@mmstack/primitives 19.0.4 → 19.1.0

package/fesm2022/mmstack-primitives.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"mmstack-primitives.mjs","sources":["../../../../packages/primitives/src/lib/to-writable.ts","../../../../packages/primitives/src/lib/debounced.ts","../../../../packages/primitives/src/lib/derived.ts","../../../../packages/primitives/src/lib/map-array.ts","../../../../packages/primitives/src/lib/mutable.ts","../../../../packages/primitives/src/mmstack-primitives.ts"],"sourcesContent":["import { Signal, untracked, WritableSignal } from '@angular/core';\n\n/**\n * Converts a read-only `Signal` into a `WritableSignal` by providing custom `set` and, optionally, `update` functions.\n * This can be useful for creating controlled write access to a signal that is otherwise read-only.\n *\n * @typeParam T - The type of value held by the signal.\n *\n * @param signal - The read-only `Signal` to be made writable.\n * @param set - A function that will be used to set the signal's value.  This function *must* handle\n *              the actual update mechanism (e.g., updating a backing store, emitting an event, etc.).\n * @param update - (Optional) A function that will be used to update the signal's value based on its\n *                 previous value.  If not provided, a default `update` implementation is used that\n *                 calls the provided `set` function with the result of the updater function. The\n *                 default implementation uses `untracked` to avoid creating unnecessary dependencies\n *                 within the updater function.\n *\n * @returns A `WritableSignal` that uses the provided `set` and `update` functions.  The `asReadonly`\n *          method of the returned signal will still return the original read-only signal.\n *\n * @example\n * // Basic usage: Making a read-only signal writable with a custom set function.\n * const originalValue = signal({a: 0});\n * const readOnlySignal = computed(() => originalValue().a);\n * const writableSignal = toWritable(readOnlySignal, (newValue) => {\n *  originalValue.update((prev) => { ...prev, a: newValue });\n * });\n *\n * writableSignal.set(5); // sets value of originalValue.a to 5 & triggers all signals\n */\nexport function toWritable<T>(\n  signal: Signal<T>,\n  set: (value: T) => void,\n  update?: (updater: (value: T) => T) => void,\n): WritableSignal<T> {\n  const internal = signal as WritableSignal<T>;\n  internal.asReadonly = () => signal;\n  internal.set = set;\n  internal.update = update ?? ((updater) => set(updater(untracked(internal))));\n\n  return internal;\n}\n","import {\n  computed,\n  type CreateSignalOptions,\n  signal,\n  untracked,\n  type WritableSignal,\n} from '@angular/core';\nimport { toWritable } from './to-writable';\n\n/**\n * A `DebouncedSignal` is a special type of `WritableSignal` that delays updates\n * to its value.  This is useful for scenarios where you want to avoid\n * frequent updates, such as responding to user input in a search field.\n * It keeps a reference to the original `WritableSignal` via the `original` property.\n *\n * @typeParam T - The type of value held by the signal.\n */\nexport type DebouncedSignal<T> = WritableSignal<T> & {\n  /**\n   * A reference to the original, un-debounced `WritableSignal`. This allows\n   * you to access the immediate value (without the debounce delay) if needed,\n   * and also ensures that any direct modifications to the original signal\n   * are reflected in the debounced signal after the debounce period.\n   */\n  original: WritableSignal<T>;\n};\n\n/**\n * Options for creating a debounced signal.\n *\n * @typeParam T - The type of value held by the signal.\n */\nexport type CreateDebouncedOptions<T> = CreateSignalOptions<T> & {\n  /**\n   * The debounce delay in milliseconds. Defaults to 300.\n   */\n  ms?: number;\n};\n\n/**\n * Creates a debounced signal. The signal's value will only be propagated to\n * subscribers after a specified delay (debounce time) has passed since the last\n * time it was set or updated.  Crucially, updates to the *original* signal\n * are also debounced.\n *\n * @see {@link DebouncedSignal}\n * @see {@link CreateDebouncedOptions}\n *\n * @example\n * ```typescript\n * // Create a debounced signal with an initial value and a custom delay.\n * const searchTerm = debounced('initial value', { ms: 500 });\n *\n * // Update the debounced signal. The actual update will be delayed by 500ms.\n * searchTerm.set('new value');\n *\n * // Access the original, un-debounced signal.\n * console.log(searchTerm.original()); // Outputs 'new value' (immediately)\n * // ... after 500ms ...\n * console.log(searchTerm()); // Outputs 'new value' (debounced)\n *\n * // Directly update the *original* signal.\n * searchTerm.original.set('direct update');\n * console.log(searchTerm.original()); // Outputs 'direct update' (immediately)\n * console.log(searchTerm()); // Outputs 'new value' (still debounced from the previous set)\n * // ... after 500ms ...\n * console.log(searchTerm()); // Outputs 'direct update' (now reflects the original signal)\n *\n * // Create a debounced signal with undefined initial value and default delay\n * const anotherSignal = debounced();\n * ```\n * @typeParam T - The type of the signal's value.\n * @param initial The initial value of the signal. Optional; defaults to `undefined`.\n * @param opt Configuration options for the signal, including the debounce delay (`ms`).\n * @returns A `DebouncedSignal` instance.\n */\nexport function debounced<T>(): DebouncedSignal<T | undefined>;\n/**\n * Creates a debounced signal with a defined initial value.\n *\n * @typeParam T - The type of the signal's value.\n * @param initial The initial value of the signal.\n * @param opt Configuration options for the signal, including the debounce delay (`ms`).\n * @returns A `DebouncedSignal` instance.\n */\nexport function debounced<T>(\n  initial: T,\n  opt?: CreateDebouncedOptions<T>,\n): DebouncedSignal<T>;\nexport function debounced<T>(\n  value?: T,\n  opt?: CreateDebouncedOptions<T | undefined>,\n): DebouncedSignal<T | undefined> {\n  const sig = signal<T | undefined>(value, opt) as DebouncedSignal<\n    T | undefined\n  >;\n  const ms = opt?.ms ?? 300;\n\n  let timeout: ReturnType<typeof setTimeout> | undefined;\n\n  const originalSet = sig.set;\n  const originalUpdate = sig.update;\n\n  const trigger = signal(false);\n\n  // Set on the original signal, then trigger the debounced update\n  const set = (value: T | undefined) => {\n    originalSet(value); // Update the *original* signal immediately\n\n    if (timeout) clearTimeout(timeout);\n    timeout = setTimeout(() => {\n      trigger.update((cur) => !cur); // Trigger the computed signal\n    }, ms);\n  };\n\n  // Update on the original signal, then trigger the debounced update\n  const update = (fn: (prev: T | undefined) => T | undefined) => {\n    originalUpdate(fn); // Update the *original* signal immediately\n\n    if (timeout) clearTimeout(timeout);\n    timeout = setTimeout(() => {\n      trigger.update((cur) => !cur); // Trigger the computed signal\n    }, ms);\n  };\n\n  // Create a computed signal that depends on the trigger.\n  // This computed signal is what provides the debounced behavior.\n  const writable = toWritable(\n    computed(() => {\n      trigger();\n      return untracked(sig);\n    }),\n    set,\n    update,\n  ) as DebouncedSignal<T | undefined>;\n\n  writable.original = sig;\n\n  return writable;\n}\n","import {\n  computed,\n  CreateSignalOptions,\n  signal,\n  untracked,\n  type WritableSignal,\n} from '@angular/core';\nimport type { UnknownObject } from '@mmstack/object';\nimport { toWritable } from './to-writable';\n\n/**\n * Options for creating a derived signal using the full `derived` function signature.\n * @typeParam T - The type of the source signal's value (parent).\n * @typeParam U - The type of the derived signal's value (child).\n */\ntype CreateDerivedOptions<T, U> = CreateSignalOptions<U> & {\n  /**\n   * A function that extracts the derived value (`U`) from the source signal's value (`T`).\n   */\n  from: (v: T) => U;\n  /**\n   * A function that updates the source signal's value (`T`) when the derived signal's value (`U`) changes.\n   * This establishes the two-way binding.\n   */\n  onChange: (newValue: U) => void;\n};\n\n/**\n * A `WritableSignal` that derives its value from another `WritableSignal` (the \"source\" signal).\n * It provides two-way binding: changes to the source signal update the derived signal, and\n * changes to the derived signal update the source signal.\n *\n * @typeParam T - The type of the source signal's value (parent).\n * @typeParam U - The type of the derived signal's value (child).\n */\nexport type DerivedSignal<T, U> = WritableSignal<U> & {\n  /**\n   * The function used to derive the derived signal's value from the source signal's value.\n   * This is primarily for internal use and introspection.\n   */\n  from: (v: T) => U;\n};\n\n/**\n * Creates a `DerivedSignal` that derives its value from another `WritableSignal` (the source signal).\n * This overload provides the most flexibility, allowing you to specify custom `from` and `onChange` functions.\n *\n * @typeParam T - The type of the source signal's value.\n * @typeParam U - The type of the derived signal's value.\n * @param source - The source `WritableSignal`.\n * @param options - An object containing the `from` and `onChange` functions, and optional signal options.\n * @returns A `DerivedSignal` instance.\n *\n * @example\n * const user = signal({ name: 'John', age: 30 });\n * const name = derived(user, {\n *   from: (u) => u.name,\n *   onChange: (newName) => user.update((u) => ({ ...u, name: newName })),\n * });\n */\nexport function derived<T, U>(\n  source: WritableSignal<T>,\n  opt: CreateDerivedOptions<T, U>,\n): DerivedSignal<T, U>;\n\n/**\n * Creates a `DerivedSignal` that derives a property from an object held by the source signal.\n * This overload simplifies creating derived signals for object properties.\n *\n * @typeParam T - The type of the source signal's value (must be an object).\n * @typeParam TKey - The key of the property to derive.\n * @param source - The source `WritableSignal` (holding an object).\n * @param key - The key of the property to derive.\n * @param options - Optional signal options for the derived signal.\n * @returns A `DerivedSignal` instance.\n *\n * @example\n * const user = signal({ name: 'John', age: 30 });\n * const name = derived(user, 'name');\n */\nexport function derived<T extends UnknownObject, TKey extends keyof T>(\n  source: WritableSignal<T>,\n  key: TKey,\n  opt?: CreateSignalOptions<T[TKey]>,\n): DerivedSignal<T, T[TKey]>;\n\n/**\n * Creates a `DerivedSignal` from an array, and derives an element by index.\n *\n * @typeParam T - The type of the source signal's value (must be an array).\n * @param source - The source `WritableSignal` (holding an array).\n * @param index - The index of the element to derive.\n * @param options - Optional signal options for the derived signal.\n * @returns A `DerivedSignal` instance.\n *\n * @example\n * const numbers = signal([1, 2, 3]);\n * const secondNumber = derived(numbers, 1); // secondNumber() === 2\n * secondNumber.set(5); // numbers() === [1, 5, 3]\n */\nexport function derived<T extends any[]>(\n  source: WritableSignal<T>,\n  index: number,\n  opt?: CreateSignalOptions<T[number]>,\n): DerivedSignal<T, T[number]>;\n\nexport function derived<T, U>(\n  source: WritableSignal<T>,\n  optOrKey: CreateDerivedOptions<T, U> | keyof T,\n  opt?: CreateSignalOptions<U>,\n): DerivedSignal<T, U> {\n  const isArray =\n    Array.isArray(untracked(source)) && typeof optOrKey === 'number';\n\n  const from =\n    typeof optOrKey === 'object' ? optOrKey.from : (v: T) => v[optOrKey] as U;\n  const onChange =\n    typeof optOrKey === 'object'\n      ? optOrKey.onChange\n      : isArray\n        ? (next: U) => {\n            source.update(\n              (cur) =>\n                (cur as unknown as any[]).map((v, i) =>\n                  i === optOrKey ? next : v,\n                ) as T,\n            );\n          }\n        : (next: U) => {\n            source.update((cur) => ({ ...cur, [optOrKey]: next }));\n          };\n\n  const rest = typeof optOrKey === 'object' ? optOrKey : opt;\n\n  const sig = toWritable<U>(\n    computed(() => from(source()), rest),\n    (newVal) => onChange(newVal),\n  ) as DerivedSignal<T, U>;\n\n  sig.from = from;\n\n  return sig;\n}\n\n/**\n * Creates a \"fake\" `DerivedSignal` from a simple value. This is useful for creating\n * `FormControlSignal` instances that are not directly derived from another signal.\n * The returned signal's `from` function will always return the initial value.\n *\n * @typeParam T -  This type parameter is not used in the implementation but is kept for type compatibility with `DerivedSignal`.\n * @typeParam U - The type of the signal's value.\n * @param initial - The initial value of the signal.\n * @returns A `DerivedSignal` instance.\n * @internal\n */\nexport function toFakeDerivation<T, U>(initial: U): DerivedSignal<T, U> {\n  const sig = signal(initial) as DerivedSignal<T, U>;\n  sig.from = () => initial;\n\n  return sig;\n}\n\n/**\n * Creates a \"fake\" `DerivedSignal` from an existing `WritableSignal`. This is useful\n * for treating a regular `WritableSignal` as a `DerivedSignal` without changing its behavior.\n *  The returned signal's `from` function returns the current value of signal, using `untracked`.\n *\n * @typeParam T - This type parameter is not used in the implementation but is kept for type compatibility with `DerivedSignal`.\n * @typeParam U - The type of the signal's value.\n * @param initial - The existing `WritableSignal`.\n * @returns A `DerivedSignal` instance.\n * @internal\n */\nexport function toFakeSignalDerivation<T, U>(\n  initial: WritableSignal<U>,\n): DerivedSignal<T, U> {\n  const sig = initial as DerivedSignal<T, U>;\n  sig.from = () => untracked(initial);\n  return sig;\n}\n\n/**\n * Type guard function to check if a given `WritableSignal` is a `DerivedSignal`.\n *\n * @typeParam T - The type of the source signal's value (optional, defaults to `any`).\n * @typeParam U - The type of the derived signal's value (optional, defaults to `any`).\n * @param sig - The `WritableSignal` to check.\n * @returns `true` if the signal is a `DerivedSignal`, `false` otherwise.\n */\nexport function isDerivation<T, U>(\n  sig: WritableSignal<U>,\n): sig is DerivedSignal<T, U> {\n  return 'from' in sig;\n}\n","import {\n  computed,\n  type CreateSignalOptions,\n  isSignal,\n  linkedSignal,\n  type Signal,\n} from '@angular/core';\n\n/**\n * Options for the mapArray function.\n * @template T The type of elements in the array.\n * @extends CreateSignalOptions<T> Inherits options for creating individual signals.\n */\nexport type MapArrayOptions<T> = CreateSignalOptions<T> & {\n  /**\n   * An optional function to transform each element from the source array.\n   * If not provided, the original element is used.\n   * @param source The current value of the source array signal.\n   * @param index The index of the element being mapped.\n   * @returns The transformed element for the corresponding signal.\n   */\n  map?: (source: T[], index: number) => T;\n};\n\nfunction createReconciler<T>(source: Signal<T[]>, opt?: MapArrayOptions<T>) {\n  const map = opt?.map ?? ((source, index) => source[index]);\n\n  return (\n    length: number,\n    prev?: {\n      value: Signal<T>[];\n      source: number;\n    },\n  ): Signal<T>[] => {\n    if (!prev)\n      return Array.from({ length }, (_, i) =>\n        computed(() => map(source(), i), opt),\n      );\n\n    if (length === prev.source) return prev.value;\n\n    if (length < prev.source) {\n      return prev.value.slice(0, length);\n    } else {\n      const next = [...prev.value];\n      for (let i = prev.source; i < length; i++) {\n        next.push(computed(() => map(source(), i), opt));\n      }\n\n      return next;\n    }\n  };\n}\n\n/**\n * Creates a reactive array of signals from a source array signal (or a function returning one),\n * applying an optional mapping function to each element.\n *\n * This is useful for scenarios like rendering lists where each item\n * needs its own reactive state derived from the source array. It efficiently\n * handles changes in the source array's length by reusing existing signals\n * for elements that remain, adding signals for new elements, and removing signals\n * for deleted elements.\n *\n * @template T The type of elements in the source array.\n * @param source A function that returns the source array (or readonly array).\n * This function will be tracked for changes.\n * @param opt Optional configuration including a `map` function to transform elements\n * and options (`CreateSignalOptions`) for the created signals.\n * @returns A signal (`Signal<Signal<T | undefined>[]>`) where the outer signal updates\n * when the array length changes, and the inner array contains signals\n * representing each element (potentially mapped).\n */\nexport function mapArray<T>(\n  source: () => T[],\n  opt?: MapArrayOptions<T | undefined>,\n): Signal<Signal<T | undefined>[]>;\n\n/**\n * Creates a reactive array of signals from a source readonly array (or a function returning one),\n * applying an optional mapping function to each element.\n *\n * This is useful for scenarios like rendering lists where each item\n * needs its own reactive state derived from the source array. It efficiently\n * handles changes in the source array's length by reusing existing signals\n * for elements that remain, adding signals for new elements, and removing signals\n * for deleted elements.\n *\n * @template T The type of elements in the source array.\n * @param source A function that returns the source readonly array.\n * This function will be tracked for changes.\n * @param opt Optional configuration including a `map` function to transform elements\n * and options (`CreateSignalOptions`) for the created signals.\n * @returns A signal (`Signal<Signal<T>[]>`) where the outer signal updates\n * when the array length changes, and the inner array contains signals\n * representing each element (potentially mapped).\n */\nexport function mapArray<T>(\n  source: () => readonly T[],\n  opt?: MapArrayOptions<T>,\n): Signal<Signal<T>[]>;\n\nexport function mapArray<T>(\n  source: (() => T[]) | (() => readonly T[]),\n  opt?: MapArrayOptions<T>,\n): Signal<Signal<T | undefined>[]> {\n  const data = isSignal(source) ? source : computed(source);\n  const length = computed(() => data().length);\n\n  const reconciler = createReconciler<T>(data as Signal<T[]>, opt);\n\n  return linkedSignal<number, Signal<T>[]>({\n    source: () => length(),\n    computation: (len, prev) => reconciler(len, prev),\n  });\n}\n","import {\r\n  signal,\r\n  type CreateSignalOptions,\r\n  type ValueEqualityFn,\r\n  type WritableSignal,\r\n} from '@angular/core';\r\n\r\nconst { is } = Object;\r\n\r\n/**\r\n * A `MutableSignal` is a special type of `WritableSignal` that allows for in-place mutation of its value.\r\n * In addition to the standard `set` and `update` methods, it provides a `mutate` method.  This is useful\r\n * for performance optimization when dealing with complex objects or arrays, as it avoids unnecessary\r\n * object copying.\r\n *\r\n * @typeParam T - The type of value held by the signal.\r\n */\r\nexport type MutableSignal<T> = WritableSignal<T> & {\r\n  /**\r\n   * Mutates the signal's value in-place.  This is similar to `update`, but it's optimized for\r\n   * scenarios where you want to modify the existing object directly rather than creating a new one.\r\n   *\r\n   * @param updater - A function that takes the current value as input and modifies it directly.\r\n   *\r\n   * @example\r\n   * const myArray = mutable([1, 2, 3]);\r\n   * myArray.mutate((arr) => {\r\n   *  arr.push(4);\r\n   *  return arr;\r\n   * }); // myArray() now returns [1, 2, 3, 4]\r\n   */\r\n  mutate: WritableSignal<T>['update'];\r\n\r\n  /**\r\n   * Mutates the signal's value in-place, similar to `mutate`, but with a void-returning value in updater\r\n   * function. This further emphasizes that the mutation is happening inline, improving readability\r\n   * in some cases.\r\n   * @param updater - Function to change to the current value\r\n   * @example\r\n   * const myObject = mutable({ a: 1, b: 2 });\r\n   * myObject.inline((obj) => (obj.a = 3)); // myObject() now returns { a: 3, b: 2 }\r\n   */\r\n  inline: (updater: Parameters<WritableSignal<T>['update']>[0]) => void;\r\n};\r\n\r\n/**\r\n * Creates a `MutableSignal`. This function overloads the standard `signal` function to provide\r\n * the additional `mutate` and `inline` methods.\r\n *\r\n * @typeParam T - The type of value held by the signal.\r\n *\r\n * @param initial - The initial value of the signal.  If no initial value is provided, it defaults to `undefined`.\r\n * @param options - Optional. An object containing signal options, including a custom equality function (`equal`).\r\n *\r\n * @returns A `MutableSignal` instance.\r\n *\r\n * @example\r\n * // Create a mutable signal with an initial value:\r\n * const mySignal = mutable({ count: 0 }) // MutableSignal<{ count: number }>;\r\n *\r\n * // Create a mutable signal with no initial value (starts as undefined):\r\n * const = mutable<number>(); // MutableSignal<number | undefined>\r\n *\r\n * // Create a mutable signal with a custom equality function:\r\n * const myCustomSignal = mutable({ a: 1 }, { equal: (a, b) => a.a === b.a });\r\n */\r\nexport function mutable<T>(): MutableSignal<T | undefined>;\r\nexport function mutable<T>(initial: T): MutableSignal<T>;\r\nexport function mutable<T>(\r\n  initial: T,\r\n  opt?: CreateSignalOptions<T>,\r\n): MutableSignal<T>;\r\n\r\nexport function mutable<T>(\r\n  initial?: T,\r\n  opt?: CreateSignalOptions<T>,\r\n): MutableSignal<T> {\r\n  const baseEqual = opt?.equal ?? is;\r\n  let trigger = false;\r\n\r\n  const equal: ValueEqualityFn<T | undefined> = (a, b) => {\r\n    if (trigger) return false;\r\n    return baseEqual(a, b);\r\n  };\r\n\r\n  const sig = signal<T | undefined>(initial, {\r\n    ...opt,\r\n    equal,\r\n  }) as MutableSignal<T>;\r\n\r\n  const internalUpdate = sig.update;\r\n\r\n  sig.mutate = (updater) => {\r\n    trigger = true;\r\n    internalUpdate(updater);\r\n    trigger = false;\r\n  };\r\n\r\n  sig.inline = (updater) => {\r\n    sig.mutate((prev) => {\r\n      updater(prev);\r\n      return prev;\r\n    });\r\n  };\r\n\r\n  return sig;\r\n}\r\n\r\n/**\r\n * Type guard function to check if a given `WritableSignal` is a `MutableSignal`.  This is useful\r\n * for situations where you need to conditionally use the `mutate` or `inline` methods.\r\n *\r\n * @typeParam T - The type of the signal's value (optional, defaults to `any`).\r\n * @param value - The `WritableSignal` to check.\r\n * @returns `true` if the signal is a `MutableSignal`, `false` otherwise.\r\n *\r\n * @example\r\n * const mySignal = signal(0);\r\n * const myMutableSignal = mutable(0);\r\n *\r\n * if (isMutable(mySignal)) {\r\n *   mySignal.mutate(x => x + 1); // This would cause a type error, as mySignal is not a MutableSignal.\r\n * }\r\n *\r\n * if (isMutable(myMutableSignal)) {\r\n *   myMutableSignal.mutate(x => x + 1); // This is safe.\r\n * }\r\n */\r\nexport function isMutable<T = any>(\r\n  value: WritableSignal<T>,\r\n): value is MutableSignal<T> {\r\n  return 'mutate' in value && typeof value.mutate === 'function';\r\n}\r\n","/**\n * Generated bundle index. Do not edit.\n */\n\nexport * from './index';\n"],"names":[],"mappings":";;AAEA;;;;;;;;;;;;;;;;;;;;;;;;;;;AA2BG;SACa,UAAU,CACxB,MAAiB,EACjB,GAAuB,EACvB,MAA2C,EAAA;IAE3C,MAAM,QAAQ,GAAG,MAA2B;AAC5C,IAAA,QAAQ,CAAC,UAAU,GAAG,MAAM,MAAM;AAClC,IAAA,QAAQ,CAAC,GAAG,GAAG,GAAG;IAClB,QAAQ,CAAC,MAAM,GAAG,MAAM,KAAK,CAAC,OAAO,KAAK,GAAG,CAAC,OAAO,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;AAE5E,IAAA,OAAO,QAAQ;AACjB;;ACgDgB,SAAA,SAAS,CACvB,KAAS,EACT,GAA2C,EAAA;IAE3C,MAAM,GAAG,GAAG,MAAM,CAAgB,KAAK,EAAE,GAAG,CAE3C;AACD,IAAA,MAAM,EAAE,GAAG,GAAG,EAAE,EAAE,IAAI,GAAG;AAEzB,IAAA,IAAI,OAAkD;AAEtD,IAAA,MAAM,WAAW,GAAG,GAAG,CAAC,GAAG;AAC3B,IAAA,MAAM,cAAc,GAAG,GAAG,CAAC,MAAM;AAEjC,IAAA,MAAM,OAAO,GAAG,MAAM,CAAC,KAAK,CAAC;;AAG7B,IAAA,MAAM,GAAG,GAAG,CAAC,KAAoB,KAAI;AACnC,QAAA,WAAW,CAAC,KAAK,CAAC,CAAC;AAEnB,QAAA,IAAI,OAAO;YAAE,YAAY,CAAC,OAAO,CAAC;AAClC,QAAA,OAAO,GAAG,UAAU,CAAC,MAAK;AACxB,YAAA,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC;SAC/B,EAAE,EAAE,CAAC;AACR,KAAC;;AAGD,IAAA,MAAM,MAAM,GAAG,CAAC,EAA0C,KAAI;AAC5D,QAAA,cAAc,CAAC,EAAE,CAAC,CAAC;AAEnB,QAAA,IAAI,OAAO;YAAE,YAAY,CAAC,OAAO,CAAC;AAClC,QAAA,OAAO,GAAG,UAAU,CAAC,MAAK;AACxB,YAAA,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC;SAC/B,EAAE,EAAE,CAAC;AACR,KAAC;;;AAID,IAAA,MAAM,QAAQ,GAAG,UAAU,CACzB,QAAQ,CAAC,MAAK;AACZ,QAAA,OAAO,EAAE;AACT,QAAA,OAAO,SAAS,CAAC,GAAG,CAAC;AACvB,KAAC,CAAC,EACF,GAAG,EACH,MAAM,CAC2B;AAEnC,IAAA,QAAQ,CAAC,QAAQ,GAAG,GAAG;AAEvB,IAAA,OAAO,QAAQ;AACjB;;SCjCgB,OAAO,CACrB,MAAyB,EACzB,QAA8C,EAC9C,GAA4B,EAAA;AAE5B,IAAA,MAAM,OAAO,GACX,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,IAAI,OAAO,QAAQ,KAAK,QAAQ;IAElE,MAAM,IAAI,GACR,OAAO,QAAQ,KAAK,QAAQ,GAAG,QAAQ,CAAC,IAAI,GAAG,CAAC,CAAI,KAAK,CAAC,CAAC,QAAQ,CAAM;AAC3E,IAAA,MAAM,QAAQ,GACZ,OAAO,QAAQ,KAAK;UAChB,QAAQ,CAAC;AACX,UAAE;AACA,cAAE,CAAC,IAAO,KAAI;AACV,gBAAA,MAAM,CAAC,MAAM,CACX,CAAC,GAAG,KACD,GAAwB,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,KACjC,CAAC,KAAK,QAAQ,GAAG,IAAI,GAAG,CAAC,CACrB,CACT;;AAEL,cAAE,CAAC,IAAO,KAAI;gBACV,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,MAAM,EAAE,GAAG,GAAG,EAAE,CAAC,QAAQ,GAAG,IAAI,EAAE,CAAC,CAAC;AACxD,aAAC;AAET,IAAA,MAAM,IAAI,GAAG,OAAO,QAAQ,KAAK,QAAQ,GAAG,QAAQ,GAAG,GAAG;AAE1D,IAAA,MAAM,GAAG,GAAG,UAAU,CACpB,QAAQ,CAAC,MAAM,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,IAAI,CAAC,EACpC,CAAC,MAAM,KAAK,QAAQ,CAAC,MAAM,CAAC,CACN;AAExB,IAAA,GAAG,CAAC,IAAI,GAAG,IAAI;AAEf,IAAA,OAAO,GAAG;AACZ;AAEA;;;;;;;;;;AAUG;AACG,SAAU,gBAAgB,CAAO,OAAU,EAAA;AAC/C,IAAA,MAAM,GAAG,GAAG,MAAM,CAAC,OAAO,CAAwB;AAClD,IAAA,GAAG,CAAC,IAAI,GAAG,MAAM,OAAO;AAExB,IAAA,OAAO,GAAG;AACZ;AAEA;;;;;;;;;;AAUG;AACG,SAAU,sBAAsB,CACpC,OAA0B,EAAA;IAE1B,MAAM,GAAG,GAAG,OAA8B;IAC1C,GAAG,CAAC,IAAI,GAAG,MAAM,SAAS,CAAC,OAAO,CAAC;AACnC,IAAA,OAAO,GAAG;AACZ;AAEA;;;;;;;AAOG;AACG,SAAU,YAAY,CAC1B,GAAsB,EAAA;IAEtB,OAAO,MAAM,IAAI,GAAG;AACtB;;ACzKA,SAAS,gBAAgB,CAAI,MAAmB,EAAE,GAAwB,EAAA;AACxE,IAAA,MAAM,GAAG,GAAG,GAAG,EAAE,GAAG,KAAK,CAAC,MAAM,EAAE,KAAK,KAAK,MAAM,CAAC,KAAK,CAAC,CAAC;AAE1D,IAAA,OAAO,CACL,MAAc,EACd,IAGC,KACc;AACf,QAAA,IAAI,CAAC,IAAI;AACP,YAAA,OAAO,KAAK,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,EAAE,CAAC,CAAC,EAAE,CAAC,KACjC,QAAQ,CAAC,MAAM,GAAG,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,CAAC,CACtC;AAEH,QAAA,IAAI,MAAM,KAAK,IAAI,CAAC,MAAM;YAAE,OAAO,IAAI,CAAC,KAAK;AAE7C,QAAA,IAAI,MAAM,GAAG,IAAI,CAAC,MAAM,EAAE;YACxB,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,MAAM,CAAC;;aAC7B;YACL,MAAM,IAAI,GAAG,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC;AAC5B,YAAA,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,GAAG,MAAM,EAAE,CAAC,EAAE,EAAE;AACzC,gBAAA,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;;AAGlD,YAAA,OAAO,IAAI;;AAEf,KAAC;AACH;AAkDgB,SAAA,QAAQ,CACtB,MAA0C,EAC1C,GAAwB,EAAA;AAExB,IAAA,MAAM,IAAI,GAAG,QAAQ,CAAC,MAAM,CAAC,GAAG,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC;AACzD,IAAA,MAAM,MAAM,GAAG,QAAQ,CAAC,MAAM,IAAI,EAAE,CAAC,MAAM,CAAC;IAE5C,MAAM,UAAU,GAAG,gBAAgB,CAAI,IAAmB,EAAE,GAAG,CAAC;AAEhE,IAAA,OAAO,YAAY,CAAsB;AACvC,QAAA,MAAM,EAAE,MAAM,MAAM,EAAE;AACtB,QAAA,WAAW,EAAE,CAAC,GAAG,EAAE,IAAI,KAAK,UAAU,CAAC,GAAG,EAAE,IAAI,CAAC;AAClD,KAAA,CAAC;AACJ;;AC5GA,MAAM,EAAE,EAAE,EAAE,GAAG,MAAM;AAkEL,SAAA,OAAO,CACrB,OAAW,EACX,GAA4B,EAAA;AAE5B,IAAA,MAAM,SAAS,GAAG,GAAG,EAAE,KAAK,IAAI,EAAE;IAClC,IAAI,OAAO,GAAG,KAAK;AAEnB,IAAA,MAAM,KAAK,GAAmC,CAAC,CAAC,EAAE,CAAC,KAAI;AACrD,QAAA,IAAI,OAAO;AAAE,YAAA,OAAO,KAAK;AACzB,QAAA,OAAO,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC;AACxB,KAAC;AAED,IAAA,MAAM,GAAG,GAAG,MAAM,CAAgB,OAAO,EAAE;AACzC,QAAA,GAAG,GAAG;QACN,KAAK;AACN,KAAA,CAAqB;AAEtB,IAAA,MAAM,cAAc,GAAG,GAAG,CAAC,MAAM;AAEjC,IAAA,GAAG,CAAC,MAAM,GAAG,CAAC,OAAO,KAAI;QACvB,OAAO,GAAG,IAAI;QACd,cAAc,CAAC,OAAO,CAAC;QACvB,OAAO,GAAG,KAAK;AACjB,KAAC;AAED,IAAA,GAAG,CAAC,MAAM,GAAG,CAAC,OAAO,KAAI;AACvB,QAAA,GAAG,CAAC,MAAM,CAAC,CAAC,IAAI,KAAI;YAClB,OAAO,CAAC,IAAI,CAAC;AACb,YAAA,OAAO,IAAI;AACb,SAAC,CAAC;AACJ,KAAC;AAED,IAAA,OAAO,GAAG;AACZ;AAEA;;;;;;;;;;;;;;;;;;;AAmBG;AACG,SAAU,SAAS,CACvB,KAAwB,EAAA;IAExB,OAAO,QAAQ,IAAI,KAAK,IAAI,OAAO,KAAK,CAAC,MAAM,KAAK,UAAU;AAChE;;ACpIA;;AAEG;;;;"}
+{"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';\n\n/**\n * Converts a read-only `Signal` into a `WritableSignal` by providing custom `set` and, optionally, `update` functions.\n * This can be useful for creating controlled write access to a signal that is otherwise read-only.\n *\n * @typeParam T - The type of value held by the signal.\n *\n * @param signal - The read-only `Signal` to be made writable.\n * @param set - A function that will be used to set the signal's value.  This function *must* handle\n *              the actual update mechanism (e.g., updating a backing store, emitting an event, etc.).\n * @param update - (Optional) A function that will be used to update the signal's value based on its\n *                 previous value.  If not provided, a default `update` implementation is used that\n *                 calls the provided `set` function with the result of the updater function. The\n *                 default implementation uses `untracked` to avoid creating unnecessary dependencies\n *                 within the updater function.\n *\n * @returns A `WritableSignal` that uses the provided `set` and `update` functions.  The `asReadonly`\n *          method of the returned signal will still return the original read-only signal.\n *\n * @example\n * // Basic usage: Making a read-only signal writable with a custom set function.\n * const originalValue = signal({a: 0});\n * const readOnlySignal = computed(() => originalValue().a);\n * const writableSignal = toWritable(readOnlySignal, (newValue) => {\n *  originalValue.update((prev) => { ...prev, a: newValue });\n * });\n *\n * writableSignal.set(5); // sets value of originalValue.a to 5 & triggers all signals\n */\nexport function toWritable<T>(\n  signal: Signal<T>,\n  set: (value: T) => void,\n  update?: (updater: (value: T) => T) => void,\n): WritableSignal<T> {\n  const internal = signal as WritableSignal<T>;\n  internal.asReadonly = () => signal;\n  internal.set = set;\n  internal.update = update ?? ((updater) => set(updater(untracked(internal))));\n\n  return internal;\n}\n","import {\n  computed,\n  type CreateSignalOptions,\n  type Signal,\n  signal,\n  type WritableSignal,\n} from '@angular/core';\nimport { toWritable } from './to-writable';\n\n/**\n * Options for creating a debounced writable signal.\n * Extends Angular's `CreateSignalOptions` with a debounce time setting.\n *\n * @template T The type of value held by the signal.\n */\nexport type CreateDebouncedOptions<T> = CreateSignalOptions<T> & {\n  /**\n   * The debounce delay in milliseconds. Specifies how long to wait after the\n   * last `set` or `update` call before the debounced signal reflects the new value.\n   */\n  ms?: number;\n};\n\n/**\n * A specialized `WritableSignal` whose publicly readable value updates are debounced.\n *\n * It provides access to the underlying, non-debounced signal via the `original` property.\n *\n * @template T The type of value held by the signal.\n */\nexport type DebouncedSignal<T> = WritableSignal<T> & {\n  /**\n   * A reference to the original, inner `WritableSignal`.\n   * This signal's value is updated *immediately* upon calls to `set` or `update`\n   * on the parent `DebouncedSignal`. Useful for accessing the latest value\n   * without the debounce delay.\n   */\n  original: Signal<T>;\n};\n\n/**\n * Creates a `WritableSignal` whose publicly readable value is updated only after\n * a specified debounce period (`ms`) has passed since the last call to its\n * `.set()` or `.update()` method.\n *\n * This implementation avoids using `effect` by leveraging intermediate `computed`\n * signals and a custom `equal` function to delay value propagation based on a timer.\n *\n * @template T The type of value the signal holds.\n * @param initial The initial value of the signal.\n * @param opt Options for signal creation, including:\n * - `ms`: The debounce time in milliseconds. Defaults to 0 if omitted (no debounce).\n * - Other `CreateSignalOptions` (like `equal`) are passed to underlying signals.\n * @returns A `DebouncedSignal<T>` instance. Its readable value updates are debounced,\n * and it includes an `.original` property providing immediate access to the latest set value.\n *\n * @example\n * ```ts\n * import { effect } from '@angular/core';\n *\n * // Create a debounced signal with a 500ms delay\n * const query = debounced('', { ms: 500 });\n *\n * effect(() => {\n * // This effect runs 500ms after the last change to 'query'\n * console.log('Debounced Query:', query());\n * });\n *\n * effect(() => {\n * // This effect runs immediately when 'query.original' changes\n * console.log('Original Query:', query.original());\n * });\n *\n * console.log('Setting query to \"a\"');\n * query.set('a');\n * // Output: Original Query: a\n *\n * setTimeout(() => {\n * console.log('Setting query to \"ab\"');\n * query.set('ab');\n * // Output: Original Query: ab\n * }, 200); // Before debounce timeout\n *\n * setTimeout(() => {\n * console.log('Setting query to \"abc\"');\n * query.set('abc');\n * // Output: Original Query: abc\n * }, 400); // Before debounce timeout\n *\n * // ~500ms after the *last* set (at 400ms), the debounced effect runs:\n * // Output (at ~900ms): Debounced Query: abc\n * ```\n */\nexport function debounced<T>(\n  initial: T,\n  opt: CreateDebouncedOptions<T>,\n): DebouncedSignal<T> {\n  const internal = signal(initial, opt);\n  const ms = opt.ms ?? 0;\n\n  const trigger = signal(false);\n\n  let timeout: ReturnType<typeof setTimeout> | undefined;\n\n  const set = (value: T) => {\n    if (timeout) clearTimeout(timeout);\n    internal.set(value);\n\n    timeout = setTimeout(() => {\n      trigger.update((c) => !c);\n    }, ms);\n  };\n\n  const update = (fn: (prev: T) => T) => {\n    if (timeout) clearTimeout(timeout);\n    internal.update(fn);\n\n    timeout = setTimeout(() => {\n      trigger.update((c) => !c);\n    }, ms);\n  };\n\n  const stable = computed(\n    () => ({\n      trigger: trigger(),\n      value: internal(),\n    }),\n    {\n      equal: (a, b) => a.trigger === b.trigger,\n    },\n  );\n\n  const writable = toWritable(\n    computed(() => stable().value, opt),\n    set,\n    update,\n  ) as DebouncedSignal<T>;\n  writable.original = internal;\n\n  return writable;\n}\n","import {\n  computed,\n  CreateSignalOptions,\n  signal,\n  untracked,\n  type WritableSignal,\n} from '@angular/core';\nimport type { UnknownObject } from '@mmstack/object';\nimport { toWritable } from './to-writable';\n\n/**\n * Options for creating a derived signal using the full `derived` function signature.\n * @typeParam T - The type of the source signal's value (parent).\n * @typeParam U - The type of the derived signal's value (child).\n */\ntype CreateDerivedOptions<T, U> = CreateSignalOptions<U> & {\n  /**\n   * A function that extracts the derived value (`U`) from the source signal's value (`T`).\n   */\n  from: (v: T) => U;\n  /**\n   * A function that updates the source signal's value (`T`) when the derived signal's value (`U`) changes.\n   * This establishes the two-way binding.\n   */\n  onChange: (newValue: U) => void;\n};\n\n/**\n * A `WritableSignal` that derives its value from another `WritableSignal` (the \"source\" signal).\n * It provides two-way binding: changes to the source signal update the derived signal, and\n * changes to the derived signal update the source signal.\n *\n * @typeParam T - The type of the source signal's value (parent).\n * @typeParam U - The type of the derived signal's value (child).\n */\nexport type DerivedSignal<T, U> = WritableSignal<U> & {\n  /**\n   * The function used to derive the derived signal's value from the source signal's value.\n   * This is primarily for internal use and introspection.\n   */\n  from: (v: T) => U;\n};\n\n/**\n * Creates a `DerivedSignal` that derives its value from another `WritableSignal` (the source signal).\n * This overload provides the most flexibility, allowing you to specify custom `from` and `onChange` functions.\n *\n * @typeParam T - The type of the source signal's value.\n * @typeParam U - The type of the derived signal's value.\n * @param source - The source `WritableSignal`.\n * @param options - An object containing the `from` and `onChange` functions, and optional signal options.\n * @returns A `DerivedSignal` instance.\n *\n * @example\n * const user = signal({ name: 'John', age: 30 });\n * const name = derived(user, {\n *   from: (u) => u.name,\n *   onChange: (newName) => user.update((u) => ({ ...u, name: newName })),\n * });\n */\nexport function derived<T, U>(\n  source: WritableSignal<T>,\n  opt: CreateDerivedOptions<T, U>,\n): DerivedSignal<T, U>;\n\n/**\n * Creates a `DerivedSignal` that derives a property from an object held by the source signal.\n * This overload simplifies creating derived signals for object properties.\n *\n * @typeParam T - The type of the source signal's value (must be an object).\n * @typeParam TKey - The key of the property to derive.\n * @param source - The source `WritableSignal` (holding an object).\n * @param key - The key of the property to derive.\n * @param options - Optional signal options for the derived signal.\n * @returns A `DerivedSignal` instance.\n *\n * @example\n * const user = signal({ name: 'John', age: 30 });\n * const name = derived(user, 'name');\n */\nexport function derived<T extends UnknownObject, TKey extends keyof T>(\n  source: WritableSignal<T>,\n  key: TKey,\n  opt?: CreateSignalOptions<T[TKey]>,\n): DerivedSignal<T, T[TKey]>;\n\n/**\n * Creates a `DerivedSignal` from an array, and derives an element by index.\n *\n * @typeParam T - The type of the source signal's value (must be an array).\n * @param source - The source `WritableSignal` (holding an array).\n * @param index - The index of the element to derive.\n * @param options - Optional signal options for the derived signal.\n * @returns A `DerivedSignal` instance.\n *\n * @example\n * const numbers = signal([1, 2, 3]);\n * const secondNumber = derived(numbers, 1); // secondNumber() === 2\n * secondNumber.set(5); // numbers() === [1, 5, 3]\n */\nexport function derived<T extends any[]>(\n  source: WritableSignal<T>,\n  index: number,\n  opt?: CreateSignalOptions<T[number]>,\n): DerivedSignal<T, T[number]>;\n\nexport function derived<T, U>(\n  source: WritableSignal<T>,\n  optOrKey: CreateDerivedOptions<T, U> | keyof T,\n  opt?: CreateSignalOptions<U>,\n): DerivedSignal<T, U> {\n  const isArray =\n    Array.isArray(untracked(source)) && typeof optOrKey === 'number';\n\n  const from =\n    typeof optOrKey === 'object' ? optOrKey.from : (v: T) => v[optOrKey] as U;\n  const onChange =\n    typeof optOrKey === 'object'\n      ? optOrKey.onChange\n      : isArray\n        ? (next: U) => {\n            source.update(\n              (cur) =>\n                (cur as unknown as any[]).map((v, i) =>\n                  i === optOrKey ? next : v,\n                ) as T,\n            );\n          }\n        : (next: U) => {\n            source.update((cur) => ({ ...cur, [optOrKey]: next }));\n          };\n\n  const rest = typeof optOrKey === 'object' ? optOrKey : opt;\n\n  const sig = toWritable<U>(\n    computed(() => from(source()), rest),\n    (newVal) => onChange(newVal),\n  ) as DerivedSignal<T, U>;\n\n  sig.from = from;\n\n  return sig;\n}\n\n/**\n * Creates a \"fake\" `DerivedSignal` from a simple value. This is useful for creating\n * `FormControlSignal` instances that are not directly derived from another signal.\n * The returned signal's `from` function will always return the initial value.\n *\n * @typeParam T -  This type parameter is not used in the implementation but is kept for type compatibility with `DerivedSignal`.\n * @typeParam U - The type of the signal's value.\n * @param initial - The initial value of the signal.\n * @returns A `DerivedSignal` instance.\n * @internal\n */\nexport function toFakeDerivation<T, U>(initial: U): DerivedSignal<T, U> {\n  const sig = signal(initial) as DerivedSignal<T, U>;\n  sig.from = () => initial;\n\n  return sig;\n}\n\n/**\n * Creates a \"fake\" `DerivedSignal` from an existing `WritableSignal`. This is useful\n * for treating a regular `WritableSignal` as a `DerivedSignal` without changing its behavior.\n *  The returned signal's `from` function returns the current value of signal, using `untracked`.\n *\n * @typeParam T - This type parameter is not used in the implementation but is kept for type compatibility with `DerivedSignal`.\n * @typeParam U - The type of the signal's value.\n * @param initial - The existing `WritableSignal`.\n * @returns A `DerivedSignal` instance.\n * @internal\n */\nexport function toFakeSignalDerivation<T, U>(\n  initial: WritableSignal<U>,\n): DerivedSignal<T, U> {\n  const sig = initial as DerivedSignal<T, U>;\n  sig.from = () => untracked(initial);\n  return sig;\n}\n\n/**\n * Type guard function to check if a given `WritableSignal` is a `DerivedSignal`.\n *\n * @typeParam T - The type of the source signal's value (optional, defaults to `any`).\n * @typeParam U - The type of the derived signal's value (optional, defaults to `any`).\n * @param sig - The `WritableSignal` to check.\n * @returns `true` if the signal is a `DerivedSignal`, `false` otherwise.\n */\nexport function isDerivation<T, U>(\n  sig: WritableSignal<U>,\n): sig is DerivedSignal<T, U> {\n  return 'from' in sig;\n}\n","import {\n  computed,\n  type CreateSignalOptions,\n  isSignal,\n  linkedSignal,\n  type Signal,\n} from '@angular/core';\n\n/**\n * Reactively maps items from a source array (or signal of an array) using a provided mapping function.\n *\n * This function serves a similar purpose to SolidJS's `mapArray` by providing stability\n * for mapped items. It receives a source function returning an array (or a Signal<T[]>)\n * and a mapping function.\n *\n * For each item in the source array, it creates a stable `computed` signal representing\n * that item's value at its current index. This stable signal (`Signal<T>`) is passed\n * to the mapping function. This ensures that downstream computations or components\n * depending on the mapped result only re-render or re-calculate for the specific items\n * that have changed, or when items are added/removed, rather than re-evaluating everything\n * when the source array reference changes but items remain the same.\n *\n * It efficiently handles changes in the source array's length by reusing existing mapped\n * results when possible, slicing when the array shrinks, and appending new mapped items\n * when it grows.\n *\n * @template T The type of items in the source array.\n * @template U The type of items in the resulting mapped array.\n *\n * @param source A function returning the source array `T[]`, or a `Signal<T[]>` itself.\n * The `mapArray` function will reactively update based on changes to this source.\n * @param map The mapping function. It is called for each item in the source array.\n * It receives:\n * - `value`: A stable `Signal<T>` representing the item at the current index.\n * Use this signal within your mapping logic if you need reactivity\n * tied to the specific item's value changes.\n * - `index`: The number index of the item in the array.\n * It should return the mapped value `U`.\n * @param [opt] Optional `CreateSignalOptions<T>`. These options are passed directly\n * to the `computed` signal created for each individual item (`Signal<T>`).\n * This allows specifying options like a custom `equal` function for item comparison.\n *\n * @returns A `Signal<U[]>` containing the mapped array. This signal updates whenever\n * the source array changes (either length or the values of its items).\n *\n * @example\n * ```ts\n * const sourceItems = signal([\n * { id: 1, name: 'Apple' },\n * { id: 2, name: 'Banana' }\n * ]);\n *\n * const mappedItems = mapArray(\n * sourceItems,\n * (itemSignal, index) => {\n * // itemSignal is stable for a given item based on its index.\n * // We create a computed here to react to changes in the item's name.\n *  return computed(() => `${index}: ${itemSignal().name.toUpperCase()}`);\n * },\n * // Example optional options (e.g., custom equality for item signals)\n * { equal: (a, b) => a.id === b.id && a.name === b.name }\n * );\n * ```\n */\nexport function mapArray<T, U>(\n  source: () => T[],\n  map: (value: Signal<T>, index: number) => U,\n  opt?: CreateSignalOptions<T>,\n): Signal<U[]> {\n  const data = isSignal(source) ? source : computed(source);\n  const len = computed(() => data().length);\n\n  return linkedSignal<number, U[]>({\n    source: () => len(),\n    computation: (len, prev) => {\n      if (!prev)\n        return Array.from({ length: len }, (_, i) =>\n          map(\n            computed(() => source()[i], opt),\n            i,\n          ),\n        );\n\n      if (len === prev.value.length) return prev.value;\n\n      if (len < prev.value.length) {\n        return prev.value.slice(0, len);\n      } else {\n        const next = [...prev.value];\n        for (let i = prev.value.length; i < len; i++) {\n          next[i] = map(\n            computed(() => source()[i], opt),\n            i,\n          );\n        }\n        return next;\n      }\n    },\n    equal: (a, b) => a.length === b.length,\n  });\n}\n","import {\r\n  signal,\r\n  type CreateSignalOptions,\r\n  type ValueEqualityFn,\r\n  type WritableSignal,\r\n} from '@angular/core';\r\n\r\nconst { is } = Object;\r\n\r\n/**\r\n * A `MutableSignal` is a special type of `WritableSignal` that allows for in-place mutation of its value.\r\n * In addition to the standard `set` and `update` methods, it provides a `mutate` method.  This is useful\r\n * for performance optimization when dealing with complex objects or arrays, as it avoids unnecessary\r\n * object copying.\r\n *\r\n * @typeParam T - The type of value held by the signal.\r\n */\r\nexport type MutableSignal<T> = WritableSignal<T> & {\r\n  /**\r\n   * Mutates the signal's value in-place.  This is similar to `update`, but it's optimized for\r\n   * scenarios where you want to modify the existing object directly rather than creating a new one.\r\n   *\r\n   * @param updater - A function that takes the current value as input and modifies it directly.\r\n   *\r\n   * @example\r\n   * const myArray = mutable([1, 2, 3]);\r\n   * myArray.mutate((arr) => {\r\n   *  arr.push(4);\r\n   *  return arr;\r\n   * }); // myArray() now returns [1, 2, 3, 4]\r\n   */\r\n  mutate: WritableSignal<T>['update'];\r\n\r\n  /**\r\n   * Mutates the signal's value in-place, similar to `mutate`, but with a void-returning value in updater\r\n   * function. This further emphasizes that the mutation is happening inline, improving readability\r\n   * in some cases.\r\n   * @param updater - Function to change to the current value\r\n   * @example\r\n   * const myObject = mutable({ a: 1, b: 2 });\r\n   * myObject.inline((obj) => (obj.a = 3)); // myObject() now returns { a: 3, b: 2 }\r\n   */\r\n  inline: (updater: (value: T) => void) => void;\r\n};\r\n\r\n/**\r\n * Creates a `MutableSignal`. This function overloads the standard `signal` function to provide\r\n * the additional `mutate` and `inline` methods.\r\n *\r\n * @typeParam T - The type of value held by the signal.\r\n *\r\n * @param initial - The initial value of the signal.  If no initial value is provided, it defaults to `undefined`.\r\n * @param options - Optional. An object containing signal options, including a custom equality function (`equal`).\r\n *\r\n * @returns A `MutableSignal` instance.\r\n *\r\n * @example\r\n * // Create a mutable signal with an initial value:\r\n * const mySignal = mutable({ count: 0 }) // MutableSignal<{ count: number }>;\r\n *\r\n * // Create a mutable signal with no initial value (starts as undefined):\r\n * const = mutable<number>(); // MutableSignal<number | undefined>\r\n *\r\n * // Create a mutable signal with a custom equality function:\r\n * const myCustomSignal = mutable({ a: 1 }, { equal: (a, b) => a.a === b.a });\r\n */\r\nexport function mutable<T>(): MutableSignal<T | undefined>;\r\nexport function mutable<T>(initial: T): MutableSignal<T>;\r\nexport function mutable<T>(\r\n  initial: T,\r\n  opt?: CreateSignalOptions<T>,\r\n): MutableSignal<T>;\r\n\r\nexport function mutable<T>(\r\n  initial?: T,\r\n  opt?: CreateSignalOptions<T>,\r\n): MutableSignal<T> {\r\n  const baseEqual = opt?.equal ?? is;\r\n  let trigger = false;\r\n\r\n  const equal: ValueEqualityFn<T | undefined> = (a, b) => {\r\n    if (trigger) return false;\r\n    return baseEqual(a, b);\r\n  };\r\n\r\n  const sig = signal<T | undefined>(initial, {\r\n    ...opt,\r\n    equal,\r\n  }) as MutableSignal<T>;\r\n\r\n  const internalUpdate = sig.update;\r\n\r\n  sig.mutate = (updater) => {\r\n    trigger = true;\r\n    internalUpdate(updater);\r\n    trigger = false;\r\n  };\r\n\r\n  sig.inline = (updater) => {\r\n    sig.mutate((prev) => {\r\n      updater(prev);\r\n      return prev;\r\n    });\r\n  };\r\n\r\n  return sig;\r\n}\r\n\r\n/**\r\n * Type guard function to check if a given `WritableSignal` is a `MutableSignal`.  This is useful\r\n * for situations where you need to conditionally use the `mutate` or `inline` methods.\r\n *\r\n * @typeParam T - The type of the signal's value (optional, defaults to `any`).\r\n * @param value - The `WritableSignal` to check.\r\n * @returns `true` if the signal is a `MutableSignal`, `false` otherwise.\r\n *\r\n * @example\r\n * const mySignal = signal(0);\r\n * const myMutableSignal = mutable(0);\r\n *\r\n * if (isMutable(mySignal)) {\r\n *   mySignal.mutate(x => x + 1); // This would cause a type error, as mySignal is not a MutableSignal.\r\n * }\r\n *\r\n * if (isMutable(myMutableSignal)) {\r\n *   myMutableSignal.mutate(x => x + 1); // This is safe.\r\n * }\r\n */\r\nexport function isMutable<T = any>(\r\n  value: WritableSignal<T>,\r\n): value is MutableSignal<T> {\r\n  return 'mutate' in value && typeof value.mutate === 'function';\r\n}\r\n","import { isPlatformServer } from '@angular/common';\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 {\n  computed,\n  type CreateSignalOptions,\n  type Signal,\n  untracked,\n  type ValueEqualityFn,\n  type WritableSignal,\n} from '@angular/core';\nimport { SIGNAL } from '@angular/core/primitives/signals';\nimport { mutable } from './mutable';\nimport { toWritable } from './to-writable';\n\nexport type SignalWithHistory<T> = WritableSignal<T> & {\n  history: Signal<T[]>;\n  undo: () => void;\n  redo: () => void;\n  canRedo: Signal<boolean>;\n  canUndo: Signal<boolean>;\n  clear: () => void;\n  canClear: Signal<boolean>;\n};\n\nexport type CreateHistoryOptions<T> = Omit<\n  CreateSignalOptions<T[]>,\n  'equal'\n> & {\n  maxSize?: number;\n};\n\nexport function withHistory<T>(\n  source: WritableSignal<T>,\n  opt?: CreateHistoryOptions<T>,\n): SignalWithHistory<T> {\n  const { equal = Object.is, debugName } = source[SIGNAL] as {\n    equal?: ValueEqualityFn<T>;\n    debugName?: string;\n  };\n\n  const maxSize = opt?.maxSize ?? Infinity;\n\n  const history = mutable<T[]>([], opt);\n\n  const redoArray = mutable<T[]>([]);\n\n  const set = (value: T) => {\n    const current = untracked(source);\n    if (equal(value, current)) return;\n\n    source.set(value);\n\n    history.mutate((c) => {\n      if (c.length >= maxSize) {\n        c = c.slice(Math.floor(maxSize / 2));\n      }\n      c.push(current);\n      return c;\n    });\n    redoArray.set([]);\n  };\n\n  const update = (updater: (prev: T) => T) => {\n    set(updater(untracked(source)));\n  };\n\n  const internal = toWritable(\n    computed(() => source(), {\n      equal,\n      debugName,\n    }),\n    set,\n    update,\n  ) as SignalWithHistory<T>;\n  internal.history = history;\n\n  internal.undo = () => {\n    const last = untracked(history);\n    if (last.length === 0) return;\n\n    const prev = last.at(-1)!;\n    const cur = untracked(source);\n\n    history.inline((c) => c.pop());\n    redoArray.inline((c) => c.push(cur));\n\n    source.set(prev);\n  };\n\n  internal.redo = () => {\n    const last = untracked(redoArray);\n    if (last.length === 0) return;\n\n    const prev = last.at(-1)!;\n\n    redoArray.inline((c) => c.pop());\n\n    set(prev);\n  };\n\n  internal.clear = () => {\n    history.set([]);\n    redoArray.set([]);\n  };\n\n  internal.canUndo = computed(() => history().length > 0);\n  internal.canRedo = computed(() => redoArray().length > 0);\n  internal.canClear = computed(() => internal.canUndo() || internal.canRedo());\n\n  return internal;\n}\n","/**\n * Generated bundle index. Do not edit.\n */\n\nexport * from './index';\n"],"names":[],"mappings":"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"}

package/index.d.ts

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

package/lib/debounced.d.ts

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

package/lib/map-array.d.ts

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

package/lib/mutable.d.ts

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

package/lib/stored.d.ts

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

package/lib/with-history.d.ts

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