@mmstack/primitives 20.0.2 → 20.0.4

package/index.d.ts

@@ -420,65 +420,51 @@ type ElementVisibilitySignal = Signal<IntersectionObserverEntry | undefined> & {
 declare function elementVisibility(target?: ElementRef<Element> | Element | Signal<ElementRef<Element> | Element | null>, opt?: ElementVisibilityOptions): ElementVisibilitySignal;
 
 /**
- * Reactively maps items from a source array (or signal of an array) using a provided mapping function.
+ * Reactively maps items from a source array to a new array, creating stable signals for each item.
  *
- * This function serves a similar purpose to SolidJS's `mapArray` by providing stability
- * for mapped items. It receives a source function returning an array (or a Signal<T[]>)
- * and a mapping function.
+ * This function is highly optimized for performance, similar to SolidJS's `mapArray`.
+ * For each item in the source array, it creates a stable signal that is passed to the mapping function.
+ * This ensures that downstream consumers only re-evaluate for items that have actually changed,
+ * or when items are added or removed from the list.
  *
- * For each item in the source array, it creates a stable `computed` signal representing
- * that item's value at its current index. This stable signal (`Signal<T>`) is passed
- * to the mapping function. This ensures that downstream computations or components
- * depending on the mapped result only re-render or re-calculate for the specific items
- * that have changed, or when items are added/removed, rather than re-evaluating everything
- * when the source array reference changes but items remain the same.
- *
- * It efficiently handles changes in the source array's length by reusing existing mapped
- * results when possible, slicing when the array shrinks, and appending new mapped items
- * when it grows.
+ * The type of signal passed to the `map` function depends on the source:
+ * - **Readonly `Signal`**: `map` receives a readonly `Signal<T>`.
+ * - **`WritableSignal`**: `map` receives a `WritableSignal<T>`, allowing two-way binding.
+ * - **`MutableSignal`**: `map` receives a `MutableSignal<T>`, allowing in-place mutation for performance.
  *
  * @template T The type of items in the source array.
  * @template U The type of items in the resulting mapped array.
  *
- * @param source A function returning the source array `T[]`, or a `Signal<T[]>` itself.
- * The `mapArray` function will reactively update based on changes to this source.
- * @param map The mapping function. It is called for each item in the source array.
- * It receives:
- * - `value`: A stable `Signal<T>` representing the item at the current index.
- * Use this signal within your mapping logic if you need reactivity
- * tied to the specific item's value changes.
- * - `index`: The number index of the item in the array.
- * It should return the mapped value `U`.
- * @param [opt] Optional `CreateSignalOptions<T>`. These options are passed directly
- * to the `computed` signal created for each individual item (`Signal<T>`).
- * This allows specifying options like a custom `equal` function for item comparison.
- *
- * @returns A `Signal<U[]>` containing the mapped array. This signal updates whenever
- * the source array changes (either length or the values of its items).
+ * @param source A `Signal<T[]>` or a function returning `T[]`.
+ * @param map The mapping function. It receives a stable signal for the item and its index.
+ * @param options Optional configuration, including `CreateSignalOptions` for the item signals
+ * (e.g., a custom `equal` function) and an `onDestroy` callback for cleanup.
+ * @returns A `Signal<U[]>` containing the mapped array.
  *
  * @example
- * ```ts
+ * // Writable example
  * const sourceItems = signal([
  * { id: 1, name: 'Apple' },
  * { id: 2, name: 'Banana' }
  * ]);
  *
- * const mappedItems = mapArray(
- * sourceItems,
- * (itemSignal, index) => {
- * // itemSignal is stable for a given item based on its index.
- * // We create a computed here to react to changes in the item's name.
- *  return computed(() => `${index}: ${itemSignal().name.toUpperCase()}`);
- * },
- * // Example optional options (e.g., custom equality for item signals)
- * { equal: (a, b) => a.id === b.id && a.name === b.name }
- * );
- * ```
- * @remarks
- * This function achieves its high performance by leveraging the new `linkedSignal`
- * API from Angular, which allows for efficient memoization and reuse of array items.
+ * // The `itemSignal` is writable because `sourceItems` is a WritableSignal.
+ * const mappedItems = mapArray(sourceItems, (itemSignal, index) => ({
+ * label: computed(() => `${index}: ${itemSignal().name.toUpperCase()}`),
+ * setName: (newName: string) => itemSignal.update(item => ({ ...item, name: newName }))
+ * }));
+ *
+ * // This will update the original source signal.
+ * mappedItems()[0].setName('Avocado');
+ * // sourceItems() is now: [{ id: 1, name: 'Avocado' }, { id: 2, name: 'Banana' }]
  */
-declare function mapArray<T, U>(source: () => T[], map: (value: Signal<T>, index: number) => U, opt?: CreateSignalOptions<T> & {
+declare function mapArray<T, U>(source: MutableSignal<T[]>, map: (value: MutableSignal<T>, index: number) => U, options?: CreateSignalOptions<T> & {
+    onDestroy?: (value: U) => void;
+}): Signal<U[]>;
+declare function mapArray<T, U>(source: WritableSignal<T[]>, map: (value: WritableSignal<T>, index: number) => U, options?: CreateSignalOptions<T> & {
+    onDestroy?: (value: U) => void;
+}): Signal<U[]>;
+declare function mapArray<T, U>(source: Signal<T[]> | (() => T[]), map: (value: Signal<T>, index: number) => U, options?: CreateSignalOptions<T> & {
     onDestroy?: (value: U) => void;
 }): Signal<U[]>;
 
@@ -1196,6 +1182,33 @@ type UntilOptions = {
     destroyRef?: DestroyRef;
     injector?: Injector;
 };
+/**
+ * Creates a Promise that resolves when a signal's value satisfies a type predicate.
+ *
+ * This overload is used when the predicate function is a type guard (e.g., `(v): v is MyType`).
+ * The returned promise will resolve with the narrowed type.
+ *
+ * @template T The base type of the signal's value.
+ * @template U The narrowed type asserted by the predicate.
+ * @param sourceSignal The signal to observe.
+ * @param predicate A type guard function that returns `true` if the value is of type `U`.
+ * @param options Optional configuration for timeout and explicit destruction.
+ * @returns A Promise that resolves with the signal's value, narrowed to type `U`.
+ *
+ * @example
+ * ```ts
+ * const event = signal<Event | null>(null);
+ *
+ * // The returned promise is `Promise<MouseEvent>`
+ * const mouseEventPromise = until(event, (e): e is MouseEvent => e instanceof MouseEvent);
+ *
+ * async function logMouseEvent() {
+ * const me = await mouseEventPromise;
+ * console.log(me.clientX); // `me` is correctly typed as MouseEvent
+ * }
+ * ```
+ */
+declare function until<T, U extends T>(sourceSignal: Signal<T>, predicate: (value: T) => value is U, options?: UntilOptions): Promise<U>;
 /**
  * Creates a Promise that resolves when a signal's value satisfies a given predicate.
  *
@@ -1208,28 +1221,6 @@ type UntilOptions = {
  * @param options Optional configuration for timeout and explicit destruction.
  * @returns A Promise that resolves with the signal's value when the predicate is true,
  * or rejects on timeout or context destruction.
- *
- * @example
- * ```ts
- * const count = signal(0);
- *
- * async function waitForCount() {
- * console.log('Waiting for count to be >= 3...');
- * try {
- * const finalCount = await until(count, c => c >= 3, { timeout: 5000 });
- * console.log(`Count reached: ${finalCount}`);
- * } catch (e: any) { // Ensure 'e' is typed if you access properties like e.message
- * console.error(e.message); // e.g., "until: Timeout after 5000ms."
- * }
- * }
- *
- * // Simulate updates
- * setTimeout(() => count.set(1), 500);
- * setTimeout(() => count.set(2), 1000);
- * setTimeout(() => count.set(3), 1500);
- *
- * waitForCount();
- * ```
  */
 declare function until<T>(sourceSignal: Signal<T>, predicate: (value: T) => boolean, options?: UntilOptions): Promise<T>;
 

package/package.json

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