@mmstack/primitives 21.0.20 → 21.0.22

package/README.md

@@ -29,6 +29,7 @@ This library provides the following primitives:
 - `toWritable` - Converts a read-only signal to writable using custom write logic.
 - `derived` - Creates a signal with two-way binding to a source signal.
 - `chunked` - Creates a signal that time-slices an array into chunked values & emits thats array based on the provided options.
+- `pooled` / `pooledArray` / `pooledMap` / `pooledSet` - Double-buffered object pools for `computed` signals; recycle the output container to remove allocation pressure in high-frequency recomputation.
 - `tabSync` - Low level primitive to "share" the value of a WritableSignal accross tabs via the BroadcastChannel api.
 - `sensor` - A facade function to create various reactive sensor signals (e.g., mouse position, network status, page visibility, dark mode preference)." (This was the suggestion from before; it just reads a little smoother and more accurately reflects what the facade creates directly).
   - `mediaQuery` - A generic primitive that tracks a CSS media query (forms the basis for `prefersDarkMode` and `prefersReducedMotion`).
@@ -94,7 +95,6 @@ import { JsonPipe } from '@angular/common';
 
 @Component({
   selector: 'app-throttle-demo',
-  standalone: true,
   imports: [JsonPipe],
   template: `
     <div (mousemove)="onMouseMove($event)" style="width: 300px; height: 200px; border: 1px solid black; padding: 10px; user-select: none;">Move mouse here to see updates...</div>
@@ -196,7 +196,6 @@ import { stored } from '@mmstack/primitives';
 
 @Component({
   selector: 'app-theme-selector',
-  standalone: true,
   // imports: [FormsModule], // Import if using ngModel
   template: `
     Theme:
@@ -274,7 +273,6 @@ import { JsonPipe } from '@angular/common';
 
 @Component({
   selector: 'app-store-demo',
-  standalone: true,
   imports: [FormsModule, JsonPipe],
   template: `
     <h3>User Profile</h3>
@@ -658,6 +656,75 @@ export class HeavyListComponent {
 }
 ```
 
+### pooled / pooledArray / pooledMap / pooledSet
+
+A double-buffered object pool for `computed` signal outputs. After a brief warm-up the pool reaches steady state with **zero allocations per recomputation** — two buffers are swapped on every read, with `reset` invoked before each `computation`. Each read returns a different identity from the previous read, so default `Object.is` equality still flags changes correctly. Most users will reach for the preset helpers (`pooledArray`, `pooledMap`, `pooledSet`); drop down to `pooled` only when you need a custom buffer type.
+
+> **Retention contract:** the value returned from a pooled signal is only valid until the next read of that signal. The container is reused on the second-next read and will be `reset` first, mutating any reference you still hold. Do not store the result in component state, async closures, or anywhere outside the same reactive tick. Treat it as scratch output consumed synchronously.
+
+Use these when a computed is recomputed at high frequency and produces a large allocation (filter/map outputs over big arrays, lookup indices, RAF-driven computeds). For typical UI computeds over small data, just use `computed` — the docs cost and footgun aren't worth saving an allocation that doesn't show up in a profile.
+
+```typescript
+import { Component, signal } from '@angular/core';
+import { pooledArray, pooledMap, pooledSet } from '@mmstack/primitives';
+
+@Component({
+  selector: 'app-pooled-demo',
+  template: `<p>Active: {{ activeIds().length }} / {{ items().length }}</p>`,
+})
+export class PooledDemoComponent {
+  readonly items = signal(Array.from({ length: 10_000 }, (_, i) => ({ id: i, active: i % 2 === 0 })));
+
+  // Recycles a single number[] across recomputations.
+  readonly activeIds = pooledArray<number[]>((buf) => {
+    for (const item of this.items()) {
+      if (item.active) buf.push(item.id);
+    }
+    return buf;
+  });
+
+  // Recycles a Map for fast id → item lookups.
+  readonly byId = pooledMap<Map<number, { id: number; active: boolean }>>((buf) => {
+    for (const item of this.items()) buf.set(item.id, item);
+    return buf;
+  });
+
+  // Recycles a Set of distinct values.
+  readonly distinctFlags = pooledSet<Set<boolean>>((buf) => {
+    for (const item of this.items()) buf.add(item.active);
+    return buf;
+  });
+}
+```
+
+Need a custom buffer type (typed array, your own struct)? Use `pooled` directly:
+
+```typescript
+import { signal } from '@angular/core';
+import { pooled } from '@mmstack/primitives';
+
+const source = signal<{ active: boolean }[]>([]);
+
+// Pre-allocate both slots at construction (eager) — useful when create() is expensive.
+const counters = pooled<{ total: number; active: number }>({
+  create: () => ({ total: 0, active: 0 }),
+  reset: (c) => {
+    c.total = 0;
+    c.active = 0;
+  },
+  computation: (c) => {
+    for (const item of source()) {
+      c.total++;
+      if (item.active) c.active++;
+    }
+    return c;
+  },
+  eager: true,
+});
+```
+
+Complementary to `linkedSignal` (which carries previous *state* forward, not the *container*) and `chunked` (which time-slices large outputs across frames).
+
 ### tabSync
 
 A low-level primitive that synchronizes a WritableSignal across multiple browser tabs or windows of the same application using the BroadcastChannel API. Used by the cache in @mmstack/resource & the stored signal.
@@ -681,7 +748,7 @@ import { tabSync } from '@mmstack/primitives';
   template: `
     <p>Open this page in two tabs!</p>
 
-    <button (click)="counter.update(n => n + 1)">Count: {{ counter() }}</button>
+    <button (click)="counter.update((n) => n + 1)">Count: {{ counter() }}</button>
 
     <select [ngModel]="theme()" (ngModelChange)="theme.set($event)">
       <option value="light">Light</option>
@@ -714,7 +781,6 @@ import { Component, signal, effect } from '@angular/core';
 
 @Component({
   selector: 'app-history-demo',
-  standalone: true,
   imports: [FormsModule, JsonPipe],
   template: `
     <h4>Simple Text Editor</h4>
@@ -781,7 +847,6 @@ import { JsonPipe } from '@angular/common';
 
 @Component({
   selector: 'app-mouse-tracker',
-  standalone: true,
   imports: [JsonPipe],
   template: `
     <div (mousemove)="onMouseMove($event)" style="width: 300px; height: 200px; border: 1px solid black; padding: 10px; user-select: none;">Move mouse here...</div>
@@ -819,7 +884,6 @@ import { DatePipe } from '@angular/common';
 
 @Component({
   selector: 'app-network-info',
-  standalone: true,
   imports: [DatePipe],
   template: `
     @if (netStatus()) {
@@ -850,7 +914,6 @@ import { sensor } from '@mmstack/primitives'; // Or import { pageVisibility }
 
 @Component({
   selector: 'app-visibility-logger',
-  standalone: true,
   template: `<p>Page is currently: {{ visibility() }}</p>`,
 })
 export class VisibilityLoggerComponent {
@@ -877,7 +940,6 @@ import { sensor } from '@mmstack/primitives'; // Or import { windowSize }
 
 @Component({
   selector: 'app-responsive-display',
-  standalone: true,
   template: `
     <p>Current Window Size: {{ winSize().width }}px x {{ winSize().height }}px</p>
     <p>Unthrottled: W: {{ winSize.unthrottled().width }} H: {{ winSize.unthrottled().height }}</p>
@@ -911,7 +973,6 @@ import { JsonPipe } from '@angular/common';
 
 @Component({
   selector: 'app-scroll-indicator',
-  standalone: true,
   imports: [JsonPipe],
   template: `
     <div style="height: 100px; border-bottom: 2px solid red; position: fixed; top: 0; left: 0; width: 100%; background: white; z-index: 10;">
@@ -945,7 +1006,6 @@ import { mediaQuery, prefersDarkMode, prefersReducedMotion } from '@mmstack/prim
 
 @Component({
   selector: 'app-layout-checker',
-  standalone: true,
   template: `
     @if (isLargeScreen()) {
       <p>Using large screen layout.</p>
@@ -1007,7 +1067,6 @@ import { elementVisibility } from '@mmstack/primitives';
 
 @Component({
   selector: 'app-lazy-load-item',
-  standalone: true,
   template: `
     <div #itemToObserve style="height: 300px; margin-top: 100vh; border: 2px solid green;">
       @if (intersectionEntry.visible()) {

package/fesm2022/mmstack-primitives.mjs

@@ -197,7 +197,7 @@ function chunked(source, options) {
             return () => clearTimeout(num);
         };
     }
-    const internal = linkedSignal({ ...(ngDevMode ? { debugName: "internal" } : {}), source,
+    const internal = linkedSignal({ ...(ngDevMode ? { debugName: "internal" } : /* istanbul ignore next */ {}), source,
         computation: (items) => items.slice(0, chunkSize),
         equal });
     nestedEffect((cleanup) => {
@@ -311,7 +311,7 @@ function debounced(initial, opt) {
  */
 function debounce(source, opt) {
     const ms = opt?.ms ?? 0;
-    const trigger = signal(false, ...(ngDevMode ? [{ debugName: "trigger" }] : []));
+    const trigger = signal(false, ...(ngDevMode ? [{ debugName: "trigger" }] : /* istanbul ignore next */ []));
     let timeout;
     try {
         const destroyRef = opt?.destroyRef ?? inject(DestroyRef, { optional: true });
@@ -540,7 +540,7 @@ function createItemSignal(source, index, setter, opt) {
 }
 function indexArray(source, map, opt = {}) {
     const data = isSignal(source) ? source : computed(source);
-    const len = computed(() => data().length, ...(ngDevMode ? [{ debugName: "len" }] : []));
+    const len = computed(() => data().length, ...(ngDevMode ? [{ debugName: "len" }] : /* istanbul ignore next */ []));
     const setter = createSetter(data);
     const writableData = isWritableSignal(data)
         ? data
@@ -643,7 +643,7 @@ function keyArray(source, mapFn, options = {}) {
                 for (j = 0; j < newLen; j++) {
                     item = newItems[j];
                     items[j] = item;
-                    const indexSignal = signal(j, ...(ngDevMode ? [{ debugName: "indexSignal" }] : []));
+                    const indexSignal = signal(j, ...(ngDevMode ? [{ debugName: "indexSignal" }] : /* istanbul ignore next */ []));
                     newIndexes[j] = indexSignal;
                     newMapped[j] = mapFn(item, indexSignal);
                 }
@@ -693,7 +693,7 @@ function keyArray(source, mapFn, options = {}) {
                         newIndexes[j].set(j);
                     }
                     else {
-                        const indexSignal = signal(j, ...(ngDevMode ? [{ debugName: "indexSignal" }] : []));
+                        const indexSignal = signal(j, ...(ngDevMode ? [{ debugName: "indexSignal" }] : /* istanbul ignore next */ []));
                         newIndexes[j] = indexSignal;
                         newMapped[j] = mapFn(newItems[j], indexSignal);
                     }
@@ -840,6 +840,98 @@ function piped(initial, opt) {
     return pipeable(signal(initial, opt));
 }
 
+/**
+ * A `Signal<U>` backed by a two-slot object pool: `create` is called at most
+ * twice over the pool's lifetime, and the two `T` instances are swapped on
+ * every recomputation with `reset` invoked on the dirty one before
+ * `computation` writes into it. Consecutive reads return different identities,
+ * so the default `Object.is` equality still flags changes.
+ *
+ * **Retention contract:** the returned value is only valid until the next
+ * recomputation of this signal. The container is recycled and `reset`,
+ * mutating any reference you still hold — do not store the result, pass it to
+ * async code, or hand it to consumers that outlive the current reactive tick.
+ *
+ * For collection buffers prefer the presets: {@link pooledArray},
+ * {@link pooledMap}, {@link pooledSet}.
+ *
+ * @see [Angular `linkedSignal`](https://angular.dev/api/core/linkedSignal) — carries previous *state* forward; complementary, not a substitute.
+ *
+ * @example
+ * ```ts
+ * const source = signal<{ active: boolean }[]>([]);
+ *
+ * const counters = pooled<{ total: number; active: number }>({
+ *   create: () => ({ total: 0, active: 0 }),
+ *   reset: (c) => { c.total = 0; c.active = 0; },
+ *   computation: (c) => {
+ *     for (const item of source()) { c.total++; if (item.active) c.active++; }
+ *     return c;
+ *   },
+ * });
+ * ```
+ */
+function pooled({ create, reset, computation, ...opt }) {
+    let other = opt.eager ? create() : undefined;
+    let current = opt.eager ? create() : undefined;
+    // only relevant for eager mode: the pre-allocated `current` is fresh until its first demote
+    let currentFresh = opt.eager;
+    return computed(() => {
+        const next = other ?? untracked(() => create());
+        if (current !== undefined) {
+            if (currentFresh) {
+                // never-mutated buffer leaving the active slot; nothing to clean
+                other = current;
+            }
+            else {
+                // reset on release: clean the dirty buffer as it goes back into the pool
+                // (also threads the swap-return correctly into the pool's spare slot)
+                other = untracked(() => reset(current)) ?? current;
+            }
+        }
+        current = next;
+        currentFresh = false;
+        return computation(next);
+    }, opt);
+}
+
+function toPooledOptions(optOrComputation, create, reset, signalOpt) {
+    const opt = typeof optOrComputation === 'object' ? optOrComputation : signalOpt;
+    const computation = typeof optOrComputation === 'function'
+        ? optOrComputation
+        : optOrComputation.computation;
+    return {
+        create,
+        reset,
+        computation,
+        ...opt,
+    };
+}
+function createEmptyArray() {
+    return [];
+}
+function resetArray(arr) {
+    arr.length = 0;
+}
+function pooledArray(optOrComputation, signalOpt) {
+    return pooled(toPooledOptions(optOrComputation, createEmptyArray, resetArray, signalOpt));
+}
+function createEmptySet() {
+    return new Set();
+}
+function resetClearable(clearable) {
+    clearable.clear();
+}
+function pooledSet(optOrComputation, signalOpt) {
+    return pooled(toPooledOptions(optOrComputation, createEmptySet, resetClearable, signalOpt));
+}
+function createEmptyMap() {
+    return new Map();
+}
+function pooledMap(optOrComputation, signalOpt) {
+    return pooled(toPooledOptions(optOrComputation, createEmptyMap, resetClearable, signalOpt));
+}
+
 function observerSupported$1() {
     return typeof ResizeObserver !== 'undefined';
 }
@@ -999,7 +1091,7 @@ function elementVisibility(target = inject(ElementRef), opt) {
         const base = computed(() => undefined, {
             debugName: opt?.debugName,
         });
-        base.visible = computed(() => false, ...(ngDevMode ? [{ debugName: "visible" }] : []));
+        base.visible = computed(() => false, ...(ngDevMode ? [{ debugName: "visible" }] : /* istanbul ignore next */ []));
         return base;
     }
     const state = signal(undefined, {
@@ -1036,7 +1128,7 @@ function elementVisibility(target = inject(ElementRef), opt) {
         if (!s)
             return false;
         return s.isIntersecting;
-    }, ...(ngDevMode ? [{ debugName: "visible" }] : []));
+    }, ...(ngDevMode ? [{ debugName: "visible" }] : /* istanbul ignore next */ []));
     return base;
 }
 
@@ -1201,7 +1293,7 @@ function throttled(initial, opt) {
  */
 function throttle(source, opt) {
     const ms = opt?.ms ?? 0;
-    const trigger = signal(false, ...(ngDevMode ? [{ debugName: "trigger" }] : []));
+    const trigger = signal(false, ...(ngDevMode ? [{ debugName: "trigger" }] : /* istanbul ignore next */ []));
     let timeout;
     try {
         const destroyRef = opt?.destroyRef ?? inject(DestroyRef, { optional: true });
@@ -1347,11 +1439,11 @@ function networkStatus(debugName = 'networkStatus') {
         const sig = computed(() => true, {
             debugName,
         });
-        sig.since = computed(() => serverDate, ...(ngDevMode ? [{ debugName: "since" }] : []));
+        sig.since = computed(() => serverDate, ...(ngDevMode ? [{ debugName: "since" }] : /* istanbul ignore next */ []));
         return sig;
     }
-    const state = signal(navigator.onLine, { ...(ngDevMode ? { debugName: "state" } : {}), debugName });
-    const since = signal(new Date(), ...(ngDevMode ? [{ debugName: "since" }] : []));
+    const state = signal(navigator.onLine, { ...(ngDevMode ? { debugName: "state" } : /* istanbul ignore next */ {}), debugName });
+    const since = signal(new Date(), ...(ngDevMode ? [{ debugName: "since" }] : /* istanbul ignore next */ []));
     const goOnline = () => {
         state.set(true);
         since.set(new Date());
@@ -1411,7 +1503,7 @@ function pageVisibility(debugName = 'pageVisibility') {
     if (isPlatformServer(inject(PLATFORM_ID))) {
         return computed(() => 'visible', { debugName });
     }
-    const visibility = signal(document.visibilityState, { ...(ngDevMode ? { debugName: "visibility" } : {}), debugName });
+    const visibility = signal(document.visibilityState, { ...(ngDevMode ? { debugName: "visibility" } : /* istanbul ignore next */ {}), debugName });
     const onVisibilityChange = () => visibility.set(document.visibilityState);
     document.addEventListener('visibilitychange', onVisibilityChange);
     inject(DestroyRef).onDestroy(() => document.removeEventListener('visibilitychange', onVisibilityChange));
@@ -1675,7 +1767,7 @@ function toArrayStore(source, injector) {
         if (!Array.isArray(v))
             return 0;
         return v.length;
-    }, ...(ngDevMode ? [{ debugName: "lengthSignal" }] : []));
+    }, ...(ngDevMode ? [{ debugName: "lengthSignal" }] : /* istanbul ignore next */ []));
     return new Proxy(source, {
         has(_, prop) {
             if (prop === 'length')
@@ -1940,7 +2032,6 @@ const noopStore = {
  *
  * @Component({
  * selector: 'app-settings',
- * standalone: true,
  * template: `
  * Theme:
  * <select [ngModel]="theme()" (ngModelChange)="theme.set($event)">
@@ -1998,7 +2089,7 @@ function stored(fallback, { key, store: providedStore, serialize = JSON.stringif
         equal,
     };
     const initialKey = untracked(keySig);
-    const internal = signal(getValue(initialKey), { ...(ngDevMode ? { debugName: "internal" } : {}), ...opt,
+    const internal = signal(getValue(initialKey), { ...(ngDevMode ? { debugName: "internal" } : /* istanbul ignore next */ {}), ...opt,
         equal: (a, b) => {
             if (a === null && b === null)
                 return true;
@@ -2083,10 +2174,10 @@ class MessageBus {
         this.channel.removeEventListener('message', listener);
         this.listeners.delete(id);
     }
-    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.0", ngImport: i0, type: MessageBus, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
-    static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "21.2.0", ngImport: i0, type: MessageBus, providedIn: 'root' });
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.12", ngImport: i0, type: MessageBus, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
+    static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "21.2.12", ngImport: i0, type: MessageBus, providedIn: 'root' });
 }
-i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.0", ngImport: i0, type: MessageBus, decorators: [{
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.12", ngImport: i0, type: MessageBus, decorators: [{
             type: Injectable,
             args: [{
                     providedIn: 'root',
@@ -2163,7 +2254,7 @@ function tabSync(sig, opt) {
             return;
         }
         post(val);
-    }, ...(ngDevMode ? [{ debugName: "effectRef" }] : []));
+    }, ...(ngDevMode ? [{ debugName: "effectRef" }] : /* istanbul ignore next */ []));
     inject(DestroyRef).onDestroy(() => {
         effectRef.destroy();
         unsub();
@@ -2359,9 +2450,9 @@ function withHistory(source, opt) {
         history.set([]);
         redoArray.set([]);
     };
-    internal.canUndo = computed(() => history().length > 0, ...(ngDevMode ? [{ debugName: "canUndo" }] : []));
-    internal.canRedo = computed(() => redoArray().length > 0, ...(ngDevMode ? [{ debugName: "canRedo" }] : []));
-    internal.canClear = computed(() => internal.canUndo() || internal.canRedo(), ...(ngDevMode ? [{ debugName: "canClear" }] : []));
+    internal.canUndo = computed(() => history().length > 0, ...(ngDevMode ? [{ debugName: "canUndo" }] : /* istanbul ignore next */ []));
+    internal.canRedo = computed(() => redoArray().length > 0, ...(ngDevMode ? [{ debugName: "canRedo" }] : /* istanbul ignore next */ []));
+    internal.canClear = computed(() => internal.canUndo() || internal.canRedo(), ...(ngDevMode ? [{ debugName: "canClear" }] : /* istanbul ignore next */ []));
     return internal;
 }
 
@@ -2369,5 +2460,5 @@ function withHistory(source, opt) {
  * Generated bundle index. Do not edit.
  */
 
-export { chunked, combineWith, debounce, debounced, derived, distinct, elementSize, elementVisibility, filter, indexArray, isDerivation, isMutable, isStore, 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 { chunked, combineWith, debounce, debounced, derived, distinct, elementSize, elementVisibility, filter, indexArray, isDerivation, isMutable, isStore, keyArray, map, mapArray, mapObject, mediaQuery, mousePosition, mutable, mutableStore, nestedEffect, networkStatus, pageVisibility, pipeable, piped, pooled, pooledArray, pooledMap, pooledSet, prefersDarkMode, prefersReducedMotion, scrollPosition, select, sensor, sensors, store, stored, tabSync, tap, throttle, throttled, toFakeDerivation, toFakeSignalDerivation, toStore, toWritable, until, windowSize, withHistory };
 //# sourceMappingURL=mmstack-primitives.mjs.map