AsyncLocalStorage
Background
Cloudflare Workers provides an implementation of a subset of the Node.js
AsyncLocalStorage API for creating in-memory stores that remain coherent through asynchronous operations.
Constructor
-
new AsyncLocalStorage():AsyncLocalStorage- Returns a new
AsyncLocalStorageinstance.
- Returns a new
Methods
-
getStore():any- Returns the current store. If called outside of an asynchronous context initialized by calling
asyncLocalStorage.run(), it returnsundefined.
- Returns the current store. If called outside of an asynchronous context initialized by calling
-
run(storeany, callbackfunction, …argsarguments):any- Runs a function synchronously within a context and returns its return value. The store is not accessible outside of the callback function. The store is accessible to any asynchronous operations created within the callback. The optional
argsare passed to the callback function. If the callback function throws an error, the error is thrown byrun()also.
- Runs a function synchronously within a context and returns its return value. The store is not accessible outside of the callback function. The store is accessible to any asynchronous operations created within the callback. The optional
-
exit(callbackfunction, …argsarguments):any- Runs a function synchronously outside of a context and returns its return value. This method is equivalent to calling
run()with thestorevalue set toundefined.
- Runs a function synchronously outside of a context and returns its return value. This method is equivalent to calling
Static Methods
-
AsyncLocalStorage.bind(fn):function- Captures the asynchronous context that is current when
bind()is called and returns a function that enters that context before calling the passed in function.
- Captures the asynchronous context that is current when
-
AsyncLocalStorage.snapshot():function- Captures the asynchronous context that is current when
snapshot()is called and returns a function that enters that context before calling a given function.
- Captures the asynchronous context that is current when
Examples
Fetch Listener
Multiple stores
The API supports multiple AsyncLocalStorage instances to be used concurrently.
Unhandled Rejections
When a Promise rejects and the rejection is unhandled, the async context propagates to the 'unhandledrejection' event handler:
AsyncLocalStorage.bind() and AsyncLocalStorage.snapshot()
AsyncResource
The
AsyncResource class is a component of Node.js’ async context tracking API that allows users to create their own async contexts. Objects that extend from AsyncResource are capable of propagating the async context in much the same way as promises.
Note that AsyncLocalStorage.snapshot() and AsyncLocalStorage.bind() provide a better approach. AsyncResource is provided solely for backwards compatibility with Node.js.
Constructor
-
new AsyncResource(typestring, optionsAsyncResourceOptions):AsyncResource- Returns a new
AsyncResource. Importantly, while the constructor arguments are required in Node.js’ implementation ofAsyncResource, they are not used in Workers.
- Returns a new
-
AsyncResource.bind(fnfunction, typestring, thisArgany)- Binds the given function to the current async context.
Methods
-
asyncResource.bind(fnfunction, thisArgany)- Binds the given function to the async context associated with this
AsyncResource.
- Binds the given function to the async context associated with this
-
asyncResource.runInAsyncScope(fnfunction, thisArgany, …argsarguments)- Call the provided function with the given arguments in the async context associated with this
AsyncResource.
- Call the provided function with the given arguments in the async context associated with this
Caveats
-
The
AsyncLocalStorageimplementation provided by Workers intentionally omits support for theasyncLocalStorage.enterWith()andasyncLocalStorage.disable()methods. -
Workers does not implement the full
async_hooksAPI upon which Node.js’ implementation ofAsyncLocalStorageis built. -
Workers does not implement the ability to create an
AsyncResourcewith an explicitly identified trigger context as allowed by Node.js. This means that a newAsyncResourcewill always be bound to the async context in which it was created. -
Thenables (non-Promise objects that expose a
then()method) are not fully supported when usingAsyncLocalStorage. When working with thenables, instead useAsyncLocalStorage.snapshot()to capture a snapshot of the current context.