@angular-architects/ngrx-toolkit 20.0.0 → 20.0.2

package/src/lib/devtools/features/with-disabled-name-indicies.ts

@@ -0,0 +1,31 @@
+import { createDevtoolsFeature } from '../internal/devtools-feature';
+
+/**
+ * If multiple instances of the same SignalStore class
+ * exist, their devtool names are indexed.
+ *
+ * For example:
+ *
+ * ```typescript
+ * const Store = signalStore(
+ *   withDevtools('flights')
+ * )
+ *
+ * const store1 = new Store(); // will show up as 'flights'
+ * const store2 = new Store(); // will show up as 'flights-1'
+ * ```
+ *
+ * With adding `withDisabledNameIndices` to the store:
+ * ```typescript
+ * const Store = signalStore(
+ *   withDevtools('flights', withDisabledNameIndices())
+ * )
+ *
+ * const store1 = new Store(); // will show up as 'flights'
+ * const store2 = new Store(); //💥 throws an error
+ * ```
+ *
+ */
+export function withDisabledNameIndices() {
+  return createDevtoolsFeature({ indexNames: false });
+}

package/src/lib/devtools/features/with-glitch-tracking.ts

@@ -0,0 +1,35 @@
+import { createDevtoolsFeature } from '../internal/devtools-feature';
+import { GlitchTrackerService } from '../internal/glitch-tracker.service';
+
+/**
+ * It tracks all state changes of the State, including intermediary updates
+ * that are typically suppressed by Angular's glitch-free mechanism.
+ *
+ * This feature is especially useful for debugging.
+ *
+ * Example:
+ *
+ * ```typescript
+ * const Store = signalStore(
+ *   { providedIn: 'root' },
+ *   withState({ count: 0 }),
+ *   withDevtools('counter', withGlitchTracking()),
+ *   withMethods((store) => ({
+ *     increase: () =>
+ *       patchState(store, (value) => ({ count: value.count + 1 })),
+ *   }))
+ * );
+ *
+ * // would show up in the DevTools with value 0
+ * const store = inject(Store);
+ *
+ * store.increase(); // would show up in the DevTools with value 1
+ * store.increase(); // would show up in the DevTools with value 2
+ * store.increase(); // would show up in the DevTools with value 3
+ * ```
+ *
+ * Without `withGlitchTracking`, the DevTools would only show the final value of 3.
+ */
+export function withGlitchTracking() {
+  return createDevtoolsFeature({ tracker: GlitchTrackerService });
+}

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

@@ -0,0 +1,34 @@
+import { createDevtoolsFeature, Mapper } from '../internal/devtools-feature';
+
+/**
+ * Allows you to define a function to map the state.
+ *
+ * It is needed for huge states, that slows down the Devtools and where
+ * you don't need to see the whole state or other reasons.
+ *
+ * Example:
+ *
+ * ```typescript
+ * const initialState = {
+ *   id: 1,
+ *   email: 'john.list@host.com',
+ *   name: 'John List',
+ *   enteredPassword: ''
+ * }
+ *
+ * const Store = signalStore(
+ *   withState(initialState),
+ *   withDevtools(
+ *     'user',
+ *     withMapper(state => ({...state, enteredPassword: '***' }))
+ *   )
+ * )
+ * ```
+ *
+ * @param map function which maps the state
+ */
+export function withMapper<State extends object>(
+  map: (state: State) => Record<string, unknown>,
+) {
+  return createDevtoolsFeature({ map: map as Mapper });
+}

package/src/lib/devtools/internal/current-action-names.ts

@@ -0,0 +1 @@
+export const currentActionNames = new Set<string>();

package/src/lib/devtools/internal/default-tracker.ts

@@ -0,0 +1,60 @@
+import { effect, Injectable, signal } from '@angular/core';
+import { getState, StateSource } from '@ngrx/signals';
+import { Tracker, TrackerStores } from './models';
+
+@Injectable({ providedIn: 'root' })
+export class DefaultTracker implements Tracker {
+  readonly #stores = signal<TrackerStores>({});
+
+  get stores(): TrackerStores {
+    return this.#stores();
+  }
+
+  #trackCallback: undefined | ((changedState: Record<string, object>) => void);
+
+  #trackingEffect = effect(() => {
+    if (this.#trackCallback === undefined) {
+      throw new Error('no callback function defined');
+    }
+    const stores = this.#stores();
+
+    const fullState = Object.entries(stores).reduce(
+      (acc, [id, store]) => {
+        return { ...acc, [id]: getState(store) };
+      },
+      {} as Record<string, object>,
+    );
+
+    this.#trackCallback(fullState);
+  });
+
+  track(id: string, store: StateSource<object>): void {
+    this.#stores.update((value) => ({
+      ...value,
+      [id]: store,
+    }));
+  }
+
+  onChange(callback: (changedState: Record<string, object>) => void): void {
+    this.#trackCallback = callback;
+  }
+
+  removeStore(id: string) {
+    this.#stores.update((stores) =>
+      Object.entries(stores).reduce((newStore, [storeId, state]) => {
+        if (storeId !== id) {
+          newStore[storeId] = state;
+        }
+        return newStore;
+      }, {} as TrackerStores),
+    );
+  }
+
+  notifyRenamedStore(id: string): void {
+    if (this.#stores()[id]) {
+      this.#stores.update((stores) => {
+        return { ...stores };
+      });
+    }
+  }
+}

package/src/lib/devtools/internal/devtools-feature.ts

@@ -0,0 +1,37 @@
+import { Tracker } from './models';
+
+export const DEVTOOLS_FEATURE = Symbol('DEVTOOLS_FEATURE');
+
+export type Mapper = (state: object) => object;
+
+export type DevtoolsOptions = {
+  indexNames?: boolean; // defines if names should be indexed.
+  map?: Mapper; // defines a mapper for the state.
+  tracker?: new () => Tracker; // defines a tracker for the state
+};
+
+export type DevtoolsInnerOptions = {
+  indexNames: boolean;
+  map: Mapper;
+  tracker: Tracker;
+};
+
+/**
+ * A DevtoolsFeature adds or modifies the behavior of the
+ * devtools extension.
+ *
+ * We use them (function calls) instead of a config object,
+ * because of tree-shaking.
+ */
+export type DevtoolsFeature = {
+  [DEVTOOLS_FEATURE]: true;
+} & Partial<DevtoolsOptions>;
+
+export function createDevtoolsFeature(
+  options: DevtoolsOptions,
+): DevtoolsFeature {
+  return {
+    [DEVTOOLS_FEATURE]: true,
+    ...options,
+  };
+}

package/src/lib/devtools/internal/devtools-syncer.service.ts

@@ -0,0 +1,202 @@
+import { isPlatformBrowser } from '@angular/common';
+import { inject, Injectable, OnDestroy, PLATFORM_ID } from '@angular/core';
+import { StateSource } from '@ngrx/signals';
+import { throwIfNull } from '../../shared/throw-if-null';
+import { REDUX_DEVTOOLS_CONFIG } from '../provide-devtools-config';
+import { currentActionNames } from './current-action-names';
+import { DevtoolsInnerOptions } from './devtools-feature';
+import { Connection, StoreRegistry, Tracker } from './models';
+
+const dummyConnection: Connection = {
+  send: () => void true,
+};
+
+/**
+ * A service provided by the root injector is
+ * required because the synchronization runs
+ * globally.
+ *
+ * The SignalStore could be provided in a component.
+ * If the effect starts in the injection
+ * context of the SignalStore, the complete sync
+ * process would shut down once the component gets
+ * destroyed.
+ */
+@Injectable({ providedIn: 'root' })
+export class DevtoolsSyncer implements OnDestroy {
+  /**
+   * Stores all SignalStores that are connected to the
+   * DevTools along their options, names and id.
+   */
+  #stores: StoreRegistry = {};
+  readonly #isBrowser = isPlatformBrowser(inject(PLATFORM_ID));
+  readonly #trackers = [] as Tracker[];
+  readonly #devtoolsConfig = {
+    name: 'NgRx SignalStore',
+    ...inject(REDUX_DEVTOOLS_CONFIG, { optional: true }),
+  };
+
+  /**
+   * Maintains the current states of all stores to avoid conflicts
+   * between glitch-free and glitched trackers when used simultaneously.
+   *
+   * The challenge lies in ensuring that glitched trackers do not
+   * interfere with the synchronization process of glitch-free trackers.
+   * Specifically, glitched trackers could cause the synchronization to
+   * read the current state of stores managed by glitch-free trackers.
+   *
+   * Therefore, the synchronization process doesn't read the state from
+   * each store, but relies on #currentState.
+   *
+   * Please note, that here the key is the name and not the id.
+   */
+  #currentState: Record<string, object> = {};
+  #currentId = 1;
+
+  readonly #connection: Connection = this.#isBrowser
+    ? window.__REDUX_DEVTOOLS_EXTENSION__
+      ? window.__REDUX_DEVTOOLS_EXTENSION__.connect(this.#devtoolsConfig)
+      : dummyConnection
+    : dummyConnection;
+
+  constructor() {
+    if (!this.#isBrowser) {
+      return;
+    }
+  }
+
+  ngOnDestroy(): void {
+    currentActionNames.clear();
+  }
+
+  syncToDevTools(changedStatePerId: Record<string, object>) {
+    const mappedChangedStatePerName = Object.entries(changedStatePerId).reduce(
+      (acc, [id, store]) => {
+        const { options, name } = this.#stores[id];
+        acc[name] = options.map(store);
+        return acc;
+      },
+      {} as Record<string, object>,
+    );
+    this.#currentState = {
+      ...this.#currentState,
+      ...mappedChangedStatePerName,
+    };
+
+    const names = Array.from(currentActionNames);
+    const type = names.length ? names.join(', ') : 'Store Update';
+    currentActionNames.clear();
+
+    this.#connection.send({ type }, this.#currentState);
+  }
+
+  getNextId() {
+    return String(this.#currentId++);
+  }
+
+  /**
+   * Consumer provides the id. That is because we can only start
+   * tracking the store in the init hook.
+   * Unfortunately, methods for renaming having the final id
+   * need to be defined already before.
+   * That's why `withDevtools` requests first the id and
+   * then registers itself later.
+   */
+  addStore(
+    id: string,
+    name: string,
+    store: StateSource<object>,
+    options: DevtoolsInnerOptions,
+  ) {
+    let storeName = name;
+    const names = Object.values(this.#stores).map((store) => store.name);
+
+    if (names.includes(storeName)) {
+      // const { options } = throwIfNull(
+      //   Object.values(this.#stores).find((store) => store.name === storeName)
+      // );
+      if (!options.indexNames) {
+        throw new Error(`An instance of the store ${storeName} already exists. \
+Enable automatic indexing via withDevTools('${storeName}', { indexNames: true }), or rename it upon instantiation.`);
+      }
+    }
+
+    for (let i = 1; names.includes(storeName); i++) {
+      storeName = `${name}-${i}`;
+    }
+    this.#stores[id] = { name: storeName, options };
+
+    const tracker = options.tracker;
+    if (!this.#trackers.includes(tracker)) {
+      this.#trackers.push(tracker);
+    }
+
+    tracker.onChange((changedState) => this.syncToDevTools(changedState));
+    tracker.track(id, store);
+  }
+
+  removeStore(id: string) {
+    const name = this.#stores[id].name;
+    this.#stores = Object.entries(this.#stores).reduce(
+      (newStore, [storeId, value]) => {
+        if (storeId !== id) {
+          newStore[storeId] = value;
+        }
+        return newStore;
+      },
+      {} as StoreRegistry,
+    );
+
+    this.#currentState = Object.entries(this.#currentState).reduce(
+      (newState, [storeName, state]) => {
+        if (storeName !== name) {
+          newState[name] = state;
+        }
+        return newState;
+      },
+      {} as Record<string, object>,
+    );
+
+    for (const tracker of this.#trackers) {
+      tracker.removeStore(id);
+    }
+  }
+
+  renameStore(oldName: string, newName: string) {
+    const storeNames = Object.values(this.#stores).map((store) => store.name);
+    const id = throwIfNull(
+      Object.keys(this.#stores).find((id) => this.#stores[id].name === oldName),
+    );
+    if (storeNames.includes(newName)) {
+      throw new Error(
+        `NgRx Toolkit/DevTools: cannot rename from ${oldName} to ${newName}. ${newName} is already assigned to another SignalStore instance.`,
+      );
+    }
+
+    this.#stores = Object.entries(this.#stores).reduce(
+      (newStore, [id, value]) => {
+        if (value.name === oldName) {
+          newStore[id] = { ...value, name: newName };
+        } else {
+          newStore[id] = value;
+        }
+        return newStore;
+      },
+      {} as StoreRegistry,
+    );
+
+    // we don't rename in #currentState but wait for tracker to notify
+    // us with a changed state that contains that name.
+    this.#currentState = Object.entries(this.#currentState).reduce(
+      (newState, [storeName, state]) => {
+        if (storeName !== oldName) {
+          newState[storeName] = state;
+        }
+        return newState;
+      },
+      {} as Record<string, object>,
+    );
+
+    this.#trackers.forEach((tracker) => tracker.notifyRenamedStore(id));
+  }
+}

package/src/lib/devtools/internal/glitch-tracker.service.ts

@@ -0,0 +1,61 @@
+import { Injectable } from '@angular/core';
+import { getState, StateSource, watchState } from '@ngrx/signals';
+import { throwIfNull } from '../../shared/throw-if-null';
+import { Tracker, TrackerStores } from './models';
+
+type Stores = Record<
+  string,
+  { destroyWatcher: () => void; store: StateSource<object> }
+>;
+
+/**
+ * Internal Service used by {@link withGlitchTracking}. It does not rely
+ * on `effect` as {@link DefaultTracker} does but uses the NgRx function
+ * `watchState` to track all state changes.
+ */
+@Injectable({ providedIn: 'root' })
+export class GlitchTrackerService implements Tracker {
+  #stores: Stores = {};
+  #callback: ((changedState: Record<string, object>) => void) | undefined;
+
+  get stores() {
+    return Object.entries(this.#stores).reduce((acc, [id, { store }]) => {
+      acc[id] = store;
+      return acc;
+    }, {} as TrackerStores);
+  }
+
+  onChange(callback: (changedState: Record<string, object>) => void): void {
+    this.#callback = callback;
+  }
+
+  removeStore(id: string): void {
+    this.#stores = Object.entries(this.#stores).reduce(
+      (newStore, [storeId, value]) => {
+        if (storeId !== id) {
+          newStore[storeId] = value;
+        } else {
+          value.destroyWatcher();
+        }
+        return newStore;
+      },
+      {} as Stores,
+    );
+
+    throwIfNull(this.#callback)({});
+  }
+
+  track(id: string, store: StateSource<object>): void {
+    const watcher = watchState(store, (state) => {
+      throwIfNull(this.#callback)({ [id]: state });
+    });
+
+    this.#stores[id] = { destroyWatcher: watcher.destroy, store };
+  }
+
+  notifyRenamedStore(id: string): void {
+    if (Object.keys(this.#stores).includes(id) && this.#callback) {
+      this.#callback({ [id]: getState(this.#stores[id].store) });
+    }
+  }
+}

package/src/lib/devtools/internal/models.ts

@@ -0,0 +1,29 @@
+import { StateSource } from '@ngrx/signals';
+import { ReduxDevtoolsConfig } from '../provide-devtools-config';
+import { DevtoolsInnerOptions } from './devtools-feature';
+
+export type Action = { type: string };
+export type Connection = {
+  send: (action: Action, state: Record<string, unknown>) => void;
+};
+export type ReduxDevtoolsExtension = {
+  connect: (options: ReduxDevtoolsConfig) => Connection;
+};
+
+export type StoreRegistry = Record<
+  string,
+  {
+    options: DevtoolsInnerOptions;
+    name: string;
+  }
+>;
+
+export type Tracker = {
+  track(id: string, store: StateSource<object>): void;
+  onChange(callback: (changedState: Record<string, object>) => void): void;
+  notifyRenamedStore(id: string): void;
+  removeStore(id: string): void;
+  get stores(): TrackerStores;
+};
+
+export type TrackerStores = Record<string, StateSource<object>>;

package/src/lib/devtools/provide-devtools-config.ts

@@ -0,0 +1,32 @@
+import { InjectionToken, ValueProvider } from '@angular/core';
+
+/**
+ * Provides the configuration options for connecting to the Redux DevTools Extension.
+ */
+export function provideDevtoolsConfig(
+  config: ReduxDevtoolsConfig,
+): ValueProvider {
+  return {
+    provide: REDUX_DEVTOOLS_CONFIG,
+    useValue: config,
+  };
+}
+
+/**
+ * Injection token for the configuration options for connecting to the Redux DevTools Extension.
+ */
+export const REDUX_DEVTOOLS_CONFIG = new InjectionToken<ReduxDevtoolsConfig>(
+  'ReduxDevtoolsConfig',
+);
+
+/**
+ * Options for connecting to the Redux DevTools Extension.
+ * @example
+ * const devToolsOptions: ReduxDevtoolsConfig = {
+ *   name: 'My App',
+ * };
+ */
+export type ReduxDevtoolsConfig = {
+  /** Optional name for the devtools instance. If empty, "NgRx SignalStore" will be used. */
+  name?: string;
+};

package/src/lib/devtools/rename-devtools-name.ts

@@ -0,0 +1,21 @@
+import { StateSource } from '@ngrx/signals';
+import { renameDevtoolsMethodName } from './with-devtools';
+
+/**
+ * Renames the name of a store how it appears in the Devtools.
+ * @param store instance of the SignalStore
+ * @param newName new name for the Devtools
+ */
+export function renameDevtoolsName<State extends object>(
+  store: StateSource<State>,
+  newName: string,
+): void {
+  const renameMethod = (store as Record<string, (newName: string) => void>)[
+    renameDevtoolsMethodName
+  ];
+  if (!renameMethod) {
+    throw new Error("Devtools extensions haven't been added to this store.");
+  }
+
+  renameMethod(newName);
+}

package/src/lib/devtools/tests/action-name.spec.ts

@@ -0,0 +1,48 @@
+import { TestBed } from '@angular/core/testing';
+import { signalStore, withMethods, withState } from '@ngrx/signals';
+import { updateState } from '../update-state';
+import { withDevtools } from '../with-devtools';
+import { setupExtensions } from './helpers.spec';
+
+describe('updateState', () => {
+  it('should show the name of the action', () => {
+    const { sendSpy } = setupExtensions();
+    TestBed.inject(
+      signalStore(
+        { providedIn: 'root' },
+        withDevtools('shop'),
+        withState({ name: 'Car' }),
+      ),
+    );
+    TestBed.flushEffects();
+    expect(sendSpy).toHaveBeenCalledWith(
+      { type: 'Store Update' },
+      { shop: { name: 'Car' } },
+    );
+  });
+
+  it('should set the action name', () => {
+    const { sendSpy } = setupExtensions();
+
+    const Store = signalStore(
+      { providedIn: 'root' },
+      withDevtools('shop'),
+      withState({ name: 'Car' }),
+      withMethods((store) => ({
+        setName(name: string) {
+          updateState(store, 'Set Name', { name });
+        },
+      })),
+    );
+    const store = TestBed.inject(Store);
+    TestBed.flushEffects();
+
+    store.setName('i4');
+    TestBed.flushEffects();
+
+    expect(sendSpy).toHaveBeenLastCalledWith(
+      { type: 'Set Name' },
+      { shop: { name: 'i4' } },
+    );
+  });
+});