feat(store): implement ActionDirector (#2329)

The `ActionDirector` allows you to attach action handlers to a state at any point after
initialization and gives you the ability to detach them when no longer needed.

Author: arturovt

CHANGELOG.md

@@ -6,6 +6,7 @@ $ npm install @ngxs/store@dev
 
 ### To become next patch version
 
+- Feature(store): Implement `ActionDirector` [#2329](https://github.com/ngxs/store/pull/2329)
 - Feature(store): Add `lazyProvider` utility [#2326](https://github.com/ngxs/store/pull/2326)
 - Feature(devtools-plugin): Add `serialize` option [#2337](https://github.com/ngxs/store/pull/2337)
 - Refactor: Replace `ngOnDestroy` with `DestroyRef` [#2289](https://github.com/ngxs/store/pull/2289)

docs/SUMMARY.md

@@ -22,8 +22,9 @@
   - [Overview](concepts/actions/README.md)
   - [Action Schematics](concepts/actions/schematics.md)
   - [Actions Life Cycle](concepts/actions/actions-life-cycle.md)
-  - [Action Handlers](concepts/actions/action-handlers.md)
+  - [Actions Stream](concepts/actions/actions-stream.md)
   - [Cancellation](concepts/actions/cancellation.md)
+  - [Dynamic Action Handlers](concepts/actions/dynamic-action-handlers.md)
   - [Monitoring Unhandled Actions](concepts/actions/monitoring-unhandled-actions.md)
 - [STATE](concepts/state/README.md)
   - [Overview](concepts/state/README.md)

docs/concepts/actions/action-handlers.md docs/concepts/actions/actions-stream.mddocs/concepts/actions/action-handlers.md renamed to docs/concepts/actions/actions-stream.md

@@ -1,21 +1,21 @@
-# Action Handlers
+# Actions Stream
 
 Before reading this article, we advise you to become acquainted with the [actions life cycle](./actions-life-cycle.md).
 
 Event sourcing involves modeling the state changes made by applications as an immutable sequence or “log” of events.
 Instead of focusing on current state, you focus on the changes that have occurred over time. It is the practice of
-modeling your system as a sequence of events. In NGXS, we called this Action Handlers.
+modeling your system as a sequence of events. In NGXS, we called this the Actions Stream.
 
 Typically actions directly correspond to state changes but it can be difficult to always make your component react
 based on state. As a side effect of this paradigm, we end up creating lots of intermediate state properties
-to do things like reset a form/etc. Action handlers let us drive our components based on state along with events
+to do things like reset a form/etc. The Actions Stream lets us drive our components based on state along with events
 that are emitted.
 
 For example, if we were to have a shopping cart and we were to delete an item out of it you might want to show
 a notification that it was successfully removed. In a pure state driven application, you might create some kind
-of message array to make the dialog show up. With Action Handlers, we can respond to the action directly.
+of message array to make the dialog show up. With the Actions Stream, we can respond to the action directly.
 
-The action handler is an Observable that receives all the actions dispatched before the state takes any action on it.
+The Actions Stream is an Observable that receives all the actions dispatched before the state takes any action on it.
 
 Actions in NGXS also have a lifecycle. Since any potential action can be async we tag actions showing when they are "DISPATCHED", "SUCCESSFUL", "CANCELED" or "ERRORED". This gives you the ability to react to actions at different points in their existence.
 
@@ -83,7 +83,7 @@ export const appConfig: ApplicationConfig = {
 };
 ```
 
-Action handlers can also be utilized in components. For example, considering the cart deletion scenario, we could use the following code:
+The Actions Stream can also be utilized in components. For example, considering the cart deletion scenario, we could use the following code:
 
 ```ts
 @Component({ ... })
@@ -96,7 +96,7 @@ export class CartComponent {
 }
 ```
 
-Also, remember to unsubscribe from the actions stream at the end:
+Also, remember to unsubscribe from the Actions Stream at the end:
 
 ```ts
 @Component({ ... })

docs/concepts/actions/dynamic-action-handlers.md

@@ -0,0 +1,96 @@
+# Dynamic Action Handlers
+
+Sometimes you need to attach action handlers dynamically after state initialization. For example, you might want to:
+
+- Add action handlers conditionally based on runtime conditions
+- Add action handlers for lazy-loaded modules
+- Add temporary action handlers that can be removed later
+
+How is a Dynamic Action Handler different to what the [Actions Stream](./actions-stream.md) gives you?
+
+- It gives you the ability to make changes to state from your handler
+- It participates in the standard [actions life cycle](./actions-life-cycle.md)
+  - The result of the handler will affect the completion result of the action
+  - The life cycle for the action will only complete once all dynamic handlers have completed too
+
+NGXS provides the `ActionDirector` service for registering Dynamic Action Handlers.
+
+## DISCLAIMER: Before you use it...
+
+Please bear in mind that this is a power user feature, and should not be used as a replacement for the typical action declarations within a state.
+
+- Overuse of Dynamic Action Handlers can lead to an application that is hard to understand and hard to determine the exact behavior of a state at a specific point in time
+- Co-location of the handlers with a state class is a massive benefit for a clean and predictable codebase. When using Dynamic Action Handlers, please consider this fact and try to honour this principle
+- The main intended use of this feature is for plugins and utilities that enhance state, so if you are doing something else, please check that you can't solve your problem with the simpler state constructs
+- Another potential use is for the lazy loading of action handler logic. This is a very specialised optimisation and should only be used if lazy loading the entire state with a route is not sufficient
+
+## The ActionDirector Service
+
+The `ActionDirector` allows you to attach action handlers to a state at any point after initialization and gives you the ability to detach them when no longer needed.
+
+### Attaching an Action Handler
+
+```ts
+import { ActionDirector, createSelector } from '@ngxs/store';
+import { inject, Injectable } from '@angular/core';
+
+// State token
+const COUNTRIES_STATE_TOKEN = new StateToken<string[]>('countries');
+
+// Action
+export class AddCountry {
+  static readonly type = '[Countries] Add Country';
+  constructor(public country: string) {}
+}
+
+@Injectable({ providedIn: 'root' })
+export class CountryService {
+  private actionDirector = inject(ActionDirector);
+  private handle: { detach: () => void } | null = null;
+
+  // Attach the action handler
+  attachCountryHandler() {
+    if (this.handle) return; // Already attached
+
+    this.handle = this.actionDirector.attachAction(
+      COUNTRIES_STATE_TOKEN,
+      AddCountry,
+      (ctx, action) => {
+        // Update state
+        ctx.setState(countries => [...countries, action.country]);
+      }
+    );
+  }
+
+  // Detach the action handler when no longer needed
+  detachCountryHandler() {
+    if (this.handle) {
+      this.handle.detach();
+      this.handle = null;
+    }
+  }
+}
+```
+
+### When to Use Dynamic Action Handlers
+
+Dynamic action handlers are useful in several scenarios:
+
+1. **Plugin systems**: Allow plugins to register their own action handlers
+2. **Lazy-loaded features**: Attach action handlers when a feature module is loaded
+3. **Temporary behaviors**: Create handlers that only exist for a specific duration
+4. **Conditional action handling**: Enable action handlers based on runtime conditions
+
+### The detach Function
+
+The `attachAction` method returns an object with a `detach` function that can be called to remove the action handler. This enables proper cleanup and prevents memory leaks.
+
+```ts
+// Example of attaching and later detaching a handler
+const handle = actionDirector.attachAction(STATE_TOKEN, SomeAction, (ctx, action) => {
+  // Handler logic
+});
+
+// Later, when the handler is no longer needed:
+handle.detach();
+```

docs/concepts/store/error-handling.md

@@ -32,7 +32,7 @@ It is recommended to handle errors within your `@Action` function in your state:
 - `Update the state` to capture the error details
   - Ensure that the relevant selectors cater for these error states and provide information for your user to respond to the error accordingly
 - OR `dispatch` an action that sends the error details to the necessary state or service
-  - This action could be picked up by an application level error state or could be picked up by a service that is listening to the action stream (see [Action Handlers](../actions/action-handlers.md))
+  - This action could be picked up by an application level error state or could be picked up by a service that is listening to the action stream (see [Actions Stream](../actions/actions-stream.md))
 
 ### Non-deterministic errors:
 

packages/store/src/actions/action-director.ts

@@ -0,0 +1,34 @@
+import { inject, Injectable } from '@angular/core';
+import {
+  type StateToken,
+  type ɵActionOptions,
+  ɵNgxsActionRegistry
+} from '@ngxs/store/internals';
+import type { Observable } from 'rxjs';
+
+import type { ActionDef } from './symbols';
+import type { StateContext } from '../symbols';
+import { InternalActionHandlerFactory } from '../internal/action-handler-factory';
+
+@Injectable({ providedIn: 'root' })
+export class ActionDirector {
+  private _registry = inject(ɵNgxsActionRegistry);
+  private _actionHandlerFactory = inject(InternalActionHandlerFactory);
+
+  attachAction<TStateModel, TActionType extends ActionDef>(
+    stateToken: StateToken<TStateModel>,
+    Action: TActionType,
+    handlerFn: (
+      ctx: StateContext<TStateModel>,
+      action: InstanceType<TActionType>
+    ) => void | Observable<void> | Promise<void>,
+    options: ɵActionOptions = {}
+  ) {
+    const actionHandler = this._actionHandlerFactory.createActionHandler(
+      stateToken.getName(),
+      handlerFn,
+      options
+    );
+    this._registry.register(Action.type, actionHandler);
+  }
+}

packages/store/src/internal/action-handler-factory.ts

@@ -0,0 +1,102 @@
+import { inject, Injectable, ɵisPromise } from '@angular/core';
+import {
+  defaultIfEmpty,
+  finalize,
+  from,
+  isObservable,
+  mergeMap,
+  type Observable,
+  of,
+  takeUntil
+} from 'rxjs';
+import type { ɵActionOptions } from '@ngxs/store/internals';
+
+import { InternalActions } from '../actions-stream';
+import { ofActionDispatched } from '../operators/of-action';
+import { StateContextFactory } from './state-context-factory';
+import type { StateContext } from '../symbols';
+
+@Injectable({ providedIn: 'root' })
+export class InternalActionHandlerFactory {
+  private readonly _actions = inject(InternalActions);
+  private readonly _stateContextFactory = inject(StateContextFactory);
+
+  createActionHandler(
+    path: string,
+    handlerFn: (ctx: StateContext<any>, action: any) => any,
+    options: ɵActionOptions
+  ): (action: any) => Observable<any> {
+    const { dispatched$ } = this._actions;
+
+    return (action: any) => {
+      const stateContext = this._stateContextFactory.createStateContext(path);
+
+      let result = handlerFn(stateContext, action);
+
+      // We need to use `isPromise` instead of checking whether
+      // `result instanceof Promise`. In zone.js patched environments, `global.Promise`
+      // is the `ZoneAwarePromise`. Some APIs, which are likely not patched by zone.js
+      // for certain reasons, might not work with `instanceof`. For instance, the dynamic
+      // import returns a native promise (not a `ZoneAwarePromise`), causing this check to
+      // be falsy.
+      if (ɵisPromise(result)) {
+        result = from(result);
+      }
+
+      if (isObservable(result)) {
+        result = result.pipe(
+          mergeMap(value => (ɵisPromise(value) || isObservable(value) ? value : of(value))),
+          // If this observable has completed without emitting any values,
+          // we wouldn't want to complete the entire chain of actions.
+          // If any observable completes, then the action will be canceled.
+          // For instance, if any action handler had a statement like
+          // `handler(ctx) { return EMPTY; }`, then the action would be canceled.
+          // See https://github.com/ngxs/store/issues/1568
+          // Note that we actually don't care about the return type; we only care
+          // about emission, and thus `undefined` is applicable by the framework.
+          defaultIfEmpty(undefined)
+        );
+
+        if (options.cancelUncompleted) {
+          const canceled = dispatched$.pipe(ofActionDispatched(action));
+          result = result.pipe(takeUntil(canceled));
+        }
+
+        result = result.pipe(
+          // Note that we use the `finalize` operator only when the action handler
+          // explicitly returns an observable (or a promise) to wait for. This means
+          // the action handler is written in a "fire & wait" style. If the handler’s
+          // result is unsubscribed (either because the observable has completed or
+          // it was unsubscribed by `takeUntil` due to a new action being dispatched),
+          // we prevent writing to the state context.
+          finalize(() => {
+            if (typeof ngDevMode !== 'undefined' && ngDevMode) {
+              function noopAndWarn() {
+                console.warn(
+                  `"${action}" attempted to change the state, but the change was ignored because state updates are not allowed after the action handler has completed.`
+                );
+              }
+
+              stateContext.setState = noopAndWarn;
+              stateContext.patchState = noopAndWarn;
+            } else {
+              stateContext.setState = noop;
+              stateContext.patchState = noop;
+            }
+          })
+        );
+      } else {
+        // If the action handler is synchronous and returns nothing (`void`), we
+        // still have to convert the result to a synchronous observable.
+        result = of(undefined);
+      }
+
+      return result;
+    };
+  }
+}
+
+// This is used to replace `setState` and `patchState` once the action
+// handler has been unsubscribed or completed, to prevent writing
+// to the state context.
+function noop() {}