@angular-architects/ngrx-toolkit 19.4.0 → 19.4.2

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

@@ -1,208 +0,0 @@
-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

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

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

@@ -1,7 +0,0 @@
-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

@@ -1,81 +0,0 @@
-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

@@ -1,58 +0,0 @@
-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

@@ -1,124 +0,0 @@
-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

@@ -1,19 +0,0 @@
-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

@@ -1,62 +0,0 @@
-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

@@ -1,18 +0,0 @@
-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);
-  }
-}

package/src/lib/storage-sync/tests/indexeddb.service.spec.ts

@@ -1,99 +0,0 @@
-import 'fake-indexeddb/auto';
-import { IndexedDBService } from '../internal/indexeddb.service';
-
-describe('IndexedDBService', () => {
-  const sampleData = JSON.stringify({
-    foo: 'bar',
-    users: [
-      { name: 'John', age: 30, isAdmin: true },
-      { name: 'Jane', age: 25, isAdmin: false },
-    ],
-  });
-
-  let indexedDBService: IndexedDBService;
-
-  beforeEach(() => {
-    indexedDBService = new IndexedDBService();
-  });
-
-  it('It should be possible to write data using write() and then read the data using read()', async (): Promise<void> => {
-    const key = 'users';
-
-    const expectedData = sampleData;
-
-    await indexedDBService.setItem(key, sampleData);
-
-    const receivedData = await indexedDBService.getItem(key);
-
-    expect(receivedData).toEqual(expectedData);
-  });
-
-  it('It should be possible to delete data using clear()', async (): Promise<void> => {
-    const key = 'sample';
-
-    await indexedDBService.setItem(key, sampleData);
-
-    await indexedDBService.clear(key);
-
-    const receivedData = await indexedDBService.getItem(key);
-
-    expect(receivedData).toEqual(null);
-  });
-
-  it('When there is no data, read() should return null', async (): Promise<void> => {
-    const key = 'nullData';
-
-    const receivedData = await indexedDBService.getItem(key);
-
-    expect(receivedData).toEqual(null);
-  });
-
-  it('write() should handle null data', async (): Promise<void> => {
-    const key = 'nullData';
-
-    await indexedDBService.setItem(key, JSON.stringify(null));
-
-    const receivedData = await indexedDBService.getItem(key);
-
-    expect(receivedData).toEqual('null');
-  });
-
-  it('write() should handle empty object data', async (): Promise<void> => {
-    const key = 'emptyData';
-
-    const emptyData = JSON.stringify({});
-    const expectedData = emptyData;
-
-    await indexedDBService.setItem(key, emptyData);
-
-    const receivedData = await indexedDBService.getItem(key);
-
-    expect(receivedData).toEqual(expectedData);
-  });
-
-  it('write() should handle large data objects', async (): Promise<void> => {
-    const key = 'largeData';
-
-    const largeData = JSON.stringify({ foo: 'a'.repeat(100000) });
-    const expectedData = largeData;
-
-    await indexedDBService.setItem(key, largeData);
-
-    const receivedData = await indexedDBService.getItem(key);
-
-    expect(receivedData).toEqual(expectedData);
-  });
-
-  it('write() should handle special characters in data', async (): Promise<void> => {
-    const key = 'specialCharData';
-
-    const specialCharData = JSON.stringify({ foo: 'bar!@#$%^&*()_+{}:"<>?' });
-    const expectedData = specialCharData;
-
-    await indexedDBService.setItem(key, specialCharData);
-
-    const receivedData = await indexedDBService.getItem(key);
-
-    expect(receivedData).toEqual(expectedData);
-  });
-});