@mmstack/primitives 20.5.2 → 20.5.4

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`).
@@ -59,6 +60,7 @@ import { FormsModule } from '@angular/forms';
 })
 export class SearchComponent {
   searchTerm = debounced('', { ms: 300 }); // Debounce for 300ms
+  example2 = debounce(signal(''), { ms: 300 }); // pattern for adding debounce to an existing signal
 
   constructor() {
     effect(() => {
@@ -93,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>
@@ -195,7 +196,6 @@ import { stored } from '@mmstack/primitives';
 
 @Component({
   selector: 'app-theme-selector',
-  standalone: true,
   // imports: [FormsModule], // Import if using ngModel
   template: `
     Theme:
@@ -273,7 +273,6 @@ import { JsonPipe } from '@angular/common';
 
 @Component({
   selector: 'app-store-demo',
-  standalone: true,
   imports: [FormsModule, JsonPipe],
   template: `
     <h3>User Profile</h3>
@@ -657,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.
@@ -680,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>
@@ -713,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>
@@ -780,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>
@@ -818,7 +884,6 @@ import { DatePipe } from '@angular/common';
 
 @Component({
   selector: 'app-network-info',
-  standalone: true,
   imports: [DatePipe],
   template: `
     @if (netStatus()) {
@@ -849,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 {
@@ -876,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>
@@ -910,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;">
@@ -944,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>
@@ -1006,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

@@ -138,6 +138,9 @@ function nestedEffect(effectFn, options) {
             manualCleanup: options?.manualCleanup ?? !!parent,
         });
     });
+    let unregisterCleanup;
+    if (!parent && !options?.manualCleanup)
+        unregisterCleanup = injector.get(DestroyRef).onDestroy(() => ref.destroy());
     const ref = {
         destroy: () => {
             if (isDestroyed)
@@ -145,10 +148,10 @@ function nestedEffect(effectFn, options) {
             isDestroyed = true;
             parent?.children.delete(ref);
             srcRef.destroy();
+            unregisterCleanup?.();
         },
     };
     parent?.children.add(ref);
-    injector.get(DestroyRef).onDestroy(() => ref.destroy());
     return ref;
 }
 
@@ -841,6 +844,102 @@ 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;
+    let otherFresh = opt.eager;
+    let currentFresh = opt.eager;
+    return computed(() => {
+        let next;
+        let nextFresh;
+        if (other !== undefined) {
+            next = other;
+            nextFresh = !!otherFresh;
+        }
+        else {
+            next = untracked(() => create());
+            nextFresh = true;
+        }
+        if (current !== undefined) {
+            other = current;
+            otherFresh = currentFresh;
+        }
+        current = next;
+        // the buffer is about to be mutated by `computation`, so it's no longer fresh
+        currentFresh = false;
+        const clean = nextFresh ? next : (untracked(() => reset(next)) ?? next);
+        return computation(clean);
+    }, 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';
 }
@@ -1940,7 +2039,6 @@ const noopStore = {
  *
  * @Component({
  * selector: 'app-settings',
- * standalone: true,
  * template: `
  * Theme:
  * <select [ngModel]="theme()" (ngModelChange)="theme.set($event)">
@@ -2378,5 +2476,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