In NGXS, how do ctx.setState and ctx.patchState differ, and when should an action handler use state operators such as patch and updateItem instead?

## Two ways to write from an action handler In NGXS every `@Action` handler receives a **`StateContext`**, an object scoped to one state's slice of the global store. Two of its methods write: | Method | Accepts | Effect on the slice | |---|---|---| | `setState(value)` | A full new value, or a function `(existing) => next` | Replaces the whole slice | | `patchState(partial)` | An object with some top-level keys | Copies the slice, overwrites those keys | Both return `void` in current NGXS; that changed in the 18 release, so code that chained on their return value belongs to an older major. ## What patchState really does `patchState` is a convenience for the common case of an object slice with a few top-level fields. Internally it spreads the existing slice into a new object and assigns each key you passed. Three consequences follow: - **The merge is shallow.** With a slice `{ reservations, filter: { floor, nights } }`, calling `ctx.patchState({ filter: { floor: 3 } })` replaces `filter` entirely, so `nights` is gone. - **It always creates a new top-level object**, even when the values you pass are identical, so anything comparing the slice by reference sees a change. - **It is meant for object slices.** In development builds NGXS throws `Patching arrays is not supported.` or `Patching primitives is not supported.` when the value you pass is an array or a primitive. `patchState` is typed to take a partial object, not a state operator. ## setState with a function, and what a state operator is `setState` can take a function that receives the current slice and returns the next one. A **state operator** is simply such a function, usually produced by a factory. NGXS ships a set of them in `@ngxs/store/operators`: - `patch(spec)`: sets properties on an object; each property can be a value **or another operator**, which is how nested updates stay readable. - `safePatch(spec)` (new in 22): like `patch`, but treats a `null` or `undefined` slice as an empty object. - `append(items)` and `insertItem(value, beforePosition?)`: add to arrays. - `updateItem(indexOrPredicate, valueOrOperator)` and, new in 22, `updateItems`: change matching elements. - `removeItem(indexOrPredicate)` and, new in 22, `removeItems`: remove elements. - `iif(condition, whenTrue, whenFalse?)` and `compose(...operators)`: branch and combine. ```ts ctx.setState( patch<ReservationsStateModel>({ items: updateItem<Reservation>( r => r.id === reservationId, patch<Reservation>({ status: 'confirmed' }) ) }) ); ``` ## Why operators matter for performance The built-in operators copy **only what changes**. `patch` clones an object only if at least one property actually gets a different value; `updateItem` returns the original array when the predicate finds nothing or the new element is identical; `append` with no items returns the existing array. Returning the same reference is the signal that nothing changed, so: 1. Memoized `@Selector` functions whose inputs kept their references are not recomputed. 2. Signals from `select()` and `selectSignal` compare by reference and do not notify. 3. `OnPush` components bound to untouched parts do not re-render. A hand-written spread such as `{ ...state, items: state.items.map(...) }` produces a new array even when no element changed, which invalidates every selector downstream. ## Immutability is still your job NGXS does not copy state for you when you mutate it. `ctx.getState().items.push(r)` changes the array in place without producing a new reference, so selectors and signals see no change. With the `developmentMode: true` store option, NGXS freezes state and actions in development, which turns such mutations into errors you notice early. The operators are the idiomatic way to write immutable updates without spreading every level by hand; the docs also show a curried Immer `produce` passed to `setState`, since it has the same signature as a state operator. ## Choosing between them - Top-level fields on an object slice: `patchState` is fine. - Replacing the slice outright, or a slice that is an array: `setState`, often with `append`, `updateItem` or `removeItem`. - Nested objects or items inside arrays: `setState(patch({ ... }))` with nested operators. - Conditional updates: `iif`, so the decision reads the live state rather than a value captured earlier. - A nested object that may still be `null`, such as an optional guest profile on a reservation: `safePatch` inside `patch`, which treats the missing object as an empty one instead of throwing. Whichever you choose, keep one style per state class; mixing hand-written spreads and operators in the same handler makes it hard to see which updates preserve references.