diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml index d319d377249b8b..428bbf678a34c3 100644 --- a/.github/ISSUE_TEMPLATE/config.yml +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -3,6 +3,6 @@ contact_links: - name: ⁉️ Need help with Node.js? url: https://github.com/nodejs/help about: Please file an issue in our help repo. - - name: 🌐 Found a problem with nodejs.org? + - name: 🌐 Found a problem with nodejs.org beyond the API reference docs? url: https://github.com/nodejs/nodejs.org/issues/new/choose about: Please file an issue in the Node.js website repo. diff --git a/.travis.yml b/.travis.yml index 77694bddf3b05e..de7d7d47f88681 100644 --- a/.travis.yml +++ b/.travis.yml @@ -85,3 +85,4 @@ jobs: - flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics allow_failures: # TODO (cclauss): remove this when dependencies are clean - name: "Find syntax errors in our Python dependencies" + - name: "First commit message adheres to guidelines at https://goo.gl/p2fr5Q" diff --git a/BUILDING.md b/BUILDING.md index b63901297b1a40..448b7711b4d4cc 100644 --- a/BUILDING.md +++ b/BUILDING.md @@ -23,7 +23,7 @@ file a new issue. * [Unix and macOS](#unix-and-macos) * [Unix prerequisites](#unix-prerequisites) * [macOS prerequisites](#macos-prerequisites) - * [Building Node.js](#building-nodejs) + * [Building Node.js](#building-nodejs-1) * [Running Tests](#running-tests) * [Running Coverage](#running-coverage) * [Building the documentation](#building-the-documentation) @@ -31,7 +31,7 @@ file a new issue. * [Windows](#windows) * [Prerequisites](#prerequisites) * [Option 1: Manual install](#option-1-manual-install) - * [Option 1: Automated install with Boxstarter](#option-1-automated-install-with-boxstarter) + * [Option 2: Automated install with Boxstarter](#option-2-automated-install-with-boxstarter) * [Building Node.js](#building-nodejs-1) * [Android/Android-based devices (e.g. Firefox OS)](#androidandroid-based-devices-eg-firefox-os) * [`Intl` (ECMA-402) support](#intl-ecma-402-support) @@ -80,7 +80,7 @@ There are three support tiers: platforms are welcome. Platforms may move between tiers between major release lines. The table below -will be updated to reflect those changes. +will reflect those changes. ### Platform list @@ -113,26 +113,26 @@ platforms. This is true regardless of entries in the table below. | AIX | ppc64be >=power7 | >= 7.2 TL02 | Tier 2 | | | FreeBSD | x64 | >= 11 | Experimental | Downgraded as of Node.js 12 [7](#fn7) | -1: GCC 6 is not provided on the base platform, users will +1: GCC 6 is not provided on the base platform. Users will need the [Toolchain test builds PPA](https://launchpad.net/~ubuntu-toolchain-r/+archive/ubuntu/test?field.series_filter=xenial) or similar to source a newer compiler. -2: GCC 6 is not provided on the base platform, users will +2: GCC 6 is not provided on the base platform. Users will need the [devtoolset-6](https://www.softwarecollections.org/en/scls/rhscl/devtoolset-6/) or later to source a newer compiler. -3: Older kernel versions may work for ARM64, however the +3: Older kernel versions may work for ARM64. However the Node.js test infrastructure only tests >= 4.5. 4: On Windows, running Node.js in Windows terminal emulators like `mintty` requires the usage of [winpty](https://github.com/rprichard/winpty) - for the tty channels to work correctly (e.g. `winpty node.exe script.js`). + for the tty channels to work (e.g. `winpty node.exe script.js`). In "Git bash" if you call the node shell alias (`node` without the `.exe` extension), `winpty` is used automatically. -5: The Windows Subsystem for Linux (WSL) is not directly +5: The Windows Subsystem for Linux (WSL) is not supported, but the GNU/Linux build process and binaries should work. The community will only address issues that reproduce on native GNU/Linux systems. Issues that only reproduce on WSL should be reported in the @@ -142,11 +142,11 @@ platforms. This is true regardless of entries in the table below. 6: Running Node.js on x86 Windows should work and binaries are provided. However, tests in our infrastructure only run on WoW64. -Furthermore, compiling on x86 Windows is currently considered Experimental and +Furthermore, compiling on x86 Windows is Experimental and may not be possible. 7: The default FreeBSD 12.0 compiler is Clang 6.0.1, but -FreeBSD 12.1 upgrades to 8.0.1. Other Clang/LLVM versions are provided +FreeBSD 12.1 upgrades to 8.0.1. Other Clang/LLVM versions are available via the system's package manager, including Clang 9.0. ### Supported toolchains diff --git a/CHANGELOG.md b/CHANGELOG.md index cb947ad02ab90b..15623ce71ab948 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -30,7 +30,8 @@ release. -13.5.0
+13.6.0
+13.5.0
13.4.0
13.3.0
13.2.0
diff --git a/CPP_STYLE_GUIDE.md b/CPP_STYLE_GUIDE.md index f29c8df3210caa..f3dcd4e647b04e 100644 --- a/CPP_STYLE_GUIDE.md +++ b/CPP_STYLE_GUIDE.md @@ -14,9 +14,9 @@ codebase not related to stylistic issues. * [Align function arguments vertically](#align-function-arguments-vertically) * [Initialization lists](#initialization-lists) * [CamelCase for methods, functions, and classes](#camelcase-for-methods-functions-and-classes) - * [snake\_case for local variables and parameters](#snake_case-for-local-variables-and-parameters) - * [snake\_case\_ for private class fields](#snake_case_-for-private-class-fields) - * [snake\_case for C-like structs](#snake_case-for-c-like-structs) + * [`snake_case` for local variables and parameters](#snake_case-for-local-variables-and-parameters) + * [`snake_case_` for private class fields](#snake_case_-for-private-class-fields) + * [`snake_case` for C-like structs](#snake_case-for-c-like-structs) * [Space after `template`](#space-after-template) * [Memory Management](#memory-management) * [Memory allocation](#memory-allocation) @@ -155,7 +155,7 @@ class FooBar { }; ``` -### snake\_case for local variables and parameters +### `snake_case` for local variables and parameters ```c++ int FunctionThatDoesSomething(const char* important_string) { @@ -163,7 +163,7 @@ int FunctionThatDoesSomething(const char* important_string) { } ``` -### snake\_case\_ for private class fields +### `snake_case_` for private class fields ```c++ class Foo { @@ -172,7 +172,8 @@ class Foo { }; ``` -### snake\_case for C-like structs +### `snake_case` for C-like structs + For plain C-like structs snake_case can be used. ```c++ diff --git a/benchmark/README.md b/benchmark/README.md index 7e027c6e76f7b8..c5fdad093471b5 100644 --- a/benchmark/README.md +++ b/benchmark/README.md @@ -74,21 +74,21 @@ The common.js module is used by benchmarks for consistency across repeated tasks. It has a number of helpful functions and properties to help with writing benchmarks. -### createBenchmark(fn, configs\[, options\]) +### `createBenchmark(fn, configs[, options])` See [the guide on writing benchmarks](writing-and-running-benchmarks.md#basics-of-a-benchmark). -### default\_http\_benchmarker +### `default_http_benchmarker` The default benchmarker used to run HTTP benchmarks. See [the guide on writing HTTP benchmarks](writing-and-running-benchmarks.md#creating-an-http-benchmark). -### PORT +### `PORT` The default port used to run HTTP benchmarks. See [the guide on writing HTTP benchmarks](writing-and-running-benchmarks.md#creating-an-http-benchmark). -### sendResult(data) +### `sendResult(data)` Used in special benchmarks that can't use `createBenchmark` and the object it returns to accomplish what they need. This function reports timing diff --git a/benchmark/async_hooks/http-server.js b/benchmark/async_hooks/http-server.js new file mode 100644 index 00000000000000..493500fd1f2d66 --- /dev/null +++ b/benchmark/async_hooks/http-server.js @@ -0,0 +1,40 @@ +'use strict'; +const common = require('../common.js'); + +const bench = common.createBenchmark(main, { + asyncHooks: ['init', 'before', 'after', 'all', 'disabled', 'none'], + connections: [50, 500] +}); + +function main({ asyncHooks, connections }) { + if (asyncHooks !== 'none') { + let hooks = { + init() {}, + before() {}, + after() {}, + destroy() {}, + promiseResolve() {} + }; + if (asyncHooks !== 'all' || asyncHooks !== 'disabled') { + hooks = { + [asyncHooks]: () => {} + }; + } + const hook = require('async_hooks').createHook(hooks); + if (asyncHooks !== 'disabled') { + hook.enable(); + } + } + const server = require('../fixtures/simple-http-server.js') + .listen(common.PORT) + .on('listening', () => { + const path = '/buffer/4/4/normal/1'; + + bench.http({ + connections, + path, + }, () => { + server.close(); + }); + }); +} diff --git a/benchmark/child_process/child-process-exec-stdout.js b/benchmark/child_process/child-process-exec-stdout.js index a1dc4aa04c72a9..f750e2cf3e68f2 100644 --- a/benchmark/child_process/child-process-exec-stdout.js +++ b/benchmark/child_process/child-process-exec-stdout.js @@ -19,7 +19,7 @@ function childProcessExecStdout({ dur, len }) { const cmd = `yes "${'.'.repeat(len)}"`; const child = exec(cmd, { 'stdio': ['ignore', 'pipe', 'ignore'] }); - var bytes = 0; + let bytes = 0; child.stdout.on('data', (msg) => { bytes += msg.length; }); diff --git a/benchmark/child_process/child-process-read-ipc.js b/benchmark/child_process/child-process-read-ipc.js index a9e9cdf7fd7914..827f75b1e54bd1 100644 --- a/benchmark/child_process/child-process-read-ipc.js +++ b/benchmark/child_process/child-process-read-ipc.js @@ -26,7 +26,7 @@ if (process.argv[2] === 'child') { const child = spawn(process.argv[0], [process.argv[1], 'child', len], options); - var bytes = 0; + let bytes = 0; child.on('message', (msg) => { bytes += msg.length; }); setTimeout(() => { diff --git a/benchmark/child_process/child-process-read.js b/benchmark/child_process/child-process-read.js index 3c0144116f589f..01e9846be22b56 100644 --- a/benchmark/child_process/child-process-read.js +++ b/benchmark/child_process/child-process-read.js @@ -24,7 +24,7 @@ function main({ dur, len }) { const options = { 'stdio': ['ignore', 'pipe', 'ignore'] }; const child = child_process.spawn('yes', [msg], options); - var bytes = 0; + let bytes = 0; child.stdout.on('data', (msg) => { bytes += msg.length; }); diff --git a/benchmark/cluster/echo.js b/benchmark/cluster/echo.js index 152f2c42f10f2b..9def87cf8b0e98 100644 --- a/benchmark/cluster/echo.js +++ b/benchmark/cluster/echo.js @@ -19,10 +19,10 @@ if (cluster.isMaster) { serialization }) { const expectedPerBroadcast = sendsPerBroadcast * workers; - var readies = 0; - var broadcasts = 0; - var msgCount = 0; - var data; + let readies = 0; + let broadcasts = 0; + let msgCount = 0; + let data; cluster.settings.serialization = serialization; @@ -37,7 +37,7 @@ if (cluster.isMaster) { throw new Error('Unsupported payload type'); } - for (var i = 0; i < workers; ++i) + for (let i = 0; i < workers; ++i) cluster.fork().on('online', onOnline).on('message', onMessage); function onOnline() { @@ -48,16 +48,15 @@ if (cluster.isMaster) { } function broadcast() { - var id; if (broadcasts++ === n) { bench.end(n); - for (id in cluster.workers) + for (const id in cluster.workers) cluster.workers[id].disconnect(); return; } - for (id in cluster.workers) { + for (const id in cluster.workers) { const worker = cluster.workers[id]; - for (var i = 0; i < sendsPerBroadcast; ++i) + for (let i = 0; i < sendsPerBroadcast; ++i) worker.send(data); } } diff --git a/benchmark/crypto/aes-gcm-throughput.js b/benchmark/crypto/aes-gcm-throughput.js index cd8f29c8c7d7b2..b1b08c481700ea 100644 --- a/benchmark/crypto/aes-gcm-throughput.js +++ b/benchmark/crypto/aes-gcm-throughput.js @@ -25,7 +25,7 @@ function AEAD_Bench(cipher, message, associate_data, key, iv, n, len) { const bits = written * 8; const mbits = bits / (1024 * 1024); - for (var i = 0; i < n; i++) { + for (let i = 0; i < n; i++) { const alice = crypto.createCipheriv(cipher, key, iv); alice.setAAD(associate_data); const enc = alice.update(message); diff --git a/benchmark/crypto/cipher-stream.js b/benchmark/crypto/cipher-stream.js index f426a32769d0dd..4bb1695e2d20cc 100644 --- a/benchmark/crypto/cipher-stream.js +++ b/benchmark/crypto/cipher-stream.js @@ -38,8 +38,8 @@ function main({ api, cipher, type, len, writes }) { const alice_cipher = crypto.createCipher(cipher, alice_secret); const bob_cipher = crypto.createDecipher(cipher, bob_secret); - var message; - var encoding; + let message; + let encoding; switch (type) { case 'asc': message = 'a'.repeat(len); @@ -65,7 +65,7 @@ function main({ api, cipher, type, len, writes }) { } function streamWrite(alice, bob, message, encoding, writes) { - var written = 0; + let written = 0; bob.on('data', (c) => { written += c.length; }); @@ -86,9 +86,9 @@ function streamWrite(alice, bob, message, encoding, writes) { } function legacyWrite(alice, bob, message, encoding, writes) { - var written = 0; - var enc, dec; - for (var i = 0; i < writes; i++) { + let written = 0; + let enc, dec; + for (let i = 0; i < writes; i++) { enc = alice.update(message, encoding); dec = bob.update(enc); written += dec.length; diff --git a/benchmark/crypto/get-ciphers.js b/benchmark/crypto/get-ciphers.js index 5bbe0915311484..1bf910a6a80ba3 100644 --- a/benchmark/crypto/get-ciphers.js +++ b/benchmark/crypto/get-ciphers.js @@ -9,7 +9,7 @@ const bench = common.createBenchmark(main, { function main({ n, v }) { const method = require(v).getCiphers; - var i = 0; + let i = 0; // First call to getCiphers will dominate the results if (n > 1) { for (; i < n; i++) diff --git a/benchmark/crypto/hash-stream-creation.js b/benchmark/crypto/hash-stream-creation.js index 0a98eb1471c9d4..c21eb6eaaaed99 100644 --- a/benchmark/crypto/hash-stream-creation.js +++ b/benchmark/crypto/hash-stream-creation.js @@ -20,8 +20,8 @@ function main({ api, type, len, out, writes, algo }) { api = 'legacy'; } - var message; - var encoding; + let message; + let encoding; switch (type) { case 'asc': message = 'a'.repeat(len); @@ -52,7 +52,7 @@ function legacyWrite(algo, message, encoding, writes, len, outEnc) { while (writes-- > 0) { const h = crypto.createHash(algo); h.update(message, encoding); - var res = h.digest(outEnc); + let res = h.digest(outEnc); // Include buffer creation costs for older versions if (outEnc === 'buffer' && typeof res === 'string') diff --git a/benchmark/crypto/hash-stream-throughput.js b/benchmark/crypto/hash-stream-throughput.js index 52be3d4caf8501..b86d70604616b5 100644 --- a/benchmark/crypto/hash-stream-throughput.js +++ b/benchmark/crypto/hash-stream-throughput.js @@ -19,8 +19,8 @@ function main({ api, type, len, algo, writes }) { api = 'legacy'; } - var message; - var encoding; + let message; + let encoding; switch (type) { case 'asc': message = 'a'.repeat(len); diff --git a/benchmark/crypto/rsa-encrypt-decrypt-throughput.js b/benchmark/crypto/rsa-encrypt-decrypt-throughput.js index 13153c20cad569..9791160263c9ec 100644 --- a/benchmark/crypto/rsa-encrypt-decrypt-throughput.js +++ b/benchmark/crypto/rsa-encrypt-decrypt-throughput.js @@ -35,7 +35,7 @@ function StreamWrite(algo, keylen, message, n, len) { const privateKey = RSA_PrivatePem[keylen]; const publicKey = RSA_PublicPem[keylen]; - for (var i = 0; i < n; i++) { + for (let i = 0; i < n; i++) { const enc = crypto.privateEncrypt(privateKey, message); crypto.publicDecrypt(publicKey, enc); } diff --git a/benchmark/dgram/array-vs-concat.js b/benchmark/dgram/array-vs-concat.js index d260a48063d489..ae9a759a983c04 100644 --- a/benchmark/dgram/array-vs-concat.js +++ b/benchmark/dgram/array-vs-concat.js @@ -18,12 +18,12 @@ const bench = common.createBenchmark(main, { function main({ dur, len, num, type, chunks }) { const chunk = []; - for (var i = 0; i < chunks; i++) { + for (let i = 0; i < chunks; i++) { chunk.push(Buffer.allocUnsafe(Math.round(len / chunks))); } // Server - var sent = 0; + let sent = 0; const socket = dgram.createSocket('udp4'); const onsend = type === 'concat' ? onsendConcat : onsendMulti; @@ -32,7 +32,7 @@ function main({ dur, len, num, type, chunks }) { // The setImmediate() is necessary to have event loop progress on OSes // that only perform synchronous I/O on nonblocking UDP sockets. setImmediate(() => { - for (var i = 0; i < num; i++) { + for (let i = 0; i < num; i++) { socket.send(Buffer.concat(chunk), PORT, '127.0.0.1', onsend); } }); @@ -44,7 +44,7 @@ function main({ dur, len, num, type, chunks }) { // The setImmediate() is necessary to have event loop progress on OSes // that only perform synchronous I/O on nonblocking UDP sockets. setImmediate(() => { - for (var i = 0; i < num; i++) { + for (let i = 0; i < num; i++) { socket.send(chunk, PORT, '127.0.0.1', onsend); } }); diff --git a/benchmark/dgram/bind-params.js b/benchmark/dgram/bind-params.js index ea1f430eed929b..5f7999f7a39241 100644 --- a/benchmark/dgram/bind-params.js +++ b/benchmark/dgram/bind-params.js @@ -15,11 +15,10 @@ const noop = () => {}; function main({ n, port, address }) { port = port === 'true' ? 0 : undefined; address = address === 'true' ? '0.0.0.0' : undefined; - var i; if (port !== undefined && address !== undefined) { bench.start(); - for (i = 0; i < n; i++) { + for (let i = 0; i < n; i++) { dgram.createSocket('udp4').bind(port, address) .on('error', noop) .unref(); @@ -27,7 +26,7 @@ function main({ n, port, address }) { bench.end(n); } else if (port !== undefined) { bench.start(); - for (i = 0; i < n; i++) { + for (let i = 0; i < n; i++) { dgram.createSocket('udp4') .bind(port) .on('error', noop) @@ -36,7 +35,7 @@ function main({ n, port, address }) { bench.end(n); } else if (port === undefined && address === undefined) { bench.start(); - for (i = 0; i < n; i++) { + for (let i = 0; i < n; i++) { dgram.createSocket('udp4') .bind() .on('error', noop) diff --git a/benchmark/dgram/multi-buffer.js b/benchmark/dgram/multi-buffer.js index 7b69a82255ed4b..add77cd7845ce1 100644 --- a/benchmark/dgram/multi-buffer.js +++ b/benchmark/dgram/multi-buffer.js @@ -18,11 +18,11 @@ const bench = common.createBenchmark(main, { function main({ dur, len, num, type, chunks }) { const chunk = []; - for (var i = 0; i < chunks; i++) { + for (let i = 0; i < chunks; i++) { chunk.push(Buffer.allocUnsafe(Math.round(len / chunks))); } - var sent = 0; - var received = 0; + let sent = 0; + let received = 0; const socket = dgram.createSocket('udp4'); function onsend() { @@ -30,7 +30,7 @@ function main({ dur, len, num, type, chunks }) { // The setImmediate() is necessary to have event loop progress on OSes // that only perform synchronous I/O on nonblocking UDP sockets. setImmediate(() => { - for (var i = 0; i < num; i++) { + for (let i = 0; i < num; i++) { socket.send(chunk, PORT, '127.0.0.1', onsend); } }); diff --git a/benchmark/dgram/offset-length.js b/benchmark/dgram/offset-length.js index 696fa6a7a0c0bd..eea0b75b773ca8 100644 --- a/benchmark/dgram/offset-length.js +++ b/benchmark/dgram/offset-length.js @@ -17,8 +17,8 @@ const bench = common.createBenchmark(main, { function main({ dur, len, num, type }) { const chunk = Buffer.allocUnsafe(len); - var sent = 0; - var received = 0; + let sent = 0; + let received = 0; const socket = dgram.createSocket('udp4'); function onsend() { @@ -26,7 +26,7 @@ function main({ dur, len, num, type }) { // The setImmediate() is necessary to have event loop progress on OSes // that only perform synchronous I/O on nonblocking UDP sockets. setImmediate(() => { - for (var i = 0; i < num; i++) { + for (let i = 0; i < num; i++) { socket.send(chunk, 0, chunk.length, PORT, '127.0.0.1', onsend); } }); diff --git a/benchmark/dgram/single-buffer.js b/benchmark/dgram/single-buffer.js index 5c95b17887d37a..b02f785bb052f2 100644 --- a/benchmark/dgram/single-buffer.js +++ b/benchmark/dgram/single-buffer.js @@ -17,8 +17,8 @@ const bench = common.createBenchmark(main, { function main({ dur, len, num, type }) { const chunk = Buffer.allocUnsafe(len); - var sent = 0; - var received = 0; + let sent = 0; + let received = 0; const socket = dgram.createSocket('udp4'); function onsend() { @@ -26,7 +26,7 @@ function main({ dur, len, num, type }) { // The setImmediate() is necessary to have event loop progress on OSes // that only perform synchronous I/O on nonblocking UDP sockets. setImmediate(() => { - for (var i = 0; i < num; i++) { + for (let i = 0; i < num; i++) { socket.send(chunk, PORT, '127.0.0.1', onsend); } }); diff --git a/benchmark/net/net-pipe.js b/benchmark/net/net-pipe.js index f19e30b5450785..06426129f7f271 100644 --- a/benchmark/net/net-pipe.js +++ b/benchmark/net/net-pipe.js @@ -6,7 +6,7 @@ const net = require('net'); const PORT = common.PORT; const bench = common.createBenchmark(main, { - len: [64, 102400, 1024 * 1024 * 16], + len: [2, 64, 102400, 1024 * 1024 * 16], type: ['utf', 'asc', 'buf'], dur: [5], }); diff --git a/benchmark/streams/writable-manywrites.js b/benchmark/streams/writable-manywrites.js index 0ed38d0357a438..049bf8eb281db2 100644 --- a/benchmark/streams/writable-manywrites.js +++ b/benchmark/streams/writable-manywrites.js @@ -5,23 +5,39 @@ const Writable = require('stream').Writable; const bench = common.createBenchmark(main, { n: [2e6], - sync: ['yes', 'no'] + sync: ['yes', 'no'], + writev: ['yes', 'no'], + callback: ['yes', 'no'] }); -function main({ n, sync }) { +function main({ n, sync, writev, callback }) { const b = Buffer.allocUnsafe(1024); const s = new Writable(); sync = sync === 'yes'; - s._write = function(chunk, encoding, cb) { + + const writecb = (cb) => { if (sync) cb(); else process.nextTick(cb); }; + if (writev === 'yes') { + s._writev = (chunks, cb) => writecb(cb); + } else { + s._write = (chunk, encoding, cb) => writecb(cb); + } + + const cb = callback === 'yes' ? () => {} : null; + bench.start(); - for (var k = 0; k < n; ++k) { - s.write(b); + + let k = 0; + function run() { + while (k++ < n && s.write(b, cb)); + if (k >= n) + bench.end(n); } - bench.end(n); + s.on('drain', run); + run(); } diff --git a/benchmark/tls/secure-pair.js b/benchmark/tls/secure-pair.js index c0409febacda00..c52f4cbf918a1d 100644 --- a/benchmark/tls/secure-pair.js +++ b/benchmark/tls/secure-pair.js @@ -2,8 +2,8 @@ const common = require('../common.js'); const bench = common.createBenchmark(main, { dur: [5], - securing: ['SecurePair', 'TLSSocket'], - size: [2, 1024, 1024 * 1024] + securing: ['SecurePair', 'TLSSocket', 'clear'], + size: [2, 100, 1024, 1024 * 1024] }); const fixtures = require('../../test/common/fixtures'); @@ -37,7 +37,8 @@ function main({ dur, size, securing }) { isServer: false, rejectUnauthorized: false, }; - const conn = tls.connect(clientOptions, () => { + const network = securing === 'clear' ? net : tls; + const conn = network.connect(clientOptions, () => { setTimeout(() => { const mbits = (received * 8) / (1024 * 1024); bench.end(mbits); @@ -69,6 +70,9 @@ function main({ dur, size, securing }) { case 'TLSSocket': secureTLSSocket(conn, client); break; + case 'clear': + conn.pipe(client); + break; default: throw new Error('Invalid securing method'); } diff --git a/common.gypi b/common.gypi index 210e86eeb260d5..d0705c772bbf7a 100644 --- a/common.gypi +++ b/common.gypi @@ -39,7 +39,7 @@ # Reset this number to 0 on major V8 upgrades. # Increment by one for each non-official patch applied to deps/v8. - 'v8_embedder_string': '-node.23', + 'v8_embedder_string': '-node.26', ##### V8 defaults for Node.js ##### @@ -333,6 +333,7 @@ [ 'OS in "linux freebsd openbsd solaris android aix cloudabi"', { 'cflags': [ '-Wall', '-Wextra', '-Wno-unused-parameter', ], 'cflags_cc': [ '-fno-rtti', '-fno-exceptions', '-std=gnu++1y' ], + 'defines': [ '__STDC_FORMAT_MACROS' ], 'ldflags': [ '-rdynamic' ], 'target_conditions': [ # The 1990s toolchain on SmartOS can't handle thin archives. diff --git a/configure.py b/configure.py index 95766d405a3f0a..bc6bff224b6515 100755 --- a/configure.py +++ b/configure.py @@ -407,13 +407,12 @@ parser.add_option('--use-largepages', action='store_true', dest='node_use_large_pages', - help='build with Large Pages support. This feature is supported only on Linux kernel' + - '>= 2.6.38 with Transparent Huge pages enabled and FreeBSD') + help='This option has no effect. --use-largepages is now a runtime option.') parser.add_option('--use-largepages-script-lld', action='store_true', dest='node_use_large_pages_script_lld', - help='link against the LLVM ld linker script. Implies -fuse-ld=lld in the linker flags') + help='This option has no effect. --use-largepages is now a runtime option.') intl_optgroup.add_option('--with-intl', action='store', @@ -1068,27 +1067,12 @@ def configure_node(o): else: o['variables']['node_use_dtrace'] = 'false' - if options.node_use_large_pages and not flavor in ('linux', 'freebsd', 'mac'): - raise Exception( - 'Large pages are supported only on Linux, FreeBSD and MacOS Systems.') - if options.node_use_large_pages and flavor in ('linux', 'freebsd', 'mac'): - if options.shared or options.enable_static: - raise Exception( - 'Large pages are supported only while creating node executable.') - if target_arch!="x64": - raise Exception( - 'Large pages are supported only x64 platform.') - if flavor == 'mac': - info('macOS server with 32GB or more is recommended') - if flavor == 'linux': - # Example full version string: 2.6.32-696.28.1.el6.x86_64 - FULL_KERNEL_VERSION=os.uname()[2] - KERNEL_VERSION=FULL_KERNEL_VERSION.split('-')[0] - if KERNEL_VERSION < "2.6.38" and flavor == 'linux': - raise Exception( - 'Large pages need Linux kernel version >= 2.6.38') - o['variables']['node_use_large_pages'] = b(options.node_use_large_pages) - o['variables']['node_use_large_pages_script_lld'] = b(options.node_use_large_pages_script_lld) + if options.node_use_large_pages or options.node_use_large_pages_script_lld: + warn('''The `--use-largepages` and `--use-largepages-script-lld` options + have no effect during build time. Support for mapping to large pages is + now a runtime option of Node.js. Run `node --use-largepages` or add + `--use-largepages` to the `NODE_OPTIONS` environment variable once + Node.js is built to enable mapping to large pages.''') if options.no_ifaddrs: o['defines'] += ['SUNOS_NO_IFADDRS'] diff --git a/deps/uvwasi/include/fd_table.h b/deps/uvwasi/include/fd_table.h index 42a5f0d920ff6e..639ff9abc8d34f 100644 --- a/deps/uvwasi/include/fd_table.h +++ b/deps/uvwasi/include/fd_table.h @@ -6,33 +6,22 @@ #include "wasi_types.h" #include "uv_mapping.h" -/* TODO(cjihrig): PATH_MAX_BYTES shouldn't be stack allocated. On Windows, paths - can be 32k long, and this PATH_MAX_BYTES is an artificial limitation. */ -#ifdef _WIN32 -/* MAX_PATH is in characters, not bytes. Make sure we have enough headroom. */ -# define PATH_MAX_BYTES (MAX_PATH * 4) -#else -# include -# define PATH_MAX_BYTES (PATH_MAX) -#endif - struct uvwasi_s; struct uvwasi_fd_wrap_t { uvwasi_fd_t id; uv_file fd; - char path[PATH_MAX_BYTES]; - char real_path[PATH_MAX_BYTES]; + char* path; + char* real_path; uvwasi_filetype_t type; uvwasi_rights_t rights_base; uvwasi_rights_t rights_inheriting; int preopen; - int valid; uv_mutex_t mutex; }; struct uvwasi_fd_table_t { - struct uvwasi_fd_wrap_t* fds; + struct uvwasi_fd_wrap_t** fds; uint32_t size; uint32_t used; uv_rwlock_t rwlock; @@ -61,7 +50,8 @@ uvwasi_errno_t uvwasi_fd_table_get(const struct uvwasi_fd_table_t* table, struct uvwasi_fd_wrap_t** wrap, uvwasi_rights_t rights_base, uvwasi_rights_t rights_inheriting); -uvwasi_errno_t uvwasi_fd_table_remove(struct uvwasi_fd_table_t* table, +uvwasi_errno_t uvwasi_fd_table_remove(struct uvwasi_s* uvwasi, + struct uvwasi_fd_table_t* table, const uvwasi_fd_t id); #endif /* __UVWASI_FD_TABLE_H__ */ diff --git a/deps/uvwasi/include/uvwasi.h b/deps/uvwasi/include/uvwasi.h index 2a4e389164357d..2fbcbc583dcbfb 100644 --- a/deps/uvwasi/include/uvwasi.h +++ b/deps/uvwasi/include/uvwasi.h @@ -11,7 +11,7 @@ extern "C" { #define UVWASI_VERSION_MAJOR 0 #define UVWASI_VERSION_MINOR 0 -#define UVWASI_VERSION_PATCH 1 +#define UVWASI_VERSION_PATCH 3 #define UVWASI_VERSION_HEX ((UVWASI_VERSION_MAJOR << 16) | \ (UVWASI_VERSION_MINOR << 8) | \ (UVWASI_VERSION_PATCH)) @@ -20,7 +20,7 @@ extern "C" { #define UVWASI_VERSION_STRING UVWASI_STRINGIFY(UVWASI_VERSION_MAJOR) "." \ UVWASI_STRINGIFY(UVWASI_VERSION_MINOR) "." \ UVWASI_STRINGIFY(UVWASI_VERSION_PATCH) -#define UVWASI_VERSION_WASI "snapshot_0" +#define UVWASI_VERSION_WASI "snapshot_1" typedef void* (*uvwasi_malloc)(size_t size, void* mem_user_data); typedef void (*uvwasi_free)(void* ptr, void* mem_user_data); @@ -69,6 +69,7 @@ void uvwasi_destroy(uvwasi_t* uvwasi); uvwasi_errno_t uvwasi_embedder_remap_fd(uvwasi_t* uvwasi, const uvwasi_fd_t fd, uv_file new_host_fd); +const char* uvwasi_embedder_err_code_to_string(uvwasi_errno_t code); // WASI system call API. diff --git a/deps/uvwasi/include/wasi_types.h b/deps/uvwasi/include/wasi_types.h index 34b5291c577627..ec1013663f6a76 100644 --- a/deps/uvwasi/include/wasi_types.h +++ b/deps/uvwasi/include/wasi_types.h @@ -155,7 +155,7 @@ typedef struct uvwasi_iovec_s { size_t buf_len; } uvwasi_iovec_t; -typedef uint32_t uvwasi_linkcount_t; +typedef uint64_t uvwasi_linkcount_t; typedef uint32_t uvwasi_lookupflags_t; /* Bitfield */ #define UVWASI_LOOKUP_SYMLINK_FOLLOW (1 << 0) @@ -266,7 +266,6 @@ typedef struct uvwasi_subscription_s { uvwasi_eventtype_t type; union { struct { - uvwasi_userdata_t identifier; uvwasi_clockid_t clock_id; uvwasi_timestamp_t timeout; uvwasi_timestamp_t precision; @@ -316,8 +315,8 @@ typedef struct uvwasi_event_s { } uvwasi_event_t; typedef uint8_t uvwasi_whence_t; -#define UVWASI_WHENCE_CUR 0 -#define UVWASI_WHENCE_END 1 -#define UVWASI_WHENCE_SET 2 +#define UVWASI_WHENCE_SET 0 +#define UVWASI_WHENCE_CUR 1 +#define UVWASI_WHENCE_END 2 #endif /* __UVWASI_WASI_TYPES_H__ */ diff --git a/deps/uvwasi/src/fd_table.c b/deps/uvwasi/src/fd_table.c index f716495e9a02b2..f3855d4da54dbe 100644 --- a/deps/uvwasi/src/fd_table.c +++ b/deps/uvwasi/src/fd_table.c @@ -187,12 +187,29 @@ static uvwasi_errno_t uvwasi__fd_table_insert(uvwasi_t* uvwasi, int preopen, struct uvwasi_fd_wrap_t** wrap) { struct uvwasi_fd_wrap_t* entry; - struct uvwasi_fd_wrap_t* new_fds; + struct uvwasi_fd_wrap_t** new_fds; uvwasi_errno_t err; uint32_t new_size; int index; uint32_t i; int r; + size_t mp_len; + char* mp_copy; + size_t rp_len; + char* rp_copy; + + mp_len = strlen(mapped_path); + rp_len = strlen(real_path); + entry = (struct uvwasi_fd_wrap_t*) + uvwasi__malloc(uvwasi, sizeof(*entry) + mp_len + rp_len + 2); + if (entry == NULL) return UVWASI_ENOMEM; + + mp_copy = (char*)(entry + 1); + rp_copy = mp_copy + mp_len + 1; + memcpy(mp_copy, mapped_path, mp_len); + mp_copy[mp_len] = '\0'; + memcpy(rp_copy, real_path, rp_len); + rp_copy[rp_len] = '\0'; uv_rwlock_wrlock(&table->rwlock); @@ -201,12 +218,13 @@ static uvwasi_errno_t uvwasi__fd_table_insert(uvwasi_t* uvwasi, new_size = table->size * 2; new_fds = uvwasi__realloc(uvwasi, table->fds, new_size * sizeof(*new_fds)); if (new_fds == NULL) { + uvwasi__free(uvwasi, entry); err = UVWASI_ENOMEM; goto exit; } for (i = table->size; i < new_size; ++i) - new_fds[i].valid = 0; + new_fds[i] = NULL; index = table->size; table->fds = new_fds; @@ -215,7 +233,7 @@ static uvwasi_errno_t uvwasi__fd_table_insert(uvwasi_t* uvwasi, /* The table is big enough, so find an empty slot for the new data. */ index = -1; for (i = 0; i < table->size; ++i) { - if (table->fds[i].valid != 1) { + if (table->fds[i] == NULL) { index = i; break; } @@ -223,12 +241,13 @@ static uvwasi_errno_t uvwasi__fd_table_insert(uvwasi_t* uvwasi, /* index should never be -1. */ if (index == -1) { + uvwasi__free(uvwasi, entry); err = UVWASI_ENOSPC; goto exit; } } - entry = &table->fds[index]; + table->fds[index] = entry; r = uv_mutex_init(&entry->mutex); if (r != 0) { @@ -238,13 +257,12 @@ static uvwasi_errno_t uvwasi__fd_table_insert(uvwasi_t* uvwasi, entry->id = index; entry->fd = fd; - strcpy(entry->path, mapped_path); - strcpy(entry->real_path, real_path); + entry->path = mp_copy; + entry->real_path = rp_copy; entry->type = type; entry->rights_base = rights_base; entry->rights_inheriting = rights_inheriting; entry->preopen = preopen; - entry->valid = 1; table->used++; if (wrap != NULL) @@ -273,19 +291,25 @@ uvwasi_errno_t uvwasi_fd_table_init(uvwasi_t* uvwasi, return UVWASI_EINVAL; table->fds = NULL; - r = uv_rwlock_init(&table->rwlock); - if (r != 0) - return uvwasi__translate_uv_error(r); - table->used = 0; table->size = init_size; table->fds = uvwasi__calloc(uvwasi, init_size, - sizeof(struct uvwasi_fd_wrap_t)); + sizeof(struct uvwasi_fd_wrap_t*)); + + if (table->fds == NULL) + return UVWASI_ENOMEM; - if (table->fds == NULL) { - err = UVWASI_ENOMEM; - goto error_exit; + r = uv_rwlock_init(&table->rwlock); + if (r != 0) { + err = uvwasi__translate_uv_error(r); + /* Free table->fds and set it to NULL here. This is done explicitly instead + of jumping to error_exit because uvwasi_fd_table_free() relies on fds + being NULL to know whether or not to destroy the rwlock. + */ + uvwasi__free(uvwasi, table->fds); + table->fds = NULL; + return err; } /* Create the stdio FDs. */ @@ -325,14 +349,27 @@ uvwasi_errno_t uvwasi_fd_table_init(uvwasi_t* uvwasi, void uvwasi_fd_table_free(uvwasi_t* uvwasi, struct uvwasi_fd_table_t* table) { + struct uvwasi_fd_wrap_t* entry; + uint32_t i; + if (table == NULL) return; - uvwasi__free(uvwasi, table->fds); - table->fds = NULL; - table->size = 0; - table->used = 0; - uv_rwlock_destroy(&table->rwlock); + for (i = 0; i < table->size; i++) { + entry = table->fds[i]; + if (entry == NULL) continue; + + uv_mutex_destroy(&entry->mutex); + uvwasi__free(uvwasi, entry); + } + + if (table->fds != NULL) { + uvwasi__free(uvwasi, table->fds); + table->fds = NULL; + table->size = 0; + table->used = 0; + uv_rwlock_destroy(&table->rwlock); + } } @@ -430,9 +467,9 @@ uvwasi_errno_t uvwasi_fd_table_get(const struct uvwasi_fd_table_t* table, goto exit; } - entry = &table->fds[id]; + entry = table->fds[id]; - if (entry->valid != 1 || entry->id != id) { + if (entry == NULL || entry->id != id) { err = UVWASI_EBADF; goto exit; } @@ -453,7 +490,8 @@ uvwasi_errno_t uvwasi_fd_table_get(const struct uvwasi_fd_table_t* table, } -uvwasi_errno_t uvwasi_fd_table_remove(struct uvwasi_fd_table_t* table, +uvwasi_errno_t uvwasi_fd_table_remove(uvwasi_t* uvwasi, + struct uvwasi_fd_table_t* table, const uvwasi_fd_t id) { struct uvwasi_fd_wrap_t* entry; uvwasi_errno_t err; @@ -468,15 +506,16 @@ uvwasi_errno_t uvwasi_fd_table_remove(struct uvwasi_fd_table_t* table, goto exit; } - entry = &table->fds[id]; + entry = table->fds[id]; - if (entry->valid != 1 || entry->id != id) { + if (entry == NULL || entry->id != id) { err = UVWASI_EBADF; goto exit; } uv_mutex_destroy(&entry->mutex); - entry->valid = 0; + uvwasi__free(uvwasi, entry); + table->fds[id] = NULL; table->used--; err = UVWASI_ESUCCESS; exit: diff --git a/deps/uvwasi/src/uvwasi.c b/deps/uvwasi/src/uvwasi.c index 0f7c4c5d3aa0ef..28c6dcc26104c9 100644 --- a/deps/uvwasi/src/uvwasi.c +++ b/deps/uvwasi/src/uvwasi.c @@ -25,6 +25,16 @@ #include "fd_table.h" #include "clocks.h" +/* TODO(cjihrig): PATH_MAX_BYTES shouldn't be stack allocated. On Windows, paths + can be 32k long, and this PATH_MAX_BYTES is an artificial limitation. */ +#ifdef _WIN32 +/* MAX_PATH is in characters, not bytes. Make sure we have enough headroom. */ +# define PATH_MAX_BYTES (MAX_PATH * 4) +#else +# include +# define PATH_MAX_BYTES (PATH_MAX) +#endif + static void* default_malloc(size_t size, void* mem_user_data) { return malloc(size); } @@ -688,7 +698,7 @@ uvwasi_errno_t uvwasi_fd_close(uvwasi_t* uvwasi, uvwasi_fd_t fd) { if (r != 0) return uvwasi__translate_uv_error(r); - return uvwasi_fd_table_remove(&uvwasi->fds, fd); + return uvwasi_fd_table_remove(uvwasi, &uvwasi->fds, fd); } @@ -1319,7 +1329,7 @@ uvwasi_errno_t uvwasi_fd_renumber(uvwasi_t* uvwasi, to_wrap->id = to; uv_mutex_unlock(&from_wrap->mutex); uv_mutex_unlock(&to_wrap->mutex); - return uvwasi_fd_table_remove(&uvwasi->fds, from); + return uvwasi_fd_table_remove(uvwasi, &uvwasi->fds, from); } @@ -1773,7 +1783,7 @@ uvwasi_errno_t uvwasi_path_open(uvwasi_t* uvwasi, if ((o_flags & UVWASI_O_DIRECTORY) != 0 && wrap.type != UVWASI_FILETYPE_DIRECTORY) { uv_mutex_unlock(&dirfd_wrap->mutex); - uvwasi_fd_table_remove(&uvwasi->fds, wrap.id); + uvwasi_fd_table_remove(uvwasi, &uvwasi->fds, wrap.id); err = UVWASI_ENOTDIR; goto close_file_and_error_exit; } @@ -2140,3 +2150,90 @@ uvwasi_errno_t uvwasi_sock_shutdown(uvwasi_t* uvwasi, https://github.com/WebAssembly/WASI/issues/4 */ return UVWASI_ENOTSUP; } + + +const char* uvwasi_embedder_err_code_to_string(uvwasi_errno_t code) { + switch (code) { +#define V(errcode) case errcode: return #errcode; + V(UVWASI_E2BIG) + V(UVWASI_EACCES) + V(UVWASI_EADDRINUSE) + V(UVWASI_EADDRNOTAVAIL) + V(UVWASI_EAFNOSUPPORT) + V(UVWASI_EAGAIN) + V(UVWASI_EALREADY) + V(UVWASI_EBADF) + V(UVWASI_EBADMSG) + V(UVWASI_EBUSY) + V(UVWASI_ECANCELED) + V(UVWASI_ECHILD) + V(UVWASI_ECONNABORTED) + V(UVWASI_ECONNREFUSED) + V(UVWASI_ECONNRESET) + V(UVWASI_EDEADLK) + V(UVWASI_EDESTADDRREQ) + V(UVWASI_EDOM) + V(UVWASI_EDQUOT) + V(UVWASI_EEXIST) + V(UVWASI_EFAULT) + V(UVWASI_EFBIG) + V(UVWASI_EHOSTUNREACH) + V(UVWASI_EIDRM) + V(UVWASI_EILSEQ) + V(UVWASI_EINPROGRESS) + V(UVWASI_EINTR) + V(UVWASI_EINVAL) + V(UVWASI_EIO) + V(UVWASI_EISCONN) + V(UVWASI_EISDIR) + V(UVWASI_ELOOP) + V(UVWASI_EMFILE) + V(UVWASI_EMLINK) + V(UVWASI_EMSGSIZE) + V(UVWASI_EMULTIHOP) + V(UVWASI_ENAMETOOLONG) + V(UVWASI_ENETDOWN) + V(UVWASI_ENETRESET) + V(UVWASI_ENETUNREACH) + V(UVWASI_ENFILE) + V(UVWASI_ENOBUFS) + V(UVWASI_ENODEV) + V(UVWASI_ENOENT) + V(UVWASI_ENOEXEC) + V(UVWASI_ENOLCK) + V(UVWASI_ENOLINK) + V(UVWASI_ENOMEM) + V(UVWASI_ENOMSG) + V(UVWASI_ENOPROTOOPT) + V(UVWASI_ENOSPC) + V(UVWASI_ENOSYS) + V(UVWASI_ENOTCONN) + V(UVWASI_ENOTDIR) + V(UVWASI_ENOTEMPTY) + V(UVWASI_ENOTRECOVERABLE) + V(UVWASI_ENOTSOCK) + V(UVWASI_ENOTSUP) + V(UVWASI_ENOTTY) + V(UVWASI_ENXIO) + V(UVWASI_EOVERFLOW) + V(UVWASI_EOWNERDEAD) + V(UVWASI_EPERM) + V(UVWASI_EPIPE) + V(UVWASI_EPROTO) + V(UVWASI_EPROTONOSUPPORT) + V(UVWASI_EPROTOTYPE) + V(UVWASI_ERANGE) + V(UVWASI_EROFS) + V(UVWASI_ESPIPE) + V(UVWASI_ESRCH) + V(UVWASI_ESTALE) + V(UVWASI_ETIMEDOUT) + V(UVWASI_ETXTBSY) + V(UVWASI_EXDEV) + V(UVWASI_ENOTCAPABLE) + V(UVWASI_ESUCCESS) +#undef V + default: + return "UVWASI_UNKNOWN_ERROR"; + } +} diff --git a/deps/v8/src/base/platform/platform-freebsd.cc b/deps/v8/src/base/platform/platform-freebsd.cc index d40452f3d48417..8d63dd2f84df34 100644 --- a/deps/v8/src/base/platform/platform-freebsd.cc +++ b/deps/v8/src/base/platform/platform-freebsd.cc @@ -13,10 +13,12 @@ #include #include #include +#include #include // open #include // mmap & munmap #include // open +#include #include // getpagesize // If you don't have execinfo.h then you need devel/libexecinfo from ports. #include @@ -46,41 +48,47 @@ static unsigned StringToLong(char* buffer) { std::vector OS::GetSharedLibraryAddresses() { std::vector result; - static const int MAP_LENGTH = 1024; - int fd = open("/proc/self/maps", O_RDONLY); - if (fd < 0) return result; - while (true) { - char addr_buffer[11]; - addr_buffer[0] = '0'; - addr_buffer[1] = 'x'; - addr_buffer[10] = 0; - ssize_t bytes_read = read(fd, addr_buffer + 2, 8); - if (bytes_read < 8) break; - unsigned start = StringToLong(addr_buffer); - bytes_read = read(fd, addr_buffer + 2, 1); - if (bytes_read < 1) break; - if (addr_buffer[2] != '-') break; - bytes_read = read(fd, addr_buffer + 2, 8); - if (bytes_read < 8) break; - unsigned end = StringToLong(addr_buffer); - char buffer[MAP_LENGTH]; - bytes_read = -1; - do { - bytes_read++; - if (bytes_read >= MAP_LENGTH - 1) break; - bytes_read = read(fd, buffer + bytes_read, 1); - if (bytes_read < 1) break; - } while (buffer[bytes_read] != '\n'); - buffer[bytes_read] = 0; - // Ignore mappings that are not executable. - if (buffer[3] != 'x') continue; - char* start_of_path = index(buffer, '/'); - // There may be no filename in this line. Skip to next. - if (start_of_path == nullptr) continue; - buffer[bytes_read] = 0; - result.push_back(SharedLibraryAddress(start_of_path, start, end)); + int mib[4] = {CTL_KERN, KERN_PROC, KERN_PROC_VMMAP, getpid()}; + size_t miblen = sizeof(mib) / sizeof(mib[0]); + size_t buffer_size; + if (sysctl(mib, miblen, nullptr, &buffer_size, nullptr, 0) == 0) { + // Overallocate the buffer by 1/3 to account for concurrent + // kinfo_vmentry change. 1/3 is an arbitrary constant that + // works in practice. + buffer_size = buffer_size * 4 / 3; + std::vector buffer(buffer_size); + int ret = sysctl(mib, miblen, buffer.data(), &buffer_size, nullptr, 0); + + if (ret == 0 || (ret == -1 && errno == ENOMEM)) { + char* start = buffer.data(); + char* end = start + buffer_size; + + while (start < end) { + struct kinfo_vmentry* map = + reinterpret_cast(start); + const size_t ssize = map->kve_structsize; + char* path = map->kve_path; + + CHECK_NE(0, ssize); + + if ((map->kve_protection & KVME_PROT_READ) != 0 && + (map->kve_protection & KVME_PROT_EXEC) != 0 && path[0] != '\0') { + char* sep = strrchr(path, '/'); + std::string lib_name; + if (sep != nullptr) { + lib_name = std::string(++sep); + } else { + lib_name = std::string(path); + } + result.push_back(SharedLibraryAddress( + lib_name, reinterpret_cast(map->kve_start), + reinterpret_cast(map->kve_end))); + } + + start += ssize; + } + } } - close(fd); return result; } diff --git a/deps/v8/src/base/platform/time.cc b/deps/v8/src/base/platform/time.cc index ecbd70fd743387..f07fd8e595fc60 100644 --- a/deps/v8/src/base/platform/time.cc +++ b/deps/v8/src/base/platform/time.cc @@ -70,6 +70,9 @@ V8_INLINE int64_t ClockNow(clockid_t clk_id) { #if defined(V8_OS_AIX) thread_cputime_t tc; if (clk_id == CLOCK_THREAD_CPUTIME_ID) { +#if defined(__PASE__) // CLOCK_THREAD_CPUTIME_ID clock not supported on IBMi + return 0; +#endif if (thread_cputime(-1, &tc) != 0) { UNREACHABLE(); } diff --git a/deps/v8/src/heap/heap.cc b/deps/v8/src/heap/heap.cc index 45b2273c50d688..7cfc36662d052f 100644 --- a/deps/v8/src/heap/heap.cc +++ b/deps/v8/src/heap/heap.cc @@ -2761,6 +2761,14 @@ HeapObject Heap::AlignWithFiller(HeapObject object, int object_size, void* Heap::AllocateExternalBackingStore( const std::function& allocate, size_t byte_length) { + size_t new_space_backing_store_bytes = + new_space()->ExternalBackingStoreBytes(); + if (new_space_backing_store_bytes >= 2 * kMaxSemiSpaceSize && + new_space_backing_store_bytes >= byte_length) { + // Performing a young generation GC amortizes over the allocated backing + // store bytes and may free enough external bytes for this allocation. + CollectGarbage(NEW_SPACE, GarbageCollectionReason::kExternalMemoryPressure); + } // TODO(ulan): Perform GCs proactively based on the byte_length and // the current external backing store counters. void* result = allocate(byte_length); diff --git a/deps/v8/src/heap/heap.h b/deps/v8/src/heap/heap.h index 182096f29c78d2..877aba01c09aa3 100644 --- a/deps/v8/src/heap/heap.h +++ b/deps/v8/src/heap/heap.h @@ -1793,10 +1793,6 @@ class Heap { void FinalizePartialMap(Map map); - // Allocate empty fixed typed array of given type. - V8_WARN_UNUSED_RESULT AllocationResult - AllocateEmptyFixedTypedArray(ExternalArrayType array_type); - void set_force_oom(bool value) { force_oom_ = value; } // =========================================================================== diff --git a/deps/v8/src/heap/spaces.h b/deps/v8/src/heap/spaces.h index 5652042d20c131..5ec281ee074aee 100644 --- a/deps/v8/src/heap/spaces.h +++ b/deps/v8/src/heap/spaces.h @@ -2804,14 +2804,14 @@ class V8_EXPORT_PRIVATE NewSpace void Shrink(); // Return the allocated bytes in the active semispace. - size_t Size() override { + size_t Size() final { DCHECK_GE(top(), to_space_.page_low()); return to_space_.pages_used() * MemoryChunkLayout::AllocatableMemoryInDataPage() + static_cast(top() - to_space_.page_low()); } - size_t SizeOfObjects() override { return Size(); } + size_t SizeOfObjects() final { return Size(); } // Return the allocatable capacity of a semispace. size_t Capacity() { @@ -2829,30 +2829,38 @@ class V8_EXPORT_PRIVATE NewSpace // Committed memory for NewSpace is the committed memory of both semi-spaces // combined. - size_t CommittedMemory() override { + size_t CommittedMemory() final { return from_space_.CommittedMemory() + to_space_.CommittedMemory(); } - size_t MaximumCommittedMemory() override { + size_t MaximumCommittedMemory() final { return from_space_.MaximumCommittedMemory() + to_space_.MaximumCommittedMemory(); } // Approximate amount of physical memory committed for this space. - size_t CommittedPhysicalMemory() override; + size_t CommittedPhysicalMemory() final; // Return the available bytes without growing. - size_t Available() override { + size_t Available() final { DCHECK_GE(Capacity(), Size()); return Capacity() - Size(); } - size_t ExternalBackingStoreBytes( - ExternalBackingStoreType type) const override { + size_t ExternalBackingStoreBytes(ExternalBackingStoreType type) const final { DCHECK_EQ(0, from_space_.ExternalBackingStoreBytes(type)); return to_space_.ExternalBackingStoreBytes(type); } + size_t ExternalBackingStoreBytes() { + size_t result = 0; + for (int i = 0; i < ExternalBackingStoreType::kNumTypes; i++) { + result += + ExternalBackingStoreBytes(static_cast(i)); + } + return result; + } + size_t AllocatedSinceLastGC() { const Address age_mark = to_space_.age_mark(); DCHECK_NE(age_mark, kNullAddress); diff --git a/deps/v8/src/objects/objects.cc b/deps/v8/src/objects/objects.cc index 227cff8da47a33..723023b707947f 100644 --- a/deps/v8/src/objects/objects.cc +++ b/deps/v8/src/objects/objects.cc @@ -4038,6 +4038,13 @@ Handle PrototypeUsers::Add(Isolate* isolate, // If there are empty slots, use one of them. int empty_slot = Smi::ToInt(empty_slot_index(*array)); + + if (empty_slot == kNoEmptySlotsMarker) { + // GCs might have cleared some references, rescan the array for empty slots. + PrototypeUsers::ScanForEmptySlots(*array); + empty_slot = Smi::ToInt(empty_slot_index(*array)); + } + if (empty_slot != kNoEmptySlotsMarker) { DCHECK_GE(empty_slot, kFirstIndex); CHECK_LT(empty_slot, array->length()); @@ -4060,6 +4067,15 @@ Handle PrototypeUsers::Add(Isolate* isolate, return array; } +// static +void PrototypeUsers::ScanForEmptySlots(WeakArrayList array) { + for (int i = kFirstIndex; i < array.length(); i++) { + if (array.Get(i)->IsCleared()) { + PrototypeUsers::MarkSlotEmpty(array, i); + } + } +} + WeakArrayList PrototypeUsers::Compact(Handle array, Heap* heap, CompactionCallback callback, AllocationType allocation) { diff --git a/deps/v8/src/objects/prototype-info.h b/deps/v8/src/objects/prototype-info.h index 94d86d2e1931c3..6f777eda8936c8 100644 --- a/deps/v8/src/objects/prototype-info.h +++ b/deps/v8/src/objects/prototype-info.h @@ -99,7 +99,7 @@ class V8_EXPORT_PRIVATE PrototypeUsers : public WeakArrayList { static inline Smi empty_slot_index(WeakArrayList array); static inline void set_empty_slot_index(WeakArrayList array, int index); - static void IsSlotEmpty(WeakArrayList array, int index); + static void ScanForEmptySlots(WeakArrayList array); DISALLOW_IMPLICIT_CONSTRUCTORS(PrototypeUsers); }; diff --git a/deps/v8/test/cctest/heap/test-heap.cc b/deps/v8/test/cctest/heap/test-heap.cc index 03f98c64537f22..53454f3e2f409a 100644 --- a/deps/v8/test/cctest/heap/test-heap.cc +++ b/deps/v8/test/cctest/heap/test-heap.cc @@ -6823,6 +6823,27 @@ TEST(CodeObjectRegistry) { CHECK(MemoryChunk::FromAddress(code2_address)->Contains(code2_address)); } +TEST(Regress9701) { + ManualGCScope manual_gc_scope; + if (!FLAG_incremental_marking) return; + CcTest::InitializeVM(); + Heap* heap = CcTest::heap(); + // Start with an empty new space. + CcTest::CollectGarbage(NEW_SPACE); + CcTest::CollectGarbage(NEW_SPACE); + + int mark_sweep_count_before = heap->ms_count(); + // Allocate many short living array buffers. + for (int i = 0; i < 1000; i++) { + HandleScope scope(heap->isolate()); + CcTest::i_isolate()->factory()->NewJSArrayBufferAndBackingStore( + 64 * KB, InitializedFlag::kZeroInitialized); + } + int mark_sweep_count_after = heap->ms_count(); + // We expect only scavenges, no full GCs. + CHECK_EQ(mark_sweep_count_before, mark_sweep_count_after); +} + } // namespace heap } // namespace internal } // namespace v8 diff --git a/doc/api/addons.md b/doc/api/addons.md index 8b17d6b417b8e8..d011af902d19c4 100644 --- a/doc/api/addons.md +++ b/doc/api/addons.md @@ -157,11 +157,11 @@ The context-aware addon can be structured to avoid global static data by performing the following steps: * defining a class which will hold per-addon-instance data. Such -a class should include a `v8::Persistent` which will hold a weak +a class should include a `v8::Global` which will hold a weak reference to the addon's `exports` object. The callback associated with the weak reference will then destroy the instance of the class. * constructing an instance of this class in the addon initializer such that the -`v8::Persistent` is set to the `exports` object. +`v8::Global` is set to the `exports` object. * storing the instance of the class in a `v8::External`, and * passing the `v8::External` to all methods exposed to JavaScript by passing it to the `v8::FunctionTemplate` constructor which creates the native-backed @@ -188,14 +188,6 @@ class AddonData { exports_.SetWeak(this, DeleteMe, WeakCallbackType::kParameter); } - ~AddonData() { - if (!exports_.IsEmpty()) { - // Reset the reference to avoid leaking data. - exports_.ClearWeak(); - exports_.Reset(); - } - } - // Per-addon data. int call_count; @@ -207,7 +199,7 @@ class AddonData { // Weak handle to the "exports" object. An instance of this class will be // destroyed along with the exports object to which it is weakly bound. - v8::Persistent exports_; + v8::Global exports_; }; static void Method(const v8::FunctionCallbackInfo& info) { @@ -400,7 +392,7 @@ only the symbols exported by Node.js will be available. source image. Using this option, the Addon will have access to the full set of dependencies. -### Loading Addons using require() +### Loading Addons using `require()` The filename extension of the compiled Addon binary is `.node` (as opposed to `.dll` or `.so`). The [`require()`][require] function is written to look for @@ -830,7 +822,7 @@ class MyObject : public node::ObjectWrap { static void New(const v8::FunctionCallbackInfo& args); static void PlusOne(const v8::FunctionCallbackInfo& args); - static v8::Persistent constructor; + double value_; }; @@ -858,12 +850,10 @@ using v8::Local; using v8::NewStringType; using v8::Number; using v8::Object; -using v8::Persistent; +using v8::ObjectTemplate; using v8::String; using v8::Value; -Persistent MyObject::constructor; - MyObject::MyObject(double value) : value_(value) { } @@ -872,9 +862,15 @@ MyObject::~MyObject() { void MyObject::Init(Local exports) { Isolate* isolate = exports->GetIsolate(); + Local context = isolate->GetCurrentContext(); + + Local addon_data_tpl = ObjectTemplate::New(isolate); + addon_data_tpl->SetInternalFieldCount(1); // 1 field for the MyObject::New() + Local addon_data = + addon_data_tpl->NewInstance(context).ToLocalChecked(); // Prepare constructor template - Local tpl = FunctionTemplate::New(isolate, New); + Local tpl = FunctionTemplate::New(isolate, New, addon_data); tpl->SetClassName(String::NewFromUtf8( isolate, "MyObject", NewStringType::kNormal).ToLocalChecked()); tpl->InstanceTemplate()->SetInternalFieldCount(1); @@ -882,11 +878,11 @@ void MyObject::Init(Local exports) { // Prototype NODE_SET_PROTOTYPE_METHOD(tpl, "plusOne", PlusOne); - Local context = isolate->GetCurrentContext(); - constructor.Reset(isolate, tpl->GetFunction(context).ToLocalChecked()); + Local constructor = tpl->GetFunction(context).ToLocalChecked(); + addon_data->SetInternalField(0, constructor); exports->Set(context, String::NewFromUtf8( isolate, "MyObject", NewStringType::kNormal).ToLocalChecked(), - tpl->GetFunction(context).ToLocalChecked()).FromJust(); + constructor).FromJust(); } void MyObject::New(const FunctionCallbackInfo& args) { @@ -904,7 +900,8 @@ void MyObject::New(const FunctionCallbackInfo& args) { // Invoked as plain function `MyObject(...)`, turn into construct call. const int argc = 1; Local argv[argc] = { args[0] }; - Local cons = Local::New(isolate, constructor); + Local cons = + args.Data().As()->GetInternalField(0).As(); Local result = cons->NewInstance(context, argc, argv).ToLocalChecked(); args.GetReturnValue().Set(result); @@ -1029,7 +1026,7 @@ class MyObject : public node::ObjectWrap { static void New(const v8::FunctionCallbackInfo& args); static void PlusOne(const v8::FunctionCallbackInfo& args); - static v8::Persistent constructor; + static v8::Global constructor; double value_; }; @@ -1047,20 +1044,23 @@ The implementation in `myobject.cc` is similar to the previous example: namespace demo { +using node::AddEnvironmentCleanupHook; using v8::Context; using v8::Function; using v8::FunctionCallbackInfo; using v8::FunctionTemplate; +using v8::Global; using v8::Isolate; using v8::Local; using v8::NewStringType; using v8::Number; using v8::Object; -using v8::Persistent; using v8::String; using v8::Value; -Persistent MyObject::constructor; +// Warning! This is not thread-safe, this addon cannot be used for worker +// threads. +Global MyObject::constructor; MyObject::MyObject(double value) : value_(value) { } @@ -1080,6 +1080,10 @@ void MyObject::Init(Isolate* isolate) { Local context = isolate->GetCurrentContext(); constructor.Reset(isolate, tpl->GetFunction(context).ToLocalChecked()); + + AddEnvironmentCleanupHook(isolate, [](void*) { + constructor.Reset(); + }, nullptr); } void MyObject::New(const FunctionCallbackInfo& args) { @@ -1246,7 +1250,7 @@ class MyObject : public node::ObjectWrap { ~MyObject(); static void New(const v8::FunctionCallbackInfo& args); - static v8::Persistent constructor; + static v8::Global constructor; double value_; }; @@ -1264,19 +1268,22 @@ The implementation of `myobject.cc` is similar to before: namespace demo { +using node::AddEnvironmentCleanupHook; using v8::Context; using v8::Function; using v8::FunctionCallbackInfo; using v8::FunctionTemplate; +using v8::Global; using v8::Isolate; using v8::Local; using v8::NewStringType; using v8::Object; -using v8::Persistent; using v8::String; using v8::Value; -Persistent MyObject::constructor; +// Warning! This is not thread-safe, this addon cannot be used for worker +// threads. +Global MyObject::constructor; MyObject::MyObject(double value) : value_(value) { } @@ -1293,6 +1300,10 @@ void MyObject::Init(Isolate* isolate) { Local context = isolate->GetCurrentContext(); constructor.Reset(isolate, tpl->GetFunction(context).ToLocalChecked()); + + AddEnvironmentCleanupHook(isolate, [](void*) { + constructor.Reset(); + }, nullptr); } void MyObject::New(const FunctionCallbackInfo& args) { diff --git a/doc/api/assert.md b/doc/api/assert.md index 9d1a7fb7e169ea..0598ee8be10880 100644 --- a/doc/api/assert.md +++ b/doc/api/assert.md @@ -15,7 +15,7 @@ lenient legacy mode. Indicates the failure of an assertion. All errors thrown by the `assert` module will be instances of the `AssertionError` class. -### new assert.AssertionError(options) +### `new assert.AssertionError(options)` @@ -146,7 +146,7 @@ lax: assert.deepEqual(/a/gi, new Date()); ``` -## assert(value\[, message\]) +## `assert(value[, message])` @@ -156,7 +156,7 @@ added: v0.5.9 An alias of [`assert.ok()`][]. -## assert.deepEqual(actual, expected\[, message\]) +## `assert.deepEqual(actual, expected[, message])` + +* `string` {string} +* `regexp` {RegExp} +* `message` {string|Error} + +> Stability: 1 - Experimental + +Expects the `string` input not to match the regular expression. + +This feature is currently experimental and the name might change or it might be +completely removed again. + +```js +const assert = require('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/); +// OK +``` + +If the values do match, or if the `string` argument is of another type than +`string`, an [`AssertionError`][] is thrown with a `message` property set equal +to the value of the `message` parameter. If the `message` parameter is +undefined, a default error message is assigned. If the `message` parameter is an +instance of an [`Error`][] then it will be thrown instead of the +[`AssertionError`][]. + +## `assert.doesNotReject(asyncFn[, error][, message])` @@ -475,7 +511,7 @@ assert.doesNotReject(Promise.reject(new TypeError('Wrong value'))) }); ``` -## assert.doesNotThrow(fn\[, error\]\[, message\]) +## `assert.doesNotThrow(fn[, error][, message])` @@ -591,7 +627,7 @@ parameter is undefined, a default error message is assigned. If the `message` parameter is an instance of an [`Error`][] then it will be thrown instead of the `AssertionError`. -## assert.fail(\[message\]) +## `assert.fail([message])` @@ -618,7 +654,7 @@ assert.fail(new TypeError('need array')); Using `assert.fail()` with more than two arguments is possible but deprecated. See below for further details. -## assert.fail(actual, expected\[, message\[, operator\[, stackStartFn\]\]\]) +## `assert.fail(actual, expected[, message[, operator[, stackStartFn]]])` + +* `string` {string} +* `regexp` {RegExp} +* `message` {string|Error} + +> Stability: 1 - Experimental + +Expects the `string` input to match the regular expression. + +This feature is currently experimental and the name might change or it might be +completely removed again. + +```js +const assert = require('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/); +// OK +``` + +If the values do not match, or if the `string` argument is of another type than +`string`, an [`AssertionError`][] is thrown with a `message` property set equal +to the value of the `message` parameter. If the `message` parameter is +undefined, a default error message is assigned. If the `message` parameter is an +instance of an [`Error`][] then it will be thrown instead of the +[`AssertionError`][]. + +## `assert.notDeepEqual(actual, expected[, message])` @@ -889,7 +961,7 @@ parameter is undefined, a default error message is assigned. If the `message` parameter is an instance of an [`Error`][] then it will be thrown instead of the `AssertionError`. -## assert.notStrictEqual(actual, expected\[, message\]) +## `assert.notStrictEqual(actual, expected[, message])` @@ -1053,7 +1125,7 @@ argument, then `error` is assumed to be omitted and the string will be used for example in [`assert.throws()`][] carefully if using a string as the second argument gets considered. -## assert.strictEqual(actual, expected\[, message\]) +## `assert.strictEqual(actual, expected[, message])` @@ -664,7 +664,7 @@ of the async resource. This will establish the context, trigger the AsyncHooks before callbacks, call the function, trigger the AsyncHooks after callbacks, and then restore the original execution context. -#### asyncResource.emitDestroy() +#### `asyncResource.emitDestroy()` * Returns: {AsyncResource} A reference to `asyncResource`. @@ -673,11 +673,11 @@ be thrown if it is called more than once. This **must** be manually called. If the resource is left to be collected by the GC then the `destroy` hooks will never be called. -#### asyncResource.asyncId() +#### `asyncResource.asyncId()` * Returns: {number} The unique `asyncId` assigned to the resource. -#### asyncResource.triggerAsyncId() +#### `asyncResource.triggerAsyncId()` * Returns: {number} The same `triggerAsyncId` that is passed to the `AsyncResource` constructor. diff --git a/doc/api/buffer.md b/doc/api/buffer.md index c5b7bf15047177..c94f03fa065a36 100644 --- a/doc/api/buffer.md +++ b/doc/api/buffer.md @@ -311,12 +311,12 @@ for (const b of buf) { Additionally, the [`buf.values()`][], [`buf.keys()`][], and [`buf.entries()`][] methods can be used to create iterators. -## Class: Buffer +## Class: `Buffer` The `Buffer` class is a global type for dealing with binary data directly. It can be constructed in a variety of ways. -### new Buffer(array) +### `new Buffer(array)` @@ -677,7 +677,7 @@ developer has observed undue memory retention in their applications. A `TypeError` will be thrown if `size` is not a number. -### Class Method: Buffer.byteLength(string\[, encoding\]) +### Class Method: `Buffer.byteLength(string[, encoding])` @@ -808,7 +808,7 @@ const buf = Buffer.from([0x62, 0x75, 0x66, 0x66, 0x65, 0x72]); A `TypeError` will be thrown if `array` is not an `Array` or other type appropriate for `Buffer.from()` variants. -### Class Method: Buffer.from(arrayBuffer\[, byteOffset\[, length\]\]) +### Class Method: `Buffer.from(arrayBuffer[, byteOffset[, length]])` @@ -857,7 +857,7 @@ console.log(buf.length); A `TypeError` will be thrown if `arrayBuffer` is not an [`ArrayBuffer`][] or a [`SharedArrayBuffer`][] or other type appropriate for `Buffer.from()` variants. -### Class Method: Buffer.from(buffer) +### Class Method: `Buffer.from(buffer)` @@ -882,7 +882,7 @@ console.log(buf2.toString()); A `TypeError` will be thrown if `buffer` is not a `Buffer` or other type appropriate for `Buffer.from()` variants. -### Class Method: Buffer.from(object\[, offsetOrEncoding\[, length\]\]) +### Class Method: `Buffer.from(object[, offsetOrEncoding[, length]])` @@ -919,7 +919,7 @@ const buf = Buffer.from(new Foo(), 'utf8'); A `TypeError` will be thrown if `object` has not mentioned methods or is not of other type appropriate for `Buffer.from()` variants. -### Class Method: Buffer.from(string\[, encoding\]) +### Class Method: `Buffer.from(string[, encoding])` @@ -945,7 +945,7 @@ console.log(buf1.toString('ascii')); A `TypeError` will be thrown if `string` is not a string or other type appropriate for `Buffer.from()` variants. -### Class Method: Buffer.isBuffer(obj) +### Class Method: `Buffer.isBuffer(obj)` @@ -955,7 +955,7 @@ added: v0.1.101 Returns `true` if `obj` is a `Buffer`, `false` otherwise. -### Class Method: Buffer.isEncoding(encoding) +### Class Method: `Buffer.isEncoding(encoding)` @@ -980,7 +980,7 @@ console.log(Buffer.isEncoding('')); // Prints: false ``` -### Class Property: Buffer.poolSize +### Class Property: `Buffer.poolSize` @@ -990,7 +990,7 @@ added: v0.11.3 This is the size (in bytes) of pre-allocated internal `Buffer` instances used for pooling. This value may be modified. -### buf\[index\] +### `buf[index]` @@ -1183,7 +1183,7 @@ console.log(buf.toString()); // Prints: efghijghijklmnopqrstuvwxyz ``` -### buf.entries() +### `buf.entries()` @@ -1210,7 +1210,7 @@ for (const pair of buf.entries()) { // [5, 114] ``` -### buf.equals(otherBuffer) +### `buf.equals(otherBuffer)` @@ -1342,7 +1342,7 @@ console.log(buf.includes('this', 4)); // Prints: false ``` -### buf.indexOf(value\[, byteOffset\]\[, encoding\]) +### `buf.indexOf(value[, byteOffset][, encoding])` @@ -1449,7 +1449,7 @@ for (const key of buf.keys()) { // 5 ``` -### buf.lastIndexOf(value\[, byteOffset\]\[, encoding\]) +### `buf.lastIndexOf(value[, byteOffset][, encoding])` @@ -1569,7 +1569,7 @@ console.log(buf.length); // Prints: 5 ``` -### buf.parent +### `buf.parent` @@ -1578,8 +1578,8 @@ deprecated: v8.0.0 The `buf.parent` property is a deprecated alias for `buf.buffer`. -### buf.readBigInt64BE(\[offset\]) -### buf.readBigInt64LE(\[offset\]) +### `buf.readBigInt64BE([offset])` +### `buf.readBigInt64LE([offset])` @@ -1594,8 +1594,8 @@ the specified endian format (`readBigInt64BE()` returns big endian, Integers read from a `Buffer` are interpreted as two's complement signed values. -### buf.readBigUInt64BE(\[offset\]) -### buf.readBigUInt64LE(\[offset\]) +### `buf.readBigUInt64BE([offset])` +### `buf.readBigUInt64LE([offset])` @@ -1618,8 +1618,8 @@ console.log(buf.readBigUInt64LE(0)); // Prints: 18446744069414584320n ``` -### buf.readDoubleBE(\[offset\]) -### buf.readDoubleLE(\[offset\]) +### `buf.readDoubleBE([offset])` +### `buf.readDoubleLE([offset])` @@ -1988,7 +1988,7 @@ console.log(buf.subarray(-5, -2).toString()); // (Equivalent to buf.subarray(1, 4).) ``` -### buf.slice(\[start\[, end\]\]) +### `buf.slice([start[, end]])` @@ -2064,7 +2064,7 @@ const buf = Buffer.from('This is little-endian UTF-16', 'utf16le'); buf.swap16(); // Convert to big-endian UTF-16 text. ``` -### buf.swap32() +### `buf.swap32()` @@ -2092,7 +2092,7 @@ buf2.swap32(); // Throws ERR_INVALID_BUFFER_SIZE. ``` -### buf.swap64() +### `buf.swap64()` @@ -2122,7 +2122,7 @@ buf2.swap64(); JavaScript cannot encode 64-bit integers. This method is intended for working with 64-bit floats. -### buf.toJSON() +### `buf.toJSON()` @@ -2149,7 +2149,7 @@ console.log(copy); // Prints: ``` -### buf.toString(\[encoding\[, start\[, end\]\]\]) +### `buf.toString([encoding[, start[, end]]])` @@ -2191,7 +2191,7 @@ console.log(buf2.toString(undefined, 0, 3)); // Prints: té ``` -### buf.values() +### `buf.values()` @@ -2227,7 +2227,7 @@ for (const value of buf) { // 114 ``` -### buf.write(string\[, offset\[, length\]\]\[, encoding\]) +### `buf.write(string[, offset[, length]][, encoding])` @@ -2254,8 +2254,8 @@ console.log(`${len} bytes: ${buf.toString('utf8', 0, len)}`); // Prints: 12 bytes: ½ + ¼ = ¾ ``` -### buf.writeBigInt64BE(value\[, offset\]) -### buf.writeBigInt64LE(value\[, offset\]) +### `buf.writeBigInt64BE(value[, offset])` +### `buf.writeBigInt64LE(value[, offset])` @@ -2280,8 +2280,8 @@ console.log(buf); // Prints: ``` -### buf.writeBigUInt64BE(value\[, offset\]) -### buf.writeBigUInt64LE(value\[, offset\]) +### `buf.writeBigUInt64BE(value[, offset])` +### `buf.writeBigUInt64LE(value[, offset])` @@ -2304,8 +2304,8 @@ console.log(buf); // Prints: ``` -### buf.writeDoubleBE(value\[, offset\]) -### buf.writeDoubleLE(value\[, offset\]) +### `buf.writeDoubleBE(value[, offset])` +### `buf.writeDoubleLE(value[, offset])` @@ -2660,7 +2660,7 @@ Returns the maximum number of bytes that will be returned when This is a property on the `buffer` module returned by `require('buffer')`, not on the `Buffer` global or a `Buffer` instance. -## buffer.kMaxLength +## `buffer.kMaxLength` @@ -2672,7 +2672,7 @@ An alias for [`buffer.constants.MAX_LENGTH`][]. This is a property on the `buffer` module returned by `require('buffer')`, not on the `Buffer` global or a `Buffer` instance. -## buffer.transcode(source, fromEnc, toEnc) +## `buffer.transcode(source, fromEnc, toEnc)` @@ -2750,7 +2750,7 @@ socket.on('readable', () => { Use of `SlowBuffer` should be used only as a last resort *after* a developer has observed undue memory retention in their applications. -### new SlowBuffer(size) +### `new SlowBuffer(size)` @@ -2790,7 +2790,7 @@ added: v8.2.0 `buffer.constants` is a property on the `buffer` module returned by `require('buffer')`, not on the `Buffer` global or a `Buffer` instance. -### buffer.constants.MAX_LENGTH +### `buffer.constants.MAX_LENGTH` @@ -2802,7 +2802,7 @@ On 64-bit architectures, this value is `(2^31)-1` (~2GB). This value is also available as [`buffer.kMaxLength`][]. -### buffer.constants.MAX_STRING_LENGTH +### `buffer.constants.MAX_STRING_LENGTH` diff --git a/doc/api/child_process.md b/doc/api/child_process.md index 746de9bd2c8b7b..6f74038b3c9c90 100644 --- a/doc/api/child_process.md +++ b/doc/api/child_process.md @@ -129,7 +129,7 @@ exec('"my script.cmd" a b', (err, stdout, stderr) => { }); ``` -### child_process.exec(command\[, options\]\[, callback\]) +### `child_process.exec(command[, options][, callback])` @@ -593,7 +593,7 @@ const subprocess = spawn('prg', [], { subprocess.unref(); ``` -#### options.stdio +#### `options.stdio` @@ -916,7 +916,7 @@ use the [`child_process.spawn()`][], [`child_process.exec()`][], [`child_process.execFile()`][], or [`child_process.fork()`][] methods to create instances of `ChildProcess`. -### Event: 'close' +### Event: `'close'` @@ -945,7 +945,7 @@ ls.on('exit', (code) => { }); ``` -### Event: 'disconnect' +### Event: `'disconnect'` @@ -956,7 +956,7 @@ The `'disconnect'` event is emitted after calling the possible to send or receive messages, and the [`subprocess.connected`][] property is `false`. -### Event: 'error' +### Event: `'error'` * `err` {Error} The error. @@ -972,7 +972,7 @@ against accidentally invoking handler functions multiple times. See also [`subprocess.kill()`][] and [`subprocess.send()`][]. -### Event: 'exit' +### Event: `'exit'` @@ -995,7 +995,7 @@ re-raise the handled signal. See waitpid(2). -### Event: 'message' +### Event: `'message'` @@ -1015,7 +1015,7 @@ child process, the `message` argument can contain data that JSON is not able to represent. See [Advanced Serialization][] for more details. -### subprocess.channel +### `subprocess.channel` @@ -1025,7 +1025,7 @@ added: v7.1.0 The `subprocess.channel` property is a reference to the child's IPC channel. If no IPC channel currently exists, this property is `undefined`. -### subprocess.connected +### `subprocess.connected` @@ -1036,7 +1036,7 @@ The `subprocess.connected` property indicates whether it is still possible to send and receive messages from a child process. When `subprocess.connected` is `false`, it is no longer possible to send or receive messages. -### subprocess.disconnect() +### `subprocess.disconnect()` @@ -1055,7 +1055,7 @@ When the child process is a Node.js instance (e.g. spawned using [`child_process.fork()`][]), the `process.disconnect()` method can be invoked within the child process to close the IPC channel as well. -### subprocess.kill(\[signal\]) +### `subprocess.kill([signal])` @@ -1117,7 +1117,7 @@ setTimeout(() => { }, 2000); ``` -### subprocess.killed +### `subprocess.killed` @@ -1129,7 +1129,7 @@ The `subprocess.killed` property indicates whether the child process successfully received a signal from `subprocess.kill()`. The `killed` property does not indicate that the child process has been terminated. -### subprocess.pid +### `subprocess.pid` @@ -1146,7 +1146,7 @@ console.log(`Spawned child pid: ${grep.pid}`); grep.stdin.end(); ``` -### subprocess.ref() +### `subprocess.ref()` @@ -1167,7 +1167,7 @@ subprocess.unref(); subprocess.ref(); ``` -### subprocess.send(message\[, sendHandle\[, options\]\]\[, callback\]) +### `subprocess.send(message[, sendHandle[, options]][, callback])` @@ -1363,7 +1363,7 @@ then this will be `null`. `subprocess.stderr` is an alias for `subprocess.stdio[2]`. Both properties will refer to the same value. -### subprocess.stdin +### `subprocess.stdin` @@ -1381,7 +1381,7 @@ then this will be `null`. `subprocess.stdin` is an alias for `subprocess.stdio[0]`. Both properties will refer to the same value. -### subprocess.stdio +### `subprocess.stdio` @@ -1421,7 +1421,7 @@ assert.strictEqual(subprocess.stdio[2], null); assert.strictEqual(subprocess.stdio[2], subprocess.stderr); ``` -### subprocess.stdout +### `subprocess.stdout` @@ -1446,7 +1446,7 @@ subprocess.stdout.on('data', (data) => { }); ``` -### subprocess.unref() +### `subprocess.unref()` diff --git a/doc/api/cli.md b/doc/api/cli.md index 6050e3dc0fb7fe..6ece4d4580244f 100644 --- a/doc/api/cli.md +++ b/doc/api/cli.md @@ -178,7 +178,7 @@ added: v8.5.0 --> Enable latest experimental modules features (currently -`--experimental-conditional-exports` and `--experimental-resolve-self`). +`--experimental-conditional-exports`). ### `--experimental-policy` - -Enable experimental support for a package using `require` or `import` to load -itself. - ### `--experimental-specifier-resolution=mode` Enable experimental WebAssembly System Interface (WASI) support. @@ -871,6 +868,22 @@ environment variables. See `SSL_CERT_DIR` and `SSL_CERT_FILE`. +### `--use-largepages=mode` + + +Re-map the Node.js static code to large memory pages at startup. If supported on +the target system, this will cause the Node.js static code to be moved onto 2 +MiB pages instead of 4 KiB pages. + +The following values are valid for `mode`: +* `off`: No mapping will be attempted. This is the default. +* `on`: If supported by the OS, mapping will be attempted. Failure to map will + be ignored and a message will be printed to standard error. +* `silent`: If supported by the OS, mapping will be attempted. Failure to map + will be ignored and will not be reported. + ### `--v8-options` @@ -122,7 +122,7 @@ A `Worker` object contains all public information and method about a worker. In the master it can be obtained using `cluster.workers`. In a worker it can be obtained using `cluster.worker`. -### Event: 'disconnect' +### Event: `'disconnect'` @@ -135,7 +135,7 @@ cluster.fork().on('disconnect', () => { }); ``` -### Event: 'error' +### Event: `'error'` @@ -144,7 +144,7 @@ This event is the same as the one provided by [`child_process.fork()`][]. Within a worker, `process.on('error')` may also be used. -### Event: 'exit' +### Event: `'exit'` @@ -168,7 +168,7 @@ worker.on('exit', (code, signal) => { }); ``` -### Event: 'listening' +### Event: `'listening'` @@ -185,7 +185,7 @@ cluster.fork().on('listening', (address) => { It is not emitted in the worker. -### Event: 'message' +### Event: `'message'` @@ -244,7 +244,7 @@ if (cluster.isMaster) { } ``` -### Event: 'online' +### Event: `'online'` @@ -259,7 +259,7 @@ cluster.fork().on('online', () => { It is not emitted in the worker. -### worker.disconnect() +### `worker.disconnect()` @@ -355,7 +355,7 @@ cluster.on('exit', (worker, code, signal) => { worker.kill(); ``` -### worker.id +### `worker.id` @@ -368,7 +368,7 @@ Each new worker is given its own unique id, this id is stored in the While a worker is alive, this is the key that indexes it in `cluster.workers`. -### worker.isConnected() +### `worker.isConnected()` @@ -377,7 +377,7 @@ This function returns `true` if the worker is connected to its master via its IPC channel, `false` otherwise. A worker is connected to its master after it has been created. It is disconnected after the `'disconnect'` event is emitted. -### worker.isDead() +### `worker.isDead()` @@ -415,7 +415,7 @@ if (cluster.isMaster) { } ``` -### worker.kill(\[signal='SIGTERM'\]) +### `worker.kill([signal='SIGTERM'])` @@ -439,7 +439,7 @@ This method is aliased as `worker.destroy()` for backwards compatibility. In a worker, `process.kill()` exists, but it is not this function; it is [`kill()`][]. -### worker.process +### `worker.process` @@ -456,7 +456,7 @@ Workers will call `process.exit(0)` if the `'disconnect'` event occurs on `process` and `.exitedAfterDisconnect` is not `true`. This protects against accidental disconnection. -### worker.send(message\[, sendHandle\[, options\]\]\[, callback\]) +### `worker.send(message[, sendHandle[, options]][, callback])` @@ -519,7 +519,7 @@ cluster.on('disconnect', (worker) => { }); ``` -## Event: 'exit' +## Event: `'exit'` @@ -543,7 +543,7 @@ cluster.on('exit', (worker, code, signal) => { See [`child_process` event: `'exit'`][]. -## Event: 'fork' +## Event: `'fork'` @@ -571,7 +571,7 @@ cluster.on('exit', (worker, code, signal) => { }); ``` -## Event: 'listening' +## Event: `'listening'` @@ -602,7 +602,7 @@ The `addressType` is one of: * `-1` (Unix domain socket) * `'udp4'` or `'udp6'` (UDP v4 or v6) -## Event: 'message' +## Event: `'message'` @@ -637,7 +637,7 @@ cluster.on('online', (worker) => { }); ``` -## Event: 'setup' +## Event: `'setup'` @@ -652,7 +652,7 @@ The `settings` object is the `cluster.settings` object at the time If accuracy is important, use `cluster.settings`. -## cluster.disconnect(\[callback\]) +## `cluster.disconnect([callback])` @@ -670,7 +670,7 @@ finished. This can only be called from the master process. -## cluster.fork(\[env\]) +## `cluster.fork([env])` @@ -682,7 +682,7 @@ Spawn a new worker process. This can only be called from the master process. -## cluster.isMaster +## `cluster.isMaster` @@ -693,7 +693,7 @@ True if the process is a master. This is determined by the `process.env.NODE_UNIQUE_ID`. If `process.env.NODE_UNIQUE_ID` is undefined, then `isMaster` is `true`. -## cluster.isWorker +## `cluster.isWorker` @@ -702,7 +702,7 @@ added: v0.6.0 True if the process is not a master (it is the negation of `cluster.isMaster`). -## cluster.schedulingPolicy +## `cluster.schedulingPolicy` @@ -720,7 +720,7 @@ distribute IOCP handles without incurring a large performance hit. `NODE_CLUSTER_SCHED_POLICY` environment variable. Valid values are `'rr'` and `'none'`. -## cluster.settings +## `cluster.settings` @@ -833,7 +833,7 @@ if (cluster.isMaster) { } ``` -## cluster.workers +## `cluster.workers` diff --git a/doc/api/console.md b/doc/api/console.md index 00072793adb496..66fa862de88178 100644 --- a/doc/api/console.md +++ b/doc/api/console.md @@ -54,7 +54,7 @@ myConsole.warn(`Danger ${name}! Danger!`); // Prints: Danger Will Robinson! Danger!, to err ``` -## Class: Console +## Class: `Console` @@ -172,7 +172,7 @@ operates similarly to the `clear` shell command. On Windows, `console.clear()` will clear only the output in the current terminal viewport for the Node.js binary. -### console.count(\[label\]) +### `console.count([label])` @@ -205,7 +205,7 @@ undefined > ``` -### console.countReset(\[label\]) +### `console.countReset([label])` @@ -227,7 +227,7 @@ undefined > ``` -### console.debug(data\[, ...args\]) +### `console.debug(data[, ...args])` @@ -260,7 +260,7 @@ added: v0.1.101 Uses [`util.inspect()`][] on `obj` and prints the resulting string to `stdout`. This function bypasses any custom `inspect()` function defined on `obj`. -### console.dirxml(...data) +### `console.dirxml(...data)` @@ -299,7 +299,7 @@ If formatting elements (e.g. `%d`) are not found in the first string then [`util.inspect()`][] is called on each argument and the resulting string values are concatenated. See [`util.format()`][] for more information. -### console.group(\[...label\]) +### `console.group([...label])` @@ -311,21 +311,21 @@ Increases indentation of subsequent lines by two spaces. If one or more `label`s are provided, those are printed first without the additional indentation. -### console.groupCollapsed() +### `console.groupCollapsed()` An alias for [`console.group()`][]. -### console.groupEnd() +### `console.groupEnd()` Decreases indentation of subsequent lines by two spaces. -### console.info(\[data\]\[, ...args\]) +### `console.info([data][, ...args])` @@ -335,7 +335,7 @@ added: v0.1.100 The `console.info()` function is an alias for [`console.log()`][]. -### console.log(\[data\]\[, ...args\]) +### `console.log([data][, ...args])` @@ -358,7 +358,7 @@ console.log('count:', count); See [`util.format()`][] for more information. -### console.table(tabularData\[, properties\]) +### `console.table(tabularData[, properties])` @@ -395,7 +395,7 @@ console.table([{ a: 1, b: 'Y' }, { a: 'Z', b: 2 }], ['a']); // └─────────┴─────┘ ``` -### console.time(\[label\]) +### `console.time([label])` @@ -407,7 +407,7 @@ are identified by a unique `label`. Use the same `label` when calling [`console.timeEnd()`][] to stop the timer and output the elapsed time in milliseconds to `stdout`. Timer durations are accurate to the sub-millisecond. -### console.timeEnd(\[label\]) +### `console.timeEnd([label])` @@ -449,7 +449,7 @@ doExpensiveProcess2(value); console.timeEnd('process'); ``` -### console.trace(\[message\]\[, ...args\]) +### `console.trace([message][, ...args])` @@ -476,7 +476,7 @@ console.trace('Show me'); // at REPLServer.Interface._ttyWrite (readline.js:826:14) ``` -### console.warn(\[data\]\[, ...args\]) +### `console.warn([data][, ...args])` @@ -491,7 +491,7 @@ The following methods are exposed by the V8 engine in the general API but do not display anything unless used in conjunction with the [inspector][] (`--inspect` flag). -### console.profile(\[label\]) +### `console.profile([label])` @@ -510,7 +510,7 @@ console.profileEnd('MyLabel'); // Adds the profile 'MyLabel' to the Profiles panel of the inspector. ``` -### console.profileEnd(\[label\]) +### `console.profileEnd([label])` @@ -525,7 +525,7 @@ the report to the **Profiles** panel of the inspector. See If this method is called without a label, the most recently started profile is stopped. -### console.timeStamp(\[label\]) +### `console.timeStamp([label])` diff --git a/doc/api/crypto.md b/doc/api/crypto.md index 5de68740aa3fe8..bfe0c8bc6acbfc 100644 --- a/doc/api/crypto.md +++ b/doc/api/crypto.md @@ -36,7 +36,7 @@ try { } ``` -## Class: Certificate +## Class: `Certificate` @@ -51,7 +51,7 @@ The `crypto` module provides the `Certificate` class for working with SPKAC data. The most common usage is handling output generated by the HTML5 `` element. Node.js uses [OpenSSL's SPKAC implementation][] internally. -### Certificate.exportChallenge(spkac) +### `Certificate.exportChallenge(spkac)` @@ -68,7 +68,7 @@ console.log(challenge.toString('utf8')); // Prints: the challenge as a UTF8 string ``` -### Certificate.exportPublicKey(spkac\[, encoding\]) +### `Certificate.exportPublicKey(spkac[, encoding])` @@ -86,7 +86,7 @@ console.log(publicKey); // Prints: the public key as ``` -### Certificate.verifySpkac(spkac) +### `Certificate.verifySpkac(spkac)` @@ -108,7 +108,7 @@ As a still supported legacy interface, it is possible (but not recommended) to create new instances of the `crypto.Certificate` class as illustrated in the examples below. -#### new crypto.Certificate() +#### `new crypto.Certificate()` Instances of the `Certificate` class can be created using the `new` keyword or by calling `crypto.Certificate()` as a function: @@ -120,7 +120,7 @@ const cert1 = new crypto.Certificate(); const cert2 = crypto.Certificate(); ``` -#### certificate.exportChallenge(spkac) +#### `certificate.exportChallenge(spkac)` @@ -137,7 +137,7 @@ console.log(challenge.toString('utf8')); // Prints: the challenge as a UTF8 string ``` -#### certificate.exportPublicKey(spkac) +#### `certificate.exportPublicKey(spkac)` @@ -154,7 +154,7 @@ console.log(publicKey); // Prints: the public key as ``` -#### certificate.verifySpkac(spkac) +#### `certificate.verifySpkac(spkac)` @@ -170,7 +170,7 @@ console.log(cert.verifySpkac(Buffer.from(spkac))); // Prints: true or false ``` -## Class: Cipher +## Class: `Cipher` @@ -265,7 +265,7 @@ console.log(encrypted); // Prints: e5f79c5915c02171eec6b212d5520d44480993d7d622a7c4c2da32f6efda0ffa ``` -### cipher.final(\[outputEncoding\]) +### `cipher.final([outputEncoding])` @@ -279,7 +279,7 @@ Once the `cipher.final()` method has been called, the `Cipher` object can no longer be used to encrypt data. Attempts to call `cipher.final()` more than once will result in an error being thrown. -### cipher.setAAD(buffer\[, options\]) +### `cipher.setAAD(buffer[, options])` @@ -299,7 +299,7 @@ of the plaintext in bytes. See [CCM mode][]. The `cipher.setAAD()` method must be called before [`cipher.update()`][]. -### cipher.getAuthTag() +### `cipher.getAuthTag()` @@ -312,7 +312,7 @@ added: v1.0.0 The `cipher.getAuthTag()` method should only be called after encryption has been completed using the [`cipher.final()`][] method. -### cipher.setAutoPadding(\[autoPadding\]) +### `cipher.setAutoPadding([autoPadding])` @@ -332,7 +332,7 @@ using `0x0` instead of PKCS padding. The `cipher.setAutoPadding()` method must be called before [`cipher.final()`][]. -### cipher.update(data\[, inputEncoding\]\[, outputEncoding\]) +### `cipher.update(data[, inputEncoding][, outputEncoding])` @@ -459,7 +459,7 @@ console.log(decrypted); // Prints: some clear text data ``` -### decipher.final(\[outputEncoding\]) +### `decipher.final([outputEncoding])` @@ -473,7 +473,7 @@ Once the `decipher.final()` method has been called, the `Decipher` object can no longer be used to decrypt data. Attempts to call `decipher.final()` more than once will result in an error being thrown. -### decipher.setAAD(buffer\[, options\]) +### `decipher.setAAD(buffer[, options])` @@ -541,7 +541,7 @@ multiple of the ciphers block size. The `decipher.setAutoPadding()` method must be called before [`decipher.final()`][]. -### decipher.update(data\[, inputEncoding\]\[, outputEncoding\]) +### `decipher.update(data[, inputEncoding][, outputEncoding])` @@ -601,7 +601,7 @@ const bobSecret = bob.computeSecret(aliceKey); assert.strictEqual(aliceSecret.toString('hex'), bobSecret.toString('hex')); ``` -### diffieHellman.computeSecret(otherPublicKey\[, inputEncoding\]\[, outputEncoding\]) +### `diffieHellman.computeSecret(otherPublicKey[, inputEncoding][, outputEncoding])` @@ -622,7 +622,7 @@ provided, `otherPublicKey` is expected to be a [`Buffer`][], If `outputEncoding` is given a string is returned; otherwise, a [`Buffer`][] is returned. -### diffieHellman.generateKeys(\[encoding\]) +### `diffieHellman.generateKeys([encoding])` @@ -636,7 +636,7 @@ transferred to the other party. If `encoding` is provided a string is returned; otherwise a [`Buffer`][] is returned. -### diffieHellman.getGenerator(\[encoding\]) +### `diffieHellman.getGenerator([encoding])` @@ -648,7 +648,7 @@ Returns the Diffie-Hellman generator in the specified `encoding`. If `encoding` is provided a string is returned; otherwise a [`Buffer`][] is returned. -### diffieHellman.getPrime(\[encoding\]) +### `diffieHellman.getPrime([encoding])` @@ -660,7 +660,7 @@ Returns the Diffie-Hellman prime in the specified `encoding`. If `encoding` is provided a string is returned; otherwise a [`Buffer`][] is returned. -### diffieHellman.getPrivateKey(\[encoding\]) +### `diffieHellman.getPrivateKey([encoding])` @@ -672,7 +672,7 @@ Returns the Diffie-Hellman private key in the specified `encoding`. If `encoding` is provided a string is returned; otherwise a [`Buffer`][] is returned. -### diffieHellman.getPublicKey(\[encoding\]) +### `diffieHellman.getPublicKey([encoding])` @@ -684,7 +684,7 @@ Returns the Diffie-Hellman public key in the specified `encoding`. If `encoding` is provided a string is returned; otherwise a [`Buffer`][] is returned. -### diffieHellman.setPrivateKey(privateKey\[, encoding\]) +### `diffieHellman.setPrivateKey(privateKey[, encoding])` @@ -697,7 +697,7 @@ Sets the Diffie-Hellman private key. If the `encoding` argument is provided, to be a string. If no `encoding` is provided, `privateKey` is expected to be a [`Buffer`][], `TypedArray`, or `DataView`. -### diffieHellman.setPublicKey(publicKey\[, encoding\]) +### `diffieHellman.setPublicKey(publicKey[, encoding])` @@ -710,7 +710,7 @@ Sets the Diffie-Hellman public key. If the `encoding` argument is provided, to be a string. If no `encoding` is provided, `publicKey` is expected to be a [`Buffer`][], `TypedArray`, or `DataView`. -### diffieHellman.verifyError +### `diffieHellman.verifyError` @@ -726,7 +726,7 @@ module): * `DH_UNABLE_TO_CHECK_GENERATOR` * `DH_NOT_SUITABLE_GENERATOR` -## Class: DiffieHellmanGroup +## Class: `DiffieHellmanGroup` @@ -753,7 +753,7 @@ modp17 modp18 ``` -## Class: ECDH +## Class: `ECDH` @@ -784,7 +784,7 @@ assert.strictEqual(aliceSecret.toString('hex'), bobSecret.toString('hex')); // OK ``` -### Class Method: ECDH.convertKey(key, curve\[, inputEncoding\[, outputEncoding\[, format\]\]\]) +### Class Method: `ECDH.convertKey(key, curve[, inputEncoding[, outputEncoding[, format]]])` @@ -832,7 +832,7 @@ const uncompressedKey = ECDH.convertKey(compressedKey, console.log(uncompressedKey === ecdh.getPublicKey('hex')); ``` -### ecdh.computeSecret(otherPublicKey\[, inputEncoding\]\[, outputEncoding\]) +### `ecdh.computeSecret(otherPublicKey[, inputEncoding][, outputEncoding])` @@ -887,7 +887,7 @@ The `format` argument specifies point encoding and can be `'compressed'` or If `encoding` is provided a string is returned; otherwise a [`Buffer`][] is returned. -### ecdh.getPrivateKey(\[encoding\]) +### `ecdh.getPrivateKey([encoding])` @@ -898,7 +898,7 @@ added: v0.11.14 If `encoding` is specified, a string is returned; otherwise a [`Buffer`][] is returned. -### ecdh.getPublicKey(\[encoding\]\[, format\]) +### `ecdh.getPublicKey([encoding][, format])` @@ -915,7 +915,7 @@ The `format` argument specifies point encoding and can be `'compressed'` or If `encoding` is specified, a string is returned; otherwise a [`Buffer`][] is returned. -### ecdh.setPrivateKey(privateKey\[, encoding\]) +### `ecdh.setPrivateKey(privateKey[, encoding])` @@ -932,7 +932,7 @@ If `privateKey` is not valid for the curve specified when the `ECDH` object was created, an error is thrown. Upon setting the private key, the associated public point (key) is also generated and set in the `ECDH` object. -### ecdh.setPublicKey(publicKey\[, encoding\]) +### `ecdh.setPublicKey(publicKey[, encoding])` @@ -1041,7 +1041,7 @@ console.log(hash.digest('hex')); // 6a2da20943931e9834fc12cfe5bb47bbd9ae43489a30726962b576f4e3993e50 ``` -### hash.copy(\[options\]) +### `hash.copy([options])` @@ -1076,7 +1076,7 @@ console.log(hash.copy().digest('hex')); // Etc. ``` -### hash.digest(\[encoding\]) +### `hash.digest([encoding])` @@ -1092,7 +1092,7 @@ a [`Buffer`][] is returned. The `Hash` object can not be used again after `hash.digest()` method has been called. Multiple calls will cause an error to be thrown. -### hash.update(data\[, inputEncoding\]) +### `hash.update(data[, inputEncoding])` @@ -1174,7 +1174,7 @@ console.log(hmac.digest('hex')); // 7fd04df92f636fd450bc841c9418e5825c17f33ad9c87c518115a45971f7f77e ``` -### hmac.digest(\[encoding\]) +### `hmac.digest([encoding])` @@ -1189,7 +1189,7 @@ provided a string is returned; otherwise a [`Buffer`][] is returned; The `Hmac` object can not be used again after `hmac.digest()` has been called. Multiple calls to `hmac.digest()` will result in an error being thrown. -### hmac.update(data\[, inputEncoding\]) +### `hmac.update(data[, inputEncoding])` @@ -1307,7 +1307,7 @@ encryption mechanism, PEM-level encryption is not supported when encrypting a PKCS#8 key. See [RFC 5208][] for PKCS#8 encryption and [RFC 1421][] for PKCS#1 and SEC1 encryption. -### keyObject.symmetricKeySize +### `keyObject.symmetricKeySize` @@ -1317,7 +1317,7 @@ added: v11.6.0 For secret keys, this property represents the size of the key in bytes. This property is `undefined` for asymmetric keys. -### keyObject.type +### `keyObject.type` @@ -1328,7 +1328,7 @@ Depending on the type of this `KeyObject`, this property is either `'secret'` for secret (symmetric) keys, `'public'` for public (asymmetric) keys or `'private'` for private (asymmetric) keys. -## Class: Sign +## Class: `Sign` @@ -1389,7 +1389,7 @@ console.log(verify.verify(publicKey, signature)); // Prints: true ``` -### sign.sign(privateKey\[, outputEncoding\]) +### `sign.sign(privateKey[, outputEncoding])` @@ -1482,7 +1482,7 @@ The [`crypto.createVerify()`][] method is used to create `Verify` instances. See [`Sign`][] for examples. -### verify.update(data\[, inputEncoding\]) +### `verify.update(data[, inputEncoding])` @@ -1574,7 +1574,7 @@ added: v6.3.0 security related operations. The specific constants currently defined are described in [Crypto Constants][]. -### crypto.DEFAULT_ENCODING +### `crypto.DEFAULT_ENCODING` * `primeLength` {number} -* `generator` {number | string | Buffer | TypedArray | DataView} **Default:** - `2` +* `generator` {number} **Default:** `2` * Returns: {DiffieHellman} Creates a `DiffieHellman` key exchange object and generates a prime of `primeLength` bits using an optional specific numeric `generator`. If `generator` is not specified, the value `2` is used. -### crypto.createDiffieHellmanGroup(name) +### `crypto.createDiffieHellmanGroup(name)` @@ -1873,7 +1872,7 @@ added: v0.9.3 An alias for [`crypto.getDiffieHellman()`][] -### crypto.createECDH(curveName) +### `crypto.createECDH(curveName)` @@ -1887,7 +1886,7 @@ predefined curve specified by the `curveName` string. Use OpenSSL releases, `openssl ecparam -list_curves` will also display the name and description of each available elliptic curve. -### crypto.createHash(algorithm\[, options\]) +### `crypto.createHash(algorithm[, options])` @@ -2001,7 +2000,7 @@ must be an object with the properties described above. If the private key is encrypted, a `passphrase` must be specified. The length of the passphrase is limited to 1024 bytes. -### crypto.createPublicKey(key) +### `crypto.createPublicKey(key)` @@ -2047,7 +2046,7 @@ added: v11.6.0 Creates and returns a new key object containing a secret key for symmetric encryption or `Hmac`. -### crypto.createSign(algorithm\[, options\]) +### `crypto.createSign(algorithm[, options])` @@ -2066,7 +2065,7 @@ the corresponding digest algorithm. This does not work for all signature algorithms, such as `'ecdsa-with-SHA256'`, so it is best to always use digest algorithm names. -### crypto.createVerify(algorithm\[, options\]) +### `crypto.createVerify(algorithm[, options])` @@ -2086,7 +2085,7 @@ the corresponding digest algorithm. This does not work for all signature algorithms, such as `'ecdsa-with-SHA256'`, so it is best to always use digest algorithm names. -### crypto.generateKeyPair(type, options, callback) +### `crypto.generateKeyPair(type, options, callback)` @@ -2221,7 +2220,7 @@ const ciphers = crypto.getCiphers(); console.log(ciphers); // ['aes-128-cbc', 'aes-128-ccm', ...] ``` -### crypto.getCurves() +### `crypto.getCurves()` @@ -2233,7 +2232,7 @@ const curves = crypto.getCurves(); console.log(curves); // ['Oakley-EC2N-3', 'Oakley-EC2N-4', ...] ``` -### crypto.getDiffieHellman(groupName) +### `crypto.getDiffieHellman(groupName)` @@ -2269,7 +2268,7 @@ const bobSecret = bob.computeSecret(alice.getPublicKey(), null, 'hex'); console.log(aliceSecret === bobSecret); ``` -### crypto.getFips() +### `crypto.getFips()` @@ -2277,7 +2276,7 @@ added: v10.0.0 * Returns: {boolean} `true` if and only if a FIPS compliant crypto provider is currently in use. -### crypto.getHashes() +### `crypto.getHashes()` @@ -2290,7 +2289,7 @@ const hashes = crypto.getHashes(); console.log(hashes); // ['DSA', 'DSA-SHA', 'DSA-SHA1', ...] ``` -### crypto.pbkdf2(password, salt, iterations, keylen, digest, callback) +### `crypto.pbkdf2(password, salt, iterations, keylen, digest, callback)` @@ -2873,7 +2872,7 @@ The flags below are deprecated in OpenSSL-1.1.0. * `crypto.constants.ENGINE_METHOD_ECDSA` * `crypto.constants.ENGINE_METHOD_STORE` -### crypto.setFips(bool) +### `crypto.setFips(bool)` @@ -2883,7 +2882,7 @@ added: v10.0.0 Enables the FIPS compliant crypto provider in a FIPS-enabled Node.js build. Throws an error if FIPS mode is not available. -### crypto.sign(algorithm, data, key) +### `crypto.sign(algorithm, data, key)` @@ -2917,7 +2916,7 @@ additional properties can be passed: size, `crypto.constants.RSA_PSS_SALTLEN_MAX_SIGN` (default) sets it to the maximum permissible value. -### crypto.timingSafeEqual(a, b) +### `crypto.timingSafeEqual(a, b)` @@ -2939,7 +2938,7 @@ Use of `crypto.timingSafeEqual` does not guarantee that the *surrounding* code is timing-safe. Care should be taken to ensure that the surrounding code does not introduce timing vulnerabilities. -### crypto.verify(algorithm, data, key, signature) +### `crypto.verify(algorithm, data, key, signature)` diff --git a/doc/api/deprecations.md b/doc/api/deprecations.md index a73d184993660d..d246eaabb618d4 100644 --- a/doc/api/deprecations.md +++ b/doc/api/deprecations.md @@ -41,7 +41,7 @@ However, the deprecation identifier will not be modified. ## List of Deprecated APIs -### DEP0001: http.OutgoingMessage.prototype.flush +### DEP0001: `http.OutgoingMessage.prototype.flush` @@ -42,7 +42,7 @@ Encapsulates the datagram functionality. New instances of `dgram.Socket` are created using [`dgram.createSocket()`][]. The `new` keyword is not to be used to create `dgram.Socket` instances. -### Event: 'close' +### Event: `'close'` @@ -50,7 +50,7 @@ added: v0.1.99 The `'close'` event is emitted after a socket is closed with [`close()`][]. Once triggered, no new `'message'` events will be emitted on this socket. -### Event: 'connect' +### Event: `'connect'` @@ -58,7 +58,7 @@ added: v12.0.0 The `'connect'` event is emitted after a socket is associated to a remote address as a result of a successful [`connect()`][] call. -### Event: 'error' +### Event: `'error'` @@ -68,7 +68,7 @@ added: v0.1.99 The `'error'` event is emitted whenever any error occurs. The event handler function is passed a single `Error` object. -### Event: 'listening' +### Event: `'listening'` @@ -76,7 +76,7 @@ added: v0.1.99 The `'listening'` event is emitted whenever a socket begins listening for datagram messages. This occurs as soon as UDP sockets are created. -### Event: 'message' +### Event: `'message'` @@ -91,7 +91,7 @@ The event handler function is passed two arguments: `msg` and `rinfo`. * `port` {number} The sender port. * `size` {number} The message size. -### socket.addMembership(multicastAddress\[, multicastInterface\]) +### `socket.addMembership(multicastAddress[, multicastInterface])` @@ -123,7 +123,7 @@ if (cluster.isMaster) { } ``` -### socket.addSourceSpecificMembership(sourceAddress, groupAddress\[, multicastInterface\]) +### `socket.addSourceSpecificMembership(sourceAddress, groupAddress[, multicastInterface])` @@ -138,7 +138,7 @@ is not specified, the operating system will choose one interface and will add membership to it. To add membership to every available interface, call `socket.addSourceSpecificMembership()` multiple times, once per interface. -### socket.address() +### `socket.address()` @@ -149,7 +149,7 @@ Returns an object containing the address information for a socket. For UDP sockets, this object will contain `address`, `family` and `port` properties. -### socket.bind(\[port\]\[, address\]\[, callback\]) +### `socket.bind([port][, address][, callback])` @@ -258,7 +258,7 @@ socket.bind({ }); ``` -### socket.close(\[callback\]) +### `socket.close([callback])` @@ -268,7 +268,7 @@ added: v0.1.99 Close the underlying socket and stop listening for data on it. If a callback is provided, it is added as a listener for the [`'close'`][] event. -### socket.connect(port\[, address\]\[, callback\]) +### `socket.connect(port[, address][, callback])` @@ -287,7 +287,7 @@ will be used by default. Once the connection is complete, a `'connect'` event is emitted and the optional `callback` function is called. In case of failure, the `callback` is called or, failing this, an `'error'` event is emitted. -### socket.disconnect() +### `socket.disconnect()` @@ -296,7 +296,7 @@ A synchronous function that disassociates a connected `dgram.Socket` from its remote address. Trying to call `disconnect()` on an already disconnected socket will result in an [`ERR_SOCKET_DGRAM_NOT_CONNECTED`][] exception. -### socket.dropMembership(multicastAddress\[, multicastInterface\]) +### `socket.dropMembership(multicastAddress[, multicastInterface])` @@ -312,7 +312,7 @@ never have reason to call this. If `multicastInterface` is not specified, the operating system will attempt to drop membership on all valid interfaces. -### socket.dropSourceSpecificMembership(sourceAddress, groupAddress\[, multicastInterface\]) +### `socket.dropSourceSpecificMembership(sourceAddress, groupAddress[, multicastInterface])` @@ -330,21 +330,21 @@ reason to call this. If `multicastInterface` is not specified, the operating system will attempt to drop membership on all valid interfaces. -### socket.getRecvBufferSize() +### `socket.getRecvBufferSize()` * Returns: {number} the `SO_RCVBUF` socket receive buffer size in bytes. -### socket.getSendBufferSize() +### `socket.getSendBufferSize()` * Returns: {number} the `SO_SNDBUF` socket send buffer size in bytes. -### socket.ref() +### `socket.ref()` @@ -362,7 +362,7 @@ Calling `socket.ref()` multiples times will have no additional effect. The `socket.ref()` method returns a reference to the socket so calls can be chained. -### socket.remoteAddress() +### `socket.remoteAddress()` @@ -373,7 +373,7 @@ Returns an object containing the `address`, `family`, and `port` of the remote endpoint. It throws an [`ERR_SOCKET_DGRAM_NOT_CONNECTED`][] exception if the socket is not connected. -### socket.send(msg\[, offset, length\]\[, port\]\[, address\]\[, callback\]) +### `socket.send(msg[, offset, length][, port][, address][, callback])` @@ -521,7 +521,7 @@ added: v0.6.9 Sets or clears the `SO_BROADCAST` socket option. When set to `true`, UDP packets may be sent to a local interface's broadcast address. -### socket.setMulticastInterface(multicastInterface) +### `socket.setMulticastInterface(multicastInterface)` @@ -599,7 +599,7 @@ A socket's address family's ANY address (IPv4 `'0.0.0.0'` or IPv6 `'::'`) can be used to return control of the sockets default outgoing interface to the system for future multicast packets. -### socket.setMulticastLoopback(flag) +### `socket.setMulticastLoopback(flag)` @@ -609,7 +609,7 @@ added: v0.3.8 Sets or clears the `IP_MULTICAST_LOOP` socket option. When set to `true`, multicast packets will also be received on the local interface. -### socket.setMulticastTTL(ttl) +### `socket.setMulticastTTL(ttl)` @@ -624,7 +624,7 @@ decremented to 0 by a router, it will not be forwarded. The `ttl` argument may be between 0 and 255. The default on most systems is `1`. -### socket.setRecvBufferSize(size) +### `socket.setRecvBufferSize(size)` @@ -634,7 +634,7 @@ added: v8.7.0 Sets the `SO_RCVBUF` socket option. Sets the maximum socket receive buffer in bytes. -### socket.setSendBufferSize(size) +### `socket.setSendBufferSize(size)` @@ -644,7 +644,7 @@ added: v8.7.0 Sets the `SO_SNDBUF` socket option. Sets the maximum socket send buffer in bytes. -### socket.setTTL(ttl) +### `socket.setTTL(ttl)` @@ -660,7 +660,7 @@ Changing TTL values is typically done for network probes or when multicasting. The `ttl` argument may be between between 1 and 255. The default on most systems is 64. -### socket.unref() +### `socket.unref()` @@ -680,7 +680,7 @@ chained. ## `dgram` module functions -### dgram.createSocket(options\[, callback\]) +### `dgram.createSocket(options[, callback])` diff --git a/doc/api/dns.md b/doc/api/dns.md index 34c6310519ef1c..6c7f29cfaf0f85 100644 --- a/doc/api/dns.md +++ b/doc/api/dns.md @@ -4,61 +4,53 @@ > Stability: 2 - Stable -The `dns` module contains functions belonging to two different categories: +The `dns` module enables name resolution. For example, use it to look up IP +addresses of host names. -1. Functions that use the underlying operating system facilities to perform - name resolution, and that do not necessarily perform any network - communication. - This category contains only one function: [`dns.lookup()`][]. **Developers - looking to perform name resolution in the same way that other applications - on the same operating system behave should use [`dns.lookup()`][].** +Although named for the Domain Name System (DNS), it does not always use the DNS +protocol for lookups. [`dns.lookup()`][] uses the operating system facilities to +perform name resolution. It may not need to perform any network communication. +Developers looking to perform name resolution in the same way that other +applications on the same operating system behave should use [`dns.lookup()`][]. - For example, looking up `iana.org`. +```js +const dns = require('dns'); - ```js - const dns = require('dns'); +dns.lookup('example.org', (err, address, family) => { + console.log('address: %j family: IPv%s', address, family); +}); +// address: "93.184.216.34" family: IPv4 +``` - dns.lookup('iana.org', (err, address, family) => { - console.log('address: %j family: IPv%s', address, family); - }); - // address: "192.0.43.8" family: IPv4 - ``` - -2. Functions that connect to an actual DNS server to perform name resolution, - and that _always_ use the network to perform DNS queries. This category - contains all functions in the `dns` module _except_ [`dns.lookup()`][]. - These functions do not use the same set of configuration files used by - [`dns.lookup()`][] (e.g. `/etc/hosts`). These functions should be used by - developers who do not want to use the underlying operating system's - facilities for name resolution, and instead want to _always_ perform DNS - queries. - - Below is an example that resolves `'archive.org'` then reverse resolves the - IP addresses that are returned. - - ```js - const dns = require('dns'); - - dns.resolve4('archive.org', (err, addresses) => { - if (err) throw err; - - console.log(`addresses: ${JSON.stringify(addresses)}`); - - addresses.forEach((a) => { - dns.reverse(a, (err, hostnames) => { - if (err) { - throw err; - } - console.log(`reverse for ${a}: ${JSON.stringify(hostnames)}`); - }); - }); +All other functions in the `dns` module connect to an actual DNS server to +perform name resolution. They will always use the network to perform DNS +queries. These functions do not use the same set of configuration files used by +[`dns.lookup()`][] (e.g. `/etc/hosts`). These functions should be used by +developers who do not want to use the underlying operating system's +facilities for name resolution, and instead want to always perform DNS queries. + +```js +const dns = require('dns'); + +dns.resolve4('archive.org', (err, addresses) => { + if (err) throw err; + + console.log(`addresses: ${JSON.stringify(addresses)}`); + + addresses.forEach((a) => { + dns.reverse(a, (err, hostnames) => { + if (err) { + throw err; + } + console.log(`reverse for ${a}: ${JSON.stringify(hostnames)}`); }); - ``` + }); +}); +``` -There are subtle consequences in choosing one over the other, please consult -the [Implementation considerations section][] for more information. +See the [Implementation considerations section][] for more information. -## Class: dns.Resolver +## Class: `dns.Resolver` @@ -99,7 +91,7 @@ The following methods from the `dns` module are available: * [`resolver.reverse()`][`dns.reverse()`] * [`resolver.setServers()`][`dns.setServers()`] -### resolver.cancel() +### `resolver.cancel()` @@ -107,7 +99,7 @@ added: v8.3.0 Cancel all outstanding DNS queries made by this resolver. The corresponding callbacks will be called with an error with code `ECANCELLED`. -## dns.getServers() +## `dns.getServers()` @@ -128,7 +120,7 @@ section if a custom port is used. ] ``` -## dns.lookup(hostname\[, options\], callback) +## `dns.lookup(hostname[, options], callback)` @@ -230,7 +222,7 @@ added: v0.11.14 * `hostname` {string} e.g. `example.com` * `service` {string} e.g. `http` -Resolves the given `address` and `port` into a hostname and service using +Resolves the given `address` and `port` into a host name and service using the operating system's underlying `getnameinfo` implementation. If `address` is not a valid IP address, a `TypeError` will be thrown. @@ -250,18 +242,18 @@ dns.lookupService('127.0.0.1', 22, (err, hostname, service) => { If this method is invoked as its [`util.promisify()`][]ed version, it returns a `Promise` for an `Object` with `hostname` and `service` properties. -## dns.resolve(hostname\[, rrtype\], callback) +## `dns.resolve(hostname[, rrtype], callback)` -* `hostname` {string} Hostname to resolve. +* `hostname` {string} Host name to resolve. * `rrtype` {string} Resource record type. **Default:** `'A'`. * `callback` {Function} * `err` {Error} * `records` {string[] | Object[] | Object} -Uses the DNS protocol to resolve a hostname (e.g. `'nodejs.org'`) into an array +Uses the DNS protocol to resolve a host name (e.g. `'nodejs.org'`) into an array of the resource records. The `callback` function has arguments `(err, records)`. When successful, `records` will be an array of resource records. The type and structure of individual results varies based on `rrtype`: @@ -283,7 +275,7 @@ records. The type and structure of individual results varies based on `rrtype`: On error, `err` is an [`Error`][] object, where `err.code` is one of the [DNS error codes](#dns_error_codes). -## dns.resolve4(hostname\[, options\], callback) +## `dns.resolve4(hostname[, options], callback)` -* `hostname` {string} Hostname to resolve. +* `hostname` {string} Host name to resolve. * `options` {Object} * `ttl` {boolean} Retrieve the Time-To-Live value (TTL) of each record. When `true`, the callback receives an array of @@ -308,7 +300,7 @@ Uses the DNS protocol to resolve a IPv4 addresses (`A` records) for the will contain an array of IPv4 addresses (e.g. `['74.125.79.104', '74.125.79.105', '74.125.79.106']`). -## dns.resolve6(hostname\[, options\], callback) +## `dns.resolve6(hostname[, options], callback)` -* `hostname` {string} Hostname to resolve. +* `hostname` {string} Host name to resolve. * `options` {Object} * `ttl` {boolean} Retrieve the Time-To-Live value (TTL) of each record. When `true`, the callback receives an array of @@ -332,7 +324,7 @@ Uses the DNS protocol to resolve a IPv6 addresses (`AAAA` records) for the `hostname`. The `addresses` argument passed to the `callback` function will contain an array of IPv6 addresses. -## dns.resolveAny(hostname, callback) +## `dns.resolveAny(hostname, callback)` * `hostname` {string} * `callback` {Function} @@ -381,7 +373,7 @@ DNS server operators may choose not to respond to `ANY` queries. It may be better to call individual methods like [`dns.resolve4()`][], [`dns.resolveMx()`][], and so on. For more details, see [RFC 8482][]. -## dns.resolveCname(hostname, callback) +## `dns.resolveCname(hostname, callback)` @@ -396,7 +388,7 @@ Uses the DNS protocol to resolve `CNAME` records for the `hostname`. The will contain an array of canonical name records available for the `hostname` (e.g. `['bar.example.com']`). -## dns.resolveMx(hostname, callback) +## `dns.resolveMx(hostname, callback)` @@ -411,7 +403,7 @@ Uses the DNS protocol to resolve mail exchange records (`MX` records) for the contain an array of objects containing both a `priority` and `exchange` property (e.g. `[{priority: 10, exchange: 'mx.example.com'}, ...]`). -## dns.resolveNaptr(hostname, callback) +## `dns.resolveNaptr(hostname, callback)` @@ -444,7 +436,7 @@ function will contain an array of objects with the following properties: } ``` -## dns.resolveNs(hostname, callback) +## `dns.resolveNs(hostname, callback)` @@ -459,7 +451,7 @@ Uses the DNS protocol to resolve name server records (`NS` records) for the contain an array of name server records available for `hostname` (e.g. `['ns1.example.com', 'ns2.example.com']`). -## dns.resolvePtr(hostname, callback) +## `dns.resolvePtr(hostname, callback)` @@ -473,7 +465,7 @@ Uses the DNS protocol to resolve pointer records (`PTR` records) for the `hostname`. The `addresses` argument passed to the `callback` function will be an array of strings containing the reply records. -## dns.resolveSoa(hostname, callback) +## `dns.resolveSoa(hostname, callback)` @@ -508,7 +500,7 @@ be an object with the following properties: } ``` -## dns.resolveSrv(hostname, callback) +## `dns.resolveSrv(hostname, callback)` @@ -537,7 +529,7 @@ be an array of objects with the following properties: } ``` -## dns.resolveTxt(hostname, callback) +## `dns.resolveTxt(hostname, callback)` @@ -554,7 +546,7 @@ two-dimensional array of the text records available for `hostname` (e.g. one record. Depending on the use case, these could be either joined together or treated separately. -## dns.reverse(ip, callback) +## `dns.reverse(ip, callback)` @@ -565,12 +557,12 @@ added: v0.1.16 * `hostnames` {string[]} Performs a reverse DNS query that resolves an IPv4 or IPv6 address to an -array of hostnames. +array of host names. On error, `err` is an [`Error`][] object, where `err.code` is one of the [DNS error codes][]. -## dns.setServers(servers) +## `dns.setServers(servers)` @@ -612,7 +604,7 @@ The `dns.promises` API provides an alternative set of asynchronous DNS methods that return `Promise` objects rather than using callbacks. The API is accessible via `require('dns').promises`. -### Class: dnsPromises.Resolver +### Class: `dnsPromises.Resolver` @@ -658,7 +650,7 @@ The following methods from the `dnsPromises` API are available: * [`resolver.reverse()`][`dnsPromises.reverse()`] * [`resolver.setServers()`][`dnsPromises.setServers()`] -### dnsPromises.getServers() +### `dnsPromises.getServers()` @@ -679,7 +671,7 @@ section if a custom port is used. ] ``` -### dnsPromises.lookup(hostname\[, options\]) +### `dnsPromises.lookup(hostname[, options])` @@ -700,7 +692,7 @@ added: v10.6.0 expected to change in the not too distant future. New code should use `{ verbatim: true }`. -Resolves a hostname (e.g. `'nodejs.org'`) into the first found A (IPv4) or +Resolves a host name (e.g. `'nodejs.org'`) into the first found A (IPv4) or AAAA (IPv6) record. All `option` properties are optional. If `options` is an integer, then it must be `4` or `6` – if `options` is not provided, then IPv4 and IPv6 addresses are both returned if found. @@ -711,7 +703,7 @@ being an array of objects with the properties `address` and `family`. On error, the `Promise` is rejected with an [`Error`][] object, where `err.code` is the error code. Keep in mind that `err.code` will be set to `'ENOTFOUND'` not only when -the hostname does not exist but also when the lookup fails in other ways +the host name does not exist but also when the lookup fails in other ways such as no available file descriptors. [`dnsPromises.lookup()`][] does not necessarily have anything to do with the DNS @@ -744,7 +736,7 @@ dnsPromises.lookup('example.com', options).then((result) => { }); ``` -### dnsPromises.lookupService(address, port) +### `dnsPromises.lookupService(address, port)` @@ -752,7 +744,7 @@ added: v10.6.0 * `address` {string} * `port` {number} -Resolves the given `address` and `port` into a hostname and service using +Resolves the given `address` and `port` into a host name and service using the operating system's underlying `getnameinfo` implementation. If `address` is not a valid IP address, a `TypeError` will be thrown. @@ -770,15 +762,15 @@ dnsPromises.lookupService('127.0.0.1', 22).then((result) => { }); ``` -### dnsPromises.resolve(hostname\[, rrtype\]) +### `dnsPromises.resolve(hostname[, rrtype])` -* `hostname` {string} Hostname to resolve. +* `hostname` {string} Host name to resolve. * `rrtype` {string} Resource record type. **Default:** `'A'`. -Uses the DNS protocol to resolve a hostname (e.g. `'nodejs.org'`) into an array +Uses the DNS protocol to resolve a host name (e.g. `'nodejs.org'`) into an array of the resource records. When successful, the `Promise` is resolved with an array of resource records. The type and structure of individual results vary based on `rrtype`: @@ -800,12 +792,12 @@ based on `rrtype`: On error, the `Promise` is rejected with an [`Error`][] object, where `err.code` is one of the [DNS error codes](#dns_error_codes). -### dnsPromises.resolve4(hostname\[, options\]) +### `dnsPromises.resolve4(hostname[, options])` -* `hostname` {string} Hostname to resolve. +* `hostname` {string} Host name to resolve. * `options` {Object} * `ttl` {boolean} Retrieve the Time-To-Live value (TTL) of each record. When `true`, the `Promise` is resolved with an array of @@ -816,12 +808,12 @@ Uses the DNS protocol to resolve IPv4 addresses (`A` records) for the `hostname`. On success, the `Promise` is resolved with an array of IPv4 addresses (e.g. `['74.125.79.104', '74.125.79.105', '74.125.79.106']`). -### dnsPromises.resolve6(hostname\[, options\]) +### `dnsPromises.resolve6(hostname[, options])` -* `hostname` {string} Hostname to resolve. +* `hostname` {string} Host name to resolve. * `options` {Object} * `ttl` {boolean} Retrieve the Time-To-Live value (TTL) of each record. When `true`, the `Promise` is resolved with an array of @@ -832,7 +824,7 @@ Uses the DNS protocol to resolve IPv6 addresses (`AAAA` records) for the `hostname`. On success, the `Promise` is resolved with an array of IPv6 addresses. -### dnsPromises.resolveAny(hostname) +### `dnsPromises.resolveAny(hostname)` @@ -877,7 +869,7 @@ Here is an example of the result object: minttl: 60 } ] ``` -### dnsPromises.resolveCname(hostname) +### `dnsPromises.resolveCname(hostname)` @@ -888,7 +880,7 @@ Uses the DNS protocol to resolve `CNAME` records for the `hostname`. On success, the `Promise` is resolved with an array of canonical name records available for the `hostname` (e.g. `['bar.example.com']`). -### dnsPromises.resolveMx(hostname) +### `dnsPromises.resolveMx(hostname)` @@ -900,7 +892,7 @@ Uses the DNS protocol to resolve mail exchange records (`MX` records) for the containing both a `priority` and `exchange` property (e.g. `[{priority: 10, exchange: 'mx.example.com'}, ...]`). -### dnsPromises.resolveNaptr(hostname) +### `dnsPromises.resolveNaptr(hostname)` @@ -930,7 +922,7 @@ of objects with the following properties: } ``` -### dnsPromises.resolveNs(hostname) +### `dnsPromises.resolveNs(hostname)` @@ -942,7 +934,7 @@ Uses the DNS protocol to resolve name server records (`NS` records) for the records available for `hostname` (e.g. `['ns1.example.com', 'ns2.example.com']`). -### dnsPromises.resolvePtr(hostname) +### `dnsPromises.resolvePtr(hostname)` @@ -953,7 +945,7 @@ Uses the DNS protocol to resolve pointer records (`PTR` records) for the `hostname`. On success, the `Promise` is resolved with an array of strings containing the reply records. -### dnsPromises.resolveSoa(hostname) +### `dnsPromises.resolveSoa(hostname)` @@ -985,7 +977,7 @@ following properties: } ``` -### dnsPromises.resolveSrv(hostname) +### `dnsPromises.resolveSrv(hostname)` @@ -1011,7 +1003,7 @@ the following properties: } ``` -### dnsPromises.resolveTxt(hostname) +### `dnsPromises.resolveTxt(hostname)` @@ -1025,7 +1017,7 @@ of the text records available for `hostname` (e.g. one record. Depending on the use case, these could be either joined together or treated separately. -### dnsPromises.reverse(ip) +### `dnsPromises.reverse(ip)` @@ -1033,12 +1025,12 @@ added: v10.6.0 * `ip` {string} Performs a reverse DNS query that resolves an IPv4 or IPv6 address to an -array of hostnames. +array of host names. On error, the `Promise` is rejected with an [`Error`][] object, where `err.code` is one of the [DNS error codes](#dns_error_codes). -### dnsPromises.setServers(servers) +### `dnsPromises.setServers(servers)` @@ -1081,7 +1073,7 @@ Each DNS query can return one of the following error codes: * `dns.NOTIMP`: DNS server does not implement requested operation. * `dns.REFUSED`: DNS server refused query. * `dns.BADQUERY`: Misformatted DNS query. -* `dns.BADNAME`: Misformatted hostname. +* `dns.BADNAME`: Misformatted host name. * `dns.BADFAMILY`: Unsupported address family. * `dns.BADRESP`: Misformatted DNS reply. * `dns.CONNREFUSED`: Could not contact DNS servers. @@ -1092,7 +1084,7 @@ Each DNS query can return one of the following error codes: * `dns.DESTRUCTION`: Channel is being destroyed. * `dns.BADSTR`: Misformatted string. * `dns.BADFLAGS`: Illegal flags specified. -* `dns.NONAME`: Given hostname is not numeric. +* `dns.NONAME`: Given host name is not numeric. * `dns.BADHINTS`: Illegal hints flags specified. * `dns.NOTINITIALIZED`: c-ares library initialization not yet performed. * `dns.LOADIPHLPAPI`: Error loading `iphlpapi.dll`. @@ -1124,7 +1116,7 @@ implications for some applications, see the [`UV_THREADPOOL_SIZE`][] documentation for more information. Various networking APIs will call `dns.lookup()` internally to resolve -host names. If that is an issue, consider resolving the hostname to an address +host names. If that is an issue, consider resolving the host name to an address using `dns.resolve()` and using the address instead of a host name. Also, some networking APIs (such as [`socket.connect()`][] and [`dgram.createSocket()`][]) allow the default resolver, `dns.lookup()`, to be replaced. diff --git a/doc/api/domain.md b/doc/api/domain.md index d0ba5a446d983d..fa3aef66b98241 100644 --- a/doc/api/domain.md +++ b/doc/api/domain.md @@ -184,7 +184,7 @@ function handleRequest(req, res) { } ``` -## Additions to Error objects +## Additions to `Error` objects @@ -267,11 +267,11 @@ serverDomain.run(() => { }); ``` -## domain.create() +## `domain.create()` * Returns: {Domain} -## Class: Domain +## Class: `Domain` * Extends: {EventEmitter} @@ -280,14 +280,14 @@ uncaught exceptions to the active `Domain` object. To handle the errors that it catches, listen to its `'error'` event. -### domain.members +### `domain.members` * {Array} An array of timers and event emitters that have been explicitly added to the domain. -### domain.add(emitter) +### `domain.add(emitter)` * `emitter` {EventEmitter|Timer} emitter or timer to be added to the domain @@ -303,7 +303,7 @@ the domain `'error'` handler. If the Timer or `EventEmitter` was already bound to a domain, it is removed from that one, and bound to this one instead. -### domain.bind(callback) +### `domain.bind(callback)` * `callback` {Function} The callback function * Returns: {Function} The bound function @@ -328,7 +328,7 @@ d.on('error', (er) => { }); ``` -### domain.enter() +### `domain.enter()` The `enter()` method is plumbing used by the `run()`, `bind()`, and `intercept()` methods to set the active domain. It sets `domain.active` and @@ -341,7 +341,7 @@ Calling `enter()` changes only the active domain, and does not alter the domain itself. `enter()` and `exit()` can be called an arbitrary number of times on a single domain. -### domain.exit() +### `domain.exit()` The `exit()` method exits the current domain, popping it off the domain stack. Any time execution is going to switch to the context of a different chain of @@ -356,7 +356,7 @@ Calling `exit()` changes only the active domain, and does not alter the domain itself. `enter()` and `exit()` can be called an arbitrary number of times on a single domain. -### domain.intercept(callback) +### `domain.intercept(callback)` * `callback` {Function} The callback function * Returns: {Function} The intercepted function @@ -391,14 +391,14 @@ d.on('error', (er) => { }); ``` -### domain.remove(emitter) +### `domain.remove(emitter)` * `emitter` {EventEmitter|Timer} emitter or timer to be removed from the domain The opposite of [`domain.add(emitter)`][]. Removes domain handling from the specified emitter. -### domain.run(fn\[, ...args\]) +### `domain.run(fn[, ...args])` * `fn` {Function} * `...args` {any} diff --git a/doc/api/errors.md b/doc/api/errors.md index cf21c142d6dd97..c5041c796be011 100644 --- a/doc/api/errors.md +++ b/doc/api/errors.md @@ -177,7 +177,7 @@ Throwing an error inside the callback **can crash the Node.js process** in most cases. If [domains][] are enabled, or a handler has been registered with `process.on('uncaughtException')`, such errors can be intercepted. -## Class: Error +## Class: `Error` @@ -189,7 +189,7 @@ provide a text description of the error. All errors generated by Node.js, including all System and JavaScript errors, will either be instances of, or inherit from, the `Error` class. -### new Error(message) +### `new Error(message)` * `message` {string} @@ -201,7 +201,7 @@ are dependent on [V8's stack trace API][]. Stack traces extend only to either (a) the beginning of *synchronous code execution*, or (b) the number of frames given by the property `Error.stackTraceLimit`, whichever is smaller. -### Error.captureStackTrace(targetObject\[, constructorOpt\]) +### `Error.captureStackTrace(targetObject[, constructorOpt])` * `targetObject` {Object} * `constructorOpt` {Function} @@ -237,7 +237,7 @@ function MyError() { new MyError().stack; ``` -### Error.stackTraceLimit +### `Error.stackTraceLimit` * {number} @@ -251,7 +251,7 @@ will affect any stack trace captured *after* the value has been changed. If set to a non-number value, or set to a negative number, stack traces will not capture any frames. -### error.code +### `error.code` * {string} @@ -261,7 +261,7 @@ between major versions of Node.js. In contrast, `error.message` strings may change between any versions of Node.js. See [Node.js Error Codes][] for details about specific codes. -### error.message +### `error.message` * {string} @@ -278,7 +278,7 @@ console.error(err.message); // Prints: The message ``` -### error.stack +### `error.stack` * {string} @@ -351,14 +351,14 @@ The number of frames captured by the stack trace is bounded by the smaller of `Error.stackTraceLimit` or the number of available frames on the current event loop tick. -## Class: AssertionError +## Class: `AssertionError` * Extends: {errors.Error} Indicates the failure of an assertion. For details, see [`Class: assert.AssertionError`][]. -## Class: RangeError +## Class: `RangeError` * Extends: {errors.Error} @@ -374,7 +374,7 @@ require('net').connect(-1); Node.js will generate and throw `RangeError` instances *immediately* as a form of argument validation. -## Class: ReferenceError +## Class: `ReferenceError` * Extends: {errors.Error} @@ -394,7 +394,7 @@ Unless an application is dynamically generating and running code, `ReferenceError` instances should always be considered a bug in the code or its dependencies. -## Class: SyntaxError +## Class: `SyntaxError` * Extends: {errors.Error} @@ -414,7 +414,7 @@ try { `SyntaxError` instances are unrecoverable in the context that created them – they may only be caught by other contexts. -## Class: SystemError +## Class: `SystemError` * Extends: {errors.Error} @@ -435,27 +435,27 @@ attempts to read a file that does not exist. * `port` {number} If present, the network connection port that is not available * `syscall` {string} The name of the system call that triggered the error -### error.address +### `error.address` * {string} If present, `error.address` is a string describing the address to which a network connection failed. -### error.code +### `error.code` * {string} The `error.code` property is a string representing the error code. -### error.dest +### `error.dest` * {string} If present, `error.dest` is the file path destination when reporting a file system error. -### error.errno +### `error.errno` * {number} @@ -467,31 +467,31 @@ On Windows the error number provided by the system will be normalized by libuv. To get the string representation of the error code, use [`util.getSystemErrorName(error.errno)`][]. -### error.info +### `error.info` * {Object} If present, `error.info` is an object with details about the error condition. -### error.message +### `error.message` * {string} `error.message` is a system-provided human-readable description of the error. -### error.path +### `error.path` * {string} If present, `error.path` is a string containing a relevant invalid pathname. -### error.port +### `error.port` * {number} If present, `error.port` is the network connection port that is not available. -### error.syscall +### `error.syscall` * {string} @@ -558,7 +558,7 @@ program. For a comprehensive list, see the [`errno`(3) man page][]. encountered by [`http`][] or [`net`][] — often a sign that a `socket.end()` was not properly called. -## Class: TypeError +## Class: `TypeError` * Extends {errors.Error} @@ -594,20 +594,20 @@ Errors originating in `crypto` or `tls` are of class `Error`, and in addition to the standard `.code` and `.message` properties, may have some additional OpenSSL-specific properties. -### error.opensslErrorStack +### `error.opensslErrorStack` An array of errors that can give context to where in the OpenSSL library an error originates from. -### error.function +### `error.function` The OpenSSL function the error originates in. -### error.library +### `error.library` The OpenSSL library the error originates in. -### error.reason +### `error.reason` A human-readable string describing the reason for the error. @@ -615,7 +615,7 @@ A human-readable string describing the reason for the error. ## Node.js Error Codes -### ERR_AMBIGUOUS_ARGUMENT +### `ERR_AMBIGUOUS_ARGUMENT` A function argument is being used in a way that suggests that the function signature may be misunderstood. This is thrown by the `assert` module when the @@ -625,42 +625,42 @@ is the expected message rather than the message the `AssertionError` will display if `block` does not throw. -### ERR_ARG_NOT_ITERABLE +### `ERR_ARG_NOT_ITERABLE` An iterable argument (i.e. a value that works with `for...of` loops) was required, but not provided to a Node.js API. -### ERR_ASSERTION +### `ERR_ASSERTION` A special type of error that can be triggered whenever Node.js detects an exceptional logic violation that should never occur. These are raised typically by the `assert` module. -### ERR_ASYNC_CALLBACK +### `ERR_ASYNC_CALLBACK` An attempt was made to register something that is not a function as an `AsyncHooks` callback. -### ERR_ASYNC_TYPE +### `ERR_ASYNC_TYPE` The type of an asynchronous resource was invalid. Users are also able to define their own types if using the public embedder API. -### ERR_BROTLI_COMPRESSION_FAILED +### `ERR_BROTLI_COMPRESSION_FAILED` Data passed to a Brotli stream was not successfully compressed. -### ERR_BROTLI_INVALID_PARAM +### `ERR_BROTLI_INVALID_PARAM` An invalid parameter key was passed during construction of a Brotli stream. -### ERR_BUFFER_CONTEXT_NOT_AVAILABLE +### `ERR_BUFFER_CONTEXT_NOT_AVAILABLE` An attempt was made to create a Node.js `Buffer` instance from addon or embedder code, while in a JS engine Context that is not associated with a Node.js @@ -673,50 +673,50 @@ prototype of the resulting object. `Uint8Array`s are generally accepted in all Node.js core APIs where `Buffer`s are; they are available in all Contexts. -### ERR_BUFFER_OUT_OF_BOUNDS +### `ERR_BUFFER_OUT_OF_BOUNDS` An operation outside the bounds of a `Buffer` was attempted. -### ERR_BUFFER_TOO_LARGE +### `ERR_BUFFER_TOO_LARGE` An attempt has been made to create a `Buffer` larger than the maximum allowed size. -### ERR_CANNOT_WATCH_SIGINT +### `ERR_CANNOT_WATCH_SIGINT` Node.js was unable to watch for the `SIGINT` signal. -### ERR_CHILD_CLOSED_BEFORE_REPLY +### `ERR_CHILD_CLOSED_BEFORE_REPLY` A child process was closed before the parent received a reply. -### ERR_CHILD_PROCESS_IPC_REQUIRED +### `ERR_CHILD_PROCESS_IPC_REQUIRED` Used when a child process is being forked without specifying an IPC channel. -### ERR_CHILD_PROCESS_STDIO_MAXBUFFER +### `ERR_CHILD_PROCESS_STDIO_MAXBUFFER` Used when the main process is trying to read data from the child process's STDERR/STDOUT, and the data's length is longer than the `maxBuffer` option. -### ERR_CONSOLE_WRITABLE_STREAM +### `ERR_CONSOLE_WRITABLE_STREAM` `Console` was instantiated without `stdout` stream, or `Console` has a non-writable `stdout` or `stderr` stream. -### ERR_CONSTRUCT_CALL_REQUIRED +### `ERR_CONSTRUCT_CALL_REQUIRED` A constructor for a class was called without `new`. -### ERR_CONSTRUCT_CALL_INVALID +### `ERR_CONSTRUCT_CALL_INVALID` @@ -724,120 +724,120 @@ added: v12.5.0 A class constructor was called that is not callable. -### ERR_CPU_USAGE +### `ERR_CPU_USAGE` The native call from `process.cpuUsage` could not be processed. -### ERR_CRYPTO_CUSTOM_ENGINE_NOT_SUPPORTED +### `ERR_CRYPTO_CUSTOM_ENGINE_NOT_SUPPORTED` A client certificate engine was requested that is not supported by the version of OpenSSL being used. -### ERR_CRYPTO_ECDH_INVALID_FORMAT +### `ERR_CRYPTO_ECDH_INVALID_FORMAT` An invalid value for the `format` argument was passed to the `crypto.ECDH()` class `getPublicKey()` method. -### ERR_CRYPTO_ECDH_INVALID_PUBLIC_KEY +### `ERR_CRYPTO_ECDH_INVALID_PUBLIC_KEY` An invalid value for the `key` argument has been passed to the `crypto.ECDH()` class `computeSecret()` method. It means that the public key lies outside of the elliptic curve. -### ERR_CRYPTO_ENGINE_UNKNOWN +### `ERR_CRYPTO_ENGINE_UNKNOWN` An invalid crypto engine identifier was passed to [`require('crypto').setEngine()`][]. -### ERR_CRYPTO_FIPS_FORCED +### `ERR_CRYPTO_FIPS_FORCED` The [`--force-fips`][] command-line argument was used but there was an attempt to enable or disable FIPS mode in the `crypto` module. -### ERR_CRYPTO_FIPS_UNAVAILABLE +### `ERR_CRYPTO_FIPS_UNAVAILABLE` An attempt was made to enable or disable FIPS mode, but FIPS mode was not available. -### ERR_CRYPTO_HASH_FINALIZED +### `ERR_CRYPTO_HASH_FINALIZED` [`hash.digest()`][] was called multiple times. The `hash.digest()` method must be called no more than one time per instance of a `Hash` object. -### ERR_CRYPTO_HASH_UPDATE_FAILED +### `ERR_CRYPTO_HASH_UPDATE_FAILED` [`hash.update()`][] failed for any reason. This should rarely, if ever, happen. -### ERR_CRYPTO_INCOMPATIBLE_KEY_OPTIONS +### `ERR_CRYPTO_INCOMPATIBLE_KEY_OPTIONS` The selected public or private key encoding is incompatible with other options. -### ERR_CRYPTO_INVALID_DIGEST +### `ERR_CRYPTO_INVALID_DIGEST` An invalid [crypto digest algorithm][] was specified. -### ERR_CRYPTO_INVALID_KEY_OBJECT_TYPE +### `ERR_CRYPTO_INVALID_KEY_OBJECT_TYPE` The given crypto key object's type is invalid for the attempted operation. -### ERR_CRYPTO_INVALID_STATE +### `ERR_CRYPTO_INVALID_STATE` A crypto method was used on an object that was in an invalid state. For instance, calling [`cipher.getAuthTag()`][] before calling `cipher.final()`. -### ERR_CRYPTO_PBKDF2_ERROR +### `ERR_CRYPTO_PBKDF2_ERROR` The PBKDF2 algorithm failed for unspecified reasons. OpenSSL does not provide more details and therefore neither does Node.js. -### ERR_CRYPTO_SCRYPT_INVALID_PARAMETER +### `ERR_CRYPTO_SCRYPT_INVALID_PARAMETER` One or more [`crypto.scrypt()`][] or [`crypto.scryptSync()`][] parameters are outside their legal range. -### ERR_CRYPTO_SCRYPT_NOT_SUPPORTED +### `ERR_CRYPTO_SCRYPT_NOT_SUPPORTED` Node.js was compiled without `scrypt` support. Not possible with the official release binaries but can happen with custom builds, including distro builds. -### ERR_CRYPTO_SIGN_KEY_REQUIRED +### `ERR_CRYPTO_SIGN_KEY_REQUIRED` A signing `key` was not provided to the [`sign.sign()`][] method. -### ERR_CRYPTO_TIMING_SAFE_EQUAL_LENGTH +### `ERR_CRYPTO_TIMING_SAFE_EQUAL_LENGTH` [`crypto.timingSafeEqual()`][] was called with `Buffer`, `TypedArray`, or `DataView` arguments of different lengths. -### ERR_DIR_CLOSED +### `ERR_DIR_CLOSED` The [`fs.Dir`][] was previously closed. -### ERR_DNS_SET_SERVERS_FAILED +### `ERR_DNS_SET_SERVERS_FAILED` `c-ares` failed to set the DNS server. -### ERR_DOMAIN_CALLBACK_NOT_AVAILABLE +### `ERR_DOMAIN_CALLBACK_NOT_AVAILABLE` The `domain` module was not usable since it could not establish the required error handling hooks, because @@ -845,7 +845,7 @@ error handling hooks, because earlier point in time. -### ERR_DOMAIN_CANNOT_SET_UNCAUGHT_EXCEPTION_CAPTURE +### `ERR_DOMAIN_CANNOT_SET_UNCAUGHT_EXCEPTION_CAPTURE` [`process.setUncaughtExceptionCaptureCallback()`][] could not be called because the `domain` module has been loaded at an earlier point in time. @@ -854,170 +854,170 @@ The stack trace is extended to include the point in time at which the `domain` module had been loaded. -### ERR_ENCODING_INVALID_ENCODED_DATA +### `ERR_ENCODING_INVALID_ENCODED_DATA` Data provided to `TextDecoder()` API was invalid according to the encoding provided. -### ERR_ENCODING_NOT_SUPPORTED +### `ERR_ENCODING_NOT_SUPPORTED` Encoding provided to `TextDecoder()` API was not one of the [WHATWG Supported Encodings][]. -### ERR_FALSY_VALUE_REJECTION +### `ERR_FALSY_VALUE_REJECTION` A `Promise` that was callbackified via `util.callbackify()` was rejected with a falsy value. -### ERR_FS_FILE_TOO_LARGE +### `ERR_FS_FILE_TOO_LARGE` An attempt has been made to read a file whose size is larger than the maximum allowed size for a `Buffer`. -### ERR_FS_INVALID_SYMLINK_TYPE +### `ERR_FS_INVALID_SYMLINK_TYPE` An invalid symlink type was passed to the [`fs.symlink()`][] or [`fs.symlinkSync()`][] methods. -### ERR_HTTP_HEADERS_SENT +### `ERR_HTTP_HEADERS_SENT` An attempt was made to add more headers after the headers had already been sent. -### ERR_HTTP_INVALID_HEADER_VALUE +### `ERR_HTTP_INVALID_HEADER_VALUE` An invalid HTTP header value was specified. -### ERR_HTTP_INVALID_STATUS_CODE +### `ERR_HTTP_INVALID_STATUS_CODE` Status code was outside the regular status code range (100-999). -### ERR_HTTP_TRAILER_INVALID +### `ERR_HTTP_TRAILER_INVALID` The `Trailer` header was set even though the transfer encoding does not support that. -### ERR_HTTP2_ALTSVC_INVALID_ORIGIN +### `ERR_HTTP2_ALTSVC_INVALID_ORIGIN` HTTP/2 ALTSVC frames require a valid origin. -### ERR_HTTP2_ALTSVC_LENGTH +### `ERR_HTTP2_ALTSVC_LENGTH` HTTP/2 ALTSVC frames are limited to a maximum of 16,382 payload bytes. -### ERR_HTTP2_CONNECT_AUTHORITY +### `ERR_HTTP2_CONNECT_AUTHORITY` For HTTP/2 requests using the `CONNECT` method, the `:authority` pseudo-header is required. -### ERR_HTTP2_CONNECT_PATH +### `ERR_HTTP2_CONNECT_PATH` For HTTP/2 requests using the `CONNECT` method, the `:path` pseudo-header is forbidden. -### ERR_HTTP2_CONNECT_SCHEME +### `ERR_HTTP2_CONNECT_SCHEME` For HTTP/2 requests using the `CONNECT` method, the `:scheme` pseudo-header is forbidden. -### ERR_HTTP2_ERROR +### `ERR_HTTP2_ERROR` A non-specific HTTP/2 error has occurred. -### ERR_HTTP2_GOAWAY_SESSION +### `ERR_HTTP2_GOAWAY_SESSION` New HTTP/2 Streams may not be opened after the `Http2Session` has received a `GOAWAY` frame from the connected peer. -### ERR_HTTP2_HEADERS_AFTER_RESPOND +### `ERR_HTTP2_HEADERS_AFTER_RESPOND` An additional headers was specified after an HTTP/2 response was initiated. -### ERR_HTTP2_HEADERS_SENT +### `ERR_HTTP2_HEADERS_SENT` An attempt was made to send multiple response headers. -### ERR_HTTP2_HEADER_SINGLE_VALUE +### `ERR_HTTP2_HEADER_SINGLE_VALUE` Multiple values were provided for an HTTP/2 header field that was required to have only a single value. -### ERR_HTTP2_INFO_STATUS_NOT_ALLOWED +### `ERR_HTTP2_INFO_STATUS_NOT_ALLOWED` Informational HTTP status codes (`1xx`) may not be set as the response status code on HTTP/2 responses. -### ERR_HTTP2_INVALID_CONNECTION_HEADERS +### `ERR_HTTP2_INVALID_CONNECTION_HEADERS` HTTP/1 connection specific headers are forbidden to be used in HTTP/2 requests and responses. -### ERR_HTTP2_INVALID_HEADER_VALUE +### `ERR_HTTP2_INVALID_HEADER_VALUE` An invalid HTTP/2 header value was specified. -### ERR_HTTP2_INVALID_INFO_STATUS +### `ERR_HTTP2_INVALID_INFO_STATUS` An invalid HTTP informational status code has been specified. Informational status codes must be an integer between `100` and `199` (inclusive). -### ERR_HTTP2_INVALID_ORIGIN +### `ERR_HTTP2_INVALID_ORIGIN` HTTP/2 `ORIGIN` frames require a valid origin. -### ERR_HTTP2_INVALID_PACKED_SETTINGS_LENGTH +### `ERR_HTTP2_INVALID_PACKED_SETTINGS_LENGTH` Input `Buffer` and `Uint8Array` instances passed to the `http2.getUnpackedSettings()` API must have a length that is a multiple of six. -### ERR_HTTP2_INVALID_PSEUDOHEADER +### `ERR_HTTP2_INVALID_PSEUDOHEADER` Only valid HTTP/2 pseudoheaders (`:status`, `:path`, `:authority`, `:scheme`, and `:method`) may be used. -### ERR_HTTP2_INVALID_SESSION +### `ERR_HTTP2_INVALID_SESSION` An action was performed on an `Http2Session` object that had already been destroyed. -### ERR_HTTP2_INVALID_SETTING_VALUE +### `ERR_HTTP2_INVALID_SETTING_VALUE` An invalid value has been specified for an HTTP/2 setting. -### ERR_HTTP2_INVALID_STREAM +### `ERR_HTTP2_INVALID_STREAM` An operation was performed on a stream that had already been destroyed. -### ERR_HTTP2_MAX_PENDING_SETTINGS_ACK +### `ERR_HTTP2_MAX_PENDING_SETTINGS_ACK` Whenever an HTTP/2 `SETTINGS` frame is sent to a connected peer, the peer is required to send an acknowledgment that it has received and applied the new @@ -1026,127 +1026,127 @@ be sent at any given time. This error code is used when that limit has been reached. -### ERR_HTTP2_NESTED_PUSH +### `ERR_HTTP2_NESTED_PUSH` An attempt was made to initiate a new push stream from within a push stream. Nested push streams are not permitted. -### ERR_HTTP2_NO_SOCKET_MANIPULATION +### `ERR_HTTP2_NO_SOCKET_MANIPULATION` An attempt was made to directly manipulate (read, write, pause, resume, etc.) a socket attached to an `Http2Session`. -### ERR_HTTP2_ORIGIN_LENGTH +### `ERR_HTTP2_ORIGIN_LENGTH` HTTP/2 `ORIGIN` frames are limited to a length of 16382 bytes. -### ERR_HTTP2_OUT_OF_STREAMS +### `ERR_HTTP2_OUT_OF_STREAMS` The number of streams created on a single HTTP/2 session reached the maximum limit. -### ERR_HTTP2_PAYLOAD_FORBIDDEN +### `ERR_HTTP2_PAYLOAD_FORBIDDEN` A message payload was specified for an HTTP response code for which a payload is forbidden. -### ERR_HTTP2_PING_CANCEL +### `ERR_HTTP2_PING_CANCEL` An HTTP/2 ping was canceled. -### ERR_HTTP2_PING_LENGTH +### `ERR_HTTP2_PING_LENGTH` HTTP/2 ping payloads must be exactly 8 bytes in length. -### ERR_HTTP2_PSEUDOHEADER_NOT_ALLOWED +### `ERR_HTTP2_PSEUDOHEADER_NOT_ALLOWED` An HTTP/2 pseudo-header has been used inappropriately. Pseudo-headers are header key names that begin with the `:` prefix. -### ERR_HTTP2_PUSH_DISABLED +### `ERR_HTTP2_PUSH_DISABLED` An attempt was made to create a push stream, which had been disabled by the client. -### ERR_HTTP2_SEND_FILE +### `ERR_HTTP2_SEND_FILE` An attempt was made to use the `Http2Stream.prototype.responseWithFile()` API to send a directory. -### ERR_HTTP2_SEND_FILE_NOSEEK +### `ERR_HTTP2_SEND_FILE_NOSEEK` An attempt was made to use the `Http2Stream.prototype.responseWithFile()` API to send something other than a regular file, but `offset` or `length` options were provided. -### ERR_HTTP2_SESSION_ERROR +### `ERR_HTTP2_SESSION_ERROR` The `Http2Session` closed with a non-zero error code. -### ERR_HTTP2_SETTINGS_CANCEL +### `ERR_HTTP2_SETTINGS_CANCEL` The `Http2Session` settings canceled. -### ERR_HTTP2_SOCKET_BOUND +### `ERR_HTTP2_SOCKET_BOUND` An attempt was made to connect a `Http2Session` object to a `net.Socket` or `tls.TLSSocket` that had already been bound to another `Http2Session` object. -### ERR_HTTP2_SOCKET_UNBOUND +### `ERR_HTTP2_SOCKET_UNBOUND` An attempt was made to use the `socket` property of an `Http2Session` that has already been closed. -### ERR_HTTP2_STATUS_101 +### `ERR_HTTP2_STATUS_101` Use of the `101` Informational status code is forbidden in HTTP/2. -### ERR_HTTP2_STATUS_INVALID +### `ERR_HTTP2_STATUS_INVALID` An invalid HTTP status code has been specified. Status codes must be an integer between `100` and `599` (inclusive). -### ERR_HTTP2_STREAM_CANCEL +### `ERR_HTTP2_STREAM_CANCEL` An `Http2Stream` was destroyed before any data was transmitted to the connected peer. -### ERR_HTTP2_STREAM_ERROR +### `ERR_HTTP2_STREAM_ERROR` A non-zero error code was been specified in an `RST_STREAM` frame. -### ERR_HTTP2_STREAM_SELF_DEPENDENCY +### `ERR_HTTP2_STREAM_SELF_DEPENDENCY` When setting the priority for an HTTP/2 stream, the stream may be marked as a dependency for a parent stream. This error code is used when an attempt is made to mark a stream and dependent of itself. -### ERR_HTTP2_TRAILERS_ALREADY_SENT +### `ERR_HTTP2_TRAILERS_ALREADY_SENT` Trailing headers have already been sent on the `Http2Stream`. -### ERR_HTTP2_TRAILERS_NOT_READY +### `ERR_HTTP2_TRAILERS_NOT_READY` The `http2stream.sendTrailers()` method cannot be called until after the `'wantTrailers'` event is emitted on an `Http2Stream` object. The @@ -1154,25 +1154,25 @@ The `http2stream.sendTrailers()` method cannot be called until after the is set for the `Http2Stream`. -### ERR_HTTP2_UNSUPPORTED_PROTOCOL +### `ERR_HTTP2_UNSUPPORTED_PROTOCOL` `http2.connect()` was passed a URL that uses any protocol other than `http:` or `https:`. -### ERR_INTERNAL_ASSERTION +### `ERR_INTERNAL_ASSERTION` There was a bug in Node.js or incorrect usage of Node.js internals. To fix the error, open an issue at https://github.com/nodejs/node/issues. -### ERR_INCOMPATIBLE_OPTION_PAIR +### `ERR_INCOMPATIBLE_OPTION_PAIR` An option pair is incompatible with each other and can not be used at the same time. -### ERR_INPUT_TYPE_NOT_ALLOWED +### `ERR_INPUT_TYPE_NOT_ALLOWED` > Stability: 1 - Experimental @@ -1180,99 +1180,99 @@ The `--input-type` flag was used to attempt to execute a file. This flag can only be used with input via `--eval`, `--print` or `STDIN`. -### ERR_INSPECTOR_ALREADY_CONNECTED +### `ERR_INSPECTOR_ALREADY_CONNECTED` While using the `inspector` module, an attempt was made to connect when the inspector was already connected. -### ERR_INSPECTOR_CLOSED +### `ERR_INSPECTOR_CLOSED` While using the `inspector` module, an attempt was made to use the inspector after the session had already closed. -### ERR_INSPECTOR_COMMAND +### `ERR_INSPECTOR_COMMAND` An error occurred while issuing a command via the `inspector` module. -### ERR_INSPECTOR_NOT_ACTIVE +### `ERR_INSPECTOR_NOT_ACTIVE` The `inspector` is not active when `inspector.waitForDebugger()` is called. -### ERR_INSPECTOR_NOT_AVAILABLE +### `ERR_INSPECTOR_NOT_AVAILABLE` The `inspector` module is not available for use. -### ERR_INSPECTOR_NOT_CONNECTED +### `ERR_INSPECTOR_NOT_CONNECTED` While using the `inspector` module, an attempt was made to use the inspector before it was connected. -### ERR_INSPECTOR_NOT_WORKER +### `ERR_INSPECTOR_NOT_WORKER` An API was called on the main thread that can only be used from the worker thread. -### ERR_INVALID_ADDRESS_FAMILY +### `ERR_INVALID_ADDRESS_FAMILY` The provided address family is not understood by the Node.js API. -### ERR_INVALID_ARG_TYPE +### `ERR_INVALID_ARG_TYPE` An argument of the wrong type was passed to a Node.js API. -### ERR_INVALID_ARG_VALUE +### `ERR_INVALID_ARG_VALUE` An invalid or unsupported value was passed for a given argument. -### ERR_INVALID_ASYNC_ID +### `ERR_INVALID_ASYNC_ID` An invalid `asyncId` or `triggerAsyncId` was passed using `AsyncHooks`. An id less than -1 should never happen. -### ERR_INVALID_BUFFER_SIZE +### `ERR_INVALID_BUFFER_SIZE` A swap was performed on a `Buffer` but its size was not compatible with the operation. -### ERR_INVALID_CALLBACK +### `ERR_INVALID_CALLBACK` A callback function was required but was not been provided to a Node.js API. -### ERR_INVALID_CHAR +### `ERR_INVALID_CHAR` Invalid characters were detected in headers. -### ERR_INVALID_CURSOR_POS +### `ERR_INVALID_CURSOR_POS` A cursor on a given stream cannot be moved to a specified row without a specified column. -### ERR_INVALID_FD +### `ERR_INVALID_FD` A file descriptor ('fd') was not valid (e.g. it was a negative value). -### ERR_INVALID_FD_TYPE +### `ERR_INVALID_FD_TYPE` A file descriptor ('fd') type was not valid. -### ERR_INVALID_FILE_URL_HOST +### `ERR_INVALID_FILE_URL_HOST` A Node.js API that consumes `file:` URLs (such as certain functions in the [`fs`][] module) encountered a file URL with an incompatible host. This @@ -1280,94 +1280,94 @@ situation can only occur on Unix-like systems where only `localhost` or an empty host is supported. -### ERR_INVALID_FILE_URL_PATH +### `ERR_INVALID_FILE_URL_PATH` A Node.js API that consumes `file:` URLs (such as certain functions in the [`fs`][] module) encountered a file URL with an incompatible path. The exact semantics for determining whether a path can be used is platform-dependent. -### ERR_INVALID_HANDLE_TYPE +### `ERR_INVALID_HANDLE_TYPE` An attempt was made to send an unsupported "handle" over an IPC communication channel to a child process. See [`subprocess.send()`][] and [`process.send()`][] for more information. -### ERR_INVALID_HTTP_TOKEN +### `ERR_INVALID_HTTP_TOKEN` An invalid HTTP token was supplied. -### ERR_INVALID_IP_ADDRESS +### `ERR_INVALID_IP_ADDRESS` An IP address is not valid. -### ERR_INVALID_OPT_VALUE +### `ERR_INVALID_OPT_VALUE` An invalid or unexpected value was passed in an options object. -### ERR_INVALID_OPT_VALUE_ENCODING +### `ERR_INVALID_OPT_VALUE_ENCODING` An invalid or unknown file encoding was passed. -### ERR_INVALID_PACKAGE_CONFIG +### `ERR_INVALID_PACKAGE_CONFIG` An invalid `package.json` file was found which failed parsing. -### ERR_INVALID_PERFORMANCE_MARK +### `ERR_INVALID_PERFORMANCE_MARK` While using the Performance Timing API (`perf_hooks`), a performance mark is invalid. -### ERR_INVALID_PROTOCOL +### `ERR_INVALID_PROTOCOL` An invalid `options.protocol` was passed to `http.request()`. -### ERR_INVALID_REPL_EVAL_CONFIG +### `ERR_INVALID_REPL_EVAL_CONFIG` Both `breakEvalOnSigint` and `eval` options were set in the [`REPL`][] config, which is not supported. -### ERR_INVALID_REPL_INPUT +### `ERR_INVALID_REPL_INPUT` The input may not be used in the [`REPL`][]. All prohibited inputs are documented in the [`REPL`][]'s documentation. -### ERR_INVALID_RETURN_PROPERTY +### `ERR_INVALID_RETURN_PROPERTY` Thrown in case a function option does not provide a valid value for one of its returned object properties on execution. -### ERR_INVALID_RETURN_PROPERTY_VALUE +### `ERR_INVALID_RETURN_PROPERTY_VALUE` Thrown in case a function option does not provide an expected value type for one of its returned object properties on execution. -### ERR_INVALID_RETURN_VALUE +### `ERR_INVALID_RETURN_VALUE` Thrown in case a function option does not return an expected value type on execution, such as when a function is expected to return a promise. -### ERR_INVALID_SYNC_FORK_INPUT +### `ERR_INVALID_SYNC_FORK_INPUT` A `Buffer`, `TypedArray`, `DataView` or `string` was provided as stdio input to an asynchronous fork. See the documentation for the [`child_process`][] module for more information. -### ERR_INVALID_THIS +### `ERR_INVALID_THIS` A Node.js API function was called with an incompatible `this` value. @@ -1380,12 +1380,12 @@ urlSearchParams.has.call(buf, 'foo'); ``` -### ERR_INVALID_TRANSFER_OBJECT +### `ERR_INVALID_TRANSFER_OBJECT` An invalid transfer object was passed to `postMessage()`. -### ERR_INVALID_TUPLE +### `ERR_INVALID_TUPLE` An element in the `iterable` provided to the [WHATWG][WHATWG URL API] [`URLSearchParams` constructor][`new URLSearchParams(iterable)`] did not @@ -1393,12 +1393,12 @@ represent a `[name, value]` tuple – that is, if an element is not iterable, or does not consist of exactly two elements. -### ERR_INVALID_URI +### `ERR_INVALID_URI` An invalid URI was passed. -### ERR_INVALID_URL +### `ERR_INVALID_URL` An invalid URL was passed to the [WHATWG][WHATWG URL API] [`URL` constructor][`new URL(input)`] to be parsed. The thrown error object @@ -1406,7 +1406,7 @@ typically has an additional property `'input'` that contains the URL that failed to parse. -### ERR_INVALID_URL_SCHEME +### `ERR_INVALID_URL_SCHEME` An attempt was made to use a URL of an incompatible scheme (protocol) for a specific purpose. It is only used in the [WHATWG URL API][] support in the @@ -1414,47 +1414,47 @@ specific purpose. It is only used in the [WHATWG URL API][] support in the in other Node.js APIs as well in the future. -### ERR_IPC_CHANNEL_CLOSED +### `ERR_IPC_CHANNEL_CLOSED` An attempt was made to use an IPC communication channel that was already closed. -### ERR_IPC_DISCONNECTED +### `ERR_IPC_DISCONNECTED` An attempt was made to disconnect an IPC communication channel that was already disconnected. See the documentation for the [`child_process`][] module for more information. -### ERR_IPC_ONE_PIPE +### `ERR_IPC_ONE_PIPE` An attempt was made to create a child Node.js process using more than one IPC communication channel. See the documentation for the [`child_process`][] module for more information. -### ERR_IPC_SYNC_FORK +### `ERR_IPC_SYNC_FORK` An attempt was made to open an IPC communication channel with a synchronously forked Node.js process. See the documentation for the [`child_process`][] module for more information. -### ERR_MANIFEST_ASSERT_INTEGRITY +### `ERR_MANIFEST_ASSERT_INTEGRITY` An attempt was made to load a resource, but the resource did not match the integrity defined by the policy manifest. See the documentation for [policy][] manifests for more information. -### ERR_MANIFEST_DEPENDENCY_MISSING +### `ERR_MANIFEST_DEPENDENCY_MISSING` An attempt was made to load a resource, but the resource was not listed as a dependency from the location that attempted to load it. See the documentation for [policy][] manifests for more information. -### ERR_MANIFEST_INTEGRITY_MISMATCH +### `ERR_MANIFEST_INTEGRITY_MISMATCH` An attempt was made to load a policy manifest, but the manifest had multiple entries for a resource which did not match each other. Update the manifest @@ -1462,43 +1462,43 @@ entries to match in order to resolve this error. See the documentation for [policy][] manifests for more information. -### ERR_MANIFEST_INVALID_RESOURCE_FIELD +### `ERR_MANIFEST_INVALID_RESOURCE_FIELD` A policy manifest resource had an invalid value for one of its fields. Update the manifest entry to match in order to resolve this error. See the documentation for [policy][] manifests for more information. -### ERR_MANIFEST_PARSE_POLICY +### `ERR_MANIFEST_PARSE_POLICY` An attempt was made to load a policy manifest, but the manifest was unable to be parsed. See the documentation for [policy][] manifests for more information. -### ERR_MANIFEST_TDZ +### `ERR_MANIFEST_TDZ` An attempt was made to read from a policy manifest, but the manifest initialization has not yet taken place. This is likely a bug in Node.js. -### ERR_MANIFEST_UNKNOWN_ONERROR +### `ERR_MANIFEST_UNKNOWN_ONERROR` A policy manifest was loaded, but had an unknown value for its "onerror" behavior. See the documentation for [policy][] manifests for more information. -### ERR_MEMORY_ALLOCATION_FAILED +### `ERR_MEMORY_ALLOCATION_FAILED` An attempt was made to allocate memory (usually in the C++ layer) but it failed. -### ERR_METHOD_NOT_IMPLEMENTED +### `ERR_METHOD_NOT_IMPLEMENTED` A method is required but not implemented. -### ERR_MISSING_ARGS +### `ERR_MISSING_ARGS` A required argument of a Node.js API was not passed. This is only used for strict compliance with the API specification (which in some cases may accept @@ -1507,7 +1507,7 @@ strict compliance with the API specification (which in some cases may accept [`ERR_INVALID_ARG_TYPE`][] error code may be used instead. -### ERR_MISSING_DYNAMIC_INSTANTIATE_HOOK +### `ERR_MISSING_DYNAMIC_INSTANTIATE_HOOK` > Stability: 1 - Experimental @@ -1515,32 +1515,32 @@ An [ES Module][] loader hook specified `format: 'dynamic'` but did not provide a `dynamicInstantiate` hook. -### ERR_MISSING_MESSAGE_PORT_IN_TRANSFER_LIST +### `ERR_MISSING_MESSAGE_PORT_IN_TRANSFER_LIST` A `MessagePort` was found in the object passed to a `postMessage()` call, but not provided in the `transferList` for that call. -### ERR_MISSING_PASSPHRASE +### `ERR_MISSING_PASSPHRASE` An attempt was made to read an encrypted key without specifying a passphrase. -### ERR_MISSING_PLATFORM_FOR_WORKER +### `ERR_MISSING_PLATFORM_FOR_WORKER` The V8 platform used by this instance of Node.js does not support creating Workers. This is caused by lack of embedder support for Workers. In particular, this error will not occur with standard builds of Node.js. -### ERR_MODULE_NOT_FOUND +### `ERR_MODULE_NOT_FOUND` > Stability: 1 - Experimental An [ES Module][] could not be resolved. -### ERR_MULTIPLE_CALLBACK +### `ERR_MULTIPLE_CALLBACK` A callback was called more than once. @@ -1549,210 +1549,210 @@ can either be fulfilled or rejected but not both at the same time. The latter would be possible by calling a callback more than once. -### ERR_NAPI_CONS_FUNCTION +### `ERR_NAPI_CONS_FUNCTION` While using `N-API`, a constructor passed was not a function. -### ERR_NAPI_INVALID_DATAVIEW_ARGS +### `ERR_NAPI_INVALID_DATAVIEW_ARGS` While calling `napi_create_dataview()`, a given `offset` was outside the bounds of the dataview or `offset + length` was larger than a length of given `buffer`. -### ERR_NAPI_INVALID_TYPEDARRAY_ALIGNMENT +### `ERR_NAPI_INVALID_TYPEDARRAY_ALIGNMENT` While calling `napi_create_typedarray()`, the provided `offset` was not a multiple of the element size. -### ERR_NAPI_INVALID_TYPEDARRAY_LENGTH +### `ERR_NAPI_INVALID_TYPEDARRAY_LENGTH` While calling `napi_create_typedarray()`, `(length * size_of_element) + byte_offset` was larger than the length of given `buffer`. -### ERR_NAPI_TSFN_CALL_JS +### `ERR_NAPI_TSFN_CALL_JS` An error occurred while invoking the JavaScript portion of the thread-safe function. -### ERR_NAPI_TSFN_GET_UNDEFINED +### `ERR_NAPI_TSFN_GET_UNDEFINED` An error occurred while attempting to retrieve the JavaScript `undefined` value. -### ERR_NAPI_TSFN_START_IDLE_LOOP +### `ERR_NAPI_TSFN_START_IDLE_LOOP` On the main thread, values are removed from the queue associated with the thread-safe function in an idle loop. This error indicates that an error has occurred when attempting to start the loop. -### ERR_NAPI_TSFN_STOP_IDLE_LOOP +### `ERR_NAPI_TSFN_STOP_IDLE_LOOP` Once no more items are left in the queue, the idle loop must be suspended. This error indicates that the idle loop has failed to stop. -### ERR_NO_CRYPTO +### `ERR_NO_CRYPTO` An attempt was made to use crypto features while Node.js was not compiled with OpenSSL crypto support. -### ERR_NO_ICU +### `ERR_NO_ICU` An attempt was made to use features that require [ICU][], but Node.js was not compiled with ICU support. -### ERR_NON_CONTEXT_AWARE_DISABLED +### `ERR_NON_CONTEXT_AWARE_DISABLED` A non-context-aware native addon was loaded in a process that disallows them. -### ERR_OUT_OF_RANGE +### `ERR_OUT_OF_RANGE` A given value is out of the accepted range. -### ERR_REQUIRE_ESM +### `ERR_REQUIRE_ESM` > Stability: 1 - Experimental An attempt was made to `require()` an [ES Module][]. -### ERR_SCRIPT_EXECUTION_INTERRUPTED +### `ERR_SCRIPT_EXECUTION_INTERRUPTED` Script execution was interrupted by `SIGINT` (For example, when Ctrl+C was pressed). -### ERR_SCRIPT_EXECUTION_TIMEOUT +### `ERR_SCRIPT_EXECUTION_TIMEOUT` Script execution timed out, possibly due to bugs in the script being executed. -### ERR_SERVER_ALREADY_LISTEN +### `ERR_SERVER_ALREADY_LISTEN` The [`server.listen()`][] method was called while a `net.Server` was already listening. This applies to all instances of `net.Server`, including HTTP, HTTPS, and HTTP/2 `Server` instances. -### ERR_SERVER_NOT_RUNNING +### `ERR_SERVER_NOT_RUNNING` The [`server.close()`][] method was called when a `net.Server` was not running. This applies to all instances of `net.Server`, including HTTP, HTTPS, and HTTP/2 `Server` instances. -### ERR_SOCKET_ALREADY_BOUND +### `ERR_SOCKET_ALREADY_BOUND` An attempt was made to bind a socket that has already been bound. -### ERR_SOCKET_BAD_BUFFER_SIZE +### `ERR_SOCKET_BAD_BUFFER_SIZE` An invalid (negative) size was passed for either the `recvBufferSize` or `sendBufferSize` options in [`dgram.createSocket()`][]. -### ERR_SOCKET_BAD_PORT +### `ERR_SOCKET_BAD_PORT` An API function expecting a port >= 0 and < 65536 received an invalid value. -### ERR_SOCKET_BAD_TYPE +### `ERR_SOCKET_BAD_TYPE` An API function expecting a socket type (`udp4` or `udp6`) received an invalid value. -### ERR_SOCKET_BUFFER_SIZE +### `ERR_SOCKET_BUFFER_SIZE` While using [`dgram.createSocket()`][], the size of the receive or send `Buffer` could not be determined. -### ERR_SOCKET_CANNOT_SEND +### `ERR_SOCKET_CANNOT_SEND` Data could be sent on a socket. -### ERR_SOCKET_CLOSED +### `ERR_SOCKET_CLOSED` An attempt was made to operate on an already closed socket. -### ERR_SOCKET_DGRAM_IS_CONNECTED +### `ERR_SOCKET_DGRAM_IS_CONNECTED` A [`dgram.connect()`][] call was made on an already connected socket. -### ERR_SOCKET_DGRAM_NOT_CONNECTED +### `ERR_SOCKET_DGRAM_NOT_CONNECTED` A [`dgram.disconnect()`][] or [`dgram.remoteAddress()`][] call was made on a disconnected socket. -### ERR_SOCKET_DGRAM_NOT_RUNNING +### `ERR_SOCKET_DGRAM_NOT_RUNNING` A call was made and the UDP subsystem was not running. -### ERR_SRI_PARSE +### `ERR_SRI_PARSE` A string was provided for a Subresource Integrity check, but was unable to be parsed. Check the format of integrity attributes by looking at the [Subresource Integrity specification][]. -### ERR_STREAM_CANNOT_PIPE +### `ERR_STREAM_CANNOT_PIPE` An attempt was made to call [`stream.pipe()`][] on a [`Writable`][] stream. -### ERR_STREAM_DESTROYED +### `ERR_STREAM_DESTROYED` A stream method was called that cannot complete because the stream was destroyed using `stream.destroy()`. -### ERR_STREAM_ALREADY_FINISHED +### `ERR_STREAM_ALREADY_FINISHED` A stream method was called that cannot complete because the stream was finished. -### ERR_STREAM_NULL_VALUES +### `ERR_STREAM_NULL_VALUES` An attempt was made to call [`stream.write()`][] with a `null` chunk. -### ERR_STREAM_PREMATURE_CLOSE +### `ERR_STREAM_PREMATURE_CLOSE` An error returned by `stream.finished()` and `stream.pipeline()`, when a stream or a pipeline ends non gracefully with no explicit error. -### ERR_STREAM_PUSH_AFTER_EOF +### `ERR_STREAM_PUSH_AFTER_EOF` An attempt was made to call [`stream.push()`][] after a `null`(EOF) had been pushed to the stream. -### ERR_STREAM_UNSHIFT_AFTER_END_EVENT +### `ERR_STREAM_UNSHIFT_AFTER_END_EVENT` An attempt was made to call [`stream.unshift()`][] after the `'end'` event was emitted. -### ERR_STREAM_WRAP +### `ERR_STREAM_WRAP` Prevents an abort if a string decoder was set on the Socket or if the decoder is in `objectMode`. @@ -1765,38 +1765,38 @@ instance.setEncoding('utf8'); ``` -### ERR_STREAM_WRITE_AFTER_END +### `ERR_STREAM_WRITE_AFTER_END` An attempt was made to call [`stream.write()`][] after `stream.end()` has been called. -### ERR_STRING_TOO_LONG +### `ERR_STRING_TOO_LONG` An attempt has been made to create a string longer than the maximum allowed length. -### ERR_SYNTHETIC +### `ERR_SYNTHETIC` An artificial error object used to capture the call stack for diagnostic reports. -### ERR_SYSTEM_ERROR +### `ERR_SYSTEM_ERROR` An unspecified or non-specific system error has occurred within the Node.js process. The error object will have an `err.info` object property with additional details. -### ERR_TLS_CERT_ALTNAME_INVALID +### `ERR_TLS_CERT_ALTNAME_INVALID` While using TLS, the hostname/IP of the peer did not match any of the `subjectAltNames` in its certificate. -### ERR_TLS_DH_PARAM_SIZE +### `ERR_TLS_DH_PARAM_SIZE` While using TLS, the parameter offered for the Diffie-Hellman (`DH`) key-agreement protocol is too small. By default, the key length must be greater @@ -1804,13 +1804,13 @@ than or equal to 1024 bits to avoid vulnerabilities, even though it is strongly recommended to use 2048 bits or larger for stronger security. -### ERR_TLS_HANDSHAKE_TIMEOUT +### `ERR_TLS_HANDSHAKE_TIMEOUT` A TLS/SSL handshake timed out. In this case, the server must also abort the connection. -### ERR_TLS_INVALID_CONTEXT +### `ERR_TLS_INVALID_CONTEXT` @@ -1818,59 +1818,64 @@ added: v13.3.0 The context must be a `SecureContext`. -### ERR_TLS_INVALID_PROTOCOL_METHOD +### `ERR_TLS_INVALID_PROTOCOL_METHOD` The specified `secureProtocol` method is invalid. It is either unknown, or disabled because it is insecure. -### ERR_TLS_INVALID_PROTOCOL_VERSION +### `ERR_TLS_INVALID_PROTOCOL_VERSION` Valid TLS protocol versions are `'TLSv1'`, `'TLSv1.1'`, or `'TLSv1.2'`. -### ERR_TLS_PROTOCOL_VERSION_CONFLICT +### `ERR_TLS_PROTOCOL_VERSION_CONFLICT` Attempting to set a TLS protocol `minVersion` or `maxVersion` conflicts with an attempt to set the `secureProtocol` explicitly. Use one mechanism or the other. -### ERR_TLS_RENEGOTIATION_DISABLED +### `ERR_TLS_RENEGOTIATION_DISABLED` An attempt was made to renegotiate TLS on a socket instance with TLS disabled. -### ERR_TLS_REQUIRED_SERVER_NAME +### `ERR_TLS_REQUIRED_SERVER_NAME` While using TLS, the `server.addContext()` method was called without providing a hostname in the first parameter. -### ERR_TLS_SESSION_ATTACK +### `ERR_TLS_SESSION_ATTACK` An excessive amount of TLS renegotiations is detected, which is a potential vector for denial-of-service attacks. -### ERR_TLS_SNI_FROM_SERVER +### `ERR_TLS_SNI_FROM_SERVER` An attempt was made to issue Server Name Indication from a TLS server-side socket, which is only valid from a client. + +### ERR_TLS_PSK_SET_IDENTIY_HINT_FAILED + +Failed to set PSK identity hint. Hint may be too long. + -### ERR_TRACE_EVENTS_CATEGORY_REQUIRED +### `ERR_TRACE_EVENTS_CATEGORY_REQUIRED` The `trace_events.createTracing()` method requires at least one trace event category. -### ERR_TRACE_EVENTS_UNAVAILABLE +### `ERR_TRACE_EVENTS_UNAVAILABLE` The `trace_events` module could not be loaded because Node.js was compiled with the `--without-v8-platform` flag. -### ERR_TRANSFERRING_EXTERNALIZED_SHAREDARRAYBUFFER +### `ERR_TRANSFERRING_EXTERNALIZED_SHAREDARRAYBUFFER` A `SharedArrayBuffer` whose memory is not managed by the JavaScript engine or by Node.js was encountered during serialization. Such a `SharedArrayBuffer` @@ -1880,22 +1885,22 @@ This can only happen when native addons create `SharedArrayBuffer`s in "externalized" mode, or put existing `SharedArrayBuffer` into externalized mode. -### ERR_TRANSFORM_ALREADY_TRANSFORMING +### `ERR_TRANSFORM_ALREADY_TRANSFORMING` A `Transform` stream finished while it was still transforming. -### ERR_TRANSFORM_WITH_LENGTH_0 +### `ERR_TRANSFORM_WITH_LENGTH_0` A `Transform` stream finished with data still in the write buffer. -### ERR_TTY_INIT_FAILED +### `ERR_TTY_INIT_FAILED` The initialization of a TTY failed due to a system error. -### ERR_UNCAUGHT_EXCEPTION_CAPTURE_ALREADY_SET +### `ERR_UNCAUGHT_EXCEPTION_CAPTURE_ALREADY_SET` [`process.setUncaughtExceptionCaptureCallback()`][] was called twice, without first resetting the callback to `null`. @@ -1904,35 +1909,35 @@ This error is designed to prevent accidentally overwriting a callback registered from another module. -### ERR_UNESCAPED_CHARACTERS +### `ERR_UNESCAPED_CHARACTERS` A string that contained unescaped characters was received. -### ERR_UNHANDLED_ERROR +### `ERR_UNHANDLED_ERROR` An unhandled error occurred (for instance, when an `'error'` event is emitted by an [`EventEmitter`][] but an `'error'` handler is not registered). -### ERR_UNKNOWN_BUILTIN_MODULE +### `ERR_UNKNOWN_BUILTIN_MODULE` Used to identify a specific kind of internal Node.js error that should not typically be triggered by user code. Instances of this error point to an internal bug within the Node.js binary itself. -### ERR_UNKNOWN_CREDENTIAL +### `ERR_UNKNOWN_CREDENTIAL` A Unix group or user identifier that does not exist was passed. -### ERR_UNKNOWN_ENCODING +### `ERR_UNKNOWN_ENCODING` An invalid or unknown encoding option was passed to an API. -### ERR_UNKNOWN_FILE_EXTENSION +### `ERR_UNKNOWN_FILE_EXTENSION` > Stability: 1 - Experimental @@ -1940,36 +1945,41 @@ An attempt was made to load a module with an unknown or unsupported file extension. -### ERR_UNKNOWN_MODULE_FORMAT +### `ERR_UNKNOWN_MODULE_FORMAT` > Stability: 1 - Experimental An attempt was made to load a module with an unknown or unsupported format. -### ERR_UNKNOWN_SIGNAL +### `ERR_UNKNOWN_SIGNAL` An invalid or unknown process signal was passed to an API expecting a valid signal (such as [`subprocess.kill()`][]). + +### `ERR_UNSUPPORTED_ESM_URL_SCHEME` + +`import` with URL schemes other than `file` and `data` is unsupported. + -### ERR_V8BREAKITERATOR +### `ERR_V8BREAKITERATOR` The V8 `BreakIterator` API was used but the full ICU data set is not installed. -### ERR_VALID_PERFORMANCE_ENTRY_TYPE +### `ERR_VALID_PERFORMANCE_ENTRY_TYPE` While using the Performance Timing API (`perf_hooks`), no valid performance entry types were found. -### ERR_VM_DYNAMIC_IMPORT_CALLBACK_MISSING +### `ERR_VM_DYNAMIC_IMPORT_CALLBACK_MISSING` A dynamic import callback was not specified. -### ERR_VM_MODULE_ALREADY_LINKED +### `ERR_VM_MODULE_ALREADY_LINKED` The module attempted to be linked is not eligible for linking, because of one of the following reasons: @@ -1979,72 +1989,72 @@ the following reasons: * Linking has failed for this module (`linkingStatus` is `'errored'`) -### ERR_VM_MODULE_DIFFERENT_CONTEXT +### `ERR_VM_MODULE_DIFFERENT_CONTEXT` The module being returned from the linker function is from a different context than the parent module. Linked modules must share the same context. -### ERR_VM_MODULE_LINKING_ERRORED +### `ERR_VM_MODULE_LINKING_ERRORED` The linker function returned a module for which linking has failed. -### ERR_VM_MODULE_NOT_MODULE +### `ERR_VM_MODULE_NOT_MODULE` The fulfilled value of a linking promise is not a `vm.Module` object. -### ERR_VM_MODULE_STATUS +### `ERR_VM_MODULE_STATUS` The current module's status does not allow for this operation. The specific meaning of the error depends on the specific function. -### ERR_WASI_ALREADY_STARTED +### `ERR_WASI_ALREADY_STARTED` The WASI instance has already started. -### ERR_WORKER_INVALID_EXEC_ARGV +### `ERR_WORKER_INVALID_EXEC_ARGV` The `execArgv` option passed to the `Worker` constructor contains invalid flags. -### ERR_WORKER_OUT_OF_MEMORY +### `ERR_WORKER_OUT_OF_MEMORY` The `Worker` instance terminated because it reached its memory limit. -### ERR_WORKER_PATH +### `ERR_WORKER_PATH` The path for the main script of a worker is neither an absolute path nor a relative path starting with `./` or `../`. -### ERR_WORKER_UNSERIALIZABLE_ERROR +### `ERR_WORKER_UNSERIALIZABLE_ERROR` All attempts at serializing an uncaught exception from a worker thread failed. -### ERR_WORKER_UNSUPPORTED_EXTENSION +### `ERR_WORKER_UNSUPPORTED_EXTENSION` The pathname used for the main script of a worker has an unknown file extension. -### ERR_WORKER_UNSUPPORTED_OPERATION +### `ERR_WORKER_UNSUPPORTED_OPERATION` The requested functionality is not supported in worker threads. -### ERR_ZLIB_INITIALIZATION_FAILED +### `ERR_ZLIB_INITIALIZATION_FAILED` Creation of a [`zlib`][] object failed due to incorrect configuration. -### HPE_HEADER_OVERFLOW +### `HPE_HEADER_OVERFLOW` @@ -271,7 +283,7 @@ myEmitter.emit('event'); // A ``` -### Event: 'removeListener' +### Event: `'removeListener'` @@ -348,7 +360,20 @@ the event emitter instance, the event’s name and the number of attached listeners, respectively. Its `name` property is set to `'MaxListenersExceededWarning'`. -### emitter.addListener(eventName, listener) +### `EventEmitter.errorMonitor` + + +This symbol shall be used to install a listener for only monitoring `'error'` +events. Listeners installed using this symbol are called before the regular +`'error'` listeners are called. + +Installing a listener using this symbol does not change the behavior once an +`'error'` event is emitted, therefore the process will still crash if no +regular `'error'` listener is installed. + +### `emitter.addListener(eventName, listener)` @@ -358,7 +383,7 @@ added: v0.1.26 Alias for `emitter.on(eventName, listener)`. -### emitter.emit(eventName\[, ...args\]) +### `emitter.emit(eventName[, ...args])` @@ -406,7 +431,7 @@ myEmitter.emit('event', 1, 2, 3, 4, 5); // event with parameters 1, 2, 3, 4, 5 in third listener ``` -### emitter.eventNames() +### `emitter.eventNames()` @@ -429,7 +454,7 @@ console.log(myEE.eventNames()); // Prints: [ 'foo', 'bar', Symbol(symbol) ] ``` -### emitter.getMaxListeners() +### `emitter.getMaxListeners()` @@ -440,7 +465,7 @@ Returns the current max listener value for the `EventEmitter` which is either set by [`emitter.setMaxListeners(n)`][] or defaults to [`EventEmitter.defaultMaxListeners`][]. -### emitter.listenerCount(eventName) +### `emitter.listenerCount(eventName)` @@ -450,7 +475,7 @@ added: v3.2.0 Returns the number of listeners listening to the event named `eventName`. -### emitter.listeners(eventName) +### `emitter.listeners(eventName)` @@ -484,7 +509,7 @@ added: v10.0.0 Alias for [`emitter.removeListener()`][]. -### emitter.on(eventName, listener) +### `emitter.on(eventName, listener)` @@ -521,7 +546,7 @@ myEE.emit('foo'); // a ``` -### emitter.once(eventName, listener) +### `emitter.once(eventName, listener)` @@ -555,7 +580,7 @@ myEE.emit('foo'); // a ``` -### emitter.prependListener(eventName, listener) +### `emitter.prependListener(eventName, listener)` @@ -578,7 +603,7 @@ server.prependListener('connection', (stream) => { Returns a reference to the `EventEmitter`, so that calls can be chained. -### emitter.prependOnceListener(eventName, listener) +### `emitter.prependOnceListener(eventName, listener)` @@ -599,7 +624,7 @@ server.prependOnceListener('connection', (stream) => { Returns a reference to the `EventEmitter`, so that calls can be chained. -### emitter.removeAllListeners(\[eventName\]) +### `emitter.removeAllListeners([eventName])` @@ -615,7 +640,7 @@ component or module (e.g. sockets or file streams). Returns a reference to the `EventEmitter`, so that calls can be chained. -### emitter.removeListener(eventName, listener) +### `emitter.removeListener(eventName, listener)` @@ -705,7 +730,7 @@ ee.emit('ping'); Returns a reference to the `EventEmitter`, so that calls can be chained. -### emitter.setMaxListeners(n) +### `emitter.setMaxListeners(n)` @@ -722,7 +747,7 @@ to indicate an unlimited number of listeners. Returns a reference to the `EventEmitter`, so that calls can be chained. -### emitter.rawListeners(eventName) +### `emitter.rawListeners(eventName)` @@ -757,7 +782,7 @@ newListeners[0](); emitter.emit('log'); ``` -### emitter\[Symbol.for('nodejs.rejection')\](err, eventName\[, ...args\]) +### `emitter[Symbol.for('nodejs.rejection')](err, eventName[, ...args])` @@ -793,7 +818,7 @@ class MyClass extends EventEmitter { } ``` -## events.once(emitter, name) +## `events.once(emitter, name)` @@ -839,7 +864,7 @@ async function run() { run(); ``` -## events.captureRejections +## `events.captureRejections` @@ -850,7 +875,7 @@ Value: {boolean} Change the default `captureRejections` option on all new `EventEmitter` objects. -## events.captureRejectionSymbol +## `events.captureRejectionSymbol` @@ -861,6 +886,41 @@ Value: `Symbol.for('nodejs.rejection')` See how to write a custom [rejection handler][rejection]. +## `events.on(emitter, eventName)` + + +* `emitter` {EventEmitter} +* `eventName` {string|symbol} The name of the event being listened for +* Returns: {AsyncIterator} that iterates `eventName` events emitted by the `emitter` + +```js +const { on, EventEmitter } = require('events'); + +(async () => { + const ee = new EventEmitter(); + + // Emit later on + process.nextTick(() => { + ee.emit('foo', 'bar'); + ee.emit('foo', 42); + }); + + for await (const event of on(ee, 'foo')) { + // The execution of this inner block is synchronous and it + // processes one event at a time (even with await). Do not use + // if concurrent execution is required. + console.log(event); // prints ['bar'] [42] + } +})(); +``` + +Returns an `AsyncIterator` that iterates `eventName` events. It will throw +if the `EventEmitter` emits `'error'`. It removes all listeners when +exiting the loop. The `value` returned by each iteration is an array +composed of the emitted event arguments. + [WHATWG-EventTarget]: https://dom.spec.whatwg.org/#interface-eventtarget [`--trace-warnings`]: cli.html#cli_trace_warnings [`EventEmitter.defaultMaxListeners`]: #events_eventemitter_defaultmaxlisteners diff --git a/doc/api/fs.md b/doc/api/fs.md index a6372f3b115337..eb92c7f0b3b2e4 100644 --- a/doc/api/fs.md +++ b/doc/api/fs.md @@ -284,7 +284,7 @@ synchronous use libuv's threadpool, which can have surprising and negative performance implications for some applications. See the [`UV_THREADPOOL_SIZE`][] documentation for more information. -## Class fs.Dir +## Class `fs.Dir` @@ -306,7 +306,7 @@ async function print(path) { print('./').catch(console.error); ``` -### dir.close() +### `dir.close()` @@ -319,7 +319,7 @@ Subsequent reads will result in errors. A `Promise` is returned that will be resolved after the resource has been closed. -### dir.close(callback) +### `dir.close(callback)` @@ -332,7 +332,7 @@ Subsequent reads will result in errors. The `callback` will be called after the resource handle has been closed. -### dir.closeSync() +### `dir.closeSync()` @@ -340,7 +340,7 @@ added: v12.12.0 Synchronously close the directory's underlying resource handle. Subsequent reads will result in errors. -### dir.path +### `dir.path` @@ -350,7 +350,7 @@ added: v12.12.0 The read-only path of this directory as was provided to [`fs.opendir()`][], [`fs.opendirSync()`][], or [`fsPromises.opendir()`][]. -### dir.read() +### `dir.read()` @@ -368,7 +368,7 @@ provided by the operating system's underlying directory mechanisms. Entries added or removed while iterating over the directory may or may not be included in the iteration results. -### dir.read(callback) +### `dir.read(callback)` @@ -388,7 +388,7 @@ provided by the operating system's underlying directory mechanisms. Entries added or removed while iterating over the directory may or may not be included in the iteration results. -### dir.readSync() +### `dir.readSync()` @@ -405,7 +405,7 @@ provided by the operating system's underlying directory mechanisms. Entries added or removed while iterating over the directory may or may not be included in the iteration results. -### dir\[Symbol.asyncIterator\]() +### `dir[Symbol.asyncIterator]()` @@ -425,7 +425,7 @@ provided by the operating system's underlying directory mechanisms. Entries added or removed while iterating over the directory may or may not be included in the iteration results. -## Class: fs.Dirent +## Class: `fs.Dirent` @@ -437,7 +437,7 @@ Additionally, when [`fs.readdir()`][] or [`fs.readdirSync()`][] is called with the `withFileTypes` option set to `true`, the resulting array is filled with `fs.Dirent` objects, rather than strings or `Buffers`. -### dirent.isBlockDevice() +### `dirent.isBlockDevice()` @@ -446,7 +446,7 @@ added: v10.10.0 Returns `true` if the `fs.Dirent` object describes a block device. -### dirent.isCharacterDevice() +### `dirent.isCharacterDevice()` @@ -455,7 +455,7 @@ added: v10.10.0 Returns `true` if the `fs.Dirent` object describes a character device. -### dirent.isDirectory() +### `dirent.isDirectory()` @@ -465,7 +465,7 @@ added: v10.10.0 Returns `true` if the `fs.Dirent` object describes a file system directory. -### dirent.isFIFO() +### `dirent.isFIFO()` @@ -475,7 +475,7 @@ added: v10.10.0 Returns `true` if the `fs.Dirent` object describes a first-in-first-out (FIFO) pipe. -### dirent.isFile() +### `dirent.isFile()` @@ -484,7 +484,7 @@ added: v10.10.0 Returns `true` if the `fs.Dirent` object describes a regular file. -### dirent.isSocket() +### `dirent.isSocket()` @@ -493,7 +493,7 @@ added: v10.10.0 Returns `true` if the `fs.Dirent` object describes a socket. -### dirent.isSymbolicLink() +### `dirent.isSymbolicLink()` @@ -502,7 +502,7 @@ added: v10.10.0 Returns `true` if the `fs.Dirent` object describes a symbolic link. -### dirent.name +### `dirent.name` @@ -513,7 +513,7 @@ The file name that this `fs.Dirent` object refers to. The type of this value is determined by the `options.encoding` passed to [`fs.readdir()`][] or [`fs.readdirSync()`][]. -## Class: fs.FSWatcher +## Class: `fs.FSWatcher` @@ -526,7 +526,7 @@ object. All `fs.FSWatcher` objects emit a `'change'` event whenever a specific watched file is modified. -### Event: 'change' +### Event: `'change'` @@ -552,7 +552,7 @@ fs.watch('./tmp', { encoding: 'buffer' }, (eventType, filename) => { }); ``` -### Event: 'close' +### Event: `'close'` @@ -560,7 +560,7 @@ added: v10.0.0 Emitted when the watcher stops watching for changes. The closed `fs.FSWatcher` object is no longer usable in the event handler. -### Event: 'error' +### Event: `'error'` @@ -570,7 +570,7 @@ added: v0.5.8 Emitted when an error occurs while watching the file. The errored `fs.FSWatcher` object is no longer usable in the event handler. -### watcher.close() +### `watcher.close()` @@ -578,7 +578,7 @@ added: v0.5.8 Stop watching for changes on the given `fs.FSWatcher`. Once stopped, the `fs.FSWatcher` object is no longer usable. -## Class: fs.ReadStream +## Class: `fs.ReadStream` @@ -588,14 +588,14 @@ added: v0.1.93 A successful call to `fs.createReadStream()` will return a new `fs.ReadStream` object. -### Event: 'close' +### Event: `'close'` Emitted when the `fs.ReadStream`'s underlying file descriptor has been closed. -### Event: 'open' +### Event: `'open'` @@ -604,7 +604,7 @@ added: v0.1.93 Emitted when the `fs.ReadStream`'s file descriptor has been opened. -### Event: 'ready' +### Event: `'ready'` @@ -613,7 +613,7 @@ Emitted when the `fs.ReadStream` is ready to be used. Fires immediately after `'open'`. -### readStream.bytesRead +### `readStream.bytesRead` @@ -622,7 +622,7 @@ added: v6.4.0 The number of bytes that have been read so far. -### readStream.path +### `readStream.path` @@ -634,7 +634,7 @@ argument to `fs.createReadStream()`. If `path` is passed as a string, then `readStream.path` will be a string. If `path` is passed as a `Buffer`, then `readStream.path` will be a `Buffer`. -### readStream.pending +### `readStream.pending` @@ -644,7 +644,7 @@ added: v11.2.0 This property is `true` if the underlying file has not been opened yet, i.e. before the `'ready'` event is emitted. -## Class: fs.Stats +## Class: `fs.Stats` @@ -720,7 +720,7 @@ added: v0.1.10 Returns `true` if the `fs.Stats` object describes a block device. -### stats.isCharacterDevice() +### `stats.isCharacterDevice()` @@ -729,7 +729,7 @@ added: v0.1.10 Returns `true` if the `fs.Stats` object describes a character device. -### stats.isDirectory() +### `stats.isDirectory()` @@ -738,7 +738,7 @@ added: v0.1.10 Returns `true` if the `fs.Stats` object describes a file system directory. -### stats.isFIFO() +### `stats.isFIFO()` @@ -748,7 +748,7 @@ added: v0.1.10 Returns `true` if the `fs.Stats` object describes a first-in-first-out (FIFO) pipe. -### stats.isFile() +### `stats.isFile()` @@ -757,7 +757,7 @@ added: v0.1.10 Returns `true` if the `fs.Stats` object describes a regular file. -### stats.isSocket() +### `stats.isSocket()` @@ -766,7 +766,7 @@ added: v0.1.10 Returns `true` if the `fs.Stats` object describes a socket. -### stats.isSymbolicLink() +### `stats.isSymbolicLink()` @@ -777,67 +777,67 @@ Returns `true` if the `fs.Stats` object describes a symbolic link. This method is only valid when using [`fs.lstat()`][]. -### stats.dev +### `stats.dev` * {number|bigint} The numeric identifier of the device containing the file. -### stats.ino +### `stats.ino` * {number|bigint} The file system specific "Inode" number for the file. -### stats.mode +### `stats.mode` * {number|bigint} A bit-field describing the file type and mode. -### stats.nlink +### `stats.nlink` * {number|bigint} The number of hard-links that exist for the file. -### stats.uid +### `stats.uid` * {number|bigint} The numeric user identifier of the user that owns the file (POSIX). -### stats.gid +### `stats.gid` * {number|bigint} The numeric group identifier of the group that owns the file (POSIX). -### stats.rdev +### `stats.rdev` * {number|bigint} A numeric device identifier if the file is considered "special". -### stats.size +### `stats.size` * {number|bigint} The size of the file in bytes. -### stats.blksize +### `stats.blksize` * {number|bigint} The file system block size for i/o operations. -### stats.blocks +### `stats.blocks` * {number|bigint} The number of blocks allocated for this file. -### stats.atimeMs +### `stats.atimeMs` @@ -847,7 +847,7 @@ added: v8.1.0 The timestamp indicating the last time this file was accessed expressed in milliseconds since the POSIX Epoch. -### stats.mtimeMs +### `stats.mtimeMs` @@ -857,7 +857,7 @@ added: v8.1.0 The timestamp indicating the last time this file was modified expressed in milliseconds since the POSIX Epoch. -### stats.ctimeMs +### `stats.ctimeMs` @@ -867,7 +867,7 @@ added: v8.1.0 The timestamp indicating the last time the file status was changed expressed in milliseconds since the POSIX Epoch. -### stats.birthtimeMs +### `stats.birthtimeMs` @@ -877,7 +877,7 @@ added: v8.1.0 The timestamp indicating the creation time of this file expressed in milliseconds since the POSIX Epoch. -### stats.atimeNs +### `stats.atimeNs` @@ -889,7 +889,7 @@ the object. The timestamp indicating the last time this file was accessed expressed in nanoseconds since the POSIX Epoch. -### stats.mtimeNs +### `stats.mtimeNs` @@ -901,7 +901,7 @@ the object. The timestamp indicating the last time this file was modified expressed in nanoseconds since the POSIX Epoch. -### stats.ctimeNs +### `stats.ctimeNs` @@ -913,7 +913,7 @@ the object. The timestamp indicating the last time the file status was changed expressed in nanoseconds since the POSIX Epoch. -### stats.birthtimeNs +### `stats.birthtimeNs` @@ -925,7 +925,7 @@ the object. The timestamp indicating the creation time of this file expressed in nanoseconds since the POSIX Epoch. -### stats.atime +### `stats.atime` @@ -934,7 +934,7 @@ added: v0.11.13 The timestamp indicating the last time this file was accessed. -### stats.mtime +### `stats.mtime` @@ -943,7 +943,7 @@ added: v0.11.13 The timestamp indicating the last time this file was modified. -### stats.ctime +### `stats.ctime` @@ -952,7 +952,7 @@ added: v0.11.13 The timestamp indicating the last time the file status was changed. -### stats.birthtime +### `stats.birthtime` @@ -1001,21 +1001,21 @@ The times in the stat object have the following semantics: Prior to Node.js 0.12, the `ctime` held the `birthtime` on Windows systems. As of 0.12, `ctime` is not "creation time", and on Unix systems, it never was. -## Class: fs.WriteStream +## Class: `fs.WriteStream` * Extends {stream.Writable} -### Event: 'close' +### Event: `'close'` Emitted when the `WriteStream`'s underlying file descriptor has been closed. -### Event: 'open' +### Event: `'open'` @@ -1024,7 +1024,7 @@ added: v0.1.93 Emitted when the `WriteStream`'s file is opened. -### Event: 'ready' +### Event: `'ready'` @@ -1033,7 +1033,7 @@ Emitted when the `fs.WriteStream` is ready to be used. Fires immediately after `'open'`. -### writeStream.bytesWritten +### `writeStream.bytesWritten` @@ -1041,7 +1041,7 @@ added: v0.4.7 The number of bytes written so far. Does not include data that is still queued for writing. -### writeStream.path +### `writeStream.path` @@ -1051,7 +1051,7 @@ argument to [`fs.createWriteStream()`][]. If `path` is passed as a string, then `writeStream.path` will be a string. If `path` is passed as a `Buffer`, then `writeStream.path` will be a `Buffer`. -### writeStream.pending +### `writeStream.pending` @@ -1061,7 +1061,7 @@ added: v11.2.0 This property is `true` if the underlying file has not been opened yet, i.e. before the `'ready'` event is emitted. -## fs.access(path\[, mode\], callback) +## `fs.access(path[, mode], callback)` * `path` {string|Buffer|URL} -* `mode` {integer} +* `mode` {string|integer} * `callback` {Function} * `err` {Error} @@ -1446,7 +1446,7 @@ Caveats: on Windows only the write permission can be changed, and the distinction among the permissions of group, owner or others is not implemented. -## fs.chmodSync(path, mode) +## `fs.chmodSync(path, mode)` * `path` {string|Buffer|URL} -* `mode` {integer} +* `mode` {string|integer} For detailed information, see the documentation of the asynchronous version of this API: [`fs.chmod()`][]. See also: chmod(2). -## fs.chown(path, uid, gid, callback) +## `fs.chown(path, uid, gid, callback)` @@ -1548,7 +1548,7 @@ Synchronous close(2). Returns `undefined`. Calling `fs.closeSync()` on any file descriptor (`fd`) that is currently in use through any other `fs` operation may lead to undefined behavior. -## fs.constants +## `fs.constants` * {Object} @@ -1556,7 +1556,7 @@ Returns an object containing commonly used constants for file system operations. The specific constants currently defined are described in [FS Constants][]. -## fs.copyFile(src, dest\[, flags\], callback) +## `fs.copyFile(src, dest[, flags], callback)` @@ -1606,7 +1606,7 @@ const { COPYFILE_EXCL } = fs.constants; fs.copyFile('source.txt', 'destination.txt', COPYFILE_EXCL, callback); ``` -## fs.copyFileSync(src, dest\[, flags\]) +## `fs.copyFileSync(src, dest[, flags])` @@ -1652,7 +1652,7 @@ const { COPYFILE_EXCL } = fs.constants; fs.copyFileSync('source.txt', 'destination.txt', COPYFILE_EXCL); ``` -## fs.createReadStream(path\[, options\]) +## `fs.createReadStream(path[, options])` * `path` {string|Buffer|URL} @@ -1688,7 +1692,8 @@ changes: * `start` {integer} * `end` {integer} **Default:** `Infinity` * `highWaterMark` {integer} **Default:** `64 * 1024` -* Returns: {fs.ReadStream} + * `fs` {Object|null} **Default:** `null` +* Returns: {fs.ReadStream} See [Readable Stream][]. Unlike the 16 kb default `highWaterMark` for a readable stream, the stream returned by this method has a default `highWaterMark` of 64 kb. @@ -1715,6 +1720,10 @@ By default, the stream will not emit a `'close'` event after it has been destroyed. This is the opposite of the default for other `Readable` streams. Set the `emitClose` option to `true` to change this behavior. +By providing the `fs` option it is possible to override the corresponding `fs` +implementations for `open`, `read` and `close`. When providing the `fs` option, +you must override `open`, `close` and `read`. + ```js const fs = require('fs'); // Create a stream from some character device. @@ -1748,7 +1757,7 @@ fs.createReadStream('sample.txt', { start: 90, end: 99 }); If `options` is a string, then it specifies the encoding. -## fs.createWriteStream(path\[, options\]) +## `fs.createWriteStream(path[, options])` * `path` {string|Buffer|URL} @@ -1780,7 +1793,8 @@ changes: * `autoClose` {boolean} **Default:** `true` * `emitClose` {boolean} **Default:** `false` * `start` {integer} -* Returns: {fs.WriteStream} + * `fs` {Object|null} **Default:** `null` +* Returns: {fs.WriteStream} See [Writable Stream][]. `options` may also include a `start` option to allow writing data at some position past the beginning of the file, allowed values are in the @@ -1799,6 +1813,12 @@ By default, the stream will not emit a `'close'` event after it has been destroyed. This is the opposite of the default for other `Writable` streams. Set the `emitClose` option to `true` to change this behavior. +By providing the `fs` option it is possible to override the corresponding `fs` +implementations for `open`, `write`, `writev` and `close`. Overriding `write()` +without `writev()` can reduce performance as some optimizations (`_writev()`) +will be disabled. When providing the `fs` option, you must override `open`, +`close` and at least one of `write` and `writev`. + Like [`ReadStream`][], if `fd` is specified, [`WriteStream`][] will ignore the `path` argument and will use the specified file descriptor. This means that no `'open'` event will be emitted. `fd` should be blocking; non-blocking `fd`s @@ -1806,7 +1826,7 @@ should be passed to [`net.Socket`][]. If `options` is a string, then it specifies the encoding. -## fs.exists(path, callback) +## `fs.exists(path, callback)` * `fd` {integer} -* `mode` {integer} +* `mode` {string|integer} * `callback` {Function} * `err` {Error} Asynchronous fchmod(2). No arguments other than a possible exception are given to the completion callback. -## fs.fchmodSync(fd, mode) +## `fs.fchmodSync(fd, mode)` * `fd` {integer} -* `mode` {integer} +* `mode` {string|integer} Synchronous fchmod(2). Returns `undefined`. -## fs.fchown(fd, uid, gid, callback) +## `fs.fchown(fd, uid, gid, callback)` @@ -2010,7 +2030,7 @@ added: v0.4.7 Synchronous fchown(2). Returns `undefined`. -## fs.fdatasync(fd, callback) +## `fs.fdatasync(fd, callback)` @@ -2040,7 +2060,7 @@ added: v0.1.96 Synchronous fdatasync(2). Returns `undefined`. -## fs.fstat(fd\[, options\], callback) +## `fs.fstat(fd[, options], callback)` @@ -2118,7 +2138,7 @@ added: v0.1.96 Synchronous fsync(2). Returns `undefined`. -## fs.ftruncate(fd\[, len\], callback) +## `fs.ftruncate(fd[, len], callback)` @@ -2195,7 +2215,7 @@ Returns `undefined`. For detailed information, see the documentation of the asynchronous version of this API: [`fs.ftruncate()`][]. -## fs.futimes(fd, atime, mtime, callback) +## `fs.futimes(fd, atime, mtime, callback)` @@ -2275,7 +2295,7 @@ deprecated: v0.4.7 Synchronous lchmod(2). Returns `undefined`. -## fs.lchown(path, uid, gid, callback) +## `fs.lchown(path, uid, gid, callback)` @@ -2588,7 +2608,7 @@ this API: [`fs.mkdtemp()`][]. The optional `options` argument can be a string specifying an encoding, or an object with an `encoding` property specifying the character encoding to use. -## fs.open(path\[, flags\[, mode\]\], callback) +## `fs.open(path[, flags[, mode]], callback)` @@ -3114,7 +3134,7 @@ On Linux, when Node.js is linked against musl libc, the procfs file system must be mounted on `/proc` in order for this function to work. Glibc does not have this restriction. -## fs.realpathSync(path\[, options\]) +## `fs.realpathSync(path[, options])` @@ -3167,7 +3187,7 @@ On Linux, when Node.js is linked against musl libc, the procfs file system must be mounted on `/proc` in order for this function to work. Glibc does not have this restriction. -## fs.rename(oldPath, newPath, callback) +## `fs.rename(oldPath, newPath, callback)` @@ -3564,7 +3584,7 @@ passed as the first argument. In this case, `fs.ftruncateSync()` is called. Passing a file descriptor is deprecated and may result in an error being thrown in the future. -## fs.unlink(path, callback) +## `fs.unlink(path, callback)` @@ -3636,7 +3656,7 @@ Using [`fs.watch()`][] is more efficient than `fs.watchFile()` and `fs.unwatchFile()`. `fs.watch()` should be used instead of `fs.watchFile()` and `fs.unwatchFile()` when possible. -## fs.utimes(path, atime, mtime, callback) +## `fs.utimes(path, atime, mtime, callback)` @@ -4181,7 +4201,7 @@ On Linux, positional writes don't work when the file is opened in append mode. The kernel ignores the position argument and always appends the data to the end of the file. -## fs.writevSync(fd, buffers\[, position\]) +## `fs.writevSync(fd, buffers[, position])` @@ -4194,13 +4214,13 @@ added: v12.9.0 For detailed information, see the documentation of the asynchronous version of this API: [`fs.writev()`][]. -## fs Promises API +## `fs` Promises API The `fs.promises` API provides an alternative set of asynchronous file system methods that return `Promise` objects rather than using callbacks. The API is accessible via `require('fs').promises`. -### class: FileHandle +### class: `FileHandle` @@ -4225,7 +4245,7 @@ the promise-based API uses the `FileHandle` class in order to help avoid accidental leaking of unclosed file descriptors after a `Promise` is resolved or rejected. -#### filehandle.appendFile(data, options) +#### `filehandle.appendFile(data, options)` @@ -4245,7 +4265,7 @@ If `options` is a string, then it specifies the encoding. The `FileHandle` must have been opened for appending. -#### filehandle.chmod(mode) +#### `filehandle.chmod(mode)` @@ -4256,7 +4276,7 @@ added: v10.0.0 Modifies the permissions on the file. The `Promise` is resolved with no arguments upon success. -#### filehandle.chown(uid, gid) +#### `filehandle.chown(uid, gid)` @@ -4268,7 +4288,7 @@ added: v10.0.0 Changes the ownership of the file then resolves the `Promise` with no arguments upon success. -#### filehandle.close() +#### `filehandle.close()` @@ -4292,7 +4312,7 @@ async function openAndClose() { } ``` -#### filehandle.datasync() +#### `filehandle.datasync()` @@ -4302,14 +4322,14 @@ added: v10.0.0 Asynchronous fdatasync(2). The `Promise` is resolved with no arguments upon success. -#### filehandle.fd +#### `filehandle.fd` * {number} The numeric file descriptor managed by the `FileHandle` object. -#### filehandle.read(buffer, offset, length, position) +#### `filehandle.read(buffer, offset, length, position)` @@ -4337,7 +4357,7 @@ Following successful read, the `Promise` is resolved with an object with a `bytesRead` property specifying the number of bytes read, and a `buffer` property that is a reference to the passed in `buffer` argument. -#### filehandle.readFile(options) +#### `filehandle.readFile(options)` @@ -4367,7 +4387,7 @@ If one or more `filehandle.read()` calls are made on a file handle and then a position till the end of the file. It doesn't always read from the beginning of the file. -#### filehandle.stat(\[options\]) +#### `filehandle.stat([options])` @@ -4394,7 +4414,7 @@ added: v10.0.0 Asynchronous fsync(2). The `Promise` is resolved with no arguments upon success. -#### filehandle.truncate(len) +#### `filehandle.truncate(len)` @@ -4463,7 +4483,7 @@ doTruncate().catch(console.error); The last three bytes are null bytes (`'\0'`), to compensate the over-truncation. -#### filehandle.utimes(atime, mtime) +#### `filehandle.utimes(atime, mtime)` @@ -4478,7 +4498,7 @@ then resolves the `Promise` with no arguments upon success. This function does not work on AIX versions before 7.1, it will resolve the `Promise` with an error using code `UV_ENOSYS`. -#### filehandle.write(buffer\[, offset\[, length\[, position\]\]\]) +#### `filehandle.write(buffer[, offset[, length[, position]]])` @@ -4510,7 +4530,7 @@ On Linux, positional writes do not work when the file is opened in append mode. The kernel ignores the position argument and always appends the data to the end of the file. -#### filehandle.write(string\[, position\[, encoding\]\]) +#### `filehandle.write(string[, position[, encoding]])` @@ -4541,7 +4561,7 @@ On Linux, positional writes do not work when the file is opened in append mode. The kernel ignores the position argument and always appends the data to the end of the file. -#### filehandle.writeFile(data, options) +#### `filehandle.writeFile(data, options)` @@ -4571,7 +4591,7 @@ If one or more `filehandle.write()` calls are made on a file handle and then a current position till the end of the file. It doesn't always write from the beginning of the file. -#### filehandle.writev(buffers\[, position\]) +#### `filehandle.writev(buffers[, position])` @@ -4597,7 +4617,7 @@ On Linux, positional writes don't work when the file is opened in append mode. The kernel ignores the position argument and always appends the data to the end of the file. -### fsPromises.access(path\[, mode\]) +### `fsPromises.access(path[, mode])` @@ -4632,7 +4652,7 @@ condition, since other processes may change the file's state between the two calls. Instead, user code should open/read/write the file directly and handle the error raised if the file is not accessible. -### fsPromises.appendFile(path, data\[, options\]) +### `fsPromises.appendFile(path, data[, options])` @@ -4654,19 +4674,19 @@ If `options` is a string, then it specifies the encoding. The `path` may be specified as a `FileHandle` that has been opened for appending (using `fsPromises.open()`). -### fsPromises.chmod(path, mode) +### `fsPromises.chmod(path, mode)` * `path` {string|Buffer|URL} -* `mode` {integer} +* `mode` {string|integer} * Returns: {Promise} Changes the permissions of a file then resolves the `Promise` with no arguments upon succces. -### fsPromises.chown(path, uid, gid) +### `fsPromises.chown(path, uid, gid)` @@ -4679,7 +4699,7 @@ added: v10.0.0 Changes the ownership of a file then resolves the `Promise` with no arguments upon success. -### fsPromises.copyFile(src, dest\[, flags\]) +### `fsPromises.copyFile(src, dest[, flags])` @@ -4732,7 +4752,7 @@ fsPromises.copyFile('source.txt', 'destination.txt', COPYFILE_EXCL) .catch(() => console.log('The file could not be copied')); ``` -### fsPromises.lchmod(path, mode) +### `fsPromises.lchmod(path, mode)` @@ -4744,7 +4764,7 @@ deprecated: v10.0.0 Changes the permissions on a symbolic link then resolves the `Promise` with no arguments upon success. This method is only implemented on macOS. -### fsPromises.lchown(path, uid, gid) +### `fsPromises.lchown(path, uid, gid)` @@ -4772,7 +4792,7 @@ added: v10.0.0 Asynchronous link(2). The `Promise` is resolved with no arguments upon success. -### fsPromises.lstat(path\[, options\]) +### `fsPromises.lstat(path[, options])` @@ -4799,7 +4819,7 @@ added: v10.0.0 * `path` {string|Buffer|URL} * `options` {Object|integer} * `recursive` {boolean} **Default:** `false` - * `mode` {integer} Not supported on Windows. **Default:** `0o777`. + * `mode` {string|integer} Not supported on Windows. **Default:** `0o777`. * Returns: {Promise} Asynchronously creates a directory then resolves the `Promise` with no @@ -4811,7 +4831,7 @@ property indicating whether parent folders should be created. Calling `fsPromises.mkdir()` when `path` is a directory that exists results in a rejection only when `recursive` is false. -### fsPromises.mkdtemp(prefix\[, options\]) +### `fsPromises.mkdtemp(prefix[, options])` @@ -4842,7 +4862,7 @@ characters directly to the `prefix` string. For instance, given a directory `prefix` must end with a trailing platform-specific path separator (`require('path').sep`). -### fsPromises.open(path, flags\[, mode\]) +### `fsPromises.open(path, flags[, mode])` @@ -4959,7 +4979,7 @@ returned. Any specified `FileHandle` has to support reading. -### fsPromises.readlink(path\[, options\]) +### `fsPromises.readlink(path[, options])` @@ -4977,7 +4997,7 @@ object with an `encoding` property specifying the character encoding to use for the link path returned. If the `encoding` is set to `'buffer'`, the link path returned will be passed as a `Buffer` object. -### fsPromises.realpath(path\[, options\]) +### `fsPromises.realpath(path[, options])` @@ -5002,7 +5022,7 @@ On Linux, when Node.js is linked against musl libc, the procfs file system must be mounted on `/proc` in order for this function to work. Glibc does not have this restriction. -### fsPromises.rename(oldPath, newPath) +### `fsPromises.rename(oldPath, newPath)` @@ -5014,7 +5034,7 @@ added: v10.0.0 Renames `oldPath` to `newPath` and resolves the `Promise` with no arguments upon success. -### fsPromises.rmdir(path\[, options\]) +### `fsPromises.rmdir(path[, options])` @@ -5091,7 +5111,7 @@ The `type` argument is only used on Windows platforms and can be one of `'dir'`, to be absolute. When using `'junction'`, the `target` argument will automatically be normalized to absolute path. -### fsPromises.truncate(path\[, len\]) +### `fsPromises.truncate(path[, len])` @@ -5103,7 +5123,7 @@ added: v10.0.0 Truncates the `path` then resolves the `Promise` with no arguments upon success. The `path` *must* be a string or `Buffer`. -### fsPromises.unlink(path) +### `fsPromises.unlink(path)` @@ -5114,7 +5134,7 @@ added: v10.0.0 Asynchronous unlink(2). The `Promise` is resolved with no arguments upon success. -### fsPromises.utimes(path, atime, mtime) +### `fsPromises.utimes(path, atime, mtime)` @@ -5134,7 +5154,7 @@ The `atime` and `mtime` arguments follow these rules: * If the value can not be converted to a number, or is `NaN`, `Infinity` or `-Infinity`, an `Error` will be thrown. -### fsPromises.writeFile(file, data\[, options\]) +### `fsPromises.writeFile(file, data[, options])` @@ -5520,6 +5540,7 @@ the file contents. [`Number.MAX_SAFE_INTEGER`]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/MAX_SAFE_INTEGER [`ReadDirectoryChangesW`]: https://docs.microsoft.com/en-us/windows/desktop/api/winbase/nf-winbase-readdirectorychangesw [`ReadStream`]: #fs_class_fs_readstream +[Readable Stream]: #stream_class_stream_readable [`URL`]: url.html#url_the_whatwg_url_api [`UV_THREADPOOL_SIZE`]: cli.html#cli_uv_threadpool_size_size [`WriteStream`]: #fs_class_fs_writestream @@ -5577,3 +5598,4 @@ the file contents. [chcp]: https://ss64.com/nt/chcp.html [inode]: https://en.wikipedia.org/wiki/Inode [support of file system `flags`]: #fs_file_system_flags +[Writable Stream]: #stream_class_stream_writable diff --git a/doc/api/globals.md b/doc/api/globals.md index 8b112c467d0acb..7e6129e9038aa2 100644 --- a/doc/api/globals.md +++ b/doc/api/globals.md @@ -17,7 +17,7 @@ The objects listed here are specific to Node.js. There are [built-in objects][] that are part of the JavaScript language itself, which are also globally accessible. -## Class: Buffer +## Class: `Buffer` @@ -28,15 +28,15 @@ added: v0.1.103 Used to handle binary data. See the [buffer section][]. -## \_\_dirname +## `__dirname` This variable may appear to be global but is not. See [`__dirname`][]. -## \_\_filename +## `__filename` This variable may appear to be global but is not. See [`__filename`][]. -## clearImmediate(immediateObject) +## `clearImmediate(immediateObject)` @@ -45,7 +45,7 @@ added: v0.9.1 [`clearImmediate`][] is described in the [timers][] section. -## clearInterval(intervalObject) +## `clearInterval(intervalObject)` @@ -54,7 +54,7 @@ added: v0.0.1 [`clearInterval`][] is described in the [timers][] section. -## clearTimeout(timeoutObject) +## `clearTimeout(timeoutObject)` @@ -63,7 +63,7 @@ added: v0.0.1 [`clearTimeout`][] is described in the [timers][] section. -## console +## `console` @@ -74,11 +74,11 @@ added: v0.1.100 Used to print to stdout and stderr. See the [`console`][] section. -## exports +## `exports` This variable may appear to be global but is not. See [`exports`][]. -## global +## `global` @@ -92,11 +92,11 @@ within the browser `var something` will define a new global variable. In Node.js this is different. The top-level scope is not the global scope; `var something` inside a Node.js module will be local to that module. -## module +## `module` This variable may appear to be global but is not. See [`module`][]. -## process +## `process` @@ -107,7 +107,7 @@ added: v0.1.7 The process object. See the [`process` object][] section. -## queueMicrotask(callback) +## `queueMicrotask(callback)` @@ -146,11 +146,11 @@ DataHandler.prototype.load = async function load(key) { }; ``` -## require() +## `require()` This variable may appear to be global but is not. See [`require()`][]. -## setImmediate(callback\[, ...args\]) +## `setImmediate(callback[, ...args])` @@ -159,7 +159,7 @@ added: v0.9.1 [`setImmediate`][] is described in the [timers][] section. -## setInterval(callback, delay\[, ...args\]) +## `setInterval(callback, delay[, ...args])` @@ -168,7 +168,7 @@ added: v0.0.1 [`setInterval`][] is described in the [timers][] section. -## setTimeout(callback, delay\[, ...args\]) +## `setTimeout(callback, delay[, ...args])` @@ -177,7 +177,7 @@ added: v0.0.1 [`setTimeout`][] is described in the [timers][] section. -## TextDecoder +## `TextDecoder` @@ -186,7 +186,7 @@ added: v11.0.0 The WHATWG `TextDecoder` class. See the [`TextDecoder`][] section. -## TextEncoder +## `TextEncoder` @@ -195,7 +195,7 @@ added: v11.0.0 The WHATWG `TextEncoder` class. See the [`TextEncoder`][] section. -## URL +## `URL` @@ -204,7 +204,7 @@ added: v10.0.0 The WHATWG `URL` class. See the [`URL`][] section. -## URLSearchParams +## `URLSearchParams` @@ -213,7 +213,7 @@ added: v10.0.0 The WHATWG `URLSearchParams` class. See the [`URLSearchParams`][] section. -## WebAssembly +## `WebAssembly` diff --git a/doc/api/http.md b/doc/api/http.md index 3550136aebb5b9..48767107affce5 100644 --- a/doc/api/http.md +++ b/doc/api/http.md @@ -47,7 +47,7 @@ list like the following: 'accepT', '*/*' ] ``` -## Class: http.Agent +## Class: `http.Agent` @@ -107,7 +107,7 @@ http.get({ }); ``` -### new Agent(\[options\]) +### `new Agent([options])` @@ -149,7 +149,7 @@ options.agent = keepAliveAgent; http.request(options, onResponseCallback); ``` -### agent.createConnection(options\[, callback\]) +### `agent.createConnection(options[, callback])` @@ -173,7 +173,7 @@ type other than {net.Socket}. `callback` has a signature of `(err, stream)`. -### agent.keepSocketAlive(socket) +### `agent.keepSocketAlive(socket)` @@ -196,7 +196,7 @@ it for use with the next request. The `socket` argument can be an instance of {net.Socket}, a subclass of {stream.Duplex}. -### agent.reuseSocket(socket, request) +### `agent.reuseSocket(socket, request)` @@ -216,7 +216,7 @@ This method can be overridden by a particular `Agent` subclass. The `socket` argument can be an instance of {net.Socket}, a subclass of {stream.Duplex}. -### agent.destroy() +### `agent.destroy()` @@ -229,7 +229,7 @@ the agent when it will no longer be used. Otherwise, sockets may hang open for quite a long time before the server terminates them. -### agent.freeSockets +### `agent.freeSockets` @@ -239,7 +239,7 @@ added: v0.11.4 An object which contains arrays of sockets currently awaiting use by the agent when `keepAlive` is enabled. Do not modify. -### agent.getName(options) +### `agent.getName(options)` @@ -259,7 +259,7 @@ connection can be reused. For an HTTP agent, this returns the name includes the CA, cert, ciphers, and other HTTPS/TLS-specific options that determine socket reusability. -### agent.maxFreeSockets +### `agent.maxFreeSockets` @@ -270,7 +270,7 @@ By default set to 256. For agents with `keepAlive` enabled, this sets the maximum number of sockets that will be left open in the free state. -### agent.maxSockets +### `agent.maxSockets` @@ -280,7 +280,7 @@ added: v0.3.6 By default set to `Infinity`. Determines how many concurrent sockets the agent can have open per origin. Origin is the returned value of [`agent.getName()`][]. -### agent.requests +### `agent.requests` @@ -290,7 +290,7 @@ added: v0.5.9 An object which contains queues of requests that have not yet been assigned to sockets. Do not modify. -### agent.sockets +### `agent.sockets` @@ -300,7 +300,7 @@ added: v0.3.6 An object which contains arrays of sockets currently in use by the agent. Do not modify. -## Class: http.ClientRequest +## Class: `http.ClientRequest` @@ -337,7 +337,7 @@ Unlike the `request` object, if the response closes prematurely, the Node.js does not check whether Content-Length and the length of the body which has been transmitted are equal or not. -### Event: 'abort' +### Event: `'abort'` @@ -345,7 +345,7 @@ added: v1.4.1 Emitted when the request has been aborted by the client. This event is only emitted on the first call to `abort()`. -### Event: 'connect' +### Event: `'connect'` @@ -419,7 +419,7 @@ proxy.listen(1337, '127.0.0.1', () => { }); ``` -### Event: 'continue' +### Event: `'continue'` @@ -428,7 +428,7 @@ Emitted when the server sends a '100 Continue' HTTP response, usually because the request contained 'Expect: 100-continue'. This is an instruction that the client should send the request body. -### Event: 'information' +### Event: `'information'` @@ -470,7 +470,7 @@ traditional HTTP request/response chain, such as web sockets, in-place TLS upgrades, or HTTP 2.0. To be notified of 101 Upgrade notices, listen for the [`'upgrade'`][] event instead. -### Event: 'response' +### Event: `'response'` @@ -480,7 +480,7 @@ added: v0.1.0 Emitted when a response is received to this request. This event is emitted only once. -### Event: 'socket' +### Event: `'socket'` @@ -491,7 +491,7 @@ This event is guaranteed to be passed an instance of the {net.Socket} class, a subclass of {stream.Duplex}, unless the user specifies a socket type other than {net.Socket}. -### Event: 'timeout' +### Event: `'timeout'` @@ -501,7 +501,7 @@ that the socket has been idle. The request must be aborted manually. See also: [`request.setTimeout()`][]. -### Event: 'upgrade' +### Event: `'upgrade'` @@ -562,7 +562,7 @@ srv.listen(1337, '127.0.0.1', () => { }); ``` -### request.abort() +### `request.abort()` @@ -570,7 +570,7 @@ added: v0.3.8 Marks the request as aborting. Calling this will cause remaining data in the response to be dropped and the socket to be destroyed. -### request.aborted +### `request.aborted` @@ -649,7 +649,7 @@ That's usually desired (it saves a TCP round-trip), but not when the first data is not sent until possibly much later. `request.flushHeaders()` bypasses the optimization and kickstarts the request. -### request.getHeader(name) +### `request.getHeader(name)` @@ -673,20 +673,20 @@ const cookie = request.getHeader('Cookie'); // 'cookie' is of type string[] ``` -### request.maxHeadersCount +### `request.maxHeadersCount` * {number} **Default:** `2000` Limits maximum response headers count. If set to 0, no limit will be applied. -### request.path +### `request.path` * {string} The request path. -### request.removeHeader(name) +### `request.removeHeader(name)` @@ -699,7 +699,7 @@ Removes a header that's already defined into headers object. request.removeHeader('Content-Type'); ``` -### request.reusedSocket +### `request.reusedSocket` @@ -780,7 +780,7 @@ or request.setHeader('Cookie', ['type=ninja', 'language=javascript']); ``` -### request.setNoDelay(\[noDelay\]) +### `request.setNoDelay([noDelay])` @@ -790,7 +790,7 @@ added: v0.5.9 Once a socket is assigned to this request and is connected [`socket.setNoDelay()`][] will be called. -### request.setSocketKeepAlive(\[enable\]\[, initialDelay\]) +### `request.setSocketKeepAlive([enable][, initialDelay])` @@ -801,7 +801,7 @@ added: v0.5.9 Once a socket is assigned to this request and is connected [`socket.setKeepAlive()`][] will be called. -### request.setTimeout(timeout\[, callback\]) +### `request.setTimeout(timeout[, callback])` @@ -849,7 +849,7 @@ This property is guaranteed to be an instance of the {net.Socket} class, a subclass of {stream.Duplex}, unless the user specified a socket type other than {net.Socket}. -### request.writableEnded +### `request.writableEnded` @@ -860,7 +860,7 @@ Is `true` after [`request.end()`][] has been called. This property does not indicate whether the data has been flushed, for this use [`request.writableFinished`][] instead. -### request.writableFinished +### `request.writableFinished` @@ -870,7 +870,7 @@ added: v12.7.0 Is `true` if all data has been flushed to the underlying system, immediately before the [`'finish'`][] event is emitted. -### request.write(chunk\[, encoding\]\[, callback\]) +### `request.write(chunk[, encoding][, callback])` @@ -899,14 +899,14 @@ buffer. Returns `false` if all or part of the data was queued in user memory. When `write` function is called with empty string or buffer, it does nothing and waits for more input. -## Class: http.Server +## Class: `http.Server` * Extends: {net.Server} -### Event: 'checkContinue' +### Event: `'checkContinue'` @@ -926,7 +926,7 @@ the request body. When this event is emitted and handled, the [`'request'`][] event will not be emitted. -### Event: 'checkExpectation' +### Event: `'checkExpectation'` @@ -941,7 +941,7 @@ automatically respond with a `417 Expectation Failed` as appropriate. When this event is emitted and handled, the [`'request'`][] event will not be emitted. -### Event: 'clientError' +### Event: `'clientError'` Emitted when the server closes. -### Event: 'connect' +### Event: `'connect'` @@ -1032,7 +1032,7 @@ After this event is emitted, the request's socket will not have a `'data'` event listener, meaning it will need to be bound in order to handle data sent to the server on that socket. -### Event: 'connection' +### Event: `'connection'` @@ -1056,7 +1056,7 @@ This event is guaranteed to be passed an instance of the {net.Socket} class, a subclass of {stream.Duplex}, unless the user specifies a socket type other than {net.Socket}. -### Event: 'request' +### Event: `'request'` @@ -1067,7 +1067,7 @@ added: v0.1.0 Emitted each time there is a request. There may be multiple requests per connection (in the case of HTTP Keep-Alive connections). -### Event: 'upgrade' +### Event: `'upgrade'` @@ -1102,7 +1102,7 @@ added: v0.1.90 Stops the server from accepting new connections. See [`net.Server.close()`][]. -### server.headersTimeout +### `server.headersTimeout` @@ -1122,19 +1122,19 @@ event is emitted on the server object, and (by default) the socket is destroyed. See [`server.timeout`][] for more information on how timeout behavior can be customized. -### server.listen() +### `server.listen()` Starts the HTTP server listening for connections. This method is identical to [`server.listen()`][] from [`net.Server`][]. -### server.listening +### `server.listening` * {boolean} Indicates whether or not the server is listening for connections. -### server.maxHeadersCount +### `server.maxHeadersCount` @@ -1143,7 +1143,7 @@ added: v0.7.0 Limits maximum incoming headers count. If set to 0, no limit will be applied. -### server.setTimeout(\[msecs\]\[, callback\]) +### `server.setTimeout([msecs][, callback])` @@ -1207,7 +1207,7 @@ to 8.0.0, which did not have a keep-alive timeout. The socket timeout logic is set up on connection, so changing this value only affects new connections to the server, not any existing connections. -## Class: http.ServerResponse +## Class: `http.ServerResponse` @@ -1217,14 +1217,14 @@ added: v0.1.17 This object is created internally by an HTTP server — not by the user. It is passed as the second parameter to the [`'request'`][] event. -### Event: 'close' +### Event: `'close'` Indicates that the underlying connection was terminated. -### Event: 'finish' +### Event: `'finish'` @@ -1234,7 +1234,7 @@ emitted when the last segment of the response headers and body have been handed off to the operating system for transmission over the network. It does not imply that the client has received anything yet. -### response.addTrailers(headers) +### `response.addTrailers(headers)` @@ -1262,7 +1262,7 @@ response.end(); Attempting to set a header field name or value that contains invalid characters will result in a [`TypeError`][] being thrown. -### response.connection +### `response.connection` See [`writable.cork()`][]. -### response.end(\[data\[, encoding\]\]\[, callback\]) +### `response.end([data[, encoding]][, callback])` Flushes the response headers. See also: [`request.flushHeaders()`][]. -### response.getHeader(name) +### `response.getHeader(name)` @@ -1349,7 +1349,7 @@ const setCookie = response.getHeader('set-cookie'); // setCookie is of type string[] ``` -### response.getHeaderNames() +### `response.getHeaderNames()` @@ -1367,7 +1367,7 @@ const headerNames = response.getHeaderNames(); // headerNames === ['foo', 'set-cookie'] ``` -### response.getHeaders() +### `response.getHeaders()` @@ -1393,7 +1393,7 @@ const headers = response.getHeaders(); // headers === { foo: 'bar', 'set-cookie': ['foo=bar', 'bar=baz'] } ``` -### response.hasHeader(name) +### `response.hasHeader(name)` @@ -1408,7 +1408,7 @@ outgoing headers. The header name matching is case-insensitive. const hasContentType = response.hasHeader('content-type'); ``` -### response.headersSent +### `response.headersSent` @@ -1417,7 +1417,7 @@ added: v0.9.3 Boolean (read-only). True if headers were sent, false otherwise. -### response.removeHeader(name) +### `response.removeHeader(name)` @@ -1430,7 +1430,7 @@ Removes a header that's queued for implicit sending. response.removeHeader('Content-Encoding'); ``` -### response.sendDate +### `response.sendDate` @@ -1443,7 +1443,7 @@ the response if it is not already present in the headers. Defaults to true. This should only be disabled for testing; HTTP requires the Date header in responses. -### response.setHeader(name, value) +### `response.setHeader(name, value)` @@ -1492,7 +1492,7 @@ header will not yield the expected result. If progressive population of headers is desired with potential future retrieval and modification, use [`response.setHeader()`][] instead of [`response.writeHead()`][]. -### response.setTimeout(msecs\[, callback\]) +### `response.setTimeout(msecs[, callback])` @@ -1510,7 +1510,7 @@ the server, then sockets are destroyed when they time out. If a handler is assigned to the request, the response, or the server's `'timeout'` events, timed out sockets must be handled explicitly. -### response.socket +### `response.socket` @@ -1536,7 +1536,7 @@ This property is guaranteed to be an instance of the {net.Socket} class, a subclass of {stream.Duplex}, unless the user specified a socket type other than {net.Socket}. -### response.statusCode +### `response.statusCode` @@ -1554,7 +1554,7 @@ response.statusCode = 404; After response header was sent to the client, this property indicates the status code which was sent out. -### response.statusMessage +### `response.statusMessage` @@ -1573,14 +1573,14 @@ response.statusMessage = 'Not found'; After response header was sent to the client, this property indicates the status message which was sent out. -### response.uncork() +### `response.uncork()` See [`writable.uncork()`][]. -### response.writableEnded +### `response.writableEnded` @@ -1591,7 +1591,7 @@ Is `true` after [`response.end()`][] has been called. This property does not indicate whether the data has been flushed, for this use [`response.writableFinished`][] instead. -### response.writableFinished +### `response.writableFinished` @@ -1601,7 +1601,7 @@ added: v12.7.0 Is `true` if all data has been flushed to the underlying system, immediately before the [`'finish'`][] event is emitted. -### response.write(chunk\[, encoding\]\[, callback\]) +### `response.write(chunk[, encoding][, callback])` @@ -1638,7 +1638,7 @@ Returns `true` if the entire data was flushed successfully to the kernel buffer. Returns `false` if all or part of the data was queued in user memory. `'drain'` will be emitted when the buffer is free again. -### response.writeContinue() +### `response.writeContinue()` @@ -1647,7 +1647,7 @@ Sends a HTTP/1.1 100 Continue message to the client, indicating that the request body should be sent. See the [`'checkContinue'`][] event on `Server`. -### response.writeHead(statusCode\[, statusMessage\]\[, headers\]) +### `response.writeHead(statusCode[, statusMessage][, headers])` @@ -1728,7 +1728,7 @@ added: v10.0.0 Sends a HTTP/1.1 102 Processing message to the client, indicating that the request body should be sent. -## Class: http.IncomingMessage +## Class: `http.IncomingMessage` Emitted when the request has been aborted. -### Event: 'close' +### Event: `'close'` Indicates that the underlying connection was closed. -### message.aborted +### `message.aborted` @@ -1768,7 +1768,7 @@ added: v10.1.0 The `message.aborted` property will be `true` if the request has been aborted. -### message.complete +### `message.complete` @@ -1796,7 +1796,7 @@ const req = http.request({ }); ``` -### message.destroy(\[error\]) +### `message.destroy([error])` @@ -1807,7 +1807,7 @@ Calls `destroy()` on the socket that received the `IncomingMessage`. If `error` is provided, an `'error'` event is emitted on the socket and `error` is passed as an argument to any listeners on the event. -### message.headers +### `message.headers` @@ -1838,7 +1838,7 @@ header name: * For duplicate `cookie` headers, the values are joined together with '; '. * For all other headers, the values are joined together with ', '. -### message.httpVersion +### `message.httpVersion` @@ -1852,7 +1852,7 @@ Probably either `'1.1'` or `'1.0'`. Also `message.httpVersionMajor` is the first integer and `message.httpVersionMinor` is the second. -### message.method +### `message.method` @@ -1863,7 +1863,7 @@ added: v0.1.1 The request method as a string. Read only. Examples: `'GET'`, `'DELETE'`. -### message.rawHeaders +### `message.rawHeaders` @@ -1892,7 +1892,7 @@ Header names are not lowercased, and duplicates are not merged. console.log(request.rawHeaders); ``` -### message.rawTrailers +### `message.rawTrailers` @@ -1902,7 +1902,7 @@ added: v0.11.6 The raw request/response trailer keys and values exactly as they were received. Only populated at the `'end'` event. -### message.setTimeout(msecs\[, callback\]) +### `message.setTimeout(msecs[, callback])` @@ -1913,7 +1913,7 @@ added: v0.5.9 Calls `message.connection.setTimeout(msecs, callback)`. -### message.socket +### `message.socket` @@ -1929,7 +1929,7 @@ This property is guaranteed to be an instance of the {net.Socket} class, a subclass of {stream.Duplex}, unless the user specified a socket type other than {net.Socket}. -### message.statusCode +### `message.statusCode` @@ -1940,7 +1940,7 @@ added: v0.1.1 The 3-digit HTTP response status code. E.G. `404`. -### message.statusMessage +### `message.statusMessage` @@ -1952,7 +1952,7 @@ added: v0.11.10 The HTTP response status message (reason phrase). E.G. `OK` or `Internal Server Error`. -### message.trailers +### `message.trailers` @@ -1961,7 +1961,7 @@ added: v0.3.0 The request/response trailers object. Only populated at the `'end'` event. -### message.url +### `message.url` @@ -1979,57 +1979,35 @@ Accept: text/plain\r\n \r\n ``` -Then `request.url` will be: +To parse the URL into its parts: - ```js -'/status?name=ryan' +new URL(request.url, `http://${request.headers.host}`); ``` -To parse the url into its parts `require('url').parse(request.url)` -can be used: +When `request.url` is `'/status?name=ryan'` and +`request.headers.host` is `'localhost:3000'`: ```console $ node -> require('url').parse('/status?name=ryan') -Url { - protocol: null, - slashes: null, - auth: null, - host: null, - port: null, - hostname: null, - hash: null, - search: '?name=ryan', - query: 'name=ryan', +> new URL(request.url, request.headers.host) +URL { + href: 'http://localhost:3000/status?name=ryan', + origin: 'http://localhost:3000', + protocol: 'http:', + username: '', + password: '', + host: 'localhost:3000', + hostname: 'localhost', + port: '3000', pathname: '/status', - path: '/status?name=ryan', - href: '/status?name=ryan' } -``` - -To extract the parameters from the query string, the -`require('querystring').parse` function can be used, or -`true` can be passed as the second argument to `require('url').parse`: - -```console -$ node -> require('url').parse('/status?name=ryan', true) -Url { - protocol: null, - slashes: null, - auth: null, - host: null, - port: null, - hostname: null, - hash: null, search: '?name=ryan', - query: { name: 'ryan' }, - pathname: '/status', - path: '/status?name=ryan', - href: '/status?name=ryan' } + searchParams: URLSearchParams { 'name' => 'ryan' }, + hash: '' +} ``` -## http.METHODS +## `http.METHODS` @@ -2038,7 +2016,7 @@ added: v0.11.8 A list of the HTTP methods that are supported by the parser. -## http.STATUS_CODES +## `http.STATUS_CODES` @@ -2049,7 +2027,7 @@ A collection of all the standard HTTP response status codes, and the short description of each. For example, `http.STATUS_CODES[404] === 'Not Found'`. -## http.createServer(\[options\]\[, requestListener\]) +## `http.createServer([options][, requestListener])` @@ -2159,7 +2137,7 @@ added: v0.5.9 Global instance of `Agent` which is used as the default for all HTTP client requests. -## http.maxHeaderSize +## `http.maxHeaderSize` @@ -2172,8 +2150,8 @@ Defaults to 8KB. Configurable using the [`--max-http-header-size`][] CLI option. This can be overridden for servers and client requests by passing the `maxHeaderSize` option. -## http.request(options\[, callback\]) -## http.request(url\[, options\]\[, callback\]) +## `http.request(options[, callback])` +## `http.request(url[, options][, callback])` @@ -119,7 +119,7 @@ User code will not create `Http2Session` instances directly. Server-side new HTTP/2 connection is received. Client-side `Http2Session` instances are created using the `http2.connect()` method. -#### Http2Session and Sockets +#### `Http2Session` and Sockets Every `Http2Session` instance is associated with exactly one [`net.Socket`][] or [`tls.TLSSocket`][] when it is created. When either the `Socket` or the @@ -134,7 +134,7 @@ the socket to become unusable. Once a `Socket` has been bound to an `Http2Session`, user code should rely solely on the API of the `Http2Session`. -#### Event: 'close' +#### Event: `'close'` @@ -142,7 +142,7 @@ added: v8.4.0 The `'close'` event is emitted once the `Http2Session` has been destroyed. Its listener does not expect any arguments. -#### Event: 'connect' +#### Event: `'connect'` @@ -155,7 +155,7 @@ connected to the remote peer and communication may begin. User code will typically not listen for this event directly. -#### Event: 'error' +#### Event: `'error'` @@ -165,7 +165,7 @@ added: v8.4.0 The `'error'` event is emitted when an error occurs during the processing of an `Http2Session`. -#### Event: 'frameError' +#### Event: `'frameError'` @@ -185,7 +185,7 @@ closed and destroyed immediately following the `'frameError'` event. If the event is not associated with a stream, the `Http2Session` will be shut down immediately following the `'frameError'` event. -#### Event: 'goaway' +#### Event: `'goaway'` @@ -201,7 +201,7 @@ The `'goaway'` event is emitted when a `GOAWAY` frame is received. The `Http2Session` instance will be shut down automatically when the `'goaway'` event is emitted. -#### Event: 'localSettings' +#### Event: `'localSettings'` @@ -222,7 +222,7 @@ session.on('localSettings', (settings) => { }); ``` -#### Event: 'ping' +#### Event: `'ping'` @@ -232,7 +232,7 @@ added: v10.12.0 The `'ping'` event is emitted whenever a `PING` frame is received from the connected peer. -#### Event: 'remoteSettings' +#### Event: `'remoteSettings'` @@ -248,7 +248,7 @@ session.on('remoteSettings', (settings) => { }); ``` -#### Event: 'stream' +#### Event: `'stream'` @@ -303,7 +303,7 @@ Even though HTTP/2 streams and network sockets are not in a 1:1 correspondence, a network error will destroy each individual stream and must be handled on the stream level, as shown above. -#### Event: 'timeout' +#### Event: `'timeout'` @@ -318,7 +318,7 @@ session.setTimeout(2000); session.on('timeout', () => { /* .. */ }); ``` -#### http2session.alpnProtocol +#### `http2session.alpnProtocol` @@ -330,7 +330,7 @@ socket, `h2c` if the `Http2Session` is not connected to a `TLSSocket`, or will return the value of the connected `TLSSocket`'s own `alpnProtocol` property. -#### http2session.close(\[callback\]) +#### `http2session.close([callback])` @@ -345,7 +345,7 @@ are no open `Http2Stream` instances. If specified, the `callback` function is registered as a handler for the `'close'` event. -#### http2session.closed +#### `http2session.closed` @@ -355,7 +355,7 @@ added: v9.4.0 Will be `true` if this `Http2Session` instance has been closed, otherwise `false`. -#### http2session.connecting +#### `http2session.connecting` @@ -366,7 +366,7 @@ Will be `true` if this `Http2Session` instance is still connecting, will be set to `false` before emitting `connect` event and/or calling the `http2.connect` callback. -#### http2session.destroy(\[error\]\[, code\]) +#### `http2session.destroy([error][, code])` @@ -387,7 +387,7 @@ is not undefined, an `'error'` event will be emitted immediately before the If there are any remaining open `Http2Streams` associated with the `Http2Session`, those will also be destroyed. -#### http2session.destroyed +#### `http2session.destroyed` @@ -397,7 +397,7 @@ added: v8.4.0 Will be `true` if this `Http2Session` instance has been destroyed and must no longer be used, otherwise `false`. -#### http2session.encrypted +#### `http2session.encrypted` @@ -409,7 +409,7 @@ connected, `true` if the `Http2Session` is connected with a `TLSSocket`, and `false` if the `Http2Session` is connected to any other kind of socket or stream. -#### http2session.goaway(\[code\[, lastStreamID\[, opaqueData\]\]\]) +#### `http2session.goaway([code[, lastStreamID[, opaqueData]]])` @@ -422,7 +422,7 @@ added: v9.4.0 Transmits a `GOAWAY` frame to the connected peer *without* shutting down the `Http2Session`. -#### http2session.localSettings +#### `http2session.localSettings` @@ -432,7 +432,7 @@ added: v8.4.0 A prototype-less object describing the current local settings of this `Http2Session`. The local settings are local to *this* `Http2Session` instance. -#### http2session.originSet +#### `http2session.originSet` @@ -445,7 +445,7 @@ considered authoritative. The `originSet` property is only available when using a secure TLS connection. -#### http2session.pendingSettingsAck +#### `http2session.pendingSettingsAck` @@ -457,7 +457,7 @@ a sent `SETTINGS` frame. Will be `true` after calling the `http2session.settings()` method. Will be `false` once all sent `SETTINGS` frames have been acknowledged. -#### http2session.ping(\[payload, \]callback) +#### `http2session.ping([payload, ]callback)` @@ -495,7 +495,7 @@ session.ping(Buffer.from('abcdefgh'), (err, duration, payload) => { If the `payload` argument is not specified, the default payload will be the 64-bit timestamp (little endian) marking the start of the `PING` duration. -#### http2session.ref() +#### `http2session.ref()` @@ -503,7 +503,7 @@ added: v9.4.0 Calls [`ref()`][`net.Socket.prototype.ref()`] on this `Http2Session` instance's underlying [`net.Socket`][]. -#### http2session.remoteSettings +#### `http2session.remoteSettings` @@ -513,7 +513,7 @@ added: v8.4.0 A prototype-less object describing the current remote settings of this `Http2Session`. The remote settings are set by the *connected* HTTP/2 peer. -#### http2session.setTimeout(msecs, callback) +#### `http2session.setTimeout(msecs, callback)` @@ -525,7 +525,7 @@ Used to set a callback function that is called when there is no activity on the `Http2Session` after `msecs` milliseconds. The given `callback` is registered as a listener on the `'timeout'` event. -#### http2session.socket +#### `http2session.socket` @@ -543,7 +543,7 @@ an error with code `ERR_HTTP2_NO_SOCKET_MANIPULATION`. See All other interactions will be routed directly to the socket. -#### http2session.state +#### `http2session.state` @@ -573,7 +573,7 @@ Provides miscellaneous information about the current state of the An object describing the current status of this `Http2Session`. -#### http2session.settings(\[settings\]\[, callback\]) +#### `http2session.settings([settings][, callback])` @@ -596,7 +596,7 @@ The new settings will not become effective until the `SETTINGS` acknowledgment is received and the `'localSettings'` event is emitted. It is possible to send multiple `SETTINGS` frames while acknowledgment is still pending. -#### http2session.type +#### `http2session.type` @@ -608,7 +608,7 @@ The `http2session.type` will be equal to server, and `http2.constants.NGHTTP2_SESSION_CLIENT` if the instance is a client. -#### http2session.unref() +#### `http2session.unref()` @@ -616,14 +616,14 @@ added: v9.4.0 Calls [`unref()`][`net.Socket.prototype.unref()`] on this `Http2Session` instance's underlying [`net.Socket`][]. -### Class: ServerHttp2Session +### Class: `ServerHttp2Session` * Extends: {Http2Session} -#### serverhttp2session.altsvc(alt, originOrStream) +#### `serverhttp2session.altsvc(alt, originOrStream)` @@ -690,7 +690,7 @@ The protocol identifier (`'h2'` in the examples) may be any valid The syntax of these values is not validated by the Node.js implementation and are passed through as provided by the user or received from the peer. -#### serverhttp2session.origin(...origins) +#### `serverhttp2session.origin(...origins)` @@ -740,14 +740,14 @@ server.on('stream', (stream) => { }); ``` -### Class: ClientHttp2Session +### Class: `ClientHttp2Session` * Extends: {Http2Session} -#### Event: 'altsvc' +#### Event: `'altsvc'` @@ -772,7 +772,7 @@ client.on('altsvc', (alt, origin, streamId) => { }); ``` -#### Event: 'origin' +#### Event: `'origin'` @@ -796,7 +796,7 @@ client.on('origin', (origins) => { The `'origin'` event is only emitted when using a secure TLS connection. -#### clienthttp2session.request(headers\[, options\]) +#### `clienthttp2session.request(headers[, options])` @@ -859,7 +859,7 @@ they respectively default to: * `:method` = `'GET'` * `:path` = `/` -### Class: Http2Stream +### Class: `Http2Stream` @@ -887,7 +887,7 @@ All `Http2Stream` instances are [`Duplex`][] streams. The `Writable` side of the `Duplex` is used to send data to the connected peer, while the `Readable` side is used to receive data sent by the connected peer. -#### Http2Stream Lifecycle +#### `Http2Stream` Lifecycle ##### Creation @@ -931,7 +931,7 @@ property will be `true` and the `http2stream.rstCode` property will specify the `RST_STREAM` error code. The `Http2Stream` instance is no longer usable once destroyed. -#### Event: 'aborted' +#### Event: `'aborted'` @@ -943,7 +943,7 @@ Its listener does not expect any arguments. The `'aborted'` event will only be emitted if the `Http2Stream` writable side has not been ended. -#### Event: 'close' +#### Event: `'close'` @@ -955,7 +955,7 @@ The HTTP/2 error code used when closing the stream can be retrieved using the `http2stream.rstCode` property. If the code is any value other than `NGHTTP2_NO_ERROR` (`0`), an `'error'` event will have also been emitted. -#### Event: 'error' +#### Event: `'error'` @@ -965,7 +965,7 @@ added: v8.4.0 The `'error'` event is emitted when an error occurs during the processing of an `Http2Stream`. -#### Event: 'frameError' +#### Event: `'frameError'` @@ -981,7 +981,7 @@ argument identifying the frame type, and an integer argument identifying the error code. The `Http2Stream` instance will be destroyed immediately after the `'frameError'` event is emitted. -#### Event: 'timeout' +#### Event: `'timeout'` @@ -991,7 +991,7 @@ The `'timeout'` event is emitted after no activity is received for this `http2stream.setTimeout()`. Its listener does not expect any arguments. -#### Event: 'trailers' +#### Event: `'trailers'` @@ -1013,7 +1013,7 @@ stream.on('trailers', (headers, flags) => { }); ``` -#### Event: 'wantTrailers' +#### Event: `'wantTrailers'` @@ -1023,7 +1023,7 @@ final `DATA` frame to be sent on a frame and the `Http2Stream` is ready to send trailing headers. When initiating a request or response, the `waitForTrailers` option must be set for this event to be emitted. -#### http2stream.aborted +#### `http2stream.aborted` @@ -1033,7 +1033,7 @@ added: v8.4.0 Set to `true` if the `Http2Stream` instance was aborted abnormally. When set, the `'aborted'` event will have been emitted. -#### http2stream.bufferSize +#### `http2stream.bufferSize` @@ -1043,7 +1043,7 @@ added: v11.2.0 This property shows the number of characters currently buffered to be written. See [`net.Socket.bufferSize`][] for details. -#### http2stream.close(code\[, callback\]) +#### `http2stream.close(code[, callback])` @@ -1056,7 +1056,7 @@ added: v8.4.0 Closes the `Http2Stream` instance by sending an `RST_STREAM` frame to the connected HTTP/2 peer. -#### http2stream.closed +#### `http2stream.closed` @@ -1065,7 +1065,7 @@ added: v9.4.0 Set to `true` if the `Http2Stream` instance has been closed. -#### http2stream.destroyed +#### `http2stream.destroyed` @@ -1075,7 +1075,7 @@ added: v8.4.0 Set to `true` if the `Http2Stream` instance has been destroyed and is no longer usable. -#### http2stream.endAfterHeaders +#### `http2stream.endAfterHeaders` @@ -1086,7 +1086,7 @@ Set the `true` if the `END_STREAM` flag was set in the request or response HEADERS frame received, indicating that no additional data should be received and the readable side of the `Http2Stream` will be closed. -#### http2stream.id +#### `http2stream.id` @@ -1096,7 +1096,7 @@ added: v8.4.0 The numeric stream identifier of this `Http2Stream` instance. Set to `undefined` if the stream identifier has not yet been assigned. -#### http2stream.pending +#### `http2stream.pending` @@ -1106,7 +1106,7 @@ added: v9.4.0 Set to `true` if the `Http2Stream` instance has not yet been assigned a numeric stream identifier. -#### http2stream.priority(options) +#### `http2stream.priority(options)` @@ -1126,7 +1126,7 @@ added: v8.4.0 Updates the priority for this `Http2Stream` instance. -#### http2stream.rstCode +#### `http2stream.rstCode` @@ -1138,7 +1138,7 @@ destroyed after either receiving an `RST_STREAM` frame from the connected peer, calling `http2stream.close()`, or `http2stream.destroy()`. Will be `undefined` if the `Http2Stream` has not been closed. -#### http2stream.sentHeaders +#### `http2stream.sentHeaders` @@ -1147,7 +1147,7 @@ added: v9.5.0 An object containing the outbound headers sent for this `Http2Stream`. -#### http2stream.sentInfoHeaders +#### `http2stream.sentInfoHeaders` @@ -1157,7 +1157,7 @@ added: v9.5.0 An array of objects containing the outbound informational (additional) headers sent for this `Http2Stream`. -#### http2stream.sentTrailers +#### `http2stream.sentTrailers` @@ -1166,7 +1166,7 @@ added: v9.5.0 An object containing the outbound trailers sent for this `HttpStream`. -#### http2stream.session +#### `http2stream.session` @@ -1176,7 +1176,7 @@ added: v8.4.0 A reference to the `Http2Session` instance that owns this `Http2Stream`. The value will be `undefined` after the `Http2Stream` instance is destroyed. -#### http2stream.setTimeout(msecs, callback) +#### `http2stream.setTimeout(msecs, callback)` @@ -1194,7 +1194,7 @@ const req = client.request({ ':path': '/' }); req.setTimeout(5000, () => req.close(NGHTTP2_CANCEL)); ``` -#### http2stream.state +#### `http2stream.state` @@ -1216,7 +1216,7 @@ Provides miscellaneous information about the current state of the A current state of this `Http2Stream`. -#### http2stream.sendTrailers(headers) +#### `http2stream.sendTrailers(headers)` @@ -1245,7 +1245,7 @@ server.on('stream', (stream) => { The HTTP/1 specification forbids trailers from containing HTTP/2 pseudo-header fields (e.g. `':method'`, `':path'`, etc). -### Class: ClientHttp2Stream +### Class: `ClientHttp2Stream` @@ -1257,7 +1257,7 @@ used exclusively on HTTP/2 Clients. `Http2Stream` instances on the client provide events such as `'response'` and `'push'` that are only relevant on the client. -#### Event: 'continue' +#### Event: `'continue'` @@ -1266,7 +1266,7 @@ Emitted when the server sends a `100 Continue` status, usually because the request contained `Expect: 100-continue`. This is an instruction that the client should send the request body. -#### Event: 'headers' +#### Event: `'headers'` @@ -1282,7 +1282,7 @@ stream.on('headers', (headers, flags) => { }); ``` -#### Event: 'push' +#### Event: `'push'` @@ -1297,7 +1297,7 @@ stream.on('push', (headers, flags) => { }); ``` -#### Event: 'response' +#### Event: `'response'` @@ -1316,7 +1316,7 @@ req.on('response', (headers, flags) => { }); ``` -### Class: ServerHttp2Stream +### Class: `ServerHttp2Stream` @@ -1328,7 +1328,7 @@ used exclusively on HTTP/2 Servers. `Http2Stream` instances on the server provide additional methods such as `http2stream.pushStream()` and `http2stream.respond()` that are only relevant on the server. -#### http2stream.additionalHeaders(headers) +#### `http2stream.additionalHeaders(headers)` @@ -1337,7 +1337,7 @@ added: v8.4.0 Sends an additional informational `HEADERS` frame to the connected HTTP/2 peer. -#### http2stream.headersSent +#### `http2stream.headersSent` @@ -1346,7 +1346,7 @@ added: v8.4.0 True if headers were sent, false otherwise (read-only). -#### http2stream.pushAllowed +#### `http2stream.pushAllowed` @@ -1358,7 +1358,7 @@ client's most recent `SETTINGS` frame. Will be `true` if the remote peer accepts push streams, `false` otherwise. Settings are the same for every `Http2Stream` in the same `Http2Session`. -#### http2stream.pushStream(headers\[, options\], callback) +#### `http2stream.pushStream(headers[, options], callback)` @@ -1403,7 +1403,7 @@ a `weight` value to `http2stream.priority` with the `silent` option set to Calling `http2stream.pushStream()` from within a pushed stream is not permitted and will throw an error. -#### http2stream.respond(\[headers\[, options\]\]) +#### `http2stream.respond([headers[, options]])` @@ -1446,7 +1446,7 @@ server.on('stream', (stream) => { }); ``` -#### http2stream.respondWithFD(fd\[, headers\[, options\]\]) +#### `http2stream.respondWithFD(fd[, headers[, options]])` @@ -1669,7 +1669,7 @@ Instances of `Http2Server` are created using the `http2.createServer()` function. The `Http2Server` class is not exported directly by the `http2` module. -#### Event: 'checkContinue' +#### Event: `'checkContinue'` @@ -1691,7 +1691,7 @@ the request body. When this event is emitted and handled, the [`'request'`][] event will not be emitted. -#### Event: 'request' +#### Event: `'request'` @@ -1702,7 +1702,7 @@ added: v8.4.0 Emitted each time there is a request. There may be multiple requests per session. See the [Compatibility API][]. -#### Event: 'session' +#### Event: `'session'` @@ -1710,7 +1710,7 @@ added: v8.4.0 The `'session'` event is emitted when a new `Http2Session` is created by the `Http2Server`. -#### Event: 'sessionError' +#### Event: `'sessionError'` @@ -1718,7 +1718,7 @@ added: v8.4.0 The `'sessionError'` event is emitted when an `'error'` event is emitted by an `Http2Session` object associated with the `Http2Server`. -#### Event: 'stream' +#### Event: `'stream'` @@ -1749,7 +1749,7 @@ server.on('stream', (stream, headers, flags) => { }); ``` -#### Event: 'timeout' +#### Event: `'timeout'` @@ -1778,7 +1778,7 @@ If `callback` is provided, it is not invoked until all active sessions have been closed, although the server has already stopped allowing new sessions. See [`net.Server.close()`][] for more details. -#### server.setTimeout(\[msecs\]\[, callback\]) +#### `server.setTimeout([msecs][, callback])` @@ -1811,7 +1811,7 @@ Instances of `Http2SecureServer` are created using the `http2.createSecureServer()` function. The `Http2SecureServer` class is not exported directly by the `http2` module. -#### Event: 'checkContinue' +#### Event: `'checkContinue'` @@ -1833,7 +1833,7 @@ the request body. When this event is emitted and handled, the [`'request'`][] event will not be emitted. -#### Event: 'request' +#### Event: `'request'` @@ -1844,7 +1844,7 @@ added: v8.4.0 Emitted each time there is a request. There may be multiple requests per session. See the [Compatibility API][]. -#### Event: 'session' +#### Event: `'session'` @@ -1852,7 +1852,7 @@ added: v8.4.0 The `'session'` event is emitted when a new `Http2Session` is created by the `Http2SecureServer`. -#### Event: 'sessionError' +#### Event: `'sessionError'` @@ -1860,7 +1860,7 @@ added: v8.4.0 The `'sessionError'` event is emitted when an `'error'` event is emitted by an `Http2Session` object associated with the `Http2SecureServer`. -#### Event: 'stream' +#### Event: `'stream'` @@ -1893,7 +1893,7 @@ server.on('stream', (stream, headers, flags) => { }); ``` -#### Event: 'timeout' +#### Event: `'timeout'` @@ -1902,7 +1902,7 @@ The `'timeout'` event is emitted when there is no activity on the Server for a given number of milliseconds set using `http2secureServer.setTimeout()`. **Default:** 2 minutes. -#### Event: 'unknownProtocol' +#### Event: `'unknownProtocol'` @@ -1912,7 +1912,7 @@ negotiate an allowed protocol (i.e. HTTP/2 or HTTP/1.1). The event handler receives the socket for handling. If no listener is registered for this event, the connection is terminated. See the [Compatibility API][]. -#### server.close(\[callback\]) +#### `server.close([callback])` @@ -1928,7 +1928,7 @@ If `callback` is provided, it is not invoked until all active sessions have been closed, although the server has already stopped allowing new sessions. See [`tls.Server.close()`][] for more details. -#### server.setTimeout(\[msecs\]\[, callback\]) +#### `server.setTimeout([msecs][, callback])` @@ -1946,7 +1946,7 @@ The given callback is registered as a listener on the `'timeout'` event. In case of no callback function were assigned, a new `ERR_INVALID_CALLBACK` error will be thrown. -### http2.createServer(options\[, onRequestHandler\]) +### `http2.createServer(options[, onRequestHandler])` -#### Error Codes for RST_STREAM and GOAWAY +#### Error Codes for `RST_STREAM` and `GOAWAY` | Value | Name | Constant | @@ -2299,7 +2299,7 @@ added: v8.4.0 The `'timeout'` event is emitted when there is no activity on the Server for a given number of milliseconds set using `http2server.setTimeout()`. -### http2.getDefaultSettings() +### `http2.getDefaultSettings()` @@ -2310,7 +2310,7 @@ Returns an object containing the default settings for an `Http2Session` instance. This method returns a new object instance every time it is called so instances returned may be safely modified for use. -### http2.getPackedSettings(\[settings\]) +### `http2.getPackedSettings([settings])` @@ -2331,7 +2331,7 @@ console.log(packed.toString('base64')); // Prints: AAIAAAAA ``` -### http2.getUnpackedSettings(buf) +### `http2.getUnpackedSettings(buf)` @@ -2413,7 +2413,7 @@ properties. header compression. The minimum allowed value is 0. The maximum allowed value is 232-1. **Default:** `4,096 octets`. * `enablePush` {boolean} Specifies `true` if HTTP/2 Push Streams are to be - permitted on the `Http2Session` instances. + permitted on the `Http2Session` instances. **Default:** `true`. * `initialWindowSize` {number} Specifies the *senders* initial window size for stream-level flow control. The minimum allowed value is 0. The maximum allowed value is 232-1. **Default:** `65,535 bytes`. @@ -2433,6 +2433,7 @@ properties. Protocol" defined by [RFC 8441][] is to be enabled. This setting is only meaningful if sent by the server. Once the `enableConnectProtocol` setting has been enabled for a given `Http2Session`, it cannot be disabled. + **Default:** `false`. All additional properties on the settings object are ignored. @@ -2499,7 +2500,7 @@ client.on('stream', (pushedStream, requestHeaders) => { const req = client.request({ ':path': '/' }); ``` -### Supporting the CONNECT method +### Supporting the `CONNECT` method The `CONNECT` method is used to allow an HTTP/2 server to be used as a proxy for TCP/IP connections. @@ -2576,7 +2577,7 @@ req.on('end', () => { req.end('Jane'); ``` -### The Extended CONNECT Protocol +### The Extended `CONNECT` Protocol [RFC 8441][] defines an "Extended CONNECT Protocol" extension to HTTP/2 that may be used to bootstrap the use of an `Http2Stream` using the `CONNECT` @@ -2674,7 +2675,7 @@ function onRequest(req, res) { The `'request'` event works identically on both [HTTPS][] and HTTP/2. -### Class: http2.Http2ServerRequest +### Class: `http2.Http2ServerRequest` @@ -2686,7 +2687,7 @@ A `Http2ServerRequest` object is created by [`http2.Server`][] or [`'request'`][] event. It may be used to access a request status, headers, and data. -#### Event: 'aborted' +#### Event: `'aborted'` @@ -2697,7 +2698,7 @@ abnormally aborted in mid-communication. The `'aborted'` event will only be emitted if the `Http2ServerRequest` writable side has not been ended. -#### Event: 'close' +#### Event: `'close'` @@ -2705,7 +2706,7 @@ added: v8.4.0 Indicates that the underlying [`Http2Stream`][] was closed. Just like `'end'`, this event occurs only once per response. -#### request.aborted +#### `request.aborted` @@ -2715,7 +2716,7 @@ added: v10.1.0 The `request.aborted` property will be `true` if the request has been aborted. -#### request.authority +#### `request.authority` @@ -2725,7 +2726,7 @@ added: v8.4.0 The request authority pseudo header field. It can also be accessed via `req.headers[':authority']`. -#### request.complete +#### `request.complete` @@ -2735,7 +2736,7 @@ added: v12.10.0 The `request.complete` property will be `true` if the request has been completed, aborted, or destroyed. -#### request.connection +#### `request.connection` @@ -2760,7 +2761,7 @@ is emitted and `error` is passed as an argument to any listeners on the event. It does nothing if the stream was already destroyed. -#### request.headers +#### `request.headers` @@ -2793,7 +2794,7 @@ removeAllHeaders(request.headers); assert(request.url); // Fails because the :path header has been removed ``` -#### request.httpVersion +#### `request.httpVersion` @@ -2807,7 +2808,7 @@ client response, the HTTP version of the connected-to server. Returns Also `message.httpVersionMajor` is the first integer and `message.httpVersionMinor` is the second. -#### request.method +#### `request.method` @@ -2816,7 +2817,7 @@ added: v8.4.0 The request method as a string. Read-only. Examples: `'GET'`, `'DELETE'`. -#### request.rawHeaders +#### `request.rawHeaders` @@ -2845,7 +2846,7 @@ Header names are not lowercased, and duplicates are not merged. console.log(request.rawHeaders); ``` -#### request.rawTrailers +#### `request.rawTrailers` @@ -2855,7 +2856,7 @@ added: v8.4.0 The raw request/response trailer keys and values exactly as they were received. Only populated at the `'end'` event. -#### request.scheme +#### `request.scheme` @@ -2865,7 +2866,7 @@ added: v8.4.0 The request scheme pseudo header field indicating the scheme portion of the target URL. -#### request.setTimeout(msecs, callback) +#### `request.setTimeout(msecs, callback)` @@ -2883,7 +2884,7 @@ the server, then [`Http2Stream`][]s are destroyed when they time out. If a handler is assigned to the request, the response, or the server's `'timeout'` events, timed out sockets must be handled explicitly. -#### request.socket +#### `request.socket` @@ -2909,7 +2910,7 @@ All other interactions will be routed directly to the socket. With TLS support, use [`request.socket.getPeerCertificate()`][] to obtain the client's authentication details. -#### request.stream +#### `request.stream` @@ -2918,7 +2919,7 @@ added: v8.4.0 The [`Http2Stream`][] object backing the request. -#### request.trailers +#### `request.trailers` @@ -2927,7 +2928,7 @@ added: v8.4.0 The request/response trailers object. Only populated at the `'end'` event. -#### request.url +#### `request.url` @@ -2993,7 +2994,7 @@ Url { href: '/status?name=ryan' } ``` -### Class: http2.Http2ServerResponse +### Class: `http2.Http2ServerResponse` @@ -3003,7 +3004,7 @@ added: v8.4.0 This object is created internally by an HTTP server — not by the user. It is passed as the second parameter to the [`'request'`][] event. -#### Event: 'close' +#### Event: `'close'` @@ -3011,7 +3012,7 @@ added: v8.4.0 Indicates that the underlying [`Http2Stream`][] was terminated before [`response.end()`][] was called or able to flush. -#### Event: 'finish' +#### Event: `'finish'` @@ -3023,7 +3024,7 @@ does not imply that the client has received anything yet. After this event, no more events will be emitted on the response object. -#### response.addTrailers(headers) +#### `response.addTrailers(headers)` @@ -3036,7 +3037,7 @@ message) to the response. Attempting to set a header field name or value that contains invalid characters will result in a [`TypeError`][] being thrown. -#### response.connection +#### `response.connection` @@ -3100,7 +3101,7 @@ The name is case-insensitive. const contentType = response.getHeader('content-type'); ``` -#### response.getHeaderNames() +#### `response.getHeaderNames()` @@ -3118,7 +3119,7 @@ const headerNames = response.getHeaderNames(); // headerNames === ['foo', 'set-cookie'] ``` -#### response.getHeaders() +#### `response.getHeaders()` @@ -3144,7 +3145,7 @@ const headers = response.getHeaders(); // headers === { foo: 'bar', 'set-cookie': ['foo=bar', 'bar=baz'] } ``` -#### response.hasHeader(name) +#### `response.hasHeader(name)` @@ -3159,7 +3160,7 @@ outgoing headers. The header name matching is case-insensitive. const hasContentType = response.hasHeader('content-type'); ``` -#### response.headersSent +#### `response.headersSent` @@ -3168,7 +3169,7 @@ added: v8.4.0 True if headers were sent, false otherwise (read-only). -#### response.removeHeader(name) +#### `response.removeHeader(name)` @@ -3181,7 +3182,7 @@ Removes a header that has been queued for implicit sending. response.removeHeader('Content-Encoding'); ``` -#### response.sendDate +#### `response.sendDate` @@ -3194,7 +3195,7 @@ the response if it is not already present in the headers. Defaults to true. This should only be disabled for testing; HTTP requires the Date header in responses. -#### response.setHeader(name, value) +#### `response.setHeader(name, value)` @@ -3233,7 +3234,7 @@ const server = http2.createServer((req, res) => { }); ``` -#### response.setTimeout(msecs\[, callback\]) +#### `response.setTimeout(msecs[, callback])` @@ -3251,7 +3252,7 @@ the server, then [`Http2Stream`][]s are destroyed when they time out. If a handler is assigned to the request, the response, or the server's `'timeout'` events, timed out sockets must be handled explicitly. -#### response.socket +#### `response.socket` @@ -3284,7 +3285,7 @@ const server = http2.createServer((req, res) => { }).listen(3000); ``` -#### response.statusCode +#### `response.statusCode` @@ -3302,7 +3303,7 @@ response.statusCode = 404; After response header was sent to the client, this property indicates the status code which was sent out. -#### response.statusMessage +#### `response.statusMessage` @@ -3312,7 +3313,7 @@ added: v8.4.0 Status message is not supported by HTTP/2 (RFC 7540 8.1.2.4). It returns an empty string. -#### response.stream +#### `response.stream` @@ -3321,7 +3322,7 @@ added: v8.4.0 The [`Http2Stream`][] object backing the response. -#### response.writableEnded +#### `response.writableEnded` @@ -3332,7 +3333,7 @@ Is `true` after [`response.end()`][] has been called. This property does not indicate whether the data has been flushed, for this use [`writable.writableFinished`][] instead. -#### response.write(chunk\[, encoding\]\[, callback\]) +#### `response.write(chunk[, encoding][, callback])` @@ -3370,7 +3371,7 @@ Returns `true` if the entire data was flushed successfully to the kernel buffer. Returns `false` if all or part of the data was queued in user memory. `'drain'` will be emitted when the buffer is free again. -#### response.writeContinue() +#### `response.writeContinue()` @@ -3379,7 +3380,7 @@ Sends a status `100 Continue` to the client, indicating that the request body should be sent. See the [`'checkContinue'`][] event on `Http2Server` and `Http2SecureServer`. -#### response.writeHead(statusCode\[, statusMessage\]\[, headers\]) +#### `response.writeHead(statusCode[, statusMessage][, headers])` diff --git a/doc/api/https.md b/doc/api/https.md index 252d4bb33953a5..58741ba04f7e01 100644 --- a/doc/api/https.md +++ b/doc/api/https.md @@ -7,7 +7,7 @@ HTTPS is the HTTP protocol over TLS/SSL. In Node.js this is implemented as a separate module. -## Class: https.Agent +## Class: `https.Agent` @@ -70,7 +70,7 @@ https.globalAgent.on('keylog', (line, tlsSocket) => { }); ``` -## Class: https.Server +## Class: `https.Server` @@ -79,7 +79,7 @@ added: v0.3.4 See [`http.Server`][] for more information. -### server.close(\[callback\]) +### `server.close([callback])` @@ -89,7 +89,7 @@ added: v0.1.90 See [`server.close()`][`http.close()`] from the HTTP module for details. -### server.headersTimeout +### `server.headersTimeout` @@ -98,18 +98,18 @@ added: v11.3.0 See [`http.Server#headersTimeout`][]. -### server.listen() +### `server.listen()` Starts the HTTPS server listening for encrypted connections. This method is identical to [`server.listen()`][] from [`net.Server`][]. -### server.maxHeadersCount +### `server.maxHeadersCount` * {number} **Default:** `2000` See [`http.Server#maxHeadersCount`][]. -### server.setTimeout(\[msecs\]\[, callback\]) +### `server.setTimeout([msecs][, callback])` @@ -120,7 +120,7 @@ added: v0.11.2 See [`http.Server#setTimeout()`][]. -### server.timeout +### `server.timeout` @@ -129,7 +129,7 @@ added: v0.11.2 See [`http.Server#timeout`][]. -### server.keepAliveTimeout +### `server.keepAliveTimeout` @@ -138,7 +138,7 @@ added: v8.0.0 See [`http.Server#keepAliveTimeout`][]. -## https.createServer(\[options\]\[, requestListener\]) +## `https.createServer([options][, requestListener])` @@ -181,8 +181,8 @@ https.createServer(options, (req, res) => { }).listen(8000); ``` -## https.get(options\[, callback\]) -## https.get(url\[, options\]\[, callback\]) +## `https.get(options[, callback])` +## `https.get(url[, options][, callback])` Global instance of [`https.Agent`][] for all HTTPS client requests. -## https.request(options\[, callback\]) -## https.request(url\[, options\]\[, callback\]) +## `https.request(options[, callback])` +## `https.request(url[, options][, callback])` @@ -77,14 +77,14 @@ Blocks until a client (existing or connected later) has sent An exception will be thrown if there is no active inspector. -## Class: inspector.Session +## Class: `inspector.Session` * Extends: {EventEmitter} The `inspector.Session` is used for dispatching messages to the V8 inspector back-end and receiving message responses and notifications. -### Constructor: new inspector.Session() +### Constructor: `new inspector.Session()` @@ -93,7 +93,7 @@ Create a new instance of the `inspector.Session` class. The inspector session needs to be connected through [`session.connect()`][] before the messages can be dispatched to the inspector backend. -### Event: 'inspectorNotification' +### Event: `'inspectorNotification'` @@ -110,7 +110,7 @@ session.on('inspectorNotification', (message) => console.log(message.method)); It is also possible to subscribe only to notifications with specific method: -### Event: <inspector-protocol-method> +### Event: ``; @@ -131,14 +131,14 @@ session.on('Debugger.paused', ({ params }) => { // [ '/the/file/that/has/the/breakpoint.js:11:0' ] ``` -### session.connect() +### `session.connect()` Connects a session to the inspector back-end. -### session.connectToMainThread() +### `session.connectToMainThread()` @@ -146,7 +146,7 @@ added: v12.11.0 Connects a session to the main thread inspector back-end. An exception will be thrown if this API was not called on a Worker thread. -### session.disconnect() +### `session.disconnect()` @@ -156,7 +156,7 @@ with an error. [`session.connect()`][] will need to be called to be able to send messages again. Reconnected session will lose all inspector state, such as enabled agents or configured breakpoints. -### session.post(method\[, params\]\[, callback\]) +### `session.post(method[, params][, callback])` diff --git a/doc/api/modules.md b/doc/api/modules.md index 5653fe8f4245bd..bac8b21d775fae 100644 --- a/doc/api/modules.md +++ b/doc/api/modules.md @@ -132,7 +132,7 @@ variable. Since the module lookups using `node_modules` folders are all relative, and based on the real path of the files making the calls to `require()`, the packages themselves can be anywhere. -## Addenda: The .mjs extension +## Addenda: The `.mjs` extension It is not possible to `require()` files that have the `.mjs` extension. Attempting to do so will throw [an error][]. The `.mjs` extension is @@ -160,9 +160,9 @@ require(X) from module at path Y a. LOAD_AS_FILE(Y + X) b. LOAD_AS_DIRECTORY(Y + X) c. THROW "not found" -4. LOAD_NODE_MODULES(X, dirname(Y)) -5. LOAD_SELF_REFERENCE(X, dirname(Y)) -6. THROW "not found" +4. LOAD_SELF_REFERENCE(X, dirname(Y)) +5. LOAD_NODE_MODULES(X, dirname(Y)) +7. THROW "not found" LOAD_AS_FILE(X) 1. If X is a file, load X as JavaScript text. STOP @@ -205,9 +205,10 @@ NODE_MODULES_PATHS(START) LOAD_SELF_REFERENCE(X, START) 1. Find the closest package scope to START. -2. If no scope was found, throw "not found". -3. If the name in `package.json` isn't a prefix of X, throw "not found". -4. Otherwise, resolve the remainder of X relative to this package as if it +2. If no scope was found, return. +3. If the `package.json` has no "exports", return. +4. If the name in `package.json` isn't a prefix of X, throw "not found". +5. Otherwise, resolve the remainder of X relative to this package as if it was loaded via `LOAD_NODE_MODULES` with a name in `package.json`. ``` @@ -518,7 +519,7 @@ the module rather than the global object. ## The module scope -### \_\_dirname +### `__dirname` @@ -539,7 +540,7 @@ console.log(path.dirname(__filename)); // Prints: /Users/mjr ``` -### \_\_filename +### `__filename` @@ -577,7 +578,7 @@ References to `__filename` within `b.js` will return `/Users/mjr/app/node_modules/b/b.js` while references to `__filename` within `a.js` will return `/Users/mjr/app/a.js`. -### exports +### `exports` @@ -590,7 +591,7 @@ A reference to the `module.exports` that is shorter to type. See the section about the [exports shortcut][] for details on when to use `exports` and when to use `module.exports`. -### module +### `module` @@ -603,7 +604,7 @@ A reference to the current module, see the section about the [`module` object][]. In particular, `module.exports` is used for defining what a module exports and makes available through `require()`. -### require(id) +### `require(id)` @@ -630,7 +631,7 @@ const jsonData = require('./path/filename.json'); const crypto = require('crypto'); ``` -#### require.cache +#### `require.cache` @@ -647,7 +648,7 @@ native modules and if a name matching a native module is added to the cache, no require call is going to receive the native module anymore. Use with care! -#### require.extensions +#### `require.extensions` @@ -710,7 +711,7 @@ Module { '/node_modules' ] } ``` -#### require.resolve(request\[, options\]) +#### `require.resolve(request[, options])` @@ -759,7 +760,7 @@ representing the current module. For convenience, `module.exports` is also accessible via the `exports` module-global. `module` is not actually a global but rather local to each module. -### module.children +### `module.children` @@ -768,7 +769,7 @@ added: v0.1.16 The module objects required for the first time by this one. -### module.exports +### `module.exports` @@ -822,7 +823,7 @@ const x = require('./x'); console.log(x.a); ``` -#### exports shortcut +#### `exports` shortcut @@ -869,7 +870,7 @@ function require(/* ... */) { } ``` -### module.filename +### `module.filename` @@ -878,7 +879,7 @@ added: v0.1.16 The fully resolved filename of the module. -### module.id +### `module.id` @@ -888,7 +889,7 @@ added: v0.1.16 The identifier for the module. Typically this is the fully resolved filename. -### module.loaded +### `module.loaded` @@ -898,7 +899,7 @@ added: v0.1.16 Whether or not the module is done loading, or is in the process of loading. -### module.parent +### `module.parent` @@ -907,7 +908,7 @@ added: v0.1.16 The module that first required this one. -### module.paths +### `module.paths` @@ -916,7 +917,7 @@ added: v0.4.0 The search paths for the module. -### module.require(id) +### `module.require(id)` @@ -944,7 +945,7 @@ Provides general utility methods when interacting with instances of `Module` — the `module` variable often seen in file modules. Accessed via `require('module')`. -### module.builtinModules +### `module.builtinModules` @@ -982,7 +983,7 @@ const require = createRequire(import.meta.url); const siblingModule = require('./sibling-module'); ``` -### module.createRequireFromPath(filename) +### `module.createRequireFromPath(filename)` diff --git a/doc/api/net.md b/doc/api/net.md index 7ec75e358f396a..13bcd60cf48e1c 100644 --- a/doc/api/net.md +++ b/doc/api/net.md @@ -55,7 +55,7 @@ net.createServer().listen( path.join('\\\\?\\pipe', process.cwd(), 'myctl')); ``` -## Class: net.Server +## Class: `net.Server` @@ -64,7 +64,7 @@ added: v0.1.90 This class is used to create a TCP or [IPC][] server. -### new net.Server(\[options\]\[, connectionListener\]) +### `new net.Server([options][, connectionListener])` * `options` {Object} See [`net.createServer([options][, connectionListener])`][`net.createServer()`]. @@ -74,7 +74,7 @@ This class is used to create a TCP or [IPC][] server. `net.Server` is an [`EventEmitter`][] with the following events: -### Event: 'close' +### Event: `'close'` @@ -82,7 +82,7 @@ added: v0.5.0 Emitted when the server closes. If connections exist, this event is not emitted until all connections are ended. -### Event: 'connection' +### Event: `'connection'` @@ -92,7 +92,7 @@ added: v0.1.90 Emitted when a new connection is made. `socket` is an instance of `net.Socket`. -### Event: 'error' +### Event: `'error'` @@ -104,14 +104,14 @@ event will **not** be emitted directly following this event unless [`server.close()`][] is manually called. See the example in discussion of [`server.listen()`][]. -### Event: 'listening' +### Event: `'listening'` Emitted when the server has been bound after calling [`server.listen()`][]. -### server.address() +### `server.address()` @@ -142,7 +142,7 @@ server.listen(() => { Don't call `server.address()` until the `'listening'` event has been emitted. -### server.close(\[callback\]) +### `server.close([callback])` @@ -157,7 +157,7 @@ The optional `callback` will be called once the `'close'` event occurs. Unlike that event, it will be called with an `Error` as its only argument if the server was not open when it was closed. -### server.connections +### `server.connections` @@ -186,7 +186,7 @@ when sockets were sent to forks. Callback should take two arguments `err` and `count`. -### server.listen() +### `server.listen()` Start a server listening for connections. A `net.Server` can be a TCP or an [IPC][] server depending on what it listens to. @@ -234,14 +234,14 @@ server.on('error', (e) => { }); ``` -#### server.listen(handle\[, backlog\]\[, callback\]) +#### `server.listen(handle[, backlog][, callback])` * `handle` {Object} * `backlog` {number} Common parameter of [`server.listen()`][] functions -* `callback` {Function} Common parameter of [`server.listen()`][] functions +* `callback` {Function} * Returns: {net.Server} Start a server listening for connections on a given `handle` that has @@ -253,7 +253,7 @@ valid file descriptor. Listening on a file descriptor is not supported on Windows. -#### server.listen(options\[, callback\]) +#### `server.listen(options[, callback])` @@ -314,12 +314,12 @@ added: v0.1.90 * `path` {string} Path the server should listen to. See [Identifying paths for IPC connections][]. * `backlog` {number} Common parameter of [`server.listen()`][] functions. -* `callback` {Function} Common parameter of [`server.listen()`][] functions. +* `callback` {Function}. * Returns: {net.Server} Start an [IPC][] server listening for connections on the given `path`. -#### server.listen(\[port\[, host\[, backlog\]\]\]\[, callback\]) +#### `server.listen([port[, host[, backlog]]][, callback])` @@ -327,7 +327,7 @@ added: v0.1.90 * `port` {number} * `host` {string} * `backlog` {number} Common parameter of [`server.listen()`][] functions. -* `callback` {Function} Common parameter of [`server.listen()`][] functions. +* `callback` {Function}. * Returns: {net.Server} Start a TCP server listening for connections on the given `port` and `host`. @@ -344,14 +344,14 @@ In most operating systems, listening to the [unspecified IPv6 address][] (`::`) may cause the `net.Server` to also listen on the [unspecified IPv4 address][] (`0.0.0.0`). -### server.listening +### `server.listening` * {boolean} Indicates whether or not the server is listening for connections. -### server.maxConnections +### `server.maxConnections` @@ -364,7 +364,7 @@ high. It is not recommended to use this option once a socket has been sent to a child with [`child_process.fork()`][]. -### server.ref() +### `server.ref()` @@ -375,7 +375,7 @@ Opposite of `unref()`, calling `ref()` on a previously `unref`ed server will *not* let the program exit if it's the only server left (the default behavior). If the server is `ref`ed calling `ref()` again will have no effect. -### server.unref() +### `server.unref()` @@ -386,7 +386,7 @@ Calling `unref()` on a server will allow the program to exit if this is the only active server in the event system. If the server is already `unref`ed calling `unref()` again will have no effect. -## Class: net.Socket +## Class: `net.Socket` @@ -406,7 +406,7 @@ is received. For example, it is passed to the listeners of a [`'connection'`][] event emitted on a [`net.Server`][], so the user can use it to interact with the client. -### new net.Socket(\[options\]) +### `new net.Socket([options])` @@ -428,7 +428,7 @@ Creates a new socket object. The newly created socket can be either a TCP socket or a streaming [IPC][] endpoint, depending on what it [`connect()`][`socket.connect()`] to. -### Event: 'close' +### Event: `'close'` @@ -438,7 +438,7 @@ added: v0.1.90 Emitted once the socket is fully closed. The argument `hadError` is a boolean which says if the socket was closed due to a transmission error. -### Event: 'connect' +### Event: `'connect'` @@ -446,7 +446,7 @@ added: v0.1.90 Emitted when a socket connection is successfully established. See [`net.createConnection()`][]. -### Event: 'data' +### Event: `'data'` @@ -459,7 +459,7 @@ Emitted when data is received. The argument `data` will be a `Buffer` or The data will be lost if there is no listener when a `Socket` emits a `'data'` event. -### Event: 'drain' +### Event: `'drain'` @@ -468,7 +468,7 @@ Emitted when the write buffer becomes empty. Can be used to throttle uploads. See also: the return values of `socket.write()`. -### Event: 'end' +### Event: `'end'` @@ -484,7 +484,7 @@ user to write arbitrary amounts of data. The user must call [`end()`][`socket.end()`] explicitly to close the connection (i.e. sending a FIN packet back). -### Event: 'error' +### Event: `'error'` @@ -494,7 +494,7 @@ added: v0.1.90 Emitted when an error occurs. The `'close'` event will be called directly following this event. -### Event: 'lookup' +### Event: `'lookup'` @@ -520,7 +520,7 @@ Emitted when a socket is ready to be used. Triggered immediately after `'connect'`. -### Event: 'timeout' +### Event: `'timeout'` @@ -530,7 +530,7 @@ the socket has been idle. The user must manually close the connection. See also: [`socket.setTimeout()`][]. -### socket.address() +### `socket.address()` @@ -541,7 +541,7 @@ Returns the bound `address`, the address `family` name and `port` of the socket as reported by the operating system: `{ port: 12346, family: 'IPv4', address: '127.0.0.1' }` -### socket.bufferSize +### `socket.bufferSize` @@ -563,7 +563,7 @@ Users who experience large or growing `bufferSize` should attempt to "throttle" the data flows in their program with [`socket.pause()`][] and [`socket.resume()`][]. -### socket.bytesRead +### `socket.bytesRead` @@ -572,7 +572,7 @@ added: v0.5.3 The amount of received bytes. -### socket.bytesWritten +### `socket.bytesWritten` @@ -581,7 +581,7 @@ added: v0.5.3 The amount of bytes sent. -### socket.connect() +### `socket.connect()` Initiate a connection on a given socket. @@ -601,7 +601,7 @@ the error passed to the [`'error'`][] listener. The last parameter `connectListener`, if supplied, will be added as a listener for the [`'connect'`][] event **once**. -#### socket.connect(options\[, connectListener\]) +#### `socket.connect(options[, connectListener])` @@ -708,7 +708,7 @@ Alias to [`socket.connect(options[, connectListener])`][`socket.connect(options)`] called with `{port: port, host: host}` as `options`. -### socket.connecting +### `socket.connecting` @@ -723,7 +723,7 @@ that the [`socket.connect(options[, connectListener])`][`socket.connect(options)`] callback is a listener for the `'connect'` event. -### socket.destroy(\[exception\]) +### `socket.destroy([exception])` @@ -737,12 +737,12 @@ case of errors (parse error or so). If `exception` is specified, an [`'error'`][] event will be emitted and any listeners for that event will receive `exception` as an argument. -### socket.destroyed +### `socket.destroyed` * {boolean} Indicates if the connection is destroyed or not. Once a connection is destroyed no further data can be transferred using it. -### socket.end(\[data\[, encoding\]\]\[, callback\]) +### `socket.end([data[, encoding]][, callback])` @@ -758,7 +758,7 @@ server will still send some data. If `data` is specified, it is equivalent to calling `socket.write(data, encoding)` followed by [`socket.end()`][]. -### socket.localAddress +### `socket.localAddress` @@ -770,7 +770,7 @@ connecting on. For example, in a server listening on `'0.0.0.0'`, if a client connects on `'192.168.1.1'`, the value of `socket.localAddress` would be `'192.168.1.1'`. -### socket.localPort +### `socket.localPort` @@ -779,14 +779,14 @@ added: v0.9.6 The numeric representation of the local port. For example, `80` or `21`. -### socket.pause() +### `socket.pause()` * Returns: {net.Socket} The socket itself. Pauses the reading of data. That is, [`'data'`][] events will not be emitted. Useful to throttle back an upload. -### socket.pending +### `socket.pending` @@ -797,7 +797,7 @@ This is `true` if the socket is not connected yet, either because `.connect()` has not yet been called or because it is still in the process of connecting (see [`socket.connecting`][]). -### socket.ref() +### `socket.ref()` @@ -808,7 +808,7 @@ Opposite of `unref()`, calling `ref()` on a previously `unref`ed socket will *not* let the program exit if it's the only socket left (the default behavior). If the socket is `ref`ed calling `ref` again will have no effect. -### socket.remoteAddress +### `socket.remoteAddress` @@ -819,7 +819,7 @@ The string representation of the remote IP address. For example, `'74.125.127.100'` or `'2001:4860:a005::68'`. Value may be `undefined` if the socket is destroyed (for example, if the client disconnected). -### socket.remoteFamily +### `socket.remoteFamily` @@ -828,7 +828,7 @@ added: v0.11.14 The string representation of the remote IP family. `'IPv4'` or `'IPv6'`. -### socket.remotePort +### `socket.remotePort` @@ -837,13 +837,13 @@ added: v0.5.10 The numeric representation of the remote port. For example, `80` or `21`. -### socket.resume() +### `socket.resume()` * Returns: {net.Socket} The socket itself. Resumes reading after a call to [`socket.pause()`][]. -### socket.setEncoding(\[encoding\]) +### `socket.setEncoding([encoding])` @@ -854,7 +854,7 @@ added: v0.1.90 Set the encoding for the socket as a [Readable Stream][]. See [`readable.setEncoding()`][] for more information. -### socket.setKeepAlive(\[enable\]\[, initialDelay\]) +### `socket.setKeepAlive([enable][, initialDelay])` @@ -871,7 +871,7 @@ data packet received and the first keepalive probe. Setting `0` for `initialDelay` will leave the value unchanged from the default (or previous) setting. -### socket.setNoDelay(\[noDelay\]) +### `socket.setNoDelay([noDelay])` @@ -883,7 +883,7 @@ Disables the Nagle algorithm. By default TCP connections use the Nagle algorithm, they buffer data before sending it off. Setting `true` for `noDelay` will immediately fire off data each time `socket.write()` is called. -### socket.setTimeout(timeout\[, callback\]) +### `socket.setTimeout(timeout[, callback])` @@ -912,7 +912,7 @@ If `timeout` is 0, then the existing idle timeout is disabled. The optional `callback` parameter will be added as a one-time listener for the [`'timeout'`][] event. -### socket.unref() +### `socket.unref()` @@ -923,7 +923,7 @@ Calling `unref()` on a socket will allow the program to exit if this is the only active socket in the event system. If the socket is already `unref`ed calling `unref()` again will have no effect. -### socket.write(data\[, encoding\]\[, callback\]) +### `socket.write(data[, encoding][, callback])` @@ -946,7 +946,7 @@ written out, which may not be immediately. See `Writable` stream [`write()`][stream_writable_write] method for more information. -## net.connect() +## `net.connect()` Aliases to [`net.createConnection()`][`net.createConnection()`]. @@ -959,7 +959,7 @@ Possible signatures: * [`net.connect(port[, host][, connectListener])`][`net.connect(port, host)`] for TCP connections. -### net.connect(options\[, connectListener\]) +### `net.connect(options[, connectListener])` @@ -971,7 +971,7 @@ added: v0.7.0 Alias to [`net.createConnection(options[, connectListener])`][`net.createConnection(options)`]. -### net.connect(path\[, connectListener\]) +### `net.connect(path[, connectListener])` @@ -983,7 +983,7 @@ added: v0.1.90 Alias to [`net.createConnection(path[, connectListener])`][`net.createConnection(path)`]. -### net.connect(port\[, host\]\[, connectListener\]) +### `net.connect(port[, host][, connectListener])` @@ -996,7 +996,7 @@ added: v0.1.90 Alias to [`net.createConnection(port[, host][, connectListener])`][`net.createConnection(port, host)`]. -## net.createConnection() +## `net.createConnection()` A factory function, which creates a new [`net.Socket`][], immediately initiates connection with [`socket.connect()`][], @@ -1016,7 +1016,7 @@ Possible signatures: The [`net.connect()`][] function is an alias to this function. -### net.createConnection(options\[, connectListener\]) +### `net.createConnection(options[, connectListener])` @@ -1066,7 +1066,7 @@ changed to: const client = net.createConnection({ path: '/tmp/echo.sock' }); ``` -### net.createConnection(path\[, connectListener\]) +### `net.createConnection(path[, connectListener])` @@ -1087,7 +1087,7 @@ immediately initiates connection with [`socket.connect(path[, connectListener])`][`socket.connect(path)`], then returns the `net.Socket` that starts the connection. -### net.createConnection(port\[, host\]\[, connectListener\]) +### `net.createConnection(port[, host][, connectListener])` @@ -1110,7 +1110,7 @@ immediately initiates connection with [`socket.connect(port[, host][, connectListener])`][`socket.connect(port, host)`], then returns the `net.Socket` that starts the connection. -## net.createServer(\[options\]\[, connectionListener\]) +## `net.createServer([options][, connectionListener])` @@ -1184,7 +1184,7 @@ Use `nc` to connect to a Unix domain socket server: $ nc -U /tmp/echo.sock ``` -## net.isIP(input) +## `net.isIP(input)` @@ -1196,7 +1196,7 @@ Tests if input is an IP address. Returns `0` for invalid strings, returns `4` for IP version 4 addresses, and returns `6` for IP version 6 addresses. -## net.isIPv4(input) +## `net.isIPv4(input)` @@ -1206,7 +1206,7 @@ added: v0.3.0 Returns `true` if input is a version 4 IP address, otherwise returns `false`. -## net.isIPv6(input) +## `net.isIPv6(input)` diff --git a/doc/api/os.md b/doc/api/os.md index b7eccda6786897..baa98406e4f657 100644 --- a/doc/api/os.md +++ b/doc/api/os.md @@ -11,7 +11,7 @@ properties. It can be accessed using: const os = require('os'); ``` -## os.EOL +## `os.EOL` @@ -23,7 +23,7 @@ The operating system-specific end-of-line marker. * `\n` on POSIX * `\r\n` on Windows -## os.arch() +## `os.arch()` @@ -36,7 +36,7 @@ compiled. Possible values are `'arm'`, `'arm64'`, `'ia32'`, `'mips'`, The return value is equivalent to [`process.arch`][]. -## os.constants +## `os.constants` @@ -47,7 +47,7 @@ Contains commonly used operating system-specific constants for error codes, process signals, and so on. The specific constants defined are described in [OS Constants](#os_os_constants_1). -## os.cpus() +## `os.cpus()` @@ -120,7 +120,7 @@ The properties included on each object include: `nice` values are POSIX-only. On Windows, the `nice` values of all processors are always 0. -## os.endianness() +## `os.endianness()` @@ -132,7 +132,7 @@ binary was compiled. Possible values are `'BE'` for big endian and `'LE'` for little endian. -## os.freemem() +## `os.freemem()` @@ -141,7 +141,7 @@ added: v0.3.3 Returns the amount of free system memory in bytes as an integer. -## os.getPriority(\[pid\]) +## `os.getPriority([pid])` @@ -153,7 +153,7 @@ added: v10.10.0 Returns the scheduling priority for the process specified by `pid`. If `pid` is not provided or is `0`, the priority of the current process is returned. -## os.homedir() +## `os.homedir()` @@ -168,7 +168,7 @@ uses the [effective UID][EUID] to look up the user's home directory. On Windows, it uses the `USERPROFILE` environment variable if defined. Otherwise it uses the path to the profile directory of the current user. -## os.hostname() +## `os.hostname()` @@ -177,7 +177,7 @@ added: v0.3.3 Returns the hostname of the operating system as a string. -## os.loadavg() +## `os.loadavg()` @@ -192,7 +192,7 @@ system and expressed as a fractional number. The load average is a Unix-specific concept. On Windows, the return value is always `[0, 0, 0]`. -## os.networkInterfaces() +## `os.networkInterfaces()` @@ -263,7 +263,7 @@ The properties available on the assigned network address object include: } ``` -## os.platform() +## `os.platform()` @@ -279,7 +279,7 @@ The return value is equivalent to [`process.platform`][]. The value `'android'` may also be returned if Node.js is built on the Android operating system. [Android support is experimental][Android building]. -## os.release() +## `os.release()` @@ -292,7 +292,7 @@ On POSIX systems, the operating system release is determined by calling [uname(3)][]. On Windows, `GetVersionExW()` is used. See https://en.wikipedia.org/wiki/Uname#Examples for more information. -## os.setPriority(\[pid, \]priority) +## `os.setPriority([pid, ]priority)` @@ -315,7 +315,7 @@ On Windows, setting priority to `PRIORITY_HIGHEST` requires elevated user privileges. Otherwise the set priority will be silently reduced to `PRIORITY_HIGH`. -## os.tmpdir() +## `os.tmpdir()` @@ -339,7 +339,7 @@ added: v0.3.3 Returns the total amount of system memory in bytes as an integer. -## os.type() +## `os.type()` @@ -352,7 +352,7 @@ returns `'Linux'` on Linux, `'Darwin'` on macOS, and `'Windows_NT'` on Windows. See https://en.wikipedia.org/wiki/Uname#Examples for additional information about the output of running [uname(3)][] on various operating systems. -## os.uptime() +## `os.uptime()` diff --git a/doc/api/path.md b/doc/api/path.md index e752d7d6883f72..e4b41605406bb0 100644 --- a/doc/api/path.md +++ b/doc/api/path.md @@ -60,7 +60,7 @@ example, `path.resolve('c:\\')` can potentially return a different result than `path.resolve('c:')`. For more information, see [this MSDN page][MSDN-Rel-Path]. -## path.basename(path\[, ext\]) +## `path.basename(path[, ext])` @@ -120,7 +120,7 @@ process.env.PATH.split(path.delimiter); // Returns ['C:\\Windows\\system32', 'C:\\Windows', 'C:\\Program Files\\node\\'] ``` -## path.dirname(path) +## `path.dirname(path)` @@ -247,7 +247,7 @@ path.format({ // Returns: 'C:\\path\\dir\\file.txt' ``` -## path.isAbsolute(path) +## `path.isAbsolute(path)` @@ -282,7 +282,7 @@ path.isAbsolute('.'); // false A [`TypeError`][] is thrown if `path` is not a string. -## path.join(\[...paths\]) +## `path.join([...paths])` @@ -307,7 +307,7 @@ path.join('foo', {}, 'bar'); A [`TypeError`][] is thrown if any of the path segments is not a string. -## path.normalize(path) +## `path.normalize(path)` @@ -350,7 +350,7 @@ path.win32.normalize('C:////temp\\\\/\\/\\/foo/bar'); A [`TypeError`][] is thrown if `path` is not a string. -## path.parse(path) +## `path.parse(path)` @@ -416,7 +416,7 @@ path.parse('C:\\path\\dir\\file.txt'); A [`TypeError`][] is thrown if `path` is not a string. -## path.posix +## `path.posix` @@ -426,7 +426,7 @@ added: v0.11.15 The `path.posix` property provides access to POSIX specific implementations of the `path` methods. -## path.relative(from, to) +## `path.relative(from, to)` @@ -504,7 +504,7 @@ path.resolve('wwwroot', 'static_files/png/', '../gif/image.gif'); A [`TypeError`][] is thrown if any of the arguments is not a string. -## path.sep +## `path.sep` @@ -534,7 +534,7 @@ On Windows, both the forward slash (`/`) and backward slash (`\`) are accepted as path segment separators; however, the `path` methods only add backward slashes (`\`). -## path.toNamespacedPath(path) +## `path.toNamespacedPath(path)` @@ -549,7 +549,7 @@ modifications. This method is meaningful only on Windows system. On POSIX systems, the method is non-operational and always returns `path` without modifications. -## path.win32 +## `path.win32` diff --git a/doc/api/perf_hooks.md b/doc/api/perf_hooks.md index 1ccf3ee37578e3..02dee38bae1987 100644 --- a/doc/api/perf_hooks.md +++ b/doc/api/perf_hooks.md @@ -2,7 +2,7 @@ -> Stability: 1 - Experimental +> Stability: 2 - Stable The Performance Timing API provides an implementation of the [W3C Performance Timeline][] specification. The purpose of the API @@ -25,12 +25,12 @@ doSomeLongRunningProcess(() => { }); ``` -## Class: Performance +## Class: `Performance` -### performance.clearMarks(\[name\]) +### `performance.clearMarks([name])` @@ -40,7 +40,7 @@ added: v8.5.0 If `name` is not provided, removes all `PerformanceMark` objects from the Performance Timeline. If `name` is provided, removes only the named mark. -### performance.mark(\[name\]) +### `performance.mark([name])` @@ -53,7 +53,7 @@ Creates a new `PerformanceMark` entry in the Performance Timeline. A `performanceEntry.duration` is always `0`. Performance marks are used to mark specific significant moments in the Performance Timeline. -### performance.measure(name, startMark, endMark) +### `performance.measure(name, startMark, endMark)` @@ -78,7 +78,7 @@ Performance Timeline or any of the timestamp properties provided by the `PerformanceNodeTiming` class. If the named `endMark` does not exist, an error will be thrown. -### performance.nodeTiming +### `performance.nodeTiming` @@ -88,7 +88,7 @@ added: v8.5.0 An instance of the `PerformanceNodeTiming` class that provides performance metrics for specific Node.js operational milestones. -### performance.now() +### `performance.now()` @@ -98,7 +98,7 @@ added: v8.5.0 Returns the current high resolution millisecond timestamp, where 0 represents the start of the current `node` process. -### performance.timeOrigin +### `performance.timeOrigin` @@ -108,7 +108,7 @@ added: v8.5.0 The [`timeOrigin`][] specifies the high resolution millisecond timestamp at which the current `node` process began, measured in Unix time. -### performance.timerify(fn) +### `performance.timerify(fn)` @@ -141,12 +141,12 @@ obs.observe({ entryTypes: ['function'] }); wrapped(); ``` -## Class: PerformanceEntry +## Class: `PerformanceEntry` -### performanceEntry.duration +### `performanceEntry.duration` @@ -156,7 +156,7 @@ added: v8.5.0 The total number of milliseconds elapsed for this entry. This value will not be meaningful for all Performance Entry types. -### performanceEntry.name +### `performanceEntry.name` @@ -165,7 +165,7 @@ added: v8.5.0 The name of the performance entry. -### performanceEntry.startTime +### `performanceEntry.startTime` @@ -175,7 +175,7 @@ added: v8.5.0 The high resolution millisecond timestamp marking the starting time of the Performance Entry. -### performanceEntry.entryType +### `performanceEntry.entryType` @@ -185,7 +185,7 @@ added: v8.5.0 The type of the performance entry. Currently it may be one of: `'node'`, `'mark'`, `'measure'`, `'gc'`, `'function'`, `'http2'` or `'http'`. -### performanceEntry.kind +### `performanceEntry.kind` @@ -201,14 +201,14 @@ The value may be one of: * `perf_hooks.constants.NODE_PERFORMANCE_GC_INCREMENTAL` * `perf_hooks.constants.NODE_PERFORMANCE_GC_WEAKCB` -## Class: PerformanceNodeTiming extends PerformanceEntry +## Class: `PerformanceNodeTiming extends PerformanceEntry` Provides timing details for Node.js itself. -### performanceNodeTiming.bootstrapComplete +### `performanceNodeTiming.bootstrapComplete` @@ -219,7 +219,7 @@ The high resolution millisecond timestamp at which the Node.js process completed bootstrapping. If bootstrapping has not yet finished, the property has the value of -1. -### performanceNodeTiming.environment +### `performanceNodeTiming.environment` @@ -229,7 +229,7 @@ added: v8.5.0 The high resolution millisecond timestamp at which the Node.js environment was initialized. -### performanceNodeTiming.loopExit +### `performanceNodeTiming.loopExit` @@ -240,7 +240,7 @@ The high resolution millisecond timestamp at which the Node.js event loop exited. If the event loop has not yet exited, the property has the value of -1. It can only have a value of not -1 in a handler of the [`'exit'`][] event. -### performanceNodeTiming.loopStart +### `performanceNodeTiming.loopStart` @@ -251,7 +251,7 @@ The high resolution millisecond timestamp at which the Node.js event loop started. If the event loop has not yet started (e.g., in the first tick of the main script), the property has the value of -1. -### performanceNodeTiming.nodeStart +### `performanceNodeTiming.nodeStart` @@ -261,7 +261,7 @@ added: v8.5.0 The high resolution millisecond timestamp at which the Node.js process was initialized. -### performanceNodeTiming.v8Start +### `performanceNodeTiming.v8Start` @@ -271,9 +271,9 @@ added: v8.5.0 The high resolution millisecond timestamp at which the V8 platform was initialized. -## Class: PerformanceObserver +## Class: `PerformanceObserver` -### new PerformanceObserver(callback) +### `new PerformanceObserver(callback)` @@ -310,13 +310,13 @@ notified about new `PerformanceEntry` instances. The callback receives a `PerformanceObserverEntryList` instance and a reference to the `PerformanceObserver`. -### performanceObserver.disconnect() +### `performanceObserver.disconnect()` Disconnects the `PerformanceObserver` instance from all notifications. -### performanceObserver.observe(options) +### `performanceObserver.observe(options)` @@ -366,7 +366,7 @@ for (let n = 0; n < 3; n++) performance.mark(`test${n}`); ``` -## Class: PerformanceObserverEntryList +## Class: `PerformanceObserverEntryList` @@ -374,7 +374,7 @@ added: v8.5.0 The `PerformanceObserverEntryList` class is used to provide access to the `PerformanceEntry` instances passed to a `PerformanceObserver`. -### performanceObserverEntryList.getEntries() +### `performanceObserverEntryList.getEntries()` @@ -384,7 +384,7 @@ added: v8.5.0 Returns a list of `PerformanceEntry` objects in chronological order with respect to `performanceEntry.startTime`. -### performanceObserverEntryList.getEntriesByName(name\[, type\]) +### `performanceObserverEntryList.getEntriesByName(name[, type])` @@ -398,7 +398,7 @@ with respect to `performanceEntry.startTime` whose `performanceEntry.name` is equal to `name`, and optionally, whose `performanceEntry.entryType` is equal to `type`. -### performanceObserverEntryList.getEntriesByType(type) +### `performanceObserverEntryList.getEntriesByType(type)` @@ -410,7 +410,7 @@ Returns a list of `PerformanceEntry` objects in chronological order with respect to `performanceEntry.startTime` whose `performanceEntry.entryType` is equal to `type`. -## perf_hooks.monitorEventLoopDelay(\[options\]) +## `perf_hooks.monitorEventLoopDelay([options])` @@ -444,13 +444,13 @@ console.log(h.percentile(50)); console.log(h.percentile(99)); ``` -### Class: Histogram +### Class: `Histogram` Tracks the event loop delay at a given sampling rate. -#### histogram.disable() +#### `histogram.disable()` @@ -460,7 +460,7 @@ added: v11.10.0 Disables the event loop delay sample timer. Returns `true` if the timer was stopped, `false` if it was already stopped. -#### histogram.enable() +#### `histogram.enable()` @@ -470,7 +470,7 @@ added: v11.10.0 Enables the event loop delay sample timer. Returns `true` if the timer was started, `false` if it was already started. -#### histogram.exceeds +#### `histogram.exceeds` @@ -480,7 +480,7 @@ added: v11.10.0 The number of times the event loop delay exceeded the maximum 1 hour event loop delay threshold. -#### histogram.max +#### `histogram.max` @@ -489,7 +489,7 @@ added: v11.10.0 The maximum recorded event loop delay. -#### histogram.mean +#### `histogram.mean` @@ -498,7 +498,7 @@ added: v11.10.0 The mean of the recorded event loop delays. -#### histogram.min +#### `histogram.min` @@ -507,7 +507,7 @@ added: v11.10.0 The minimum recorded event loop delay. -#### histogram.percentile(percentile) +#### `histogram.percentile(percentile)` @@ -517,7 +517,7 @@ added: v11.10.0 Returns the value at the given percentile. -#### histogram.percentiles +#### `histogram.percentiles` @@ -526,14 +526,14 @@ added: v11.10.0 Returns a `Map` object detailing the accumulated percentile distribution. -#### histogram.reset() +#### `histogram.reset()` Resets the collected histogram data. -#### histogram.stddev +#### `histogram.stddev` diff --git a/doc/api/process.md b/doc/api/process.md index 217fbb66bc0f9b..f5d81878cfe4d3 100644 --- a/doc/api/process.md +++ b/doc/api/process.md @@ -16,7 +16,7 @@ const process = require('process'); The `process` object is an instance of [`EventEmitter`][]. -### Event: 'beforeExit' +### Event: `'beforeExit'` @@ -53,7 +53,7 @@ console.log('This message is displayed first.'); // Process exit event with code: 0 ``` -### Event: 'disconnect' +### Event: `'disconnect'` @@ -62,7 +62,7 @@ If the Node.js process is spawned with an IPC channel (see the [Child Process][] and [Cluster][] documentation), the `'disconnect'` event will be emitted when the IPC channel is closed. -### Event: 'exit' +### Event: `'exit'` @@ -101,7 +101,7 @@ process.on('exit', (code) => { }); ``` -### Event: 'message' +### Event: `'message'` @@ -124,7 +124,7 @@ process, the `message` argument can contain data that JSON is not able to represent. See [Advanced Serialization for `child_process`][] for more details. -### Event: 'multipleResolves' +### Event: `'multipleResolves'` @@ -173,7 +173,7 @@ main().then(console.log); // First call ``` -### Event: 'rejectionHandled' +### Event: `'rejectionHandled'` @@ -220,7 +220,7 @@ possible to record such errors in an error log, either periodically (which is likely best for long-running application) or upon process exit (which is likely most convenient for scripts). -### Event: 'uncaughtException' +### Event: `'uncaughtException'` @@ -429,6 +429,8 @@ Signal events will be emitted when the Node.js process receives a signal. Please refer to signal(7) for a listing of standard POSIX signal names such as `'SIGINT'`, `'SIGHUP'`, etc. +Signals are not available on [`Worker`][] threads. + The signal handler will receive the signal's name (`'SIGINT'`, `'SIGTERM'`, etc.) as the first argument. @@ -490,7 +492,7 @@ with [`process.kill()`][], and [`subprocess.kill()`][]. Sending signal `0` can be used to test for the existence of a process. Sending `SIGINT`, `SIGTERM`, and `SIGKILL` cause the unconditional termination of the target process. -## process.abort() +## `process.abort()` @@ -500,7 +502,7 @@ generate a core file. This feature is not available in [`Worker`][] threads. -## process.allowedNodeEnvironmentFlags +## `process.allowedNodeEnvironmentFlags` @@ -549,7 +551,7 @@ If Node.js was compiled *without* [`NODE_OPTIONS`][] support (shown in [`process.config`][]), `process.allowedNodeEnvironmentFlags` will contain what *would have* been allowable. -## process.arch +## `process.arch` @@ -564,7 +566,7 @@ Possible values are: `'arm'`, `'arm64'`, `'ia32'`, `'mips'`,`'mipsel'`, `'ppc'`, console.log(`This processor architecture is ${process.arch}`); ``` -## process.argv +## `process.argv` @@ -603,7 +605,7 @@ Would generate the output: 4: four ``` -## process.argv0 +## `process.argv0` @@ -621,7 +623,7 @@ $ bash -c 'exec -a customArgv0 ./node' 'customArgv0' ``` -## process.channel +## `process.channel` @@ -633,7 +635,7 @@ If the Node.js process was spawned with an IPC channel (see the property is a reference to the IPC channel. If no IPC channel exists, this property is `undefined`. -## process.chdir(directory) +## `process.chdir(directory)` @@ -656,7 +658,7 @@ try { This feature is not available in [`Worker`][] threads. -## process.config +## `process.config` @@ -703,7 +705,7 @@ The `process.config` property is **not** read-only and there are existing modules in the ecosystem that are known to extend, modify, or entirely replace the value of `process.config`. -## process.connected +## `process.connected` @@ -718,7 +720,7 @@ and [Cluster][] documentation), the `process.connected` property will return Once `process.connected` is `false`, it is no longer possible to send messages over the IPC channel using `process.send()`. -## process.cpuUsage(\[previousValue\]) +## `process.cpuUsage([previousValue])` @@ -750,7 +752,7 @@ console.log(process.cpuUsage(startUsage)); // { user: 514883, system: 11226 } ``` -## process.cwd() +## `process.cwd()` @@ -764,7 +766,7 @@ process. console.log(`Current directory: ${process.cwd()}`); ``` -## process.debugPort +## `process.debugPort` @@ -777,7 +779,7 @@ The port used by Node.js's debugger when enabled. process.debugPort = 5858; ``` -## process.disconnect() +## `process.disconnect()` @@ -793,7 +795,7 @@ The effect of calling `process.disconnect()` is the same as calling If the Node.js process was not spawned with an IPC channel, `process.disconnect()` will be `undefined`. -## process.dlopen(module, filename\[, flags\]) +## `process.dlopen(module, filename[, flags])` @@ -881,7 +883,7 @@ process.on('warning', (warning) => { If `warning` is passed as an `Error` object, the `options` argument is ignored. -## process.emitWarning(warning\[, type\[, code\]\]\[, ctor\]) +## `process.emitWarning(warning[, type[, code]][, ctor])` @@ -978,7 +980,7 @@ emitMyWarning(); // Emits nothing ``` -## process.env +## `process.env` @@ -1100,7 +1102,7 @@ And `process.argv`: ['/usr/local/bin/node', 'script.js', '--version'] ``` -## process.execPath +## `process.execPath` @@ -1115,7 +1117,7 @@ that started the Node.js process. '/usr/local/bin/node' ``` -## process.exit(\[code\]) +## `process.exit([code])` @@ -1183,7 +1185,7 @@ is safer than calling `process.exit()`. In [`Worker`][] threads, this function stops the current thread rather than the current process. -## process.exitCode +## `process.exitCode` @@ -1197,7 +1199,7 @@ a code. Specifying a code to [`process.exit(code)`][`process.exit()`] will override any previous setting of `process.exitCode`. -## process.getegid() +## `process.getegid()` @@ -1214,7 +1216,7 @@ if (process.getegid) { This function is only available on POSIX platforms (i.e. not Windows or Android). -## process.geteuid() +## `process.geteuid()` @@ -1233,7 +1235,7 @@ if (process.geteuid) { This function is only available on POSIX platforms (i.e. not Windows or Android). -## process.getgid() +## `process.getgid()` @@ -1252,7 +1254,7 @@ if (process.getgid) { This function is only available on POSIX platforms (i.e. not Windows or Android). -## process.getgroups() +## `process.getgroups()` @@ -1266,7 +1268,7 @@ Node.js ensures it always is. This function is only available on POSIX platforms (i.e. not Windows or Android). -## process.getuid() +## `process.getuid()` @@ -1285,7 +1287,7 @@ if (process.getuid) { This function is only available on POSIX platforms (i.e. not Windows or Android). -## process.hasUncaughtExceptionCaptureCallback() +## `process.hasUncaughtExceptionCaptureCallback()` @@ -1295,7 +1297,7 @@ added: v9.3.0 Indicates whether a callback has been set using [`process.setUncaughtExceptionCaptureCallback()`][]. -## process.hrtime(\[time\]) +## `process.hrtime([time])` @@ -1334,7 +1336,7 @@ setTimeout(() => { }, 1000); ``` -## process.hrtime.bigint() +## `process.hrtime.bigint()` @@ -1361,7 +1363,7 @@ setTimeout(() => { }, 1000); ``` -## process.initgroups(user, extraGroup) +## `process.initgroups(user, extraGroup)` @@ -1388,7 +1390,7 @@ This function is only available on POSIX platforms (i.e. not Windows or Android). This feature is not available in [`Worker`][] threads. -## process.kill(pid\[, signal\]) +## `process.kill(pid[, signal])` @@ -1428,7 +1430,7 @@ process.kill(process.pid, 'SIGHUP'); When `SIGUSR1` is received by a Node.js process, Node.js will start the debugger. See [Signal Events][]. -## process.mainModule +## `process.mainModule` @@ -1444,7 +1446,7 @@ safe to assume that the two refer to the same module. As with [`require.main`][], `process.mainModule` will be `undefined` if there is no entry script. -## process.memoryUsage() +## `process.memoryUsage()` @@ -1597,7 +1599,7 @@ the [`'warning'` event][process_warning] and the [`emitWarning()` method][process_emit_warning] for more information about this flag's behavior. -## process.pid +## `process.pid` @@ -1610,7 +1612,7 @@ The `process.pid` property returns the PID of the process. console.log(`This process is pid ${process.pid}`); ``` -## process.platform +## `process.platform` @@ -1638,7 +1640,7 @@ The value `'android'` may also be returned if the Node.js is built on the Android operating system. However, Android support in Node.js [is experimental][Android building]. -## process.ppid +## `process.ppid` @@ -1718,7 +1720,7 @@ added: v11.8.0 reports for the current process. Additional documentation is available in the [report documentation][]. -### process.report.directory +### `process.report.directory` @@ -1735,7 +1737,7 @@ Node.js process. console.log(`Report directory is ${process.report.directory}`); ``` -### process.report.filename +### `process.report.filename` @@ -1752,7 +1754,7 @@ value is the empty string. console.log(`Report filename is ${process.report.filename}`); ``` -### process.report.getReport(\[err\]) +### `process.report.getReport([err])` @@ -1777,7 +1779,7 @@ fs.writeFileSync(util.inspect(data), 'my-report.log', 'utf8'); Additional documentation is available in the [report documentation][]. -### process.report.reportOnFatalError +### `process.report.reportOnFatalError` @@ -1793,7 +1795,7 @@ memory errors or failed C++ assertions. console.log(`Report on fatal error: ${process.report.reportOnFatalError}`); ``` -### process.report.reportOnSignal +### `process.report.reportOnSignal` @@ -1809,7 +1811,7 @@ signal specified by `process.report.signal`. console.log(`Report on signal: ${process.report.reportOnSignal}`); ``` -### process.report.reportOnUncaughtException +### `process.report.reportOnUncaughtException` @@ -1824,7 +1826,7 @@ If `true`, a diagnostic report is generated on uncaught exception. console.log(`Report on exception: ${process.report.reportOnUncaughtException}`); ``` -### process.report.signal +### `process.report.signal` @@ -1840,7 +1842,7 @@ The signal used to trigger the creation of a diagnostic report. Defaults to console.log(`Report signal: ${process.report.signal}`); ``` -### process.report.writeReport(\[filename\]\[, err\]) +### `process.report.writeReport([filename][, err])` @@ -1865,7 +1867,7 @@ process.report.writeReport(); Additional documentation is available in the [report documentation][]. -## process.resourceUsage() +## `process.resourceUsage()` @@ -1938,7 +1940,7 @@ console.log(process.resourceUsage()); */ ``` -## process.send(message\[, sendHandle\[, options\]\]\[, callback\]) +## `process.send(message[, sendHandle[, options]][, callback])` @@ -1963,7 +1965,7 @@ If Node.js was not spawned with an IPC channel, `process.send` will be The message goes through serialization and parsing. The resulting message might not be the same as what is originally sent. -## process.setegid(id) +## `process.setegid(id)` @@ -1991,7 +1993,7 @@ This function is only available on POSIX platforms (i.e. not Windows or Android). This feature is not available in [`Worker`][] threads. -## process.seteuid(id) +## `process.seteuid(id)` @@ -2019,7 +2021,7 @@ This function is only available on POSIX platforms (i.e. not Windows or Android). This feature is not available in [`Worker`][] threads. -## process.setgid(id) +## `process.setgid(id)` @@ -2047,7 +2049,7 @@ This function is only available on POSIX platforms (i.e. not Windows or Android). This feature is not available in [`Worker`][] threads. -## process.setgroups(groups) +## `process.setgroups(groups)` @@ -2064,7 +2066,7 @@ This function is only available on POSIX platforms (i.e. not Windows or Android). This feature is not available in [`Worker`][] threads. -## process.setuid(id) +## `process.setuid(id)` @@ -2092,7 +2094,7 @@ This function is only available on POSIX platforms (i.e. not Windows or Android). This feature is not available in [`Worker`][] threads. -## process.setUncaughtExceptionCaptureCallback(fn) +## `process.setUncaughtExceptionCaptureCallback(fn)` @@ -2116,7 +2118,7 @@ throw an error. Using this function is mutually exclusive with using the deprecated [`domain`][] built-in module. -## process.stderr +## `process.stderr` * {Stream} @@ -2128,7 +2130,7 @@ a [Writable][] stream. `process.stderr` differs from other Node.js streams in important ways. See [note on process I/O][] for more information. -## process.stdin +## `process.stdin` * {Stream} @@ -2161,7 +2163,7 @@ In "old" streams mode the `stdin` stream is paused by default, so one must call `process.stdin.resume()` to read from it. Note also that calling `process.stdin.resume()` itself would switch stream to "old" mode. -## process.stdout +## `process.stdout` * {Stream} @@ -2227,7 +2229,7 @@ false See the [TTY][] documentation for more information. -## process.throwDeprecation +## `process.throwDeprecation` @@ -2257,7 +2259,7 @@ Thrown: [DeprecationWarning: test] { name: 'DeprecationWarning' } ``` -## process.title +## `process.title` @@ -2277,7 +2279,7 @@ allowed for longer process title strings by also overwriting the `environ` memory but that was potentially insecure and confusing in some (rather obscure) cases. -## process.traceDeprecation +## `process.traceDeprecation` @@ -2290,12 +2292,12 @@ documentation for the [`'warning'` event][process_warning] and the [`emitWarning()` method][process_emit_warning] for more information about this flag's behavior. -## process.umask(\[mask\]) +## `process.umask([mask])` -* `mask` {number} +* `mask` {string|integer} The `process.umask()` method sets or returns the Node.js process's file mode creation mask. Child processes inherit the mask from the parent process. Invoked @@ -2313,7 +2315,7 @@ console.log( [`Worker`][] threads are able to read the umask, however attempting to set the umask will result in a thrown exception. -## process.uptime() +## `process.uptime()` @@ -2326,7 +2328,7 @@ process has been running. The return value includes fractions of a second. Use `Math.floor()` to get whole seconds. -## process.version +## `process.version` @@ -2339,7 +2341,7 @@ The `process.version` property returns the Node.js version string. console.log(`Version: ${process.version}`); ``` -## process.versions +## `process.versions` @@ -52,7 +52,7 @@ punycode.decode('maana-pta'); // 'mañana' punycode.decode('--dqo34k'); // '☃-⌘' ``` -## punycode.encode(string) +## `punycode.encode(string)` @@ -67,7 +67,7 @@ punycode.encode('mañana'); // 'maana-pta' punycode.encode('☃-⌘'); // '--dqo34k' ``` -## punycode.toASCII(domain) +## `punycode.toASCII(domain)` @@ -86,7 +86,7 @@ punycode.toASCII('☃-⌘.com'); // 'xn----dqo34k.com' punycode.toASCII('example.com'); // 'example.com' ``` -## punycode.toUnicode(domain) +## `punycode.toUnicode(domain)` @@ -104,12 +104,12 @@ punycode.toUnicode('xn----dqo34k.com'); // '☃-⌘.com' punycode.toUnicode('example.com'); // 'example.com' ``` -## punycode.ucs2 +## `punycode.ucs2` -### punycode.ucs2.decode(string) +### `punycode.ucs2.decode(string)` @@ -125,7 +125,7 @@ punycode.ucs2.decode('abc'); // [0x61, 0x62, 0x63] punycode.ucs2.decode('\uD834\uDF06'); // [0x1D306] ``` -### punycode.ucs2.encode(codePoints) +### `punycode.ucs2.encode(codePoints)` @@ -140,7 +140,7 @@ punycode.ucs2.encode([0x61, 0x62, 0x63]); // 'abc' punycode.ucs2.encode([0x1D306]); // '\uD834\uDF06' ``` -## punycode.version +## `punycode.version` diff --git a/doc/api/querystring.md b/doc/api/querystring.md index 383b162ee260b8..c7fafd23d955b8 100644 --- a/doc/api/querystring.md +++ b/doc/api/querystring.md @@ -13,21 +13,21 @@ query strings. It can be accessed using: const querystring = require('querystring'); ``` -## querystring.decode() +## `querystring.decode()` The `querystring.decode()` function is an alias for `querystring.parse()`. -## querystring.encode() +## `querystring.encode()` The `querystring.encode()` function is an alias for `querystring.stringify()`. -## querystring.escape(str) +## `querystring.escape(str)` @@ -43,7 +43,7 @@ generally not expected to be used directly. It is exported primarily to allow application code to provide a replacement percent-encoding implementation if necessary by assigning `querystring.escape` to an alternative function. -## querystring.parse(str\[, sep\[, eq\[, options\]\]\]) +## `querystring.parse(str[, sep[, eq[, options]]])` @@ -140,7 +140,7 @@ querystring.stringify({ w: '中文', foo: 'bar' }, null, null, { encodeURIComponent: gbkEncodeURIComponent }); ``` -## querystring.unescape(str) +## `querystring.unescape(str)` diff --git a/doc/api/readline.md b/doc/api/readline.md index b98f7055045ef1..cbb844886d6647 100644 --- a/doc/api/readline.md +++ b/doc/api/readline.md @@ -34,7 +34,7 @@ Once this code is invoked, the Node.js application will not terminate until the `readline.Interface` is closed because the interface waits for data to be received on the `input` stream. -## Class: Interface +## Class: `Interface` @@ -47,7 +47,7 @@ single `input` [Readable][] stream and a single `output` [Writable][] stream. The `output` stream is used to print prompts for user input that arrives on, and is read from, the `input` stream. -### Event: 'close' +### Event: `'close'` @@ -66,7 +66,7 @@ The listener function is called without passing any arguments. The `readline.Interface` instance is finished once the `'close'` event is emitted. -### Event: 'line' +### Event: `'line'` @@ -84,7 +84,7 @@ rl.on('line', (input) => { }); ``` -### Event: 'pause' +### Event: `'pause'` @@ -103,7 +103,7 @@ rl.on('pause', () => { }); ``` -### Event: 'resume' +### Event: `'resume'` @@ -118,7 +118,7 @@ rl.on('resume', () => { }); ``` -### Event: 'SIGCONT' +### Event: `'SIGCONT'` @@ -141,7 +141,7 @@ rl.on('SIGCONT', () => { The `'SIGCONT'` event is _not_ supported on Windows. -### Event: 'SIGINT' +### Event: `'SIGINT'` @@ -161,7 +161,7 @@ rl.on('SIGINT', () => { }); ``` -### Event: 'SIGTSTP' +### Event: `'SIGTSTP'` @@ -189,7 +189,7 @@ rl.on('SIGTSTP', () => { The `'SIGTSTP'` event is _not_ supported on Windows. -### rl.close() +### `rl.close()` @@ -201,7 +201,7 @@ the `'close'` event will be emitted. Calling `rl.close()` does not immediately stop other events (including `'line'`) from being emitted by the `readline.Interface` instance. -### rl.pause() +### `rl.pause()` @@ -212,7 +212,7 @@ later if necessary. Calling `rl.pause()` does not immediately pause other events (including `'line'`) from being emitted by the `readline.Interface` instance. -### rl.prompt(\[preserveCursor\]) +### `rl.prompt([preserveCursor])` @@ -230,7 +230,7 @@ paused. If the `readline.Interface` was created with `output` set to `null` or `undefined` the prompt is not written. -### rl.question(query, callback) +### `rl.question(query, callback)` @@ -262,14 +262,14 @@ The `callback` function passed to `rl.question()` does not follow the typical pattern of accepting an `Error` object or `null` as the first argument. The `callback` is called with the provided answer as the only argument. -### rl.resume() +### `rl.resume()` The `rl.resume()` method resumes the `input` stream if it has been paused. -### rl.setPrompt(prompt) +### `rl.setPrompt(prompt)` @@ -279,7 +279,7 @@ added: v0.1.98 The `rl.setPrompt()` method sets the prompt that will be written to `output` whenever `rl.prompt()` is called. -### rl.write(data\[, key\]) +### `rl.write(data[, key])` @@ -312,7 +312,7 @@ rl.write(null, { ctrl: true, name: 'u' }); The `rl.write()` method will write the data to the `readline` `Interface`'s `input` *as if it were provided by the user*. -### rl\[Symbol.asyncIterator\]() +### `rl[Symbol.asyncIterator]()` @@ -384,7 +384,7 @@ process.stdin.on('keypress', (c, k) => { }); ``` -### rl.cursor +### `rl.cursor` @@ -398,7 +398,7 @@ reading input from a TTY stream. The position of cursor determines the portion of the input string that will be modified as input is processed, as well as the column where the terminal caret will be rendered. -### rl.getCursorPos() +### `rl.getCursorPos()` @@ -411,7 +411,7 @@ Returns the real position of the cursor in relation to the input prompt + string. Long input (wrapping) strings, as well as multiple line prompts are included in the calculations. -## readline.clearLine(stream, dir\[, callback\]) +## `readline.clearLine(stream, dir[, callback])` @@ -598,7 +598,7 @@ if (process.stdin.isTTY) process.stdin.setRawMode(true); ``` -## readline.moveCursor(stream, dx, dy\[, callback\]) +## `readline.moveCursor(stream, dx, dy[, callback])` + +The REPL supports bi-directional reverse-i-search similar to [ZSH][]. It is +triggered with ` + R` to search backwards and ` + S` to search +forwards. + +Duplicated history entires will be skipped. + +Entries are accepted as soon as any button is pressed that doesn't correspond +with the reverse search. Cancelling is possible by pressing `escape` or +` + C`. + +Changing the direction immediately searches for the next entry in the expected +direction from the current position on. + ### Custom Evaluation Functions When a new [`repl.REPLServer`][] is created, a custom evaluation function may be @@ -327,17 +347,27 @@ function myWriter(output) { } ``` -## Class: REPLServer +## Class: `REPLServer` +* `options` {Object|string} See [`repl.start()`][] * Extends: {readline.Interface} -Instances of `repl.REPLServer` are created using the `repl.start()` method and -*should not* be created directly using the JavaScript `new` keyword. +Instances of `repl.REPLServer` are created using the [`repl.start()`][] method +or directly using the JavaScript `new` keyword. + +```js +const repl = require('repl'); + +const options = { useColors: true }; + +const firstInstance = repl.start(options); +const secondInstance = new repl.REPLServer(options); +``` -### Event: 'exit' +### Event: `'exit'` @@ -354,7 +384,7 @@ replServer.on('exit', () => { }); ``` -### Event: 'reset' +### Event: `'reset'` @@ -399,7 +429,7 @@ Clearing context... > ``` -### replServer.defineCommand(keyword, cmd) +### `replServer.defineCommand(keyword, cmd)` @@ -445,7 +475,7 @@ Hello, Node.js User! Goodbye! ``` -### replServer.displayPrompt(\[preserveCursor\]) +### `replServer.displayPrompt([preserveCursor])` @@ -465,7 +495,7 @@ The `replServer.displayPrompt` method is primarily intended to be called from within the action function for commands registered using the `replServer.defineCommand()` method. -### replServer.clearBufferedCommand() +### `replServer.clearBufferedCommand()` @@ -475,7 +505,7 @@ buffered but not yet executed. This method is primarily intended to be called from within the action function for commands registered using the `replServer.defineCommand()` method. -### replServer.parseREPLKeyword(keyword\[, rest\]) +### `replServer.parseREPLKeyword(keyword[, rest])` @@ -506,7 +536,7 @@ by default. However, this is not the case when creating a REPL programmatically. Use this method to initialize a history log file when working with REPL instances programmatically. -## repl.start(\[options\]) +## `repl.start([options])` -##### Event: 'close' +##### Event: `'close'` @@ -267,7 +267,7 @@ function writeOneMillionTimes(writer, data, encoding, callback) { } ``` -##### Event: 'error' +##### Event: `'error'` @@ -284,7 +284,7 @@ stream. After `'error'`, no further events other than `'close'` *should* be emitted (including `'error'` events). -##### Event: 'finish' +##### Event: `'finish'` @@ -303,7 +303,7 @@ writer.on('finish', () => { writer.end('This is the end\n'); ``` -##### Event: 'pipe' +##### Event: `'pipe'` @@ -323,7 +323,7 @@ writer.on('pipe', (src) => { reader.pipe(writer); ``` -##### Event: 'unpipe' +##### Event: `'unpipe'` @@ -349,7 +349,7 @@ reader.pipe(writer); reader.unpipe(writer); ``` -##### writable.cork() +##### `writable.cork()` @@ -358,15 +358,18 @@ The `writable.cork()` method forces all written data to be buffered in memory. The buffered data will be flushed when either the [`stream.uncork()`][] or [`stream.end()`][stream-end] methods are called. -The primary intent of `writable.cork()` is to avoid a situation where writing -many small chunks of data to a stream do not cause a backup in the internal -buffer that would have an adverse impact on performance. In such situations, -implementations that implement the `writable._writev()` method can perform -buffered writes in a more optimized manner. +The primary intent of `writable.cork()` is to accommodate a situation in which +several small chunks are written to the stream in rapid succession. Instead of +immediately forwarding them to the underlying destination, `writable.cork()` +buffers all the chunks until `writable.uncork()` is called, which will pass them +all to `writable._writev()`, if present. This prevents a head-of-line blocking +situation where data is being buffered while waiting for the first small chunk +to be processed. However, use of `writable.cork()` without implementing +`writable._writev()` may have an adverse effect on throughput. -See also: [`writable.uncork()`][]. +See also: [`writable.uncork()`][], [`writable._writev()`][stream-_writev]. -##### writable.destroy(\[error\]) +##### `writable.destroy([error])` @@ -385,7 +388,7 @@ the `'drain'` event before destroying the stream. Implementors should not override this method, but instead implement [`writable._destroy()`][writable-_destroy]. -##### writable.destroyed +##### `writable.destroyed` @@ -394,7 +397,7 @@ added: v8.0.0 Is `true` after [`writable.destroy()`][writable-destroy] has been called. -##### writable.end(\[chunk\[, encoding\]\]\[, callback\]) +##### `writable.end([chunk[, encoding]][, callback])` @@ -485,7 +488,7 @@ process.nextTick(() => { See also: [`writable.cork()`][]. -##### writable.writable +##### `writable.writable` @@ -494,7 +497,7 @@ added: v11.4.0 Is `true` if it is safe to call [`writable.write()`][stream-write]. -##### writable.writableEnded +##### `writable.writableEnded` @@ -505,7 +508,7 @@ Is `true` after [`writable.end()`][] has been called. This property does not indicate whether the data has been flushed, for this use [`writable.writableFinished`][] instead. -##### writable.writableCorked +##### `writable.writableCorked` @@ -515,7 +518,7 @@ added: v13.2.0 Number of times [`writable.uncork()`][stream-uncork] needs to be called in order to fully uncork the stream. -##### writable.writableFinished +##### `writable.writableFinished` @@ -524,7 +527,7 @@ added: v12.6.0 Is set to `true` immediately before the [`'finish'`][] event is emitted. -##### writable.writableHighWaterMark +##### `writable.writableHighWaterMark` @@ -534,7 +537,7 @@ added: v9.3.0 Return the value of `highWaterMark` passed when constructing this `Writable`. -##### writable.writableLength +##### `writable.writableLength` @@ -545,7 +548,7 @@ This property contains the number of bytes (or objects) in the queue ready to be written. The value provides introspection data regarding the status of the `highWaterMark`. -##### writable.writableObjectMode +##### `writable.writableObjectMode` @@ -554,7 +557,7 @@ added: v12.3.0 Getter for the property `objectMode` of a given `Writable` stream. -##### writable.write(chunk\[, encoding\]\[, callback\]) +##### `writable.write(chunk[, encoding][, callback])` -##### Event: 'close' +##### Event: `'close'` @@ -815,7 +818,7 @@ readable.on('data', (chunk) => { }); ``` -##### Event: 'end' +##### Event: `'end'` @@ -838,7 +841,7 @@ readable.on('end', () => { }); ``` -##### Event: 'error' +##### Event: `'error'` @@ -852,7 +855,7 @@ to push an invalid chunk of data. The listener callback will be passed a single `Error` object. -##### Event: 'pause' +##### Event: `'pause'` @@ -860,7 +863,7 @@ added: v0.9.4 The `'pause'` event is emitted when [`stream.pause()`][stream-pause] is called and `readableFlowing` is not `false`. -##### Event: 'readable' +##### Event: `'readable'` @@ -937,7 +940,7 @@ added: v0.9.4 The `'resume'` event is emitted when [`stream.resume()`][stream-resume] is called and `readableFlowing` is not `true`. -##### readable.destroy(\[error\]) +##### `readable.destroy([error])` @@ -952,7 +955,7 @@ will be ignored. Implementors should not override this method, but instead implement [`readable._destroy()`][readable-_destroy]. -##### readable.destroyed +##### `readable.destroyed` @@ -961,7 +964,7 @@ added: v8.0.0 Is `true` after [`readable.destroy()`][readable-destroy] has been called. -##### readable.isPaused() +##### `readable.isPaused()` @@ -983,7 +986,7 @@ readable.resume(); readable.isPaused(); // === false ``` -##### readable.pause() +##### `readable.pause()` @@ -1010,7 +1013,7 @@ readable.on('data', (chunk) => { The `readable.pause()` method has no effect if there is a `'readable'` event listener. -##### readable.pipe(destination\[, options\]) +##### `readable.pipe(destination[, options])` @@ -1072,7 +1075,7 @@ to prevent memory leaks. The [`process.stderr`][] and [`process.stdout`][] `Writable` streams are never closed until the Node.js process exits, regardless of the specified options. -##### readable.read(\[size\]) +##### `readable.read([size])` @@ -1124,7 +1127,7 @@ also be emitted. Calling [`stream.read([size])`][stream-read] after the [`'end'`][] event has been emitted will return `null`. No runtime error will be raised. -##### readable.readable +##### `readable.readable` @@ -1133,7 +1136,7 @@ added: v11.4.0 Is `true` if it is safe to call [`readable.read()`][stream-read]. -##### readable.readableEncoding +##### `readable.readableEncoding` @@ -1143,7 +1146,7 @@ added: v12.7.0 Getter for the property `encoding` of a given `Readable` stream. The `encoding` property can be set using the [`readable.setEncoding()`][] method. -##### readable.readableEnded +##### `readable.readableEnded` @@ -1152,7 +1155,7 @@ added: v12.9.0 Becomes `true` when [`'end'`][] event is emitted. -##### readable.readableFlowing +##### `readable.readableFlowing` @@ -1162,7 +1165,7 @@ added: v9.4.0 This property reflects the current state of a `Readable` stream as described in the [Stream Three States][] section. -##### readable.readableHighWaterMark +##### `readable.readableHighWaterMark` @@ -1172,7 +1175,7 @@ added: v9.3.0 Returns the value of `highWaterMark` passed when constructing this `Readable`. -##### readable.readableLength +##### `readable.readableLength` @@ -1183,7 +1186,7 @@ This property contains the number of bytes (or objects) in the queue ready to be read. The value provides introspection data regarding the status of the `highWaterMark`. -##### readable.readableObjectMode +##### `readable.readableObjectMode` @@ -1192,7 +1195,7 @@ added: v12.3.0 Getter for the property `objectMode` of a given `Readable` stream. -##### readable.resume() +##### `readable.resume()` @@ -1253,7 +1256,7 @@ readable.on('data', (chunk) => { }); ``` -##### readable.unpipe(\[destination\]) +##### `readable.unpipe([destination])` @@ -1284,7 +1287,7 @@ setTimeout(() => { }, 1000); ``` -##### readable.unshift(chunk\[, encoding\]) +##### `readable.unshift(chunk[, encoding])` @@ -1393,7 +1396,7 @@ myReader.on('readable', () => { }); ``` -##### readable\[Symbol.asyncIterator\]() +##### `readable[Symbol.asyncIterator]()` @@ -1465,7 +1468,7 @@ Examples of `Transform` streams include: * [zlib streams][zlib] * [crypto streams][crypto] -##### transform.destroy(\[error\]) +##### `transform.destroy([error])` @@ -1479,7 +1482,7 @@ Implementors should not override this method, but instead implement The default implementation of `_destroy()` for `Transform` also emit `'close'` unless `emitClose` is set in false. -### stream.finished(stream\[, options\], callback) +### `stream.finished(stream[, options], callback)` @@ -1552,7 +1555,7 @@ const cleanup = finished(rs, (err) => { }); ``` -### stream.pipeline(...streams, callback) +### `stream.pipeline(...streams, callback)` @@ -1613,7 +1616,7 @@ run().catch(console.error); after the `callback` has been invoked. In the case of reuse of streams after failure, this can cause event listener leaks and swallowed errors. -### stream.Readable.from(iterable, \[options\]) +### `stream.Readable.from(iterable, [options])` @@ -1731,7 +1734,7 @@ Custom `Writable` streams *must* call the `new stream.Writable([options])` constructor and implement the `writable._write()` and/or `writable._writev()` method. -#### Constructor: new stream.Writable(\[options\]) +#### Constructor: `new stream.Writable([options])` @@ -1902,7 +1905,7 @@ added: v8.0.0 The `_destroy()` method is called by [`writable.destroy()`][writable-destroy]. It can be overridden by child classes but it **must not** be called directly. -#### writable.\_final(callback) +#### `writable._final(callback)` @@ -2011,7 +2014,7 @@ The `stream.Readable` class is extended to implement a [`Readable`][] stream. Custom `Readable` streams *must* call the `new stream.Readable([options])` constructor and implement the `readable._read()` method. -#### new stream.Readable(\[options\]) +#### `new stream.Readable([options])` @@ -2113,7 +2116,7 @@ The `readable._read()` method is prefixed with an underscore because it is internal to the class that defines it, and should never be called directly by user programs. -#### readable.\_destroy(err, callback) +#### `readable._destroy(err, callback)` @@ -2125,7 +2128,7 @@ added: v8.0.0 The `_destroy()` method is called by [`readable.destroy()`][readable-destroy]. It can be overridden by child classes but it **must not** be called directly. -#### readable.push(chunk\[, encoding\]) +#### `readable.push(chunk[, encoding])` @@ -54,7 +54,7 @@ added: v0.1.99 Creates a new `StringDecoder` instance. -### stringDecoder.end(\[buffer\]) +### `stringDecoder.end([buffer])` @@ -70,7 +70,7 @@ substitution characters appropriate for the character encoding. If the `buffer` argument is provided, one final call to `stringDecoder.write()` is performed before returning the remaining input. -### stringDecoder.write(buffer) +### `stringDecoder.write(buffer)` @@ -32,7 +32,7 @@ added: v11.0.0 If true, the `Immediate` object will keep the Node.js event loop active. -### immediate.ref() +### `immediate.ref()` @@ -46,7 +46,7 @@ effect. By default, all `Immediate` objects are "ref'ed", making it normally unnecessary to call `immediate.ref()` unless `immediate.unref()` had been called previously. -### immediate.unref() +### `immediate.unref()` @@ -58,7 +58,7 @@ loop to remain active. If there is no other activity keeping the event loop running, the process may exit before the `Immediate` object's callback is invoked. Calling `immediate.unref()` multiple times will have no effect. -## Class: Timeout +## Class: `Timeout` This object is created internally and is returned from [`setTimeout()`][] and [`setInterval()`][]. It can be passed to either [`clearTimeout()`][] or @@ -70,7 +70,7 @@ timer is active. Each of the `Timeout` objects returned by these functions export both `timeout.ref()` and `timeout.unref()` functions that can be used to control this default behavior. -### timeout.hasRef() +### `timeout.hasRef()` @@ -79,7 +79,7 @@ added: v11.0.0 If true, the `Timeout` object will keep the Node.js event loop active. -### timeout.ref() +### `timeout.ref()` @@ -92,7 +92,7 @@ When called, requests that the Node.js event loop *not* exit so long as the By default, all `Timeout` objects are "ref'ed", making it normally unnecessary to call `timeout.ref()` unless `timeout.unref()` had been called previously. -### timeout.refresh() +### `timeout.refresh()` @@ -107,7 +107,7 @@ JavaScript object. Using this on a timer that has already called its callback will reactivate the timer. -### timeout.unref() +### `timeout.unref()` @@ -130,7 +130,7 @@ a certain period of time. When a timer's function is called varies depending on which method was used to create the timer and what other work the Node.js event loop is doing. -### setImmediate(callback\[, ...args\]) +### `setImmediate(callback[, ...args])` @@ -172,7 +172,7 @@ async function timerExample() { timerExample(); ``` -### setInterval(callback, delay\[, ...args\]) +### `setInterval(callback, delay[, ...args])` @@ -190,7 +190,7 @@ set to `1`. Non-integer delays are truncated to an integer. If `callback` is not a function, a [`TypeError`][] will be thrown. -### setTimeout(callback, delay\[, ...args\]) +### `setTimeout(callback, delay[, ...args])` @@ -235,7 +235,7 @@ cancel the timer and prevent it from triggering. It is not possible to cancel timers that were created using the promisified variants of [`setImmediate()`][], [`setTimeout()`][]. -### clearImmediate(immediate) +### `clearImmediate(immediate)` @@ -245,7 +245,7 @@ added: v0.9.1 Cancels an `Immediate` object created by [`setImmediate()`][]. -### clearInterval(timeout) +### `clearInterval(timeout)` @@ -254,7 +254,7 @@ added: v0.0.1 Cancels a `Timeout` object created by [`setInterval()`][]. -### clearTimeout(timeout) +### `clearTimeout(timeout)` diff --git a/doc/api/tls.md b/doc/api/tls.md index ad73586ae96549..81b86abee928e0 100644 --- a/doc/api/tls.md +++ b/doc/api/tls.md @@ -118,6 +118,40 @@ SNI (Server Name Indication) are TLS handshake extensions: * SNI: Allows the use of one TLS server for multiple hostnames with different SSL certificates. +### Pre-shared keys + + + +TLS-PSK support is available as an alternative to normal certificate-based +authentication. It uses a pre-shared key instead of certificates to +authenticate a TLS connection, providing mutual authentication. +TLS-PSK and public key infrastructure are not mutually exclusive. Clients and +servers can accommodate both, choosing either of them during the normal cipher +negotiation step. + +TLS-PSK is only a good choice where means exist to securely share a +key with every connecting machine, so it does not replace PKI +(Public Key Infrastructure) for the majority of TLS uses. +The TLS-PSK implementation in OpenSSL has seen many security flaws in +recent years, mostly because it is used only by a minority of applications. +Please consider all alternative solutions before switching to PSK ciphers. +Upon generating PSK it is of critical importance to use sufficient entropy as +discussed in [RFC 4086][]. Deriving a shared secret from a password or other +low-entropy sources is not secure. + +PSK ciphers are disabled by default, and using TLS-PSK thus requires explicitly +specifying a cipher suite with the `ciphers` option. The list of available +ciphers can be retrieved via `openssl ciphers -v 'PSK'`. All TLS 1.3 +ciphers are eligible for PSK but currently only those that use SHA256 digest are +supported they can be retrieved via `openssl ciphers -v -s -tls1_3 -psk`. + +According to the [RFC 4279][], PSK identities up to 128 bytes in length and +PSKs up to 64 bytes in length must be supported. As of OpenSSL 1.1.0 +maximum identity size is 128 bytes, and maximum PSK length is 256 bytes. + +The current implementation doesn't support asynchronous PSK callbacks due to the +limitations of the underlying OpenSSL API. + ### Client-initiated renegotiation attack mitigation @@ -327,7 +361,7 @@ The first 3 are enabled by default. The last 2 `CCM`-based suites are supported by TLSv1.3 because they may be more performant on constrained systems, but they are not enabled by default since they offer less security. -## Class: tls.Server +## Class: `tls.Server` @@ -336,7 +370,7 @@ added: v0.3.2 Accepts encrypted connections using TLS or SSL. -### Event: 'keylog' +### Event: `'keylog'` @@ -364,7 +398,7 @@ server.on('keylog', (line, tlsSocket) => { }); ``` -### Event: 'newSession' +### Event: `'newSession'` @@ -383,7 +417,7 @@ The listener callback is passed three arguments when called: Listening for this event will have an effect only on connections established after the addition of the event listener. -### Event: 'OCSPRequest' +### Event: `'OCSPRequest'` @@ -430,7 +464,7 @@ after the addition of the event listener. An npm module like [asn1.js][] may be used to parse the certificates. -### Event: 'resumeSession' +### Event: `'resumeSession'` @@ -469,7 +503,7 @@ server.on('resumeSession', (id, cb) => { }); ``` -### Event: 'secureConnection' +### Event: `'secureConnection'` @@ -493,7 +527,7 @@ equals `false`. The `tlsSocket.servername` property is a string containing the server name requested via SNI. -### Event: 'tlsClientError' +### Event: `'tlsClientError'` @@ -506,7 +540,7 @@ called: * `tlsSocket` {tls.TLSSocket} The `tls.TLSSocket` instance from which the error originated. -### server.addContext(hostname, context) +### `server.addContext(hostname, context)` @@ -519,7 +553,7 @@ added: v0.5.3 The `server.addContext()` method adds a secure context that will be used if the client request's SNI name matches the supplied `hostname` (or wildcard). -### server.address() +### `server.address()` @@ -530,7 +564,7 @@ Returns the bound address, the address family name, and port of the server as reported by the operating system. See [`net.Server.address()`][] for more information. -### server.close(\[callback\]) +### `server.close([callback])` @@ -544,7 +578,7 @@ The `server.close()` method stops the server from accepting new connections. This function operates asynchronously. The `'close'` event will be emitted when the server has no more open connections. -### server.connections +### `server.connections` @@ -567,12 +601,12 @@ Returns the session ticket keys. See [Session Resumption][] for more information. -### server.listen() +### `server.listen()` Starts the server listening for encrypted connections. This method is identical to [`server.listen()`][] from [`net.Server`][]. -### server.setSecureContext(options) +### `server.setSecureContext(options)` @@ -584,7 +618,7 @@ added: v11.0.0 The `server.setSecureContext()` method replaces the secure context of an existing server. Existing connections to the server are not interrupted. -### server.setTicketKeys(keys) +### `server.setTicketKeys(keys)` @@ -598,7 +632,7 @@ Existing or currently pending server connections will use the previous keys. See [Session Resumption][] for more information. -## Class: tls.TLSSocket +## Class: `tls.TLSSocket` @@ -614,7 +648,7 @@ Methods that return TLS connection metadata (e.g. [`tls.TLSSocket.getPeerCertificate()`][] will only return data while the connection is open. -### new tls.TLSSocket(socket\[, options\]) +### `new tls.TLSSocket(socket[, options])` @@ -677,7 +711,7 @@ const logFile = fs.createWriteStream('/tmp/ssl-keys.log', { flags: 'a' }); tlsSocket.on('keylog', (line) => logFile.write(line)); ``` -### Event: 'OCSPResponse' +### Event: `'OCSPResponse'` @@ -691,7 +725,7 @@ The listener callback is passed a single argument when called: Typically, the `response` is a digitally signed object from the server's CA that contains information about server's certificate revocation status. -### Event: 'secureConnect' +### Event: `'secureConnect'` @@ -706,7 +740,7 @@ determine if the server certificate was signed by one of the specified CAs. If `tlsSocket.alpnProtocol` property can be checked to determine the negotiated protocol. -### Event: 'session' +### Event: `'session'` @@ -745,7 +779,7 @@ tlsSocket.once('session', (session) => { }); ``` -### tlsSocket.address() +### `tlsSocket.address()` @@ -756,7 +790,7 @@ Returns the bound `address`, the address `family` name, and `port` of the underlying socket as reported by the operating system: `{ port: 12346, family: 'IPv4', address: '127.0.0.1' }`. -### tlsSocket.authorizationError +### `tlsSocket.authorizationError` @@ -764,7 +798,7 @@ added: v0.11.4 Returns the reason why the peer's certificate was not been verified. This property is set only when `tlsSocket.authorized === false`. -### tlsSocket.authorized +### `tlsSocket.authorized` @@ -774,7 +808,7 @@ added: v0.11.4 Returns `true` if the peer certificate was signed by one of the CAs specified when creating the `tls.TLSSocket` instance, otherwise `false`. -### tlsSocket.disableRenegotiation() +### `tlsSocket.disableRenegotiation()` @@ -782,7 +816,7 @@ added: v8.4.0 Disables TLS renegotiation for this `TLSSocket` instance. Once called, attempts to renegotiate will trigger an `'error'` event on the `TLSSocket`. -### tlsSocket.enableTrace() +### `tlsSocket.enableTrace()` @@ -795,7 +829,7 @@ Note: The format of the output is identical to the output of `openssl s_client `SSL_trace()` function, the format is undocumented, can change without notice, and should not be relied on. -### tlsSocket.encrypted +### `tlsSocket.encrypted` @@ -803,7 +837,7 @@ added: v0.11.4 Always returns `true`. This may be used to distinguish TLS sockets from regular `net.Socket` instances. -### tlsSocket.getCertificate() +### `tlsSocket.getCertificate()` @@ -819,7 +853,7 @@ structure. If there is no local certificate, an empty object will be returned. If the socket has been destroyed, `null` will be returned. -### tlsSocket.getCipher() +### `tlsSocket.getCipher()` @@ -869,7 +903,7 @@ if called on a server socket. The supported types are `'DH'` and `'ECDH'`. The For example: `{ type: 'ECDH', name: 'prime256v1', size: 256 }`. -### tlsSocket.getFinished() +### `tlsSocket.getFinished()` @@ -886,7 +920,7 @@ provided by SSL/TLS is not desired or is not enough. Corresponds to the `SSL_get_finished` routine in OpenSSL and may be used to implement the `tls-unique` channel binding from [RFC 5929][]. -### tlsSocket.getPeerCertificate(\[detailed\]) +### `tlsSocket.getPeerCertificate([detailed])` @@ -992,7 +1026,7 @@ Example certificate: raw: } ``` -### tlsSocket.getPeerFinished() +### `tlsSocket.getPeerFinished()` @@ -1009,7 +1043,7 @@ provided by SSL/TLS is not desired or is not enough. Corresponds to the `SSL_get_peer_finished` routine in OpenSSL and may be used to implement the `tls-unique` channel binding from [RFC 5929][]. -### tlsSocket.getProtocol() +### `tlsSocket.getProtocol()` @@ -1031,7 +1065,7 @@ Protocol versions are: See the OpenSSL [`SSL_get_version`][] documentation for more information. -### tlsSocket.getSession() +### `tlsSocket.getSession()` @@ -1048,7 +1082,7 @@ See [Session Resumption][] for more information. Note: `getSession()` works only for TLSv1.2 and below. For TLSv1.3, applications must use the [`'session'`][] event (it also works for TLSv1.2 and below). -### tlsSocket.getSharedSigalgs() +### `tlsSocket.getSharedSigalgs()` @@ -1060,7 +1094,7 @@ See [SSL_get_shared_sigalgs](https://www.openssl.org/docs/man1.1.1/man3/SSL_get_shared_sigalgs.html) for more information. -### tlsSocket.getTLSTicket() +### `tlsSocket.getTLSTicket()` @@ -1074,7 +1108,7 @@ It may be useful for debugging. See [Session Resumption][] for more information. -### tlsSocket.isSessionReused() +### `tlsSocket.isSessionReused()` @@ -1083,7 +1117,7 @@ added: v0.5.6 See [Session Resumption][] for more information. -### tlsSocket.localAddress +### `tlsSocket.localAddress` @@ -1092,7 +1126,7 @@ added: v0.11.4 Returns the string representation of the local IP address. -### tlsSocket.localPort +### `tlsSocket.localPort` @@ -1101,7 +1135,7 @@ added: v0.11.4 Returns the numeric representation of the local port. -### tlsSocket.remoteAddress +### `tlsSocket.remoteAddress` @@ -1111,7 +1145,7 @@ added: v0.11.4 Returns the string representation of the remote IP address. For example, `'74.125.127.100'` or `'2001:4860:a005::68'`. -### tlsSocket.remoteFamily +### `tlsSocket.remoteFamily` @@ -1120,7 +1154,7 @@ added: v0.11.4 Returns the string representation of the remote IP family. `'IPv4'` or `'IPv6'`. -### tlsSocket.remotePort +### `tlsSocket.remotePort` @@ -1129,7 +1163,7 @@ added: v0.11.4 Returns the numeric representation of the remote port. For example, `443`. -### tlsSocket.renegotiate(options, callback) +### `tlsSocket.renegotiate(options, callback)` @@ -1161,7 +1195,7 @@ When running as the server, the socket will be destroyed with an error after For TLSv1.3, renegotiation cannot be initiated, it is not supported by the protocol. -### tlsSocket.setMaxSendFragment(size) +### `tlsSocket.setMaxSendFragment(size)` @@ -1180,7 +1214,7 @@ and their processing can be delayed due to packet loss or reordering. However, smaller fragments add extra TLS framing bytes and CPU overhead, which may decrease overall server throughput. -## tls.checkServerIdentity(hostname, cert) +## `tls.checkServerIdentity(hostname, cert)` @@ -1203,10 +1237,13 @@ the checks done with additional verification. This function is only called if the certificate passed all other checks, such as being issued by trusted CA (`options.ca`). -## tls.connect(options\[, callback\]) +## `tls.connect(options[, callback])` @@ -1348,7 +1402,7 @@ as an argument instead of an option. A path option, if specified, will take precedence over the path argument. -## tls.connect(port\[, host\]\[, options\]\[, callback\]) +## `tls.connect(port[, host][, options][, callback])` @@ -1365,7 +1419,7 @@ as arguments instead of options. A port or host option, if specified, will take precedence over any port or host argument. -## tls.createSecureContext(\[options\]) +## `tls.createSecureContext([options])` @@ -1655,7 +1731,7 @@ TLSv1.2 and below. console.log(tls.getCiphers()); // ['aes128-gcm-sha256', 'aes128-sha', ...] ``` -## tls.rootCertificates +## `tls.rootCertificates` @@ -1666,7 +1742,7 @@ An immutable array of strings representing the root certificates (in PEM format) used for verifying peer certificates. This is the default value of the `ca` option to [`tls.createSecureContext()`][]. -## tls.DEFAULT_ECDH_CURVE +## `tls.DEFAULT_ECDH_CURVE` @@ -1692,7 +1768,7 @@ added: v11.4.0 the default to `'TLSv1.3'`. If multiple of the options are provided, the highest maximum is used. -## tls.DEFAULT_MIN_VERSION +## `tls.DEFAULT_MIN_VERSION` @@ -1708,7 +1784,7 @@ added: v11.4.0 ## Deprecated APIs -### Class: CryptoStream +### Class: `CryptoStream` @@ -41,7 +41,7 @@ Represents the readable side of a TTY. In normal circumstances [`process.stdin`][] will be the only `tty.ReadStream` instance in a Node.js process and there should be no reason to create additional instances. -### readStream.isRaw +### `readStream.isRaw` @@ -49,14 +49,14 @@ added: v0.7.7 A `boolean` that is `true` if the TTY is currently configured to operate as a raw device. Defaults to `false`. -### readStream.isTTY +### `readStream.isTTY` A `boolean` that is always `true` for `tty.ReadStream` instances. -### readStream.setRawMode(mode) +### `readStream.setRawMode(mode)` @@ -74,7 +74,7 @@ including modifiers. Additionally, all special processing of characters by the terminal is disabled, including echoing input characters. `CTRL`+`C` will no longer cause a `SIGINT` when in this mode. -## Class: tty.WriteStream +## Class: `tty.WriteStream` @@ -86,7 +86,7 @@ Represents the writable side of a TTY. In normal circumstances, `tty.WriteStream` instances created for a Node.js process and there should be no reason to create additional instances. -### Event: 'resize' +### Event: `'resize'` @@ -102,7 +102,7 @@ process.stdout.on('resize', () => { }); ``` -### writeStream.clearLine(dir\[, callback\]) +### `writeStream.clearLine(dir[, callback])` @@ -148,7 +148,7 @@ added: v0.7.7 A `number` specifying the number of columns the TTY currently has. This property is updated whenever the `'resize'` event is emitted. -### writeStream.cursorTo(x\[, y\]\[, callback\]) +### `writeStream.cursorTo(x[, y][, callback])` @@ -202,7 +202,7 @@ To enforce a specific color support, use one of the below environment settings. Disabling color support is also possible by using the `NO_COLOR` and `NODE_DISABLE_COLORS` environment variables. -### writeStream.getWindowSize() +### `writeStream.getWindowSize()` @@ -214,7 +214,7 @@ corresponding to this `WriteStream`. The array is of the type `[numColumns, numRows]` where `numColumns` and `numRows` represent the number of columns and rows in the corresponding [TTY](tty.html). -### writeStream.hasColors(\[count\]\[, env\]) +### `writeStream.hasColors([count][, env])` @@ -243,14 +243,14 @@ process.stdout.hasColors(2 ** 24, { TMUX: '1' }); // Returns false (the environment setting pretends to support 2 ** 8 colors). ``` -### writeStream.isTTY +### `writeStream.isTTY` A `boolean` that is always `true`. -### writeStream.moveCursor(dx, dy\[, callback\]) +### `writeStream.moveCursor(dx, dy[, callback])` @@ -277,7 +277,7 @@ added: v0.7.7 A `number` specifying the number of rows the TTY currently has. This property is updated whenever the `'resize'` event is emitted. -## tty.isatty(fd) +## `tty.isatty(fd)` diff --git a/doc/api/url.md b/doc/api/url.md index 80deff6f4b9984..0fb6939d4494a4 100644 --- a/doc/api/url.md +++ b/doc/api/url.md @@ -67,7 +67,7 @@ const myURL = ## The WHATWG URL API -### Class: URL +### Class: `URL` @@ -915,7 +915,7 @@ new URL('file:///hello world').pathname; // Incorrect: /hello%20world fileURLToPath('file:///hello world'); // Correct: /hello world (POSIX) ``` -### url.format(URL\[, options\]) +### `url.format(URL[, options])` @@ -954,7 +954,7 @@ console.log(url.format(myURL, { fragment: false, unicode: true, auth: false })); // Prints 'https://測試/?abc' ``` -### url.pathToFileURL(path) +### `url.pathToFileURL(path)` @@ -993,7 +993,7 @@ changes: The legacy `urlObject` (`require('url').Url`) is created and returned by the `url.parse()` function. -#### urlObject.auth +#### `urlObject.auth` The `auth` property is the username and password portion of the URL, also referred to as _userinfo_. This string subset follows the `protocol` and @@ -1003,35 +1003,35 @@ by `:`. For example: `'user:pass'`. -#### urlObject.hash +#### `urlObject.hash` The `hash` property is the fragment identifier portion of the URL including the leading `#` character. For example: `'#hash'`. -#### urlObject.host +#### `urlObject.host` The `host` property is the full lower-cased host portion of the URL, including the `port` if specified. For example: `'sub.example.com:8080'`. -#### urlObject.hostname +#### `urlObject.hostname` The `hostname` property is the lower-cased host name portion of the `host` component *without* the `port` included. For example: `'sub.example.com'`. -#### urlObject.href +#### `urlObject.href` The `href` property is the full URL string that was parsed with both the `protocol` and `host` components converted to lower-case. For example: `'http://user:pass@sub.example.com:8080/p/a/t/h?query=string#hash'`. -#### urlObject.path +#### `urlObject.path` The `path` property is a concatenation of the `pathname` and `search` components. @@ -1040,7 +1040,7 @@ For example: `'/p/a/t/h?query=string'`. No decoding of the `path` is performed. -#### urlObject.pathname +#### `urlObject.pathname` The `pathname` property consists of the entire path section of the URL. This is everything following the `host` (including the `port`) and before the start @@ -1051,19 +1051,19 @@ For example: `'/p/a/t/h'`. No decoding of the path string is performed. -#### urlObject.port +#### `urlObject.port` The `port` property is the numeric port portion of the `host` component. For example: `'8080'`. -#### urlObject.protocol +#### `urlObject.protocol` The `protocol` property identifies the URL's lower-cased protocol scheme. For example: `'http:'`. -#### urlObject.query +#### `urlObject.query` The `query` property is either the query string without the leading ASCII question mark (`?`), or an object returned by the [`querystring`][] module's @@ -1075,7 +1075,7 @@ For example: `'query=string'` or `{'query': 'string'}`. If returned as a string, no decoding of the query string is performed. If returned as an object, both keys and values are decoded. -#### urlObject.search +#### `urlObject.search` The `search` property consists of the entire "query string" portion of the URL, including the leading ASCII question mark (`?`) character. @@ -1084,13 +1084,13 @@ For example: `'?query=string'`. No decoding of the query string is performed. -#### urlObject.slashes +#### `urlObject.slashes` The `slashes` property is a `boolean` with a value of `true` if two ASCII forward-slash characters (`/`) are required following the colon in the `protocol`. -### url.format(urlObject) +### `url.format(urlObject)` @@ -68,7 +68,7 @@ callbackFunction((err, ret) => { }); ``` -## util.debuglog(section) +## `util.debuglog(section)` @@ -119,7 +119,7 @@ FOO-BAR 3257: hi there, it's foo-bar [2333] Multiple comma-separated `section` names may be specified in the `NODE_DEBUG` environment variable: `NODE_DEBUG=fs,net,tls`. -## util.deprecate(fn, msg\[, code\]) +## `util.deprecate(fn, msg[, code])` @@ -305,7 +305,7 @@ util.formatWithOptions({ colors: true }, 'See object %O', { foo: 42 }); // when printed to a terminal. ``` -## util.getSystemErrorName(err) +## `util.getSystemErrorName(err)` @@ -324,7 +324,7 @@ fs.access('file/that/does/not/exist', (err) => { }); ``` -## util.inherits(constructor, superConstructor) +## `util.inherits(constructor, superConstructor)` @@ -864,7 +864,7 @@ util.inspect.defaultOptions.maxArrayLength = null; console.log(arr); // logs the full array ``` -## util.isDeepStrictEqual(val1, val2) +## `util.isDeepStrictEqual(val1, val2)` @@ -879,7 +879,7 @@ Otherwise, returns `false`. See [`assert.deepStrictEqual()`][] for more information about deep strict equality. -## util.promisify(original) +## `util.promisify(original)` @@ -992,7 +992,7 @@ doSomething[util.promisify.custom] = (foo) => { If `promisify.custom` is defined but is not a function, `promisify()` will throw an error. -### util.promisify.custom +### `util.promisify.custom` @@ -1000,7 +1000,7 @@ added: v8.0.0 * {symbol} that can be used to declare custom promisified variants of functions, see [Custom promisified functions][]. -## Class: util.TextDecoder +## Class: `util.TextDecoder` @@ -1083,7 +1083,7 @@ Different Node.js build configurations support different sets of encodings. The `'iso-8859-16'` encoding listed in the [WHATWG Encoding Standard][] is not supported. -### new TextDecoder(\[encoding\[, options\]\]) +### `new TextDecoder([encoding[, options]])` @@ -1209,7 +1209,7 @@ The result generally does not make any guarantees about what kinds of properties or behavior a value exposes in JavaScript. They are primarily useful for addon developers who prefer to do type checking in JavaScript. -### util.types.isAnyArrayBuffer(value) +### `util.types.isAnyArrayBuffer(value)` @@ -1228,7 +1228,7 @@ util.types.isAnyArrayBuffer(new ArrayBuffer()); // Returns true util.types.isAnyArrayBuffer(new SharedArrayBuffer()); // Returns true ``` -### util.types.isArgumentsObject(value) +### `util.types.isArgumentsObject(value)` @@ -1245,7 +1245,7 @@ function foo() { } ``` -### util.types.isArrayBuffer(value) +### `util.types.isArrayBuffer(value)` @@ -1262,7 +1262,7 @@ util.types.isArrayBuffer(new ArrayBuffer()); // Returns true util.types.isArrayBuffer(new SharedArrayBuffer()); // Returns false ``` -### util.types.isAsyncFunction(value) +### `util.types.isAsyncFunction(value)` @@ -1280,7 +1280,7 @@ util.types.isAsyncFunction(function foo() {}); // Returns false util.types.isAsyncFunction(async function foo() {}); // Returns true ``` -### util.types.isBigInt64Array(value) +### `util.types.isBigInt64Array(value)` @@ -1295,7 +1295,7 @@ util.types.isBigInt64Array(new BigInt64Array()); // Returns true util.types.isBigInt64Array(new BigUint64Array()); // Returns false ``` -### util.types.isBigUint64Array(value) +### `util.types.isBigUint64Array(value)` @@ -1310,7 +1310,7 @@ util.types.isBigUint64Array(new BigInt64Array()); // Returns false util.types.isBigUint64Array(new BigUint64Array()); // Returns true ``` -### util.types.isBooleanObject(value) +### `util.types.isBooleanObject(value)` @@ -1330,7 +1330,7 @@ util.types.isBooleanObject(Boolean(false)); // Returns false util.types.isBooleanObject(Boolean(true)); // Returns false ``` -### util.types.isBoxedPrimitive(value) +### `util.types.isBoxedPrimitive(value)` @@ -1351,7 +1351,7 @@ util.types.isBoxedPrimitive(Object(Symbol('foo'))); // Returns true util.types.isBoxedPrimitive(Object(BigInt(5))); // Returns true ``` -### util.types.isDataView(value) +### `util.types.isDataView(value)` @@ -1369,7 +1369,7 @@ util.types.isDataView(new Float64Array()); // Returns false See also [`ArrayBuffer.isView()`][]. -### util.types.isDate(value) +### `util.types.isDate(value)` @@ -1383,7 +1383,7 @@ Returns `true` if the value is a built-in [`Date`][] instance. util.types.isDate(new Date()); // Returns true ``` -### util.types.isExternal(value) +### `util.types.isExternal(value)` @@ -1393,7 +1393,7 @@ added: v10.0.0 Returns `true` if the value is a native `External` value. -### util.types.isFloat32Array(value) +### `util.types.isFloat32Array(value)` @@ -1409,7 +1409,7 @@ util.types.isFloat32Array(new Float32Array()); // Returns true util.types.isFloat32Array(new Float64Array()); // Returns false ``` -### util.types.isFloat64Array(value) +### `util.types.isFloat64Array(value)` @@ -1425,7 +1425,7 @@ util.types.isFloat64Array(new Uint8Array()); // Returns false util.types.isFloat64Array(new Float64Array()); // Returns true ``` -### util.types.isGeneratorFunction(value) +### `util.types.isGeneratorFunction(value)` @@ -1443,7 +1443,7 @@ util.types.isGeneratorFunction(function foo() {}); // Returns false util.types.isGeneratorFunction(function* foo() {}); // Returns true ``` -### util.types.isGeneratorObject(value) +### `util.types.isGeneratorObject(value)` @@ -1463,7 +1463,7 @@ const generator = foo(); util.types.isGeneratorObject(generator); // Returns true ``` -### util.types.isInt8Array(value) +### `util.types.isInt8Array(value)` @@ -1479,7 +1479,7 @@ util.types.isInt8Array(new Int8Array()); // Returns true util.types.isInt8Array(new Float64Array()); // Returns false ``` -### util.types.isInt16Array(value) +### `util.types.isInt16Array(value)` @@ -1495,7 +1495,7 @@ util.types.isInt16Array(new Int16Array()); // Returns true util.types.isInt16Array(new Float64Array()); // Returns false ``` -### util.types.isInt32Array(value) +### `util.types.isInt32Array(value)` @@ -1511,7 +1511,7 @@ util.types.isInt32Array(new Int32Array()); // Returns true util.types.isInt32Array(new Float64Array()); // Returns false ``` -### util.types.isMap(value) +### `util.types.isMap(value)` @@ -1525,7 +1525,7 @@ Returns `true` if the value is a built-in [`Map`][] instance. util.types.isMap(new Map()); // Returns true ``` -### util.types.isMapIterator(value) +### `util.types.isMapIterator(value)` @@ -1544,7 +1544,7 @@ util.types.isMapIterator(map.entries()); // Returns true util.types.isMapIterator(map[Symbol.iterator]()); // Returns true ``` -### util.types.isModuleNamespaceObject(value) +### `util.types.isModuleNamespaceObject(value)` @@ -1561,7 +1561,7 @@ import * as ns from './a.js'; util.types.isModuleNamespaceObject(ns); // Returns true ``` -### util.types.isNativeError(value) +### `util.types.isNativeError(value)` @@ -1577,7 +1577,7 @@ util.types.isNativeError(new TypeError()); // Returns true util.types.isNativeError(new RangeError()); // Returns true ``` -### util.types.isNumberObject(value) +### `util.types.isNumberObject(value)` @@ -1593,7 +1593,7 @@ util.types.isNumberObject(0); // Returns false util.types.isNumberObject(new Number(0)); // Returns true ``` -### util.types.isPromise(value) +### `util.types.isPromise(value)` @@ -1607,7 +1607,7 @@ Returns `true` if the value is a built-in [`Promise`][]. util.types.isPromise(Promise.resolve(42)); // Returns true ``` -### util.types.isProxy(value) +### `util.types.isProxy(value)` @@ -1624,7 +1624,7 @@ util.types.isProxy(target); // Returns false util.types.isProxy(proxy); // Returns true ``` -### util.types.isRegExp(value) +### `util.types.isRegExp(value)` @@ -1639,7 +1639,7 @@ util.types.isRegExp(/abc/); // Returns true util.types.isRegExp(new RegExp('abc')); // Returns true ``` -### util.types.isSet(value) +### `util.types.isSet(value)` @@ -1653,7 +1653,7 @@ Returns `true` if the value is a built-in [`Set`][] instance. util.types.isSet(new Set()); // Returns true ``` -### util.types.isSetIterator(value) +### `util.types.isSetIterator(value)` @@ -1672,7 +1672,7 @@ util.types.isSetIterator(set.entries()); // Returns true util.types.isSetIterator(set[Symbol.iterator]()); // Returns true ``` -### util.types.isSharedArrayBuffer(value) +### `util.types.isSharedArrayBuffer(value)` @@ -1689,7 +1689,7 @@ util.types.isSharedArrayBuffer(new ArrayBuffer()); // Returns false util.types.isSharedArrayBuffer(new SharedArrayBuffer()); // Returns true ``` -### util.types.isStringObject(value) +### `util.types.isStringObject(value)` @@ -1705,7 +1705,7 @@ util.types.isStringObject('foo'); // Returns false util.types.isStringObject(new String('foo')); // Returns true ``` -### util.types.isSymbolObject(value) +### `util.types.isSymbolObject(value)` @@ -1722,7 +1722,7 @@ util.types.isSymbolObject(symbol); // Returns false util.types.isSymbolObject(Object(symbol)); // Returns true ``` -### util.types.isTypedArray(value) +### `util.types.isTypedArray(value)` @@ -1740,7 +1740,7 @@ util.types.isTypedArray(new Float64Array()); // Returns true See also [`ArrayBuffer.isView()`][]. -### util.types.isUint8Array(value) +### `util.types.isUint8Array(value)` @@ -1756,7 +1756,7 @@ util.types.isUint8Array(new Uint8Array()); // Returns true util.types.isUint8Array(new Float64Array()); // Returns false ``` -### util.types.isUint8ClampedArray(value) +### `util.types.isUint8ClampedArray(value)` @@ -1772,7 +1772,7 @@ util.types.isUint8ClampedArray(new Uint8ClampedArray()); // Returns true util.types.isUint8ClampedArray(new Float64Array()); // Returns false ``` -### util.types.isUint16Array(value) +### `util.types.isUint16Array(value)` @@ -1788,7 +1788,7 @@ util.types.isUint16Array(new Uint16Array()); // Returns true util.types.isUint16Array(new Float64Array()); // Returns false ``` -### util.types.isUint32Array(value) +### `util.types.isUint32Array(value)` @@ -1804,7 +1804,7 @@ util.types.isUint32Array(new Uint32Array()); // Returns true util.types.isUint32Array(new Float64Array()); // Returns false ``` -### util.types.isWeakMap(value) +### `util.types.isWeakMap(value)` @@ -1818,7 +1818,7 @@ Returns `true` if the value is a built-in [`WeakMap`][] instance. util.types.isWeakMap(new WeakMap()); // Returns true ``` -### util.types.isWeakSet(value) +### `util.types.isWeakSet(value)` @@ -1832,7 +1832,7 @@ Returns `true` if the value is a built-in [`WeakSet`][] instance. util.types.isWeakSet(new WeakSet()); // Returns true ``` -### util.types.isWebAssemblyCompiledModule(value) +### `util.types.isWebAssemblyCompiledModule(value)` @@ -1852,7 +1852,7 @@ util.types.isWebAssemblyCompiledModule(module); // Returns true The following APIs are deprecated and should no longer be used. Existing applications and modules should be updated to find alternative approaches. -### util.\_extend(target, source) +### `util._extend(target, source)` @@ -23,7 +23,7 @@ command line flags and detected CPU features. This is useful for determining whether a [`vm.Script`][] `cachedData` buffer is compatible with this instance of V8. -## v8.getHeapSpaceStatistics() +## `v8.getHeapSpaceStatistics()` @@ -106,7 +106,7 @@ const stream = v8.getHeapSnapshot(); stream.pipe(process.stdout); ``` -## v8.getHeapStatistics() +## `v8.getHeapStatistics()` @@ -188,7 +188,7 @@ Returns an object with the following properties: } ``` -## v8.setFlagsFromString(flags) +## `v8.setFlagsFromString(flags)` @@ -212,7 +212,7 @@ v8.setFlagsFromString('--trace_gc'); setTimeout(() => { v8.setFlagsFromString('--notrace_gc'); }, 60e3); ``` -## v8.writeHeapSnapshot(\[filename\]) +## `v8.writeHeapSnapshot([filename])` @@ -270,7 +270,7 @@ The serialization API provides means of serializing JavaScript values in a way that is compatible with the [HTML structured clone algorithm][]. The format is backward-compatible (i.e. safe to store to disk). -### v8.serialize(value) +### `v8.serialize(value)` @@ -280,7 +280,7 @@ added: v8.0.0 Uses a [`DefaultSerializer`][] to serialize `value` into a buffer. -### v8.deserialize(buffer) +### `v8.deserialize(buffer)` @@ -290,19 +290,19 @@ added: v8.0.0 Uses a [`DefaultDeserializer`][] with default options to read a JS value from a buffer. -### class: v8.Serializer +### Class: `v8.Serializer` -#### new Serializer() +#### `new Serializer()` Creates a new `Serializer` object. -#### serializer.writeHeader() +#### `serializer.writeHeader()` Writes out a header, which includes the serialization format version. -#### serializer.writeValue(value) +#### `serializer.writeValue(value)` * `value` {any} @@ -311,7 +311,7 @@ internal buffer. This throws an error if `value` cannot be serialized. -#### serializer.releaseBuffer() +#### `serializer.releaseBuffer()` * Returns: {Buffer} @@ -319,7 +319,7 @@ Returns the stored internal buffer. This serializer should not be used once the buffer is released. Calling this method results in undefined behavior if a previous write has failed. -#### serializer.transferArrayBuffer(id, arrayBuffer) +#### `serializer.transferArrayBuffer(id, arrayBuffer)` * `id` {integer} A 32-bit unsigned integer. * `arrayBuffer` {ArrayBuffer} An `ArrayBuffer` instance. @@ -328,14 +328,14 @@ Marks an `ArrayBuffer` as having its contents transferred out of band. Pass the corresponding `ArrayBuffer` in the deserializing context to [`deserializer.transferArrayBuffer()`][]. -#### serializer.writeUint32(value) +#### `serializer.writeUint32(value)` * `value` {integer} Write a raw 32-bit unsigned integer. For use inside of a custom [`serializer._writeHostObject()`][]. -#### serializer.writeUint64(hi, lo) +#### `serializer.writeUint64(hi, lo)` * `hi` {integer} * `lo` {integer} @@ -343,14 +343,14 @@ For use inside of a custom [`serializer._writeHostObject()`][]. Write a raw 64-bit unsigned integer, split into high and low 32-bit parts. For use inside of a custom [`serializer._writeHostObject()`][]. -#### serializer.writeDouble(value) +#### `serializer.writeDouble(value)` * `value` {number} Write a JS `number` value. For use inside of a custom [`serializer._writeHostObject()`][]. -#### serializer.writeRawBytes(buffer) +#### `serializer.writeRawBytes(buffer)` * `buffer` {Buffer|TypedArray|DataView} @@ -358,7 +358,7 @@ Write raw bytes into the serializer’s internal buffer. The deserializer will require a way to compute the length of the buffer. For use inside of a custom [`serializer._writeHostObject()`][]. -#### serializer.\_writeHostObject(object) +#### `serializer._writeHostObject(object)` * `object` {Object} @@ -369,7 +369,7 @@ exception should be thrown. This method is not present on the `Serializer` class itself but can be provided by subclasses. -#### serializer.\_getDataCloneError(message) +#### `serializer._getDataCloneError(message)` * `message` {string} @@ -379,7 +379,7 @@ object can not be cloned. This method defaults to the [`Error`][] constructor and can be overridden on subclasses. -#### serializer.\_getSharedArrayBufferId(sharedArrayBuffer) +#### `serializer._getSharedArrayBufferId(sharedArrayBuffer)` * `sharedArrayBuffer` {SharedArrayBuffer} @@ -394,36 +394,36 @@ If the object cannot be serialized, an exception should be thrown. This method is not present on the `Serializer` class itself but can be provided by subclasses. -#### serializer.\_setTreatArrayBufferViewsAsHostObjects(flag) +#### `serializer._setTreatArrayBufferViewsAsHostObjects(flag)` * `flag` {boolean} **Default:** `false` Indicate whether to treat `TypedArray` and `DataView` objects as host objects, i.e. pass them to [`serializer._writeHostObject()`][]. -### class: v8.Deserializer +### Class: `v8.Deserializer` -#### new Deserializer(buffer) +#### `new Deserializer(buffer)` * `buffer` {Buffer|TypedArray|DataView} A buffer returned by [`serializer.releaseBuffer()`][]. Creates a new `Deserializer` object. -#### deserializer.readHeader() +#### `deserializer.readHeader()` Reads and validates a header (including the format version). May, for example, reject an invalid or unsupported wire format. In that case, an `Error` is thrown. -#### deserializer.readValue() +#### `deserializer.readValue()` Deserializes a JavaScript value from the buffer and returns it. -#### deserializer.transferArrayBuffer(id, arrayBuffer) +#### `deserializer.transferArrayBuffer(id, arrayBuffer)` * `id` {integer} A 32-bit unsigned integer. * `arrayBuffer` {ArrayBuffer|SharedArrayBuffer} An `ArrayBuffer` instance. @@ -433,7 +433,7 @@ Pass the corresponding `ArrayBuffer` in the serializing context to [`serializer.transferArrayBuffer()`][] (or return the `id` from [`serializer._getSharedArrayBufferId()`][] in the case of `SharedArrayBuffer`s). -#### deserializer.getWireFormatVersion() +#### `deserializer.getWireFormatVersion()` * Returns: {integer} @@ -441,14 +441,14 @@ Reads the underlying wire format version. Likely mostly to be useful to legacy code reading old wire format versions. May not be called before `.readHeader()`. -#### deserializer.readUint32() +#### `deserializer.readUint32()` * Returns: {integer} Read a raw 32-bit unsigned integer and return it. For use inside of a custom [`deserializer._readHostObject()`][]. -#### deserializer.readUint64() +#### `deserializer.readUint64()` * Returns: {integer[]} @@ -456,14 +456,14 @@ Read a raw 64-bit unsigned integer and return it as an array `[hi, lo]` with two 32-bit unsigned integer entries. For use inside of a custom [`deserializer._readHostObject()`][]. -#### deserializer.readDouble() +#### `deserializer.readDouble()` * Returns: {number} Read a JS `number` value. For use inside of a custom [`deserializer._readHostObject()`][]. -#### deserializer.readRawBytes(length) +#### `deserializer.readRawBytes(length)` * `length` {integer} * Returns: {Buffer} @@ -473,7 +473,7 @@ must correspond to the length of the buffer that was passed to [`serializer.writeRawBytes()`][]. For use inside of a custom [`deserializer._readHostObject()`][]. -#### deserializer.\_readHostObject() +#### `deserializer._readHostObject()` This method is called to read some kind of host object, i.e. an object that is created by native C++ bindings. If it is not possible to deserialize the data, @@ -482,7 +482,7 @@ a suitable exception should be thrown. This method is not present on the `Deserializer` class itself but can be provided by subclasses. -### class: v8.DefaultSerializer +### Class: `v8.DefaultSerializer` @@ -491,7 +491,7 @@ A subclass of [`Serializer`][] that serializes `TypedArray` (in particular [`Buffer`][]) and `DataView` objects as host objects, and only stores the part of their underlying `ArrayBuffer`s that they are referring to. -### class: v8.DefaultDeserializer +### Class: `v8.DefaultDeserializer` diff --git a/doc/api/vm.md b/doc/api/vm.md index 7712ea78abce0c..9e832ac8bb8606 100644 --- a/doc/api/vm.md +++ b/doc/api/vm.md @@ -6,52 +6,49 @@ -The `vm` module provides APIs for compiling and running code within V8 Virtual +The `vm` module enables compiling and running code within V8 Virtual Machine contexts. **The `vm` module is not a security mechanism. Do -not use it to run untrusted code**. The term "sandbox" is used throughout these -docs simply to refer to a separate context, and does not confer any security -guarantees. +not use it to run untrusted code**. JavaScript code can be compiled and run immediately or compiled, saved, and run later. -A common use case is to run the code in a sandboxed environment. -The sandboxed code uses a different V8 Context, meaning that -it has a different global object than the rest of the code. +A common use case is to run the code in a different V8 Context. This means +invoked code has a different global object than the invoking code. -One can provide the context by ["contextifying"][contextified] a sandbox -object. The sandboxed code treats any property in the sandbox like a -global variable. Any changes to global variables caused by the sandboxed -code are reflected in the sandbox object. +One can provide the context by [_contextifying_][contextified] an +object. The invoked code treats any property in the context like a +global variable. Any changes to global variables caused by the invoked +code are reflected in the context object. ```js const vm = require('vm'); const x = 1; -const sandbox = { x: 2 }; -vm.createContext(sandbox); // Contextify the sandbox. +const context = { x: 2 }; +vm.createContext(context); // Contextify the object. const code = 'x += 40; var y = 17;'; -// `x` and `y` are global variables in the sandboxed environment. -// Initially, x has the value 2 because that is the value of sandbox.x. -vm.runInContext(code, sandbox); +// `x` and `y` are global variables in the context. +// Initially, x has the value 2 because that is the value of context.x. +vm.runInContext(code, context); -console.log(sandbox.x); // 42 -console.log(sandbox.y); // 17 +console.log(context.x); // 42 +console.log(context.y); // 17 console.log(x); // 1; y is not defined. ``` -## Class: vm.Script +## Class: `vm.Script` Instances of the `vm.Script` class contain precompiled scripts that can be -executed in specific sandboxes (or "contexts"). +executed in specific contexts. -### Constructor: new vm.Script(code\[, options\]) +### Constructor: `new vm.Script(code[, options])` @@ -129,7 +126,7 @@ script.runInThisContext(); const cacheWithX = script.createCachedData(); ``` -### script.runInContext(contextifiedSandbox\[, options\]) +### `script.runInContext(contextifiedObject[, options])` -* `contextifiedSandbox` {Object} A [contextified][] object as returned by the +* `contextifiedObject` {Object} A [contextified][] object as returned by the `vm.createContext()` method. * `options` {Object} * `displayErrors` {boolean} When `true`, if an [`Error`][] occurs @@ -155,30 +152,30 @@ changes: * Returns: {any} the result of the very last statement executed in the script. Runs the compiled code contained by the `vm.Script` object within the given -`contextifiedSandbox` and returns the result. Running code does not have access +`contextifiedObject` and returns the result. Running code does not have access to local scope. The following example compiles code that increments a global variable, sets the value of another global variable, then execute the code multiple times. -The globals are contained in the `sandbox` object. +The globals are contained in the `context` object. ```js const util = require('util'); const vm = require('vm'); -const sandbox = { +const context = { animal: 'cat', count: 2 }; const script = new vm.Script('count += 1; name = "kitty";'); -const context = vm.createContext(sandbox); +vm.createContext(context); for (let i = 0; i < 10; ++i) { script.runInContext(context); } -console.log(util.inspect(sandbox)); +console.log(util.inspect(context)); // { animal: 'cat', count: 12, name: 'kitty' } ``` @@ -187,7 +184,7 @@ Using the `timeout` or `breakOnSigint` options will result in new event loops and corresponding threads being started, which have a non-zero performance overhead. -### script.runInNewContext(\[sandbox\[, options\]\]) +### `script.runInNewContext([contextObject[, options]])` -* `sandbox` {Object} An object that will be [contextified][]. If `undefined`, a - new object will be created. +* `contextObject` {Object} An object that will be [contextified][]. If + `undefined`, a new object will be created. * `options` {Object} * `displayErrors` {boolean} When `true`, if an [`Error`][] occurs while compiling the `code`, the line of code causing the error is attached @@ -230,13 +227,13 @@ changes: module will throw a `WebAssembly.CompileError`. **Default:** `true`. * Returns: {any} the result of the very last statement executed in the script. -First contextifies the given `sandbox`, runs the compiled code contained by -the `vm.Script` object within the created sandbox, and returns the result. +First contextifies the given `contextObject`, runs the compiled code contained +by the `vm.Script` object within the created context, and returns the result. Running code does not have access to local scope. The following example compiles code that sets a global variable, then executes the code multiple times in different contexts. The globals are set on and -contained within each individual `sandbox`. +contained within each individual `context`. ```js const util = require('util'); @@ -244,17 +241,17 @@ const vm = require('vm'); const script = new vm.Script('globalVar = "set"'); -const sandboxes = [{}, {}, {}]; -sandboxes.forEach((sandbox) => { - script.runInNewContext(sandbox); +const contexts = [{}, {}, {}]; +contexts.forEach((context) => { + script.runInNewContext(context); }); -console.log(util.inspect(sandboxes)); +console.log(util.inspect(contexts)); // [{ globalVar: 'set' }, { globalVar: 'set' }, { globalVar: 'set' }] ``` -### script.runInThisContext(\[options\]) +### `script.runInThisContext([options])` @@ -332,7 +329,7 @@ support is planned. ```js const vm = require('vm'); -const contextifiedSandbox = vm.createContext({ secret: 42 }); +const contextifiedObject = vm.createContext({ secret: 42 }); (async () => { // Step 1 @@ -340,7 +337,7 @@ const contextifiedSandbox = vm.createContext({ secret: 42 }); // Create a Module by constructing a new `vm.SourceTextModule` object. This // parses the provided source text, throwing a `SyntaxError` if anything goes // wrong. By default, a Module is created in the top context. But here, we - // specify `contextifiedSandbox` as the context this Module belongs to. + // specify `contextifiedObject` as the context this Module belongs to. // // Here, we attempt to obtain the default export from the module "foo", and // put it into local binding "secret". @@ -348,7 +345,7 @@ const contextifiedSandbox = vm.createContext({ secret: 42 }); const bar = new vm.SourceTextModule(` import s from 'foo'; s; - `, { context: contextifiedSandbox }); + `, { context: contextifiedObject }); // Step 2 // @@ -377,11 +374,11 @@ const contextifiedSandbox = vm.createContext({ secret: 42 }); if (specifier === 'foo') { return new vm.SourceTextModule(` // The "secret" variable refers to the global variable we added to - // "contextifiedSandbox" when creating the context. + // "contextifiedObject" when creating the context. export default secret; `, { context: referencingModule.context }); - // Using `contextifiedSandbox` instead of `referencingModule.context` + // Using `contextifiedObject` instead of `referencingModule.context` // here would work as well. } throw new Error(`Unable to resolve dependency: ${specifier}`); @@ -403,7 +400,7 @@ const contextifiedSandbox = vm.createContext({ secret: 42 }); })(); ``` -### module.dependencySpecifiers +### `module.dependencySpecifiers` * {string[]} @@ -413,7 +410,7 @@ to disallow any changes to it. Corresponds to the `[[RequestedModules]]` field of [Cyclic Module Record][]s in the ECMAScript specification. -### module.error +### `module.error` * {any} @@ -427,7 +424,7 @@ exception due to possible ambiguity with `throw undefined;`. Corresponds to the `[[EvaluationError]]` field of [Cyclic Module Record][]s in the ECMAScript specification. -### module.evaluate(\[options\]) +### `module.evaluate([options])` * `options` {Object} * `timeout` {integer} Specifies the number of milliseconds to evaluate @@ -457,7 +454,7 @@ This method cannot be called while the module is being evaluated Corresponds to the [Evaluate() concrete method][] field of [Cyclic Module Record][]s in the ECMAScript specification. -### module.link(linker) +### `module.link(linker)` * `linker` {Function} * `specifier` {string} The specifier of the requested module: @@ -505,7 +502,7 @@ specification. Corresponds to the [Link() concrete method][] field of [Cyclic Module Record][]s in the ECMAScript specification. -### module.namespace +### `module.namespace` * {Object} @@ -515,7 +512,7 @@ The namespace object of the module. This is only available after linking Corresponds to the [GetModuleNamespace][] abstract operation in the ECMAScript specification. -### module.status +### `module.status` * {string} @@ -541,13 +538,13 @@ Other than `'errored'`, this status string corresponds to the specification's `'evaluated'` in the specification, but with `[[EvaluationError]]` set to a value that is not `undefined`. -### module.identifier +### `module.identifier` * {string} The identifier of the current module, as set in the constructor. -## Class: vm.SourceTextModule +## Class: `vm.SourceTextModule` @@ -562,7 +559,7 @@ flag enabled.* The `vm.SourceTextModule` class provides the [Source Text Module Record][] as defined in the ECMAScript specification. -### Constructor: new vm.SourceTextModule(code\[, options\]) +### Constructor: `new vm.SourceTextModule(code[, options])` * `code` {string} JavaScript Module code to parse * `options` @@ -597,7 +594,7 @@ allow the module to access information outside the specified `context`. Use ```js const vm = require('vm'); -const contextifiedSandbox = vm.createContext({ secret: 42 }); +const contextifiedObject = vm.createContext({ secret: 42 }); (async () => { const module = new vm.SourceTextModule( @@ -607,7 +604,7 @@ const contextifiedSandbox = vm.createContext({ secret: 42 }); // Note: this object is created in the top context. As such, // Object.getPrototypeOf(import.meta.prop) points to the // Object.prototype in the top context rather than that in - // the sandbox. + // the contextified object. meta.prop = {}; } }); @@ -620,11 +617,11 @@ const contextifiedSandbox = vm.createContext({ secret: 42 }); // To fix this problem, replace // meta.prop = {}; // above with - // meta.prop = vm.runInContext('{}', contextifiedSandbox); + // meta.prop = vm.runInContext('{}', contextifiedObject); })(); ``` -## Class: vm.SyntheticModule +## Class: `vm.SyntheticModule` @@ -653,7 +650,7 @@ const module = new vm.SyntheticModule(['default'], function() { // Use `module` in linking... ``` -### Constructor: new vm.SyntheticModule(exportNames, evaluateCallback\[, options\]) +### Constructor: `new vm.SyntheticModule(exportNames, evaluateCallback[, options])` @@ -673,7 +670,7 @@ Objects assigned to the exports of this instance may allow importers of the module to access information outside the specified `context`. Use `vm.runInContext()` to create objects in a specific context. -### syntheticModule.setExport(name, value) +### `syntheticModule.setExport(name, value)` @@ -700,7 +697,7 @@ const vm = require('vm'); })(); ``` -## vm.compileFunction(code\[, params\[, options\]\]) +## `vm.compileFunction(code[, params[, options]])` @@ -720,30 +717,30 @@ added: v10.10.0 source. * `produceCachedData` {boolean} Specifies whether to produce new cache data. **Default:** `false`. - * `parsingContext` {Object} The [contextified][] sandbox in which the said + * `parsingContext` {Object} The [contextified][] object in which the said function should be compiled in. * `contextExtensions` {Object[]} An array containing a collection of context extensions (objects wrapping the current scope) to be applied while compiling. **Default:** `[]`. * Returns: {Function} -Compiles the given code into the provided context/sandbox (if no context is +Compiles the given code into the provided context (if no context is supplied, the current context is used), and returns it wrapped inside a function with the given `params`. -## vm.createContext(\[sandbox\[, options\]\]) +## `vm.createContext([contextObject[, options]])` -* `sandbox` {Object} +* `contextObject` {Object} * `options` {Object} * `name` {string} Human-readable name of the newly created context. **Default:** `'VM Context i'`, where `i` is an ascending numerical index of @@ -760,12 +757,12 @@ changes: `EvalError`. **Default:** `true`. * `wasm` {boolean} If set to false any attempt to compile a WebAssembly module will throw a `WebAssembly.CompileError`. **Default:** `true`. -* Returns: {Object} contextified sandbox. +* Returns: {Object} contextified object. -If given a `sandbox` object, the `vm.createContext()` method will [prepare -that sandbox][contextified] so that it can be used in calls to +If given a `contextObject`, the `vm.createContext()` method will [prepare +that object][contextified] so that it can be used in calls to [`vm.runInContext()`][] or [`script.runInContext()`][]. Inside such scripts, -the `sandbox` object will be the global object, retaining all of its existing +the `contextObject` will be the global object, retaining all of its existing properties but also having the built-in objects and functions any standard [global object][] has. Outside of scripts run by the vm module, global variables will remain unchanged. @@ -776,40 +773,40 @@ const vm = require('vm'); global.globalVar = 3; -const sandbox = { globalVar: 1 }; -vm.createContext(sandbox); +const context = { globalVar: 1 }; +vm.createContext(context); -vm.runInContext('globalVar *= 2;', sandbox); +vm.runInContext('globalVar *= 2;', context); -console.log(util.inspect(sandbox)); // { globalVar: 2 } +console.log(util.inspect(context)); // { globalVar: 2 } console.log(util.inspect(globalVar)); // 3 ``` -If `sandbox` is omitted (or passed explicitly as `undefined`), a new, empty -[contextified][] sandbox object will be returned. +If `contextObject` is omitted (or passed explicitly as `undefined`), a new, +empty [contextified][] object will be returned. The `vm.createContext()` method is primarily useful for creating a single -sandbox that can be used to run multiple scripts. For instance, if emulating a -web browser, the method can be used to create a single sandbox representing a -window's global object, then run all `