diff --git a/doc/api/globals.md b/doc/api/globals.md index 7dffaf6dfea8f4..6f791732b9536d 100644 --- a/doc/api/globals.md +++ b/doc/api/globals.md @@ -4,8 +4,6 @@ -> 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 @@ -33,8 +31,10 @@ changes: description: No longer experimental. --> + + A utility class used to signal cancelation in selected `Promise`-based APIs. -The API is based on the Web API {AbortController}. +The API is based on the Web API [`AbortController`][]. ```js const ac = new AbortController(); @@ -104,7 +104,7 @@ changes: description: Added the new optional reason argument. --> -* `reason` {any} +* `reason`: {any} * Returns: {AbortSignal} Returns a new already aborted `AbortSignal`. @@ -230,6 +230,8 @@ If `abortSignal.aborted` is `true`, throws `abortSignal.reason`. added: v18.0.0 --> + + See {Blob}. ## Class: `Buffer` @@ -238,7 +240,9 @@ See {Blob}. added: v0.1.103 --> -* Type: {Function} + + +* {Function} Used to handle binary data. See the [buffer section][]. @@ -246,14 +250,10 @@ Used to handle binary data. See the [buffer section][]. +> Stability: 1 - Experimental. + A browser-compatible implementation of [`ByteLengthQueuingStrategy`][]. ## `__dirname` @@ -274,7 +274,7 @@ added: v16.0.0 Global alias for [`buffer.atob()`][]. -## Class: `BroadcastChannel` +## `BroadcastChannel` + + [`clearImmediate`][] is described in the [timers][] section. ## `clearInterval(intervalObject)` @@ -306,6 +308,8 @@ added: v0.9.1 added: v0.0.1 --> + + [`clearInterval`][] is described in the [timers][] section. ## `clearTimeout(timeoutObject)` @@ -314,34 +318,31 @@ added: v0.0.1 added: v0.0.1 --> + + [`clearTimeout`][] is described in the [timers][] section. -## Class: `CloseEvent` +## `CloseEvent` -A browser-compatible implementation of {CloseEvent}. Disable this API + + +The `CloseEvent` class. See [`CloseEvent`][] for more details. + +A browser-compatible implementation of [`CloseEvent`][]. Disable this API with the [`--no-experimental-websocket`][] CLI flag. ## Class: `CompressionStream` +> Stability: 1 - Experimental. + A browser-compatible implementation of [`CompressionStream`][]. ## `console` @@ -350,7 +351,9 @@ A browser-compatible implementation of [`CompressionStream`][]. added: v0.1.100 --> -* Type: {Object} + + +* {Object} Used to print to stdout and stderr. See the [`console`][] section. @@ -358,17 +361,13 @@ Used to print to stdout and stderr. See the [`console`][] section. +> Stability: 1 - Experimental. + A browser-compatible implementation of [`CountQueuingStrategy`][]. -## Class: `Crypto` +## `Crypto` +> Stability: 2 - Stable. + 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. @@ -402,9 +403,11 @@ changes: description: No longer behind `--experimental-global-webcrypto` CLI flag. --> +> Stability: 2 - Stable. + A browser-compatible implementation of the [Web Crypto API][]. -## Class: `CryptoKey` +## `CryptoKey` +> Stability: 2 - Stable. + 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` +## `CustomEvent` -A browser-compatible implementation of {CustomEvent}. +> Stability: 2 - Stable + + + +A browser-compatible implementation of the [`CustomEvent` Web API][]. ## Class: `DecompressionStream` -A browser-compatible implementation of [`DecompressionStream`][]. - -## `ErrorEvent` - - +> Stability: 1 - Experimental. -A browser-compatible implementation of {ErrorEvent}. +A browser-compatible implementation of [`DecompressionStream`][]. -## Class: `Event` +## `Event` + + A browser-compatible implementation of the `Event` class. See [`EventTarget` and `Event` API][] for more details. -## Class: `EventSource` +## `EventSource` + + A browser-compatible implementation of the `EventTarget` class. See [`EventTarget` and `Event` API][] for more details. @@ -531,47 +527,29 @@ changes: description: No longer behind `--experimental-fetch` CLI flag. --> -A browser-compatible implementation of the [`fetch()`][] function. - -```mjs -const res = await fetch('https://nodejs.org/api/documentation.json'); -if (res.ok) { - const data = await res.json(); - console.log(data); -} -``` +> Stability: 2 - Stable -The implementation is based upon [undici](https://undici.nodejs.org), 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. +A browser-compatible implementation of the [`fetch()`][] function. -### Custom dispatcher +### Differences Between Node.js `fetch()` and Standard Fetch API -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](https://undici.nodejs.org/#/docs/api/Dispatcher.md). +Node.js's `fetch()` implementation is inspired by the Fetch API standard, but it includes several key differences: -```js -fetch(url, { dispatcher: new MyAgent() }); -``` +1. **`new Response(asyncIterable)`**: + * Node.js extends the standard `Response` constructor to accept an `asyncIterable` as its body. This allows streams and other async sources to be directly used. This feature is not part of the Fetch API in browsers. -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. +2. **Cookies Handling**: + * Unlike browsers, Node.js does not automatically manage cookies. In browsers, cookies are managed through the `Cookie` header and automatically sent with requests. In Node.js, you need to manually handle cookies, potentially using additional libraries like `node-fetch-cookie`. -```mjs -import { setGlobalDispatcher } from 'undici'; -setGlobalDispatcher(new MyAgent()); -``` +3. **No Forbidden Headers**: + * In browsers, there are several headers (e.g., `User-Agent`, `Referer`, `Host`) that are restricted from being modified by the developer for security reasons. In Node.js, these headers can be freely set, giving developers more control. -### Related classes +4. **Environment-Specific Behavior**: + * Node.js operates outside of a browser environment and doesn't have access to browser-specific features like Service Workers, Cache API, etc. This can affect how requests and responses are handled in Node.js. -The following globals are available to use with `fetch`: +For more details, refer to the [WHATWG Fetch Standard](https://fetch.spec.whatwg.org/) and the Node.js implementation notes. -* [`FormData`](https://nodejs.org/api/globals.html#class-formdata) -* [`Headers`](https://nodejs.org/api/globals.html#class-headers) -* [`Request`](https://nodejs.org/api/globals.html#request) -* [`Response`](https://nodejs.org/api/globals.html#response). +The `fetch()` function in Node.js is based on the Fetch API standard but has several differences. For a detailed comparison of how Node.js’s `fetch` differs from the standard Fetch API, see the [Undici documentation](https://github.com/nodejs/undici/blob/main/docs/). ## Class: `File` @@ -579,9 +557,11 @@ The following globals are available to use with `fetch`: added: v20.0.0 --> + + See {File}. -## Class: `FormData` +## Class `FormData` +> Stability: 2 - Stable + A browser-compatible implementation of {FormData}. ## `global` @@ -605,9 +587,11 @@ A browser-compatible implementation of {FormData}. added: v0.1.27 --> + + > Stability: 3 - Legacy. Use [`globalThis`][] instead. -* Type: {Object} The global namespace object. +* {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 @@ -616,7 +600,7 @@ 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` +## Class `Headers` +> Stability: 2 - Stable + A browser-compatible implementation of {Headers}. ## `localStorage` @@ -640,43 +626,51 @@ A browser-compatible implementation of {Headers}. added: v22.4.0 --> +> Stability: 1.0 - Early development. + 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. -Disable this API with the [`--no-webstorage`][] (or its alias `--no-experimental-webstorage`) CLI flag. +Enable this API with the [`--experimental-webstorage`][] CLI flag. `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` +## `MessageChannel` + + The `MessageChannel` class. See [`MessageChannel`][] for more details. -## Class: `MessageEvent` +## `MessageEvent` -A browser-compatible implementation of {MessageEvent}. + + +The `MessageEvent` class. See [`MessageEvent`][] for more details. -## Class: `MessagePort` +## `MessagePort` + + The `MessagePort` class. See [`MessagePort`][] for more details. ## `module` This variable may appear to be global but is not. See [`module`][]. -## Class: `Navigator` +## `Navigator` -* Type: {number} +* {number} The `navigator.hardwareConcurrency` read-only property returns the number of logical processors available to the current Node.js instance. @@ -719,7 +713,7 @@ console.log(`This process is running on ${navigator.hardwareConcurrency} logical added: v21.2.0 --> -* Type: {string} +* {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 @@ -740,7 +734,7 @@ console.log(`The preferred language of the Node.js instance has the tag '${navig added: v21.2.0 --> -* Type: {Array} +* {Array} The `navigator.languages` read-only property returns an array of strings representing the preferred languages of the Node.js instance. @@ -760,7 +754,7 @@ console.log(`The preferred languages are '${navigator.languages}'`); added: v21.2.0 --> -* Type: {string} +* {string} The `navigator.platform` read-only property returns a string identifying the platform on which the Node.js instance is running. @@ -775,7 +769,7 @@ console.log(`This process is running on ${navigator.platform}`); added: v21.1.0 --> -* Type: {string} +* {string} The `navigator.userAgent` read-only property returns user agent consisting of the runtime name and major version number. @@ -784,102 +778,65 @@ consisting of the runtime name and major version number. console.log(`The user-agent is ${navigator.userAgent}`); // Prints "Node.js/21" ``` -### `navigator.locks` - - - -> 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. - -```mjs -// 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}`); -}); -``` - -```cjs -// 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. - -## Class: `PerformanceEntry` +## `PerformanceEntry` + + The `PerformanceEntry` class. See [`PerformanceEntry`][] for more details. -## Class: `PerformanceMark` +## `PerformanceMark` + + The `PerformanceMark` class. See [`PerformanceMark`][] for more details. -## Class: `PerformanceMeasure` +## `PerformanceMeasure` + + The `PerformanceMeasure` class. See [`PerformanceMeasure`][] for more details. -## Class: `PerformanceObserver` +## `PerformanceObserver` + + The `PerformanceObserver` class. See [`PerformanceObserver`][] for more details. -## Class: `PerformanceObserverEntryList` +## `PerformanceObserverEntryList` + + The `PerformanceObserverEntryList` class. See [`PerformanceObserverEntryList`][] for more details. -## Class: `PerformanceResourceTiming` +## `PerformanceResourceTiming` + + The `PerformanceResourceTiming` class. See [`PerformanceResourceTiming`][] for more details. @@ -897,7 +854,9 @@ The [`perf_hooks.performance`][] object. added: v0.1.7 --> -* Type: {Object} + + +* {Object} The process object. See the [`process` object][] section. @@ -907,6 +866,8 @@ The process object. See the [`process` object][] section. added: v11.0.0 --> + + * `callback` {Function} Function to be queued. The `queueMicrotask()` method queues a microtask to invoke `callback`. If @@ -943,91 +904,67 @@ DataHandler.prototype.load = async function load(key) { +> Stability: 1 - Experimental. + A browser-compatible implementation of [`ReadableByteStreamController`][]. ## Class: `ReadableStream` +> Stability: 1 - Experimental. + A browser-compatible implementation of [`ReadableStream`][]. ## Class: `ReadableStreamBYOBReader` +> Stability: 1 - Experimental. + A browser-compatible implementation of [`ReadableStreamBYOBReader`][]. ## Class: `ReadableStreamBYOBRequest` +> Stability: 1 - Experimental. + A browser-compatible implementation of [`ReadableStreamBYOBRequest`][]. ## Class: `ReadableStreamDefaultController` +> Stability: 1 - Experimental. + A browser-compatible implementation of [`ReadableStreamDefaultController`][]. ## Class: `ReadableStreamDefaultReader` +> Stability: 1 - Experimental. + A browser-compatible implementation of [`ReadableStreamDefaultReader`][]. ## `require()` This variable may appear to be global but is not. See [`require()`][]. -## Class: `Response` +## `Response` +> Stability: 2 - Stable + A browser-compatible implementation of {Response}. -## Class: `Request` +## `Request` +> Stability: 2 - Stable + A browser-compatible implementation of {Request}. ## `sessionStorage` @@ -1081,6 +1022,8 @@ the currently running process, and is not shared between workers. added: v0.9.1 --> + + [`setImmediate`][] is described in the [timers][] section. ## `setInterval(callback, delay[, ...args])` @@ -1089,6 +1032,8 @@ added: v0.9.1 added: v0.0.1 --> + + [`setInterval`][] is described in the [timers][] section. ## `setTimeout(callback, delay[, ...args])` @@ -1097,6 +1042,8 @@ added: v0.0.1 added: v0.0.1 --> + + [`setTimeout`][] is described in the [timers][] section. ## Class: `Storage` @@ -1105,11 +1052,10 @@ added: v0.0.1 added: v22.4.0 --> -> Stability: 1.0 - Early development. Enable this API with the -> \[`--experimental-webstorage`]\[] CLI flag. +> Stability: 1.0 - Early development. -A browser-compatible implementation of {Storage}. Disable this API with the -[`--no-webstorage`][] (or its alias `--no-experimental-webstorage`) CLI flag. +A browser-compatible implementation of [`Storage`][]. Enable this API with the +[`--experimental-webstorage`][] CLI flag. ## `structuredClone(value[, options])` @@ -1117,9 +1063,11 @@ A browser-compatible implementation of {Storage}. Disable this API with the added: v17.0.0 --> + + The WHATWG [`structuredClone`][] method. -## Class: `SubtleCrypto` +## `SubtleCrypto` +> Stability: 2 - Stable. + 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: `DOMException` +## `DOMException` -The WHATWG {DOMException} class. + + +The WHATWG `DOMException` class. See [`DOMException`][] for more details. -## Class: `TextDecoder` +## `TextDecoder` + + The WHATWG `TextDecoder` class. See the [`TextDecoder`][] section. ## Class: `TextDecoderStream` +> Stability: 1 - Experimental. + A browser-compatible implementation of [`TextDecoderStream`][]. -## Class: `TextEncoder` +## `TextEncoder` + + The WHATWG `TextEncoder` class. See the [`TextEncoder`][] section. ## Class: `TextEncoderStream` +> Stability: 1 - Experimental. + A browser-compatible implementation of [`TextEncoderStream`][]. ## Class: `TransformStream` +> Stability: 1 - Experimental. + A browser-compatible implementation of [`TransformStream`][]. ## Class: `TransformStreamDefaultController` +> Stability: 1 - Experimental. + A browser-compatible implementation of [`TransformStreamDefaultController`][]. -## Class: `URL` +## `URL` -The WHATWG `URL` class. See the [`URL`][] section. - -## Class: `URLPattern` - - - -> Stability: 1 - Experimental + -The WHATWG `URLPattern` class. See the [`URLPattern`][] section. +The WHATWG `URL` class. See the [`URL`][] section. -## Class: `URLSearchParams` +## `URLSearchParams` + + The WHATWG `URLSearchParams` class. See the [`URLSearchParams`][] section. -## Class: `WebAssembly` +## `WebAssembly` -* Type: {Object} + + +* {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` +## `WebSocket` -A browser-compatible implementation of {WebSocket}. Disable this API +> Stability: 2 - Stable. + +A browser-compatible implementation of [`WebSocket`][]. Disable this API with the [`--no-experimental-websocket`][] CLI flag. ## Class: `WritableStream` +> Stability: 1 - Experimental. + A browser-compatible implementation of [`WritableStream`][]. ## Class: `WritableStreamDefaultController` +> Stability: 1 - Experimental. + A browser-compatible implementation of [`WritableStreamDefaultController`][]. ## Class: `WritableStreamDefaultWriter` +> Stability: 1 - Experimental. + A browser-compatible implementation of [`WritableStreamDefaultWriter`][]. [CommonJS module]: modules.md @@ -1320,17 +1246,22 @@ A browser-compatible implementation of [`WritableStreamDefaultWriter`][]. [RFC 5646]: https://www.rfc-editor.org/rfc/rfc5646.txt [Web Crypto API]: webcrypto.md [`--experimental-eventsource`]: cli.md#--experimental-eventsource +[`--experimental-webstorage`]: cli.md#--experimental-webstorage [`--localstorage-file`]: cli.md#--localstorage-filefile [`--no-experimental-global-navigator`]: cli.md#--no-experimental-global-navigator [`--no-experimental-websocket`]: cli.md#--no-experimental-websocket -[`--no-webstorage`]: cli.md#--no-webstorage +[`AbortController`]: https://developer.mozilla.org/en-US/docs/Web/API/AbortController [`ByteLengthQueuingStrategy`]: webstreams.md#class-bytelengthqueuingstrategy +[`CloseEvent`]: https://developer.mozilla.org/en-US/docs/Web/API/CloseEvent/CloseEvent [`CompressionStream`]: webstreams.md#class-compressionstream [`CountQueuingStrategy`]: webstreams.md#class-countqueuingstrategy +[`CustomEvent` Web API]: https://dom.spec.whatwg.org/#customevent +[`DOMException`]: https://developer.mozilla.org/en-US/docs/Web/API/DOMException [`DecompressionStream`]: webstreams.md#class-decompressionstream +[`EventSource`]: https://developer.mozilla.org/en-US/docs/Web/API/EventSource [`EventTarget` and `Event` API]: events.md#eventtarget-and-event-api -[`LockManager`]: worker_threads.md#class-lockmanager [`MessageChannel`]: worker_threads.md#class-messagechannel +[`MessageEvent`]: https://developer.mozilla.org/en-US/docs/Web/API/MessageEvent/MessageEvent [`MessagePort`]: worker_threads.md#class-messageport [`PerformanceEntry`]: perf_hooks.md#class-performanceentry [`PerformanceMark`]: perf_hooks.md#class-performancemark @@ -1344,15 +1275,16 @@ A browser-compatible implementation of [`WritableStreamDefaultWriter`][]. [`ReadableStreamDefaultController`]: webstreams.md#class-readablestreamdefaultcontroller [`ReadableStreamDefaultReader`]: webstreams.md#class-readablestreamdefaultreader [`ReadableStream`]: webstreams.md#class-readablestream +[`Storage`]: https://developer.mozilla.org/en-US/docs/Web/API/Storage [`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 +[`WebSocket`]: https://developer.mozilla.org/en-US/docs/Web/API/WebSocket [`WritableStreamDefaultController`]: webstreams.md#class-writablestreamdefaultcontroller [`WritableStreamDefaultWriter`]: webstreams.md#class-writablestreamdefaultwriter [`WritableStream`]: webstreams.md#class-writablestream @@ -1380,10 +1312,8 @@ A browser-compatible implementation of [`WritableStreamDefaultWriter`][]. [`setTimeout`]: timers.md#settimeoutcallback-delay-args [`structuredClone`]: https://developer.mozilla.org/en-US/docs/Web/API/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 [webassembly-mdn]: https://developer.mozilla.org/en-US/docs/WebAssembly -[webassembly-org]: https://webassembly.org +[webassembly-org]: https://webassembly.org \ No newline at end of file