@ghostry/fabricator 0.0.8 → 0.0.10

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 (77) hide show
  1. package/dist/esm/Bound.js +6 -1
  2. package/dist/esm/Distribution/index.js +51 -11
  3. package/dist/esm/Instance/Core.js +8 -8
  4. package/dist/esm/Primitive/always/Schema.js +2 -0
  5. package/dist/esm/Primitive/array/Fabricator.js +4 -9
  6. package/dist/esm/Primitive/array/Schema.js +2 -0
  7. package/dist/esm/Primitive/bigint/Schema.js +2 -0
  8. package/dist/esm/Primitive/boolean/Schema.js +2 -0
  9. package/dist/esm/Primitive/choice/Schema.js +2 -0
  10. package/dist/esm/Primitive/date/Schema.js +2 -0
  11. package/dist/esm/Primitive/derive/Schema.js +2 -0
  12. package/dist/esm/Primitive/enum/Schema.js +2 -0
  13. package/dist/esm/Primitive/null/Schema.js +2 -0
  14. package/dist/esm/Primitive/nullable/Schema.js +2 -0
  15. package/dist/esm/Primitive/nullish/Schema.js +2 -0
  16. package/dist/esm/Primitive/number/Fabricator.js +3 -7
  17. package/dist/esm/Primitive/number/Schema.js +2 -0
  18. package/dist/esm/Primitive/object/Schema.js +3 -1
  19. package/dist/esm/Primitive/object/compute/Schema.js +2 -0
  20. package/dist/esm/Primitive/object/omittable/Schema.js +2 -0
  21. package/dist/esm/Primitive/object/optional/Schema.js +2 -0
  22. package/dist/esm/Primitive/opaque/Schema.js +2 -0
  23. package/dist/esm/Primitive/record/Fabricator.js +6 -1
  24. package/dist/esm/Primitive/record/Schema.js +2 -0
  25. package/dist/esm/Primitive/recursive/Schema.js +2 -0
  26. package/dist/esm/Primitive/recursive/self/Schema.js +2 -0
  27. package/dist/esm/Primitive/string/Fabricator.js +6 -2
  28. package/dist/esm/Primitive/string/Schema.js +2 -0
  29. package/dist/esm/Primitive/symbol/Schema.js +2 -0
  30. package/dist/esm/Primitive/tuple/Schema.js +2 -0
  31. package/dist/esm/Primitive/undefinable/Schema.js +2 -0
  32. package/dist/esm/Primitive/undefined/Schema.js +2 -0
  33. package/dist/esm/Schema/Satisfies.js +5 -0
  34. package/dist/esm/index.js +1 -0
  35. package/dist/esm/internal.js +1 -0
  36. package/dist/types/Bound.d.ts +20 -4
  37. package/dist/types/Distribution/index.d.ts +36 -2
  38. package/dist/types/Error/index.d.ts +2 -4
  39. package/dist/types/Harnessing/Core.d.ts +4 -4
  40. package/dist/types/Primitive/always/Schema.d.ts +8 -1
  41. package/dist/types/Primitive/array/Registry.d.ts +7 -5
  42. package/dist/types/Primitive/array/Schema.d.ts +7 -0
  43. package/dist/types/Primitive/array/Types.d.ts +3 -9
  44. package/dist/types/Primitive/bigint/Schema.d.ts +7 -0
  45. package/dist/types/Primitive/boolean/Schema.d.ts +7 -0
  46. package/dist/types/Primitive/choice/Registry.d.ts +3 -3
  47. package/dist/types/Primitive/choice/Schema.d.ts +7 -0
  48. package/dist/types/Primitive/date/Schema.d.ts +7 -0
  49. package/dist/types/Primitive/derive/Schema.d.ts +8 -0
  50. package/dist/types/Primitive/derive/Types.d.ts +5 -6
  51. package/dist/types/Primitive/enum/Registry.d.ts +3 -3
  52. package/dist/types/Primitive/enum/Schema.d.ts +7 -0
  53. package/dist/types/Primitive/null/Schema.d.ts +9 -2
  54. package/dist/types/Primitive/nullable/Schema.d.ts +7 -0
  55. package/dist/types/Primitive/nullish/Schema.d.ts +7 -0
  56. package/dist/types/Primitive/number/Schema.d.ts +7 -0
  57. package/dist/types/Primitive/object/Schema.d.ts +12 -2
  58. package/dist/types/Primitive/object/compute/Schema.d.ts +8 -0
  59. package/dist/types/Primitive/object/omittable/Schema.d.ts +10 -1
  60. package/dist/types/Primitive/object/optional/Schema.d.ts +9 -1
  61. package/dist/types/Primitive/opaque/Schema.d.ts +8 -1
  62. package/dist/types/Primitive/record/Schema.d.ts +7 -0
  63. package/dist/types/Primitive/record/Types.d.ts +2 -2
  64. package/dist/types/Primitive/recursive/Schema.d.ts +8 -1
  65. package/dist/types/Primitive/recursive/self/Schema.d.ts +11 -1
  66. package/dist/types/Primitive/string/Registry.d.ts +13 -9
  67. package/dist/types/Primitive/string/Schema.d.ts +7 -0
  68. package/dist/types/Primitive/string/Types.d.ts +7 -11
  69. package/dist/types/Primitive/symbol/Schema.d.ts +7 -0
  70. package/dist/types/Primitive/tuple/Schema.d.ts +7 -0
  71. package/dist/types/Primitive/undefinable/Schema.d.ts +7 -0
  72. package/dist/types/Primitive/undefined/Schema.d.ts +9 -2
  73. package/dist/types/Schema/Satisfies.d.ts +84 -0
  74. package/dist/types/Schema/Types.d.ts +17 -1
  75. package/dist/types/index.d.ts +9 -0
  76. package/dist/types/internal.d.ts +7 -0
  77. package/package.json +1 -1
@@ -1,3 +1,4 @@
1
+ import type { Distribution } from "./Distribution";
1
2
  /**
2
3
  * Canonical endpoint stored on `[Meta].whereby`. Call sites still accept a
3
4
  * scalar (inclusive) via {@link InputBound}; `.whereby()` runs {@link toBound} so
@@ -56,13 +57,28 @@ export declare function towardInterior(value: number, toward: number): number;
56
57
  export declare function constrainContinuous(next: () => number, min: Bound<number>, max: Bound<number>): () => number;
57
58
  export declare function epochBound(bound: Bound<Date>): Bound<number>;
58
59
  /**
59
- * Array/string `length`: a bare number is an exact count; an omitted `min` is
60
- * inclusive `0`. Always stored as a Bound pair so adapters have one path.
60
+ * Call-site `length` for `string` and `array`: a bare number is an exact count,
61
+ * and `{ max, min?, distribution? }` is a range. A scalar end is inclusive.
61
62
  */
62
- export declare function toLengthRange(length: number | {
63
+ export type InputLength = number | {
63
64
  max: InputBound<number>;
64
65
  min?: InputBound<number> | undefined;
65
- }, label: string): {
66
+ distribution?: Distribution | undefined;
67
+ };
68
+ /**
69
+ * Stored `length`: both ends are canonical {@link Bound}s. `distribution` is
70
+ * present only when the caller set one, so a bare count and an unspecified
71
+ * distribution stay off the stored object.
72
+ */
73
+ export type Length = {
66
74
  min: Bound<number>;
67
75
  max: Bound<number>;
76
+ distribution?: Distribution | undefined;
68
77
  };
78
+ /**
79
+ * Array/string `length`: a bare number is an exact count (no distribution); an
80
+ * omitted `min` is inclusive `0`. Always stored as a Bound pair so adapters
81
+ * have one path. `distribution` is copied only when the caller set one,
82
+ * matching `date/Registry.ts`'s `toWhereby`, so stored meta stays minimal.
83
+ */
84
+ export declare function toLengthRange(length: InputLength, label: string): Length;
@@ -88,6 +88,20 @@ export declare namespace Distribution {
88
88
  */
89
89
  const custom: (shape: (u: number) => number) => Distribution;
90
90
  }
91
+ /**
92
+ * Integer draw over the inclusive `[min, max]` of `range`. Samples `[min, max +
93
+ * 1)` and floors, so each integer owns a full-width bucket — avoiding the
94
+ * half-width endpoint bias that rounding a `[min, max]` draw would produce. An
95
+ * omitted `distribution` is uniform. `range` is already the effective inclusive
96
+ * interval; exclusive ends are the caller's to resolve (`effectiveDiscrete`).
97
+ *
98
+ * The `Math.min(max, …)` clamp is load-bearing, not defensive. `max + 1` is
99
+ * exact even at `Number.MAX_SAFE_INTEGER` (it is 2^53), but near there doubles
100
+ * are spaced 1 apart, so `sampler`'s `(1 - u) * min + u * (max + 1)` can round
101
+ * up to exactly `max + 1` — e.g. `[MAX_SAFE_INTEGER - 10, MAX_SAFE_INTEGER]` —
102
+ * which would floor to one past `max`.
103
+ */
104
+ export declare function discreteSampler(distribution: Distribution | undefined, range: Range, stream: Stream): () => number;
91
105
  /**
92
106
  * Build a sampler that draws values within `range` following `distribution`.
93
107
  * Each call consumes one fresh uniform draw and, by construction, returns a
@@ -120,8 +134,9 @@ export declare function isDrawable(weight: number): boolean;
120
134
  * Whether a weight is _expressible_ at all, as opposed to whether it is
121
135
  * drawable. `0` is valid and disables the outcome; a negative weight or `NaN`
122
136
  * is a mistake. `Infinity` is rejected because it cannot be summed into a
123
- * usable draw table — every cumulative bound becomes `Infinity`, so
124
- * `weighted()`'s `x < weight` scan matches nothing.
137
+ * usable draw table — the sum becomes `Infinity`, so `weighted()`'s alias
138
+ * scaling (`weight * n / sum`) yields `NaN` for the infinite entry and `0` for
139
+ * every other.
125
140
  */
126
141
  export declare function isValidWeight(weight: number): boolean;
127
142
  /**
@@ -152,4 +167,23 @@ export declare function assertDrawableWeights(label: string, noun: string, items
152
167
  * defaulted in stage 2.
153
168
  */
154
169
  export declare function assertDrawableKeyedWeights<$Outcome extends string>(label: string, outcomes: ReadonlyArray<$Outcome>, weights: Readonly<Record<string, number | undefined>>): void;
170
+ /**
171
+ * A pick over `weights`, in O(1) per call regardless of table size. The table
172
+ * is built once, here, during `new Fabricator(...)`; the returned closure is
173
+ * what `.fabricate()` calls.
174
+ *
175
+ * Two paths, chosen at construction:
176
+ *
177
+ * - **Equal weights** (every `.uniform(...)` registry, every default-weighted
178
+ * presence wrapper) need no table at all: the pick is `discreteSampler`'s
179
+ * uniform index draw, one `stream.next()` per call.
180
+ * - **Unequal weights** use Vose's alias method (see {@link toAliasTable}): draw
181
+ * a column with that same index draw, then a second `stream.next()` as a coin
182
+ * between the column's own item and its alias. The coin is a separate draw
183
+ * rather than the fractional remainder of the first, because that remainder
184
+ * keeps only `53 - log2(n)` bits, which coarsens the probabilities as the
185
+ * table grows. A column whose probability is `1` returns without drawing the
186
+ * coin; the draw count stays a pure function of the stream, so this is still
187
+ * replayable.
188
+ */
155
189
  export declare function weighted<const $Item>(weights: ReadonlyArray<readonly [number, $Item]>, stream: Stream, label: string): () => $Item;
@@ -128,8 +128,7 @@ export declare namespace FabricatorError {
128
128
  */
129
129
  readonly label: string;
130
130
  /**
131
- * What the caller calls its items, e.g.
132
- * `"member"`/`"option"`/`"item"`.
131
+ * What the caller calls its items, e.g. `"member"`/`"option"`/`"item"`.
133
132
  */
134
133
  readonly noun: string;
135
134
  constructor(
@@ -139,8 +138,7 @@ export declare namespace FabricatorError {
139
138
  */
140
139
  label: string,
141
140
  /**
142
- * What the caller calls its items, e.g.
143
- * `"member"`/`"option"`/`"item"`.
141
+ * What the caller calls its items, e.g. `"member"`/`"option"`/`"item"`.
144
142
  */
145
143
  noun: string);
146
144
  }
@@ -35,10 +35,10 @@ import type { FabricatorTestContext, Integration } from "./Types";
35
35
  * captured result would pin one frame.
36
36
  *
37
37
  * The per-test wrap is entered on `context.scope()`, so it governs that
38
- * instance and its ancestors: the integrated instance when nothing encloses
39
- * it, and that instance as an ancestor of the enclosing scope when something
40
- * does. It does not govern forks of the integrated instance. Per-test data
41
- * therefore comes from the instance handed to `integration(...)`, from
38
+ * instance and its ancestors: the integrated instance when nothing encloses it,
39
+ * and that instance as an ancestor of the enclosing scope when something does.
40
+ * It does not govern forks of the integrated instance. Per-test data therefore
41
+ * comes from the instance handed to `integration(...)`, from
42
42
  * `context.fabricator`, or from a fork of that scope — a module-level fork of
43
43
  * the integrated instance draws the same data in every test, and because its
44
44
  * construction counter runs across tests, which values a test gets depends on
@@ -1,6 +1,7 @@
1
1
  import { type AdaptationEntry } from "../../Adapter/Core";
2
2
  import type { Adaptations, Adapter, Adapting, WithAdaptations } from "../../Adapter/Types";
3
- import type { Core, Value } from "./Types";
3
+ import { type SatisfiesThis } from "../../Schema/Satisfies";
4
+ import type { Core, Fabricated, Value } from "./Types";
4
5
  /**
5
6
  * A fixed value, so unlike every other kind there is no `.as()` — nothing left
6
7
  * to override about producing it. `adapt` still applies: what a value _means_
@@ -10,6 +11,12 @@ import type { Core, Value } from "./Types";
10
11
  * close the gap.
11
12
  */
12
13
  export interface Schema<$Value extends Value = Value, $Adaptations extends Adaptations = {}> extends Core<$Value, $Adaptations> {
14
+ /**
15
+ * Check that this schema's fabricated value type is assignable to `$Target`.
16
+ * Identity at runtime; the target is not carried into later chained calls —
17
+ * see `object/Schema.ts`'s `satisfies`.
18
+ */
19
+ satisfies<$Target>(this: this & SatisfiesThis<Fabricated<$Value>, $Target>): Schema<$Value, $Adaptations>;
13
20
  /**
14
21
  * Override what this schema maps to in one or more external schema libraries
15
22
  * — see `string/Schema.ts`'s `adapt` for the full contract.
@@ -3,11 +3,13 @@ import { Schema } from "./Schema";
3
3
  import type { Definition, Fabricated, InputWhereby } from "./Types";
4
4
  type ThisRegistry<$Definition extends Definition> = {
5
5
  /**
6
- * An array of `definition`, repeated `whereby.length` times — either a fixed
7
- * count, or uniformly across `[length.min, length.max]` with `length.min`
8
- * defaulting to inclusive 0, so an empty array is a legitimate outcome when
9
- * no `min` is given. Exclusive ends use a Bound object; a bare `length: N` is
10
- * stored as min = max = N inclusive.
6
+ * An array of `definition`, repeated `length` times. `length` is a bare `N`
7
+ * (exactly N) or `{ min?, max, distribution? }`. `min` defaults to inclusive
8
+ * 0, so an empty array is a legitimate outcome when no `min` is given.
9
+ * Exclusive ends use a Bound object. A bare `N` is stored as min = max = N
10
+ * inclusive and carries no distribution. Without `distribution`, the length
11
+ * is drawn uniformly across the inclusive interval; `distribution` shapes
12
+ * that draw the same way it does for `T.number.integer`.
11
13
  */
12
14
  whereby: (whereby: InputWhereby) => Schema<$Definition>;
13
15
  /**
@@ -1,6 +1,7 @@
1
1
  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
+ import { type SatisfiesThis } from "../../Schema/Satisfies";
4
5
  import type { Core, Definition, Fabricated } from "./Types";
5
6
  /**
6
7
  * The buildable recipe for an `array`: a single element Schema, repeated
@@ -13,6 +14,12 @@ export interface Schema<$Definition extends Definition = Definition, $Adaptation
13
14
  * (or future validation of `produce`) still has them to check against.
14
15
  */
15
16
  as: (produce: Produce<Fabricated<$Definition>>) => Schema<$Definition, $Adaptations>;
17
+ /**
18
+ * Check that this schema's fabricated value type is assignable to `$Target`.
19
+ * Identity at runtime; the target is not carried into later chained calls —
20
+ * see `object/Schema.ts`'s `satisfies`.
21
+ */
22
+ satisfies<$Target>(this: this & SatisfiesThis<Fabricated<$Definition>, $Target>): Schema<$Definition, $Adaptations>;
16
23
  /**
17
24
  * Override what this schema maps to in one or more external schema libraries
18
25
  * — see `string/Schema.ts`'s `adapt` for the full contract.
@@ -1,21 +1,15 @@
1
1
  import type { Adaptations } from "../../Adapter/Types";
2
- import type { Bound, InputBound } from "../../Bound";
2
+ import type { InputLength, Length } from "../../Bound";
3
3
  import type { Produce } from "../../Random/Types";
4
4
  import type { AnySchema, ValueOf } from "../../Schema/Types";
5
5
  import type { Adaptation, Kind, Meta, Produces } from "../../Types";
6
6
  export type Definition = AnySchema;
7
7
  export type Fabricated<$Definition extends Definition, $Bindings extends unknown[] = []> = Array<ValueOf<$Definition, $Bindings>>;
8
8
  export type InputWhereby = {
9
- length: number | {
10
- max: InputBound<number>;
11
- min?: InputBound<number> | undefined;
12
- };
9
+ length: InputLength;
13
10
  };
14
11
  export type Whereby = {
15
- length: {
16
- min: Bound<number>;
17
- max: Bound<number>;
18
- };
12
+ length: Length;
19
13
  };
20
14
  /**
21
15
  * `whereby` (a length spec — no natural bound to fuzz to, so unlike
@@ -1,6 +1,7 @@
1
1
  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
+ import { type SatisfiesThis } from "../../Schema/Satisfies";
4
5
  import type { Core, Fabricated, Meta as ThisMeta } from "./Types";
5
6
  /**
6
7
  * Buildable `bigint` recipe: a range (`whereby` — required, like `string`; no
@@ -18,6 +19,12 @@ export interface Schema<$Meta extends ThisMeta = ThisMeta, $Adaptations extends
18
19
  * validation of `produce`) still has it to check against.
19
20
  */
20
21
  as: (produce: Produce<Fabricated>) => Schema<$Meta, $Adaptations>;
22
+ /**
23
+ * Check that this schema's fabricated value type is assignable to `$Target`.
24
+ * Identity at runtime; the target is not carried into later chained calls —
25
+ * see `object/Schema.ts`'s `satisfies`.
26
+ */
27
+ satisfies<$Target>(this: this & SatisfiesThis<Fabricated, $Target>): Schema<$Meta, $Adaptations>;
21
28
  /**
22
29
  * Override what this schema maps to in one or more external schema libraries
23
30
  * — see `string/Schema.ts`'s `adapt` for the full contract.
@@ -1,6 +1,7 @@
1
1
  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
+ import { type SatisfiesThis } from "../../Schema/Satisfies";
4
5
  import type { Core, Fabricated, Meta as ThisMeta, Weights } from "./Types";
5
6
  /**
6
7
  * Buildable `boolean` recipe: an even coin flip, a weighted one (`weights`), or
@@ -18,6 +19,12 @@ export interface Schema<$Meta extends ThisMeta = ThisMeta, $Adaptations extends
18
19
  * validation of `produce`) still has it to check against.
19
20
  */
20
21
  as: (produce: Produce<Fabricated>) => Schema<$Meta, $Adaptations>;
22
+ /**
23
+ * Check that this schema's fabricated value type is assignable to `$Target`.
24
+ * Identity at runtime; the target is not carried into later chained calls —
25
+ * see `object/Schema.ts`'s `satisfies`.
26
+ */
27
+ satisfies<$Target>(this: this & SatisfiesThis<Fabricated, $Target>): Schema<$Meta, $Adaptations>;
21
28
  weighted: (weights: Weights) => Schema<$Meta, $Adaptations>;
22
29
  /**
23
30
  * Override what this schema maps to in one or more external schema libraries
@@ -13,9 +13,9 @@ type Weighted<$Items extends ReadonlyArray<Item>> = {
13
13
  };
14
14
  /**
15
15
  * At least one element — a `choice` with no option has nothing to draw, which
16
- * would otherwise fail inside `weighted()` (`Distribution/index.ts`) with an
17
- * opaque `TypeError` at fabricate time (weight sum is `0`, so `.find` returns
18
- * `undefined` and `chosen![1]` throws).
16
+ * would otherwise surface only as `weighted()`'s (`Distribution/index.ts`)
17
+ * generic `NoDrawableOutcomesError` at construction, naming an "outcome" rather
18
+ * than this registry's own `EmptyItemsError` for an option.
19
19
  *
20
20
  * Only a _statically_ empty tuple (a literal `[]`) is a compile error. A
21
21
  * dynamically built array — e.g. `.map()` over an `as const` array — is
@@ -1,6 +1,7 @@
1
1
  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
+ import { type SatisfiesThis } from "../../Schema/Satisfies";
4
5
  import type { Core, Fabricated, Items } from "./Types";
5
6
  /**
6
7
  * Buildable `choice` recipe: a weighted set of option Schemas, one of which is
@@ -15,6 +16,12 @@ export interface Schema<$Items extends Items = Items, $Adaptations extends Adapt
15
16
  * validation of `produce`) still has it to check against.
16
17
  */
17
18
  as: (produce: Produce<Fabricated<$Items>>) => Schema<$Items, $Adaptations>;
19
+ /**
20
+ * Check that this schema's fabricated value type is assignable to `$Target`.
21
+ * Identity at runtime; the target is not carried into later chained calls —
22
+ * see `object/Schema.ts`'s `satisfies`.
23
+ */
24
+ satisfies<$Target>(this: this & SatisfiesThis<Fabricated<$Items>, $Target>): Schema<$Items, $Adaptations>;
18
25
  /**
19
26
  * Override what this schema maps to in one or more external schema libraries
20
27
  * — see `string/Schema.ts`'s `adapt` for the full contract.
@@ -1,6 +1,7 @@
1
1
  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
+ import { type SatisfiesThis } from "../../Schema/Satisfies";
4
5
  import type { Core, Fabricated, Meta as ThisMeta } from "./Types";
5
6
  /**
6
7
  * Buildable `Date` recipe: a range/distribution (`whereby`, absent for the
@@ -18,6 +19,12 @@ export interface Schema<$Meta extends ThisMeta = ThisMeta, $Adaptations extends
18
19
  * future validation of `produce`) still has them to check against.
19
20
  */
20
21
  as: (produce: Produce<Fabricated>) => Schema<$Meta, $Adaptations>;
22
+ /**
23
+ * Check that this schema's fabricated value type is assignable to `$Target`.
24
+ * Identity at runtime; the target is not carried into later chained calls —
25
+ * see `object/Schema.ts`'s `satisfies`.
26
+ */
27
+ satisfies<$Target>(this: this & SatisfiesThis<Fabricated, $Target>): Schema<$Meta, $Adaptations>;
21
28
  /**
22
29
  * Override what this schema maps to in one or more external schema libraries
23
30
  * — see `string/Schema.ts`'s `adapt` for the full contract.
@@ -1,6 +1,7 @@
1
1
  import { type AdaptationEntry } from "../../Adapter/Core";
2
2
  import type { Adaptations, Adapter, Adapting, WithAdaptations } from "../../Adapter/Types";
3
3
  import type { ProduceContext } from "../../Random/Types";
4
+ import { type SatisfiesThis } from "../../Schema/Satisfies";
4
5
  import type * as tuple from "../tuple/Types";
5
6
  import type { Core, From, Resolved, Source } from "./Types";
6
7
  /**
@@ -24,6 +25,13 @@ export type Deriver<$From extends From, $To extends Source> = {
24
25
  * for the mismatch check against `to`.
25
26
  */
26
27
  export interface Schema<$From extends From = From, $To extends Source = Source, $Adaptations extends Adaptations = {}> extends Core<$From, $To, $Adaptations> {
28
+ /**
29
+ * Check that this schema's fabricated value type is assignable to `$Target`.
30
+ * Identity at runtime; the target is not carried into later chained calls —
31
+ * see `object/Schema.ts`'s `satisfies`. The produced type is `to`'s
32
+ * (`Resolved<$To>`), not `from`'s.
33
+ */
34
+ satisfies<$Target>(this: this & SatisfiesThis<Resolved<$To>, $Target>): Schema<$From, $To, $Adaptations>;
27
35
  /**
28
36
  * Override what this schema maps to in one or more external schema libraries
29
37
  * — see `string/Schema.ts`'s `adapt` for the full contract. An unadapted
@@ -18,12 +18,11 @@ export type { Denoted, Resolved, Source } from "../object/compute/Types";
18
18
  * `from` is stored after `toSchema` (inert per-slot schemas, same as `tuple`).
19
19
  * `to` is stored exactly as given, whether a Schema or a builder, so its
20
20
  * `[Meta]` and `[Adaptation]` survive: adapters convert it as a nested schema
21
- * (honoring its own adaptation unless the derive is adapted), and
22
- * `toValueKind` follows it to the kind a result or override is checked
23
- * against. `resolve` is plain data from the moment `.as(resolve)` is called.
24
- * `to` is only used for its shape/type — the value comes entirely from
25
- * `resolve`, which is why `to` may not even have a buildable recipe (a bare
26
- * `T.string`/`T.bigint`).
21
+ * (honoring its own adaptation unless the derive is adapted), and `toValueKind`
22
+ * follows it to the kind a result or override is checked against. `resolve` is
23
+ * plain data from the moment `.as(resolve)` is called. `to` is only used for
24
+ * its shape/type — the value comes entirely from `resolve`, which is why `to`
25
+ * may not even have a buildable recipe (a bare `T.string`/`T.bigint`).
27
26
  */
28
27
  export type Meta<$From extends From = From, $To extends Source = Source> = {
29
28
  from: $From;
@@ -14,9 +14,9 @@ type Weighted<$Items extends ReadonlyArray<Item>> = {
14
14
  };
15
15
  /**
16
16
  * At least one element — an `enum` with no member has nothing to draw, which
17
- * would otherwise fail inside `weighted()` (`Distribution/index.ts`) with an
18
- * opaque `TypeError` at fabricate time (weight sum is `0`, so `.find` returns
19
- * `undefined` and `chosen![1]` throws).
17
+ * would otherwise surface only as `weighted()`'s (`Distribution/index.ts`)
18
+ * generic `NoDrawableOutcomesError` at construction, naming an "outcome" rather
19
+ * than this registry's own `EmptyItemsError` for a member.
20
20
  *
21
21
  * Only a _statically_ empty tuple (a literal `[]`) is a compile error. A
22
22
  * dynamically built array — e.g. `.map()` over an `as const` array — is
@@ -1,6 +1,7 @@
1
1
  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
+ import { type SatisfiesThis } from "../../Schema/Satisfies";
4
5
  import type { Core, Fabricated, Items } from "./Types";
5
6
  /**
6
7
  * The buildable recipe for an `enum`: a weighted set of member values, one of
@@ -14,6 +15,12 @@ export interface Schema<$Items extends Items = Items, $Adaptations extends Adapt
14
15
  * validation of `produce`) still has it to check against.
15
16
  */
16
17
  as: (produce: Produce<Fabricated<$Items>>) => Schema<$Items, $Adaptations>;
18
+ /**
19
+ * Check that this schema's fabricated value type is assignable to `$Target`.
20
+ * Identity at runtime; the target is not carried into later chained calls —
21
+ * see `object/Schema.ts`'s `satisfies`.
22
+ */
23
+ satisfies<$Target>(this: this & SatisfiesThis<Fabricated<$Items>, $Target>): Schema<$Items, $Adaptations>;
17
24
  /**
18
25
  * Override what this schema maps to in one or more external schema libraries
19
26
  * — see `string/Schema.ts`'s `adapt` for the full contract.
@@ -1,12 +1,19 @@
1
1
  import { type AdaptationEntry } from "../../Adapter/Core";
2
2
  import type { Adaptations, Adapter, Adapting, WithAdaptations } from "../../Adapter/Types";
3
- import type { Core, Meta as ThisMeta } from "./Types";
3
+ import { type SatisfiesThis } from "../../Schema/Satisfies";
4
+ import type { Core, Fabricated, Meta as ThisMeta } from "./Types";
4
5
  /**
5
6
  * Nothing to configure (see `Types.ts`'s `Meta`), so `adapt` is this kind's
6
- * only builder method — an external library that spells "null" differently
7
+ * only mapping method — an external library that spells "null" differently
7
8
  * still needs a way to say so.
8
9
  */
9
10
  export interface Schema<$Adaptations extends Adaptations = {}> extends Core<ThisMeta, $Adaptations> {
11
+ /**
12
+ * Check that this schema's fabricated value type is assignable to `$Target`.
13
+ * Identity at runtime; the target is not carried into later chained calls —
14
+ * see `object/Schema.ts`'s `satisfies`.
15
+ */
16
+ satisfies<$Target>(this: this & SatisfiesThis<Fabricated, $Target>): Schema<$Adaptations>;
10
17
  /**
11
18
  * Override what this schema maps to in one or more external schema libraries
12
19
  * — see `string/Schema.ts`'s `adapt` for the full contract.
@@ -1,6 +1,7 @@
1
1
  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
+ import { type SatisfiesThis } from "../../Schema/Satisfies";
4
5
  import type { AnySchema } from "../../Schema/Types";
5
6
  import type { Core, Definition, Fabricated, Weights } from "./Types";
6
7
  /**
@@ -16,6 +17,12 @@ export interface Schema<$Definition extends Definition = Definition, $Adaptation
16
17
  * does.
17
18
  */
18
19
  as: (produce: Produce<Fabricated<$Definition>>) => Schema<$Definition, $Adaptations>;
20
+ /**
21
+ * Check that this schema's fabricated value type is assignable to `$Target`.
22
+ * Identity at runtime; the target is not carried into later chained calls —
23
+ * see `object/Schema.ts`'s `satisfies`.
24
+ */
25
+ satisfies<$Target>(this: this & SatisfiesThis<Fabricated<$Definition>, $Target>): Schema<$Definition, $Adaptations>;
19
26
  /**
20
27
  * Reweight the built-in 50/50 roll. Keys are optional — an omitted key keeps
21
28
  * baseline weight `1`, the same weight the 50/50 split already uses — but
@@ -1,6 +1,7 @@
1
1
  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
+ import { type SatisfiesThis } from "../../Schema/Satisfies";
4
5
  import type { AnySchema } from "../../Schema/Types";
5
6
  import type { Core, Definition, Fabricated, Weights } from "./Types";
6
7
  /**
@@ -16,6 +17,12 @@ export interface Schema<$Definition extends Definition = Definition, $Adaptation
16
17
  * built-in three-way roll does.
17
18
  */
18
19
  as: (produce: Produce<Fabricated<$Definition>>) => Schema<$Definition, $Adaptations>;
20
+ /**
21
+ * Check that this schema's fabricated value type is assignable to `$Target`.
22
+ * Identity at runtime; the target is not carried into later chained calls —
23
+ * see `object/Schema.ts`'s `satisfies`.
24
+ */
25
+ satisfies<$Target>(this: this & SatisfiesThis<Fabricated<$Definition>, $Target>): Schema<$Definition, $Adaptations>;
19
26
  /**
20
27
  * Reweight the built-in three-way roll. Keys are optional — an omitted key
21
28
  * keeps baseline weight `1`, the same weight the uniform 1/3 split already
@@ -1,6 +1,7 @@
1
1
  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
+ import { type SatisfiesThis } from "../../Schema/Satisfies";
4
5
  import type { Core, Fabricated, JsonSchema, Meta as ThisMeta } from "./Types";
5
6
  /**
6
7
  * Buildable `number` recipe: a range/distribution (`whereby`, absent for the
@@ -22,6 +23,12 @@ export interface Schema<$Meta extends ThisMeta = ThisMeta, $Adaptations extends
22
23
  * against.
23
24
  */
24
25
  as: (produce: Produce<Fabricated>, hints?: JsonSchema) => Schema<$Meta, $Adaptations>;
26
+ /**
27
+ * Check that this schema's fabricated value type is assignable to `$Target`.
28
+ * Identity at runtime; the target is not carried into later chained calls —
29
+ * see `object/Schema.ts`'s `satisfies`.
30
+ */
31
+ satisfies<$Target>(this: this & SatisfiesThis<Fabricated, $Target>): Schema<$Meta, $Adaptations>;
25
32
  /**
26
33
  * Override what this schema maps to in one or more external schema libraries
27
34
  * — see `string/Schema.ts`'s `adapt` for the full contract.
@@ -1,6 +1,7 @@
1
1
  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
+ import { type SatisfiesThis } from "../../Schema/Satisfies";
4
5
  import type { AnySchema } from "../../Schema/Types";
5
6
  import type { ShallowMerge } from "../../Utility/ShallowMerge";
6
7
  import type { Computer } from "./compute/Schema";
@@ -22,6 +23,14 @@ export interface Schema<$Definition extends Definition = Definition, $Adaptation
22
23
  * against.
23
24
  */
24
25
  as: (produce: Produce<Fabricated<$Definition>>) => Schema<$Definition, $Adaptations>;
26
+ /**
27
+ * Check that this schema's fabricated value type is assignable to `$Target`.
28
+ * Identity at runtime; the target is not carried into later chained calls.
29
+ * Canonical `.satisfies`; every other kind's method is the same and points
30
+ * here. See `Schema/Satisfies.ts` for the `this`-param signature and why the
31
+ * alternatives fail.
32
+ */
33
+ satisfies<$Target>(this: this & SatisfiesThis<Fabricated<$Definition>, $Target>): Schema<$Definition, $Adaptations>;
25
34
  /**
26
35
  * Override what this schema maps to in one or more external schema libraries
27
36
  * — see `string/Schema.ts`'s `adapt` for the full contract. Carried through
@@ -35,7 +44,8 @@ export interface Schema<$Definition extends Definition = Definition, $Adaptation
35
44
  * `make` alongside `extend`/`refine`/`override`: those three rebuild from
36
45
  * `definition`/`refinements` rather than deriving from this object, so the
37
46
  * adaptation map has to be threaded through `make` itself or chaining one of
38
- * them would drop it (see `make`'s `adapt`).
47
+ * them would drop it (see `make`'s `adapt`). `as` and `satisfies` are the
48
+ * methods this factory attaches, so they are what the parameter omits.
39
49
  */
40
- export declare function Schema<$Definition extends Definition, $Adaptations extends Adaptations = {}>(schema: Omit<Schema<$Definition, $Adaptations>, "as">): Schema<$Definition, $Adaptations>;
50
+ export declare function Schema<$Definition extends Definition, $Adaptations extends Adaptations = {}>(schema: Omit<Schema<$Definition, $Adaptations>, "as" | "satisfies">): Schema<$Definition, $Adaptations>;
41
51
  export declare function isObjectSchema(candidate: AnySchema): candidate is Schema;
@@ -1,6 +1,7 @@
1
1
  import { type AdaptationEntry } from "../../../Adapter/Core";
2
2
  import type { Adaptations, Adapter, Adapting, WithAdaptations } from "../../../Adapter/Types";
3
3
  import type { AnySchema } from "../../../Schema/Types";
4
+ import { type SatisfiesThis } from "../../../Schema/Satisfies";
4
5
  import type * as object from "../Types";
5
6
  import type { Core, Resolved, Source } from "./Types";
6
7
  export type Computer<$Definition extends object.Definition> = <const $Source extends Source>(source: $Source) => {
@@ -9,6 +10,13 @@ export type Computer<$Definition extends object.Definition> = <const $Source ext
9
10
  }) => NoInfer<Resolved<$Source>>) => Schema<object.Fabricated<$Definition>, $Source>;
10
11
  };
11
12
  export interface Schema<$Fabricated, $Source extends Source, $Adaptations extends Adaptations = {}> extends Core<$Fabricated, $Source, $Adaptations> {
13
+ /**
14
+ * Check that this schema's fabricated value type is assignable to `$Target`.
15
+ * Identity at runtime; the target is not carried into later chained calls —
16
+ * see `object/Schema.ts`'s `satisfies`. The produced type is `source`'s
17
+ * (`Resolved<$Source>`), not the enclosing object's.
18
+ */
19
+ satisfies<$Target>(this: this & SatisfiesThis<Resolved<$Source>, $Target>): Schema<$Fabricated, $Source, $Adaptations>;
12
20
  /**
13
21
  * Override what this schema maps to in one or more external schema libraries
14
22
  * — see `string/Schema.ts`'s `adapt` for the full contract. Adapting the
@@ -1,8 +1,9 @@
1
1
  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
+ import { type SatisfiesThis } from "../../../Schema/Satisfies";
4
5
  import type { AnySchema } from "../../../Schema/Types";
5
- import type { Core, Definition, Resolved, Weights } from "./Types";
6
+ import type { Core, Definition, Fabricated, Resolved, Weights } from "./Types";
6
7
  export interface Schema<$Definition extends Definition = Definition, $Adaptations extends Adaptations = {}> extends Core<$Definition, $Adaptations> {
7
8
  /**
8
9
  * Layer an opaque production on this schema's existing `[Meta]` — carrying
@@ -12,6 +13,14 @@ export interface Schema<$Definition extends Definition = Definition, $Adaptation
12
13
  * built-in roll does.
13
14
  */
14
15
  as: (produce: Produce<Resolved<$Definition>>) => Schema<$Definition, $Adaptations>;
16
+ /**
17
+ * Check that this schema's fabricated value type is assignable to `$Target`.
18
+ * Identity at runtime; the target is not carried into later chained calls —
19
+ * see `object/Schema.ts`'s `satisfies`. The produced type is the wrapped
20
+ * value (not `Omitted`); omission is a fact about the enclosing object's
21
+ * keys, which is why this check lives more usefully on the object.
22
+ */
23
+ satisfies<$Target>(this: this & SatisfiesThis<Fabricated<$Definition>, $Target>): Schema<$Definition, $Adaptations>;
15
24
  /**
16
25
  * Reweight the built-in presence roll. Keys are optional — an omitted key
17
26
  * keeps baseline weight `1`, the same weight the 50/50 split already uses —
@@ -1,8 +1,9 @@
1
1
  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
+ import { type SatisfiesThis } from "../../../Schema/Satisfies";
4
5
  import type { AnySchema } from "../../../Schema/Types";
5
- import type { Core, Definition, Resolved, Weights } from "./Types";
6
+ import type { Core, Definition, Fabricated, Resolved, Weights } from "./Types";
6
7
  export interface Schema<$Definition extends Definition = Definition, $Adaptations extends Adaptations = {}> extends Core<$Definition, $Adaptations> {
7
8
  /**
8
9
  * Layer an opaque production on this schema's existing `[Meta]` — carrying
@@ -12,6 +13,13 @@ export interface Schema<$Definition extends Definition = Definition, $Adaptation
12
13
  * built-in three-way roll does.
13
14
  */
14
15
  as: (produce: Produce<Resolved<$Definition>>) => Schema<$Definition, $Adaptations>;
16
+ /**
17
+ * Check that this schema's fabricated value type is assignable to `$Target`.
18
+ * Identity at runtime; the target is not carried into later chained calls —
19
+ * see `object/Schema.ts`'s `satisfies`. The produced type includes `|
20
+ * undefined`; omission is a fact about the enclosing object's keys.
21
+ */
22
+ satisfies<$Target>(this: this & SatisfiesThis<Fabricated<$Definition>, $Target>): Schema<$Definition, $Adaptations>;
15
23
  /**
16
24
  * Reweight the built-in three-way roll. Keys are optional — an omitted key
17
25
  * keeps baseline weight `1`, the same weight the uniform 1/3 split already
@@ -1,6 +1,7 @@
1
1
  import { type AdaptationEntry } from "../../Adapter/Core";
2
2
  import type { Adaptations, Adapter, Adapting, WithAdaptations } from "../../Adapter/Types";
3
- import type { Core } from "./Types";
3
+ import { type SatisfiesThis } from "../../Schema/Satisfies";
4
+ import type { Core, Fabricated } from "./Types";
4
5
  /**
5
6
  * Escape hatch for values no kind models — a `Map`, a `Set`, a `URL`, a class
6
7
  * instance, a branded type. `produce` is supplied at construction and receives
@@ -12,6 +13,12 @@ import type { Core } from "./Types";
12
13
  * imprecise, and `.adapt(typebox, ...)` is the only way to say more.
13
14
  */
14
15
  export interface Schema<$T = unknown, $Adaptations extends Adaptations = {}> extends Core<$T, $Adaptations> {
16
+ /**
17
+ * Check that this schema's fabricated value type is assignable to `$Target`.
18
+ * Identity at runtime; the target is not carried into later chained calls —
19
+ * see `object/Schema.ts`'s `satisfies`.
20
+ */
21
+ satisfies<$Target>(this: this & SatisfiesThis<Fabricated<$T>, $Target>): Schema<$T, $Adaptations>;
15
22
  /**
16
23
  * Override what this schema maps to in one or more external schema libraries
17
24
  * — see `string/Schema.ts`'s `adapt` for the full contract.