@schmock/openapi 1.2.0 → 1.4.0

package/src/generators.ts

@@ -1,6 +1,7 @@
-/// <reference path="../../../types/schmock.d.ts" />
+/// <reference path="../../core/schmock.d.ts" />
 
-import { generateFromSchema } from "@schmock/schema";
+import { randomUUID } from "node:crypto";
+import { generateFromSchema } from "@schmock/faker";
 import type { JSONSchema7 } from "json-schema";
 import type { CrudResource } from "./crud-detector.js";
 import type { ParsedPath } from "./parser.js";
@@ -8,6 +9,136 @@ import { isRecord } from "./utils.js";
 
 const COLLECTION_STATE_PREFIX = "openapi:collections:";
 
+/**
+ * Result of finding the array property in a response schema.
+ * If property is undefined, the schema is a flat array (or unknown).
+ */
+interface ArrayPropertyInfo {
+  /** Property name holding the array (e.g. "data"), undefined for flat arrays */
+  property?: string;
+  /** Schema for the array items */
+  itemSchema?: JSONSchema7;
+}
+
+/**
+ * Find which property in a response schema holds the array of items.
+ * Handles flat arrays, object wrappers (Stripe), and allOf compositions (Scalar Galaxy).
+ */
+export function findArrayProperty(schema: JSONSchema7): ArrayPropertyInfo {
+  if (!schema || typeof schema === "boolean") return {};
+
+  // Case 1: flat array
+  if (schema.type === "array") {
+    const items = Array.isArray(schema.items) ? schema.items[0] : schema.items;
+    const itemSchema = isRecord(items) ? (items as JSONSchema7) : undefined;
+    return { itemSchema };
+  }
+
+  // Case 2: object with properties — scan for the array property
+  if (schema.type === "object" && isRecord(schema.properties)) {
+    return findArrayInProperties(schema.properties);
+  }
+
+  // Case 3: allOf — merge branches into one virtual object, then scan
+  if (Array.isArray(schema.allOf)) {
+    const merged: Record<string, JSONSchema7> = {};
+    for (const branch of schema.allOf) {
+      if (isRecord(branch) && isRecord(branch.properties)) {
+        for (const [key, value] of Object.entries(branch.properties)) {
+          if (isRecord(value)) {
+            merged[key] = value as JSONSchema7;
+          }
+        }
+      }
+    }
+    if (Object.keys(merged).length > 0) {
+      return findArrayInProperties(merged);
+    }
+  }
+
+  // Case 4: anyOf/oneOf — try first branch
+  for (const keyword of ["anyOf", "oneOf"] as const) {
+    const branches = schema[keyword];
+    if (Array.isArray(branches) && branches.length > 0) {
+      const first = branches[0];
+      if (isRecord(first)) {
+        return findArrayProperty(first as JSONSchema7);
+      }
+    }
+  }
+
+  return {};
+}
+
+function findArrayInProperties(
+  properties: Record<string, unknown>,
+): ArrayPropertyInfo {
+  for (const [key, value] of Object.entries(properties)) {
+    if (!isRecord(value)) continue;
+    const prop = value as JSONSchema7;
+    if (prop.type === "array" && prop.items) {
+      const items = Array.isArray(prop.items) ? prop.items[0] : prop.items;
+      const itemSchema = isRecord(items) ? (items as JSONSchema7) : undefined;
+      return { property: key, itemSchema };
+    }
+  }
+  return {};
+}
+
+/**
+ * Generate header values from spec-defined response header definitions.
+ */
+export function generateHeaderValues(
+  headerDefs: Record<string, Schmock.ResponseHeaderDef> | undefined,
+): Record<string, string> {
+  if (!headerDefs) return {};
+
+  const headers: Record<string, string> = {};
+
+  for (const [name, def] of Object.entries(headerDefs)) {
+    const value = generateSingleHeaderValue(def.schema);
+    if (value !== undefined) {
+      headers[name] = value;
+    }
+  }
+
+  return headers;
+}
+
+function generateSingleHeaderValue(
+  schema: JSONSchema7 | undefined,
+): string | undefined {
+  if (!schema || typeof schema === "boolean") return undefined;
+
+  // Has enum → first value
+  if (Array.isArray(schema.enum) && schema.enum.length > 0) {
+    return String(schema.enum[0]);
+  }
+
+  // Has default (from example → default normalization)
+  if ("default" in schema && schema.default !== undefined) {
+    return String(schema.default);
+  }
+
+  // Format-based generation
+  if (schema.format === "uuid") {
+    return randomUUID();
+  }
+  if (schema.format === "date-time") {
+    return new Date().toISOString();
+  }
+
+  // Type-based fallback
+  if (schema.type === "integer" || schema.type === "number") {
+    return "0";
+  }
+  if (schema.type === "string") {
+    return "";
+  }
+
+  return undefined;
+}
+
 function toTuple(status: number, body: unknown): [number, unknown] {
   return [status, body];
 }
@@ -45,16 +176,40 @@ function getNextId(
 
 export function createListGenerator(
   resource: CrudResource,
+  meta?: Schmock.CrudOperationMeta,
 ): Schmock.GeneratorFunction {
+  // Pre-compute wrapper info at setup time
+  const wrapperInfo = meta?.responseSchema
+    ? findArrayProperty(meta.responseSchema)
+    : undefined;
+  const headerDefs = meta?.responseHeaders;
+
   return (ctx: Schmock.RequestContext) => {
     const collection = getCollection(ctx.state, resource.name);
-    return [...collection];
+    const items = [...collection];
+
+    // If no wrapper detected or flat array, return items directly
+    if (!wrapperInfo?.property || !meta?.responseSchema) {
+      return addHeaders(items, headerDefs);
+    }
+
+    // Generate the full wrapper skeleton from schema, then inject live data
+    const skeleton = generateWrapperSkeleton(meta.responseSchema);
+    if (isRecord(skeleton)) {
+      skeleton[wrapperInfo.property] = items;
+      return addHeaders(skeleton, headerDefs);
+    }
+
+    return addHeaders(items, headerDefs);
   };
 }
 
 export function createCreateGenerator(
   resource: CrudResource,
+  meta?: Schmock.CrudOperationMeta,
 ): Schmock.GeneratorFunction {
+  const headerDefs = meta?.responseHeaders;
+
   return (ctx: Schmock.RequestContext) => {
     const collection = getCollection(ctx.state, resource.name);
     const id = getNextId(ctx.state, resource.name);
@@ -70,36 +225,42 @@ export function createCreateGenerator(
     }
 
     collection.push(item);
-    return toTuple(201, item);
+    return addHeaders(toTuple(201, item), headerDefs);
   };
 }
 
 export function createReadGenerator(
   resource: CrudResource,
+  meta?: Schmock.CrudOperationMeta,
 ): Schmock.GeneratorFunction {
+  const headerDefs = meta?.responseHeaders;
+
   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 generateErrorResponse(404, meta);
     }
 
-    return item;
+    return addHeaders(item, headerDefs);
   };
 }
 
 export function createUpdateGenerator(
   resource: CrudResource,
+  meta?: Schmock.CrudOperationMeta,
 ): Schmock.GeneratorFunction {
+  const headerDefs = meta?.responseHeaders;
+
   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" });
+      return generateErrorResponse(404, meta);
     }
 
     const existingRaw = collection[index];
@@ -110,12 +271,13 @@ export function createUpdateGenerator(
       [resource.idParam]: existing[resource.idParam], // Preserve ID
     };
     collection[index] = updated;
-    return updated;
+    return addHeaders(updated, headerDefs);
   };
 }
 
 export function createDeleteGenerator(
   resource: CrudResource,
+  meta?: Schmock.CrudOperationMeta,
 ): Schmock.GeneratorFunction {
   return (ctx: Schmock.RequestContext) => {
     const collection = getCollection(ctx.state, resource.name);
@@ -123,7 +285,7 @@ export function createDeleteGenerator(
     const index = findIndexById(collection, resource.idParam, idValue);
 
     if (index === -1) {
-      return toTuple(404, { error: "Not found", code: "NOT_FOUND" });
+      return generateErrorResponse(404, meta);
     }
 
     collection.splice(index, 1);
@@ -133,6 +295,7 @@ export function createDeleteGenerator(
 
 export function createStaticGenerator(
   parsedPath: ParsedPath,
+  seed?: number,
 ): Schmock.GeneratorFunction {
   // Get the success response schema
   let responseSchema: JSONSchema7 | undefined;
@@ -155,7 +318,7 @@ export function createStaticGenerator(
   return () => {
     if (responseSchema) {
       try {
-        return generateFromSchema({ schema: responseSchema });
+        return generateFromSchema({ schema: responseSchema, seed });
       } catch (error) {
         console.warn(
           `[@schmock/openapi] Schema generation failed for ${parsedPath.method} ${parsedPath.path}:`,
@@ -175,10 +338,11 @@ export function generateSeedItems(
   schema: JSONSchema7,
   count: number,
   idParam: string,
+  seed?: number,
 ): unknown[] {
   const items: unknown[] = [];
   for (let i = 0; i < count; i++) {
-    const generated = generateFromSchema({ schema });
+    const generated = generateFromSchema({ schema, seed });
     const item: Record<string, unknown> = isRecord(generated)
       ? generated
       : { value: generated };
@@ -188,6 +352,68 @@ export function generateSeedItems(
   return items;
 }
 
+/**
+ * Generate an error response using the spec's error schema if available,
+ * or fall back to the default { error, code } format.
+ */
+function generateErrorResponse(
+  status: number,
+  meta?: Schmock.CrudOperationMeta,
+): [number, unknown] | [number, unknown, Record<string, string>] {
+  const errorSchema = meta?.errorSchemas?.get(status);
+  if (errorSchema) {
+    try {
+      const body = generateFromSchema({ schema: errorSchema });
+      return toTuple(status, body);
+    } catch {
+      // Fall through to default
+    }
+  }
+
+  // Default error format
+  const defaults: Record<number, { error: string; code: string }> = {
+    404: { error: "Not found", code: "NOT_FOUND" },
+    400: { error: "Bad request", code: "BAD_REQUEST" },
+    409: { error: "Conflict", code: "CONFLICT" },
+  };
+  return toTuple(status, defaults[status] ?? { error: "Error", code: "ERROR" });
+}
+
+/**
+ * Generate a skeleton object from a response schema.
+ * Used to create wrapper objects (e.g. { data: [], has_more: false, object: "list" })
+ */
+function generateWrapperSkeleton(schema: JSONSchema7): unknown {
+  try {
+    return generateFromSchema({ schema });
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * If response headers are defined, convert a response value into a triple [status, body, headers].
+ * Otherwise return the value as-is.
+ */
+function addHeaders(
+  value: Schmock.ResponseResult,
+  headerDefs: Record<string, Schmock.ResponseHeaderDef> | undefined,
+): Schmock.ResponseResult {
+  const headers = generateHeaderValues(headerDefs);
+  if (Object.keys(headers).length === 0) {
+    return value;
+  }
+
+  // If already a tuple [status, body] or [status, body, headers]
+  if (Array.isArray(value) && value.length >= 2) {
+    const status = typeof value[0] === "number" ? value[0] : 200;
+    return [status, value[1], headers];
+  }
+
+  // Plain value → [200, body, headers]
+  return [200, value, headers];
+}
+
 function findById(
   collection: unknown[],
   idParam: string,

package/src/index.ts

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

package/src/normalizer.ts

@@ -1,4 +1,4 @@
-/// <reference path="../../../types/schmock.d.ts" />
+/// <reference path="../../core/schmock.d.ts" />
 
 import type { JSONSchema7 } from "json-schema";
 import { isRecord, toJsonSchema } from "./utils.js";