@ngrx/signals 21.0.0 → 21.1.0

package/fesm2022/ngrx-signals.mjs

@@ -57,10 +57,63 @@ function isIterable(value) {
     return typeof value?.[Symbol.iterator] === 'function';
 }
 
+/**
+ * @description
+ *
+ * Creates a computed signal with deeply nested signals for each property when
+ * the result is an object literal.
+ *
+ * @usageNotes
+ *
+ * ```ts
+ * import { signal } from '@angular/core';
+ * import { deepComputed } from '@ngrx/signals';
+ *
+ * const limit = signal(10);
+ * const offset = signal(0);
+ *
+ * const pagination = deepComputed(() => ({
+ *   currentPage: Math.floor(offset() / limit()) + 1,
+ *   pageSize: limit(),
+ * }));
+ *
+ * console.log(pagination()); // { currentPage: 1, pageSize: 10 }
+ * console.log(pagination.currentPage()); // 1
+ * console.log(pagination.pageSize()); // 10
+ * ```
+ */
 function deepComputed(computation) {
     return toDeepSignal(computed(computation));
 }
 
+/**
+ * @description
+ *
+ * Creates a method for managing side effects with signals.
+ * The method accepts a signal, a computation function, or a static value.
+ *
+ * @usageNotes
+ *
+ * ```ts
+ * import { Component, signal } from '@angular/core';
+ * import { signalMethod } from '@ngrx/signals';
+ *
+ * \@Component(...)
+ * export class Counter {
+ *   readonly count = signal(1);
+ *   readonly logDoubledNumber = signalMethod<number>(
+ *     (num) => console.log(num * 2)
+ *   );
+ *
+ *   constructor() {
+ *     this.logDoubledNumber(10); // logs: 20
+ *
+ *     this.logDoubledNumber(this.count); // logs: 2
+ *     setTimeout(() => this.count.set(2), 1_000); // logs: 4 (after 1s)
+ *   }
+ * }
+ * ```
+ */
 function signalMethod(processingFn, config) {
     if (typeof ngDevMode !== 'undefined' && ngDevMode && !config?.injector) {
         assertInInjectionContext(signalMethod);
@@ -74,7 +127,7 @@ function signalMethod(processingFn, config) {
                 ngDevMode &&
                 config?.injector === undefined &&
                 callerInjector === undefined) {
-                console.warn('@ngrx/signals: The function returned by signalMethod was called', 'outside the injection context with a signal. This may lead to', 'a memory leak. Make sure to call it within the injection context', '(e.g. in a constructor or field initializer) or pass an injector', 'explicitly via the config parameter.\n\nFor more information, see:', 'https://ngrx.io/guide/signals/signal-method#automatic-cleanup');
+                console.warn('@ngrx/signals: Calling signalMethod outside of an injection', 'context with a signal is deprecated. In a future version,', 'this will throw an error. Either call it within an injection', 'context (e.g. in a constructor or field initializer) or pass', 'an injector explicitly via the config parameter.', '\n\nFor more information, see:', 'https://ngrx.io/guide/signals/signal-method#automatic-cleanup');
             }
             const instanceInjector = config?.injector ?? callerInjector ?? sourceInjector;
             const watcher = effect(() => {
@@ -125,6 +178,30 @@ function isWritableStateSource(stateSource) {
         return isWritableSignal(signals[key]);
     });
 }
+/**
+ * @description
+ *
+ * Updates the state of a SignalStore or SignalState.
+ * Accepts a sequence of partial state objects and partial state updaters.
+ *
+ * @usageNotes
+ *
+ * ```ts
+ * import { patchState, signalStore, withMethods, withState } from '@ngrx/signals';
+ *
+ * export const CounterStore = signalStore(
+ *   withState({ count1: 0, count2: 0 }),
+ *   withMethods((store) => ({
+ *     incrementFirst(): void {
+ *       patchState(store, (state) => ({ count1: state.count1 + 1 }));
+ *     },
+ *     resetSecond(): void {
+ *       patchState(store, { count2: 0 });
+ *     },
+ *   }))
+ * );
+ * ```
+ */
 function patchState(stateSource, ...updaters) {
     const currentState = untracked(() => getState(stateSource));
     const newState = updaters.reduce((nextState, updater) => ({
@@ -146,6 +223,36 @@ function patchState(stateSource, ...updaters) {
     }
     notifyWatchers(stateSource);
 }
+/**
+ * @description
+ *
+ * Returns a snapshot of the current state from a SignalStore or SignalState.
+ * When used within a reactive context, state changes are automatically tracked.
+ *
+ * @usageNotes
+ *
+ * ```ts
+ * import { Component, effect, inject } from '@angular/core';
+ * import { getState, signalStore, withState } from '@ngrx/signals';
+ *
+ * export const CounterStore = signalStore(
+ *   withState({ count1: 0, count2: 0 })
+ * );
+ *
+ * \@Component(...)
+ * export class Counter {
+ *   readonly store = inject(CounterStore);
+ *
+ *   constructor() {
+ *     effect(() => {
+ *       const state = getState(this.store);
+ *       // 👇 Logs on state changes.
+ *       console.log(state);
+ *     });
+ *   }
+ * }
+ * ```
+ */
 function getState(stateSource) {
     const signals = stateSource[STATE_SOURCE];
     return Reflect.ownKeys(stateSource[STATE_SOURCE]).reduce((state, key) => {
@@ -156,6 +263,28 @@ function getState(stateSource) {
         };
     }, {});
 }
+/**
+ * @description
+ *
+ * Synchronously tracks state changes of a SignalStore or SignalState.
+ *
+ * @usageNotes
+ *
+ * ```ts
+ * import { Component } from '@angular/core';
+ * import { signalState, watchState } from '@ngrx/signals';
+ *
+ * \@Component(...)
+ * export class Counter {
+ *   readonly state = signalState({ count1: 0, count2: 0 });
+ *
+ *   constructor() {
+ *     // 👇 Synchronously logs every state change without debouncing.
+ *     watchState(this.state, console.log);
+ *   }
+ * }
+ * ```
+ */
 function watchState(stateSource, watcher, config) {
     if (typeof ngDevMode !== 'undefined' && ngDevMode && !config?.injector) {
         assertInInjectionContext(watchState);
@@ -187,6 +316,32 @@ function removeWatcher(stateSource, watcher) {
     STATE_WATCHERS.set(stateSource[STATE_SOURCE], watchers.filter((w) => w !== watcher));
 }
 
+/**
+ * @description
+ *
+ * Creates a state container with deeply nested signals for each property that
+ * is an object literal.
+ *
+ * @usageNotes
+ *
+ * ```ts
+ * import { Component } from '@angular/core';
+ * import { signalState, patchState } from '@ngrx/signals';
+ *
+ * \@Component(...)
+ * export class Counter {
+ *   readonly state = signalState({ count: 0 });
+ *
+ *   logCount(): void {
+ *     console.log(this.state.count());
+ *   }
+ *
+ *   increment(): void {
+ *     patchState(this.state, ({ count }) => ({ count: count + 1 }));
+ *   }
+ * }
+ * ```
+ */
 function signalState(initialState) {
     const stateKeys = Reflect.ownKeys(initialState);
     const stateSource = stateKeys.reduce((signalsDict, key) => ({
@@ -205,6 +360,44 @@ function signalState(initialState) {
     return signalState;
 }
 
+/**
+ * @description
+ *
+ * Creates a store by composing features.
+ * Returns an injectable service that can be provided locally or globally.
+ *
+ * @usageNotes
+ *
+ * ```ts
+ * import { Component, inject } from '@angular/core';
+ * import { patchState, signalStore, withMethods, withState } from '@ngrx/signals';
+ *
+ * export const CounterStore = signalStore(
+ *   withState({ count: 0 }),
+ *   withMethods((store) => ({
+ *     increment(): void {
+ *       patchState(store, ({ count }) => ({ count: count + 1 }));
+ *     },
+ *   }))
+ * );
+ *
+ * \@Component({
+ *   // ...
+ *   providers: [CounterStore],
+ * })
+ * export class Counter {
+ *   readonly store = inject(CounterStore);
+ *
+ *   logCount(): void {
+ *     console.log(this.store.count());
+ *   }
+ *
+ *   increment(): void {
+ *     this.store.increment();
+ *   }
+ * }
+ * ```
+ */
 function signalStore(...args) {
     const signalStoreArgs = [...args];
     const config = typeof signalStoreArgs[0] === 'function'
@@ -251,6 +444,36 @@ function getInitialInnerStore() {
     };
 }
 
+/**
+ * @description
+ *
+ * Combines multiple store features into a single feature.
+ *
+ * @usageNotes
+ *
+ * ```ts
+ * import {
+ *   patchState,
+ *   signalStore,
+ *   signalStoreFeature,
+ *   withMethods,
+ *   withState,
+ * } from '@ngrx/signals';
+ *
+ * export function withCounter() {
+ *   return signalStoreFeature(
+ *     withState({ count: 0 }),
+ *     withMethods((store) => ({
+ *       increment(): void {
+ *         patchState(store, ({ count }) => ({ count: count + 1 }));
+ *       },
+ *     }))
+ *   );
+ * }
+ *
+ * export const CounterStore = signalStore(withCounter());
+ * ```
+ */
 function signalStoreFeature(...args) {
     const features = (typeof args[0] === 'function' ? args : args.slice(1));
     return (inputStore) => features.reduce((store, feature) => feature(store), inputStore);
@@ -271,6 +494,25 @@ function assertUniqueStoreMembers(store, newMemberKeys) {
     }
 }
 
+/**
+ * @description
+ *
+ * Adds custom properties to a SignalStore.
+ *
+ * @usageNotes
+ *
+ * ```ts
+ * import { toObservable } from '@angular/core/rxjs-interop';
+ * import { signalStore, withProps, withState } from '@ngrx/signals';
+ *
+ * export const TodosStore = signalStore(
+ *   withState({ todos: [] as Todo[], isLoading: false }),
+ *   withProps(({ isLoading }) => ({
+ *     isLoading$: toObservable(isLoading),
+ *   }))
+ * );
+ * ```
+ */
 function withProps(propsFactory) {
     return (store) => {
         const props = propsFactory({
@@ -289,6 +531,26 @@ function withProps(propsFactory) {
     };
 }
 
+/**
+ * @description
+ *
+ * Adds computed signals to a SignalStore.
+ * Accepts a factory function that returns a dictionary of computed signals or
+ * computation functions.
+ *
+ * @usageNotes
+ *
+ * ```ts
+ * import { signalStore, withState, withComputed } from '@ngrx/signals';
+ *
+ * export const CounterStore = signalStore(
+ *   withState({ count: 0 }),
+ *   withComputed(({ count }) => ({
+ *     doubleCount: () => count() * 2,
+ *   }))
+ * );
+ * ```
+ */
 function withComputed(computedFactory) {
     return withProps((store) => {
         const computedResult = computedFactory(store);
@@ -307,25 +569,27 @@ function withComputed(computedFactory) {
 
 /**
  * @description
- * Allows passing properties, methods, or signals from a SignalStore
- * to a feature.
+ *
+ * Allows passing state signals, properties, and methods from a SignalStore
+ * instance to a custom feature.
  *
  * @usageNotes
- * ```typescript
- * signalStore(
+ *
+ * ```ts
+ * import { signalStore, withFeature, withMethods } from '@ngrx/signals';
+ *
+ * export const UserStore = signalStore(
  *   withMethods((store) => ({
- *     load(id: number): Observable<Entity> {
- *       return of({ id, name: 'John' });
+ *     loadById(id: number): Promise<User> {
+ *       return Promise.resolve({ id, name: 'John' });
  *     },
  *   })),
  *   withFeature(
- *     // 👇 has full access to the store
- *     (store) => withEntityLoader((id) => firstValueFrom(store.load(id)))
+ *     // 👇 Has full access to store members.
+ *     (store) => withEntityLoader((id) => store.loadById(id))
  *   )
  * );
  * ```
- *
- * @param featureFactory function returning the actual feature
  */
 function withFeature(featureFactory) {
     return (store) => {
@@ -339,6 +603,31 @@ function withFeature(featureFactory) {
     };
 }
 
+/**
+ * @description
+ *
+ * Adds lifecycle hooks to a SignalStore.
+ * Supports an onInit hook that executes when the store is initialized.
+ * Supports an onDestroy hook for when the store is destroyed.
+ *
+ * @usageNotes
+ *
+ * ```ts
+ * import { signalStore, withHooks, withState } from '@ngrx/signals';
+ *
+ * export const UserStore = signalStore(
+ *   withState({ firstName: 'Jimi', lastName: 'Hendrix' }),
+ *   withHooks({
+ *     onInit({ firstName }) {
+ *       console.log('first name on init', firstName());
+ *     },
+ *     onDestroy({ lastName }) {
+ *       console.log('last name on destroy', lastName());
+ *     },
+ *   })
+ * );
+ * ```
+ */
 function withHooks(hooksOrFactory) {
     return (store) => {
         const storeMembers = {
@@ -374,11 +663,17 @@ function withHooks(hooksOrFactory) {
  * @description
  *
  * Adds linked state slices to a SignalStore.
+ * Accepts a factory function that returns a dictionary of linked signals or
+ * computation functions.
  *
  * @usageNotes
  *
- * ```typescript
- * const OptionsStore = signalStore(
+ * ### Using a computation function
+ *
+ * ```ts
+ * import { signalStore, withLinkedState, withState } from '@ngrx/signals';
+ *
+ * export const OptionsStore = signalStore(
  *   withState({ options: [1, 2, 3] }),
  *   withLinkedState(({ options }) => ({
  *     selectedOption: () => options()[0],
@@ -386,15 +681,15 @@ function withHooks(hooksOrFactory) {
  * );
  * ```
  *
- * This returns a state of type `{ options: number[], selectedOption: number | undefined }`.
- * When the `options` signal changes, the `selectedOption` automatically updates.
+ * ### Using linkedSignal for advanced use cases
  *
- * For advanced use cases, `linkedSignal` or any other `WritableSignal` instance can be used within `withLinkedState`:
+ * ```ts
+ * import { linkedSignal } from '@angular/core';
+ * import { signalStore, withLinkedState, withState } from '@ngrx/signals';
  *
- * ```typescript
  * type Option = { id: number; label: string };
  *
- * const OptionsStore = signalStore(
+ * export const OptionsStore = signalStore(
  *   withState({ options: [] as Option[] }),
  *   withLinkedState(({ options }) => ({
  *     selectedOption: linkedSignal<Option[], Option>({
@@ -403,12 +698,10 @@ function withHooks(hooksOrFactory) {
  *         const option = newOptions.find((o) => o.id === previous?.value.id);
  *         return option ?? newOptions[0];
  *       },
- *     })
+ *     }),
  *   }))
  * )
  * ```
- *
- * @param linkedStateFactory A function that returns an object literal with properties containing an actual `linkedSignal` or the computation function.
  */
 function withLinkedState(linkedStateFactory) {
     return (store) => {
@@ -436,6 +729,29 @@ function withLinkedState(linkedStateFactory) {
     };
 }
 
+/**
+ * @description
+ *
+ * Adds methods to a SignalStore.
+ *
+ * @usageNotes
+ *
+ * ```ts
+ * import { patchState, signalStore, withMethods, withState } from '@ngrx/signals';
+ *
+ * export const CounterStore = signalStore(
+ *   withState({ count: 0 }),
+ *   withMethods((store) => ({
+ *     increment(): void {
+ *       patchState(store, ({ count }) => ({ count: count + 1 }));
+ *     },
+ *     decrement(): void {
+ *       patchState(store, ({ count }) => ({ count: count - 1 }));
+ *     },
+ *   }))
+ * );
+ * ```
+ */
 function withMethods(methodsFactory) {
     return (store) => {
         const methods = methodsFactory({
@@ -454,6 +770,22 @@ function withMethods(methodsFactory) {
     };
 }
 
+/**
+ * @description
+ *
+ * Adds state slices to a SignalStore.
+ * Accepts an object or a factory function that returns the initial state.
+ *
+ * @usageNotes
+ *
+ * ```ts
+ * import { signalStore, withState } from '@ngrx/signals';
+ *
+ * export const CounterStore = signalStore(
+ *   withState({ count: 0 })
+ * );
+ * ```
+ */
 function withState(stateOrFactory) {
     return (store) => {
         const state = (typeof stateOrFactory === 'function' ? stateOrFactory() : stateOrFactory);