@ghostry/fabricator 0.0.1

package/dist/types/Error/index.d.ts

@@ -0,0 +1,541 @@
+/**
+ * Every error this library throws is a named subclass of
+ * {@link FabricatorError}, kept in one dependency-free module:
+ * `instanceof FabricatorError` catches everything the library raises, and no
+ * error definition can pull a primitive's module graph into an unrelated
+ * import.
+ *
+ * Kind tags are plain `string`, not the `Kind` union from
+ * `Primitive/index.ts` — that second reason, and because several of these
+ * errors exist precisely because the kind in hand was *not* a member of it.
+ *
+ * Context is `public readonly` constructor parameters, but the message still
+ * stands on its own: a consumer reading only `.message` should not need a
+ * field to understand the failure. Fields are for programmatic access, and
+ * for detail too bulky to inline.
+ */
+/**
+ * Base error class from which more specific errors inherit.
+ */
+export declare abstract class FabricatorError extends Error {
+    constructor();
+}
+export declare namespace FabricatorError {
+    /**
+     * The phase a failure was raised from, for the errors reachable both while
+     * building a Fabricator (`Fabricator/Constructor.ts`'s `make`) and while
+     * converting to an external schema (an adapter's own `convert`).
+     */
+    type Phase = "construction" | "adaptation";
+    /**
+     * `initialize({ limits: { combinatorial } })` when the configured limit
+     * could never be a meaningful instance count.
+     */
+    class InvalidCombinatorialLimitError extends FabricatorError {
+        /**
+         * The rejected limit, as resolved — so an explicit `0`, a fractional
+         * number, and a value past `Number.MAX_SAFE_INTEGER` are all
+         * distinguishable after the fact.
+         */
+        readonly limit: unknown;
+        constructor(
+        /**
+         * The rejected limit, as resolved — so an explicit `0`, a fractional
+         * number, and a value past `Number.MAX_SAFE_INTEGER` are all
+         * distinguishable after the fact.
+         */
+        limit: unknown);
+    }
+    /**
+     * `initialize({ attribution: { kind: "rooted", root } })` when `root` is
+     * not an absolute path or a `file://` URL. A relative root can never prefix
+     * a resolved caller file, so `relativize` would leave every file unchanged
+     * — the option would look configured while silently doing nothing. Thrown
+     * eagerly at `initialize()`, not deferred to wherever that would first
+     * become observable.
+     */
+    class InvalidAttributionRootError extends FabricatorError {
+        /**
+         * The rejected root, as given.
+         */
+        readonly root: string;
+        constructor(
+        /**
+         * The rejected root, as given.
+         */
+        root: string);
+    }
+    /**
+     * A `self` placeholder resolved with no `T.recursive` expanding around it
+     * — only reachable by holding a `self` reference outside the
+     * `T.recursive(...)` callback it was handed to.
+     */
+    class DetachedSelfError extends FabricatorError {
+        /**
+         * Which walk hit the detached reference.
+         */
+        readonly during: Phase;
+        constructor(
+        /**
+         * Which walk hit the detached reference.
+         */
+        during: Phase);
+    }
+    /**
+     * `T.recursive(body).whereby({ depth })` with no `terminal`, when `body`
+     * has a `self` that is not behind a kind that can stop recursing — a
+     * required object field, a tuple slot, the body itself, or a `choice`
+     * whose every option still contains `self`. Thrown at `.whereby()`, not
+     * at fabricate time. An explicit `terminal` is the way out.
+     */
+    class UnterminableRecursiveError extends FabricatorError {
+        /**
+         * Structural path from the recursive body to the unterminable
+         * `self` (or to the `choice` that had no remaining non-`self`
+         * option), as field names / slot indices.
+         */
+        readonly path: ReadonlyArray<string>;
+        constructor(
+        /**
+         * Structural path from the recursive body to the unterminable
+         * `self` (or to the `choice` that had no remaining non-`self`
+         * option), as field names / slot indices.
+         */
+        path: ReadonlyArray<string>);
+    }
+    /**
+     * A walk reached a node whose `[Kind]` it has no case for — a Schema built
+     * by hand or cast past the type system, or a kind added to
+     * `Primitive/index.ts` without wiring it into every dispatch site.
+     */
+    class UnknownKindError extends FabricatorError {
+        /**
+         * The unrecognized `[Kind]` tag, stringified — it may be any value at all,
+         * since reaching this error means the type system was already bypassed.
+         */
+        readonly kind: string;
+        /**
+         * Which walk failed to dispatch it.
+         */
+        readonly during: Phase;
+        constructor(
+        /**
+         * The unrecognized `[Kind]` tag, stringified — it may be any value at all,
+         * since reaching this error means the type system was already bypassed.
+         */
+        kind: string, 
+        /**
+         * Which walk failed to dispatch it.
+         */
+        during: Phase);
+    }
+    /**
+     * `T.enum`/`T.choice` given no items. An empty draw table has nothing to
+     * select, which would otherwise surface as an opaque `TypeError` inside
+     * `weighted()` at fabricate time rather than here.
+     */
+    class EmptyItemsError extends FabricatorError {
+        /**
+         * The registry entry that was called, e.g. `"T.enum.uniform"`.
+         */
+        readonly label: string;
+        /**
+         * What the kind calls its items, e.g. `"member"`/`"option"`.
+         */
+        readonly noun: string;
+        constructor(
+        /**
+         * The registry entry that was called, e.g. `"T.enum.uniform"`.
+         */
+        label: string, 
+        /**
+         * What the kind calls its items, e.g. `"member"`/`"option"`.
+         */
+        noun: string);
+    }
+    /**
+     * An object's definition names a key that would reach `Object.prototype` —
+     * a developer-written key, where throwing is actionable (contrast
+     * `record`'s *drawn* keys, written with `Object.defineProperty` instead of
+     * rejected).
+     */
+    class PrototypePollutionError extends FabricatorError {
+        /**
+         * The offending key.
+         */
+        readonly key: string;
+        constructor(
+        /**
+         * The offending key.
+         */
+        key: string);
+    }
+    /**
+     * A `.refine()`-computed field fabricated on its own. A computed field's
+     * value is derived from its sibling fields, so there is nothing to resolve
+     * against outside the object that owns it.
+     */
+    class DetachedComputeError extends FabricatorError {
+        constructor();
+    }
+    /**
+     * A `.refine()`-computed field's resolver returned a value of the wrong
+     * shape for the source schema it was declared against.
+     */
+    class ComputeResultMismatchError extends FabricatorError {
+        /**
+         * The `[Kind]` of the field's source schema.
+         */
+        readonly kind: string;
+        /**
+         * What the resolver actually returned.
+         */
+        readonly value: unknown;
+        constructor(
+        /**
+         * The `[Kind]` of the field's source schema.
+         */
+        kind: string, 
+        /**
+         * What the resolver actually returned.
+         */
+        value: unknown);
+    }
+    /**
+     * An override names a field the object schema does not define — most
+     * often a typo, which is why the known fields are listed.
+     */
+    class UnknownOverrideFieldError extends FabricatorError {
+        /**
+         * The name that was not found.
+         */
+        readonly field: string;
+        /**
+         * Every field the schema does define, in definition order.
+         */
+        readonly available: ReadonlyArray<string>;
+        constructor(
+        /**
+         * The name that was not found.
+         */
+        field: string, 
+        /**
+         * Every field the schema does define, in definition order.
+         */
+        available: ReadonlyArray<string>);
+    }
+    /**
+     * An override value does not fit the field it is meant to replace. Raised
+     * for every field shape — a plain field, a nested object, and each presence
+     * wrapper unwrapped to its inner kind — the same failure in each case.
+     */
+    class InvalidOverrideValueError extends FabricatorError {
+        /**
+         * The field being overridden.
+         */
+        readonly field: string;
+        /**
+         * The `[Kind]` the value was checked against — for a wrapper field, the
+         * *inner* kind, since the wrapper's own absent/null outcomes are accepted
+         * separately.
+         */
+        readonly kind: string;
+        /**
+         * The rejected value.
+         */
+        readonly value: unknown;
+        constructor(
+        /**
+         * The field being overridden.
+         */
+        field: string, 
+        /**
+         * The `[Kind]` the value was checked against — for a wrapper field, the
+         * *inner* kind, since the wrapper's own absent/null outcomes are accepted
+         * separately.
+         */
+        kind: string, 
+        /**
+         * The rejected value.
+         */
+        value: unknown);
+    }
+    /**
+     * Thrown when `Omitted` is passed to override a field that has no
+     * absent outcome. Only `T.omittable`/`T.optional` fields can be forced
+     * off.
+     */
+    class IllegalOmittedOverrideError extends FabricatorError {
+        /**
+         * The field being overridden.
+         */
+        readonly field: string;
+        /**
+         * The field's `[Kind]`, which is neither `object.omittable` nor
+         * `object.optional`.
+         */
+        readonly kind: string;
+        constructor(
+        /**
+         * The field being overridden.
+         */
+        field: string, 
+        /**
+         * The field's `[Kind]`, which is neither `object.omittable` nor
+         * `object.optional`.
+         */
+        kind: string);
+    }
+    /**
+     * An enumeration axis asked for an index at or past its own width — an
+     * internal invariant of `Enumeration/Plan.ts`, not caller-reachable.
+     */
+    class EnumerationIndexError extends FabricatorError {
+        /**
+         * The requested index.
+         */
+        readonly index: bigint;
+        /**
+         * The axis's width, which the index must stay below.
+         */
+        readonly width: bigint;
+        constructor(
+        /**
+         * The requested index.
+         */
+        index: bigint, 
+        /**
+         * The axis's width, which the index must stay below.
+         */
+        width: bigint);
+    }
+    /**
+     * `resolve()` handed a pin for a kind `plan()` never produces one for —
+     * the two must stay in agreement; internal invariant, not caller-reachable.
+     */
+    class UnpinnableKindError extends FabricatorError {
+        /**
+         * The kind that received a pin.
+         */
+        readonly kind: string;
+        constructor(
+        /**
+         * The kind that received a pin.
+         */
+        kind: string);
+    }
+    /**
+     * `combinatorial(...)` when the cartesian product of every enumerable axis
+     * exceeds the configured limit. Thrown eagerly, before any instance is
+     * produced.
+     */
+    class CombinatorialLimitExceededError extends FabricatorError {
+        /**
+         * The exact instance count, counted in `bigint` so it stays precise past
+         * `Number.MAX_SAFE_INTEGER`.
+         */
+        readonly width: bigint;
+        /**
+         * The configured limit it exceeded.
+         */
+        readonly limit: number;
+        constructor(
+        /**
+         * The exact instance count, counted in `bigint` so it stays precise past
+         * `Number.MAX_SAFE_INTEGER`.
+         */
+        width: bigint, 
+        /**
+         * The configured limit it exceeded.
+         */
+        limit: number);
+    }
+    /**
+     * A `record`'s key schema has no counterpart in the external schema library
+     * being adapted to — a symbol key, for TypeBox, whose `Type.Record`
+     * silently yields a schema nothing can satisfy rather than raising.
+     */
+    class UnrepresentableRecordKeyError extends FabricatorError {
+        /**
+         * The `[Kind]` of the record's key schema.
+         */
+        readonly kind: string;
+        constructor(
+        /**
+         * The `[Kind]` of the record's key schema.
+         */
+        kind: string);
+    }
+    /**
+     * A `{ min, max }` range contains no fabricable value — inverted bounds,
+     * a point range with an exclusive end, or a discrete exclusive pair whose
+     * effective integers are none. Thrown at `.whereby()` (or at construction
+     * for `T.date.past`/`future`, whose other end is the instance clock).
+     */
+    class EmptyRangeError extends FabricatorError {
+        /**
+         * The registry entry that was called, e.g. `"T.number.whereby"`.
+         */
+        readonly label: string;
+        /**
+         * Canonical lower bound as stored — `{ value, exclusive }`.
+         */
+        readonly min: {
+            readonly value: unknown;
+            readonly exclusive: boolean;
+        };
+        /**
+         * Canonical upper bound as stored.
+         */
+        readonly max: {
+            readonly value: unknown;
+            readonly exclusive: boolean;
+        };
+        constructor(
+        /**
+         * The registry entry that was called, e.g. `"T.number.whereby"`.
+         */
+        label: string, 
+        /**
+         * Canonical lower bound as stored — `{ value, exclusive }`.
+         */
+        min: {
+            readonly value: unknown;
+            readonly exclusive: boolean;
+        }, 
+        /**
+         * Canonical upper bound as stored.
+         */
+        max: {
+            readonly value: unknown;
+            readonly exclusive: boolean;
+        });
+    }
+    /**
+     * A distribution's bounds fall outside its own domain — a `logarithmic`
+     * distribution's density is proportional to `1/x`, so it is undefined at
+     * or below zero.
+     */
+    class InvalidDistributionBoundError extends FabricatorError {
+        /**
+         * The distribution that rejected the bounds.
+         */
+        readonly distribution: string;
+        /**
+         * The lower bound as given.
+         */
+        readonly min: number;
+        /**
+         * The upper bound as given.
+         */
+        readonly max: number;
+        constructor(
+        /**
+         * The distribution that rejected the bounds.
+         */
+        distribution: string, 
+        /**
+         * The lower bound as given.
+         */
+        min: number, 
+        /**
+         * The upper bound as given.
+         */
+        max: number);
+    }
+    /**
+     * Which entry of a `.weighted(...)` call carried the bad weight: a position in
+     * a caller-supplied list, or one of a fixed, named outcome set.
+     */
+    type WeightEntry = {
+        readonly kind: "index";
+        readonly index: number;
+        readonly noun: string;
+    } | {
+        readonly kind: "name";
+        readonly name: string;
+    };
+    /**
+     * A `.weighted(...)` call gives an outcome a weight that is not
+     * expressible: negative, `NaN`, or `Infinity`. Zero is valid — it
+     * disables the outcome — so this is not "anything `weighted()` would
+     * drop." An empty drawable set is {@link NoDrawableOutcomesError}.
+     */
+    class InvalidWeightError extends FabricatorError {
+        /**
+         * The registry entry that was called, e.g. `"T.choice.weighted"`.
+         */
+        readonly label: string;
+        /**
+         * The rejected weight.
+         */
+        readonly weight: number;
+        /**
+         * Which entry it was attached to.
+         */
+        readonly entry: WeightEntry;
+        constructor(
+        /**
+         * The registry entry that was called, e.g. `"T.choice.weighted"`.
+         */
+        label: string, 
+        /**
+         * The rejected weight.
+         */
+        weight: number, 
+        /**
+         * Which entry it was attached to.
+         */
+        entry: WeightEntry);
+    }
+    /**
+     * A weighted draw table has nothing left to pick: every weight is
+     * zero (or the list was empty of drawable entries). Zeroing an
+     * outcome disables it, so at least one must keep a positive weight.
+     */
+    class NoDrawableOutcomesError extends FabricatorError {
+        /**
+         * The registry entry or call site, e.g. `"T.enum.weighted"`.
+         */
+        readonly label: string;
+        /**
+         * What the kind calls its entries, e.g. `"member"`/`"option"`/
+         * `"outcome"`/`"component"`/`"character class"`.
+         */
+        readonly noun: string;
+        constructor(
+        /**
+         * The registry entry or call site, e.g. `"T.enum.weighted"`.
+         */
+        label: string, 
+        /**
+         * What the kind calls its entries, e.g. `"member"`/`"option"`/
+         * `"outcome"`/`"component"`/`"character class"`.
+         */
+        noun: string);
+    }
+    /**
+     * `new Fabricator(schema, trace)` when `trace.kind` names a different
+     * kind than `schema`. A trace reproduces the node it was taken from,
+     * so its kind must match the schema it is replayed against.
+     */
+    class TraceKindMismatchError extends FabricatorError {
+        /**
+         * The schema's own kind.
+         */
+        readonly expected: string;
+        /**
+         * The kind recorded on the trace.
+         */
+        readonly given: string;
+        constructor(
+        /**
+         * The schema's own kind.
+         */
+        expected: string, 
+        /**
+         * The kind recorded on the trace.
+         */
+        given: string);
+    }
+}

package/dist/types/Fabricator/Constructor.d.ts

@@ -0,0 +1,43 @@
+import type { Stack } from "../Instance/Types";
+import type { ConstructorOptions, RandomSource } from "../Random/Types";
+import { type Buildable } from "../Types";
+import { type AsFabricator } from "./Types";
+/**
+ * The type of `construct()` itself, as handed back by `Constructor` —
+ * kept separate so `initialize`'s return type (`src/index.ts`) can name
+ * it without re-deriving it from `Constructor`'s implementation.
+ *
+ * Both a call signature and a construct signature: `construct` is a
+ * plain `function` that explicitly returns an object, so
+ * `new construct(schema)` behaves identically to `construct(schema)` —
+ * a `new` call's returned object always replaces the freshly-created
+ * `this`. The construct signature lets callers spell
+ * `new T.Fabricator(schema)` — or `new Fabricator(schema, { seed })` to
+ * pin this one build to an explicit seed, independent of the file it's
+ * constructed in (see `construct()` for what `options.seed` does).
+ */
+export type Constructor = {
+    new <const $Schema extends Buildable>(schema: $Schema, options?: ConstructorOptions): AsFabricator<$Schema>;
+};
+/**
+ * Build the untyped recursive core — mirrors `Adapter/TypeBox/index.ts`'s
+ * own internal `convert(schema: any)` — and the precisely-typed
+ * `construct()` boundary around it, both closed over a single instance's
+ * `source` so every fabricator this `construct()` produces draws from
+ * that instance's own seed/streams and never another instance's.
+ *
+ * `stack` is the instance's own lineage-wide ambient stack
+ * (`Instance/Core.ts`'s `toStack()`) — passed straight through to
+ * `resolveScope` on every `construct()` call, never read here directly,
+ * so a build reached inside an active `wrap` resolves against that
+ * frame automatically, with nothing threaded through by the caller.
+ *
+ * No separate `clock` parameter: `source` already carries its own
+ * resolved clock intrinsically (`Random/Types.ts`'s `Options.clock`,
+ * baked in when the source was built), and `resolveScope`'s chosen
+ * source — the active `wrap` frame's, or this one — is exactly the
+ * source whose clock a construction should resolve "now" against.
+ * `toConstructionContext` reads it straight off the resolved root
+ * rather than threading a second value alongside `source`.
+ */
+export declare function Constructor(source: RandomSource, stack: Stack): Constructor;