@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.
Files changed (105) hide show
  1. package/dist/esm/Bound.js +74 -1
  2. package/dist/esm/Distribution/index.js +103 -2
  3. package/dist/esm/Enumeration/Enumerate.js +10 -5
  4. package/dist/esm/Enumeration/Plan.js +2 -2
  5. package/dist/esm/Error/index.js +96 -27
  6. package/dist/esm/Fabricator/Constructor.js +7 -5
  7. package/dist/esm/Instance/Core.js +3 -0
  8. package/dist/esm/Primitive/array/Admits.js +18 -0
  9. package/dist/esm/Primitive/array/Fabricator.js +20 -2
  10. package/dist/esm/Primitive/array/Registry.js +32 -0
  11. package/dist/esm/Primitive/array/Schema.js +8 -0
  12. package/dist/esm/Primitive/bigint/Admits.js +11 -0
  13. package/dist/esm/Primitive/bigint/Fabricator.js +16 -23
  14. package/dist/esm/Primitive/bigint/Registry.js +17 -6
  15. package/dist/esm/Primitive/bigint/Schema.js +8 -0
  16. package/dist/esm/Primitive/date/Admits.js +22 -0
  17. package/dist/esm/Primitive/date/Defaults.js +27 -1
  18. package/dist/esm/Primitive/date/Fabricator.js +32 -34
  19. package/dist/esm/Primitive/date/Registry.js +80 -13
  20. package/dist/esm/Primitive/date/Schema.js +8 -0
  21. package/dist/esm/Primitive/enum/Fabricator.js +14 -2
  22. package/dist/esm/Primitive/enum/Registry.js +38 -25
  23. package/dist/esm/Primitive/index.js +1 -0
  24. package/dist/esm/Primitive/number/Admits.js +27 -0
  25. package/dist/esm/Primitive/number/Fabricator.js +18 -9
  26. package/dist/esm/Primitive/number/Registry.js +55 -4
  27. package/dist/esm/Primitive/number/Schema.js +10 -3
  28. package/dist/esm/Primitive/object/Fabricator.js +2 -0
  29. package/dist/esm/Primitive/record/Admits.js +42 -0
  30. package/dist/esm/Primitive/record/Fabricator.js +49 -19
  31. package/dist/esm/Primitive/record/Registry.js +29 -0
  32. package/dist/esm/Primitive/record/Schema.js +8 -0
  33. package/dist/esm/Primitive/recursive/Fabricator.js +3 -2
  34. package/dist/esm/Primitive/recursive/Terminate.js +16 -2
  35. package/dist/esm/Primitive/string/Admits.js +26 -0
  36. package/dist/esm/Primitive/string/Capacity.js +81 -0
  37. package/dist/esm/Primitive/string/Fabricator.js +23 -43
  38. package/dist/esm/Primitive/string/Registry.js +31 -9
  39. package/dist/esm/Primitive/string/Schema.js +10 -3
  40. package/dist/esm/Primitive/string/Sources.js +41 -0
  41. package/dist/esm/Primitive/unique/Registry.js +22 -0
  42. package/dist/esm/Primitive/unique/index.js +2 -0
  43. package/dist/esm/Types.js +2 -1
  44. package/dist/esm/Unique/Capacity.js +85 -0
  45. package/dist/esm/Unique/Distinct.js +187 -0
  46. package/dist/esm/Unique/Key.js +70 -0
  47. package/dist/esm/Unique/Override.js +23 -0
  48. package/dist/esm/Unique/Strategy.js +173 -0
  49. package/dist/esm/internal.js +1 -0
  50. package/dist/types/Bound.d.ts +66 -0
  51. package/dist/types/Distribution/index.d.ts +82 -0
  52. package/dist/types/Enumeration/Types.d.ts +10 -1
  53. package/dist/types/Error/index.d.ts +283 -0
  54. package/dist/types/Fabricator/Constructor.d.ts +6 -2
  55. package/dist/types/Fabricator/Types.d.ts +13 -0
  56. package/dist/types/Instance/Types.d.ts +14 -0
  57. package/dist/types/Primitive/array/Admits.d.ts +7 -0
  58. package/dist/types/Primitive/array/Fabricator.d.ts +2 -2
  59. package/dist/types/Primitive/array/Registry.d.ts +38 -1
  60. package/dist/types/Primitive/array/Schema.d.ts +6 -1
  61. package/dist/types/Primitive/array/Types.d.ts +33 -1
  62. package/dist/types/Primitive/bigint/Admits.d.ts +7 -0
  63. package/dist/types/Primitive/bigint/Fabricator.d.ts +3 -1
  64. package/dist/types/Primitive/bigint/Registry.d.ts +20 -0
  65. package/dist/types/Primitive/bigint/Schema.d.ts +9 -1
  66. package/dist/types/Primitive/bigint/Types.d.ts +27 -3
  67. package/dist/types/Primitive/date/Admits.d.ts +7 -0
  68. package/dist/types/Primitive/date/Defaults.d.ts +22 -1
  69. package/dist/types/Primitive/date/Fabricator.d.ts +3 -1
  70. package/dist/types/Primitive/date/Registry.d.ts +47 -11
  71. package/dist/types/Primitive/date/Schema.d.ts +10 -1
  72. package/dist/types/Primitive/date/Types.d.ts +53 -4
  73. package/dist/types/Primitive/enum/Fabricator.d.ts +3 -1
  74. package/dist/types/Primitive/enum/Registry.d.ts +20 -0
  75. package/dist/types/Primitive/enum/Types.d.ts +5 -0
  76. package/dist/types/Primitive/index.d.ts +1 -0
  77. package/dist/types/Primitive/number/Admits.d.ts +9 -0
  78. package/dist/types/Primitive/number/Fabricator.d.ts +3 -1
  79. package/dist/types/Primitive/number/Registry.d.ts +42 -1
  80. package/dist/types/Primitive/number/Schema.d.ts +10 -2
  81. package/dist/types/Primitive/number/Types.d.ts +32 -10
  82. package/dist/types/Primitive/record/Admits.d.ts +18 -0
  83. package/dist/types/Primitive/record/Fabricator.d.ts +2 -2
  84. package/dist/types/Primitive/record/Registry.d.ts +18 -1
  85. package/dist/types/Primitive/record/Schema.d.ts +8 -1
  86. package/dist/types/Primitive/record/Types.d.ts +60 -6
  87. package/dist/types/Primitive/recursive/Terminate.d.ts +7 -0
  88. package/dist/types/Primitive/string/Admits.d.ts +8 -0
  89. package/dist/types/Primitive/string/Capacity.d.ts +36 -0
  90. package/dist/types/Primitive/string/Fabricator.d.ts +3 -1
  91. package/dist/types/Primitive/string/Registry.d.ts +26 -5
  92. package/dist/types/Primitive/string/Schema.d.ts +28 -2
  93. package/dist/types/Primitive/string/Sources.d.ts +16 -0
  94. package/dist/types/Primitive/string/Types.d.ts +35 -15
  95. package/dist/types/Primitive/unique/Registry.d.ts +39 -0
  96. package/dist/types/Primitive/unique/index.d.ts +2 -0
  97. package/dist/types/Types.d.ts +9 -0
  98. package/dist/types/Unique/Capacity.d.ts +29 -0
  99. package/dist/types/Unique/Distinct.d.ts +95 -0
  100. package/dist/types/Unique/Key.d.ts +29 -0
  101. package/dist/types/Unique/Override.d.ts +16 -0
  102. package/dist/types/Unique/Strategy.d.ts +135 -0
  103. package/dist/types/index.d.ts +13 -0
  104. package/dist/types/internal.d.ts +1 -0
  105. 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
- * JSON-Schema keywords that constrain a string value — carried as neutral,
38
- * schema-library-agnostic hints (see the builder's `as`). Adapters forward them
39
- * to their target: `toTypeBox` to `Type.String(...)`, a future `toZod` to
40
- * `z.string()` refinements, etc.
41
- *
42
- * Length lives on `whereby` as Bound pairs, which adapters forward as
43
- * `minLength`/`maxLength`; `hints` never duplicates it — these are the
44
- * orthogonal, non-length constraints.
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 JsonSchema = {
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
- hints?: JsonSchema | undefined;
79
+ admits?: Admits | undefined;
80
+ unique?: true;
62
81
  produce?: never;
63
82
  } | {
64
83
  whereby?: Whereby;
65
- hints?: JsonSchema | undefined;
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;
@@ -0,0 +1,2 @@
1
+ export * from "./Registry";
2
+ export { default } from "./Registry";
@@ -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;
@@ -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";
@@ -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.13",
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.5"
68
+ "@ghostry/harness": "^0.0.6"
69
69
  },
70
70
  "scripts": {
71
71
  "build:reset": "rm -rf ./dist",