@schmock/openapi 1.1.0

package/src/generators.ts

@@ -0,0 +1,212 @@
+/// <reference path="../../../types/schmock.d.ts" />
+
+import { generateFromSchema } from "@schmock/schema";
+import type { JSONSchema7 } from "json-schema";
+import type { CrudResource } from "./crud-detector.js";
+import type { ParsedPath } from "./parser.js";
+
+const COLLECTION_STATE_PREFIX = "openapi:collections:";
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function toTuple(status: number, body: unknown): [number, unknown] {
+  return [status, body];
+}
+
+function collectionKey(resourceName: string): string {
+  return `${COLLECTION_STATE_PREFIX}${resourceName}`;
+}
+
+function getCollection(
+  state: Record<string, unknown>,
+  resourceName: string,
+): unknown[] {
+  const key = collectionKey(resourceName);
+  if (!Array.isArray(state[key])) {
+    state[key] = [];
+  }
+  const value = state[key];
+  if (Array.isArray(value)) {
+    return value;
+  }
+  return [];
+}
+
+function getNextId(
+  state: Record<string, unknown>,
+  resourceName: string,
+): number {
+  const counterKey = `openapi:counter:${resourceName}`;
+  const current = state[counterKey];
+  const base = typeof current === "number" ? current : 0;
+  const next = base + 1;
+  state[counterKey] = next;
+  return next;
+}
+
+export function createListGenerator(
+  resource: CrudResource,
+): Schmock.GeneratorFunction {
+  return (ctx: Schmock.RequestContext) => {
+    const collection = getCollection(ctx.state, resource.name);
+    return [...collection];
+  };
+}
+
+export function createCreateGenerator(
+  resource: CrudResource,
+): Schmock.GeneratorFunction {
+  return (ctx: Schmock.RequestContext) => {
+    const collection = getCollection(ctx.state, resource.name);
+    const id = getNextId(ctx.state, resource.name);
+
+    let item: Record<string, unknown>;
+    if (isRecord(ctx.body)) {
+      item = {
+        ...ctx.body,
+        [resource.idParam]: id,
+      };
+    } else {
+      item = { [resource.idParam]: id };
+    }
+
+    collection.push(item);
+    return toTuple(201, item);
+  };
+}
+
+export function createReadGenerator(
+  resource: CrudResource,
+): Schmock.GeneratorFunction {
+  return (ctx: Schmock.RequestContext) => {
+    const collection = getCollection(ctx.state, resource.name);
+    const idValue = ctx.params[resource.idParam];
+    const item = findById(collection, resource.idParam, idValue);
+
+    if (!item) {
+      return toTuple(404, { error: "Not found", code: "NOT_FOUND" });
+    }
+
+    return item;
+  };
+}
+
+export function createUpdateGenerator(
+  resource: CrudResource,
+): Schmock.GeneratorFunction {
+  return (ctx: Schmock.RequestContext) => {
+    const collection = getCollection(ctx.state, resource.name);
+    const idValue = ctx.params[resource.idParam];
+    const index = findIndexById(collection, resource.idParam, idValue);
+
+    if (index === -1) {
+      return toTuple(404, { error: "Not found", code: "NOT_FOUND" });
+    }
+
+    const existingRaw = collection[index];
+    const existing = isRecord(existingRaw) ? existingRaw : {};
+    const updated = {
+      ...existing,
+      ...(isRecord(ctx.body) ? ctx.body : {}),
+      [resource.idParam]: existing[resource.idParam], // Preserve ID
+    };
+    collection[index] = updated;
+    return updated;
+  };
+}
+
+export function createDeleteGenerator(
+  resource: CrudResource,
+): Schmock.GeneratorFunction {
+  return (ctx: Schmock.RequestContext) => {
+    const collection = getCollection(ctx.state, resource.name);
+    const idValue = ctx.params[resource.idParam];
+    const index = findIndexById(collection, resource.idParam, idValue);
+
+    if (index === -1) {
+      return toTuple(404, { error: "Not found", code: "NOT_FOUND" });
+    }
+
+    collection.splice(index, 1);
+    return toTuple(204, undefined);
+  };
+}
+
+export function createStaticGenerator(
+  parsedPath: ParsedPath,
+): Schmock.GeneratorFunction {
+  // Get the success response schema
+  let responseSchema: JSONSchema7 | undefined;
+  for (const code of [200, 201]) {
+    const resp = parsedPath.responses.get(code);
+    if (resp?.schema) {
+      responseSchema = resp.schema;
+      break;
+    }
+  }
+  if (!responseSchema) {
+    for (const [code, resp] of parsedPath.responses) {
+      if (code >= 200 && code < 300 && resp.schema) {
+        responseSchema = resp.schema;
+        break;
+      }
+    }
+  }
+
+  return () => {
+    if (responseSchema) {
+      try {
+        return generateFromSchema({ schema: responseSchema });
+      } catch {
+        // Complex schemas (deep anyOf, circular refs) may fail generation.
+        // Fall back to an empty object rather than crashing.
+        return {};
+      }
+    }
+    return toTuple(200, {});
+  };
+}
+
+/**
+ * Generate seed items for a resource using its schema.
+ */
+export function generateSeedItems(
+  schema: JSONSchema7,
+  count: number,
+  idParam: string,
+): unknown[] {
+  const items: unknown[] = [];
+  for (let i = 0; i < count; i++) {
+    const generated = generateFromSchema({ schema });
+    const item: Record<string, unknown> = isRecord(generated)
+      ? generated
+      : { value: generated };
+    item[idParam] = i + 1;
+    items.push(item);
+  }
+  return items;
+}
+
+function findById(
+  collection: unknown[],
+  idParam: string,
+  idValue: string,
+): unknown | undefined {
+  return collection.find((item) => {
+    if (!isRecord(item)) return false;
+    return String(item[idParam]) === String(idValue);
+  });
+}
+
+function findIndexById(
+  collection: unknown[],
+  idParam: string,
+  idValue: string,
+): number {
+  return collection.findIndex((item) => {
+    if (!isRecord(item)) return false;
+    return String(item[idParam]) === String(idValue);
+  });
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+/// <reference path="../../../types/schmock.d.ts" />
+
+export type { OpenApiOptions, SeedConfig, SeedSource } from "./plugin.js";
+export { openapi } from "./plugin.js";

package/src/normalizer.test.ts

@@ -0,0 +1,253 @@
+import { describe, expect, it } from "vitest";
+import { normalizeSchema } from "./normalizer";
+
+describe("normalizeSchema", () => {
+  describe("nullable", () => {
+    it("converts nullable: true to oneOf with null type", () => {
+      const result = normalizeSchema(
+        { type: "string", nullable: true },
+        "response",
+      );
+      expect(result).toEqual({
+        oneOf: [{ type: "string" }, { type: "null" }],
+      });
+    });
+
+    it("removes nullable: false without adding null type", () => {
+      const result = normalizeSchema(
+        { type: "string", nullable: false },
+        "response",
+      );
+      expect(result).toEqual({ type: "string" });
+    });
+  });
+
+  describe("readOnly / writeOnly", () => {
+    it("strips readOnly fields from request schemas", () => {
+      const result = normalizeSchema(
+        {
+          type: "object",
+          required: ["id", "name"],
+          properties: {
+            id: { type: "integer", readOnly: true },
+            name: { type: "string" },
+          },
+        },
+        "request",
+      );
+      expect(result.properties).not.toHaveProperty("id");
+      expect(result.properties).toHaveProperty("name");
+      expect(result.required).toEqual(["name"]);
+    });
+
+    it("keeps readOnly fields in response schemas", () => {
+      const result = normalizeSchema(
+        {
+          type: "object",
+          properties: {
+            id: { type: "integer", readOnly: true },
+            name: { type: "string" },
+          },
+        },
+        "response",
+      );
+      expect(result.properties).toHaveProperty("id");
+      expect(result.properties).toHaveProperty("name");
+    });
+
+    it("strips writeOnly fields from response schemas", () => {
+      const result = normalizeSchema(
+        {
+          type: "object",
+          properties: {
+            password: { type: "string", writeOnly: true },
+            name: { type: "string" },
+          },
+        },
+        "response",
+      );
+      expect(result.properties).not.toHaveProperty("password");
+      expect(result.properties).toHaveProperty("name");
+    });
+
+    it("keeps writeOnly fields in request schemas", () => {
+      const result = normalizeSchema(
+        {
+          type: "object",
+          properties: {
+            password: { type: "string", writeOnly: true },
+            name: { type: "string" },
+          },
+        },
+        "request",
+      );
+      expect(result.properties).toHaveProperty("password");
+    });
+  });
+
+  describe("example → default", () => {
+    it("copies example to default when default is not set", () => {
+      const result = normalizeSchema(
+        { type: "string", example: "hello" },
+        "response",
+      );
+      expect(result.default).toBe("hello");
+      expect(result).not.toHaveProperty("example");
+    });
+
+    it("preserves existing default when example is present", () => {
+      const result = normalizeSchema(
+        { type: "string", example: "hello", default: "world" },
+        "response",
+      );
+      expect(result.default).toBe("world");
+    });
+  });
+
+  describe("exclusiveMinimum/exclusiveMaximum boolean → number", () => {
+    it("converts exclusiveMinimum: true to number format", () => {
+      const result = normalizeSchema(
+        { type: "number", minimum: 0, exclusiveMinimum: true },
+        "response",
+      );
+      expect(result.exclusiveMinimum).toBe(0);
+      expect(result).not.toHaveProperty("minimum");
+    });
+
+    it("removes exclusiveMinimum: false", () => {
+      const result = normalizeSchema(
+        { type: "number", minimum: 0, exclusiveMinimum: false },
+        "response",
+      );
+      expect(result.minimum).toBe(0);
+      expect(result).not.toHaveProperty("exclusiveMinimum");
+    });
+
+    it("converts exclusiveMaximum: true to number format", () => {
+      const result = normalizeSchema(
+        { type: "number", maximum: 100, exclusiveMaximum: true },
+        "response",
+      );
+      expect(result.exclusiveMaximum).toBe(100);
+      expect(result).not.toHaveProperty("maximum");
+    });
+  });
+
+  describe("x-* extensions", () => {
+    it("strips all x- prefixed properties", () => {
+      const result = normalizeSchema(
+        {
+          type: "string",
+          "x-custom": "value",
+          "x-another": 42,
+        },
+        "response",
+      );
+      expect(result).not.toHaveProperty("x-custom");
+      expect(result).not.toHaveProperty("x-another");
+      expect(result.type).toBe("string");
+    });
+  });
+
+  describe("deep recursion", () => {
+    it("normalizes nested properties → items → oneOf", () => {
+      const result = normalizeSchema(
+        {
+          type: "object",
+          properties: {
+            items: {
+              type: "array",
+              items: {
+                oneOf: [
+                  { type: "string", nullable: true },
+                  { type: "integer", example: 42 },
+                ],
+              },
+            },
+          },
+        },
+        "response",
+      );
+
+      const itemsSchema = result.properties?.items;
+      expect(itemsSchema).toBeDefined();
+      const arraySchema = itemsSchema as Record<string, unknown>;
+      const itemSchema = arraySchema.items as Record<string, unknown>;
+      const branches = itemSchema.oneOf as Record<string, unknown>[];
+      expect(branches).toHaveLength(2);
+      // First branch: nullable string → oneOf
+      expect(branches[0]).toHaveProperty("oneOf");
+      // Second branch: example → default
+      expect(branches[1]).toHaveProperty("default", 42);
+    });
+  });
+
+  describe("passthrough", () => {
+    it("preserves standard JSON Schema 7 features", () => {
+      const input = {
+        type: "object",
+        properties: {
+          name: { type: "string", minLength: 1, maxLength: 100 },
+          age: { type: "integer", minimum: 0, maximum: 150 },
+          role: { type: "string", enum: ["admin", "user"] },
+          email: { type: "string", pattern: "^[^@]+@[^@]+$" },
+        },
+        required: ["name"],
+      };
+      const result = normalizeSchema(input, "response");
+      expect(result.properties?.name).toMatchObject({
+        type: "string",
+        minLength: 1,
+        maxLength: 100,
+      });
+      expect(result.properties?.age).toMatchObject({
+        type: "integer",
+        minimum: 0,
+        maximum: 150,
+      });
+      expect(result.required).toEqual(["name"]);
+    });
+  });
+
+  describe("discriminator", () => {
+    it("adds required and enum constraints for discriminator", () => {
+      const result = normalizeSchema(
+        {
+          discriminator: {
+            propertyName: "petType",
+            mapping: {
+              dog: "#/components/schemas/Dog",
+              cat: "#/components/schemas/Cat",
+            },
+          },
+          oneOf: [
+            {
+              type: "object",
+              properties: {
+                petType: { type: "string" },
+                bark: { type: "boolean" },
+              },
+            },
+            {
+              type: "object",
+              properties: {
+                petType: { type: "string" },
+                purr: { type: "boolean" },
+              },
+            },
+          ],
+        },
+        "response",
+      );
+
+      expect(result).not.toHaveProperty("discriminator");
+      const branches = result.oneOf as Record<string, unknown>[];
+      expect(branches).toHaveLength(2);
+
+      // Each branch should have petType as required
+      for (const branch of branches) {
+        expect(branch.required).toContain("petType");
+      }
+    });
+  });
+});

package/src/normalizer.ts

@@ -0,0 +1,233 @@
+/// <reference path="../../../types/schmock.d.ts" />
+
+import type { JSONSchema7 } from "json-schema";
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function toJsonSchema(node: Record<string, unknown>): JSONSchema7 {
+  // Object.assign merges unknown-keyed properties into JSONSchema7.
+  // This is safe because the normalizer has already ensured the shape
+  // is valid JSON Schema 7 before calling this function.
+  return Object.assign<JSONSchema7, Record<string, unknown>>({}, node);
+}
+
+/**
+ * Normalize an OpenAPI schema to pure JSON Schema 7 that json-schema-faker understands.
+ *
+ * Transforms applied:
+ * - nullable: true -> oneOf with null type
+ * - discriminator -> required + enum on branches
+ * - readOnly/writeOnly -> strip based on direction
+ * - example -> default (if default not set)
+ * - exclusiveMinimum/exclusiveMaximum boolean -> number format
+ * - x-* extensions -> stripped
+ */
+export function normalizeSchema(
+  schema: Record<string, unknown>,
+  direction: "request" | "response",
+): JSONSchema7 {
+  return normalizeNode(structuredClone(schema), direction, new WeakSet());
+}
+
+function normalizeNode(
+  node: Record<string, unknown>,
+  direction: "request" | "response",
+  visited: WeakSet<object>,
+): JSONSchema7 {
+  if (!node || typeof node !== "object" || Array.isArray(node)) {
+    return toJsonSchema({});
+  }
+
+  // Circular reference detection — break cycles
+  if (visited.has(node)) {
+    return toJsonSchema({});
+  }
+  visited.add(node);
+
+  // Strip x-* extensions
+  for (const key of Object.keys(node)) {
+    if (key.startsWith("x-")) {
+      delete node[key];
+    }
+  }
+
+  // Handle nullable: true -> oneOf with null
+  if (node.nullable === true) {
+    delete node.nullable;
+    // Only wrap if not already a composition with null
+    const copy = { ...node };
+    delete copy.nullable;
+    return {
+      oneOf: [normalizeNode(copy, direction, visited), { type: "null" }],
+    };
+  }
+  delete node.nullable;
+
+  // Handle discriminator
+  if (node.discriminator && isRecord(node.discriminator)) {
+    const disc = node.discriminator;
+    const propName = disc.propertyName;
+    if (typeof propName === "string" && Array.isArray(node.oneOf)) {
+      const mappingRaw = disc.mapping ?? {};
+      const mapping = isRecord(mappingRaw) ? mappingRaw : {};
+      // mapping keys ARE the discriminator values (e.g. "dog", "cat")
+      // mapping values are $ref strings — after dereference they can't be matched to branches
+      // Use key order to correspond to oneOf branch order
+      const discriminatorValues = Object.keys(mapping);
+
+      node.oneOf = node.oneOf
+        .filter((branch): branch is Record<string, unknown> => isRecord(branch))
+        .map((branch, index) => {
+          const normalized = normalizeNode(branch, direction, visited);
+          // Ensure discriminator property is required
+          if (isRecord(normalized)) {
+            const required = Array.isArray(normalized.required)
+              ? [...normalized.required]
+              : [];
+            if (!required.includes(propName)) {
+              required.push(propName);
+            }
+            normalized.required = required;
+
+            // Add enum constraint for the discriminator value
+            const mappingValue = discriminatorValues[index];
+            if (mappingValue && isRecord(normalized.properties)) {
+              const props = normalized.properties;
+              const existingRaw = props[propName] ?? {};
+              const existing = isRecord(existingRaw) ? existingRaw : {};
+              props[propName] = { ...existing, enum: [mappingValue] };
+            }
+          }
+          return normalized;
+        });
+    }
+    delete node.discriminator;
+  }
+
+  // Handle readOnly/writeOnly on properties
+  if (isRecord(node.properties)) {
+    const props = node.properties;
+    const required = Array.isArray(node.required)
+      ? node.required.filter((r): r is string => typeof r === "string")
+      : [];
+    const keysToRemove: string[] = [];
+
+    for (const [propName, propSchemaRaw] of Object.entries(props)) {
+      if (!isRecord(propSchemaRaw)) continue;
+      const propSchema = propSchemaRaw;
+
+      // readOnly fields: remove from request schemas
+      if (direction === "request" && propSchema.readOnly === true) {
+        keysToRemove.push(propName);
+        continue;
+      }
+      // writeOnly fields: remove from response schemas
+      if (direction === "response" && propSchema.writeOnly === true) {
+        keysToRemove.push(propName);
+        continue;
+      }
+
+      // Clean up the flags after handling
+      delete propSchema.readOnly;
+      delete propSchema.writeOnly;
+
+      // Recurse into property
+      props[propName] = normalizeNode(propSchema, direction, visited);
+    }
+
+    for (const key of keysToRemove) {
+      delete props[key];
+      const reqIdx = required.indexOf(key);
+      if (reqIdx !== -1) {
+        required.splice(reqIdx, 1);
+      }
+    }
+
+    if (required.length > 0) {
+      node.required = required;
+    } else if (keysToRemove.length > 0 && Array.isArray(node.required)) {
+      // If we removed all required fields, clean up
+      if (required.length === 0) {
+        delete node.required;
+      }
+    }
+  }
+
+  // Handle example -> default
+  if ("example" in node && !("default" in node)) {
+    node.default = node.example;
+  }
+  delete node.example;
+
+  // Handle exclusiveMinimum/exclusiveMaximum boolean -> number
+  if (node.exclusiveMinimum === true && typeof node.minimum === "number") {
+    node.exclusiveMinimum = node.minimum;
+    delete node.minimum;
+  } else if (node.exclusiveMinimum === false) {
+    delete node.exclusiveMinimum;
+  }
+
+  if (node.exclusiveMaximum === true && typeof node.maximum === "number") {
+    node.exclusiveMaximum = node.maximum;
+    delete node.maximum;
+  } else if (node.exclusiveMaximum === false) {
+    delete node.exclusiveMaximum;
+  }
+
+  // Recurse into items (array schema)
+  if (node.items) {
+    if (Array.isArray(node.items)) {
+      node.items = node.items.map((item: unknown) =>
+        isRecord(item) ? normalizeNode(item, direction, visited) : item,
+      );
+    } else if (isRecord(node.items)) {
+      node.items = normalizeNode(node.items, direction, visited);
+    }
+  }
+
+  // Recurse into additionalProperties
+  if (isRecord(node.additionalProperties)) {
+    node.additionalProperties = normalizeNode(
+      node.additionalProperties,
+      direction,
+      visited,
+    );
+  }
+
+  // Recurse into composition keywords
+  for (const keyword of ["allOf", "anyOf", "oneOf"]) {
+    const keywordValue = node[keyword];
+    if (Array.isArray(keywordValue)) {
+      node[keyword] = keywordValue.map((branch: unknown) =>
+        isRecord(branch) ? normalizeNode(branch, direction, visited) : branch,
+      );
+    }
+  }
+
+  // Recurse into not
+  if (isRecord(node.not)) {
+    node.not = normalizeNode(node.not, direction, visited);
+  }
+
+  // Recurse into conditional
+  for (const keyword of ["if", "then", "else"]) {
+    const keywordValue = node[keyword];
+    if (isRecord(keywordValue)) {
+      node[keyword] = normalizeNode(keywordValue, direction, visited);
+    }
+  }
+
+  // Recurse into patternProperties
+  if (isRecord(node.patternProperties)) {
+    const pp = node.patternProperties;
+    for (const [pattern, schema] of Object.entries(pp)) {
+      if (isRecord(schema)) {
+        pp[pattern] = normalizeNode(schema, direction, visited);
+      }
+    }
+  }
+
+  return toJsonSchema(node);
+}