@databehave/schema 0.1.2 → 0.1.4

package/dist/foundation/walk.js

@@ -0,0 +1,265 @@
+/**
+ * Extensibility API — IR walker and IR-to-builder reconstruction.
+ *
+ * databehave intentionally ships no CLI, no OpenAPI ingestion, no zod adapter,
+ * no GUI — these belong in *external* packages. This module exposes the
+ * minimum surface those packages need:
+ *
+ *   - `walkSchema(node, visitor)` : pre/post-order traversal with paths
+ *   - `fromIR(node)`              : reconstruct a `Schema` builder from IR
+ *
+ * Combined with the already-public `SchemaNode`, `Modifiers`, `Axes`,
+ * `mock`, `parse`, `mockDataset`, `createTrace`, and `seedFromString` /
+ * `rngFromString`, this is the full extension contract.
+ *
+ * Extension authors do NOT subclass `Schema`. They build IR (or compose
+ * existing builders) and call `fromIR` to obtain a typed builder back.
+ */
+import { arr, enum_, literal, obj, tuple, union, } from '../schema/composites.js';
+import { discriminated } from '../schema/conditional.js';
+import { decimal } from '../schema/decimal.js';
+import { bool, int, null_, num, str } from '../schema/primitives.js';
+import { SchemaConflictError } from './errors.js';
+import { Schema } from './types.js';
+/**
+ * Depth-first pre/post-order traversal of a schema IR tree.
+ *
+ * The visitor receives every node (including composites) with its
+ * JSON-pointer-style path. Use this to power codegen (OpenAPI, zod, SQL DDL,
+ * documentation) without coupling to the builder classes.
+ */
+export const walkSchema = (schemaOrNode, visitor) => {
+    const root = schemaOrNode instanceof Schema ? schemaOrNode._node : schemaOrNode;
+    walk(root, [], visitor);
+};
+const walk = (node, path, v) => {
+    const shouldDescend = v.enter ? v.enter(node, path) !== false : true;
+    if (shouldDescend) {
+        switch (node.kind) {
+            case 'object':
+                for (const k of Object.keys(node.fields)) {
+                    walk(node.fields[k], [...path, k], v);
+                }
+                break;
+            case 'array':
+                walk(node.item, [...path, '[]'], v);
+                break;
+            case 'tuple':
+                node.items.forEach((it, i) => walk(it, [...path, i], v));
+                break;
+            case 'union':
+                node.options.forEach((o, i) => walk(o, [...path, `|${i}`], v));
+                break;
+            case 'discriminated': {
+                // Positional `|i` tags mirror `union` so codegen tools can treat
+                // both as ordered alternatives.
+                const tags = Object.keys(node.branches);
+                tags.forEach((tag, i) => walk(node.branches[tag], [...path, `|${i}`], v));
+                break;
+            }
+            default:
+                break;
+        }
+    }
+    v.leave?.(node, path);
+};
+/**
+ * Reconstruct a `Schema` builder from an IR node.
+ *
+ * Modifiers (`nullable`, `optional`, `default`, `describe`, axes) are
+ * preserved. Returns `Schema<unknown>` — extension authors that know the shape
+ * statically can cast to a more precise type.
+ */
+export const fromIR = (node) => {
+    const base = buildBase(node);
+    return applyMods(base, node);
+};
+const buildBase = (node) => {
+    switch (node.kind) {
+        case 'string': {
+            let s = str();
+            if (node.min !== undefined)
+                s = s.min(node.min);
+            if (node.max !== undefined)
+                s = s.max(node.max);
+            if (node.pattern !== undefined)
+                s = s.pattern(node.pattern);
+            return s;
+        }
+        case 'number': {
+            let n = node.int ? int() : num();
+            if (node.min !== undefined)
+                n = n.min(node.min);
+            if (node.max !== undefined)
+                n = n.max(node.max);
+            return n;
+        }
+        case 'decimal': {
+            let d = decimal(node.precision, node.scale);
+            if (node.min !== undefined)
+                d = d.min(node.min);
+            if (node.max !== undefined)
+                d = d.max(node.max);
+            return d;
+        }
+        case 'boolean':
+            return bool();
+        case 'null':
+            return null_();
+        case 'literal':
+            return literal(node.value);
+        case 'enum':
+            return enum_(node.values);
+        case 'object': {
+            const fields = {};
+            for (const k of Object.keys(node.fields)) {
+                fields[k] = fromIR(node.fields[k]);
+            }
+            return obj(fields);
+        }
+        case 'array': {
+            let a = arr(fromIR(node.item));
+            if (node.length !== undefined)
+                a = a.length(node.length);
+            else {
+                if (node.minLength !== undefined)
+                    a = a.min(node.minLength);
+                if (node.maxLength !== undefined)
+                    a = a.max(node.maxLength);
+            }
+            return a;
+        }
+        case 'tuple': {
+            const items = node.items.map((it) => fromIR(it));
+            return tuple(...items);
+        }
+        case 'union': {
+            const opts = node.options.map((o) => fromIR(o));
+            return union(...opts);
+        }
+        case 'discriminated': {
+            // Reconstruct the branches as object schemas and feed them back to the
+            // builder. Round-tripping preserves the discriminator key.
+            const branchSchemas = {};
+            for (const tag of Object.keys(node.branches)) {
+                branchSchemas[tag] = fromIR(node.branches[tag]);
+            }
+            return discriminated(node.key, branchSchemas);
+        }
+    }
+};
+const applyMods = (schema, node) => {
+    const mods = node.mods;
+    if (mods === undefined)
+        return schema;
+    let out = schema;
+    if (mods.nullable === true)
+        out = out.nullable();
+    if (mods.optional === true)
+        out = out.optional();
+    if (mods.hasDefault === true)
+        out = out.default(mods.defaultValue);
+    if (mods.description !== undefined)
+        out = out.describe(mods.description);
+    if (mods.axes !== undefined) {
+        // Use the public axes-replay helper instead of reaching through a
+        // protected method via a cast.
+        out = out._applyAxes(mods.axes);
+    }
+    return out;
+};
+// ── IR versioning ──────────────────────────────────────────────────────
+//
+// The wire envelope ships a `$databehaveVersion` so a node serialised
+// by one MAJOR cannot silently load into an incompatible one. Bare
+// `SchemaNode`s remain accepted by `fromIR` for backward compatibility
+// with in-process extension authors; cross-process / on-disk callers
+// should round-trip through `serializeSchema` / `deserializeSchema`.
+/** Current IR contract version. Bumped on every MAJOR release. */
+export const IR_VERSION = 1;
+/**
+ * Wrap a schema's IR in a versioned envelope safe for serialisation
+ * (JSON, disk, IPC). Pair with {@link deserializeSchema} on the
+ * receiving end.
+ *
+ * Throws {@link SchemaConflictError} (`code: 'serialize.closure-axis'`)
+ * when any node in the tree carries a closure-bearing axis — `derived`,
+ * `invariants`, or an `occasionally` override whose `value` is a
+ * function. Closures cannot survive a JSON round-trip, so encoding such
+ * a schema would silently drop the axis on the receiving end and
+ * produce subtly wrong values. The check is loud at the encode site so
+ * callers reach for {@link replay} or hand-coded carriers instead.
+ */
+export const serializeSchema = (schema) => {
+    assertNoClosureAxes(schema._node, []);
+    return {
+        $databehaveVersion: IR_VERSION,
+        node: schema._node,
+    };
+};
+const assertNoClosureAxes = (node, path) => {
+    const axes = node.mods?.axes;
+    if (axes !== undefined) {
+        if (typeof axes.derived === 'function') {
+            throw new SchemaConflictError(`serializeSchema: axis 'derived' carries a closure that cannot be JSON-serialised`, [...path, 'axes', 'derived'], 'closures cannot survive JSON round-trip — keep derivedFrom() at the call site', 'serialize.closure-axis');
+        }
+        if (axes.invariants !== undefined && axes.invariants.length > 0) {
+            const idx = axes.invariants.findIndex((fn) => typeof fn === 'function');
+            if (idx >= 0) {
+                throw new SchemaConflictError(`serializeSchema: axis 'invariants[${idx}]' carries a closure that cannot be JSON-serialised`, [...path, 'axes', 'invariants', idx], 'closures cannot survive JSON round-trip — keep invariant() at the call site', 'serialize.closure-axis');
+            }
+        }
+        if (axes.occasionally !== undefined) {
+            const idx = axes.occasionally.findIndex((o) => typeof o.value === 'function');
+            if (idx >= 0) {
+                throw new SchemaConflictError(`serializeSchema: axis 'occasionally[${idx}].value' carries a closure that cannot be JSON-serialised`, [...path, 'axes', 'occasionally', idx, 'value'], 'closures cannot survive JSON round-trip — keep occasionally() at the call site', 'serialize.closure-axis');
+            }
+        }
+    }
+    switch (node.kind) {
+        case 'object':
+            for (const k of Object.keys(node.fields)) {
+                assertNoClosureAxes(node.fields[k], [...path, k]);
+            }
+            return;
+        case 'array':
+            assertNoClosureAxes(node.item, [...path, '[]']);
+            return;
+        case 'tuple':
+            node.items.forEach((it, i) => assertNoClosureAxes(it, [...path, i]));
+            return;
+        case 'union':
+            node.options.forEach((o, i) => assertNoClosureAxes(o, [...path, `|${i}`]));
+            return;
+        case 'discriminated': {
+            const tags = Object.keys(node.branches);
+            tags.forEach((tag, i) => assertNoClosureAxes(node.branches[tag], [...path, `|${i}`]));
+            return;
+        }
+        default:
+            return;
+    }
+};
+/**
+ * Inverse of {@link serializeSchema}. Throws when the envelope was
+ * produced by an incompatible MAJOR version — the failure is loud
+ * because silently loading a node with a renamed or removed field
+ * would manifest as a subtle generation/parse bug far from the cause.
+ */
+export const deserializeSchema = (envelope) => {
+    if (typeof envelope !== 'object' || envelope === null) {
+        throw new TypeError(`databehave/deserializeSchema: expected an envelope object, got ${typeof envelope}`);
+    }
+    const v = envelope.$databehaveVersion;
+    if (v !== IR_VERSION) {
+        throw new Error(`databehave/deserializeSchema: incompatible IR version ` +
+            `(envelope=${JSON.stringify(v)}, this build=${IR_VERSION}). ` +
+            `Re-serialise with the matching databehave MAJOR.`);
+    }
+    const node = envelope.node;
+    if (typeof node !== 'object' || node === null) {
+        throw new TypeError('databehave/deserializeSchema: envelope.node must be an IR object');
+    }
+    return fromIR(node);
+};
+//# sourceMappingURL=walk.js.map

package/dist/foundation/walk.js.map

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

package/dist/generator/engine.d.ts

@@ -0,0 +1,100 @@
+/**
+ * Generator engine — turns a SchemaNode + context into a deterministic value.
+ *
+ * Wires the data-schema axes into the sampling pipeline.
+ * Resolution priority during sampling:
+ *
+ *   1. invariants   (rejection-sample until they hold; bounded by MAX_ATTEMPTS)
+ *   2. identity     (handled at dataset layer; not seen here)
+ *   3. derived      (computed from sibling/root context — skip sampling entirely)
+ *   4. conditional  (union / discriminated branch selection)
+ *   5. domain       (closed candidate set)
+ *   6. distribution (weighted / normal / typical)
+ *   7. type         (fall-back bounds from the IR)
+ */
+import type { GenContext } from '../foundation/axes.js';
+import type { SchemaNode } from '../foundation/ir.js';
+import { type Rng } from '../foundation/prng.js';
+import type { Infer, Schema } from '../foundation/types.js';
+import type { TraceCollector } from './trace.js';
+/**
+ * Per-leaf stable-seed hook.
+ *
+ * Called for every leaf-value sampling (string/number/decimal/boolean/enum/domain).
+ * Return a non-empty string to deterministically reseed *just this leaf*
+ * (path-scoped) — useful for snapshot/CI runs where a subset of rows must
+ * stay identical regardless of the outer `seed`.
+ * Return `null`/`undefined`/`''` to fall back to the shared rng (normal random).
+ *
+ * Composite kinds (object/array/tuple/union) are unaffected; their children
+ * re-enter this hook with their own path.
+ */
+export type StableByFn = (ctx: GenContext) => string | null | undefined;
+/**
+ * Per-modifier probabilities for random injection during generation.
+ *
+ * These are opt-in. With the default `{ default: 0, optional: 0, nullable: 0 }`
+ * `mock()` always samples a real value for the underlying type and never
+ * silently substitutes the modifier short-circuit. Set a non-zero probability
+ * to exercise the `undefined` / `null` / default-value paths.
+ */
+export type ModifierProbs = {
+    /** Probability that `.default(v)` returns `v` instead of sampling. */
+    readonly default?: number;
+    /** Probability that `.optional()` returns `undefined`. */
+    readonly optional?: number;
+    /** Probability that `.nullable()` returns `null`. */
+    readonly nullable?: number;
+};
+export type MockOptions = {
+    /** Override the deterministic seed. Either a string or unsigned 32-bit int. */
+    readonly seed?: string | number;
+    /** Caller-supplied context channel exposed to derived/invariants as `ctx.input`. */
+    readonly input?: Readonly<Record<string, unknown>>;
+    /** Top-level row index (used by `mockDataset` so per-row derived can read `ctx.index`). */
+    readonly index?: number;
+    /** Optional trace collector — receives one entry per resolved field. */
+    readonly trace?: TraceCollector;
+    /** Reseed leaf sampling deterministically from a caller-chosen key. */
+    readonly stableBy?: StableByFn;
+    /**
+     * Probabilities used for modifier short-circuits during sampling.
+     *
+     * Defaults are **all zero** — modifiers do not inject randomness unless you
+     * explicitly opt in. This makes `mock()` exercise the underlying type by
+     * default (e.g. `mock(str().optional())` always returns a string).
+     */
+    readonly modifierProbs?: ModifierProbs;
+    /**
+     * Override the PRNG factory used when `seed` is a number.
+     *
+     * Defaults to {@link mulberry32}. When `seed` is a string the seed is
+     * first hashed (`seedFromString`) and then handed to this factory.
+     *
+     * Useful for tests that need to inject a constant or recorded RNG to
+     * exercise probability-driven branches deterministically. Production
+     * callers should leave this unset — `mulberry32` is the seeded default
+     * the determinism contract is calibrated against, and swapping it
+     * perturbs the output sequence.
+     */
+    readonly prng?: (seed: number) => Rng;
+};
+/**
+ * Generate a value that conforms to the given schema.
+ *
+ * Deterministic: identical `schema` + `options.seed` always yields the same
+ * value, on every machine, every run.
+ */
+export declare const mock: <S extends Schema>(schema: S, options?: MockOptions) => Infer<S>;
+export type GenState = {
+    rng: Rng;
+    rootSeed: string;
+    root: unknown;
+    modifierProbs: Required<ModifierProbs>;
+    input?: Readonly<Record<string, unknown>>;
+    rootIndex?: number;
+    trace?: TraceCollector;
+    stableBy?: StableByFn;
+};
+export declare const generateNode: (node: SchemaNode, path: readonly (string | number)[], parent: Readonly<Record<string, unknown>>, state: GenState) => unknown;
+//# sourceMappingURL=engine.d.ts.map

package/dist/generator/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../src/generator/engine.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAMV,UAAU,EAEX,MAAM,uBAAuB,CAAA;AAE9B,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAA;AACrD,OAAO,EAA6C,KAAK,GAAG,EAAE,MAAM,uBAAuB,CAAA;AAC3F,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAA;AAC3D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAA;AAEhD;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,GAAG,EAAE,UAAU,KAAK,MAAM,GAAG,IAAI,GAAG,SAAS,CAAA;AAEvE;;;;;;;GAOG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B,sEAAsE;IACtE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;IACzB,0DAA0D;IAC1D,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;IAC1B,qDAAqD;IACrD,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;CAC3B,CAAA;AAED,MAAM,MAAM,WAAW,GAAG;IACxB,+EAA+E;IAC/E,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;IAC/B,oFAAoF;IACpF,QAAQ,CAAC,KAAK,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;IAClD,2FAA2F;IAC3F,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;IACvB,wEAAwE;IACxE,QAAQ,CAAC,KAAK,CAAC,EAAE,cAAc,CAAA;IAC/B,uEAAuE;IACvE,QAAQ,CAAC,QAAQ,CAAC,EAAE,UAAU,CAAA;IAC9B;;;;;;OAMG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,aAAa,CAAA;IACtC;;;;;;;;;;;OAWG;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,GAAG,CAAA;CACtC,CAAA;AAMD;;;;;GAKG;AACH,eAAO,MAAM,IAAI,GAAI,CAAC,SAAS,MAAM,EAAE,QAAQ,CAAC,EAAE,UAAS,WAAgB,KAAG,KAAK,CAAC,CAAC,CAiCpF,CAAA;AAMD,MAAM,MAAM,QAAQ,GAAG;IACrB,GAAG,EAAE,GAAG,CAAA;IACR,QAAQ,EAAE,MAAM,CAAA;IAChB,IAAI,EAAE,OAAO,CAAA;IACb,aAAa,EAAE,QAAQ,CAAC,aAAa,CAAC,CAAA;IACtC,KAAK,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;IACzC,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,KAAK,CAAC,EAAE,cAAc,CAAA;IACtB,QAAQ,CAAC,EAAE,UAAU,CAAA;CACtB,CAAA;AA0DD,eAAO,MAAM,YAAY,GACvB,MAAM,UAAU,EAChB,MAAM,SAAS,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,EAClC,QAAQ,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACzC,OAAO,QAAQ,KACd,OA6DF,CAAA"}