@mmstack/primitives 19.0.4 → 19.0.5

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-present Miha Mulec
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,229 @@
-# mmstack/primitives
+# @mmstack/primitives
 
-A library for signal primitives, still working on the docs ;)
+A collection of utility functions and primitives designed to enhance development with Angular Signals, providing helpful patterns and inspired by features from other reactive libraries. All value helpers also use pure derivations (no effects/RxJS).
+
+[![npm version](https://badge.fury.io/js/%40mmstack%2Fprimitives.svg)](https://badge.fury.io/js/%40mmstack%2Fprimitives)
+
+## Installation
+
+```bash
+npm install @mmstack/primitives
+```
+
+## Primitives
+
+This library provides the following primitives:
+
+- `debounced` - Creates a writable signal whose value updates are debounced after set/update.
+- `mutable` - A signal variant allowing in-place mutations while triggering updates.
+- `stored` - Creates a signal synchronized with persistent storage (e.g., localStorage).
+- `mapArray` - Maps a reactive array efficently into an array of stable derivations.
+- `toWritable` - Converts a read-only signal to writable using custom write logic.
+- `derived` - Creates a signal with two-way binding to a source signal.
+
+---
+
+### debounced
+
+Creates a WritableSignal where the propagation of its value (after calls to .set() or .update()) is delayed. The publicly readable signal value updates only after a specified time (ms) has passed without further set/update calls. It also includes an .original property, which is a Signal reflecting the value immediately after set/update is called.
+
+```typescript
+import { Component, signal, effect } from '@angular/core';
+import { debounced } from '@mmstack/primitives';
+import { FormsModule } from '@angular/forms';
+
+@Component({
+  selector: 'app-debounced',
+  template: `<input [(ngModel)]="searchTerm" />`,
+})
+export class SearchComponent {
+  searchTerm = debounced('', { ms: 300 }); // Debounce for 300ms
+
+  constructor() {
+    effect(() => {
+      // Runs 300ms after the user stops typing
+      console.log('Perform search for:', this.searchTerm());
+    });
+    effect(() => {
+      // Runs immediately on input change
+      console.log('Input value:', this.searchTerm.original());
+    });
+  }
+}
+```
+
+### mutable
+
+Creates a MutableSignal, a signal variant designed for scenarios where you want to perform in-place mutations on objects or arrays held within the signal, while still ensuring Angular's change detection is correctly triggered. It provides .mutate() and .inline() methods alongside the standard .set() and .update(). Please note that any computeds, which resolve non-primitive values from a mutable require equals to be set to false.
+
+```typescript
+import { Component, computed, effect } from '@angular/core';
+import { mutable } from '@mmstack/primitives';
+import { FormsModule } from '@angular/forms';
+
+@Component({
+  selector: 'app-mutable',
+  template: ` <button (click)="incrementAge()">inc</button> `,
+})
+export class SearchComponent {
+  user = mutable({ name: { first: 'John', last: 'Doe' }, age: 30 });
+
+  constructor() {
+    effect(() => {
+      // Runs every time user is mutated
+      console.log(this.user());
+    });
+
+    const age = computed(() => this.user().age);
+
+    effect(() => {
+      // Runs every time age changes
+      console.log(age());
+    });
+
+    const name = computed(() => this.user().name);
+    effect(() => {
+      // Doesnt run if user changes, unless name is destructured
+      console.log(name());
+    });
+
+    const name2 = computed(() => this.user().name, {
+      equal: () => false,
+    });
+
+    effect(() => {
+      // Runs every time user changes (even if name did not change)
+      console.log(name2());
+    });
+  }
+
+  incrementAge() {
+    user.mutate((prev) => {
+      prev.age++;
+      return prev;
+    });
+  }
+
+  incrementInline() {
+    user.inline((prev) => {
+      prev.age++;
+    });
+  }
+}
+```
+
+### stored
+
+Creates a WritableSignal whose state is automatically synchronized with persistent storage (like localStorage or sessionStorage), providing a fallback value when no data is found or fails to parse.
+
+It handles Server-Side Rendering (SSR) gracefully, allows dynamic storage keys, custom serialization/deserialization, custom storage providers, and optional synchronization across browser tabs via the storage event. It returns a StoredSignal<T> which includes a .clear() method and a reactive .key signal.
+
+```typescript
+import { Component, effect, signal } from '@angular/core';
+import { stored } from '@mmstack/primitives';
+// import { FormsModule } from '@angular/forms'; // Needed for ngModel
+
+@Component({
+  selector: 'app-theme-selector',
+  standalone: true,
+  // imports: [FormsModule], // Import if using ngModel
+  template: `
+    Theme:
+    <select [value]="theme()" (change)="theme.set($event.target.value)">
+      <option value="light">Light</option>
+      <option value="dark">Dark</option>
+      <option value="system">System</option>
+    </select>
+    <button (click)="theme.clear()">Reset Theme</button>
+    <p>Using storage key: {{ theme.key() }}</p>
+  `,
+})
+export class ThemeSelectorComponent {
+  // Persist theme preference in localStorage, default to 'system'
+  theme = stored<'light' | 'dark' | 'system'>('system', {
+    key: 'user-theme',
+    syncTabs: true, // Sync theme choice across tabs
+  });
+
+  constructor() {
+    effect(() => {
+      console.log(`Theme set to: ${this.theme()}`);
+      // Logic to apply theme (e.g., add class to body)
+      document.body.className = `theme-${this.theme()}`;
+    });
+  }
+}
+```
+
+### mapArray
+
+Reactive map helper that stabilizes a source array Signal by length. It provides stability by giving the mapping function a stable Signal<T> for each item based on its index. Sub signals are not re-created, rather they propagate value updates through. This is particularly useful for rendering lists (@for) as it minimizes DOM changes when array items change identity but represent the same conceptual entity.
+
+```typescript
+import { Component, signal } from '@angular/core';
+import { mapArray } from '@mmstack/primitives';
+
+@Component({
+  selector: 'app-map-demo',
+  template: `
+    <ul>
+      @for (item of displayItems(); track item) {
+        <li>{{ item() }}</li>
+      }
+    </ul>
+    <button (click)="addItem()">Add</button>
+    <button (click)="updateFirst()">Update First</button>
+  `,
+})
+export class ListComponent {
+  sourceItems = signal([
+    { id: 1, name: 'A' },
+    { id: 2, name: 'B' },
+  ]);
+
+  readonly displayItems = mapArray(this.sourceItems, (child, index) => computed(() => `Item ${index}: ${child().name}`));
+
+  addItem() {
+    this.sourceItems.update((items) => [...items, { id: Date.now(), name: String.fromCharCode(67 + items.length - 2) }]);
+  }
+
+  updateFirst() {
+    this.sourceItems.update((items) => {
+      items[0] = { ...items[0], name: items[0].name + '+' };
+      return [...items]; // New array, but mapArray keeps stable signals
+    });
+  }
+}
+```
+
+### toWritable
+
+A utility function that converts a read-only Signal into a WritableSignal by allowing you to provide custom implementations for the .set() and .update() methods. This is useful for creating controlled write access to signals that are naturally read-only (like those created by computed). This is used under the hood in derived.
+
+```typescript
+import { Component, signal, effect } from '@angular/core';
+import { toWritable } from '@mmstack/primitives';
+
+const user = signal({ name: 'John' });
+
+const name = toWritable(
+  computed(() => user().name),
+  (name) => user.update((prev) => ({ ...prev, name })),
+); // WritableSignal<string> bound to user signal
+```
+
+### derived
+
+Creates a WritableSignal that represents a part of another source WritableSignal (e.g., an object property or an array element), enabling two-way data binding. Changes to the source update the derived signal, and changes to the derived signal (via .set() or .update()) update the source signal accordingly.
+
+```typescript
+const user = signal({ name: 'John' });
+
+const name = derived(user, 'name'); // WritableSignal<string>, which updates user signal & reacts to changes in the name property
+
+// Full syntax example
+const name2 = derived(user, {
+  from: (u) => u.name,
+  onChange: (name) => user.update((prev) => ({ ...prev, name })),
+});
+```

package/fesm2022/mmstack-primitives.mjs

@@ -1,4 +1,5 @@
-import { untracked, signal, computed, isSignal, linkedSignal } from '@angular/core';
+import { untracked, signal, computed, isSignal, linkedSignal, inject, PLATFORM_ID, isDevMode, effect, DestroyRef } from '@angular/core';
+import { isPlatformServer } from '@angular/common';
 
 /**
  * Converts a read-only `Signal` into a `WritableSignal` by providing custom `set` and, optionally, `update` functions.
@@ -36,38 +37,88 @@ function toWritable(signal, set, update) {
     return internal;
 }
 
-function debounced(value, opt) {
-    const sig = signal(value, opt);
-    const ms = opt?.ms ?? 300;
-    let timeout;
-    const originalSet = sig.set;
-    const originalUpdate = sig.update;
+/**
+ * Creates a `WritableSignal` whose publicly readable value is updated only after
+ * a specified debounce period (`ms`) has passed since the last call to its
+ * `.set()` or `.update()` method.
+ *
+ * This implementation avoids using `effect` by leveraging intermediate `computed`
+ * signals and a custom `equal` function to delay value propagation based on a timer.
+ *
+ * @template T The type of value the signal holds.
+ * @param initial The initial value of the signal.
+ * @param opt Options for signal creation, including:
+ * - `ms`: The debounce time in milliseconds. Defaults to 0 if omitted (no debounce).
+ * - Other `CreateSignalOptions` (like `equal`) are passed to underlying signals.
+ * @returns A `DebouncedSignal<T>` instance. Its readable value updates are debounced,
+ * and it includes an `.original` property providing immediate access to the latest set value.
+ *
+ * @example
+ * ```ts
+ * import { effect } from '@angular/core';
+ *
+ * // Create a debounced signal with a 500ms delay
+ * const query = debounced('', { ms: 500 });
+ *
+ * effect(() => {
+ * // This effect runs 500ms after the last change to 'query'
+ * console.log('Debounced Query:', query());
+ * });
+ *
+ * effect(() => {
+ * // This effect runs immediately when 'query.original' changes
+ * console.log('Original Query:', query.original());
+ * });
+ *
+ * console.log('Setting query to "a"');
+ * query.set('a');
+ * // Output: Original Query: a
+ *
+ * setTimeout(() => {
+ * console.log('Setting query to "ab"');
+ * query.set('ab');
+ * // Output: Original Query: ab
+ * }, 200); // Before debounce timeout
+ *
+ * setTimeout(() => {
+ * console.log('Setting query to "abc"');
+ * query.set('abc');
+ * // Output: Original Query: abc
+ * }, 400); // Before debounce timeout
+ *
+ * // ~500ms after the *last* set (at 400ms), the debounced effect runs:
+ * // Output (at ~900ms): Debounced Query: abc
+ * ```
+ */
+function debounced(initial, opt) {
+    const internal = signal(initial, opt);
+    const ms = opt.ms ?? 0;
     const trigger = signal(false);
-    // Set on the original signal, then trigger the debounced update
+    let timeout;
     const set = (value) => {
-        originalSet(value); // Update the *original* signal immediately
         if (timeout)
             clearTimeout(timeout);
+        internal.set(value);
         timeout = setTimeout(() => {
-            trigger.update((cur) => !cur); // Trigger the computed signal
+            trigger.update((c) => !c);
         }, ms);
     };
-    // Update on the original signal, then trigger the debounced update
     const update = (fn) => {
-        originalUpdate(fn); // Update the *original* signal immediately
         if (timeout)
             clearTimeout(timeout);
+        internal.update(fn);
         timeout = setTimeout(() => {
-            trigger.update((cur) => !cur); // Trigger the computed signal
+            trigger.update((c) => !c);
         }, ms);
     };
-    // Create a computed signal that depends on the trigger.
-    // This computed signal is what provides the debounced behavior.
-    const writable = toWritable(computed(() => {
-        trigger();
-        return untracked(sig);
-    }), set, update);
-    writable.original = sig;
+    const stable = computed(() => ({
+        trigger: trigger(),
+        value: internal(),
+    }), {
+        equal: (a, b) => a.trigger === b.trigger,
+    });
+    const writable = toWritable(computed(() => stable().value, opt), set, update);
+    writable.original = internal;
     return writable;
 }
 
@@ -132,32 +183,84 @@ function isDerivation(sig) {
     return 'from' in sig;
 }
 
-function createReconciler(source, opt) {
-    const map = opt?.map ?? ((source, index) => source[index]);
-    return (length, prev) => {
-        if (!prev)
-            return Array.from({ length }, (_, i) => computed(() => map(source(), i), opt));
-        if (length === prev.source)
-            return prev.value;
-        if (length < prev.source) {
-            return prev.value.slice(0, length);
-        }
-        else {
-            const next = [...prev.value];
-            for (let i = prev.source; i < length; i++) {
-                next.push(computed(() => map(source(), i), opt));
-            }
-            return next;
-        }
-    };
-}
-function mapArray(source, opt) {
+/**
+ * Reactively maps items from a source array (or signal of an array) using a provided mapping function.
+ *
+ * This function serves a similar purpose to SolidJS's `mapArray` by providing stability
+ * for mapped items. It receives a source function returning an array (or a Signal<T[]>)
+ * and a mapping function.
+ *
+ * For each item in the source array, it creates a stable `computed` signal representing
+ * that item's value at its current index. This stable signal (`Signal<T>`) is passed
+ * to the mapping function. This ensures that downstream computations or components
+ * depending on the mapped result only re-render or re-calculate for the specific items
+ * that have changed, or when items are added/removed, rather than re-evaluating everything
+ * when the source array reference changes but items remain the same.
+ *
+ * It efficiently handles changes in the source array's length by reusing existing mapped
+ * results when possible, slicing when the array shrinks, and appending new mapped items
+ * when it grows.
+ *
+ * @template T The type of items in the source array.
+ * @template U The type of items in the resulting mapped array.
+ *
+ * @param source A function returning the source array `T[]`, or a `Signal<T[]>` itself.
+ * The `mapArray` function will reactively update based on changes to this source.
+ * @param map The mapping function. It is called for each item in the source array.
+ * It receives:
+ * - `value`: A stable `Signal<T>` representing the item at the current index.
+ * Use this signal within your mapping logic if you need reactivity
+ * tied to the specific item's value changes.
+ * - `index`: The number index of the item in the array.
+ * It should return the mapped value `U`.
+ * @param [opt] Optional `CreateSignalOptions<T>`. These options are passed directly
+ * to the `computed` signal created for each individual item (`Signal<T>`).
+ * This allows specifying options like a custom `equal` function for item comparison.
+ *
+ * @returns A `Signal<U[]>` containing the mapped array. This signal updates whenever
+ * the source array changes (either length or the values of its items).
+ *
+ * @example
+ * ```ts
+ * const sourceItems = signal([
+ * { id: 1, name: 'Apple' },
+ * { id: 2, name: 'Banana' }
+ * ]);
+ *
+ * const mappedItems = mapArray(
+ * sourceItems,
+ * (itemSignal, index) => {
+ * // itemSignal is stable for a given item based on its index.
+ * // We create a computed here to react to changes in the item's name.
+ *  return computed(() => `${index}: ${itemSignal().name.toUpperCase()}`);
+ * },
+ * // Example optional options (e.g., custom equality for item signals)
+ * { equal: (a, b) => a.id === b.id && a.name === b.name }
+ * );
+ * ```
+ */
+function mapArray(source, map, opt) {
     const data = isSignal(source) ? source : computed(source);
-    const length = computed(() => data().length);
-    const reconciler = createReconciler(data, opt);
+    const len = computed(() => data().length);
     return linkedSignal({
-        source: () => length(),
-        computation: (len, prev) => reconciler(len, prev),
+        source: () => len(),
+        computation: (len, prev) => {
+            if (!prev)
+                return Array.from({ length: len }, (_, i) => map(computed(() => source()[i], opt), i));
+            if (len === prev.value.length)
+                return prev.value;
+            if (len < prev.value.length) {
+                return prev.value.slice(0, len);
+            }
+            else {
+                const next = [...prev.value];
+                for (let i = prev.value.length; i < len; i++) {
+                    next[i] = map(computed(() => source()[i], opt), i);
+                }
+                return next;
+            }
+        },
+        equal: (a, b) => a.length === b.length,
     });
 }
 
@@ -212,9 +315,140 @@ function isMutable(value) {
     return 'mutate' in value && typeof value.mutate === 'function';
 }
 
+// Internal dummy store for server-side rendering
+const noopStore = {
+    getItem: () => null,
+    setItem: () => {
+        /* noop */
+    },
+    removeItem: () => {
+        /* noop */
+    },
+};
+/**
+ * Creates a `WritableSignal` whose state is automatically synchronized with persistent storage
+ * (like `localStorage` or `sessionStorage`).
+ *
+ * It handles Server-Side Rendering (SSR) gracefully, allows dynamic storage keys,
+ * custom serialization/deserialization, custom storage providers, and optional
+ * synchronization across browser tabs.
+ *
+ * @template T The type of value held by the signal and stored (after serialization).
+ * @param fallback The default value of type `T` to use when no value is found in storage
+ * or when deserialization fails. The signal's value will never be `null` or `undefined`
+ * publicly, it will always revert to this fallback.
+ * @param options Configuration options (`CreateStoredOptions<T>`). Requires at least the `key`.
+ * @returns A `StoredSignal<T>` instance. This signal behaves like a standard `WritableSignal<T>`,
+ * but its value is persisted. It includes a `.clear()` method to remove the item from storage
+ * and a `.key` signal providing the current storage key.
+ *
+ * @remarks
+ * - **Persistence:** The signal automatically saves its value to storage whenever the signal's
+ * value or its configured `key` changes. This is managed internally using `effect`.
+ * - **SSR Safety:** Detects server environments and uses a no-op storage, preventing errors.
+ * - **Error Handling:** Catches and logs errors during serialization/deserialization in dev mode.
+ * - **Tab Sync:** If `syncTabs` is true, listens to `storage` events to keep the signal value
+ * consistent across browser tabs using the same key. Cleanup is handled automatically
+ * using `DestroyRef`.
+ * - **Removal:** Use the `.clear()` method on the returned signal to remove the item from storage.
+ * Setting the signal to the fallback value will store the fallback value, not remove the item.
+ *
+ * @example
+ * ```ts
+ * import { Component, effect, signal } from '@angular/core';
+ * import { stored } from '@mmstack/primitives'; // Adjust import path
+ *
+ * @Component({
+ * selector: 'app-settings',
+ * standalone: true,
+ * template: `
+ * Theme:
+ * <select [ngModel]="theme()" (ngModelChange)="theme.set($event)">
+ * <option value="light">Light</option>
+ * <option value="dark">Dark</option>
+ * </select>
+ * <button (click)="theme.clear()">Clear Theme Setting</button>
+ * <p>Storage Key Used: {{ theme.key() }}</p>
+ * ` // Requires FormsModule for ngModel
+ * })
+ * export class SettingsComponent {
+ *  theme = stored<'light' | 'dark'>('light', { key: 'app-theme', syncTabs: true });
+ * }
+ * ```
+ */
+function stored(fallback, { key, store: providedStore, serialize = JSON.stringify, deserialize = JSON.parse, syncTabs = false, equal = Object.is, ...rest }) {
+    const isServer = isPlatformServer(inject(PLATFORM_ID));
+    const fallbackStore = isServer ? noopStore : localStorage;
+    const store = providedStore ?? fallbackStore;
+    const keySig = typeof key === 'string'
+        ? computed(() => key)
+        : isSignal(key)
+            ? key
+            : computed(key);
+    const getValue = (key) => {
+        const found = store.getItem(key);
+        if (found === null)
+            return null;
+        try {
+            return deserialize(found);
+        }
+        catch (err) {
+            if (isDevMode())
+                console.error(`Failed to parse stored value for key "${key}":`, err);
+            return null;
+        }
+    };
+    const storeValue = (key, value) => {
+        try {
+            if (value === null)
+                return store.removeItem(key);
+            const serialized = serialize(value);
+            store.setItem(key, serialized);
+        }
+        catch (err) {
+            if (isDevMode())
+                console.error(`Failed to store value for key "${key}":`, err);
+        }
+    };
+    const opt = {
+        ...rest,
+        equal,
+    };
+    const internal = signal(getValue(untracked(keySig)), {
+        ...opt,
+        equal: (a, b) => {
+            if (a === null && b === null)
+                return true;
+            if (a === null || b === null)
+                return false;
+            return equal(a, b);
+        },
+    });
+    effect(() => storeValue(keySig(), internal()));
+    if (syncTabs && !isServer) {
+        const destroyRef = inject(DestroyRef);
+        const sync = (e) => {
+            if (e.key !== untracked(keySig))
+                return;
+            if (e.newValue === null)
+                internal.set(null);
+            else
+                internal.set(getValue(e.key));
+        };
+        window.addEventListener('storage', sync);
+        destroyRef.onDestroy(() => window.removeEventListener('storage', sync));
+    }
+    const writable = toWritable(computed(() => internal() ?? fallback, opt), internal.set);
+    writable.clear = () => {
+        internal.set(null);
+    };
+    writable.key = keySig;
+    return writable;
+}
+
 /**
  * Generated bundle index. Do not edit.
  */
 
-export { debounced, derived, isDerivation, isMutable, mapArray, mutable, toFakeDerivation, toFakeSignalDerivation, toWritable };
+export { debounced, derived, isDerivation, isMutable, mapArray, mutable, stored, toFakeDerivation, toFakeSignalDerivation, toWritable };
 //# sourceMappingURL=mmstack-primitives.mjs.map

package/fesm2022/mmstack-primitives.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"mmstack-primitives.mjs","sources":["../../../../packages/primitives/src/lib/to-writable.ts","../../../../packages/primitives/src/lib/debounced.ts","../../../../packages/primitives/src/lib/derived.ts","../../../../packages/primitives/src/lib/map-array.ts","../../../../packages/primitives/src/lib/mutable.ts","../../../../packages/primitives/src/mmstack-primitives.ts"],"sourcesContent":["import { Signal, untracked, WritableSignal } from '@angular/core';\n\n/**\n * Converts a read-only `Signal` into a `WritableSignal` by providing custom `set` and, optionally, `update` functions.\n * This can be useful for creating controlled write access to a signal that is otherwise read-only.\n *\n * @typeParam T - The type of value held by the signal.\n *\n * @param signal - The read-only `Signal` to be made writable.\n * @param set - A function that will be used to set the signal's value.  This function *must* handle\n *              the actual update mechanism (e.g., updating a backing store, emitting an event, etc.).\n * @param update - (Optional) A function that will be used to update the signal's value based on its\n *                 previous value.  If not provided, a default `update` implementation is used that\n *                 calls the provided `set` function with the result of the updater function. The\n *                 default implementation uses `untracked` to avoid creating unnecessary dependencies\n *                 within the updater function.\n *\n * @returns A `WritableSignal` that uses the provided `set` and `update` functions.  The `asReadonly`\n *          method of the returned signal will still return the original read-only signal.\n *\n * @example\n * // Basic usage: Making a read-only signal writable with a custom set function.\n * const originalValue = signal({a: 0});\n * const readOnlySignal = computed(() => originalValue().a);\n * const writableSignal = toWritable(readOnlySignal, (newValue) => {\n *  originalValue.update((prev) => { ...prev, a: newValue });\n * });\n *\n * writableSignal.set(5); // sets value of originalValue.a to 5 & triggers all signals\n */\nexport function toWritable<T>(\n  signal: Signal<T>,\n  set: (value: T) => void,\n  update?: (updater: (value: T) => T) => void,\n): WritableSignal<T> {\n  const internal = signal as WritableSignal<T>;\n  internal.asReadonly = () => signal;\n  internal.set = set;\n  internal.update = update ?? ((updater) => set(updater(untracked(internal))));\n\n  return internal;\n}\n","import {\n  computed,\n  type CreateSignalOptions,\n  signal,\n  untracked,\n  type WritableSignal,\n} from '@angular/core';\nimport { toWritable } from './to-writable';\n\n/**\n * A `DebouncedSignal` is a special type of `WritableSignal` that delays updates\n * to its value.  This is useful for scenarios where you want to avoid\n * frequent updates, such as responding to user input in a search field.\n * It keeps a reference to the original `WritableSignal` via the `original` property.\n *\n * @typeParam T - The type of value held by the signal.\n */\nexport type DebouncedSignal<T> = WritableSignal<T> & {\n  /**\n   * A reference to the original, un-debounced `WritableSignal`. This allows\n   * you to access the immediate value (without the debounce delay) if needed,\n   * and also ensures that any direct modifications to the original signal\n   * are reflected in the debounced signal after the debounce period.\n   */\n  original: WritableSignal<T>;\n};\n\n/**\n * Options for creating a debounced signal.\n *\n * @typeParam T - The type of value held by the signal.\n */\nexport type CreateDebouncedOptions<T> = CreateSignalOptions<T> & {\n  /**\n   * The debounce delay in milliseconds. Defaults to 300.\n   */\n  ms?: number;\n};\n\n/**\n * Creates a debounced signal. The signal's value will only be propagated to\n * subscribers after a specified delay (debounce time) has passed since the last\n * time it was set or updated.  Crucially, updates to the *original* signal\n * are also debounced.\n *\n * @see {@link DebouncedSignal}\n * @see {@link CreateDebouncedOptions}\n *\n * @example\n * ```typescript\n * // Create a debounced signal with an initial value and a custom delay.\n * const searchTerm = debounced('initial value', { ms: 500 });\n *\n * // Update the debounced signal. The actual update will be delayed by 500ms.\n * searchTerm.set('new value');\n *\n * // Access the original, un-debounced signal.\n * console.log(searchTerm.original()); // Outputs 'new value' (immediately)\n * // ... after 500ms ...\n * console.log(searchTerm()); // Outputs 'new value' (debounced)\n *\n * // Directly update the *original* signal.\n * searchTerm.original.set('direct update');\n * console.log(searchTerm.original()); // Outputs 'direct update' (immediately)\n * console.log(searchTerm()); // Outputs 'new value' (still debounced from the previous set)\n * // ... after 500ms ...\n * console.log(searchTerm()); // Outputs 'direct update' (now reflects the original signal)\n *\n * // Create a debounced signal with undefined initial value and default delay\n * const anotherSignal = debounced();\n * ```\n * @typeParam T - The type of the signal's value.\n * @param initial The initial value of the signal. Optional; defaults to `undefined`.\n * @param opt Configuration options for the signal, including the debounce delay (`ms`).\n * @returns A `DebouncedSignal` instance.\n */\nexport function debounced<T>(): DebouncedSignal<T | undefined>;\n/**\n * Creates a debounced signal with a defined initial value.\n *\n * @typeParam T - The type of the signal's value.\n * @param initial The initial value of the signal.\n * @param opt Configuration options for the signal, including the debounce delay (`ms`).\n * @returns A `DebouncedSignal` instance.\n */\nexport function debounced<T>(\n  initial: T,\n  opt?: CreateDebouncedOptions<T>,\n): DebouncedSignal<T>;\nexport function debounced<T>(\n  value?: T,\n  opt?: CreateDebouncedOptions<T | undefined>,\n): DebouncedSignal<T | undefined> {\n  const sig = signal<T | undefined>(value, opt) as DebouncedSignal<\n    T | undefined\n  >;\n  const ms = opt?.ms ?? 300;\n\n  let timeout: ReturnType<typeof setTimeout> | undefined;\n\n  const originalSet = sig.set;\n  const originalUpdate = sig.update;\n\n  const trigger = signal(false);\n\n  // Set on the original signal, then trigger the debounced update\n  const set = (value: T | undefined) => {\n    originalSet(value); // Update the *original* signal immediately\n\n    if (timeout) clearTimeout(timeout);\n    timeout = setTimeout(() => {\n      trigger.update((cur) => !cur); // Trigger the computed signal\n    }, ms);\n  };\n\n  // Update on the original signal, then trigger the debounced update\n  const update = (fn: (prev: T | undefined) => T | undefined) => {\n    originalUpdate(fn); // Update the *original* signal immediately\n\n    if (timeout) clearTimeout(timeout);\n    timeout = setTimeout(() => {\n      trigger.update((cur) => !cur); // Trigger the computed signal\n    }, ms);\n  };\n\n  // Create a computed signal that depends on the trigger.\n  // This computed signal is what provides the debounced behavior.\n  const writable = toWritable(\n    computed(() => {\n      trigger();\n      return untracked(sig);\n    }),\n    set,\n    update,\n  ) as DebouncedSignal<T | undefined>;\n\n  writable.original = sig;\n\n  return writable;\n}\n","import {\n  computed,\n  CreateSignalOptions,\n  signal,\n  untracked,\n  type WritableSignal,\n} from '@angular/core';\nimport type { UnknownObject } from '@mmstack/object';\nimport { toWritable } from './to-writable';\n\n/**\n * Options for creating a derived signal using the full `derived` function signature.\n * @typeParam T - The type of the source signal's value (parent).\n * @typeParam U - The type of the derived signal's value (child).\n */\ntype CreateDerivedOptions<T, U> = CreateSignalOptions<U> & {\n  /**\n   * A function that extracts the derived value (`U`) from the source signal's value (`T`).\n   */\n  from: (v: T) => U;\n  /**\n   * A function that updates the source signal's value (`T`) when the derived signal's value (`U`) changes.\n   * This establishes the two-way binding.\n   */\n  onChange: (newValue: U) => void;\n};\n\n/**\n * A `WritableSignal` that derives its value from another `WritableSignal` (the \"source\" signal).\n * It provides two-way binding: changes to the source signal update the derived signal, and\n * changes to the derived signal update the source signal.\n *\n * @typeParam T - The type of the source signal's value (parent).\n * @typeParam U - The type of the derived signal's value (child).\n */\nexport type DerivedSignal<T, U> = WritableSignal<U> & {\n  /**\n   * The function used to derive the derived signal's value from the source signal's value.\n   * This is primarily for internal use and introspection.\n   */\n  from: (v: T) => U;\n};\n\n/**\n * Creates a `DerivedSignal` that derives its value from another `WritableSignal` (the source signal).\n * This overload provides the most flexibility, allowing you to specify custom `from` and `onChange` functions.\n *\n * @typeParam T - The type of the source signal's value.\n * @typeParam U - The type of the derived signal's value.\n * @param source - The source `WritableSignal`.\n * @param options - An object containing the `from` and `onChange` functions, and optional signal options.\n * @returns A `DerivedSignal` instance.\n *\n * @example\n * const user = signal({ name: 'John', age: 30 });\n * const name = derived(user, {\n *   from: (u) => u.name,\n *   onChange: (newName) => user.update((u) => ({ ...u, name: newName })),\n * });\n */\nexport function derived<T, U>(\n  source: WritableSignal<T>,\n  opt: CreateDerivedOptions<T, U>,\n): DerivedSignal<T, U>;\n\n/**\n * Creates a `DerivedSignal` that derives a property from an object held by the source signal.\n * This overload simplifies creating derived signals for object properties.\n *\n * @typeParam T - The type of the source signal's value (must be an object).\n * @typeParam TKey - The key of the property to derive.\n * @param source - The source `WritableSignal` (holding an object).\n * @param key - The key of the property to derive.\n * @param options - Optional signal options for the derived signal.\n * @returns A `DerivedSignal` instance.\n *\n * @example\n * const user = signal({ name: 'John', age: 30 });\n * const name = derived(user, 'name');\n */\nexport function derived<T extends UnknownObject, TKey extends keyof T>(\n  source: WritableSignal<T>,\n  key: TKey,\n  opt?: CreateSignalOptions<T[TKey]>,\n): DerivedSignal<T, T[TKey]>;\n\n/**\n * Creates a `DerivedSignal` from an array, and derives an element by index.\n *\n * @typeParam T - The type of the source signal's value (must be an array).\n * @param source - The source `WritableSignal` (holding an array).\n * @param index - The index of the element to derive.\n * @param options - Optional signal options for the derived signal.\n * @returns A `DerivedSignal` instance.\n *\n * @example\n * const numbers = signal([1, 2, 3]);\n * const secondNumber = derived(numbers, 1); // secondNumber() === 2\n * secondNumber.set(5); // numbers() === [1, 5, 3]\n */\nexport function derived<T extends any[]>(\n  source: WritableSignal<T>,\n  index: number,\n  opt?: CreateSignalOptions<T[number]>,\n): DerivedSignal<T, T[number]>;\n\nexport function derived<T, U>(\n  source: WritableSignal<T>,\n  optOrKey: CreateDerivedOptions<T, U> | keyof T,\n  opt?: CreateSignalOptions<U>,\n): DerivedSignal<T, U> {\n  const isArray =\n    Array.isArray(untracked(source)) && typeof optOrKey === 'number';\n\n  const from =\n    typeof optOrKey === 'object' ? optOrKey.from : (v: T) => v[optOrKey] as U;\n  const onChange =\n    typeof optOrKey === 'object'\n      ? optOrKey.onChange\n      : isArray\n        ? (next: U) => {\n            source.update(\n              (cur) =>\n                (cur as unknown as any[]).map((v, i) =>\n                  i === optOrKey ? next : v,\n                ) as T,\n            );\n          }\n        : (next: U) => {\n            source.update((cur) => ({ ...cur, [optOrKey]: next }));\n          };\n\n  const rest = typeof optOrKey === 'object' ? optOrKey : opt;\n\n  const sig = toWritable<U>(\n    computed(() => from(source()), rest),\n    (newVal) => onChange(newVal),\n  ) as DerivedSignal<T, U>;\n\n  sig.from = from;\n\n  return sig;\n}\n\n/**\n * Creates a \"fake\" `DerivedSignal` from a simple value. This is useful for creating\n * `FormControlSignal` instances that are not directly derived from another signal.\n * The returned signal's `from` function will always return the initial value.\n *\n * @typeParam T -  This type parameter is not used in the implementation but is kept for type compatibility with `DerivedSignal`.\n * @typeParam U - The type of the signal's value.\n * @param initial - The initial value of the signal.\n * @returns A `DerivedSignal` instance.\n * @internal\n */\nexport function toFakeDerivation<T, U>(initial: U): DerivedSignal<T, U> {\n  const sig = signal(initial) as DerivedSignal<T, U>;\n  sig.from = () => initial;\n\n  return sig;\n}\n\n/**\n * Creates a \"fake\" `DerivedSignal` from an existing `WritableSignal`. This is useful\n * for treating a regular `WritableSignal` as a `DerivedSignal` without changing its behavior.\n *  The returned signal's `from` function returns the current value of signal, using `untracked`.\n *\n * @typeParam T - This type parameter is not used in the implementation but is kept for type compatibility with `DerivedSignal`.\n * @typeParam U - The type of the signal's value.\n * @param initial - The existing `WritableSignal`.\n * @returns A `DerivedSignal` instance.\n * @internal\n */\nexport function toFakeSignalDerivation<T, U>(\n  initial: WritableSignal<U>,\n): DerivedSignal<T, U> {\n  const sig = initial as DerivedSignal<T, U>;\n  sig.from = () => untracked(initial);\n  return sig;\n}\n\n/**\n * Type guard function to check if a given `WritableSignal` is a `DerivedSignal`.\n *\n * @typeParam T - The type of the source signal's value (optional, defaults to `any`).\n * @typeParam U - The type of the derived signal's value (optional, defaults to `any`).\n * @param sig - The `WritableSignal` to check.\n * @returns `true` if the signal is a `DerivedSignal`, `false` otherwise.\n */\nexport function isDerivation<T, U>(\n  sig: WritableSignal<U>,\n): sig is DerivedSignal<T, U> {\n  return 'from' in sig;\n}\n","import {\n  computed,\n  type CreateSignalOptions,\n  isSignal,\n  linkedSignal,\n  type Signal,\n} from '@angular/core';\n\n/**\n * Options for the mapArray function.\n * @template T The type of elements in the array.\n * @extends CreateSignalOptions<T> Inherits options for creating individual signals.\n */\nexport type MapArrayOptions<T> = CreateSignalOptions<T> & {\n  /**\n   * An optional function to transform each element from the source array.\n   * If not provided, the original element is used.\n   * @param source The current value of the source array signal.\n   * @param index The index of the element being mapped.\n   * @returns The transformed element for the corresponding signal.\n   */\n  map?: (source: T[], index: number) => T;\n};\n\nfunction createReconciler<T>(source: Signal<T[]>, opt?: MapArrayOptions<T>) {\n  const map = opt?.map ?? ((source, index) => source[index]);\n\n  return (\n    length: number,\n    prev?: {\n      value: Signal<T>[];\n      source: number;\n    },\n  ): Signal<T>[] => {\n    if (!prev)\n      return Array.from({ length }, (_, i) =>\n        computed(() => map(source(), i), opt),\n      );\n\n    if (length === prev.source) return prev.value;\n\n    if (length < prev.source) {\n      return prev.value.slice(0, length);\n    } else {\n      const next = [...prev.value];\n      for (let i = prev.source; i < length; i++) {\n        next.push(computed(() => map(source(), i), opt));\n      }\n\n      return next;\n    }\n  };\n}\n\n/**\n * Creates a reactive array of signals from a source array signal (or a function returning one),\n * applying an optional mapping function to each element.\n *\n * This is useful for scenarios like rendering lists where each item\n * needs its own reactive state derived from the source array. It efficiently\n * handles changes in the source array's length by reusing existing signals\n * for elements that remain, adding signals for new elements, and removing signals\n * for deleted elements.\n *\n * @template T The type of elements in the source array.\n * @param source A function that returns the source array (or readonly array).\n * This function will be tracked for changes.\n * @param opt Optional configuration including a `map` function to transform elements\n * and options (`CreateSignalOptions`) for the created signals.\n * @returns A signal (`Signal<Signal<T | undefined>[]>`) where the outer signal updates\n * when the array length changes, and the inner array contains signals\n * representing each element (potentially mapped).\n */\nexport function mapArray<T>(\n  source: () => T[],\n  opt?: MapArrayOptions<T | undefined>,\n): Signal<Signal<T | undefined>[]>;\n\n/**\n * Creates a reactive array of signals from a source readonly array (or a function returning one),\n * applying an optional mapping function to each element.\n *\n * This is useful for scenarios like rendering lists where each item\n * needs its own reactive state derived from the source array. It efficiently\n * handles changes in the source array's length by reusing existing signals\n * for elements that remain, adding signals for new elements, and removing signals\n * for deleted elements.\n *\n * @template T The type of elements in the source array.\n * @param source A function that returns the source readonly array.\n * This function will be tracked for changes.\n * @param opt Optional configuration including a `map` function to transform elements\n * and options (`CreateSignalOptions`) for the created signals.\n * @returns A signal (`Signal<Signal<T>[]>`) where the outer signal updates\n * when the array length changes, and the inner array contains signals\n * representing each element (potentially mapped).\n */\nexport function mapArray<T>(\n  source: () => readonly T[],\n  opt?: MapArrayOptions<T>,\n): Signal<Signal<T>[]>;\n\nexport function mapArray<T>(\n  source: (() => T[]) | (() => readonly T[]),\n  opt?: MapArrayOptions<T>,\n): Signal<Signal<T | undefined>[]> {\n  const data = isSignal(source) ? source : computed(source);\n  const length = computed(() => data().length);\n\n  const reconciler = createReconciler<T>(data as Signal<T[]>, opt);\n\n  return linkedSignal<number, Signal<T>[]>({\n    source: () => length(),\n    computation: (len, prev) => reconciler(len, prev),\n  });\n}\n","import {\r\n  signal,\r\n  type CreateSignalOptions,\r\n  type ValueEqualityFn,\r\n  type WritableSignal,\r\n} from '@angular/core';\r\n\r\nconst { is } = Object;\r\n\r\n/**\r\n * A `MutableSignal` is a special type of `WritableSignal` that allows for in-place mutation of its value.\r\n * In addition to the standard `set` and `update` methods, it provides a `mutate` method.  This is useful\r\n * for performance optimization when dealing with complex objects or arrays, as it avoids unnecessary\r\n * object copying.\r\n *\r\n * @typeParam T - The type of value held by the signal.\r\n */\r\nexport type MutableSignal<T> = WritableSignal<T> & {\r\n  /**\r\n   * Mutates the signal's value in-place.  This is similar to `update`, but it's optimized for\r\n   * scenarios where you want to modify the existing object directly rather than creating a new one.\r\n   *\r\n   * @param updater - A function that takes the current value as input and modifies it directly.\r\n   *\r\n   * @example\r\n   * const myArray = mutable([1, 2, 3]);\r\n   * myArray.mutate((arr) => {\r\n   *  arr.push(4);\r\n   *  return arr;\r\n   * }); // myArray() now returns [1, 2, 3, 4]\r\n   */\r\n  mutate: WritableSignal<T>['update'];\r\n\r\n  /**\r\n   * Mutates the signal's value in-place, similar to `mutate`, but with a void-returning value in updater\r\n   * function. This further emphasizes that the mutation is happening inline, improving readability\r\n   * in some cases.\r\n   * @param updater - Function to change to the current value\r\n   * @example\r\n   * const myObject = mutable({ a: 1, b: 2 });\r\n   * myObject.inline((obj) => (obj.a = 3)); // myObject() now returns { a: 3, b: 2 }\r\n   */\r\n  inline: (updater: Parameters<WritableSignal<T>['update']>[0]) => void;\r\n};\r\n\r\n/**\r\n * Creates a `MutableSignal`. This function overloads the standard `signal` function to provide\r\n * the additional `mutate` and `inline` methods.\r\n *\r\n * @typeParam T - The type of value held by the signal.\r\n *\r\n * @param initial - The initial value of the signal.  If no initial value is provided, it defaults to `undefined`.\r\n * @param options - Optional. An object containing signal options, including a custom equality function (`equal`).\r\n *\r\n * @returns A `MutableSignal` instance.\r\n *\r\n * @example\r\n * // Create a mutable signal with an initial value:\r\n * const mySignal = mutable({ count: 0 }) // MutableSignal<{ count: number }>;\r\n *\r\n * // Create a mutable signal with no initial value (starts as undefined):\r\n * const = mutable<number>(); // MutableSignal<number | undefined>\r\n *\r\n * // Create a mutable signal with a custom equality function:\r\n * const myCustomSignal = mutable({ a: 1 }, { equal: (a, b) => a.a === b.a });\r\n */\r\nexport function mutable<T>(): MutableSignal<T | undefined>;\r\nexport function mutable<T>(initial: T): MutableSignal<T>;\r\nexport function mutable<T>(\r\n  initial: T,\r\n  opt?: CreateSignalOptions<T>,\r\n): MutableSignal<T>;\r\n\r\nexport function mutable<T>(\r\n  initial?: T,\r\n  opt?: CreateSignalOptions<T>,\r\n): MutableSignal<T> {\r\n  const baseEqual = opt?.equal ?? is;\r\n  let trigger = false;\r\n\r\n  const equal: ValueEqualityFn<T | undefined> = (a, b) => {\r\n    if (trigger) return false;\r\n    return baseEqual(a, b);\r\n  };\r\n\r\n  const sig = signal<T | undefined>(initial, {\r\n    ...opt,\r\n    equal,\r\n  }) as MutableSignal<T>;\r\n\r\n  const internalUpdate = sig.update;\r\n\r\n  sig.mutate = (updater) => {\r\n    trigger = true;\r\n    internalUpdate(updater);\r\n    trigger = false;\r\n  };\r\n\r\n  sig.inline = (updater) => {\r\n    sig.mutate((prev) => {\r\n      updater(prev);\r\n      return prev;\r\n    });\r\n  };\r\n\r\n  return sig;\r\n}\r\n\r\n/**\r\n * Type guard function to check if a given `WritableSignal` is a `MutableSignal`.  This is useful\r\n * for situations where you need to conditionally use the `mutate` or `inline` methods.\r\n *\r\n * @typeParam T - The type of the signal's value (optional, defaults to `any`).\r\n * @param value - The `WritableSignal` to check.\r\n * @returns `true` if the signal is a `MutableSignal`, `false` otherwise.\r\n *\r\n * @example\r\n * const mySignal = signal(0);\r\n * const myMutableSignal = mutable(0);\r\n *\r\n * if (isMutable(mySignal)) {\r\n *   mySignal.mutate(x => x + 1); // This would cause a type error, as mySignal is not a MutableSignal.\r\n * }\r\n *\r\n * if (isMutable(myMutableSignal)) {\r\n *   myMutableSignal.mutate(x => x + 1); // This is safe.\r\n * }\r\n */\r\nexport function isMutable<T = any>(\r\n  value: WritableSignal<T>,\r\n): value is MutableSignal<T> {\r\n  return 'mutate' in value && typeof value.mutate === 'function';\r\n}\r\n","/**\n * Generated bundle index. Do not edit.\n */\n\nexport * from './index';\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"mmstack-primitives.mjs","sources":["../../../../packages/primitives/src/lib/to-writable.ts","../../../../packages/primitives/src/lib/debounced.ts","../../../../packages/primitives/src/lib/derived.ts","../../../../packages/primitives/src/lib/map-array.ts","../../../../packages/primitives/src/lib/mutable.ts","../../../../packages/primitives/src/lib/stored.ts","../../../../packages/primitives/src/mmstack-primitives.ts"],"sourcesContent":["import { Signal, untracked, WritableSignal } from '@angular/core';\n\n/**\n * Converts a read-only `Signal` into a `WritableSignal` by providing custom `set` and, optionally, `update` functions.\n * This can be useful for creating controlled write access to a signal that is otherwise read-only.\n *\n * @typeParam T - The type of value held by the signal.\n *\n * @param signal - The read-only `Signal` to be made writable.\n * @param set - A function that will be used to set the signal's value.  This function *must* handle\n *              the actual update mechanism (e.g., updating a backing store, emitting an event, etc.).\n * @param update - (Optional) A function that will be used to update the signal's value based on its\n *                 previous value.  If not provided, a default `update` implementation is used that\n *                 calls the provided `set` function with the result of the updater function. The\n *                 default implementation uses `untracked` to avoid creating unnecessary dependencies\n *                 within the updater function.\n *\n * @returns A `WritableSignal` that uses the provided `set` and `update` functions.  The `asReadonly`\n *          method of the returned signal will still return the original read-only signal.\n *\n * @example\n * // Basic usage: Making a read-only signal writable with a custom set function.\n * const originalValue = signal({a: 0});\n * const readOnlySignal = computed(() => originalValue().a);\n * const writableSignal = toWritable(readOnlySignal, (newValue) => {\n *  originalValue.update((prev) => { ...prev, a: newValue });\n * });\n *\n * writableSignal.set(5); // sets value of originalValue.a to 5 & triggers all signals\n */\nexport function toWritable<T>(\n  signal: Signal<T>,\n  set: (value: T) => void,\n  update?: (updater: (value: T) => T) => void,\n): WritableSignal<T> {\n  const internal = signal as WritableSignal<T>;\n  internal.asReadonly = () => signal;\n  internal.set = set;\n  internal.update = update ?? ((updater) => set(updater(untracked(internal))));\n\n  return internal;\n}\n","import {\n  computed,\n  type CreateSignalOptions,\n  type Signal,\n  signal,\n  type WritableSignal,\n} from '@angular/core';\nimport { toWritable } from './to-writable';\n\n/**\n * Options for creating a debounced writable signal.\n * Extends Angular's `CreateSignalOptions` with a debounce time setting.\n *\n * @template T The type of value held by the signal.\n */\nexport type CreateDebouncedOptions<T> = CreateSignalOptions<T> & {\n  /**\n   * The debounce delay in milliseconds. Specifies how long to wait after the\n   * last `set` or `update` call before the debounced signal reflects the new value.\n   */\n  ms?: number;\n};\n\n/**\n * A specialized `WritableSignal` whose publicly readable value updates are debounced.\n *\n * It provides access to the underlying, non-debounced signal via the `original` property.\n *\n * @template T The type of value held by the signal.\n */\nexport type DebouncedSignal<T> = WritableSignal<T> & {\n  /**\n   * A reference to the original, inner `WritableSignal`.\n   * This signal's value is updated *immediately* upon calls to `set` or `update`\n   * on the parent `DebouncedSignal`. Useful for accessing the latest value\n   * without the debounce delay.\n   */\n  original: Signal<T>;\n};\n\n/**\n * Creates a `WritableSignal` whose publicly readable value is updated only after\n * a specified debounce period (`ms`) has passed since the last call to its\n * `.set()` or `.update()` method.\n *\n * This implementation avoids using `effect` by leveraging intermediate `computed`\n * signals and a custom `equal` function to delay value propagation based on a timer.\n *\n * @template T The type of value the signal holds.\n * @param initial The initial value of the signal.\n * @param opt Options for signal creation, including:\n * - `ms`: The debounce time in milliseconds. Defaults to 0 if omitted (no debounce).\n * - Other `CreateSignalOptions` (like `equal`) are passed to underlying signals.\n * @returns A `DebouncedSignal<T>` instance. Its readable value updates are debounced,\n * and it includes an `.original` property providing immediate access to the latest set value.\n *\n * @example\n * ```ts\n * import { effect } from '@angular/core';\n *\n * // Create a debounced signal with a 500ms delay\n * const query = debounced('', { ms: 500 });\n *\n * effect(() => {\n * // This effect runs 500ms after the last change to 'query'\n * console.log('Debounced Query:', query());\n * });\n *\n * effect(() => {\n * // This effect runs immediately when 'query.original' changes\n * console.log('Original Query:', query.original());\n * });\n *\n * console.log('Setting query to \"a\"');\n * query.set('a');\n * // Output: Original Query: a\n *\n * setTimeout(() => {\n * console.log('Setting query to \"ab\"');\n * query.set('ab');\n * // Output: Original Query: ab\n * }, 200); // Before debounce timeout\n *\n * setTimeout(() => {\n * console.log('Setting query to \"abc\"');\n * query.set('abc');\n * // Output: Original Query: abc\n * }, 400); // Before debounce timeout\n *\n * // ~500ms after the *last* set (at 400ms), the debounced effect runs:\n * // Output (at ~900ms): Debounced Query: abc\n * ```\n */\nexport function debounced<T>(\n  initial: T,\n  opt: CreateDebouncedOptions<T>,\n): DebouncedSignal<T> {\n  const internal = signal(initial, opt);\n  const ms = opt.ms ?? 0;\n\n  const trigger = signal(false);\n\n  let timeout: ReturnType<typeof setTimeout> | undefined;\n\n  const set = (value: T) => {\n    if (timeout) clearTimeout(timeout);\n    internal.set(value);\n\n    timeout = setTimeout(() => {\n      trigger.update((c) => !c);\n    }, ms);\n  };\n\n  const update = (fn: (prev: T) => T) => {\n    if (timeout) clearTimeout(timeout);\n    internal.update(fn);\n\n    timeout = setTimeout(() => {\n      trigger.update((c) => !c);\n    }, ms);\n  };\n\n  const stable = computed(\n    () => ({\n      trigger: trigger(),\n      value: internal(),\n    }),\n    {\n      equal: (a, b) => a.trigger === b.trigger,\n    },\n  );\n\n  const writable = toWritable(\n    computed(() => stable().value, opt),\n    set,\n    update,\n  ) as DebouncedSignal<T>;\n  writable.original = internal;\n\n  return writable;\n}\n","import {\n  computed,\n  CreateSignalOptions,\n  signal,\n  untracked,\n  type WritableSignal,\n} from '@angular/core';\nimport type { UnknownObject } from '@mmstack/object';\nimport { toWritable } from './to-writable';\n\n/**\n * Options for creating a derived signal using the full `derived` function signature.\n * @typeParam T - The type of the source signal's value (parent).\n * @typeParam U - The type of the derived signal's value (child).\n */\ntype CreateDerivedOptions<T, U> = CreateSignalOptions<U> & {\n  /**\n   * A function that extracts the derived value (`U`) from the source signal's value (`T`).\n   */\n  from: (v: T) => U;\n  /**\n   * A function that updates the source signal's value (`T`) when the derived signal's value (`U`) changes.\n   * This establishes the two-way binding.\n   */\n  onChange: (newValue: U) => void;\n};\n\n/**\n * A `WritableSignal` that derives its value from another `WritableSignal` (the \"source\" signal).\n * It provides two-way binding: changes to the source signal update the derived signal, and\n * changes to the derived signal update the source signal.\n *\n * @typeParam T - The type of the source signal's value (parent).\n * @typeParam U - The type of the derived signal's value (child).\n */\nexport type DerivedSignal<T, U> = WritableSignal<U> & {\n  /**\n   * The function used to derive the derived signal's value from the source signal's value.\n   * This is primarily for internal use and introspection.\n   */\n  from: (v: T) => U;\n};\n\n/**\n * Creates a `DerivedSignal` that derives its value from another `WritableSignal` (the source signal).\n * This overload provides the most flexibility, allowing you to specify custom `from` and `onChange` functions.\n *\n * @typeParam T - The type of the source signal's value.\n * @typeParam U - The type of the derived signal's value.\n * @param source - The source `WritableSignal`.\n * @param options - An object containing the `from` and `onChange` functions, and optional signal options.\n * @returns A `DerivedSignal` instance.\n *\n * @example\n * const user = signal({ name: 'John', age: 30 });\n * const name = derived(user, {\n *   from: (u) => u.name,\n *   onChange: (newName) => user.update((u) => ({ ...u, name: newName })),\n * });\n */\nexport function derived<T, U>(\n  source: WritableSignal<T>,\n  opt: CreateDerivedOptions<T, U>,\n): DerivedSignal<T, U>;\n\n/**\n * Creates a `DerivedSignal` that derives a property from an object held by the source signal.\n * This overload simplifies creating derived signals for object properties.\n *\n * @typeParam T - The type of the source signal's value (must be an object).\n * @typeParam TKey - The key of the property to derive.\n * @param source - The source `WritableSignal` (holding an object).\n * @param key - The key of the property to derive.\n * @param options - Optional signal options for the derived signal.\n * @returns A `DerivedSignal` instance.\n *\n * @example\n * const user = signal({ name: 'John', age: 30 });\n * const name = derived(user, 'name');\n */\nexport function derived<T extends UnknownObject, TKey extends keyof T>(\n  source: WritableSignal<T>,\n  key: TKey,\n  opt?: CreateSignalOptions<T[TKey]>,\n): DerivedSignal<T, T[TKey]>;\n\n/**\n * Creates a `DerivedSignal` from an array, and derives an element by index.\n *\n * @typeParam T - The type of the source signal's value (must be an array).\n * @param source - The source `WritableSignal` (holding an array).\n * @param index - The index of the element to derive.\n * @param options - Optional signal options for the derived signal.\n * @returns A `DerivedSignal` instance.\n *\n * @example\n * const numbers = signal([1, 2, 3]);\n * const secondNumber = derived(numbers, 1); // secondNumber() === 2\n * secondNumber.set(5); // numbers() === [1, 5, 3]\n */\nexport function derived<T extends any[]>(\n  source: WritableSignal<T>,\n  index: number,\n  opt?: CreateSignalOptions<T[number]>,\n): DerivedSignal<T, T[number]>;\n\nexport function derived<T, U>(\n  source: WritableSignal<T>,\n  optOrKey: CreateDerivedOptions<T, U> | keyof T,\n  opt?: CreateSignalOptions<U>,\n): DerivedSignal<T, U> {\n  const isArray =\n    Array.isArray(untracked(source)) && typeof optOrKey === 'number';\n\n  const from =\n    typeof optOrKey === 'object' ? optOrKey.from : (v: T) => v[optOrKey] as U;\n  const onChange =\n    typeof optOrKey === 'object'\n      ? optOrKey.onChange\n      : isArray\n        ? (next: U) => {\n            source.update(\n              (cur) =>\n                (cur as unknown as any[]).map((v, i) =>\n                  i === optOrKey ? next : v,\n                ) as T,\n            );\n          }\n        : (next: U) => {\n            source.update((cur) => ({ ...cur, [optOrKey]: next }));\n          };\n\n  const rest = typeof optOrKey === 'object' ? optOrKey : opt;\n\n  const sig = toWritable<U>(\n    computed(() => from(source()), rest),\n    (newVal) => onChange(newVal),\n  ) as DerivedSignal<T, U>;\n\n  sig.from = from;\n\n  return sig;\n}\n\n/**\n * Creates a \"fake\" `DerivedSignal` from a simple value. This is useful for creating\n * `FormControlSignal` instances that are not directly derived from another signal.\n * The returned signal's `from` function will always return the initial value.\n *\n * @typeParam T -  This type parameter is not used in the implementation but is kept for type compatibility with `DerivedSignal`.\n * @typeParam U - The type of the signal's value.\n * @param initial - The initial value of the signal.\n * @returns A `DerivedSignal` instance.\n * @internal\n */\nexport function toFakeDerivation<T, U>(initial: U): DerivedSignal<T, U> {\n  const sig = signal(initial) as DerivedSignal<T, U>;\n  sig.from = () => initial;\n\n  return sig;\n}\n\n/**\n * Creates a \"fake\" `DerivedSignal` from an existing `WritableSignal`. This is useful\n * for treating a regular `WritableSignal` as a `DerivedSignal` without changing its behavior.\n *  The returned signal's `from` function returns the current value of signal, using `untracked`.\n *\n * @typeParam T - This type parameter is not used in the implementation but is kept for type compatibility with `DerivedSignal`.\n * @typeParam U - The type of the signal's value.\n * @param initial - The existing `WritableSignal`.\n * @returns A `DerivedSignal` instance.\n * @internal\n */\nexport function toFakeSignalDerivation<T, U>(\n  initial: WritableSignal<U>,\n): DerivedSignal<T, U> {\n  const sig = initial as DerivedSignal<T, U>;\n  sig.from = () => untracked(initial);\n  return sig;\n}\n\n/**\n * Type guard function to check if a given `WritableSignal` is a `DerivedSignal`.\n *\n * @typeParam T - The type of the source signal's value (optional, defaults to `any`).\n * @typeParam U - The type of the derived signal's value (optional, defaults to `any`).\n * @param sig - The `WritableSignal` to check.\n * @returns `true` if the signal is a `DerivedSignal`, `false` otherwise.\n */\nexport function isDerivation<T, U>(\n  sig: WritableSignal<U>,\n): sig is DerivedSignal<T, U> {\n  return 'from' in sig;\n}\n","import {\n  computed,\n  type CreateSignalOptions,\n  isSignal,\n  linkedSignal,\n  type Signal,\n} from '@angular/core';\n\n/**\n * Reactively maps items from a source array (or signal of an array) using a provided mapping function.\n *\n * This function serves a similar purpose to SolidJS's `mapArray` by providing stability\n * for mapped items. It receives a source function returning an array (or a Signal<T[]>)\n * and a mapping function.\n *\n * For each item in the source array, it creates a stable `computed` signal representing\n * that item's value at its current index. This stable signal (`Signal<T>`) is passed\n * to the mapping function. This ensures that downstream computations or components\n * depending on the mapped result only re-render or re-calculate for the specific items\n * that have changed, or when items are added/removed, rather than re-evaluating everything\n * when the source array reference changes but items remain the same.\n *\n * It efficiently handles changes in the source array's length by reusing existing mapped\n * results when possible, slicing when the array shrinks, and appending new mapped items\n * when it grows.\n *\n * @template T The type of items in the source array.\n * @template U The type of items in the resulting mapped array.\n *\n * @param source A function returning the source array `T[]`, or a `Signal<T[]>` itself.\n * The `mapArray` function will reactively update based on changes to this source.\n * @param map The mapping function. It is called for each item in the source array.\n * It receives:\n * - `value`: A stable `Signal<T>` representing the item at the current index.\n * Use this signal within your mapping logic if you need reactivity\n * tied to the specific item's value changes.\n * - `index`: The number index of the item in the array.\n * It should return the mapped value `U`.\n * @param [opt] Optional `CreateSignalOptions<T>`. These options are passed directly\n * to the `computed` signal created for each individual item (`Signal<T>`).\n * This allows specifying options like a custom `equal` function for item comparison.\n *\n * @returns A `Signal<U[]>` containing the mapped array. This signal updates whenever\n * the source array changes (either length or the values of its items).\n *\n * @example\n * ```ts\n * const sourceItems = signal([\n * { id: 1, name: 'Apple' },\n * { id: 2, name: 'Banana' }\n * ]);\n *\n * const mappedItems = mapArray(\n * sourceItems,\n * (itemSignal, index) => {\n * // itemSignal is stable for a given item based on its index.\n * // We create a computed here to react to changes in the item's name.\n *  return computed(() => `${index}: ${itemSignal().name.toUpperCase()}`);\n * },\n * // Example optional options (e.g., custom equality for item signals)\n * { equal: (a, b) => a.id === b.id && a.name === b.name }\n * );\n * ```\n */\nexport function mapArray<T, U>(\n  source: () => T[],\n  map: (value: Signal<T>, index: number) => U,\n  opt?: CreateSignalOptions<T>,\n): Signal<U[]> {\n  const data = isSignal(source) ? source : computed(source);\n  const len = computed(() => data().length);\n\n  return linkedSignal<number, U[]>({\n    source: () => len(),\n    computation: (len, prev) => {\n      if (!prev)\n        return Array.from({ length: len }, (_, i) =>\n          map(\n            computed(() => source()[i], opt),\n            i,\n          ),\n        );\n\n      if (len === prev.value.length) return prev.value;\n\n      if (len < prev.value.length) {\n        return prev.value.slice(0, len);\n      } else {\n        const next = [...prev.value];\n        for (let i = prev.value.length; i < len; i++) {\n          next[i] = map(\n            computed(() => source()[i], opt),\n            i,\n          );\n        }\n        return next;\n      }\n    },\n    equal: (a, b) => a.length === b.length,\n  });\n}\n","import {\r\n  signal,\r\n  type CreateSignalOptions,\r\n  type ValueEqualityFn,\r\n  type WritableSignal,\r\n} from '@angular/core';\r\n\r\nconst { is } = Object;\r\n\r\n/**\r\n * A `MutableSignal` is a special type of `WritableSignal` that allows for in-place mutation of its value.\r\n * In addition to the standard `set` and `update` methods, it provides a `mutate` method.  This is useful\r\n * for performance optimization when dealing with complex objects or arrays, as it avoids unnecessary\r\n * object copying.\r\n *\r\n * @typeParam T - The type of value held by the signal.\r\n */\r\nexport type MutableSignal<T> = WritableSignal<T> & {\r\n  /**\r\n   * Mutates the signal's value in-place.  This is similar to `update`, but it's optimized for\r\n   * scenarios where you want to modify the existing object directly rather than creating a new one.\r\n   *\r\n   * @param updater - A function that takes the current value as input and modifies it directly.\r\n   *\r\n   * @example\r\n   * const myArray = mutable([1, 2, 3]);\r\n   * myArray.mutate((arr) => {\r\n   *  arr.push(4);\r\n   *  return arr;\r\n   * }); // myArray() now returns [1, 2, 3, 4]\r\n   */\r\n  mutate: WritableSignal<T>['update'];\r\n\r\n  /**\r\n   * Mutates the signal's value in-place, similar to `mutate`, but with a void-returning value in updater\r\n   * function. This further emphasizes that the mutation is happening inline, improving readability\r\n   * in some cases.\r\n   * @param updater - Function to change to the current value\r\n   * @example\r\n   * const myObject = mutable({ a: 1, b: 2 });\r\n   * myObject.inline((obj) => (obj.a = 3)); // myObject() now returns { a: 3, b: 2 }\r\n   */\r\n  inline: (updater: (value: T) => void) => void;\r\n};\r\n\r\n/**\r\n * Creates a `MutableSignal`. This function overloads the standard `signal` function to provide\r\n * the additional `mutate` and `inline` methods.\r\n *\r\n * @typeParam T - The type of value held by the signal.\r\n *\r\n * @param initial - The initial value of the signal.  If no initial value is provided, it defaults to `undefined`.\r\n * @param options - Optional. An object containing signal options, including a custom equality function (`equal`).\r\n *\r\n * @returns A `MutableSignal` instance.\r\n *\r\n * @example\r\n * // Create a mutable signal with an initial value:\r\n * const mySignal = mutable({ count: 0 }) // MutableSignal<{ count: number }>;\r\n *\r\n * // Create a mutable signal with no initial value (starts as undefined):\r\n * const = mutable<number>(); // MutableSignal<number | undefined>\r\n *\r\n * // Create a mutable signal with a custom equality function:\r\n * const myCustomSignal = mutable({ a: 1 }, { equal: (a, b) => a.a === b.a });\r\n */\r\nexport function mutable<T>(): MutableSignal<T | undefined>;\r\nexport function mutable<T>(initial: T): MutableSignal<T>;\r\nexport function mutable<T>(\r\n  initial: T,\r\n  opt?: CreateSignalOptions<T>,\r\n): MutableSignal<T>;\r\n\r\nexport function mutable<T>(\r\n  initial?: T,\r\n  opt?: CreateSignalOptions<T>,\r\n): MutableSignal<T> {\r\n  const baseEqual = opt?.equal ?? is;\r\n  let trigger = false;\r\n\r\n  const equal: ValueEqualityFn<T | undefined> = (a, b) => {\r\n    if (trigger) return false;\r\n    return baseEqual(a, b);\r\n  };\r\n\r\n  const sig = signal<T | undefined>(initial, {\r\n    ...opt,\r\n    equal,\r\n  }) as MutableSignal<T>;\r\n\r\n  const internalUpdate = sig.update;\r\n\r\n  sig.mutate = (updater) => {\r\n    trigger = true;\r\n    internalUpdate(updater);\r\n    trigger = false;\r\n  };\r\n\r\n  sig.inline = (updater) => {\r\n    sig.mutate((prev) => {\r\n      updater(prev);\r\n      return prev;\r\n    });\r\n  };\r\n\r\n  return sig;\r\n}\r\n\r\n/**\r\n * Type guard function to check if a given `WritableSignal` is a `MutableSignal`.  This is useful\r\n * for situations where you need to conditionally use the `mutate` or `inline` methods.\r\n *\r\n * @typeParam T - The type of the signal's value (optional, defaults to `any`).\r\n * @param value - The `WritableSignal` to check.\r\n * @returns `true` if the signal is a `MutableSignal`, `false` otherwise.\r\n *\r\n * @example\r\n * const mySignal = signal(0);\r\n * const myMutableSignal = mutable(0);\r\n *\r\n * if (isMutable(mySignal)) {\r\n *   mySignal.mutate(x => x + 1); // This would cause a type error, as mySignal is not a MutableSignal.\r\n * }\r\n *\r\n * if (isMutable(myMutableSignal)) {\r\n *   myMutableSignal.mutate(x => x + 1); // This is safe.\r\n * }\r\n */\r\nexport function isMutable<T = any>(\r\n  value: WritableSignal<T>,\r\n): value is MutableSignal<T> {\r\n  return 'mutate' in value && typeof value.mutate === 'function';\r\n}\r\n","import { isPlatformServer } from '@angular/common';\nimport {\n  computed,\n  DestroyRef,\n  effect,\n  inject,\n  isDevMode,\n  isSignal,\n  PLATFORM_ID,\n  Signal,\n  signal,\n  untracked,\n  type CreateSignalOptions,\n  type WritableSignal,\n} from '@angular/core';\nimport { toWritable } from './to-writable';\n\n/**\n * Interface for storage mechanisms compatible with the `stored` signal.\n * Matches the essential parts of the `Storage` interface (`localStorage`, `sessionStorage`).\n */\ntype Store = {\n  /** Retrieves an item from storage for a given key. */\n  getItem: (key: string) => string | null;\n  /** Sets an item in storage for a given key. */\n  setItem: (key: string, value: string) => void;\n  /** Removes an item from storage for a given key. */\n  removeItem: (key: string) => void;\n};\n\n// Internal dummy store for server-side rendering\nconst noopStore: Store = {\n  getItem: () => null,\n  setItem: () => {\n    /* noop */\n  },\n  removeItem: () => {\n    /* noop */\n  },\n};\n\n/**\n * Options for creating a signal synchronized with persistent storage using `stored()`.\n * Extends Angular's `CreateSignalOptions`.\n *\n * @template T The type of value held by the signal.\n */\nexport type CreateStoredOptions<T> = CreateSignalOptions<T> & {\n  /**\n   * The key used to identify the item in storage.\n   * Can be a static string or a function/signal returning a string for dynamic keys\n   * (e.g., based on user ID or other application state).\n   */\n  key: string | (() => string);\n  /**\n   * Optional custom storage implementation (e.g., `sessionStorage` or a custom adapter).\n   * Must conform to the `Store` interface (`getItem`, `setItem`, `removeItem`).\n   * Defaults to `localStorage` in browser environments and a no-op store on the server.\n   */\n  store?: Store;\n  /**\n   * Optional function to serialize the value (type `T`) into a string before storing.\n   * Defaults to `JSON.stringify`.\n   * @param {T} value The value to serialize.\n   * @returns {string} The serialized string representation.\n   */\n  serialize?: (value: T) => string;\n  /**\n   * Optional function to deserialize the string retrieved from storage back into the value (type `T`).\n   * Defaults to `JSON.parse`.\n   * @param {string} value The string retrieved from storage.\n   * @returns {T} The deserialized value.\n   */\n  deserialize?: (value: string) => T;\n  /**\n   * If `true`, the signal will attempt to synchronize its state across multiple browser tabs\n   * using the `storage` event. Changes made in one tab (set, update, clear) will be\n   * reflected in other tabs using the same storage key.\n   * Requires a browser environment. Defaults to `false`.\n   */\n  syncTabs?: boolean;\n};\n\n/**\n * A specialized `WritableSignal` returned by the `stored()` function.\n * It synchronizes its value with persistent storage and provides additional methods.\n *\n * @template T The type of value held by the signal (matches the fallback type).\n */\nexport type StoredSignal<T> = WritableSignal<T> & {\n  /**\n   * Removes the item associated with the signal's key from the configured storage.\n   * After clearing, reading the signal will return the fallback value until it's set again.\n   */\n  clear: () => void;\n  /**\n   * A `Signal<string>` containing the current storage key being used by this stored signal.\n   * This is particularly useful if the key was configured dynamically. You can read or react\n   * to this signal to know the active key.\n   */\n  key: Signal<string>;\n};\n\n/**\n * Creates a `WritableSignal` whose state is automatically synchronized with persistent storage\n * (like `localStorage` or `sessionStorage`).\n *\n * It handles Server-Side Rendering (SSR) gracefully, allows dynamic storage keys,\n * custom serialization/deserialization, custom storage providers, and optional\n * synchronization across browser tabs.\n *\n * @template T The type of value held by the signal and stored (after serialization).\n * @param fallback The default value of type `T` to use when no value is found in storage\n * or when deserialization fails. The signal's value will never be `null` or `undefined`\n * publicly, it will always revert to this fallback.\n * @param options Configuration options (`CreateStoredOptions<T>`). Requires at least the `key`.\n * @returns A `StoredSignal<T>` instance. This signal behaves like a standard `WritableSignal<T>`,\n * but its value is persisted. It includes a `.clear()` method to remove the item from storage\n * and a `.key` signal providing the current storage key.\n *\n * @remarks\n * - **Persistence:** The signal automatically saves its value to storage whenever the signal's\n * value or its configured `key` changes. This is managed internally using `effect`.\n * - **SSR Safety:** Detects server environments and uses a no-op storage, preventing errors.\n * - **Error Handling:** Catches and logs errors during serialization/deserialization in dev mode.\n * - **Tab Sync:** If `syncTabs` is true, listens to `storage` events to keep the signal value\n * consistent across browser tabs using the same key. Cleanup is handled automatically\n * using `DestroyRef`.\n * - **Removal:** Use the `.clear()` method on the returned signal to remove the item from storage.\n * Setting the signal to the fallback value will store the fallback value, not remove the item.\n *\n * @example\n * ```ts\n * import { Component, effect, signal } from '@angular/core';\n * import { stored } from '@mmstack/primitives'; // Adjust import path\n *\n * @Component({\n * selector: 'app-settings',\n * standalone: true,\n * template: `\n * Theme:\n * <select [ngModel]=\"theme()\" (ngModelChange)=\"theme.set($event)\">\n * <option value=\"light\">Light</option>\n * <option value=\"dark\">Dark</option>\n * </select>\n * <button (click)=\"theme.clear()\">Clear Theme Setting</button>\n * <p>Storage Key Used: {{ theme.key() }}</p>\n * ` // Requires FormsModule for ngModel\n * })\n * export class SettingsComponent {\n *  theme = stored<'light' | 'dark'>('light', { key: 'app-theme', syncTabs: true });\n * }\n * ```\n */\nexport function stored<T>(\n  fallback: T,\n  {\n    key,\n    store: providedStore,\n    serialize = JSON.stringify,\n    deserialize = JSON.parse,\n    syncTabs = false,\n    equal = Object.is,\n    ...rest\n  }: CreateStoredOptions<T>,\n): StoredSignal<T> {\n  const isServer = isPlatformServer(inject(PLATFORM_ID));\n\n  const fallbackStore = isServer ? noopStore : localStorage;\n  const store = providedStore ?? fallbackStore;\n\n  const keySig =\n    typeof key === 'string'\n      ? computed(() => key)\n      : isSignal(key)\n        ? key\n        : computed(key);\n\n  const getValue = (key: string): T | null => {\n    const found = store.getItem(key);\n    if (found === null) return null;\n    try {\n      return deserialize(found);\n    } catch (err) {\n      if (isDevMode())\n        console.error(`Failed to parse stored value for key \"${key}\":`, err);\n      return null;\n    }\n  };\n\n  const storeValue = (key: string, value: T | null) => {\n    try {\n      if (value === null) return store.removeItem(key);\n      const serialized = serialize(value);\n      store.setItem(key, serialized);\n    } catch (err) {\n      if (isDevMode())\n        console.error(`Failed to store value for key \"${key}\":`, err);\n    }\n  };\n\n  const opt = {\n    ...rest,\n    equal,\n  };\n\n  const internal = signal(getValue(untracked(keySig)), {\n    ...opt,\n    equal: (a, b) => {\n      if (a === null && b === null) return true;\n      if (a === null || b === null) return false;\n      return equal(a, b);\n    },\n  });\n\n  effect(() => storeValue(keySig(), internal()));\n\n  if (syncTabs && !isServer) {\n    const destroyRef = inject(DestroyRef);\n    const sync = (e: StorageEvent) => {\n      if (e.key !== untracked(keySig)) return;\n\n      if (e.newValue === null) internal.set(null);\n      else internal.set(getValue(e.key));\n    };\n\n    window.addEventListener('storage', sync);\n\n    destroyRef.onDestroy(() => window.removeEventListener('storage', sync));\n  }\n\n  const writable = toWritable<T>(\n    computed(() => internal() ?? fallback, opt),\n    internal.set,\n  ) as StoredSignal<T>;\n\n  writable.clear = () => {\n    internal.set(null);\n  };\n  writable.key = keySig;\n  return writable;\n}\n","/**\n * Generated bundle index. Do not edit.\n */\n\nexport * from './index';\n"],"names":[],"mappings":"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"}

package/index.d.ts

@@ -2,4 +2,5 @@ export * from './lib/debounced';
 export * from './lib/derived';
 export * from './lib/map-array';
 export * from './lib/mutable';
+export * from './lib/stored';
 export * from './lib/to-writable';

package/lib/debounced.d.ts

@@ -1,76 +1,84 @@
-import { type CreateSignalOptions, type WritableSignal } from '@angular/core';
+import { type CreateSignalOptions, type Signal, type WritableSignal } from '@angular/core';
 /**
- * A `DebouncedSignal` is a special type of `WritableSignal` that delays updates
- * to its value.  This is useful for scenarios where you want to avoid
- * frequent updates, such as responding to user input in a search field.
- * It keeps a reference to the original `WritableSignal` via the `original` property.
+ * Options for creating a debounced writable signal.
+ * Extends Angular's `CreateSignalOptions` with a debounce time setting.
  *
- * @typeParam T - The type of value held by the signal.
+ * @template T The type of value held by the signal.
  */
-export type DebouncedSignal<T> = WritableSignal<T> & {
+export type CreateDebouncedOptions<T> = CreateSignalOptions<T> & {
     /**
-     * A reference to the original, un-debounced `WritableSignal`. This allows
-     * you to access the immediate value (without the debounce delay) if needed,
-     * and also ensures that any direct modifications to the original signal
-     * are reflected in the debounced signal after the debounce period.
+     * The debounce delay in milliseconds. Specifies how long to wait after the
+     * last `set` or `update` call before the debounced signal reflects the new value.
      */
-    original: WritableSignal<T>;
+    ms?: number;
 };
 /**
- * Options for creating a debounced signal.
+ * A specialized `WritableSignal` whose publicly readable value updates are debounced.
+ *
+ * It provides access to the underlying, non-debounced signal via the `original` property.
  *
- * @typeParam T - The type of value held by the signal.
+ * @template T The type of value held by the signal.
  */
-export type CreateDebouncedOptions<T> = CreateSignalOptions<T> & {
+export type DebouncedSignal<T> = WritableSignal<T> & {
     /**
-     * The debounce delay in milliseconds. Defaults to 300.
+     * A reference to the original, inner `WritableSignal`.
+     * This signal's value is updated *immediately* upon calls to `set` or `update`
+     * on the parent `DebouncedSignal`. Useful for accessing the latest value
+     * without the debounce delay.
      */
-    ms?: number;
+    original: Signal<T>;
 };
 /**
- * Creates a debounced signal. The signal's value will only be propagated to
- * subscribers after a specified delay (debounce time) has passed since the last
- * time it was set or updated.  Crucially, updates to the *original* signal
- * are also debounced.
+ * Creates a `WritableSignal` whose publicly readable value is updated only after
+ * a specified debounce period (`ms`) has passed since the last call to its
+ * `.set()` or `.update()` method.
+ *
+ * This implementation avoids using `effect` by leveraging intermediate `computed`
+ * signals and a custom `equal` function to delay value propagation based on a timer.
  *
- * @see {@link DebouncedSignal}
- * @see {@link CreateDebouncedOptions}
+ * @template T The type of value the signal holds.
+ * @param initial The initial value of the signal.
+ * @param opt Options for signal creation, including:
+ * - `ms`: The debounce time in milliseconds. Defaults to 0 if omitted (no debounce).
+ * - Other `CreateSignalOptions` (like `equal`) are passed to underlying signals.
+ * @returns A `DebouncedSignal<T>` instance. Its readable value updates are debounced,
+ * and it includes an `.original` property providing immediate access to the latest set value.
  *
  * @example
- * ```typescript
- * // Create a debounced signal with an initial value and a custom delay.
- * const searchTerm = debounced('initial value', { ms: 500 });
+ * ```ts
+ * import { effect } from '@angular/core';
  *
- * // Update the debounced signal. The actual update will be delayed by 500ms.
- * searchTerm.set('new value');
+ * // Create a debounced signal with a 500ms delay
+ * const query = debounced('', { ms: 500 });
  *
- * // Access the original, un-debounced signal.
- * console.log(searchTerm.original()); // Outputs 'new value' (immediately)
- * // ... after 500ms ...
- * console.log(searchTerm()); // Outputs 'new value' (debounced)
+ * effect(() => {
+ * // This effect runs 500ms after the last change to 'query'
+ * console.log('Debounced Query:', query());
+ * });
  *
- * // Directly update the *original* signal.
- * searchTerm.original.set('direct update');
- * console.log(searchTerm.original()); // Outputs 'direct update' (immediately)
- * console.log(searchTerm()); // Outputs 'new value' (still debounced from the previous set)
- * // ... after 500ms ...
- * console.log(searchTerm()); // Outputs 'direct update' (now reflects the original signal)
+ * effect(() => {
+ * // This effect runs immediately when 'query.original' changes
+ * console.log('Original Query:', query.original());
+ * });
  *
- * // Create a debounced signal with undefined initial value and default delay
- * const anotherSignal = debounced();
- * ```
- * @typeParam T - The type of the signal's value.
- * @param initial The initial value of the signal. Optional; defaults to `undefined`.
- * @param opt Configuration options for the signal, including the debounce delay (`ms`).
- * @returns A `DebouncedSignal` instance.
- */
-export declare function debounced<T>(): DebouncedSignal<T | undefined>;
-/**
- * Creates a debounced signal with a defined initial value.
+ * console.log('Setting query to "a"');
+ * query.set('a');
+ * // Output: Original Query: a
  *
- * @typeParam T - The type of the signal's value.
- * @param initial The initial value of the signal.
- * @param opt Configuration options for the signal, including the debounce delay (`ms`).
- * @returns A `DebouncedSignal` instance.
+ * setTimeout(() => {
+ * console.log('Setting query to "ab"');
+ * query.set('ab');
+ * // Output: Original Query: ab
+ * }, 200); // Before debounce timeout
+ *
+ * setTimeout(() => {
+ * console.log('Setting query to "abc"');
+ * query.set('abc');
+ * // Output: Original Query: abc
+ * }, 400); // Before debounce timeout
+ *
+ * // ~500ms after the *last* set (at 400ms), the debounced effect runs:
+ * // Output (at ~900ms): Debounced Query: abc
+ * ```
  */
-export declare function debounced<T>(initial: T, opt?: CreateDebouncedOptions<T>): DebouncedSignal<T>;
+export declare function debounced<T>(initial: T, opt: CreateDebouncedOptions<T>): DebouncedSignal<T>;

package/lib/map-array.d.ts

@@ -1,56 +1,58 @@
 import { type CreateSignalOptions, type Signal } from '@angular/core';
 /**
- * Options for the mapArray function.
- * @template T The type of elements in the array.
- * @extends CreateSignalOptions<T> Inherits options for creating individual signals.
- */
-export type MapArrayOptions<T> = CreateSignalOptions<T> & {
-    /**
-     * An optional function to transform each element from the source array.
-     * If not provided, the original element is used.
-     * @param source The current value of the source array signal.
-     * @param index The index of the element being mapped.
-     * @returns The transformed element for the corresponding signal.
-     */
-    map?: (source: T[], index: number) => T;
-};
-/**
- * Creates a reactive array of signals from a source array signal (or a function returning one),
- * applying an optional mapping function to each element.
- *
- * This is useful for scenarios like rendering lists where each item
- * needs its own reactive state derived from the source array. It efficiently
- * handles changes in the source array's length by reusing existing signals
- * for elements that remain, adding signals for new elements, and removing signals
- * for deleted elements.
- *
- * @template T The type of elements in the source array.
- * @param source A function that returns the source array (or readonly array).
- * This function will be tracked for changes.
- * @param opt Optional configuration including a `map` function to transform elements
- * and options (`CreateSignalOptions`) for the created signals.
- * @returns A signal (`Signal<Signal<T | undefined>[]>`) where the outer signal updates
- * when the array length changes, and the inner array contains signals
- * representing each element (potentially mapped).
- */
-export declare function mapArray<T>(source: () => T[], opt?: MapArrayOptions<T | undefined>): Signal<Signal<T | undefined>[]>;
-/**
- * Creates a reactive array of signals from a source readonly array (or a function returning one),
- * applying an optional mapping function to each element.
- *
- * This is useful for scenarios like rendering lists where each item
- * needs its own reactive state derived from the source array. It efficiently
- * handles changes in the source array's length by reusing existing signals
- * for elements that remain, adding signals for new elements, and removing signals
- * for deleted elements.
- *
- * @template T The type of elements in the source array.
- * @param source A function that returns the source readonly array.
- * This function will be tracked for changes.
- * @param opt Optional configuration including a `map` function to transform elements
- * and options (`CreateSignalOptions`) for the created signals.
- * @returns A signal (`Signal<Signal<T>[]>`) where the outer signal updates
- * when the array length changes, and the inner array contains signals
- * representing each element (potentially mapped).
+ * Reactively maps items from a source array (or signal of an array) using a provided mapping function.
+ *
+ * This function serves a similar purpose to SolidJS's `mapArray` by providing stability
+ * for mapped items. It receives a source function returning an array (or a Signal<T[]>)
+ * and a mapping function.
+ *
+ * For each item in the source array, it creates a stable `computed` signal representing
+ * that item's value at its current index. This stable signal (`Signal<T>`) is passed
+ * to the mapping function. This ensures that downstream computations or components
+ * depending on the mapped result only re-render or re-calculate for the specific items
+ * that have changed, or when items are added/removed, rather than re-evaluating everything
+ * when the source array reference changes but items remain the same.
+ *
+ * It efficiently handles changes in the source array's length by reusing existing mapped
+ * results when possible, slicing when the array shrinks, and appending new mapped items
+ * when it grows.
+ *
+ * @template T The type of items in the source array.
+ * @template U The type of items in the resulting mapped array.
+ *
+ * @param source A function returning the source array `T[]`, or a `Signal<T[]>` itself.
+ * The `mapArray` function will reactively update based on changes to this source.
+ * @param map The mapping function. It is called for each item in the source array.
+ * It receives:
+ * - `value`: A stable `Signal<T>` representing the item at the current index.
+ * Use this signal within your mapping logic if you need reactivity
+ * tied to the specific item's value changes.
+ * - `index`: The number index of the item in the array.
+ * It should return the mapped value `U`.
+ * @param [opt] Optional `CreateSignalOptions<T>`. These options are passed directly
+ * to the `computed` signal created for each individual item (`Signal<T>`).
+ * This allows specifying options like a custom `equal` function for item comparison.
+ *
+ * @returns A `Signal<U[]>` containing the mapped array. This signal updates whenever
+ * the source array changes (either length or the values of its items).
+ *
+ * @example
+ * ```ts
+ * const sourceItems = signal([
+ * { id: 1, name: 'Apple' },
+ * { id: 2, name: 'Banana' }
+ * ]);
+ *
+ * const mappedItems = mapArray(
+ * sourceItems,
+ * (itemSignal, index) => {
+ * // itemSignal is stable for a given item based on its index.
+ * // We create a computed here to react to changes in the item's name.
+ *  return computed(() => `${index}: ${itemSignal().name.toUpperCase()}`);
+ * },
+ * // Example optional options (e.g., custom equality for item signals)
+ * { equal: (a, b) => a.id === b.id && a.name === b.name }
+ * );
+ * ```
  */
-export declare function mapArray<T>(source: () => readonly T[], opt?: MapArrayOptions<T>): Signal<Signal<T>[]>;
+export declare function mapArray<T, U>(source: () => T[], map: (value: Signal<T>, index: number) => U, opt?: CreateSignalOptions<T>): Signal<U[]>;

package/lib/mutable.d.ts

@@ -31,7 +31,7 @@ export type MutableSignal<T> = WritableSignal<T> & {
      * const myObject = mutable({ a: 1, b: 2 });
      * myObject.inline((obj) => (obj.a = 3)); // myObject() now returns { a: 3, b: 2 }
      */
-    inline: (updater: Parameters<WritableSignal<T>['update']>[0]) => void;
+    inline: (updater: (value: T) => void) => void;
 };
 /**
  * Creates a `MutableSignal`. This function overloads the standard `signal` function to provide

package/lib/stored.d.ts

@@ -0,0 +1,126 @@
+import { Signal, type CreateSignalOptions, type WritableSignal } from '@angular/core';
+/**
+ * Interface for storage mechanisms compatible with the `stored` signal.
+ * Matches the essential parts of the `Storage` interface (`localStorage`, `sessionStorage`).
+ */
+type Store = {
+    /** Retrieves an item from storage for a given key. */
+    getItem: (key: string) => string | null;
+    /** Sets an item in storage for a given key. */
+    setItem: (key: string, value: string) => void;
+    /** Removes an item from storage for a given key. */
+    removeItem: (key: string) => void;
+};
+/**
+ * Options for creating a signal synchronized with persistent storage using `stored()`.
+ * Extends Angular's `CreateSignalOptions`.
+ *
+ * @template T The type of value held by the signal.
+ */
+export type CreateStoredOptions<T> = CreateSignalOptions<T> & {
+    /**
+     * The key used to identify the item in storage.
+     * Can be a static string or a function/signal returning a string for dynamic keys
+     * (e.g., based on user ID or other application state).
+     */
+    key: string | (() => string);
+    /**
+     * Optional custom storage implementation (e.g., `sessionStorage` or a custom adapter).
+     * Must conform to the `Store` interface (`getItem`, `setItem`, `removeItem`).
+     * Defaults to `localStorage` in browser environments and a no-op store on the server.
+     */
+    store?: Store;
+    /**
+     * Optional function to serialize the value (type `T`) into a string before storing.
+     * Defaults to `JSON.stringify`.
+     * @param {T} value The value to serialize.
+     * @returns {string} The serialized string representation.
+     */
+    serialize?: (value: T) => string;
+    /**
+     * Optional function to deserialize the string retrieved from storage back into the value (type `T`).
+     * Defaults to `JSON.parse`.
+     * @param {string} value The string retrieved from storage.
+     * @returns {T} The deserialized value.
+     */
+    deserialize?: (value: string) => T;
+    /**
+     * If `true`, the signal will attempt to synchronize its state across multiple browser tabs
+     * using the `storage` event. Changes made in one tab (set, update, clear) will be
+     * reflected in other tabs using the same storage key.
+     * Requires a browser environment. Defaults to `false`.
+     */
+    syncTabs?: boolean;
+};
+/**
+ * A specialized `WritableSignal` returned by the `stored()` function.
+ * It synchronizes its value with persistent storage and provides additional methods.
+ *
+ * @template T The type of value held by the signal (matches the fallback type).
+ */
+export type StoredSignal<T> = WritableSignal<T> & {
+    /**
+     * Removes the item associated with the signal's key from the configured storage.
+     * After clearing, reading the signal will return the fallback value until it's set again.
+     */
+    clear: () => void;
+    /**
+     * A `Signal<string>` containing the current storage key being used by this stored signal.
+     * This is particularly useful if the key was configured dynamically. You can read or react
+     * to this signal to know the active key.
+     */
+    key: Signal<string>;
+};
+/**
+ * Creates a `WritableSignal` whose state is automatically synchronized with persistent storage
+ * (like `localStorage` or `sessionStorage`).
+ *
+ * It handles Server-Side Rendering (SSR) gracefully, allows dynamic storage keys,
+ * custom serialization/deserialization, custom storage providers, and optional
+ * synchronization across browser tabs.
+ *
+ * @template T The type of value held by the signal and stored (after serialization).
+ * @param fallback The default value of type `T` to use when no value is found in storage
+ * or when deserialization fails. The signal's value will never be `null` or `undefined`
+ * publicly, it will always revert to this fallback.
+ * @param options Configuration options (`CreateStoredOptions<T>`). Requires at least the `key`.
+ * @returns A `StoredSignal<T>` instance. This signal behaves like a standard `WritableSignal<T>`,
+ * but its value is persisted. It includes a `.clear()` method to remove the item from storage
+ * and a `.key` signal providing the current storage key.
+ *
+ * @remarks
+ * - **Persistence:** The signal automatically saves its value to storage whenever the signal's
+ * value or its configured `key` changes. This is managed internally using `effect`.
+ * - **SSR Safety:** Detects server environments and uses a no-op storage, preventing errors.
+ * - **Error Handling:** Catches and logs errors during serialization/deserialization in dev mode.
+ * - **Tab Sync:** If `syncTabs` is true, listens to `storage` events to keep the signal value
+ * consistent across browser tabs using the same key. Cleanup is handled automatically
+ * using `DestroyRef`.
+ * - **Removal:** Use the `.clear()` method on the returned signal to remove the item from storage.
+ * Setting the signal to the fallback value will store the fallback value, not remove the item.
+ *
+ * @example
+ * ```ts
+ * import { Component, effect, signal } from '@angular/core';
+ * import { stored } from '@mmstack/primitives'; // Adjust import path
+ *
+ * @Component({
+ * selector: 'app-settings',
+ * standalone: true,
+ * template: `
+ * Theme:
+ * <select [ngModel]="theme()" (ngModelChange)="theme.set($event)">
+ * <option value="light">Light</option>
+ * <option value="dark">Dark</option>
+ * </select>
+ * <button (click)="theme.clear()">Clear Theme Setting</button>
+ * <p>Storage Key Used: {{ theme.key() }}</p>
+ * ` // Requires FormsModule for ngModel
+ * })
+ * export class SettingsComponent {
+ *  theme = stored<'light' | 'dark'>('light', { key: 'app-theme', syncTabs: true });
+ * }
+ * ```
+ */
+export declare function stored<T>(fallback: T, { key, store: providedStore, serialize, deserialize, syncTabs, equal, ...rest }: CreateStoredOptions<T>): StoredSignal<T>;
+export {};

package/package.json

@@ -1,8 +1,22 @@
 {
   "name": "@mmstack/primitives",
-  "version": "19.0.4",
+  "version": "19.0.5",
+  "keywords": [
+    "angular",
+    "signals",
+    "debounce",
+    "mapArray",
+    "primitives"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/mihajm/mmstack"
+  },
+  "homepage": "https://github.com/mihajm/mmstack/blob/master/packages/primitives",
   "peerDependencies": {
     "@angular/core": "~19.2.3",
+    "@angular/common": "~19.2.3",
     "@mmstack/object": "~19.0.0"
   },
   "sideEffects": false,