@mmstack/primitives 21.0.12 → 21.0.14

package/fesm2022/mmstack-primitives.mjs

@@ -1,8 +1,214 @@
 import * as i0 from '@angular/core';
-import { computed, untracked, signal, inject, DestroyRef, isDevMode, Injector, effect, isWritableSignal as isWritableSignal$1, isSignal, linkedSignal, ElementRef, PLATFORM_ID, Injectable, runInInjectionContext } from '@angular/core';
+import { isDevMode, inject, Injector, untracked, effect, DestroyRef, linkedSignal, computed, signal, isWritableSignal as isWritableSignal$1, isSignal, ElementRef, PLATFORM_ID, Injectable, runInInjectionContext } from '@angular/core';
 import { isPlatformServer } from '@angular/common';
 import { SIGNAL } from '@angular/core/primitives/signals';
 
+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: options?.manualCleanup ?? !!parent,
+        });
+    });
+    const ref = {
+        destroy: () => {
+            if (isDestroyed)
+                return;
+            isDestroyed = true;
+            parent?.children.delete(ref);
+            srcRef.destroy();
+        },
+    };
+    parent?.children.add(ref);
+    injector.get(DestroyRef).onDestroy(() => ref.destroy());
+    return ref;
+}
+
+/**
+ * Creates a new `Signal` that processes an array of items in time-sliced chunks. This is useful for handling large lists without blocking the main thread.
+ *
+ * The returned signal will initially contain the first `chunkSize` items from the source array. It will then schedule updates to include additional chunks of items based on the specified `duration`.
+ *
+ * @template T The type of items in the array.
+ * @param source A `Signal` or a function that returns an array of items to be processed in chunks.
+ * @param options Configuration options for chunk size, delay duration, equality function, and injector.
+ * @returns A `Signal` that emits the current chunk of items being processed.
+ *
+ * @example
+ * const largeList = signal(Array.from({ length: 1000 }, (_, i) => i));
+ * const chunkedList = chunked(largeList, { chunkSize: 100, duration: 100 });
+ */
+function chunked(source, options) {
+    const { chunkSize = 50, delay = 'frame', equal, injector } = options || {};
+    let delayFn;
+    if (delay === 'frame') {
+        delayFn = (callback) => {
+            const num = requestAnimationFrame(callback);
+            return () => cancelAnimationFrame(num);
+        };
+    }
+    else if (delay === 'microtask') {
+        delayFn = (cb) => {
+            let isCancelled = false;
+            queueMicrotask(() => {
+                if (isCancelled)
+                    return;
+                cb();
+            });
+            return () => {
+                isCancelled = true;
+            };
+        };
+    }
+    else {
+        delayFn = (cb) => {
+            const num = setTimeout(cb, delay);
+            return () => clearTimeout(num);
+        };
+    }
+    const internal = linkedSignal({ ...(ngDevMode ? { debugName: "internal" } : {}), source,
+        computation: (items) => items.slice(0, chunkSize),
+        equal });
+    nestedEffect((cleanup) => {
+        const fullList = source();
+        const current = internal();
+        if (current.length >= fullList.length)
+            return;
+        return cleanup(delayFn(() => untracked(() => internal.set(fullList.slice(0, current.length + chunkSize)))));
+    }, {
+        injector: injector,
+    });
+    return internal.asReadonly();
+}
+
 /**
  * Converts a read-only `Signal` into a `WritableSignal` by providing custom `set` and, optionally, `update` functions.
  * This can be useful for creating controlled write access to a signal that is otherwise read-only.
@@ -115,19 +321,19 @@ function debounce(source, opt) {
     catch {
         // not in injection context & no destroyRef provided opting out of cleanup
     }
-    const triggerFn = (afterClean) => {
+    const triggerFn = (next) => {
         if (timeout)
             clearTimeout(timeout);
-        afterClean();
+        source.set(next);
         timeout = setTimeout(() => {
             trigger.update((c) => !c);
         }, ms);
     };
     const set = (value) => {
-        triggerFn(() => source.set(value));
+        triggerFn(value);
     };
     const update = (fn) => {
-        triggerFn(() => source.update(fn));
+        triggerFn(fn(untracked(source)));
     };
     const writable = toWritable(computed(() => {
         trigger();
@@ -289,155 +495,6 @@ 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: options?.manualCleanup ?? !!parent,
-        });
-    });
-    const ref = {
-        destroy: () => {
-            if (isDestroyed)
-                return;
-            isDestroyed = true;
-            parent?.children.delete(ref);
-            srcRef.destroy();
-        },
-    };
-    parent?.children.add(ref);
-    injector.get(DestroyRef).onDestroy(() => ref.destroy());
-    return ref;
-}
-
 function isWritableSignal(value) {
     return isWritableSignal$1(value);
 }
@@ -1149,8 +1206,7 @@ function throttle(source, opt) {
     catch {
         // not in injection context & no destroyRef provided opting out of cleanup
     }
-    const triggerFn = (updateSourceAction) => {
-        updateSourceAction();
+    const tick = () => {
         if (timeout)
             return;
         timeout = setTimeout(() => {
@@ -1159,10 +1215,12 @@ function throttle(source, opt) {
         }, ms);
     };
     const set = (value) => {
-        triggerFn(() => source.set(value));
+        source.set(value);
+        tick();
     };
     const update = (fn) => {
-        triggerFn(() => source.update(fn));
+        source.update(fn);
+        tick();
     };
     const writable = toWritable(computed(() => {
         trigger();
@@ -1576,6 +1634,14 @@ const SIGNAL_FN_PROP = new Set([
     'inline',
     'asReadonly',
 ]);
+/**
+ * Validates whether a value is a Signal Store.
+ */
+function isStore(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        value[IS_STORE] === true);
+}
 /**
  * @experimental This API is experimental and may change or be removed in future releases.
  * Converts a Signal into a deep-observable Store.
@@ -1585,7 +1651,7 @@ const SIGNAL_FN_PROP = new Set([
  * const nameSignal = state.user.name; // WritableSignal<string>
  */
 function toStore(source, injector) {
-    if (source[IS_STORE])
+    if (isStore(source))
         return source;
     if (!injector)
         injector = inject(Injector);
@@ -2145,5 +2211,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 { chunked, combineWith, debounce, debounced, derived, distinct, elementSize, elementVisibility, filter, indexArray, isDerivation, isMutable, isStore, 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 };
 //# sourceMappingURL=mmstack-primitives.mjs.map