API Design for Libraries (Fluent APIs, Diagnostics, Source Maps)
Designing a chainable fluent API that defers work to a clear terminal call, actionable diagnostics, and source maps that keep debugging transformed code usable.
Purpose
Beyond correctness, a library’s API design determines whether it’s pleasant and safe to use. Three concerns come up repeatedly for a library or tool: chainable (fluent) call design, actionable error reporting, and — for anything that transforms code — keeping the debugging experience intact.
Fluent APIs
const results = await query('users').where('age', '>=', 18).orderBy('name').limit(10).execute();Each chained call before .execute() should only accumulate a description of the eventual
operation, not perform real work immediately — this keeps the chain composable and lets a single
terminal call (.execute()) act on the complete picture, rather than reacting to each clause as it
arrives.
Diagnostics
A diagnostic bundles more than a message: a severity (error/warning/hint), a precise source location, a stable error code (for lookup, suppression, and documentation), and ideally a suggested fix — the same discipline as a good runtime validation error, scaled for a tool whose primary output is its diagnostics.
Error [E042]: Invalid configuration at "server.port" (config.json:4:10):
expected a number between 1 and 65535, received the string "abc".Source maps
A source map maps positions in generated/transformed code back to the original source — what lets a debugger show original source, variable names, and stack traces even though different code is actually running.
Behavior notes
- A fluent API whose intermediate calls have real side effects surprises callers who expect only the terminal call to “do” anything.
- A diagnostic’s error code should remain stable across versions — consumers may match on it programmatically (to suppress a specific warning, for instance), and changing it silently breaks that.
- Shipping a build without source maps (or without publishing them) makes debugging transformed production code significantly harder — a deliberate trade sometimes made for source privacy, but a trade that should be conscious, not accidental.
Common mistakes
- Performing real work in an intermediate chained call, breaking the fluent API’s composability.
- Shipping a vague, generic error message (“Invalid configuration”) when a specific location and expected-vs-actual comparison were available to include.
Runtime notes
API design principles, not language features — applicable to any library or tool regardless of the runtime it targets.