@alt-stack/zod-openapi 1.1.3 → 1.3.0

package/src/interface-generator.ts

@@ -0,0 +1,290 @@
+/**
+ * Generates TypeScript interface/type strings from OpenAPI schemas.
+ *
+ * This produces concrete types that appear directly in .d.ts files,
+ * rather than requiring z.infer<> resolution at the type level.
+ */
+
+import {
+  getSchemaExportedVariableNameForPrimitiveType,
+  getSchemaExportedVariableNameForStringFormat,
+} from "./registry";
+import type { AnySchema } from "./types/types";
+
+const validIdentifierRegex = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/;
+
+type SchemaToTypeOptions = {
+  outputSchemaNames?: Set<string>;
+};
+
+function quotePropertyName(name: string): string {
+  return validIdentifierRegex.test(name) ? name : `'${name}'`;
+}
+
+function toPascalCase(name: string): string {
+  return name
+    .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+    .replace(/[^a-zA-Z0-9]/g, " ")
+    .split(" ")
+    .filter(Boolean)
+    .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+    .join("");
+}
+
+export function schemaExportNameToOutputAlias(name: string): string {
+  return `${toPascalCase(name)}Output`;
+}
+
+function registerOutputSchemaName(
+  schemaName: string,
+  options?: SchemaToTypeOptions,
+): string {
+  options?.outputSchemaNames?.add(schemaName);
+  return schemaExportNameToOutputAlias(schemaName);
+}
+
+function getRegisteredOutputAlias(
+  schema: AnySchema,
+  options?: SchemaToTypeOptions,
+): string | undefined {
+  if (!schema || typeof schema !== "object") return undefined;
+
+  if (schema["type"] === "string" && typeof schema["format"] === "string") {
+    const customSchemaName = getSchemaExportedVariableNameForStringFormat(
+      schema["format"],
+    );
+    if (customSchemaName) {
+      return registerOutputSchemaName(customSchemaName, options);
+    }
+  }
+
+  if (
+    schema["type"] === "number" ||
+    schema["type"] === "integer" ||
+    schema["type"] === "boolean"
+  ) {
+    const customSchemaName = getSchemaExportedVariableNameForPrimitiveType(
+      schema["type"],
+    );
+    if (customSchemaName) {
+      return registerOutputSchemaName(customSchemaName, options);
+    }
+  }
+
+  return undefined;
+}
+
+/**
+ * Converts an OpenAPI schema to a TypeScript type string.
+ *
+ * @example
+ * schemaToTypeString({ type: 'string' }) // => 'string'
+ * schemaToTypeString({ type: 'object', properties: { id: { type: 'string' } } }) // => '{ id?: string }'
+ */
+export function schemaToTypeString(
+  schema: AnySchema,
+  options?: SchemaToTypeOptions,
+): string {
+  if (!schema || typeof schema !== "object") return "unknown";
+
+  // Handle $ref
+  if (schema["$ref"] && typeof schema["$ref"] === "string") {
+    const match = (schema["$ref"] as string).match(
+      /#\/components\/schemas\/(.+)/,
+    );
+    let result = "unknown";
+    if (match && match[1]) {
+      // Decode URI-encoded schema names (e.g., %20 -> space)
+      result = decodeURIComponent(match[1]);
+    }
+    if (schema["nullable"] === true) {
+      result = `(${result} | null)`;
+    }
+    return result;
+  }
+
+  let result: string = "unknown";
+
+  // Handle oneOf (union)
+  if ("oneOf" in schema && Array.isArray(schema["oneOf"])) {
+    const unionMembers = (schema["oneOf"] as AnySchema[]).map((s) =>
+      schemaToTypeString(s, options),
+    );
+    result = unionMembers.length > 1 ? `(${unionMembers.join(" | ")})` : unionMembers[0] ?? "unknown";
+  }
+  // Handle allOf (intersection)
+  else if ("allOf" in schema && Array.isArray(schema["allOf"])) {
+    const intersectionMembers = (schema["allOf"] as AnySchema[]).map((s) =>
+      schemaToTypeString(s, options),
+    );
+    result = intersectionMembers.length > 1
+      ? `(${intersectionMembers.join(" & ")})`
+      : intersectionMembers[0] ?? "unknown";
+  }
+  // Handle anyOf (union, similar to oneOf)
+  else if ("anyOf" in schema && Array.isArray(schema["anyOf"])) {
+    const unionMembers = (schema["anyOf"] as AnySchema[]).map((s) =>
+      schemaToTypeString(s, options),
+    );
+    result = unionMembers.length > 1 ? `(${unionMembers.join(" | ")})` : unionMembers[0] ?? "unknown";
+  }
+  // Handle type-based schemas
+  else {
+    switch (schema["type"]) {
+      case "string": {
+        const registeredAlias = getRegisteredOutputAlias(schema, options);
+        if (registeredAlias) {
+          result = registeredAlias;
+        } else if (schema["enum"] && Array.isArray(schema["enum"])) {
+          // String enum
+          result = (schema["enum"] as string[])
+            .map((v) => JSON.stringify(v))
+            .join(" | ");
+        } else {
+          result = "string";
+        }
+        break;
+      }
+      case "number":
+      case "integer": {
+        const registeredAlias = getRegisteredOutputAlias(schema, options);
+        if (registeredAlias) {
+          result = registeredAlias;
+        } else if (schema["enum"] && Array.isArray(schema["enum"])) {
+          // Numeric enum
+          result = (schema["enum"] as number[]).map((v) => String(v)).join(" | ");
+        } else {
+          result = "number";
+        }
+        break;
+      }
+      case "boolean":
+        result = getRegisteredOutputAlias(schema, options) ?? "boolean";
+        break;
+      case "null":
+        result = "null";
+        break;
+      case "array":
+        if (schema["items"]) {
+          const itemType = schemaToTypeString(schema["items"] as AnySchema, options);
+          result = `Array<${itemType}>`;
+        } else {
+          result = "unknown[]";
+        }
+        break;
+      case "object":
+        result = objectSchemaToTypeString(schema, options);
+        break;
+      default:
+        // Try to detect object from properties
+        if (schema["properties"]) {
+          result = objectSchemaToTypeString(schema, options);
+        } else if (schema["enum"] && Array.isArray(schema["enum"])) {
+          // Untyped enum
+          result = (schema["enum"] as unknown[])
+            .map((v) => JSON.stringify(v))
+            .join(" | ");
+        } else {
+          result = "unknown";
+        }
+        break;
+    }
+  }
+
+  // Handle nullable
+  if (schema["nullable"] === true) {
+    result = `(${result} | null)`;
+  }
+
+  return result;
+}
+
+/**
+ * Converts an OpenAPI object schema to a TypeScript object type string.
+ */
+function objectSchemaToTypeString(
+  schema: AnySchema,
+  options?: SchemaToTypeOptions,
+): string {
+  const properties = schema["properties"] as Record<string, AnySchema> | undefined;
+  const required = new Set((schema["required"] as string[]) ?? []);
+  const additionalProperties = schema["additionalProperties"];
+
+  if (!properties && !additionalProperties) {
+    return "Record<string, unknown>";
+  }
+
+  const propertyStrings: string[] = [];
+
+  if (properties) {
+    for (const [propName, propSchema] of Object.entries(properties)) {
+      const isRequired = required.has(propName);
+      const propType = schemaToTypeString(propSchema, options);
+      const quotedName = quotePropertyName(propName);
+      propertyStrings.push(
+        `${quotedName}${isRequired ? "" : "?"}: ${propType}`,
+      );
+    }
+  }
+
+  // Handle additionalProperties
+  if (additionalProperties === true) {
+    propertyStrings.push("[key: string]: unknown");
+  } else if (
+    typeof additionalProperties === "object" &&
+    additionalProperties !== null
+  ) {
+    const additionalType = schemaToTypeString(additionalProperties as AnySchema, options);
+    propertyStrings.push(`[key: string]: ${additionalType}`);
+  }
+
+  return `{ ${propertyStrings.join("; ")} }`;
+}
+
+/**
+ * Generates a full TypeScript interface declaration.
+ *
+ * @example
+ * generateInterface('User', { type: 'object', properties: { id: { type: 'string' } }, required: ['id'] })
+ * // => 'export interface User { id: string; }'
+ */
+export function generateInterface(
+  name: string,
+  schema: AnySchema,
+  options?: SchemaToTypeOptions,
+): string {
+  const properties = schema["properties"] as Record<string, AnySchema> | undefined;
+  const required = new Set((schema["required"] as string[]) ?? []);
+
+  // For non-object types, use type alias instead of interface
+  if (schema["type"] !== "object" && !properties) {
+    return `export type ${name} = ${schemaToTypeString(schema, options)};`;
+  }
+
+  const lines: string[] = [];
+  lines.push(`export interface ${name} {`);
+
+  if (properties) {
+    for (const [propName, propSchema] of Object.entries(properties)) {
+      const isRequired = required.has(propName);
+      const propType = schemaToTypeString(propSchema, options);
+      const quotedName = quotePropertyName(propName);
+      lines.push(`  ${quotedName}${isRequired ? "" : "?"}: ${propType};`);
+    }
+  }
+
+  // Handle additionalProperties
+  const additionalProperties = schema["additionalProperties"];
+  if (additionalProperties === true) {
+    lines.push("  [key: string]: unknown;");
+  } else if (
+    typeof additionalProperties === "object" &&
+    additionalProperties !== null
+  ) {
+    const additionalType = schemaToTypeString(additionalProperties as AnySchema, options);
+    lines.push(`  [key: string]: ${additionalType};`);
+  }
+
+  lines.push("}");
+  return lines.join("\n");
+}

package/src/registry.ts

@@ -76,6 +76,12 @@ function isStringsRegistration(
   return reg.type === "string" && "formats" in reg;
 }
 
+function isSupportedStringFormat(
+  format: string,
+): format is SupportedStringFormat {
+  return Object.prototype.hasOwnProperty.call(SUPPORTED_STRING_FORMATS_MAP, format);
+}
+
 // ============================================================================
 // Helper Functions
 // ============================================================================
@@ -167,8 +173,9 @@ class ZodSchemaRegistry {
    * Reverse-lookup helper: given a string format, return the registered schema's exported variable name
    */
   getSchemaExportedVariableNameForStringFormat(
-    format: SupportedStringFormat,
+    format: SupportedStringFormat | string,
   ): string | undefined {
+    if (!isSupportedStringFormat(format)) return undefined;
     for (const registration of this.map.values()) {
       if (registration.type !== "string") continue;
 
@@ -188,6 +195,20 @@ class ZodSchemaRegistry {
     }
     return undefined;
   }
+
+  /**
+   * Reverse-lookup helper: given a primitive type, return the registered schema's exported variable name
+   */
+  getSchemaExportedVariableNameForPrimitiveType(
+    type: ZodOpenApiRegistrationPrimitive["type"],
+  ): string | undefined {
+    for (const registration of this.map.values()) {
+      if (registration.type === type) {
+        return registration.schemaExportedVariableName;
+      }
+    }
+    return undefined;
+  }
 }
 
 // ============================================================================
@@ -214,11 +235,20 @@ export function registerZodSchemaToOpenApiSchema(
  * Convenience helper to get an exported schema variable name for a given string format
  */
 export function getSchemaExportedVariableNameForStringFormat(
-  format: SupportedStringFormat,
+  format: SupportedStringFormat | string,
 ): string | undefined {
   return schemaRegistry.getSchemaExportedVariableNameForStringFormat(format);
 }
 
+/**
+ * Convenience helper to get an exported schema variable name for a given primitive type
+ */
+export function getSchemaExportedVariableNameForPrimitiveType(
+  type: ZodOpenApiRegistrationPrimitive["type"],
+): string | undefined {
+  return schemaRegistry.getSchemaExportedVariableNameForPrimitiveType(type);
+}
+
 /**
  * Clear all registered schemas in the global registry
  */

package/src/to-typescript.spec.ts

@@ -1,4 +1,5 @@
 import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { z } from "zod";
 import { openApiToZodTsCode } from "./to-typescript";
 import {
   registerZodSchemaToOpenApiSchema,
@@ -70,6 +71,65 @@ describe("openApiToZodTsCode with routes", () => {
       expect(result).toContain("'200': GetUsersId200Response");
     });
 
+    it("should use output alias for registered schemas in routes", () => {
+      const uuidSchema = z.string().uuid();
+      registerZodSchemaToOpenApiSchema(uuidSchema, {
+        schemaExportedVariableName: "uuidSchema",
+        type: "string",
+        format: "uuid",
+      });
+
+      const openapi = {
+        components: {
+          schemas: {
+            User: {
+              type: "object",
+              properties: {
+                id: { type: "string", format: "uuid" },
+              },
+              required: ["id"],
+            },
+          },
+        },
+        paths: {
+          "/users/{id}": {
+            get: {
+              parameters: [
+                {
+                  name: "id",
+                  in: "path",
+                  required: true,
+                  schema: { type: "string" },
+                },
+              ],
+              responses: {
+                "200": {
+                  content: {
+                    "application/json": {
+                      schema: { $ref: "#/components/schemas/User" },
+                    },
+                  },
+                },
+              },
+            },
+          },
+        },
+      };
+
+      const result = openApiToZodTsCode(
+        openapi,
+        ['import { uuidSchema } from "./custom-schemas";'],
+        { includeRoutes: true },
+      );
+
+      expect(result).toContain(
+        "type UuidSchemaOutput = z.output<typeof uuidSchema>;",
+      );
+      expect(result).toContain("id: UuidSchemaOutput;");
+      expect(result).toContain("export const GetUsersId200Response = UserSchema;");
+      expect(result).toContain("'200': GetUsersId200Response");
+    });
+
     it("should generate Request with body schema", () => {
       const openapi = {
         components: {

package/src/to-typescript.ts

@@ -14,6 +14,7 @@ import {
   generateRouteSchemaNames,
   type RouteInfo,
 } from "./routes";
+import { generateInterface, schemaExportNameToOutputAlias } from "./interface-generator";
 
 const validIdentifierRegex = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/;
 
@@ -429,20 +430,37 @@ export const openApiToZodTsCode = (
   lines.push(...(customImportLines ?? []));
   lines.push("");
 
+  // Type assertion helper for compile-time verification
+  lines.push("// Type assertion helper - verifies interface matches schema at compile time");
+  lines.push("type _AssertEqual<T, U> = [T] extends [U] ? ([U] extends [T] ? true : never) : never;");
+  lines.push("");
+
   // Create registry for schema deduplication
   const registry = createSchemaRegistry();
 
   const sortedSchemaNames = topologicalSortSchemas(schemas);
 
+  // Collect all type assertions to emit after all schemas
+  const typeAssertions: string[] = [];
+  const outputSchemaNames = new Set<string>();
+  const schemaBlocks: string[] = [];
+
   for (const name of sortedSchemaNames) {
     const schema = schemas[name];
     if (schema) {
       const zodExpr = convertSchemaToZodString(schema);
       const schemaName = `${name}Schema`;
       const typeName = name;
-      lines.push(`export const ${schemaName} = ${zodExpr};`);
-      lines.push(`export type ${typeName} = z.infer<typeof ${schemaName}>;`);
-      lines.push("");
+
+      // Generate interface (concrete type in .d.ts)
+      schemaBlocks.push(generateInterface(typeName, schema, { outputSchemaNames }));
+
+      // Generate schema with ZodType<T> annotation (simple type in .d.ts)
+      schemaBlocks.push(`export const ${schemaName}: z.ZodType<${typeName}> = ${zodExpr};`);
+      schemaBlocks.push("");
+
+      // Add type assertion to verify interface matches schema
+      typeAssertions.push(`type _Assert${typeName} = _AssertEqual<${typeName}, z.infer<typeof ${schemaName}>>;`);
 
       // Register component schemas so they can be referenced by route schemas
       const fingerprint = getSchemaFingerprint(schema);
@@ -450,6 +468,24 @@ export const openApiToZodTsCode = (
     }
   }
 
+  if (outputSchemaNames.size > 0) {
+    lines.push("// Zod output aliases for registered schemas");
+    for (const schemaName of outputSchemaNames) {
+      const aliasName = schemaExportNameToOutputAlias(schemaName);
+      lines.push(`type ${aliasName} = z.output<typeof ${schemaName}>;`);
+    }
+    lines.push("");
+  }
+
+  lines.push(...schemaBlocks);
+
+  // Emit all type assertions
+  if (typeAssertions.length > 0) {
+    lines.push("// Compile-time type assertions - ensure interfaces match schemas");
+    lines.push(typeAssertions.join("\n"));
+    lines.push("");
+  }
+
   if (options?.includeRoutes) {
     const routes = parseOpenApiPaths(openapi);
     if (routes.length > 0) {

package/src/to-zod.spec.ts

@@ -289,9 +289,12 @@ describe("openApiToZodTsCode", () => {
 
       const result = openApiToZodTsCode(openapi);
       expect(result).toContain("import { z } from 'zod';");
-      expect(result).toContain("export const UserSchema =");
+      // New format: interface + ZodType annotation
+      expect(result).toContain("export interface User {");
+      expect(result).toContain("export const UserSchema: z.ZodType<User> =");
       expect(result).toContain("z.object({ name: z.string() })");
-      expect(result).toContain("export type User = z.infer<typeof UserSchema>;");
+      // Type assertion for compile-time verification
+      expect(result).toContain("type _AssertUser = _AssertEqual<User, z.infer<typeof UserSchema>>;");
     });
 
     it("should convert OpenAPI document with multiple schemas", () => {
@@ -317,10 +320,11 @@ describe("openApiToZodTsCode", () => {
       };
 
       const result = openApiToZodTsCode(openapi);
-      expect(result).toContain("export const UserSchema =");
-      expect(result).toContain("export const ProductSchema =");
-      expect(result).toContain("export type User =");
-      expect(result).toContain("export type Product =");
+      // New format: interface + ZodType annotation
+      expect(result).toContain("export interface User {");
+      expect(result).toContain("export interface Product {");
+      expect(result).toContain("export const UserSchema: z.ZodType<User> =");
+      expect(result).toContain("export const ProductSchema: z.ZodType<Product> =");
     });
 
     it("should include file header comment", () => {