mutts 1.0.7 → 1.0.8

package/README.md

@@ -44,6 +44,66 @@ import { Destroyable, allocated } from 'mutts/destroyable'
 
 **Note:** When importing from source files, you'll need to configure your build system (TypeScript, Vite, Webpack, etc.) to handle TypeScript compilation and module resolution. The source files are published alongside the built modules, so you can import directly from the `src` directory.
 
+### Environment Setup (Node vs Browser)
+
+`mutts` has two distinct entry points to handle environment-specific behaviors (like `async_hooks` in Node vs `wrap` in Browser).
+
+*   **Automatic Resolution**: Bundlers (Vite, Rollup, Webpack) and Node.js will automatically pick the correct entry point (`mutts/node` or `mutts/browser`) based on the `exports` field in `package.json`.
+*   **Manual Selection**: You can force a specific environment if needed:
+    ```typescript
+    import 'mutts/node' // Side-effect import to polyfill async hooks in tests
+    import { ... } from 'mutts/node' // Explicit Node entry
+    import { ... } from 'mutts/browser' // Explicit Browser entry
+    ```
+
+## [Reactive](./docs/reactive.md)
+
+A comprehensive reactivity system. See the **[Introduction](./docs/reactive/core.md)** or browse the **[Table of Contents](./docs/reactive.md)**.
+
+**Key Features:**
+- **Core Reactivity**: Proxy-based property access tracking with `reactive()`, `effect()`, `memoize()`, `project()`, and `scan()`
+- **Deep Watching**: Automatic tracking of nested object changes with `deepWatch()`
+- **Reactive Collections**: Specialized reactive versions of Array, Map, Set, WeakMap, and WeakSet
+- **Class Reactivity**: `@reactive` decorator and `ReactiveBase` for class-based reactivity
+- **Reactive Mixin**: Always-reactive classes with mixin support (`Reactive`)
+- **Back-Reference System**: Efficient change propagation through object hierarchies
+- **Type Safety**: Full TypeScript support with proper type inference
+- **Performance Optimized**: Lazy back-reference creation and efficient dependency tracking
+- **Debugging & Development**: Built-in tools like cycle detection and memoization discrepancy check
+
+**Use Cases:**
+- State management systems
+- UI framework reactivity
+- Data synchronization
+- Real-time applications
+- Form validation and processing
+
+## [Zones & Async Context](./docs/zone.md)
+
+A powerful context propagation system that maintains state across asynchronous boundaries (Promises, timeouts, listeners).
+
+**Key Features:**
+- **Universal Context**: Works reliably in both Node.js (via `async_hooks`) and Browser/Edge environments.
+- **Zone**: A simple value container that propagates with execution flow.
+- **ZoneHistory**: A zone that tracks the history of values it has held in the current execution path.
+- **ZoneAggregator**: Combines multiple zones into a single propagatable context.
+- **Async Hooks**: Low-level hooks to capture, restore, and undo context changes across async boundaries.
+
+```typescript
+import { Zone, asyncZone } from 'mutts'
+
+const userZone = new Zone<User>()
+// Register for async propagation
+asyncZone.add(userZone)
+
+userZone.with(currentUser, async () => {
+  // Context is available here
+  await someAsyncWork()
+  // Context is STILL available here, magically!
+  console.log(userZone.active) // currentUser
+})
+```
+
 ## [Indexable](./docs/indexable.md)
 
 A way to write classes that allow numeric indexes managed by a custom function - either given in the class by the symbols [getAt] and [setAt] either by a specification if the Indexable class.
@@ -156,26 +216,4 @@ A comprehensive resource management system that provides automatic cleanup for o
 - Network resource management
 - Memory management for large objects
 - Plugin systems with proper cleanup
-- Temporary resource management
-
-## [Reactive](./docs/reactive.md)
-
-A comprehensive reactivity system. See the **[Introduction](./docs/reactive/core.md)** or browse the **[Table of Contents](./docs/reactive.md)**.
-
-**Key Features:**
-- **Core Reactivity**: Proxy-based property access tracking with `reactive()`, `effect()`, `memoize()`, `project()`, and `scan()`
-- **Deep Watching**: Automatic tracking of nested object changes with `deepWatch()`
-- **Reactive Collections**: Specialized reactive versions of Array, Map, Set, WeakMap, and WeakSet
-- **Class Reactivity**: `@reactive` decorator and `ReactiveBase` for class-based reactivity
-- **Reactive Mixin**: Always-reactive classes with mixin support (`Reactive`)
-- **Back-Reference System**: Efficient change propagation through object hierarchies
-- **Type Safety**: Full TypeScript support with proper type inference
-- **Performance Optimized**: Lazy back-reference creation and efficient dependency tracking
-- **Debugging & Development**: Built-in tools like cycle detection and memoization discrepancy check
-
-**Use Cases:**
-- State management systems
-- UI framework reactivity
-- Data synchronization
-- Real-time applications
-- Form validation and processing
+- Temporary resource management

package/dist/async/browser.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=browser.d.ts.map

package/dist/async/browser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../../src/async/browser.ts"],"names":[],"mappings":""}

package/dist/async/index.d.ts

@@ -0,0 +1,18 @@
+export type Restorer = () => () => void;
+export type Hook = () => Restorer;
+export declare const asyncHooks: {
+    addHook(_hook: Hook): () => void;
+    /**
+     * [Hack] Sanitize a promise (or value) to prevent context leaks.
+     * Default: Identity function.
+     * Browser: Uses Macrotask wrapping to break microtask chains.
+     */
+    sanitizePromise(p: any): any;
+};
+/**
+ * Register a hook that will be called whenever an asynchronous operation is initiated.
+ * The hook should return a restorer function which will be called just before the async callback runs.
+ * That restorer should in turn return an undoer function which will be called just after the async callback finishes.
+ */
+export declare const asyncHook: (hook: Hook) => () => void;
+//# sourceMappingURL=index.d.ts.map

package/dist/async/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/async/index.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,QAAQ,GAAG,MAAM,MAAM,IAAI,CAAA;AACvC,MAAM,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAA;AAEjC,eAAO,MAAM,UAAU;mBACP,IAAI,GAAG,MAAM,IAAI;IAG7B;;;;OAIG;uBACgB,GAAG,GAAG,GAAG;CAG/B,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,SAAS,GAAI,MAAM,IAAI,WAlBP,IAkBoC,CAAA"}

package/dist/async/node.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=node.d.ts.map

package/dist/async/node.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"node.d.ts","sourceRoot":"","sources":["../../src/async/node.ts"],"names":[],"mappings":""}

package/dist/{chunks/index-BFYK02LG.js → browser.cjs}

@@ -1,10 +1,9 @@
 'use strict';
 
-const asyncHooks = {
-    addHook(_hook) {
-        throw 'One must import the library from the server or the client side';
-    }
-};
+require('./chunks/async-browser-CA0jPWIi.cjs');
+var asyncCore = require('./chunks/async-core-UqHzvJ-S.cjs');
+require('./chunks/async-node-BYHuGTni.cjs');
+require('node:async_hooks');
 
 /**
  * Combines multiple arrays into an array of tuples, stopping at the shortest array length
@@ -266,7 +265,7 @@ function contentRef(container) {
         })));
     return contentRefs.get(container);
 }
-function tag(obj, name) {
+function tag(name, obj) {
     Object.defineProperties(obj, {
         [Symbol.toStringTag]: {
             value: name,
@@ -2059,6 +2058,9 @@ function addToMutationHistory(source, target, obj, prop, evolution) {
 }
 
 var _ZoneAggregator_zones;
+function isu(z) {
+    return z;
+}
 class AZone {
     enter(value) {
         const prev = this.active;
@@ -2070,12 +2072,16 @@ class AZone {
     }
     with(value, fn) {
         const entered = this.enter(value);
+        let res;
         try {
-            return fn();
+            res = fn();
         }
         finally {
             this.leave(entered);
         }
+        // [HACK]: Sanitization
+        // See BROWSER_ASYNC_POLYFILL.md
+        return asyncCore.asyncHooks.sanitizePromise(res);
     }
     root(fn) {
         let prev = this.enter();
@@ -2118,12 +2124,12 @@ class ZoneHistory extends AZone {
                     throw new Error('ZoneHistory: re-entering historical zone');
                 if (value !== undefined)
                     self.history.add(value);
-                return { added: value, entered: controlled.enter(value) };
+                return { added: value, entered: isu(controlled).enter(value) };
             },
             leave(entered) {
                 if (entered.added !== undefined)
                     self.history.delete(entered.added);
-                return controlled.leave(entered.entered);
+                return isu(controlled).leave(entered.entered);
             }
         }));
     }
@@ -2157,13 +2163,13 @@ class ZoneAggregator extends AZone {
         const entered = new Map();
         for (const z of __classPrivateFieldGet(this, _ZoneAggregator_zones, "f")) {
             const v = value?.get(z);
-            entered.set(z, z.enter(v));
+            entered.set(z, isu(z).enter(v));
         }
         return entered;
     }
     leave(entered) {
         for (const z of __classPrivateFieldGet(this, _ZoneAggregator_zones, "f"))
-            z.leave(entered.get(z));
+            isu(z).leave(entered.get(z));
     }
     add(z) {
         __classPrivateFieldGet(this, _ZoneAggregator_zones, "f").add(z);
@@ -2176,8 +2182,8 @@ class ZoneAggregator extends AZone {
     }
 }
 _ZoneAggregator_zones = new WeakMap();
-const asyncZone = tag(new ZoneAggregator(), 'async');
-asyncHooks.addHook(() => {
+const asyncZone = tag('async', new ZoneAggregator());
+asyncCore.asyncHooks.addHook(() => {
     const zone = asyncZone.active;
     return () => {
         const prev = asyncZone.active;
@@ -2186,10 +2192,10 @@ asyncHooks.addHook(() => {
     };
 });
 
-const effectHistory = tag(new ZoneHistory(), 'effectHistory');
-tag(effectHistory.present, 'effectHistory.present');
+const effectHistory = tag('effectHistory', new ZoneHistory());
+tag('effectHistory.present', effectHistory.present);
 asyncZone.add(effectHistory);
-const effectAggregator = tag(new ZoneAggregator(effectHistory.present), 'effectAggregator');
+const effectAggregator = tag('effectAggregator', new ZoneAggregator(effectHistory.present));
 function isRunning(effect) {
     const root = getRoot(effect);
     return effectHistory.some((e) => getRoot(e) === root);
@@ -5452,6 +5458,17 @@ function scan(source, callback, initialValue) {
         indexEffects.clear();
     });
 }
+function resolve(cb) {
+    const result = reactive([]);
+    return cleanedBy(result, effect(() => {
+        const source = cb();
+        if (result.length !== source.length)
+            result.length = source.length;
+        for (let i = 0; i < source.length; i++)
+            if (result[i] !== source[i])
+                result[i] = source[i];
+    }));
+}
 
 function* index(i, { length = true } = {}) {
     if (length)
@@ -5524,6 +5541,8 @@ class ReactiveArray extends Array {
     at(index) {
         const actualIndex = index < 0 ? this.length + index : index;
         dependant(this, actualIndex);
+        if (index < 0)
+            dependant(this, 'length');
         if (actualIndex < 0 || actualIndex >= this.length)
             return undefined;
         return reactive(this[actualIndex]);
@@ -5578,36 +5597,61 @@ class ReactiveArray extends Array {
         };
     }
     indexOf(searchElement, fromIndex) {
-        dependant(this);
+        const length = this.length;
+        let i = fromIndex === undefined ? 0 : fromIndex;
+        if (i < 0)
+            i = Math.max(length + i, 0);
         const unwrappedSearch = unwrap(searchElement);
-        // Check both wrapped and unwrapped versions since array may contain either
-        const index = this.indexOf(unwrappedSearch, fromIndex);
-        if (index !== -1)
-            return index;
-        // If not found with unwrapped, try with wrapped (in case array contains wrapped version)
-        return this.indexOf(searchElement, fromIndex);
+        for (; i < length; i++) {
+            dependant(this, i);
+            const item = this[i];
+            if (item === searchElement || item === unwrappedSearch || unwrap(item) === unwrappedSearch) {
+                return i;
+            }
+        }
+        dependant(this, 'length');
+        return -1;
     }
     lastIndexOf(searchElement, fromIndex) {
-        dependant(this);
+        const length = this.length;
+        let i = fromIndex === undefined ? length - 1 : fromIndex;
+        if (i >= length)
+            i = length - 1;
+        if (i < 0)
+            i = Math.max(length + i, -1); // -1 ensures loop condition i >= 0 works correctly
         const unwrappedSearch = unwrap(searchElement);
-        // Check both wrapped and unwrapped versions since array may contain either
-        const index = this.lastIndexOf(unwrappedSearch, fromIndex);
-        if (index !== -1)
-            return index;
-        // If not found with unwrapped, try with wrapped (in case array contains wrapped version)
-        return this.lastIndexOf(searchElement, fromIndex);
+        for (; i >= 0; i--) {
+            dependant(this, i);
+            const item = this[i];
+            if (item === searchElement || item === unwrappedSearch || unwrap(item) === unwrappedSearch) {
+                return i;
+            }
+        }
+        // If we scanned the whole relevant part and didn't find it, we depend on length 
+        // (because adding elements might shift indices or add the element)
+        // Actually for lastIndexOf, if we start from end, length dependency is implicit in the start index calculation?
+        // But if we return -1, it means we didn't find it.
+        // If we push an element, should lastIndexOf update?
+        // Yes, if the new element is the one we are looking for.
+        dependant(this, 'length');
+        return -1;
     }
     includes(searchElement, fromIndex) {
-        dependant(this);
-        const unwrappedSearch = unwrap(searchElement);
-        // Check both wrapped and unwrapped versions since array may contain either
-        return this.includes(unwrappedSearch, fromIndex) || this.includes(searchElement, fromIndex);
+        return this.indexOf(searchElement, fromIndex) !== -1;
     }
     find(predicateOrElement, thisArg) {
-        dependant(this);
         if (typeof predicateOrElement === 'function') {
             const predicate = predicateOrElement;
-            return reactive(this.find((value, index, array) => predicate.call(thisArg, reactive(value), index, array), thisArg));
+            const length = this.length;
+            for (let i = 0; i < length; i++) {
+                dependant(this, i);
+                const val = reactive(this[i]);
+                if (predicate.call(thisArg, val, i, this)) {
+                    return val;
+                }
+            }
+            dependant(this, 'length');
+            return undefined;
         }
         const fromIndex = typeof thisArg === 'number' ? thisArg : undefined;
         const index = this.indexOf(predicateOrElement, fromIndex);
@@ -5616,10 +5660,18 @@ class ReactiveArray extends Array {
         return reactive(this[index]);
     }
     findIndex(predicateOrElement, thisArg) {
-        dependant(this);
         if (typeof predicateOrElement === 'function') {
             const predicate = predicateOrElement;
-            return this.findIndex((value, index, array) => predicate.call(thisArg, reactive(value), index, array), thisArg);
+            const length = this.length;
+            for (let i = 0; i < length; i++) {
+                dependant(this, i);
+                const val = reactive(this[i]);
+                if (predicate.call(thisArg, val, i, this)) {
+                    return i;
+                }
+            }
+            dependant(this, 'length');
+            return -1;
         }
         const fromIndex = typeof thisArg === 'number' ? thisArg : undefined;
         return this.indexOf(predicateOrElement, fromIndex);
@@ -5678,12 +5730,26 @@ class ReactiveArray extends Array {
         });
     }
     every(callbackfn, thisArg) {
-        dependant(this);
-        return this.every((value, index, array) => callbackfn.call(thisArg, reactive(value), index, array), thisArg);
+        const length = this.length;
+        for (let i = 0; i < length; i++) {
+            dependant(this, i);
+            if (!callbackfn.call(thisArg, reactive(this[i]), i, this)) {
+                return false;
+            }
+        }
+        dependant(this, 'length');
+        return true;
     }
     some(callbackfn, thisArg) {
-        dependant(this);
-        return this.some((value, index, array) => callbackfn.call(thisArg, reactive(value), index, array), thisArg);
+        const length = this.length;
+        for (let i = 0; i < length; i++) {
+            dependant(this, i);
+            if (callbackfn.call(thisArg, reactive(this[i]), i, this)) {
+                return true;
+            }
+        }
+        dependant(this, 'length');
+        return false;
     }
     // Side-effectful
     push(...items) {
@@ -5725,19 +5791,29 @@ class ReactiveArray extends Array {
     }
     splice(start, deleteCount, ...items) {
         const oldLength = this.length;
-        if (deleteCount === undefined)
-            deleteCount = oldLength - start;
+        // Normalize start index
+        let actualStart = start;
+        if (actualStart < 0)
+            actualStart = Math.max(oldLength + actualStart, 0);
+        else
+            actualStart = Math.min(actualStart, oldLength);
+        // Normalize deleteCount
+        let actualDeleteCount = deleteCount;
+        if (actualDeleteCount === undefined) {
+            actualDeleteCount = oldLength - actualStart;
+        }
+        else {
+            actualDeleteCount = Math.max(0, Math.min(actualDeleteCount, oldLength - actualStart));
+        }
         try {
             if (deleteCount === undefined)
                 return reactive(this.splice(start));
             return reactive(this.splice(start, deleteCount, ...items));
         }
         finally {
-            touched(this, { type: 'bunch', method: 'splice' }, 
-            // TODO: edge cases
-            deleteCount === items.length
-                ? range(start, start + deleteCount)
-                : range(start, oldLength + Math.max(items.length - deleteCount, 0), {
+            touched(this, { type: 'bunch', method: 'splice' }, actualDeleteCount === items.length
+                ? range(actualStart, actualStart + actualDeleteCount - 1)
+                : range(actualStart, oldLength + Math.max(items.length - actualDeleteCount, 0), {
                     length: true,
                 }));
         }
@@ -5760,6 +5836,17 @@ class ReactiveArray extends Array {
         }
     }
     fill(value, start, end) {
+        const len = this.length;
+        let k = start === undefined ? 0 : start;
+        if (k < 0)
+            k = Math.max(len + k, 0);
+        else
+            k = Math.min(k, len);
+        let final = end === undefined ? len : end;
+        if (final < 0)
+            final = Math.max(len + final, 0);
+        else
+            final = Math.min(final, len);
         try {
             if (start === undefined)
                 return this.fill(value);
@@ -5768,7 +5855,9 @@ class ReactiveArray extends Array {
             return this.fill(value, start, end);
         }
         finally {
-            touched(this, { type: 'bunch', method: 'fill' }, range(0, this.length - 1));
+            if (final > k) {
+                touched(this, { type: 'bunch', method: 'fill' }, range(k, final - 1));
+            }
         }
     }
     copyWithin(target, start, end) {
@@ -5778,11 +5867,27 @@ class ReactiveArray extends Array {
             return this.copyWithin(target, start, end);
         }
         finally {
-            touched(this, { type: 'bunch', method: 'copyWithin' }, 
-            // TODO: calculate the range properly
-            range(0, this.length - 1));
+            const len = this.length;
+            let to = target;
+            if (to < 0)
+                to = Math.max(len + to, 0);
+            else if (to >= len)
+                to = len;
+            let from = start;
+            if (from < 0)
+                from = Math.max(len + from, 0);
+            else if (from >= len)
+                from = len;
+            let final = end === undefined ? len : end;
+            if (final < 0)
+                final = Math.max(len + final, 0);
+            else if (final >= len)
+                final = len;
+            const count = Math.min(final - from, len - to);
+            if (count > 0) {
+                touched(this, { type: 'bunch', method: 'copyWithin' }, range(to, to + count - 1));
+            }
         }
-        // Touch all affected indices with a single allProps call
     }
 }
 
@@ -5878,7 +5983,7 @@ class ReactiveMap extends Map {
                 return this;
             },
             [Symbol.dispose]() { },
-        };
+        }; // TODO: real iterator? (If easy)
     }
     // Implement Map methods with reactivity
     delete(key) {
@@ -6023,7 +6128,7 @@ class ReactiveSet extends Set {
                 return this;
             },
             [Symbol.dispose]() { },
-        };
+        }; //TODO? (something easy)
     }
 }
 
@@ -6240,7 +6345,7 @@ function throttle(delay) {
     });
 }
 
-var version$1 = "1.0.7";
+var version$1 = "1.0.8";
 var pkg = {
 	version: version$1};
 
@@ -6289,6 +6394,8 @@ if (globalScope) {
     globalScope[GLOBAL_MUTTS_KEY] = currentSourceInfo;
 }
 
+exports.asyncHook = asyncCore.asyncHook;
+exports.asyncHooks = asyncCore.asyncHooks;
 exports.AZone = AZone;
 exports.ArrayReadForward = ArrayReadForward;
 exports.DecoratorError = DecoratorError;
@@ -6309,7 +6416,6 @@ exports.addBatchCleanup = addBatchCleanup;
 exports.allocated = allocated;
 exports.allocatedValues = allocatedValues;
 exports.arrayEquals = arrayEquals;
-exports.asyncHooks = asyncHooks;
 exports.asyncZone = asyncZone;
 exports.atomic = atomic;
 exports.biDi = biDi;
@@ -6331,9 +6437,11 @@ exports.derived = derived;
 exports.describe = describe;
 exports.destructor = destructor;
 exports.effect = effect;
+exports.effectAggregator = effectAggregator;
 exports.enableDevTools = enableDevTools;
 exports.forwardArray = forwardArray;
 exports.getActivationLog = getActivationLog;
+exports.getActiveEffect = getActiveEffect;
 exports.getActiveProjection = getActiveProjection;
 exports.getAt = getAt;
 exports.getState = getState;
@@ -6349,17 +6457,18 @@ exports.memoize = memoize;
 exports.mixin = mixin;
 exports.modernDecorator = modernDecorator;
 exports.named = named;
-exports.options = options;
 exports.organize = organize;
 exports.organized = organized;
 exports.profileInfo = profileInfo;
 exports.project = project;
 exports.reactive = reactive;
+exports.reactiveOptions = options;
 exports.register = register;
 exports.registerEffectForDebug = registerEffectForDebug;
 exports.registerNativeReactivity = registerNativeReactivity;
 exports.registerObjectForDebug = registerObjectForDebug;
 exports.renamed = renamed;
+exports.resolve = resolve;
 exports.root = root;
 exports.scan = scan;
 exports.setAt = setAt;
@@ -6375,4 +6484,4 @@ exports.untracked = untracked;
 exports.unwrap = unwrap;
 exports.watch = watch;
 exports.zip = zip;
-//# sourceMappingURL=index-BFYK02LG.js.map
+//# sourceMappingURL=browser.cjs.map