Workers runtime supports Node.js API compatibility
The Workers runtime features are compatible with a subset of Node.js APIs. Developers can set a compatibility date or compatibility flag to control which APIs are available.
Cloudflare Workers · Runtime APIs · all subjects
runtime
283 notes in this subject, read out of this brain and free to use. This is page 1 of 5.
Workers runtime is JavaScript standards compliant
The Workers runtime is designed to be JavaScript standards compliant and web-interoperable. It uses web platform APIs wherever possible, so code can be reused across client and server, as well as across WinterCG JavaScript runtimes.
close event behavior in Workers MessageChannel
The 'close' event will be emitted on both ports when one of the ports is closed. However, it will not be emitted when the Worker is terminated or when one of the ports is garbage collected.
MessageChannel supported message values
Any value that can be used with the structuredClone(...) API can be sent over a MessageChannel port.
messageerror event partial support in Workers
The 'messageerror' event is only partially supported in the Workers MessageChannel implementation. If the 'onmessage' handler throws an error, the 'messageerror' event will be triggered. However, it will not be triggered when there are errors serializing or deserializing the message data. Instead, the error will be thrown when the postMessage method is called on the sending port.
MessagePort is not serializable in Workers
The MessagePort is not serializable in the Workers runtime. This means you cannot send a MessagePort object through the postMessage method or via JSRPC calls.
MessageChannel basic usage example
const { port1, port2 } = new MessageChannel(); port2.onmessage = (event) => { console.log('Received message:', event.data); }; port2.postMessage('Hello from port2!');
MessageChannel API availability and scope
The Workers runtime provides a minimal implementation of the MessageChannel API. It is currently limited to uses with a single Worker instance, meaning you can use MessageChannel to send messages between different parts of your Worker, but not across different Workers.
MessageChannel transfer lists not supported
Transfer lists are not supported in the Workers MessageChannel implementation. You will not be able to transfer ownership of objects like ArrayBuffer or MessagePort between ports.
uncaughtException event not implemented in Workers
The 'uncaughtException' event on the process object, which exists in Node.js, is currently not implemented in the Cloudflare Workers runtime. Always add an 'error' listener to EventEmitter instances rather than relying on process-level exception handling.
EventEmitter available in Workers runtime
The EventEmitter class from Node.js is available in Cloudflare Workers via the 'node:events' module. It can be imported with: import { EventEmitter } from 'node:events';
EventEmitter basic usage - on and emit methods
EventEmitter provides on() method to register event listeners and emit() method to trigger events. Example: const emitter = new EventEmitter(); emitter.on('hello', (...args) => { console.log(...args); }); emitter.emit('hello', 1, 2, 3); will log '1 2 3'.
EventEmitter captureRejections option
EventEmitter supports the captureRejections option, which when set to true, improves handling of async functions as event handlers by emitting promise rejections as 'error' events. Example: new EventEmitter({ captureRejections: true }) will cause async function rejections to be emitted as 'error' events rather than becoming unhandled promise rejections.
EventEmitter full API support
The Workers runtime supports the entire Node.js EventEmitter API, including all methods and options documented in the Node.js EventEmitter class.
EventEmitter error event behavior
When an 'error' event is emitted on an EventEmitter and there is no listener for it, the error will be immediately thrown. It is strongly recommended to always add an 'error' listener to any EventEmitter instance.
ok assertion in Workers
ok(value) asserts that a value is truthy. ok(true) passes, but ok(false) fails and throws AssertionError.
assert strict mode in Workers
In the Workers implementation of assert, all assertions run in strict assertion mode as defined by Node.js. In strict mode, non-strict methods behave like their corresponding strict methods. For example, deepEqual() behaves like deepStrictEqual().
doesNotReject assertion in Workers
doesNotReject(asyncFn) is an async function that asserts an async function does not reject. await doesNotReject(async () => {}) passes, but await doesNotReject(async () => { throw new Error("boom"); }) fails and throws AssertionError.
deepStrictEqual assertion in Workers
deepStrictEqual(value1, value2) performs a deep strict equality check on objects. deepStrictEqual({ a: { b: 1 } }, { a: { b: 1 } }) passes, but deepStrictEqual({ a: { b: 1 } }, { a: { b: 2 } }) fails and throws AssertionError.
strictEqual assertion in Workers
strictEqual(value1, value2) performs a strict equality check. strictEqual(1, 1) passes, but strictEqual(1, "1") fails and throws AssertionError.
node:assert module available in Workers
The Node.js assert module is available in Cloudflare Workers and provides useful assertions for testing. It can be imported using `import { strictEqual, deepStrictEqual, ok, doesNotReject } from "node:assert"`.
Buffer.toString() method with encoding
The toString() method on a Buffer instance accepts an encoding parameter to convert buffer contents to a string. Supported encodings include 'hex' and 'base64'.
Buffer memory allocation differences in Workers vs Node.js
The Workers implementation of Buffer does not use a global memory pool like Node.js. All Buffer instances are allocated independently instead of being allocated from a shared pool.
Buffer.allocUnsafe() not supported in Workers
The Buffer.allocUnsafe() method is not supported in Cloudflare Workers. All Buffer instances in Workers are always initialized and filled with null bytes (0x00) when allocated.
Buffer usage with streams
Buffer can be used when interacting with streams. A Buffer instance can be written to a writable stream using writer.write(Buffer.from('hello world')).
Buffer compatibility with Response API
Buffer can be used in any Workers API that accepts Uint8Array, such as creating a new Response with Buffer.from(). Example: new Response(Buffer.from('hello world')).
Example: Buffer hex and base64 encoding
```js import { Buffer } from "node:buffer"; const buf = Buffer.from("hello world", "utf8"); console.log(buf.toString("hex")); // Prints: 68656c6c6f20776f726c64 console.log(buf.toString("base64")); // Prints: aGVsbG8gd29ybGQ= ``` This example shows how to create a Buffer from a string and convert it to hex and base64 representations.
Buffer.from() with encoding parameter
Buffer.from() accepts a string and an encoding parameter. Example: Buffer.from('hello world', 'utf8') creates a buffer from a UTF-8 encoded string.
Buffer encoding and decoding capabilities
The Buffer API provides built-in base64 and hex encoding/decoding, byte-order manipulation, and encoding-aware substring searching.
Buffer API availability in Workers
The Node.js Buffer API is available in Cloudflare Workers for manipulating binary data. Every Buffer instance extends from the standard Uint8Array class.
node:crypto FIPS mode limitation
It is not possible to manually enable or disable FIPS mode when using node:crypto in Cloudflare Workers.
node:crypto unsupported functions
The generateKeyPair and generateKeyPairSync functions do not support DSA or DH key pairs in Cloudflare Workers.
node:crypto module support in Workers
The node:crypto module provides cryptographic functionality including wrappers for OpenSSL's hash, HMAC, cipher, decipher, sign, and verify functions. All node:crypto APIs are fully supported in Cloudflare Workers with specific exceptions.
node:crypto unsupported curves
The ed448 and x448 curves are not supported in the node:crypto module when used in Cloudflare Workers.
WebCrypto API alternative
The WebCrypto API is available within Cloudflare Workers and does not require the nodejs_compat compatibility flag.
AsyncLocalStorage in fetch handler example
Example showing AsyncLocalStorage usage in a fetch handler: ```js 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()); }); } }; ```
AsyncLocalStorage.disable() not supported
The asyncLocalStorage.disable() method is not supported in Cloudflare Workers.
AsyncLocalStorage.snapshot() static method
The AsyncLocalStorage.snapshot() static method captures the asynchronous context that is current when snapshot() is called and returns a function that enters that context before calling a given function.
AsyncResource usage example
Example showing AsyncResource usage: ```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 ```
AsyncLocalStorage.exit() method
The exit(callback, ...args) method 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.
AsyncResource explicit trigger context not supported
Workers does not implement the ability to create an AsyncResource with an explicitly identified trigger context as allowed by Node.js. This means that a new AsyncResource will always be bound to the async context in which it was created.
Thenables not fully supported with AsyncLocalStorage
Thenables (non-Promise objects that expose a then() method) are not fully supported when using AsyncLocalStorage. When working with thenables, instead use AsyncLocalStorage.snapshot() to capture a snapshot of the current context.
AsyncLocalStorage.run() method
The run(store, callback, ...args) method 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.
AsyncLocalStorage constructor
The AsyncLocalStorage constructor is called with no arguments: `new AsyncLocalStorage()` returns a new AsyncLocalStorage instance.
AsyncLocalStorage import
AsyncLocalStorage is imported from the 'node:async_hooks' module in Cloudflare Workers: `import { AsyncLocalStorage } from 'node:async_hooks';`
Full async_hooks API not implemented
Workers does not implement the full async_hooks API upon which Node.js' implementation of AsyncLocalStorage is built.
asyncResource.bind() instance method
The asyncResource.bind(fn, thisArg) instance method binds the given function to the async context associated with this AsyncResource.
AsyncResource.bind() static method
The AsyncResource.bind(fn, type, thisArg) static method binds the given function to the current async context.
AsyncResource constructor
The AsyncResource constructor is called with `new AsyncResource(type, options)` and returns a new AsyncResource instance. While the constructor arguments are required in Node.js' implementation of AsyncResource, they are not used in Workers.
AsyncResource class
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. However, AsyncLocalStorage.snapshot() and AsyncLocalStorage.bind() provide a better approach. AsyncResource is provided solely for backwards compatibility with Node.js.
AsyncLocalStorage.snapshot() in class example
Example showing AsyncLocalStorage.snapshot() usage in a class: ```js 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 ```
AsyncLocalStorage.bind() example
Example showing AsyncLocalStorage.bind() usage: ```js 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' ```
Async context propagation to unhandledrejection event
When a Promise rejects and the rejection is unhandled, the async context propagates to the 'unhandledrejection' event handler, allowing access to the store via getStore() within that handler.
AsyncLocalStorage.getStore() method
The getStore() method returns the current store. If called outside of an asynchronous context initialized by calling asyncLocalStorage.run(), it returns undefined.
Multiple AsyncLocalStorage instances
The API supports multiple AsyncLocalStorage instances to be used concurrently. Example: ```js 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()}`); }); }); } }; ```
AsyncLocalStorage.bind() static method
The AsyncLocalStorage.bind(fn) static method 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.
asyncResource.runInAsyncScope() method
The asyncResource.runInAsyncScope(fn, thisArg, ...args) method calls the provided function with the given arguments in the async context associated with this AsyncResource.
AsyncLocalStorage.enterWith() not supported
The asyncLocalStorage.enterWith() method is not supported in Cloudflare Workers.
Channel instances are singletons
All Channel instances are singletons per each Isolate/context (for example, the same entry point).
Creating and publishing to a diagnostics channel
To publish messages to a channel, acquire a channel object using channel('channel-name'), then call publish() with any JavaScript value. Example: const myChannel = channel('my-channel'); myChannel.publish({ foo: 'bar' });