@schmock/faker 1.9.5 → 1.12.0

package/src/field-name-matcher.test.ts

@@ -0,0 +1,252 @@
+import { describe, expect, it } from "vitest";
+import {
+  findBestMapping,
+  scoreMatch,
+  tokenizeFieldName,
+} from "./field-name-matcher";
+
+describe("tokenizeFieldName", () => {
+  it("splits camelCase", () => {
+    expect(tokenizeFieldName("userFirstName")).toEqual([
+      "user",
+      "first",
+      "name",
+    ]);
+  });
+
+  it("splits snake_case", () => {
+    expect(tokenizeFieldName("created_at")).toEqual(["created", "at"]);
+  });
+
+  it("splits kebab-case", () => {
+    expect(tokenizeFieldName("user-name")).toEqual(["user", "name"]);
+  });
+
+  it("handles consecutive uppercase (HTMLParser)", () => {
+    expect(tokenizeFieldName("HTMLParser")).toEqual(["html", "parser"]);
+  });
+
+  it("handles is_active", () => {
+    expect(tokenizeFieldName("is_active")).toEqual(["is", "active"]);
+  });
+
+  it("handles single word", () => {
+    expect(tokenizeFieldName("email")).toEqual(["email"]);
+  });
+
+  it("handles uppercase single word", () => {
+    expect(tokenizeFieldName("UUID")).toEqual(["uuid"]);
+  });
+
+  it("handles mixed formats", () => {
+    expect(tokenizeFieldName("userEmail_address")).toEqual([
+      "user",
+      "email",
+      "address",
+    ]);
+  });
+});
+
+describe("scoreMatch", () => {
+  it("returns 1.0 for exact match", () => {
+    expect(scoreMatch(["email"], ["email"])).toBe(1.0);
+  });
+
+  it("returns 1.0 for exact multi-token match", () => {
+    expect(scoreMatch(["first", "name"], ["first_name"])).toBe(1.0);
+  });
+
+  it("returns 0.7 for substring match with low keyword coverage", () => {
+    // "email" is 1/3 tokens → low coverage (0.65) but substring match (0.7) wins
+    expect(scoreMatch(["user", "email", "address"], ["email"])).toBe(0.7);
+  });
+
+  it("returns 0.9 when all keyword tokens found with high coverage", () => {
+    // ["created", "at"] are both found in ["user", "created", "at"] → 2/3 coverage > 50%
+    expect(scoreMatch(["user", "created", "at"], ["created_at"])).toBe(0.9);
+  });
+
+  it("returns 0.8 when field ends with keyword", () => {
+    // ["name"] is at the end of ["display", "name"] — ends-with score = 0.8
+    // coverage is 1/2 = 0.5, not > 0.5, so "all found" gives 0.65
+    // ends-with wins at 0.8
+    expect(scoreMatch(["display", "name"], ["name"])).toBe(0.8);
+  });
+
+  it("returns 0.7 for substring match", () => {
+    expect(scoreMatch(["myemailfield"], ["email"])).toBe(0.7);
+  });
+
+  it("returns 0 for no match", () => {
+    expect(scoreMatch(["foo", "bar"], ["email"])).toBe(0);
+  });
+});
+
+describe("findBestMapping", () => {
+  it("maps email field", () => {
+    const result = findBestMapping("email", { type: "string" });
+    expect(result).toBeDefined();
+    expect(result?.mapping.fakerMethod).toBe("internet.email");
+  });
+
+  it("maps userEmail field", () => {
+    const result = findBestMapping("userEmail", { type: "string" });
+    expect(result).toBeDefined();
+    expect(result?.mapping.fakerMethod).toBe("internet.email");
+  });
+
+  it("maps firstName field", () => {
+    const result = findBestMapping("firstName", { type: "string" });
+    expect(result).toBeDefined();
+    expect(result?.mapping.fakerMethod).toBe("person.firstName");
+  });
+
+  it("maps first_name field", () => {
+    const result = findBestMapping("first_name", { type: "string" });
+    expect(result).toBeDefined();
+    expect(result?.mapping.fakerMethod).toBe("person.firstName");
+  });
+
+  it("maps createdAt to date.recent", () => {
+    const result = findBestMapping("createdAt", { type: "string" });
+    expect(result).toBeDefined();
+    expect(result?.mapping.fakerMethod).toBe("date.recent");
+    expect(result?.mapping.format).toBe("date-time");
+  });
+
+  it("maps city field", () => {
+    const result = findBestMapping("city", { type: "string" });
+    expect(result).toBeDefined();
+    expect(result?.mapping.fakerMethod).toBe("location.city");
+  });
+
+  it("maps url field", () => {
+    const result = findBestMapping("url", { type: "string" });
+    expect(result).toBeDefined();
+    expect(result?.mapping.fakerMethod).toBe("internet.url");
+  });
+
+  it("maps avatar field", () => {
+    const result = findBestMapping("avatar", { type: "string" });
+    expect(result).toBeDefined();
+    expect(result?.mapping.fakerMethod).toBe("image.avatar");
+  });
+
+  it("maps latitude field to number", () => {
+    const result = findBestMapping("latitude", { type: "number" });
+    expect(result).toBeDefined();
+    expect(result?.mapping.fakerMethod).toBe("location.latitude");
+  });
+
+  it("maps description field", () => {
+    const result = findBestMapping("description", { type: "string" });
+    expect(result).toBeDefined();
+    expect(result?.mapping.fakerMethod).toBe("lorem.paragraph");
+  });
+
+  it("maps title field", () => {
+    const result = findBestMapping("title", { type: "string" });
+    expect(result).toBeDefined();
+    expect(result?.mapping.fakerMethod).toBe("lorem.sentence");
+  });
+
+  it("maps country field", () => {
+    const result = findBestMapping("country", { type: "string" });
+    expect(result).toBeDefined();
+    expect(result?.mapping.fakerMethod).toBe("location.country");
+  });
+
+  it("maps isActive boolean with probability", () => {
+    const result = findBestMapping("isActive", { type: "boolean" });
+    expect(result).toBeDefined();
+    expect(result?.mapping.trueProbability).toBe(0.9);
+  });
+
+  it("maps is_deleted boolean with low probability", () => {
+    const result = findBestMapping("is_deleted", { type: "boolean" });
+    expect(result).toBeDefined();
+    expect(result?.mapping.trueProbability).toBe(0.05);
+  });
+
+  describe("ID suffix detection", () => {
+    it("maps userId to UUID", () => {
+      const result = findBestMapping("userId", { type: "string" });
+      expect(result).toBeDefined();
+      expect(result?.mapping.fakerMethod).toBe("string.uuid");
+    });
+
+    it("maps order_id to UUID", () => {
+      const result = findBestMapping("order_id", { type: "string" });
+      expect(result).toBeDefined();
+      expect(result?.mapping.fakerMethod).toBe("string.uuid");
+    });
+
+    it("maps parent_id to UUID", () => {
+      const result = findBestMapping("parent_id", { type: "string" });
+      expect(result).toBeDefined();
+      expect(result?.mapping.fakerMethod).toBe("string.uuid");
+    });
+
+    it("does not map single id without format:uuid", () => {
+      const result = findBestMapping("id", { type: "string" });
+      // 'id' alone shouldn't trigger UUID — it's a single token so suffix rule doesn't apply
+      // But it could still match something else. Let's just check it doesn't falsely match
+      if (result) {
+        // Could match 'id' in some mapping, that's OK
+        expect(result.score).toBeGreaterThan(0);
+      }
+    });
+
+    it("does not map Id suffix on number fields", () => {
+      const result = findBestMapping("userId", { type: "number" });
+      // Number type should not get UUID mapping
+      if (result) {
+        expect(result.mapping.fakerMethod).not.toBe("string.uuid");
+      }
+    });
+  });
+
+  describe("skip conditions", () => {
+    it("skips when schema has pattern", () => {
+      const result = findBestMapping("email", {
+        type: "string",
+        pattern: "^[a-z]+$",
+      });
+      expect(result).toBeUndefined();
+    });
+
+    it("skips when schema has enum", () => {
+      const result = findBestMapping("email", {
+        type: "string",
+        enum: ["a@b.com", "c@d.com"],
+      });
+      expect(result).toBeUndefined();
+    });
+
+    it("skips when schema already has faker", () => {
+      const schema = { type: "string" as const, faker: "lorem.word" } as any;
+      const result = findBestMapping("email", schema);
+      expect(result).toBeUndefined();
+    });
+  });
+
+  it("does not map unrecognized fields", () => {
+    const result = findBestMapping("randomFieldXYZ123", { type: "string" });
+    expect(result).toBeUndefined();
+  });
+
+  it("respects type constraints", () => {
+    // latitude mapping requires number type
+    const result = findBestMapping("latitude", { type: "string" });
+    expect(result).toBeUndefined();
+  });
+
+  it("maps format:uuid even without name match", () => {
+    const result = findBestMapping("someField", {
+      type: "string",
+      format: "uuid",
+    });
+    expect(result).toBeDefined();
+    expect(result?.mapping.fakerMethod).toBe("string.uuid");
+  });
+});

package/src/field-name-matcher.ts

@@ -0,0 +1,172 @@
+import type { JSONSchema7 } from "json-schema";
+import type { FieldMapping } from "./field-mappings.js";
+import { ALL_FIELD_MAPPINGS } from "./field-mappings.js";
+
+/**
+ * Split a field name (camelCase, snake_case, kebab-case) into lowercase tokens.
+ * "userFirstName" → ["user", "first", "name"]
+ * "created_at"    → ["created", "at"]
+ * "HTMLParser"    → ["html", "parser"]
+ * "is_active"     → ["is", "active"]
+ */
+export function tokenizeFieldName(name: string): string[] {
+  // Split on _ and -
+  const parts = name.split(/[_-]/);
+  const tokens: string[] = [];
+
+  for (const part of parts) {
+    if (!part) continue;
+    // Split camelCase and consecutive uppercase (e.g., HTMLParser → HTML, Parser)
+    const camelTokens = part
+      .replace(/([A-Z]+)([A-Z][a-z])/g, "$1_$2")
+      .replace(/([a-z0-9])([A-Z])/g, "$1_$2")
+      .split("_");
+
+    for (const t of camelTokens) {
+      if (t) tokens.push(t.toLowerCase());
+    }
+  }
+
+  return tokens;
+}
+
+/**
+ * Score how well a set of keyword tokens matches field name tokens.
+ * Returns 0-1:
+ *   1.0 — exact full match (joined tokens equal joined keywords)
+ *   0.9 — all keyword tokens found in field tokens with high coverage (>50%)
+ *   0.8 — field ends with keyword tokens
+ *   0.7 — substring match (keyword appears in joined field name)
+ *   0.65 — all keyword tokens found but low coverage (<=50%)
+ */
+export function scoreMatch(fieldTokens: string[], keywords: string[]): number {
+  const fieldJoined = fieldTokens.join("");
+
+  let bestScore = 0;
+
+  // Try each keyword variant, keep the highest score
+  for (const keyword of keywords) {
+    const kwTokens = tokenizeFieldName(keyword);
+    const kwJoined = kwTokens.join("");
+
+    // Exact match: joined tokens are identical
+    if (fieldJoined === kwJoined) return 1.0;
+
+    // All keyword tokens present in field tokens with high coverage
+    if (
+      kwTokens.length > 0 &&
+      kwTokens.every((kt) => fieldTokens.includes(kt))
+    ) {
+      const coverage = kwTokens.length / fieldTokens.length;
+      const score = coverage > 0.5 ? 0.9 : 0.65;
+      bestScore = Math.max(bestScore, score);
+    }
+
+    // Field ends with keyword tokens
+    if (kwTokens.length > 0 && kwTokens.length <= fieldTokens.length) {
+      const tail = fieldTokens.slice(-kwTokens.length);
+      if (tail.every((t, i) => t === kwTokens[i])) {
+        bestScore = Math.max(bestScore, 0.8);
+      }
+    }
+
+    // Substring match: keyword joined appears in field joined
+    if (kwJoined.length >= 3 && fieldJoined.includes(kwJoined)) {
+      bestScore = Math.max(bestScore, 0.7);
+    }
+  }
+
+  return bestScore;
+}
+
+interface MatchResult {
+  mapping: FieldMapping;
+  score: number;
+}
+
+/**
+ * Find the best field mapping for a given field name and schema.
+ * Returns the highest-scoring match above its threshold, or undefined.
+ */
+export function findBestMapping(
+  fieldName: string,
+  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
+  if (schemaType === "string" && schema.format === "uuid") {
+    return {
+      mapping: {
+        keywords: ["uuid"],
+        fakerMethod: "string.uuid",
+        schemaType: "string",
+        minScore: 0.5,
+      },
+      score: 1.0,
+    };
+  }
+
+  // Skip if schema already has pattern, enum, or faker constraint
+  if (schemaAny.pattern || schemaAny.enum || schemaAny.faker) {
+    return undefined;
+  }
+
+  // Skip numeric faker mapping when schema already constrains the range
+  const hasNumericConstraints =
+    schema.minimum !== undefined ||
+    schema.maximum !== undefined ||
+    schema.exclusiveMinimum !== undefined ||
+    schema.exclusiveMaximum !== undefined;
+
+  const tokens = tokenizeFieldName(fieldName);
+
+  let best: MatchResult | undefined;
+
+  for (const mapping of mappings) {
+    // Skip numeric faker mappings when schema has explicit constraints
+    if (
+      hasNumericConstraints &&
+      (mapping.schemaType === "number" || mapping.schemaType === "integer")
+    ) {
+      continue;
+    }
+
+    // Check schema type constraint
+    if (mapping.schemaType && schemaType && mapping.schemaType !== schemaType) {
+      const isNumeric =
+        (mapping.schemaType === "number" && schemaType === "integer") ||
+        (mapping.schemaType === "integer" && schemaType === "number");
+      if (!isNumeric) continue;
+    }
+
+    const score = scoreMatch(tokens, mapping.keywords);
+    if (score >= mapping.minScore && (!best || score > best.score)) {
+      best = { mapping, score };
+    }
+  }
+
+  // ID suffix detection: fields ending in Id/_id with string type → UUID
+  // Only if no better match was found or the existing match is weak
+  if (schemaType === "string") {
+    const lastToken = tokens[tokens.length - 1];
+    if (lastToken === "id" && tokens.length > 1) {
+      const idScore = 0.8;
+      if (!best || best.score < idScore) {
+        best = {
+          mapping: {
+            keywords: ["id"],
+            fakerMethod: "string.uuid",
+            schemaType: "string",
+            minScore: 0.5,
+          },
+          score: idScore,
+        };
+      }
+    }
+  }
+
+  return best;
+}

package/src/index.ts

@@ -6,11 +6,11 @@ import {
   SchemaValidationError,
 } from "@schmock/core";
 import type { JSONSchema7 } from "json-schema";
-import { MAX_ARRAY_SIZE } from "./constants.js";
+import { MAX_ARRAY_SIZE, NULLABLE_NULL_PROBABILITY } from "./constants.js";
 import { getJsf } from "./jsf-config.js";
 import { applyOverrides, determineArrayCount } from "./overrides.js";
 import { enhanceSchemaWithSmartMapping } from "./schema-enhancement.js";
-import { validateSchema } from "./validation.js";
+import { isJSONSchema7, validateSchema } from "./validation.js";
 
 export interface SchemaGenerationContext {
   schema: JSONSchema7;
@@ -106,12 +106,12 @@ export function generateFromSchema(options: SchemaGenerationContext): any {
     }
 
     const itemSchema = rawItemSchema;
+    const enhancedItemSchema = enhanceSchemaWithSmartMapping(itemSchema);
 
     generated = [];
     for (let i = 0; i < itemCount; i++) {
-      let item = getJsf(seed).generate(
-        enhanceSchemaWithSmartMapping(itemSchema),
-      );
+      let item = getJsf(seed).generate(enhancedItemSchema);
+      item = postProcessGenerated(item, enhancedItemSchema);
       item = applyOverrides(item, overrides, params, state, query);
       generated.push(item);
     }
@@ -119,8 +119,61 @@ export function generateFromSchema(options: SchemaGenerationContext): any {
     // Handle object schemas
     const enhancedSchema = enhanceSchemaWithSmartMapping(schema);
     generated = getJsf(seed).generate(enhancedSchema);
+    generated = postProcessGenerated(generated, enhancedSchema);
     generated = applyOverrides(generated, overrides, params, state, query);
   }
 
   return generated;
 }
+
+/**
+ * Post-process generated data to apply nullable probability and boolean weighting.
+ * Walks the schema and generated data in parallel, applying:
+ * - schmockNullable: ~5% chance of null
+ * - schmockTrueProbability: weighted boolean generation
+ */
+function postProcessGenerated(data: any, schema: JSONSchema7): any {
+  if (
+    data === null ||
+    data === undefined ||
+    !schema ||
+    typeof schema !== "object"
+  ) {
+    return data;
+  }
+
+  const schemaAny = schema as Record<string, unknown>;
+
+  // Apply nullable probability at this level
+  if (schemaAny.schmockNullable === true) {
+    if (Math.random() < NULLABLE_NULL_PROBABILITY) {
+      return null;
+    }
+  }
+
+  // Apply boolean weighting at this level
+  if (
+    schema.type === "boolean" &&
+    typeof schemaAny.schmockTrueProbability === "number"
+  ) {
+    return Math.random() < schemaAny.schmockTrueProbability;
+  }
+
+  // Recurse into object properties
+  if (typeof data === "object" && !Array.isArray(data) && schema.properties) {
+    for (const [key, propSchema] of Object.entries(schema.properties)) {
+      if (key in data && isJSONSchema7(propSchema)) {
+        data[key] = postProcessGenerated(data[key], propSchema);
+      }
+    }
+  }
+
+  // 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);
+    }
+  }
+
+  return data;
+}

package/src/jsf-config.ts

@@ -1,4 +1,4 @@
-import { en, Faker } from "@faker-js/faker";
+import { base, en, Faker } from "@faker-js/faker";
 import jsf from "json-schema-faker";
 
 /**
@@ -7,7 +7,7 @@ import jsf from "json-schema-faker";
  * @returns Fresh Faker instance with English locale
  */
 export function createFakerInstance(seed?: number) {
-  const faker = new Faker({ locale: [en] });
+  const faker = new Faker({ locale: [en, base] });
   if (seed !== undefined) {
     faker.seed(seed);
   }

package/src/schema-enhancement.ts

@@ -1,9 +1,12 @@
 import type { JSONSchema7 } from "json-schema";
+import { findBestMapping } from "./field-name-matcher.js";
 import { isJSONSchema7, validateFakerMethod } from "./validation.js";
 
-/** JSONSchema7 extended with json-schema-faker's `faker` property */
+/** JSONSchema7 extended with json-schema-faker's `faker` property and schmock markers */
 interface FakerSchema extends JSONSchema7 {
   faker?: string;
+  schmockNullable?: boolean;
+  schmockTrueProbability?: number;
 }
 
 export function enhanceSchemaWithSmartMapping(
@@ -13,10 +16,10 @@ export function enhanceSchemaWithSmartMapping(
     return schema;
   }
 
-  const enhanced = { ...schema };
+  const enhanced = { ...schema } as FakerSchema;
 
   // Handle object properties
-  if (enhanced.type === "object" && enhanced.properties) {
+  if (enhanced.properties) {
     enhanced.properties = { ...enhanced.properties };
 
     for (const [fieldName, fieldSchema] of Object.entries(
@@ -31,6 +34,38 @@ export function enhanceSchemaWithSmartMapping(
     }
   }
 
+  // Recurse into composition keywords
+  for (const keyword of ["allOf", "anyOf", "oneOf"] as const) {
+    const branches = enhanced[keyword];
+    if (Array.isArray(branches)) {
+      (enhanced as Record<string, unknown>)[keyword] = branches.map((branch) =>
+        isJSONSchema7(branch) ? enhanceSchemaWithSmartMapping(branch) : branch,
+      );
+    }
+  }
+
+  // Recurse into array items
+  if (enhanced.items) {
+    if (Array.isArray(enhanced.items)) {
+      enhanced.items = enhanced.items.map((item) =>
+        isJSONSchema7(item) ? enhanceSchemaWithSmartMapping(item) : item,
+      );
+    } else if (isJSONSchema7(enhanced.items)) {
+      enhanced.items = enhanceSchemaWithSmartMapping(enhanced.items);
+    }
+  }
+
+  // Recurse into additionalProperties
+  if (
+    enhanced.additionalProperties &&
+    typeof enhanced.additionalProperties === "object" &&
+    !Array.isArray(enhanced.additionalProperties)
+  ) {
+    enhanced.additionalProperties = enhanceSchemaWithSmartMapping(
+      enhanced.additionalProperties as JSONSchema7,
+    );
+  }
+
   return enhanced;
 }
 
@@ -46,60 +81,28 @@ function enhanceFieldSchema(
     return enhanced;
   }
 
-  // Apply smart field name mapping
-  const lowerFieldName = fieldName.toLowerCase();
-
-  // Email fields
-  if (lowerFieldName.includes("email")) {
-    enhanced.format = "email";
-    enhanced.faker = "internet.email";
-  }
-  // Name fields
-  else if (lowerFieldName === "firstname" || lowerFieldName === "first_name") {
-    enhanced.faker = "person.firstName";
-  } else if (lowerFieldName === "lastname" || lowerFieldName === "last_name") {
-    enhanced.faker = "person.lastName";
-  } else if (lowerFieldName === "name" || lowerFieldName === "fullname") {
-    enhanced.faker = "person.fullName";
+  // Recursively enhance nested schemas first
+  const hasComposition = enhanced.allOf || enhanced.anyOf || enhanced.oneOf;
+  if (enhanced.properties || hasComposition || enhanced.items) {
+    const recursed = enhanceSchemaWithSmartMapping(enhanced);
+    Object.assign(enhanced, recursed);
   }
-  // Phone fields
-  else if (lowerFieldName.includes("phone") || lowerFieldName === "mobile") {
-    enhanced.faker = "phone.number";
-  }
-  // Address fields
-  else if (lowerFieldName === "street" || lowerFieldName === "address") {
-    enhanced.faker = "location.streetAddress";
-  } else if (lowerFieldName === "city") {
-    enhanced.faker = "location.city";
-  } else if (lowerFieldName === "zipcode" || lowerFieldName === "zip") {
-    enhanced.faker = "location.zipCode";
-  }
-  // UUID fields
-  else if (
-    lowerFieldName === "uuid" ||
-    (lowerFieldName === "id" && enhanced.format === "uuid")
-  ) {
-    enhanced.faker = "string.uuid";
-  }
-  // Date fields
-  else if (
-    lowerFieldName.includes("createdat") ||
-    lowerFieldName.includes("created_at") ||
-    lowerFieldName.includes("updatedat") ||
-    lowerFieldName.includes("updated_at")
-  ) {
-    enhanced.format = "date-time";
-    enhanced.faker = "date.recent";
-  }
-  // Company fields
-  else if (lowerFieldName.includes("company")) {
-    enhanced.faker = "company.name";
-  } else if (lowerFieldName === "position" || lowerFieldName === "jobtitle") {
-    enhanced.faker = "person.jobTitle";
+
+  // Don't apply field-level faker mapping to composition schemas — the branches define their own types
+  if (hasComposition) {
+    return enhanced;
   }
-  // Price/money fields
-  else if (lowerFieldName === "price" || lowerFieldName === "amount") {
-    enhanced.faker = "commerce.price";
+
+  // Apply smart field name mapping via the scoring matcher
+  const match = findBestMapping(fieldName, enhanced);
+  if (match) {
+    enhanced.faker = match.mapping.fakerMethod;
+    if (match.mapping.format) {
+      enhanced.format = match.mapping.format;
+    }
+    if (match.mapping.trueProbability !== undefined) {
+      enhanced.schmockTrueProbability = match.mapping.trueProbability;
+    }
   }
 
   return enhanced;