hono-takibi 0.9.9997 → 0.9.9999

package/README.md

@@ -4,12 +4,6 @@
 
 ![img](https://raw.githubusercontent.com/nakita628/hono-takibi/refs/heads/main/assets/img/hono-takibi.png)
 
-```bash
-npm install -D hono-takibi
-```
-
-## OpenAPI to Hono Code Generator
-
 **[Hono Takibi](https://www.npmjs.com/package/hono-takibi)** generates type-safe [Hono](https://hono.dev/) code from [OpenAPI](https://www.openapis.org/) / [TypeSpec](https://typespec.io/) specifications.
 
 - OpenAPI schemas to [Zod](https://zod.dev/) schemas
@@ -19,6 +13,10 @@ npm install -D hono-takibi
 - RPC client, mock server, TypeScript types
 - API reference docs with [hono-cli](https://github.com/honojs/cli) commands
 
+```bash
+npm install -D hono-takibi
+```
+
 ## Quick Start
 
 ### CLI
@@ -36,9 +34,7 @@ import { defineConfig } from 'hono-takibi/config'
 
 export default defineConfig({
   input: 'openapi.yaml',
-  'zod-openapi': {
-    output: './src/routes.ts',
-  },
+  output: './src/routes.ts',
 })
 ```
 
@@ -127,13 +123,11 @@ Generate a complete app structure with handler stubs and test files:
 ```ts
 export default defineConfig({
   input: 'openapi.yaml',
-  'zod-openapi': {
-    output: './src/routes.ts',
-    template: {
-      test: true,
-      pathAlias: '@/',
-      testFramework: 'bun', // "vitest" (default) | "vite-plus" | "bun"
-    },
+  output: './src/routes.ts',
+  template: {
+    test: true,
+    pathAlias: '@/',
+    testFramework: 'bun', // "vitest" (default) | "vite-plus" | "bun"
   },
 })
 ```
@@ -201,6 +195,34 @@ export const api = app.openapi(getHealthRoute, getHealthRouteHandler)
 export default app
 ```
 
+#### `define: true`
+
+```ts
+export default defineConfig({
+  input: 'openapi.yaml',
+  output: './src/index.ts',
+  template: { define: true },
+})
+```
+
+```ts
+// src/routes/users.ts
+export const getUsersIdRoute = defineOpenAPIRoute({
+  route: createRoute({
+    method: 'get',
+    path: '/users/{id}',
+    request: { params: z.object({ id: z.string() }) },
+    responses: {
+      200: { description: 'ok', content: { 'application/json': { schema: UserSchema } } },
+    },
+  }),
+  handler: async (c) => {},
+  addRoute: true,
+})
+```
+
+Component schemas go to `components/index.ts` (override with `components.output`). Set `template.output` to change the route directory (default `./src/routes`).
+
 ## Client Library Integrations
 
 Supported: SWR, TanStack Query, Preact Query, Solid Query, Vue Query, Svelte Query, Angular Query, RPC Client.
@@ -210,7 +232,7 @@ export default defineConfig({
   input: 'openapi.yaml',
   'tanstack-query': {
     output: './src/tanstack-query',
-    import: '../client',
+    import: '../lib',
     split: true,
     client: 'client',
   },
@@ -237,7 +259,7 @@ export default defineConfig({
   input: 'openapi.yaml',
   test: {
     output: './src/test.ts',
-    import: '../index',
+    import: '.',
     testFramework: 'bun', // "vitest" (default) | "vite-plus" | "bun"
   },
 })
@@ -254,9 +276,9 @@ export default defineConfig({
 })
 ```
 
-### API Reference Docs
+## API Reference Docs
 
-Generate API reference Markdown with [hono-cli](https://github.com/honojs/cli) `hono request` commands that can be run directly without starting a server:
+Generate API reference Markdown with [hono-cli](https://github.com/honojs/cli) `hono request` commands:
 
 ```ts
 export default defineConfig({
@@ -268,7 +290,7 @@ export default defineConfig({
 })
 ```
 
-To generate `curl` commands instead of `hono request`:
+Set `curl: true` with `baseUrl` to generate `curl` commands for a running server:
 
 ```ts
 export default defineConfig({
@@ -283,212 +305,203 @@ export default defineConfig({
 
 ## Full Config Reference
 
+Some options are mutually exclusive: `output` ↔ `routes`, `components.output` ↔ per-type components, `template.define` ↔ `routeHandler`.
+
 ```ts
-// hono-takibi.config.ts
 import { defineConfig } from 'hono-takibi/config'
 
 export default defineConfig({
-  // OpenAPI spec file (.yaml, .json, or .tsp)
   input: 'openapi.yaml',
 
-  // Base path prefix for all routes
+  output: './src/routes.ts', // single-file mode; with template.define, the app entry (required)
   basePath: '/api',
+  readonly: true,
+  // format: {}, // oxfmt FormatConfig
+
+  template: {
+    test: true,
+    routeHandler: false, // true: RouteHandler exports
+    define: false, // true: defineOpenAPIRoute output
+    // output: './src/routes', // define mode dir (default ./src/routes)
+    pathAlias: '@/',
+    testFramework: 'vitest', // "vitest" | "vite-plus" | "bun"
+  },
 
-  // oxfmt FormatConfig for generated code output
-  // @see https://www.npmjs.com/package/oxfmt
-  // format: {},
-
-  // Main code generation (Zod + OpenAPI + Hono)
-  'zod-openapi': {
-    // Output: use 'output' for single file, or 'routes' for split mode (mutually exclusive)
-    output: './src/routes.ts',
-    readonly: true, // Add 'as const' to generated schemas
-
-    // Template generation (app entry point + handler stubs + tests)
-    template: {
-      test: true, // Generate test files
-      routeHandler: false, // false: inline .openapi() (default), true: RouteHandler exports
-      pathAlias: '@/', // TypeScript path alias for imports
-      testFramework: 'vitest', // "vitest" (default) | "vite-plus" | "bun" — test import source
-    },
+  exportSchemas: true,
+  exportSchemasTypes: true,
+  exportResponses: true,
+  exportParameters: true,
+  exportParametersTypes: true,
+  exportExamples: true,
+  exportRequestBodies: true,
+  exportHeaders: true,
+  exportHeadersTypes: true,
+  exportSecuritySchemes: true,
+  exportLinks: true,
+  exportCallbacks: true,
+  exportPathItems: true,
+  exportMediaTypes: true,
+  exportMediaTypesTypes: true,
+
+  routes: {
+    output: './src/routes',
+    split: true,
+    import: '@packages/routes',
+  },
+
+  webhooks: {
+    output: './src/webhooks',
+    split: true,
+    import: '@packages/webhooks',
+  },
 
-    // Export options (OpenAPI Components Object)
-    exportSchemas: true,
-    exportSchemasTypes: true,
-    exportResponses: true,
-    exportParameters: true,
-    exportParametersTypes: true,
-    exportExamples: true,
-    exportRequestBodies: true,
-    exportHeaders: true,
-    exportHeadersTypes: true,
-    exportSecuritySchemes: true,
-    exportLinks: true,
-    exportCallbacks: true,
-    exportPathItems: true,
-    exportMediaTypes: true,
-    exportMediaTypesTypes: true,
-
-    // Split routes into separate files
-    routes: {
-      output: './src/routes',
+  // `output` (single file) and the per-type fields below (split) are mutually exclusive.
+  // `exportTypes` applies only to schemas / parameters / headers / mediaTypes.
+  components: {
+    output: './src/components/index.ts',
+
+    schemas: {
+      output: './src/schemas',
+      exportTypes: true,
       split: true,
-      import: '@packages/routes',
+      import: '../schemas',
     },
-
-    // Split webhooks into separate files
-    webhooks: {
-      output: './src/webhooks',
+    responses: {
+      output: './src/responses',
       split: true,
-      import: '@packages/webhooks',
+      import: '../responses',
     },
-
-    // Split components into separate files
-    components: {
-      schemas: {
-        output: './src/schemas',
-        exportTypes: true,
-        split: true,
-        import: '../schemas',
-      },
-      responses: {
-        output: './src/responses',
-        split: true,
-        import: '../responses',
-      },
-      parameters: {
-        output: './src/parameters',
-        exportTypes: true,
-        split: true,
-        import: '../parameters',
-      },
-      examples: {
-        output: './src/examples',
-        split: true,
-        import: '../examples',
-      },
-      requestBodies: {
-        output: './src/requestBodies',
-        split: true,
-        import: '../requestBodies',
-      },
-      headers: {
-        output: './src/headers',
-        exportTypes: true,
-        split: true,
-        import: '../headers',
-      },
-      securitySchemes: {
-        output: './src/securitySchemes',
-        split: true,
-        import: '../securitySchemes',
-      },
-      links: {
-        output: './src/links',
-        split: true,
-        import: '../links',
-      },
-      callbacks: {
-        output: './src/callbacks',
-        split: true,
-        import: '../callbacks',
-      },
-      pathItems: {
-        output: './src/pathItems',
-        split: true,
-        import: '../pathItems',
-      },
-      mediaTypes: {
-        output: './src/mediaTypes',
-        exportTypes: true,
-        split: true,
-        import: '../mediaTypes',
-      },
+    parameters: {
+      output: './src/parameters',
+      exportTypes: true,
+      split: true,
+      import: '../parameters',
+    },
+    examples: {
+      output: './src/examples',
+      split: true,
+      import: '../examples',
+    },
+    requestBodies: {
+      output: './src/requestBodies',
+      split: true,
+      import: '../requestBodies',
+    },
+    headers: {
+      output: './src/headers',
+      exportTypes: true,
+      split: true,
+      import: '../headers',
+    },
+    securitySchemes: {
+      output: './src/securitySchemes',
+      split: true,
+      import: '../securitySchemes',
+    },
+    links: {
+      output: './src/links',
+      split: true,
+      import: '../links',
+    },
+    callbacks: {
+      output: './src/callbacks',
+      split: true,
+      import: '../callbacks',
+    },
+    pathItems: {
+      output: './src/pathItems',
+      split: true,
+      import: '../pathItems',
+    },
+    mediaTypes: {
+      output: './src/mediaTypes',
+      exportTypes: true,
+      split: true,
+      import: '../mediaTypes',
     },
   },
 
-  // TypeScript type generation
   type: {
     output: './src/types.ts',
     readonly: true,
   },
 
-  // RPC client generation
   rpc: {
     output: './src/rpc',
-    import: '../client', // Import path for the Hono RPC client
+    import: '../lib',
     split: true,
-    client: 'client', // Export name of the client instance
-    parseResponse: true, // Use parseResponse for type-safe responses
+    client: 'client',
+    parseResponse: true,
+    docs: false, // operation summary/description as JSDoc
   },
 
-  // Client library integrations (SWR, TanStack Query, Preact Query, Solid Query, Vue Query, Svelte Query, Angular Query)
   swr: {
     output: './src/swr',
-    import: '../client',
+    import: '../lib',
     split: true,
     client: 'client',
   },
   'tanstack-query': {
     output: './src/tanstack-query',
-    import: '../client',
+    import: '../lib',
     split: true,
     client: 'client',
   },
   'preact-query': {
     output: './src/preact-query',
-    import: '../client',
+    import: '../lib',
     split: true,
     client: 'client',
   },
   'solid-query': {
     output: './src/solid-query',
-    import: '../client',
+    import: '../lib',
     split: true,
     client: 'client',
   },
   'vue-query': {
     output: './src/vue-query',
-    import: '../client',
+    import: '../lib',
     split: true,
     client: 'client',
   },
   'svelte-query': {
     output: './src/svelte-query',
-    import: '../client',
+    import: '../lib',
     split: true,
     client: 'client',
   },
   'angular-query': {
     output: './src/angular-query',
-    import: '../client',
+    import: '../lib',
     split: true,
     client: 'client',
   },
 
-  // Test generation
   test: {
     output: './src/test.ts',
-    import: '../index', // Import path for the app instance
-    testFramework: 'vitest', // "vitest" (default) | "vite-plus" | "bun" — test import source
+    import: '.',
+    testFramework: 'vitest', // "vitest" | "vite-plus" | "bun"
   },
 
-  // Mock server generation
   mock: {
     output: './src/mock.ts',
   },
 
-  // API reference docs generation
   docs: {
     output: './docs/api.md',
-    entry: 'src/index.ts', // App entry point for hono request commands
-    curl: false, // true: generate curl commands (requires baseUrl), false: hono request (default)
-    baseUrl: 'http://localhost:3000', // Base URL for curl commands (required when curl: true)
+    entry: 'src/index.ts',
+    curl: false, // true: curl commands (requires baseUrl); false: hono request
+    baseUrl: 'http://localhost:3000',
   },
 })
 ```
 
-## Custom Validation Error Messages
+## Vendor Extensions (x-\*)
+
+hono-takibi reads `x-*` vendor extensions on your OpenAPI / JSON Schema to customize the generated Zod. Each extension maps 1:1 to a Zod feature.
+
+### Custom Validation Error Messages
 
 Use `x-*` vendor extensions to attach custom Zod error messages, with **one extension per JSON Schema keyword** (1:1 mapping). The extension name follows the pattern `x-<jsonSchemaKeyword>-message` (e.g. `x-minLength-message`, `x-pattern-message`), plus four generic forms: `x-error-message`, `x-required-message`, `x-const-message`, `x-enum-message`.
 
@@ -508,8 +521,6 @@ z.string({ error: 'Name must be a string' })
   .max(50, { error: 'Name must be at most 50 characters' })
 ```
 
-### Extension Reference
-
 All custom message extensions follow the `x-<keyword>-message` naming convention and map directly to Zod validator error messages.
 
 #### Common (any schema type)
@@ -591,9 +602,9 @@ All custom message extensions follow the `x-<keyword>-message` naming convention
 | `x-unevaluatedProperties-message` | `unevaluatedProperties`         |
 | `x-unevaluatedItems-message`      | `unevaluatedItems`              |
 
-## Behavior Extensions
+### Behavior Extensions
 
-### String Pre-validation Transforms
+#### String Pre-validation Transforms
 
 | Extension       | Generated                     | Value                                   |
 | --------------- | ----------------------------- | --------------------------------------- |
@@ -613,7 +624,7 @@ homepage:
 z.string().trim().pipe(z.url())
 ```
 
-### String Validation Checks
+#### String Validation Checks
 
 | Extension     | Generated                | Value  |
 | ------------- | ------------------------ | ------ |
@@ -630,9 +641,9 @@ slug:
 z.string().lowercase()
 ```
 
-### Preprocess (Input Normalization)
+#### Preprocess
 
-#### `x-preprocess`
+**`x-preprocess`**
 
 ```yaml
 username:
@@ -644,9 +655,9 @@ username:
 z.preprocess((val) => (typeof val === 'string' ? val.trim() : val), z.string())
 ```
 
-### Type Coercion
+#### Type Coercion
 
-#### `x-coerce`
+**`x-coerce`**
 
 ```yaml
 asNumber:
@@ -663,7 +674,7 @@ z.coerce.number()
 z.coerce.date()
 ```
 
-#### `x-stringbool`
+**`x-stringbool`**
 
 ```yaml
 notify:
@@ -688,27 +699,27 @@ notify:
 z.stringbool({ truthy: ['yes', 'on'], falsy: ['no', 'off'], case: 'sensitive' })
 ```
 
-### Codec (Bidirectional Transform)
+#### Codec
 
-#### `x-codec`
+**`x-codec`**
 
 ```yaml
 updatedAt:
   type: string
   format: date-time
-  x-codec: 'z.codec(z.iso.datetime(), z.date(), { decode: (val) => new Date(val), encode: (val) => val.toISOString() })'
+  x-codec: 'z.codec(z.iso.datetime(), z.date(), { decode: (isoString) => new Date(isoString), encode: (date) => date.toISOString() })'
 ```
 
 ```ts
 z.codec(z.iso.datetime(), z.date(), {
-  decode: (val) => new Date(val),
-  encode: (val) => val.toISOString(),
+  decode: (isoString) => new Date(isoString),
+  encode: (date) => date.toISOString(),
 })
 ```
 
-### Custom Validation
+#### Custom Validation
 
-#### `x-refine`
+**`x-refine`**
 
 ```yaml
 password:
@@ -722,7 +733,7 @@ z.string()
   .refine((val) => /[A-Z]/.test(val), { message: 'Password must contain an uppercase letter' })
 ```
 
-#### `x-superRefine`
+**`x-superRefine`**
 
 ```yaml
 normalizedEmail:
@@ -739,9 +750,9 @@ z.email().superRefine((val, ctx) => {
 })
 ```
 
-### Transform & Pipe
+#### Transform & Pipe
 
-#### `x-transform`
+**`x-transform`**
 
 ```yaml
 code:
@@ -753,7 +764,7 @@ code:
 z.string().transform((val) => val.toUpperCase())
 ```
 
-#### `x-pipe`
+**`x-pipe`**
 
 ```yaml
 port:
@@ -765,9 +776,9 @@ port:
 z.string().pipe(z.number().int().positive())
 ```
 
-### Default & Fallback Values
+#### Default & Fallback Values
 
-#### `x-prefault`
+**`x-prefault`**
 
 ```yaml
 greeting:
@@ -779,7 +790,7 @@ greeting:
 z.string().prefault('hello')
 ```
 
-#### `x-catch`
+**`x-catch`**
 
 ```yaml
 retries:
@@ -791,9 +802,9 @@ retries:
 z.int().catch(0)
 ```
 
-### Immutability
+#### Immutability
 
-#### `x-readonly`
+**`x-readonly`**
 
 ```yaml
 config:
@@ -808,9 +819,9 @@ config:
 z.object({ name: z.string() }).readonly()
 ```
 
-### String Content Checks
+#### String Content Checks
 
-#### `x-startsWith` / `x-endsWith` / `x-includes`
+**`x-startsWith` / `x-endsWith` / `x-includes`**
 
 ```yaml
 url:
@@ -827,7 +838,7 @@ z.string().startsWith('https://').endsWith('.com')
 z.string().includes('/api/')
 ```
 
-### Format-Specific Options
+#### Format-Specific Options
 
 ```yaml
 htmlEmail:
@@ -850,23 +861,23 @@ preciseDatetime:
   x-isoOffset: true
 ```
 
-| Extension        | Maps to                         | Values                           |
-| ---------------- | ------------------------------- | -------------------------------- |
-| `x-emailPattern` | `z.email({ pattern })`          | `html5` / `browser` / `unicode`  |
-| `x-emailRegex`   | `z.email({ pattern: /.../ })`   | custom regex string              |
-| `x-uuidVersion`  | `z.uuid({ version })`           | `v1` / `v4` / `v6` / `v7` / `v8` |
-| `x-urlProtocol`  | `z.url({ protocol: /.../ })`    | regex string                     |
-| `x-urlHostname`  | `z.url({ hostname: /.../ })`    | regex string                     |
-| `x-urlNormalize` | `z.url({ normalize })`          | `true` / `false`                 |
-| `x-isoPrecision` | `z.iso.datetime({ precision })` | fractional second digits         |
-| `x-isoOffset`    | `z.iso.datetime({ offset })`    | `true` / `false`                 |
-| `x-isoLocal`     | `z.iso.datetime({ local })`     | `true` / `false`                 |
-| `x-macDelimiter` | `z.mac({ delimiter })`          | `:` / `-` / `.`                  |
-| `x-jwtAlg`       | `z.jwt({ alg })`                | `HS256` etc.                     |
-| `x-hashAlg`      | `z.hash(alg, ...)`              | `sha256` etc.                    |
-| `x-hashEnc`      | `z.hash(alg, { enc })`          | `hex` / `base64` / `base64url`   |
-
-## Branded Types
+| Extension        | Maps to                         | Values                                                |
+| ---------------- | ------------------------------- | ----------------------------------------------------- |
+| `x-emailPattern` | `z.email({ pattern })`          | `html5` / `rfc5322` / `unicode`                       |
+| `x-emailRegex`   | `z.email({ pattern: /.../ })`   | custom regex string                                   |
+| `x-uuidVersion`  | `z.uuid({ version })`           | `v1` / `v2` / `v3` / `v4` / `v5` / `v6` / `v7` / `v8` |
+| `x-urlProtocol`  | `z.url({ protocol: /.../ })`    | regex string                                          |
+| `x-urlHostname`  | `z.url({ hostname: /.../ })`    | regex string                                          |
+| `x-urlNormalize` | `z.url({ normalize })`          | `true` / `false`                                      |
+| `x-isoPrecision` | `z.iso.datetime({ precision })` | fractional second digits                              |
+| `x-isoOffset`    | `z.iso.datetime({ offset })`    | `true` / `false`                                      |
+| `x-isoLocal`     | `z.iso.datetime({ local })`     | `true` / `false`                                      |
+| `x-macDelimiter` | `z.mac({ delimiter })`          | `:` / `-` / `.`                                       |
+| `x-jwtAlg`       | `z.jwt({ alg })`                | `HS256` etc.                                          |
+| `x-hashAlg`      | `z.hash(alg, ...)`              | `sha256` etc.                                         |
+| `x-hashEnc`      | `z.hash(alg, { enc })`          | `hex` / `base64` / `base64url`                        |
+
+### Branded Types (x-brand)
 
 Use the `x-brand` vendor extension to generate [Zod branded types](https://zod.dev/api?id=branded-types), creating nominal types that are structurally identical but semantically distinct: