@mmstack/primitives 21.0.20 → 21.0.22

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mmstack/primitives",
-  "version": "21.0.20",
+  "version": "21.0.22",
   "keywords": [
     "angular",
     "signals",
@@ -31,6 +31,7 @@
       "default": "./fesm2022/mmstack-primitives.mjs"
     }
   },
+  "type": "module",
   "dependencies": {
     "tslib": "^2.3.0"
   }

package/types/mmstack-primitives.d.ts

@@ -685,6 +685,128 @@ declare function pipeable<TSig extends Signal<any>>(signal: TSig): PipeableSigna
  */
 declare function piped<T>(initial: T, opt?: CreateSignalOptions<T>): PipeableSignal<T, WritableSignal<T>>;
 
+/**
+ * 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.
+ */
+type Computation<T, U> = (buffer: T) => U;
+/**
+ * Options for {@link pooled}.
+ */
+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;
+ *   },
+ * });
+ * ```
+ */
+declare function pooled<T, U = T>({ create, reset, computation, ...opt }: CreatePooledOptions<T, U>): Signal<U>;
+
+/**
+ * Options for the preset pool helpers. Same shape as
+ * {@link CreatePooledOptions}, with `create` and `reset` made optional — each
+ * helper supplies its own defaults.
+ */
+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;
+ * });
+ * ```
+ */
+declare function pooledArray<T extends unknown[], U = T>(computation: Computation<T, U>, opt?: CreateSignalOptions<U>): Signal<U>;
+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;
+ * });
+ * ```
+ */
+declare function pooledSet<T extends Set<unknown>, U = T>(computation: Computation<T, U>, opt?: CreateSignalOptions<U>): Signal<U>;
+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;
+ * });
+ * ```
+ */
+declare function pooledMap<T extends Map<unknown, unknown>, U = T>(computation: Computation<T, U>, opt?: CreateSignalOptions<U>): Signal<U>;
+declare function pooledMap<T extends Map<unknown, unknown>, U = T>(opt: CreateProvidedPooledOptions<T, U>): Signal<U>;
+
 /**
  * Represents the size of an element.
  */
@@ -1507,7 +1629,6 @@ type StoredSignal<T> = WritableSignal<T> & {
  *
  * @Component({
  * selector: 'app-settings',
- * standalone: true,
  * template: `
  * Theme:
  * <select [ngModel]="theme()" (ngModelChange)="theme.set($event)">
@@ -1828,5 +1949,5 @@ type CreateHistoryOptions<T> = Omit<CreateSignalOptions<T[]>, 'equal'> & {
  */
 declare function withHistory<T>(source: WritableSignal<T>, opt?: CreateHistoryOptions<T>): SignalWithHistory<T>;
 
-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 type { CreateChunkedOptions, 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 };
+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 };
+export type { Computation, CreateChunkedOptions, CreateDebouncedOptions, CreateHistoryOptions, CreatePooledOptions, CreateProvidedPooledOptions, 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 };