New experimental "action listener middleware" package available

[markerikson]

Update, 2022-02-08: Listener Middleware Released in RTK 1.8!

The listener middleware is now available in RTK 1.8! Thanks to everyone who helped try out the alpha versions and gave us feedback.

Previously

This discussion is for feedback and API design of our experimental "listener middleware" package:

https://www.npmjs.com/package/@rtk-incubator/action-listener-middleware

npm i @rtk-incubator/action-listener-middleware

yarn add @rtk-incubator/action-listener-middleware

Status

As of 2022-02-12, we've published v0.8.0 of the standalone middleware package. It contains major breaking changes due to API renames and return value changes, but the API should now be finished.

The plan is to release the middleware as part of RTK 1.8:

• RTK 1.8 and 1.9 planning #2003

Don't have an ETA for that release yet, but hopefully fairly soon.

Overview

I did a livestream where I described the purpose of this middleware and dug into the source code:

• https://youtu.be/D5WOry6gw9c

Pasting the actual description from the README:

This package provides a callback-based Redux middleware that we plan to include in Redux Toolkit directly in the next feature release. We're publishing it as a standalone package to allow users to try it out separately and give us feedback on its API design.

This middleware lets you define "listener" entries containing "effect" callbacks that will run in response to specific actions being dispatched. 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.

Basic Usage

import { configureStore } from '@reduxjs/toolkit'
import { createListenerMiddleware } from '@rtk-incubator/action-listener-middleware'

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, or cancel previous
      listenerApi.dispatch(todoAdded('Buy pet food'))
      listenerApi.unsubscribe()
    }
  },
})

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),
})

Motivation

The Redux community has settled around three primary side effects libraries over time:

• Thunks use basic functions passed to dispatch. They let users run arbitrary logic, including dispatching actions and getting state. These are mostly used for basic AJAX requests and logic that needs to read from state before dispatching actions
• Sagas use generator functions and a custom set of "effects" APIs, which are then executed by a middleware. Sagas let users write powerful async logic and workflows that can respond to any dispatched action, including "background thread"-type behavior like infinite loops and cancelation.
• Observables use RxJS observable operators. Observables form pipelines that do arbitrary processing similar to sagas, but with a more functional API style.

All three of those have strengths and weaknesses:

• Thunks are simple to use, but can only run imperative code and have no way to respond to dispatched actions
• Sagas are extremely powerful, but require learning generator functions and the specifics of redux-saga's effects API, and are overkill for many simpler use cases
• Observables are also powerful, but RxJS is its own complex API to learn and they can be hard to debug

If you need to run some code in response to a specific action being dispatched, you could write a custom middleware:

const myMiddleware = (storeAPI) => (next) => (action) => {
  if (action.type === 'some/specificAction') {
    console.log('Do something useful here')
  }

  return next(action)
}

However, it would be nice to have a more structured API to help abstract this process.

The createListenerMiddleware API provides that structure.

For more background and debate over the use cases and API design, see the original discussion issue and PR:

• RTK issue #237: Add an action listener middleware
• RTK PR #547: yet another attempt at an action listener middleware
• RTK discussion #1648: New experimental "action listener middleware" package available

API Reference

createListenerMiddleware lets you add listeners by providing an "effect callback" containing additional logic, and a way to specify when that callback should run based on dispatched actions or state changes.

The middleware then gives you access to dispatch and getState for use in your effect callback's logic, 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.

createListenerMiddleware: (options?: CreateMiddlewareOptions) => ListenerMiddlewareInstance

Creates an instance of the middleware, which should then be added to the store via configureStore's middleware parameter.

Current options are:

• extra: an optional "extra argument" that will be injected into the listenerApi parameter of each listener. Equivalent to the "extra argument" in the Redux Thunk middleware.

• onError: an optional error handler that gets called with synchronous and async errors raised by listener and synchronous errors thrown by predicate.

createListenerMiddleware returns an object (similar to how createSlice does), with the following fields:

• middleware: the actual listener middleware instance. Add this to configureStore()
• startListening: adds a single listener entry to this specific middleware instance
• stopListening: removes a single listener entry from this specific middleware instance
• clearListeners: removes all listener entries from this specific middleware instance

startListening(options: AddListenerOptions) : Unsubscribe

Statically adds a new listener entry to the middleware.

The available options are:

type ListenerPredicate<Action extends AnyAction, State> = (
  action: Action,
  currentState?: State,
  originalState?: State
) => boolean

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>
}

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
startListening({ type: 'todos/todoAdded', listener })
// 2) RTK action creator
startListening({ actionCreator: todoAdded, listener })
// 3) RTK matcher function
startListening({ matcher: isAnyOf(todoAdded, todoToggled), listener })
// 4) Listener predicate
startListening({
  predicate: (action, currentState, previousState) => {
    // return true when the listener should run
  },
  listener,
})

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 predicates.

The return value is a standard unsubscribe() callback that will remove this listener. 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(options: AddListenerOptions): boolean

Removes a given listener. 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.

Returns true if the options.effect listener has been removed, or false if no subscription matching the input provided has been found.

// 1) Action type string
stopListening({ type: 'todos/todoAdded', listener })
// 2) RTK action creator
stopListening({ actionCreator: todoAdded, listener })
// 3) RTK matcher function
stopListening({ matcher, listener })
// 4) Listener predicate
stopListening({ predicate, listener })

clearListeners(): void

Removes all current listener entries. 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.

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, listener }))

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().

Returns true if the options.listener listener has been removed, false if no subscription matching the input provided has been found.

store.dispatch(removeListener({ predicate, listener }))

removeAllListeners

A standard RTK action creator, imported from the package. Dispatching this action tells the middleware to dynamically remove all listeners at runtime.

store.dispatch(removeAllListeners())

listenerApi

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. These can be divided into several categories:

Store Interaction Methods

• dispatch: Dispatch: the standard store.dispatch method
• getState: () => State: the standard store.getState method
• getOriginalState: () => 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.)

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.

Middleware Options

• extra: unknown: the "extra argument" that was provided as part of the middleware setup, if any

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: will remove the listener from the middleware
• subscribe: () => void: will re-subscribe the listener if it was previously removed, or no-op if currently subscribed
• cancelActiveListeners: () => void: cancels all other running instances of this same listener except for the one that made this call. (The cancelation will only have a meaningful effect if the other instances are paused using one of the cancelation-aware APIs like take/cancel/pause/delay - see "Cancelation and Task Management" in the "Usage" section for more details)
• signal: AbortSignal: An AbortSignal whose aborted property will be set to true if 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 the predicate returns true. The return value is the [action, currentState, previousState] combination that the predicate saw as arguments. If a timeout is provided and expires first, the promise resolves to null.
• condition: (predicate: ListenerPredicate, timeout?: number) => Promise<boolean>: Similar to take, but resolves to true if the predicate succeeds, and false if a timeout is 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 cancelation-aware promise that resolves after the timeout, or rejects if canceled before the expiration
• pause: (promise: Promise<T>) => Promise<T>: accepts any promise, and returns a cancelation-aware promise that either resolves with the argument promise or rejects if canceled 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 cancelation-aware, and will throw a TaskAbortError if the listener instance is canceled while paused.

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 with a forkApi object containing {pause, delay, signal}, allowing it to pause or check cancelation 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:

export 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
}

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!).

As of v0.5.0, the middleware does include several async workflow primitives that are sufficient to write equivalents to many Redux-Saga effects operators like takeLatest, takeLeading, and debounce.

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))
  },
})

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 - it would run the first time the relevant action is seen, and then immediately stop and not handle any future actions. (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 AnyAction, State> = (
  predicate: ListenerPredicate<Action, State> | (() => boolean),
  timeout?: number
) => Promise<boolean>

type TakeFunction<Action extends AnyAction, 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 before and after every action is processed, 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)).

This should enable writing longer-running workflows with more complex async logic, such as the "cancellable counter" example from Redux-Saga.

An example of 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)
})

Cancelation and Task Management

As of 0.5.0, the middleware now supports cancelation 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 cancelation-aware way to have the current listener sleep. pause() accepts a promise, while delay accepts a timeout value. If the listener is canceled while waiting, a TaskAbortError will be thrown. In addition, both take and condition support cancelation interruption as well.

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 an Ovalue
      return 42
    })

    const result = await task.result
    // Unwrap the child result in the listener
    if (result.status === 'ok') {
      console.log('Child succeeded: ', result.value)
    }
  },
})

Complex Async Workflows

The provided async workflow primitives (cancelActiveListeners, unsuscribe, subscribe, take, condition, pause, delay) can be used to implement 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:

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('canceled', async () => {
  // canceled allows checking if the current task was canceled
  // Ref: https://redux-saga.js.org/docs/api#cancelled

  let canceledAndCaught = false
  let canceledCheck = false

  // Example of canceling prior instances conditionally and checking cancelation
  listenerMiddleware.startListening({
    matcher: isAnyOf(increment, decrement, incrementByAmount),
    effect: async (action, listenerApi) => {
      if (increment.match(action)) {
        // Have this branch wait around to be canceled by the other
        try {
          await listenerApi.delay(10)
        } catch (err) {
          // Can check cancelation based on the exception and its reason
          if (err instanceof TaskAbortError) {
            canceledAndCaught = true
          }
        }
      } else if (incrementByAmount.match(action)) {
        // do a non-cancelation-aware wait
        await delay(15)
        if (listenerApi.signal.aborted) {
          canceledCheck = true
        }
      } else if (decrement.match(action)) {
        listenerApi.cancelActiveListeners()
      }
    },
  })
})

TypeScript Usage

The code is fully 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:

// listenerMiddleware.ts
import {
  createListenerMiddleware,
  addListener,
} from '@rtk-incubator/action-listener-middleware'
import type {
  TypedStartListening,
  TypedAddListener,
} from '@rtk-incubator/action-listener-middleware'

import type { RootState } from './store'

export const listenerMiddleware = createListenerMiddleware()

export const startAppListening =
  listenerMiddleware.startListening as TypedStartListening<RootState>
export const addAppListener = addListener as TypedAddListenern<RootState>

Then import and use those pre-typed versions in your components.

Feedback

Please provide feedback in RTK discussion #1648: "New experimental "action listener middleware" package".

[jvitela]

Hi,
I like the proposal. Would it be OK to dispatch new actions within this middleware? can the listener function be async?

For example:

listenerMiddleware.addListener(productAdded, async (action, listenerApi) => {
  const { product } = action.payload;
  const basket = await addProductToBasket(product); // recalculate shipping costs, promo discounts, etc;
  listenerApi.dispatch(basketUpdated(basket));
})

[markerikson]

@jvitela yes, that's exactly what this is meant for!

Much like thunks, the idea is that the middleware gives you dispatch and getState, and you get to write any arbitrary logic you want in the callback that makes use of those in any way.

[budarin]

We have been using similar functionality for a long time
https://github.com/budarin/redux-business-logic-middleare

[markerikson]

Action Listener Middleware Notes

I've just gone through all the prior issues and PR discussions about this middleware implementation and pulled out links and summaries of any points that looked interesting or worth further discussion. I'll do a follow-up pass on this list tomorrow and summarize the summaries into a list of bullet points that I think we ought to nail down.

Issue #237

• Add an action listener callback middleware #237 (comment)

There are essentially two schools of thought for working with side effects with redux.

The first approach is to put the side effects in the actions -- e.g. instead of dispatching a simple value, dispatch a promise, or a function that calls side effects. Middleware like redux-promise and redux-thunk intercept these non-value actions and run them.

The second approach is to put the side effects directly into the middleware -- the actions are always simple values, but the middleware listens to these actions, and can run side effects in response to them. This is the approach used by redux-saga and redux-loop; it's also how logging and metrics-reporting middleware work.

I prefer the second approach because it encourages you to keep the "how" with the state, and the "what" with the UI. However, the tools associated with this approach, particularly redux-saga, tend to have a pretty steep learning curve. The approach I'm using here is less expressive, but much closer to the complexity of redux-thunk.

• Other Redux abstractions:

  • Easy-Peasy listeners: https://easy-peasy.vercel.app/docs/api/listeners.html
  • Kea: https://kea.js.org/docs/api/logic#logiclisteners
  • Rematch: https://rematch.github.io/rematch/#/api-reference/api?id=effects

• Add an action listener callback middleware #237 (comment)

  • centralized middleware setup vs in createSlice?

• Me: Add an action listener callback middleware #237 (comment)

  • multiple handlers per action
  • add/remove handlers at runtime by dispatching actions
  • run reducers before listeners
  • pass in "store/thunk API"

• Add an action listener callback middleware #237 (comment)

  • keeping logic in slices is more "ducksy"
  • dynamic subscriptions leads to async logic everywhere
  • unsubscribe: by cb reference, or ID, or... ?

• Add an action listener callback middleware #237 (comment)

  • run listener after reducer
  • should be a default middleware
  • standalone package, as an RTK dep

• Add an action listener callback middleware #237 (comment)

  • have a createListener API, then add them
  • example can't handle adding listeners at runtime or multiple actions

• Add an action listener callback middleware #237 (comment)

  • Lenz doesn't like dynamically adding/removing listeners - too easy to abuse this, especially in components
  • "can couple React components to store logic, essentially reducing Redux to a CQRS stream, and brings in problems like unsubscribing on unmountand memory leaks"
  • Add React-Redux as an optional dep and have a custom hook to help with handling listeners?

• Me: Add an action listener callback middleware #237 (comment)

  • pass both (action, state) to the matching callback?

• Me: Add an action listener callback middleware #237 (comment)

  • "Predicate API": type ActionListenerPredicate = (state: State, action: Action) => boolean

• Add an action listener callback middleware #237 (comment)

  • https://www.npmjs.com/package/redux-when

• Add an action listener callback middleware #237 (comment)

  • Don't like reliance on getDefaultMiddleware to initialize, but could live with it

• Add an action listener callback middleware #237 (comment)

  • would like a takeLatest/takeLeading option

• Add an action listener callback middleware #237 (comment)

  • no idea how takeLatest would work for functions

• Add an action listener callback middleware #237 (comment)

  • https://github.com/Jazzmanpw/yam
  • only one action dispatched per handler
  • effects called after state change, but option to compare prev and current state

PR #547

• yet another attempt at actionListenerMiddleware #547 (comment)
  • Forward addListener action onwards for observability? any real value here?
  • could dispatch a "started listening" action with an ID, but also not clear how useful it is.
• yet another attempt at actionListenerMiddleware #547 (comment)
  • Does TS know that this middleware returns an unsubscribe function?
• yet another attempt at actionListenerMiddleware #547 (comment)
  • good way to handle unsubscribing even if cb references changed?
• yet another attempt at actionListenerMiddleware #547 (comment)
  • default to "before" or "after" for listeners?
• yet another attempt at actionListenerMiddleware #547 (comment)
  • have a "once" option? is unsubscribe enough?
• yet another attempt at actionListenerMiddleware #547 (comment)
  • Is stopPropagation actually a good idea?
• yet another attempt at actionListenerMiddleware #547 (comment)
  • "1-M action type to listeners relationship feels backwards"
  • "Would like to have a listener act more like a reducer where the action is used to conditionally run logic"
• yet another attempt at actionListenerMiddleware #547 (comment)
  • scenarios:
    • listener creates WS after action, listens for message, tears down handler
    • error reporting for .rejected cases
    • "cancellable counter": click increment, countdown starts, increment when it hits 0, if button clicked cancel countdown w/ no increment
    • see other saga examples: https://github.com/redux-saga/redux-saga/tree/master/examples/cancellable-counter
• yet another attempt at actionListenerMiddleware #547 (comment)
  • analysis of other libs:
    • Easy-Peasy: lets you listen for regular action types, thunks (at various stages: start, success, fail), and lists/combinations of these. Listening for multiple targets probably cuts down on repeated code in some cases.
    • Rematch: gives you dispatch
    • Kea: has "breakpoints" for debouncing
    • summary of several other standalone middleware
• yet another attempt at actionListenerMiddleware #547 (comment)
  • concerns with stopPropagation, especially because we don't know what order listeners run in
  • some alternate API proposals, including a "pre-state/post-state" useEffect-type split
• yet another attempt at actionListenerMiddleware #547 (comment)
  • split stopPropagation into its own separate middleware?
• yet another attempt at actionListenerMiddleware #547 (comment)
  • do we need getPreviousState?
  • how would you listen for multiple actions in a sequence?
• yet another attempt at actionListenerMiddleware #547 (comment)
  • add subscribe to listenerApi ?
• yet another attempt at actionListenerMiddleware #547 (comment)
  • add extraArgument support?
  • can listeners be given an "extra argument" as part of subscription?
  • can we pass in listeners on middleware creation?
• yet another attempt at actionListenerMiddleware #547 (comment)
  • what does "action listener" mean anyway?
  • can do wild-card style action matches with type guards (birth of RTK's "matchers")
  • extra or context would be a good idea
• yet another attempt at actionListenerMiddleware #547 (comment)
  • Impl should be a Set, not a Map
  • Added createListener()
  • Bulk add listeners on startup
• yet another attempt at actionListenerMiddleware #547 (comment)
  • What if a listener throws an error? would currently act like a stopImmediatePropagation()
  • suggest having a try/catch around every listener call, and then notify on error somehow

Other discussions

• Having to cast dispatch to support dispatching thunks is a pain. Don't want to import global thunk type override, but could default its Dispatch type to ThunkDispatch

Other thoughts

• We could simplify the internals by converting all of the items into matchers. Give a string type, just make a matcher out of it
• Could also generate a UUID for every listener, and do Map<ListenerId, ListenerEntry>, and then we can always unsubscribe regardless of callback references or use of a matcher arg
• No good way to do comparisons over time / multiple actions over time

[landisdesign]

How would you know when one of those listeners is done so you could clear it?

It seems the listener would need to be wrapped, somehow, which could get tricky. Making everything async just in case seems expensive.

[markerikson]

Hmm. Maybe something with AbortController somehow? This seems like it would actually be the right use case for that sort of thing.

I don't wanna get too bogged down trying to solve all potential use cases - after all I did explicitly say that "this isn't meant to completely replace sagas", etc. But if there's a couple primitives we could add that would make stuff like that possible, it's worth brainstorming now.

Oh. Y'know, it just occurred to me that this also relates to the error-handling logic that @FaberVitale just added. If a listener is async, we won't catch any potential errors.

[landisdesign]

Yeah. This feels pretty rabbit-hole-ish. It seems like the solution is down the road of wrapping listeners/predicates in Promises that can update run status and receive errors/rejections, and letting the wrappers run asynchronously. Maybe there's an easy way to encapsulate that with a wrapFunction(fn, onComplete, onError) interface... but it is adding a bunch of complexity, it seems. It still begs the question of how to actually stop a listener. Someone has to listen for the signal.

[landisdesign]

If a listener is async, we won't catch any potential errors

This feels like a standard async challenge, even for someone doing a simple fetch in a component. 🤷

[landisdesign]

Yeah, to @phryneas's point below, it may be as simple as adding

const subscribe = () => listenerMap.set(id, entry);

and calling it a day.

[FaberVitale]

stopPropagation

Seldom a react developer needs to worry about the order of scheduled useEffect, saga or epic:
he can be confident that the control flow is contained inside that single listener he subscribed to an event.

stopPropagation introduces the following complications:

1. Is the listener going to be run? Isn't if (!condition) { return; } inside a listener more readable and maintainable?
2. Is the listener I'm developing going to be attached before or after a stopPropagation listener?

---

Conclusion

stopPropagation does not bring substantial benefits to offset the complications it adds.

[markerikson]

Agreed, and I just removed it from the API in version 0.2.0

[markerikson]

Changelog

v0.2.0

I implemented most of the fixes I had listed in #1648 (reply in thread) , and I updated the README with much more extensive usage information and pasted all that content into the main post up top.

https://www.npmjs.com/package/@rtk-incubator/action-listener-middleware

npm i @rtk-incubator/action-listener-middleware@0.2.0

yarn add @rtk-incubator/action-listener-middleware@0.2.0

Changes per #1706 :

• Removes the type: "module" line from the listener middleware package.json file to avoid unwanted ESM handling
• Sets up Jest+TS testing
• Copies the test file from yet another attempt at actionListenerMiddleware #547
• Adds additional tests for the matcher and actionPredicate listener overloads
• Rewrites the internals to track all listeners in a Map<idString, ListenerEntry>
• Removes the stopPropagation method
• Renames the When values to 'beforeReducer' and 'afterReducer', and adds an additional 'both' value
• Wraps listeners in a try/catch to handle errors
• Hacks in runtime support for an extra value ala thunks, but without good typing
• Adds a getOriginalState method that captures the state before the action was dispatched
• Tries and fails to get thunk-typed dispatching working
• Adds a condition method to enable long-running async workflows, based on https://docs.temporal.io/docs/typescript/workflows/#condition

I did realize that the addListener action creator now has its arguments and types badly out of sync with middleware.addListener - you can add based on action types and action creators, but not matchers or predicates. I briefly tried to extract a createListenerEntry function that would contain the setup logic so it could be used in both places, but it wasn't working out and I want to get these changes live.

The really big news here is that the middleware now has support for longer-running async workflows via the condition method. It's based off of https://docs.temporal.io/docs/typescript/workflows/#condition and was suggested by @swyx . Loosely, you can now do:

const checkSucceeded = await condition(listenerPredicate, timeout?);

Returns true if the condition matched, false if the timeout happens.

That should allow behavior like "sleep until some other action is dispatched".

With that in place, I think this is now really a viable lightweight alternative to sagas and observables!

[agusterodin]

Cool! So the new "condition" function is the equivalent of what take (https://redux-saga.js.org/docs/api#takepattern) is in redux-saga?

[markerikson]

Yes! With the added ability that rather than just matching on actions, it also feeds in currentState, previousState. So, if you wanted to write a condition that just matches on "state field X changed", you could do that.

[Jazzmanpw]

I still think that listening to an action change should be handled wiser. If a couple of listeners try to compare by the same selector that is memoized, we'll run into a case when the first one to run will break the cache (I mean reselect-memoized with no tweaks), and the second one won't work as expected. It was easy to implement in my middleware that you mentioned above, but for all your difficult cases with wait for action and all of that it becomes not clear how we could do it. And even what the previous and the next state are is a tricky question

[markerikson]

@Jazzmanpw: can you give some specific examples of what you're describing?

[Jazzmanpw]

Sure. Imagine a search app that stores the current search parameters in the URL. There's one listener that sends the request when the state changes, and another one that writes the parameters to the URL. A single dispatch tweaks the parameters and should trigger two handlers. If these parameters are not stored directly in the state, and the computation is done with memoizing selectors, we'll call the selectors (1) with the previous state in the listener A, then (2) with the next state in the listener A, then (3) with the previous state in the listener B, then (4) with the next in B.

(1) returns the cached value. (2) returns the new value for the new state (even if the value computed by the selector itself shouldn't change, the cache will expect the next state to be the cached input). (3) tries to compute the value for the previous state, but it won't be referentially equal to the value returned in (1)

Interestingly enough, I'm starting to see that I might be wrong. But I'll leave the development of my thoughts, so maybe you'll confirm that it's worth worrying about

maybe, the original concern was that in these two listeners we'll continue recomputing the selector results jumping between two inputs (the previous state and the next one). it might not bring us to a point where something will stop working, but knowing that all that computations happen (although they may not) feels disturbing

[Jazzmanpw]

Just a minor note: if the Redux style guide tells us that the actions should actually be events, not setters, don't you want to try to name them properly? I tried to find the solution, but I found nothing better than handlerRequired and handlerRejected events

[markerikson]

Sorry, not clear what you're suggesting here - can you clarify?

[Jazzmanpw]

the suggestion is to find a name for add/remove listener actions such that they will look like events, but not like imperatives. according to this guide

[Jazzmanpw]

I'm not fully sure it's very important. I still didn't get a chance to work with a fully event-based redux architecture, although it seems to be great. So the suggestion is also me trying to understand that maybe there're places where imperative actions are still viable. Or not

These two actions are pretty clear for me as events: a listener became necessary and a listener became useless or something along those lines. I have a feeling of these events, but I can't find proper words to describe it

[phryneas]

One general addition: this is not trying to replace saga. This does not need to cover every nook and cranny and weird use case.

This is meant to fill a gap that thunks can't fill and where saga is still oversized.

Please let's not overengineer this thing, but keep it simple.

[budarin]

it is better to leave the opportunity for overengineering than overengineering for everyone by default :)

[landisdesign]

Such opportunities! 😃

[Jazzmanpw]

What is the supposed way if several handlers should be added as a piece of a single module? To make it clear:

const listenToLogin = (action) => localStorage.setItem('token', action.payload.token)
const listenToLogout = (action) => localStorage.removeItem('token')

It's a very rough example, but in my experience, there's a sense to group some handlers together. If I get it correct, with the current API we have either the option to export an array of matcher-listener pairs and iterate through them or to do this:

addListener(anyOf(loggedIn, loggedOut), (action) => {
  if (action.matches(loggedIn)) {
    localStorage.setItem('token', action.payload.token)
  } else /* if action matches(loggedOut) */ {
    localStorage.removeItem('token')
  }
})

But the latter looks awkward to me

I might be wrong with the interfaces, so it's more like pseudocode, but the question is: what is the supposed way of grouping the listeners (not as dependents, but more as neighbours)? Do we really want to keep the action/listener coupling at the top of the middleware API, or maybe it may be moved lower? I always thought of it more like of a reducer-ish type of interface

[swyxio]

I built a "Tweet Undo" feature with the condition api: https://codesandbox.io/s/redux-toolkit-action-listener-middleware-demo-react-tailwind-98brh?file=/src/App.tsx:2045-2052

ScreenFlow.mp4

[markerikson]

I've spent the last couple days attempting to rewrite both the TS types and the code structure so that:

• There's a single implementation of how to turn all the possible options into a "listener entry" object
• That should support defining the "action to listen for" as a type string, an action creator, a "matcher" function, or a "listener predicate" function, and the type of action in the listener needs to be inferred correctly based on which approach was used.
• I then want to be able to write something like export const addAppListener = PreTypedAddListener<RootState> = middleware.addListener, and now all the state usages inside (currentState/previousState in predicates, listenerApi.getState, etc) have the right state type, and otherwise have the state be unknown if you use the default.

So far I'm failing. I've started and stopped a couple dozen attempts at the types. A couple came close but couldn't quite get the inference right.

The current WIP branch is here: https://github.com/reduxjs/redux-toolkit/commits/feature/listener-middleware-fixes

If anyone has ideas on how to make this work the way I want, I'd really appreciate help here!

[landisdesign]

Excellent! Welp, at least I got the project up and running on my machine. Hope to do some good next time.

[markerikson]

Cool. FYI I just threw in the subscribe option and am about to PR that, then put out 0.3. Please feel free to play around and brainstorm any other improvements you can think of :)

[landisdesign]

Sweet! Will do.

[einarq]

Looks very interesting. Will there be a way to add listeners after the store is created? Thinking about code-splitting and lazy loading.

[markerikson]

Yep, can already do that!

      store.dispatch(
        addListenerAction({
          actionCreator: incrementByAmount,
          listener: (action, listenerApi) => {
            expectType<PayloadAction<number>>(action)
          },
        })
      )

and the condition method is actually a one-shot listener itself.

[markerikson]

I kinda wanted to have a single "Changelog" subthread, but I think the continuing updates will get buried because Github collapses subthreads after a handful of replies. So, one top-level reply per meaningful release, I guess? (You can tell we haven't figured out this monorepo thing yet)

v0.3.0

Changelog

This release completely rewrites the TS types and logic so that addListener/addActionListener now accept options objects instead of positional parameters, adds types to allow defining "pre-typed" versions of those functions, and adds a subscribe function to listenerApi.

npm i @rtk-incubator/action-listener-middleware@0.3.0

yarn add @rtk-incubator/action-listener-middleware@0.3.0

[BREAKING] Add Listener Options Changes

0.2.0 had a couple major issues with adding listeners. The middleware.addListener function took different options than did the addListenerAction action creator, and neither of them allowed passing through correct types for state for use inside the listeners themselves. So, you always had to do const state = getState() as MyAppState, etc. Similarly, the listener predicate functions were not inferring any of their argument types correctly - everything was unknown or any.

I knew what I wanted the API and types behavior to look like, but I ran into a wall trying to get them to cooperate. Happily, @josh-degraw and @phryneas both tried tackling the problem, and came up with the puzzle pieces I needed. Josh showed how to properly extract the type overloads to be reusable, and Lenz showed an approach for passing an options object with varying fields that could be type-inferred correctly.

So, both middleware.addListener() and dispatch(addListenerAction()) now take a single options object instead of multiple positional parameters. That object looks roughly like:

type AddListenerOptions = {
  type?: string
  actionCreator?: TypedActionCreator
  matcher?: Matcher
  predicate?: ListenerPredicate
  listener: ActionListener
  when?: When
}

You must provide one of the first four fields to tell the middleware how to know when the listener needs to run. type and actionCreator will match a single action type exactly. matcher and predicate will match whenever the function returns true.

Any actual usages of the middleware and addListener* functions need to be updated to match the new signatures

Typing Listeners

The createActionListenerMiddleware function does accept a State generic. Unfortunately, this will rarely be usable, because normally your app infers type RootState = ReturnType<typeof store.getState>. If you try to use that in a middleware, TS will error due to a circular type inference problem. (If you were to do type RootState = ReturnType<typeof rootReducer>, it would probably work.)

Instead, the middleware now includes a pair of types for defining "pre-typed" versions of the middleware.addListener and addActionListener functions: TypedAddListener and TypedAddListenerAction. You can use those in combination with your app's RootState the same way we recommend creating "pre-typed" versions of the React-Redux hooks, so that the rest of the app always imports and uses versions of these functions with the right types applied.

The TS type of the action param in the listener should be inferred correctly, although if you are using a ListenerPredicate, you must write it as a true TS type predicate with an action is MyActionType declaration, and you must declare the TS types of all args. Additionally, you'll need to use the pre-typed functions to avoid errors from declaring real parameter types when the inferred type is unknown anyway. Here's a modified example from our typetests, showing all the expected types being passed through:

import {
  createActionListenerMiddleware,
  TypedAddListener,
  TypedAddListenerAction,
} from '@rtk-incubator/action-listener-middleware';

import { incrementByAmount } from '../features/counter/counterSlice';

import type { AppState } from './store';

export const listenerMiddleware = createActionListenerMiddleware();

// Declare and export pre-typed versions of these functions
export const addAppListener: TypedAddListener<AppState> =
  listenerMiddleware.addListener;
export const addAppListenerAction: TypedAddListenerAction<AppState> =
  listenerMiddleware.addListenerAction;
  
// 
addAppListener({
  // If passing a `predicate`, declare each param's type explicitly,
  // and correct action inference requires the type predicate assertion too
	predicate: (
	  action: AnyAction,
	  currentState: CounterState,
	  originalState: CounterState
	): action is PayloadAction<number> => {
	  // The types of both `currentState/originalState` should be from the pre-typed version
	  expectNotAny(currentState)
	  expectExactType<CounterState>(currentState)
	  return true
	},
	listener: (action, listenerApi) => {
	  // If using `action`, `type`, `matcher`, or a `predicate` that has the right
	  // declarations, the type of `action` should be inferred
	  expectType<PayloadAction<number>>(action)

    // The `state` type should carry through to `listenerApi`
	  const listenerState = listenerApi.getState()
	  expectExactType<CounterState>(listenerState)
	  
	  // Dispatching thunks should work okay by default
	  listenerApi.dispatch((dispatch, getState) => {
	    // And the state type should carry through to thunks as well
		  const thunkState = listenerApi.getState()
		  expectExactType<CounterState>(thunkState)
	  })
	},
})

Package Fixes

The 0.2.0 package tried to use type: "module" for ESM support. That promptly broke various usages. After experimenting, this release updates the build system to hopefully be compatible with most build setups (including Next 12 in both client and server modes).

Error Handling

createActionListenerMiddleware now accepts an onError function as an option. If provided, this will be called any time an error is thrown from synchronous listeners. (If your listener is async, we can't catch that right now.) This should be useful for a form of global error handling.

subscribe Function

We were already passing unsubscribe as part of listenerOptions. A subscribe function has been added that will (re)insert the current listener's entry. This can be used for the equivalent of a takeLeading-type behavior to ensure that only one "instance" of the listener is running at a time: unsubscribe() at the start of a listener, do some work, and subscribe() again at the end:

middleware.addListener({
	actionCreator: testAction1,
	listener: async (action, listenerApi) => {
		listenerApi.unsubscribe()

		await listenerApi.condition(testAction2.match)

		listenerApi.subscribe()
	},
})

What's Changed

• [action-listener-middleware] add error handling #1708 by @FaberVitale
• Fix assorted issues with options package #1729 by @markerikson
• Rewrite action listener middleware types for better DX #1730 by @markerikson
• Add listener resubscribe option and clean up types #1731 by @markerikson

[FaberVitale]

I'm wondering if we should handle async errors from listeners too.

Why

Unhandled rejections are not fun to deal with when you are constrained by an external api:
In node unhandled rejections crash the server.

If we encourage async listeners we ought to provide a reasonable way to catch and handle them.

Suggested Changes

• I'm going to submit a PR that will provide async error handling through the onError callback.

• Improve typing of ActionListenerMiddleware its return type should be void | Promise<void>. I'm not sure if it's better to use a union type or function overloading.

[FaberVitale]

I've created a simple counter example that uses action-listener-middleware that uses condition and subscribes 2 listeners.

• demo
• source

[markerikson]

Been doing some more brainstorming with regards to API design and capabilities, particularly around task cancellation and error handling.

Note: I'm not trying to turn this middleware into a massive API or completely match capabilities of other libraries like sagas, but I think it's worth exploring what the capabilities should be and how much we can make possible with a few key built-in options. (Plus there's lots of other people way smarter than me who have spent years thinking about this topic and I'm barely able to scratch the surface here.)

Looking through the saga docs ( https://redux-saga.js.org/docs/basics/DeclarativeEffects and onwards ), I think we can mimic a decent portion of what can be done with sagas. The listener already acts like a takeEvery, and you can do the equivalent of a takeLeading by calling unsubscribe() at the start of a listener and subscribe() at the end. On the other hand, per https://redux-saga.js.org/docs/advanced/Concurrency , takeLatest requires some form of cancelation to kill off the previously running listener.

The biggest weakness with async/await is that it's not easily cancelable, because A) Promises themselves aren't meaningfully cancelable, and B) async functions aren't externally controlled the way generator functions are.

Besides sagas, there's three other major side effects approaches that I can think of that might do something like that: observables, state machines, and https://github.com/jeffbski/redux-logic:

• redux-observable has cancelation as described at https://redux-observable.js.org/docs/recipes/Cancellation.html
• Glancing through the XState docs, I can't immediately any mentions of "canceling" besides a couple specific states in examples, so perhaps that's not much of a thing?
• https://github.com/jeffbski/redux-logic does talk about cancelation (and is also built on observables)

There's also http://ember-concurrency.com , which is similar to sagas in that it uses generator functions. (Plus I'm seeing a bunch of other JS libs that implement more complex async logic with generators, like https://github.com/getify/CAF, https://github.com/thefrontside/effection , https://github.com/jetako/mst-async-task, https://github.com/CygnusRoboticus/concurrency-light, etc).

Another thing that sagas and ember-concurrency can do that we can't do here is hierarchical tasks, where there's a defined parent/child relationship: https://redux-saga.js.org/docs/advanced/ForkModel , http://ember-concurrency.com/docs/child-tasks

Searching around through NPM for things like async cancelation and cancelable task, and googling for js async function cancel, I see a few libs that seem to implement some kind of relevant API. Some of them rely on AbortController or some kind of "cancelation token" that has to be passed around or explicitly waited on at spots in the async logic. I also saw a couple that appear to be more "task"-oriented, which looked kind of interesting:

• https://github.com/ethossoftworks/job-ts
• https://gist.github.com/andrewcourtice/ef1b8f14935b409cfe94901558ba5594

It would be interesting to see if one of those could be adapted here.

I will say that https://github.com/jeffbski/redux-logic does have a very interesting API, but A) the lib seems to be semi-dead at this point, B) has a huge bundle size due to use of rx-js and core-js, and C) doesn't seem to be published well (v4.0.0 listed as "latest" on the repo but not live on NPM, 3.0 shouldn't be pulling in core-js anyway).

There's also a prior related RTK issue thread on "declarative side effects and data fetching", which has discussed things like state machines.

Temporal.io has some interesting and relevant API design also: https://docs.temporal.io/docs/typescript/cancellation-scopes/ , https://docs.temporal.io/docs/typescript/workflows/#workflow-apis .

No real conclusions atm, other than "canceling async functions is clearly not easily doable - if you really want that you need generators".

[FaberVitale]

Add take(pattern)

We do not have currently the equivalent of take.
It would be nice to have the equivalent of condition that returns the matched action instead of true.

Why?

If you want, inside a listener, to process payload of an action that matched a condition you have to:

1. Grab it via closure.
2. Write yourself a version of condition that returns matched action.

Can't we just provide it instead?

[markerikson]

Hah, yes, I was literally thinking the exact same thing :)

I based the implementation of condition off the one in https://docs.temporal.io/docs/typescript/workflows/#condition . The current semantics are: returns a promise that resolves to true if the condition matched, and false if the timeout kicked in. I'm wondering if it should maybe be more like: resolves with [action, currentState, previousState] if the condition matched, or rejects if the timeout expired.

Or we could just have condition and take be separate.

[FaberVitale]

if the condition matched, or rejects if the timeout expired.

Mmmm... try & catch are not fun especially when are not strictly necessary, see #1648 (reply in thread) and #1732.

It would also make certailn workflows more verbose:
e.g. I've used condition returning false to trigger a cancellable delayed dispatch here: https://github.com/reduxjs/redux-toolkit/pull/1737/files#diff-e619b8395679d4c6ccf667624031f549b2ca764dd58948a146ab40d5354e0c3eR48

Is it possible to add an overload of condition that returns the action if the timeout is not passed?

[landisdesign]

Is it possible to add an overload of condition that returns the action if the timeout is not passed?

Perhaps take becomes the basis for condition. take resolves to [action, currentState, previousState] or null, while condition wraps that in a boolean. It seems like they have different purposes and mental concepts, even though their underlying processes are virtually the same.

[markerikson]

As of #1792 (comment) , we've now got:

• a new take API that resolves to [action, currentState, previousState] (same as what the predicate receives)
• condition is now just a wrapper around take that returns true/false instead
• the Job lib I've been playing with is partially integrated, and all listener invocations are wrapped in a Job instance
• Canceling a running listener also cancels its active take/condition functions that it's waiting on and throws a JobCancellationException
• You can cancel all previous/currently-running instances of a listener via listenerApi.cancelPrevious()
• The API for the current job is exposed as listenerApi.job.* - see https://github.com/ethossoftworks/job-ts/blob/main/docs/api.md for an idea what's there, including launching child jobs and cancelation-aware pause and delay

In particular, listenerApi.cancelPrevious() is basically the equivalent of takeLatest() in sagas. Just call it at the start of your listener. This does assume the earlier instances are at a cancelation-aware pause point, but it's a whole lot more than you could ever do with thunks :)

I'm not ready to put this out as a 0.4.0 yet - I want to polish it, flesh out tests, and update the README docs. But, I'd love it if someone were to try out the CSB CI build from that PR.

/cc @agusterodin

[agusterodin]

Sorry for the delay :( have been swamped all morning.

Here are a few use cases of takeLatest in our codebase. I did a lot of soul searching when looking back at these and realize that have a) implemented it another way that is arguably better or b) convert over to RTK query. Regardless, it is nice to have a drop in replacement for saga to ease transition to RTK or for people that don't want to use RTK query for data fetching and instead do things manually. In all cases I personally would opt to use RTK query. Also worth noting that RTK query didn't exist at the time of writing any of this code.

1. Pretty straightforward and common but debounce. “listening” to the same action as the textbox value setter.

This example is fetching autocomplete suggestions as you type.

In the future I can just implement debounce inside of the map autocomplete searchbox component itself. I could take advantage of useDebounce from react-use in conjunction with useState to keep track of debouncedSearchText. That debounced search text could feed into RTK Query.

export function* fetchMapPlacesSuggestionsTask(action: ReturnType<typeof setMapPlaceSearchText>) {
  const { value: query, skipFetch } = action.payload
  if (query.trim() === '') {
    yield put(setMapPlaceSearchResults(null))
  }
  else if (!skipFetch) {
    yield delay(AUTOCOMPLETE_DEBOUNCE_DURATION)
    const center = getMapViewport(yield select())?.center
    try {
      if (center) {
        const searchResults = yield* call(findPlacesBySearchText, query, center, 5)
        yield put(setMapPlaceSearchResults(searchResults))
      }
    }
    catch (error) {
      yield put(setToast({ text: 'Failed to fetch places results', style: ToastStyle.Error }))
    }
  }
}

2. Auth flow

In hindsight implementing auth ourselves is a fools chore. We do have our own auth server that serves as a “proxy” to Auth0 so that certain things are completely customized. It would be cool to instead use a solution like next-auth. Unfortunately, in my experience with a personal project next-auth still isn’t 100% viable for our needs (but is rapidly improving). We would also need to transition all of our apps to Next which is a very heavy lift with not many tangible business value compared to other tickets. To make matters more complicated our backend really isn't even really a legit Oauth server, more of a proxy so next-auth potentially wouldn't even be what to reach for. RTK query would probably be the more appropriate thing to reach for in this scenario.

One part of this that we absolutely needed was the “inactivity check”. Our application is used by government customers with sensitive data. It is required that we “kick them off” after a certain period of inactivity (similar to what banking sites do). In hindsight file could have used the useIdle hook from react-use in our App.tsx and dispatched logout from there.

Ideally I want to reimplement this flow in RTK Query in the future in conjunction with the useIdle hook as mentioned above.

import { createAction } from '@reduxjs/toolkit'
import { put, takeLatest, select, call, spawn, fork, delay, take, cancel } from 'typed-redux-saga/macro'
import { push } from 'connected-react-router'
import { stringify as generateQueryString, parse as parseQueryString } from 'query-string'
import authApi from '../legacyApi'
import { setUserProfile, setAuthenticated, setAuthenticationLoading } from './authentication'

// Constants And Custom Interfaces

const TOKEN_EARLY_RENEWAL_TIME = 30 // 30 Seconds
const INACTIVITY_CHECK_INTERVAL = 60 * 10 // 10 Minutes

// Action Creators

export const loginRedirect = createAction('authentication/loginRedirect')
export const processToken = createAction('authentication/processToken')
export const fetchProfile = createAction('authentication/fetchProfile')
export const loggedIn = createAction('authentication/loggedIn')
export const logout = createAction('authentication/logout')

// Helpers

// Expiry time that comes back from server and that is stored in cookies is in unix epoch seconds (not milliseconds)
// JavaScript and Redux Saga work in milliseconds so we use helper conversion functions when necessary
export const hasExpired = (expiryTime: number) => getUnixTimeInSeconds() > expiryTime
export const getUnixTimeInSeconds = () => Math.floor(new Date().getTime() / 1000.0)
export const secondsToMilliseconds = (seconds: number) => seconds * 1000

// Selectors

const getCurrentRoute = state => state.router.location.pathname
const getCurrentQueryString = state => state.router.location.search
const getHashParameters = state => state.router.location.hash

// Tasks

export function* authenticationFlowTask() {
  let task = yield* fork(fetchProfileTask)
  while (true) {
    yield* take(loggedIn.toString())
    if (task) yield* cancel(task)
    task = yield* fork(inactivityCheck)
    yield* take(logout.toString())
    yield* cancel(task)
  }
}

export function* loginRedirectTask() {
  const currentRoute = yield* select(getCurrentRoute)
  const currentQueryString = yield* select(getCurrentQueryString)
  localStorage.removeItem('access_token')
  localStorage.removeItem('expiry_time')
  sessionStorage.setItem('lastUnauthenticatedRoute', currentRoute)
  sessionStorage.setItem('lastUnauthenticatedQueryString', currentQueryString)
  const queryString = generateQueryString({ redirectUri: `${window.location.origin}/callback` })
  window.location.replace(`${process.env.REACT_APP_AUTH_URL}/login?${queryString}`)
}

export function* processTokenTask() {
  const rawHashParameters = yield* select(getHashParameters)
  const { token, expiry } = parseQueryString(rawHashParameters)
  if (token && expiry) {
    // @ts-ignore
    localStorage.setItem('access_token', token)
    // @ts-ignore
    localStorage.setItem('expiry_time', expiry)
  }
  let lastUnauthenticatedRoute = sessionStorage.getItem('lastUnauthenticatedRoute')
  let lastUnauthenticatedQueryString = sessionStorage.getItem('lastUnauthenticatedQueryString')
  if (lastUnauthenticatedRoute === '/callback') {
    lastUnauthenticatedRoute = '/'
  }
  sessionStorage.removeItem('lastUnauthenticatedRoute')
  sessionStorage.removeItem('lastUnauthenticatedQueryString')
  yield* put(fetchProfile())
  if (lastUnauthenticatedRoute) {
    yield* put(push(`${lastUnauthenticatedRoute}${lastUnauthenticatedQueryString}`))
  }
}

export function* fetchProfileTask() {
  yield* put(setAuthenticationLoading(true))
  const accessToken = localStorage.getItem('access_token')
  const expiryTime = localStorage.getItem('expiry_time')
  try {
    // @ts-ignore
    if (accessToken && expiryTime && !hasExpired(expiryTime)) {
      yield* delay(0)
      const userProfile = (yield* call(authApi.getProfile)).data
      yield* put(setUserProfile(userProfile))
      yield* put(setAuthenticated(true))
      yield* put(loggedIn())
    }
  }
  catch {
  }
  finally {
    yield* put(setAuthenticationLoading(false))
  }
}

export function* renewTokenSaga() {
  try {
    // @ts-ignore
    const { token, expiryTime } = (yield* call(authApi.renewToken)).data
    if (token && expiryTime) {
      localStorage.setItem('access_token', token)
      localStorage.setItem('expiry_time', expiryTime)
    }
    else {
      yield* loginRedirectTask()
    }
  }
  catch {
    yield* loginRedirectTask()
  }
}

export function* logoutTask() {
  localStorage.removeItem('access_token')
  localStorage.removeItem('expiry_time')
  yield* put(setAuthenticated(false))
  yield* put(setUserProfile(null))
}

function* inactivityCheck() {
  let mouseWasMoved = false
  const captureMousePosition = () => {
    mouseWasMoved = true
    document.removeEventListener('mousemove', captureMousePosition)
  }
  while (true) {
    document.addEventListener('mousemove', captureMousePosition)
    const expiryTime = localStorage.getItem('expiry_time')
    if (expiryTime) {
      // Delay time calculation is based in seconds and gets converted to milliseconds when passed to saga delay function
      // @ts-ignore
      const delayTime = Math.min(expiryTime - getUnixTimeInSeconds() - TOKEN_EARLY_RENEWAL_TIME, INACTIVITY_CHECK_INTERVAL)
      yield* delay(secondsToMilliseconds(delayTime))
      document.removeEventListener('mousemove', captureMousePosition)
      if (mouseWasMoved) {
        yield* renewTokenSaga()
      }
      // @ts-ignore
      else if (expiryTime - getUnixTimeInSeconds() - TOKEN_EARLY_RENEWAL_TIME < INACTIVITY_CHECK_INTERVAL) {
        yield* loginRedirectTask()
      }
      mouseWasMoved = false
    }
  }
}

export default [
  spawn(authenticationFlowTask),
  takeLatest(loginRedirect.toString(), loginRedirectTask),
  takeLatest(processToken.toString(), processTokenTask),
  takeLatest(fetchProfile.toString(), fetchProfileTask),
  takeLatest(logout.toString(), logoutTask)
]

3. This example probably harder to put into a tangible form. Unfortunately the implementation for this scenario is used in an application that is used by the government so I can’t just capture a video.

The company I work for makes an interactive data analysis tool that data analysts use (similar to Tableau). The analysis tool UI contains a summary panel containing a summary of current sub selections made, an interactive timeline, a data table, and a map. All of these components show the same data simultaneously but presented in different ways. A feature that the analysts absolutely love is being able to hover over a device identifier in the timeline plot/table/map/summary panel and have that row of data “emphasized”/highlighted on all other components (currently hovered device identifier is referred to as "highlightedDeviceIdentifier" in Redux). We also have a longHoveredHighlightedDeviceIdentifier which is debounced. Our primary use for this is that the Plot library we use gets really slow when a ton of rerenders occur. We fixed this issue by only feeding the plot library the longHoveredDeviceIdentifier instead of hoveredDeviceIndentifier to minimize these expensive rerenders. We very well could have implemented debounce for the “longHoveredDeviceIdentifier” on an individual component basis but it is much more ergonomic to have this handled at a global level.

[markerikson]

v0.4.0

This release adds a new take API that waits for an action and returns the action + state, enables cancelation of existing listeners, and adds a new "job" abstraction that can be used to launch child tasks and wait for their results.

I've updated the API reference in the main post of this thread to cover this version.

Changelog

New take API

We previously added condition: (predicate, timeout?) => Promise<boolean>, which resolves when the predicate returns true based on some action+state combination. Since it returns a boolean, it can be used for conditional checks like if (await condition()). However, it's common to want to access to the actual action that was being checked, such as logic that needs to make use of the action payload.

We've added a new take: (predicate, timeout?) => Promise<[action, state, state] | null> function which behaves the same way, but resolves to the same (action, currentState, previousState) combination that the predicate saw when it returned true.

Listener Cancelation

Canceling async functions is a very difficult thing to do, and the main reason why libraries like Redux-Saga and Ember Concurrency rely on generator functions that can be controlled by the driver logic to enable cancelation.

However, cancelation is a key prerequisite for async operations like "take only the latest of several operations started in succession", so we wanted to find a way to enable that here.

After searching for existing libraries, we've found an excellent library at https://github.com/ethossoftworks/job-ts . It provides a Job class that has cancelation capabilities built in, with a small and understandable API and implementation.

We've copied the library's implementation into the RTK codebase (thanks to a friendly MIT license), and made some tweaks to the implementation to suit the needs of the middleware.

All listener calls are now wrapped in a Job instance, which can be used to cancel the running listener. For the cancelation to have an effect on behavior, the listener must currently be paused waiting for one of the cancelation-aware APIs to complete: take, condition, or listenerAPI.job.delay/pause. If the listener is canceled while waiting for one of those, a JobCancellationException will be thrown inside the listener.

The listenerApi object now has a new cancelPrevious method, which can be used to cancel any prior outstanding instances of the listener.

Jobs API

A running Job creates a JobHandle instance, which can be used to check the job's status, cancel it, or even launch child jobs that can be awaited on to collect their results. That JobHandle object for the current listener is now exposed as listenerApi.job.

See https://github.com/ethossoftworks/job-ts/blob/main/docs/api.md for full documentation of that API for now.

Saga-Style Effects Behaviors

While this isn't a feature by itself, the new workflow primitives can be used to implement the equivalent of many of the "effects" operators from Redux-Saga, including takeLatest, takeLeading, throttle, debounce, fork + join, and fork + cancel.

See effectsScenarios.test.ts for some small examples of what it looks like to implement equivalent patterns using the middleware's API primitives.

Changes

• Add a "jobs" system to the listener middleware #1792 by @markerikson
• feature/middleware-jobs -> implement take using jobs #1799 by @FaberVitale

[markerikson]

Interesting thought I just had:

Right now it's easy to access middleware.addListener because it's a separate package and so you have to create it separate from the store.

What happens if we finalize this, put it into RTK, and add it to configureStore by default?

You won't have access to the middleware instance, and thus won't have access to middleware.addListener either.

Not sure how we'd be able to expose that.

[FaberVitale]

Interesting thought I just had:

Right now it's easy to access middleware.addListener because it's a separate package and so you have to create it separate from the store.

What happens if we finalize this, put it into RTK, and add it to configureStore by default?

You won't have access to the middleware instance, and thus won't have access to middleware.addListener either.

Not sure how we'd be able to expose that.

We could drop middleware.addListener and require users to add and remove listeners only via an action creator with a well known type.
RtkQuery does the same thing and it works.

[phryneas]

That could work to circularity issues though, where slice files that immediately want to dispatch a listener build a circle.

store - reducer - slice file - addListener dispatch - store

If there is a middleware.addListener, there is no circle

store - reducer - slice file
store - middleware
slice file - middleware

[timoxley]

In action-listener-middleware the listener signature looks like: (action: Action, listenerApi: ListenerApi) where ListenerApi is basically an enhanced Store.

I immediately felt like this was weirdly inconsistent with other redux apis where the context/state/store is passed as the first argument and action second.

e.g. reducers are (state, action)

Is there a reason why the argument order is action first, store/context/api second?

[timoxley]

Fair enough.

[timoxley]

Thinking on this, makes me wonder if "effect" would be a more suggestive/coercive term than "listener"?

[FaberVitale]

Thinking on this, makes me wonder if "effect" would be a more suggestive/coercive term than "listener"?

That's a reasonable point, especially if you're primarily using predicate or match.
On the other if you're mostly using actionCreator or type this middleware looks like an event bus.

---

Middleware name

We're brainstorming a new name for this middleware, something shorter and catchier.

I personally lean towards rtk-listeners(google search) but we'd really like feedback and suggestions on this one.

[markerikson]

Yeah, the addition of the (action, currentState, prevState) predicate signature does make it a lot more than just an "action" listener. (and you could almost argue that it's worth having some kind of a built-in "did this state change?" handler to simplify that particular use case.)

Note that the end goal here is to merge it back into RTK itself as just another top-level API, ie, createActionListenerMiddleware, rather than keeping it as a separate package permanently. Could maybe drop the "action" out of the name?

[FaberVitale]

Note that the end goal here is to merge it back into RTK itself as just another top-level API, ie, createActionListenerMiddleware, rather than keeping it as a separate package permanently.

Regardless of the way the is going to be released, we need a shorter name to use when we're talking about middleware:
26 characters (action-listener-middleware) is a bit too long.

It definitely stands out when compared to other RTK features:
slice, asyncThunk, rtk-query, entityAdapter.

It could really use a shorter name.

---

Could maybe drop the "action" out of the name?

That's a good idea.

[einarq]

What would be the equivalent of using an "actionChannel" in redux saga, is that achievable with listeners atm?
I'm using actionChannel to make sure that many actions of the same type that are triggered at the same time do not all run at the same time, but instead run in sequence. For instance when wanting to load the details of many nodes at the same time.

The user might open a single node (the most common scenario), or they might open many nodes. Every opened node will try to load their details data.

There are other ways I can model this of course, but just wondering if there was a recipe already for something like this using a listener.

https://redux-saga.js.org/docs/advanced/Channels/

[phryneas]

No, at that point where you use action channels you are at one of the points where sagas actually make sense.

This package is not trying to replace them, but to offer a lightweight alternative for more simple use cases where sagas are just oversized.

[einarq]

Gotcha, makes sense. I only have a couple of usages of actionChannel, and they should be fairly simple to replace with a custom hook for instance.

[wuweiweiwu]

bug report:

currently if you follow the instructions for setting up typescript addListenerAction the the return value from dispatch is not () => void instead is a action { type: string, payload: ... }

even though the return value is actually the unsubscribe function

[markerikson]

Yeah, that's a known-ish issue - I've actually got a // @ts-ignore and a // TODO in the tests where it's checking that behavior.

Not yet sure if it's the middleware specifically, or configureStore that's the issue.

Will have to investigate that further and fix it before this is ready to go final.

Thanks for trying this out and noting this! Out of curiosity, what's your use case for the middleware?

[wuweiweiwu]

current use case is that i want to start a data fetching thunk every time a redux state field is updated. and rather than specifying implicit dependencies in effect hooks (current solution) this new listener api would be much nicer for achieve side effects when actions are dispatched

[FaberVitale]

Memory pressure caused by getOriginalState

What's the issue?

Currently action-listener-middleware exposes a producer getOriginalState that returns the state before the update.

It effectively means that parts of the original state that could be garbage collected cannot be reclaimed until
all the listeners have completed their sync or async execution.

That can be really problematic especially when dealing with asynchronous saga-like listeners and heavy redux stores.

---

Reproduction

I've written a simple demo that showcases the problem:

• standalone: https://cocky-kowalevski-eac3c4.netlify.app
• codesandbox: https://codesandbox.io/s/action-listener-middleware-memory-leak-test-5j068

It is recommended that you use the standalone version.

---

TL;DR

Current implementation of getOriginalState can create memory issues with long running listeners.

I'd like to make getOriginalState an opt-in feature.

[FaberVitale]

I was vaguely wondering if that might be an issue.

How would we make this "opt-in"?

getOriginalState as optional 3rd argument | Breaking change

getOriginalState is no longer available inside listenerApi but is instead provided as an optional 3rd argument.

We could, like express.js, use function.length to figure out what kind of function the user is passing.
We'd call the listener with getOriginalState as 3rd argument only if function.length >= 3.

---

Example

async function calledWithGetOriginalState(_, listenerApi, getOriginalState) {}

async function calledWithoutGetOriginalState(_, listenerApi) {}

actionListenerMiddleware.addListener({
  actionCreator: counterActions.updateByAsync,
  listener: calledWithGetOriginalState,
});

actionListenerMiddleware.addListener({
  actionCreator: counterActions.updateByAsync,
  listener: calledWithoutGetOriginalState,
});

---

What about varargs listeners?

(function(...args){}).length === 0;
(function(action, ...args){}).length === 1;
(function(action,listenerApi, ...args){}).length === 2;

We do not pass getOriginalState in those edge cases:
a user has to explicitly request getOriginalState.

---

Pros

I believe this solution is maintainable, it's just an overload, and it simple to use for JS and TS users.

Cons

It doesn't play nice with higher order functions like_.debounce or _.throttle.
I believe that it is an acceptable compromise because that are simple workarounds:

import { debounce } from 'lodash-es';

const innerListener = debounce((_: AnyAction, listenerApi: ListenerApi, getOriginalState: () => State) => {
}, 300);

actionListenerMiddleware.addListener({
  actionCreator: counterActions.updateByAsync,
  listener:  (action, listenerApi, getOriginalState) => innerListener(action, listenerApi, getOriginalState) ,
});

[phryneas]

Alternatively, could this be made capture the original state and free it after the listener has been executed synchronously? A listener that wanted to use it later would have to save it to the side manually. That would keep things more simple.

let originalState = store.getState()
function getOriginalState() {
  if (originalState === undefined) throw new Error("originalState has to be accessed synchronously")
  return originalState
}
listener(action, { getOriginalState, ...otherstuff })
originalState = undefined;

[timoxley]

I like that approach @phryneas. Perhaps also warrants something to disable the sync freeing for debugging, like React's SyntheticEvent#persist()

[FaberVitale]

Alternatively, could this be made capture the original state and free it after the listener has been executed synchronously?

Yeah, that's definitely better. 👍

I'll try to implement your idea.

---

Perhaps also warrants something to disable the sync freeing for debugging, like React's SyntheticEvent#persist()

Not sure about this. Imo @phryneas solution works.
If possible we'd like to keep the size and complexity low.

I only wonder if we should rename getOriginalState in order to clarify that can be invoked only synchronously.

[phryneas]

I only wonder if we should rename getOriginalState in order to clarify that can be invoked only synchronously.

I think throwing a good error message will do in that case - it will be noticed.

[agusterodin]

Found a great use case for this middleware: Google Maps places API result fetching. Google forces you to use their JS library instead of HTTP endpoints which means RTK query can't be used.

Will be digging in deep during coming week and excited to run the middleware through its paces :D

Are things looking promising for this middleware in terms of it making it into RTK at some point (with the exception of potential API changes)?

[markerikson]

FWIW, you most likely could use RTKQ's queryFn option, which lets you make any arbitrary async request instead of having the endpoint fetch() on its own:

https://redux-toolkit.js.org/rtk-query/usage/customizing-queries#customizing-queries-with-queryfn

But if this works too that's cool :)

And yeah, I think we're all pretty happy with the general shape and capabilities of the API at this point, and we're down to some fine-tuning of options and behavior. I've been generally assuming this would go into an RTK 1.8 release, whenever that happens, and if there isn't anything else feature-sized that comes up soon then 1.8 might really just be the middleware addition.

[markerikson]

The author of https://github.com/neurosnap/robodux (which is a similar library inspired by RTK but taken in a different direction API-wise) just posted that they've been creating an "Express-style middleware" setup:

https://www.reddit.com/r/reactjs/comments/s1ubrx/robodux_a_powerful_middleware_and_caching_library/

Looks like the actual code is here: createApi/index.ts

Seeing a few bits of similarity in there, especially the use of cancelation and take(). Interesting.

edit

Looks like the author just extracted that code into its own repo:

https://github.com/neurosnap/redux-express-query

[timoxley]

@markerikson they're all different APIs to say "run this before that" with various ways of filtering/matching.

Just thinking it'd be elegant if maybe all of those things could somehow share the same api, something like express middleware e.g.

const itemSlice = createSlice({
  …
  reducers: {
    addOne: [predicate, prepare, entityAdaptor.addOne]
  },
  extraReducers() {
    // ???
  }
})

listenerMiddleware.addListener({
  [itemSlice.actions.addOne]: [predicate, listener1, listener2],
  [someOtherActionCreator]: [listener3, listener4],
})
  

[markerikson]

Hmm. Okay, I sorta see what you're saying.

FWIW prepare doesn't fit in here because that's not a "conditional check" kind of thing. It's basically providing the body of the action creator.

We did actually discuss adding a predicate field or something similar to the object form of createSlice.reducers at some point, mostly for the use case of treating it more as a state machine - ie, "only run the fulfilled case reducer if state.status === pending", etc. Looking.... ah yes, it was #366 . We closed that on the grounds that it didn't seem useful enough, but I'd be open to reviving that one.

[timoxley]

FWIW prepare doesn't fit in here because that's not a "conditional check" kind of thing

Hm, I guess I'm thinking in express, there's no difference in how you attach middleware that act as a guard/predicate and middleware that actually handle requests. It's the same core interface for everything.

We did actually discuss adding a predicate field

Yeah I mean, sure, but I'm more trying to think about whether there's a more general solution so you don't need to make a call on whether it's useful to have a predicate api or not, everything gets the same functionality, with the same api.

[markerikson]

At this point, I don't think so.

Tbh I'm also not sure I'm a fan of an Express-style middleware API in the first place.

To some extent, that's what a standard handwritten Redux middleware is anyway, just in the form of nested closures instead of a multi-arg function:

https://redux.js.org/faq/design-decisions#why-does-the-middleware-signature-use-currying

The goal of the listener middleware is to provide a higher-level and more opinionated approach to writing the "should we handle this action" checks that you would have otherwise written as if (action.type === 'my/action') inside a hand-written custom middleware.

[neurosnap]

Tbh I'm also not sure I'm a fan of an Express-style middleware API in the first place.

I'd be happy to chat through my experiences with using express middleware on the FE. Overall I think it could be a powerful paradigm, especially for code-reusability. It did seem awkward that I had stapled a new middleware system on top of redux which already has a middleware system. However, I have found it really useful in my own side projects and it allowed me to wire up api endpoints very quickly. Even if people aren't using it for API endpoints, using it as a middleware for thunks was pretty refreshing.

The thing I really liked about using express (really koa) middleware was the flow control.

async function mdw(ctx, next) {
  console.log('before all the next middleware');
  await next();
  console.log('after all middleware has been completed');
}

Having a context object that can be modified throughout the stack is a little awkward but I found it pretty easy to use and extremely useful when dealing with dependent queries

const thunk1 = api.create('thunk-1', async(ctx, next) {
  ctx.something = 'awesome!';
  await next();
});

const thunk2 = api.create('thunk-2', async(ctx, next) {
  const thunk1Ctx = await ctx.dispatch(thunk1());
  console.log(thunk1Ctx.something);
  // output: awesome!
  await next();
});

store.dispatch(thunk2());

Here's a blog article showcasing how middleware logic can dramatically improve code-reuse when migrating from redux-saga to something like saga-query: https://erock.io/2021/06/20/refactor-listifi-to-use-saga-query.html

[timoxley]

Is there a way to forcibly remove all listeners? e.g. to reliably clean up listeners between tests

Something like:

listenerMiddleware.removeAllListeners = (): void => {
  listenerMap.clear()
}

[markerikson]

Hmm. I really wouldn't recommend using the same middleware instance across multiple stores. That's really not how middleware are meant to be used in the first place.

But yeah, improving the removal/cleanup logic and behavior is likely something we need to look at, and I'd definitely appreciate any PRs to tweak things.

[FaberVitale]

Clear all listeners

I've develop a PR #1952 that adds simple clear method that removes all listeners and cancels running tasks and listeners.

This method can be very useful in SSR, because it provides a simple way to clean up all listeners that are still subscribed or running after rendering the page.

It also provides a simple wat to clean up between tests as requested here.

---

RemoveListener

I'll also note that I'm not particularly happy with the removal behavior right now.

However, while you can remove listeners by exact action type, you can't do that for matcher/predicate listeners.

removeListener should support the same overloads used by add addListener:

const listener = () => {};
const predicate = () => {};
const matcher = (action: any): action is PayloadAction<string> => typeof action?.payload === 'string';

// actionCreator
alm.addListener({ actionCreator: test1, listener });
alm.removeListener({ actionCreator: test1, listener });

// type
alm.addListener({ type: 'pong', listener });
alm.removeListener({ type: 'pong', listener });

// predicate
alm.addListener({ predicate, listener });
alm.removeListener({ predicate, listener });

// matcher
alm.addListener({ matcher, listener });
alm.removeListener({ matcher, listener });

We need reuse the logic defined here (/src/index.ts#L173) to find the tuple [predicate; listener] and then call findListenerEntry()?.unsubscribe():

findListenerEntry(({ predicate, listener }) => {
  return predicate === matchTuple.predicate && listener === matchTuple.listener
})?.unsubscribe();

If the user provides ({ type, listener }) the tuple used to match the entry will be[type; listener].

---

For that matter, passing in a new listener entry with the same listener function reference as another entry just keeps the existing entry instead. I'm not sure that's intuitive behavior, or what we really want.

I get that it can be not intuitive but rely on this behavior and is an acceptable limitation.

[markerikson]

@FaberVitale : Yeah, agreed in general. The one issue I see with your description there is that currently createListenerEntry creates a new action creator if you pass in type so it can use ac.match as the predicate, and thus there's no way to ever have predicate === matchTuple.predicate work if it was defined with type:

  if (type) {
    predicate = createAction(type).match  // <---- here
  } else if (actionCreator) {
    type = actionCreator!.type
    predicate = actionCreator.match
  } else if (matcher) {
    predicate = matcher
  } else if (predicate) {
    // pass
  } else {

If you've got ideas for further cleanup to the listener behavior, by all means please PR those changes :)

[FaberVitale]

@FaberVitale : Yeah, agreed in general. The one issue I see with your description there is that currently createListenerEntry creates a new action creator if you pass in type so it can use ac.match as the predicate, and thus there's no way to ever have

If you've got ideas for further cleanup to the listener behavior, by all means please PR those changes :)

I've briefly mentioned that alm.removeListener({ predicate, listener }); was an edge case but I didn't elaborate on it:

findListenerEntry(({ predicate, listener, type }) => {
  const matchPredicateOrType = typeof matchTuple.type === 'string' ?
    matchTuple.type === type : 
    matchTuple.predicate === predicate;

  return matchPredicateOrType && matchTuple.listener === listener;
})?.unsubscribe();

---

If you've got ideas for further cleanup to the listener behavior, by all means please PR those changes :)

Beyond the issues mentioned previously, I think that we need to look into these enhancements:

1. We need to populate TaskAbortError.reason in order to differentiate between listener and task cancellation.

2. await fork().result always returns an ADT even if the listener gets cancelled.
   The other methods, (pause, take, delay), throw if the listener is cancelled.
   Should we reject await fork().result if the listener is cancelled?

[markerikson]

Heh, my brain is bouncing between too many topics atm to come up with good answers :) But at first glance yes, those sound like good ideas. Please feel free to make those improvements and PR them!

[markerikson]

v0.7.0

This release adds a middleware.clearListeners() method, updates the removeListener/removeListenerAction functions to accept the same arguments as the addListener/addListenerAction functions, removes the addListenerAction/removeListenerAction from being attached to the middleware instance, and updates getOriginalState to only be called synchronously to avoid memory issues.

Changelog

Listener Removal Improvements

The middleware instance now has a middleware.clearListener method that will remove all active listeners. This is primarily useful for test scenarios where the same store instance might be reused across tests.

The middleware.removeListener and removeListenerAction methods have been updated to accept all the same options as the add functions. The middleware will try to find an existing listener entry by comparing the listener function reference, as well as the actionCreator/matcher/predicate reference or the type string.

Also, the addListenerAction and removeListenerAction functions are no longer included as fields on the middleware instance, to avoid confusion about usage. Import them from the package instead.

getOriginalState Memory Improvements

Previously, getOriginalState captured the Redux state reference permanently, since the function was kept as an option for the life of the listener. This could lead to potential memory leak concerns.

getOriginalState now can only be called synchronously during the original dispatch call stack. At the end of that synchronous sequence, the state value will be nulled out to allow the state to be garbage collected and calling getOriginalState later will throw an error.

[markerikson]

Middleware Status Update and Proposed Changes - 2022-02-05

At this point I'm satisfied with the overall listener middleware API.

There's two outstanding TS issues that need to be fixed:

• The extra type isn't carried through
• Doing const unsubscribe = store.dispatch(addListenerAction()) isn't typed right - it's coming back as a plain object, not an Unsubscribe callback

I've already fixed the extra type locally.

Lenz and I have been investigating the "unsubscribe returned from dispatch" issue, and there's two different things going on. One is that configureStore and getDefaultMiddleware needed better type inference for the provided middleware array, and we've put together a PR in #2001 to fix that (although the PR doesn't seem to have reflected the latest push).

However, the flip side is that modifying the middleware to attach {addListener, removeListener} appears to be breaking TS's ability to extract "the type of dispatch extensions" from the middleware. If I comment out those lines, the inference works correctly.

While getting the type of unsubscribe right here isn't an absolutely earthshattering problem, it is something I'd like to have working right before release.

Lenz suggested that another option might be to have the create function return an object like {middleware, addListener, removeListener}. That way the middleware itself doesn't have its type modified.

Somewhat related: Faber suggested somewhere around here that we should shorten the name (although I can't find where that was).

Based on all that, I propose to:

• Change the API name from createActionListenerMiddleware to createListenerMiddleware
• Change the return value to be {middleware, addListener, removeListener}

I'm going to give that a shot see how it turns out.

[FaberVitale]

Change the return value to be {middleware, addListener, removeListener}

Where's clearListeners?

Change the API name from createActionListenerMiddleware to createListenerMiddleware

👍

---

I still think that we need to address the issues I mentioned in #1648 (reply in thread)

[markerikson]

Yeah, can you go ahead and create a PR to make those changes? (And yes clearListeners would go in there, I just keep forgetting about it because it's new.)

Also FYI the TS changes we're making to configureStore are going to get merged into a new v1.8.0-integration branch that I need to go create here in a few minutes, just in case we decide to put out another 1.7.x patch release before 1.8 is ready. That also means that basically all remaining work on the listener middleware needs to be done against that integration branch also.

[markerikson]

One more naming question: should we rename addListenerAction somehow? We want to distinguish it from addListener, and especially now that addListener is a free-standing function instead of being attached to the middleware, but I'm not sure I like the Action part of the name.

[FaberVitale]

Yeah, I'd drop action too.

I wonder if it makes sense to expose them inside an object.

import {  listenerActions } from '@reduxjs/toolkit';

dispatch(listenerActions.addListener());

dispatch(listenerActions.removeListener());

dispatch(listenerActions.clearListeners());

[markerikson]

Name Bikeshedding Time!

Following on from the previous subthread, Lenz and I started bikeshedding renaming basically everything.

The main questions are:

• What should we call the object returned from the create() function?
  • Related to this, Lenz isn't keen on having the examples destructure {middleware, addListener}, and would prefer something like obj.middleware instead
• Lenz suggested renaming the main API to createListener(), so that you have listener.middleware, etc
  • Problem is that we've been referring to the actual callback functions as "listeners', so that would require coming up with a different name for those
• We do want to differentiate between the "instance methods" for adding and removing entries, vs the action creators

If we were to go with createListener, then some options are:

• methods:
  • add/remove
  • addX/removeX
  • attach/detach
  • subscribe/unsubscribe
• actions:
  • addX/removeX
  • xAdded/yRemoved
  • subscribeListener/unsubscribeListener
• field/functions:
  • listener
  • callback
  • effect

I already have a PR up at #2005 to rename to createListenerMiddleware and alter the return API to {middleware, addListener, removeListener}, but I'm going to hold off on merging it until we can do some bikeshedding here and try to finalize on naming.

Thoughts?

[markerikson]

Well, it's been a week and no one has replied :)

My preference here would be:

• Keep createListenerMiddleware. It makes it clear what we're doing, and it matches the createSagaMiddleware/createEpicMiddleware naming pattern from those libraries.
• Keep the existing listener name for the function field

That means we just need to come up with a consistent name for the object returned from createListenerMiddleware that contains {middleware, addListener, removeListener}, and settle on a name for the action creators.

One option would be to give the action creators all "past tense" names: listenerAdded, listenerRemoved, listenersCleared. That sort of aligns with the "actions as events" mindset.... except that these aren't even actions that are meant to update state, they really are direct commands to the middleware itself. So, that slightly bothers me too. But it would at least give us a naming convention to distinguish the action creators from the instance methods.

I don't have overly strong feelings about the "return object" name. I kinda prefer destructuring the fields immediately anyway. If we have to give it a name, I'd even be okay with listenerMiddleware (or maybe listenerInstance?). Yes, that means you'd have listenerMiddleware.middleware or something as part of store setup, but it's really only going to appear in the file where you call createListenerMiddleware, and in store.ts. The one argument I can see against destructuring is you'd have export const { middleware } = createListenerMiddleware() and import { middleware } from './otherFile', and just having a variable named middleware isn't helpful.

[josh-degraw]

Not sure how much I like it since it would essentially require deconstruction which can invoke strong opinions lol, but one potential option to address the point of just exporting middleware could be to return a tuple, that way it can be named whatever the user wants, and also highlights the distinction between the middleware and the action creators

export const [listenerMiddleware, { addListener, removeListener }] = ... 

Or even:

export const [listenerMiddleware, listenerActions] = ... 

//... 

listenerActions.addListener(...)
listenerActions.removeListener(...)

[markerikson]

So part of the issue here is there's both the "instance methods" that directly modify the middleware immediately (currently addListener) and the action creators that are used to do exactly the same task but via dispatching, intend for use elsewhere in the app (currently addListenerAction). The original question was really prompted by me not liking the word "Action" in the names, and wanting to come up with an alternate naming scheme that both distinguishes "action creators" from "instance methods", and doesn't have "Action" in the name.

At the moment we actually don't include the action creators in the return value from createListenerMiddleware(). We did originally, but removed them to help with disambiguation.

[markerikson]

After considerable bikeshedding over the last couple hours in Reactiflux, here's what we've settled on:

• API: createListenerMiddleware
• return object: {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

const listenerMiddleware = createListenerMiddleware(). 

listenerMiddleware.startListening({type, effect})
listenerMiddleware.stopListening({type, effect})

configureStore({
  middleware: gDM => gDM().prepend(listenerMiddleware.middleware)
})

const unsubscribe = store.dispatch(addListener({type, effect}))

I will update PR #2005 to match this.

[markerikson]

Merged #2005 . @FaberVitale has one more set of tweaks to make related to error codes / reasons. I will publish 0.8.0 with all these breaking changes and renames so people can use it.

Once that's done, we can move the actual code over into packages/toolkit/, and it should be ready to go into RTK 1.8.0.

I've got an open issue to discuss 1.8 planning at #2003 . Personally I'd be happy to publish it sooner rather than spending a lot of time accumulating features like we did with 1.7.

[markerikson]

v0.8.0

This release contains significant breaking changes from API renames and signature changes! However, this should be the final standalone version before we release this in an upcoming RTK 1.8 build.

Changelog

API Renaming

Now that the feature set and behavior is complete, we did a review and extensive discussion to determine final naming for all the APIs. The goals were:

• Establish consistent terminology for each piece of the API
• Distinguish naming between the "instance methods" of the middleware, and the corresponding action creators

After much bikeshedding, we settled on these final names and terms:

• API: createListenerMiddleware
• return object: {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

const listenerMiddleware = createListenerMiddleware(). 

listenerMiddleware.startListening({type, effect})
listenerMiddleware.stopListening({type, effect})

configureStore({
  middleware: gDM => gDM().prepend(listenerMiddleware.middleware)
})

const unsubscribe = store.dispatch(addListener({type, effect}))

This release includes all of those name changes.

createListenerMiddleware Return Value

Previously createListenerMiddleware() returned the actual middleware instance itself (which you would then pass to configureStore(). The "instance methods" were attached to the middleware instance object.

However, this caused some problems with TS inference. In particular, TS was unable to infer the "dispatch extensions" type from the middleware instance, and thus const unsubscribe = dispatch(addListener()) would be typed as the action object, not an unsubscribe callback.

Fixing this TS issue required significant changes to the TS types for RTK's configureStore, but also still required that we give up on attaching the instance methods to the middleware itself. Instead, createListenerMiddleware() now returns an object that contains the middleware instance and the instance methods:

const { middleware, startListening, stopListening} = createListenerMiddleware()

Note that the best TS results with dispatch(addListener()) will still require using the changes to RTK's configureStore, which have not been released yet. If this is an issue, you can use the CodeSandbox CI builds from PR #2004 .

Cancellation Reason Codes

Finishing or cancelling listeners and tasks now results in an appropriate error string like 'task-cancelled' or 'listener-completed' as the signal.reason field.

[markerikson]

A user on Reddit brought up the question of "how does this middleware relate to SSR, if at all?", and listed examples of sagas and observables having to deal with "handling endless streams of actions" and "notifying React that you're done".

Not sure there's anything we could / should do here, but interesting question:

https://www.reddit.com/r/reactjs/comments/sumbjo/how_are_you_using_redux/hxbv0g1/?context=3

[FaberVitale]

I've added "clearListeners" because I wanted a practical way clean up after a server side render.

I've settled on "clearListener"s because:

1. It is a simple way to free memory.
2. The cancellation is equivalent to the END signal used by redux-saga.

See this reply for more details: #1648 (reply in thread)

Note that is still up to the user to clean up macro tasks or any async logic that is not tied directly to listenerApi or forkApi.

I can probably add a simple SSR example, if necessary.

Relevant PRs

• feat(alm): add cancellation message to TaskAbortError, listenerApi.signal & forkApi.signal. #2023
• feat(alm): add alm.clear() method #1952

Further ideas

1. I still need to change the fork behavior: see New experimental "action listener middleware" package available #1648 (reply in thread)
2. Do we need to send a special cancellation signal in SSR? Is 'listener-cancelled' good enough?

[n-ii-ma]

Would this be an appropriate place to establish a WebSocket connection?

Something better than your own example in here: https://gist.github.com/markerikson/3df1cf5abbac57820a20059287b4be58

[phryneas]

Yes, that would be perfectly valid.

[n-ii-ma]

Could you please provide more examples regarding the removal of a listener?
How would listenerMiddleware.stopListening() know which listener to remove?

I'm implementing the createListenerMiddleware with Web Sockets and want to remove the listener that has finished listening for a specific event after completion.

Also, is there any way to get the list of all active listeners?
I think that would be a nice feature.

[phryneas]

Well, it's really pretty much

      startListening({ actionCreator,  effect })
      stopListening({ actionCreator, effect })

where you have to make sure that actionCreator and effect are really referentially equal.

[markerikson]

actionCreator doesn't have to be - the middleware grabs the .type field. (although in practice of course you'd pass the same todoAdded action creator both times, there'd be no reason to have multiple instances of it.)

[n-ii-ma]

Many thanks to both of you for the answers.

I wanted to further elaborate my use case of stopListening(). What I am trying to achieve is to remove the listener that invoked the socket connection after its work is done. For instance this socket connection gets established after a particular action is dispatched:

let socket;

socketListenerMiddleware.startListening({
  type: 'user/getUser/fulfilled',
  effect: async (action, listenerApi) => {
    // Initialize connection
    socket = io('https://server-domain.com');

    // Connect and listen
    socket.on('connect', () => {
      console.log(socket.id);

      // Dispatch some action
      listenerApi.dispatch(actionOne());
    });
  },
});

Then another listener establishes another socket connection based on the dispatched actionOne:

socketListenerMiddleware.startListening({
  actionCreator: actionOne,
  effect: async (action, listenerApi) => {
    // Listen to another event
    socket.on('someEvent', () => {
      listenerApi.dispatch(actionTwo());
    });
  },
});

Now imagine I want to stop the first listener that dispatched actionOne. Is stopListeneing() even the right place to do this? Something like:

socketListenerMiddleware.stopListening({
  actionCreator: 'user/getUser/fulfilled',
  effect: async (action, listenerApi) => {
    // Disconnect
    socket.on('disconnect', () => {
      // Action to be dispatched upon disconnection
      listenerApi.dispatch(actionThree());
    });
  },
  cancelActive: true
});

Honestly, I'm getting quite confused about the whole matter.

[markerikson]

I think the "best" answer here would be to have the first listener use await take() to wait for a signaling action from the second listener.

But this sort of "cross-coordinate between different independent chunks of code by dispatching actions" behavior is why sagas quickly become unmaintainable, so it's not a pattern I would recommend in general.

Can you give more details about why there's two separate sockets getting set up in response to different actions?

[n-ii-ma]

Well TBH, I'm actually using Laravel Echo with Socket IO and in there I start listening to channels based on dispatched actions. (I guess using Socket IO as an example for my question wasn't the best idea, since with Laravel Echo there's only one instance of socket and different channels)

For example, in listener A I start listening to a status event so that if I get the status of success from the server, an action gets dispatched which sets the status state in my store to a success. Then in listener B, I have the predicate of checking that particular status state so that if it is a success, I start listening to another event from the socket instance:

socketListenerMiddleware.startListening({
  type: 'user/getUser/fulfilled',
  effect: async (action, listenerApi) => {
    // Create a new Echo class instance
    echo = new Echo({
      host: `${HOST}:6001`,
      broadcaster: 'socket.io',
      client: io,
      auth: {
        headers: {
          Authorization: api.defaults.headers['Authorization'],
        },
      },
    });

    // Connect to the channel and listen for the event of status
    echo.private('channel.A').listen('.status', ev => {
      listenerApi.dispatch(setStatus(ev));
    });
  },
});

socketListenerMiddleware.startListening({
  predicate: (action, currentState, previousState) => {
    return currentState.user.status === 'success';
  },
  effect: async (action, listenerApi) => {
    listenerApi.cancelActiveListeners();

    // Connect to the channel and listen for another event
    echo.private('channel.A').listen('.any_event', ev => {
      listenerApi.dispatch(setSomeState(ev));
    });
  },
});

What I eventually wanted to achieve was to remove listener A after it has resolved in setting the status state to success.

At first, I tried using a simple middleware following your own sample example but after further discussion with Lenz in Stackoverflow, I decided to try out the listenerMiddleware.

[VladimirKras]

A fork misses actions that were dispatched immediately after its creation, but a listener doesn't. It means that if I want to guarantee that I don't miss any actions, I have to imitate forks by adding a listener and triggering it instantly. (a) Is this intended? (b) Is this a good workaround? (c) Are there any guarantees for forks and listeners wrt to missing some actions?

CodeSandbox Example. Click "Test", then look at the console,

1. addListener(...) is dispatched.
2. Trigger for that listener is dispatched. The listener's effect spawns a fork and another listener that it immediately triggers. After that all three continuously listen for actions using api.take(...).
3. An action is dispatched synchronously. Both listeners catch it, but the fork doesn't.
4. An action is dispatched asynchronously with setTimeout(..., 0). Everyone catches it.

[markerikson]

Hmm. Off the top of my head (and without having looked at the sandbox yet), it's because the middleware is synchronously iterating over the list of listeners that existed at the time the current action was dispatched.

If you add more listeners synchronously inside of a listener effect, you're technically still in the middle of that original middleware iteration call stack. So, in that sense it's expected behavior, but tbh it's not something we specifically thought through or designed that way.

[FaberVitale]

If I recall ccorrectly we intentionally wait before running the taks to provide a consistent behavior between synch and async tasks:

If you run forked tasks synchronously you cannot cancel them because they have already completed.

const forkedTaskHandle = fork(console.log)
forkedTaskHandle.cancel() // noop if you run forked task synchronously

It was an intentional design decision that isn't mentioned in the docs, sorry about that :/

See also:

• redux-toolkit/packages/toolkit/src/listenerMiddleware/tests/fork.test.ts

  Line 162 in 6a7879f

  it('does not run an executor if the task is synchronously cancelled', async () => {

• redux-toolkit/packages/toolkit/src/listenerMiddleware/tests/fork.test.ts

  Line 184 in 6a7879f

  it.each<{