@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,7 +1,8 @@
1
1
  import type { Adaptations } from "../Adapter/Types";
2
2
  import type { Kind as SchemaKind } from "../Primitive";
3
- import { Adaptation, Kind, Meta, type Produced, type Produces } from "../Types";
3
+ import { Adaptation, Kind, Meta, type Buildable, type Produced, type Produces } from "../Types";
4
4
  import { type PlainObject } from "../Utility/Types";
5
+ import type { AnySchema } from "./Types";
5
6
  /**
6
7
  * Normalize a Schema, a builder namespace, or an already-built Fabricator into
7
8
  * a clean, storable Schema — keeping only `[Kind]`/ `[Meta]`/`[Adaptation]` and
@@ -36,6 +37,20 @@ export declare function toSchema<$Kind extends string, $Meta extends PlainObject
36
37
  readonly [Produces]?: Produced<$Produces>;
37
38
  readonly [Adaptation]?: $Adaptations;
38
39
  };
40
+ /**
41
+ * Whether `candidate` is something `new Fabricator(...)` can build: a Schema or
42
+ * a built Fabricator, which both carry a `[Kind]` tag and a `[Meta]`. A bare
43
+ * builder that is a function (`T.array`, `T.recursive`) fails the first test;
44
+ * one that is an object but has no `[Kind]` fails the second. `T.string` and
45
+ * `T.bigint` carry `[Kind]` so they can name a compute source, but have no
46
+ * `[Meta]` until `.whereby(...)`, and fail the third.
47
+ */
48
+ export declare function isBuildable(candidate: unknown): candidate is Buildable;
49
+ /**
50
+ * {@link isBuildable}, excluding a built Fabricator: a Schema is inert, and only
51
+ * a Fabricator has `fabricate`.
52
+ */
53
+ export declare function isSchema(candidate: unknown): candidate is AnySchema;
39
54
  /**
40
55
  * The `[Kind]` a schema's fabricated value should be checked against with
41
56
  * {@link violatesKind}. For most kinds that is its own `[Kind]`, but
@@ -2,11 +2,14 @@ import * as primitives from "../Primitive";
2
2
  import { deepMerge, type DeepMerge } from "../Utility/DeepMerge";
3
3
  import { type PlainObject } from "../Utility/Types";
4
4
  /**
5
- * `Primitive/index.ts` also exports the kind-module namespace as `Primitive`
6
- * (`Primitive.boolean.Schema`, …). That is not a builder — omitting it here is
7
- * what keeps `T.Primitive` from existing.
5
+ * A kind whose `Registry.ts` default export takes no arguments returns a bare
6
+ * Schema, which `builders` installs behind a getter; every builder takes at
7
+ * least one. A bare kind left without a getter therefore fails to compile in
8
+ * `builders`, where the spread supplies the function itself.
8
9
  */
9
- type Builders = Omit<typeof primitives, "Primitive">;
10
+ type Builders = {
11
+ [$K in Exclude<keyof typeof primitives, "Primitive">]: (typeof primitives)[$K] extends () => infer $Schema ? $Schema : (typeof primitives)[$K];
12
+ };
10
13
  type RegistryInterface<$Registry> = {
11
14
  extend: <const $Extension extends PlainObject>(types: (params: {
12
15
  T: $Registry;
@@ -83,6 +83,15 @@ export declare const Adaptation: unique symbol;
83
83
  * distinguishes the two outcomes).
84
84
  */
85
85
  export declare const Omitted: unique symbol;
86
+ /**
87
+ * Marks a value as already produced, carried only by a built `T.unique.*` leaf
88
+ * (`Unique/Distinct.ts`'s `Tracker`). A per-call override skips that leaf's
89
+ * draw, so `object/Fabricator.ts` hands the override value here through
90
+ * `Unique/Override.ts`'s `recordOverride`, and no later draw repeats it.
91
+ * Recording only — claiming a value already produced is not an error, since the
92
+ * caller asked for it.
93
+ */
94
+ export declare const Claim: unique symbol;
86
95
  /**
87
96
  * Everything `construct()`/`toTypeBox()` accept as a starting point: a
88
97
  * not-yet-built Schema, or something already built into a Fabricator.
@@ -0,0 +1,29 @@
1
+ import { type Buildable } from "../Types";
2
+ /**
3
+ * How many times one built Fabricator of `schema` can `fabricate()` before a
4
+ * `T.unique.*` leaf runs out, or `undefined` when no leaf has a known limit.
5
+ * The answer for a fresh Fabricator: it does not count what an existing one has
6
+ * already drawn.
7
+ */
8
+ export type Capacity = (schema: Buildable) => bigint | undefined;
9
+ /**
10
+ * Walk `schema` — the Schema, not a build, so nothing is constructed, no
11
+ * ordinal is taken, and an object's hidden fields are seen — and take the
12
+ * tightest limit any unique leaf sets. A leaf allows `capacity / draws`
13
+ * fabrications, `draws` being the most times one fabrication can reach it: one,
14
+ * multiplied by `length.max`/`size.max` for each array or record above it.
15
+ *
16
+ * Conservative where a leaf may not draw at all: one behind a presence wrapper
17
+ * or a `choice` option is counted as drawing every time. Not counted, since
18
+ * they never limit one Fabricator's fabrications:
19
+ *
20
+ * - a unique collection's members, distinct only within each value and checked
21
+ * against the length at construction;
22
+ * - anything under `T.recursive`, whose expansions each build afresh;
23
+ * - a `[Fixed]` field and an `object.compute` source, which never draw;
24
+ * - any node with `.as(...)`, whose producer replaces everything beneath it;
25
+ * - a leaf of unknown size, such as a continuous `T.unique.number` range.
26
+ *
27
+ * `clock` resolves a `date` leaf's `past`/`future` end.
28
+ */
29
+ export declare function toCapacity(schema: Buildable, clock: number): bigint | undefined;
@@ -0,0 +1,95 @@
1
+ import { type Distribution, type Range } from "../Distribution";
2
+ import type { Fabricator } from "../Fabricator/Types";
3
+ import type { Whereby as BigintWhereby } from "../Primitive/bigint/Types";
4
+ import type { Meta as NumberMeta } from "../Primitive/number/Types";
5
+ import type { Stream } from "../Random/Types";
6
+ import { type Strategy } from "./Strategy";
7
+ /**
8
+ * How many distinct values a unique `number` can produce: every integer of an
9
+ * integer range, skewed or not, and for a continuous range only the single
10
+ * value of one whose ends meet — any other continuous range is left uncounted.
11
+ * Shared by {@link toNumberStrategy} and `Unique/Capacity.ts`.
12
+ */
13
+ export declare function toNumberCapacity(meta: NumberMeta): bigint | undefined;
14
+ /**
15
+ * The size of an inclusive integer range, exact past `Number.MAX_SAFE_INTEGER`.
16
+ */
17
+ export declare function toRangeCapacity(range: Range): bigint;
18
+ /**
19
+ * How a unique `number` draws. A uniform integer range small enough for exact
20
+ * positions is a sparse Fisher–Yates permutation on `stream`. Everything else —
21
+ * an unbounded integer, a skewed integer range, any continuous range — tracks
22
+ * the numbers it has produced, calling `draw` (the kind's ordinary sampler)
23
+ * until it lands on a new one. An integer range keeps its exact size as
24
+ * `capacity` even when tracked, so it exhausts by counting rather than by
25
+ * spinning; a continuous range has one only when its two ends meet.
26
+ *
27
+ * Shared by `number/Fabricator.ts` (a `T.unique.number` leaf, with its own
28
+ * stream and sampler) and {@link toDistinct} (a collection member, with the
29
+ * collection's stream and the member's `fabricate`). A leaf's cap is its own
30
+ * `whereby.redraws`; a member's is the collection's.
31
+ */
32
+ export declare function toNumberStrategy(options: {
33
+ label: string;
34
+ meta: NumberMeta;
35
+ stream: Stream;
36
+ draw: () => number;
37
+ redraws?: number | undefined;
38
+ }): Strategy;
39
+ /**
40
+ * How a unique `date` draws, over `range` — every whole millisecond a draw can
41
+ * produce (`date/Defaults.ts`'s `toEpochRange`). A uniform range small enough
42
+ * for exact positions is a permutation of those milliseconds, like an integer
43
+ * range. Anything wider or skewed tracks the instants produced, by time value,
44
+ * and its exact size lets it exhaust by counting.
45
+ *
46
+ * Both draw whole milliseconds from `stream` — the tracked path through
47
+ * `discreteSampler`, the integer draw — never through the kind's ordinary
48
+ * continuous sampler. That sampler reaches the upper millisecond only when a
49
+ * draw lands exactly on it, so a count that includes it would leave the last
50
+ * instant all but unreachable and the final draw spinning to the cap.
51
+ */
52
+ export declare function toDateStrategy(options: {
53
+ label: string;
54
+ range: Range;
55
+ distribution: Distribution | undefined;
56
+ stream: Stream;
57
+ redraws?: number | undefined;
58
+ }): Strategy;
59
+ /**
60
+ * How a unique `bigint` draws: a bigint sparse Fisher–Yates permutation of its
61
+ * range on `stream`, exact at any width.
62
+ */
63
+ export declare function toBigintStrategy(whereby: BigintWhereby, stream: Stream): Strategy;
64
+ /**
65
+ * How a unique collection (`T.unique.array`'s elements, `T.unique.record`'s
66
+ * keys) draws distinct members from `member`, an already-built Fabricator.
67
+ * Chosen once, at construction, by reading `member`'s `[Kind]`/`[Meta]`; the
68
+ * collection then opens a fresh scope per `fabricate()` call.
69
+ *
70
+ * Exact strategies draw from `stream`, the collection's own, never from the
71
+ * member's — the member's own `fabricate` is simply not called. A `date` member
72
+ * reads its range against its own `trace.clock`. Everything else is tracked by
73
+ * canonical key over `member.fabricate`: any member under a `by` projection or
74
+ * an `.as(...)` producer, and also a member that does not repeat by itself (a
75
+ * `sequence`, a bare `symbol`, a `T.unique.*` leaf). Trusting the last group
76
+ * would save a hash per member, but a unique leaf does repeat once it cycles
77
+ * under `combinatorial`/`coverage` (`Fabricator/Types.ts`'s `Exhaustion`), and
78
+ * a repeat would land inside one value.
79
+ *
80
+ * Reads another kind's `[Meta]`, which AGENTS.md otherwise keeps kind-private —
81
+ * the same exception `Enumeration/Plan.ts` takes, for the same reason: the
82
+ * finite value set a kind draws from is exactly what is needed here.
83
+ */
84
+ export declare function toDistinct(member: Fabricator<unknown>, stream: Stream, options: {
85
+ label: string;
86
+ by?: ((value: any) => unknown) | undefined;
87
+ redraws?: number | undefined;
88
+ }): Strategy;
89
+ /**
90
+ * Reject, at construction, a collection that may ask for more distinct members
91
+ * than its member schema has — so an exact member can never run out on a draw
92
+ * whose size depends on the salt. A member of unknown capacity passes; it is
93
+ * left to the tracked scope's cap.
94
+ */
95
+ export declare function assertCapacity(label: string, strategy: Strategy, requested: number): void;
@@ -0,0 +1,29 @@
1
+ /**
2
+ * Maps a value to a number that equal values share — what a tracked unique
3
+ * scope (`Unique/Strategy.ts`) stores in place of the value itself, so memory
4
+ * per produced value stays one number however large the value is.
5
+ */
6
+ export type Keyer = (value: unknown) => number;
7
+ /**
8
+ * A fresh {@link Keyer}, owning the identity tables its encoding needs. Two
9
+ * values share a key when they are the same plain data:
10
+ *
11
+ * - Primitives compare by SameValueZero, as a `Set` would: `-0` is `0`, `NaN` is
12
+ * `NaN`, and `"1"` is not `1`.
13
+ * - A `Date` compares by its time value.
14
+ * - Arrays compare element by element, a hole reading as `undefined`.
15
+ * - Plain objects compare by their own enumerable keys and values, in any key
16
+ * order. A key present as `undefined` differs from an absent one, the
17
+ * distinction `T.optional` draws.
18
+ *
19
+ * Everything else — symbols, functions, and objects that are not plain data
20
+ * (`Map`, `Set`, class instances) — compares by identity, through an id the
21
+ * tables hand out on first sight. Structural rules for those would be guesses;
22
+ * a `by` projection says what makes one unique.
23
+ *
24
+ * The encoding is hashed to 53 bits (`cyrb128`'s first two words), exact as a
25
+ * `number`. The error is one-sided: two different values sharing a hash makes a
26
+ * scope skip one of them, never produce a duplicate. Across a million values
27
+ * that happens with probability around 5e-5.
28
+ */
29
+ export declare function toKeyer(): Keyer;
@@ -0,0 +1,16 @@
1
+ /**
2
+ * Record a per-call override on the `T.unique.*` leaf it stands in for, so no
3
+ * later draw repeats it. An override skips the field's draw
4
+ * (`object/Fabricator.ts`), so without this the leaf would never learn that the
5
+ * value was used.
6
+ *
7
+ * The field handed in is not always the leaf: `T.omittable(T.unique...)` is how
8
+ * an optional unique field is spelled. So this walks down through the
9
+ * single-child presence wrappers via `[Children]`, stopping where `value` is
10
+ * that wrapper's own outcome (`null`, `undefined`, `Omitted`) rather than its
11
+ * child's, and calls the leaf's `[Claim]`. Any other node ends the walk: a
12
+ * nested `object` records its own fields through its own
13
+ * `fabricate(overrides)`, and nothing else holds a unique leaf whose draw an
14
+ * override could stand in for.
15
+ */
16
+ export declare function recordOverride(field: any, value: unknown): void;
@@ -0,0 +1,135 @@
1
+ import { type Range } from "../Distribution";
2
+ import { FabricatorError } from "../Error";
3
+ import type { Exhaustion } from "../Fabricator/Types";
4
+ import type { Stream } from "../Random/Types";
5
+ import { type Keyer } from "./Key";
6
+ /**
7
+ * One run of distinct draws: nothing `draw` returns repeats anything it, or
8
+ * `claim`, saw before in the same scope. A `T.unique.*` leaf opens one scope
9
+ * for its built Fabricator's lifetime; a unique collection opens a fresh one
10
+ * per `fabricate()` call.
11
+ */
12
+ export type Scope = {
13
+ draw: () => unknown;
14
+ /**
15
+ * Record `value` as produced without drawing it — an override value
16
+ * (`Unique/Override.ts`). Recording only: claiming a value already produced,
17
+ * or one outside the domain, changes nothing.
18
+ */
19
+ claim: (value: unknown) => void;
20
+ };
21
+ /**
22
+ * How a schema's distinct values are drawn. `capacity` is how many there are,
23
+ * when that is known, which is what lets a collection reject an impossible size
24
+ * at construction rather than on a salt-dependent draw.
25
+ */
26
+ export type Strategy = {
27
+ readonly capacity: bigint | undefined;
28
+ open: () => Scope;
29
+ };
30
+ export declare function defaultRedraws(produced: number): number;
31
+ /**
32
+ * The `redraws` every `T.unique.*` builder's `.whereby` accepts: how many times
33
+ * in a row a tracked draw may repeat a value already produced while looking for
34
+ * a new one, before it forfeits — per value, not across the scope. `0` means
35
+ * one draw and no retries. Replaces the default formula
36
+ * ({@link defaultRedraws}); a skewed distribution is what needs it most, since
37
+ * its rarest values take many draws to find. Validated by {@link toRedraws},
38
+ * and stored on each kind's `Whereby` as a plain `redraws` field.
39
+ */
40
+ export type Redraws = {
41
+ redraws?: number | undefined;
42
+ };
43
+ /**
44
+ * Validate a caller-supplied `redraws`. It counts retries, so any whole number
45
+ * from `0` up can be one.
46
+ */
47
+ export declare function toRedraws(label: string, redraws: number | undefined): number | undefined;
48
+ /**
49
+ * Sampling without replacement from a weighted list of values — `enum`,
50
+ * `boolean`, and the single-value kinds. Equal values (by {@link toKeyer}) are
51
+ * merged first, their weights summed, so `capacity` counts distinct values and
52
+ * `T.enum.uniform(["a", "a", "b"])` still draws `"a"` two times in three. Draws
53
+ * come from `stream`, the owning node's own.
54
+ */
55
+ export declare function exactValues(kind: string, entries: ReadonlyArray<readonly [number, unknown]>, stream: Stream): Strategy;
56
+ /**
57
+ * `entries`' drawable values with equal ones merged and their weights summed,
58
+ * each tagged with its canonical key — what {@link exactValues} draws from, and
59
+ * what `Unique/Capacity.ts` counts for a unique `enum`. Returns the
60
+ * {@link Keyer} too, since a claim must key a value the same way.
61
+ */
62
+ export declare function toDistinctValues(entries: ReadonlyArray<readonly [number, unknown]>): {
63
+ keyer: Keyer;
64
+ values: Array<[number, {
65
+ key: number;
66
+ value: unknown;
67
+ }]>;
68
+ };
69
+ /**
70
+ * Sampling without replacement from a uniform integer range, by sparse
71
+ * Fisher–Yates (`Distribution/index.ts`'s `permutation`). A claimed value is
72
+ * held aside and skipped when the permutation reaches it — consumed, not
73
+ * redrawn into — which leaves every later draw uniform over what remains.
74
+ * Precondition: the range's size is at most `Number.MAX_SAFE_INTEGER`.
75
+ */
76
+ export declare function exactRange(kind: string, range: Range, stream: Stream): Strategy;
77
+ /**
78
+ * {@link exactRange} over a bigint range — no size precondition.
79
+ */
80
+ export declare function exactBigintRange(kind: string, range: {
81
+ min: bigint;
82
+ max: bigint;
83
+ }, stream: Stream): Strategy;
84
+ /**
85
+ * Rejection sampling: draw, and draw again while the key has been seen. For
86
+ * every domain no exact strategy covers — strings, dates, composites,
87
+ * `.as(...)`, a skewed or unbounded integer range, a `by` projection.
88
+ *
89
+ * `key` reduces a value to what is stored: a number for a numeric domain (`Set`
90
+ * compares those by SameValueZero already), a {@link Keyer} hash otherwise. When
91
+ * `capacity` is known the scope counts rather than searches — exhausted the
92
+ * moment it has seen that many, with no retries. `admits` keeps a claimed value
93
+ * from outside the domain out of that count: an override of `0` on a `[1, 10]`
94
+ * field must not use up one of its ten.
95
+ */
96
+ export declare function tracked(options: {
97
+ label: string;
98
+ kind: string;
99
+ draw: () => unknown;
100
+ key: (value: unknown) => unknown;
101
+ capacity?: bigint | undefined;
102
+ admits?: ((value: unknown) => boolean) | undefined;
103
+ redraws?: number | undefined;
104
+ }): Strategy;
105
+ /**
106
+ * {@link tracked} keyed by a fresh {@link Keyer}, through `by` when given.
107
+ */
108
+ export declare function trackedByKey(options: {
109
+ label: string;
110
+ kind: string;
111
+ draw: () => unknown;
112
+ by?: ((value: any) => unknown) | undefined;
113
+ capacity?: bigint | undefined;
114
+ admits?: ((value: unknown) => boolean) | undefined;
115
+ redraws?: number | undefined;
116
+ }): Strategy;
117
+ /**
118
+ * `member.fabricate`, for a plain `T.array`/`T.record` whose element or key is
119
+ * a `T.unique.*` leaf (one carrying `[Claim]`): an exhaustion it raises is
120
+ * re-raised naming the collection, whose message points at the per-value
121
+ * builder. Any other member is returned untouched, so the common path pays
122
+ * nothing.
123
+ */
124
+ export declare function withinCollection<$T>(collection: FabricatorError.UniqueWithin, member: {
125
+ fabricate: () => $T;
126
+ }): () => $T;
127
+ /**
128
+ * The scope a `T.unique.*` leaf keeps for its built Fabricator's whole life,
129
+ * under the build's exhaustion policy. Under `"cycle"` (an enumeration build —
130
+ * `Fabricator/Types.ts`'s `Exhaustion`), running out opens a fresh scope and
131
+ * draws again, as if nothing had been produced; claims go to whichever scope is
132
+ * current. Both exhaustion errors reset: a tracked leaf of unknown size knows
133
+ * it ran out only by hitting its cap.
134
+ */
135
+ export declare function toLifetimeScope(strategy: Strategy, exhaustion: Exhaustion): Scope;
@@ -11,4 +11,15 @@ export type DeepMerge<$A, $B> = $B extends {
11
11
  [_ in $K]?: infer $BV;
12
12
  } ? $BV : never;
13
13
  }>;
14
+ /**
15
+ * Copies property descriptors rather than values, so a getter stays a getter on
16
+ * the result. The registry depends on that: every registry entry that is a
17
+ * Schema is a getter returning a fresh object (`Schema/Registry.ts`), and a
18
+ * merge that copied its value would pin it to one.
19
+ *
20
+ * Where both sides hold a key, each is read once — a getter included — and the
21
+ * values merge as they always have. If either side was a getter, the result is
22
+ * a getter again, returning a new object {@link rebuilt} from the merged one on
23
+ * every read, so an entry an extension merges into stays fresh.
24
+ */
14
25
  export declare function deepMerge<$A extends PlainObject, $B extends PlainObject>(a: $A, b: $B): DeepMerge<$A, $B>;
@@ -105,6 +105,13 @@ export { registry } from "./Schema/Registry";
105
105
  */
106
106
  export { effectiveDiscrete, toBound } from "./Bound";
107
107
  export type { Bound, InputBound } from "./Bound";
108
+ /**
109
+ * What `.admits(...)` accepts for a group of ends, and how `[Meta].admits`
110
+ * stores it (an absent end states no limit). Exported so an argument built
111
+ * programmatically, or an `.adapt` producer reading `meta.admits`, can be typed
112
+ * — the same rationale as `Bound`.
113
+ */
114
+ export type { AdmittedEnds, InputAdmittedEnds } from "./Bound";
108
115
  /**
109
116
  * The `length` shapes `T.string`/`T.array`'s `.whereby(...)` accept and store,
110
117
  * and the `distribution` every range-bearing `whereby` takes. Exported so a
@@ -205,3 +212,9 @@ export type { Trace } from "./Random/Types";
205
212
  * anything a caller needs to name.
206
213
  */
207
214
  export type { Ancestry, Config, Context, Overlay, Stack, } from "./Instance/Types";
215
+ /**
216
+ * `capacity`'s type, and what `combinatorial`/`coverage` return, so a caller
217
+ * holding either can name it.
218
+ */
219
+ export type { Capacity } from "./Unique/Capacity";
220
+ export type { Enumeration } from "./Enumeration/Types";
@@ -44,6 +44,15 @@ export type { AsFabricator } from "./Fabricator/Types";
44
44
  */
45
45
  export { Children, Kind, Meta, Produces, type Buildable, type Produced, } from "./Types";
46
46
  export { isArray, isPlainObject } from "./Utility/Core";
47
+ /**
48
+ * The runtime counterparts of `Buildable` and `AnySchema`, for an integration
49
+ * that takes one from an untyped caller. `@ghostry/extern`'s fabricator
50
+ * extension claims a block identity with `isSchema`: a built Fabricator is not
51
+ * an identity, since a block could either continue its streams or build afresh
52
+ * from its schema.
53
+ */
54
+ export { isBuildable, isSchema } from "./Schema/Core";
55
+ export { toKeyer, type Keyer } from "./Unique/Key";
47
56
  export type * as Primitive from "./Primitive/namespace";
48
57
  /**
49
58
  * `Schema/Types.ts`'s own value-type resolution, needed by tests asserting
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@ghostry/fabricator",
3
- "version": "0.0.12",
3
+ "version": "0.0.14",
4
4
  "license": "MIT",
5
5
  "description": "Fabricate typed data from composable schemas.",
6
6
  "keywords": [
@@ -20,7 +20,7 @@
20
20
  "url": "git+https://github.com/ghostry-dev/fabricator",
21
21
  "directory": "pkg/fabricator"
22
22
  },
23
- "homepage": "https://docs.ghostry.dev/fabricator/",
23
+ "homepage": "https://docs.ghostry.dev/fabricator",
24
24
  "bugs": "https://github.com/ghostry-dev/fabricator/issues",
25
25
  "type": "module",
26
26
  "sideEffects": false,
@@ -65,7 +65,7 @@
65
65
  "provenance": true
66
66
  },
67
67
  "devDependencies": {
68
- "@ghostry/harness": "^0.0.5"
68
+ "@ghostry/harness": "^0.0.6"
69
69
  },
70
70
  "scripts": {
71
71
  "build:reset": "rm -rf ./dist",