@alt-stack/zod-openapi 1.0.1

package/src/dependencies.spec.ts

@@ -0,0 +1,440 @@
+import { describe, it, expect } from "vitest";
+import {
+  extractSchemaDependencies,
+  topologicalSortSchemas,
+} from "./dependencies";
+import type { AnySchema } from "./types/types";
+
+describe("extractSchemaDependencies", () => {
+  describe("basic $ref extraction", () => {
+    it("should extract single $ref dependency", () => {
+      const schema: AnySchema = {
+        $ref: "#/components/schemas/User",
+      };
+
+      const result = extractSchemaDependencies(schema);
+      expect(result).toEqual(["User"]);
+    });
+
+    it("should extract multiple $ref dependencies", () => {
+      const schema: AnySchema = {
+        type: "object",
+        properties: {
+          user: { $ref: "#/components/schemas/User" },
+          profile: { $ref: "#/components/schemas/Profile" },
+        },
+      };
+
+      const result = extractSchemaDependencies(schema);
+      expect(result.sort()).toEqual(["Profile", "User"]);
+    });
+
+    it("should handle $ref with URL encoding", () => {
+      const schema: AnySchema = {
+        $ref: "#/components/schemas/User%20Profile",
+      };
+
+      const result = extractSchemaDependencies(schema);
+      expect(result).toEqual(["User Profile"]);
+    });
+  });
+
+  describe("nested schema dependencies", () => {
+    it("should extract dependencies from nested objects", () => {
+      const schema: AnySchema = {
+        type: "object",
+        properties: {
+          user: {
+            type: "object",
+            properties: {
+              profile: { $ref: "#/components/schemas/Profile" },
+            },
+          },
+        },
+      };
+
+      const result = extractSchemaDependencies(schema);
+      expect(result).toEqual(["Profile"]);
+    });
+
+    it("should extract dependencies from arrays", () => {
+      const schema: AnySchema = {
+        type: "array",
+        items: {
+          $ref: "#/components/schemas/User",
+        },
+      };
+
+      const result = extractSchemaDependencies(schema);
+      expect(result).toEqual(["User"]);
+    });
+
+    it("should extract dependencies from nested arrays", () => {
+      const schema: AnySchema = {
+        type: "array",
+        items: {
+          type: "array",
+          items: {
+            $ref: "#/components/schemas/User",
+          },
+        },
+      };
+
+      const result = extractSchemaDependencies(schema);
+      expect(result).toEqual(["User"]);
+    });
+  });
+
+  describe("oneOf dependencies", () => {
+    it("should extract dependencies from oneOf", () => {
+      const schema: AnySchema = {
+        oneOf: [
+          { $ref: "#/components/schemas/User" },
+          { $ref: "#/components/schemas/Admin" },
+        ],
+      };
+
+      const result = extractSchemaDependencies(schema);
+      expect(result.sort()).toEqual(["Admin", "User"]);
+    });
+
+    it("should extract nested dependencies from oneOf", () => {
+      const schema: AnySchema = {
+        oneOf: [
+          {
+            type: "object",
+            properties: {
+              user: { $ref: "#/components/schemas/User" },
+            },
+          },
+        ],
+      };
+
+      const result = extractSchemaDependencies(schema);
+      expect(result).toEqual(["User"]);
+    });
+  });
+
+  describe("allOf dependencies", () => {
+    it("should extract dependencies from allOf", () => {
+      const schema: AnySchema = {
+        allOf: [
+          { $ref: "#/components/schemas/Base" },
+          { $ref: "#/components/schemas/Extended" },
+        ],
+      };
+
+      const result = extractSchemaDependencies(schema);
+      expect(result.sort()).toEqual(["Base", "Extended"]);
+    });
+  });
+
+  describe("complex nested structures", () => {
+    it("should extract all dependencies from complex schema", () => {
+      const schema: AnySchema = {
+        type: "object",
+        properties: {
+          users: {
+            type: "array",
+            items: { $ref: "#/components/schemas/User" },
+          },
+          metadata: {
+            type: "object",
+            properties: {
+              creator: { $ref: "#/components/schemas/User" },
+              updater: { $ref: "#/components/schemas/User" },
+            },
+          },
+        },
+      };
+
+      const result = extractSchemaDependencies(schema);
+      expect(result).toEqual(["User"]);
+    });
+
+    it("should handle duplicate dependencies", () => {
+      const schema: AnySchema = {
+        type: "object",
+        properties: {
+          user1: { $ref: "#/components/schemas/User" },
+          user2: { $ref: "#/components/schemas/User" },
+        },
+      };
+
+      const result = extractSchemaDependencies(schema);
+      expect(result).toEqual(["User"]);
+    });
+  });
+
+  describe("edge cases", () => {
+    it("should handle invalid $ref format", () => {
+      const schema: AnySchema = {
+        $ref: "invalid-ref",
+      };
+
+      const result = extractSchemaDependencies(schema);
+      expect(result).toEqual([]);
+    });
+
+    it("should handle null schema", () => {
+      const result = extractSchemaDependencies(null);
+      expect(result).toEqual([]);
+    });
+
+    it("should handle schema without $ref", () => {
+      const schema: AnySchema = {
+        type: "string",
+      };
+
+      const result = extractSchemaDependencies(schema);
+      expect(result).toEqual([]);
+    });
+
+    it("should handle circular references without infinite loop", () => {
+      const user: AnySchema = {
+        type: "object",
+        properties: {
+          friend: { $ref: "#/components/schemas/User" },
+        },
+      };
+
+      const result = extractSchemaDependencies(user);
+      expect(result).toEqual(["User"]);
+    });
+  });
+});
+
+describe("topologicalSortSchemas", () => {
+  describe("simple dependency ordering", () => {
+    it("should sort schemas with single dependency", () => {
+      const schemas: Record<string, AnySchema> = {
+        User: {
+          type: "object",
+          properties: {
+            profile: { $ref: "#/components/schemas/Profile" },
+          },
+        },
+        Profile: {
+          type: "object",
+          properties: {
+            name: { type: "string" },
+          },
+        },
+      };
+
+      const result = topologicalSortSchemas(schemas);
+      expect(result.indexOf("Profile")).toBeLessThan(result.indexOf("User"));
+    });
+
+    it("should sort schemas with multiple dependencies", () => {
+      const schemas: Record<string, AnySchema> = {
+        User: {
+          type: "object",
+          properties: {
+            profile: { $ref: "#/components/schemas/Profile" },
+            settings: { $ref: "#/components/schemas/Settings" },
+          },
+        },
+        Profile: {
+          type: "object",
+          properties: {
+            name: { type: "string" },
+          },
+        },
+        Settings: {
+          type: "object",
+          properties: {
+            theme: { type: "string" },
+          },
+        },
+      };
+
+      const result = topologicalSortSchemas(schemas);
+      expect(result.indexOf("Profile")).toBeLessThan(result.indexOf("User"));
+      expect(result.indexOf("Settings")).toBeLessThan(result.indexOf("User"));
+    });
+
+    it("should sort schemas with transitive dependencies", () => {
+      const schemas: Record<string, AnySchema> = {
+        A: {
+          type: "object",
+          properties: {
+            b: { $ref: "#/components/schemas/B" },
+          },
+        },
+        B: {
+          type: "object",
+          properties: {
+            c: { $ref: "#/components/schemas/C" },
+          },
+        },
+        C: {
+          type: "object",
+          properties: {
+            value: { type: "string" },
+          },
+        },
+      };
+
+      const result = topologicalSortSchemas(schemas);
+      expect(result.indexOf("C")).toBeLessThan(result.indexOf("B"));
+      expect(result.indexOf("B")).toBeLessThan(result.indexOf("A"));
+    });
+  });
+
+  describe("independent schemas", () => {
+    it("should handle schemas without dependencies", () => {
+      const schemas: Record<string, AnySchema> = {
+        User: {
+          type: "object",
+          properties: {
+            name: { type: "string" },
+          },
+        },
+        Product: {
+          type: "object",
+          properties: {
+            id: { type: "number" },
+          },
+        },
+      };
+
+      const result = topologicalSortSchemas(schemas);
+      expect(result).toContain("User");
+      expect(result).toContain("Product");
+      expect(result.length).toBe(2);
+    });
+
+    it("should handle empty schemas object", () => {
+      const schemas: Record<string, AnySchema> = {};
+      const result = topologicalSortSchemas(schemas);
+      expect(result).toEqual([]);
+    });
+  });
+
+  describe("circular dependencies", () => {
+    it("should handle circular dependencies gracefully", () => {
+      const schemas: Record<string, AnySchema> = {
+        A: {
+          type: "object",
+          properties: {
+            b: { $ref: "#/components/schemas/B" },
+          },
+        },
+        B: {
+          type: "object",
+          properties: {
+            a: { $ref: "#/components/schemas/A" },
+          },
+        },
+      };
+
+      const result = topologicalSortSchemas(schemas);
+      expect(result).toContain("A");
+      expect(result).toContain("B");
+      expect(result.length).toBe(2);
+    });
+
+    it("should handle three-way circular dependency", () => {
+      const schemas: Record<string, AnySchema> = {
+        A: {
+          type: "object",
+          properties: {
+            b: { $ref: "#/components/schemas/B" },
+          },
+        },
+        B: {
+          type: "object",
+          properties: {
+            c: { $ref: "#/components/schemas/C" },
+          },
+        },
+        C: {
+          type: "object",
+          properties: {
+            a: { $ref: "#/components/schemas/A" },
+          },
+        },
+      };
+
+      const result = topologicalSortSchemas(schemas);
+      expect(result).toContain("A");
+      expect(result).toContain("B");
+      expect(result).toContain("C");
+      expect(result.length).toBe(3);
+    });
+  });
+
+  describe("external dependencies", () => {
+    it("should ignore dependencies that are not in schemas", () => {
+      const schemas: Record<string, AnySchema> = {
+        User: {
+          type: "object",
+          properties: {
+            external: { $ref: "#/components/schemas/External" },
+            local: { $ref: "#/components/schemas/Profile" },
+          },
+        },
+        Profile: {
+          type: "object",
+          properties: {
+            name: { type: "string" },
+          },
+        },
+      };
+
+      const result = topologicalSortSchemas(schemas);
+      expect(result.indexOf("Profile")).toBeLessThan(result.indexOf("User"));
+      expect(result).not.toContain("External");
+    });
+  });
+
+  describe("complex scenarios", () => {
+    it("should handle mixed dependency structure", () => {
+      const schemas: Record<string, AnySchema> = {
+        User: {
+          type: "object",
+          properties: {
+            profile: { $ref: "#/components/schemas/Profile" },
+          },
+        },
+        Profile: {
+          type: "object",
+          properties: {
+            avatar: { $ref: "#/components/schemas/Image" },
+          },
+        },
+        Image: {
+          type: "object",
+          properties: {
+            url: { type: "string" },
+          },
+        },
+        Product: {
+          type: "object",
+          properties: {
+            id: { type: "number" },
+          },
+        },
+      };
+
+      const result = topologicalSortSchemas(schemas);
+      expect(result.indexOf("Image")).toBeLessThan(result.indexOf("Profile"));
+      expect(result.indexOf("Profile")).toBeLessThan(result.indexOf("User"));
+      expect(result).toContain("Product");
+      expect(result.length).toBe(4);
+    });
+
+    it("should preserve all schema names", () => {
+      const schemas: Record<string, AnySchema> = {
+        A: { type: "string" },
+        B: { type: "number" },
+        C: { type: "boolean" },
+      };
+
+      const result = topologicalSortSchemas(schemas);
+      expect(result.sort()).toEqual(["A", "B", "C"]);
+    });
+  });
+});
+

package/src/dependencies.ts

@@ -0,0 +1,176 @@
+import type { AnySchema } from "./types/types";
+
+/**
+ * Extracts all schema references ($ref) from an OpenAPI schema by recursively
+ * traversing its structure.
+ *
+ * This function is used during the OpenAPI-to-Zod conversion process to identify
+ * which schemas a given schema depends on. It traverses all OpenAPI schema
+ * structures including objects, arrays, unions (oneOf), intersections (allOf),
+ * conditionals (if/then/else), and discriminator mappings to find all $ref
+ * references that point to other schemas in the components/schemas section.
+ *
+ * The extracted dependency names are used by `topologicalSortSchemas` to build
+ * a dependency graph and determine the correct order for generating Zod schemas,
+ * ensuring that referenced schemas are defined before they are used in the
+ * generated TypeScript code.
+ *
+ * @param schema - The OpenAPI schema to extract dependencies from
+ * @returns An array of schema names that this schema references (via $ref)
+ */
+export function extractSchemaDependencies(schema: AnySchema): string[] {
+  const dependencies: Set<string> = new Set();
+  const visited = new WeakSet();
+
+  function traverse(obj: any): void {
+    if (!obj || typeof obj !== "object") return;
+
+    if (visited.has(obj)) return;
+    visited.add(obj);
+
+    if (obj["$ref"] && typeof obj["$ref"] === "string") {
+      const match = (obj["$ref"] as string).match(
+        /#\/components\/schemas\/(.+)/,
+      );
+      if (match && match[1]) {
+        dependencies.add(decodeURIComponent(match[1]));
+      }
+      return;
+    }
+
+    if (Array.isArray(obj)) {
+      obj.forEach(traverse);
+      return;
+    }
+
+    if (obj.properties && typeof obj.properties === "object") {
+      for (const propValue of Object.values(obj.properties)) {
+        traverse(propValue);
+      }
+    }
+
+    const schemaKeys = [
+      "items",
+      "oneOf",
+      "allOf",
+      "anyOf",
+      "not",
+      "if",
+      "then",
+      "else",
+      "prefixItems",
+      "contains",
+      "propertyNames",
+      "dependentSchemas",
+    ];
+
+    for (const key of schemaKeys) {
+      if (obj[key]) {
+        traverse(obj[key]);
+      }
+    }
+
+    if (
+      obj.additionalProperties &&
+      typeof obj.additionalProperties === "object"
+    ) {
+      traverse(obj.additionalProperties);
+    }
+
+    if (obj.discriminator?.mapping) {
+      Object.values(obj.discriminator.mapping).forEach(traverse);
+    }
+  }
+
+  traverse(schema);
+  return Array.from(dependencies);
+}
+
+/**
+ * Sorts OpenAPI schemas topologically based on their dependencies to ensure
+ * correct generation order.
+ *
+ * When converting OpenAPI schemas to Zod schemas and generating TypeScript code,
+ * schemas must be defined before they are referenced. For example, if `UserSchema`
+ * references `ProfileSchema` (via $ref), then `ProfileSchema` must be generated
+ * before `UserSchema` to avoid "undefined variable" errors in the generated code.
+ *
+ * This function uses Kahn's algorithm for topological sorting to order schemas
+ * such that all dependencies come before their dependents. It:
+ * 1. Extracts dependencies for each schema using `extractSchemaDependencies`
+ * 2. Builds a dependency graph and computes in-degrees
+ * 3. Sorts schemas starting with those that have no dependencies (in-degree 0)
+ * 4. Handles circular dependencies gracefully by appending any remaining schemas
+ *    that couldn't be sorted (though this indicates a problematic schema structure)
+ *
+ * This function is called by `openApiToZodTsCode` to determine the order in which
+ * schemas should be converted and emitted in the generated TypeScript file.
+ *
+ * @param schemas - A record mapping schema names to their OpenAPI schema definitions
+ * @returns An array of schema names sorted in topological order (dependencies before dependents)
+ */
+export function topologicalSortSchemas(
+  schemas: Record<string, AnySchema>,
+): string[] {
+  const schemaNames = Object.keys(schemas);
+  const dependencies: Map<string, string[]> = new Map();
+  const inDegree: Map<string, number> = new Map();
+  const sorted: string[] = [];
+  const queue: string[] = [];
+  const dependents: Map<string, string[]> = new Map();
+
+  for (const name of schemaNames) {
+    dependencies.set(name, []);
+    dependents.set(name, []);
+    inDegree.set(name, 0);
+  }
+
+  for (const name of schemaNames) {
+    const schemaValue = schemas[name];
+    if (schemaValue) {
+      const deps = extractSchemaDependencies(schemaValue);
+      const validDeps = deps.filter((dep) => schemaNames.includes(dep));
+      dependencies.set(name, validDeps);
+
+      for (const dep of validDeps) {
+        const currentDependents = dependents.get(dep) || [];
+        currentDependents.push(name);
+        dependents.set(dep, currentDependents);
+      }
+    }
+  }
+
+  for (const [name, deps] of dependencies.entries()) {
+    inDegree.set(name, deps.length);
+  }
+
+  for (const [name, degree] of inDegree.entries()) {
+    if (degree === 0) {
+      queue.push(name);
+    }
+  }
+
+  while (queue.length > 0) {
+    const current = queue.shift()!;
+    sorted.push(current);
+
+    const currentDependents = dependents.get(current) || [];
+    for (const dependent of currentDependents) {
+      const newDegree = (inDegree.get(dependent) || 0) - 1;
+      inDegree.set(dependent, newDegree);
+      if (newDegree === 0) {
+        queue.push(dependent);
+      }
+    }
+  }
+
+  if (sorted.length !== schemaNames.length) {
+    for (const name of schemaNames) {
+      if (!sorted.includes(name)) {
+        sorted.push(name);
+      }
+    }
+  }
+
+  return sorted;
+}

package/src/index.ts

@@ -0,0 +1,27 @@
+export { openApiToZodTsCode } from "./to-typescript.js";
+export {
+  registerZodSchemaToOpenApiSchema,
+  clearZodSchemaToOpenApiSchemaRegistry,
+  getSchemaExportedVariableNameForStringFormat,
+  SUPPORTED_STRING_FORMATS,
+  schemaRegistry,
+} from "./registry.js";
+export type {
+  ZodOpenApiRegistrationString,
+  ZodOpenApiRegistrationStrings,
+  ZodOpenApiRegistrationPrimitive,
+  ZodOpenApiRegistration,
+} from "./registry.js";
+export { convertSchemaToZodString } from "./to-zod.js";
+export {
+  parseOpenApiPaths,
+  generateRouteSchemaNames,
+} from "./routes.js";
+export type {
+  HttpMethod,
+  RouteParameter,
+  RouteInfo,
+  RouteSchemaNames,
+} from "./routes.js";
+export type { AnySchema, OpenAPIObjectSchema } from "./types/types.js";
+