@ghostry/fabricator 0.0.2 → 0.0.4

package/README.md

@@ -1,6 +1,20 @@
-# fabricator
+<div align="center">
 
-Fabricate typed data from composable schemas.
+<img src="https://docs.ghostry.dev/fabricator/logo.png" alt="fabricator" width="96" height="96">
+
+# @ghostry/fabricator
+
+**Fabricate typed data from composable schemas.**
+
+[![npm](https://img.shields.io/badge/npm-ffffff.svg?style=for-the-badge&color=000000&logo=npm&logoColor=CB3837)](https://www.npmjs.com/package/@ghostry/fabricator)
+[![npmx](https://img.shields.io/badge/npmx-ffffff.svg?style=for-the-badge&color=000000&logo=data:image/svg+xml;base64,PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTgiPz4KPHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHdpZHRoPSIxNTMiIGhlaWdodD0iMTUzIiB2ZXJzaW9uPSIxLjEiIHZpZXdCb3g9IjAgMCAxNTMgMTUzIj4KICA8ZyB0cmFuc2Zvcm09InRyYW5zbGF0ZSgxNi43MDQgOS45ODI3KSI+CiAgICA8cGF0aCBkPSJtMC45MzQ3NiA5Ny4yMDVoMjQuMDgxdjIzLjY5M2gtMjQuMDgxeiIgZmlsbD0iI2ZmZiI+PC9wYXRoPgogICAgPHBhdGggZD0ibTEwMy4xMi05LjIzMDctMy42MjExIDEwLjI0Ni00Ni4zMDkgMTMxLTMuNjIxMSAxMC4yNDZoMTUuNTM3bDMuNjIxMS0xMC4yNDYgMTEuNzE3LTMzLjE0OCAzOC4yMTEtMTA4LjF6IiBmaWxsPSIjNTFjOGZjIj48L3BhdGg+CiAgPC9nPgo8L3N2Zz4K&logoColor=51C8FC)](https://npmx.dev/package/@ghostry/fabricator)
+[![jsr](https://img.shields.io/badge/jsr-ffffff?style=for-the-badge&color=000000&logo=jsr&logoColor=F7DF1E)](https://jsr.io/@ghostry/fabricator)
+[![github](https://img.shields.io/badge/github-ffffff?style=for-the-badge&color=000000&logo=github&logoColor=ffffff)](https://github.com/ghostry-dev/fabricator)
+[![typescript](https://img.shields.io/badge/typescript-ffffff?style=for-the-badge&color=000000&logo=typescript&logoColor=3178C6)](#)
+[![bun](https://img.shields.io/badge/bun-ffffff?style=for-the-badge&color=000000&logo=bun&logoColor=FBF0DF)](#)
+[![node](https://img.shields.io/badge/node-ffffff?style=for-the-badge&color=000000&logo=nodedotjs&logoColor=5FA04E)](#)
+
+</div>
 
 ## Install
 
@@ -8,14 +22,12 @@ Fabricate typed data from composable schemas.
 npm install @ghostry/fabricator
 ```
 
-Also available via `bun add @ghostry/fabricator` or `bunx jsr add @ghostry/fabricator`.
-
 ## Example
 
 ```ts
 import { initialize } from "@ghostry/fabricator";
 
-const { T, Fabricator } = initialize({ seed: "1234" });
+const { T, Fabricator } = initialize();
 
 const ProductSchema = T.object({
   name: T.string.whereby({ length: { min: 1, max: 25 } }),
@@ -38,4 +50,4 @@ const item = Product.fabricate();
 const widget = Product.fabricate({ name: "Widget", inStock: true });
 ```
 
-`seed: "1234"` is an optional mixer; `clock` (the wall-clock instant of this call, by default) is the run's entropy. Pass the same seed and clock to replay. See the [docs site](https://docs.ghostry.dev/fabricator/) for the full guide: the mental model behind Schemas and Fabricators, composing and overriding schemas, custom types, distributions, and the [TypeBox adapter](https://www.npmjs.com/package/@ghostry/fabricator-adapter-typebox-v0).
+`initialize()` takes no required configuration. Its `clock` (by default, the wall-clock instant of the call) is the run's entropy, so every run differs, and passing that one number back as `clock` replays the run exactly. See the [docs site](https://docs.ghostry.dev/fabricator/) for the full guide: the mental model behind Schemas and Fabricators, composing and overriding schemas, custom types, distributions, and the [TypeBox adapter](https://www.npmjs.com/package/@ghostry/fabricator-adapter-typebox-v0).

package/dist/esm/Adapter/Core.js

@@ -38,10 +38,10 @@ function Core_layer(key, adaptation, prior) {
             [key]: prior
         }));
 }
-function drive(adapter, schema, context) {
+function walk(adapter, schema, context) {
     var _schema_Adaptation;
     const adaptation = null == (_schema_Adaptation = schema[Adaptation]) ? void 0 : _schema_Adaptation[adapter.key];
     if (adaptation) return adaptation(schema);
-    return adapter.convert(schema, (child, childContext)=>drive(adapter, child, childContext), context);
+    return adapter.convert(schema, (child, childContext)=>walk(adapter, child, childContext), context);
 }
-export { drive, mergeAdaptations, withAdaptations };
+export { mergeAdaptations, walk, withAdaptations };

package/dist/esm/Enumeration/Enumerate.js

@@ -1,14 +1,15 @@
 import { shuffle } from "../Distribution/index.js";
 import { FabricatorError } from "../Error/index.js";
 import { Constructor } from "../Fabricator/Constructor.js";
+import { toInnermostFrame } from "../Instance/Stack/Visible.js";
 import { toStreamFromTrace } from "../Random/index.js";
 import { plan, resolve } from "./Plan.js";
-function enumerables(source, limits, stack) {
-    const Fabricator = Constructor(source, stack);
+function enumerables(source, limits, stack, ancestry) {
+    const Fabricator = Constructor(source, stack, ancestry);
     function effectiveSource() {
         var _ref;
-        var _stack_current;
-        return null != (_ref = null == (_stack_current = stack.current()) ? void 0 : _stack_current.source) ? _ref : source;
+        var _toInnermostFrame;
+        return null != (_ref = null == (_toInnermostFrame = toInnermostFrame(stack, ancestry)) ? void 0 : _toInnermostFrame.source) ? _ref : source;
     }
     function iterable(rebuild) {
         return {
@@ -34,19 +35,21 @@ function enumerables(source, limits, stack) {
         };
     }
     function combinatorial(schema) {
-        const combinatorialSeed = [
-            ...effectiveSource().seed,
+        const combinatorialSalt = [
+            ...effectiveSource().salt,
             "combinatorial"
         ];
         const probe = plan(new Fabricator(schema, {
-            seed: combinatorialSeed
+            salt: combinatorialSalt,
+            ordinal: null
         }), {
             strategy: "product"
         });
         if (probe.width > BigInt(limits.combinatorial)) throw new FabricatorError.CombinatorialLimitExceededError(probe.width, limits.combinatorial);
         return iterable(()=>{
             const built = new Fabricator(schema, {
-                seed: combinatorialSeed
+                salt: combinatorialSalt,
+                ordinal: null
             });
             return {
                 built,
@@ -58,24 +61,25 @@ function enumerables(source, limits, stack) {
     }
     function coverage(schema) {
         const base = effectiveSource();
-        const coverageSeed = [
-            ...base.seed,
+        const coverageSalt = [
+            ...base.salt,
             "coverage"
         ];
-        const orderSeed = [
-            ...base.seed,
+        const orderSalt = [
+            ...base.salt,
             "coverage",
             "order"
         ];
         return iterable(()=>{
             const built = new Fabricator(schema, {
-                seed: coverageSeed
+                salt: coverageSalt,
+                ordinal: null
             });
             return {
                 built,
                 axis: plan(built, {
                     strategy: "cycle",
-                    orderer: orderer(base, orderSeed)
+                    orderer: orderer(base, orderSalt)
                 })
             };
         });
@@ -85,11 +89,11 @@ function enumerables(source, limits, stack) {
         coverage
     };
 }
-function orderer(source, seed) {
-    const forked = source.fork(seed);
-    const root = forked.toRoot("unattributed");
+function orderer(source, salt) {
+    const forked = source.fork(salt);
+    const trace = forked.toConstructionTrace();
     const stream = toStreamFromTrace(forked.algorithm, {
-        ...root,
+        ...trace,
         path: [],
         kind: "order"
     });

package/dist/esm/Error/index.js

@@ -31,14 +31,6 @@ class Error_FabricatorError extends Error {
         }
     }
     FabricatorError.InvalidCombinatorialLimitError = InvalidCombinatorialLimitError;
-    class InvalidAttributionRootError extends FabricatorError {
-        constructor(root){
-            super(), _define_property(this, "root", void 0), this.root = root;
-            this.name = "InvalidAttributionRootError";
-            this.message = `initialize({ attribution: { kind: "rooted", root } }) requires an absolute path or a "file://" URL; received "${root}".`;
-        }
-    }
-    FabricatorError.InvalidAttributionRootError = InvalidAttributionRootError;
     class DetachedSelfError extends FabricatorError {
         constructor(during){
             super(), _define_property(this, "during", void 0), this.during = during;
@@ -205,5 +197,13 @@ class Error_FabricatorError extends Error {
         }
     }
     FabricatorError.SynchronousStackError = SynchronousStackError;
+    class HarnessingProviderError extends FabricatorError {
+        constructor(){
+            super();
+            this.name = "HarnessingProviderError";
+            this.message = "The `fabricator` provider was called outside its integration's `around`, so there is no per-test scope to provide. A composer must run each integration's providers inside that integration's `around` frame, as `@ghostry/harness` does.";
+        }
+    }
+    FabricatorError.HarnessingProviderError = HarnessingProviderError;
 })(Error_FabricatorError || (Error_FabricatorError = {}));
 export { Error_FabricatorError as FabricatorError };

package/dist/esm/Fabricator/Constructor.js

@@ -1,10 +1,11 @@
 import { FabricatorError } from "../Error/index.js";
+import { toInnermostFrame } from "../Instance/Stack/Visible.js";
 import { Primitive } from "../Primitive/index.js";
-import { isLayered, normalizeSeed } from "../Random/index.js";
+import { isLayered, normalizeSalt } from "../Random/index.js";
 import { toSchema } from "../Schema/Core.js";
 import { Adaptation, Fixed, Kind, Layer, Meta } from "../Types.js";
 import { inline } from "../Utility/Core.js";
-function Constructor(source, stack) {
+function Constructor(source, stack, ancestry) {
     function make(schema, path, context) {
         schema = toSchema(schema);
         const kind = schema[Kind];
@@ -280,7 +281,7 @@ function Constructor(source, stack) {
     function construct(schema, options = {}) {
         var _options_path;
         if ("string" == typeof options.kind && options.kind !== schema[Kind]) throw new FabricatorError.TraceKindMismatchError(schema[Kind], options.kind);
-        const context = toConstructionContext(source, options, stack);
+        const context = toConstructionContext(source, options, stack, ancestry);
         const made = make(schema, null != (_options_path = options.path) ? _options_path : [], context);
         const adaptations = schema[Adaptation];
         return adaptations ? {
@@ -290,39 +291,37 @@ function Constructor(source, stack) {
     }
     return construct;
 }
-function toConstructionContext(source, options, stack) {
-    const { source: rooted, root: construction } = resolveScope(source, options, stack);
+function toConstructionContext(source, options, stack, ancestry) {
+    const { source: resolved, trace } = resolveScope(source, options, stack, ancestry);
     return {
         toTrace: (path, kind)=>({
-                ...construction,
+                ...trace,
                 path,
                 kind
             }),
-        algorithm: rooted.algorithm
+        algorithm: resolved.algorithm
     };
 }
-function resolveScope(source, options, stack) {
+function resolveScope(source, options, stack, ancestry) {
     var _ref;
-    const frame = stack.current();
-    const base = null != (_ref = null == frame ? void 0 : frame.source) ? _ref : source;
+    var _toInnermostFrame;
+    const base = null != (_ref = null == (_toInnermostFrame = toInnermostFrame(stack, ancestry)) ? void 0 : _toInnermostFrame.source) ? _ref : source;
+    const salt = inline(()=>{
+        if (!options.salt) return;
+        if (isLayered(options.salt)) return [
+            ...base.salt,
+            ...normalizeSalt(options.salt[Layer])
+        ];
+        return normalizeSalt(options.salt);
+    });
     const pins = {
+        salt,
         clock: options.clock,
-        root: options.root,
-        file: options.file,
         ordinal: options.ordinal
     };
-    if (!options.seed) return {
-        source: base,
-        root: base.toRoot("attributed", pins)
-    };
-    const seed = isLayered(options.seed) ? [
-        ...base.seed,
-        ...normalizeSeed(options.seed[Layer])
-    ] : options.seed;
-    const forked = base.fork(seed);
     return {
-        source: forked,
-        root: forked.toRoot("unattributed", pins)
+        source: base,
+        trace: base.toConstructionTrace(pins)
     };
 }
 export { Constructor };

package/dist/esm/Harnessing/Core.js

@@ -0,0 +1,30 @@
+import { FabricatorError } from "../Error/index.js";
+import { layer as index_js_layer } from "../Random/index.js";
+import { saltFor } from "./Salt.js";
+function integration(instance) {
+    let scope;
+    return {
+        name: "@ghostry/fabricator",
+        provides: {
+            fabricator: ()=>{
+                if (void 0 === scope) throw new FabricatorError.HarnessingProviderError();
+                return scope;
+            }
+        },
+        around (identity, body) {
+            const salt = index_js_layer(saltFor(identity));
+            return instance.wrap({
+                salt
+            }, (entered)=>{
+                const previous = scope;
+                scope = entered;
+                try {
+                    return body();
+                } finally{
+                    scope = previous;
+                }
+            });
+        }
+    };
+}
+export { integration };

package/dist/esm/Harnessing/Salt.js

@@ -0,0 +1,12 @@
+function saltFor(identity) {
+    const salt = [
+        identity.kind,
+        ...identity.path,
+        identity.name
+    ];
+    return "number" == typeof identity.row ? [
+        ...salt,
+        String(identity.row)
+    ] : salt;
+}
+export { saltFor };

package/dist/esm/Harnessing/Types.js

@@ -0,0 +1 @@
+export { };

package/dist/esm/Instance/Core.js

@@ -1,10 +1,11 @@
 import { enumerables } from "../Enumeration/Enumerate.js";
 import { FabricatorError } from "../Error/index.js";
 import { Constructor } from "../Fabricator/Constructor.js";
-import { defaultAlgorithm, deriveClock, isLayered, normalizeSeed, resolveAttribution, toRandomSource } from "../Random/index.js";
+import { defaultAlgorithm, deriveClock, isLayered, normalizeSalt, toRandomSource } from "../Random/index.js";
 import { registry } from "../Schema/Registry.js";
 import { Layer } from "../Types.js";
 import { inline, isThenable, noop } from "../Utility/Core.js";
+import { toInnermostFrame } from "./Stack/Visible.js";
 const DEFAULT_COMBINATORIAL_LIMIT = 1024;
 function resolveCombinatorialLimit(limit) {
     if (void 0 === limit) return DEFAULT_COMBINATORIAL_LIMIT;
@@ -12,57 +13,72 @@ function resolveCombinatorialLimit(limit) {
     return limit;
 }
 function resolveClock(config) {
-    return "number" == typeof config.clock ? config.clock : deriveClock(config.algorithm, normalizeSeed(config.seed));
+    return "number" == typeof config.clock ? config.clock : deriveClock(config.algorithm, normalizeSalt(config.salt));
+}
+function mint() {
+    return Symbol("fabricator.instance");
 }
 function overlay(base, over) {
-    var _ref, _over_algorithm, _base_attribution, _ref1, _over_types, _over_limits;
+    var _ref, _over_algorithm, _ref1, _over_types, _over_limits;
     var _this;
-    const seed = inline(()=>{
-        if (void 0 === over.seed) return normalizeSeed(base.seed);
-        if (isLayered(over.seed)) return [
-            ...normalizeSeed(base.seed),
-            ...normalizeSeed(over.seed[Layer])
+    const salt = inline(()=>{
+        if (void 0 === over.salt) return normalizeSalt(base.salt);
+        if (isLayered(over.salt)) return [
+            ...normalizeSalt(base.salt),
+            ...normalizeSalt(over.salt[Layer])
         ];
-        return normalizeSeed(over.seed);
+        return normalizeSalt(over.salt);
     });
     const clock = inline(()=>{
         var _base_clock;
-        if ("seeded" === over.clock) return "seeded";
+        if ("derived" === over.clock) return "derived";
         if (void 0 !== over.clock) return over.clock.valueOf();
         return null != (_base_clock = base.clock) ? _base_clock : Date.now();
     });
     return {
-        seed,
+        salt,
         clock,
         algorithm: null != (_ref = null != (_over_algorithm = over.algorithm) ? _over_algorithm : base.algorithm) ? _ref : defaultAlgorithm,
-        attribution: over.attribution ? resolveAttribution(over.attribution) : null != (_base_attribution = base.attribution) ? _base_attribution : resolveAttribution(void 0),
         types: null != (_ref1 = null != (_over_types = over.types) ? _over_types : base.types) ? _ref1 : registry,
         limits: {
             combinatorial: resolveCombinatorialLimit(null == (_this = null != (_over_limits = over.limits) ? _over_limits : base.limits) ? void 0 : _this.combinatorial)
         }
     };
 }
-function instantiate(config, stack) {
+function instantiate(config, stack, parent) {
+    const ancestry = void 0 === parent ? [
+        mint()
+    ] : [
+        ...parent.ancestry,
+        mint()
+    ];
     const source = toRandomSource({
-        seed: config.seed,
+        salt: config.salt,
         algorithm: config.algorithm,
-        attribution: config.attribution,
         clock: resolveClock(config)
     });
-    const Fabricator = Constructor(source, stack);
-    const { combinatorial, coverage } = enumerables(source, config.limits, stack);
+    const Fabricator = Constructor(source, stack, ancestry);
+    const { combinatorial, coverage } = enumerables(source, config.limits, stack, ancestry);
+    function derive(over) {
+        const derived = overlay(config, over);
+        return {
+            ...instantiate(derived, stack, {
+                ancestry,
+                root: instance.root
+            }),
+            config: derived
+        };
+    }
     function fork(forkOverlay = {}) {
-        return instantiate(overlay(config, forkOverlay), stack).instance;
+        return derive(forkOverlay).instance;
     }
     function wrap(wrapOverlay, block) {
-        var _ref;
-        var _stack_current;
-        const base = null != (_ref = null == (_stack_current = stack.current()) ? void 0 : _stack_current.config) ? _ref : config;
-        const scopedConfig = overlay(base, wrapOverlay);
-        const scoped = instantiate(scopedConfig, stack);
+        const scoped = derive(wrapOverlay);
         const result = stack.enter({
-            config: scopedConfig,
-            source: scoped.source
+            config: scoped.config,
+            source: scoped.source,
+            instance: scoped.instance,
+            ancestry
         }, ()=>block(scoped.instance));
         if (!stack.asynchronous && isThenable(result)) {
             result.then(noop, noop);
@@ -70,34 +86,45 @@ function instantiate(config, stack) {
         }
         return result;
     }
+    function visibleFrame() {
+        return toInnermostFrame(stack, ancestry);
+    }
     const context = {
-        get seed () {
+        get salt () {
             var _ref;
-            var _stack_current;
-            return normalizeSeed((null != (_ref = null == (_stack_current = stack.current()) ? void 0 : _stack_current.config) ? _ref : config).seed);
+            var _visibleFrame;
+            return normalizeSalt((null != (_ref = null == (_visibleFrame = visibleFrame()) ? void 0 : _visibleFrame.config) ? _ref : config).salt);
         },
         get algorithm () {
             var _ref1;
-            var _stack_current1;
-            return (null != (_ref1 = null == (_stack_current1 = stack.current()) ? void 0 : _stack_current1.config) ? _ref1 : config).algorithm;
+            var _visibleFrame1;
+            return (null != (_ref1 = null == (_visibleFrame1 = visibleFrame()) ? void 0 : _visibleFrame1.config) ? _ref1 : config).algorithm;
         },
-        get attribution () {
+        get clock () {
             var _ref2;
-            var _stack_current2;
-            return (null != (_ref2 = null == (_stack_current2 = stack.current()) ? void 0 : _stack_current2.config) ? _ref2 : config).attribution;
+            var _visibleFrame2;
+            return resolveClock(null != (_ref2 = null == (_visibleFrame2 = visibleFrame()) ? void 0 : _visibleFrame2.config) ? _ref2 : config);
         },
-        get clock () {
-            var _ref3;
-            var _stack_current3;
-            return resolveClock(null != (_ref3 = null == (_stack_current3 = stack.current()) ? void 0 : _stack_current3.config) ? _ref3 : config);
+        scope: ()=>{
+            var _ref;
+            var _visibleFrame;
+            return null != (_ref = null == (_visibleFrame = visibleFrame()) ? void 0 : _visibleFrame.instance) ? _ref : instance;
+        },
+        get depth () {
+            return stack.visible(ancestry).length;
         }
     };
     const instance = {
         T: config.types,
+        ancestry,
+        get root () {
+            var _ref3;
+            return null != (_ref3 = null == parent ? void 0 : parent.root) ? _ref3 : instance;
+        },
         Fabricator,
         combinatorial,
         coverage,
-        seed: source.seed,
+        salt: source.salt,
         fork,
         wrap,
         context

package/dist/esm/Instance/Stack/Async.js

@@ -1,10 +1,18 @@
 import { AsyncLocalStorage } from "async_hooks";
+import { toVisible } from "./Visible.js";
 function toStack() {
     const store = new AsyncLocalStorage();
+    const getFrames = ()=>{
+        var _store_getStore;
+        return null != (_store_getStore = store.getStore()) ? _store_getStore : [];
+    };
     return {
         asynchronous: true,
-        current: ()=>store.getStore(),
-        enter: (frame, block)=>store.run(frame, block)
+        visible: (ancestry)=>toVisible(getFrames(), ancestry),
+        enter: (frame, block)=>store.run([
+                ...getFrames(),
+                frame
+            ], block)
     };
 }
 export { toStack };

package/dist/esm/Instance/Stack/Sync.js

@@ -1,8 +1,9 @@
+import { toVisible } from "./Visible.js";
 function toStack() {
     const frames = [];
     return {
         asynchronous: false,
-        current: ()=>frames[frames.length - 1],
+        visible: (ancestry)=>toVisible(frames, ancestry),
         enter: (frame, block)=>{
             frames.push(frame);
             try {

package/dist/esm/Instance/Stack/Visible.js

@@ -0,0 +1,13 @@
+function onDirectLine(a, b) {
+    const shared = Math.min(a.length, b.length);
+    for(let index = 0; index < shared; index++)if (a[index] !== b[index]) return false;
+    return true;
+}
+function toVisible(frames, ancestry) {
+    return frames.filter((frame)=>onDirectLine(frame.ancestry, ancestry));
+}
+function toInnermostFrame(stack, ancestry) {
+    const frames = stack.visible(ancestry);
+    return frames[frames.length - 1];
+}
+export { toInnermostFrame, toVisible };

package/dist/esm/Primitive/recursive/Fabricator.js

@@ -10,7 +10,7 @@ function Fabricator(context, forkSource, make) {
     function fabricateAt(depth) {
         const atMax = depth >= meta.depth.max;
         const target = atMax ? meta.terminal : meta.body;
-        const construction = privateSource.toRoot("counted");
+        const construction = privateSource.toConstructionTrace();
         const context = {
             toTrace: (path, kind)=>({
                     ...construction,