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

package/index.d.ts

@@ -506,6 +506,12 @@ declare function withNgxsNoopExecutionStrategy(): i0.EnvironmentProviders;
  */
 declare function withNgxsPendingTasks(): i0.EnvironmentProviders;
 
+declare class StateContextDestroyedError extends Error {
+    readonly path: string;
+    readonly name = "StateContextDestroyedError";
+    constructor(path: string);
+}
+
 /**
  * This function provides global store providers and initializes the store.
  *
@@ -718,5 +724,5 @@ declare function registerNgxsPlugin(plugin: Type<NgxsPlugin> | NgxsPluginFn): vo
 
 declare function ɵprovideNgxsInternalStateTokens(): i0.EnvironmentProviders;
 
-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 };
 export type { ActionCompletion, ActionContext, ActionDef, ActionMap, ActionType, NgxsAfterBootstrap, NgxsDevelopmentOptions, NgxsModuleOptions, NgxsOnChanges, NgxsOnInit, NgxsUnhandledErrorContext, PropertySelectors, SelectorMap, StateContext, TypedSelector, ɵSelectorDef, ɵSelectorFunc, ɵSelectorReturnType, ɵStateSelector };

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,20 +162,109 @@ 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
+ * 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[]>;
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngxs/store",
-  "version": "21.0.0-dev.master-f8041d1",
+  "version": "21.0.0-dev.master-35d18c0",
   "license": "MIT",
   "sideEffects": false,
   "peerDependencies": {