createListenerMiddleware
Overview
A Redux middleware that lets you define "listener" entries that contain an "effect" callback with additional logic, and a way to specify when that callback should run based on dispatched actions or state changes.
It's intended to be a lightweight alternative to more widely used Redux async middleware like sagas and observables. While similar to thunks in level of complexity and concept, it can be used to replicate some common saga usage patterns.
Conceptually, you can think of this as being similar to React's useEffect hook, except that it runs logic in response to Redux store updates instead of component props/state updates.
Listener effect callbacks have access to dispatch and getState, similar to thunks. The listener also receives a set of async workflow functions like take, condition, pause, fork, and unsubscribe, which allow writing more complex async logic.
Listeners can be defined statically by calling listenerMiddleware.startListening() during setup, or added and removed dynamically at runtime with special dispatch(addListener()) and dispatch(removeListener()) actions.
Basic Usage
import { configureStore, createListenerMiddleware } from '@reduxjs/toolkit'
import todosReducer, {
todoAdded,
todoToggled,
todoDeleted,
} from '../features/todos/todosSlice'
// Create the middleware instance and methods
const listenerMiddleware = createListenerMiddleware()
// Add one or more listener entries that look for specific actions.
// They may contain any sync or async logic, similar to thunks.
listenerMiddleware.startListening({
actionCreator: todoAdded,
effect: async (action, listenerApi) => {
// Run whatever additional side-effect-y logic you want here
console.log('Todo added: ', action.payload.text)
// Can cancel other running instances
listenerApi.cancelActiveListeners()
// Run async logic
const data = await fetchData()
// Pause until action dispatched or state changed
if (await listenerApi.condition(matchSomeAction)) {
// Use the listener API methods to dispatch, get state,
// unsubscribe the listener, start child tasks, and more
listenerApi.dispatch(todoAdded('Buy pet food'))
// Spawn "child tasks" that can do more work and return results
const task = listenerApi.fork(async (forkApi) => {
// Can pause execution
await forkApi.delay(5)
// Complete the child by returning a value
return 42
})
const result = await task.result
// Unwrap the child result in the listener
if (result.status === 'ok') {
// Logs the `42` result value that was returned
console.log('Child succeeded: ', result.value)
}
}
},
})
const store = configureStore({
reducer: {
todos: todosReducer,
},
// Add the listener middleware to the store.
// NOTE: Since this can receive actions with functions inside,
// it should go before the serializability check middleware
middleware: (getDefaultMiddleware) =>
getDefaultMiddleware().prepend(listenerMiddleware.middleware),
})
createListenerMiddleware
Creates an instance of the middleware, which should then be added to the store via configureStore's middleware parameter.
const createListenerMiddleware = (options?: CreateMiddlewareOptions) =>
ListenerMiddlewareInstance
interface CreateListenerMiddlewareOptions<ExtraArgument = unknown> {
extra?: ExtraArgument
onError?: ListenerErrorHandler
}
type ListenerErrorHandler = (
error: unknown,
errorInfo: ListenerErrorInfo,
) => void
interface ListenerErrorInfo {
raisedBy: 'effect' | 'predicate'
}
Middleware Options
extra: an optional "extra argument" that will be injected into thelistenerApiparameter of each listener. Equivalent to the "extra argument" in the Redux Thunk middlewareonError: an optional error handler that gets called with synchronous and async errors raised bylistenerand synchronous errors thrown bypredicate.
Listener Middleware Instance
The "listener middleware instance" returned from createListenerMiddleware is an object similar to the "slice" objects generated by createSlice. The instance object is not the actual Redux middleware itself. Rather, it contains the middleware and some instance methods used to add and remove listener entries within the middleware.
interface ListenerMiddlewareInstance<
State = unknown,
Dispatch extends ThunkDispatch<State, unknown, UnknownAction> = ThunkDispatch<
State,
unknown,
UnknownAction
>,
ExtraArgument = unknown,
> {
middleware: ListenerMiddleware<State, Dispatch, ExtraArgument>
startListening: (options: AddListenerOptions) => Unsubscribe
stopListening: (
options: AddListenerOptions & UnsubscribeListenerOptions,
) => boolean
clearListeners: () => void
}
middleware
The actual Redux middleware. Add this to the Redux store via the configureStore.middleware option.
Since the listener middleware can receive "add" and "remove" actions containing functions, this should normally be added as the first middleware in the chain so that it is before the serializability check middleware.
const store = configureStore({
reducer: {
todos: todosReducer,
},
// Add the listener middleware to the store.
// NOTE: Since this can receive actions with functions inside,
// it should go before the serializability check middleware
middleware: (getDefaultMiddleware) =>
getDefaultMiddleware().prepend(listenerMiddleware.middleware),
})
startListening
Adds a new listener entry to the middleware. Typically used to "statically" add new listeners during application setup.
const startListening = (options: AddListenerOptions) => UnsubscribeListener
interface AddListenerOptions {
// Four options for deciding when the listener will run:
// 1) Exact action type string match
type?: string
// 2) Exact action type match based on the RTK action creator
actionCreator?: ActionCreator
// 3) Match one of many actions using an RTK matcher
matcher?: Matcher
// 4) Return true based on a combination of action + state
predicate?: ListenerPredicate
// The actual callback to run when the action is matched
effect: (action: Action, listenerApi: ListenerApi) => void | Promise<void>
}
type ListenerPredicate<Action extends ReduxAction, State> = (
action: Action,
currentState?: State,
originalState?: State,
) => boolean
type UnsubscribeListener = (
unsubscribeOptions?: UnsubscribeListenerOptions,
) => void
interface UnsubscribeListenerOptions {
cancelActive?: true
}
You must provide exactly one of the four options for deciding when the listener will run: type, actionCreator, matcher, or predicate. Every time an action is dispatched, each listener will be checked to see if it should run based on the current action vs the comparison option provided.
These are all acceptable:
// 1) Action type string
listenerMiddleware.startListening({ type: 'todos/todoAdded', effect })
// 2) RTK action creator
listenerMiddleware.startListening({ actionCreator: todoAdded, effect })
// 3) RTK matcher function
listenerMiddleware.startListening({
matcher: isAnyOf(todoAdded, todoToggled),
effect,
})
// 4) Listener predicate
listenerMiddleware.startListening({
predicate: (action, currentState, previousState) => {
// return true when the listener should run
},
effect,
})
Note that the predicate option actually allows matching solely against state-related checks, such as "did state.x change" or "the current value of state.x matches some criteria", regardless of the actual action.
The "matcher" utility functions included in RTK are acceptable as either the matcher or predicate option.
The return value is an unsubscribe() callback that will remove this listener. By default, unsubscribing will not cancel any active instances of the listener. However, you may also pass in {cancelActive: true} to cancel running instances.
If you try to add a listener entry but another entry with this exact function reference already exists, no new entry will be added, and the existing unsubscribe method will be returned.
The effect callback will receive the current action as its first argument, as well as a "listener API" object similar to the "thunk API" object in createAsyncThunk.
All listener predicates and callbacks are checked after the root reducer has already processed the action and updated the state. The listenerApi.getOriginalState() method can be used to get the state value that existed before the action that triggered this listener was processed.
stopListening
Removes a given listener entry.
It accepts the same arguments as startListening(). It checks for an existing listener entry by comparing the function references of listener and the provided actionCreator/matcher/predicate function or type string.
By default, this does not cancel any active running instances. However, you may also pass in {cancelActive: true} to cancel running instances.
const stopListening = (
options: AddListenerOptions & UnsubscribeListenerOptions,
) => boolean
interface UnsubscribeListenerOptions {
cancelActive?: true
}
Returns true if the listener entry has been removed, or false if no subscription matching the input provided has been found.
// Examples:
// 1) Action type string
listenerMiddleware.stopListening({
type: 'todos/todoAdded',
listener,
cancelActive: true,
})
// 2) RTK action creator
listenerMiddleware.stopListening({ actionCreator: todoAdded, effect })
// 3) RTK matcher function
listenerMiddleware.stopListening({ matcher, effect, cancelActive: true })
// 4) Listener predicate
listenerMiddleware.stopListening({ predicate, effect })
clearListeners
Removes all current listener entries. It also cancels all active running instances of those listeners as well.
This is most likely useful for test scenarios where a single middleware or store instance might be used in multiple tests, as well as some app cleanup situations.
const clearListeners = () => void;
Action Creators
In addition to adding and removing listeners by directly calling methods on the listener instance, you can dynamically add and remove listeners at runtime by dispatching special "add" and "remove" actions. These are exported from the main RTK package as standard RTK-generated action creators.
addListener
A standard RTK action creator, imported from the package. Dispatching this action tells the middleware to dynamically add a new listener at runtime. It accepts exactly the same options as startListening()
Dispatching this action returns an unsubscribe() callback from dispatch.
// Per above, provide `predicate` or any of the other comparison options
const unsubscribe = store.dispatch(addListener({ predicate, effect }))
removeListener
A standard RTK action creator, imported from the package. Dispatching this action tells the middleware to dynamically remove a listener at runtime. Accepts the same arguments as stopListening().
By default, this does not cancel any active running instances. However, you may also pass in {cancelActive: true} to cancel running instances.
Returns true if the listener entry has been removed, false if no subscription matching the input provided has been found.
const wasRemoved = store.dispatch(
removeListener({ predicate, effect, cancelActive: true }),
)
clearAllListeners
A standard RTK action creator, imported from the package. Dispatching this action tells the middleware to remove all current listener entries. It also cancels all active running instances of those listeners as well.
store.dispatch(clearAllListeners())
Listener API
The listenerApi object is the second argument to each listener callback. It contains several utility functions that may be called anywhere inside the listener's logic.
export interface ListenerEffectAPI<
State,
Dispatch extends ReduxDispatch<UnknownAction>,
ExtraArgument = unknown,
> extends MiddlewareAPI<Dispatch, State> {
// NOTE: MiddlewareAPI contains `dispatch` and `getState` already
/**
* Returns the store state as it existed when the action was originally dispatched, _before_ the reducers ran.
* This function can **only** be invoked **synchronously**, it throws error otherwise.
*/
getOriginalState: () => State
/**
* Removes the listener entry from the middleware and prevent future instances of the listener from running.
* It does **not** cancel any active instances.
*/
unsubscribe(): void
/**
* It will subscribe a listener if it was previously removed, noop otherwise.
*/
subscribe(): void
/**
* Returns a promise that resolves when the input predicate returns `true` or
* rejects if the listener has been cancelled or is completed.
*
* The return value is `true` if the predicate succeeds or `false` if a timeout is provided and expires first.
*/
condition: ConditionFunction<State>
/**
* Returns a promise that resolves when the input predicate returns `true` or
* rejects if the listener has been cancelled or is completed.
*
* The return value is the `[action, currentState, previousState]` combination that the predicate saw as arguments.
*
* The promise resolves to null if a timeout is provided and expires first.
*/
take: TakePattern<State>
/**
* Cancels all other running instances of this same listener except for the one that made this call.
*/
cancelActiveListeners: () => void
/**
* Cancels the listener instance that made this call.
*/
cancel: () => void
/**
* Throws a `TaskAbortError` if this listener has been cancelled
*/
throwIfCancelled: () => void
/**
* An abort signal whose `aborted` property is set to `true`
* if the listener execution is either aborted or completed.
* @see https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal
*/
signal: AbortSignal
/**
* Returns a promise that resolves after `timeoutMs` or
* rejects if the listener has been cancelled or is completed.
*/
delay(timeoutMs: number): Promise<void>
/**
* Queues in the next microtask the execution of a task.
*/
fork<T>(executor: ForkedTaskExecutor<T>): ForkedTask<T>
/**
* Returns a promise that resolves when `waitFor` resolves or
* rejects if the listener has been cancelled or is completed.
* @param promise
*/
pause<M>(promise: Promise<M>): Promise<M>
extra: ExtraArgument
}
These can be divided into several categories.
Store Interaction Methods
dispatch: Dispatch: the standardstore.dispatchmethodgetState: () => State: the standardstore.getStatemethodgetOriginalState: () => State: returns the store state as it existed when the action was originally dispatched, before the reducers ran. (Note: this method can only be called synchronously, during the initial dispatch call stack, to avoid memory leaks. Calling it asynchronously will throw an error.)extra: unknown: the "extra argument" that was provided as part of the middleware setup, if any
dispatch and getState are exactly the same as in a thunk. getOriginalState can be used to compare the original state before the listener was started.
extra can be used to inject a value such as an API service layer into the middleware at creation time, and is accessible here.
Listener Subscription Management
unsubscribe: () => void: removes the listener entry from the middleware, and prevent future instances of the listener from running. (This does not cancel any active instances.)subscribe: () => void: will re-subscribe the listener entry if it was previously removed, or no-op if currently subscribedcancelActiveListeners: () => void: cancels all other running instances of this same listener except for the one that made this call. (The cancellation will only have a meaningful effect if the other instances are paused using one of the cancellation-aware APIs liketake/cancel/pause/delay- see "Cancelation and Task Management" in the "Usage" section for more details)cancel: () => void: cancels the instance of this listener that made this call.throwIfCancelled: () => void: throws aTaskAbortErrorif the current listener instance was cancelled.signal: AbortSignal: AnAbortSignalwhoseabortedproperty will be set totrueif the listener execution is aborted or completed.
Dynamically unsubscribing and re-subscribing this listener allows for more complex async workflows, such as avoiding duplicate running instances by calling listenerApi.unsubscribe() at the start of a listener, or calling listenerApi.cancelActiveListeners() to ensure that only the most recent instance is allowed to complete.
Conditional Workflow Execution
take: (predicate: ListenerPredicate, timeout?: number) => Promise<[Action, State, State] | null>: returns a promise that will resolve when thepredicatereturnstrue. The return value is the[action, currentState, previousState]combination that the predicate saw as arguments. If atimeoutis provided and expires first, the promise resolves tonull.condition: (predicate: ListenerPredicate, timeout?: number) => Promise<boolean>: Similar totake, but resolves totrueif the predicate succeeds, andfalseif atimeoutis provided and expires first. This allows async logic to pause and wait for some condition to occur before continuing. See "Writing Async Workflows" below for details on usage.delay: (timeoutMs: number) => Promise<void>: returns a cancellation-aware promise that resolves after the timeout, or rejects if cancelled before the expirationpause: (promise: Promise<T>) => Promise<T>: accepts any promise, and returns a cancellation-aware promise that either resolves with the argument promise or rejects if cancelled before the resolution
These methods provide the ability to write conditional logic based on future dispatched actions and state changes. Both also accept an optional timeout in milliseconds.
take resolves to a [action, currentState, previousState] tuple or null if it timed out, whereas condition resolves to true if it succeeded or false if timed out.
take is meant for "wait for an action and get its contents", while condition is meant for checks like if (await condition(predicate)).
Both these methods are cancellation-aware, and will throw a TaskAbortError if the listener instance is cancelled while paused.
Note that both take and condition will only resolve after the next action has been dispatched. They do not resolve immediately even if their predicate would return true for the current state.
Child Tasks
fork: (executor: (forkApi: ForkApi) => T | Promise<T>) => ForkedTask<T>: Launches a "child task" that may be used to accomplish additional work. Accepts any sync or async function as its argument, and returns a{result, cancel}object that can be used to check the final status and return value of the child task, or cancel it while in-progress.
Child tasks can be launched, and waited on to collect their return values. The provided executor function will be called asynchronously with a forkApi object containing {pause, delay, signal}, allowing it to pause or check cancellation status. It can also make use of the listenerApi from the listener's scope.
An example of this might be a listener that forks a child task containing an infinite loop that listens for events from a server. The parent then uses listenerApi.condition() to wait for a "stop" action, and cancels the child task.
The task and result types are:
interface ForkedTaskAPI {
pause<W>(waitFor: Promise<W>): Promise<W>
delay(timeoutMs: number): Promise<void>
signal: AbortSignal
}
export type TaskResolved<T> = {
readonly status: 'ok'
readonly value: T
}
export type TaskRejected = {
readonly status: 'rejected'
readonly error: unknown
}
export type TaskCancelled = {
readonly status: 'cancelled'
readonly error: TaskAbortError
}
export type TaskResult<Value> =
| TaskResolved<Value>
| TaskRejected
| TaskCancelled
export interface ForkedTask<T> {
result: Promise<TaskResult<T>>
cancel(): void
}
TypeScript Usage
The middleware code is fully TS-typed. However, the startListening and addListener functions do not know what the store's RootState type looks like by default, so getState() will return unknown.
To fix this, the middleware provides types for defining "pre-typed" versions of those methods, similar to the pattern used for defing pre-typed React-Redux hooks. We specifically recommend creating the middleware instance in a separate file from the actual configureStore() call:
// listenerMiddleware.ts
import { createListenerMiddleware, addListener } from '@reduxjs/toolkit'
import type { RootState, AppDispatch } from './store'
declare type ExtraArgument = {foo: string};
export const listenerMiddleware = createListenerMiddleware()
export const startAppListening = listenerMiddleware.startListening.withTypes<
RootState,
AppDispatch,
ExtraArgument
>()
export const addAppListener = addListener.withTypes<RootState, AppDispatch>()
Then import and use those pre-typed methods in your components.
Usage Guide
Overall Purpose
This middleware lets you run additional logic when some action is dispatched, as a lighter-weight alternative to middleware like sagas and observables that have both a heavy runtime bundle cost and a large conceptual overhead.
This middleware is not intended to handle all possible use cases. Like thunks, it provides you with a basic set of primitives (including access to dispatch and getState), and gives you freedom to write any sync or async logic you want. This is both a strength (you can do anything!) and a weakness (you can do anything, with no guard rails!).
The middleware includes several async workflow primitives that are sufficient to write equivalents to many Redux-Saga effects operators like takeLatest, takeLeading, and debounce, although none of those methods are directly included. (See the listener middleware tests file for examples of how to write code equivalent to those effects.)
Standard Usage Patterns
The most common expected usage is "run some logic after a given action was dispatched". For example, you could set up a simple analytics tracker by looking for certain actions and sending extracted data to the server, including pulling user details from the store:
listenerMiddleware.startListening({
matcher: isAnyOf(action1, action2, action3),
effect: (action, listenerApi) => {
const user = selectUserDetails(listenerApi.getState())
const { specialData } = action.meta
analyticsApi.trackUsage(action.type, user, specialData)
},
})
However, the predicate option also allows triggering logic when some state value has changed, or when the state matches a particular condition:
listenerMiddleware.startListening({
predicate: (action, currentState, previousState) => {
// Trigger logic whenever this field changes
return currentState.counter.value !== previousState.counter.value
},
effect,
})
listenerMiddleware.startListening({
predicate: (action, currentState, previousState) => {
// Trigger logic after every action if this condition is true
return currentState.counter.value > 3
},
effect,
})
You could also implement a generic API fetching capability, where the UI dispatches a plain action describing the type of resource to be requested, and the middleware automatically fetches it and dispatches a result action:
listenerMiddleware.startListening({
actionCreator: resourceRequested,
effect: async (action, listenerApi) => {
const { name, args } = action.payload
listenerApi.dispatch(resourceLoading())
const res = await serverApi.fetch(`/api/${name}`, ...args)
listenerApi.dispatch(resourceLoaded(res.data))
},
})
(That said, we would recommend use of RTK Query for any meaningful data fetching behavior - this is primarily an example of what you could do in a listener.)
The listenerApi.unsubscribe method may be used at any time, and will remove the listener from handling any future actions. As an example, you could create a one-shot listener by unconditionally calling unsubscribe() in the body - the effect callback would run the first time the relevant action is seen, then immediately unsubscribe and never run again. (The middleware actually uses this technique internally for the take/condition methods)
Writing Async Workflows with Conditions
One of the great strengths of both sagas and observables is their support for complex async workflows, including stopping and starting behavior based on specific dispatched actions. However, the weakness is that both require mastering a complex API with many unique operators (effects methods like call() and fork() for sagas, RxJS operators for observables), and both add a significant amount to application bundle size.
While the listener middleware is not meant to fully replace sagas or observables, it does provide a carefully chosen set of APIs to implement long-running async workflows as well.
Listeners can use the condition and take methods in listenerApi to wait until some action is dispatched or state check is met. The condition method is directly inspired by the condition function in Temporal.io's workflow API (credit to @swyx for the suggestion!), and take is inspired by the take effect from Redux-Saga.
The signatures are:
type ConditionFunction<Action extends ReduxAction, State> = (
predicate: ListenerPredicate<Action, State> | (() => boolean),
timeout?: number,
) => Promise<boolean>
type TakeFunction<Action extends ReduxAction, State> = (
predicate: ListenerPredicate<Action, State> | (() => boolean),
timeout?: number,
) => Promise<[Action, State, State] | null>
You can use await condition(somePredicate) as a way to pause execution of your listener callback until some criteria is met.
The predicate will be called after every action is processed by the reducers, and should return true when the condition should resolve. (It is effectively a one-shot listener itself.) If a timeout number (in ms) is provided, the promise will resolve true if the predicate returns first, or false if the timeout expires. This allows you to write comparisons like if (await condition(predicate, timeout)).
This should enable writing longer-running workflows with more complex async logic, such as the "cancellable counter" example from Redux-Saga.
An example of condition usage, from the test suite:
test('condition method resolves promise when there is a timeout', async () => {
let finalCount = 0
let listenerStarted = false
listenerMiddleware.startListening({
predicate: (action, currentState: CounterState) => {
return increment.match(action) && currentState.value === 0
},
effect: async (action, listenerApi) => {
listenerStarted = true
// Wait for either the counter to hit 3, or 50ms to elapse
const result = await listenerApi.condition(
(action, currentState: CounterState) => {
return currentState.value === 3
},
50,
)
// In this test, we expect the timeout to happen first
expect(result).toBe(false)
// Save the state for comparison outside the listener
const latestState = listenerApi.getState()
finalCount = latestState.value
},
})
store.dispatch(increment())
// The listener should have started right away
expect(listenerStarted).toBe(true)
store.dispatch(increment())
// If we wait 150ms, the condition timeout will expire first
await delay(150)
// Update the state one more time to confirm the listener isn't checking it
store.dispatch(increment())
// Handled the state update before the delay, but not after
expect(finalCount).toBe(2)
})
Cancellation and Task Management
The listener middleware supports cancellation of running listener instances, take/condition/pause/delay functions, and "child tasks", with an implementation based on AbortController.
The listenerApi.pause/delay() functions provide a cancellation-aware way to have the current listener sleep. pause() accepts a promise, while delay accepts a timeout value. If the listener is cancelled while waiting, a TaskAbortError will be thrown. In addition, both take and condition support cancellation interruption as well.
listenerApi.cancelActiveListeners() will cancel other existing instances that are running, while listenerApi.cancel() can be used to cancel the current instance (which may be useful from a fork, which could be deeply nested and not able to directly throw a promise to break out of the effect execution). listenerAPi.throwIfCancelled() can also be useful to bail out of workflows in case cancellation happened while the effect was doing other work.
listenerApi.fork() can used to launch "child tasks" that can do additional work. These can be waited on to collect their results. An example of this might look like:
listenerMiddleware.startListening({
actionCreator: increment,
effect: async (action, listenerApi) => {
// Spawn a child task and start it immediately
const task = listenerApi.fork(async (forkApi) => {
// Artificially wait a bit inside the child
await forkApi.delay(5)
// Complete the child by returning a value
return 42
})
const result = await task.result
// Unwrap the child result in the listener
if (result.status === 'ok') {
// Logs the `42` result value that was returned
console.log('Child succeeded: ', result.value)
}
},
})
Complex Async Workflows
The provided async workflow primitives (cancelActiveListeners, cancel, unsubscribe, subscribe, take, condition, pause, delay) can be used to implement behavior that is equivalent to many of the more complex async workflow capabilities found in the Redux-Saga library. This includes effects such as throttle, debounce, takeLatest, takeLeading, and fork/join. Some examples from the test suite:
test('debounce / takeLatest', async () => {
// Repeated calls cancel previous ones, no work performed
// until the specified delay elapses without another call
// NOTE: This is also basically identical to `takeLatest`.
// Ref: https://redux-saga.js.org/docs/api#debouncems-pattern-saga-args
// Ref: https://redux-saga.js.org/docs/api#takelatestpattern-saga-args
listenerMiddleware.startListening({
actionCreator: increment,
effect: async (action, listenerApi) => {
// Cancel any in-progress instances of this listener
listenerApi.cancelActiveListeners()
// Delay before starting actual work
await listenerApi.delay(15)
// do work here
},
})
}
test('takeLeading', async () => {
// Starts listener on first action, ignores others until task completes
// Ref: https://redux-saga.js.org/docs/api#takeleadingpattern-saga-args
listenerMiddleware.startListening({
actionCreator: increment,
effect: async (action, listenerApi) => {
listenerCalls++
// Stop listening for this action
listenerApi.unsubscribe()
// Pretend we're doing expensive work
// Re-enable the listener
listenerApi.subscribe()
},
})
})
test('cancelled', async () => {
// cancelled allows checking if the current task was cancelled
// Ref: https://redux-saga.js.org/docs/api#cancelled
let canceledAndCaught = false
let canceledCheck = false
// Example of canceling prior instances conditionally and checking cancellation
listenerMiddleware.startListening({
matcher: isAnyOf(increment, decrement, incrementByAmount),
effect: async (action, listenerApi) => {
if (increment.match(action)) {
// Have this branch wait around to be cancelled by the other
try {
await listenerApi.delay(10)
} catch (err) {
// Can check cancellation based on the exception and its reason
if (err instanceof TaskAbortError) {
canceledAndCaught = true
}
}
} else if (incrementByAmount.match(action)) {
// do a non-cancellation-aware wait
await delay(15)
if (listenerApi.signal.aborted) {
canceledCheck = true
}
} else if (decrement.match(action)) {
listenerApi.cancelActiveListeners()
}
},
})
})
As a more practical example: this saga-based "long polling" loop repeatedly asks the server for a message and then processes each response. The child loop is started on demand when a "start polling" action is dispatched, and the loop is cancelled when a "stop polling" action is dispatched.
That approach can be implemented via the listener middleware:
// Track how many times each message was processed by the loop
const receivedMessages = {
a: 0,
b: 0,
c: 0,
}
const eventPollingStarted = createAction('serverPolling/started')
const eventPollingStopped = createAction('serverPolling/stopped')
listenerMiddleware.startListening({
actionCreator: eventPollingStarted,
effect: async (action, listenerApi) => {
// Only allow one instance of this listener to run at a time
listenerApi.unsubscribe()
// Start a child job that will infinitely loop receiving messages
const pollingTask = listenerApi.fork(async (forkApi) => {
try {
while (true) {
// Cancellation-aware pause for a new server message
const serverEvent = await forkApi.pause(pollForEvent())
// Process the message. In this case, just count the times we've seen this message.
if (serverEvent.type in receivedMessages) {
receivedMessages[
serverEvent.type as keyof typeof receivedMessages
]++
}
}
} catch (err) {
if (err instanceof TaskAbortError) {
// could do something here to track that the task was cancelled
}
}
})
// Wait for the "stop polling" action
await listenerApi.condition(eventPollingStopped.match)
pollingTask.cancel()
},
})
Adding Listeners Inside Components
Listeners can be added at runtime via dispatch(addListener()). This means that you can add listeners anywhere you have access to dispatch, and that includes React components.
Since dispatching addListener returns an unsubscribe callback, this naturally maps to the behavior of React useEffect hooks, which let you return a cleanup function. You can add a listener in an effect, and remove the listener when the hook is cleaned up.
The basic pattern might look like:
useEffect(() => {
// Could also just `return dispatch(addListener())` directly, but showing this
// as a separate variable to be clear on what's happening
const unsubscribe = dispatch(
addListener({
actionCreator: todoAdded,
effect: (action, listenerApi) => {
// do some useful logic here
},
}),
)
return unsubscribe
}, [])
While this pattern is possible, we do not necessarily recommend doing this! The React and Redux communities have always tried to emphasize basing behavior on state as much as possible. Having React components directly tie into the Redux action dispatch pipeline could potentialy lead to codebases that are more difficult to maintain.
At the same time, this is a valid technique, both in terms of API behavior and potential use cases. It's been common to lazy-load sagas as part of a code-split app, and that has often required some complex additional setup work to "inject" sagas. In contrast, dispatch(addListener()) fits naturally into a React component's lifecycle.
So, while we're not specifically encouraging use of this pattern, it's worth documenting here so that users are aware of it as a possibility.
Organizing Listeners in Files
As a starting point, it's best to create the listener middleware in a separate file, such as app/listenerMiddleware.ts, rather than in the same file as the store. This avoids any potential circular import problems from other files trying to import middleware.addListener.
From there, so far we've come up with three different ways to organize listener functions and setup.
First, you can import effect callbacks from slice files into the middleware file, and add the listeners:
import { action1, listener1 } from '../features/feature1/feature1Slice'
import { action2, listener2 } from '../features/feature2/feature2Slice'
listenerMiddleware.startListening({ actionCreator: action1, effect: listener1 })
listenerMiddleware.startListening({ actionCreator: action2, effect: listener2 })
This is probably the simplest option, and mirrors how the store setup pulls together all the slice reducers to create the app.
The second option is the opposite: have the slice files import the middleware and directly add their listeners:
import { listenerMiddleware } from '../../app/listenerMiddleware'
const feature1Slice = createSlice(/* */)
const { action1 } = feature1Slice.actions
export default feature1Slice.reducer
listenerMiddleware.startListening({
actionCreator: action1,
effect: () => {},
})
This keeps all the logic in the slice, although it does lock the setup into a single middleware instance.
The third option is to create a setup function in the slice, but let the listener file call that on startup:
import type { AppStartListening } from '../../app/listenerMiddleware'
const feature1Slice = createSlice(/* */)
const { action1 } = feature1Slice.actions
export default feature1Slice.reducer
export const addFeature1Listeners = (startListening: AppStartListening) => {
startListening({
actionCreator: action1,
effect: () => {},
})
}
import { addFeature1Listeners } from '../features/feature1/feature1Slice'
addFeature1Listeners(listenerMiddleware.startListening)
Feel free to use whichever of these approaches works best in your app.