@amritk/generate-examples 0.0.0 → 0.2.0

package/dist/generators/build-schema.d.ts

@@ -0,0 +1,34 @@
+import type { JSONSchema } from 'json-schema-typed/draft-2020-12';
+/**
+ * Represents a generated TypeScript file with its filename and content.
+ */
+export type GeneratedFile = {
+    filename: string;
+    content: string;
+};
+/**
+ * Builds all TypeScript example files from a JSON Schema by traversing all
+ * `$ref` / `$dynamicRef` references recursively (via the shared
+ * `@amritk/helpers/walk-ref-graph` walker).
+ *
+ * Each generated file exports:
+ * - A TypeScript type definition
+ * - A `fast-check` arbitrary (`FooArbitrary`) that produces schema-valid values
+ * - A concrete example value (`fooExample`)
+ *
+ * An `index.ts` re-exports everything. The generated output imports `fast-check`,
+ * which consumers must install as a (dev) dependency.
+ *
+ * @param rootSchema - The root JSON Schema to build from
+ * @param rootTypeName - The name for the root type (e.g. "Document")
+ * @param typeSuffix - Suffix appended to every `$ref`-derived name (default `''`)
+ * @returns An array of generated TypeScript files
+ *
+ * @example
+ * ```typescript
+ * const files = await buildExampleSchema(schema, 'Document')
+ * // files → [{ filename: 'document.ts', content: '...' }, { filename: 'index.ts', ... }]
+ * ```
+ */
+export declare const buildExampleSchema: (rootSchema: JSONSchema, rootTypeName: string, typeSuffix?: string) => Promise<GeneratedFile[]>;
+//# sourceMappingURL=build-schema.d.ts.map

package/dist/generators/build-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-schema.d.ts","sourceRoot":"","sources":["../../src/generators/build-schema.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iCAAiC,CAAA;AAIjE;;GAEG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B,QAAQ,EAAE,MAAM,CAAA;IAChB,OAAO,EAAE,MAAM,CAAA;CAChB,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,eAAO,MAAM,kBAAkB,eACjB,UAAU,gBACR,MAAM,0BAEnB,OAAO,CAAC,aAAa,EAAE,CAmBzB,CAAA"}

package/dist/generators/build-schema.js

@@ -0,0 +1,44 @@
+import { generateIndexBarrel } from '@amritk/helpers/generate-index-barrel';
+import { walkRefGraph } from '@amritk/helpers/walk-ref-graph';
+import { generateExampleFile } from './generate-files.js';
+/**
+ * Builds all TypeScript example files from a JSON Schema by traversing all
+ * `$ref` / `$dynamicRef` references recursively (via the shared
+ * `@amritk/helpers/walk-ref-graph` walker).
+ *
+ * Each generated file exports:
+ * - A TypeScript type definition
+ * - A `fast-check` arbitrary (`FooArbitrary`) that produces schema-valid values
+ * - A concrete example value (`fooExample`)
+ *
+ * An `index.ts` re-exports everything. The generated output imports `fast-check`,
+ * which consumers must install as a (dev) dependency.
+ *
+ * @param rootSchema - The root JSON Schema to build from
+ * @param rootTypeName - The name for the root type (e.g. "Document")
+ * @param typeSuffix - Suffix appended to every `$ref`-derived name (default `''`)
+ * @returns An array of generated TypeScript files
+ *
+ * @example
+ * ```typescript
+ * const files = await buildExampleSchema(schema, 'Document')
+ * // files → [{ filename: 'document.ts', content: '...' }, { filename: 'index.ts', ... }]
+ * ```
+ */
+export const buildExampleSchema = async (rootSchema, rootTypeName, typeSuffix = '') => {
+    const files = [];
+    walkRefGraph(rootSchema, rootTypeName, { typeSuffix }, (node) => {
+        // `index` is reserved for the barrel below, so never let a definition of
+        // that name overwrite it.
+        if (node.filename === 'index')
+            return;
+        const content = generateExampleFile(node.schema, node.typeName, {
+            rootSchema: node.rootSchema,
+            typeSuffix,
+            ...(node.ref !== undefined ? { selfRef: node.ref } : {}),
+        });
+        files.push({ filename: `${node.filename}.ts`, content });
+    });
+    files.push({ filename: 'index.ts', content: generateIndexBarrel(files) });
+    return files;
+};

package/dist/generators/collect-example-imports.d.ts

@@ -0,0 +1,35 @@
+import type { JSONSchema } from 'json-schema-typed/draft-2020-12';
+/**
+ * Options for controlling how example imports are collected.
+ */
+type CollectExampleImportsOptions = {
+    /**
+     * The $ref path of the schema being generated (e.g. `#/$defs/address`).
+     * Prevents a file from importing itself.
+     */
+    readonly selfRef?: string | undefined;
+    /**
+     * The root schema document. URI refs that cannot be resolved within it
+     * are excluded from the import list (they were never generated as files).
+     */
+    readonly rootSchema?: Record<string, unknown> | undefined;
+    /**
+     * Suffix appended to every type/arbitrary name derived from a `$ref`. Must
+     * match the suffix used when generating the referenced files. Defaults to `''`.
+     */
+    readonly typeSuffix?: string;
+};
+/**
+ * Collects import statements for all $ref dependencies of a schema. Each import
+ * brings in both the generated TypeScript type and the arbitrary for that ref.
+ *
+ * @example
+ * ```typescript
+ * const schema = { properties: { address: { $ref: '#/$defs/address' } } }
+ * collectExampleImports(schema)
+ * // ["import { type Address, AddressArbitrary } from './address'"]
+ * ```
+ */
+export declare const collectExampleImports: (schema: JSONSchema, options?: CollectExampleImportsOptions) => string[];
+export {};
+//# sourceMappingURL=collect-example-imports.d.ts.map

package/dist/generators/collect-example-imports.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"collect-example-imports.d.ts","sourceRoot":"","sources":["../../src/generators/collect-example-imports.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iCAAiC,CAAA;AAEjE;;GAEG;AACH,KAAK,4BAA4B,GAAG;IAClC;;;OAGG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;IACrC;;;OAGG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAA;IACzD;;;OAGG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAC7B,CAAA;AA0DD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,qBAAqB,WAAY,UAAU,YAAY,4BAA4B,KAAG,MAAM,EA0BxG,CAAA"}

package/dist/generators/collect-example-imports.js

@@ -0,0 +1,88 @@
+import { refToFilename } from '@amritk/helpers/ref-to-filename';
+import { refToName } from '@amritk/helpers/ref-to-name';
+import { resolveRef } from '@amritk/helpers/resolve-ref';
+import { hasAdditionalProperties, hasAllOf, hasAnyOf, hasItems, hasOneOf, hasRef } from '@amritk/helpers/schema-guards';
+/**
+ * Generates an import statement for a single $ref, importing both the generated
+ * type and its arbitrary from the ref's generated file.
+ */
+const buildImport = (ref, suffix) => {
+    const filename = refToFilename(ref);
+    const typeName = refToName(ref, suffix);
+    return `import { type ${typeName}, ${typeName}Arbitrary } from './${filename}'`;
+};
+/**
+ * Walks one level of the schema and yields all direct $ref strings that should
+ * become imports: properties, additionalProperties, items, and union branches.
+ */
+const collectDirectRefs = (schema) => {
+    if (typeof schema === 'boolean' || schema === null)
+        return [];
+    const refs = [];
+    if (hasRef(schema)) {
+        refs.push(schema.$ref);
+        return refs;
+    }
+    const propSchemas = 'properties' in schema && typeof schema.properties === 'object' && schema.properties !== null
+        ? Object.values(schema.properties)
+        : [];
+    for (const prop of propSchemas) {
+        if (hasRef(prop))
+            refs.push(prop.$ref);
+        if (hasItems(prop) && hasRef(prop.items))
+            refs.push(prop.items.$ref);
+        if (hasAdditionalProperties(prop) && hasRef(prop.additionalProperties)) {
+            refs.push(prop.additionalProperties.$ref);
+        }
+    }
+    if (hasItems(schema) && hasRef(schema.items)) {
+        refs.push(schema.items.$ref);
+    }
+    if (hasAdditionalProperties(schema) && hasRef(schema.additionalProperties)) {
+        refs.push(schema.additionalProperties.$ref);
+    }
+    for (const branch of [
+        ...(hasOneOf(schema) ? schema.oneOf : []),
+        ...(hasAnyOf(schema) ? schema.anyOf : []),
+        ...(hasAllOf(schema) ? schema.allOf : []),
+    ]) {
+        if (hasRef(branch))
+            refs.push(branch.$ref);
+    }
+    return refs;
+};
+/**
+ * Collects import statements for all $ref dependencies of a schema. Each import
+ * brings in both the generated TypeScript type and the arbitrary for that ref.
+ *
+ * @example
+ * ```typescript
+ * const schema = { properties: { address: { $ref: '#/$defs/address' } } }
+ * collectExampleImports(schema)
+ * // ["import { type Address, AddressArbitrary } from './address'"]
+ * ```
+ */
+export const collectExampleImports = (schema, options) => {
+    const selfFilename = options?.selfRef ? refToFilename(options.selfRef) : null;
+    const rootSchema = options?.rootSchema;
+    const typeSuffix = options?.typeSuffix ?? '';
+    const refs = collectDirectRefs(schema);
+    const seen = new Set();
+    const imports = [];
+    for (const ref of refs) {
+        const filename = refToFilename(ref);
+        if (seen.has(filename))
+            continue;
+        if (selfFilename && filename === selfFilename)
+            continue;
+        // Skip refs that don't resolve in this schema (external / never generated)
+        if (rootSchema) {
+            const resolved = resolveRef(ref, rootSchema);
+            if (!resolved)
+                continue;
+        }
+        seen.add(filename);
+        imports.push(buildImport(ref, typeSuffix));
+    }
+    return imports;
+};

package/dist/generators/derive-example.d.ts

@@ -0,0 +1,30 @@
+import type { JSONSchema } from 'json-schema-typed/draft-2020-12';
+/**
+ * Derives a single concrete, schema-valid value from a JSON Schema.
+ *
+ * Prefers explicit hints in this order: `const`, `examples[0]`, `default`,
+ * `enum[0]`; otherwise produces a canonical value for the declared type.
+ * `$ref`s are resolved and inlined by value; recursive refs short-circuit to
+ * `null` (tracked via `seen`).
+ *
+ * Note: values constrained only by `pattern` are not guaranteed to match the
+ * pattern — use the generated arbitrary when pattern fidelity matters.
+ */
+export declare const deriveExample: (schema: JSONSchema, rootSchema?: Record<string, unknown>, seen?: ReadonlySet<string>) => unknown;
+/**
+ * Serializes a derived value into a TypeScript source expression. Handles the
+ * non-JSON values `deriveExample` can produce (`Date`, `bigint`) in addition to
+ * plain JSON.
+ */
+export declare const serializeValue: (value: unknown) => string;
+/**
+ * Generates an exported const holding a concrete, schema-valid example value.
+ *
+ * @example
+ * ```typescript
+ * generateExampleConst({ type: 'object', properties: { name: { type: 'string' } } }, 'Info')
+ * // export const infoExample: Info = { "name": "string" }
+ * ```
+ */
+export declare const generateExampleConst: (schema: JSONSchema, typeName: string, rootSchema?: Record<string, unknown>) => string;
+//# sourceMappingURL=derive-example.d.ts.map

package/dist/generators/derive-example.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"derive-example.d.ts","sourceRoot":"","sources":["../../src/generators/derive-example.ts"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iCAAiC,CAAA;AAgCjE;;;;;;;;;;GAUG;AACH,eAAO,MAAM,aAAa,WAChB,UAAU,eACL,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,SAC9B,WAAW,CAAC,MAAM,CAAC,KACxB,OAuDF,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,cAAc,UAAW,OAAO,KAAG,MAW/C,CAAA;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,oBAAoB,WACvB,UAAU,YACR,MAAM,eACH,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KACnC,MAGF,CAAA"}

package/dist/generators/derive-example.js

@@ -0,0 +1,137 @@
+import { getMjstInstanceOf, getMjstPrimitive } from '@amritk/helpers/mjst-extension';
+import { resolveRef } from '@amritk/helpers/resolve-ref';
+import { hasAnyOf, hasConst, hasDefault, hasEnum, hasExamples, hasFormat, hasItems, hasMaxLength, hasMinItems, hasMinimum, hasMinLength, hasOneOf, hasProperties, hasRef, hasType, isSchemaObject, } from '@amritk/helpers/schema-guards';
+/** Lowercases the first character of a name. e.g. "User" → "user" */
+const lowerFirst = (name) => name.charAt(0).toLowerCase() + name.slice(1);
+/** Derives the example const name from a type name. e.g. "User" → "userExample" */
+const exampleName = (typeName) => `${lowerFirst(typeName)}Example`;
+/** Returns a representative string honouring `format` and length constraints. */
+const exampleString = (schema) => {
+    if (hasFormat(schema)) {
+        switch (schema.format) {
+            case 'email':
+                return 'user@example.com';
+            case 'uuid':
+                return '00000000-0000-0000-0000-000000000000';
+            case 'uri':
+            case 'url':
+                return 'https://example.com';
+            case 'date-time':
+                return '1970-01-01T00:00:00.000Z';
+            case 'date':
+                return '1970-01-01';
+        }
+    }
+    let value = 'string';
+    if (hasMinLength(schema) && value.length < schema.minLength)
+        value = value.padEnd(schema.minLength, 'x');
+    if (hasMaxLength(schema) && value.length > schema.maxLength)
+        value = value.slice(0, schema.maxLength);
+    return value;
+};
+/**
+ * Derives a single concrete, schema-valid value from a JSON Schema.
+ *
+ * Prefers explicit hints in this order: `const`, `examples[0]`, `default`,
+ * `enum[0]`; otherwise produces a canonical value for the declared type.
+ * `$ref`s are resolved and inlined by value; recursive refs short-circuit to
+ * `null` (tracked via `seen`).
+ *
+ * Note: values constrained only by `pattern` are not guaranteed to match the
+ * pattern — use the generated arbitrary when pattern fidelity matters.
+ */
+export const deriveExample = (schema, rootSchema, seen = new Set()) => {
+    if (!isSchemaObject(schema))
+        return null;
+    if (hasConst(schema))
+        return schema.const;
+    if (hasExamples(schema) && Array.isArray(schema.examples) && schema.examples.length > 0)
+        return schema.examples[0];
+    if (hasDefault(schema))
+        return schema.default;
+    if (hasEnum(schema) && schema.enum.length > 0)
+        return schema.enum[0];
+    if (hasRef(schema)) {
+        const ref = schema.$ref;
+        if (seen.has(ref) || !rootSchema)
+            return null;
+        const resolved = resolveRef(ref, rootSchema);
+        if (!resolved)
+            return null;
+        return deriveExample(resolved, rootSchema, new Set([...seen, ref]));
+    }
+    const instanceOf = getMjstInstanceOf(schema);
+    if (instanceOf === 'Date')
+        return new Date(0);
+    const primitive = getMjstPrimitive(schema);
+    if (primitive === 'bigint')
+        return 0n;
+    if (hasOneOf(schema) && schema.oneOf[0] !== undefined)
+        return deriveExample(schema.oneOf[0], rootSchema, seen);
+    if (hasAnyOf(schema) && schema.anyOf[0] !== undefined)
+        return deriveExample(schema.anyOf[0], rootSchema, seen);
+    // `hasType` only matches a single string `type`; multi-type schemas fall
+    // through to `null`.
+    if (!hasType(schema))
+        return null;
+    switch (schema.type) {
+        case 'string':
+            return exampleString(schema);
+        case 'number':
+        case 'integer':
+            return hasMinimum(schema) ? schema.minimum : 0;
+        case 'boolean':
+            return true;
+        case 'null':
+            return null;
+        case 'array': {
+            const item = hasItems(schema) ? deriveExample(schema.items, rootSchema, seen) : null;
+            const count = hasMinItems(schema) ? Math.max(schema.minItems, 1) : 1;
+            return Array.from({ length: count }, () => item);
+        }
+        case 'object': {
+            const out = {};
+            if (hasProperties(schema)) {
+                for (const [key, propSchema] of Object.entries(schema.properties)) {
+                    out[key] = deriveExample(propSchema, rootSchema, seen);
+                }
+            }
+            return out;
+        }
+        default:
+            return null;
+    }
+};
+/**
+ * Serializes a derived value into a TypeScript source expression. Handles the
+ * non-JSON values `deriveExample` can produce (`Date`, `bigint`) in addition to
+ * plain JSON.
+ */
+export const serializeValue = (value) => {
+    if (typeof value === 'bigint')
+        return `${value}n`;
+    if (value instanceof Date)
+        return `new Date(${JSON.stringify(value.toISOString())})`;
+    if (Array.isArray(value))
+        return `[${value.map(serializeValue).join(', ')}]`;
+    if (value !== null && typeof value === 'object') {
+        const entries = Object.entries(value)
+            .filter(([, v]) => v !== undefined)
+            .map(([key, v]) => `${JSON.stringify(key)}: ${serializeValue(v)}`);
+        return `{ ${entries.join(', ')} }`;
+    }
+    return JSON.stringify(value);
+};
+/**
+ * Generates an exported const holding a concrete, schema-valid example value.
+ *
+ * @example
+ * ```typescript
+ * generateExampleConst({ type: 'object', properties: { name: { type: 'string' } } }, 'Info')
+ * // export const infoExample: Info = { "name": "string" }
+ * ```
+ */
+export const generateExampleConst = (schema, typeName, rootSchema) => {
+    const value = deriveExample(schema, rootSchema);
+    return `export const ${exampleName(typeName)}: ${typeName} = ${serializeValue(value)}`;
+};

package/dist/generators/generate-arbitrary.d.ts

@@ -0,0 +1,12 @@
+import type { JSONSchema } from 'json-schema-typed/draft-2020-12';
+/**
+ * Generates a `fast-check` arbitrary that produces schema-valid values.
+ *
+ * @example
+ * ```typescript
+ * generateArbitrary({ type: 'object', properties: { name: { type: 'string' } }, required: ['name'] }, 'Info')
+ * // export const InfoArbitrary: fc.Arbitrary<Info> = fc.record({ "name": fc.string() })
+ * ```
+ */
+export declare const generateArbitrary: (schema: JSONSchema, typeName: string, suffix?: string) => string;
+//# sourceMappingURL=generate-arbitrary.d.ts.map

package/dist/generators/generate-arbitrary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generate-arbitrary.d.ts","sourceRoot":"","sources":["../../src/generators/generate-arbitrary.ts"],"names":[],"mappings":"AA0BA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iCAAiC,CAAA;AA2JjE;;;;;;;;GAQG;AACH,eAAO,MAAM,iBAAiB,WAAY,UAAU,YAAY,MAAM,sBAAgB,MAGrF,CAAA"}

package/dist/generators/generate-arbitrary.js

@@ -0,0 +1,165 @@
+import { getMjstInstanceOf, getMjstPrimitive } from '@amritk/helpers/mjst-extension';
+import { refToName } from '@amritk/helpers/ref-to-name';
+import { hasAnyOf, hasConst, hasEnum, hasExclusiveMaximum, hasExclusiveMinimum, hasFormat, hasItems, hasMaxItems, hasMaximum, hasMaxLength, hasMinItems, hasMinimum, hasMinLength, hasMultipleOf, hasOneOf, hasPattern, hasProperties, hasRef, hasRequired, hasType, hasUniqueItems, isSchemaObject, } from '@amritk/helpers/schema-guards';
+/**
+ * Derives the arbitrary const name from a type name.
+ * e.g. "User" → "UserArbitrary"
+ */
+const arbitraryName = (typeName) => `${typeName}Arbitrary`;
+/** Builds a `fc.string({ ... })` expression honouring format and length constraints. */
+const stringExpr = (schema) => {
+    if (hasFormat(schema)) {
+        switch (schema.format) {
+            case 'email':
+                return 'fc.emailAddress()';
+            case 'uuid':
+                return 'fc.uuid()';
+            case 'uri':
+            case 'url':
+                return 'fc.webUrl()';
+            case 'date-time':
+                return 'fc.date({ noInvalidDate: true }).map((d) => d.toISOString())';
+            case 'date':
+                return 'fc.date({ noInvalidDate: true }).map((d) => d.toISOString().slice(0, 10))';
+        }
+    }
+    if (hasPattern(schema))
+        return `fc.stringMatching(/${schema.pattern}/)`;
+    const opts = [];
+    if (hasMinLength(schema))
+        opts.push(`minLength: ${schema.minLength}`);
+    if (hasMaxLength(schema))
+        opts.push(`maxLength: ${schema.maxLength}`);
+    return opts.length > 0 ? `fc.string({ ${opts.join(', ')} })` : 'fc.string()';
+};
+/** Builds a `fc.integer({ ... })` expression honouring range and multiple-of constraints. */
+const integerExpr = (schema) => {
+    const opts = [];
+    if (hasMinimum(schema))
+        opts.push(`min: ${schema.minimum}`);
+    else if (hasExclusiveMinimum(schema))
+        opts.push(`min: ${Number(schema.exclusiveMinimum) + 1}`);
+    if (hasMaximum(schema))
+        opts.push(`max: ${schema.maximum}`);
+    else if (hasExclusiveMaximum(schema))
+        opts.push(`max: ${Number(schema.exclusiveMaximum) - 1}`);
+    const base = opts.length > 0 ? `fc.integer({ ${opts.join(', ')} })` : 'fc.integer()';
+    return hasMultipleOf(schema) ? `${base}.filter((n) => n % ${schema.multipleOf} === 0)` : base;
+};
+/** Builds a `fc.double({ ... })` expression honouring range and multiple-of constraints. */
+const numberExpr = (schema) => {
+    const opts = ['noNaN: true', 'noDefaultInfinity: true'];
+    if (hasMinimum(schema))
+        opts.push(`min: ${schema.minimum}`);
+    else if (hasExclusiveMinimum(schema))
+        opts.push(`min: ${schema.exclusiveMinimum}`, 'minExcluded: true');
+    if (hasMaximum(schema))
+        opts.push(`max: ${schema.maximum}`);
+    else if (hasExclusiveMaximum(schema))
+        opts.push(`max: ${schema.exclusiveMaximum}`, 'maxExcluded: true');
+    const base = `fc.double({ ${opts.join(', ')} })`;
+    return hasMultipleOf(schema) ? `${base}.filter((n) => n % ${schema.multipleOf} === 0)` : base;
+};
+/** Builds a `fc.array(...)` / `fc.uniqueArray(...)` expression for an array schema. */
+const arrayExpr = (schema, suffix) => {
+    const items = hasItems(schema) && isSchemaObject(schema.items) ? arbitraryExpr(schema.items, suffix) : 'fc.anything()';
+    const opts = [];
+    if (hasMinItems(schema))
+        opts.push(`minLength: ${schema.minItems}`);
+    if (hasMaxItems(schema))
+        opts.push(`maxLength: ${schema.maxItems}`);
+    const fn = hasUniqueItems(schema) && schema.uniqueItems === true ? 'fc.uniqueArray' : 'fc.array';
+    return opts.length > 0 ? `${fn}(${items}, { ${opts.join(', ')} })` : `${fn}(${items})`;
+};
+/** Builds a `fc.record(...)` expression for an object schema. */
+const objectExpr = (schema, suffix) => {
+    if (!hasProperties(schema))
+        return 'fc.object()';
+    const required = new Set(hasRequired(schema) ? schema.required : []);
+    const keys = Object.keys(schema.properties);
+    const entries = Object.entries(schema.properties).map(([key, propSchema]) => `${JSON.stringify(key)}: ${arbitraryExpr(propSchema, suffix)}`);
+    if (entries.length === 0)
+        return 'fc.record({})';
+    const model = `{ ${entries.join(', ')} }`;
+    // fc.record treats all keys as required by default. Only emit requiredKeys
+    // when at least one property is optional.
+    if (keys.every((key) => required.has(key)))
+        return `fc.record(${model})`;
+    const requiredKeys = [...required].map((key) => JSON.stringify(key)).join(', ');
+    return `fc.record(${model}, { requiredKeys: [${requiredKeys}] })`;
+};
+/** Builds a `fc.oneof(...)` expression from a list of branch schemas. */
+const oneofExpr = (branches, suffix) => {
+    const exprs = branches.map((branch) => arbitraryExpr(branch, suffix));
+    return `fc.oneof(${exprs.join(', ')})`;
+};
+/** Builds the fast-check expression for a single (non-union) JSON Schema type. */
+const scalarExpr = (type, schema, suffix) => {
+    switch (type) {
+        case 'string':
+            return stringExpr(schema);
+        case 'integer':
+            return integerExpr(schema);
+        case 'number':
+            return numberExpr(schema);
+        case 'boolean':
+            return 'fc.boolean()';
+        case 'null':
+            return 'fc.constant(null)';
+        case 'array':
+            return arrayExpr(schema, suffix);
+        case 'object':
+            return objectExpr(schema, suffix);
+        default:
+            return 'fc.anything()';
+    }
+};
+/**
+ * Recursively builds the fast-check arbitrary expression for a schema node.
+ * `$ref`s resolve to the referenced file's exported arbitrary; everything else
+ * maps to the appropriate `fc.*` combinator.
+ */
+const arbitraryExpr = (schema, suffix) => {
+    if (!isSchemaObject(schema))
+        return 'fc.anything()';
+    if (hasRef(schema))
+        return arbitraryName(refToName(schema.$ref, suffix));
+    if (hasConst(schema))
+        return `fc.constant(${JSON.stringify(schema.const)})`;
+    if (hasEnum(schema)) {
+        const values = schema.enum.map((value) => JSON.stringify(value)).join(', ');
+        return `fc.constantFrom(${values})`;
+    }
+    const instanceOf = getMjstInstanceOf(schema);
+    if (instanceOf === 'Date')
+        return 'fc.date({ noInvalidDate: true })';
+    if (instanceOf)
+        return 'fc.anything()';
+    const primitive = getMjstPrimitive(schema);
+    if (primitive === 'bigint')
+        return 'fc.bigInt()';
+    if (primitive)
+        return 'fc.anything()';
+    if (hasOneOf(schema))
+        return oneofExpr(schema.oneOf, suffix);
+    if (hasAnyOf(schema))
+        return oneofExpr(schema.anyOf, suffix);
+    // `hasType` only matches a single string `type`; multi-type schemas
+    // (`type: ['string', 'null']`) fall through to the permissive fallback.
+    if (hasType(schema))
+        return scalarExpr(schema.type, schema, suffix);
+    return 'fc.anything()';
+};
+/**
+ * Generates a `fast-check` arbitrary that produces schema-valid values.
+ *
+ * @example
+ * ```typescript
+ * generateArbitrary({ type: 'object', properties: { name: { type: 'string' } }, required: ['name'] }, 'Info')
+ * // export const InfoArbitrary: fc.Arbitrary<Info> = fc.record({ "name": fc.string() })
+ * ```
+ */
+export const generateArbitrary = (schema, typeName, suffix = '') => {
+    const expr = arbitraryExpr(schema, suffix);
+    return `export const ${arbitraryName(typeName)}: fc.Arbitrary<${typeName}> = ${expr}`;
+};

package/dist/generators/generate-files.d.ts

@@ -0,0 +1,43 @@
+import type { JSONSchema } from 'json-schema-typed/draft-2020-12';
+/**
+ * Options for controlling what gets generated in an example file.
+ */
+type GenerateExampleFileOptions = {
+    /**
+     * The $ref path of the schema being generated (e.g. `#/$defs/address`).
+     * Prevents the file from importing itself.
+     */
+    readonly selfRef?: string;
+    /**
+     * The root schema document. Used to resolve `$ref`s when deriving a concrete
+     * example value, and to filter out unresolvable refs from the import list.
+     */
+    readonly rootSchema?: Record<string, unknown>;
+    /**
+     * Suffix appended to every type/arbitrary name derived from a `$ref`.
+     * Defaults to `''` (no suffix).
+     */
+    readonly typeSuffix?: string;
+};
+/**
+ * Generates a complete TypeScript example file from a JSON Schema.
+ *
+ * The file contains:
+ * - An import of `fast-check` and imports for any `$ref` types and arbitraries
+ * - The exported TypeScript type definition
+ * - An exported `fast-check` arbitrary (`FooArbitrary`)
+ * - An exported concrete example value (`fooExample`)
+ *
+ * @example
+ * ```typescript
+ * const schema = { type: 'object', properties: { title: { type: 'string' } }, required: ['title'] }
+ * generateExampleFile(schema, 'Info')
+ * // import * as fc from 'fast-check'
+ * // export type Info = { title: string }
+ * // export const InfoArbitrary: fc.Arbitrary<Info> = fc.record({ "title": fc.string() })
+ * // export const infoExample: Info = { "title": "string" }
+ * ```
+ */
+export declare const generateExampleFile: (schema: JSONSchema, typeName: string, options?: GenerateExampleFileOptions) => string;
+export {};
+//# sourceMappingURL=generate-files.d.ts.map

package/dist/generators/generate-files.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generate-files.d.ts","sourceRoot":"","sources":["../../src/generators/generate-files.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iCAAiC,CAAA;AAMjE;;GAEG;AACH,KAAK,0BAA0B,GAAG;IAChC;;;OAGG;IACH,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;IACzB;;;OAGG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC7C;;;OAGG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAC7B,CAAA;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,eAAO,MAAM,mBAAmB,WACtB,UAAU,YACR,MAAM,YACN,0BAA0B,KACnC,MAsBF,CAAA"}

package/dist/generators/generate-files.js

@@ -0,0 +1,41 @@
+import { generateTypeDefinition } from '@amritk/helpers/generate-type-definition';
+import { collectExampleImports } from './collect-example-imports.js';
+import { generateExampleConst } from './derive-example.js';
+import { generateArbitrary } from './generate-arbitrary.js';
+/**
+ * Generates a complete TypeScript example file from a JSON Schema.
+ *
+ * The file contains:
+ * - An import of `fast-check` and imports for any `$ref` types and arbitraries
+ * - The exported TypeScript type definition
+ * - An exported `fast-check` arbitrary (`FooArbitrary`)
+ * - An exported concrete example value (`fooExample`)
+ *
+ * @example
+ * ```typescript
+ * const schema = { type: 'object', properties: { title: { type: 'string' } }, required: ['title'] }
+ * generateExampleFile(schema, 'Info')
+ * // import * as fc from 'fast-check'
+ * // export type Info = { title: string }
+ * // export const InfoArbitrary: fc.Arbitrary<Info> = fc.record({ "title": fc.string() })
+ * // export const infoExample: Info = { "title": "string" }
+ * ```
+ */
+export const generateExampleFile = (schema, typeName, options) => {
+    const typeSuffix = options?.typeSuffix ?? '';
+    const refImports = collectExampleImports(schema, {
+        selfRef: options?.selfRef,
+        rootSchema: options?.rootSchema,
+        typeSuffix,
+    });
+    const typeDefinition = generateTypeDefinition(schema, typeName, { typeSuffix });
+    const arbitrary = generateArbitrary(schema, typeName, typeSuffix);
+    const example = generateExampleConst(schema, typeName, options?.rootSchema);
+    let result = `import * as fc from 'fast-check'\n`;
+    for (const imp of refImports) {
+        result += imp + '\n';
+    }
+    result += '\n';
+    result += typeDefinition + '\n\n' + arbitrary + '\n\n' + example + '\n';
+    return result;
+};

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export type { GeneratedFile } from './generators/build-schema.js';
+export { buildExampleSchema } from './generators/build-schema.js';
+export { deriveExample, generateExampleConst, serializeValue } from './generators/derive-example.js';
+export { generateArbitrary } from './generators/generate-arbitrary.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,aAAa,EAAE,MAAM,2BAA2B,CAAA;AAC9D,OAAO,EAAE,kBAAkB,EAAE,MAAM,2BAA2B,CAAA;AAC9D,OAAO,EAAE,aAAa,EAAE,oBAAoB,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAA;AACjG,OAAO,EAAE,iBAAiB,EAAE,MAAM,iCAAiC,CAAA"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export { buildExampleSchema } from './generators/build-schema.js';
+export { deriveExample, generateExampleConst, serializeValue } from './generators/derive-example.js';
+export { generateArbitrary } from './generators/generate-arbitrary.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amritk/generate-examples",
-  "version": "0.0.0",
+  "version": "0.2.0",
   "description": "Generate fast-check arbitraries and example values from JSON Schemas.",
   "module": "./dist/index.js",
   "type": "module",
@@ -33,23 +33,23 @@
     "access": "public"
   },
   "scripts": {
-    "build": "bun run build:code && bun run build:types",
-    "build:code": "bun build ./src/index.ts --outdir=dist --target=node",
-    "build:types": "tsc -p ."
+    "build": "tsgo -p tsconfig.build.json && tsc-alias -p tsconfig.build.json -f",
+    "types:check": "tsgo -p . --noEmit",
+    "test": "NODE_ENV=production vitest run --root ../.. generate-examples"
   },
   "imports": {
     "#generators/*": "./src/generators/*.ts"
   },
   "exports": {
     ".": {
-      "bun": "./src/index.ts",
+      "development": "./src/index.ts",
       "default": "./dist/index.js",
       "types": "./dist/index.d.ts"
     }
   },
   "dependencies": {
-    "json-schema-typed": "catalog:",
-    "@amritk/helpers": "workspace:*"
+    "json-schema-typed": "^8.0.1",
+    "@amritk/helpers": "0.7.0"
   },
   "peerDependencies": {
     "fast-check": ">=3"

package/src/generators/build-schema.ts

@@ -1,10 +1,5 @@
-import { buildDynamicRefMap } from '@amritk/helpers/build-dynamic-ref-map'
-import { extractRefs } from '@amritk/helpers/extract-refs'
-import { refToFilename } from '@amritk/helpers/ref-to-filename'
-import { refToName } from '@amritk/helpers/ref-to-name'
-import { resolveDynamicRefs } from '@amritk/helpers/resolve-dynamic-refs'
-import { resolveRef } from '@amritk/helpers/resolve-ref'
-import { upgradeDraft07Schema } from '@amritk/helpers/upgrade-draft07-schema'
+import { generateIndexBarrel } from '@amritk/helpers/generate-index-barrel'
+import { walkRefGraph } from '@amritk/helpers/walk-ref-graph'
 import type { JSONSchema } from 'json-schema-typed/draft-2020-12'
 
 import { generateExampleFile } from './generate-files'
@@ -19,7 +14,8 @@ export type GeneratedFile = {
 
 /**
  * Builds all TypeScript example files from a JSON Schema by traversing all
- * $ref references recursively, mirroring the generate-parsers pipeline.
+ * `$ref` / `$dynamicRef` references recursively (via the shared
+ * `@amritk/helpers/walk-ref-graph` walker).
  *
  * Each generated file exports:
  * - A TypeScript type definition
@@ -45,83 +41,22 @@ export const buildExampleSchema = async (
   rootTypeName: string,
   typeSuffix = '',
 ): Promise<GeneratedFile[]> => {
-  rootSchema = upgradeDraft07Schema(rootSchema as Record<string, unknown>) as JSONSchema
-
   const files: GeneratedFile[] = []
-  const processedRefs = new Set<string>()
-  const processedFilenames = new Set<string>()
-  const refsToProcess: string[] = []
-
-  const dynamicRefMap = buildDynamicRefMap(rootSchema)
-
-  // Root schema
-  const processedRootSchema = resolveDynamicRefs(rootSchema, dynamicRefMap)
-  const rootContent = generateExampleFile(processedRootSchema, rootTypeName, {
-    rootSchema: rootSchema as Record<string, unknown>,
-    typeSuffix,
-  })
-  const rootFilename = rootTypeName.toLowerCase()
 
-  if (rootFilename !== 'index') {
-    processedFilenames.add(rootFilename)
-    files.push({ filename: `${rootFilename}.ts`, content: rootContent })
-  }
+  walkRefGraph(rootSchema, rootTypeName, { typeSuffix }, (node) => {
+    // `index` is reserved for the barrel below, so never let a definition of
+    // that name overwrite it.
+    if (node.filename === 'index') return
 
-  const rootRefs = extractRefs(rootSchema)
-  refsToProcess.push(...rootRefs)
-
-  while (refsToProcess.length > 0) {
-    const ref = refsToProcess.shift()
-    if (!ref || processedRefs.has(ref)) continue
-    processedRefs.add(ref)
-
-    const resolvedSchema = resolveRef(ref, rootSchema as Record<string, unknown>)
-    if (!resolvedSchema) {
-      console.warn(`Warning: Could not resolve ref: ${ref}`)
-      continue
-    }
-
-    const typeName = refToName(ref, typeSuffix)
-    const filename = refToFilename(ref)
-    const processedSchema = resolveDynamicRefs(resolvedSchema as JSONSchema, dynamicRefMap)
-    const content = generateExampleFile(processedSchema, typeName, {
-      selfRef: ref,
-      rootSchema: rootSchema as Record<string, unknown>,
+    const content = generateExampleFile(node.schema, node.typeName, {
+      rootSchema: node.rootSchema,
       typeSuffix,
+      ...(node.ref !== undefined ? { selfRef: node.ref } : {}),
     })
+    files.push({ filename: `${node.filename}.ts`, content })
+  })
 
-    if (filename !== 'index' && !processedFilenames.has(filename)) {
-      processedFilenames.add(filename)
-      files.push({ filename: `${filename}.ts`, content })
-    }
-
-    for (const nestedRef of extractRefs(resolvedSchema as JSONSchema)) {
-      if (!processedRefs.has(nestedRef)) refsToProcess.push(nestedRef)
-    }
-  }
-
-  // Generate index.ts barrel
-  const TYPE_EXPORT_RE = /^export type (\w+)/gm
-  const CONST_EXPORT_RE = /^export const (\w+)/gm
-
-  const sortedFiles = [...files].sort((a, b) => a.filename.localeCompare(b.filename))
-  let indexContent = ''
-
-  for (const file of sortedFiles) {
-    const moduleName = file.filename.replace(/\.ts$/, '')
-    const typeNames: string[] = []
-    const constNames: string[] = []
-
-    for (const match of file.content.matchAll(TYPE_EXPORT_RE)) typeNames.push(match[1] as string)
-    for (const match of file.content.matchAll(CONST_EXPORT_RE)) constNames.push(match[1] as string)
-
-    if (typeNames.length === 0 && constNames.length === 0) continue
-
-    const typeExports = typeNames.map((n) => `type ${n}`)
-    indexContent += `export { ${[...typeExports, ...constNames].join(', ')} } from './${moduleName}';\n`
-  }
-
-  files.push({ filename: 'index.ts', content: indexContent })
+  files.push({ filename: 'index.ts', content: generateIndexBarrel(files) })
 
   return files
 }