@typokit/testing 0.1.4

package/dist/contract-generator.d.ts

@@ -0,0 +1,65 @@
+import type { HttpMethod, SchemaTypeMap } from "@typokit/types";
+/** A route definition used for contract test generation */
+export interface ContractTestRoute {
+    /** HTTP method */
+    method: HttpMethod;
+    /** Route path (e.g. "/users/:id") */
+    path: string;
+    /** Handler reference */
+    handlerRef: string;
+    /** Validator schema references */
+    validators?: {
+        params?: string;
+        query?: string;
+        body?: string;
+    };
+    /** Response schema name (for toMatchSchema assertions) */
+    responseSchema?: string;
+    /** Expected success status code (default: 200) */
+    expectedStatus?: number;
+}
+/** Supported test runners */
+export type TestRunner = "jest" | "vitest" | "rstest";
+/** Options for contract test generation */
+export interface ContractTestOptions {
+    /** Test runner to generate imports for */
+    runner: TestRunner;
+    /** Import path for the app module (e.g. "../src/app") */
+    appImport: string;
+    /** Routes to generate tests for */
+    routes: ContractTestRoute[];
+    /** Schema type metadata for validators */
+    schemas: SchemaTypeMap;
+}
+/** A generated contract test file */
+export interface ContractTestOutput {
+    /** Relative file path (e.g. "__generated__/users.contract.test.ts") */
+    filePath: string;
+    /** Generated file content */
+    content: string;
+}
+/**
+ * Generate contract test files from route schemas.
+ *
+ * Groups routes by path prefix and produces one test file per group.
+ * Each file tests: valid input → expected status, missing required
+ * fields → 400, invalid field formats → 400.
+ *
+ * ```ts
+ * const outputs = generateContractTests({
+ *   runner: "vitest",
+ *   appImport: "../src/app",
+ *   routes: [{ method: "POST", path: "/users", ... }],
+ *   schemas: { CreateUserInput: { ... } },
+ * });
+ * ```
+ */
+export declare function generateContractTests(options: ContractTestOptions): ContractTestOutput[];
+/**
+ * Detect the test runner used in a project by checking for known
+ * config files or dependencies.
+ *
+ * Returns the detected runner or "vitest" as default.
+ */
+export declare function detectTestRunner(packageJson: Record<string, unknown>): TestRunner;
+//# sourceMappingURL=contract-generator.d.ts.map

package/dist/contract-generator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract-generator.d.ts","sourceRoot":"","sources":["../src/contract-generator.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,UAAU,EAAgB,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAI9E,2DAA2D;AAC3D,MAAM,WAAW,iBAAiB;IAChC,kBAAkB;IAClB,MAAM,EAAE,UAAU,CAAC;IACnB,qCAAqC;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,wBAAwB;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB,kCAAkC;IAClC,UAAU,CAAC,EAAE;QACX,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,KAAK,CAAC,EAAE,MAAM,CAAC;QACf,IAAI,CAAC,EAAE,MAAM,CAAC;KACf,CAAC;IACF,0DAA0D;IAC1D,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,kDAAkD;IAClD,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,6BAA6B;AAC7B,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAEtD,2CAA2C;AAC3C,MAAM,WAAW,mBAAmB;IAClC,0CAA0C;IAC1C,MAAM,EAAE,UAAU,CAAC;IACnB,yDAAyD;IACzD,SAAS,EAAE,MAAM,CAAC;IAClB,mCAAmC;IACnC,MAAM,EAAE,iBAAiB,EAAE,CAAC;IAC5B,0CAA0C;IAC1C,OAAO,EAAE,aAAa,CAAC;CACxB;AAED,qCAAqC;AACrC,MAAM,WAAW,kBAAkB;IACjC,uEAAuE;IACvE,QAAQ,EAAE,MAAM,CAAC;IACjB,6BAA6B;IAC7B,OAAO,EAAE,MAAM,CAAC;CACjB;AAuHD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,mBAAmB,GAC3B,kBAAkB,EAAE,CAgBtB;AAoLD;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACnC,UAAU,CAoBZ"}

package/dist/contract-generator.js

@@ -0,0 +1,325 @@
+// @typokit/testing — Contract Test Generation
+//
+// Auto-generates baseline contract tests from route schemas.
+// Output is test-runner-agnostic (Jest, Vitest, Rstest).
+// ─── Helpers ──────────────────────────────────────────────────
+/** Deterministic seed-based data generator for inline test values */
+function generateSampleValue(type, jsdoc) {
+    // Check for format constraints
+    const format = jsdoc?.["format"] ?? jsdoc?.["@format"];
+    if (format === "email")
+        return "test@example.com";
+    if (format === "url")
+        return "https://example.com";
+    if (format === "uuid")
+        return "550e8400-e29b-41d4-a716-446655440000";
+    if (format === "date-time")
+        return "2026-01-01T00:00:00.000Z";
+    // Check for string unions
+    if (type.includes("|") && type.includes('"')) {
+        const values = type.split("|").map((v) => v.trim().replace(/^"|"$/g, ""));
+        return values[0];
+    }
+    if (type === "string")
+        return "test-value";
+    if (type === "number")
+        return 42;
+    if (type === "boolean")
+        return true;
+    if (type === "string[]")
+        return ["test-item"];
+    if (type === "number[]")
+        return [1];
+    if (type.endsWith("[]"))
+        return [];
+    return "test-value";
+}
+/** Generate an invalid value for a given type */
+function generateInvalidSampleValue(type, jsdoc) {
+    const format = jsdoc?.["format"] ?? jsdoc?.["@format"];
+    if (format === "email")
+        return "not-an-email";
+    if (format === "url")
+        return "not-a-url";
+    if (format === "uuid")
+        return "not-a-uuid";
+    if (format === "date-time")
+        return "not-a-date";
+    if (type === "number")
+        return "not-a-number";
+    if (type === "boolean")
+        return "not-a-boolean";
+    // String unions — use a value not in the set
+    if (type.includes("|") && type.includes('"')) {
+        return "__invalid_enum_value__";
+    }
+    return 12345;
+}
+/** Get the test runner import statement */
+function getImportStatement(runner) {
+    switch (runner) {
+        case "jest":
+            return 'import { describe, it, expect } from "@jest/globals";';
+        case "vitest":
+            return 'import { describe, it, expect } from "vitest";';
+        case "rstest":
+            return 'import { describe, it, expect } from "@rstest/core";';
+    }
+}
+/** Group routes by path prefix for file organization */
+function groupRoutesByPrefix(routes) {
+    const groups = {};
+    for (const route of routes) {
+        // Extract first path segment as group name
+        const segments = route.path.split("/").filter(Boolean);
+        const prefix = segments.length > 0 ? segments[0] : "root";
+        if (!groups[prefix]) {
+            groups[prefix] = [];
+        }
+        groups[prefix].push(route);
+    }
+    // Sort routes within each group deterministically
+    for (const key of Object.keys(groups)) {
+        groups[key].sort((a, b) => {
+            const methodOrder = a.method.localeCompare(b.method);
+            if (methodOrder !== 0)
+                return methodOrder;
+            return a.path.localeCompare(b.path);
+        });
+    }
+    return groups;
+}
+/** Escape a value for use in generated TypeScript code */
+function toCodeLiteral(value) {
+    if (typeof value === "string")
+        return JSON.stringify(value);
+    if (typeof value === "number")
+        return String(value);
+    if (typeof value === "boolean")
+        return String(value);
+    if (Array.isArray(value)) {
+        return `[${value.map(toCodeLiteral).join(", ")}]`;
+    }
+    return JSON.stringify(value);
+}
+/** Build a valid body object literal as code string */
+function buildBodyLiteral(schema, indent) {
+    const entries = [];
+    for (const [key, prop] of Object.entries(schema.properties)) {
+        if (prop.optional)
+            continue;
+        const value = generateSampleValue(prop.type, prop.jsdoc);
+        entries.push(`${indent}  ${key}: ${toCodeLiteral(value)},`);
+    }
+    if (entries.length === 0)
+        return "{}";
+    return `{\n${entries.join("\n")}\n${indent}}`;
+}
+// ─── Generator ────────────────────────────────────────────────
+/**
+ * Generate contract test files from route schemas.
+ *
+ * Groups routes by path prefix and produces one test file per group.
+ * Each file tests: valid input → expected status, missing required
+ * fields → 400, invalid field formats → 400.
+ *
+ * ```ts
+ * const outputs = generateContractTests({
+ *   runner: "vitest",
+ *   appImport: "../src/app",
+ *   routes: [{ method: "POST", path: "/users", ... }],
+ *   schemas: { CreateUserInput: { ... } },
+ * });
+ * ```
+ */
+export function generateContractTests(options) {
+    const { runner, appImport, routes, schemas } = options;
+    const groups = groupRoutesByPrefix(routes);
+    const outputs = [];
+    for (const [prefix, groupRoutes] of Object.entries(groups).sort(([a], [b]) => a.localeCompare(b))) {
+        const content = generateTestFile(runner, appImport, groupRoutes, schemas);
+        outputs.push({
+            filePath: `__generated__/${prefix}.contract.test.ts`,
+            content,
+        });
+    }
+    return outputs;
+}
+/** Generate a single contract test file for a group of routes */
+function generateTestFile(runner, appImport, routes, schemas) {
+    const lines = [];
+    // Header
+    lines.push("// DO NOT EDIT — regenerated on schema change");
+    lines.push(`// Generated by @typokit/testing contract-generator`);
+    lines.push("");
+    // Imports
+    lines.push(getImportStatement(runner));
+    lines.push(`import { createTestClient } from "@typokit/testing";`);
+    // Only import toMatchSchema if any route has a response schema
+    const hasResponseSchema = routes.some((r) => r.responseSchema);
+    if (hasResponseSchema) {
+        lines.push(`import { toMatchSchema } from "@typokit/testing";`);
+    }
+    lines.push(`import { app } from ${JSON.stringify(appImport)};`);
+    lines.push("");
+    // Setup
+    lines.push("let client: Awaited<ReturnType<typeof createTestClient>>;");
+    lines.push("");
+    lines.push("beforeAll(async () => {");
+    lines.push("  client = await createTestClient(app);");
+    lines.push("});");
+    lines.push("");
+    lines.push("afterAll(async () => {");
+    lines.push("  await client.close();");
+    lines.push("});");
+    lines.push("");
+    // Generate test blocks for each route
+    for (const route of routes) {
+        generateRouteTests(lines, route, schemas);
+        lines.push("");
+    }
+    return lines.join("\n");
+}
+/** Generate describe/it blocks for a single route */
+function generateRouteTests(lines, route, schemas) {
+    const { method, path, validators, responseSchema, expectedStatus } = route;
+    const successStatus = expectedStatus ?? 200;
+    const methodLower = method.toLowerCase();
+    lines.push(`describe("${method} ${path}", () => {`);
+    // Resolve body schema if validators reference one
+    const bodySchemaName = validators?.body;
+    const bodySchema = bodySchemaName ? schemas[bodySchemaName] : undefined;
+    // Determine if the method typically has a body
+    const hasBody = ["POST", "PUT", "PATCH"].includes(method);
+    // ── Test 1: Valid input → expected status ──
+    if (hasBody && bodySchema) {
+        const bodyLiteral = buildBodyLiteral(bodySchema, "      ");
+        lines.push(`  it("accepts valid ${bodySchemaName}", async () => {`);
+        lines.push(`    const res = await client.${methodLower}("${path}", {`);
+        lines.push(`      body: ${bodyLiteral},`);
+        lines.push(`    });`);
+        lines.push(`    expect(res.status).toBe(${successStatus});`);
+        if (responseSchema) {
+            lines.push(`    expect(res.body).toMatchSchema("${responseSchema}");`);
+        }
+        lines.push(`  });`);
+    }
+    else {
+        lines.push(`  it("responds with ${successStatus}", async () => {`);
+        lines.push(`    const res = await client.${methodLower}("${path}");`);
+        lines.push(`    expect(res.status).toBe(${successStatus});`);
+        if (responseSchema) {
+            lines.push(`    expect(res.body).toMatchSchema("${responseSchema}");`);
+        }
+        lines.push(`  });`);
+    }
+    // ── Test 2: Missing required fields → 400 ──
+    if (hasBody && bodySchema) {
+        const requiredFields = Object.entries(bodySchema.properties)
+            .filter(([, prop]) => !prop.optional)
+            .map(([key]) => key)
+            .sort();
+        if (requiredFields.length > 0) {
+            lines.push("");
+            lines.push(`  it("rejects missing required fields", async () => {`);
+            lines.push(`    const res = await client.${methodLower}("${path}", { body: {} });`);
+            lines.push(`    expect(res.status).toBe(400);`);
+            lines.push(`  });`);
+            // Individual field tests for more specific coverage
+            for (const field of requiredFields) {
+                lines.push("");
+                lines.push(`  it("rejects missing '${field}' field", async () => {`);
+                // Build a body with all required fields except this one
+                const partialEntries = [];
+                for (const [key, prop] of Object.entries(bodySchema.properties)) {
+                    if (prop.optional || key === field)
+                        continue;
+                    const value = generateSampleValue(prop.type, prop.jsdoc);
+                    partialEntries.push(`        ${key}: ${toCodeLiteral(value)},`);
+                }
+                const partialBody = partialEntries.length > 0
+                    ? `{\n${partialEntries.join("\n")}\n      }`
+                    : "{}";
+                lines.push(`    const res = await client.${methodLower}("${path}", {`);
+                lines.push(`      body: ${partialBody},`);
+                lines.push(`    });`);
+                lines.push(`    expect(res.status).toBe(400);`);
+                lines.push(`  });`);
+            }
+        }
+    }
+    // ── Test 3: Invalid field formats → 400 ──
+    if (hasBody && bodySchema) {
+        const fieldsWithFormats = Object.entries(bodySchema.properties)
+            .filter(([, prop]) => {
+            const jsdoc = prop.jsdoc;
+            if (!jsdoc)
+                return false;
+            return !!(jsdoc["format"] || jsdoc["@format"]);
+        })
+            .sort(([a], [b]) => a.localeCompare(b));
+        // Also include string unions and typed fields that can be invalidated
+        const fieldsWithTypes = Object.entries(bodySchema.properties)
+            .filter(([, prop]) => {
+            // Already covered by format
+            if (prop.jsdoc?.["format"] || prop.jsdoc?.["@format"])
+                return false;
+            return (prop.type === "number" ||
+                prop.type === "boolean" ||
+                (prop.type.includes("|") && prop.type.includes('"')));
+        })
+            .sort(([a], [b]) => a.localeCompare(b));
+        const invalidFields = [...fieldsWithFormats, ...fieldsWithTypes];
+        for (const [field, prop] of invalidFields) {
+            const invalidValue = generateInvalidSampleValue(prop.type, prop.jsdoc);
+            lines.push("");
+            lines.push(`  it("rejects invalid ${field} format", async () => {`);
+            // Build a valid body, then replace the field with invalid value
+            const fullEntries = [];
+            for (const [key, p] of Object.entries(bodySchema.properties)) {
+                if (p.optional)
+                    continue;
+                const value = key === field ? invalidValue : generateSampleValue(p.type, p.jsdoc);
+                fullEntries.push(`        ${key}: ${toCodeLiteral(value)},`);
+            }
+            const fullBody = fullEntries.length > 0 ? `{\n${fullEntries.join("\n")}\n      }` : "{}";
+            lines.push(`    const res = await client.${methodLower}("${path}", {`);
+            lines.push(`      body: ${fullBody},`);
+            lines.push(`    });`);
+            lines.push(`    expect(res.status).toBe(400);`);
+            lines.push(`  });`);
+        }
+    }
+    lines.push(`});`);
+}
+/**
+ * Detect the test runner used in a project by checking for known
+ * config files or dependencies.
+ *
+ * Returns the detected runner or "vitest" as default.
+ */
+export function detectTestRunner(packageJson) {
+    const deps = {
+        ...packageJson["dependencies"],
+        ...packageJson["devDependencies"],
+    };
+    if (deps["rstest"])
+        return "rstest";
+    if (deps["vitest"])
+        return "vitest";
+    if (deps["jest"] || deps["@jest/globals"])
+        return "jest";
+    // Check scripts for runner hints
+    const scripts = packageJson["scripts"];
+    if (scripts) {
+        const testScript = scripts["test"] ?? "";
+        if (testScript.includes("rstest"))
+            return "rstest";
+        if (testScript.includes("vitest"))
+            return "vitest";
+        if (testScript.includes("jest"))
+            return "jest";
+    }
+    return "vitest";
+}
+//# sourceMappingURL=contract-generator.js.map

package/dist/contract-generator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"contract-generator.js","sourceRoot":"","sources":["../src/contract-generator.ts"],"names":[],"mappings":"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"}

package/dist/factory.d.ts

@@ -0,0 +1,27 @@
+import type { TypeMetadata } from "@typokit/types";
+/** Options for creating a factory */
+export interface FactoryOptions {
+    /** Seed for deterministic random generation */
+    seed?: number;
+}
+/** A test factory that produces typed instances */
+export interface Factory<T> {
+    /** Build a single valid instance with optional field overrides */
+    build(overrides?: Partial<T>): T;
+    /** Build multiple valid instances */
+    buildMany(count: number, overrides?: Partial<T>): T[];
+    /** Build an instance with a specific field set to an invalid value */
+    buildInvalid(field: keyof T & string): T;
+}
+/**
+ * Create a type-safe test factory from TypeMetadata.
+ *
+ * ```ts
+ * const userFactory = createFactory<User>(userMetadata, { seed: 42 });
+ * const user = userFactory.build();
+ * const admin = userFactory.build({ role: "admin" });
+ * const invalid = userFactory.buildInvalid("email");
+ * ```
+ */
+export declare function createFactory<T>(metadata: TypeMetadata, options?: FactoryOptions): Factory<T>;
+//# sourceMappingURL=factory.d.ts.map

package/dist/factory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"factory.d.ts","sourceRoot":"","sources":["../src/factory.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAgBnD,qCAAqC;AACrC,MAAM,WAAW,cAAc;IAC7B,+CAA+C;IAC/C,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,mDAAmD;AACnD,MAAM,WAAW,OAAO,CAAC,CAAC;IACxB,kEAAkE;IAClE,KAAK,CAAC,SAAS,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IACjC,qCAAqC;IACrC,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC;IACtD,sEAAsE;IACtE,YAAY,CAAC,KAAK,EAAE,MAAM,CAAC,GAAG,MAAM,GAAG,CAAC,CAAC;CAC1C;AAuJD;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAC7B,QAAQ,EAAE,YAAY,EACtB,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC,CAAC,CAAC,CAgDZ"}

package/dist/factory.js

@@ -0,0 +1,194 @@
+// @typokit/testing — Test Factories
+//
+// Type-safe test factories that produce valid/invalid fixture data
+// from TypeMetadata. Deterministic when seeded.
+// ─── Seeded PRNG (mulberry32) ─────────────────────────────────
+function mulberry32(seed) {
+    let s = seed | 0;
+    return () => {
+        s = (s + 0x6d2b79f5) | 0;
+        let t = Math.imul(s ^ (s >>> 15), 1 | s);
+        t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+        return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+    };
+}
+// ─── Random Data Generators ───────────────────────────────────
+function randomString(rand, length) {
+    const chars = "abcdefghijklmnopqrstuvwxyz";
+    let result = "";
+    for (let i = 0; i < length; i++) {
+        result += chars[Math.floor(rand() * chars.length)];
+    }
+    return result;
+}
+function randomEmail(rand) {
+    return `${randomString(rand, 8)}@${randomString(rand, 5)}.com`;
+}
+function randomUrl(rand) {
+    return `https://${randomString(rand, 8)}.com/${randomString(rand, 4)}`;
+}
+function randomUuid(rand) {
+    const hex = "0123456789abcdef";
+    const segments = [8, 4, 4, 4, 12];
+    return segments
+        .map((len) => {
+        let s = "";
+        for (let i = 0; i < len; i++) {
+            s += hex[Math.floor(rand() * 16)];
+        }
+        return s;
+    })
+        .join("-");
+}
+function randomInt(rand, min, max) {
+    return Math.floor(rand() * (max - min + 1)) + min;
+}
+function randomDate(rand) {
+    const year = randomInt(rand, 2020, 2030);
+    const month = String(randomInt(rand, 1, 12)).padStart(2, "0");
+    const day = String(randomInt(rand, 1, 28)).padStart(2, "0");
+    return `${year}-${month}-${day}T00:00:00.000Z`;
+}
+// ─── Value Generator ──────────────────────────────────────────
+function generateValue(type, jsdoc, rand) {
+    const format = jsdoc?.["format"];
+    const minLengthStr = jsdoc?.["minLength"];
+    const maxLengthStr = jsdoc?.["maxLength"];
+    const minStr = jsdoc?.["minimum"];
+    const maxStr = jsdoc?.["maximum"];
+    // Check for JSDoc format constraints first
+    if (format === "email")
+        return randomEmail(rand);
+    if (format === "url" || format === "uri")
+        return randomUrl(rand);
+    if (format === "uuid")
+        return randomUuid(rand);
+    if (format === "date" || format === "date-time")
+        return randomDate(rand);
+    // String union types like '"a" | "b" | "c"'
+    if (type.includes('" | "') || type.includes("' | '")) {
+        const values = type
+            .split("|")
+            .map((v) => v.trim().replace(/^["']|["']$/g, ""));
+        return values[Math.floor(rand() * values.length)];
+    }
+    // Handle base types
+    const baseType = type.replace(/\[\]$/, "");
+    const isArray = type.endsWith("[]");
+    const gen = () => {
+        switch (baseType) {
+            case "string": {
+                const minLen = minLengthStr ? parseInt(minLengthStr, 10) : 5;
+                const maxLen = maxLengthStr ? parseInt(maxLengthStr, 10) : 20;
+                const len = randomInt(rand, minLen, maxLen);
+                return randomString(rand, len);
+            }
+            case "number": {
+                const min = minStr ? parseInt(minStr, 10) : 1;
+                const max = maxStr ? parseInt(maxStr, 10) : 1000;
+                return randomInt(rand, min, max);
+            }
+            case "boolean":
+                return rand() > 0.5;
+            case "Date":
+                return randomDate(rand);
+            default:
+                return randomString(rand, 10);
+        }
+    };
+    if (isArray) {
+        const count = randomInt(rand, 1, 3);
+        return Array.from({ length: count }, gen);
+    }
+    return gen();
+}
+// ─── Invalid Value Generator ──────────────────────────────────
+function generateInvalidValue(type, jsdoc) {
+    const format = jsdoc?.["format"];
+    const minLengthStr = jsdoc?.["minLength"];
+    const maxStr = jsdoc?.["maximum"];
+    const minStr = jsdoc?.["minimum"];
+    if (format === "email")
+        return "not-an-email";
+    if (format === "url" || format === "uri")
+        return "not a url";
+    if (format === "uuid")
+        return "not-a-uuid";
+    if (format === "date" || format === "date-time")
+        return "not-a-date";
+    if (type.includes('" | "') || type.includes("' | '")) {
+        return "__invalid_enum_value__";
+    }
+    const baseType = type.replace(/\[\]$/, "");
+    switch (baseType) {
+        case "string": {
+            if (minLengthStr) {
+                const minLen = parseInt(minLengthStr, 10);
+                return minLen > 1 ? "x" : "";
+            }
+            return "";
+        }
+        case "number": {
+            if (maxStr)
+                return parseInt(maxStr, 10) + 100;
+            if (minStr)
+                return parseInt(minStr, 10) - 100;
+            return null;
+        }
+        case "boolean":
+            return "not-a-boolean";
+        default:
+            return null;
+    }
+}
+// ─── createFactory ────────────────────────────────────────────
+/**
+ * Create a type-safe test factory from TypeMetadata.
+ *
+ * ```ts
+ * const userFactory = createFactory<User>(userMetadata, { seed: 42 });
+ * const user = userFactory.build();
+ * const admin = userFactory.build({ role: "admin" });
+ * const invalid = userFactory.buildInvalid("email");
+ * ```
+ */
+export function createFactory(metadata, options = {}) {
+    const seed = options.seed ?? 12345;
+    function buildOne(rand, overrides) {
+        const result = {};
+        for (const [key, prop] of Object.entries(metadata.properties)) {
+            if (prop.optional && rand() > 0.7) {
+                continue; // skip some optional fields
+            }
+            result[key] = generateValue(prop.type, prop.jsdoc, rand);
+        }
+        if (overrides) {
+            Object.assign(result, overrides);
+        }
+        return result;
+    }
+    return {
+        build(overrides) {
+            const rand = mulberry32(seed);
+            return buildOne(rand, overrides);
+        },
+        buildMany(count, overrides) {
+            const rand = mulberry32(seed);
+            const results = [];
+            for (let i = 0; i < count; i++) {
+                results.push(buildOne(rand, overrides));
+            }
+            return results;
+        },
+        buildInvalid(field) {
+            const rand = mulberry32(seed);
+            const instance = buildOne(rand);
+            const prop = metadata.properties[field];
+            if (prop) {
+                instance[field] = generateInvalidValue(prop.type, prop.jsdoc);
+            }
+            return instance;
+        },
+    };
+}
+//# sourceMappingURL=factory.js.map

package/dist/factory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"factory.js","sourceRoot":"","sources":["../src/factory.ts"],"names":[],"mappings":"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"}