hono-takibi 0.9.9991 → 0.9.9993

package/README.md

@@ -102,70 +102,6 @@ export const getRoute = createRoute({
 })
 ```
 
-## Custom Validation Error Messages
-
-Use `x-*` vendor extensions to customize Zod error messages:
-
-```yaml
-name:
-  type: string
-  minLength: 1
-  x-error-message: 'Name is required'
-  x-minimum-message: 'Name cannot be empty'
-```
-
-```ts
-// Generated output
-z.string({ error: 'Name is required' }).min(1, { error: 'Name cannot be empty' })
-```
-
-| Extension                     | Applies to                                                        |
-| ----------------------------- | ----------------------------------------------------------------- |
-| `x-error-message`             | Schema constructor (`z.string()`, `z.number()`, `z.enum()`, etc.) |
-| `x-minimum-message`           | `.min()`, `.gte()`                                                |
-| `x-maximum-message`           | `.max()`, `.lte()`                                                |
-| `x-size-message`              | `.length()`                                                       |
-| `x-pattern-message`           | `.regex()`                                                        |
-| `x-multipleOf-message`        | `.multipleOf()`                                                   |
-| `x-enum-error-messages`       | Per-value enum messages (`{ "value": "message" }`)                |
-| `x-anyOf-message`             | `anyOf`                                                           |
-| `x-oneOf-message`             | `oneOf`                                                           |
-| `x-not-message`               | `not`                                                             |
-| `x-propertyNames-message`     | `propertyNames`                                                   |
-| `x-dependentRequired-message` | `dependentRequired`                                               |
-
-## Branded Types
-
-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:
-
-```yaml
-components:
-  schemas:
-    Cat:
-      type: object
-      properties:
-        name:
-          type: string
-      required:
-        - name
-      x-brand: Cat
-    Dog:
-      type: object
-      properties:
-        name:
-          type: string
-      required:
-        - name
-      x-brand: Dog
-```
-
-```ts
-// Generated output
-const CatSchema = z.object({ name: z.string() }).brand<'Cat'>().openapi('Cat')
-
-const DogSchema = z.object({ name: z.string() }).brand<'Dog'>().openapi('Dog')
-```
-
 ## Vite Plugin
 
 Watches your OpenAPI spec and `hono-takibi.config.ts` for changes, then auto-regenerates code on save.
@@ -210,8 +146,6 @@ This generates:
 
 Re-running after updating your OpenAPI spec is safe — your hand-written handler logic and test customizations are preserved. Only new routes are added as stubs.
 
-> **Note:** If you remove a path from your OpenAPI spec and re-run, the corresponding handler and test files will be deleted. Make sure to back up or migrate any custom logic before removing API definitions.
-
 ### Handler Generation Modes
 
 #### `routeHandler: false` (default)
@@ -274,10 +208,6 @@ Supported: SWR, TanStack Query, Preact Query, Solid Query, Vue Query, Svelte Que
 ```ts
 export default defineConfig({
   input: 'openapi.yaml',
-  'zod-openapi': {
-    output: './src/routes.ts',
-    exportSchemas: true,
-  },
   'tanstack-query': {
     output: './src/tanstack-query',
     import: '../client',
@@ -305,9 +235,6 @@ paths:
 ```ts
 export default defineConfig({
   input: 'openapi.yaml',
-  'zod-openapi': {
-    output: './src/routes.ts',
-  },
   test: {
     output: './src/test.ts',
     import: '../index',
@@ -321,10 +248,6 @@ export default defineConfig({
 ```ts
 export default defineConfig({
   input: 'openapi.yaml',
-  'zod-openapi': {
-    output: './src/routes.ts',
-    readonly: true,
-  },
   mock: {
     output: './src/mock.ts',
   },
@@ -338,10 +261,6 @@ Generate API reference Markdown with [hono-cli](https://github.com/honojs/cli) `
 ```ts
 export default defineConfig({
   input: 'openapi.yaml',
-  'zod-openapi': {
-    output: './src/routes.ts',
-    readonly: true,
-  },
   docs: {
     output: './docs/api.md',
     entry: 'src/index.ts',
@@ -354,10 +273,6 @@ To generate `curl` commands instead of `hono request`:
 ```ts
 export default defineConfig({
   input: 'openapi.yaml',
-  'zod-openapi': {
-    output: './src/routes.ts',
-    readonly: true,
-  },
   docs: {
     output: './docs/api.md',
     curl: true,
@@ -368,10 +283,6 @@ export default defineConfig({
 
 ## Full Config Reference
 
-> `split: true` - `output` is a **directory** (many files + `index.ts`).
-> `split` omitted or `false` - `output` is a **single `.ts` file**.
-> `output` and `routes` are **mutually exclusive** in `zod-openapi`.
-
 ```ts
 // hono-takibi.config.ts
 import { defineConfig } from 'hono-takibi/config'
@@ -422,7 +333,14 @@ export default defineConfig({
     routes: {
       output: './src/routes',
       split: true,
-      import: '@packages/routes', // Custom import path (monorepo support)
+      import: '@packages/routes',
+    },
+
+    // Split webhooks into separate files
+    webhooks: {
+      output: './src/webhooks',
+      split: true,
+      import: '@packages/webhooks',
     },
 
     // Split components into separate files
@@ -486,11 +404,6 @@ export default defineConfig({
         split: true,
         import: '../mediaTypes',
       },
-      webhooks: {
-        output: './src/webhooks',
-        split: true,
-        import: '../webhooks',
-      },
     },
   },
 
@@ -575,22 +488,376 @@ export default defineConfig({
 })
 ```
 
-## Projects Using Hono Takibi
+## Custom Validation Error Messages
 
-- **[resend-local](https://github.com/y-hiraoka/resend-local)** — A local emulator for the Resend email API.
+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`.
+
+```yaml
+name:
+  type: string
+  minLength: 1
+  maxLength: 50
+  x-error-message: 'Name must be a string'
+  x-minLength-message: 'Name cannot be empty'
+  x-maxLength-message: 'Name must be at most 50 characters'
+```
 
-## Limitations
+```ts
+z.string({ error: 'Name must be a string' })
+  .min(1, { error: 'Name cannot be empty' })
+  .max(50, { error: 'Name must be at most 50 characters' })
+```
 
-**This package is in active development and may introduce breaking changes without prior notice.**
+### 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)
+
+| Extension            | Applies to                       |
+| -------------------- | -------------------------------- |
+| `x-error-message`    | All schemas (top-level fallback) |
+| `x-required-message` | Required properties              |
+| `x-const-message`    | `const`                          |
+| `x-enum-message`     | `enum`                           |
+
+#### Numeric (number / integer)
+
+| Extension                    | Applies to         |
+| ---------------------------- | ------------------ |
+| `x-minimum-message`          | `minimum`          |
+| `x-maximum-message`          | `maximum`          |
+| `x-exclusiveMinimum-message` | `exclusiveMinimum` |
+| `x-exclusiveMaximum-message` | `exclusiveMaximum` |
+| `x-multipleOf-message`       | `multipleOf`       |
+
+#### String
+
+| Extension             | Applies to                                 |
+| --------------------- | ------------------------------------------ |
+| `x-minLength-message` | `minLength`                                |
+| `x-maxLength-message` | `maxLength`                                |
+| `x-pattern-message`   | `pattern`                                  |
+| `x-length-message`    | Exact length (`minLength` === `maxLength`) |
+
+#### Array
+
+| Extension               | Applies to    |
+| ----------------------- | ------------- |
+| `x-minItems-message`    | `minItems`    |
+| `x-maxItems-message`    | `maxItems`    |
+| `x-uniqueItems-message` | `uniqueItems` |
+| `x-contains-message`    | `contains`    |
+| `x-minContains-message` | `minContains` |
+| `x-maxContains-message` | `maxContains` |
+
+#### Object
+
+| Extension                        | Applies to             |
+| -------------------------------- | ---------------------- |
+| `x-minProperties-message`        | `minProperties`        |
+| `x-maxProperties-message`        | `maxProperties`        |
+| `x-additionalProperties-message` | `additionalProperties` |
+| `x-propertyNames-message`        | `propertyNames`        |
+| `x-patternProperties-message`    | `patternProperties`    |
+| `x-dependentRequired-message`    | `dependentRequired`    |
+| `x-dependentSchemas-message`     | `dependentSchemas`     |
+
+#### Combinators
+
+| Extension         | Applies to |
+| ----------------- | ---------- |
+| `x-allOf-message` | `allOf`    |
+| `x-anyOf-message` | `anyOf`    |
+| `x-oneOf-message` | `oneOf`    |
+| `x-not-message`   | `not`      |
+
+#### Conditional
+
+| Extension        | Applies to |
+| ---------------- | ---------- |
+| `x-if-message`   | `if`       |
+| `x-then-message` | `then`     |
+| `x-else-message` | `else`     |
+
+#### Typeless / Array Applicator
+
+| Extension                         | Applies to                      |
+| --------------------------------- | ------------------------------- |
+| `x-properties-message`            | `properties` (typeless schemas) |
+| `x-prefixItems-message`           | `prefixItems`                   |
+| `x-items-message`                 | `items`                         |
+| `x-unevaluatedProperties-message` | `unevaluatedProperties`         |
+| `x-unevaluatedItems-message`      | `unevaluatedItems`              |
+
+## Behavior Extensions
+
+### String Pre-validation Transforms
+
+| Extension       | Generated                     | Value                                   |
+| --------------- | ----------------------------- | --------------------------------------- |
+| `x-trim`        | `z.string().trim()`           | `true`                                  |
+| `x-toLowerCase` | `z.string().toLowerCase()`    | `true`                                  |
+| `x-toUpperCase` | `z.string().toUpperCase()`    | `true`                                  |
+| `x-normalize`   | `z.string().normalize('NFC')` | `'NFC'` / `'NFD'` / `'NFKC'` / `'NFKD'` |
 
-- Not all OpenAPI features are supported
-- Some OpenAPI validations may not be perfectly converted to Zod
+```yaml
+homepage:
+  type: string
+  format: url
+  x-trim: true
+```
 
-We strongly recommend:
+```ts
+z.string().trim().pipe(z.url())
+```
+
+### Preprocess (Input Normalization)
+
+#### `x-preprocess`
+
+```yaml
+username:
+  type: string
+  x-preprocess: 'z.preprocess((val) => typeof val === "string" ? val.trim() : val, z.string())'
+```
+
+```ts
+z.preprocess((val) => (typeof val === 'string' ? val.trim() : val), z.string())
+```
+
+### Type Coercion
+
+#### `x-coerce`
+
+```yaml
+asNumber:
+  type: number
+  x-coerce: true
+asDate:
+  type: string
+  format: date-time
+  x-coerce: true
+```
+
+```ts
+z.coerce.number()
+z.coerce.date()
+```
+
+### Codec (Bidirectional Transform)
+
+#### `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() })'
+```
+
+```ts
+z.codec(z.iso.datetime(), z.date(), {
+  decode: (val) => new Date(val),
+  encode: (val) => val.toISOString(),
+})
+```
 
-- Pinning to exact versions in production
-- Testing thoroughly when updating versions
-- Reviewing generated code after updates
+### Custom Validation
+
+#### `x-refine`
+
+```yaml
+password:
+  type: string
+  x-refine: '.refine((val) => val.length >= 8, { message: "Password must be at least 8 characters" }).refine((val) => /[A-Z]/.test(val), { message: "Password must contain an uppercase letter" })'
+```
+
+```ts
+z.string()
+  .refine((val) => val.length >= 8, { message: 'Password must be at least 8 characters' })
+  .refine((val) => /[A-Z]/.test(val), { message: 'Password must contain an uppercase letter' })
+```
+
+#### `x-superRefine`
+
+```yaml
+normalizedEmail:
+  type: string
+  format: email
+  x-superRefine: '.superRefine((val, ctx) => { if (val.endsWith("@blocked.example")) ctx.addIssue({ code: "custom", message: "Blocked domain" }) })'
+```
+
+```ts
+z.email().superRefine((val, ctx) => {
+  if (val.endsWith('@blocked.example')) {
+    ctx.addIssue({ code: 'custom', message: 'Blocked domain' })
+  }
+})
+```
+
+### Transform & Pipe
+
+#### `x-transform`
+
+```yaml
+code:
+  type: string
+  x-transform: 'z.string().transform((val) => val.toUpperCase())'
+```
+
+```ts
+z.string().transform((val) => val.toUpperCase())
+```
+
+#### `x-pipe`
+
+```yaml
+port:
+  type: string
+  x-pipe: 'z.string().pipe(z.number().int().positive())'
+```
+
+```ts
+z.string().pipe(z.number().int().positive())
+```
+
+### Default & Fallback Values
+
+#### `x-prefault`
+
+```yaml
+greeting:
+  type: string
+  x-prefault: 'hello'
+```
+
+```ts
+z.string().prefault('hello')
+```
+
+#### `x-catch`
+
+```yaml
+retries:
+  type: integer
+  x-catch: 0
+```
+
+```ts
+z.int().catch(0)
+```
+
+### Immutability
+
+#### `x-freeze`
+
+```yaml
+config:
+  type: object
+  properties:
+    name:
+      type: string
+  x-freeze: true
+```
+
+```ts
+z.object({ name: z.string() }).readonly()
+```
+
+### String Content Checks
+
+#### `x-startsWith` / `x-endsWith` / `x-includes`
+
+```yaml
+url:
+  type: string
+  x-startsWith: 'https://'
+  x-endsWith: '.com'
+path:
+  type: string
+  x-includes: '/api/'
+```
+
+```ts
+z.string().startsWith('https://').endsWith('.com')
+z.string().includes('/api/')
+```
+
+### Format-Specific Options
+
+```yaml
+htmlEmail:
+  type: string
+  format: email
+  x-emailPattern: 'html5' # email pattern preset
+uuidV7:
+  type: string
+  format: uuid
+  x-uuidVersion: v7 # uuid version
+httpsUrl:
+  type: string
+  format: uri
+  x-urlProtocol: '^https$' # url protocol regex
+  x-urlNormalize: true
+preciseDatetime:
+  type: string
+  format: date-time
+  x-isoPrecision: 3 # iso datetime precision / offset / local
+  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
+
+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:
+
+```yaml
+components:
+  schemas:
+    Cat:
+      type: object
+      properties:
+        name:
+          type: string
+      required:
+        - name
+      x-brand: Cat
+    Dog:
+      type: object
+      properties:
+        name:
+          type: string
+      required:
+        - name
+      x-brand: Dog
+```
+
+```ts
+// Generated output
+const CatSchema = z.object({ name: z.string() }).brand<'Cat'>().openapi('Cat')
+
+const DogSchema = z.object({ name: z.string() }).brand<'Dog'>().openapi('Dog')
+```
+
+## Projects Using Hono Takibi
+
+- **[resend-local](https://github.com/y-hiraoka/resend-local)** — A local emulator for the Resend email API.
 
 ## Contributing