@mmstack/primitives 20.0.2 → 20.0.4

package/README.md

@@ -217,7 +217,7 @@ Reactive map helper that stabilizes a source array Signal by length. It provides
 
 ```typescript
 import { Component, signal } from '@angular/core';
-import { mapArray } from '@mmstack/primitives';
+import { mapArray, mutable } from '@mmstack/primitives';
 
 @Component({
   selector: 'app-map-demo',
@@ -225,14 +225,16 @@ import { mapArray } from '@mmstack/primitives';
     <ul>
       @for (item of displayItems(); track item) {
         <li>{{ item() }}</li>
+        @if ($first) {
+            <button (click)="updateFirst(item)">Update First</button>
+        }
       }
     </ul>
     <button (click)="addItem()">Add</button>
-    <button (click)="updateFirst()">Update First</button>
   `,
 })
 export class ListComponent {
-  sourceItems = signal([
+  readonly sourceItems = signal([
     { id: 1, name: 'A' },
     { id: 2, name: 'B' },
   ]);
@@ -249,6 +251,41 @@ export class ListComponent {
       return [...items]; // New array, but mapArray keeps stable signals
     });
   }
+
+  // since the underlying source is a signal we can also create updaters in the mapper
+  readonly updatableItems = mapArray(this.sourceItems, (child, index) => {
+
+    return {
+      value: computed(() => `Item ${index}: ${child().name}`))
+      updateName: () => child.update((cur) => ({...cur, name: cur.name + '+'}))
+    };
+  });
+
+
+  // since the underlying source is a WritableSignal we can also create updaters in the mapper
+  readonly writableItems = mapArray(this.sourceItems, (child, index) => {
+
+    return {
+      value: computed(() => `Item ${index}: ${child().name}`))
+      updateName: () => child.update((cur) => ({...cur, name: cur.name + '+'}))
+    };
+  });
+
+  // if the source is a mutable signal we can even update them inline
+  readonly sourceItems = mutable([
+    { id: 1, name: 'A' },
+    { id: 2, name: 'B' },
+  ]);
+
+  readonly mutableItems = mapArray(this.sourceItems, (child, index) => {
+
+    return {
+      value: computed(() => `Item ${index}: ${child().name}`))
+      updateName: () => child.inline((cur) => {
+        cur.name += '+';
+      })
+    };
+  });
 }
 ```
 

package/fesm2022/mmstack-primitives.mjs

@@ -391,77 +391,69 @@ function elementVisibility(target = inject(ElementRef), opt) {
 }
 
 /**
- * Reactively maps items from a source array (or signal of an array) using a provided mapping function.
- *
- * This function serves a similar purpose to SolidJS's `mapArray` by providing stability
- * for mapped items. It receives a source function returning an array (or a Signal<T[]>)
- * and a mapping function.
- *
- * For each item in the source array, it creates a stable `computed` signal representing
- * that item's value at its current index. This stable signal (`Signal<T>`) is passed
- * to the mapping function. This ensures that downstream computations or components
- * depending on the mapped result only re-render or re-calculate for the specific items
- * that have changed, or when items are added/removed, rather than re-evaluating everything
- * when the source array reference changes but items remain the same.
- *
- * It efficiently handles changes in the source array's length by reusing existing mapped
- * results when possible, slicing when the array shrinks, and appending new mapped items
- * when it grows.
- *
- * @template T The type of items in the source array.
- * @template U The type of items in the resulting mapped array.
- *
- * @param source A function returning the source array `T[]`, or a `Signal<T[]>` itself.
- * The `mapArray` function will reactively update based on changes to this source.
- * @param map The mapping function. It is called for each item in the source array.
- * It receives:
- * - `value`: A stable `Signal<T>` representing the item at the current index.
- * Use this signal within your mapping logic if you need reactivity
- * tied to the specific item's value changes.
- * - `index`: The number index of the item in the array.
- * It should return the mapped value `U`.
- * @param [opt] Optional `CreateSignalOptions<T>`. These options are passed directly
- * to the `computed` signal created for each individual item (`Signal<T>`).
- * This allows specifying options like a custom `equal` function for item comparison.
- *
- * @returns A `Signal<U[]>` containing the mapped array. This signal updates whenever
- * the source array changes (either length or the values of its items).
- *
- * @example
- * ```ts
- * const sourceItems = signal([
- * { id: 1, name: 'Apple' },
- * { id: 2, name: 'Banana' }
- * ]);
- *
- * const mappedItems = mapArray(
- * sourceItems,
- * (itemSignal, index) => {
- * // itemSignal is stable for a given item based on its index.
- * // We create a computed here to react to changes in the item's name.
- *  return computed(() => `${index}: ${itemSignal().name.toUpperCase()}`);
- * },
- * // Example optional options (e.g., custom equality for item signals)
- * { equal: (a, b) => a.id === b.id && a.name === b.name }
- * );
- * ```
- * @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.
+ * @internal
+ * Checks if a signal is a WritableSignal.
+ * @param sig The signal to check.
  */
-function mapArray(source, map, opt) {
+function isWritable(sig) {
+    // We just need to check for the presence of a 'set' method.
+    return 'set' in sig;
+}
+/**
+ * @internal
+ * Creates a setter function for a source signal of type `Signal<T[]>` or a function returning `T[]`.
+ * @param source The source signal of type `Signal<T[]>` or a function returning `T[]`.
+ * @returns
+ */
+function createSetter(source) {
+    if (!isWritable(source))
+        return () => {
+            // noop;
+        };
+    if (isMutable(source))
+        return (value, index) => {
+            source.inline((arr) => {
+                arr[index] = value;
+            });
+        };
+    return (value, index) => {
+        source.update((arr) => arr.map((v, i) => (i === index ? value : v)));
+    };
+}
+function mapArray(source, map, options) {
     const data = isSignal(source) ? source : computed(source);
     const len = computed(() => data().length, ...(ngDevMode ? [{ debugName: "len" }] : []));
+    const setter = createSetter(data);
+    const opt = { ...options };
+    const writableData = isWritable(data)
+        ? data
+        : toWritable(data, () => {
+            // noop
+        });
+    if (isWritable(data) && isMutable(data) && !opt.equal) {
+        opt.equal = (a, b) => {
+            if (a !== b)
+                return false; // actually check primitives and references
+            return false; // opt out for same refs
+        };
+    }
     return linkedSignal({
         source: () => len(),
         computation: (len, prev) => {
             if (!prev)
-                return Array.from({ length: len }, (_, i) => map(computed(() => source()[i], opt), i));
+                return Array.from({ length: len }, (_, i) => {
+                    const derivation = derived(writableData, // typcase to largest type
+                    {
+                        from: (src) => src[i],
+                        onChange: (value) => setter(value, i),
+                    }, opt);
+                    return map(derivation, i);
+                });
             if (len === prev.value.length)
                 return prev.value;
             if (len < prev.value.length) {
                 const slice = prev.value.slice(0, len);
-                if (opt?.onDestroy) {
+                if (opt.onDestroy) {
                     for (let i = len; i < prev.value.length; i++) {
                         opt.onDestroy?.(prev.value[i]);
                     }
@@ -471,7 +463,12 @@ function mapArray(source, map, opt) {
             else {
                 const next = [...prev.value];
                 for (let i = prev.value.length; i < len; i++) {
-                    next[i] = map(computed(() => source()[i], opt), i);
+                    const derivation = derived(writableData, // typcase to largest type
+                    {
+                        from: (src) => src[i],
+                        onChange: (value) => setter(value, i),
+                    }, opt);
+                    next[i] = map(derivation, i);
                 }
                 return next;
             }
@@ -524,11 +521,11 @@ function mapArray(source, map, opt) {
  * }
  * ```
  */
-function mediaQuery(query, debugName) {
+function mediaQuery(query, debugName = 'mediaQuery') {
     if (isPlatformServer(inject(PLATFORM_ID)))
         return computed(() => false, { debugName });
     const mediaQueryList = window.matchMedia(query);
-    const state = signal(mediaQueryList.matches, ...(ngDevMode ? [{ debugName: "state", debugName }] : [{ debugName }]));
+    const state = signal(mediaQueryList.matches, { debugName: debugName });
     const handleChange = (event) => {
         state.set(event.matches);
     };
@@ -712,12 +709,12 @@ function mousePosition(opt) {
             x: 0,
             y: 0,
         }), {
-            debugName: opt?.debugName,
+            debugName: opt?.debugName ?? 'mousePosition',
         });
         base.unthrottled = base;
         return base;
     }
-    const { target = window, coordinateSpace = 'client', touch = false, debugName, throttle = 100, } = opt ?? {};
+    const { target = window, coordinateSpace = 'client', touch = false, debugName = 'mousePosition', throttle = 100, } = opt ?? {};
     const eventTarget = target instanceof ElementRef ? target.nativeElement : target;
     if (!eventTarget) {
         if (isDevMode())
@@ -778,7 +775,7 @@ const serverDate = new Date();
  * @param debugName Optional debug name for the signal.
  * @returns A `NetworkStatusSignal` instance.
  */
-function networkStatus(debugName) {
+function networkStatus(debugName = 'networkStatus') {
     if (isPlatformServer(inject(PLATFORM_ID))) {
         const sig = computed(() => true, {
             debugName,
@@ -845,7 +842,7 @@ function networkStatus(debugName) {
  * }
  * ```
  */
-function pageVisibility(debugName) {
+function pageVisibility(debugName = 'pageVisibility') {
     if (isPlatformServer(inject(PLATFORM_ID))) {
         return computed(() => 'visible', { debugName });
     }
@@ -907,12 +904,12 @@ function scrollPosition(opt) {
             x: 0,
             y: 0,
         }), {
-            debugName: opt?.debugName,
+            debugName: opt?.debugName ?? 'scrollPosition',
         });
         base.unthrottled = base;
         return base;
     }
-    const { target = window, throttle = 100, debugName } = opt || {};
+    const { target = window, throttle = 100, debugName = 'scrollPosition', } = opt || {};
     let element;
     let getScrollPosition;
     if (target instanceof Window) {
@@ -998,12 +995,12 @@ function windowSize(opt) {
         const base = computed(() => ({
             width: 1024,
             height: 768,
-        }), { debugName: opt?.debugName });
+        }), { debugName: opt?.debugName ?? 'windowSize' });
         base.unthrottled = base;
         return base;
     }
     const sizeSignal = throttled({ width: window.innerWidth, height: window.innerHeight }, {
-        debugName: opt?.debugName,
+        debugName: opt?.debugName ?? 'windowSize',
         equal: (a, b) => a.width === b.width && a.height === b.height,
         ms: opt?.throttle ?? 100,
     });
@@ -1211,41 +1208,6 @@ function stored(fallback, { key, store: providedStore, serialize = JSON.stringif
     return writable;
 }
 
-/**
- * Creates a Promise that resolves when a signal's value satisfies a given predicate.
- *
- * This is useful for imperatively waiting for a reactive state to change,
- * for example, in tests or to orchestrate complex asynchronous operations.
- *
- * @template T The type of the signal's value.
- * @param sourceSignal The signal to observe.
- * @param predicate A function that takes the signal's value and returns `true` if the condition is met.
- * @param options Optional configuration for timeout and explicit destruction.
- * @returns A Promise that resolves with the signal's value when the predicate is true,
- * or rejects on timeout or context destruction.
- *
- * @example
- * ```ts
- * const count = signal(0);
- *
- * async function waitForCount() {
- * console.log('Waiting for count to be >= 3...');
- * try {
- * const finalCount = await until(count, c => c >= 3, { timeout: 5000 });
- * console.log(`Count reached: ${finalCount}`);
- * } catch (e: any) { // Ensure 'e' is typed if you access properties like e.message
- * console.error(e.message); // e.g., "until: Timeout after 5000ms."
- * }
- * }
- *
- * // Simulate updates
- * setTimeout(() => count.set(1), 500);
- * setTimeout(() => count.set(2), 1000);
- * setTimeout(() => count.set(3), 1500);
- *
- * waitForCount();
- * ```
- */
 function until(sourceSignal, predicate, options = {}) {
     const injector = options.injector ?? inject(Injector);
     return new Promise((resolve, reject) => {