Skip to content

envelope.md

Latest commit

 

History

History
55 lines (36 loc) · 3.01 KB

envelope.md

File metadata and controls

55 lines (36 loc) · 3.01 KB
Raw

Envelope modes

The generator inspects each operation’s success JSON schema and classifies the spec into one of three envelope modes. You do not set the mode in source.ts; it is inferred.

An object “looks like an envelope” when it has a data field, or when it has a success field and every other field is envelope metadata (error, message, requestId, or timestamp). A business payload such as { success, deletedCount, requested } remains raw.

shared

Every success response shares the same envelope object (for example { success, data, timestamp }).

  • Writes generated/base.ts with BaseResponse<T>.
  • Per-operation response types unwrap data: export type GETApiAcmeV3WidgetsResponse = BaseResponse<Widget[]>.
  • Operation-specific fields beside data are intersected back into the response, preserving their exact schemas instead of widening them to the shared base field type.
  • If apiRoot/models.ts already exports BaseResponse<T> and its fields differ from the spec, generate fails until you either update models.ts or run accept-base.

Synthetic fixture: test/fixtures/specs/envelope-list.json (/api/acme/v3/widgets).

raw

Success bodies are not a shared envelope. Types are emitted as the spec schema, with no BaseResponse wrapper. Typical of cursor-style list payloads.

Synthetic fixture: test/fixtures/specs/raw-cursor-list.json (/api/orbit/v1).

mixed

Some operations return an envelope with data; others return a plain object. Mixed mode:

  1. Writes generated/base.ts from the largest envelope group that includes data.
  2. Operations matching that primary envelope use BaseResponse<Unwrapped>.
  3. Other operations keep their exact raw schema, including differently shaped objects that also contain data.

Example from test/fixtures/specs/mixed-envelope.json:

Operation Success body Generated response
GET /api/acme/v3/widgets { success, data, timestamp } BaseResponse<string[]>
GET /api/acme/v3/plain/{token} { token, caption } { token: string; caption?: string }

Callers still return the HTTPFetch { data } payload (the transport wrapper), not a TypeScript as cast. Envelope unwrap is a type concern: TResponse is BaseResponse<T> or the raw body, depending on the operation.

HTTP clients that unwrap envelopes

Set unwrapResponseData: true only when the injected HTTPFetch already normalizes { success, data } bodies. Recognized envelopes emit the inner data payload type, or null when data is absent. Business payloads containing success plus domain fields and data-only cursor objects remain raw. Envelope objects composed through component references and allOf are recognized without changing their source schemas.

accept-base

typeforge accept-base --source atlas regenerates generated/base.ts and rewrites BaseResponse in models.ts to match the spec. Use it when the envelope shape in the spec is the source of truth and models.ts is stale. Do not combine with --check.