Redocly/redocly-cli / packages/client-generator/eject-assets/skills/typescript-generator
typescript-generator
UnverifiedDesign of the ejected Redocly `typescript` client generator. Read it, and update it, before changing generators/typescript/.
The typescript generator — its skill
This file is the DESIGN of your ejected typescript generator (generators/typescript/):
to change the generator, edit this skill first, then make the code match it — a diff
to generators/typescript/ that has no covering sentence here is incomplete.
What it emits
The typed TypeScript client itself: model types with JSDoc, type guards, the Ops
type map, the OPERATIONS descriptor table, a client instance, one binding per
operation, and the runtime — embedded in the file (runtime: inline, the default) or
written as real modules in a runtime/ folder beside it that the client imports
relatively (runtime: module).
With client.telemetry: on, it also writes <stem>.telemetry.ts: the usage telemetry
middleware. The module exports telemetry() and flush(), and the application registers
it with use(telemetry({ sdkName, sdkVersion, client })).
Design decisions that must hold
- Descriptor-driven: generated code is DATA (
OPERATIONS+Ops) plus wiring; request behavior lives in the runtime, never in per-operation code.satisfies Record<string, OperationDescriptor>is the version-skew guard. singlevssplit: split derives<stem>.schemas.ts(types, enums, guards) and an entry thatexport *s it; the entry type-imports only the schema names it references (collectEntrySchemaRefs).- Zero runtime dependencies.
Date,Blob,fetch— nothing else. - It type-checks under the strictest common settings. The output compiles as part of
the user's sources, so
skipLibCheckdoes not cover it:strict,noUncheckedIndexedAccess, andexactOptionalPropertyTypesmust all pass. Guard an index access explicitly instead of asserting it, and leave an absent optional key out (a conditional spread) instead of setting it toundefined. - Timeouts need no platform statics.
send()usesAbortSignal.timeout()andAbortSignal.any()where they exist and builds the same signal from anAbortControllerandsetTimeoutwhere they do not (Chrome before 116, Safari before 17.4, Firefox before 124). A timed-out attempt is recognized by its own timeout signal having fired, never by the abort reason's name, because Chrome 103 to 123 abort a timeout withAbortError. - Names are collision-safe:
packageIdentsseeds every reserved wiring name before any operation is sanitized, so renames are deterministic (configure→configure_2). A rename becomes part of the SDK's public API, so the warning must say WHICH cause it is and what the publisher can do: a duplicateoperationIdin the description (fix the description — the only real fix), a name that isn't a valid identifier, or a clash with a name the generated module already declares. A vague "collides or is invalid" message leaves the publisher unable to act. - One operation, one function, one input shape. The module-level names are bindings
of the client's own methods (
export const { getOrder } = client;), never wrappers, sogetOrderandclient.getOrdercannot disagree about their arguments.argsStyleshapes the method itself:grouped(the default) namespaces the inputs by transport layer —path,query,headers,cookies,body— andflatmerges them into one object, which the runtime converts back using the descriptor's own parameter list. An operation whose merged names would collide keeps the grouped shape. - Stream bodies pass through. A request body that is a
ReadableStream, or any async iterable of bytes (a NodeReadable), is a pass-through upload:send()hands it tofetchuntouched withduplex: 'half'and makes exactly one attempt, because a consumed stream cannot be replayed, whatever the retry policy says. The whole-attempttimeoutstill applies; callers passtimeout: 0or a budget that fits the upload per call. The body type of an untypedmultipart/form-dataoperation isFormData | ReadableStream, and of a binary operation (isBinaryContentType:application/octet-stream,application/pdf, images, audio, video, fonts, zip)Blob | ArrayBuffer | ReadableStream. The client stays free of Node types: a Node request becomes a web stream withReadable.toWeb(request). Typed multipart objects are unaffected. - The caller's
Content-Typewins; the description's fills the gap. For a pass-through body other thanFormDataorURLSearchParams(whose typefetchderives, boundary included),send()sets the operation's declared content type only when the caller set none, the same rule the JSON branch already follows. A forwarded multipart boundary therefore survives, and a binary upload is never sent untyped. onSettledsees every sent call once.send()calls it after the last attempt with the final response, the error, or both, the attempt count, and the duration from the first attempt to the end of theonResponsehooks on the final response. A call that fails inonRequestor in body serialization does not reach it. A call whose signal is already aborted reaches it with 0 attempts. Every hook runs. The first hook error rejects a successful call; on a failed call, the original error wins.- Telemetry is opt-in at generation time. Without
telemetry: on, the output holds no telemetry code, and the client file does not change. An event holds only the operation id, the counts, the window, and the SDK identity. The kill switches and a browser turn the middleware off. The module embeds on its own, not inRUNTIME_SOURCES, sotelemetryandflushnever become reserved names of a client. - Throw mode returns the body;
{ envelope: true }opts into{ data, headers, response }with typed declared headers. Result mode returns{ data, error, response }and ignoresenvelope.
The stage files
One file per stage of the emit, same skeleton as the other generators:
types.ts renders type text (tsType, JSDoc, the model type aliases);
operations.ts the per-operation surface (the Ops map, the <Op>* aliases, the
input shapes, flatInputShape);
descriptor.ts the OPERATIONS wire table and the collision-safe packageIdents;
client.ts the assembly (single/split entries, the runtime needs, the module-mode
runtime files);
type-guards.ts, response-headers.ts, operation-types.ts, operation-signature.ts
the narrower questions their names state;
banner.ts the generated-by header and title comment;
inline-runtime.ts the runtime assembly for both modes. The runtime's real sources ship
inside the package and reach the generator through
@redocly/client-generator/runtime-sources (in this repo they live in runtime/ beside
these files). Naming and string escaping live in the TypeScript printer
(@redocly/client-generator/printers/typescript).
The telemetry middleware ships the same way, as TELEMETRY_RUNTIME_SOURCE (in this repo
it lives in telemetry/); index.ts writes it with the contract import pointed at the
client entry and the generator version baked in. The prepare script replaces its type import
from @redocly/cli-otel with the declarations of the event type (ADR 0024).
Ejecting it
redocly eject-generator typescript copies this generator's TypeScript source folder to
generators/typescript/ — the stage files above, exactly as we wrote them. Imports stay
package specifiers: @redocly/client-generator (the toolkit and IR types),
@redocly/client-generator/printers/typescript (naming and text mechanics), and
@redocly/client-generator/runtime-sources (the runtime sources it embeds). Running a
.ts generator uses Node's own type stripping (Node 22.18, 23.6, or newer), and newer
built-in versions merge into your copy per file with
redocly eject-generator typescript --update.
It is the largest of them, so reach for the smaller paths first when they fit:
client.setup bakes publisher defaults into the generated client, and middleware or
configure() change behavior at run time rather than generation time.
- It documents itself. With
client.docs(or--docs), thedocshook writes<stem>.typescript.md: the security schemes, then one section per operation with its parameters, body, response type, and behavior notes. The call snippets come from this generator's ownsamplehook, so the page can only show the syntax of the SDK beside it, and the layout comes fromrenderReferencePagein the authoring toolkit — reachable from an ejected copy through@redocly/client-generator. Pagination on the page is decided bypaginationRuleFor, the same helper this generator resolves pagination with.
The modify loop
- Edit this skill: state the new behavior or decision.
- Make
generators/typescript/match it. - Run
redocly generate-clientand inspect thegit diffof the generated output — generated files are never hand-edited.
Newer built-in versions merge in with redocly eject-generator typescript --update.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |