UNPKG

@reduxjs/toolkit

Version:

The official, opinionated, batteries-included toolset for efficient Redux development

608 lines (536 loc) • 16.9 kB
import type { Action, Dispatch, MiddlewareAPI, UnknownAction } from 'redux' import { isAction } from '../reduxImports' import type { ThunkDispatch } from 'redux-thunk' import { createAction } from '../createAction' import { nanoid } from '../nanoid' import { TaskAbortError, listenerCancelled, listenerCompleted, taskCancelled, taskCompleted, } from './exceptions' import { createDelay, createPause, raceWithSignal, runTask, validateActive, } from './task' import type { AddListenerOverloads, AnyListenerPredicate, CreateListenerMiddlewareOptions, FallbackAddListenerOptions, ForkOptions, ForkedTask, ForkedTaskAPI, ForkedTaskExecutor, ListenerEntry, ListenerErrorHandler, ListenerErrorInfo, ListenerMiddleware, ListenerMiddlewareInstance, TakePattern, TaskResult, TypedAddListener, TypedCreateListenerEntry, TypedRemoveListener, UnsubscribeListener, UnsubscribeListenerOptions, } from './types' import { addAbortSignalListener, assertFunction, catchRejection, noop, } from './utils' export { TaskAbortError } from './exceptions' export type { AsyncTaskExecutor, CreateListenerMiddlewareOptions, ForkedTask, ForkedTaskAPI, ForkedTaskExecutor, ListenerEffect, ListenerEffectAPI, ListenerErrorHandler, ListenerMiddleware, ListenerMiddlewareDispatch, ListenerMiddlewareInstance, SyncTaskExecutor, TaskCancelled, TaskRejected, TaskResolved, TaskResult, TypedAddListener, TypedAddListenerAction, TypedRemoveListener, TypedRemoveListenerAction, TypedStartListening, TypedStopListening, UnsubscribeListener, UnsubscribeListenerOptions, } from './types' //Overly-aggressive byte-shaving const { assign } = Object /** * @internal */ const INTERNAL_NIL_TOKEN = {} as const const alm = 'listenerMiddleware' as const // Settled promises remove themselves from the set, so loop until it is empty // to also wait for auto-joined forks started while we were waiting. const joinAll = async (promises: Set<Promise<unknown>>) => { while (promises.size) { await Promise.all(promises) } } const createFork = ( parentAbortSignal: AbortSignal, parentBlockingPromises: Set<Promise<unknown>>, api: MiddlewareAPI, ): ForkedTaskAPI['fork'] => { return <T>( taskExecutor: ForkedTaskExecutor<T>, opts?: ForkOptions, ): ForkedTask<T> => { assertFunction(taskExecutor, 'taskExecutor') const childAbortController = new AbortController() const { signal } = childAbortController const unlinkFromParent = addAbortSignalListener(parentAbortSignal, () => childAbortController.abort(parentAbortSignal.reason), ) const result = runTask<T>( async (): Promise<T> => { validateActive(parentAbortSignal) validateActive(signal) const childBlockingPromises = new Set<Promise<unknown>>() let result: T try { result = (await taskExecutor({ getState: api.getState, dispatch: api.dispatch, pause: createPause(signal), delay: createDelay(signal), signal, fork: createFork(signal, childBlockingPromises, api), })) as T } finally { await joinAll(childBlockingPromises) } validateActive(signal) return result }, () => { unlinkFromParent() childAbortController.abort(taskCompleted) }, ) if (opts?.autoJoin) { // Drop each promise once it settles, so long-running tasks that fork // repeatedly don't keep every finished result alive. const blocking = result.then(() => { parentBlockingPromises.delete(blocking) }) parentBlockingPromises.add(blocking) } return { result: createPause<TaskResult<T>>(parentAbortSignal)(result), cancel() { childAbortController.abort(taskCancelled) }, } } } const createTakePattern = <S>( startListening: AddListenerOverloads<UnsubscribeListener, S, Dispatch>, signal: AbortSignal, ): TakePattern<S> => { /** * A function that takes a ListenerPredicate and an optional timeout, * and resolves when either the predicate returns `true` based on an action * state combination or when the timeout expires. * If the parent listener is canceled while waiting, this will throw a * TaskAbortError. */ const take = async <P extends AnyListenerPredicate<S>>( predicate: P, timeout: number | undefined, ) => { validateActive(signal) // Placeholder unsubscribe function until the listener is added let unsubscribe: UnsubscribeListener = noop const tuplePromise = new Promise<[Action, S, S]>((resolve, reject) => { // Inside the Promise, we synchronously add the listener. let stopListening = startListening({ predicate: predicate as any, effect: (action, listenerApi): void => { // One-shot listener that cleans up as soon as the predicate passes listenerApi.unsubscribe() // Resolve the promise with the same arguments the predicate saw resolve([ action, listenerApi.getState(), listenerApi.getOriginalState(), ]) }, }) unsubscribe = () => { stopListening() reject() } }) const promises: (Promise<null> | Promise<[Action, S, S]>)[] = [tuplePromise] let timeoutId: ReturnType<typeof setTimeout> | undefined if (timeout != null) { promises.push( new Promise<null>((resolve) => { timeoutId = setTimeout(resolve, timeout, null) }), ) } try { const output = await raceWithSignal(signal, Promise.race(promises)) validateActive(signal) return output } finally { clearTimeout(timeoutId) // Always clean up the listener unsubscribe() } } return ((predicate: AnyListenerPredicate<S>, timeout: number | undefined) => catchRejection(take(predicate, timeout))) as TakePattern<S> } const getListenerEntryPropsFrom = (options: FallbackAddListenerOptions) => { let { type, actionCreator, matcher, predicate, effect } = options if (type) { predicate = createAction(type).match } else if (actionCreator) { type = actionCreator!.type predicate = actionCreator.match } else if (matcher) { predicate = matcher } else if (!predicate) { throw new Error( 'Creating or removing a listener requires one of the known fields for matching an action', ) } assertFunction(effect, 'options.listener') return { predicate, type, effect } } /** Accepts the possible options for creating a listener, and returns a formatted listener entry */ export const createListenerEntry: TypedCreateListenerEntry<unknown> = /* @__PURE__ */ assign( (options: FallbackAddListenerOptions) => { const { type, predicate, effect } = getListenerEntryPropsFrom(options) const entry: ListenerEntry<unknown> = { id: nanoid(), effect, type, predicate, pending: new Set<AbortController>(), unsubscribe: () => { throw new Error('Unsubscribe not initialized') }, } return entry }, { withTypes: () => createListenerEntry }, ) as unknown as TypedCreateListenerEntry<unknown> const findListenerEntry = ( listenerMap: Map<string, ListenerEntry>, options: FallbackAddListenerOptions, ) => { const { type, effect, predicate } = getListenerEntryPropsFrom(options) return Array.from(listenerMap.values()).find((entry) => { const matchPredicateOrType = typeof type === 'string' ? entry.type === type : entry.predicate === predicate return matchPredicateOrType && entry.effect === effect }) } const unsubscribeEntry = ( entry: ListenerEntry, options?: UnsubscribeListenerOptions, ) => { entry.unsubscribe() if (options?.cancelActive) { entry.pending.forEach((controller) => { controller.abort(listenerCancelled) }) } } /** * Safely reports errors to the `errorHandler` provided. * Errors that occur inside `errorHandler` are notified in a new task. * Inspired by [rxjs reportUnhandledError](https://github.com/ReactiveX/rxjs/blob/6fafcf53dc9e557439b25debaeadfd224b245a66/src/internal/util/reportUnhandledError.ts) * @param errorHandler * @param errorToNotify */ const safelyNotifyError = ( errorHandler: ListenerErrorHandler, errorToNotify: unknown, errorInfo: ListenerErrorInfo, ): void => { try { errorHandler(errorToNotify, errorInfo) } catch (errorHandlerError) { // We cannot let an error raised here block the listener queue. // The error raised here will be picked up by `window.onerror`, `process.on('error')` etc... setTimeout(() => { throw errorHandlerError }, 0) } } /** * @public */ export const addListener = /* @__PURE__ */ assign( /* @__PURE__ */ createAction(`${alm}/add`), { withTypes: () => addListener, }, ) as unknown as TypedAddListener<unknown> /** * @public */ export const clearAllListeners = /* @__PURE__ */ createAction( `${alm}/removeAll`, ) /** * @public */ export const removeListener = /* @__PURE__ */ assign( /* @__PURE__ */ createAction(`${alm}/remove`), { withTypes: () => removeListener, }, ) as unknown as TypedRemoveListener<unknown> const defaultErrorHandler: ListenerErrorHandler = (...args: unknown[]) => { console.error(`${alm}/error`, ...args) } /** * @public */ export const createListenerMiddleware = < StateType = unknown, DispatchType extends Dispatch<Action> = ThunkDispatch< StateType, unknown, UnknownAction >, ExtraArgument = unknown, >( middlewareOptions: CreateListenerMiddlewareOptions<ExtraArgument> = {}, ) => { const listenerMap = new Map<string, ListenerEntry>() // Controllers of every effect currently executing, so clearListeners can // abort even listeners that have become unsubscribed while executing. const executingControllers = new Set<AbortController>() const { extra, onError = defaultErrorHandler } = middlewareOptions assertFunction(onError, 'onError') // Snapshot of `listenerMap`, rebuilt only after it changes. Listeners // added or removed by an effect take effect from the next dispatch. let snapshot: | { entries: ListenerEntry[]; types: Set<string>; anyType: boolean } | undefined const getSnapshot = () => { if (!snapshot) { const entries = Array.from(listenerMap.values()) const types = new Set<string>() let anyType = false for (const entry of entries) { if (typeof entry.type === 'string') { types.add(entry.type) } else { anyType = true } } snapshot = { entries, types, anyType } } return snapshot } const addToListenerMap = (entry: ListenerEntry) => { if (!listenerMap.has(entry.id)) { listenerMap.set(entry.id, entry) snapshot = undefined } } const insertEntry = (entry: ListenerEntry) => { entry.unsubscribe = () => { if (listenerMap.delete(entry.id)) { snapshot = undefined } } addToListenerMap(entry) return (cancelOptions?: UnsubscribeListenerOptions) => unsubscribeEntry(entry, cancelOptions) } const startListening = ((options: FallbackAddListenerOptions) => { const entry = findListenerEntry(listenerMap, options) ?? createListenerEntry(options as any) return insertEntry(entry) }) as AddListenerOverloads<any> assign(startListening, { withTypes: () => startListening, }) const stopListening = ( options: FallbackAddListenerOptions & UnsubscribeListenerOptions, ): boolean => { const entry = findListenerEntry(listenerMap, options) if (entry) { unsubscribeEntry(entry, options) } return !!entry } assign(stopListening, { withTypes: () => stopListening, }) const notifyListener = async ( entry: ListenerEntry<unknown, Dispatch<UnknownAction>>, action: unknown, api: MiddlewareAPI, getOriginalState: () => StateType, ) => { const internalTaskController = new AbortController() const { signal } = internalTaskController const take = createTakePattern( startListening as AddListenerOverloads<any>, signal, ) const autoJoinPromises = new Set<Promise<unknown>>() try { entry.pending.add(internalTaskController) executingControllers.add(internalTaskController) await entry.effect( action, // Use assign() rather than ... to avoid extra helper functions added to bundle assign({}, api, { getOriginalState, condition: (predicate: AnyListenerPredicate<any>, timeout?: number) => take(predicate, timeout).then(Boolean), take, delay: createDelay(signal), pause: createPause<any>(signal), extra, signal, fork: createFork(signal, autoJoinPromises, api), unsubscribe: entry.unsubscribe, subscribe: () => { addToListenerMap(entry) }, cancelActiveListeners: () => { entry.pending.forEach((controller, _, set) => { if (controller !== internalTaskController) { controller.abort(listenerCancelled) set.delete(controller) } }) }, cancel: () => { internalTaskController.abort(listenerCancelled) entry.pending.delete(internalTaskController) }, throwIfCancelled: () => { validateActive(signal) }, }), ) } catch (listenerError) { if (!(listenerError instanceof TaskAbortError)) { safelyNotifyError(onError, listenerError, { raisedBy: 'effect', }) } } finally { await joinAll(autoJoinPromises) internalTaskController.abort(listenerCompleted) // Notify that the task has completed executingControllers.delete(internalTaskController) entry.pending.delete(internalTaskController) } } const clearListenerMiddleware = () => { executingControllers.forEach((controller) => { controller.abort(listenerCancelled) }) listenerMap.clear() snapshot = undefined } const middleware: ListenerMiddleware< StateType, DispatchType, ExtraArgument > = (api) => (next) => (action) => { if (!isAction(action)) { // we only want to notify listeners for action objects return next(action) } if (addListener.match(action)) { return startListening(action.payload as any) } if (clearAllListeners.match(action)) { clearListenerMiddleware() return } if (removeListener.match(action)) { return stopListening( action.payload as FallbackAddListenerOptions & UnsubscribeListenerOptions, ) } // Need to get this state _before_ the reducer processes the action let originalState: StateType | typeof INTERNAL_NIL_TOKEN = api.getState() // `getOriginalState` can only be called synchronously. // @see https://github.com/reduxjs/redux-toolkit/discussions/1648#discussioncomment-1932820 const getOriginalState = (): StateType => { if (originalState === INTERNAL_NIL_TOKEN) { throw new Error( `${alm}: getOriginalState can only be called synchronously`, ) } return originalState as StateType } let result: unknown try { // Actually forward the action to the reducer before we handle listeners result = next(action) const { entries, types, anyType } = getSnapshot() // Entries registered by `type` or `actionCreator` can only match their // own type; `matcher` and `predicate` entries can match any action. if (anyType || types.has(action.type)) { const currentState = api.getState() for (const entry of entries) { if (typeof entry.type === 'string' && entry.type !== action.type) { continue } let runListener = false try { runListener = entry.predicate(action, currentState, originalState) } catch (predicateError) { safelyNotifyError(onError, predicateError, { raisedBy: 'predicate', }) } if (!runListener) { continue } notifyListener(entry, action, api, getOriginalState) } } } finally { // Remove `originalState` store from this scope. originalState = INTERNAL_NIL_TOKEN } return result } return { middleware, startListening, stopListening, clearListeners: clearListenerMiddleware, } as ListenerMiddlewareInstance<StateType, DispatchType, ExtraArgument> }