@ghostry/fabricator 0.0.13 → 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/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/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/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 +80 -13
- 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/number/Admits.js +27 -0
- package/dist/esm/Primitive/number/Fabricator.js +18 -9
- package/dist/esm/Primitive/number/Registry.js +55 -4
- 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/unique/Registry.js +22 -0
- package/dist/esm/Primitive/unique/index.js +2 -0
- 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/internal.js +1 -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/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/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 +47 -11
- 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/number/Admits.d.ts +9 -0
- package/dist/types/Primitive/number/Fabricator.d.ts +3 -1
- package/dist/types/Primitive/number/Registry.d.ts +42 -1
- 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/unique/Registry.d.ts +39 -0
- package/dist/types/Primitive/unique/index.d.ts +2 -0
- 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/index.d.ts +13 -0
- package/dist/types/internal.d.ts +1 -0
- package/package.json +2 -2
|
@@ -1,8 +1,9 @@
|
|
|
1
1
|
import type { Adaptations } from "../../Adapter/Types";
|
|
2
|
-
import type { InputLength, Length } from "../../Bound";
|
|
2
|
+
import type { AdmittedEnds, InputAdmittedEnds, InputLength, Length } from "../../Bound";
|
|
3
3
|
import type { Produce } from "../../Random/Types";
|
|
4
4
|
import type { Adaptation, Kind, Meta, Produced, Produces } from "../../Types";
|
|
5
5
|
import type { classes } from "./Constants";
|
|
6
|
+
import type { Redraws } from "../../Unique/Strategy";
|
|
6
7
|
/** An inclusive range of Unicode code points. */
|
|
7
8
|
export type CodepointRange = {
|
|
8
9
|
from: number;
|
|
@@ -28,25 +29,42 @@ export type InputWhereby = {
|
|
|
28
29
|
length: InputLength;
|
|
29
30
|
composition?: Composition;
|
|
30
31
|
};
|
|
32
|
+
/** `T.unique.string`'s `.whereby`: the same input, plus {@link Redraws}. */
|
|
33
|
+
export type InputUniqueWhereby = InputWhereby & Redraws;
|
|
34
|
+
/** `redraws` is set only through {@link InputUniqueWhereby}. */
|
|
31
35
|
export type Whereby = {
|
|
32
36
|
length: Length;
|
|
33
37
|
composition?: Composition;
|
|
38
|
+
redraws?: number | undefined;
|
|
34
39
|
};
|
|
35
|
-
export type Fabricated = string;
|
|
36
40
|
/**
|
|
37
|
-
*
|
|
38
|
-
*
|
|
39
|
-
*
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
|
|
44
|
-
|
|
41
|
+
* `.admits(...)`'s input: the length an adapter states, widening what `whereby`
|
|
42
|
+
* draws. An end is replaced, `Infinity` (or `-Infinity` for `min`) states no
|
|
43
|
+
* limit, and an omitted end keeps what is admitted already.
|
|
44
|
+
*/
|
|
45
|
+
export type InputAdmits = {
|
|
46
|
+
length?: InputAdmittedEnds<number> | undefined;
|
|
47
|
+
} & Keywords;
|
|
48
|
+
/**
|
|
49
|
+
* JSON-Schema keywords for what the strings are, which adapters forward to
|
|
50
|
+
* their target: `toTypeBox` to `Type.String(...)`, a future `toZod` to
|
|
51
|
+
* `z.string()` refinements. Unlike a length they are not checked against what
|
|
52
|
+
* is drawn — like `.adapt`, the caller vouches that fabricated values match,
|
|
53
|
+
* usually by fabricating through `.as(produce)`. A keyword left out keeps what
|
|
54
|
+
* is admitted already.
|
|
45
55
|
*/
|
|
46
|
-
export type
|
|
47
|
-
format?: string;
|
|
48
|
-
pattern?: string;
|
|
56
|
+
export type Keywords = {
|
|
57
|
+
format?: string | undefined;
|
|
58
|
+
pattern?: string | undefined;
|
|
49
59
|
};
|
|
60
|
+
/**
|
|
61
|
+
* `[Meta].admits`, set only by `.admits(...)` and complete once set: an absent
|
|
62
|
+
* end states no limit (`Admits.ts`'s `toAdmits`).
|
|
63
|
+
*/
|
|
64
|
+
export type Admits = {
|
|
65
|
+
length: AdmittedEnds<number>;
|
|
66
|
+
} & Keywords;
|
|
67
|
+
export type Fabricated = string;
|
|
50
68
|
/**
|
|
51
69
|
* A length and optional composition, drawn via `whereby`. There is no natural
|
|
52
70
|
* bound to fuzz a string to, so unlike `number`/`date` the builder itself has
|
|
@@ -58,11 +76,13 @@ export type JsonSchema = {
|
|
|
58
76
|
*/
|
|
59
77
|
export type Meta = {
|
|
60
78
|
whereby: Whereby;
|
|
61
|
-
|
|
79
|
+
admits?: Admits | undefined;
|
|
80
|
+
unique?: true;
|
|
62
81
|
produce?: never;
|
|
63
82
|
} | {
|
|
64
83
|
whereby?: Whereby;
|
|
65
|
-
|
|
84
|
+
admits?: Admits | undefined;
|
|
85
|
+
unique?: true;
|
|
66
86
|
produce: Produce<Fabricated>;
|
|
67
87
|
};
|
|
68
88
|
export type Core<$Meta extends Meta = Meta, $Adaptations extends Adaptations = {}> = {
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
import { unique as array } from "../array/Registry";
|
|
2
|
+
import { unique as bigint } from "../bigint/Registry";
|
|
3
|
+
import { unique as date } from "../date/Registry";
|
|
4
|
+
import { unique as enumeration } from "../enum/Registry";
|
|
5
|
+
import { unique as number } from "../number/Registry";
|
|
6
|
+
import { unique as record } from "../record/Registry";
|
|
7
|
+
import { unique as string } from "../string/Registry";
|
|
8
|
+
/**
|
|
9
|
+
* `T.unique`: the builders whose Schemas promise distinct values. Not a kind —
|
|
10
|
+
* each builder returns an ordinary Schema of its own kind with `unique` on
|
|
11
|
+
* `[Meta]`, so dispatch, `Fabricated`, and adapters treat it as that kind. Two
|
|
12
|
+
* shapes:
|
|
13
|
+
*
|
|
14
|
+
* - **Leaves** (`enum`, `number`, `bigint`, `string`, `date`) never repeat a
|
|
15
|
+
* value for their built Fabricator's lifetime — across every `.fabricate()`
|
|
16
|
+
* call, and across every `fabricate(schema)` call in one scope.
|
|
17
|
+
* - **Collections** (`array`, `record`) hold distinct members within each value
|
|
18
|
+
* they fabricate, and are free to repeat across values.
|
|
19
|
+
*
|
|
20
|
+
* Each kind's own `Registry.ts` builds its variant beside its ordinary one, so
|
|
21
|
+
* the kind-specific checks and labels stay with the kind; this module only
|
|
22
|
+
* assembles them. See AGENTS.md's "Uniqueness".
|
|
23
|
+
*/
|
|
24
|
+
type ThisRegistry = {
|
|
25
|
+
readonly enum: typeof enumeration;
|
|
26
|
+
/**
|
|
27
|
+
* A getter, like `T.number`: each read is a fresh Schema (AGENTS.md's
|
|
28
|
+
* "Registry entries are getters").
|
|
29
|
+
*/
|
|
30
|
+
readonly number: ReturnType<typeof number>;
|
|
31
|
+
readonly bigint: typeof bigint;
|
|
32
|
+
readonly string: typeof string;
|
|
33
|
+
/** A getter, like `T.date` — see `number`. */
|
|
34
|
+
readonly date: ReturnType<typeof date>;
|
|
35
|
+
readonly array: typeof array;
|
|
36
|
+
readonly record: typeof record;
|
|
37
|
+
};
|
|
38
|
+
declare const registry: ThisRegistry;
|
|
39
|
+
export default 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;
|
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
|
@@ -52,6 +52,7 @@ export { isArray, isPlainObject } from "./Utility/Core";
|
|
|
52
52
|
* from its schema.
|
|
53
53
|
*/
|
|
54
54
|
export { isBuildable, isSchema } from "./Schema/Core";
|
|
55
|
+
export { toKeyer, type Keyer } from "./Unique/Key";
|
|
55
56
|
export type * as Primitive from "./Primitive/namespace";
|
|
56
57
|
/**
|
|
57
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": [
|
|
@@ -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",
|