mutts 1.0.3 → 1.0.5

package/README.md

@@ -16,7 +16,7 @@ npm install mutts
 
 > [!TIP]
 > **Are you an AI Agent?**
-> If you are an LLM or autonomous agent trying to fix bugs or understand this codebase, please read the **[AI Agent Manual](./docs/ai.md)**.
+> If you are an LLM or autonomous agent trying to fix bugs or understand this codebase, please read the **[AI Agent Manual](./docs/ai/manual.md)**.
 > It contains structured protocols, error code definitions, and introspection API details designed specifically for you.
 > A precise **[API Reference](./docs/ai/api-reference.md)** is also available for type lookups.
 

package/dist/chunks/{index-HNVqPzjz.js → index-Cvxdw6Ax.js}

@@ -354,6 +354,10 @@ const prototypeForwarding = Symbol('prototype-forwarding');
  * Symbol representing all properties in reactive tracking
  */
 const allProps = Symbol('all-props');
+/**
+ * Symbol for accessing projection information on reactive objects
+ */
+const projectionInfo = Symbol('projection-info');
 // Symbol to mark functions with their root function
 const rootFunction = Symbol('root-function');
 /**
@@ -428,6 +432,12 @@ const options = {
      * @default 100
      */
     maxEffectChain: 100,
+    /**
+     * Maximum number of times an effect can be triggered by the same cause in a single batch
+     * Used to detect aggressive re-computation or infinite loops
+     * @default 10
+     */
+    maxTriggerPerBatch: 10,
     /**
      * Debug purpose: maximum effect reaction (like call stack max depth)
      * Used to prevent infinite loops
@@ -1260,6 +1270,50 @@ function formatRoots(roots, limit = 20) {
     const end = names.slice(-10);
     return `${start.join(' → ')} ... (${names.length - 15} more) ... ${end.join(' → ')}`;
 }
+// Nested map structure for efficient counting and batch cleanup
+// batchId -> effect root -> obj -> prop -> count
+let activationRegistry;
+const activationLog = new Array(100);
+function getActivationLog() {
+    return activationLog;
+}
+function recordActivation(effect, obj, evolution, prop) {
+    const root = getRoot(effect);
+    if (!activationRegistry)
+        return;
+    let effectData = activationRegistry.get(root);
+    if (!effectData) {
+        effectData = new Map();
+        activationRegistry.set(root, effectData);
+    }
+    let objData = effectData.get(obj);
+    if (!objData) {
+        objData = new Map();
+        effectData.set(obj, objData);
+    }
+    const count = (objData.get(prop) ?? 0) + 1;
+    objData.set(prop, count);
+    // Keep a limited history for diagnostics
+    activationLog.unshift({
+        effect,
+        obj,
+        evolution,
+        prop,
+    });
+    activationLog.pop();
+    if (count >= options.maxTriggerPerBatch) {
+        const effectName = root?.name || 'anonymous';
+        const message = `Aggressive trigger detected: effect "${effectName}" triggered ${count} times in the batch by the same cause.`;
+        if (options.maxEffectReaction === 'throw') {
+            throw new ReactiveError(message, {
+                code: ReactiveErrorCode.MaxReactionExceeded,
+                count,
+                effect: effectName,
+            });
+        }
+        options.warn(`[reactive] ${message}`);
+    }
+}
 /**
  * Registers a debug callback that is called when the current effect is triggered by a dependency change
  *
@@ -1549,6 +1603,9 @@ function cleanupEffectFromGraph(effect) {
 // Track currently executing effects to prevent re-execution
 // These are all the effects triggered under `activeEffect`
 let batchQueue;
+function hasBatched(effect) {
+    return batchQueue?.all.has(getRoot(effect));
+}
 const batchCleanups = new Set();
 /**
  * Computes and caches in-degrees for all effects in the batch
@@ -1955,21 +2012,29 @@ function batch(effect, immediate) {
             addToBatch(effect[i], caller, immediate === 'immediate');
         }
         if (immediate) {
+            const firstReturn = {};
             // Execute immediately (before batch returns)
             for (let i = 0; i < effect.length; i++) {
                 try {
-                    effect[i]();
+                    const rv = effect[i]();
+                    if (rv !== undefined && !('value' in firstReturn))
+                        firstReturn.value = rv;
                 }
                 finally {
                     const root = getRoot(effect[i]);
                     batchQueue.all.delete(root);
                 }
             }
+            return firstReturn.value;
         }
         // Otherwise, effects will be picked up in next executeNext() call
     }
     else {
         // New batch - initialize
+        if (!activationRegistry)
+            activationRegistry = new Map();
+        else
+            throw new Error('Batch already in progress');
         options.beginChain(roots);
         batchQueue = {
             all: new Map(),
@@ -2048,6 +2113,7 @@ function batch(effect, immediate) {
                 return firstReturn.value;
             }
             finally {
+                activationRegistry = undefined;
                 batchQueue = undefined;
                 options.endChain();
             }
@@ -2056,60 +2122,69 @@ function batch(effect, immediate) {
             // Execute in dependency order
             const firstReturn = {};
             try {
-                while (batchQueue.all.size > 0) {
-                    if (effectuatedRoots.length > options.maxEffectChain) {
-                        const cycle = findCycleInChain(effectuatedRoots);
-                        const trace = formatRoots(effectuatedRoots);
-                        const message = cycle
-                            ? `Max effect chain reached (cycle detected: ${formatRoots(cycle)})`
-                            : `Max effect chain reached (trace: ${trace})`;
-                        const queuedRoots = batchQueue ? Array.from(batchQueue.all.keys()) : [];
-                        const queued = queuedRoots.map((r) => r.name || '<anonymous>');
-                        const debugInfo = {
-                            code: ReactiveErrorCode.MaxDepthExceeded,
-                            effectuatedRoots,
-                            cycle,
-                            trace,
-                            maxEffectChain: options.maxEffectChain,
-                            queued: queued.slice(0, 50),
-                            queuedCount: queued.length,
-                            // Try to get causation for the last effect
-                            causalChain: effectuatedRoots.length > 0
-                                ? getTriggerChain(batchQueue.all.get(effectuatedRoots[effectuatedRoots.length - 1]))
-                                : [],
-                        };
-                        switch (options.maxEffectReaction) {
-                            case 'throw':
-                                throw new ReactiveError(`[reactive] ${message}`, debugInfo);
-                            case 'debug':
-                                // biome-ignore lint/suspicious/noDebugger: This is the whole point here
-                                debugger;
-                                throw new ReactiveError(`[reactive] ${message}`, debugInfo);
-                            case 'warn':
-                                options.warn(`[reactive] ${message} (queued: ${queued.slice(0, 10).join(', ')}${queued.length > 10 ? ', …' : ''})`);
-                                break;
+                // Outer loop: continue while there are effects OR cleanups pending.
+                // This ensures effects triggered by cleanups are not lost.
+                while (batchQueue.all.size > 0 || batchCleanups.size > 0) {
+                    // Inner loop: execute all pending effects
+                    while (batchQueue.all.size > 0) {
+                        if (effectuatedRoots.length > options.maxEffectChain) {
+                            const cycle = findCycleInChain(effectuatedRoots);
+                            const trace = formatRoots(effectuatedRoots);
+                            const message = cycle
+                                ? `Max effect chain reached (cycle detected: ${formatRoots(cycle)})`
+                                : `Max effect chain reached (trace: ${trace})`;
+                            const queuedRoots = batchQueue ? Array.from(batchQueue.all.keys()) : [];
+                            const queued = queuedRoots.map((r) => r.name || '<anonymous>');
+                            const debugInfo = {
+                                code: ReactiveErrorCode.MaxDepthExceeded,
+                                effectuatedRoots,
+                                cycle,
+                                trace,
+                                maxEffectChain: options.maxEffectChain,
+                                queued: queued.slice(0, 50),
+                                queuedCount: queued.length,
+                                // Try to get causation for the last effect
+                                causalChain: effectuatedRoots.length > 0
+                                    ? getTriggerChain(batchQueue.all.get(effectuatedRoots[effectuatedRoots.length - 1]))
+                                    : [],
+                            };
+                            switch (options.maxEffectReaction) {
+                                case 'throw':
+                                    throw new ReactiveError(`[reactive] ${message}`, debugInfo);
+                                case 'debug':
+                                    // biome-ignore lint/suspicious/noDebugger: This is the whole point here
+                                    debugger;
+                                    throw new ReactiveError(`[reactive] ${message}`, debugInfo);
+                                case 'warn':
+                                    options.warn(`[reactive] ${message} (queued: ${queued.slice(0, 10).join(', ')}${queued.length > 10 ? ', …' : ''})`);
+                                    break;
+                            }
                         }
+                        const rv = executeNext(effectuatedRoots);
+                        // executeNext() returns null when batch is complete or cycle detected (throws error)
+                        // But functions can legitimately return null, so we check batchQueue.all.size instead
+                        if (batchQueue.all.size === 0) {
+                            // Batch complete
+                            break;
+                        }
+                        // If executeNext() returned null but batch is not empty, it means a cycle was detected
+                        // and an error was thrown, so we won't reach here
+                        if (rv !== undefined && !('value' in firstReturn))
+                            firstReturn.value = rv;
+                        // Note: executeNext() already removed it from batchQueue, so we track by count
                     }
-                    const rv = executeNext(effectuatedRoots);
-                    // executeNext() returns null when batch is complete or cycle detected (throws error)
-                    // But functions can legitimately return null, so we check batchQueue.all.size instead
-                    if (batchQueue.all.size === 0) {
-                        // Batch complete
-                        break;
+                    // Process cleanups. If they trigger new effects, the outer loop will catch them.
+                    if (batchCleanups.size > 0) {
+                        const cleanups = Array.from(batchCleanups);
+                        batchCleanups.clear();
+                        for (const cleanup of cleanups)
+                            cleanup();
                     }
-                    // If executeNext() returned null but batch is not empty, it means a cycle was detected
-                    // and an error was thrown, so we won't reach here
-                    if (rv !== undefined && !('value' in firstReturn))
-                        firstReturn.value = rv;
-                    // Note: executeNext() already removed it from batchQueue, so we track by count
                 }
-                const cleanups = Array.from(batchCleanups);
-                batchCleanups.clear();
-                for (const cleanup of cleanups)
-                    cleanup();
                 return firstReturn.value;
             }
             finally {
+                activationRegistry = undefined;
                 batchQueue = undefined;
                 options.endChain();
             }
@@ -2479,7 +2554,11 @@ function collectEffects(obj, evolution, effects, objectWatchers, ...keyChains) {
                         options.skipRunningEffect(effect, runningChain);
                         continue;
                     }
-                    effects.add(effect);
+                    if (!effects.has(effect)) {
+                        effects.add(effect);
+                        if (!hasBatched(effect))
+                            recordActivation(effect, obj, evolution, key);
+                    }
                     const trackers = effectTrackers.get(effect);
                     recordTriggerLink(sourceEffect, effect, obj, key, evolution);
                     if (trackers) {
@@ -2547,6 +2626,7 @@ function touchedOpaque(obj, evolution, prop) {
             continue;
         }
         effects.add(effect);
+        recordActivation(effect, obj, evolution, prop);
         const trackers = effectTrackers.get(effect);
         recordTriggerLink(sourceEffect, effect, obj, prop, evolution);
         if (trackers) {
@@ -2866,7 +2946,11 @@ const reactiveHandlers = {
                 dependant(current, prop);
                 if (Object.hasOwn(current, prop))
                     break;
-                current = reactiveObject(Object.getPrototypeOf(current));
+                let next = reactiveObject(Object.getPrototypeOf(current));
+                if (next === current) {
+                    next = reactiveObject(Object.getPrototypeOf(unwrap(current)));
+                }
+                current = next;
             }
         }
         const value = decorator.ReflectGet(obj, prop, receiver);
@@ -3331,7 +3415,6 @@ function* makeReactiveEntriesIterator(iterator) {
 const native$2 = Symbol('native');
 const isArray = Array.isArray;
 Array.isArray = ((value) => isArray(value) ||
-    // biome-ignore lint/suspicious/useIsArray: We are defining it
     (value &&
         typeof value === 'object' &&
         prototypeForwarding in value &&
@@ -4227,6 +4310,17 @@ function register(keyFn, initial) {
     return new RegisterClass(keyFn, initial);
 }
 
+/**
+ * Maps projection effects (item effects) to their projection context
+ */
+const effectProjectionMetadata = new WeakMap();
+/**
+ * Returns the projection context of the currently running effect, if any.
+ */
+function getActiveProjection() {
+    const active = getActiveEffect();
+    return active ? effectProjectionMetadata.get(active) : undefined;
+}
 function defineAccessValue(access) {
     Object.defineProperty(access, 'value', {
         get: access.get,
@@ -4235,7 +4329,15 @@ function defineAccessValue(access) {
         enumerable: true,
     });
 }
-function makeCleanup(target, effectMap, onDispose) {
+function makeCleanup(target, effectMap, onDispose, metadata) {
+    if (metadata) {
+        Object.defineProperty(target, projectionInfo, {
+            value: metadata,
+            writable: false,
+            enumerable: false,
+            configurable: true,
+        });
+    }
     return cleanedBy(target, () => {
         onDispose();
         for (const stop of effectMap.values())
@@ -4258,6 +4360,8 @@ function projectArray(source, apply) {
             Reflect.deleteProperty(target, index);
         }
     }
+    const parent = getActiveProjection();
+    const depth = parent ? parent.depth + 1 : 0;
     const cleanupLength = effect(function projectArrayLengthEffect({ ascend }) {
         const length = observedSource.length;
         normalizeTargetLength(length);
@@ -4280,6 +4384,14 @@ function projectArray(source, apply) {
                     const produced = apply(accessBase, target);
                     target[index] = produced;
                 });
+                setEffectName(stop, `project[${depth}]:${index}`);
+                effectProjectionMetadata.set(stop, {
+                    source: observedSource,
+                    key: index,
+                    target,
+                    depth,
+                    parent,
+                });
                 indexEffects.set(i, stop);
             });
         }
@@ -4287,7 +4399,13 @@ function projectArray(source, apply) {
             if (index >= length)
                 disposeIndex(index);
     });
-    return makeCleanup(target, indexEffects, () => cleanupLength());
+    return makeCleanup(target, indexEffects, () => cleanupLength(), {
+        source: observedSource,
+        target,
+        apply,
+        depth,
+        parent,
+    });
 }
 function projectRegister(source, apply) {
     const observedSource = reactive(source);
@@ -4302,6 +4420,8 @@ function projectRegister(source, apply) {
             target.delete(key);
         }
     }
+    const parent = getActiveProjection();
+    const depth = parent ? parent.depth + 1 : 0;
     const cleanupKeys = effect(function projectRegisterEffect({ ascend }) {
         const keys = new Set();
         for (const key of observedSource.mapKeys())
@@ -4326,6 +4446,14 @@ function projectRegister(source, apply) {
                     const produced = apply(accessBase, target);
                     target.set(key, produced);
                 });
+                setEffectName(stop, `project[${depth}]:${String(key)}`);
+                effectProjectionMetadata.set(stop, {
+                    source: observedSource,
+                    key,
+                    target,
+                    depth,
+                    parent,
+                });
                 keyEffects.set(key, stop);
             });
         }
@@ -4333,7 +4461,13 @@ function projectRegister(source, apply) {
             if (!keys.has(key))
                 disposeKey(key);
     });
-    return makeCleanup(target, keyEffects, () => cleanupKeys());
+    return makeCleanup(target, keyEffects, () => cleanupKeys(), {
+        source: observedSource,
+        target,
+        apply,
+        depth,
+        parent,
+    });
 }
 function projectRecord(source, apply) {
     const observedSource = reactive(source);
@@ -4347,6 +4481,8 @@ function projectRecord(source, apply) {
             Reflect.deleteProperty(target, key);
         }
     }
+    const parent = getActiveProjection();
+    const depth = parent ? parent.depth + 1 : 0;
     const cleanupKeys = effect(function projectRecordEffect({ ascend }) {
         const keys = new Set();
         for (const key in observedSource)
@@ -4372,6 +4508,14 @@ function projectRecord(source, apply) {
                     const produced = apply(accessBase, target);
                     target[sourceKey] = produced;
                 });
+                setEffectName(stop, `project[${depth}]:${String(key)}`);
+                effectProjectionMetadata.set(stop, {
+                    source: observedSource,
+                    key,
+                    target,
+                    depth,
+                    parent,
+                });
                 keyEffects.set(key, stop);
             });
         }
@@ -4379,7 +4523,13 @@ function projectRecord(source, apply) {
             if (!keys.has(key))
                 disposeKey(key);
     });
-    return makeCleanup(target, keyEffects, () => cleanupKeys());
+    return makeCleanup(target, keyEffects, () => cleanupKeys(), {
+        source: observedSource,
+        target,
+        apply,
+        depth,
+        parent,
+    });
 }
 function projectMap(source, apply) {
     const observedSource = reactive(source);
@@ -4394,6 +4544,8 @@ function projectMap(source, apply) {
             target.delete(key);
         }
     }
+    const parent = getActiveProjection();
+    const depth = parent ? parent.depth + 1 : 0;
     const cleanupKeys = effect(function projectMapEffect({ ascend }) {
         const keys = new Set();
         for (const key of observedSource.keys())
@@ -4418,6 +4570,14 @@ function projectMap(source, apply) {
                     const produced = apply(accessBase, target);
                     target.set(key, produced);
                 });
+                setEffectName(stop, `project[${depth}]:${String(key)}`);
+                effectProjectionMetadata.set(stop, {
+                    source: observedSource,
+                    key,
+                    target,
+                    depth,
+                    parent,
+                });
                 keyEffects.set(key, stop);
             });
         }
@@ -4425,7 +4585,13 @@ function projectMap(source, apply) {
             if (!keys.has(key))
                 disposeKey(key);
     });
-    return makeCleanup(target, keyEffects, () => cleanupKeys());
+    return makeCleanup(target, keyEffects, () => cleanupKeys(), {
+        source: observedSource,
+        target,
+        apply,
+        depth,
+        parent,
+    });
 }
 function projectCore(source, apply) {
     if (Array.isArray(source))
@@ -4573,7 +4739,7 @@ class ReactiveWeakMap {
         Object.defineProperties(this, {
             [native$1]: { value: original },
             [prototypeForwarding]: { value: original },
-            content: { value: Symbol('content') },
+            content: { value: Symbol('WeakMapContent') },
             [Symbol.toStringTag]: { value: 'ReactiveWeakMap' },
         });
     }
@@ -4613,7 +4779,7 @@ class ReactiveMap {
         Object.defineProperties(this, {
             [native$1]: { value: original },
             [prototypeForwarding]: { value: original },
-            content: { value: Symbol('content') },
+            content: { value: Symbol('MapContent') },
             [Symbol.toStringTag]: { value: 'ReactiveMap' },
         });
     }
@@ -4708,7 +4874,7 @@ class ReactiveWeakSet {
         Object.defineProperties(this, {
             [native]: { value: original },
             [prototypeForwarding]: { value: original },
-            content: { value: Symbol('content') },
+            content: { value: Symbol('WeakSetContent') },
             [Symbol.toStringTag]: { value: 'ReactiveWeakSet' },
         });
     }
@@ -4743,7 +4909,7 @@ class ReactiveSet {
         Object.defineProperties(this, {
             [native]: { value: original },
             [prototypeForwarding]: { value: original },
-            content: { value: Symbol('content') },
+            content: { value: Symbol('SetContent') },
             [Symbol.toStringTag]: { value: 'ReactiveSet' },
         });
     }
@@ -4847,6 +5013,7 @@ exports.ReadOnlyError = ReadOnlyError;
 exports.Register = Register;
 exports.addBatchCleanup = addBatchCleanup;
 exports.atomic = atomic;
+exports.batch = batch;
 exports.biDi = biDi;
 exports.buildReactivityGraph = buildReactivityGraph;
 exports.cleanedBy = cleanedBy;
@@ -4856,7 +5023,9 @@ exports.defer = defer;
 exports.derived = derived;
 exports.effect = effect;
 exports.enableDevTools = enableDevTools;
+exports.getActivationLog = getActivationLog;
 exports.getActiveEffect = getActiveEffect;
+exports.getActiveProjection = getActiveProjection;
 exports.getState = getState;
 exports.immutables = immutables;
 exports.isDevtoolsEnabled = isDevtoolsEnabled;
@@ -4888,4 +5057,4 @@ exports.unreactive = unreactive;
 exports.untracked = untracked;
 exports.unwrap = unwrap;
 exports.watch = watch;
-//# sourceMappingURL=index-HNVqPzjz.js.map
+//# sourceMappingURL=index-Cvxdw6Ax.js.map