@angular-architects/ngrx-toolkit 20.0.0 → 20.0.2

package/src/lib/devtools/tests/with-glitch-tracking.spec.ts

@@ -0,0 +1,272 @@
+import {
+  createEnvironmentInjector,
+  EnvironmentInjector,
+  inject,
+  runInInjectionContext,
+} from '@angular/core';
+import { TestBed } from '@angular/core/testing';
+import { patchState, signalStore, withMethods, withState } from '@ngrx/signals';
+import { withGlitchTracking } from '../features/with-glitch-tracking';
+import { renameDevtoolsName } from '../rename-devtools-name';
+import { withDevtools } from '../with-devtools';
+import { setupExtensions } from './helpers.spec';
+
+describe('withGlitchTracking', () => {
+  it('should sync immediately upon instantiation', () => {
+    const { sendSpy } = setupExtensions();
+
+    const Store = signalStore(
+      { providedIn: 'root' },
+      withDevtools('counter', withGlitchTracking()),
+      withState({ count: 0 }),
+    );
+
+    expect(sendSpy).not.toHaveBeenCalled();
+    TestBed.inject(Store);
+
+    expect(sendSpy).toHaveBeenCalledWith(
+      { type: 'Store Update' },
+      { counter: { count: 0 } },
+    );
+  });
+
+  it('should sync synchronous state changes', () => {
+    const { sendSpy } = setupExtensions();
+
+    const Store = signalStore(
+      { providedIn: 'root' },
+      withState({ count: 0 }),
+      withDevtools('counter', withGlitchTracking()),
+      withMethods((store) => ({
+        increase: () =>
+          patchState(store, (value) => ({ count: value.count + 1 })),
+      })),
+    );
+
+    const store = TestBed.inject(Store);
+
+    store.increase();
+    store.increase();
+    store.increase();
+    TestBed.flushEffects();
+
+    expect(sendSpy.mock.calls).toEqual([
+      [{ type: 'Store Update' }, { counter: { count: 0 } }],
+      [{ type: 'Store Update' }, { counter: { count: 1 } }],
+      [{ type: 'Store Update' }, { counter: { count: 2 } }],
+      [{ type: 'Store Update' }, { counter: { count: 3 } }],
+    ]);
+  });
+
+  it('should support a mixed approach', () => {
+    const { sendSpy } = setupExtensions();
+
+    const GlitchFreeStore = signalStore(
+      { providedIn: 'root' },
+      withState({ count: 0 }),
+      withDevtools('glitch-free counter'),
+      withMethods((store) => ({
+        increase: () =>
+          patchState(store, (value) => ({ count: value.count + 1 })),
+      })),
+    );
+
+    const GlitchStore = signalStore(
+      { providedIn: 'root' },
+      withState({ count: 0 }),
+      withDevtools('glitch counter', withGlitchTracking()),
+      withMethods((store) => ({
+        increase: () =>
+          patchState(store, (value) => ({ count: value.count + 1 })),
+      })),
+    );
+
+    const glitchFreeStore = TestBed.inject(GlitchFreeStore);
+    const glitchStore = TestBed.inject(GlitchStore);
+
+    TestBed.flushEffects();
+    for (let i = 0; i < 2; i++) {
+      glitchFreeStore.increase();
+      glitchStore.increase();
+    }
+    TestBed.flushEffects();
+
+    expect(sendSpy.mock.calls).toEqual([
+      [{ type: 'Store Update' }, { 'glitch counter': { count: 0 } }],
+      [
+        { type: 'Store Update' },
+        { 'glitch-free counter': { count: 0 }, 'glitch counter': { count: 0 } },
+      ],
+      [
+        { type: 'Store Update' },
+        { 'glitch-free counter': { count: 0 }, 'glitch counter': { count: 1 } },
+      ],
+      [
+        { type: 'Store Update' },
+        { 'glitch-free counter': { count: 0 }, 'glitch counter': { count: 2 } },
+      ],
+      [
+        { type: 'Store Update' },
+        { 'glitch-free counter': { count: 2 }, 'glitch counter': { count: 2 } },
+      ],
+    ]);
+  });
+
+  it('two glitch stores should sync per change', () => {
+    const { sendSpy } = setupExtensions();
+
+    const GlitchStore1 = signalStore(
+      { providedIn: 'root' },
+      withState({ count: 0 }),
+      withDevtools('glitch counter 1', withGlitchTracking()),
+      withMethods((store) => ({
+        increase: () =>
+          patchState(store, (value) => ({ count: value.count + 1 })),
+      })),
+    );
+
+    const GlitchStore2 = signalStore(
+      { providedIn: 'root' },
+      withState({ count: 0 }),
+      withDevtools('glitch counter 2', withGlitchTracking()),
+      withMethods((store) => ({
+        increase: () =>
+          patchState(store, (value) => ({ count: value.count + 1 })),
+      })),
+    );
+
+    const glitchStore1 = TestBed.inject(GlitchStore1);
+    const glitchStore2 = TestBed.inject(GlitchStore2);
+
+    for (let i = 0; i < 2; i++) {
+      glitchStore1.increase();
+      glitchStore2.increase();
+    }
+    TestBed.flushEffects();
+
+    expect(sendSpy.mock.calls).toEqual([
+      [{ type: 'Store Update' }, { 'glitch counter 1': { count: 0 } }],
+      [
+        { type: 'Store Update' },
+        { 'glitch counter 1': { count: 0 }, 'glitch counter 2': { count: 0 } },
+      ],
+      [
+        { type: 'Store Update' },
+        { 'glitch counter 1': { count: 1 }, 'glitch counter 2': { count: 0 } },
+      ],
+      [
+        { type: 'Store Update' },
+        { 'glitch counter 1': { count: 1 }, 'glitch counter 2': { count: 1 } },
+      ],
+      [
+        { type: 'Store Update' },
+        { 'glitch counter 1': { count: 2 }, 'glitch counter 2': { count: 1 } },
+      ],
+      [
+        { type: 'Store Update' },
+        { 'glitch counter 1': { count: 2 }, 'glitch counter 2': { count: 2 } },
+      ],
+    ]);
+  });
+
+  it('should not sync glitch-free if glitched is renamed', () => {
+    const { sendSpy } = setupExtensions();
+
+    const GlitchFreeStore = signalStore(
+      { providedIn: 'root' },
+      withState({ name: 'Product', price: 10.5 }),
+      withDevtools('flight1'),
+    );
+
+    const GlitchStore = signalStore(
+      { providedIn: 'root' },
+      withState({ name: 'Product', price: 10.5 }),
+      withDevtools('flight2', withGlitchTracking()),
+    );
+
+    TestBed.inject(GlitchFreeStore);
+    const glitchStore = TestBed.inject(GlitchStore);
+
+    TestBed.flushEffects();
+
+    expect(sendSpy.mock.calls).toEqual([
+      [{ type: 'Store Update' }, { flight2: { name: 'Product', price: 10.5 } }],
+      [
+        { type: 'Store Update' },
+        {
+          flight1: { name: 'Product', price: 10.5 },
+          flight2: { name: 'Product', price: 10.5 },
+        },
+      ],
+    ]);
+    sendSpy.mockClear();
+
+    renameDevtoolsName(glitchStore, 'flights2');
+    TestBed.flushEffects();
+
+    expect(sendSpy.mock.calls).toEqual([
+      [
+        { type: 'Store Update' },
+        {
+          flight1: { name: 'Product', price: 10.5 },
+          flights2: { name: 'Product', price: 10.5 },
+        },
+      ],
+    ]);
+  });
+
+  it('should not sync glitch tracker if glitch-free store is renamed', () => {
+    const { sendSpy } = setupExtensions();
+
+    const GlitchFreeStore = signalStore(
+      { providedIn: 'root' },
+      withState({ name: 'Product', price: 10.5 }),
+      withDevtools('flight1'),
+    );
+
+    const GlitchStore = signalStore(
+      { providedIn: 'root' },
+      withState({ name: 'Product', price: 10.5 }),
+      withDevtools('glitched Flights', withGlitchTracking()),
+    );
+
+    const glitchFreeStore = TestBed.inject(GlitchFreeStore);
+    TestBed.inject(GlitchStore);
+    TestBed.flushEffects();
+
+    sendSpy.mockClear();
+    renameDevtoolsName(glitchFreeStore, 'glitch-free Flights');
+    expect(sendSpy).not.toHaveBeenCalled();
+    TestBed.flushEffects();
+
+    expect(sendSpy.mock.calls).toEqual([
+      [
+        { type: 'Store Update' },
+        {
+          'glitch-free Flights': { name: 'Product', price: 10.5 },
+          'glitched Flights': { name: 'Product', price: 10.5 },
+        },
+      ],
+    ]);
+  });
+
+  it('should destroy watcher if store is destroyed', () => {
+    const { sendSpy } = setupExtensions();
+
+    const GlitchStore = signalStore(
+      withState({ name: 'Product', price: 10.5 }),
+      withDevtools('Glitched Store', withGlitchTracking()),
+    );
+
+    const childContext = createEnvironmentInjector(
+      [GlitchStore],
+      TestBed.inject(EnvironmentInjector),
+    );
+    runInInjectionContext(childContext, () => inject(GlitchStore));
+
+    expect(sendSpy).toHaveBeenCalled();
+    sendSpy.mockClear();
+    childContext.destroy();
+    expect(sendSpy).toHaveBeenCalledWith({ type: 'Store Update' }, {});
+  });
+});

package/src/lib/devtools/tests/with-mapper.spec.ts

@@ -0,0 +1,69 @@
+import { TestBed } from '@angular/core/testing';
+import { signalStore, withState } from '@ngrx/signals';
+import { withMapper } from '../features/with-mapper';
+import { withDevtools } from '../with-devtools';
+import { setupExtensions } from './helpers.spec';
+
+function domRemover(state: Record<string, unknown>) {
+  return Object.keys(state).reduce((acc, key) => {
+    const value = state[key];
+
+    if (value instanceof HTMLElement) {
+      return acc;
+    } else {
+      return { ...acc, [key]: value };
+    }
+  }, {});
+}
+
+describe('with-mapper', () => {
+  it('should remove DOM Nodes', () => {
+    const { sendSpy } = setupExtensions();
+
+    const Store = signalStore(
+      { providedIn: 'root' },
+      withState({
+        name: 'Car',
+        carElement: document.createElement('div'),
+      }),
+      withDevtools('shop', withMapper(domRemover)),
+    );
+
+    TestBed.inject(Store);
+    TestBed.flushEffects();
+    expect(sendSpy).toHaveBeenCalledWith(
+      { type: 'Store Update' },
+      { shop: { name: 'Car' } },
+    );
+  });
+
+  it('should every property ending with *Key', () => {
+    const { sendSpy } = setupExtensions();
+    const Store = signalStore(
+      { providedIn: 'root' },
+      withState({
+        name: 'Car',
+        unlockKey: '1234',
+      }),
+      withDevtools(
+        'shop',
+        withMapper((state: Record<string, unknown>) =>
+          Object.keys(state).reduce((acc, key) => {
+            if (key.endsWith('Key')) {
+              return acc;
+            } else {
+              return { ...acc, [key]: state[key] };
+            }
+          }, {}),
+        ),
+      ),
+    );
+
+    TestBed.inject(Store);
+    TestBed.flushEffects();
+    expect(sendSpy).toHaveBeenCalledWith(
+      { type: 'Store Update' },
+      { shop: { name: 'Car' } },
+    );
+  });
+});

package/src/lib/devtools/update-state.ts

@@ -0,0 +1,38 @@
+import {
+  patchState as originalPatchState,
+  PartialStateUpdater,
+  WritableStateSource,
+} from '@ngrx/signals';
+import { currentActionNames } from './internal/current-action-names';
+
+type PatchFn = typeof originalPatchState extends (
+  arg1: infer First,
+  ...args: infer Rest
+) => infer Returner
+  ? (state: First, action: string, ...rest: Rest) => Returner
+  : never;
+
+/**
+ * @deprecated Has been renamed to `updateState`
+ */
+export const patchState: PatchFn = (state, action, ...rest) => {
+  updateState(state, action, ...rest);
+};
+
+/**
+ * Wrapper of `patchState` for DevTools integration. Next to updating the state,
+ * it also sends the action to the DevTools.
+ * @param stateSource state of Signal Store
+ * @param action name of action how it will show in DevTools
+ * @param updaters updater functions or objects
+ */
+export function updateState<State extends object>(
+  stateSource: WritableStateSource<State>,
+  action: string,
+  ...updaters: Array<
+    Partial<NoInfer<State>> | PartialStateUpdater<NoInfer<State>>
+  >
+): void {
+  currentActionNames.add(action);
+  return originalPatchState(stateSource, ...updaters);
+}

package/src/lib/devtools/with-dev-tools-stub.ts

@@ -0,0 +1,6 @@
+import { withDevtools } from './with-devtools';
+
+/**
+ * Stub for DevTools integration. Can be used to disable DevTools in production.
+ */
+export const withDevToolsStub: typeof withDevtools = () => (store) => store;

package/src/lib/devtools/with-devtools.ts

@@ -0,0 +1,81 @@
+import { inject, InjectionToken } from '@angular/core';
+import {
+  EmptyFeatureResult,
+  SignalStoreFeature,
+  signalStoreFeature,
+  withHooks,
+  withMethods,
+} from '@ngrx/signals';
+import { DefaultTracker } from './internal/default-tracker';
+import {
+  DevtoolsFeature,
+  DevtoolsInnerOptions,
+} from './internal/devtools-feature';
+import { DevtoolsSyncer } from './internal/devtools-syncer.service';
+import { ReduxDevtoolsExtension } from './internal/models';
+
+declare global {
+  interface Window {
+    __REDUX_DEVTOOLS_EXTENSION__: ReduxDevtoolsExtension | undefined;
+  }
+}
+
+export const renameDevtoolsMethodName = '___renameDevtoolsName';
+export const uniqueDevtoolsId = '___uniqueDevtoolsId';
+
+const EXISTING_NAMES = new InjectionToken(
+  'Array contain existing names for the signal stores',
+  { factory: () => [] as string[], providedIn: 'root' },
+);
+
+/**
+ * Adds this store as a feature state to the Redux DevTools.
+ *
+ * By default, the action name is 'Store Update'. You can
+ * change that via the {@link updateState} method, which has as second
+ * parameter the action name.
+ *
+ * The standalone function {@link renameDevtoolsName} can rename
+ * the store name.
+ *
+ * @param name name of the store as it should appear in the DevTools
+ * @param features features to extend or modify the behavior of the Devtools
+ */
+export function withDevtools(name: string, ...features: DevtoolsFeature[]) {
+  return signalStoreFeature(
+    withMethods(() => {
+      const syncer = inject(DevtoolsSyncer);
+
+      const id = syncer.getNextId();
+
+      // TODO: use withProps and symbols
+      return {
+        [renameDevtoolsMethodName]: (newName: string) => {
+          syncer.renameStore(name, newName);
+        },
+        [uniqueDevtoolsId]: () => id,
+      } as Record<string, (newName?: unknown) => unknown>;
+    }),
+    withHooks((store) => {
+      const syncer = inject(DevtoolsSyncer);
+      const id = String(store[uniqueDevtoolsId]());
+      return {
+        onInit() {
+          const id = String(store[uniqueDevtoolsId]());
+          const finalOptions: DevtoolsInnerOptions = {
+            indexNames: !features.some((f) => f.indexNames === false),
+            map: features.find((f) => f.map)?.map ?? ((state) => state),
+            tracker: inject(
+              features.find((f) => f.tracker)?.tracker || DefaultTracker,
+            ),
+          };
+
+          syncer.addStore(id, name, store, finalOptions);
+        },
+        onDestroy() {
+          syncer.removeStore(id);
+        },
+      };
+    }),
+  ) as SignalStoreFeature<EmptyFeatureResult, EmptyFeatureResult>;
+}

package/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;
+}

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