feat: add withImmutableState

`withImmutableState` acts like `withState` but prevents unintended mutations
by throwing a runtime error.

The protection applies not only within SignalStore but also externally.

Author: rainerhahnekamp

apps/demo/e2e/immutable-state.spec.ts

@@ -0,0 +1,27 @@
+import { test, expect } from '@playwright/test';
+
+test.describe('immutable state', () => {
+  test.beforeEach(async ({ page }) => {
+    await page.goto('');
+    await page.getByRole('link', { name: 'withImmutableState' }).click();
+  });
+
+  for (const position of ['inside', 'outside']) {
+    test(`mutation ${position}`, async ({ page }) => {
+      const errorInConsole = page.waitForEvent('console');
+      await page.getByRole('button', { name: position }).click();
+      expect((await errorInConsole).text()).toContain(
+        `Cannot assign to read only property 'id'`
+      );
+    });
+  }
+
+  test(`mutation via form field`, async ({ page }) => {
+    const errorInConsole = page.waitForEvent('console');
+    await page.getByRole('textbox').focus();
+    await page.keyboard.press('Space');
+    expect((await errorInConsole).text()).toContain(
+      `Cannot assign to read only property 'name'`
+    );
+  });
+});

apps/demo/src/app/app.component.html

@@ -20,6 +20,7 @@
       >
       <a mat-list-item routerLink="/todo-storage-sync">withStorageSync</a>
       <a mat-list-item routerLink="/reset">withReset</a>
+      <a mat-list-item routerLink="/immutable-state">withImmutableState</a>
     </mat-nav-list>
   </mat-drawer>
   <mat-drawer-content>

apps/demo/src/app/immutable-state/immutable-state.component.ts

@@ -0,0 +1,58 @@
+import { Component, inject } from '@angular/core';
+import { patchState, signalStore, withMethods } from '@ngrx/signals';
+import { withImmutableState } from '@angular-architects/ngrx-toolkit';
+import { MatButton } from '@angular/material/button';
+import { FormsModule } from '@angular/forms';
+
+const initialState = { user: { id: 1, name: 'Konrad' } };
+
+const UserStore = signalStore(
+  { providedIn: 'root' },
+  withImmutableState(initialState),
+  withMethods((store) => ({
+    mutateState() {
+      patchState(store, (state) => {
+        state.user.id = 2;
+        return state;
+      });
+    },
+  }))
+);
+
+@Component({
+  template: `
+    <h2>
+      <pre>withImmutableState</pre>
+    </h2>
+    <p>
+      withImmutableState throws an error if the state is mutated, regardless
+      inside or outside the SignalStore.
+    </p>
+    <ul>
+      <li>
+        <button mat-raised-button (click)="mutateOutside()">
+          Mutate State outside the SignalStore
+        </button>
+      </li>
+      <li>
+        <button mat-raised-button (click)="mutateInside()">
+          Mutate State inside the SignalStore
+        </button>
+      </li>
+    </ul>
+
+    <p>Form to edit State mutable via ngModel</p>
+    <input [(ngModel)]="userStore.user().name" />
+  `,
+  imports: [MatButton, FormsModule],
+})
+export class ImmutableStateComponent {
+  protected readonly userStore = inject(UserStore);
+  mutateOutside() {
+    initialState.user.id = 2;
+  }
+
+  mutateInside() {
+    this.userStore.mutateState();
+  }
+}

apps/demo/src/app/lazy-routes.ts

@@ -38,4 +38,11 @@ export const lazyRoutes: Route[] = [
     loadComponent: () =>
       import('./reset/todo.component').then((m) => m.TodoComponent),
   },
+  {
+    path: 'immutable-state',
+    loadComponent: () =>
+      import('./immutable-state/immutable-state.component').then(
+        (m) => m.ImmutableStateComponent
+      ),
+  },
 ];

docs/docs/extensions.md

@@ -12,6 +12,7 @@ It offers extensions like:
 - [Storage Sync](./with-storage-sync): Synchronizes the Store with Web Storage
 - [Undo Redo](./with-undo-redo): Adds Undo/Redo functionality to your store
 - [Reset](./with-reset): Adds a `resetState` method to your store
+- [State Immutability Protection](./with-immutable-state): Protects the state from being mutated outside or inside the Store.
 
 To install it, run
 

docs/docs/with-immutable-state.md

@@ -0,0 +1,66 @@
+---
+title: withImmutableState()
+---
+
+`withImmutableState` acts like `withState` but protects
+the state against unintended mutable changes, by throwing
+a runtime error.
+
+The protection is not limited to changes within the
+SignalStore but also outside of it.
+
+```ts
+const initialState = { user: { id: 1, name: 'Konrad' } };
+
+const UserStore = signalStore(
+  { providedIn: 'root' },
+  withImmutableState(initialState),
+  withMethods((store) => ({
+    mutateState() {
+      patchState(store, (state) => {
+        state.user.id = 2;
+        return state;
+      });
+    },
+  }))
+);
+```
+
+If `mutateState` is called, a runtime error will be thrown.
+
+```ts
+class SomeComponent {
+  userStore = inject(UserStore);
+
+  mutateChange() {
+    this.userStore.mutateState(); // 🔥 throws an error
+  }
+}
+```
+
+The same is also true, when `initialState` is changed:
+
+```ts
+initialState.user.id = 2; // 🔥 throws an error
+```
+
+Finally, it could also happen, if third-party libraries or the Angular API does mutations to the state.
+
+A common example is the usage in template-driven forms:
+
+```ts
+@Component({
+  template: ` <input [(ngModel)]="userStore.user().id" /> `,
+})
+class SomeComponent {}
+```
+
+## Protection in production mode
+
+By default, `withImmutableState` is only active in development mode.
+
+There is a way to enable it in production mode as well:
+
+```ts
+const UserStore = signalStore({ providedIn: 'root' }, withImmutableState(initialState, { enableInProduction: true }));
+```

docs/sidebars.ts

@@ -21,6 +21,7 @@ const sidebars: SidebarsConfig = {
     'with-redux',
     'with-storage-sync',
     'with-undo-redo',
+    'with-immutable-state',
   ],
   reduxConnectorSidebar: [
     {

libs/ngrx-toolkit/src/index.ts

@@ -20,3 +20,4 @@ export * from './lib/with-data-service';
 export { withStorageSync, SyncConfig } from './lib/with-storage-sync';
 export * from './lib/with-pagination';
 export { withReset, setResetState } from './lib/with-reset';
+export { withImmutableState } from './lib/immutable-state/with-immutable-state';

libs/ngrx-toolkit/src/lib/immutable-state/deep-freeze.ts

@@ -0,0 +1,43 @@
+/**
+ * Deep freezes a state object along its properties with primitive values
+ * on the first level.
+ *
+ * The reason for this is that the final state is a merge of all
+ * root properties of all states, i.e. `withState`,....
+ *
+ * Since the root object will not be part of the state (shadow clone),
+ * we are not freezing it.
+ */
+
+export function deepFreeze<T extends Record<string | symbol, unknown>>(
+  target: T,
+  // if empty all properties will be frozen
+  propertyNamesToBeFrozen: (string | symbol)[],
+  // also means that we are on the first level
+  isRoot = true
+): void {
+  const runPropertyNameCheck = propertyNamesToBeFrozen.length > 0;
+  for (const key of Reflect.ownKeys(target)) {
+    if (runPropertyNameCheck && !propertyNamesToBeFrozen.includes(key)) {
+      continue;
+    }
+
+    const propValue = target[key];
+    if (isRecordLike(propValue) && !Object.isFrozen(propValue)) {
+      Object.freeze(propValue);
+      deepFreeze(propValue, [], false);
+    } else if (isRoot) {
+      Object.defineProperty(target, key, {
+        value: propValue,
+        writable: false,
+        configurable: false,
+      });
+    }
+  }
+}
+
+function isRecordLike(
+  target: unknown
+): target is Record<string | symbol, unknown> {
+  return typeof target === 'object' && target !== null;
+}

libs/ngrx-toolkit/src/lib/immutable-state/is-dev-mode.ts

@@ -0,0 +1,6 @@
+import { isDevMode as ngIsInDevMode } from '@angular/core';
+
+// necessary wrapper function to test prod mode
+export function isDevMode() {
+  return ngIsInDevMode();
+}