feat: zod as response transformer by SukkaW · Pull Request #3847 · hey-api/openapi-ts

SukkaW · 2026-05-03T15:54:59Z

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 · 2026-05-03T15:55:02Z

Run & review this pull request in StackBlitz Codeflow.

changeset-bot · 2026-05-03T15:55:03Z

⚠️ No Changeset found

Latest commit: 5af6914

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 · 2026-05-03T15:55:03Z

@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 · 2026-05-03T15:56:52Z

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 · 2026-05-03T15:58:40Z

Codecov Report

❌ Patch coverage is 14.70588% with 58 lines in your changes missing coverage. Please review.
✅ Project coverage is 37.76%. Comparing base (02280f8) to head (5af6914).

Files with missing lines	Patch %	Lines
packages/openapi-ts/src/plugins/zod/api.ts	0.00%	11 Missing and 1 partial ⚠️
...-ts/src/plugins/@hey-api/sdk/shared/transformer.ts	16.66%	8 Missing and 2 partials ⚠️
packages/openapi-ts/src/plugins/zod/mini/api.ts	0.00%	6 Missing ⚠️
packages/openapi-ts/src/plugins/zod/v3/api.ts	0.00%	6 Missing ⚠️
packages/openapi-ts/src/plugins/zod/v4/api.ts	0.00%	6 Missing ⚠️
...ages/openapi-ts/src/plugins/@hey-api/sdk/config.ts	44.44%	4 Missing and 1 partial ⚠️
packages/openapi-ts/src/plugins/valibot/v1/api.ts	0.00%	4 Missing ⚠️
...pi-ts/src/plugins/@hey-api/sdk/shared/operation.ts	40.00%	3 Missing ⚠️
packages/openapi-ts/src/plugins/arktype/api.ts	0.00%	2 Missing ⚠️
packages/openapi-ts/src/plugins/arktype/v2/api.ts	0.00%	2 Missing ⚠️
... and 1 more

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #3847      +/-   ##
==========================================
- Coverage   37.78%   37.76%   -0.03%     
==========================================
  Files         580      581       +1     
  Lines       20777    20805      +28     
  Branches     6047     6058      +11     
==========================================
+ Hits         7851     7856       +5     
- Misses      10522    10543      +21     
- Partials     2404     2406       +2

Flag	Coverage Δ
unittests	`37.76% <14.70%> (-0.03%)`	⬇️

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 ｜ 𝕏}

pkg-pr-new · 2026-05-03T15:59:57Z

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: 5af6914

pullfrog · 2026-05-03T16:01:12Z

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 · 2026-05-03T16:04:45Z

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 ｜ 𝕏}

…-as-response-transformer

mrlubos · 2026-05-15T18:27:06Z

@SukkaW don't mind me, I'm going to complete this pull request. I need to add support for Valibot and get rid of the "duplicate parseAsync calls" warning

SukkaW · 2026-05-15T18:30:35Z

@SukkaW don't mind me, I'm going to complete this pull request. I need to add support for Valibot and get rid of the "duplicate parseAsync calls" warning

Feel free to do so. And feel free to change how plugins expose the transformer codegen API, and the options shape.

mrlubos · 2026-05-15T18:33:15Z

@SukkaW I'm going to add one more optional method for returning response handlers together. This will be called only if the same plugin is configured for both. Then the plugin can decide whether to return only transformer or both. In this case, we want to return only transformer to avoid wasted cycles

SukkaW added 5 commits May 3, 2026 23:17

feat(zod): implement response transformer

f31d3d6

feat(sdk): add zod to new transformer type

665fb3b

feat(sdk): adapt response transformer to new format

03db4a4

test(zod): add test cases for zod transformer support

b2a3b8f

docs(zod): document that zod as transformer is a thing now

5a4d8db

SukkaW marked this pull request as ready for review May 3, 2026 15:55

dosubot Bot added size:XXL This PR changes 1000+ lines, ignoring generated files. feature 🚀 Feature request. labels May 3, 2026

SukkaW mentioned this pull request May 3, 2026

Add ability to use Zod schema as sdk responseTransformer #3289

Open

pullfrog Bot reviewed May 3, 2026

View reviewed changes

Comment thread packages/openapi-ts/src/plugins/@hey-api/sdk/shared/operation.ts Outdated

Comment thread packages/openapi-ts/src/plugins/zod/mini/api.ts

Comment thread packages/openapi-ts/src/plugins/@hey-api/sdk/config.ts Outdated

mrlubos added 6 commits May 15, 2026 23:51

Merge branch 'main' of https://github.com/hey-api/openapi-ts into zod…

a6304b4

…-as-response-transformer

test: update snapshots

d9b646f

chore: update sdk types

4277623

test: update snapshots

186ed9e

chore: simplify transformer config

2fab005

chore: discriminate on function nodes

5af6914

Uh oh!

Conversation

SukkaW commented May 3, 2026

Uh oh!

bolt-new-by-stackblitz Bot commented May 3, 2026

Uh oh!

changeset-bot Bot commented May 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

⚠️ No Changeset found

Uh oh!

vercel Bot commented May 3, 2026

Uh oh!

pullfrog Bot commented May 3, 2026

Key changes

transformer config normalization and type expansion

Zod plugin createResponseTransformer method

SDK code-gen dispatches on transformer plugin capabilities

Uh oh!

codecov Bot commented May 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

pullfrog Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

pkg-pr-new Bot commented May 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

pullfrog Bot commented May 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

pullfrog Bot commented May 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mrlubos commented May 15, 2026

Uh oh!

SukkaW commented May 15, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mrlubos commented May 15, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

changeset-bot Bot commented May 3, 2026 •

edited

Loading

`transformer` config normalization and type expansion

Zod plugin `createResponseTransformer` method

codecov Bot commented May 3, 2026 •

edited

Loading

pkg-pr-new Bot commented May 3, 2026 •

edited

Loading

pullfrog Bot commented May 3, 2026 •

edited

Loading

pullfrog Bot commented May 3, 2026 •

edited

Loading

SukkaW commented May 15, 2026 •

edited

Loading