diff --git a/commit_message b/commit_message
index da7941a55..a820c1ba0 100644
--- a/commit_message
+++ b/commit_message
@@ -1 +1 @@
-e2cca61a docs(component): remove redundant standalone flag (#4625)
+1b571c32 docs(signals): remove redundant standalone flag (#4624)
diff --git a/generated/docs/guide/signals/signal-state.json b/generated/docs/guide/signals/signal-state.json
index 542e1bfbf..e8675c304 100644
--- a/generated/docs/guide/signals/signal-state.json
+++ b/generated/docs/guide/signals/signal-state.json
@@ -1,5 +1,5 @@
{
"id": "guide/signals/signal-state",
"title": "SignalState",
- "contents": "\n\n\n \n\n\n\n
SignalState
\n
SignalState is a lightweight utility designed for managing signal-based state in a concise and minimalistic manner.\nIt's suitable for managing modest-sized states and can be used directly in components, services, or standalone functions.
\n
Creating a SignalState
\n
SignalState is instantiated using the signalState function, which accepts an initial state as an input argument.
\n
\nimport { signalState } from '@ngrx/signals';\nimport { User } from './user.model';\n\ntype UserState = { user: User; isAdmin: boolean };\n\nconst userState = signalState<UserState>({\n user: { firstName: 'Eric', lastName: 'Clapton' },\n isAdmin: false,\n});\n\n
The state's type must be a record/object literal. Add arrays or primitive values to properties.
\n
signalState returns an extended version of a signal that possesses all the capabilities of a read-only signal.
\n
\nimport { computed, effect } from '@angular/core';\n\n// 👇 Creating computed signals.\nconst userStateStr = computed(() => JSON.stringify(userState()));\n\n// 👇 Performing side effects.\neffect(() => console.log('userState', userState()));\n\n
Additionally, the signalState function generates signals for each state property.
\n
\nconst user = userState.user; // type: DeepSignal<User>\nconst isAdmin = userState.isAdmin; // type: Signal<boolean>\n\nconsole.log(user()); // logs: { firstName: 'Eric', lastName: 'Clapton' }\nconsole.log(isAdmin()); // logs: false\n\n
When a state property holds an object as its value, the signalState function generates a DeepSignal.\nIt can be used as a regular read-only signal, but it also contains signals for each property of the object it refers to.
\n
\nconst firstName = user.firstName; // type: Signal<string>\nconst lastName = user.lastName; // type: Signal<string>\n\nconsole.log(firstName()); // logs: 'Eric'\nconsole.log(lastName()); // logs: 'Clapton'\n\n
\n
For enhanced performance, deeply nested signals are generated lazily and initialized only upon first access.
\n
\n
Updating State
\n
The patchState function provides a type-safe way to perform updates on pieces of state.\nIt takes a SignalState or SignalStore instance as the first argument, followed by a sequence of partial states or partial state updaters as additional arguments.
\n
\nimport { patchState } from '@ngrx/signals';\n\n// 👇 Providing a partial state object.\npatchState(userState, { isAdmin: true });\n\n// 👇 Providing a partial state updater.\npatchState(userState, (state) => ({\n user: { ...state.user, firstName: 'Jimi' },\n}));\n\n// 👇 Providing a sequence of partial state objects and/or updaters.\npatchState(\n userState,\n { isAdmin: false },\n (state) => ({ user: { ...state.user, lastName: 'Hendrix' } })\n);\n\n
\n
Updaters passed to the patchState function must perform state updates in an immutable manner.\nIf a mutable change occurs to the state object, an error will be thrown in development mode.
\n
\n
Custom State Updaters
\n
Instead of providing partial states or updaters directly to the patchState function, it's possible to create custom state updaters.
\n
\nimport { PartialStateUpdater } from '@ngrx/signals';\n\nfunction setFirstName(firstName: string): PartialStateUpdater<{ user: User }> {\n return (state) => ({ user: { ...state.user, firstName } });\n}\n\nconst setAdmin = () => ({ isAdmin: true });\n\n
Custom state updaters are easy to test and can be reused across different parts of the application.
\n
\n// Before:\npatchState(userState, (state) => ({\n user: { ...state.user, firstName: 'Stevie' },\n isAdmin: true,\n}));\n\n// After:\npatchState(userState, setFirstName('Stevie'), setAdmin());\n\n
Usage
\n
Example 1: SignalState in a Component
\n
\n\nimport { ChangeDetectionStrategy, Component } from '@angular/core';\nimport { signalState, patchState } from '@ngrx/signals';\n\n@Component({\n selector: 'ngrx-counter',\n standalone: true,\n template: `\n <p>Count: {{ state.count() }}</p>\n\n <button (click)=\"increment()\">Increment</button>\n <button (click)=\"decrement()\">Decrement</button>\n <button (click)=\"reset()\">Reset</button>\n `,\n changeDetection: ChangeDetectionStrategy.OnPush,\n})\nexport class CounterComponent {\n readonly state = signalState({ count: 0 });\n\n increment(): void {\n patchState(this.state, (state) => ({ count: state.count + 1 }));\n }\n\n decrement(): void {\n patchState(this.state, (state) => ({ count: state.count - 1 }));\n }\n\n reset(): void {\n patchState(this.state, { count: 0 });\n }\n}\n\n\n
Example 2: SignalState in a Service
\n
\n\n\nimport { inject, Injectable } from '@angular/core';\nimport { exhaustMap, pipe, tap } from 'rxjs';\nimport { signalState, patchState } from '@ngrx/signals';\nimport { rxMethod } from '@ngrx/signals/rxjs-interop';\nimport { tapResponse } from '@ngrx/operators';\nimport { BooksService } from './books.service';\nimport { Book } from './book.model';\n\ntype BooksState = { books: Book[]; isLoading: boolean };\n\nconst initialState: BooksState = {\n books: [],\n isLoading: false,\n};\n\n@Injectable()\nexport class BooksStore {\n readonly #booksService = inject(BooksService);\n readonly #state = signalState(initialState);\n\n readonly books = this.#state.books;\n readonly isLoading = this.#state.isLoading;\n\n readonly loadBooks = rxMethod<void>(\n pipe(\n tap(() => patchState(this.#state, { isLoading: true })),\n exhaustMap(() => {\n return this.#booksService.getAll().pipe(\n tapResponse({\n next: (books) => patchState(this.#state, { books }),\n error: console.error,\n finalize: () => patchState(this.#state, { isLoading: false }),\n })\n );\n })\n )\n );\n}\n\n\n\n\n\nimport { ChangeDetectionStrategy, Component, inject, OnInit } from '@angular/core';\nimport { BooksStore } from './books.store';\n\n@Component({\n selector: 'ngrx-books',\n standalone: true,\n template: `\n <h1>Books</h1>\n \n @if (store.isLoading()) {\n <p>Loading...</p>\n } @else {\n <ul>\n @for (book of store.books(); track book.id) {\n <li>{{ book.title }}</li>\n }\n </ul>\n }\n `,\n providers: [BooksStore],\n changeDetection: ChangeDetectionStrategy.OnPush,\n})\nexport class BooksComponent implements OnInit {\n readonly store = inject(BooksStore);\n\n ngOnInit(): void {\n this.store.loadBooks();\n }\n}\n\n\n\n\n
\n
SignalState
\n
SignalState is a lightweight utility designed for managing signal-based state in a concise and minimalistic manner.\nIt's suitable for managing modest-sized states and can be used directly in components, services, or standalone functions.
\n
Creating a SignalState
\n
SignalState is instantiated using the signalState function, which accepts an initial state as an input argument.
\n
\nimport { signalState } from '@ngrx/signals';\nimport { User } from './user.model';\n\ntype UserState = { user: User; isAdmin: boolean };\n\nconst userState = signalState<UserState>({\n user: { firstName: 'Eric', lastName: 'Clapton' },\n isAdmin: false,\n});\n\n
The state's type must be a record/object literal. Add arrays or primitive values to properties.
\n
signalState returns an extended version of a signal that possesses all the capabilities of a read-only signal.
\n
\nimport { computed, effect } from '@angular/core';\n\n// 👇 Creating computed signals.\nconst userStateStr = computed(() => JSON.stringify(userState()));\n\n// 👇 Performing side effects.\neffect(() => console.log('userState', userState()));\n\n
Additionally, the signalState function generates signals for each state property.
\n
\nconst user = userState.user; // type: DeepSignal<User>\nconst isAdmin = userState.isAdmin; // type: Signal<boolean>\n\nconsole.log(user()); // logs: { firstName: 'Eric', lastName: 'Clapton' }\nconsole.log(isAdmin()); // logs: false\n\n
When a state property holds an object as its value, the signalState function generates a DeepSignal.\nIt can be used as a regular read-only signal, but it also contains signals for each property of the object it refers to.
\n
\nconst firstName = user.firstName; // type: Signal<string>\nconst lastName = user.lastName; // type: Signal<string>\n\nconsole.log(firstName()); // logs: 'Eric'\nconsole.log(lastName()); // logs: 'Clapton'\n\n
\n
For enhanced performance, deeply nested signals are generated lazily and initialized only upon first access.
\n
\n
Updating State
\n
The patchState function provides a type-safe way to perform updates on pieces of state.\nIt takes a SignalState or SignalStore instance as the first argument, followed by a sequence of partial states or partial state updaters as additional arguments.
\n
\nimport { patchState } from '@ngrx/signals';\n\n// 👇 Providing a partial state object.\npatchState(userState, { isAdmin: true });\n\n// 👇 Providing a partial state updater.\npatchState(userState, (state) => ({\n user: { ...state.user, firstName: 'Jimi' },\n}));\n\n// 👇 Providing a sequence of partial state objects and/or updaters.\npatchState(\n userState,\n { isAdmin: false },\n (state) => ({ user: { ...state.user, lastName: 'Hendrix' } })\n);\n\n
\n
Updaters passed to the patchState function must perform state updates in an immutable manner.\nIf a mutable change occurs to the state object, an error will be thrown in development mode.
\n
\n
Custom State Updaters
\n
Instead of providing partial states or updaters directly to the patchState function, it's possible to create custom state updaters.
\n
\nimport { PartialStateUpdater } from '@ngrx/signals';\n\nfunction setFirstName(firstName: string): PartialStateUpdater<{ user: User }> {\n return (state) => ({ user: { ...state.user, firstName } });\n}\n\nconst setAdmin = () => ({ isAdmin: true });\n\n
Custom state updaters are easy to test and can be reused across different parts of the application.
\n
\n// Before:\npatchState(userState, (state) => ({\n user: { ...state.user, firstName: 'Stevie' },\n isAdmin: true,\n}));\n\n// After:\npatchState(userState, setFirstName('Stevie'), setAdmin());\n\n
Usage
\n
Example 1: SignalState in a Component
\n
\n\nimport { ChangeDetectionStrategy, Component } from '@angular/core';\nimport { signalState, patchState } from '@ngrx/signals';\n\n@Component({\n selector: 'ngrx-counter',\n template: `\n <p>Count: {{ state.count() }}</p>\n\n <button (click)=\"increment()\">Increment</button>\n <button (click)=\"decrement()\">Decrement</button>\n <button (click)=\"reset()\">Reset</button>\n `,\n changeDetection: ChangeDetectionStrategy.OnPush,\n})\nexport class CounterComponent {\n readonly state = signalState({ count: 0 });\n\n increment(): void {\n patchState(this.state, (state) => ({ count: state.count + 1 }));\n }\n\n decrement(): void {\n patchState(this.state, (state) => ({ count: state.count - 1 }));\n }\n\n reset(): void {\n patchState(this.state, { count: 0 });\n }\n}\n\n\n
Example 2: SignalState in a Service
\n
\n\n\nimport { inject, Injectable } from '@angular/core';\nimport { exhaustMap, pipe, tap } from 'rxjs';\nimport { signalState, patchState } from '@ngrx/signals';\nimport { rxMethod } from '@ngrx/signals/rxjs-interop';\nimport { tapResponse } from '@ngrx/operators';\nimport { BooksService } from './books.service';\nimport { Book } from './book.model';\n\ntype BooksState = { books: Book[]; isLoading: boolean };\n\nconst initialState: BooksState = {\n books: [],\n isLoading: false,\n};\n\n@Injectable()\nexport class BooksStore {\n readonly #booksService = inject(BooksService);\n readonly #state = signalState(initialState);\n\n readonly books = this.#state.books;\n readonly isLoading = this.#state.isLoading;\n\n readonly loadBooks = rxMethod<void>(\n pipe(\n tap(() => patchState(this.#state, { isLoading: true })),\n exhaustMap(() => {\n return this.#booksService.getAll().pipe(\n tapResponse({\n next: (books) => patchState(this.#state, { books }),\n error: console.error,\n finalize: () => patchState(this.#state, { isLoading: false }),\n })\n );\n })\n )\n );\n}\n\n\n\n\n\nimport { ChangeDetectionStrategy, Component, inject, OnInit } from '@angular/core';\nimport { BooksStore } from './books.store';\n\n@Component({\n selector: 'ngrx-books',\n template: `\n <h1>Books</h1>\n \n @if (store.isLoading()) {\n <p>Loading...</p>\n } @else {\n <ul>\n @for (book of store.books(); track book.id) {\n <li>{{ book.title }}</li>\n }\n </ul>\n }\n `,\n providers: [BooksStore],\n changeDetection: ChangeDetectionStrategy.OnPush,\n})\nexport class BooksComponent implements OnInit {\n readonly store = inject(BooksStore);\n\n ngOnInit(): void {\n this.store.loadBooks();\n }\n}\n\n\n\n\n
\n
SignalStore
\n
NgRx SignalStore is a fully-featured state management solution that offers a robust way to manage application state.\nWith its native support for Signals, it provides the ability to define stores in a clear and declarative manner.\nThe simplicity and flexibility of SignalStore, coupled with its opinionated and extensible design, establish it as a versatile solution for effective state management in Angular.
\n
Creating a Store
\n
A SignalStore is created using the signalStore function. This function accepts a sequence of store features.\nThrough the combination of store features, the SignalStore gains state, properties, and methods, allowing for a flexible and extensible store implementation.\nBased on the utilized features, the signalStore function returns an injectable service that can be provided and injected where needed.
\n
The withState feature is used to add state slices to the SignalStore.\nThis feature accepts initial state as an input argument. As with signalState, the state's type must be a record/object literal.
\n
\n\nimport { signalStore, withState } from '@ngrx/signals';\nimport { Book } from './book.model';\n\ntype BooksState = {\n books: Book[];\n isLoading: boolean;\n filter: { query: string; order: 'asc' | 'desc' };\n};\n\nconst initialState: BooksState = {\n books: [],\n isLoading: false,\n filter: { query: '', order: 'asc' },\n};\n\nexport const BooksStore = signalStore(\n withState(initialState)\n);\n\n\n
For each state slice, a corresponding signal is automatically created.\nThe same applies to nested state properties, with all deeply nested signals being generated lazily on demand.
\n
The BooksStore instance will contain the following properties:
\n
\nbooks: Signal<Book[]>isLoading: Signal<boolean>filter: DeepSignal<{ query: string; order: 'asc' | 'desc' }>filter.query: Signal<string>filter.order: Signal<'asc' | 'desc'>
\n
\n
The withState feature also has a signature that takes the initial state factory as an input argument.\nThe factory is executed within the injection context, allowing initial state to be obtained from a service or injection token.
\n
\nconst BOOKS_STATE = new InjectionToken<BooksState>('BooksState', {\n factory: () => initialState,\n});\n\nconst BooksStore = signalStore(\n withState(() => inject(BOOKS_STATE))\n);\n\n
\n
Providing and Injecting the Store
\n
SignalStore can be provided locally and globally.\nBy default, a SignalStore is not registered with any injectors and must be included in a providers array at the component, route, or root level before injection.
\n
\n\nimport { Component, inject } from '@angular/core';\nimport { BooksStore } from './books.store';\n\n@Component({\n /* ... */\n // 👇 Providing `BooksStore` at the component level.\n providers: [BooksStore],\n})\nexport class BooksComponent {\n readonly store = inject(BooksStore);\n}\n\n\n
When provided at the component level, the store is tied to the component lifecycle, making it useful for managing local/component state.\nAlternatively, a SignalStore can be globally registered by setting the providedIn property to root when defining the store.
\n
\n\nimport { signalStore, withState } from '@ngrx/signals';\nimport { Book } from './book.model';\n\ntype BooksState = { /* ... */ };\n\nconst initialState: BooksState = { /* ... */ };\n\nexport const BooksStore = signalStore(\n // 👇 Providing `BooksStore` at the root level.\n { providedIn: 'root' },\n withState(initialState)\n);\n\n\n
When provided globally, the store is registered with the root injector and becomes accessible anywhere in the application.\nThis is beneficial for managing global state, as it ensures a single shared instance of the store across the entire application.
\n
Reading State
\n
Signals generated for state slices can be utilized to access state values, as demonstrated below.
\n
\n\nimport { ChangeDetectionStrategy, Component, inject } from '@angular/core';\nimport { JsonPipe } from '@angular/common';\nimport { BooksStore } from './books.store';\n\n@Component({\n standalone: true,\n imports: [JsonPipe],\n template: `\n <p>Books: {{ store.books() | json }}</p>\n <p>Loading: {{ store.isLoading() }}</p>\n\n <!-- 👇 The `DeepSignal` value can be read in the same way as `Signal`. -->\n <p>Pagination: {{ store.filter() | json }}</p>\n\n <!-- 👇 Nested signals are created as `DeepSignal` properties. -->\n <p>Query: {{ store.filter.query() }}</p>\n <p>Order: {{ store.filter.order() }}</p>\n `,\n providers: [BooksStore],\n changeDetection: ChangeDetectionStrategy.OnPush,\n})\nexport class BooksComponent {\n readonly store = inject(BooksStore);\n}\n\n\n
Defining Store Properties
\n
Computed signals can be added to the store using the withComputed feature.\nThis feature accepts a factory function as an input argument, which is executed within the injection context.\nThe factory should return a dictionary of computed signals, utilizing previously defined state signals and properties that are accessible through its input argument.
\n
\n\nimport { computed } from '@angular/core';\nimport { signalStore, withComputed, withState } from '@ngrx/signals';\nimport { Book } from './book.model';\n\ntype BooksState = { /* ... */ };\n\nconst initialState: BooksState = { /* ... */ };\n\nexport const BooksStore = signalStore(\n withState(initialState),\n // 👇 Accessing previously defined state signals and properties.\n withComputed(({ books, filter }) => ({\n booksCount: computed(() => books().length),\n sortedBooks: computed(() => {\n const direction = filter.order() === 'asc' ? 1 : -1;\n\n return books().toSorted((a, b) =>\n direction * a.title.localeCompare(b.title)\n );\n }),\n }))\n);\n\n\n
\n
The withProps feature can be used to add static properties, observables, dependencies, and any other custom properties to a SignalStore.\nFor more details, see the Custom Store Properties guide.
\n
\n
Defining Store Methods
\n
Methods can be added to the store using the withMethods feature.\nThis feature takes a factory function as an input argument and returns a dictionary of methods.\nSimilar to withComputed, the withMethods factory is also executed within the injection context.\nThe store instance, including previously defined state signals, properties, and methods, is accessible through the factory input.
\n
\n\nimport { computed } from '@angular/core';\nimport {\n patchState,\n signalStore,\n withComputed,\n withMethods,\n withState,\n} from '@ngrx/signals';\nimport { Book } from './book.model';\n\ntype BooksState = { /* ... */ };\n\nconst initialState: BooksState = { /* ... */ };\n\nexport const BooksStore = signalStore(\n withState(initialState),\n withComputed(/* ... */),\n // 👇 Accessing a store instance with previously defined state signals,\n // properties, and methods.\n withMethods((store) => ({\n updateQuery(query: string): void {\n // 👇 Updating state using the `patchState` function.\n patchState(store, (state) => ({ filter: { ...state.filter, query } }));\n },\n updateOrder(order: 'asc' | 'desc'): void {\n patchState(store, (state) => ({ filter: { ...state.filter, order } }));\n },\n }))\n);\n\n\n
\n
\n
By default, SignalStore's state is protected from external modifications, ensuring a consistent and predictable data flow.\nThis is the recommended approach.\nHowever, external updates to the state can be enabled by setting the protectedState option to false when creating a SignalStore.
\n
\nexport const BooksStore = signalStore(\n { protectedState: false }, // 👈\n withState(initialState)\n);\n\n@Component({ /* ... */ })\nexport class BooksComponent {\n readonly store = inject(BooksStore);\n\n addBook(book: Book): void {\n // ⚠️ The state of the `BooksStore` is unprotected from external modifications.\n patchState(this.store, ({ books }) => ({ books: [...books, book] }));\n }\n}\n\n
\n
In addition to methods for updating state, the withMethods feature can also be used to create methods for performing side effects.\nAsynchronous side effects can be executed using Promise-based APIs, as demonstrated below.
\n
\n\nimport { computed, inject } from '@angular/core';\nimport { patchState, signalStore, /* ... */ } from '@ngrx/signals';\nimport { Book } from './book.model';\nimport { BooksService } from './books.service';\n\ntype BooksState = { /* ... */ };\n\nconst initialState: BooksState = { /* ... */ };\n\nexport const BooksStore = signalStore(\n withState(initialState),\n withComputed(/* ... */),\n // 👇 `BooksService` can be injected within the `withMethods` factory.\n withMethods((store, booksService = inject(BooksService)) => ({\n /* ... */\n // 👇 Defining a method to load all books.\n async loadAll(): Promise<void> {\n patchState(store, { isLoading: true });\n\n const books = await booksService.getAll();\n patchState(store, { books, isLoading: false });\n },\n }))\n);\n\n\n
Reactive Store Methods
\n
In more complex scenarios, opting for RxJS to handle asynchronous side effects is advisable.\nTo create a reactive SignalStore method that harnesses RxJS APIs, use the rxMethod function from the rxjs-interop plugin.
\n
\n\nimport { computed, inject } from '@angular/core';\nimport { debounceTime, distinctUntilChanged, pipe, switchMap, tap } from 'rxjs';\nimport { patchState, signalStore, /* ... */ } from '@ngrx/signals';\nimport { rxMethod } from '@ngrx/signals/rxjs-interop';\nimport { tapResponse } from '@ngrx/operators';\nimport { Book } from './book.model';\nimport { BooksService } from './books.service';\n\ntype BooksState = { /* ... */ };\n\nconst initialState: BooksState = { /* ... */ };\n\nexport const BooksStore = signalStore(\n withState(initialState),\n withComputed(/* ... */),\n withMethods((store, booksService = inject(BooksService)) => ({\n /* ... */\n // 👇 Defining a method to load books by query.\n loadByQuery: rxMethod<string>(\n pipe(\n debounceTime(300),\n distinctUntilChanged(),\n tap(() => patchState(store, { isLoading: true })),\n switchMap((query) => {\n return booksService.getByQuery(query).pipe(\n tapResponse({\n next: (books) => patchState(store, { books, isLoading: false }),\n error: (err) => {\n patchState(store, { isLoading: false });\n console.error(err);\n },\n })\n );\n })\n )\n ),\n }))\n);\n\n\n
\n
Putting It All Together
\n
The final BooksStore implementation with state, computed signals, and methods from this guide is shown below.
\n
\n\nimport { computed, inject } from '@angular/core';\nimport { debounceTime, distinctUntilChanged, pipe, switchMap, tap } from 'rxjs';\nimport {\n patchState,\n signalStore,\n withComputed,\n withMethods,\n withState,\n} from '@ngrx/signals';\nimport { rxMethod } from '@ngrx/signals/rxjs-interop';\nimport { tapResponse } from '@ngrx/operators';\nimport { Book } from './book.model';\nimport { BooksService } from './books.service';\n\ntype BooksState = {\n books: Book[];\n isLoading: boolean;\n filter: { query: string; order: 'asc' | 'desc' };\n};\n\nconst initialState: BooksState = {\n books: [],\n isLoading: false,\n filter: { query: '', order: 'asc' },\n};\n\nexport const BooksStore = signalStore(\n withState(initialState),\n withComputed(({ books, filter }) => ({\n booksCount: computed(() => books().length),\n sortedBooks: computed(() => {\n const direction = filter.order() === 'asc' ? 1 : -1;\n\n return books().toSorted((a, b) =>\n direction * a.title.localeCompare(b.title)\n );\n }), \n })),\n withMethods((store, booksService = inject(BooksService)) => ({\n updateQuery(query: string): void {\n patchState(store, (state) => ({ filter: { ...state.filter, query } }));\n },\n updateOrder(order: 'asc' | 'desc'): void {\n patchState(store, (state) => ({ filter: { ...state.filter, order } }));\n },\n loadByQuery: rxMethod<string>(\n pipe(\n debounceTime(300),\n distinctUntilChanged(),\n tap(() => patchState(store, { isLoading: true })),\n switchMap((query) => {\n return booksService.getByQuery(query).pipe(\n tapResponse({\n next: (books) => patchState(store, { books }),\n error: console.error,\n finalize: () => patchState(store, { isLoading: false }),\n })\n );\n })\n )\n ),\n }))\n);\n\n\n
The BooksStore instance will contain the following properties and methods:
\n
\n- \n
State signals:
\n\nbooks: Signal<Book[]>isLoading: Signal<boolean>filter: DeepSignal<{ query: string; order: 'asc' | 'desc' }>filter.query: Signal<string>filter.order: Signal<'asc' | 'desc'>
\n \n- \n
Computed signals:
\n\nbooksCount: Signal<number>sortedBooks: Signal<Book[]>
\n \n- \n
Methods:
\n\nupdateQuery(query: string): voidupdateOrder(order: 'asc' | 'desc'): voidloadByQuery: RxMethod<string>
\n \n
\n
\n
The BooksComponent can use the BooksStore to manage the state, as demonstrated below.
\n
\n\nimport { ChangeDetectionStrategy, Component, inject, OnInit } from '@angular/core';\nimport { BooksFilterComponent } from './books-filter.component';\nimport { BookListComponent } from './book-list.component';\nimport { BooksStore } from './books.store';\n\n@Component({\n standalone: true,\n imports: [BooksFilterComponent, BookListComponent],\n template: `\n <h1>Books ({{ store.booksCount() }})</h1>\n\n <ngrx-books-filter\n [query]=\"store.filter.query()\"\n [order]=\"store.filter.order()\"\n (queryChange)=\"store.updateQuery($event)\"\n (orderChange)=\"store.updateOrder($event)\"\n />\n\n <ngrx-book-list\n [books]=\"store.sortedBooks()\"\n [isLoading]=\"store.isLoading()\"\n />\n `,\n providers: [BooksStore],\n changeDetection: ChangeDetectionStrategy.OnPush,\n})\nexport class BooksComponent implements OnInit {\n readonly store = inject(BooksStore);\n\n ngOnInit(): void {\n const query = this.store.filter.query;\n // 👇 Re-fetch books whenever the value of query signal changes.\n this.store.loadByQuery(query);\n }\n}\n\n\n
\n
In addition to component lifecycle hooks, SignalStore also offers the ability to define them at the store level.\nLearn more about SignalStore lifecycle hooks here.
\n
\n\n
\n
SignalStore
\n
NgRx SignalStore is a fully-featured state management solution that offers a robust way to manage application state.\nWith its native support for Signals, it provides the ability to define stores in a clear and declarative manner.\nThe simplicity and flexibility of SignalStore, coupled with its opinionated and extensible design, establish it as a versatile solution for effective state management in Angular.
\n
Creating a Store
\n
A SignalStore is created using the signalStore function. This function accepts a sequence of store features.\nThrough the combination of store features, the SignalStore gains state, properties, and methods, allowing for a flexible and extensible store implementation.\nBased on the utilized features, the signalStore function returns an injectable service that can be provided and injected where needed.
\n
The withState feature is used to add state slices to the SignalStore.\nThis feature accepts initial state as an input argument. As with signalState, the state's type must be a record/object literal.
\n
\n\nimport { signalStore, withState } from '@ngrx/signals';\nimport { Book } from './book.model';\n\ntype BooksState = {\n books: Book[];\n isLoading: boolean;\n filter: { query: string; order: 'asc' | 'desc' };\n};\n\nconst initialState: BooksState = {\n books: [],\n isLoading: false,\n filter: { query: '', order: 'asc' },\n};\n\nexport const BooksStore = signalStore(\n withState(initialState)\n);\n\n\n
For each state slice, a corresponding signal is automatically created.\nThe same applies to nested state properties, with all deeply nested signals being generated lazily on demand.
\n
The BooksStore instance will contain the following properties:
\n
\nbooks: Signal<Book[]>isLoading: Signal<boolean>filter: DeepSignal<{ query: string; order: 'asc' | 'desc' }>filter.query: Signal<string>filter.order: Signal<'asc' | 'desc'>
\n
\n
The withState feature also has a signature that takes the initial state factory as an input argument.\nThe factory is executed within the injection context, allowing initial state to be obtained from a service or injection token.
\n
\nconst BOOKS_STATE = new InjectionToken<BooksState>('BooksState', {\n factory: () => initialState,\n});\n\nconst BooksStore = signalStore(\n withState(() => inject(BOOKS_STATE))\n);\n\n
\n
Providing and Injecting the Store
\n
SignalStore can be provided locally and globally.\nBy default, a SignalStore is not registered with any injectors and must be included in a providers array at the component, route, or root level before injection.
\n
\n\nimport { Component, inject } from '@angular/core';\nimport { BooksStore } from './books.store';\n\n@Component({\n /* ... */\n // 👇 Providing `BooksStore` at the component level.\n providers: [BooksStore],\n})\nexport class BooksComponent {\n readonly store = inject(BooksStore);\n}\n\n\n
When provided at the component level, the store is tied to the component lifecycle, making it useful for managing local/component state.\nAlternatively, a SignalStore can be globally registered by setting the providedIn property to root when defining the store.
\n
\n\nimport { signalStore, withState } from '@ngrx/signals';\nimport { Book } from './book.model';\n\ntype BooksState = { /* ... */ };\n\nconst initialState: BooksState = { /* ... */ };\n\nexport const BooksStore = signalStore(\n // 👇 Providing `BooksStore` at the root level.\n { providedIn: 'root' },\n withState(initialState)\n);\n\n\n
When provided globally, the store is registered with the root injector and becomes accessible anywhere in the application.\nThis is beneficial for managing global state, as it ensures a single shared instance of the store across the entire application.
\n
Reading State
\n
Signals generated for state slices can be utilized to access state values, as demonstrated below.
\n
\n\nimport { ChangeDetectionStrategy, Component, inject } from '@angular/core';\nimport { JsonPipe } from '@angular/common';\nimport { BooksStore } from './books.store';\n\n@Component({\n imports: [JsonPipe],\n template: `\n <p>Books: {{ store.books() | json }}</p>\n <p>Loading: {{ store.isLoading() }}</p>\n\n <!-- 👇 The `DeepSignal` value can be read in the same way as `Signal`. -->\n <p>Pagination: {{ store.filter() | json }}</p>\n\n <!-- 👇 Nested signals are created as `DeepSignal` properties. -->\n <p>Query: {{ store.filter.query() }}</p>\n <p>Order: {{ store.filter.order() }}</p>\n `,\n providers: [BooksStore],\n changeDetection: ChangeDetectionStrategy.OnPush,\n})\nexport class BooksComponent {\n readonly store = inject(BooksStore);\n}\n\n\n
Defining Store Properties
\n
Computed signals can be added to the store using the withComputed feature.\nThis feature accepts a factory function as an input argument, which is executed within the injection context.\nThe factory should return a dictionary of computed signals, utilizing previously defined state signals and properties that are accessible through its input argument.
\n
\n\nimport { computed } from '@angular/core';\nimport { signalStore, withComputed, withState } from '@ngrx/signals';\nimport { Book } from './book.model';\n\ntype BooksState = { /* ... */ };\n\nconst initialState: BooksState = { /* ... */ };\n\nexport const BooksStore = signalStore(\n withState(initialState),\n // 👇 Accessing previously defined state signals and properties.\n withComputed(({ books, filter }) => ({\n booksCount: computed(() => books().length),\n sortedBooks: computed(() => {\n const direction = filter.order() === 'asc' ? 1 : -1;\n\n return books().toSorted((a, b) =>\n direction * a.title.localeCompare(b.title)\n );\n }),\n }))\n);\n\n\n
\n
The withProps feature can be used to add static properties, observables, dependencies, and any other custom properties to a SignalStore.\nFor more details, see the Custom Store Properties guide.
\n
\n
Defining Store Methods
\n
Methods can be added to the store using the withMethods feature.\nThis feature takes a factory function as an input argument and returns a dictionary of methods.\nSimilar to withComputed, the withMethods factory is also executed within the injection context.\nThe store instance, including previously defined state signals, properties, and methods, is accessible through the factory input.
\n
\n\nimport { computed } from '@angular/core';\nimport {\n patchState,\n signalStore,\n withComputed,\n withMethods,\n withState,\n} from '@ngrx/signals';\nimport { Book } from './book.model';\n\ntype BooksState = { /* ... */ };\n\nconst initialState: BooksState = { /* ... */ };\n\nexport const BooksStore = signalStore(\n withState(initialState),\n withComputed(/* ... */),\n // 👇 Accessing a store instance with previously defined state signals,\n // properties, and methods.\n withMethods((store) => ({\n updateQuery(query: string): void {\n // 👇 Updating state using the `patchState` function.\n patchState(store, (state) => ({ filter: { ...state.filter, query } }));\n },\n updateOrder(order: 'asc' | 'desc'): void {\n patchState(store, (state) => ({ filter: { ...state.filter, order } }));\n },\n }))\n);\n\n\n
\n
\n
By default, SignalStore's state is protected from external modifications, ensuring a consistent and predictable data flow.\nThis is the recommended approach.\nHowever, external updates to the state can be enabled by setting the protectedState option to false when creating a SignalStore.
\n
\nexport const BooksStore = signalStore(\n { protectedState: false }, // 👈\n withState(initialState)\n);\n\n@Component({ /* ... */ })\nexport class BooksComponent {\n readonly store = inject(BooksStore);\n\n addBook(book: Book): void {\n // ⚠️ The state of the `BooksStore` is unprotected from external modifications.\n patchState(this.store, ({ books }) => ({ books: [...books, book] }));\n }\n}\n\n
\n
In addition to methods for updating state, the withMethods feature can also be used to create methods for performing side effects.\nAsynchronous side effects can be executed using Promise-based APIs, as demonstrated below.
\n
\n\nimport { computed, inject } from '@angular/core';\nimport { patchState, signalStore, /* ... */ } from '@ngrx/signals';\nimport { Book } from './book.model';\nimport { BooksService } from './books.service';\n\ntype BooksState = { /* ... */ };\n\nconst initialState: BooksState = { /* ... */ };\n\nexport const BooksStore = signalStore(\n withState(initialState),\n withComputed(/* ... */),\n // 👇 `BooksService` can be injected within the `withMethods` factory.\n withMethods((store, booksService = inject(BooksService)) => ({\n /* ... */\n // 👇 Defining a method to load all books.\n async loadAll(): Promise<void> {\n patchState(store, { isLoading: true });\n\n const books = await booksService.getAll();\n patchState(store, { books, isLoading: false });\n },\n }))\n);\n\n\n
Reactive Store Methods
\n
In more complex scenarios, opting for RxJS to handle asynchronous side effects is advisable.\nTo create a reactive SignalStore method that harnesses RxJS APIs, use the rxMethod function from the rxjs-interop plugin.
\n
\n\nimport { computed, inject } from '@angular/core';\nimport { debounceTime, distinctUntilChanged, pipe, switchMap, tap } from 'rxjs';\nimport { patchState, signalStore, /* ... */ } from '@ngrx/signals';\nimport { rxMethod } from '@ngrx/signals/rxjs-interop';\nimport { tapResponse } from '@ngrx/operators';\nimport { Book } from './book.model';\nimport { BooksService } from './books.service';\n\ntype BooksState = { /* ... */ };\n\nconst initialState: BooksState = { /* ... */ };\n\nexport const BooksStore = signalStore(\n withState(initialState),\n withComputed(/* ... */),\n withMethods((store, booksService = inject(BooksService)) => ({\n /* ... */\n // 👇 Defining a method to load books by query.\n loadByQuery: rxMethod<string>(\n pipe(\n debounceTime(300),\n distinctUntilChanged(),\n tap(() => patchState(store, { isLoading: true })),\n switchMap((query) => {\n return booksService.getByQuery(query).pipe(\n tapResponse({\n next: (books) => patchState(store, { books, isLoading: false }),\n error: (err) => {\n patchState(store, { isLoading: false });\n console.error(err);\n },\n })\n );\n })\n )\n ),\n }))\n);\n\n\n
\n
Putting It All Together
\n
The final BooksStore implementation with state, computed signals, and methods from this guide is shown below.
\n
\n\nimport { computed, inject } from '@angular/core';\nimport { debounceTime, distinctUntilChanged, pipe, switchMap, tap } from 'rxjs';\nimport {\n patchState,\n signalStore,\n withComputed,\n withMethods,\n withState,\n} from '@ngrx/signals';\nimport { rxMethod } from '@ngrx/signals/rxjs-interop';\nimport { tapResponse } from '@ngrx/operators';\nimport { Book } from './book.model';\nimport { BooksService } from './books.service';\n\ntype BooksState = {\n books: Book[];\n isLoading: boolean;\n filter: { query: string; order: 'asc' | 'desc' };\n};\n\nconst initialState: BooksState = {\n books: [],\n isLoading: false,\n filter: { query: '', order: 'asc' },\n};\n\nexport const BooksStore = signalStore(\n withState(initialState),\n withComputed(({ books, filter }) => ({\n booksCount: computed(() => books().length),\n sortedBooks: computed(() => {\n const direction = filter.order() === 'asc' ? 1 : -1;\n\n return books().toSorted((a, b) =>\n direction * a.title.localeCompare(b.title)\n );\n }), \n })),\n withMethods((store, booksService = inject(BooksService)) => ({\n updateQuery(query: string): void {\n patchState(store, (state) => ({ filter: { ...state.filter, query } }));\n },\n updateOrder(order: 'asc' | 'desc'): void {\n patchState(store, (state) => ({ filter: { ...state.filter, order } }));\n },\n loadByQuery: rxMethod<string>(\n pipe(\n debounceTime(300),\n distinctUntilChanged(),\n tap(() => patchState(store, { isLoading: true })),\n switchMap((query) => {\n return booksService.getByQuery(query).pipe(\n tapResponse({\n next: (books) => patchState(store, { books }),\n error: console.error,\n finalize: () => patchState(store, { isLoading: false }),\n })\n );\n })\n )\n ),\n }))\n);\n\n\n
The BooksStore instance will contain the following properties and methods:
\n
\n- \n
State signals:
\n\nbooks: Signal<Book[]>isLoading: Signal<boolean>filter: DeepSignal<{ query: string; order: 'asc' | 'desc' }>filter.query: Signal<string>filter.order: Signal<'asc' | 'desc'>
\n \n- \n
Computed signals:
\n\nbooksCount: Signal<number>sortedBooks: Signal<Book[]>
\n \n- \n
Methods:
\n\nupdateQuery(query: string): voidupdateOrder(order: 'asc' | 'desc'): voidloadByQuery: RxMethod<string>
\n \n
\n
\n
The BooksComponent can use the BooksStore to manage the state, as demonstrated below.
\n
\n\nimport { ChangeDetectionStrategy, Component, inject, OnInit } from '@angular/core';\nimport { BooksFilterComponent } from './books-filter.component';\nimport { BookListComponent } from './book-list.component';\nimport { BooksStore } from './books.store';\n\n@Component({\n imports: [BooksFilterComponent, BookListComponent],\n template: `\n <h1>Books ({{ store.booksCount() }})</h1>\n\n <ngrx-books-filter\n [query]=\"store.filter.query()\"\n [order]=\"store.filter.order()\"\n (queryChange)=\"store.updateQuery($event)\"\n (orderChange)=\"store.updateOrder($event)\"\n />\n\n <ngrx-book-list\n [books]=\"store.sortedBooks()\"\n [isLoading]=\"store.isLoading()\"\n />\n `,\n providers: [BooksStore],\n changeDetection: ChangeDetectionStrategy.OnPush,\n})\nexport class BooksComponent implements OnInit {\n readonly store = inject(BooksStore);\n\n ngOnInit(): void {\n const query = this.store.filter.query;\n // 👇 Re-fetch books whenever the value of query signal changes.\n this.store.loadByQuery(query);\n }\n}\n\n\n
\n
In addition to component lifecycle hooks, SignalStore also offers the ability to define them at the store level.\nLearn more about SignalStore lifecycle hooks here.
\n
\n\n
\n
Testing
\n
A SignalStore is a straightforward Angular service, and the same testing techniques applied to other services also apply to SignalStore. This guide provides examples for common testing scenarios.
\n
One of the challenges in testing is managing asynchronous tasks and mocking dependencies. Although the examples use Jest, the same principles are applicable to other testing frameworks.
\n
There are two primary scenarios for testing:
\n
\n- Testing the SignalStore itself.
\n- Testing a component or service that utilizes the SignalStore.
\n
\n
In the first scenario, the dependencies of the SignalStore should be mocked, while in the second scenario, the SignalStore itself needs to be mocked.
\n
\n
When testing the SignalStore, interaction should occur through its public API, as any component or service would.
\n
A key concern in testing is maintainability. The more tests are coupled to internal implementations, the more frequently they are likely to break. Public APIs are generally more stable and less prone to change.
\n
For example, when testing the store in a loading state, avoid directly setting the loading property. Instead, trigger a loading method and assert against an exposed computed property or slice. This approach reduces dependency on internal implementations, such as properties set during the loading state.
\n
From this perspective, private properties or methods of the SignalStore should not be accessed. Additionally, avoid running patchState if the state is protected.
\n
\n
The SignalStore is a function that returns a class, allowing tests to instantiate the class and test it without using TestBed.
\n
However, in practice, TestBed is typically used due to its numerous advantages, such as the ability to mock dependencies and trigger the execution of effects.
\n
Additionally, key features of the SignalStore do not function properly if they do not run in an injection context. Examples include rxMethod, the use of inject within withMethods(), and withHooks().
\n
\n
Note: Using the TestBed is also the recommendation of the Angular team.
\n
\n
Testing the SignalStore
\n
The following example demonstrates the testing of a SignalStore:
\n
Globally provided
\n
\n\nimport { signalStore, withState } from '@ngrx/signals';\n\ntype Movie = {\n id: number;\n name: string;\n};\n\ntype State = { movies: Movie[] };\n\nexport const MoviesStore = signalStore(\n { providedIn: 'root' },\n withState<State>({\n movies: [\n { id: 1, name: 'A New Hope' },\n { id: 2, name: 'Into Darkness' },\n { id: 3, name: 'The Lord of the Rings' },\n ],\n })\n);\n\n\n
The TestBed instantiates the MoviesStore, enabling immediate testing.
\n
\n\nimport { MoviesStore } from './movies-store';\nimport { TestBed } from '@angular/core/testing';\n\ndescribe('MoviesStore', () => {\n it('should verify that three movies are available', () => {\n const store = TestBed.inject(MoviesStore);\n\n expect(store.movies()).toHaveLength(3);\n });\n});\n\n\n
Locally Provided
\n
This is possible due to the MoviesStore being provided globally. For locally provided stores, some adjustments to the test are required.
\n
\n\nexport const MoviesStore = signalStore(\n withState({\n movies: [\n // ... entries\n ],\n })\n);\n\n\n
The required addition is that the internal TestingModule must provide the MoviesStore.
\n
\n\nimport { MoviesStore } from './movies.store';\n\ndescribe('MoviesStore', () => {\n it('should verify that three movies are available', () => {\n TestBed.configureTestingModule({\n providers: [MoviesStore],\n });\n\n const store = TestBed.inject(MoviesStore);\n\n expect(store.movies()).toHaveLength(3);\n });\n});\n\n\n
\n
Testing derived values of withComputed is also straightforward.
\n
\n\nexport const MoviesStore = signalStore(\n withState({\n movies: [\n // ... entries\n ],\n }),\n withComputed((state) => ({\n moviesCount: computed(() => state.movies().length),\n }))\n);\n\n\n
\n\nimport { MoviesStore } from './movies.store';\n\ndescribe('MoviesStore', () => {\n it('should verify that three movies are available', () => {\n const store = TestBed.inject(MoviesStore);\n\n expect(store.moviesCount()).toBe(3);\n });\n});\n\n\n
withMethods, Dependency Injection, and Asynchronous Tasks
\n
A loading method asynchronously retrieves movies by studio in this scenario.
\n
\n\nimport { signalStore, withState } from '@ngrx/signals';\n\ntype State = { studio: string; movies: Movie[]; loading: boolean };\n\nexport const MoviesStore = signalStore(\n withState<State>({\n studio: '',\n movies: [],\n loading: false,\n }),\n withMethods((store) => {\n const moviesService = store.inject(MoviesService);\n\n return {\n async load(studio: string) {\n this.patchState({ loading: true });\n const movies = await moviesService.loadMovies(studio);\n this.patchState(store, { studio, movies, loading: false });\n },\n };\n })\n);\n\n\n
The MoviesService is mocked in the test, with the implementation returning the result as a Promise.
\n
\n\ndescribe('MoviesStore', () => {\n it('should load movies of Warner Bros', fakeAsync(() => {\n const moviesService = {\n load: () =>\n Promise.resolve([\n { id: 1, name: 'Harry Potter' },\n { id: 2, name: 'The Dark Knight' },\n ]),\n };\n\n TestBed.configureTestingModule({\n providers: [\n {\n provide: MoviesService,\n useValue: moviesService,\n },\n ],\n });\n\n const store = TestBed.inject(MoviesStore);\n store.load('Warner Bros');\n expect(store.loading()).toBe(true);\n \n tick();\n\n expect(store.moviesCount()).toBe(2);\n expect(store.loading()).toBe(false);\n }));\n});\n\n\n
\n
Note: Manually mocking dependencies is not required. Libraries such as ng-mocks, @testing-library/angular, and [jest|jasmine]-auto-spies can be used for this purpose.
\n
\n
\n
The load method is created using rxMethod to accommodate a component that provides an input field for the studio and initiates loading as soon as a user types in a name.
\n
In this scenario, the MovieService returns an Observable<Movie[]> instead of a Promise<Movie[]>.
\n
\n\nexport const MoviesStore = signalStore(\n // ... code omitted\n withMethods((store, moviesService = inject(MoviesService)) => ({\n load: rxMethod<string>(\n pipe(\n tap(() => patchState(store, { loading: true })),\n switchMap((studio) =>\n moviesService.load(studio).pipe(\n tapResponse({\n next: (movies) =>\n patchState(store, { movies, loading: false }),\n error: console.error,\n })\n )\n )\n )\n ),\n }))\n);\n\n\n
Since rxMethod accepts a string as a parameter, the previous test remains valid.
\n
An additional focus in testing is ensuring proper handling of race conditions, which is why switchMap is used.
\n
The parameter's type can also be Signal<number> or Observable<number>, in addition to number.
\n
With Observables
\n
The goal is to test whether the load method properly handles the scenario where a new studio name is entered before or after the previous request has completed.
\n
\n\ndescribe('MoviesStore', () => {\n // ... beforeEach and afterEach omitted\n\n const setup = () => {\n const moviesService = {\n load: jest.fn((studio: string) =>\n of([\n studio === 'Warner Bros'\n ? { id: 1, name: 'Harry Potter' }\n : { id: 2, name: 'Jurassic Park' }\n ]).pipe(delay(100))\n ),\n };\n\n TestBed.configureTestingModule({\n providers: [\n {\n provide: MoviesService,\n useValue: moviesService,\n },\n ],\n });\n\n return TestBed.inject(MoviesStore);\n };\n\n it('should load two times', fakeAsync(() => {\n const store = setup();\n\n const studio$ = new Subject<string>();\n store.load(studio$);\n studio$.next('Warner Bros');\n\n tick(100);\n expect(store.movies()).toEqual([{ id: 1, name: 'Harry Potter' }]);\n\n studio$.next('Universal');\n tick(100);\n expect(store.movies()).toEqual([{ id: 2, name: 'Jurassic Park' }]);\n }));\n\n it('should cancel a running request when a new one is made', fakeAsync(() => {\n const store = setup();\n\n const studio$ = new Subject<string>();\n store.load(studio$);\n studio$.next('Warner Bros');\n\n tick(50);\n studio$.next('Universal');\n\n tick(50);\n expect(store.movies()).toEqual([]);\n expect(store.loading()).toBe(true);\n\n tick(50);\n expect(store.movies()).toEqual([{ id: 2, name: 'Jurassic Park' }]);\n expect(store.loading()).toBe(false);\n }));\n});\n\n\n
By utilizing the testing framework's function to manage time, both scenarios can be verified.
\n
The test also employs a setup function to prevent code duplication, a common pattern in testing and an alternative to the beforeEach function. In this case, each test can choose whether to use the setup function or not.
\n
With Signals
\n
Testing both scenarios with a Signal type as input is similar to testing with Observables.
\n
This similarity arises primarily due to the asynchronous tasks involved.
\n
\n\ndescribe('MoviesStore', () => {\n // ... setup omitted\n\n it('should test two sequential loads with a Signal', fakeAsync(() => {\n const store = setup();\n const studio = signal('Warner Bros');\n store.load(studio);\n\n tick(100);\n expect(store.movies()).toEqual([{ id: 1, name: 'Harry Potter' }]);\n\n studio.set('Universal');\n tick(100);\n expect(store.movies()).toEqual([{ id: 2, name: 'Jurassic Park' }]);\n }));\n\n it('should cancel a running request when a new one is made via a Signal', fakeAsync(() => {\n const store = setup();\n const studio = signal('Warner Bros');\n\n effect(() => {\n console.log(studio());\n });\n store.load(studio);\n\n tick(50);\n\n studio.set('Universal');\n tick(50);\n expect(store.movies()).toEqual([]);\n expect(store.loading()).toBe(true);\n\n tick(50);\n expect(store.movies()).toEqual([{ id: 2, name: 'Jurassic Park' }]);\n expect(store.loading()).toBe(false);\n }));\n});\n\n\n
It is important to account for the glitch-free effect when using Signals. The rxMethod relies on effect, which may need to be triggered manually through TestBed.flushEffects().
\n
If the mocked MovieService operates synchronously, the following test fails unless TestBed.flushEffects() is called.
\n
\n\ndescribe('MoviesStore', () => {\n // ... beforeEach, and afterEach omitted\n\n it('should depend on flushEffects because of synchronous execution', () => {\n const moviesService = {\n load: jest.fn((studio: string) =>\n of([\n studio === 'Warner Bros'\n ? { id: 1, name: 'Harry Potter' }\n : { id: 2, name: 'Jurassic Park' }\n ])\n ),\n };\n\n TestBed.configureTestingModule({\n providers: [\n {\n provide: MoviesService,\n useValue: moviesService,\n },\n ],\n });\n\n const store = TestBed.inject(MoviesStore);\n const studio = signal('Warner Bros');\n store.load(studio);\n TestBed.flushEffects(); // required\n expect(store.movies()).toEqual([{ id: 1, name: 'Harry Potter' }]);\n\n studio.set('Universal');\n TestBed.flushEffects(); // required\n expect(store.movies()).toEqual([{ id: 2, name: 'Jurassic Park' }]);\n });\n});\n\n\n
Mocking the SignalStore
\n
What applies to testing the SignalStore also applies to mocking it. The SignalStore functions like any other service, meaning it can be mocked using the same tools and techniques applied to other services.
\n
The MovieComponent utilizes the MoviesStore to display movies:
\n
\n\n@Component({\n selector: 'app-movies',\n template: `\n <input\n type=\"text\"\n [(ngModel)]=\"studio\"\n [disabled]=\"store.loading()\"\n placeholder=\"Name of Studio\"\n />\n\n <ul>\n @for (movie of store.movies(); track movie.id) {\n <p>{{ movie.id }}: {{ movie.name }}</p>\n }\n </ul>\n `,\n standalone: true,\n imports: [FormsModule],\n})\nexport class MoviesComponent {\n protected studio = signal('');\n protected readonly store = inject(MoviesStore);\n\n constructor() {\n this.store.load(this.studio);\n }\n}\n\n\n
Native Mocking
\n
\n\nit('should show movies (native Jest)', () => {\n const load = jest.fn<void, [Signal<string>]>();\n\n const moviesStore = {\n movies: signal(new Array<Movie>()),\n loading: signal(false),\n load,\n };\n\n TestBed.configureTestingModule({\n imports: [MoviesComponent],\n providers: [\n {\n provide: MoviesStore,\n useValue: moviesStore,\n },\n ],\n });\n\n const fixture = TestBed.createComponent(MoviesComponent);\n fixture.autoDetectChanges(true);\n\n const studio = load.mock.calls[0][0];\n const input: HTMLInputElement = fixture.debugElement.query(By.css('input')).nativeElement;\n\n expect(studio()).toBe('');\n\n input.value = 'Warner Bros';\n input.dispatchEvent(new Event('input'));\n expect(studio()).toBe('Warner Bros');\n\n moviesStore.movies.set([\n { id: 1, name: 'Harry Potter' },\n { id: 2, name: 'The Dark Knight' },\n ]);\n fixture.detectChanges();\n\n const movieNames = fixture.debugElement.queryAll(By.css('p')).map((el) =>\n el.nativeElement.textContent\n );\n expect(movieNames).toEqual(['1: Harry Potter', '2: The Dark Knight']);\n});\n\n\n
The test mocks only the properties and methods used by the component in the specific test. Even if a SignalStore contains additional methods, it is not necessary to mock all of them.
\n
\"Partial Mocking\" via Spies
\n
Partial mocking can be used to mock only the load method. This approach allows computed properties to function correctly without requiring them to be mocked.
\n
\n\nit('should show movies (spy)', () => {\n TestBed.configureTestingModule({\n imports: [MoviesComponent],\n providers: [\n {\n provide: MoviesService,\n useValue: {},\n },\n ],\n });\n\n const moviesStore = TestBed.inject(MoviesStore);\n const loadSpy = jest.spyOn(moviesStore, 'load');\n const fixture = TestBed.createComponent(MoviesComponent);\n\n fixture.autoDetectChanges(true);\n\n const studio = loadSpy.mock.calls[0][0];\n if (studio instanceof Observable || typeof studio === 'string') {\n throw new Error('Expected signal');\n }\n\n const input: HTMLInputElement = fixture.debugElement.query(By.css('input')).nativeElement;\n\n expect(studio()).toBe('');\n\n input.value = 'Warner Bros';\n input.dispatchEvent(new Event('input'));\n expect(studio()).toBe('Warner Bros');\n\n patchState(moviesStore, {\n movies: [\n { id: 1, name: 'Harry Potter' },\n { id: 2, name: 'The Dark Knight' },\n ],\n });\n\n fixture.detectChanges();\n\n const movies = fixture.debugElement.queryAll(By.css('p')).map((el) =>\n el.nativeElement.textContent\n );\n expect(movies).toEqual(['1: Harry Potter', '2: The Dark Knight']);\n});\n\n\n
This version requires the MoviesStore state to be unprotected.
\n
Integration Tests
\n
Services attached to a component are often simple, and writing unit tests for them may not always be necessary, particularly when considering the returned value and maintenance costs. In such cases, it is more effective to test the services together with the component as a whole. This type of testing is commonly referred to as integration testing.
\n
The same applies to the SignalStore. If the SignalStore, such as the MoviesStore, is relatively simple, a single test can cover both the MoviesComponent and the MoviesStore. However, the HttpClient must still be replaced with a test double.
\n
\n\nit('should show movies with MoviesStore', async () => {\n const fixture = TestBed.configureTestingModule({\n imports: [MoviesComponent],\n providers: [provideHttpClient(), provideHttpClientTesting()],\n }).createComponent(MoviesComponent);\n\n const ctrl = TestBed.inject(HttpTestingController);\n\n fixture.autoDetectChanges(true);\n\n const input: HTMLInputElement = fixture.debugElement.query(\n By.css('input')\n ).nativeElement;\n input.value = 'Warner Bros';\n input.dispatchEvent(new Event('input'));\n\n\n ctrl.expectOne('https://movies.com/studios?query=Warner%20Bros').flush(\n [\n {id: 1, name: 'Harry Potter'},\n {id: 2, name: 'The Dark Knight'},\n ]\n )\n await fixture.whenStable()\n\n const movies = fixture.debugElement.queryAll(By.css('p')).map((el) =>\n el.nativeElement.textContent\n );\n expect(movies).toEqual(['1: Harry Potter', '2: The Dark Knight']);\n ctrl.verify();\n});\n\n\n
This test assumes that the MoviesService sends a request.
\n
Testing Custom Extensions
\n
An extension is responsible for playing a movie and tracking the duration of viewership. The extension provides play and stop methods, along with a Signal containing the movie's ID and the time spent watching it.
\n
\n\ntype PlayTrackingState = {\n _currentId: number;\n _status: 'playing' | 'stopped';\n _startedAt: Date | undefined;\n trackedData: Record<number, number>;\n};\n\nconst initialState: PlayTrackingState = {\n _currentId: 0,\n _status: 'stopped',\n _startedAt: undefined,\n trackedData: {},\n};\n\nexport const withPlayTracking = () =>\n signalStoreFeature(\n withState(initialState),\n withMethods((store) => {\n const stop = () => {\n const startedAt = store._startedAt();\n if (!startedAt || store._status() === 'stopped') {\n return;\n }\n\n const timeSpent = new Date().getTime() - startedAt.getTime();\n const alreadySpent = store.trackedData()[store._currentId()] ?? 0;\n patchState(store, (state) => ({\n _currentId: 0,\n _status: 'stopped' as const,\n trackedData: { ...state.trackedData, [state._currentId]: alreadySpent + timeSpent },\n }));\n };\n\n return {\n play(id: number) {\n stop();\n patchState(store, {\n _currentId: id,\n _status: 'playing',\n _startedAt: new Date(),\n });\n },\n stop,\n };\n })\n );\n\n\n
There are two options for testing this extension: in combination with the MoviesStore or in isolation.
\n
When tested with the MoviesStore, the same approach as in previous examples is followed.
\n
To test the extension in isolation, an artificial \"Wrapper\" SignalStore is created. The test process remains straightforward.
\n
\n\ndescribe('withTrackedPlay', () => {\n const TrackedPlayStore = signalStore({ providedIn: 'root' }, withPlayTracking());\n\n it('should track movies', fakeAsync(() => {\n const store = TestBed.inject(TrackedPlayStore);\n\n store.play(1);\n tick(1000);\n\n store.stop();\n store.play(2);\n tick(1000);\n\n store.play(3);\n tick(1000);\n\n store.play(1);\n tick(1000);\n store.stop();\n\n expect(store.trackedData()).toEqual({ 1: 2000, 2: 1000, 3: 1000 });\n }))\n});\n\n\n\n
\n
Testing
\n
A SignalStore is a straightforward Angular service, and the same testing techniques applied to other services also apply to SignalStore. This guide provides examples for common testing scenarios.
\n
One of the challenges in testing is managing asynchronous tasks and mocking dependencies. Although the examples use Jest, the same principles are applicable to other testing frameworks.
\n
There are two primary scenarios for testing:
\n
\n- Testing the SignalStore itself.
\n- Testing a component or service that utilizes the SignalStore.
\n
\n
In the first scenario, the dependencies of the SignalStore should be mocked, while in the second scenario, the SignalStore itself needs to be mocked.
\n
\n
When testing the SignalStore, interaction should occur through its public API, as any component or service would.
\n
A key concern in testing is maintainability. The more tests are coupled to internal implementations, the more frequently they are likely to break. Public APIs are generally more stable and less prone to change.
\n
For example, when testing the store in a loading state, avoid directly setting the loading property. Instead, trigger a loading method and assert against an exposed computed property or slice. This approach reduces dependency on internal implementations, such as properties set during the loading state.
\n
From this perspective, private properties or methods of the SignalStore should not be accessed. Additionally, avoid running patchState if the state is protected.
\n
\n
The SignalStore is a function that returns a class, allowing tests to instantiate the class and test it without using TestBed.
\n
However, in practice, TestBed is typically used due to its numerous advantages, such as the ability to mock dependencies and trigger the execution of effects.
\n
Additionally, key features of the SignalStore do not function properly if they do not run in an injection context. Examples include rxMethod, the use of inject within withMethods(), and withHooks().
\n
\n
Note: Using the TestBed is also the recommendation of the Angular team.
\n
\n
Testing the SignalStore
\n
The following example demonstrates the testing of a SignalStore:
\n
Globally provided
\n
\n\nimport { signalStore, withState } from '@ngrx/signals';\n\ntype Movie = {\n id: number;\n name: string;\n};\n\ntype State = { movies: Movie[] };\n\nexport const MoviesStore = signalStore(\n { providedIn: 'root' },\n withState<State>({\n movies: [\n { id: 1, name: 'A New Hope' },\n { id: 2, name: 'Into Darkness' },\n { id: 3, name: 'The Lord of the Rings' },\n ],\n })\n);\n\n\n
The TestBed instantiates the MoviesStore, enabling immediate testing.
\n
\n\nimport { MoviesStore } from './movies-store';\nimport { TestBed } from '@angular/core/testing';\n\ndescribe('MoviesStore', () => {\n it('should verify that three movies are available', () => {\n const store = TestBed.inject(MoviesStore);\n\n expect(store.movies()).toHaveLength(3);\n });\n});\n\n\n
Locally Provided
\n
This is possible due to the MoviesStore being provided globally. For locally provided stores, some adjustments to the test are required.
\n
\n\nexport const MoviesStore = signalStore(\n withState({\n movies: [\n // ... entries\n ],\n })\n);\n\n\n
The required addition is that the internal TestingModule must provide the MoviesStore.
\n
\n\nimport { MoviesStore } from './movies.store';\n\ndescribe('MoviesStore', () => {\n it('should verify that three movies are available', () => {\n TestBed.configureTestingModule({\n providers: [MoviesStore],\n });\n\n const store = TestBed.inject(MoviesStore);\n\n expect(store.movies()).toHaveLength(3);\n });\n});\n\n\n
\n
Testing derived values of withComputed is also straightforward.
\n
\n\nexport const MoviesStore = signalStore(\n withState({\n movies: [\n // ... entries\n ],\n }),\n withComputed((state) => ({\n moviesCount: computed(() => state.movies().length),\n }))\n);\n\n\n
\n\nimport { MoviesStore } from './movies.store';\n\ndescribe('MoviesStore', () => {\n it('should verify that three movies are available', () => {\n const store = TestBed.inject(MoviesStore);\n\n expect(store.moviesCount()).toBe(3);\n });\n});\n\n\n
withMethods, Dependency Injection, and Asynchronous Tasks
\n
A loading method asynchronously retrieves movies by studio in this scenario.
\n
\n\nimport { signalStore, withState } from '@ngrx/signals';\n\ntype State = { studio: string; movies: Movie[]; loading: boolean };\n\nexport const MoviesStore = signalStore(\n withState<State>({\n studio: '',\n movies: [],\n loading: false,\n }),\n withMethods((store) => {\n const moviesService = store.inject(MoviesService);\n\n return {\n async load(studio: string) {\n this.patchState({ loading: true });\n const movies = await moviesService.loadMovies(studio);\n this.patchState(store, { studio, movies, loading: false });\n },\n };\n })\n);\n\n\n
The MoviesService is mocked in the test, with the implementation returning the result as a Promise.
\n
\n\ndescribe('MoviesStore', () => {\n it('should load movies of Warner Bros', fakeAsync(() => {\n const moviesService = {\n load: () =>\n Promise.resolve([\n { id: 1, name: 'Harry Potter' },\n { id: 2, name: 'The Dark Knight' },\n ]),\n };\n\n TestBed.configureTestingModule({\n providers: [\n {\n provide: MoviesService,\n useValue: moviesService,\n },\n ],\n });\n\n const store = TestBed.inject(MoviesStore);\n store.load('Warner Bros');\n expect(store.loading()).toBe(true);\n \n tick();\n\n expect(store.moviesCount()).toBe(2);\n expect(store.loading()).toBe(false);\n }));\n});\n\n\n
\n
Note: Manually mocking dependencies is not required. Libraries such as ng-mocks, @testing-library/angular, and [jest|jasmine]-auto-spies can be used for this purpose.
\n
\n
\n
The load method is created using rxMethod to accommodate a component that provides an input field for the studio and initiates loading as soon as a user types in a name.
\n
In this scenario, the MovieService returns an Observable<Movie[]> instead of a Promise<Movie[]>.
\n
\n\nexport const MoviesStore = signalStore(\n // ... code omitted\n withMethods((store, moviesService = inject(MoviesService)) => ({\n load: rxMethod<string>(\n pipe(\n tap(() => patchState(store, { loading: true })),\n switchMap((studio) =>\n moviesService.load(studio).pipe(\n tapResponse({\n next: (movies) =>\n patchState(store, { movies, loading: false }),\n error: console.error,\n })\n )\n )\n )\n ),\n }))\n);\n\n\n
Since rxMethod accepts a string as a parameter, the previous test remains valid.
\n
An additional focus in testing is ensuring proper handling of race conditions, which is why switchMap is used.
\n
The parameter's type can also be Signal<number> or Observable<number>, in addition to number.
\n
With Observables
\n
The goal is to test whether the load method properly handles the scenario where a new studio name is entered before or after the previous request has completed.
\n
\n\ndescribe('MoviesStore', () => {\n // ... beforeEach and afterEach omitted\n\n const setup = () => {\n const moviesService = {\n load: jest.fn((studio: string) =>\n of([\n studio === 'Warner Bros'\n ? { id: 1, name: 'Harry Potter' }\n : { id: 2, name: 'Jurassic Park' }\n ]).pipe(delay(100))\n ),\n };\n\n TestBed.configureTestingModule({\n providers: [\n {\n provide: MoviesService,\n useValue: moviesService,\n },\n ],\n });\n\n return TestBed.inject(MoviesStore);\n };\n\n it('should load two times', fakeAsync(() => {\n const store = setup();\n\n const studio$ = new Subject<string>();\n store.load(studio$);\n studio$.next('Warner Bros');\n\n tick(100);\n expect(store.movies()).toEqual([{ id: 1, name: 'Harry Potter' }]);\n\n studio$.next('Universal');\n tick(100);\n expect(store.movies()).toEqual([{ id: 2, name: 'Jurassic Park' }]);\n }));\n\n it('should cancel a running request when a new one is made', fakeAsync(() => {\n const store = setup();\n\n const studio$ = new Subject<string>();\n store.load(studio$);\n studio$.next('Warner Bros');\n\n tick(50);\n studio$.next('Universal');\n\n tick(50);\n expect(store.movies()).toEqual([]);\n expect(store.loading()).toBe(true);\n\n tick(50);\n expect(store.movies()).toEqual([{ id: 2, name: 'Jurassic Park' }]);\n expect(store.loading()).toBe(false);\n }));\n});\n\n\n
By utilizing the testing framework's function to manage time, both scenarios can be verified.
\n
The test also employs a setup function to prevent code duplication, a common pattern in testing and an alternative to the beforeEach function. In this case, each test can choose whether to use the setup function or not.
\n
With Signals
\n
Testing both scenarios with a Signal type as input is similar to testing with Observables.
\n
This similarity arises primarily due to the asynchronous tasks involved.
\n
\n\ndescribe('MoviesStore', () => {\n // ... setup omitted\n\n it('should test two sequential loads with a Signal', fakeAsync(() => {\n const store = setup();\n const studio = signal('Warner Bros');\n store.load(studio);\n\n tick(100);\n expect(store.movies()).toEqual([{ id: 1, name: 'Harry Potter' }]);\n\n studio.set('Universal');\n tick(100);\n expect(store.movies()).toEqual([{ id: 2, name: 'Jurassic Park' }]);\n }));\n\n it('should cancel a running request when a new one is made via a Signal', fakeAsync(() => {\n const store = setup();\n const studio = signal('Warner Bros');\n\n effect(() => {\n console.log(studio());\n });\n store.load(studio);\n\n tick(50);\n\n studio.set('Universal');\n tick(50);\n expect(store.movies()).toEqual([]);\n expect(store.loading()).toBe(true);\n\n tick(50);\n expect(store.movies()).toEqual([{ id: 2, name: 'Jurassic Park' }]);\n expect(store.loading()).toBe(false);\n }));\n});\n\n\n
It is important to account for the glitch-free effect when using Signals. The rxMethod relies on effect, which may need to be triggered manually through TestBed.flushEffects().
\n
If the mocked MovieService operates synchronously, the following test fails unless TestBed.flushEffects() is called.
\n
\n\ndescribe('MoviesStore', () => {\n // ... beforeEach, and afterEach omitted\n\n it('should depend on flushEffects because of synchronous execution', () => {\n const moviesService = {\n load: jest.fn((studio: string) =>\n of([\n studio === 'Warner Bros'\n ? { id: 1, name: 'Harry Potter' }\n : { id: 2, name: 'Jurassic Park' }\n ])\n ),\n };\n\n TestBed.configureTestingModule({\n providers: [\n {\n provide: MoviesService,\n useValue: moviesService,\n },\n ],\n });\n\n const store = TestBed.inject(MoviesStore);\n const studio = signal('Warner Bros');\n store.load(studio);\n TestBed.flushEffects(); // required\n expect(store.movies()).toEqual([{ id: 1, name: 'Harry Potter' }]);\n\n studio.set('Universal');\n TestBed.flushEffects(); // required\n expect(store.movies()).toEqual([{ id: 2, name: 'Jurassic Park' }]);\n });\n});\n\n\n
Mocking the SignalStore
\n
What applies to testing the SignalStore also applies to mocking it. The SignalStore functions like any other service, meaning it can be mocked using the same tools and techniques applied to other services.
\n
The MovieComponent utilizes the MoviesStore to display movies:
\n
\n\n@Component({\n selector: 'app-movies',\n template: `\n <input\n type=\"text\"\n [(ngModel)]=\"studio\"\n [disabled]=\"store.loading()\"\n placeholder=\"Name of Studio\"\n />\n\n <ul>\n @for (movie of store.movies(); track movie.id) {\n <p>{{ movie.id }}: {{ movie.name }}</p>\n }\n </ul>\n `,\n imports: [FormsModule],\n})\nexport class MoviesComponent {\n protected studio = signal('');\n protected readonly store = inject(MoviesStore);\n\n constructor() {\n this.store.load(this.studio);\n }\n}\n\n\n
Native Mocking
\n
\n\nit('should show movies (native Jest)', () => {\n const load = jest.fn<void, [Signal<string>]>();\n\n const moviesStore = {\n movies: signal(new Array<Movie>()),\n loading: signal(false),\n load,\n };\n\n TestBed.configureTestingModule({\n imports: [MoviesComponent],\n providers: [\n {\n provide: MoviesStore,\n useValue: moviesStore,\n },\n ],\n });\n\n const fixture = TestBed.createComponent(MoviesComponent);\n fixture.autoDetectChanges(true);\n\n const studio = load.mock.calls[0][0];\n const input: HTMLInputElement = fixture.debugElement.query(By.css('input')).nativeElement;\n\n expect(studio()).toBe('');\n\n input.value = 'Warner Bros';\n input.dispatchEvent(new Event('input'));\n expect(studio()).toBe('Warner Bros');\n\n moviesStore.movies.set([\n { id: 1, name: 'Harry Potter' },\n { id: 2, name: 'The Dark Knight' },\n ]);\n fixture.detectChanges();\n\n const movieNames = fixture.debugElement.queryAll(By.css('p')).map((el) =>\n el.nativeElement.textContent\n );\n expect(movieNames).toEqual(['1: Harry Potter', '2: The Dark Knight']);\n});\n\n\n
The test mocks only the properties and methods used by the component in the specific test. Even if a SignalStore contains additional methods, it is not necessary to mock all of them.
\n
\"Partial Mocking\" via Spies
\n
Partial mocking can be used to mock only the load method. This approach allows computed properties to function correctly without requiring them to be mocked.
\n
\n\nit('should show movies (spy)', () => {\n TestBed.configureTestingModule({\n imports: [MoviesComponent],\n providers: [\n {\n provide: MoviesService,\n useValue: {},\n },\n ],\n });\n\n const moviesStore = TestBed.inject(MoviesStore);\n const loadSpy = jest.spyOn(moviesStore, 'load');\n const fixture = TestBed.createComponent(MoviesComponent);\n\n fixture.autoDetectChanges(true);\n\n const studio = loadSpy.mock.calls[0][0];\n if (studio instanceof Observable || typeof studio === 'string') {\n throw new Error('Expected signal');\n }\n\n const input: HTMLInputElement = fixture.debugElement.query(By.css('input')).nativeElement;\n\n expect(studio()).toBe('');\n\n input.value = 'Warner Bros';\n input.dispatchEvent(new Event('input'));\n expect(studio()).toBe('Warner Bros');\n\n patchState(moviesStore, {\n movies: [\n { id: 1, name: 'Harry Potter' },\n { id: 2, name: 'The Dark Knight' },\n ],\n });\n\n fixture.detectChanges();\n\n const movies = fixture.debugElement.queryAll(By.css('p')).map((el) =>\n el.nativeElement.textContent\n );\n expect(movies).toEqual(['1: Harry Potter', '2: The Dark Knight']);\n});\n\n\n
This version requires the MoviesStore state to be unprotected.
\n
Integration Tests
\n
Services attached to a component are often simple, and writing unit tests for them may not always be necessary, particularly when considering the returned value and maintenance costs. In such cases, it is more effective to test the services together with the component as a whole. This type of testing is commonly referred to as integration testing.
\n
The same applies to the SignalStore. If the SignalStore, such as the MoviesStore, is relatively simple, a single test can cover both the MoviesComponent and the MoviesStore. However, the HttpClient must still be replaced with a test double.
\n
\n\nit('should show movies with MoviesStore', async () => {\n const fixture = TestBed.configureTestingModule({\n imports: [MoviesComponent],\n providers: [provideHttpClient(), provideHttpClientTesting()],\n }).createComponent(MoviesComponent);\n\n const ctrl = TestBed.inject(HttpTestingController);\n\n fixture.autoDetectChanges(true);\n\n const input: HTMLInputElement = fixture.debugElement.query(\n By.css('input')\n ).nativeElement;\n input.value = 'Warner Bros';\n input.dispatchEvent(new Event('input'));\n\n\n ctrl.expectOne('https://movies.com/studios?query=Warner%20Bros').flush(\n [\n {id: 1, name: 'Harry Potter'},\n {id: 2, name: 'The Dark Knight'},\n ]\n )\n await fixture.whenStable()\n\n const movies = fixture.debugElement.queryAll(By.css('p')).map((el) =>\n el.nativeElement.textContent\n );\n expect(movies).toEqual(['1: Harry Potter', '2: The Dark Knight']);\n ctrl.verify();\n});\n\n\n
This test assumes that the MoviesService sends a request.
\n
Testing Custom Extensions
\n
An extension is responsible for playing a movie and tracking the duration of viewership. The extension provides play and stop methods, along with a Signal containing the movie's ID and the time spent watching it.
\n
\n\ntype PlayTrackingState = {\n _currentId: number;\n _status: 'playing' | 'stopped';\n _startedAt: Date | undefined;\n trackedData: Record<number, number>;\n};\n\nconst initialState: PlayTrackingState = {\n _currentId: 0,\n _status: 'stopped',\n _startedAt: undefined,\n trackedData: {},\n};\n\nexport const withPlayTracking = () =>\n signalStoreFeature(\n withState(initialState),\n withMethods((store) => {\n const stop = () => {\n const startedAt = store._startedAt();\n if (!startedAt || store._status() === 'stopped') {\n return;\n }\n\n const timeSpent = new Date().getTime() - startedAt.getTime();\n const alreadySpent = store.trackedData()[store._currentId()] ?? 0;\n patchState(store, (state) => ({\n _currentId: 0,\n _status: 'stopped' as const,\n trackedData: { ...state.trackedData, [state._currentId]: alreadySpent + timeSpent },\n }));\n };\n\n return {\n play(id: number) {\n stop();\n patchState(store, {\n _currentId: id,\n _status: 'playing',\n _startedAt: new Date(),\n });\n },\n stop,\n };\n })\n );\n\n\n
There are two options for testing this extension: in combination with the MoviesStore or in isolation.
\n
When tested with the MoviesStore, the same approach as in previous examples is followed.
\n
To test the extension in isolation, an artificial \"Wrapper\" SignalStore is created. The test process remains straightforward.
\n
\n\ndescribe('withTrackedPlay', () => {\n const TrackedPlayStore = signalStore({ providedIn: 'root' }, withPlayTracking());\n\n it('should track movies', fakeAsync(() => {\n const store = TestBed.inject(TrackedPlayStore);\n\n store.play(1);\n tick(1000);\n\n store.stop();\n store.play(2);\n tick(1000);\n\n store.play(3);\n tick(1000);\n\n store.play(1);\n tick(1000);\n store.stop();\n\n expect(store.trackedData()).toEqual({ 1: 2000, 2: 1000, 3: 1000 });\n }))\n});\n\n\n\n