Duolith docs

0109. The typed client types every part of an operation, or refuses it

  • Status: Accepted (Mik, 16 Nov 2026)
  • Date: 2026-11-15
  • Decided by: domain E fixer (internal only), after the review of PR #36
  • Amends: 0104

Context

The first generator (0104) followed any $ref inline, so a schema that referred to itself overflowed the stack and stopped every build. It also left parts out or typed them loosely without saying so: header and cookie parameters were dropped, a {name} in a path with no parameter was sent as it was, {} and not: became unknown, a form or multipart body was typed and sent as JSON, head, options and trace were skipped, and a default answer (usually the error) was taken as the success. The owner's rule is that anything statically knowable fails the build loudly.

Decision

Every part of an operation is typed as the server takes it, or the build fails with a diagnostic that says what to change.

In the descriptionBecomes
A schema under #/components/schemas/<Name>A named type; it may refer to itself (type Tree = { kids?: (Tree)[] })
Any other $ref in the fileWritten out where it is used; one that leads back to itself is E0517, with the fix "name it under #/components/schemas"
A named schema that is itself through $ref, allOf, oneOf or anyOf aloneE0517 (TypeScript cannot write type A = A)
{}, not:, an array without items, a body or answer with no schemaE0517
A schema with only additionalPropertiesAn object with an index signature
A header parameterheaders: { "X-Api-Key": string }, required when any header is; sent as text. Accept, Content-Type and Authorization are ignored, as OpenAPI says
A cookie parameterE0518: browsers drop a Cookie header a script sets, so it could never be sent
A required query memberquery is required too
A {name} in the path no parameter declares, or a path parameter the path lacksE0518
A body with no JSON media type (form, multipart, other)E0518; JSON is chosen when the body offers it beside others
AnswersThe union of every 2xx answer (JSON schema, string for text/*, undefined for none); no 2xx answer, including default alone, is E0518
head, optionsTyped and callable (server.head(...), server.options(...)); head answers void
traceE0518: browsers refuse to send it

At run time typedApi refuses a path parameter that is missing, empty, . or .. (each would change which path is called; servers normalise %2e%2e too), instead of sending it.

Alternatives considered

OptionWhy not
Type a self-referring inline $ref by naming it after its pointerA name the description never gives; moving it under components/schemas is one line and gives it a real name
Send form and multipart bodiesThe generated file holds only types, so the runtime cannot know a path's encoding without shipping a table per operation; fetch with FormData is already the way to send them
Send cookies by writing document.cookieWrites a lasting cookie for the whole site as a side effect of one call, and does nothing across origins
Skip trace with a warningEvery other part fails loudly; a warning would be the one silent exception

Consequences

A description that used to build may now fail with E0517 or E0518; each message names the part and the fix. The data example's description needed no change.