@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.
Files changed (122) hide show
  1. package/README.md +1 -1
  2. package/dist/esm/Bound.js +74 -1
  3. package/dist/esm/Distribution/index.js +103 -2
  4. package/dist/esm/Enumeration/Enumerate.js +10 -5
  5. package/dist/esm/Enumeration/Plan.js +2 -2
  6. package/dist/esm/Error/index.js +96 -27
  7. package/dist/esm/Fabricator/Constructor.js +7 -5
  8. package/dist/esm/Fabricator/Fabricate.js +1 -6
  9. package/dist/esm/Instance/Core.js +3 -0
  10. package/dist/esm/Primitive/array/Admits.js +18 -0
  11. package/dist/esm/Primitive/array/Fabricator.js +20 -2
  12. package/dist/esm/Primitive/array/Registry.js +32 -0
  13. package/dist/esm/Primitive/array/Schema.js +8 -0
  14. package/dist/esm/Primitive/bigint/Admits.js +11 -0
  15. package/dist/esm/Primitive/bigint/Fabricator.js +16 -23
  16. package/dist/esm/Primitive/bigint/Registry.js +17 -6
  17. package/dist/esm/Primitive/bigint/Schema.js +8 -0
  18. package/dist/esm/Primitive/boolean/Registry.js +10 -8
  19. package/dist/esm/Primitive/date/Admits.js +22 -0
  20. package/dist/esm/Primitive/date/Defaults.js +27 -1
  21. package/dist/esm/Primitive/date/Fabricator.js +32 -34
  22. package/dist/esm/Primitive/date/Registry.js +111 -38
  23. package/dist/esm/Primitive/date/Schema.js +8 -0
  24. package/dist/esm/Primitive/enum/Fabricator.js +14 -2
  25. package/dist/esm/Primitive/enum/Registry.js +38 -25
  26. package/dist/esm/Primitive/index.js +1 -0
  27. package/dist/esm/Primitive/null/Registry.js +6 -4
  28. package/dist/esm/Primitive/number/Admits.js +27 -0
  29. package/dist/esm/Primitive/number/Fabricator.js +18 -9
  30. package/dist/esm/Primitive/number/Registry.js +86 -29
  31. package/dist/esm/Primitive/number/Schema.js +10 -3
  32. package/dist/esm/Primitive/object/Fabricator.js +2 -0
  33. package/dist/esm/Primitive/record/Admits.js +42 -0
  34. package/dist/esm/Primitive/record/Fabricator.js +49 -19
  35. package/dist/esm/Primitive/record/Registry.js +29 -0
  36. package/dist/esm/Primitive/record/Schema.js +8 -0
  37. package/dist/esm/Primitive/recursive/Fabricator.js +3 -2
  38. package/dist/esm/Primitive/recursive/Terminate.js +16 -2
  39. package/dist/esm/Primitive/string/Admits.js +26 -0
  40. package/dist/esm/Primitive/string/Capacity.js +81 -0
  41. package/dist/esm/Primitive/string/Fabricator.js +23 -43
  42. package/dist/esm/Primitive/string/Registry.js +31 -9
  43. package/dist/esm/Primitive/string/Schema.js +10 -3
  44. package/dist/esm/Primitive/string/Sources.js +41 -0
  45. package/dist/esm/Primitive/symbol/Registry.js +15 -13
  46. package/dist/esm/Primitive/undefined/Registry.js +6 -4
  47. package/dist/esm/Primitive/unique/Registry.js +22 -0
  48. package/dist/esm/Primitive/unique/index.js +2 -0
  49. package/dist/esm/Schema/Core.js +9 -1
  50. package/dist/esm/Schema/Registry.js +27 -7
  51. package/dist/esm/Types.js +2 -1
  52. package/dist/esm/Unique/Capacity.js +85 -0
  53. package/dist/esm/Unique/Distinct.js +187 -0
  54. package/dist/esm/Unique/Key.js +70 -0
  55. package/dist/esm/Unique/Override.js +23 -0
  56. package/dist/esm/Unique/Strategy.js +173 -0
  57. package/dist/esm/Utility/DeepMerge.js +47 -6
  58. package/dist/esm/internal.js +2 -0
  59. package/dist/types/Bound.d.ts +66 -0
  60. package/dist/types/Distribution/index.d.ts +82 -0
  61. package/dist/types/Enumeration/Types.d.ts +10 -1
  62. package/dist/types/Error/index.d.ts +283 -0
  63. package/dist/types/Fabricator/Constructor.d.ts +6 -2
  64. package/dist/types/Fabricator/Fabricate.d.ts +4 -2
  65. package/dist/types/Fabricator/Types.d.ts +13 -0
  66. package/dist/types/Instance/Types.d.ts +14 -0
  67. package/dist/types/Primitive/array/Admits.d.ts +7 -0
  68. package/dist/types/Primitive/array/Fabricator.d.ts +2 -2
  69. package/dist/types/Primitive/array/Registry.d.ts +38 -1
  70. package/dist/types/Primitive/array/Schema.d.ts +6 -1
  71. package/dist/types/Primitive/array/Types.d.ts +33 -1
  72. package/dist/types/Primitive/bigint/Admits.d.ts +7 -0
  73. package/dist/types/Primitive/bigint/Fabricator.d.ts +3 -1
  74. package/dist/types/Primitive/bigint/Registry.d.ts +20 -0
  75. package/dist/types/Primitive/bigint/Schema.d.ts +9 -1
  76. package/dist/types/Primitive/bigint/Types.d.ts +27 -3
  77. package/dist/types/Primitive/boolean/Registry.d.ts +6 -1
  78. package/dist/types/Primitive/date/Admits.d.ts +7 -0
  79. package/dist/types/Primitive/date/Defaults.d.ts +22 -1
  80. package/dist/types/Primitive/date/Fabricator.d.ts +3 -1
  81. package/dist/types/Primitive/date/Registry.d.ts +54 -12
  82. package/dist/types/Primitive/date/Schema.d.ts +10 -1
  83. package/dist/types/Primitive/date/Types.d.ts +53 -4
  84. package/dist/types/Primitive/enum/Fabricator.d.ts +3 -1
  85. package/dist/types/Primitive/enum/Registry.d.ts +20 -0
  86. package/dist/types/Primitive/enum/Types.d.ts +5 -0
  87. package/dist/types/Primitive/index.d.ts +1 -0
  88. package/dist/types/Primitive/null/Registry.d.ts +6 -1
  89. package/dist/types/Primitive/number/Admits.d.ts +9 -0
  90. package/dist/types/Primitive/number/Fabricator.d.ts +3 -1
  91. package/dist/types/Primitive/number/Registry.d.ts +50 -2
  92. package/dist/types/Primitive/number/Schema.d.ts +10 -2
  93. package/dist/types/Primitive/number/Types.d.ts +32 -10
  94. package/dist/types/Primitive/record/Admits.d.ts +18 -0
  95. package/dist/types/Primitive/record/Fabricator.d.ts +2 -2
  96. package/dist/types/Primitive/record/Registry.d.ts +18 -1
  97. package/dist/types/Primitive/record/Schema.d.ts +8 -1
  98. package/dist/types/Primitive/record/Types.d.ts +60 -6
  99. package/dist/types/Primitive/recursive/Terminate.d.ts +7 -0
  100. package/dist/types/Primitive/string/Admits.d.ts +8 -0
  101. package/dist/types/Primitive/string/Capacity.d.ts +36 -0
  102. package/dist/types/Primitive/string/Fabricator.d.ts +3 -1
  103. package/dist/types/Primitive/string/Registry.d.ts +26 -5
  104. package/dist/types/Primitive/string/Schema.d.ts +28 -2
  105. package/dist/types/Primitive/string/Sources.d.ts +16 -0
  106. package/dist/types/Primitive/string/Types.d.ts +35 -15
  107. package/dist/types/Primitive/symbol/Registry.d.ts +6 -1
  108. package/dist/types/Primitive/undefined/Registry.d.ts +6 -1
  109. package/dist/types/Primitive/unique/Registry.d.ts +39 -0
  110. package/dist/types/Primitive/unique/index.d.ts +2 -0
  111. package/dist/types/Schema/Core.d.ts +16 -1
  112. package/dist/types/Schema/Registry.d.ts +7 -4
  113. package/dist/types/Types.d.ts +9 -0
  114. package/dist/types/Unique/Capacity.d.ts +29 -0
  115. package/dist/types/Unique/Distinct.d.ts +95 -0
  116. package/dist/types/Unique/Key.d.ts +29 -0
  117. package/dist/types/Unique/Override.d.ts +16 -0
  118. package/dist/types/Unique/Strategy.d.ts +135 -0
  119. package/dist/types/Utility/DeepMerge.d.ts +11 -0
  120. package/dist/types/index.d.ts +13 -0
  121. package/dist/types/internal.d.ts +9 -0
  122. package/package.json +3 -3
@@ -132,6 +132,88 @@ export declare function sample<$T>(list: ReadonlyArray<$T>, stream: Stream): $T;
132
132
  * `items`, matching `sample`/`weighted`'s read-only convention.
133
133
  */
134
134
  export declare function shuffle<$T>(items: ReadonlyArray<$T>, stream: Stream): $T[];
135
+ /**
136
+ * A weighted draw that never returns the same entry twice — each pick leaves
137
+ * the pool. The first pick follows `entries`' weights exactly as `weighted()`
138
+ * would; every later one follows the weights of what remains, which is the same
139
+ * distribution conditioned on not repeating.
140
+ */
141
+ export type Pool<$Item> = {
142
+ /** How many entries are left to draw. */
143
+ readonly remaining: number;
144
+ /**
145
+ * Remove and return one entry. The caller checks `remaining` first: an empty
146
+ * pool has nothing to return.
147
+ */
148
+ draw: () => $Item;
149
+ /**
150
+ * Remove the first remaining entry `matches` accepts, without drawing — for
151
+ * an entry produced some other way. A no-op when none matches.
152
+ */
153
+ discard: (matches: (item: $Item) => boolean) => void;
154
+ };
155
+ /**
156
+ * A {@link Pool} over `entries`' drawable members (`isDrawable`; a zero weight
157
+ * stays out, as in `weighted()`). Linear in the pool's size per draw, which
158
+ * suits the small, caller-written member lists it is built from (`enum`'s
159
+ * members, `boolean`'s two outcomes).
160
+ *
161
+ * Equal weights stay equal as entries leave, so that case is fixed once: the
162
+ * pick is `discreteSampler`'s uniform index, one `stream.next()` per draw.
163
+ * Unequal weights take one `stream.next()` scaled over the remaining total,
164
+ * summed afresh each draw so removals never accumulate float drift. `splice`,
165
+ * not swap-remove, so the remaining order stays the caller's.
166
+ */
167
+ export declare function withoutReplacement<$Item>(entries: ReadonlyArray<readonly [number, $Item]>, stream: Stream): Pool<$Item>;
168
+ /**
169
+ * Every integer of an inclusive range, in a uniformly random order, one per
170
+ * `next()` — so no value repeats until all of them have been returned.
171
+ */
172
+ export type Permutation<$T extends number | bigint> = {
173
+ /** How many values are left before the range is used up. */
174
+ readonly remaining: $T;
175
+ /**
176
+ * The next value. The caller checks `remaining` first: a used-up range has
177
+ * nothing to return.
178
+ */
179
+ next: () => $T;
180
+ };
181
+ /**
182
+ * A sparse Fisher–Yates shuffle of `[min, max]`: step `i` swaps position `i`
183
+ * with a uniform position `j` in `[i, size)` and returns what was at `j`. Only
184
+ * positions a swap has touched live in `displaced`, so memory grows with the
185
+ * values drawn, never with the range — `[1, 2^53]` costs nothing up front.
186
+ * Position `i` is never read again after its step, so its entry is deleted.
187
+ *
188
+ * The index draw is `discreteSampler`'s, never an inlined `floor(next() * n)`
189
+ * (see AGENTS.md's "Traps in the length/size draw"). Precondition: `max - min +
190
+ * 1 <= Number.MAX_SAFE_INTEGER`, so every position is an exact integer.
191
+ */
192
+ export declare function permutation(range: Range, stream: Stream): Permutation<number>;
193
+ /**
194
+ * {@link permutation} over a bigint range, with {@link bigintSampler} drawing
195
+ * each step's position. No size precondition: bigint positions are exact at any
196
+ * width.
197
+ */
198
+ export declare function bigintPermutation(range: {
199
+ min: bigint;
200
+ max: bigint;
201
+ }, stream: Stream): Permutation<bigint>;
202
+ /**
203
+ * A uniform bigint draw over the inclusive `[min, max]`.
204
+ *
205
+ * Fills a buffer one byte at a time from the seeded stream — the top 8 bits of
206
+ * each draw — so bigint generation replays under a salt like every other
207
+ * primitive, rather than drawing unseedable bytes from
208
+ * `crypto.getRandomValues`. Then rejection: keep the low `bitWidth` bits and
209
+ * retry any candidate past the span, which avoids the modulo bias of `random %
210
+ * span`. The mask keeps every candidate within one bit of the span, so the loop
211
+ * expects fewer than two iterations.
212
+ */
213
+ export declare function bigintSampler(range: {
214
+ min: bigint;
215
+ max: bigint;
216
+ }, stream: Stream): () => bigint;
135
217
  /**
136
218
  * `weighted()`'s own inclusion rule: whether this entry stays in the draw
137
219
  * table. `0` is valid and disables the outcome; negative/`NaN` are rejected
@@ -73,7 +73,16 @@ export type Limits = {
73
73
  * Fabricator: `AnySchema` excludes `Fabricator<any>` (which carries no
74
74
  * `[Produces]`), so `Fabricated` can't silently degrade to `unknown`.
75
75
  */
76
- export type Enumerable = <const $Schema extends AnySchema>(schema: $Schema) => Iterable<Fabricated<$Schema>>;
76
+ export type Enumerable = <const $Schema extends AnySchema>(schema: $Schema) => Enumeration<Fabricated<$Schema>>;
77
+ /**
78
+ * What `combinatorial`/`coverage` return: the lazy instances, plus `size`, how
79
+ * many there are — known before any is produced. When compared against
80
+ * `capacity(schema)`, it says up front whether every instance can hold distinct
81
+ * unique values, or whether some leaf will start a fresh round.
82
+ */
83
+ export type Enumeration<$T> = Iterable<$T> & {
84
+ readonly size: bigint;
85
+ };
77
86
  export type Resolvable = {
78
87
  [Kind]: SchemaKind;
79
88
  [Meta]: PlainObject<any>;
@@ -12,6 +12,13 @@
12
12
  * stands on its own: a consumer reading only `.message` should not need a field
13
13
  * to understand the failure. Fields are for programmatic access, and for detail
14
14
  * too bulky to inline.
15
+ *
16
+ * A `name` is the package and the class,
17
+ * `"@ghostry/fabricator:UnknownFieldError"`, so it identifies an error where
18
+ * `instanceof` cannot: across two installed copies of this package, or after
19
+ * the error is serialized. `:`, not `/`, which would read as a subpath export.
20
+ * A package extending {@link FabricatorError} prefixes its own errors with its
21
+ * own name.
15
22
  */
16
23
  /**
17
24
  * Base error class from which more specific errors inherit.
@@ -101,6 +108,46 @@ export declare namespace FabricatorError {
101
108
  */
102
109
  path: ReadonlyArray<string>);
103
110
  }
111
+ /**
112
+ * `T.recursive(body).whereby({ depth })` with no `terminal`, when the derived
113
+ * terminal must empty a collection of `self` that states a minimum above 0.
114
+ * Every branch ends at the depth limit with that collection empty, and an
115
+ * adapter states the minimum as written, so no finite tree could pass the
116
+ * validation it builds. Thrown at `.whereby()`. `.admits({ length: { min: 0 }
117
+ * })` on the collection keeps drawing at least the minimum below the limit
118
+ * while stating none for the adapter.
119
+ */
120
+ class UnsatisfiableRecursiveBoundError extends FabricatorError {
121
+ /**
122
+ * Structural path from the recursive body to the collection, as field
123
+ * names / slot indices.
124
+ */
125
+ readonly path: ReadonlyArray<string>;
126
+ /**
127
+ * The collection's bound — `"length"` for an array, `"size"` for a
128
+ * record.
129
+ */
130
+ readonly key: "length" | "size";
131
+ /**
132
+ * The smallest count the collection states, as an inclusive integer.
133
+ */
134
+ readonly min: number;
135
+ constructor(
136
+ /**
137
+ * Structural path from the recursive body to the collection, as field
138
+ * names / slot indices.
139
+ */
140
+ path: ReadonlyArray<string>,
141
+ /**
142
+ * The collection's bound — `"length"` for an array, `"size"` for a
143
+ * record.
144
+ */
145
+ key: "length" | "size",
146
+ /**
147
+ * The smallest count the collection states, as an inclusive integer.
148
+ */
149
+ min: number);
150
+ }
104
151
  /**
105
152
  * A walk reached a node whose `[Kind]` it has no case for — a Schema built by
106
153
  * hand or cast past the type system, or a kind added to `Primitive/index.ts`
@@ -469,6 +516,102 @@ export declare namespace FabricatorError {
469
516
  readonly exclusive: boolean;
470
517
  });
471
518
  }
519
+ /**
520
+ * A bound given as a `number` that does not convert exactly to its kind's
521
+ * type — a fractional or unsafe integer for a `bigint`, an instant `Date`
522
+ * cannot hold — or a non-finite value where an end must be finite.
523
+ */
524
+ class InvalidBoundError extends FabricatorError {
525
+ /**
526
+ * What was called, e.g. `"T.bigint.whereby"` or `".admits on a bigint
527
+ * schema"`.
528
+ */
529
+ readonly label: string;
530
+ /**
531
+ * Which end was rejected.
532
+ */
533
+ readonly end: "min" | "max";
534
+ /**
535
+ * The rejected value, as given.
536
+ */
537
+ readonly value: number;
538
+ /**
539
+ * What the end accepts, in words — e.g. `"a safe integer or a bigint"`.
540
+ */
541
+ readonly expected: string;
542
+ constructor(
543
+ /**
544
+ * What was called, e.g. `"T.bigint.whereby"` or `".admits on a bigint
545
+ * schema"`.
546
+ */
547
+ label: string,
548
+ /**
549
+ * Which end was rejected.
550
+ */
551
+ end: "min" | "max",
552
+ /**
553
+ * The rejected value, as given.
554
+ */
555
+ value: number,
556
+ /**
557
+ * What the end accepts, in words — e.g. `"a safe integer or a bigint"`.
558
+ */
559
+ expected: string);
560
+ }
561
+ /**
562
+ * `.admits(...)` names an end that excludes values the schema fabricates.
563
+ * Admitted ends may only widen the fabricated range — a fabricated value must
564
+ * pass the validation an adapter builds from them.
565
+ */
566
+ class AdmitsExcludesDrawError extends FabricatorError {
567
+ /**
568
+ * What was called, e.g. `".admits on a string schema"`.
569
+ */
570
+ readonly label: string;
571
+ /**
572
+ * The rejected end's path, e.g. `"length.max"` or `"min"`.
573
+ */
574
+ readonly end: string;
575
+ /**
576
+ * The admitted end, canonical as stored.
577
+ */
578
+ readonly admitted: {
579
+ readonly value: unknown;
580
+ readonly exclusive: boolean;
581
+ };
582
+ /**
583
+ * The fabricated end it excludes values from; absent when that end is
584
+ * drawn against the kind's unbounded cap, which only no limit admits.
585
+ */
586
+ readonly fabricated: {
587
+ readonly value: unknown;
588
+ readonly exclusive: boolean;
589
+ } | undefined;
590
+ constructor(
591
+ /**
592
+ * What was called, e.g. `".admits on a string schema"`.
593
+ */
594
+ label: string,
595
+ /**
596
+ * The rejected end's path, e.g. `"length.max"` or `"min"`.
597
+ */
598
+ end: string,
599
+ /**
600
+ * The admitted end, canonical as stored.
601
+ */
602
+ admitted: {
603
+ readonly value: unknown;
604
+ readonly exclusive: boolean;
605
+ },
606
+ /**
607
+ * The fabricated end it excludes values from; absent when that end is
608
+ * drawn against the kind's unbounded cap, which only no limit admits.
609
+ */
610
+ fabricated: {
611
+ readonly value: unknown;
612
+ readonly exclusive: boolean;
613
+ } | undefined);
614
+ }
472
615
  /**
473
616
  * A distribution's bounds fall outside its own domain — a `logarithmic`
474
617
  * distribution's density is proportional to `1/x`, so it is undefined at or
@@ -648,4 +791,144 @@ export declare namespace FabricatorError {
648
791
  class HarnessingProviderError extends FabricatorError {
649
792
  constructor();
650
793
  }
794
+ /**
795
+ * Where a unique leaf that ran out sits directly inside a plain collection —
796
+ * the element of a `T.array` or the key of a `T.record`. Such a leaf stays
797
+ * distinct across every value the collection makes, which is easy to mistake
798
+ * for distinct within one, so the message names `T.unique.array`/
799
+ * `T.unique.record`.
800
+ */
801
+ type UniqueWithin = "array" | "record";
802
+ /**
803
+ * A `T.unique.*` leaf asked for one more value than its domain holds. Thrown
804
+ * on draw n + 1 of an n-value domain whatever the salt, since a domain with a
805
+ * known size is counted rather than searched (`Unique/Distinct.ts`).
806
+ */
807
+ class UniqueExhaustedError extends FabricatorError {
808
+ /**
809
+ * The `[Kind]` of the exhausted schema.
810
+ */
811
+ readonly kind: string;
812
+ /**
813
+ * How many distinct values the domain holds — every one of them already
814
+ * produced or claimed.
815
+ */
816
+ readonly capacity: bigint;
817
+ /**
818
+ * The plain collection the leaf sits directly inside, when it does.
819
+ */
820
+ readonly collection?: UniqueWithin | undefined;
821
+ constructor(
822
+ /**
823
+ * The `[Kind]` of the exhausted schema.
824
+ */
825
+ kind: string,
826
+ /**
827
+ * How many distinct values the domain holds — every one of them already
828
+ * produced or claimed.
829
+ */
830
+ capacity: bigint,
831
+ /**
832
+ * The plain collection the leaf sits directly inside, when it does.
833
+ */
834
+ collection?: UniqueWithin | undefined);
835
+ }
836
+ /**
837
+ * A unique draw over a domain of unknown size kept landing on values it had
838
+ * already produced, and forfeited after its redraws ran out rather than loop
839
+ * forever. Either the domain is used up, or it is skewed enough that its
840
+ * remaining values are rare — a higher `redraws` is for the second case.
841
+ */
842
+ class UniqueRedrawsError extends FabricatorError {
843
+ /**
844
+ * The registry entry or call site, e.g. `"T.unique.array"`.
845
+ */
846
+ readonly label: string;
847
+ /**
848
+ * How many redraws the draw was allowed after its first, each of which
849
+ * also repeated a value already produced.
850
+ */
851
+ readonly redraws: number;
852
+ /**
853
+ * How many distinct values the scope had produced when it gave up.
854
+ */
855
+ readonly produced: number;
856
+ /**
857
+ * The plain collection a unique leaf sits directly inside, when it does.
858
+ */
859
+ readonly collection?: UniqueWithin | undefined;
860
+ constructor(
861
+ /**
862
+ * The registry entry or call site, e.g. `"T.unique.array"`.
863
+ */
864
+ label: string,
865
+ /**
866
+ * How many redraws the draw was allowed after its first, each of which
867
+ * also repeated a value already produced.
868
+ */
869
+ redraws: number,
870
+ /**
871
+ * How many distinct values the scope had produced when it gave up.
872
+ */
873
+ produced: number,
874
+ /**
875
+ * The plain collection a unique leaf sits directly inside, when it does.
876
+ */
877
+ collection?: UniqueWithin | undefined);
878
+ }
879
+ /**
880
+ * A unique collection could draw more members than its member schema has
881
+ * distinct values. Thrown at construction, so the draw that would run out
882
+ * never depends on the salt.
883
+ */
884
+ class UniqueCapacityError extends FabricatorError {
885
+ /**
886
+ * The registry entry, e.g. `"T.unique.array"`.
887
+ */
888
+ readonly label: string;
889
+ /**
890
+ * How many distinct values the member schema has.
891
+ */
892
+ readonly capacity: bigint;
893
+ /**
894
+ * The largest member count the collection may draw.
895
+ */
896
+ readonly requested: number;
897
+ constructor(
898
+ /**
899
+ * The registry entry, e.g. `"T.unique.array"`.
900
+ */
901
+ label: string,
902
+ /**
903
+ * How many distinct values the member schema has.
904
+ */
905
+ capacity: bigint,
906
+ /**
907
+ * The largest member count the collection may draw.
908
+ */
909
+ requested: number);
910
+ }
911
+ /**
912
+ * `redraws` on a unique builder is not a whole number from `0` up, so it
913
+ * could never be a count of retries.
914
+ */
915
+ class InvalidRedrawsError extends FabricatorError {
916
+ /**
917
+ * The registry entry, e.g. `"T.unique.array.whereby"`.
918
+ */
919
+ readonly label: string;
920
+ /**
921
+ * The rejected value.
922
+ */
923
+ readonly redraws: number;
924
+ constructor(
925
+ /**
926
+ * The registry entry, e.g. `"T.unique.array.whereby"`.
927
+ */
928
+ label: string,
929
+ /**
930
+ * The rejected value.
931
+ */
932
+ redraws: number);
933
+ }
651
934
  }
@@ -1,7 +1,7 @@
1
1
  import type { Ancestry, Stack } from "../Instance/Types";
2
2
  import type { ConstructorOptions, RandomSource } from "../Random/Types";
3
3
  import { type Buildable } from "../Types";
4
- import { type AsFabricator } from "./Types";
4
+ import { type AsFabricator, type Exhaustion } from "./Types";
5
5
  /**
6
6
  * The type of `construct()` itself, as handed back by `Constructor` — kept
7
7
  * separate so `initialize`'s return type (`src/index.ts`) can name it without
@@ -40,5 +40,9 @@ export type Constructor = {
40
40
  * should resolve "now" against. `toConstructionContext` reads it straight off
41
41
  * the resolved construction trace rather than threading a second value
42
42
  * alongside `source`.
43
+ *
44
+ * `exhaustion` is how this constructor's `T.unique.*` leaves treat running out
45
+ * (`Fabricator/Types.ts`'s `Exhaustion`); only `Enumeration/Enumerate.ts`
46
+ * passes anything but the default.
43
47
  */
44
- export declare function Constructor(source: RandomSource, stack: Stack, ancestry: Ancestry): Constructor;
48
+ export declare function Constructor(source: RandomSource, stack: Stack, ancestry: Ancestry, exhaustion?: Exhaustion): Constructor;
@@ -12,8 +12,10 @@ import type { NaiveFabricator } from "./Types";
12
12
  * The key is the schema's identity. A schema held in a variable — including an
13
13
  * overridden one, `const Admin = User.override({ ... })` — is reused. One
14
14
  * written at the call site — `fabricate(User.override({ ... }))`, an inline
15
- * `.whereby(...)` — is a new object on every call, so every call builds and
16
- * takes an ordinal, exactly as `new Fabricator(...).fabricate()` would.
15
+ * `.whereby(...)`, a bare registry entry like `fabricate(T.number)`, whose
16
+ * every read is a fresh Schema — is a new object on every call, so every call
17
+ * builds and takes an ordinal, exactly as `new Fabricator(...).fabricate()`
18
+ * would.
17
19
  *
18
20
  * A Schema only, never a built Fabricator: given one, neither reusing it nor
19
21
  * caching a fresh build of it is the obvious reading, so the type rejects it
@@ -47,7 +47,19 @@ export type ConstructionContext = {
47
47
  algorithm: Algorithm;
48
48
  fork: (salt: Salt) => RandomSource;
49
49
  self?: (() => unknown) | undefined;
50
+ exhaustion: Exhaustion;
50
51
  };
52
+ /**
53
+ * What a `T.unique.*` leaf does once its values run out. `"throw"` everywhere
54
+ * except `combinatorial`/`coverage`, whose builds pass `"cycle"`
55
+ * (`Enumeration/Enumerate.ts`): an enumeration is a testing schedule over its
56
+ * axes, and a unique leaf with fewer values than the schedule has instances
57
+ * starts a fresh round rather than failing the schedule partway. Carried on the
58
+ * construction rather than the Schema, so the same Schema throws when built
59
+ * anywhere else. Unique collections are unaffected: cycling inside one array
60
+ * would repeat a member within one value.
61
+ */
62
+ export type Exhaustion = "throw" | "cycle";
51
63
  /**
52
64
  * What every kind's `Fabricator(...)` receives in place of a repeated `(schema,
53
65
  * algorithm, trace)` positional list — `Constructor.ts`'s `make` builds one per
@@ -68,6 +80,7 @@ export type FabricatorContext<$Schema> = {
68
80
  schema: $Schema;
69
81
  algorithm: Algorithm;
70
82
  trace: Trace;
83
+ exhaustion: Exhaustion;
71
84
  };
72
85
  /**
73
86
  * The most basic interface for a typed Fabricator. No type introspection is
@@ -1,3 +1,4 @@
1
+ import type { Capacity } from "../Unique/Capacity";
1
2
  import type { Enumerable, Limits } from "../Enumeration/Types";
2
3
  import type { Constructor } from "../Fabricator/Constructor";
3
4
  import type { Fabricate } from "../Fabricator/Fabricate";
@@ -286,6 +287,19 @@ export interface Instance<$Registry extends PlainObject> extends Pick<RandomSour
286
287
  * it carries no limit.
287
288
  */
288
289
  coverage: Enumerable;
290
+ /**
291
+ * How many times one built Fabricator of `schema` can `fabricate()` before a
292
+ * `T.unique.*` leaf runs out, or `undefined` when no leaf has a known limit.
293
+ * For a fresh Fabricator, so it does not count what an existing one has
294
+ * drawn. Builds nothing, so it shifts no later draw. A `date` leaf's
295
+ * `past`/`future` end is read against the built Fabricator's clock when one
296
+ * is passed, otherwise against `context.clock`. See `Unique/Capacity.ts` for
297
+ * what it counts.
298
+ *
299
+ * Compare it with `coverage(schema).size` or `combinatorial(schema).size` to
300
+ * know whether every enumerated instance can hold distinct values.
301
+ */
302
+ capacity: Capacity;
289
303
  /**
290
304
  * Derive a new instance laid over this one: anything the overlay names
291
305
  * overrides, anything it omits inherits. A bare `salt` replaces this
@@ -0,0 +1,7 @@
1
+ import type { Admits, InputAdmits, Meta } from "./Types";
2
+ /**
3
+ * Resolve `.admits(...)` against what is admitted already: `meta.admits`, or by
4
+ * default the drawn `length` — what an adapter states without one. Under
5
+ * `.as(produce)` nothing is drawn, so nothing is checked.
6
+ */
7
+ export declare function toAdmits(meta: Meta, input: InputAdmits): Admits;
@@ -1,5 +1,5 @@
1
1
  import type { AdaptationsOf } from "../../Adapter/Types";
2
- import type { FabricatorContext, NaiveFabricator } from "../../Fabricator/Types";
2
+ import type { Fabricator as BaseFabricator, FabricatorContext, NaiveFabricator } from "../../Fabricator/Types";
3
3
  import type { Trace } from "../../Random/Types";
4
4
  import { Children, Kind, Meta, type Adaptation } from "../../Types";
5
5
  import { Schema } from "./Schema";
@@ -19,4 +19,4 @@ export type Fabricator<$Schema extends {
19
19
  readonly [Adaptation]?: AdaptationsOf<$Schema>;
20
20
  schema: Schema<$Schema[typeof Meta]["definition"], AdaptationsOf<$Schema>>;
21
21
  };
22
- export declare function Fabricator<$Definition extends Definition>(context: FabricatorContext<Schema<$Definition>>, element: NaiveFabricator<any>): Fabricator<Schema<$Definition>>;
22
+ export declare function Fabricator<$Definition extends Definition>(context: FabricatorContext<Schema<$Definition>>, element: BaseFabricator<any>): Fabricator<Schema<$Definition>>;
@@ -1,6 +1,7 @@
1
1
  import type { Produce } from "../../Random/Types";
2
+ import type { Fabricated as FabricatedBy } from "../../Schema/Types";
2
3
  import { Schema } from "./Schema";
3
- import type { Definition, Fabricated, InputWhereby } from "./Types";
4
+ import type { Definition, Fabricated, InputUniqueWhereby, InputWhereby } from "./Types";
4
5
  type ThisRegistry<$Definition extends Definition> = {
5
6
  /**
6
7
  * An array of `definition`, repeated `length` times. `length` is a bare `N`
@@ -19,4 +20,40 @@ type ThisRegistry<$Definition extends Definition> = {
19
20
  as: (produce: Produce<Fabricated<$Definition>>) => Schema<$Definition>;
20
21
  };
21
22
  export default function <const $Definition extends Definition>(definition: $Definition): ThisRegistry<$Definition>;
23
+ type UniqueRegistry<$Definition extends Definition> = {
24
+ /**
25
+ * An array of `definition` whose members are distinct within each array,
26
+ * repeated `length` times as `T.array`'s is. A member drawn from a finite set
27
+ * (`T.enum`, `T.boolean`, a uniform integer range, a bigint range) is drawn
28
+ * without replacement, and a `length` that could exceed that set is rejected
29
+ * here, at construction. Any other member is redrawn while it repeats one
30
+ * already in the array, up to `redraws` times in a row.
31
+ *
32
+ * Members compare as plain data: by value, `Date` by time, arrays and plain
33
+ * objects by content. Other objects compare by identity; `.by(...)` says what
34
+ * should be distinct instead.
35
+ */
36
+ whereby: (whereby: InputUniqueWhereby) => Schema<$Definition>;
37
+ /**
38
+ * Make members distinct by `key(member)` rather than by the whole member —
39
+ * `.by((user) => user.email)`.
40
+ *
41
+ * Members are always redrawn while their key repeats, even from a finite set
42
+ * that would otherwise be drawn without replacement. A projection can map
43
+ * different members to one key — `["Ann", "Anne", "Bob"]` by first letter has
44
+ * three members but two keys — so the member set's size says nothing about
45
+ * how many distinct keys exist. There is no capacity check at construction,
46
+ * and running out surfaces as `UniqueRedrawsError` once `redraws` consecutive
47
+ * draws repeat a key.
48
+ */
49
+ by: (key: (element: FabricatedBy<$Definition>) => unknown) => {
50
+ whereby: (whereby: InputUniqueWhereby) => Schema<$Definition>;
51
+ };
52
+ };
53
+ /**
54
+ * `T.unique.array`, assembled into the namespace by `Primitive/unique`. No
55
+ * `as`: a producer replaces the draw, so it would discard the one thing this
56
+ * builder adds.
57
+ */
58
+ export declare function unique<const $Definition extends Definition>(definition: $Definition): UniqueRegistry<$Definition>;
22
59
  export {};
@@ -2,7 +2,7 @@ import { type AdaptationEntry } from "../../Adapter/Core";
2
2
  import type { Adaptations, Adapter, Adapting, WithAdaptations } from "../../Adapter/Types";
3
3
  import type { Produce } from "../../Random/Types";
4
4
  import { type SatisfiesThis } from "../../Schema/Satisfies";
5
- import type { Core, Definition, Fabricated } from "./Types";
5
+ import type { Core, Definition, Fabricated, InputAdmits } from "./Types";
6
6
  /**
7
7
  * The buildable recipe for an `array`: a single element Schema, repeated
8
8
  * `whereby.length` times.
@@ -14,6 +14,11 @@ export interface Schema<$Definition extends Definition = Definition, $Adaptation
14
14
  * (or future validation of `produce`) still has them to check against.
15
15
  */
16
16
  as: (produce: Produce<Fabricated<$Definition>>) => Schema<$Definition, $Adaptations>;
17
+ /**
18
+ * State what adapters admit for this schema, widening what `whereby` draws —
19
+ * see `string/Schema.ts`'s `admits` for the full contract.
20
+ */
21
+ admits: (admitted: InputAdmits) => Schema<$Definition, $Adaptations>;
17
22
  /**
18
23
  * Check that this schema's fabricated value type is assignable to `$Target`.
19
24
  * Identity at runtime; the target is not carried into later chained calls —
@@ -1,15 +1,43 @@
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 { AnySchema, Fabricated as FabricatedBy } from "../../Schema/Types";
5
5
  import type { Adaptation, Kind, Meta, Produced, Produces } from "../../Types";
6
+ import type { Redraws } from "../../Unique/Strategy";
6
7
  export type Definition = AnySchema;
7
8
  export type Fabricated<$Definition extends Definition, $Bindings extends unknown[] = []> = Array<FabricatedBy<$Definition, $Bindings>>;
8
9
  export type InputWhereby = {
9
10
  length: InputLength;
10
11
  };
12
+ /** `T.unique.array`'s `.whereby`: the same `length`, plus {@link Redraws}. */
13
+ export type InputUniqueWhereby = InputWhereby & Redraws;
11
14
  export type Whereby = {
12
15
  length: Length;
16
+ redraws?: number | undefined;
17
+ };
18
+ /**
19
+ * `.admits(...)`'s input: the length an adapter states, widening what `whereby`
20
+ * draws. An end is replaced, `Infinity` (or `-Infinity` for `min`) states no
21
+ * limit, and an omitted end keeps what is admitted already.
22
+ */
23
+ export type InputAdmits = {
24
+ length?: InputAdmittedEnds<number> | undefined;
25
+ };
26
+ /**
27
+ * `[Meta].admits`, set only by `.admits(...)` and complete once set: an absent
28
+ * end states no limit (`Admits.ts`'s `toAdmits`).
29
+ */
30
+ export type Admits = {
31
+ length: AdmittedEnds<number>;
32
+ };
33
+ /**
34
+ * `T.unique.array`'s marker on `[Meta]`: members are distinct within each
35
+ * fabricated array. `by` projects a member to what must be distinct, and is
36
+ * typed to the element at the builder (`Registry.ts`'s `unique`); stored here
37
+ * as `any` so `Meta` stays covariant in `$Definition`.
38
+ */
39
+ export type Unique = {
40
+ by?: ((element: any) => unknown) | undefined;
13
41
  };
14
42
  /**
15
43
  * `whereby` (a length spec — no natural bound to fuzz to, so unlike
@@ -23,10 +51,14 @@ export type Whereby = {
23
51
  export type Meta<$Definition extends Definition = Definition> = {
24
52
  definition: $Definition;
25
53
  whereby: Whereby;
54
+ unique?: Unique;
55
+ admits?: Admits | undefined;
26
56
  produce?: never;
27
57
  } | {
28
58
  definition: $Definition;
29
59
  whereby?: Whereby;
60
+ unique?: Unique;
61
+ admits?: Admits | undefined;
30
62
  produce: Produce<Fabricated<$Definition>>;
31
63
  };
32
64
  export interface Core<$Definition extends Definition = Definition, $Adaptations extends Adaptations = {}> {
@@ -0,0 +1,7 @@
1
+ import type { Admits, InputAdmits, Meta } from "./Types";
2
+ /**
3
+ * Resolve `.admits(...)` against what is admitted already: `meta.admits`, or by
4
+ * default the drawn range — what an adapter states without one. Under
5
+ * `.as(produce)` nothing is drawn, so nothing is checked.
6
+ */
7
+ export declare function toAdmits(meta: Meta, input: InputAdmits): Admits;