What is @azure/abort-controller?
The @azure/abort-controller npm package provides a way to use AbortController and AbortSignal, which are interfaces for abortable operations, in the Azure SDKs. These are particularly useful for cancelling asynchronous operations in JavaScript, such as network requests or long-running processes.
What are @azure/abort-controller's main functionalities?
Creating an AbortController and AbortSignal
This feature allows you to create an instance of AbortController and retrieve its AbortSignal. The signal can then be passed to operations that support cancellation.
const { AbortController } = require('@azure/abort-controller');
const controller = new AbortController();
const signal = controller.signal;
Aborting an operation
This feature enables you to abort an operation by calling the `abort` method on the controller. Any operation listening to the associated signal will be cancelled.
controller.abort();
Listening for an abort signal
This feature allows you to listen for an abort event on the AbortSignal. This is useful for performing cleanup or rollback actions when an operation is cancelled.
signal.addEventListener('abort', () => {
console.log('Operation aborted!');
});
Other packages similar to @azure/abort-controller
abort-controller
The 'abort-controller' package provides a similar API for creating abortable operations using AbortController and AbortSignal. It is a polyfill for the AbortController interface that works in both web browsers and Node.js environments. Compared to @azure/abort-controller, it is not specific to Azure SDKs and can be used in a wider range of applications.
Azure Abort Controller client library for JavaScript
The @azure/abort-controller
package provides AbortController
and AbortSignal
classes. These classes are compatible
with the AbortController built into modern browsers
and the AbortSignal
used by fetch.
Use the AbortController
class to create an instance of the AbortSignal
class that can be used to cancel an operation
in an Azure SDK that accept a parameter of type AbortSignalLike
.
Getting started
Installation
Install this library using npm as follows
npm install @azure/abort-controller
Key Concepts
Use the AbortController
to create an AbortSignal
which can then be passed to Azure SDK operations to cancel
pending work. The AbortSignal
can be accessed via the signal
property on an instantiated AbortController
.
An AbortSignal
can also be returned directly from a static method, e.g. AbortController.timeout(100)
.
that is cancelled after 100 milliseconds.
Calling abort()
on the instantiated AbortController
invokes the registered abort
event listeners on the associated AbortSignal
.
Any subsequent calls to abort()
on the same controller will have no effect.
The AbortSignal.none
static property returns an AbortSignal
that can not be aborted.
Multiple instances of an AbortSignal
can be linked so that calling abort()
on the parent signal,
aborts all linked signals.
This linkage is one-way, meaning that a parent signal can affect a linked signal, but not the other way around.
To link AbortSignals
together, pass in the parent signals to the AbortController
constructor.
Examples
The below examples assume that doAsyncWork
is a function that takes a bag of properties, one of which is
of the abort signal.
Example 1 - basic usage
import { AbortController } from "@azure/abort-controller";
const controller = new AbortController();
doAsyncWork({ abortSignal: controller.signal });
controller.abort();
Example 2 - Aborting with timeout
import { AbortController } from "@azure/abort-controller";
const signal = AbortController.timeout(1000);
doAsyncWork({ abortSignal: signal });
Example 3 - Aborting sub-tasks
import { AbortController } from "@azure/abort-controller";
const allTasksController = new AbortController();
const subTask1 = new AbortController(allTasksController.signal);
const subtask2 = new AbortController(allTasksController.signal);
allTasksController.abort();
subTask1.abort();
Example 4 - Aborting with parent signal or timeout
import { AbortController } from "@azure/abort-controller";
const allTasksController = new AbortController();
const subTask = new AbortController(allTasksController.signal, AbortController.timeout(100));
allTasksController.abort();
subTask.abort();
Next steps
You can build and run the tests locally by executing rushx test
. Explore the test
folder to see advanced usage and behavior of the public classes.
Troubleshooting
If you run into issues while using this library, please feel free to file an issue.
Contributing
If you'd like to contribute to this library, please read the contributing guide to learn more about how to build and test the code.