Rename listener middleware public APIs and rework return value

This commit makes major breaking changes to the listener middleware.

First, we've renamed all the public methods and action creators,
so that we have a consistent naming scheme without clashes:

- API: `createListenerMiddleware`
- Returns: `{middleware, startListening, stopListening, clearListeners}`
- Docs examples show the object as `listenerMiddleware`
- One entry: "listener"
- Field in that listener entry: `effect`
- Action creators: `addListener`, `removeListener`, `removeAllListeners`

Next, `createListenerMiddleware` now returns an object containing
`{middleware, start/stop/clear}`, rather than the middleware itself
with those methods attached.

This works around the TS inference issues from attaching the add
and remove functions directly to the middleware function itself,
and allows `const unsub = dispatch(addListener())` to have
correct TS types for the return value.

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)
@@ -300,9 +297,9 @@ export function createListenerMiddleware<
     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) {
@@ -312,16 +309,16 @@ export function createListenerMiddleware<
     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()
@@ -336,18 +333,21 @@ export function createListenerMiddleware<
     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,
@@ -374,7 +374,7 @@ export function createListenerMiddleware<
     } catch (listenerError) {
       if (!(listenerError instanceof TaskAbortError)) {
         safelyNotifyError(onError, listenerError, {
-          raisedBy: 'listener',
+          raisedBy: 'effect',
         })
       }
     } finally {
@@ -385,84 +385,76 @@ export function createListenerMiddleware<
 
   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>
 }