@ngxs/store 21.0.0-dev.master-f8041d1 → 21.0.0-dev.master-35d18c0

package/fesm2022/ngxs-store-operators.mjs

@@ -6,12 +6,28 @@ const isNumber = (value) => typeof value === 'number';
 const invalidIndex = (index) => Number.isNaN(index) || index === -1;
 
 /**
- * @param items - Specific items to append to the end of an array
+ * Adds items to the end of an array without mutating the original. Handles
+ * the case where the array property does not exist yet, so callers do not
+ * need to initialise it before appending. A `null`, `undefined`, or empty
+ * `items` argument is treated as a no-op to allow safe pass-through of
+ * optional data.
+ *
+ * @param items - Items to add to the end of the array.
+ *
+ * @example
+ * ```ts
+ * // Add a new zebra to the end of the list without touching the rest of state.
+ * ctx.setState(
+ *   patch<AnimalsStateModel>({
+ *     zebras: append<string>([action.payload])
+ *   })
+ * );
+ * ```
  */
 function append(items) {
     return function appendOperator(existing) {
-        // If `items` is `undefined` or `null` or `[]` but `existing` is provided
-        // just return `existing`
+        // Nothing meaningful to append, so preserve the existing reference
+        // to avoid invalidating memoized selectors unnecessarily.
         const itemsNotProvidedButExistingIs = (!items || !items.length) && existing;
         if (itemsNotProvidedButExistingIs) {
             return existing;
@@ -19,12 +35,29 @@ function append(items) {
         if (isArray(existing)) {
             return existing.concat(items);
         }
-        // For example if some property is added dynamically
-        // and didn't exist before thus it's not `ArrayLike`
+        // The array property was never initialised, so `items` becomes the
+        // initial state rather than being appended to a non-existent array.
         return items;
     };
 }
 
+/**
+ * Chains multiple state operators so they execute left-to-right, each
+ * receiving the output of the previous one. Useful when several independent
+ * transformations must be applied to the same state slice in a single atomic
+ * update, avoiding multiple `setState` calls.
+ *
+ * @example
+ * ```ts
+ * // Apply two independent array mutations in one atomic setState call.
+ * ctx.setState(
+ *   compose<AnimalsStateModel>(
+ *     patch({ zebras: append<string>([action.zebraName]) }),
+ *     patch({ pandas: removeItem<string>(name => name === action.pandaToRemove) })
+ *   )
+ * );
+ * ```
+ */
 function compose(...operators) {
     return function composeOperator(existing) {
         return operators.reduce((accumulator, operator) => operator(accumulator), existing);
@@ -32,32 +65,51 @@ function compose(...operators) {
 }
 
 function retrieveValue(operatorOrValue, existing) {
-    // If state operator is a function
-    // then call it with an original value
+    // Delegate to the operator so a derived transformation can be applied
+    // rather than substituting a static value.
     if (isStateOperator(operatorOrValue)) {
         const value = operatorOrValue(existing);
         return value;
     }
-    // If operator or value was not provided
-    // e.g. `elseOperatorOrValue` is `undefined`
-    // then we just return an original value
+    // No else branch was provided, so leave the state unchanged.
     if (operatorOrValue === undefined) {
         return existing;
     }
     return operatorOrValue;
 }
 /**
- * @param condition - Condition can be a plain boolean value or a function,
- * that returns boolean, also this function can take a value as an argument
- * to which this state operator applies
- * @param trueOperatorOrValue - Any value or a state operator
- * @param elseOperatorOrValue - Any value or a state operator
+ * Applies one of two operators (or values) based on a condition, keeping
+ * conditional logic out of action handlers and inside the state mutation
+ * pipeline where it belongs.
+ *
+ * @param condition - A boolean or a predicate receiving the current state value.
+ * Use a predicate when the decision depends on the existing state rather than
+ * external data available at dispatch time.
+ * @param trueOperatorOrValue - Applied when `condition` is truthy.
+ * @param elseOperatorOrValue - Applied when `condition` is falsy. Omit to
+ * leave the state unchanged in the false branch.
+ *
+ * @example
+ * ```ts
+ * // Only add a panda when the list has fewer than 5 — the cap is enforced
+ * // inside the operator so the action handler stays free of branching logic.
+ * ctx.setState(
+ *   patch<AnimalsStateModel>({
+ *     pandas: iif(
+ *       pandas => pandas.length < 5,
+ *       append<string>([action.payload])
+ *     )
+ *   })
+ * );
+ * ```
  */
 function iif(condition, trueOperatorOrValue, elseOperatorOrValue) {
     return function iifOperator(existing) {
-        // Convert the value to a boolean
+        // Normalise to a boolean so both plain booleans and predicates
+        // share the same resolution path below.
         let result = !!condition;
-        // but if it is a function then run it to get the result
+        // Predicates receive the current state value so the decision can be
+        // based on live state rather than values captured at dispatch time.
         if (isPredicate(condition)) {
             result = condition(existing);
         }
@@ -69,25 +121,51 @@ function iif(condition, trueOperatorOrValue, elseOperatorOrValue) {
 }
 
 /**
- * @param value - Value to insert
- * @param [beforePosition] -  Specified index to insert value before, optional
+ * Inserts an item into an array without mutating the original, satisfying
+ * NGXS's immutability requirement. Handles the case where the array property
+ * does not exist yet, so callers do not need to initialise it first.
+ *
+ * @param value - The item to insert. A `null` or `undefined` value is a no-op
+ * so that callers can pass through optional data safely.
+ * @param beforePosition - Index before which to insert. Omit (or pass a
+ * non-positive number) to prepend to the beginning of the array.
+ *
+ * @example
+ * ```ts
+ * // Prepend a new zebra (no position = insert at index 0).
+ * ctx.setState(
+ *   patch<AnimalsStateModel>({
+ *     zebras: insertItem<string>(action.payload)
+ *   })
+ * );
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Insert before index 2, shifting subsequent items right.
+ * ctx.setState(
+ *   patch<AnimalsStateModel>({
+ *     zebras: insertItem<string>(action.payload, 2)
+ *   })
+ * );
+ * ```
  */
 function insertItem(value, beforePosition) {
     return function insertItemOperator(existing) {
-        // Have to check explicitly for `null` and `undefined`
-        // because `value` can be `0`, thus `!value` will return `true`
+        // `== null` covers both `null` and `undefined` while letting falsy
+        // values like `0` or `false` through, where `!value` would not.
         if (value == null && existing) {
             return existing;
         }
-        // Property may be dynamic and might not existed before
+        // The array property may not have been initialised yet; treat it as
+        // empty so callers don't have to guard against that case themselves.
         if (!isArray(existing)) {
             return [value];
         }
         const clone = existing.slice();
         let index = 0;
-        // No need to call `isNumber`
-        // as we are checking `> 0` not `>= 0`
-        // everything except number will return false here
+        // `> 0` rather than `>= 0` intentionally: non-numeric values coerce
+        // to NaN and fail this check, so no explicit `isNumber` call is needed.
         if (beforePosition > 0) {
             index = beforePosition;
         }
@@ -96,6 +174,40 @@ function insertItem(value, beforePosition) {
     };
 }
 
+/**
+ * Applies a partial update to a state object, only cloning it when at least
+ * one property actually changes. This preserves referential equality for
+ * unchanged states, preventing unnecessary re-renders in `OnPush` components
+ * and keeping memoized selectors from recalculating.
+ *
+ * Each property in `patchObject` can itself be a state operator, enabling
+ * nested immutable updates without manually spreading every level of the tree.
+ *
+ * @example
+ * ```ts
+ * // Add an optional property to a state slice without touching existing ones.
+ * ctx.setState(
+ *   patch<AnimalsStateModel>({ monkeys: [] })
+ * );
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Deep update — specify explicit types at each level so TypeScript can
+ * // catch property name mistakes in nested patches.
+ * ctx.setState(
+ *   patch<AddressStateModel>({
+ *     country: patch<AddressStateModel['country']>({
+ *       city: patch<AddressStateModel['country']['city']>({
+ *         address: patch<AddressStateModel['country']['city']['address']>({
+ *           line1: action.line1
+ *         })
+ *       })
+ *     })
+ *   })
+ * );
+ * ```
+ */
 function patch(patchObject) {
     return function patchStateOperator(existing) {
         let clone = null;
@@ -116,6 +228,24 @@ function patch(patchObject) {
     };
 }
 
+/**
+ * Like `patch`, but safe to call when the state slice is `null` or
+ * `undefined`. Treats a missing slice as an empty object so the patch is
+ * applied against a clean baseline rather than throwing. Useful for lazily
+ * initialised state properties or optional sub-states that may not have been
+ * set yet.
+ *
+ * @example
+ * ```ts
+ * // Update a nested preferences slice that starts as null — no prior
+ * // null-check needed; safePatch treats null as an empty object.
+ * ctx.setState(
+ *   patch<UserStateModel>({
+ *     preferences: safePatch<UserPreferences>({ theme: action.theme })
+ *   })
+ * );
+ * ```
+ */
 function safePatch(patchSpec) {
     const patcher = patch(patchSpec);
     return function patchSafely(existing) {
@@ -124,10 +254,30 @@ function safePatch(patchSpec) {
 }
 
 /**
- * @param selector - Index of item in the array or a predicate function
- * that can be provided in `Array.prototype.findIndex`
- * @param operatorOrValue - New value under the `selector` index or a
- * function that can be applied to an existing value
+ * Replaces or transforms a single array element without cloning elements that
+ * did not change, preserving referential equality for the rest of the array.
+ * Returns the original array reference when nothing changed, keeping
+ * memoized selectors and `OnPush` components from re-rendering unnecessarily.
+ *
+ * @param selector - The index to update, or a predicate used to locate the
+ * item. Prefer a predicate when the item's position may have shifted since the
+ * index was last known.
+ * @param operatorOrValue - The replacement value, or a state operator applied
+ * to the existing element when a derived update is needed.
+ *
+ * @example
+ * ```ts
+ * // Rename a panda — locate it by current name so the index doesn't need
+ * // to be known ahead of time.
+ * ctx.setState(
+ *   patch<AnimalsStateModel>({
+ *     pandas: updateItem<string>(
+ *       name => name === action.payload.name,
+ *       action.payload.newName
+ *     )
+ *   })
+ * );
+ * ```
  */
 function updateItem(selector, operatorOrValue) {
     return function updateItemOperator(existing) {
@@ -142,8 +292,8 @@ function updateItem(selector, operatorOrValue) {
             return existing;
         }
         let value = null;
-        // Need to check if the new item value will change the existing item value
-        // then, only if it will change it then clone the array and set the item
+        // Resolve the new value before touching the array so we can bail out
+        // early and skip the clone when nothing actually changed.
         const theOperatorOrValue = operatorOrValue;
         if (isStateOperator(theOperatorOrValue)) {
             value = theOperatorOrValue(existing[index]);
@@ -151,8 +301,8 @@ function updateItem(selector, operatorOrValue) {
         else {
             value = theOperatorOrValue;
         }
-        // If the value hasn't been mutated
-        // then we just return `existing` array
+        // Return the original reference to prevent memoized selectors and
+        // OnPush components from reacting to a no-op update.
         if (value === existing[index]) {
             return existing;
         }
@@ -163,7 +313,24 @@ function updateItem(selector, operatorOrValue) {
 }
 
 /**
- * @param selector - index or predicate to remove an item from an array by
+ * Removes a single element from an array without mutating the original.
+ * Returns the original array reference when no matching item is found, so
+ * memoized selectors are not invalidated by a no-op removal.
+ *
+ * @param selector - The index to remove, or a predicate used to locate the
+ * item. Prefer a predicate when the item's position is not guaranteed to be
+ * stable across concurrent state updates.
+ *
+ * @example
+ * ```ts
+ * // Remove a panda by name — a predicate is safer than a hard-coded index
+ * // because the array order may change between dispatch and execution.
+ * ctx.setState(
+ *   patch<AnimalsStateModel>({
+ *     pandas: removeItem<string>(name => name === action.payload)
+ *   })
+ * );
+ * ```
  */
 function removeItem(selector) {
     return function removeItemOperator(existing) {

package/fesm2022/ngxs-store-operators.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"ngxs-store-operators.mjs","sources":["../../../packages/store/operators/src/utils.ts","../../../packages/store/operators/src/append.ts","../../../packages/store/operators/src/compose.ts","../../../packages/store/operators/src/iif.ts","../../../packages/store/operators/src/insert-item.ts","../../../packages/store/operators/src/patch.ts","../../../packages/store/operators/src/safe-patch.ts","../../../packages/store/operators/src/update-item.ts","../../../packages/store/operators/src/remove-item.ts","../../../packages/store/operators/src/index.ts","../../../packages/store/operators/src/ngxs-store-operators.ts"],"sourcesContent":["import { StateOperator } from './types';\n\nexport const isArray = Array.isArray;\n\nexport type Predicate<T = any> = (value: T | Readonly<T>) => boolean;\n\nconst isFunction = (value: unknown) => typeof value == 'function';\n\nexport const isStateOperator = isFunction as <T>(\n  value: T | StateOperator<T>\n) => value is StateOperator<T>;\n\nexport const isPredicate = isFunction as <T>(\n  value: Predicate<T> | boolean | number\n) => value is Predicate<T>;\n\nexport const isNumber = (value: unknown): value is number => typeof value === 'number';\n\nexport const invalidIndex = (index: number) => Number.isNaN(index) || index === -1;\n","import { ExistingState, NoInfer, StateOperator } from './types';\nimport { isArray } from './utils';\n\n/**\n * @param items - Specific items to append to the end of an array\n */\nexport function append<T>(items: NoInfer<T[]>): StateOperator<T[]> {\n  return function appendOperator(existing: ExistingState<T[]>): T[] {\n    // If `items` is `undefined` or `null` or `[]` but `existing` is provided\n    // just return `existing`\n    const itemsNotProvidedButExistingIs = (!items || !items.length) && existing;\n    if (itemsNotProvidedButExistingIs) {\n      return existing as unknown as T[];\n    }\n\n    if (isArray(existing)) {\n      return existing.concat(items as unknown as ExistingState<T[]>);\n    }\n\n    // For example if some property is added dynamically\n    // and didn't exist before thus it's not `ArrayLike`\n    return items as unknown as T[];\n  };\n}\n","import { ExistingState, NoInfer, StateOperator } from './types';\n\nexport function compose<T>(...operators: NoInfer<StateOperator<T>[]>): StateOperator<T> {\n  return function composeOperator(existing: ExistingState<T>): T {\n    return operators.reduce(\n      (accumulator, operator) => operator(accumulator as ExistingState<T>),\n      existing as T\n    );\n  };\n}\n","import { ExistingState, NoInfer, StateOperator } from './types';\n\nimport { isStateOperator, isPredicate, Predicate } from './utils';\n\nfunction retrieveValue<T>(\n  operatorOrValue: StateOperator<T> | T,\n  existing: ExistingState<T>\n): T {\n  // If state operator is a function\n  // then call it with an original value\n  if (isStateOperator(operatorOrValue)) {\n    const value = operatorOrValue(existing);\n    return value as T;\n  }\n\n  // If operator or value was not provided\n  // e.g. `elseOperatorOrValue` is `undefined`\n  // then we just return an original value\n  if (operatorOrValue === undefined) {\n    return existing as T;\n  }\n\n  return operatorOrValue as T;\n}\n\n/**\n * @param condition - Condition can be a plain boolean value or a function,\n * that returns boolean, also this function can take a value as an argument\n * to which this state operator applies\n * @param trueOperatorOrValue - Any value or a state operator\n * @param elseOperatorOrValue - Any value or a state operator\n */\nexport function iif<T>(\n  condition: NoInfer<Predicate<T>> | boolean,\n  trueOperatorOrValue: NoInfer<StateOperator<T> | T>,\n  elseOperatorOrValue?: NoInfer<StateOperator<T> | T>\n): StateOperator<T> {\n  return function iifOperator(existing: ExistingState<T>): T {\n    // Convert the value to a boolean\n    let result = !!condition;\n    // but if it is a function then run it to get the result\n    if (isPredicate(condition)) {\n      result = condition(existing as T);\n    }\n\n    if (result) {\n      return retrieveValue<T>(trueOperatorOrValue as StateOperator<T> | T, existing);\n    }\n\n    return retrieveValue<T>(elseOperatorOrValue! as StateOperator<T> | T, existing);\n  };\n}\n","import { ExistingState, NoInfer, StateOperator } from './types';\nimport { isArray } from './utils';\n\n/**\n * @param value - Value to insert\n * @param [beforePosition] -  Specified index to insert value before, optional\n */\nexport function insertItem<T>(value: NoInfer<T>, beforePosition?: number): StateOperator<T[]> {\n  return function insertItemOperator(existing: ExistingState<T[]>): T[] {\n    // Have to check explicitly for `null` and `undefined`\n    // because `value` can be `0`, thus `!value` will return `true`\n    if (value == null && existing) {\n      return existing as T[];\n    }\n\n    // Property may be dynamic and might not existed before\n    if (!isArray(existing)) {\n      return [value as unknown as T];\n    }\n\n    const clone = existing.slice();\n\n    let index = 0;\n\n    // No need to call `isNumber`\n    // as we are checking `> 0` not `>= 0`\n    // everything except number will return false here\n    if (beforePosition! > 0) {\n      index = beforePosition!;\n    }\n\n    clone.splice(index, 0, value as unknown as T);\n    return clone;\n  };\n}\n","import { ExistingState, NoInfer, StateOperator } from './types';\nimport { isStateOperator } from './utils';\n\ntype NotUndefined<T> = T extends undefined ? never : T;\n\nexport type ɵPatchSpec<T> = { [P in keyof T]?: T[P] | StateOperator<NotUndefined<T[P]>> };\n\nexport function patch<T extends Record<string, any>>(\n  patchObject: NoInfer<ɵPatchSpec<T>>\n): StateOperator<T> {\n  return function patchStateOperator(existing: ExistingState<T>): T {\n    let clone = null;\n    for (const k in patchObject) {\n      const newValue = patchObject[k];\n      const existingPropValue = existing?.[k];\n      const newPropValue = isStateOperator(newValue)\n        ? newValue(<any>existingPropValue)\n        : newValue;\n      if (newPropValue !== existingPropValue) {\n        if (!clone) {\n          clone = { ...(<any>existing) };\n        }\n        clone[k] = newPropValue;\n      }\n    }\n    return clone || existing;\n  };\n}\n","import { patch, type ɵPatchSpec } from './patch';\nimport type { ExistingState, NoInfer, StateOperator } from './types';\n\nexport function safePatch<T extends object>(\n  patchSpec: NoInfer<ɵPatchSpec<T>>\n): StateOperator<T> {\n  const patcher = patch(patchSpec as ɵPatchSpec<T>) as unknown as StateOperator<\n    Readonly<NonNullable<T>>\n  >;\n  return function patchSafely(existing: ExistingState<T>): T {\n    return patcher(existing ?? ({} as ExistingState<Readonly<NonNullable<T>>>));\n  };\n}\n","import { ExistingState, NoInfer, StateOperator } from './types';\n\nimport { isStateOperator, isPredicate, isNumber, invalidIndex, Predicate } from './utils';\n\n/**\n * @param selector - Index of item in the array or a predicate function\n * that can be provided in `Array.prototype.findIndex`\n * @param operatorOrValue - New value under the `selector` index or a\n * function that can be applied to an existing value\n */\nexport function updateItem<T>(\n  selector: number | NoInfer<Predicate<T>>,\n  operatorOrValue: NoInfer<T> | NoInfer<StateOperator<T>>\n): StateOperator<T[]> {\n  return function updateItemOperator(existing: ExistingState<T[]>): T[] {\n    let index = -1;\n\n    if (isPredicate(selector)) {\n      index = existing.findIndex(selector as Predicate<T>);\n    } else if (isNumber(selector)) {\n      index = selector;\n    }\n\n    if (invalidIndex(index)) {\n      return existing as T[];\n    }\n\n    let value: T = null!;\n    // Need to check if the new item value will change the existing item value\n    // then, only if it will change it then clone the array and set the item\n    const theOperatorOrValue = operatorOrValue as T | StateOperator<T>;\n    if (isStateOperator(theOperatorOrValue)) {\n      value = theOperatorOrValue(existing[index] as ExistingState<T>);\n    } else {\n      value = theOperatorOrValue;\n    }\n\n    // If the value hasn't been mutated\n    // then we just return `existing` array\n    if (value === existing[index]) {\n      return existing as T[];\n    }\n\n    const clone = existing.slice();\n    clone[index] = value as T;\n    return clone;\n  };\n}\n","import { ExistingState, NoInfer, StateOperator } from './types';\nimport { isPredicate, isNumber, invalidIndex, Predicate } from './utils';\n\n/**\n * @param selector - index or predicate to remove an item from an array by\n */\nexport function removeItem<T>(selector: number | NoInfer<Predicate<T>>): StateOperator<T[]> {\n  return function removeItemOperator(existing: ExistingState<T[]>): T[] {\n    let index = -1;\n\n    if (isPredicate(selector)) {\n      index = existing.findIndex(selector);\n    } else if (isNumber(selector)) {\n      index = selector;\n    }\n\n    if (invalidIndex(index)) {\n      return existing as T[];\n    }\n\n    const clone = existing.slice();\n    clone.splice(index, 1);\n    return clone;\n  };\n}\n","/**\n * @module\n * @description\n * Entry point for all public APIs of this package.\n */\nexport { append } from './append';\nexport { compose } from './compose';\nexport { iif } from './iif';\nexport { insertItem } from './insert-item';\nexport { patch, type ɵPatchSpec } from './patch';\nexport { safePatch } from './safe-patch';\nexport { isStateOperator, isPredicate, type Predicate } from './utils';\nexport { updateItem } from './update-item';\nexport { removeItem } from './remove-item';\nexport type { ExistingState, NoInfer, StateOperator } from './types';\n","/**\n * Generated bundle index. Do not edit.\n */\n\nexport * from './index';\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"ngxs-store-operators.mjs","sources":["../../../packages/store/operators/src/utils.ts","../../../packages/store/operators/src/append.ts","../../../packages/store/operators/src/compose.ts","../../../packages/store/operators/src/iif.ts","../../../packages/store/operators/src/insert-item.ts","../../../packages/store/operators/src/patch.ts","../../../packages/store/operators/src/safe-patch.ts","../../../packages/store/operators/src/update-item.ts","../../../packages/store/operators/src/remove-item.ts","../../../packages/store/operators/src/index.ts","../../../packages/store/operators/src/ngxs-store-operators.ts"],"sourcesContent":["import { StateOperator } from './types';\n\nexport const isArray = Array.isArray;\n\nexport type Predicate<T = any> = (value: T | Readonly<T>) => boolean;\n\nconst isFunction = (value: unknown) => typeof value == 'function';\n\nexport const isStateOperator = isFunction as <T>(\n  value: T | StateOperator<T>\n) => value is StateOperator<T>;\n\nexport const isPredicate = isFunction as <T>(\n  value: Predicate<T> | boolean | number\n) => value is Predicate<T>;\n\nexport const isNumber = (value: unknown): value is number => typeof value === 'number';\n\nexport const invalidIndex = (index: number) => Number.isNaN(index) || index === -1;\n","import { ExistingState, NoInfer, StateOperator } from './types';\nimport { isArray } from './utils';\n\n/**\n * Adds items to the end of an array without mutating the original. Handles\n * the case where the array property does not exist yet, so callers do not\n * need to initialise it before appending. A `null`, `undefined`, or empty\n * `items` argument is treated as a no-op to allow safe pass-through of\n * optional data.\n *\n * @param items - Items to add to the end of the array.\n *\n * @example\n * ```ts\n * // Add a new zebra to the end of the list without touching the rest of state.\n * ctx.setState(\n *   patch<AnimalsStateModel>({\n *     zebras: append<string>([action.payload])\n *   })\n * );\n * ```\n */\nexport function append<T>(items: NoInfer<T[]>): StateOperator<T[]> {\n  return function appendOperator(existing: ExistingState<T[]>): T[] {\n    // Nothing meaningful to append, so preserve the existing reference\n    // to avoid invalidating memoized selectors unnecessarily.\n    const itemsNotProvidedButExistingIs = (!items || !items.length) && existing;\n    if (itemsNotProvidedButExistingIs) {\n      return existing as unknown as T[];\n    }\n\n    if (isArray(existing)) {\n      return existing.concat(items as unknown as ExistingState<T[]>);\n    }\n\n    // The array property was never initialised, so `items` becomes the\n    // initial state rather than being appended to a non-existent array.\n    return items as unknown as T[];\n  };\n}\n","import { ExistingState, NoInfer, StateOperator } from './types';\n\n/**\n * Chains multiple state operators so they execute left-to-right, each\n * receiving the output of the previous one. Useful when several independent\n * transformations must be applied to the same state slice in a single atomic\n * update, avoiding multiple `setState` calls.\n *\n * @example\n * ```ts\n * // Apply two independent array mutations in one atomic setState call.\n * ctx.setState(\n *   compose<AnimalsStateModel>(\n *     patch({ zebras: append<string>([action.zebraName]) }),\n *     patch({ pandas: removeItem<string>(name => name === action.pandaToRemove) })\n *   )\n * );\n * ```\n */\nexport function compose<T>(...operators: NoInfer<StateOperator<T>[]>): StateOperator<T> {\n  return function composeOperator(existing: ExistingState<T>): T {\n    return operators.reduce(\n      (accumulator, operator) => operator(accumulator as ExistingState<T>),\n      existing as T\n    );\n  };\n}\n","import { ExistingState, NoInfer, StateOperator } from './types';\n\nimport { isStateOperator, isPredicate, Predicate } from './utils';\n\nfunction retrieveValue<T>(\n  operatorOrValue: StateOperator<T> | T,\n  existing: ExistingState<T>\n): T {\n  // Delegate to the operator so a derived transformation can be applied\n  // rather than substituting a static value.\n  if (isStateOperator(operatorOrValue)) {\n    const value = operatorOrValue(existing);\n    return value as T;\n  }\n\n  // No else branch was provided, so leave the state unchanged.\n  if (operatorOrValue === undefined) {\n    return existing as T;\n  }\n\n  return operatorOrValue as T;\n}\n\n/**\n * Applies one of two operators (or values) based on a condition, keeping\n * conditional logic out of action handlers and inside the state mutation\n * pipeline where it belongs.\n *\n * @param condition - A boolean or a predicate receiving the current state value.\n * Use a predicate when the decision depends on the existing state rather than\n * external data available at dispatch time.\n * @param trueOperatorOrValue - Applied when `condition` is truthy.\n * @param elseOperatorOrValue - Applied when `condition` is falsy. Omit to\n * leave the state unchanged in the false branch.\n *\n * @example\n * ```ts\n * // Only add a panda when the list has fewer than 5 — the cap is enforced\n * // inside the operator so the action handler stays free of branching logic.\n * ctx.setState(\n *   patch<AnimalsStateModel>({\n *     pandas: iif(\n *       pandas => pandas.length < 5,\n *       append<string>([action.payload])\n *     )\n *   })\n * );\n * ```\n */\nexport function iif<T>(\n  condition: NoInfer<Predicate<T>> | boolean,\n  trueOperatorOrValue: NoInfer<StateOperator<T> | T>,\n  elseOperatorOrValue?: NoInfer<StateOperator<T> | T>\n): StateOperator<T> {\n  return function iifOperator(existing: ExistingState<T>): T {\n    // Normalise to a boolean so both plain booleans and predicates\n    // share the same resolution path below.\n    let result = !!condition;\n    // Predicates receive the current state value so the decision can be\n    // based on live state rather than values captured at dispatch time.\n    if (isPredicate(condition)) {\n      result = condition(existing as T);\n    }\n\n    if (result) {\n      return retrieveValue<T>(trueOperatorOrValue as StateOperator<T> | T, existing);\n    }\n\n    return retrieveValue<T>(elseOperatorOrValue! as StateOperator<T> | T, existing);\n  };\n}\n","import { ExistingState, NoInfer, StateOperator } from './types';\nimport { isArray } from './utils';\n\n/**\n * Inserts an item into an array without mutating the original, satisfying\n * NGXS's immutability requirement. Handles the case where the array property\n * does not exist yet, so callers do not need to initialise it first.\n *\n * @param value - The item to insert. A `null` or `undefined` value is a no-op\n * so that callers can pass through optional data safely.\n * @param beforePosition - Index before which to insert. Omit (or pass a\n * non-positive number) to prepend to the beginning of the array.\n *\n * @example\n * ```ts\n * // Prepend a new zebra (no position = insert at index 0).\n * ctx.setState(\n *   patch<AnimalsStateModel>({\n *     zebras: insertItem<string>(action.payload)\n *   })\n * );\n * ```\n *\n * @example\n * ```ts\n * // Insert before index 2, shifting subsequent items right.\n * ctx.setState(\n *   patch<AnimalsStateModel>({\n *     zebras: insertItem<string>(action.payload, 2)\n *   })\n * );\n * ```\n */\nexport function insertItem<T>(value: NoInfer<T>, beforePosition?: number): StateOperator<T[]> {\n  return function insertItemOperator(existing: ExistingState<T[]>): T[] {\n    // `== null` covers both `null` and `undefined` while letting falsy\n    // values like `0` or `false` through, where `!value` would not.\n    if (value == null && existing) {\n      return existing as T[];\n    }\n\n    // The array property may not have been initialised yet; treat it as\n    // empty so callers don't have to guard against that case themselves.\n    if (!isArray(existing)) {\n      return [value as unknown as T];\n    }\n\n    const clone = existing.slice();\n\n    let index = 0;\n\n    // `> 0` rather than `>= 0` intentionally: non-numeric values coerce\n    // to NaN and fail this check, so no explicit `isNumber` call is needed.\n    if (beforePosition! > 0) {\n      index = beforePosition!;\n    }\n\n    clone.splice(index, 0, value as unknown as T);\n    return clone;\n  };\n}\n","import { ExistingState, NoInfer, StateOperator } from './types';\nimport { isStateOperator } from './utils';\n\ntype NotUndefined<T> = T extends undefined ? never : T;\n\nexport type ɵPatchSpec<T> = { [P in keyof T]?: T[P] | StateOperator<NotUndefined<T[P]>> };\n\n/**\n * Applies a partial update to a state object, only cloning it when at least\n * one property actually changes. This preserves referential equality for\n * unchanged states, preventing unnecessary re-renders in `OnPush` components\n * and keeping memoized selectors from recalculating.\n *\n * Each property in `patchObject` can itself be a state operator, enabling\n * nested immutable updates without manually spreading every level of the tree.\n *\n * @example\n * ```ts\n * // Add an optional property to a state slice without touching existing ones.\n * ctx.setState(\n *   patch<AnimalsStateModel>({ monkeys: [] })\n * );\n * ```\n *\n * @example\n * ```ts\n * // Deep update — specify explicit types at each level so TypeScript can\n * // catch property name mistakes in nested patches.\n * ctx.setState(\n *   patch<AddressStateModel>({\n *     country: patch<AddressStateModel['country']>({\n *       city: patch<AddressStateModel['country']['city']>({\n *         address: patch<AddressStateModel['country']['city']['address']>({\n *           line1: action.line1\n *         })\n *       })\n *     })\n *   })\n * );\n * ```\n */\nexport function patch<T extends Record<string, any>>(\n  patchObject: NoInfer<ɵPatchSpec<T>>\n): StateOperator<T> {\n  return function patchStateOperator(existing: ExistingState<T>): T {\n    let clone = null;\n    for (const k in patchObject) {\n      const newValue = patchObject[k];\n      const existingPropValue = existing?.[k];\n      const newPropValue = isStateOperator(newValue)\n        ? newValue(<any>existingPropValue)\n        : newValue;\n      if (newPropValue !== existingPropValue) {\n        if (!clone) {\n          clone = { ...(<any>existing) };\n        }\n        clone[k] = newPropValue;\n      }\n    }\n    return clone || existing;\n  };\n}\n","import { patch, type ɵPatchSpec } from './patch';\nimport type { ExistingState, NoInfer, StateOperator } from './types';\n\n/**\n * Like `patch`, but safe to call when the state slice is `null` or\n * `undefined`. Treats a missing slice as an empty object so the patch is\n * applied against a clean baseline rather than throwing. Useful for lazily\n * initialised state properties or optional sub-states that may not have been\n * set yet.\n *\n * @example\n * ```ts\n * // Update a nested preferences slice that starts as null — no prior\n * // null-check needed; safePatch treats null as an empty object.\n * ctx.setState(\n *   patch<UserStateModel>({\n *     preferences: safePatch<UserPreferences>({ theme: action.theme })\n *   })\n * );\n * ```\n */\nexport function safePatch<T extends object>(\n  patchSpec: NoInfer<ɵPatchSpec<T>>\n): StateOperator<T> {\n  const patcher = patch(patchSpec as ɵPatchSpec<T>) as unknown as StateOperator<\n    Readonly<NonNullable<T>>\n  >;\n  return function patchSafely(existing: ExistingState<T>): T {\n    return patcher(existing ?? ({} as ExistingState<Readonly<NonNullable<T>>>));\n  };\n}\n","import { ExistingState, NoInfer, StateOperator } from './types';\n\nimport { isStateOperator, isPredicate, isNumber, invalidIndex, Predicate } from './utils';\n\n/**\n * Replaces or transforms a single array element without cloning elements that\n * did not change, preserving referential equality for the rest of the array.\n * Returns the original array reference when nothing changed, keeping\n * memoized selectors and `OnPush` components from re-rendering unnecessarily.\n *\n * @param selector - The index to update, or a predicate used to locate the\n * item. Prefer a predicate when the item's position may have shifted since the\n * index was last known.\n * @param operatorOrValue - The replacement value, or a state operator applied\n * to the existing element when a derived update is needed.\n *\n * @example\n * ```ts\n * // Rename a panda — locate it by current name so the index doesn't need\n * // to be known ahead of time.\n * ctx.setState(\n *   patch<AnimalsStateModel>({\n *     pandas: updateItem<string>(\n *       name => name === action.payload.name,\n *       action.payload.newName\n *     )\n *   })\n * );\n * ```\n */\nexport function updateItem<T>(\n  selector: number | NoInfer<Predicate<T>>,\n  operatorOrValue: NoInfer<T> | NoInfer<StateOperator<T>>\n): StateOperator<T[]> {\n  return function updateItemOperator(existing: ExistingState<T[]>): T[] {\n    let index = -1;\n\n    if (isPredicate(selector)) {\n      index = existing.findIndex(selector as Predicate<T>);\n    } else if (isNumber(selector)) {\n      index = selector;\n    }\n\n    if (invalidIndex(index)) {\n      return existing as T[];\n    }\n\n    let value: T = null!;\n    // Resolve the new value before touching the array so we can bail out\n    // early and skip the clone when nothing actually changed.\n    const theOperatorOrValue = operatorOrValue as T | StateOperator<T>;\n    if (isStateOperator(theOperatorOrValue)) {\n      value = theOperatorOrValue(existing[index] as ExistingState<T>);\n    } else {\n      value = theOperatorOrValue;\n    }\n\n    // Return the original reference to prevent memoized selectors and\n    // OnPush components from reacting to a no-op update.\n    if (value === existing[index]) {\n      return existing as T[];\n    }\n\n    const clone = existing.slice();\n    clone[index] = value as T;\n    return clone;\n  };\n}\n","import { ExistingState, NoInfer, StateOperator } from './types';\nimport { isPredicate, isNumber, invalidIndex, Predicate } from './utils';\n\n/**\n * Removes a single element from an array without mutating the original.\n * Returns the original array reference when no matching item is found, so\n * memoized selectors are not invalidated by a no-op removal.\n *\n * @param selector - The index to remove, or a predicate used to locate the\n * item. Prefer a predicate when the item's position is not guaranteed to be\n * stable across concurrent state updates.\n *\n * @example\n * ```ts\n * // Remove a panda by name — a predicate is safer than a hard-coded index\n * // because the array order may change between dispatch and execution.\n * ctx.setState(\n *   patch<AnimalsStateModel>({\n *     pandas: removeItem<string>(name => name === action.payload)\n *   })\n * );\n * ```\n */\nexport function removeItem<T>(selector: number | NoInfer<Predicate<T>>): StateOperator<T[]> {\n  return function removeItemOperator(existing: ExistingState<T[]>): T[] {\n    let index = -1;\n\n    if (isPredicate(selector)) {\n      index = existing.findIndex(selector);\n    } else if (isNumber(selector)) {\n      index = selector;\n    }\n\n    if (invalidIndex(index)) {\n      return existing as T[];\n    }\n\n    const clone = existing.slice();\n    clone.splice(index, 1);\n    return clone;\n  };\n}\n","/**\n * @module\n * @description\n * Entry point for all public APIs of this package.\n */\nexport { append } from './append';\nexport { compose } from './compose';\nexport { iif } from './iif';\nexport { insertItem } from './insert-item';\nexport { patch, type ɵPatchSpec } from './patch';\nexport { safePatch } from './safe-patch';\nexport { isStateOperator, isPredicate, type Predicate } from './utils';\nexport { updateItem } from './update-item';\nexport { removeItem } from './remove-item';\nexport type { ExistingState, NoInfer, StateOperator } from './types';\n","/**\n * Generated bundle index. Do not edit.\n */\n\nexport * from './index';\n"],"names":[],"mappings":"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"}

package/fesm2022/ngxs-store.mjs

@@ -1056,22 +1056,48 @@ function simplePatch(value) {
     };
 }
 
+class StateContextDestroyedError extends Error {
+    path;
+    name = 'StateContextDestroyedError';
+    constructor(path) {
+        super(typeof ngDevMode !== 'undefined' && ngDevMode
+            ? `Attempted to interact with state after the injector has been destroyed. State path: "${path}". ` +
+                `This can happen in server-side rendering when the app is destroyed before all async operations complete, ` +
+                `e.g. inside a finalize() operator that runs after the injector has been destroyed.`
+            : '');
+        this.path = path;
+        Object.setPrototypeOf(this, StateContextDestroyedError.prototype);
+    }
+}
 /**
- * State Context factory class
+ * Creates `StateContext` instances scoped to a specific state path.
+ * Each action handler receives one of these contexts so it can read and
+ * write only its own slice of the global state tree.
  * @ignore
  */
 class StateContextFactory {
     _injector = inject(EnvironmentInjector);
     _internalStateOperations = inject(InternalStateOperations);
+    // Resolved lazily via `setErrorHandler` to avoid a cyclic dependency when
+    // the ErrorHandler itself injects the Store.
+    _errorHandler = null;
     /**
      * Create the state context
      */
     createStateContext(path, abortSignal) {
         const injector = this._injector;
+        const errorHandler = this._errorHandler;
         const root = this._internalStateOperations.getRootStateOperations();
         return {
             abortSignal,
             getState() {
+                if (injector.destroyed) {
+                    // Only report — do not return early. Returning `undefined as T` would
+                    // be a breaking change for callers that assume getState() always
+                    // returns a value. handleError is just for observability (e.g. Rollbar);
+                    // the state data is still readable even after the injector is gone.
+                    errorHandler?.handleError(new StateContextDestroyedError(path));
+                }
                 const currentAppState = root.getState();
                 return getState(currentAppState, path);
             },
@@ -1079,15 +1105,7 @@ class StateContextFactory {
                 // If the injector has been destroyed (e.g. app destroyed mid-action),
                 // skip the state update to avoid writing to completed subjects.
                 if (injector.destroyed) {
-                    // Also warn in SSR regardless of devMode — bundle size is not a
-                    // concern on the server, and silently dropping state mutations is
-                    // critical enough to always surface in server logs.
-                    if ((typeof ngDevMode !== 'undefined' && ngDevMode) ||
-                        (typeof ngServerMode !== 'undefined' && ngServerMode)) {
-                        console.warn(`Attempted to patchState after injector has been destroyed. Value: ${JSON.stringify(value)}, state path: "${path}". ` +
-                            `This can happen in server-side rendering when the app is destroyed before all async operations complete, ` +
-                            `e.g. inside a finalize() operator that runs after the injector has been destroyed.`);
-                    }
+                    errorHandler?.handleError(new StateContextDestroyedError(path));
                     return;
                 }
                 const currentAppState = root.getState();
@@ -1097,15 +1115,7 @@ class StateContextFactory {
             setState(value) {
                 // Same guard as patchState — no-op if the injector is already destroyed.
                 if (injector.destroyed) {
-                    // Also warn in SSR regardless of devMode — bundle size is not a
-                    // concern on the server, and silently dropping state mutations is
-                    // critical enough to always surface in server logs.
-                    if ((typeof ngDevMode !== 'undefined' && ngDevMode) ||
-                        (typeof ngServerMode !== 'undefined' && ngServerMode)) {
-                        console.warn(`Attempted to setState after injector has been destroyed. Value: ${JSON.stringify(value)}, state path: "${path}". ` +
-                            `This can happen in server-side rendering when the app is destroyed before all async operations complete, ` +
-                            `e.g. inside a finalize() operator that runs after the injector has been destroyed.`);
-                    }
+                    errorHandler?.handleError(new StateContextDestroyedError(path));
                     return;
                 }
                 const currentAppState = root.getState();
@@ -1121,6 +1131,14 @@ class StateContextFactory {
             }
         };
     }
+    /** @internal */
+    setErrorHandler() {
+        // Called from `LifecycleStateManager.ngxsBootstrap` rather than at
+        // construction time. If we injected ErrorHandler in the constructor,
+        // an ErrorHandler that itself injects Store would create a circular
+        // dependency — deferring the lookup breaks the cycle.
+        this._errorHandler ??= this._injector.get(ErrorHandler);
+    }
     /** @nocollapse */ static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "20.3.2", ngImport: i0, type: StateContextFactory, deps: [], target: i0.ɵɵFactoryTarget.Injectable });
     /** @nocollapse */ static ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "20.3.2", ngImport: i0, type: StateContextFactory, providedIn: 'root' });
 }
@@ -1131,13 +1149,10 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "20.3.2", ngImpor
 function setStateValue(root, currentAppState, newValue, path) {
     const newAppState = setValue(currentAppState, path, newValue);
     root.setState(newAppState);
+    // Note: this returns the full app state rather than just the patched slice.
+    // That's a long-standing quirk (present since the original state-factory.ts)
+    // and fixing it would be a breaking change — tracked for a future release.
     return newAppState;
-    // In doing this refactoring I noticed that there is a 'bug' where the
-    // application state is returned instead of this state slice.
-    // This has worked this way since the beginning see:
-    // https://github.com/ngxs/store/blame/324c667b4b7debd8eb979006c67ca0ae347d88cd/src/state-factory.ts
-    // This needs to be fixed, but is a 'breaking' change.
-    // I will do this fix in a subsequent PR and we can decide how to handle it.
 }
 function setStateFromOperator(root, currentAppState, stateOperator, path) {
     const local = getState(currentAppState, path);
@@ -1769,6 +1784,7 @@ class LifecycleStateManager {
         inject(DestroyRef).onDestroy(() => this._abortController.abort());
     }
     ngxsBootstrap(action, results) {
+        this._stateContextFactory.setErrorHandler();
         if (typeof ngDevMode !== 'undefined' && ngDevMode) {
             if (action instanceof InitState) {
                 this._initStateHasBeenDispatched = true;
@@ -2687,5 +2703,5 @@ function ɵprovideNgxsInternalStateTokens() {
  * Generated bundle index. Do not edit.
  */
 
-export { Action, ActionDirector, ActionStatus, Actions, AsyncReturnType, NgxsConfig, NgxsDevelopmentModule, NgxsModule, NgxsSimpleChange, NgxsUnhandledActionsLogger, NgxsUnhandledErrorHandler, Select, Selector, SelectorOptions, State, Store, createDispatchMap, createModelSelector, createPickSelector, createPropertySelectors, createSelectMap, createSelector, dispatch, lazyProvider, ofAction, ofActionCanceled, ofActionCompleted, ofActionDispatched, ofActionErrored, ofActionSuccessful, provideStates, provideStore, registerNgxsPlugin, select, withNgxsDevelopmentOptions, withNgxsNoopExecutionStrategy, withNgxsPendingTasks, withNgxsPlugin, withNgxsPreboot, NgxsFeatureModule as ɵNgxsFeatureModule, NgxsRootModule as ɵNgxsRootModule, ɵprovideNgxsInternalStateTokens };
+export { Action, ActionDirector, ActionStatus, Actions, AsyncReturnType, NgxsConfig, NgxsDevelopmentModule, NgxsModule, NgxsSimpleChange, NgxsUnhandledActionsLogger, NgxsUnhandledErrorHandler, Select, Selector, SelectorOptions, State, StateContextDestroyedError, Store, createDispatchMap, createModelSelector, createPickSelector, createPropertySelectors, createSelectMap, createSelector, dispatch, lazyProvider, ofAction, ofActionCanceled, ofActionCompleted, ofActionDispatched, ofActionErrored, ofActionSuccessful, provideStates, provideStore, registerNgxsPlugin, select, withNgxsDevelopmentOptions, withNgxsNoopExecutionStrategy, withNgxsPendingTasks, withNgxsPlugin, withNgxsPreboot, NgxsFeatureModule as ɵNgxsFeatureModule, NgxsRootModule as ɵNgxsRootModule, ɵprovideNgxsInternalStateTokens };
 //# sourceMappingURL=ngxs-store.mjs.map