@mmstack/primitives 19.1.0 → 19.1.2

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.0",
+  "version": "19.1.2",
   "keywords": [
     "angular",
     "signals",