@alt-stack/zod-openapi 1.2.0 → 1.3.1

package/src/interface-generator.ts

@@ -5,14 +5,75 @@
  * 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.
  *
@@ -20,7 +81,10 @@ function quotePropertyName(name: string): string {
  * schemaToTypeString({ type: 'string' }) // => 'string'
  * schemaToTypeString({ type: 'object', properties: { id: { type: 'string' } } }) // => '{ id?: string }'
  */
-export function schemaToTypeString(schema: AnySchema): string {
+export function schemaToTypeString(
+  schema: AnySchema,
+  options?: SchemaToTypeOptions,
+): string {
   if (!schema || typeof schema !== "object") return "unknown";
 
   // Handle $ref
@@ -44,14 +108,14 @@ export function schemaToTypeString(schema: AnySchema): string {
   // Handle oneOf (union)
   if ("oneOf" in schema && Array.isArray(schema["oneOf"])) {
     const unionMembers = (schema["oneOf"] as AnySchema[]).map((s) =>
-      schemaToTypeString(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),
+      schemaToTypeString(s, options),
     );
     result = intersectionMembers.length > 1
       ? `(${intersectionMembers.join(" & ")})`
@@ -60,15 +124,18 @@ export function schemaToTypeString(schema: AnySchema): string {
   // 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),
+      schemaToTypeString(s, options),
     );
     result = unionMembers.length > 1 ? `(${unionMembers.join(" | ")})` : unionMembers[0] ?? "unknown";
   }
   // Handle type-based schemas
   else {
     switch (schema["type"]) {
-      case "string":
-        if (schema["enum"] && Array.isArray(schema["enum"])) {
+      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))
@@ -77,36 +144,41 @@ export function schemaToTypeString(schema: AnySchema): string {
           result = "string";
         }
         break;
+      }
       case "number":
-      case "integer":
-        if (schema["enum"] && Array.isArray(schema["enum"])) {
+      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 = "boolean";
+        result = getRegisteredOutputAlias(schema, options) ?? "boolean";
         break;
       case "null":
         result = "null";
         break;
       case "array":
         if (schema["items"]) {
-          const itemType = schemaToTypeString(schema["items"] as AnySchema);
+          const itemType = schemaToTypeString(schema["items"] as AnySchema, options);
           result = `Array<${itemType}>`;
         } else {
           result = "unknown[]";
         }
         break;
       case "object":
-        result = objectSchemaToTypeString(schema);
+        result = objectSchemaToTypeString(schema, options);
         break;
       default:
         // Try to detect object from properties
         if (schema["properties"]) {
-          result = objectSchemaToTypeString(schema);
+          result = objectSchemaToTypeString(schema, options);
         } else if (schema["enum"] && Array.isArray(schema["enum"])) {
           // Untyped enum
           result = (schema["enum"] as unknown[])
@@ -130,7 +202,10 @@ export function schemaToTypeString(schema: AnySchema): string {
 /**
  * Converts an OpenAPI object schema to a TypeScript object type string.
  */
-function objectSchemaToTypeString(schema: AnySchema): 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"];
@@ -144,7 +219,7 @@ function objectSchemaToTypeString(schema: AnySchema): string {
   if (properties) {
     for (const [propName, propSchema] of Object.entries(properties)) {
       const isRequired = required.has(propName);
-      const propType = schemaToTypeString(propSchema);
+      const propType = schemaToTypeString(propSchema, options);
       const quotedName = quotePropertyName(propName);
       propertyStrings.push(
         `${quotedName}${isRequired ? "" : "?"}: ${propType}`,
@@ -159,7 +234,7 @@ function objectSchemaToTypeString(schema: AnySchema): string {
     typeof additionalProperties === "object" &&
     additionalProperties !== null
   ) {
-    const additionalType = schemaToTypeString(additionalProperties as AnySchema);
+    const additionalType = schemaToTypeString(additionalProperties as AnySchema, options);
     propertyStrings.push(`[key: string]: ${additionalType}`);
   }
 
@@ -173,13 +248,17 @@ function objectSchemaToTypeString(schema: AnySchema): string {
  * generateInterface('User', { type: 'object', properties: { id: { type: 'string' } }, required: ['id'] })
  * // => 'export interface User { id: string; }'
  */
-export function generateInterface(name: string, schema: AnySchema): 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)};`;
+    return `export type ${name} = ${schemaToTypeString(schema, options)};`;
   }
 
   const lines: string[] = [];
@@ -188,7 +267,7 @@ export function generateInterface(name: string, schema: AnySchema): string {
   if (properties) {
     for (const [propName, propSchema] of Object.entries(properties)) {
       const isRequired = required.has(propName);
-      const propType = schemaToTypeString(propSchema);
+      const propType = schemaToTypeString(propSchema, options);
       const quotedName = quotePropertyName(propName);
       lines.push(`  ${quotedName}${isRequired ? "" : "?"}: ${propType};`);
     }
@@ -202,7 +281,7 @@ export function generateInterface(name: string, schema: AnySchema): string {
     typeof additionalProperties === "object" &&
     additionalProperties !== null
   ) {
-    const additionalType = schemaToTypeString(additionalProperties as AnySchema);
+    const additionalType = schemaToTypeString(additionalProperties as AnySchema, options);
     lines.push(`  [key: string]: ${additionalType};`);
   }
 

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,7 +14,7 @@ import {
   generateRouteSchemaNames,
   type RouteInfo,
 } from "./routes";
-import { generateInterface, schemaToTypeString } from "./interface-generator";
+import { generateInterface, schemaExportNameToOutputAlias } from "./interface-generator";
 
 const validIdentifierRegex = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/;
 
@@ -442,6 +442,8 @@ export const openApiToZodTsCode = (
 
   // 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];
@@ -451,11 +453,11 @@ export const openApiToZodTsCode = (
       const typeName = name;
 
       // Generate interface (concrete type in .d.ts)
-      lines.push(generateInterface(typeName, schema));
+      schemaBlocks.push(generateInterface(typeName, schema, { outputSchemaNames }));
 
       // Generate schema with ZodType<T> annotation (simple type in .d.ts)
-      lines.push(`export const ${schemaName}: z.ZodType<${typeName}> = ${zodExpr};`);
-      lines.push("");
+      schemaBlocks.push(`export const ${schemaName} = ${zodExpr};`);
+      schemaBlocks.push("");
 
       // Add type assertion to verify interface matches schema
       typeAssertions.push(`type _Assert${typeName} = _AssertEqual<${typeName}, z.infer<typeof ${schemaName}>>;`);
@@ -466,6 +468,17 @@ 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");

package/src/to-zod.spec.ts

@@ -289,10 +289,9 @@ describe("openApiToZodTsCode", () => {
 
       const result = openApiToZodTsCode(openapi);
       expect(result).toContain("import { z } from 'zod';");
-      // New format: interface + ZodType annotation
+      // New format: interface + schema without explicit type 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 const UserSchema = z.object({ name: z.string() })");
       // Type assertion for compile-time verification
       expect(result).toContain("type _AssertUser = _AssertEqual<User, z.infer<typeof UserSchema>>;");
     });
@@ -320,11 +319,11 @@ describe("openApiToZodTsCode", () => {
       };
 
       const result = openApiToZodTsCode(openapi);
-      // New format: interface + ZodType annotation
+      // New format: interface + schema without explicit type 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> =");
+      expect(result).toContain("export const UserSchema = z.object({ name: z.string() })");
+      expect(result).toContain("export const ProductSchema = z.object({ id: z.number() })");
     });
 
     it("should include file header comment", () => {