@kubb/plugin-zod 4.18.4 → 4.18.5

package/dist/{types-BNtlNlKK.d.ts → types-CaZySLsa.d.ts}

@@ -37,7 +37,7 @@ declare class Oas extends BaseOas {
   getResponseSchema(operation: Operation$1, statusCode: string | number): SchemaObject$1;
   getRequestSchema(operation: Operation$1): SchemaObject$1 | undefined;
   getParametersSchema(operation: Operation$1, inKey: 'path' | 'query' | 'header'): SchemaObject$1 | null;
-  valdiate(): Promise<oas_normalize_lib_types0.ValidationResult>;
+  validate(): Promise<oas_normalize_lib_types0.ValidationResult>;
   flattenSchema(schema: SchemaObject$1 | null): SchemaObject$1 | null;
 }
 //#endregion
@@ -339,7 +339,7 @@ type Config<TInput = Input> = {
   input: TInput;
   output: {
     /**
-     * The path where all generated files will be exported.
+     * The path where all generated files receives exported.
      * This can be an absolute path or a path relative to the specified root option.
      */
     path: string;
@@ -354,41 +354,39 @@ type Config<TInput = Input> = {
     write?: boolean;
     /**
      * Specifies the formatting tool to be used.
-     * @default prettier
-     *
-     * Possible values:
-     * - 'auto': Automatically detects and uses biome or prettier (in that order of preference).
-     * - 'prettier': Uses Prettier for code formatting.
-     * - 'biome': Uses Biome for code formatting.
-     *
+     * - 'auto' automatically detects and uses biome or prettier (in that order of preference).
+     * - 'prettier' uses Prettier for code formatting.
+     * - 'biome' uses Biome for code formatting.
+     * - 'oxfmt' uses Oxfmt for code formatting.
+     * - false disables code formatting.
+     * @default 'prettier'
      */
     format?: 'auto' | 'prettier' | 'biome' | 'oxfmt' | false;
     /**
      * Specifies the linter that should be used to analyze the code.
-     * The accepted values indicate different linting tools.
-     *
-     * Possible values:
-     * - 'auto': Automatically detects and uses biome, oxlint, or eslint (in that order of preference).
-     * - 'eslint': Represents the use of ESLint, a widely used JavaScript linter.
-     * - 'biome': Represents the Biome linter, a modern tool for code scanning.
-     * - 'oxlint': Represents the Oxlint tool for linting purposes.
-     *
+     * - 'auto' automatically detects and uses biome, oxlint, or eslint (in that order of preference).
+     * - 'eslint' uses ESLint for linting.
+     * - 'biome' uses Biome for linting.
+     * - 'oxlint' uses Oxlint for linting.
+     * - false disables linting.
+     * @default 'auto'
      */
     lint?: 'auto' | 'eslint' | 'biome' | 'oxlint' | false;
     /**
-     * Override the extension to the generated imports and exports, by default each plugin will add an extension
+     * Overrides the extension for generated imports and exports. By default, each plugin adds an extension.
      * @default { '.ts': '.ts'}
      */
     extension?: Record<KubbFile.Extname, KubbFile.Extname | ''>;
     /**
-     * Specify how `index.ts` files should be created. You can also disable the generation of barrel files here. While each plugin has its own `barrelType` option, this setting controls the creation of the root barrel file, such as` src/gen/index.ts`.
+     * Configures how `index.ts` files are created, including disabling barrel file generation. Each plugin has its own `barrelType` option; this setting controls the root barrel file (e.g., `src/gen/index.ts`).
      * @default 'named'
      */
     barrelType?: Exclude<BarrelType, 'propagate'> | false;
     /**
-     * Add a default banner to the beginning of every generated file. This makes it clear that the file was generated by Kubb.
-     * - 'simple': will only add banner with link to Kubb
-     * - 'full': will add source, title, description and the OpenAPI version used
+     * Adds a default banner to the start of every generated file indicating it was generated by Kubb.
+     * - 'simple' adds banner with link to Kubb.
+     * - 'full' adds source, title, description, and OpenAPI version.
+     * - false disables banner generation.
      * @default 'simple'
      */
     defaultBanner?: 'simple' | 'full' | false;
@@ -401,17 +399,17 @@ type Config<TInput = Input> = {
     override?: boolean;
   };
   /**
-   * An array of Kubb plugins that will be used in the generation.
+   * An array of Kubb plugins that used in the generation.
    * Each plugin may include additional configurable options(defined in the plugin itself).
-   * If a plugin depends on another plugin, an error will be returned if the required dependency is missing. See pre for more details.
+   * If a plugin depends on another plugin, an error is returned if the required dependency is missing. See pre for more details.
    */
   plugins?: Array<Plugin>;
   /**
-   * Hooks that will be called when a specific action is triggered in Kubb.
+   * Hooks triggered when a specific action occurs in Kubb.
    */
   hooks?: {
     /**
-     * Hook that will be triggered at the end of all executions.
+     * Hook that triggers at the end of all executions.
      * Useful for running Prettier or ESLint to format/lint your code.
      */
     done?: string | Array<string>;
@@ -440,7 +438,7 @@ TContext = any,
 TResolvePathOptions extends object = object> = {
   name: TName;
   /**
-   * Same behaviour like what has been done with `QueryKey` in `@tanstack/react-query`
+   * Same behavior like what has been done with `QueryKey` in `@tanstack/react-query`
    */
   key: PluginKey<TName | string>;
   options: TOptions;
@@ -461,12 +459,12 @@ type UserPlugin<TOptions extends PluginFactoryOptions = PluginFactoryOptions> =
    */
   options: TOptions['resolvedOptions'];
   /**
-   * Specifies the preceding plugins for the current plugin. You can pass an array of preceding plugin names, and the current plugin will be executed after these plugins.
+   * Specifies the preceding plugins for the current plugin. You can pass an array of preceding plugin names, and the current plugin is executed after these plugins.
    * Can be used to validate dependent plugins.
    */
   pre?: Array<string>;
   /**
-   * Specifies the succeeding plugins for the current plugin. You can pass an array of succeeding plugin names, and the current plugin will be executed before these plugins.
+   * Specifies the succeeding plugins for the current plugin. You can pass an array of succeeding plugin names, and the current plugin is executed before these plugins.
    */
   post?: Array<string>;
   inject?: (this: PluginContext<TOptions>, context: PluginContext<TOptions>) => TOptions['context'];
@@ -484,12 +482,12 @@ type Plugin<TOptions extends PluginFactoryOptions = PluginFactoryOptions> = {
    */
   key: TOptions['key'];
   /**
-   * Specifies the preceding plugins for the current plugin. You can pass an array of preceding plugin names, and the current plugin will be executed after these plugins.
+   * Specifies the preceding plugins for the current plugin. You can pass an array of preceding plugin names, and the current plugin is executed after these plugins.
    * Can be used to validate dependent plugins.
    */
   pre?: Array<string>;
   /**
-   * Specifies the succeeding plugins for the current plugin. You can pass an array of succeeding plugin names, and the current plugin will be executed before these plugins.
+   * Specifies the succeeding plugins for the current plugin. You can pass an array of succeeding plugin names, and the current plugin is executed before these plugins.
    */
   post?: Array<string>;
   /**
@@ -539,10 +537,12 @@ type ResolveNameParams = {
   name: string;
   pluginKey?: Plugin['key'];
   /**
-   * `file` will be used to customize the name of the created file(use of camelCase)
-   * `function` can be used to customize the exported functions(use of camelCase)
-   * `type` is a special type for TypeScript(use of PascalCase)
-   * `const` can be used for variables(use of camelCase)
+   * Specifies the type of entity being named.
+   * - 'file' customizes the name of the created file (uses camelCase).
+   * - 'function' customizes the exported function names (uses camelCase).
+   * - 'type' customizes TypeScript types (uses PascalCase).
+   * - 'const' customizes variable names (uses camelCase).
+   * @default undefined
    */
   type?: 'file' | 'function' | 'type' | 'const';
 };
@@ -597,11 +597,14 @@ type GroupContext = {
 };
 type Group = {
   /**
-   * Define a type where to group the files on
+   * Defines the type where to group the files.
+   * - 'tag' groups files by OpenAPI tags.
+   * - 'path' groups files by OpenAPI paths.
+   * @default undefined
    */
   type: 'tag' | 'path';
   /**
-   * Return the name of a group based on the group name, this will be used for the file and name generation
+   * Return the name of a group based on the group name, this used for the file and name generation
    */
   name?: (context: GroupContext) => string;
 };
@@ -673,7 +676,7 @@ declare class PluginManager {
     parameters: PluginParameter<H>;
   }): Array<ReturnType<ParseResult<H>>> | null;
   /**
-   * First non-null result stops and will return it's value.
+   * Returns the first non-null result.
    */
   hookFirst<H extends PluginLifecycleHooks>({
     hookName,
@@ -685,7 +688,7 @@ declare class PluginManager {
     skipped?: ReadonlySet<Plugin> | null;
   }): Promise<SafeParseResult<H>>;
   /**
-   * First non-null result stops and will return it's value.
+   * Returns the first non-null result.
    */
   hookFirstSync<H extends PluginLifecycleHooks>({
     hookName,
@@ -697,15 +700,15 @@ declare class PluginManager {
     skipped?: ReadonlySet<Plugin> | null;
   }): SafeParseResult<H>;
   /**
-   * Run all plugins in parallel(order will be based on `this.plugin` and if `pre` or `post` is set).
+   * Runs all plugins in parallel based on `this.plugin` order and `pre`/`post` settings.
    */
-  hookParallel<H extends PluginLifecycleHooks, TOuput = void>({
+  hookParallel<H extends PluginLifecycleHooks, TOutput = void>({
     hookName,
     parameters
   }: {
     hookName: H;
     parameters?: Parameters<RequiredPluginLifecycle[H]> | undefined;
-  }): Promise<Awaited<TOuput>[]>;
+  }): Promise<Awaited<TOutput>[]>;
   /**
    * Chains plugins
    */
@@ -841,8 +844,8 @@ type SchemaKeywordMapper = {
        */
       path: KubbFile.Path;
       /**
-       * When true `File.Import` will be used.
-       * When false a reference will be used inside the current file.
+       * When true `File.Import` is used.
+       * When false a reference is used inside the current file.
        */
       isImportable: boolean;
     };
@@ -1074,7 +1077,7 @@ type SchemaGeneratorOptions = {
      */
     name?: (name: ResolveNameParams['name'], type?: ResolveNameParams['type']) => string;
     /**
-     * Receive schema and name(propertName) and return FakerMeta array
+     * Receive schema and name(propertyName) and return FakerMeta array
      * TODO TODO add docs
      * @beta
      */
@@ -1185,7 +1188,7 @@ type Options = {
   output?: Output<Oas>;
   /**
    * Define which contentType should be used.
-   * By default, the first JSON valid mediaType will be used
+   * By default, the first JSON valid mediaType is used
    */
   contentType?: contentType;
   /**
@@ -1206,25 +1209,36 @@ type Options = {
   override?: Array<Override<ResolvedOptions>>;
   /**
    * Path to Zod
-   * It will be used as `import { z } from '${importPath}'`.
-   * It allows both relative and absolute path.
-   * the path will be applied as is, so relative path should be based on the file being generated.
+   * It used as `import { z } from '${importPath}'`.
+   * Accepts relative and absolute paths.
+   * Path is used as-is; relative paths are based on the generated file location.
    * @default 'zod'
    */
   importPath?: string;
   /**
-   * Choose to use `date` or `datetime` as JavaScript `Date` instead of `string`.
-   * False will fallback on a simple z.string() format
-   * @default 'string' 'stringOffset' will become the default in Kubb v3
+   * Choose to use date or datetime as JavaScript Date instead of string.
+   * - false falls back to a simple z.string() format.
+   * - 'string' uses z.string().datetime() for datetime validation.
+   * - 'stringOffset' uses z.string().datetime({ offset: true }) for datetime with timezone offset validation.
+   * - 'stringLocal' uses z.string().datetime({ local: true }) for local datetime validation.
+   * - 'date' uses z.date() for JavaScript Date objects.
+   * @default 'string'
+   * @note 'stringOffset' will become the default in Kubb v3.
    */
   dateType?: false | 'string' | 'stringOffset' | 'stringLocal' | 'date';
   /**
-   * Which type to use when the Swagger/OpenAPI file is not providing more information
+   * Which type to use when the Swagger/OpenAPI file is not providing more information.
+   * - 'any' allows any value.
+   * - 'unknown' requires type narrowing before use.
+   * - 'void' represents no value.
    * @default 'any'
    */
   unknownType?: 'any' | 'unknown' | 'void';
   /**
-   * Which type to use for empty schema values
+   * Which type to use for empty schema values.
+   * - 'any' allows any value.
+   * - 'unknown' requires type narrowing before use.
+   * - 'void' represents no value.
    * @default `unknownType`
    */
   emptySchemaType?: 'any' | 'unknown' | 'void';
@@ -1253,7 +1267,7 @@ type Options = {
      */
     name?: (name: ResolveNameParams['name'], type?: ResolveNameParams['type']) => string;
     /**
-     * Receive schema and baseName(propertName) and return FakerMeta array
+     * Receive schema and baseName(propertyName) and return FakerMeta array
      * TODO TODO add docs
      * @beta
      */
@@ -1264,14 +1278,16 @@ type Options = {
     }, defaultSchemas: Schema[]) => Schema[] | undefined;
   };
   /**
-   * Which version of Zod should be used
-   * @default '3
+   * Which version of Zod should be used.
+   * - '3' uses Zod v3.x syntax and features.
+   * - '4' uses Zod v4.x syntax and features.
+   * @default '3'
    */
   version?: '3' | '4';
   /**
    * Use Zod Mini's functional API for better tree-shaking support.
    * When enabled, generates functional syntax (e.g., `z.optional(z.string())`) instead of chainable methods (e.g., `z.string().optional()`).
-   * Requires Zod v4 or later. When `mini: true`, `version` will be set to '4' and `importPath` will default to 'zod/mini'.
+   * Requires Zod v4 or later. When `mini: true`, `version` is set to '4' and `importPath` will default to 'zod/mini'.
    * @default false
    */
   mini?: boolean;
@@ -1312,4 +1328,4 @@ type ResolvedOptions = {
 type PluginZod = PluginFactoryOptions<'plugin-zod', Options, ResolvedOptions, never, ResolvePathOptions>;
 //#endregion
 export { UserPluginWithLifeCycle as a, Schema as i, PluginZod as n, Operation$1 as o, ReactGenerator as r, SchemaObject$1 as s, Options as t };
-//# sourceMappingURL=types-BNtlNlKK.d.ts.map
+//# sourceMappingURL=types-CaZySLsa.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubb/plugin-zod",
-  "version": "4.18.4",
+  "version": "4.18.5",
   "description": "Zod schema generator plugin for Kubb, creating type-safe validation schemas from OpenAPI specifications for runtime data validation.",
   "keywords": [
     "zod",
@@ -69,10 +69,10 @@
   ],
   "dependencies": {
     "@kubb/react-fabric": "0.12.4",
-    "@kubb/core": "4.18.4",
-    "@kubb/oas": "4.18.4",
-    "@kubb/plugin-oas": "4.18.4",
-    "@kubb/plugin-ts": "4.18.4"
+    "@kubb/core": "4.18.5",
+    "@kubb/oas": "4.18.5",
+    "@kubb/plugin-oas": "4.18.5",
+    "@kubb/plugin-ts": "4.18.5"
   },
   "devDependencies": {
     "@asteasolutions/zod-to-openapi": "^8.4.0",

package/src/generators/__snapshots__/createItemUnionWithReadOnly.ts

@@ -0,0 +1,34 @@
+/**
+ * Generated by Kubb (https://kubb.dev/).
+ * Do not edit manually.
+ */
+import { z } from 'zod'
+
+/**
+ * @description Success
+ */
+export const createItem200 = z.lazy(() => item)
+
+/**
+ * @description Item to create
+ */
+export const createItemMutationRequest = z.union([
+  z
+    .lazy(() => itemTypeA)
+    .and(
+      z.object({
+        name: z.string(),
+        type: z.literal('typeA'),
+      }),
+    ),
+  z
+    .lazy(() => itemTypeB)
+    .and(
+      z.object({
+        name: z.string(),
+        type: z.literal('typeB'),
+      }),
+    ),
+])
+
+export const createItemMutationResponse = z.lazy(() => createItem200)

package/src/generators/__snapshots__/createItemUnionWithReadOnly_wrapOutput.ts

@@ -0,0 +1,34 @@
+/**
+ * Generated by Kubb (https://kubb.dev/).
+ * Do not edit manually.
+ */
+import { z } from '@hono/zod-openapi'
+
+/**
+ * @description Success
+ */
+export const createItem200 = z.lazy(() => item)
+
+/**
+ * @description Item to create
+ */
+export const createItemMutationRequest = z.union([
+  z
+    .lazy(() => itemTypeA)
+    .and(
+      z.object({
+        name: z.string(),
+        type: z.literal('typeA'),
+      }),
+    ),
+  z
+    .lazy(() => itemTypeB)
+    .and(
+      z.object({
+        name: z.string(),
+        type: z.literal('typeB'),
+      }),
+    ),
+])
+
+export const createItemMutationResponse = z.lazy(() => createItem200)

package/src/generators/__snapshots__/unionWithReadOnly.ts

@@ -0,0 +1,28 @@
+/**
+ * Generated by Kubb (https://kubb.dev/).
+ * Do not edit manually.
+ */
+import { z } from 'zod'
+
+export const item = z.union([
+  z
+    .lazy(() => itemTypeA)
+    .and(
+      z.object({
+        id: z.optional(z.number().int()),
+        type: z.literal('typeA'),
+        name: z.string(),
+        createdAt: z.optional(z.date()),
+      }),
+    ),
+  z
+    .lazy(() => itemTypeB)
+    .and(
+      z.object({
+        id: z.optional(z.number().int()),
+        type: z.literal('typeB'),
+        name: z.string(),
+        createdAt: z.optional(z.date()),
+      }),
+    ),
+])

package/src/generators/__snapshots__/updateItemUnionWithReadOnly.ts

@@ -0,0 +1,34 @@
+/**
+ * Generated by Kubb (https://kubb.dev/).
+ * Do not edit manually.
+ */
+import { z } from 'zod'
+
+/**
+ * @description Success
+ */
+export const updateItem200 = z.lazy(() => item)
+
+/**
+ * @description Item to update
+ */
+export const updateItemMutationRequest = z.union([
+  z
+    .lazy(() => itemTypeA)
+    .and(
+      z.object({
+        name: z.string(),
+        type: z.literal('typeA'),
+      }),
+    ),
+  z
+    .lazy(() => itemTypeB)
+    .and(
+      z.object({
+        name: z.string(),
+        type: z.literal('typeB'),
+      }),
+    ),
+])
+
+export const updateItemMutationResponse = z.lazy(() => updateItem200)

package/src/generators/__snapshots__/updateItemUnionWithReadOnly_wrapOutput.ts

@@ -0,0 +1,34 @@
+/**
+ * Generated by Kubb (https://kubb.dev/).
+ * Do not edit manually.
+ */
+import { z } from '@hono/zod-openapi'
+
+/**
+ * @description Success
+ */
+export const updateItem200 = z.lazy(() => item)
+
+/**
+ * @description Item to update
+ */
+export const updateItemMutationRequest = z.union([
+  z
+    .lazy(() => itemTypeA)
+    .and(
+      z.object({
+        name: z.string(),
+        type: z.literal('typeA'),
+      }),
+    ),
+  z
+    .lazy(() => itemTypeB)
+    .and(
+      z.object({
+        name: z.string(),
+        type: z.literal('typeB'),
+      }),
+    ),
+])
+
+export const updateItemMutationResponse = z.lazy(() => updateItem200)

package/src/generators/zodGenerator.tsx

@@ -40,7 +40,27 @@ export const zodGenerator = createReactGenerator<PluginZod>({
       .flat()
       .filter(Boolean)
 
-    const mapOperationSchema = ({ name, schema: schemaObject, description, keysToOmit, ...options }: OperationSchemaType) => {
+    const mapOperationSchema = ({ name, schema: schemaOriginal, description, keysToOmit: keysToOmitOriginal, ...options }: OperationSchemaType) => {
+      let schemaObject = schemaOriginal
+      let keysToOmit = keysToOmitOriginal
+
+      if ((schemaOriginal.anyOf || schemaOriginal.oneOf) && keysToOmitOriginal && keysToOmitOriginal.length > 0) {
+        schemaObject = structuredClone(schemaOriginal)
+
+        // Remove $ref so the schema parser generates inline schema instead of a reference
+        delete schemaObject.$ref
+
+        for (const key of keysToOmitOriginal) {
+          delete schemaObject.properties?.[key]
+        }
+
+        if (Array.isArray(schemaObject.required)) {
+          schemaObject.required = schemaObject.required.filter((key) => !keysToOmitOriginal.includes(key))
+        }
+
+        keysToOmit = undefined
+      }
+
       const hasProperties = Object.keys(schemaObject || {}).length > 0
       const hasDefaults = Object.values(schemaObject.properties || {}).some((prop) => prop && Object.hasOwn(prop, 'default'))
 

package/src/types.ts

@@ -10,7 +10,7 @@ export type Options = {
   output?: Output<Oas>
   /**
    * Define which contentType should be used.
-   * By default, the first JSON valid mediaType will be used
+   * By default, the first JSON valid mediaType is used
    */
   contentType?: contentType
   /**
@@ -31,26 +31,37 @@ export type Options = {
   override?: Array<Override<ResolvedOptions>>
   /**
    * Path to Zod
-   * It will be used as `import { z } from '${importPath}'`.
-   * It allows both relative and absolute path.
-   * the path will be applied as is, so relative path should be based on the file being generated.
+   * It used as `import { z } from '${importPath}'`.
+   * Accepts relative and absolute paths.
+   * Path is used as-is; relative paths are based on the generated file location.
    * @default 'zod'
    */
   importPath?: string
 
   /**
-   * Choose to use `date` or `datetime` as JavaScript `Date` instead of `string`.
-   * False will fallback on a simple z.string() format
-   * @default 'string' 'stringOffset' will become the default in Kubb v3
+   * Choose to use date or datetime as JavaScript Date instead of string.
+   * - false falls back to a simple z.string() format.
+   * - 'string' uses z.string().datetime() for datetime validation.
+   * - 'stringOffset' uses z.string().datetime({ offset: true }) for datetime with timezone offset validation.
+   * - 'stringLocal' uses z.string().datetime({ local: true }) for local datetime validation.
+   * - 'date' uses z.date() for JavaScript Date objects.
+   * @default 'string'
+   * @note 'stringOffset' will become the default in Kubb v3.
    */
   dateType?: false | 'string' | 'stringOffset' | 'stringLocal' | 'date'
   /**
-   * Which type to use when the Swagger/OpenAPI file is not providing more information
+   * Which type to use when the Swagger/OpenAPI file is not providing more information.
+   * - 'any' allows any value.
+   * - 'unknown' requires type narrowing before use.
+   * - 'void' represents no value.
    * @default 'any'
    */
   unknownType?: 'any' | 'unknown' | 'void'
   /**
-   * Which type to use for empty schema values
+   * Which type to use for empty schema values.
+   * - 'any' allows any value.
+   * - 'unknown' requires type narrowing before use.
+   * - 'void' represents no value.
    * @default `unknownType`
    */
   emptySchemaType?: 'any' | 'unknown' | 'void'
@@ -81,7 +92,7 @@ export type Options = {
      */
     name?: (name: ResolveNameParams['name'], type?: ResolveNameParams['type']) => string
     /**
-     * Receive schema and baseName(propertName) and return FakerMeta array
+     * Receive schema and baseName(propertyName) and return FakerMeta array
      * TODO TODO add docs
      * @beta
      */
@@ -95,14 +106,16 @@ export type Options = {
     ) => Schema[] | undefined
   }
   /**
-   * Which version of Zod should be used
-   * @default '3
+   * Which version of Zod should be used.
+   * - '3' uses Zod v3.x syntax and features.
+   * - '4' uses Zod v4.x syntax and features.
+   * @default '3'
    */
   version?: '3' | '4'
   /**
    * Use Zod Mini's functional API for better tree-shaking support.
    * When enabled, generates functional syntax (e.g., `z.optional(z.string())`) instead of chainable methods (e.g., `z.string().optional()`).
-   * Requires Zod v4 or later. When `mini: true`, `version` will be set to '4' and `importPath` will default to 'zod/mini'.
+   * Requires Zod v4 or later. When `mini: true`, `version` is set to '4' and `importPath` will default to 'zod/mini'.
    * @default false
    */
   mini?: boolean