{"id":7292,"date":"2023-07-05T13:30:50","date_gmt":"2023-07-05T11:30:50","guid":{"rendered":"https:\/\/www.angulararchitects.io\/?p=7292"},"modified":"2023-12-08T13:07:03","modified_gmt":"2023-12-08T12:07:03","slug":"the-new-ngrx-signal-store-for-angular-2-1-flavors","status":"publish","type":"post","link":"https:\/\/www.angulararchitects.io\/en\/blog\/the-new-ngrx-signal-store-for-angular-2-1-flavors\/","title":{"rendered":"The new NGRX Signal Store for Angular: 3+n Flavors"},"content":{"rendered":"
\n\t\t\t\n\t\n\t\n\t\t

\n\t\t\tThis is post 1 of 7 in the series “NGRX Signal Store”<\/em>\t\t<\/p>\n\t\t\t<\/label>\n\n\t\t\t

\n\t\t\t
    \n\t\t\t\t\t\t\t\t\t
  1. The new NGRX Signal Store for Angular: 3+n Flavors<\/span><\/li>\n\t\t\t\t\t\t\t\t\t
  2. Smarter, Not Harder: Simplifying your Application With NGRX Signal Store and Custom Features<\/a><\/li>\n\t\t\t\t\t\t\t\t\t
  3. NGRX Signal Store Deep Dive: Flexible and Type-Safe Custom Extensions<\/a><\/li>\n\t\t\t\t\t\t\t\t\t
  4. The NGRX Signal Store and Your Architecture<\/a><\/li>\n\t\t\t\t\t\t\t\t\t
  5. Using Angular’s Resource API with the NGRX Signal Store<\/a><\/li>\n\t\t\t\t\t\t\t\t\t
  6. The new Event API for the NgRx Signal Store: A Quantum of Redux<\/a><\/li>\n\t\t\t\t\t\t\t\t\t
  7. Full-Cycle Reactivity in Angular: Signal Forms, Signal Store, Resources, & Mutation API<\/a><\/li>\n\t\t\t\t\t\t\t<\/ol>\n\t\t<\/div>\n\t<\/div>\n

    Since the advent of Signals, the NGRX team has been working on a store that leverages this new reactive building block. This new NGRX Signal Store was released with NGRX 17, is fully Signal-based, and highly extensible. <\/p>\n

    This article shows how to incorporate it in your application. For this, it shows up 3+1 different flavors of using it.<\/p>\n

    \ud83d\udcc2 Source Code<\/a> <\/p>\n

    Getting the Package<\/h2>\n

    To install the Signal Store, you just need to add the package @ngrx\/signals<\/code> to your application:<\/p>\n

    npm i @ngrx\/signals<\/code><\/pre>\n
    Flavor 1: Lightweight with signalState<\/h2>\n
    \ud83d\udd00 Branch:<\/em> arc-signal-store<\/code><\/p>\n
    A very lightweight way of managing Signals with the Signal Store is its signalState<\/code> function (not to be confused with the signalStore<\/code> function). It creates a simple container for managing the passed state using Signals. This container is represented by the type SignalState<\/code>:<\/p>\n
    @Injectable({ providedIn: 'root' })\n\nimport { signalState } from '@ngrx\/signals';\n\n[...]\n\nexport class FlightBookingFacade {\n\n    [...]\n\n    private state = signalState({\n        from: 'Paris',\n        to: 'London',\n        preferences: {\n          directConnection: false,\n          maxPrice: 350,\n        },        \n        flights: [] as Flight[],\n        basket: {} as Record<number, boolean>,\n    });\n\n    \/\/ fetch read-only signals\n    flights = this.state.flights;\n    from = this.state.from;\n    to = this.state.to;\n    basket = this.state.basket;\n\n  [...]\n}<\/code><\/pre>\n
    Each top-level state property gets its own Signal. These properties are retrieved as read-only Signals, ensuring a separation between reading and writing: Consumers using the Signals can just read their values. For updating the state, the service encapsulating the state provides methods (see below). This ensures that the state can only be updated in a well-defined manner.<\/p>\n
    Also, nested objects like the one provided by the preferences<\/code> property above result in nested signals. Hence, one can retrieve the whole preferences<\/code> object as a Signal but also its properties:<\/p>\n
    const ps = this.state.preferences();\nconst direct = this.state.preferences.directConnection();<\/code><\/pre>\n
    Currently, this isn't implemented for arrays, as Angular's envisioned Signal Components will solve this use case by creating a Signal for each iterated item.  <\/p>\n
    Selecting and Computing Signals<\/h3>\n
    As the Signal Store provides the state as Signals, we can directly use Angular's computed<\/code> function:<\/p>\n
    selected = computed(() =>\n  this.flights().filter((f) => this.basket()[f.id])\n);<\/code><\/pre>\n
    Here, computed<\/code> serves the same purpose as Selectors in the Redux-based NGRX Store: It
    \nenables us to calculate different state representations for different use cases. These so-called View Models are only recomputed when at least one of the underlying signals changes.<\/p>\n
    Updating State<\/h3>\n
    For updating the SignalState<\/code>, Signal Store provides us with a patchState<\/code> function:<\/p>\n
    import { patchState } from '@ngrx\/signals';\n\n[...]\n\nupdateCriteria(from: string, to: string): void {\n  patchState(this.state, { from, to })\n}<\/code><\/pre>\n
    Here, we pass in the state container and a partial state. As an alternative, one can pass a function taking the current state and transforming it to the new state:<\/p>\n
    updateBasket(id: number, selected: boolean): void {\n  patchState(this.state, state => ({\n    basket: {\n      ...state.basket,\n      [id]: selected,\n    },\n  }));\n}<\/code><\/pre>\n
    Side Effects<\/h2>\n
    Besides updating the state, methods can also trigger side effects like loading and saving objects:<\/p>\n
    async load() {\n  if (!this.from() || !this.to()) return;\n\n  const flights = await this.flightService.findPromise(\n    this.from(),\n    this.to()\n  );\n\n  patchState(this.state, { flights });\n}<\/code><\/pre>\n
    Decoupling Intention from Execution<\/h3>\n
    Sometimes, the caller of patchState<\/code> only knows that some state needs to be updated without knowing where it's located. For such cases, you can provide Updaters. Updaters are just functions taking a current state and returning an updated version of it:<\/p>\n
    type BasketSlice = { basket: Record<number, boolean> };\ntype BasketUpdateter = (state: BasketSlice) => BasketSlice;\n\nexport function updateBasket(flightId: number, selected: boolean): BasketUpdateter {\n  return (state) => ({\n    ...state,\n    basket: {\n      ...state.basket,\n      [flightId]: selected,\n    },\n  });\n}<\/code><\/pre>\n
    It's also fine to just return a partial state. It will be patched over the current state:<\/p>\n
    type BasketSlice = { basket: Record<number, boolean> };\ntype BasketUpdateter = (state: BasketSlice) => BasketSlice;\n\nexport function updateBasket(flightId: number, selected: boolean): BasketUpdateter {\n  return (state) => ({\n    basket: {\n      ...state.basket,\n      [flightId]: selected,\n    },\n  });\n}<\/code><\/pre>\n
    If you don't need to project the current state, just returning a partial state is fine too. In this case, you can skip the inner function:<\/p>\n
    export function updateFlights(flights: Flight[]) {\n  return { flights };\n}<\/code><\/pre>\n
    Updater can be defined in the Store<\/code>'s (signalState<\/code>'s) "sovereign territory". For the consumer, it is just a black box:<\/p>\n
    patchState(updateBasket(id, selected))<\/code><\/pre>\n
    Passing an Updater to patchState<\/code> expresses an intention. This is similar to dispatching an Action in the classic NGRX store. However, other than with Redux, no eventing is involved, and we cannot prevent the caller from directly passing their own Updaters. For the latter reason, I'm hiding the SignalStore<\/code> behind a facade.<\/p>\n
    More: Angular Architecture Workshop (online, interactive, advanced)<\/h3>\n
    Become an expert for enterprise-scale and maintainable Angular applications with our Angular Architecture workshop!<\/a>\"\"<\/p>\n
    All Details (English Workshop)<\/a> | All Details (German Workshop)<\/a>
    \n<\/p>\n
    Flavor 2: Powerful with signalStore<\/h2>\n
    \ud83d\udd00 Branch:<\/em> arc-signal-store-2<\/code><\/p>\n
    Similar to signalState<\/code>, the signalStore<\/code> function creates a container managing state with Signals. However, now, this container is a fully-fledged Store that not only comes with state Signals but also with computed Signals as well as methods for updating the state and for triggering side effects. Hence, there is less need for crafting a facade by hand, as shown above.<\/p>\n
    Technically, the Store is an Angular service that is composed of several pre-existing features:<\/p>\n
    export const FlightBookingStore = signalStore(\n  { providedIn: 'root' },\n  withState({\n    from: 'Paris',\n    to: 'London',\n    initialized: false,\n    flights: [] as Flight[],\n    basket: {} as Record<number, boolean>,\n  }),\n\n  \/\/ Activating further features\n  withComputed([...]),\n  withMethods([...]),\n  withHooks([...]),\n)<\/code><\/pre>\n
    In this case, the service is also registered in the root scope. When skipping { providedIn: 'root' }<\/code>, one needs to register the service by hand, e. g., by providing it when bootstrapping the application, within a router configuration, or on component level.<\/p>\n
    Selecting and Computing Signals<\/h3>\n
    The withComputed<\/code> feature takes the store with its state Signals and defines an object with calculated signals:<\/p>\n
    withComputed((store) => ({\n  selected: computed(() => store.flights().filter((f) => store.basket()[f.id])),\n  criteria: computed(() => ({ from: store.from(), to: store.to() })),\n})),<\/code><\/pre>\n
    The returned computed signals become part of the store. A more compact version might involve directly destructuring the passed store:<\/p>\n
    withComputed(({ flights, basket, from, to }) => ({\n  selected: selectSignal(() => flights().filter((f) => basket()[f.id])),\n  criteria: selectSignal(() => ({ from: from(), to: to() })),\n})),<\/code><\/pre>\n
    Methods for Updating State and Side Effects<\/h3>\n
    Similar to withComputed<\/code>, withMethods<\/code> also takes the store and returns an object with methods:<\/p>\n
    withMethods((state) => {\n  const { basket, flights, from, to, initialized } = state;\n  const flightService = inject(FlightService);\n\n  return {\n    updateCriteria: (from: string, to: string) => {\n      patchState(state, { from, to });\n    },\n    updateBasket: (flightId: number, selected: boolean) => {\n      patchState(state, {\n        basket: {\n          ...basket(),\n          [flightId]: selected,\n        },\n      });\n    },\n    delay: () => {\n      const currentFlights = flights();\n      const flight = currentFlights[0];\n\n      const date = addMinutes(flight.date, 15);\n      const updFlight = { ...flight, date };\n      const updFlights = [updFlight, ...currentFlights.slice(1)];\n\n      patchState(state, { flights: updFlights });\n    },\n    load: async () => {\n      if (!from() || !to()) return;\n      const flights = await flightService.findPromise(from(), to());\n      patchState(state, { flights });\n    }     \n  };\n}),<\/code><\/pre>\n
    withMethods<\/code> runs in an injection context and hence can use inject<\/code> to get hold of services. After withMethods<\/code> was executed, the retrieved methods are added to the store.<\/p>\n
    Consuming the Store<\/h3>\n
    From the caller's perspective, the store looks a lot like the facade shown above. We can inject it into a consuming component:<\/p>\n
    @Component([...])\nexport class FlightSearchComponent {\n  private store = inject(FlightBookingStore);\n\n  from = this.store.from;\n  to = this.store.to;\n  basket = this.store.basket;\n  flights = this.store.flights;\n  selected = this.store.selected;\n\n  async search() {\n    this.store.load();\n  }\n\n  delay(): void {\n    this.store.delay();\n  }\n\n  updateCriteria(from: string, to: string): void {\n    this.store.updateCriteria(from, to);\n  }\n\n  updateBasket(id: number, selected: boolean): void {\n    this.store.updateBasket(id, selected);\n  }\n}<\/code><\/pre>\n
    Hooks<\/h3>\n
    The function withHooks<\/code> provides another feature allowing to setup lifecycle hooks to run when the store is initialized or destroyed:<\/p>\n
    withHooks({\n  onInit({ load }) {\n    load()\n  },\n  onDestroy({ flights }) {\n    console.log('flights are destroyed now', flights());\n  },\n}),<\/code><\/pre>\n
    Both hooks get the store passed. One more time, by using destructuring, you can focus on a subset of the stores members.<\/p>\n
    rxMethod<\/h3>\n
    \ud83d\udd00 Branch:<\/em> arc-signal-store-rx<\/code><\/p>\n
    While Signals are easy to use, they are not a full replacement for RxJS. For leveraging RxJS and its powerful operators, the Signal Store provides a secondary entry point @ngrx\/signals\/rxjs-interop<\/code>, containing a function rxMethod<T><\/code>. It allows working with an Observable representing side-effects that automatically run when specific values change:<\/p>\n
    import { rxMethod } from '@ngrx\/signals\/rxjs-interop';\n\n[...]\n\nwithMethods(({ $update, basket, flights, from, to, initialized }) => {\n  const flightService = inject(FlightService);\n\n  return {\n    [...]\n    connectCriteria: rxMethod<Criteria>((c$) => c$.pipe(\n      filter(c => c.from.length >= 3 && c.to.length >= 3),\n      debounceTime(300),\n      switchMap((c) => flightService.find(c.from, c.to)),\n      tap(flights => patchState(state, { flights }))\n    ))\n  }\n});<\/code><\/pre>\n
    The type parameter T<\/code> defines the type the rxMethod<\/code> works on. While the rxMethod<\/code> receives an Obserable<T><\/code>, the caller can also pass an Observable<T><\/code>, a Signal<T><\/code>, or T<\/code> directly. In the latter two cases, the passed values are converted into an Observable.<\/p>\n
    After defining the rxMethod<\/code>, somewhere else in the application, e. g. in a hook or a regular method, you can call this effect:<\/p>\n
    withHooks({\n  onInit({ loadBy, criteria }) {\n    connectCriteria(criteria());\n  },\n})<\/code><\/pre>\n
    Here, the criteria Signal -- a computed signal -- is passed. Every time this Signal changes, the effect within connectCriteria<\/code> is re-executed.<\/p>\n
    Custom Features - The Road Towards Further Flavors<\/h2>\n
    \ud83d\udd00 Branch:<\/em> arc-signal-store-custom<\/code><\/p>\n
    Besides configuring the Store with baked-in features, everyone can write their own features to automate repeating tasks. The playground provided by Marko Stanimirovi\u0107<\/a>, the NGRX contributor behind the Signal Store, contains several examples of such features.<\/p>\n
    One of the examples found in this repository is a CallState feature<\/a> defining a state property informing about the state of the current HTTP call:<\/p>\n
    export type CallState = 'init' | 'loading' | 'loaded' | { error: string };<\/code><\/pre>\n
    In this section, I'm using this example to explain how to provide custom features.<\/p>\n
    Defining Custom Features<\/h3>\n
    A feature is usually created by calling signalStoreFeature<\/code>. This function constructs a new feature on top of existing ones.<\/p>\n
    \/\/ Taken from: https:\/\/github.com\/markostanimirovic\/ngrx-signal-store-playground\/blob\/main\/src\/app\/shared\/call-state.feature.ts\n\nimport { computed } from '@angular\/core';\nimport {\n  signalStoreFeature,\n  withComputed,\n  withState,\n} from '@ngrx\/signals';\n\nexport type CallState = 'init' | 'loading' | 'loaded' | { error: string };\n\nexport function withCallState() {\n  return signalStoreFeature(\n    withState<{ callState: CallState }>({ callState: 'init' }),\n    withComputed(({ callState }) => ({\n      loading: computed(() => callState() === 'loading'),\n      loaded: computed(() => callState() === 'loaded'),\n      error: computed(() => {\n        const state = callState();\n        return typeof state === 'object' ? state.error : null\n      }),\n    }))\n  );\n}<\/code><\/pre>\n
    For the state properties added by the feature, one can provide Updaters<\/code>:<\/p>\n
    export function setLoading(): { callState: CallState } {\n  return { callState: 'loading' };\n}\n\nexport function setLoaded(): { callState: CallState } {\n  return { callState: 'loaded' };\n}\n\nexport function setError(error: string): { callState: CallState } {\n  return { callState: { error } };\n}<\/code><\/pre>\n
    Updaters allows the consumer to modify the feature state without actually knowing how it's structured. <\/p>\n
    Using Custom Features<\/h3>\n
    For using Custom Features, just call the provided factory when setting up the store:<\/p>\n
    export const FlightBookingStore = signalStore(\n  { providedIn: 'root' },\n  withState({ [...] }),\n\n  \/\/ Add feature:\n  withCallState(),\n  [...]\n\n  withMethods([...])\n  [...]\n);<\/code><\/pre>\n
    The provided properties, methods, and Updaters can be used in the Store's methods:<\/p>\n
    load: async () => {\n  if (!from() || !to()) return;\n\n  \/\/ Setting the callState via an Updater\n  patchState(state, setLoading());\n\n  const flights = await flightService.findPromise(from(), to());\n  patchState(state, { flights });\n\n  \/\/ Setting the callState via an Updater\n  patchState(state, setLoaded());\n},<\/code><\/pre>\n
    The consumer of the store sees the properties provided by the feature too:<\/p>\n
    private store = inject(FlightBookingStore);\n\nflights = this.store.flightEntities;\nloading = this.store.loading;<\/code><\/pre>\n
    As each feature is transforming the Store's properties and methods, make sure to call them in the right order. If we assume that methods registered with withMethods<\/code> use the CallState<\/code>, withCallState<\/code> has to be called before withMethods<\/code>.<\/p>\n
    Flavor 3: Built-in Features like Entity Management<\/h2>\n
    \ud83d\udd00 Branch:<\/em> arc-signal-store-entities<\/code><\/p>\n
    The NGRX Signal Store already comes with a convenient extension for managing entities. It can be found in the secondary entry point @ngrx\/signals\/entities<\/code> and provides data structures for entities but also several Updaters, e. g., for inserting entities or for updating a single entity by id.<\/p>\n
    To setup entity management, just call the withEntities<\/code> function:<\/p>\n
    import { withEntities } from '@ngrx\/signals\/entities';\n\nconst BooksStore = signalStore(\n  [...]\n\n  \/\/ Defining an Entity\n  withEntities({ entity: type<Flight>(), collection: 'flight' }),\n\n  \/\/ withEntities created a flightEntities signal for us:\n  withComputed(({ flightEntities, basket, from, to }) => ({\n    selected: computed(() => flightEntities().filter((f) => basket()[f.id])),\n    criteria: computed(() => ({ from: from(), to: to() })),\n  })),\n\n  withMethods((state) => {\n    const { basket, flightEntities, from, to, initialized } = state;\n    const flightService = inject(FlightService);\n\n    return {\n      [...],\n\n      load: async () => {\n        if (!from() || !to()) return;\n        patchState(state, setLoading());\n\n        const flights = await flightService.findPromise(from(), to());\n\n        \/\/ Updating entities with out-of-the-box setAllEntities Updater\n        patchState(state, setAllEntities(flights, { collection: 'flight' }));\n        patchState(state, setLoaded());\n      },\n\n      [...],\n    };\n  }),\n);<\/code><\/pre>\n
    The passed collection name prevents naming conflicts. In our case, the collection is called flight<\/code>, and hence the feature creates several properties beginning with flight<\/code>, e.g., flightEntities<\/code>.<\/p>\n
    There is quite an amount of ready-to-use Updaters: <\/p>\n