@mmstack/primitives 19.3.2 → 19.3.4

package/index.d.ts

@@ -5,6 +5,8 @@ export { nestedEffect } from './lib/effect';
 export * from './lib/mappers';
 export * from './lib/mutable';
 export * from './lib/pipeable/public_api';
+export * from './lib/pooled';
+export * from './lib/provided-pools';
 export * from './lib/sensors';
 export * from './lib/store';
 export * from './lib/stored';

package/lib/pooled.d.ts

@@ -0,0 +1,59 @@
+import { type CreateSignalOptions, type Signal } from '@angular/core';
+/**
+ * Derives a value (`U`) from a freshly-reset buffer (`T`). Mutate the buffer
+ * and either return it directly or derive a different value from it. Naming
+ * matches Angular's `linkedSignal` `computation` convention.
+ */
+export type Computation<T, U> = (buffer: T) => U;
+/**
+ * Options for {@link pooled}.
+ */
+export type CreatePooledOptions<T, U = T> = {
+    /** Factory for a buffer slot. Called at most twice in total per pool. */
+    create: () => T;
+    /**
+     * Restores a dirty buffer in-place, or returns a replacement instance. Not
+     * called on freshly-created buffers — only on reused ones.
+     */
+    reset: (dirty: T) => void | T;
+    /** Writes into the buffer and returns the derived value. */
+    computation: Computation<T, U>;
+    /**
+     * Pre-allocate both buffer slots at construction. Use when `create()` is
+     * expensive and you'd rather pay the cost up front than on the first reads.
+     * @default false
+     */
+    eager?: boolean;
+} & CreateSignalOptions<U>;
+/**
+ * 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;
+ *   },
+ * });
+ * ```
+ */
+export declare function pooled<T, U = T>({ create, reset, computation, ...opt }: CreatePooledOptions<T, U>): Signal<U>;

package/lib/provided-pools.d.ts

@@ -0,0 +1,64 @@
+import type { CreateSignalOptions, Signal } from '@angular/core';
+import { type Computation, type CreatePooledOptions } from './pooled';
+/**
+ * Options for the preset pool helpers. Same shape as
+ * {@link CreatePooledOptions}, with `create` and `reset` made optional — each
+ * helper supplies its own defaults.
+ */
+export type CreateProvidedPooledOptions<T, U = T> = Omit<CreatePooledOptions<T, U>, 'create' | 'reset'> & Partial<Pick<CreatePooledOptions<T, U>, 'create' | 'reset'>>;
+/**
+ * Array-buffer preset for {@link pooled}. Recycles a single array per slot;
+ * cleared via `arr.length = 0` between reads.
+ *
+ * Two overloads: a {@link Computation} shorthand (most common) or the full
+ * options object when you need `eager` or custom `create`/`reset`.
+ *
+ * Generic inference defaults `T` to `unknown[]` — annotate the callback or
+ * pass the type argument for tighter element types.
+ *
+ * @see {@link pooled} for the retention contract.
+ *
+ * @example
+ * ```ts
+ * const activeIds = pooledArray<number[]>((buf) => {
+ *   for (const item of items()) if (item.active) buf.push(item.id);
+ *   return buf;
+ * });
+ * ```
+ */
+export declare function pooledArray<T extends unknown[], U = T>(computation: Computation<T, U>, opt?: CreateSignalOptions<U>): Signal<U>;
+export declare function pooledArray<T extends unknown[], U = T>(opt: CreateProvidedPooledOptions<T, U>): Signal<U>;
+/**
+ * Set-buffer preset for {@link pooled}. Recycles a single `Set` per slot;
+ * cleared via `.clear()` between reads. Overload shape mirrors
+ * {@link pooledArray}.
+ *
+ * @see {@link pooled} for the retention contract.
+ *
+ * @example
+ * ```ts
+ * const distinctRoles = pooledSet<Set<string>>((buf) => {
+ *   for (const u of users()) buf.add(u.role);
+ *   return buf;
+ * });
+ * ```
+ */
+export declare function pooledSet<T extends Set<unknown>, U = T>(computation: Computation<T, U>, opt?: CreateSignalOptions<U>): Signal<U>;
+export declare function pooledSet<T extends Set<unknown>, U = T>(opt: CreateProvidedPooledOptions<T, U>): Signal<U>;
+/**
+ * Map-buffer preset for {@link pooled}. Recycles a single `Map` per slot;
+ * cleared via `.clear()` between reads. Overload shape mirrors
+ * {@link pooledArray}.
+ *
+ * @see {@link pooled} for the retention contract.
+ *
+ * @example
+ * ```ts
+ * const byId = pooledMap<Map<number, User>>((buf) => {
+ *   for (const u of users()) buf.set(u.id, u);
+ *   return buf;
+ * });
+ * ```
+ */
+export declare function pooledMap<T extends Map<unknown, unknown>, U = T>(computation: Computation<T, U>, opt?: CreateSignalOptions<U>): Signal<U>;
+export declare function pooledMap<T extends Map<unknown, unknown>, U = T>(opt: CreateProvidedPooledOptions<T, U>): Signal<U>;

package/lib/stored.d.ts

@@ -120,7 +120,6 @@ export type StoredSignal<T> = WritableSignal<T> & {
  *
  * @Component({
  * selector: 'app-settings',
- * standalone: true,
  * template: `
  * Theme:
  * <select [ngModel]="theme()" (ngModelChange)="theme.set($event)">

package/package.json

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