@mmstack/primitives 19.0.5 → 19.1.1

package/LICENSE

@@ -1,21 +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.
+MIT License
+
+Copyright (c) 2025-present Miha J. 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,229 +1,239 @@
-# @mmstack/primitives
-
-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 })),
-});
-```
+# @mmstack/primitives
+
+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)
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/mihajm/mmstack/blob/master/packages/primitives/LICENSE)
+
+## 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, debounce } 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());
+    });
+  }
+}
+```
+
+You can also debounce an existing signal:
+
+```typescript
+import { debounce } from '@mmstack/primitives';
+
+const query = signal('');
+const debouncedQuery = debounce(query, { ms: 300 });
+```
+
+### 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,5 +1,6 @@
-import { untracked, signal, computed, isSignal, linkedSignal, inject, PLATFORM_ID, isDevMode, effect, DestroyRef } from '@angular/core';
+import { untracked, signal, inject, DestroyRef, computed, isSignal, linkedSignal, PLATFORM_ID, isDevMode, effect } from '@angular/core';
 import { isPlatformServer } from '@angular/common';
+import { SIGNAL } from '@angular/core/primitives/signals';
 
 /**
  * Converts a read-only `Signal` into a `WritableSignal` by providing custom `set` and, optionally, `update` functions.
@@ -38,87 +39,100 @@ function toWritable(signal, set, 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.
+ * A convenience function that creates and debounces a new `WritableSignal` in one step.
  *
- * This implementation avoids using `effect` by leveraging intermediate `computed`
- * signals and a custom `equal` function to delay value propagation based on a timer.
+ * @see {debounce} for the core implementation details.
  *
  * @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.
+ * @param opt Options for signal creation, including debounce time `ms`.
+ * @returns A `DebouncedSignal<T>` instance.
+ *
+ * @example
+ * // The existing example remains perfect here.
+ * const query = debounced('', { ms: 500 });
+ * effect(() => console.log('Debounced Query:', query()));
+ * query.set('abc');
+ * // ...500ms later...
+ * // Output: Debounced Query: abc
+ */
+function debounced(initial, opt) {
+    return debounce(signal(initial, opt), opt);
+}
+/**
+ * Wraps an existing `WritableSignal` to create a new one whose readable value is debounced.
+ *
+ * This implementation avoids using `effect` by pairing a trigger signal with an `untracked`
+ * read of the source signal to control when the debounced value is re-evaluated.
+ *
+ * @template T The type of value the signal holds.
+ * @param source The source `WritableSignal` to wrap. Writes are applied to this signal immediately.
+ * @param opt Options for debouncing, including debounce time `ms` and an optional `DestroyRef`.
+ * @returns A new `DebouncedSignal<T>` whose read value is debounced. The `.original` property
+ * of the returned signal is a reference back to the provided `source` signal.
  *
  * @example
  * ```ts
- * import { effect } from '@angular/core';
+ * import { signal, effect } from '@angular/core';
  *
- * // Create a debounced signal with a 500ms delay
- * const query = debounced('', { ms: 500 });
+ * // 1. Create a standard source signal.
+ * const sourceQuery = signal('');
+ *
+ * // 2. Create a debounced version of it.
+ * const debouncedQuery = debounce(sourceQuery, { ms: 500 });
  *
+ * // This effect tracks the original signal and runs immediately.
  * effect(() => {
- * // This effect runs 500ms after the last change to 'query'
- * console.log('Debounced Query:', query());
+ * console.log('Original Query:', debouncedQuery.original());
  * });
  *
+ * // This effect tracks the debounced signal and runs after the delay.
  * effect(() => {
- * // This effect runs immediately when 'query.original' changes
- * console.log('Original Query:', query.original());
+ * console.log('Debounced Query:', debouncedQuery());
  * });
  *
  * console.log('Setting query to "a"');
- * query.set('a');
+ * debouncedQuery.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
+ * // ...500ms later...
+ * // Output: Debounced Query: a
  * ```
  */
-function debounced(initial, opt) {
-    const internal = signal(initial, opt);
-    const ms = opt.ms ?? 0;
+function debounce(source, opt) {
+    const ms = opt?.ms ?? 0;
     const trigger = signal(false);
     let timeout;
-    const set = (value) => {
+    try {
+        const destroyRef = opt?.destroyRef ?? inject(DestroyRef, { optional: true });
+        destroyRef?.onDestroy(() => {
+            if (timeout)
+                clearTimeout(timeout);
+            timeout = undefined;
+        });
+    }
+    catch {
+        // not in injection context & no destroyRef provided opting out of cleanup
+    }
+    const triggerFn = (afterClean) => {
         if (timeout)
             clearTimeout(timeout);
-        internal.set(value);
+        afterClean();
         timeout = setTimeout(() => {
             trigger.update((c) => !c);
         }, ms);
     };
+    const set = (value) => {
+        triggerFn(() => source.set(value));
+    };
     const update = (fn) => {
-        if (timeout)
-            clearTimeout(timeout);
-        internal.update(fn);
-        timeout = setTimeout(() => {
-            trigger.update((c) => !c);
-        }, ms);
+        triggerFn(() => source.update(fn));
     };
-    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;
+    const writable = toWritable(computed(() => {
+        trigger();
+        return untracked(source);
+    }, opt), set, update);
+    writable.original = source;
     return writable;
 }
 
@@ -446,9 +460,64 @@ function stored(fallback, { key, store: providedStore, serialize = JSON.stringif
     return writable;
 }
 
+function withHistory(source, opt) {
+    const { equal = Object.is, debugName } = source[SIGNAL];
+    const maxSize = opt?.maxSize ?? Infinity;
+    const history = mutable([], opt);
+    const redoArray = mutable([]);
+    const set = (value) => {
+        const current = untracked(source);
+        if (equal(value, current))
+            return;
+        source.set(value);
+        history.mutate((c) => {
+            if (c.length >= maxSize) {
+                c = c.slice(Math.floor(maxSize / 2));
+            }
+            c.push(current);
+            return c;
+        });
+        redoArray.set([]);
+    };
+    const update = (updater) => {
+        set(updater(untracked(source)));
+    };
+    const internal = toWritable(computed(() => source(), {
+        equal,
+        debugName,
+    }), set, update);
+    internal.history = history;
+    internal.undo = () => {
+        const last = untracked(history);
+        if (last.length === 0)
+            return;
+        const prev = last.at(-1);
+        const cur = untracked(source);
+        history.inline((c) => c.pop());
+        redoArray.inline((c) => c.push(cur));
+        source.set(prev);
+    };
+    internal.redo = () => {
+        const last = untracked(redoArray);
+        if (last.length === 0)
+            return;
+        const prev = last.at(-1);
+        redoArray.inline((c) => c.pop());
+        set(prev);
+    };
+    internal.clear = () => {
+        history.set([]);
+        redoArray.set([]);
+    };
+    internal.canUndo = computed(() => history().length > 0);
+    internal.canRedo = computed(() => redoArray().length > 0);
+    internal.canClear = computed(() => internal.canUndo() || internal.canRedo());
+    return internal;
+}
+
 /**
  * Generated bundle index. Do not edit.
  */
 
-export { debounced, derived, isDerivation, isMutable, mapArray, mutable, stored, toFakeDerivation, toFakeSignalDerivation, toWritable };
+export { debounce, debounced, derived, isDerivation, isMutable, mapArray, mutable, stored, toFakeDerivation, toFakeSignalDerivation, toWritable, withHistory };
 //# 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/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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"}
+{"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/lib/with-history.ts","../../../../packages/primitives/src/mmstack-primitives.ts"],"sourcesContent":["import { Signal, untracked, WritableSignal } from '@angular/core';\r\n\r\n/**\r\n * Converts a read-only `Signal` into a `WritableSignal` by providing custom `set` and, optionally, `update` functions.\r\n * This can be useful for creating controlled write access to a signal that is otherwise read-only.\r\n *\r\n * @typeParam T - The type of value held by the signal.\r\n *\r\n * @param signal - The read-only `Signal` to be made writable.\r\n * @param set - A function that will be used to set the signal's value.  This function *must* handle\r\n *              the actual update mechanism (e.g., updating a backing store, emitting an event, etc.).\r\n * @param update - (Optional) A function that will be used to update the signal's value based on its\r\n *                 previous value.  If not provided, a default `update` implementation is used that\r\n *                 calls the provided `set` function with the result of the updater function. The\r\n *                 default implementation uses `untracked` to avoid creating unnecessary dependencies\r\n *                 within the updater function.\r\n *\r\n * @returns A `WritableSignal` that uses the provided `set` and `update` functions.  The `asReadonly`\r\n *          method of the returned signal will still return the original read-only signal.\r\n *\r\n * @example\r\n * // Basic usage: Making a read-only signal writable with a custom set function.\r\n * const originalValue = signal({a: 0});\r\n * const readOnlySignal = computed(() => originalValue().a);\r\n * const writableSignal = toWritable(readOnlySignal, (newValue) => {\r\n *  originalValue.update((prev) => { ...prev, a: newValue });\r\n * });\r\n *\r\n * writableSignal.set(5); // sets value of originalValue.a to 5 & triggers all signals\r\n */\r\nexport function toWritable<T>(\r\n  signal: Signal<T>,\r\n  set: (value: T) => void,\r\n  update?: (updater: (value: T) => T) => void,\r\n): WritableSignal<T> {\r\n  const internal = signal as WritableSignal<T>;\r\n  internal.asReadonly = () => signal;\r\n  internal.set = set;\r\n  internal.update = update ?? ((updater) => set(updater(untracked(internal))));\r\n\r\n  return internal;\r\n}\r\n","import {\r\n  computed,\r\n  type CreateSignalOptions,\r\n  DestroyRef,\r\n  inject,\r\n  type Signal,\r\n  signal,\r\n  untracked,\r\n  type WritableSignal,\r\n} from '@angular/core';\r\nimport { toWritable } from './to-writable';\r\n\r\n/**\r\n * Options for creating a debounced writable signal.\r\n * Extends Angular's `CreateSignalOptions` with a debounce time setting.\r\n *\r\n * @template T The type of value held by the signal.\r\n */\r\nexport type CreateDebouncedOptions<T> = CreateSignalOptions<T> & {\r\n  /**\r\n   * The debounce delay in milliseconds. Specifies how long to wait after the\r\n   * last `set` or `update` call before the debounced signal reflects the new value.\r\n   */\r\n  ms?: number;\r\n  /**\r\n   * Optional `DestroyRef` to clean up the debounce timer when the signal is destroyed.\r\n   * If provided, the timer will be cleared when the signal is destroyed.\r\n   * If the signal is called within a reactive context a DestroyRef is injected automatically.\r\n   * If it is not provided or injected, the timer will not be cleared automatically...which is usually fine :)\r\n   */\r\n  destroyRef?: DestroyRef;\r\n};\r\n\r\n/**\r\n * A specialized `WritableSignal` whose publicly readable value updates are debounced.\r\n *\r\n * It provides access to the underlying, non-debounced signal via the `original` property.\r\n *\r\n * @template T The type of value held by the signal.\r\n */\r\nexport type DebouncedSignal<T> = WritableSignal<T> & {\r\n  /**\r\n   * A reference to the original, inner `WritableSignal`.\r\n   * This signal's value is updated *immediately* upon calls to `set` or `update`\r\n   * on the parent `DebouncedSignal`. Useful for accessing the latest value\r\n   * without the debounce delay.\r\n   */\r\n  original: Signal<T>;\r\n};\r\n\r\n/**\r\n * A convenience function that creates and debounces a new `WritableSignal` in one step.\r\n *\r\n * @see {debounce} for the core implementation details.\r\n *\r\n * @template T The type of value the signal holds.\r\n * @param initial The initial value of the signal.\r\n * @param opt Options for signal creation, including debounce time `ms`.\r\n * @returns A `DebouncedSignal<T>` instance.\r\n *\r\n * @example\r\n * // The existing example remains perfect here.\r\n * const query = debounced('', { ms: 500 });\r\n * effect(() => console.log('Debounced Query:', query()));\r\n * query.set('abc');\r\n * // ...500ms later...\r\n * // Output: Debounced Query: abc\r\n */\r\nexport function debounced<T>(\r\n  initial: T,\r\n  opt?: CreateDebouncedOptions<T>,\r\n): DebouncedSignal<T> {\r\n  return debounce(signal(initial, opt), opt);\r\n}\r\n\r\n/**\r\n * Wraps an existing `WritableSignal` to create a new one whose readable value is debounced.\r\n *\r\n * This implementation avoids using `effect` by pairing a trigger signal with an `untracked`\r\n * read of the source signal to control when the debounced value is re-evaluated.\r\n *\r\n * @template T The type of value the signal holds.\r\n * @param source The source `WritableSignal` to wrap. Writes are applied to this signal immediately.\r\n * @param opt Options for debouncing, including debounce time `ms` and an optional `DestroyRef`.\r\n * @returns A new `DebouncedSignal<T>` whose read value is debounced. The `.original` property\r\n * of the returned signal is a reference back to the provided `source` signal.\r\n *\r\n * @example\r\n * ```ts\r\n * import { signal, effect } from '@angular/core';\r\n *\r\n * // 1. Create a standard source signal.\r\n * const sourceQuery = signal('');\r\n *\r\n * // 2. Create a debounced version of it.\r\n * const debouncedQuery = debounce(sourceQuery, { ms: 500 });\r\n *\r\n * // This effect tracks the original signal and runs immediately.\r\n * effect(() => {\r\n * console.log('Original Query:', debouncedQuery.original());\r\n * });\r\n *\r\n * // This effect tracks the debounced signal and runs after the delay.\r\n * effect(() => {\r\n * console.log('Debounced Query:', debouncedQuery());\r\n * });\r\n *\r\n * console.log('Setting query to \"a\"');\r\n * debouncedQuery.set('a');\r\n * // Output: Original Query: a\r\n *\r\n * // ...500ms later...\r\n * // Output: Debounced Query: a\r\n * ```\r\n */\r\nexport function debounce<T>(\r\n  source: WritableSignal<T>,\r\n  opt?: CreateDebouncedOptions<T>,\r\n): DebouncedSignal<T> {\r\n  const ms = opt?.ms ?? 0;\r\n\r\n  const trigger = signal(false);\r\n\r\n  let timeout: ReturnType<typeof setTimeout> | undefined;\r\n\r\n  try {\r\n    const destroyRef =\r\n      opt?.destroyRef ?? inject(DestroyRef, { optional: true });\r\n\r\n    destroyRef?.onDestroy(() => {\r\n      if (timeout) clearTimeout(timeout);\r\n      timeout = undefined;\r\n    });\r\n  } catch {\r\n    // not in injection context & no destroyRef provided opting out of cleanup\r\n  }\r\n\r\n  const triggerFn = (afterClean: () => void) => {\r\n    if (timeout) clearTimeout(timeout);\r\n    afterClean();\r\n    timeout = setTimeout(() => {\r\n      trigger.update((c) => !c);\r\n    }, ms);\r\n  };\r\n\r\n  const set = (value: T) => {\r\n    triggerFn(() => source.set(value));\r\n  };\r\n\r\n  const update = (fn: (prev: T) => T) => {\r\n    triggerFn(() => source.update(fn));\r\n  };\r\n\r\n  const writable = toWritable(\r\n    computed(() => {\r\n      trigger();\r\n      return untracked(source);\r\n    }, opt),\r\n    set,\r\n    update,\r\n  ) as DebouncedSignal<T>;\r\n  writable.original = source;\r\n\r\n  return writable;\r\n}\r\n","import {\r\n  computed,\r\n  CreateSignalOptions,\r\n  signal,\r\n  untracked,\r\n  type WritableSignal,\r\n} from '@angular/core';\r\nimport type { UnknownObject } from '@mmstack/object';\r\nimport { toWritable } from './to-writable';\r\n\r\n/**\r\n * Options for creating a derived signal using the full `derived` function signature.\r\n * @typeParam T - The type of the source signal's value (parent).\r\n * @typeParam U - The type of the derived signal's value (child).\r\n */\r\ntype CreateDerivedOptions<T, U> = CreateSignalOptions<U> & {\r\n  /**\r\n   * A function that extracts the derived value (`U`) from the source signal's value (`T`).\r\n   */\r\n  from: (v: T) => U;\r\n  /**\r\n   * A function that updates the source signal's value (`T`) when the derived signal's value (`U`) changes.\r\n   * This establishes the two-way binding.\r\n   */\r\n  onChange: (newValue: U) => void;\r\n};\r\n\r\n/**\r\n * A `WritableSignal` that derives its value from another `WritableSignal` (the \"source\" signal).\r\n * It provides two-way binding: changes to the source signal update the derived signal, and\r\n * changes to the derived signal update the source signal.\r\n *\r\n * @typeParam T - The type of the source signal's value (parent).\r\n * @typeParam U - The type of the derived signal's value (child).\r\n */\r\nexport type DerivedSignal<T, U> = WritableSignal<U> & {\r\n  /**\r\n   * The function used to derive the derived signal's value from the source signal's value.\r\n   * This is primarily for internal use and introspection.\r\n   */\r\n  from: (v: T) => U;\r\n};\r\n\r\n/**\r\n * Creates a `DerivedSignal` that derives its value from another `WritableSignal` (the source signal).\r\n * This overload provides the most flexibility, allowing you to specify custom `from` and `onChange` functions.\r\n *\r\n * @typeParam T - The type of the source signal's value.\r\n * @typeParam U - The type of the derived signal's value.\r\n * @param source - The source `WritableSignal`.\r\n * @param options - An object containing the `from` and `onChange` functions, and optional signal options.\r\n * @returns A `DerivedSignal` instance.\r\n *\r\n * @example\r\n * const user = signal({ name: 'John', age: 30 });\r\n * const name = derived(user, {\r\n *   from: (u) => u.name,\r\n *   onChange: (newName) => user.update((u) => ({ ...u, name: newName })),\r\n * });\r\n */\r\nexport function derived<T, U>(\r\n  source: WritableSignal<T>,\r\n  opt: CreateDerivedOptions<T, U>,\r\n): DerivedSignal<T, U>;\r\n\r\n/**\r\n * Creates a `DerivedSignal` that derives a property from an object held by the source signal.\r\n * This overload simplifies creating derived signals for object properties.\r\n *\r\n * @typeParam T - The type of the source signal's value (must be an object).\r\n * @typeParam TKey - The key of the property to derive.\r\n * @param source - The source `WritableSignal` (holding an object).\r\n * @param key - The key of the property to derive.\r\n * @param options - Optional signal options for the derived signal.\r\n * @returns A `DerivedSignal` instance.\r\n *\r\n * @example\r\n * const user = signal({ name: 'John', age: 30 });\r\n * const name = derived(user, 'name');\r\n */\r\nexport function derived<T extends UnknownObject, TKey extends keyof T>(\r\n  source: WritableSignal<T>,\r\n  key: TKey,\r\n  opt?: CreateSignalOptions<T[TKey]>,\r\n): DerivedSignal<T, T[TKey]>;\r\n\r\n/**\r\n * Creates a `DerivedSignal` from an array, and derives an element by index.\r\n *\r\n * @typeParam T - The type of the source signal's value (must be an array).\r\n * @param source - The source `WritableSignal` (holding an array).\r\n * @param index - The index of the element to derive.\r\n * @param options - Optional signal options for the derived signal.\r\n * @returns A `DerivedSignal` instance.\r\n *\r\n * @example\r\n * const numbers = signal([1, 2, 3]);\r\n * const secondNumber = derived(numbers, 1); // secondNumber() === 2\r\n * secondNumber.set(5); // numbers() === [1, 5, 3]\r\n */\r\nexport function derived<T extends any[]>(\r\n  source: WritableSignal<T>,\r\n  index: number,\r\n  opt?: CreateSignalOptions<T[number]>,\r\n): DerivedSignal<T, T[number]>;\r\n\r\nexport function derived<T, U>(\r\n  source: WritableSignal<T>,\r\n  optOrKey: CreateDerivedOptions<T, U> | keyof T,\r\n  opt?: CreateSignalOptions<U>,\r\n): DerivedSignal<T, U> {\r\n  const isArray =\r\n    Array.isArray(untracked(source)) && typeof optOrKey === 'number';\r\n\r\n  const from =\r\n    typeof optOrKey === 'object' ? optOrKey.from : (v: T) => v[optOrKey] as U;\r\n  const onChange =\r\n    typeof optOrKey === 'object'\r\n      ? optOrKey.onChange\r\n      : isArray\r\n        ? (next: U) => {\r\n            source.update(\r\n              (cur) =>\r\n                (cur as unknown as any[]).map((v, i) =>\r\n                  i === optOrKey ? next : v,\r\n                ) as T,\r\n            );\r\n          }\r\n        : (next: U) => {\r\n            source.update((cur) => ({ ...cur, [optOrKey]: next }));\r\n          };\r\n\r\n  const rest = typeof optOrKey === 'object' ? optOrKey : opt;\r\n\r\n  const sig = toWritable<U>(\r\n    computed(() => from(source()), rest),\r\n    (newVal) => onChange(newVal),\r\n  ) as DerivedSignal<T, U>;\r\n\r\n  sig.from = from;\r\n\r\n  return sig;\r\n}\r\n\r\n/**\r\n * Creates a \"fake\" `DerivedSignal` from a simple value. This is useful for creating\r\n * `FormControlSignal` instances that are not directly derived from another signal.\r\n * The returned signal's `from` function will always return the initial value.\r\n *\r\n * @typeParam T -  This type parameter is not used in the implementation but is kept for type compatibility with `DerivedSignal`.\r\n * @typeParam U - The type of the signal's value.\r\n * @param initial - The initial value of the signal.\r\n * @returns A `DerivedSignal` instance.\r\n * @internal\r\n */\r\nexport function toFakeDerivation<T, U>(initial: U): DerivedSignal<T, U> {\r\n  const sig = signal(initial) as DerivedSignal<T, U>;\r\n  sig.from = () => initial;\r\n\r\n  return sig;\r\n}\r\n\r\n/**\r\n * Creates a \"fake\" `DerivedSignal` from an existing `WritableSignal`. This is useful\r\n * for treating a regular `WritableSignal` as a `DerivedSignal` without changing its behavior.\r\n *  The returned signal's `from` function returns the current value of signal, using `untracked`.\r\n *\r\n * @typeParam T - This type parameter is not used in the implementation but is kept for type compatibility with `DerivedSignal`.\r\n * @typeParam U - The type of the signal's value.\r\n * @param initial - The existing `WritableSignal`.\r\n * @returns A `DerivedSignal` instance.\r\n * @internal\r\n */\r\nexport function toFakeSignalDerivation<T, U>(\r\n  initial: WritableSignal<U>,\r\n): DerivedSignal<T, U> {\r\n  const sig = initial as DerivedSignal<T, U>;\r\n  sig.from = () => untracked(initial);\r\n  return sig;\r\n}\r\n\r\n/**\r\n * Type guard function to check if a given `WritableSignal` is a `DerivedSignal`.\r\n *\r\n * @typeParam T - The type of the source signal's value (optional, defaults to `any`).\r\n * @typeParam U - The type of the derived signal's value (optional, defaults to `any`).\r\n * @param sig - The `WritableSignal` to check.\r\n * @returns `true` if the signal is a `DerivedSignal`, `false` otherwise.\r\n */\r\nexport function isDerivation<T, U>(\r\n  sig: WritableSignal<U>,\r\n): sig is DerivedSignal<T, U> {\r\n  return 'from' in sig;\r\n}\r\n","import {\r\n  computed,\r\n  type CreateSignalOptions,\r\n  isSignal,\r\n  linkedSignal,\r\n  type Signal,\r\n} from '@angular/core';\r\n\r\n/**\r\n * Reactively maps items from a source array (or signal of an array) using a provided mapping function.\r\n *\r\n * This function serves a similar purpose to SolidJS's `mapArray` by providing stability\r\n * for mapped items. It receives a source function returning an array (or a Signal<T[]>)\r\n * and a mapping function.\r\n *\r\n * For each item in the source array, it creates a stable `computed` signal representing\r\n * that item's value at its current index. This stable signal (`Signal<T>`) is passed\r\n * to the mapping function. This ensures that downstream computations or components\r\n * depending on the mapped result only re-render or re-calculate for the specific items\r\n * that have changed, or when items are added/removed, rather than re-evaluating everything\r\n * when the source array reference changes but items remain the same.\r\n *\r\n * It efficiently handles changes in the source array's length by reusing existing mapped\r\n * results when possible, slicing when the array shrinks, and appending new mapped items\r\n * when it grows.\r\n *\r\n * @template T The type of items in the source array.\r\n * @template U The type of items in the resulting mapped array.\r\n *\r\n * @param source A function returning the source array `T[]`, or a `Signal<T[]>` itself.\r\n * The `mapArray` function will reactively update based on changes to this source.\r\n * @param map The mapping function. It is called for each item in the source array.\r\n * It receives:\r\n * - `value`: A stable `Signal<T>` representing the item at the current index.\r\n * Use this signal within your mapping logic if you need reactivity\r\n * tied to the specific item's value changes.\r\n * - `index`: The number index of the item in the array.\r\n * It should return the mapped value `U`.\r\n * @param [opt] Optional `CreateSignalOptions<T>`. These options are passed directly\r\n * to the `computed` signal created for each individual item (`Signal<T>`).\r\n * This allows specifying options like a custom `equal` function for item comparison.\r\n *\r\n * @returns A `Signal<U[]>` containing the mapped array. This signal updates whenever\r\n * the source array changes (either length or the values of its items).\r\n *\r\n * @example\r\n * ```ts\r\n * const sourceItems = signal([\r\n * { id: 1, name: 'Apple' },\r\n * { id: 2, name: 'Banana' }\r\n * ]);\r\n *\r\n * const mappedItems = mapArray(\r\n * sourceItems,\r\n * (itemSignal, index) => {\r\n * // itemSignal is stable for a given item based on its index.\r\n * // We create a computed here to react to changes in the item's name.\r\n *  return computed(() => `${index}: ${itemSignal().name.toUpperCase()}`);\r\n * },\r\n * // Example optional options (e.g., custom equality for item signals)\r\n * { equal: (a, b) => a.id === b.id && a.name === b.name }\r\n * );\r\n * ```\r\n */\r\nexport function mapArray<T, U>(\r\n  source: () => T[],\r\n  map: (value: Signal<T>, index: number) => U,\r\n  opt?: CreateSignalOptions<T>,\r\n): Signal<U[]> {\r\n  const data = isSignal(source) ? source : computed(source);\r\n  const len = computed(() => data().length);\r\n\r\n  return linkedSignal<number, U[]>({\r\n    source: () => len(),\r\n    computation: (len, prev) => {\r\n      if (!prev)\r\n        return Array.from({ length: len }, (_, i) =>\r\n          map(\r\n            computed(() => source()[i], opt),\r\n            i,\r\n          ),\r\n        );\r\n\r\n      if (len === prev.value.length) return prev.value;\r\n\r\n      if (len < prev.value.length) {\r\n        return prev.value.slice(0, len);\r\n      } else {\r\n        const next = [...prev.value];\r\n        for (let i = prev.value.length; i < len; i++) {\r\n          next[i] = map(\r\n            computed(() => source()[i], opt),\r\n            i,\r\n          );\r\n        }\r\n        return next;\r\n      }\r\n    },\r\n    equal: (a, b) => a.length === b.length,\r\n  });\r\n}\r\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';\r\nimport {\r\n  computed,\r\n  DestroyRef,\r\n  effect,\r\n  inject,\r\n  isDevMode,\r\n  isSignal,\r\n  PLATFORM_ID,\r\n  Signal,\r\n  signal,\r\n  untracked,\r\n  type CreateSignalOptions,\r\n  type WritableSignal,\r\n} from '@angular/core';\r\nimport { toWritable } from './to-writable';\r\n\r\n/**\r\n * Interface for storage mechanisms compatible with the `stored` signal.\r\n * Matches the essential parts of the `Storage` interface (`localStorage`, `sessionStorage`).\r\n */\r\ntype Store = {\r\n  /** Retrieves an item from storage for a given key. */\r\n  getItem: (key: string) => string | null;\r\n  /** Sets an item in storage for a given key. */\r\n  setItem: (key: string, value: string) => void;\r\n  /** Removes an item from storage for a given key. */\r\n  removeItem: (key: string) => void;\r\n};\r\n\r\n// Internal dummy store for server-side rendering\r\nconst noopStore: Store = {\r\n  getItem: () => null,\r\n  setItem: () => {\r\n    /* noop */\r\n  },\r\n  removeItem: () => {\r\n    /* noop */\r\n  },\r\n};\r\n\r\n/**\r\n * Options for creating a signal synchronized with persistent storage using `stored()`.\r\n * Extends Angular's `CreateSignalOptions`.\r\n *\r\n * @template T The type of value held by the signal.\r\n */\r\nexport type CreateStoredOptions<T> = CreateSignalOptions<T> & {\r\n  /**\r\n   * The key used to identify the item in storage.\r\n   * Can be a static string or a function/signal returning a string for dynamic keys\r\n   * (e.g., based on user ID or other application state).\r\n   */\r\n  key: string | (() => string);\r\n  /**\r\n   * Optional custom storage implementation (e.g., `sessionStorage` or a custom adapter).\r\n   * Must conform to the `Store` interface (`getItem`, `setItem`, `removeItem`).\r\n   * Defaults to `localStorage` in browser environments and a no-op store on the server.\r\n   */\r\n  store?: Store;\r\n  /**\r\n   * Optional function to serialize the value (type `T`) into a string before storing.\r\n   * Defaults to `JSON.stringify`.\r\n   * @param {T} value The value to serialize.\r\n   * @returns {string} The serialized string representation.\r\n   */\r\n  serialize?: (value: T) => string;\r\n  /**\r\n   * Optional function to deserialize the string retrieved from storage back into the value (type `T`).\r\n   * Defaults to `JSON.parse`.\r\n   * @param {string} value The string retrieved from storage.\r\n   * @returns {T} The deserialized value.\r\n   */\r\n  deserialize?: (value: string) => T;\r\n  /**\r\n   * If `true`, the signal will attempt to synchronize its state across multiple browser tabs\r\n   * using the `storage` event. Changes made in one tab (set, update, clear) will be\r\n   * reflected in other tabs using the same storage key.\r\n   * Requires a browser environment. Defaults to `false`.\r\n   */\r\n  syncTabs?: boolean;\r\n};\r\n\r\n/**\r\n * A specialized `WritableSignal` returned by the `stored()` function.\r\n * It synchronizes its value with persistent storage and provides additional methods.\r\n *\r\n * @template T The type of value held by the signal (matches the fallback type).\r\n */\r\nexport type StoredSignal<T> = WritableSignal<T> & {\r\n  /**\r\n   * Removes the item associated with the signal's key from the configured storage.\r\n   * After clearing, reading the signal will return the fallback value until it's set again.\r\n   */\r\n  clear: () => void;\r\n  /**\r\n   * A `Signal<string>` containing the current storage key being used by this stored signal.\r\n   * This is particularly useful if the key was configured dynamically. You can read or react\r\n   * to this signal to know the active key.\r\n   */\r\n  key: Signal<string>;\r\n};\r\n\r\n/**\r\n * Creates a `WritableSignal` whose state is automatically synchronized with persistent storage\r\n * (like `localStorage` or `sessionStorage`).\r\n *\r\n * It handles Server-Side Rendering (SSR) gracefully, allows dynamic storage keys,\r\n * custom serialization/deserialization, custom storage providers, and optional\r\n * synchronization across browser tabs.\r\n *\r\n * @template T The type of value held by the signal and stored (after serialization).\r\n * @param fallback The default value of type `T` to use when no value is found in storage\r\n * or when deserialization fails. The signal's value will never be `null` or `undefined`\r\n * publicly, it will always revert to this fallback.\r\n * @param options Configuration options (`CreateStoredOptions<T>`). Requires at least the `key`.\r\n * @returns A `StoredSignal<T>` instance. This signal behaves like a standard `WritableSignal<T>`,\r\n * but its value is persisted. It includes a `.clear()` method to remove the item from storage\r\n * and a `.key` signal providing the current storage key.\r\n *\r\n * @remarks\r\n * - **Persistence:** The signal automatically saves its value to storage whenever the signal's\r\n * value or its configured `key` changes. This is managed internally using `effect`.\r\n * - **SSR Safety:** Detects server environments and uses a no-op storage, preventing errors.\r\n * - **Error Handling:** Catches and logs errors during serialization/deserialization in dev mode.\r\n * - **Tab Sync:** If `syncTabs` is true, listens to `storage` events to keep the signal value\r\n * consistent across browser tabs using the same key. Cleanup is handled automatically\r\n * using `DestroyRef`.\r\n * - **Removal:** Use the `.clear()` method on the returned signal to remove the item from storage.\r\n * Setting the signal to the fallback value will store the fallback value, not remove the item.\r\n *\r\n * @example\r\n * ```ts\r\n * import { Component, effect, signal } from '@angular/core';\r\n * import { stored } from '@mmstack/primitives'; // Adjust import path\r\n *\r\n * @Component({\r\n * selector: 'app-settings',\r\n * standalone: true,\r\n * template: `\r\n * Theme:\r\n * <select [ngModel]=\"theme()\" (ngModelChange)=\"theme.set($event)\">\r\n * <option value=\"light\">Light</option>\r\n * <option value=\"dark\">Dark</option>\r\n * </select>\r\n * <button (click)=\"theme.clear()\">Clear Theme Setting</button>\r\n * <p>Storage Key Used: {{ theme.key() }}</p>\r\n * ` // Requires FormsModule for ngModel\r\n * })\r\n * export class SettingsComponent {\r\n *  theme = stored<'light' | 'dark'>('light', { key: 'app-theme', syncTabs: true });\r\n * }\r\n * ```\r\n */\r\nexport function stored<T>(\r\n  fallback: T,\r\n  {\r\n    key,\r\n    store: providedStore,\r\n    serialize = JSON.stringify,\r\n    deserialize = JSON.parse,\r\n    syncTabs = false,\r\n    equal = Object.is,\r\n    ...rest\r\n  }: CreateStoredOptions<T>,\r\n): StoredSignal<T> {\r\n  const isServer = isPlatformServer(inject(PLATFORM_ID));\r\n\r\n  const fallbackStore = isServer ? noopStore : localStorage;\r\n  const store = providedStore ?? fallbackStore;\r\n\r\n  const keySig =\r\n    typeof key === 'string'\r\n      ? computed(() => key)\r\n      : isSignal(key)\r\n        ? key\r\n        : computed(key);\r\n\r\n  const getValue = (key: string): T | null => {\r\n    const found = store.getItem(key);\r\n    if (found === null) return null;\r\n    try {\r\n      return deserialize(found);\r\n    } catch (err) {\r\n      if (isDevMode())\r\n        console.error(`Failed to parse stored value for key \"${key}\":`, err);\r\n      return null;\r\n    }\r\n  };\r\n\r\n  const storeValue = (key: string, value: T | null) => {\r\n    try {\r\n      if (value === null) return store.removeItem(key);\r\n      const serialized = serialize(value);\r\n      store.setItem(key, serialized);\r\n    } catch (err) {\r\n      if (isDevMode())\r\n        console.error(`Failed to store value for key \"${key}\":`, err);\r\n    }\r\n  };\r\n\r\n  const opt = {\r\n    ...rest,\r\n    equal,\r\n  };\r\n\r\n  const internal = signal(getValue(untracked(keySig)), {\r\n    ...opt,\r\n    equal: (a, b) => {\r\n      if (a === null && b === null) return true;\r\n      if (a === null || b === null) return false;\r\n      return equal(a, b);\r\n    },\r\n  });\r\n\r\n  effect(() => storeValue(keySig(), internal()));\r\n\r\n  if (syncTabs && !isServer) {\r\n    const destroyRef = inject(DestroyRef);\r\n    const sync = (e: StorageEvent) => {\r\n      if (e.key !== untracked(keySig)) return;\r\n\r\n      if (e.newValue === null) internal.set(null);\r\n      else internal.set(getValue(e.key));\r\n    };\r\n\r\n    window.addEventListener('storage', sync);\r\n\r\n    destroyRef.onDestroy(() => window.removeEventListener('storage', sync));\r\n  }\r\n\r\n  const writable = toWritable<T>(\r\n    computed(() => internal() ?? fallback, opt),\r\n    internal.set,\r\n  ) as StoredSignal<T>;\r\n\r\n  writable.clear = () => {\r\n    internal.set(null);\r\n  };\r\n  writable.key = keySig;\r\n  return writable;\r\n}\r\n","import {\r\n  computed,\r\n  type CreateSignalOptions,\r\n  type Signal,\r\n  untracked,\r\n  type ValueEqualityFn,\r\n  type WritableSignal,\r\n} from '@angular/core';\r\nimport { SIGNAL } from '@angular/core/primitives/signals';\r\nimport { mutable } from './mutable';\r\nimport { toWritable } from './to-writable';\r\n\r\nexport type SignalWithHistory<T> = WritableSignal<T> & {\r\n  history: Signal<T[]>;\r\n  undo: () => void;\r\n  redo: () => void;\r\n  canRedo: Signal<boolean>;\r\n  canUndo: Signal<boolean>;\r\n  clear: () => void;\r\n  canClear: Signal<boolean>;\r\n};\r\n\r\nexport type CreateHistoryOptions<T> = Omit<\r\n  CreateSignalOptions<T[]>,\r\n  'equal'\r\n> & {\r\n  maxSize?: number;\r\n};\r\n\r\nexport function withHistory<T>(\r\n  source: WritableSignal<T>,\r\n  opt?: CreateHistoryOptions<T>,\r\n): SignalWithHistory<T> {\r\n  const { equal = Object.is, debugName } = source[SIGNAL] as {\r\n    equal?: ValueEqualityFn<T>;\r\n    debugName?: string;\r\n  };\r\n\r\n  const maxSize = opt?.maxSize ?? Infinity;\r\n\r\n  const history = mutable<T[]>([], opt);\r\n\r\n  const redoArray = mutable<T[]>([]);\r\n\r\n  const set = (value: T) => {\r\n    const current = untracked(source);\r\n    if (equal(value, current)) return;\r\n\r\n    source.set(value);\r\n\r\n    history.mutate((c) => {\r\n      if (c.length >= maxSize) {\r\n        c = c.slice(Math.floor(maxSize / 2));\r\n      }\r\n      c.push(current);\r\n      return c;\r\n    });\r\n    redoArray.set([]);\r\n  };\r\n\r\n  const update = (updater: (prev: T) => T) => {\r\n    set(updater(untracked(source)));\r\n  };\r\n\r\n  const internal = toWritable(\r\n    computed(() => source(), {\r\n      equal,\r\n      debugName,\r\n    }),\r\n    set,\r\n    update,\r\n  ) as SignalWithHistory<T>;\r\n  internal.history = history;\r\n\r\n  internal.undo = () => {\r\n    const last = untracked(history);\r\n    if (last.length === 0) return;\r\n\r\n    const prev = last.at(-1)!;\r\n    const cur = untracked(source);\r\n\r\n    history.inline((c) => c.pop());\r\n    redoArray.inline((c) => c.push(cur));\r\n\r\n    source.set(prev);\r\n  };\r\n\r\n  internal.redo = () => {\r\n    const last = untracked(redoArray);\r\n    if (last.length === 0) return;\r\n\r\n    const prev = last.at(-1)!;\r\n\r\n    redoArray.inline((c) => c.pop());\r\n\r\n    set(prev);\r\n  };\r\n\r\n  internal.clear = () => {\r\n    history.set([]);\r\n    redoArray.set([]);\r\n  };\r\n\r\n  internal.canUndo = computed(() => history().length > 0);\r\n  internal.canRedo = computed(() => redoArray().length > 0);\r\n  internal.canClear = computed(() => internal.canUndo() || internal.canRedo());\r\n\r\n  return internal;\r\n}\r\n","/**\n * Generated bundle index. Do not edit.\n */\n\nexport * from './index';\n"],"names":[],"mappings":"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"}

package/index.d.ts

@@ -4,3 +4,4 @@ export * from './lib/map-array';
 export * from './lib/mutable';
 export * from './lib/stored';
 export * from './lib/to-writable';
+export * from './lib/with-history';

package/lib/debounced.d.ts

@@ -1,4 +1,4 @@
-import { type CreateSignalOptions, type Signal, type WritableSignal } from '@angular/core';
+import { type CreateSignalOptions, DestroyRef, type Signal, type WritableSignal } from '@angular/core';
 /**
  * Options for creating a debounced writable signal.
  * Extends Angular's `CreateSignalOptions` with a debounce time setting.
@@ -11,6 +11,13 @@ export type CreateDebouncedOptions<T> = CreateSignalOptions<T> & {
      * last `set` or `update` call before the debounced signal reflects the new value.
      */
     ms?: number;
+    /**
+     * Optional `DestroyRef` to clean up the debounce timer when the signal is destroyed.
+     * If provided, the timer will be cleared when the signal is destroyed.
+     * If the signal is called within a reactive context a DestroyRef is injected automatically.
+     * If it is not provided or injected, the timer will not be cleared automatically...which is usually fine :)
+     */
+    destroyRef?: DestroyRef;
 };
 /**
  * A specialized `WritableSignal` whose publicly readable value updates are debounced.
@@ -29,56 +36,62 @@ export type DebouncedSignal<T> = WritableSignal<T> & {
     original: Signal<T>;
 };
 /**
- * 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.
+ * A convenience function that creates and debounces a new `WritableSignal` in one step.
  *
- * This implementation avoids using `effect` by leveraging intermediate `computed`
- * signals and a custom `equal` function to delay value propagation based on a timer.
+ * @see {debounce} for the core implementation details.
  *
  * @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.
+ * @param opt Options for signal creation, including debounce time `ms`.
+ * @returns A `DebouncedSignal<T>` instance.
+ *
+ * @example
+ * // The existing example remains perfect here.
+ * const query = debounced('', { ms: 500 });
+ * effect(() => console.log('Debounced Query:', query()));
+ * query.set('abc');
+ * // ...500ms later...
+ * // Output: Debounced Query: abc
+ */
+export declare function debounced<T>(initial: T, opt?: CreateDebouncedOptions<T>): DebouncedSignal<T>;
+/**
+ * Wraps an existing `WritableSignal` to create a new one whose readable value is debounced.
+ *
+ * This implementation avoids using `effect` by pairing a trigger signal with an `untracked`
+ * read of the source signal to control when the debounced value is re-evaluated.
+ *
+ * @template T The type of value the signal holds.
+ * @param source The source `WritableSignal` to wrap. Writes are applied to this signal immediately.
+ * @param opt Options for debouncing, including debounce time `ms` and an optional `DestroyRef`.
+ * @returns A new `DebouncedSignal<T>` whose read value is debounced. The `.original` property
+ * of the returned signal is a reference back to the provided `source` signal.
  *
  * @example
  * ```ts
- * import { effect } from '@angular/core';
+ * import { signal, effect } from '@angular/core';
  *
- * // Create a debounced signal with a 500ms delay
- * const query = debounced('', { ms: 500 });
+ * // 1. Create a standard source signal.
+ * const sourceQuery = signal('');
  *
+ * // 2. Create a debounced version of it.
+ * const debouncedQuery = debounce(sourceQuery, { ms: 500 });
+ *
+ * // This effect tracks the original signal and runs immediately.
  * effect(() => {
- * // This effect runs 500ms after the last change to 'query'
- * console.log('Debounced Query:', query());
+ * console.log('Original Query:', debouncedQuery.original());
  * });
  *
+ * // This effect tracks the debounced signal and runs after the delay.
  * effect(() => {
- * // This effect runs immediately when 'query.original' changes
- * console.log('Original Query:', query.original());
+ * console.log('Debounced Query:', debouncedQuery());
  * });
  *
  * console.log('Setting query to "a"');
- * query.set('a');
+ * debouncedQuery.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
+ * // ...500ms later...
+ * // Output: Debounced Query: a
  * ```
  */
-export declare function debounced<T>(initial: T, opt: CreateDebouncedOptions<T>): DebouncedSignal<T>;
+export declare function debounce<T>(source: WritableSignal<T>, opt?: CreateDebouncedOptions<T>): DebouncedSignal<T>;

package/lib/with-history.d.ts

@@ -0,0 +1,14 @@
+import { type CreateSignalOptions, type Signal, type WritableSignal } from '@angular/core';
+export type SignalWithHistory<T> = WritableSignal<T> & {
+    history: Signal<T[]>;
+    undo: () => void;
+    redo: () => void;
+    canRedo: Signal<boolean>;
+    canUndo: Signal<boolean>;
+    clear: () => void;
+    canClear: Signal<boolean>;
+};
+export type CreateHistoryOptions<T> = Omit<CreateSignalOptions<T[]>, 'equal'> & {
+    maxSize?: number;
+};
+export declare function withHistory<T>(source: WritableSignal<T>, opt?: CreateHistoryOptions<T>): SignalWithHistory<T>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mmstack/primitives",
-  "version": "19.0.5",
+  "version": "19.1.1",
   "keywords": [
     "angular",
     "signals",
@@ -14,10 +14,13 @@
     "url": "https://github.com/mihajm/mmstack"
   },
   "homepage": "https://github.com/mihajm/mmstack/blob/master/packages/primitives",
+  "dependencies": {
+    "@mmstack/object": "^19.1.0",
+    "tslib": "^2.3.0"
+  },
   "peerDependencies": {
     "@angular/core": "~19.2.3",
-    "@angular/common": "~19.2.3",
-    "@mmstack/object": "~19.0.0"
+    "@angular/common": "~19.2.3"
   },
   "sideEffects": false,
   "module": "fesm2022/mmstack-primitives.mjs",
@@ -30,8 +33,5 @@
       "types": "./index.d.ts",
       "default": "./fesm2022/mmstack-primitives.mjs"
     }
-  },
-  "dependencies": {
-    "tslib": "^2.3.0"
   }
 }