@mmstack/primitives 20.4.4 → 20.4.6

package/fesm2022/mmstack-primitives.mjs

@@ -1,4 +1,5 @@
-import { untracked, signal, inject, DestroyRef, computed, PLATFORM_ID, isSignal, effect, ElementRef, linkedSignal, isDevMode, Injector, runInInjectionContext } from '@angular/core';
+import * as i0 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';
 
@@ -477,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. */
@@ -1293,6 +1429,122 @@ function stored(fallback, { key, store: providedStore, serialize = JSON.stringif
     return writable;
 }
 
+class MessageBus {
+    channel = new BroadcastChannel('mmstack-tab-sync-bus');
+    listeners = new Map();
+    subscribe(id, listener) {
+        this.unsubscribe(id); // Ensure no duplicate listeners
+        const wrapped = (ev) => {
+            try {
+                if (ev.data?.id === id)
+                    listener(ev.data?.value);
+            }
+            catch {
+                // noop
+            }
+        };
+        this.channel.addEventListener('message', wrapped);
+        this.listeners.set(id, wrapped);
+        return {
+            unsub: (() => this.unsubscribe(id)).bind(this),
+            post: ((value) => this.channel.postMessage({ id, value })).bind(this),
+        };
+    }
+    unsubscribe(id) {
+        const listener = this.listeners.get(id);
+        if (!listener)
+            return;
+        this.channel.removeEventListener('message', listener);
+        this.listeners.delete(id);
+    }
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "20.3.1", ngImport: i0, type: MessageBus, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
+    static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "20.3.1", ngImport: i0, type: MessageBus, providedIn: 'root' });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.1", ngImport: i0, type: MessageBus, decorators: [{
+            type: Injectable,
+            args: [{
+                    providedIn: 'root',
+                }]
+        }] });
+function generateDeterministicID() {
+    const stack = new Error().stack;
+    if (stack) {
+        // Look for the actual caller (first non-internal frame)
+        const lines = stack.split('\n');
+        for (let i = 2; i < lines.length; i++) {
+            const line = lines[i];
+            if (line && !line.includes('tabSync') && !line.includes('MessageBus')) {
+                let hash = 0;
+                for (let j = 0; j < line.length; j++) {
+                    const char = line.charCodeAt(j);
+                    hash = (hash << 5) - hash + char;
+                    hash = hash & hash;
+                }
+                return `auto-${Math.abs(hash)}`;
+            }
+        }
+    }
+    throw new Error('Could not generate deterministic ID, please provide one manually.');
+}
+/**
+ * Synchronizes a WritableSignal across browser tabs using BroadcastChannel API.
+ *
+ * Creates a shared signal that automatically syncs its value between all tabs
+ * of the same application. When the signal is updated in one tab, all other
+ * tabs will receive the new value automatically.
+ *
+ * @template T - The type of the WritableSignal
+ * @param sig - The WritableSignal to synchronize across tabs
+ * @param opt - Optional configuration object
+ * @param opt.id - Explicit channel ID for synchronization. If not provided,
+ *                 a deterministic ID is generated based on the call site.
+ *                 Use explicit IDs in production for reliability.
+ *
+ * @returns The same WritableSignal instance, now synchronized across tabs
+ *
+ * @throws {Error} When deterministic ID generation fails and no explicit ID is provided
+ *
+ * @example
+ * ```typescript
+ * // Basic usage - auto-generates channel ID from call site
+ * const theme = tabSync(signal('dark'));
+ *
+ * // With explicit ID (recommended for production)
+ * const userPrefs = tabSync(signal({ lang: 'en' }), { id: 'user-preferences' });
+ *
+ * // Changes in one tab will sync to all other tabs
+ * theme.set('light'); // All tabs will update to 'light'
+ * ```
+ *
+ * @remarks
+ * - Only works in browser environments (returns original signal on server)
+ * - Uses a single BroadcastChannel for all synchronized signals
+ * - Automatically cleans up listeners when the injection context is destroyed
+ * - Initial signal value after sync setup is not broadcasted to prevent loops
+ *
+ */
+function tabSync(sig, opt) {
+    if (isPlatformServer(inject(PLATFORM_ID)))
+        return sig;
+    const id = opt?.id || generateDeterministicID();
+    const bus = inject(MessageBus);
+    const { unsub, post } = bus.subscribe(id, (next) => sig.set(next));
+    let first = false;
+    const effectRef = effect(() => {
+        const val = sig();
+        if (!first) {
+            first = true;
+            return;
+        }
+        post(val);
+    }, ...(ngDevMode ? [{ debugName: "effectRef" }] : []));
+    inject(DestroyRef).onDestroy(() => {
+        effectRef.destroy();
+        unsub();
+    });
+    return sig;
+}
+
 function until(sourceSignal, predicate, options = {}) {
     const injector = options.injector ?? inject(Injector);
     return new Promise((resolve, reject) => {
@@ -1491,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, 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