@kubb/plugin-zod 5.9.0 → 5.9.1

package/docs/guides/customization.md

@@ -47,7 +47,7 @@ The `integer` handler controls `int32` fields separately. To change integer repr
 
 ## Remove descriptions
 
-Use the [description-removal macro](https://kubb.dev/extensions/kubb-labs/plugin-ts/guides/customization#remove-descriptions) with `pluginZod({ macros: [dropDescriptions] })`. Generated schemas omit description metadata.
+Use the [description-removal macro](https://kubb.dev/extensions/kubb-labs/plugin-ts/guides/customization#remove-descriptions) with `pluginZod({ macros: [dropDescriptions] })`. Schemas omit their own `.describe()` calls. A `$ref` to a described component keeps one, such as `addPetBodySchema = petSchema.describe('A pet')` or the property `owner: ownerSchema.describe('An owner')`, because a macro does not visit the schema a `$ref` points to.
 
 ## Encode custom types
 
@@ -64,7 +64,7 @@ const nodes: PrinterZodNodes = {
   },
 }
 
-pluginZod({ inferred: true, printer: { nodes } })
+pluginZod({ inferred: 'codec', printer: { nodes } })
 ```
 
 Use a runtime that provides `Temporal`, or add its polyfill through a generated import or banner. Match the OpenAPI format: `time`, `date`, and `date-time` use `time`, `date`, and `datetime` handlers.
@@ -82,9 +82,9 @@ export const slotInputSchema = z.object({
 ```
 
 > [!IMPORTANT]
-> Use `inferred: true` without `pluginTs` so the client types follow these conversions. Types from `pluginTs` describe the wire format.
+> Use `inferred: 'codec'` so the client types follow these conversions. With `inferred: true`, a request type is the encoded string, not `Temporal.PlainTime`. Types from `pluginTs` describe the wire format.
 
-For built-in date conversion, set `dateType: 'date'` on the adapter. Generated response schemas convert ISO datetimes to `Date`. Request schemas convert them back with `toISOString()`.
+For built-in date conversion, set `dateType: 'date'` on the adapter. Generated response schemas convert ISO datetimes to `Date`. Request schemas convert them back with `toISOString()`. With `mini: true`, both print a plain `z.date()` without the conversion.
 
 ## Import a custom codec
 
@@ -120,8 +120,9 @@ Generated files import `myCodec` from `my-codec/zod`. Leave `root` unset on this
 | `integer`                                              | `z.int()`                             | `z.int()`                             | Coerces to `z.coerce.number().int()` when `coercion.numbers` is enabled         |
 | `integer`, `format: int32`                             | `z.int32()`                           | `z.int32()`                           | 32-bit signed integer                                                           |
 | `integer`, `format: uint32`                            | `z.uint32()`                          | `z.uint32()`                          | 32-bit unsigned integer                                                         |
-| `integer`, `format: int64`                             | `z.bigint()`                          | `z.bigint()`                          | 64-bit integer                                                                  |
-| `string`, `format: byte` / `base64`                    | `z.base64()`                          | `z.base64()`                          | Base64 string validation                                                        |
+| `integer`, `format: int64`                             | `z.coerce.bigint()`                   | `z.coerce.bigint()`                   | 64-bit integer, always coerced because JSON holds a number                      |
+| `string`, `format: base64`                             | `z.base64()`                          | `z.base64()`                          | Base64 string validation                                                        |
+| `string`, `format: byte` / `binary`                    | `z.instanceof(Blob)`                  | `z.instanceof(Blob)`                  | Binary payload                                                                  |
 | `string`, `format: base64url`                          | `z.base64url()`                       | `z.base64url()`                       | URL-safe base64 string validation                                               |
 | `string`, `contentEncoding: base64` / `base64url`      | `z.base64()` / `z.base64url()`        | `z.base64()` / `z.base64url()`        | Same checks as the formats. Other encodings stay `z.string()`                   |
 | `string`, JSON `contentMediaType` with `contentSchema` | `z.string().refine(...)`              | `z.string().check(z.refine(...))`     | The string must parse as JSON that passes the content schema. It stays a string |

package/docs/options.md

@@ -76,7 +76,7 @@ export type PutEventBodySchemaType = z.input<typeof putEventBodySchema>
 
 Pair `'codec'` with `validator: { request: 'zod', params: 'zod' }` in [`@kubb/plugin-fetch`](https://kubb.dev/extensions/kubb-labs/plugin-fetch/options#validator) or [`@kubb/plugin-axios`](https://kubb.dev/extensions/kubb-labs/plugin-axios/options#validator). Without request validation, the client sends the domain value unencoded.
 
-It also writes a `ResponsesSchema` for each operation (one schema per status code) and its inferred type. [`@kubb/plugin-fetch`](https://kubb.dev/extensions/kubb-labs/plugin-fetch) and [`@kubb/plugin-axios`](https://kubb.dev/extensions/kubb-labs/plugin-axios) key their `RequestResult` on it when `@kubb/plugin-ts` is absent.
+`inferred` also writes a `ResponsesSchema` for each operation (one schema per status code) and its inferred type. [`@kubb/plugin-fetch`](https://kubb.dev/extensions/kubb-labs/plugin-fetch) and [`@kubb/plugin-axios`](https://kubb.dev/extensions/kubb-labs/plugin-axios) key their `RequestResult` on it when `@kubb/plugin-ts` is absent.
 
 ### coercion
 
@@ -107,6 +107,8 @@ Chooses which primitives to coerce.
 > [!NOTE]
 > `numbers` also coerces an enum whose schema has a numeric `format`, such as `type: integer, format: int32`. Other enums are not coerced. When such an enum is the discriminator of a `oneOf`, the union prints as `z.union` instead of `z.discriminatedUnion`, which cannot read coerced values.
 >
+> `strings` replaces the `base64`, `base64url`, `jwt`, `ulid`, `iban`, and `duration` validators with `z.coerce.string()`, so those formats are no longer checked. Fields with `format: email`, `uri`, `uuid`, `ipv4`, or `ipv6` keep their validator and are not coerced. `numbers` prints every integer as `z.coerce.number().int()`, which drops the `int32` and `uint32` range checks.
+>
 > `dates` coerces only `Date`-typed fields (from `dateType: 'date'`). ISO-string fields are never coerced, and neither are `format: time` fields, because `new Date()` cannot parse a bare `HH:mm:ss`. For a time-of-day type such as `Temporal.PlainTime`, see [Encode custom types](https://kubb.dev/extensions/kubb-labs/plugin-zod/guides/customization#encode-custom-types).
 
 ### guidType
@@ -148,14 +150,14 @@ Emits a regex literal, such as `.regex(/^[a-z]+$/)`.
 :::
 
 :::field{name="'constructor'"}
-Emits the `RegExp` constructor, such as `.regex(new RegExp('^[a-z]+$'))`.
+Emits the `RegExp` constructor, such as `.regex(new RegExp("^[a-z]+$"))`.
 :::
 
 ::
 
 ### oneOfType
 
-Controls how a `oneOf` is validated. Use `'xor'` when values may carry extra keys, or when members have no `required` keys.
+Controls how a `oneOf` is validated. Use `'xor'` when values may carry extra keys. With `'xor'`, members need `required` keys that tell them apart. When every key is optional, an object matches several members and `z.xor` rejects it.
 
 |          |                    |
 | -------- | ------------------ |
@@ -198,16 +200,19 @@ Compiles schemas using `z.compile(...)`.
 :::
 
 :::field{name="{ strict: true }"}
-Passes `{ strict: true }` to `z.compile(...)`, which throws when any part of the schema cannot be compiled into flat JavaScript instead of falling back to the interpreter.
+Passes `{ strict: true }` to `z.compile(...)`. Zod then throws when a part of the schema cannot be compiled into flat JavaScript, where `true` falls back to the interpreter.
 :::
 
 ::
 
-Schemas with circular references (`z.lazy`) and bare `$ref` response aliases stay uncompiled to prevent runtime errors.
+Schemas with circular references (`z.lazy`) and bare `$ref` response aliases stay uncompiled to prevent runtime errors. An alias that adds a description, such as `petSchema.describe('A pet')`, is compiled.
+
+> [!NOTE]
+> `z.compile` cannot compile `z.coerce` or `z.xor`. With `strict: true`, a schema that is one of them stays uncompiled, so the generated module loads without a `ZodCompileUnsupportedError`. The same goes for a union with such a member, and for a schema that reaches a circular one through a `$ref`. Every `format: int64` schema is coerced, and so is every schema that [`coercion`](#coercion) covers. An object or array that holds a coerced field is still compiled, and Zod runs that field on its interpreter. To compile an `int64` schema, set [`integerType: 'number'`](https://kubb.dev/extensions/kubb-labs/adapter-oas/options#integertype) on the adapter.
 
 ### mini
 
-Generates [Zod Mini](https://zod.dev/packages/mini) schemas. They use functions (`z.optional(z.string())`) instead of method chains (`z.string().optional()`), so bundlers can drop unused validators. Also sets the `importPath` default to `'zod/mini'`.
+Generates [Zod Mini](https://zod.dev/packages/mini) schemas. They use functions (`z.optional(z.string())`) instead of method chains (`z.string().optional()`), so bundlers can drop unused validators. `mini` also sets the `importPath` default to `'zod/mini'`.
 
 |          |           |
 | -------- | --------- |
@@ -236,7 +241,7 @@ Generates both `is<Schema>` type guards and `assert<Schema>` assertion functions
 :::
 
 :::field{name="{ is?: boolean; assert?: boolean }"}
-Enables type guards or assertions separately.
+Turns type guards or assertions off separately. Both default to `true`, so `{ assert: false }` generates only the `is*` guards.
 :::
 
 ::
@@ -284,6 +289,7 @@ type ResolverZodPatch = {
     path?(node: OperationNode, param: ParameterNode): string
     query?(node: OperationNode, param: ParameterNode): string
     headers?(node: OperationNode, param: ParameterNode): string
+    cookies?(node: OperationNode, param: ParameterNode): string
   }
   response?: {
     status?(node: OperationNode, statusCode: StatusCode): string

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubb/plugin-zod",
-  "version": "5.9.0",
+  "version": "5.9.1",
   "description": "Generate Zod validation schemas with Kubb for runtime data parsing and type safety. Pairs with @kubb/plugin-ts for end-to-end type coverage.",
   "keywords": [
     "code-generation",
@@ -69,8 +69,8 @@
     "registry": "https://registry.npmjs.org/"
   },
   "dependencies": {
-    "@kubb/kit": "^5.18.6",
-    "@kubb/renderer-jsx": "^5.18.6"
+    "@kubb/kit": "^5.18.8",
+    "@kubb/renderer-jsx": "^5.18.8"
   },
   "devDependencies": {
     "@internals/shared": "0.0.0",