@cerios/openapi-to-zod 1.1.1 → 1.3.0

package/README.md

@@ -19,7 +19,7 @@ Transform OpenAPI YAML specifications into Zod v4 compliant schemas with full Ty
 - 📊 **Statistics**: Optional generation statistics in output files
 - ❗ **Better Errors**: Clear error messages with file paths and line numbers
 - 🎭 **Tuple Validation**: OpenAPI 3.1 `prefixItems` support with `.tuple()` and `.rest()`
-- 🔗 **Smart AllOf**: Uses `.merge()` for objects, `.and()` for primitives
+- 🔗 **Smart AllOf**: Uses `.extend()` for objects (Zod v4), `.and()` for primitives
 - 🎯 **Literal Types**: `const` keyword support with `z.literal()`
 - 🔢 **Exclusive Bounds**: `exclusiveMinimum`/`exclusiveMaximum` with `.gt()`/`.lt()`
 - 🎨 **Unique Arrays**: `uniqueItems` validation with Set-based checking
@@ -181,9 +181,11 @@ Examples:
 | `name` | `string` | Optional identifier for logging |
 | `input` | `string` | Input OpenAPI YAML file path (required) |
 | `output` | `string` | Output TypeScript file path (required) |
-| `mode` | `"strict"` \| `"normal"` \| `"loose"` | Validation mode |
+| `mode` | `"strict"` \| `"normal"` \| `"loose"` | Validation mode for top-level schemas (default: `"normal"`) |
+| `emptyObjectBehavior` | `"strict"` \| `"loose"` \| `"record"` | How to handle empty objects (default: `"loose"`) |
 | `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 |
@@ -313,6 +315,43 @@ const userSchema = z.looseObject({
 });
 ```
 
+## Empty Object Behavior
+
+When OpenAPI schemas define an object without any properties (e.g., `type: object` with no `properties`), the generator needs to decide how to represent it. The `emptyObjectBehavior` option controls this:
+
+### Loose (default)
+Uses `z.looseObject({})` which allows any additional properties:
+
+```typescript
+// OpenAPI: { type: object }
+const metadataSchema = z.looseObject({});
+
+// Accepts: {}, { foo: "bar" }, { any: "properties" }
+```
+
+### Strict
+Uses `z.strictObject({})` which rejects any properties:
+
+```typescript
+// OpenAPI: { type: object }
+const emptySchema = z.strictObject({});
+
+// Accepts: {}
+// Rejects: { foo: "bar" }
+```
+
+### Record
+Uses `z.record(z.string(), z.unknown())` which treats it as an arbitrary key-value map:
+
+```typescript
+// OpenAPI: { type: object }
+const mapSchema = z.record(z.string(), z.unknown());
+
+// Accepts: {}, { foo: "bar" }, { any: "properties" }
+```
+
+> **Note:** The `mode` option controls how top-level schema definitions are wrapped, while `emptyObjectBehavior` controls how nested empty objects (properties without defined structure) are generated. These are independent settings.
+
 ## Examples
 
 ### Input OpenAPI YAML
@@ -410,6 +449,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,9 +664,90 @@ 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
+  }]
+});
+```
+
+**Important:** `defaultNullable` only applies to **primitive property values** within objects. It does NOT apply to:
+
+- **Top-level schema definitions** - Schemas are not made nullable at the definition level
+- **Schema references (`$ref`)** - References preserve the nullability of the target schema; add explicit `nullable: true` if needed
+- **Enum values** - Enums define discrete values and are not nullable by default
+- **Const/literal values** - Literals are exact values and are not nullable by default
+
+**Behavior comparison:**
+
+| Schema Property | `defaultNullable: false` (default) | `defaultNullable: true` |
+|-----------------|-------------------------------------|-------------------------|
+| `nullable: true` | `.nullable()` | `.nullable()` |
+| `nullable: false` | No `.nullable()` | No `.nullable()` |
+| No annotation (primitive) | No `.nullable()` | `.nullable()` |
+| No annotation (`$ref`) | No `.nullable()` | No `.nullable()` |
+| No annotation (enum) | No `.nullable()` | No `.nullable()` |
+| No annotation (const) | No `.nullable()` | No `.nullable()` |
+
+**Example:**
+
+```yaml
+components:
+  schemas:
+    Status:
+      type: string
+      enum: [active, inactive]
+    User:
+      type: object
+      properties:
+        id:
+          type: integer
+        name:
+          type: string
+        status:
+          $ref: '#/components/schemas/Status'
+        nullableStatus:
+          allOf:
+            - $ref: '#/components/schemas/Status'
+          nullable: true
+```
+
+**With `defaultNullable: false` (default):**
+```typescript
+export const statusSchema = z.enum(["active", "inactive"]);
+
+export const userSchema = z.object({
+  id: z.number().int(),
+  name: z.string(),              // Not nullable (no annotation)
+  status: statusSchema,          // Not nullable ($ref)
+  nullableStatus: statusSchema.nullable(), // Explicitly nullable
+});
+```
+
+**With `defaultNullable: true`:**
+```typescript
+export const statusSchema = z.enum(["active", "inactive"]);
+
+export const userSchema = z.object({
+  id: z.number().int().nullable(),  // Nullable (primitive)
+  name: z.string().nullable(),       // Nullable (primitive)
+  status: statusSchema,              // NOT nullable ($ref - must be explicit)
+  nullableStatus: statusSchema.nullable(), // Explicitly nullable
+});
+```
+
 ### Schema Composition
 
-- `allOf` → `.merge()` for objects, `.and()` for primitives
+- `allOf` → `.extend()` for objects (Zod v4), `.and()` for primitives
 - `oneOf`, `anyOf` → `z.union()` or `z.discriminatedUnion()`
 - `$ref` → Proper schema references
 
@@ -1015,11 +1197,11 @@ export const flexibleMetadataSchema = z
 
 ### Schema Composition
 
-#### AllOf - Smart Merging
+#### AllOf - Smart Extending
 
-Uses `.merge()` for objects, `.and()` for primitives:
+Uses `.extend()` for objects (Zod v4 compliant - `.merge()` is deprecated), `.and()` for primitives:
 
-**Object Merging:**
+**Object Extending:**
 ```yaml
 User:
   allOf:
@@ -1036,10 +1218,10 @@ User:
 **Generated:**
 ```typescript
 export const userSchema = baseEntitySchema
-  .merge(timestampedSchema)
-  .merge(z.object({
+  .extend(timestampedSchema.shape)
+  .extend(z.object({
     username: z.string()
-  }));
+  }).shape);
 ```
 
 #### OneOf / AnyOf
@@ -1161,7 +1343,7 @@ export const statusCodeSchema = z.enum(["200", "201", "400", "404", "500"]);
 | const | ✅ | ✅ | `z.literal()` |
 | nullable (property) | ✅ | ✅ | `.nullable()` |
 | nullable (type array) | ❌ | ✅ | `.nullable()` |
-| allOf (objects) | ✅ | ✅ | `.merge()` |
+| allOf (objects) | ✅ | ✅ | `.extend()` |
 | allOf (primitives) | ✅ | ✅ | `.and()` |
 | oneOf/anyOf | ✅ | ✅ | `z.union()` |
 | discriminators | ✅ | ✅ | `z.discriminatedUnion()` |