feat: add withMutations(#202) [backport v19]

This introduces `withMutations` as a new SignalStore feature,
with initial support for RxJS-powered mutations via `rxMutation`.

Example:

```typescript
export const CounterStore = signalStore(
  withState({ counter: 0 }),
  withMutations((store) => ({
    increment: rxMutation({
      operation: (value: number) => {
        return httpClient.post('counter/increase', {value});
      },
      onSuccess: (result) => {
        patchState(store, { counter: result });
      }
    }),
  })),
);

const counterStore = inject(CounterStore);
counterStore.increment(1)
console.log(counterStore.counter()) // prints 1
```
---

### Background

- Mutations is the term the Angular team uses for the a potential upcoming feature that complements *resources* (which are read-only). Mutations enable writing data back to the server.
- To align with this mutation-based mindset, we are introducing custom mutation support in the toolkit.
- The design is inspired by @markostanimirovic’s prototype: https://github.com/markostanimirovic/rx-resource-proto
- Thanks to Marko for consulting with the NgRx team, and to Alex Rickabaugh (@alxhub) for the core mutation design.
- We also took ideas from TanStack Query's mutation feature. https://tanstack.com/query/latest

---

This commit lays the foundation for further expansion of mutation
support in SignalStore.

Author: manfredsteyer

apps/demo/src/app/app.component.html

@@ -26,6 +26,7 @@
       <a mat-list-item routerLink="/immutable-state">withImmutableState</a>
       <a mat-list-item routerLink="/feature-factory">withFeatureFactory</a>
       <a mat-list-item routerLink="/conditional">withConditional</a>
+      <a mat-list-item routerLink="/mutation">withMutation</a>
     </mat-nav-list>
   </mat-drawer>
   <mat-drawer-content>

apps/demo/src/app/counter-mutation/counter-mutation.css

@@ -0,0 +1,13 @@
+<h1>withMutations</h1>
+
+<div class="counter">{{ counter() }}</div>
+
+<ul>
+  <li>isPending: {{ isPending() }}</li>
+  <li>Status: {{ status() }}</li>
+  <li>Error: {{ error() | json }}</li>
+</ul>
+
+<div>
+  <button (click)="increment()">Increment</button>
+</div>

apps/demo/src/app/counter-mutation/counter-mutation.html

@@ -0,0 +1,22 @@
+import { CommonModule } from '@angular/common';
+import { Component, inject } from '@angular/core';
+import { CounterStore } from './counter.store';
+
+@Component({
+  selector: 'demo-counter-mutation',
+  imports: [CommonModule],
+  templateUrl: './counter-mutation.html',
+  styleUrl: './counter-mutation.css',
+})
+export class CounterMutation {
+  private store = inject(CounterStore);
+
+  protected counter = this.store.counter;
+  protected error = this.store.incrementError;
+  protected isPending = this.store.incrementIsPending;
+  protected status = this.store.incrementStatus;
+
+  increment() {
+    this.store.increment({ value: 1 });
+  }
+}

apps/demo/src/app/counter-mutation/counter-mutation.ts

@@ -0,0 +1,53 @@
+import {
+  concatOp,
+  rxMutation,
+  withMutations,
+} from '@angular-architects/ngrx-toolkit';
+import { patchState, signalStore, withState } from '@ngrx/signals';
+import { delay, Observable } from 'rxjs';
+
+export type Params = {
+  value: number;
+};
+
+export const CounterStore = signalStore(
+  { providedIn: 'root' },
+  withState({ counter: 0 }),
+  withMutations((store) => ({
+    increment: rxMutation({
+      operation: (params: Params) => {
+        return calcSum(store.counter(), params.value);
+      },
+      operator: concatOp,
+      onSuccess: (result) => {
+        console.log('result', result);
+        patchState(store, { counter: result });
+      },
+      onError: (error) => {
+        console.error('Error occurred:', error);
+      },
+    }),
+  })),
+);
+
+let error = false;
+
+function createSumObservable(a: number, b: number): Observable<number> {
+  return new Observable<number>((subscriber) => {
+    const result = a + b;
+
+    if ((result === 7 || result === 13) && !error) {
+      subscriber.error({ message: 'error due to bad luck!', result });
+      error = true;
+    } else {
+      subscriber.next(result);
+      error = false;
+    }
+    subscriber.complete();
+  });
+}
+
+function calcSum(a: number, b: number): Observable<number> {
+  // return of(a + b);
+  return createSumObservable(a, b).pipe(delay(500));
+}

apps/demo/src/app/counter-mutation/counter.store.ts

@@ -61,4 +61,11 @@ export const lazyRoutes: Route[] = [
         (m) => m.ConditionalSettingComponent,
       ),
   },
+  {
+    path: 'mutation',
+    loadComponent: () =>
+      import('./counter-mutation/counter-mutation').then(
+        (m) => m.CounterMutation,
+      ),
+  },
 ];

apps/demo/src/app/lazy-routes.ts

@@ -41,4 +41,14 @@ export {
 } from './lib/storage-sync/with-storage-sync';
 export { emptyFeature, withConditional } from './lib/with-conditional';
 export { withFeatureFactory } from './lib/with-feature-factory';
+
+export * from './lib/rx-mutation';
+export * from './lib/with-mutations';
 export { mapToResource, withResource } from './lib/with-resource';
+
+export {
+  concatOp,
+  exhaustOp,
+  mergeOp,
+  switchOp,
+} from './lib/flattening-operator';

libs/ngrx-toolkit/src/index.ts

@@ -0,0 +1,42 @@
+import {
+  concatMap,
+  exhaustMap,
+  mergeMap,
+  ObservableInput,
+  ObservedValueOf,
+  OperatorFunction,
+  switchMap,
+} from 'rxjs';
+
+export type RxJsFlatteningOperator = <T, O extends ObservableInput<unknown>>(
+  project: (value: T, index: number) => O,
+) => OperatorFunction<T, ObservedValueOf<O>>;
+
+/**
+ * A wrapper for an RxJS flattening operator.
+ * This wrapper informs about whether the operator has exhaust semantics or not.
+ */
+export type FlatteningOperator = {
+  rxJsOperator: RxJsFlatteningOperator;
+  exhaustSemantics: boolean;
+};
+
+export const switchOp: FlatteningOperator = {
+  rxJsOperator: switchMap,
+  exhaustSemantics: false,
+};
+
+export const mergeOp: FlatteningOperator = {
+  rxJsOperator: mergeMap,
+  exhaustSemantics: false,
+};
+
+export const concatOp: FlatteningOperator = {
+  rxJsOperator: concatMap,
+  exhaustSemantics: false,
+};
+
+export const exhaustOp: FlatteningOperator = {
+  rxJsOperator: exhaustMap,
+  exhaustSemantics: true,
+};

libs/ngrx-toolkit/src/lib/flattening-operator.ts

@@ -0,0 +1,172 @@
+import { computed, DestroyRef, inject, Injector, signal } from '@angular/core';
+import { takeUntilDestroyed } from '@angular/core/rxjs-interop';
+import {
+  catchError,
+  defer,
+  EMPTY,
+  finalize,
+  Observable,
+  Subject,
+  tap,
+} from 'rxjs';
+
+import { concatOp, FlatteningOperator } from './flattening-operator';
+import { Mutation, MutationResult, MutationStatus } from './with-mutations';
+
+export type Func<P, R> = (params: P) => R;
+
+export interface RxMutationOptions<P, R> {
+  operation: Func<P, Observable<R>>;
+  onSuccess?: (result: R, params: P) => void;
+  onError?: (error: unknown, params: P) => void;
+  operator?: FlatteningOperator;
+  injector?: Injector;
+}
+
+/**
+ * Creates a mutation that leverages RxJS.
+ *
+ * For each mutation the following options can be defined:
+ * - `operation`: A function that defines the mutation logic. It returns an Observable.
+ * - `onSuccess`: A callback that is called when the mutation is successful.
+ * - `onError`: A callback that is called when the mutation fails.
+ * - `operator`: An optional wrapper of an RxJS flattening operator. By default `concat` sematics are used.
+ * - `injector`: An optional Angular injector to use for dependency injection.
+ *
+ * The `operation` is the only mandatory option.
+ *
+ * ```typescript
+ * export type Params = {
+ *   value: number;
+ * };
+ *
+ * export const CounterStore = signalStore(
+ *   { providedIn: 'root' },
+ *   withState({ counter: 0 }),
+ *   withMutations((store) => ({
+ *     increment: rxMutation({
+ *       operation: (params: Params) => {
+ *         return calcSum(store.counter(), params.value);
+ *       },
+ *       operator: concatOp,
+ *       onSuccess: (result) => {
+ *         console.log('result', result);
+ *         patchState(store, { counter: result });
+ *       },
+ *       onError: (error) => {
+ *         console.error('Error occurred:', error);
+ *       },
+ *     }),
+ *   })),
+ * );
+ *
+ * function calcSum(a: number, b: number): Observable<number> {
+ *   return of(a + b);
+ * }
+ * ```
+ *
+ * @param options
+ * @returns
+ */
+export function rxMutation<P, R>(
+  options: RxMutationOptions<P, R>,
+): Mutation<P, R> {
+  const inputSubject = new Subject<{
+    param: P;
+    resolve: (result: MutationResult<R>) => void;
+  }>();
+  const flatteningOp = options.operator ?? concatOp;
+
+  const destroyRef = options.injector?.get(DestroyRef) ?? inject(DestroyRef);
+
+  const callCount = signal(0);
+  const errorSignal = signal<unknown>(undefined);
+  const idle = signal(true);
+  const isPending = computed(() => callCount() > 0);
+
+  const status = computed<MutationStatus>(() => {
+    if (idle()) {
+      return 'idle';
+    }
+    if (callCount() > 0) {
+      return 'pending';
+    }
+    if (errorSignal()) {
+      return 'error';
+    }
+    return 'success';
+  });
+
+  const initialInnerStatus: MutationStatus = 'idle';
+  let innerStatus: MutationStatus = initialInnerStatus;
+  let lastResult: R;
+
+  inputSubject
+    .pipe(
+      flatteningOp.rxJsOperator((input) =>
+        defer(() => {
+          callCount.update((c) => c + 1);
+          idle.set(false);
+          return options.operation(input.param).pipe(
+            tap((result: R) => {
+              options.onSuccess?.(result, input.param);
+              innerStatus = 'success';
+              errorSignal.set(undefined);
+              lastResult = result;
+            }),
+            catchError((error: unknown) => {
+              options.onError?.(error, input.param);
+              errorSignal.set(error);
+              innerStatus = 'error';
+              return EMPTY;
+            }),
+            finalize(() => {
+              callCount.update((c) => c - 1);
+
+              if (innerStatus === 'success') {
+                input.resolve({
+                  status: 'success',
+                  value: lastResult,
+                });
+              } else if (innerStatus === 'error') {
+                input.resolve({
+                  status: 'error',
+                  error: errorSignal(),
+                });
+              } else {
+                input.resolve({
+                  status: 'aborted',
+                });
+              }
+
+              innerStatus = initialInnerStatus;
+            }),
+          );
+        }),
+      ),
+      takeUntilDestroyed(destroyRef),
+    )
+    .subscribe();
+
+  const mutationFn = (param: P) => {
+    return new Promise<MutationResult<R>>((resolve) => {
+      if (callCount() > 0 && flatteningOp.exhaustSemantics) {
+        resolve({
+          status: 'aborted',
+        });
+      } else {
+        inputSubject.next({
+          param,
+          resolve,
+        });
+      }
+    });
+  };
+
+  const mutation = mutationFn as Mutation<P, R>;
+  mutation.status = status;
+  mutation.isPending = isPending;
+  mutation.error = errorSignal;
+
+  return mutation;
+}