refactor: withStorageSync

- modify `withStorageSync` so that it is not breaking
- Improve the typing, where `withIndexedDB` returns asynchronous methods
- Add and improve tests
- Deprecate `withIndexeddb` in favour of `withIndexedDB`

Author: rainerhahnekamp

apps/demo/src/app/todo-indexeddb-sync/synced-todo-store.ts

@@ -1,3 +1,8 @@
+import {
+  withIndexedDB,
+  withStorageSync,
+} from '@angular-architects/ngrx-toolkit';
+import { inject } from '@angular/core';
 import { getState, patchState, signalStore, withMethods } from '@ngrx/signals';
 import {
   removeEntity,
@@ -6,11 +11,6 @@ import {
   withEntities,
 } from '@ngrx/signals/entities';
 import { AddTodo, Todo, TodoService } from '../shared/todo.service';
-import {
-  withIndexeddb,
-  withStorageSync,
-} from '@angular-architects/ngrx-toolkit';
-import { inject } from '@angular/core';
 
 export const SyncedTodoStore = signalStore(
   { providedIn: 'root' },
@@ -19,7 +19,7 @@ export const SyncedTodoStore = signalStore(
     {
       key: 'todos-indexeddb',
     },
-    withIndexeddb()
+    withIndexedDB()
   ),
   withMethods((store, todoService = inject(TodoService)) => {
     let currentId = 0;

libs/ngrx-toolkit/jest.config.ts

@@ -1,6 +1,6 @@
 export default {
   displayName: 'ngrx-toolkit',
-  setupFiles: ['fake-indexeddb/auto', 'core-js'],
+  setupFiles: ['core-js'],
   preset: '../../jest.preset.js',
   setupFilesAfterEnv: ['<rootDir>/src/test-setup.ts'],
   coverageDirectory: '../../coverage/libs/ngrx-toolkit',

libs/ngrx-toolkit/src/index.ts

@@ -1,36 +1,43 @@
-export { withDevToolsStub } from './lib/devtools/with-dev-tools-stub';
-export { withDevtools } from './lib/devtools/with-devtools';
 export { withDisabledNameIndices } from './lib/devtools/features/with-disabled-name-indicies';
-export { withMapper } from './lib/devtools/features/with-mapper';
 export { withGlitchTracking } from './lib/devtools/features/with-glitch-tracking';
-export { patchState, updateState } from './lib/devtools/update-state';
-export { renameDevtoolsName } from './lib/devtools/rename-devtools-name';
+export { withMapper } from './lib/devtools/features/with-mapper';
 export {
   provideDevtoolsConfig,
   ReduxDevtoolsConfig,
 } from './lib/devtools/provide-devtools-config';
+export { renameDevtoolsName } from './lib/devtools/rename-devtools-name';
+export { patchState, updateState } from './lib/devtools/update-state';
+export { withDevToolsStub } from './lib/devtools/with-dev-tools-stub';
+export { withDevtools } from './lib/devtools/with-devtools';
 
 export {
-  withRedux,
-  payload,
-  noPayload,
-  createReducer,
   createEffects,
+  createReducer,
+  noPayload,
+  payload,
+  withRedux,
 } from './lib/with-redux';
 
 export * from './lib/with-call-state';
-export * from './lib/with-undo-redo';
 export * from './lib/with-data-service';
 export * from './lib/with-pagination';
-export { withReset, setResetState } from './lib/with-reset';
+export { setResetState, withReset } from './lib/with-reset';
+export * from './lib/with-undo-redo';
 
-export { withLocalStorage } from './lib/storage-sync/features/with-local-storage';
-export { withSessionStorage } from './lib/storage-sync/features/with-session-storage';
-export { withIndexeddb } from './lib/storage-sync/features/with-indexeddb';
+export { withImmutableState } from './lib/immutable-state/with-immutable-state';
+export { withIndexedDB } from './lib/storage-sync/features/with-indexed-db';
+
+/**
+ * @deprecated Use {@link withIndexedDB} instead.
+ */
+export { withIndexedDB as withIndexeddb } from './lib/storage-sync/features/with-indexed-db';
+export {
+  withLocalStorage,
+  withSessionStorage,
+} from './lib/storage-sync/features/with-local-storage';
 export {
-  withStorageSync,
   SyncConfig,
+  withStorageSync,
 } from './lib/storage-sync/with-storage-sync';
-export { withImmutableState } from './lib/immutable-state/with-immutable-state';
+export { emptyFeature, withConditional } from './lib/with-conditional';
 export { withFeatureFactory } from './lib/with-feature-factory';
-export { withConditional, emptyFeature } from './lib/with-conditional';

libs/ngrx-toolkit/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;
+}

libs/ngrx-toolkit/src/lib/storage-sync/features/with-indexeddb.ts

@@ -1,3 +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 const withLocalStorage = () => LocalStorageService;
+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;
+}

libs/ngrx-toolkit/src/lib/storage-sync/features/with-local-storage.ts

@@ -1,9 +1,4 @@
 import { Injectable } from '@angular/core';
-import {
-  IndexeddbService,
-  PROMISE_NOOP,
-  WithIndexeddbSyncFeatureResult,
-} from './models';
 
 export const keyPath = 'ngrxToolkitKeyPath';
 
@@ -14,7 +9,7 @@ export const storeName = 'ngrxToolkitStore';
 export const VERSION: number = 1 as const;
 
 @Injectable({ providedIn: 'root' })
-export class IndexedDBService implements IndexeddbService {
+export class IndexedDBService {
   /**
    * write to indexedDB
    * @param key
@@ -102,15 +97,6 @@ export class IndexedDBService implements IndexeddbService {
     });
   }
 
-  /** return stub */
-  getStub(): Pick<WithIndexeddbSyncFeatureResult, 'methods'>['methods'] {
-    return {
-      clearStorage: PROMISE_NOOP,
-      readFromStorage: PROMISE_NOOP,
-      writeToStorage: PROMISE_NOOP,
-    };
-  }
-
   /**
    * open indexedDB
    */

libs/ngrx-toolkit/src/lib/storage-sync/features/with-session-storage.ts

@@ -1,10 +1,10 @@
 import { Injectable } from '@angular/core';
-import { NOOP, StorageService, WithStorageSyncFeatureResult } from './models';
+import {} from './models';
 
 @Injectable({
   providedIn: 'root',
 })
-export class LocalStorageService implements StorageService {
+export class LocalStorageService {
   getItem(key: string): string | null {
     return localStorage.getItem(key);
   }
@@ -16,13 +16,4 @@ export class LocalStorageService implements StorageService {
   clear(key: string): void {
     return localStorage.removeItem(key);
   }
-
-  /** return stub */
-  getStub(): Pick<WithStorageSyncFeatureResult, 'methods'>['methods'] {
-    return {
-      clearStorage: NOOP,
-      readFromStorage: NOOP,
-      writeToStorage: NOOP,
-    };
-  }
 }

libs/ngrx-toolkit/src/lib/storage-sync/internal/indexeddb.service.ts

@@ -1,46 +1,49 @@
-import { EmptyFeatureResult } from '@ngrx/signals';
-import { Type } from '@angular/core';
-
-export interface StorageService {
-  clear(key: string): void;
-
-  getItem(key: string): string | null;
-
-  setItem(key: string, data: string): void;
-
-  getStub(): Pick<WithStorageSyncFeatureResult, 'methods'>['methods'];
-}
-
-export interface IndexeddbService {
-  clear(key: string): Promise<void>;
-
-  getItem(key: string): Promise<string | null>;
+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;
+};
 
-  setItem(key: string, data: string): Promise<void>;
+export type SyncFeatureResult = EmptyFeatureResult & {
+  methods: SyncMethods;
+};
 
-  getStub(): Pick<WithIndexeddbSyncFeatureResult, 'methods'>['methods'];
-}
+export type SyncStoreForFactory<State extends object> =
+  WritableStateSource<State>;
 
-export type StorageServiceFactory =
-  | Type<IndexeddbService>
-  | Type<StorageService>;
+export type SyncStorageStrategy<State extends object> = ((
+  config: Required<SyncConfig<State>>,
+  store: SyncStoreForFactory<State>,
+  useStubs: boolean
+) => SyncMethods) & { type: 'sync' };
 
-export type WithIndexeddbSyncFeatureResult = EmptyFeatureResult & {
-  methods: {
-    clearStorage(): Promise<void>;
-    readFromStorage(): Promise<void>;
-    writeToStorage(): Promise<void>;
-  };
+export type AsyncMethods = {
+  clearStorage(): Promise<void>;
+  readFromStorage(): Promise<void>;
+  writeToStorage(): Promise<void>;
 };
 
-export type WithStorageSyncFeatureResult = EmptyFeatureResult & {
-  methods: {
-    clearStorage(): void;
-    readFromStorage(): void;
-    writeToStorage(): void;
+export const SYNC_STATUS = Symbol('SYNC_STATUS');
+export type SyncStatus = 'idle' | 'syncing' | 'synced';
+
+export type AsyncFeatureResult = EmptyFeatureResult & {
+  methods: AsyncMethods;
+  props: {
+    isSynced: Signal<boolean>;
+    whenSynced: () => Promise<void>;
+    [SYNC_STATUS]: WritableSignal<SyncStatus>;
   };
 };
 
-export const NOOP = () => void true;
+export type AsyncStoreForFactory<State extends object> =
+  WritableStateSource<State> & AsyncFeatureResult['props'];
 
-export const PROMISE_NOOP = () => Promise.resolve();
+export type AsyncStorageStrategy<State extends object> = ((
+  config: Required<SyncConfig<State>>,
+  store: AsyncStoreForFactory<State>,
+  useStubs: boolean
+) => AsyncMethods) & { type: 'async' };