@mmstack/primitives 20.4.5 → 20.4.7

package/README.md

@@ -22,6 +22,7 @@ This library provides the following primitives:
 - `piped` – Creates a signal with a chainable & typesafe `.pipe(...)` method, which returns a pipable computed.
 - `withHistory` - Enhances a signal with a complete undo/redo history stack.
 - `mapArray` - Maps a reactive array efficently into an array of stable derivations.
+- `nestedEffect` - Creates an effect with a hierarchical lifetime, enabling fine-grained, conditional side-effects.
 - `toWritable` - Converts a read-only signal to writable using custom write logic.
 - `derived` - Creates a signal with two-way binding to a source signal.
 - `sensor` - A facade function to create various reactive sensor signals (e.g., mouse position, network status, page visibility, dark mode preference)." (This was the suggestion from before; it just reads a little smoother and more accurately reflects what the facade creates directly).
@@ -318,6 +319,95 @@ export class ListComponent {
 }
 ```
 
+### nestedEffect
+
+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". This is a powerful optimization for scenarios where a "hot" signal (which changes often) should only be tracked when a "cold" signal (a condition that changes rarely) is true.
+
+```ts
+import { Component, signal } from '@angular/core';
+import { nestedEffect } from '@mmstack/primitives';
+
+@Component({ selector: 'app-nested-demo' })
+export class NestedDemoComponent {
+  // `coldGuard` changes rarely
+  readonly coldGuard = signal(false);
+  // `hotSignal` changes very often
+  readonly hotSignal = signal(0);
+
+  constructor() {
+    // A standard effect would track *both* signals and run
+    // every time `hotSignal` changes, even if `coldGuard` is false.
+    // effect(() => {
+    //   if (this.coldGuard()) {
+    //     console.log('Hot signal is:', this.hotSignal());
+    //   }
+    // });
+
+    // `nestedEffect` solves this:
+    nestedEffect(() => {
+      // This outer effect ONLY tracks `coldGuard`.
+      // It does not track `hotSignal`.
+      if (this.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:', this.hotSignal());
+        });
+      }
+    });
+  }
+}
+```
+
+#### Advanced Example: Fine-grained Lists
+
+`nestedEffect` can be composed with `mapArray` to create truly fine-grained reactive lists, where each item can manage its own side-effects (like external library integrations) that are automatically cleaned up when the item is removed.
+
+```ts
+import { Component, signal, computed } from '@angular/core';
+import { mapArray, nestedEffect } from '@mmstack/primitives';
+
+@Component({ selector: 'app-list-demo' })
+export class ListDemoComponent {
+  readonly users = signal([
+    { id: 1, name: 'Alice' },
+    { id: 2, name: 'Bob' },
+  ]);
+
+  // mapArray creates stable signals for each item
+  readonly mappedUsers = mapArray(
+    this.users,
+    (userSignal, index) => {
+      // Create a side-effect tied to THIS item's lifetime
+      const effectRef = nestedEffect(() => {
+        // This only runs if `userSignal` (this specific user) changes.
+        console.log(`User ${index} updated:`, userSignal().name);
+
+        // e.g., updateAGGridRow(index, userSignal());
+      });
+
+      // Return the data and the cleanup logic
+      return {
+        label: computed(() => `User: ${userSignal().name}`),
+        // This function will be called by `onDestroy`
+        _destroy: () => effectRef.destroy(),
+      };
+    },
+    {
+      // When mapArray removes an item, it calls `onDestroy`
+      onDestroy: (mappedItem) => {
+        mappedItem._destroy(); // Manually destroy the nested effect
+      },
+    },
+  );
+}
+```
+
 ### toWritable
 
 A utility function that converts a read-only Signal into a WritableSignal by allowing you to provide custom implementations for the .set() and .update() methods. This is useful for creating controlled write access to signals that are naturally read-only (like those created by computed). This is used under the hood in derived.

package/fesm2022/mmstack-primitives.mjs

@@ -1,5 +1,5 @@
 import * as i0 from '@angular/core';
-import { untracked, signal, inject, DestroyRef, computed, PLATFORM_ID, isSignal, effect, ElementRef, linkedSignal, isDevMode, Injectable, Injector, runInInjectionContext } from '@angular/core';
+import { untracked, signal, inject, DestroyRef, computed, PLATFORM_ID, isSignal, effect, ElementRef, linkedSignal, isDevMode, Injector, Injectable, runInInjectionContext } from '@angular/core';
 import { isPlatformServer } from '@angular/common';
 import { SIGNAL } from '@angular/core/primitives/signals';
 
@@ -478,6 +478,141 @@ function mapArray(source, map, options) {
     });
 }
 
+const frameStack = [];
+function current() {
+    return frameStack.at(-1) ?? null;
+}
+function clearFrame(frame, userCleanups) {
+    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 parent = current();
+    const injector = options?.injector ?? parent?.injector ?? inject(Injector);
+    const srcRef = untracked(() => {
+        return effect((cleanup) => {
+            const frame = {
+                injector,
+                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. */
@@ -1608,5 +1743,5 @@ function withHistory(source, opt) {
  * Generated bundle index. Do not edit.
  */
 
-export { combineWith, debounce, debounced, derived, distinct, elementVisibility, filter, isDerivation, isMutable, map, mapArray, mediaQuery, mousePosition, mutable, networkStatus, pageVisibility, pipeable, piped, prefersDarkMode, prefersReducedMotion, scrollPosition, select, sensor, stored, tabSync, tap, throttle, throttled, toFakeDerivation, toFakeSignalDerivation, toWritable, until, windowSize, withHistory };
+export { combineWith, debounce, debounced, derived, distinct, elementVisibility, filter, isDerivation, isMutable, map, mapArray, mediaQuery, mousePosition, mutable, nestedEffect, networkStatus, pageVisibility, pipeable, piped, prefersDarkMode, prefersReducedMotion, scrollPosition, select, sensor, stored, tabSync, tap, throttle, throttled, toFakeDerivation, toFakeSignalDerivation, toWritable, until, windowSize, withHistory };
 //# sourceMappingURL=mmstack-primitives.mjs.map