@alt-stack/zod-openapi 1.0.1

package/src/registry.spec.ts

@@ -0,0 +1,308 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import { z } from "zod";
+import {
+  registerZodSchemaToOpenApiSchema,
+  getSchemaExportedVariableNameForStringFormat,
+  clearZodSchemaToOpenApiSchemaRegistry,
+  schemaRegistry,
+} from "./registry";
+
+describe("ZodSchemaRegistry", () => {
+  beforeEach(() => {
+    clearZodSchemaToOpenApiSchemaRegistry();
+  });
+
+  describe("registerZodSchemaToOpenApiSchema", () => {
+    describe("string format registration", () => {
+      it("should register schema with single string format", () => {
+        const schema = z.string().email();
+        registerZodSchemaToOpenApiSchema(schema, {
+          schemaExportedVariableName: "emailSchema",
+          type: "string",
+          format: "email",
+        });
+
+        const result = getSchemaExportedVariableNameForStringFormat("email");
+        expect(result).toBe("emailSchema");
+      });
+
+      it("should register schema with multiple string formats", () => {
+        const schema = z.string();
+        registerZodSchemaToOpenApiSchema(schema, {
+          schemaExportedVariableName: "dateSchema",
+          type: "string",
+          formats: ["date", "iso-date"],
+        });
+
+        expect(getSchemaExportedVariableNameForStringFormat("date")).toBe(
+          "dateSchema",
+        );
+        expect(getSchemaExportedVariableNameForStringFormat("iso-date")).toBe(
+          "dateSchema",
+        );
+      });
+
+      it("should throw error when registering duplicate format", () => {
+        const schema1 = z.string().email();
+        const schema2 = z.string().email();
+
+        registerZodSchemaToOpenApiSchema(schema1, {
+          schemaExportedVariableName: "emailSchema1",
+          type: "string",
+          format: "email",
+        });
+
+        expect(() => {
+          registerZodSchemaToOpenApiSchema(schema2, {
+            schemaExportedVariableName: "emailSchema2",
+            type: "string",
+            format: "email",
+          });
+        }).toThrow("duplicate Zod OpenAPI registration");
+      });
+
+      it("should allow same schema to be registered multiple times", () => {
+        const schema = z.string().email();
+        registerZodSchemaToOpenApiSchema(schema, {
+          schemaExportedVariableName: "emailSchema",
+          type: "string",
+          format: "email",
+        });
+
+        expect(() => {
+          registerZodSchemaToOpenApiSchema(schema, {
+            schemaExportedVariableName: "emailSchema",
+            type: "string",
+            format: "email",
+          });
+        }).not.toThrow();
+      });
+    });
+
+    describe("primitive type registration", () => {
+      it("should register number schema", () => {
+        const schema = z.number();
+        registerZodSchemaToOpenApiSchema(schema, {
+          schemaExportedVariableName: "numberSchema",
+          type: "number",
+        });
+
+        expect(schemaRegistry.isRegistered(schema)).toBe(true);
+      });
+
+      it("should register integer schema", () => {
+        const schema = z.number().int();
+        registerZodSchemaToOpenApiSchema(schema, {
+          schemaExportedVariableName: "integerSchema",
+          type: "integer",
+        });
+
+        expect(schemaRegistry.isRegistered(schema)).toBe(true);
+      });
+
+      it("should register boolean schema", () => {
+        const schema = z.boolean();
+        registerZodSchemaToOpenApiSchema(schema, {
+          schemaExportedVariableName: "booleanSchema",
+          type: "boolean",
+        });
+
+        expect(schemaRegistry.isRegistered(schema)).toBe(true);
+      });
+    });
+
+    describe("multiple registrations", () => {
+      it("should register multiple schemas with different formats", () => {
+        const emailSchema = z.string().email();
+        const uuidSchema = z.string().uuid();
+        const dateSchema = z.string();
+
+        registerZodSchemaToOpenApiSchema(emailSchema, {
+          schemaExportedVariableName: "emailSchema",
+          type: "string",
+          format: "email",
+        });
+
+        registerZodSchemaToOpenApiSchema(uuidSchema, {
+          schemaExportedVariableName: "uuidSchema",
+          type: "string",
+          format: "uuid",
+        });
+
+        registerZodSchemaToOpenApiSchema(dateSchema, {
+          schemaExportedVariableName: "dateSchema",
+          type: "string",
+          formats: ["date", "date-time"],
+        });
+
+        expect(getSchemaExportedVariableNameForStringFormat("email")).toBe(
+          "emailSchema",
+        );
+        expect(getSchemaExportedVariableNameForStringFormat("uuid")).toBe(
+          "uuidSchema",
+        );
+        expect(getSchemaExportedVariableNameForStringFormat("date")).toBe(
+          "dateSchema",
+        );
+        expect(getSchemaExportedVariableNameForStringFormat("date-time")).toBe(
+          "dateSchema",
+        );
+      });
+    });
+  });
+
+  describe("getSchemaExportedVariableNameForStringFormat", () => {
+    it("should return undefined for unregistered format", () => {
+      const result = getSchemaExportedVariableNameForStringFormat("email");
+      expect(result).toBeUndefined();
+    });
+
+    it("should return variable name for registered single format", () => {
+      const schema = z.string().email();
+      registerZodSchemaToOpenApiSchema(schema, {
+        schemaExportedVariableName: "customEmail",
+        type: "string",
+        format: "email",
+      });
+
+      const result = getSchemaExportedVariableNameForStringFormat("email");
+      expect(result).toBe("customEmail");
+    });
+
+    it("should return variable name for registered format in formats array", () => {
+      const schema = z.string();
+      registerZodSchemaToOpenApiSchema(schema, {
+        schemaExportedVariableName: "customDate",
+        type: "string",
+        formats: ["date", "iso-date"],
+      });
+
+      expect(getSchemaExportedVariableNameForStringFormat("date")).toBe(
+        "customDate",
+      );
+      expect(getSchemaExportedVariableNameForStringFormat("iso-date")).toBe(
+        "customDate",
+      );
+    });
+
+    it("should not return variable name for unregistered format in same schema", () => {
+      const schema = z.string();
+      registerZodSchemaToOpenApiSchema(schema, {
+        schemaExportedVariableName: "customDate",
+        type: "string",
+        formats: ["date"],
+      });
+
+      const result = getSchemaExportedVariableNameForStringFormat("email");
+      expect(result).toBeUndefined();
+    });
+  });
+
+  describe("schemaRegistry methods", () => {
+    describe("getOpenApiSchema", () => {
+      it("should return registration for registered schema", () => {
+        const schema = z.string().email();
+        const registration = {
+          schemaExportedVariableName: "emailSchema",
+          type: "string" as const,
+          format: "email" as const,
+        };
+
+        registerZodSchemaToOpenApiSchema(schema, registration);
+        const result = schemaRegistry.getOpenApiSchema(schema);
+
+        expect(result).toEqual(registration);
+      });
+
+      it("should return undefined for unregistered schema", () => {
+        const schema = z.string();
+        const result = schemaRegistry.getOpenApiSchema(schema);
+        expect(result).toBeUndefined();
+      });
+    });
+
+    describe("isRegistered", () => {
+      it("should return true for registered schema", () => {
+        const schema = z.string().email();
+        registerZodSchemaToOpenApiSchema(schema, {
+          schemaExportedVariableName: "emailSchema",
+          type: "string",
+          format: "email",
+        });
+
+        expect(schemaRegistry.isRegistered(schema)).toBe(true);
+      });
+
+      it("should return false for unregistered schema", () => {
+        const schema = z.string();
+        expect(schemaRegistry.isRegistered(schema)).toBe(false);
+      });
+    });
+
+    describe("clear", () => {
+      it("should clear all registered schemas", () => {
+        const schema = z.string().email();
+        registerZodSchemaToOpenApiSchema(schema, {
+          schemaExportedVariableName: "emailSchema",
+          type: "string",
+          format: "email",
+        });
+
+        expect(schemaRegistry.isRegistered(schema)).toBe(true);
+
+        clearZodSchemaToOpenApiSchemaRegistry();
+
+        expect(schemaRegistry.isRegistered(schema)).toBe(false);
+        expect(
+          getSchemaExportedVariableNameForStringFormat("email"),
+        ).toBeUndefined();
+      });
+    });
+  });
+
+  describe("edge cases", () => {
+    it("should handle registration with description", () => {
+      const schema = z.string().email();
+      registerZodSchemaToOpenApiSchema(schema, {
+        schemaExportedVariableName: "emailSchema",
+        type: "string",
+        format: "email",
+        description: "Custom email schema",
+      });
+
+      const result = schemaRegistry.getOpenApiSchema(schema);
+      expect(result?.description).toBe("Custom email schema");
+    });
+
+    it("should handle all supported string formats", () => {
+      const formats = [
+        "color-hex",
+        "date",
+        "date-time",
+        "email",
+        "iso-date",
+        "iso-date-time",
+        "objectid",
+        "uri",
+        "url",
+        "uuid",
+      ];
+
+      for (const format of formats) {
+        const schema = z.string();
+        registerZodSchemaToOpenApiSchema(schema, {
+          schemaExportedVariableName: `${format}Schema`,
+          type: "string",
+          format: format as any,
+        });
+
+        const result = getSchemaExportedVariableNameForStringFormat(
+          format as any,
+        );
+        expect(result).toBe(`${format}Schema`);
+
+        clearZodSchemaToOpenApiSchemaRegistry();
+      }
+    });
+  });
+});

package/src/registry.ts

@@ -0,0 +1,227 @@
+import { z } from "zod";
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+const SUPPORTED_STRING_FORMATS_MAP = {
+  "color-hex": 1,
+  date: 1,
+  "date-time": 1,
+  email: 1,
+  "iso-date": 1,
+  "iso-date-time": 1,
+  objectid: 1,
+  uri: 1,
+  url: 1,
+  uuid: 1,
+} as const;
+
+export const SUPPORTED_STRING_FORMATS = Object.keys(
+  SUPPORTED_STRING_FORMATS_MAP,
+) as unknown as keyof typeof SUPPORTED_STRING_FORMATS_MAP;
+
+type SupportedStringFormat = typeof SUPPORTED_STRING_FORMATS;
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export type ZodOpenApiRegistrationString<
+  F extends SupportedStringFormat = SupportedStringFormat,
+> = {
+  /** The name of the schema variable, IMPORTANT: must be named the same as the variable name */
+  schemaExportedVariableName: string;
+  type: "string";
+  description?: string;
+  format: F;
+};
+
+export type ZodOpenApiRegistrationStrings<
+  Fs extends
+    readonly SupportedStringFormat[] = readonly SupportedStringFormat[],
+> = {
+  /** The name of the schema variable, IMPORTANT: must be named the same as the variable name */
+  schemaExportedVariableName: string;
+  type: "string";
+  description?: string;
+  formats: Fs;
+};
+
+export type ZodOpenApiRegistrationPrimitive = {
+  /** The name of the schema variable, IMPORTANT: must be named the same as the variable name */
+  schemaExportedVariableName: string;
+  description?: string;
+  type: "number" | "integer" | "boolean";
+};
+
+export type ZodOpenApiRegistration =
+  | ZodOpenApiRegistrationString
+  | ZodOpenApiRegistrationStrings
+  | ZodOpenApiRegistrationPrimitive;
+
+// ============================================================================
+// Type Guards
+// ============================================================================
+
+function isStringRegistration(
+  reg: ZodOpenApiRegistration,
+): reg is ZodOpenApiRegistrationString {
+  return reg.type === "string" && "format" in reg;
+}
+
+function isStringsRegistration(
+  reg: ZodOpenApiRegistration,
+): reg is ZodOpenApiRegistrationStrings {
+  return reg.type === "string" && "formats" in reg;
+}
+
+// ============================================================================
+// Helper Functions
+// ============================================================================
+
+type TypeFormatPair = { type: string; format: string | undefined };
+
+function getTypeFormatPairs(reg: ZodOpenApiRegistration): TypeFormatPair[] {
+  if (isStringRegistration(reg)) {
+    return [{ type: "string", format: reg.format }];
+  }
+
+  if (isStringsRegistration(reg)) {
+    return reg.formats.map((f) => ({ type: "string", format: f }));
+  }
+
+  return [];
+}
+
+// ============================================================================
+// Registry Class
+// ============================================================================
+
+/**
+ * Global registry for mapping Zod schemas to OpenAPI schema representations
+ */
+class ZodSchemaRegistry {
+  private readonly map = new Map<z.ZodTypeAny, ZodOpenApiRegistration>();
+
+  /**
+   * Register a Zod schema with its OpenAPI representation
+   */
+  register<F extends SupportedStringFormat>(
+    schema: z.ZodTypeAny,
+    registration: ZodOpenApiRegistrationString<F>,
+  ): void;
+  register<Fs extends readonly SupportedStringFormat[]>(
+    schema: z.ZodTypeAny,
+    registration: ZodOpenApiRegistrationStrings<Fs>,
+  ): void;
+  register(
+    schema: z.ZodTypeAny,
+    registration: ZodOpenApiRegistrationPrimitive,
+  ): void;
+  register(schema: z.ZodTypeAny, registration: ZodOpenApiRegistration): void {
+    const newPairs = getTypeFormatPairs(registration);
+
+    if (newPairs.length > 0) {
+      for (const [existingSchema, existingRegistration] of this.map.entries()) {
+        if (existingSchema === schema) continue;
+
+        const existingPairs = getTypeFormatPairs(existingRegistration);
+        for (const { type, format } of newPairs) {
+          if (
+            existingPairs.some((p) => p.type === type && p.format === format)
+          ) {
+            throw new Error(
+              `duplicate Zod OpenAPI registration for (type, format)=('${type}', '${format as string}')`,
+            );
+          }
+        }
+      }
+    }
+
+    this.map.set(schema, registration);
+  }
+
+  /**
+   * Get the OpenAPI schema for a given Zod schema
+   */
+  getOpenApiSchema(schema: z.ZodTypeAny): ZodOpenApiRegistration | undefined {
+    return this.map.get(schema);
+  }
+
+  /**
+   * Check if a Zod schema is registered
+   */
+  isRegistered(schema: z.ZodTypeAny): boolean {
+    return this.map.has(schema);
+  }
+
+  /**
+   * Clear all registered schemas
+   */
+  clear(): void {
+    this.map.clear();
+  }
+
+  /**
+   * Reverse-lookup helper: given a string format, return the registered schema's exported variable name
+   */
+  getSchemaExportedVariableNameForStringFormat(
+    format: SupportedStringFormat,
+  ): string | undefined {
+    for (const registration of this.map.values()) {
+      if (registration.type !== "string") continue;
+
+      if (
+        isStringRegistration(registration) &&
+        registration.format === format
+      ) {
+        return registration.schemaExportedVariableName;
+      }
+
+      if (
+        isStringsRegistration(registration) &&
+        registration.formats.includes(format)
+      ) {
+        return registration.schemaExportedVariableName;
+      }
+    }
+    return undefined;
+  }
+}
+
+// ============================================================================
+// Global Registry Instance
+// ============================================================================
+
+export const schemaRegistry = new ZodSchemaRegistry();
+
+// ============================================================================
+// Public API
+// ============================================================================
+
+/**
+ * Helper function to register a Zod schema with its OpenAPI representation
+ */
+export function registerZodSchemaToOpenApiSchema(
+  schema: z.ZodTypeAny,
+  openApiSchema: ZodOpenApiRegistration,
+): void {
+  schemaRegistry.register(schema, openApiSchema as any);
+}
+
+/**
+ * Convenience helper to get an exported schema variable name for a given string format
+ */
+export function getSchemaExportedVariableNameForStringFormat(
+  format: SupportedStringFormat,
+): string | undefined {
+  return schemaRegistry.getSchemaExportedVariableNameForStringFormat(format);
+}
+
+/**
+ * Clear all registered schemas in the global registry
+ */
+export function clearZodSchemaToOpenApiSchemaRegistry(): void {
+  schemaRegistry.clear();
+}