@cerios/openapi-to-zod 1.1.0 → 1.2.0

package/README.md

@@ -184,10 +184,11 @@ Examples:
 | `mode` | `"strict"` \| `"normal"` \| `"loose"` | Validation mode |
 | `includeDescriptions` | `boolean` | Include JSDoc comments |
 | `useDescribe` | `boolean` | Add `.describe()` calls |
+| `defaultNullable` | `boolean` | Treat properties as nullable by default when not explicitly specified (default: `false`) |
 | `schemaType` | `"all"` \| `"request"` \| `"response"` | Schema filtering |
 | `prefix` | `string` | Prefix for schema names |
 | `suffix` | `string` | Suffix for schema names |
-| `stripSchemaPrefix` | `string \| RegExp` | Strip prefix from schema names before generating (e.g., `"Company.Models."` or `/^[A-Z]+\./`) |
+| `stripSchemaPrefix` | `string` | Strip prefix from schema names before generating using glob patterns (e.g., `"Company.Models."` or `"*.Models."`) |
 | `showStats` | `boolean` | Include generation statistics |
 | `request` | `object` | Request-specific options (mode, includeDescriptions, useDescribe) |
 | `response` | `object` | Response-specific options (mode, includeDescriptions, useDescribe) |
@@ -410,6 +411,68 @@ The generator supports all OpenAPI string formats with Zod v4:
 | `cidrv4` | `z.cidrv4()` |
 | `cidrv6` | `z.cidrv6()` |
 
+### Custom Date-Time Format
+
+By default, the generator uses `z.iso.datetime()` for `date-time` format fields, which requires an ISO 8601 datetime string with a timezone suffix (e.g., `2026-01-07T14:30:00Z`).
+
+If your API returns date-times **without the `Z` suffix** (e.g., `2026-01-07T14:30:00`), you can override this with a custom regex pattern:
+
+```typescript
+import { defineConfig } from '@cerios/openapi-to-zod';
+
+export default defineConfig({
+  defaults: {
+    // For date-times without Z suffix
+    customDateTimeFormatRegex: '^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}$',
+  },
+  specs: [
+    {
+      input: 'openapi.yaml',
+      output: 'src/schemas.ts',
+    },
+  ],
+});
+```
+
+**TypeScript Config - RegExp Literals:**
+
+In TypeScript config files, you can also use RegExp literals (which don't require double-escaping):
+
+```typescript
+export default defineConfig({
+  defaults: {
+    // Use RegExp literal (single escaping)
+    customDateTimeFormatRegex: /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}$/,
+  },
+  specs: [
+    {
+      input: 'openapi.yaml',
+      output: 'src/schemas.ts',
+    },
+  ],
+});
+```
+
+**Common Custom Formats:**
+
+| Use Case | String Pattern (JSON/YAML) | RegExp Literal (TypeScript) |
+|----------|----------------------------|----------------------------|
+| No timezone suffix<br>`2026-01-07T14:30:00` | `'^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}$'` | `/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}$/` |
+| With milliseconds, no Z<br>`2026-01-07T14:30:00.123` | `'^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}$'` | `/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}$/` |
+| Optional Z suffix<br>`2026-01-07T14:30:00` or<br>`2026-01-07T14:30:00Z` | `'^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}Z?$'` | `/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z?$/` |
+| With milliseconds + optional Z<br>`2026-01-07T14:30:00.123Z` | `'^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}\\.\\d{3}Z?$'` | `/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z?$/` |
+
+**Generated Output:**
+
+When using a custom regex, the generator will produce:
+
+```typescript
+// Instead of: z.iso.datetime()
+// You get: z.string().regex(/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}$/)
+```
+
+**Note:** This option only affects `date-time` format fields. Other formats (like `date`, `email`, `uuid`) remain unchanged.
+
 ## Advanced Features
 
 ### Operation Filtering
@@ -563,6 +626,68 @@ export const userSchema = z.object({
 
 OpenAPI's `nullable: true` is converted to `.nullable()`
 
+#### Default Nullable Behavior
+
+By default, properties are only nullable when explicitly marked with `nullable: true` (OpenAPI 3.0) or `type: ["string", "null"]` (OpenAPI 3.1).
+
+However, many teams follow the industry de facto standard for OpenAPI 3.0.x where properties are assumed nullable unless explicitly constrained. You can enable this behavior with the `defaultNullable` option:
+
+```typescript
+export default defineConfig({
+  specs: [{
+    input: 'openapi.yaml',
+    output: 'schemas.ts',
+    defaultNullable: true,  // Treat unspecified properties as nullable
+  }]
+});
+```
+
+**Behavior comparison:**
+
+| Schema Property | `defaultNullable: false` (default) | `defaultNullable: true` |
+|-----------------|-------------------------------------|-------------------------|
+| `nullable: true` | `.nullable()` | `.nullable()` |
+| `nullable: false` | No `.nullable()` | No `.nullable()` |
+| No `nullable` specified | No `.nullable()` | `.nullable()` |
+
+**Example:**
+
+```yaml
+User:
+  type: object
+  properties:
+    id:
+      type: integer
+    name:
+      type: string
+    email:
+      type: string
+      nullable: true
+    phone:
+      type: string
+      nullable: false
+```
+
+**With `defaultNullable: false` (default):**
+```typescript
+export const userSchema = z.object({
+  id: z.number().int(),
+  name: z.string(),           // Not nullable (no annotation)
+  email: z.string().nullable(), // Explicitly nullable
+  phone: z.string(),           // Explicitly not nullable
+});
+```
+
+**With `defaultNullable: true`:**
+```typescript
+export const userSchema = z.object({
+  id: z.number().int().nullable(),  // Nullable by default
+  name: z.string().nullable(),       // Nullable by default
+  email: z.string().nullable(),      // Explicitly nullable
+  phone: z.string(),                 // Explicitly NOT nullable (respected)
+});
+```
+
 ### Schema Composition
 
 - `allOf` → `.merge()` for objects, `.and()` for primitives
@@ -571,10 +696,46 @@ OpenAPI's `nullable: true` is converted to `.nullable()`
 
 ### Enums
 
-Enums are generated as Zod enums with:
-- Proper string value handling
-- Zod schema using `z.enum()`
-- TypeScript type inference from the Zod schema
+Enums are generated based on their value types:
+
+- **String enums**: `z.enum()` for type-safe string unions
+- **Numeric enums**: `z.union([z.literal(n), ...])` for proper number types
+- **Boolean enums**: `z.boolean()` for true/false values
+- **Mixed enums**: `z.union([z.literal(...), ...])` for heterogeneous values
+
+**Examples:**
+
+```yaml
+# String enum
+Status:
+  type: string
+  enum: [active, inactive, pending]
+
+# Integer enum
+Priority:
+  type: integer
+  enum: [0, 1, 2, 3]
+
+# Mixed enum
+Value:
+  enum: [0, "none", 1, "some"]
+```
+
+**Generated schemas:**
+
+```typescript
+// String enum → z.enum()
+export const statusSchema = z.enum(["active", "inactive", "pending"]);
+export type Status = z.infer<typeof statusSchema>; // "active" | "inactive" | "pending"
+
+// Integer enum → z.union with z.literal
+export const prioritySchema = z.union([z.literal(0), z.literal(1), z.literal(2), z.literal(3)]);
+export type Priority = z.infer<typeof prioritySchema>; // 0 | 1 | 2 | 3
+
+// Mixed enum → z.union with z.literal
+export const valueSchema = z.union([z.literal(0), z.literal("none"), z.literal(1), z.literal("some")]);
+export type Value = z.infer<typeof valueSchema>; // 0 | "none" | 1 | "some"
+```
 
 ## Schema Naming
 
@@ -684,39 +845,39 @@ export default defineConfig({
 });
 ```
 
-#### Regex Patterns
+#### Glob Patterns
 
-Use regex patterns to strip dynamic prefixes:
+Use glob patterns to strip dynamic prefixes:
 
 ```typescript
 export default defineConfig({
   specs: [{
     input: 'openapi.yaml',
     output: 'schemas.ts',
-    // Strip any namespace prefix ending with a dot
-    stripSchemaPrefix: '^[A-Z][a-z]+\\.'
+    // Strip any namespace prefix with wildcard
+    stripSchemaPrefix: '*.Models.'
   }]
 });
 ```
 
-**Regex Auto-Detection:**
+**Glob Pattern Syntax:**
 
-Regex patterns are auto-detected if they contain: `^`, `$`, `\\d`, `\\w`, `\\s`, `.*`, `.+`, `[]`, `()`
+Glob patterns support powerful matching using [minimatch](https://github.com/isaacs/minimatch):
+- `*` matches any characters within a single segment (stops at `.`)
+- `**` matches any characters across multiple segments (crosses `.` boundaries)
+- `?` matches a single character
+- `[abc]` matches any character in the set
+- `{a,b}` matches any of the alternatives
+- `!(pattern)` matches anything except the pattern
 
 ```typescript
-// These are all treated as regex patterns:
-stripSchemaPrefix: '^Company\\.'       // Starts with ^
-stripSchemaPrefix: '[A-Z]+\\.'         // Contains []
-stripSchemaPrefix: '.*\\.Models\\.'    // Contains .*
-
-// This is a literal string:
-stripSchemaPrefix: 'Company.Models.'   // No regex markers
-```
-
-For TypeScript configs, you can also use `RegExp` objects:
-
-```typescript
-stripSchemaPrefix: /^[A-Z][a-z]+\./
+// Examples of glob patterns:
+stripSchemaPrefix: '*.Models.'                      // Matches Company.Models., App.Models.
+stripSchemaPrefix: '**.Models.'                     // Matches any depth: Company.Api.Models., App.V2.Models.
+stripSchemaPrefix: 'Company.{Models,Services}.'     // Matches Company.Models. or Company.Services.
+stripSchemaPrefix: 'api_v[0-9]_'                   // Matches api_v1_, api_v2_, etc.
+stripSchemaPrefix: 'v*.*.'                          // Matches v1.0., v2.1., etc.
+stripSchemaPrefix: '!(Internal)*.'                  // Matches any prefix except those starting with Internal
 ```
 
 #### Common Patterns
@@ -730,24 +891,44 @@ stripSchemaPrefix: /^[A-Z][a-z]+\./
 // Company.Models.Post → Post
 ```
 
-**Pattern 2: Multiple Namespaces**
+**Pattern 2: Multiple Namespaces with Wildcard**
 ```typescript
 {
-  stripSchemaPrefix: '^[A-Za-z]+\\.Models\\.'
+  stripSchemaPrefix: '*.Models.'
 }
 // MyApp.Models.User → User
 // OtherApp.Models.User → User
+// Company.Models.Post → Post
 ```
 
-**Pattern 3: Version Prefixes**
+**Pattern 3: Multiple Namespace Types**
 ```typescript
 {
-  stripSchemaPrefix: '^v\\d+\\.'
+  stripSchemaPrefix: '*.{Models,Services}.'
+}
+// App.Models.User → User
+// App.Services.UserService → UserService
+```
+
+**Pattern 4: Version Prefixes with Character Class**
+```typescript
+{
+  stripSchemaPrefix: 'v[0-9].'
 }
 // v1.User → User
 // v2.Product → Product
 ```
 
+**Pattern 5: Versioned Prefixes with Wildcards**
+```typescript
+{
+  stripSchemaPrefix: 'api_v*_'
+}
+// api_v1_User → User
+// api_v2_Product → Product
+// api_v10_Comment → Comment
+```
+
 #### Interaction with prefix/suffix Options
 
 `stripSchemaPrefix` is applied **before** `prefix` and `suffix` options: