@ghostry/fabricator 0.0.1 → 0.0.2

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 (124) hide show
  1. package/README.md +1 -7
  2. package/dist/esm/Error/index.js +8 -0
  3. package/dist/esm/Instance/Core.js +8 -17
  4. package/dist/esm/Instance/Stack/Async.js +10 -0
  5. package/dist/esm/Instance/Stack/Sync.js +16 -0
  6. package/dist/esm/Primitive/bigint/Registry.js +12 -12
  7. package/dist/esm/Primitive/boolean/Registry.js +2 -1
  8. package/dist/esm/Primitive/date/Registry.js +15 -14
  9. package/dist/esm/Primitive/null/Registry.js +2 -1
  10. package/dist/esm/Primitive/number/Registry.js +18 -17
  11. package/dist/esm/Primitive/symbol/Registry.js +2 -1
  12. package/dist/esm/Primitive/undefined/Registry.js +2 -1
  13. package/dist/esm/Random/CallSite.js +27 -13
  14. package/dist/esm/Utility/Core.js +6 -1
  15. package/dist/esm/index.js +4 -2
  16. package/dist/esm/internal.js +2 -1
  17. package/dist/types/Adapter/Core.d.ts +29 -32
  18. package/dist/types/Adapter/Types.d.ts +78 -88
  19. package/dist/types/Bound.d.ts +15 -15
  20. package/dist/types/Distribution/index.d.ts +54 -61
  21. package/dist/types/Enumeration/Enumerate.d.ts +21 -23
  22. package/dist/types/Enumeration/Plan.d.ts +22 -26
  23. package/dist/types/Enumeration/Types.d.ts +38 -43
  24. package/dist/types/Error/index.d.ts +94 -76
  25. package/dist/types/Fabricator/Constructor.d.ts +23 -25
  26. package/dist/types/Fabricator/Types.d.ts +73 -81
  27. package/dist/types/Instance/Core.d.ts +54 -73
  28. package/dist/types/Instance/Stack/Async.d.ts +14 -0
  29. package/dist/types/Instance/Stack/Sync.d.ts +14 -0
  30. package/dist/types/Instance/Types.d.ts +91 -89
  31. package/dist/types/Primitive/always/Schema.d.ts +8 -8
  32. package/dist/types/Primitive/always/Types.d.ts +7 -7
  33. package/dist/types/Primitive/array/Registry.d.ts +10 -8
  34. package/dist/types/Primitive/array/Schema.d.ts +4 -5
  35. package/dist/types/Primitive/array/Types.d.ts +6 -6
  36. package/dist/types/Primitive/bigint/Registry.d.ts +6 -6
  37. package/dist/types/Primitive/bigint/Schema.d.ts +8 -8
  38. package/dist/types/Primitive/bigint/Types.d.ts +5 -5
  39. package/dist/types/Primitive/boolean/Outcomes.d.ts +8 -8
  40. package/dist/types/Primitive/boolean/Registry.d.ts +2 -12
  41. package/dist/types/Primitive/boolean/Schema.d.ts +8 -8
  42. package/dist/types/Primitive/boolean/Types.d.ts +3 -3
  43. package/dist/types/Primitive/choice/Fabricator.d.ts +6 -7
  44. package/dist/types/Primitive/choice/Registry.d.ts +13 -13
  45. package/dist/types/Primitive/choice/Schema.d.ts +6 -6
  46. package/dist/types/Primitive/choice/Types.d.ts +11 -11
  47. package/dist/types/Primitive/date/Registry.d.ts +25 -48
  48. package/dist/types/Primitive/date/Schema.d.ts +9 -10
  49. package/dist/types/Primitive/date/Types.d.ts +4 -4
  50. package/dist/types/Primitive/enum/Registry.d.ts +13 -13
  51. package/dist/types/Primitive/enum/Schema.d.ts +5 -5
  52. package/dist/types/Primitive/enum/Types.d.ts +17 -19
  53. package/dist/types/Primitive/namespace.d.ts +10 -10
  54. package/dist/types/Primitive/null/Registry.d.ts +2 -2
  55. package/dist/types/Primitive/null/Schema.d.ts +2 -2
  56. package/dist/types/Primitive/null/Types.d.ts +3 -3
  57. package/dist/types/Primitive/nullable/Fabricator.d.ts +7 -7
  58. package/dist/types/Primitive/nullable/Schema.d.ts +13 -13
  59. package/dist/types/Primitive/nullable/Types.d.ts +9 -10
  60. package/dist/types/Primitive/nullish/Fabricator.d.ts +12 -13
  61. package/dist/types/Primitive/nullish/Schema.d.ts +8 -8
  62. package/dist/types/Primitive/nullish/Types.d.ts +12 -13
  63. package/dist/types/Primitive/number/Registry.d.ts +20 -38
  64. package/dist/types/Primitive/number/Schema.d.ts +11 -12
  65. package/dist/types/Primitive/number/Types.d.ts +13 -13
  66. package/dist/types/Primitive/number/defaults.d.ts +3 -3
  67. package/dist/types/Primitive/object/Fabricator.d.ts +15 -15
  68. package/dist/types/Primitive/object/Registry.d.ts +8 -8
  69. package/dist/types/Primitive/object/Schema.d.ts +10 -10
  70. package/dist/types/Primitive/object/Types.d.ts +20 -22
  71. package/dist/types/Primitive/object/compute/Fabricator.d.ts +4 -5
  72. package/dist/types/Primitive/object/compute/Schema.d.ts +4 -4
  73. package/dist/types/Primitive/object/compute/Types.d.ts +19 -20
  74. package/dist/types/Primitive/object/omittable/Fabricator.d.ts +10 -10
  75. package/dist/types/Primitive/object/omittable/Outcomes.d.ts +2 -2
  76. package/dist/types/Primitive/object/omittable/Schema.d.ts +11 -11
  77. package/dist/types/Primitive/object/omittable/Types.d.ts +14 -15
  78. package/dist/types/Primitive/object/optional/Fabricator.d.ts +16 -18
  79. package/dist/types/Primitive/object/optional/Outcomes.d.ts +2 -2
  80. package/dist/types/Primitive/object/optional/Schema.d.ts +4 -4
  81. package/dist/types/Primitive/object/optional/Types.d.ts +17 -17
  82. package/dist/types/Primitive/opaque/Registry.d.ts +3 -3
  83. package/dist/types/Primitive/opaque/Schema.d.ts +8 -9
  84. package/dist/types/Primitive/record/Registry.d.ts +8 -6
  85. package/dist/types/Primitive/record/Schema.d.ts +9 -11
  86. package/dist/types/Primitive/record/Types.d.ts +25 -25
  87. package/dist/types/Primitive/recursive/Fabricator.d.ts +16 -17
  88. package/dist/types/Primitive/recursive/Registry.d.ts +6 -7
  89. package/dist/types/Primitive/recursive/Schema.d.ts +8 -8
  90. package/dist/types/Primitive/recursive/Terminate.d.ts +13 -14
  91. package/dist/types/Primitive/recursive/Types.d.ts +31 -31
  92. package/dist/types/Primitive/recursive/self/Fabricator.d.ts +11 -12
  93. package/dist/types/Primitive/recursive/self/Schema.d.ts +10 -10
  94. package/dist/types/Primitive/recursive/self/Types.d.ts +7 -8
  95. package/dist/types/Primitive/string/Constants.d.ts +12 -13
  96. package/dist/types/Primitive/string/Fabricator.d.ts +2 -2
  97. package/dist/types/Primitive/string/Registry.d.ts +10 -16
  98. package/dist/types/Primitive/string/Schema.d.ts +5 -5
  99. package/dist/types/Primitive/string/Types.d.ts +17 -17
  100. package/dist/types/Primitive/symbol/Fabricator.d.ts +2 -2
  101. package/dist/types/Primitive/symbol/Registry.d.ts +4 -11
  102. package/dist/types/Primitive/symbol/Schema.d.ts +6 -6
  103. package/dist/types/Primitive/symbol/Types.d.ts +2 -2
  104. package/dist/types/Primitive/tuple/Fabricator.d.ts +7 -8
  105. package/dist/types/Primitive/tuple/Schema.d.ts +5 -5
  106. package/dist/types/Primitive/tuple/Types.d.ts +24 -25
  107. package/dist/types/Primitive/undefinable/Fabricator.d.ts +7 -7
  108. package/dist/types/Primitive/undefinable/Schema.d.ts +13 -13
  109. package/dist/types/Primitive/undefinable/Types.d.ts +10 -10
  110. package/dist/types/Primitive/undefined/Registry.d.ts +2 -2
  111. package/dist/types/Primitive/undefined/Schema.d.ts +4 -4
  112. package/dist/types/Primitive/undefined/Types.d.ts +3 -3
  113. package/dist/types/Random/CallSite.d.ts +63 -44
  114. package/dist/types/Random/Generator/sfc32.d.ts +4 -4
  115. package/dist/types/Random/Types.d.ts +214 -236
  116. package/dist/types/Random/index.d.ts +63 -70
  117. package/dist/types/Schema/Core.d.ts +19 -21
  118. package/dist/types/Schema/Registry.d.ts +3 -3
  119. package/dist/types/Schema/Types.d.ts +41 -48
  120. package/dist/types/Types.d.ts +39 -45
  121. package/dist/types/Utility/Core.d.ts +18 -9
  122. package/dist/types/index.d.ts +110 -108
  123. package/dist/types/internal.d.ts +68 -37
  124. package/package.json +17 -5
@@ -1,5 +1,5 @@
1
1
  import type { Limits } from "./Enumeration/Types";
2
- import type { Instance } from "./Instance/Types";
2
+ import type { Instance, Stack } from "./Instance/Types";
3
3
  import type { Algorithm, Attribution, Seed } from "./Random/Types";
4
4
  import { registry } from "./Schema/Registry";
5
5
  import type { PlainObject } from "./Utility/Types";
@@ -7,180 +7,182 @@ export declare function initialize<const $Registry extends PlainObject = typeof
7
7
  /** The registry of type definers to use — `registry` itself. */
8
8
  types: $Registry;
9
9
  /**
10
- * Optional mixer composed into every stream beside `clock`. Accepts
11
- * a single string, or several — several lets a seed be composed out
12
- * of independent, meaningful parts (a user id, a scenario label)
13
- * without hand-joining them first. If omitted, the seed is empty
14
- * (unless `FABRICATOR_SEED` / `SEED` / `RANDOM_SEED` supplies one):
15
- * wall-clock `clock` is the default entropy, so an unconfigured
16
- * instance varies by run and replays from `context.clock` alone.
17
- * Pass a seed when two instances should share a clock but draw
18
- * different universes, or when `clock: "seeded"` should make the
19
- * seed itself the reproducibility unit.
10
+ * Optional mixer composed into every stream beside `clock`. Accepts a
11
+ * single string, or several — several lets a seed be composed out of
12
+ * independent, meaningful parts (a user id, a scenario label) without
13
+ * hand-joining them first. If omitted, the seed is empty (unless
14
+ * `FABRICATOR_SEED` / `SEED` / `RANDOM_SEED` supplies one): wall-clock
15
+ * `clock` is the default entropy, so an unconfigured instance varies by run
16
+ * and replays from `context.clock` alone. Pass a seed when two instances
17
+ * should share a clock but draw different universes, or when `clock:
18
+ * "seeded"` should make the seed itself the reproducibility unit.
20
19
  */
21
20
  seed?: Seed;
22
21
  /**
23
- * Bring your own PRNG: a factory that, given a seed, returns a
24
- * source of randomness — a `() => number` in `[0, 1)`, a drop-in
25
- * for `Math.random`. Defaults to the built-in `sfc32` generator.
22
+ * Bring your own PRNG: a factory that, given a seed, returns a source of
23
+ * randomness — a `() => number` in `[0, 1)`, a drop-in for `Math.random`.
24
+ * Defaults to the built-in `sfc32` generator.
26
25
  */
27
26
  algorithm?: Algorithm;
28
27
  /**
29
- * How this instance attributes a construction's randomness to the
30
- * file it was written in:
28
+ * How this instance attributes a construction's randomness to the file it
29
+ * was written in:
31
30
  *
32
- * - `{ kind: "rooted", root }` expresses every file relative to
33
- * `root` (an absolute path or a `file://` URL), so the same seed
34
- * reproduces the same data on a checkout at a different absolute
35
- * path.
36
- * - `{ kind: "call site" }`, the default, is `"rooted"` at the
37
- * directory of whichever file called `initialize()`.
38
- * - `{ kind: "none" }` attributes nothing: every construction of a
39
- * given kind anywhere in the instance shares one stream, keyed
40
- * by kind alone.
31
+ * - `{ kind: "rooted", root }` expresses every file relative to `root` (an
32
+ * absolute path or a `file://` URL), so the same seed reproduces the same
33
+ * data on a checkout at a different absolute path.
34
+ * - `{ kind: "call site" }`, the default, is `"rooted"` at the directory of
35
+ * whichever file called `initialize()`.
36
+ * - `{ kind: "none" }` attributes nothing: every construction of a given kind
37
+ * anywhere in the instance shares one stream, keyed by kind alone.
41
38
  *
42
- * See [Reproducibility](https://ghostry-dev.github.io/fabricator/guides/reproducibility)
39
+ * See
40
+ * [Reproducibility](https://docs.ghostry.dev/fabricator/guides/reproducibility)
43
41
  * for the trade-offs between the three.
44
42
  */
45
43
  attribution?: Attribution;
46
44
  /**
47
- * Instance-wide numeric ceilings. `combinatorial` bounds how many
48
- * instances `combinatorial(...)` may enumerate — the check is
49
- * eager, it throws at call time before any instance is produced.
50
- * Defaults to 1024 if omitted. `coverage(...)` carries no entry
51
- * here: its count is the widest single axis, so there is nothing
52
- * for a limit to protect against.
45
+ * Instance-wide numeric ceilings. `combinatorial` bounds how many instances
46
+ * `combinatorial(...)` may enumerate — the check is eager, it throws at
47
+ * call time before any instance is produced. Defaults to 1024 if omitted.
48
+ * `coverage(...)` carries no entry here: its count is the widest single
49
+ * axis, so there is nothing for a limit to protect against.
53
50
  */
54
51
  limits?: Limits;
55
52
  /**
56
53
  * What `T.date.past`/`T.date.future` (and any producer reading
57
- * `ProduceContext.clock`) resolve "now" against — and, because it
58
- * sits in every leaf's trace, the default entropy for the instance.
59
- * Defaults to the wall-clock instant of this `initialize()` call, so
60
- * an unconfigured run has realistic dates and varies by process, and
61
- * replays from `context.clock` (with the same empty or supplied
62
- * `seed`). Pass a fixed `Date` to freeze "now" (and the rest of the
63
- * run, unless `seed` also differs). Pass `"seeded"` to derive "now"
64
- * from the instance seed instead — an instant drawn across the whole
65
- * representable `Date` span, so an implausible date is the expected
66
- * outcome of that policy, not a bug. `"seeded"` is what makes `seed`
67
- * alone the reproducibility unit.
54
+ * `ProduceContext.clock`) resolve "now" against — and, because it sits in
55
+ * every leaf's trace, the default entropy for the instance. Defaults to the
56
+ * wall-clock instant of this `initialize()` call, so an unconfigured run
57
+ * has realistic dates and varies by process, and replays from
58
+ * `context.clock` (with the same empty or supplied `seed`). Pass a fixed
59
+ * `Date` to freeze "now" (and the rest of the run, unless `seed` also
60
+ * differs). Pass `"seeded"` to derive "now" from the instance seed instead
61
+ * — an instant drawn across the whole representable `Date` span, so an
62
+ * implausible date is the expected outcome of that policy, not a bug.
63
+ * `"seeded"` is what makes `seed` alone the reproducibility unit.
68
64
  */
69
65
  clock?: Date | "seeded";
66
+ /**
67
+ * The ambient carrier backing `wrap` for this lineage — override only to
68
+ * force a specific one.
69
+ *
70
+ * Left unset (the norm), the `#stack` package import picks it: every
71
+ * runtime with `node:async_hooks` — Node, Bun, Deno — gets the
72
+ * `AsyncLocalStorage` carrier, whose frames survive `await` and isolate
73
+ * concurrent `wrap`s; anywhere else falls back to a synchronous LIFO, on
74
+ * which `wrap` rejects an async block rather than silently resolving a
75
+ * later build against this instance. Supplying one is how a test drives the
76
+ * carrier it did not get by condition.
77
+ */
78
+ stack?: Stack;
70
79
  }>): Instance<$Registry>;
71
80
  export { Omitted } from "./Types";
72
81
  /**
73
- * Tags a `Seed` — for `new Fabricator(schema, { seed })`, or `fork`'s
74
- * own `Overlay.seed` — as composing onto whatever base is in effect,
75
- * rather than replacing it outright.
82
+ * Tags a `Seed` — for `new Fabricator(schema, { seed })`, or `fork`'s own
83
+ * `Overlay.seed` — as composing onto whatever base is in effect, rather than
84
+ * replacing it outright.
76
85
  */
77
86
  export { layer } from "./Random";
78
87
  /**
79
- * `layer(...)`'s return type, so a caller building one programmatically
80
- * can name it — the same rationale as the existing `Seed`/`Attribution`
81
- * exports.
88
+ * `layer(...)`'s return type, so a caller building one programmatically can
89
+ * name it — the same rationale as the existing `Seed`/`Attribution` exports.
82
90
  */
83
91
  export type { Layered } from "./Random/Types";
84
92
  /**
85
93
  * Every failure this library raises is an instance of this class — see
86
- * `src/Error/index.ts` for the full hierarchy. Only the base is
87
- * public; subclasses are distinguished by `.name`.
94
+ * `src/Error/index.ts` for the full hierarchy. Only the base is public;
95
+ * subclasses are distinguished by `.name`.
88
96
  */
89
97
  export { FabricatorError } from "./Error";
90
98
  /**
91
- * The adapter contract, exported because an adapter is a separate
92
- * package rather than something registered here: `Adapter`/`Recurse`
93
- * are what one declares, `drive` is what its conversion entry point
94
- * calls, and `Adaptation`/`AdaptationsOf` are how it reads what a
95
- * Schema declared — `[Adaptation]` at runtime, `AdaptationsOf` at the
96
- * type level, keyed by its own `key` in both cases.
99
+ * The adapter contract, exported because an adapter is a separate package
100
+ * rather than something registered here: `Adapter`/`Recurse` are what one
101
+ * declares, `drive` is what its conversion entry point calls, and
102
+ * `Adaptation`/`AdaptationsOf` are how it reads what a Schema declared —
103
+ * `[Adaptation]` at runtime, `AdaptationsOf` at the type level, keyed by its
104
+ * own `key` in both cases.
97
105
  *
98
- * This package names no external schema library and depends on none:
99
- * every mapping, and every dependency it needs, belongs to the
100
- * adapter.
106
+ * This package names no external schema library and depends on none: every
107
+ * mapping, and every dependency it needs, belongs to the adapter.
101
108
  *
102
- * `Adapting` is the odd one out, facing whoever *writes* an adaptation
103
- * rather than whoever implements an adapter: it is the parameter type
104
- * of every kind's `.adapt(adapter, produce)` producer, so a caller
105
- * writing that producer as a named function can name it — the same
106
- * reason `Stream` is exported below.
109
+ * `Adapting` is the odd one out, facing whoever _writes_ an adaptation rather
110
+ * than whoever implements an adapter: it is the parameter type of every kind's
111
+ * `.adapt(adapter, produce)` producer, so a caller writing that producer as a
112
+ * named function can name it — the same reason `Stream` is exported below.
107
113
  */
108
114
  export { drive } from "./Adapter/Core";
109
115
  export type { Adaptations, AdaptationsOf, Adapter, Adapting, Recurse, } from "./Adapter/Types";
110
116
  export { Adaptation } from "./Types";
111
117
  /**
112
- * The default registry of type definers, exported so it can be
113
- * extended via `registry.extend(({ T }) => ({ ... }))` before being
114
- * passed to `initialize({ types })`.
118
+ * The default registry of type definers, exported so it can be extended via
119
+ * `registry.extend(({ T }) => ({ ... }))` before being passed to `initialize({
120
+ * types })`.
115
121
  */
116
122
  export { registry } from "./Schema/Registry";
117
123
  /**
118
- * Canonical `{ value, exclusive }` endpoint stored on `whereby` min/max,
119
- * plus the call-site union that still accepts a scalar (inclusive). Exported
120
- * so a named `.whereby(...)` argument or an `.adapt` producer reading `meta`
121
- * can type it — the same rationale as `Stream`.
124
+ * Canonical `{ value, exclusive }` endpoint stored on `whereby` min/max, plus
125
+ * the call-site union that still accepts a scalar (inclusive). Exported so a
126
+ * named `.whereby(...)` argument or an `.adapt` producer reading `meta` can
127
+ * type it — the same rationale as `Stream`.
122
128
  */
129
+ export { effectiveDiscrete, toBound } from "./Bound";
123
130
  export type { Bound, InputBound } from "./Bound";
124
- export { toBound, effectiveDiscrete } from "./Bound";
125
131
  /**
126
- * Public because it is the type of `ProduceContext`'s `random` member
127
- * — the seeded stream every kind's `.as(produce)` and `T.opaque`'s
128
- * producer are handed — so a caller writing either as a named function
129
- * can name it.
132
+ * Public because it is the type of `ProduceContext`'s `random` member — the
133
+ * seeded stream every kind's `.as(produce)` and `T.opaque`'s producer are
134
+ * handed — so a caller writing either as a named function can name it.
130
135
  */
131
136
  export type { Stream } from "./Random/Types";
132
137
  /**
133
- * What every kind's `.as(produce)` producer is called with — a single
134
- * curated object rather than a positional argument list, so a caller
135
- * writing the producer as a named function can name its parameter.
136
- * `T.opaque`'s producer takes the same shape.
138
+ * What every kind's `.as(produce)` producer is called with — a single curated
139
+ * object rather than a positional argument list, so a caller writing the
140
+ * producer as a named function can name its parameter. `T.opaque`'s producer
141
+ * takes the same shape.
137
142
  */
138
143
  export type { ProduceContext } from "./Random/Types";
139
144
  /**
140
- * The shape `initialize({ seed })` and `new Fabricator(schema, { seed })`
141
- * both accept — a single string, or several — so a caller building one
142
- * programmatically (rather than as an inline literal) can name the
143
- * type.
145
+ * The shape `initialize({ seed })` and `new Fabricator(schema, { seed })` both
146
+ * accept — a single string, or several — so a caller building one
147
+ * programmatically (rather than as an inline literal) can name the type.
144
148
  */
145
149
  export type { Seed } from "./Random/Types";
146
150
  /**
147
- * The shape `initialize({ attribution })` accepts, so a caller building
148
- * one programmatically — a rooted policy derived from an env var, say
149
- * — can name the type.
151
+ * The shape `initialize({ attribution })` accepts, so a caller building one
152
+ * programmatically — a rooted policy derived from an env var, say — can name
153
+ * the type.
150
154
  */
151
155
  export type { Attribution } from "./Random/Types";
152
156
  /**
153
- * Reads the value type a built Fabricator produces straight off its
154
- * `fabricate` signature — `Fabrication<typeof Product>` instead of
155
- * `ReturnType<typeof Product.fabricate>`.
157
+ * Reads the value type a built Fabricator produces straight off its `fabricate`
158
+ * signature — `Fabrication<typeof Product>` instead of `ReturnType<typeof
159
+ * Product.fabricate>`.
156
160
  */
157
161
  export type { Fabrication } from "./Fabricator/Types";
158
162
  /**
159
- * Reads the value type a Schema (not yet built) will eventually
160
- * produce, via its phantom `[Produces]` marker. Mostly useful for a
161
- * helper that accepts a Schema before it's built into a Fabricator.
163
+ * Reads the value type a Schema (not yet built) will eventually produce, via
164
+ * its phantom `[Produces]` marker. Mostly useful for a helper that accepts a
165
+ * Schema before it's built into a Fabricator.
162
166
  */
163
167
  export type { ValueOf } from "./Schema/Types";
164
168
  /**
165
- * `fabricator.trace`'s type — otherwise unnameable by a caller
166
- * wanting to hold onto one, the same reason `Stream` is exported
167
- * above.
169
+ * `fabricator.trace`'s type — otherwise unnameable by a caller wanting to hold
170
+ * onto one, the same reason `Stream` is exported above.
168
171
  */
169
172
  export type { Trace } from "./Random/Types";
170
173
  /**
171
- * How `file` and `ordinal` on a {@link Trace} were resolved — recorded
172
- * so a captured trace is self-describing, including `"counted"`
173
- * (replayed for a node taken from inside a `T.recursive` expansion;
174
- * not a variant you choose when building).
174
+ * How `file` and `ordinal` on a {@link Trace} were resolved — recorded so a
175
+ * captured trace is self-describing, including `"counted"` (replayed for a node
176
+ * taken from inside a `T.recursive` expansion; not a variant you choose when
177
+ * building).
175
178
  */
176
179
  export type { RootKind } from "./Random/Types";
177
180
  /**
178
181
  * `fork`/`wrap`'s own config shapes, so a caller building an overlay
179
- * programmatically (rather than as an inline literal) can name them —
180
- * the same rationale as the existing `Seed`/`Attribution` exports.
181
- * `Config` is what `initialize`'s own parameter is a `Partial` of;
182
- * `Overlay` is what `fork`/`wrap` accept; `Context` is
183
- * `instance.context`'s own type, so a caller writing a helper that
184
- * reads it can name the parameter.
182
+ * programmatically (rather than as an inline literal) can name them — the same
183
+ * rationale as the existing `Seed`/`Attribution` exports. `Config` is what
184
+ * `initialize`'s own parameter is a `Partial` of; `Overlay` is what
185
+ * `fork`/`wrap` accept; `Context` is `instance.context`'s own type, so a caller
186
+ * writing a helper that reads it can name the parameter.
185
187
  */
186
- export type { Config, Context, Overlay } from "./Instance/Types";
188
+ export type { Config, Context, Overlay, Stack } from "./Instance/Types";
@@ -1,64 +1,95 @@
1
1
  /**
2
2
  * The "adapter-authoring SDK" entry point — published as the
3
- * `@ghostry/fabricator/internal` package export, deliberately *not*
4
- * re-exported from `./index.ts`. An external adapter package (e.g.
5
- * `@ghostry/fabricator-adapter-typebox-v0`) needs to walk a Schema/
6
- * Fabricator structurally and dispatch on each primitive kind's `Core`
7
- * shape — see "Match `Core`, never `Schema`, in a dispatch" — which
8
- * the end-user-facing `.` export has no reason to carry.
3
+ * `@ghostry/fabricator/internal` package export, deliberately _not_ re-exported
4
+ * from `./index.ts`. An external adapter package (e.g.
5
+ * `@ghostry/fabricator-adapter-typebox-v0`) needs to walk a Schema/ Fabricator
6
+ * structurally and dispatch on each primitive kind's `Core` shape — see "Match
7
+ * `Core`, never `Schema`, in a dispatch" — which the end-user-facing `.` export
8
+ * has no reason to carry.
9
9
  *
10
- * Also this package's own white-box test suite's route to source: a
11
- * test file imports through `@ghostry/fabricator`/
12
- * `@ghostry/fabricator/internal` rather than a relative `../src/...`
13
- * path specifically so it resolves through the built `dist/` (see the
14
- * "Random", "Schema", and "Enumeration" groups below) the same
15
- * reason an adapter needs this entry point, applied to this package's
10
+ * Also this package's own white-box test suite's route to source: a test file
11
+ * imports through `@ghostry/fabricator`/ `@ghostry/fabricator/internal` rather
12
+ * than a relative `../src/...` path specifically so it resolves through the
13
+ * built `dist/` (see the "Random", "Schema", and "Enumeration" groups below)
14
+ * the same reason an adapter needs this entry point, applied to this package's
16
15
  * own tests instead of an external one.
17
16
  *
18
- * Everything here is curated, not incidental. When wiring a new leaf
19
- * kind into the rest of the system, add its module to
20
- * `Primitive/namespace.ts` (re-exported here as `Primitive`), or no
21
- * adapter can reach that kind's `Core` type.
17
+ * Everything here is curated, not incidental. When wiring a new leaf kind into
18
+ * the rest of the system, add its module to `Primitive/namespace.ts`
19
+ * (re-exported here as `Primitive`), or no adapter can reach that kind's `Core`
20
+ * type.
22
21
  */
23
22
  export type { Fabrication, NaiveFabricator } from "./Fabricator/Types";
23
+ /**
24
+ * Schema -> the Fabricator type `construct()` produces for it, dispatching per
25
+ * kind. `Constructor` already names this as its own construct signature's
26
+ * return, but only _inside_ a generic call: a wrapping library that hands a
27
+ * built Fabricator to its own callers has to name the type without making that
28
+ * call, and cannot infer it back out of `Constructor` because the signature is
29
+ * generic (a `Constructor extends { new (schema: $S, ...): infer $R }` match
30
+ * instantiates at the constraint, not at `$S`).
31
+ *
32
+ * `@ghostry/extern-extension-fabricator-v0` is the case in point: it hands the
33
+ * built Fabricator to a user callback as the shaping handle, so the handle's
34
+ * type is exactly this. Without it, an integration is pushed into hand-writing
35
+ * a per-kind stand-in — a second copy of this mapping, susceptible to drift.
36
+ */
37
+ export type { AsFabricator } from "./Fabricator/Types";
24
38
  export { Children, Kind, Meta, Produces, type Buildable } from "./Types";
25
39
  export { isPlainObject } from "./Utility/Core";
26
40
  export type * as Primitive from "./Primitive/namespace";
27
41
  /**
28
- * `Schema/Types.ts`'s own value-type resolution, needed by tests
29
- * asserting `ValueOf<...>` directly rather than through a built
30
- * Fabricator's `Fabrication<...>`.
42
+ * `Schema/Types.ts`'s own value-type resolution, needed by tests asserting
43
+ * `ValueOf<...>` directly rather than through a built Fabricator's
44
+ * `Fabrication<...>`.
31
45
  */
32
46
  export type { ValueOf } from "./Schema/Types";
33
47
  /**
34
- * `Constructor` is `Instance.Fabricator`'s own type — public in effect
35
- * (every `initialize()` caller receives one), just never named
36
- * directly by the `.` export, which only ever describes it inline.
48
+ * `Constructor` is `Instance.Fabricator`'s own type — public in effect (every
49
+ * `initialize()` caller receives one), just never named directly by the `.`
50
+ * export, which only ever describes it inline.
37
51
  */
38
52
  export type { Constructor } from "./Fabricator/Constructor";
39
53
  /**
40
- * The enumeration planner's own shapes — `combinatorial`/`coverage`
41
- * (the `.` export's public entry points) are built on `plan`/`resolve`,
42
- * which a test asserting `axisFor`'s per-kind width/strategy decisions
43
- * needs directly.
54
+ * The enumeration planner's own shapes — `combinatorial`/`coverage` (the `.`
55
+ * export's public entry points) are built on `plan`/`resolve`, which a test
56
+ * asserting `axisFor`'s per-kind width/strategy decisions needs directly.
44
57
  */
45
58
  export { plan, resolve } from "./Enumeration/Plan";
46
59
  export type { Axis, Enumerable, Pin, Resolvable } from "./Enumeration/Types";
47
60
  /**
48
- * The randomness layer underneath
49
- * `initialize({ seed, algorithm, attribution })` and a Fabricator's
50
- * `.trace` needed by tests exercising stream attribution and
51
- * construction directly, beneath the level `initialize()` itself
52
- * exposes.
61
+ * The randomness layer underneath `initialize({ seed, algorithm, attribution
62
+ * })` and a Fabricator's `.trace` — needed by tests exercising stream
63
+ * attribution and construction directly, beneath the level `initialize()`
64
+ * itself exposes.
53
65
  */
54
66
  export { defaultAlgorithm, encode, randomSeed, toRandomSource, toStream, toStreamFromTrace, } from "./Random";
55
67
  export type { Algorithm, ConstructionTrace, ConstructorOptions, ResolvedAttribution, RootKind, RootPins, Seed, Trace, } from "./Random/Types";
56
68
  /**
57
- * `Random/CallSite.ts`'s pure string helpers. Exported for this
58
- * package's own tests: the percent-encoded, `file://`-prefixed, and
59
- * backslashed spellings they exist to fold together cannot be produced
60
- * by running the suite from an ordinary POSIX checkout, so they have
61
- * to be driven with synthetic frame strings instead of real stack
62
- * frames.
69
+ * `Random/CallSite.ts`'s pure string helpers. Exported for this package's own
70
+ * tests: the percent-encoded, `file://`-prefixed, and backslashed spellings
71
+ * they exist to fold together cannot be produced by running the suite from an
72
+ * ordinary POSIX checkout, so they have to be driven with synthetic frame
73
+ * strings instead of real stack frames.
63
74
  */
64
75
  export { directoryOf, normalizeLocation, relativize } from "./Random/CallSite";
76
+ /**
77
+ * Resolves the file that triggered the current call. Exported here for a
78
+ * library that wraps fabricator (e.g. `@ghostry/extern`'s testing scope) and
79
+ * wants a construction attributed to _its own_ caller rather than to itself,
80
+ * which is what the `skip` option is for. See `Random/CallSite.ts`'s doc
81
+ * comment for the full contract, including why `skip` is a list of roots that
82
+ * composes onto this library's own root rather than replacing it.
83
+ */
84
+ export { resolveCallerFile } from "./Random/CallSite";
85
+ /**
86
+ * The synchronous ambient carrier. `#stack` (`package.json`) selects it only
87
+ * where there is no `node:async_hooks` — in practice a browser bundle — so on
88
+ * Bun, Node, and Deno alike the condition always resolves to the
89
+ * `AsyncLocalStorage` one instead. Exported for this package's own tests:
90
+ * without it, neither the synchronous carrier's behavior nor `wrap`'s rejection
91
+ * of an async block under it is reachable from the suite. It is also a
92
+ * serviceable argument for `initialize({ stack })` for anyone who wants the old
93
+ * semantics back deliberately.
94
+ */
95
+ export { toStack as toSynchronousStack } from "./Instance/Stack/Sync";
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@ghostry/fabricator",
3
- "version": "0.0.1",
3
+ "version": "0.0.2",
4
4
  "license": "MIT",
5
5
  "description": "Fabricate typed data from composable schemas.",
6
6
  "keywords": [
@@ -19,6 +19,15 @@
19
19
  "type": "module",
20
20
  "types": "./dist/types/index.d.ts",
21
21
  "module": "./dist/esm/index.js",
22
+ "imports": {
23
+ "#stack": {
24
+ "types": "./src/Instance/Stack/Async.ts",
25
+ "deno": "./src/Instance/Stack/Async.ts",
26
+ "node": "./dist/esm/Instance/Stack/Async.js",
27
+ "bun": "./dist/esm/Instance/Stack/Async.js",
28
+ "default": "./dist/esm/Instance/Stack/Sync.js"
29
+ }
30
+ },
22
31
  "exports": {
23
32
  ".": {
24
33
  "types": "./dist/types/index.d.ts",
@@ -39,13 +48,16 @@
39
48
  "build:reset": "rm -rf ./dist",
40
49
  "build:compile": "bunx --no-install --bun rslib build --config ./rslib.config.ts",
41
50
  "build:compile:rsdoctor": "RSDOCTOR=true bunx --no-install --bun rslib build --config ./rslib.config.ts",
51
+ "build:types": "bun --bun ../../node_modules/typescript-5/lib/tsc.js -p ./tsconfig.build.json --noEmit false --declaration --emitDeclarationOnly --declarationDir ./dist/types",
52
+ "build:verify": "tsc --noEmit -p ./tsconfig.verify.json",
42
53
  "build:clean": "find ./dist -type f -name '*.tsbuildinfo' -delete",
43
- "build": "bun run build:reset && bun run build:compile && bun run build:clean",
44
- "build:rsdoctor": "bun run build:reset && bun run build:compile:rsdoctor && bun run build:clean",
54
+ "build": "bun run build:reset && bun run build:compile && bun run build:types && bun run build:verify && bun run build:clean",
55
+ "build:rsdoctor": "bun run build:reset && bun run build:compile:rsdoctor && bun run build:types && bun run build:verify && bun run build:clean",
45
56
  "check": "tsc --noEmit",
46
57
  "check:ts5": "bun --bun ../../node_modules/typescript-5/lib/tsc.js --noEmit",
47
- "prettier": "bunx --no-install --bun prettier .",
48
- "test": "bun run check && bun run check:ts5 && bun test"
58
+ "check:jsr": "DENO_BIN_PATH=$PWD/../../node_modules/.bin/deno bunx --no-install jsr publish --dry-run --allow-dirty",
59
+ "format": "bunx --no-install oxfmt .",
60
+ "test": "bun run check && bun run check:ts5 && bun run check:jsr && bun test"
49
61
  },
50
62
  "files": [
51
63
  "dist"