@mmstack/primitives 20.4.3 → 20.4.5

package/README.md

@@ -214,40 +214,30 @@ export class ThemeSelectorComponent {
 
 ### piped
 
-Adds a chainable .pipe(...) method to signals, allowing you to compose pure, synchronous transforms into reactive pipelines. Each .pipe(...) call returns a computed signal that is itself pipeable, so you can keep chaining.
+Adds two fluent APIs to signals:
 
-```typescript
-import { Component, effect } from '@angular/core';
-import { piped, pipeable } from '@mmstack/primitives';
+- **`.map(...transforms, [options])`** – compose pure, synchronous value→value transforms. Returns a computed signal that remains pipeable.
+- **`.pipe(...operators)`** – compose operators (signal→signal), useful for combining signals or reusable projections.
 
-@Component({
-  selector: 'app-pipeable',
-  template: `<button (click)="increment()">Increment</button>`,
-})
-export class PipeableComponent {
-  count = piped(1);
+```typescript
+import { piped, pipeable, select, combineWith } from '@mmstack/primitives';
+import { signal } from '@angular/core';
 
-  // Create a derived pipeline
-  label = this.count.pipe(
-    (n) => n * 2, // number -> number
-    (n) => `#${n}`, // number -> string
-  );
+const count = piped(1);
 
-  constructor() {
-    effect(() => {
-      console.log('Label:', this.label()); // e.g., "#2"
-    });
-  }
+// Map: value -> value
+const label = count.map(
+  (n) => n * 2,
+  (n) => (num: n),
+  { equal: (a, b) => a.num === b.num },
+);
 
-  increment() {
-    this.count.update((n) => n + 1);
-  }
-}
+// Pipe: signal -> signal
+const base = pipeable(signal(10));
+const total = count.pipe(select((n) => n * 3)).pipe(combineWith(count, (a, b) => a + b));
 
-// You can also transform existing signals into pipable versions
-const example = pipeable(computed(() => 1)); // PipeableSignal<number> (a readonly signal + pipe)
-const example2 = pipeable(signal(1)); // PipeableSignal<number, WritableSignal<number>> (a writable signal + pipe)
-const example3 = pipeable(mutable({ name: 'john' })); // This returns a pipeable mutable signal (you get the point :) )
+label(); // e.g., "#2"
+total(); // reactive sum
 ```
 
 ### mapArray

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, Injectable, Injector, runInInjectionContext } from '@angular/core';
 import { isPlatformServer } from '@angular/common';
 import { SIGNAL } from '@angular/core/primitives/signals';
 
@@ -477,6 +478,91 @@ function mapArray(source, map, options) {
     });
 }
 
+/** Project with optional equality. Pure & sync. */
+const select = (projector, opt) => (src) => computed(() => projector(src()), opt);
+/** Combine with another signal using a projector. */
+const combineWith = (other, project, opt) => (src) => computed(() => project(src(), other()), opt);
+/** Only re-emit when equal(prev, next) is false. */
+const distinct = (equal = Object.is) => (src) => computed(() => src(), { equal });
+/** map to new value */
+const map = (fn) => (src) => computed(() => fn(src()));
+/** filter values, keeping the last value if it was ever available, if first value is filtered will return undefined */
+const filter = (predicate) => (src) => linkedSignal({
+    source: src,
+    computation: (next, prev) => {
+        if (predicate(next))
+            return next;
+        return prev?.source;
+    },
+});
+/** tap into the value */
+const tap = (fn) => (src) => {
+    effect(() => fn(src()));
+    return src;
+};
+
+/**
+ * Decorate any `Signal<T>` with a chainable `.pipe(...)` method.
+ *
+ * @example
+ * const s = pipeable(signal(1)); // WritableSignal<number> (+ pipe)
+ * const label = s.pipe(n => n * 2, n => `#${n}`); // Signal<string> (+ pipe)
+ * label(); // "#2"
+ */
+function pipeable(signal) {
+    const internal = signal;
+    const mapImpl = (...fns) => {
+        const last = fns.at(-1);
+        let opt;
+        if (last && typeof last !== 'function') {
+            fns = fns.slice(0, -1);
+            opt = last;
+        }
+        if (fns.length === 0)
+            return internal;
+        if (fns.length === 1) {
+            const fn = fns[0];
+            return pipeable(computed(() => fn(internal()), opt));
+        }
+        const transformer = (input) => fns.reduce((acc, fn) => fn(acc), input);
+        return pipeable(computed(() => transformer(internal()), opt));
+    };
+    const pipeImpl = (...ops) => {
+        if (ops.length === 0)
+            return internal;
+        return ops.reduce((src, op) => pipeable(op(src)), internal);
+    };
+    Object.defineProperties(internal, {
+        map: {
+            value: mapImpl,
+            configurable: true,
+            enumerable: false,
+            writable: false,
+        },
+        pipe: {
+            value: pipeImpl,
+            configurable: true,
+            enumerable: false,
+            writable: false,
+        },
+    });
+    return internal;
+}
+/**
+ * Create a new **writable** signal and return it as a `PipableSignal`.
+ *
+ * The returned value is a `WritableSignal<T>` with `.set`, `.update`, `.asReadonly`
+ * still available (via intersection type), plus a chainable `.pipe(...)`.
+ *
+ * @example
+ * const count = piped(1); // WritableSignal<number> (+ pipe)
+ * const even = count.pipe(n => n % 2 === 0); // Signal<boolean> (+ pipe)
+ * count.update(n => n + 1);
+ */
+function piped(initial, opt) {
+    return pipeable(signal(initial, opt));
+}
+
 /**
  * Creates a read-only signal that reactively tracks whether a CSS media query
  * string currently matches.
@@ -1208,6 +1294,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) => {
@@ -1406,5 +1608,5 @@ function withHistory(source, opt) {
  * Generated bundle index. Do not edit.
  */
 
-export { debounce, debounced, derived, elementVisibility, isDerivation, isMutable, mapArray, mediaQuery, mousePosition, mutable, networkStatus, pageVisibility, prefersDarkMode, prefersReducedMotion, scrollPosition, sensor, stored, throttle, throttled, toFakeDerivation, toFakeSignalDerivation, toWritable, until, windowSize, withHistory };
+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 };
 //# sourceMappingURL=mmstack-primitives.mjs.map