@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
@@ -1,8 +1,9 @@
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 end is unbounded (the same policy as a bare `T.number`), not a
@@ -13,26 +14,42 @@ export type InputWhereby = {
13
14
  max?: InputBound<number> | undefined;
14
15
  distribution?: Distribution | undefined;
15
16
  };
17
+ /** `T.unique.number`'s `.whereby`: the same input, plus {@link Redraws}. */
18
+ export type InputUniqueWhereby = InputWhereby & Redraws;
16
19
  /**
17
20
  * Stored `{ min, max }` — each present end is a canonical {@link Bound}. An
18
21
  * omitted end stays omitted (fabricate fills the unbounded cap; adapters
19
- * forward only the ends that were named).
22
+ * forward only the ends that were named). `redraws` is set only through
23
+ * {@link InputUniqueWhereby}.
20
24
  */
21
25
  export type Whereby = {
22
26
  min?: Bound<number> | undefined;
23
27
  max?: Bound<number> | undefined;
24
28
  distribution?: Distribution | undefined;
29
+ redraws?: number | undefined;
25
30
  };
26
- export type Fabricated = number;
27
31
  /**
28
- * JSON-Schema keywords that constrain a number value — carried as neutral,
29
- * schema-library-agnostic hints (see the builder's `as`). The numeric range
30
- * lives on `whereby` as {@link Bound}s, which adapters forward; `hints` holds
31
- * only the orthogonal constraints not expressible there.
32
+ * `.admits(...)`'s input: the ends an adapter states, widening what `whereby`
33
+ * draws. An end is replaced, `Infinity` (or `-Infinity` for `min`) states no
34
+ * limit, and an omitted end keeps what is admitted already.
35
+ */
36
+ export type InputAdmits = InputAdmittedEnds<number> & Keywords;
37
+ /**
38
+ * JSON-Schema keywords for what the numbers are, which adapters forward to
39
+ * their target. Unlike an end, `multipleOf` is not checked against what is
40
+ * drawn — like `.adapt`, the caller vouches that fabricated values match,
41
+ * usually by fabricating through `.as(produce)`. A keyword left out keeps what
42
+ * is admitted already.
32
43
  */
33
- export type JsonSchema = {
34
- multipleOf?: number;
44
+ export type Keywords = {
45
+ multipleOf?: number | undefined;
35
46
  };
47
+ /**
48
+ * `[Meta].admits`, set only by `.admits(...)` and complete once set: an absent
49
+ * end states no limit (`Admits.ts`'s `toAdmits`).
50
+ */
51
+ export type Admits = AdmittedEnds<number> & Keywords;
52
+ export type Fabricated = number;
36
53
  /**
37
54
  * A ranged number — `whereby` is absent on the full-range form, `integer` (a
38
55
  * literal, not widened to `boolean`) selects whole-number semantics, or a
@@ -40,12 +57,17 @@ export type JsonSchema = {
40
57
  * counter only ever yields whole numbers), optionally overridden by an opaque
41
58
  * `as` production — carried alongside the rest rather than replacing it, so a
42
59
  * prior scoping survives `as` for future validation.
60
+ *
61
+ * `unique` is set by `T.unique.number`: the built Fabricator never repeats a
62
+ * value for its whole lifetime (`Unique/Distinct.ts`'s `toNumberStrategy`).
63
+ * Never paired with `sequence`, which cannot repeat by design.
43
64
  */
44
65
  export type Meta = {
45
66
  whereby?: Whereby;
46
67
  integer?: boolean;
47
68
  sequence?: boolean;
48
- hints?: JsonSchema | undefined;
69
+ unique?: true;
70
+ admits?: Admits | undefined;
49
71
  produce?: Produce<Fabricated>;
50
72
  };
51
73
  export type Core<$Meta extends Meta = Meta, $Adaptations extends Adaptations = {}> = {
@@ -0,0 +1,18 @@
1
+ import { type AdmittedEnds } from "../../Bound";
2
+ import type { Admits, InputAdmits, Meta } from "./Types";
3
+ /**
4
+ * Resolve `.admits(...)` against what is admitted already: `meta.admits`, or by
5
+ * default the written size ({@link toStatedSize}) — what an adapter states
6
+ * without one. Admitting is checked against what the record can fabricate
7
+ * ({@link toFabricableSize}), which for a plain record differs from what it
8
+ * states. Under `.as(produce)` nothing is drawn, so nothing is checked.
9
+ */
10
+ export declare function toAdmits(meta: Meta, input: InputAdmits): Admits;
11
+ /**
12
+ * The count a record states without `.admits`: the bounds written in `whereby`,
13
+ * as written. A unique record's `size` is a range. A plain record's `minTried`
14
+ * counts attempts, not entries, so only `max` is stated. The TypeBox adapter's
15
+ * `toPropertyCount` states the same, and `recursive/Terminate.ts` reads it to
16
+ * see whether an emptied record would break a stated minimum.
17
+ */
18
+ export declare function toStatedSize(meta: Meta): AdmittedEnds<number>;
@@ -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";
@@ -22,4 +22,4 @@ export type Fabricator<$Schema extends {
22
22
  readonly [Adaptation]?: AdaptationsOf<$Schema>;
23
23
  schema: Schema<$Schema[typeof Meta]["key"], $Schema[typeof Meta]["value"], AdaptationsOf<$Schema>>;
24
24
  };
25
- export declare function Fabricator<$Key extends Key, $Value extends Value>(context: FabricatorContext<Schema<$Key, $Value>>, key: NaiveFabricator<any>, value: NaiveFabricator<any>): Fabricator<Schema<$Key, $Value>>;
25
+ export declare function Fabricator<$Key extends Key, $Value extends Value>(context: FabricatorContext<Schema<$Key, $Value>>, key: BaseFabricator<any>, value: BaseFabricator<any>): Fabricator<Schema<$Key, $Value>>;
@@ -1,6 +1,6 @@
1
1
  import type { Produce } from "../../Random/Types";
2
2
  import { Schema } from "./Schema";
3
- import type { Fabricated, Key, Value, Whereby } from "./Types";
3
+ import type { Fabricated, InputUniqueWhereby, Key, Value, Whereby } from "./Types";
4
4
  type ThisRegistry<$Key extends Key, $Value extends Value> = {
5
5
  /**
6
6
  * A record of `value` keyed by `key`, attempted `whereby.size` times —
@@ -16,4 +16,21 @@ type ThisRegistry<$Key extends Key, $Value extends Value> = {
16
16
  as: (produce: Produce<Fabricated<$Key, $Value>>) => Schema<$Key, $Value>;
17
17
  };
18
18
  export default function <const $Key extends Key, const $Value extends Value>(key: $Key, value: $Value): ThisRegistry<$Key, $Value>;
19
+ type UniqueRegistry<$Key extends Key, $Value extends Value> = {
20
+ /**
21
+ * A record of `value` keyed by `key`, with `size` drawn from a bare `N` or `{
22
+ * min?, max, distribution? }` and every key distinct, so the record holds
23
+ * exactly the size drawn. A key drawn from a finite set (`T.enum`,
24
+ * `T.always`, …) is drawn without replacement, and a `size` that could exceed
25
+ * that set is rejected here, at construction. Any other key is redrawn while
26
+ * it repeats one already in the record, up to `redraws` times in a row.
27
+ */
28
+ whereby: (whereby: InputUniqueWhereby) => Schema<$Key, $Value>;
29
+ };
30
+ /**
31
+ * `T.unique.record`, assembled into the namespace by `Primitive/unique`. No
32
+ * `as`: a producer replaces the draw, so it would discard the one thing this
33
+ * builder adds.
34
+ */
35
+ export declare function unique<const $Key extends Key, const $Value extends Value>(key: $Key, value: $Value): UniqueRegistry<$Key, $Value>;
19
36
  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, Fabricated, Key, Value } from "./Types";
5
+ import type { Core, Fabricated, Key, Value, InputAdmits } from "./Types";
6
6
  /**
7
7
  * The buildable recipe for a `record`: a key Schema and a value Schema, drawn
8
8
  * `whereby.size` times. `array`'s sibling — one repeated value shape and a
@@ -15,6 +15,13 @@ export interface Schema<$Key extends Key = Key, $Value extends Value = Value, $A
15
15
  * (or future validation of `produce`) still has them to check against.
16
16
  */
17
17
  as: (produce: Produce<Fabricated<$Key, $Value>>) => Schema<$Key, $Value, $Adaptations>;
18
+ /**
19
+ * State what adapters admit for this schema, widening what `whereby` draws —
20
+ * see `string/Schema.ts`'s `admits` for the full contract. A plain record
21
+ * fabricates `[minTried >= 1 ? 1 : 0, size.max]` entries, since colliding
22
+ * keys collapse; a unique record its drawn `size`.
23
+ */
24
+ admits: (admitted: InputAdmits) => Schema<$Key, $Value, $Adaptations>;
18
25
  /**
19
26
  * Check that this schema's fabricated value type is assignable to `$Target`.
20
27
  * Identity at runtime; the target is not carried into later chained calls —
@@ -1,7 +1,9 @@
1
1
  import type { Adaptations } from "../../Adapter/Types";
2
+ import type { AdmittedEnds, InputAdmittedEnds, InputLength, Length } from "../../Bound";
2
3
  import type { Produce } from "../../Random/Types";
3
4
  import type { AnySchema, Fabricated as FabricatedBy } from "../../Schema/Types";
4
5
  import { Produces, type Adaptation, type Kind, type Meta, type Produced } from "../../Types";
6
+ import type { Redraws } from "../../Unique/Strategy";
5
7
  /**
6
8
  * A Schema usable as a record's keys: any Schema whose fabricated value is a
7
9
  * legal JS property key. Constrained through the phantom `[Produces]` marker
@@ -40,8 +42,12 @@ type IsKeyspaceOpen<$Key> = string extends $Key ? true : symbol extends $Key ? t
40
42
  *
41
43
  * A finite literal key set (`enum`/`always`/`choice`) is `Partial`: size is
42
44
  * drawn from `whereby.size`, and colliding keys collapse (`Fabricator.ts`), so
43
- * a two-member key schema may produce only one. Every key present wants
44
- * `T.object({ ... })` — what a record over a finite key set degenerates to.
45
+ * a two-member key schema may produce only one. `T.unique.record` has no
46
+ * collisions, but it still holds only as many keys as its drawn size: over
47
+ * `["a", "b", "c"]` with `size: { min: 1, max: 3 }`, a value may hold `a`
48
+ * alone. Only a size fixed at the key count guarantees every key, which the
49
+ * type does not track. Every key present wants `T.object({ ... })` — what a
50
+ * record over a finite key set degenerates to.
45
51
  */
46
52
  export type Fabricated<$Key extends Key = Key, $Value extends Value = Value, $Bindings extends unknown[] = []> = IsKeyspaceOpen<FabricatedBy<$Key, $Bindings>> extends true ? Record<FabricatedBy<$Key, $Bindings> & PropertyKey, FabricatedBy<$Value, $Bindings>> : Partial<Record<FabricatedBy<$Key, $Bindings> & PropertyKey, FabricatedBy<$Value, $Bindings>>>;
47
53
  /**
@@ -54,7 +60,8 @@ export type Fabricated<$Key extends Key = Key, $Value extends Value = Value, $Bi
54
60
  * `whereby.length.min`.
55
61
  *
56
62
  * No bare-number form (unlike `string`'s and `array`'s `length`): "exactly N"
57
- * is a promise a collapsing key set cannot keep.
63
+ * is a promise a collapsing key set cannot keep. `T.unique.record` draws its
64
+ * keys distinct instead, which is what lets its {@link UniqueWhereby} keep it.
58
65
  */
59
66
  export type Whereby = {
60
67
  size: {
@@ -62,24 +69,71 @@ export type Whereby = {
62
69
  minTried?: number | undefined;
63
70
  };
64
71
  };
72
+ /**
73
+ * `T.unique.record`'s `.whereby`: keys are drawn distinct, so `size` is a real
74
+ * `Length` — a bare `N` or `{ min?, max, distribution? }` whose `min` holds —
75
+ * plus {@link Redraws}.
76
+ */
77
+ export type InputUniqueWhereby = {
78
+ size: InputLength;
79
+ } & Redraws;
80
+ export type UniqueWhereby = {
81
+ size: Length;
82
+ redraws?: number | undefined;
83
+ };
84
+ /**
85
+ * `.admits(...)`'s input: the property count an adapter states, widening what
86
+ * the record fabricates. An end is replaced, `Infinity` states no limit, and an
87
+ * omitted end keeps what is admitted already. A plain record fabricates
88
+ * `[minTried >= 1 ? 1 : 0, size.max]` entries, since colliding keys collapse
89
+ * but the first attempt always lands; a unique record its drawn `size`.
90
+ */
91
+ export type InputAdmits = {
92
+ size?: InputAdmittedEnds<number> | undefined;
93
+ };
94
+ /**
95
+ * `[Meta].admits`, set only by `.admits(...)` and complete once set: an absent
96
+ * end states no limit (`Admits.ts`'s `toAdmits`).
97
+ */
98
+ export type Admits = {
99
+ size: AdmittedEnds<number>;
100
+ };
65
101
  /**
66
102
  * `key`/`value` stay required regardless of `produce` — both are known at
67
103
  * `T.record(...)` call time and describe the shape TypeBox derives either way.
68
104
  * `produce` is carried _alongside_ `whereby` rather than replacing it, so a
69
105
  * prior size spec survives `as` for future validation — same as `array`'s
70
106
  * `Meta`.
107
+ *
108
+ * Two discriminants, crossed. `unique` decides `whereby`'s shape, so testing it
109
+ * narrows `whereby` to {@link Whereby} or {@link UniqueWhereby} with no cast.
110
+ * `produce` decides whether anything is drawn, and is `never` on the drawn
111
+ * members so that a falsy `produce` narrows to them — an optional `Produce` on
112
+ * every member would not narrow. Only the plain builder's `.as(...)` produces
113
+ * with no `whereby`; `T.unique.record` has no such form, so a unique record
114
+ * always carries its size.
71
115
  */
72
116
  export type Meta<$Key extends Key = Key, $Value extends Value = Value> = {
73
117
  key: $Key;
74
118
  value: $Value;
119
+ admits?: Admits | undefined;
120
+ } & ({
121
+ unique?: never;
75
122
  whereby: Whereby;
76
123
  produce?: never;
77
124
  } | {
78
- key: $Key;
79
- value: $Value;
125
+ unique?: never;
80
126
  whereby?: Whereby;
81
127
  produce: Produce<Fabricated<$Key, $Value>>;
82
- };
128
+ } | {
129
+ unique: true;
130
+ whereby: UniqueWhereby;
131
+ produce?: never;
132
+ } | {
133
+ unique: true;
134
+ whereby: UniqueWhereby;
135
+ produce: Produce<Fabricated<$Key, $Value>>;
136
+ });
83
137
  export interface Core<$Key extends Key = Key, $Value extends Value = Value, $Adaptations extends Adaptations = {}> {
84
138
  [Kind]: "record";
85
139
  [Meta]: Meta<$Key, $Value>;
@@ -15,5 +15,12 @@ import type { AnySchema } from "../../Schema/Types";
15
15
  *
16
16
  * Nested `T.recursive` is its own fixed point and is treated as a leaf; its
17
17
  * inner `self` is not this walk's `self`.
18
+ *
19
+ * An emptied collection must not state a minimum above 0: an adapter states it
20
+ * as written, for every level of the tree, and every branch ends here empty, so
21
+ * no finite tree would validate. {@link assertEmptiable} throws
22
+ * `UnsatisfiableRecursiveBoundError` instead. A wrapper above the collection
23
+ * declines first (`T.optional(T.array(self))` becomes omitted), so only a
24
+ * collection this walk empties is checked.
18
25
  */
19
26
  export declare function terminate(body: AnySchema): AnySchema;
@@ -0,0 +1,8 @@
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. `format` and
6
+ * `pattern` are never checked (`Types.ts`'s `Keywords`).
7
+ */
8
+ export declare function toAdmits(meta: Meta, input: InputAdmits): Admits;
@@ -0,0 +1,36 @@
1
+ import type { Whereby } from "./Types";
2
+ /**
3
+ * The strings a `string` `whereby` can produce: how many, and a membership test
4
+ * for a value claimed rather than drawn (`Unique/Strategy.ts`'s `tracked`,
5
+ * whose `admits` keeps an out-of-domain override from using up capacity).
6
+ */
7
+ export type StringDomain = {
8
+ readonly capacity: bigint;
9
+ admits: (value: unknown) => boolean;
10
+ };
11
+ /**
12
+ * Count exactly what `Fabricator.ts` can produce, so a unique string exhausts
13
+ * by counting and a unique collection of strings is checked at construction.
14
+ *
15
+ * The characters are the union of every drawable source's code points — a
16
+ * character two sources share counts once. Length is in UTF-16 code units: a
17
+ * BMP character takes one, an astral character two. So with `a` one-unit and
18
+ * `b` two-unit characters, the strings of exactly `L` units number `f(L) =
19
+ * a·f(L − 1) + b·f(L − 2)`, `f(0) = 1`.
20
+ *
21
+ * The fabricator also has a filler: when one unit of budget is left and an
22
+ * astral character is drawn, it inserts one BMP scalar from outside the
23
+ * composition at any character boundary and stops. So when `b > 0`, a string of
24
+ * `L` units may also be any `L − 1`-unit string with one such character
25
+ * inserted. Its positions are the base string's character count plus one, so
26
+ * the count carries `c(L)`, the total characters across all `L`-unit strings:
27
+ * `c(L) = a·(c(L − 1) + f(L − 1)) + b·(c(L − 2) + f(L − 2))`. A filler from
28
+ * inside the composition produces a string already counted, so only the BMP
29
+ * scalars outside it add new ones.
30
+ *
31
+ * Every length in `[min, max]` is assumed reachable, which holds for every
32
+ * built-in `distribution`; a `custom` one that gives a length zero probability
33
+ * leaves the count too high, and the last strings surface as
34
+ * `UniqueRedrawsError` rather than `UniqueExhaustedError`.
35
+ */
36
+ export declare function toStringDomain(whereby: Whereby): StringDomain;
@@ -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.string` 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
  /**
@@ -1,7 +1,7 @@
1
1
  import type { Produce } from "../../Random/Types";
2
2
  import { Kind } from "../../Types";
3
3
  import { Schema } from "./Schema";
4
- import type { Fabricated, InputWhereby, JsonSchema, Whereby } from "./Types";
4
+ import type { Fabricated, InputUniqueWhereby, InputWhereby, Whereby } from "./Types";
5
5
  declare const _default: {
6
6
  /**
7
7
  * The builder carries the primitive's `[Kind]` so it can be named directly as
@@ -11,12 +11,11 @@ declare const _default: {
11
11
  [Kind]: "string";
12
12
  /**
13
13
  * Derive a custom string type: a `string` Schema whose production is
14
- * `produce`, optionally tagged with a `format` hint that schema exporters
15
- * (e.g. `toTypeBox`) read.
14
+ * `produce`. Chain `.admits({ format })` (or `pattern`) to tell adapters what
15
+ * the strings are.
16
16
  */
17
- as: (produce: Produce<Fabricated>, hints?: JsonSchema) => Schema<{
17
+ as: (produce: Produce<Fabricated>) => Schema<{
18
18
  produce: Produce<Fabricated>;
19
- hints: JsonSchema | undefined;
20
19
  }>;
21
20
  /**
22
21
  * A string of `length` UTF-16 code units. `length` is a bare `N` (exactly N)
@@ -40,3 +39,25 @@ declare const _default: {
40
39
  }>;
41
40
  };
42
41
  export default _default;
42
+ /**
43
+ * `T.unique.string`, assembled into the namespace by `Primitive/unique`. No
44
+ * `as`: a producer replaces the draw, so it would discard the one thing this
45
+ * builder adds.
46
+ */
47
+ export declare const unique: {
48
+ /** See the default export's `[Kind]`. */
49
+ [Kind]: "string";
50
+ /**
51
+ * A string the built Fabricator never repeats, drawn like `T.string.whereby`.
52
+ * Each draw is redrawn while it matches one already produced, up to `redraws`
53
+ * times in a row. The strings a length and composition can spell are counted
54
+ * exactly (`Capacity.ts`'s `toStringDomain`), so the draw after the last one
55
+ * throws `UniqueExhaustedError` rather than spending the cap. A `custom`
56
+ * length distribution can leave lengths unreachable that the count assumes
57
+ * reachable; those last strings surface as `UniqueRedrawsError`.
58
+ */
59
+ whereby: (whereby: InputUniqueWhereby) => Schema<{
60
+ whereby: Whereby;
61
+ unique: true;
62
+ }>;
63
+ };
@@ -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, JsonSchema, Meta as ThisMeta } from "./Types";
5
+ import type { Core, Fabricated, Meta as ThisMeta, Admits, InputAdmits } from "./Types";
6
6
  /**
7
7
  * Buildable `string` recipe: length/composition (`whereby` — required, unlike
8
8
  * `number`/`date`; no natural bound to fuzz a length to), or opaque production
@@ -19,7 +19,33 @@ export interface Schema<$Meta extends ThisMeta = ThisMeta, $Adaptations extends
19
19
  * `whereby` forward, not discarding it, so a later `.as(...)` (or future
20
20
  * validation of `produce`) still has it to check against.
21
21
  */
22
- as: (produce: Produce<Fabricated>, hints?: JsonSchema) => Schema<$Meta, $Adaptations>;
22
+ as: (produce: Produce<Fabricated>) => Schema<$Meta, $Adaptations>;
23
+ /**
24
+ * State what adapters admit for this schema, widening the bounds `whereby`
25
+ * draws — a `length.max` set small for test data need not cap what is
26
+ * accepted at runtime. Canonical `admits`; every other kind's method is the
27
+ * same and points here.
28
+ *
29
+ * Each end named replaces the current one, `Infinity` (`-Infinity` for a
30
+ * `min`) states no limit, and each end left out keeps what is admitted
31
+ * already — by default the drawn bounds, which is what an adapter states
32
+ * without this — so successive calls merge. Admitting may only widen: an end
33
+ * that excludes a value this schema can fabricate throws
34
+ * `AdmitsExcludesDrawError`, since that value would fail its own validation.
35
+ * Under `.as(produce)` nothing is drawn and nothing is checked.
36
+ *
37
+ * `format` and `pattern` ride along: JSON-Schema keywords for what the
38
+ * strings are, merged the same way and never checked against what is drawn.
39
+ * Like `.adapt`, the caller vouches that fabricated values match them —
40
+ * usually by fabricating through `.as(produce)`. `number` takes `multipleOf`
41
+ * the same way.
42
+ *
43
+ * This library validates nothing itself; `admits` only describes the set an
44
+ * adapter translates. `.as(...)` and `.adapt(...)` carry it forward.
45
+ */
46
+ admits: (admitted: InputAdmits) => Schema<$Meta & {
47
+ admits: Admits;
48
+ }, $Adaptations>;
23
49
  /**
24
50
  * Check that this schema's fabricated value type is assignable to `$Target`.
25
51
  * Identity at runtime; the target is not carried into later chained calls —
@@ -0,0 +1,16 @@
1
+ import type { CharacterSource, CodepointRange, Composition } from "./Types";
2
+ /**
3
+ * A composition as weighted character sources — the shape `Fabricator.ts` draws
4
+ * from and `Capacity.ts` counts. No composition is every Unicode scalar value;
5
+ * a class-name record maps each name to its preset ranges.
6
+ */
7
+ export declare function toSources(composition: Composition | undefined): ReadonlyArray<readonly [number, CharacterSource]>;
8
+ /** Normalize any character source to its underlying code point ranges. */
9
+ export declare function toRanges(source: CharacterSource): ReadonlyArray<CodepointRange>;
10
+ /**
11
+ * Single-UTF-16-unit, well-formed code points (the BMP minus surrogates). Used
12
+ * to top up a length budget when a drawn unit is too wide to fit the remaining
13
+ * space (`Fabricator.ts`'s `fabricate`), which also puts them in the set of
14
+ * strings `Capacity.ts` counts.
15
+ */
16
+ export declare const bmpScalars: ReadonlyArray<CodepointRange>;
@@ -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 = {}> = {
@@ -5,5 +5,10 @@ type ThisRegistry = Schema<{}, Adaptations> & {
5
5
  key: string;
6
6
  }>;
7
7
  };
8
- declare const registry: ThisRegistry;
8
+ /**
9
+ * A function, not the Schema itself: `Schema/Registry.ts` installs it as the
10
+ * `T.symbol` getter, so every read is a distinct Schema — see AGENTS.md's
11
+ * "Registry entries are getters."
12
+ */
13
+ declare function registry(): ThisRegistry;
9
14
  export default registry;
@@ -1,3 +1,8 @@
1
1
  import { Schema } from "./Schema";
2
- declare const registry: Schema;
2
+ /**
3
+ * A function, not the Schema itself: `Schema/Registry.ts` installs it as the
4
+ * `T.undefined` getter, so every read is a distinct Schema — see AGENTS.md's
5
+ * "Registry entries are getters."
6
+ */
7
+ declare function registry(): Schema;
3
8
  export default registry;
@@ -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";