mutts 1.0.4 → 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-GRBSx0mB.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
@@ -1974,6 +2031,10 @@ function batch(effect, immediate) {
     }
     else {
         // New batch - initialize
+        if (!activationRegistry)
+            activationRegistry = new Map();
+        else
+            throw new Error('Batch already in progress');
         options.beginChain(roots);
         batchQueue = {
             all: new Map(),
@@ -2052,6 +2113,7 @@ function batch(effect, immediate) {
                 return firstReturn.value;
             }
             finally {
+                activationRegistry = undefined;
                 batchQueue = undefined;
                 options.endChain();
             }
@@ -2122,6 +2184,7 @@ function batch(effect, immediate) {
                 return firstReturn.value;
             }
             finally {
+                activationRegistry = undefined;
                 batchQueue = undefined;
                 options.endChain();
             }
@@ -2491,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) {
@@ -2559,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) {
@@ -3347,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 &&
@@ -4243,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,
@@ -4251,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())
@@ -4274,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);
@@ -4296,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);
             });
         }
@@ -4303,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);
@@ -4318,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())
@@ -4342,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);
             });
         }
@@ -4349,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);
@@ -4363,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)
@@ -4388,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);
             });
         }
@@ -4395,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);
@@ -4410,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())
@@ -4434,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);
             });
         }
@@ -4441,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))
@@ -4589,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' },
         });
     }
@@ -4629,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' },
         });
     }
@@ -4724,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' },
         });
     }
@@ -4759,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' },
         });
     }
@@ -4873,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;
@@ -4905,4 +5057,4 @@ exports.unreactive = unreactive;
 exports.untracked = untracked;
 exports.unwrap = unwrap;
 exports.watch = watch;
-//# sourceMappingURL=index-GRBSx0mB.js.map
+//# sourceMappingURL=index-Cvxdw6Ax.js.map