Skip to main content

useSequentialRequest

Wraps an async request function so that only the most recent call ever resolves meaningfully — any in-flight previous request is automatically canceled via AbortSignal.

When to use it​

  • Type-ahead search boxes where only the latest query's results matter.
  • Rapidly re-submitted forms or buttons where stale responses should be discarded.
  • Any scenario prone to race conditions between overlapping requests.

Demo​

Open the Network tab in DevTools, then click "Run Query" repeatedly and watch earlier requests get canceled.

Loading demo…

Signature​

function useSequentialRequest<T>(
requestFn: (signal: AbortSignal) => Promise<T>
): () => Promise<T>;
ParameterTypeDescription
requestFn(signal: AbortSignal) => Promise<T>The request function; must accept and honor an AbortSignal.

Returns: a callback that runs the request, canceling any previous one.

Usage notes​

  • If a request is superseded before completing, it rejects with a standard AbortError (a DOMException), the same reason its signal was aborted with. Use the exported isAbortError(error) to tell a cancellation from a real failure; it also recognizes the AbortError that fetch throws.

Migrating from 0.11​

Canceled requests used to reject with new Error("CanceledError"). Replace error.message !== "CanceledError" checks with !isAbortError(error):

import { isAbortError, useSequentialRequest } from "@altalyst/hookify";

try {
setResults(await search());
} catch (error) {
if (!isAbortError(error)) console.error("Search failed:", error);
}
  • Any still-pending request is also canceled automatically on unmount.
  • Because requestFn is accessed through a ref internally, you can safely pass an inline function without worrying about stale closures.

Hook source​

View useSequentialRequest source

use-sequential-request.ts
import { useCallback, useEffect, useRef } from "react";

import { useLatest } from "./use-latest";

/**
* Returns whether `error` is an abort error, such as the one a
* `useSequentialRequest` call rejects with when a newer call or an unmount
* cancels it, or the one `fetch` throws when its signal is aborted.
*
* It checks the error's `name`, so it recognizes the standard `DOMException`
* as well as libraries that throw their own `Error` named `"AbortError"`.
*
* @param error - The value caught from a rejected promise.
* @returns `true` if `error` is an abort error.
*
* @example
* ```ts
* try {
* setResults(await search());
* } catch (error) {
* if (!isAbortError(error)) console.error("Search failed:", error);
* }
* ```
*/
export const isAbortError = (error: unknown): boolean =>
typeof error === "object" &&
error !== null &&
(error as { name?: unknown }).name === "AbortError";

/** Creates the reason a superseded or unmounted request is aborted with. */
const createAbortError = (): Error =>
typeof DOMException === "function"
? new DOMException("The request was canceled.", "AbortError")
: Object.assign(new Error("The request was canceled."), {
name: "AbortError",
});

/**
* Creates a cancelable fetch operation with an AbortController.
*
* This helper function wraps a request function with abort capability, allowing
* the request to be canceled at any time. If the request is aborted, it rejects
* with an `AbortError` (the same reason the signal is aborted with). Otherwise, it
* resolves or rejects based on the original request function's behavior.
*
* @typeParam T - The type of data expected from the request.
* @param requestFn - The request function that accepts an AbortSignal.
* @returns An object containing:
* - `run`: Function to execute the request.
* - `cancel`: Function to abort the ongoing request.
*/
const buildCancelableFetch = <T>(
requestFn: (signal: AbortSignal) => Promise<T>
): { run: () => Promise<T>; cancel: () => void } => {
const abortController = new AbortController();
return {
run: () =>
new Promise<T>((resolve, reject) => {
requestFn(abortController.signal)
.then(resolve)
.catch((error) => {
if (abortController.signal.aborted) {
reject(abortController.signal.reason);
} else {
reject(error);
}
});
}),
cancel: () => abortController.abort(createAbortError()),
};
};

/**
* A custom React hook for managing sequential asynchronous requests with automatic cancellation.
*
* This hook ensures that only the most recent request is processed by automatically canceling
* any previous ongoing requests when a new request is initiated. This is particularly useful
* for handling rapid user interactions (like search inputs or button clicks) where only the
* latest request's result matters.
*
* When a new request is triggered while another is in progress, the previous request is
* immediately aborted using the AbortSignal API. This prevents race conditions and ensures
* that stale data doesn't override newer results.
*
* The hook also handles cleanup on component unmount, automatically canceling any pending
* requests to prevent memory leaks and unwanted state updates.
*
* @typeParam T - The type of data expected from the request.
* @param requestFn - The asynchronous request function
* that should accept an AbortSignal parameter for cancellation support. This function
* should handle the abort signal appropriately (e.g., pass it to fetch API).
* @returns A callback function that triggers the request. When called,
* it cancels any previous ongoing request and starts a new one. The returned promise
* resolves with the request result or rejects with an `AbortError` if canceled.
* Use `isAbortError` to tell a cancellation from a real failure.
*
* @example
* ```ts
* const searchUsers = useSequentialRequest(async (signal) => {
* const response = await fetch(`/api/users?query=${query}`, { signal });
* return response.json();
* });
*
* // In an event handler:
* const handleSearch = async () => {
* try {
* const results = await searchUsers();
* setResults(results);
* } catch (error) {
* if (!isAbortError(error)) {
* console.error("Search failed:", error);
* }
* }
* };
* ```
*
* @example
* ```ts
* const submitForm = useSequentialRequest(async (signal) => {
* const response = await fetch('/api/submit', {
* method: 'POST',
* body: JSON.stringify(formData),
* signal
* });
* return response.json();
* });
*
* // Only the last submission will complete
* await submitForm();
* ```
*
* For a live, editable example, see the [useSequentialRequest docs page](https://altalyst-solutions.github.io/hookify/hooks/use-sequential-request).
*/
export const useSequentialRequest = <T>(
requestFn: (signal: AbortSignal) => Promise<T>
): (() => Promise<T>) => {
const requestFnRef = useLatest(requestFn);
const currentRequest = useRef<{ cancel: () => void } | null>(null);

useEffect(() => {
return () => {
if (currentRequest.current) {
currentRequest.current.cancel();
}
};
}, []);

/**
* Executes the request function, canceling any previous ongoing request.
*
* @returns A promise that resolves with the request result or rejects
* with an `AbortError` if the request is canceled.
*/
return useCallback(async () => {
if (currentRequest.current) {
currentRequest.current.cancel();
}

const { run, cancel } = buildCancelableFetch(requestFnRef.current);
currentRequest.current = { cancel };

try {
return await run();
} finally {
if (currentRequest.current?.cancel === cancel) {
currentRequest.current = null;
}
}
}, [requestFnRef]);
};