cancellation-context
Promise-cancellation made easy. Cancel one or more promises in a given context.
Install
npm i cancellation-context
Usage
Create a new context by calling the exported factory function.
const CancellationContext = ;const context = ;
Once you have a context, you can create new "cancellable-promise" instances within that context by calling context.Cancellable
with promise-thunk factory.
Note: Promises are eager by design and don't naturally lend themselve to cancellation. As such, arbitrary promises are not cancellable and the onus is the author to write cancellable promise implementations. No library, including this one, will be able to solve for that unless there are some fundamental changes to the JavaScript spec.
The cancellation-context
library attempts to make the authoring of cancellable-promises as easy as possible by designing around the idea of promise-thunks.
The recommended pattern is as follows:
CancellableFactory = ({{ ...args }}) => onCancel => {{ promise }};
For example...
const context = require('cancellation-context')();
const MyCancellableFactory = msg => onCancel => new Promise((resolve, reject) => {
const t = setTimeout(() => resolve(msg), 1000);
onCancel(reason => {
clearTimeout(t);
resolve(reason);
});
});
(async () => {
const myCancellable = context.Cancellable(MyCancellableFactory('success!'));
setTimeout(() => myCancellable.cancel('cancelled!'), 500);
console.log(await myCancellable); // => 'cancelled!'
})();
By leveraging a thunk pattern, you can maintain composability while supporting the need for an onCancel
hook.
API
cancellation-context
- cancellation-context
- module.exports ⇒
CancellationContext
⏏- ~CancellationContext
- ~CancellationError
- ~TimeoutError
- ~Cancellable(PromiseThunkFactory) ⇒
CancellablePromise
- ~Perishable(PromiseThunkFactory) ⇒
PerishablePromise
- ~cancel(promise, reason) ⇒
void
- ~cancelAll(reason) ⇒
void
- ~delay(ms) ⇒
function
- ~timeout(ms) ⇒
function
- ~CancellableDelay(ms) ⇒
function
- ~CancellableTimeout(ms) ⇒
function
- ~PerishableTimeout(ms, ttl) ⇒
function
- ~PerishableDelay(ms, ttl) ⇒
function
- module.exports ⇒
CancellationContext
⏏
module.exports ⇒ Factory function for creating CancellationContext instances.
module.exports~CancellationContext
Kind: inner class of module.exports
See: CancellationContextFactory
new CancellationContext()
CancellationContext
is a private class. Use exported CancellationContextFactory
function for instantiation.
module.exports~CancellationError
Kind: inner class of module.exports
Implements: Error
new CancellationError()
An error class used for indicating cancellation events.
module.exports~TimeoutError
Kind: inner class of module.exports
Implements: Error
new TimeoutError()
An error class used for indicating timeout events.
CancellablePromise
module.exports~Cancellable(PromiseThunkFactory) ⇒ Given a PromiseThunkFactory which accepts on onCancel
hook, returns a CancellablePromise.
Kind: inner method of module.exports
Returns: CancellablePromise
- A CancellablePromise
is a promise with an additional cancel
method attached.
Param | Type |
---|---|
PromiseThunkFactory | function |
PerishablePromise
module.exports~Perishable(PromiseThunkFactory) ⇒ Given a PromiseThunkFactory which accepts on onCancel
hook, returns a PerishablePromise.
Kind: inner method of module.exports
Returns: PerishablePromise
- A PerishablePromise
is a CancellablePromise
which will be automatically cancelled after a specified amount of time.
Param | Type |
---|---|
PromiseThunkFactory | function |
void
module.exports~cancel(promise, reason) ⇒ Given promise
and reason
calls canceller on promise
with reason
.
Kind: inner method of module.exports
Param | Type | Description |
---|---|---|
promise | Promise |
CancellablePromise to be cancelled |
reason | 'string' | 'Error' |
reason for cancellation |
void
module.exports~cancelAll(reason) ⇒ Calls cancel
method with reason
on every CancellablePromise associated with the context instance.
Kind: inner method of module.exports
Param | Type | Description |
---|---|---|
reason | 'string' | 'Error' |
reason for cancellation |
function
module.exports~delay(ms) ⇒ A cancellable delay implementation which resolves after given number of milliseconds.
Kind: inner method of module.exports
Returns: function
- Returns function which accepts onCancel
hook.
Param | Type | Description |
---|---|---|
ms | number |
Number of milliseconds to wait |
Example
const cancellableDelay = context;;await cancellableDelay;
function
module.exports~timeout(ms) ⇒ A cancellable timeout implementation which resolves after given number of milliseconds.
Kind: inner method of module.exports
Returns: function
- Returns function which accepts onCancel
hook.
Param | Type | Description |
---|---|---|
ms | number |
Number of milliseconds to wait |
Example
const cancellableTimeout = context;;await cancellableTimeout;
function
module.exports~CancellableDelay(ms) ⇒ A CancellableFactory which resolves after given number of milliseconds.
Kind: inner method of module.exports
Returns: function
- Returns function which accepts onCancel
hook.
Param | Type | Description |
---|---|---|
ms | number |
Number of milliseconds to wait |
Example
const cancellableDelay = context);;await cancellableDelay;
function
module.exports~CancellableTimeout(ms) ⇒ A CancellableFactory which rejects after given number of milliseconds.
Kind: inner method of module.exports
Returns: function
- Returns function which accepts onCancel
hook.
Param | Type | Description |
---|---|---|
ms | number |
Number of milliseconds to wait |
Example
const cancellableTimeout = context);;await cancellableTimeout;
function
module.exports~PerishableTimeout(ms, ttl) ⇒ A PerishableFactory which rejects after given number of milliseconds.
Kind: inner method of module.exports
Returns: function
- Returns function which accepts onCancel
hook.
Param | Type | Description |
---|---|---|
ms | number |
Number of milliseconds to wait |
ttl | number |
Number of milliseconds until cancelled |
Example
const cancellableTimeout = context;await cancellableTimeout;
function
module.exports~PerishableDelay(ms, ttl) ⇒ A PerishableFactory which resolves after given number of milliseconds.
Kind: inner method of module.exports
Returns: function
- Returns function which accepts onCancel
hook.
Param | Type | Description |
---|---|---|
ms | number |
Number of milliseconds to wait |
ttl | number |
Number of milliseconds until cancelled |
Example
const cancellableDelay = context;await cancellableDelay;
Examples
Cancellable Delay
const context = ; async { try const ttl = 1000; // try increasing to 10000 console; catch e console; };
Manual Cancellation
const context = ; const sleep = { return { const t = ; ; };}; async { try const promise = context; const handle = ; // try increasing to 10000 console; ; catch e console; };
Async Iterables
const context = ; async { { while true const promises = context context context ; await Promiseallpromises; } ; try for await const result of console; catch e context; console; };