@schmock/faker 2.2.3 → 2.3.0

package/dist/test-utils.js

@@ -1,5 +1,8 @@
 import { expect } from "vitest";
 import { generateFromSchema } from "./index";
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
 // Schema Factory Functions
 export const schemas = {
     simple: {
@@ -89,16 +92,22 @@ export const validators = {
         // Generate multiple samples to check for patterns
         const mappedSamples = [];
         for (let i = 0; i < 10; i++) {
-            const result = (await generateFromSchema({
+            const result = await generateFromSchema({
                 schema: mappedSchema,
-            }));
+            });
+            if (!isRecord(result)) {
+                throw new Error("Expected mapped schema generation to return an object");
+            }
             mappedSamples.push(result[fieldName]);
         }
         const unmappedSamples = [];
         for (let i = 0; i < 10; i++) {
-            const result = (await generateFromSchema({
+            const result = await generateFromSchema({
                 schema: unmappedSchema,
-            }));
+            });
+            if (!isRecord(result)) {
+                throw new Error("Expected unmapped schema generation to return an object");
+            }
             unmappedSamples.push(result.unmappedRandomField12345);
         }
         // If field is mapped to a specific faker method, it should have different characteristics
@@ -179,14 +188,12 @@ export const generate = {
     samples: async (schema, count = 10, options) => {
         const results = [];
         for (let i = 0; i < count; i++) {
-            results.push((await generateFromSchema({ schema, ...options })));
+            results.push(await generateFromSchema({ schema, ...options }));
         }
         return results;
     },
-    withSeed: async (schema, _seed) => {
-        // Note: faker.js doesn't support seeding in the same way,
-        // but we can at least ensure consistent test behavior
-        return await generateFromSchema({ schema });
+    withSeed: async (schema, seed) => {
+        return await generateFromSchema({ schema, seed });
     },
 };
 // Statistical Analysis
@@ -194,7 +201,7 @@ export const stats = {
     distribution: (samples) => {
         const dist = new Map();
         for (const sample of samples) {
-            const key = JSON.stringify(sample);
+            const key = JSON.stringify(sample) ?? "undefined";
             dist.set(key, (dist.get(key) || 0) + 1);
         }
         return dist;
@@ -231,9 +238,15 @@ export const schemaTests = {
             throw new Error("Expected schema validation to fail");
         }
         catch (error) {
+            expect(error).toBeInstanceOf(Error);
+            if (!(error instanceof Error)) {
+                throw new Error("Expected schema validation to throw an Error");
+            }
             expect(error.name).toBe("SchemaValidationError");
             // The schemaPath is in the context
-            if (error.context?.schemaPath) {
+            if ("context" in error &&
+                isRecord(error.context) &&
+                error.context.schemaPath) {
                 expect(error.context.schemaPath).toBe(path);
             }
             if (issue) {
@@ -248,7 +261,7 @@ function analyzeDataCharacteristics(samples) {
         return "empty";
     const first = samples[0];
     const type = typeof first;
-    if (type !== "string")
+    if (!samples.every((sample) => typeof sample === "string"))
         return type;
     // Analyze string characteristics
     const characteristics = [type];

package/dist/validation.js

@@ -288,7 +288,7 @@ export function validateFakerMethod(fakerMethod) {
     let current = faker;
     for (const part of parts) {
         if (current && typeof current === "object" && part in current) {
-            current = current[part];
+            current = Reflect.get(current, part);
         }
         else {
             throw new SchemaValidationError("$.faker", `Invalid faker method: "${fakerMethod}"`, "Check faker.js documentation for valid methods");

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@schmock/faker",
   "description": "Faker-powered automatic data generation for Schmock",
-  "version": "2.2.3",
+  "version": "2.3.0",
   "type": "module",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -21,7 +21,7 @@
     "build": "bun build:lib && bun build:types",
     "build:lib": "bun build --minify --target browser --outdir=dist src/index.ts --external @faker-js/faker --external json-schema-faker --external @schmock/core",
     "build:types": "tsc -p tsconfig.json",
-    "test": "vitest",
+    "test": "vitest run",
     "test:watch": "vitest --watch",
     "test:bdd": "vitest run --config vitest.config.bdd.ts",
     "lint": "biome check src/*.ts",
@@ -30,15 +30,15 @@
   },
   "license": "MIT",
   "dependencies": {
+    "@types/json-schema": "^7.0.15",
     "@faker-js/faker": "^10.5.0",
     "json-schema-faker": "^0.6.2"
   },
   "peerDependencies": {
-    "@schmock/core": "^2.2.3"
+    "@schmock/core": "^2.3.0"
   },
   "devDependencies": {
     "@amiceli/vitest-cucumber": "^7.0.0",
-    "@types/json-schema": "^7.0.15",
     "@types/node": "^26.1.0",
     "vitest": "^4.1.9"
   }

package/src/field-mappings.ts

@@ -412,7 +412,14 @@ const text: FieldMapping[] = [
 // ── Business/Commerce ───────────────────────────────────────────────
 const business: FieldMapping[] = [
   {
-    keywords: ["company", "organization", "org", "employer", "brand"],
+    keywords: [
+      "company",
+      "organization",
+      "org",
+      "employer",
+      "brand",
+      "operator",
+    ],
     fakerMethod: "company.name",
     schemaType: "string",
     minScore: 0.6,

package/src/field-name-matcher.ts

@@ -93,7 +93,6 @@ export function findBestMapping(
   schema: JSONSchema7,
   mappings: FieldMapping[] = ALL_FIELD_MAPPINGS,
 ): MatchResult | undefined {
-  const schemaAny = schema as Record<string, unknown>;
   const schemaType = typeof schema.type === "string" ? schema.type : undefined;
 
   // Priority: format:uuid always maps to string.uuid
@@ -115,10 +114,10 @@ export function findBestMapping(
   // constraints, so they'd produce out-of-range strings ~20% of the time.
   // Mirrors the numeric constraint skip just below.
   if (
-    schemaAny.pattern ||
-    schemaAny.enum ||
-    schemaAny.faker ||
-    schemaAny.$ref ||
+    schema.pattern ||
+    schema.enum ||
+    ("faker" in schema && schema.faker) ||
+    schema.$ref ||
     (schemaType === "string" &&
       (schema.minLength !== undefined || schema.maxLength !== undefined))
   ) {

package/src/index.test.ts

@@ -41,6 +41,108 @@ describe("Schema Generator", () => {
       });
     });
 
+    it("uses one seeded sequence across a generated array", async () => {
+      const schema: JSONSchema7 = {
+        type: "array",
+        items: {
+          type: "object",
+          properties: {
+            id: { type: "integer" },
+            name: { type: "string" },
+          },
+          required: ["id", "name"],
+        },
+      };
+
+      const first = await generateFromSchema({ schema, count: 5, seed: 42 });
+      const second = await generateFromSchema({ schema, count: 5, seed: 42 });
+
+      expect(first).toEqual(second);
+      expect(Array.isArray(first)).toBe(true);
+      if (!Array.isArray(first)) {
+        throw new Error("Expected generated data to be an array");
+      }
+      expect(new Set(first.map((item) => JSON.stringify(item))).size).toBe(5);
+    });
+
+    it("generates tuple positions from their respective schemas", async () => {
+      const schema: JSONSchema7 = {
+        type: "array",
+        items: [{ type: "string" }, { type: "integer" }, { type: "boolean" }],
+        minItems: 3,
+        maxItems: 3,
+      };
+
+      const result = await generateFromSchema({ schema, seed: 42 });
+
+      expect(Array.isArray(result)).toBe(true);
+      if (!Array.isArray(result)) {
+        throw new Error("Expected generated data to be a tuple");
+      }
+      expect(result).toHaveLength(3);
+      expect(typeof result[0]).toBe("string");
+      expect(typeof result[1]).toBe("number");
+      expect(typeof result[2]).toBe("boolean");
+    });
+
+    it("generates a nested tuple reached through a definition reference", async () => {
+      const schema: JSONSchema7 = {
+        type: "object",
+        properties: {
+          payload: { $ref: "#/definitions/payloadTuple" },
+        },
+        required: ["payload"],
+        definitions: {
+          payloadTuple: {
+            type: "array",
+            items: [
+              { type: "string" },
+              { type: "integer" },
+              { type: "boolean" },
+            ],
+            minItems: 3,
+            maxItems: 3,
+            additionalItems: false,
+          },
+        },
+      };
+
+      const result = await generateFromSchema({ schema, seed: 42 });
+
+      expect(result).toMatchObject({ payload: expect.any(Array) });
+      if (
+        typeof result !== "object" ||
+        result === null ||
+        !("payload" in result) ||
+        !Array.isArray(result.payload)
+      ) {
+        throw new Error("Expected generated payload to be a tuple");
+      }
+      expect(result.payload).toHaveLength(3);
+      expect(typeof result.payload[0]).toBe("string");
+      expect(typeof result.payload[1]).toBe("number");
+      expect(typeof result.payload[2]).toBe("boolean");
+    });
+
+    it("honors uniqueItems while generating the complete array", async () => {
+      const schema: JSONSchema7 = {
+        type: "array",
+        items: { type: "integer" },
+        minItems: 8,
+        maxItems: 8,
+        uniqueItems: true,
+      };
+
+      const result = await generateFromSchema({ schema, seed: 42 });
+
+      expect(Array.isArray(result)).toBe(true);
+      if (!Array.isArray(result)) {
+        throw new Error("Expected generated data to be an array");
+      }
+      expect(result).toHaveLength(8);
+      expect(new Set(result).size).toBe(8);
+    });
+
     it("respects array constraints from schema", async () => {
       const schema = schemas.simple.array(schemas.simple.string(), {
         minItems: 2,

package/src/index.ts

@@ -8,7 +8,11 @@ import {
 import type { JSONSchema7 } from "json-schema";
 import { version as packageVersion } from "../package.json";
 import { MAX_ARRAY_SIZE, NULLABLE_NULL_PROBABILITY } from "./constants.js";
-import { generateWithJsf } from "./jsf-config.js";
+import {
+  createSeededRandom,
+  generateWithJsf,
+  resolveGenerationSeed,
+} from "./jsf-config.js";
 import { applyOverrides, determineArrayCount } from "./overrides.js";
 import { enhanceSchemaWithSmartMapping } from "./schema-enhancement.js";
 import { isJSONSchema7, validateSchema } from "./validation.js";
@@ -17,6 +21,10 @@ export type SchemaGenerationContext = Schmock.SchemaGenerationContext;
 
 export type FakerPluginOptions = Schmock.FakerPluginOptions;
 
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
 export function fakerPlugin(options: FakerPluginOptions): Schmock.Plugin {
   // Validate schema immediately when plugin is created (fail-fast)
   validateSchema(options.schema);
@@ -73,43 +81,39 @@ export async function generateFromSchema(
 
   validateSchema(schema);
 
-  // Handle array schemas with count
+  const generationSeed = resolveGenerationSeed(seed);
+  const random = createSeededRandom(generationSeed);
+
+  let enhancedSchema = enhanceSchemaWithSmartMapping(schema);
+
+  // Resolve the top-level array size once, then let JSF generate the complete
+  // array so tuple positions, uniqueness, and a seeded sequence are preserved.
   if (schema.type === "array" && schema.items) {
-    const itemCount = determineArrayCount(schema, count);
+    const itemCount = determineArrayCount(schema, count, random);
 
-    // Check for resource limits
     if (itemCount > MAX_ARRAY_SIZE) {
       throw new ResourceLimitError("array_size", MAX_ARRAY_SIZE, itemCount);
     }
 
-    const rawItemSchema = Array.isArray(schema.items)
-      ? schema.items[0]
-      : schema.items;
-
-    if (!rawItemSchema || typeof rawItemSchema === "boolean") {
-      throw new SchemaValidationError(
-        "$.items",
-        "Array schema must have valid items definition",
-      );
-    }
+    enhancedSchema = {
+      ...enhancedSchema,
+      minItems: itemCount,
+      maxItems: itemCount,
+    };
+  }
 
-    const itemSchema = rawItemSchema;
-    const enhancedItemSchema = enhanceSchemaWithSmartMapping(itemSchema);
+  let generated: unknown = await generateWithJsf(
+    enhancedSchema,
+    generationSeed,
+  );
+  generated = postProcessGenerated(generated, enhancedSchema, random);
 
-    const items: unknown[] = [];
-    for (let i = 0; i < itemCount; i++) {
-      let item: unknown = await generateWithJsf(enhancedItemSchema, seed);
-      item = postProcessGenerated(item, enhancedItemSchema);
-      item = applyOverrides(item, overrides, params, state, query);
-      items.push(item);
-    }
-    return items;
+  if (Array.isArray(generated)) {
+    return generated.map((item) =>
+      applyOverrides(item, overrides, params, state, query),
+    );
   }
 
-  // Handle object schemas
-  const enhancedSchema = enhanceSchemaWithSmartMapping(schema);
-  let generated: unknown = await generateWithJsf(enhancedSchema, seed);
-  generated = postProcessGenerated(generated, enhancedSchema);
   generated = applyOverrides(generated, overrides, params, state, query);
   return generated;
 }
@@ -120,7 +124,11 @@ export async function generateFromSchema(
  * - schmockNullable: ~5% chance of null
  * - schmockTrueProbability: weighted boolean generation
  */
-function postProcessGenerated(data: unknown, schema: JSONSchema7): unknown {
+function postProcessGenerated(
+  data: unknown,
+  schema: JSONSchema7,
+  random: () => number,
+): unknown {
   if (
     data === null ||
     data === undefined ||
@@ -130,11 +138,9 @@ function postProcessGenerated(data: unknown, schema: JSONSchema7): unknown {
     return data;
   }
 
-  const schemaExt = schema as Record<string, unknown>;
-
   // Apply nullable probability at this level
-  if (schemaExt.schmockNullable === true) {
-    if (Math.random() < NULLABLE_NULL_PROBABILITY) {
+  if ("schmockNullable" in schema && schema.schmockNullable === true) {
+    if (random() < NULLABLE_NULL_PROBABILITY) {
       return null;
     }
   }
@@ -142,25 +148,36 @@ function postProcessGenerated(data: unknown, schema: JSONSchema7): unknown {
   // Apply boolean weighting at this level
   if (
     schema.type === "boolean" &&
-    typeof schemaExt.schmockTrueProbability === "number"
+    "schmockTrueProbability" in schema &&
+    typeof schema.schmockTrueProbability === "number"
   ) {
-    return Math.random() < schemaExt.schmockTrueProbability;
+    return random() < schema.schmockTrueProbability;
   }
 
   // Recurse into object properties
-  if (typeof data === "object" && !Array.isArray(data) && schema.properties) {
-    const record = data as Record<string, unknown>;
+  if (isRecord(data) && schema.properties) {
     for (const [key, propSchema] of Object.entries(schema.properties)) {
-      if (key in record && isJSONSchema7(propSchema)) {
-        record[key] = postProcessGenerated(record[key], propSchema);
+      if (key in data && isJSONSchema7(propSchema)) {
+        data[key] = postProcessGenerated(data[key], propSchema, random);
       }
     }
   }
 
   // Recurse into array items
-  if (Array.isArray(data) && schema.items && isJSONSchema7(schema.items)) {
-    for (let i = 0; i < data.length; i++) {
-      data[i] = postProcessGenerated(data[i], schema.items);
+  if (Array.isArray(data) && Array.isArray(schema.items)) {
+    for (let index = 0; index < data.length; index++) {
+      const itemSchema = schema.items[index];
+      if (itemSchema && isJSONSchema7(itemSchema)) {
+        data[index] = postProcessGenerated(data[index], itemSchema, random);
+      }
+    }
+  } else if (
+    Array.isArray(data) &&
+    schema.items &&
+    isJSONSchema7(schema.items)
+  ) {
+    for (let index = 0; index < data.length; index++) {
+      data[index] = postProcessGenerated(data[index], schema.items, random);
     }
   }
 

package/src/jsf-config.test.ts

@@ -0,0 +1,65 @@
+import type { JSONSchema7 } from "json-schema";
+import { describe, expect, it } from "vitest";
+import { normalizeSchemaForJsf } from "./jsf-config.js";
+
+const tuple: JSONSchema7 = {
+  type: "array",
+  items: [{ type: "string" }, { type: "integer" }],
+  minItems: 2,
+  maxItems: 2,
+  additionalItems: false,
+};
+
+function expectNormalizedTuple(value: unknown): void {
+  expect(value).toMatchObject({
+    type: "array",
+    prefixItems: [{ type: "string" }, { type: "integer" }],
+    items: false,
+  });
+  expect(value).not.toHaveProperty("additionalItems");
+}
+
+describe("normalizeSchemaForJsf", () => {
+  it("recurses through Draft-7 schema-bearing keywords", () => {
+    const normalized = normalizeSchemaForJsf({
+      type: "object",
+      definitions: { legacy: tuple },
+      $defs: { modern: tuple },
+      patternProperties: { "^tuple$": tuple },
+      contains: tuple,
+      not: tuple,
+      if: tuple,
+      // biome-ignore lint/suspicious/noThenProperty: JSON Schema's conditional keyword is named "then"
+      then: tuple,
+      else: tuple,
+    });
+
+    const record: Record<string, unknown> = normalized;
+    const definitions = record.definitions;
+    const defs = record.$defs;
+    const patternProperties = record.patternProperties;
+
+    expect(definitions).toBeTypeOf("object");
+    expect(defs).toBeTypeOf("object");
+    expect(patternProperties).toBeTypeOf("object");
+    if (
+      definitions === null ||
+      typeof definitions !== "object" ||
+      defs === null ||
+      typeof defs !== "object" ||
+      patternProperties === null ||
+      typeof patternProperties !== "object"
+    ) {
+      throw new Error("Expected normalized schema maps");
+    }
+
+    expectNormalizedTuple(Reflect.get(definitions, "legacy"));
+    expectNormalizedTuple(Reflect.get(defs, "modern"));
+    expectNormalizedTuple(Reflect.get(patternProperties, "^tuple$"));
+    expectNormalizedTuple(record.contains);
+    expectNormalizedTuple(record.not);
+    expectNormalizedTuple(record.if);
+    expectNormalizedTuple(record.then);
+    expectNormalizedTuple(record.else);
+  });
+});

package/src/jsf-config.ts

@@ -1,11 +1,14 @@
 import { base, en, Faker } from "@faker-js/faker";
-import type { JSONSchema7 } from "json-schema";
+import type { JSONSchema7, JSONSchema7Definition } from "json-schema";
 import {
   type GenerateOptions,
   generate,
   type JsonSchema,
 } from "json-schema-faker";
 
+const MAX_GENERATION_SEED = 2_147_483_647;
+type JsfObjectSchema = Exclude<JsonSchema, boolean>;
+
 /**
  * Create isolated faker instance to avoid race conditions.
  * Each generation gets its own faker instance to ensure thread-safety.
@@ -18,31 +21,136 @@ export function createFakerInstance(seed?: number) {
   return faker;
 }
 
+export function resolveGenerationSeed(seed?: number): number {
+  return seed ?? Math.floor(Math.random() * MAX_GENERATION_SEED);
+}
+
+export function createSeededRandom(seed: number): () => number {
+  let state = seed;
+  return () => {
+    state += 0x6d2b79f5;
+    let value = state;
+    value = Math.imul(value ^ (value >>> 15), value | 1);
+    value ^= value + Math.imul(value ^ (value >>> 7), value | 61);
+    return ((value ^ (value >>> 14)) >>> 0) / 4_294_967_296;
+  };
+}
+
+function normalizeDefinitionForJsf(
+  definition: JSONSchema7Definition,
+): JsonSchema {
+  return typeof definition === "boolean"
+    ? definition
+    : normalizeSchemaForJsf(definition);
+}
+
+function normalizeDefinitionMap(
+  definitions: Record<string, JSONSchema7Definition>,
+): Record<string, JsonSchema> {
+  return Object.fromEntries(
+    Object.entries(definitions).map(([key, definition]) => [
+      key,
+      normalizeDefinitionForJsf(definition),
+    ]),
+  );
+}
+
+/**
+ * json-schema-faker consumes tuple schemas through the 2020-12 `prefixItems`
+ * keyword. Convert Draft 7 tuple `items` recursively at the library boundary.
+ */
+export function normalizeSchemaForJsf(schema: JSONSchema7): JsfObjectSchema {
+  const normalized: JsfObjectSchema = {};
+  for (const [key, value] of Object.entries(schema)) {
+    normalized[key] = value;
+  }
+
+  if (schema.properties) {
+    normalized.properties = normalizeDefinitionMap(schema.properties);
+  }
+
+  if (schema.definitions) {
+    normalized.definitions = normalizeDefinitionMap(schema.definitions);
+  }
+
+  if (schema.$defs) {
+    normalized.$defs = normalizeDefinitionMap(schema.$defs);
+  }
+
+  if (schema.patternProperties) {
+    normalized.patternProperties = normalizeDefinitionMap(
+      schema.patternProperties,
+    );
+  }
+
+  if (Array.isArray(schema.items)) {
+    normalized.prefixItems = schema.items.map(normalizeDefinitionForJsf);
+    normalized.items =
+      schema.additionalItems === undefined
+        ? true
+        : normalizeDefinitionForJsf(schema.additionalItems);
+    delete normalized.additionalItems;
+  } else if (schema.items !== undefined) {
+    normalized.items = normalizeDefinitionForJsf(schema.items);
+  }
+
+  for (const keyword of ["allOf", "anyOf", "oneOf"] as const) {
+    const definitions = schema[keyword];
+    if (definitions) {
+      normalized[keyword] = definitions.map(normalizeDefinitionForJsf);
+    }
+  }
+
+  if (schema.additionalProperties !== undefined) {
+    normalized.additionalProperties = normalizeDefinitionForJsf(
+      schema.additionalProperties,
+    );
+  }
+
+  for (const keyword of [
+    "contains",
+    "not",
+    "if",
+    "then",
+    "else",
+    "propertyNames",
+  ] as const) {
+    const definition = schema[keyword];
+    if (definition !== undefined) {
+      normalized[keyword] = normalizeDefinitionForJsf(definition);
+    }
+  }
+
+  if (schema.dependencies) {
+    normalized.dependencies = Object.fromEntries(
+      Object.entries(schema.dependencies).map(([key, dependency]) => [
+        key,
+        Array.isArray(dependency)
+          ? [...dependency]
+          : normalizeDefinitionForJsf(dependency),
+      ]),
+    );
+  }
+
+  return normalized;
+}
+
 /**
  * Generate data from a JSON schema using json-schema-faker 0.6.0 async API.
  * Stateless — each call is self-contained with its own faker instance and options.
  */
 export async function generateWithJsf(
   schema: JSONSchema7,
-  seed?: number,
+  seed: number,
 ): Promise<unknown> {
-  // When no seed is specified, generate a random seed to ensure different
-  // results on each call. JSF 0.6.0 treats seed=undefined as deterministic.
-  const effectiveSeed = seed ?? Math.floor(Math.random() * 2147483647);
-
-  return generate(
-    // JSONSchema7.items allows arrays but JsonSchema.items does not — structural
-    // mismatch requires routing through `unknown`.
-    schema as unknown as JsonSchema,
-    {
-      seed: effectiveSeed,
-      optionalsProbability: 1.0,
-      alwaysFakeOptionals: true,
-      useDefaultValue: true,
-      ignoreMissingRefs: true,
-      failOnInvalidTypes: false,
-      failOnInvalidFormat: false,
-      extensions: { faker: createFakerInstance(seed) },
-    } as GenerateOptions & Record<string, unknown>,
-  );
+  const options: GenerateOptions = {
+    seed,
+    optionalsProbability: 1.0,
+    alwaysFakeOptionals: true,
+    useDefaultValue: true,
+    failOnInvalidTypes: false,
+    extensions: { faker: createFakerInstance(seed) },
+  };
+
+  return generate(normalizeSchemaForJsf(schema), options);
 }