@angular-architects/ngrx-toolkit 20.0.0 → 20.0.2

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);
+  }
+}

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

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

package/src/lib/storage-sync/tests/with-storage-async.spec.ts

@@ -0,0 +1,305 @@
+import { TestBed } from '@angular/core/testing';
+import { getState, patchState, signalStore, withState } from '@ngrx/signals';
+import 'fake-indexeddb/auto';
+import { withIndexedDB } from '../features/with-indexed-db';
+import { IndexedDBService } from '../internal/indexeddb.service';
+import { withStorageSync } from '../with-storage-sync';
+
+interface StateObject {
+  foo: string;
+  age: number;
+}
+
+const initialState: StateObject = {
+  foo: 'bar',
+  age: 18,
+};
+const key = 'FooBar';
+
+const waitForSyncStable = async (store: {
+  whenSynced?: () => Promise<void>;
+}) => {
+  if (store.whenSynced) {
+    await store.whenSynced();
+  }
+};
+
+describe('withStorageSync (async storage)', () => {
+  beforeEach(() => {
+    // make sure to start with a clean storage
+    globalThis.indexedDB = new IDBFactory();
+  });
+
+  it('adds methods for storage access to the store', () => {
+    TestBed.runInInjectionContext(() => {
+      const Store = signalStore(withStorageSync({ key }, withIndexedDB()));
+      const store = new Store();
+
+      expect(Object.keys(store)).toEqual([
+        'isSynced',
+        'whenSynced',
+        'clearStorage',
+        'readFromStorage',
+        'writeToStorage',
+      ]);
+    });
+  });
+
+  it('offers manual sync using provided methods', async () => {
+    TestBed.runInInjectionContext(async () => {
+      // prefill storage
+      const indexedDBService = TestBed.inject(IndexedDBService);
+      await indexedDBService.setItem(
+        key,
+        JSON.stringify({
+          foo: 'baz',
+          age: 99,
+        }),
+      );
+
+      const Store = signalStore(
+        { protectedState: false },
+        withState(initialState),
+        withStorageSync({ key, autoSync: false }, withIndexedDB()),
+      );
+      const store = TestBed.inject(Store);
+      await waitForSyncStable(store);
+
+      expect(getState(store)).toEqual({});
+
+      await store.readFromStorage();
+
+      expect(getState(store)).toEqual({
+        foo: 'baz',
+        age: 99,
+      });
+
+      patchState(store, { ...initialState });
+      await waitForSyncStable(store);
+
+      expect(await indexedDBService.getItem(key)).toEqual({
+        foo: 'baz',
+        age: 99,
+      });
+
+      await store.writeToStorage();
+      expect(await indexedDBService.getItem(key)).toEqual({
+        ...initialState,
+      });
+
+      await store.clearStorage();
+      expect(await indexedDBService.getItem(key)).toEqual(null);
+    });
+  });
+
+  describe('autoSync', () => {
+    it('inits from storage and write to storage on changes when set to `true`', async () => {
+      const indexedDBService = TestBed.inject(IndexedDBService);
+      // prefill storage
+      await indexedDBService.setItem(
+        key,
+        JSON.stringify({
+          foo: 'baz',
+          age: 99,
+        } as StateObject),
+      );
+
+      const Store = signalStore(
+        { providedIn: 'root', protectedState: false },
+        withState(initialState),
+        withStorageSync(key, withIndexedDB()),
+      );
+
+      const store = TestBed.inject(Store);
+      await waitForSyncStable(store);
+      expect(getState(store)).toEqual({
+        foo: 'baz',
+        age: 99,
+      });
+
+      patchState(store, { ...initialState });
+      await waitForSyncStable(store);
+
+      expect(getState(store)).toEqual({
+        ...initialState,
+      });
+
+      expect(await indexedDBService.getItem(key)).toEqual(
+        JSON.stringify(initialState),
+      );
+    });
+
+    it('does not init from storage and does write to storage on changes when set to `false`', async () => {
+      const indexedDBService = TestBed.inject(IndexedDBService);
+      await indexedDBService.setItem(
+        key,
+        JSON.stringify({
+          foo: 'baz',
+          age: 99,
+        }),
+      );
+
+      const Store = signalStore(
+        { providedIn: 'root', protectedState: false },
+        withStorageSync({ key, autoSync: false }, withIndexedDB()),
+      );
+      const store = TestBed.inject(Store);
+      expect(store.isSynced()).toBe(false);
+      expect(getState(store)).toEqual({});
+
+      patchState(store, { ...initialState });
+      expect(store.isSynced()).toBe(false);
+
+      const storeItem = JSON.parse(
+        (await indexedDBService.getItem(key)) || '{}',
+      );
+      expect(storeItem).toEqual({
+        foo: 'baz',
+        age: 99,
+      });
+    });
+  });
+
+  describe('select', () => {
+    it('syncs the whole state by default', async () => {
+      const indexedDBService = TestBed.inject(IndexedDBService);
+      const Store = signalStore(
+        { providedIn: 'root', protectedState: false },
+        withState(initialState),
+        withStorageSync(key, withIndexedDB()),
+      );
+      const store = TestBed.inject(Store);
+      await waitForSyncStable(store);
+
+      patchState(store, { foo: 'baz', age: 25 });
+      await waitForSyncStable(store);
+
+      expect(await indexedDBService.getItem(key)).toEqual(
+        JSON.stringify({ foo: 'baz', age: 25 }),
+      );
+    });
+
+    it('syncs selected slices when specified', async () => {
+      const indexedDBService = TestBed.inject(IndexedDBService);
+      const Store = signalStore(
+        { providedIn: 'root', protectedState: false },
+        withState(initialState),
+        withStorageSync(
+          { key, select: ({ foo }) => ({ foo }) },
+          withIndexedDB(),
+        ),
+      );
+      const store = TestBed.inject(Store);
+      await waitForSyncStable(store);
+
+      patchState(store, { foo: 'baz' });
+      await waitForSyncStable(store);
+
+      const storeItem = JSON.parse(
+        (await indexedDBService.getItem(key)) || '{}',
+      );
+      expect(storeItem).toEqual({
+        foo: 'baz',
+      });
+    });
+  });
+
+  describe('parse/stringify', () => {
+    it('uses custom parsing/stringification when specified', async () => {
+      const indexedDBService = TestBed.inject(IndexedDBService);
+      const parse = (stateString: string) => {
+        const [foo, age] = stateString.split('_');
+        return {
+          foo,
+          age: +age,
+        };
+      };
+
+      const Store = signalStore(
+        { providedIn: 'root', protectedState: false },
+        withState(initialState),
+        withStorageSync(
+          {
+            key,
+            parse,
+            stringify: (state) => `${state.foo}_${state.age}`,
+          },
+          withIndexedDB(),
+        ),
+      );
+
+      const store = TestBed.inject(Store);
+      await waitForSyncStable(store);
+      patchState(store, { foo: 'baz' });
+      await waitForSyncStable(store);
+
+      const storeItem = parse((await indexedDBService.getItem(key)) || '');
+      expect(storeItem).toEqual({
+        ...initialState,
+        foo: 'baz',
+      });
+    });
+  });
+
+  describe('withStorageSync', () => {
+    let warnings = [] as string[];
+
+    jest.spyOn(console, 'warn').mockImplementation((...messages: string[]) => {
+      warnings.push(...messages);
+    });
+
+    beforeEach(() => {
+      warnings = [];
+    });
+
+    it('logs when writing happens before state is synchronized', async () => {
+      const Store = signalStore(
+        { providedIn: 'root', protectedState: false },
+        withState({ name: 'Delta', age: 52 }),
+        withStorageSync('flights', withIndexedDB()),
+      );
+      const store = TestBed.inject(Store);
+      await waitForSyncStable(store);
+
+      expect(warnings).toEqual([]);
+    });
+
+    it('warns when reading happens during a write', async () => {
+      const Store = signalStore(
+        { providedIn: 'root', protectedState: false },
+        withState({ name: 'Delta', age: 52 }),
+        withStorageSync('flights', withIndexedDB()),
+      );
+
+      const store = TestBed.inject(Store);
+      await waitForSyncStable(store);
+      patchState(store, { name: 'Lufthansa', age: 27 });
+      store.readFromStorage();
+
+      expect(warnings).toEqual([
+        'Reading to Store (flights) 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.',
+      ]);
+    });
+
+    it('warns when writing happens during a read', async () => {
+      const Store = signalStore(
+        { providedIn: 'root', protectedState: false },
+        withState({ name: 'Delta', age: 52 }),
+        withStorageSync('flights', withIndexedDB()),
+      );
+
+      const store = TestBed.inject(Store);
+      await waitForSyncStable(store);
+
+      store.readFromStorage();
+      patchState(store, { name: 'Lufthansa', age: 27 });
+      expect(warnings).toEqual([
+        'Writing to Store (flights) 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.',
+      ]);
+    });
+  });
+});