@angular-architects/ngrx-toolkit 20.0.0 → 20.0.2

package/src/lib/immutable-state/tests/with-immutable-state.spec.ts

@@ -0,0 +1,278 @@
+import { TestBed } from '@angular/core/testing';
+import { getState, patchState, signalStore, withState } from '@ngrx/signals';
+import * as devMode from '../is-dev-mode';
+import { withImmutableState } from '../with-immutable-state';
+
+describe('withImmutableState', () => {
+  const SECRET = Symbol('secret');
+
+  const createInitialState = () => ({
+    user: {
+      firstName: 'John',
+      lastName: 'Smith',
+    },
+    foo: 'bar',
+    numbers: [1, 2, 3],
+    ngrx: 'signals',
+    nestedSymbol: {
+      [SECRET]: 'another secret',
+    },
+    [SECRET]: {
+      code: 'secret',
+      value: '123',
+    },
+  });
+
+  const createStore = (enableInProduction: boolean | undefined) => {
+    const initialState = createInitialState();
+    const Store = signalStore(
+      { protectedState: false },
+      enableInProduction === undefined
+        ? withImmutableState(initialState)
+        : withImmutableState(initialState, { enableInProduction }),
+    );
+    return TestBed.configureTestingModule({ providers: [Store] }).inject(Store);
+  };
+
+  for (const isDevMode of [true, false]) {
+    describe(isDevMode ? 'dev mode' : 'production mode', () => {
+      beforeEach(() => {
+        jest.spyOn(devMode, 'isDevMode').mockReturnValue(isDevMode);
+      });
+      for (const { stateFactory, enableInProduction, name, protectionOn } of [
+        {
+          name: 'dev-only protection',
+          stateFactory: () => createStore(false),
+          enableInProduction: false,
+          protectionOn: isDevMode,
+        },
+        {
+          name: 'production protection',
+          enableInProduction: true,
+          stateFactory: () => createStore(true),
+          protectionOn: true,
+        },
+        {
+          name: 'default settings',
+          enableInProduction: undefined,
+          stateFactory: () => createStore(undefined),
+          protectionOn: isDevMode,
+        },
+      ]) {
+        describe(name, () => {
+          it(`throws not on a mutable change (primitive type)`, () => {
+            const state = stateFactory();
+
+            const patch = () =>
+              patchState(state, (state) => {
+                state.ngrx = 'mutable change';
+                return state;
+              });
+
+            expect(patch).not.toThrow();
+          });
+
+          it(`throws ${protectionOn ? '' : 'not '}on a mutable change (object type)`, () => {
+            const state = stateFactory();
+
+            const patch = () =>
+              patchState(state, (state) => {
+                state.user.firstName = 'Siegfried';
+                return state;
+              });
+
+            if (protectionOn) {
+              expect(patch).toThrow(
+                "Cannot assign to read only property 'firstName' of object",
+              );
+            } else {
+              expect(patch).not.toThrow();
+            }
+          });
+
+          it(`does ${
+            protectionOn ? '' : 'not '
+          }on a nested mutable change`, () => {
+            const state = stateFactory();
+
+            const patch = () =>
+              patchState(state, (state) => {
+                state.user.firstName = 'mutable change';
+                return state;
+              });
+
+            if (protectionOn) {
+              expect(patch).toThrow(
+                "Cannot assign to read only property 'firstName' of object",
+              );
+            } else {
+              expect(patch).not.toThrow();
+            }
+          });
+
+          describe('mutable changes outside of patchState', () => {
+            it(`throws${
+              protectionOn ? '' : ' not'
+            } on reassigned a property of the exposed state`, () => {
+              const state = stateFactory();
+              const patch = () => {
+                state.user().firstName = 'mutable change 1';
+              };
+              if (protectionOn) {
+                expect(patch).toThrow(
+                  "Cannot assign to read only property 'firstName' of object",
+                );
+              } else {
+                expect(patch).not.toThrow();
+              }
+            });
+
+            it(`throws not when exposed state (primitive type) via getState is mutated`, () => {
+              const state = stateFactory();
+              const s = getState(state);
+
+              const patch = () => (s.ngrx = 'mutable change 2');
+              expect(patch).not.toThrow();
+            });
+
+            it(`throws ${protectionOn ? '' : 'not '} when exposed state (object type) via getState is mutated`, () => {
+              const state = stateFactory();
+              const s = getState(state);
+
+              const patch = () => (s.user.firstName = 'Hans');
+
+              if (protectionOn) {
+                expect(patch).toThrow(
+                  "Cannot assign to read only property 'firstName' of object",
+                );
+              } else {
+                expect(patch).not.toThrow();
+              }
+            });
+
+            it(`throws ${
+              protectionOn ? '' : 'not '
+            }when mutable change happens`, () => {
+              const state = stateFactory();
+              const s = { user: { firstName: 'M', lastName: 'S' } };
+              patchState(state, s);
+              const patch = () => {
+                s.user.firstName = 'mutable change 3';
+              };
+              if (protectionOn) {
+                expect(patch).toThrow(
+                  "Cannot assign to read only property 'firstName' of object",
+                );
+              } else {
+                expect(patch).not.toThrow();
+              }
+            });
+
+            it(`throws ${
+              protectionOn ? '' : 'not '
+            }when mutable change of root symbol property happens`, () => {
+              const state = stateFactory();
+              const s = getState(state);
+
+              const patch = () => {
+                s[SECRET].code = 'mutable change';
+              };
+
+              if (protectionOn) {
+                expect(patch).toThrow(
+                  "Cannot assign to read only property 'code' of object",
+                );
+              } else {
+                expect(patch).not.toThrow();
+              }
+            });
+
+            it(`throws ${
+              protectionOn ? '' : 'not '
+            }when mutable change of nested symbol property happens`, () => {
+              const state = stateFactory();
+              const s = getState(state);
+
+              const patch = () => {
+                s.nestedSymbol[SECRET] = 'mutable change';
+              };
+
+              if (protectionOn) {
+                expect(patch).toThrow(
+                  "Cannot assign to read only property 'Symbol(secret)' of object",
+                );
+              } else {
+                expect(patch).not.toThrow();
+              }
+            });
+          });
+
+          describe('special tests', () => {
+            for (const { name, mutationFn } of [
+              {
+                name: 'location',
+                mutationFn: (state: { location: { city: string } }) =>
+                  (state.location.city = 'Paris'),
+              },
+              {
+                name: 'user',
+                mutationFn: (state: { user: { firstName: string } }) =>
+                  (state.user.firstName = 'Jane'),
+              },
+            ]) {
+              it(`throws ${
+                protectionOn ? '' : 'not '
+              }on concatenated state (${name})`, () => {
+                const UserStore = signalStore(
+                  { providedIn: 'root' },
+                  withImmutableState(createInitialState(), {
+                    enableInProduction,
+                  }),
+                  withImmutableState(
+                    { location: { city: 'London' } },
+                    { enableInProduction },
+                  ),
+                );
+                const store = TestBed.inject(UserStore);
+                const state = getState(store);
+
+                if (protectionOn) {
+                  expect(() => mutationFn(state)).toThrow();
+                } else {
+                  expect(() => mutationFn(state)).not.toThrow();
+                }
+              });
+            }
+          });
+
+          it('should be possible to mix both mutable and immutable state', () => {
+            const immutableState = {
+              user: {
+                id: 1,
+                name: 'John',
+              },
+            };
+
+            const mutableState = {
+              address: 'London',
+            };
+            const TestStore = signalStore(
+              { providedIn: 'root', protectedState: false },
+              withImmutableState(immutableState, { enableInProduction }),
+              withState(mutableState),
+            );
+
+            TestBed.inject(TestStore);
+
+            if (protectionOn) {
+              expect(() => (immutableState.user.name = 'Jane')).toThrow();
+            } else {
+              expect(() => (immutableState.user.name = 'Jane')).not.toThrow();
+            }
+            expect(() => (mutableState.address = 'Glastonbury')).not.toThrow();
+          });
+        });
+      }
+    });
+  }
+});

package/src/lib/immutable-state/with-immutable-state.ts

@@ -0,0 +1,150 @@
+import {
+  EmptyFeatureResult,
+  getState,
+  signalStoreFeature,
+  SignalStoreFeature,
+  SignalStoreFeatureResult,
+  watchState,
+  withHooks,
+  withState,
+} from '@ngrx/signals';
+import { deepFreeze } from './deep-freeze';
+import { isDevMode } from './is-dev-mode';
+
+/**
+ * Starting from v20, the root properties of the state object
+ * are all of type `WritableSignal`.
+ *
+ * That means, we cannot freeze root properties, which are of a
+ * primitive data type.
+ *
+ * This is a breaking change, because in v19 the state was a Signal.
+ * We had the possibility to freeze that Signal's
+ * object and could therefore provide immutability for
+ * root properties of primitive data types.
+ *
+ * For example:
+ *
+ * ```ts
+ * const state = {
+ *   id: 1, // was frozen in v19, but not in >= v20
+ *   address: {
+ *     street: 'Main St',
+ *     city: 'Springfield',
+ *   }
+ * }
+ * ```
+ */
+
+/**
+ * Prevents mutation of the state.
+ *
+ * This is done by applying `Object.freeze` to each root
+ * property of the state. Any mutable change within
+ * or outside the `SignalStore` will throw an error.
+ *
+ * Root properties of the state having a primitive data type
+ * are not supported.
+ *
+ *  * For example:
+ *
+ * ```ts
+ * const state = {
+ *   // ⛔️ are not frozen -> mutable changes possible
+ *   id: 1,
+ *
+ *   // ✅ are frozen -> mutable changes throw
+ *   address: {
+ *     street: 'Main St',
+ *     city: 'Springfield',
+ *   }
+ * }
+ * ```
+ *
+ * @param state the state object
+ * @param options enable protection in production (default: false)
+ */
+export function withImmutableState<State extends object>(
+  state: State,
+  options?: { enableInProduction?: boolean },
+): SignalStoreFeature<
+  SignalStoreFeatureResult,
+  EmptyFeatureResult & { state: State }
+>;
+/**
+ * Prevents mutation of the state.
+ *
+ * This is done by applying `Object.freeze` to each root
+ * property of the state. Any mutable change within
+ * or outside the `SignalStore` will throw an error.
+ *
+ * Root properties of the state having a primitive data type
+ * are not supported.
+ *
+ *  * For example:
+ *
+ * ```ts
+ * const state = {
+ *   // ⛔️ are not frozen -> mutable changes possible
+ *   id: 1,
+ *
+ *   // ✅ are frozen -> mutable changes throw
+ *   address: {
+ *     street: 'Main St',
+ *     city: 'Springfield',
+ *   }
+ * }
+ * ```
+ *
+ * @param stateFactory a function returning the state object
+ * @param options enable protection in production (default: false)
+ */
+export function withImmutableState<State extends object>(
+  stateFactory: () => State,
+  options?: { enableInProduction?: boolean },
+): SignalStoreFeature<
+  SignalStoreFeatureResult,
+  EmptyFeatureResult & { state: State }
+>;
+export function withImmutableState<State extends object>(
+  stateOrFactory: State | (() => State),
+  options?: { enableInProduction?: boolean },
+): SignalStoreFeature<
+  SignalStoreFeatureResult,
+  EmptyFeatureResult & { state: State }
+> {
+  const immutableState =
+    typeof stateOrFactory === 'function' ? stateOrFactory() : stateOrFactory;
+  const stateKeys = Reflect.ownKeys(immutableState);
+
+  const applyFreezing = isDevMode() || options?.enableInProduction === true;
+  return signalStoreFeature(
+    withState(immutableState),
+    withHooks((store) => ({
+      onInit() {
+        if (!applyFreezing) {
+          return;
+        }
+        /**
+         * `immutableState` will be initially frozen. That is because
+         * of potential mutations outside the SignalStore
+         *
+         * ```ts
+         * const initialState = {user: {id: 1}};
+         * signalStore(withImmutableState(initialState));
+         *
+         * initialState.user.id = 2; // must throw immutability
+         * ```
+         */
+        deepFreeze(
+          getState(store) as Record<string | symbol, unknown>,
+          stateKeys,
+        );
+
+        watchState(store, (state) => {
+          deepFreeze(state as Record<string | symbol, unknown>, stateKeys);
+        });
+      },
+    })),
+  );
+}

package/src/lib/shared/prettify.ts

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

package/src/lib/shared/signal-store-models.ts

@@ -0,0 +1,30 @@
+/**
+ * This file contains copies of types of the Signal Store which are not public.
+ *
+ * Since certain features depend on them, if we don't want to break
+ * the encapsulation of @ngrx/signals, we decided to copy them.
+ *
+ * Since TypeScript is based on structural typing, we can get away with it.
+ *
+ * If @ngrx/signals changes its internal types, we catch them via integration
+ * tests.
+ *
+ * Because of the "tight coupling", the toolkit doesn't have version range
+ * to @ngrx/signal, but is very precise.
+ */
+import { Signal } from '@angular/core';
+import { EntityId } from '@ngrx/signals/entities';
+
+// withEntites models
+export type EntityState<Entity> = {
+  entityMap: Record<EntityId, Entity>;
+  ids: EntityId[];
+};
+
+export type EntityComputed<Entity> = {
+  entities: Signal<Entity[]>;
+};
+
+export type NamedEntityComputed<Entity, Collection extends string> = {
+  [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;
+}