@amritk/generate-examples 0.4.1 → 0.4.2

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

@@ -9,7 +9,8 @@ import { hasAdditionalProperties, hasAllOf, hasAnyOf, hasItems, hasOneOf, hasRef
 const buildImport = (ref, suffix) => {
     const filename = refToFilename(ref);
     const typeName = refToName(ref, suffix);
-    return `import { type ${typeName}, ${typeName}Arbitrary } from './${filename}'`;
+    // `.js` extension so the emitted import resolves under Node ESM, not only Bun.
+    return `import { type ${typeName}, ${typeName}Arbitrary } from './${filename}.js'`;
 };
 /**
  * Walks one level of the schema and yields all direct $ref strings that should

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

@@ -11,6 +11,7 @@ import type { JSONSchema } from 'json-schema-typed/draft-2020-12';
  * pattern — use the generated arbitrary when pattern fidelity matters.
  */
 export declare const deriveExample: (schema: JSONSchema, rootSchema?: Record<string, unknown>, seen?: ReadonlySet<string>) => unknown;
+export declare const mergeAllOf: (schema: JSONSchema) => JSONSchema;
 /**
  * Serializes a derived value into a TypeScript source expression. Handles the
  * non-JSON values `deriveExample` can produce (`Date`, `bigint`) in addition to

package/dist/generators/derive-example.js

@@ -472,7 +472,7 @@ const TIGHTEST = new Map([
     ['maxItems', 'min'],
     ['maxProperties', 'min'],
 ]);
-const mergeAllOf = (schema) => {
+export const mergeAllOf = (schema) => {
     const branches = hasAllOf(schema) ? schema.allOf : [];
     const merged = {};
     const properties = {};

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

@@ -2,6 +2,10 @@ import type { JSONSchema } from 'json-schema-typed/draft-2020-12';
 /**
  * Generates a `fast-check` arbitrary that produces schema-valid values.
  *
+ * A schema that references itself is wrapped in `fc.letrec` so the recursion is
+ * tied lazily — a plain `const NodeArbitrary = fc.record({ next: NodeArbitrary })`
+ * would throw a TDZ `ReferenceError` the moment the module is imported.
+ *
  * @example
  * ```typescript
  * generateArbitrary({ type: 'object', properties: { name: { type: 'string' } }, required: ['name'] }, 'Info')

package/dist/generators/generate-arbitrary.js

@@ -1,11 +1,14 @@
 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';
+import { hasAdditionalProperties, hasAllOf, 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';
+import { mergeAllOf } from './derive-example.js';
 /**
  * Derives the arbitrary const name from a type name.
  * e.g. "User" → "UserArbitrary"
  */
 const arbitraryName = (typeName) => `${typeName}Arbitrary`;
+/** The letrec key used for a type's own (self-referential) arbitrary. */
+const SELF_KEY = 'self';
 /** Builds a `fc.string({ ... })` expression honouring format and length constraints. */
 const stringExpr = (schema) => {
     if (hasFormat(schema)) {
@@ -31,8 +34,20 @@ const stringExpr = (schema) => {
                 return 'fc.ipV6()';
         }
     }
-    if (hasPattern(schema))
-        return `fc.stringMatching(/${schema.pattern}/)`;
+    if (hasPattern(schema)) {
+        // Build the regex via `new RegExp(<json-string>)` rather than inlining the
+        // pattern into a `/.../ ` literal: a pattern containing `/` (e.g. `^/api/v\d+$`)
+        // would otherwise close the literal early and emit invalid TypeScript.
+        const base = `fc.stringMatching(new RegExp(${JSON.stringify(schema.pattern)}))`;
+        // `stringMatching` takes no length bounds, so honour any min/maxLength with a
+        // filter instead of silently dropping them. Only emit it when a bound exists.
+        const checks = [];
+        if (hasMinLength(schema))
+            checks.push(`s.length >= ${schema.minLength}`);
+        if (hasMaxLength(schema))
+            checks.push(`s.length <= ${schema.maxLength}`);
+        return checks.length > 0 ? `${base}.filter((s) => ${checks.join(' && ')})` : base;
+    }
     const opts = [];
     if (hasMinLength(schema))
         opts.push(`minLength: ${schema.minLength}`);
@@ -43,14 +58,23 @@ const stringExpr = (schema) => {
 /** Builds a `fc.integer({ ... })` expression honouring range and multiple-of constraints. */
 const integerExpr = (schema) => {
     const opts = [];
+    // With both `minimum` and `exclusiveMinimum` present the effective lower bound
+    // is the tighter (larger) of the two, so combine them rather than letting one
+    // shadow the other via else-if.
+    const mins = [];
     if (hasMinimum(schema))
-        opts.push(`min: ${schema.minimum}`);
-    else if (hasExclusiveMinimum(schema))
-        opts.push(`min: ${Number(schema.exclusiveMinimum) + 1}`);
+        mins.push(Number(schema.minimum));
+    if (hasExclusiveMinimum(schema))
+        mins.push(Number(schema.exclusiveMinimum) + 1);
+    if (mins.length > 0)
+        opts.push(`min: ${Math.max(...mins)}`);
+    const maxs = [];
     if (hasMaximum(schema))
-        opts.push(`max: ${schema.maximum}`);
-    else if (hasExclusiveMaximum(schema))
-        opts.push(`max: ${Number(schema.exclusiveMaximum) - 1}`);
+        maxs.push(Number(schema.maximum));
+    if (hasExclusiveMaximum(schema))
+        maxs.push(Number(schema.exclusiveMaximum) - 1);
+    if (maxs.length > 0)
+        opts.push(`max: ${Math.min(...maxs)}`);
     const base = opts.length > 0 ? `fc.integer({ ${opts.join(', ')} })` : 'fc.integer()';
     return hasMultipleOf(schema) ? `${base}.filter((n) => n % ${schema.multipleOf} === 0)` : base;
 };
@@ -68,9 +92,24 @@ const numberExpr = (schema) => {
     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()';
+/** Builds a `fc.array(...)` / `fc.uniqueArray(...)` / `fc.tuple(...)` expression for an array schema. */
+const arrayExpr = (schema, ctx) => {
+    const raw = schema;
+    // A tuple is `prefixItems` (2020-12) or the draft-07 array-form `items`. Both
+    // describe one schema per position, so map them to `fc.tuple(...)`. Extra items
+    // beyond the prefix are unconstrained (or forbidden by `items: false`); the
+    // minimal tuple is schema-valid either way.
+    const prefixItems = raw['prefixItems'];
+    const tuple = Array.isArray(prefixItems)
+        ? prefixItems
+        : Array.isArray(raw['items'])
+            ? raw['items']
+            : undefined;
+    if (tuple) {
+        const exprs = tuple.map((item) => arbitraryExpr(item, ctx));
+        return `fc.tuple(${exprs.join(', ')})`;
+    }
+    const items = hasItems(schema) && isSchemaObject(schema.items) ? arbitraryExpr(schema.items, ctx) : 'fc.anything()';
     const opts = [];
     if (hasMinItems(schema))
         opts.push(`minLength: ${schema.minItems}`);
@@ -79,30 +118,43 @@ const arrayExpr = (schema, suffix) => {
     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()';
+/** Builds a `fc.record(...)` / `fc.dictionary(...)` expression for an object schema. */
+const objectExpr = (schema, ctx) => {
+    // The `additionalProperties` value schema (when it constrains extra keys with a
+    // real subschema rather than the boolean true/false form).
+    const additional = hasAdditionalProperties(schema) ? schema.additionalProperties : false;
+    const additionalArb = isSchemaObject(additional) ? arbitraryExpr(additional, ctx) : undefined;
+    if (!hasProperties(schema)) {
+        // A map-style object (no declared properties) with a typed `additionalProperties`
+        // is a dictionary of that value type; otherwise fall back to a free-form object.
+        return additionalArb ? `fc.dictionary(fc.string(), ${additionalArb})` : '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)}`);
+    const entries = Object.entries(schema.properties).map(([key, propSchema]) => `${JSON.stringify(key)}: ${arbitraryExpr(propSchema, ctx)}`);
     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}] })`;
+    const record = keys.every((key) => required.has(key))
+        ? `fc.record(${model})`
+        : `fc.record(${model}, { requiredKeys: [${[...required].map((key) => JSON.stringify(key)).join(', ')}] })`;
+    // When both declared properties and a typed `additionalProperties` are present,
+    // fold in a dictionary of extra keys so the value exercises the open-map part of
+    // the schema too. The declared keys win on collision (merged last).
+    if (additionalArb) {
+        return `fc.tuple(${record}, fc.dictionary(fc.string(), ${additionalArb})).map(([base, extra]) => ({ ...extra, ...base }))`;
+    }
+    return record;
 };
 /** Builds a `fc.oneof(...)` expression from a list of branch schemas. */
-const oneofExpr = (branches, suffix) => {
-    const exprs = branches.map((branch) => arbitraryExpr(branch, suffix));
+const oneofExpr = (branches, ctx) => {
+    const exprs = branches.map((branch) => arbitraryExpr(branch, ctx));
     return `fc.oneof(${exprs.join(', ')})`;
 };
 /** Builds the fast-check expression for a single (non-union) JSON Schema type. */
-const scalarExpr = (type, schema, suffix) => {
+const scalarExpr = (type, schema, ctx) => {
     switch (type) {
         case 'string':
             return stringExpr(schema);
@@ -115,23 +167,32 @@ const scalarExpr = (type, schema, suffix) => {
         case 'null':
             return 'fc.constant(null)';
         case 'array':
-            return arrayExpr(schema, suffix);
+            return arrayExpr(schema, ctx);
         case 'object':
-            return objectExpr(schema, suffix);
+            return objectExpr(schema, ctx);
         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.
+ * `$ref`s resolve to the referenced file's exported arbitrary; a self-`$ref`
+ * resolves to `tie('self')` so recursive schemas tie lazily via `fc.letrec`.
+ * Everything else maps to the appropriate `fc.*` combinator.
  */
-const arbitraryExpr = (schema, suffix) => {
+const arbitraryExpr = (schema, ctx) => {
     if (!isSchemaObject(schema))
         return 'fc.anything()';
-    if (hasRef(schema))
-        return arbitraryName(refToName(schema.$ref, suffix));
+    if (hasRef(schema)) {
+        const name = arbitraryName(refToName(schema.$ref, ctx.suffix));
+        // A reference back to the type being generated must be tied lazily; an eager
+        // identifier would touch a still-uninitialized const (TDZ) at import time.
+        if (name === ctx.selfArbName) {
+            ctx.usedTie.value = true;
+            return `tie(${JSON.stringify(SELF_KEY)})`;
+        }
+        return name;
+    }
     if (hasConst(schema))
         return `fc.constant(${JSON.stringify(schema.const)})`;
     if (hasEnum(schema)) {
@@ -148,16 +209,21 @@ const arbitraryExpr = (schema, suffix) => {
         return 'fc.bigInt()';
     if (primitive)
         return 'fc.anything()';
+    // `allOf` must satisfy every branch at once. fast-check has no generic
+    // intersection combinator, so flatten the branches into one merged schema
+    // (tightest bounds, unioned required, merged properties) and generate from it.
+    if (hasAllOf(schema))
+        return arbitraryExpr(mergeAllOf(schema), ctx);
     if (hasOneOf(schema))
-        return oneofExpr(schema.oneOf, suffix);
+        return oneofExpr(schema.oneOf, ctx);
     if (hasAnyOf(schema))
-        return oneofExpr(schema.anyOf, suffix);
+        return oneofExpr(schema.anyOf, ctx);
     if (hasType(schema))
-        return scalarExpr(schema.type, schema, suffix);
+        return scalarExpr(schema.type, schema, ctx);
     // Multi-type schemas (`type: ['string', 'null']`) become a oneof over each
     // member type; `hasType` only matches a single string `type`.
     if (Array.isArray(schema.type)) {
-        const exprs = schema.type.map((type) => scalarExpr(type, schema, suffix));
+        const exprs = schema.type.map((type) => scalarExpr(type, schema, ctx));
         return exprs.length === 1 ? exprs[0] : `fc.oneof(${exprs.join(', ')})`;
     }
     return 'fc.anything()';
@@ -165,6 +231,10 @@ const arbitraryExpr = (schema, suffix) => {
 /**
  * Generates a `fast-check` arbitrary that produces schema-valid values.
  *
+ * A schema that references itself is wrapped in `fc.letrec` so the recursion is
+ * tied lazily — a plain `const NodeArbitrary = fc.record({ next: NodeArbitrary })`
+ * would throw a TDZ `ReferenceError` the moment the module is imported.
+ *
  * @example
  * ```typescript
  * generateArbitrary({ type: 'object', properties: { name: { type: 'string' } }, required: ['name'] }, 'Info')
@@ -172,6 +242,11 @@ const arbitraryExpr = (schema, suffix) => {
  * ```
  */
 export const generateArbitrary = (schema, typeName, suffix = '') => {
-    const expr = arbitraryExpr(schema, suffix);
-    return `export const ${arbitraryName(typeName)}: fc.Arbitrary<${typeName}> = ${expr}`;
+    const selfArbName = arbitraryName(typeName);
+    const ctx = { suffix, selfArbName, usedTie: { value: false } };
+    const expr = arbitraryExpr(schema, ctx);
+    if (ctx.usedTie.value) {
+        return `export const ${selfArbName}: fc.Arbitrary<${typeName}> = fc.letrec<{ ${SELF_KEY}: ${typeName} }>((tie) => ({\n  ${SELF_KEY}: ${expr},\n})).${SELF_KEY}`;
+    }
+    return `export const ${selfArbName}: fc.Arbitrary<${typeName}> = ${expr}`;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@amritk/generate-examples",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "description": "Generate fast-check arbitraries and example values from JSON Schemas.",
   "module": "./dist/index.js",
   "type": "module",
@@ -41,13 +41,13 @@
   },
   "exports": {
     ".": {
-      "default": "./dist/index.js",
-      "types": "./dist/index.d.ts"
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
     }
   },
   "dependencies": {
     "json-schema-typed": "^8.0.1",
-    "@amritk/helpers": "0.10.1"
+    "@amritk/helpers": "0.10.2"
   },
   "devDependencies": {
     "ajv": "^8.17.1"