@mmstack/primitives 21.0.12 → 21.0.14

package/package.json

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

package/types/mmstack-primitives.d.ts

@@ -1,4 +1,40 @@
-import { CreateSignalOptions, DestroyRef, WritableSignal, Signal, Injector, EffectRef, EffectCleanupRegisterFn, CreateEffectOptions, ElementRef, ValueEqualityFn } from '@angular/core';
+import { ValueEqualityFn, Injector, Signal, CreateSignalOptions, DestroyRef, WritableSignal, EffectRef, EffectCleanupRegisterFn, CreateEffectOptions, ElementRef } from '@angular/core';
+
+type CreateChunkedOptions<T> = {
+    /**
+     * The number of items to process in each chunk.
+     * @default 50
+     */
+    chunkSize?: number;
+    /**
+     * The delay between processing each chunk. Can be a number (milliseconds) or 'frame' to use `requestAnimationFrame`.
+     * @default 'frame'
+     */
+    delay?: number | 'frame' | 'microtask';
+    /**
+     * A custom equality function to determine if the processed chunk has changed. This can help prevent unnecessary updates if the chunk content is the same as the previous one.
+     */
+    equal?: ValueEqualityFn<T[]>;
+    /**
+     * An optional `Injector` to use for the internal effect. This allows the effect to have access to dependency injection if needed.
+     */
+    injector?: Injector;
+};
+/**
+ * Creates a new `Signal` that processes an array of items in time-sliced chunks. This is useful for handling large lists without blocking the main thread.
+ *
+ * The returned signal will initially contain the first `chunkSize` items from the source array. It will then schedule updates to include additional chunks of items based on the specified `duration`.
+ *
+ * @template T The type of items in the array.
+ * @param source A `Signal` or a function that returns an array of items to be processed in chunks.
+ * @param options Configuration options for chunk size, delay duration, equality function, and injector.
+ * @returns A `Signal` that emits the current chunk of items being processed.
+ *
+ * @example
+ * const largeList = signal(Array.from({ length: 1000 }, (_, i) => i));
+ * const chunkedList = chunked(largeList, { chunkSize: 100, duration: 100 });
+ */
+declare function chunked<T>(source: Signal<T[]> | (() => T[]), options?: CreateChunkedOptions<T>): Signal<T[]>;
 
 /**
  * Options for creating a debounced writable signal.
@@ -1312,6 +1348,10 @@ type MutableSignalStore<T> = MutableSignal<T> & {
 } & (NonNullable<T> extends BaseType ? unknown : Readonly<{
     [K in keyof Required<T>]: MutableSignalStore<NonNullable<T>[K]>;
 }>);
+/**
+ * Validates whether a value is a Signal Store.
+ */
+declare function isStore<T>(value: unknown): value is SignalStore<T>;
 declare function toStore<T extends AnyRecord>(source: MutableSignal<T>, injector?: Injector): MutableSignalStore<T>;
 declare function toStore<T extends AnyRecord>(source: WritableSignal<T>, injector?: Injector): WritableSignalStore<T>;
 declare function toStore<T extends AnyRecord>(source: Signal<T>, injector?: Injector): SignalStore<T>;
@@ -1602,6 +1642,11 @@ declare function throttle<T>(source: WritableSignal<T>, opt?: CreateThrottledOpt
  * writableSignal.set(5); // sets value of originalValue.a to 5 & triggers all signals
  */
 declare function toWritable<T>(source: Signal<T>, set: (value: T) => void, update?: (updater: (value: T) => T) => void, opt?: CreateSignalOptions<T> & {
+    /**
+     * If `true` (the default), the returned signal will be a computed signal that depends on the source signal.
+     * If `false`, the returned signal will be a direct wrapper around the source signal without creating a new computed signal.
+     * @default true
+     */
     pure?: boolean;
 }): WritableSignal<T>;
 
@@ -1755,5 +1800,5 @@ type CreateHistoryOptions<T> = Omit<CreateSignalOptions<T[]>, 'equal'> & {
  */
 declare function withHistory<T>(source: WritableSignal<T>, opt?: CreateHistoryOptions<T>): SignalWithHistory<T>;
 
-export { combineWith, debounce, debounced, derived, distinct, elementSize, elementVisibility, filter, indexArray, isDerivation, isMutable, 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 { 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, 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 };