@ghostry/fabricator 0.0.11 → 0.0.12

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 (49) hide show
  1. package/dist/esm/Enumeration/Enumerate.js +2 -4
  2. package/dist/esm/Error/index.js +34 -6
  3. package/dist/esm/Fabricator/Constructor.js +40 -33
  4. package/dist/esm/Fabricator/Fabricate.js +28 -0
  5. package/dist/esm/Instance/Core.js +14 -2
  6. package/dist/esm/Instance/Stack/Visible.js +6 -1
  7. package/dist/esm/Primitive/date/Defaults.js +12 -0
  8. package/dist/esm/Primitive/date/Fabricator.js +5 -10
  9. package/dist/esm/Primitive/date/Registry.js +8 -4
  10. package/dist/esm/Primitive/index.js +2 -0
  11. package/dist/esm/Primitive/number/Fabricator.js +1 -1
  12. package/dist/esm/Primitive/number/Registry.js +1 -1
  13. package/dist/esm/Primitive/object/Fabricator.js +33 -11
  14. package/dist/esm/Primitive/object/Registry.js +90 -10
  15. package/dist/esm/Primitive/object/compute/Fabricator.js +10 -3
  16. package/dist/esm/Primitive/object/compute/Registry.js +20 -3
  17. package/dist/esm/Primitive/object/omit/Registry.js +5 -0
  18. package/dist/esm/Primitive/object/omit/index.js +2 -0
  19. package/dist/esm/Primitive/object/pick/Registry.js +5 -0
  20. package/dist/esm/Primitive/object/pick/index.js +2 -0
  21. package/dist/esm/Primitive/recursive/Fabricator.js +1 -0
  22. package/dist/esm/Primitive/recursive/Terminate.js +21 -9
  23. package/dist/types/Error/index.d.ts +71 -6
  24. package/dist/types/Fabricator/Fabricate.d.ts +61 -0
  25. package/dist/types/Fabricator/Types.d.ts +13 -3
  26. package/dist/types/Harnessing/Core.d.ts +7 -7
  27. package/dist/types/Instance/Core.d.ts +15 -8
  28. package/dist/types/Instance/Stack/Visible.d.ts +10 -0
  29. package/dist/types/Instance/Types.d.ts +30 -15
  30. package/dist/types/Primitive/date/Defaults.d.ts +11 -0
  31. package/dist/types/Primitive/date/Registry.d.ts +6 -8
  32. package/dist/types/Primitive/date/Types.d.ts +10 -0
  33. package/dist/types/Primitive/index.d.ts +2 -0
  34. package/dist/types/Primitive/object/Fabricator.d.ts +13 -5
  35. package/dist/types/Primitive/object/Registry.d.ts +17 -1
  36. package/dist/types/Primitive/object/Types.d.ts +19 -0
  37. package/dist/types/Primitive/object/compute/Fabricator.d.ts +9 -8
  38. package/dist/types/Primitive/object/compute/Registry.d.ts +7 -1
  39. package/dist/types/Primitive/object/compute/Schema.d.ts +20 -0
  40. package/dist/types/Primitive/object/compute/Types.d.ts +10 -0
  41. package/dist/types/Primitive/object/omit/Registry.d.ts +7 -0
  42. package/dist/types/Primitive/object/omit/index.d.ts +2 -0
  43. package/dist/types/Primitive/object/pick/Registry.d.ts +8 -0
  44. package/dist/types/Primitive/object/pick/index.d.ts +2 -0
  45. package/dist/types/Primitive/recursive/Fabricator.d.ts +9 -7
  46. package/dist/types/index.d.ts +23 -10
  47. package/package.json +3 -3
  48. /package/dist/esm/Primitive/number/{defaults.js → Defaults.js} +0 -0
  49. /package/dist/types/Primitive/number/{defaults.d.ts → Defaults.d.ts} +0 -0
@@ -1,14 +1,31 @@
1
+ import { FabricatorError } from "../../../Error/index.js";
1
2
  import { Kind, Meta } from "../../../Types.js";
2
3
  import { Schema } from "./Schema.js";
3
- function make() {
4
+ function make(base) {
4
5
  return (source)=>({
5
6
  as: (resolve)=>Schema({
6
7
  [Kind]: "object.compute",
7
8
  [Meta]: {
8
9
  source,
9
- resolve
10
+ resolve,
11
+ dependencies: base,
12
+ narrowed: false
10
13
  }
11
- })
14
+ }),
15
+ from: (keys)=>{
16
+ for (const key of keys)if (!base.includes(key)) throw new FabricatorError.UnknownFieldError(key, base, "compute from");
17
+ return {
18
+ as: (resolve)=>Schema({
19
+ [Kind]: "object.compute",
20
+ [Meta]: {
21
+ source,
22
+ resolve,
23
+ dependencies: keys,
24
+ narrowed: true
25
+ }
26
+ })
27
+ };
28
+ }
12
29
  });
13
30
  }
14
31
  const Registry = make;
@@ -0,0 +1,5 @@
1
+ import { subset } from "../Registry.js";
2
+ function omit(source, keys) {
3
+ return subset(source, keys, "omit");
4
+ }
5
+ export default omit;
@@ -0,0 +1,2 @@
1
+ export * from "./Registry.js";
2
+ export { default } from "./Registry.js";
@@ -0,0 +1,5 @@
1
+ import { subset } from "../Registry.js";
2
+ function pick(source, keys) {
3
+ return subset(source, keys, "pick");
4
+ }
5
+ export default pick;
@@ -0,0 +1,2 @@
1
+ export * from "./Registry.js";
2
+ export { default } from "./Registry.js";
@@ -18,6 +18,7 @@ function Fabricator(context, forkSource, make) {
18
18
  kind
19
19
  }),
20
20
  algorithm,
21
+ fork: privateSource.fork,
21
22
  self: atMax ? void 0 : ()=>fabricateAt(depth + 1)
22
23
  };
23
24
  return make(target, [], context).fabricate();
@@ -58,15 +58,24 @@ function terminateAt(schema, path) {
58
58
  case "object":
59
59
  {
60
60
  const s = schema;
61
- const definition = s[Meta].definition;
62
- const next = {};
63
- for (const key of Object.keys(definition))next[key] = terminateAt(definition[key], [
64
- ...path,
65
- key
66
- ]);
61
+ const terminateFields = (definition)=>{
62
+ const next = {};
63
+ for (const key of Object.keys(definition))next[key] = terminateAt(definition[key], [
64
+ ...path,
65
+ key
66
+ ]);
67
+ return next;
68
+ };
69
+ const definition = terminateFields(s[Meta].definition);
70
+ if (!s[Meta].hidden) return withMeta(s, {
71
+ ...s[Meta],
72
+ definition
73
+ });
74
+ const hidden = terminateFields(s[Meta].hidden);
67
75
  return withMeta(s, {
68
76
  ...s[Meta],
69
- definition: next
77
+ definition,
78
+ hidden
70
79
  });
71
80
  }
72
81
  case "tuple":
@@ -168,8 +177,11 @@ function containsSelf(schema) {
168
177
  case "object":
169
178
  {
170
179
  const s = schema;
171
- const definition = s[Meta].definition;
172
- return Object.keys(definition).some((key)=>containsSelf(definition[key]));
180
+ const all = {
181
+ ...s[Meta].hidden,
182
+ ...s[Meta].definition
183
+ };
184
+ return Object.keys(all).some((key)=>containsSelf(all[key]));
173
185
  }
174
186
  case "tuple":
175
187
  {
@@ -45,6 +45,24 @@ export declare namespace FabricatorError {
45
45
  */
46
46
  limit: unknown);
47
47
  }
48
+ /**
49
+ * `initialize({ clock })`, `fork({ clock })`, or `wrap({ clock }, …)` given
50
+ * an instant a `Date` cannot hold exactly — a fractional or non-finite
51
+ * number, one past ±8.64e15, or an invalid `Date`. Rejected rather than
52
+ * adjusted the way `Date`'s own `TimeClip` would, so the clock a run records
53
+ * is the clock the caller passed.
54
+ */
55
+ class InvalidClockError extends FabricatorError {
56
+ /**
57
+ * The rejected clock, as given — a number or a `Date`.
58
+ */
59
+ readonly clock: unknown;
60
+ constructor(
61
+ /**
62
+ * The rejected clock, as given — a number or a `Date`.
63
+ */
64
+ clock: unknown);
65
+ }
48
66
  /**
49
67
  * A `self` placeholder resolved with no `T.recursive` expanding around it —
50
68
  * only reachable by holding a `self` reference outside the `T.recursive(...)`
@@ -213,27 +231,57 @@ export declare namespace FabricatorError {
213
231
  value: unknown);
214
232
  }
215
233
  /**
216
- * An override names a field the object schema does not define — most often a
217
- * typo, which is why the known fields are listed.
234
+ * A key names a field the object schema does not define — most often a typo,
235
+ * which is why the known fields are listed. One failure reached from four
236
+ * places: `.override()`, `T.pick`, `T.omit`, and a compute field's
237
+ * `.from([...])`, told apart by `operation`.
218
238
  */
219
- class UnknownOverrideFieldError extends FabricatorError {
239
+ class UnknownFieldError extends FabricatorError {
220
240
  /**
221
241
  * The name that was not found.
222
242
  */
223
243
  readonly field: string;
224
244
  /**
225
- * Every field the schema does define, in definition order.
245
+ * Every field the schema does define, in definition order. For `"compute
246
+ * from"`, the fields the enclosing `.refine()` stage can read.
226
247
  */
227
248
  readonly available: ReadonlyArray<string>;
249
+ /**
250
+ * What named the unknown field, worded to read as the message's verb.
251
+ */
252
+ readonly operation: "override" | "pick" | "omit" | "compute from";
228
253
  constructor(
229
254
  /**
230
255
  * The name that was not found.
231
256
  */
232
257
  field: string,
233
258
  /**
234
- * Every field the schema does define, in definition order.
259
+ * Every field the schema does define, in definition order. For `"compute
260
+ * from"`, the fields the enclosing `.refine()` stage can read.
261
+ */
262
+ available: ReadonlyArray<string>,
263
+ /**
264
+ * What named the unknown field, worded to read as the message's verb.
265
+ */
266
+ operation: "override" | "pick" | "omit" | "compute from");
267
+ }
268
+ /**
269
+ * Compute fields whose declared dependencies form a loop, so none of them can
270
+ * resolve first. A compute field only names fields that already exist, but a
271
+ * later `.refine()` or `.extend()` can replace one of those with a compute
272
+ * field that reads it back. Thrown by that call, while building the schema,
273
+ * never at fabrication.
274
+ */
275
+ class ComputeDependencyCycleError extends FabricatorError {
276
+ /**
277
+ * The compute fields on the loop, in the order they were reached.
235
278
  */
236
- available: ReadonlyArray<string>);
279
+ readonly fields: ReadonlyArray<string>;
280
+ constructor(
281
+ /**
282
+ * The compute fields on the loop, in the order they were reached.
283
+ */
284
+ fields: ReadonlyArray<string>);
237
285
  }
238
286
  /**
239
287
  * An override value does not fit the field it is meant to replace. Raised for
@@ -548,6 +596,23 @@ export declare namespace FabricatorError {
548
596
  */
549
597
  given: string);
550
598
  }
599
+ /**
600
+ * `fabricate(...)` handed anything but a Schema: a built Fabricator, a bare
601
+ * builder that still needs configuring (`T.array(x)`, `T.recursive(f)`), or a
602
+ * value that is no schema at all. Its type already rejects each; this is the
603
+ * runtime guard for an untyped caller.
604
+ */
605
+ class FabricateArgumentError extends FabricatorError {
606
+ /**
607
+ * What `fabricate(...)` was handed.
608
+ */
609
+ readonly argument: unknown;
610
+ constructor(
611
+ /**
612
+ * What `fabricate(...)` was handed.
613
+ */
614
+ argument: unknown);
615
+ }
551
616
  /**
552
617
  * `wrap(overlay, block)` handed an `async` block while the lineage's ambient
553
618
  * carrier is the synchronous one (`Instance/Stack/Sync.ts`).
@@ -0,0 +1,61 @@
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(...)` — is a new object on every call, so every call builds and
16
+ * takes an ordinal, exactly as `new Fabricator(...).fabricate()` would.
17
+ *
18
+ * A Schema only, never a built Fabricator: given one, neither reusing it nor
19
+ * caching a fresh build of it is the obvious reading, so the type rejects it
20
+ * (`fabricate?: never` — a Fabricator otherwise matches `AnySchema`
21
+ * structurally), and the runtime throws `FabricateArgumentError` for it or for
22
+ * anything else that is not a Schema.
23
+ *
24
+ * Identity rather than structure on purpose: a schema can carry functions
25
+ * (`.as` producers, compute and derive resolvers, `T.opaque`) and `always`/
26
+ * `enum` hold arbitrary values, none of which has a sound structural equality.
27
+ */
28
+ export type Fabricate = <const $Schema extends AnySchema & {
29
+ readonly fabricate?: never;
30
+ }>(schema: $Schema) => Fabricated<$Schema>;
31
+ /**
32
+ * Every cached Fabricator of one lineage, keyed first by the `RandomSource`
33
+ * whose ordinal its build took, then by the schema it was built from. Both maps
34
+ * are weak: a per-test `wrap`'s source is released with its scope, and its
35
+ * entries with it.
36
+ */
37
+ export type FabricatorCache = WeakMap<RandomSource, WeakMap<AnySchema, NaiveFabricator<unknown>>>;
38
+ /**
39
+ * Bind `fabricate` to one instance — the same `(source, stack, ancestry)` its
40
+ * `construct` closes over — and to its lineage's shared `fabricatorCache`.
41
+ *
42
+ * **Keyed by source before schema.** The source is the one `resolveScope` would
43
+ * take an ordinal from (`toEffectiveSource`): the innermost visible `wrap`
44
+ * frame's, else this instance's. Keyed by schema alone, a module-level `User`
45
+ * fabricated in one test would carry its stream into the next, so a test's data
46
+ * would depend on which tests ran before it — the order-dependence each
47
+ * per-test `wrap` exists to remove. Keyed by source, every fresh scope starts
48
+ * empty.
49
+ *
50
+ * **Shared across the lineage, not held per instance.** Inside a `wrap`, the
51
+ * receiver and the wrap's own scope both resolve the frame's source, and must
52
+ * reach the same cached Fabricator — otherwise interleaving
53
+ * `instance.fabricate(S)` with `scope.fabricate(S)` would draw two separate
54
+ * sequences, where `new Fabricator` keeps the implicit and explicit routes in
55
+ * agreement (`test/Wrap.test.ts`). Two lineages never resolve the same source,
56
+ * so one map per lineage shares nothing between `initialize()` calls.
57
+ *
58
+ * The source is resolved and the build made in one synchronous call, so
59
+ * `construct` resolves the same frame this function keyed by.
60
+ */
61
+ 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
@@ -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
  /**
@@ -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";
@@ -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;