@cerios/openapi-to-zod 1.1.1 → 1.2.0

package/README.md

@@ -184,6 +184,7 @@ 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 |
@@ -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

package/dist/cli.js

@@ -5233,14 +5233,17 @@ function escapeJSDoc(str) {
 function wrapNullable(validation, isNullable2) {
   return isNullable2 ? `${validation}.nullable()` : validation;
 }
-function isNullable(schema) {
+function isNullable(schema, defaultNullable = false) {
   if (schema.nullable === true) {
     return true;
   }
+  if (schema.nullable === false) {
+    return false;
+  }
   if (Array.isArray(schema.type)) {
     return schema.type.includes("null");
   }
-  return false;
+  return defaultNullable;
 }
 function getPrimaryType(schema) {
   if (Array.isArray(schema.type)) {
@@ -5411,6 +5414,22 @@ function stripPrefix(input, pattern, ensureLeadingChar) {
   }
   return input;
 }
+function stripPathPrefix(path, pattern) {
+  if (!pattern) {
+    return path;
+  }
+  if (!isGlobPattern(pattern)) {
+    let normalizedPattern = pattern.trim();
+    if (!normalizedPattern.startsWith("/")) {
+      normalizedPattern = `/${normalizedPattern}`;
+    }
+    if (normalizedPattern.endsWith("/") && normalizedPattern !== "/") {
+      normalizedPattern = normalizedPattern.slice(0, -1);
+    }
+    return stripPrefix(path, normalizedPattern, "/");
+  }
+  return stripPrefix(path, pattern, "/");
+}
 
 // src/validators/array-validator.ts
 init_cjs_shims();
@@ -5944,7 +5963,7 @@ function configurePatternCache(size) {
     PATTERN_CACHE = new LRUCache(size);
   }
 }
-var FORMAT_MAP = {
+var DEFAULT_FORMAT_MAP = {
   uuid: "z.uuid()",
   email: "z.email()",
   uri: "z.url()",
@@ -5954,7 +5973,6 @@ var FORMAT_MAP = {
   byte: "z.base64()",
   binary: "z.string()",
   date: "z.iso.date()",
-  "date-time": "z.iso.datetime()",
   time: "z.iso.time()",
   duration: 'z.string().refine((val) => /^P(?:(?:\\d+Y)?(?:\\d+M)?(?:\\d+D)?(?:T(?:\\d+H)?(?:\\d+M)?(?:\\d+(?:\\.\\d+)?S)?)?|\\d+W)$/.test(val) && !/^PT?$/.test(val), { message: "Must be a valid ISO 8601 duration" })',
   ipv4: "z.ipv4()",
@@ -5973,6 +5991,30 @@ var FORMAT_MAP = {
   "json-pointer": 'z.string().refine((val) => val === "" || /^(\\/([^~/]|~0|~1)+)+$/.test(val), { message: "Must be a valid JSON Pointer (RFC 6901)" })',
   "relative-json-pointer": 'z.string().refine((val) => /^(0|[1-9]\\d*)(#|(\\/([^~/]|~0|~1)+)*)$/.test(val), { message: "Must be a valid relative JSON Pointer" })'
 };
+var FORMAT_MAP = {
+  ...DEFAULT_FORMAT_MAP,
+  "date-time": "z.iso.datetime()"
+};
+function configureDateTimeFormat(pattern) {
+  if (!pattern) {
+    FORMAT_MAP["date-time"] = "z.iso.datetime()";
+    return;
+  }
+  const patternStr = pattern instanceof RegExp ? pattern.source : pattern;
+  if (patternStr === "") {
+    FORMAT_MAP["date-time"] = "z.iso.datetime()";
+    return;
+  }
+  try {
+    new RegExp(patternStr);
+  } catch (error) {
+    throw new Error(
+      `Invalid regular expression pattern for customDateTimeFormatRegex: ${patternStr}. ${error instanceof Error ? error.message : "Pattern is malformed"}`
+    );
+  }
+  const escapedPattern = escapePattern(patternStr);
+  FORMAT_MAP["date-time"] = `z.string().regex(/${escapedPattern}/)`;
+}
 function generateStringValidation(schema, useDescribe) {
   let validation = FORMAT_MAP[schema.format || ""] || "z.string()";
   if (schema.minLength !== void 0) {
@@ -6262,7 +6304,8 @@ var _PropertyGenerator = class _PropertyGenerator {
     if ((this.context.schemaType === "request" || this.context.schemaType === "response") && schema.properties) {
       schema = this.filterNestedProperties(schema);
     }
-    const nullable = isNullable(schema);
+    const effectiveDefaultNullable = isTopLevel ? false : this.context.defaultNullable;
+    const nullable = isNullable(schema, effectiveDefaultNullable);
     if (hasMultipleTypes(schema)) {
       const union = this.generateMultiTypeUnion(schema, currentSchema);
       return wrapNullable(union, nullable);
@@ -6582,7 +6625,7 @@ var OpenApiGenerator = class {
     this.schemaUsageMap = /* @__PURE__ */ new Map();
     this.needsZodImport = true;
     this.filterStats = createFilterStatistics();
-    var _a, _b, _c, _d, _e;
+    var _a, _b, _c, _d, _e, _f, _g;
     if (!options.input) {
       throw new ConfigurationError("Input path is required", { providedOptions: options });
     }
@@ -6592,21 +6635,27 @@ var OpenApiGenerator = class {
       output: options.output,
       includeDescriptions: (_a = options.includeDescriptions) != null ? _a : true,
       useDescribe: (_b = options.useDescribe) != null ? _b : false,
+      defaultNullable: (_c = options.defaultNullable) != null ? _c : false,
       schemaType: options.schemaType || "all",
       prefix: options.prefix,
       suffix: options.suffix,
       stripSchemaPrefix: options.stripSchemaPrefix,
-      showStats: (_c = options.showStats) != null ? _c : true,
+      stripPathPrefix: options.stripPathPrefix,
+      showStats: (_d = options.showStats) != null ? _d : true,
       request: options.request,
       response: options.response,
       operationFilters: options.operationFilters,
       ignoreHeaders: options.ignoreHeaders,
-      cacheSize: (_d = options.cacheSize) != null ? _d : 1e3,
-      batchSize: (_e = options.batchSize) != null ? _e : 10
+      cacheSize: (_e = options.cacheSize) != null ? _e : 1e3,
+      batchSize: (_f = options.batchSize) != null ? _f : 10,
+      customDateTimeFormatRegex: options.customDateTimeFormatRegex
     };
     if (this.options.cacheSize) {
       configurePatternCache(this.options.cacheSize);
     }
+    if (this.options.customDateTimeFormatRegex) {
+      configureDateTimeFormat(this.options.customDateTimeFormatRegex);
+    }
     try {
       const fs = require("fs");
       if (!fs.existsSync(this.options.input)) {
@@ -6669,6 +6718,7 @@ var OpenApiGenerator = class {
       mode: this.requestOptions.mode,
       includeDescriptions: this.requestOptions.includeDescriptions,
       useDescribe: this.requestOptions.useDescribe,
+      defaultNullable: (_g = this.options.defaultNullable) != null ? _g : false,
       namingOptions: {
         prefix: this.options.prefix,
         suffix: this.options.suffix
@@ -7022,7 +7072,7 @@ var OpenApiGenerator = class {
    * Generate schema for a component
    */
   generateComponentSchema(name, schema) {
-    var _a, _b;
+    var _a, _b, _c;
     if (!this.schemaDependencies.has(name)) {
       this.schemaDependencies.set(name, /* @__PURE__ */ new Set());
     }
@@ -7054,14 +7104,14 @@ ${typeCode}`;
       mode: resolvedOptions.mode,
       includeDescriptions: resolvedOptions.includeDescriptions,
       useDescribe: resolvedOptions.useDescribe,
+      defaultNullable: (_b = this.options.defaultNullable) != null ? _b : false,
       namingOptions: {
         prefix: this.options.prefix,
         suffix: this.options.suffix
       },
       stripSchemaPrefix: this.options.stripSchemaPrefix
     });
-    const isAlias = !!(schema.$ref && !schema.properties && !schema.allOf && !schema.oneOf && !schema.anyOf);
-    const zodSchema = this.propertyGenerator.generatePropertySchema(schema, name, isAlias);
+    const zodSchema = this.propertyGenerator.generatePropertySchema(schema, name, true);
     const zodSchemaCode = `${jsdoc}export const ${schemaName} = ${zodSchema};`;
     if (zodSchema.includes("z.discriminatedUnion(")) {
       const match = zodSchema.match(/z\.discriminatedUnion\([^,]+,\s*\[([^\]]+)\]/);
@@ -7071,7 +7121,7 @@ ${typeCode}`;
           const depMatch = ref.match(/^([a-z][a-zA-Z0-9]*?)Schema$/);
           if (depMatch) {
             const depName = depMatch[1].charAt(0).toUpperCase() + depMatch[1].slice(1);
-            (_b = this.schemaDependencies.get(name)) == null ? void 0 : _b.add(depName);
+            (_c = this.schemaDependencies.get(name)) == null ? void 0 : _c.add(depName);
           }
         }
       }
@@ -7095,7 +7145,7 @@ ${typeCode}`;
         if (!shouldIncludeOperation(operation, path, method, this.options.operationFilters)) {
           continue;
         }
-        if (!operation.operationId || !operation.parameters || !Array.isArray(operation.parameters)) {
+        if (!operation.parameters || !Array.isArray(operation.parameters)) {
           continue;
         }
         const queryParams = operation.parameters.filter(
@@ -7104,7 +7154,13 @@ ${typeCode}`;
         if (queryParams.length === 0) {
           continue;
         }
-        const pascalOperationId = operation.operationId.includes("-") ? toPascalCase(operation.operationId) : operation.operationId.charAt(0).toUpperCase() + operation.operationId.slice(1);
+        let pascalOperationId;
+        if (operation.operationId) {
+          pascalOperationId = operation.operationId.includes("-") ? toPascalCase(operation.operationId) : operation.operationId.charAt(0).toUpperCase() + operation.operationId.slice(1);
+        } else {
+          const strippedPath = stripPathPrefix(path, this.options.stripPathPrefix);
+          pascalOperationId = this.generateMethodNameFromPath(method, strippedPath);
+        }
         const schemaName = `${pascalOperationId}QueryParams`;
         if (!this.schemaDependencies.has(schemaName)) {
           this.schemaDependencies.set(schemaName, /* @__PURE__ */ new Set());
@@ -7152,8 +7208,9 @@ ${propsCode}
         const prefixedName = this.options.prefix ? `${toPascalCase(this.options.prefix)}${operationName}` : operationName;
         const suffixedName = this.options.suffix ? `${prefixedName}${toPascalCase(this.options.suffix)}` : prefixedName;
         const camelCaseSchemaName = `${suffixedName.charAt(0).toLowerCase() + suffixedName.slice(1)}QueryParamsSchema`;
+        const jsdocOperationName = operation.operationId || `${method.toUpperCase()} ${path}`;
         const jsdoc = `/**
- * Query parameters for ${operation.operationId}
+ * Query parameters for ${jsdocOperationName}
  */
 `;
         const fullSchemaCode = `${jsdoc}export const ${camelCaseSchemaName} = ${schemaCode};`;
@@ -7162,6 +7219,35 @@ ${propsCode}
       }
     }
   }
+  /**
+   * Generate a PascalCase method name from HTTP method and path
+   * Used as fallback when operationId is not available
+   * @internal
+   */
+  generateMethodNameFromPath(method, path) {
+    const segments = path.split("/").filter(Boolean).map((segment) => {
+      if (segment.startsWith("{") && segment.endsWith("}")) {
+        const paramName = segment.slice(1, -1);
+        return `By${this.capitalizeSegment(paramName)}`;
+      }
+      return this.capitalizeSegment(segment);
+    }).join("");
+    const capitalizedMethod = method.charAt(0).toUpperCase() + method.slice(1).toLowerCase();
+    return `${capitalizedMethod}${segments}`;
+  }
+  /**
+   * Capitalizes a path segment, handling special characters like dashes, underscores, and dots
+   * @internal
+   */
+  capitalizeSegment(str) {
+    if (str.includes("-") || str.includes("_") || str.includes(".")) {
+      return str.split(/[-_.]/).map((part) => {
+        if (!part) return "";
+        return part.charAt(0).toUpperCase() + part.slice(1).toLowerCase();
+      }).join("");
+    }
+    return str.charAt(0).toUpperCase() + str.slice(1);
+  }
   /**
    * Check if a header should be ignored based on filter patterns
    * @internal
@@ -7198,7 +7284,7 @@ ${propsCode}
         if (!shouldIncludeOperation(operation, path, method, this.options.operationFilters)) {
           continue;
         }
-        if (!operation.operationId || !operation.parameters || !Array.isArray(operation.parameters)) {
+        if (!operation.parameters || !Array.isArray(operation.parameters)) {
           continue;
         }
         const headerParams = operation.parameters.filter(
@@ -7207,7 +7293,13 @@ ${propsCode}
         if (headerParams.length === 0) {
           continue;
         }
-        const pascalOperationId = operation.operationId.includes("-") ? toPascalCase(operation.operationId) : operation.operationId.charAt(0).toUpperCase() + operation.operationId.slice(1);
+        let pascalOperationId;
+        if (operation.operationId) {
+          pascalOperationId = operation.operationId.includes("-") ? toPascalCase(operation.operationId) : operation.operationId.charAt(0).toUpperCase() + operation.operationId.slice(1);
+        } else {
+          const strippedPath = stripPathPrefix(path, this.options.stripPathPrefix);
+          pascalOperationId = this.generateMethodNameFromPath(method, strippedPath);
+        }
         const schemaName = `${pascalOperationId}HeaderParams`;
         if (!this.schemaDependencies.has(schemaName)) {
           this.schemaDependencies.set(schemaName, /* @__PURE__ */ new Set());
@@ -7244,8 +7336,9 @@ ${propsCode}
         const prefixedName = this.options.prefix ? `${toPascalCase(this.options.prefix)}${operationName}` : operationName;
         const suffixedName = this.options.suffix ? `${prefixedName}${toPascalCase(this.options.suffix)}` : prefixedName;
         const camelCaseSchemaName = `${suffixedName.charAt(0).toLowerCase() + suffixedName.slice(1)}HeaderParamsSchema`;
+        const jsdocOperationName = operation.operationId || `${method.toUpperCase()} ${path}`;
         const jsdoc = `/**
- * Header parameters for ${operation.operationId}
+ * Header parameters for ${jsdocOperationName}
  */
 `;
         const fullSchemaCode = `${jsdoc}export const ${camelCaseSchemaName} = ${schemaCode};`;
@@ -7425,7 +7518,8 @@ var import_zod = require("zod");
 var RequestResponseOptionsSchema = import_zod.z.strictObject({
   mode: import_zod.z.enum(["strict", "normal", "loose"]).optional(),
   useDescribe: import_zod.z.boolean().optional(),
-  includeDescriptions: import_zod.z.boolean().optional()
+  includeDescriptions: import_zod.z.boolean().optional(),
+  defaultNullable: import_zod.z.boolean().optional()
 });
 var OperationFiltersSchema = import_zod.z.strictObject({
   includeTags: import_zod.z.array(import_zod.z.string()).optional(),
@@ -7508,6 +7602,7 @@ var OpenApiGeneratorOptionsSchema = import_zod2.z.strictObject({
   output: import_zod2.z.string(),
   includeDescriptions: import_zod2.z.boolean().optional(),
   useDescribe: import_zod2.z.boolean().optional(),
+  defaultNullable: import_zod2.z.boolean().optional(),
   schemaType: import_zod2.z.enum(["all", "request", "response"]).optional(),
   prefix: import_zod2.z.string().optional(),
   suffix: import_zod2.z.string().optional(),
@@ -7518,13 +7613,28 @@ var OpenApiGeneratorOptionsSchema = import_zod2.z.strictObject({
   name: import_zod2.z.string().optional(),
   operationFilters: OperationFiltersSchema.optional(),
   cacheSize: import_zod2.z.number().positive().optional(),
-  batchSize: import_zod2.z.number().positive().optional()
+  batchSize: import_zod2.z.number().positive().optional(),
+  customDateTimeFormatRegex: import_zod2.z.union([
+    import_zod2.z.string().refine(
+      (pattern) => {
+        try {
+          new RegExp(pattern);
+          return true;
+        } catch {
+          return false;
+        }
+      },
+      { message: "Must be a valid regular expression pattern" }
+    ),
+    import_zod2.z.instanceof(RegExp)
+  ]).optional()
 });
 var ConfigFileSchema = import_zod2.z.strictObject({
   defaults: import_zod2.z.strictObject({
     mode: import_zod2.z.enum(["strict", "normal", "loose"]).optional(),
     includeDescriptions: import_zod2.z.boolean().optional(),
     useDescribe: import_zod2.z.boolean().optional(),
+    defaultNullable: import_zod2.z.boolean().optional(),
     schemaType: import_zod2.z.enum(["all", "request", "response"]).optional(),
     prefix: import_zod2.z.string().optional(),
     suffix: import_zod2.z.string().optional(),
@@ -7534,7 +7644,21 @@ var ConfigFileSchema = import_zod2.z.strictObject({
     response: RequestResponseOptionsSchema.optional(),
     operationFilters: OperationFiltersSchema.optional(),
     cacheSize: import_zod2.z.number().positive().optional(),
-    batchSize: import_zod2.z.number().positive().optional()
+    batchSize: import_zod2.z.number().positive().optional(),
+    customDateTimeFormatRegex: import_zod2.z.union([
+      import_zod2.z.string().refine(
+        (pattern) => {
+          try {
+            new RegExp(pattern);
+            return true;
+          } catch {
+            return false;
+          }
+        },
+        { message: "Must be a valid regular expression pattern" }
+      ),
+      import_zod2.z.instanceof(RegExp)
+    ]).optional()
   }).optional(),
   specs: import_zod2.z.array(OpenApiGeneratorOptionsSchema).min(1, {
     message: "Configuration must include at least one specification. Each specification should have 'input' and 'output' paths."
@@ -7583,10 +7707,12 @@ function mergeConfigWithDefaults(config) {
       mode: defaults.mode,
       includeDescriptions: defaults.includeDescriptions,
       useDescribe: defaults.useDescribe,
+      defaultNullable: defaults.defaultNullable,
       schemaType: defaults.schemaType,
       prefix: defaults.prefix,
       suffix: defaults.suffix,
       showStats: defaults.showStats,
+      customDateTimeFormatRegex: defaults.customDateTimeFormatRegex,
       // Override with spec-specific values (including required input/output)
       ...spec
     };