@ngxs/store 21.0.0 → 22.0.0-dev.master-d79b246

package/index.d.ts

@@ -1,8 +1,7 @@
 import * as i0 from '@angular/core';
 import { ModuleWithProviders, Signal, EnvironmentProviders, Type } from '@angular/core';
-import { ɵActionOptions as _ActionOptions, StateToken, ɵSharedSelectorOptions as _SharedSelectorOptions, ɵStateClass as _StateClass, ɵStoreOptions as _StoreOptions } from '@ngxs/store/internals';
-export { ɵActionOptions as ActionOptions, StateToken } from '@ngxs/store/internals';
-import * as rxjs from 'rxjs';
+import { ɵSharedSelectorOptions as _SharedSelectorOptions, ɵStateClass as _StateClass, ActionType, ɵActionOptions as _ActionOptions, ActionDef, StateToken, ɵStoreOptions as _StoreOptions, ɵNgxsDevelopmentOptions as _NgxsDevelopmentOptions, ɵPlainObjectOf as _PlainObjectOf, ɵActionHandlerMetaData as _ActionHandlerMetaData, ɵStateClassInternal as _StateClassInternal } from '@ngxs/store/internals';
+export { ActionDef, ɵActionOptions as ActionOptions, ActionType, ɵNgxsDevelopmentOptions as NgxsDevelopmentOptions, StateToken } from '@ngxs/store/internals';
 import { Observable, Subscription, OperatorFunction } from 'rxjs';
 import { StateOperator } from '@ngxs/store/operators';
 export { StateOperator } from '@ngxs/store/operators';
@@ -118,22 +117,23 @@ declare class NgxsFeatureModule {
     static ɵinj: i0.ɵɵInjectorDeclaration<NgxsFeatureModule>;
 }
 
+/**
+ * @deprecated Use `provideStore()` and `provideStates()` instead.
+ */
 declare class NgxsModule {
+    /**
+     * @deprecated Use `provideStore()` instead.
+     */
     static forRoot(states?: _StateClass[], options?: NgxsModuleOptions): ModuleWithProviders<NgxsRootModule>;
+    /**
+     * @deprecated Use `provideStates()` instead.
+     */
     static forFeature(states?: _StateClass[]): ModuleWithProviders<NgxsFeatureModule>;
     static ɵfac: i0.ɵɵFactoryDeclaration<NgxsModule, never>;
     static ɵmod: i0.ɵɵNgModuleDeclaration<NgxsModule, never, never, never>;
     static ɵinj: i0.ɵɵInjectorDeclaration<NgxsModule>;
 }
 
-interface ActionDef<TArgs extends any[] = any[], TReturn = any> {
-    type: string;
-    new (...args: TArgs): TReturn;
-}
-type ActionType = ActionDef | {
-    type: string;
-};
-
 /**
  * Given an action class, returns its payload.
  */
@@ -176,10 +176,7 @@ type MappedResult<TSelectorMap> = {
 };
 declare function createModelSelector<T extends SelectorMap$1>(selectorMap: T): ModelSelector<T>;
 
-type KeysToValues<T, Keys extends (keyof T)[]> = {
-    [Index in keyof Keys]: Keys[Index] extends keyof T ? T[Keys[Index]] : never;
-};
-declare function createPickSelector<TModel, Keys extends (keyof TModel)[]>(selector: TypedSelector<TModel>, keys: [...Keys]): (...props: KeysToValues<TModel, Keys>) => Pick<TModel, Keys[number]>;
+declare function createPickSelector<TModel, Keys extends (keyof TModel)[]>(selector: TypedSelector<TModel>, keys: [...Keys]): (...props: (NonNullable<TModel>[Keys[number]] | undefined)[]) => Pick<TModel, Keys[number]>;
 
 type PropertySelectors<TModel> = {
     [P in keyof NonNullable<TModel>]-?: (model: TModel) => TModel extends null | undefined ? undefined : NonNullable<TModel>[P];
@@ -199,18 +196,13 @@ type SelectorArg = ɵSelectorDef<any>;
  * @param originalFn The original function being made into a selector
  * @param creationMetadata
  */
-declare function createSelector<S1 extends SelectorArg, TProjector extends (s1: ɵSelectorReturnType<S1>) => any>(selectors: [S1], projector: TProjector, creationMetadata?: Partial<CreationMetadata>): TProjector;
-declare function createSelector<S1 extends SelectorArg, S2 extends SelectorArg, TProjector extends (s1: ɵSelectorReturnType<S1>, s2: ɵSelectorReturnType<S2>) => any>(selectors: [S1, S2], projector: TProjector, creationMetadata?: Partial<CreationMetadata>): TProjector;
-declare function createSelector<S1 extends SelectorArg, S2 extends SelectorArg, S3 extends SelectorArg, TProjector extends (s1: ɵSelectorReturnType<S1>, s2: ɵSelectorReturnType<S2>, s3: ɵSelectorReturnType<S3>) => any>(selectors: [S1, S2, S3], projector: TProjector, creationMetadata?: Partial<CreationMetadata>): TProjector;
-declare function createSelector<S1 extends SelectorArg, S2 extends SelectorArg, S3 extends SelectorArg, S4 extends SelectorArg, TProjector extends (s1: ɵSelectorReturnType<S1>, s2: ɵSelectorReturnType<S2>, s3: ɵSelectorReturnType<S3>, s4: ɵSelectorReturnType<S4>) => any>(selectors: [S1, S2, S3, S4], projector: TProjector, creationMetadata?: Partial<CreationMetadata>): TProjector;
-declare function createSelector<S1 extends SelectorArg, S2 extends SelectorArg, S3 extends SelectorArg, S4 extends SelectorArg, S5 extends SelectorArg, TProjector extends (s1: ɵSelectorReturnType<S1>, s2: ɵSelectorReturnType<S2>, s3: ɵSelectorReturnType<S3>, s4: ɵSelectorReturnType<S4>, s5: ɵSelectorReturnType<S5>) => any>(selectors: [S1, S2, S3, S4, S5], projector: TProjector, creationMetadata?: Partial<CreationMetadata>): TProjector;
-declare function createSelector<S1 extends SelectorArg, S2 extends SelectorArg, S3 extends SelectorArg, S4 extends SelectorArg, S5 extends SelectorArg, S6 extends SelectorArg, TProjector extends (s1: ɵSelectorReturnType<S1>, s2: ɵSelectorReturnType<S2>, s3: ɵSelectorReturnType<S3>, s4: ɵSelectorReturnType<S4>, s5: ɵSelectorReturnType<S5>, s6: ɵSelectorReturnType<S6>) => any>(selectors: [S1, S2, S3, S4, S5, S6], projector: TProjector, creationMetadata?: Partial<CreationMetadata>): TProjector;
-declare function createSelector<S1 extends SelectorArg, S2 extends SelectorArg, S3 extends SelectorArg, S4 extends SelectorArg, S5 extends SelectorArg, S6 extends SelectorArg, S7 extends SelectorArg, TProjector extends (s1: ɵSelectorReturnType<S1>, s2: ɵSelectorReturnType<S2>, s3: ɵSelectorReturnType<S3>, s4: ɵSelectorReturnType<S4>, s5: ɵSelectorReturnType<S5>, s6: ɵSelectorReturnType<S6>, s7: ɵSelectorReturnType<S7>) => any>(selectors: [S1, S2, S3, S4, S5, S6, S7], projector: TProjector, creationMetadata?: Partial<CreationMetadata>): TProjector;
-declare function createSelector<S1 extends SelectorArg, S2 extends SelectorArg, S3 extends SelectorArg, S4 extends SelectorArg, S5 extends SelectorArg, S6 extends SelectorArg, S7 extends SelectorArg, S8 extends SelectorArg, TProjector extends (s1: ɵSelectorReturnType<S1>, s2: ɵSelectorReturnType<S2>, s3: ɵSelectorReturnType<S3>, s4: ɵSelectorReturnType<S4>, s5: ɵSelectorReturnType<S5>, s6: ɵSelectorReturnType<S6>, s7: ɵSelectorReturnType<S7>, s8: ɵSelectorReturnType<S8>) => any>(selectors: [S1, S2, S3, S4, S5, S6, S7, S8], projector: TProjector, creationMetadata?: Partial<CreationMetadata>): TProjector;
-declare function createSelector<T extends (...args: any[]) => any>(selectors: SelectorArg[] | undefined, projector: T, creationMetadata?: Partial<CreationMetadata>): T;
+declare function createSelector<Selectors extends SelectorArg[], TProjector extends (...selectorResult: {
+    [K in keyof Selectors]: ɵSelectorReturnType<Selectors[K]>;
+}) => any>(selectors: [...Selectors], projector: TProjector, creationMetadata?: Partial<CreationMetadata>): TProjector;
 
 type ActionOrArrayOfActions<T> = T extends (infer U)[] ? NonNullable<U>[] : NonNullable<T>;
 declare class Store {
+    private _injector?;
     private _stateStream;
     private _internalStateOperations;
     private _config;
@@ -465,19 +457,19 @@ declare class NgxsUnhandledErrorHandler {
     static ɵprov: i0.ɵɵInjectableDeclaration<NgxsUnhandledErrorHandler>;
 }
 
-interface NgxsDevelopmentOptions {
-    warnOnUnhandledActions: true | {
-        ignore: ActionType[];
-    };
-}
-
+/**
+ * @deprecated Use `withNgxsDevelopmentOptions()` instead.
+ */
 declare class NgxsDevelopmentModule {
-    static forRoot(options: NgxsDevelopmentOptions): ModuleWithProviders<NgxsDevelopmentModule>;
+    /**
+     * @deprecated Use `withNgxsDevelopmentOptions()` instead.
+     */
+    static forRoot(options: _NgxsDevelopmentOptions): ModuleWithProviders<NgxsDevelopmentModule>;
     static ɵfac: i0.ɵɵFactoryDeclaration<NgxsDevelopmentModule, never>;
     static ɵmod: i0.ɵɵNgModuleDeclaration<NgxsDevelopmentModule, never, never, never>;
     static ɵinj: i0.ɵɵInjectorDeclaration<NgxsDevelopmentModule>;
 }
-declare function withNgxsDevelopmentOptions(options: NgxsDevelopmentOptions): i0.EnvironmentProviders;
+declare function withNgxsDevelopmentOptions(options: _NgxsDevelopmentOptions): i0.EnvironmentProviders;
 
 declare class NgxsUnhandledActionsLogger {
     /**
@@ -516,6 +508,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.
  *
@@ -609,7 +607,12 @@ declare function withNgxsPreboot(prebootFn: VoidFunction): i0.EnvironmentProvide
  */
 declare function select<T>(selector: TypedSelector<T>): Signal<T>;
 
-declare function dispatch<TArgs extends any[]>(ActionType: ActionDef<TArgs>): (...args: TArgs) => rxjs.Observable<void>;
+declare class AsyncReturnType<T> extends Observable<T> implements PromiseLike<void> {
+    private dispatchResult$;
+    constructor(dispatchResult$: Observable<T>);
+    then<TResult1 = void, TResult2 = never>(onfulfilled?: ((value: void) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null): PromiseLike<TResult1 | TResult2>;
+}
+declare function dispatch<TArgs extends any[]>(ActionType: ActionDef<TArgs>): (...args: TArgs) => AsyncReturnType<void>;
 
 type SelectorMap = Record<string, TypedSelector<unknown>>;
 declare function createSelectMap<T extends SelectorMap>(selectorMap: T): { readonly [K in keyof T]: Signal<ɵSelectorReturnType<T[K]>>; };
@@ -650,7 +653,93 @@ interface DefaultExport<T> {
  */
 declare function lazyProvider(factory: () => Promise<EnvironmentProviders | DefaultExport<EnvironmentProviders>>): () => Promise<boolean>;
 
+/**
+ * Dynamically registers an NGXS plugin in the current injection context.
+ *
+ * This function allows you to register NGXS plugins at runtime, creating an isolated
+ * environment injector for the plugin. The plugin is automatically cleaned up when
+ * the injection context is destroyed. In development mode, the function validates
+ * that the same plugin is not registered multiple times.
+ *
+ * @param plugin - The NGXS plugin to register. Can be either a class type implementing
+ *                 `NgxsPlugin` or a plugin function (`NgxsPluginFn`).
+ *
+ * @throws {Error} Throws an error if called outside of an injection context.
+ * @throws {Error} In development mode, throws an error if the plugin has already been registered.
+ *
+ * @remarks
+ * - Must be called within an injection context (e.g., constructor, field initializer, or `runInInjectionContext`).
+ * - The created environment injector is automatically destroyed when the parent context is destroyed.
+ * - Duplicate plugin registration is only checked in development mode for performance reasons.
+ *
+ * @example
+ * ```ts
+ * // Register a plugin class
+ * import { MyThirdPartyIntegrationPlugin } from './plugins/third-party.plugin';
+ *
+ * @Component({
+ *   selector: 'app-root',
+ *   template: '...'
+ * })
+ * export class AppComponent {
+ *   constructor() {
+ *     registerNgxsPlugin(MyThirdPartyIntegrationPlugin);
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Register a plugin function
+ * import { myThirdPartyIntegrationPluginFn } from './plugins/third-party.plugin';
+ *
+ * @Component({
+ *   selector: 'app-feature',
+ *   template: '...'
+ * })
+ * export class FeatureComponent {
+ *   constructor() {
+ *     registerNgxsPlugin(myThirdPartyIntegrationPluginFn);
+ *   }
+ * }
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Register conditionally based on environment
+ * import { MyDevtoolsPlugin } from './plugins/devtools.plugin';
+ *
+ * @Component({
+ *   selector: 'app-root',
+ *   template: '...'
+ * })
+ * export class AppComponent {
+ *   constructor() {
+ *     if (ngDevMode) {
+ *       registerNgxsPlugin(MyDevtoolsPlugin);
+ *     }
+ *   }
+ * }
+ * ```
+ */
+declare function registerNgxsPlugin(plugin: Type<NgxsPlugin> | NgxsPluginFn): void;
+
+type StatesByName = _PlainObjectOf<_StateClassInternal>;
+interface MappedStore {
+    name: string;
+    isInitialised: boolean;
+    actions: _PlainObjectOf<_ActionHandlerMetaData[]>;
+    defaults: any;
+    instance: any;
+    path: string;
+}
+
 declare function ɵprovideNgxsInternalStateTokens(): i0.EnvironmentProviders;
+declare function ɵgetTypedNgxsStateFactory(stateFactory: any): {
+    states: MappedStore[];
+    statesByName: StatesByName;
+    statePaths: _PlainObjectOf<string>;
+};
 
-export { Action, ActionDirector, ActionStatus, Actions, 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, 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 };
+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, ɵgetTypedNgxsStateFactory, ɵprovideNgxsInternalStateTokens };
+export type { ActionCompletion, ActionContext, ActionMap, NgxsAfterBootstrap, NgxsModuleOptions, NgxsOnChanges, NgxsOnInit, NgxsUnhandledErrorContext, PropertySelectors, SelectorMap, StateContext, TypedSelector, ɵSelectorDef, ɵSelectorFunc, ɵSelectorReturnType, ɵStateSelector };

package/internals/index.d.ts

@@ -1,6 +1,6 @@
 import * as i0 from '@angular/core';
 import { InjectionToken, Signal } from '@angular/core';
-import { Observable, BehaviorSubject, Subject, MonoTypeOperatorFunction } from 'rxjs';
+import { BehaviorSubject, Subject, MonoTypeOperatorFunction, Observable } from 'rxjs';
 
 declare class StateToken<T = void> {
     private readonly _name;
@@ -94,7 +94,16 @@ interface ɵActionHandlerMetaData {
     fn: string | symbol;
     options: ɵActionOptions;
     type: string;
+    /** The action class this handler was registered for, used to detect `type` collisions in dev mode. */
+    actionClass: unknown;
 }
+interface ActionDef<TArgs extends any[] = any[], TReturn = any> {
+    type: string;
+    new (...args: TArgs): TReturn;
+}
+type ActionType = ActionDef | {
+    type: string;
+};
 
 /**
  * Ensures metadata is attached to the class and returns it.
@@ -127,7 +136,7 @@ declare function ɵgetSelectorMetadata(target: any): ɵSelectorMetaDataModel;
  *
  * @ignore
  */
-declare function ɵmemoize<T extends (...args: any[]) => any>(func: T, equalityCheck?: (value1: any, value2: any) => boolean): T;
+declare function ɵmemoize<T extends (...args: any[]) => any>(fn: T, originalFn?: T): T;
 
 declare class ɵInitialState {
     private static _value;
@@ -136,12 +145,7 @@ declare class ɵInitialState {
 }
 declare const ɵINITIAL_STATE_TOKEN: InjectionToken<ɵPlainObject>;
 
-declare class ɵNgxsAppBootstrappedState extends BehaviorSubject<boolean> {
-    constructor();
-    bootstrap(): void;
-    static ɵfac: i0.ɵɵFactoryDeclaration<ɵNgxsAppBootstrappedState, never>;
-    static ɵprov: i0.ɵɵInjectableDeclaration<ɵNgxsAppBootstrappedState>;
-}
+declare const ɵNGXS_APP_BOOTSTRAP_STATE: InjectionToken<i0.WritableSignal<boolean>>;
 
 declare const ɵNGXS_STATE_FACTORY: InjectionToken<any>;
 declare const ɵNGXS_STATE_CONTEXT_FACTORY: InjectionToken<any>;
@@ -207,12 +211,29 @@ declare const ɵdefineProperty: <T>(o: T, p: PropertyKey, attributes: PropertyDe
 type ActionHandlerFn = (action: any) => Observable<unknown>;
 declare class ɵNgxsActionRegistry {
     private readonly _actionTypeToHandlersMap;
+    private readonly _actionTypeToClass?;
     constructor();
     get(type: string): Set<ActionHandlerFn> | undefined;
-    register(type: string, handler: ActionHandlerFn): () => void;
+    register(type: string, handler: ActionHandlerFn, actionClass?: unknown): () => void;
     static ɵfac: i0.ɵɵFactoryDeclaration<ɵNgxsActionRegistry, never>;
     static ɵprov: i0.ɵɵInjectableDeclaration<ɵNgxsActionRegistry>;
 }
 
-export { StateToken, ɵINITIAL_STATE_TOKEN, ɵInitialState, ɵMETA_KEY, ɵMETA_OPTIONS_KEY, ɵNGXS_STATE_CONTEXT_FACTORY, ɵNGXS_STATE_FACTORY, ɵNgxsActionRegistry, ɵNgxsAppBootstrappedState, ɵOrderedBehaviorSubject, ɵOrderedSubject, ɵSELECTOR_META_KEY, ɵStateStream, ɵdefineProperty, ɵensureSelectorMetadata, ɵensureStoreMetadata, ɵgetSelectorMetadata, ɵgetStoreMetadata, ɵhasOwnProperty, ɵmemoize, ɵwrapObserverCalls };
-export type { ɵActionHandlerMetaData, ɵActionOptions, ɵExtractTokenType, ɵMetaDataModel, ɵPlainObject, ɵPlainObjectOf, ɵRuntimeSelectorContext, ɵSelectFromRootState, ɵSelectorFactory, ɵSelectorMetaDataModel, ɵSharedSelectorOptions, ɵStateClass, ɵStateClassInternal, ɵStateToken, ɵStoreOptions, ɵTokenName };
+interface ɵNgxsDevelopmentOptions {
+    warnOnNewReferenceWithIdenticalValue?: {
+        isEqual: (a: unknown, b: unknown) => boolean;
+    };
+    warnOnUnhandledActions: true | {
+        ignore: ActionType[];
+    };
+    /**
+     * Warns when two different action classes are declared with the same `type` string.
+     * Since handlers are looked up by `type`, every handler registered for that type runs
+     * whenever either action is dispatched, even though their payloads may differ.
+     */
+    warnOnDuplicateActionTypes?: boolean;
+}
+declare const ɵNGXS_DEVELOPMENT_OPTIONS: InjectionToken<ɵNgxsDevelopmentOptions>;
+
+export { StateToken, ɵINITIAL_STATE_TOKEN, ɵInitialState, ɵMETA_KEY, ɵMETA_OPTIONS_KEY, ɵNGXS_APP_BOOTSTRAP_STATE, ɵNGXS_DEVELOPMENT_OPTIONS, ɵNGXS_STATE_CONTEXT_FACTORY, ɵNGXS_STATE_FACTORY, ɵNgxsActionRegistry, ɵOrderedBehaviorSubject, ɵOrderedSubject, ɵSELECTOR_META_KEY, ɵStateStream, ɵdefineProperty, ɵensureSelectorMetadata, ɵensureStoreMetadata, ɵgetSelectorMetadata, ɵgetStoreMetadata, ɵhasOwnProperty, ɵmemoize, ɵwrapObserverCalls };
+export type { ActionDef, ActionType, ɵActionHandlerMetaData, ɵActionOptions, ɵExtractTokenType, ɵMetaDataModel, ɵNgxsDevelopmentOptions, ɵPlainObject, ɵPlainObjectOf, ɵRuntimeSelectorContext, ɵSelectFromRootState, ɵSelectorFactory, ɵSelectorMetaDataModel, ɵSharedSelectorOptions, ɵStateClass, ɵStateClassInternal, ɵStateToken, ɵStoreOptions, ɵTokenName };

package/internals/testing/index.d.ts

@@ -1,6 +1,6 @@
 import { NgxsModuleOptions, Store } from '@ngxs/store';
 import * as i0 from '@angular/core';
-import { EnvironmentProviders, ModuleWithProviders } from '@angular/core';
+import { ModuleWithProviders, EnvironmentProviders } from '@angular/core';
 import { TestBedStatic } from '@angular/core/testing';
 import { ɵStateClass as _StateClass } from '@ngxs/store/internals';
 

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,162 @@ 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>;
 
 /**
- * @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
+ * 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>;
+
+/**
+ * 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.
+ *
+ * Returns the original array reference unchanged when no elements match the
+ * predicate, preserving referential equality for memoized selectors. A new
+ * array is returned only when at least one element was actually updated.
+ *
+ * @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, updateItem };
+/**
+ * Removes every array element that matches the predicate. Unlike `removeItem`,
+ * which stops at the first match, this operator walks the entire array so all
+ * qualifying elements are eliminated in one pass.
+ *
+ * Returns the original array reference when no elements matched, so memoized
+ * selectors are not invalidated by a no-op removal.
+ *
+ * @param selector - Predicate used to decide which elements to remove.
+ * Elements for which the predicate returns `true` are dropped; the rest are kept.
+ *
+ * @example
+ * ```ts
+ * // Remove all inactive animals in one setState call.
+ * ctx.setState(
+ *   patch<AnimalsStateModel>({
+ *     animals: removeItems<Animal>(animal => !animal.active)
+ *   })
+ * );
+ * ```
+ */
+declare function removeItems<T>(selector: NoInfer<Predicate<T>>): (existing: ExistingState<T[]>) => T[];
+
+export { append, compose, iif, insertItem, isPredicate, isStateOperator, patch, removeItem, removeItems, safePatch, updateItem, updateItems };
 export type { ExistingState, NoInfer, Predicate, StateOperator, ɵPatchSpec };

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@ngxs/store",
-  "version": "21.0.0",
+  "version": "22.0.0-dev.master-d79b246",
   "license": "MIT",
   "sideEffects": false,
   "peerDependencies": {
-    "@angular/core": ">=21.0.0 <22.0.0",
+    "@angular/core": ">=22.0.0 <23.0.0",
     "rxjs": ">=7.0.0"
   },
   "schematics": "./schematics/collection.json",
@@ -61,18 +61,9 @@
   ],
   "author": "Austin McDaniel",
   "contributors": [
-    {
-      "name": "Danny Blue"
-    },
-    {
-      "name": "Leon Radley"
-    },
     {
       "name": "Mark Whitfeld"
     },
-    {
-      "name": "Maxim Ivanov"
-    },
     {
       "name": "Artur Androsovych"
     }
@@ -85,4 +76,4 @@
     "type": "opencollective",
     "url": "https://opencollective.com/ngxs"
   }
-}
+}

package/schematics/src/utils/versions.json

@@ -1,3 +1,3 @@
 {
-  "@ngxs/store": "21.0.0"
+  "@ngxs/store": "22.0.0"
 }