···11+---
22+'@hey-api/openapi-ts': minor
33+---
44+55+fix: require sdk.transformer to use generated transformers
66+77+### Added `sdk.transformer` option
88+99+When generating SDKs, you now have to specify `transformer` in order to modify response data. By default, adding `@hey-api/transformers` to your plugins will only produce additional output. To preserve the previous functionality, set `sdk.transformer` to `true`.
1010+1111+```js
1212+import { defaultPlugins } from '@hey-api/openapi-ts';
1313+1414+export default {
1515+ client: '@hey-api/client-fetch',
1616+ input: 'path/to/openapi.json',
1717+ output: 'src/client',
1818+ plugins: [
1919+ ...defaultPlugins,
2020+ {
2121+ dates: true,
2222+ name: '@hey-api/transformers',
2323+ },
2424+ {
2525+ name: '@hey-api/sdk',
2626+ transformer: true, // [!code ++]
2727+ },
2828+ ],
2929+};
3030+```
···27272828Automatically update your code when the APIs it depends on change. [Find out more](https://heyapi.dev/openapi-ts/integrations.html).
29293030-## Migrating from OpenAPI Typescript Codegen?
3131-3232-Please read our [migration guide](https://heyapi.dev/openapi-ts/migrating.html#openapi-typescript-codegen).
3333-3434-## Contributing
3030+## Migration Guides
35313636-Want to get involved? Please refer to the [contributing guide](https://heyapi.dev/contributing.html).
3232+[OpenAPI Typescript Codegen](https://heyapi.dev/openapi-ts/migrating.html#openapi-typescript-codegen).
···15151616- seamless integration with `@hey-api/openapi-ts` ecosystem
1717- type-safe response data and errors
1818+- response data validation and transformation
1819- access to the original request and response
1920- granular request and response customization options
2021- minimal learning curve thanks to extending the underlying technology
+27
docs/openapi-ts/migrating.md
···27272828This config option is deprecated and will be removed.
29293030+## v0.60.0
3131+3232+### Added `sdk.transformer` option
3333+3434+When generating SDKs, you now have to specify `transformer` in order to modify response data. By default, adding `@hey-api/transformers` to your plugins will only produce additional output. To preserve the previous functionality, set `sdk.transformer` to `true`.
3535+3636+```js
3737+import { defaultPlugins } from '@hey-api/openapi-ts';
3838+3939+export default {
4040+ client: '@hey-api/client-fetch',
4141+ input: 'path/to/openapi.json',
4242+ output: 'src/client',
4343+ plugins: [
4444+ ...defaultPlugins,
4545+ {
4646+ dates: true,
4747+ name: '@hey-api/transformers',
4848+ },
4949+ {
5050+ name: '@hey-api/sdk',
5151+ transformer: true, // [!code ++]
5252+ },
5353+ ],
5454+};
5555+```
5656+3057## v0.59.0
31583259### Added `logs.level` option
+1-1
docs/openapi-ts/plugins.md
···2626- [`@tanstack/svelte-query`](/openapi-ts/tanstack-query) - TanStack Query functions and query keys
2727- [`@tanstack/vue-query`](/openapi-ts/tanstack-query) - TanStack Query functions and query keys
2828- [`fastify`](/openapi-ts/fastify) - TypeScript interface for Fastify route handlers
2929-- [`zod`](/openapi-ts/zod) - Zod schemas to validate your data
2929+- [`zod`](/openapi-ts/validators/zod) - Zod schemas to validate your data
30303131## Community
3232
+41-1
docs/openapi-ts/transformers.md
···11---
22title: Transformers
33-description: Learn about transforming payloads with @hey-api/openapi-ts.
33+description: Learn about transforming data with @hey-api/openapi-ts.
44---
5566# Transformers
···2626- error responses are not transformed
27272828If your data isn't being transformed as expected, we encourage you to leave feedback on [GitHub](https://github.com/hey-api/openapi-ts/issues).
2929+3030+## Configuration
3131+3232+To generate transformers, add `@hey-api/transformers` to your plugins.
3333+3434+```js
3535+import { defaultPlugins } from '@hey-api/openapi-ts';
3636+3737+export default {
3838+ client: '@hey-api/client-fetch',
3939+ input: 'path/to/openapi.json',
4040+ output: 'src/client',
4141+ plugins: [
4242+ ...defaultPlugins,
4343+ '@hey-api/transformers', // [!code ++]
4444+ ],
4545+};
4646+```
4747+4848+## SDKs
4949+5050+To automatically transform response data in your SDKs, set `transformer` to `true`.
5151+5252+```js
5353+import { defaultPlugins } from '@hey-api/openapi-ts';
5454+5555+export default {
5656+ client: '@hey-api/client-fetch',
5757+ input: 'path/to/openapi.json',
5858+ output: 'src/client',
5959+ plugins: [
6060+ ...defaultPlugins,
6161+ '@hey-api/transformers',
6262+ {
6363+ name: '@hey-api/sdk', // [!code ++]
6464+ transformer: true, // [!code ++]
6565+ },
6666+ ],
6767+};
6868+```
29693070## Dates
3171
+62
docs/openapi-ts/validators.md
···11+---
22+title: Validators
33+description: Learn about validating data with @hey-api/openapi-ts.
44+---
55+66+# Validators
77+88+There are times when you cannot blindly trust the server to return the correct data. You might be working on a critical application where any mistakes would be costly, or you're simply dealing with a legacy or undocumented system.
99+1010+Hey API clients support validating responses so you can rest assured that you're working with the correct data.
1111+1212+## Available Validators
1313+1414+- [Zod](/openapi-ts/validators/zod)
1515+- [Ajv](https://ajv.js.org/) <span class="soon">Soon</span>
1616+- [Joi](https://joi.dev/) <span class="soon">Soon</span>
1717+- [Yup](https://github.com/jquense/yup) <span class="soon">Soon</span>
1818+1919+If you'd like Hey API to support your validator, let us know by [opening an issue](https://github.com/hey-api/openapi-ts/issues).
2020+2121+## Installation
2222+2323+There are two ways to generate validators. If you only need response validation in your SDKs, set `sdk.validator` to the desired value. For a more granular approach, add the validator to your plugins and set `sdk.validator` to `true`.
2424+2525+::: code-group
2626+2727+```js [sdk]
2828+export default {
2929+ client: '@hey-api/client-fetch',
3030+ input: 'path/to/openapi.json',
3131+ output: 'src/client',
3232+ plugins: [
3333+ {
3434+ name: '@hey-api/sdk',
3535+ validator: 'zod', // [!code ++]
3636+ },
3737+ ],
3838+};
3939+```
4040+4141+```js [validator]
4242+export default {
4343+ client: '@hey-api/client-fetch',
4444+ input: 'path/to/openapi.json',
4545+ output: 'src/client',
4646+ plugins: [
4747+ {
4848+ name: '@hey-api/sdk',
4949+ validator: true, // [!code ++]
5050+ },
5151+ {
5252+ name: 'zod', // [!code ++]
5353+ // other options
5454+ },
5555+ ],
5656+};
5757+```
5858+5959+:::
6060+6161+<!--@include: ../examples.md-->
6262+<!--@include: ../sponsorship.md-->
···45454646You can now generate Zod artifacts. 🎉
47474848+## SDKs
4949+5050+To automatically validate response data in your SDKs, set `validator` to `true`.
5151+5252+```js
5353+import { defaultPlugins } from '@hey-api/openapi-ts';
5454+5555+export default {
5656+ client: '@hey-api/client-fetch',
5757+ input: 'path/to/openapi.json',
5858+ output: 'src/client',
5959+ plugins: [
6060+ ...defaultPlugins,
6161+ 'zod',
6262+ {
6363+ name: '@hey-api/sdk', // [!code ++]
6464+ validator: true, // [!code ++]
6565+ },
6666+ ],
6767+};
6868+```
6969+4870## Output
49715072The Zod plugin will generate the following artifacts, depending on the input specification.
···53755476More information will be provided as we finalize the plugin.
55775656-<!--@include: ../examples.md-->
5757-<!--@include: ../sponsorship.md-->
7878+<!--@include: ../../examples.md-->
7979+<!--@include: ../../sponsorship.md-->
+3-6
packages/client-axios/README.md
···10101111- seamless integration with `@hey-api/openapi-ts` ecosystem
1212- type-safe response data and errors
1313+- response data validation and transformation
1314- access to the original request and response
1415- granular request and response customization options
1516- minimal learning curve thanks to extending the underlying technology
···27282829Automatically update your code when the APIs it depends on change. [Find out more](https://heyapi.dev/openapi-ts/integrations.html).
29303030-## Migrating from OpenAPI Typescript Codegen?
3131-3232-Please read our [migration guide](https://heyapi.dev/openapi-ts/migrating.html#openapi-typescript-codegen).
3333-3434-## Contributing
3131+## Migration Guides
35323636-Want to get involved? Please refer to the [contributing guide](https://heyapi.dev/contributing.html).
3333+[OpenAPI Typescript Codegen](https://heyapi.dev/openapi-ts/migrating.html#openapi-typescript-codegen).
+8-2
packages/client-axios/src/index.ts
···64646565 let { data } = response;
66666767- if (opts.responseType === 'json' && opts.responseTransformer) {
6868- data = await opts.responseTransformer(data);
6767+ if (opts.responseType === 'json') {
6868+ if (opts.responseValidator) {
6969+ await opts.responseValidator(data);
7070+ }
7171+7272+ if (opts.responseTransformer) {
7373+ data = await opts.responseTransformer(data);
7474+ }
6975 }
70767177 return {
+9-4
packages/client-axios/src/types.ts
···8383 */
8484 querySerializer?: QuerySerializer | QuerySerializerOptions;
8585 /**
8686- * A function for transforming response data before it's returned to the
8787- * caller function. This is an ideal place to post-process server data,
8888- * e.g. convert date ISO strings into native Date objects.
8686+ * A function transforming response data before it's returned. This is useful
8787+ * for post-processing data, e.g. converting ISO strings into Date objects.
8988 */
9089 responseTransformer?: (data: unknown) => Promise<unknown>;
9190 /**
9191+ * A function validating response data. This is useful if you want to ensure
9292+ * the response conforms to the desired shape, so it can be safely passed to
9393+ * the transformers and returned to the user.
9494+ */
9595+ responseValidator?: (data: unknown) => Promise<unknown>;
9696+ /**
9297 * Throw an error instead of returning it in the response?
9398 *
9499 * @default false
···97102}
9810399104export interface RequestOptions<
100100- ThrowOnError extends boolean = false,
105105+ ThrowOnError extends boolean = boolean,
101106 Url extends string = string,
102107> extends Config<ThrowOnError> {
103108 /**
+3-6
packages/client-fetch/README.md
···10101111- seamless integration with `@hey-api/openapi-ts` ecosystem
1212- type-safe response data and errors
1313+- response data validation and transformation
1314- access to the original request and response
1415- granular request and response customization options
1516- minimal learning curve thanks to extending the underlying technology
···27282829Automatically update your code when the APIs it depends on change. [Find out more](https://heyapi.dev/openapi-ts/integrations.html).
29303030-## Migrating from OpenAPI Typescript Codegen?
3131-3232-Please read our [migration guide](https://heyapi.dev/openapi-ts/migrating.html#openapi-typescript-codegen).
3333-3434-## Contributing
3131+## Migration Guides
35323636-Want to get involved? Please refer to the [contributing guide](https://heyapi.dev/contributing.html).
3333+[OpenAPI Typescript Codegen](https://heyapi.dev/openapi-ts/migrating.html#openapi-typescript-codegen).
+8-2
packages/client-fetch/src/index.ts
···106106 : opts.parseAs) ?? 'json';
107107108108 let data = await response[parseAs]();
109109- if (parseAs === 'json' && opts.responseTransformer) {
110110- data = await opts.responseTransformer(data);
109109+ if (parseAs === 'json') {
110110+ if (opts.responseValidator) {
111111+ await opts.responseValidator(data);
112112+ }
113113+114114+ if (opts.responseTransformer) {
115115+ data = await opts.responseTransformer(data);
116116+ }
111117 }
112118113119 return {
+8-3
packages/client-fetch/src/types.ts
···8888 */
8989 querySerializer?: QuerySerializer | QuerySerializerOptions;
9090 /**
9191- * A function for transforming response data before it's returned to the
9292- * caller function. This is an ideal place to post-process server data,
9393- * e.g. convert date ISO strings into native Date objects.
9191+ * A function transforming response data before it's returned. This is useful
9292+ * for post-processing data, e.g. converting ISO strings into Date objects.
9493 */
9594 responseTransformer?: (data: unknown) => Promise<unknown>;
9595+ /**
9696+ * A function validating response data. This is useful if you want to ensure
9797+ * the response conforms to the desired shape, so it can be safely passed to
9898+ * the transformers and returned to the user.
9999+ */
100100+ responseValidator?: (data: unknown) => Promise<unknown>;
96101 /**
97102 * Throw an error instead of returning it in the response?
98103 *
+2-6
packages/openapi-ts/README.md
···27272828Automatically update your code when the APIs it depends on change. [Find out more](https://heyapi.dev/openapi-ts/integrations.html).
29293030-## Migrating from OpenAPI Typescript Codegen?
3131-3232-Please read our [migration guide](https://heyapi.dev/openapi-ts/migrating.html#openapi-typescript-codegen).
3333-3434-## Contributing
3030+## Migration Guides
35313636-Want to get involved? Please refer to the [contributing guide](https://heyapi.dev/contributing.html).
3232+[OpenAPI Typescript Codegen](https://heyapi.dev/openapi-ts/migrating.html#openapi-typescript-codegen).
···8585};
86868787interface OperationResponsesMap {
8888+ /**
8989+ * A deduplicated union of all error types. Unknown types are omitted.
9090+ */
8891 error?: IRSchemaObject;
9292+ /**
9393+ * An object containing a map of status codes for each error type.
9494+ */
8995 errors?: IRSchemaObject;
9696+ /**
9797+ * A deduplicated union of all response types. Unknown types are omitted.
9898+ */
9099 response?: IRSchemaObject;
100100+ /**
101101+ * An object containing a map of status codes for each response type.
102102+ */
91103 responses?: IRSchemaObject;
92104}
93105
···7777 * @default '{{name}}Service'
7878 */
7979 serviceNameBuilder?: string;
8080+ /**
8181+ * Transform response data before returning. This is useful if you want to
8282+ * convert for example ISO strings into Date objects. However, transformation
8383+ * adds runtime overhead, so it's not recommended to use unless necessary.
8484+ *
8585+ * You can customize the selected transformer output through its plugin. You
8686+ * can also set `transformer` to `true` to automatically choose the
8787+ * transformer from your defined plugins.
8888+ *
8989+ * @default false
9090+ */
9191+ transformer?: '@hey-api/transformers' | boolean;
9292+ /**
9393+ * **This feature works only with the experimental parser**
9494+ *
9595+ * Validate response data against schema before returning. This is useful
9696+ * if you want to ensure the response conforms to a desired shape. However,
9797+ * validation adds runtime overhead, so it's not recommended to use unless
9898+ * absolutely necessary.
9999+ *
100100+ * Ensure you have declared the selected library as a dependency to avoid
101101+ * errors. You can customize the selected validator output through its
102102+ * plugin. You can also set `validator` to `true` to automatically choose
103103+ * the validator from your defined plugins.
104104+ *
105105+ * @default false
106106+ */
107107+ validator?: 'zod' | boolean;
80108}
···1616import { getConfig } from '../../../utils/config';
1717import { getServiceName } from '../../../utils/postprocess';
1818import { transformServiceName } from '../../../utils/transform';
1919-import {
2020- operationIrRef,
2121- operationOptionsType,
2222-} from '../../@hey-api/sdk/plugin';
1919+import { operationOptionsType } from '../../@hey-api/sdk/plugin';
2320import { serviceFunctionIdentifier } from '../../@hey-api/sdk/plugin-legacy';
2421import { schemaToType } from '../../@hey-api/typescript/plugin';
2222+import { operationIrRef } from '../../shared/utils/ref';
2523import type { Plugin } from '../../types';
2624import type { Config as AngularQueryConfig } from '../angular-query-experimental';
2725import type { Config as ReactQueryConfig } from '../react-query';
+1-1
packages/openapi-ts/src/plugins/fastify/plugin.ts
···55import type { IROperationObject } from '../../ir/ir';
66import { operationResponsesMap } from '../../ir/operation';
77import { hasParameterGroupObjectRequired } from '../../ir/parameter';
88-import { operationIrRef } from '../@hey-api/sdk/plugin';
88+import { operationIrRef } from '../shared/utils/ref';
99import type { Plugin } from '../types';
1010import type { Config } from './types';
1111
···8383 */
8484 querySerializer?: QuerySerializer | QuerySerializerOptions;
8585 /**
8686- * A function for transforming response data before it's returned to the
8787- * caller function. This is an ideal place to post-process server data,
8888- * e.g. convert date ISO strings into native Date objects.
8686+ * A function transforming response data before it's returned. This is useful
8787+ * for post-processing data, e.g. converting ISO strings into Date objects.
8988 */
9089 responseTransformer?: (data: unknown) => Promise<unknown>;
9190 /**
9191+ * A function validating response data. This is useful if you want to ensure
9292+ * the response conforms to the desired shape, so it can be safely passed to
9393+ * the transformers and returned to the user.
9494+ */
9595+ responseValidator?: (data: unknown) => Promise<unknown>;
9696+ /**
9297 * Throw an error instead of returning it in the response?
9398 *
9499 * @default false
···97102}
9810399104export interface RequestOptions<
100100- ThrowOnError extends boolean = false,
105105+ ThrowOnError extends boolean = boolean,
101106 Url extends string = string,
102107> extends Config<ThrowOnError> {
103108 /**
···8383 */
8484 querySerializer?: QuerySerializer | QuerySerializerOptions;
8585 /**
8686- * A function for transforming response data before it's returned to the
8787- * caller function. This is an ideal place to post-process server data,
8888- * e.g. convert date ISO strings into native Date objects.
8686+ * A function transforming response data before it's returned. This is useful
8787+ * for post-processing data, e.g. converting ISO strings into Date objects.
8988 */
9089 responseTransformer?: (data: unknown) => Promise<unknown>;
9190 /**
9191+ * A function validating response data. This is useful if you want to ensure
9292+ * the response conforms to the desired shape, so it can be safely passed to
9393+ * the transformers and returned to the user.
9494+ */
9595+ responseValidator?: (data: unknown) => Promise<unknown>;
9696+ /**
9297 * Throw an error instead of returning it in the response?
9398 *
9499 * @default false
···97102}
9810399104export interface RequestOptions<
100100- ThrowOnError extends boolean = false,
105105+ ThrowOnError extends boolean = boolean,
101106 Url extends string = string,
102107> extends Config<ThrowOnError> {
103108 /**
···8888 */
8989 querySerializer?: QuerySerializer | QuerySerializerOptions;
9090 /**
9191- * A function for transforming response data before it's returned to the
9292- * caller function. This is an ideal place to post-process server data,
9393- * e.g. convert date ISO strings into native Date objects.
9191+ * A function transforming response data before it's returned. This is useful
9292+ * for post-processing data, e.g. converting ISO strings into Date objects.
9493 */
9594 responseTransformer?: (data: unknown) => Promise<unknown>;
9595+ /**
9696+ * A function validating response data. This is useful if you want to ensure
9797+ * the response conforms to the desired shape, so it can be safely passed to
9898+ * the transformers and returned to the user.
9999+ */
100100+ responseValidator?: (data: unknown) => Promise<unknown>;
96101 /**
97102 * Throw an error instead of returning it in the response?
98103 *
···8888 */
8989 querySerializer?: QuerySerializer | QuerySerializerOptions;
9090 /**
9191- * A function for transforming response data before it's returned to the
9292- * caller function. This is an ideal place to post-process server data,
9393- * e.g. convert date ISO strings into native Date objects.
9191+ * A function transforming response data before it's returned. This is useful
9292+ * for post-processing data, e.g. converting ISO strings into Date objects.
9493 */
9594 responseTransformer?: (data: unknown) => Promise<unknown>;
9595+ /**
9696+ * A function validating response data. This is useful if you want to ensure
9797+ * the response conforms to the desired shape, so it can be safely passed to
9898+ * the transformers and returned to the user.
9999+ */
100100+ responseValidator?: (data: unknown) => Promise<unknown>;
96101 /**
97102 * Throw an error instead of returning it in the response?
98103 *