node-bin-darwin-arm64 26.3.1 → 26.5.0

package/share/man/man1/node.1

@@ -1,28 +1,11 @@
 .\"
-.\" This manpage is written in mdoc(7).
+.\" This file was generated automatically by the @node-core/doc-kit tool.
+.\" Please do not edit this file manually. Make any updates to cli.md
+.\" and regenerate the file afterward.
 .\"
-.\" * Language reference:
-.\"   https://man.openbsd.org/mdoc.7
-.\"
-.\" * Linting changes:
-.\"   mandoc -Wall -Tlint /path/to/this.file  # BSD
-.\"   groff -w all -z /path/to/this.file      # GNU/Linux, macOS
-.\"
-.\"
-.\" Before making changes, please note the following:
-.\"
-.\" * In Roff, each new sentence should begin on a new line. This gives
-.\"   the Roff formatter better control over text-spacing, line-wrapping,
-.\"   and paragraph justification.
-.\"
-.\" * Do not leave blank lines in the markup. If whitespace is desired
-.\"   for readability, put a dot in the first column to indicate a null/empty
-.\"   command. Comments and horizontal whitespace may optionally follow: each
-.\"   of these lines are an example of a null command immediately followed by
-.\"   a comment.
+.\" To regenerate this file, run `make doc/node.1`.
 .\"
 .\"======================================================================
-.
 .Dd $Mdocdate$
 .Dt NODE 1
 .
@@ -38,7 +21,7 @@
 .Op Ar arguments ...
 .
 .Nm node
-.Cm inspect
+.Cm inspect,
 .Op Ar <program-entry-point> | Fl e Ar string | Ar <host>:<port>
 .Ar ...
 .
@@ -136,12 +119,11 @@ flags are propagated via the \fBNODE_OPTIONS\fR environment variable rather than
 directly through the process arguments.
 .
 .It Fl -allow-ffi
-When using the Permission Model, the process will not be able to use
-\fBnode:ffi\fR by default.
-Attempts to use FFI APIs will throw an \fBERR_ACCESS_DENIED\fR exception unless
-the user explicitly passes the \fB--allow-ffi\fR flag when starting Node.js.
-The \fBnode:ffi\fR module also requires the \fB--experimental-ffi\fR flag and
-is only available in builds with FFI support.
+When using the Permission Model, the process will not be able to use FFI
+APIs by default. Attempts to use FFI APIs will throw an \fBERR_ACCESS_DENIED\fR
+exception unless the user explicitly passes the \fB--allow-ffi\fR flag when
+starting Node.js. The \fBnode:ffi\fR module also requires the
+\fB--experimental-ffi\fR flag and is only available in builds with FFI support.
 Example:
 .Bd -literal
 const { DynamicLibrary } = require('node:ffi');
@@ -165,7 +147,7 @@ The valid arguments for the \fB--allow-fs-read\fR flag are:
 \fB*\fR - To allow all \fBFileSystemRead\fR operations.
 .It
 Multiple paths can be allowed using multiple \fB--allow-fs-read\fR flags.
-Example \fB--allow-fs-read=/folder1/ --allow-fs-read=/folder1/\fR
+Example \fB--allow-fs-read=/folder1/ --allow-fs-read=/folder2/\fR
 .El
 Examples can be found in the File System Permissions documentation.
 The initializer module and custom \fB--require\fR modules has a implicit
@@ -179,9 +161,9 @@ The \fBcustom-require.js\fR, \fBcustom-require-2.js\fR, and \fBindex.js\fR will
 by default in the allowed read list.
 .El
 .Bd -literal
-process.has('fs.read', 'index.js'); // true
-process.has('fs.read', 'custom-require.js'); // true
-process.has('fs.read', 'custom-require-2.js'); // true
+process.permission.has('fs.read', 'index.js'); // true
+process.permission.has('fs.read', 'custom-require.js'); // true
+process.permission.has('fs.read', 'custom-require-2.js'); // true
 .Ed
 .
 .It Fl -allow-fs-write
@@ -193,7 +175,7 @@ The valid arguments for the \fB--allow-fs-write\fR flag are:
 \fB*\fR - To allow all \fBFileSystemWrite\fR operations.
 .It
 Multiple paths can be allowed using multiple \fB--allow-fs-write\fR flags.
-Example \fB--allow-fs-write=/folder1/ --allow-fs-write=/folder1/\fR
+Example \fB--allow-fs-write=/folder1/ --allow-fs-write=/folder2/\fR
 .El
 Paths delimited by comma (\fB,\fR) are no longer allowed.
 When passing a single flag with a comma a warning will be displayed.
@@ -326,7 +308,7 @@ $ node --snapshot-blob snapshot.blob
 I am from the snapshot
 .Ed
 For more information, check out the \fBv8.startupSnapshot\fR API documentation.
-The snapshot currently only supports loding a single entrypoint during the
+The snapshot currently only supports loading a single entrypoint during the
 snapshot building process, which can load built-in modules, but not additional user-land modules.
 Users can bundle their applications into a single script with their bundler
 of choice before building a snapshot.
@@ -479,36 +461,26 @@ vm.measureMemory();
 .Ed
 .
 .It Fl -disable-wasm-trap-handler
-By default, Node.js enables trap-handler-based WebAssembly bound
-checks. As a result, V8 does not need to insert inline bound checks
-in the code compiled from WebAssembly which may speed up WebAssembly
-execution significantly, but this optimization requires allocating
-a big virtual memory cage (currently 10GB). If the Node.js process
-does not have access to a large enough virtual memory address space
-due to system configurations or hardware limitations, users won't
-be able to run any WebAssembly that involves allocation in this
-virtual memory cage and will see an out-of-memory error.
-.Bd -literal
-$ ulimit -v 5000000
-$ node -p "new WebAssembly.Memory({ initial: 10, maximum: 100 });"
-[eval]:1
-new WebAssembly.Memory({ initial: 10, maximum: 100 });
-^
-
-RangeError: WebAssembly.Memory(): could not allocate memory
-    at [eval]:1:1
-    at runScriptInThisContext (node:internal/vm:209:10)
-    at node:internal/process/execution:118:14
-    at [eval]-wrapper:6:24
-    at runScript (node:internal/process/execution:101:62)
-    at evalScript (node:internal/process/execution:136:3)
-    at node:internal/main/eval_string:49:3
-
-.Ed
-\fB--disable-wasm-trap-handler\fR disables this optimization so that
-users can at least run WebAssembly (with less optimal performance)
-when the virtual memory address space available to their Node.js
-process is lower than what the V8 WebAssembly memory cage needs.
+Node.js enables V8's trap-handler-based WebAssembly bound checks on 64-bit platforms,
+which significantly improves WebAssembly performance by eliminating the need for
+inline bound checks. This optimization requires allocating a large virtual memory
+cage per WebAssembly memory instance (currently typically 8GB for 32-bit WebAssembly memory,
+16GB for 64-bit WebAssembly memory) to trap out-of-bound accesses. On most 64-bit
+platforms, the virtual memory address space is usually large enough (around 128TB)
+to accommodate typical WebAssembly usages, but if the machine has manual limits
+on virtual memory (e.g. through \fBulimit -v\fR), WebAssembly memory allocation is
+more likely to fail with \fBWebAssembly.Memory(): could not allocate memory\fR.
+At startup, Node.js automatically checks whether there is enough virtual memory
+available to allocate at least one cage, and if not, the trap-handler optimization
+is automatically disabled so that WebAssembly can still run using inline
+bound checks (with less optimal performance). But if the application needs to create
+many WebAssembly memory instances and the machine still configures a relatively high
+limit on virtual memory, allocation of WebAssembly memory instances may still fail
+more quickly than expected due to the raised virtual memory usage.
+\fB--disable-wasm-trap-handler\fR fully disables this optimization so that WebAssembly memory
+instances always use inline bound checks instead of reserving large virtual memory cages.
+This allows more instances to be created when the virtual memory address space available
+to the Node.js process is limited.
 .
 .It Fl -disallow-code-generation-from-strings
 Make built-in language features like \fBeval\fR and \fBnew Function\fR that generate
@@ -614,6 +586,8 @@ can use the \fB--env-file-if-exists\fR flag instead.
 .It Fl e , Fl -eval Ar "script"
 Evaluate the following argument as JavaScript. The modules which are
 predefined in the REPL can also be used in \fBscript\fR.
+If \fBscript\fR starts with \fB-\fR, pass it using \fB=\fR (for example,
+\fBnode --print --eval=-42\fR) so it is parsed as the value of \fB--eval\fR.
 On Windows, using \fBcmd.exe\fR a single quote will not work correctly because it
 only recognizes double \fB"\fR for quoting. In Powershell or Git bash, both \fB'\fR
 and \fB"\fR are usable.
@@ -623,15 +597,18 @@ It is possible to run code containing inline types unless the
 .It Fl -experimental-addon-modules
 Enable experimental import support for \fB.node\fR addons.
 .
-.It Fl -experimental-config-file= Ns Ar config , Fl -experimental-config-file , Fl -experimental-default-config-file
+.It Fl -experimental-config-file Ns = Ns Ar path , Fl -experimental-config-file
 If present, Node.js will look for a configuration file at the specified path.
 If the path is not specified, Node.js will look for a \fBnode.config.json\fR file
 in the current working directory.
-To specify a custom path, use the \fB--experimental-config-file=\fR\fBpath\fR form.
+To specify a custom path, use the \fB--experimental-config-file=path\fR form.
 The space-separated \fB--experimental-config-file path\fR form is not supported.
+The alias \fB--experimental-default-config-file\fR is equivalent to
+\fB--experimental-config-file\fR without an argument.
 Node.js will read the configuration file and apply the settings. The
 configuration file should be a JSON file with the following structure. \fBvX.Y.Z\fR
-in the \fB$schema\fR must be replaced with the version of Node.js you are using.
+in the \fB$schema\fR must be replaced with the version of Node.js you are using or
+\fBlatest-vX.x\fR for the latest version of that major release line.
 .Bd -literal
 {
   "$schema": "https://nodejs.org/dist/vX.Y.Z/docs/node-config-schema.json",
@@ -657,6 +634,39 @@ The \fBnodeOptions\fR field contains CLI flags that are allowed in \fBNODE_OPTIO
 .It
 Namespace fields like \fBtest\fR, \fBwatch\fR, and \fBpermission\fR contain configuration specific to that subsystem.
 .El
+The configuration file can target a specific Node.js major version with
+\fBnodeVersion\fR:
+.Bd -literal
+{
+  "nodeVersion": 25,
+  "nodeOptions": {
+    "watch-path": "src"
+  }
+}
+.Ed
+To keep multiple version-specific configurations in the same file, use the
+\fBconfigs\fR array. Node.js will use the first entry whose \fBnodeVersion\fR matches
+the current Node.js major version:
+.Bd -literal
+{
+  "$schema": "https://nodejs.org/dist/latest-v26.x/docs/node-config-schema.json",
+  "configs": [
+    {
+      "nodeVersion": 25,
+      "config": {
+        "$schema": "https://nodejs.org/dist/latest-v25.x/docs/node-config-schema.json",
+        "nodeOptions": {
+          "watch-path": "src"
+        }
+      }
+    }
+  ]
+}
+.Ed
+When \fBconfigs\fR is used, the top level may only contain \fB$schema\fR and
+\fBconfigs\fR. Each \fBconfigs\fR item must define an integer \fBnodeVersion\fR and an
+object \fBconfig\fR. A single top-level config does not require \fBnodeVersion\fR, but
+if present it must match the current Node.js major version.
 When a namespace is present in the
 configuration file, Node.js automatically enables the corresponding flag
 (e.g., \fB--test\fR, \fB--watch\fR, \fB--permission\fR). This allows you to configure
@@ -700,13 +710,13 @@ The priority in configuration is as follows:
 .It
 NODE_OPTIONS and command-line options
 .It
-Configuration file
-.It
 Dotenv NODE_OPTIONS
+.It
+Configuration file
 .El
 Values in the configuration file will not override the values in the environment
-variables and command-line options, but will override the values in the \fBNODE_OPTIONS\fR
-env file parsed by the \fB--env-file\fR flag.
+variables, command-line options, or the \fBNODE_OPTIONS\fR env file parsed by the
+\fB--env-file\fR flag.
 Keys cannot be duplicated within the same or different namespaces.
 The configuration parser will throw an error if the configuration file contains
 unknown keys or keys that cannot be used in a namespace.
@@ -731,6 +741,10 @@ Enable experimental \fBimport.meta.resolve()\fR parent URL support, which allows
 passing a second \fBparentURL\fR argument for contextual resolution.
 Previously gated the entire \fBimport.meta.resolve\fR feature.
 .
+.It Fl -experimental-import-text
+Enable experimental support for importing modules with
+\fBwith { type: 'text' }\fR.
+.
 .It Fl -experimental-inspector-network-resource
 Enable experimental support for inspector network resources.
 .
@@ -742,19 +756,24 @@ This feature requires \fB--allow-worker\fR if used with the Permission Model.
 .It Fl -experimental-network-inspection
 Enable experimental support for the network inspection with Chrome DevTools.
 .
+.It Fl -experimental-package-map Ns = Ns Ar <path>
+Enable experimental package map resolution. The \fBpath\fR argument specifies the
+location of a JSON configuration file that defines package resolution mappings.
+.Bd -literal
+node --experimental-package-map=./package-map.json app.js
+.Ed
+When enabled, bare specifier resolution consults the package map for resolution.
+This allows explicit control over which packages can import which dependencies.
+See Package maps for details on the configuration file format and
+resolution algorithm.
+.
 .It Fl -experimental-print-required-tla
-If the ES module being \fBrequire()\fR'd contains top-level \fBawait\fR, this flag
-allows Node.js to evaluate the module, try to locate the
-top-level awaits, and print their location to help users find them.
+If the ES module graph cannot be \fBrequire()\fR'd because it contains any top-level \fBawait\fR,
+this flag allows Node.js to locate and print their locations.
 .
 .It Fl -experimental-quic
 Enable experimental support for the QUIC protocol.
 .
-.It Fl -experimental-stream-iter
-Enable the experimental
-.Sy node:stream/iter
-module.
-.
 .It Fl -experimental-sea-config
 Use this flag to generate a blob that can be injected into the Node.js
 binary to produce a single executable application. See the documentation
@@ -766,6 +785,9 @@ Use this flag to enable ShadowRealm support.
 .It Fl -experimental-storage-inspection
 Enable experimental support for storage inspection
 .
+.It Fl -experimental-stream-iter
+Enable the experimental \fBnode:stream/iter\fR module.
+.
 .It Fl -experimental-test-coverage
 When used in conjunction with the \fBnode:test\fR module, a code coverage report is
 generated as part of the test runner output. If no tests are run, a coverage
@@ -776,9 +798,17 @@ collecting code coverage from tests for more details.
 Enable module mocking in the test runner.
 This feature requires \fB--allow-worker\fR if used with the Permission Model.
 .
-.It Fl -experimental-test-tag-filter Ar tag
-Run only tests whose tag set contains \fItag\fR. May be specified multiple
-times; tests must contain every filter to run.
+.It Fl -experimental-test-tag-filter Ns = Ns Ar <tag>
+Run only tests whose tag set contains \fB<tag>\fR. Tests declare tags via the
+\fBtags\fR option on \fBtest()\fR, \fBit()\fR, \fBsuite()\fR, or \fBdescribe()\fR; tags
+inherit from suites to nested tests by union. Filtering is
+case-insensitive.
+The flag may be specified more than once; tests must contain \fBevery\fR
+filter value to run. See Test tags for details on declaring and
+inheriting tags.
+.
+.It Fl -experimental-vfs
+Enable the experimental \fBnode:vfs\fR module.
 .
 .It Fl -experimental-vm-modules
 Enable experimental ES Module support in the \fBnode:vm\fR module.
@@ -971,6 +1001,8 @@ Activate inspector on \fBhost:port\fR and break at start of user script.
 Default \fBhost:port\fR is \fB127.0.0.1:9229\fR. If port \fB0\fR is specified,
 a random available port will be used.
 See V8 Inspector integration for Node.js for further explanation on Node.js debugger.
+See the security warning below regarding the \fBhost\fR
+parameter usage.
 .
 .It Fl -inspect-port Ns = Ns Ar [host:]port
 Set the \fBhost:port\fR to be used when the inspector is activated.
@@ -991,6 +1023,8 @@ Activate inspector on \fBhost:port\fR and wait for debugger to be attached.
 Default \fBhost:port\fR is \fB127.0.0.1:9229\fR. If port \fB0\fR is specified,
 a random available port will be used.
 See V8 Inspector integration for Node.js for further explanation on Node.js debugger.
+See the security warning below regarding the \fBhost\fR
+parameter usage.
 .
 .It Fl -inspect Ns = Ns Ar [[host:]port]
 Activate inspector on \fBhost:port\fR. Default is \fB127.0.0.1:9229\fR. If port \fB0\fR is
@@ -1400,19 +1434,20 @@ Configures the test runner to only execute top level tests that have the \fBonly
 option set. This flag is not necessary when test isolation is disabled.
 .
 .It Fl -test-random-seed
-Set the seed used to randomize test execution order.
-This applies to both test file execution order and queued tests within each file.
-Providing this flag enables randomization implicitly, even without
-\fB--test-randomize\fR.
-The value must be an integer between 0 and 4294967295.
+Set the seed used to randomize test execution order. This applies to both test
+file execution order and queued tests within each file. Providing this flag
+enables randomization implicitly, even without \fB--test-randomize\fR.
+The value must be an integer between \fB0\fR and \fB4294967295\fR.
 This flag cannot be used with \fB--watch\fR or \fB--test-rerun-failures\fR.
 .
 .It Fl -test-randomize
-Randomize test execution order.
-This applies to both test file execution order and queued tests within each file.
-This can help detect tests that rely on shared state or execution order.
+Randomize test execution order. This applies to both test file execution order
+and queued tests within each file. This can help detect tests that rely on
+shared state or execution order.
 The seed used for randomization is printed in the test summary and can be
 reused with \fB--test-random-seed\fR.
+For detailed behavior and examples, see
+randomizing tests execution order.
 This flag cannot be used with \fB--watch\fR or \fB--test-rerun-failures\fR.
 .
 .It Fl -test-reporter
@@ -1920,12 +1955,16 @@ one is included in the list below.
 .It
 \fB--experimental-import-meta-resolve\fR
 .It
+\fB--experimental-import-text\fR
+.It
 \fB--experimental-json-modules\fR
 .It
 \fB--experimental-loader\fR
 .It
 \fB--experimental-modules\fR
 .It
+\fB--experimental-package-map\fR
+.It
 \fB--experimental-print-required-tla\fR
 .It
 \fB--experimental-quic\fR
@@ -1936,10 +1975,14 @@ one is included in the list below.
 .It
 \fB--experimental-specifier-resolution\fR
 .It
+\fB--experimental-stream-iter\fR
+.It
 \fB--experimental-test-isolation\fR
 .It
 \fB--experimental-top-level-await\fR
 .It
+\fB--experimental-vfs\fR
+.It
 \fB--experimental-vm-modules\fR
 .It
 \fB--experimental-wasi-unstable-preview1\fR
@@ -2036,10 +2079,10 @@ one is included in the list below.
 .It
 \fB--pending-deprecation\fR
 .It
-\fB--permission\fR
-.It
 \fB--permission-audit\fR
 .It
+\fB--permission\fR
+.It
 \fB--preserve-symlinks-main\fR
 .It
 \fB--preserve-symlinks\fR
@@ -2094,11 +2137,11 @@ one is included in the list below.
 .It
 \fB--test-only\fR
 .It
-\fB--test-reporter-destination\fR
+\fB--test-random-seed\fR
 .It
 \fB--test-randomize\fR
 .It
-\fB--test-random-seed\fR
+\fB--test-reporter-destination\fR
 .It
 \fB--test-reporter\fR
 .It
@@ -2197,6 +2240,8 @@ V8 options that are allowed are:
 .It
 \fB--jitless\fR
 .It
+\fB--max-heap-size\fR
+.It
 \fB--max-old-space-size\fR
 .It
 \fB--max-semi-space-size\fR