@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.
- package/README.md +1 -1
- package/dist/esm/Enumeration/Enumerate.js +2 -4
- package/dist/esm/Error/index.js +34 -6
- package/dist/esm/Fabricator/Constructor.js +40 -33
- package/dist/esm/Fabricator/Fabricate.js +23 -0
- package/dist/esm/Instance/Core.js +14 -2
- package/dist/esm/Instance/Stack/Visible.js +6 -1
- package/dist/esm/Primitive/boolean/Registry.js +10 -8
- package/dist/esm/Primitive/date/Defaults.js +12 -0
- package/dist/esm/Primitive/date/Fabricator.js +5 -10
- package/dist/esm/Primitive/date/Registry.js +49 -39
- package/dist/esm/Primitive/index.js +2 -0
- package/dist/esm/Primitive/null/Registry.js +6 -4
- package/dist/esm/Primitive/number/Fabricator.js +1 -1
- package/dist/esm/Primitive/number/Registry.js +36 -30
- package/dist/esm/Primitive/object/Fabricator.js +33 -11
- package/dist/esm/Primitive/object/Registry.js +90 -10
- package/dist/esm/Primitive/object/compute/Fabricator.js +10 -3
- package/dist/esm/Primitive/object/compute/Registry.js +20 -3
- package/dist/esm/Primitive/object/omit/Registry.js +5 -0
- package/dist/esm/Primitive/object/omit/index.js +2 -0
- package/dist/esm/Primitive/object/pick/Registry.js +5 -0
- package/dist/esm/Primitive/object/pick/index.js +2 -0
- package/dist/esm/Primitive/recursive/Fabricator.js +1 -0
- package/dist/esm/Primitive/recursive/Terminate.js +21 -9
- package/dist/esm/Primitive/symbol/Registry.js +15 -13
- package/dist/esm/Primitive/undefined/Registry.js +6 -4
- package/dist/esm/Schema/Core.js +9 -1
- package/dist/esm/Schema/Registry.js +27 -7
- package/dist/esm/Utility/DeepMerge.js +47 -6
- package/dist/esm/internal.js +1 -0
- package/dist/types/Error/index.d.ts +71 -6
- package/dist/types/Fabricator/Fabricate.d.ts +63 -0
- package/dist/types/Fabricator/Types.d.ts +13 -3
- package/dist/types/Harnessing/Core.d.ts +7 -7
- package/dist/types/Instance/Core.d.ts +15 -8
- package/dist/types/Instance/Stack/Visible.d.ts +10 -0
- package/dist/types/Instance/Types.d.ts +30 -15
- package/dist/types/Primitive/boolean/Registry.d.ts +6 -1
- package/dist/types/Primitive/date/Defaults.d.ts +11 -0
- package/dist/types/Primitive/date/Registry.d.ts +13 -9
- package/dist/types/Primitive/date/Types.d.ts +10 -0
- package/dist/types/Primitive/index.d.ts +2 -0
- package/dist/types/Primitive/null/Registry.d.ts +6 -1
- package/dist/types/Primitive/number/Registry.d.ts +8 -1
- package/dist/types/Primitive/object/Fabricator.d.ts +13 -5
- package/dist/types/Primitive/object/Registry.d.ts +17 -1
- package/dist/types/Primitive/object/Types.d.ts +19 -0
- package/dist/types/Primitive/object/compute/Fabricator.d.ts +9 -8
- package/dist/types/Primitive/object/compute/Registry.d.ts +7 -1
- package/dist/types/Primitive/object/compute/Schema.d.ts +20 -0
- package/dist/types/Primitive/object/compute/Types.d.ts +10 -0
- package/dist/types/Primitive/object/omit/Registry.d.ts +7 -0
- package/dist/types/Primitive/object/omit/index.d.ts +2 -0
- package/dist/types/Primitive/object/pick/Registry.d.ts +8 -0
- package/dist/types/Primitive/object/pick/index.d.ts +2 -0
- package/dist/types/Primitive/recursive/Fabricator.d.ts +9 -7
- package/dist/types/Primitive/symbol/Registry.d.ts +6 -1
- package/dist/types/Primitive/undefined/Registry.d.ts +6 -1
- package/dist/types/Schema/Core.d.ts +16 -1
- package/dist/types/Schema/Registry.d.ts +7 -4
- package/dist/types/Utility/DeepMerge.d.ts +11 -0
- package/dist/types/index.d.ts +23 -10
- package/dist/types/internal.d.ts +8 -0
- package/package.json +4 -4
- /package/dist/esm/Primitive/number/{defaults.js → Defaults.js} +0 -0
- /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
|
|
30
|
-
*
|
|
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)
|
|
56
|
-
* wall-clock default are already concrete numbers by the time
|
|
57
|
-
* them, so they inherit through every `wrap` — the frame in
|
|
58
|
-
* salt varies per test, "now" does not. `clock: "derived"`
|
|
59
|
-
* purpose — that policy's documented meaning is that the salt
|
|
60
|
-
* reproducibility unit, so per-test clocks are the request honored,
|
|
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
|
|
36
|
-
* default are stored as epoch milliseconds (a stated instant,
|
|
37
|
-
* from then on
|
|
38
|
-
*
|
|
39
|
-
* `
|
|
40
|
-
* `
|
|
41
|
-
*
|
|
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-
|
|
17
|
-
*
|
|
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
|
|
37
|
-
* | "derived"`, so a caller can hand in a literal instant without
|
|
38
|
-
* to epoch milliseconds themselves
|
|
39
|
-
*
|
|
40
|
-
*
|
|
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(...)`, `
|
|
284
|
-
* inside — on this instance, and on this instance's
|
|
285
|
-
* against the fork instead, with nothing threaded
|
|
286
|
-
* passed to `block`: use it explicitly where that
|
|
287
|
-
* _necessarily_ for any async work, which the ambient frame
|
|
288
|
-
* — a build reached after an `await` inside `block` sees
|
|
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
|
-
|
|
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]`.
|
|
9
|
-
*
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
52
|
-
*
|
|
53
|
-
* covered by `overrides`, in which case it resolves in phase 1 like any
|
|
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
|
-
|
|
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,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]>>;
|