← Cloudflare Workers / workers / runtime-apis / nodejs

AsyncLocalStorage

Cloudflare Workers предоставляет реализацию подмножества Node.js AsyncLocalStorage ↗ API для создания хранилищ в памяти, которые остаются согласованными при выполнении асинхронных операций.

import { AsyncLocalStorage } from "node:async_hooks";

const asyncLocalStorage = new AsyncLocalStorage();

• new AsyncLocalStorage() : AsyncLocalStorage
  • Возвращает новый AsyncLocalStorage инстанс.

• getStore() : any

  • Возвращает текущее хранилище. Если вызвана вне асинхронного контекста, инициализированного вызовом asyncLocalStorage.run(), он возвращает undefined.

• run(storeany, callbackfunction, ...argsarguments) : any

  • Синхронно выполняет функцию в рамках контекста и возвращает её результат. Хранилище недоступно за пределами функции обратного вызова. Хранилище доступно любым асинхронным операциям, созданным внутри этой функции. Необязательный args передаются в функцию обратного вызова. Если функция обратного вызова выбрасывает ошибку, эта ошибка выбрасывается run() также.

• exit(callbackfunction, ...argsarguments) : any

  • Синхронно выполняет функцию вне контекста и возвращает её результат. Этот метод эквивалентен вызову run() на store значение, равное undefined.

• AsyncLocalStorage.bind(fn) : function

  • Захватывает асинхронный контекст, который является текущим в момент, когда bind() вызывается и возвращает функцию, которая входит в этот контекст перед вызовом переданной функции.

• AsyncLocalStorage.snapshot() : function

  • Захватывает асинхронный контекст, который является текущим в момент, когда snapshot() вызывается и возвращает функцию, которая входит в этот контекст перед вызовом заданной функции.

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());
    });
  }
};

API поддерживает несколько AsyncLocalStorage экземпляров для одновременного использования.

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()}`);
      });
    });
  }
};

Когда Promise отклоняется и это отклонение остаётся необработанным, асинхронный контекст передаётся в 'unhandledrejection' обработчик события:

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");
		});
	},
};

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 ↗ класс является частью API отслеживания асинхронного контекста Node.js, который позволяет создавать собственные асинхронные контексты. Объекты, расширяющие AsyncResource способны передавать асинхронный контекст почти так же, как promises.

Обратите внимание, что AsyncLocalStorage.snapshot() и AsyncLocalStorage.bind() предлагают более удачный подход. AsyncResource предоставляется исключительно для обратной совместимости с Node.js.

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

  • Возвращает новый AsyncResource. Обратите внимание, что в реализации Node.js аргументы конструктора обязательны для AsyncResource, они не используются в Workers.
• AsyncResource.bind(fnfunction, typestring, thisArgany)
  • Привязывает переданную функцию к текущему асинхронному контексту.

• asyncResource.bind(fnfunction, thisArgany)
  • Привязывает переданную функцию к асинхронному контексту, связанному с этим AsyncResource.
• asyncResource.runInAsyncScope(fnfunction, thisArgany, ...argsarguments)
  • Вызывает переданную функцию с указанными аргументами в асинхронном контексте, связанном с этим AsyncResource.

• AsyncLocalStorage реализация, предоставляемая Workers, намеренно не поддерживает asyncLocalStorage.enterWith() ↗ и asyncLocalStorage.disable() ↗ методы.

• Workers не реализует полную версию async_hooks ↗ API, на основе которого реализация Node.js для AsyncLocalStorage собран.

• Workers не реализует возможность создания AsyncResource с явно указанным контекстом триггера, как это допускает Node.js. Это означает, что новый AsyncResource всегда привязан к асинхронному контексту, в котором он был создан.

• Thenable-объекты (объекты, не являющиеся Promise, но предоставляющие then() метод) не полностью поддерживаются при использовании AsyncLocalStorage. При работе с thenable-объектами вместо этого используйте AsyncLocalStorage.snapshot() ↗ чтобы сделать снимок текущего контекста.