@alt-stack/zod-openapi 1.1.2 → 1.2.0

package/src/interface-generator.ts

@@ -0,0 +1,211 @@
+/**
+ * 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 type { AnySchema } from "./types/types";
+
+const validIdentifierRegex = /^[a-zA-Z_$][a-zA-Z0-9_$]*$/;
+
+function quotePropertyName(name: string): string {
+  return validIdentifierRegex.test(name) ? name : `'${name}'`;
+}
+
+/**
+ * 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): 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),
+    );
+    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),
+    );
+    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),
+    );
+    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"])) {
+          // String enum
+          result = (schema["enum"] as string[])
+            .map((v) => JSON.stringify(v))
+            .join(" | ");
+        } else {
+          result = "string";
+        }
+        break;
+      case "number":
+      case "integer":
+        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";
+        break;
+      case "null":
+        result = "null";
+        break;
+      case "array":
+        if (schema["items"]) {
+          const itemType = schemaToTypeString(schema["items"] as AnySchema);
+          result = `Array<${itemType}>`;
+        } else {
+          result = "unknown[]";
+        }
+        break;
+      case "object":
+        result = objectSchemaToTypeString(schema);
+        break;
+      default:
+        // Try to detect object from properties
+        if (schema["properties"]) {
+          result = objectSchemaToTypeString(schema);
+        } 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): 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);
+      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);
+    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): 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)};`;
+  }
+
+  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);
+      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);
+    lines.push(`  [key: string]: ${additionalType};`);
+  }
+
+  lines.push("}");
+  return lines.join("\n");
+}

package/src/schema-dedup.ts

@@ -0,0 +1,199 @@
+import type { AnySchema } from "./types/types";
+
+/**
+ * Schema deduplication utilities for optimizing generated TypeScript types.
+ *
+ * This module provides fingerprinting and registry functionality to detect
+ * structurally identical schemas and generate them only once, reducing
+ * memory usage in consuming TypeScript projects.
+ */
+
+/**
+ * Recursively sorts an object's keys to create a stable representation.
+ * This ensures that {a: 1, b: 2} and {b: 2, a: 1} produce the same fingerprint.
+ */
+function sortObjectDeep(obj: unknown): unknown {
+  if (obj === null || typeof obj !== "object") return obj;
+  if (Array.isArray(obj)) return obj.map(sortObjectDeep);
+
+  const sorted: Record<string, unknown> = {};
+  const keys = Object.keys(obj as Record<string, unknown>).sort();
+  for (const key of keys) {
+    sorted[key] = sortObjectDeep((obj as Record<string, unknown>)[key]);
+  }
+  return sorted;
+}
+
+/**
+ * Generates a canonical fingerprint for an OpenAPI schema.
+ * Identical schemas will produce identical fingerprints.
+ */
+export function getSchemaFingerprint(schema: AnySchema): string {
+  return JSON.stringify(sortObjectDeep(schema));
+}
+
+/**
+ * Registry for tracking unique schemas and their canonical names.
+ */
+export interface SchemaRegistry {
+  /** Map from fingerprint to the first schema name that used it */
+  fingerprintToName: Map<string, string>;
+  /** Map from schema name to its fingerprint (for reverse lookup) */
+  nameToFingerprint: Map<string, string>;
+}
+
+/**
+ * Creates a new empty schema registry.
+ */
+export function createSchemaRegistry(): SchemaRegistry {
+  return {
+    fingerprintToName: new Map(),
+    nameToFingerprint: new Map(),
+  };
+}
+
+/**
+ * Result of registering a schema.
+ */
+export interface RegisterSchemaResult {
+  /** Whether this is a new unique schema */
+  isNew: boolean;
+  /** The canonical name for this schema (may be different from input name if duplicate) */
+  canonicalName: string;
+}
+
+/**
+ * Registers a schema in the registry. If an identical schema already exists,
+ * returns the existing canonical name instead.
+ */
+export function registerSchema(
+  registry: SchemaRegistry,
+  name: string,
+  schema: AnySchema,
+): RegisterSchemaResult {
+  const fingerprint = getSchemaFingerprint(schema);
+
+  const existing = registry.fingerprintToName.get(fingerprint);
+  if (existing) {
+    return { isNew: false, canonicalName: existing };
+  }
+
+  registry.fingerprintToName.set(fingerprint, name);
+  registry.nameToFingerprint.set(name, fingerprint);
+  return { isNew: true, canonicalName: name };
+}
+
+/**
+ * Pre-registers a schema with a specific fingerprint.
+ * Used for common schemas that should take priority.
+ */
+export function preRegisterSchema(
+  registry: SchemaRegistry,
+  name: string,
+  fingerprint: string,
+): void {
+  registry.fingerprintToName.set(fingerprint, name);
+  registry.nameToFingerprint.set(name, fingerprint);
+}
+
+/**
+ * Extracts the error code from an OpenAPI error schema.
+ * Looks for patterns like: { error: { code: enum(['UNAUTHORIZED']) } }
+ */
+export function extractErrorCode(schema: AnySchema): string | null {
+  const properties = schema?.["properties"] as Record<string, AnySchema> | undefined;
+  const errorObj = properties?.["error"] as AnySchema | undefined;
+  const errorProps = errorObj?.["properties"] as Record<string, AnySchema> | undefined;
+  const codeSchema = errorProps?.["code"] as AnySchema | undefined;
+  const codeEnum = codeSchema?.["enum"] as string[] | undefined;
+
+  if (Array.isArray(codeEnum) && codeEnum.length === 1) {
+    return codeEnum[0]!;
+  }
+  return null;
+}
+
+/**
+ * Converts an error code like UNAUTHORIZED or NOT_FOUND to PascalCase.
+ * UNAUTHORIZED -> Unauthorized
+ * NOT_FOUND -> NotFound
+ */
+export function errorCodeToPascalCase(code: string): string {
+  return code
+    .split("_")
+    .map((part) => part.charAt(0) + part.slice(1).toLowerCase())
+    .join("");
+}
+
+/**
+ * Generates a common error schema name from an error code.
+ * UNAUTHORIZED -> UnauthorizedErrorSchema
+ */
+export function generateCommonErrorSchemaName(errorCode: string): string {
+  return `${errorCodeToPascalCase(errorCode)}ErrorSchema`;
+}
+
+/**
+ * Represents a common schema that appears multiple times.
+ */
+export interface CommonSchema {
+  /** The canonical name for this schema */
+  name: string;
+  /** The schema definition */
+  schema: AnySchema;
+  /** The fingerprint for deduplication */
+  fingerprint: string;
+  /** Number of times this schema appears */
+  count: number;
+}
+
+/**
+ * Scans schemas and identifies those that appear multiple times.
+ * Returns common schemas sorted by count (most common first).
+ */
+export function findCommonSchemas(
+  schemas: Array<{ name: string; schema: AnySchema }>,
+  minCount: number = 2,
+): CommonSchema[] {
+  const fingerprints = new Map<
+    string,
+    { schema: AnySchema; names: string[]; errorCode: string | null }
+  >();
+
+  // Count occurrences of each unique schema
+  for (const { name, schema } of schemas) {
+    const fingerprint = getSchemaFingerprint(schema);
+    const existing = fingerprints.get(fingerprint);
+
+    if (existing) {
+      existing.names.push(name);
+    } else {
+      fingerprints.set(fingerprint, {
+        schema,
+        names: [name],
+        errorCode: extractErrorCode(schema),
+      });
+    }
+  }
+
+  // Filter to schemas appearing minCount+ times
+  const commonSchemas: CommonSchema[] = [];
+  for (const [fingerprint, data] of fingerprints) {
+    if (data.names.length >= minCount) {
+      // Generate a semantic name if it's an error schema, otherwise use first occurrence
+      const name = data.errorCode
+        ? generateCommonErrorSchemaName(data.errorCode)
+        : data.names[0]!;
+
+      commonSchemas.push({
+        name,
+        schema: data.schema,
+        fingerprint,
+        count: data.names.length,
+      });
+    }
+  }
+
+  // Sort by count descending (most common first)
+  return commonSchemas.sort((a, b) => b.count - a.count);
+}

package/src/to-typescript.spec.ts

@@ -522,5 +522,223 @@ describe("openApiToZodTsCode with routes", () => {
       expect(result).toContain("'/users/{id}':");
     });
   });
+
+  describe("schema deduplication", () => {
+    it("should deduplicate identical error responses across endpoints", () => {
+      const unauthorizedError = {
+        type: "object",
+        properties: {
+          error: {
+            type: "object",
+            properties: {
+              code: { type: "string", enum: ["UNAUTHORIZED"] },
+              message: { type: "string" },
+            },
+            required: ["code", "message"],
+          },
+        },
+        required: ["error"],
+      };
+
+      const openapi = {
+        components: { schemas: {} },
+        paths: {
+          "/users": {
+            get: {
+              responses: {
+                "200": {
+                  content: {
+                    "application/json": {
+                      schema: { type: "object", properties: {} },
+                    },
+                  },
+                },
+                "401": {
+                  content: {
+                    "application/json": { schema: unauthorizedError },
+                  },
+                },
+              },
+            },
+            post: {
+              responses: {
+                "200": {
+                  content: {
+                    "application/json": {
+                      schema: { type: "object", properties: {} },
+                    },
+                  },
+                },
+                "401": {
+                  content: {
+                    "application/json": { schema: unauthorizedError },
+                  },
+                },
+              },
+            },
+          },
+          "/items": {
+            get: {
+              responses: {
+                "200": {
+                  content: {
+                    "application/json": {
+                      schema: { type: "object", properties: {} },
+                    },
+                  },
+                },
+                "401": {
+                  content: {
+                    "application/json": { schema: unauthorizedError },
+                  },
+                },
+              },
+            },
+          },
+        },
+      };
+
+      const result = openApiToZodTsCode(openapi, undefined, {
+        includeRoutes: true,
+      });
+
+      // Should generate a common error schema
+      expect(result).toContain("// Common Error Schemas (deduplicated)");
+      expect(result).toContain("UnauthorizedErrorSchema");
+
+      // Route-specific schemas should reference the common schema
+      expect(result).toContain(
+        "export const GetUsers401ErrorResponse = UnauthorizedErrorSchema;",
+      );
+      expect(result).toContain(
+        "export const PostUsers401ErrorResponse = UnauthorizedErrorSchema;",
+      );
+      expect(result).toContain(
+        "export const GetItems401ErrorResponse = UnauthorizedErrorSchema;",
+      );
+
+      // Response object should reference the canonical schema
+      expect(result).toContain("'401': UnauthorizedErrorSchema");
+    });
+
+    it("should deduplicate identical success responses across endpoints", () => {
+      const userSchema = {
+        type: "object",
+        properties: {
+          id: { type: "string" },
+          name: { type: "string" },
+        },
+        required: ["id", "name"],
+      };
+
+      const openapi = {
+        components: { schemas: {} },
+        paths: {
+          "/users/{id}": {
+            get: {
+              parameters: [
+                {
+                  name: "id",
+                  in: "path",
+                  required: true,
+                  schema: { type: "string" },
+                },
+              ],
+              responses: {
+                "200": {
+                  content: {
+                    "application/json": { schema: userSchema },
+                  },
+                },
+              },
+            },
+            put: {
+              parameters: [
+                {
+                  name: "id",
+                  in: "path",
+                  required: true,
+                  schema: { type: "string" },
+                },
+              ],
+              responses: {
+                "200": {
+                  content: {
+                    "application/json": { schema: userSchema },
+                  },
+                },
+              },
+            },
+          },
+        },
+      };
+
+      const result = openApiToZodTsCode(openapi, undefined, {
+        includeRoutes: true,
+      });
+
+      // The first occurrence becomes the canonical schema
+      expect(result).toContain("export const GetUsersId200Response =");
+
+      // The second should be an alias to the first
+      expect(result).toContain(
+        "export const PutUsersId200Response = GetUsersId200Response;",
+      );
+    });
+
+    it("should not deduplicate different schemas", () => {
+      const openapi = {
+        components: { schemas: {} },
+        paths: {
+          "/users": {
+            get: {
+              responses: {
+                "200": {
+                  content: {
+                    "application/json": {
+                      schema: {
+                        type: "object",
+                        properties: { users: { type: "array" } },
+                      },
+                    },
+                  },
+                },
+                "401": {
+                  content: {
+                    "application/json": {
+                      schema: {
+                        type: "object",
+                        properties: {
+                          error: {
+                            type: "object",
+                            properties: {
+                              code: { type: "string", enum: ["UNAUTHORIZED"] },
+                            },
+                          },
+                        },
+                      },
+                    },
+                  },
+                },
+              },
+            },
+          },
+        },
+      };
+
+      const result = openApiToZodTsCode(openapi, undefined, {
+        includeRoutes: true,
+      });
+
+      // Both should be separate schemas since they're different
+      expect(result).toContain("export const GetUsers200Response =");
+      expect(result).toContain("export const GetUsers401ErrorResponse =");
+
+      // They should not reference each other
+      expect(result).not.toContain(
+        "GetUsers401ErrorResponse = GetUsers200Response",
+      );
+    });
+  });
 });