@mmstack/primitives 19.5.1 → 19.6.0

package/lib/store/types.d.ts

@@ -0,0 +1,85 @@
+import { type Signal, type WritableSignal } from '@angular/core';
+import { type MutableSignal } from '../mutable';
+import { type LEAF } from './leaf';
+import { type OPAQUE, type UnwrapOpaque } from './opaque';
+type BaseType = string | number | boolean | symbol | bigint | undefined | null | Function | Date | RegExp | {
+    readonly [OPAQUE]: true;
+};
+export type Key = string | number;
+export type AnyRecord = Record<Key, any>;
+/**
+ * @internal Resolves to `true` only for `any`. In a conditional type, `any` distributes across
+ * *both* branches (`unknown | object`), and `unknown | X` collapses to `unknown` — which would
+ * erase a store's property access and `extend`. Guarding on this routes an `any`-typed store to
+ * the full object shape instead.
+ */
+type IsAny<T> = 0 extends 1 & T ? true : false;
+/**
+ * @internal Flattens an intersection (`A & B & C`) into a single object literal so editor
+ * tooltips show the resolved members instead of the raw intersection chain. Display-only —
+ * structurally identical to its input.
+ */
+export type Simplify<T> = {
+    [K in keyof T]: T[K];
+} & {};
+export type SignalArrayStore<T extends any[]> = Signal<T> & {
+    readonly [index: number]: SignalStore<T[number]>;
+    readonly length: Signal<number>;
+    [Symbol.iterator](): Iterator<SignalStore<T[number]>>;
+};
+export type WritableArrayStore<T extends any[]> = WritableSignal<T> & {
+    readonly asReadonlyStore: () => SignalArrayStore<T>;
+    readonly [index: number]: WritableSignalStore<T[number]>;
+    readonly length: Signal<number>;
+    [Symbol.iterator](): Iterator<WritableSignalStore<T[number]>>;
+};
+export type MutableArrayStore<T extends any[]> = MutableSignal<T> & {
+    readonly asReadonlyStore: () => SignalArrayStore<T>;
+    readonly [index: number]: MutableSignalStore<T[number]>;
+    readonly length: Signal<number>;
+    [Symbol.iterator](): Iterator<MutableSignalStore<T[number]>>;
+};
+/** @internal The object shape of a readonly store: a child store per key, plus `extend`. */
+type SignalStoreObject<T> = Simplify<Readonly<{
+    [K in keyof Required<T>]: SignalStore<NonNullable<T>[K]>;
+}> & {
+    /** @deprecated Use the standalone `extendStore(store, …)`; the `extend` key is removed next minor. */
+    readonly extend: {
+        <L extends AnyRecord>(source: Signal<L>): SignalStore<Simplify<Omit<NonNullable<T>, keyof L> & L>>;
+        <L extends AnyRecord>(props: L): SignalStore<Simplify<Omit<NonNullable<T>, keyof L> & L>>;
+    };
+}>;
+/** @internal The object shape of a writable store. */
+type WritableSignalStoreObject<T> = Simplify<Readonly<{
+    [K in keyof Required<T>]: WritableSignalStore<NonNullable<T>[K]>;
+}> & {
+    /** @deprecated Use the standalone `extendStore(store, …)`; the `extend` key is removed next minor. */
+    readonly extend: {
+        <L extends AnyRecord>(source: WritableSignal<L>): WritableSignalStore<Simplify<Omit<NonNullable<T>, keyof L> & L>>;
+        <L extends AnyRecord>(props: L): WritableSignalStore<Simplify<Omit<NonNullable<T>, keyof L> & L>>;
+    };
+}>;
+/** @internal The object shape of a mutable store. */
+type MutableSignalStoreObject<T> = Simplify<Readonly<{
+    [K in keyof Required<T>]: MutableSignalStore<NonNullable<T>[K]>;
+}> & {
+    /** @deprecated Use the standalone `extendStore(store, …)`; the `extend` key is removed next minor. */
+    readonly extend: {
+        <L extends AnyRecord>(source: MutableSignal<L>): MutableSignalStore<Simplify<Omit<NonNullable<T>, keyof L> & L>>;
+        <L extends AnyRecord>(props: L): MutableSignalStore<Simplify<Omit<NonNullable<T>, keyof L> & L>>;
+    };
+}>;
+export type SignalStore<T> = Signal<UnwrapOpaque<T>> & (IsAny<T> extends true ? SignalStoreObject<T> : NonNullable<T> extends BaseType ? {
+    readonly [LEAF]: () => boolean;
+} : NonNullable<T> extends any[] ? SignalArrayStore<NonNullable<T>> : SignalStoreObject<T>);
+export type WritableSignalStore<T> = WritableSignal<UnwrapOpaque<T>> & {
+    readonly asReadonlyStore: () => SignalStore<T>;
+} & (IsAny<T> extends true ? WritableSignalStoreObject<T> : NonNullable<T> extends BaseType ? {
+    readonly [LEAF]: () => boolean;
+} : NonNullable<T> extends any[] ? WritableArrayStore<NonNullable<T>> : WritableSignalStoreObject<T>);
+export type MutableSignalStore<T> = MutableSignal<UnwrapOpaque<T>> & {
+    readonly asReadonlyStore: () => SignalStore<T>;
+} & (IsAny<T> extends true ? MutableSignalStoreObject<T> : NonNullable<T> extends BaseType ? {
+    readonly [LEAF]: () => boolean;
+} : NonNullable<T> extends any[] ? MutableArrayStore<NonNullable<T>> : MutableSignalStoreObject<T>);
+export {};

package/lib/stored.d.ts

@@ -1,4 +1,5 @@
-import { type CreateSignalOptions, type Signal, type WritableSignal } from '@angular/core';
+import { Injector, type CreateSignalOptions, type Signal, type WritableSignal } from '@angular/core';
+import { type PauseOption } from './concurrent/pausable';
 /**
  * Interface for storage mechanisms compatible with the `stored` signal.
  * Matches the essential parts of the `Storage` interface (`localStorage`, `sessionStorage`).
@@ -65,6 +66,18 @@ export type CreateStoredOptions<T> = CreateSignalOptions<T> & {
      * Optional validator, which is called on load of value. Store will be set to fallback if value is false
      */
     validate?: (value: T) => boolean;
+    /**
+     * Opt-in pause: gate the persistence effect on an ambient Activity boundary (`true`), a custom
+     * predicate, or `false` (default — no pausing). While paused the value stays live; persistence is
+     * skipped and flushes the latest value on resume. The inbound `storage` listener stays live.
+     * See {@link PauseOption}.
+     */
+    pause?: PauseOption;
+    /**
+     * Injector used when `stored` is created outside an injection context, and to resolve the ambient
+     * pause boundary when `pause` is `true`.
+     */
+    injector?: Injector;
 };
 /**
  * A specialized `WritableSignal` returned by the `stored()` function.
@@ -136,5 +149,5 @@ export type StoredSignal<T> = WritableSignal<T> & {
  * }
  * ```
  */
-export declare function stored<T>(fallback: T, { key, store: providedStore, serialize, deserialize, syncTabs, equal, onKeyChange, cleanupOldKey, validate, ...rest }: CreateStoredOptions<T>): StoredSignal<T>;
+export declare function stored<T>(fallback: T, { key, store: providedStore, serialize, deserialize, syncTabs, equal, onKeyChange, cleanupOldKey, validate, pause, injector: providedInjector, ...rest }: CreateStoredOptions<T>): StoredSignal<T>;
 export {};

package/lib/tab-sync.d.ts

@@ -1,4 +1,4 @@
-import { type OnDestroy, type WritableSignal } from '@angular/core';
+import { Injector, type OnDestroy, type WritableSignal } from '@angular/core';
 import * as i0 from "@angular/core";
 export declare class MessageBus implements OnDestroy {
     private readonly channel;
@@ -22,6 +22,14 @@ type LegacySyncSignalOptions = {
 };
 export type SyncSignalOptions = {
     id: string;
+    /**
+     * Injector used when `tabSync` is called outside an injection context.
+     *
+     * NOTE: `tabSync` is intentionally NOT pausable. Pausing the outbound broadcast would let its
+     * mount-time echo guard swallow a value changed while hidden, so other tabs would silently miss
+     * it — a cross-tab consistency gap not worth the negligible saving. The channel stays live.
+     */
+    injector?: Injector;
 };
 /**
  * @example tabSync(signal('dark'), { id: 'theme' })

package/lib/throttled.d.ts

@@ -37,12 +37,16 @@ export type CreateThrottledOptions<T> = CreateSignalOptions<T> & {
 /**
  * A specialized `WritableSignal` whose publicly readable value updates are throttled.
  *
- * It provides access to the underlying, non-throttled signal via the `original` property.
+ * Provides access to the underlying, non-throttled signal via `original`, and a
+ * `flush()` that emits the current value immediately (clearing any open window) —
+ * useful for terminal transitions that shouldn't wait for the trailing edge.
  *
  * @template T The type of value held by the signal.
- * @see {DebouncedSignal} as the output type has the same structure.
  */
-export type ThrottledSignal<T> = DebouncedSignal<T>;
+export type ThrottledSignal<T> = DebouncedSignal<T> & {
+    /** Emit the latest value now, bypassing the remaining throttle window. */
+    flush: () => void;
+};
 /**
  * A convenience function that creates and throttles a new `WritableSignal` in one step.
  *
@@ -63,7 +67,7 @@ export type ThrottledSignal<T> = DebouncedSignal<T>;
  * // With a trailing-edge throttle, the final value 'c' would be set
  * // after the 500ms cooldown.
  */
-export declare function throttled<T>(initial: T, opt?: CreateThrottledOptions<T>): DebouncedSignal<T>;
+export declare function throttled<T>(initial: T, opt?: CreateThrottledOptions<T>): ThrottledSignal<T>;
 /**
  * Wraps an existing `WritableSignal` to create a new one whose readable value is throttled.
  *

package/package.json

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