@ghostry/fabricator 0.0.11 → 0.0.13

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 (67) hide show
  1. package/README.md +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 +23 -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/boolean/Registry.js +10 -8
  9. package/dist/esm/Primitive/date/Defaults.js +12 -0
  10. package/dist/esm/Primitive/date/Fabricator.js +5 -10
  11. package/dist/esm/Primitive/date/Registry.js +49 -39
  12. package/dist/esm/Primitive/index.js +2 -0
  13. package/dist/esm/Primitive/null/Registry.js +6 -4
  14. package/dist/esm/Primitive/number/Fabricator.js +1 -1
  15. package/dist/esm/Primitive/number/Registry.js +36 -30
  16. package/dist/esm/Primitive/object/Fabricator.js +33 -11
  17. package/dist/esm/Primitive/object/Registry.js +90 -10
  18. package/dist/esm/Primitive/object/compute/Fabricator.js +10 -3
  19. package/dist/esm/Primitive/object/compute/Registry.js +20 -3
  20. package/dist/esm/Primitive/object/omit/Registry.js +5 -0
  21. package/dist/esm/Primitive/object/omit/index.js +2 -0
  22. package/dist/esm/Primitive/object/pick/Registry.js +5 -0
  23. package/dist/esm/Primitive/object/pick/index.js +2 -0
  24. package/dist/esm/Primitive/recursive/Fabricator.js +1 -0
  25. package/dist/esm/Primitive/recursive/Terminate.js +21 -9
  26. package/dist/esm/Primitive/symbol/Registry.js +15 -13
  27. package/dist/esm/Primitive/undefined/Registry.js +6 -4
  28. package/dist/esm/Schema/Core.js +9 -1
  29. package/dist/esm/Schema/Registry.js +27 -7
  30. package/dist/esm/Utility/DeepMerge.js +47 -6
  31. package/dist/esm/internal.js +1 -0
  32. package/dist/types/Error/index.d.ts +71 -6
  33. package/dist/types/Fabricator/Fabricate.d.ts +63 -0
  34. package/dist/types/Fabricator/Types.d.ts +13 -3
  35. package/dist/types/Harnessing/Core.d.ts +7 -7
  36. package/dist/types/Instance/Core.d.ts +15 -8
  37. package/dist/types/Instance/Stack/Visible.d.ts +10 -0
  38. package/dist/types/Instance/Types.d.ts +30 -15
  39. package/dist/types/Primitive/boolean/Registry.d.ts +6 -1
  40. package/dist/types/Primitive/date/Defaults.d.ts +11 -0
  41. package/dist/types/Primitive/date/Registry.d.ts +13 -9
  42. package/dist/types/Primitive/date/Types.d.ts +10 -0
  43. package/dist/types/Primitive/index.d.ts +2 -0
  44. package/dist/types/Primitive/null/Registry.d.ts +6 -1
  45. package/dist/types/Primitive/number/Registry.d.ts +8 -1
  46. package/dist/types/Primitive/object/Fabricator.d.ts +13 -5
  47. package/dist/types/Primitive/object/Registry.d.ts +17 -1
  48. package/dist/types/Primitive/object/Types.d.ts +19 -0
  49. package/dist/types/Primitive/object/compute/Fabricator.d.ts +9 -8
  50. package/dist/types/Primitive/object/compute/Registry.d.ts +7 -1
  51. package/dist/types/Primitive/object/compute/Schema.d.ts +20 -0
  52. package/dist/types/Primitive/object/compute/Types.d.ts +10 -0
  53. package/dist/types/Primitive/object/omit/Registry.d.ts +7 -0
  54. package/dist/types/Primitive/object/omit/index.d.ts +2 -0
  55. package/dist/types/Primitive/object/pick/Registry.d.ts +8 -0
  56. package/dist/types/Primitive/object/pick/index.d.ts +2 -0
  57. package/dist/types/Primitive/recursive/Fabricator.d.ts +9 -7
  58. package/dist/types/Primitive/symbol/Registry.d.ts +6 -1
  59. package/dist/types/Primitive/undefined/Registry.d.ts +6 -1
  60. package/dist/types/Schema/Core.d.ts +16 -1
  61. package/dist/types/Schema/Registry.d.ts +7 -4
  62. package/dist/types/Utility/DeepMerge.d.ts +11 -0
  63. package/dist/types/index.d.ts +23 -10
  64. package/dist/types/internal.d.ts +8 -0
  65. package/package.json +4 -4
  66. /package/dist/esm/Primitive/number/{defaults.js → Defaults.js} +0 -0
  67. /package/dist/types/Primitive/number/{defaults.d.ts → Defaults.d.ts} +0 -0
@@ -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
@@ -5,5 +5,10 @@ type ThisRegistry = Schema<{}, Adaptations> & {
5
5
  key: string;
6
6
  }>;
7
7
  };
8
- declare const registry: ThisRegistry;
8
+ /**
9
+ * A function, not the Schema itself: `Schema/Registry.ts` installs it as the
10
+ * `T.symbol` getter, so every read is a distinct Schema — see AGENTS.md's
11
+ * "Registry entries are getters."
12
+ */
13
+ declare function registry(): ThisRegistry;
9
14
  export default registry;
@@ -1,3 +1,8 @@
1
1
  import { Schema } from "./Schema";
2
- declare const registry: Schema;
2
+ /**
3
+ * A function, not the Schema itself: `Schema/Registry.ts` installs it as the
4
+ * `T.undefined` getter, so every read is a distinct Schema — see AGENTS.md's
5
+ * "Registry entries are getters."
6
+ */
7
+ declare function registry(): Schema;
3
8
  export default registry;
@@ -1,7 +1,8 @@
1
1
  import type { Adaptations } from "../Adapter/Types";
2
2
  import type { Kind as SchemaKind } from "../Primitive";
3
- import { Adaptation, Kind, Meta, type Produced, type Produces } from "../Types";
3
+ import { Adaptation, Kind, Meta, type Buildable, type Produced, type Produces } from "../Types";
4
4
  import { type PlainObject } from "../Utility/Types";
5
+ import type { AnySchema } from "./Types";
5
6
  /**
6
7
  * Normalize a Schema, a builder namespace, or an already-built Fabricator into
7
8
  * a clean, storable Schema — keeping only `[Kind]`/ `[Meta]`/`[Adaptation]` and
@@ -36,6 +37,20 @@ export declare function toSchema<$Kind extends string, $Meta extends PlainObject
36
37
  readonly [Produces]?: Produced<$Produces>;
37
38
  readonly [Adaptation]?: $Adaptations;
38
39
  };
40
+ /**
41
+ * Whether `candidate` is something `new Fabricator(...)` can build: a Schema or
42
+ * a built Fabricator, which both carry a `[Kind]` tag and a `[Meta]`. A bare
43
+ * builder that is a function (`T.array`, `T.recursive`) fails the first test;
44
+ * one that is an object but has no `[Kind]` fails the second. `T.string` and
45
+ * `T.bigint` carry `[Kind]` so they can name a compute source, but have no
46
+ * `[Meta]` until `.whereby(...)`, and fail the third.
47
+ */
48
+ export declare function isBuildable(candidate: unknown): candidate is Buildable;
49
+ /**
50
+ * {@link isBuildable}, excluding a built Fabricator: a Schema is inert, and only
51
+ * a Fabricator has `fabricate`.
52
+ */
53
+ export declare function isSchema(candidate: unknown): candidate is AnySchema;
39
54
  /**
40
55
  * The `[Kind]` a schema's fabricated value should be checked against with
41
56
  * {@link violatesKind}. For most kinds that is its own `[Kind]`, but
@@ -2,11 +2,14 @@ import * as primitives from "../Primitive";
2
2
  import { deepMerge, type DeepMerge } from "../Utility/DeepMerge";
3
3
  import { type PlainObject } from "../Utility/Types";
4
4
  /**
5
- * `Primitive/index.ts` also exports the kind-module namespace as `Primitive`
6
- * (`Primitive.boolean.Schema`, …). That is not a builder — omitting it here is
7
- * what keeps `T.Primitive` from existing.
5
+ * A kind whose `Registry.ts` default export takes no arguments returns a bare
6
+ * Schema, which `builders` installs behind a getter; every builder takes at
7
+ * least one. A bare kind left without a getter therefore fails to compile in
8
+ * `builders`, where the spread supplies the function itself.
8
9
  */
9
- type Builders = Omit<typeof primitives, "Primitive">;
10
+ type Builders = {
11
+ [$K in Exclude<keyof typeof primitives, "Primitive">]: (typeof primitives)[$K] extends () => infer $Schema ? $Schema : (typeof primitives)[$K];
12
+ };
10
13
  type RegistryInterface<$Registry> = {
11
14
  extend: <const $Extension extends PlainObject>(types: (params: {
12
15
  T: $Registry;
@@ -11,4 +11,15 @@ export type DeepMerge<$A, $B> = $B extends {
11
11
  [_ in $K]?: infer $BV;
12
12
  } ? $BV : never;
13
13
  }>;
14
+ /**
15
+ * Copies property descriptors rather than values, so a getter stays a getter on
16
+ * the result. The registry depends on that: every registry entry that is a
17
+ * Schema is a getter returning a fresh object (`Schema/Registry.ts`), and a
18
+ * merge that copied its value would pin it to one.
19
+ *
20
+ * Where both sides hold a key, each is read once — a getter included — and the
21
+ * values merge as they always have. If either side was a getter, the result is
22
+ * a getter again, returning a new object {@link rebuilt} from the merged one on
23
+ * every read, so an entry an extension merges into stays fresh.
24
+ */
14
25
  export declare function deepMerge<$A extends PlainObject, $B extends PlainObject>(a: $A, b: $B): DeepMerge<$A, $B>;
@@ -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
@@ -44,6 +44,14 @@ export type { AsFabricator } from "./Fabricator/Types";
44
44
  */
45
45
  export { Children, Kind, Meta, Produces, type Buildable, type Produced, } from "./Types";
46
46
  export { isArray, isPlainObject } from "./Utility/Core";
47
+ /**
48
+ * The runtime counterparts of `Buildable` and `AnySchema`, for an integration
49
+ * that takes one from an untyped caller. `@ghostry/extern`'s fabricator
50
+ * extension claims a block identity with `isSchema`: a built Fabricator is not
51
+ * an identity, since a block could either continue its streams or build afresh
52
+ * from its schema.
53
+ */
54
+ export { isBuildable, isSchema } from "./Schema/Core";
47
55
  export type * as Primitive from "./Primitive/namespace";
48
56
  /**
49
57
  * `Schema/Types.ts`'s own value-type resolution, needed by tests asserting
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@ghostry/fabricator",
3
- "version": "0.0.11",
3
+ "version": "0.0.13",
4
4
  "license": "MIT",
5
5
  "description": "Fabricate typed data from composable schemas.",
6
6
  "keywords": [
@@ -20,7 +20,7 @@
20
20
  "url": "git+https://github.com/ghostry-dev/fabricator",
21
21
  "directory": "pkg/fabricator"
22
22
  },
23
- "homepage": "https://docs.ghostry.dev/fabricator/",
23
+ "homepage": "https://docs.ghostry.dev/fabricator",
24
24
  "bugs": "https://github.com/ghostry-dev/fabricator/issues",
25
25
  "type": "module",
26
26
  "sideEffects": false,
@@ -65,7 +65,7 @@
65
65
  "provenance": true
66
66
  },
67
67
  "devDependencies": {
68
- "@ghostry/harness": "^0.0.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": [