@mmstack/primitives 21.0.8 → 21.0.10

package/fesm2022/mmstack-primitives.mjs

@@ -1,5 +1,5 @@
 import * as i0 from '@angular/core';
-import { computed, untracked, signal, inject, DestroyRef, isWritableSignal as isWritableSignal$1, isSignal, linkedSignal, isDevMode, Injector, effect, ElementRef, PLATFORM_ID, Injectable, runInInjectionContext } from '@angular/core';
+import { computed, untracked, signal, inject, DestroyRef, isDevMode, Injector, effect, runInInjectionContext, isWritableSignal as isWritableSignal$1, isSignal, linkedSignal, ElementRef, PLATFORM_ID, Injectable } from '@angular/core';
 import { isPlatformServer } from '@angular/common';
 import { SIGNAL } from '@angular/core/primitives/signals';
 
@@ -289,6 +289,252 @@ function isDerivation(sig) {
     return 'from' in sig;
 }
 
+const frameStack = [];
+function currentFrame() {
+    return frameStack.at(-1) ?? null;
+}
+function clearFrame(frame, userCleanups) {
+    frame.parent = null;
+    for (const fn of userCleanups) {
+        try {
+            fn();
+        }
+        catch (e) {
+            if (isDevMode())
+                console.error('Error destroying nested effect:', e);
+        }
+    }
+    userCleanups.length = 0;
+    for (const child of frame.children) {
+        try {
+            child.destroy();
+        }
+        catch (e) {
+            if (isDevMode())
+                console.error('Error destroying nested effect:', e);
+        }
+    }
+    frame.children.clear();
+}
+function pushFrame(frame) {
+    return frameStack.push(frame);
+}
+function popFrame() {
+    return frameStack.pop();
+}
+
+/**
+ * Creates an effect that can be nested, similar to SolidJS's `createEffect`.
+ *
+ * This primitive enables true hierarchical reactivity. A `nestedEffect` created
+ * within another `nestedEffect` is automatically destroyed and recreated when
+ * the parent re-runs.
+ *
+ * It automatically handles injector propagation and lifetime management, allowing
+ * you to create fine-grained, conditional side-effects that only track
+ * dependencies when they are "live".
+ *
+ * @param effectFn The side-effect function, which receives a cleanup register function.
+ * @param options (Optional) Angular's `CreateEffectOptions`.
+ * @returns An `EffectRef` for the created effect.
+ *
+ * @example
+ * ```ts
+ * // Assume `coldGuard` changes rarely, but `hotSignal` changes often.
+ * const coldGuard = signal(false);
+ * const hotSignal = signal(0);
+ *
+ * nestedEffect(() => {
+ * // This outer effect only tracks `coldGuard`.
+ * if (coldGuard()) {
+ *
+ * // This inner effect is CREATED when coldGuard is true
+ * // and DESTROYED when it becomes false.
+ * nestedEffect(() => {
+ * // It only tracks `hotSignal` while it exists.
+ * console.log('Hot signal is:', hotSignal());
+ * });
+ * }
+ * // If `coldGuard` is false, this outer effect does not track `hotSignal`.
+ * });
+ * ```
+ * @example
+ * ```ts
+ * const users = signal([
+ *   { id: 1, name: 'Alice' },
+ *   { id: 2, name: 'Bob' }
+ * ]);
+ *
+ * // The fine-grained mapped list
+ * const mappedUsers = mapArray(
+ *   users,
+ *   (userSignal, index) => {
+ *     // 1. Create a fine-grained SIDE EFFECT for *this item*
+ *     // This effect's lifetime is now tied to this specific item. created once on init of this index.
+ *     const effectRef = nestedEffect(() => {
+ *       // This only runs if *this* userSignal changes,
+ *       // not if the whole list changes.
+ *       console.log(`User ${index} updated:`, userSignal().name);
+ *     });
+ *
+ *     // 2. Return the data AND the cleanup logic
+ *     return {
+ *       // The mapped data
+ *       label: computed(() => `User: ${userSignal().name}`),
+ *
+ *       // The cleanup function
+ *       destroyEffect: () => effectRef.destroy()
+ *     };
+ *   },
+ *   {
+ *     // 3. Tell mapArray HOW to clean up when an item is removed, this needs to be manual as it's not a nestedEffect itself
+ *     onDestroy: (mappedItem) => {
+ *       mappedItem.destroyEffect();
+ *     }
+ *   }
+ * );
+ * ```
+ */
+function nestedEffect(effectFn, options) {
+    const bindToFrame = options?.bindToFrame ?? ((parent) => parent);
+    const parent = bindToFrame(currentFrame());
+    const injector = options?.injector ?? parent?.injector ?? inject(Injector);
+    let isDestroyed = false;
+    const srcRef = untracked(() => {
+        return effect((cleanup) => {
+            if (isDestroyed)
+                return;
+            const frame = {
+                injector,
+                parent,
+                children: new Set(),
+            };
+            const userCleanups = [];
+            pushFrame(frame);
+            try {
+                effectFn((fn) => {
+                    userCleanups.push(fn);
+                });
+            }
+            finally {
+                popFrame();
+            }
+            return cleanup(() => clearFrame(frame, userCleanups));
+        }, {
+            ...options,
+            injector,
+            manualCleanup: !!parent,
+        });
+    });
+    const ref = {
+        ...srcRef,
+        destroy: () => {
+            if (isDestroyed)
+                return;
+            isDestroyed = true;
+            parent?.children.delete(ref);
+            srcRef.destroy();
+        },
+    };
+    parent?.children.add(ref);
+    if (parent === null)
+        injector.get(DestroyRef).onDestroy(() => ref.destroy());
+    return ref;
+}
+
+let isBatching = false;
+const pendingEffects = new Set();
+function batch(fn) {
+    if (isBatching)
+        return fn();
+    isBatching = true;
+    try {
+        fn();
+    }
+    finally {
+        isBatching = false;
+        for (const run of pendingEffects) {
+            pendingEffects.delete(run);
+            run();
+        }
+    }
+}
+const ALWAYS_FALSE = () => false;
+/**
+ * A synchronous version of Angular's effect, optimized for DOM-heavy renderers.
+ * Runs immediately on creation and on dependency changes, bypassing the microtask queue.
+ * * @example
+ * renderEffect((onCleanup) => {
+ * const el = document.createElement('div');
+ * el.textContent = count();
+ * container.appendChild(el);
+ * onCleanup(() => el.remove());
+ * });
+ */
+function renderEffect(effectFn, options) {
+    const parent = currentFrame();
+    const injector = options?.injector ?? parent?.injector ?? inject(Injector);
+    let cleanupFn;
+    let isDestroyed = false;
+    const tracker = computed(() => {
+        if (cleanupFn) {
+            try {
+                cleanupFn();
+            }
+            catch {
+                // noop
+            }
+            cleanupFn = undefined;
+        }
+        const frame = {
+            injector,
+            parent,
+            children: new Set(),
+        };
+        const userCleanups = [];
+        pushFrame(frame);
+        try {
+            effectFn((fn) => userCleanups.push(fn));
+        }
+        finally {
+            popFrame();
+            cleanupFn = () => clearFrame(frame, userCleanups);
+        }
+    }, { ...(ngDevMode ? { debugName: "tracker" } : {}), equal: ALWAYS_FALSE });
+    const run = (isFromBridge = false) => {
+        if (isDestroyed)
+            return;
+        if (isBatching && !isFromBridge) {
+            pendingEffects.add(run);
+            return;
+        }
+        tracker();
+    };
+    let rootEffectRef = null;
+    const ref = {
+        run,
+        destroy: () => {
+            if (isDestroyed)
+                return;
+            isDestroyed = true;
+            rootEffectRef?.destroy();
+            parent?.children.delete(ref);
+            pendingEffects.delete(run);
+            if (cleanupFn)
+                cleanupFn();
+        },
+    };
+    parent?.children.add(ref);
+    if (parent === null) {
+        rootEffectRef = runInInjectionContext(injector, () => untracked(() => effect(() => run(true), { injector, manualCleanup: true })));
+        injector.get(DestroyRef).onDestroy(() => ref.destroy());
+    }
+    else {
+        untracked(() => run(true));
+    }
+    return ref;
+}
+
 function isWritableSignal(value) {
     return isWritableSignal$1(value);
 }
@@ -429,7 +675,6 @@ function keyArray(source, mapFn, options = {}) {
                 }
                 return mapped;
             }
-            // Fast path for new create (init)
             if (len === 0) {
                 for (j = 0; j < newLen; j++) {
                     item = newItems[j];
@@ -444,19 +689,16 @@ function keyArray(source, mapFn, options = {}) {
                 temp.length = 0;
                 tempIndexes.length = 0;
                 newIndicesNext.length = 0;
-                // Skip common prefix
                 for (start = 0, end = Math.min(len, newLen); start < end && getKey(items[start]) === getKey(newItems[start]); start++) {
                     newMapped[start] = mapped[start];
                     newIndexes[start] = indexes[start];
                 }
-                // Common suffix
                 for (end = len - 1, newEnd = newLen - 1; end >= start &&
                     newEnd >= start &&
                     getKey(items[end]) === getKey(newItems[newEnd]); end--, newEnd--) {
                     temp[newEnd] = mapped[end];
                     tempIndexes[newEnd] = indexes[end];
                 }
-                // 0) Prepare a map of all indices in newItems, scanning backwards
                 for (j = newEnd; j >= start; j--) {
                     item = newItems[j];
                     key = getKey(item);
@@ -464,7 +706,6 @@ function keyArray(source, mapFn, options = {}) {
                     newIndicesNext[j] = i === undefined ? -1 : i;
                     newIndices.set(key, j);
                 }
-                // 1) Step through old items: check if they are in new set
                 for (i = start; i <= end; i++) {
                     item = items[i];
                     key = getKey(item);
@@ -482,10 +723,10 @@ function keyArray(source, mapFn, options = {}) {
                 }
                 // 2) Set all new values
                 for (j = start; j < newLen; j++) {
-                    if (j in temp) {
+                    if (temp[j] !== undefined) {
                         newMapped[j] = temp[j];
                         newIndexes[j] = tempIndexes[j];
-                        untracked(() => newIndexes[j].set(j)); // Update index signal
+                        newIndexes[j].set(j);
                     }
                     else {
                         const indexSignal = signal(j, ...(ngDevMode ? [{ debugName: "indexSignal" }] : []));
@@ -493,7 +734,6 @@ function keyArray(source, mapFn, options = {}) {
                         newMapped[j] = mapFn(newItems[j], indexSignal);
                     }
                 }
-                // 4) Save items for next update
                 items.length = newLen;
                 for (let k = 0; k < newLen; k++)
                     items[k] = newItems[k];
@@ -551,144 +791,6 @@ function mapObject(source, mapFn, options = {}) {
     }).asReadonly();
 }
 
-const frameStack = [];
-function current() {
-    return frameStack.at(-1) ?? null;
-}
-function clearFrame(frame, userCleanups) {
-    frame.parent = null;
-    for (const child of frame.children) {
-        try {
-            child.destroy();
-        }
-        catch (e) {
-            if (isDevMode())
-                console.error('Error destroying nested effect:', e);
-        }
-    }
-    frame.children.clear();
-    for (const fn of userCleanups) {
-        try {
-            fn();
-        }
-        catch (e) {
-            if (isDevMode())
-                console.error('Error destroying nested effect:', e);
-        }
-    }
-    userCleanups.length = 0;
-}
-/**
- * Creates an effect that can be nested, similar to SolidJS's `createEffect`.
- *
- * This primitive enables true hierarchical reactivity. A `nestedEffect` created
- * within another `nestedEffect` is automatically destroyed and recreated when
- * the parent re-runs.
- *
- * It automatically handles injector propagation and lifetime management, allowing
- * you to create fine-grained, conditional side-effects that only track
- * dependencies when they are "live".
- *
- * @param effectFn The side-effect function, which receives a cleanup register function.
- * @param options (Optional) Angular's `CreateEffectOptions`.
- * @returns An `EffectRef` for the created effect.
- *
- * @example
- * ```ts
- * // Assume `coldGuard` changes rarely, but `hotSignal` changes often.
- * const coldGuard = signal(false);
- * const hotSignal = signal(0);
- *
- * nestedEffect(() => {
- * // This outer effect only tracks `coldGuard`.
- * if (coldGuard()) {
- *
- * // This inner effect is CREATED when coldGuard is true
- * // and DESTROYED when it becomes false.
- * nestedEffect(() => {
- * // It only tracks `hotSignal` while it exists.
- * console.log('Hot signal is:', hotSignal());
- * });
- * }
- * // If `coldGuard` is false, this outer effect does not track `hotSignal`.
- * });
- * ```
- * @example
- * ```ts
- * const users = signal([
- *   { id: 1, name: 'Alice' },
- *   { id: 2, name: 'Bob' }
- * ]);
- *
- * // The fine-grained mapped list
- * const mappedUsers = mapArray(
- *   users,
- *   (userSignal, index) => {
- *     // 1. Create a fine-grained SIDE EFFECT for *this item*
- *     // This effect's lifetime is now tied to this specific item. created once on init of this index.
- *     const effectRef = nestedEffect(() => {
- *       // This only runs if *this* userSignal changes,
- *       // not if the whole list changes.
- *       console.log(`User ${index} updated:`, userSignal().name);
- *     });
- *
- *     // 2. Return the data AND the cleanup logic
- *     return {
- *       // The mapped data
- *       label: computed(() => `User: ${userSignal().name}`),
- *
- *       // The cleanup function
- *       destroyEffect: () => effectRef.destroy()
- *     };
- *   },
- *   {
- *     // 3. Tell mapArray HOW to clean up when an item is removed, this needs to be manual as it's not a nestedEffect itself
- *     onDestroy: (mappedItem) => {
- *       mappedItem.destroyEffect();
- *     }
- *   }
- * );
- * ```
- */
-function nestedEffect(effectFn, options) {
-    const bindToFrame = options?.bindToFrame ?? ((parent) => parent);
-    const parent = bindToFrame(current());
-    const injector = options?.injector ?? parent?.injector ?? inject(Injector);
-    const srcRef = untracked(() => {
-        return effect((cleanup) => {
-            const frame = {
-                injector,
-                parent,
-                children: new Set(),
-            };
-            const userCleanups = [];
-            frameStack.push(frame);
-            try {
-                effectFn((fn) => {
-                    userCleanups.push(fn);
-                });
-            }
-            finally {
-                frameStack.pop();
-            }
-            return cleanup(() => clearFrame(frame, userCleanups));
-        }, {
-            ...options,
-            injector,
-            manualCleanup: !!parent,
-        });
-    });
-    const ref = {
-        ...srcRef,
-        destroy: () => {
-            parent?.children.delete(ref);
-            srcRef.destroy();
-        },
-    };
-    parent?.children.add(ref);
-    return ref;
-}
-
 /** Project with optional equality. Pure & sync. */
 const select = (projector, opt) => (src) => computed(() => projector(src()), opt);
 /** Combine with another signal using a projector. */
@@ -2140,5 +2242,5 @@ function withHistory(source, opt) {
  * Generated bundle index. Do not edit.
  */
 
-export { combineWith, debounce, debounced, derived, distinct, elementSize, elementVisibility, filter, indexArray, isDerivation, isMutable, keyArray, map, mapArray, mapObject, mediaQuery, mousePosition, mutable, mutableStore, nestedEffect, networkStatus, pageVisibility, pipeable, piped, prefersDarkMode, prefersReducedMotion, scrollPosition, select, sensor, sensors, store, stored, tabSync, tap, throttle, throttled, toFakeDerivation, toFakeSignalDerivation, toStore, toWritable, until, windowSize, withHistory };
+export { batch, combineWith, debounce, debounced, derived, distinct, elementSize, elementVisibility, filter, indexArray, isDerivation, isMutable, keyArray, map, mapArray, mapObject, mediaQuery, mousePosition, mutable, mutableStore, nestedEffect, networkStatus, pageVisibility, pipeable, piped, prefersDarkMode, prefersReducedMotion, renderEffect, scrollPosition, select, sensor, sensors, store, stored, tabSync, tap, throttle, throttled, toFakeDerivation, toFakeSignalDerivation, toStore, toWritable, until, windowSize, withHistory };
 //# sourceMappingURL=mmstack-primitives.mjs.map