@ghostry/fabricator 0.0.11 → 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 (49) hide show
  1. package/dist/esm/Enumeration/Enumerate.js +2 -4
  2. package/dist/esm/Error/index.js +34 -6
  3. package/dist/esm/Fabricator/Constructor.js +40 -33
  4. package/dist/esm/Fabricator/Fabricate.js +28 -0
  5. package/dist/esm/Instance/Core.js +14 -2
  6. package/dist/esm/Instance/Stack/Visible.js +6 -1
  7. package/dist/esm/Primitive/date/Defaults.js +12 -0
  8. package/dist/esm/Primitive/date/Fabricator.js +5 -10
  9. package/dist/esm/Primitive/date/Registry.js +8 -4
  10. package/dist/esm/Primitive/index.js +2 -0
  11. package/dist/esm/Primitive/number/Fabricator.js +1 -1
  12. package/dist/esm/Primitive/number/Registry.js +1 -1
  13. package/dist/esm/Primitive/object/Fabricator.js +33 -11
  14. package/dist/esm/Primitive/object/Registry.js +90 -10
  15. package/dist/esm/Primitive/object/compute/Fabricator.js +10 -3
  16. package/dist/esm/Primitive/object/compute/Registry.js +20 -3
  17. package/dist/esm/Primitive/object/omit/Registry.js +5 -0
  18. package/dist/esm/Primitive/object/omit/index.js +2 -0
  19. package/dist/esm/Primitive/object/pick/Registry.js +5 -0
  20. package/dist/esm/Primitive/object/pick/index.js +2 -0
  21. package/dist/esm/Primitive/recursive/Fabricator.js +1 -0
  22. package/dist/esm/Primitive/recursive/Terminate.js +21 -9
  23. package/dist/types/Error/index.d.ts +71 -6
  24. package/dist/types/Fabricator/Fabricate.d.ts +61 -0
  25. package/dist/types/Fabricator/Types.d.ts +13 -3
  26. package/dist/types/Harnessing/Core.d.ts +7 -7
  27. package/dist/types/Instance/Core.d.ts +15 -8
  28. package/dist/types/Instance/Stack/Visible.d.ts +10 -0
  29. package/dist/types/Instance/Types.d.ts +30 -15
  30. package/dist/types/Primitive/date/Defaults.d.ts +11 -0
  31. package/dist/types/Primitive/date/Registry.d.ts +6 -8
  32. package/dist/types/Primitive/date/Types.d.ts +10 -0
  33. package/dist/types/Primitive/index.d.ts +2 -0
  34. package/dist/types/Primitive/object/Fabricator.d.ts +13 -5
  35. package/dist/types/Primitive/object/Registry.d.ts +17 -1
  36. package/dist/types/Primitive/object/Types.d.ts +19 -0
  37. package/dist/types/Primitive/object/compute/Fabricator.d.ts +9 -8
  38. package/dist/types/Primitive/object/compute/Registry.d.ts +7 -1
  39. package/dist/types/Primitive/object/compute/Schema.d.ts +20 -0
  40. package/dist/types/Primitive/object/compute/Types.d.ts +10 -0
  41. package/dist/types/Primitive/object/omit/Registry.d.ts +7 -0
  42. package/dist/types/Primitive/object/omit/index.d.ts +2 -0
  43. package/dist/types/Primitive/object/pick/Registry.d.ts +8 -0
  44. package/dist/types/Primitive/object/pick/index.d.ts +2 -0
  45. package/dist/types/Primitive/recursive/Fabricator.d.ts +9 -7
  46. package/dist/types/index.d.ts +23 -10
  47. package/package.json +3 -3
  48. /package/dist/esm/Primitive/number/{defaults.js → Defaults.js} +0 -0
  49. /package/dist/types/Primitive/number/{defaults.d.ts → Defaults.d.ts} +0 -0
@@ -67,12 +67,31 @@ export type Override<$Definition extends Definition> = Pretty<{
67
67
  * `extend`/`refine`/`override` and `ToTypeBox`'s structural derivation keep
68
68
  * working, and a prior definition survives `as` for future validation of
69
69
  * `produce`.
70
+ *
71
+ * `hidden` holds fields that are fabricated but never emitted: the dependencies
72
+ * of a kept compute field that `T.pick`/`T.omit` (`Registry.ts`) dropped from
73
+ * `definition`. Absent when there are none. It sits outside `definition` so
74
+ * that everything reading `definition` — the `Fabricated`/`Override` types,
75
+ * `.override()`'s key check, `[Children]` (and so enumeration), and every
76
+ * adapter — never sees a hidden field. Only `Constructor.ts`'s `make`,
77
+ * `Fabricator.ts`'s `fabricate`, and `recursive/Terminate.ts` read it.
70
78
  */
71
79
  export type Meta<$Definition extends Definition = Definition> = {
72
80
  definition: $Definition;
73
81
  refinements: Refinements;
74
82
  produce?: Produce<Fabricated<$Definition>>;
83
+ hidden?: Definition;
84
+ };
85
+ /**
86
+ * What `T.pick`/`T.omit` accept: an `object` Schema or a built `object`
87
+ * Fabricator — anything already carrying this kind's `[Meta]`, the same input
88
+ * `Registry.ts`'s `rehydrate` takes.
89
+ */
90
+ export type Subsettable = {
91
+ readonly [Kind]: "object";
92
+ readonly [Meta]: Meta<any>;
75
93
  };
94
+ export type DefinitionOf<$Source extends Subsettable> = $Source[typeof Meta]["definition"];
76
95
  export interface Core<$Definition extends Definition = Definition, $Adaptations extends Adaptations = {}> {
77
96
  [Kind]: "object";
78
97
  [Meta]: Meta<$Definition>;
@@ -2,17 +2,13 @@ import type { Adaptations } from "../../../Adapter/Types";
2
2
  import type { Fabricator as BaseFabricator, FabricatorContext } from "../../../Fabricator/Types";
3
3
  import type { Trace } from "../../../Random/Types";
4
4
  import { Kind, Meta, type Adaptation } from "../../../Types";
5
+ import { type PlainObject } from "../../../Utility/Types";
5
6
  import type { Schema } from "./Schema";
6
- import type { Resolved, Source } from "./Types";
7
+ import type { Resolved, Source, Meta as ThisMeta } from "./Types";
7
8
  export type Fabrication<$Fabricator extends Fabricator<any, Source>> = $Fabricator extends Fabricator<any, infer $Source> ? Resolved<$Source> : never;
8
9
  export type Fabricator<$Fabricated, $Source extends Source, $Adaptations extends Adaptations = {}> = {
9
10
  [Kind]: "object.compute";
10
- [Meta]: {
11
- source: $Source;
12
- resolve: (params: {
13
- fabricated: $Fabricated;
14
- }) => Resolved<$Source>;
15
- };
11
+ [Meta]: ThisMeta<$Fabricated, $Source>;
16
12
  readonly trace: Trace;
17
13
  readonly [Adaptation]?: $Adaptations;
18
14
  fabricate: (params?: {
@@ -26,5 +22,10 @@ export declare function isObjectComputeFabricator(candidate: BaseFabricator<unkn
26
22
  * comes entirely from `resolve`, given the rest of the object. The node still
27
23
  * records `trace` so it can be rebuilt from a parent field's captured trace;
28
24
  * `.fabricate()` without the parent object throws `DetachedComputeError`.
25
+ *
26
+ * The parent hands over everything it has fabricated so far; a `narrowed` field
27
+ * (`.from([...])`) passes its resolver only its `dependencies`, and only those
28
+ * present, so an omitted dependency stays absent rather than becoming
29
+ * `undefined`. Narrowing here keeps `object/Fabricator.ts` unaware of it.
29
30
  */
30
- export declare function Fabricator<$Fabricated, $Source extends Source>(context: FabricatorContext<Schema<$Fabricated, $Source>>): Fabricator<$Fabricated, $Source>;
31
+ export declare function Fabricator<$Fabricated extends PlainObject, $Source extends Source>(context: FabricatorContext<Schema<$Fabricated, $Source>>): Fabricator<$Fabricated, $Source>;
@@ -1,4 +1,10 @@
1
1
  import type { Definition } from "../Types";
2
2
  import { type Computer } from "./Schema";
3
- declare function make<$Definition extends Definition>(): Computer<$Definition>;
3
+ /**
4
+ * `base` is the keys of the `.refine()` stage's base definition — what a plain
5
+ * `.as` resolver depends on, and what `.from([...])` may name. Checked at
6
+ * runtime as well as by type, since a cast or a built Fabricator's widened type
7
+ * can reach `.from` with a key the base never had.
8
+ */
9
+ declare function make<$Definition extends Definition>(base: ReadonlyArray<string>): Computer<$Definition>;
4
10
  export default make;
@@ -2,12 +2,32 @@ 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
4
  import { type SatisfiesThis } from "../../../Schema/Satisfies";
5
+ import type { Pretty } from "../../../Utility/Types";
5
6
  import type * as object from "../Types";
6
7
  import type { Core, Resolved, Source } from "./Types";
8
+ /**
9
+ * The fields a `.from([...])` resolver is handed: only the named ones, each
10
+ * keeping its own `?:` (an omittable or optional dependency may be absent).
11
+ */
12
+ export type Narrowed<$Definition extends object.Definition, $Keys extends keyof $Definition> = Pretty<Pick<object.Fabricated<$Definition>, $Keys & keyof object.Fabricated<$Definition>>>;
7
13
  export type Computer<$Definition extends object.Definition> = <const $Source extends Source>(source: $Source) => {
14
+ /**
15
+ * Resolve against the whole object fabricated so far. The field depends on
16
+ * every field of this `.refine()` stage's base, so `T.pick`/`T.omit` keep all
17
+ * of them fabricated when this field is kept.
18
+ */
8
19
  as: (resolve: (params: {
9
20
  fabricated: object.Fabricated<$Definition>;
10
21
  }) => NoInfer<Resolved<$Source>>) => Schema<object.Fabricated<$Definition>, $Source>;
22
+ /**
23
+ * Declare the fields this one reads. The resolver is handed only those, and
24
+ * they are all `T.pick`/`T.omit` keep fabricated when this field is kept.
25
+ */
26
+ from: <const $Keys extends ReadonlyArray<keyof $Definition & string>>(keys: $Keys) => {
27
+ as: (resolve: (params: {
28
+ fabricated: Narrowed<$Definition, $Keys[number]>;
29
+ }) => NoInfer<Resolved<$Source>>) => Schema<Narrowed<$Definition, $Keys[number]>, $Source>;
30
+ };
11
31
  };
12
32
  export interface Schema<$Fabricated, $Source extends Source, $Adaptations extends Adaptations = {}> extends Core<$Fabricated, $Source, $Adaptations> {
13
33
  /**
@@ -39,12 +39,22 @@ export type Resolved<$Source, $Bindings extends unknown[] = []> = FabricatedBy<D
39
39
  * Unlike every other kind's `Meta`, this one is generic over the _enclosing
40
40
  * object's_ fabricated type as well as the source — that is what the resolver
41
41
  * is handed.
42
+ *
43
+ * `dependencies` is always present, so every compute field has a known set of
44
+ * fields it reads: the keys named by `.from([...])`, or, without one, every key
45
+ * of the `.refine()` stage's base — exactly what the resolver's type lets it
46
+ * read. `object/Fabricator.ts` resolves compute fields in dependency order from
47
+ * it, and `T.pick`/`T.omit` (`object/Registry.ts`) keep exactly those fields
48
+ * fabricated. `narrowed` is whether the resolver is handed only its
49
+ * `dependencies` (from `.from`) or the whole object fabricated so far.
42
50
  */
43
51
  export type Meta<$Fabricated, $Source extends Source> = {
44
52
  source: $Source;
45
53
  resolve: (params: {
46
54
  fabricated: $Fabricated;
47
55
  }) => Resolved<$Source>;
56
+ dependencies: ReadonlyArray<string>;
57
+ narrowed: boolean;
48
58
  };
49
59
  export interface Core<$Fabricated, $Source extends Source, $Adaptations extends Adaptations = {}> {
50
60
  [Kind]: "object.compute";
@@ -0,0 +1,7 @@
1
+ import type { Schema } from "../Schema";
2
+ import type { DefinitionOf, Subsettable } from "../Types";
3
+ /**
4
+ * `T.omit(source, keys)`: an `object` Schema without `keys`. `T.pick`'s
5
+ * inverse, and not a kind either — see `subset` in `object/Registry.ts`.
6
+ */
7
+ export default function omit<$Source extends Subsettable, const $Keys extends ReadonlyArray<keyof DefinitionOf<$Source> & string>>(source: $Source, keys: $Keys): Schema<Omit<DefinitionOf<$Source>, $Keys[number]>>;
@@ -0,0 +1,2 @@
1
+ export * from "./Registry";
2
+ export { default } from "./Registry";
@@ -0,0 +1,8 @@
1
+ import type { Schema } from "../Schema";
2
+ import type { DefinitionOf, Subsettable } from "../Types";
3
+ /**
4
+ * `T.pick(source, keys)`: an `object` Schema with only `keys`, in source order.
5
+ * Not a kind — the result is an ordinary `object` Schema. See `subset` in
6
+ * `object/Registry.ts` for what is kept, hidden, and dropped.
7
+ */
8
+ export default function pick<$Source extends Subsettable, const $Keys extends ReadonlyArray<keyof DefinitionOf<$Source> & string>>(source: $Source, keys: $Keys): Schema<Pick<DefinitionOf<$Source>, $Keys[number]>>;
@@ -0,0 +1,2 @@
1
+ export * from "./Registry";
2
+ export { default } from "./Registry";
@@ -28,13 +28,15 @@ export type Fabricator<$Schema extends {
28
28
  * how deep this `fabricate()` goes — so no structural path distinguishes
29
29
  * sibling expansions at the same depth (an `array` of three `self` children
30
30
  * calls `fabricateAt` three times on one shared element Fabricator; the schema
31
- * does not tell them apart). `forkSource` mints an isolated `RandomSource`
32
- * salted from this node's draw, and each `fabricateAt` resolves a
33
- * `ConstructionTrace` on it (`RandomSource.toConstructionTrace`), recorded on
34
- * each expansion's `trace`. The private source's construction counter orders
35
- * expansions; nothing to increment here. Isolation also keeps this node's
36
- * data-dependent draws from perturbing (or being perturbed by) an unrelated
37
- * Fabricator from the same `initialize()` instance.
31
+ * does not tell them apart). `forkSource` — the outer construction's
32
+ * `ConstructionContext.fork`, carrying its resolved algorithm and clock — mints
33
+ * an isolated `RandomSource` salted from this node's draw, and each
34
+ * `fabricateAt` resolves a `ConstructionTrace` on it
35
+ * (`RandomSource.toConstructionTrace`), recorded on each expansion's `trace`.
36
+ * The private source's construction counter orders expansions; nothing to
37
+ * increment here. Isolation also keeps this node's data-dependent draws from
38
+ * perturbing (or being perturbed by) an unrelated Fabricator from the same
39
+ * `initialize()` instance.
38
40
  *
39
41
  * Each `self` gets its own independently-dispatched expansion — calling
40
42
  * `context.self` twice (two array slots) is two `fabricateAt` calls, each with
@@ -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
  /**
@@ -157,6 +165,11 @@ export type { Adapting } from "./Adapter/Types";
157
165
  * programmatically (rather than as an inline literal) can name the type.
158
166
  */
159
167
  export type { Salt } from "./Random/Types";
168
+ /**
169
+ * The shape that `initialize({ algorithm })` accepts — a seed in, a `[0, 1)`
170
+ * generator out.
171
+ */
172
+ export type { Algorithm } from "./Random/Types";
160
173
  /**
161
174
  * Reads the value type a Schema produces, via its phantom `[Produces]` marker —
162
175
  * before it is built, which is what a helper accepting a Schema needs — or the
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@ghostry/fabricator",
3
- "version": "0.0.11",
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",
@@ -79,7 +79,7 @@
79
79
  "check": "tsc --noEmit && tsc --noEmit -p ./tsconfig.inexact.json",
80
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": [