@angular-architects/ngrx-toolkit 19.2.3 → 19.4.0

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

@@ -0,0 +1,260 @@
+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 ${protectionOn ? '' : 'not '}on a mutable change`, () => {
+            const state = stateFactory();
+
+            const patch = () =>
+              patchState(state, (state) => {
+                state.ngrx = 'mutable change';
+                return state;
+              });
+
+            if (protectionOn) {
+              expect(patch).toThrowError(
+                "Cannot assign to read only property 'ngrx' of object",
+              );
+            } else {
+              expect(patch).not.toThrowError();
+            }
+          });
+
+          it(`throws ${
+            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).toThrowError(
+                "Cannot assign to read only property 'firstName' of object",
+              );
+            } else {
+              expect(patch).not.toThrowError();
+            }
+          });
+
+          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).toThrowError(
+                  "Cannot assign to read only property 'firstName' of object",
+                );
+              } else {
+                expect(patch).not.toThrowError();
+              }
+            });
+
+            it(`throws ${
+              protectionOn ? '' : 'not '
+            }when exposed state via getState is mutated`, () => {
+              const state = stateFactory();
+              const s = getState(state);
+
+              const patch = () => (s.ngrx = 'mutable change 2');
+
+              if (protectionOn) {
+                expect(patch).toThrowError(
+                  "Cannot assign to read only property 'ngrx' of object",
+                );
+              } else {
+                expect(patch).not.toThrowError();
+              }
+            });
+
+            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).toThrowError(
+                  "Cannot assign to read only property 'firstName' of object",
+                );
+              } else {
+                expect(patch).not.toThrowError();
+              }
+            });
+
+            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).toThrowError(
+                  "Cannot assign to read only property 'code' of object",
+                );
+              } else {
+                expect(patch).not.toThrowError();
+              }
+            });
+
+            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).toThrowError(
+                  "Cannot assign to read only property 'Symbol(secret)' of object",
+                );
+              } else {
+                expect(patch).not.toThrowError();
+              }
+            });
+          });
+
+          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)).toThrowError();
+                } else {
+                  expect(() => mutationFn(state)).not.toThrowError();
+                }
+              });
+            }
+          });
+
+          it('should be possible to mix both mutable and immutable state', () => {
+            const immutableState = {
+              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.name = 'Jane')).toThrow();
+            } else {
+              expect(() => (immutableState.name = 'Jane')).not.toThrow();
+            }
+            expect(
+              () => (mutableState.address = 'Glastonbury'),
+            ).not.toThrowError();
+          });
+        });
+      }
+    });
+  }
+});

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

@@ -0,0 +1,115 @@
+import {
+  EmptyFeatureResult,
+  signalStoreFeature,
+  SignalStoreFeature,
+  SignalStoreFeatureResult,
+  watchState,
+  withHooks,
+  withState,
+} from '@ngrx/signals';
+import { deepFreeze } from './deep-freeze';
+import { isDevMode } from './is-dev-mode';
+
+/**
+ * The implementation of this feature is a little bit tricky.
+ *
+ * `signalStore` does a shallow clone in the initial phase, in order to
+ * merge all different states together.
+ *
+ * Shallow cloning also happens in `patchState`.
+ *
+ * With shallow cloning, the root state object is replaced, which means,
+ * the freezing only stays for its nested properties but not for
+ * the primitive and immediate properties.
+ *
+ * For example:
+ *
+ * ```ts
+ * const state = {
+ *   id: 1,
+ *   address: {
+ *     street: 'Main St',
+ *     city: 'Springfield',
+ *   }
+ * }
+ * ```
+ *
+ * Running `Object.freeze` on `state` will freeze the `address` object, and
+ * the `id`. But since `state` is shallow cloned, the "frozing" state of the
+ * `id` is lost. `address`, being an object, is still frozen.
+ *
+ * To overcome that, we run `watchState` and run `deepFreeze`
+ * on every change.
+ */
+
+/**
+ * Prevents mutation of the state.
+ *
+ * This is done by deeply applying `Object.freeze`. Any mutable change within
+ * or outside the `SignalStore` will throw an error.
+ *
+ * @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 deeply applying `Object.freeze`. Any mutable change within
+ * or outside the `SignalStore` will throw an error.
+ *
+ * @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 = {id: 1};
+         * signalStore(withImmutableState(initialState));
+         *
+         * initialState.id = 2; // must throw immutability
+         * ```
+         */
+
+        Object.freeze(immutableState);
+        watchState(store, (state) => {
+          deepFreeze(state, stateKeys);
+        });
+      },
+    })),
+  );
+}