@mmstack/primitives 21.0.4 → 21.0.6

package/package.json

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

package/types/mmstack-primitives.d.ts

@@ -1,4 +1,4 @@
-import { CreateSignalOptions, DestroyRef, WritableSignal, Signal, EffectCleanupRegisterFn, CreateEffectOptions, ElementRef, Injector, ValueEqualityFn } from '@angular/core';
+import { CreateSignalOptions, DestroyRef, WritableSignal, Signal, EffectCleanupRegisterFn, CreateEffectOptions, Injector, EffectRef, ElementRef, ValueEqualityFn } from '@angular/core';
 
 /**
  * Options for creating a debounced writable signal.
@@ -271,31 +271,32 @@ declare function derived<T, U>(source: WritableSignal<T>, opt: CreateDerivedOpti
  * console.log(user().name); // Outputs: Jane
  * ```
  */
-declare function derived<T extends UnknownObject, TKey extends keyof T>(source: WritableSignal<T>, key: TKey, opt?: CreateSignalOptions<T[TKey]>): DerivedSignal<T, T[TKey]>;
+declare function derived<T extends UnknownObject, TKey extends keyof T>(source: MutableSignal<T>, key: TKey, opt?: CreateSignalOptions<T[TKey]>): DerivedSignal<T, T[TKey]> & MutableSignal<T[TKey]>;
 /**
- * Creates a `DerivedSignal` from an array, deriving an element by its index.
- * This overload is a convenient shorthand for accessing array elements.
+ * Creates a `DerivedSignal` that derives a property from an object held by the source signal.
+ * This overload is a convenient shorthand for accessing object properties.
  *
- * @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.
+ * @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 numbers = signal([1, 2, 3]);
- * const secondNumber = derived(numbers, 1);
+ * const user = signal({ name: 'John', age: 30 });
+ * const name = derived(user, 'name');
  *
- * console.log(secondNumber()); // Outputs: 2
+ * console.log(name()); // Outputs: John
  *
  * // Update the derived signal, which also updates the source
- * secondNumber.set(5);
+ * name.set('Jane');
  *
- * console.log(numbers()); // Outputs: [1, 5, 3]
+ * console.log(user().name); // Outputs: Jane
  * ```
  */
-declare function derived<T extends any[]>(source: WritableSignal<T>, index: number, opt?: CreateSignalOptions<T[number]>): DerivedSignal<T, T[number]>;
+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` that derives its value from another `MutableSignal`.
  * Use mutuable signals with caution, but very useful for deeply nested structures.
@@ -319,6 +320,30 @@ declare function derived<T extends any[]>(source: WritableSignal<T>, index: numb
  * ```
  */
 declare function derived<T, U>(source: MutableSignal<T>, optOrKey: CreateDerivedOptions<T, U> | keyof T, opt?: CreateSignalOptions<U>): DerivedSignal<T, U> & MutableSignal<U>;
+/**
+ * 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.
+ * @returns A `DerivedSignal` instance.
+ *
+ * @example
+ * ```ts
+ * const numbers = signal([1, 2, 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]
+ * ```
+ */
+declare function derived<T extends any[]>(source: WritableSignal<T>, index: number, opt?: CreateSignalOptions<T[number]>): DerivedSignal<T, T[number]>;
 /**
  * Creates a "fake" `DerivedSignal` from a simple value. This is useful for creating
  * `FormControlSignal` instances that are not directly derived from another signal.
@@ -407,31 +432,51 @@ declare function indexArray<T, U>(source: Signal<T[]> | (() => T[]), map: (value
 declare const mapArray: typeof indexArray;
 
 /**
- * Reactively maps items from a source array to a new array using a key function to maintain stability.
+ * Reactively maps items from a source array to a new array by value (identity).
  *
- * This function preserves the `mapped` signals for items even if they move within the array,
- * as long as their key remains the same. This is equivalent to SolidJS's `mapArray` or Angular's `@for (item of items; track item.id)`.
+ * similar to `Array.prototype.map`, but:
+ * 1. The `mapFn` receives the `index` as a Signal.
+ * 2. If an item in the `source` array moves to a new position, the *result* of the map function is reused and moved.
+ *    The `index` signal is updated to the new index.
+ * 3. The `mapFn` is only run for *new* items.
  *
- * @template T The type of items in the source array.
- * @template U The type of items in the resulting mapped array.
- * @template K The type of the key.
+ * This is useful for building efficient lists where DOM nodes or heavy instances should be reused
+ * when the list is reordered.
  *
  * @param source A `Signal<T[]>` or a function returning `T[]`.
- * @param keyFn A function to extract a unique key for each item.
- * @param map The mapping function. It receives a stable signal for the item and a signal for its index.
- * @param options Optional configuration, including `CreateSignalOptions` and an `onDestroy` callback.
+ * @param mapFn The mapping function. Receives the item and its index as a Signal.
+ * @param options Optional configuration:
+ *  - `onDestroy`: A callback invoked when a mapped item is removed from the array.
  * @returns A `Signal<U[]>` containing the mapped array.
  */
-declare function keyArray<T, U>(source: MutableSignal<T[]>, keyFn: (item: T) => string | number, map: (value: MutableSignal<T>, index: Signal<number>) => U, options?: CreateSignalOptions<T> & {
+declare function keyArray<T, U, K>(source: Signal<T[]> | (() => T[]), mapFn: (v: T, i: Signal<number>) => U, options?: {
     onDestroy?: (value: U) => void;
+    /**
+     * Optional function to use a custom key for item comparison.
+     * Use this if you want to reuse mapped items based on a property (like an ID)
+     * even if the item reference changes.
+     */
+    key?: (item: T) => K;
 }): Signal<U[]>;
-declare function keyArray<T, U>(source: WritableSignal<T[]>, keyFn: (item: T) => string | number, map: (value: WritableSignal<T>, index: Signal<number>) => U, options?: CreateSignalOptions<T> & {
+
+type MappedObject<T extends Record<string, any>, U> = {
+    [K in keyof T]: U;
+};
+declare function mapObject<T extends Record<string, any>, U>(source: MutableSignal<T>, mapFn: <K extends keyof T>(key: K, value: MutableSignal<T[K]>) => U, options?: {
     onDestroy?: (value: U) => void;
-}): Signal<U[]>;
-declare function keyArray<T, U>(source: Signal<T[]> | (() => T[]), keyFn: (item: T) => string | number, map: (value: Signal<T>, index: Signal<number>) => U, options?: CreateSignalOptions<T> & {
+}): Signal<MappedObject<T, U>>;
+declare function mapObject<T extends Record<string, any>, U>(source: WritableSignal<T>, mapFn: <K extends keyof T>(key: K, value: WritableSignal<T[K]>) => U, options?: {
     onDestroy?: (value: U) => void;
-}): Signal<U[]>;
+}): Signal<MappedObject<T, U>>;
+declare function mapObject<T extends Record<string, any>, U>(source: (() => T) | Signal<T>, mapFn: <K extends keyof T>(key: K, value: Signal<T[K]>) => U, options?: {
+    onDestroy?: (value: U) => void;
+}): Signal<MappedObject<T, U>>;
 
+type Frame = {
+    injector: Injector;
+    parent: Frame | null;
+    children: Set<EffectRef>;
+};
 /**
  * Creates an effect that can be nested, similar to SolidJS's `createEffect`.
  *
@@ -470,42 +515,42 @@ declare function keyArray<T, U>(source: Signal<T[]> | (() => T[]), keyFn: (item:
  * @example
  * ```ts
  * const users = signal([
-  { id: 1, name: 'Alice' },
-  { id: 2, name: 'Bob' }
-]);
-
-// The fine-grained mapped list
-const mappedUsers = mapArray(
-  users,
-  (userSignal, index) => {
-    // 1. Create a fine-grained SIDE EFFECT for *this item*
-    // This effect's lifetime is now tied to this specific item. created once on init of this index.
-    const effectRef = nestedEffect(() => {
-      // This only runs if *this* userSignal changes,
-      // not if the whole list changes.
-      console.log(`User ${index} updated:`, userSignal().name);
-    });
-
-    // 2. Return the data AND the cleanup logic
-    return {
-      // The mapped data
-      label: computed(() => `User: ${userSignal().name}`),
-      
-      // The cleanup function
-      destroyEffect: () => effectRef.destroy()
-    };
-  },
-  {
-    // 3. Tell mapArray HOW to clean up when an item is removed, this needs to be manual as it's not a nestedEffect itself
-    onDestroy: (mappedItem) => {
-      mappedItem.destroyEffect();
-    }
-  }
-);
+ *   { id: 1, name: 'Alice' },
+ *   { id: 2, name: 'Bob' }
+ * ]);
+ *
+ * // The fine-grained mapped list
+ * const mappedUsers = mapArray(
+ *   users,
+ *   (userSignal, index) => {
+ *     // 1. Create a fine-grained SIDE EFFECT for *this item*
+ *     // This effect's lifetime is now tied to this specific item. created once on init of this index.
+ *     const effectRef = nestedEffect(() => {
+ *       // This only runs if *this* userSignal changes,
+ *       // not if the whole list changes.
+ *       console.log(`User ${index} updated:`, userSignal().name);
+ *     });
+ *
+ *     // 2. Return the data AND the cleanup logic
+ *     return {
+ *       // The mapped data
+ *       label: computed(() => `User: ${userSignal().name}`),
+ *
+ *       // The cleanup function
+ *       destroyEffect: () => effectRef.destroy()
+ *     };
+ *   },
+ *   {
+ *     // 3. Tell mapArray HOW to clean up when an item is removed, this needs to be manual as it's not a nestedEffect itself
+ *     onDestroy: (mappedItem) => {
+ *       mappedItem.destroyEffect();
+ *     }
+ *   }
+ * );
  * ```
  */
 declare function nestedEffect(effectFn: (registerCleanup: EffectCleanupRegisterFn) => void, options?: CreateEffectOptions & {
-    bindToFrame?: number;
+    bindToFrame?: (parent: Frame | null) => Frame | null;
 }): {
     destroy: () => void;
 };
@@ -1252,25 +1297,21 @@ type Sensors<TKey extends keyof SensorTypedOptions> = {
 declare function sensors<const TType extends keyof SensorTypedOptions>(track: TType[], opt?: SensorsOptions<TType>): Sensors<TType>;
 
 type AnyRecord = Record<PropertyKey, any>;
-type NonRecord = Iterable<any> | WeakSet<any> | WeakMap<any, any> | Promise<any> | Date | Error | RegExp | ArrayBuffer | DataView | Function | Array<any>;
-type IsRecord<T> = T extends object ? T extends NonRecord ? false : true : false;
-type IsUnknownRecord<T> = keyof T extends never ? true : string extends keyof T ? true : symbol extends keyof T ? true : number extends keyof T ? true : false;
-type IsKnownRecord<T> = IsRecord<T> extends true ? IsUnknownRecord<T> extends true ? false : true : false;
-type SignalStore<T> = Signal<T> & (IsKnownRecord<T> extends true ? Readonly<{
-    [K in keyof T]: IsKnownRecord<T[K]> extends true ? SignalStore<T[K]> : Signal<T[K]>;
-}> : unknown);
-type WritableSignalStore<T> = WritableSignal<T> & (IsKnownRecord<T> extends true ? Readonly<{
-    [K in keyof T]: IsKnownRecord<T[K]> extends true ? WritableSignalStore<T[K]> : WritableSignal<T[K]>;
-}> : unknown);
-type MutableSignalStore<T> = MutableSignal<T> & (IsKnownRecord<T> extends true ? Readonly<{
-    [K in keyof T]: IsKnownRecord<T[K]> extends true ? MutableSignalStore<T[K]> : MutableSignal<T[K]>;
-}> : unknown);
-type inferValid<T extends AnyRecord> = IsKnownRecord<T> extends false ? never : T;
-declare function toStore<T extends AnyRecord>(source: MutableSignal<inferValid<T>>, injector?: Injector): MutableSignalStore<T>;
-declare function toStore<T extends AnyRecord>(source: WritableSignal<inferValid<T>>, injector?: Injector): WritableSignalStore<T>;
-declare function toStore<T extends AnyRecord>(source: Signal<inferValid<T>>, injector?: Injector): SignalStore<T>;
-declare function store<T extends AnyRecord>(value: inferValid<T>, opt?: CreateSignalOptions<T>): WritableSignalStore<T>;
-declare function mutableStore<T extends AnyRecord>(value: inferValid<T>, opt?: CreateSignalOptions<T>): MutableSignalStore<T>;
+type BaseType = string | number | boolean | symbol | undefined | null | Function | Date | RegExp | any[];
+type SignalStore<T> = Signal<T> & (T extends BaseType ? unknown : Readonly<{
+    [K in keyof T]: SignalStore<T[K]>;
+}>);
+type WritableSignalStore<T> = WritableSignal<T> & (T extends BaseType ? unknown : Readonly<{
+    [K in keyof T]: WritableSignalStore<T[K]>;
+}>);
+type MutableSignalStore<T> = MutableSignal<T> & (T extends BaseType ? unknown : Readonly<{
+    [K in keyof T]: MutableSignalStore<T[K]>;
+}>);
+declare function toStore<T extends AnyRecord>(source: MutableSignal<T>, injector?: Injector): MutableSignalStore<T>;
+declare function toStore<T extends AnyRecord>(source: WritableSignal<T>, injector?: Injector): WritableSignalStore<T>;
+declare function toStore<T extends AnyRecord>(source: Signal<T>, injector?: Injector): SignalStore<T>;
+declare function store<T extends AnyRecord>(value: T, opt?: CreateSignalOptions<T>): WritableSignalStore<T>;
+declare function mutableStore<T extends AnyRecord>(value: T, opt?: CreateSignalOptions<T>): MutableSignalStore<T>;
 
 /**
  * Interface for storage mechanisms compatible with the `stored` signal.
@@ -1709,5 +1750,5 @@ type CreateHistoryOptions<T> = Omit<CreateSignalOptions<T[]>, 'equal'> & {
  */
 declare function withHistory<T>(source: WritableSignal<T>, opt?: CreateHistoryOptions<T>): SignalWithHistory<T>;
 
-export { combineWith, debounce, debounced, derived, distinct, elementSize, elementVisibility, filter, indexArray, isDerivation, isMutable, keyArray, map, mapArray, mediaQuery, mousePosition, mutable, mutableStore, nestedEffect, networkStatus, pageVisibility, pipeable, piped, prefersDarkMode, prefersReducedMotion, scrollPosition, select, sensor, sensors, store, stored, tabSync, tap, throttle, throttled, toFakeDerivation, toFakeSignalDerivation, toStore, toWritable, until, windowSize, withHistory };
-export type { CreateDebouncedOptions, CreateHistoryOptions, CreateStoredOptions, CreateThrottledOptions, DebouncedSignal, DerivedSignal, ElementSize, ElementSizeOptions, ElementSizeSignal, ElementVisibilityOptions, ElementVisibilitySignal, IsKnownRecord, IsRecord, IsUnknownRecord, MousePositionOptions, MousePositionSignal, MutableSignal, MutableSignalStore, NetworkStatusSignal, PipeableSignal, ScrollPosition, ScrollPositionOptions, ScrollPositionSignal, SignalStore, SignalWithHistory, StoredSignal, ThrottledSignal, UntilOptions, WindowSize, WindowSizeOptions, WindowSizeSignal, WritableSignalStore };
+export { combineWith, debounce, debounced, derived, distinct, elementSize, elementVisibility, filter, indexArray, isDerivation, isMutable, keyArray, map, mapArray, mapObject, mediaQuery, mousePosition, mutable, mutableStore, nestedEffect, networkStatus, pageVisibility, pipeable, piped, prefersDarkMode, prefersReducedMotion, scrollPosition, select, sensor, sensors, store, stored, tabSync, tap, throttle, throttled, toFakeDerivation, toFakeSignalDerivation, toStore, toWritable, until, windowSize, withHistory };
+export type { CreateDebouncedOptions, CreateHistoryOptions, CreateStoredOptions, CreateThrottledOptions, DebouncedSignal, DerivedSignal, ElementSize, ElementSizeOptions, ElementSizeSignal, ElementVisibilityOptions, ElementVisibilitySignal, MousePositionOptions, MousePositionSignal, MutableSignal, MutableSignalStore, NetworkStatusSignal, PipeableSignal, ScrollPosition, ScrollPositionOptions, ScrollPositionSignal, SignalStore, SignalWithHistory, StoredSignal, ThrottledSignal, UntilOptions, WindowSize, WindowSizeOptions, WindowSizeSignal, WritableSignalStore };