@ngrx/signals 21.0.0 → 21.1.0

package/schematics-core/utility/libs-version.js.map

@@ -1 +1 @@
-{"version":3,"file":"libs-version.js","sourceRoot":"","sources":["../../../../../modules/signals/schematics-core/utility/libs-version.ts"],"names":[],"mappings":";;;AAAa,QAAA,eAAe,GAAG,SAAS,CAAC","sourcesContent":["export const platformVersion = '^21.0.0';\n"]}
+{"version":3,"file":"libs-version.js","sourceRoot":"","sources":["../../../../../modules/signals/schematics-core/utility/libs-version.ts"],"names":[],"mappings":";;;AAAa,QAAA,eAAe,GAAG,SAAS,CAAC","sourcesContent":["export const platformVersion = '^21.1.0';\n"]}

package/types/ngrx-signals-events.d.ts

@@ -137,7 +137,7 @@ declare abstract class BaseEvents {
  *
  * const increment = event('[Counter Page] Increment');
  *
- * \@Component({ /* ... *\/ })
+ * \@Component(...)
  * class Counter {
  *   readonly #events = inject(Events);
  *
@@ -180,7 +180,7 @@ declare class ReducerEvents extends BaseEvents {
  *
  * const increment = event('[Counter Page] Increment');
  *
- * \@Component({ /* ... *\/ })
+ * \@Component(...)
  * class Counter {
  *   readonly #dispatcher = inject(Dispatcher);
  *
@@ -212,7 +212,7 @@ declare class Dispatcher {
  * const increment = event('[Counter Page] Increment');
  *
  * \@Component({
- *   /* ... *\/
+ *   // ...
  *   providers: [provideDispatcher()],
  * })
  * class Counter {
@@ -285,7 +285,7 @@ type SelfDispatchingEvents<EventGroup extends Record<string, EventCreator<string
  *   },
  * });
  *
- * \@Component({ /* ... *\/ })
+ * \@Component(...)
  * class Counter {
  *   readonly dispatch = injectDispatch(counterPageEvents);
  *

package/types/ngrx-signals-rxjs-interop.d.ts

@@ -7,6 +7,45 @@ type RxMethodRef = {
 type RxMethod<Input> = ((input: Input | (() => Input) | Observable<Input>, config?: {
     injector?: Injector;
 }) => RxMethodRef) & RxMethodRef;
+/**
+ * @description
+ *
+ * Creates a reactive method for managing side effects by utilizing RxJS APIs.
+ * The method accepts an observable, a signal, a computation function, or
+ * a static value.
+ *
+ * @usageNotes
+ *
+ * ```ts
+ * import { Component, inject, signal } from '@angular/core';
+ * import { switchMap } from 'rxjs';
+ * import { rxMethod } from '@ngrx/signals/rxjs-interop';
+ * import { tapResponse } from '@ngrx/operators';
+ *
+ * \@Component(...)
+ * export class TodoList {
+ *   readonly #todosService = inject(TodosService);
+ *   readonly userId = signal(1);
+ *   readonly todos = signal<Todo[]>([]);
+ *
+ *   readonly loadTodos = rxMethod<number>(
+ *     switchMap((id) =>
+ *       this.#todosService.getByUserId(id).pipe(
+ *         tapResponse({
+ *           next: (todos) => this.todos.set(todos),
+ *           error: console.error,
+ *         })
+ *       )
+ *     )
+ *   );
+ *
+ *   constructor() {
+ *     // 👇 Load todos on `userId` changes.
+ *     this.loadTodos(this.userId);
+ *   }
+ * }
+ * ```
+ */
 declare function rxMethod<Input>(generator: (source$: Observable<Input>) => Observable<unknown>, config?: {
     injector?: Injector;
 }): RxMethod<Input>;

package/types/ngrx-signals-testing.d.ts

@@ -1,6 +1,41 @@
 import { StateSource, Prettify, WritableStateSource } from '@ngrx/signals';
 
 type UnprotectedSource<Source extends StateSource<object>> = Source extends StateSource<infer State> ? Prettify<Omit<Source, keyof StateSource<State>> & WritableStateSource<State>> : never;
+/**
+ * @description
+ *
+ * Allows updating the protected state of a SignalStore for testing purposes.
+ *
+ * @usageNotes
+ *
+ * ```ts
+ * import { TestBed } from '@angular/core/testing';
+ * import {
+ *   patchState,
+ *   signalStore,
+ *   withState,
+ *   withComputed,
+ * } from '@ngrx/signals';
+ * import { unprotected } from '@ngrx/signals/testing';
+ *
+ * const UserStore = signalStore(
+ *   { providedIn: 'root' },
+ *   withState({ firstName: 'Eric', lastName: 'Clapton' }),
+ *   withComputed(({ firstName, lastName }) => ({
+ *     fullName: () => `${firstName()} ${lastName()}`,
+ *   }))
+ * );
+ *
+ * describe('UserStore', () => {
+ *   it('recomputes fullName on firstName changes', () => {
+ *     const userStore = TestBed.inject(UserStore);
+ *
+ *     patchState(unprotected(userStore), { firstName: 'Patrick' });
+ *     expect(userStore.fullName()).toBe('Patrick Clapton');
+ *   });
+ * });
+ * ```
+ */
 declare function unprotected<Source extends StateSource<object>>(source: Source): UnprotectedSource<Source>;
 
 export { unprotected };

package/types/ngrx-signals.d.ts

@@ -15,11 +15,64 @@ type DeepSignal<T> = Signal<T> & (IsKnownRecord<T> extends true ? Readonly<{
     [K in keyof T]: IsKnownRecord<T[K]> extends true ? DeepSignal<T[K]> : Signal<T[K]>;
 }> : unknown);
 
+/**
+ * @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
+ * ```
+ */
 declare function deepComputed<T extends object>(computation: () => T): DeepSignal<T>;
 
 type SignalMethod<Input> = ((input: Input | (() => Input), config?: {
     injector?: Injector;
 }) => EffectRef) & EffectRef;
+/**
+ * @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)
+ *   }
+ * }
+ * ```
+ */
 declare function signalMethod<Input>(processingFn: (value: Input) => void, config?: {
     injector?: Injector;
 }): SignalMethod<Input>;
@@ -38,8 +91,84 @@ type StateSource<State extends object> = {
 type PartialStateUpdater<State extends object> = (state: State) => Partial<State>;
 type StateWatcher<State extends object> = (state: NoInfer<State>) => void;
 declare function isWritableStateSource<State extends object>(stateSource: StateSource<State>): stateSource is WritableStateSource<State>;
+/**
+ * @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 });
+ *     },
+ *   }))
+ * );
+ * ```
+ */
 declare function patchState<State extends object>(stateSource: WritableStateSource<State>, ...updaters: Array<Partial<NoInfer<State>> | PartialStateUpdater<NoInfer<State>>>): void;
+/**
+ * @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);
+ *     });
+ *   }
+ * }
+ * ```
+ */
 declare function getState<State extends object>(stateSource: StateSource<State>): State;
+/**
+ * @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);
+ *   }
+ * }
+ * ```
+ */
 declare function watchState<State extends object>(stateSource: StateSource<State>, watcher: StateWatcher<State>, config?: {
     injector?: Injector;
 }): {
@@ -47,6 +176,32 @@ declare function watchState<State extends object>(stateSource: StateSource<State
 };
 
 type SignalState<State extends object> = DeepSignal<State> & WritableStateSource<State>;
+/**
+ * @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 }));
+ *   }
+ * }
+ * ```
+ */
 declare function signalState<State extends object>(initialState: State): SignalState<State>;
 
 type StateSignals<State> = IsKnownRecord<Prettify<State>> extends true ? {
@@ -215,6 +370,26 @@ declare function type<T>(): T;
 type ComputedResult<ComputedDictionary extends Record<string | symbol, Signal<unknown> | (() => unknown)>> = {
     [P in keyof ComputedDictionary]: ComputedDictionary[P] extends Signal<unknown> ? ComputedDictionary[P] : ComputedDictionary[P] extends () => infer V ? Signal<V> : never;
 };
+/**
+ * @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,
+ *   }))
+ * );
+ * ```
+ */
 declare function withComputed<Input extends SignalStoreFeatureResult, ComputedDictionary extends Record<string | symbol, Signal<unknown> | (() => unknown)>>(computedFactory: (store: Prettify<StateSignals<Input['state']> & Input['props'] & Input['methods']>) => ComputedDictionary): SignalStoreFeature<Input, {
     state: {};
     props: ComputedResult<ComputedDictionary>;
@@ -223,25 +398,27 @@ declare function withComputed<Input extends SignalStoreFeatureResult, ComputedDi
 
 /**
  * @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
  */
 declare function withFeature<Input extends SignalStoreFeatureResult, Output extends SignalStoreFeatureResult>(featureFactory: (store: Prettify<StateSignals<Input['state']> & Input['props'] & Input['methods'] & WritableStateSource<Input['state']>>) => SignalStoreFeature<Input, Output>): SignalStoreFeature<Input, Output>;
 
@@ -263,11 +440,17 @@ type LinkedStateResult<LinkedStateInput extends Record<string | symbol, Writable
  * @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],
@@ -275,15 +458,15 @@ type LinkedStateResult<LinkedStateInput extends Record<string | symbol, Writable
  * );
  * ```
  *
- * 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>({
@@ -292,12 +475,10 @@ type LinkedStateResult<LinkedStateInput extends Record<string | symbol, Writable
  *         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.
  */
 declare function withLinkedState<State extends Record<string | symbol, WritableSignal<unknown> | (() => unknown)>, Input extends SignalStoreFeatureResult>(linkedStateFactory: (store: Prettify<StateSignals<Input['state']> & Input['props']>) => State): SignalStoreFeature<Input, {
     state: LinkedStateResult<State>;
@@ -305,12 +486,54 @@ declare function withLinkedState<State extends Record<string | symbol, WritableS
     methods: {};
 }>;
 
+/**
+ * @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 }));
+ *     },
+ *   }))
+ * );
+ * ```
+ */
 declare function withMethods<Input extends SignalStoreFeatureResult, Methods extends MethodsDictionary>(methodsFactory: (store: Prettify<StateSignals<Input['state']> & Input['props'] & Input['methods'] & WritableStateSource<Input['state']>>) => Methods): SignalStoreFeature<Input, {
     state: {};
     props: {};
     methods: Methods;
 }>;
 
+/**
+ * @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),
+ *   }))
+ * );
+ * ```
+ */
 declare function withProps<Input extends SignalStoreFeatureResult, Props extends object>(propsFactory: (store: Prettify<StateSignals<Input['state']> & Input['props'] & Input['methods'] & WritableStateSource<Input['state']>>) => Props): SignalStoreFeature<Input, {
     state: {};
     props: Props;