feat(devtools): enhance withEventsTracking to support glitch-free tracking and add tests

Author: msari-ipe-ext-1

libs/ngrx-toolkit/src/lib/devtools/features/with-events-tracking.ts

@@ -1,6 +1,7 @@
 import { inject } from '@angular/core';
-import { Events } from '@ngrx/signals/events';
+import { Dispatcher, Events } from '@ngrx/signals/events';
 import { createDevtoolsFeature } from '../internal/devtools-feature';
+import { GlitchTrackerService } from '../internal/glitch-tracker.service';
 
 /**
  * Automatically infers DevTools action names from NgRx SignalStore events.
@@ -9,13 +10,60 @@ import { createDevtoolsFeature } from '../internal/devtools-feature';
  * the event's type as the upcoming DevTools action name. When the corresponding
  * reducer mutates state, the DevTools sync will use that name instead of
  * the default "Store Update".
+ *
+ * By default (withGlitchTracking = true), the `GlitchTrackerService` is used to capture
+ * all intermediate updates (glitched states). To use the default, glitch-free tracker
+ * and synchronize only stable state transitions, set `withGlitchTracking` to `false`.
+ *
+ * @param {{ withGlitchTracking?: boolean }} [options] Options to configure tracking behavior.
+ * @param {boolean} [options.withGlitchTracking=true] Enable capturing intermediate (glitched) state updates.
+ * @returns Devtools feature enabling events-based action naming; glitched tracking is enabled by default.
+ * Set `withGlitchTracking: false` to use glitch-free tracking instead.
+ * @example
+ * // Capture intermediate updates (default)
+ * withDevtools('counter', withEventsTracking());
+ * @example
+ * // Glitch-free tracking (only stable transitions)
+ * withDevtools('counter', withEventsTracking({ withGlitchTracking: false }));
+ * @see withGlitchTracking
  */
-export function withEventsTracking() {
+export function withEventsTracking(
+  options: { withGlitchTracking: boolean } = { withGlitchTracking: true },
+) {
+  const useGlitchTracking = options.withGlitchTracking === true;
   return createDevtoolsFeature({
+    tracker: useGlitchTracking ? GlitchTrackerService : undefined,
     eventsTracking: true,
     onInit: ({ trackEvents }) => {
-      const events = inject(Events);
-      trackEvents(events.on());
+      const reducerEvents = getReducerEvents();
+      if (useGlitchTracking) {
+        trackEvents(reducerEvents.on());
+      } else {
+        trackEvents(inject(Events).on());
+      }
     },
   });
 }
+
+/**
+ * Returns the synchronous reducer event stream exposed by the dispatcher.
+ *
+ * NgRx's `Dispatcher` delivers events to `ReducerEvents` immediately but feeds
+ * the public `Events` stream via `queueScheduler`. When `GlitchTrackerService`
+ * captures the state change synchronously, the queued `Events` emission arrives
+ * too late and DevTools records the update as `Store Update`. Tapping into the
+ * reducer stream keeps event names and state changes aligned on the same tick.
+ *
+ * TODO(@ngrx): expose a synchronous events API (similar to what `withReducer` uses)
+ * so consumers do not need to reach into dispatcher internals.
+ */
+function getReducerEvents() {
+  type ReducerEventsLike = {
+    on(): ReturnType<Dispatcher['events']['on']>;
+  };
+
+  const dispatcher = inject(Dispatcher) as unknown as {
+    reducerEvents: ReducerEventsLike;
+  };
+  return dispatcher.reducerEvents;
+}

libs/ngrx-toolkit/src/lib/devtools/tests/with-events-tracking.spec.ts

@@ -0,0 +1,79 @@
+import { EnvironmentInjector, runInInjectionContext } from '@angular/core';
+import { TestBed } from '@angular/core/testing';
+import { signalStore, type, withState } from '@ngrx/signals';
+import {
+  eventGroup,
+  injectDispatch,
+  on,
+  withReducer,
+} from '@ngrx/signals/events';
+import { withEventsTracking } from '../features/with-events-tracking';
+import { withDevtools } from '../with-devtools';
+import { setupExtensions } from './helpers.spec';
+
+const testEvents = eventGroup({
+  source: 'Spec Store',
+  events: {
+    bump: type<void>(),
+  },
+});
+
+describe('withEventsTracking', () => {
+  it('should send a glitched update on event', async () => {
+    const { sendSpy } = setupExtensions();
+
+    const Store = signalStore(
+      { providedIn: 'root' },
+      withDevtools('store-a', withEventsTracking({ withGlitchTracking: true })),
+      withState({ count: 0 }),
+      withReducer(
+        on(testEvents.bump, (_event, state) => ({ count: state.count + 1 })),
+      ),
+    );
+
+    TestBed.inject(Store);
+
+    runInInjectionContext(TestBed.inject(EnvironmentInjector), () => {
+      injectDispatch(testEvents).bump();
+    });
+
+    expect(sendSpy).toHaveBeenLastCalledWith(
+      { type: '[Spec Store] bump' },
+      { 'store-a': { count: 1 } },
+    );
+  });
+
+  it('should emit two glitched updates when two stores react to the same event', async () => {
+    const { sendSpy } = setupExtensions();
+
+    const StoreA = signalStore(
+      { providedIn: 'root' },
+      withDevtools('store-a', withEventsTracking({ withGlitchTracking: true })),
+      withState({ count: 0 }),
+      withReducer(
+        on(testEvents.bump, (_event, state) => ({ count: state.count + 1 })),
+      ),
+    );
+
+    const StoreB = signalStore(
+      { providedIn: 'root' },
+      withDevtools('store-b', withEventsTracking({ withGlitchTracking: true })),
+      withState({ count: 0 }),
+      withReducer(
+        on(testEvents.bump, (_event, state) => ({ count: state.count + 1 })),
+      ),
+    );
+
+    TestBed.inject(StoreA);
+    TestBed.inject(StoreB);
+
+    runInInjectionContext(TestBed.inject(EnvironmentInjector), () => {
+      injectDispatch(testEvents).bump();
+    });
+
+    expect(sendSpy).toHaveBeenLastCalledWith(
+      { type: '[Spec Store] bump' },
+      { 'store-a': { count: 1 }, 'store-b': { count: 1 } },
+    );
+  });
+});