@ghostry/fabricator 0.0.11 → 0.0.13

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (67) hide show
  1. package/README.md +1 -1
  2. package/dist/esm/Enumeration/Enumerate.js +2 -4
  3. package/dist/esm/Error/index.js +34 -6
  4. package/dist/esm/Fabricator/Constructor.js +40 -33
  5. package/dist/esm/Fabricator/Fabricate.js +23 -0
  6. package/dist/esm/Instance/Core.js +14 -2
  7. package/dist/esm/Instance/Stack/Visible.js +6 -1
  8. package/dist/esm/Primitive/boolean/Registry.js +10 -8
  9. package/dist/esm/Primitive/date/Defaults.js +12 -0
  10. package/dist/esm/Primitive/date/Fabricator.js +5 -10
  11. package/dist/esm/Primitive/date/Registry.js +49 -39
  12. package/dist/esm/Primitive/index.js +2 -0
  13. package/dist/esm/Primitive/null/Registry.js +6 -4
  14. package/dist/esm/Primitive/number/Fabricator.js +1 -1
  15. package/dist/esm/Primitive/number/Registry.js +36 -30
  16. package/dist/esm/Primitive/object/Fabricator.js +33 -11
  17. package/dist/esm/Primitive/object/Registry.js +90 -10
  18. package/dist/esm/Primitive/object/compute/Fabricator.js +10 -3
  19. package/dist/esm/Primitive/object/compute/Registry.js +20 -3
  20. package/dist/esm/Primitive/object/omit/Registry.js +5 -0
  21. package/dist/esm/Primitive/object/omit/index.js +2 -0
  22. package/dist/esm/Primitive/object/pick/Registry.js +5 -0
  23. package/dist/esm/Primitive/object/pick/index.js +2 -0
  24. package/dist/esm/Primitive/recursive/Fabricator.js +1 -0
  25. package/dist/esm/Primitive/recursive/Terminate.js +21 -9
  26. package/dist/esm/Primitive/symbol/Registry.js +15 -13
  27. package/dist/esm/Primitive/undefined/Registry.js +6 -4
  28. package/dist/esm/Schema/Core.js +9 -1
  29. package/dist/esm/Schema/Registry.js +27 -7
  30. package/dist/esm/Utility/DeepMerge.js +47 -6
  31. package/dist/esm/internal.js +1 -0
  32. package/dist/types/Error/index.d.ts +71 -6
  33. package/dist/types/Fabricator/Fabricate.d.ts +63 -0
  34. package/dist/types/Fabricator/Types.d.ts +13 -3
  35. package/dist/types/Harnessing/Core.d.ts +7 -7
  36. package/dist/types/Instance/Core.d.ts +15 -8
  37. package/dist/types/Instance/Stack/Visible.d.ts +10 -0
  38. package/dist/types/Instance/Types.d.ts +30 -15
  39. package/dist/types/Primitive/boolean/Registry.d.ts +6 -1
  40. package/dist/types/Primitive/date/Defaults.d.ts +11 -0
  41. package/dist/types/Primitive/date/Registry.d.ts +13 -9
  42. package/dist/types/Primitive/date/Types.d.ts +10 -0
  43. package/dist/types/Primitive/index.d.ts +2 -0
  44. package/dist/types/Primitive/null/Registry.d.ts +6 -1
  45. package/dist/types/Primitive/number/Registry.d.ts +8 -1
  46. package/dist/types/Primitive/object/Fabricator.d.ts +13 -5
  47. package/dist/types/Primitive/object/Registry.d.ts +17 -1
  48. package/dist/types/Primitive/object/Types.d.ts +19 -0
  49. package/dist/types/Primitive/object/compute/Fabricator.d.ts +9 -8
  50. package/dist/types/Primitive/object/compute/Registry.d.ts +7 -1
  51. package/dist/types/Primitive/object/compute/Schema.d.ts +20 -0
  52. package/dist/types/Primitive/object/compute/Types.d.ts +10 -0
  53. package/dist/types/Primitive/object/omit/Registry.d.ts +7 -0
  54. package/dist/types/Primitive/object/omit/index.d.ts +2 -0
  55. package/dist/types/Primitive/object/pick/Registry.d.ts +8 -0
  56. package/dist/types/Primitive/object/pick/index.d.ts +2 -0
  57. package/dist/types/Primitive/recursive/Fabricator.d.ts +9 -7
  58. package/dist/types/Primitive/symbol/Registry.d.ts +6 -1
  59. package/dist/types/Primitive/undefined/Registry.d.ts +6 -1
  60. package/dist/types/Schema/Core.d.ts +16 -1
  61. package/dist/types/Schema/Registry.d.ts +7 -4
  62. package/dist/types/Utility/DeepMerge.d.ts +11 -0
  63. package/dist/types/index.d.ts +23 -10
  64. package/dist/types/internal.d.ts +8 -0
  65. package/package.json +4 -4
  66. /package/dist/esm/Primitive/number/{defaults.js → Defaults.js} +0 -0
  67. /package/dist/types/Primitive/number/{defaults.d.ts → Defaults.d.ts} +0 -0
@@ -0,0 +1,63 @@
1
+ import type { Ancestry, Stack } from "../Instance/Types";
2
+ import type { RandomSource } from "../Random/Types";
3
+ import type { AnySchema, Fabricated } from "../Schema/Types";
4
+ import type { Constructor } from "./Constructor";
5
+ import type { NaiveFabricator } from "./Types";
6
+ /**
7
+ * `new Fabricator(schema).fabricate()` in one call, without a build per call:
8
+ * the first call with a given schema in a given scope builds, and every later
9
+ * one continues that same Fabricator's streams. A repeated call therefore takes
10
+ * no construction ordinal, so it shifts nothing built after it.
11
+ *
12
+ * The key is the schema's identity. A schema held in a variable — including an
13
+ * overridden one, `const Admin = User.override({ ... })` — is reused. One
14
+ * written at the call site — `fabricate(User.override({ ... }))`, an inline
15
+ * `.whereby(...)`, a bare registry entry like `fabricate(T.number)`, whose
16
+ * every read is a fresh Schema — is a new object on every call, so every call
17
+ * builds and takes an ordinal, exactly as `new Fabricator(...).fabricate()`
18
+ * would.
19
+ *
20
+ * A Schema only, never a built Fabricator: given one, neither reusing it nor
21
+ * caching a fresh build of it is the obvious reading, so the type rejects it
22
+ * (`fabricate?: never` — a Fabricator otherwise matches `AnySchema`
23
+ * structurally), and the runtime throws `FabricateArgumentError` for it or for
24
+ * anything else that is not a Schema.
25
+ *
26
+ * Identity rather than structure on purpose: a schema can carry functions
27
+ * (`.as` producers, compute and derive resolvers, `T.opaque`) and `always`/
28
+ * `enum` hold arbitrary values, none of which has a sound structural equality.
29
+ */
30
+ export type Fabricate = <const $Schema extends AnySchema & {
31
+ readonly fabricate?: never;
32
+ }>(schema: $Schema) => Fabricated<$Schema>;
33
+ /**
34
+ * Every cached Fabricator of one lineage, keyed first by the `RandomSource`
35
+ * whose ordinal its build took, then by the schema it was built from. Both maps
36
+ * are weak: a per-test `wrap`'s source is released with its scope, and its
37
+ * entries with it.
38
+ */
39
+ export type FabricatorCache = WeakMap<RandomSource, WeakMap<AnySchema, NaiveFabricator<unknown>>>;
40
+ /**
41
+ * Bind `fabricate` to one instance — the same `(source, stack, ancestry)` its
42
+ * `construct` closes over — and to its lineage's shared `fabricatorCache`.
43
+ *
44
+ * **Keyed by source before schema.** The source is the one `resolveScope` would
45
+ * take an ordinal from (`toEffectiveSource`): the innermost visible `wrap`
46
+ * frame's, else this instance's. Keyed by schema alone, a module-level `User`
47
+ * fabricated in one test would carry its stream into the next, so a test's data
48
+ * would depend on which tests ran before it — the order-dependence each
49
+ * per-test `wrap` exists to remove. Keyed by source, every fresh scope starts
50
+ * empty.
51
+ *
52
+ * **Shared across the lineage, not held per instance.** Inside a `wrap`, the
53
+ * receiver and the wrap's own scope both resolve the frame's source, and must
54
+ * reach the same cached Fabricator — otherwise interleaving
55
+ * `instance.fabricate(S)` with `scope.fabricate(S)` would draw two separate
56
+ * sequences, where `new Fabricator` keeps the implicit and explicit routes in
57
+ * agreement (`test/Wrap.test.ts`). Two lineages never resolve the same source,
58
+ * so one map per lineage shares nothing between `initialize()` calls.
59
+ *
60
+ * The source is resolved and the build made in one synchronous call, so
61
+ * `construct` resolves the same frame this function keyed by.
62
+ */
63
+ export declare function Fabricate(construct: Constructor, source: RandomSource, stack: Stack, ancestry: Ancestry, fabricatorCache: FabricatorCache): Fabricate;
@@ -1,6 +1,6 @@
1
1
  import type { Adaptations, AdaptationsOf } from "../Adapter/Types";
2
2
  import type { Primitive, Kind as SchemaKind } from "../Primitive";
3
- import type { Algorithm, Trace } from "../Random/Types";
3
+ import type { Algorithm, RandomSource, Salt, Trace } from "../Random/Types";
4
4
  import type { Fabricated } from "../Schema/Types";
5
5
  import type { Adaptation, Kind, Meta, Produced, Produces } from "../Types";
6
6
  import type { PlainObject } from "../Utility/Types";
@@ -26,8 +26,17 @@ import type { PlainObject } from "../Utility/Types";
26
26
  *
27
27
  * `algorithm` rather than the `RandomSource` itself: stream derivation depends
28
28
  * on no per-source state, and a leaf has no business with
29
- * `toConstructionTrace`/`fork`. `clock` is not a field of its own — it is
30
- * always `trace.clock`.
29
+ * `toConstructionTrace`. `clock` is not a field of its own — it is always
30
+ * `trace.clock`.
31
+ *
32
+ * `fork` mints `T.recursive`'s private source, and is bound to this
33
+ * construction's _resolved_ algorithm and clock rather than the instance's: an
34
+ * active `wrap` frame's, or a pinned clock from a replayed {@link Trace}. A
35
+ * fork carries only its parent's algorithm and clock forward (its salt is the
36
+ * argument), so those two are all that make one fork differ from another, and
37
+ * the instance's own `source.fork` would silently give a recursive expansion
38
+ * the instance's "now" inside `wrap({ clock })`. An expansion rebinds it to its
39
+ * private source's `fork`, which carries the same pair.
31
40
  *
32
41
  * `self` is what makes `case "recursive.self"` resolve to "recurse one level
33
42
  * deeper, right now" — absent outside any active recursion, which is how `case
@@ -36,6 +45,7 @@ import type { PlainObject } from "../Utility/Types";
36
45
  export type ConstructionContext = {
37
46
  toTrace: (path: ReadonlyArray<string>, kind: string) => Trace;
38
47
  algorithm: Algorithm;
48
+ fork: (salt: Salt) => RandomSource;
39
49
  self?: (() => unknown) | undefined;
40
50
  };
41
51
  /**
@@ -52,12 +52,12 @@ import type { FabricatorTestContext, Integration } from "./Types";
52
52
  * running providers outside the frame it opened, and raises
53
53
  * `HarnessingProviderError` rather than quietly providing the base instance.
54
54
  *
55
- * Nothing here sets `clock`. A pinned `Date` (the recommended setup) and the
56
- * wall-clock default are already concrete numbers by the time `overlay()` sees
57
- * them, so they inherit through every `wrap` — the frame in effect's included:
58
- * salt varies per test, "now" does not. `clock: "derived"` is left alone on
59
- * purpose — that policy's documented meaning is that the salt _is_ the
60
- * reproducibility unit, so per-test clocks are the request honored, not a bug
61
- * to override.
55
+ * Nothing here sets `clock`. A pinned `Date` or number (the recommended setup)
56
+ * and the wall-clock default are already concrete numbers by the time
57
+ * `overlay()` sees them, so they inherit through every `wrap` — the frame in
58
+ * effect's included: salt varies per test, "now" does not. `clock: "derived"`
59
+ * is left alone on purpose — that policy's documented meaning is that the salt
60
+ * _is_ the reproducibility unit, so per-test clocks are the request honored,
61
+ * not a bug to override.
62
62
  */
63
63
  export declare function integration<$Registry extends PlainObject>(instance: Instance<$Registry>): Integration<FabricatorTestContext<$Registry>, Instance<$Registry>>;
@@ -1,3 +1,4 @@
1
+ import { type FabricatorCache } from "../Fabricator/Fabricate";
1
2
  import type { RandomSource } from "../Random/Types";
2
3
  import type { PlainObject } from "../Utility/Types";
3
4
  import type { Ancestry, Config, Instance, Overlay, Stack } from "./Types";
@@ -32,13 +33,15 @@ export declare const DEFAULT_COMBINATORIAL_LIMIT = 1024;
32
33
  * inherited, or defaulted), so a bad limit fails at `fork()`/`initialize()`
33
34
  * time rather than at first use. `clock` follows the given → inherited →
34
35
  * default shape `algorithm` does, but stays _unresolved_ only for the explicit
35
- * `"derived"` sentinel: an explicit `Date` and the unconfigured wall-clock
36
- * default are stored as epoch milliseconds (a stated instant, inherited as-is
37
- * from then on), while `"derived"` is left as the sentinel rather than
38
- * collapsed to a number, so `resolveClock` can re-derive it from whichever
39
- * `salt` is actually in effect at read time. An omitted `clock` on a
40
- * `fork`/`wrap` whose salt changed therefore keeps the parent's instant unless
41
- * that parent was itself `"derived"`.
36
+ * `"derived"` sentinel: an explicit `Date` or number and the unconfigured
37
+ * wall-clock default are stored as epoch milliseconds (a stated instant,
38
+ * inherited as-is from then on; an explicit one is checked by `resolveInstant`,
39
+ * so a `fork()`/`wrap()` rejects a bad clock as eagerly as `initialize()`
40
+ * does), while `"derived"` is left as the sentinel rather than collapsed to a
41
+ * number, so `resolveClock` can re-derive it from whichever `salt` is actually
42
+ * in effect at read time. An omitted `clock` on a `fork`/`wrap` whose salt
43
+ * changed therefore keeps the parent's instant unless that parent was itself
44
+ * `"derived"`.
42
45
  */
43
46
  export declare function overlay<$Registry extends PlainObject>(base: Partial<Config<PlainObject>>, over: Overlay<$Registry>): Config<$Registry>;
44
47
  /**
@@ -59,7 +62,10 @@ export declare function overlay<$Registry extends PlainObject>(base: Partial<Con
59
62
  *
60
63
  * `parent` describes the instance this one is derived from, and its absence is
61
64
  * the single marker of a root: `initialize` passes none, every `fork`/`wrap`
62
- * passes the receiver's.
65
+ * passes the receiver's. Its three fields always travel together: `ancestry`
66
+ * and `root` place this instance in its lineage, and `fabricatorCache` is the
67
+ * lineage's one `fabricate` cache, created here at the root and handed to every
68
+ * descendant (see `Fabricator/Fabricate.ts` for why it is shared).
63
69
  *
64
70
  * A fresh token is minted either way, so no two instances share an identity,
65
71
  * and the `ancestry` built here is _this_ instance's: the parent's plus one.
@@ -67,6 +73,7 @@ export declare function overlay<$Registry extends PlainObject>(base: Partial<Con
67
73
  export declare function instantiate<$Registry extends PlainObject>(config: Config<$Registry>, stack: Stack, parent?: {
68
74
  ancestry: Ancestry;
69
75
  root: Instance<PlainObject>;
76
+ fabricatorCache: FabricatorCache;
70
77
  }): {
71
78
  instance: Instance<$Registry>;
72
79
  source: RandomSource;
@@ -1,3 +1,4 @@
1
+ import type { RandomSource } from "../../Random/Types";
1
2
  import type { Ancestry, Frame, Stack } from "../Types";
2
3
  /**
3
4
  * The frames in `frames` that `ancestry` may resolve against, outermost first —
@@ -24,3 +25,12 @@ export declare function toVisible(frames: ReadonlyArray<Frame>, ancestry: Ancest
24
25
  * indexing `visible()` itself, so "innermost visible" has one definition.
25
26
  */
26
27
  export declare function toInnermostFrame(stack: Stack, ancestry: Ancestry): Frame | undefined;
28
+ /**
29
+ * The `RandomSource` a construction reached right now draws from: the innermost
30
+ * visible frame's, or `source` (the reader's own) outside any. One definition
31
+ * for every consumer that needs it — `resolveScope` takes its ordinal from it,
32
+ * `enumerables` derives its salts from it, and `fabricate` keys its cache by it
33
+ * — so the cache key and the source a cached build drew its ordinal from cannot
34
+ * disagree.
35
+ */
36
+ export declare function toEffectiveSource(source: RandomSource, stack: Stack, ancestry: Ancestry): RandomSource;
@@ -1,5 +1,6 @@
1
1
  import type { Enumerable, Limits } from "../Enumeration/Types";
2
2
  import type { Constructor } from "../Fabricator/Constructor";
3
+ import type { Fabricate } from "../Fabricator/Fabricate";
3
4
  import type { Algorithm, Layered, RandomSource, Salt } from "../Random/Types";
4
5
  import type { PlainObject } from "../Utility/Types";
5
6
  /**
@@ -13,8 +14,8 @@ import type { PlainObject } from "../Utility/Types";
13
14
  * milliseconds) or the unresolved `"derived"` policy — never collapsed to a
14
15
  * number by `overlay()` when `"derived"`, because that policy must re-derive
15
16
  * whenever the salt it composes changes (a `fork({ salt: layer(...) })`). The
16
- * unconfigured default is a wall- clock number, inherited as-is like an
17
- * explicit `Date`. `resolveClock` (`Instance/Core.ts`) is the one place that
17
+ * unconfigured default is a wall-clock number, inherited as-is like an explicit
18
+ * `Date` or number. `resolveClock` (`Instance/Core.ts`) is the one place that
18
19
  * resolves `"derived"` to a number, called fresh wherever the clock actually
19
20
  * matters (`instantiate`, the `context.clock` getter) rather than once here.
20
21
  */
@@ -33,11 +34,12 @@ export type Config<$Registry extends PlainObject> = {
33
34
  * (`[...base.salt, ...salt]`) — the shape a wrapping integration wants, and
34
35
  * what `ConstructorOptions`' layered form is for a single construction.
35
36
  * Omitting `salt` inherits the base's unchanged. `clock` similarly accepts the
36
- * caller-facing `Date | "derived"` rather than `Config`'s own resolved `number
37
- * | "derived"`, so a caller can hand in a literal instant without converting it
38
- * to epoch milliseconds themselves. `"derived"` is the explicit opt-in that
39
- * derives "now" from the instance salt; omitting `clock` at the root captures
40
- * wall-clock time instead.
37
+ * caller-facing `Date | number | "derived"` rather than `Config`'s own resolved
38
+ * `number | "derived"`, so a caller can hand in a literal instant without
39
+ * converting it to epoch milliseconds themselves, or hand back a logged
40
+ * `context.clock` without wrapping it in a `Date`. `"derived"` is the explicit
41
+ * opt-in that derives "now" from the instance salt; omitting `clock` at the
42
+ * root captures wall-clock time instead.
41
43
  *
42
44
  * `initialize`'s own parameter keeps a plain `salt?: Salt`, so passing
43
45
  * `layer(...)` there is a compile error: there is no base to layer onto at the
@@ -45,7 +47,7 @@ export type Config<$Registry extends PlainObject> = {
45
47
  */
46
48
  export type Overlay<$Registry extends PlainObject> = Partial<Omit<Config<$Registry>, "salt" | "clock">> & {
47
49
  readonly salt?: Salt | Layered;
48
- readonly clock?: Date | "derived" | undefined;
50
+ readonly clock?: Date | number | "derived" | undefined;
49
51
  };
50
52
  declare const Brand: unique symbol;
51
53
  /**
@@ -256,6 +258,19 @@ export interface Instance<$Registry extends PlainObject> extends Pick<RandomSour
256
258
  * it.
257
259
  */
258
260
  Fabricator: Constructor;
261
+ /**
262
+ * `new Fabricator(schema).fabricate()` in one call. The first call with a
263
+ * schema builds; every later call with the same schema object continues that
264
+ * Fabricator, taking no new construction ordinal — so it is safe in a loop.
265
+ *
266
+ * The cache follows the scope in effect, like `new Fabricator` does: inside a
267
+ * `wrap` this instance can see, the frame's source is used and its entries
268
+ * are its own, so each per-test scope starts fresh. The key is identity: hold
269
+ * an overridden or configured schema in a variable to reuse it. Writing
270
+ * `.override(...)` or `.whereby(...)` inline at the call site makes a new
271
+ * schema, and a new build, on every call. See `Fabricator/Fabricate.ts`.
272
+ */
273
+ fabricate: Fabricate;
259
274
  /**
260
275
  * Every combination of every enumerable node in `schema` — every enum member,
261
276
  * both sides of an optional field, and so on — as a cartesian product,
@@ -280,13 +295,13 @@ export interface Instance<$Registry extends PlainObject> extends Pick<RandomSour
280
295
  fork<const $ForkRegistry extends PlainObject = $Registry>(overlay?: Overlay<$ForkRegistry>): Instance<$ForkRegistry>;
281
296
  /**
282
297
  * `fork(overlay)`, made ambient for the synchronous extent of `block`: every
283
- * `new Fabricator(...)`, `combinatorial(...)`, and `coverage(...)` reached
284
- * inside — on this instance, and on this instance's ancestors — resolves
285
- * against the fork instead, with nothing threaded through. The fork is also
286
- * passed to `block`: use it explicitly where that reads better, and
287
- * _necessarily_ for any async work, which the ambient frame does not survive
288
- * — a build reached after an `await` inside `block` sees this instance's own
289
- * configuration again, not the wrap's.
298
+ * `new Fabricator(...)`, `fabricate(...)`, `combinatorial(...)`, and
299
+ * `coverage(...)` reached inside — on this instance, and on this instance's
300
+ * ancestors — resolves against the fork instead, with nothing threaded
301
+ * through. The fork is also passed to `block`: use it explicitly where that
302
+ * reads better, and _necessarily_ for any async work, which the ambient frame
303
+ * does not survive — a build reached after an `await` inside `block` sees
304
+ * this instance's own configuration again, not the wrap's.
290
305
  *
291
306
  * The overlay lays over _this instance's_ config, exactly as `fork`'s does,
292
307
  * whether or not a frame is already open. So a nested `wrap` accumulates when
@@ -1,4 +1,9 @@
1
1
  import type { Adaptations } from "../../Adapter/Types";
2
2
  import { Schema } from "./Schema";
3
- declare const registry: Schema<{}, Adaptations>;
3
+ /**
4
+ * A function, not the Schema itself: `Schema/Registry.ts` installs it as the
5
+ * `T.boolean` getter, so every read is a distinct Schema — see AGENTS.md's
6
+ * "Registry entries are getters."
7
+ */
8
+ declare function registry(): Schema<{}, Adaptations>;
4
9
  export default registry;
@@ -0,0 +1,11 @@
1
+ import type { Bound } from "../../Bound";
2
+ /**
3
+ * Inclusive epoch-millisecond caps that a missing `whereby` end draws against —
4
+ * the whole representable `Date` range. Not stored on `[Meta]`: an omitted end
5
+ * stays omitted, and adapters forward only the ends that were named. `past` and
6
+ * `future` fill their one open end from here too.
7
+ */
8
+ export declare const unboundedEpoch: {
9
+ min: Bound<number>;
10
+ max: Bound<number>;
11
+ };
@@ -2,17 +2,15 @@ import type { Adaptations } from "../../Adapter/Types";
2
2
  import { type InputBound } from "../../Bound";
3
3
  import { type Distribution } from "../../Distribution";
4
4
  import { Schema } from "./Schema";
5
- import type { Whereby } from "./Types";
5
+ import type { InputWhereby, Whereby } from "./Types";
6
6
  type ThisRegistry = Schema<{}, Adaptations> & {
7
7
  /**
8
- * A `Date` drawn from `[min, max]`. Pass a `distribution` to shape how values
9
- * cluster within the range; without one, every instant is equally likely.
8
+ * A `Date` drawn from `[min, max]`. Either end may be omitted: `min` defaults
9
+ * to the earliest representable instant and `max` to the latest. Pass a
10
+ * `distribution` to shape how values cluster within the range; without one,
11
+ * every instant is equally likely.
10
12
  */
11
- whereby: (whereby: {
12
- min: InputBound<Date>;
13
- max: InputBound<Date>;
14
- distribution?: Distribution | undefined;
15
- }) => Schema<{
13
+ whereby: (whereby: InputWhereby) => Schema<{
16
14
  whereby: Whereby;
17
15
  }>;
18
16
  /**
@@ -55,5 +53,11 @@ type ThisRegistry = Schema<{}, Adaptations> & {
55
53
  }>;
56
54
  };
57
55
  };
58
- declare const registry: ThisRegistry;
56
+ /**
57
+ * A function, not the Schema itself: `Schema/Registry.ts` installs it as the
58
+ * `T.date` getter, so every read is a distinct Schema. `past` and `future` are
59
+ * getters for the same reason — see AGENTS.md's "Registry entries are
60
+ * getters."
61
+ */
62
+ declare function registry(): ThisRegistry;
59
63
  export default registry;
@@ -3,11 +3,21 @@ import type { Bound, InputBound } from "../../Bound";
3
3
  import type { Distribution } from "../../Distribution";
4
4
  import type { Produce } from "../../Random/Types";
5
5
  import type { Adaptation, Kind, Meta, Produced, Produces } from "../../Types";
6
+ /**
7
+ * Call-site `{ min, max }` — scalars are inclusive. Either end may be omitted;
8
+ * a missing `min` is the earliest representable instant and a missing `max` the
9
+ * latest, the same span as a bare `T.date`.
10
+ */
6
11
  export type InputWhereby = {
7
12
  min?: InputBound<Date> | undefined;
8
13
  max?: InputBound<Date> | undefined;
9
14
  distribution?: Distribution | undefined;
10
15
  };
16
+ /**
17
+ * Stored `{ min, max }` — each present end is a canonical {@link Bound}. An
18
+ * omitted end stays omitted (fabricate fills `Defaults.ts`'s `unboundedEpoch`;
19
+ * adapters forward only the ends that were named).
20
+ */
11
21
  export type Whereby = {
12
22
  min?: Bound<Date> | undefined;
13
23
  max?: Bound<Date> | undefined;
@@ -13,8 +13,10 @@ export { default as nullable } from "./nullable";
13
13
  export { default as nullish } from "./nullish";
14
14
  export { default as number } from "./number";
15
15
  export { default as object } from "./object";
16
+ export { default as omit } from "./object/omit";
16
17
  export { default as omittable } from "./object/omittable";
17
18
  export { default as optional } from "./object/optional";
19
+ export { default as pick } from "./object/pick";
18
20
  export { default as opaque } from "./opaque";
19
21
  export { default as record } from "./record";
20
22
  export { default as recursive } from "./recursive";
@@ -1,3 +1,8 @@
1
1
  import { Schema } from "./Schema";
2
- declare const registry: Schema;
2
+ /**
3
+ * A function, not the Schema itself: `Schema/Registry.ts` installs it as the
4
+ * `T.null` getter, so every read is a distinct Schema — see AGENTS.md's
5
+ * "Registry entries are getters."
6
+ */
7
+ declare function registry(): Schema;
3
8
  export default registry;
@@ -30,5 +30,12 @@ type ThisRegistry = Schema<{}, Adaptations> & {
30
30
  big: typeof bigint;
31
31
  };
32
32
  };
33
- declare const registry: ThisRegistry;
33
+ /**
34
+ * A function, not the Schema itself: `Schema/Registry.ts` installs it as the
35
+ * `T.number` getter, so every read is a distinct Schema. `integer` and
36
+ * `integer.sequence` are getters for the same reason; `big` is a builder, not a
37
+ * Schema, so it stays a plain property — see AGENTS.md's "Registry entries are
38
+ * getters."
39
+ */
40
+ declare function registry(): ThisRegistry;
34
41
  export default registry;
@@ -48,9 +48,17 @@ export type Fields = Record<string, BaseFabricator<unknown>>;
48
48
  * A compute-kind field (from `.refine()`) needs the rest of the object already
49
49
  * fabricated (`object/compute/Fabricator.ts`), which isn't available until
50
50
  * every ordinary field has resolved. Two phases: ordinary fields first, then
51
- * compute fields against the accumulated result, in definition order (a compute
52
- * field can see an earlier compute field's value, not a later one) — unless
53
- * covered by `overrides`, in which case it resolves in phase 1 like any other
54
- * overridden field.
51
+ * compute fields against the accumulated result, in dependency order — each
52
+ * after every compute field among its `dependencies` (`compute/Types.ts`) —
53
+ * unless covered by `overrides`, in which case it resolves in phase 1 like any
54
+ * other overridden field. Dependency order rather than definition order is what
55
+ * lets `hidden` live in its own map: a hidden compute field can sit between two
56
+ * visible ones in the chain, and no fixed visible/hidden order resolves that.
57
+ *
58
+ * `hidden` is `[Meta].hidden` built (`Types.ts`'s `Meta`): fabricated in both
59
+ * phases exactly like `fields`, so compute fields can read them, then deleted
60
+ * before returning. Per-call `overrides` only reach `fields` — `.override()`
61
+ * rejects a hidden key, and `{ validate: false }` must not let one through.
62
+ * `[Children]` stays `fields` alone, so enumeration never pins a hidden field.
55
63
  */
56
- export declare function Fabricator<$Definition extends Definition>(context: FabricatorContext<Schema<$Definition>>, fields: Fields): Fabricator<Schema<$Definition>>;
64
+ export declare function Fabricator<$Definition extends Definition>(context: FabricatorContext<Schema<$Definition>>, fields: Fields, hidden?: Fields): Fabricator<Schema<$Definition>>;
@@ -1,7 +1,7 @@
1
1
  import type { Adaptations } from "../../Adapter/Types";
2
2
  import { Adaptation, Meta } from "../../Types";
3
3
  import { Schema } from "./Schema";
4
- import type { Definition, Meta as ThisMeta } from "./Types";
4
+ import type { Definition, Subsettable, Meta as ThisMeta } from "./Types";
5
5
  /**
6
6
  * Rebuild a full `object` Schema — with `extend`/`refine` restored — from
7
7
  * anything already reduced to this kind's `[Meta]` (a bare Schema, or a built
@@ -19,5 +19,21 @@ export declare function rehydrate<$Definition extends Definition, $Adaptations e
19
19
  [Meta]: ThisMeta<$Definition>;
20
20
  readonly [Adaptation]?: $Adaptations;
21
21
  }): Schema<$Definition, $Adaptations>;
22
+ /**
23
+ * Shared body of `T.pick`/`T.omit` (`pick/Registry.ts`, `omit/Registry.ts`),
24
+ * kept here because it rebuilds through `make`. A pure Schema → Schema
25
+ * transform, like `.override()`: the result is an ordinary `object` Schema over
26
+ * the kept fields, in source order. A dependency of a kept compute field that
27
+ * is not itself kept moves to `[Meta].hidden` — fabricated, so the resolver can
28
+ * read it, but never emitted. A dropped field nothing depends on is gone
29
+ * entirely.
30
+ *
31
+ * The source's own `produce` (`.as(...)`) and whole-object `[Adaptation]` are
32
+ * not carried: both describe the source's full shape, not this one. Field
33
+ * entries are reused as they are, so a kept or hidden field's own adaptation
34
+ * and `[Fixed]` override come along. `refinements` is filtered down to the kept
35
+ * fields.
36
+ */
37
+ export declare function subset(source: Subsettable, keys: ReadonlyArray<string>, operation: "pick" | "omit"): Schema<any>;
22
38
  declare const _default: <const $Definition extends Definition>(definition: $Definition) => Schema<$Definition>;
23
39
  export default _default;
@@ -67,12 +67,31 @@ export type Override<$Definition extends Definition> = Pretty<{
67
67
  * `extend`/`refine`/`override` and `ToTypeBox`'s structural derivation keep
68
68
  * working, and a prior definition survives `as` for future validation of
69
69
  * `produce`.
70
+ *
71
+ * `hidden` holds fields that are fabricated but never emitted: the dependencies
72
+ * of a kept compute field that `T.pick`/`T.omit` (`Registry.ts`) dropped from
73
+ * `definition`. Absent when there are none. It sits outside `definition` so
74
+ * that everything reading `definition` — the `Fabricated`/`Override` types,
75
+ * `.override()`'s key check, `[Children]` (and so enumeration), and every
76
+ * adapter — never sees a hidden field. Only `Constructor.ts`'s `make`,
77
+ * `Fabricator.ts`'s `fabricate`, and `recursive/Terminate.ts` read it.
70
78
  */
71
79
  export type Meta<$Definition extends Definition = Definition> = {
72
80
  definition: $Definition;
73
81
  refinements: Refinements;
74
82
  produce?: Produce<Fabricated<$Definition>>;
83
+ hidden?: Definition;
84
+ };
85
+ /**
86
+ * What `T.pick`/`T.omit` accept: an `object` Schema or a built `object`
87
+ * Fabricator — anything already carrying this kind's `[Meta]`, the same input
88
+ * `Registry.ts`'s `rehydrate` takes.
89
+ */
90
+ export type Subsettable = {
91
+ readonly [Kind]: "object";
92
+ readonly [Meta]: Meta<any>;
75
93
  };
94
+ export type DefinitionOf<$Source extends Subsettable> = $Source[typeof Meta]["definition"];
76
95
  export interface Core<$Definition extends Definition = Definition, $Adaptations extends Adaptations = {}> {
77
96
  [Kind]: "object";
78
97
  [Meta]: Meta<$Definition>;
@@ -2,17 +2,13 @@ import type { Adaptations } from "../../../Adapter/Types";
2
2
  import type { Fabricator as BaseFabricator, FabricatorContext } from "../../../Fabricator/Types";
3
3
  import type { Trace } from "../../../Random/Types";
4
4
  import { Kind, Meta, type Adaptation } from "../../../Types";
5
+ import { type PlainObject } from "../../../Utility/Types";
5
6
  import type { Schema } from "./Schema";
6
- import type { Resolved, Source } from "./Types";
7
+ import type { Resolved, Source, Meta as ThisMeta } from "./Types";
7
8
  export type Fabrication<$Fabricator extends Fabricator<any, Source>> = $Fabricator extends Fabricator<any, infer $Source> ? Resolved<$Source> : never;
8
9
  export type Fabricator<$Fabricated, $Source extends Source, $Adaptations extends Adaptations = {}> = {
9
10
  [Kind]: "object.compute";
10
- [Meta]: {
11
- source: $Source;
12
- resolve: (params: {
13
- fabricated: $Fabricated;
14
- }) => Resolved<$Source>;
15
- };
11
+ [Meta]: ThisMeta<$Fabricated, $Source>;
16
12
  readonly trace: Trace;
17
13
  readonly [Adaptation]?: $Adaptations;
18
14
  fabricate: (params?: {
@@ -26,5 +22,10 @@ export declare function isObjectComputeFabricator(candidate: BaseFabricator<unkn
26
22
  * comes entirely from `resolve`, given the rest of the object. The node still
27
23
  * records `trace` so it can be rebuilt from a parent field's captured trace;
28
24
  * `.fabricate()` without the parent object throws `DetachedComputeError`.
25
+ *
26
+ * The parent hands over everything it has fabricated so far; a `narrowed` field
27
+ * (`.from([...])`) passes its resolver only its `dependencies`, and only those
28
+ * present, so an omitted dependency stays absent rather than becoming
29
+ * `undefined`. Narrowing here keeps `object/Fabricator.ts` unaware of it.
29
30
  */
30
- export declare function Fabricator<$Fabricated, $Source extends Source>(context: FabricatorContext<Schema<$Fabricated, $Source>>): Fabricator<$Fabricated, $Source>;
31
+ export declare function Fabricator<$Fabricated extends PlainObject, $Source extends Source>(context: FabricatorContext<Schema<$Fabricated, $Source>>): Fabricator<$Fabricated, $Source>;
@@ -1,4 +1,10 @@
1
1
  import type { Definition } from "../Types";
2
2
  import { type Computer } from "./Schema";
3
- declare function make<$Definition extends Definition>(): Computer<$Definition>;
3
+ /**
4
+ * `base` is the keys of the `.refine()` stage's base definition — what a plain
5
+ * `.as` resolver depends on, and what `.from([...])` may name. Checked at
6
+ * runtime as well as by type, since a cast or a built Fabricator's widened type
7
+ * can reach `.from` with a key the base never had.
8
+ */
9
+ declare function make<$Definition extends Definition>(base: ReadonlyArray<string>): Computer<$Definition>;
4
10
  export default make;
@@ -2,12 +2,32 @@ import { type AdaptationEntry } from "../../../Adapter/Core";
2
2
  import type { Adaptations, Adapter, Adapting, WithAdaptations } from "../../../Adapter/Types";
3
3
  import type { AnySchema } from "../../../Schema/Types";
4
4
  import { type SatisfiesThis } from "../../../Schema/Satisfies";
5
+ import type { Pretty } from "../../../Utility/Types";
5
6
  import type * as object from "../Types";
6
7
  import type { Core, Resolved, Source } from "./Types";
8
+ /**
9
+ * The fields a `.from([...])` resolver is handed: only the named ones, each
10
+ * keeping its own `?:` (an omittable or optional dependency may be absent).
11
+ */
12
+ export type Narrowed<$Definition extends object.Definition, $Keys extends keyof $Definition> = Pretty<Pick<object.Fabricated<$Definition>, $Keys & keyof object.Fabricated<$Definition>>>;
7
13
  export type Computer<$Definition extends object.Definition> = <const $Source extends Source>(source: $Source) => {
14
+ /**
15
+ * Resolve against the whole object fabricated so far. The field depends on
16
+ * every field of this `.refine()` stage's base, so `T.pick`/`T.omit` keep all
17
+ * of them fabricated when this field is kept.
18
+ */
8
19
  as: (resolve: (params: {
9
20
  fabricated: object.Fabricated<$Definition>;
10
21
  }) => NoInfer<Resolved<$Source>>) => Schema<object.Fabricated<$Definition>, $Source>;
22
+ /**
23
+ * Declare the fields this one reads. The resolver is handed only those, and
24
+ * they are all `T.pick`/`T.omit` keep fabricated when this field is kept.
25
+ */
26
+ from: <const $Keys extends ReadonlyArray<keyof $Definition & string>>(keys: $Keys) => {
27
+ as: (resolve: (params: {
28
+ fabricated: Narrowed<$Definition, $Keys[number]>;
29
+ }) => NoInfer<Resolved<$Source>>) => Schema<Narrowed<$Definition, $Keys[number]>, $Source>;
30
+ };
11
31
  };
12
32
  export interface Schema<$Fabricated, $Source extends Source, $Adaptations extends Adaptations = {}> extends Core<$Fabricated, $Source, $Adaptations> {
13
33
  /**
@@ -39,12 +39,22 @@ export type Resolved<$Source, $Bindings extends unknown[] = []> = FabricatedBy<D
39
39
  * Unlike every other kind's `Meta`, this one is generic over the _enclosing
40
40
  * object's_ fabricated type as well as the source — that is what the resolver
41
41
  * is handed.
42
+ *
43
+ * `dependencies` is always present, so every compute field has a known set of
44
+ * fields it reads: the keys named by `.from([...])`, or, without one, every key
45
+ * of the `.refine()` stage's base — exactly what the resolver's type lets it
46
+ * read. `object/Fabricator.ts` resolves compute fields in dependency order from
47
+ * it, and `T.pick`/`T.omit` (`object/Registry.ts`) keep exactly those fields
48
+ * fabricated. `narrowed` is whether the resolver is handed only its
49
+ * `dependencies` (from `.from`) or the whole object fabricated so far.
42
50
  */
43
51
  export type Meta<$Fabricated, $Source extends Source> = {
44
52
  source: $Source;
45
53
  resolve: (params: {
46
54
  fabricated: $Fabricated;
47
55
  }) => Resolved<$Source>;
56
+ dependencies: ReadonlyArray<string>;
57
+ narrowed: boolean;
48
58
  };
49
59
  export interface Core<$Fabricated, $Source extends Source, $Adaptations extends Adaptations = {}> {
50
60
  [Kind]: "object.compute";
@@ -0,0 +1,7 @@
1
+ import type { Schema } from "../Schema";
2
+ import type { DefinitionOf, Subsettable } from "../Types";
3
+ /**
4
+ * `T.omit(source, keys)`: an `object` Schema without `keys`. `T.pick`'s
5
+ * inverse, and not a kind either — see `subset` in `object/Registry.ts`.
6
+ */
7
+ export default function omit<$Source extends Subsettable, const $Keys extends ReadonlyArray<keyof DefinitionOf<$Source> & string>>(source: $Source, keys: $Keys): Schema<Omit<DefinitionOf<$Source>, $Keys[number]>>;
@@ -0,0 +1,2 @@
1
+ export * from "./Registry";
2
+ export { default } from "./Registry";
@@ -0,0 +1,8 @@
1
+ import type { Schema } from "../Schema";
2
+ import type { DefinitionOf, Subsettable } from "../Types";
3
+ /**
4
+ * `T.pick(source, keys)`: an `object` Schema with only `keys`, in source order.
5
+ * Not a kind — the result is an ordinary `object` Schema. See `subset` in
6
+ * `object/Registry.ts` for what is kept, hidden, and dropped.
7
+ */
8
+ export default function pick<$Source extends Subsettable, const $Keys extends ReadonlyArray<keyof DefinitionOf<$Source> & string>>(source: $Source, keys: $Keys): Schema<Pick<DefinitionOf<$Source>, $Keys[number]>>;
@@ -0,0 +1,2 @@
1
+ export * from "./Registry";
2
+ export { default } from "./Registry";