A simple cancellable promise implementation for JavaScript and TypeScript.
Read the announcement post for a full explanation. In particular, see the "Prior art" section for a comparison to existing cancellable promise libraries.
yarn add real-cancellable-promise
import { CancellablePromise } from 'real-cancellable-promise';
const cancellablePromise = new CancellablePromise(normalPromise, cancel);
cancellablePromise.cancel();
await cancellablePromise; // throws a Cancellation object that subclasses Error
The CancellablePromise constructor takes in a promise and a cancel function.
Your cancel function MUST cause promise to reject with a Cancellation object.
This will NOT work, your callbacks with still run:
new CancellablePromise(normalPromise, () => {});
How do I convert a normal Promise to a CancellablePromise?
export function cancellableFetch(
input: RequestInfo,
init: RequestInit = {}
): CancellablePromise<Response> {
const controller = new AbortController();
const promise = fetch(input, {
...init,
signal: controller.signal,
}).catch((e) => {
if (e.name === 'AbortError') {
throw new Cancellation();
}
// rethrow the original error
throw e;
});
return new CancellablePromise<Response>(promise, () => controller.abort());
}
// Use just like normal fetch:
const cancellablePromise = cancellableFetch(url, {
/* pass options here */
});
fetch with response handlingexport function cancellableFetch<T>(
input: RequestInfo,
init: RequestInit = {}
): CancellablePromise<T> {
const controller = new AbortController();
const promise = fetch(input, {
...init,
signal: controller.signal,
})
.then((response) => {
// Handle the response object however you want
if (!response.ok) {
throw new Error(`Fetch failed with status code ${response.status}.`);
}
if (response.headers.get('content-type')?.includes('application/json')) {
return response.json();
} else {
return response.text();
}
})
.catch((e) => {
if (e.name === 'AbortError') {
throw new Cancellation();
}
// rethrow the original error
throw e;
});
return new CancellablePromise<T>(promise, () => controller.abort());
}
export function cancellableAxios<T>(
config: AxiosRequestConfig
): CancellablePromise<T> {
const source = axios.CancelToken.source();
config = { ...config, cancelToken: source.token };
const promise = axios(config)
.then((response) => response.data)
.catch((e) => {
if (e instanceof axios.Cancel) {
throw new Cancellation();
}
// rethrow the original error
throw e;
});
return new CancellablePromise<T>(promise, () => source.cancel());
}
// Use just like normal axios:
const cancellablePromise = cancellableAxios({ url });
export function cancellableJQueryAjax<T>(
settings: JQuery.AjaxSettings
): CancellablePromise<T> {
const xhr = $.ajax(settings);
const promise = xhr.catch((e) => {
if (e.statusText === 'abort') throw new Cancellation();
// rethrow the original error
throw e;
});
return new CancellablePromise<T>(promise, () => xhr.abort());
}
// Use just like normal $.ajax:
const cancellablePromise = cancellableJQueryAjax({ url, dataType: 'json' });
CancellablePromise supports all the methods that the normal Promise object
supports, except Promise.any (ES2021). See the API
Reference for details.
React will give you a warning if you attempt to update a component's state after it has unmounted. This will happen if your component makes an API call but gets unmounted before the API call completes.
You can fix this by canceling the API call in the cleanup function of an effect.
function listBlogPosts(): CancellablePromise<Post[]> {
// call the API
}
export function Blog() {
const [posts, setPosts] = useState<Post[]>([]);
useEffect(() => {
const cancellablePromise = listBlogPosts()
.then(setPosts)
.catch(console.error);
// The promise will get canceled when the component unmounts
return cancellablePromise.cancel;
}, []);
return (
<div>
{posts.map((p) => {
/* ... */
})}
</div>
);
}
CodeSandbox: prevent setState after unmount
Sometimes API calls have parameters, like a search string entered by the user.
function searchUsers(searchTerm: string): CancellablePromise<User[]> {
// call the API
}
export function UserList() {
const [searchTerm, setSearchTerm] = useState('');
const [users, setUsers] = useState<User[]>([]);
// In a real app you should debounce the searchTerm
useEffect(() => {
const cancellablePromise = searchUsers(searchTerm)
.then(setUsers)
.catch(console.error);
// The old API call gets canceled whenever searchTerm changes. This prevents
// setUsers from being called with incorrect results if the API calls complete
// out of order.
return cancellablePromise.cancel;
}, [searchTerm]);
return (
<div>
<SearchInput searchTerm={searchTerm} onChange={setSearchTerm} />
{users.map((u) => {
/* ... */
})}
</div>
);
}
CodeSandbox: cancel the in-progress API call when query parameters change
The utility function buildCancellablePromise lets you capture every
cancellable operation in a multi-step process. In this example, if bigQuery is
canceled, each of the 3 API calls will be canceled (though some might have
already completed).
function bigQuery(userId: number): CancellablePromise<QueryResult> {
return buildCancellablePromise(async (capture) => {
const userPromise = api.user.get(userId);
const rolePromise = api.user.listRoles(userId);
const [user, roles] = await capture(
CancellablePromise.all([userPromise, rolePromise])
);
// User must be loaded before this query can run
const customer = await capture(api.customer.get(user.customerId));
return { user, roles, customer };
});
}
react-queryIf your query key changes and there's an API call in progress, react-query
will cancel the CancellablePromise automatically.
CodeSandbox: react-query integration
CancellationUsually, you'll want to ignore Cancellation objects that get thrown:
try {
await capture(cancellablePromise);
} catch (e) {
if (e instanceof Cancellation) {
// do nothing — the component probably just unmounted.
// or you could do something here it's up to you 😆
return;
}
// log the error or display it to the user
}
Sometimes you need to call an asynchronous function that doesn't support
cancellation. In this case, you can use pseudoCancellable:
const cancellablePromise = pseudoCancellable(normalPromise);
// Later...
cancellablePromise.cancel();
await cancellablePromise; // throws Cancellation object if promise did not already resolve
CancellablePromise.delayawait CancellablePromise.delay(1000); // wait 1 second
Browser: anything that's not Internet Explorer.
React Native / Expo: should work in any recent release. AbortController has been available since 0.60.
Node.js: 14+. AbortController is only available in Node 15+. Both require() (CommonJS) and import (ES modules) are supported without use of a transpiler or bundler.
MIT
See CONTRIBUTING.md.
Generated using TypeDoc