@mmstack/primitives 20.4.5 → 20.4.6

package/index.d.ts

@@ -1,4 +1,4 @@
-import { CreateSignalOptions, DestroyRef, WritableSignal, Signal, ElementRef, Injector, ValueEqualityFn } from '@angular/core';
+import { CreateSignalOptions, DestroyRef, WritableSignal, Signal, ElementRef, EffectCleanupRegisterFn, CreateEffectOptions, Injector, ValueEqualityFn } from '@angular/core';
 
 /**
  * Options for creating a debounced writable signal.
@@ -468,6 +468,82 @@ declare function mapArray<T, U>(source: Signal<T[]> | (() => T[]), map: (value:
     onDestroy?: (value: U) => void;
 }): Signal<U[]>;
 
+/**
+ * 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();
+    }
+  }
+);
+ * ```
+ */
+declare function nestedEffect(effectFn: (registerCleanup: EffectCleanupRegisterFn) => void, options?: CreateEffectOptions): {
+    destroy: () => void;
+};
+
 /**
  * A pure, synchronous transform from I -> O.
  * Prefer transforms without side effects to keep derivations predictable.
@@ -1456,5 +1532,5 @@ type CreateHistoryOptions<T> = Omit<CreateSignalOptions<T[]>, 'equal'> & {
  */
 declare function withHistory<T>(source: WritableSignal<T>, opt?: CreateHistoryOptions<T>): SignalWithHistory<T>;
 
-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 };
 export type { CreateDebouncedOptions, CreateHistoryOptions, CreateStoredOptions, CreateThrottledOptions, DebouncedSignal, DerivedSignal, ElementVisibilityOptions, ElementVisibilitySignal, MousePositionOptions, MousePositionSignal, MutableSignal, NetworkStatusSignal, PipeableSignal, ScrollPosition, ScrollPositionOptions, ScrollPositionSignal, SignalWithHistory, StoredSignal, ThrottledSignal, UntilOptions, WindowSize, WindowSizeOptions, WindowSizeSignal };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mmstack/primitives",
-  "version": "20.4.5",
+  "version": "20.4.6",
   "keywords": [
     "angular",
     "signals",