feat: zod as response transformer

[SukkaW]

Fixes #3289

This PR extends the @hey-api/sdk plugin's transformer option to accept 'zod'. When zod is used as a transformer, its parseAsync return value is forwarded as responseTransformer on the generated request options — enabling Zod's coercion and transformation rules (e.g. z.coerce.date()) to apply to response data.

The PR changes the following things:

New transformer shapes

// existing — unchanged behavior
transformer: true; // auto-select @hey-api/transformers
transformer: '@hey-api/transformers'; // explicit transformer plugin

// new
transformer: 'zod'; // use zod's parseAsync as responseTransformer
transformer: {
  response: 'zod';
} // object form — mirrors how validator: { response } works
transformer: {
  response: '@hey-api/transformers';
} // object form for transformers plugin too

Enabling transformer option as object form allows us to expand transformer abilities to request in the future.

Zod plugin as transformer

• @hey-api/transformers path (existing): a named async transformer function is code-gen'd and passed as a reference to responseTransformer.
• zod path (new): the zod plugin now exposes a createResponseTransformer method. During code-gen we will check if the plugin exposes this method, and use that to generate an inline arrow function for responseTransformer. In this case, we generate a parseAsync call.

Updated test snapshots

The test cases for this change uses the type-format.yaml spec (which has an int64 field) with transformer: 'zod' and validator: true. The generated output lives in __snapshots__/3.1.x/{v3,v4,mini}/zod-transformer/.

Two snapshot files are worth looking at:

zod.gen.ts — the generated Zod schema. The int64 field becomes z.coerce.bigint(), meaning parseAsync will coerce the raw wire value into a real BigInt:

export const zFoo = z.object({
    foo: z.coerce.bigint()...,
    id: z.string(),
});
export const zPostFooResponse = zFoo;

sdk.gen.ts — the generated SDK function. Three request options are present:

export const postFoo = (...) => client.post({
    requestValidator:    async (data) => await z.object({...}).parseAsync(data), // validates the request
    responseTransformer: async (data) => await zPostFooResponse.parseAsync(data), // NEW: transforms + coerces the response
    responseValidator:   async (data) => await zPostFooResponse.parseAsync(data), // validates the response
    url: '/foo',
});

---

The PR introduces no breaking changes:

• Default transformer: false behaviour is unchanged.
• transformer: true and transformer: '@hey-api/transformers' continue to work exactly as before.
• validator configuration is untouched.

[bolt-new-by-stackblitz]

Run & review this pull request in StackBlitz Codeflow.

[changeset-bot]

⚠️ No Changeset found

Latest commit: 5a4d8db

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

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

[vercel]

@SukkaW is attempting to deploy a commit to the Hey API Team on Vercel.

A member of the Team first needs to authorize it.

[pullfrog]

TL;DR — Extends the @hey-api/sdk plugin's transformer option to accept 'zod', enabling Zod's parseAsync (with coercion rules like z.coerce.date() and z.coerce.bigint()) to be used as a responseTransformer on generated SDK functions.

Key changes

• Expand transformer type to accept 'zod' and an object form — the UserConfig type now accepts transformer: 'zod' | { response: 'zod' | ... } alongside existing boolean / plugin-name values; the internal Config normalizes to { response: ... }
• Add createResponseTransformer to the Zod plugin API — each compatibility version (v3, v4, mini) exposes a new method that delegates to the existing response validator logic (generating an inline async (data) => await schema.parseAsync(data) arrow)
• Wire SDK code-gen to dispatch between transformer styles — if the resolved transformer plugin exposes createResponseTransformer, generate an inline arrow; otherwise fall back to the existing @hey-api/transformers named-function reference
• Auto-resolve transformer: true to validator plugins — when no @hey-api/transformers plugin is configured, the resolver now falls back to pluginByTag('validator') (e.g. Zod)
• Document Zod-as-transformer usage and warn about duplicate parseAsync — new docs section with config examples and a warning about redundant response validation
• Add snapshot tests for zod-transformer across all spec versions — 153 new snapshot files covering OpenAPI 2.0.x, 3.0.x, 3.1.x × v3/v4/mini

_{Summary ｜ 164 files ｜ 5 commits ｜ base: main ← zod-as-response-transformer}

transformer config normalization and type expansion

Before: transformer accepted PluginTransformerNames | boolean and was stored as a flat string | false internally.
After: transformer accepts PluginTransformerNames | 'zod' | boolean | { response: ... } and is always normalized to { response: string | false } during plugin setup.

The normalization logic in config.ts now converts any shorthand (true, 'zod', '@hey-api/transformers') into { response: <resolved> } before the rest of code-gen runs. The true resolver attempts pluginByTag('transformer') first, then falls back to pluginByTag('validator').

config.ts · types.ts

Zod plugin createResponseTransformer method

Before: The Zod plugin only exposed createResponseValidator for response validation.
After: It additionally exposes createResponseTransformer — which currently delegates to the same parseAsync generation as the validator, but is a distinct API surface for the SDK to dispatch on.

Each compatibility layer (mini/api.ts, v3/api.ts, v4/api.ts) adds a thin wrapper that calls the existing response validator builder. The IApi interface in zod/api.ts gains the new method signature.

zod/api.ts · mini/api.ts · v4/api.ts

SDK code-gen dispatches on transformer plugin capabilities

Before: operationStatements unconditionally looked up a named 'transform' symbol and referenced it.
After: It first checks whether the resolved transformer plugin exposes createResponseTransformer; if so, it generates an inline arrow (async (data) => await zSchema.parseAsync(data)). Otherwise it falls back to the existing symbol-reference path for @hey-api/transformers.

A new shared/transformer.ts module encapsulates the delegation logic — resolving the transformer plugin, verifying the API surface, and calling into it.

shared/operation.ts · shared/transformer.ts

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

[codecov]

Codecov Report

❌ Patch coverage is 9.61538% with 47 lines in your changes missing coverage. Please review.
✅ Project coverage is 39.51%. Comparing base (290ef7c) to head (5a4d8db).

Files with missing lines	Patch %	Lines
...ages/openapi-ts/src/plugins/@hey-api/sdk/config.ts	26.66%	9 Missing and 2 partials ⚠️
...pi-ts/src/plugins/@hey-api/sdk/shared/operation.ts	9.09%	7 Missing and 3 partials ⚠️
...-ts/src/plugins/@hey-api/sdk/shared/transformer.ts	0.00%	8 Missing and 2 partials ⚠️
packages/openapi-ts/src/plugins/zod/api.ts	0.00%	9 Missing and 1 partial ⚠️
packages/openapi-ts/src/plugins/zod/mini/api.ts	0.00%	2 Missing ⚠️
packages/openapi-ts/src/plugins/zod/v3/api.ts	0.00%	2 Missing ⚠️
packages/openapi-ts/src/plugins/zod/v4/api.ts	0.00%	2 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #3847      +/-   ##
==========================================
- Coverage   39.58%   39.51%   -0.08%     
==========================================
  Files         532      533       +1     
  Lines       19581    19619      +38     
  Branches     5835     5850      +15     
==========================================
+ Hits         7751     7752       +1     
- Misses       9582     9613      +31     
- Partials     2248     2254       +6     

Flag	Coverage Δ
unittests	39.51% <9.61%> (-0.08%)	⬇️

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]

Important

Two design-level observations worth discussing before this merges. Neither is a correctness bug, but both affect maintainability.

Overall the approach is sound — the config normalization, plugin dispatch, and generated output all look correct. The snapshot coverage is thorough across all spec versions and compat modes. The boilerplate snapshot files (client scaffolding, utils, core modules) are standard generated code that doesn't change between the existing and new test scenarios.

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

[pullfrog]

Minor: defaultConfig uses the normalized form { response: false } here, whereas validator on the next line uses the un-normalized false. Both work because resolveConfig handles normalization, but it's slightly inconsistent. Not blocking — just a readability note.

[pkg-pr-new]

Open in StackBlitz

@hey-api/codegen-core

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

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

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

@hey-api/nuxt

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

@hey-api/openapi-ts

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

@hey-api/shared

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

@hey-api/spec-types

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

@hey-api/types

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

@hey-api/vite-plugin

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

commit: 5a4d8db

[pullfrog]

Acknowledged that the outer type guard in operation.ts is required for TypeScript narrowing (since getPlugin returns a union where @hey-api/transformers types api as Record<string, unknown> | undefined). Replied to the comment and resolved the thread — no code changes needed.

Task list (2/2 completed)

• Acknowledge author's response about TypeScript type narrowing requirement
• Reply to the review comment and resolve the thread

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

[pullfrog]

Acknowledged the author's reply on the createResponseTransformerMini thread — the separate function is an intentional extension point and error handling is already addressed in #3814. Thread resolved, no code changes needed.

Task list (3/3 completed)

• Review the comment thread and determine appropriate response
• Reply to the review comment acknowledging the author's response
• Report progress

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