feat!: generate TypeScript from string templates and drop the TypeScript dependency

[im10furry]

Changes

Closes #2841. Supersedes #2867. Related: #2862, #2818.

TypeScript 7 (the native compiler) is latest on npm and its root module ships no classic
compiler API. openapi-typescript built its output with ts.factory / createPrinter /
createSourceFile, so a TS7 application hits two hard blockers:

1. npm i typescript@7 openapi-typescript fails outright:

   npm error ERESOLVE unable to resolve dependency tree
   npm error peer typescript@"^5.x" from openapi-typescript@7.13.0
   

2. Forcing past it (--legacy-peer-deps) crashes on first import:

   TypeError: Cannot read properties of undefined (reading 'createKeywordTypeNode')
   

This PR does what @mrlubos asked for in #2841 — "remove the entire TypeScript dependency and switch
to raw string templates" — so TypeScript is no longer a dependency at all.

• src/lib/ts.ts rewritten as a string builder. The helper surface keeps its shape (tsUnion,
  tsLiteral, oapiRef, tsEnum, …) but now returns source text, plus new line-oriented builders
  (typeLiteral, tupleType, propertySignature, indexSignature, typeAlias, interfaceDecl,
  enumDecl) and tsComment() for JSDoc.
• All 13 transforms, lib/utils.ts and transform/index.ts migrated. Multi-line constructs thread
  an explicit indentation level, reproducing the printer's 4-space nesting exactly.
• The printer's quirks are reproduced deliberately, each verified against the real printer:
  trailing whitespace stripped on every comment line; nested unions/intersections parenthesised
  (including inside array types and after readonly); tuples always multi-line while {} is inline;
  string literals escaped the way createStringLiteral does ("emoji🎉" → "emoji\uD83C\uDF89",
  while the tsLiteral UTF-8 workaround stays verbatim); and the $defs / template-literal /
  operations assembly keeps its exact shape.
• openapiTS() resolves to a string — the complete file body, ending in a newline.
  astToString() is retained as a normalizer for older call sites.
• peerDependencies.typescript removed; typescript stays a devDependency for the repo's own
  tsc. The built dist/ contains zero references to typescript.

Breaking changes (major)

Before	After
openapiTS(): Promise<ts.Node[]>	openapiTS(): Promise<string>
transform → ts.TypeNode | TransformObject	transform → string | { schema: string; questionToken: boolean }
postTransform(type: ts.TypeNode)	postTransform(type: string)
transformProperty(property: ts.PropertySignature)	transformProperty(property: { name; optional; type; comment?; indent })
GlobalContext.injectFooter: ts.Node[]	GlobalContext.injectFooter: FooterDeclaration[]
stringToAST(), tsModifiers(), QUESTION_TOKEN	removed; see the new builders above

Migration for AST callbacks is mechanical: ts.factory.createTypeReferenceNode("Date") → "Date".
Attach JSDoc from transformProperty with tsComment(tags, property.indent).

The inject option is now emitted verbatim rather than re-printed by the printer.

Two bugs fixed along the way

Both produced invalid TypeScript; both are covered by new tests.

• A multi-line x-enum-descriptions entry leaked a bare token into the enum body
  (// line1\nline2 → now // line1 line2).
• With pathParamsAsTypes, a URL containing a backtick broke out of the generated template literal
  type (`/a`b/${string}` → now `/a\`b/${string}`).

One deliberate, semantically-neutral output change: tsUnion()/tsIntersection() no longer emit a
redundant single-member union, so (string)[][] becomes string[][].

How to Review

• The core is packages/openapi-typescript/src/lib/ts.ts. Everything else is a mechanical port
  against it; transform/schema-object.ts is the largest consumer.
• Ignore the diff noise in the transform files — most of it is ts.factory.createX(...) becoming
  a string builder call plus an indent argument. The interesting parts are $defs, the array /
  arrayLength branches, and the operations assembly.
• transform/index.ts keeps a typeLiteralMembers() helper that mirrors the old .members?.length
  check on the generated AST node, which is how the root paths/webhooks/components/$defs
  interface-vs-fallback decision still works.
• The rewrite is one atomic commit on purpose: swapping the node type to string ripples through
  every transform, so the repo cannot be green in between. The byte-exact snapshot suite is what
  makes that safe.

Verification

Output parity. Every committed example snapshot diffs clean, including the 123,077-line GitHub
API outputs:

github-api                          diff=0      octokit-ghes-3.6-diff-to-api   diff=0
github-api-immutable                diff=0      stripe-api                     diff=0
github-api-export-type-immutable    diff=0      digital-ocean-api              diff=0
github-api-root-types               diff=0      github-api-next                diff=0
                                                enum-root-types                diff=0

Beyond the committed fixtures, I ran the published 7.13.0 and this branch side by side over a
purpose-built schema (discriminators, allOf/oneOf/anyOf, patternProperties, $defs, prefixItems,
readOnly/writeOnly, x-enum-* metadata, non-ASCII in descriptions, enum values, property names and
$ref targets) across 27 option combinations — including a kitchen-sink run — and every pair is
byte-identical. pnpm run update:examples produces no diff.

Suite. pnpm test → 26 files / 297 tests pass (byte-exact toMatchFileSnapshot fixtures, inline
want assertions, CLI snapshot tests, CJS bundle, Node API). tsc --noEmit,
tsc -p tsconfig.examples.json --noEmit and biome check are clean (the 3 remaining
noTemplateCurlyInString warnings are pre-existing on untouched lines).

Compiler matrix — same schema generated, then type-checked with each compiler:

TypeScript	install	generation parity	tsc --noEmit --strict on output
5.9.3	clean	identical	PASS
6.0.3	clean	identical	PASS
7.0.2 (native)	clean, no peer conflict	identical	PASS

End-to-end under TS7, the exact scenario from #2841:

$ npm i typescript@7 openapi-typescript-<this PR>.tgz    # no flags, no ERESOLVE
$ npx openapi-typescript ./schema.yaml -o ./out.d.ts      # ✅

With no TypeScript installed at all, both the CLI and the Node API (including transform,
postTransform and transformProperty) work — typescript does not even resolve from the consumer
project.

Checklist

• Unit tests updated
• docs/ updated (if necessary)
• pnpm run update:examples run (only applicable for openapi-typescript)

Notes

• The ja/zh translations of docs/node.md still show the old AST examples and need a follow-up
  translation pass.
• No changes to openapi-typescript-helpers, openapi-fetch, or any other package.
• With no compiler dependency at all, Support TypeScript 7 applications with a package-owned compiler #2867's "compiler isolation" question becomes moot.

[netlify]

👷 Deploy request for openapi-ts pending review.

Visit the deploys page to approve it

Name	Link
🔨 Latest commit	26f4233

[changeset-bot]

🦋 Changeset detected

Latest commit: 26f4233

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
openapi-typescript	Major

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[im10furry]

Open question: the transformProperty hook shape

I posted a fuller sign-off request on #2841; this is the one API decision I'd like a maintainer's call on before this lands, because it is the only place where the string rewrite can't preserve the old shape exactly.

What changed. transformProperty used to receive a ts.PropertySignature node and return one. A plain string can't carry that structure — the hook needs to read and change the property name, whether it is optional, and its type — so it now receives and returns a small plain object:

transformProperty?: (
  property: { name: string; optional: boolean; type: string; comment?: string; indent: string },
  schemaObject: SchemaObject,
  options: TransformNodeOptions,
) => typeof property | undefined;

comment and indent exist because the old hook could attach JSDoc via ts.addSyntheticLeadingComment, and a correctly-indented block comment needs to know the property's indentation. The PR adds a public tsComment(lines, indent) helper so hooks don't have to hand-build one:

transformProperty(property, schemaObject) {
  if (schemaObject.minLength === undefined) return undefined;
  return { ...property, comment: tsComment([`@minLength ${schemaObject.minLength}`], property.indent) };
}

The alternatives I considered:

1. This PR — a structured { name, optional, type, comment?, indent } object. Keeps the old ergonomics (patch one field, return the object) and keeps indentation out of the caller's hands.
2. Raw property string — the hook gets the already-rendered name?: type; line and returns a replacement line. Maximum flexibility and the most "string templates" spirit, but callers have to parse/re-emit the line and handle indentation themselves.
3. Only change the return type — keep passing an object but let the hook return a plain string for the rendered property. A middle ground, but the asymmetry reads oddly.

I went with (1) as the closest analogue to the old API, but (2) is defensible if you'd rather keep the public surface strictly string-based. Happy to rework it — it's contained to transformProperty in src/transform/schema-object.ts, the hook's type in src/types.ts, and two test cases.

Everything else in the breaking-change list should be a mechanical migration for callers (ts.factory.createTypeReferenceNode("Date") → "Date"), and CLI users plus consumers of the generated types need no migration at all.

[im10furry]

CI note: test-e2e is stuck on an infrastructure step

Every check passes except test-e2e, which has been sitting in pnpm exec playwright install --with-deps for ~20 minutes. That step never completed, so the suite itself (pnpm run test-e2e) is still pending and hasn't run — this is not a test failure.

That job isn't exercised by this change: it runs the openapi-fetch Playwright suite, and packages/openapi-fetch/test/helpers.ts only imports openapi-typescript-helpers. The same code passes pnpm test on the macOS and Windows jobs, which do cover the packages.

It also matches the flakiness this job already has on main — it runs on node-version: latest, which is exactly what #2818 pins to Node 22 to avoid. For context, test-e2e is CANCELLED on #2862, #2867 and #2815.

I don't have permission to cancel or re-run the workflow (viewerPermission=none on this repo), so a maintainer re-run would be needed to clear it. Everything else is green, and the failure mode here is a stuck dependency download rather than anything in the diff.

[im10furry]

Follow-up: the stuck test-e2e job here is a repo-wide, pre-existing failure, and I've opened #2869 to fix it.

test-e2e has been dying in pnpm exec playwright install --with-deps at GitHub's 6-hour job limit on every run since 2026-08-24 (last green run 32722419757, 79s). #2869 moves that job into the official Playwright container so there is nothing to install, and it is green there in 57s.

Once #2869 lands, rebasing this PR on main will make test-e2e green here too — nothing in this PR's diff is involved.