@mmstack/primitives 20.4.3 → 20.4.5

package/index.d.ts

@@ -468,6 +468,102 @@ declare function mapArray<T, U>(source: Signal<T[]> | (() => T[]), map: (value:
     onDestroy?: (value: U) => void;
 }): Signal<U[]>;
 
+/**
+ * A pure, synchronous transform from I -> O.
+ * Prefer transforms without side effects to keep derivations predictable.
+ */
+type UnaryFunction<I, O> = (a: I) => O;
+/** An Operator transforms a source Signal<I> into a derived Signal<O>. */
+type Operator<I, O> = (src: Signal<I>) => Signal<O>;
+type SignalMap<In> = {
+    (): PipeableSignal<In>;
+    <A>(fn1: UnaryFunction<In, A>, opt?: CreateSignalOptions<A>): PipeableSignal<A>;
+    <A, B>(fn1: UnaryFunction<In, A>, fn2: UnaryFunction<A, B>, opt?: CreateSignalOptions<B>): PipeableSignal<B>;
+    <A, B, C>(fn1: UnaryFunction<In, A>, fn2: UnaryFunction<A, B>, fn3: UnaryFunction<B, C>, opt?: CreateSignalOptions<C>): PipeableSignal<C>;
+    <A, B, C, D>(fn1: UnaryFunction<In, A>, fn2: UnaryFunction<A, B>, fn3: UnaryFunction<B, C>, fn4: UnaryFunction<C, D>, opt?: CreateSignalOptions<D>): PipeableSignal<D>;
+    <A, B, C, D, E>(fn1: UnaryFunction<In, A>, fn2: UnaryFunction<A, B>, fn3: UnaryFunction<B, C>, fn4: UnaryFunction<C, D>, fn5: UnaryFunction<D, E>, opt?: CreateSignalOptions<E>): PipeableSignal<E>;
+    <A, B, C, D, E, F>(fn1: UnaryFunction<In, A>, fn2: UnaryFunction<A, B>, fn3: UnaryFunction<B, C>, fn4: UnaryFunction<C, D>, fn5: UnaryFunction<D, E>, fn6: UnaryFunction<E, F>, opt?: CreateSignalOptions<F>): PipeableSignal<F>;
+    <A, B, C, D, E, F, G>(fn1: UnaryFunction<In, A>, fn2: UnaryFunction<A, B>, fn3: UnaryFunction<B, C>, fn4: UnaryFunction<C, D>, fn5: UnaryFunction<D, E>, fn6: UnaryFunction<E, F>, fn7: UnaryFunction<F, G>, opt?: CreateSignalOptions<G>): PipeableSignal<G>;
+    <A, B, C, D, E, F, G, H>(fn1: UnaryFunction<In, A>, fn2: UnaryFunction<A, B>, fn3: UnaryFunction<B, C>, fn4: UnaryFunction<C, D>, fn5: UnaryFunction<D, E>, fn6: UnaryFunction<E, F>, fn7: UnaryFunction<F, G>, fn8: UnaryFunction<G, H>, opt?: CreateSignalOptions<H>): PipeableSignal<H>;
+    <A, B, C, D, E, F, G, H, I>(fn1: UnaryFunction<In, A>, fn2: UnaryFunction<A, B>, fn3: UnaryFunction<B, C>, fn4: UnaryFunction<C, D>, fn5: UnaryFunction<D, E>, fn6: UnaryFunction<E, F>, fn7: UnaryFunction<F, G>, fn8: UnaryFunction<G, H>, fn9: UnaryFunction<H, I>, ...rest: UnaryFunction<any, any>[]): PipeableSignal<unknown>;
+};
+/** `.pipe(...)` — compose operators (Signal -> Signal). */
+type SignalPipe<In> = {
+    (): PipeableSignal<In>;
+    <A>(op1: Operator<In, A>): PipeableSignal<A>;
+    <A, B>(op1: Operator<In, A>, op2: Operator<A, B>): PipeableSignal<B>;
+    <A, B, C>(op1: Operator<In, A>, op2: Operator<A, B>, op3: Operator<B, C>): PipeableSignal<C>;
+    <A, B, C, D>(op1: Operator<In, A>, op2: Operator<A, B>, op3: Operator<B, C>, op4: Operator<C, D>): PipeableSignal<D>;
+    <A, B, C, D, E>(op1: Operator<In, A>, op2: Operator<A, B>, op3: Operator<B, C>, op4: Operator<C, D>, op5: Operator<D, E>): PipeableSignal<E>;
+    <A, B, C, D, E, F>(op1: Operator<In, A>, op2: Operator<A, B>, op3: Operator<B, C>, op4: Operator<C, D>, op5: Operator<D, E>, op6: Operator<E, F>): PipeableSignal<F>;
+    <A, B, C, D, E, F, G>(op1: Operator<In, A>, op2: Operator<A, B>, op3: Operator<B, C>, op4: Operator<C, D>, op5: Operator<D, E>, op6: Operator<E, F>, op7: Operator<F, G>): PipeableSignal<G>;
+    <A, B, C, D, E, F, G, H>(op1: Operator<In, A>, op2: Operator<A, B>, op3: Operator<B, C>, op4: Operator<C, D>, op5: Operator<D, E>, op6: Operator<E, F>, op7: Operator<F, G>, op8: Operator<G, H>): PipeableSignal<H>;
+    <A, B, C, D, E, F, G, H, I>(op1: Operator<In, A>, op2: Operator<A, B>, op3: Operator<B, C>, op4: Operator<C, D>, op5: Operator<D, E>, op6: Operator<E, F>, op7: Operator<F, G>, op8: Operator<G, H>, op9: Operator<H, I>, ...rest: Operator<any, any>[]): PipeableSignal<unknown>;
+};
+/**
+ * A `Signal<T>` augmented with a chainable `.pipe(...)` method.
+ *
+ * The `.pipe(...)` returns **computed** signals wrapped with the same method,
+ * allowing fluent, strongly-typed pipelines.
+ * @see {@link SignalPipe}
+ * @example
+ * ```ts
+ * import { piped } from '@ngrx/signals';
+ *
+ * const count = piped(1);
+ *
+ * const doubled = count.pipe(x => x * 2); // PipeableSignal<number>
+ * // doubled() === 2
+ * const toString = doubled.pipe(String); // PipeableSignal<string>
+ * // toString() === '2'
+ * ```
+ */
+type PipeableSignal<T, TSig extends Signal<T> = Signal<T>> = TSig & {
+    pipe: SignalPipe<T>;
+    /** Chain pure transforms to derive new signals. See {@link SignalMap}. */
+    map: SignalMap<T>;
+};
+/**
+ * Helper type to infer the value type of a signal.
+ * @internal
+ */
+type SignalValue<TSig extends Signal<any>> = TSig extends Signal<infer V> ? V : never;
+
+/** Project with optional equality. Pure & sync. */
+declare const select: <I, O>(projector: (v: I) => O, opt?: CreateSignalOptions<O>) => Operator<I, O>;
+/** Combine with another signal using a projector. */
+declare const combineWith: <A, B, R>(other: Signal<B>, project: (a: A, b: B) => R, opt?: CreateSignalOptions<R>) => Operator<A, R>;
+/** Only re-emit when equal(prev, next) is false. */
+declare const distinct: <T>(equal?: (a: T, b: T) => boolean) => Operator<T, T>;
+/** map to new value */
+declare const map: <I, O>(fn: (v: I) => O) => Operator<I, O>;
+/** filter values, keeping the last value if it was ever available, if first value is filtered will return undefined */
+declare const filter: <T>(predicate: (v: T) => boolean) => Operator<T, T | undefined>;
+/** tap into the value */
+declare const tap: <T>(fn: (v: T) => void) => Operator<T, T>;
+
+/**
+ * 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"
+ */
+declare function pipeable<TSig extends Signal<any>>(signal: TSig): PipeableSignal<SignalValue<TSig>, TSig>;
+/**
+ * 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);
+ */
+declare function piped<T>(initial: T, opt?: CreateSignalOptions<T>): PipeableSignal<T, WritableSignal<T>>;
+
 /**
  * Creates a read-only signal that reactively tracks whether a CSS media query
  * string currently matches.
@@ -1064,6 +1160,48 @@ type StoredSignal<T> = WritableSignal<T> & {
  */
 declare function stored<T>(fallback: T, { key, store: providedStore, serialize, deserialize, syncTabs, equal, onKeyChange, cleanupOldKey, ...rest }: CreateStoredOptions<T>): StoredSignal<T>;
 
+type SyncSignalOptions = {
+    id?: string;
+};
+/**
+ * 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
+ *
+ */
+declare function tabSync<T extends WritableSignal<any>>(sig: T, opt?: SyncSignalOptions): T;
+
 /**
  * Options for creating a throttled writable signal.
  * Extends Angular's `CreateSignalOptions` with a throttle time setting.
@@ -1318,5 +1456,5 @@ type CreateHistoryOptions<T> = Omit<CreateSignalOptions<T[]>, 'equal'> & {
  */
 declare function withHistory<T>(source: WritableSignal<T>, opt?: CreateHistoryOptions<T>): SignalWithHistory<T>;
 
-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 type { CreateDebouncedOptions, CreateHistoryOptions, CreateStoredOptions, CreateThrottledOptions, DebouncedSignal, DerivedSignal, ElementVisibilityOptions, ElementVisibilitySignal, MousePositionOptions, MousePositionSignal, MutableSignal, NetworkStatusSignal, ScrollPosition, ScrollPositionOptions, ScrollPositionSignal, SignalWithHistory, StoredSignal, ThrottledSignal, UntilOptions, WindowSize, WindowSizeOptions, WindowSizeSignal };
+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 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.3",
+  "version": "20.4.5",
   "keywords": [
     "angular",
     "signals",