Merge pull request #2005 from reduxjs/feature/listener-signature-changes

Author: markerikson

packages/action-listener-middleware/README.md

@@ -9,25 +9,25 @@ import type {
 import { createAction, nanoid } from '@reduxjs/toolkit'
 
 import type {
-  ActionListenerMiddleware,
+  ListenerMiddleware,
+  ListenerMiddlewareInstance,
   AddListenerOverloads,
-  AnyActionListenerPredicate,
+  AnyListenerPredicate,
   CreateListenerMiddlewareOptions,
   TypedActionCreator,
+  TypedStartListening,
   TypedAddListener,
-  TypedAddListenerAction,
   TypedCreateListenerEntry,
   FallbackAddListenerOptions,
   ListenerEntry,
   ListenerErrorHandler,
   Unsubscribe,
-  WithMiddlewareType,
   TakePattern,
   ListenerErrorInfo,
   ForkedTaskExecutor,
   ForkedTask,
-  TypedRemoveListenerAction,
   TypedRemoveListener,
+  TypedStopListening,
 } from './types'
 import { assertFunction, catchRejection } from './utils'
 import { TaskAbortError } from './exceptions'
@@ -40,16 +40,15 @@ import {
 } from './task'
 export { TaskAbortError } from './exceptions'
 export type {
-  ActionListener,
-  ActionListenerMiddleware,
-  ActionListenerMiddlewareAPI,
-  ActionListenerOptions,
+  ListenerEffect,
+  ListenerMiddleware,
+  ListenerEffectAPI,
   CreateListenerMiddlewareOptions,
   ListenerErrorHandler,
+  TypedStartListening,
   TypedAddListener,
-  TypedAddListenerAction,
+  TypedStopListening,
   TypedRemoveListener,
-  TypedRemoveListenerAction,
   Unsubscribe,
   ForkedTaskExecutor,
   ForkedTask,
@@ -69,7 +68,7 @@ const { assign } = Object
  */
 const INTERNAL_NIL_TOKEN = {} as const
 
-const alm = 'actionListenerMiddleware' as const
+const alm = 'listenerMiddleware' as const
 
 const createFork = (parentAbortSignal: AbortSignal) => {
   return <T>(taskExecutor: ForkedTaskExecutor<T>): ForkedTask<T> => {
@@ -100,17 +99,17 @@ const createFork = (parentAbortSignal: AbortSignal) => {
 }
 
 const createTakePattern = <S>(
-  addListener: AddListenerOverloads<Unsubscribe, S, Dispatch<AnyAction>>,
+  startListening: AddListenerOverloads<Unsubscribe, S, Dispatch<AnyAction>>,
   signal: AbortSignal
 ): TakePattern<S> => {
   /**
-   * A function that takes an ActionListenerPredicate and an optional timeout,
+   * A function that takes a ListenerPredicate and an optional timeout,
    * and resolves when either the predicate returns `true` based on an action
    * state combination or when the timeout expires.
    * If the parent listener is canceled while waiting, this will throw a
    * TaskAbortError.
    */
-  const take = async <P extends AnyActionListenerPredicate<S>>(
+  const take = async <P extends AnyListenerPredicate<S>>(
     predicate: P,
     timeout: number | undefined
   ) => {
@@ -121,9 +120,9 @@ const createTakePattern = <S>(
 
     const tuplePromise = new Promise<[AnyAction, S, S]>((resolve) => {
       // Inside the Promise, we synchronously add the listener.
-      unsubscribe = addListener({
+      unsubscribe = startListening({
         predicate: predicate as any,
-        listener: (action, listenerApi): void => {
+        effect: (action, listenerApi): void => {
           // One-shot listener that cleans up as soon as the predicate passes
           listenerApi.unsubscribe()
           // Resolve the promise with the same arguments the predicate saw
@@ -158,14 +157,12 @@ const createTakePattern = <S>(
     }
   }
 
-  return ((
-    predicate: AnyActionListenerPredicate<S>,
-    timeout: number | undefined
-  ) => catchRejection(take(predicate, timeout))) as TakePattern<S>
+  return ((predicate: AnyListenerPredicate<S>, timeout: number | undefined) =>
+    catchRejection(take(predicate, timeout))) as TakePattern<S>
 }
 
 const getListenerEntryPropsFrom = (options: FallbackAddListenerOptions) => {
-  let { type, actionCreator, matcher, predicate, listener } = options
+  let { type, actionCreator, matcher, predicate, effect } = options
 
   if (type) {
     predicate = createAction(type).match
@@ -182,21 +179,21 @@ const getListenerEntryPropsFrom = (options: FallbackAddListenerOptions) => {
     )
   }
 
-  assertFunction(listener, 'options.listener')
+  assertFunction(effect, 'options.listener')
 
-  return { predicate, type, listener }
+  return { predicate, type, effect }
 }
 
 /** Accepts the possible options for creating a listener, and returns a formatted listener entry */
 export const createListenerEntry: TypedCreateListenerEntry<unknown> = (
   options: FallbackAddListenerOptions
 ) => {
-  const { type, predicate, listener } = getListenerEntryPropsFrom(options)
+  const { type, predicate, effect } = getListenerEntryPropsFrom(options)
 
   const id = nanoid()
   const entry: ListenerEntry<unknown> = {
     id,
-    listener,
+    effect,
     type,
     predicate,
     pending: new Set<AbortController>(),
@@ -248,21 +245,21 @@ const safelyNotifyError = (
 /**
  * @alpha
  */
-export const addListenerAction = createAction(
+export const addListener = createAction(
   `${alm}/add`
-) as TypedAddListenerAction<unknown>
+) as TypedAddListener<unknown>
 
 /**
  * @alpha
  */
-export const clearListenerMiddlewareAction = createAction(`${alm}/clear`)
+export const removeAllListeners = createAction(`${alm}/removeAll`)
 
 /**
  * @alpha
  */
-export const removeListenerAction = createAction(
+export const removeListener = createAction(
   `${alm}/remove`
-) as TypedRemoveListenerAction<unknown>
+) as TypedRemoveListener<unknown>
 
 const defaultErrorHandler: ListenerErrorHandler = (...args: unknown[]) => {
   console.error(`${alm}/error`, ...args)
@@ -271,9 +268,8 @@ const defaultErrorHandler: ListenerErrorHandler = (...args: unknown[]) => {
 /**
  * @alpha
  */
-export function createActionListenerMiddleware<
+export function createListenerMiddleware<
   S = unknown,
-  // TODO Carry through the thunk extra arg somehow?
   D extends Dispatch<AnyAction> = ThunkDispatch<S, unknown, AnyAction>,
   ExtraArgument = unknown
 >(middlewareOptions: CreateListenerMiddlewareOptions<ExtraArgument> = {}) {
@@ -301,9 +297,9 @@ export function createActionListenerMiddleware<
     return undefined
   }
 
-  const addListener = (options: FallbackAddListenerOptions) => {
+  const startListening = (options: FallbackAddListenerOptions) => {
     let entry = findListenerEntry(
-      (existingEntry) => existingEntry.listener === options.listener
+      (existingEntry) => existingEntry.effect === options.effect
     )
 
     if (!entry) {
@@ -313,16 +309,16 @@ export function createActionListenerMiddleware<
     return insertEntry(entry)
   }
 
-  const removeListener = (options: FallbackAddListenerOptions): boolean => {
-    const { type, listener, predicate } = getListenerEntryPropsFrom(options)
+  const stopListening = (options: FallbackAddListenerOptions): boolean => {
+    const { type, effect, predicate } = getListenerEntryPropsFrom(options)
 
     const entry = findListenerEntry((entry) => {
       const matchPredicateOrType =
         typeof type === 'string'
           ? entry.type === type
           : entry.predicate === predicate
 
-      return matchPredicateOrType && entry.listener === listener
+      return matchPredicateOrType && entry.effect === effect
     })
 
     entry?.unsubscribe()
@@ -337,18 +333,21 @@ export function createActionListenerMiddleware<
     getOriginalState: () => S
   ) => {
     const internalTaskController = new AbortController()
-    const take = createTakePattern(addListener, internalTaskController.signal)
+    const take = createTakePattern(
+      startListening,
+      internalTaskController.signal
+    )
 
     try {
       entry.pending.add(internalTaskController)
       await Promise.resolve(
-        entry.listener(
+        entry.effect(
           action,
           // Use assign() rather than ... to avoid extra helper functions added to bundle
           assign({}, api, {
             getOriginalState,
             condition: (
-              predicate: AnyActionListenerPredicate<any>,
+              predicate: AnyListenerPredicate<any>,
               timeout?: number
             ) => take(predicate, timeout).then(Boolean),
             take,
@@ -375,7 +374,7 @@ export function createActionListenerMiddleware<
     } catch (listenerError) {
       if (!(listenerError instanceof TaskAbortError)) {
         safelyNotifyError(onError, listenerError, {
-          raisedBy: 'listener',
+          raisedBy: 'effect',
         })
       }
     } finally {
@@ -386,84 +385,76 @@ export function createActionListenerMiddleware<
 
   const clearListenerMiddleware = createClearListenerMiddleware(listenerMap)
 
-  const middleware: Middleware<
-    {
-      (action: Action<`${typeof alm}/add`>): Unsubscribe
-    },
-    S,
-    D
-  > = (api) => (next) => (action) => {
-    if (addListenerAction.match(action)) {
-      return addListener(action.payload)
-    }
+  const middleware: ListenerMiddleware<S, D, ExtraArgument> =
+    (api) => (next) => (action) => {
+      if (addListener.match(action)) {
+        return startListening(action.payload)
+      }
 
-    if (clearListenerMiddlewareAction.match(action)) {
-      clearListenerMiddleware()
-      return
-    }
+      if (removeAllListeners.match(action)) {
+        clearListenerMiddleware()
+        return
+      }
 
-    if (removeListenerAction.match(action)) {
-      return removeListener(action.payload)
-    }
+      if (removeListener.match(action)) {
+        return stopListening(action.payload)
+      }
 
-    // Need to get this state _before_ the reducer processes the action
-    let originalState: S | typeof INTERNAL_NIL_TOKEN = api.getState()
+      // Need to get this state _before_ the reducer processes the action
+      let originalState: S | typeof INTERNAL_NIL_TOKEN = api.getState()
 
-    // `getOriginalState` can only be called synchronously.
-    // @see https://github.com/reduxjs/redux-toolkit/discussions/1648#discussioncomment-1932820
-    const getOriginalState = (): S => {
-      if (originalState === INTERNAL_NIL_TOKEN) {
-        throw new Error(
-          `${alm}: getOriginalState can only be called synchronously`
-        )
+      // `getOriginalState` can only be called synchronously.
+      // @see https://github.com/reduxjs/redux-toolkit/discussions/1648#discussioncomment-1932820
+      const getOriginalState = (): S => {
+        if (originalState === INTERNAL_NIL_TOKEN) {
+          throw new Error(
+            `${alm}: getOriginalState can only be called synchronously`
+          )
+        }
+
+        return originalState as S
       }
 
-      return originalState as S
-    }
+      let result: unknown
 
-    let result: unknown
+      try {
+        // Actually forward the action to the reducer before we handle listeners
+        result = next(action)
 
-    try {
-      // Actually forward the action to the reducer before we handle listeners
-      result = next(action)
-
-      if (listenerMap.size > 0) {
-        let currentState = api.getState()
-        for (let entry of listenerMap.values()) {
-          let runListener = false
-
-          try {
-            runListener = entry.predicate(action, currentState, originalState)
-          } catch (predicateError) {
-            runListener = false
-
-            safelyNotifyError(onError, predicateError, {
-              raisedBy: 'predicate',
-            })
-          }
+        if (listenerMap.size > 0) {
+          let currentState = api.getState()
+          for (let entry of listenerMap.values()) {
+            let runListener = false
 
-          if (!runListener) {
-            continue
-          }
+            try {
+              runListener = entry.predicate(action, currentState, originalState)
+            } catch (predicateError) {
+              runListener = false
 
-          notifyListener(entry, action, api, getOriginalState)
+              safelyNotifyError(onError, predicateError, {
+                raisedBy: 'predicate',
+              })
+            }
+
+            if (!runListener) {
+              continue
+            }
+
+            notifyListener(entry, action, api, getOriginalState)
+          }
         }
+      } finally {
+        // Remove `originalState` store from this scope.
+        originalState = INTERNAL_NIL_TOKEN
       }
-    } finally {
-      // Remove `originalState` store from this scope.
-      originalState = INTERNAL_NIL_TOKEN
-    }
 
-    return result
-  }
+      return result
+    }
 
-  return assign(
+  return {
     middleware,
-    {
-      addListener: addListener as TypedAddListener<S, D>,
-      removeListener: removeListener as TypedRemoveListener<S, D>,
-      clearListeners: clearListenerMiddleware,
-    },
-    {} as WithMiddlewareType<typeof middleware>
-  )
+    startListening,
+    stopListening,
+    clearListeners: clearListenerMiddleware,
+  } as ListenerMiddlewareInstance<S, D, ExtraArgument>
 }