Contributing#

Report errors in this documentation inthe issue tracker. Seethe contributing guide for directions on how to submit pull requests.

Stability index#

Throughout the documentation are indications of a section's stability. Some APIsare so proven and so relied upon that they are unlikely to ever change at all.Others are brand new and experimental, or known to be hazardous.

The stability indexes are as follows:

Features are marked as legacy rather than being deprecated if their use does noharm, and they are widely relied upon within the npm ecosystem. Bugs found inlegacy features are unlikely to be fixed.

Use caution when making use of Experimental features, particularly whenauthoring libraries. Users may not be aware that experimental features are beingused. Bugs or behavior changes may surprise users when Experimental APImodifications occur. To avoid surprises, use of an Experimental feature may needa command-line flag. Experimental features may also emit awarning.

Stability overview#

JSON output#

Every.html document has a corresponding.json document. This is for IDEsand other utilities that consume the documentation.

System calls and man pages#

Node.js functions which wrap a system call will document that. The docs linkto the corresponding man pages which describe how the system call works.

Most Unix system calls have Windows analogues. Still, behavior differences maybe unavoidable.

Usage#

node [options] [V8 options] [script.js | -e "script" | - ] [arguments]

Please see theCommand-line options document for more information.

Example#

An example of aweb server written with Node.js which responds with'Hello, World!':

Commands in this document start with$ or> to replicate how they wouldappear in a user's terminal. Do not include the$ and> characters. They arethere to show the start of each command.

Lines that don't start with$ or> character show the output of the previouscommand.

First, make sure to have downloaded and installed Node.js. SeeInstalling Node.js via package manager for further install information.

Now, create an empty project folder calledprojects, then navigate into it.

Linux and Mac:

mkdir ~/projectscd ~/projectscopy

Windows CMD:

mkdir %USERPROFILE%\projectscd %USERPROFILE%\projectscopy

Windows PowerShell:

mkdir$env:USERPROFILE\projectscd$env:USERPROFILE\projectscopy

Next, create a new source file in theprojectsfolder and call ithello-world.js.

Openhello-world.js in any preferred text editor andpaste in the following content:

const http =require('node:http');const hostname ='127.0.0.1';const port =3000;const server = http.createServer((req, res) => {  res.statusCode =200;  res.setHeader('Content-Type','text/plain');  res.end('Hello, World!\n');});server.listen(port, hostname,() => {console.log(`Server running at http://${hostname}:${port}/`);});copy

Save the file. Then, in the terminal window, to run thehello-world.js file,enter:

node hello-world.jscopy

Output like this should appear in the terminal:

Server running at http://127.0.0.1:3000/copy

Now, open any preferred web browser and visithttp://127.0.0.1:3000.

If the browser displays the stringHello, World!, that indicatesthe server is working.

Strict assertion mode#

In strict assertion mode, non-strict methods behave like their correspondingstrict methods. For example,assert.deepEqual() will behave likeassert.deepStrictEqual().

In strict assertion mode, error messages for objects display a diff. In legacyassertion mode, error messages for objects display the objects, often truncated.

To use strict assertion mode:

import { strictas assert }from'node:assert';const assert =require('node:assert').strict;copy

import assertfrom'node:assert/strict';const assert =require('node:assert/strict');copy

Example error diff:

import { strictas assert }from'node:assert';assert.deepEqual([[[1,2,3]],4,5], [[[1,2,'3']],4,5]);// AssertionError: Expected inputs to be strictly deep-equal:// + actual - expected ... Lines skipped////   [//     [// ...//       2,// +     3// -     '3'//     ],// ...//     5//   ]const assert =require('node:assert/strict');assert.deepEqual([[[1,2,3]],4,5], [[[1,2,'3']],4,5]);// AssertionError: Expected inputs to be strictly deep-equal:// + actual - expected ... Lines skipped////   [//     [// ...//       2,// +     3// -     '3'//     ],// ...//     5//   ]copy

To deactivate the colors, use theNO_COLOR orNODE_DISABLE_COLORSenvironment variables. This will also deactivate the colors in the REPL. Formore on color support in terminal environments, read the ttygetColorDepth() documentation.

Legacy assertion mode#

Legacy assertion mode uses the== operator in:

• assert.deepEqual()
• assert.equal()
• assert.notDeepEqual()
• assert.notEqual()

To use legacy assertion mode:

import assertfrom'node:assert';const assert =require('node:assert');copy

Legacy assertion mode may have surprising results, especially when usingassert.deepEqual():

// WARNING: This does not throw an AssertionError in legacy assertion mode!assert.deepEqual(/a/gi,newDate());copy

Class:assert.AssertionError#

• Extends:<errors.Error>

Indicates the failure of an assertion. All errors thrown by thenode:assertmodule will be instances of theAssertionError class.

import assertfrom'node:assert';// Generate an AssertionError to compare the error message later:const { message } =new assert.AssertionError({actual:1,expected:2,operator:'strictEqual',});// Verify error output:try {  assert.strictEqual(1,2);}catch (err) {assert(errinstanceof assert.AssertionError);  assert.strictEqual(err.message, message);  assert.strictEqual(err.name,'AssertionError');  assert.strictEqual(err.actual,1);  assert.strictEqual(err.expected,2);  assert.strictEqual(err.code,'ERR_ASSERTION');  assert.strictEqual(err.operator,'strictEqual');  assert.strictEqual(err.generatedMessage,true);}const assert =require('node:assert');// Generate an AssertionError to compare the error message later:const { message } =new assert.AssertionError({actual:1,expected:2,operator:'strictEqual',});// Verify error output:try {  assert.strictEqual(1,2);}catch (err) {assert(errinstanceof assert.AssertionError);  assert.strictEqual(err.message, message);  assert.strictEqual(err.name,'AssertionError');  assert.strictEqual(err.actual,1);  assert.strictEqual(err.expected,2);  assert.strictEqual(err.code,'ERR_ASSERTION');  assert.strictEqual(err.operator,'strictEqual');  assert.strictEqual(err.generatedMessage,true);}copy

Class:assert.Assert#

TheAssert class allows creating independent assertion instances with custom options.

const {Assert } =require('node:assert');const assertInstance =newAssert({diff:'full' });assertInstance.deepStrictEqual({a:1 }, {a:2 });// Shows a full diff in the error message.copy

const myAssert =newAssert({diff:'full' });// This works as expected - uses 'full' diffmyAssert.strictEqual({a:1 }, {b: {c:1 } });// This loses the 'full' diff setting - falls back to default 'simple' diffconst { strictEqual } = myAssert;strictEqual({a:1 }, {b: {c:1 } });copy

classFoo {constructor(a) {this.a = a;  }}classBar {constructor(a) {this.a = a;  }}const foo =newFoo(1);const bar =newBar(1);// Default behavior - fails due to different constructorsconst assert1 =newAssert();assert1.deepStrictEqual(foo, bar);// AssertionError// Skip prototype comparison - passes if properties are equalconst assert2 =newAssert({skipPrototype:true });assert2.deepStrictEqual(foo, bar);// OKcopy

assert(value[, message])#

• value<any> The input that is checked for being truthy.
• message<string> |<Error>

An alias ofassert.ok().

assert.deepEqual(actual, expected[, message])#

• actual<any>
• expected<any>
• message<string> |<Error>

Strict assertion mode

An alias ofassert.deepStrictEqual().

Legacy assertion mode

Tests for deep equality between theactual andexpected parameters. Considerusingassert.deepStrictEqual() instead.assert.deepEqual() can havesurprising results.

Deep equality means that the enumerable "own" properties of child objectsare also recursively evaluated by the following rules.

import assertfrom'node:assert';// WARNING: This does not throw an AssertionError!assert.deepEqual('+00000000',false);const assert =require('node:assert');// WARNING: This does not throw an AssertionError!assert.deepEqual('+00000000',false);copy

import assertfrom'node:assert';const obj1 = {a: {b:1,  },};const obj2 = {a: {b:2,  },};const obj3 = {a: {b:1,  },};const obj4 = {__proto__: obj1 };assert.deepEqual(obj1, obj1);// OK// Values of b are different:assert.deepEqual(obj1, obj2);// AssertionError: { a: { b: 1 } } deepEqual { a: { b: 2 } }assert.deepEqual(obj1, obj3);// OK// Prototypes are ignored:assert.deepEqual(obj1, obj4);// AssertionError: { a: { b: 1 } } deepEqual {}const assert =require('node:assert');const obj1 = {a: {b:1,  },};const obj2 = {a: {b:2,  },};const obj3 = {a: {b:1,  },};const obj4 = {__proto__: obj1 };assert.deepEqual(obj1, obj1);// OK// Values of b are different:assert.deepEqual(obj1, obj2);// AssertionError: { a: { b: 1 } } deepEqual { a: { b: 2 } }assert.deepEqual(obj1, obj3);// OK// Prototypes are ignored:assert.deepEqual(obj1, obj4);// AssertionError: { a: { b: 1 } } deepEqual {}copy

assert.deepStrictEqual(actual, expected[, message])#

• actual<any>
• expected<any>
• message<string> |<Error>

Tests for deep equality between theactual andexpected parameters."Deep" equality means that the enumerable "own" properties of child objectsare recursively evaluated also by the following rules.

import assertfrom'node:assert/strict';// This fails because 1 !== '1'.assert.deepStrictEqual({a:1 }, {a:'1' });// AssertionError: Expected inputs to be strictly deep-equal:// + actual - expected////   {// +   a: 1// -   a: '1'//   }// The following objects don't have own propertiesconst date =newDate();const object = {};const fakeDate = {};Object.setPrototypeOf(fakeDate,Date.prototype);// Different [[Prototype]]:assert.deepStrictEqual(object, fakeDate);// AssertionError: Expected inputs to be strictly deep-equal:// + actual - expected//// + {}// - Date {}// Different type tags:assert.deepStrictEqual(date, fakeDate);// AssertionError: Expected inputs to be strictly deep-equal:// + actual - expected//// + 2018-04-26T00:49:08.604Z// - Date {}assert.deepStrictEqual(NaN,NaN);// OK because Object.is(NaN, NaN) is true.// Different unwrapped numbers:assert.deepStrictEqual(newNumber(1),newNumber(2));// AssertionError: Expected inputs to be strictly deep-equal:// + actual - expected//// + [Number: 1]// - [Number: 2]assert.deepStrictEqual(newString('foo'),Object('foo'));// OK because the object and the string are identical when unwrapped.assert.deepStrictEqual(-0, -0);// OK// Different zeros:assert.deepStrictEqual(0, -0);// AssertionError: Expected inputs to be strictly deep-equal:// + actual - expected//// + 0// - -0const symbol1 =Symbol();const symbol2 =Symbol();assert.deepStrictEqual({ [symbol1]:1 }, { [symbol1]:1 });// OK, because it is the same symbol on both objects.assert.deepStrictEqual({ [symbol1]:1 }, { [symbol2]:1 });// AssertionError [ERR_ASSERTION]: Inputs identical but not reference equal://// {//   Symbol(): 1// }const weakMap1 =newWeakMap();const weakMap2 =newWeakMap();const obj = {};weakMap1.set(obj,'value');weakMap2.set(obj,'value');// Comparing different instances fails, even with same contentsassert.deepStrictEqual(weakMap1, weakMap2);// AssertionError: Values have same structure but are not reference-equal://// WeakMap {//   <items unknown>// }// Comparing the same instance to itself succeedsassert.deepStrictEqual(weakMap1, weakMap1);// OKconst weakSet1 =newWeakSet();const weakSet2 =newWeakSet();weakSet1.add(obj);weakSet2.add(obj);// Comparing different instances fails, even with same contentsassert.deepStrictEqual(weakSet1, weakSet2);// AssertionError: Values have same structure but are not reference-equal:// + actual - expected//// WeakSet {//   <items unknown>// }// Comparing the same instance to itself succeedsassert.deepStrictEqual(weakSet1, weakSet1);// OKconst assert =require('node:assert/strict');// This fails because 1 !== '1'.assert.deepStrictEqual({a:1 }, {a:'1' });// AssertionError: Expected inputs to be strictly deep-equal:// + actual - expected////   {// +   a: 1// -   a: '1'//   }// The following objects don't have own propertiesconst date =newDate();const object = {};const fakeDate = {};Object.setPrototypeOf(fakeDate,Date.prototype);// Different [[Prototype]]:assert.deepStrictEqual(object, fakeDate);// AssertionError: Expected inputs to be strictly deep-equal:// + actual - expected//// + {}// - Date {}// Different type tags:assert.deepStrictEqual(date, fakeDate);// AssertionError: Expected inputs to be strictly deep-equal:// + actual - expected//// + 2018-04-26T00:49:08.604Z// - Date {}assert.deepStrictEqual(NaN,NaN);// OK because Object.is(NaN, NaN) is true.// Different unwrapped numbers:assert.deepStrictEqual(newNumber(1),newNumber(2));// AssertionError: Expected inputs to be strictly deep-equal:// + actual - expected//// + [Number: 1]// - [Number: 2]assert.deepStrictEqual(newString('foo'),Object('foo'));// OK because the object and the string are identical when unwrapped.assert.deepStrictEqual(-0, -0);// OK// Different zeros:assert.deepStrictEqual(0, -0);// AssertionError: Expected inputs to be strictly deep-equal:// + actual - expected//// + 0// - -0const symbol1 =Symbol();const symbol2 =Symbol();assert.deepStrictEqual({ [symbol1]:1 }, { [symbol1]:1 });// OK, because it is the same symbol on both objects.assert.deepStrictEqual({ [symbol1]:1 }, { [symbol2]:1 });// AssertionError [ERR_ASSERTION]: Inputs identical but not reference equal://// {//   Symbol(): 1// }const weakMap1 =newWeakMap();const weakMap2 =newWeakMap();const obj = {};weakMap1.set(obj,'value');weakMap2.set(obj,'value');// Comparing different instances fails, even with same contentsassert.deepStrictEqual(weakMap1, weakMap2);// AssertionError: Values have same structure but are not reference-equal://// WeakMap {//   <items unknown>// }// Comparing the same instance to itself succeedsassert.deepStrictEqual(weakMap1, weakMap1);// OKconst weakSet1 =newWeakSet();const weakSet2 =newWeakSet();weakSet1.add(obj);weakSet2.add(obj);// Comparing different instances fails, even with same contentsassert.deepStrictEqual(weakSet1, weakSet2);// AssertionError: Values have same structure but are not reference-equal:// + actual - expected//// WeakSet {//   <items unknown>// }// Comparing the same instance to itself succeedsassert.deepStrictEqual(weakSet1, weakSet1);// OKcopy

assert.doesNotMatch(string, regexp[, message])#

• string<string>
• regexp<RegExp>
• message<string> |<Error>

Expects thestring input not to match the regular expression.

import assertfrom'node:assert/strict';assert.doesNotMatch('I will fail',/fail/);// AssertionError [ERR_ASSERTION]: The input was expected to not match the ...assert.doesNotMatch(123,/pass/);// AssertionError [ERR_ASSERTION]: The "string" argument must be of type string.assert.doesNotMatch('I will pass',/different/);// OKconst assert =require('node:assert/strict');assert.doesNotMatch('I will fail',/fail/);// AssertionError [ERR_ASSERTION]: The input was expected to not match the ...assert.doesNotMatch(123,/pass/);// AssertionError [ERR_ASSERTION]: The "string" argument must be of type string.assert.doesNotMatch('I will pass',/different/);// OKcopy

If the values do match, or if thestring argument is of another type thanstring, anAssertionError is thrown with amessage property set equalto the value of themessage parameter. If themessage parameter isundefined, a default error message is assigned. If themessage parameter is aninstance of<Error> then it will be thrown instead of theAssertionError.

assert.doesNotReject(asyncFn[, error][, message])#

• asyncFn<Function> |<Promise>
• error<RegExp> |<Function>
• message<string>
• Returns:<Promise>

Awaits theasyncFn promise or, ifasyncFn is a function, immediatelycalls the function and awaits the returned promise to complete. It will thencheck that the promise is not rejected.

IfasyncFn is a function and it throws an error synchronously,assert.doesNotReject() will return a rejectedPromise with that error. Ifthe function does not return a promise,assert.doesNotReject() will return arejectedPromise with anERR_INVALID_RETURN_VALUE error. In both casesthe error handler is skipped.

Usingassert.doesNotReject() is actually not useful because there is littlebenefit in catching a rejection and then rejecting it again. Instead, consideradding a comment next to the specific code path that should not reject and keeperror messages as expressive as possible.

If specified,error can be aClass,<RegExp> or a validationfunction. Seeassert.throws() for more details.

Besides the async nature to await the completion behaves identically toassert.doesNotThrow().

import assertfrom'node:assert/strict';await assert.doesNotReject(async () => {thrownewTypeError('Wrong value');  },SyntaxError,);const assert =require('node:assert/strict');(async () => {await assert.doesNotReject(async () => {thrownewTypeError('Wrong value');    },SyntaxError,  );})();copy

import assertfrom'node:assert/strict';assert.doesNotReject(Promise.reject(newTypeError('Wrong value')))  .then(() => {// ...  });const assert =require('node:assert/strict');assert.doesNotReject(Promise.reject(newTypeError('Wrong value')))  .then(() => {// ...  });copy

assert.doesNotThrow(fn[, error][, message])#

• fn<Function>
• error<RegExp> |<Function>
• message<string>

Asserts that the functionfn does not throw an error.

Usingassert.doesNotThrow() is actually not useful because thereis no benefit in catching an error and then rethrowing it. Instead, consideradding a comment next to the specific code path that should not throw and keeperror messages as expressive as possible.

Whenassert.doesNotThrow() is called, it will immediately call thefnfunction.

If an error is thrown and it is the same type as that specified by theerrorparameter, then anAssertionError is thrown. If the error is of adifferent type, or if theerror parameter is undefined, the error ispropagated back to the caller.

If specified,error can be aClass,<RegExp>, or a validationfunction. Seeassert.throws() for more details.

The following, for instance, will throw the<TypeError> because there is nomatching error type in the assertion:

import assertfrom'node:assert/strict';assert.doesNotThrow(() => {thrownewTypeError('Wrong value');  },SyntaxError,);const assert =require('node:assert/strict');assert.doesNotThrow(() => {thrownewTypeError('Wrong value');  },SyntaxError,);copy

However, the following will result in anAssertionError with the message'Got unwanted exception...':

import assertfrom'node:assert/strict';assert.doesNotThrow(() => {thrownewTypeError('Wrong value');  },TypeError,);const assert =require('node:assert/strict');assert.doesNotThrow(() => {thrownewTypeError('Wrong value');  },TypeError,);copy

If anAssertionError is thrown and a value is provided for themessageparameter, the value ofmessage will be appended to theAssertionErrormessage:

import assertfrom'node:assert/strict';assert.doesNotThrow(() => {thrownewTypeError('Wrong value');  },/Wrong value/,'Whoops',);// Throws: AssertionError: Got unwanted exception: Whoopsconst assert =require('node:assert/strict');assert.doesNotThrow(() => {thrownewTypeError('Wrong value');  },/Wrong value/,'Whoops',);// Throws: AssertionError: Got unwanted exception: Whoopscopy

assert.equal(actual, expected[, message])#

• actual<any>
• expected<any>
• message<string> |<Error>

Strict assertion mode

An alias ofassert.strictEqual().

Legacy assertion mode

Tests shallow, coercive equality between theactual andexpected parametersusing the== operator.NaN is specially handledand treated as being identical if both sides areNaN.

import assertfrom'node:assert';assert.equal(1,1);// OK, 1 == 1assert.equal(1,'1');// OK, 1 == '1'assert.equal(NaN,NaN);// OKassert.equal(1,2);// AssertionError: 1 == 2assert.equal({a: {b:1 } }, {a: {b:1 } });// AssertionError: { a: { b: 1 } } == { a: { b: 1 } }const assert =require('node:assert');assert.equal(1,1);// OK, 1 == 1assert.equal(1,'1');// OK, 1 == '1'assert.equal(NaN,NaN);// OKassert.equal(1,2);// AssertionError: 1 == 2assert.equal({a: {b:1 } }, {a: {b:1 } });// AssertionError: { a: { b: 1 } } == { a: { b: 1 } }copy

If the values are not equal, anAssertionError is thrown with amessageproperty set equal to the value of themessage parameter. If themessageparameter is undefined, a default error message is assigned. If themessageparameter is an instance of<Error> then it will be thrown instead of theAssertionError.

assert.fail([message])#

• message<string> |<Error>Default:'Failed'

Throws anAssertionError with the provided error message or a defaulterror message. If themessage parameter is an instance of<Error> thenit will be thrown instead of theAssertionError.

import assertfrom'node:assert/strict';assert.fail();// AssertionError [ERR_ASSERTION]: Failedassert.fail('boom');// AssertionError [ERR_ASSERTION]: boomassert.fail(newTypeError('need array'));// TypeError: need arrayconst assert =require('node:assert/strict');assert.fail();// AssertionError [ERR_ASSERTION]: Failedassert.fail('boom');// AssertionError [ERR_ASSERTION]: boomassert.fail(newTypeError('need array'));// TypeError: need arraycopy

assert.ifError(value)#

• value<any>

Throwsvalue ifvalue is notundefined ornull. This is useful whentesting theerror argument in callbacks. The stack trace contains all framesfrom the error passed toifError() including the potential new frames forifError() itself.

import assertfrom'node:assert/strict';assert.ifError(null);// OKassert.ifError(0);// AssertionError [ERR_ASSERTION]: ifError got unwanted exception: 0assert.ifError('error');// AssertionError [ERR_ASSERTION]: ifError got unwanted exception: 'error'assert.ifError(newError());// AssertionError [ERR_ASSERTION]: ifError got unwanted exception: Error// Create some random error frames.let err;(functionerrorFrame() {  err =newError('test error');})();(functionifErrorFrame() {  assert.ifError(err);})();// AssertionError [ERR_ASSERTION]: ifError got unwanted exception: test error//     at ifErrorFrame//     at errorFrameconst assert =require('node:assert/strict');assert.ifError(null);// OKassert.ifError(0);// AssertionError [ERR_ASSERTION]: ifError got unwanted exception: 0assert.ifError('error');// AssertionError [ERR_ASSERTION]: ifError got unwanted exception: 'error'assert.ifError(newError());// AssertionError [ERR_ASSERTION]: ifError got unwanted exception: Error// Create some random error frames.let err;(functionerrorFrame() {  err =newError('test error');})();(functionifErrorFrame() {  assert.ifError(err);})();// AssertionError [ERR_ASSERTION]: ifError got unwanted exception: test error//     at ifErrorFrame//     at errorFramecopy

assert.match(string, regexp[, message])#

• string<string>
• regexp<RegExp>
• message<string> |<Error>

Expects thestring input to match the regular expression.

import assertfrom'node:assert/strict';assert.match('I will fail',/pass/);// AssertionError [ERR_ASSERTION]: The input did not match the regular ...assert.match(123,/pass/);// AssertionError [ERR_ASSERTION]: The "string" argument must be of type string.assert.match('I will pass',/pass/);// OKconst assert =require('node:assert/strict');assert.match('I will fail',/pass/);// AssertionError [ERR_ASSERTION]: The input did not match the regular ...assert.match(123,/pass/);// AssertionError [ERR_ASSERTION]: The "string" argument must be of type string.assert.match('I will pass',/pass/);// OKcopy

If the values do not match, or if thestring argument is of another type thanstring, anAssertionError is thrown with amessage property set equalto the value of themessage parameter. If themessage parameter isundefined, a default error message is assigned. If themessage parameter is aninstance of<Error> then it will be thrown instead of theAssertionError.

assert.notDeepEqual(actual, expected[, message])#

• actual<any>
• expected<any>
• message<string> |<Error>

Strict assertion mode

An alias ofassert.notDeepStrictEqual().

Legacy assertion mode

Tests for any deep inequality. Opposite ofassert.deepEqual().

import assertfrom'node:assert';const obj1 = {a: {b:1,  },};const obj2 = {a: {b:2,  },};const obj3 = {a: {b:1,  },};const obj4 = {__proto__: obj1 };assert.notDeepEqual(obj1, obj1);// AssertionError: { a: { b: 1 } } notDeepEqual { a: { b: 1 } }assert.notDeepEqual(obj1, obj2);// OKassert.notDeepEqual(obj1, obj3);// AssertionError: { a: { b: 1 } } notDeepEqual { a: { b: 1 } }assert.notDeepEqual(obj1, obj4);// OKconst assert =require('node:assert');const obj1 = {a: {b:1,  },};const obj2 = {a: {b:2,  },};const obj3 = {a: {b:1,  },};const obj4 = {__proto__: obj1 };assert.notDeepEqual(obj1, obj1);// AssertionError: { a: { b: 1 } } notDeepEqual { a: { b: 1 } }assert.notDeepEqual(obj1, obj2);// OKassert.notDeepEqual(obj1, obj3);// AssertionError: { a: { b: 1 } } notDeepEqual { a: { b: 1 } }assert.notDeepEqual(obj1, obj4);// OKcopy

If the values are deeply equal, anAssertionError is thrown with amessage property set equal to the value of themessage parameter. If themessage parameter is undefined, a default error message is assigned. If themessage parameter is an instance of<Error> then it will be throwninstead of theAssertionError.

assert.notDeepStrictEqual(actual, expected[, message])#

• actual<any>
• expected<any>
• message<string> |<Error>

Tests for deep strict inequality. Opposite ofassert.deepStrictEqual().

import assertfrom'node:assert/strict';assert.notDeepStrictEqual({a:1 }, {a:'1' });// OKconst assert =require('node:assert/strict');assert.notDeepStrictEqual({a:1 }, {a:'1' });// OKcopy

If the values are deeply and strictly equal, anAssertionError is thrownwith amessage property set equal to the value of themessage parameter. Ifthemessage parameter is undefined, a default error message is assigned. Ifthemessage parameter is an instance of<Error> then it will be throwninstead of theAssertionError.

assert.notEqual(actual, expected[, message])#

• actual<any>
• expected<any>
• message<string> |<Error>

Strict assertion mode

An alias ofassert.notStrictEqual().

Legacy assertion mode

Tests shallow, coercive inequality with the!= operator.NaN isspecially handled and treated as being identical if both sides areNaN.

import assertfrom'node:assert';assert.notEqual(1,2);// OKassert.notEqual(1,1);// AssertionError: 1 != 1assert.notEqual(1,'1');// AssertionError: 1 != '1'const assert =require('node:assert');assert.notEqual(1,2);// OKassert.notEqual(1,1);// AssertionError: 1 != 1assert.notEqual(1,'1');// AssertionError: 1 != '1'copy

If the values are equal, anAssertionError is thrown with amessageproperty set equal to the value of themessage parameter. If themessageparameter is undefined, a default error message is assigned. If themessageparameter is an instance of<Error> then it will be thrown instead of theAssertionError.

assert.notStrictEqual(actual, expected[, message])#

• actual<any>
• expected<any>
• message<string> |<Error>

Tests strict inequality between theactual andexpected parameters asdetermined byObject.is().

import assertfrom'node:assert/strict';assert.notStrictEqual(1,2);// OKassert.notStrictEqual(1,1);// AssertionError [ERR_ASSERTION]: Expected "actual" to be strictly unequal to://// 1assert.notStrictEqual(1,'1');// OKconst assert =require('node:assert/strict');assert.notStrictEqual(1,2);// OKassert.notStrictEqual(1,1);// AssertionError [ERR_ASSERTION]: Expected "actual" to be strictly unequal to://// 1assert.notStrictEqual(1,'1');// OKcopy

If the values are strictly equal, anAssertionError is thrown with amessage property set equal to the value of themessage parameter. If themessage parameter is undefined, a default error message is assigned. If themessage parameter is an instance of<Error> then it will be throwninstead of theAssertionError.

assert.ok(value[, message])#

• value<any>
• message<string> |<Error>

Tests ifvalue is truthy. It is equivalent toassert.equal(!!value, true, message).

Ifvalue is not truthy, anAssertionError is thrown with amessageproperty set equal to the value of themessage parameter. If themessageparameter isundefined, a default error message is assigned. If themessageparameter is an instance of<Error> then it will be thrown instead of theAssertionError.If no arguments are passed in at allmessage will be set to the string:'No value argument passed to `assert.ok()`'.

Be aware that in therepl the error message will be different to the onethrown in a file! See below for further details.

import assertfrom'node:assert/strict';assert.ok(true);// OKassert.ok(1);// OKassert.ok();// AssertionError: No value argument passed to `assert.ok()`assert.ok(false,'it\'s false');// AssertionError: it's false// In the repl:assert.ok(typeof123 ==='string');// AssertionError: false == true// In a file (e.g. test.js):assert.ok(typeof123 ==='string');// AssertionError: The expression evaluated to a falsy value:////   assert.ok(typeof 123 === 'string')assert.ok(false);// AssertionError: The expression evaluated to a falsy value:////   assert.ok(false)assert.ok(0);// AssertionError: The expression evaluated to a falsy value:////   assert.ok(0)copy

const assert =require('node:assert/strict');assert.ok(true);// OKassert.ok(1);// OKassert.ok();// AssertionError: No value argument passed to `assert.ok()`assert.ok(false,'it\'s false');// AssertionError: it's false// In the repl:assert.ok(typeof123 ==='string');// AssertionError: false == true// In a file (e.g. test.js):assert.ok(typeof123 ==='string');// AssertionError: The expression evaluated to a falsy value:////   assert.ok(typeof 123 === 'string')assert.ok(false);// AssertionError: The expression evaluated to a falsy value:////   assert.ok(false)assert.ok(0);// AssertionError: The expression evaluated to a falsy value:////   assert.ok(0)import assertfrom'node:assert/strict';// Using `assert()` works the same:assert(2 +2 >5);// AssertionError: The expression evaluated to a falsy value:////   assert(2 + 2 > 5)copy

const assert =require('node:assert');// Using `assert()` works the same:assert(2 +2 >5);// AssertionError: The expression evaluated to a falsy value:////   assert(2 + 2 > 5)copy

assert.rejects(asyncFn[, error][, message])#

• asyncFn<Function> |<Promise>
• error<RegExp> |<Function> |<Object> |<Error>
• message<string>
• Returns:<Promise>

Awaits theasyncFn promise or, ifasyncFn is a function, immediatelycalls the function and awaits the returned promise to complete. It will thencheck that the promise is rejected.

IfasyncFn is a function and it throws an error synchronously,assert.rejects() will return a rejectedPromise with that error. If thefunction does not return a promise,assert.rejects() will return a rejectedPromise with anERR_INVALID_RETURN_VALUE error. In both cases the errorhandler is skipped.

Besides the async nature to await the completion behaves identically toassert.throws().

If specified,error can be aClass,<RegExp>, a validation function,an object where each property will be tested for, or an instance of error whereeach property will be tested for including the non-enumerablemessage andname properties.

If specified,message will be the message provided by theAssertionErrorif theasyncFn fails to reject.

import assertfrom'node:assert/strict';await assert.rejects(async () => {thrownewTypeError('Wrong value');  },  {name:'TypeError',message:'Wrong value',  },);const assert =require('node:assert/strict');(async () => {await assert.rejects(async () => {thrownewTypeError('Wrong value');    },    {name:'TypeError',message:'Wrong value',    },  );})();copy

import assertfrom'node:assert/strict';await assert.rejects(async () => {thrownewTypeError('Wrong value');  },(err) => {    assert.strictEqual(err.name,'TypeError');    assert.strictEqual(err.message,'Wrong value');returntrue;  },);const assert =require('node:assert/strict');(async () => {await assert.rejects(async () => {thrownewTypeError('Wrong value');    },(err) => {      assert.strictEqual(err.name,'TypeError');      assert.strictEqual(err.message,'Wrong value');returntrue;    },  );})();copy

import assertfrom'node:assert/strict';assert.rejects(Promise.reject(newError('Wrong value')),Error,).then(() => {// ...});const assert =require('node:assert/strict');assert.rejects(Promise.reject(newError('Wrong value')),Error,).then(() => {// ...});copy

error cannot be a string. If a string is provided as the secondargument, thenerror is assumed to be omitted and the string will be used formessage instead. This can lead to easy-to-miss mistakes. Please read theexample inassert.throws() carefully if using a string as the secondargument gets considered.

assert.strictEqual(actual, expected[, message])#

• actual<any>
• expected<any>
• message<string> |<Error>

Tests strict equality between theactual andexpected parameters asdetermined byObject.is().

import assertfrom'node:assert/strict';assert.strictEqual(1,2);// AssertionError [ERR_ASSERTION]: Expected inputs to be strictly equal://// 1 !== 2assert.strictEqual(1,1);// OKassert.strictEqual('Hello foobar','Hello World!');// AssertionError [ERR_ASSERTION]: Expected inputs to be strictly equal:// + actual - expected//// + 'Hello foobar'// - 'Hello World!'//          ^const apples =1;const oranges =2;assert.strictEqual(apples, oranges,`apples${apples} !== oranges${oranges}`);// AssertionError [ERR_ASSERTION]: apples 1 !== oranges 2assert.strictEqual(1,'1',newTypeError('Inputs are not identical'));// TypeError: Inputs are not identicalconst assert =require('node:assert/strict');assert.strictEqual(1,2);// AssertionError [ERR_ASSERTION]: Expected inputs to be strictly equal://// 1 !== 2assert.strictEqual(1,1);// OKassert.strictEqual('Hello foobar','Hello World!');// AssertionError [ERR_ASSERTION]: Expected inputs to be strictly equal:// + actual - expected//// + 'Hello foobar'// - 'Hello World!'//          ^const apples =1;const oranges =2;assert.strictEqual(apples, oranges,`apples${apples} !== oranges${oranges}`);// AssertionError [ERR_ASSERTION]: apples 1 !== oranges 2assert.strictEqual(1,'1',newTypeError('Inputs are not identical'));// TypeError: Inputs are not identicalcopy

If the values are not strictly equal, anAssertionError is thrown with amessage property set equal to the value of themessage parameter. If themessage parameter is undefined, a default error message is assigned. If themessage parameter is an instance of<Error> then it will be throwninstead of theAssertionError.

assert.throws(fn[, error][, message])#

• fn<Function>
• error<RegExp> |<Function> |<Object> |<Error>
• message<string>

Expects the functionfn to throw an error.

If specified,error can be aClass,<RegExp>, a validation function,a validation object where each property will be tested for strict deep equality,or an instance of error where each property will be tested for strict deepequality including the non-enumerablemessage andname properties. Whenusing an object, it is also possible to use a regular expression, whenvalidating against a string property. See below for examples.

If specified,message will be appended to the message provided by theAssertionError if thefn call fails to throw or in case the error validationfails.

Custom validation object/error instance:

import assertfrom'node:assert/strict';const err =newTypeError('Wrong value');err.code =404;err.foo ='bar';err.info = {nested:true,baz:'text',};err.reg =/abc/i;assert.throws(() => {throw err;  },  {name:'TypeError',message:'Wrong value',info: {nested:true,baz:'text',    },// Only properties on the validation object will be tested for.// Using nested objects requires all properties to be present. Otherwise// the validation is going to fail.  },);// Using regular expressions to validate error properties:assert.throws(() => {throw err;  },  {// The `name` and `message` properties are strings and using regular// expressions on those will match against the string. If they fail, an// error is thrown.name:/^TypeError$/,message:/Wrong/,foo:'bar',info: {nested:true,// It is not possible to use regular expressions for nested properties!baz:'text',    },// The `reg` property contains a regular expression and only if the// validation object contains an identical regular expression, it is going// to pass.reg:/abc/i,  },);// Fails due to the different `message` and `name` properties:assert.throws(() => {const otherErr =newError('Not found');// Copy all enumerable properties from `err` to `otherErr`.for (const [key, value]ofObject.entries(err)) {      otherErr[key] = value;    }throw otherErr;  },// The error's `message` and `name` properties will also be checked when using// an error as validation object.  err,);const assert =require('node:assert/strict');const err =newTypeError('Wrong value');err.code =404;err.foo ='bar';err.info = {nested:true,baz:'text',};err.reg =/abc/i;assert.throws(() => {throw err;  },  {name:'TypeError',message:'Wrong value',info: {nested:true,baz:'text',    },// Only properties on the validation object will be tested for.// Using nested objects requires all properties to be present. Otherwise// the validation is going to fail.  },);// Using regular expressions to validate error properties:assert.throws(() => {throw err;  },  {// The `name` and `message` properties are strings and using regular// expressions on those will match against the string. If they fail, an// error is thrown.name:/^TypeError$/,message:/Wrong/,foo:'bar',info: {nested:true,// It is not possible to use regular expressions for nested properties!baz:'text',    },// The `reg` property contains a regular expression and only if the// validation object contains an identical regular expression, it is going// to pass.reg:/abc/i,  },);// Fails due to the different `message` and `name` properties:assert.throws(() => {const otherErr =newError('Not found');// Copy all enumerable properties from `err` to `otherErr`.for (const [key, value]ofObject.entries(err)) {      otherErr[key] = value;    }throw otherErr;  },// The error's `message` and `name` properties will also be checked when using// an error as validation object.  err,);copy

Validate instanceof using constructor:

import assertfrom'node:assert/strict';assert.throws(() => {thrownewError('Wrong value');  },Error,);const assert =require('node:assert/strict');assert.throws(() => {thrownewError('Wrong value');  },Error,);copy

Validate error message using<RegExp>:

Using a regular expression runs.toString on the error object, and willtherefore also include the error name.

import assertfrom'node:assert/strict';assert.throws(() => {thrownewError('Wrong value');  },/^Error: Wrong value$/,);const assert =require('node:assert/strict');assert.throws(() => {thrownewError('Wrong value');  },/^Error: Wrong value$/,);copy

Custom error validation:

The function must returntrue to indicate all internal validations passed.It will otherwise fail with anAssertionError.

import assertfrom'node:assert/strict';assert.throws(() => {thrownewError('Wrong value');  },(err) => {assert(errinstanceofError);assert(/value/.test(err));// Avoid returning anything from validation functions besides `true`.// Otherwise, it's not clear what part of the validation failed. Instead,// throw an error about the specific validation that failed (as done in this// example) and add as much helpful debugging information to that error as// possible.returntrue;  },'unexpected error',);const assert =require('node:assert/strict');assert.throws(() => {thrownewError('Wrong value');  },(err) => {assert(errinstanceofError);assert(/value/.test(err));// Avoid returning anything from validation functions besides `true`.// Otherwise, it's not clear what part of the validation failed. Instead,// throw an error about the specific validation that failed (as done in this// example) and add as much helpful debugging information to that error as// possible.returntrue;  },'unexpected error',);copy

error cannot be a string. If a string is provided as the secondargument, thenerror is assumed to be omitted and the string will be used formessage instead. This can lead to easy-to-miss mistakes. Using the samemessage as the thrown error message is going to result in anERR_AMBIGUOUS_ARGUMENT error. Please read the example below carefully if usinga string as the second argument gets considered:

import assertfrom'node:assert/strict';functionthrowingFirst() {thrownewError('First');}functionthrowingSecond() {thrownewError('Second');}functionnotThrowing() {}// The second argument is a string and the input function threw an Error.// The first case will not throw as it does not match for the error message// thrown by the input function!assert.throws(throwingFirst,'Second');// In the next example the message has no benefit over the message from the// error and since it is not clear if the user intended to actually match// against the error message, Node.js throws an `ERR_AMBIGUOUS_ARGUMENT` error.assert.throws(throwingSecond,'Second');// TypeError [ERR_AMBIGUOUS_ARGUMENT]// The string is only used (as message) in case the function does not throw:assert.throws(notThrowing,'Second');// AssertionError [ERR_ASSERTION]: Missing expected exception: Second// If it was intended to match for the error message do this instead:// It does not throw because the error messages match.assert.throws(throwingSecond,/Second$/);// If the error message does not match, an AssertionError is thrown.assert.throws(throwingFirst,/Second$/);// AssertionError [ERR_ASSERTION]const assert =require('node:assert/strict');functionthrowingFirst() {thrownewError('First');}functionthrowingSecond() {thrownewError('Second');}functionnotThrowing() {}// The second argument is a string and the input function threw an Error.// The first case will not throw as it does not match for the error message// thrown by the input function!assert.throws(throwingFirst,'Second');// In the next example the message has no benefit over the message from the// error and since it is not clear if the user intended to actually match// against the error message, Node.js throws an `ERR_AMBIGUOUS_ARGUMENT` error.assert.throws(throwingSecond,'Second');// TypeError [ERR_AMBIGUOUS_ARGUMENT]// The string is only used (as message) in case the function does not throw:assert.throws(notThrowing,'Second');// AssertionError [ERR_ASSERTION]: Missing expected exception: Second// If it was intended to match for the error message do this instead:// It does not throw because the error messages match.assert.throws(throwingSecond,/Second$/);// If the error message does not match, an AssertionError is thrown.assert.throws(throwingFirst,/Second$/);// AssertionError [ERR_ASSERTION]copy

Due to the confusing error-prone notation, avoid a string as the secondargument.

assert.partialDeepStrictEqual(actual, expected[, message])#

• actual<any>
• expected<any>
• message<string> |<Error>

Tests for partial deep equality between theactual andexpected parameters."Deep" equality means that the enumerable "own" properties of child objectsare recursively evaluated also by the following rules. "Partial" equality meansthat only properties that exist on theexpected parameter are going to becompared.

This method always passes the same test cases asassert.deepStrictEqual(),behaving as a super set of it.

import assertfrom'node:assert';assert.partialDeepStrictEqual(  {a: {b: {c:1 } } },  {a: {b: {c:1 } } },);// OKassert.partialDeepStrictEqual(  {a:1,b:2,c:3 },  {b:2 },);// OKassert.partialDeepStrictEqual(  [1,2,3,4,5,6,7,8,9],  [4,5,8],);// OKassert.partialDeepStrictEqual(newSet([{a:1 }, {b:1 }]),newSet([{a:1 }]),);// OKassert.partialDeepStrictEqual(newMap([['key1','value1'], ['key2','value2']]),newMap([['key2','value2']]),);// OKassert.partialDeepStrictEqual(123n,123n);// OKassert.partialDeepStrictEqual(  [1,2,3,4,5,6,7,8,9],  [5,4,8],);// AssertionErrorassert.partialDeepStrictEqual(  {a:1 },  {a:1,b:2 },);// AssertionErrorassert.partialDeepStrictEqual(  {a: {b:2 } },  {a: {b:'2' } },);// AssertionErrorconst assert =require('node:assert');assert.partialDeepStrictEqual(  {a: {b: {c:1 } } },  {a: {b: {c:1 } } },);// OKassert.partialDeepStrictEqual(  {a:1,b:2,c:3 },  {b:2 },);// OKassert.partialDeepStrictEqual(  [1,2,3,4,5,6,7,8,9],  [4,5,8],);// OKassert.partialDeepStrictEqual(newSet([{a:1 }, {b:1 }]),newSet([{a:1 }]),);// OKassert.partialDeepStrictEqual(newMap([['key1','value1'], ['key2','value2']]),newMap([['key2','value2']]),);// OKassert.partialDeepStrictEqual(123n,123n);// OKassert.partialDeepStrictEqual(  [1,2,3,4,5,6,7,8,9],  [5,4,8],);// AssertionErrorassert.partialDeepStrictEqual(  {a:1 },  {a:1,b:2 },);// AssertionErrorassert.partialDeepStrictEqual(  {a: {b:2 } },  {a: {b:'2' } },);// AssertionErrorcopy

Introduction#

These classes are used to associate state and propagate it throughoutcallbacks and promise chains.They allow storing data throughout the lifetime of a web requestor any other asynchronous duration. It is similar to thread-local storagein other languages.

TheAsyncLocalStorage andAsyncResource classes are part of thenode:async_hooks module:

import {AsyncLocalStorage,AsyncResource }from'node:async_hooks';const {AsyncLocalStorage,AsyncResource } =require('node:async_hooks');copy

Class:AsyncLocalStorage#

This class creates stores that stay coherent through asynchronous operations.

While you can create your own implementation on top of thenode:async_hooksmodule,AsyncLocalStorage should be preferred as it is a performant and memorysafe implementation that involves significant optimizations that are non-obviousto implement.

The following example usesAsyncLocalStorage to build a simple loggerthat assigns IDs to incoming HTTP requests and includes them in messageslogged within each request.

import httpfrom'node:http';import {AsyncLocalStorage }from'node:async_hooks';const asyncLocalStorage =newAsyncLocalStorage();functionlogWithId(msg) {const id = asyncLocalStorage.getStore();console.log(`${id !==undefined ? id :'-'}:`, msg);}let idSeq =0;http.createServer((req, res) => {  asyncLocalStorage.run(idSeq++,() => {logWithId('start');// Imagine any chain of async operations heresetImmediate(() => {logWithId('finish');      res.end();    });  });}).listen(8080);http.get('http://localhost:8080');http.get('http://localhost:8080');// Prints://   0: start//   0: finish//   1: start//   1: finishconst http =require('node:http');const {AsyncLocalStorage } =require('node:async_hooks');const asyncLocalStorage =newAsyncLocalStorage();functionlogWithId(msg) {const id = asyncLocalStorage.getStore();console.log(`${id !==undefined ? id :'-'}:`, msg);}let idSeq =0;http.createServer((req, res) => {  asyncLocalStorage.run(idSeq++,() => {logWithId('start');// Imagine any chain of async operations heresetImmediate(() => {logWithId('finish');      res.end();    });  });}).listen(8080);http.get('http://localhost:8080');http.get('http://localhost:8080');// Prints://   0: start//   0: finish//   1: start//   1: finishcopy

Each instance ofAsyncLocalStorage maintains an independent storage context.Multiple instances can safely exist simultaneously without risk of interferingwith each other's data.

const asyncLocalStorage =newAsyncLocalStorage();const runInAsyncScope = asyncLocalStorage.run(123,() =>AsyncLocalStorage.snapshot());const result = asyncLocalStorage.run(321,() =>runInAsyncScope(() => asyncLocalStorage.getStore()));console.log(result);// returns 123copy

classFoo {  #runInAsyncScope =AsyncLocalStorage.snapshot();get() {returnthis.#runInAsyncScope(() => asyncLocalStorage.getStore()); }}const foo = asyncLocalStorage.run(123,() =>newFoo());console.log(asyncLocalStorage.run(321,() => foo.get()));// returns 123copy

const store = {id:1 };// Replaces previous store with the given store objectasyncLocalStorage.enterWith(store);asyncLocalStorage.getStore();// Returns the store objectsomeAsyncOperation(() => {  asyncLocalStorage.getStore();// Returns the same object});copy

const store = {id:1 };emitter.on('my-event',() => {  asyncLocalStorage.enterWith(store);});emitter.on('my-event',() => {  asyncLocalStorage.getStore();// Returns the same object});asyncLocalStorage.getStore();// Returns undefinedemitter.emit('my-event');asyncLocalStorage.getStore();// Returns the same objectcopy

const store = {id:2 };try {  asyncLocalStorage.run(store,() => {    asyncLocalStorage.getStore();// Returns the store objectsetTimeout(() => {      asyncLocalStorage.getStore();// Returns the store object    },200);thrownewError();  });}catch (e) {  asyncLocalStorage.getStore();// Returns undefined// The error will be caught here}copy

// Within a call to runtry {  asyncLocalStorage.getStore();// Returns the store object or value  asyncLocalStorage.exit(() => {    asyncLocalStorage.getStore();// Returns undefinedthrownewError();  });}catch (e) {  asyncLocalStorage.getStore();// Returns the same object or value// The error will be caught here}copy

asyncfunctionfn() {await asyncLocalStorage.run(newMap(),() => {    asyncLocalStorage.getStore().set('key', value);returnfoo();// The return value of foo will be awaited  });}copy

Class:AsyncResource#

The classAsyncResource is designed to be extended by the embedder's asyncresources. Using this, users can easily trigger the lifetime events of theirown resources.

Theinit hook will trigger when anAsyncResource is instantiated.

The following is an overview of theAsyncResource API.

import {AsyncResource, executionAsyncId }from'node:async_hooks';// AsyncResource() is meant to be extended. Instantiating a// new AsyncResource() also triggers init. If triggerAsyncId is omitted then// async_hook.executionAsyncId() is used.const asyncResource =newAsyncResource(  type, {triggerAsyncId:executionAsyncId(),requireManualDestroy:false },);// Run a function in the execution context of the resource. This will// * establish the context of the resource// * trigger the AsyncHooks before callbacks// * call the provided function `fn` with the supplied arguments// * trigger the AsyncHooks after callbacks// * restore the original execution contextasyncResource.runInAsyncScope(fn, thisArg, ...args);// Call AsyncHooks destroy callbacks.asyncResource.emitDestroy();// Return the unique ID assigned to the AsyncResource instance.asyncResource.asyncId();// Return the trigger ID for the AsyncResource instance.asyncResource.triggerAsyncId();const {AsyncResource, executionAsyncId } =require('node:async_hooks');// AsyncResource() is meant to be extended. Instantiating a// new AsyncResource() also triggers init. If triggerAsyncId is omitted then// async_hook.executionAsyncId() is used.const asyncResource =newAsyncResource(  type, {triggerAsyncId:executionAsyncId(),requireManualDestroy:false },);// Run a function in the execution context of the resource. This will// * establish the context of the resource// * trigger the AsyncHooks before callbacks// * call the provided function `fn` with the supplied arguments// * trigger the AsyncHooks after callbacks// * restore the original execution contextasyncResource.runInAsyncScope(fn, thisArg, ...args);// Call AsyncHooks destroy callbacks.asyncResource.emitDestroy();// Return the unique ID assigned to the AsyncResource instance.asyncResource.asyncId();// Return the trigger ID for the AsyncResource instance.asyncResource.triggerAsyncId();copy

classDBQueryextendsAsyncResource {constructor(db) {super('DBQuery');this.db = db;  }getInfo(query, callback) {this.db.get(query,(err, data) => {this.runInAsyncScope(callback,null, err, data);    });  }close() {this.db =null;this.emitDestroy();  }}copy

import { parentPort }from'node:worker_threads';parentPort.on('message',(task) => {  parentPort.postMessage(task.a + task.b);});const { parentPort } =require('node:worker_threads');parentPort.on('message',(task) => {  parentPort.postMessage(task.a + task.b);});copy

import {AsyncResource }from'node:async_hooks';import {EventEmitter }from'node:events';import {Worker }from'node:worker_threads';const kTaskInfo =Symbol('kTaskInfo');const kWorkerFreedEvent =Symbol('kWorkerFreedEvent');classWorkerPoolTaskInfoextendsAsyncResource {constructor(callback) {super('WorkerPoolTaskInfo');this.callback = callback;  }done(err, result) {this.runInAsyncScope(this.callback,null, err, result);this.emitDestroy();// `TaskInfo`s are used only once.  }}exportdefaultclassWorkerPoolextendsEventEmitter {constructor(numThreads) {super();this.numThreads = numThreads;this.workers = [];this.freeWorkers = [];this.tasks = [];for (let i =0; i < numThreads; i++)this.addNewWorker();// Any time the kWorkerFreedEvent is emitted, dispatch// the next task pending in the queue, if any.this.on(kWorkerFreedEvent,() => {if (this.tasks.length >0) {const { task, callback } =this.tasks.shift();this.runTask(task, callback);      }    });  }addNewWorker() {const worker =newWorker(newURL('task_processor.js',import.meta.url));    worker.on('message',(result) => {// In case of success: Call the callback that was passed to `runTask`,// remove the `TaskInfo` associated with the Worker, and mark it as free// again.      worker[kTaskInfo].done(null, result);      worker[kTaskInfo] =null;this.freeWorkers.push(worker);this.emit(kWorkerFreedEvent);    });    worker.on('error',(err) => {// In case of an uncaught exception: Call the callback that was passed to// `runTask` with the error.if (worker[kTaskInfo])        worker[kTaskInfo].done(err,null);elsethis.emit('error', err);// Remove the worker from the list and start a new Worker to replace the// current one.this.workers.splice(this.workers.indexOf(worker),1);this.addNewWorker();    });this.workers.push(worker);this.freeWorkers.push(worker);this.emit(kWorkerFreedEvent);  }runTask(task, callback) {if (this.freeWorkers.length ===0) {// No free threads, wait until a worker thread becomes free.this.tasks.push({ task, callback });return;    }const worker =this.freeWorkers.pop();    worker[kTaskInfo] =newWorkerPoolTaskInfo(callback);    worker.postMessage(task);  }close() {for (const workerofthis.workers) worker.terminate();  }}const {AsyncResource } =require('node:async_hooks');const {EventEmitter } =require('node:events');const path =require('node:path');const {Worker } =require('node:worker_threads');const kTaskInfo =Symbol('kTaskInfo');const kWorkerFreedEvent =Symbol('kWorkerFreedEvent');classWorkerPoolTaskInfoextendsAsyncResource {constructor(callback) {super('WorkerPoolTaskInfo');this.callback = callback;  }done(err, result) {this.runInAsyncScope(this.callback,null, err, result);this.emitDestroy();// `TaskInfo`s are used only once.  }}classWorkerPoolextendsEventEmitter {constructor(numThreads) {super();this.numThreads = numThreads;this.workers = [];this.freeWorkers = [];this.tasks = [];for (let i =0; i < numThreads; i++)this.addNewWorker();// Any time the kWorkerFreedEvent is emitted, dispatch// the next task pending in the queue, if any.this.on(kWorkerFreedEvent,() => {if (this.tasks.length >0) {const { task, callback } =this.tasks.shift();this.runTask(task, callback);      }    });  }addNewWorker() {const worker =newWorker(path.resolve(__dirname,'task_processor.js'));    worker.on('message',(result) => {// In case of success: Call the callback that was passed to `runTask`,// remove the `TaskInfo` associated with the Worker, and mark it as free// again.      worker[kTaskInfo].done(null, result);      worker[kTaskInfo] =null;this.freeWorkers.push(worker);this.emit(kWorkerFreedEvent);    });    worker.on('error',(err) => {// In case of an uncaught exception: Call the callback that was passed to// `runTask` with the error.if (worker[kTaskInfo])        worker[kTaskInfo].done(err,null);elsethis.emit('error', err);// Remove the worker from the list and start a new Worker to replace the// current one.this.workers.splice(this.workers.indexOf(worker),1);this.addNewWorker();    });this.workers.push(worker);this.freeWorkers.push(worker);this.emit(kWorkerFreedEvent);  }runTask(task, callback) {if (this.freeWorkers.length ===0) {// No free threads, wait until a worker thread becomes free.this.tasks.push({ task, callback });return;    }const worker =this.freeWorkers.pop();    worker[kTaskInfo] =newWorkerPoolTaskInfo(callback);    worker.postMessage(task);  }close() {for (const workerofthis.workers) worker.terminate();  }}module.exports =WorkerPool;copy

importWorkerPoolfrom'./worker_pool.js';import osfrom'node:os';const pool =newWorkerPool(os.availableParallelism());let finished =0;for (let i =0; i <10; i++) {  pool.runTask({a:42,b:100 },(err, result) => {console.log(i, err, result);if (++finished ===10)      pool.close();  });}constWorkerPool =require('./worker_pool.js');const os =require('node:os');const pool =newWorkerPool(os.availableParallelism());let finished =0;for (let i =0; i <10; i++) {  pool.runTask({a:42,b:100 },(err, result) => {console.log(i, err, result);if (++finished ===10)      pool.close();  });}copy

import { createServer }from'node:http';import {AsyncResource, executionAsyncId }from'node:async_hooks';const server =createServer((req, res) => {  req.on('close',AsyncResource.bind(() => {// Execution context is bound to the current outer scope.  }));  req.on('close',() => {// Execution context is bound to the scope that caused 'close' to emit.  });  res.end();}).listen(3000);const { createServer } =require('node:http');const {AsyncResource, executionAsyncId } =require('node:async_hooks');const server =createServer((req, res) => {  req.on('close',AsyncResource.bind(() => {// Execution context is bound to the current outer scope.  }));  req.on('close',() => {// Execution context is bound to the scope that caused 'close' to emit.  });  res.end();}).listen(3000);copy

Terminology#

An asynchronous resource represents an object with an associated callback.This callback may be called multiple times, such as the'connection'event innet.createServer(), or just a single time like infs.open().A resource can also be closed before the callback is called.AsyncHook doesnot explicitly distinguish between these different cases but will represent themas the abstract concept that is a resource.

IfWorkers are used, each thread has an independentasync_hooksinterface, and each thread will use a new set of async IDs.

Overview#

Following is a simple overview of the public API.

import async_hooksfrom'node:async_hooks';// Return the ID of the current execution context.const eid = async_hooks.executionAsyncId();// Return the ID of the handle responsible for triggering the callback of the// current execution scope to call.const tid = async_hooks.triggerAsyncId();// Create a new AsyncHook instance. All of these callbacks are optional.const asyncHook =    async_hooks.createHook({ init, before, after, destroy, promiseResolve });// Allow callbacks of this AsyncHook instance to call. This is not an implicit// action after running the constructor, and must be explicitly run to begin// executing callbacks.asyncHook.enable();// Disable listening for new asynchronous events.asyncHook.disable();//// The following are the callbacks that can be passed to createHook().//// init() is called during object construction. The resource may not have// completed construction when this callback runs. Therefore, all fields of the// resource referenced by "asyncId" may not have been populated.functioninit(asyncId, type, triggerAsyncId, resource) { }// before() is called just before the resource's callback is called. It can be// called 0-N times for handles (such as TCPWrap), and will be called exactly 1// time for requests (such as FSReqCallback).functionbefore(asyncId) { }// after() is called just after the resource's callback has finished.functionafter(asyncId) { }// destroy() is called when the resource is destroyed.functiondestroy(asyncId) { }// promiseResolve() is called only for promise resources, when the// resolve() function passed to the Promise constructor is invoked// (either directly or through other means of resolving a promise).functionpromiseResolve(asyncId) { }const async_hooks =require('node:async_hooks');// Return the ID of the current execution context.const eid = async_hooks.executionAsyncId();// Return the ID of the handle responsible for triggering the callback of the// current execution scope to call.const tid = async_hooks.triggerAsyncId();// Create a new AsyncHook instance. All of these callbacks are optional.const asyncHook =    async_hooks.createHook({ init, before, after, destroy, promiseResolve });// Allow callbacks of this AsyncHook instance to call. This is not an implicit// action after running the constructor, and must be explicitly run to begin// executing callbacks.asyncHook.enable();// Disable listening for new asynchronous events.asyncHook.disable();//// The following are the callbacks that can be passed to createHook().//// init() is called during object construction. The resource may not have// completed construction when this callback runs. Therefore, all fields of the// resource referenced by "asyncId" may not have been populated.functioninit(asyncId, type, triggerAsyncId, resource) { }// before() is called just before the resource's callback is called. It can be// called 0-N times for handles (such as TCPWrap), and will be called exactly 1// time for requests (such as FSReqCallback).functionbefore(asyncId) { }// after() is called just after the resource's callback has finished.functionafter(asyncId) { }// destroy() is called when the resource is destroyed.functiondestroy(asyncId) { }// promiseResolve() is called only for promise resources, when the// resolve() function passed to the Promise constructor is invoked// (either directly or through other means of resolving a promise).functionpromiseResolve(asyncId) { }copy

async_hooks.createHook(options)#

• options<Object> TheHook Callbacks to register
  • init<Function> Theinit callback.
  • before<Function> Thebefore callback.
  • after<Function> Theafter callback.
  • destroy<Function> Thedestroy callback.
  • promiseResolve<Function> ThepromiseResolve callback.
  • trackPromises<boolean> Whether the hook should trackPromises. Cannot befalse ifpromiseResolve is set.Default:true.
• Returns:<AsyncHook> Instance used for disabling and enabling hooks

Registers functions to be called for different lifetime events of each asyncoperation.

The callbacksinit()/before()/after()/destroy() are called for therespective asynchronous event during a resource's lifetime.

All callbacks are optional. For example, if only resource cleanup needs tobe tracked, then only thedestroy callback needs to be passed. Thespecifics of all functions that can be passed tocallbacks is in theHook Callbacks section.

import { createHook }from'node:async_hooks';const asyncHook =createHook({init(asyncId, type, triggerAsyncId, resource) { },destroy(asyncId) { },});const async_hooks =require('node:async_hooks');const asyncHook = async_hooks.createHook({init(asyncId, type, triggerAsyncId, resource) { },destroy(asyncId) { },});copy

The callbacks will be inherited via the prototype chain:

classMyAsyncCallbacks {init(asyncId, type, triggerAsyncId, resource) { }destroy(asyncId) {}}classMyAddedCallbacksextendsMyAsyncCallbacks {before(asyncId) { }after(asyncId) { }}const asyncHook = async_hooks.createHook(newMyAddedCallbacks());copy

Because promises are asynchronous resources whose lifecycle is trackedvia the async hooks mechanism, theinit(),before(),after(), anddestroy() callbacksmust not be async functions that return promises.

import { writeFileSync }from'node:fs';import { format }from'node:util';functiondebug(...args) {// Use a function like this one when debugging inside an AsyncHook callbackwriteFileSync('log.out',`${format(...args)}\n`, {flag:'a' });}const fs =require('node:fs');const util =require('node:util');functiondebug(...args) {// Use a function like this one when debugging inside an AsyncHook callback  fs.writeFileSync('log.out',`${util.format(...args)}\n`, {flag:'a' });}copy

Class:AsyncHook#

The classAsyncHook exposes an interface for tracking lifetime eventsof asynchronous operations.

import { createHook }from'node:async_hooks';const hook =createHook(callbacks).enable();const async_hooks =require('node:async_hooks');const hook = async_hooks.createHook(callbacks).enable();copy

import { createServer }from'node:net';createServer().listen(function() {this.close(); });// ORclearTimeout(setTimeout(() => {},10));require('node:net').createServer().listen(function() {this.close(); });// ORclearTimeout(setTimeout(() => {},10));copy

import { createHook, executionAsyncId }from'node:async_hooks';import { stdout }from'node:process';import netfrom'node:net';import fsfrom'node:fs';createHook({init(asyncId, type, triggerAsyncId) {const eid =executionAsyncId();    fs.writeSync(      stdout.fd,`${type}(${asyncId}): trigger:${triggerAsyncId} execution:${eid}\n`);  },}).enable();net.createServer((conn) => {}).listen(8080);const { createHook, executionAsyncId } =require('node:async_hooks');const { stdout } =require('node:process');const net =require('node:net');const fs =require('node:fs');createHook({init(asyncId, type, triggerAsyncId) {const eid =executionAsyncId();    fs.writeSync(      stdout.fd,`${type}(${asyncId}): trigger:${triggerAsyncId} execution:${eid}\n`);  },}).enable();net.createServer((conn) => {}).listen(8080);copy

TCPSERVERWRAP(5): trigger: 1 execution: 1TCPWRAP(7): trigger: 5 execution: 0copy

import async_hooksfrom'node:async_hooks';import fsfrom'node:fs';import netfrom'node:net';import { stdout }from'node:process';const { fd } = stdout;let indent =0;async_hooks.createHook({init(asyncId, type, triggerAsyncId) {const eid = async_hooks.executionAsyncId();const indentStr =' '.repeat(indent);    fs.writeSync(      fd,`${indentStr}${type}(${asyncId}):` +` trigger:${triggerAsyncId} execution:${eid}\n`);  },before(asyncId) {const indentStr =' '.repeat(indent);    fs.writeSync(fd,`${indentStr}before:${asyncId}\n`);    indent +=2;  },after(asyncId) {    indent -=2;const indentStr =' '.repeat(indent);    fs.writeSync(fd,`${indentStr}after:${asyncId}\n`);  },destroy(asyncId) {const indentStr =' '.repeat(indent);    fs.writeSync(fd,`${indentStr}destroy:${asyncId}\n`);  },}).enable();net.createServer(() => {}).listen(8080,() => {// Let's wait 10ms before logging the server started.setTimeout(() => {console.log('>>>', async_hooks.executionAsyncId());  },10);});const async_hooks =require('node:async_hooks');const fs =require('node:fs');const net =require('node:net');const { fd } = process.stdout;let indent =0;async_hooks.createHook({init(asyncId, type, triggerAsyncId) {const eid = async_hooks.executionAsyncId();const indentStr =' '.repeat(indent);    fs.writeSync(      fd,`${indentStr}${type}(${asyncId}):` +` trigger:${triggerAsyncId} execution:${eid}\n`);  },before(asyncId) {const indentStr =' '.repeat(indent);    fs.writeSync(fd,`${indentStr}before:${asyncId}\n`);    indent +=2;  },after(asyncId) {    indent -=2;const indentStr =' '.repeat(indent);    fs.writeSync(fd,`${indentStr}after:${asyncId}\n`);  },destroy(asyncId) {const indentStr =' '.repeat(indent);    fs.writeSync(fd,`${indentStr}destroy:${asyncId}\n`);  },}).enable();net.createServer(() => {}).listen(8080,() => {// Let's wait 10ms before logging the server started.setTimeout(() => {console.log('>>>', async_hooks.executionAsyncId());  },10);});copy

TCPSERVERWRAP(5): trigger: 1 execution: 1TickObject(6): trigger: 5 execution: 1before:  6  Timeout(7): trigger: 6 execution: 6after:   6destroy: 6before:  7>>> 7  TickObject(8): trigger: 7 execution: 7after:   7before:  8after:   8copy

  root(1)     ^     |TickObject(6)     ^     | Timeout(7)copy

 bootstrap(1)     |     ˅TCPSERVERWRAP(5)     |     ˅ TickObject(6)     |     ˅  Timeout(7)copy

newPromise((resolve) =>resolve(true)).then((a) => {});copy

init for PROMISE with id 5, trigger id: 1  promise resolve 5      # corresponds to resolve(true)init for PROMISE with id 6, trigger id: 5  # the Promise returned by then()  before 6               # the then() callback is entered  promise resolve 6      # the then() callback resolves the promise by returning  after 6copy

import { open }from'node:fs';import { executionAsyncId, executionAsyncResource }from'node:async_hooks';console.log(executionAsyncId(),executionAsyncResource());// 1 {}open(newURL(import.meta.url),'r',(err, fd) => {console.log(executionAsyncId(),executionAsyncResource());// 7 FSReqWrap});const { open } =require('node:fs');const { executionAsyncId, executionAsyncResource } =require('node:async_hooks');console.log(executionAsyncId(),executionAsyncResource());// 1 {}open(__filename,'r',(err, fd) => {console.log(executionAsyncId(),executionAsyncResource());// 7 FSReqWrap});copy

import { createServer }from'node:http';import {  executionAsyncId,  executionAsyncResource,  createHook,}from'node:async_hooks';const sym =Symbol('state');// Private symbol to avoid pollutioncreateHook({init(asyncId, type, triggerAsyncId, resource) {const cr =executionAsyncResource();if (cr) {      resource[sym] = cr[sym];    }  },}).enable();const server =createServer((req, res) => {executionAsyncResource()[sym] = {state: req.url };setTimeout(function() {    res.end(JSON.stringify(executionAsyncResource()[sym]));  },100);}).listen(3000);const { createServer } =require('node:http');const {  executionAsyncId,  executionAsyncResource,  createHook,} =require('node:async_hooks');const sym =Symbol('state');// Private symbol to avoid pollutioncreateHook({init(asyncId, type, triggerAsyncId, resource) {const cr =executionAsyncResource();if (cr) {      resource[sym] = cr[sym];    }  },}).enable();const server =createServer((req, res) => {executionAsyncResource()[sym] = {state: req.url };setTimeout(function() {    res.end(JSON.stringify(executionAsyncResource()[sym]));  },100);}).listen(3000);copy

import { executionAsyncId }from'node:async_hooks';import fsfrom'node:fs';console.log(executionAsyncId());// 1 - bootstrapconst path ='.';fs.open(path,'r',(err, fd) => {console.log(executionAsyncId());// 6 - open()});const async_hooks =require('node:async_hooks');const fs =require('node:fs');console.log(async_hooks.executionAsyncId());// 1 - bootstrapconst path ='.';fs.open(path,'r',(err, fd) => {console.log(async_hooks.executionAsyncId());// 6 - open()});copy

const server = net.createServer((conn) => {// Returns the ID of the server, not of the new connection, because the// callback runs in the execution scope of the server's MakeCallback().  async_hooks.executionAsyncId();}).listen(port,() => {// Returns the ID of a TickObject (process.nextTick()) because all// callbacks passed to .listen() are wrapped in a nextTick().  async_hooks.executionAsyncId();});copy

const server = net.createServer((conn) => {// The resource that caused (or triggered) this callback to be called// was that of the new connection. Thus the return value of triggerAsyncId()// is the asyncId of "conn".  async_hooks.triggerAsyncId();}).listen(port,() => {// Even though all callbacks passed to .listen() are wrapped in a nextTick()// the callback itself exists because the call to the server's .listen()// was made. So the return value would be the ID of the server.  async_hooks.triggerAsyncId();});copy

Promise execution tracking#

By default, promise executions are not assignedasyncIds due to the relativelyexpensive nature of thepromise introspection API provided byV8. This means that programs using promises orasync/await will not getcorrect execution and trigger ids for promise callback contexts by default.

import { executionAsyncId, triggerAsyncId }from'node:async_hooks';Promise.resolve(1729).then(() => {console.log(`eid${executionAsyncId()} tid${triggerAsyncId()}`);});// produces:// eid 1 tid 0const { executionAsyncId, triggerAsyncId } =require('node:async_hooks');Promise.resolve(1729).then(() => {console.log(`eid${executionAsyncId()} tid${triggerAsyncId()}`);});// produces:// eid 1 tid 0copy

Observe that thethen() callback claims to have executed in the context of theouter scope even though there was an asynchronous hop involved. Also,thetriggerAsyncId value is0, which means that we are missing context aboutthe resource that caused (triggered) thethen() callback to be executed.

Installing async hooks viaasync_hooks.createHook enables promise executiontracking:

import { createHook, executionAsyncId, triggerAsyncId }from'node:async_hooks';createHook({init() {} }).enable();// forces PromiseHooks to be enabled.Promise.resolve(1729).then(() => {console.log(`eid${executionAsyncId()} tid${triggerAsyncId()}`);});// produces:// eid 7 tid 6const { createHook, executionAsyncId, triggerAsyncId } =require('node:async_hooks');createHook({init() {} }).enable();// forces PromiseHooks to be enabled.Promise.resolve(1729).then(() => {console.log(`eid${executionAsyncId()} tid${triggerAsyncId()}`);});// produces:// eid 7 tid 6copy

In this example, adding any actual hook function enabled the tracking ofpromises. There are two promises in the example above; the promise created byPromise.resolve() and the promise returned by the call tothen(). In theexample above, the first promise got theasyncId6 and the latter gotasyncId7. During the execution of thethen() callback, we are executingin the context of promise withasyncId7. This promise was triggered byasync resource6.

Another subtlety with promises is thatbefore andafter callbacks are runonly on chained promises. That means promises not created bythen()/catch()will not have thebefore andafter callbacks fired on them. For more detailssee the details of the V8PromiseHooks API.

const { createHook } =require('node:async_hooks');const { writeSync } =require('node:fs');createHook({init(asyncId, type, triggerAsyncId, resource) {// This init hook does not get called when trackPromises is set to false.writeSync(1,`init hook triggered for${type}\n`);  },trackPromises:false,// Do not track promises.}).enable();Promise.resolve(1729);import { createHook }from'node:async_hooks';import { writeSync }from'node:fs';createHook({init(asyncId, type, triggerAsyncId, resource) {// This init hook does not get called when trackPromises is set to false.writeSync(1,`init hook triggered for${type}\n`);  },trackPromises:false,// Do not track promises.}).enable();Promise.resolve(1729);copy

JavaScript embedder API#

Library developers that handle their own asynchronous resources performing taskslike I/O, connection pooling, or managing callback queues may use theAsyncResource JavaScript API so that all the appropriate callbacks are called.

Class:AsyncLocalStorage#

The documentation for this class has movedAsyncLocalStorage.

Buffers and character encodings#

When converting betweenBuffers and strings, a character encoding may bespecified. If no character encoding is specified, UTF-8 will be used as thedefault.

import {Buffer }from'node:buffer';const buf =Buffer.from('hello world','utf8');console.log(buf.toString('hex'));// Prints: 68656c6c6f20776f726c64console.log(buf.toString('base64'));// Prints: aGVsbG8gd29ybGQ=console.log(Buffer.from('fhqwhgads','utf8'));// Prints: <Buffer 66 68 71 77 68 67 61 64 73>console.log(Buffer.from('fhqwhgads','utf16le'));// Prints: <Buffer 66 00 68 00 71 00 77 00 68 00 67 00 61 00 64 00 73 00>const {Buffer } =require('node:buffer');const buf =Buffer.from('hello world','utf8');console.log(buf.toString('hex'));// Prints: 68656c6c6f20776f726c64console.log(buf.toString('base64'));// Prints: aGVsbG8gd29ybGQ=console.log(Buffer.from('fhqwhgads','utf8'));// Prints: <Buffer 66 68 71 77 68 67 61 64 73>console.log(Buffer.from('fhqwhgads','utf16le'));// Prints: <Buffer 66 00 68 00 71 00 77 00 68 00 67 00 61 00 64 00 73 00>copy

Node.js buffers accept all case variations of encoding strings that theyreceive. For example, UTF-8 can be specified as'utf8','UTF8', or'uTf8'.

The character encodings currently supported by Node.js are the following:

• 'utf8' (alias:'utf-8'): Multi-byte encoded Unicode characters. Many webpages and other document formats useUTF-8. This is the default characterencoding. When decoding aBuffer into a string that does not exclusivelycontain valid UTF-8 data, the Unicode replacement characterU+FFFD � will beused to represent those errors.

• 'utf16le' (alias:'utf-16le'): Multi-byte encoded Unicode characters.Unlike'utf8', each character in the string will be encoded using either 2or 4 bytes. Node.js only supports thelittle-endian variant ofUTF-16.

• 'latin1': Latin-1 stands forISO-8859-1. This character encoding onlysupports the Unicode characters fromU+0000 toU+00FF. Each character isencoded using a single byte. Characters that do not fit into that range aretruncated and will be mapped to characters in that range.

Converting aBuffer into a string using one of the above is referred to asdecoding, and converting a string into aBuffer is referred to as encoding.

Node.js also supports the following binary-to-text encodings. Forbinary-to-text encodings, the naming convention is reversed: Converting aBuffer into a string is typically referred to as encoding, and converting astring into aBuffer as decoding.

• 'base64':Base64 encoding. When creating aBuffer from a string,this encoding will also correctly accept "URL and Filename Safe Alphabet" asspecified inRFC 4648, Section 5. Whitespace characters such as spaces,tabs, and new lines contained within the base64-encoded string are ignored.

• 'base64url':base64url encoding as specified inRFC 4648, Section 5. When creating aBuffer from a string, thisencoding will also correctly accept regular base64-encoded strings. Whenencoding aBuffer to a string, this encoding will omit padding.

• 'hex': Encode each byte as two hexadecimal characters. Data truncationmay occur when decoding strings that do not exclusively consist of an evennumber of hexadecimal characters. See below for an example.

The following legacy character encodings are also supported:

• 'ascii': For 7-bitASCII data only. When encoding a string into aBuffer, this is equivalent to using'latin1'. When decoding aBufferinto a string, using this encoding will additionally unset the highest bit ofeach byte before decoding as'latin1'.Generally, there should be no reason to use this encoding, as'utf8'(or, if the data is known to always be ASCII-only,'latin1') will be abetter choice when encoding or decoding ASCII-only text. It is only providedfor legacy compatibility.

• 'binary': Alias for'latin1'.The name of this encoding can be very misleading, as all of theencodings listed here convert between strings and binary data. For convertingbetween strings andBuffers, typically'utf8' is the right choice.

• 'ucs2','ucs-2': Aliases of'utf16le'. UCS-2 used to refer to a variantof UTF-16 that did not support characters that had code points larger thanU+FFFF. In Node.js, these code points are always supported.

import {Buffer }from'node:buffer';Buffer.from('1ag123','hex');// Prints <Buffer 1a>, data truncated when first non-hexadecimal value// ('g') encountered.Buffer.from('1a7','hex');// Prints <Buffer 1a>, data truncated when data ends in single digit ('7').Buffer.from('1634','hex');// Prints <Buffer 16 34>, all data represented.const {Buffer } =require('node:buffer');Buffer.from('1ag123','hex');// Prints <Buffer 1a>, data truncated when first non-hexadecimal value// ('g') encountered.Buffer.from('1a7','hex');// Prints <Buffer 1a>, data truncated when data ends in single digit ('7').Buffer.from('1634','hex');// Prints <Buffer 16 34>, all data represented.copy

Modern Web browsers follow theWHATWG Encoding Standard which aliasesboth'latin1' and'ISO-8859-1' to'win-1252'. This means that while doingsomething likehttp.get(), if the returned charset is one of those listed inthe WHATWG specification it is possible that the server actually returned'win-1252'-encoded data, and using'latin1' encoding may incorrectly decodethe characters.

Buffers and TypedArrays#

Buffer instances are also JavaScript<Uint8Array> and<TypedArray>instances. All<TypedArray> methods and properties are available onBuffers. There are,however, subtle incompatibilities between theBuffer API and the<TypedArray> API.

In particular:

• WhileTypedArray.prototype.slice() creates a copy of part of theTypedArray,Buffer.prototype.slice() creates a view over the existingBufferwithout copying. This behavior can be surprising, and only exists for legacycompatibility.TypedArray.prototype.subarray() can be used to achievethe behavior ofBuffer.prototype.slice() on bothBuffersand otherTypedArrays and should be preferred.
• buf.toString() is incompatible with itsTypedArray equivalent.
• A number of methods, e.g.buf.indexOf(), support additional arguments.

There are two ways to create new<TypedArray> instances from aBuffer:

• Passing aBuffer to a<TypedArray> constructor will copy theBuffer'scontents, interpreted as an array of integers, and not as a byte sequenceof the target type.

import {Buffer }from'node:buffer';const buf =Buffer.from([1,2,3,4]);const uint32array =newUint32Array(buf);console.log(uint32array);// Prints: Uint32Array(4) [ 1, 2, 3, 4 ]const {Buffer } =require('node:buffer');const buf =Buffer.from([1,2,3,4]);const uint32array =newUint32Array(buf);console.log(uint32array);// Prints: Uint32Array(4) [ 1, 2, 3, 4 ]copy

• Passing theBuffer's underlying<ArrayBuffer> will create a<TypedArray> that shares its memory with theBuffer.

import {Buffer }from'node:buffer';const buf =Buffer.from('hello','utf16le');const uint16array =newUint16Array(  buf.buffer,  buf.byteOffset,  buf.length /Uint16Array.BYTES_PER_ELEMENT);console.log(uint16array);// Prints: Uint16Array(5) [ 104, 101, 108, 108, 111 ]const {Buffer } =require('node:buffer');const buf =Buffer.from('hello','utf16le');const uint16array =newUint16Array(  buf.buffer,  buf.byteOffset,  buf.length /Uint16Array.BYTES_PER_ELEMENT);console.log(uint16array);// Prints: Uint16Array(5) [ 104, 101, 108, 108, 111 ]copy

It is possible to create a newBuffer that shares the same allocatedmemory as a<TypedArray> instance by using theTypedArray object's.buffer property in the same way.Buffer.from()behaves likenew Uint8Array() in this context.

import {Buffer }from'node:buffer';const arr =newUint16Array(2);arr[0] =5000;arr[1] =4000;// Copies the contents of `arr`.const buf1 =Buffer.from(arr);// Shares memory with `arr`.const buf2 =Buffer.from(arr.buffer);console.log(buf1);// Prints: <Buffer 88 a0>console.log(buf2);// Prints: <Buffer 88 13 a0 0f>arr[1] =6000;console.log(buf1);// Prints: <Buffer 88 a0>console.log(buf2);// Prints: <Buffer 88 13 70 17>const {Buffer } =require('node:buffer');const arr =newUint16Array(2);arr[0] =5000;arr[1] =4000;// Copies the contents of `arr`.const buf1 =Buffer.from(arr);// Shares memory with `arr`.const buf2 =Buffer.from(arr.buffer);console.log(buf1);// Prints: <Buffer 88 a0>console.log(buf2);// Prints: <Buffer 88 13 a0 0f>arr[1] =6000;console.log(buf1);// Prints: <Buffer 88 a0>console.log(buf2);// Prints: <Buffer 88 13 70 17>copy

When creating aBuffer using a<TypedArray>'s.buffer, it ispossible to use only a portion of the underlying<ArrayBuffer> by passing inbyteOffset andlength parameters.

import {Buffer }from'node:buffer';const arr =newUint16Array(20);const buf =Buffer.from(arr.buffer,0,16);console.log(buf.length);// Prints: 16const {Buffer } =require('node:buffer');const arr =newUint16Array(20);const buf =Buffer.from(arr.buffer,0,16);console.log(buf.length);// Prints: 16copy

TheBuffer.from() andTypedArray.from() have different signatures andimplementations. Specifically, the<TypedArray> variants accept a secondargument that is a mapping function that is invoked on every element of thetyped array:

• TypedArray.from(source[, mapFn[, thisArg]])

TheBuffer.from() method, however, does not support the use of a mappingfunction:

• Buffer.from(array)
• Buffer.from(buffer)
• Buffer.from(arrayBuffer[, byteOffset[, length]])
• Buffer.from(string[, encoding])

const { toString, write } =Buffer.prototype;const uint8array =newUint8Array(5);write.call(uint8array,'hello',0,5,'utf8');// 5// <Uint8Array 68 65 6c 6c 6f>toString.call(uint8array,'utf8');// 'hello'copy

Buffers and iteration#

Buffer instances can be iterated over usingfor..of syntax:

import {Buffer }from'node:buffer';const buf =Buffer.from([1,2,3]);for (const bof buf) {console.log(b);}// Prints://   1//   2//   3const {Buffer } =require('node:buffer');const buf =Buffer.from([1,2,3]);for (const bof buf) {console.log(b);}// Prints://   1//   2//   3copy

Additionally, thebuf.values(),buf.keys(), andbuf.entries() methods can be used to create iterators.

Class:Blob#

A<Blob> encapsulates immutable, raw data that can be safely shared acrossmultiple worker threads.

const blob =newBlob(['hello']);blob.bytes().then((bytes) => {console.log(bytes);// Outputs: Uint8Array(5) [ 104, 101, 108, 108, 111 ]});copy

import {Blob }from'node:buffer';import {setTimeoutas delay }from'node:timers/promises';const blob =newBlob(['hello there']);const mc1 =newMessageChannel();const mc2 =newMessageChannel();mc1.port1.onmessage =async ({ data }) => {console.log(await data.arrayBuffer());  mc1.port1.close();};mc2.port1.onmessage =async ({ data }) => {awaitdelay(1000);console.log(await data.arrayBuffer());  mc2.port1.close();};mc1.port2.postMessage(blob);mc2.port2.postMessage(blob);// The Blob is still usable after posting.blob.text().then(console.log);const {Blob } =require('node:buffer');const {setTimeout: delay } =require('node:timers/promises');const blob =newBlob(['hello there']);const mc1 =newMessageChannel();const mc2 =newMessageChannel();mc1.port1.onmessage =async ({ data }) => {console.log(await data.arrayBuffer());  mc1.port1.close();};mc2.port1.onmessage =async ({ data }) => {awaitdelay(1000);console.log(await data.arrayBuffer());  mc2.port1.close();};mc1.port2.postMessage(blob);mc2.port2.postMessage(blob);// The Blob is still usable after posting.blob.text().then(console.log);copy

Class:Buffer#

TheBuffer class is a global type for dealing with binary data directly.It can be constructed in a variety of ways.

import {Buffer }from'node:buffer';const buf =Buffer.alloc(5);console.log(buf);// Prints: <Buffer 00 00 00 00 00>const {Buffer } =require('node:buffer');const buf =Buffer.alloc(5);console.log(buf);// Prints: <Buffer 00 00 00 00 00>copy

import {Buffer }from'node:buffer';const buf =Buffer.alloc(5,'a');console.log(buf);// Prints: <Buffer 61 61 61 61 61>const {Buffer } =require('node:buffer');const buf =Buffer.alloc(5,'a');console.log(buf);// Prints: <Buffer 61 61 61 61 61>copy

import {Buffer }from'node:buffer';const buf =Buffer.alloc(11,'aGVsbG8gd29ybGQ=','base64');console.log(buf);// Prints: <Buffer 68 65 6c 6c 6f 20 77 6f 72 6c 64>const {Buffer } =require('node:buffer');const buf =Buffer.alloc(11,'aGVsbG8gd29ybGQ=','base64');console.log(buf);// Prints: <Buffer 68 65 6c 6c 6f 20 77 6f 72 6c 64>copy

import {Buffer }from'node:buffer';const buf =Buffer.allocUnsafe(10);console.log(buf);// Prints (contents may vary): <Buffer a0 8b 28 3f 01 00 00 00 50 32>buf.fill(0);console.log(buf);// Prints: <Buffer 00 00 00 00 00 00 00 00 00 00>const {Buffer } =require('node:buffer');const buf =Buffer.allocUnsafe(10);console.log(buf);// Prints (contents may vary): <Buffer a0 8b 28 3f 01 00 00 00 50 32>buf.fill(0);console.log(buf);// Prints: <Buffer 00 00 00 00 00 00 00 00 00 00>copy

import {Buffer }from'node:buffer';// Need to keep around a few small chunks of memory.const store = [];socket.on('readable',() => {let data;while (null !== (data = readable.read())) {// Allocate for retained data.const sb =Buffer.allocUnsafeSlow(10);// Copy the data into the new allocation.    data.copy(sb,0,0,10);    store.push(sb);  }});const {Buffer } =require('node:buffer');// Need to keep around a few small chunks of memory.const store = [];socket.on('readable',() => {let data;while (null !== (data = readable.read())) {// Allocate for retained data.const sb =Buffer.allocUnsafeSlow(10);// Copy the data into the new allocation.    data.copy(sb,0,0,10);    store.push(sb);  }});copy

import {Buffer }from'node:buffer';const str ='\u00bd + \u00bc = \u00be';console.log(`${str}:${str.length} characters, ` +`${Buffer.byteLength(str,'utf8')} bytes`);// Prints: ½ + ¼ = ¾: 9 characters, 12 bytesconst {Buffer } =require('node:buffer');const str ='\u00bd + \u00bc = \u00be';console.log(`${str}:${str.length} characters, ` +`${Buffer.byteLength(str,'utf8')} bytes`);// Prints: ½ + ¼ = ¾: 9 characters, 12 bytescopy