@angular-architects/ngrx-toolkit 20.0.2 → 20.1.0

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

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

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

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

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

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

@@ -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;
-}