@ghostry/fabricator 0.0.12 → 0.0.14
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/Bound.js +74 -1
- package/dist/esm/Distribution/index.js +103 -2
- package/dist/esm/Enumeration/Enumerate.js +10 -5
- package/dist/esm/Enumeration/Plan.js +2 -2
- package/dist/esm/Error/index.js +96 -27
- package/dist/esm/Fabricator/Constructor.js +7 -5
- package/dist/esm/Fabricator/Fabricate.js +1 -6
- package/dist/esm/Instance/Core.js +3 -0
- package/dist/esm/Primitive/array/Admits.js +18 -0
- package/dist/esm/Primitive/array/Fabricator.js +20 -2
- package/dist/esm/Primitive/array/Registry.js +32 -0
- package/dist/esm/Primitive/array/Schema.js +8 -0
- package/dist/esm/Primitive/bigint/Admits.js +11 -0
- package/dist/esm/Primitive/bigint/Fabricator.js +16 -23
- package/dist/esm/Primitive/bigint/Registry.js +17 -6
- package/dist/esm/Primitive/bigint/Schema.js +8 -0
- package/dist/esm/Primitive/boolean/Registry.js +10 -8
- package/dist/esm/Primitive/date/Admits.js +22 -0
- package/dist/esm/Primitive/date/Defaults.js +27 -1
- package/dist/esm/Primitive/date/Fabricator.js +32 -34
- package/dist/esm/Primitive/date/Registry.js +111 -38
- package/dist/esm/Primitive/date/Schema.js +8 -0
- package/dist/esm/Primitive/enum/Fabricator.js +14 -2
- package/dist/esm/Primitive/enum/Registry.js +38 -25
- package/dist/esm/Primitive/index.js +1 -0
- package/dist/esm/Primitive/null/Registry.js +6 -4
- package/dist/esm/Primitive/number/Admits.js +27 -0
- package/dist/esm/Primitive/number/Fabricator.js +18 -9
- package/dist/esm/Primitive/number/Registry.js +86 -29
- package/dist/esm/Primitive/number/Schema.js +10 -3
- package/dist/esm/Primitive/object/Fabricator.js +2 -0
- package/dist/esm/Primitive/record/Admits.js +42 -0
- package/dist/esm/Primitive/record/Fabricator.js +49 -19
- package/dist/esm/Primitive/record/Registry.js +29 -0
- package/dist/esm/Primitive/record/Schema.js +8 -0
- package/dist/esm/Primitive/recursive/Fabricator.js +3 -2
- package/dist/esm/Primitive/recursive/Terminate.js +16 -2
- package/dist/esm/Primitive/string/Admits.js +26 -0
- package/dist/esm/Primitive/string/Capacity.js +81 -0
- package/dist/esm/Primitive/string/Fabricator.js +23 -43
- package/dist/esm/Primitive/string/Registry.js +31 -9
- package/dist/esm/Primitive/string/Schema.js +10 -3
- package/dist/esm/Primitive/string/Sources.js +41 -0
- package/dist/esm/Primitive/symbol/Registry.js +15 -13
- package/dist/esm/Primitive/undefined/Registry.js +6 -4
- package/dist/esm/Primitive/unique/Registry.js +22 -0
- package/dist/esm/Primitive/unique/index.js +2 -0
- package/dist/esm/Schema/Core.js +9 -1
- package/dist/esm/Schema/Registry.js +27 -7
- package/dist/esm/Types.js +2 -1
- package/dist/esm/Unique/Capacity.js +85 -0
- package/dist/esm/Unique/Distinct.js +187 -0
- package/dist/esm/Unique/Key.js +70 -0
- package/dist/esm/Unique/Override.js +23 -0
- package/dist/esm/Unique/Strategy.js +173 -0
- package/dist/esm/Utility/DeepMerge.js +47 -6
- package/dist/esm/internal.js +2 -0
- package/dist/types/Bound.d.ts +66 -0
- package/dist/types/Distribution/index.d.ts +82 -0
- package/dist/types/Enumeration/Types.d.ts +10 -1
- package/dist/types/Error/index.d.ts +283 -0
- package/dist/types/Fabricator/Constructor.d.ts +6 -2
- package/dist/types/Fabricator/Fabricate.d.ts +4 -2
- package/dist/types/Fabricator/Types.d.ts +13 -0
- package/dist/types/Instance/Types.d.ts +14 -0
- package/dist/types/Primitive/array/Admits.d.ts +7 -0
- package/dist/types/Primitive/array/Fabricator.d.ts +2 -2
- package/dist/types/Primitive/array/Registry.d.ts +38 -1
- package/dist/types/Primitive/array/Schema.d.ts +6 -1
- package/dist/types/Primitive/array/Types.d.ts +33 -1
- package/dist/types/Primitive/bigint/Admits.d.ts +7 -0
- package/dist/types/Primitive/bigint/Fabricator.d.ts +3 -1
- package/dist/types/Primitive/bigint/Registry.d.ts +20 -0
- package/dist/types/Primitive/bigint/Schema.d.ts +9 -1
- package/dist/types/Primitive/bigint/Types.d.ts +27 -3
- package/dist/types/Primitive/boolean/Registry.d.ts +6 -1
- package/dist/types/Primitive/date/Admits.d.ts +7 -0
- package/dist/types/Primitive/date/Defaults.d.ts +22 -1
- package/dist/types/Primitive/date/Fabricator.d.ts +3 -1
- package/dist/types/Primitive/date/Registry.d.ts +54 -12
- package/dist/types/Primitive/date/Schema.d.ts +10 -1
- package/dist/types/Primitive/date/Types.d.ts +53 -4
- package/dist/types/Primitive/enum/Fabricator.d.ts +3 -1
- package/dist/types/Primitive/enum/Registry.d.ts +20 -0
- package/dist/types/Primitive/enum/Types.d.ts +5 -0
- package/dist/types/Primitive/index.d.ts +1 -0
- package/dist/types/Primitive/null/Registry.d.ts +6 -1
- package/dist/types/Primitive/number/Admits.d.ts +9 -0
- package/dist/types/Primitive/number/Fabricator.d.ts +3 -1
- package/dist/types/Primitive/number/Registry.d.ts +50 -2
- package/dist/types/Primitive/number/Schema.d.ts +10 -2
- package/dist/types/Primitive/number/Types.d.ts +32 -10
- package/dist/types/Primitive/record/Admits.d.ts +18 -0
- package/dist/types/Primitive/record/Fabricator.d.ts +2 -2
- package/dist/types/Primitive/record/Registry.d.ts +18 -1
- package/dist/types/Primitive/record/Schema.d.ts +8 -1
- package/dist/types/Primitive/record/Types.d.ts +60 -6
- package/dist/types/Primitive/recursive/Terminate.d.ts +7 -0
- package/dist/types/Primitive/string/Admits.d.ts +8 -0
- package/dist/types/Primitive/string/Capacity.d.ts +36 -0
- package/dist/types/Primitive/string/Fabricator.d.ts +3 -1
- package/dist/types/Primitive/string/Registry.d.ts +26 -5
- package/dist/types/Primitive/string/Schema.d.ts +28 -2
- package/dist/types/Primitive/string/Sources.d.ts +16 -0
- package/dist/types/Primitive/string/Types.d.ts +35 -15
- package/dist/types/Primitive/symbol/Registry.d.ts +6 -1
- package/dist/types/Primitive/undefined/Registry.d.ts +6 -1
- package/dist/types/Primitive/unique/Registry.d.ts +39 -0
- package/dist/types/Primitive/unique/index.d.ts +2 -0
- package/dist/types/Schema/Core.d.ts +16 -1
- package/dist/types/Schema/Registry.d.ts +7 -4
- package/dist/types/Types.d.ts +9 -0
- package/dist/types/Unique/Capacity.d.ts +29 -0
- package/dist/types/Unique/Distinct.d.ts +95 -0
- package/dist/types/Unique/Key.d.ts +29 -0
- package/dist/types/Unique/Override.d.ts +16 -0
- package/dist/types/Unique/Strategy.d.ts +135 -0
- package/dist/types/Utility/DeepMerge.d.ts +11 -0
- package/dist/types/index.d.ts +13 -0
- package/dist/types/internal.d.ts +9 -0
- package/package.json +3 -3
|
@@ -1,7 +1,8 @@
|
|
|
1
1
|
import type { Adaptations } from "../Adapter/Types";
|
|
2
2
|
import type { Kind as SchemaKind } from "../Primitive";
|
|
3
|
-
import { Adaptation, Kind, Meta, type Produced, type Produces } from "../Types";
|
|
3
|
+
import { Adaptation, Kind, Meta, type Buildable, type Produced, type Produces } from "../Types";
|
|
4
4
|
import { type PlainObject } from "../Utility/Types";
|
|
5
|
+
import type { AnySchema } from "./Types";
|
|
5
6
|
/**
|
|
6
7
|
* Normalize a Schema, a builder namespace, or an already-built Fabricator into
|
|
7
8
|
* a clean, storable Schema — keeping only `[Kind]`/ `[Meta]`/`[Adaptation]` and
|
|
@@ -36,6 +37,20 @@ export declare function toSchema<$Kind extends string, $Meta extends PlainObject
|
|
|
36
37
|
readonly [Produces]?: Produced<$Produces>;
|
|
37
38
|
readonly [Adaptation]?: $Adaptations;
|
|
38
39
|
};
|
|
40
|
+
/**
|
|
41
|
+
* Whether `candidate` is something `new Fabricator(...)` can build: a Schema or
|
|
42
|
+
* a built Fabricator, which both carry a `[Kind]` tag and a `[Meta]`. A bare
|
|
43
|
+
* builder that is a function (`T.array`, `T.recursive`) fails the first test;
|
|
44
|
+
* one that is an object but has no `[Kind]` fails the second. `T.string` and
|
|
45
|
+
* `T.bigint` carry `[Kind]` so they can name a compute source, but have no
|
|
46
|
+
* `[Meta]` until `.whereby(...)`, and fail the third.
|
|
47
|
+
*/
|
|
48
|
+
export declare function isBuildable(candidate: unknown): candidate is Buildable;
|
|
49
|
+
/**
|
|
50
|
+
* {@link isBuildable}, excluding a built Fabricator: a Schema is inert, and only
|
|
51
|
+
* a Fabricator has `fabricate`.
|
|
52
|
+
*/
|
|
53
|
+
export declare function isSchema(candidate: unknown): candidate is AnySchema;
|
|
39
54
|
/**
|
|
40
55
|
* The `[Kind]` a schema's fabricated value should be checked against with
|
|
41
56
|
* {@link violatesKind}. For most kinds that is its own `[Kind]`, but
|
|
@@ -2,11 +2,14 @@ import * as primitives from "../Primitive";
|
|
|
2
2
|
import { deepMerge, type DeepMerge } from "../Utility/DeepMerge";
|
|
3
3
|
import { type PlainObject } from "../Utility/Types";
|
|
4
4
|
/**
|
|
5
|
-
* `
|
|
6
|
-
*
|
|
7
|
-
*
|
|
5
|
+
* A kind whose `Registry.ts` default export takes no arguments returns a bare
|
|
6
|
+
* Schema, which `builders` installs behind a getter; every builder takes at
|
|
7
|
+
* least one. A bare kind left without a getter therefore fails to compile in
|
|
8
|
+
* `builders`, where the spread supplies the function itself.
|
|
8
9
|
*/
|
|
9
|
-
type Builders =
|
|
10
|
+
type Builders = {
|
|
11
|
+
[$K in Exclude<keyof typeof primitives, "Primitive">]: (typeof primitives)[$K] extends () => infer $Schema ? $Schema : (typeof primitives)[$K];
|
|
12
|
+
};
|
|
10
13
|
type RegistryInterface<$Registry> = {
|
|
11
14
|
extend: <const $Extension extends PlainObject>(types: (params: {
|
|
12
15
|
T: $Registry;
|
package/dist/types/Types.d.ts
CHANGED
|
@@ -83,6 +83,15 @@ export declare const Adaptation: unique symbol;
|
|
|
83
83
|
* distinguishes the two outcomes).
|
|
84
84
|
*/
|
|
85
85
|
export declare const Omitted: unique symbol;
|
|
86
|
+
/**
|
|
87
|
+
* Marks a value as already produced, carried only by a built `T.unique.*` leaf
|
|
88
|
+
* (`Unique/Distinct.ts`'s `Tracker`). A per-call override skips that leaf's
|
|
89
|
+
* draw, so `object/Fabricator.ts` hands the override value here through
|
|
90
|
+
* `Unique/Override.ts`'s `recordOverride`, and no later draw repeats it.
|
|
91
|
+
* Recording only — claiming a value already produced is not an error, since the
|
|
92
|
+
* caller asked for it.
|
|
93
|
+
*/
|
|
94
|
+
export declare const Claim: unique symbol;
|
|
86
95
|
/**
|
|
87
96
|
* Everything `construct()`/`toTypeBox()` accept as a starting point: a
|
|
88
97
|
* not-yet-built Schema, or something already built into a Fabricator.
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
import { type Buildable } from "../Types";
|
|
2
|
+
/**
|
|
3
|
+
* How many times one built Fabricator of `schema` can `fabricate()` before a
|
|
4
|
+
* `T.unique.*` leaf runs out, or `undefined` when no leaf has a known limit.
|
|
5
|
+
* The answer for a fresh Fabricator: it does not count what an existing one has
|
|
6
|
+
* already drawn.
|
|
7
|
+
*/
|
|
8
|
+
export type Capacity = (schema: Buildable) => bigint | undefined;
|
|
9
|
+
/**
|
|
10
|
+
* Walk `schema` — the Schema, not a build, so nothing is constructed, no
|
|
11
|
+
* ordinal is taken, and an object's hidden fields are seen — and take the
|
|
12
|
+
* tightest limit any unique leaf sets. A leaf allows `capacity / draws`
|
|
13
|
+
* fabrications, `draws` being the most times one fabrication can reach it: one,
|
|
14
|
+
* multiplied by `length.max`/`size.max` for each array or record above it.
|
|
15
|
+
*
|
|
16
|
+
* Conservative where a leaf may not draw at all: one behind a presence wrapper
|
|
17
|
+
* or a `choice` option is counted as drawing every time. Not counted, since
|
|
18
|
+
* they never limit one Fabricator's fabrications:
|
|
19
|
+
*
|
|
20
|
+
* - a unique collection's members, distinct only within each value and checked
|
|
21
|
+
* against the length at construction;
|
|
22
|
+
* - anything under `T.recursive`, whose expansions each build afresh;
|
|
23
|
+
* - a `[Fixed]` field and an `object.compute` source, which never draw;
|
|
24
|
+
* - any node with `.as(...)`, whose producer replaces everything beneath it;
|
|
25
|
+
* - a leaf of unknown size, such as a continuous `T.unique.number` range.
|
|
26
|
+
*
|
|
27
|
+
* `clock` resolves a `date` leaf's `past`/`future` end.
|
|
28
|
+
*/
|
|
29
|
+
export declare function toCapacity(schema: Buildable, clock: number): bigint | undefined;
|
|
@@ -0,0 +1,95 @@
|
|
|
1
|
+
import { type Distribution, type Range } from "../Distribution";
|
|
2
|
+
import type { Fabricator } from "../Fabricator/Types";
|
|
3
|
+
import type { Whereby as BigintWhereby } from "../Primitive/bigint/Types";
|
|
4
|
+
import type { Meta as NumberMeta } from "../Primitive/number/Types";
|
|
5
|
+
import type { Stream } from "../Random/Types";
|
|
6
|
+
import { type Strategy } from "./Strategy";
|
|
7
|
+
/**
|
|
8
|
+
* How many distinct values a unique `number` can produce: every integer of an
|
|
9
|
+
* integer range, skewed or not, and for a continuous range only the single
|
|
10
|
+
* value of one whose ends meet — any other continuous range is left uncounted.
|
|
11
|
+
* Shared by {@link toNumberStrategy} and `Unique/Capacity.ts`.
|
|
12
|
+
*/
|
|
13
|
+
export declare function toNumberCapacity(meta: NumberMeta): bigint | undefined;
|
|
14
|
+
/**
|
|
15
|
+
* The size of an inclusive integer range, exact past `Number.MAX_SAFE_INTEGER`.
|
|
16
|
+
*/
|
|
17
|
+
export declare function toRangeCapacity(range: Range): bigint;
|
|
18
|
+
/**
|
|
19
|
+
* How a unique `number` draws. A uniform integer range small enough for exact
|
|
20
|
+
* positions is a sparse Fisher–Yates permutation on `stream`. Everything else —
|
|
21
|
+
* an unbounded integer, a skewed integer range, any continuous range — tracks
|
|
22
|
+
* the numbers it has produced, calling `draw` (the kind's ordinary sampler)
|
|
23
|
+
* until it lands on a new one. An integer range keeps its exact size as
|
|
24
|
+
* `capacity` even when tracked, so it exhausts by counting rather than by
|
|
25
|
+
* spinning; a continuous range has one only when its two ends meet.
|
|
26
|
+
*
|
|
27
|
+
* Shared by `number/Fabricator.ts` (a `T.unique.number` leaf, with its own
|
|
28
|
+
* stream and sampler) and {@link toDistinct} (a collection member, with the
|
|
29
|
+
* collection's stream and the member's `fabricate`). A leaf's cap is its own
|
|
30
|
+
* `whereby.redraws`; a member's is the collection's.
|
|
31
|
+
*/
|
|
32
|
+
export declare function toNumberStrategy(options: {
|
|
33
|
+
label: string;
|
|
34
|
+
meta: NumberMeta;
|
|
35
|
+
stream: Stream;
|
|
36
|
+
draw: () => number;
|
|
37
|
+
redraws?: number | undefined;
|
|
38
|
+
}): Strategy;
|
|
39
|
+
/**
|
|
40
|
+
* How a unique `date` draws, over `range` — every whole millisecond a draw can
|
|
41
|
+
* produce (`date/Defaults.ts`'s `toEpochRange`). A uniform range small enough
|
|
42
|
+
* for exact positions is a permutation of those milliseconds, like an integer
|
|
43
|
+
* range. Anything wider or skewed tracks the instants produced, by time value,
|
|
44
|
+
* and its exact size lets it exhaust by counting.
|
|
45
|
+
*
|
|
46
|
+
* Both draw whole milliseconds from `stream` — the tracked path through
|
|
47
|
+
* `discreteSampler`, the integer draw — never through the kind's ordinary
|
|
48
|
+
* continuous sampler. That sampler reaches the upper millisecond only when a
|
|
49
|
+
* draw lands exactly on it, so a count that includes it would leave the last
|
|
50
|
+
* instant all but unreachable and the final draw spinning to the cap.
|
|
51
|
+
*/
|
|
52
|
+
export declare function toDateStrategy(options: {
|
|
53
|
+
label: string;
|
|
54
|
+
range: Range;
|
|
55
|
+
distribution: Distribution | undefined;
|
|
56
|
+
stream: Stream;
|
|
57
|
+
redraws?: number | undefined;
|
|
58
|
+
}): Strategy;
|
|
59
|
+
/**
|
|
60
|
+
* How a unique `bigint` draws: a bigint sparse Fisher–Yates permutation of its
|
|
61
|
+
* range on `stream`, exact at any width.
|
|
62
|
+
*/
|
|
63
|
+
export declare function toBigintStrategy(whereby: BigintWhereby, stream: Stream): Strategy;
|
|
64
|
+
/**
|
|
65
|
+
* How a unique collection (`T.unique.array`'s elements, `T.unique.record`'s
|
|
66
|
+
* keys) draws distinct members from `member`, an already-built Fabricator.
|
|
67
|
+
* Chosen once, at construction, by reading `member`'s `[Kind]`/`[Meta]`; the
|
|
68
|
+
* collection then opens a fresh scope per `fabricate()` call.
|
|
69
|
+
*
|
|
70
|
+
* Exact strategies draw from `stream`, the collection's own, never from the
|
|
71
|
+
* member's — the member's own `fabricate` is simply not called. A `date` member
|
|
72
|
+
* reads its range against its own `trace.clock`. Everything else is tracked by
|
|
73
|
+
* canonical key over `member.fabricate`: any member under a `by` projection or
|
|
74
|
+
* an `.as(...)` producer, and also a member that does not repeat by itself (a
|
|
75
|
+
* `sequence`, a bare `symbol`, a `T.unique.*` leaf). Trusting the last group
|
|
76
|
+
* would save a hash per member, but a unique leaf does repeat once it cycles
|
|
77
|
+
* under `combinatorial`/`coverage` (`Fabricator/Types.ts`'s `Exhaustion`), and
|
|
78
|
+
* a repeat would land inside one value.
|
|
79
|
+
*
|
|
80
|
+
* Reads another kind's `[Meta]`, which AGENTS.md otherwise keeps kind-private —
|
|
81
|
+
* the same exception `Enumeration/Plan.ts` takes, for the same reason: the
|
|
82
|
+
* finite value set a kind draws from is exactly what is needed here.
|
|
83
|
+
*/
|
|
84
|
+
export declare function toDistinct(member: Fabricator<unknown>, stream: Stream, options: {
|
|
85
|
+
label: string;
|
|
86
|
+
by?: ((value: any) => unknown) | undefined;
|
|
87
|
+
redraws?: number | undefined;
|
|
88
|
+
}): Strategy;
|
|
89
|
+
/**
|
|
90
|
+
* Reject, at construction, a collection that may ask for more distinct members
|
|
91
|
+
* than its member schema has — so an exact member can never run out on a draw
|
|
92
|
+
* whose size depends on the salt. A member of unknown capacity passes; it is
|
|
93
|
+
* left to the tracked scope's cap.
|
|
94
|
+
*/
|
|
95
|
+
export declare function assertCapacity(label: string, strategy: Strategy, requested: number): void;
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Maps a value to a number that equal values share — what a tracked unique
|
|
3
|
+
* scope (`Unique/Strategy.ts`) stores in place of the value itself, so memory
|
|
4
|
+
* per produced value stays one number however large the value is.
|
|
5
|
+
*/
|
|
6
|
+
export type Keyer = (value: unknown) => number;
|
|
7
|
+
/**
|
|
8
|
+
* A fresh {@link Keyer}, owning the identity tables its encoding needs. Two
|
|
9
|
+
* values share a key when they are the same plain data:
|
|
10
|
+
*
|
|
11
|
+
* - Primitives compare by SameValueZero, as a `Set` would: `-0` is `0`, `NaN` is
|
|
12
|
+
* `NaN`, and `"1"` is not `1`.
|
|
13
|
+
* - A `Date` compares by its time value.
|
|
14
|
+
* - Arrays compare element by element, a hole reading as `undefined`.
|
|
15
|
+
* - Plain objects compare by their own enumerable keys and values, in any key
|
|
16
|
+
* order. A key present as `undefined` differs from an absent one, the
|
|
17
|
+
* distinction `T.optional` draws.
|
|
18
|
+
*
|
|
19
|
+
* Everything else — symbols, functions, and objects that are not plain data
|
|
20
|
+
* (`Map`, `Set`, class instances) — compares by identity, through an id the
|
|
21
|
+
* tables hand out on first sight. Structural rules for those would be guesses;
|
|
22
|
+
* a `by` projection says what makes one unique.
|
|
23
|
+
*
|
|
24
|
+
* The encoding is hashed to 53 bits (`cyrb128`'s first two words), exact as a
|
|
25
|
+
* `number`. The error is one-sided: two different values sharing a hash makes a
|
|
26
|
+
* scope skip one of them, never produce a duplicate. Across a million values
|
|
27
|
+
* that happens with probability around 5e-5.
|
|
28
|
+
*/
|
|
29
|
+
export declare function toKeyer(): Keyer;
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Record a per-call override on the `T.unique.*` leaf it stands in for, so no
|
|
3
|
+
* later draw repeats it. An override skips the field's draw
|
|
4
|
+
* (`object/Fabricator.ts`), so without this the leaf would never learn that the
|
|
5
|
+
* value was used.
|
|
6
|
+
*
|
|
7
|
+
* The field handed in is not always the leaf: `T.omittable(T.unique...)` is how
|
|
8
|
+
* an optional unique field is spelled. So this walks down through the
|
|
9
|
+
* single-child presence wrappers via `[Children]`, stopping where `value` is
|
|
10
|
+
* that wrapper's own outcome (`null`, `undefined`, `Omitted`) rather than its
|
|
11
|
+
* child's, and calls the leaf's `[Claim]`. Any other node ends the walk: a
|
|
12
|
+
* nested `object` records its own fields through its own
|
|
13
|
+
* `fabricate(overrides)`, and nothing else holds a unique leaf whose draw an
|
|
14
|
+
* override could stand in for.
|
|
15
|
+
*/
|
|
16
|
+
export declare function recordOverride(field: any, value: unknown): void;
|
|
@@ -0,0 +1,135 @@
|
|
|
1
|
+
import { type Range } from "../Distribution";
|
|
2
|
+
import { FabricatorError } from "../Error";
|
|
3
|
+
import type { Exhaustion } from "../Fabricator/Types";
|
|
4
|
+
import type { Stream } from "../Random/Types";
|
|
5
|
+
import { type Keyer } from "./Key";
|
|
6
|
+
/**
|
|
7
|
+
* One run of distinct draws: nothing `draw` returns repeats anything it, or
|
|
8
|
+
* `claim`, saw before in the same scope. A `T.unique.*` leaf opens one scope
|
|
9
|
+
* for its built Fabricator's lifetime; a unique collection opens a fresh one
|
|
10
|
+
* per `fabricate()` call.
|
|
11
|
+
*/
|
|
12
|
+
export type Scope = {
|
|
13
|
+
draw: () => unknown;
|
|
14
|
+
/**
|
|
15
|
+
* Record `value` as produced without drawing it — an override value
|
|
16
|
+
* (`Unique/Override.ts`). Recording only: claiming a value already produced,
|
|
17
|
+
* or one outside the domain, changes nothing.
|
|
18
|
+
*/
|
|
19
|
+
claim: (value: unknown) => void;
|
|
20
|
+
};
|
|
21
|
+
/**
|
|
22
|
+
* How a schema's distinct values are drawn. `capacity` is how many there are,
|
|
23
|
+
* when that is known, which is what lets a collection reject an impossible size
|
|
24
|
+
* at construction rather than on a salt-dependent draw.
|
|
25
|
+
*/
|
|
26
|
+
export type Strategy = {
|
|
27
|
+
readonly capacity: bigint | undefined;
|
|
28
|
+
open: () => Scope;
|
|
29
|
+
};
|
|
30
|
+
export declare function defaultRedraws(produced: number): number;
|
|
31
|
+
/**
|
|
32
|
+
* The `redraws` every `T.unique.*` builder's `.whereby` accepts: how many times
|
|
33
|
+
* in a row a tracked draw may repeat a value already produced while looking for
|
|
34
|
+
* a new one, before it forfeits — per value, not across the scope. `0` means
|
|
35
|
+
* one draw and no retries. Replaces the default formula
|
|
36
|
+
* ({@link defaultRedraws}); a skewed distribution is what needs it most, since
|
|
37
|
+
* its rarest values take many draws to find. Validated by {@link toRedraws},
|
|
38
|
+
* and stored on each kind's `Whereby` as a plain `redraws` field.
|
|
39
|
+
*/
|
|
40
|
+
export type Redraws = {
|
|
41
|
+
redraws?: number | undefined;
|
|
42
|
+
};
|
|
43
|
+
/**
|
|
44
|
+
* Validate a caller-supplied `redraws`. It counts retries, so any whole number
|
|
45
|
+
* from `0` up can be one.
|
|
46
|
+
*/
|
|
47
|
+
export declare function toRedraws(label: string, redraws: number | undefined): number | undefined;
|
|
48
|
+
/**
|
|
49
|
+
* Sampling without replacement from a weighted list of values — `enum`,
|
|
50
|
+
* `boolean`, and the single-value kinds. Equal values (by {@link toKeyer}) are
|
|
51
|
+
* merged first, their weights summed, so `capacity` counts distinct values and
|
|
52
|
+
* `T.enum.uniform(["a", "a", "b"])` still draws `"a"` two times in three. Draws
|
|
53
|
+
* come from `stream`, the owning node's own.
|
|
54
|
+
*/
|
|
55
|
+
export declare function exactValues(kind: string, entries: ReadonlyArray<readonly [number, unknown]>, stream: Stream): Strategy;
|
|
56
|
+
/**
|
|
57
|
+
* `entries`' drawable values with equal ones merged and their weights summed,
|
|
58
|
+
* each tagged with its canonical key — what {@link exactValues} draws from, and
|
|
59
|
+
* what `Unique/Capacity.ts` counts for a unique `enum`. Returns the
|
|
60
|
+
* {@link Keyer} too, since a claim must key a value the same way.
|
|
61
|
+
*/
|
|
62
|
+
export declare function toDistinctValues(entries: ReadonlyArray<readonly [number, unknown]>): {
|
|
63
|
+
keyer: Keyer;
|
|
64
|
+
values: Array<[number, {
|
|
65
|
+
key: number;
|
|
66
|
+
value: unknown;
|
|
67
|
+
}]>;
|
|
68
|
+
};
|
|
69
|
+
/**
|
|
70
|
+
* Sampling without replacement from a uniform integer range, by sparse
|
|
71
|
+
* Fisher–Yates (`Distribution/index.ts`'s `permutation`). A claimed value is
|
|
72
|
+
* held aside and skipped when the permutation reaches it — consumed, not
|
|
73
|
+
* redrawn into — which leaves every later draw uniform over what remains.
|
|
74
|
+
* Precondition: the range's size is at most `Number.MAX_SAFE_INTEGER`.
|
|
75
|
+
*/
|
|
76
|
+
export declare function exactRange(kind: string, range: Range, stream: Stream): Strategy;
|
|
77
|
+
/**
|
|
78
|
+
* {@link exactRange} over a bigint range — no size precondition.
|
|
79
|
+
*/
|
|
80
|
+
export declare function exactBigintRange(kind: string, range: {
|
|
81
|
+
min: bigint;
|
|
82
|
+
max: bigint;
|
|
83
|
+
}, stream: Stream): Strategy;
|
|
84
|
+
/**
|
|
85
|
+
* Rejection sampling: draw, and draw again while the key has been seen. For
|
|
86
|
+
* every domain no exact strategy covers — strings, dates, composites,
|
|
87
|
+
* `.as(...)`, a skewed or unbounded integer range, a `by` projection.
|
|
88
|
+
*
|
|
89
|
+
* `key` reduces a value to what is stored: a number for a numeric domain (`Set`
|
|
90
|
+
* compares those by SameValueZero already), a {@link Keyer} hash otherwise. When
|
|
91
|
+
* `capacity` is known the scope counts rather than searches — exhausted the
|
|
92
|
+
* moment it has seen that many, with no retries. `admits` keeps a claimed value
|
|
93
|
+
* from outside the domain out of that count: an override of `0` on a `[1, 10]`
|
|
94
|
+
* field must not use up one of its ten.
|
|
95
|
+
*/
|
|
96
|
+
export declare function tracked(options: {
|
|
97
|
+
label: string;
|
|
98
|
+
kind: string;
|
|
99
|
+
draw: () => unknown;
|
|
100
|
+
key: (value: unknown) => unknown;
|
|
101
|
+
capacity?: bigint | undefined;
|
|
102
|
+
admits?: ((value: unknown) => boolean) | undefined;
|
|
103
|
+
redraws?: number | undefined;
|
|
104
|
+
}): Strategy;
|
|
105
|
+
/**
|
|
106
|
+
* {@link tracked} keyed by a fresh {@link Keyer}, through `by` when given.
|
|
107
|
+
*/
|
|
108
|
+
export declare function trackedByKey(options: {
|
|
109
|
+
label: string;
|
|
110
|
+
kind: string;
|
|
111
|
+
draw: () => unknown;
|
|
112
|
+
by?: ((value: any) => unknown) | undefined;
|
|
113
|
+
capacity?: bigint | undefined;
|
|
114
|
+
admits?: ((value: unknown) => boolean) | undefined;
|
|
115
|
+
redraws?: number | undefined;
|
|
116
|
+
}): Strategy;
|
|
117
|
+
/**
|
|
118
|
+
* `member.fabricate`, for a plain `T.array`/`T.record` whose element or key is
|
|
119
|
+
* a `T.unique.*` leaf (one carrying `[Claim]`): an exhaustion it raises is
|
|
120
|
+
* re-raised naming the collection, whose message points at the per-value
|
|
121
|
+
* builder. Any other member is returned untouched, so the common path pays
|
|
122
|
+
* nothing.
|
|
123
|
+
*/
|
|
124
|
+
export declare function withinCollection<$T>(collection: FabricatorError.UniqueWithin, member: {
|
|
125
|
+
fabricate: () => $T;
|
|
126
|
+
}): () => $T;
|
|
127
|
+
/**
|
|
128
|
+
* The scope a `T.unique.*` leaf keeps for its built Fabricator's whole life,
|
|
129
|
+
* under the build's exhaustion policy. Under `"cycle"` (an enumeration build —
|
|
130
|
+
* `Fabricator/Types.ts`'s `Exhaustion`), running out opens a fresh scope and
|
|
131
|
+
* draws again, as if nothing had been produced; claims go to whichever scope is
|
|
132
|
+
* current. Both exhaustion errors reset: a tracked leaf of unknown size knows
|
|
133
|
+
* it ran out only by hitting its cap.
|
|
134
|
+
*/
|
|
135
|
+
export declare function toLifetimeScope(strategy: Strategy, exhaustion: Exhaustion): Scope;
|
|
@@ -11,4 +11,15 @@ export type DeepMerge<$A, $B> = $B extends {
|
|
|
11
11
|
[_ in $K]?: infer $BV;
|
|
12
12
|
} ? $BV : never;
|
|
13
13
|
}>;
|
|
14
|
+
/**
|
|
15
|
+
* Copies property descriptors rather than values, so a getter stays a getter on
|
|
16
|
+
* the result. The registry depends on that: every registry entry that is a
|
|
17
|
+
* Schema is a getter returning a fresh object (`Schema/Registry.ts`), and a
|
|
18
|
+
* merge that copied its value would pin it to one.
|
|
19
|
+
*
|
|
20
|
+
* Where both sides hold a key, each is read once — a getter included — and the
|
|
21
|
+
* values merge as they always have. If either side was a getter, the result is
|
|
22
|
+
* a getter again, returning a new object {@link rebuilt} from the merged one on
|
|
23
|
+
* every read, so an entry an extension merges into stays fresh.
|
|
24
|
+
*/
|
|
14
25
|
export declare function deepMerge<$A extends PlainObject, $B extends PlainObject>(a: $A, b: $B): DeepMerge<$A, $B>;
|
package/dist/types/index.d.ts
CHANGED
|
@@ -105,6 +105,13 @@ export { registry } from "./Schema/Registry";
|
|
|
105
105
|
*/
|
|
106
106
|
export { effectiveDiscrete, toBound } from "./Bound";
|
|
107
107
|
export type { Bound, InputBound } from "./Bound";
|
|
108
|
+
/**
|
|
109
|
+
* What `.admits(...)` accepts for a group of ends, and how `[Meta].admits`
|
|
110
|
+
* stores it (an absent end states no limit). Exported so an argument built
|
|
111
|
+
* programmatically, or an `.adapt` producer reading `meta.admits`, can be typed
|
|
112
|
+
* — the same rationale as `Bound`.
|
|
113
|
+
*/
|
|
114
|
+
export type { AdmittedEnds, InputAdmittedEnds } from "./Bound";
|
|
108
115
|
/**
|
|
109
116
|
* The `length` shapes `T.string`/`T.array`'s `.whereby(...)` accept and store,
|
|
110
117
|
* and the `distribution` every range-bearing `whereby` takes. Exported so a
|
|
@@ -205,3 +212,9 @@ export type { Trace } from "./Random/Types";
|
|
|
205
212
|
* anything a caller needs to name.
|
|
206
213
|
*/
|
|
207
214
|
export type { Ancestry, Config, Context, Overlay, Stack, } from "./Instance/Types";
|
|
215
|
+
/**
|
|
216
|
+
* `capacity`'s type, and what `combinatorial`/`coverage` return, so a caller
|
|
217
|
+
* holding either can name it.
|
|
218
|
+
*/
|
|
219
|
+
export type { Capacity } from "./Unique/Capacity";
|
|
220
|
+
export type { Enumeration } from "./Enumeration/Types";
|
package/dist/types/internal.d.ts
CHANGED
|
@@ -44,6 +44,15 @@ export type { AsFabricator } from "./Fabricator/Types";
|
|
|
44
44
|
*/
|
|
45
45
|
export { Children, Kind, Meta, Produces, type Buildable, type Produced, } from "./Types";
|
|
46
46
|
export { isArray, isPlainObject } from "./Utility/Core";
|
|
47
|
+
/**
|
|
48
|
+
* The runtime counterparts of `Buildable` and `AnySchema`, for an integration
|
|
49
|
+
* that takes one from an untyped caller. `@ghostry/extern`'s fabricator
|
|
50
|
+
* extension claims a block identity with `isSchema`: a built Fabricator is not
|
|
51
|
+
* an identity, since a block could either continue its streams or build afresh
|
|
52
|
+
* from its schema.
|
|
53
|
+
*/
|
|
54
|
+
export { isBuildable, isSchema } from "./Schema/Core";
|
|
55
|
+
export { toKeyer, type Keyer } from "./Unique/Key";
|
|
47
56
|
export type * as Primitive from "./Primitive/namespace";
|
|
48
57
|
/**
|
|
49
58
|
* `Schema/Types.ts`'s own value-type resolution, needed by tests asserting
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@ghostry/fabricator",
|
|
3
|
-
"version": "0.0.
|
|
3
|
+
"version": "0.0.14",
|
|
4
4
|
"license": "MIT",
|
|
5
5
|
"description": "Fabricate typed data from composable schemas.",
|
|
6
6
|
"keywords": [
|
|
@@ -20,7 +20,7 @@
|
|
|
20
20
|
"url": "git+https://github.com/ghostry-dev/fabricator",
|
|
21
21
|
"directory": "pkg/fabricator"
|
|
22
22
|
},
|
|
23
|
-
"homepage": "https://docs.ghostry.dev/fabricator
|
|
23
|
+
"homepage": "https://docs.ghostry.dev/fabricator",
|
|
24
24
|
"bugs": "https://github.com/ghostry-dev/fabricator/issues",
|
|
25
25
|
"type": "module",
|
|
26
26
|
"sideEffects": false,
|
|
@@ -65,7 +65,7 @@
|
|
|
65
65
|
"provenance": true
|
|
66
66
|
},
|
|
67
67
|
"devDependencies": {
|
|
68
|
-
"@ghostry/harness": "^0.0.
|
|
68
|
+
"@ghostry/harness": "^0.0.6"
|
|
69
69
|
},
|
|
70
70
|
"scripts": {
|
|
71
71
|
"build:reset": "rm -rf ./dist",
|