Support TypeScript 6 and 7 without a runtime compiler dependency

[darkbasic]

Changes

Support TypeScript 5, 6, and 7 consumers, including generation without TypeScript installed, by combining the TS6 work from #2774 with the compiler-free generator from #2868. This PR carries over the additional fixes developed in the darkbasic fork and adds regression and installed-package coverage around both changes. The generator's Node API changes require a major release; the helpers package receives a separate patch release.

Addresses #2841 and the compatibility discussion in #2831.

This is a focused extraction against main. It excludes the fork's separate required-only allOf feature, pnpm upgrade, and dependency/security updates. Existing ordinary allOf behavior and all nine generated example snapshots are preserved. The only dependency changes serve compiler compatibility or the published declarations.

Relationship to the existing PRs

Prior PR	What it already provides	What this PR adds
#2774, reviewed at 6a805ba5	TS5/TS6 peer compatibility, callable preservation in the helpers package, and the Headers.forEach workaround.	Consistent package and generated read/write helpers; broader readonly collection, generic, and recursion fixes; semantic regression tests; workspace-wide TS6 configuration and TS5/TS6 CI. The compiler peer is ultimately removed by the string-emitter change.
#2868, reviewed at 26f4233d	A compiler-free string emitter, TypeScript peer removal, string-based Node APIs, a structured property hook, deferred operations, and initial output fixes.	The enhanced TS6 helpers, further array/precedence/escaping/root-output fixes, property-hook readonly control, stricter migration behavior, declaration packaging fixes, installed-consumer coverage, and completed migration documentation.
#2867	An alternative approach that retains AST generation, ships a package-owned classic TypeScript compiler, and exports ts for callbacks. It also contains CJS declaration and installed-consumer fixes.	This PR follows #2868's compiler-free architecture. Its strict consumer checks include the generated helper semantics and all three compiler majors, and the published package supplies the declaration dependencies its consumers need.

#2868 already makes the generator usable with TS6 as well as TS7 by removing its compiler API dependency. The separate TS6 work addresses helper semantics, workspace configuration, and regression coverage. This PR includes both sets of changes; it does not require merging #2774 separately.

Credit for the original approaches belongs to the authors of #2774 and #2868. The CJS and consumer-test improvements below are additions beyond #2868, rather than claims of originality across every proposal.

Further work beyond #2774

The original fork comparison is recorded in this comment on #2774. The relevant additions included here are:

• Apply fixes to generated helpers too. --read-write-markers emits the same corrected Readable<T> and Writable<T> behavior as openapi-typescript-helpers, under both mutable and immutable generation.
• Preserve built-in methods without bypassing data filtering. Date and RegExp keep their callable methods while visibility markers on their additional data properties are resolved. Callable arguments, results, and attached properties remain opaque. The mapped-type bug also existed under TS5; it was not caused by a TS6 change to whether Date extends object.
• Resolve readonly collections consistently. Array methods and iteration expose resolved elements, while readonly indices, length, required numeric properties, and additional data modifiers are preserved. Excluded readonly elements use the existing mutable-array never rule.
• Cover generics and recursion without adding a new tuple model. Constrained generic objects and arrays, recursive arrays/tuples, and array interfaces are exercised. Existing mutable-tuple behavior is retained; this does not introduce full readonly tuple-bound reconstruction or depth-limit machinery.
• Avoid a new generated-name collision. The generated readonly-data mapping is inline, so a root type named ReadonlyArrayData remains usable. The package keeps its private alias, and the any fast path remains available for compiler efficiency.
• Check semantics, including invalid uses. Compile-time assertions cover the package and actual generated output. Negative checks reject accidental widening to any, lost visibility filtering, incorrect method signatures, or mutable access to readonly positions. Test sources are excluded from published packages.
• Use TS6 throughout the workspace. The shared catalog selects TS6.0.3. Deprecated compiler options are removed, the nonstrict test's rootDir is corrected, and CI checks TS5/TS6 on Node 22/24 with framework examples. Peer exceptions apply only to the specific existing build-tool and SvelteKit versions tested with TS6.

Further work beyond #2868

The string emitter and removal of the compiler dependency come from #2868. The additional work addresses the behavior around that rewrite:

• Preserve array dimensions and type precedence. An items schema always describes an element, even when it emits an array, tuple, literal, or composed type. The outer array is no longer inferred from the rendered text. Nested immutable arrays produce readonly (readonly number[])[]; arrays of union items retain their outer dimension regardless of union order. Rest elements and hook-returned type expressions use the same precedence handling.
• Handle type source containing strings and comments. Composition helpers account for quoted strings, template literals, and comments, including all JavaScript line-comment terminators, when deciding where parentheses are required.
• Complete path escaping. Template literal paths handle backslashes and interpolation markers as well as backticks, including unusual parameter names. feat!: generate TypeScript from string templates and drop the TypeScript dependency #2868's initial backtick escaping is retained.
• Deduplicate actual declarations. Footer helpers are matched by their complete canonical declaration. An enum value or comment containing WithRequired, for example, cannot suppress the real helper.
• Expose property mutability to hooks. transformProperty receives and can override readonly for ordinary properties and $defs, alongside the existing name, optionality, type, and comment fields.
• Recognize custom root output reliably. Root detection accepts surrounding comments and inline formatting. With postTransform configured, nonempty object-shaped $defs use aliases so mapped types remain valid. Empty-root fallback behavior is retained.
• Make obsolete API calls fail explicitly. astToString() normalizes source strings and rejects old AST inputs or printer options, instead of silently ignoring incompatible options.
• Match installed CommonJS behavior. Generated CJS declarations describe the actual object containing default and named exports. The build disables the existing unbuild transform that otherwise rewrites this shape incorrectly.
• Publish required declaration dependencies. @types/js-yaml moves from development to runtime dependencies, and json-schema-to-ts is added. Redocly's exposed declarations refer to these packages; strict consumers should not need to discover and install them separately.
• Exercise the published packages. Isolated npm consumers test CLI, ESM, CommonJS, all three hooks, public API types, generated declarations, and the full helper assertion suite under TS5.9.3, TS6.0.3, and TS7.0.2. A separate case verifies generation with no TypeScript installed. Both Node 22 and 24 are covered, with strict: true and skipLibCheck: false for compiler cases.
• Document the complete migration. English, Japanese, and Chinese Node API documentation, package guidance, and contribution instructions describe source-based generation and callback changes.

The single-member union simplification and multiline enum-description fix are inherited from #2868.

Breaking Node API changes

• openapiTS() returns Promise<string> instead of Promise<ts.Node[]>. The returned body ends with a newline and does not include COMMENT_HEADER.
• transform returns type source text, or { schema: string, questionToken: boolean }. postTransform receives and returns type source text.
• transformProperty uses { name, optional, readonly, type, comment?, indent }. Use tsComment() when constructing JSDoc from this hook.
• Footer declarations are strings or deferred operations. AST-only utilities are replaced by source-building helpers.
• inject is emitted verbatim.
• astToString() accepts a source string or an array of source strings, joins the fragments, and ensures a trailing newline. AST nodes and printer options are unsupported.
• Configuring postTransform changes nonempty object-shaped $defs roots to type aliases, allowing custom mapped types.

For a simple callback, returning ts.factory.createTypeReferenceNode("Date") becomes returning "Date". Callbacks that inspect or rewrite arbitrary ASTs require a source-based rewrite. The CLI's basic invocation stays the same.

How to Review

Start with packages/openapi-typescript/src/types.ts and docs/node.md for the public API, then review the source builders in src/lib/ts.ts and their transformer call sites. The additional behavior beyond #2868 is concentrated in array handling, property mutability, root output, path escaping, and footer helper membership.

Review packages/openapi-typescript-helpers/src/index.ts together with the generated helper templates in packages/openapi-typescript/src/transform/index.ts. The package assertions and test/read-write-helpers.test.ts verify that both forms preserve the same semantics.

For packaging and compatibility, review build.config.ts, the generator's package.json, scripts/test-consumer.mjs, its fixtures, and .github/workflows/ci.yml. The repository retains main's pnpm 10.30.3, existing dependency versions apart from the changes described above, and existing browser CI configuration.

Validation on this branch

These results were rerun on the focused extraction using main's dependency graph:

Check	Coverage	Result
Workspace tests and builds	TS5.9.3 / TS6.0.3 × Node 22.23.2 / 24.19.0	841 tests pass in each combination: 353 generator, 451 fetch, 37 react-query. All eight Turbo tasks run uncached, including helper assertions, example compilation, and package export checks.
Package and nonstrict typechecks	The same four compiler/Node combinations	Pass.
Packed npm consumers	TS5.9.3 / TS6.0.3 / TS7.0.2 / no compiler × Node 22.23.2 / 24.19.0	All eight combinations pass. Compiler cases use strict checking with skipLibCheck: false.
Framework examples	Vue, Svelte, and Next under TS5 and TS6 on Node 24	Pass.
Static lint and documentation	Repository JavaScript/TypeScript lint; VitePress build	Pass.
Generated examples	Nine CLI outputs using cached schemas, including all GitHub flag variants	Byte-for-byte identical to main. Generated examples compile with TS6 under the existing example configuration, retaining its DigitalOcean exclusion.
Installation and release metadata	Frozen pnpm install; Changesets release plan	Pass: major generator release and patch helpers release.
Independent review	Correctness, maintainability, minimality, and repository conventions	No outstanding blockers. An independent 1,620-case allOf comparison found no type or callback-trace differences from main.

TS7 coverage applies to installed consumers, the public API declarations, and generated types. Workspace build/test tooling remains on the classic TS5/TS6 compiler. Browser, macOS, and Windows tests were not rerun locally; their CI jobs remain in place. Live schema downloads were not refreshed; cached-schema generation verified that no example snapshot changes are needed.

Useful checks after installing dependencies:

pnpm test --force
pnpm --recursive run --if-present lint:js
pnpm --recursive --filter '!openapi-typescript-helpers' run --if-present lint:ts
pnpm --recursive run --if-present lint:ts-no-strict
pnpm --filter openapi-typescript --filter openapi-typescript-helpers build
for version in 5.9.3 6.0.3 7.0.2 none; do
  pnpm --filter openapi-typescript test:consumer -- "$version"
done

The workflow performs the workspace TS5 check by changing the shared catalog to ^5.9.3 before installing in that job. Local TS5 validation used a separate workspace copy with its own dependency installation.

Checklist

• Unit and semantic regression tests updated.
• docs/ updated, including English, Japanese, and Chinese migration guidance.
• Generated examples verified against cached schemas; all nine match main. The live-refresh pnpm run update:examples command was not run.
• Separate generator-major and helpers-patch changesets included.
• TS5/TS6 workspace checks and TS5/TS6/TS7/compiler-free consumer checks pass.

[changeset-bot]

🦋 Changeset detected

Latest commit: a8e1738

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

This PR includes changesets to release 2 packages

Name	Type
openapi-typescript	Major
openapi-typescript-helpers	Patch

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

[netlify]

👷 Deploy request for openapi-ts pending review.

Visit the deploys page to approve it

Name	Link
🔨 Latest commit	a8e1738