@ngxs/store 21.0.0-dev.master-a4d1cfd → 21.0.0-dev.master-31acb66

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,77 @@ function updateItem(selector, operatorOrValue) {
 }
 
 /**
- * @param selector - index or predicate to remove an item from an array by
+ * Replaces or transforms every array element that matches the predicate.
+ * Unlike `updateItem`, which stops at the first match, this operator walks
+ * the entire array so all qualifying elements are updated in one pass.
+ *
+ * Always returns a new array reference, even when no elements matched or the
+ * values produced by the operator are identical to the originals. Use
+ * `updateItem` instead when only a single element needs updating and
+ * referential equality on no-op updates matters.
+ *
+ * @param selector - Predicate used to decide which elements to update.
+ * @param operatorOrValue - Replacement value, or a state operator applied
+ * to each matching element when a derived update is needed.
+ *
+ * @example
+ * ```ts
+ * // Mark every inactive animal as active in one setState call.
+ * ctx.setState(
+ *   patch<AnimalsStateModel>({
+ *     animals: updateItems<Animal>(
+ *       animal => !animal.active,
+ *       patch({ active: true })
+ *     )
+ *   })
+ * );
+ * ```
+ */
+function updateItems(selector, operatorOrValue) {
+    return function updateItemsOperator(existing) {
+        if (!Array.isArray(existing)) {
+            return [];
+        }
+        else if (existing.length === 0) {
+            return existing;
+        }
+        const clone = existing.slice();
+        for (let index = 0; index < clone.length; index++) {
+            let value = clone[index];
+            if (selector(value)) {
+                const theOperatorOrValue = operatorOrValue;
+                if (isStateOperator(theOperatorOrValue)) {
+                    value = theOperatorOrValue(value);
+                }
+                else {
+                    value = theOperatorOrValue;
+                }
+                clone[index] = value;
+            }
+        }
+        return clone;
+    };
+}
+
+/**
+ * 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) {
@@ -193,5 +413,5 @@ function removeItem(selector) {
  * Generated bundle index. Do not edit.
  */
 
-export { append, compose, iif, insertItem, isPredicate, isStateOperator, patch, removeItem, safePatch, updateItem };
+export { append, compose, iif, insertItem, isPredicate, isStateOperator, patch, removeItem, safePatch, updateItem, updateItems };
 //# sourceMappingURL=ngxs-store-operators.mjs.map

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":"AAEO,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO;AAIpC,MAAM,UAAU,GAAG,CAAC,KAAc,KAAK,OAAO,KAAK,IAAI,UAAU;AAE1D,MAAM,eAAe,GAAG;AAIxB,MAAM,WAAW,GAAG;AAIpB,MAAM,QAAQ,GAAG,CAAC,KAAc,KAAsB,OAAO,KAAK,KAAK,QAAQ;AAE/E,MAAM,YAAY,GAAG,CAAC,KAAa,KAAK,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,KAAK,KAAK,CAAC,CAAC;;ACflF;;AAEG;AACG,SAAU,MAAM,CAAI,KAAmB,EAAA;IAC3C,OAAO,SAAS,cAAc,CAAC,QAA4B,EAAA;;;AAGzD,QAAA,MAAM,6BAA6B,GAAG,CAAC,CAAC,KAAK,IAAI,CAAC,KAAK,CAAC,MAAM,KAAK,QAAQ;QAC3E,IAAI,6BAA6B,EAAE;AACjC,YAAA,OAAO,QAA0B;;AAGnC,QAAA,IAAI,OAAO,CAAC,QAAQ,CAAC,EAAE;AACrB,YAAA,OAAO,QAAQ,CAAC,MAAM,CAAC,KAAsC,CAAC;;;;AAKhE,QAAA,OAAO,KAAuB;AAChC,KAAC;AACH;;ACrBgB,SAAA,OAAO,CAAI,GAAG,SAAsC,EAAA;IAClE,OAAO,SAAS,eAAe,CAAC,QAA0B,EAAA;AACxD,QAAA,OAAO,SAAS,CAAC,MAAM,CACrB,CAAC,WAAW,EAAE,QAAQ,KAAK,QAAQ,CAAC,WAA+B,CAAC,EACpE,QAAa,CACd;AACH,KAAC;AACH;;ACLA,SAAS,aAAa,CACpB,eAAqC,EACrC,QAA0B,EAAA;;;AAI1B,IAAA,IAAI,eAAe,CAAC,eAAe,CAAC,EAAE;AACpC,QAAA,MAAM,KAAK,GAAG,eAAe,CAAC,QAAQ,CAAC;AACvC,QAAA,OAAO,KAAU;;;;;AAMnB,IAAA,IAAI,eAAe,KAAK,SAAS,EAAE;AACjC,QAAA,OAAO,QAAa;;AAGtB,IAAA,OAAO,eAAoB;AAC7B;AAEA;;;;;;AAMG;SACa,GAAG,CACjB,SAA0C,EAC1C,mBAAkD,EAClD,mBAAmD,EAAA;IAEnD,OAAO,SAAS,WAAW,CAAC,QAA0B,EAAA;;AAEpD,QAAA,IAAI,MAAM,GAAG,CAAC,CAAC,SAAS;;AAExB,QAAA,IAAI,WAAW,CAAC,SAAS,CAAC,EAAE;AAC1B,YAAA,MAAM,GAAG,SAAS,CAAC,QAAa,CAAC;;QAGnC,IAAI,MAAM,EAAE;AACV,YAAA,OAAO,aAAa,CAAI,mBAA2C,EAAE,QAAQ,CAAC;;AAGhF,QAAA,OAAO,aAAa,CAAI,mBAA4C,EAAE,QAAQ,CAAC;AACjF,KAAC;AACH;;AChDA;;;AAGG;AACa,SAAA,UAAU,CAAI,KAAiB,EAAE,cAAuB,EAAA;IACtE,OAAO,SAAS,kBAAkB,CAAC,QAA4B,EAAA;;;AAG7D,QAAA,IAAI,KAAK,IAAI,IAAI,IAAI,QAAQ,EAAE;AAC7B,YAAA,OAAO,QAAe;;;AAIxB,QAAA,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE;YACtB,OAAO,CAAC,KAAqB,CAAC;;AAGhC,QAAA,MAAM,KAAK,GAAG,QAAQ,CAAC,KAAK,EAAE;QAE9B,IAAI,KAAK,GAAG,CAAC;;;;AAKb,QAAA,IAAI,cAAe,GAAG,CAAC,EAAE;YACvB,KAAK,GAAG,cAAe;;QAGzB,KAAK,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,EAAE,KAAqB,CAAC;AAC7C,QAAA,OAAO,KAAK;AACd,KAAC;AACH;;AC3BM,SAAU,KAAK,CACnB,WAAmC,EAAA;IAEnC,OAAO,SAAS,kBAAkB,CAAC,QAA0B,EAAA;QAC3D,IAAI,KAAK,GAAG,IAAI;AAChB,QAAA,KAAK,MAAM,CAAC,IAAI,WAAW,EAAE;AAC3B,YAAA,MAAM,QAAQ,GAAG,WAAW,CAAC,CAAC,CAAC;AAC/B,YAAA,MAAM,iBAAiB,GAAG,QAAQ,GAAG,CAAC,CAAC;AACvC,YAAA,MAAM,YAAY,GAAG,eAAe,CAAC,QAAQ;AAC3C,kBAAE,QAAQ,CAAM,iBAAiB;kBAC/B,QAAQ;AACZ,YAAA,IAAI,YAAY,KAAK,iBAAiB,EAAE;gBACtC,IAAI,CAAC,KAAK,EAAE;AACV,oBAAA,KAAK,GAAG,EAAE,GAAS,QAAS,EAAE;;AAEhC,gBAAA,KAAK,CAAC,CAAC,CAAC,GAAG,YAAY;;;QAG3B,OAAO,KAAK,IAAI,QAAQ;AAC1B,KAAC;AACH;;ACxBM,SAAU,SAAS,CACvB,SAAiC,EAAA;AAEjC,IAAA,MAAM,OAAO,GAAG,KAAK,CAAC,SAA0B,CAE/C;IACD,OAAO,SAAS,WAAW,CAAC,QAA0B,EAAA;AACpD,QAAA,OAAO,OAAO,CAAC,QAAQ,IAAK,EAA8C,CAAC;AAC7E,KAAC;AACH;;ACRA;;;;;AAKG;AACa,SAAA,UAAU,CACxB,QAAwC,EACxC,eAAuD,EAAA;IAEvD,OAAO,SAAS,kBAAkB,CAAC,QAA4B,EAAA;AAC7D,QAAA,IAAI,KAAK,GAAG,CAAC,CAAC;AAEd,QAAA,IAAI,WAAW,CAAC,QAAQ,CAAC,EAAE;AACzB,YAAA,KAAK,GAAG,QAAQ,CAAC,SAAS,CAAC,QAAwB,CAAC;;AAC/C,aAAA,IAAI,QAAQ,CAAC,QAAQ,CAAC,EAAE;YAC7B,KAAK,GAAG,QAAQ;;AAGlB,QAAA,IAAI,YAAY,CAAC,KAAK,CAAC,EAAE;AACvB,YAAA,OAAO,QAAe;;QAGxB,IAAI,KAAK,GAAM,IAAK;;;QAGpB,MAAM,kBAAkB,GAAG,eAAuC;AAClE,QAAA,IAAI,eAAe,CAAC,kBAAkB,CAAC,EAAE;YACvC,KAAK,GAAG,kBAAkB,CAAC,QAAQ,CAAC,KAAK,CAAqB,CAAC;;aAC1D;YACL,KAAK,GAAG,kBAAkB;;;;AAK5B,QAAA,IAAI,KAAK,KAAK,QAAQ,CAAC,KAAK,CAAC,EAAE;AAC7B,YAAA,OAAO,QAAe;;AAGxB,QAAA,MAAM,KAAK,GAAG,QAAQ,CAAC,KAAK,EAAE;AAC9B,QAAA,KAAK,CAAC,KAAK,CAAC,GAAG,KAAU;AACzB,QAAA,OAAO,KAAK;AACd,KAAC;AACH;;AC5CA;;AAEG;AACG,SAAU,UAAU,CAAI,QAAwC,EAAA;IACpE,OAAO,SAAS,kBAAkB,CAAC,QAA4B,EAAA;AAC7D,QAAA,IAAI,KAAK,GAAG,CAAC,CAAC;AAEd,QAAA,IAAI,WAAW,CAAC,QAAQ,CAAC,EAAE;AACzB,YAAA,KAAK,GAAG,QAAQ,CAAC,SAAS,CAAC,QAAQ,CAAC;;AAC/B,aAAA,IAAI,QAAQ,CAAC,QAAQ,CAAC,EAAE;YAC7B,KAAK,GAAG,QAAQ;;AAGlB,QAAA,IAAI,YAAY,CAAC,KAAK,CAAC,EAAE;AACvB,YAAA,OAAO,QAAe;;AAGxB,QAAA,MAAM,KAAK,GAAG,QAAQ,CAAC,KAAK,EAAE;AAC9B,QAAA,KAAK,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC;AACtB,QAAA,OAAO,KAAK;AACd,KAAC;AACH;;ACxBA;;;;AAIG;;ACJH;;AAEG;;;;"}
+{"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/update-items.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 { type StateOperator, type ExistingState, type NoInfer } from './types';\nimport { isStateOperator, type Predicate } from './utils';\n\n/**\n * Replaces or transforms every array element that matches the predicate.\n * Unlike `updateItem`, which stops at the first match, this operator walks\n * the entire array so all qualifying elements are updated in one pass.\n *\n * Always returns a new array reference, even when no elements matched or the\n * values produced by the operator are identical to the originals. Use\n * `updateItem` instead when only a single element needs updating and\n * referential equality on no-op updates matters.\n *\n * @param selector - Predicate used to decide which elements to update.\n * @param operatorOrValue - Replacement value, or a state operator applied\n * to each matching element when a derived update is needed.\n *\n * @example\n * ```ts\n * // Mark every inactive animal as active in one setState call.\n * ctx.setState(\n *   patch<AnimalsStateModel>({\n *     animals: updateItems<Animal>(\n *       animal => !animal.active,\n *       patch({ active: true })\n *     )\n *   })\n * );\n * ```\n */\nexport function updateItems<T>(\n  selector: NoInfer<Predicate<T>>,\n  operatorOrValue: NoInfer<T> | NoInfer<StateOperator<T>>\n) {\n  return function updateItemsOperator(existing: ExistingState<T[]>): T[] {\n    if (!Array.isArray(existing)) {\n      return [] as T[];\n    } else if (existing.length === 0) {\n      return existing as T[];\n    }\n\n    const clone = existing.slice();\n    for (let index = 0; index < clone.length; index++) {\n      let value = clone[index];\n      if (selector(value)) {\n        const theOperatorOrValue = operatorOrValue as T | StateOperator<T>;\n        if (isStateOperator(theOperatorOrValue)) {\n          value = theOperatorOrValue(value as ExistingState<T>);\n        } else {\n          value = theOperatorOrValue;\n        }\n        clone[index] = value;\n      }\n    }\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 { updateItems } from './update-items';\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/operators/index.d.ts

@@ -55,10 +55,43 @@ type ExistingState<T> = T extends any ? ɵAsReadonly<T> : never;
 type StateOperator<T> = (existing: ExistingState<T>) => T;
 
 /**
- * @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])
+ *   })
+ * );
+ * ```
  */
 declare function append<T>(items: NoInfer<T[]>): StateOperator<T[]>;
 
+/**
+ * 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) })
+ *   )
+ * );
+ * ```
+ */
 declare function compose<T>(...operators: NoInfer<StateOperator<T>[]>): StateOperator<T>;
 
 type Predicate<T = any> = (value: T | Readonly<T>) => boolean;
@@ -66,17 +99,62 @@ declare const isStateOperator: <T>(value: T | StateOperator<T>) => value is Stat
 declare const isPredicate: <T>(value: Predicate<T> | boolean | number) => value is Predicate<T>;
 
 /**
- * @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])
+ *     )
+ *   })
+ * );
+ * ```
  */
 declare function iif<T>(condition: NoInfer<Predicate<T>> | boolean, trueOperatorOrValue: NoInfer<StateOperator<T> | T>, elseOperatorOrValue?: NoInfer<StateOperator<T> | T>): StateOperator<T>;
 
 /**
- * @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)
+ *   })
+ * );
+ * ```
  */
 declare function insertItem<T>(value: NoInfer<T>, beforePosition?: number): StateOperator<T[]>;
 
@@ -84,22 +162,140 @@ type NotUndefined<T> = T extends undefined ? never : T;
 type ɵPatchSpec<T> = {
     [P in keyof T]?: T[P] | StateOperator<NotUndefined<T[P]>>;
 };
+/**
+ * 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
+ *         })
+ *       })
+ *     })
+ *   })
+ * );
+ * ```
+ */
 declare function patch<T extends Record<string, any>>(patchObject: NoInfer<ɵPatchSpec<T>>): StateOperator<T>;
 
+/**
+ * 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 })
+ *   })
+ * );
+ * ```
+ */
 declare function safePatch<T extends object>(patchSpec: NoInfer<ɵPatchSpec<T>>): StateOperator<T>;
 
 /**
- * @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
+ *     )
+ *   })
+ * );
+ * ```
  */
 declare function updateItem<T>(selector: number | NoInfer<Predicate<T>>, operatorOrValue: NoInfer<T> | NoInfer<StateOperator<T>>): StateOperator<T[]>;
 
 /**
- * @param selector - index or predicate to remove an item from an array by
+ * Replaces or transforms every array element that matches the predicate.
+ * Unlike `updateItem`, which stops at the first match, this operator walks
+ * the entire array so all qualifying elements are updated in one pass.
+ *
+ * Always returns a new array reference, even when no elements matched or the
+ * values produced by the operator are identical to the originals. Use
+ * `updateItem` instead when only a single element needs updating and
+ * referential equality on no-op updates matters.
+ *
+ * @param selector - Predicate used to decide which elements to update.
+ * @param operatorOrValue - Replacement value, or a state operator applied
+ * to each matching element when a derived update is needed.
+ *
+ * @example
+ * ```ts
+ * // Mark every inactive animal as active in one setState call.
+ * ctx.setState(
+ *   patch<AnimalsStateModel>({
+ *     animals: updateItems<Animal>(
+ *       animal => !animal.active,
+ *       patch({ active: true })
+ *     )
+ *   })
+ * );
+ * ```
+ */
+declare function updateItems<T>(selector: NoInfer<Predicate<T>>, operatorOrValue: NoInfer<T> | NoInfer<StateOperator<T>>): (existing: ExistingState<T[]>) => T[];
+
+/**
+ * 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)
+ *   })
+ * );
+ * ```
  */
 declare function removeItem<T>(selector: number | NoInfer<Predicate<T>>): StateOperator<T[]>;
 
-export { append, compose, iif, insertItem, isPredicate, isStateOperator, patch, removeItem, safePatch, updateItem };
+export { append, compose, iif, insertItem, isPredicate, isStateOperator, patch, removeItem, safePatch, updateItem, updateItems };
 export type { ExistingState, NoInfer, Predicate, StateOperator, ɵPatchSpec };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngxs/store",
-  "version": "21.0.0-dev.master-a4d1cfd",
+  "version": "21.0.0-dev.master-31acb66",
   "license": "MIT",
   "sideEffects": false,
   "peerDependencies": {
@@ -18,14 +18,14 @@
       "types": "./index.d.ts",
       "default": "./fesm2022/ngxs-store.mjs"
     },
-    "./experimental": {
-      "types": "./experimental/index.d.ts",
-      "default": "./fesm2022/ngxs-store-experimental.mjs"
-    },
     "./internals": {
       "types": "./internals/index.d.ts",
       "default": "./fesm2022/ngxs-store-internals.mjs"
     },
+    "./experimental": {
+      "types": "./experimental/index.d.ts",
+      "default": "./fesm2022/ngxs-store-experimental.mjs"
+    },
     "./operators": {
       "types": "./operators/index.d.ts",
       "default": "./fesm2022/ngxs-store-operators.mjs"