hono-takibi 0.8.7 → 0.9.0

package/dist/cli/index.d.ts

@@ -1,7 +1,34 @@
 /**
  * CLI entry point for `hono-takibi`.
  *
- * @returns A `Result` containing help text or CLI execution result.
+ * Executes the CLI flow: parse args → optional help → validate options → run generator (`takibi`) → return result.
+ *
+ * ```mermaid
+ * flowchart TD
+ *   A["Start honoTakibi()"] --> B["args = process.argv.slice(2)"]
+ *   B --> C{"isHelpRequested(args) ?"}
+ *   C -->|Yes| D["return { ok:true, value: HELP_TEXT }"]
+ *   C -->|No| E["cliResult = parseCli(args)"]
+ *   E --> F{"cliResult.ok ?"}
+ *   F -->|No| G["return { ok:false, error: cliResult.error }"]
+ *   F -->|Yes| H["cli = cliResult.value"]
+ *   H --> I["takibiResult = await takibi(cli.input, cli.output, ...options)"]
+ *   I --> J{"takibiResult.ok ?"}
+ *   J -->|No| K["return { ok:false, error: takibiResult.error }"]
+ *   J -->|Yes| L["return { ok:true, value: takibiResult.value }"]
+ * ```
+ *
+ * **Options**
+ * - `--export-type`        Export TypeScript type aliases
+ * - `--export-schema`      Export Zod schema objects
+ * - `--template`           Generate app file and handler stubs
+ * - `--test`               Generate empty `*.test.ts` files
+ * - `--base-path <path>`   API prefix (default: `/`)
+ * - `-h, --help`           Show help and exit
+ *
+ * @returns A Result-like object:
+ * - `{ ok: true, value: string }` with either help text or generation message
+ * - `{ ok: false, error: string }` on validation or generation errors
  */
 export declare function honoTakibi(): Promise<{
     ok: true;

package/dist/cli/index.js

@@ -1,4 +1,3 @@
-import { asyncAndThen } from '../result/index.js';
 import { parseCli } from '../utils/index.js';
 import { takibi } from './takibi.js';
 const HELP_TEXT = `Usage: hono-takibi <input.{yaml,json,tsp}> -o <routes.ts> [options]
@@ -13,7 +12,34 @@ Options:
 /**
  * CLI entry point for `hono-takibi`.
  *
- * @returns A `Result` containing help text or CLI execution result.
+ * Executes the CLI flow: parse args → optional help → validate options → run generator (`takibi`) → return result.
+ *
+ * ```mermaid
+ * flowchart TD
+ *   A["Start honoTakibi()"] --> B["args = process.argv.slice(2)"]
+ *   B --> C{"isHelpRequested(args) ?"}
+ *   C -->|Yes| D["return { ok:true, value: HELP_TEXT }"]
+ *   C -->|No| E["cliResult = parseCli(args)"]
+ *   E --> F{"cliResult.ok ?"}
+ *   F -->|No| G["return { ok:false, error: cliResult.error }"]
+ *   F -->|Yes| H["cli = cliResult.value"]
+ *   H --> I["takibiResult = await takibi(cli.input, cli.output, ...options)"]
+ *   I --> J{"takibiResult.ok ?"}
+ *   J -->|No| K["return { ok:false, error: takibiResult.error }"]
+ *   J -->|Yes| L["return { ok:true, value: takibiResult.value }"]
+ * ```
+ *
+ * **Options**
+ * - `--export-type`        Export TypeScript type aliases
+ * - `--export-schema`      Export Zod schema objects
+ * - `--template`           Generate app file and handler stubs
+ * - `--test`               Generate empty `*.test.ts` files
+ * - `--base-path <path>`   API prefix (default: `/`)
+ * - `-h, --help`           Show help and exit
+ *
+ * @returns A Result-like object:
+ * - `{ ok: true, value: string }` with either help text or generation message
+ * - `{ ok: false, error: string }` on validation or generation errors
  */
 export async function honoTakibi() {
     // Slice the arguments to remove the first two (node and script path)
@@ -27,10 +53,17 @@ export async function honoTakibi() {
             value: HELP_TEXT,
         };
     }
-    return await asyncAndThen(parseCli(args), async (cli) => asyncAndThen(await takibi(cli.input, cli.output, cli.exportSchema ?? false, cli.exportType ?? false, cli.template ?? false, cli.test ?? false, cli.basePath), async (result) => {
-        return {
-            ok: true,
-            value: result,
-        };
-    }));
+    const cliResult = parseCli(args);
+    if (!cliResult.ok) {
+        return { ok: false, error: cliResult.error };
+    }
+    const cli = cliResult.value;
+    const takibiResult = await takibi(cli.input, cli.output, cli.exportSchema ?? false, cli.exportType ?? false, cli.template ?? false, cli.test ?? false, cli.basePath);
+    if (!takibiResult.ok) {
+        return { ok: false, error: takibiResult.error };
+    }
+    return {
+        ok: true,
+        value: takibiResult.value,
+    };
 }

package/dist/cli/takibi.d.ts

@@ -1,6 +1,41 @@
 /**
  * Generates TypeScript code from an OpenAPI spec and optional templates.
  *
+ * ```mermaid
+ * flowchart TD
+ *   A["takibi(input, output, flags)"] --> B["openAPIResult = parseOpenAPI(input)"]
+ *   B --> C{"openAPIResult.ok ?"}
+ *   C -->|No| D["return { ok:false, error: openAPIResult.error }"]
+ *   C -->|Yes| E["openAPI = openAPIResult.value"]
+ *   E --> F["honoResult = fmt(zodOpenAPIHono(openAPI, exportSchema, exportType))"]
+ *   F --> G{"honoResult.ok ?"}
+ *   G -->|No| H["return { ok:false, error: honoResult.error }"]
+ *   G -->|Yes| I["mkdirResult = mkdir(dirname(output))"]
+ *   I --> J{"mkdirResult.ok ?"}
+ *   J -->|No| K["return { ok:false, error: mkdirResult.error }"]
+ *   J -->|Yes| L["writeResult = writeFile(output, honoResult.value)"]
+ *   L --> M{"writeResult.ok ?"}
+ *   M -->|No| N["return { ok:false, error: writeResult.error }"]
+ *   M -->|Yes| O{"template && output includes '/' ?"}
+ *   O -->|No| P["return { ok:true, value: 'Generated code written to ' + output }"]
+ *   O -->|Yes| Q["appResult = fmt(app(openAPI, output, basePath))"]
+ *   Q --> R{"appResult.ok ?"}
+ *   R -->|No| S["return { ok:false, error: appResult.error }"]
+ *   R -->|Yes| T["dir = dirname(output)"]
+ *   T --> U["readdirResult = readdir(dir)"]
+ *   U --> V{"readdirResult.ok ?"}
+ *   V -->|No| W["return { ok:false, error: readdirResult.error }"]
+ *   V -->|Yes| X["files = readdirResult.value"]
+ *   X --> Y["target = join(dir, files includes 'index.ts' ? 'main.ts' : 'index.ts')"]
+ *   Y --> Z["writeResult2 = writeFile(target, appResult.value)"]
+ *   Z --> ZA{"writeResult2.ok ?"}
+ *   ZA -->|No| ZB["return { ok:false, error: writeResult2.error }"]
+ *   ZA -->|Yes| ZC["handlerResult = zodOpenapiHonoHandler(openAPI, output, test)"]
+ *   ZC --> ZD{"handlerResult.ok ?"}
+ *   ZD -->|No| ZE["return { ok:false, error: handlerResult.error }"]
+ *   ZD -->|Yes| ZF["return { ok:true, value: 'Generated code and template files written' }"]
+ * ```
+ *
  * @param input - Input OpenAPI file (`.yaml`, `.json`, or `.tsp`).
  * @param output - Output `.ts` file path.
  * @param exportSchema - Whether to export schemas.

package/dist/cli/takibi.js

@@ -1,13 +1,48 @@
 import path from 'node:path';
 import { fmt } from '../format/index.js';
-import { mkdir, writeFile } from '../fsp/index.js';
+import { mkdir, readdir, writeFile } from '../fsp/index.js';
+import { app } from '../generator/zod-openapi-hono/app/index.js';
+import { zodOpenapiHonoHandler } from '../generator/zod-openapi-hono/handler/zod-openapi-hono-handler.js';
 import zodOpenAPIHono from '../generator/zod-openapi-hono/openapi/index.js';
 import { parseOpenAPI } from '../openapi/index.js';
-import { asyncAndThen } from '../result/index.js';
-import { templateCode } from './template-code.js';
 /**
  * Generates TypeScript code from an OpenAPI spec and optional templates.
  *
+ * ```mermaid
+ * flowchart TD
+ *   A["takibi(input, output, flags)"] --> B["openAPIResult = parseOpenAPI(input)"]
+ *   B --> C{"openAPIResult.ok ?"}
+ *   C -->|No| D["return { ok:false, error: openAPIResult.error }"]
+ *   C -->|Yes| E["openAPI = openAPIResult.value"]
+ *   E --> F["honoResult = fmt(zodOpenAPIHono(openAPI, exportSchema, exportType))"]
+ *   F --> G{"honoResult.ok ?"}
+ *   G -->|No| H["return { ok:false, error: honoResult.error }"]
+ *   G -->|Yes| I["mkdirResult = mkdir(dirname(output))"]
+ *   I --> J{"mkdirResult.ok ?"}
+ *   J -->|No| K["return { ok:false, error: mkdirResult.error }"]
+ *   J -->|Yes| L["writeResult = writeFile(output, honoResult.value)"]
+ *   L --> M{"writeResult.ok ?"}
+ *   M -->|No| N["return { ok:false, error: writeResult.error }"]
+ *   M -->|Yes| O{"template && output includes '/' ?"}
+ *   O -->|No| P["return { ok:true, value: 'Generated code written to ' + output }"]
+ *   O -->|Yes| Q["appResult = fmt(app(openAPI, output, basePath))"]
+ *   Q --> R{"appResult.ok ?"}
+ *   R -->|No| S["return { ok:false, error: appResult.error }"]
+ *   R -->|Yes| T["dir = dirname(output)"]
+ *   T --> U["readdirResult = readdir(dir)"]
+ *   U --> V{"readdirResult.ok ?"}
+ *   V -->|No| W["return { ok:false, error: readdirResult.error }"]
+ *   V -->|Yes| X["files = readdirResult.value"]
+ *   X --> Y["target = join(dir, files includes 'index.ts' ? 'main.ts' : 'index.ts')"]
+ *   Y --> Z["writeResult2 = writeFile(target, appResult.value)"]
+ *   Z --> ZA{"writeResult2.ok ?"}
+ *   ZA -->|No| ZB["return { ok:false, error: writeResult2.error }"]
+ *   ZA -->|Yes| ZC["handlerResult = zodOpenapiHonoHandler(openAPI, output, test)"]
+ *   ZC --> ZD{"handlerResult.ok ?"}
+ *   ZD -->|No| ZE["return { ok:false, error: handlerResult.error }"]
+ *   ZD -->|Yes| ZF["return { ok:true, value: 'Generated code and template files written' }"]
+ * ```
+ *
  * @param input - Input OpenAPI file (`.yaml`, `.json`, or `.tsp`).
  * @param output - Output `.ts` file path.
  * @param exportSchema - Whether to export schemas.
@@ -18,15 +53,47 @@ import { templateCode } from './template-code.js';
  * @returns A `Result` containing a success message or an error string.
  */
 export async function takibi(input, output, exportSchema, exportType, template, test, basePath) {
-    return await asyncAndThen(await parseOpenAPI(input), async (openAPI) => asyncAndThen(await fmt(zodOpenAPIHono(openAPI, exportSchema, exportType)), async (code) => asyncAndThen(await mkdir(path.dirname(output)), async () => asyncAndThen(await writeFile(output, code), async () => template && output.includes('/')
-        ? asyncAndThen(await templateCode(openAPI, output, test, basePath), async () => {
-            return {
-                ok: true,
-                value: 'Generated code and template files written',
-            };
-        })
-        : {
-            ok: true,
-            value: `Generated code written to ${output}`,
-        }))));
+    const openAPIResult = await parseOpenAPI(input);
+    if (!openAPIResult.ok) {
+        return { ok: false, error: openAPIResult.error };
+    }
+    const openAPI = openAPIResult.value;
+    const honoResult = await fmt(zodOpenAPIHono(openAPI, exportSchema, exportType));
+    if (!honoResult.ok) {
+        return { ok: false, error: honoResult.error };
+    }
+    const mkdirResult = await mkdir(path.dirname(output));
+    if (!mkdirResult.ok) {
+        return { ok: false, error: mkdirResult.error };
+    }
+    const writeResult = await writeFile(output, honoResult.value);
+    if (!writeResult.ok) {
+        return { ok: false, error: writeResult.error };
+    }
+    if (template && output.includes('/')) {
+        const appResult = await fmt(app(openAPI, output, basePath));
+        if (!appResult.ok) {
+            return { ok: false, error: appResult.error };
+        }
+        const dir = path.dirname(output);
+        const readdirResult = await readdir(dir);
+        if (!readdirResult.ok) {
+            return { ok: false, error: readdirResult.error };
+        }
+        const files = readdirResult.value;
+        const target = path.join(dir, files.includes('index.ts') ? 'main.ts' : 'index.ts');
+        const writeResult = await writeFile(target, appResult.value);
+        if (!writeResult.ok) {
+            return { ok: false, error: writeResult.error };
+        }
+        const handlerResult = await zodOpenapiHonoHandler(openAPI, output, test);
+        if (!handlerResult.ok) {
+            return { ok: false, error: handlerResult.error };
+        }
+        return { ok: true, value: 'Generated code and template files written' };
+    }
+    return {
+        ok: true,
+        value: `Generated code written to ${output}`,
+    };
 }

package/dist/generator/zod-openapi-hono/handler/zod-openapi-hono-handler.d.ts

@@ -1,5 +1,4 @@
 import type { OpenAPI } from '../../../openapi/index.js';
-import type { Result } from '../../../result/index.js';
 /**
  * Generates route handler files for a Hono app using Zod and OpenAPI.
  *
@@ -8,4 +7,10 @@ import type { Result } from '../../../result/index.js';
  * @param test - Whether to generate corresponding empty test files.
  * @returns A `Result` indicating success or error with message.
  */
-export declare function zodOpenapiHonoHandler(openapi: OpenAPI, output: string, test: boolean): Promise<Result<void, string>>;
+export declare function zodOpenapiHonoHandler(openapi: OpenAPI, output: string, test: boolean): Promise<{
+    ok: true;
+    value: undefined;
+} | {
+    ok: false;
+    error: string;
+}>;

package/dist/generator/zod-openapi-hono/openapi/components/index.js

@@ -32,9 +32,9 @@ export function componentsCode(components, exportSchema, exportType) {
         // 4.1 get schema definition corresponding to schema name
         const schema = schemas[schemaName];
         // 4.2 generate zod schema
-        const zodSchema = zodToOpenAPI(schema);
+        const z = zodToOpenAPI(schema);
         // 4.3 generate zod schema definition
-        return zodToOpenAPISchema(schemaName, zodSchema, exportSchema, exportType);
+        return zodToOpenAPISchema(schemaName, z, exportSchema, exportType);
     })
         .join('\n\n');
     // 5. return code

package/dist/generator/zod-openapi-hono/openapi/route/params/params-object.js

@@ -16,8 +16,6 @@ import { queryParameter } from './index.js';
  */
 export function paramsObject(parameters) {
     return parameters.reduce((acc, param) => {
-        // const z = zod(param.schema)
-        const optionalSuffix = param.required ? '' : '.optional()';
         // path params are generated with the param name
         const baseSchema = param.in
             ? zodToOpenAPI(param.schema, param.name, param.in)
@@ -27,9 +25,9 @@ export function paramsObject(parameters) {
             acc[param.in] = {};
         }
         // queryParameter check
-        const zodSchema = queryParameter(baseSchema, param);
+        const z = queryParameter(baseSchema, param);
         // Add parameter to its section
-        acc[param.in][getToSafeIdentifier(param.name)] = `${zodSchema}${optionalSuffix}`;
+        acc[param.in][getToSafeIdentifier(param.name)] = `${z}${param.required ? '' : '.optional()'}`;
         return acc;
     }, {});
 }

package/dist/generator/zod-openapi-hono/openapi/route/params/request-parameter.js

@@ -38,9 +38,9 @@ export function requestParameter(parameters, body) {
             const z = zodToOpenAPI(schema);
             uniqueSchemas.set(z, z);
         }
-        const request_body_required = body.required ?? false;
+        const required = body.required ?? false;
         const [firstSchema] = uniqueSchemas.values();
-        const requestBodyCode = requestBody(request_body_required, body.content, firstSchema);
+        const requestBodyCode = requestBody(required, body.content, firstSchema);
         if (params) {
             return params.replace('request:{', `request:{${requestBodyCode}`);
         }

package/dist/generator/zod-openapi-hono/openapi/route/request/body/index.js

@@ -25,7 +25,7 @@ export function requestBody(required, content, schema) {
                 contentParts.push(`'${contentType}':{schema:${schema}}`);
             }
         }
-        return `body:{required:${required},content:{${contentParts.join(',')}},},`;
+        return `body:{required:${required},content:{${contentParts.join(',')}}},`;
     }
     return '';
 }

package/dist/generator/zod-openapi-hono/openapi/route/response/index.js

@@ -29,7 +29,7 @@ export function response(responses) {
             const contentParts = [];
             for (const contentType of contentTypes) {
                 const content = response.content[contentType];
-                const zodSchema = zodToOpenAPI(content.schema);
+                const z = zodToOpenAPI(content.schema);
                 const examples = content.examples;
                 const exampleString = examples && Object.keys(examples).length > 0
                     ? `,examples:{${Object.entries(examples)
@@ -43,9 +43,9 @@ export function response(responses) {
                     })
                         .join(',')}}`
                     : '';
-                contentParts.push(`'${contentType}':{schema:${zodSchema}${exampleString}}`);
+                contentParts.push(`'${contentType}':{schema:${z}${exampleString}}`);
             }
-            return `${code}:{description:'${escapeStringLiteral(response.description ?? '')}',content:{${contentParts.join(',')}},},`;
+            return `${code}:{description:'${escapeStringLiteral(response.description ?? '')}',content:{${contentParts.join(',')}}},`;
         }
     });
     // 3.combine all response definitions

package/dist/generator/zod-to-openapi/index.js

@@ -6,30 +6,20 @@ import { integer } from './z/integer.js';
 import { number } from './z/number.js';
 import { object } from './z/object.js';
 import { string } from './z/string.js';
+// Test run
+// pnpm vitest run ./src/generator/zod-to-openapi/index.test.ts
 export function zodToOpenAPI(schema, paramName, paramIn) {
     if (schema === undefined)
         throw new Error('hono-takibi: only #/components/schemas/* is supported');
     // ref
     if (schema.$ref) {
-        if (Boolean(schema.$ref) === true) {
-            return wrap(refSchema(schema.$ref), schema, paramName, paramIn);
-        }
-        if (schema.type === 'array' && Boolean(schema.items?.$ref)) {
-            if (schema.items?.$ref) {
-                const ref = wrap(refSchema(schema.items.$ref), schema.items);
-                return `z.array(${ref})`;
-            }
-            const z = 'z.array(z.any())';
-            return wrap(z, schema, paramName, paramIn);
-        }
-        const z = 'z.any()';
-        return wrap(z, schema, paramName, paramIn);
+        return wrap(refSchema(schema.$ref), schema, paramName, paramIn);
     }
     /* combinators */
     // allOf
     if (schema.allOf) {
         if (!schema.allOf || schema.allOf.length === 0) {
-            return wrap('z.any()', schema);
+            return wrap('z.any()', schema, paramName, paramIn);
         }
         const { schemas, nullable } = schema.allOf.reduce((acc, s) => {
             const isOnlyNullable = (typeof s === 'object' && s.type === 'null') ||
@@ -42,7 +32,7 @@ export function zodToOpenAPI(schema, paramName, paramIn) {
             }
             const z = zodToOpenAPI(s, paramName, paramIn);
             return {
-                schemas: [...acc.schemas, wrap(z, s)],
+                schemas: [...acc.schemas, z],
                 nullable: acc.nullable,
             };
         }, {
@@ -62,18 +52,18 @@ export function zodToOpenAPI(schema, paramName, paramIn) {
     // anyOf
     if (schema.anyOf) {
         if (!schema.anyOf || schema.anyOf.length === 0) {
-            return 'z.any()';
+            return wrap('z.any()', schema, paramName, paramIn);
         }
         const schemas = schema.anyOf.map((subSchema) => {
             return zodToOpenAPI(subSchema, paramName, paramIn);
         });
         const z = `z.union([${schemas.join(',')}])`;
-        return wrap(z, schema);
+        return wrap(z, schema, paramName, paramIn);
     }
     // oneOf
     if (schema.oneOf) {
         if (!schema.oneOf || schema.oneOf.length === 0) {
-            return 'z.any()';
+            return wrap('z.any()', schema, paramName, paramIn);
         }
         const schemas = schema.oneOf.map((schema) => {
             return zodToOpenAPI(schema, paramName, paramIn);
@@ -84,6 +74,7 @@ export function zodToOpenAPI(schema, paramName, paramIn) {
         // const z = discriminator
         //   ? `z.discriminatedUnion('${discriminator}',[${schemas.join(',')}])`
         //   : `z.union([${schemas.join(',')}])`
+        // return wrap(z, schema, paramName, paramIn)
         const z = `z.union([${schemas.join(',')}])`;
         return wrap(z, schema, paramName, paramIn);
     }
@@ -91,14 +82,16 @@ export function zodToOpenAPI(schema, paramName, paramIn) {
     if (schema.not) {
         if (typeof schema.not === 'object' && schema.not.type && typeof schema.not.type === 'string') {
             const predicate = `(v) => typeof v !== '${schema.not.type}'`;
-            return `z.any().refine(${predicate})`;
+            const z = `z.any().refine(${predicate})`;
+            return wrap(z, schema, paramName, paramIn);
         }
         if (typeof schema.not === 'object' && Array.isArray(schema.not.enum)) {
             const list = JSON.stringify(schema.not.enum);
             const predicate = `(v) => !${list}.includes(v)`;
-            return `z.any().refine(${predicate})`;
+            const z = `z.any().refine(${predicate})`;
+            return wrap(z, schema, paramName, paramIn);
         }
-        return 'z.any()';
+        return wrap('z.any()', schema, paramName, paramIn);
     }
     // const
     if (schema.const) {

package/dist/generator/zod-to-openapi/z/array.d.ts

@@ -1,2 +1,50 @@
 import type { Schema } from '../../../openapi/index.js';
+/**
+ * Converts an OpenAPI/JSON Schema `array` definition into a Zod schema string.
+ *
+ * ### Conversion rules
+ * ```mermaid
+ * flowchart TD
+ *   A["array(schema)"] --> B[const item =]
+ *   B --> C{schema.items?.$ref}
+ *   C -- "Yes" --> D["refSchema(schema.items.$ref)"]
+ *   C -- "No"  --> E{schema.items}
+ *   E -- "Yes" --> F["zodToOpenAPI(schema.items)"]
+ *   E -- "No"  --> G["z.any()"]
+ *   D --> B
+ *   F --> B
+ *   G --> B
+ *   B --> I["const z = z.array(${item})"]
+ *   I --> J{"typeof schema.minItems === number && typeof schema.maxItems === number"}
+ *   J -- "Yes" --> K{"schema.minItems === schema.maxItems"}
+ *   K -- "Yes" --> L["${z}.length(${schema.minItems})"]
+ *   K -- "No"  --> M["${z}.min(${schema.minItems}).max(${schema.maxItems})"]
+ *   J -- "No"  --> N{"typeof schema.minItems === number"}
+ *   N -- "Yes" --> O["${z}.min(${schema.minItems})"]
+ *   N -- "No"  --> P{"typeof schema.maxItems === number"}
+ *   P -- "Yes" --> Q["${z}.max(${schema.maxItems})"]
+ *   P -- "No"  --> R[z]
+ * ```
+ *
+ * @param schema - OpenAPI or JSON Schema object representing an array type.
+ *                 - `items` may be a `$ref` or an inline schema.
+ *                 - `minItems` / `maxItems` control `.min()`, `.max()`, or `.length()`.
+ * @returns Zod schema string for the array, e.g. `z.array(z.string()).min(1).max(5)`.
+ *
+ * @remarks
+ * - Does not currently handle tuple schemas (`items: Schema[]` or `prefixItems`).
+ * - Does not handle `uniqueItems`, `contains`, `minContains`, or `maxContains`.
+ * - Nullable arrays should be wrapped at a higher level (e.g. via `wrap()`).
+ *
+ * @example
+ * ```ts
+ * array({
+ *   type: 'array',
+ *   items: { type: 'string' },
+ *   minItems: 1,
+ *   maxItems: 3
+ * })
+ * // → "z.array(z.string()).min(1).max(3)"
+ * ```
+ */
 export declare function array(schema: Schema): string;

package/dist/generator/zod-to-openapi/z/array.js

@@ -1,17 +1,68 @@
+import { refSchema } from '../../../utils/index.js';
 import { zodToOpenAPI } from '../index.js';
+/**
+ * Converts an OpenAPI/JSON Schema `array` definition into a Zod schema string.
+ *
+ * ### Conversion rules
+ * ```mermaid
+ * flowchart TD
+ *   A["array(schema)"] --> B[const item =]
+ *   B --> C{schema.items?.$ref}
+ *   C -- "Yes" --> D["refSchema(schema.items.$ref)"]
+ *   C -- "No"  --> E{schema.items}
+ *   E -- "Yes" --> F["zodToOpenAPI(schema.items)"]
+ *   E -- "No"  --> G["z.any()"]
+ *   D --> B
+ *   F --> B
+ *   G --> B
+ *   B --> I["const z = z.array(${item})"]
+ *   I --> J{"typeof schema.minItems === number && typeof schema.maxItems === number"}
+ *   J -- "Yes" --> K{"schema.minItems === schema.maxItems"}
+ *   K -- "Yes" --> L["${z}.length(${schema.minItems})"]
+ *   K -- "No"  --> M["${z}.min(${schema.minItems}).max(${schema.maxItems})"]
+ *   J -- "No"  --> N{"typeof schema.minItems === number"}
+ *   N -- "Yes" --> O["${z}.min(${schema.minItems})"]
+ *   N -- "No"  --> P{"typeof schema.maxItems === number"}
+ *   P -- "Yes" --> Q["${z}.max(${schema.maxItems})"]
+ *   P -- "No"  --> R[z]
+ * ```
+ *
+ * @param schema - OpenAPI or JSON Schema object representing an array type.
+ *                 - `items` may be a `$ref` or an inline schema.
+ *                 - `minItems` / `maxItems` control `.min()`, `.max()`, or `.length()`.
+ * @returns Zod schema string for the array, e.g. `z.array(z.string()).min(1).max(5)`.
+ *
+ * @remarks
+ * - Does not currently handle tuple schemas (`items: Schema[]` or `prefixItems`).
+ * - Does not handle `uniqueItems`, `contains`, `minContains`, or `maxContains`.
+ * - Nullable arrays should be wrapped at a higher level (e.g. via `wrap()`).
+ *
+ * @example
+ * ```ts
+ * array({
+ *   type: 'array',
+ *   items: { type: 'string' },
+ *   minItems: 1,
+ *   maxItems: 3
+ * })
+ * // → "z.array(z.string()).min(1).max(3)"
+ * ```
+ */
 export function array(schema) {
-    const array = `z.array(${schema.items ? zodToOpenAPI(schema.items) : 'z.any()'})`;
+    const item = schema.items?.$ref
+        ? refSchema(schema.items.$ref)
+        : schema.items
+            ? zodToOpenAPI(schema.items)
+            : 'z.any()';
+    const z = `z.array(${item})`;
     if (typeof schema.minItems === 'number' && typeof schema.maxItems === 'number') {
-        if (schema.minItems === schema.maxItems) {
-            return `${array}.length(${schema.minItems})`;
-        }
-        return `${array}.min(${schema.minItems}).max(${schema.maxItems})`;
+        return schema.minItems === schema.maxItems
+            ? `${z}.length(${schema.minItems})`
+            : `${z}.min(${schema.minItems}).max(${schema.maxItems})`;
     }
-    if (typeof schema.minItems === 'number') {
-        return `${array}.min(${schema.minItems})`;
-    }
-    if (typeof schema.maxItems === 'number') {
-        return `${array}.max(${schema.maxItems})`;
-    }
-    return array;
+    if (typeof schema.minItems === 'number')
+        return `${z}.min(${schema.minItems})`;
+    if (typeof schema.maxItems === 'number')
+        return `${z}.max(${schema.maxItems})`;
+    return z;
 }

package/dist/generator/zod-to-openapi/z/string.d.ts

@@ -1,3 +1,41 @@
 import type { Schema } from '../../../openapi/index.js';
-/** Build a Zod string schema from an OpenAPI string schema. */
+/**
+ * Builds a Zod string schema from an OpenAPI string schema definition.
+ *
+ * - If `schema.format` exists and matches `FORMAT_STRING`, uses `z.<format>()`; otherwise falls back to `z.string()`
+ * - If `schema.pattern` is set, appends `.regex(...)` using the `regex()` helper
+ * - If `minLength` and `maxLength` are defined and equal, appends `.length(n)`
+ * - Otherwise, appends `.min(n)` and/or `.max(n)` individually
+ * - Returns the concatenated Zod schema string
+ *
+ * ```mermaid
+ * flowchart TD
+ *   A["string(schema)"] --> B["format = schema.format && FORMAT_STRING[format]"]
+ *   B --> C{"Format exists?"}
+ *   C -- "Yes" --> D["o.push(z.${format})"]
+ *   C -- "No"  --> E["o.push(z.string())"]
+ *   D --> F{"Pattern exists?"}
+ *   E --> F
+ *   F -- "Yes" --> G["o.push(regex(schema.pattern))"]
+ *   F -- "No"  --> I
+ *   G --> I{"minLength and maxLength are equal?"}
+ *   I -- "Yes" --> J["o.push(length(minLength))"]
+ *   I -- "No"  --> K{"minLength or maxLength?"}
+ *   K -- "min" --> L["o.push(min(minLength))"]
+ *   K -- "max" --> M["o.push(max(maxLength))"]
+ *   L --> N["return o.join('')"]
+ *   M --> N
+ *   J --> N
+ * ```
+ *
+ * @example
+ * ```ts
+ * // With format, pattern, and minLength
+ * string({ type: 'string', format: 'email', pattern: '^.+@example\\.com$', minLength: 5 })
+ * // => 'z.email().regex(/^.+@example\\.com$/).min(5)'
+ * ```
+ *
+ * @param schema - OpenAPI string schema
+ * @returns Concatenated Zod string schema
+ */
 export declare function string(schema: Schema): string;