@angular-architects/ngrx-toolkit 19.2.3 → 19.4.0

package/src/lib/mutation/rx-mutation.ts

@@ -0,0 +1,208 @@
+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 './mutation';
+
+export type Operation<Parameter, Result> = (param: Parameter) => Result;
+
+export interface RxMutationOptions<Parameter, Result> {
+  operation: Operation<Parameter, Observable<Result>>;
+  onSuccess?: (result: Result, param: Parameter) => void;
+  onError?: (error: unknown, param: Parameter) => 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.
+ *
+ * The returned mutation can be called as an async function and returns a Promise.
+ * This promise informs about whether the mutation was successful, failed, or aborted
+ * (due to switchMap or exhaustMap semantics).
+ *
+ * The mutation also provides several Signals such as error, status or isPending (see below).
+ *
+ * Example usage without Store:
+ *
+ * ```typescript
+ * const counterSignal = signal(0);
+ *
+ * const increment = rxMutation({
+ *   operation: (param: Param) => {
+ *     return calcSum(this.counterSignal(), param.value);
+ *   },
+ *   operator: concatOp,
+ *   onSuccess: (result) => {
+ *     this.counterSignal.set(result);
+ *   },
+ *   onError: (error) => {
+ *     console.error('Error occurred:', error);
+ *   },
+ * });
+ *
+ * const error = increment.error;
+ * const isPending = increment.isPending;
+ * const status = increment.status;
+ * const value = increment.value;
+ * const hasValue = increment.hasValue;
+ *
+ * async function incrementCounter() {
+ *     const result = await increment({ value: 1 });
+ *     if (result.status === 'success') {
+ *       console.log('Success:', result.value);
+ *     }
+ *     if (result.status === 'error') {
+ *       console.log('Error:', result.error);
+ *     }
+ *     if (result.status === 'aborted') {
+ *       console.log('Operation aborted');
+ *     }
+ * }
+ *
+ * function calcSum(a: number, b: number): Observable<number> {
+ *   return of(result).pipe(delay(500));
+ * }
+ * ```
+ *
+ * @param options
+ * @returns the actual mutation function along tracking data as properties/methods
+ */
+export function rxMutation<Parameter, Result>(
+  optionsOrOperation:
+    | RxMutationOptions<Parameter, Result>
+    | Operation<Parameter, Observable<Result>>,
+): Mutation<Parameter, Result> {
+  const inputSubject = new Subject<{
+    param: Parameter;
+    resolve: (result: MutationResult<Result>) => void;
+  }>();
+
+  const options =
+    typeof optionsOrOperation === 'function'
+      ? { operation: optionsOrOperation }
+      : optionsOrOperation;
+
+  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 value = signal<Result | undefined>(undefined);
+  const isSuccess = computed(() => !idle() && !isPending() && !errorSignal());
+
+  const hasValue = function (
+    this: Mutation<Parameter, Result>,
+  ): this is Mutation<Exclude<Parameter, undefined>, Result> {
+    return typeof value() !== 'undefined';
+  };
+
+  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;
+
+  inputSubject
+    .pipe(
+      flatteningOp.rxJsOperator((input) =>
+        defer(() => {
+          callCount.update((c) => c + 1);
+          idle.set(false);
+          return options.operation(input.param).pipe(
+            tap((result: Result) => {
+              options.onSuccess?.(result, input.param);
+              innerStatus = 'success';
+              errorSignal.set(undefined);
+              value.set(result);
+            }),
+            catchError((error: unknown) => {
+              options.onError?.(error, input.param);
+              errorSignal.set(error);
+              value.set(undefined);
+              innerStatus = 'error';
+              return EMPTY;
+            }),
+            finalize(() => {
+              callCount.update((c) => c - 1);
+
+              if (innerStatus === 'success') {
+                input.resolve({
+                  status: 'success',
+                  value: value() as Result,
+                });
+              } else if (innerStatus === 'error') {
+                input.resolve({
+                  status: 'error',
+                  error: errorSignal(),
+                });
+              } else {
+                input.resolve({
+                  status: 'aborted',
+                });
+              }
+
+              innerStatus = initialInnerStatus;
+            }),
+          );
+        }),
+      ),
+      takeUntilDestroyed(destroyRef),
+    )
+    .subscribe();
+
+  const mutationFn = (param: Parameter) => {
+    return new Promise<MutationResult<Result>>((resolve) => {
+      if (callCount() > 0 && flatteningOp.exhaustSemantics) {
+        resolve({
+          status: 'aborted',
+        });
+      } else {
+        inputSubject.next({
+          param,
+          resolve,
+        });
+      }
+    });
+  };
+
+  const mutation = mutationFn as Mutation<Parameter, Result>;
+  mutation.status = status;
+  mutation.isPending = isPending;
+  mutation.error = errorSignal;
+  mutation.value = value;
+  mutation.hasValue = hasValue;
+  mutation.isSuccess = isSuccess;
+  return mutation;
+}

package/src/lib/shared/prettify.ts

@@ -0,0 +1,3 @@
+export type Prettify<Type extends object> = {
+  [Key in keyof Type]: Type[Key];
+};

package/{lib/shared/signal-store-models.d.ts → src/lib/shared/signal-store-models.ts}

@@ -14,13 +14,17 @@
  */
 import { Signal } from '@angular/core';
 import { EntityId } from '@ngrx/signals/entities';
+
+// withEntites models
 export type EntityState<Entity> = {
-    entityMap: Record<EntityId, Entity>;
-    ids: EntityId[];
+  entityMap: Record<EntityId, Entity>;
+  ids: EntityId[];
 };
+
 export type EntityComputed<Entity> = {
-    entities: Signal<Entity[]>;
+  entities: Signal<Entity[]>;
 };
+
 export type NamedEntityComputed<Entity, Collection extends string> = {
-    [K in keyof EntityComputed<Entity> as `${Collection}${Capitalize<K>}`]: EntityComputed<Entity>[K];
+  [K in keyof EntityComputed<Entity> as `${Collection}${Capitalize<K>}`]: EntityComputed<Entity>[K];
 };

package/src/lib/shared/throw-if-null.ts

@@ -0,0 +1,7 @@
+export function throwIfNull<T>(obj: T): NonNullable<T> {
+  if (obj === null || obj === undefined) {
+    throw new Error('');
+  }
+
+  return obj;
+}

package/src/lib/storage-sync/features/with-indexed-db.ts

@@ -0,0 +1,81 @@
+import { inject } from '@angular/core';
+import { getState, patchState } from '@ngrx/signals';
+import { IndexedDBService } from '../internal/indexeddb.service';
+import {
+  AsyncMethods,
+  AsyncStorageStrategy,
+  AsyncStoreForFactory,
+  SYNC_STATUS,
+} from '../internal/models';
+import { SyncConfig } from '../with-storage-sync';
+
+export function withIndexedDB<
+  State extends object,
+>(): AsyncStorageStrategy<State> {
+  function factory(
+    { key, parse, select, stringify }: Required<SyncConfig<State>>,
+    store: AsyncStoreForFactory<State>,
+    useStubs: boolean,
+  ): AsyncMethods {
+    if (useStubs) {
+      return {
+        clearStorage: () => Promise.resolve(),
+        readFromStorage: () => Promise.resolve(),
+        writeToStorage: () => Promise.resolve(),
+      };
+    }
+
+    const indexeddbService = inject(IndexedDBService);
+
+    function warnOnSyncing(mode: 'read' | 'write'): void {
+      if (store[SYNC_STATUS]() === 'syncing') {
+        const prettyMode = mode === 'read' ? 'Reading' : 'Writing';
+        console.warn(
+          `${prettyMode} to Store (${key}) happened during an ongoing synchronization process.`,
+          'Please ensure that the store is not in syncing state via `store.whenSynced()`.',
+          'Alternatively, you can disable the autoSync by passing `autoSync: false` in the config.',
+        );
+      }
+    }
+
+    return {
+      /**
+       * Removes the item stored in storage.
+       */
+      async clearStorage(): Promise<void> {
+        warnOnSyncing('write');
+        store[SYNC_STATUS].set('syncing');
+        patchState(store, {});
+        await indexeddbService.clear(key);
+        store[SYNC_STATUS].set('synced');
+      },
+
+      /**
+       * Reads item from storage and patches the state.
+       */
+      async readFromStorage(): Promise<void> {
+        warnOnSyncing('read');
+        store[SYNC_STATUS].set('syncing');
+        const stateString = await indexeddbService.getItem(key);
+        if (stateString) {
+          patchState(store, parse(stateString));
+        }
+        store[SYNC_STATUS].set('synced');
+      },
+
+      /**
+       * Writes selected portion to storage.
+       */
+      async writeToStorage(): Promise<void> {
+        warnOnSyncing('write');
+        store[SYNC_STATUS].set('syncing');
+        const slicedState = select(getState(store)) as State;
+        await indexeddbService.setItem(key, stringify(slicedState));
+        store[SYNC_STATUS].set('synced');
+      },
+    };
+  }
+  factory.type = 'async' as const;
+
+  return factory;
+}

package/src/lib/storage-sync/features/with-local-storage.ts

@@ -0,0 +1,58 @@
+import { inject, Type } from '@angular/core';
+import { getState, patchState } from '@ngrx/signals';
+import { LocalStorageService } from '../internal/local-storage.service';
+import { SyncStorageStrategy, SyncStoreForFactory } from '../internal/models';
+import { SessionStorageService } from '../internal/session-storage.service';
+import { SyncConfig } from '../with-storage-sync';
+
+export function withLocalStorage<
+  State extends object,
+>(): SyncStorageStrategy<State> {
+  return createSyncMethods<State>(LocalStorageService);
+}
+
+export function withSessionStorage<State extends object>() {
+  return createSyncMethods<State>(SessionStorageService);
+}
+
+function createSyncMethods<State extends object>(
+  Storage: Type<LocalStorageService | SessionStorageService>,
+): SyncStorageStrategy<State> {
+  function factory(
+    { key, parse, select, stringify }: Required<SyncConfig<State>>,
+    store: SyncStoreForFactory<State>,
+    useStubs: boolean,
+  ) {
+    if (useStubs) {
+      return {
+        clearStorage: () => undefined,
+        readFromStorage: () => undefined,
+        writeToStorage: () => undefined,
+      };
+    }
+
+    const storage = inject(Storage);
+
+    return {
+      clearStorage(): void {
+        storage.clear(key);
+      },
+
+      readFromStorage(): void {
+        const stateString = storage.getItem(key);
+
+        if (stateString) {
+          patchState(store, parse(stateString));
+        }
+      },
+
+      writeToStorage() {
+        const slicedState = select(getState(store)) as State;
+        storage.setItem(key, stringify(slicedState));
+      },
+    };
+  }
+  factory.type = 'sync' as const;
+
+  return factory;
+}

package/src/lib/storage-sync/internal/indexeddb.service.ts

@@ -0,0 +1,124 @@
+import { Injectable } from '@angular/core';
+
+export const keyPath = 'ngrxToolkitKeyPath';
+
+export const dbName = 'ngrxToolkitDb';
+
+export const storeName = 'ngrxToolkitStore';
+
+export const VERSION: number = 1 as const;
+
+@Injectable({ providedIn: 'root' })
+export class IndexedDBService {
+  /**
+   * write to indexedDB
+   * @param key
+   * @param data
+   */
+  async setItem(key: string, data: string): Promise<void> {
+    const db = await this.openDB();
+
+    const tx = db.transaction(storeName, 'readwrite');
+
+    const store = tx.objectStore(storeName);
+
+    store.put({
+      [keyPath]: key,
+      value: data,
+    });
+
+    return new Promise((resolve, reject) => {
+      tx.oncomplete = (): void => {
+        db.close();
+        resolve();
+      };
+
+      tx.onerror = (): void => {
+        db.close();
+        reject();
+      };
+    });
+  }
+
+  /**
+   * read from indexedDB
+   * @param key
+   */
+  async getItem(key: string): Promise<string | null> {
+    const db = await this.openDB();
+
+    const tx = db.transaction(storeName, 'readonly');
+
+    const store = tx.objectStore(storeName);
+
+    const request = store.get(key);
+
+    return new Promise((resolve, reject) => {
+      request.onsuccess = (): void => {
+        db.close();
+        // localStorage(sessionStorage) returns null if the key does not exist
+        // Similarly, indexedDB should return null
+        if (request.result === undefined) {
+          resolve(null);
+        }
+        resolve(request.result?.['value']);
+      };
+
+      request.onerror = (): void => {
+        db.close();
+        reject();
+      };
+    });
+  }
+
+  /**
+   * delete indexedDB
+   * @param key
+   */
+  async clear(key: string): Promise<void> {
+    const db = await this.openDB();
+
+    const tx = db.transaction(storeName, 'readwrite');
+
+    const store = tx.objectStore(storeName);
+
+    const request = store.delete(key);
+
+    return new Promise((resolve, reject) => {
+      request.onsuccess = (): void => {
+        db.close();
+        resolve();
+      };
+
+      request.onerror = (): void => {
+        db.close();
+        reject();
+      };
+    });
+  }
+
+  /**
+   * open indexedDB
+   */
+  private async openDB(): Promise<IDBDatabase> {
+    return new Promise((resolve, reject) => {
+      const request = indexedDB.open(dbName, VERSION);
+
+      request.onupgradeneeded = () => {
+        const db = request.result;
+
+        if (!db.objectStoreNames.contains(storeName)) {
+          db.createObjectStore(storeName, { keyPath });
+        }
+      };
+
+      request.onsuccess = (): void => {
+        resolve(request.result);
+      };
+
+      request.onerror = (): void => {
+        reject(request.error);
+      };
+    });
+  }
+}

package/src/lib/storage-sync/internal/local-storage.service.ts

@@ -0,0 +1,19 @@
+import { Injectable } from '@angular/core';
+import {} from './models';
+
+@Injectable({
+  providedIn: 'root',
+})
+export class LocalStorageService {
+  getItem(key: string): string | null {
+    return localStorage.getItem(key);
+  }
+
+  setItem(key: string, data: string): void {
+    return localStorage.setItem(key, data);
+  }
+
+  clear(key: string): void {
+    return localStorage.removeItem(key);
+  }
+}

package/src/lib/storage-sync/internal/models.ts

@@ -0,0 +1,62 @@
+import { Signal, WritableSignal } from '@angular/core';
+import { EmptyFeatureResult, WritableStateSource } from '@ngrx/signals';
+import { SyncConfig } from '../with-storage-sync';
+
+export type SyncMethods = {
+  clearStorage(): void;
+  readFromStorage(): void;
+  writeToStorage(): void;
+};
+
+export type SyncFeatureResult = EmptyFeatureResult & {
+  methods: SyncMethods;
+};
+
+export type SyncStoreForFactory<State extends object> =
+  WritableStateSource<State>;
+
+export type SyncStorageStrategy<State extends object> = ((
+  config: Required<SyncConfig<State>>,
+  store: SyncStoreForFactory<State>,
+  useStubs: boolean,
+) => SyncMethods) & { type: 'sync' };
+
+export type AsyncMethods = {
+  clearStorage(): Promise<void>;
+  readFromStorage(): Promise<void>;
+  writeToStorage(): Promise<void>;
+};
+
+/**
+ * AsyncFeatureResult is used as the public interface that users interact with
+ * when calling `withIndexedDB`. It intentionally omits the internal SYNC_STATUS
+ * property to avoid TypeScript error TS4058 (return type of public method
+ * includes private type).
+ *
+ * For internal implementation, we use AsyncStoreForFactory which includes
+ * the SYNC_STATUS property needed for state management.
+ */
+export const SYNC_STATUS = Symbol('SYNC_STATUS');
+export type SyncStatus = 'idle' | 'syncing' | 'synced';
+
+// Keeping it internal avoids TS4058 error
+export type InternalAsyncProps = AsyncFeatureResult['props'] & {
+  [SYNC_STATUS]: WritableSignal<SyncStatus>;
+};
+
+export type AsyncFeatureResult = EmptyFeatureResult & {
+  methods: AsyncMethods;
+  props: {
+    isSynced: Signal<boolean>;
+    whenSynced: () => Promise<void>;
+  };
+};
+
+export type AsyncStoreForFactory<State extends object> =
+  WritableStateSource<State> & InternalAsyncProps;
+
+export type AsyncStorageStrategy<State extends object> = ((
+  config: Required<SyncConfig<State>>,
+  store: AsyncStoreForFactory<State>,
+  useStubs: boolean,
+) => AsyncMethods) & { type: 'async' };

package/src/lib/storage-sync/internal/session-storage.service.ts

@@ -0,0 +1,18 @@
+import { Injectable } from '@angular/core';
+
+@Injectable({
+  providedIn: 'root',
+})
+export class SessionStorageService {
+  getItem(key: string): string | null {
+    return sessionStorage.getItem(key);
+  }
+
+  setItem(key: string, data: string): void {
+    return sessionStorage.setItem(key, data);
+  }
+
+  clear(key: string): void {
+    return sessionStorage.removeItem(key);
+  }
+}