@ghostry/fabricator 0.0.10 → 0.0.12

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 (86) hide show
  1. package/dist/esm/Distribution/index.js +1 -1
  2. package/dist/esm/Enumeration/Enumerate.js +2 -4
  3. package/dist/esm/Error/index.js +34 -6
  4. package/dist/esm/Fabricator/Constructor.js +40 -33
  5. package/dist/esm/Fabricator/Fabricate.js +28 -0
  6. package/dist/esm/Instance/Core.js +14 -2
  7. package/dist/esm/Instance/Stack/Visible.js +6 -1
  8. package/dist/esm/Primitive/date/Defaults.js +12 -0
  9. package/dist/esm/Primitive/date/Fabricator.js +5 -10
  10. package/dist/esm/Primitive/date/Registry.js +8 -4
  11. package/dist/esm/Primitive/index.js +2 -0
  12. package/dist/esm/Primitive/null/Registry.js +2 -3
  13. package/dist/esm/Primitive/number/Fabricator.js +1 -1
  14. package/dist/esm/Primitive/number/Registry.js +1 -1
  15. package/dist/esm/Primitive/object/Fabricator.js +33 -11
  16. package/dist/esm/Primitive/object/Registry.js +90 -10
  17. package/dist/esm/Primitive/object/compute/Fabricator.js +10 -3
  18. package/dist/esm/Primitive/object/compute/Registry.js +20 -3
  19. package/dist/esm/Primitive/object/omit/Registry.js +5 -0
  20. package/dist/esm/Primitive/object/omit/index.js +2 -0
  21. package/dist/esm/Primitive/object/pick/Registry.js +5 -0
  22. package/dist/esm/Primitive/object/pick/index.js +2 -0
  23. package/dist/esm/Primitive/recursive/Fabricator.js +1 -0
  24. package/dist/esm/Primitive/recursive/Terminate.js +21 -9
  25. package/dist/esm/Primitive/undefined/Registry.js +2 -3
  26. package/dist/esm/index.js +1 -0
  27. package/dist/esm/internal.js +2 -2
  28. package/dist/types/Adapter/Types.d.ts +3 -2
  29. package/dist/types/Distribution/index.d.ts +10 -0
  30. package/dist/types/Enumeration/Types.d.ts +3 -3
  31. package/dist/types/Error/index.d.ts +71 -6
  32. package/dist/types/Fabricator/Fabricate.d.ts +61 -0
  33. package/dist/types/Fabricator/Types.d.ts +21 -11
  34. package/dist/types/Harnessing/Core.d.ts +7 -7
  35. package/dist/types/Instance/Core.d.ts +15 -8
  36. package/dist/types/Instance/Stack/Visible.d.ts +10 -0
  37. package/dist/types/Instance/Types.d.ts +30 -15
  38. package/dist/types/Primitive/always/Types.d.ts +2 -2
  39. package/dist/types/Primitive/array/Types.d.ts +4 -4
  40. package/dist/types/Primitive/bigint/Types.d.ts +2 -2
  41. package/dist/types/Primitive/boolean/Types.d.ts +2 -2
  42. package/dist/types/Primitive/choice/Types.d.ts +4 -4
  43. package/dist/types/Primitive/date/Defaults.d.ts +11 -0
  44. package/dist/types/Primitive/date/Registry.d.ts +6 -8
  45. package/dist/types/Primitive/date/Types.d.ts +12 -2
  46. package/dist/types/Primitive/derive/Types.d.ts +2 -2
  47. package/dist/types/Primitive/enum/Types.d.ts +2 -2
  48. package/dist/types/Primitive/index.d.ts +2 -0
  49. package/dist/types/Primitive/null/Types.d.ts +2 -2
  50. package/dist/types/Primitive/nullable/Types.d.ts +4 -4
  51. package/dist/types/Primitive/nullish/Types.d.ts +4 -4
  52. package/dist/types/Primitive/number/Types.d.ts +2 -2
  53. package/dist/types/Primitive/object/Fabricator.d.ts +13 -5
  54. package/dist/types/Primitive/object/Registry.d.ts +17 -1
  55. package/dist/types/Primitive/object/Types.d.ts +28 -9
  56. package/dist/types/Primitive/object/compute/Fabricator.d.ts +9 -8
  57. package/dist/types/Primitive/object/compute/Registry.d.ts +7 -1
  58. package/dist/types/Primitive/object/compute/Schema.d.ts +20 -0
  59. package/dist/types/Primitive/object/compute/Types.d.ts +14 -4
  60. package/dist/types/Primitive/object/omit/Registry.d.ts +7 -0
  61. package/dist/types/Primitive/object/omit/index.d.ts +2 -0
  62. package/dist/types/Primitive/object/omittable/Types.d.ts +4 -4
  63. package/dist/types/Primitive/object/optional/Types.d.ts +4 -4
  64. package/dist/types/Primitive/object/pick/Registry.d.ts +8 -0
  65. package/dist/types/Primitive/object/pick/index.d.ts +2 -0
  66. package/dist/types/Primitive/opaque/Types.d.ts +2 -2
  67. package/dist/types/Primitive/record/Types.d.ts +11 -6
  68. package/dist/types/Primitive/recursive/Fabricator.d.ts +9 -7
  69. package/dist/types/Primitive/recursive/Types.d.ts +12 -8
  70. package/dist/types/Primitive/recursive/self/Schema.d.ts +4 -4
  71. package/dist/types/Primitive/recursive/self/Types.d.ts +7 -5
  72. package/dist/types/Primitive/string/Constants.d.ts +7 -31
  73. package/dist/types/Primitive/string/Types.d.ts +2 -2
  74. package/dist/types/Primitive/symbol/Types.d.ts +2 -2
  75. package/dist/types/Primitive/tuple/Types.d.ts +7 -7
  76. package/dist/types/Primitive/undefinable/Types.d.ts +4 -4
  77. package/dist/types/Primitive/undefined/Types.d.ts +2 -2
  78. package/dist/types/Schema/Core.d.ts +10 -6
  79. package/dist/types/Schema/Satisfies.d.ts +31 -23
  80. package/dist/types/Schema/Types.d.ts +31 -18
  81. package/dist/types/Types.d.ts +24 -0
  82. package/dist/types/index.d.ts +45 -18
  83. package/dist/types/internal.d.ts +24 -4
  84. package/package.json +5 -5
  85. /package/dist/esm/Primitive/number/{defaults.js → Defaults.js} +0 -0
  86. /package/dist/types/Primitive/number/{defaults.d.ts → Defaults.d.ts} +0 -0
@@ -1,7 +1,7 @@
1
1
  import type { Adaptations } from "../Adapter/Types";
2
2
  import type { NaiveFabricator } from "../Fabricator/Types";
3
3
  import type { Kind as SchemaKind } from "../Primitive";
4
- import type { Adaptation, Kind, Meta, Produces } from "../Types";
4
+ import type { Adaptation, Kind, Meta, Produced, Produces } from "../Types";
5
5
  import type { PlainObject } from "../Utility/Types";
6
6
  /**
7
7
  * The broadest Schema constraint: some kind, some config. Used by compound
@@ -25,7 +25,8 @@ export type AnySchema = {
25
25
  * `fabricate: () => $T` already plays for `NaiveFabricator<infer $T>`, one step
26
26
  * earlier, before a Schema has been built. `[Produces]` is always optional
27
27
  * (never assigned at runtime — see `DeepMerge`'s handling of optional-only keys
28
- * for why that matters).
28
+ * for why that matters), and what it holds is the value type boxed,
29
+ * `Produced<…>` (`Types.ts`), never the value type itself.
29
30
  *
30
31
  * A built Fabricator carries no `[Produces]` — its value type lives on
31
32
  * `fabricate: () => $T` (`Fabricator/Types.ts`) — yet `toSchema` lets one stand
@@ -55,25 +56,37 @@ export type AnySchema = {
55
56
  * this is closer to a de-Bruijn-style resolution environment — kept as a tuple,
56
57
  * as TypeBox's is, so a second bound self-reference could occupy index 1 later
57
58
  * without restructuring, though nothing today defines what that would mean.
58
- * `test/ValueOfBindings.types.test.ts` is the only thing asserting any of it.
59
+ * `test/FabricatedBindings.types.test.ts` is the only thing asserting any of
60
+ * it.
59
61
  *
60
62
  * Three details here are load-bearing, and each looks simplifiable:
61
63
  *
62
64
  * - **Indexed access, not a conditional `infer`.** Writing this as `($Schema & {
63
- * bindings: $Bindings }) extends { [Produces]?: infer $T } ? ...` fails with
64
- * `TS2615` — the bindings do not collapse, and the error surfaces as
65
- * `unknown[] & [...]`.
66
- * - **`Required<>`, never `Exclude<..., undefined>`.** Both strip the `|
67
- * undefined` that indexing an optional property adds, but `Exclude` also
68
- * strips the _legitimate_ `undefined` out of
69
- * `nullish`/`undefinable`/`object.optional`/`undefined`'s own value types.
70
- * - **The `extends` guard belongs inside, not on the parameter.** Constraining
71
- * `$Schema` instead would force `[Produces]` onto `AnySchema` (which
72
- * deliberately omits it), and that shifts variance enough to break `.as`'s
73
- * contravariant parameter check in `Fabrication.types.test.ts`.
65
+ * bindings: $Bindings }) extends { [Produces]?: Produced<infer $T> } ? ...`
66
+ * fails with `TS2615` — the bindings do not collapse, and the error surfaces
67
+ * as `unknown[] & [...]`.
68
+ * - **`Exclude<…, undefined>` is applied to the box, never to a value type.**
69
+ * Indexing an optional property adds `| undefined`, and `Exclude` strips
70
+ * every `undefined` in the union it is handed. That is exact only because the
71
+ * union is `Produced<…> | undefined`: the box is never `undefined`, so the
72
+ * one stripped is the modifier's, and the _legitimate_ `undefined` in
73
+ * `nullish`/`undefinable`/`object.optional`/`undefined`'s own value types
74
+ * sits inside the box, out of reach. No reader of an _unboxed_ value type can
75
+ * be exact: `Required<>` spares a declared `undefined` only when the consumer
76
+ * compiles with `exactOptionalPropertyTypes`, and strips it like `Exclude`
77
+ * when they do not. `Required<…>[typeof Produces]["value"]` is not a way to
78
+ * keep `Required<>` either — it fails `TS2536`.
79
+ * `test/Fabricated.types.test.ts`, compiled with the flag off by
80
+ * `tsconfig.inexact.json`, is the guard.
81
+ * - **The `extends` guard names the box, and belongs inside, not on the
82
+ * parameter.** Matched against `{ [Produces]?: unknown }`, the read has no
83
+ * `"value"` to index (`TS2536`). Constraining `$Schema` instead would force
84
+ * `[Produces]` onto `AnySchema` (which deliberately omits it), and that
85
+ * shifts variance enough to break `.as`'s contravariant parameter check in
86
+ * `Fabrication.types.test.ts`.
74
87
  */
75
- export type ValueOf<$Schema, $Bindings extends unknown[] = []> = $Schema extends NaiveFabricator<infer $T> ? $T : $Schema extends {
76
- readonly [Produces]?: unknown;
77
- } ? Required<$Schema & {
88
+ export type Fabricated<$Schema, $Bindings extends unknown[] = []> = $Schema extends NaiveFabricator<infer $T> ? $T : $Schema extends {
89
+ readonly [Produces]?: Produced<unknown>;
90
+ } ? Exclude<($Schema & {
78
91
  bindings: $Bindings;
79
- }>[typeof Produces] : unknown;
92
+ })[typeof Produces], undefined>["value"] : unknown;
@@ -5,6 +5,30 @@ export declare const Meta: unique symbol;
5
5
  export declare const Produces: unique symbol;
6
6
  export declare const Replace: unique symbol;
7
7
  export declare const Fixed: unique symbol;
8
+ /**
9
+ * What a Schema's phantom `[Produces]` holds: its value type, boxed.
10
+ *
11
+ * `[Produces]` is optional, and reading an optional property always yields `|
12
+ * undefined`. Whether that `undefined` can be told apart from one the value
13
+ * type itself contains depends on the _reader's_ `exactOptionalPropertyTypes`.
14
+ * With the flag on, the modifier contributes a distinct "missing" marker that
15
+ * `Required<>` strips on its own. With it off, the property is a plain `X |
16
+ * undefined`, and nothing recovers whether `X` held an `undefined` of its own —
17
+ * `Required<>` strips it exactly as `Exclude<…, undefined>` does, and inferring
18
+ * `$T` against `{ [Produces]?: $T }` absorbs it into the optional slot. A
19
+ * consumer compiles this library's declarations under their own tsconfig, so
20
+ * the flag is not this package's to choose.
21
+ *
22
+ * Boxed, the modifier's `undefined` sits beside the box and the value type's
23
+ * sits inside it, so the two never share a union. Stripping `undefined` off
24
+ * `Produced<X> | undefined` is exact under either setting — for `Fabricated`
25
+ * (`Schema/Types.ts`), and for anything that matches or infers through the
26
+ * brand, which has to name the box too: `{ readonly [Produces]?: Produced<$T>
27
+ * }`, never `{ readonly [Produces]?: $T }`.
28
+ */
29
+ export type Produced<$T> = {
30
+ readonly value: $T;
31
+ };
8
32
  /**
9
33
  * Tags a `Salt` as composing onto whatever base is in effect, rather than
10
34
  * replacing it — the reading a bare `salt` has everywhere else in this library.
@@ -23,7 +23,9 @@ export declare function initialize<const $Registry extends PlainObject = typeof
23
23
  * Bring your own PRNG: a factory that, given a seed, returns a source of
24
24
  * randomness — a `() => number` in `[0, 1)`, a drop-in for `Math.random`.
25
25
  * The seed is a whole encoded trace, of which `salt` is one slot, not the
26
- * `salt` itself. Defaults to the built-in `sfc32` generator.
26
+ * `salt` itself. Defaults to the built-in `sfc32` generator, which is not
27
+ * cryptographically secure; a generator that ignores its seed and draws
28
+ * from `crypto.getRandomValues` is, at the cost of all reproducibility.
27
29
  */
28
30
  algorithm?: Algorithm;
29
31
  /**
@@ -40,14 +42,18 @@ export declare function initialize<const $Registry extends PlainObject = typeof
40
42
  * every leaf's trace, the default entropy for the instance. Defaults to the
41
43
  * wall-clock instant of this `initialize()` call, so an unconfigured run
42
44
  * has realistic dates and varies by process, and replays from
43
- * `context.clock` (with the same empty or supplied `salt`). Pass a fixed
44
- * `Date` to freeze "now" (and the rest of the run, unless `salt` also
45
- * differs). Pass `"derived"` to derive "now" from the instance salt instead
46
- * — an instant drawn across the whole representable `Date` span, so an
47
- * implausible date is the expected outcome of that policy, not a bug.
48
- * `"derived"` is what makes `salt` alone the reproducibility unit.
45
+ * `context.clock` (with the same empty or supplied `salt`) handed back here
46
+ * as-is. Pass a fixed `Date`, or the same instant as epoch milliseconds, to
47
+ * freeze "now" (and the rest of the run, unless `salt` also differs). A
48
+ * number must be one a `Date` holds unchanged — an integer within ±8.64e15
49
+ * — or this throws `InvalidClockError` rather than adjusting it; an invalid
50
+ * `Date` throws the same way. Pass `"derived"` to derive "now" from the
51
+ * instance salt instead — an instant drawn across the whole representable
52
+ * `Date` span, so an implausible date is the expected outcome of that
53
+ * policy, not a bug. `"derived"` is what makes `salt` alone the
54
+ * reproducibility unit.
49
55
  */
50
- clock?: Date | "derived";
56
+ clock?: Date | number | "derived";
51
57
  /**
52
58
  * The ambient carrier backing `wrap` for this lineage — override only to
53
59
  * force a specific one. A choice of carrier and nothing more: lineage
@@ -79,8 +85,10 @@ export { layer } from "./Random";
79
85
  export type { Layered } from "./Random/Types";
80
86
  /**
81
87
  * Every failure this library raises is an instance of this class — see
82
- * `src/Error/index.ts` for the full hierarchy. Only the base is public;
83
- * subclasses are distinguished by `.name`.
88
+ * `src/Error/index.ts` for the full hierarchy. Every subclass is a member of
89
+ * the merged `FabricatorError` namespace, so this one export carries all of
90
+ * them: `e instanceof FabricatorError.InvalidOverrideValueError` works, and
91
+ * `.name` names the same failure.
84
92
  */
85
93
  export { FabricatorError } from "./Error";
86
94
  /**
@@ -97,6 +105,26 @@ export { registry } from "./Schema/Registry";
97
105
  */
98
106
  export { effectiveDiscrete, toBound } from "./Bound";
99
107
  export type { Bound, InputBound } from "./Bound";
108
+ /**
109
+ * The `length` shapes `T.string`/`T.array`'s `.whereby(...)` accept and store,
110
+ * and the `distribution` every range-bearing `whereby` takes. Exported so a
111
+ * `whereby` argument built programmatically, or read back off a schema's `meta`
112
+ * in an `.adapt` producer, can be typed — the same rationale as `Bound`.
113
+ * `Distribution` is type-only: a distribution is written as its plain tagged
114
+ * object (`{ kind: "skew", exponent: 4 }`), and the type's namespace members
115
+ * (`Distribution.Normal`, …) name each variant.
116
+ */
117
+ export type { Distribution, Range } from "./Distribution";
118
+ export type { InputLength, Length } from "./Bound";
119
+ /**
120
+ * `T.string`'s `composition` vocabulary: the class-weighting and `[weight,
121
+ * source]` forms, and the sources the second form draws from. `classes` holds
122
+ * each built-in class as its code point ranges, so the pair form can mix a
123
+ * class with an arbitrary range (`[[3, classes.lowercase], [1, unicode.bmp]]`);
124
+ * `unicode` holds codespace presets and `range(from, to)`.
125
+ */
126
+ export type { CharacterClass, CharacterSource, CodepointRange, Composition, } from "./Primitive/string/Types";
127
+ export { classes, unicode } from "./Primitive/string/Constants";
100
128
  /**
101
129
  * Public because it is the type of `ProduceContext`'s `random` member — the
102
130
  * seeded stream every kind's `.as(produce)` and `T.opaque`'s producer are
@@ -138,17 +166,16 @@ export type { Adapting } from "./Adapter/Types";
138
166
  */
139
167
  export type { Salt } from "./Random/Types";
140
168
  /**
141
- * Reads the value type a built Fabricator produces straight off its `fabricate`
142
- * signature — `Fabrication<typeof Product>` instead of `ReturnType<typeof
143
- * Product.fabricate>`.
169
+ * The shape that `initialize({ algorithm })` accepts — a seed in, a `[0, 1)`
170
+ * generator out.
144
171
  */
145
- export type { Fabrication } from "./Fabricator/Types";
172
+ export type { Algorithm } from "./Random/Types";
146
173
  /**
147
- * Reads the value type a Schema (not yet built) will eventually produce, via
148
- * its phantom `[Produces]` marker. Mostly useful for a helper that accepts a
149
- * Schema before it's built into a Fabricator.
174
+ * Reads the value type a Schema produces, via its phantom `[Produces]` marker —
175
+ * before it is built, which is what a helper accepting a Schema needs — or the
176
+ * value type a built Fabricator produces, off its `fabricate` signature.
150
177
  */
151
- export type { ValueOf } from "./Schema/Types";
178
+ export type { Fabricated } from "./Schema/Types";
152
179
  /**
153
180
  * Check that a Schema or built Fabricator produces a value assignable to a
154
181
  * supplied type — `.satisfies<T>()` on every kind's Schema is the main form;
@@ -35,15 +35,22 @@ export type { Fabrication, NaiveFabricator } from "./Fabricator/Types";
35
35
  * a per-kind stand-in — a second copy of this mapping, susceptible to drift.
36
36
  */
37
37
  export type { AsFabricator } from "./Fabricator/Types";
38
- export { Children, Kind, Meta, Produces, type Buildable } from "./Types";
39
- export { isPlainObject } from "./Utility/Core";
38
+ /**
39
+ * `Produced` travels with `Produces`: `[Produces]` holds a Schema's value type
40
+ * boxed, so anything outside this package that matches or infers through the
41
+ * brand has to name the box — `{ readonly [Produces]?: Produced<$T> }`. See
42
+ * `Types.ts` for why an unboxed `{ readonly [Produces]?: $T }` cannot be read
43
+ * exactly.
44
+ */
45
+ export { Children, Kind, Meta, Produces, type Buildable, type Produced, } from "./Types";
46
+ export { isArray, isPlainObject } from "./Utility/Core";
40
47
  export type * as Primitive from "./Primitive/namespace";
41
48
  /**
42
49
  * `Schema/Types.ts`'s own value-type resolution, needed by tests asserting
43
- * `ValueOf<...>` directly rather than through a built Fabricator's
50
+ * `Fabricated<...>` directly rather than through a built Fabricator's
44
51
  * `Fabrication<...>`.
45
52
  */
46
- export type { ValueOf } from "./Schema/Types";
53
+ export type { Fabricated } from "./Schema/Types";
47
54
  /**
48
55
  * `Constructor` is `Instance.Fabricator`'s own type — public in effect (every
49
56
  * `initialize()` caller receives one), just never named directly by the `.`
@@ -71,6 +78,19 @@ export type { Algorithm, ConstructionPins, ConstructionTrace, ConstructorOptions
71
78
  * registry guards or `.fabricate()` in between.
72
79
  */
73
80
  export { weighted } from "./Distribution";
81
+ /**
82
+ * The normal CDF the `normal` distribution's truncation is computed with. The
83
+ * docs site's distribution explorer draws each variant's exact density, and a
84
+ * truncated normal's density divides by the mass this function measures —
85
+ * importing it rather than restating the approximation keeps the plotted curve
86
+ * normalized exactly as `sampler` truncates.
87
+ *
88
+ * `normalInv` is its inverse, the quantile `sampler` maps a truncated unit draw
89
+ * through. `@ghostry/fabricator-census` imports both to score a fitted `normal`
90
+ * against the exact curve fabrication will draw from, rather than against a
91
+ * second approximation that could disagree with it in the tails.
92
+ */
93
+ export { normalCdf, normalInv } from "./Distribution";
74
94
  /**
75
95
  * The synchronous ambient carrier. `#stack` (`package.json`) selects it only
76
96
  * where there is no `node:async_hooks` — in practice a browser bundle — so on
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@ghostry/fabricator",
3
- "version": "0.0.10",
3
+ "version": "0.0.12",
4
4
  "license": "MIT",
5
5
  "description": "Fabricate typed data from composable schemas.",
6
6
  "keywords": [
@@ -65,7 +65,7 @@
65
65
  "provenance": true
66
66
  },
67
67
  "devDependencies": {
68
- "@ghostry/harness": "^0.0.4"
68
+ "@ghostry/harness": "^0.0.5"
69
69
  },
70
70
  "scripts": {
71
71
  "build:reset": "rm -rf ./dist",
@@ -76,10 +76,10 @@
76
76
  "build:clean": "find ./dist -type f -name '*.tsbuildinfo' -delete",
77
77
  "build": "bun run build:reset && bun run build:compile && bun run build:types && bun run build:verify && bun run build:clean",
78
78
  "build:rsdoctor": "bun run build:reset && bun run build:compile:rsdoctor && bun run build:types && bun run build:verify && bun run build:clean",
79
- "check": "tsc --noEmit",
80
- "check:ts5": "bun --bun ../../node_modules/typescript-5/lib/tsc.js --noEmit",
79
+ "check": "tsc --noEmit && tsc --noEmit -p ./tsconfig.inexact.json",
80
+ "check:ts5": "bun --bun ../../node_modules/typescript-5/lib/tsc.js --noEmit && bun --bun ../../node_modules/typescript-5/lib/tsc.js --noEmit -p ./tsconfig.inexact.json",
81
81
  "check:jsr": "DENO_BIN_PATH=$PWD/../../node_modules/.bin/deno bunx --no-install jsr publish --dry-run --allow-dirty",
82
- "format": "bunx --no-install oxfmt .",
82
+ "format": "bun fmt",
83
83
  "test": "bun run check && bun run check:ts5 && bun run check:jsr && bun test"
84
84
  },
85
85
  "files": [