@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,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;
@@ -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;
@@ -1,7 +1,7 @@
1
1
  import type { AdaptationsOf } from "../../Adapter/Types";
2
2
  import type { FabricatorContext, NaiveFabricator } from "../../Fabricator/Types";
3
3
  import type { Trace } from "../../Random/Types";
4
- import { Kind, Meta, type Adaptation } from "../../Types";
4
+ import { Claim, Kind, Meta, type Adaptation } from "../../Types";
5
5
  import { Schema } from "./Schema";
6
6
  import type { Fabricated, Meta as ThisMeta } from "./Types";
7
7
  export type Fabrication<_ extends Fabricator> = Fabricated;
@@ -14,6 +14,8 @@ export type Fabricator<$Schema extends {
14
14
  [Meta]: $Schema[typeof Meta];
15
15
  readonly trace: Trace;
16
16
  readonly [Adaptation]?: AdaptationsOf<$Schema>;
17
+ /** Present on a `T.unique.bigint` only — see `Types.ts`'s `Claim`. */
18
+ readonly [Claim]?: (value: unknown) => void;
17
19
  schema: Schema<$Schema[typeof Meta], AdaptationsOf<$Schema>>;
18
20
  };
19
21
  export declare function Fabricator(context: FabricatorContext<Schema>): Fabricator;
@@ -17,3 +17,23 @@ declare const _default: {
17
17
  }>;
18
18
  };
19
19
  export default _default;
20
+ type UniqueRegistry = {
21
+ /** See the default export's `[Kind]`. */
22
+ [Kind]: "bigint";
23
+ /**
24
+ * A bigint the built Fabricator never repeats, drawn from `[min, max]` like
25
+ * `T.bigint.whereby`. The range is yielded as a random permutation at any
26
+ * width, so it produces every value exactly once and the draw after the last
27
+ * throws `UniqueExhaustedError`.
28
+ */
29
+ whereby: (whereby: InputWhereby) => Schema<{
30
+ whereby: Whereby;
31
+ unique: true;
32
+ }>;
33
+ };
34
+ /**
35
+ * `T.unique.bigint` (and `T.unique.number.integer.big`), assembled into the
36
+ * namespace by `Primitive/unique`. No `as`: a producer replaces the draw, so it
37
+ * would discard the one thing this builder adds.
38
+ */
39
+ export declare const unique: UniqueRegistry;
@@ -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, Fabricated, Meta as ThisMeta } from "./Types";
5
+ import type { Admits, Core, Fabricated, InputAdmits, Meta as ThisMeta } from "./Types";
6
6
  /**
7
7
  * Buildable `bigint` recipe: a range (`whereby` — required, like `string`; no
8
8
  * natural bound to fuzz to), or opaque production via `as`.
@@ -19,6 +19,14 @@ export interface Schema<$Meta extends ThisMeta = ThisMeta, $Adaptations extends
19
19
  * validation of `produce`) still has it to check against.
20
20
  */
21
21
  as: (produce: Produce<Fabricated>) => Schema<$Meta, $Adaptations>;
22
+ /**
23
+ * State what adapters admit for this schema, widening what `whereby` draws —
24
+ * see `string/Schema.ts`'s `admits` for the full contract. A safe-integer
25
+ * `number` converts as in `whereby`.
26
+ */
27
+ admits: (admitted: InputAdmits) => Schema<$Meta & {
28
+ admits: Admits;
29
+ }, $Adaptations>;
22
30
  /**
23
31
  * Check that this schema's fabricated value type is assignable to `$Target`.
24
32
  * Identity at runtime; the target is not carried into later chained calls —
@@ -1,15 +1,31 @@
1
1
  import type { Adaptations } from "../../Adapter/Types";
2
- import type { Bound, InputBound } from "../../Bound";
2
+ import type { AdmittedEnds, Bound, InputAdmittedEnds, InputBound } from "../../Bound";
3
3
  import type { Produce } from "../../Random/Types";
4
4
  import type { Adaptation, Kind, Meta, Produced, Produces } from "../../Types";
5
+ /**
6
+ * Call-site `{ min?, max }`. Either end may be a `number` that is a safe
7
+ * integer (`Bound.ts`'s `toBigintBound`), stored as a `bigint`.
8
+ */
5
9
  export type InputWhereby = {
6
- min?: InputBound<bigint> | undefined;
7
- max: InputBound<bigint>;
10
+ min?: InputBound<bigint | number> | undefined;
11
+ max: InputBound<bigint | number>;
8
12
  };
9
13
  export type Whereby = {
10
14
  min: Bound<bigint>;
11
15
  max: Bound<bigint>;
12
16
  };
17
+ /**
18
+ * `.admits(...)`'s input: the ends an adapter states, widening what `whereby`
19
+ * draws. An end is replaced (a safe-integer `number` converts as in `whereby`),
20
+ * `Infinity` (or `-Infinity` for `min`) states no limit, and an omitted end
21
+ * keeps what is admitted already.
22
+ */
23
+ export type InputAdmits = InputAdmittedEnds<bigint | number>;
24
+ /**
25
+ * `[Meta].admits`, set only by `.admits(...)` and complete once set: an absent
26
+ * end states no limit (`Admits.ts`'s `toAdmits`).
27
+ */
28
+ export type Admits = AdmittedEnds<bigint>;
13
29
  export type Fabricated = bigint;
14
30
  /**
15
31
  * A ranged bigint, drawn via `whereby` — no natural bound to fuzz to, so unlike
@@ -17,12 +33,20 @@ export type Fabricated = bigint;
17
33
  * `as` production, carried alongside `whereby` rather than replacing it (when
18
34
  * `whereby` was already set) so a prior range survives `as` for future
19
35
  * validation.
36
+ *
37
+ * `unique` is set by `T.unique.bigint`: the built Fabricator yields its range
38
+ * as a random permutation, never repeating for its whole lifetime
39
+ * (`Unique/Distinct.ts`'s `toBigintStrategy`).
20
40
  */
21
41
  export type Meta = {
22
42
  whereby: Whereby;
43
+ unique?: true;
44
+ admits?: Admits | undefined;
23
45
  produce?: never;
24
46
  } | {
25
47
  whereby?: Whereby;
48
+ unique?: true;
49
+ admits?: Admits | undefined;
26
50
  produce: Produce<Fabricated>;
27
51
  };
28
52
  export type Core<$Meta extends Meta = Meta, $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 `whereby` ends — what an adapter states without one. An omitted
5
+ * `whereby` end draws against `±MAX_TIME`, so only no limit admits it.
6
+ */
7
+ export declare function toAdmits(meta: Meta, input: InputAdmits): Admits;
@@ -1,4 +1,5 @@
1
- import type { Bound } from "../../Bound";
1
+ import { type Bound } from "../../Bound";
2
+ import type { Meta } from "./Types";
2
3
  /**
3
4
  * Inclusive epoch-millisecond caps that a missing `whereby` end draws against —
4
5
  * the whole representable `Date` range. Not stored on `[Meta]`: an omitted end
@@ -9,3 +10,23 @@ export declare const unboundedEpoch: {
9
10
  min: Bound<number>;
10
11
  max: Bound<number>;
11
12
  };
13
+ /**
14
+ * The epoch-millisecond ends a `date` draws between, given the construction's
15
+ * `clock`: `whereby`'s named ends, the unbounded caps for the rest, and `clock`
16
+ * itself (inclusive) as `past`'s upper or `future`'s lower end. Here rather
17
+ * than in `Fabricator.ts` so `Unique/Distinct.ts` can read a collection
18
+ * member's range without importing a Fabricator.
19
+ */
20
+ export declare function toEpochBounds(meta: Meta, clock: number): {
21
+ min: Bound<number>;
22
+ max: Bound<number>;
23
+ };
24
+ /**
25
+ * {@link toEpochBounds} as the inclusive whole-millisecond interval a `Date` can
26
+ * actually take — `Date` is `TimeClip`ped to whole milliseconds, so this is
27
+ * every value a draw can produce.
28
+ */
29
+ export declare function toEpochRange(meta: Meta, clock: number): {
30
+ min: number;
31
+ max: number;
32
+ };
@@ -1,7 +1,7 @@
1
1
  import type { AdaptationsOf } from "../../Adapter/Types";
2
2
  import type { FabricatorContext, NaiveFabricator } from "../../Fabricator/Types";
3
3
  import type { Trace } from "../../Random/Types";
4
- import { Kind, Meta, type Adaptation } from "../../Types";
4
+ import { Claim, Kind, Meta, type Adaptation } from "../../Types";
5
5
  import { Schema } from "./Schema";
6
6
  import type { Fabricated, Meta as ThisMeta } from "./Types";
7
7
  export type Fabrication<_ extends Fabricator> = Fabricated;
@@ -14,6 +14,8 @@ export type Fabricator<$Schema extends {
14
14
  [Meta]: $Schema[typeof Meta];
15
15
  readonly trace: Trace;
16
16
  readonly [Adaptation]?: AdaptationsOf<$Schema>;
17
+ /** Present on a `T.unique.date` only — see `Types.ts`'s `Claim`. */
18
+ readonly [Claim]?: (value: unknown) => void;
17
19
  schema: Schema<$Schema[typeof Meta], AdaptationsOf<$Schema>>;
18
20
  };
19
21
  export declare function Fabricator(context: FabricatorContext<Schema>): Fabricator;
@@ -1,8 +1,6 @@
1
1
  import type { Adaptations } from "../../Adapter/Types";
2
- import { type InputBound } from "../../Bound";
3
- import { type Distribution } from "../../Distribution";
4
2
  import { Schema } from "./Schema";
5
- import type { InputWhereby, Whereby } from "./Types";
3
+ import type { InputFutureWhereby, InputPastWhereby, InputUniqueFutureWhereby, InputUniquePastWhereby, InputUniqueWhereby, InputWhereby, Whereby } from "./Types";
6
4
  type ThisRegistry = Schema<{}, Adaptations> & {
7
5
  /**
8
6
  * A `Date` drawn from `[min, max]`. Either end may be omitted: `min` defaults
@@ -26,10 +24,7 @@ type ThisRegistry = Schema<{}, Adaptations> & {
26
24
  * `distribution` to shape how values cluster within the range; without one,
27
25
  * every instant is equally likely.
28
26
  */
29
- whereby: (whereby: {
30
- min?: InputBound<Date> | undefined;
31
- distribution?: Distribution | undefined;
32
- }) => Schema<{
27
+ whereby: (whereby: InputPastWhereby) => Schema<{
33
28
  mode: "past";
34
29
  whereby: Whereby;
35
30
  }>;
@@ -44,10 +39,7 @@ type ThisRegistry = Schema<{}, Adaptations> & {
44
39
  * `distribution` to shape how values cluster within the range; without one,
45
40
  * every instant is equally likely.
46
41
  */
47
- whereby: (whereby: {
48
- max?: InputBound<Date> | undefined;
49
- distribution?: Distribution | undefined;
50
- }) => Schema<{
42
+ whereby: (whereby: InputFutureWhereby) => Schema<{
51
43
  mode: "future";
52
44
  whereby: Whereby;
53
45
  }>;
@@ -61,3 +53,47 @@ type ThisRegistry = Schema<{}, Adaptations> & {
61
53
  */
62
54
  declare function registry(): ThisRegistry;
63
55
  export default registry;
56
+ type UniqueRegistry = Schema<{
57
+ unique: true;
58
+ }, Adaptations> & {
59
+ /**
60
+ * A `Date` the built Fabricator never repeats, drawn from `[min, max]` like
61
+ * `T.date.whereby`. Instants are whole milliseconds, so a uniform range is
62
+ * drawn as a random permutation of them: every instant exactly once, then
63
+ * `UniqueExhaustedError`. A skewed range is tracked instead, still exhausting
64
+ * exactly; `redraws` raises the cap on consecutive repeats its rarest
65
+ * instants can need.
66
+ */
67
+ whereby: (whereby: InputUniqueWhereby) => Schema<{
68
+ unique: true;
69
+ whereby: Whereby;
70
+ }>;
71
+ /** A past `Date` the built Fabricator never repeats. */
72
+ past: Schema<{
73
+ mode: "past";
74
+ unique: true;
75
+ }> & {
76
+ whereby: (whereby: InputUniquePastWhereby) => Schema<{
77
+ mode: "past";
78
+ unique: true;
79
+ whereby: Whereby;
80
+ }>;
81
+ };
82
+ /** A future `Date` the built Fabricator never repeats. */
83
+ future: Schema<{
84
+ mode: "future";
85
+ unique: true;
86
+ }> & {
87
+ whereby: (whereby: InputUniqueFutureWhereby) => Schema<{
88
+ mode: "future";
89
+ unique: true;
90
+ whereby: Whereby;
91
+ }>;
92
+ };
93
+ };
94
+ /**
95
+ * `T.unique.date`, assembled into the namespace by `Primitive/unique`, which
96
+ * installs it as a getter for the same reason `T.date` is one. `past` and
97
+ * `future` are getters here too.
98
+ */
99
+ export declare function unique(): UniqueRegistry;
@@ -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, Fabricated, Meta as ThisMeta } from "./Types";
5
+ import type { Core, Fabricated, Meta as ThisMeta, Admits, InputAdmitsOf } from "./Types";
6
6
  /**
7
7
  * Buildable `Date` recipe: a range/distribution (`whereby`, absent for the
8
8
  * full-range bare form), optionally scoped by `mode` to `"past"` (up to now) or
@@ -19,6 +19,15 @@ export interface Schema<$Meta extends ThisMeta = ThisMeta, $Adaptations extends
19
19
  * future validation of `produce`) still has them to check against.
20
20
  */
21
21
  as: (produce: Produce<Fabricated>) => Schema<$Meta, $Adaptations>;
22
+ /**
23
+ * State what adapters admit for this schema, widening what `whereby` draws —
24
+ * see `string/Schema.ts`'s `admits` for the full contract. Epoch milliseconds
25
+ * convert as in `whereby`. `past` admits only a `min` and `future` only a
26
+ * `max`: their other end is the clock.
27
+ */
28
+ admits: (admitted: InputAdmitsOf<$Meta>) => Schema<$Meta & {
29
+ admits: Admits;
30
+ }, $Adaptations>;
22
31
  /**
23
32
  * Check that this schema's fabricated value type is assignable to `$Target`.
24
33
  * Identity at runtime; the target is not carried into later chained calls —
@@ -1,28 +1,74 @@
1
1
  import type { Adaptations } from "../../Adapter/Types";
2
- import type { Bound, InputBound } from "../../Bound";
2
+ import type { AdmittedEnds, Bound, InputAdmittedEnds, InputBound } from "../../Bound";
3
3
  import type { Distribution } from "../../Distribution";
4
4
  import type { Produce } from "../../Random/Types";
5
5
  import type { Adaptation, Kind, Meta, Produced, Produces } from "../../Types";
6
+ import type { Redraws } from "../../Unique/Strategy";
6
7
  /**
7
8
  * Call-site `{ min, max }` — scalars are inclusive. Either end may be omitted;
8
9
  * a missing `min` is the earliest representable instant and a missing `max` the
9
- * latest, the same span as a bare `T.date`.
10
+ * latest, the same span as a bare `T.date`. Either end may be epoch
11
+ * milliseconds (`Bound.ts`'s `toDateBound`), stored as a `Date`.
10
12
  */
11
13
  export type InputWhereby = {
12
- min?: InputBound<Date> | undefined;
13
- max?: InputBound<Date> | undefined;
14
+ min?: InputBound<Date | number> | undefined;
15
+ max?: InputBound<Date | number> | undefined;
14
16
  distribution?: Distribution | undefined;
15
17
  };
18
+ /** `T.date.past.whereby`: `past` closes its upper end at the clock. */
19
+ export type InputPastWhereby = {
20
+ min?: InputBound<Date | number> | undefined;
21
+ distribution?: Distribution | undefined;
22
+ };
23
+ /** `T.date.future.whereby`: `future` closes its lower end at the clock. */
24
+ export type InputFutureWhereby = {
25
+ max?: InputBound<Date | number> | undefined;
26
+ distribution?: Distribution | undefined;
27
+ };
28
+ /** `T.unique.date`'s `.whereby` inputs: each plain one, plus {@link Redraws}. */
29
+ export type InputUniqueWhereby = InputWhereby & Redraws;
30
+ export type InputUniquePastWhereby = InputPastWhereby & Redraws;
31
+ export type InputUniqueFutureWhereby = InputFutureWhereby & Redraws;
16
32
  /**
17
33
  * Stored `{ min, max }` — each present end is a canonical {@link Bound}. An
18
34
  * omitted end stays omitted (fabricate fills `Defaults.ts`'s `unboundedEpoch`;
19
35
  * adapters forward only the ends that were named).
36
+ *
37
+ * `redraws` is set only through {@link InputUniqueWhereby} and its
38
+ * `past`/`future` forms.
20
39
  */
21
40
  export type Whereby = {
22
41
  min?: Bound<Date> | undefined;
23
42
  max?: Bound<Date> | undefined;
24
43
  distribution?: Distribution | undefined;
44
+ redraws?: number | undefined;
25
45
  };
46
+ /**
47
+ * `.admits(...)`'s input: the ends an adapter states, widening what `whereby`
48
+ * draws. An end is replaced (epoch milliseconds convert as in `whereby`),
49
+ * `Infinity` (or `-Infinity` for `min`) states no limit, and an omitted end
50
+ * keeps what is admitted already.
51
+ */
52
+ export type InputAdmits = InputAdmittedEnds<Date | number>;
53
+ /**
54
+ * `T.date.past`'s `.admits`: its upper end is the clock, unknown until a
55
+ * Fabricator is built, so only `min` can be widened.
56
+ */
57
+ export type InputPastAdmits = Pick<InputAdmits, "min">;
58
+ /** `T.date.future`'s `.admits`: likewise, only `max`. */
59
+ export type InputFutureAdmits = Pick<InputAdmits, "max">;
60
+ /** The `.admits` input a date schema of `$Meta` takes, by its `mode`. */
61
+ export type InputAdmitsOf<$Meta extends Meta> = $Meta extends {
62
+ mode: "past";
63
+ } ? InputPastAdmits : InputAdmitsOfFuture<$Meta>;
64
+ type InputAdmitsOfFuture<$Meta extends Meta> = $Meta extends {
65
+ mode: "future";
66
+ } ? InputFutureAdmits : InputAdmits;
67
+ /**
68
+ * `[Meta].admits`, set only by `.admits(...)` and complete once set: an absent
69
+ * end states no limit (`Admits.ts`'s `toAdmits`).
70
+ */
71
+ export type Admits = AdmittedEnds<Date>;
26
72
  export type Fabricated = Date;
27
73
  /**
28
74
  * A range/distribution (`whereby`, absent for the full-range bare form),
@@ -34,6 +80,8 @@ export type Fabricated = Date;
34
80
  export type Meta = {
35
81
  mode?: "past" | "future";
36
82
  whereby?: Whereby;
83
+ unique?: true;
84
+ admits?: Admits | undefined;
37
85
  produce?: Produce<Fabricated>;
38
86
  };
39
87
  export type Core<$Meta extends Meta = Meta, $Adaptations extends Adaptations = {}> = {
@@ -42,3 +90,4 @@ export type Core<$Meta extends Meta = Meta, $Adaptations extends Adaptations = {
42
90
  readonly [Produces]?: Produced<Fabricated>;
43
91
  readonly [Adaptation]?: $Adaptations;
44
92
  };
93
+ export {};
@@ -1,7 +1,7 @@
1
1
  import type { AdaptationsOf } from "../../Adapter/Types";
2
2
  import type { FabricatorContext, NaiveFabricator } from "../../Fabricator/Types";
3
3
  import type { Trace } from "../../Random/Types";
4
- import { Kind, Meta, type Adaptation } from "../../Types";
4
+ import { Claim, Kind, Meta, type Adaptation } from "../../Types";
5
5
  import { Schema } from "./Schema";
6
6
  import type { Fabricated, Items, Meta as ThisMeta } from "./Types";
7
7
  export type Fabrication<$Fabricator extends Fabricator> = $Fabricator extends Fabricator<infer $Schema> ? Fabricated<$Schema[typeof Meta]["items"]> : never;
@@ -14,6 +14,8 @@ export type Fabricator<$Schema extends {
14
14
  [Meta]: $Schema[typeof Meta];
15
15
  readonly trace: Trace;
16
16
  readonly [Adaptation]?: AdaptationsOf<$Schema>;
17
+ /** Present on a `T.unique.enum` only — see `Types.ts`'s `Claim`. */
18
+ readonly [Claim]?: (value: unknown) => void;
17
19
  schema: Schema<$Schema[typeof Meta]["items"], AdaptationsOf<$Schema>>;
18
20
  };
19
21
  export declare function Fabricator<$Items extends Items>(context: FabricatorContext<Schema<$Items>>): Fabricator<Schema<$Items>>;