@mmstack/primitives 19.0.4 → 19.1.0

package/LICENSE

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

package/fesm2022/mmstack-primitives.mjs

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