@mmstack/primitives 21.0.7 → 21.0.9

package/package.json

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

package/types/mmstack-primitives.d.ts

@@ -1,4 +1,4 @@
-import { CreateSignalOptions, DestroyRef, WritableSignal, Signal, EffectCleanupRegisterFn, CreateEffectOptions, Injector, EffectRef, ElementRef, ValueEqualityFn } from '@angular/core';
+import { CreateSignalOptions, DestroyRef, WritableSignal, Signal, Injector, EffectRef, EffectCleanupRegisterFn, CreateEffectOptions, ElementRef, ValueEqualityFn } from '@angular/core';
 
 /**
  * Options for creating a debounced writable signal.
@@ -378,6 +378,108 @@ declare function toFakeSignalDerivation<T, U>(initial: WritableSignal<U>): Deriv
  */
 declare function isDerivation<T, U>(sig: WritableSignal<U>): sig is DerivedSignal<T, U>;
 
+type Frame = {
+    injector: Injector;
+    parent: Frame | null;
+    children: Set<EffectRef>;
+};
+
+/**
+ * Creates an effect that can be nested, similar to SolidJS's `createEffect`.
+ *
+ * This primitive enables true hierarchical reactivity. A `nestedEffect` created
+ * within another `nestedEffect` is automatically destroyed and recreated when
+ * the parent re-runs.
+ *
+ * It automatically handles injector propagation and lifetime management, allowing
+ * you to create fine-grained, conditional side-effects that only track
+ * dependencies when they are "live".
+ *
+ * @param effectFn The side-effect function, which receives a cleanup register function.
+ * @param options (Optional) Angular's `CreateEffectOptions`.
+ * @returns An `EffectRef` for the created effect.
+ *
+ * @example
+ * ```ts
+ * // Assume `coldGuard` changes rarely, but `hotSignal` changes often.
+ * const coldGuard = signal(false);
+ * const hotSignal = signal(0);
+ *
+ * nestedEffect(() => {
+ * // This outer effect only tracks `coldGuard`.
+ * if (coldGuard()) {
+ *
+ * // This inner effect is CREATED when coldGuard is true
+ * // and DESTROYED when it becomes false.
+ * nestedEffect(() => {
+ * // It only tracks `hotSignal` while it exists.
+ * console.log('Hot signal is:', hotSignal());
+ * });
+ * }
+ * // If `coldGuard` is false, this outer effect does not track `hotSignal`.
+ * });
+ * ```
+ * @example
+ * ```ts
+ * const users = signal([
+ *   { id: 1, name: 'Alice' },
+ *   { id: 2, name: 'Bob' }
+ * ]);
+ *
+ * // The fine-grained mapped list
+ * const mappedUsers = mapArray(
+ *   users,
+ *   (userSignal, index) => {
+ *     // 1. Create a fine-grained SIDE EFFECT for *this item*
+ *     // This effect's lifetime is now tied to this specific item. created once on init of this index.
+ *     const effectRef = nestedEffect(() => {
+ *       // This only runs if *this* userSignal changes,
+ *       // not if the whole list changes.
+ *       console.log(`User ${index} updated:`, userSignal().name);
+ *     });
+ *
+ *     // 2. Return the data AND the cleanup logic
+ *     return {
+ *       // The mapped data
+ *       label: computed(() => `User: ${userSignal().name}`),
+ *
+ *       // The cleanup function
+ *       destroyEffect: () => effectRef.destroy()
+ *     };
+ *   },
+ *   {
+ *     // 3. Tell mapArray HOW to clean up when an item is removed, this needs to be manual as it's not a nestedEffect itself
+ *     onDestroy: (mappedItem) => {
+ *       mappedItem.destroyEffect();
+ *     }
+ *   }
+ * );
+ * ```
+ */
+declare function nestedEffect(effectFn: (registerCleanup: EffectCleanupRegisterFn) => void, options?: CreateEffectOptions & {
+    bindToFrame?: (parent: Frame | null) => Frame | null;
+}): {
+    destroy: () => void;
+};
+
+/**
+ * A synchronous version of Angular's effect, optimized for DOM-heavy renderers.
+ * Runs immediately on creation and on dependency changes, bypassing the microtask queue.
+ * * @example
+ * renderEffect((onCleanup) => {
+ * const el = document.createElement('div');
+ * el.textContent = count();
+ * container.appendChild(el);
+ * onCleanup(() => el.remove());
+ * });
+ */
+declare function renderEffect(effectFn: (onCleanup: (fn: () => void) => void) => void, options?: {
+    injector?: Injector;
+}): {
+    run: (isFromBridge?: boolean) => void;
+    destroy: () => void;
+};
+
 /**
  * Reactively maps items from a source array to a new array, creating stable signals for each item.
  *
@@ -472,89 +574,6 @@ declare function mapObject<T extends Record<string, any>, U>(source: (() => T) |
     onDestroy?: (value: U) => void;
 }): Signal<MappedObject<T, U>>;
 
-type Frame = {
-    injector: Injector;
-    parent: Frame | null;
-    children: Set<EffectRef>;
-};
-/**
- * Creates an effect that can be nested, similar to SolidJS's `createEffect`.
- *
- * This primitive enables true hierarchical reactivity. A `nestedEffect` created
- * within another `nestedEffect` is automatically destroyed and recreated when
- * the parent re-runs.
- *
- * It automatically handles injector propagation and lifetime management, allowing
- * you to create fine-grained, conditional side-effects that only track
- * dependencies when they are "live".
- *
- * @param effectFn The side-effect function, which receives a cleanup register function.
- * @param options (Optional) Angular's `CreateEffectOptions`.
- * @returns An `EffectRef` for the created effect.
- *
- * @example
- * ```ts
- * // Assume `coldGuard` changes rarely, but `hotSignal` changes often.
- * const coldGuard = signal(false);
- * const hotSignal = signal(0);
- *
- * nestedEffect(() => {
- * // This outer effect only tracks `coldGuard`.
- * if (coldGuard()) {
- *
- * // This inner effect is CREATED when coldGuard is true
- * // and DESTROYED when it becomes false.
- * nestedEffect(() => {
- * // It only tracks `hotSignal` while it exists.
- * console.log('Hot signal is:', hotSignal());
- * });
- * }
- * // If `coldGuard` is false, this outer effect does not track `hotSignal`.
- * });
- * ```
- * @example
- * ```ts
- * const users = signal([
- *   { id: 1, name: 'Alice' },
- *   { id: 2, name: 'Bob' }
- * ]);
- *
- * // The fine-grained mapped list
- * const mappedUsers = mapArray(
- *   users,
- *   (userSignal, index) => {
- *     // 1. Create a fine-grained SIDE EFFECT for *this item*
- *     // This effect's lifetime is now tied to this specific item. created once on init of this index.
- *     const effectRef = nestedEffect(() => {
- *       // This only runs if *this* userSignal changes,
- *       // not if the whole list changes.
- *       console.log(`User ${index} updated:`, userSignal().name);
- *     });
- *
- *     // 2. Return the data AND the cleanup logic
- *     return {
- *       // The mapped data
- *       label: computed(() => `User: ${userSignal().name}`),
- *
- *       // The cleanup function
- *       destroyEffect: () => effectRef.destroy()
- *     };
- *   },
- *   {
- *     // 3. Tell mapArray HOW to clean up when an item is removed, this needs to be manual as it's not a nestedEffect itself
- *     onDestroy: (mappedItem) => {
- *       mappedItem.destroyEffect();
- *     }
- *   }
- * );
- * ```
- */
-declare function nestedEffect(effectFn: (registerCleanup: EffectCleanupRegisterFn) => void, options?: CreateEffectOptions & {
-    bindToFrame?: (parent: Frame | null) => Frame | null;
-}): {
-    destroy: () => void;
-};
-
 /**
  * A pure, synchronous transform from I -> O.
  * Prefer transforms without side effects to keep derivations predictable.
@@ -1303,10 +1322,14 @@ type AnyRecord = Record<Key, any>;
 type SignalStore<T> = Signal<T> & (NonNullable<T> extends BaseType ? unknown : Readonly<{
     [K in keyof Required<T>]: SignalStore<NonNullable<T>[K]>;
 }>);
-type WritableSignalStore<T> = WritableSignal<T> & (NonNullable<T> extends BaseType ? unknown : Readonly<{
+type WritableSignalStore<T> = WritableSignal<T> & {
+    readonly asReadonlyStore: () => SignalStore<T>;
+} & (NonNullable<T> extends BaseType ? unknown : Readonly<{
     [K in keyof Required<T>]: WritableSignalStore<NonNullable<T>[K]>;
 }>);
-type MutableSignalStore<T> = MutableSignal<T> & (NonNullable<T> extends BaseType ? unknown : Readonly<{
+type MutableSignalStore<T> = MutableSignal<T> & {
+    readonly asReadonlyStore: () => SignalStore<T>;
+} & (NonNullable<T> extends BaseType ? unknown : Readonly<{
     [K in keyof Required<T>]: MutableSignalStore<NonNullable<T>[K]>;
 }>);
 declare function toStore<T extends AnyRecord>(source: MutableSignal<T>, injector?: Injector): MutableSignalStore<T>;
@@ -1752,5 +1775,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 { 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, renderEffect, 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 };