markz
On this page

Global objects

Stability: 2 - Stable

These objects are available in all modules.

The following variables may appear to be global but are not. They exist only in the scope of [CommonJS modules][]:

  • [__dirname][]
  • [__filename][]
  • [exports][]
  • [module][]
  • [require()][]

The objects listed here are specific to Node.js. There are [built-in objects][] that are part of the JavaScript language itself, which are also globally accessible.

__dirname

This variable may appear to be global but is not. See [__dirname][].

__filename

This variable may appear to be global but is not. See [__filename][].

Class: AbortController

A utility class used to signal cancelation in selected Promise-based APIs. The API is based on the Web API {AbortController}.

const ac = new AbortController();

ac.signal.addEventListener('abort', () => console.log('Aborted!'),
                           { once: true });

ac.abort();

console.log(ac.signal.aborted);  // Prints true

abortController.abort([reason])

  • reason {any} An optional reason, retrievable on the AbortSignal's reason property.

Triggers the abort signal, causing the abortController.signal to emit the 'abort' event.

abortController.signal

  • Type: {AbortSignal}

Class: AbortSignal

  • Extends: {EventTarget}

The AbortSignal is used to notify observers when the abortController.abort() method is called.

Static method: AbortSignal.abort([reason])

  • reason {any}
  • Returns: {AbortSignal}

Returns a new already aborted AbortSignal.

Static method: AbortSignal.timeout(delay)

  • delay {number} The number of milliseconds to wait before triggering the AbortSignal.

Returns a new AbortSignal which will be aborted in delay milliseconds.

Static method: AbortSignal.any(signals)

  • signals {Iterable} An iterable of {AbortSignal}s from which to compose a new {AbortSignal}.

Returns a new AbortSignal which will be aborted if any of the provided signals are aborted. Its [abortSignal.reason][] will be set to whichever one of the signals caused it to be aborted.

Event: 'abort'

The 'abort' event is emitted when the abortController.abort() method is called. The callback is invoked with a single object argument with a single type property set to 'abort':

const ac = new AbortController();

// Use either the onabort property...
ac.signal.onabort = () => console.log('aborted!');

// Or the EventTarget API...
ac.signal.addEventListener('abort', (event) => {
  console.log(event.type);  // Prints 'abort'
}, { once: true });

ac.abort();

The AbortController with which the AbortSignal is associated will only ever trigger the 'abort' event once. We recommended that code check that the abortSignal.aborted attribute is false before adding an 'abort' event listener.

Any event listeners attached to the AbortSignal should use the { once: true } option (or, if using the EventEmitter APIs to attach a listener, use the once() method) to ensure that the event listener is removed as soon as the 'abort' event is handled. Failure to do so may result in memory leaks.

abortSignal.aborted

  • Type: {boolean}

True after the AbortController has been aborted.

abortSignal.onabort

  • Type: {Function}

An optional callback function that may be set by user code to be notified when the abortController.abort() function has been called.

abortSignal.reason

  • Type: {any}

An optional reason specified when the AbortSignal was triggered.

const ac = new AbortController();
ac.abort(new Error('boom!'));
console.log(ac.signal.reason);  // Error: boom!

abortSignal.throwIfAborted()

If abortSignal.aborted is true, throws abortSignal.reason.

atob(data)

Stability: 3 - Legacy. Use Buffer.from(data, 'base64') instead.

Global alias for [buffer.atob()][].

An automated migration is available (source):

npx codemod@latest @nodejs/buffer-atob-btoa

Class: Blob

See {Blob}.

Class: BroadcastChannel

See {BroadcastChannel}.

btoa(data)

Stability: 3 - Legacy. Use buf.toString('base64') instead.

Global alias for [buffer.btoa()][].

An automated migration is available (source):

npx codemod@latest @nodejs/buffer-atob-btoa

Class: Buffer

  • Type: {Function}

Used to handle binary data. See the [buffer section][].

Class: ByteLengthQueuingStrategy

A browser-compatible implementation of [ByteLengthQueuingStrategy][].

clearImmediate(immediateObject)

[clearImmediate][] is described in the [timers][] section.

clearInterval(intervalObject)

[clearInterval][] is described in the [timers][] section.

clearTimeout(timeoutObject)

[clearTimeout][] is described in the [timers][] section.

Class: CloseEvent

A browser-compatible implementation of {CloseEvent}.

Class: CompressionStream

A browser-compatible implementation of [CompressionStream][].

console

  • Type: {Object}

Used to print to stdout and stderr. See the [console][] section.

Class: CountQueuingStrategy

A browser-compatible implementation of [CountQueuingStrategy][].

Class: Crypto

A browser-compatible implementation of {Crypto}. This global is available only if the Node.js binary was compiled with including support for the node:crypto module.

crypto

A browser-compatible implementation of the [Web Crypto API][].

Class: CryptoKey

A browser-compatible implementation of {CryptoKey}. This global is available only if the Node.js binary was compiled with including support for the node:crypto module.

Class: CustomEvent

A browser-compatible implementation of {CustomEvent}.

Class: DecompressionStream

A browser-compatible implementation of [DecompressionStream][].

Class: DOMException

The WHATWG {DOMException} class.

ErrorEvent

A browser-compatible implementation of {ErrorEvent}.

Class: Event

A browser-compatible implementation of the Event class. See [EventTarget and Event API][] for more details.

Class: EventSource

Stability: 1 - Experimental. Enable this API with the [--experimental-eventsource][] CLI flag.

A browser-compatible implementation of {EventSource}.

Class: EventTarget

A browser-compatible implementation of the EventTarget class. See [EventTarget and Event API][] for more details.

exports

This variable may appear to be global but is not. See [exports][].

fetch

A browser-compatible implementation of the [fetch()][] function.

const res = await fetch('https://nodejs.org/api/documentation.json');
if (res.ok) {
  const data = await res.json();
  console.log(data);
}

The implementation is based upon undici, an HTTP/1.1 client written from scratch for Node.js. You can figure out which version of undici is bundled in your Node.js process reading the process.versions.undici property.

Custom dispatcher

You can use a custom dispatcher to dispatch requests passing it in fetch's options object. The dispatcher must be compatible with undici's Dispatcher class.

fetch(url, { dispatcher: new MyAgent() });

It is possible to change the global dispatcher in Node.js by installing undici and using the setGlobalDispatcher() method. Calling this method will affect both undici and Node.js.

import { setGlobalDispatcher } from 'undici';
setGlobalDispatcher(new MyAgent());

The following globals are available to use with fetch:

  • [FormData][]
  • [Headers][]
  • [Request][]
  • [Response][]

Class: File

See {File}.

Class: FormData

A browser-compatible implementation of {FormData}.

global

Stability: 3 - Legacy. Use [globalThis][] instead.

  • Type: {Object} The global namespace object.

In browsers, the top-level scope has traditionally been the global scope. This means that var something will define a new global variable, except within ECMAScript modules. In Node.js, this is different. The top-level scope is not the global scope; var something inside a Node.js module will be local to that module, regardless of whether it is a [CommonJS module][] or an [ECMAScript module][].

Class: Headers

A browser-compatible implementation of {Headers}.

localStorage

Stability: 1.2 - Release candidate. Disable this API with [--no-experimental-webstorage][].

A browser-compatible implementation of [localStorage][]. Data is stored unencrypted in the file specified by the [--localstorage-file][] CLI flag. The maximum amount of data that can be stored is 10 MB. Any modification of this data outside of the Web Storage API is not supported. localStorage data is not stored per user or per request when used in the context of a server, it is shared across all users and requests.

Class: MessageChannel

The MessageChannel class. See [MessageChannel][] for more details.

Class: MessageEvent

A browser-compatible implementation of {MessageEvent}.

Class: MessagePort

The MessagePort class. See [MessagePort][] for more details.

module

This variable may appear to be global but is not. See [module][].

Class: Navigator

Stability: 1.1 - Active development. Disable this API with the [--no-experimental-global-navigator][] CLI flag.

A partial implementation of the [Navigator API][].

Stability: 1.1 - Active development. Disable this API with the [--no-experimental-global-navigator][] CLI flag.

A partial implementation of [window.navigator][].

  • Type: {number}

The navigator.hardwareConcurrency read-only property returns the number of logical processors available to the current Node.js instance.

console.log(`This process is running on ${navigator.hardwareConcurrency} logical processors`);
  • Type: {string}

The navigator.language read-only property returns a string representing the preferred language of the Node.js instance. The language will be determined by the ICU library used by Node.js at runtime based on the default language of the operating system.

The value is representing the language version as defined in [RFC 5646][].

The fallback value on builds without ICU is 'en-US'.

console.log(`The preferred language of the Node.js instance has the tag '${navigator.language}'`);
  • Type: {string[]}

The navigator.languages read-only property returns an array of strings representing the preferred languages of the Node.js instance. By default navigator.languages contains only the value of navigator.language, which will be determined by the ICU library used by Node.js at runtime based on the default language of the operating system.

The fallback value on builds without ICU is ['en-US'].

console.log(`The preferred languages are '${navigator.languages}'`);

Stability: 1 - Experimental

The navigator.locks read-only property returns a [LockManager][] instance that can be used to coordinate access to resources that may be shared across multiple threads within the same process. This global implementation matches the semantics of the [browser LockManager][] API.

// Request an exclusive lock
await navigator.locks.request('my_resource', async (lock) => {
  // The lock has been acquired.
  console.log(`Lock acquired: ${lock.name}`);
  // Lock is automatically released when the function returns
});

// Request a shared lock
await navigator.locks.request('shared_resource', { mode: 'shared' }, async (lock) => {
  // Multiple shared locks can be held simultaneously
  console.log(`Shared lock acquired: ${lock.name}`);
});
// Request an exclusive lock
navigator.locks.request('my_resource', async (lock) => {
  // The lock has been acquired.
  console.log(`Lock acquired: ${lock.name}`);
  // Lock is automatically released when the function returns
}).then(() => {
  console.log('Lock released');
});

// Request a shared lock
navigator.locks.request('shared_resource', { mode: 'shared' }, async (lock) => {
  // Multiple shared locks can be held simultaneously
  console.log(`Shared lock acquired: ${lock.name}`);
}).then(() => {
  console.log('Shared lock released');
});

See [worker_threads.locks][] for detailed API documentation.

  • Type: {string}

The navigator.platform read-only property returns a string identifying the platform on which the Node.js instance is running.

console.log(`This process is running on ${navigator.platform}`);
  • Type: {string}

The navigator.userAgent read-only property returns user agent consisting of the runtime name and major version number.

console.log(`The user-agent is ${navigator.userAgent}`); // Prints "Node.js/21"

performance

The [perf_hooks.performance][] object.

Class: PerformanceEntry

The PerformanceEntry class. See [PerformanceEntry][] for more details.

Class: PerformanceMark

The PerformanceMark class. See [PerformanceMark][] for more details.

Class: PerformanceMeasure

The PerformanceMeasure class. See [PerformanceMeasure][] for more details.

Class: PerformanceObserver

The PerformanceObserver class. See [PerformanceObserver][] for more details.

Class: PerformanceObserverEntryList

The PerformanceObserverEntryList class. See [PerformanceObserverEntryList][] for more details.

Class: PerformanceResourceTiming

The PerformanceResourceTiming class. See [PerformanceResourceTiming][] for more details.

process

  • Type: {Object}

The process object. See the [process object][] section.

queueMicrotask(callback)

  • callback {Function} Function to be queued.

The queueMicrotask() method queues a microtask to invoke callback. If callback throws an exception, the [process object][] 'uncaughtException' event will be emitted.

The microtask queue is managed by V8 and may be used in a similar manner to the [process.nextTick()][] queue, which is managed by Node.js. The process.nextTick() queue is always processed before the microtask queue within each turn of the Node.js event loop.

// Here, `queueMicrotask()` is used to ensure the 'load' event is always
// emitted asynchronously, and therefore consistently. Using
// `process.nextTick()` here would result in the 'load' event always emitting
// before any other promise jobs.

DataHandler.prototype.load = async function load(key) {
  const hit = this._cache.get(key);
  if (hit !== undefined) {
    queueMicrotask(() => {
      this.emit('load', hit);
    });
    return;
  }

  const data = await fetchData(key);
  this._cache.set(key, data);
  this.emit('load', data);
};

Class: QuotaExceededError

The WHATWG {QuotaExceededError} class. Extends {DOMException}.

Class: ReadableByteStreamController

A browser-compatible implementation of [ReadableByteStreamController][].

Class: ReadableStream

A browser-compatible implementation of [ReadableStream][].

Class: ReadableStreamBYOBReader

A browser-compatible implementation of [ReadableStreamBYOBReader][].

Class: ReadableStreamBYOBRequest

A browser-compatible implementation of [ReadableStreamBYOBRequest][].

Class: ReadableStreamDefaultController

A browser-compatible implementation of [ReadableStreamDefaultController][].

Class: ReadableStreamDefaultReader

A browser-compatible implementation of [ReadableStreamDefaultReader][].

Class: Request

A browser-compatible implementation of {Request}.

require()

This variable may appear to be global but is not. See [require()][].

Class: Response

A browser-compatible implementation of {Response}.

sessionStorage

Stability: 1.2 - Release candidate. Disable this API with [--no-experimental-webstorage][].

A browser-compatible implementation of [sessionStorage][]. Data is stored in memory, with a storage quota of 10 MB. sessionStorage data persists only within the currently running process, and is not shared between workers.

setImmediate(callback[, ...args])

[setImmediate][] is described in the [timers][] section.

setInterval(callback, delay[, ...args])

[setInterval][] is described in the [timers][] section.

setTimeout(callback, delay[, ...args])

[setTimeout][] is described in the [timers][] section.

Class: Storage

Stability: 1.2 - Release candidate. Disable this API with [--no-experimental-webstorage][].

A browser-compatible implementation of {Storage}.

structuredClone(value[, options])

The WHATWG [structuredClone][] method.

Class: SubtleCrypto

A browser-compatible implementation of {SubtleCrypto}. This global is available only if the Node.js binary was compiled with including support for the node:crypto module.

Class: TextDecoder

The WHATWG TextDecoder class. See the [TextDecoder][] section.

Class: TextDecoderStream

A browser-compatible implementation of [TextDecoderStream][].

Class: TextEncoder

The WHATWG TextEncoder class. See the [TextEncoder][] section.

Class: TextEncoderStream

A browser-compatible implementation of [TextEncoderStream][].

Class: TransformStream

A browser-compatible implementation of [TransformStream][].

Class: TransformStreamDefaultController

A browser-compatible implementation of [TransformStreamDefaultController][].

Class: URL

The WHATWG URL class. See the [URL][] section.

Class: URLPattern

Stability: 1 - Experimental

The WHATWG URLPattern class. See the [URLPattern][] section.

Class: URLSearchParams

The WHATWG URLSearchParams class. See the [URLSearchParams][] section.

Class: WebAssembly

  • Type: {Object}

The object that acts as the namespace for all W3C [WebAssembly][webassembly-org] related functionality. See the [Mozilla Developer Network][webassembly-mdn] for usage and compatibility.

Class: WebSocket

A browser-compatible implementation of {WebSocket}.

Class: Worker

Stability: 1 - Experimental. Enable this API with the [--experimental-web-worker][] CLI flag.

A mostly browser-compatible implementation of Web Workers of the [HTML Standard][], implemented on top of [node:worker_threads][]. Threads created with it are given the {DedicatedWorkerGlobalScope} API (self, name, location, navigator, postMessage(), close(), and importScripts()), in addition to the usual Node.js globals, such as process.

// worker.js
addEventListener('message', (event) => {
  postMessage(`${event.data} from ${name}!`);
});
// main.js
const worker = new Worker('./worker.js', { name: 'greeter' });

worker.addEventListener('message', (event) => {
  console.log(event.data); // Prints: Hello from greeter!
  worker.terminate();
});

worker.postMessage('Hello');

Because their lifetime and sharing model depend on origins and browsing contexts, Node.js does not currently implement SharedWorker.

Loading worker scripts

Worker scripts are read synchronously from the local file system or from memory rather than fetched over the network, which changes which URLs are accepted and how failures are reported:

  • new Worker() and importScripts() accept only file:, data:, and blob: URLs. Any other scheme makes new Worker() throw a NotSupportedError and importScripts() throw a NetworkError.
  • A script that cannot be read makes importScripts() throw a NetworkError; for new Worker() it fires an error event at the Worker object.
  • Redirects, the nosniff check, and HTTP MIME type validation do not apply. MIME types are validated only for data: and blob: URLs. The credentials option is validated for API compatibility but has no effect, since no network request is made.
  • On the main thread, relative script URLs are resolved against the current working directory, because there is no document base URL. Within a worker they are resolved against the worker's own URL (as is done in the spec).
  • For blob: URLs, the script must be held in memory, so blobs backed by a file, such as those returned by [fs.openAsBlob()][], cannot be used.

[Type stripping][type stripping] only applies to module workers loaded from file: URLs. The type option, not the file extension, decides how an entry is run, so a .cts entry is still evaluated as an ES module.

Differences from the HTML Standard

Besides script loading, mentioned above:

  • Node.js has no origin model, so same-origin and cross-origin distinctions do not exist and location.origin is 'null' for every supported scheme.
  • close() terminates the worker immediately instead of following the specification's "closing flag" algorithm, so code remaining in the current task after close() is not executed.
  • The worker global is the normal Node.js global object with DedicatedWorkerGlobalScope inserted into its prototype chain, rather than a fresh global created from the interface. Node.js globals such as process, Buffer, and require() remain available to worker scripts.
  • ErrorEvents dispatched at Worker instances include message and error, but filename, lineno, and colno are always '', 0, and 0. An uncaught exception terminates the worker thread, and an unhandled error event is not propagated further: it neither reaches the parent's global scope nor affects the exit code of the process.
  • The following {WorkerGlobalScope} events are never dispatched, although their handler properties exist: languagechange, online, and offline, since these concepts do not exist in Node.js; rejectionhandled and unhandledrejection, since Node.js exposes the equivalent does not implement the PromiseRejectionEvent interface or the per-rejection preventDefault() behavior required by the HTML Standard.
  • Module workers loaded from file: URLs support [type stripping][].

Web Workers and node:worker_threads

Every Web Worker is backed by a [node:worker_threads][] {Worker}, so the two APIs share their threading, structured clone, and transfer semantics. Inside a worker, [worker_threads.parentPort][] is the port behind self.postMessage() and the worker's message events, isMainThread is false, and workerData is undefined.

Web Workers, like node:worker_threads workers, keep the event loop alive by default. In Node.js, Web Workers implement the [Refable protocol][], and can be ref'd and unref'd using process.ref(worker) and process.unref(worker).

As a rule of thumb, use [node:worker_threads][] directly when a program needs workerData, a custom env or execArgv, resource limits, stdio redirection, the 'online' and 'exit' events, or worker.threadId; Worker accepts only the name, type, and credentials options and, per the specification, its terminate() returns undefined, rather than a promise. Threads started through [node:worker_threads][] are ordinary Node.js threads and do not get the worker global scope APIs.

Class: WritableStream

A browser-compatible implementation of [WritableStream][].

Class: WritableStreamDefaultController

A browser-compatible implementation of [WritableStreamDefaultController][].

Class: WritableStreamDefaultWriter

A browser-compatible implementation of [WritableStreamDefaultWriter][].

[CommonJS module]: modules.md [CommonJS modules]: modules.md [ECMAScript module]: esm.md [HTML Standard]: https://html.spec.whatwg.org/multipage/workers.html [Navigator API]: https://html.spec.whatwg.org/multipage/system-state.html#the-navigator-object [RFC 5646]: https://www.rfc-editor.org/rfc/rfc5646.txt [Refable protocol]: process.md#processrefmayberefable [Web Crypto API]: webcrypto.md [--experimental-eventsource]: cli.md#--experimental-eventsource [--experimental-web-worker]: cli.md#--experimental-web-worker [--localstorage-file]: cli.md#--localstorage-filefile [--no-experimental-global-navigator]: cli.md#--no-experimental-global-navigator [--no-experimental-webstorage]: cli.md#--no-experimental-webstorage [ByteLengthQueuingStrategy]: webstreams.md#class-bytelengthqueuingstrategy [CompressionStream]: webstreams.md#class-compressionstream [CountQueuingStrategy]: webstreams.md#class-countqueuingstrategy [DecompressionStream]: webstreams.md#class-decompressionstream [EventTarget and Event API]: events.md#eventtarget-and-event-api [FormData]: #class-formdata [Headers]: #class-headers [LockManager]: worker_threads.md#class-lockmanager [MessageChannel]: worker_threads.md#class-messagechannel [MessagePort]: worker_threads.md#class-messageport [PerformanceEntry]: perf_hooks.md#class-performanceentry [PerformanceMark]: perf_hooks.md#class-performancemark [PerformanceMeasure]: perf_hooks.md#class-performancemeasure [PerformanceObserverEntryList]: perf_hooks.md#class-performanceobserverentrylist [PerformanceObserver]: perf_hooks.md#class-performanceobserver [PerformanceResourceTiming]: perf_hooks.md#class-performanceresourcetiming [ReadableByteStreamController]: webstreams.md#class-readablebytestreamcontroller [ReadableStreamBYOBReader]: webstreams.md#class-readablestreambyobreader [ReadableStreamBYOBRequest]: webstreams.md#class-readablestreambyobrequest [ReadableStreamDefaultController]: webstreams.md#class-readablestreamdefaultcontroller [ReadableStreamDefaultReader]: webstreams.md#class-readablestreamdefaultreader [ReadableStream]: webstreams.md#class-readablestream [Request]: #class-request [Response]: #class-response [TextDecoderStream]: webstreams.md#class-textdecoderstream [TextDecoder]: util.md#class-utiltextdecoder [TextEncoderStream]: webstreams.md#class-textencoderstream [TextEncoder]: util.md#class-utiltextencoder [TransformStreamDefaultController]: webstreams.md#class-transformstreamdefaultcontroller [TransformStream]: webstreams.md#class-transformstream [URLPattern]: url.md#class-urlpattern [URLSearchParams]: url.md#class-urlsearchparams [URL]: url.md#class-url [WritableStreamDefaultController]: webstreams.md#class-writablestreamdefaultcontroller [WritableStreamDefaultWriter]: webstreams.md#class-writablestreamdefaultwriter [WritableStream]: webstreams.md#class-writablestream [__dirname]: modules.md#__dirname [__filename]: modules.md#__filename [abortSignal.reason]: #abortsignalreason [buffer.atob()]: buffer.md#bufferatobdata [buffer.btoa()]: buffer.md#bufferbtoadata [clearImmediate]: timers.md#clearimmediateimmediate [clearInterval]: timers.md#clearintervaltimeout [clearTimeout]: timers.md#cleartimeouttimeout [console]: console.md [exports]: modules.md#exports [fetch()]: https://developer.mozilla.org/en-US/docs/Web/API/Window/fetch [fs.openAsBlob()]: fs.md#fsopenasblobpath-options [globalThis]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/globalThis [localStorage]: https://developer.mozilla.org/en-US/docs/Web/API/Window/localStorage [module]: modules.md#module [node:worker_threads]: worker_threads.md [perf_hooks.performance]: perf_hooks.md#perf_hooksperformance [process.nextTick()]: process.md#processnexttickcallback-args [process object]: process.md#process [require()]: modules.md#requireid [sessionStorage]: https://developer.mozilla.org/en-US/docs/Web/API/Window/sessionStorage [setImmediate]: timers.md#setimmediatecallback-args [setInterval]: timers.md#setintervalcallback-delay-args [setTimeout]: timers.md#settimeoutcallback-delay-args [structuredClone]: https://developer.mozilla.org/en-US/docs/Web/API/Window/structuredClone [window.navigator]: https://developer.mozilla.org/en-US/docs/Web/API/Window/navigator [worker_threads.locks]: worker_threads.md#worker_threadslocks [browser LockManager]: https://developer.mozilla.org/en-US/docs/Web/API/LockManager [buffer section]: buffer.md [built-in objects]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects [timers]: timers.md [type stripping]: typescript.md#type-stripping [webassembly-mdn]: https://developer.mozilla.org/en-US/docs/WebAssembly [webassembly-org]: https://webassembly.org