feat(typescript): add toggles to disable generated request/response/error/client options

[SM-OliLegg]

Ref: #3850

Hi! I want to make @hey-api/typescript output more configurable for teams that prefer minimal generated artifacts. This PR adds controls to reduce generated TypeScript artifacts when needed.

What’s added

• @hey-api/typescript plugin toggles:
  • requests: false
  • responses: false
  • errors: false
  • clientOptions: false

Why

Some teams only want core schema/definition types. These changes make that output mode configurable.

Included in this PR

• parser read/write transform updates (readWrite, plus per-variant requests / responses controls)
• @hey-api/typescript plugin toggles for requests, responses, errors, and clientOptions
• docs updates for parser and TypeScript plugin configuration
• a regression test covering the minimal-output configuration end-to-end

plugins: [
  {
    name: "@hey-api/typescript",
    requests: false,
    responses: false,
    errors: false,
    clientOptions: false,
  },
],

[bolt-new-by-stackblitz]

Run & review this pull request in StackBlitz Codeflow.

[pullfrog]

Reviewed PR #3837. Submitted review identifying a critical dangling $ref bug in readWrite.ts when only one variant is enabled (the original schema is deleted but refs for the disabled variant's context are never rewritten). Also flagged the misleading definite assignment assertions, duplicated config logic, and a formatting nit. A follow-up push added docs, tests, and a changelog entry — the test covers the "all disabled" case but not the asymmetric case that triggers the bug.

Task list (5/5 completed)

• Read PR description and diff TOC
• Read and analyze each changed file in the diff
• Investigate impact of changes (grep for stale references, breaking changes)
• Draft review comments and self-critique
• Submit review

  ^{｜ View workflow run ｜ via Pullfrog ｜ 𝕏}

[vercel]

@SM-OliLegg is attempting to deploy a commit to the Hey API Team on Vercel.

A member of the Team first needs to authorize it.

[changeset-bot]

🦋 Changeset detected

Latest commit: 4522ef8

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

This PR includes changesets to release 1 package

Name	Type
@hey-api/openapi-ts	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

[pullfrog]

TL;DR — Adds granular feature toggles for disabling individual code-generation artifacts. The @hey-api/typescript plugin gains requests, responses, errors, and clientOptions boolean flags, and the parser's readWrite transform can now disable request/response schema-split variants independently.

Key changes

• Add enabled toggle to @hey-api/typescript operation artifacts — requests, responses, and errors now accept false (or { enabled: false }) to suppress generation of their corresponding type aliases; a new top-level clientOptions boolean controls ClientOptions emission.
• Allow independent disable of readWrite schema-split variants — parser.transforms.readWrite.requests and parser.transforms.readWrite.responses each accept false to skip generating the writable or readable schema variant.
• Refactor splitSchemas to conditionally produce variants — The read/write split loop now checks per-variant enabled flags before cloning, pruning, and registering schemas, avoiding unnecessary work when a variant is disabled.
• Add integration test and documentation — A new createClient test verifies that all artifacts are suppressed when every toggle is false; docs for the parser and TypeScript plugin are updated with usage examples.

_{Summary ｜ 12 files ｜ 2 commits ｜ base: main ← feature/disable-parser-features}

Feature toggles for TypeScript operation aliases

Before: requests, responses, and errors only accepted naming configuration (string, function, or object with name/case). All operation aliases were always emitted.
After: Each option also accepts boolean (or { enabled: boolean }) to suppress the corresponding type aliases entirely. A new clientOptions: boolean flag controls ClientOptions generation.

When set to false, the plugin skips both symbol registration and node emission for the disabled artifact category. The valueToObject mapper pipeline handles the boolean → { enabled } coercion so existing string/function/object configs remain unaffected.

types.ts · config.ts · operation.ts · plugin.ts

Independent disable of readWrite schema-split variants

Before: parser.transforms.readWrite could be disabled entirely (false) or configured as a unit — both read and write variants were always produced together.
After: readWrite.requests and readWrite.responses each accept false to independently skip generating the writable ({{name}}Writable) or readable variant.

The splitSchemas function now reads per-variant enabled flags and conditionally runs deepClone + pruneSchemaByScope only for enabled variants. The early-exit equality check (deepEqual(readSchema, writeSchema)) is gated behind both variants being enabled, since the comparison is meaningless when one side is absent.

readWrite.ts · parser/types.ts · parser/config.ts

Test and documentation coverage

Before: No test coverage for disabling individual artifacts.
After: A new integration test exercises createClient with all toggles set to false and asserts that none of the suppressed type aliases or Writable variants appear in the output.

Docs for both the parser configuration and the TypeScript plugin are updated with code examples showing how to disable individual features.

index.test.ts · parser.md · typescript.md

  ^{｜ View workflow run ｜ via Pullfrog ｜ 𝕏}

[pullfrog]

TL;DR — Adds granular toggles to the @hey-api/typescript plugin so consumers can disable generation of requests, responses, errors, and ClientOptions type aliases individually, reducing output size for projects that don't need every artifact.

Key changes

• Add enabled toggle to requests, responses, and errors config — Each option now accepts boolean | NameTransformer | object (with an enabled field on the object form); passing false suppresses that artifact entirely.
• Add clientOptions boolean to the TypeScript plugin — Controls whether the ClientOptions type alias is emitted; defaults to true.
• Gate operationToType and createClientOptions behind their toggles — operation.ts checks plugin.config.requests.enabled, plugin.config.errors.enabled, and plugin.config.responses.enabled before processing; plugin.ts wraps createClientOptions in a plugin.config.clientOptions guard.
• Wire up boolean mapper in config normalization — config.ts adds a boolean mapper to valueToObject for each option so false resolves to { enabled: false } while preserving naming defaults.
• Extend UserConfig types with boolean union arms and FeatureToggle — types.ts adds | boolean to the UserConfig unions for requests, responses, and errors, and intersects the resolved Config types with FeatureToggle (imported from @hey-api/shared).
• Add integration test for disabled artifacts — A new test in index.test.ts constructs a minimal OpenAPI 3.1 spec and asserts that disabling all toggles together with parser.transforms.readWrite: false produces output without the suppressed type aliases or Writable variants.
• Add documentation and changeset — Docs for the TypeScript plugin include a usage example combining parser.transforms.readWrite: false with the new plugin toggles, plus brief notes under the Requests, Responses, and a new Errors section; changeset marks @hey-api/openapi-ts as patch.

_{Summary ｜ 8 files ｜ 11 commits ｜ base: main ← feature/disable-parser-features}

Toggle TypeScript operation artifact generation

Before: requests, responses, and errors accepted only naming config (string, function, or object with name/case); ClientOptions was always emitted.
After: Each option additionally accepts false (or { enabled: false }) to suppress that artifact entirely. A new clientOptions: boolean config controls ClientOptions generation.

The plugin's operationToType function now checks plugin.config.requests.enabled, plugin.config.errors.enabled, and plugin.config.responses.enabled before processing each category. The handlerV1 entry point gates createClientOptions behind plugin.config.clientOptions. Config normalization in config.ts adds boolean mappers so false resolves to { enabled: false }, keeping naming defaults intact for re-enabling later.

How does the boolean mapper work?

When the user passes requests: false, the existing valueToObject utility routes through the new boolean mapper, which converts it to { enabled: false }. The rest of the config fields (name, case) retain their defaults, so re-enabling later requires no additional config.

types.ts · config.ts · operation.ts · plugin.ts

Test and documentation coverage

Before: No test or doc coverage for disabling individual TypeScript artifacts.
After: An integration test exercises all toggles simultaneously; docs include a combined usage example.

The integration test creates a minimal OpenAPI 3.1 spec with readOnly/writeOnly properties, disables all toggles (including parser.transforms.readWrite: false), and asserts the output contains none of the suppressed type aliases. The documentation section in typescript.md shows how to combine parser.transforms.readWrite: false with the new plugin-level toggles, and adds brief notes under the existing Requests, Responses, and a new Errors section explaining how to disable each.

index.test.ts · typescript.md

  ^{｜ View workflow run ｜ via Pullfrog ｜ 𝕏}

[pullfrog]

Caution

Dangling $refs when only one readWrite variant is enabled — the original schema is removed but refs in the disabled variant's context are never rewritten, leaving broken pointers.

Summary: This PR adds the ability to independently disable readWrite split variants (requests/responses) in the parser config and disable TypeScript operation artifacts (requests, responses, errors, clientOptions). The TypeScript plugin changes are clean, but the splitSchemas changes in readWrite.ts introduce a correctness bug in the asymmetric case. Several housekeeping items are also missing.

Missing items:

• No PR description explaining the motivation or usage
• No tests (the diff against main shows test additions but they are not present in the actual commit)
• No documentation changes (same — appear in GitHub diff but are not in the commit)
• No changeset file (this repo uses changesets for releases, not manual CHANGELOG.md entries)
• pnpm-lock.yaml has large changes (720 additions / 835 deletions) that seem unrelated to this feature — likely caused by running a different pnpm version or re-resolving the lockfile

Task list (5/5 completed)

• Read PR description and diff TOC
• Read and analyze each changed file in the diff
• Investigate impact of changes (grep for stale references, breaking changes)
• Draft review comments and self-critique
• Submit review

  ^{｜ Fix all ➔ ｜ Fix 👍s ➔ ｜ View workflow run ｜ 𝕏}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 37.78%. Comparing base (0c865e1) to head (4522ef8).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #3837      +/-   ##
==========================================
+ Coverage   37.70%   37.78%   +0.07%     
==========================================
  Files         582      582              
  Lines       20844    20849       +5     
  Branches     6063     6072       +9     
==========================================
+ Hits         7860     7877      +17     
+ Misses      10570    10560      -10     
+ Partials     2414     2412       -2     

Flag	Coverage Δ
unittests	37.78% <100.00%> (+0.07%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[pullfrog]

Reviewed commit 0883c55 ("Fixing comments") and replied to all 4 review threads. The commit addressed 3 of the 4 items (resolveEnabled helper, ! assertion fix, dangling $ref fix via resolveVariantRefWithFallback). The types.ts formatting nit was dismissed as likely enforced by oxfmt. All threads resolved.

Task list (5/5 completed)

• Review commit 0883c55 against each review thread
• Reply to types.ts formatting thread (not addressed in commit)
• Reply to config.ts resolveEnabled thread (addressed)
• Reply to readWrite.ts dangling refs thread (addressed)
• Report progress

  ^{｜ View workflow run ｜ via Pullfrog ｜ 𝕏}

[pullfrog]

Reviewed commit 0883c55 addressing all 4 review comments. Three threads resolved: resolveEnabled helper extraction, definite assignment fix, and the dangling $ref fallback via resolveVariantRefWithFallback. The types.ts formatting nit was not changed (minor style suggestion, no action needed). Replied to all threads with assessments.

Task list (6/6 completed)

• Checkout PR and review the new commit addressing feedback
• Verify fix for types.ts formatting (comment 1)
• Verify fix for resolveEnabled helper extraction (comment 2)
• Verify fix for definite assignment assertions (comment 3)
• Verify fix for dangling $ref bug (comment 4)
• Reply to each review comment with assessment

  ^{｜ View workflow run ｜ via Pullfrog ｜ 𝕏}

[pullfrog]

Author addressed the review feedback in commit 0883c55 by replacing definite assignment assertions with undefined initialization. Verified the fix, replied, and resolved the thread.

Task list (3/3 completed)

• Review the author's response to the review comment
• Verify the fix in the current code
• Reply to the review comment and resolve the thread

  ^{｜ View workflow run ｜ via Pullfrog ｜ 𝕏}

[pullfrog]

Reviewed commit 0883c55 which addresses the dangling $ref concern via a resolveVariantRefWithFallback helper. The fix correctly falls back to the available variant when only one is enabled. Acknowledged the fix and resolved the thread.

Task list (4/4 completed)

• Understand the review feedback and the author's response commit
• Review the new commit (0883c55) to see if it addresses the dangling $ref concern
• Verify the fix is correct and respond to the thread
• Report progress

  ^{｜ View workflow run ｜ via Pullfrog ｜ 𝕏}

[pkg-pr-new]

Open in StackBlitz

@hey-api/codegen-core

npm i https://pkg.pr.new/@hey-api/codegen-core@3837

@hey-api/json-schema-ref-parser

npm i https://pkg.pr.new/@hey-api/json-schema-ref-parser@3837

@hey-api/nuxt

npm i https://pkg.pr.new/@hey-api/nuxt@3837

@hey-api/openapi-ts

npm i https://pkg.pr.new/@hey-api/openapi-ts@3837

@hey-api/shared

npm i https://pkg.pr.new/@hey-api/shared@3837

@hey-api/spec-types

npm i https://pkg.pr.new/@hey-api/spec-types@3837

@hey-api/types

npm i https://pkg.pr.new/@hey-api/types@3837

@hey-api/vite-plugin

npm i https://pkg.pr.new/@hey-api/vite-plugin@3837

commit: 4522ef8