@mmstack/primitives 19.1.1 → 19.1.2

package/fesm2022/mmstack-primitives.mjs

@@ -143,7 +143,11 @@ function derived(source, optOrKey, opt) {
         ? optOrKey.onChange
         : isArray
             ? (next) => {
-                source.update((cur) => cur.map((v, i) => i === optOrKey ? next : v));
+                source.update((cur) => {
+                    const newArray = [...cur];
+                    newArray[optOrKey] = next;
+                    return newArray;
+                });
             }
             : (next) => {
                 source.update((cur) => ({ ...cur, [optOrKey]: next }));
@@ -252,6 +256,9 @@ function isDerivation(sig) {
  * { equal: (a, b) => a.id === b.id && a.name === b.name }
  * );
  * ```
+ * @remarks
+ * This function achieves its high performance by leveraging the new `linkedSignal`
+ * API from Angular, which allows for efficient memoization and reuse of array items.
  */
 function mapArray(source, map, opt) {
     const data = isSignal(source) ? source : computed(source);
@@ -390,7 +397,7 @@ const noopStore = {
  * }
  * ```
  */
-function stored(fallback, { key, store: providedStore, serialize = JSON.stringify, deserialize = JSON.parse, syncTabs = false, equal = Object.is, ...rest }) {
+function stored(fallback, { key, store: providedStore, serialize = JSON.stringify, deserialize = JSON.parse, syncTabs = false, equal = Object.is, onKeyChange = 'load', cleanupOldKey = false, ...rest }) {
     const isServer = isPlatformServer(inject(PLATFORM_ID));
     const fallbackStore = isServer ? noopStore : localStorage;
     const store = providedStore ?? fallbackStore;
@@ -428,7 +435,8 @@ function stored(fallback, { key, store: providedStore, serialize = JSON.stringif
         ...rest,
         equal,
     };
-    const internal = signal(getValue(untracked(keySig)), {
+    const initialKey = untracked(keySig);
+    const internal = signal(getValue(initialKey), {
         ...opt,
         equal: (a, b) => {
             if (a === null && b === null)
@@ -438,7 +446,33 @@ function stored(fallback, { key, store: providedStore, serialize = JSON.stringif
             return equal(a, b);
         },
     });
-    effect(() => storeValue(keySig(), internal()));
+    let prevKey = initialKey;
+    if (onKeyChange === 'store') {
+        effect(() => {
+            const k = keySig();
+            storeValue(k, internal());
+            if (prevKey !== k) {
+                if (cleanupOldKey)
+                    store.removeItem(prevKey);
+                prevKey = k;
+            }
+        });
+    }
+    else {
+        effect(() => {
+            const k = keySig();
+            if (k === prevKey) {
+                return storeValue(k, internal()); // normal operation
+            }
+            else {
+                if (cleanupOldKey)
+                    store.removeItem(prevKey);
+                const value = getValue(k);
+                internal.set(value); // load new value
+                prevKey = k;
+            }
+        });
+    }
     if (syncTabs && !isServer) {
         const destroyRef = inject(DestroyRef);
         const sync = (e) => {

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/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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"}
+{"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`.\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 * ```ts\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\n * name.set('Jane'); // Updates the original signal\r\n * console.log(user().name); // Outputs: Jane\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 is a convenient shorthand for accessing 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 * ```ts\r\n * const user = signal({ name: 'John', age: 30 });\r\n * const name = derived(user, 'name');\r\n *\r\n * console.log(name()); // Outputs: John\r\n *\r\n * // Update the derived signal, which also updates the source\r\n * name.set('Jane');\r\n *\r\n * console.log(user().name); // Outputs: Jane\r\n * ```\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, deriving an element by its index.\r\n * This overload is a convenient shorthand for accessing array elements.\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 * ```ts\r\n * const numbers = signal([1, 2, 3]);\r\n * const secondNumber = derived(numbers, 1);\r\n *\r\n * console.log(secondNumber()); // Outputs: 2\r\n *\r\n * // Update the derived signal, which also updates the source\r\n * secondNumber.set(5);\r\n *\r\n * console.log(numbers()); // Outputs: [1, 5, 3]\r\n * ```\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((cur) => {\r\n              const newArray = [...(cur as unknown as any[])];\r\n              newArray[optOrKey] = next;\r\n              return newArray 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 * @remarks\r\n * This function achieves its high performance by leveraging the new `linkedSignal`\r\n * API from Angular, which allows for efficient memoization and reuse of array items.\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 * @param initial The initial value of the signal.\r\n * @param options Optional signal options, including a custom `equal` function.\r\n * @returns A `MutableSignal` instance.\r\n *\r\n * ### Important Note on `computed` Signals\r\n *\r\n * When creating a `computed` signal that derives a non-primitive value (e.g., an object or array)\r\n * from a `mutable` signal, you **must** provide the `{ equal: false }` option to the `computed`\r\n * function.\r\n *\r\n * This is because a `.mutate()` call notifies its dependents that it has changed, but if the\r\n * reference to a derived object hasn't changed, the `computed` signal will not trigger its\r\n * own dependents by default.\r\n *\r\n * @example\r\n * ```ts\r\n * const state = mutable({ user: { name: 'John' }, lastUpdated: new Date() });\r\n *\r\n * // ✅ CORRECT: Deriving a primitive value works as expected.\r\n * const name = computed(() => state().user.name);\r\n *\r\n * // ❌ INCORRECT: This will not update reliably after the first change.\r\n * const userObject = computed(() => state().user);\r\n *\r\n * // ✅ CORRECT: For object derivations, `equal: false` is required.\r\n * const userObjectFixed = computed(() => state().user, { equal: false });\r\n *\r\n * // This mutation will now correctly trigger effects depending on `userObjectFixed`.\r\n * state.mutate(s => s.lastUpdated = new Date());\r\n * ```\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   * Optional parameter to specify how key changes should be handled, load is the default.\r\n   * - `load`: The signal will load the value from storage when the key changes & replace the signal's value.\r\n   * - `store`: The signal will store the current value to the new key when the key changes.\r\n   */\r\n  onKeyChange?: 'load' | 'store';\r\n  /**\r\n   * If 'true', the signal will remove the old key from storage when the key changes, defaults to `false`.\r\n   */\r\n  cleanupOldKey?: 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    onKeyChange = 'load',\r\n    cleanupOldKey = false,\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 initialKey = untracked(keySig);\r\n  const internal = signal(getValue(initialKey), {\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  let prevKey = initialKey;\r\n\r\n  if (onKeyChange === 'store') {\r\n    effect(() => {\r\n      const k = keySig();\r\n      storeValue(k, internal());\r\n      if (prevKey !== k) {\r\n        if (cleanupOldKey) store.removeItem(prevKey);\r\n        prevKey = k;\r\n      }\r\n    });\r\n  } else {\r\n    effect(() => {\r\n      const k = keySig();\r\n\r\n      if (k === prevKey) {\r\n        return storeValue(k, internal()); // normal operation\r\n      } else {\r\n        if (cleanupOldKey) store.removeItem(prevKey);\r\n        const value = getValue(k);\r\n        internal.set(value); // load new value\r\n        prevKey = k;\r\n      }\r\n    });\r\n  }\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/lib/derived.d.ts

@@ -32,52 +32,75 @@ export type DerivedSignal<T, U> = WritableSignal<U> & {
     from: (v: T) => U;
 };
 /**
- * Creates a `DerivedSignal` that derives its value from another `WritableSignal` (the source signal).
+ * Creates a `DerivedSignal` that derives its value from another `WritableSignal`.
  * This overload provides the most flexibility, allowing you to specify custom `from` and `onChange` functions.
  *
- * @typeParam T - The type of the source signal's value.
- * @typeParam U - The type of the derived signal's value.
- * @param source - The source `WritableSignal`.
- * @param options - An object containing the `from` and `onChange` functions, and optional signal options.
+ * @typeParam T The type of the source signal's value.
+ * @typeParam U The type of the derived signal's value.
+ * @param source The source `WritableSignal`.
+ * @param options An object containing the `from` and `onChange` functions, and optional signal options.
  * @returns A `DerivedSignal` instance.
  *
  * @example
+ * ```ts
  * const user = signal({ name: 'John', age: 30 });
  * const name = derived(user, {
- *   from: (u) => u.name,
- *   onChange: (newName) => user.update((u) => ({ ...u, name: newName })),
+ * from: (u) => u.name,
+ * onChange: (newName) => user.update((u) => ({ ...u, name: newName })),
  * });
+ *
+ * name.set('Jane'); // Updates the original signal
+ * console.log(user().name); // Outputs: Jane
+ * ```
  */
 export declare function derived<T, U>(source: WritableSignal<T>, opt: CreateDerivedOptions<T, U>): DerivedSignal<T, U>;
 /**
  * Creates a `DerivedSignal` that derives a property from an object held by the source signal.
- * This overload simplifies creating derived signals for object properties.
+ * This overload is a convenient shorthand for accessing object properties.
  *
- * @typeParam T - The type of the source signal's value (must be an object).
- * @typeParam TKey - The key of the property to derive.
- * @param source - The source `WritableSignal` (holding an object).
- * @param key - The key of the property to derive.
- * @param options - Optional signal options for the derived signal.
+ * @typeParam T The type of the source signal's value (must be an object).
+ * @typeParam TKey The key of the property to derive.
+ * @param source The source `WritableSignal` (holding an object).
+ * @param key The key of the property to derive.
+ * @param options Optional signal options for the derived signal.
  * @returns A `DerivedSignal` instance.
  *
  * @example
+ * ```ts
  * const user = signal({ name: 'John', age: 30 });
  * const name = derived(user, 'name');
+ *
+ * console.log(name()); // Outputs: John
+ *
+ * // Update the derived signal, which also updates the source
+ * name.set('Jane');
+ *
+ * console.log(user().name); // Outputs: Jane
+ * ```
  */
 export declare function derived<T extends UnknownObject, TKey extends keyof T>(source: WritableSignal<T>, key: TKey, opt?: CreateSignalOptions<T[TKey]>): DerivedSignal<T, T[TKey]>;
 /**
- * Creates a `DerivedSignal` from an array, and derives an element by index.
+ * Creates a `DerivedSignal` from an array, deriving an element by its index.
+ * This overload is a convenient shorthand for accessing array elements.
  *
- * @typeParam T - The type of the source signal's value (must be an array).
- * @param source - The source `WritableSignal` (holding an array).
- * @param index - The index of the element to derive.
- * @param options - Optional signal options for the derived signal.
+ * @typeParam T The type of the source signal's value (must be an array).
+ * @param source The source `WritableSignal` (holding an array).
+ * @param index The index of the element to derive.
+ * @param options Optional signal options for the derived signal.
  * @returns A `DerivedSignal` instance.
  *
  * @example
+ * ```ts
  * const numbers = signal([1, 2, 3]);
- * const secondNumber = derived(numbers, 1); // secondNumber() === 2
- * secondNumber.set(5); // numbers() === [1, 5, 3]
+ * const secondNumber = derived(numbers, 1);
+ *
+ * console.log(secondNumber()); // Outputs: 2
+ *
+ * // Update the derived signal, which also updates the source
+ * secondNumber.set(5);
+ *
+ * console.log(numbers()); // Outputs: [1, 5, 3]
+ * ```
  */
 export declare function derived<T extends any[]>(source: WritableSignal<T>, index: number, opt?: CreateSignalOptions<T[number]>): DerivedSignal<T, T[number]>;
 /**

package/lib/map-array.d.ts

@@ -54,5 +54,8 @@ import { type CreateSignalOptions, type Signal } from '@angular/core';
  * { equal: (a, b) => a.id === b.id && a.name === b.name }
  * );
  * ```
+ * @remarks
+ * This function achieves its high performance by leveraging the new `linkedSignal`
+ * API from Angular, which allows for efficient memoization and reuse of array items.
  */
 export declare function mapArray<T, U>(source: () => T[], map: (value: Signal<T>, index: number) => U, opt?: CreateSignalOptions<T>): Signal<U[]>;

package/lib/mutable.d.ts

@@ -37,22 +37,37 @@ export type MutableSignal<T> = WritableSignal<T> & {
  * Creates a `MutableSignal`. This function overloads the standard `signal` function to provide
  * the additional `mutate` and `inline` methods.
  *
- * @typeParam T - The type of value held by the signal.
+ * @typeParam T The type of value held by the signal.
+ * @param initial The initial value of the signal.
+ * @param options Optional signal options, including a custom `equal` function.
+ * @returns A `MutableSignal` instance.
  *
- * @param initial - The initial value of the signal.  If no initial value is provided, it defaults to `undefined`.
- * @param options - Optional. An object containing signal options, including a custom equality function (`equal`).
+ * ### Important Note on `computed` Signals
  *
- * @returns A `MutableSignal` instance.
+ * When creating a `computed` signal that derives a non-primitive value (e.g., an object or array)
+ * from a `mutable` signal, you **must** provide the `{ equal: false }` option to the `computed`
+ * function.
+ *
+ * This is because a `.mutate()` call notifies its dependents that it has changed, but if the
+ * reference to a derived object hasn't changed, the `computed` signal will not trigger its
+ * own dependents by default.
  *
  * @example
- * // Create a mutable signal with an initial value:
- * const mySignal = mutable({ count: 0 }) // MutableSignal<{ count: number }>;
+ * ```ts
+ * const state = mutable({ user: { name: 'John' }, lastUpdated: new Date() });
+ *
+ * // ✅ CORRECT: Deriving a primitive value works as expected.
+ * const name = computed(() => state().user.name);
+ *
+ * // ❌ INCORRECT: This will not update reliably after the first change.
+ * const userObject = computed(() => state().user);
  *
- * // Create a mutable signal with no initial value (starts as undefined):
- * const = mutable<number>(); // MutableSignal<number | undefined>
+ * // ✅ CORRECT: For object derivations, `equal: false` is required.
+ * const userObjectFixed = computed(() => state().user, { equal: false });
  *
- * // Create a mutable signal with a custom equality function:
- * const myCustomSignal = mutable({ a: 1 }, { equal: (a, b) => a.a === b.a });
+ * // This mutation will now correctly trigger effects depending on `userObjectFixed`.
+ * state.mutate(s => s.lastUpdated = new Date());
+ * ```
  */
 export declare function mutable<T>(): MutableSignal<T | undefined>;
 export declare function mutable<T>(initial: T): MutableSignal<T>;

package/lib/stored.d.ts

@@ -51,6 +51,16 @@ export type CreateStoredOptions<T> = CreateSignalOptions<T> & {
      * Requires a browser environment. Defaults to `false`.
      */
     syncTabs?: boolean;
+    /**
+     * Optional parameter to specify how key changes should be handled, load is the default.
+     * - `load`: The signal will load the value from storage when the key changes & replace the signal's value.
+     * - `store`: The signal will store the current value to the new key when the key changes.
+     */
+    onKeyChange?: 'load' | 'store';
+    /**
+     * If 'true', the signal will remove the old key from storage when the key changes, defaults to `false`.
+     */
+    cleanupOldKey?: boolean;
 };
 /**
  * A specialized `WritableSignal` returned by the `stored()` function.
@@ -122,5 +132,5 @@ export type StoredSignal<T> = WritableSignal<T> & {
  * }
  * ```
  */
-export declare function stored<T>(fallback: T, { key, store: providedStore, serialize, deserialize, syncTabs, equal, ...rest }: CreateStoredOptions<T>): StoredSignal<T>;
+export declare function stored<T>(fallback: T, { key, store: providedStore, serialize, deserialize, syncTabs, equal, onKeyChange, cleanupOldKey, ...rest }: CreateStoredOptions<T>): StoredSignal<T>;
 export {};

package/package.json

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