@ghostry/fabricator 0.0.1 → 0.0.2

package/dist/types/Enumeration/Types.d.ts

@@ -3,38 +3,35 @@ import type { AnySchema, ValueOf } from "../Schema/Types";
 import type { Children, Kind, Meta } from "../Types";
 import type { PlainObject } from "../Utility/Types";
 /**
- * How a composite with more than one child combines their widths.
- * `"product"` is the cartesian product — width is the product of every
- * child's width; `at(index)` mixed-radix decodes to a full combination
- * (`combinatorial`). `"cycle"` (`coverage`) takes the widest child as
- * the composite's width, cycling narrower children to fill it — see
- * CLAUDE.md's "sum vs product" note for why cycling only ever applies
- * to `object`/`tuple` and never to a sum node (`choice`, the presence
- * wrappers), which always total their children's widths regardless of
- * strategy.
+ * How a composite with more than one child combines their widths. `"product"`
+ * is the cartesian product — width is the product of every child's width;
+ * `at(index)` mixed-radix decodes to a full combination (`combinatorial`).
+ * `"cycle"` (`coverage`) takes the widest child as the composite's width,
+ * cycling narrower children to fill it — see CLAUDE.md's "sum vs product" note
+ * for why cycling only ever applies to `object`/`tuple` and never to a sum node
+ * (`choice`, the presence wrappers), which always total their children's widths
+ * regardless of strategy.
  */
 export type Strategy = "product" | "cycle";
 /**
- * A fresh, reproducible permutation of `0..width-1` each call — one
- * per width-`>1` node `plan()` visits, in walk order, so two nodes of
- * the same width never receive the same permutation (which would
- * otherwise iterate them in lockstep — see CLAUDE.md's note on why a
- * constant phase offset isn't enough). Only consulted under `"cycle"`;
- * `"product"`'s mixed-radix decode already visits every combination,
- * so permuting there would only reorder identical output. Built in
- * `Enumerate.ts` (which can reach `Random/`), then threaded through
- * `plan()` as data — `Plan.ts` stays a total function and never
- * imports randomness.
+ * A fresh, reproducible permutation of `0..width-1` each call — one per
+ * width-`>1` node `plan()` visits, in walk order, so two nodes of the same
+ * width never receive the same permutation (which would otherwise iterate them
+ * in lockstep — see CLAUDE.md's note on why a constant phase offset isn't
+ * enough). Only consulted under `"cycle"`; `"product"`'s mixed-radix decode
+ * already visits every combination, so permuting there would only reorder
+ * identical output. Built in `Enumerate.ts` (which can reach `Random/`), then
+ * threaded through `plan()` as data — `Plan.ts` stays a total function and
+ * never imports randomness.
  */
 export type Orderer = (width: bigint) => ReadonlyArray<bigint>;
 /**
- * Recipe for one enumerated combination against a built Fabricator
- * tree: `undefined` for a drawn (not chosen) node — fabricate
- * normally; `{ value }` for a literal (enum member, boolean, `null`,
- * `undefined`, `Omitted`); `{ slots }`/`{ fields }` for a
- * tuple/object, recursing per position/key; `{ branch, inner }` for a
- * choice's chosen option, or a presence wrapper's "present" arm,
- * recursing into whichever child was picked.
+ * Recipe for one enumerated combination against a built Fabricator tree:
+ * `undefined` for a drawn (not chosen) node — fabricate normally; `{ value }`
+ * for a literal (enum member, boolean, `null`, `undefined`, `Omitted`); `{
+ * slots }`/`{ fields }` for a tuple/object, recursing per position/key; `{
+ * branch, inner }` for a choice's chosen option, or a presence wrapper's
+ * "present" arm, recursing into whichever child was picked.
  */
 export type Pin = undefined | {
     value: unknown;
@@ -47,35 +44,33 @@ export type Pin = undefined | {
     inner: Pin;
 };
 /**
- * One enumerable dimension: how many distinct outcomes, and the `Pin`
- * for the `index`-th (`0 <= index < width`). Widths are `bigint` so a
- * schema with many combined axes can be counted exactly — a `number`
- * would silently lose precision past `Number.MAX_SAFE_INTEGER` and
- * eventually overflow to `Infinity`, which would make a combinatorial
- * limit's error message state a false count.
+ * One enumerable dimension: how many distinct outcomes, and the `Pin` for the
+ * `index`-th (`0 <= index < width`). Widths are `bigint` so a schema with many
+ * combined axes can be counted exactly — a `number` would silently lose
+ * precision past `Number.MAX_SAFE_INTEGER` and eventually overflow to
+ * `Infinity`, which would make a combinatorial limit's error message state a
+ * false count.
  */
 export type Axis = {
     readonly width: bigint;
     readonly at: (index: bigint) => Pin;
 };
 /**
- * Resolved, already-validated enumeration limits — `initialize()` is
- * where `limits.combinatorial` is defaulted and checked
- * (`Number.isSafeInteger(limit) && limit >= 1`), so `Enumerate()`
- * always receives a value it can trust without re-validating.
- * `coverage` carries no limit here: its count is the widest single
- * axis, linear in the schema as written rather than a product, so
+ * Resolved, already-validated enumeration limits — `initialize()` is where
+ * `limits.combinatorial` is defaulted and checked (`Number.isSafeInteger(limit)
+ * && limit >= 1`), so `Enumerate()` always receives a value it can trust
+ * without re-validating. `coverage` carries no limit here: its count is the
+ * widest single axis, linear in the schema as written rather than a product, so
  * there is nothing for a limit to protect against.
  */
 export type Limits = {
     combinatorial: number;
 };
 /**
- * The shape both `combinatorial` and `coverage` share — strategy and
- * limit differ internally, neither visible here. Takes a Schema, not
- * a built Fabricator: `AnySchema` excludes `Fabricator<any>` (which
- * carries no `[Produces]`), so `ValueOf` can't silently degrade to
- * `unknown`.
+ * The shape both `combinatorial` and `coverage` share — strategy and limit
+ * differ internally, neither visible here. Takes a Schema, not a built
+ * Fabricator: `AnySchema` excludes `Fabricator<any>` (which carries no
+ * `[Produces]`), so `ValueOf` can't silently degrade to `unknown`.
  */
 export type Enumerable = <const $Schema extends AnySchema>(schema: $Schema) => Iterable<ValueOf<$Schema>>;
 export type Resolvable = {

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

@@ -1,18 +1,17 @@
 /**
  * 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.
+ * {@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.
+ * 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.
+ * 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.
@@ -28,8 +27,8 @@ export declare namespace FabricatorError {
      */
     type Phase = "construction" | "adaptation";
     /**
-     * `initialize({ limits: { combinatorial } })` when the configured limit
-     * could never be a meaningful instance count.
+     * `initialize({ limits: { combinatorial } })` when the configured limit could
+     * never be a meaningful instance count.
      */
     class InvalidCombinatorialLimitError extends FabricatorError {
         /**
@@ -47,12 +46,12 @@ export declare namespace FabricatorError {
         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.
+     * `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 {
         /**
@@ -66,9 +65,9 @@ export declare namespace FabricatorError {
         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.
+     * 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 {
         /**
@@ -82,36 +81,37 @@ export declare namespace FabricatorError {
         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.
+     * `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.
+         * 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.
+         * 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.
+     * 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.
+         * 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;
         /**
@@ -120,8 +120,9 @@ export declare namespace FabricatorError {
         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.
+         * 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, 
         /**
@@ -154,10 +155,9 @@ export declare namespace FabricatorError {
         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).
+     * 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 {
         /**
@@ -179,8 +179,8 @@ export declare namespace FabricatorError {
         constructor();
     }
     /**
-     * A `.refine()`-computed field's resolver returned a value of the wrong
-     * shape for the source schema it was declared against.
+     * 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 {
         /**
@@ -202,8 +202,8 @@ export declare namespace FabricatorError {
         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.
+     * 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 {
         /**
@@ -225,8 +225,8 @@ export declare namespace FabricatorError {
         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
+     * 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 {
@@ -236,7 +236,7 @@ export declare namespace FabricatorError {
         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
+         * _inner_ kind, since the wrapper's own absent/null outcomes are accepted
          * separately.
          */
         readonly kind: string;
@@ -251,7 +251,7 @@ export declare namespace FabricatorError {
         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
+         * _inner_ kind, since the wrapper's own absent/null outcomes are accepted
          * separately.
          */
         kind: string, 
@@ -261,9 +261,8 @@ export declare namespace FabricatorError {
         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.
+     * 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 {
         /**
@@ -310,8 +309,8 @@ export declare namespace FabricatorError {
         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.
+     * `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 {
         /**
@@ -352,8 +351,8 @@ export declare namespace FabricatorError {
     }
     /**
      * 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.
+     * 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 {
         /**
@@ -367,10 +366,10 @@ export declare namespace FabricatorError {
         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).
+     * 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 {
         /**
@@ -413,8 +412,8 @@ export declare namespace FabricatorError {
     }
     /**
      * 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.
+     * distribution's density is proportional to `1/x`, so it is undefined at or
+     * below zero.
      */
     class InvalidDistributionBoundError extends FabricatorError {
         /**
@@ -444,8 +443,8 @@ export declare namespace FabricatorError {
         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.
+     * 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";
@@ -456,10 +455,10 @@ export declare namespace FabricatorError {
         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}.
+     * 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 {
         /**
@@ -489,9 +488,9 @@ export declare namespace FabricatorError {
         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.
+     * 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 {
         /**
@@ -515,9 +514,9 @@ export declare namespace FabricatorError {
         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.
+     * `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 {
         /**
@@ -538,4 +537,23 @@ export declare namespace FabricatorError {
          */
         given: string);
     }
+    /**
+     * `wrap(overlay, block)` handed an `async` block while the lineage's ambient
+     * carrier is the synchronous one (`Instance/Stack/Sync.ts`).
+     *
+     * Its frame cannot outlive the block's first `await`, so a build reached
+     * after one would resolve against the base instance rather than the wrap —
+     * plausible data, quietly drawn from the wrong configuration. Raised instead
+     * of allowing that, which is why it fires even when `block` only ever uses
+     * `scope`: whether a later build reads the ambient frame is not knowable from
+     * here.
+     *
+     * Reachable only where `#stack` resolved to `default` — a runtime with no
+     * `node:async_hooks`, in practice a browser bundle — or where `initialize({
+     * stack })` supplied a synchronous carrier explicitly. Node, Bun, and Deno
+     * all resolve to the `AsyncLocalStorage` carrier and never raise this.
+     */
+    class SynchronousStackError extends FabricatorError {
+        constructor();
+    }
 }

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

@@ -3,41 +3,39 @@ 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.
+ * 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
+ * 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.
+ * 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.
+ * `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`.
+ * 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;