← Cloudflare Workers / workers / runtime-apis / nodejs

AsyncLocalStorage

Cloudflare Workers poskytuje implementaci podmnožiny Node.js AsyncLocalStorage ↗ API pro vytváření úložišť v paměti, která zůstávají konzistentní i během asynchronních operací.

import { AsyncLocalStorage } from "node:async_hooks";

const asyncLocalStorage = new AsyncLocalStorage();

• new AsyncLocalStorage() : AsyncLocalStorage
  • Vrátí nový AsyncLocalStorage instance.

• getStore() : any

  • Vrátí aktuální store. Pokud je zavoláno mimo asynchronní kontext inicializovaný voláním asyncLocalStorage.run(), vrátí undefined.

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

  • Synchronně spustí funkci v rámci kontextu a vrátí její návratovou hodnotu. Úložiště není přístupné mimo callback funkci. Úložiště je přístupné jakýmkoli asynchronním operacím vytvořeným uvnitř callbacku. Volitelný args se předávají do callback funkce. Pokud callback funkce vyvolá chybu, tuto chybu vyvolá run() také.

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

  • Synchronně spustí funkci mimo kontext a vrátí její návratovou hodnotu. Tato metoda je ekvivalentní volání run() hodnotou store hodnota nastavena na undefined.

• AsyncLocalStorage.bind(fn) : function

  • Zachytí asynchronní kontext, který je aktuální ve chvíli, kdy bind() je volána a vrací funkci, která před voláním předané funkce vstoupí do daného kontextu.

• AsyncLocalStorage.snapshot() : function

  • Zachytí asynchronní kontext, který je aktuální ve chvíli, kdy snapshot() je volána a vrací funkci, která před voláním dané funkce vstoupí do daného kontextu.

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 podporuje více AsyncLocalStorage instance, které lze používat souběžně.

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

Když je Promise je odmítnut a odmítnutí není zpracováno, asynchronní kontext se propaguje do 'unhandledrejection' obslužná rutina události:

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 ↗ třída je součástí Node.js API pro sledování asynchronního kontextu, které uživatelům umožňuje vytvářet vlastní asynchronní kontexty. Objekty, které dědí z AsyncResource dokážou šířit asynchronní kontext podobně jako promises.

Upozorňujeme, že AsyncLocalStorage.snapshot() a AsyncLocalStorage.bind() poskytují lepší přístup. AsyncResource je poskytováno výhradně kvůli zpětné kompatibilitě s 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

  • Vrátí nový AsyncResource. Je důležité mít na paměti, že argumenty konstruktoru jsou v implementaci Node.js vyžadovány pro AsyncResource, ve Workers se nepoužívají.
• AsyncResource.bind(fnfunction, typestring, thisArgany)
  • Sváže danou funkci s aktuálním asynchronním kontextem.

• asyncResource.bind(fnfunction, thisArgany)
  • Sváže danou funkci s asynchronním kontextem přidruženým k tomuto AsyncResource.
• asyncResource.runInAsyncScope(fnfunction, thisArgany, ...argsarguments)
  • Zavolá poskytnutou funkci se zadanými argumenty v asynchronním kontextu přidruženém k tomuto AsyncResource.

• AsyncLocalStorage implementace poskytovaná Workers záměrně vynechává podporu pro asyncLocalStorage.enterWith() ↗ a asyncLocalStorage.disable() ↗ metody.

• Workers neimplementuje celé async_hooks ↗ API, na němž je založena implementace AsyncLocalStorage se sestavuje.

• Workers neimplementuje možnost vytvořit AsyncResource s explicitně určeným kontextem spouštěče, jak to umožňuje Node.js. To znamená, že nové AsyncResource bude vždy svázán s asynchronním kontextem, ve kterém byl vytvořen.

• Thenables (objekty, které nejsou Promise a vystavují then() metoda) nejsou plně podporovány při použití AsyncLocalStorage. Při práci s thenables místo toho použijte AsyncLocalStorage.snapshot() ↗ pro zachycení snímku aktuálního kontextu.