@ghostry/fabricator 0.0.1 → 0.0.2

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

@@ -5,35 +5,32 @@ import type { ValueOf } from "../Schema/Types";
 import type { Adaptation, Kind, Meta, Produces } from "../Types";
 import type { PlainObject } from "../Utility/Types";
 /**
- * Threaded through `Constructor.ts`'s `make` for every dispatch of one
- * `new Fabricator(...)` construction — every branch forwards it
- * (extending `path`, never `algorithm`/`self`) into its own nested
- * `make(...)` calls, so it reaches however deeply a leaf sits nested
- * through `array`/`object`/`tuple`/etc.
+ * Threaded through `Constructor.ts`'s `make` for every dispatch of one `new
+ * Fabricator(...)` construction — every branch forwards it (extending `path`,
+ * never `algorithm`/`self`) into its own nested `make(...)` calls, so it
+ * reaches however deeply a leaf sits nested through
+ * `array`/`object`/`tuple`/etc.
  *
- * `toTrace` records this node's {@link Trace} — a plain object literal,
- * no hashing. Hashing is paid only where a kind actually calls
- * `toStreamFromTrace(algorithm, trace)`. Bound once in `construct()` to
- * this one construction's already-resolved `RandomSource`/
- * `ConstructionTrace` pair (see `Constructor.ts`'s `resolveScope`) —
- * every leaf calls `toTrace` with only its own structural `path` and
- * kind, never re-resolving the construction's root itself.
- * `T.recursive` is the one kind that rebinds `toTrace`: each lazy
- * expansion opens its own scope on the node's own private forked
- * `RandomSource` (see `recursive/Fabricator.ts`), so a data-dependent
- * expansion count can never perturb, or be perturbed by, anything else
- * built from the same `initialize()` instance —
- * `RandomSource.fork` (`Random/Types.ts`) is the isolation primitive.
+ * `toTrace` records this node's {@link Trace} — a plain object literal, no
+ * hashing. Hashing is paid only where a kind actually calls
+ * `toStreamFromTrace(algorithm, trace)`. Bound once in `construct()` to this
+ * one construction's already-resolved `RandomSource`/ `ConstructionTrace` pair
+ * (see `Constructor.ts`'s `resolveScope`) — every leaf calls `toTrace` with
+ * only its own structural `path` and kind, never re-resolving the
+ * construction's root itself. `T.recursive` is the one kind that rebinds
+ * `toTrace`: each lazy expansion opens its own scope on the node's own private
+ * forked `RandomSource` (see `recursive/Fabricator.ts`), so a data-dependent
+ * expansion count can never perturb, or be perturbed by, anything else built
+ * from the same `initialize()` instance — `RandomSource.fork`
+ * (`Random/Types.ts`) is the isolation primitive.
  *
- * `algorithm` rather than the `RandomSource` itself: stream derivation
- * depends on no per-source state, and a leaf has no business with
- * `toRoot`/`fork`. `clock` is not a field of its own — it is always
- * `trace.clock`.
+ * `algorithm` rather than the `RandomSource` itself: stream derivation depends
+ * on no per-source state, and a leaf has no business with `toRoot`/`fork`.
+ * `clock` is not a field of its own — it is always `trace.clock`.
  *
- * `self` is what makes `case "recursive.self"` resolve to "recurse one
- * level deeper, right now" — absent outside any active recursion, which
- * is how `case "recursive.self"` detects and rejects a `self` node used
- * where none applies.
+ * `self` is what makes `case "recursive.self"` resolve to "recurse one level
+ * deeper, right now" — absent outside any active recursion, which is how `case
+ * "recursive.self"` detects and rejects a `self` node used where none applies.
  */
 export type ConstructionContext = {
     toTrace: (path: ReadonlyArray<string>, kind: string) => Trace;
@@ -41,22 +38,20 @@ export type ConstructionContext = {
     self?: (() => unknown) | undefined;
 };
 /**
- * What every kind's `Fabricator(...)` receives in place of a repeated
- * `(schema, algorithm, trace)` positional list — `Constructor.ts`'s
- * `make` builds one per dispatched node from its own
- * `ConstructionContext`. `trace` is already path-bound and built
- * eagerly, so a kind that never draws still records one without calling
- * `toStreamFromTrace`. Laziness is load-bearing: `toTrace` is a plain
- * object literal, and hashing is paid only where a kind actually calls
- * `toStreamFromTrace(algorithm, trace)`. The guard is the call site's
- * own `if (meta.produce)` branch (or the equivalent drawing path), not
- * an unevaluated closure. `algorithm` rather than the `RandomSource`:
- * derivation depends on no per-source state, and a leaf has no business
- * with `toRoot`/`fork`. No `clock`: it is `trace.clock`, always. A
- * kind-specific extra — an array's `element`, an object's `fields`, a
- * choice's `weightings` — still follows as its own trailing parameter:
- * those vary per kind and were never part of the shared prefix this
- * replaces.
+ * What every kind's `Fabricator(...)` receives in place of a repeated `(schema,
+ * algorithm, trace)` positional list — `Constructor.ts`'s `make` builds one per
+ * dispatched node from its own `ConstructionContext`. `trace` is already
+ * path-bound and built eagerly, so a kind that never draws still records one
+ * without calling `toStreamFromTrace`. Laziness is load-bearing: `toTrace` is a
+ * plain object literal, and hashing is paid only where a kind actually calls
+ * `toStreamFromTrace(algorithm, trace)`. The guard is the call site's own `if
+ * (meta.produce)` branch (or the equivalent drawing path), not an unevaluated
+ * closure. `algorithm` rather than the `RandomSource`: derivation depends on no
+ * per-source state, and a leaf has no business with `toRoot`/`fork`. No
+ * `clock`: it is `trace.clock`, always. A kind-specific extra — an array's
+ * `element`, an object's `fields`, a choice's `weightings` — still follows as
+ * its own trailing parameter: those vary per kind and were never part of the
+ * shared prefix this replaces.
  */
 export type FabricatorContext<$Schema> = {
     schema: $Schema;
@@ -64,18 +59,18 @@ export type FabricatorContext<$Schema> = {
     trace: Trace;
 };
 /**
- * The most basic interface for a typed Fabricator.
- * No type introspection is possible.
+ * The most basic interface for a typed Fabricator. No type introspection is
+ * possible.
  */
 export type NaiveFabricator<$T> = {
     fabricate: () => $T;
 };
 /**
- * What every kind's `construct()` produces: a `NaiveFabricator` that
- * also hands back the Schema it was built from, via the same
- * `[Kind]`/`[Meta]` a Schema itself carries — so a built Fabricator
- * can be passed back into `object`/`array`/a registry `.extend()`
- * anywhere a Schema is expected (see `toSchema`).
+ * What every kind's `construct()` produces: a `NaiveFabricator` that also hands
+ * back the Schema it was built from, via the same `[Kind]`/`[Meta]` a Schema
+ * itself carries — so a built Fabricator can be passed back into
+ * `object`/`array`/a registry `.extend()` anywhere a Schema is expected (see
+ * `toSchema`).
  */
 export type Fabricator<$T> = NaiveFabricator<$T> & {
     [Kind]: SchemaKind;
@@ -83,48 +78,45 @@ export type Fabricator<$T> = NaiveFabricator<$T> & {
     readonly trace: Trace;
     /**
      * Carried over from the Schema by `Constructor.ts`'s `make` — inert to
-     * fabrication, but it has to survive building for an adapter handed a
-     * built Fabricator to see what the Schema declared (see
-     * `Adapter/Types.ts`).
+     * fabrication, but it has to survive building for an adapter handed a built
+     * Fabricator to see what the Schema declared (see `Adapter/Types.ts`).
      */
     readonly [Adaptation]?: Adaptations;
 };
 /**
  * The value type a built Fabricator produces — read directly off its
- * `fabricate` signature. Every kind's `construct()` output shares the
- * exact same shape (`NaiveFabricator<$T>` plus `[Kind]`/`[Meta]`, see
- * this file's `Fabricator<$T>`), so there's nothing to dispatch per
- * kind here — unlike `ValueOf`, which reads a Schema's phantom
- * `[Produces]` marker for the pre-`construct()` case, this only ever
- * needs to unwrap an already-uniform `fabricate: () => $T`.
+ * `fabricate` signature. Every kind's `construct()` output shares the exact
+ * same shape (`NaiveFabricator<$T>` plus `[Kind]`/`[Meta]`, see this file's
+ * `Fabricator<$T>`), so there's nothing to dispatch per kind here — unlike
+ * `ValueOf`, which reads a Schema's phantom `[Produces]` marker for the
+ * pre-`construct()` case, this only ever needs to unwrap an already-uniform
+ * `fabricate: () => $T`.
  */
 export type Fabrication<$Fabricator extends NaiveFabricator<any>> = $Fabricator extends NaiveFabricator<infer $T> ? $T : never;
 /**
- * Maps a Schema (or an already-built Fabricator of the same kind — see
- * the `object` branch, and every other branch below since each kind's
- * `Schema` also carries a required `as` method a built Fabricator never
- * has) to the precise, kind-specific `Fabricator<...>` type it builds
- * into. Mirrors `Adapter/TypeBox/index.ts`'s `ToTypeBox` dispatch.
- * Falls back to the loose base `Fabricator<ValueOf<$Schema>>` for
- * anything unmatched.
+ * Maps a Schema (or an already-built Fabricator of the same kind — see the
+ * `object` branch, and every other branch below since each kind's `Schema` also
+ * carries a required `as` method a built Fabricator never has) to the precise,
+ * kind-specific `Fabricator<...>` type it builds into. Mirrors
+ * `Adapter/TypeBox/index.ts`'s `ToTypeBox` dispatch. Falls back to the loose
+ * base `Fabricator<ValueOf<$Schema>>` for anything unmatched.
  *
- * No branch here needs to do anything about `[Adaptation]`: each
- * kind's own `Fabricator<$Schema>` reads it back off `$Schema` via
- * `AdaptationsOf`, so an adapted Schema's Fabricator carries the map
- * without this dispatch (or an intersection on top of it, which the
- * warning below would otherwise apply to) having to mention it.
- * `object.compute` is the one exception, taking its `$Adaptations`
- * explicitly because its Fabricator is parameterized by the computed
- * value and source rather than by the Schema.
+ * No branch here needs to do anything about `[Adaptation]`: each kind's own
+ * `Fabricator<$Schema>` reads it back off `$Schema` via `AdaptationsOf`, so an
+ * adapted Schema's Fabricator carries the map without this dispatch (or an
+ * intersection on top of it, which the warning below would otherwise apply to)
+ * having to mention it. `object.compute` is the one exception, taking its
+ * `$Adaptations` explicitly because its Fabricator is parameterized by the
+ * computed value and source rather than by the Schema.
  *
- * Every branch's own `Fabricator<$Schema>` type already carries a
- * `.schema` field (see each kind's `Core.ts`) — *not* added here via an
- * extra `& { schema: ... }` intersection: wrapping an already-named
- * type in a fresh intersection defeats a later `infer` over it (e.g.
- * each kind's own `Fabrication<$Fabricator>` helper, which narrows via
- * `extends Fabricator<infer $Schema>`) — TypeScript can't always
- * decompose the intersection back to recover `$Schema`, and silently
- * widens to the generic's constraint instead.
+ * Every branch's own `Fabricator<$Schema>` type already carries a `.schema`
+ * field (see each kind's `Core.ts`) — _not_ added here via an extra `& {
+ * schema: ... }` intersection: wrapping an already-named type in a fresh
+ * intersection defeats a later `infer` over it (e.g. each kind's own
+ * `Fabrication<$Fabricator>` helper, which narrows via `extends
+ * Fabricator<infer $Schema>`) — TypeScript can't always decompose the
+ * intersection back to recover `$Schema`, and silently widens to the generic's
+ * constraint instead.
  */
 export type AsFabricator<$Schema> = 
 /**

package/dist/types/Instance/Core.d.ts

@@ -2,95 +2,76 @@ import type { RandomSource } from "../Random/Types";
 import type { PlainObject } from "../Utility/Types";
 import type { Config, Instance, Overlay, Stack } from "./Types";
 /**
- * `combinatorial`'s default limit — `2**10`, so it admits ten
- * independent binary axes before requiring the caller to raise it
- * explicitly. Each enumerated instance costs a full build and
- * fabricate, so this is as much a wall-clock guard as a combinatorial
- * one.
+ * `combinatorial`'s default limit — `2**10`, so it admits ten independent
+ * binary axes before requiring the caller to raise it explicitly. Each
+ * enumerated instance costs a full build and fabricate, so this is as much a
+ * wall-clock guard as a combinatorial one.
  */
 export declare const DEFAULT_COMBINATORIAL_LIMIT = 1024;
 /**
- * The single place a `Config` inherits from a base — `initialize` lays
- * its own config over an empty `{}` base (nothing to inherit, so every
- * field falls through to a hardcoded default: an empty seed, wall-clock
- * `clock`, the built-in algorithm, `resolveAttribution(undefined)`'s
- * `"call site"` resolution, the default registry, the default
- * combinatorial limit), and `fork` lays its overlay over the instance
- * it was called on (a full, already-resolved `Config`, so every field
- * has a real value to fall back to). `base` is typed
- * `Partial<Config<PlainObject>>` rather than `Config` specifically so
- * both calls go through the same function.
+ * The single place a `Config` inherits from a base — `initialize` lays its own
+ * config over an empty `{}` base (nothing to inherit, so every field falls
+ * through to a hardcoded default: an empty seed, wall-clock `clock`, the
+ * built-in algorithm, `resolveAttribution(undefined)`'s `"call site"`
+ * resolution, the default registry, the default combinatorial limit), and
+ * `fork` lays its overlay over the instance it was called on (a full,
+ * already-resolved `Config`, so every field has a real value to fall back to).
+ * `base` is typed `Partial<Config<PlainObject>>` rather than `Config`
+ * specifically so both calls go through the same function.
  *
- * `seed` composes onto the base rather than replacing it only when
- * tagged with `layer(...)` (`{@link isLayered}`) — a bare `seed` (the
- * ordinary meaning everywhere else in this library) replaces the
- * base's outright, and an omitted `seed` inherits the base's unchanged
- * (or, at the root, an empty mixer via `normalizeSeed(undefined)`,
- * unless an env var supplies one). Wall-clock `clock` is the default
- * entropy; `seed` is an optional mixer.
+ * `seed` composes onto the base rather than replacing it only when tagged with
+ * `layer(...)` (`{@link isLayered}`) — a bare `seed` (the ordinary meaning
+ * everywhere else in this library) replaces the base's outright, and an omitted
+ * `seed` inherits the base's unchanged (or, at the root, an empty mixer via
+ * `normalizeSeed(undefined)`, unless an env var supplies one). Wall-clock
+ * `clock` is the default entropy; `seed` is an optional mixer.
  *
- * `attribution` resolves through `resolveAttribution` at most once per
- * call, and only when it's actually needed:
- * - an explicit `over.attribution` always wins (resolved fresh, so
- *   `fork({ attribution: { kind: "call site" } })` roots at *that*
- *   call);
- * - otherwise an already-resolved `base.attribution` is reused as-is
- *   — never re-resolved, which keeps a fork from silently re-rooting
- *   `"call site"` at wherever `fork()` itself happens to be called
- *   (`resolveCallerFile()` skips this library's own frames, so calling
- *   it from here still lands on the user's call site either way);
- * - only when neither is available (the root case, `base.attribution`
- *   absent) does this fall back to resolving the `"call site"`
- *   default.
- * That also keeps `initialize({ attribution: { kind: "none" } })` — or
- * any other explicit override — from paying for a stack walk whose
- * result would be immediately discarded.
+ * `attribution` resolves through `resolveAttribution` at most once per call,
+ * and only when it's actually needed:
+ *
+ * - an explicit `over.attribution` always wins (resolved fresh, so `fork({
+ *   attribution: { kind: "call site" } })` roots at _that_ call);
+ * - otherwise an already-resolved `base.attribution` is reused as-is — never
+ *   re-resolved, which keeps a fork from silently re-rooting `"call site"` at
+ *   wherever `fork()` itself happens to be called (`resolveCallerFile()` skips
+ *   this library's own frames, so calling it from here still lands on the
+ *   user's call site either way);
+ * - only when neither is available (the root case, `base.attribution` absent)
+ *   does this fall back to resolving the `"call site"` default. That also keeps
+ *   `initialize({ attribution: { kind: "none" } })` — or any other explicit
+ *   override — from paying for a stack walk whose result would be immediately
+ *   discarded.
  *
  * `algorithm`/`types`: wholesale replacement when given, matching how
  * `initialize({ types })` already behaves — no deep merge;
  * `registry.extend(...)` is the existing tool for that. `limits` is
  * re-validated through `resolveCombinatorialLimit` whenever given (or
- * inherited, or defaulted), so a bad limit fails at
- * `fork()`/`initialize()` time rather than at first use. `clock`
- * follows the given → inherited → default shape `algorithm` does, but
- * stays *unresolved* only for the explicit `"seeded"` sentinel: an
- * explicit `Date` and the unconfigured wall-clock default are stored
- * as epoch milliseconds (a stated instant, inherited as-is from then
- * on), while `"seeded"` is left as the sentinel rather than collapsed
- * to a number, so `resolveClock` can re-derive it from whichever
- * `seed` is actually in effect at read time. An omitted `clock` on a
- * `fork`/`wrap` whose seed changed therefore keeps the parent's
- * instant unless that parent was itself `"seeded"`.
+ * inherited, or defaulted), so a bad limit fails at `fork()`/`initialize()`
+ * time rather than at first use. `clock` follows the given → inherited →
+ * default shape `algorithm` does, but stays _unresolved_ only for the explicit
+ * `"seeded"` sentinel: an explicit `Date` and the unconfigured wall-clock
+ * default are stored as epoch milliseconds (a stated instant, inherited as-is
+ * from then on), while `"seeded"` is left as the sentinel rather than collapsed
+ * to a number, so `resolveClock` can re-derive it from whichever `seed` is
+ * actually in effect at read time. An omitted `clock` on a `fork`/`wrap` whose
+ * seed changed therefore keeps the parent's instant unless that parent was
+ * itself `"seeded"`.
  */
 export declare function overlay<$Registry extends PlainObject>(base: Partial<Config<PlainObject>>, over: Overlay<$Registry>): Config<$Registry>;
-/**
- * Builds a `Stack`: closes over a private `Frame[]`, pushing on `enter`
- * and popping in a `finally` — correct even around a `throw` from
- * `block`. One per root `initialize()`, threaded — never re-created —
- * through every `fork`/`wrap` descended from it, so it stays
- * per-lineage rather than module-level: two unrelated `initialize()`
- * calls each get their own stack and can never perturb each other,
- * while every instance sharing one stack (a fork included, no matter
- * where in the lineage it was created) resolves against the same
- * active frame.
- */
-export declare function toStack(): Stack;
 /**
  * The shared body `initialize` and `fork` both reduce to: build a
  * `RandomSource` from an already-resolved `Config`, then everything an
- * `Instance` exposes off of it. Returns the `RandomSource` alongside
- * the `Instance` — `initialize`/`fork` discard it, `wrap` keeps it to
- * stash on the `Frame` it pushes, so implicit (ambient) and explicit
- * (`scope.Fabricator`) construction inside one `wrap` resolve against
- * the very same source rather than each independently re-deriving one
- * from the same config (and so silently diverging/duplicating
- * construction ordinals).
+ * `Instance` exposes off of it. Returns the `RandomSource` alongside the
+ * `Instance` — `initialize`/`fork` discard it, `wrap` keeps it to stash on the
+ * `Frame` it pushes, so implicit (ambient) and explicit (`scope.Fabricator`)
+ * construction inside one `wrap` resolve against the very same source rather
+ * than each independently re-deriving one from the same config (and so silently
+ * diverging/duplicating construction ordinals).
  *
- * `stack` is threaded straight through to `Constructor`/`enumerables`
- * — this function never reads or writes it itself, only passes it
- * along so every built `Fabricator`/`combinatorial`/`coverage` can
- * consult whichever frame is active *at the moment each is called*,
- * not at this moment.
+ * `stack` is threaded straight through to `Constructor`/`enumerables` — this
+ * function never reads or writes it itself, only passes it along so every built
+ * `Fabricator`/`combinatorial`/`coverage` can consult whichever frame is active
+ * _at the moment each is called_, not at this moment.
  */
 export declare function instantiate<$Registry extends PlainObject>(config: Config<$Registry>, stack: Stack): {
     instance: Instance<$Registry>;

package/dist/types/Instance/Stack/Async.d.ts

@@ -0,0 +1,14 @@
+import type { Stack } from "../Types";
+/**
+ * The asynchronous carrier, and the **only** module in this package importing
+ * anything from `node:`. Nothing imports it directly: `Instance/Core.ts`
+ * imports `#stack`, whose `node`/`bun`/`deno` conditions (`package.json`)
+ * resolve here while `default` resolves to `./sync.ts`. That is what keeps the
+ * package importable on a runtime with no `node:async_hooks` while every
+ * runtime that has one gets async-safe `wrap` with nothing to configure.
+ *
+ * `AsyncLocalStorage.run` returns whatever `block` returns, so this satisfies
+ * `enter`'s sync-preserving `<$Return>` signature exactly as the sync carrier
+ * does — a synchronous `wrap` is unaffected by which carrier is in play.
+ */
+export declare function toStack(): Stack;

package/dist/types/Instance/Stack/Sync.d.ts

@@ -0,0 +1,14 @@
+import type { Stack } from "../Types";
+/**
+ * The synchronous carrier: a private `Frame[]`, pushed on `enter` and popped in
+ * a `finally` — correct even around a `throw` from `block`.
+ *
+ * Selected by the `#stack` `default` condition (`package.json`), i.e. on any
+ * runtime without `node:async_hooks` — in practice a browser bundle. Its frame
+ * cannot survive an `await`: `enter` returns `block()` without awaiting, so an
+ * async block's frame unwinds at the block's first suspension point, and a
+ * shared LIFO could not represent two overlapping scopes even if it did await.
+ * Both are why `asynchronous` is `false` and `wrap` refuses an async block here
+ * rather than resolving it against the base instance with no signal.
+ */
+export declare function toStack(): Stack;