Cloudflare Docs
Workers
Cloudflare Docs
Workers
GitHub icon
Edit this page on GitHub
Set theme to dark (⇧+D)
  1. Products
  2. Workers
  3. ...
  4. Node.js compatibility
  5. AsyncLocalStorage

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

import { AsyncLocalStorage } from 'node:async_hooks';



const asyncLocalStorage = new AsyncLocalStorage();

  • new AsyncLocalStorage() : AsyncLocalStorage

    • Returns a new AsyncLocalStorage instance.

​​ Methods

  • getStore() : any

    • Returns the current store. If called outside of an asynchronous context initialized by calling asyncLocalStorage.run(), it returns undefined.

  • 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 args are passed to the callback function. If the callback function throws an error, the error is thrown by run() also.

  • 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 the store value set to undefined.

​​ 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.

  • 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.

​​ Examples

​​ Fetch Listener

import { AsyncLocalStorage } from 'node:async_hooks';



const asyncLocalStorage = new AsyncLocalStorage();

let idSeq = 0;



export default {
  async fetch(req) {
    return asyncLocalStorage.run(idSeq++, () => {
      // Simulate some async activity...
      await scheduler.wait(1000);
      return new Response(asyncLocalStorage.getStore());
    });
  }

};

​​ Multiple stores

The API supports multiple AsyncLocalStorage instances to be used concurrently.

import { AsyncLocalStorage } from 'node:async_hooks';



const als1 = new AsyncLocalStorage();

const als2 = new AsyncLocalStorage();



export default {
  async fetch(req) {
    return als1.run(123, () => {
      return als2.run(321, () => {
        // Simulate some async activity...
        await scheduler.wait(1000);
        return new Response(`${als1.getStore()}-${als2.getStore()}`);
      });
    });
  }

};

​​ Unhandled Rejections

When a Promise rejects and the rejection is unhandled, the async context propagates to the 'unhandledrejection' event handler:

import { AsyncLocalStorage } from 'node:async_hooks';



const asyncLocalStorage = new AsyncLocalStorage();

let idSeq = 0;



addEventListener('unhandledrejection', (event) => {
  console.log(asyncLocalStorage.getStore(), 'unhandled rejection!');

});



export default {
  async fetch(req) {
    return asyncLocalStorage.run(idSeq++, () => {
      // Cause an unhandled rejection!
      throw new Error('boom');
    });
  }

};

​​ AsyncLocalStorage.bind() and AsyncLocalStorage.snapshot()

import { AsyncLocalStorage } from 'node:async_hooks';



const als = new AsyncLocalStorage();



function foo() { console.log(als.getStore()); }

function bar() { console.log(als.getStore()); }



const oneFoo = als.run(123, () => AsyncLocalStorage.bind(foo));

oneFoo(); // prints 123



const snapshot = als.run('abc', () => AsyncLocalStorage.snapshot());

snapshot(foo); // prints 'abc'

snapshot(bar); // prints 'abc'

import { AsyncLocalStorage } from 'node:async_hooks';



const als = new AsyncLocalStorage();



class MyResource {
  #runInAsyncScope = AsyncLocalStorage.snapshot();


  doSomething() {
    this.#runInAsyncScope(() => {
      return als.getStore();
    });
  }

};



const myResource = als.run(123, () => new MyResource());
console.log(myResource.doSomething()); // prints 123

​​ 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

import { AsyncResource, AsyncLocalStorage } from 'node:async_hooks';



const als = new AsyncLocalStorage();



class MyResource extends AsyncResource {
  constructor() {
    // The type string is required by Node.js but unused in Workers.
    super('MyResource');
  }


  doSomething() {
    this.runInAsyncScope(() => {
      return als.getStore();
    });
  }

};



const myResource = als.run(123, () => new MyResource());
console.log(myResource.doSomething()); // prints 123

  • new AsyncResource(typestring, optionsAsyncResourceOptions) : AsyncResource

    • Returns a new AsyncResource. Importantly, while the constructor arguments are required in Node.js’ implementation of AsyncResource, they are not used in Workers.

  • 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.

  • asyncResource.runInAsyncScope(fnfunction, thisArgany, …argsarguments)

    • Call the provided function with the given arguments in the async context associated with this AsyncResource.

​​ Caveats