feat(signals): rename withEffects to withEventHandlers (#5009)

BREAKING CHANGES:

The withEffects feature from @ngrx/signals/events plugin is renamed to withEventHandlers.

BEFORE:

import { withEffects } from '@ngrx/signals/events';

export const CounterStore = signalStore(
  withState({ count: 0 }),
  withEffects((store, events = inject(Events)) => ({
    logCount$: events.on(increment).pipe(
      tap(() => console.log(store.count()))
    ),
  }))
);

AFTER:

import { withEventHandlers } from '@ngrx/signals/events';

export const CounterStore = signalStore(
  withState({ count: 0 }),
  withEventHandlers((store, events = inject(Events)) => ({
    logCount$: events.on(increment).pipe(
      tap(() => console.log(store.count()))
    ),
  }))
);

Author: markostanimirovic

modules/signals/events/spec/integration.spec.ts

@@ -32,7 +32,7 @@ import {
   Events,
   injectDispatch,
   on,
-  withEffects,
+  withEventHandlers,
   withReducer,
 } from '../src';
 
@@ -92,7 +92,7 @@ describe('Integration Tests', () => {
     return { requestStatus: { error } };
   }
 
-  describe('withReducer and withEffects', () => {
+  describe('withReducer and withEventHandlers', () => {
     const booksPageEvents = eventGroup({
       source: 'Books Page',
       events: {
@@ -113,7 +113,7 @@ describe('Integration Tests', () => {
         ]),
         on(booksApiEvents.loadedFailure, ({ payload }) => setError(payload))
       ),
-      withEffects(
+      withEventHandlers(
         (_, events = inject(Events), booksService = inject(BooksService)) => ({
           loadUsers$: events
             .on(booksPageEvents.opened, booksPageEvents.refreshed)
@@ -242,15 +242,15 @@ describe('Integration Tests', () => {
       const Store = signalStore(
         { providedIn: 'root' },
         withState({ savedEvents: [] as string[] }),
-        withEffects((_, events = inject(Events)) => ({
+        withEventHandlers((_, events = inject(Events)) => ({
           emitSecond$: events.on(first).pipe(
             tap(({ type }) =>
-              handledEventsLog.push(`emitSecond$ effect: ${type}`)
+              handledEventsLog.push(`emitSecond$ handler: ${type}`)
             ),
             map(() => second())
           ),
           save$: events.on(first, second).pipe(
-            tap(({ type }) => handledEventsLog.push(`save$ effect: ${type}`)),
+            tap(({ type }) => handledEventsLog.push(`save$ handler: ${type}`)),
             map(({ type }) => save(type))
           ),
         })),
@@ -272,17 +272,17 @@ describe('Integration Tests', () => {
       expect(store.savedEvents()).toEqual(['first', 'second']);
       expect(handledEventsLog).toEqual([
         'reducer: first',
-        'emitSecond$ effect: first',
+        'emitSecond$ handler: first',
         'reducer: second',
-        'save$ effect: first',
+        'save$ handler: first',
         'reducer: savefirst',
-        'save$ effect: second',
+        'save$ handler: second',
         'reducer: savesecond',
       ]);
     });
   });
 
-  describe('custom withReducer and withEffects', () => {
+  describe('custom withReducer and withEventHandlers', () => {
     const booksPageEvents = eventGroup({
       source: 'Books Page',
       events: {
@@ -312,10 +312,10 @@ describe('Integration Tests', () => {
       );
     }
 
-    function withBooksEffects() {
+    function withBooksEventHandlers() {
       return signalStoreFeature(
         { state: type<QueryState>() },
-        withEffects(
+        withEventHandlers(
           (
             { query },
             events = inject(Events),
@@ -348,7 +348,7 @@ describe('Integration Tests', () => {
       withEntities<Book>(),
       withRequestStatus(),
       withBooksReducer(),
-      withBooksEffects()
+      withBooksEventHandlers()
     );
 
     it('loads entities when queryChanged and refreshed events are dispatched', fakeAsync(() => {

…signals/events/spec/with-effects.spec.ts …/events/spec/with-event-handlers.spec.tsmodules/signals/events/spec/with-effects.spec.ts renamed to modules/signals/events/spec/with-event-handlers.spec.ts modules/signals/events/spec/with-effects.spec.ts renamed to modules/signals/events/spec/with-event-handlers.spec.ts

@@ -17,11 +17,11 @@ import {
   Events,
   mapToScope,
   toScope,
-  withEffects,
+  withEventHandlers,
 } from '../src';
 import { createLocalService } from '../../spec/helpers';
 
-describe('withEffects', () => {
+describe('withEventHandlers', () => {
   const event1 = event('event1');
   const event2 = event('event2');
   const event3 = event('event3', type<string>());
@@ -42,7 +42,7 @@ describe('withEffects', () => {
           return 'n';
         },
       })),
-      withEffects(({ k, l, m, n, ...store }) => {
+      withEventHandlers(({ k, l, m, n, ...store }) => {
         values.push(k(), l(), m, n(), getState(store).k);
         return {};
       })
@@ -53,10 +53,10 @@ describe('withEffects', () => {
     expect(values).toEqual(['k', 'k l', 'm', 'n', 'k']);
   });
 
-  it('dispatches events returned by effects', () => {
+  it('dispatches events returned by event handlers', () => {
     const Store = signalStore(
       { providedIn: 'root' },
-      withEffects((_, events = inject(Events)) => ({
+      withEventHandlers((_, events = inject(Events)) => ({
         $: events.on(event1, event2).pipe(map(({ type }) => event3(type))),
         $$: events
           .on(event3)
@@ -84,10 +84,10 @@ describe('withEffects', () => {
     ]);
   });
 
-  it('does not re-dispatch the same event when an effect does not return a new event', () => {
+  it('does not re-dispatch the same event when an event handler does not return a new event', () => {
     const Store = signalStore(
       { providedIn: 'root' },
-      withEffects((_, events = inject(Events)) => ({
+      withEventHandlers((_, events = inject(Events)) => ({
         $: events.on(event1).pipe(tap(() => {})),
         $$: events.on(event2).pipe(tap(() => {})),
       }))
@@ -106,12 +106,12 @@ describe('withEffects', () => {
     expect(emittedEvents).toEqual([{ type: 'event1' }, { type: 'event2' }]);
   });
 
-  it('re-dispatches the same event when it is explicitly returned from an effect', () => {
+  it('re-dispatches the same event when it is explicitly returned from an event handler', () => {
     let executionCount = 0;
 
     const Store = signalStore(
       { providedIn: 'root' },
-      withEffects((_, events = inject(Events)) => ({
+      withEventHandlers((_, events = inject(Events)) => ({
         $: events.on(event1).pipe(
           map(() => (executionCount < 2 ? event1() : null)),
           tap(() => executionCount++)
@@ -138,7 +138,7 @@ describe('withEffects', () => {
   it('handles observables returned as an array', () => {
     const Store = signalStore(
       { providedIn: 'root' },
-      withEffects((_, events = inject(Events)) => [
+      withEventHandlers((_, events = inject(Events)) => [
         events.on(event1, event2).pipe(map(({ type }) => event3(type))),
         events.on(event3).pipe(tap(() => {})),
       ])
@@ -165,7 +165,7 @@ describe('withEffects', () => {
   it('dispatches an event with provided scope via toScope', () => {
     const Store = signalStore(
       { providedIn: 'root' },
-      withEffects((_, events = inject(Events)) => ({
+      withEventHandlers((_, events = inject(Events)) => ({
         $: events.on(event1).pipe(map(() => [event2(), toScope('parent')])),
       }))
     );
@@ -184,7 +184,7 @@ describe('withEffects', () => {
   it('dispatches an event with provided scope via mapToScope', () => {
     const Store = signalStore(
       { providedIn: 'root' },
-      withEffects((_, events = inject(Events)) => ({
+      withEventHandlers((_, events = inject(Events)) => ({
         $: events.on(event1).pipe(
           map(() => event3('ngrx')),
           mapToScope('global')
@@ -203,11 +203,11 @@ describe('withEffects', () => {
     });
   });
 
-  it('unsubscribes from effects when the store is destroyed', () => {
+  it('unsubscribes from event handlers when the store is destroyed', () => {
     let executionCount = 0;
 
     const Store = signalStore(
-      withEffects((_, events = inject(Events)) => ({
+      withEventHandlers((_, events = inject(Events)) => ({
         $: events.on(event1).pipe(tap(() => executionCount++)),
       }))
     );

modules/signals/events/src/index.ts

@@ -11,5 +11,5 @@ export {
 } from './event-scope';
 export { Events, ReducerEvents } from './events-service';
 export { injectDispatch } from './inject-dispatch';
-export { withEffects } from './with-effects';
+export { withEventHandlers } from './with-event-handlers';
 export { withReducer } from './with-reducer';

…dules/signals/events/src/with-effects.ts …ignals/events/src/with-event-handlers.tsmodules/signals/events/src/with-effects.ts renamed to modules/signals/events/src/with-event-handlers.ts modules/signals/events/src/with-effects.ts renamed to modules/signals/events/src/with-event-handlers.ts

@@ -20,29 +20,29 @@ import { SOURCE_TYPE } from './events-service';
  * @experimental
  * @description
  *
- * SignalStore feature for defining side effects.
+ * SignalStore feature for defining event handlers.
  *
  * @usageNotes
  *
  * ```ts
  * import { signalStore, withState } from '@ngrx/signals';
- * import { event, Events, withEffects } from '@ngrx/signals/events';
+ * import { event, Events, withEventHandlers } from '@ngrx/signals/events';
  *
  * const increment = event('[Counter Page] Increment');
  * const decrement = event('[Counter Page] Decrement');
  *
  * const CounterStore = signalStore(
  *   withState({ count: 0 }),
- *   withEffects(({ count }, events = inject(Events)) => ({
+ *   withEventHandlers(({ count }, events = inject(Events)) => ({
  *     logCount$: events.on(increment, decrement).pipe(
  *       tap(({ type }) => console.log(type, count())),
  *     ),
  *   })),
  * );
  * ```
  */
-export function withEffects<Input extends SignalStoreFeatureResult>(
-  effectsFactory: (
+export function withEventHandlers<Input extends SignalStoreFeatureResult>(
+  handlersFactory: (
     store: Prettify<
       StateSignals<Input['state']> &
         Input['props'] &
@@ -55,9 +55,9 @@ export function withEffects<Input extends SignalStoreFeatureResult>(
     type<Input>(),
     withHooks({
       onInit(store, dispatcher = inject(Dispatcher)) {
-        const effectSources = effectsFactory(store);
-        const effects = Object.values(effectSources).map((effectSource$) =>
-          effectSource$.pipe(
+        const handlerSources = handlersFactory(store);
+        const handlers = Object.values(handlerSources).map((handlerSource$) =>
+          handlerSource$.pipe(
             tap((result) => {
               const [potentialEvent, config] = Array.isArray(result)
                 ? result
@@ -73,7 +73,7 @@ export function withEffects<Input extends SignalStoreFeatureResult>(
           )
         );
 
-        merge(...effects)
+        merge(...handlers)
           .pipe(takeUntilDestroyed())
           .subscribe();
       },

modules/signals/events/src/with-reducer.ts

@@ -1,24 +1,23 @@
 import { inject, untracked } from '@angular/core';
-import { takeUntilDestroyed } from '@angular/core/rxjs-interop';
-import { merge, tap } from 'rxjs';
+import { tap } from 'rxjs';
 import {
   EmptyFeatureResult,
   getState,
   patchState,
   SignalStoreFeature,
   signalStoreFeature,
   type,
-  withHooks,
 } from '@ngrx/signals';
 import { CaseReducerResult } from './case-reducer';
 import { EventCreator } from './event-creator';
 import { ReducerEvents } from './events-service';
+import { withEventHandlers } from './with-event-handlers';
 
 /**
  * @experimental
  * @description
  *
- * SignalStore feature for defining state changes based on dispatched events.
+ * SignalStore feature for defining state transitions based on dispatched events.
  *
  * @usageNotes
  *
@@ -44,24 +43,18 @@ export function withReducer<State extends object>(
 > {
   return signalStoreFeature(
     { state: type<State>() },
-    withHooks({
-      onInit(store, events = inject(ReducerEvents)) {
-        const updates = caseReducers.map((caseReducer) =>
-          events.on(...caseReducer.events).pipe(
-            tap((event) => {
-              const state = untracked(() => getState(store));
-              const result = caseReducer.reducer(event, state);
-              const updaters = Array.isArray(result) ? result : [result];
+    withEventHandlers((store, events = inject(ReducerEvents)) =>
+      caseReducers.map((caseReducer) =>
+        events.on(...caseReducer.events).pipe(
+          tap((event) => {
+            const state = untracked(() => getState(store));
+            const result = caseReducer.reducer(event, state);
+            const updaters = Array.isArray(result) ? result : [result];
 
-              patchState(store, ...updaters);
-            })
-          )
-        );
-
-        merge(...updates)
-          .pipe(takeUntilDestroyed())
-          .subscribe();
-      },
-    })
+            patchState(store, ...updaters);
+          })
+        )
+      )
+    )
   );
 }