diff --git a/api-docs/1b31101da2a144f40b5e6eda01603c9d73eb024122ce2e857399b9a06694ffe3.md b/addons/addon_examples.md similarity index 100% rename from api-docs/1b31101da2a144f40b5e6eda01603c9d73eb024122ce2e857399b9a06694ffe3.md rename to addons/addon_examples.md diff --git a/api-docs/83ec18db763f1bef014a9843167d7a74dba11a2f8b5a3b9ddfc11b0806b9100c.md b/addons/atexit_hooks.md similarity index 100% rename from api-docs/83ec18db763f1bef014a9843167d7a74dba11a2f8b5a3b9ddfc11b0806b9100c.md rename to addons/atexit_hooks.md diff --git a/api-docs/f4e1878558e45c95368f7eb3badcfe568b8d85b11bfc740ca183034af8f75d08.md b/addons/building.md similarity index 100% rename from api-docs/f4e1878558e45c95368f7eb3badcfe568b8d85b11bfc740ca183034af8f75d08.md rename to addons/building.md diff --git a/api-docs/cc7ea2277aa43560db52f3fe797bbf5f562b5fc7363375cf3850d2a69a938417.md b/addons/c_addons.md similarity index 100% rename from api-docs/cc7ea2277aa43560db52f3fe797bbf5f562b5fc7363375cf3850d2a69a938417.md rename to addons/c_addons.md diff --git a/api-docs/bb3c878df179eb4e9cd3aa82455cf3c674652916c92f6931fe9fd77d857547b1.md b/addons/callbacks.md similarity index 100% rename from api-docs/bb3c878df179eb4e9cd3aa82455cf3c674652916c92f6931fe9fd77d857547b1.md rename to addons/callbacks.md diff --git a/api-docs/8ce70d6297ff0b3a74394670797e99a7dbcac6c3bf8944e48be3dd4e2dd320fb.md b/addons/context_aware_addons.md similarity index 100% rename from api-docs/8ce70d6297ff0b3a74394670797e99a7dbcac6c3bf8944e48be3dd4e2dd320fb.md rename to addons/context_aware_addons.md diff --git a/api-docs/2209f0f94d4e7be8a792ca5441eb8c7adc1d88402c3b485a87ef89743a07c0f6.md b/addons/factory_of_wrapped_objects.md similarity index 100% rename from api-docs/2209f0f94d4e7be8a792ca5441eb8c7adc1d88402c3b485a87ef89743a07c0f6.md rename to addons/factory_of_wrapped_objects.md diff --git a/api-docs/805149d5a438cdac32f011c5d0a8e231a9adb1d701f9b64840f04afa1000d9af.md b/addons/function_arguments.md similarity index 100% rename from api-docs/805149d5a438cdac32f011c5d0a8e231a9adb1d701f9b64840f04afa1000d9af.md rename to addons/function_arguments.md diff --git a/api-docs/86a9032d79d05a7ab693d9b17ca64dde1b6945e3440faee82fa9ef4f50f739ed.md b/addons/function_factory.md similarity index 100% rename from api-docs/86a9032d79d05a7ab693d9b17ca64dde1b6945e3440faee82fa9ef4f50f739ed.md rename to addons/function_factory.md diff --git a/api-docs/08d02b5653aa5c5019ed8d0927c59bafcd904377106800bea59e57de098ac407.md b/addons/hello_world.md similarity index 100% rename from api-docs/08d02b5653aa5c5019ed8d0927c59bafcd904377106800bea59e57de098ac407.md rename to addons/hello_world.md diff --git a/api-docs/4a49b515d409b1cdb6c5b58b9a5318c22117025c6925d4c04a0de7afc5a5e886.md b/addons/linking_to_node_js_own_dependencies.md similarity index 100% rename from api-docs/4a49b515d409b1cdb6c5b58b9a5318c22117025c6925d4c04a0de7afc5a5e886.md rename to addons/linking_to_node_js_own_dependencies.md diff --git a/api-docs/4188f8a3b40f8a707ae250daff0c403faff50be3dea058cf47a692a87169b462.md b/addons/loading_addons_using_require.md similarity index 100% rename from api-docs/4188f8a3b40f8a707ae250daff0c403faff50be3dea058cf47a692a87169b462.md rename to addons/loading_addons_using_require.md diff --git a/api-docs/689769679d3505e0ac4ec007406a01a91a3aafdefc11936a497123323ce0df44.md b/addons/n_api.md similarity index 100% rename from api-docs/689769679d3505e0ac4ec007406a01a91a3aafdefc11936a497123323ce0df44.md rename to addons/n_api.md diff --git a/api-docs/55783048481393f82c57275fcfd382b416104d4218020a58c89748402ca33d25.md b/addons/native_abstractions_for_node_js.md similarity index 100% rename from api-docs/55783048481393f82c57275fcfd382b416104d4218020a58c89748402ca33d25.md rename to addons/native_abstractions_for_node_js.md diff --git a/api-docs/e4e009215d34671bedc45fdbc5ba10843613b841b4d90eab607d36277a62fe6d.md b/addons/object_factory.md similarity index 100% rename from api-docs/e4e009215d34671bedc45fdbc5ba10843613b841b4d90eab607d36277a62fe6d.md rename to addons/object_factory.md diff --git a/api-docs/046c7232bb9c4cacd6799aea872a8ab332b785184f270b39a233aadc923dcdec.md b/addons/passing_wrapped_objects_around.md similarity index 100% rename from api-docs/046c7232bb9c4cacd6799aea872a8ab332b785184f270b39a233aadc923dcdec.md rename to addons/passing_wrapped_objects_around.md diff --git a/api-docs/c30f7677273ea20ab4bc72b3238edecf577431ed8102e34f68b34e7fc13a1452.md b/addons/void_atexit_callback_args.md similarity index 100% rename from api-docs/c30f7677273ea20ab4bc72b3238edecf577431ed8102e34f68b34e7fc13a1452.md rename to addons/void_atexit_callback_args.md diff --git a/api-docs/5acec414700c63086cb20889f9b02b21f542e169f20dbd4a226f366cde6e64b3.md b/addons/wrapping_c_objects.md similarity index 100% rename from api-docs/5acec414700c63086cb20889f9b02b21f542e169f20dbd4a226f366cde6e64b3.md rename to addons/wrapping_c_objects.md diff --git a/api-docs/0296d3432ebf3cc4ec9327ee1179db09a6060ad811a076c17e410ab7a28f3510.md b/api-docs/0296d3432ebf3cc4ec9327ee1179db09a6060ad811a076c17e410ab7a28f3510.md deleted file mode 100644 index d1d5cd52..00000000 --- a/api-docs/0296d3432ebf3cc4ec9327ee1179db09a6060ad811a076c17e410ab7a28f3510.md +++ /dev/null @@ -1,7 +0,0 @@ - -* `object` {Object} - -此方法用来写出某种宿主对象，进一步说，是由绑定的原生C++代码所生成的一个对象。 如果无法序列化`object`，那么一个恰当的异常会被抛出。 - -此方法在`Serializer`对象本身是不存在的，但可在其子类中提供。 - diff --git a/api-docs/0e467c61286d7133633f85f850cddce74d6b311ef1e88ea41ee8c6bb12103d07.md b/api-docs/0e467c61286d7133633f85f850cddce74d6b311ef1e88ea41ee8c6bb12103d07.md deleted file mode 100644 index 83e2cf3e..00000000 --- a/api-docs/0e467c61286d7133633f85f850cddce74d6b311ef1e88ea41ee8c6bb12103d07.md +++ /dev/null @@ -1,2 +0,0 @@ -读取并验证一个头文件（包含格式信息）。 -验证在某些情况下有可能不会通过，比如传输格式不合格或者不被支持。若发生上述情况，那么一个`Error`会被抛出。 diff --git a/api-docs/1b7ce85a5e43ea21acb6e922e1aee712aafbbd94c888b01f5bac7d3167893412.md b/api-docs/1b7ce85a5e43ea21acb6e922e1aee712aafbbd94c888b01f5bac7d3167893412.md deleted file mode 100644 index c475a35f..00000000 --- a/api-docs/1b7ce85a5e43ea21acb6e922e1aee712aafbbd94c888b01f5bac7d3167893412.md +++ /dev/null @@ -1,6 +0,0 @@ - - -`writeStream.clearScreenDown()` 从当前光标向下清除此 `WriteStream`。 - diff --git a/api-docs/20a3fd236093d810f8d2acb7f3b21cecba3f0479130216cdf4e0131bf7211480.md b/api-docs/20a3fd236093d810f8d2acb7f3b21cecba3f0479130216cdf4e0131bf7211480.md deleted file mode 100644 index f63f2940..00000000 --- a/api-docs/20a3fd236093d810f8d2acb7f3b21cecba3f0479130216cdf4e0131bf7211480.md +++ /dev/null @@ -1,5 +0,0 @@ - - -[`Serializer`][]的子类，用来将`TypedArray`(尤其是[`Buffer`][])和`Dataview`序列化成一个宿主对象，并且对于它们底层的`ArrayBuffer`，只有被它们实际指向的部分会被存储起来。 diff --git a/api-docs/23d4271b6edd4816803f03df5096d703b2739bb7b7d075d2523d4b640fa30516.md b/api-docs/23d4271b6edd4816803f03df5096d703b2739bb7b7d075d2523d4b640fa30516.md deleted file mode 100644 index 59cc6dbf..00000000 --- a/api-docs/23d4271b6edd4816803f03df5096d703b2739bb7b7d075d2523d4b640fa30516.md +++ /dev/null @@ -1,6 +0,0 @@ - -* `id` {integer} 一个32位的无符号整型。 -* `arrayBuffer` {ArrayBuffer} 一个`ArrayBuffer`实例。 - -标记一个`ArrayBuffer`, 表明它的内容正在被带外传输中。同时将`ArrayBuffer`包裹于一个反序列化的上下文内，之后将结果传入[`deserializer.transferArrayBuffer()`][]中。 - diff --git a/api-docs/2b0a91616953976437fe1689bb7d2c3e32bed6248ac47b6bda7bf9e75fdfbcf1.md b/api-docs/2b0a91616953976437fe1689bb7d2c3e32bed6248ac47b6bda7bf9e75fdfbcf1.md deleted file mode 100644 index 80c852e5..00000000 --- a/api-docs/2b0a91616953976437fe1689bb7d2c3e32bed6248ac47b6bda7bf9e75fdfbcf1.md +++ /dev/null @@ -1,7 +0,0 @@ - -* `hi` {integer} -* `lo` {integer} - -写出一个原始64位无符号整型，会被拆分成高32位和低32位两部分。 -此方法用于一个自定义的[`serializer._writeHostObject()`][]. - diff --git a/api-docs/2dc8208af99f28f9e98eecb5030a3949d8e4a1200271b7b72270d33237cd1b8e.md b/api-docs/2dc8208af99f28f9e98eecb5030a3949d8e4a1200271b7b72270d33237cd1b8e.md deleted file mode 100644 index d9e8e8e9..00000000 --- a/api-docs/2dc8208af99f28f9e98eecb5030a3949d8e4a1200271b7b72270d33237cd1b8e.md +++ /dev/null @@ -1,15 +0,0 @@ - - -* `historyPath` {string} 历史文件的路径。 -* `callback` {Function} 当历史记录写入已准备好或出错时调用。 - * `err` {Error} - * `repl` {repl.REPLServer} - -Initializes a history log file for the REPL instance. When executing the -Node.js binary and using the command line REPL, a history file is initialized -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. - diff --git a/api-docs/2f18b5882118d556a2821ab56569c4ba30a70fdbf2a58bc112ea9b24f31e4ac1.md b/api-docs/2f18b5882118d556a2821ab56569c4ba30a70fdbf2a58bc112ea9b24f31e4ac1.md deleted file mode 100644 index 2398a3f0..00000000 --- a/api-docs/2f18b5882118d556a2821ab56569c4ba30a70fdbf2a58bc112ea9b24f31e4ac1.md +++ /dev/null @@ -1,9 +0,0 @@ - - -* `x` {number} -* `y` {number} - -`writeStream.cursorTo()` 将 `WriteStream` 的光标移动到指定的位置。 - diff --git a/api-docs/2f1e6ca3b7d28cfb5401cb77109a394fab1bad4abb2b6d70eb13386ecf1167d4.md b/api-docs/2f1e6ca3b7d28cfb5401cb77109a394fab1bad4abb2b6d70eb13386ecf1167d4.md deleted file mode 100644 index 1d6f614e..00000000 --- a/api-docs/2f1e6ca3b7d28cfb5401cb77109a394fab1bad4abb2b6d70eb13386ecf1167d4.md +++ /dev/null @@ -1,2 +0,0 @@ -创建一个新的`Serializer`对象。 - diff --git a/api-docs/37e842146b9f89ea72695272ce179ed80eeb63f6c62fd6aaf5ecf165f734875e.md b/api-docs/37e842146b9f89ea72695272ce179ed80eeb63f6c62fd6aaf5ecf165f734875e.md deleted file mode 100644 index 9840aea8..00000000 --- a/api-docs/37e842146b9f89ea72695272ce179ed80eeb63f6c62fd6aaf5ecf165f734875e.md +++ /dev/null @@ -1,8 +0,0 @@ - -* `sharedArrayBuffer` {SharedArrayBuffer} - -当序列化机制将要序列化一个`ShareArrayBuffer`对象时会调用此方法。它必须为这对象返回一个32位无符号整型的ID，但若这个对象已被序列化过，则返回上一次序列化时所分配的ID。这个ID会在对象被反序列化时传入[`deserializer.transferArrayBuffer()`][]中。 - -如果对象不能被序列化，则抛出异常。 - -`Serializer`类本身不包含此方法，但可以在其子类中设置它。 diff --git a/api-docs/3ddd41c82bbfc7f513c729f97e4a2a0ee230bbccb5a2075040ab5aef44cb40ec.md b/api-docs/3ddd41c82bbfc7f513c729f97e4a2a0ee230bbccb5a2075040ab5aef44cb40ec.md deleted file mode 100644 index b8db8107..00000000 --- a/api-docs/3ddd41c82bbfc7f513c729f97e4a2a0ee230bbccb5a2075040ab5aef44cb40ec.md +++ /dev/null @@ -1,9 +0,0 @@ - - -* `dx` {number} -* `dy` {number} - -`writeStream.moveCursor()` 将 `WriteStream` 的光标相对于其当前位置移动。 - diff --git a/api-docs/411f21e59a7283e3072605634631ea1666b31cdf0cca7bf319dcce74e06b6324.md b/api-docs/411f21e59a7283e3072605634631ea1666b31cdf0cca7bf319dcce74e06b6324.md deleted file mode 100644 index 47711fc2..00000000 --- a/api-docs/411f21e59a7283e3072605634631ea1666b31cdf0cca7bf319dcce74e06b6324.md +++ /dev/null @@ -1,5 +0,0 @@ - -* Returns: {integer} - -读取并返回一个原始32位无符号整型。 -用于一个自定义的[`deserializer._readHostObject()`][]。 diff --git a/api-docs/419668a6c02565035c2c246053580df6e24f07977d47994f9de6601e2be014ca.md b/api-docs/419668a6c02565035c2c246053580df6e24f07977d47994f9de6601e2be014ca.md deleted file mode 100644 index 8c553f36..00000000 --- a/api-docs/419668a6c02565035c2c246053580df6e24f07977d47994f9de6601e2be014ca.md +++ /dev/null @@ -1,7 +0,0 @@ - -* `flag` {boolean} - -表明是否视`TypedArray`，`DataView`对象为宿主对象，也就是说，是否能将他们传入[`serializer._writeHostObject()`][]中。 - -默认以上对象非宿主对象。 - diff --git a/api-docs/47d1485bfa79f0eb8bbe68761ead48c9bb23ee9b470162df8ddbe8c40c973255.md b/api-docs/47d1485bfa79f0eb8bbe68761ead48c9bb23ee9b470162df8ddbe8c40c973255.md deleted file mode 100644 index 1bbe91c7..00000000 --- a/api-docs/47d1485bfa79f0eb8bbe68761ead48c9bb23ee9b470162df8ddbe8c40c973255.md +++ /dev/null @@ -1,4 +0,0 @@ -1. 任何指定的文件描述符都必须支持写入。 -2. 如果将文件描述符指定为 `file`，则不会自动关闭它。 -3. 写入将从文件的开头开始。例如，如果文件已经有内容 `'Hello World`' 并且新写入的内容是 `'Aloha'`，则该文件的内容将是 `'Aloha World'` 而不仅仅是 `'Aloha'`。 - diff --git a/api-docs/539a24ad01d4a8e55452ab34b52b290c598ddc7cadcd447373da345ff72d86ea.md b/api-docs/539a24ad01d4a8e55452ab34b52b290c598ddc7cadcd447373da345ff72d86ea.md deleted file mode 100644 index c848b69c..00000000 --- a/api-docs/539a24ad01d4a8e55452ab34b52b290c598ddc7cadcd447373da345ff72d86ea.md +++ /dev/null @@ -1,3 +0,0 @@ - -写出一个包含序列化格式版本的头文件 - diff --git a/api-docs/58ad332907022a3a5dc9c2948a69db824ad77ac26c8c3d407e8526c41604c1a6.md b/api-docs/58ad332907022a3a5dc9c2948a69db824ad77ac26c8c3d407e8526c41604c1a6.md deleted file mode 100644 index 20598741..00000000 --- a/api-docs/58ad332907022a3a5dc9c2948a69db824ad77ac26c8c3d407e8526c41604c1a6.md +++ /dev/null @@ -1,2 +0,0 @@ -返回存储里的内部缓冲区。若缓冲区已经被释放则不应该使用此序列化机制。如果之前的一次写入操作失败，那么执行此方法会造成不可预知的行为。 - diff --git a/api-docs/602b0ec7400b25a259764abd9ac26b1b6b58200427bbff3bc73619edb657a129.md b/api-docs/602b0ec7400b25a259764abd9ac26b1b6b58200427bbff3bc73619edb657a129.md deleted file mode 100644 index ba4a83e5..00000000 --- a/api-docs/602b0ec7400b25a259764abd9ac26b1b6b58200427bbff3bc73619edb657a129.md +++ /dev/null @@ -1,12 +0,0 @@ - - -* `stream` {stream.Writable} -* `dir` {number} - * `-1` - 从光标向左。 - * `1` - 从光标向右 - * `0` - 整行。 - -`readline.clearLine()` 方法在由 `dir` 标识的指定方向上清除给定的 [TTY] 流的当前行。 - diff --git a/api-docs/628d48b9f9b51f649838dd7de62503b643a554f6a96df6c3fbb349afb2faabc3.md b/api-docs/628d48b9f9b51f649838dd7de62503b643a554f6a96df6c3fbb349afb2faabc3.md deleted file mode 100644 index cd3a01b1..00000000 --- a/api-docs/628d48b9f9b51f649838dd7de62503b643a554f6a96df6c3fbb349afb2faabc3.md +++ /dev/null @@ -1,10 +0,0 @@ - - -* `stream` {stream.Writable} -* `x` {number} -* `y` {number} - -`readline.cursorTo()` 方法将光标移动到给定的 [TTY] `stream` 中的指定位置。 - diff --git a/api-docs/71bac2fa9a621974f7bf30f4bb23c9f8bba9428cccdaf92f1e124bedf572d396.md b/api-docs/71bac2fa9a621974f7bf30f4bb23c9f8bba9428cccdaf92f1e124bedf572d396.md deleted file mode 100644 index df30ac26..00000000 --- a/api-docs/71bac2fa9a621974f7bf30f4bb23c9f8bba9428cccdaf92f1e124bedf572d396.md +++ /dev/null @@ -1,5 +0,0 @@ - -* `id` {integer} 一个 32 位无符号整型 -* `arrayBuffer` {ArrayBuffer|SharedArrayBuffer} `ArrayBuffer`实例 - -标记一个`ArrayBuffer`, 表明它的内容正在被带外传输中。同时将`ArrayBuffer`包裹于一个序列化的上下文内，之后将结果传入[`serializer.transferArrayBuffer()`][]中（当`arrayBuffer`是`ShareArrayBuffer`实例时，返回[`serializer._getSharedArrayBufferId()`][]产生的`id`） diff --git a/api-docs/79fdca7145f11d6a0f3d499e0eea6b4d42019b1eefc9e1267f6b7147de3d25a0.md b/api-docs/79fdca7145f11d6a0f3d499e0eea6b4d42019b1eefc9e1267f6b7147de3d25a0.md deleted file mode 100644 index c41038c8..00000000 --- a/api-docs/79fdca7145f11d6a0f3d499e0eea6b4d42019b1eefc9e1267f6b7147de3d25a0.md +++ /dev/null @@ -1,10 +0,0 @@ - -使用以下环境变量，可以自定义 Node.js REPL 的各种行为： - - - `NODE_REPL_HISTORY` - 当给定了一个有效的路径，则 REPL 的历史记录将被保存到指定的文件，而不是用户目录下的 `.node_repl_history` 文件。 - 设为 `''` 将禁用 REPL 历史记录。 - 值两头的空格键会被去掉。 - - `NODE_REPL_HISTORY_SIZE` - 默认为 `1000`。控制历史记录的最大行数。必须是正数。 - - `NODE_REPL_MODE` - 可以是 `'sloppy'` 或 `'strict'`。 -  默认是 `'sloppy'`, 在 `'sloppy'` 模式下，允许代码在非严格模式下运行。 - diff --git a/api-docs/867f3049f468fb1cf31b2381d51684028ca3d3ad01a38c1b1f8943c296edc95a.md b/api-docs/867f3049f468fb1cf31b2381d51684028ca3d3ad01a38c1b1f8943c296edc95a.md deleted file mode 100644 index 75efcaf2..00000000 --- a/api-docs/867f3049f468fb1cf31b2381d51684028ca3d3ad01a38c1b1f8943c296edc95a.md +++ /dev/null @@ -1,8 +0,0 @@ - - -* `buffer` {Buffer|Uint8Array} 由[`serialize()`][]返回的一个缓冲区。 - -用默认配置来执行[`DefaultDeserializer`][]从而从一个缓冲区中读取一个JS值 - diff --git a/api-docs/8b4e81ae56fff658457895f39c00922a1719170caf31c56780da204c7ab1c2d5.md b/api-docs/8b4e81ae56fff658457895f39c00922a1719170caf31c56780da204c7ab1c2d5.md deleted file mode 100644 index c93feb8d..00000000 --- a/api-docs/8b4e81ae56fff658457895f39c00922a1719170caf31c56780da204c7ab1c2d5.md +++ /dev/null @@ -1,8 +0,0 @@ - -> 稳定性: 1 - 实验性质 - -序列化API提供了一系列用于序列化JavaScript值的方法，它们兼容于[HTML structured clone algorithm][]。 -格式是向下兼容的（可以安心存储于硬盘中）。 - -*注意*: 此API正在开发中，任何变化（包括不兼容的API或者传输格式）可能会随时发生直到此警告被移除。 - diff --git a/api-docs/9bcff233489fc34daf7ab62ab593aaf5c553679ee33fa7c062a87f7ca622cdec.md b/api-docs/9bcff233489fc34daf7ab62ab593aaf5c553679ee33fa7c062a87f7ca622cdec.md deleted file mode 100644 index 6e1cd0fb..00000000 --- a/api-docs/9bcff233489fc34daf7ab62ab593aaf5c553679ee33fa7c062a87f7ca622cdec.md +++ /dev/null @@ -1,5 +0,0 @@ - -* Returns: {Array} - -读取一个原始64位无符号整型，将其拆分成一个包含两个32位无符号整型的`[hi, lo]`数组，并返回此数组。 -用于一个自定义的[`deserializer._readHostObject()`][]。 diff --git a/api-docs/9c309ce0dfc809863c6c2f09673477fa6af0ee39eccbaf5a751b6faba570301b.md b/api-docs/9c309ce0dfc809863c6c2f09673477fa6af0ee39eccbaf5a751b6faba570301b.md deleted file mode 100644 index 9a29e070..00000000 --- a/api-docs/9c309ce0dfc809863c6c2f09673477fa6af0ee39eccbaf5a751b6faba570301b.md +++ /dev/null @@ -1,11 +0,0 @@ - - -* `dir` {number} - * `-1` - 从光标向左。 - * `1` - 从光标向右。 - * `0` - 整行。 - -`writeStream.clearLine()` 在 `dir` 标识的方向上清除此 `WriteStream` 的当前行。 - diff --git a/api-docs/9cd0c345c3af10628742d58b7bd9ff17d4ee529d8db40ea319fc44d042be6b55.md b/api-docs/9cd0c345c3af10628742d58b7bd9ff17d4ee529d8db40ea319fc44d042be6b55.md deleted file mode 100644 index c61697c0..00000000 --- a/api-docs/9cd0c345c3af10628742d58b7bd9ff17d4ee529d8db40ea319fc44d042be6b55.md +++ /dev/null @@ -1,5 +0,0 @@ - -* `buffer` {Buffer|Uint8Array} - -将原始字节写入序列化机制的内部缓冲区中。反序列化机制会有对应的方法来获得缓冲区的长度。 -此方法用于一个自定义的[`serializer._writeHostObject()`][]中。 diff --git a/api-docs/a0efcee453a03f6e5b54977e4c6800634e9f93c4a69763fe87efdf56c85984c9.md b/api-docs/a0efcee453a03f6e5b54977e4c6800634e9f93c4a69763fe87efdf56c85984c9.md deleted file mode 100644 index 79814f13..00000000 --- a/api-docs/a0efcee453a03f6e5b54977e4c6800634e9f93c4a69763fe87efdf56c85984c9.md +++ /dev/null @@ -1,6 +0,0 @@ - -* `message` {string} - -当一个对象无法被克隆时，会使用此方法来生成待抛出的错误对象。 - -此方法默认为[`Error`][]的构造函数，可以在子类中被覆盖。 diff --git a/api-docs/a1e0a1d320409147193511a2b61462abda4e91de682f681cfca82648cd899dbc.md b/api-docs/a1e0a1d320409147193511a2b61462abda4e91de682f681cfca82648cd899dbc.md deleted file mode 100644 index 96e27b31..00000000 --- a/api-docs/a1e0a1d320409147193511a2b61462abda4e91de682f681cfca82648cd899dbc.md +++ /dev/null @@ -1,6 +0,0 @@ - -* `value` {number} - -写出一个JS的`number`值。 -从方法用于一个自定义的[`serializer._writeHostObject()`][]. - diff --git a/api-docs/adbe31a7869e361e2da58b150291843a0456857004ecef173d4dcfd91ca1aff8.md b/api-docs/adbe31a7869e361e2da58b150291843a0456857004ecef173d4dcfd91ca1aff8.md deleted file mode 100644 index fa1fd996..00000000 --- a/api-docs/adbe31a7869e361e2da58b150291843a0456857004ecef173d4dcfd91ca1aff8.md +++ /dev/null @@ -1,10 +0,0 @@ - - -* `stream` {stream.Writable} -* `dx` {number} -* `dy` {number} - -`readline.moveCursor()` 方法相对于给定的 [TTY] `stream` 中的当前位置移动光标。 - diff --git a/api-docs/c0dc9f6a5678222bc5a4a40c488225b62a44612590697dcbfa9ff8d7c8d44362.md b/api-docs/c0dc9f6a5678222bc5a4a40c488225b62a44612590697dcbfa9ff8d7c8d44362.md deleted file mode 100644 index dcec2510..00000000 --- a/api-docs/c0dc9f6a5678222bc5a4a40c488225b62a44612590697dcbfa9ff8d7c8d44362.md +++ /dev/null @@ -1,8 +0,0 @@ - - -* `stream` {stream.Writable} - -`readline.clearScreenDown()` 方法从光标的当前位置向下清除给定的 [TTY] 流。 - diff --git a/api-docs/cb3d675ca91e8071f95beb2be37359bfbd42a1637263a6eb0964e3cfc92b187c.md b/api-docs/cb3d675ca91e8071f95beb2be37359bfbd42a1637263a6eb0964e3cfc92b187c.md deleted file mode 100644 index a36a4e51..00000000 --- a/api-docs/cb3d675ca91e8071f95beb2be37359bfbd42a1637263a6eb0964e3cfc92b187c.md +++ /dev/null @@ -1,3 +0,0 @@ -序列化一个JavaScript值并将结果加入内部的缓冲区。 - -如果`value`不能被序列化则抛出错误。 diff --git a/api-docs/d00ba183c4663402a59f3b8141fb87a4d755179bba49abb8dfdc4e8cb533e431.md b/api-docs/d00ba183c4663402a59f3b8141fb87a4d755179bba49abb8dfdc4e8cb533e431.md deleted file mode 100644 index 8292ca91..00000000 --- a/api-docs/d00ba183c4663402a59f3b8141fb87a4d755179bba49abb8dfdc4e8cb533e431.md +++ /dev/null @@ -1,5 +0,0 @@ - -* Returns: {number} - -读取一个JS`number`值。 -用于一个自定义的[`deserializer._readHostObject()`][]。 diff --git a/api-docs/d2fa01d97f88d993ce983fd9379b714fca5fef5db39a941ec6585c845e92a82c.md b/api-docs/d2fa01d97f88d993ce983fd9379b714fca5fef5db39a941ec6585c845e92a82c.md deleted file mode 100644 index 3ca27ca6..00000000 --- a/api-docs/d2fa01d97f88d993ce983fd9379b714fca5fef5db39a941ec6585c845e92a82c.md +++ /dev/null @@ -1,5 +0,0 @@ - -* Returns: {Buffer} - -从反序列化机制的内部缓冲区中读取原始字节。`length`必须和传入[`serializer.writeRawBytes()`][]中的缓冲区的长度相符。 -用于一个自定义的[`serializer.writeRawBytes()`][]。 diff --git a/api-docs/d87df6557047b494cbb63f81f8101aa2c5cb1da2f4b893ee4870a14e62012b75.md b/api-docs/d87df6557047b494cbb63f81f8101aa2c5cb1da2f4b893ee4870a14e62012b75.md deleted file mode 100644 index 4381fad4..00000000 --- a/api-docs/d87df6557047b494cbb63f81f8101aa2c5cb1da2f4b893ee4870a14e62012b75.md +++ /dev/null @@ -1,4 +0,0 @@ - -* `buffer` {Buffer|Uint8Array} 由[`serializer.releaseBuffer()`][]返回的缓冲区 - -生成一个新的`Deserializer`对象。 diff --git a/api-docs/deeb81afca2e354fc9ce75bee634518993f47c846ca82d6a3a40f3d4c7f76bf0.md b/api-docs/deeb81afca2e354fc9ce75bee634518993f47c846ca82d6a3a40f3d4c7f76bf0.md deleted file mode 100644 index bdb75002..00000000 --- a/api-docs/deeb81afca2e354fc9ce75bee634518993f47c846ca82d6a3a40f3d4c7f76bf0.md +++ /dev/null @@ -1,6 +0,0 @@ - -* `value` {integer} - -写出一个原始32位无符号整型。 -此方法在一个自定义的[`serializer._writeHostObject()`][]中使用. - diff --git a/api-docs/e192547b8a4692efa2c0720a6af7620e8eb959b9a39cb1559087d10fb9bc08de.md b/api-docs/e192547b8a4692efa2c0720a6af7620e8eb959b9a39cb1559087d10fb9bc08de.md deleted file mode 100644 index ea306df9..00000000 --- a/api-docs/e192547b8a4692efa2c0720a6af7620e8eb959b9a39cb1559087d10fb9bc08de.md +++ /dev/null @@ -1,4 +0,0 @@ - -* Returns: {integer} - -读取底层的传输格式的版本。很可能有助于遗留代码来读取旧的传输格式版本。不可在`.readHeader()`之前调用此方法。 diff --git a/api-docs/e5952efb1c7daeb169cfb0d58a73e21eaec70436cdf4e475beca0d9c7b4fdc17.md b/api-docs/e5952efb1c7daeb169cfb0d58a73e21eaec70436cdf4e475beca0d9c7b4fdc17.md deleted file mode 100644 index 7ab24190..00000000 --- a/api-docs/e5952efb1c7daeb169cfb0d58a73e21eaec70436cdf4e475beca0d9c7b4fdc17.md +++ /dev/null @@ -1,8 +0,0 @@ - - -* Returns: {Buffer} - -使用[`DefaultSerializer`][]来序列化`value`到一个缓冲区中。 - diff --git a/api-docs/e8517f3cadef213efc478a4cbfde2b834416b171fe7b7f5a6a28add40d4b0718.md b/api-docs/e8517f3cadef213efc478a4cbfde2b834416b171fe7b7f5a6a28add40d4b0718.md deleted file mode 100644 index 4e9e073c..00000000 --- a/api-docs/e8517f3cadef213efc478a4cbfde2b834416b171fe7b7f5a6a28add40d4b0718.md +++ /dev/null @@ -1,3 +0,0 @@ -此方法用来写出某种宿主对象，进一步说，是由绑定的原生C++代码所生成的一个对象。 如果无法序列化数据，那么一个恰当的异常会被抛出。 - -此方法在`Deserializer`对象本身上是不存在的，但可有其子类提供。 diff --git a/api-docs/ec0c2ac556ce39592ee1cc4fde996f84d64b3598590530442cd41cf3634c75e3.md b/api-docs/ec0c2ac556ce39592ee1cc4fde996f84d64b3598590530442cd41cf3634c75e3.md deleted file mode 100644 index 93f20903..00000000 --- a/api-docs/ec0c2ac556ce39592ee1cc4fde996f84d64b3598590530442cd41cf3634c75e3.md +++ /dev/null @@ -1,2 +0,0 @@ - -从缓冲区中反序列化一个JavaScript值，并返回它。 diff --git a/api-docs/90a72bdeb52f3f7fa2bc4dcc8bc52e89a1e176ffbd4a8715a2129570b27aa062.md b/assert/assert.md similarity index 100% rename from api-docs/90a72bdeb52f3f7fa2bc4dcc8bc52e89a1e176ffbd4a8715a2129570b27aa062.md rename to assert/assert.md diff --git a/assert/assert_deepequal_actual_expected_message.md b/assert/assert_deepequal_actual_expected_message.md new file mode 100644 index 00000000..e12a9108 --- /dev/null +++ b/assert/assert_deepequal_actual_expected_message.md @@ -0,0 +1,95 @@ + +* `actual` {any} +* `expected` {any} +* `message` {string|Error} + +**Strict mode** + +An alias of [`assert.deepStrictEqual()`][]. + +**Legacy mode** + +> Stability: 0 - Deprecated: Use [`assert.deepStrictEqual()`][] instead. + +Tests for deep equality between the `actual` and `expected` parameters. +Primitive values are compared with the [Abstract Equality Comparison][] +( `==` ). + +Only [enumerable "own" properties][] are considered. The +[`assert.deepEqual()`][] implementation does not test the +[`[[Prototype]]`][prototype-spec] of objects or enumerable own [`Symbol`][] +properties. For such checks, consider using [`assert.deepStrictEqual()`][] +instead. [`assert.deepEqual()`][] can have potentially surprising results. The +following example does not throw an `AssertionError` because the properties on +the [`RegExp`][] object are not enumerable: + +```js +// WARNING: This does not throw an AssertionError! +assert.deepEqual(/a/gi, new Date()); +``` + +An exception is made for [`Map`][] and [`Set`][]. `Map`s and `Set`s have their +contained items compared too, as expected. + +"Deep" equality means that the enumerable "own" properties of child objects +are evaluated also: + +```js +const assert = require('assert'); + +const obj1 = { + a: { + b: 1 + } +}; +const obj2 = { + a: { + b: 2 + } +}; +const obj3 = { + a: { + b: 1 + } +}; +const obj4 = Object.create(obj1); + +assert.deepEqual(obj1, obj1); +// OK + +// Values of b are different: +assert.deepEqual(obj1, obj2); +// AssertionError: { a: { b: 1 } } deepEqual { a: { b: 2 } } + +assert.deepEqual(obj1, obj3); +// OK + +// Prototypes are ignored: +assert.deepEqual(obj1, obj4); +// AssertionError: { a: { b: 1 } } deepEqual {} +``` + +If the values are not equal, 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`. + diff --git a/api-docs/9b2728f6df6f72f07be7173740fc63fd17d890eed8c56cedc60c1e2061126f64.md b/assert/assert_deepstrictequal_actual_expected_message.md similarity index 100% rename from api-docs/9b2728f6df6f72f07be7173740fc63fd17d890eed8c56cedc60c1e2061126f64.md rename to assert/assert_deepstrictequal_actual_expected_message.md diff --git a/api-docs/c25ab77fc47054d96a53ff81e58f896a9b7e52c02185b76b535b538674464392.md b/assert/assert_doesnotreject_asyncfn_error_message.md similarity index 100% rename from api-docs/c25ab77fc47054d96a53ff81e58f896a9b7e52c02185b76b535b538674464392.md rename to assert/assert_doesnotreject_asyncfn_error_message.md diff --git a/api-docs/4d0d92f57a080c7a07bdf81695789892657442323cf3d5b170e00b16dfea2612.md b/assert/assert_doesnotthrow_fn_error_message.md similarity index 100% rename from api-docs/4d0d92f57a080c7a07bdf81695789892657442323cf3d5b170e00b16dfea2612.md rename to assert/assert_doesnotthrow_fn_error_message.md diff --git a/assert/assert_equal_actual_expected_message.md b/assert/assert_equal_actual_expected_message.md new file mode 100644 index 00000000..fa763d66 --- /dev/null +++ b/assert/assert_equal_actual_expected_message.md @@ -0,0 +1,38 @@ + +* `actual` {any} +* `expected` {any} +* `message` {string|Error} + +**Strict mode** + +An alias of [`assert.strictEqual()`][]. + +**Legacy mode** + +> Stability: 0 - Deprecated: Use [`assert.strictEqual()`][] instead. + +Tests shallow, coercive equality between the `actual` and `expected` parameters +using the [Abstract Equality Comparison][] ( `==` ). + +```js +const assert = require('assert'); + +assert.equal(1, 1); +// OK, 1 == 1 +assert.equal(1, '1'); +// OK, 1 == '1' + +assert.equal(1, 2); +// AssertionError: 1 == 2 +assert.equal({ a: { b: 1 } }, { a: { b: 1 } }); +// AssertionError: { a: { b: 1 } } == { a: { b: 1 } } +``` + +If the values are not equal, 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`. + diff --git a/assert/assert_fail_actual_expected_message_operator_stackstartfn.md b/assert/assert_fail_actual_expected_message_operator_stackstartfn.md new file mode 100644 index 00000000..c7771a4b --- /dev/null +++ b/assert/assert_fail_actual_expected_message_operator_stackstartfn.md @@ -0,0 +1,61 @@ + +* `actual` {any} +* `expected` {any} +* `message` {string|Error} +* `operator` {string} **Default:** `'!='` +* `stackStartFn` {Function} **Default:** `assert.fail` + +> Stability: 0 - Deprecated: Use `assert.fail([message])` or other assert +> functions instead. + +If `message` is falsy, the error message is set as the values of `actual` and +`expected` separated by the provided `operator`. If just the two `actual` and +`expected` arguments are provided, `operator` will default to `'!='`. If +`message` is provided as third argument it will be used as the error message and +the other arguments will be stored as properties on the thrown object. If +`stackStartFn` is provided, all stack frames above that function will be +removed from stacktrace (see [`Error.captureStackTrace`]). If no arguments are +given, the default message `Failed` will be used. + +```js +const assert = require('assert').strict; + +assert.fail('a', 'b'); +// AssertionError [ERR_ASSERTION]: 'a' != 'b' + +assert.fail(1, 2, undefined, '>'); +// AssertionError [ERR_ASSERTION]: 1 > 2 + +assert.fail(1, 2, 'fail'); +// AssertionError [ERR_ASSERTION]: fail + +assert.fail(1, 2, 'whoops', '>'); +// AssertionError [ERR_ASSERTION]: whoops + +assert.fail(1, 2, new TypeError('need array')); +// TypeError: need array +``` + +In the last three cases `actual`, `expected`, and `operator` have no +influence on the error message. + +Example use of `stackStartFn` for truncating the exception's stacktrace: + +```js +function suppressFrame() { + assert.fail('a', 'b', undefined, '!==', suppressFrame); +} +suppressFrame(); +// AssertionError [ERR_ASSERTION]: 'a' !== 'b' +// at repl:1:1 +// at ContextifyScript.Script.runInThisContext (vm.js:44:33) +// ... +``` + diff --git a/api-docs/ecca09531fe55beeb3ba868643fcedcb964c21786dcf5aa3d56391c5de893067.md b/assert/assert_fail_message.md similarity index 100% rename from api-docs/ecca09531fe55beeb3ba868643fcedcb964c21786dcf5aa3d56391c5de893067.md rename to assert/assert_fail_message.md diff --git a/api-docs/f152aa66c02a17ddfafe3fefc283c7f1806a5ed6f2e6003b8c0ed91af17527d2.md b/assert/assert_iferror_value.md similarity index 100% rename from api-docs/f152aa66c02a17ddfafe3fefc283c7f1806a5ed6f2e6003b8c0ed91af17527d2.md rename to assert/assert_iferror_value.md diff --git a/assert/assert_notdeepequal_actual_expected_message.md b/assert/assert_notdeepequal_actual_expected_message.md new file mode 100644 index 00000000..51fafc94 --- /dev/null +++ b/assert/assert_notdeepequal_actual_expected_message.md @@ -0,0 +1,72 @@ + +* `actual` {any} +* `expected` {any} +* `message` {string|Error} + +**Strict mode** + +An alias of [`assert.notDeepStrictEqual()`][]. + +**Legacy mode** + +> Stability: 0 - Deprecated: Use [`assert.notDeepStrictEqual()`][] instead. + +Tests for any deep inequality. Opposite of [`assert.deepEqual()`][]. + +```js +const assert = require('assert'); + +const obj1 = { + a: { + b: 1 + } +}; +const obj2 = { + a: { + b: 2 + } +}; +const obj3 = { + a: { + b: 1 + } +}; +const obj4 = Object.create(obj1); + +assert.notDeepEqual(obj1, obj1); +// AssertionError: { a: { b: 1 } } notDeepEqual { a: { b: 1 } } + +assert.notDeepEqual(obj1, obj2); +// OK + +assert.notDeepEqual(obj1, obj3); +// AssertionError: { a: { b: 1 } } notDeepEqual { a: { b: 1 } } + +assert.notDeepEqual(obj1, obj4); +// OK +``` + +If the values are deeply equal, 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`. + diff --git a/api-docs/b6fe4fdd8333613c34403035460748cc7420c012f9535acacfd6aab057866b83.md b/assert/assert_notdeepstrictequal_actual_expected_message.md similarity index 100% rename from api-docs/b6fe4fdd8333613c34403035460748cc7420c012f9535acacfd6aab057866b83.md rename to assert/assert_notdeepstrictequal_actual_expected_message.md diff --git a/assert/assert_notequal_actual_expected_message.md b/assert/assert_notequal_actual_expected_message.md new file mode 100644 index 00000000..2f9a846e --- /dev/null +++ b/assert/assert_notequal_actual_expected_message.md @@ -0,0 +1,37 @@ + +* `actual` {any} +* `expected` {any} +* `message` {string|Error} + +**Strict mode** + +An alias of [`assert.notStrictEqual()`][]. + +**Legacy mode** + +> Stability: 0 - Deprecated: Use [`assert.notStrictEqual()`][] instead. + +Tests shallow, coercive inequality with the [Abstract Equality Comparison][] +( `!=` ). + +```js +const assert = require('assert'); + +assert.notEqual(1, 2); +// OK + +assert.notEqual(1, 1); +// AssertionError: 1 != 1 + +assert.notEqual(1, '1'); +// AssertionError: 1 != '1' +``` + +If the values are equal, 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`. + diff --git a/api-docs/86bce27993a2e64909accf40c955d5648e857b0def78c975ce7cd06624f1897e.md b/assert/assert_notstrictequal_actual_expected_message.md similarity index 100% rename from api-docs/86bce27993a2e64909accf40c955d5648e857b0def78c975ce7cd06624f1897e.md rename to assert/assert_notstrictequal_actual_expected_message.md diff --git a/api-docs/6aed4b39018a0243817c669d35baa073846a96afbe9e15b8585ed9faf85ef167.md b/assert/assert_ok_value_message.md similarity index 100% rename from api-docs/6aed4b39018a0243817c669d35baa073846a96afbe9e15b8585ed9faf85ef167.md rename to assert/assert_ok_value_message.md diff --git a/api-docs/672e694eef186f816b2037d23c162841dca14e78d5a4deba411bfbb70e8eded7.md b/assert/assert_rejects_asyncfn_error_message.md similarity index 100% rename from api-docs/672e694eef186f816b2037d23c162841dca14e78d5a4deba411bfbb70e8eded7.md rename to assert/assert_rejects_asyncfn_error_message.md diff --git a/api-docs/1fac2e6cd6944a5ac8bfcd31b08907d1fbe4372f286ba1e91eece2a1ae40bf34.md b/assert/assert_strictequal_actual_expected_message.md similarity index 100% rename from api-docs/1fac2e6cd6944a5ac8bfcd31b08907d1fbe4372f286ba1e91eece2a1ae40bf34.md rename to assert/assert_strictequal_actual_expected_message.md diff --git a/api-docs/e0e29e3db0aee36b75e0b72cd6048e923b05eaf209784843bd829ee16b7c6718.md b/assert/assert_throws_fn_error_message.md similarity index 100% rename from api-docs/e0e29e3db0aee36b75e0b72cd6048e923b05eaf209784843bd829ee16b7c6718.md rename to assert/assert_throws_fn_error_message.md diff --git a/api-docs/7115e9ac826f58e675f453c5d4d271f7c50dee6e8e8448b4b5f019d14ae94a78.md b/assert/assert_value_message.md similarity index 100% rename from api-docs/7115e9ac826f58e675f453c5d4d271f7c50dee6e8e8448b4b5f019d14ae94a78.md rename to assert/assert_value_message.md diff --git a/api-docs/b620070d910ae9eb862160848bc72a0429278d1f305c084425d066e11b320406.md b/assert/class_assert_assertionerror.md similarity index 100% rename from api-docs/b620070d910ae9eb862160848bc72a0429278d1f305c084425d066e11b320406.md rename to assert/class_assert_assertionerror.md diff --git a/api-docs/b01cfa46995b823aa01157ecf9da5e09372765e0fc6b3596d75cde5e3a3dc910.md b/assert/comparison_details.md similarity index 100% rename from api-docs/b01cfa46995b823aa01157ecf9da5e09372765e0fc6b3596d75cde5e3a3dc910.md rename to assert/comparison_details.md diff --git a/api-docs/042fb55f582eb7ecac57389a7516c6879f0932a07147d67141ad43dfc23c1add.md b/assert/legacy_mode.md similarity index 100% rename from api-docs/042fb55f582eb7ecac57389a7516c6879f0932a07147d67141ad43dfc23c1add.md rename to assert/legacy_mode.md diff --git a/api-docs/4e370d1ca0b7f4d09799adfb40a785ef4e61a1bb995d8651a718610904225482.md b/assert/new_assert_assertionerror_options.md similarity index 100% rename from api-docs/4e370d1ca0b7f4d09799adfb40a785ef4e61a1bb995d8651a718610904225482.md rename to assert/new_assert_assertionerror_options.md diff --git a/api-docs/92c0c99d5eea1aeb1baab16d81e5b481a4bdb5734f2e206bf0ffe8c64f7af97e.md b/assert/strict_mode.md similarity index 100% rename from api-docs/92c0c99d5eea1aeb1baab16d81e5b481a4bdb5734f2e206bf0ffe8c64f7af97e.md rename to assert/strict_mode.md diff --git a/async_hooks/after_asyncid.md b/async_hooks/after_asyncid.md new file mode 100644 index 00000000..0f74b950 --- /dev/null +++ b/async_hooks/after_asyncid.md @@ -0,0 +1,9 @@ + +* `asyncId` {number} + +Called immediately after the callback specified in `before` is completed. + +If an uncaught exception occurs during execution of the callback, then `after` +will run *after* the `'uncaughtException'` event is emitted or a `domain`'s +handler runs. + diff --git a/async_hooks/async_hooks.md b/async_hooks/async_hooks.md new file mode 100644 index 00000000..dc84973c --- /dev/null +++ b/async_hooks/async_hooks.md @@ -0,0 +1,13 @@ + + + +> Stability: 1 - Experimental + +The `async_hooks` module provides an API to register callbacks tracking the +lifetime of asynchronous resources created inside a Node.js application. +It can be accessed using: + +```js +const async_hooks = require('async_hooks'); +``` + diff --git a/async_hooks/async_hooks_createhook_callbacks.md b/async_hooks/async_hooks_createhook_callbacks.md new file mode 100644 index 00000000..6259daeb --- /dev/null +++ b/async_hooks/async_hooks_createhook_callbacks.md @@ -0,0 +1,48 @@ + + + +* `callbacks` {Object} The [Hook Callbacks][] to register + * `init` {Function} The [`init` callback][]. + * `before` {Function} The [`before` callback][]. + * `after` {Function} The [`after` callback][]. + * `destroy` {Function} The [`destroy` callback][]. +* Returns: {AsyncHook} Instance used for disabling and enabling hooks + +Registers functions to be called for different lifetime events of each async +operation. + +The callbacks `init()`/`before()`/`after()`/`destroy()` are called for the +respective asynchronous event during a resource's lifetime. + +All callbacks are optional. For example, if only resource cleanup needs to +be tracked, then only the `destroy` callback needs to be passed. The +specifics of all functions that can be passed to `callbacks` is in the +[Hook Callbacks][] section. + +```js +const async_hooks = require('async_hooks'); + +const asyncHook = async_hooks.createHook({ + init(asyncId, type, triggerAsyncId, resource) { }, + destroy(asyncId) { } +}); +``` + +Note that the callbacks will be inherited via the prototype chain: + +```js +class MyAsyncCallbacks { + init(asyncId, type, triggerAsyncId, resource) { } + destroy(asyncId) {} +} + +class MyAddedCallbacks extends MyAsyncCallbacks { + before(asyncId) { } + after(asyncId) { } +} + +const asyncHook = async_hooks.createHook(new MyAddedCallbacks()); +``` + diff --git a/async_hooks/async_hooks_executionasyncid.md b/async_hooks/async_hooks_executionasyncid.md new file mode 100644 index 00000000..df69dcd5 --- /dev/null +++ b/async_hooks/async_hooks_executionasyncid.md @@ -0,0 +1,40 @@ + + + +* Returns: {number} The `asyncId` of the current execution context. Useful to + track when something calls. + +```js +const async_hooks = require('async_hooks'); + +console.log(async_hooks.executionAsyncId()); // 1 - bootstrap +fs.open(path, 'r', (err, fd) => { + console.log(async_hooks.executionAsyncId()); // 6 - open() +}); +``` + +The ID returned from `executionAsyncId()` is related to execution timing, not +causality (which is covered by `triggerAsyncId()`): + +```js +const server = net.createServer((conn) => { + // Returns the ID of the server, not of the new connection, because the + // callback runs in the execution scope of the server's MakeCallback(). + async_hooks.executionAsyncId(); + +}).listen(port, () => { + // Returns the ID of a TickObject (i.e. process.nextTick()) because all + // callbacks passed to .listen() are wrapped in a nextTick(). + async_hooks.executionAsyncId(); +}); +``` + +Note that promise contexts may not get precise `executionAsyncIds` by default. +See the section on [promise execution tracking][]. + diff --git a/async_hooks/async_hooks_triggerasyncid.md b/async_hooks/async_hooks_triggerasyncid.md new file mode 100644 index 00000000..8a5acb9b --- /dev/null +++ b/async_hooks/async_hooks_triggerasyncid.md @@ -0,0 +1,22 @@ + +* Returns: {number} The ID of the resource responsible for calling the callback + that is currently being executed. + +```js +const server = net.createServer((conn) => { + // The resource that caused (or triggered) this callback to be called + // was that of the new connection. Thus the return value of triggerAsyncId() + // is the asyncId of "conn". + async_hooks.triggerAsyncId(); + +}).listen(port, () => { + // Even though all callbacks passed to .listen() are wrapped in a nextTick() + // the callback itself exists because the call to the server's .listen() + // was made. So the return value would be the ID of the server. + async_hooks.triggerAsyncId(); +}); +``` + +Note that promise contexts may not get valid `triggerAsyncId`s by default. See +the section on [promise execution tracking][]. + diff --git a/async_hooks/asynchook_disable.md b/async_hooks/asynchook_disable.md new file mode 100644 index 00000000..b1b0e07c --- /dev/null +++ b/async_hooks/asynchook_disable.md @@ -0,0 +1,9 @@ + +* Returns: {AsyncHook} A reference to `asyncHook`. + +Disable the callbacks for a given `AsyncHook` instance from the global pool of +`AsyncHook` callbacks to be executed. Once a hook has been disabled it will not +be called again until enabled. + +For API consistency `disable()` also returns the `AsyncHook` instance. + diff --git a/async_hooks/asynchook_enable.md b/async_hooks/asynchook_enable.md new file mode 100644 index 00000000..e2838174 --- /dev/null +++ b/async_hooks/asynchook_enable.md @@ -0,0 +1,15 @@ + +* Returns: {AsyncHook} A reference to `asyncHook`. + +Enable the callbacks for a given `AsyncHook` instance. If no callbacks are +provided enabling is a noop. + +The `AsyncHook` instance is disabled by default. If the `AsyncHook` instance +should be enabled immediately after creation, the following pattern can be used. + +```js +const async_hooks = require('async_hooks'); + +const hook = async_hooks.createHook(callbacks).enable(); +``` + diff --git a/async_hooks/asynchronous_context_example.md b/async_hooks/asynchronous_context_example.md new file mode 100644 index 00000000..879fcced --- /dev/null +++ b/async_hooks/asynchronous_context_example.md @@ -0,0 +1,79 @@ + +The following is an example with additional information about the calls to +`init` between the `before` and `after` calls, specifically what the +callback to `listen()` will look like. The output formatting is slightly more +elaborate to make calling context easier to see. + +```js +let indent = 0; +async_hooks.createHook({ + init(asyncId, type, triggerAsyncId) { + const eid = async_hooks.executionAsyncId(); + const indentStr = ' '.repeat(indent); + fs.writeSync( + 1, + `${indentStr}${type}(${asyncId}):` + + ` trigger: ${triggerAsyncId} execution: ${eid}\n`); + }, + before(asyncId) { + const indentStr = ' '.repeat(indent); + fs.writeFileSync('log.out', + `${indentStr}before: ${asyncId}\n`, { flag: 'a' }); + indent += 2; + }, + after(asyncId) { + indent -= 2; + const indentStr = ' '.repeat(indent); + fs.writeFileSync('log.out', + `${indentStr}after: ${asyncId}\n`, { flag: 'a' }); + }, + destroy(asyncId) { + const indentStr = ' '.repeat(indent); + fs.writeFileSync('log.out', + `${indentStr}destroy: ${asyncId}\n`, { flag: 'a' }); + }, +}).enable(); + +require('net').createServer(() => {}).listen(8080, () => { + // Let's wait 10ms before logging the server started. + setTimeout(() => { + console.log('>>>', async_hooks.executionAsyncId()); + }, 10); +}); +``` + +Output from only starting the server: + +```console +TCPSERVERWRAP(5): trigger: 1 execution: 1 +TickObject(6): trigger: 5 execution: 1 +before: 6 + Timeout(7): trigger: 6 execution: 6 +after: 6 +destroy: 6 +before: 7 +>>> 7 + TickObject(8): trigger: 7 execution: 7 +after: 7 +before: 8 +after: 8 +``` + +As illustrated in the example, `executionAsyncId()` and `execution` each specify +the value of the current execution context; which is delineated by calls to +`before` and `after`. + +Only using `execution` to graph resource allocation results in the following: + +```console +Timeout(7) -> TickObject(6) -> root(1) +``` + +The `TCPSERVERWRAP` is not part of this graph, even though it was the reason for +`console.log()` being called. This is because binding to a port without a +hostname is a *synchronous* operation, but to maintain a completely asynchronous +API the user's callback is placed in a `process.nextTick()`. + +The graph only shows *when* a resource was created, not *why*, so to track +the *why* use `triggerAsyncId`. + diff --git a/async_hooks/asyncresource_asyncid.md b/async_hooks/asyncresource_asyncid.md new file mode 100644 index 00000000..9acd3ed3 --- /dev/null +++ b/async_hooks/asyncresource_asyncid.md @@ -0,0 +1,3 @@ + +* Returns: {number} The unique `asyncId` assigned to the resource. + diff --git a/async_hooks/asyncresource_emitafter.md b/async_hooks/asyncresource_emitafter.md new file mode 100644 index 00000000..a51b3260 --- /dev/null +++ b/async_hooks/asyncresource_emitafter.md @@ -0,0 +1,18 @@ + +> Stability: 0 - Deprecated: Use [`asyncResource.runInAsyncScope()`][] instead. + +Call all `after` callbacks. If nested calls to `emitBefore()` were made, then +make sure the stack is unwound properly. Otherwise an error will be thrown. + +If the user's callback throws an exception, `emitAfter()` will automatically be +called for all `asyncId`s on the stack if the error is handled by a domain or +`'uncaughtException'` handler. + +`before` and `after` calls must be unwound in the same order that they +are called. Otherwise, an unrecoverable exception will occur and the process +will abort. For this reason, the `emitBefore` and `emitAfter` APIs are +considered deprecated. Please use `runInAsyncScope`, as it provides a much safer +alternative. + diff --git a/async_hooks/asyncresource_emitbefore.md b/async_hooks/asyncresource_emitbefore.md new file mode 100644 index 00000000..6de1a5e7 --- /dev/null +++ b/async_hooks/asyncresource_emitbefore.md @@ -0,0 +1,15 @@ + +> Stability: 0 - Deprecated: Use [`asyncResource.runInAsyncScope()`][] instead. + +Call all `before` callbacks to notify that a new asynchronous execution context +is being entered. If nested calls to `emitBefore()` are made, the stack of +`asyncId`s will be tracked and properly unwound. + +`before` and `after` calls must be unwound in the same order that they +are called. Otherwise, an unrecoverable exception will occur and the process +will abort. For this reason, the `emitBefore` and `emitAfter` APIs are +considered deprecated. Please use `runInAsyncScope`, as it provides a much safer +alternative. + diff --git a/async_hooks/asyncresource_emitdestroy.md b/async_hooks/asyncresource_emitdestroy.md new file mode 100644 index 00000000..9702e6e8 --- /dev/null +++ b/async_hooks/asyncresource_emitdestroy.md @@ -0,0 +1,8 @@ + +* Returns: {AsyncResource} A reference to `asyncResource`. + +Call all `destroy` hooks. This should only ever be called once. An error will +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. + diff --git a/async_hooks/asyncresource_runinasyncscope_fn_thisarg_args.md b/async_hooks/asyncresource_runinasyncscope_fn_thisarg_args.md new file mode 100644 index 00000000..73fd81f0 --- /dev/null +++ b/async_hooks/asyncresource_runinasyncscope_fn_thisarg_args.md @@ -0,0 +1,14 @@ + + +* `fn` {Function} The function to call in the execution context of this async + resource. +* `thisArg` {any} The receiver to be used for the function call. +* `...args` {any} Optional arguments to pass to the function. + +Call the provided function with the provided arguments in the execution context +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. + diff --git a/api-docs/ae2173c4651ebec532148650b9cb023e1f1285a0786c24c90d22ec2f461f677b.md b/async_hooks/asyncresource_triggerasyncid.md similarity index 100% rename from api-docs/ae2173c4651ebec532148650b9cb023e1f1285a0786c24c90d22ec2f461f677b.md rename to async_hooks/asyncresource_triggerasyncid.md diff --git a/async_hooks/asyncresource_type_options.md b/async_hooks/asyncresource_type_options.md new file mode 100644 index 00000000..84b8b51d --- /dev/null +++ b/async_hooks/asyncresource_type_options.md @@ -0,0 +1,35 @@ + +* `type` {string} The type of async event. +* `options` {Object} + * `triggerAsyncId` {number} The ID of the execution context that created this + async event. **Default:** `executionAsyncId()` + * `requireManualDestroy` {boolean} Disables automatic `emitDestroy` when the + object is garbage collected. This usually does not need to be set (even if + `emitDestroy` is called manually), unless the resource's asyncId is retrieved + and the sensitive API's `emitDestroy` is called with it. + **Default:** `false` + +Example usage: + +```js +class DBQuery extends AsyncResource { + constructor(db) { + super('DBQuery'); + this.db = db; + } + + getInfo(query, callback) { + this.db.get(query, (err, data) => { + this.emitBefore(); + callback(err, data); + this.emitAfter(); + }); + } + + close() { + this.db = null; + this.emitDestroy(); + } +} +``` + diff --git a/async_hooks/asyncresource_type_triggerasyncid.md b/async_hooks/asyncresource_type_triggerasyncid.md new file mode 100644 index 00000000..6846137d --- /dev/null +++ b/async_hooks/asyncresource_type_triggerasyncid.md @@ -0,0 +1,29 @@ + +* `type` {string} The type of async event. +* `triggerAsyncId` {number} The ID of the execution context that created this + async event. + +Example usage: + +```js +class DBQuery extends AsyncResource { + constructor(db) { + super('DBQuery'); + this.db = db; + } + + getInfo(query, callback) { + this.db.get(query, (err, data) => { + this.emitBefore(); + callback(err, data); + this.emitAfter(); + }); + } + + close() { + this.db = null; + this.emitDestroy(); + } +} +``` + diff --git a/async_hooks/before_asyncid.md b/async_hooks/before_asyncid.md new file mode 100644 index 00000000..616c9795 --- /dev/null +++ b/async_hooks/before_asyncid.md @@ -0,0 +1,16 @@ + +* `asyncId` {number} + +When an asynchronous operation is initiated (such as a TCP server receiving a +new connection) or completes (such as writing data to disk) a callback is +called to notify the user. The `before` callback is called just before said +callback is executed. `asyncId` is the unique identifier assigned to the +resource about to execute the callback. + +The `before` callback will be called 0 to N times. The `before` callback +will typically be called 0 times if the asynchronous operation was cancelled +or, for example, if no connections are received by a TCP server. Persistent +asynchronous resources like a TCP server will typically call the `before` +callback multiple times, while other operations like `fs.open()` will call +it only once. + diff --git a/async_hooks/class_asyncresource.md b/async_hooks/class_asyncresource.md new file mode 100644 index 00000000..70c0fec3 --- /dev/null +++ b/async_hooks/class_asyncresource.md @@ -0,0 +1,37 @@ + +The class `AsyncResource` is designed to be extended by the embedder's async +resources. Using this, users can easily trigger the lifetime events of their +own resources. + +The `init` hook will trigger when an `AsyncResource` is instantiated. + +The following is an overview of the `AsyncResource` API. + +```js +const { AsyncResource, executionAsyncId } = require('async_hooks'); + +// AsyncResource() is meant to be extended. Instantiating a +// new AsyncResource() also triggers init. If triggerAsyncId is omitted then +// async_hook.executionAsyncId() is used. +const asyncResource = new AsyncResource( + type, { triggerAsyncId: executionAsyncId(), requireManualDestroy: false } +); + +// Run a function in the execution context of the resource. This will +// * establish the context of the resource +// * trigger the AsyncHooks before callbacks +// * call the provided function `fn` with the supplied arguments +// * trigger the AsyncHooks after callbacks +// * restore the original execution context +asyncResource.runInAsyncScope(fn, thisArg, ...args); + +// Call AsyncHooks destroy callbacks. +asyncResource.emitDestroy(); + +// Return the unique ID assigned to the AsyncResource instance. +asyncResource.asyncId(); + +// Return the trigger ID for the AsyncResource instance. +asyncResource.triggerAsyncId(); +``` + diff --git a/async_hooks/destroy_asyncid.md b/async_hooks/destroy_asyncid.md new file mode 100644 index 00000000..d8e95c75 --- /dev/null +++ b/async_hooks/destroy_asyncid.md @@ -0,0 +1,11 @@ + +* `asyncId` {number} + +Called after the resource corresponding to `asyncId` is destroyed. It is also +called asynchronously from the embedder API `emitDestroy()`. + +Some resources depend on garbage collection for cleanup, so if a reference is +made to the `resource` object passed to `init` it is possible that `destroy` +will never be called, causing a memory leak in the application. If the resource +does not depend on garbage collection, then this will not be an issue. + diff --git a/async_hooks/error_handling.md b/async_hooks/error_handling.md new file mode 100644 index 00000000..85c5d025 --- /dev/null +++ b/async_hooks/error_handling.md @@ -0,0 +1,16 @@ + +If any `AsyncHook` callbacks throw, the application will print the stack trace +and exit. The exit path does follow that of an uncaught exception, but +all `'uncaughtException'` listeners are removed, thus forcing the process to +exit. The `'exit'` callbacks will still be called unless the application is run +with `--abort-on-uncaught-exception`, in which case a stack trace will be +printed and the application exits, leaving a core file. + +The reason for this error handling behavior is that these callbacks are running +at potentially volatile points in an object's lifetime, for example during +class construction and destruction. Because of this, it is deemed necessary to +bring down the process quickly in order to prevent an unintentional abort in the +future. This is subject to change in the future if a comprehensive analysis is +performed to ensure an exception can follow the normal control flow without +unintentional side effects. + diff --git a/async_hooks/hook_callbacks.md b/async_hooks/hook_callbacks.md new file mode 100644 index 00000000..4d791e9d --- /dev/null +++ b/async_hooks/hook_callbacks.md @@ -0,0 +1,5 @@ + +Key events in the lifetime of asynchronous events have been categorized into +four areas: instantiation, before/after the callback is called, and when the +instance is destroyed. + diff --git a/async_hooks/init_asyncid_type_triggerasyncid_resource.md b/async_hooks/init_asyncid_type_triggerasyncid_resource.md new file mode 100644 index 00000000..17dcb7c4 --- /dev/null +++ b/async_hooks/init_asyncid_type_triggerasyncid_resource.md @@ -0,0 +1,26 @@ + +* `asyncId` {number} A unique ID for the async resource. +* `type` {string} The type of the async resource. +* `triggerAsyncId` {number} The unique ID of the async resource in whose + execution context this async resource was created. +* `resource` {Object} Reference to the resource representing the async + operation, needs to be released during _destroy_. + +Called when a class is constructed that has the _possibility_ to emit an +asynchronous event. This _does not_ mean the instance must call +`before`/`after` before `destroy` is called, only that the possibility +exists. + +This behavior can be observed by doing something like opening a resource then +closing it before the resource can be used. The following snippet demonstrates +this. + +```js +require('net').createServer().listen(function() { this.close(); }); +// OR +clearTimeout(setTimeout(() => {}, 10)); +``` + +Every new resource is assigned an ID that is unique within the scope of the +current Node.js instance. + diff --git a/async_hooks/javascript_embedder_api.md b/async_hooks/javascript_embedder_api.md new file mode 100644 index 00000000..81ba966f --- /dev/null +++ b/async_hooks/javascript_embedder_api.md @@ -0,0 +1,5 @@ + +Library developers that handle their own asynchronous resources performing tasks +like I/O, connection pooling, or managing callback queues may use the +`AsyncWrap` JavaScript API so that all the appropriate callbacks are called. + diff --git a/async_hooks/new_asyncresource_type_options.md b/async_hooks/new_asyncresource_type_options.md new file mode 100644 index 00000000..f29d678a --- /dev/null +++ b/async_hooks/new_asyncresource_type_options.md @@ -0,0 +1,33 @@ + +* `type` {string} The type of async event. +* `options` {Object} + * `triggerAsyncId` {number} The ID of the execution context that created this + async event. **Default:** `executionAsyncId()`. + * `requireManualDestroy` {boolean} Disables automatic `emitDestroy` when the + object is garbage collected. This usually does not need to be set (even if + `emitDestroy` is called manually), unless the resource's `asyncId` is + retrieved and the sensitive API's `emitDestroy` is called with it. + **Default:** `false`. + +Example usage: + +```js +class DBQuery extends AsyncResource { + constructor(db) { + super('DBQuery'); + this.db = db; + } + + getInfo(query, callback) { + this.db.get(query, (err, data) => { + this.runInAsyncScope(callback, null, err, data); + }); + } + + close() { + this.db = null; + this.emitDestroy(); + } +} +``` + diff --git a/async_hooks/overview.md b/async_hooks/overview.md new file mode 100644 index 00000000..50e635e9 --- /dev/null +++ b/async_hooks/overview.md @@ -0,0 +1,51 @@ + +Following is a simple overview of the public API. + +```js +const async_hooks = require('async_hooks'); + +// Return the ID of the current execution context. +const eid = async_hooks.executionAsyncId(); + +// Return the ID of the handle responsible for triggering the callback of the +// current execution scope to call. +const tid = async_hooks.triggerAsyncId(); + +// Create a new AsyncHook instance. All of these callbacks are optional. +const asyncHook = + async_hooks.createHook({ init, before, after, destroy, promiseResolve }); + +// Allow callbacks of this AsyncHook instance to call. This is not an implicit +// action after running the constructor, and must be explicitly run to begin +// executing callbacks. +asyncHook.enable(); + +// Disable listening for new asynchronous events. +asyncHook.disable(); + +// +// The following are the callbacks that can be passed to createHook(). +// + +// init is called during object construction. The resource may not have +// completed construction when this callback runs, therefore all fields of the +// resource referenced by "asyncId" may not have been populated. +function init(asyncId, type, triggerAsyncId, resource) { } + +// before is called just before the resource's callback is called. It can be +// called 0-N times for handles (e.g. TCPWrap), and will be called exactly 1 +// time for requests (e.g. FSReqWrap). +function before(asyncId) { } + +// after is called just after the resource's callback has finished. +function after(asyncId) { } + +// destroy is called when an AsyncWrap instance is destroyed. +function destroy(asyncId) { } + +// promiseResolve is called only for promise resources, when the +// `resolve` function passed to the `Promise` constructor is invoked +// (either directly or through other means of resolving a promise). +function promiseResolve(asyncId) { } +``` + diff --git a/async_hooks/printing_in_asynchooks_callbacks.md b/async_hooks/printing_in_asynchooks_callbacks.md new file mode 100644 index 00000000..0db33425 --- /dev/null +++ b/async_hooks/printing_in_asynchooks_callbacks.md @@ -0,0 +1,25 @@ + +Because printing to the console is an asynchronous operation, `console.log()` +will cause the AsyncHooks callbacks to be called. Using `console.log()` or +similar asynchronous operations inside an AsyncHooks callback function will thus +cause an infinite recursion. An easy solution to this when debugging is to use a +synchronous logging operation such as `fs.writeFileSync(file, msg, flag)`. +This will print to the file and will not invoke AsyncHooks recursively because +it is synchronous. + +```js +const fs = require('fs'); +const util = require('util'); + +function debug(...args) { + // use a function like this one when debugging inside an AsyncHooks callback + fs.writeFileSync('log.out', `${util.format(...args)}\n`, { flag: 'a' }); +} +``` + +If an asynchronous operation is needed for logging, it is possible to keep +track of what caused the asynchronous operation using the information +provided by AsyncHooks itself. The logging should then be skipped when +it was the logging itself that caused AsyncHooks callback to call. By +doing this the otherwise infinite recursion is broken. + diff --git a/async_hooks/promise_execution_tracking.md b/async_hooks/promise_execution_tracking.md new file mode 100644 index 00000000..4a061672 --- /dev/null +++ b/async_hooks/promise_execution_tracking.md @@ -0,0 +1,46 @@ + +By default, promise executions are not assigned `asyncId`s due to the relatively +expensive nature of the [promise introspection API][PromiseHooks] provided by +V8. This means that programs using promises or `async`/`await` will not get +correct execution and trigger ids for promise callback contexts by default. + +```js +const ah = require('async_hooks'); +Promise.resolve(1729).then(() => { + console.log(`eid ${ah.executionAsyncId()} tid ${ah.triggerAsyncId()}`); +}); +// produces: +// eid 1 tid 0 +``` + +Observe that the `then()` callback claims to have executed in the context of the +outer scope even though there was an asynchronous hop involved. Also note that +the `triggerAsyncId` value is `0`, which means that we are missing context about +the resource that caused (triggered) the `then()` callback to be executed. + +Installing async hooks via `async_hooks.createHook` enables promise execution +tracking: + +```js +const ah = require('async_hooks'); +ah.createHook({ init() {} }).enable(); // forces PromiseHooks to be enabled. +Promise.resolve(1729).then(() => { + console.log(`eid ${ah.executionAsyncId()} tid ${ah.triggerAsyncId()}`); +}); +// produces: +// eid 7 tid 6 +``` + +In this example, adding any actual hook function enabled the tracking of +promises. There are two promises in the example above; the promise created by +`Promise.resolve()` and the promise returned by the call to `then()`. In the +example above, the first promise got the `asyncId` `6` and the latter got +`asyncId` `7`. During the execution of the `then()` callback, we are executing +in the context of promise with `asyncId` `7`. This promise was triggered by +async resource `6`. + +Another subtlety with promises is that `before` and `after` callbacks are run +only on chained promises. That means promises not created by `then()`/`catch()` +will not have the `before` and `after` callbacks fired on them. For more details +see the details of the V8 [PromiseHooks][] API. + diff --git a/async_hooks/promiseresolve_asyncid.md b/async_hooks/promiseresolve_asyncid.md new file mode 100644 index 00000000..21a93b37 --- /dev/null +++ b/async_hooks/promiseresolve_asyncid.md @@ -0,0 +1,26 @@ + +* `asyncId` {number} + +Called when the `resolve` function passed to the `Promise` constructor is +invoked (either directly or through other means of resolving a promise). + +Note that `resolve()` does not do any observable synchronous work. + +The `Promise` is not necessarily fulfilled or rejected at this point if the +`Promise` was resolved by assuming the state of another `Promise`. + +```js +new Promise((resolve) => resolve(true)).then((a) => {}); +``` + +calls the following callbacks: + +```text +init for PROMISE with id 5, trigger id: 1 + promise resolve 5 # corresponds to resolve(true) +init for PROMISE with id 6, trigger id: 5 # the Promise returned by then() + before 6 # the then() callback is entered + promise resolve 6 # the then() callback resolves the promise by returning + after 6 +``` + diff --git a/api-docs/164de25273f0694273063411508fd0312251de74b0cd66ea7e462adb2a73c858.md b/async_hooks/public_api.md similarity index 100% rename from api-docs/164de25273f0694273063411508fd0312251de74b0cd66ea7e462adb2a73c858.md rename to async_hooks/public_api.md diff --git a/async_hooks/resource.md b/async_hooks/resource.md new file mode 100644 index 00000000..a6c435bf --- /dev/null +++ b/async_hooks/resource.md @@ -0,0 +1,19 @@ + +`resource` is an object that represents the actual async resource that has +been initialized. This can contain useful information that can vary based on +the value of `type`. For instance, for the `GETADDRINFOREQWRAP` resource type, +`resource` provides the hostname used when looking up the IP address for the +host in `net.Server.listen()`. The API for accessing this information is +currently not considered public, but using the Embedder API, users can provide +and document their own resource objects. For example, such a resource object +could contain the SQL query being executed. + +In the case of Promises, the `resource` object will have `promise` property +that refers to the `Promise` that is being initialized, and an +`isChainedPromise` property, set to `true` if the promise has a parent promise, +and `false` otherwise. For example, in the case of `b = a.then(handler)`, `a` is +considered a parent `Promise` of `b`. Here, `b` is considered a chained promise. + +In some cases the resource object is reused for performance reasons, it is +thus not safe to use it as a key in a `WeakMap` or add properties to it. + diff --git a/async_hooks/terminology.md b/async_hooks/terminology.md new file mode 100644 index 00000000..e0cee350 --- /dev/null +++ b/async_hooks/terminology.md @@ -0,0 +1,11 @@ + +An asynchronous resource represents an object with an associated callback. +This callback may be called multiple times, for example, the `'connection'` +event in `net.createServer()`, or just a single time like in `fs.open()`. +A resource can also be closed before the callback is called. `AsyncHook` does +not explicitly distinguish between these different cases but will represent them +as the abstract concept that is a resource. + +If [`Worker`][]s are used, each thread has an independent `async_hooks` +interface, and each thread will use a new set of async IDs. + diff --git a/async_hooks/triggerasyncid.md b/async_hooks/triggerasyncid.md new file mode 100644 index 00000000..707d648d --- /dev/null +++ b/async_hooks/triggerasyncid.md @@ -0,0 +1,37 @@ + +`triggerAsyncId` is the `asyncId` of the resource that caused (or "triggered") +the new resource to initialize and that caused `init` to call. This is different +from `async_hooks.executionAsyncId()` that only shows *when* a resource was +created, while `triggerAsyncId` shows *why* a resource was created. + +The following is a simple demonstration of `triggerAsyncId`: + +```js +async_hooks.createHook({ + init(asyncId, type, triggerAsyncId) { + const eid = async_hooks.executionAsyncId(); + fs.writeSync( + 1, `${type}(${asyncId}): trigger: ${triggerAsyncId} execution: ${eid}\n`); + } +}).enable(); + +require('net').createServer((conn) => {}).listen(8080); +``` + +Output when hitting the server with `nc localhost 8080`: + +```console +TCPSERVERWRAP(5): trigger: 1 execution: 1 +TCPWRAP(7): trigger: 5 execution: 0 +``` + +The `TCPSERVERWRAP` is the server which receives the connections. + +The `TCPWRAP` is the new connection from the client. When a new +connection is made, the `TCPWrap` instance is immediately constructed. This +happens outside of any JavaScript stack. (An `executionAsyncId()` of `0` means +that it is being executed from C++ with no JavaScript stack above it.) With only +that information, it would be impossible to link resources together in +terms of what caused them to be created, so `triggerAsyncId` is given the task +of propagating what resource is responsible for the new resource's existence. + diff --git a/async_hooks/triggerid.md b/async_hooks/triggerid.md new file mode 100644 index 00000000..213924ed --- /dev/null +++ b/async_hooks/triggerid.md @@ -0,0 +1,38 @@ + +`triggerAsyncId` is the `asyncId` of the resource that caused (or "triggered") +the new resource to initialize and that caused `init` to call. This is different +from `async_hooks.executionAsyncId()` that only shows *when* a resource was +created, while `triggerAsyncId` shows *why* a resource was created. + + +The following is a simple demonstration of `triggerAsyncId`: + +```js +async_hooks.createHook({ + init(asyncId, type, triggerAsyncId) { + const eid = async_hooks.executionAsyncId(); + fs.writeSync( + 1, `${type}(${asyncId}): trigger: ${triggerAsyncId} execution: ${eid}\n`); + } +}).enable(); + +require('net').createServer((conn) => {}).listen(8080); +``` + +Output when hitting the server with `nc localhost 8080`: + +```console +TCPSERVERWRAP(2): trigger: 1 execution: 1 +TCPWRAP(4): trigger: 2 execution: 0 +``` + +The `TCPSERVERWRAP` is the server which receives the connections. + +The `TCPWRAP` is the new connection from the client. When a new +connection is made the `TCPWrap` instance is immediately constructed. This +happens outside of any JavaScript stack (side note: a `executionAsyncId()` of `0` +means it's being executed from C++, with no JavaScript stack above it). +With only that information, it would be impossible to link resources together in +terms of what caused them to be created, so `triggerAsyncId` is given the task of +propagating what resource is responsible for the new resource's existence. + diff --git a/async_hooks/type.md b/async_hooks/type.md new file mode 100644 index 00000000..e653f178 --- /dev/null +++ b/async_hooks/type.md @@ -0,0 +1,22 @@ + +The `type` is a string identifying the type of resource that caused +`init` to be called. Generally, it will correspond to the name of the +resource's constructor. + +```text +FSEVENTWRAP, FSREQWRAP, GETADDRINFOREQWRAP, GETNAMEINFOREQWRAP, HTTPPARSER, +JSSTREAM, PIPECONNECTWRAP, PIPEWRAP, PROCESSWRAP, QUERYWRAP, SHUTDOWNWRAP, +SIGNALWRAP, STATWATCHER, TCPCONNECTWRAP, TCPSERVERWRAP, TCPWRAP, TIMERWRAP, +TTYWRAP, UDPSENDWRAP, UDPWRAP, WRITEWRAP, ZLIB, SSLCONNECTION, PBKDF2REQUEST, +RANDOMBYTESREQUEST, TLSWRAP, Timeout, Immediate, TickObject +``` + +There is also the `PROMISE` resource type, which is used to track `Promise` +instances and asynchronous work scheduled by them. + +Users are able to define their own `type` when using the public embedder API. + +It is possible to have type name collisions. Embedders are encouraged to use +unique prefixes, such as the npm package name, to prevent collisions when +listening to the hooks. + diff --git a/api-docs/ea6a06892825ad28d333f9c64f6cd8d8dde8f94075a7379f355082b9739cb16c.md b/buffer/buf_buffer.md similarity index 100% rename from api-docs/ea6a06892825ad28d333f9c64f6cd8d8dde8f94075a7379f355082b9739cb16c.md rename to buffer/buf_buffer.md diff --git a/api-docs/f951a01c58d6ce10de3b4e88664beabd4d1e8e22ba6de0d053e35caafa7d8247.md b/buffer/buf_byteoffset.md similarity index 100% rename from api-docs/f951a01c58d6ce10de3b4e88664beabd4d1e8e22ba6de0d053e35caafa7d8247.md rename to buffer/buf_byteoffset.md diff --git a/api-docs/8003717b48d1461454911f99d6d11b38f3640429c2988a003c4441e9153de024.md b/buffer/buf_compare_target_targetstart_targetend_sourcestart_sourceend.md similarity index 100% rename from api-docs/8003717b48d1461454911f99d6d11b38f3640429c2988a003c4441e9153de024.md rename to buffer/buf_compare_target_targetstart_targetend_sourcestart_sourceend.md diff --git a/api-docs/8de88ccfecf60b4ef4dca6c150c70d4abc6887c243f28c28f0bcd5426ea7bb06.md b/buffer/buf_copy_target_targetstart_sourcestart_sourceend.md similarity index 100% rename from api-docs/8de88ccfecf60b4ef4dca6c150c70d4abc6887c243f28c28f0bcd5426ea7bb06.md rename to buffer/buf_copy_target_targetstart_sourcestart_sourceend.md diff --git a/api-docs/e54f66e06cd3e0319bb11d782a5ceb15420d35eb39a02af49a5368f06de7de80.md b/buffer/buf_entries.md similarity index 100% rename from api-docs/e54f66e06cd3e0319bb11d782a5ceb15420d35eb39a02af49a5368f06de7de80.md rename to buffer/buf_entries.md diff --git a/api-docs/bd8425142eb165b7df659358252b105c00358856e2c36b2ebd55e0275ca66261.md b/buffer/buf_equals_otherbuffer.md similarity index 100% rename from api-docs/bd8425142eb165b7df659358252b105c00358856e2c36b2ebd55e0275ca66261.md rename to buffer/buf_equals_otherbuffer.md diff --git a/api-docs/6eaf4da3292a5c92208984e7d15bb5fdbe4d6e2f4aa92e530a27040e210d6bb7.md b/buffer/buf_fill_value_offset_end_encoding.md similarity index 100% rename from api-docs/6eaf4da3292a5c92208984e7d15bb5fdbe4d6e2f4aa92e530a27040e210d6bb7.md rename to buffer/buf_fill_value_offset_end_encoding.md diff --git a/api-docs/b740c172e9e87ce5ef218c9cfa13b6fb5654817ee220a10adf788ffc374a36dd.md b/buffer/buf_includes_value_byteoffset_encoding.md similarity index 100% rename from api-docs/b740c172e9e87ce5ef218c9cfa13b6fb5654817ee220a10adf788ffc374a36dd.md rename to buffer/buf_includes_value_byteoffset_encoding.md diff --git a/api-docs/37875416166d47a8759b19984f8ceffe355a86b405237aeaf90fbfb3a0d2cd04.md b/buffer/buf_index.md similarity index 100% rename from api-docs/37875416166d47a8759b19984f8ceffe355a86b405237aeaf90fbfb3a0d2cd04.md rename to buffer/buf_index.md diff --git a/api-docs/bca1e619ad01aa7113484b2ccb34cfda688febfc80edd630fa26251a83fc07e7.md b/buffer/buf_indexof_value_byteoffset_encoding.md similarity index 100% rename from api-docs/bca1e619ad01aa7113484b2ccb34cfda688febfc80edd630fa26251a83fc07e7.md rename to buffer/buf_indexof_value_byteoffset_encoding.md diff --git a/api-docs/23e57cc0b412f081a39b02e14967f3fbed9a97b94e9de4d057c6b81efc00cc28.md b/buffer/buf_keys.md similarity index 100% rename from api-docs/23e57cc0b412f081a39b02e14967f3fbed9a97b94e9de4d057c6b81efc00cc28.md rename to buffer/buf_keys.md diff --git a/api-docs/65d5f21df7626d1f9c278504db61d347ba2dea962e678a71f4c9357450443dc8.md b/buffer/buf_lastindexof_value_byteoffset_encoding.md similarity index 100% rename from api-docs/65d5f21df7626d1f9c278504db61d347ba2dea962e678a71f4c9357450443dc8.md rename to buffer/buf_lastindexof_value_byteoffset_encoding.md diff --git a/api-docs/6b8679972481a3bb96c45f2344b3833900b59651063268690117e91512675d1d.md b/buffer/buf_length.md similarity index 100% rename from api-docs/6b8679972481a3bb96c45f2344b3833900b59651063268690117e91512675d1d.md rename to buffer/buf_length.md diff --git a/buffer/buf_parent.md b/buffer/buf_parent.md new file mode 100644 index 00000000..0eb5ab64 --- /dev/null +++ b/buffer/buf_parent.md @@ -0,0 +1,8 @@ + + +> Stability: 0 - Deprecated: Use [`buf.buffer`][] instead. + +The `buf.parent` property is a deprecated alias for `buf.buffer`. + diff --git a/api-docs/1478a1b0d7503f470f3b9d9ad5c6d46e3b521cfe0aa231a57d06f70356a00b23.md b/buffer/buf_readbigint64be_offset.md similarity index 100% rename from api-docs/1478a1b0d7503f470f3b9d9ad5c6d46e3b521cfe0aa231a57d06f70356a00b23.md rename to buffer/buf_readbigint64be_offset.md diff --git a/api-docs/c943cb75421b7a2786b68a6a53bef0f000520c6d45a8191e80cd63517b633365.md b/buffer/buf_readbigint64le_offset.md similarity index 100% rename from api-docs/c943cb75421b7a2786b68a6a53bef0f000520c6d45a8191e80cd63517b633365.md rename to buffer/buf_readbigint64le_offset.md diff --git a/api-docs/28c08f3fc92321ff8242a3113b8ef22071869fa346a59150f6b31c50c597a440.md b/buffer/buf_readbiguint64be_offset.md similarity index 100% rename from api-docs/28c08f3fc92321ff8242a3113b8ef22071869fa346a59150f6b31c50c597a440.md rename to buffer/buf_readbiguint64be_offset.md diff --git a/api-docs/30a5f34fb8812b8225e4854945c7ae610d3367a14d6865070579bf4e42f374a4.md b/buffer/buf_readbiguint64le_offset.md similarity index 100% rename from api-docs/30a5f34fb8812b8225e4854945c7ae610d3367a14d6865070579bf4e42f374a4.md rename to buffer/buf_readbiguint64le_offset.md diff --git a/api-docs/308e40831495ab82b18ad24ef8d10e9c0e72fde5eedc2ba9892a0c51e88f8842.md b/buffer/buf_readdoublebe_offset.md similarity index 100% rename from api-docs/308e40831495ab82b18ad24ef8d10e9c0e72fde5eedc2ba9892a0c51e88f8842.md rename to buffer/buf_readdoublebe_offset.md diff --git a/api-docs/5a3176139c4ec43c3efbfc47da19cc8a98ac1bad0ac7cca9680f9a75191c1170.md b/buffer/buf_readdoublele_offset.md similarity index 100% rename from api-docs/5a3176139c4ec43c3efbfc47da19cc8a98ac1bad0ac7cca9680f9a75191c1170.md rename to buffer/buf_readdoublele_offset.md diff --git a/api-docs/34761e760edcc7f42534f0c61c3e5ae4b8d484250277bf144a140fe725ef822c.md b/buffer/buf_readfloatbe_offset.md similarity index 100% rename from api-docs/34761e760edcc7f42534f0c61c3e5ae4b8d484250277bf144a140fe725ef822c.md rename to buffer/buf_readfloatbe_offset.md diff --git a/api-docs/ebe635a9d6d67ae0870094a5b58ff6588689f4c9e4bf2dbcc298ac96bc233f12.md b/buffer/buf_readfloatle_offset.md similarity index 100% rename from api-docs/ebe635a9d6d67ae0870094a5b58ff6588689f4c9e4bf2dbcc298ac96bc233f12.md rename to buffer/buf_readfloatle_offset.md diff --git a/api-docs/4a05a3d6de34e8cf15d50eb9251c019694320b4cab2879a912e4dfcf15f38aa1.md b/buffer/buf_readint16be_offset.md similarity index 100% rename from api-docs/4a05a3d6de34e8cf15d50eb9251c019694320b4cab2879a912e4dfcf15f38aa1.md rename to buffer/buf_readint16be_offset.md diff --git a/api-docs/31f537f5a5d6546170819c897253a6ed88467cd265b49f72a256bcd73a755300.md b/buffer/buf_readint16le_offset.md similarity index 100% rename from api-docs/31f537f5a5d6546170819c897253a6ed88467cd265b49f72a256bcd73a755300.md rename to buffer/buf_readint16le_offset.md diff --git a/api-docs/530964885707bd27e0c7995e150fe8c78a948b37f79052e1cc91e2c3e3c95da3.md b/buffer/buf_readint32be_offset.md similarity index 100% rename from api-docs/530964885707bd27e0c7995e150fe8c78a948b37f79052e1cc91e2c3e3c95da3.md rename to buffer/buf_readint32be_offset.md diff --git a/api-docs/77e7e516697ae964c9d8e8c1c2908cd260724bb23dd501a03418425363c9eeaf.md b/buffer/buf_readint32le_offset.md similarity index 100% rename from api-docs/77e7e516697ae964c9d8e8c1c2908cd260724bb23dd501a03418425363c9eeaf.md rename to buffer/buf_readint32le_offset.md diff --git a/api-docs/aae4aa384253028217a78316dfd30033fb9dd1274ef33a8b552c0b53e2169087.md b/buffer/buf_readint8_offset.md similarity index 100% rename from api-docs/aae4aa384253028217a78316dfd30033fb9dd1274ef33a8b552c0b53e2169087.md rename to buffer/buf_readint8_offset.md diff --git a/api-docs/58c9587abc485b9fee4ddc741f3c5088518cafa3ae54a9e68498c581156d8c1b.md b/buffer/buf_readintbe_offset_bytelength.md similarity index 100% rename from api-docs/58c9587abc485b9fee4ddc741f3c5088518cafa3ae54a9e68498c581156d8c1b.md rename to buffer/buf_readintbe_offset_bytelength.md diff --git a/api-docs/d7555f30cae9e8e036c06030ab7184eb8977a21da621b94aada78a3e5da9cf1a.md b/buffer/buf_readintle_offset_bytelength.md similarity index 100% rename from api-docs/d7555f30cae9e8e036c06030ab7184eb8977a21da621b94aada78a3e5da9cf1a.md rename to buffer/buf_readintle_offset_bytelength.md diff --git a/api-docs/6dffe6f8a9bafbcf789bbe94dd9633d98e0a172edb2a5bcb9492dfd15f84c6e4.md b/buffer/buf_readuint16be_offset.md similarity index 100% rename from api-docs/6dffe6f8a9bafbcf789bbe94dd9633d98e0a172edb2a5bcb9492dfd15f84c6e4.md rename to buffer/buf_readuint16be_offset.md diff --git a/api-docs/e11a670a4c03a1bb0ca6bb1c8540eab0cda0aa14128671451e1e665d22228b8d.md b/buffer/buf_readuint16le_offset.md similarity index 100% rename from api-docs/e11a670a4c03a1bb0ca6bb1c8540eab0cda0aa14128671451e1e665d22228b8d.md rename to buffer/buf_readuint16le_offset.md diff --git a/api-docs/74acea7ee74bcbe74d65cd0b98af15f815e22cce79b61b8826b97adaca904e5c.md b/buffer/buf_readuint32be_offset.md similarity index 100% rename from api-docs/74acea7ee74bcbe74d65cd0b98af15f815e22cce79b61b8826b97adaca904e5c.md rename to buffer/buf_readuint32be_offset.md diff --git a/api-docs/0e3fa84ad158da512b23d376c7d315524128f1ebfb7b36a84b5d4c74bcc65e2e.md b/buffer/buf_readuint32le_offset.md similarity index 100% rename from api-docs/0e3fa84ad158da512b23d376c7d315524128f1ebfb7b36a84b5d4c74bcc65e2e.md rename to buffer/buf_readuint32le_offset.md diff --git a/api-docs/268910193a6ee19ef280c98fd18e35837e48dd1c644afe809ec9867099a0e6b5.md b/buffer/buf_readuint8_offset.md similarity index 100% rename from api-docs/268910193a6ee19ef280c98fd18e35837e48dd1c644afe809ec9867099a0e6b5.md rename to buffer/buf_readuint8_offset.md diff --git a/api-docs/7cb0227963ce1d25072931441edf655af5fa69129bc49a07af5956f0c32fd9ff.md b/buffer/buf_readuintbe_offset_bytelength.md similarity index 100% rename from api-docs/7cb0227963ce1d25072931441edf655af5fa69129bc49a07af5956f0c32fd9ff.md rename to buffer/buf_readuintbe_offset_bytelength.md diff --git a/api-docs/164a46588e58e6b945c687b4149a5fd59c66ca9d3c914ff90c8cce504f6fbfa7.md b/buffer/buf_readuintle_offset_bytelength.md similarity index 100% rename from api-docs/164a46588e58e6b945c687b4149a5fd59c66ca9d3c914ff90c8cce504f6fbfa7.md rename to buffer/buf_readuintle_offset_bytelength.md diff --git a/api-docs/dfbfd82cd9907ddc69e201293660daf21e541934a3b353201f9bd65c6723909b.md b/buffer/buf_slice_start_end.md similarity index 100% rename from api-docs/dfbfd82cd9907ddc69e201293660daf21e541934a3b353201f9bd65c6723909b.md rename to buffer/buf_slice_start_end.md diff --git a/api-docs/f138c37d9f50fd2199ac2bb7ad4d281a69d465624d05e579bf232ddd4fddf32d.md b/buffer/buf_subarray_start_end.md similarity index 100% rename from api-docs/f138c37d9f50fd2199ac2bb7ad4d281a69d465624d05e579bf232ddd4fddf32d.md rename to buffer/buf_subarray_start_end.md diff --git a/api-docs/dc3b15c8d2cd01ace78ce973b3092b7a7cf6d69f8087eb92ec72644425c9d393.md b/buffer/buf_swap16.md similarity index 100% rename from api-docs/dc3b15c8d2cd01ace78ce973b3092b7a7cf6d69f8087eb92ec72644425c9d393.md rename to buffer/buf_swap16.md diff --git a/api-docs/b4d9efc89f05c144198ee9e55ffd05bd8b5fde16685bb2d6c914a0c30e87c8ef.md b/buffer/buf_swap32.md similarity index 100% rename from api-docs/b4d9efc89f05c144198ee9e55ffd05bd8b5fde16685bb2d6c914a0c30e87c8ef.md rename to buffer/buf_swap32.md diff --git a/api-docs/9444af56a1057f38c38e3bc58cb522a12603cc8c37bd540f5bc14953e19fd0d4.md b/buffer/buf_swap64.md similarity index 100% rename from api-docs/9444af56a1057f38c38e3bc58cb522a12603cc8c37bd540f5bc14953e19fd0d4.md rename to buffer/buf_swap64.md diff --git a/api-docs/d6c3c10f97d4d41420fd5cb5f8c978072bf90fd2cf6d11cfdbce209ca32a15c6.md b/buffer/buf_tojson.md similarity index 100% rename from api-docs/d6c3c10f97d4d41420fd5cb5f8c978072bf90fd2cf6d11cfdbce209ca32a15c6.md rename to buffer/buf_tojson.md diff --git a/api-docs/effdef2edd271f4ec1403b692b29e93490d8fab0163edd91ba360d7c033fb3c8.md b/buffer/buf_tostring_encoding_start_end.md similarity index 100% rename from api-docs/effdef2edd271f4ec1403b692b29e93490d8fab0163edd91ba360d7c033fb3c8.md rename to buffer/buf_tostring_encoding_start_end.md diff --git a/api-docs/ebdb3b4efe6f1bdd4cbeecb05e673e39227a2988878d8f3d1bc26cf516408a1b.md b/buffer/buf_values.md similarity index 100% rename from api-docs/ebdb3b4efe6f1bdd4cbeecb05e673e39227a2988878d8f3d1bc26cf516408a1b.md rename to buffer/buf_values.md diff --git a/api-docs/ff357faffa113ea730749e7247f44393e4e545128612f78ea80b2d08bed6783c.md b/buffer/buf_write_string_offset_length_encoding.md similarity index 100% rename from api-docs/ff357faffa113ea730749e7247f44393e4e545128612f78ea80b2d08bed6783c.md rename to buffer/buf_write_string_offset_length_encoding.md diff --git a/api-docs/80322a96f1dac0d741287816224e5ccd7350c675a516f716612c753391dece8a.md b/buffer/buf_writebigint64be_value_offset.md similarity index 100% rename from api-docs/80322a96f1dac0d741287816224e5ccd7350c675a516f716612c753391dece8a.md rename to buffer/buf_writebigint64be_value_offset.md diff --git a/api-docs/9e9ee8869c866421a724b02a152e668959a25895e9fc5a4e92bf2b76309377ef.md b/buffer/buf_writebigint64le_value_offset.md similarity index 100% rename from api-docs/9e9ee8869c866421a724b02a152e668959a25895e9fc5a4e92bf2b76309377ef.md rename to buffer/buf_writebigint64le_value_offset.md diff --git a/api-docs/8afec0f15908c2896061bf926376a90ee48b57c2dfad134be208baa189f95f20.md b/buffer/buf_writebiguint64be_value_offset.md similarity index 100% rename from api-docs/8afec0f15908c2896061bf926376a90ee48b57c2dfad134be208baa189f95f20.md rename to buffer/buf_writebiguint64be_value_offset.md diff --git a/api-docs/09054afeac3f107b4cd181c6a97cf66e9e9f07f70b2a851efedd66bea334dbee.md b/buffer/buf_writebiguint64le_value_offset.md similarity index 100% rename from api-docs/09054afeac3f107b4cd181c6a97cf66e9e9f07f70b2a851efedd66bea334dbee.md rename to buffer/buf_writebiguint64le_value_offset.md diff --git a/api-docs/9732dc0bd7d7c2fda4f920fa198ae9bb975e5220d7b457271bee02631f2cbf8f.md b/buffer/buf_writedoublebe_value_offset.md similarity index 100% rename from api-docs/9732dc0bd7d7c2fda4f920fa198ae9bb975e5220d7b457271bee02631f2cbf8f.md rename to buffer/buf_writedoublebe_value_offset.md diff --git a/api-docs/aaa4ff72812d3f25c362b2efdbe002e9ccf7c2dc6ecb57300ed2e6a43613d2c6.md b/buffer/buf_writedoublele_value_offset.md similarity index 100% rename from api-docs/aaa4ff72812d3f25c362b2efdbe002e9ccf7c2dc6ecb57300ed2e6a43613d2c6.md rename to buffer/buf_writedoublele_value_offset.md diff --git a/api-docs/986fba91c35141f17ce16d4ff50ebd607c07ea7c05176c4a78c397c7922613e4.md b/buffer/buf_writefloatbe_value_offset.md similarity index 100% rename from api-docs/986fba91c35141f17ce16d4ff50ebd607c07ea7c05176c4a78c397c7922613e4.md rename to buffer/buf_writefloatbe_value_offset.md diff --git a/api-docs/50c5423dfc290cb99ef0f1e59b41c6c88c1d0b93841cdc82639a1bf04350864d.md b/buffer/buf_writefloatle_value_offset.md similarity index 100% rename from api-docs/50c5423dfc290cb99ef0f1e59b41c6c88c1d0b93841cdc82639a1bf04350864d.md rename to buffer/buf_writefloatle_value_offset.md diff --git a/api-docs/a4607bc2798f132c9d8829868a8461fb24529b0f3f9d8ba013578863133a8da5.md b/buffer/buf_writeint16be_value_offset.md similarity index 100% rename from api-docs/a4607bc2798f132c9d8829868a8461fb24529b0f3f9d8ba013578863133a8da5.md rename to buffer/buf_writeint16be_value_offset.md diff --git a/api-docs/eb7b83fa576b002a00b2945ece283aa6b2e9a450b7b9aebd5efedfa3b43b17ef.md b/buffer/buf_writeint16le_value_offset.md similarity index 100% rename from api-docs/eb7b83fa576b002a00b2945ece283aa6b2e9a450b7b9aebd5efedfa3b43b17ef.md rename to buffer/buf_writeint16le_value_offset.md diff --git a/api-docs/ada21a0fc67bb32f0ef6cf21e627c864ad3f82593bcb3bced3695ed6cf4b36b4.md b/buffer/buf_writeint32be_value_offset.md similarity index 100% rename from api-docs/ada21a0fc67bb32f0ef6cf21e627c864ad3f82593bcb3bced3695ed6cf4b36b4.md rename to buffer/buf_writeint32be_value_offset.md diff --git a/api-docs/815beb5f147380ca7f9f3b4e733fe07a0544fe21af74fc9d0ac8332d65b94636.md b/buffer/buf_writeint32le_value_offset.md similarity index 100% rename from api-docs/815beb5f147380ca7f9f3b4e733fe07a0544fe21af74fc9d0ac8332d65b94636.md rename to buffer/buf_writeint32le_value_offset.md diff --git a/api-docs/36776039d30f6eb860c28a580ba5c64e3138f9e2d0ac81855883455a6ba2aaf7.md b/buffer/buf_writeint8_value_offset.md similarity index 100% rename from api-docs/36776039d30f6eb860c28a580ba5c64e3138f9e2d0ac81855883455a6ba2aaf7.md rename to buffer/buf_writeint8_value_offset.md diff --git a/api-docs/b877eddeaae22476ac287784929b5482b8666b7665bb987f311fa1d7858e405e.md b/buffer/buf_writeintbe_value_offset_bytelength.md similarity index 100% rename from api-docs/b877eddeaae22476ac287784929b5482b8666b7665bb987f311fa1d7858e405e.md rename to buffer/buf_writeintbe_value_offset_bytelength.md diff --git a/api-docs/e59f152044daf82f58d7156d5c56a1ece1bcfaaced92453b4bc81606a4f251c4.md b/buffer/buf_writeintle_value_offset_bytelength.md similarity index 100% rename from api-docs/e59f152044daf82f58d7156d5c56a1ece1bcfaaced92453b4bc81606a4f251c4.md rename to buffer/buf_writeintle_value_offset_bytelength.md diff --git a/api-docs/bb676fca7b2c4d585ff88b2f2f4fae7de1d2e13b0925bbb4fef3ded6d0f8e789.md b/buffer/buf_writeuint16be_value_offset.md similarity index 100% rename from api-docs/bb676fca7b2c4d585ff88b2f2f4fae7de1d2e13b0925bbb4fef3ded6d0f8e789.md rename to buffer/buf_writeuint16be_value_offset.md diff --git a/api-docs/378554ff3580bf9da89b903624a942b0605f0fa36bfbe35280408bebbdfd749d.md b/buffer/buf_writeuint16le_value_offset.md similarity index 100% rename from api-docs/378554ff3580bf9da89b903624a942b0605f0fa36bfbe35280408bebbdfd749d.md rename to buffer/buf_writeuint16le_value_offset.md diff --git a/api-docs/be92b1dfea7f66c8c61e2d6d0155fa80eaa827e2b81c9dbcbb6d9175ebbd1e4b.md b/buffer/buf_writeuint32be_value_offset.md similarity index 100% rename from api-docs/be92b1dfea7f66c8c61e2d6d0155fa80eaa827e2b81c9dbcbb6d9175ebbd1e4b.md rename to buffer/buf_writeuint32be_value_offset.md diff --git a/api-docs/31c1a1e5d38d9cded84251c18eb3dbae1f77358a116b77aad6680695dc6fc280.md b/buffer/buf_writeuint32le_value_offset.md similarity index 100% rename from api-docs/31c1a1e5d38d9cded84251c18eb3dbae1f77358a116b77aad6680695dc6fc280.md rename to buffer/buf_writeuint32le_value_offset.md diff --git a/api-docs/bc9edd1ff87381db359957ad31659b5857b71e370809655fb3139879735224e9.md b/buffer/buf_writeuint8_value_offset.md similarity index 100% rename from api-docs/bc9edd1ff87381db359957ad31659b5857b71e370809655fb3139879735224e9.md rename to buffer/buf_writeuint8_value_offset.md diff --git a/api-docs/c0bf84711b6c45fcec99e8888a0aedc0c132ddb1e43738c48c82bbcd25f9237e.md b/buffer/buf_writeuintbe_value_offset_bytelength.md similarity index 100% rename from api-docs/c0bf84711b6c45fcec99e8888a0aedc0c132ddb1e43738c48c82bbcd25f9237e.md rename to buffer/buf_writeuintbe_value_offset_bytelength.md diff --git a/api-docs/5feb9f0c1175ee424d0641f2791a376d5670406ffee82306187599a1c6e7e514.md b/buffer/buf_writeuintle_value_offset_bytelength.md similarity index 100% rename from api-docs/5feb9f0c1175ee424d0641f2791a376d5670406ffee82306187599a1c6e7e514.md rename to buffer/buf_writeuintle_value_offset_bytelength.md diff --git a/api-docs/95177fe7fc3c8f6b1f0995a7c139d481cd671865c68057fe3f043d04bc2beb54.md b/buffer/buffer.md similarity index 100% rename from api-docs/95177fe7fc3c8f6b1f0995a7c139d481cd671865c68057fe3f043d04bc2beb54.md rename to buffer/buffer.md diff --git a/api-docs/60d4859318dd2d18315de5dd6a4be30a611f62182a81ad228a44158ddfe7ea7e.md b/buffer/buffer_constants.md similarity index 100% rename from api-docs/60d4859318dd2d18315de5dd6a4be30a611f62182a81ad228a44158ddfe7ea7e.md rename to buffer/buffer_constants.md diff --git a/api-docs/affe9d8333e559bfd231a1665039fc781997c3395daad404abe73190696f3609.md b/buffer/buffer_constants_max_length.md similarity index 100% rename from api-docs/affe9d8333e559bfd231a1665039fc781997c3395daad404abe73190696f3609.md rename to buffer/buffer_constants_max_length.md diff --git a/api-docs/68b6ec2e210ac8a81b46e699ad47e76202a6c9a01a54550717d62801ffa21fa6.md b/buffer/buffer_constants_max_string_length.md similarity index 100% rename from api-docs/68b6ec2e210ac8a81b46e699ad47e76202a6c9a01a54550717d62801ffa21fa6.md rename to buffer/buffer_constants_max_string_length.md diff --git a/api-docs/cba05cd2398ba351772dadbb2cc28a41e2fab3e1abb772c5c692a61784115336.md b/buffer/buffer_from_buffer_alloc_and_buffer_allocunsafe.md similarity index 100% rename from api-docs/cba05cd2398ba351772dadbb2cc28a41e2fab3e1abb772c5c692a61784115336.md rename to buffer/buffer_from_buffer_alloc_and_buffer_allocunsafe.md diff --git a/api-docs/e35079c85b58af259065ffa5fb79879d5a81515060d4939a19cf1bde571954ee.md b/buffer/buffer_inspect_max_bytes.md similarity index 100% rename from api-docs/e35079c85b58af259065ffa5fb79879d5a81515060d4939a19cf1bde571954ee.md rename to buffer/buffer_inspect_max_bytes.md diff --git a/api-docs/aae4c592b3760dd2d8f931bf47a791b04f1fe84343d4a9f422f906ff15ef2bd5.md b/buffer/buffer_kmaxlength.md similarity index 100% rename from api-docs/aae4c592b3760dd2d8f931bf47a791b04f1fe84343d4a9f422f906ff15ef2bd5.md rename to buffer/buffer_kmaxlength.md diff --git a/api-docs/1f8eeb5a3ee1494a5efdf883f81861e1b7ac7e29e84932ed98e14eff2946a5ac.md b/buffer/buffer_transcode_source_fromenc_toenc.md similarity index 100% rename from api-docs/1f8eeb5a3ee1494a5efdf883f81861e1b7ac7e29e84932ed98e14eff2946a5ac.md rename to buffer/buffer_transcode_source_fromenc_toenc.md diff --git a/api-docs/17906ba17953795a6f0e03d9a8896b36c3002da126e6e45378f1435815d0ee21.md b/buffer/buffers_and_character_encodings.md similarity index 100% rename from api-docs/17906ba17953795a6f0e03d9a8896b36c3002da126e6e45378f1435815d0ee21.md rename to buffer/buffers_and_character_encodings.md diff --git a/api-docs/4b516d354ede1f728d262cd29ddd1690bc73c5bebd596023986fe79f507afc14.md b/buffer/buffers_and_iteration.md similarity index 100% rename from api-docs/4b516d354ede1f728d262cd29ddd1690bc73c5bebd596023986fe79f507afc14.md rename to buffer/buffers_and_iteration.md diff --git a/api-docs/66d3d6dd4436c56f39288238802138a2161d066848ce83b957edeafd2e161dcb.md b/buffer/buffers_and_typedarray.md similarity index 100% rename from api-docs/66d3d6dd4436c56f39288238802138a2161d066848ce83b957edeafd2e161dcb.md rename to buffer/buffers_and_typedarray.md diff --git a/api-docs/8fa6976d343bcc0c272c8b62cb036cad5c98935792e78c060fc516c6114119b5.md b/buffer/class_buffer.md similarity index 100% rename from api-docs/8fa6976d343bcc0c272c8b62cb036cad5c98935792e78c060fc516c6114119b5.md rename to buffer/class_buffer.md diff --git a/api-docs/a318fd6fde703d77903db991efc46bfddd8d1a38c3e9f65e2e435bb964e0a1d3.md b/buffer/class_method_buffer_alloc_size_fill_encoding.md similarity index 100% rename from api-docs/a318fd6fde703d77903db991efc46bfddd8d1a38c3e9f65e2e435bb964e0a1d3.md rename to buffer/class_method_buffer_alloc_size_fill_encoding.md diff --git a/api-docs/af97460c8817ca6861fc885494fa13b286041848aecaecc4349d50b9545dd463.md b/buffer/class_method_buffer_allocunsafe_size.md similarity index 100% rename from api-docs/af97460c8817ca6861fc885494fa13b286041848aecaecc4349d50b9545dd463.md rename to buffer/class_method_buffer_allocunsafe_size.md diff --git a/api-docs/25970bf5e00aee70c3003b73c2db91d9e9e3e10427f5e2de330644f2922d6faa.md b/buffer/class_method_buffer_allocunsafeslow_size.md similarity index 100% rename from api-docs/25970bf5e00aee70c3003b73c2db91d9e9e3e10427f5e2de330644f2922d6faa.md rename to buffer/class_method_buffer_allocunsafeslow_size.md diff --git a/api-docs/1392986206310c35dafcce6dc1dcdb69b334f22c6e340fc1dabaa854d8975ca6.md b/buffer/class_method_buffer_bytelength_string_encoding.md similarity index 100% rename from api-docs/1392986206310c35dafcce6dc1dcdb69b334f22c6e340fc1dabaa854d8975ca6.md rename to buffer/class_method_buffer_bytelength_string_encoding.md diff --git a/api-docs/0d7aff484621c199cddb6825d8494154e408c027a390c579f745753b2f28fecc.md b/buffer/class_method_buffer_compare_buf1_buf2.md similarity index 100% rename from api-docs/0d7aff484621c199cddb6825d8494154e408c027a390c579f745753b2f28fecc.md rename to buffer/class_method_buffer_compare_buf1_buf2.md diff --git a/api-docs/ae56012f5999ed616fac88c0320b6e9951a703a59cc4637077d10f36b425b8c3.md b/buffer/class_method_buffer_concat_list_totallength.md similarity index 100% rename from api-docs/ae56012f5999ed616fac88c0320b6e9951a703a59cc4637077d10f36b425b8c3.md rename to buffer/class_method_buffer_concat_list_totallength.md diff --git a/api-docs/b71c5b9c4b1c26198fbb9369d567a442a40b6726d9ffc7dcf4d48a0447269c02.md b/buffer/class_method_buffer_from_array.md similarity index 100% rename from api-docs/b71c5b9c4b1c26198fbb9369d567a442a40b6726d9ffc7dcf4d48a0447269c02.md rename to buffer/class_method_buffer_from_array.md diff --git a/api-docs/277e167302a0c123189688b04a46396dd449e60aaf6f9dddfb7dc05f980d8107.md b/buffer/class_method_buffer_from_arraybuffer_byteoffset_length.md similarity index 100% rename from api-docs/277e167302a0c123189688b04a46396dd449e60aaf6f9dddfb7dc05f980d8107.md rename to buffer/class_method_buffer_from_arraybuffer_byteoffset_length.md diff --git a/api-docs/d05cc69659ab94e5afbd3070317b1d48f53d8b5cf1a998cfff9de98b8b17fa9d.md b/buffer/class_method_buffer_from_buffer.md similarity index 100% rename from api-docs/d05cc69659ab94e5afbd3070317b1d48f53d8b5cf1a998cfff9de98b8b17fa9d.md rename to buffer/class_method_buffer_from_buffer.md diff --git a/api-docs/79cc00fee3a195b37a7e747c52786013dc18dca05d98ed90aab0850ae034ca8a.md b/buffer/class_method_buffer_from_object_offsetorencoding_length.md similarity index 100% rename from api-docs/79cc00fee3a195b37a7e747c52786013dc18dca05d98ed90aab0850ae034ca8a.md rename to buffer/class_method_buffer_from_object_offsetorencoding_length.md diff --git a/api-docs/be4a836cdb654b4f5f6f42b579aebcc0837d08eba62bd89f0f69005ec56706fa.md b/buffer/class_method_buffer_from_string_encoding.md similarity index 100% rename from api-docs/be4a836cdb654b4f5f6f42b579aebcc0837d08eba62bd89f0f69005ec56706fa.md rename to buffer/class_method_buffer_from_string_encoding.md diff --git a/api-docs/a215bc8218cc614ad46c3585a983a4accd237d082e897890e046699ac0c47702.md b/buffer/class_method_buffer_isbuffer_obj.md similarity index 100% rename from api-docs/a215bc8218cc614ad46c3585a983a4accd237d082e897890e046699ac0c47702.md rename to buffer/class_method_buffer_isbuffer_obj.md diff --git a/api-docs/3a5638c3282e54cb3f1a2bbe08880aeefc7548c83f45daca3db8f7d926568a02.md b/buffer/class_method_buffer_isencoding_encoding.md similarity index 100% rename from api-docs/3a5638c3282e54cb3f1a2bbe08880aeefc7548c83f45daca3db8f7d926568a02.md rename to buffer/class_method_buffer_isencoding_encoding.md diff --git a/api-docs/bf40443fd3d8e7ed8e1d0ed39808294423155626eb68525832826018c88ebbb9.md b/buffer/class_property_buffer_poolsize.md similarity index 100% rename from api-docs/bf40443fd3d8e7ed8e1d0ed39808294423155626eb68525832826018c88ebbb9.md rename to buffer/class_property_buffer_poolsize.md diff --git a/buffer/class_slowbuffer.md b/buffer/class_slowbuffer.md new file mode 100644 index 00000000..00106ea4 --- /dev/null +++ b/buffer/class_slowbuffer.md @@ -0,0 +1,37 @@ + + +> Stability: 0 - Deprecated: Use [`Buffer.allocUnsafeSlow()`][] instead. + +Returns an un-pooled `Buffer`. + +In order to avoid the garbage collection overhead of creating many individually +allocated `Buffer` instances, by default allocations under 4KB are sliced from a +single larger allocated object. + +In the case where a developer may need to retain a small chunk of memory from a +pool for an indeterminate amount of time, it may be appropriate to create an +un-pooled `Buffer` instance using `SlowBuffer` then copy out the relevant bits. + +```js +// Need to keep around a few small chunks of memory. +const store = []; + +socket.on('readable', () => { + let data; + while (null !== (data = readable.read())) { + // Allocate for retained data. + const sb = SlowBuffer(10); + + // Copy the data into the new allocation. + data.copy(sb, 0, 0, 10); + + store.push(sb); + } +}); +``` + +Use of `SlowBuffer` should be used only as a last resort *after* a developer +has observed undue memory retention in their applications. + diff --git a/buffer/new_buffer_array.md b/buffer/new_buffer_array.md new file mode 100644 index 00000000..aadcdc9b --- /dev/null +++ b/buffer/new_buffer_array.md @@ -0,0 +1,26 @@ + + +> Stability: 0 - Deprecated: Use [`Buffer.from(array)`][] instead. + +* `array` {integer[]} An array of bytes to copy from. + +Allocates a new `Buffer` using an `array` of octets. + +```js +// Creates a new Buffer containing the UTF-8 bytes of the string 'buffer'. +const buf = new Buffer([0x62, 0x75, 0x66, 0x66, 0x65, 0x72]); +``` + diff --git a/buffer/new_buffer_arraybuffer_byteoffset_length.md b/buffer/new_buffer_arraybuffer_byteoffset_length.md new file mode 100644 index 00000000..1e2e4726 --- /dev/null +++ b/buffer/new_buffer_arraybuffer_byteoffset_length.md @@ -0,0 +1,56 @@ + + +> Stability: 0 - Deprecated: Use +> [`Buffer.from(arrayBuffer[, byteOffset[, length]])`][`Buffer.from(arrayBuf)`] +> instead. + +* `arrayBuffer` {ArrayBuffer|SharedArrayBuffer} An [`ArrayBuffer`][], + [`SharedArrayBuffer`][] or the `.buffer` property of a [`TypedArray`][]. +* `byteOffset` {integer} Index of first byte to expose. **Default:** `0`. +* `length` {integer} Number of bytes to expose. + **Default:** `arrayBuffer.length - byteOffset`. + +This creates a view of the [`ArrayBuffer`][] or [`SharedArrayBuffer`][] without +copying the underlying memory. For example, when passed a reference to the +`.buffer` property of a [`TypedArray`][] instance, the newly created `Buffer` +will share the same allocated memory as the [`TypedArray`][]. + +The optional `byteOffset` and `length` arguments specify a memory range within +the `arrayBuffer` that will be shared by the `Buffer`. + +```js +const arr = new Uint16Array(2); + +arr[0] = 5000; +arr[1] = 4000; + +// Shares memory with `arr`. +const buf = new Buffer(arr.buffer); + +console.log(buf); +// Prints: + +// Changing the original Uint16Array changes the Buffer also. +arr[1] = 6000; + +console.log(buf); +// Prints: +``` + diff --git a/buffer/new_buffer_buffer.md b/buffer/new_buffer_buffer.md new file mode 100644 index 00000000..9143a9b1 --- /dev/null +++ b/buffer/new_buffer_buffer.md @@ -0,0 +1,34 @@ + + +> Stability: 0 - Deprecated: Use [`Buffer.from(buffer)`][] instead. + +* `buffer` {Buffer|Uint8Array} An existing `Buffer` or [`Uint8Array`][] from + which to copy data. + +Copies the passed `buffer` data onto a new `Buffer` instance. + +```js +const buf1 = new Buffer('buffer'); +const buf2 = new Buffer(buf1); + +buf1[0] = 0x61; + +console.log(buf1.toString()); +// Prints: auffer +console.log(buf2.toString()); +// Prints: buffer +``` + diff --git a/buffer/new_buffer_size.md b/buffer/new_buffer_size.md new file mode 100644 index 00000000..da07487f --- /dev/null +++ b/buffer/new_buffer_size.md @@ -0,0 +1,41 @@ + + +> Stability: 0 - Deprecated: Use [`Buffer.alloc()`][] instead (also see +> [`Buffer.allocUnsafe()`][]). + +* `size` {integer} The desired length of the new `Buffer`. + +Allocates a new `Buffer` of `size` bytes. If `size` is larger than +[`buffer.constants.MAX_LENGTH`][] or smaller than 0, [`ERR_INVALID_OPT_VALUE`][] +is thrown. A zero-length `Buffer` is created if `size` is 0. + +Prior to Node.js 8.0.0, the underlying memory for `Buffer` instances +created in this way is *not initialized*. The contents of a newly created +`Buffer` are unknown and *may contain sensitive data*. Use +[`Buffer.alloc(size)`][`Buffer.alloc()`] instead to initialize a `Buffer` +with zeroes. + +```js +const buf = new Buffer(10); + +console.log(buf); +// Prints: +``` + diff --git a/buffer/new_buffer_string_encoding.md b/buffer/new_buffer_string_encoding.md new file mode 100644 index 00000000..05222389 --- /dev/null +++ b/buffer/new_buffer_string_encoding.md @@ -0,0 +1,36 @@ + + +> Stability: 0 - Deprecated: +> Use [`Buffer.from(string[, encoding])`][`Buffer.from(string)`] instead. + +* `string` {string} String to encode. +* `encoding` {string} The encoding of `string`. **Default:** `'utf8'`. + +Creates a new `Buffer` containing `string`. The `encoding` parameter identifies +the character encoding of `string`. + +```js +const buf1 = new Buffer('this is a tést'); +const buf2 = new Buffer('7468697320697320612074c3a97374', 'hex'); + +console.log(buf1.toString()); +// Prints: this is a tést +console.log(buf2.toString()); +// Prints: this is a tést +console.log(buf1.toString('ascii')); +// Prints: this is a tC)st +``` + diff --git a/buffer/new_slowbuffer_size.md b/buffer/new_slowbuffer_size.md new file mode 100644 index 00000000..0ae507c9 --- /dev/null +++ b/buffer/new_slowbuffer_size.md @@ -0,0 +1,31 @@ + + +> Stability: 0 - Deprecated: Use [`Buffer.allocUnsafeSlow()`][] instead. + +* `size` {integer} The desired length of the new `SlowBuffer`. + +Allocates a new `Buffer` of `size` bytes. If `size` is larger than +[`buffer.constants.MAX_LENGTH`][] or smaller than 0, [`ERR_INVALID_OPT_VALUE`][] +is thrown. A zero-length `Buffer` is created if `size` is 0. + +The underlying memory for `SlowBuffer` instances is *not initialized*. The +contents of a newly created `SlowBuffer` are unknown and may contain sensitive +data. Use [`buf.fill(0)`][`buf.fill()`] to initialize a `SlowBuffer` with +zeroes. + +```js +const { SlowBuffer } = require('buffer'); + +const buf = new SlowBuffer(5); + +console.log(buf); +// Prints: (contents may vary): + +buf.fill(0); + +console.log(buf); +// Prints: +``` + diff --git a/api-docs/4ae2c1a36dfdc4a12a69dadd197939411b7eb1703586d21b597f84f04847af5b.md b/buffer/the_zero_fill_buffers_command_line_option.md similarity index 100% rename from api-docs/4ae2c1a36dfdc4a12a69dadd197939411b7eb1703586d21b597f84f04847af5b.md rename to buffer/the_zero_fill_buffers_command_line_option.md diff --git a/api-docs/e7fabd725bca3de65132e58deadc37c3d0e4dbf4231bf30f57081029d5f4545c.md b/buffer/what_makes_buffer_allocunsafe_and_buffer_allocunsafeslow_unsafe.md similarity index 100% rename from api-docs/e7fabd725bca3de65132e58deadc37c3d0e4dbf4231bf30f57081029d5f4545c.md rename to buffer/what_makes_buffer_allocunsafe_and_buffer_allocunsafeslow_unsafe.md diff --git a/api-docs/6e3b925f7c129296f86f726e64ff694c92ce001fa41db859e977002da43dee41.md b/child_process/asynchronous_process_creation.md similarity index 100% rename from api-docs/6e3b925f7c129296f86f726e64ff694c92ce001fa41db859e977002da43dee41.md rename to child_process/asynchronous_process_creation.md diff --git a/api-docs/51d119504dfe709a5dc4cb3964bdce3e859fda3ac937e8ee6e91b62fd02d680e.md b/child_process/child_process.md similarity index 100% rename from api-docs/51d119504dfe709a5dc4cb3964bdce3e859fda3ac937e8ee6e91b62fd02d680e.md rename to child_process/child_process.md diff --git a/api-docs/89bd3e2a1713619ec30e6a4a2df16ccef061a480d1c4a7fbdaeaa2e4c6ab9f99.md b/child_process/child_process_exec_command_options_callback.md similarity index 94% rename from api-docs/89bd3e2a1713619ec30e6a4a2df16ccef061a480d1c4a7fbdaeaa2e4c6ab9f99.md rename to child_process/child_process_exec_command_options_callback.md index 1fe92cc8..8f55054b 100644 --- a/api-docs/89bd3e2a1713619ec30e6a4a2df16ccef061a480d1c4a7fbdaeaa2e4c6ab9f99.md +++ b/child_process/child_process_exec_command_options_callback.md @@ -9,10 +9,10 @@ changes: * `command` {string} 要运行的命令，并带上以空格分隔的参数。 * `options` {Object} * `cwd` {string} 子进程的当前工作目录。**默认值:** `null`。 - * `env` {Object} 环境变量的键值对。**默认值:** `null`。 + * `env` {Object} 环境变量的键值对。**默认值:** `process.env`。 * `encoding` {string} **默认值:** `'utf8'`。 * `shell` {string} 用于执行命令的 shell。参阅 [shell 的要求][Shell Requirements]与 [Windows 默认的 shell][Default Windows Shell]。 - **默认值:** UNIX 上是 `'/bin/sh'`，Windows 上是 `process.env.ComSpec`。 + **默认值:** Unix 上是 `'/bin/sh'`，Windows 上是 `process.env.ComSpec`。 * `timeout` {number} **默认值:** `0`。 * `maxBuffer` {number} stdout 或 stderr 上允许的最大字节数。如果超过限制，则子进程会被终止并且截断任何输出。参阅 [maxBuffer 与 Unicode][`maxBuffer` and Unicode] 中的警告。**默认值:** `1024 * 1024`。 * `killSignal` {string|integer} **默认值:** `'SIGTERM'`。 diff --git a/api-docs/763f4426dfefd0a2b31f5e36abf98fc3452a5d265b7ed3eab6a3693cd99cffb0.md b/child_process/child_process_execfile_file_args_options_callback.md similarity index 96% rename from api-docs/763f4426dfefd0a2b31f5e36abf98fc3452a5d265b7ed3eab6a3693cd99cffb0.md rename to child_process/child_process_execfile_file_args_options_callback.md index b4f48917..fdd127c7 100644 --- a/api-docs/763f4426dfefd0a2b31f5e36abf98fc3452a5d265b7ed3eab6a3693cd99cffb0.md +++ b/child_process/child_process_execfile_file_args_options_callback.md @@ -10,7 +10,7 @@ changes: * `args` {string[]} 字符串参数的列表。 * `options` {Object} * `cwd` {string} 子进程的当前工作目录。 - * `env` {Object} 环境变量的键值对。 + * `env` {Object} 环境变量的键值对。**默认值:** `process.env`。 * `encoding` {string} 字符编码。**默认值:** `'utf8'`。 * `timeout` {number} **默认值:** `0`。 * `maxBuffer` {number} stdout 或 stderr 上允许的最大字节数。如果超过限制，则子进程会被终止并且截断任何输出。参阅 [maxBuffer 与 Unicode][`maxBuffer` and Unicode] 中的警告。**默认值:** `1024 * 1024`。 @@ -20,7 +20,7 @@ changes: * `windowsHide` {boolean} 隐藏子进程的控制台窗口（在 Windows 系统上通常会创建）。**默认值:** `false`。 * `windowsVerbatimArguments` {boolean} 在 Windows 上不为参数加上引号或转义。在 Unix 上忽略。**默认值:** `false`。 * `shell` {boolean|string} 如果为 `true`，则在 shell 中运行 `command`。 - 在 UNIX 上使用 `'/bin/sh'`，在 Windows 上使用 `process.env.ComSpec`。 + 在 Unix 上使用 `'/bin/sh'`，在 Windows 上使用 `process.env.ComSpec`。 可以将不同的 shell 指定为字符串。 参阅 [shell 的要求][Shell Requirements]与 [Windows 默认的 shell][Default Windows Shell]。 **默认值:** `false`（没有 shell）。 diff --git a/api-docs/4c1ee2b5c1766a677c0b7ad956ecb5655cf26ccdd2112ff9efd34dcccad96a55.md b/child_process/child_process_execfilesync_file_args_options.md similarity index 95% rename from api-docs/4c1ee2b5c1766a677c0b7ad956ecb5655cf26ccdd2112ff9efd34dcccad96a55.md rename to child_process/child_process_execfilesync_file_args_options.md index 9a226fb9..1a83d7c9 100644 --- a/api-docs/4c1ee2b5c1766a677c0b7ad956ecb5655cf26ccdd2112ff9efd34dcccad96a55.md +++ b/child_process/child_process_execfilesync_file_args_options.md @@ -22,7 +22,7 @@ changes: * `cwd` {string} 子进程的当前工作目录。 * `input` {string|Buffer|TypedArray|DataView} 该值将会作为 stdin 传给衍生的进程。提供此值将会覆盖 `stdio[0]`。 * `stdio` {string|Array} 子进程的 stdio 配置。默认情况下，除非指定了 `stdio`，否则 `stderr` 将会被输出到父进程的 stderr。**默认值:** `'pipe'`。 - * `env` {Object} 环境变量的键值对。 + * `env` {Object} 环境变量的键值对。**默认值:** `process.env`。 * `uid` {number} 设置进程的用户标识，参阅 setuid(2)。 * `gid` {number} 设置进程的群组标识，参阅 setgid(2)。 * `timeout` {number} 允许进程运行的最长时间，以毫秒为单位。**默认值:** `undefined`。 @@ -31,7 +31,7 @@ changes: * `encoding` {string} 用于所有 stdio 输入和输出的字符编码。**默认值:** `'buffer'`。 * `windowsHide` {boolean} 隐藏子进程的控制台窗口（在 Windows 系统上通常会创建）。**默认值:** `false`。 * `shell` {boolean|string} 如果为 `true`，则在 shell 中运行 `command`。 - 在 UNIX 上使用 `'/bin/sh'`，在 Windows 上使用 `process.env.ComSpec`。 + 在 Unix 上使用 `'/bin/sh'`，在 Windows 上使用 `process.env.ComSpec`。 可以将不同的 shell 指定为字符串。 参阅 [shell 的要求][Shell Requirements]与 [Windows 默认的 shell][Default Windows Shell]。 **默认值:** `false`（没有 shell）。 diff --git a/api-docs/8848c03a5042b7422a09f5214f1ae233cad48b7db9b440978afba2847fc28a4c.md b/child_process/child_process_execsync_command_options.md similarity index 94% rename from api-docs/8848c03a5042b7422a09f5214f1ae233cad48b7db9b440978afba2847fc28a4c.md rename to child_process/child_process_execsync_command_options.md index b1b42bdf..b51bc377 100644 --- a/api-docs/8848c03a5042b7422a09f5214f1ae233cad48b7db9b440978afba2847fc28a4c.md +++ b/child_process/child_process_execsync_command_options.md @@ -18,9 +18,9 @@ changes: * `cwd` {string} 子进程的当前工作目录。 * `input` {string|Buffer|TypedArray|DataView} 该值将会作为 stdin 传给衍生的进程。提供此值将会覆盖 `stdio[0]`。 * `stdio` {string|Array} 子进程的 stdio 配置。默认情况下，除非指定了 `stdio`，否则 `stderr` 将会被输出到父进程的 stderr。**默认值:** `'pipe'`。 - * `env` {Object} 环境变量的键值对。 + * `env` {Object} 环境变量的键值对。**默认值:** `process.env`。 * `shell` {string} 用于执行命令的 shell。参阅 [shell 的要求][Shell Requirements]与 [Windows 默认的 shell][Default Windows Shell]。 - **默认值:** UNIX 上是 `'/bin/sh'`，Windows 上是 `process.env.ComSpec`。 + **默认值:** Unix 上是 `'/bin/sh'`，Windows 上是 `process.env.ComSpec`。 * `uid` {number} 设置进程的用户标识，参阅 setuid(2)。 * `gid` {number} 设置进程的群组标识，参阅 setgid(2)。 * `timeout` {number} 允许进程运行的最长时间，以毫秒为单位。**默认值:** `undefined`。 diff --git a/api-docs/022ce4c274a34ea348b52eeba9236d8ea582322ac5dd0fcfa2a40bf8181b211a.md b/child_process/child_process_fork_modulepath_args_options.md similarity index 97% rename from api-docs/022ce4c274a34ea348b52eeba9236d8ea582322ac5dd0fcfa2a40bf8181b211a.md rename to child_process/child_process_fork_modulepath_args_options.md index b89dd440..5c2cbc1a 100644 --- a/api-docs/022ce4c274a34ea348b52eeba9236d8ea582322ac5dd0fcfa2a40bf8181b211a.md +++ b/child_process/child_process_fork_modulepath_args_options.md @@ -14,7 +14,7 @@ changes: * `options` {Object} * `cwd` {string} 子进程的当前工作目录。 * `detached` {boolean} 准备子进程独立于其父进程运行。具体行为取决于平台，参阅 [`options.detached`]。 - * `env` {Object} 环境变量的键值对。 + * `env` {Object} 环境变量的键值对。**默认值:** `process.env`。 * `execPath` {string} 用于创建子进程的可执行文件。 * `execArgv` {string[]} 传给可执行文件的字符串参数的列表。**默认值:** `process.execArgv`。 * `silent` {boolean} 如果为 `true`，则子进程的 stdin、stdout 和 stderr 将会被输送到父进程，否则它们将会继承自父进程，详见 [`child_process.spawn()`] 的 [`stdio`] 中的 `'pipe'` 和 `'inherit'` 选项。**默认值:** `false`。 diff --git a/api-docs/e2a344f45535fa78b484b46031d5f6bb36f4c7ef2191ab765348b217a566fb77.md b/child_process/child_process_spawn_command_args_options.md similarity index 96% rename from api-docs/e2a344f45535fa78b484b46031d5f6bb36f4c7ef2191ab765348b217a566fb77.md rename to child_process/child_process_spawn_command_args_options.md index 1e404b53..0ff783e4 100644 --- a/api-docs/e2a344f45535fa78b484b46031d5f6bb36f4c7ef2191ab765348b217a566fb77.md +++ b/child_process/child_process_spawn_command_args_options.md @@ -16,14 +16,14 @@ changes: * `args` {string[]} 字符串参数的列表。 * `options` {Object} * `cwd` {string} 子进程的当前工作目录。 - * `env` {Object} 环境变量的键值对。 + * `env` {Object} 环境变量的键值对。**默认值:** `process.env`。 * `argv0` {string} 显式地设置发送给子进程的 `argv[0]` 的值。如果没有指定，则将会被设置为 `command` 的值。 * `stdio` {Array|string} 子进程的 stdio 配置。参阅 [`options.stdio`][`stdio`]。 * `detached` {boolean} 准备子进程独立于其父进程运行。具体行为取决于平台，参阅 [`options.detached`]。 * `uid` {number} 设置进程的用户标识，参阅 setuid(2)。 * `gid` {number} 设置进程的群组标识，参阅 setgid(2)。 * `shell` {boolean|string} 如果为 `true`，则在 shell 中运行 `command`。 - 在 UNIX 上使用 `'/bin/sh'`，在 Windows 上使用 `process.env.ComSpec`。 + 在 Unix 上使用 `'/bin/sh'`，在 Windows 上使用 `process.env.ComSpec`。 可以将不同的 shell 指定为字符串。 参阅 [shell 的要求][Shell Requirements]与 [Windows 默认的 shell][Default Windows Shell]。 **默认值:** `false`（没有 shell）。 diff --git a/api-docs/12b1e817b03f301bcecb93365e2c29b38522a4b00ff856c2b56062bdeb622187.md b/child_process/child_process_spawnsync_command_args_options.md similarity index 96% rename from api-docs/12b1e817b03f301bcecb93365e2c29b38522a4b00ff856c2b56062bdeb622187.md rename to child_process/child_process_spawnsync_command_args_options.md index 0ea9dc7f..2aaae581 100644 --- a/api-docs/12b1e817b03f301bcecb93365e2c29b38522a4b00ff856c2b56062bdeb622187.md +++ b/child_process/child_process_spawnsync_command_args_options.md @@ -26,7 +26,7 @@ changes: * `input` {string|Buffer|TypedArray|DataView} 该值将会作为 stdin 传给衍生的进程。提供此值将会覆盖 `stdio[0]`。 * `argv0` {string} 显式地设置发送给子进程的 `argv[0]` 的值。如果没有指定，则将会被设置为 `command` 的值。 * `stdio` {string|Array} 子进程的 stdio 配置。 - * `env` {Object} 环境变量的键值对。 + * `env` {Object} 环境变量的键值对。**默认值:** `process.env`。 * `uid` {number} 设置进程的用户标识，参阅 setuid(2)。 * `gid` {number} 设置进程的群组标识，参阅 setgid(2)。 * `timeout` {number} 允许进程运行的最长时间，以毫秒为单位。**默认值:** `undefined`。 @@ -34,7 +34,7 @@ changes: * `maxBuffer` {number} stdout 或 stderr 上允许的最大字节数。如果超过限制，则子进程会被终止并且截断任何输出。参阅 [maxBuffer 与 Unicode][`maxBuffer` and Unicode] 中的警告。**默认值:** `1024 * 1024`。 * `encoding` {string} 用于所有 stdio 输入和输出的字符编码。**默认值:** `'buffer'`。 * `shell` {boolean|string} 如果为 `true`，则在 shell 中运行 `command`。 - 在 UNIX 上使用 `'/bin/sh'`，在 Windows 上使用 `process.env.ComSpec`。 + 在 Unix 上使用 `'/bin/sh'`，在 Windows 上使用 `process.env.ComSpec`。 可以将不同的 shell 指定为字符串。 参阅 [shell 的要求][Shell Requirements]与 [Windows 默认的 shell][Default Windows Shell]。 **默认值:** `false`（没有 shell）。 diff --git a/api-docs/8274c3842ee44815e67bc72b82fce7765dad777de21d38e7ae3ab29760765012.md b/child_process/class_childprocess.md similarity index 100% rename from api-docs/8274c3842ee44815e67bc72b82fce7765dad777de21d38e7ae3ab29760765012.md rename to child_process/class_childprocess.md diff --git a/api-docs/a3dcff945ca91035c9c2c1b7e1577837da6a3731cd01aac6a86cfe066bd8a303.md b/child_process/default_windows_shell.md similarity index 100% rename from api-docs/a3dcff945ca91035c9c2c1b7e1577837da6a3731cd01aac6a86cfe066bd8a303.md rename to child_process/default_windows_shell.md diff --git a/api-docs/f2d262e03b0e96c933128c5369b0e7893e910f04ea8c88d61b21cbd666541a65.md b/child_process/event_close.md similarity index 100% rename from api-docs/f2d262e03b0e96c933128c5369b0e7893e910f04ea8c88d61b21cbd666541a65.md rename to child_process/event_close.md diff --git a/api-docs/7984d45baf8b7dd5cb8bb7a041e635b723948d4fd9ecfc66926ca5d2d39d5c4a.md b/child_process/event_disconnect.md similarity index 100% rename from api-docs/7984d45baf8b7dd5cb8bb7a041e635b723948d4fd9ecfc66926ca5d2d39d5c4a.md rename to child_process/event_disconnect.md diff --git a/api-docs/cd673e812fdb99f9d6f98a38c7bc6928eb47627ca3476e0f2afffd0cee11afa3.md b/child_process/event_error.md similarity index 100% rename from api-docs/cd673e812fdb99f9d6f98a38c7bc6928eb47627ca3476e0f2afffd0cee11afa3.md rename to child_process/event_error.md diff --git a/api-docs/91e596857d6cefdf134d310e4e6c8be6730d70ff7b0682189b712f66d2bc55af.md b/child_process/event_exit.md similarity index 100% rename from api-docs/91e596857d6cefdf134d310e4e6c8be6730d70ff7b0682189b712f66d2bc55af.md rename to child_process/event_exit.md diff --git a/api-docs/d729d792f0913183831367a3c9b9a793aa7970b20a313644ad91ec7b4e2f8a2f.md b/child_process/event_message.md similarity index 100% rename from api-docs/d729d792f0913183831367a3c9b9a793aa7970b20a313644ad91ec7b4e2f8a2f.md rename to child_process/event_message.md diff --git a/api-docs/9320698b77fe7f64ff80ee280c65615d03588b46b2fa925714422c6d2f34e25d.md b/child_process/example_sending_a_server_object.md similarity index 95% rename from api-docs/9320698b77fe7f64ff80ee280c65615d03588b46b2fa925714422c6d2f34e25d.md rename to child_process/example_sending_a_server_object.md index 5262cd72..be442f60 100644 --- a/api-docs/9320698b77fe7f64ff80ee280c65615d03588b46b2fa925714422c6d2f34e25d.md +++ b/child_process/example_sending_a_server_object.md @@ -29,5 +29,5 @@ process.on('message', (m, server) => { 一旦服务器在父进程和子进程之间是共享的，则一些连接可被父进程处理，另一些可被子进程处理。 上面的示例使用了一个由 `net` 模块创建的服务器，虽然 `dgram` 模块的服务器使用完全相同的工作流程，但它监听 `'message'` 事件而不是 `'connection'` 事件，且使用 `server.bind()` 而不是 `server.listen()`。 -目前仅在 UNIX 平台上支持这一点。 +目前仅在 Unix 平台上支持这一点。 diff --git a/api-docs/cdd0dfa58f49fbd6d2a76791261f944e69588b3f1b22855dfa7a027f5948e6d1.md b/child_process/example_sending_a_socket_object.md similarity index 100% rename from api-docs/cdd0dfa58f49fbd6d2a76791261f944e69588b3f1b22855dfa7a027f5948e6d1.md rename to child_process/example_sending_a_socket_object.md diff --git a/api-docs/d1ee70a3cc9657708884a681881cc038fc135321d38cf3d432a7f397797b7085.md b/child_process/maxbuffer_and_unicode.md similarity index 100% rename from api-docs/d1ee70a3cc9657708884a681881cc038fc135321d38cf3d432a7f397797b7085.md rename to child_process/maxbuffer_and_unicode.md diff --git a/api-docs/586ee43dfddb0f0d3e99bcdeeea9b93b343512e0cf9a01ddd1b5e5d07f433dd3.md b/child_process/options_detached.md similarity index 100% rename from api-docs/586ee43dfddb0f0d3e99bcdeeea9b93b343512e0cf9a01ddd1b5e5d07f433dd3.md rename to child_process/options_detached.md diff --git a/api-docs/4e152714767ac4bdfb00be5ea94499af063803d5852c8d0ee2423826cae0260b.md b/child_process/options_stdio.md similarity index 98% rename from api-docs/4e152714767ac4bdfb00be5ea94499af063803d5852c8d0ee2423826cae0260b.md rename to child_process/options_stdio.md index 24247665..365ca267 100644 --- a/api-docs/4e152714767ac4bdfb00be5ea94499af063803d5852c8d0ee2423826cae0260b.md +++ b/child_process/options_stdio.md @@ -61,7 +61,7 @@ spawn('prg', [], { stdio: ['pipe', null, null, null, 'pipe'] }); 当在父进程和子进程之间建立 IPC 通道，并且子进程是一个 Node.js 进程时，则子进程启动时不会指向 IPC 通道（使用 `unref()`），直到子进程为 [`'disconnect'`] 事件或 [`'message'`] 事件注册了事件处理函数。 这允许子进程正常退出而不需要通过开放的 IPC 通道保持打开该进程。 -在类 UNIX 操作系统上，[`child_process.spawn()`] 方法在将事件循环与子进程解耦之前会同步地执行内存操作。 +在类 Unix 操作系统上，[`child_process.spawn()`] 方法在将事件循环与子进程解耦之前会同步地执行内存操作。 具有大内存占用的应用程序可能会发现频繁的 [`child_process.spawn()`] 调用成为瓶颈。 详见 [V8 问题 7381][V8 issue 7381]。 diff --git a/api-docs/548cc55355cffcca624c41e109b8882035278af23c6190020954f51a792be1b0.md b/child_process/shell_requirements.md similarity index 100% rename from api-docs/548cc55355cffcca624c41e109b8882035278af23c6190020954f51a792be1b0.md rename to child_process/shell_requirements.md diff --git a/api-docs/8281ddf17d264e5679680cb490a6b38b9e26c88f8fd2835f4321f564c9d2d52f.md b/child_process/spawning_bat_and_cmd_files_on_windows.md similarity index 100% rename from api-docs/8281ddf17d264e5679680cb490a6b38b9e26c88f8fd2835f4321f564c9d2d52f.md rename to child_process/spawning_bat_and_cmd_files_on_windows.md diff --git a/api-docs/6fe5865ac700b7b774c3657288e5b40b684f5cd3dc368877744137a1ba122717.md b/child_process/subprocess_channel.md similarity index 100% rename from api-docs/6fe5865ac700b7b774c3657288e5b40b684f5cd3dc368877744137a1ba122717.md rename to child_process/subprocess_channel.md diff --git a/api-docs/96c1aa6dd4efcf877e8751b8735e70a4acd96288862603933bbf12a736ca048e.md b/child_process/subprocess_connected.md similarity index 100% rename from api-docs/96c1aa6dd4efcf877e8751b8735e70a4acd96288862603933bbf12a736ca048e.md rename to child_process/subprocess_connected.md diff --git a/api-docs/7cda0821a9d147f0b9cd27db52033fa2173b67d3a665c25d56b5c3fa07af0b22.md b/child_process/subprocess_disconnect.md similarity index 100% rename from api-docs/7cda0821a9d147f0b9cd27db52033fa2173b67d3a665c25d56b5c3fa07af0b22.md rename to child_process/subprocess_disconnect.md diff --git a/api-docs/a9b4e7ec6123d4e361f22f2e13b8bbe2591513ccbe0fa6c7f1000841821662ce.md b/child_process/subprocess_kill_signal.md similarity index 100% rename from api-docs/a9b4e7ec6123d4e361f22f2e13b8bbe2591513ccbe0fa6c7f1000841821662ce.md rename to child_process/subprocess_kill_signal.md diff --git a/api-docs/84e56d99e61642860a0c5c6f550515c559b51d6eff17c140dad46796b9d0f06e.md b/child_process/subprocess_killed.md similarity index 100% rename from api-docs/84e56d99e61642860a0c5c6f550515c559b51d6eff17c140dad46796b9d0f06e.md rename to child_process/subprocess_killed.md diff --git a/api-docs/6e2fb07cb7d72313c500729ccb09369ba390a7499e7e86e7da7ec7518daf4f6d.md b/child_process/subprocess_pid.md similarity index 100% rename from api-docs/6e2fb07cb7d72313c500729ccb09369ba390a7499e7e86e7da7ec7518daf4f6d.md rename to child_process/subprocess_pid.md diff --git a/api-docs/7e6706e7cbe65ce012b6e8e1288fabd6a3ffb5fab183fd35b00521f36f4b2053.md b/child_process/subprocess_ref.md similarity index 100% rename from api-docs/7e6706e7cbe65ce012b6e8e1288fabd6a3ffb5fab183fd35b00521f36f4b2053.md rename to child_process/subprocess_ref.md diff --git a/api-docs/ce3355958759c41ec24de3c1a8c1458fe5d12ba81840253d824e2d4d2b018a09.md b/child_process/subprocess_send_message_sendhandle_options_callback.md similarity index 100% rename from api-docs/ce3355958759c41ec24de3c1a8c1458fe5d12ba81840253d824e2d4d2b018a09.md rename to child_process/subprocess_send_message_sendhandle_options_callback.md diff --git a/api-docs/2bc84d863747e7c96f85add71e6af198b09b945d76209bbf0a6b2483ee9afae7.md b/child_process/subprocess_stderr.md similarity index 100% rename from api-docs/2bc84d863747e7c96f85add71e6af198b09b945d76209bbf0a6b2483ee9afae7.md rename to child_process/subprocess_stderr.md diff --git a/api-docs/07541a286b72469969e40e4cadd940714cb75501b908e0821189f555cb23f1e0.md b/child_process/subprocess_stdin.md similarity index 100% rename from api-docs/07541a286b72469969e40e4cadd940714cb75501b908e0821189f555cb23f1e0.md rename to child_process/subprocess_stdin.md diff --git a/api-docs/afd972cf31ac4189dbfa33ca073e4d9f48d3bb961f12425c81f913e43c59f166.md b/child_process/subprocess_stdio.md similarity index 100% rename from api-docs/afd972cf31ac4189dbfa33ca073e4d9f48d3bb961f12425c81f913e43c59f166.md rename to child_process/subprocess_stdio.md diff --git a/api-docs/ce63bd9b2cba7f327fd45f2c1281967a952bf311c6b8c93d5e25d13ed7e54b54.md b/child_process/subprocess_stdout.md similarity index 63% rename from api-docs/ce63bd9b2cba7f327fd45f2c1281967a952bf311c6b8c93d5e25d13ed7e54b54.md rename to child_process/subprocess_stdout.md index 9f052b2f..a430e426 100644 --- a/api-docs/ce63bd9b2cba7f327fd45f2c1281967a952bf311c6b8c93d5e25d13ed7e54b54.md +++ b/child_process/subprocess_stdout.md @@ -11,3 +11,13 @@ added: v0.1.90 `subprocess.stdout` 是 `subprocess.stdio[1]` 的别名。 两个属性都将会指向相同的值。 +```js +const { spawn } = require('child_process'); + +const subprocess = spawn('ls'); + +subprocess.stdout.on('data', (data) => { + console.log(`接收到数据块 ${data}`); +}); +``` + diff --git a/api-docs/76d0da575b8bf3c74b85bc2b6083ef658f36412776a2f4bf431591e09ccfa6f4.md b/child_process/subprocess_unref.md similarity index 100% rename from api-docs/76d0da575b8bf3c74b85bc2b6083ef658f36412776a2f4bf431591e09ccfa6f4.md rename to child_process/subprocess_unref.md diff --git a/api-docs/e0fef1449ff9fc356770b0e207137668687fca88f026c9bd196ac61f64a0a310.md b/child_process/synchronous_process_creation.md similarity index 100% rename from api-docs/e0fef1449ff9fc356770b0e207137668687fca88f026c9bd196ac61f64a0a310.md rename to child_process/synchronous_process_creation.md diff --git a/api-docs/9a8f330483c6a928591e99d24b2e1a6bae082e7be6bec533809926d2bf0671eb.md b/cli/.md similarity index 100% rename from api-docs/9a8f330483c6a928591e99d24b2e1a6bae082e7be6bec533809926d2bf0671eb.md rename to cli/.md diff --git a/api-docs/cb850a0a2222e9602d558e25cc5b46dda3e368e1e24216913c2ab69760954186.md b/cli/_1.md similarity index 100% rename from api-docs/cb850a0a2222e9602d558e25cc5b46dda3e368e1e24216913c2ab69760954186.md rename to cli/_1.md diff --git a/api-docs/eba89869c64b960f62f0d44be0f9ba7a724ac0ebbbf380c10e790c0009c1a70c.md b/cli/abort_on_uncaught_exception.md similarity index 100% rename from api-docs/eba89869c64b960f62f0d44be0f9ba7a724ac0ebbbf380c10e790c0009c1a70c.md rename to cli/abort_on_uncaught_exception.md diff --git a/api-docs/1ec15add9d4a47b4889242f5c98c18c6b97a6f35c2ed6cc48ee8be3718024f89.md b/cli/c_check.md similarity index 100% rename from api-docs/1ec15add9d4a47b4889242f5c98c18c6b97a6f35c2ed6cc48ee8be3718024f89.md rename to cli/c_check.md diff --git a/api-docs/c41320d3c7e1b9a96d52ff9216e1cc755bb3f7938d7f1714566cf120d88ab9d2.md b/cli/command_line_options.md similarity index 100% rename from api-docs/c41320d3c7e1b9a96d52ff9216e1cc755bb3f7938d7f1714566cf120d88ab9d2.md rename to cli/command_line_options.md diff --git a/api-docs/43f77b7f25d354e1f7ca97d5698c5d5b692142e03fae720f3af4d41bd74a74b3.md b/cli/completion_bash.md similarity index 100% rename from api-docs/43f77b7f25d354e1f7ca97d5698c5d5b692142e03fae720f3af4d41bd74a74b3.md rename to cli/completion_bash.md diff --git a/api-docs/48096bbde313f544bb9337e13e4843e26a18c24daa6c6fceadd424bdee378ea2.md b/cli/e_eval_script.md similarity index 100% rename from api-docs/48096bbde313f544bb9337e13e4843e26a18c24daa6c6fceadd424bdee378ea2.md rename to cli/e_eval_script.md diff --git a/api-docs/9a3db4e08078a888dda5aa5804058158f9a55db716b497ea6866df1e7ec58938.md b/cli/enable_fips.md similarity index 100% rename from api-docs/9a3db4e08078a888dda5aa5804058158f9a55db716b497ea6866df1e7ec58938.md rename to cli/enable_fips.md diff --git a/api-docs/1d71751ac7621a2391bb3a38feaa038ae7be556589d403537fe2b89fe428a6ab.md b/cli/environment_variables.md similarity index 100% rename from api-docs/1d71751ac7621a2391bb3a38feaa038ae7be556589d403537fe2b89fe428a6ab.md rename to cli/environment_variables.md diff --git a/api-docs/60d380a631255e5bb39f33f241cf2fc3d44ff17abd9f603e45831303be09274e.md b/cli/experimental_modules.md similarity index 100% rename from api-docs/60d380a631255e5bb39f33f241cf2fc3d44ff17abd9f603e45831303be09274e.md rename to cli/experimental_modules.md diff --git a/api-docs/c36797399f005da812b52085924619e17872b959c57733fcdd9ea6dff02c1b41.md b/cli/experimental_repl_await.md similarity index 100% rename from api-docs/c36797399f005da812b52085924619e17872b959c57733fcdd9ea6dff02c1b41.md rename to cli/experimental_repl_await.md diff --git a/api-docs/c94ef538d2a3c400150701c73d12e7192991e6d6e2eb8c6d85b67f0fb3449a30.md b/cli/experimental_vm_modules.md similarity index 100% rename from api-docs/c94ef538d2a3c400150701c73d12e7192991e6d6e2eb8c6d85b67f0fb3449a30.md rename to cli/experimental_vm_modules.md diff --git a/api-docs/30008cdd8551fec47b8bf25c15bd4502e1d322d3427003ea65b1471a18155204.md b/cli/experimental_worker.md similarity index 100% rename from api-docs/30008cdd8551fec47b8bf25c15bd4502e1d322d3427003ea65b1471a18155204.md rename to cli/experimental_worker.md diff --git a/api-docs/2e99a69095f785f1b1866323dd4062327a579880c1c4d19d49ce0e07f81325f9.md b/cli/force_fips.md similarity index 100% rename from api-docs/2e99a69095f785f1b1866323dd4062327a579880c1c4d19d49ce0e07f81325f9.md rename to cli/force_fips.md diff --git a/api-docs/64d9cb304a891fe5bf568abd7073bd50f84be3d6e53a6d8f3cb49720e17ecd04.md b/cli/h_help.md similarity index 100% rename from api-docs/64d9cb304a891fe5bf568abd7073bd50f84be3d6e53a6d8f3cb49720e17ecd04.md rename to cli/h_help.md diff --git a/api-docs/8abc9f945d8109cb25bd3dc0a807f0bc2b5fafecd96cec864e432466ad60848d.md b/cli/i_interactive.md similarity index 100% rename from api-docs/8abc9f945d8109cb25bd3dc0a807f0bc2b5fafecd96cec864e432466ad60848d.md rename to cli/i_interactive.md diff --git a/api-docs/dd2628e0d875c6183b2c9654feab210d81a63c95e52d7ea55e32fca471dd437b.md b/cli/icu_data_dir_file.md similarity index 100% rename from api-docs/dd2628e0d875c6183b2c9654feab210d81a63c95e52d7ea55e32fca471dd437b.md rename to cli/icu_data_dir_file.md diff --git a/api-docs/e22c4d1fc24c537fe4aa8afe21b741bcaa082b3b21f83bb98e276b57250e0f49.md b/cli/inspect_brk_host_port.md similarity index 100% rename from api-docs/e22c4d1fc24c537fe4aa8afe21b741bcaa082b3b21f83bb98e276b57250e0f49.md rename to cli/inspect_brk_host_port.md diff --git a/api-docs/9699d816d8110bdb38fe3b539c015c8109fce9f91afc8b1442058c406566e75b.md b/cli/inspect_host_port.md similarity index 100% rename from api-docs/9699d816d8110bdb38fe3b539c015c8109fce9f91afc8b1442058c406566e75b.md rename to cli/inspect_host_port.md diff --git a/api-docs/11fa15f0490192e2fb98a66feb35c9fd7e8fe41a3abf108f905b87da2ffd6fc3.md b/cli/inspect_port_host_port.md similarity index 100% rename from api-docs/11fa15f0490192e2fb98a66feb35c9fd7e8fe41a3abf108f905b87da2ffd6fc3.md rename to cli/inspect_port_host_port.md diff --git a/api-docs/71514ad46e8a183cd60fbc91df6834d463a5bcb4a9c19b6e2b34b99af290d42b.md b/cli/loader_file.md similarity index 100% rename from api-docs/71514ad46e8a183cd60fbc91df6834d463a5bcb4a9c19b6e2b34b99af290d42b.md rename to cli/loader_file.md diff --git a/api-docs/5e3af0d787f98569733679a6223a87fb8633b6bec47e339e6a8fc2c55321fb43.md b/cli/max_http_header_size_size.md similarity index 100% rename from api-docs/5e3af0d787f98569733679a6223a87fb8633b6bec47e339e6a8fc2c55321fb43.md rename to cli/max_http_header_size_size.md diff --git a/api-docs/2d92d10d3f32ed580600957fa454fd2047dac8867e0338e8c071ee4655906cda.md b/cli/napi_modules.md similarity index 100% rename from api-docs/2d92d10d3f32ed580600957fa454fd2047dac8867e0338e8c071ee4655906cda.md rename to cli/napi_modules.md diff --git a/api-docs/73278ae46070b89370edeac3416bed9ba61d3abff9d93ab4352efa0e7bc7a969.md b/cli/no_deprecation.md similarity index 100% rename from api-docs/73278ae46070b89370edeac3416bed9ba61d3abff9d93ab4352efa0e7bc7a969.md rename to cli/no_deprecation.md diff --git a/api-docs/9886e9b8dd3f758a1f643bb1c2d6e11a760f47428ac97d63f5002701f63eda82.md b/cli/no_force_async_hooks_checks.md similarity index 100% rename from api-docs/9886e9b8dd3f758a1f643bb1c2d6e11a760f47428ac97d63f5002701f63eda82.md rename to cli/no_force_async_hooks_checks.md diff --git a/api-docs/8bc7085c9636a92c5b5144cf8882e382b4a5a5668e3cef8a3bf2051324b4a069.md b/cli/no_warnings.md similarity index 100% rename from api-docs/8bc7085c9636a92c5b5144cf8882e382b4a5a5668e3cef8a3bf2051324b4a069.md rename to cli/no_warnings.md diff --git a/api-docs/19dd0114d28e1feef926bcd02b301efcbd3dfcbd5f5e18afd1fdd763e9de103a.md b/cli/node_debug_module.md similarity index 100% rename from api-docs/19dd0114d28e1feef926bcd02b301efcbd3dfcbd5f5e18afd1fdd763e9de103a.md rename to cli/node_debug_module.md diff --git a/api-docs/9bd7e9ee3c0a46376eaebf3b0e9726f42a709b9dd2e1af11ad1c32c18d7cc891.md b/cli/node_debug_native_module.md similarity index 100% rename from api-docs/9bd7e9ee3c0a46376eaebf3b0e9726f42a709b9dd2e1af11ad1c32c18d7cc891.md rename to cli/node_debug_native_module.md diff --git a/api-docs/bf2ca8461f3cd5a276b8da18e0f058b05300a2d927669e22a0fe112864711cfe.md b/cli/node_disable_colors_1.md similarity index 100% rename from api-docs/bf2ca8461f3cd5a276b8da18e0f058b05300a2d927669e22a0fe112864711cfe.md rename to cli/node_disable_colors_1.md diff --git a/api-docs/f2471307e62643f5d1984d9c24ce806a2425c1dc576dd298578cef3a7de0b990.md b/cli/node_extra_ca_certs_file.md similarity index 100% rename from api-docs/f2471307e62643f5d1984d9c24ce806a2425c1dc576dd298578cef3a7de0b990.md rename to cli/node_extra_ca_certs_file.md diff --git a/api-docs/c3fcb9c19902e48914854131db23a7f69ca0024b38cc363b86f55ccb5bde403e.md b/cli/node_icu_data_file.md similarity index 100% rename from api-docs/c3fcb9c19902e48914854131db23a7f69ca0024b38cc363b86f55ccb5bde403e.md rename to cli/node_icu_data_file.md diff --git a/api-docs/6182c38eb76d0f1acf721a80df8397a1c0e8f51dbeaa099243dce93fd9e0fcf9.md b/cli/node_no_warnings_1.md similarity index 100% rename from api-docs/6182c38eb76d0f1acf721a80df8397a1c0e8f51dbeaa099243dce93fd9e0fcf9.md rename to cli/node_no_warnings_1.md diff --git a/api-docs/c72492c59698e6bdd925192554a4d1a1d27e10d0231bec5ee24eee6669893c1f.md b/cli/node_options_options.md similarity index 100% rename from api-docs/c72492c59698e6bdd925192554a4d1a1d27e10d0231bec5ee24eee6669893c1f.md rename to cli/node_options_options.md diff --git a/api-docs/74c039ccba600fae9a733134b61959d032e2e918cb2eaa11f7e2840a6b1c9378.md b/cli/node_path_path.md similarity index 100% rename from api-docs/74c039ccba600fae9a733134b61959d032e2e918cb2eaa11f7e2840a6b1c9378.md rename to cli/node_path_path.md diff --git a/api-docs/0d204baa7ff49ff7abfcfbb64ade0bb0a5764b35814d253b1577e7e09faedb9d.md b/cli/node_pending_deprecation_1.md similarity index 100% rename from api-docs/0d204baa7ff49ff7abfcfbb64ade0bb0a5764b35814d253b1577e7e09faedb9d.md rename to cli/node_pending_deprecation_1.md diff --git a/api-docs/f3e35dbad52e39d9f1f508ef6be892d81ecd264125d74eeca8376c7f52edd868.md b/cli/node_preserve_symlinks_1.md similarity index 100% rename from api-docs/f3e35dbad52e39d9f1f508ef6be892d81ecd264125d74eeca8376c7f52edd868.md rename to cli/node_preserve_symlinks_1.md diff --git a/api-docs/9c9e3c81775c1ecc657b0df21af8c849000e85bfd95e0927fc18d356e86e9671.md b/cli/node_redirect_warnings_file.md similarity index 100% rename from api-docs/9c9e3c81775c1ecc657b0df21af8c849000e85bfd95e0927fc18d356e86e9671.md rename to cli/node_redirect_warnings_file.md diff --git a/api-docs/336ee70ab7b0c9047a567be2ce4829b6575b7e8a88456977bdfce54075d12734.md b/cli/node_repl_history_file.md similarity index 100% rename from api-docs/336ee70ab7b0c9047a567be2ce4829b6575b7e8a88456977bdfce54075d12734.md rename to cli/node_repl_history_file.md diff --git a/api-docs/7ff8b582ee40afcf1cf4fce0f51559efec52ccc65e155076a50165d589024dad.md b/cli/node_tls_reject_unauthorized_value.md similarity index 100% rename from api-docs/7ff8b582ee40afcf1cf4fce0f51559efec52ccc65e155076a50165d589024dad.md rename to cli/node_tls_reject_unauthorized_value.md diff --git a/api-docs/07e61a56918818b3a6b32f3c7df557321379104be7b28edc75966a160c8343fa.md b/cli/node_v8_coverage_dir.md similarity index 100% rename from api-docs/07e61a56918818b3a6b32f3c7df557321379104be7b28edc75966a160c8343fa.md rename to cli/node_v8_coverage_dir.md diff --git a/api-docs/f093611009ac3189340c96b7d4d6660d1ea00d7cabc61587d80f5888ce63e08b.md b/cli/openssl_conf_file.md similarity index 100% rename from api-docs/f093611009ac3189340c96b7d4d6660d1ea00d7cabc61587d80f5888ce63e08b.md rename to cli/openssl_conf_file.md diff --git a/api-docs/eb5a3edc49ea1abe5e4a08cc4f79eb4ce6617ad2b3c8aae9b5fa73d82ae3fc89.md b/cli/openssl_config_file.md similarity index 100% rename from api-docs/eb5a3edc49ea1abe5e4a08cc4f79eb4ce6617ad2b3c8aae9b5fa73d82ae3fc89.md rename to cli/openssl_config_file.md diff --git a/api-docs/ed09ad70e893bfcb05213e2e9aeb8231a1c04c59e210c24df3ed248d74a833e1.md b/cli/options.md similarity index 100% rename from api-docs/ed09ad70e893bfcb05213e2e9aeb8231a1c04c59e210c24df3ed248d74a833e1.md rename to cli/options.md diff --git a/api-docs/5c0d7f5891abb87e4481e0e6471702709454577729c1525007806ea28f18cf91.md b/cli/p_print_script.md similarity index 100% rename from api-docs/5c0d7f5891abb87e4481e0e6471702709454577729c1525007806ea28f18cf91.md rename to cli/p_print_script.md diff --git a/api-docs/49cdcfd0204612cdaa10bbdc1d579ae9f1169360ae62cf662d8ea0bbc97aee9d.md b/cli/pending_deprecation.md similarity index 100% rename from api-docs/49cdcfd0204612cdaa10bbdc1d579ae9f1169360ae62cf662d8ea0bbc97aee9d.md rename to cli/pending_deprecation.md diff --git a/api-docs/6765f9cf5e935bbae3b9003d1403817d0bd1049d88432d3968c0908c68b165f7.md b/cli/preserve_symlinks.md similarity index 100% rename from api-docs/6765f9cf5e935bbae3b9003d1403817d0bd1049d88432d3968c0908c68b165f7.md rename to cli/preserve_symlinks.md diff --git a/api-docs/7e18a6fcfd99aed524325ec360bbc0a6b9e31034e9487d05b508bdb5464b8097.md b/cli/preserve_symlinks_main.md similarity index 100% rename from api-docs/7e18a6fcfd99aed524325ec360bbc0a6b9e31034e9487d05b508bdb5464b8097.md rename to cli/preserve_symlinks_main.md diff --git a/api-docs/4986332cde81593b4a09617f56760c8612135ac9bdc23d6592c5eedf7634d718.md b/cli/prof.md similarity index 100% rename from api-docs/4986332cde81593b4a09617f56760c8612135ac9bdc23d6592c5eedf7634d718.md rename to cli/prof.md diff --git a/api-docs/b9f31f5c27e0773214650cf2cb630c3173e3f1e05028b640e858940fd60644ea.md b/cli/prof_process.md similarity index 100% rename from api-docs/b9f31f5c27e0773214650cf2cb630c3173e3f1e05028b640e858940fd60644ea.md rename to cli/prof_process.md diff --git a/api-docs/16d5f22d12faed55d8d5cdb4c3911b20f54bd2cae6538422de707021c22c9674.md b/cli/r_require_module.md similarity index 100% rename from api-docs/16d5f22d12faed55d8d5cdb4c3911b20f54bd2cae6538422de707021c22c9674.md rename to cli/r_require_module.md diff --git a/api-docs/766cfc3e5794cfc9738c3ed86c5a518d9f33faf87d5dcf1452169eeb8e36c5d3.md b/cli/redirect_warnings_file.md similarity index 100% rename from api-docs/766cfc3e5794cfc9738c3ed86c5a518d9f33faf87d5dcf1452169eeb8e36c5d3.md rename to cli/redirect_warnings_file.md diff --git a/api-docs/d1bbb870568e1668dcf2c2ba96baa7f8612ff2fa68b6c2ce32d9236dc306b4b2.md b/cli/ssl_cert_dir_dir.md similarity index 100% rename from api-docs/d1bbb870568e1668dcf2c2ba96baa7f8612ff2fa68b6c2ce32d9236dc306b4b2.md rename to cli/ssl_cert_dir_dir.md diff --git a/api-docs/987a6f8704b4a9a6435f220b40c0c868a0de94d595392512f31770d8324a9281.md b/cli/ssl_cert_file_file.md similarity index 100% rename from api-docs/987a6f8704b4a9a6435f220b40c0c868a0de94d595392512f31770d8324a9281.md rename to cli/ssl_cert_file_file.md diff --git a/api-docs/39102a5eac66a6e1eb21bb310b6d5d76ba9c7c50375bbab00739b31158e889fd.md b/cli/synopsis.md similarity index 100% rename from api-docs/39102a5eac66a6e1eb21bb310b6d5d76ba9c7c50375bbab00739b31158e889fd.md rename to cli/synopsis.md diff --git a/api-docs/d170a99b962c9852382e682cf64dd2fe9e0133ce7c65e0a4a8daef483e991e6e.md b/cli/throw_deprecation.md similarity index 100% rename from api-docs/d170a99b962c9852382e682cf64dd2fe9e0133ce7c65e0a4a8daef483e991e6e.md rename to cli/throw_deprecation.md diff --git a/api-docs/17a9b0534a09641bba56fbeca1a39a7b039e44a7ad38315cd7781dd64d2967ab.md b/cli/title_title.md similarity index 100% rename from api-docs/17a9b0534a09641bba56fbeca1a39a7b039e44a7ad38315cd7781dd64d2967ab.md rename to cli/title_title.md diff --git a/api-docs/142ee5cd3aa5a5ddfde6167ef97bb907dedd3411ad607f4d074caafd29c9b80b.md b/cli/tls_cipher_list_list.md similarity index 100% rename from api-docs/142ee5cd3aa5a5ddfde6167ef97bb907dedd3411ad607f4d074caafd29c9b80b.md rename to cli/tls_cipher_list_list.md diff --git a/api-docs/d2bfa9d4240241a1fe006389a1e19904b461a3fbe3c568f6902bfb955c4a1099.md b/cli/trace_deprecation.md similarity index 100% rename from api-docs/d2bfa9d4240241a1fe006389a1e19904b461a3fbe3c568f6902bfb955c4a1099.md rename to cli/trace_deprecation.md diff --git a/api-docs/fdaa10a2fef2a896c14cf37f60d6c8956994e8a09174f51a3c510980c3e088ef.md b/cli/trace_event_categories.md similarity index 100% rename from api-docs/fdaa10a2fef2a896c14cf37f60d6c8956994e8a09174f51a3c510980c3e088ef.md rename to cli/trace_event_categories.md diff --git a/api-docs/633dd2d80d940dc6087084c4c287c1e19eb26862eaf2164503446d9aec4d1ac3.md b/cli/trace_event_file_pattern.md similarity index 100% rename from api-docs/633dd2d80d940dc6087084c4c287c1e19eb26862eaf2164503446d9aec4d1ac3.md rename to cli/trace_event_file_pattern.md diff --git a/api-docs/6fb5d9541a048fb4834a8cf95d4ea63a102db6db55fb345303daebf2f769f054.md b/cli/trace_events_enabled.md similarity index 100% rename from api-docs/6fb5d9541a048fb4834a8cf95d4ea63a102db6db55fb345303daebf2f769f054.md rename to cli/trace_events_enabled.md diff --git a/api-docs/1d686bd83888f336fb66b616446fa7eab1d54601a68d9ed8a2a0d14763577273.md b/cli/trace_sync_io.md similarity index 100% rename from api-docs/1d686bd83888f336fb66b616446fa7eab1d54601a68d9ed8a2a0d14763577273.md rename to cli/trace_sync_io.md diff --git a/api-docs/6be650bb99fe82e109b8601ff56a37018769dbefd2b0f8964a879109ae4a2cae.md b/cli/trace_warnings.md similarity index 100% rename from api-docs/6be650bb99fe82e109b8601ff56a37018769dbefd2b0f8964a879109ae4a2cae.md rename to cli/trace_warnings.md diff --git a/api-docs/52e473f4635c93334145f8a8920be019323d533059a2a2c96588382c237c0da4.md b/cli/track_heap_objects.md similarity index 100% rename from api-docs/52e473f4635c93334145f8a8920be019323d533059a2a2c96588382c237c0da4.md rename to cli/track_heap_objects.md diff --git a/api-docs/a7ce8870e9e0d00b09f40a42d9c0969d414ce285c11a64269af11904ca894ddf.md b/cli/use_bundled_ca_use_openssl_ca.md similarity index 100% rename from api-docs/a7ce8870e9e0d00b09f40a42d9c0969d414ce285c11a64269af11904ca894ddf.md rename to cli/use_bundled_ca_use_openssl_ca.md diff --git a/api-docs/d0d1912dbe74e037fa4106231a224035876b49ea70d7264ca5e200423528fe2f.md b/cli/uv_threadpool_size_size.md similarity index 100% rename from api-docs/d0d1912dbe74e037fa4106231a224035876b49ea70d7264ca5e200423528fe2f.md rename to cli/uv_threadpool_size_size.md diff --git a/api-docs/b265d42fa8007ecd41c67d856472972e98cff44e7fd4ef9f152efd51d52c8955.md b/cli/v8_options.md similarity index 100% rename from api-docs/b265d42fa8007ecd41c67d856472972e98cff44e7fd4ef9f152efd51d52c8955.md rename to cli/v8_options.md diff --git a/api-docs/b5bbdacc5dd7baad8bf7ef4caab66613c99583afb1df6ac790ab8358c0064401.md b/cli/v8_pool_size_num.md similarity index 100% rename from api-docs/b5bbdacc5dd7baad8bf7ef4caab66613c99583afb1df6ac790ab8358c0064401.md rename to cli/v8_pool_size_num.md diff --git a/api-docs/0a2ac3dee61f04314b0048a7e73a71eb0b9825c6e342fd428857328879f7e078.md b/cli/v_version.md similarity index 100% rename from api-docs/0a2ac3dee61f04314b0048a7e73a71eb0b9825c6e342fd428857328879f7e078.md rename to cli/v_version.md diff --git a/api-docs/8f532f099b70278bfadd57c31b9c080daca1336ce723435e004a9f25bf59ec98.md b/cli/warning_binding_inspector_to_a_public_ip_port_combination_is_insecure.md similarity index 100% rename from api-docs/8f532f099b70278bfadd57c31b9c080daca1336ce723435e004a9f25bf59ec98.md rename to cli/warning_binding_inspector_to_a_public_ip_port_combination_is_insecure.md diff --git a/api-docs/428968c59c680d4bacf2551b3a033f9d1efce757c2b768e704f7275e2ecb758e.md b/cli/zero_fill_buffers.md similarity index 100% rename from api-docs/428968c59c680d4bacf2551b3a033f9d1efce757c2b768e704f7275e2ecb758e.md rename to cli/zero_fill_buffers.md diff --git a/api-docs/866ca26c809dad7a197e249531f55fc0c7026301bb5b687f0d1d6fae81ad8d75.md b/cluster/class_worker.md similarity index 100% rename from api-docs/866ca26c809dad7a197e249531f55fc0c7026301bb5b687f0d1d6fae81ad8d75.md rename to cluster/class_worker.md diff --git a/api-docs/001745f64786eb720f7708fba401015868dc8b42dc11d1d9641b3c977588ae74.md b/cluster/cluster.md similarity index 100% rename from api-docs/001745f64786eb720f7708fba401015868dc8b42dc11d1d9641b3c977588ae74.md rename to cluster/cluster.md diff --git a/api-docs/3bd27d2320d7a383758a90b6dc915e39871ca441e1d691b1717addf4cad246c6.md b/cluster/cluster_disconnect_callback.md similarity index 100% rename from api-docs/3bd27d2320d7a383758a90b6dc915e39871ca441e1d691b1717addf4cad246c6.md rename to cluster/cluster_disconnect_callback.md diff --git a/api-docs/25579665dcea434f19cdc71c006276874402fbb427592b0d92a8cc4df4f2c7e6.md b/cluster/cluster_fork_env.md similarity index 100% rename from api-docs/25579665dcea434f19cdc71c006276874402fbb427592b0d92a8cc4df4f2c7e6.md rename to cluster/cluster_fork_env.md diff --git a/api-docs/cd67773bb391a643f62860834ffaa3f31be6c35677cecd3d56b1cc7fce38c1f3.md b/cluster/cluster_ismaster.md similarity index 100% rename from api-docs/cd67773bb391a643f62860834ffaa3f31be6c35677cecd3d56b1cc7fce38c1f3.md rename to cluster/cluster_ismaster.md diff --git a/api-docs/26c73d05ebf309bd1c759c1b15cae75b120b39db93b939b01e6cf4288ab8c565.md b/cluster/cluster_isworker.md similarity index 100% rename from api-docs/26c73d05ebf309bd1c759c1b15cae75b120b39db93b939b01e6cf4288ab8c565.md rename to cluster/cluster_isworker.md diff --git a/api-docs/2e2a8ef03e0237cdd176409e65b3395a986573d0d571b21e872c5fa0e4fe5dc8.md b/cluster/cluster_schedulingpolicy.md similarity index 100% rename from api-docs/2e2a8ef03e0237cdd176409e65b3395a986573d0d571b21e872c5fa0e4fe5dc8.md rename to cluster/cluster_schedulingpolicy.md diff --git a/api-docs/87d37829a8b71950360cfde1a871e18da629c2c6011174a26806336a6d992996.md b/cluster/cluster_settings.md similarity index 100% rename from api-docs/87d37829a8b71950360cfde1a871e18da629c2c6011174a26806336a6d992996.md rename to cluster/cluster_settings.md diff --git a/api-docs/20940c92840ffa9ec3ad86acf8c601a2b1183a36e0f2dd83c0028cb2467e6d5f.md b/cluster/cluster_setupmaster_settings.md similarity index 100% rename from api-docs/20940c92840ffa9ec3ad86acf8c601a2b1183a36e0f2dd83c0028cb2467e6d5f.md rename to cluster/cluster_setupmaster_settings.md diff --git a/api-docs/d8975596c1461189710ac5b9cbc62c3ddcffb86afa29786efed21d7abb9c6aef.md b/cluster/cluster_worker.md similarity index 100% rename from api-docs/d8975596c1461189710ac5b9cbc62c3ddcffb86afa29786efed21d7abb9c6aef.md rename to cluster/cluster_worker.md diff --git a/api-docs/edf8a7b26cfe7e2013a5ab6ff78ea0442416bf19bce7ba2c81e24934688a5fc0.md b/cluster/cluster_workers.md similarity index 100% rename from api-docs/edf8a7b26cfe7e2013a5ab6ff78ea0442416bf19bce7ba2c81e24934688a5fc0.md rename to cluster/cluster_workers.md diff --git a/api-docs/9b6022f93de0034fd7905418ff2cf582872bcfecf4db62b63a3e98492c42160a.md b/cluster/event_disconnect.md similarity index 100% rename from api-docs/9b6022f93de0034fd7905418ff2cf582872bcfecf4db62b63a3e98492c42160a.md rename to cluster/event_disconnect.md diff --git a/api-docs/40c662dc8c70be88d59e5c7142674b2dc5c9b2d6d81c9696a9bf22d9a285707e.md b/cluster/event_disconnect_1.md similarity index 100% rename from api-docs/40c662dc8c70be88d59e5c7142674b2dc5c9b2d6d81c9696a9bf22d9a285707e.md rename to cluster/event_disconnect_1.md diff --git a/api-docs/28b0b495d87dc79c0d591378f66eff8dd61ecda1a0ed2f9700098a99692b7f77.md b/cluster/event_error.md similarity index 100% rename from api-docs/28b0b495d87dc79c0d591378f66eff8dd61ecda1a0ed2f9700098a99692b7f77.md rename to cluster/event_error.md diff --git a/api-docs/8965833829c15c1e1dd8b71ca206f195fb308c0af57d8ef45873de689b7cfddd.md b/cluster/event_exit.md similarity index 100% rename from api-docs/8965833829c15c1e1dd8b71ca206f195fb308c0af57d8ef45873de689b7cfddd.md rename to cluster/event_exit.md diff --git a/api-docs/21f5842d79bef30ade1232efbf488fc252940c50a91e8a5c1511d01bf2a58b4b.md b/cluster/event_exit_1.md similarity index 100% rename from api-docs/21f5842d79bef30ade1232efbf488fc252940c50a91e8a5c1511d01bf2a58b4b.md rename to cluster/event_exit_1.md diff --git a/api-docs/035c24e4fc8ae96a25f0fd60c571c0b3909890aea9433ff2eb4c0ea74d31be90.md b/cluster/event_fork.md similarity index 100% rename from api-docs/035c24e4fc8ae96a25f0fd60c571c0b3909890aea9433ff2eb4c0ea74d31be90.md rename to cluster/event_fork.md diff --git a/api-docs/e701ade5f7c46b5ec0ac650feecf3b8c8646e16b25ff3556642dc5ea465c3a3b.md b/cluster/event_listening.md similarity index 100% rename from api-docs/e701ade5f7c46b5ec0ac650feecf3b8c8646e16b25ff3556642dc5ea465c3a3b.md rename to cluster/event_listening.md diff --git a/api-docs/672ee764600032d062e2678bef7eec266aff695bcf93e98976d685946a38997c.md b/cluster/event_listening_1.md similarity index 96% rename from api-docs/672ee764600032d062e2678bef7eec266aff695bcf93e98976d685946a38997c.md rename to cluster/event_listening_1.md index 00803ace..84a46341 100644 --- a/api-docs/672ee764600032d062e2678bef7eec266aff695bcf93e98976d685946a38997c.md +++ b/cluster/event_listening_1.md @@ -21,6 +21,6 @@ cluster.on('listening', (worker, address) => { * `4` (TCPv4) * `6` (TCPv6) -* `-1` (unix 域 socket) +* `-1` (Unix 域 socket) * `'udp4'` or `'udp6'` (UDP v4 或 v6) diff --git a/api-docs/2fe76d8cd444407eb48985fe8cea196b86c5a66f97a1aab02b1624cda19e1e39.md b/cluster/event_message.md similarity index 100% rename from api-docs/2fe76d8cd444407eb48985fe8cea196b86c5a66f97a1aab02b1624cda19e1e39.md rename to cluster/event_message.md diff --git a/api-docs/1bc34fc2978a4313fd449658bffdf657bd9d2a19ea8317c47081bdf266a95987.md b/cluster/event_message_1.md similarity index 100% rename from api-docs/1bc34fc2978a4313fd449658bffdf657bd9d2a19ea8317c47081bdf266a95987.md rename to cluster/event_message_1.md diff --git a/api-docs/7bc3c34043ece90af47e1afa88f1e744111d0517c36740b50dbce246489f532e.md b/cluster/event_online.md similarity index 100% rename from api-docs/7bc3c34043ece90af47e1afa88f1e744111d0517c36740b50dbce246489f532e.md rename to cluster/event_online.md diff --git a/api-docs/135b00b9bdb0403f367caaccb4dc78d649a875dc06de55a82356cabb2060c870.md b/cluster/event_online_1.md similarity index 100% rename from api-docs/135b00b9bdb0403f367caaccb4dc78d649a875dc06de55a82356cabb2060c870.md rename to cluster/event_online_1.md diff --git a/api-docs/e960d7830fc245d86f36079de0bf2654f18f9d87d11872bf809c4190719c41b8.md b/cluster/event_setup.md similarity index 100% rename from api-docs/e960d7830fc245d86f36079de0bf2654f18f9d87d11872bf809c4190719c41b8.md rename to cluster/event_setup.md diff --git a/api-docs/0282e756d5a46ae99afb565254574c3623af1b241d3b9f031c106e6080a1faa7.md b/cluster/how_it_works.md similarity index 100% rename from api-docs/0282e756d5a46ae99afb565254574c3623af1b241d3b9f031c106e6080a1faa7.md rename to cluster/how_it_works.md diff --git a/api-docs/9175bfcccbb0a4d583ba58ac054cb65fded6146188617942190a8ea9ce74b01e.md b/cluster/worker_disconnect.md similarity index 100% rename from api-docs/9175bfcccbb0a4d583ba58ac054cb65fded6146188617942190a8ea9ce74b01e.md rename to cluster/worker_disconnect.md diff --git a/api-docs/8bcf20cd5bbfc628affff8748d06777a105170b904c90060f907a604f8842831.md b/cluster/worker_exitedafterdisconnect.md similarity index 100% rename from api-docs/8bcf20cd5bbfc628affff8748d06777a105170b904c90060f907a604f8842831.md rename to cluster/worker_exitedafterdisconnect.md diff --git a/api-docs/08b459f71b1d65d34042aadebe679c775c3b8a449c356c896925768ab931657e.md b/cluster/worker_id.md similarity index 100% rename from api-docs/08b459f71b1d65d34042aadebe679c775c3b8a449c356c896925768ab931657e.md rename to cluster/worker_id.md diff --git a/api-docs/cf9730692c10f81b5754878b89c392162e4a241bc97818088f0bb2c9c873f762.md b/cluster/worker_isconnected.md similarity index 100% rename from api-docs/cf9730692c10f81b5754878b89c392162e4a241bc97818088f0bb2c9c873f762.md rename to cluster/worker_isconnected.md diff --git a/api-docs/fe0c05205cbfebf49a0d3f028ff90bf3201c42e66a26a43cd16f721037427f5a.md b/cluster/worker_isdead.md similarity index 100% rename from api-docs/fe0c05205cbfebf49a0d3f028ff90bf3201c42e66a26a43cd16f721037427f5a.md rename to cluster/worker_isdead.md diff --git a/api-docs/d90ea68f5ebbd08371be2136607e16bd4ae0f894066d1c9bf3b02c30f98ae304.md b/cluster/worker_kill_signal_sigterm.md similarity index 100% rename from api-docs/d90ea68f5ebbd08371be2136607e16bd4ae0f894066d1c9bf3b02c30f98ae304.md rename to cluster/worker_kill_signal_sigterm.md diff --git a/api-docs/47299c81afc95900a33912cf608b8eac2cd2292a2ce128bff707eeff969bd881.md b/cluster/worker_process.md similarity index 100% rename from api-docs/47299c81afc95900a33912cf608b8eac2cd2292a2ce128bff707eeff969bd881.md rename to cluster/worker_process.md diff --git a/api-docs/acd39486a50ab0cfc22b61a440c5bfc9232e90f47da8146a19a50db055bb9e6c.md b/cluster/worker_send_message_sendhandle_callback.md similarity index 100% rename from api-docs/acd39486a50ab0cfc22b61a440c5bfc9232e90f47da8146a19a50db055bb9e6c.md rename to cluster/worker_send_message_sendhandle_callback.md diff --git a/api-docs/1068d96a36ca9250f126a01908fad2ea764062497a2de92671a02410a82e46cf.md b/console/class_console.md similarity index 100% rename from api-docs/1068d96a36ca9250f126a01908fad2ea764062497a2de92671a02410a82e46cf.md rename to console/class_console.md diff --git a/api-docs/88ab9d015ed8c4c3f442f65d1cbbb4de2952d1edd6534c03d3c1fdc7a9a107ae.md b/console/console.md similarity index 100% rename from api-docs/88ab9d015ed8c4c3f442f65d1cbbb4de2952d1edd6534c03d3c1fdc7a9a107ae.md rename to console/console.md diff --git a/api-docs/74b5865f3fb258fbf6244b8cba770eb6ff19cc93891ea93350d08f21fe2965df.md b/console/console_assert_value_message.md similarity index 100% rename from api-docs/74b5865f3fb258fbf6244b8cba770eb6ff19cc93891ea93350d08f21fe2965df.md rename to console/console_assert_value_message.md diff --git a/api-docs/1d30c7a1147c84c5dc7a136f06805b3f8518307343b56f76812eb62de83fcac4.md b/console/console_clear.md similarity index 100% rename from api-docs/1d30c7a1147c84c5dc7a136f06805b3f8518307343b56f76812eb62de83fcac4.md rename to console/console_clear.md diff --git a/api-docs/dbd200349ad354708b29f0a0ce384e7e2835d9521b666f2ec76daf5f05738a4e.md b/console/console_count_label.md similarity index 100% rename from api-docs/dbd200349ad354708b29f0a0ce384e7e2835d9521b666f2ec76daf5f05738a4e.md rename to console/console_count_label.md diff --git a/api-docs/78f3845474d4a91a884d5636d7ead04e787bc0e780659e203e7a8f65986d168b.md b/console/console_countreset_label.md similarity index 100% rename from api-docs/78f3845474d4a91a884d5636d7ead04e787bc0e780659e203e7a8f65986d168b.md rename to console/console_countreset_label.md diff --git a/api-docs/7feee2749c2862b2b5ba79d6fbfef22a164882276dbd0df2fe0464e5ca4b9a7e.md b/console/console_debug_data_args.md similarity index 100% rename from api-docs/7feee2749c2862b2b5ba79d6fbfef22a164882276dbd0df2fe0464e5ca4b9a7e.md rename to console/console_debug_data_args.md diff --git a/api-docs/3579fb048c76e146931892d0cb97d99e03b461a7a03f85ced02a593433887ce2.md b/console/console_dir_obj_options.md similarity index 100% rename from api-docs/3579fb048c76e146931892d0cb97d99e03b461a7a03f85ced02a593433887ce2.md rename to console/console_dir_obj_options.md diff --git a/api-docs/0f1747562832000b635c81e578ebbf55df72da39db10fa11123d2c4729c22db1.md b/console/console_dirxml_data.md similarity index 100% rename from api-docs/0f1747562832000b635c81e578ebbf55df72da39db10fa11123d2c4729c22db1.md rename to console/console_dirxml_data.md diff --git a/api-docs/64e0cab7d5f5bcf71f02f71d8329fbe750bf127b26e2ea67de411c69cf17cb55.md b/console/console_error_data_args.md similarity index 100% rename from api-docs/64e0cab7d5f5bcf71f02f71d8329fbe750bf127b26e2ea67de411c69cf17cb55.md rename to console/console_error_data_args.md diff --git a/api-docs/f965d6e01d0d42864007f7a21ad72602dda0c40aa7d4bf9eea73e4248254f369.md b/console/console_group_label.md similarity index 100% rename from api-docs/f965d6e01d0d42864007f7a21ad72602dda0c40aa7d4bf9eea73e4248254f369.md rename to console/console_group_label.md diff --git a/api-docs/d26dd3eea4d6640cd1bf1bb3b7dcc3f99d3166d46de3cf3ea9e4093a2ca3659d.md b/console/console_groupcollapsed.md similarity index 100% rename from api-docs/d26dd3eea4d6640cd1bf1bb3b7dcc3f99d3166d46de3cf3ea9e4093a2ca3659d.md rename to console/console_groupcollapsed.md diff --git a/api-docs/6ee2c1388e751c8345db921b03d1f43b81e29d89f9eff51a1ffa4a9844771850.md b/console/console_groupend.md similarity index 100% rename from api-docs/6ee2c1388e751c8345db921b03d1f43b81e29d89f9eff51a1ffa4a9844771850.md rename to console/console_groupend.md diff --git a/api-docs/26559151b1d83e779a382d597565673571be194b3b4317ba6fb96add06d75ba5.md b/console/console_info_data_args.md similarity index 100% rename from api-docs/26559151b1d83e779a382d597565673571be194b3b4317ba6fb96add06d75ba5.md rename to console/console_info_data_args.md diff --git a/api-docs/d463ed4d13709e36d6d21a5b2cf1ea7f90fdcc3452a1df9e8ccd044835c959a3.md b/console/console_log_data_args.md similarity index 100% rename from api-docs/d463ed4d13709e36d6d21a5b2cf1ea7f90fdcc3452a1df9e8ccd044835c959a3.md rename to console/console_log_data_args.md diff --git a/api-docs/3f5e57d17aa10fb4cc773afedb153e5d8846d5882d7e55a3bca21624101bbdbb.md b/console/console_marktimeline_label.md similarity index 100% rename from api-docs/3f5e57d17aa10fb4cc773afedb153e5d8846d5882d7e55a3bca21624101bbdbb.md rename to console/console_marktimeline_label.md diff --git a/api-docs/f712a89acadfdee5e695f45e369c87d6ea28b2711ae504310b9020469572f92b.md b/console/console_profile_label.md similarity index 100% rename from api-docs/f712a89acadfdee5e695f45e369c87d6ea28b2711ae504310b9020469572f92b.md rename to console/console_profile_label.md diff --git a/api-docs/b16e08bc2fc3a429b0a7eb7a2d14bb5ed6406e760165f3d0903d9017bcd91ba0.md b/console/console_profileend_label.md similarity index 100% rename from api-docs/b16e08bc2fc3a429b0a7eb7a2d14bb5ed6406e760165f3d0903d9017bcd91ba0.md rename to console/console_profileend_label.md diff --git a/api-docs/350542f1b6ee869ba45fbf48958700c5cf8ab63e4f44aecdc3775a47f889bc27.md b/console/console_table_tabulardata_properties.md similarity index 100% rename from api-docs/350542f1b6ee869ba45fbf48958700c5cf8ab63e4f44aecdc3775a47f889bc27.md rename to console/console_table_tabulardata_properties.md diff --git a/api-docs/2e575a3df14b629f0de7041dddc7081b8d68886be90a8dd5fd1b6f70af8e99df.md b/console/console_time_label.md similarity index 100% rename from api-docs/2e575a3df14b629f0de7041dddc7081b8d68886be90a8dd5fd1b6f70af8e99df.md rename to console/console_time_label.md diff --git a/api-docs/6eaf6e84b58853ff4ce55ea887a99b191b56c406396a7f6caf943f245060e0c0.md b/console/console_timeend_label.md similarity index 100% rename from api-docs/6eaf6e84b58853ff4ce55ea887a99b191b56c406396a7f6caf943f245060e0c0.md rename to console/console_timeend_label.md diff --git a/api-docs/a2a2bcf818e16d1c8cdca9831be9ca9a5b5349f9c38a30e2b7733de90b1be5ed.md b/console/console_timeline_label.md similarity index 100% rename from api-docs/a2a2bcf818e16d1c8cdca9831be9ca9a5b5349f9c38a30e2b7733de90b1be5ed.md rename to console/console_timeline_label.md diff --git a/api-docs/b0b55a1326124c685707a2f5cd32803ae3fc9f53326d2bc4a4c4e1cdd6c3311c.md b/console/console_timelineend_label.md similarity index 100% rename from api-docs/b0b55a1326124c685707a2f5cd32803ae3fc9f53326d2bc4a4c4e1cdd6c3311c.md rename to console/console_timelineend_label.md diff --git a/api-docs/4b4543f2323ae433268ec8a53c0dc68aa8e8cc51b70048f7d8f879daebc14d36.md b/console/console_timelog_label_data.md similarity index 100% rename from api-docs/4b4543f2323ae433268ec8a53c0dc68aa8e8cc51b70048f7d8f879daebc14d36.md rename to console/console_timelog_label_data.md diff --git a/api-docs/bd4d4eb9e4b298f857ae018569eecd2ab1ffcf9e02dc08dbcacddce13bf06d5b.md b/console/console_timestamp_label.md similarity index 100% rename from api-docs/bd4d4eb9e4b298f857ae018569eecd2ab1ffcf9e02dc08dbcacddce13bf06d5b.md rename to console/console_timestamp_label.md diff --git a/api-docs/5d25e2cf02dd30a638a86c6a580f0ca88380c30e5722b1c35c54b95d3fc86457.md b/console/console_trace_message_args.md similarity index 100% rename from api-docs/5d25e2cf02dd30a638a86c6a580f0ca88380c30e5722b1c35c54b95d3fc86457.md rename to console/console_trace_message_args.md diff --git a/api-docs/e0a9395631d4822328f6eba121a2d7a41eabb55292f1ec3b01fce0b272f3aef7.md b/console/console_warn_data_args.md similarity index 100% rename from api-docs/e0a9395631d4822328f6eba121a2d7a41eabb55292f1ec3b01fce0b272f3aef7.md rename to console/console_warn_data_args.md diff --git a/api-docs/f7c4ebdf59755497e482c928d4a559dfd1fcba3bfbbf9eafea271d58ef7a7e3e.md b/console/inspector_only_methods.md similarity index 100% rename from api-docs/f7c4ebdf59755497e482c928d4a559dfd1fcba3bfbbf9eafea271d58ef7a7e3e.md rename to console/inspector_only_methods.md diff --git a/api-docs/fb2776cf948db44644f0ca34960caeb94acf16b3ad2702c40937b444e0651bc7.md b/console/new_console_options.md similarity index 100% rename from api-docs/fb2776cf948db44644f0ca34960caeb94acf16b3ad2702c40937b444e0651bc7.md rename to console/new_console_options.md diff --git a/api-docs/dd525953e72ce4d102beca4556775a09117c2e98833c23630daa2ccae8a297cb.md b/console/new_console_stdout_stderr_ignoreerrors.md similarity index 100% rename from api-docs/dd525953e72ce4d102beca4556775a09117c2e98833c23630daa2ccae8a297cb.md rename to console/new_console_stdout_stderr_ignoreerrors.md diff --git a/api-docs/c71fecf2c4fc52bbe979cb30616d560f059dd6e96b7f6bc59c5cfa6f3ddbd500.md b/crypto/ccm_mode.md similarity index 100% rename from api-docs/c71fecf2c4fc52bbe979cb30616d560f059dd6e96b7f6bc59c5cfa6f3ddbd500.md rename to crypto/ccm_mode.md diff --git a/api-docs/eaa57e936960aa43149ab531c921d8d6355aef9447fd38fcc4773e7daa05f568.md b/crypto/certificate_exportchallenge_spkac.md similarity index 100% rename from api-docs/eaa57e936960aa43149ab531c921d8d6355aef9447fd38fcc4773e7daa05f568.md rename to crypto/certificate_exportchallenge_spkac.md diff --git a/api-docs/33388b75d78080a7af711e27b0c169c2bf9c25e24c68d5f96b460f22973cfbf0.md b/crypto/certificate_exportchallenge_spkac_1.md similarity index 100% rename from api-docs/33388b75d78080a7af711e27b0c169c2bf9c25e24c68d5f96b460f22973cfbf0.md rename to crypto/certificate_exportchallenge_spkac_1.md diff --git a/api-docs/24039684b945af0b4079eaa17835ebe2bee3228e8f6a063612e915a2e2359545.md b/crypto/certificate_exportpublickey_spkac.md similarity index 100% rename from api-docs/24039684b945af0b4079eaa17835ebe2bee3228e8f6a063612e915a2e2359545.md rename to crypto/certificate_exportpublickey_spkac.md diff --git a/api-docs/273b8d1d5961a59fcca9db520d0e8c9398a5fc1443ef562f1a38e3ad9bd38521.md b/crypto/certificate_exportpublickey_spkac_encoding.md similarity index 100% rename from api-docs/273b8d1d5961a59fcca9db520d0e8c9398a5fc1443ef562f1a38e3ad9bd38521.md rename to crypto/certificate_exportpublickey_spkac_encoding.md diff --git a/api-docs/51aee3aa1ba615a09d28ced90234e4d710798333da147f96992bdb8575577a15.md b/crypto/certificate_verifyspkac_spkac.md similarity index 100% rename from api-docs/51aee3aa1ba615a09d28ced90234e4d710798333da147f96992bdb8575577a15.md rename to crypto/certificate_verifyspkac_spkac.md diff --git a/api-docs/1378ca4bc00d5720eb266c7a088663e79c9fda2ad294ad3c001360484ff04e42.md b/crypto/certificate_verifyspkac_spkac_1.md similarity index 100% rename from api-docs/1378ca4bc00d5720eb266c7a088663e79c9fda2ad294ad3c001360484ff04e42.md rename to crypto/certificate_verifyspkac_spkac_1.md diff --git a/api-docs/a552053a817cb180ae168eb2c7744cc812fd6ff72dd11938efe8a158d8fc9537.md b/crypto/cipher_final_outputencoding.md similarity index 100% rename from api-docs/a552053a817cb180ae168eb2c7744cc812fd6ff72dd11938efe8a158d8fc9537.md rename to crypto/cipher_final_outputencoding.md diff --git a/api-docs/4e4e4717886a2a41a2118ae7fa2bf65a6b57dbbe8ab3249c87931a14fc78f3c6.md b/crypto/cipher_getauthtag.md similarity index 100% rename from api-docs/4e4e4717886a2a41a2118ae7fa2bf65a6b57dbbe8ab3249c87931a14fc78f3c6.md rename to crypto/cipher_getauthtag.md diff --git a/api-docs/2668335e3ce668968a48743aeba205766327daac382e3b6e2519efdf41175f04.md b/crypto/cipher_setaad_buffer_options.md similarity index 100% rename from api-docs/2668335e3ce668968a48743aeba205766327daac382e3b6e2519efdf41175f04.md rename to crypto/cipher_setaad_buffer_options.md diff --git a/api-docs/00f61bc768f2a783988b1f63961e58accf1192017ddae9b070657a827821513c.md b/crypto/cipher_setautopadding_autopadding.md similarity index 100% rename from api-docs/00f61bc768f2a783988b1f63961e58accf1192017ddae9b070657a827821513c.md rename to crypto/cipher_setautopadding_autopadding.md diff --git a/api-docs/98ba6d7bd599e112831d2a5b5a993f639690f17335be9b3996d963740e5bfa4d.md b/crypto/cipher_update_data_inputencoding_outputencoding.md similarity index 100% rename from api-docs/98ba6d7bd599e112831d2a5b5a993f639690f17335be9b3996d963740e5bfa4d.md rename to crypto/cipher_update_data_inputencoding_outputencoding.md diff --git a/api-docs/a10a9b72dce2848be9fe72150205bce8da25df60b4384851c19fc12f6157772c.md b/crypto/class_certificate.md similarity index 100% rename from api-docs/a10a9b72dce2848be9fe72150205bce8da25df60b4384851c19fc12f6157772c.md rename to crypto/class_certificate.md diff --git a/api-docs/289df838cdee6466f8e4b3dcacc77fbf6902c77d8d68d87db3a38a67a851be2f.md b/crypto/class_cipher.md similarity index 100% rename from api-docs/289df838cdee6466f8e4b3dcacc77fbf6902c77d8d68d87db3a38a67a851be2f.md rename to crypto/class_cipher.md diff --git a/api-docs/7de0be3a8b1b5ee79e4d1e1d9714708cc67e53c5315034a4787c708c12cf4577.md b/crypto/class_decipher.md similarity index 100% rename from api-docs/7de0be3a8b1b5ee79e4d1e1d9714708cc67e53c5315034a4787c708c12cf4577.md rename to crypto/class_decipher.md diff --git a/api-docs/f04527e3dfe361e51df497d72ba42d3a9f497340dcd735d465f1702e39935df5.md b/crypto/class_diffiehellman.md similarity index 100% rename from api-docs/f04527e3dfe361e51df497d72ba42d3a9f497340dcd735d465f1702e39935df5.md rename to crypto/class_diffiehellman.md diff --git a/api-docs/c37d0ce3f9889cc3821e5e1af0d8b8488117d801b913391d6855be1fb7b1bc07.md b/crypto/class_ecdh.md similarity index 100% rename from api-docs/c37d0ce3f9889cc3821e5e1af0d8b8488117d801b913391d6855be1fb7b1bc07.md rename to crypto/class_ecdh.md diff --git a/api-docs/a30b1a532c9c17368e1deb261c83d60389294b998c5c2514c7ef4b0cc945a0d5.md b/crypto/class_hash.md similarity index 100% rename from api-docs/a30b1a532c9c17368e1deb261c83d60389294b998c5c2514c7ef4b0cc945a0d5.md rename to crypto/class_hash.md diff --git a/api-docs/3eca4b7b759ceede57890bf08bf5bee24b044a97d0549ffce67834e0888d6363.md b/crypto/class_hmac.md similarity index 100% rename from api-docs/3eca4b7b759ceede57890bf08bf5bee24b044a97d0549ffce67834e0888d6363.md rename to crypto/class_hmac.md diff --git a/api-docs/baa09e3dbeaa8c240e60c51180b9e3a37e94b317fba9dae52858847491fda81d.md b/crypto/class_method_ecdh_convertkey_key_curve_inputencoding_outputencoding_format.md similarity index 100% rename from api-docs/baa09e3dbeaa8c240e60c51180b9e3a37e94b317fba9dae52858847491fda81d.md rename to crypto/class_method_ecdh_convertkey_key_curve_inputencoding_outputencoding_format.md diff --git a/api-docs/a7d0d56fa43f880c28add0afd636701f6dafc59b2ac0c21d223f656ce29243d3.md b/crypto/class_sign.md similarity index 100% rename from api-docs/a7d0d56fa43f880c28add0afd636701f6dafc59b2ac0c21d223f656ce29243d3.md rename to crypto/class_sign.md diff --git a/api-docs/54723482de3ea5b5b34dff2be3b82e027697a9696d04e164b424c449f6ce31f2.md b/crypto/class_verify.md similarity index 100% rename from api-docs/54723482de3ea5b5b34dff2be3b82e027697a9696d04e164b424c449f6ce31f2.md rename to crypto/class_verify.md diff --git a/api-docs/df0c859e5952d539b583d5b902f8c0716be42185098a008c6845609e3a7c3556.md b/crypto/crypto.md similarity index 100% rename from api-docs/df0c859e5952d539b583d5b902f8c0716be42185098a008c6845609e3a7c3556.md rename to crypto/crypto.md diff --git a/api-docs/b4dfd9bd6334d2d7492961b06e833473cff883949c340b1dad20079049f3d30d.md b/crypto/crypto_constants.md similarity index 100% rename from api-docs/b4dfd9bd6334d2d7492961b06e833473cff883949c340b1dad20079049f3d30d.md rename to crypto/crypto_constants.md diff --git a/api-docs/646cfcf2da65715376ecf41d811995536420a89f939496758588ab4592f4d2af.md b/crypto/crypto_constants_1.md similarity index 100% rename from api-docs/646cfcf2da65715376ecf41d811995536420a89f939496758588ab4592f4d2af.md rename to crypto/crypto_constants_1.md diff --git a/crypto/crypto_createcipher_algorithm_password_options.md b/crypto/crypto_createcipher_algorithm_password_options.md new file mode 100644 index 00000000..17c22b7d --- /dev/null +++ b/crypto/crypto_createcipher_algorithm_password_options.md @@ -0,0 +1,55 @@ + + +> Stability: 0 - Deprecated: Use [`crypto.createCipheriv()`][] instead. + +* `algorithm` {string} +* `password` {string | Buffer | TypedArray | DataView} +* `options` {Object} [`stream.transform` options][] +* Returns: {Cipher} + +Creates and returns a `Cipher` object that uses the given `algorithm` and +`password`. + +The `options` argument controls stream behavior and is optional except when a +cipher in CCM or OCB mode is used (e.g. `'aes-128-ccm'`). In that case, the +`authTagLength` option is required and specifies the length of the +authentication tag in bytes, see [CCM mode][]. In GCM mode, the `authTagLength` +option is not required but can be used to set the length of the authentication +tag that will be returned by `getAuthTag()` and defaults to 16 bytes. + +The `algorithm` is dependent on OpenSSL, examples are `'aes192'`, etc. On +recent OpenSSL releases, `openssl list -cipher-algorithms` +(`openssl list-cipher-algorithms` for older versions of OpenSSL) will +display the available cipher algorithms. + +The `password` is used to derive the cipher key and initialization vector (IV). +The value must be either a `'latin1'` encoded string, a [`Buffer`][], a +`TypedArray`, or a `DataView`. + +The implementation of `crypto.createCipher()` derives keys using the OpenSSL +function [`EVP_BytesToKey`][] with the digest algorithm set to MD5, one +iteration, and no salt. The lack of salt allows dictionary attacks as the same +password always creates the same key. The low iteration count and +non-cryptographically secure hash algorithm allow passwords to be tested very +rapidly. + +In line with OpenSSL's recommendation to use a more modern algorithm instead of +[`EVP_BytesToKey`][] it is recommended that developers derive a key and IV on +their own using [`crypto.scrypt()`][] and to use [`crypto.createCipheriv()`][] +to create the `Cipher` object. Users should not use ciphers with counter mode +(e.g. CTR, GCM, or CCM) in `crypto.createCipher()`. A warning is emitted when +they are used in order to avoid the risk of IV reuse that causes +vulnerabilities. For the case when IV is reused in GCM, see [Nonce-Disrespecting +Adversaries][] for details. + diff --git a/api-docs/761a970aa095a8eb0d80d78f210c77bf84a3edbabc1a9237bc862ddc8d62b8c2.md b/crypto/crypto_createcipheriv_algorithm_key_iv_options.md similarity index 100% rename from api-docs/761a970aa095a8eb0d80d78f210c77bf84a3edbabc1a9237bc862ddc8d62b8c2.md rename to crypto/crypto_createcipheriv_algorithm_key_iv_options.md diff --git a/crypto/crypto_createcredentials_details.md b/crypto/crypto_createcredentials_details.md new file mode 100644 index 00000000..8132c5b8 --- /dev/null +++ b/crypto/crypto_createcredentials_details.md @@ -0,0 +1,18 @@ + + +> Stability: 0 - Deprecated: Use [`tls.createSecureContext()`][] instead. + +- `details` {Object} Identical to [`tls.createSecureContext()`][]. +- Returns: {tls.SecureContext} + +The `crypto.createCredentials()` method is a deprecated function for creating +and returning a `tls.SecureContext`. It should not be used. Replace it with +[`tls.createSecureContext()`][] which has the exact same arguments and return +value. + +Returns a `tls.SecureContext`, as-if [`tls.createSecureContext()`][] had been +called. + diff --git a/crypto/crypto_createdecipher_algorithm_password_options.md b/crypto/crypto_createdecipher_algorithm_password_options.md new file mode 100644 index 00000000..7bf79379 --- /dev/null +++ b/crypto/crypto_createdecipher_algorithm_password_options.md @@ -0,0 +1,36 @@ + + +> Stability: 0 - Deprecated: Use [`crypto.createDecipheriv()`][] instead. + +* `algorithm` {string} +* `password` {string | Buffer | TypedArray | DataView} +* `options` {Object} [`stream.transform` options][] +* Returns: {Decipher} + +Creates and returns a `Decipher` object that uses the given `algorithm` and +`password` (key). + +The `options` argument controls stream behavior and is optional except when a +cipher in CCM or OCB mode is used (e.g. `'aes-128-ccm'`). In that case, the +`authTagLength` option is required and specifies the length of the +authentication tag in bytes, see [CCM mode][]. + +The implementation of `crypto.createDecipher()` derives keys using the OpenSSL +function [`EVP_BytesToKey`][] with the digest algorithm set to MD5, one +iteration, and no salt. The lack of salt allows dictionary attacks as the same +password always creates the same key. The low iteration count and +non-cryptographically secure hash algorithm allow passwords to be tested very +rapidly. + +In line with OpenSSL's recommendation to use a more modern algorithm instead of +[`EVP_BytesToKey`][] it is recommended that developers derive a key and IV on +their own using [`crypto.scrypt()`][] and to use [`crypto.createDecipheriv()`][] +to create the `Decipher` object. + diff --git a/api-docs/030afeb3ecb92aec4ac548d4bc1d3e2a4f37a8b489ff92f66e0227befbea65bf.md b/crypto/crypto_createdecipheriv_algorithm_key_iv_options.md similarity index 100% rename from api-docs/030afeb3ecb92aec4ac548d4bc1d3e2a4f37a8b489ff92f66e0227befbea65bf.md rename to crypto/crypto_createdecipheriv_algorithm_key_iv_options.md diff --git a/api-docs/eb8f991f25d51c8da71b7dba0751f571cde6eb5643454ebddc9a8d189c97e49c.md b/crypto/crypto_creatediffiehellman_prime_primeencoding_generator_generatorencoding.md similarity index 100% rename from api-docs/eb8f991f25d51c8da71b7dba0751f571cde6eb5643454ebddc9a8d189c97e49c.md rename to crypto/crypto_creatediffiehellman_prime_primeencoding_generator_generatorencoding.md diff --git a/api-docs/451bf236cea488f3c5625faffa959abddd627ac2e25684314dbfa0a8f1a22f94.md b/crypto/crypto_creatediffiehellman_primelength_generator.md similarity index 100% rename from api-docs/451bf236cea488f3c5625faffa959abddd627ac2e25684314dbfa0a8f1a22f94.md rename to crypto/crypto_creatediffiehellman_primelength_generator.md diff --git a/api-docs/7f3f4c55033ce8cd6d2ba4bcfc15fe2288b26717049c0cdc04e39b52bab4ba42.md b/crypto/crypto_createecdh_curvename.md similarity index 100% rename from api-docs/7f3f4c55033ce8cd6d2ba4bcfc15fe2288b26717049c0cdc04e39b52bab4ba42.md rename to crypto/crypto_createecdh_curvename.md diff --git a/api-docs/7ea7ee8694951f17172840a79e4b2b80d08198be33aaa4a714cc12323a693073.md b/crypto/crypto_createhash_algorithm_options.md similarity index 100% rename from api-docs/7ea7ee8694951f17172840a79e4b2b80d08198be33aaa4a714cc12323a693073.md rename to crypto/crypto_createhash_algorithm_options.md diff --git a/api-docs/be3d7a7bfee95039e088e3a8ce42d94577de353ad0b85472f1e281f326b0dfd1.md b/crypto/crypto_createhmac_algorithm_key_options.md similarity index 100% rename from api-docs/be3d7a7bfee95039e088e3a8ce42d94577de353ad0b85472f1e281f326b0dfd1.md rename to crypto/crypto_createhmac_algorithm_key_options.md diff --git a/api-docs/0839232616e59c383d70172d317cc62593544e04432c86411051ce794aed7aca.md b/crypto/crypto_createsign_algorithm_options.md similarity index 100% rename from api-docs/0839232616e59c383d70172d317cc62593544e04432c86411051ce794aed7aca.md rename to crypto/crypto_createsign_algorithm_options.md diff --git a/api-docs/3557f35816a967fee980a7a2a49787ce1fca82e59d102ef4d278e6cd4496eaba.md b/crypto/crypto_createverify_algorithm_options.md similarity index 100% rename from api-docs/3557f35816a967fee980a7a2a49787ce1fca82e59d102ef4d278e6cd4496eaba.md rename to crypto/crypto_createverify_algorithm_options.md diff --git a/crypto/crypto_default_encoding.md b/crypto/crypto_default_encoding.md new file mode 100644 index 00000000..abad7d79 --- /dev/null +++ b/crypto/crypto_default_encoding.md @@ -0,0 +1,18 @@ + + +> Stability: 0 - Deprecated + +The default encoding to use for functions that can take either strings +or [buffers][`Buffer`]. The default value is `'buffer'`, which makes methods +default to [`Buffer`][] objects. + +The `crypto.DEFAULT_ENCODING` mechanism is provided for backwards compatibility +with legacy programs that expect `'latin1'` to be the default encoding. + +New applications should expect the default to be `'buffer'`. + +This property is deprecated. + diff --git a/crypto/crypto_fips.md b/crypto/crypto_fips.md new file mode 100644 index 00000000..adc0ed49 --- /dev/null +++ b/crypto/crypto_fips.md @@ -0,0 +1,13 @@ + + +> Stability: 0 - Deprecated + +Property for checking and controlling whether a FIPS compliant crypto provider +is currently in use. Setting to true requires a FIPS build of Node.js. + +This property is deprecated. Please use `crypto.setFips()` and +`crypto.getFips()` instead. + diff --git a/api-docs/50ee14e198b0d8c9c227349335e96ae3e84a938133311d2fd6a84b43624105e6.md b/crypto/crypto_generatekeypair_type_options_callback.md similarity index 100% rename from api-docs/50ee14e198b0d8c9c227349335e96ae3e84a938133311d2fd6a84b43624105e6.md rename to crypto/crypto_generatekeypair_type_options_callback.md diff --git a/api-docs/02c6378c68816d25a3863326dc3dd6c421b83890861de0673ccfbe7255526273.md b/crypto/crypto_generatekeypairsync_type_options.md similarity index 100% rename from api-docs/02c6378c68816d25a3863326dc3dd6c421b83890861de0673ccfbe7255526273.md rename to crypto/crypto_generatekeypairsync_type_options.md diff --git a/api-docs/03616d141236323c7eea61bf4d7c558f8c7c77c8e6bd64e0fcf733fa08c05b3f.md b/crypto/crypto_getciphers.md similarity index 100% rename from api-docs/03616d141236323c7eea61bf4d7c558f8c7c77c8e6bd64e0fcf733fa08c05b3f.md rename to crypto/crypto_getciphers.md diff --git a/api-docs/acdca8fb7c5b36d6e364ab09f1f92cd31e0d47824688a823a9930a14ba808501.md b/crypto/crypto_getcurves.md similarity index 100% rename from api-docs/acdca8fb7c5b36d6e364ab09f1f92cd31e0d47824688a823a9930a14ba808501.md rename to crypto/crypto_getcurves.md diff --git a/api-docs/b3e34b38864281141ae359030d4a2b200ed7eeff27bd7250ded739a490779cc3.md b/crypto/crypto_getdiffiehellman_groupname.md similarity index 100% rename from api-docs/b3e34b38864281141ae359030d4a2b200ed7eeff27bd7250ded739a490779cc3.md rename to crypto/crypto_getdiffiehellman_groupname.md diff --git a/api-docs/6dbc16f25f85af078deade06af210f4e322f29f4a4e0ff75d2e735b1c935a089.md b/crypto/crypto_getfips.md similarity index 100% rename from api-docs/6dbc16f25f85af078deade06af210f4e322f29f4a4e0ff75d2e735b1c935a089.md rename to crypto/crypto_getfips.md diff --git a/api-docs/22a128a9e657480f10a12cd5281e99aa87379d3c73ff640e389fbf518fe007b8.md b/crypto/crypto_gethashes.md similarity index 100% rename from api-docs/22a128a9e657480f10a12cd5281e99aa87379d3c73ff640e389fbf518fe007b8.md rename to crypto/crypto_gethashes.md diff --git a/api-docs/25b86bbf5ea703ddfaf782410617fb4eff33ab1556a356967aa1ca3bb7b4e6d7.md b/crypto/crypto_module_methods_and_properties.md similarity index 100% rename from api-docs/25b86bbf5ea703ddfaf782410617fb4eff33ab1556a356967aa1ca3bb7b4e6d7.md rename to crypto/crypto_module_methods_and_properties.md diff --git a/api-docs/2d8a3f31e6a5a7ee6e9a5cab8492c619b0366c496110fdf4fd941da534f47990.md b/crypto/crypto_pbkdf2_password_salt_iterations_keylen_digest_callback.md similarity index 100% rename from api-docs/2d8a3f31e6a5a7ee6e9a5cab8492c619b0366c496110fdf4fd941da534f47990.md rename to crypto/crypto_pbkdf2_password_salt_iterations_keylen_digest_callback.md diff --git a/api-docs/578053e7432e91d764278104191a357001e6a2324514f43183f7404db63a4982.md b/crypto/crypto_pbkdf2sync_password_salt_iterations_keylen_digest.md similarity index 100% rename from api-docs/578053e7432e91d764278104191a357001e6a2324514f43183f7404db63a4982.md rename to crypto/crypto_pbkdf2sync_password_salt_iterations_keylen_digest.md diff --git a/api-docs/4f624b08a0b7f29afa1ec95b520de6aae7acfd5bc477f2fa9173093a0551907a.md b/crypto/crypto_privatedecrypt_privatekey_buffer.md similarity index 100% rename from api-docs/4f624b08a0b7f29afa1ec95b520de6aae7acfd5bc477f2fa9173093a0551907a.md rename to crypto/crypto_privatedecrypt_privatekey_buffer.md diff --git a/api-docs/aaf50dfb683fc576904c7ba3756582b02376e4cd8b4d2b7c72e87432d9d5eabf.md b/crypto/crypto_privateencrypt_privatekey_buffer.md similarity index 100% rename from api-docs/aaf50dfb683fc576904c7ba3756582b02376e4cd8b4d2b7c72e87432d9d5eabf.md rename to crypto/crypto_privateencrypt_privatekey_buffer.md diff --git a/api-docs/3b8c1318b2e8c640de843ccac84c6d460cd687ad63ac25d8ddcf75850da70cd4.md b/crypto/crypto_publicdecrypt_key_buffer.md similarity index 100% rename from api-docs/3b8c1318b2e8c640de843ccac84c6d460cd687ad63ac25d8ddcf75850da70cd4.md rename to crypto/crypto_publicdecrypt_key_buffer.md diff --git a/api-docs/a63ca150604d0692a1d7c1a7b1ea75c167d52149476b07aadf5f76fda9de57c9.md b/crypto/crypto_publicencrypt_key_buffer.md similarity index 100% rename from api-docs/a63ca150604d0692a1d7c1a7b1ea75c167d52149476b07aadf5f76fda9de57c9.md rename to crypto/crypto_publicencrypt_key_buffer.md diff --git a/api-docs/f78667ec8e26a72ddff0041e31dd052a0cdc25fbb0caa5287e11e32c20b61137.md b/crypto/crypto_randombytes_size_callback.md similarity index 100% rename from api-docs/f78667ec8e26a72ddff0041e31dd052a0cdc25fbb0caa5287e11e32c20b61137.md rename to crypto/crypto_randombytes_size_callback.md diff --git a/api-docs/e665715e6dd71ef2f7b6661700cec2b4814fb9ef770805abc4ec720421d05412.md b/crypto/crypto_randomfill_buffer_offset_size_callback.md similarity index 100% rename from api-docs/e665715e6dd71ef2f7b6661700cec2b4814fb9ef770805abc4ec720421d05412.md rename to crypto/crypto_randomfill_buffer_offset_size_callback.md diff --git a/api-docs/4056e75ceea3924192f788e92274c37fcdaa2aca7dff6e8b0ad05de7b3513b4a.md b/crypto/crypto_randomfillsync_buffer_offset_size.md similarity index 100% rename from api-docs/4056e75ceea3924192f788e92274c37fcdaa2aca7dff6e8b0ad05de7b3513b4a.md rename to crypto/crypto_randomfillsync_buffer_offset_size.md diff --git a/api-docs/eb9d89a8d0665ae20caafd5c50d4591acb9f07b857dba234006fdb545637111d.md b/crypto/crypto_scrypt_password_salt_keylen_options_callback.md similarity index 100% rename from api-docs/eb9d89a8d0665ae20caafd5c50d4591acb9f07b857dba234006fdb545637111d.md rename to crypto/crypto_scrypt_password_salt_keylen_options_callback.md diff --git a/api-docs/07cc2eb690287f48e7186bc04f6e67608a6a758642242b2cba8d7941792f4656.md b/crypto/crypto_scryptsync_password_salt_keylen_options.md similarity index 100% rename from api-docs/07cc2eb690287f48e7186bc04f6e67608a6a758642242b2cba8d7941792f4656.md rename to crypto/crypto_scryptsync_password_salt_keylen_options.md diff --git a/api-docs/db5737e404325e000dd370bb478d2d9938b52d128947a2e5d4426c320e89a19f.md b/crypto/crypto_setengine_engine_flags.md similarity index 100% rename from api-docs/db5737e404325e000dd370bb478d2d9938b52d128947a2e5d4426c320e89a19f.md rename to crypto/crypto_setengine_engine_flags.md diff --git a/api-docs/95573bcb938fe45ff29bb0ca7a1606ae4f27860f6487f48f4330995caea0a1e4.md b/crypto/crypto_setfips_bool.md similarity index 100% rename from api-docs/95573bcb938fe45ff29bb0ca7a1606ae4f27860f6487f48f4330995caea0a1e4.md rename to crypto/crypto_setfips_bool.md diff --git a/api-docs/20ce7461d67ff513c8da35207940d0e6e07ce3f00f6a9260d4360896b69c4c8f.md b/crypto/crypto_timingsafeequal_a_b.md similarity index 100% rename from api-docs/20ce7461d67ff513c8da35207940d0e6e07ce3f00f6a9260d4360896b69c4c8f.md rename to crypto/crypto_timingsafeequal_a_b.md diff --git a/api-docs/8bdf08af9e17c143b45bf57580d12b1d12dfc02c781a676baa84fa0d8061f8fb.md b/crypto/decipher_final_outputencoding.md similarity index 100% rename from api-docs/8bdf08af9e17c143b45bf57580d12b1d12dfc02c781a676baa84fa0d8061f8fb.md rename to crypto/decipher_final_outputencoding.md diff --git a/api-docs/b33a3fdbc875d5d9b06d626897f186ec4a307dbf35d71e406b1ecfb503df2fa0.md b/crypto/decipher_setaad_buffer_options.md similarity index 100% rename from api-docs/b33a3fdbc875d5d9b06d626897f186ec4a307dbf35d71e406b1ecfb503df2fa0.md rename to crypto/decipher_setaad_buffer_options.md diff --git a/api-docs/e32049dc359bed8c9379833621a16f937b0c23ac8c9ef58bb0505611a3f64d2a.md b/crypto/decipher_setauthtag_buffer.md similarity index 100% rename from api-docs/e32049dc359bed8c9379833621a16f937b0c23ac8c9ef58bb0505611a3f64d2a.md rename to crypto/decipher_setauthtag_buffer.md diff --git a/api-docs/71fd1d08adf432eb36b33098f55bcda5e58ccf850e44a923dd32d54d79e3ad15.md b/crypto/decipher_setautopadding_autopadding.md similarity index 100% rename from api-docs/71fd1d08adf432eb36b33098f55bcda5e58ccf850e44a923dd32d54d79e3ad15.md rename to crypto/decipher_setautopadding_autopadding.md diff --git a/api-docs/7dd9149138c605210bbb64e48c662e982ee2090dd0ad8ad713c17bc54a249f90.md b/crypto/decipher_update_data_inputencoding_outputencoding.md similarity index 100% rename from api-docs/7dd9149138c605210bbb64e48c662e982ee2090dd0ad8ad713c17bc54a249f90.md rename to crypto/decipher_update_data_inputencoding_outputencoding.md diff --git a/api-docs/819d5b9d6b1ed92a1e4e68a802c793110daf7ab00b2f64d69f283809b28cfa21.md b/crypto/determining_if_crypto_support_is_unavailable.md similarity index 100% rename from api-docs/819d5b9d6b1ed92a1e4e68a802c793110daf7ab00b2f64d69f283809b28cfa21.md rename to crypto/determining_if_crypto_support_is_unavailable.md diff --git a/api-docs/bc47e9606fe195a0c48445e417701462e77f88614434b128d4d4b8ee06dfea47.md b/crypto/diffiehellman_computesecret_otherpublickey_inputencoding_outputencoding.md similarity index 100% rename from api-docs/bc47e9606fe195a0c48445e417701462e77f88614434b128d4d4b8ee06dfea47.md rename to crypto/diffiehellman_computesecret_otherpublickey_inputencoding_outputencoding.md diff --git a/api-docs/c001076f69bd6accf724e9ecb87376fdd0fbb37a94bb8474835606298369993a.md b/crypto/diffiehellman_generatekeys_encoding.md similarity index 100% rename from api-docs/c001076f69bd6accf724e9ecb87376fdd0fbb37a94bb8474835606298369993a.md rename to crypto/diffiehellman_generatekeys_encoding.md diff --git a/api-docs/e3f57ce1132470c17043c994f72d108070ac4a7951d83375f55915f100026c0b.md b/crypto/diffiehellman_getgenerator_encoding.md similarity index 100% rename from api-docs/e3f57ce1132470c17043c994f72d108070ac4a7951d83375f55915f100026c0b.md rename to crypto/diffiehellman_getgenerator_encoding.md diff --git a/api-docs/6e67f0b2082b25eacbf094977cab28e1d6b6c10ae9c7a7b6c5d046db7aa2c70b.md b/crypto/diffiehellman_getprime_encoding.md similarity index 100% rename from api-docs/6e67f0b2082b25eacbf094977cab28e1d6b6c10ae9c7a7b6c5d046db7aa2c70b.md rename to crypto/diffiehellman_getprime_encoding.md diff --git a/api-docs/4e25475f51d0cd72bf5fe1a39fa1c4e559b88d4e575d7539132ffc845a6733c7.md b/crypto/diffiehellman_getprivatekey_encoding.md similarity index 100% rename from api-docs/4e25475f51d0cd72bf5fe1a39fa1c4e559b88d4e575d7539132ffc845a6733c7.md rename to crypto/diffiehellman_getprivatekey_encoding.md diff --git a/api-docs/d7f21eaeec39d23f0499c83ddd58601c09a74d8ab8e3f4c627fda1b24b3fa9de.md b/crypto/diffiehellman_getpublickey_encoding.md similarity index 100% rename from api-docs/d7f21eaeec39d23f0499c83ddd58601c09a74d8ab8e3f4c627fda1b24b3fa9de.md rename to crypto/diffiehellman_getpublickey_encoding.md diff --git a/api-docs/853fd618db22e93a5d40063a0bb25c4bea3ed03fe1dfe2b6cc35455bc1b944a5.md b/crypto/diffiehellman_setprivatekey_privatekey_encoding.md similarity index 100% rename from api-docs/853fd618db22e93a5d40063a0bb25c4bea3ed03fe1dfe2b6cc35455bc1b944a5.md rename to crypto/diffiehellman_setprivatekey_privatekey_encoding.md diff --git a/api-docs/01c8b0fa9b9089f818974a742938f3bee0e4d2d9cad15286ac14f13767f34488.md b/crypto/diffiehellman_setpublickey_publickey_encoding.md similarity index 100% rename from api-docs/01c8b0fa9b9089f818974a742938f3bee0e4d2d9cad15286ac14f13767f34488.md rename to crypto/diffiehellman_setpublickey_publickey_encoding.md diff --git a/api-docs/80ced1cceb29b3a7f0a7e7d946219ac047909bc0bc242908e0306fa9ff7cadd4.md b/crypto/diffiehellman_verifyerror.md similarity index 100% rename from api-docs/80ced1cceb29b3a7f0a7e7d946219ac047909bc0bc242908e0306fa9ff7cadd4.md rename to crypto/diffiehellman_verifyerror.md diff --git a/api-docs/c395816695206a98af3c00a2abd72e453adeca1bc14582cce5891504ed32fc2d.md b/crypto/ecdh_computesecret_otherpublickey_inputencoding_outputencoding.md similarity index 100% rename from api-docs/c395816695206a98af3c00a2abd72e453adeca1bc14582cce5891504ed32fc2d.md rename to crypto/ecdh_computesecret_otherpublickey_inputencoding_outputencoding.md diff --git a/api-docs/ca017163e6d73f31e5678609b433ab6af3b94bdffb36256ce12deab68d80a13b.md b/crypto/ecdh_generatekeys_encoding_format.md similarity index 100% rename from api-docs/ca017163e6d73f31e5678609b433ab6af3b94bdffb36256ce12deab68d80a13b.md rename to crypto/ecdh_generatekeys_encoding_format.md diff --git a/api-docs/6ace6a420a16ab35f49ba0012f7101aa9d9895faef6c182272da11e80d3599dc.md b/crypto/ecdh_getprivatekey_encoding.md similarity index 100% rename from api-docs/6ace6a420a16ab35f49ba0012f7101aa9d9895faef6c182272da11e80d3599dc.md rename to crypto/ecdh_getprivatekey_encoding.md diff --git a/api-docs/b737f96d1e000d7be27a0cdd9e4e452814aea82aa2b5dc4ad73c33fc25306d77.md b/crypto/ecdh_getpublickey_encoding_format.md similarity index 100% rename from api-docs/b737f96d1e000d7be27a0cdd9e4e452814aea82aa2b5dc4ad73c33fc25306d77.md rename to crypto/ecdh_getpublickey_encoding_format.md diff --git a/api-docs/47c5f85821c9d37379b1ce8d998b8b741e4d9d33c40f8cb7b20461e70b9574f5.md b/crypto/ecdh_setprivatekey_privatekey_encoding.md similarity index 100% rename from api-docs/47c5f85821c9d37379b1ce8d998b8b741e4d9d33c40f8cb7b20461e70b9574f5.md rename to crypto/ecdh_setprivatekey_privatekey_encoding.md diff --git a/crypto/ecdh_setpublickey_publickey_encoding.md b/crypto/ecdh_setpublickey_publickey_encoding.md new file mode 100644 index 00000000..ccd2f92d --- /dev/null +++ b/crypto/ecdh_setpublickey_publickey_encoding.md @@ -0,0 +1,46 @@ + + +> Stability: 0 - Deprecated + +* `publicKey` {string | Buffer | TypedArray | DataView} +* `encoding` {string} The [encoding][] of the `publicKey` string. + +Sets the EC Diffie-Hellman public key. +If `encoding` is provided `publicKey` is expected to +be a string; otherwise a [`Buffer`][], `TypedArray`, or `DataView` is expected. + +Note that there is not normally a reason to call this method because `ECDH` +only requires a private key and the other party's public key to compute the +shared secret. Typically either [`ecdh.generateKeys()`][] or +[`ecdh.setPrivateKey()`][] will be called. The [`ecdh.setPrivateKey()`][] method +attempts to generate the public point/key associated with the private key being +set. + +Example (obtaining a shared secret): + +```js +const crypto = require('crypto'); +const alice = crypto.createECDH('secp256k1'); +const bob = crypto.createECDH('secp256k1'); + +// This is a shortcut way of specifying one of Alice's previous private +// keys. It would be unwise to use such a predictable private key in a real +// application. +alice.setPrivateKey( + crypto.createHash('sha256').update('alice', 'utf8').digest() +); + +// Bob uses a newly generated cryptographically strong +// pseudorandom key pair +bob.generateKeys(); + +const aliceSecret = alice.computeSecret(bob.getPublicKey(), null, 'hex'); +const bobSecret = bob.computeSecret(alice.getPublicKey(), null, 'hex'); + +// aliceSecret and bobSecret should be the same shared secret value +console.log(aliceSecret === bobSecret); +``` + diff --git a/api-docs/533f61dc37d20f7c5f69c1932b88b03cd40a5c7f1560a4ddc1bf6b34d4f44e41.md b/crypto/hash_digest_encoding.md similarity index 100% rename from api-docs/533f61dc37d20f7c5f69c1932b88b03cd40a5c7f1560a4ddc1bf6b34d4f44e41.md rename to crypto/hash_digest_encoding.md diff --git a/api-docs/570388e70b4d6c479f217605cea969225a502f106686b4b583bb5339d20a7402.md b/crypto/hash_update_data_inputencoding.md similarity index 100% rename from api-docs/570388e70b4d6c479f217605cea969225a502f106686b4b583bb5339d20a7402.md rename to crypto/hash_update_data_inputencoding.md diff --git a/api-docs/e26f4c11953d609e7ac1d1c6a143df7017282e10cb81c18d49ea78521d22042a.md b/crypto/hmac_digest_encoding.md similarity index 100% rename from api-docs/e26f4c11953d609e7ac1d1c6a143df7017282e10cb81c18d49ea78521d22042a.md rename to crypto/hmac_digest_encoding.md diff --git a/api-docs/7d4b7ae4f9194884382f9b8870bf726659c1ca0f5ebaac01dd2f98c75962b2ec.md b/crypto/hmac_update_data_inputencoding.md similarity index 100% rename from api-docs/7d4b7ae4f9194884382f9b8870bf726659c1ca0f5ebaac01dd2f98c75962b2ec.md rename to crypto/hmac_update_data_inputencoding.md diff --git a/api-docs/e10448a8bee16bc6141f5fa3ad0d5307e533a33cfe0f4dddd2ff03ced3cb9156.md b/crypto/legacy_api.md similarity index 100% rename from api-docs/e10448a8bee16bc6141f5fa3ad0d5307e533a33cfe0f4dddd2ff03ced3cb9156.md rename to crypto/legacy_api.md diff --git a/api-docs/f8d8d2f6eec768ff622fa37fb247c089c0669a87cf680b4a013965287b8cf62a.md b/crypto/legacy_streams_api_pre_node_js_v0_10.md similarity index 100% rename from api-docs/f8d8d2f6eec768ff622fa37fb247c089c0669a87cf680b4a013965287b8cf62a.md rename to crypto/legacy_streams_api_pre_node_js_v0_10.md diff --git a/api-docs/db3bf3b4525e44e7aa6f2bc049c21cba387f84ceb92f55ea8ce1abce42d15c4e.md b/crypto/new_crypto_certificate.md similarity index 100% rename from api-docs/db3bf3b4525e44e7aa6f2bc049c21cba387f84ceb92f55ea8ce1abce42d15c4e.md rename to crypto/new_crypto_certificate.md diff --git a/api-docs/bf516cadaa2041db3211195d3d153695bd3b4296bc9e0519008e3ade1d8ae855.md b/crypto/node_js_crypto_constants.md similarity index 100% rename from api-docs/bf516cadaa2041db3211195d3d153695bd3b4296bc9e0519008e3ade1d8ae855.md rename to crypto/node_js_crypto_constants.md diff --git a/api-docs/500c84d78d145406af3321a11ba2fa28a9863cb56979b54aee11e3cc9298061a.md b/crypto/notes.md similarity index 100% rename from api-docs/500c84d78d145406af3321a11ba2fa28a9863cb56979b54aee11e3cc9298061a.md rename to crypto/notes.md diff --git a/api-docs/a9e30f61d81cc81e6f4ae9370902c34f3b65c3448b940387a89f9024c45df410.md b/crypto/openssl_engine_constants.md similarity index 100% rename from api-docs/a9e30f61d81cc81e6f4ae9370902c34f3b65c3448b940387a89f9024c45df410.md rename to crypto/openssl_engine_constants.md diff --git a/api-docs/b74e2902f92c96074b117a90d497a179357ccba3096f799f9e28508f887dc5e9.md b/crypto/openssl_options.md similarity index 100% rename from api-docs/b74e2902f92c96074b117a90d497a179357ccba3096f799f9e28508f887dc5e9.md rename to crypto/openssl_options.md diff --git a/api-docs/37a1582ece0ef0a33d6d2bf9609224a5920883776984c509310ed02f91110e6a.md b/crypto/other_openssl_constants.md similarity index 100% rename from api-docs/37a1582ece0ef0a33d6d2bf9609224a5920883776984c509310ed02f91110e6a.md rename to crypto/other_openssl_constants.md diff --git a/api-docs/9217fc86824bb067b13b1814786af1a5845f38de1b8e04b9423a419ce88c5640.md b/crypto/recent_ecdh_changes.md similarity index 100% rename from api-docs/9217fc86824bb067b13b1814786af1a5845f38de1b8e04b9423a419ce88c5640.md rename to crypto/recent_ecdh_changes.md diff --git a/api-docs/816beae88e3deb2631fb32d99c37648aef42bdfa34a7438a8d21388154042407.md b/crypto/sign_sign_privatekey_outputencoding.md similarity index 100% rename from api-docs/816beae88e3deb2631fb32d99c37648aef42bdfa34a7438a8d21388154042407.md rename to crypto/sign_sign_privatekey_outputencoding.md diff --git a/api-docs/7e6347b4a66d976b12c0d0162735ca9345b563caafe03fe4290f2863f867a3bd.md b/crypto/sign_update_data_inputencoding.md similarity index 100% rename from api-docs/7e6347b4a66d976b12c0d0162735ca9345b563caafe03fe4290f2863f867a3bd.md rename to crypto/sign_update_data_inputencoding.md diff --git a/api-docs/7c462d5ee4c930511be05235eb2b9ddad47c4155c7d35ae2e333d2a6db44e851.md b/crypto/support_for_weak_or_compromised_algorithms.md similarity index 100% rename from api-docs/7c462d5ee4c930511be05235eb2b9ddad47c4155c7d35ae2e333d2a6db44e851.md rename to crypto/support_for_weak_or_compromised_algorithms.md diff --git a/api-docs/fdf6e88779925afe9f168f52e51c29e80e7f3cda2ade8aa0a09a2c2a5626adb5.md b/crypto/verify_update_data_inputencoding.md similarity index 100% rename from api-docs/fdf6e88779925afe9f168f52e51c29e80e7f3cda2ade8aa0a09a2c2a5626adb5.md rename to crypto/verify_update_data_inputencoding.md diff --git a/api-docs/e1cd354c06302255222fdbd67a58057fe713232cd4b46be1a70aee7869ad121d.md b/crypto/verify_verify_object_signature_signatureencoding.md similarity index 100% rename from api-docs/e1cd354c06302255222fdbd67a58057fe713232cd4b46be1a70aee7869ad121d.md rename to crypto/verify_verify_object_signature_signatureencoding.md diff --git a/api-docs/5285cdf1df50a0ac250bc30551e683083b6076ae50fbb94cebf31e5c590a1e0e.md b/debugger/advanced_usage.md similarity index 100% rename from api-docs/5285cdf1df50a0ac250bc30551e683083b6076ae50fbb94cebf31e5c590a1e0e.md rename to debugger/advanced_usage.md diff --git a/api-docs/0288b151bc6320cc9a59a54b591e39db105d00441736348642fb5a8be0e08e95.md b/debugger/breakpoints.md similarity index 100% rename from api-docs/0288b151bc6320cc9a59a54b591e39db105d00441736348642fb5a8be0e08e95.md rename to debugger/breakpoints.md diff --git a/api-docs/794f0b0950776b9206d1a24205e02e1bc772a1df3cb4522cf05ab1763a4fbe55.md b/debugger/command_reference.md similarity index 100% rename from api-docs/794f0b0950776b9206d1a24205e02e1bc772a1df3cb4522cf05ab1763a4fbe55.md rename to debugger/command_reference.md diff --git a/api-docs/a378f8613c81a8ec9c21b34ad383c6bf91d1215f1938073a76a779988af63b19.md b/debugger/debugger.md similarity index 100% rename from api-docs/a378f8613c81a8ec9c21b34ad383c6bf91d1215f1938073a76a779988af63b19.md rename to debugger/debugger.md diff --git a/api-docs/accd828e0b8c2828a65ed62a1d3bfc06eca61db4f26c3762eacfd702e5874a66.md b/debugger/execution_control.md similarity index 100% rename from api-docs/accd828e0b8c2828a65ed62a1d3bfc06eca61db4f26c3762eacfd702e5874a66.md rename to debugger/execution_control.md diff --git a/api-docs/cdc1234115b3daea752866c3e8b8e025e113d0a395d929bf0561be78cca14c34.md b/debugger/information.md similarity index 100% rename from api-docs/cdc1234115b3daea752866c3e8b8e025e113d0a395d929bf0561be78cca14c34.md rename to debugger/information.md diff --git a/api-docs/71aa61df17bbb449b320ca9458688fef8f7250c352b84541ce0ada0d8ab8efde.md b/debugger/stepping.md similarity index 100% rename from api-docs/71aa61df17bbb449b320ca9458688fef8f7250c352b84541ce0ada0d8ab8efde.md rename to debugger/stepping.md diff --git a/api-docs/f25d1085aa0ca331174381508e1897c29edd842fdd4c87498ad36740da047210.md b/debugger/v8_inspector_integration_for_node_js.md similarity index 100% rename from api-docs/f25d1085aa0ca331174381508e1897c29edd842fdd4c87498ad36740da047210.md rename to debugger/v8_inspector_integration_for_node_js.md diff --git a/api-docs/adac779a768c472e0da2ab506694a64bca9a51fff24747cb974b33784308aab6.md b/debugger/various.md similarity index 100% rename from api-docs/adac779a768c472e0da2ab506694a64bca9a51fff24747cb974b33784308aab6.md rename to debugger/various.md diff --git a/api-docs/7374a0fe7db91f1ee2d88d1480683a9c7485219ae0f808cef9ab1198bf48170a.md b/debugger/watchers.md similarity index 100% rename from api-docs/7374a0fe7db91f1ee2d88d1480683a9c7485219ae0f808cef9ab1198bf48170a.md rename to debugger/watchers.md diff --git a/deprecations/dep0001_http_outgoingmessage_prototype_flush.md b/deprecations/dep0001_http_outgoingmessage_prototype_flush.md new file mode 100644 index 00000000..1b4e5286 --- /dev/null +++ b/deprecations/dep0001_http_outgoingmessage_prototype_flush.md @@ -0,0 +1,18 @@ + + +Type: Runtime + +The `OutgoingMessage.prototype.flush()` method is deprecated. Use +`OutgoingMessage.prototype.flushHeaders()` instead. + + diff --git a/deprecations/dep0002_require_linklist.md b/deprecations/dep0002_require_linklist.md new file mode 100644 index 00000000..9a04c1ee --- /dev/null +++ b/deprecations/dep0002_require_linklist.md @@ -0,0 +1,18 @@ + + +Type: End-of-Life + +The `_linklist` module is deprecated. Please use a userland alternative. + + diff --git a/deprecations/dep0003_writablestate_buffer.md b/deprecations/dep0003_writablestate_buffer.md new file mode 100644 index 00000000..f7c949f9 --- /dev/null +++ b/deprecations/dep0003_writablestate_buffer.md @@ -0,0 +1,18 @@ + + +Type: Runtime + +The `_writableState.buffer` property is deprecated. Use the +`_writableState.getBuffer()` method instead. + + diff --git a/deprecations/dep0004_cryptostream_prototype_readystate.md b/deprecations/dep0004_cryptostream_prototype_readystate.md new file mode 100644 index 00000000..fee44eff --- /dev/null +++ b/deprecations/dep0004_cryptostream_prototype_readystate.md @@ -0,0 +1,20 @@ + + +Type: End-of-Life + +The `CryptoStream.prototype.readyState` property was removed. + + diff --git a/deprecations/dep0005_buffer_constructor.md b/deprecations/dep0005_buffer_constructor.md new file mode 100644 index 00000000..97b15e4a --- /dev/null +++ b/deprecations/dep0005_buffer_constructor.md @@ -0,0 +1,39 @@ + + +Type: Runtime (supports [`--pending-deprecation`][]) + +The `Buffer()` function and `new Buffer()` constructor are deprecated due to +API usability issues that can potentially lead to accidental security issues. + +As an alternative, use of the following methods of constructing `Buffer` objects +is strongly recommended: + +* [`Buffer.alloc(size[, fill[, encoding]])`][alloc] - Create a `Buffer` with + *initialized* memory. +* [`Buffer.allocUnsafe(size)`][alloc_unsafe_size] - Create a `Buffer` with + *uninitialized* memory. +* [`Buffer.allocUnsafeSlow(size)`][] - Create a `Buffer` with *uninitialized* + memory. +* [`Buffer.from(array)`][] - Create a `Buffer` with a copy of `array` +* [`Buffer.from(arrayBuffer[, byteOffset[, length]])`][from_arraybuffer] - + Create a `Buffer` that wraps the given `arrayBuffer`. +* [`Buffer.from(buffer)`][] - Create a `Buffer` that copies `buffer`. +* [`Buffer.from(string[, encoding])`][from_string_encoding] - Create a `Buffer` + that copies `string`. + +As of v10.0.0, a deprecation warning is printed at runtime when +`--pending-deprecation` is used or when the calling code is +outside `node_modules` in order to better target developers, rather than users. + + diff --git a/deprecations/dep0006_child_process_options_customfds.md b/deprecations/dep0006_child_process_options_customfds.md new file mode 100644 index 00000000..b25ca1c9 --- /dev/null +++ b/deprecations/dep0006_child_process_options_customfds.md @@ -0,0 +1,20 @@ + + +Type: Runtime + +Within the [`child_process`][] module's `spawn()`, `fork()`, and `exec()` +methods, the `options.customFds` option is deprecated. The `options.stdio` +option should be used instead. + + diff --git a/deprecations/dep0007_replace_cluster_worker_suicide_with_worker_exitedafterdisconnect.md b/deprecations/dep0007_replace_cluster_worker_suicide_with_worker_exitedafterdisconnect.md new file mode 100644 index 00000000..ad876489 --- /dev/null +++ b/deprecations/dep0007_replace_cluster_worker_suicide_with_worker_exitedafterdisconnect.md @@ -0,0 +1,26 @@ + + +Type: End-of-Life + +In an earlier version of the Node.js `cluster`, a boolean property with the name +`suicide` was added to the `Worker` object. The intent of this property was to +provide an indication of how and why the `Worker` instance exited. In Node.js +6.0.0, the old property was deprecated and replaced with a new +[`worker.exitedAfterDisconnect`][] property. The old property name did not +precisely describe the actual semantics and was unnecessarily emotion-laden. + + diff --git a/deprecations/dep0008_require_constants.md b/deprecations/dep0008_require_constants.md new file mode 100644 index 00000000..ac577dcc --- /dev/null +++ b/deprecations/dep0008_require_constants.md @@ -0,0 +1,18 @@ + + +Type: Documentation-only + +The `constants` module is deprecated. When requiring access to constants +relevant to specific Node.js builtin modules, developers should instead refer +to the `constants` property exposed by the relevant module. For instance, +`require('fs').constants` and `require('os').constants`. + + diff --git a/deprecations/dep0009_crypto_pbkdf2_without_digest.md b/deprecations/dep0009_crypto_pbkdf2_without_digest.md new file mode 100644 index 00000000..dda7a3d3 --- /dev/null +++ b/deprecations/dep0009_crypto_pbkdf2_without_digest.md @@ -0,0 +1,22 @@ + + +Type: End-of-Life + +Use of the [`crypto.pbkdf2()`][] API without specifying a digest was deprecated +in Node.js 6.0 because the method defaulted to using the non-recommended +`'SHA1'` digest. Previously, a deprecation warning was printed. Starting in +Node.js 8.0.0, calling `crypto.pbkdf2()` or `crypto.pbkdf2Sync()` with an +undefined `digest` will throw a `TypeError`. + + diff --git a/deprecations/dep0010_crypto_createcredentials.md b/deprecations/dep0010_crypto_createcredentials.md new file mode 100644 index 00000000..1688d718 --- /dev/null +++ b/deprecations/dep0010_crypto_createcredentials.md @@ -0,0 +1,18 @@ + + +Type: Runtime + +The [`crypto.createCredentials()`][] API is deprecated. Please use +[`tls.createSecureContext()`][] instead. + + diff --git a/deprecations/dep0011_crypto_credentials.md b/deprecations/dep0011_crypto_credentials.md new file mode 100644 index 00000000..65d13972 --- /dev/null +++ b/deprecations/dep0011_crypto_credentials.md @@ -0,0 +1,18 @@ + + +Type: Runtime + +The `crypto.Credentials` class is deprecated. Please use [`tls.SecureContext`][] +instead. + + diff --git a/deprecations/dep0012_domain_dispose.md b/deprecations/dep0012_domain_dispose.md new file mode 100644 index 00000000..62072261 --- /dev/null +++ b/deprecations/dep0012_domain_dispose.md @@ -0,0 +1,21 @@ + + +Type: End-of-Life + +`Domain.dispose()` has been removed. Recover from failed I/O actions +explicitly via error event handlers set on the domain instead. + + diff --git a/deprecations/dep0013_fs_asynchronous_function_without_callback.md b/deprecations/dep0013_fs_asynchronous_function_without_callback.md new file mode 100644 index 00000000..3e745c27 --- /dev/null +++ b/deprecations/dep0013_fs_asynchronous_function_without_callback.md @@ -0,0 +1,16 @@ + + +Type: End-of-Life + +Calling an asynchronous function without a callback throws a `TypeError` +in Node.js 10.0.0 onwards. (See .) + + diff --git a/deprecations/dep0014_fs_read_legacy_string_interface.md b/deprecations/dep0014_fs_read_legacy_string_interface.md new file mode 100644 index 00000000..9eb26afa --- /dev/null +++ b/deprecations/dep0014_fs_read_legacy_string_interface.md @@ -0,0 +1,24 @@ + + +Type: End-of-Life + +The [`fs.read()`][] legacy `String` interface is deprecated. Use the `Buffer` +API as mentioned in the documentation instead. + + diff --git a/deprecations/dep0015_fs_readsync_legacy_string_interface.md b/deprecations/dep0015_fs_readsync_legacy_string_interface.md new file mode 100644 index 00000000..fd9ab843 --- /dev/null +++ b/deprecations/dep0015_fs_readsync_legacy_string_interface.md @@ -0,0 +1,24 @@ + + +Type: End-of-Life + +The [`fs.readSync()`][] legacy `String` interface is deprecated. Use the +`Buffer` API as mentioned in the documentation instead. + + diff --git a/deprecations/dep0016_global_root.md b/deprecations/dep0016_global_root.md new file mode 100644 index 00000000..09b201e7 --- /dev/null +++ b/deprecations/dep0016_global_root.md @@ -0,0 +1,16 @@ + + +Type: Runtime + +The `GLOBAL` and `root` aliases for the `global` property are deprecated +and should no longer be used. + + diff --git a/deprecations/dep0017_intl_v8breakiterator.md b/deprecations/dep0017_intl_v8breakiterator.md new file mode 100644 index 00000000..f04cc8f3 --- /dev/null +++ b/deprecations/dep0017_intl_v8breakiterator.md @@ -0,0 +1,16 @@ + + +Type: End-of-Life + +`Intl.v8BreakIterator` was a non-standard extension and has been removed. +See [`Intl.Segmenter`](https://github.com/tc39/proposal-intl-segmenter). + + diff --git a/deprecations/dep0018_unhandled_promise_rejections.md b/deprecations/dep0018_unhandled_promise_rejections.md new file mode 100644 index 00000000..24538bea --- /dev/null +++ b/deprecations/dep0018_unhandled_promise_rejections.md @@ -0,0 +1,14 @@ + + +Type: Runtime + +Unhandled promise rejections are deprecated. In the future, promise rejections +that are not handled will terminate the Node.js process with a non-zero exit +code. + + diff --git a/deprecations/dep0019_require_resolved_outside_directory.md b/deprecations/dep0019_require_resolved_outside_directory.md new file mode 100644 index 00000000..9565bf11 --- /dev/null +++ b/deprecations/dep0019_require_resolved_outside_directory.md @@ -0,0 +1,19 @@ + + +Type: Runtime + +In certain cases, `require('.')` may resolve outside the package directory. +This behavior is deprecated and will be removed in a future major Node.js +release. + + diff --git a/deprecations/dep0020_server_connections.md b/deprecations/dep0020_server_connections.md new file mode 100644 index 00000000..6f7412f3 --- /dev/null +++ b/deprecations/dep0020_server_connections.md @@ -0,0 +1,18 @@ + + +Type: Runtime + +The [`Server.connections`][] property is deprecated. Please use the +[`Server.getConnections()`][] method instead. + + diff --git a/deprecations/dep0021_server_listenfd.md b/deprecations/dep0021_server_listenfd.md new file mode 100644 index 00000000..89731be4 --- /dev/null +++ b/deprecations/dep0021_server_listenfd.md @@ -0,0 +1,18 @@ + + +Type: Runtime + +The `Server.listenFD()` method is deprecated. Please use +[`Server.listen({fd: })`][] instead. + + diff --git a/deprecations/dep0022_os_tmpdir.md b/deprecations/dep0022_os_tmpdir.md new file mode 100644 index 00000000..3e0461b9 --- /dev/null +++ b/deprecations/dep0022_os_tmpdir.md @@ -0,0 +1,12 @@ + + +Type: Runtime + +The `os.tmpDir()` API is deprecated. Please use [`os.tmpdir()`][] instead. + + diff --git a/deprecations/dep0023_os_getnetworkinterfaces.md b/deprecations/dep0023_os_getnetworkinterfaces.md new file mode 100644 index 00000000..4113d32b --- /dev/null +++ b/deprecations/dep0023_os_getnetworkinterfaces.md @@ -0,0 +1,18 @@ + + +Type: Runtime + +The `os.getNetworkInterfaces()` method is deprecated. Please use the +[`os.networkInterfaces`][] property instead. + + diff --git a/deprecations/dep0024_replserver_prototype_converttocontext.md b/deprecations/dep0024_replserver_prototype_converttocontext.md new file mode 100644 index 00000000..a7887cff --- /dev/null +++ b/deprecations/dep0024_replserver_prototype_converttocontext.md @@ -0,0 +1,15 @@ + + +Type: End-of-Life + +The `REPLServer.prototype.convertToContext()` API has been removed. + + diff --git a/deprecations/dep0025_require_sys.md b/deprecations/dep0025_require_sys.md new file mode 100644 index 00000000..4cc00be1 --- /dev/null +++ b/deprecations/dep0025_require_sys.md @@ -0,0 +1,17 @@ + + +Type: Runtime + +The `sys` module is deprecated. Please use the [`util`][] module instead. + + diff --git a/deprecations/dep0026_util_print.md b/deprecations/dep0026_util_print.md new file mode 100644 index 00000000..f46c5a18 --- /dev/null +++ b/deprecations/dep0026_util_print.md @@ -0,0 +1,18 @@ + + +Type: Runtime + +The [`util.print()`][] API is deprecated. Please use [`console.log()`][] +instead. + + diff --git a/deprecations/dep0027_util_puts.md b/deprecations/dep0027_util_puts.md new file mode 100644 index 00000000..81bc3770 --- /dev/null +++ b/deprecations/dep0027_util_puts.md @@ -0,0 +1,17 @@ + + +Type: Runtime + +The [`util.puts()`][] API is deprecated. Please use [`console.log()`][] instead. + + diff --git a/deprecations/dep0028_util_debug.md b/deprecations/dep0028_util_debug.md new file mode 100644 index 00000000..e052a97f --- /dev/null +++ b/deprecations/dep0028_util_debug.md @@ -0,0 +1,18 @@ + + +Type: Runtime + +The [`util.debug()`][] API is deprecated. Please use [`console.error()`][] +instead. + + diff --git a/deprecations/dep0029_util_error.md b/deprecations/dep0029_util_error.md new file mode 100644 index 00000000..02b96ae0 --- /dev/null +++ b/deprecations/dep0029_util_error.md @@ -0,0 +1,18 @@ + + +Type: Runtime + +The [`util.error()`][] API is deprecated. Please use [`console.error()`][] +instead. + + diff --git a/deprecations/dep0030_slowbuffer.md b/deprecations/dep0030_slowbuffer.md new file mode 100644 index 00000000..7deae1eb --- /dev/null +++ b/deprecations/dep0030_slowbuffer.md @@ -0,0 +1,16 @@ + + +Type: Documentation-only + +The [`SlowBuffer`][] class is deprecated. Please use +[`Buffer.allocUnsafeSlow(size)`][] instead. + + diff --git a/deprecations/dep0031_ecdh_setpublickey.md b/deprecations/dep0031_ecdh_setpublickey.md new file mode 100644 index 00000000..6ba37846 --- /dev/null +++ b/deprecations/dep0031_ecdh_setpublickey.md @@ -0,0 +1,16 @@ + + +Type: Documentation-only + +The [`ecdh.setPublicKey()`][] method is now deprecated as its inclusion in the +API is not useful. + + diff --git a/deprecations/dep0032_domain_module.md b/deprecations/dep0032_domain_module.md new file mode 100644 index 00000000..936e5f98 --- /dev/null +++ b/deprecations/dep0032_domain_module.md @@ -0,0 +1,17 @@ + + +Type: Documentation-only + +The [`domain`][] module is deprecated and should not be used. + + diff --git a/deprecations/dep0033_eventemitter_listenercount.md b/deprecations/dep0033_eventemitter_listenercount.md new file mode 100644 index 00000000..e8b8288f --- /dev/null +++ b/deprecations/dep0033_eventemitter_listenercount.md @@ -0,0 +1,18 @@ + + +Type: Documentation-only + +The [`EventEmitter.listenerCount(emitter, eventName)`][] API is +deprecated. Please use [`emitter.listenerCount(eventName)`][] instead. + + diff --git a/deprecations/dep0034_fs_exists_path_callback.md b/deprecations/dep0034_fs_exists_path_callback.md new file mode 100644 index 00000000..9205e6ef --- /dev/null +++ b/deprecations/dep0034_fs_exists_path_callback.md @@ -0,0 +1,18 @@ + + +Type: Documentation-only + +The [`fs.exists(path, callback)`][] API is deprecated. Please use +[`fs.stat()`][] or [`fs.access()`][] instead. + + diff --git a/deprecations/dep0035_fs_lchmod_path_mode_callback.md b/deprecations/dep0035_fs_lchmod_path_mode_callback.md new file mode 100644 index 00000000..fd801599 --- /dev/null +++ b/deprecations/dep0035_fs_lchmod_path_mode_callback.md @@ -0,0 +1,16 @@ + + +Type: Documentation-only + +The [`fs.lchmod(path, mode, callback)`][] API is deprecated. + + diff --git a/deprecations/dep0036_fs_lchmodsync_path_mode.md b/deprecations/dep0036_fs_lchmodsync_path_mode.md new file mode 100644 index 00000000..cb42893c --- /dev/null +++ b/deprecations/dep0036_fs_lchmodsync_path_mode.md @@ -0,0 +1,16 @@ + + +Type: Documentation-only + +The [`fs.lchmodSync(path, mode)`][] API is deprecated. + + diff --git a/deprecations/dep0037_fs_lchown_path_uid_gid_callback.md b/deprecations/dep0037_fs_lchown_path_uid_gid_callback.md new file mode 100644 index 00000000..f88cdd6b --- /dev/null +++ b/deprecations/dep0037_fs_lchown_path_uid_gid_callback.md @@ -0,0 +1,19 @@ + + +Type: Deprecation revoked + +The [`fs.lchown(path, uid, gid, callback)`][] API is deprecated. + + diff --git a/deprecations/dep0038_fs_lchownsync_path_uid_gid.md b/deprecations/dep0038_fs_lchownsync_path_uid_gid.md new file mode 100644 index 00000000..9b7189e1 --- /dev/null +++ b/deprecations/dep0038_fs_lchownsync_path_uid_gid.md @@ -0,0 +1,19 @@ + + +Type: Deprecation revoked + +The [`fs.lchownSync(path, uid, gid)`][] API is deprecated. + + diff --git a/deprecations/dep0039_require_extensions.md b/deprecations/dep0039_require_extensions.md new file mode 100644 index 00000000..df03cc15 --- /dev/null +++ b/deprecations/dep0039_require_extensions.md @@ -0,0 +1,17 @@ + + +Type: Documentation-only + +The [`require.extensions`][] property is deprecated. + + diff --git a/deprecations/dep0040_punycode_module.md b/deprecations/dep0040_punycode_module.md new file mode 100644 index 00000000..b17c9412 --- /dev/null +++ b/deprecations/dep0040_punycode_module.md @@ -0,0 +1,13 @@ + + +Type: Documentation-only + +The [`punycode`][] module is deprecated. Please use a userland alternative +instead. + + diff --git a/deprecations/dep0041_node_repl_history_file_environment_variable.md b/deprecations/dep0041_node_repl_history_file_environment_variable.md new file mode 100644 index 00000000..d15bbb61 --- /dev/null +++ b/deprecations/dep0041_node_repl_history_file_environment_variable.md @@ -0,0 +1,21 @@ + + +Type: End-of-Life + +The `NODE_REPL_HISTORY_FILE` environment variable was removed. Please use +`NODE_REPL_HISTORY` instead. + + diff --git a/deprecations/dep0042_tls_cryptostream.md b/deprecations/dep0042_tls_cryptostream.md new file mode 100644 index 00000000..71bff536 --- /dev/null +++ b/deprecations/dep0042_tls_cryptostream.md @@ -0,0 +1,21 @@ + + +Type: End-of-Life + +The [`tls.CryptoStream`][] class was removed. Please use +[`tls.TLSSocket`][] instead. + + diff --git a/deprecations/dep0043_tls_securepair.md b/deprecations/dep0043_tls_securepair.md new file mode 100644 index 00000000..ca94fd87 --- /dev/null +++ b/deprecations/dep0043_tls_securepair.md @@ -0,0 +1,27 @@ + + +Type: Documentation-only + +The [`tls.SecurePair`][] class is deprecated. Please use +[`tls.TLSSocket`][] instead. + + diff --git a/deprecations/dep0044_util_isarray.md b/deprecations/dep0044_util_isarray.md new file mode 100644 index 00000000..ad19515b --- /dev/null +++ b/deprecations/dep0044_util_isarray.md @@ -0,0 +1,20 @@ + + +Type: Documentation-only + +The [`util.isArray()`][] API is deprecated. Please use `Array.isArray()` +instead. + + diff --git a/deprecations/dep0045_util_isboolean.md b/deprecations/dep0045_util_isboolean.md new file mode 100644 index 00000000..98ecd7e3 --- /dev/null +++ b/deprecations/dep0045_util_isboolean.md @@ -0,0 +1,19 @@ + + +Type: Documentation-only + +The [`util.isBoolean()`][] API is deprecated. + + diff --git a/deprecations/dep0046_util_isbuffer.md b/deprecations/dep0046_util_isbuffer.md new file mode 100644 index 00000000..556cbcb0 --- /dev/null +++ b/deprecations/dep0046_util_isbuffer.md @@ -0,0 +1,20 @@ + + +Type: Documentation-only + +The [`util.isBuffer()`][] API is deprecated. Please use +[`Buffer.isBuffer()`][] instead. + + diff --git a/deprecations/dep0047_util_isdate.md b/deprecations/dep0047_util_isdate.md new file mode 100644 index 00000000..79b0d232 --- /dev/null +++ b/deprecations/dep0047_util_isdate.md @@ -0,0 +1,19 @@ + + +Type: Documentation-only + +The [`util.isDate()`][] API is deprecated. + + diff --git a/deprecations/dep0048_util_iserror.md b/deprecations/dep0048_util_iserror.md new file mode 100644 index 00000000..7bb827f2 --- /dev/null +++ b/deprecations/dep0048_util_iserror.md @@ -0,0 +1,19 @@ + + +Type: Documentation-only + +The [`util.isError()`][] API is deprecated. + + diff --git a/deprecations/dep0049_util_isfunction.md b/deprecations/dep0049_util_isfunction.md new file mode 100644 index 00000000..dcd7453b --- /dev/null +++ b/deprecations/dep0049_util_isfunction.md @@ -0,0 +1,19 @@ + + +Type: Documentation-only + +The [`util.isFunction()`][] API is deprecated. + + diff --git a/deprecations/dep0050_util_isnull.md b/deprecations/dep0050_util_isnull.md new file mode 100644 index 00000000..e8c43ec1 --- /dev/null +++ b/deprecations/dep0050_util_isnull.md @@ -0,0 +1,19 @@ + + +Type: Documentation-only + +The [`util.isNull()`][] API is deprecated. + + diff --git a/deprecations/dep0051_util_isnullorundefined.md b/deprecations/dep0051_util_isnullorundefined.md new file mode 100644 index 00000000..701179fc --- /dev/null +++ b/deprecations/dep0051_util_isnullorundefined.md @@ -0,0 +1,19 @@ + + +Type: Documentation-only + +The [`util.isNullOrUndefined()`][] API is deprecated. + + diff --git a/deprecations/dep0052_util_isnumber.md b/deprecations/dep0052_util_isnumber.md new file mode 100644 index 00000000..459b7684 --- /dev/null +++ b/deprecations/dep0052_util_isnumber.md @@ -0,0 +1,19 @@ + + +Type: Documentation-only + +The [`util.isNumber()`][] API is deprecated. + + diff --git a/deprecations/dep0053_util_isobject.md b/deprecations/dep0053_util_isobject.md new file mode 100644 index 00000000..5f00b6f0 --- /dev/null +++ b/deprecations/dep0053_util_isobject.md @@ -0,0 +1,19 @@ + + +Type: Documentation-only + +The [`util.isObject()`][] API is deprecated. + + diff --git a/deprecations/dep0054_util_isprimitive.md b/deprecations/dep0054_util_isprimitive.md new file mode 100644 index 00000000..66c82205 --- /dev/null +++ b/deprecations/dep0054_util_isprimitive.md @@ -0,0 +1,19 @@ + + +Type: Documentation-only + +The [`util.isPrimitive()`][] API is deprecated. + + diff --git a/deprecations/dep0055_util_isregexp.md b/deprecations/dep0055_util_isregexp.md new file mode 100644 index 00000000..f8da7d2f --- /dev/null +++ b/deprecations/dep0055_util_isregexp.md @@ -0,0 +1,19 @@ + + +Type: Documentation-only + +The [`util.isRegExp()`][] API is deprecated. + + diff --git a/deprecations/dep0056_util_isstring.md b/deprecations/dep0056_util_isstring.md new file mode 100644 index 00000000..3c6de110 --- /dev/null +++ b/deprecations/dep0056_util_isstring.md @@ -0,0 +1,19 @@ + + +Type: Documentation-only + +The [`util.isString()`][] API is deprecated. + + diff --git a/deprecations/dep0057_util_issymbol.md b/deprecations/dep0057_util_issymbol.md new file mode 100644 index 00000000..508ad164 --- /dev/null +++ b/deprecations/dep0057_util_issymbol.md @@ -0,0 +1,19 @@ + + +Type: Documentation-only + +The [`util.isSymbol()`][] API is deprecated. + + diff --git a/deprecations/dep0058_util_isundefined.md b/deprecations/dep0058_util_isundefined.md new file mode 100644 index 00000000..2adf60bb --- /dev/null +++ b/deprecations/dep0058_util_isundefined.md @@ -0,0 +1,19 @@ + + +Type: Documentation-only + +The [`util.isUndefined()`][] API is deprecated. + + diff --git a/deprecations/dep0059_util_log.md b/deprecations/dep0059_util_log.md new file mode 100644 index 00000000..eabfaee2 --- /dev/null +++ b/deprecations/dep0059_util_log.md @@ -0,0 +1,15 @@ + + +Type: Documentation-only + +The [`util.log()`][] API is deprecated. + + diff --git a/deprecations/dep0060_util_extend.md b/deprecations/dep0060_util_extend.md new file mode 100644 index 00000000..0e7eee13 --- /dev/null +++ b/deprecations/dep0060_util_extend.md @@ -0,0 +1,15 @@ + + +Type: Documentation-only + +The [`util._extend()`][] API is deprecated. + + diff --git a/deprecations/dep0061_fs_syncwritestream.md b/deprecations/dep0061_fs_syncwritestream.md new file mode 100644 index 00000000..a4ac33da --- /dev/null +++ b/deprecations/dep0061_fs_syncwritestream.md @@ -0,0 +1,16 @@ + + +Type: Runtime + +The `fs.SyncWriteStream` class was never intended to be a publicly accessible +API. No alternative API is available. Please use a userland alternative. + + diff --git a/deprecations/dep0062_node_debug.md b/deprecations/dep0062_node_debug.md new file mode 100644 index 00000000..9ae68d16 --- /dev/null +++ b/deprecations/dep0062_node_debug.md @@ -0,0 +1,14 @@ + + +Type: Runtime + +`--debug` activates the legacy V8 debugger interface, which was removed as +of V8 5.8. It is replaced by Inspector which is activated with `--inspect` +instead. + + diff --git a/deprecations/dep0063_serverresponse_prototype_writeheader.md b/deprecations/dep0063_serverresponse_prototype_writeheader.md new file mode 100644 index 00000000..0a0e6244 --- /dev/null +++ b/deprecations/dep0063_serverresponse_prototype_writeheader.md @@ -0,0 +1,16 @@ + + +Type: Documentation-only + +The `http` module `ServerResponse.prototype.writeHeader()` API is +deprecated. Please use `ServerResponse.prototype.writeHead()` instead. + +The `ServerResponse.prototype.writeHeader()` method was never documented as an +officially supported API. + + diff --git a/deprecations/dep0064_tls_createsecurepair.md b/deprecations/dep0064_tls_createsecurepair.md new file mode 100644 index 00000000..1ce7f4c8 --- /dev/null +++ b/deprecations/dep0064_tls_createsecurepair.md @@ -0,0 +1,27 @@ + + +Type: Runtime + +The `tls.createSecurePair()` API was deprecated in documentation in Node.js +0.11.3. Users should use `tls.Socket` instead. + + diff --git a/deprecations/dep0065_repl_repl_mode_magic_and_node_repl_mode_magic.md b/deprecations/dep0065_repl_repl_mode_magic_and_node_repl_mode_magic.md new file mode 100644 index 00000000..0adf414c --- /dev/null +++ b/deprecations/dep0065_repl_repl_mode_magic_and_node_repl_mode_magic.md @@ -0,0 +1,22 @@ + + +Type: End-of-Life + +The `repl` module's `REPL_MODE_MAGIC` constant, used for `replMode` option, has +been removed. Its behavior has been functionally identical to that of +`REPL_MODE_SLOPPY` since Node.js 6.0.0, when V8 5.0 was imported. Please use +`REPL_MODE_SLOPPY` instead. + +The `NODE_REPL_MODE` environment variable is used to set the underlying +`replMode` of an interactive `node` session. Its value, `magic`, is also +removed. Please use `sloppy` instead. + + diff --git a/deprecations/dep0066_outgoingmessage_headers_outgoingmessage_headernames.md b/deprecations/dep0066_outgoingmessage_headers_outgoingmessage_headernames.md new file mode 100644 index 00000000..8a304778 --- /dev/null +++ b/deprecations/dep0066_outgoingmessage_headers_outgoingmessage_headernames.md @@ -0,0 +1,20 @@ + + +Type: Documentation-only + +The `http` module `outgoingMessage._headers` and `outgoingMessage._headerNames` +properties are deprecated. Use one of the public methods +(e.g. `outgoingMessage.getHeader()`, `outgoingMessage.getHeaders()`, +`outgoingMessage.getHeaderNames()`, `outgoingMessage.hasHeader()`, +`outgoingMessage.removeHeader()`, `outgoingMessage.setHeader()`) for working +with outgoing headers. + +The `outgoingMessage._headers` and `outgoingMessage._headerNames` properties +were never documented as officially supported properties. + + diff --git a/deprecations/dep0067_outgoingmessage_prototype_renderheaders.md b/deprecations/dep0067_outgoingmessage_prototype_renderheaders.md new file mode 100644 index 00000000..6006480b --- /dev/null +++ b/deprecations/dep0067_outgoingmessage_prototype_renderheaders.md @@ -0,0 +1,16 @@ + + +Type: Documentation-only + +The `http` module `OutgoingMessage.prototype._renderHeaders()` API is +deprecated. + +The `OutgoingMessage.prototype._renderHeaders` property was never documented as +an officially supported API. + + diff --git a/deprecations/dep0068_node_debug.md b/deprecations/dep0068_node_debug.md new file mode 100644 index 00000000..2788a971 --- /dev/null +++ b/deprecations/dep0068_node_debug.md @@ -0,0 +1,13 @@ + + +Type: Runtime + +`node debug` corresponds to the legacy CLI debugger which has been replaced with +a V8-inspector based CLI debugger available through `node inspect`. + + diff --git a/deprecations/dep0069_vm_runindebugcontext_string.md b/deprecations/dep0069_vm_runindebugcontext_string.md new file mode 100644 index 00000000..de6938a7 --- /dev/null +++ b/deprecations/dep0069_vm_runindebugcontext_string.md @@ -0,0 +1,20 @@ + + +Type: End-of-Life + +DebugContext has been removed in V8 and is not available in Node.js 10+. + +DebugContext was an experimental API. + + diff --git a/deprecations/dep0070_async_hooks_currentid.md b/deprecations/dep0070_async_hooks_currentid.md new file mode 100644 index 00000000..53b5716d --- /dev/null +++ b/deprecations/dep0070_async_hooks_currentid.md @@ -0,0 +1,18 @@ + + +Type: End-of-Life + +`async_hooks.currentId()` was renamed to `async_hooks.executionAsyncId()` for +clarity. + +This change was made while `async_hooks` was an experimental API. + + diff --git a/deprecations/dep0071_async_hooks_triggerid.md b/deprecations/dep0071_async_hooks_triggerid.md new file mode 100644 index 00000000..c7be7db3 --- /dev/null +++ b/deprecations/dep0071_async_hooks_triggerid.md @@ -0,0 +1,18 @@ + + +Type: End-of-Life + +`async_hooks.triggerId()` was renamed to `async_hooks.triggerAsyncId()` for +clarity. + +This change was made while `async_hooks` was an experimental API. + + diff --git a/deprecations/dep0072_async_hooks_asyncresource_triggerid.md b/deprecations/dep0072_async_hooks_asyncresource_triggerid.md new file mode 100644 index 00000000..19ab5517 --- /dev/null +++ b/deprecations/dep0072_async_hooks_asyncresource_triggerid.md @@ -0,0 +1,18 @@ + + +Type: End-of-Life + +`async_hooks.AsyncResource.triggerId()` was renamed to +`async_hooks.AsyncResource.triggerAsyncId()` for clarity. + +This change was made while `async_hooks` was an experimental API. + + diff --git a/deprecations/dep0073_several_internal_properties_of_net_server.md b/deprecations/dep0073_several_internal_properties_of_net_server.md new file mode 100644 index 00000000..5b0138b5 --- /dev/null +++ b/deprecations/dep0073_several_internal_properties_of_net_server.md @@ -0,0 +1,19 @@ + + +Type: End-of-Life + +Accessing several internal, undocumented properties of `net.Server` instances +with inappropriate names is deprecated. + +As the original API was undocumented and not generally useful for non-internal +code, no replacement API is provided. + + diff --git a/deprecations/dep0074_replserver_bufferedcommand.md b/deprecations/dep0074_replserver_bufferedcommand.md new file mode 100644 index 00000000..a5b40cc2 --- /dev/null +++ b/deprecations/dep0074_replserver_bufferedcommand.md @@ -0,0 +1,13 @@ + + +Type: Runtime + +The `REPLServer.bufferedCommand` property was deprecated in favor of +[`REPLServer.clearBufferedCommand()`][]. + + diff --git a/deprecations/dep0075_replserver_parsereplkeyword.md b/deprecations/dep0075_replserver_parsereplkeyword.md new file mode 100644 index 00000000..b5d0a29e --- /dev/null +++ b/deprecations/dep0075_replserver_parsereplkeyword.md @@ -0,0 +1,12 @@ + + +Type: Runtime + +`REPLServer.parseREPLKeyword()` was removed from userland visibility. + + diff --git a/deprecations/dep0076_tls_parsecertstring.md b/deprecations/dep0076_tls_parsecertstring.md new file mode 100644 index 00000000..7e83b7ea --- /dev/null +++ b/deprecations/dep0076_tls_parsecertstring.md @@ -0,0 +1,31 @@ + + +Type: Runtime + +`tls.parseCertString()` is a trivial parsing helper that was made public by +mistake. This function can usually be replaced with: + +```js +const querystring = require('querystring'); +querystring.parse(str, '\n', '='); +``` + +This function is not completely equivalent to `querystring.parse()`. One +difference is that `querystring.parse()` does url decoding: + +```sh +> querystring.parse('%E5%A5%BD=1', '\n', '='); +{ '好': '1' } +> tls.parseCertString('%E5%A5%BD=1'); +{ '%E5%A5%BD': '1' } +``` + + diff --git a/deprecations/dep0077_module_debug.md b/deprecations/dep0077_module_debug.md new file mode 100644 index 00000000..3211a4cf --- /dev/null +++ b/deprecations/dep0077_module_debug.md @@ -0,0 +1,15 @@ + + +Type: Runtime + +`Module._debug()` is deprecated. + +The `Module._debug()` function was never documented as an officially +supported API. + + diff --git a/deprecations/dep0078_replserver_turnoffeditormode.md b/deprecations/dep0078_replserver_turnoffeditormode.md new file mode 100644 index 00000000..0e2add8f --- /dev/null +++ b/deprecations/dep0078_replserver_turnoffeditormode.md @@ -0,0 +1,12 @@ + + +Type: Runtime + +`REPLServer.turnOffEditorMode()` was removed from userland visibility. + + diff --git a/deprecations/dep0079_custom_inspection_function_on_objects_via_inspect.md b/deprecations/dep0079_custom_inspection_function_on_objects_via_inspect.md new file mode 100644 index 00000000..15086cd0 --- /dev/null +++ b/deprecations/dep0079_custom_inspection_function_on_objects_via_inspect.md @@ -0,0 +1,18 @@ + + +Type: Runtime + +Using a property named `inspect` on an object to specify a custom inspection +function for [`util.inspect()`][] is deprecated. Use [`util.inspect.custom`][] +instead. For backward compatibility with Node.js prior to version 6.4.0, both +may be specified. + + diff --git a/deprecations/dep0080_path_makelong.md b/deprecations/dep0080_path_makelong.md new file mode 100644 index 00000000..360b3dfc --- /dev/null +++ b/deprecations/dep0080_path_makelong.md @@ -0,0 +1,14 @@ + + +Type: Documentation-only + +The internal `path._makeLong()` was not intended for public use. However, +userland modules have found it useful. The internal API is deprecated +and replaced with an identical, public `path.toNamespacedPath()` method. + + diff --git a/deprecations/dep0081_fs_truncate_using_a_file_descriptor.md b/deprecations/dep0081_fs_truncate_using_a_file_descriptor.md new file mode 100644 index 00000000..64e39271 --- /dev/null +++ b/deprecations/dep0081_fs_truncate_using_a_file_descriptor.md @@ -0,0 +1,14 @@ + + +Type: Runtime + +`fs.truncate()` `fs.truncateSync()` usage with a file descriptor is +deprecated. Please use `fs.ftruncate()` or `fs.ftruncateSync()` to work with +file descriptors. + + diff --git a/deprecations/dep0082_replserver_prototype_memory.md b/deprecations/dep0082_replserver_prototype_memory.md new file mode 100644 index 00000000..682f0461 --- /dev/null +++ b/deprecations/dep0082_replserver_prototype_memory.md @@ -0,0 +1,13 @@ + + +Type: Runtime + +`REPLServer.prototype.memory()` is only necessary for the internal mechanics of +the `REPLServer` itself. Do not use this function. + + diff --git a/deprecations/dep0083_disabling_ecdh_by_setting_ecdhcurve_to_false.md b/deprecations/dep0083_disabling_ecdh_by_setting_ecdhcurve_to_false.md new file mode 100644 index 00000000..817905ad --- /dev/null +++ b/deprecations/dep0083_disabling_ecdh_by_setting_ecdhcurve_to_false.md @@ -0,0 +1,18 @@ + + +Type: End-of-Life. + +The `ecdhCurve` option to `tls.createSecureContext()` and `tls.TLSSocket` could +be set to `false` to disable ECDH entirely on the server only. This mode was +deprecated in preparation for migrating to OpenSSL 1.1.0 and consistency with +the client and is now unsupported. Use the `ciphers` parameter instead. + + diff --git a/deprecations/dep0084_requiring_bundled_internal_dependencies.md b/deprecations/dep0084_requiring_bundled_internal_dependencies.md new file mode 100644 index 00000000..507a08d5 --- /dev/null +++ b/deprecations/dep0084_requiring_bundled_internal_dependencies.md @@ -0,0 +1,36 @@ + + +Type: Runtime + +Since Node.js versions 4.4.0 and 5.2.0, several modules only intended for +internal usage are mistakenly exposed to user code through `require()`. These +modules are: + +- `v8/tools/codemap` +- `v8/tools/consarray` +- `v8/tools/csvparser` +- `v8/tools/logreader` +- `v8/tools/profile_view` +- `v8/tools/profile` +- `v8/tools/SourceMap` +- `v8/tools/splaytree` +- `v8/tools/tickprocessor-driver` +- `v8/tools/tickprocessor` +- `node-inspect/lib/_inspect` (from 7.6.0) +- `node-inspect/lib/internal/inspect_client` (from 7.6.0) +- `node-inspect/lib/internal/inspect_repl` (from 7.6.0) + +The `v8/*` modules do not have any exports, and if not imported in a specific +order would in fact throw errors. As such there are virtually no legitimate use +cases for importing them through `require()`. + +On the other hand, `node-inspect` may be installed locally through a package +manager, as it is published on the npm registry under the same name. No source +code modification is necessary if that is done. + + diff --git a/deprecations/dep0085_asynchooks_sensitive_api.md b/deprecations/dep0085_asynchooks_sensitive_api.md new file mode 100644 index 00000000..a4dfef5f --- /dev/null +++ b/deprecations/dep0085_asynchooks_sensitive_api.md @@ -0,0 +1,19 @@ + + +Type: End-of-Life + +The AsyncHooks Sensitive API was never documented and had various minor issues. +(See .) Use the `AsyncResource` +API instead. + + diff --git a/deprecations/dep0086_remove_runinasyncidscope.md b/deprecations/dep0086_remove_runinasyncidscope.md new file mode 100644 index 00000000..ca91dd32 --- /dev/null +++ b/deprecations/dep0086_remove_runinasyncidscope.md @@ -0,0 +1,19 @@ + + +Type: End-of-Life + +`runInAsyncIdScope` doesn't emit the `'before'` or `'after'` event and can thus +cause a lot of issues. See for +more details. + + diff --git a/deprecations/dep0089_require_assert.md b/deprecations/dep0089_require_assert.md new file mode 100644 index 00000000..b86f5744 --- /dev/null +++ b/deprecations/dep0089_require_assert.md @@ -0,0 +1,16 @@ + + +Type: Documentation-only + +Importing assert directly is not recommended as the exposed functions will use +loose equality checks. Use `require('assert').strict` instead. The API is the +same as the legacy assert but it will always use strict equality checks. + + diff --git a/deprecations/dep0090_invalid_gcm_authentication_tag_lengths.md b/deprecations/dep0090_invalid_gcm_authentication_tag_lengths.md new file mode 100644 index 00000000..bf83c5d8 --- /dev/null +++ b/deprecations/dep0090_invalid_gcm_authentication_tag_lengths.md @@ -0,0 +1,17 @@ + + +Type: Runtime + +Node.js supports all GCM authentication tag lengths which are accepted by +OpenSSL when calling [`decipher.setAuthTag()`][]. This behavior will change in +a future version at which point only authentication tag lengths of 128, 120, +112, 104, 96, 64, and 32 bits will be allowed. Authentication tags whose length +is not included in this list will be considered invalid in compliance with +[NIST SP 800-38D][]. + + diff --git a/deprecations/dep0091_crypto_default_encoding.md b/deprecations/dep0091_crypto_default_encoding.md new file mode 100644 index 00000000..e51f8e57 --- /dev/null +++ b/deprecations/dep0091_crypto_default_encoding.md @@ -0,0 +1,12 @@ + + +Type: Runtime + +The [`crypto.DEFAULT_ENCODING`][] property is deprecated. + + diff --git a/deprecations/dep0092_top_level_this_bound_to_module_exports.md b/deprecations/dep0092_top_level_this_bound_to_module_exports.md new file mode 100644 index 00000000..0e281a16 --- /dev/null +++ b/deprecations/dep0092_top_level_this_bound_to_module_exports.md @@ -0,0 +1,14 @@ + + +Type: Documentation-only + +Assigning properties to the top-level `this` as an alternative +to `module.exports` is deprecated. Developers should use `exports` +or `module.exports` instead. + + diff --git a/deprecations/dep0093_crypto_fips_is_deprecated_and_replaced.md b/deprecations/dep0093_crypto_fips_is_deprecated_and_replaced.md new file mode 100644 index 00000000..7e8628eb --- /dev/null +++ b/deprecations/dep0093_crypto_fips_is_deprecated_and_replaced.md @@ -0,0 +1,13 @@ + + +Type: Documentation-only + +The [`crypto.fips`][] property is deprecated. Please use `crypto.setFips()` +and `crypto.getFips()` instead. + + diff --git a/deprecations/dep0094_using_assert_fail_with_more_than_one_argument.md b/deprecations/dep0094_using_assert_fail_with_more_than_one_argument.md new file mode 100644 index 00000000..6c00c63c --- /dev/null +++ b/deprecations/dep0094_using_assert_fail_with_more_than_one_argument.md @@ -0,0 +1,14 @@ + + +Type: Runtime + +Using `assert.fail()` with more than one argument is deprecated. Use +`assert.fail()` with only one argument or use a different `assert` module +method. + + diff --git a/deprecations/dep0095_timers_enroll.md b/deprecations/dep0095_timers_enroll.md new file mode 100644 index 00000000..ad4b8f16 --- /dev/null +++ b/deprecations/dep0095_timers_enroll.md @@ -0,0 +1,13 @@ + + +Type: Runtime + +`timers.enroll()` is deprecated. Please use the publicly documented +[`setTimeout()`][] or [`setInterval()`][] instead. + + diff --git a/deprecations/dep0096_timers_unenroll.md b/deprecations/dep0096_timers_unenroll.md new file mode 100644 index 00000000..2c8bfe67 --- /dev/null +++ b/deprecations/dep0096_timers_unenroll.md @@ -0,0 +1,13 @@ + + +Type: Runtime + +`timers.unenroll()` is deprecated. Please use the publicly documented +[`clearTimeout()`][] or [`clearInterval()`][] instead. + + diff --git a/deprecations/dep0097_makecallback_with_domain_property.md b/deprecations/dep0097_makecallback_with_domain_property.md new file mode 100644 index 00000000..56e28b08 --- /dev/null +++ b/deprecations/dep0097_makecallback_with_domain_property.md @@ -0,0 +1,14 @@ + + +Type: Runtime + +Users of `MakeCallback` that add the `domain` property to carry context, +should start using the `async_context` variant of `MakeCallback` or +`CallbackScope`, or the high-level `AsyncResource` class. + + diff --git a/deprecations/dep0098_asynchooks_embedder_asyncresource_emitbefore_and_asyncresource_emitafter_apis.md b/deprecations/dep0098_asynchooks_embedder_asyncresource_emitbefore_and_asyncresource_emitafter_apis.md new file mode 100644 index 00000000..05927f2d --- /dev/null +++ b/deprecations/dep0098_asynchooks_embedder_asyncresource_emitbefore_and_asyncresource_emitafter_apis.md @@ -0,0 +1,21 @@ + + +Type: Runtime + +The embedded API provided by AsyncHooks exposes `.emitBefore()` and +`.emitAfter()` methods which are very easy to use incorrectly which can lead +to unrecoverable errors. + +Use [`asyncResource.runInAsyncScope()`][] API instead which provides a much +safer, and more convenient, alternative. See + for more details. + + diff --git a/deprecations/dep0099_async_context_unaware_node_makecallback_c_apis.md b/deprecations/dep0099_async_context_unaware_node_makecallback_c_apis.md new file mode 100644 index 00000000..11aae171 --- /dev/null +++ b/deprecations/dep0099_async_context_unaware_node_makecallback_c_apis.md @@ -0,0 +1,14 @@ + + +Type: Compile-time + +Certain versions of `node::MakeCallback` APIs available to native modules are +deprecated. Please use the versions of the API that accept an `async_context` +parameter. + + diff --git a/deprecations/dep0100_process_assert.md b/deprecations/dep0100_process_assert.md new file mode 100644 index 00000000..354f94d1 --- /dev/null +++ b/deprecations/dep0100_process_assert.md @@ -0,0 +1,16 @@ + + +Type: Runtime + +`process.assert()` is deprecated. Please use the [`assert`][] module instead. + +This was never a documented feature. + + diff --git a/deprecations/dep0101_with_lttng.md b/deprecations/dep0101_with_lttng.md new file mode 100644 index 00000000..11059e27 --- /dev/null +++ b/deprecations/dep0101_with_lttng.md @@ -0,0 +1,12 @@ + + +Type: End-of-Life + +The `--with-lttng` compile-time option has been removed. + + diff --git a/deprecations/dep0102_using_noassert_in_buffer_read_write_operations.md b/deprecations/dep0102_using_noassert_in_buffer_read_write_operations.md new file mode 100644 index 00000000..954f4b02 --- /dev/null +++ b/deprecations/dep0102_using_noassert_in_buffer_read_write_operations.md @@ -0,0 +1,14 @@ + + +Type: End-of-Life + +Using the `noAssert` argument has no functionality anymore. All input is going +to be verified, no matter if it is set to true or not. Skipping the verification +could lead to hard to find errors and crashes. + + diff --git a/deprecations/dep0103_process_binding_util_is_typechecks.md b/deprecations/dep0103_process_binding_util_is_typechecks.md new file mode 100644 index 00000000..b0b21722 --- /dev/null +++ b/deprecations/dep0103_process_binding_util_is_typechecks.md @@ -0,0 +1,19 @@ + + +Type: Documentation-only (supports [`--pending-deprecation`][]) + +Using `process.binding()` in general should be avoided. The type checking +methods in particular can be replaced by using [`util.types`][]. + +This deprecation has been superseded by the deprecation of the +`process.binding()` API ([DEP0111](#DEP0111)). + + diff --git a/deprecations/dep0104_process_env_string_coercion.md b/deprecations/dep0104_process_env_string_coercion.md new file mode 100644 index 00000000..0e245144 --- /dev/null +++ b/deprecations/dep0104_process_env_string_coercion.md @@ -0,0 +1,16 @@ + + +Type: Documentation-only (supports [`--pending-deprecation`][]) + +When assigning a non-string property to [`process.env`][], the assigned value is +implicitly converted to a string. This behavior is deprecated if the assigned +value is not a string, boolean, or number. In the future, such assignment may +result in a thrown error. Please convert the property to a string before +assigning it to `process.env`. + + diff --git a/deprecations/dep0105_decipher_finaltol.md b/deprecations/dep0105_decipher_finaltol.md new file mode 100644 index 00000000..818b9785 --- /dev/null +++ b/deprecations/dep0105_decipher_finaltol.md @@ -0,0 +1,14 @@ + + +Type: Runtime + +`decipher.finaltol()` has never been documented and is currently an alias for +[`decipher.final()`][]. In the future, this API will likely be removed, and it +is recommended to use [`decipher.final()`][] instead. + + diff --git a/deprecations/dep0106_crypto_createcipher_and_crypto_createdecipher.md b/deprecations/dep0106_crypto_createcipher_and_crypto_createdecipher.md new file mode 100644 index 00000000..b3e7b9cb --- /dev/null +++ b/deprecations/dep0106_crypto_createcipher_and_crypto_createdecipher.md @@ -0,0 +1,17 @@ + + +Type: Documentation-only + +Using [`crypto.createCipher()`][] and [`crypto.createDecipher()`][] should be +avoided as they use a weak key derivation function (MD5 with no salt) and static +initialization vectors. It is recommended to derive a key using +[`crypto.pbkdf2()`][] or [`crypto.scrypt()`][] and to use +[`crypto.createCipheriv()`][] and [`crypto.createDecipheriv()`][] to obtain the +[`Cipher`][] and [`Decipher`][] objects respectively. + + diff --git a/deprecations/dep0107_tls_convertnpnprotocols.md b/deprecations/dep0107_tls_convertnpnprotocols.md new file mode 100644 index 00000000..e1322dc4 --- /dev/null +++ b/deprecations/dep0107_tls_convertnpnprotocols.md @@ -0,0 +1,13 @@ + + +Type: Runtime + +This was an undocumented helper function not intended for use outside Node.js +core and obsoleted by the removal of NPN (Next Protocol Negotiation) support. + + diff --git a/deprecations/dep0108_zlib_bytesread.md b/deprecations/dep0108_zlib_bytesread.md new file mode 100644 index 00000000..0f38d2c3 --- /dev/null +++ b/deprecations/dep0108_zlib_bytesread.md @@ -0,0 +1,15 @@ + + +Type: Documentation-only + +Deprecated alias for [`zlib.bytesWritten`][]. This original name was chosen +because it also made sense to interpret the value as the number of bytes +read by the engine, but is inconsistent with other streams in Node.js that +expose values under these names. + + diff --git a/deprecations/dep0110_vm_script_cached_data.md b/deprecations/dep0110_vm_script_cached_data.md new file mode 100644 index 00000000..1031ef2b --- /dev/null +++ b/deprecations/dep0110_vm_script_cached_data.md @@ -0,0 +1,13 @@ + + +Type: Documentation-only + +The `produceCachedData` option is deprecated. Use +[`script.createCachedData()`][] instead. + + diff --git a/api-docs/ef6d015d40b9d1e7bddc87e622b28321cd670f6c304fad1c7d7ab1edac989e8d.md b/deprecations/dep0111_process_binding.md similarity index 65% rename from api-docs/ef6d015d40b9d1e7bddc87e622b28321cd670f6c304fad1c7d7ab1edac989e8d.md rename to deprecations/dep0111_process_binding.md index 75727bc4..2324b600 100644 --- a/api-docs/ef6d015d40b9d1e7bddc87e622b28321cd670f6c304fad1c7d7ab1edac989e8d.md +++ b/deprecations/dep0111_process_binding.md @@ -7,8 +7,7 @@ changes: Type: Documentation-only -The `process.binding()` API is intended for use by Node.js internal code -only. Use of `process.binding()` by userland code is unsupported. +`process.binding()` is for use by Node.js internal code only. diff --git a/deprecations/deprecated_apis.md b/deprecations/deprecated_apis.md new file mode 100644 index 00000000..b871e0d4 --- /dev/null +++ b/deprecations/deprecated_apis.md @@ -0,0 +1,31 @@ + + + + +Node.js may deprecate APIs when either: (a) use of the API is considered to be +unsafe, (b) an improved alternative API is available, or (c) breaking changes to +the API are expected in a future major release. + +Node.js utilizes three kinds of Deprecations: + +* Documentation-only +* Runtime +* End-of-Life + +A Documentation-only deprecation is one that is expressed only within the +Node.js API docs. These generate no side-effects while running Node.js. +Some Documentation-only deprecations trigger a runtime warning when launched +with [`--pending-deprecation`][] flag (or its alternative, +`NODE_PENDING_DEPRECATION=1` environment variable), similarly to Runtime +deprecations below. Documentation-only deprecations that support that flag +are explicitly labeled as such in the +[list of Deprecated APIs](#deprecations_list_of_deprecated_apis). + +A Runtime deprecation will, by default, generate a process warning that will +be printed to `stderr` the first time the deprecated API is used. When the +`--throw-deprecation` command-line flag is used, a Runtime deprecation will +cause an error to be thrown. + +An End-of-Life deprecation is used when functionality is or will soon be removed +from Node.js. + diff --git a/deprecations/list_of_deprecated_apis.md b/deprecations/list_of_deprecated_apis.md new file mode 100644 index 00000000..3e5e2066 --- /dev/null +++ b/deprecations/list_of_deprecated_apis.md @@ -0,0 +1,2 @@ + + diff --git a/deprecations/revoking_deprecations.md b/deprecations/revoking_deprecations.md new file mode 100644 index 00000000..79ff68eb --- /dev/null +++ b/deprecations/revoking_deprecations.md @@ -0,0 +1,5 @@ + +Occasionally, the deprecation of an API may be reversed. In such situations, +this document will be updated with information relevant to the decision. +However, the deprecation identifier will not be modified. + diff --git a/api-docs/7433e0e22cdab08e6aa865bcaac6673efff8936f92f4f140b75399e8682bf49d.md b/dgram/call_results.md similarity index 100% rename from api-docs/7433e0e22cdab08e6aa865bcaac6673efff8936f92f4f140b75399e8682bf49d.md rename to dgram/call_results.md diff --git a/api-docs/926de2dc5f138624cdb24aea6efd12d212894daa1c0fb7483d5314c317175c34.md b/dgram/change_to_asynchronous_socket_bind_behavior.md similarity index 100% rename from api-docs/926de2dc5f138624cdb24aea6efd12d212894daa1c0fb7483d5314c317175c34.md rename to dgram/change_to_asynchronous_socket_bind_behavior.md diff --git a/api-docs/3daef8dedeeed1dc4ae6216e5aaca8ad36995531193ac88c02f434b7f8238d43.md b/dgram/class_dgram_socket.md similarity index 100% rename from api-docs/3daef8dedeeed1dc4ae6216e5aaca8ad36995531193ac88c02f434b7f8238d43.md rename to dgram/class_dgram_socket.md diff --git a/api-docs/82644b1bf48986bc0d126eb802e0a72fb16189813a4e3da8284ab793b75040ea.md b/dgram/dgram_createsocket_options_callback.md similarity index 100% rename from api-docs/82644b1bf48986bc0d126eb802e0a72fb16189813a4e3da8284ab793b75040ea.md rename to dgram/dgram_createsocket_options_callback.md diff --git a/api-docs/bd8810233d1ec693b0bf5e925ef970dbe8dae771a208cf63bea3c7ec2b3a651e.md b/dgram/dgram_createsocket_type_callback.md similarity index 100% rename from api-docs/bd8810233d1ec693b0bf5e925ef970dbe8dae771a208cf63bea3c7ec2b3a651e.md rename to dgram/dgram_createsocket_type_callback.md diff --git a/api-docs/a852a5dd17fbc59c8326ad337e0045b9d3fa06ef76796f28df1cb8bb761f1f10.md b/dgram/dgram_module_functions.md similarity index 100% rename from api-docs/a852a5dd17fbc59c8326ad337e0045b9d3fa06ef76796f28df1cb8bb761f1f10.md rename to dgram/dgram_module_functions.md diff --git a/api-docs/3c42964b31968a09e9067ffffecdab739ed391f580b703fb2fd374195f95d5ff.md b/dgram/event_close.md similarity index 100% rename from api-docs/3c42964b31968a09e9067ffffecdab739ed391f580b703fb2fd374195f95d5ff.md rename to dgram/event_close.md diff --git a/api-docs/e30397e9d28755b6d6e2b4c8d4ed646555a5f032eddc78f99cc0799bdde1bace.md b/dgram/event_error.md similarity index 100% rename from api-docs/e30397e9d28755b6d6e2b4c8d4ed646555a5f032eddc78f99cc0799bdde1bace.md rename to dgram/event_error.md diff --git a/api-docs/49dc702492772c76afc6b193431f5d5052d139771e8ac76ffbf712af5591ea02.md b/dgram/event_listening.md similarity index 100% rename from api-docs/49dc702492772c76afc6b193431f5d5052d139771e8ac76ffbf712af5591ea02.md rename to dgram/event_listening.md diff --git a/api-docs/3fc5496e5edaffa3810cb953dd877273fb5f39b8cd8a7c610443b4979a17ff5e.md b/dgram/event_message.md similarity index 100% rename from api-docs/3fc5496e5edaffa3810cb953dd877273fb5f39b8cd8a7c610443b4979a17ff5e.md rename to dgram/event_message.md diff --git a/api-docs/3e85f5bf87661bc01c845375c77dcf216f09d916479c295b4cf472c647316165.md b/dgram/example_ipv4_outgoing_multicast_interface.md similarity index 100% rename from api-docs/3e85f5bf87661bc01c845375c77dcf216f09d916479c295b4cf472c647316165.md rename to dgram/example_ipv4_outgoing_multicast_interface.md diff --git a/api-docs/58f3a82a717a760ca945e3db0a663583e4b89ec1f2b97f8e637caf8bc891a8c7.md b/dgram/examples_ipv6_outgoing_multicast_interface.md similarity index 100% rename from api-docs/58f3a82a717a760ca945e3db0a663583e4b89ec1f2b97f8e637caf8bc891a8c7.md rename to dgram/examples_ipv6_outgoing_multicast_interface.md diff --git a/api-docs/700bdf8be73e8fcb079a79896e44fabd2f8b205d5e24755964f9af4b2c872139.md b/dgram/socket_addmembership_multicastaddress_multicastinterface.md similarity index 100% rename from api-docs/700bdf8be73e8fcb079a79896e44fabd2f8b205d5e24755964f9af4b2c872139.md rename to dgram/socket_addmembership_multicastaddress_multicastinterface.md diff --git a/api-docs/ad9a747e23eb367cc8d27c728200dac0eddc12aa5612a754beed511975f81b2b.md b/dgram/socket_address.md similarity index 100% rename from api-docs/ad9a747e23eb367cc8d27c728200dac0eddc12aa5612a754beed511975f81b2b.md rename to dgram/socket_address.md diff --git a/api-docs/61b1b4f48182b80b798ffe8d7aa6c60713e3dfb3130f3d75c5338ada0fcee84f.md b/dgram/socket_bind_options_callback.md similarity index 100% rename from api-docs/61b1b4f48182b80b798ffe8d7aa6c60713e3dfb3130f3d75c5338ada0fcee84f.md rename to dgram/socket_bind_options_callback.md diff --git a/api-docs/0469e0ffd3440131a40724d5163963bc16483bf5a8bff83ee9df1b70f46e5d4e.md b/dgram/socket_bind_port_address_callback.md similarity index 100% rename from api-docs/0469e0ffd3440131a40724d5163963bc16483bf5a8bff83ee9df1b70f46e5d4e.md rename to dgram/socket_bind_port_address_callback.md diff --git a/api-docs/f1dfeae5794e5485a17304813694d88be3a237bf33b77e47e0c72434087d21f8.md b/dgram/socket_close_callback.md similarity index 100% rename from api-docs/f1dfeae5794e5485a17304813694d88be3a237bf33b77e47e0c72434087d21f8.md rename to dgram/socket_close_callback.md diff --git a/api-docs/e82777c6be51e73fc2683446b38a945b45f4866021dbf1bed0f143b041651182.md b/dgram/socket_dropmembership_multicastaddress_multicastinterface.md similarity index 100% rename from api-docs/e82777c6be51e73fc2683446b38a945b45f4866021dbf1bed0f143b041651182.md rename to dgram/socket_dropmembership_multicastaddress_multicastinterface.md diff --git a/api-docs/fe77791b78ab0a9026d6dc4db20e3c362ee4fe3aa13b2ff4b8cbad2e722f2750.md b/dgram/socket_getrecvbuffersize.md similarity index 100% rename from api-docs/fe77791b78ab0a9026d6dc4db20e3c362ee4fe3aa13b2ff4b8cbad2e722f2750.md rename to dgram/socket_getrecvbuffersize.md diff --git a/api-docs/efaf15c55d1e01cbaeb618efc2c3c27dc7f239ac56f7d62321f45003d8eee463.md b/dgram/socket_getsendbuffersize.md similarity index 100% rename from api-docs/efaf15c55d1e01cbaeb618efc2c3c27dc7f239ac56f7d62321f45003d8eee463.md rename to dgram/socket_getsendbuffersize.md diff --git a/api-docs/9f119808d0a41ee6edb0a585c8da2ef0cb584b4b1e3962af925e7354f421ad59.md b/dgram/socket_ref.md similarity index 100% rename from api-docs/9f119808d0a41ee6edb0a585c8da2ef0cb584b4b1e3962af925e7354f421ad59.md rename to dgram/socket_ref.md diff --git a/api-docs/7dbd05481949111c3dadbe3e76ee424b7f0897e8f46fb66b6bb60ac3e1385fc3.md b/dgram/socket_send_msg_offset_length_port_address_callback.md similarity index 100% rename from api-docs/7dbd05481949111c3dadbe3e76ee424b7f0897e8f46fb66b6bb60ac3e1385fc3.md rename to dgram/socket_send_msg_offset_length_port_address_callback.md diff --git a/api-docs/80f637686c36fc25bd946123311a92b2db7bb6e60d219b6a6ce1fe8ffccfdd9f.md b/dgram/socket_setbroadcast_flag.md similarity index 100% rename from api-docs/80f637686c36fc25bd946123311a92b2db7bb6e60d219b6a6ce1fe8ffccfdd9f.md rename to dgram/socket_setbroadcast_flag.md diff --git a/api-docs/8f8d2e8c6793296d87a66ab210f3fc80898d956d7b6db6b6af0906ece8d1333e.md b/dgram/socket_setmulticastinterface_multicastinterface.md similarity index 100% rename from api-docs/8f8d2e8c6793296d87a66ab210f3fc80898d956d7b6db6b6af0906ece8d1333e.md rename to dgram/socket_setmulticastinterface_multicastinterface.md diff --git a/api-docs/eac7801caf85bc798fb0f7a5e40a5a55e8f2986622d0fa96b42546d38edab77f.md b/dgram/socket_setmulticastloopback_flag.md similarity index 100% rename from api-docs/eac7801caf85bc798fb0f7a5e40a5a55e8f2986622d0fa96b42546d38edab77f.md rename to dgram/socket_setmulticastloopback_flag.md diff --git a/api-docs/512e3f62d7c658b486cf1592e0fc571d1e8760ce35d41888749fe61a9278f430.md b/dgram/socket_setmulticastttl_ttl.md similarity index 100% rename from api-docs/512e3f62d7c658b486cf1592e0fc571d1e8760ce35d41888749fe61a9278f430.md rename to dgram/socket_setmulticastttl_ttl.md diff --git a/api-docs/3df239a6f1fd7d2544e9530c76fc117766a350a4bd71143fc752222ab1309617.md b/dgram/socket_setrecvbuffersize_size.md similarity index 100% rename from api-docs/3df239a6f1fd7d2544e9530c76fc117766a350a4bd71143fc752222ab1309617.md rename to dgram/socket_setrecvbuffersize_size.md diff --git a/api-docs/661961f04077716d49ab187c099062c0a84980d0a7b3efc257193ee96a1ab870.md b/dgram/socket_setsendbuffersize_size.md similarity index 100% rename from api-docs/661961f04077716d49ab187c099062c0a84980d0a7b3efc257193ee96a1ab870.md rename to dgram/socket_setsendbuffersize_size.md diff --git a/api-docs/bba489a6f210752a98d3d8350d032a820460d13c1ca81b0e86ab73f53f3834cb.md b/dgram/socket_setttl_ttl.md similarity index 100% rename from api-docs/bba489a6f210752a98d3d8350d032a820460d13c1ca81b0e86ab73f53f3834cb.md rename to dgram/socket_setttl_ttl.md diff --git a/api-docs/bdcae0ab931ed393745628d36b4505260a28eeda5849e1081fdf0e33268f336c.md b/dgram/socket_unref.md similarity index 100% rename from api-docs/bdcae0ab931ed393745628d36b4505260a28eeda5849e1081fdf0e33268f336c.md rename to dgram/socket_unref.md diff --git a/api-docs/e6b9ecd7f748a4ddfe93f303ebbf9ec9c05148c9117f277b2d17b4122d9e7360.md b/dgram/udp_datagram_sockets.md similarity index 100% rename from api-docs/e6b9ecd7f748a4ddfe93f303ebbf9ec9c05148c9117f277b2d17b4122d9e7360.md rename to dgram/udp_datagram_sockets.md diff --git a/api-docs/475ec1ce7baf16ed112c4fcd5da5b9b8c58d3e220d0ec60330a6f0fb6e7d1f79.md b/dns/class_dns_resolver.md similarity index 100% rename from api-docs/475ec1ce7baf16ed112c4fcd5da5b9b8c58d3e220d0ec60330a6f0fb6e7d1f79.md rename to dns/class_dns_resolver.md diff --git a/dns/class_dnspromises_resolver.md b/dns/class_dnspromises_resolver.md new file mode 100644 index 00000000..b32121e8 --- /dev/null +++ b/dns/class_dnspromises_resolver.md @@ -0,0 +1,45 @@ + + +An independent resolver for DNS requests. + +Note that creating a new resolver uses the default server settings. Setting +the servers used for a resolver using +[`resolver.setServers()`][`dnsPromises.setServers()`] does not affect +other resolvers: + +```js +const { Resolver } = require('dns').promises; +const resolver = new Resolver(); +resolver.setServers(['4.4.4.4']); + +// This request will use the server at 4.4.4.4, independent of global settings. +resolver.resolve4('example.org').then((addresses) => { + // ... +}); + +// Alternatively, the same code can be written using async-await style. +(async function() { + const addresses = await resolver.resolve4('example.org'); +})(); +``` + +The following methods from the `dnsPromises` API are available: + +* [`resolver.getServers()`][`dnsPromises.getServers()`] +* [`resolver.resolve()`][`dnsPromises.resolve()`] +* [`resolver.resolve4()`][`dnsPromises.resolve4()`] +* [`resolver.resolve6()`][`dnsPromises.resolve6()`] +* [`resolver.resolveAny()`][`dnsPromises.resolveAny()`] +* [`resolver.resolveCname()`][`dnsPromises.resolveCname()`] +* [`resolver.resolveMx()`][`dnsPromises.resolveMx()`] +* [`resolver.resolveNaptr()`][`dnsPromises.resolveNaptr()`] +* [`resolver.resolveNs()`][`dnsPromises.resolveNs()`] +* [`resolver.resolvePtr()`][`dnsPromises.resolvePtr()`] +* [`resolver.resolveSoa()`][`dnsPromises.resolveSoa()`] +* [`resolver.resolveSrv()`][`dnsPromises.resolveSrv()`] +* [`resolver.resolveTxt()`][`dnsPromises.resolveTxt()`] +* [`resolver.reverse()`][`dnsPromises.reverse()`] +* [`resolver.setServers()`][`dnsPromises.setServers()`] + diff --git a/api-docs/c1efd9ee05314ad66cefd3fa00c2fefa153c771cbdddd85283d92f0b24236b7f.md b/dns/dns.md similarity index 100% rename from api-docs/c1efd9ee05314ad66cefd3fa00c2fefa153c771cbdddd85283d92f0b24236b7f.md rename to dns/dns.md diff --git a/api-docs/cb6075c462ca244f79d77a3295185db4deeee848c560d9916cb4a00d2b2b2913.md b/dns/dns_getservers.md similarity index 100% rename from api-docs/cb6075c462ca244f79d77a3295185db4deeee848c560d9916cb4a00d2b2b2913.md rename to dns/dns_getservers.md diff --git a/api-docs/df3734a974a56fe584d776cf009b775c20897e813eb442d85ffc8ce9080de3b2.md b/dns/dns_lookup.md similarity index 100% rename from api-docs/df3734a974a56fe584d776cf009b775c20897e813eb442d85ffc8ce9080de3b2.md rename to dns/dns_lookup.md diff --git a/api-docs/07e20d042e25dd519e7a450a2d4ca27250cc4ae41a91c2243829cdc9f865252d.md b/dns/dns_lookup_hostname_options_callback.md similarity index 100% rename from api-docs/07e20d042e25dd519e7a450a2d4ca27250cc4ae41a91c2243829cdc9f865252d.md rename to dns/dns_lookup_hostname_options_callback.md diff --git a/api-docs/e173b8d7130d81565ea460e53e7288260787156f7b1a951c0a22f6a7f159fd91.md b/dns/dns_lookupservice_address_port_callback.md similarity index 100% rename from api-docs/e173b8d7130d81565ea460e53e7288260787156f7b1a951c0a22f6a7f159fd91.md rename to dns/dns_lookupservice_address_port_callback.md diff --git a/dns/dns_promises_api.md b/dns/dns_promises_api.md new file mode 100644 index 00000000..6d8944f4 --- /dev/null +++ b/dns/dns_promises_api.md @@ -0,0 +1,7 @@ + +> Stability: 1 - Experimental + +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`. + diff --git a/api-docs/84c7920e6d5220dc920a89a59d5bbe18c2ebe916c76a6361604b625bdb012069.md b/dns/dns_resolve4_hostname_options_callback.md similarity index 100% rename from api-docs/84c7920e6d5220dc920a89a59d5bbe18c2ebe916c76a6361604b625bdb012069.md rename to dns/dns_resolve4_hostname_options_callback.md diff --git a/api-docs/2865824d268a25f5cb1bd0cab25147d8d27361dcd3bbb49950f8e374709b66d0.md b/dns/dns_resolve6_hostname_options_callback.md similarity index 100% rename from api-docs/2865824d268a25f5cb1bd0cab25147d8d27361dcd3bbb49950f8e374709b66d0.md rename to dns/dns_resolve6_hostname_options_callback.md diff --git a/api-docs/f56a4d011ede578cec171a901c244d368bcd2babad01c96e5e3df796fdad6cce.md b/dns/dns_resolve_dns_resolve_and_dns_reverse.md similarity index 100% rename from api-docs/f56a4d011ede578cec171a901c244d368bcd2babad01c96e5e3df796fdad6cce.md rename to dns/dns_resolve_dns_resolve_and_dns_reverse.md diff --git a/api-docs/ba170938f3eecc9b9d1a6668ac3f1418f3a2bd670c9617fe4ba20ec2ad93973f.md b/dns/dns_resolve_hostname_rrtype_callback.md similarity index 100% rename from api-docs/ba170938f3eecc9b9d1a6668ac3f1418f3a2bd670c9617fe4ba20ec2ad93973f.md rename to dns/dns_resolve_hostname_rrtype_callback.md diff --git a/api-docs/f8861f5fc552c10899d078299a366dbe17cf0988ccc29a61ed79c54d8f6d7ab5.md b/dns/dns_resolveany_hostname_callback.md similarity index 100% rename from api-docs/f8861f5fc552c10899d078299a366dbe17cf0988ccc29a61ed79c54d8f6d7ab5.md rename to dns/dns_resolveany_hostname_callback.md diff --git a/api-docs/7973b9a0a62b9b445e1eaeaa17a9373daec208324280ce07056e118993218c98.md b/dns/dns_resolvecname_hostname_callback.md similarity index 100% rename from api-docs/7973b9a0a62b9b445e1eaeaa17a9373daec208324280ce07056e118993218c98.md rename to dns/dns_resolvecname_hostname_callback.md diff --git a/api-docs/33a3b8c1ccef0a1613909436e32327dc9a854a7656aac7851c84ea3568ed424e.md b/dns/dns_resolvemx_hostname_callback.md similarity index 100% rename from api-docs/33a3b8c1ccef0a1613909436e32327dc9a854a7656aac7851c84ea3568ed424e.md rename to dns/dns_resolvemx_hostname_callback.md diff --git a/api-docs/fec25975314cb2505dc53ae71aa05873428e1d515d1881cc8180b55dec109a2e.md b/dns/dns_resolvenaptr_hostname_callback.md similarity index 100% rename from api-docs/fec25975314cb2505dc53ae71aa05873428e1d515d1881cc8180b55dec109a2e.md rename to dns/dns_resolvenaptr_hostname_callback.md diff --git a/api-docs/d251de7eb24643e9d7b71c7c6cfc064317b317eda0f2c36fb49c57d3b8db16c3.md b/dns/dns_resolvens_hostname_callback.md similarity index 100% rename from api-docs/d251de7eb24643e9d7b71c7c6cfc064317b317eda0f2c36fb49c57d3b8db16c3.md rename to dns/dns_resolvens_hostname_callback.md diff --git a/api-docs/86d072bf14dd29abd20e872f4c4e502ceb1fb2a6a4744eca793e54bb7eeef2a7.md b/dns/dns_resolveptr_hostname_callback.md similarity index 100% rename from api-docs/86d072bf14dd29abd20e872f4c4e502ceb1fb2a6a4744eca793e54bb7eeef2a7.md rename to dns/dns_resolveptr_hostname_callback.md diff --git a/api-docs/2bcb81aefe4803b198ec3c9f1d921253ad16af43eca490bb9c98d7ecb792ab0c.md b/dns/dns_resolvesoa_hostname_callback.md similarity index 100% rename from api-docs/2bcb81aefe4803b198ec3c9f1d921253ad16af43eca490bb9c98d7ecb792ab0c.md rename to dns/dns_resolvesoa_hostname_callback.md diff --git a/api-docs/70fef12c3f4d91b9ac3df0548cdec25a7bb4005a853f57c9fcfd7455d101b6fd.md b/dns/dns_resolvesrv_hostname_callback.md similarity index 100% rename from api-docs/70fef12c3f4d91b9ac3df0548cdec25a7bb4005a853f57c9fcfd7455d101b6fd.md rename to dns/dns_resolvesrv_hostname_callback.md diff --git a/api-docs/0b5a5a369fe8ae0c4bc34d0a3316e1482d1e1c6d73e3facf5192299f5c576bbc.md b/dns/dns_resolvetxt_hostname_callback.md similarity index 100% rename from api-docs/0b5a5a369fe8ae0c4bc34d0a3316e1482d1e1c6d73e3facf5192299f5c576bbc.md rename to dns/dns_resolvetxt_hostname_callback.md diff --git a/api-docs/f854c021a84181807378f7e8e9199bfa2faea8c8fde8e19a14196e90827afada.md b/dns/dns_reverse_ip_callback.md similarity index 100% rename from api-docs/f854c021a84181807378f7e8e9199bfa2faea8c8fde8e19a14196e90827afada.md rename to dns/dns_reverse_ip_callback.md diff --git a/api-docs/eda1a1a45d55fb21f917e75b58bf0e5e034233848b91fa274ebd41fcab343574.md b/dns/dns_setservers_servers.md similarity index 100% rename from api-docs/eda1a1a45d55fb21f917e75b58bf0e5e034233848b91fa274ebd41fcab343574.md rename to dns/dns_setservers_servers.md diff --git a/dns/dnspromises_getservers.md b/dns/dnspromises_getservers.md new file mode 100644 index 00000000..0fd48aec --- /dev/null +++ b/dns/dnspromises_getservers.md @@ -0,0 +1,20 @@ + + +* Returns: {string[]} + +Returns an array of IP address strings, formatted according to [rfc5952][], +that are currently configured for DNS resolution. A string will include a port +section if a custom port is used. + + +```js +[ + '4.4.4.4', + '2001:4860:4860::8888', + '4.4.4.4:1053', + '[2001:4860:4860::8888]:1053' +] +``` + diff --git a/dns/dnspromises_lookup_hostname_options.md b/dns/dnspromises_lookup_hostname_options.md new file mode 100644 index 00000000..62b544d9 --- /dev/null +++ b/dns/dnspromises_lookup_hostname_options.md @@ -0,0 +1,62 @@ + +* `hostname` {string} +* `options` {integer | Object} + - `family` {integer} The record family. Must be `4` or `6`. IPv4 + and IPv6 addresses are both returned by default. + - `hints` {number} One or more [supported `getaddrinfo` flags][]. Multiple + flags may be passed by bitwise `OR`ing their values. + - `all` {boolean} When `true`, the `Promise` is resolved with all addresses in + an array. Otherwise, returns a single address. **Default:** `false`. + - `verbatim` {boolean} When `true`, the `Promise` is resolved with IPv4 and + IPv6 addresses in the order the DNS resolver returned them. When `false`, + IPv4 addresses are placed before IPv6 addresses. + **Default:** currently `false` (addresses are reordered) but this is + 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 +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. + +With the `all` option set to `true`, the `Promise` is resolved with `addresses` +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 `'ENOENT'` not only when +the hostname 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 +protocol. The implementation uses an operating system facility that can +associate names with addresses, and vice versa. This implementation can have +subtle but important consequences on the behavior of any Node.js program. Please +take some time to consult the [Implementation considerations section][] before +using `dnsPromises.lookup()`. + +Example usage: + +```js +const dns = require('dns'); +const dnsPromises = dns.promises; +const options = { + family: 6, + hints: dns.ADDRCONFIG | dns.V4MAPPED, +}; + +dnsPromises.lookup('example.com', options).then((result) => { + console.log('address: %j family: IPv%s', result.address, result.family); + // address: "2606:2800:220:1:248:1893:25c8:1946" family: IPv6 +}); + +// When options.all is true, the result will be an Array. +options.all = true; +dnsPromises.lookup('example.com', options).then((result) => { + console.log('addresses: %j', result); + // addresses: [{"address":"2606:2800:220:1:248:1893:25c8:1946","family":6}] +}); +``` + diff --git a/dns/dnspromises_lookupservice_address_port.md b/dns/dnspromises_lookupservice_address_port.md new file mode 100644 index 00000000..a6b834ce --- /dev/null +++ b/dns/dnspromises_lookupservice_address_port.md @@ -0,0 +1,24 @@ + +* `address` {string} +* `port` {number} + +Resolves the given `address` and `port` into a hostname and service using +the operating system's underlying `getnameinfo` implementation. + +If `address` is not a valid IP address, a `TypeError` will be thrown. +The `port` will be coerced to a number. If it is not a legal port, a `TypeError` +will be thrown. + +On error, the `Promise` is rejected with an [`Error`][] object, where `err.code` +is the error code. + +```js +const dnsPromises = require('dns').promises; +dnsPromises.lookupService('127.0.0.1', 22).then((result) => { + console.log(result.hostname, result.service); + // Prints: localhost ssh +}); +``` + diff --git a/dns/dnspromises_resolve4_hostname_options.md b/dns/dnspromises_resolve4_hostname_options.md new file mode 100644 index 00000000..c1578011 --- /dev/null +++ b/dns/dnspromises_resolve4_hostname_options.md @@ -0,0 +1,14 @@ + +* `hostname` {string} Hostname 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 + `{ address: '1.2.3.4', ttl: 60 }` objects rather than an array of strings, + with the TTL expressed in seconds. + +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']`). + diff --git a/dns/dnspromises_resolve6_hostname_options.md b/dns/dnspromises_resolve6_hostname_options.md new file mode 100644 index 00000000..6563c55c --- /dev/null +++ b/dns/dnspromises_resolve6_hostname_options.md @@ -0,0 +1,14 @@ + +* `hostname` {string} Hostname 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 + `{ address: '0:1:2:3:4:5:6:7', ttl: 60 }` objects rather than an array of + strings, with the TTL expressed in seconds. + +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. + diff --git a/dns/dnspromises_resolve_hostname_rrtype.md b/dns/dnspromises_resolve_hostname_rrtype.md new file mode 100644 index 00000000..8cad5af3 --- /dev/null +++ b/dns/dnspromises_resolve_hostname_rrtype.md @@ -0,0 +1,28 @@ + +* `hostname` {string} Hostname to resolve. +* `rrtype` {string} Resource record type. **Default:** `'A'`. + +Uses the DNS protocol to resolve a hostname (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`: + +| `rrtype` | `records` contains | Result type | Shorthand method | +|-----------|--------------------------------|-------------|--------------------------| +| `'A'` | IPv4 addresses (default) | {string} | [`dnsPromises.resolve4()`][] | +| `'AAAA'` | IPv6 addresses | {string} | [`dnsPromises.resolve6()`][] | +| `'ANY'` | any records | {Object} | [`dnsPromises.resolveAny()`][] | +| `'CNAME'` | canonical name records | {string} | [`dnsPromises.resolveCname()`][] | +| `'MX'` | mail exchange records | {Object} | [`dnsPromises.resolveMx()`][] | +| `'NAPTR'` | name authority pointer records | {Object} | [`dnsPromises.resolveNaptr()`][] | +| `'NS'` | name server records | {string} | [`dnsPromises.resolveNs()`][] | +| `'PTR'` | pointer records | {string} | [`dnsPromises.resolvePtr()`][] | +| `'SOA'` | start of authority records | {Object} | [`dnsPromises.resolveSoa()`][] | +| `'SRV'` | service records | {Object} | [`dnsPromises.resolveSrv()`][] | +| `'TXT'` | text records | {string[]} | [`dnsPromises.resolveTxt()`][] | + +On error, the `Promise` is rejected with an [`Error`][] object, where `err.code` +is one of the [DNS error codes](#dns_error_codes). + diff --git a/dns/dnspromises_resolveany_hostname.md b/dns/dnspromises_resolveany_hostname.md new file mode 100644 index 00000000..5a6550f1 --- /dev/null +++ b/dns/dnspromises_resolveany_hostname.md @@ -0,0 +1,43 @@ + +* `hostname` {string} + +Uses the DNS protocol to resolve all records (also known as `ANY` or `*` query). +On success, the `Promise` is resolved with an array containing various types of +records. Each object has a property `type` that indicates the type of the +current record. And depending on the `type`, additional properties will be +present on the object: + +| Type | Properties | +|------|------------| +| `'A'` | `address`/`ttl` | +| `'AAAA'` | `address`/`ttl` | +| `'CNAME'` | `value` | +| `'MX'` | Refer to [`dnsPromises.resolveMx()`][] | +| `'NAPTR'` | Refer to [`dnsPromises.resolveNaptr()`][] | +| `'NS'` | `value` | +| `'PTR'` | `value` | +| `'SOA'` | Refer to [`dnsPromises.resolveSoa()`][] | +| `'SRV'` | Refer to [`dnsPromises.resolveSrv()`][] | +| `'TXT'` | This type of record contains an array property called `entries` which refers to [`dnsPromises.resolveTxt()`][], e.g. `{ entries: ['...'], type: 'TXT' }` | + +Here is an example of the result object: + + +```js +[ { type: 'A', address: '127.0.0.1', ttl: 299 }, + { type: 'CNAME', value: 'example.com' }, + { type: 'MX', exchange: 'alt4.aspmx.l.example.com', priority: 50 }, + { type: 'NS', value: 'ns1.example.com' }, + { type: 'TXT', entries: [ 'v=spf1 include:_spf.example.com ~all' ] }, + { type: 'SOA', + nsname: 'ns1.example.com', + hostmaster: 'admin.example.com', + serial: 156696742, + refresh: 900, + retry: 900, + expire: 1800, + minttl: 60 } ] +``` + diff --git a/dns/dnspromises_resolvecname_hostname.md b/dns/dnspromises_resolvecname_hostname.md new file mode 100644 index 00000000..c354d2b2 --- /dev/null +++ b/dns/dnspromises_resolvecname_hostname.md @@ -0,0 +1,9 @@ + +* `hostname` {string} + +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']`). + diff --git a/dns/dnspromises_resolvemx_hostname.md b/dns/dnspromises_resolvemx_hostname.md new file mode 100644 index 00000000..51bbd2e8 --- /dev/null +++ b/dns/dnspromises_resolvemx_hostname.md @@ -0,0 +1,10 @@ + +* `hostname` {string} + +Uses the DNS protocol to resolve mail exchange records (`MX` records) for the +`hostname`. On success, the `Promise` is resolved with an array of objects +containing both a `priority` and `exchange` property (e.g. +`[{priority: 10, exchange: 'mx.example.com'}, ...]`). + diff --git a/dns/dnspromises_resolvenaptr_hostname.md b/dns/dnspromises_resolvenaptr_hostname.md new file mode 100644 index 00000000..ad188f6e --- /dev/null +++ b/dns/dnspromises_resolvenaptr_hostname.md @@ -0,0 +1,28 @@ + +* `hostname` {string} + +Uses the DNS protocol to resolve regular expression based records (`NAPTR` +records) for the `hostname`. On success, the `Promise` is resolved with an array +of objects with the following properties: + +* `flags` +* `service` +* `regexp` +* `replacement` +* `order` +* `preference` + + +```js +{ + flags: 's', + service: 'SIP+D2U', + regexp: '', + replacement: '_sip._udp.example.com', + order: 30, + preference: 100 +} +``` + diff --git a/dns/dnspromises_resolvens_hostname.md b/dns/dnspromises_resolvens_hostname.md new file mode 100644 index 00000000..8ad63d66 --- /dev/null +++ b/dns/dnspromises_resolvens_hostname.md @@ -0,0 +1,10 @@ + +* `hostname` {string} + +Uses the DNS protocol to resolve name server records (`NS` records) for the +`hostname`. On success, the `Promise` is resolved with an array of name server +records available for `hostname` (e.g. +`['ns1.example.com', 'ns2.example.com']`). + diff --git a/dns/dnspromises_resolveptr_hostname.md b/dns/dnspromises_resolveptr_hostname.md new file mode 100644 index 00000000..0b498660 --- /dev/null +++ b/dns/dnspromises_resolveptr_hostname.md @@ -0,0 +1,9 @@ + +* `hostname` {string} + +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. + diff --git a/dns/dnspromises_resolvesoa_hostname.md b/dns/dnspromises_resolvesoa_hostname.md new file mode 100644 index 00000000..b87d1c98 --- /dev/null +++ b/dns/dnspromises_resolvesoa_hostname.md @@ -0,0 +1,30 @@ + +* `hostname` {string} + +Uses the DNS protocol to resolve a start of authority record (`SOA` record) for +the `hostname`. On success, the `Promise` is resolved with an object with the +following properties: + +* `nsname` +* `hostmaster` +* `serial` +* `refresh` +* `retry` +* `expire` +* `minttl` + + +```js +{ + nsname: 'ns.example.com', + hostmaster: 'root.example.com', + serial: 2013101809, + refresh: 10000, + retry: 2400, + expire: 604800, + minttl: 3600 +} +``` + diff --git a/dns/dnspromises_resolvesrv_hostname.md b/dns/dnspromises_resolvesrv_hostname.md new file mode 100644 index 00000000..864d2450 --- /dev/null +++ b/dns/dnspromises_resolvesrv_hostname.md @@ -0,0 +1,24 @@ + +* `hostname` {string} + +Uses the DNS protocol to resolve service records (`SRV` records) for the +`hostname`. On success, the `Promise` is resolved with an array of objects with +the following properties: + +* `priority` +* `weight` +* `port` +* `name` + + +```js +{ + priority: 10, + weight: 5, + port: 21223, + name: 'service.example.com' +} +``` + diff --git a/dns/dnspromises_resolvetxt_hostname.md b/dns/dnspromises_resolvetxt_hostname.md new file mode 100644 index 00000000..e69e5499 --- /dev/null +++ b/dns/dnspromises_resolvetxt_hostname.md @@ -0,0 +1,12 @@ + +* `hostname` {string} + +Uses the DNS protocol to resolve text queries (`TXT` records) for the +`hostname`. On success, the `Promise` is resolved with a two-dimensional array +of the text records available for `hostname` (e.g. +`[ ['v=spf1 ip4:0.0.0.0 ', '~all' ] ]`). Each sub-array contains TXT chunks of +one record. Depending on the use case, these could be either joined together or +treated separately. + diff --git a/dns/dnspromises_reverse_ip.md b/dns/dnspromises_reverse_ip.md new file mode 100644 index 00000000..b3b6c08d --- /dev/null +++ b/dns/dnspromises_reverse_ip.md @@ -0,0 +1,11 @@ + +* `ip` {string} + +Performs a reverse DNS query that resolves an IPv4 or IPv6 address to an +array of hostnames. + +On error, the `Promise` is rejected with an [`Error`][] object, where `err.code` +is one of the [DNS error codes](#dns_error_codes). + diff --git a/api-docs/6ce886c322e6a978379c901ba5435ee213f58db78a1fa5db052ec719a98b7d4b.md b/dns/dnspromises_setservers_servers.md similarity index 100% rename from api-docs/6ce886c322e6a978379c901ba5435ee213f58db78a1fa5db052ec719a98b7d4b.md rename to dns/dnspromises_setservers_servers.md diff --git a/api-docs/3581a9d09eea8bda90b57899c21127c87a762a4b6efb1b5afe00708ee46e0213.md b/dns/error_codes.md similarity index 100% rename from api-docs/3581a9d09eea8bda90b57899c21127c87a762a4b6efb1b5afe00708ee46e0213.md rename to dns/error_codes.md diff --git a/api-docs/f47ce0b71f335f41f81560b5e264562c02828177749767c25f9f96f871b38dc9.md b/dns/implementation_considerations.md similarity index 100% rename from api-docs/f47ce0b71f335f41f81560b5e264562c02828177749767c25f9f96f871b38dc9.md rename to dns/implementation_considerations.md diff --git a/api-docs/3c243209fa1e30ed754086c2f1932252f9019e799b79c5288abe5de4c555c2d2.md b/dns/resolver_cancel.md similarity index 100% rename from api-docs/3c243209fa1e30ed754086c2f1932252f9019e799b79c5288abe5de4c555c2d2.md rename to dns/resolver_cancel.md diff --git a/api-docs/ec1e168430ff744929883cc1619f5243a3fe1c7ccca9e3211c1e24a653f4ed23.md b/dns/supported_getaddrinfo_flags.md similarity index 100% rename from api-docs/ec1e168430ff744929883cc1619f5243a3fe1c7ccca9e3211c1e24a653f4ed23.md rename to dns/supported_getaddrinfo_flags.md diff --git a/api-docs/aaf91d9694f05bb366f9da6f469fdddd6fd0fab031198fd34e530bd01e3e2574.md b/documentation/about_this_documentation.md similarity index 100% rename from api-docs/aaf91d9694f05bb366f9da6f469fdddd6fd0fab031198fd34e530bd01e3e2574.md rename to documentation/about_this_documentation.md diff --git a/api-docs/0f945401d809658601f4b599d394492d15e87c1e47bf89547e86af5aca35a8fb.md b/documentation/contributing.md similarity index 100% rename from api-docs/0f945401d809658601f4b599d394492d15e87c1e47bf89547e86af5aca35a8fb.md rename to documentation/contributing.md diff --git a/documentation/json_output.md b/documentation/json_output.md new file mode 100644 index 00000000..42de3da5 --- /dev/null +++ b/documentation/json_output.md @@ -0,0 +1,7 @@ + + +Every `.html` document has a corresponding `.json` document. This is for IDEs +and other utilities that consume the documentation. + diff --git a/api-docs/69c443f975b1730d53df1bd64db91d1ac19854c7bc7138ce722b3c2e9a650e0f.md b/documentation/stability_index.md similarity index 100% rename from api-docs/69c443f975b1730d53df1bd64db91d1ac19854c7bc7138ce722b3c2e9a650e0f.md rename to documentation/stability_index.md diff --git a/api-docs/8142380729c23e5513a233cadd5cef28d9ca30cb6d694f66b14064950739a2cf.md b/documentation/syscalls_and_man_pages.md similarity index 100% rename from api-docs/8142380729c23e5513a233cadd5cef28d9ca30cb6d694f66b14064950739a2cf.md rename to documentation/syscalls_and_man_pages.md diff --git a/api-docs/8ecbb477dcd938c3d0f1ee7302e90339835ea17a0bd9646691f07191e726fee0.md b/documentation/system_calls_and_man_pages.md similarity index 100% rename from api-docs/8ecbb477dcd938c3d0f1ee7302e90339835ea17a0bd9646691f07191e726fee0.md rename to documentation/system_calls_and_man_pages.md diff --git a/domain/additions_to_error_objects.md b/domain/additions_to_error_objects.md new file mode 100644 index 00000000..6740ab69 --- /dev/null +++ b/domain/additions_to_error_objects.md @@ -0,0 +1,14 @@ + + + +Any time an `Error` object is routed through a domain, a few extra fields +are added to it. + +* `error.domain` The domain that first handled the error. +* `error.domainEmitter` The event emitter that emitted an `'error'` event + with the error object. +* `error.domainBound` The callback function which was bound to the + domain, and passed an error as its first argument. +* `error.domainThrown` A boolean indicating whether the error was + thrown, emitted, or passed to a bound callback function. + diff --git a/domain/class_domain.md b/domain/class_domain.md new file mode 100644 index 00000000..0b3fea4c --- /dev/null +++ b/domain/class_domain.md @@ -0,0 +1,7 @@ + +The `Domain` class encapsulates the functionality of routing errors and +uncaught exceptions to the active `Domain` object. + +`Domain` is a child class of [`EventEmitter`][]. To handle the errors that it +catches, listen to its `'error'` event. + diff --git a/domain/domain.md b/domain/domain.md new file mode 100644 index 00000000..87857594 --- /dev/null +++ b/domain/domain.md @@ -0,0 +1,31 @@ + + + + +> Stability: 0 - Deprecated + +**This module is pending deprecation**. Once a replacement API has been +finalized, this module will be fully deprecated. Most end users should +**not** have cause to use this module. Users who absolutely must have +the functionality that domains provide may rely on it for the time being +but should expect to have to migrate to a different solution +in the future. + +Domains provide a way to handle multiple different IO operations as a +single group. If any of the event emitters or callbacks registered to a +domain emit an `'error'` event, or throw an error, then the domain object +will be notified, rather than losing the context of the error in the +`process.on('uncaughtException')` handler, or causing the program to +exit immediately with an error code. + diff --git a/domain/domain_add_emitter.md b/domain/domain_add_emitter.md new file mode 100644 index 00000000..5ba757e2 --- /dev/null +++ b/domain/domain_add_emitter.md @@ -0,0 +1,15 @@ + +* `emitter` {EventEmitter|Timer} emitter or timer to be added to the domain + +Explicitly adds an emitter to the domain. If any event handlers called by +the emitter throw an error, or if the emitter emits an `'error'` event, it +will be routed to the domain's `'error'` event, just like with implicit +binding. + +This also works with timers that are returned from [`setInterval()`][] and +[`setTimeout()`][]. If their callback function throws, it will be caught by +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. + diff --git a/domain/domain_bind_callback.md b/domain/domain_bind_callback.md new file mode 100644 index 00000000..0fdc6204 --- /dev/null +++ b/domain/domain_bind_callback.md @@ -0,0 +1,24 @@ + +* `callback` {Function} The callback function +* Returns: {Function} The bound function + +The returned function will be a wrapper around the supplied callback +function. When the returned function is called, any errors that are +thrown will be routed to the domain's `'error'` event. + +```js +const d = domain.create(); + +function readSomeFile(filename, cb) { + fs.readFile(filename, 'utf8', d.bind((er, data) => { + // If this throws, it will also be passed to the domain. + return cb(er, data ? JSON.parse(data) : null); + })); +} + +d.on('error', (er) => { + // An error occurred somewhere. If we throw it now, it will crash the program + // with the normal line number and stack message. +}); +``` + diff --git a/domain/domain_create.md b/domain/domain_create.md new file mode 100644 index 00000000..f55d9722 --- /dev/null +++ b/domain/domain_create.md @@ -0,0 +1,3 @@ + +* Returns: {Domain} + diff --git a/domain/domain_enter.md b/domain/domain_enter.md new file mode 100644 index 00000000..a45e265c --- /dev/null +++ b/domain/domain_enter.md @@ -0,0 +1,12 @@ + +The `enter()` method is plumbing used by the `run()`, `bind()`, and +`intercept()` methods to set the active domain. It sets `domain.active` and +`process.domain` to the domain, and implicitly pushes the domain onto the domain +stack managed by the domain module (see [`domain.exit()`][] for details on the +domain stack). The call to `enter()` delimits the beginning of a chain of +asynchronous calls and I/O operations bound to a domain. + +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. + diff --git a/domain/domain_exit.md b/domain/domain_exit.md new file mode 100644 index 00000000..13c7d15e --- /dev/null +++ b/domain/domain_exit.md @@ -0,0 +1,14 @@ + +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 +asynchronous calls, it's important to ensure that the current domain is exited. +The call to `exit()` delimits either the end of or an interruption to the chain +of asynchronous calls and I/O operations bound to a domain. + +If there are multiple, nested domains bound to the current execution context, +`exit()` will exit any domains nested within this domain. + +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. + diff --git a/domain/domain_intercept_callback.md b/domain/domain_intercept_callback.md new file mode 100644 index 00000000..bb700790 --- /dev/null +++ b/domain/domain_intercept_callback.md @@ -0,0 +1,34 @@ + +* `callback` {Function} The callback function +* Returns: {Function} The intercepted function + +This method is almost identical to [`domain.bind(callback)`][]. However, in +addition to catching thrown errors, it will also intercept [`Error`][] +objects sent as the first argument to the function. + +In this way, the common `if (err) return callback(err);` pattern can be replaced +with a single error handler in a single place. + +```js +const d = domain.create(); + +function readSomeFile(filename, cb) { + fs.readFile(filename, 'utf8', d.intercept((data) => { + // Note, the first argument is never passed to the + // callback since it is assumed to be the 'Error' argument + // and thus intercepted by the domain. + + // If this throws, it will also be passed to the domain + // so the error-handling logic can be moved to the 'error' + // event on the domain instead of being repeated throughout + // the program. + return cb(null, JSON.parse(data)); + })); +} + +d.on('error', (er) => { + // An error occurred somewhere. If we throw it now, it will crash the program + // with the normal line number and stack message. +}); +``` + diff --git a/domain/domain_members.md b/domain/domain_members.md new file mode 100644 index 00000000..2c0c6472 --- /dev/null +++ b/domain/domain_members.md @@ -0,0 +1,6 @@ + +* {Array} + +An array of timers and event emitters that have been explicitly added +to the domain. + diff --git a/domain/domain_remove_emitter.md b/domain/domain_remove_emitter.md new file mode 100644 index 00000000..9f870168 --- /dev/null +++ b/domain/domain_remove_emitter.md @@ -0,0 +1,6 @@ + +* `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. + diff --git a/domain/domain_run_fn_args.md b/domain/domain_run_fn_args.md new file mode 100644 index 00000000..cd1738be --- /dev/null +++ b/domain/domain_run_fn_args.md @@ -0,0 +1,33 @@ + +* `fn` {Function} +* `...args` {any} + +Run the supplied function in the context of the domain, implicitly +binding all event emitters, timers, and lowlevel requests that are +created in that context. Optionally, arguments can be passed to +the function. + +This is the most basic way to use a domain. + +```js +const domain = require('domain'); +const fs = require('fs'); +const d = domain.create(); +d.on('error', (er) => { + console.error('Caught error!', er); +}); +d.run(() => { + process.nextTick(() => { + setTimeout(() => { // Simulating some various async stuff + fs.open('non-existent file', 'r', (er, fd) => { + if (er) throw er; + // proceed... + }); + }, 100); + }); +}); +``` + +In this example, the `d.on('error')` handler will be triggered, rather +than crashing the program. + diff --git a/api-docs/1208d4818b8a2351a534504d8684c9dae32feb53afbe9686e2601860459d0c86.md b/domain/domains_and_promises.md similarity index 78% rename from api-docs/1208d4818b8a2351a534504d8684c9dae32feb53afbe9686e2601860459d0c86.md rename to domain/domains_and_promises.md index c13d333f..c116de88 100644 --- a/api-docs/1208d4818b8a2351a534504d8684c9dae32feb53afbe9686e2601860459d0c86.md +++ b/domain/domains_and_promises.md @@ -36,9 +36,9 @@ d2.run(() => { }); ``` -Note that domains will not interfere with the error handling mechanisms for -Promises, i.e. no `'error'` event will be emitted for unhandled `Promise` -rejections. +Domains will not interfere with the error handling mechanisms for +Promises. In other words, no `'error'` event will be emitted for unhandled +`Promise` rejections. diff --git a/domain/explicit_binding.md b/domain/explicit_binding.md new file mode 100644 index 00000000..86952046 --- /dev/null +++ b/domain/explicit_binding.md @@ -0,0 +1,41 @@ + + + +Sometimes, the domain in use is not the one that ought to be used for a +specific event emitter. Or, the event emitter could have been created +in the context of one domain, but ought to instead be bound to some +other domain. + +For example, there could be one domain in use for an HTTP server, but +perhaps we would like to have a separate domain to use for each request. + +That is possible via explicit binding. + +```js +// Create a top-level domain for the server +const domain = require('domain'); +const http = require('http'); +const serverDomain = domain.create(); + +serverDomain.run(() => { + // Server is created in the scope of serverDomain + http.createServer((req, res) => { + // Req and res are also created in the scope of serverDomain + // however, we'd prefer to have a separate domain for each request. + // create it first thing, and add req and res to it. + const reqd = domain.create(); + reqd.add(req); + reqd.add(res); + reqd.on('error', (er) => { + console.error('Error', er, req.url); + try { + res.writeHead(500); + res.end('Error occurred, sorry.'); + } catch (er2) { + console.error('Error sending 500', er2, req.url); + } + }); + }).listen(1337); +}); +``` + diff --git a/domain/implicit_binding.md b/domain/implicit_binding.md new file mode 100644 index 00000000..f8c7091f --- /dev/null +++ b/domain/implicit_binding.md @@ -0,0 +1,25 @@ + + + +If domains are in use, then all **new** `EventEmitter` objects (including +Stream objects, requests, responses, etc.) will be implicitly bound to +the active domain at the time of their creation. + +Additionally, callbacks passed to lowlevel event loop requests (such as +to `fs.open()`, or other callback-taking methods) will automatically be +bound to the active domain. If they throw, then the domain will catch +the error. + +In order to prevent excessive memory usage, `Domain` objects themselves +are not implicitly added as children of the active domain. If they +were, then it would be too easy to prevent request and response objects +from being properly garbage collected. + +To nest `Domain` objects as children of a parent `Domain` they must be +explicitly added. + +Implicit binding routes thrown errors and `'error'` events to the +`Domain`'s `'error'` event, but does not register the `EventEmitter` on the +`Domain`. +Implicit binding only takes care of thrown errors and `'error'` events. + diff --git a/domain/warning_don_t_ignore_errors.md b/domain/warning_don_t_ignore_errors.md new file mode 100644 index 00000000..f8dfb1bf --- /dev/null +++ b/domain/warning_don_t_ignore_errors.md @@ -0,0 +1,153 @@ + + + +Domain error handlers are not a substitute for closing down a +process when an error occurs. + +By the very nature of how [`throw`][] works in JavaScript, there is almost +never any way to safely "pick up where it left off", without leaking +references, or creating some other sort of undefined brittle state. + +The safest way to respond to a thrown error is to shut down the +process. Of course, in a normal web server, there may be many +open connections, and it is not reasonable to abruptly shut those down +because an error was triggered by someone else. + +The better approach is to send an error response to the request that +triggered the error, while letting the others finish in their normal +time, and stop listening for new requests in that worker. + +In this way, `domain` usage goes hand-in-hand with the cluster module, +since the master process can fork a new worker when a worker +encounters an error. For Node.js programs that scale to multiple +machines, the terminating proxy or service registry can take note of +the failure, and react accordingly. + +For example, this is not a good idea: + +```js +// XXX WARNING! BAD IDEA! + +const d = require('domain').create(); +d.on('error', (er) => { + // The error won't crash the process, but what it does is worse! + // Though we've prevented abrupt process restarting, we are leaking + // resources like crazy if this ever happens. + // This is no better than process.on('uncaughtException')! + console.log(`error, but oh well ${er.message}`); +}); +d.run(() => { + require('http').createServer((req, res) => { + handleRequest(req, res); + }).listen(PORT); +}); +``` + +By using the context of a domain, and the resilience of separating our +program into multiple worker processes, we can react more +appropriately, and handle errors with much greater safety. + +```js +// Much better! + +const cluster = require('cluster'); +const PORT = +process.env.PORT || 1337; + +if (cluster.isMaster) { + // A more realistic scenario would have more than 2 workers, + // and perhaps not put the master and worker in the same file. + // + // It is also possible to get a bit fancier about logging, and + // implement whatever custom logic is needed to prevent DoS + // attacks and other bad behavior. + // + // See the options in the cluster documentation. + // + // The important thing is that the master does very little, + // increasing our resilience to unexpected errors. + + cluster.fork(); + cluster.fork(); + + cluster.on('disconnect', (worker) => { + console.error('disconnect!'); + cluster.fork(); + }); + +} else { + // the worker + // + // This is where we put our bugs! + + const domain = require('domain'); + + // See the cluster documentation for more details about using + // worker processes to serve requests. How it works, caveats, etc. + + const server = require('http').createServer((req, res) => { + const d = domain.create(); + d.on('error', (er) => { + console.error(`error ${er.stack}`); + + // We're in dangerous territory! + // By definition, something unexpected occurred, + // which we probably didn't want. + // Anything can happen now! Be very careful! + + try { + // Make sure we close down within 30 seconds + const killtimer = setTimeout(() => { + process.exit(1); + }, 30000); + // But don't keep the process open just for that! + killtimer.unref(); + + // Stop taking new requests. + server.close(); + + // Let the master know we're dead. This will trigger a + // 'disconnect' in the cluster master, and then it will fork + // a new worker. + cluster.worker.disconnect(); + + // Try to send an error to the request that triggered the problem + res.statusCode = 500; + res.setHeader('content-type', 'text/plain'); + res.end('Oops, there was a problem!\n'); + } catch (er2) { + // Oh well, not much we can do at this point. + console.error(`Error sending 500! ${er2.stack}`); + } + }); + + // Because req and res were created before this domain existed, + // we need to explicitly add them. + // See the explanation of implicit vs explicit binding below. + d.add(req); + d.add(res); + + // Now run the handler function in the domain. + d.run(() => { + handleRequest(req, res); + }); + }); + server.listen(PORT); +} + +// This part is not important. Just an example routing thing. +// Put fancy application logic here. +function handleRequest(req, res) { + switch (req.url) { + case '/error': + // We do some async stuff, and then... + setTimeout(() => { + // Whoops! + flerb.bark(); + }, timeout); + break; + default: + res.end('ok'); + } +} +``` + diff --git a/api-docs/b1a9d46f86b78c0bc51358bd5db25d21ac24a6b89399f1d235c4547d88473ad5.md b/errors/class_assertionerror.md similarity index 100% rename from api-docs/b1a9d46f86b78c0bc51358bd5db25d21ac24a6b89399f1d235c4547d88473ad5.md rename to errors/class_assertionerror.md diff --git a/api-docs/e15f7251abd7f818a9cfd5990483fa618cfe918f0433bc72e9b2335d592d4ec1.md b/errors/class_error.md similarity index 100% rename from api-docs/e15f7251abd7f818a9cfd5990483fa618cfe918f0433bc72e9b2335d592d4ec1.md rename to errors/class_error.md diff --git a/api-docs/c286a5b8c386c8719d0e0340d9d11f5ce9f91d642ca89f670b7df7300846311e.md b/errors/class_rangeerror.md similarity index 100% rename from api-docs/c286a5b8c386c8719d0e0340d9d11f5ce9f91d642ca89f670b7df7300846311e.md rename to errors/class_rangeerror.md diff --git a/api-docs/2d6ce4f198a2d062d087ff07bf3a77949d30ec580a34dca94bdb393c5191084b.md b/errors/class_referenceerror.md similarity index 100% rename from api-docs/2d6ce4f198a2d062d087ff07bf3a77949d30ec580a34dca94bdb393c5191084b.md rename to errors/class_referenceerror.md diff --git a/api-docs/5c9aa6f8b7adc1f5b4a0bd55519308c01db742b64a14ff472825c3342456d116.md b/errors/class_syntaxerror.md similarity index 100% rename from api-docs/5c9aa6f8b7adc1f5b4a0bd55519308c01db742b64a14ff472825c3342456d116.md rename to errors/class_syntaxerror.md diff --git a/api-docs/ca1cdc83458ec6580339003e8188a85b243a5c772e90fe8e86b0cf8e6eef82aa.md b/errors/class_systemerror.md similarity index 100% rename from api-docs/ca1cdc83458ec6580339003e8188a85b243a5c772e90fe8e86b0cf8e6eef82aa.md rename to errors/class_systemerror.md diff --git a/api-docs/5f12e4e4376c1e0570da072639859b2aa53798393b92ae25610caf081ae22a21.md b/errors/class_typeerror.md similarity index 100% rename from api-docs/5f12e4e4376c1e0570da072639859b2aa53798393b92ae25610caf081ae22a21.md rename to errors/class_typeerror.md diff --git a/api-docs/e1af299a9465d5c892ca9877480820f1b381d2b82275d19fd50bee8b83cbb82a.md b/errors/common_system_errors.md similarity index 100% rename from api-docs/e1af299a9465d5c892ca9877480820f1b381d2b82275d19fd50bee8b83cbb82a.md rename to errors/common_system_errors.md diff --git a/api-docs/91c7b02df856d87b8ea944414d02ed641ec545036fc8ac643634519006bb6d56.md b/errors/err_ambiguous_argument.md similarity index 100% rename from api-docs/91c7b02df856d87b8ea944414d02ed641ec545036fc8ac643634519006bb6d56.md rename to errors/err_ambiguous_argument.md diff --git a/api-docs/d0341161535007f1e8629c85ab48d01060367b534bf635a4c1ad04d315bac585.md b/errors/err_arg_not_iterable.md similarity index 100% rename from api-docs/d0341161535007f1e8629c85ab48d01060367b534bf635a4c1ad04d315bac585.md rename to errors/err_arg_not_iterable.md diff --git a/api-docs/19ee3b8c0b697fd60a6bce86fd356c3ecf9d803b1766691fc7a0d6eaed83a123.md b/errors/err_assertion.md similarity index 100% rename from api-docs/19ee3b8c0b697fd60a6bce86fd356c3ecf9d803b1766691fc7a0d6eaed83a123.md rename to errors/err_assertion.md diff --git a/api-docs/7cc3f012697118d38aa96b425b72aa10e9c76f29c06496a6f8f6c09875e9306c.md b/errors/err_async_callback.md similarity index 100% rename from api-docs/7cc3f012697118d38aa96b425b72aa10e9c76f29c06496a6f8f6c09875e9306c.md rename to errors/err_async_callback.md diff --git a/api-docs/acec9df681a25c71e987998be3972f12930a7ebf0b7d02d9521e5badfc99892c.md b/errors/err_async_type.md similarity index 100% rename from api-docs/acec9df681a25c71e987998be3972f12930a7ebf0b7d02d9521e5badfc99892c.md rename to errors/err_async_type.md diff --git a/api-docs/ca51a09c00269ab1d94385fb4089892c7b406a4cdf325e8846b8f78292893051.md b/errors/err_brotli_compression_failed.md similarity index 100% rename from api-docs/ca51a09c00269ab1d94385fb4089892c7b406a4cdf325e8846b8f78292893051.md rename to errors/err_brotli_compression_failed.md diff --git a/api-docs/ce9193b7f5f73a21f7eade89eaaf5f3164bb6b75965c02a99ac8afb6be6d2646.md b/errors/err_brotli_invalid_param.md similarity index 100% rename from api-docs/ce9193b7f5f73a21f7eade89eaaf5f3164bb6b75965c02a99ac8afb6be6d2646.md rename to errors/err_brotli_invalid_param.md diff --git a/api-docs/7657cef5715156ed8119df664f77ba8e6d693e38ac1a8787d32bb61fc0b9b7c3.md b/errors/err_buffer_out_of_bounds.md similarity index 100% rename from api-docs/7657cef5715156ed8119df664f77ba8e6d693e38ac1a8787d32bb61fc0b9b7c3.md rename to errors/err_buffer_out_of_bounds.md diff --git a/api-docs/4e7473b18be4b49b7b7a395e1a0d4a99e24c3358786b03adcc582f8377b70c45.md b/errors/err_buffer_too_large.md similarity index 100% rename from api-docs/4e7473b18be4b49b7b7a395e1a0d4a99e24c3358786b03adcc582f8377b70c45.md rename to errors/err_buffer_too_large.md diff --git a/api-docs/babd3de78232967f8000d896d1cc81b62ce36816d5b37de48f4d8970cd5da810.md b/errors/err_cannot_transfer_object.md similarity index 100% rename from api-docs/babd3de78232967f8000d896d1cc81b62ce36816d5b37de48f4d8970cd5da810.md rename to errors/err_cannot_transfer_object.md diff --git a/api-docs/ecceea48acf32c49e949160d79a9b3fc74d661c0a49b577785fde22302d0319f.md b/errors/err_cannot_watch_sigint.md similarity index 100% rename from api-docs/ecceea48acf32c49e949160d79a9b3fc74d661c0a49b577785fde22302d0319f.md rename to errors/err_cannot_watch_sigint.md diff --git a/api-docs/d67fd0fb4683a7ef1ec2c02b2e958b01f256043f4e491c8ad3e862dbbaadf716.md b/errors/err_child_closed_before_reply.md similarity index 100% rename from api-docs/d67fd0fb4683a7ef1ec2c02b2e958b01f256043f4e491c8ad3e862dbbaadf716.md rename to errors/err_child_closed_before_reply.md diff --git a/api-docs/d53a52c12781c29056fef5ceff79b32f11980c0953d04af59212da69c52cb51a.md b/errors/err_child_process_ipc_required.md similarity index 100% rename from api-docs/d53a52c12781c29056fef5ceff79b32f11980c0953d04af59212da69c52cb51a.md rename to errors/err_child_process_ipc_required.md diff --git a/api-docs/63077abfcea3cdaaec846fc75766cc6f97bcb5f6e8ba079032d0818aa0688ff1.md b/errors/err_child_process_stdio_maxbuffer.md similarity index 100% rename from api-docs/63077abfcea3cdaaec846fc75766cc6f97bcb5f6e8ba079032d0818aa0688ff1.md rename to errors/err_child_process_stdio_maxbuffer.md diff --git a/api-docs/cf25bc8574f16e81e08c075cb39f64864a5c456b29196262f3380a586ac21ad8.md b/errors/err_closed_message_port.md similarity index 100% rename from api-docs/cf25bc8574f16e81e08c075cb39f64864a5c456b29196262f3380a586ac21ad8.md rename to errors/err_closed_message_port.md diff --git a/api-docs/f065ebb39a4a8d033077c1719ef5eb70ab06506561f3747a6cca45f212227d1e.md b/errors/err_console_writable_stream.md similarity index 100% rename from api-docs/f065ebb39a4a8d033077c1719ef5eb70ab06506561f3747a6cca45f212227d1e.md rename to errors/err_console_writable_stream.md diff --git a/api-docs/c18017c61939cdf22e0198a1eb702a12c7161c3c60b37bb276f8ffa6924c3732.md b/errors/err_construct_call_required.md similarity index 100% rename from api-docs/c18017c61939cdf22e0198a1eb702a12c7161c3c60b37bb276f8ffa6924c3732.md rename to errors/err_construct_call_required.md diff --git a/api-docs/523afb71b452c739d9adc35260f3d15fe988d36787c027eb240bc095970f0864.md b/errors/err_cpu_usage.md similarity index 100% rename from api-docs/523afb71b452c739d9adc35260f3d15fe988d36787c027eb240bc095970f0864.md rename to errors/err_cpu_usage.md diff --git a/api-docs/708af8d41629adf77998eb117b4bc054905b79db9eb9043e96221ea9ca38d539.md b/errors/err_crypto_custom_engine_not_supported.md similarity index 100% rename from api-docs/708af8d41629adf77998eb117b4bc054905b79db9eb9043e96221ea9ca38d539.md rename to errors/err_crypto_custom_engine_not_supported.md diff --git a/api-docs/d5b8248773b3ed82bc7ea362a8a3866ec43e2862b60ae11c583c2fe5f8555f58.md b/errors/err_crypto_ecdh_invalid_format.md similarity index 100% rename from api-docs/d5b8248773b3ed82bc7ea362a8a3866ec43e2862b60ae11c583c2fe5f8555f58.md rename to errors/err_crypto_ecdh_invalid_format.md diff --git a/api-docs/10f4d8db2e7771a48a6e4cea2baab1726278d6c2ac43545ed80a235745d13fc3.md b/errors/err_crypto_ecdh_invalid_public_key.md similarity index 100% rename from api-docs/10f4d8db2e7771a48a6e4cea2baab1726278d6c2ac43545ed80a235745d13fc3.md rename to errors/err_crypto_ecdh_invalid_public_key.md diff --git a/api-docs/378018c0ef0f040152992b97136b62c9278dba0b1c6e4cb29bf369350efa7af9.md b/errors/err_crypto_engine_unknown.md similarity index 100% rename from api-docs/378018c0ef0f040152992b97136b62c9278dba0b1c6e4cb29bf369350efa7af9.md rename to errors/err_crypto_engine_unknown.md diff --git a/api-docs/e62bd881b012f727eb127c11e550f2574eb21803f50fc84775ba4ecc029f4cc3.md b/errors/err_crypto_fips_forced.md similarity index 100% rename from api-docs/e62bd881b012f727eb127c11e550f2574eb21803f50fc84775ba4ecc029f4cc3.md rename to errors/err_crypto_fips_forced.md diff --git a/api-docs/ca9d65d337ced6f7cc97ad71b807a4d8c5d465ea71ef040f17a9c52802a60a94.md b/errors/err_crypto_fips_unavailable.md similarity index 100% rename from api-docs/ca9d65d337ced6f7cc97ad71b807a4d8c5d465ea71ef040f17a9c52802a60a94.md rename to errors/err_crypto_fips_unavailable.md diff --git a/api-docs/77e14f8a8e5a9ce0acdc64055e109015ced067d714e7572fde2075c882e56b95.md b/errors/err_crypto_hash_digest_no_utf16.md similarity index 100% rename from api-docs/77e14f8a8e5a9ce0acdc64055e109015ced067d714e7572fde2075c882e56b95.md rename to errors/err_crypto_hash_digest_no_utf16.md diff --git a/api-docs/7f0d15a453363230c09804ed0ea3afd85e4229d3d2f712ac69bd1afbad68c548.md b/errors/err_crypto_hash_finalized.md similarity index 100% rename from api-docs/7f0d15a453363230c09804ed0ea3afd85e4229d3d2f712ac69bd1afbad68c548.md rename to errors/err_crypto_hash_finalized.md diff --git a/api-docs/ca319a216a3a8646b7f8881927839d23fed81fc5ccb4323fd35662d25a6b902c.md b/errors/err_crypto_hash_update_failed.md similarity index 100% rename from api-docs/ca319a216a3a8646b7f8881927839d23fed81fc5ccb4323fd35662d25a6b902c.md rename to errors/err_crypto_hash_update_failed.md diff --git a/api-docs/613977ae73953bfea0090a5a7d7d13d48324bafbc4f7078ca19ff752fa42115b.md b/errors/err_crypto_incompatible_key_options.md similarity index 100% rename from api-docs/613977ae73953bfea0090a5a7d7d13d48324bafbc4f7078ca19ff752fa42115b.md rename to errors/err_crypto_incompatible_key_options.md diff --git a/api-docs/aff491f0db9a3bdf0377d4d6349134aaf74ea306a9869cabb95ed0cef1ae85ab.md b/errors/err_crypto_invalid_digest.md similarity index 100% rename from api-docs/aff491f0db9a3bdf0377d4d6349134aaf74ea306a9869cabb95ed0cef1ae85ab.md rename to errors/err_crypto_invalid_digest.md diff --git a/api-docs/ff65b25adf657c396c95cb7a507a90d70a832d774f73357b232433ce3ebda255.md b/errors/err_crypto_invalid_state.md similarity index 100% rename from api-docs/ff65b25adf657c396c95cb7a507a90d70a832d774f73357b232433ce3ebda255.md rename to errors/err_crypto_invalid_state.md diff --git a/api-docs/b4f71cd7e8779dbb0ff3c04f147479fbc36cbb3542356c81de5df6094f029736.md b/errors/err_crypto_pbkdf2_error.md similarity index 100% rename from api-docs/b4f71cd7e8779dbb0ff3c04f147479fbc36cbb3542356c81de5df6094f029736.md rename to errors/err_crypto_pbkdf2_error.md diff --git a/api-docs/8faf9a219a4c4c33ee1448b8c9e42e7d69c942b56b92542f5125d06275b58b58.md b/errors/err_crypto_scrypt_invalid_parameter.md similarity index 100% rename from api-docs/8faf9a219a4c4c33ee1448b8c9e42e7d69c942b56b92542f5125d06275b58b58.md rename to errors/err_crypto_scrypt_invalid_parameter.md diff --git a/api-docs/92bd7de1500d3b2f47e64e28039e395b55b48c61124eda3babd2bbfc88580344.md b/errors/err_crypto_scrypt_not_supported.md similarity index 100% rename from api-docs/92bd7de1500d3b2f47e64e28039e395b55b48c61124eda3babd2bbfc88580344.md rename to errors/err_crypto_scrypt_not_supported.md diff --git a/api-docs/39800cf08f5915957dd21368369bd002a31e4d3b8551f039209e0e096f394489.md b/errors/err_crypto_sign_key_required.md similarity index 100% rename from api-docs/39800cf08f5915957dd21368369bd002a31e4d3b8551f039209e0e096f394489.md rename to errors/err_crypto_sign_key_required.md diff --git a/api-docs/87cba5b36f910624e676a80ce337cf193c5c9bfab3b8d49c184bc697fa6a50d9.md b/errors/err_crypto_timing_safe_equal_length.md similarity index 100% rename from api-docs/87cba5b36f910624e676a80ce337cf193c5c9bfab3b8d49c184bc697fa6a50d9.md rename to errors/err_crypto_timing_safe_equal_length.md diff --git a/api-docs/96687ad7a450a36a31271361da671f4d75f6a507ca19c507ad679aaa38450785.md b/errors/err_dns_set_servers_failed.md similarity index 100% rename from api-docs/96687ad7a450a36a31271361da671f4d75f6a507ca19c507ad679aaa38450785.md rename to errors/err_dns_set_servers_failed.md diff --git a/api-docs/729fb0fd9cee2dbc293008f110105254cdd3b487e081025c648cf59877ac57cf.md b/errors/err_domain_callback_not_available.md similarity index 100% rename from api-docs/729fb0fd9cee2dbc293008f110105254cdd3b487e081025c648cf59877ac57cf.md rename to errors/err_domain_callback_not_available.md diff --git a/api-docs/9f9d107097dae5ce2f8403772d09d250b55b5f6489795b983e936617bc272993.md b/errors/err_domain_cannot_set_uncaught_exception_capture.md similarity index 100% rename from api-docs/9f9d107097dae5ce2f8403772d09d250b55b5f6489795b983e936617bc272993.md rename to errors/err_domain_cannot_set_uncaught_exception_capture.md diff --git a/api-docs/e974e30856b32a968af49235b3650f4d6fcdc89ca1b5e82ed6489d58d6704782.md b/errors/err_encoding_invalid_encoded_data.md similarity index 100% rename from api-docs/e974e30856b32a968af49235b3650f4d6fcdc89ca1b5e82ed6489d58d6704782.md rename to errors/err_encoding_invalid_encoded_data.md diff --git a/api-docs/e329f89756b7b0d582d2fd84ea2b7d50c2c1eb98a2ecd46235d4caefdf78a6cd.md b/errors/err_encoding_not_supported.md similarity index 100% rename from api-docs/e329f89756b7b0d582d2fd84ea2b7d50c2c1eb98a2ecd46235d4caefdf78a6cd.md rename to errors/err_encoding_not_supported.md diff --git a/api-docs/845d1426a62065aa45c627f411476cfd56a721a7198ea450b0a05ee11a612528.md b/errors/err_falsy_value_rejection.md similarity index 100% rename from api-docs/845d1426a62065aa45c627f411476cfd56a721a7198ea450b0a05ee11a612528.md rename to errors/err_falsy_value_rejection.md diff --git a/api-docs/ae640a8031a61722d887f670ef79b15017a58b2a80b9b7b9bd11b94c239175ed.md b/errors/err_fs_file_too_large.md similarity index 100% rename from api-docs/ae640a8031a61722d887f670ef79b15017a58b2a80b9b7b9bd11b94c239175ed.md rename to errors/err_fs_file_too_large.md diff --git a/api-docs/e5c951b0b062d3db2ec79a196947fe8bf31594e95dd1c4ea6eb0394a81e1a805.md b/errors/err_fs_invalid_symlink_type.md similarity index 100% rename from api-docs/e5c951b0b062d3db2ec79a196947fe8bf31594e95dd1c4ea6eb0394a81e1a805.md rename to errors/err_fs_invalid_symlink_type.md diff --git a/api-docs/b0ffee439cd96254a8ff8d42e64a13ebfaa6b5fd302e4d3c00801a006e26757e.md b/errors/err_fs_watcher_already_started.md similarity index 100% rename from api-docs/b0ffee439cd96254a8ff8d42e64a13ebfaa6b5fd302e4d3c00801a006e26757e.md rename to errors/err_fs_watcher_already_started.md diff --git a/api-docs/a20b909445ca676d707d076771c739ff0a10c33e6901fb518ded69e6050d2d1d.md b/errors/err_fs_watcher_not_started.md similarity index 100% rename from api-docs/a20b909445ca676d707d076771c739ff0a10c33e6901fb518ded69e6050d2d1d.md rename to errors/err_fs_watcher_not_started.md diff --git a/api-docs/34a2ef49c80394c08a8ca28d46788be480a50fc9ec0500f1daffe0a7014f723d.md b/errors/err_http2_already_shutdown.md similarity index 100% rename from api-docs/34a2ef49c80394c08a8ca28d46788be480a50fc9ec0500f1daffe0a7014f723d.md rename to errors/err_http2_already_shutdown.md diff --git a/api-docs/56c3dc55a6c22250b8cb267d998ccdbb253e665221dd40b1bf01a5680d434265.md b/errors/err_http2_altsvc_invalid_origin.md similarity index 100% rename from api-docs/56c3dc55a6c22250b8cb267d998ccdbb253e665221dd40b1bf01a5680d434265.md rename to errors/err_http2_altsvc_invalid_origin.md diff --git a/api-docs/f4b99e12b678f9352582f72bf9f1ac17307dcc19ab54080d9c859b91b61b2a5d.md b/errors/err_http2_altsvc_length.md similarity index 100% rename from api-docs/f4b99e12b678f9352582f72bf9f1ac17307dcc19ab54080d9c859b91b61b2a5d.md rename to errors/err_http2_altsvc_length.md diff --git a/api-docs/79b29a765bb87dc109c66b7b3a95372da99bcf418b9eab3eaf7a1e744bd7c385.md b/errors/err_http2_connect_authority.md similarity index 100% rename from api-docs/79b29a765bb87dc109c66b7b3a95372da99bcf418b9eab3eaf7a1e744bd7c385.md rename to errors/err_http2_connect_authority.md diff --git a/api-docs/b291203ede34a914247634e936a2fc7c81d9f75b2d075b7ef8783e29e0b2bc06.md b/errors/err_http2_connect_path.md similarity index 100% rename from api-docs/b291203ede34a914247634e936a2fc7c81d9f75b2d075b7ef8783e29e0b2bc06.md rename to errors/err_http2_connect_path.md diff --git a/api-docs/fb26239d416a1ec62475165c5b6d8cb6c875addaea3ed4c182b24b6f15dc1013.md b/errors/err_http2_connect_scheme.md similarity index 100% rename from api-docs/fb26239d416a1ec62475165c5b6d8cb6c875addaea3ed4c182b24b6f15dc1013.md rename to errors/err_http2_connect_scheme.md diff --git a/api-docs/78f3b194c108621d76496b298b3d1e88ace852bb5f7126a02a67376e2e3ab81c.md b/errors/err_http2_error.md similarity index 100% rename from api-docs/78f3b194c108621d76496b298b3d1e88ace852bb5f7126a02a67376e2e3ab81c.md rename to errors/err_http2_error.md diff --git a/api-docs/238d1fffbfe9df0dccc1727598c1fad23d6838cf17d27197a955a669d3343d85.md b/errors/err_http2_error_1.md similarity index 100% rename from api-docs/238d1fffbfe9df0dccc1727598c1fad23d6838cf17d27197a955a669d3343d85.md rename to errors/err_http2_error_1.md diff --git a/api-docs/2d5124a4bfa804cd594dd4b40bc10a27d5ef90289ef24af2464395ddae7cb554.md b/errors/err_http2_frame_error.md similarity index 100% rename from api-docs/2d5124a4bfa804cd594dd4b40bc10a27d5ef90289ef24af2464395ddae7cb554.md rename to errors/err_http2_frame_error.md diff --git a/api-docs/31334394c6b16160c31ce4ecf1d632485eefdf76104d642a606524e11980194a.md b/errors/err_http2_goaway_session.md similarity index 100% rename from api-docs/31334394c6b16160c31ce4ecf1d632485eefdf76104d642a606524e11980194a.md rename to errors/err_http2_goaway_session.md diff --git a/api-docs/bd58f3e190d5448ba67fe0b6fd1d43ae6663eb02fd26c99e1b478ae5caa4cd5b.md b/errors/err_http2_header_required.md similarity index 100% rename from api-docs/bd58f3e190d5448ba67fe0b6fd1d43ae6663eb02fd26c99e1b478ae5caa4cd5b.md rename to errors/err_http2_header_required.md diff --git a/api-docs/c2684065c3adcca29ef25f3783770e5a5dadaaee6b536a949d4090cca40443fb.md b/errors/err_http2_header_single_value.md similarity index 100% rename from api-docs/c2684065c3adcca29ef25f3783770e5a5dadaaee6b536a949d4090cca40443fb.md rename to errors/err_http2_header_single_value.md diff --git a/api-docs/509b5b572fad013456755c851929479653f7b9a470bf328fcb0bc35a51f0c6ae.md b/errors/err_http2_headers_after_respond.md similarity index 100% rename from api-docs/509b5b572fad013456755c851929479653f7b9a470bf328fcb0bc35a51f0c6ae.md rename to errors/err_http2_headers_after_respond.md diff --git a/api-docs/ede08144514ed6ce24675fc75f37ccfa230f4a764bf16549532189a2f1e319ea.md b/errors/err_http2_headers_object.md similarity index 100% rename from api-docs/ede08144514ed6ce24675fc75f37ccfa230f4a764bf16549532189a2f1e319ea.md rename to errors/err_http2_headers_object.md diff --git a/api-docs/228299eb3ae67ba0ebe4d5be333e23224548372c5067ce053b3c2bf342ce19c5.md b/errors/err_http2_headers_sent.md similarity index 100% rename from api-docs/228299eb3ae67ba0ebe4d5be333e23224548372c5067ce053b3c2bf342ce19c5.md rename to errors/err_http2_headers_sent.md diff --git a/api-docs/748d47171bacee11578af3a0dc76d371e15a5d5122a9e574e66af9b05705cef2.md b/errors/err_http2_info_headers_after_respond.md similarity index 100% rename from api-docs/748d47171bacee11578af3a0dc76d371e15a5d5122a9e574e66af9b05705cef2.md rename to errors/err_http2_info_headers_after_respond.md diff --git a/api-docs/a141c91f6942dc336316f093c041d9df325e93bf1e5a000480085e226f26c883.md b/errors/err_http2_info_status_not_allowed.md similarity index 100% rename from api-docs/a141c91f6942dc336316f093c041d9df325e93bf1e5a000480085e226f26c883.md rename to errors/err_http2_info_status_not_allowed.md diff --git a/api-docs/d5c9cd9774392fd03de8569382c3f3253309ee0e572d6b46d4e1ed6376054112.md b/errors/err_http2_invalid_connection_headers.md similarity index 100% rename from api-docs/d5c9cd9774392fd03de8569382c3f3253309ee0e572d6b46d4e1ed6376054112.md rename to errors/err_http2_invalid_connection_headers.md diff --git a/api-docs/1be18a17be07290638bfa6ea203b2632f78df8faccd352371de9ed8a926a9f67.md b/errors/err_http2_invalid_header_value.md similarity index 100% rename from api-docs/1be18a17be07290638bfa6ea203b2632f78df8faccd352371de9ed8a926a9f67.md rename to errors/err_http2_invalid_header_value.md diff --git a/api-docs/8779a55375020de6ce0c7e21d8e296b96d666dd1e3ccea6ecb503346af9c17b5.md b/errors/err_http2_invalid_info_status.md similarity index 100% rename from api-docs/8779a55375020de6ce0c7e21d8e296b96d666dd1e3ccea6ecb503346af9c17b5.md rename to errors/err_http2_invalid_info_status.md diff --git a/api-docs/6aab37d011e5920e83ba86922b62a1e975cfcc6a63eb66d5c96cbffe605b7675.md b/errors/err_http2_invalid_origin.md similarity index 100% rename from api-docs/6aab37d011e5920e83ba86922b62a1e975cfcc6a63eb66d5c96cbffe605b7675.md rename to errors/err_http2_invalid_origin.md diff --git a/api-docs/7d5e10d2997124ac69f7220b3e9c35d3bacce6ff2747729dc1c042ce78f37334.md b/errors/err_http2_invalid_packed_settings_length.md similarity index 100% rename from api-docs/7d5e10d2997124ac69f7220b3e9c35d3bacce6ff2747729dc1c042ce78f37334.md rename to errors/err_http2_invalid_packed_settings_length.md diff --git a/api-docs/bce9853cf156d793a32ad03a017e8db96cbededf8ac60ff6622f6107485529f2.md b/errors/err_http2_invalid_pseudoheader.md similarity index 100% rename from api-docs/bce9853cf156d793a32ad03a017e8db96cbededf8ac60ff6622f6107485529f2.md rename to errors/err_http2_invalid_pseudoheader.md diff --git a/api-docs/1565265fdafae2159bf1515d47f0514069da01b8640f6dabba7bfa6e69007d50.md b/errors/err_http2_invalid_session.md similarity index 100% rename from api-docs/1565265fdafae2159bf1515d47f0514069da01b8640f6dabba7bfa6e69007d50.md rename to errors/err_http2_invalid_session.md diff --git a/api-docs/122997cdb1fdddc75ff63c4c7627d68492357b6fb4772602f82ac7aef5fbf95b.md b/errors/err_http2_invalid_setting_value.md similarity index 100% rename from api-docs/122997cdb1fdddc75ff63c4c7627d68492357b6fb4772602f82ac7aef5fbf95b.md rename to errors/err_http2_invalid_setting_value.md diff --git a/api-docs/873e64abec72cc812a4ee5a692aaa4315ab3607f7fefcf0b423cdf4c2ba37cd2.md b/errors/err_http2_invalid_stream.md similarity index 100% rename from api-docs/873e64abec72cc812a4ee5a692aaa4315ab3607f7fefcf0b423cdf4c2ba37cd2.md rename to errors/err_http2_invalid_stream.md diff --git a/api-docs/59b219a662905e9775efc2aec8f64be31529fd97c67be818ed125bdb6105bb12.md b/errors/err_http2_max_pending_settings_ack.md similarity index 100% rename from api-docs/59b219a662905e9775efc2aec8f64be31529fd97c67be818ed125bdb6105bb12.md rename to errors/err_http2_max_pending_settings_ack.md diff --git a/api-docs/85dfd83202b35a36ed007cfbf847249a9fe44b43afeb436a70faa9277eae1b11.md b/errors/err_http2_nested_push.md similarity index 100% rename from api-docs/85dfd83202b35a36ed007cfbf847249a9fe44b43afeb436a70faa9277eae1b11.md rename to errors/err_http2_nested_push.md diff --git a/api-docs/e0780e2266152b5daf14ba1df899261e209e7e470749be5432eca5d213e7c9e0.md b/errors/err_http2_no_socket_manipulation.md similarity index 100% rename from api-docs/e0780e2266152b5daf14ba1df899261e209e7e470749be5432eca5d213e7c9e0.md rename to errors/err_http2_no_socket_manipulation.md diff --git a/api-docs/dbe294740a366d397f29ef45ba345fb5e3fdec0030dfa3d0cfc05e30cd47a833.md b/errors/err_http2_origin_length.md similarity index 100% rename from api-docs/dbe294740a366d397f29ef45ba345fb5e3fdec0030dfa3d0cfc05e30cd47a833.md rename to errors/err_http2_origin_length.md diff --git a/api-docs/0f35c2cb87dd0e0526486accc214c4bcbf923f40a2f2730b7f5692528e1108be.md b/errors/err_http2_out_of_streams.md similarity index 100% rename from api-docs/0f35c2cb87dd0e0526486accc214c4bcbf923f40a2f2730b7f5692528e1108be.md rename to errors/err_http2_out_of_streams.md diff --git a/api-docs/efbfacd2a02461b8474950bc2d3031a2bb1ac70cd100cc7803b51d992b65a8c3.md b/errors/err_http2_payload_forbidden.md similarity index 100% rename from api-docs/efbfacd2a02461b8474950bc2d3031a2bb1ac70cd100cc7803b51d992b65a8c3.md rename to errors/err_http2_payload_forbidden.md diff --git a/api-docs/6adf94005110fd61e70d2dd646870bef10db376f22fbab3c5c8aa170ac0c8fe8.md b/errors/err_http2_ping_cancel.md similarity index 100% rename from api-docs/6adf94005110fd61e70d2dd646870bef10db376f22fbab3c5c8aa170ac0c8fe8.md rename to errors/err_http2_ping_cancel.md diff --git a/api-docs/bad96236a9d4ed594b4131e444e3c019cfb5bf6eeea8a0033c49963fe2f8e036.md b/errors/err_http2_ping_length.md similarity index 100% rename from api-docs/bad96236a9d4ed594b4131e444e3c019cfb5bf6eeea8a0033c49963fe2f8e036.md rename to errors/err_http2_ping_length.md diff --git a/api-docs/a9872f09bf056608d2f17bf9da935fad6ec9c65ff1bb11eec510e96d60d6edb4.md b/errors/err_http2_pseudoheader_not_allowed.md similarity index 100% rename from api-docs/a9872f09bf056608d2f17bf9da935fad6ec9c65ff1bb11eec510e96d60d6edb4.md rename to errors/err_http2_pseudoheader_not_allowed.md diff --git a/api-docs/bb38caf7d16b7e2802a592abde153accd7c61fbd188089119124522073d90261.md b/errors/err_http2_push_disabled.md similarity index 100% rename from api-docs/bb38caf7d16b7e2802a592abde153accd7c61fbd188089119124522073d90261.md rename to errors/err_http2_push_disabled.md diff --git a/api-docs/ebdfcab27c5b8b350f0129de9b76cb5e74f979223f2b31a1da819d485f592576.md b/errors/err_http2_send_file.md similarity index 100% rename from api-docs/ebdfcab27c5b8b350f0129de9b76cb5e74f979223f2b31a1da819d485f592576.md rename to errors/err_http2_send_file.md diff --git a/api-docs/1e1625a3eacd2e160a760edd37e54ab1a6e72290395233f565543351eff10178.md b/errors/err_http2_send_file_noseek.md similarity index 100% rename from api-docs/1e1625a3eacd2e160a760edd37e54ab1a6e72290395233f565543351eff10178.md rename to errors/err_http2_send_file_noseek.md diff --git a/api-docs/341ad2e525d5659a37bb360050958a8adfb29899e18395b0a17e0e46a0219cd6.md b/errors/err_http2_session_error.md similarity index 100% rename from api-docs/341ad2e525d5659a37bb360050958a8adfb29899e18395b0a17e0e46a0219cd6.md rename to errors/err_http2_session_error.md diff --git a/api-docs/1ce4b8c8f1bb7f89dd385bf4c38e9cdac8e36d0681288ad75be09f381bb61b58.md b/errors/err_http2_settings_cancel.md similarity index 100% rename from api-docs/1ce4b8c8f1bb7f89dd385bf4c38e9cdac8e36d0681288ad75be09f381bb61b58.md rename to errors/err_http2_settings_cancel.md diff --git a/api-docs/a7ecde0bccef5a130b0cc650059eef8e16ab7f3476dc02168dce51f0a84bb247.md b/errors/err_http2_socket_bound.md similarity index 100% rename from api-docs/a7ecde0bccef5a130b0cc650059eef8e16ab7f3476dc02168dce51f0a84bb247.md rename to errors/err_http2_socket_bound.md diff --git a/api-docs/049dad32335cd74cec831f6fb01d9725c5f3d91f15dbab28cc6b9c57a46fe1b6.md b/errors/err_http2_socket_unbound.md similarity index 100% rename from api-docs/049dad32335cd74cec831f6fb01d9725c5f3d91f15dbab28cc6b9c57a46fe1b6.md rename to errors/err_http2_socket_unbound.md diff --git a/api-docs/f70b602d71d57f4a265c8c837ca97f7e0ceee417a44f8f660b9981889187821f.md b/errors/err_http2_status_101.md similarity index 100% rename from api-docs/f70b602d71d57f4a265c8c837ca97f7e0ceee417a44f8f660b9981889187821f.md rename to errors/err_http2_status_101.md diff --git a/api-docs/307153bf22415747dca5ee287f036f30a4d06a0394f23b94e5781868e7d4a704.md b/errors/err_http2_status_invalid.md similarity index 100% rename from api-docs/307153bf22415747dca5ee287f036f30a4d06a0394f23b94e5781868e7d4a704.md rename to errors/err_http2_status_invalid.md diff --git a/api-docs/7f189325da3468f7bbe5e87b7ed61c5f762c5cd7bfc293c534037d3f9d9d1322.md b/errors/err_http2_stream_cancel.md similarity index 100% rename from api-docs/7f189325da3468f7bbe5e87b7ed61c5f762c5cd7bfc293c534037d3f9d9d1322.md rename to errors/err_http2_stream_cancel.md diff --git a/api-docs/f57ee3119ee171996fa1a3e0054fee1b0bd0be793ec9fb2b9c04771cad3ab1da.md b/errors/err_http2_stream_closed.md similarity index 100% rename from api-docs/f57ee3119ee171996fa1a3e0054fee1b0bd0be793ec9fb2b9c04771cad3ab1da.md rename to errors/err_http2_stream_closed.md diff --git a/api-docs/bab4ee3dbc03dbe3edb88decc212551e88c8cc2f04c70a231458351c635c7091.md b/errors/err_http2_stream_error.md similarity index 100% rename from api-docs/bab4ee3dbc03dbe3edb88decc212551e88c8cc2f04c70a231458351c635c7091.md rename to errors/err_http2_stream_error.md diff --git a/api-docs/f56fd7b5a0d9343f91e48bd0638644b3e351413118a7155191150faa5f3bf212.md b/errors/err_http2_stream_self_dependency.md similarity index 100% rename from api-docs/f56fd7b5a0d9343f91e48bd0638644b3e351413118a7155191150faa5f3bf212.md rename to errors/err_http2_stream_self_dependency.md diff --git a/api-docs/8159f8b9ddf490d611b98fe3497ec49144c8c0cf24edd9ed9641e32c7f4f8d55.md b/errors/err_http2_trailers_already_sent.md similarity index 100% rename from api-docs/8159f8b9ddf490d611b98fe3497ec49144c8c0cf24edd9ed9641e32c7f4f8d55.md rename to errors/err_http2_trailers_already_sent.md diff --git a/api-docs/c483329e210ce74e59215cf1a4be786dea55bb3c531ad59fb8ad6b0b68616027.md b/errors/err_http2_trailers_not_ready.md similarity index 100% rename from api-docs/c483329e210ce74e59215cf1a4be786dea55bb3c531ad59fb8ad6b0b68616027.md rename to errors/err_http2_trailers_not_ready.md diff --git a/api-docs/89544f74d2d406bdfb6bdb0f4750cbf97ea2dd0fc2f8840e34be0523625cf188.md b/errors/err_http2_unsupported_protocol.md similarity index 100% rename from api-docs/89544f74d2d406bdfb6bdb0f4750cbf97ea2dd0fc2f8840e34be0523625cf188.md rename to errors/err_http2_unsupported_protocol.md diff --git a/api-docs/8a7dd361608a03b5b4a1ad7ae4a9223869d741ed908b60714718ffce8437434a.md b/errors/err_http_headers_sent.md similarity index 100% rename from api-docs/8a7dd361608a03b5b4a1ad7ae4a9223869d741ed908b60714718ffce8437434a.md rename to errors/err_http_headers_sent.md diff --git a/api-docs/0a239d424096f473a28144ad571bf8a528da4c57f1f01d41aaea76f5392327cf.md b/errors/err_http_invalid_char.md similarity index 100% rename from api-docs/0a239d424096f473a28144ad571bf8a528da4c57f1f01d41aaea76f5392327cf.md rename to errors/err_http_invalid_char.md diff --git a/api-docs/f5a474276b3f3ec0693e5e83b5bf5001afd4916649cf357e6cd9a91b26f06544.md b/errors/err_http_invalid_header_value.md similarity index 100% rename from api-docs/f5a474276b3f3ec0693e5e83b5bf5001afd4916649cf357e6cd9a91b26f06544.md rename to errors/err_http_invalid_header_value.md diff --git a/api-docs/3332b104a6cb39b1b9daa8516c96afe5a441005d64fe330d3e24726b240e0154.md b/errors/err_http_invalid_status_code.md similarity index 100% rename from api-docs/3332b104a6cb39b1b9daa8516c96afe5a441005d64fe330d3e24726b240e0154.md rename to errors/err_http_invalid_status_code.md diff --git a/api-docs/aaab8948ddafd201592b69b622b80ac2c7d356a1d4e654d91082f17e4f9aea33.md b/errors/err_http_trailer_invalid.md similarity index 100% rename from api-docs/aaab8948ddafd201592b69b622b80ac2c7d356a1d4e654d91082f17e4f9aea33.md rename to errors/err_http_trailer_invalid.md diff --git a/api-docs/d3f35277e16bad3e639074e401e73a61320839549335d134c133d2ea5cf8bbbe.md b/errors/err_index_out_of_range.md similarity index 100% rename from api-docs/d3f35277e16bad3e639074e401e73a61320839549335d134c133d2ea5cf8bbbe.md rename to errors/err_index_out_of_range.md diff --git a/api-docs/fc2adcc6174e6b7851d8b5fda4f43c6a0ce189b2ce7e01f712f971de692f10e7.md b/errors/err_inspector_already_connected.md similarity index 100% rename from api-docs/fc2adcc6174e6b7851d8b5fda4f43c6a0ce189b2ce7e01f712f971de692f10e7.md rename to errors/err_inspector_already_connected.md diff --git a/api-docs/7c084b435baffc7c1488b3baae99421117d72c854f194c51cc0d58353fced585.md b/errors/err_inspector_closed.md similarity index 100% rename from api-docs/7c084b435baffc7c1488b3baae99421117d72c854f194c51cc0d58353fced585.md rename to errors/err_inspector_closed.md diff --git a/api-docs/61668f9f6e2feeb9a3031ed0eb8c78c34e08a5e4a248eaf4acd3e2259cf8c1da.md b/errors/err_inspector_not_available.md similarity index 100% rename from api-docs/61668f9f6e2feeb9a3031ed0eb8c78c34e08a5e4a248eaf4acd3e2259cf8c1da.md rename to errors/err_inspector_not_available.md diff --git a/api-docs/d5b4f3b1edddc4696be44f124b45a260b757db8fa19a338b4526b83c600d85b1.md b/errors/err_inspector_not_connected.md similarity index 100% rename from api-docs/d5b4f3b1edddc4696be44f124b45a260b757db8fa19a338b4526b83c600d85b1.md rename to errors/err_inspector_not_connected.md diff --git a/api-docs/61fd54de77ccd49ae9d1e19997338db009902f3c91c2f1737a933bc233525e0d.md b/errors/err_invalid_address_family.md similarity index 100% rename from api-docs/61fd54de77ccd49ae9d1e19997338db009902f3c91c2f1737a933bc233525e0d.md rename to errors/err_invalid_address_family.md diff --git a/api-docs/a215ea6e9b295d2173bfbf6e820629bee19b1961ac9aa4b7002c0cddd2c63378.md b/errors/err_invalid_arg_type.md similarity index 100% rename from api-docs/a215ea6e9b295d2173bfbf6e820629bee19b1961ac9aa4b7002c0cddd2c63378.md rename to errors/err_invalid_arg_type.md diff --git a/api-docs/a0bba0df0b77cde558ebe08bc369029c2d90180dd3f329e1b431ad5db456e582.md b/errors/err_invalid_arg_value.md similarity index 100% rename from api-docs/a0bba0df0b77cde558ebe08bc369029c2d90180dd3f329e1b431ad5db456e582.md rename to errors/err_invalid_arg_value.md diff --git a/api-docs/c8812cf5589e2f09e9a91693ff07e1cd81d9b33d0216b6d28c89c87262a9c9dc.md b/errors/err_invalid_array_length.md similarity index 100% rename from api-docs/c8812cf5589e2f09e9a91693ff07e1cd81d9b33d0216b6d28c89c87262a9c9dc.md rename to errors/err_invalid_array_length.md diff --git a/api-docs/e2b68636374769543dc32a1f27c45b76b03d5fbf4985715fa0fc20b8f5742687.md b/errors/err_invalid_async_id.md similarity index 100% rename from api-docs/e2b68636374769543dc32a1f27c45b76b03d5fbf4985715fa0fc20b8f5742687.md rename to errors/err_invalid_async_id.md diff --git a/api-docs/d34661c64ffe91d2c775d17294d8d9aef1a9c93e8bee8ddd9c368bff59d177ce.md b/errors/err_invalid_buffer_size.md similarity index 100% rename from api-docs/d34661c64ffe91d2c775d17294d8d9aef1a9c93e8bee8ddd9c368bff59d177ce.md rename to errors/err_invalid_buffer_size.md diff --git a/api-docs/cdb1f398b32351cedcc32ffaf9186f8d85f0553eebb5256980d647a8b5437cb4.md b/errors/err_invalid_callback.md similarity index 100% rename from api-docs/cdb1f398b32351cedcc32ffaf9186f8d85f0553eebb5256980d647a8b5437cb4.md rename to errors/err_invalid_callback.md diff --git a/api-docs/7803c6ec62c86f1d4a42ee3cb9fbd526e3f33c368511c40e22734b890084e5fd.md b/errors/err_invalid_char.md similarity index 100% rename from api-docs/7803c6ec62c86f1d4a42ee3cb9fbd526e3f33c368511c40e22734b890084e5fd.md rename to errors/err_invalid_char.md diff --git a/api-docs/c184b4f8463889baee92ae26287132284c29b9e3bb0661271a03a6bd30c5d00b.md b/errors/err_invalid_cursor_pos.md similarity index 100% rename from api-docs/c184b4f8463889baee92ae26287132284c29b9e3bb0661271a03a6bd30c5d00b.md rename to errors/err_invalid_cursor_pos.md diff --git a/api-docs/bbadca1007d9f9cafdbf9f36f2dc2d8b01682fa21dbe2ca7355c9a62b24ba02b.md b/errors/err_invalid_domain_name.md similarity index 100% rename from api-docs/bbadca1007d9f9cafdbf9f36f2dc2d8b01682fa21dbe2ca7355c9a62b24ba02b.md rename to errors/err_invalid_domain_name.md diff --git a/api-docs/ac238115b7051faf8297d84274d68282b08e64e8ec214e959fea374e068b5824.md b/errors/err_invalid_fd.md similarity index 100% rename from api-docs/ac238115b7051faf8297d84274d68282b08e64e8ec214e959fea374e068b5824.md rename to errors/err_invalid_fd.md diff --git a/api-docs/37744f249e5446c68459d9f4a6e31c4e81b43fed69f0bf8ae56920d2dbdc19c0.md b/errors/err_invalid_fd_type.md similarity index 100% rename from api-docs/37744f249e5446c68459d9f4a6e31c4e81b43fed69f0bf8ae56920d2dbdc19c0.md rename to errors/err_invalid_fd_type.md diff --git a/api-docs/42a2f62fba06dfa25df29f025c58fb47165a4465302b9b92e798cea318abeac9.md b/errors/err_invalid_file_url_host.md similarity index 100% rename from api-docs/42a2f62fba06dfa25df29f025c58fb47165a4465302b9b92e798cea318abeac9.md rename to errors/err_invalid_file_url_host.md diff --git a/api-docs/3fbaefe82de16dc63b0f4309b3e597ea7abb632784c14c262e1aac43a23f2505.md b/errors/err_invalid_file_url_path.md similarity index 100% rename from api-docs/3fbaefe82de16dc63b0f4309b3e597ea7abb632784c14c262e1aac43a23f2505.md rename to errors/err_invalid_file_url_path.md diff --git a/api-docs/043494b06d5e0daae1b6255dfaca282798cdeed2ed101c65fbf084fa81f53d68.md b/errors/err_invalid_handle_type.md similarity index 100% rename from api-docs/043494b06d5e0daae1b6255dfaca282798cdeed2ed101c65fbf084fa81f53d68.md rename to errors/err_invalid_handle_type.md diff --git a/api-docs/43989a3d7b3588e03453d445c3e4cc1d102db36d8c811bbb07259a0046e8d604.md b/errors/err_invalid_http_token.md similarity index 100% rename from api-docs/43989a3d7b3588e03453d445c3e4cc1d102db36d8c811bbb07259a0046e8d604.md rename to errors/err_invalid_http_token.md diff --git a/api-docs/12ba612f9569414d1e324bb927e3b2f3017305bf39f3919940bdf92f4eebdb81.md b/errors/err_invalid_ip_address.md similarity index 100% rename from api-docs/12ba612f9569414d1e324bb927e3b2f3017305bf39f3919940bdf92f4eebdb81.md rename to errors/err_invalid_ip_address.md diff --git a/api-docs/85b1046663e01e318d4ed722be7abe82a34047224c8c72e4649b8a32067ef937.md b/errors/err_invalid_opt_value.md similarity index 100% rename from api-docs/85b1046663e01e318d4ed722be7abe82a34047224c8c72e4649b8a32067ef937.md rename to errors/err_invalid_opt_value.md diff --git a/api-docs/75131da7fc4ce2f384bfa0e11e16cb772e00f102a69c768584681f8edefc748e.md b/errors/err_invalid_opt_value_encoding.md similarity index 100% rename from api-docs/75131da7fc4ce2f384bfa0e11e16cb772e00f102a69c768584681f8edefc748e.md rename to errors/err_invalid_opt_value_encoding.md diff --git a/api-docs/61ade24deebc5cf29fec44e14d4975280641ff012534ee664b88a1a2cc4bf519.md b/errors/err_invalid_performance_mark.md similarity index 100% rename from api-docs/61ade24deebc5cf29fec44e14d4975280641ff012534ee664b88a1a2cc4bf519.md rename to errors/err_invalid_performance_mark.md diff --git a/api-docs/4fb5e029b886955ed150029d565ba7e9083c7fff6a28f2ce17c5c97b5b21e113.md b/errors/err_invalid_protocol.md similarity index 100% rename from api-docs/4fb5e029b886955ed150029d565ba7e9083c7fff6a28f2ce17c5c97b5b21e113.md rename to errors/err_invalid_protocol.md diff --git a/api-docs/15178b9c86cfa51921f78902fa1f827d670c6509ef14db0111ec51644339b333.md b/errors/err_invalid_repl_eval_config.md similarity index 100% rename from api-docs/15178b9c86cfa51921f78902fa1f827d670c6509ef14db0111ec51644339b333.md rename to errors/err_invalid_repl_eval_config.md diff --git a/api-docs/89f0a5040550601c7407362b879833d102bdb3d571e4c43adba1d5155661838a.md b/errors/err_invalid_repl_history.md similarity index 100% rename from api-docs/89f0a5040550601c7407362b879833d102bdb3d571e4c43adba1d5155661838a.md rename to errors/err_invalid_repl_history.md diff --git a/api-docs/f7a0f4b5f024d807ffc046acc38f1c276ed469ec1bb1ee8bb9308887d4dcd0eb.md b/errors/err_invalid_return_property.md similarity index 100% rename from api-docs/f7a0f4b5f024d807ffc046acc38f1c276ed469ec1bb1ee8bb9308887d4dcd0eb.md rename to errors/err_invalid_return_property.md diff --git a/api-docs/85f1a3ec59170fc18b849deeebaff2f396a03db48cd5d455a26bec5b5a3c5eb7.md b/errors/err_invalid_return_property_value.md similarity index 100% rename from api-docs/85f1a3ec59170fc18b849deeebaff2f396a03db48cd5d455a26bec5b5a3c5eb7.md rename to errors/err_invalid_return_property_value.md diff --git a/api-docs/ba0c900f780310a56f5d2aac26e8f9db4125e7439c05487d1f369051e8e7f26d.md b/errors/err_invalid_return_value.md similarity index 100% rename from api-docs/ba0c900f780310a56f5d2aac26e8f9db4125e7439c05487d1f369051e8e7f26d.md rename to errors/err_invalid_return_value.md diff --git a/api-docs/2723b38612a8665664272cc15e0459996c165bbff6f3238bd1c6e5d353c9c8cd.md b/errors/err_invalid_sync_fork_input.md similarity index 100% rename from api-docs/2723b38612a8665664272cc15e0459996c165bbff6f3238bd1c6e5d353c9c8cd.md rename to errors/err_invalid_sync_fork_input.md diff --git a/api-docs/7322fbea7d2f2f381c2634510cf74f52a84e9cd752377be9c000b32a4b7edfdb.md b/errors/err_invalid_this.md similarity index 100% rename from api-docs/7322fbea7d2f2f381c2634510cf74f52a84e9cd752377be9c000b32a4b7edfdb.md rename to errors/err_invalid_this.md diff --git a/api-docs/ae3fe699b0d39b8a5fa8db2bcf602d8f0f1b46a420ab2b9c4f3c0b16f2f4d455.md b/errors/err_invalid_transfer_object.md similarity index 100% rename from api-docs/ae3fe699b0d39b8a5fa8db2bcf602d8f0f1b46a420ab2b9c4f3c0b16f2f4d455.md rename to errors/err_invalid_transfer_object.md diff --git a/api-docs/d88d957209d7f9603ccb8724747cf1f57e21a281938dd5465140b1e69de114cb.md b/errors/err_invalid_tuple.md similarity index 100% rename from api-docs/d88d957209d7f9603ccb8724747cf1f57e21a281938dd5465140b1e69de114cb.md rename to errors/err_invalid_tuple.md diff --git a/api-docs/6dcbe436112c35d2172f5f883e9fe95a01f8332f9a0f3f5ccb7c61c87b58cbc8.md b/errors/err_invalid_uri.md similarity index 100% rename from api-docs/6dcbe436112c35d2172f5f883e9fe95a01f8332f9a0f3f5ccb7c61c87b58cbc8.md rename to errors/err_invalid_uri.md diff --git a/api-docs/7b77a09f963166b0aba557839301bf6aa8ccc388b92911845e3515ee22db6a96.md b/errors/err_invalid_url.md similarity index 100% rename from api-docs/7b77a09f963166b0aba557839301bf6aa8ccc388b92911845e3515ee22db6a96.md rename to errors/err_invalid_url.md diff --git a/api-docs/d066b4d8cf1efaf937d66cc3bc9cf9984e601105c8f5cb53494869f1ef50247f.md b/errors/err_invalid_url_scheme.md similarity index 100% rename from api-docs/d066b4d8cf1efaf937d66cc3bc9cf9984e601105c8f5cb53494869f1ef50247f.md rename to errors/err_invalid_url_scheme.md diff --git a/api-docs/37ff78da3c2947528c510a1f31837e43462d87666103e1f6317dfe491c4158dd.md b/errors/err_ipc_channel_closed.md similarity index 100% rename from api-docs/37ff78da3c2947528c510a1f31837e43462d87666103e1f6317dfe491c4158dd.md rename to errors/err_ipc_channel_closed.md diff --git a/api-docs/af45895a2d90b766458b754978df390c83b49aa801bd7aa72fb1248efa2c6332.md b/errors/err_ipc_disconnected.md similarity index 100% rename from api-docs/af45895a2d90b766458b754978df390c83b49aa801bd7aa72fb1248efa2c6332.md rename to errors/err_ipc_disconnected.md diff --git a/api-docs/bbd19cc7c314fe7db1fad00b6f921abdc0812f6f2fa71c5df7feeae06162f643.md b/errors/err_ipc_one_pipe.md similarity index 100% rename from api-docs/bbd19cc7c314fe7db1fad00b6f921abdc0812f6f2fa71c5df7feeae06162f643.md rename to errors/err_ipc_one_pipe.md diff --git a/api-docs/6b5739bdb3f451f897aa4e36a076be410b29a99652092a56411a59cd4eb914ea.md b/errors/err_ipc_sync_fork.md similarity index 100% rename from api-docs/6b5739bdb3f451f897aa4e36a076be410b29a99652092a56411a59cd4eb914ea.md rename to errors/err_ipc_sync_fork.md diff --git a/api-docs/cc8d0eb3ad370357ecad8814c281cd8fde03cd60a740d5626c5be1aaf6851b3b.md b/errors/err_memory_allocation_failed.md similarity index 100% rename from api-docs/cc8d0eb3ad370357ecad8814c281cd8fde03cd60a740d5626c5be1aaf6851b3b.md rename to errors/err_memory_allocation_failed.md diff --git a/api-docs/99df7d000bfcc059623ab0a564890f8186504aae4b50be69327c677b04b28158.md b/errors/err_method_not_implemented.md similarity index 100% rename from api-docs/99df7d000bfcc059623ab0a564890f8186504aae4b50be69327c677b04b28158.md rename to errors/err_method_not_implemented.md diff --git a/api-docs/a2fe03c3ce166aa975e620fe8aa83f7bca3923e3338a7ab8006ef4f002571c70.md b/errors/err_missing_args.md similarity index 100% rename from api-docs/a2fe03c3ce166aa975e620fe8aa83f7bca3923e3338a7ab8006ef4f002571c70.md rename to errors/err_missing_args.md diff --git a/errors/err_missing_dynamic_instantiate_hook.md b/errors/err_missing_dynamic_instantiate_hook.md new file mode 100644 index 00000000..a60bc97b --- /dev/null +++ b/errors/err_missing_dynamic_instantiate_hook.md @@ -0,0 +1,7 @@ + +> Stability: 1 - Experimental + +An [ES6 module][] loader hook specified `format: 'dynamic'` but did not provide +a `dynamicInstantiate` hook. + + diff --git a/api-docs/4b9eae557964aa58915336b8f84593d628189aa7dd7a83a2a7008c41b085d1b8.md b/errors/err_missing_dynamic_instantiate_hook_1.md similarity index 100% rename from api-docs/4b9eae557964aa58915336b8f84593d628189aa7dd7a83a2a7008c41b085d1b8.md rename to errors/err_missing_dynamic_instantiate_hook_1.md diff --git a/api-docs/804abd156b58b404de8fda9ec9c068eda43e99c43695b5eb2fe7210750b617dd.md b/errors/err_missing_message_port_in_transfer_list.md similarity index 100% rename from api-docs/804abd156b58b404de8fda9ec9c068eda43e99c43695b5eb2fe7210750b617dd.md rename to errors/err_missing_message_port_in_transfer_list.md diff --git a/errors/err_missing_module.md b/errors/err_missing_module.md new file mode 100644 index 00000000..26df541e --- /dev/null +++ b/errors/err_missing_module.md @@ -0,0 +1,6 @@ + +> Stability: 1 - Experimental + +An [ES6 module][] could not be resolved. + + diff --git a/api-docs/3db3489121a6862fa7a48825d3ab418b4ac8a639625b6678649c4f66b49ac457.md b/errors/err_missing_platform_for_worker.md similarity index 100% rename from api-docs/3db3489121a6862fa7a48825d3ab418b4ac8a639625b6678649c4f66b49ac457.md rename to errors/err_missing_platform_for_worker.md diff --git a/errors/err_module_resolution_legacy.md b/errors/err_module_resolution_legacy.md new file mode 100644 index 00000000..4f20dbc3 --- /dev/null +++ b/errors/err_module_resolution_legacy.md @@ -0,0 +1,6 @@ + +> Stability: 1 - Experimental + +A failure occurred resolving imports in an [ES6 module][]. + + diff --git a/api-docs/57c38dded94c39e8ebb0a0893a4d1d8c7b727828154c57523173c02d677c3a99.md b/errors/err_multiple_callback.md similarity index 100% rename from api-docs/57c38dded94c39e8ebb0a0893a4d1d8c7b727828154c57523173c02d677c3a99.md rename to errors/err_multiple_callback.md diff --git a/api-docs/e64e713c4a6ff4d6568a66304199489df5b6eba574a41a94b547c36046b52ae4.md b/errors/err_napi_cons_function.md similarity index 100% rename from api-docs/e64e713c4a6ff4d6568a66304199489df5b6eba574a41a94b547c36046b52ae4.md rename to errors/err_napi_cons_function.md diff --git a/api-docs/68710f4168fe2dd0583276e159e4a8696cadb8e14cd1c53fbee547acfeea0542.md b/errors/err_napi_cons_prototype_object.md similarity index 100% rename from api-docs/68710f4168fe2dd0583276e159e4a8696cadb8e14cd1c53fbee547acfeea0542.md rename to errors/err_napi_cons_prototype_object.md diff --git a/api-docs/e17507b02b81cdc0b4e802d73bcfbb415c1cff7767d97d48a3c2312ab9f3bcac.md b/errors/err_napi_invalid_dataview_args.md similarity index 100% rename from api-docs/e17507b02b81cdc0b4e802d73bcfbb415c1cff7767d97d48a3c2312ab9f3bcac.md rename to errors/err_napi_invalid_dataview_args.md diff --git a/api-docs/c1bdba728a046e9527834656bf3d3e2c03d9f38683ac95b81e035f83dfb013fe.md b/errors/err_napi_invalid_typedarray_alignment.md similarity index 100% rename from api-docs/c1bdba728a046e9527834656bf3d3e2c03d9f38683ac95b81e035f83dfb013fe.md rename to errors/err_napi_invalid_typedarray_alignment.md diff --git a/api-docs/12f118882119c3825cd4aa193f845a637e2e9d351371fbfe0b62f7ec8f3ab616.md b/errors/err_napi_invalid_typedarray_length.md similarity index 100% rename from api-docs/12f118882119c3825cd4aa193f845a637e2e9d351371fbfe0b62f7ec8f3ab616.md rename to errors/err_napi_invalid_typedarray_length.md diff --git a/api-docs/67ee8b469a5568b7161da461d792a4f70d632d51b664753f56b3d70147c665ef.md b/errors/err_napi_tsfn_call_js.md similarity index 100% rename from api-docs/67ee8b469a5568b7161da461d792a4f70d632d51b664753f56b3d70147c665ef.md rename to errors/err_napi_tsfn_call_js.md diff --git a/api-docs/3c788f2c0c2842a7366e4444e7c8469844ed689b9186b48a6eea899c0315dae1.md b/errors/err_napi_tsfn_get_undefined.md similarity index 100% rename from api-docs/3c788f2c0c2842a7366e4444e7c8469844ed689b9186b48a6eea899c0315dae1.md rename to errors/err_napi_tsfn_get_undefined.md diff --git a/api-docs/f464f4f3d12228c59a83b4af55357c028272d87fe4c45a42fd19c84cddf52da6.md b/errors/err_napi_tsfn_start_idle_loop.md similarity index 100% rename from api-docs/f464f4f3d12228c59a83b4af55357c028272d87fe4c45a42fd19c84cddf52da6.md rename to errors/err_napi_tsfn_start_idle_loop.md diff --git a/api-docs/8255049b21c7f346469ae3fcc64893db78701c7eb8b3537fce11c882e3500b7e.md b/errors/err_napi_tsfn_stop_idle_loop.md similarity index 100% rename from api-docs/8255049b21c7f346469ae3fcc64893db78701c7eb8b3537fce11c882e3500b7e.md rename to errors/err_napi_tsfn_stop_idle_loop.md diff --git a/api-docs/3c8c5b85ecd2a9d5e7ade564a42b2921f39a65ede483607b5b4e6a739168f5df.md b/errors/err_no_crypto.md similarity index 100% rename from api-docs/3c8c5b85ecd2a9d5e7ade564a42b2921f39a65ede483607b5b4e6a739168f5df.md rename to errors/err_no_crypto.md diff --git a/api-docs/4dfd5e3bc2ac51d2b4b84f9173ca0f92cb67d453d00e7b24bc7b7fb4330aba1c.md b/errors/err_no_icu.md similarity index 100% rename from api-docs/4dfd5e3bc2ac51d2b4b84f9173ca0f92cb67d453d00e7b24bc7b7fb4330aba1c.md rename to errors/err_no_icu.md diff --git a/api-docs/7afafe7dd55b2ef64247ed713ad1ffd73209601635434d86494a3ae3eae11e68.md b/errors/err_no_longer_supported.md similarity index 100% rename from api-docs/7afafe7dd55b2ef64247ed713ad1ffd73209601635434d86494a3ae3eae11e68.md rename to errors/err_no_longer_supported.md diff --git a/api-docs/f30754e5fa518878548f8fd5e465eab4f2d9b901ee6e2bed852cde361a23e59c.md b/errors/err_out_of_range.md similarity index 100% rename from api-docs/f30754e5fa518878548f8fd5e465eab4f2d9b901ee6e2bed852cde361a23e59c.md rename to errors/err_out_of_range.md diff --git a/api-docs/c899bcd4ca024d397c858f37a2b51b7b59ee7a5b15a918b0aa75b99cd1cea991.md b/errors/err_outofmemory.md similarity index 100% rename from api-docs/c899bcd4ca024d397c858f37a2b51b7b59ee7a5b15a918b0aa75b99cd1cea991.md rename to errors/err_outofmemory.md diff --git a/api-docs/938925270b85a0725a4459364d4b03790019bc4718072d93b59399806719719e.md b/errors/err_parse_history_data.md similarity index 100% rename from api-docs/938925270b85a0725a4459364d4b03790019bc4718072d93b59399806719719e.md rename to errors/err_parse_history_data.md diff --git a/errors/err_require_esm.md b/errors/err_require_esm.md new file mode 100644 index 00000000..9644488f --- /dev/null +++ b/errors/err_require_esm.md @@ -0,0 +1,6 @@ + +> Stability: 1 - Experimental + +An attempt was made to `require()` an [ES6 module][]. + + diff --git a/api-docs/7d1e67df3a180f4c5497c7337dbe72c71571a7440d3658da7f21566d9025a910.md b/errors/err_script_execution_interrupted.md similarity index 100% rename from api-docs/7d1e67df3a180f4c5497c7337dbe72c71571a7440d3658da7f21566d9025a910.md rename to errors/err_script_execution_interrupted.md diff --git a/api-docs/a641b2388627b64b8f7b8ee4e4dffb67d354b141240b0e498267730ec7711697.md b/errors/err_server_already_listen.md similarity index 100% rename from api-docs/a641b2388627b64b8f7b8ee4e4dffb67d354b141240b0e498267730ec7711697.md rename to errors/err_server_already_listen.md diff --git a/api-docs/e7ca8241e24fa9e3cb06bd5a79432b6ec036908bc8f01d6643f811d84fee391e.md b/errors/err_server_not_running.md similarity index 100% rename from api-docs/e7ca8241e24fa9e3cb06bd5a79432b6ec036908bc8f01d6643f811d84fee391e.md rename to errors/err_server_not_running.md diff --git a/api-docs/f7cae07081fe40d4a48de37e7e9958a1dca14f4cbb4c9a6a81a0ff6935728b04.md b/errors/err_socket_already_bound.md similarity index 100% rename from api-docs/f7cae07081fe40d4a48de37e7e9958a1dca14f4cbb4c9a6a81a0ff6935728b04.md rename to errors/err_socket_already_bound.md diff --git a/api-docs/2bab8f25b652e10fd2a24100ac8ec41fecb67464f00f30c4b44a0a1bf0b0a991.md b/errors/err_socket_bad_buffer_size.md similarity index 100% rename from api-docs/2bab8f25b652e10fd2a24100ac8ec41fecb67464f00f30c4b44a0a1bf0b0a991.md rename to errors/err_socket_bad_buffer_size.md diff --git a/api-docs/fb003670b6ff551734fcbf0a76a64e2aeaae4033fa0c38716b268da5d8bf0c0a.md b/errors/err_socket_bad_port.md similarity index 100% rename from api-docs/fb003670b6ff551734fcbf0a76a64e2aeaae4033fa0c38716b268da5d8bf0c0a.md rename to errors/err_socket_bad_port.md diff --git a/api-docs/e2bc2b5bb8f18e4fb26f4d1a2df76b5b5911fbac2a84b50d9264beead5f25d92.md b/errors/err_socket_bad_type.md similarity index 100% rename from api-docs/e2bc2b5bb8f18e4fb26f4d1a2df76b5b5911fbac2a84b50d9264beead5f25d92.md rename to errors/err_socket_bad_type.md diff --git a/api-docs/441e79532ecb8b51bf2d71da8b6e6f2d28bb0e67979c0027d89361bc928bb250.md b/errors/err_socket_buffer_size.md similarity index 100% rename from api-docs/441e79532ecb8b51bf2d71da8b6e6f2d28bb0e67979c0027d89361bc928bb250.md rename to errors/err_socket_buffer_size.md diff --git a/api-docs/347aecf9b43987f84bd77f98b54c9b754ece9d2e935db5938ea2cccd8f65c84b.md b/errors/err_socket_cannot_send.md similarity index 100% rename from api-docs/347aecf9b43987f84bd77f98b54c9b754ece9d2e935db5938ea2cccd8f65c84b.md rename to errors/err_socket_cannot_send.md diff --git a/api-docs/cd78143de0a68b069cc285537e36cc04c18ff702c77c5a9e86b1855662241e0a.md b/errors/err_socket_closed.md similarity index 100% rename from api-docs/cd78143de0a68b069cc285537e36cc04c18ff702c77c5a9e86b1855662241e0a.md rename to errors/err_socket_closed.md diff --git a/api-docs/a25b026d7de2e2d6d305d6d2b6291aea4c193187a796a03c0b5e089edd1f5fb0.md b/errors/err_socket_dgram_not_running.md similarity index 100% rename from api-docs/a25b026d7de2e2d6d305d6d2b6291aea4c193187a796a03c0b5e089edd1f5fb0.md rename to errors/err_socket_dgram_not_running.md diff --git a/api-docs/ef7000358965c6aa296f4b115d9543772cd8281cf0452e47be32d4f962ade1bf.md b/errors/err_stderr_close.md similarity index 100% rename from api-docs/ef7000358965c6aa296f4b115d9543772cd8281cf0452e47be32d4f962ade1bf.md rename to errors/err_stderr_close.md diff --git a/api-docs/2cfccb9b7de87232d107ee86fafd91c895a72c83d1948ed98066ed042e2b9581.md b/errors/err_stdout_close.md similarity index 100% rename from api-docs/2cfccb9b7de87232d107ee86fafd91c895a72c83d1948ed98066ed042e2b9581.md rename to errors/err_stdout_close.md diff --git a/api-docs/c73278ef04ece8b06bba8c85d4ac07e0ea2dbe98cbc4ca9351214e36c864957c.md b/errors/err_stream_cannot_pipe.md similarity index 100% rename from api-docs/c73278ef04ece8b06bba8c85d4ac07e0ea2dbe98cbc4ca9351214e36c864957c.md rename to errors/err_stream_cannot_pipe.md diff --git a/api-docs/87cab49be1f7ce26dc9e9a6d4d66e00e365aaf4256863c763825b5621b754766.md b/errors/err_stream_destroyed.md similarity index 100% rename from api-docs/87cab49be1f7ce26dc9e9a6d4d66e00e365aaf4256863c763825b5621b754766.md rename to errors/err_stream_destroyed.md diff --git a/api-docs/b31269b796eb3a03be9c9156f01dfb0f52eb808587c3847127aa0eaee7c6b71d.md b/errors/err_stream_has_stringdecoder.md similarity index 100% rename from api-docs/b31269b796eb3a03be9c9156f01dfb0f52eb808587c3847127aa0eaee7c6b71d.md rename to errors/err_stream_has_stringdecoder.md diff --git a/api-docs/ac68603d0dbde123900e2d1b7295b7f54d870a9cb5c128c3c0fccbe455a77dea.md b/errors/err_stream_null_values.md similarity index 100% rename from api-docs/ac68603d0dbde123900e2d1b7295b7f54d870a9cb5c128c3c0fccbe455a77dea.md rename to errors/err_stream_null_values.md diff --git a/api-docs/5a43b51a727fc3419429b785b583309665849d54813fdea922b83bf41d29501a.md b/errors/err_stream_premature_close.md similarity index 100% rename from api-docs/5a43b51a727fc3419429b785b583309665849d54813fdea922b83bf41d29501a.md rename to errors/err_stream_premature_close.md diff --git a/api-docs/ee0970c996e83f0f691ca358e8389e2da48bf4419d1472d47cd71452842c1562.md b/errors/err_stream_push_after_eof.md similarity index 100% rename from api-docs/ee0970c996e83f0f691ca358e8389e2da48bf4419d1472d47cd71452842c1562.md rename to errors/err_stream_push_after_eof.md diff --git a/api-docs/f34bcc7afa922bbef307394c60180f127f99ef24d04990c7a5721b537e0ff3e0.md b/errors/err_stream_read_not_implemented.md similarity index 100% rename from api-docs/f34bcc7afa922bbef307394c60180f127f99ef24d04990c7a5721b537e0ff3e0.md rename to errors/err_stream_read_not_implemented.md diff --git a/api-docs/8d9adfbf4ddd856fe27f0ec6f962fb47789bb26248c692286bab8c991ab2ad67.md b/errors/err_stream_unshift_after_end_event.md similarity index 100% rename from api-docs/8d9adfbf4ddd856fe27f0ec6f962fb47789bb26248c692286bab8c991ab2ad67.md rename to errors/err_stream_unshift_after_end_event.md diff --git a/api-docs/061b9671ae5971fd02f18affdcdeda5d9d1cf256201b51fe80ee3f9fd051af5d.md b/errors/err_stream_wrap.md similarity index 100% rename from api-docs/061b9671ae5971fd02f18affdcdeda5d9d1cf256201b51fe80ee3f9fd051af5d.md rename to errors/err_stream_wrap.md diff --git a/api-docs/f91f2941ad8f2bad0adc14c00a5e979845d3b8fabc07c1774f7604b561094e7b.md b/errors/err_stream_write_after_end.md similarity index 100% rename from api-docs/f91f2941ad8f2bad0adc14c00a5e979845d3b8fabc07c1774f7604b561094e7b.md rename to errors/err_stream_write_after_end.md diff --git a/api-docs/474ad254908c7ba43285c86746236820e6b8b8dd0df86bf9dcdc38e0166bee81.md b/errors/err_string_too_large.md similarity index 100% rename from api-docs/474ad254908c7ba43285c86746236820e6b8b8dd0df86bf9dcdc38e0166bee81.md rename to errors/err_string_too_large.md diff --git a/api-docs/3b3ed4967166e72e8a584a34ec660ce68863bccd04500ec5ac8da6f178993b92.md b/errors/err_string_too_long.md similarity index 100% rename from api-docs/3b3ed4967166e72e8a584a34ec660ce68863bccd04500ec5ac8da6f178993b92.md rename to errors/err_string_too_long.md diff --git a/api-docs/16bcb3ec0458a30b2ef26d5909a358064f70583a211febd82ec41baa15107007.md b/errors/err_system_error.md similarity index 100% rename from api-docs/16bcb3ec0458a30b2ef26d5909a358064f70583a211febd82ec41baa15107007.md rename to errors/err_system_error.md diff --git a/api-docs/f168154537304b781c7305dd683b67b933d330693ea61a16cff847ac88baab57.md b/errors/err_tls_cert_altname_invalid.md similarity index 100% rename from api-docs/f168154537304b781c7305dd683b67b933d330693ea61a16cff847ac88baab57.md rename to errors/err_tls_cert_altname_invalid.md diff --git a/api-docs/6cf4ec0d67d77a602ae8be6f8a6f0b78d4925cccbc0e5b9baeefe3633bed2790.md b/errors/err_tls_dh_param_size.md similarity index 100% rename from api-docs/6cf4ec0d67d77a602ae8be6f8a6f0b78d4925cccbc0e5b9baeefe3633bed2790.md rename to errors/err_tls_dh_param_size.md diff --git a/api-docs/aba5d2455434418d5e112376eedbbcd9f112bde4b70476dda5969fb8edae43ca.md b/errors/err_tls_handshake_timeout.md similarity index 100% rename from api-docs/aba5d2455434418d5e112376eedbbcd9f112bde4b70476dda5969fb8edae43ca.md rename to errors/err_tls_handshake_timeout.md diff --git a/api-docs/ca2aa5dc8e9cd1631409b081033bebe1a023a585dda16a3c9c20295339ebf88b.md b/errors/err_tls_invalid_protocol_version.md similarity index 100% rename from api-docs/ca2aa5dc8e9cd1631409b081033bebe1a023a585dda16a3c9c20295339ebf88b.md rename to errors/err_tls_invalid_protocol_version.md diff --git a/api-docs/c197032cdf8d5719e6cc50b6b6582b11951f3f408969323f6632f4516e2f6251.md b/errors/err_tls_protocol_version_conflict.md similarity index 100% rename from api-docs/c197032cdf8d5719e6cc50b6b6582b11951f3f408969323f6632f4516e2f6251.md rename to errors/err_tls_protocol_version_conflict.md diff --git a/api-docs/ad93a8419ff7222496aac5b54d61847fcee32d55a859d34c0525a462f3628fed.md b/errors/err_tls_renegotiate.md similarity index 100% rename from api-docs/ad93a8419ff7222496aac5b54d61847fcee32d55a859d34c0525a462f3628fed.md rename to errors/err_tls_renegotiate.md diff --git a/api-docs/5c1870c4f4fabdc1901674634de068ddd606a1504a852961e498caf517e835a0.md b/errors/err_tls_renegotiation_disabled.md similarity index 100% rename from api-docs/5c1870c4f4fabdc1901674634de068ddd606a1504a852961e498caf517e835a0.md rename to errors/err_tls_renegotiation_disabled.md diff --git a/api-docs/c3a4511c3cfa01a803d60e30f85c3b4b10974a2046f4c2c4908c749db44b658d.md b/errors/err_tls_renegotiation_failed.md similarity index 100% rename from api-docs/c3a4511c3cfa01a803d60e30f85c3b4b10974a2046f4c2c4908c749db44b658d.md rename to errors/err_tls_renegotiation_failed.md diff --git a/api-docs/99a300640caf7097ec7b7a97d00fcededce83658f103e35e877f4b243a2d3e5f.md b/errors/err_tls_required_server_name.md similarity index 100% rename from api-docs/99a300640caf7097ec7b7a97d00fcededce83658f103e35e877f4b243a2d3e5f.md rename to errors/err_tls_required_server_name.md diff --git a/api-docs/29c4cd7bfe46b6f0c140d251b874469f378756399f2e612879b2cded1f41b903.md b/errors/err_tls_session_attack.md similarity index 100% rename from api-docs/29c4cd7bfe46b6f0c140d251b874469f378756399f2e612879b2cded1f41b903.md rename to errors/err_tls_session_attack.md diff --git a/api-docs/00c0c953ff2d277659328f3e821ca03a91e2cbd08e6147c9db561c063090ae6c.md b/errors/err_tls_sni_from_server.md similarity index 100% rename from api-docs/00c0c953ff2d277659328f3e821ca03a91e2cbd08e6147c9db561c063090ae6c.md rename to errors/err_tls_sni_from_server.md diff --git a/api-docs/3aefd3d35df3d4209b25a16058c5b9074fd1bae8a664bbbf261de7ef9929e3f7.md b/errors/err_trace_events_category_required.md similarity index 100% rename from api-docs/3aefd3d35df3d4209b25a16058c5b9074fd1bae8a664bbbf261de7ef9929e3f7.md rename to errors/err_trace_events_category_required.md diff --git a/api-docs/c6418589af02f22fd83a4052ead56722b761f4a37d9a10b78689a9fea8b65284.md b/errors/err_trace_events_unavailable.md similarity index 100% rename from api-docs/c6418589af02f22fd83a4052ead56722b761f4a37d9a10b78689a9fea8b65284.md rename to errors/err_trace_events_unavailable.md diff --git a/api-docs/1c37ffcb399caf9b4006aab28b0a490d4df590deb5ad7f4c5832cd1a1ba1ad2a.md b/errors/err_transferring_externalized_sharedarraybuffer.md similarity index 100% rename from api-docs/1c37ffcb399caf9b4006aab28b0a490d4df590deb5ad7f4c5832cd1a1ba1ad2a.md rename to errors/err_transferring_externalized_sharedarraybuffer.md diff --git a/api-docs/3ee45b345cd67add3775a008c0a41e869ef0ef54994ca46b979f98b9261c5151.md b/errors/err_transform_already_transforming.md similarity index 100% rename from api-docs/3ee45b345cd67add3775a008c0a41e869ef0ef54994ca46b979f98b9261c5151.md rename to errors/err_transform_already_transforming.md diff --git a/api-docs/11cc56db912e622827e80b41c2b619ac9308552b43947b74d10527b2051fcd65.md b/errors/err_transform_with_length_0.md similarity index 100% rename from api-docs/11cc56db912e622827e80b41c2b619ac9308552b43947b74d10527b2051fcd65.md rename to errors/err_transform_with_length_0.md diff --git a/api-docs/9d1be1dbc0c302fd69cb08143403efbd36a33b920c089895fc0a5bf7f6d583cf.md b/errors/err_tty_init_failed.md similarity index 100% rename from api-docs/9d1be1dbc0c302fd69cb08143403efbd36a33b920c089895fc0a5bf7f6d583cf.md rename to errors/err_tty_init_failed.md diff --git a/api-docs/efbb1abd300ac22c2778d507aed62e21af8a6268fad549abc23495bdff215120.md b/errors/err_uncaught_exception_capture_already_set.md similarity index 100% rename from api-docs/efbb1abd300ac22c2778d507aed62e21af8a6268fad549abc23495bdff215120.md rename to errors/err_uncaught_exception_capture_already_set.md diff --git a/api-docs/f1a9300291f9ae5dd1965819ad661b443c158f5acb542c2b9aaecadd0e92135f.md b/errors/err_unescaped_characters.md similarity index 100% rename from api-docs/f1a9300291f9ae5dd1965819ad661b443c158f5acb542c2b9aaecadd0e92135f.md rename to errors/err_unescaped_characters.md diff --git a/api-docs/f70f383052778487011ce646a63a589b1697eae009793c36e747daf4d5be9255.md b/errors/err_unhandled_error.md similarity index 100% rename from api-docs/f70f383052778487011ce646a63a589b1697eae009793c36e747daf4d5be9255.md rename to errors/err_unhandled_error.md diff --git a/api-docs/ba17fb12bd93039fffe774e3e117cc34c00e08b50cc0a31157c2ff19d2672923.md b/errors/err_unknown_builtin_module.md similarity index 100% rename from api-docs/ba17fb12bd93039fffe774e3e117cc34c00e08b50cc0a31157c2ff19d2672923.md rename to errors/err_unknown_builtin_module.md diff --git a/api-docs/cf4457c54fb76283ec8cdf0f31a2bd638cb17687dac6a9dd861afd9f5f492821.md b/errors/err_unknown_builtin_module_1.md similarity index 100% rename from api-docs/cf4457c54fb76283ec8cdf0f31a2bd638cb17687dac6a9dd861afd9f5f492821.md rename to errors/err_unknown_builtin_module_1.md diff --git a/api-docs/3993c3642ebaac4e810a9746bf174eaa4be07f20cde928ad8c38070bbc392c20.md b/errors/err_unknown_encoding.md similarity index 100% rename from api-docs/3993c3642ebaac4e810a9746bf174eaa4be07f20cde928ad8c38070bbc392c20.md rename to errors/err_unknown_encoding.md diff --git a/errors/err_unknown_file_extension.md b/errors/err_unknown_file_extension.md new file mode 100644 index 00000000..be1e7a9e --- /dev/null +++ b/errors/err_unknown_file_extension.md @@ -0,0 +1,7 @@ + +> Stability: 1 - Experimental + +An attempt was made to load a module with an unknown or unsupported file +extension. + + diff --git a/errors/err_unknown_module_format.md b/errors/err_unknown_module_format.md new file mode 100644 index 00000000..856d43f1 --- /dev/null +++ b/errors/err_unknown_module_format.md @@ -0,0 +1,6 @@ + +> Stability: 1 - Experimental + +An attempt was made to load a module with an unknown or unsupported format. + + diff --git a/api-docs/2bf383eacb1cabd84470250c6dc267a446b16b678523ee9c32f6b11725dbb543.md b/errors/err_unknown_signal.md similarity index 100% rename from api-docs/2bf383eacb1cabd84470250c6dc267a446b16b678523ee9c32f6b11725dbb543.md rename to errors/err_unknown_signal.md diff --git a/api-docs/f864de1debcff59925a041eecd53a4393ad8977e4216bf3f1f187b0d7b1e874a.md b/errors/err_unknown_stdin_type.md similarity index 100% rename from api-docs/f864de1debcff59925a041eecd53a4393ad8977e4216bf3f1f187b0d7b1e874a.md rename to errors/err_unknown_stdin_type.md diff --git a/api-docs/ce785cfb4458094aedc4db745b09ed9daada7b572c086b96b83449389209fe86.md b/errors/err_unknown_stream_type.md similarity index 100% rename from api-docs/ce785cfb4458094aedc4db745b09ed9daada7b572c086b96b83449389209fe86.md rename to errors/err_unknown_stream_type.md diff --git a/api-docs/cc5c3a0b0ebbb98a0ea1a7d182d7e2eebe578dedcd404f5ed341e0fea26f9763.md b/errors/err_v8breakiterator.md similarity index 100% rename from api-docs/cc5c3a0b0ebbb98a0ea1a7d182d7e2eebe578dedcd404f5ed341e0fea26f9763.md rename to errors/err_v8breakiterator.md diff --git a/api-docs/c5beb17361d3b478515894f45ebeeb23f58a5057b0be06918795bc3ca09663ce.md b/errors/err_valid_performance_entry_type.md similarity index 100% rename from api-docs/c5beb17361d3b478515894f45ebeeb23f58a5057b0be06918795bc3ca09663ce.md rename to errors/err_valid_performance_entry_type.md diff --git a/api-docs/b0da610fa4617be6178a7c494dd82703e00f65683b84055f81845cd970995080.md b/errors/err_value_out_of_range.md similarity index 100% rename from api-docs/b0da610fa4617be6178a7c494dd82703e00f65683b84055f81845cd970995080.md rename to errors/err_value_out_of_range.md diff --git a/api-docs/5e5165fa798b44dd109a4c1551d9ad3b43b1b1b3182ea1e8eeacec73dca2d5a2.md b/errors/err_vm_dynamic_import_callback_missing.md similarity index 100% rename from api-docs/5e5165fa798b44dd109a4c1551d9ad3b43b1b1b3182ea1e8eeacec73dca2d5a2.md rename to errors/err_vm_dynamic_import_callback_missing.md diff --git a/api-docs/25fc287d897208814e8048d04e335e7001d45a21830865c360b8bf47bb8cf6ca.md b/errors/err_vm_module_already_linked.md similarity index 100% rename from api-docs/25fc287d897208814e8048d04e335e7001d45a21830865c360b8bf47bb8cf6ca.md rename to errors/err_vm_module_already_linked.md diff --git a/api-docs/4e2b32a4909db62f7d68f20150c37fd43673c19275b0803607f15b61fa3a7185.md b/errors/err_vm_module_different_context.md similarity index 100% rename from api-docs/4e2b32a4909db62f7d68f20150c37fd43673c19275b0803607f15b61fa3a7185.md rename to errors/err_vm_module_different_context.md diff --git a/api-docs/9ad116a893265fc4bc3a7a55e915a923f29e1a6de50342ef321209567da31c01.md b/errors/err_vm_module_linking_errored.md similarity index 100% rename from api-docs/9ad116a893265fc4bc3a7a55e915a923f29e1a6de50342ef321209567da31c01.md rename to errors/err_vm_module_linking_errored.md diff --git a/api-docs/02443124edb28bd8a62b393d552047ab68e1507a283ccb0057c55a743df30dea.md b/errors/err_vm_module_not_linked.md similarity index 100% rename from api-docs/02443124edb28bd8a62b393d552047ab68e1507a283ccb0057c55a743df30dea.md rename to errors/err_vm_module_not_linked.md diff --git a/api-docs/57709aa0d0cac87d982a0dd17345ecee6ccd27c265a6d2c56edcf56e26160928.md b/errors/err_vm_module_not_module.md similarity index 100% rename from api-docs/57709aa0d0cac87d982a0dd17345ecee6ccd27c265a6d2c56edcf56e26160928.md rename to errors/err_vm_module_not_module.md diff --git a/api-docs/cf5baa6a7dac32c764e8e0715efd96b4e216e73ebd2bd9a339a9281e8507e495.md b/errors/err_vm_module_status.md similarity index 100% rename from api-docs/cf5baa6a7dac32c764e8e0715efd96b4e216e73ebd2bd9a339a9281e8507e495.md rename to errors/err_vm_module_status.md diff --git a/api-docs/0dfbacf598c1b788c4b66722a473dbf326b126a725c37613df70f0eb3325cc60.md b/errors/err_worker_path.md similarity index 100% rename from api-docs/0dfbacf598c1b788c4b66722a473dbf326b126a725c37613df70f0eb3325cc60.md rename to errors/err_worker_path.md diff --git a/api-docs/86cfb6486d4a379bb234f0cb948960a71631425ba3a209c8d16a90a315d51eb0.md b/errors/err_worker_unserializable_error.md similarity index 100% rename from api-docs/86cfb6486d4a379bb234f0cb948960a71631425ba3a209c8d16a90a315d51eb0.md rename to errors/err_worker_unserializable_error.md diff --git a/api-docs/9ce9cd14a8526f5ad974c244fce919050316f9badb96dc59336580ffd8b94d97.md b/errors/err_worker_unsupported_extension.md similarity index 100% rename from api-docs/9ce9cd14a8526f5ad974c244fce919050316f9badb96dc59336580ffd8b94d97.md rename to errors/err_worker_unsupported_extension.md diff --git a/api-docs/b5c2c6ed1fb47488051d216da3d262ef507f3ca03191d341c53cd92fca53e82b.md b/errors/err_zlib_binding_closed.md similarity index 100% rename from api-docs/b5c2c6ed1fb47488051d216da3d262ef507f3ca03191d341c53cd92fca53e82b.md rename to errors/err_zlib_binding_closed.md diff --git a/api-docs/c7bcb225d5a972b184da703ca39393fb20bc7777a7267f2b0a7c8d5acdeae8bb.md b/errors/err_zlib_initialization_failed.md similarity index 100% rename from api-docs/c7bcb225d5a972b184da703ca39393fb20bc7777a7267f2b0a7c8d5acdeae8bb.md rename to errors/err_zlib_initialization_failed.md diff --git a/api-docs/8b84b3d13bc104e57c96aa91c170a2ce23cdcea0cc3bb4ff31caff8f45410d77.md b/errors/error_address.md similarity index 100% rename from api-docs/8b84b3d13bc104e57c96aa91c170a2ce23cdcea0cc3bb4ff31caff8f45410d77.md rename to errors/error_address.md diff --git a/api-docs/0cfc7d0ceacddd71d1e225283a348dc4d1b76875c1ecc4820a90cb31ceaea79b.md b/errors/error_capturestacktrace_targetobject_constructoropt.md similarity index 100% rename from api-docs/0cfc7d0ceacddd71d1e225283a348dc4d1b76875c1ecc4820a90cb31ceaea79b.md rename to errors/error_capturestacktrace_targetobject_constructoropt.md diff --git a/api-docs/607cc51def3469e46bc6d203e9d8990e428ed47c92a11d0da7773cad7d46dd5d.md b/errors/error_code.md similarity index 100% rename from api-docs/607cc51def3469e46bc6d203e9d8990e428ed47c92a11d0da7773cad7d46dd5d.md rename to errors/error_code.md diff --git a/api-docs/5bdce66aa160ceaee1fd1c61677a8519669203c1b9c0824b9d8b75b061866b3e.md b/errors/error_code_1.md similarity index 100% rename from api-docs/5bdce66aa160ceaee1fd1c61677a8519669203c1b9c0824b9d8b75b061866b3e.md rename to errors/error_code_1.md diff --git a/api-docs/a9b8865df31a053bbec26bd0aead59c9c52e8f94e54d47f6cb2fbccd76628442.md b/errors/error_dest.md similarity index 100% rename from api-docs/a9b8865df31a053bbec26bd0aead59c9c52e8f94e54d47f6cb2fbccd76628442.md rename to errors/error_dest.md diff --git a/api-docs/a97e4da379accd78e454f99c861bcbed0ac3fb6ce0b53df478316427a4ad4f7e.md b/errors/error_errno.md similarity index 100% rename from api-docs/a97e4da379accd78e454f99c861bcbed0ac3fb6ce0b53df478316427a4ad4f7e.md rename to errors/error_errno.md diff --git a/api-docs/4908d79276a6f8889a038ef3cff14798627a512e0bcae25ead54626d76d3f9b8.md b/errors/error_first_callbacks.md similarity index 100% rename from api-docs/4908d79276a6f8889a038ef3cff14798627a512e0bcae25ead54626d76d3f9b8.md rename to errors/error_first_callbacks.md diff --git a/api-docs/4284d71dd60fea05b28f2325775240dd2f5e9a18d3b229a05069cddf32bea5f9.md b/errors/error_info.md similarity index 100% rename from api-docs/4284d71dd60fea05b28f2325775240dd2f5e9a18d3b229a05069cddf32bea5f9.md rename to errors/error_info.md diff --git a/api-docs/cb47073085e3b45c56033987767612587d9dad15fe4a6b33b8719df399e89b9d.md b/errors/error_message.md similarity index 100% rename from api-docs/cb47073085e3b45c56033987767612587d9dad15fe4a6b33b8719df399e89b9d.md rename to errors/error_message.md diff --git a/api-docs/4075edc6f3ac329d24be038f159ab0018f9150aa62eb42e2651262703016004e.md b/errors/error_message_1.md similarity index 100% rename from api-docs/4075edc6f3ac329d24be038f159ab0018f9150aa62eb42e2651262703016004e.md rename to errors/error_message_1.md diff --git a/api-docs/4648e8fac9eb69bb7fd076ea2b65f18f6b3cc718a542b1232f7b8e688439d28b.md b/errors/error_path.md similarity index 100% rename from api-docs/4648e8fac9eb69bb7fd076ea2b65f18f6b3cc718a542b1232f7b8e688439d28b.md rename to errors/error_path.md diff --git a/api-docs/f921f4878ca811a1e6b5f111cf858a7e92fe84f4d66ba47b1cdae55828b6fa8a.md b/errors/error_port.md similarity index 100% rename from api-docs/f921f4878ca811a1e6b5f111cf858a7e92fe84f4d66ba47b1cdae55828b6fa8a.md rename to errors/error_port.md diff --git a/api-docs/587f7cf3ac011fddd62e7ec96aae217dd468de273c712a88c4732224ceb6be44.md b/errors/error_propagation_and_interception.md similarity index 100% rename from api-docs/587f7cf3ac011fddd62e7ec96aae217dd468de273c712a88c4732224ceb6be44.md rename to errors/error_propagation_and_interception.md diff --git a/api-docs/25232f4e73d27e17ae177624debf6f01e7ca298d00a5da07603fd3de93f5a2f5.md b/errors/error_stack.md similarity index 100% rename from api-docs/25232f4e73d27e17ae177624debf6f01e7ca298d00a5da07603fd3de93f5a2f5.md rename to errors/error_stack.md diff --git a/api-docs/9eb6e7358cedd8a5a8272c147b2a9d9bfa2fb8018db98e66595e178233d06472.md b/errors/error_stacktracelimit.md similarity index 100% rename from api-docs/9eb6e7358cedd8a5a8272c147b2a9d9bfa2fb8018db98e66595e178233d06472.md rename to errors/error_stacktracelimit.md diff --git a/api-docs/4adb356b77c21eafe7d6e42556dd842bbe2a4ffece0f5d70a1eac0740d285bae.md b/errors/error_syscall.md similarity index 100% rename from api-docs/4adb356b77c21eafe7d6e42556dd842bbe2a4ffece0f5d70a1eac0740d285bae.md rename to errors/error_syscall.md diff --git a/api-docs/b3489149fc80e6c447c4e37afe8f0551cc4db75fd2da6aeffdba4d21d5fb76ff.md b/errors/errors.md similarity index 100% rename from api-docs/b3489149fc80e6c447c4e37afe8f0551cc4db75fd2da6aeffdba4d21d5fb76ff.md rename to errors/errors.md diff --git a/api-docs/997b276304aab6d9971c28eb8ed4c71770c0215f335db60809a35607fbde4b1e.md b/errors/exceptions_vs_errors.md similarity index 100% rename from api-docs/997b276304aab6d9971c28eb8ed4c71770c0215f335db60809a35607fbde4b1e.md rename to errors/exceptions_vs_errors.md diff --git a/api-docs/21bd47647b3355031d4745bf6a1c837d0b6e3798c30b521134ddfc320305a825.md b/errors/hpe_header_overflow.md similarity index 100% rename from api-docs/21bd47647b3355031d4745bf6a1c837d0b6e3798c30b521134ddfc320305a825.md rename to errors/hpe_header_overflow.md diff --git a/errors/legacy_node_js_error_codes.md b/errors/legacy_node_js_error_codes.md new file mode 100644 index 00000000..c6a88f55 --- /dev/null +++ b/errors/legacy_node_js_error_codes.md @@ -0,0 +1,5 @@ + +> Stability: 0 - Deprecated. These error codes are either inconsistent, or have +> been removed. + + diff --git a/api-docs/dd88bdcfb59e79665176bf6fd3286ca574bbaf702128380628366c214710d110.md b/errors/module_not_found.md similarity index 100% rename from api-docs/dd88bdcfb59e79665176bf6fd3286ca574bbaf702128380628366c214710d110.md rename to errors/module_not_found.md diff --git a/api-docs/238c24882f46f6969bc56d26ffc15920978bcdfc3ab7aa09434b47d167e7529d.md b/errors/new_error_message.md similarity index 100% rename from api-docs/238c24882f46f6969bc56d26ffc15920978bcdfc3ab7aa09434b47d167e7529d.md rename to errors/new_error_message.md diff --git a/api-docs/14257961305fc17459af21429fde2aaa4a6110b490ff98089252f3f41758f7f2.md b/errors/node_js_error_codes.md similarity index 100% rename from api-docs/14257961305fc17459af21429fde2aaa4a6110b490ff98089252f3f41758f7f2.md rename to errors/node_js_error_codes.md diff --git a/api-docs/e0168750c4c19589df05eb0bee6012b49b3348b219674b8107327c846a6489f3.md b/errors/other_error_codes.md similarity index 100% rename from api-docs/e0168750c4c19589df05eb0bee6012b49b3348b219674b8107327c846a6489f3.md rename to errors/other_error_codes.md diff --git a/api-docs/e05ab3c2b99e2dc40940136a7917ead34364c171713bf62448f1d51a2cabb188.md b/errors/system_errors.md similarity index 100% rename from api-docs/e05ab3c2b99e2dc40940136a7917ead34364c171713bf62448f1d51a2cabb188.md rename to errors/system_errors.md diff --git a/esm/builtin_modules.md b/esm/builtin_modules.md new file mode 100644 index 00000000..411bd347 --- /dev/null +++ b/esm/builtin_modules.md @@ -0,0 +1,30 @@ + +Builtin modules will provide named exports of their public API, as well as a +default export which can be used for, among other things, modifying the named +exports. Named exports of builtin modules are updated when the corresponding +exports property is accessed, redefined, or deleted. + +```js +import EventEmitter from 'events'; +const e = new EventEmitter(); +``` + +```js +import { readFile } from 'fs'; +readFile('./foo.txt', (err, source) => { + if (err) { + console.error(err); + } else { + console.log(source); + } +}); +``` + +```js +import fs, { readFileSync } from 'fs'; + +fs.readFileSync = () => Buffer.from('Hello, ESM'); + +fs.readFileSync === readFileSync; +``` + diff --git a/esm/code_import_code_expressions.md b/esm/code_import_code_expressions.md new file mode 100644 index 00000000..d8507d13 --- /dev/null +++ b/esm/code_import_code_expressions.md @@ -0,0 +1,10 @@ + +Dynamic `import()` is supported in both CommonJS and ES modules. It can be used +to include ES module files from CommonJS code. + +```js +(async () => { + await import('./my-app.mjs'); +})(); +``` + diff --git a/api-docs/b5dca4050e8eb308236bfbc27c382d3c407e020a1f6ecc8499e318899ab6525e.md b/esm/code_import_code_specifiers.md similarity index 100% rename from api-docs/b5dca4050e8eb308236bfbc27c382d3c407e020a1f6ecc8499e318899ab6525e.md rename to esm/code_import_code_specifiers.md diff --git a/esm/code_import_code_statements.md b/esm/code_import_code_statements.md new file mode 100644 index 00000000..c00bd282 --- /dev/null +++ b/esm/code_import_code_statements.md @@ -0,0 +1,31 @@ + +An `import` statement can reference either ES module or CommonJS JavaScript. +Other file types such as JSON and Native modules are not supported. For those, +use [`module.createRequire()`][]. + +`import` statements are permitted only in ES modules. For similar functionality +in CommonJS, see [`import()`][]. + +The _specifier_ of an `import` statement (the string after the `from` keyword) +can either be an URL-style relative path like `'./file.mjs'` or a package name +like `'fs'`. + +Like in CommonJS, files within packages can be accessed by appending a path to +the package name. + +```js +import { sin, cos } from 'geometry/trigonometry-functions.mjs'; +``` + +> Currently only the “default export” is supported for CommonJS files or +> packages: +> +> +> ```js +> import packageMain from 'commonjs-package'; // Works +> +> import { method } from 'commonjs-package'; // Errors +> ``` +> +> There are ongoing efforts to make the latter code possible. + diff --git a/esm/code_input_type_code_flag.md b/esm/code_input_type_code_flag.md new file mode 100644 index 00000000..556a327c --- /dev/null +++ b/esm/code_input_type_code_flag.md @@ -0,0 +1,17 @@ + +Strings passed in as an argument to `--eval` or `--print` (or `-e` or `-p`), or +piped to `node` via `STDIN`, will be treated as ES modules when the +`--input-type=module` flag is set. + +```sh +node --experimental-modules --input-type=module --eval \ + "import { sep } from 'path'; console.log(sep);" + +echo "import { sep } from 'path'; console.log(sep);" | \ + node --experimental-modules --input-type=module +``` + +For completeness there is also `--input-type=commonjs`, for explicitly running +string input as CommonJS. This is the default behavior if `--input-type` is +unspecified. + diff --git a/esm/code_package_json_code_code_type_code_field.md b/esm/code_package_json_code_code_type_code_field.md new file mode 100644 index 00000000..f1d298db --- /dev/null +++ b/esm/code_package_json_code_code_type_code_field.md @@ -0,0 +1,18 @@ + +Files ending with `.js` or `.mjs`, or lacking any extension, +will be loaded as ES modules when the nearest parent `package.json` file +contains a top-level field `"type"` with a value of `"module"`. + +The nearest parent `package.json` is defined as the first `package.json` found +when searching in the current folder, that folder’s parent, and so on up +until the root of the volume is reached. + + +```js +// package.json +{ + "type": "module" +} +``` + +```sh diff --git a/esm/code_require_code.md b/esm/code_require_code.md new file mode 100644 index 00000000..1eed2fac --- /dev/null +++ b/esm/code_require_code.md @@ -0,0 +1,7 @@ + +`require` always treats the files it references as CommonJS. This applies +whether `require` is used the traditional way within a CommonJS environment, or +in an ES module environment using [`module.createRequire()`][]. + +To include an ES module into CommonJS, use [`import()`][]. + diff --git a/esm/commonjs_json_and_native_modules.md b/esm/commonjs_json_and_native_modules.md new file mode 100644 index 00000000..4068b7e1 --- /dev/null +++ b/esm/commonjs_json_and_native_modules.md @@ -0,0 +1,18 @@ + +CommonJS, JSON, and Native modules can be used with +[`module.createRequire()`][]. + +```js +// cjs.js +module.exports = 'cjs'; + +// esm.mjs +import { createRequire } from 'module'; +import { fileURLToPath as fromURL } from 'url'; + +const require = createRequire(fromURL(import.meta.url)); + +const cjs = require('./cjs'); +cjs === 'cjs'; // true +``` + diff --git a/esm/customizing_esm_specifier_resolution_algorithm.md b/esm/customizing_esm_specifier_resolution_algorithm.md new file mode 100644 index 00000000..8fe203ae --- /dev/null +++ b/esm/customizing_esm_specifier_resolution_algorithm.md @@ -0,0 +1,33 @@ + +The current specifier resolution does not support all default behavior of +the CommonJS loader. One of the behavior differences is automatic resolution +of file extensions and the ability to import directories that have an index +file. + +The `--es-module-specifier-resolution=[mode]` flag can be used to customize +the extension resolution algorithm. The default mode is `explicit`, which +requires the full path to a module be provided to the loader. To enable the +automatic extension resolution and importing from directories that include an +index file use the `node` mode. + +```bash +$ node --experimental-modules index.mjs +success! +$ node --experimental-modules index #Failure! +Error: Cannot find module +$ node --experimental-modules --es-module-specifier-resolution=node index +success! +``` + + + + + + + + + + + + + diff --git a/api-docs/d91efa0a5273c855ff4e0dfc868429a98c81427c4d5748c13d4d180befca9c25.md b/esm/differences_between_es_modules_and_commonjs.md similarity index 100% rename from api-docs/d91efa0a5273c855ff4e0dfc868429a98c81427c4d5748c13d4d180befca9c25.md rename to esm/differences_between_es_modules_and_commonjs.md diff --git a/api-docs/5c343324d2cf8c7af7bce8c2e0e36bf53bd97b95a4650711b7e65cc650fe679a.md b/esm/dynamic_instantiate_hook.md similarity index 90% rename from api-docs/5c343324d2cf8c7af7bce8c2e0e36bf53bd97b95a4650711b7e65cc650fe679a.md rename to esm/dynamic_instantiate_hook.md index 838099fe..4ddd108e 100644 --- a/api-docs/5c343324d2cf8c7af7bce8c2e0e36bf53bd97b95a4650711b7e65cc650fe679a.md +++ b/esm/dynamic_instantiate_hook.md @@ -9,7 +9,7 @@ export async function dynamicInstantiate(url) { return { exports: ['customExportName'], execute: (exports) => { - // get and set functions provided for pre-allocated export names + // Get and set functions provided for pre-allocated export names exports.customExportName.set('value'); } }; @@ -20,6 +20,3 @@ With the list of module exports provided upfront, the `execute` function will then be called at the exact point of module evaluation order for that module in the import tree. - - - diff --git a/esm/ecmascript_modules.md b/esm/ecmascript_modules.md new file mode 100644 index 00000000..54035bd9 --- /dev/null +++ b/esm/ecmascript_modules.md @@ -0,0 +1,6 @@ + + + + +> Stability: 1 - Experimental + diff --git a/esm/enabling.md b/esm/enabling.md new file mode 100644 index 00000000..1175f71a --- /dev/null +++ b/esm/enabling.md @@ -0,0 +1,36 @@ + + + +The `--experimental-modules` flag can be used to enable support for +ECMAScript modules (ES modules). + +Once enabled, Node.js will treat the following as ES modules when passed to +`node` as the initial input, or when referenced by `import` statements within +ES module code: + +- Files ending in `.mjs`. + +- Files ending in `.js`, or extensionless files, when the nearest parent + `package.json` file contains a top-level field `"type"` with a value of + `"module"`. + +- Strings passed in as an argument to `--eval` or `--print`, or piped to + `node` via `STDIN`, with the flag `--input-type=module`. + +Node.js will treat as CommonJS all other forms of input, such as `.js` files +where the nearest parent `package.json` file contains no top-level `"type"` +field, or string input without the flag `--input-type`. This behavior is to +preserve backward compatibility. However, now that Node.js supports both +CommonJS and ES modules, it is best to be explicit whenever possible. Node.js +will treat the following as CommonJS when passed to `node` as the initial input, +or when referenced by `import` statements within ES module code: + +- Files ending in `.cjs`. + +- Files ending in `.js`, or extensionless files, when the nearest parent + `package.json` file contains a top-level field `"type"` with a value of + `"commonjs"`. + +- Strings passed in as an argument to `--eval` or `--print`, or piped to + `node` via `STDIN`, with the flag `--input-type=commonjs`. + diff --git a/esm/experimental_loader_hooks.md b/esm/experimental_loader_hooks.md new file mode 100644 index 00000000..07e7001c --- /dev/null +++ b/esm/experimental_loader_hooks.md @@ -0,0 +1,11 @@ + +**Note: This API is currently being redesigned and will still change.** + + + +To customize the default module resolution, loader hooks can optionally be +provided via a `--loader ./loader-name.mjs` argument to Node.js. + +When hooks are used they only apply to ES module loading and not to any +CommonJS modules loaded. + diff --git a/esm/experimental_wasm_modules.md b/esm/experimental_wasm_modules.md new file mode 100644 index 00000000..8a1db3aa --- /dev/null +++ b/esm/experimental_wasm_modules.md @@ -0,0 +1,23 @@ + +Importing Web Assembly modules is supported under the +`--experimental-wasm-modules` flag, allowing any `.wasm` files to be +imported as normal modules while also supporting their module imports. + +This integration is in line with the +[ES Module Integration Proposal for Web Assembly][]. + +For example, an `index.mjs` containing: + +```js +import * as M from './module.wasm'; +console.log(M); +``` + +executed under: + +```bash +node --experimental-modules --experimental-wasm-modules index.mjs +``` + +would provide the exports interface for the instantiation of `module.wasm`. + diff --git a/esm/features.md b/esm/features.md new file mode 100644 index 00000000..d23815f8 --- /dev/null +++ b/esm/features.md @@ -0,0 +1,10 @@ + +The resolver has the following properties: + +* FileURL-based resolution as is used by ES modules +* Support for builtin module loading +* Relative and absolute URL resolution +* No default extensions +* No folder mains +* Bare specifier package resolution lookup through node_modules + diff --git a/esm/import_meta.md b/esm/import_meta.md new file mode 100644 index 00000000..77191625 --- /dev/null +++ b/esm/import_meta.md @@ -0,0 +1,8 @@ + +* {Object} + +The `import.meta` metaproperty is an `Object` that contains the following +property: + +* `url` {string} The absolute `file:` URL of the module. + diff --git a/esm/in_same_folder_as_above_package_json.md b/esm/in_same_folder_as_above_package_json.md new file mode 100644 index 00000000..7616af69 --- /dev/null +++ b/esm/in_same_folder_as_above_package_json.md @@ -0,0 +1,17 @@ +node --experimental-modules my-app.js # Runs as ES module +``` + +If the nearest parent `package.json` lacks a `"type"` field, or contains +`"type": "commonjs"`, extensionless and `.js` files are treated as CommonJS. +If the volume root is reached and no `package.json` is found, +Node.js defers to the default, a `package.json` with no `"type"` +field. + +`import` statements of `.js` and extensionless files are treated as ES modules +if the nearest parent `package.json` contains `"type": "module"`. + +```js +// my-app.js, part of the same example as above +import './startup.js'; // Loaded as ES module because of package.json +``` + diff --git a/esm/interop_with_existing_modules.md b/esm/interop_with_existing_modules.md new file mode 100644 index 00000000..c2d4e8aa --- /dev/null +++ b/esm/interop_with_existing_modules.md @@ -0,0 +1,47 @@ + +All CommonJS, JSON, and C++ modules can be used with `import`. + +Modules loaded this way will only be loaded once, even if their query +or fragment string differs between `import` statements. + +When loaded via `import` these modules will provide a single `default` export +representing the value of `module.exports` at the time they finished evaluating. + +```js +// foo.js +module.exports = { one: 1 }; + +// bar.mjs +import foo from './foo.js'; +foo.one === 1; // true +``` + +Builtin modules will provide named exports of their public API, as well as a +default export which can be used for, among other things, modifying the named +exports. Named exports of builtin modules are updated when the corresponding +exports property is accessed, redefined, or deleted. + +```js +import EventEmitter from 'events'; +const e = new EventEmitter(); +``` + +```js +import { readFile } from 'fs'; +readFile('./foo.txt', (err, source) => { + if (err) { + console.error(err); + } else { + console.log(source); + } +}); +``` + +```js +import fs, { readFileSync } from 'fs'; + +fs.readFileSync = () => Buffer.from('Hello, ESM'); + +fs.readFileSync === readFileSync; +``` + diff --git a/api-docs/e7ab287e213d4f28d79feedbf35096895579c26473c13893eaf1e0139d6e1034.md b/esm/interoperability_with_commonjs.md similarity index 100% rename from api-docs/e7ab287e213d4f28d79feedbf35096895579c26473c13893eaf1e0139d6e1034.md rename to esm/interoperability_with_commonjs.md diff --git a/esm/introduction.md b/esm/introduction.md new file mode 100644 index 00000000..1b9954b7 --- /dev/null +++ b/esm/introduction.md @@ -0,0 +1,17 @@ + + + +ECMAScript modules are [the official standard format][] to package JavaScript +code for reuse. Modules are defined using a variety of [`import`][] and +[`export`][] statements. + +Node.js fully supports ECMAScript modules as they are currently specified and +provides limited interoperability between them and the existing module format, +[CommonJS][]. + +Node.js contains support for ES Modules based upon the +[Node.js EP for ES Modules][] and the [ECMAScript-modules implementation][]. + +Expect major changes in the implementation including interoperability support, +specifier resolution, and default behavior. + diff --git a/esm/json_modules.md b/esm/json_modules.md new file mode 100644 index 00000000..966a0d49 --- /dev/null +++ b/esm/json_modules.md @@ -0,0 +1,16 @@ + +JSON modules follow the [WHATWG JSON modules specification][]. + +The imported JSON only exposes a `default`. There is no +support for named exports. A cache entry is created in the CommonJS +cache, to avoid duplication. The same object will be returned in +CommonJS if the JSON module has already been imported from the +same path. + +Assuming an `index.mjs` with + + +```js +import packageConfig from './package.json'; +``` + diff --git a/esm/loader_hooks.md b/esm/loader_hooks.md new file mode 100644 index 00000000..f1c67605 --- /dev/null +++ b/esm/loader_hooks.md @@ -0,0 +1,9 @@ + + + +To customize the default module resolution, loader hooks can optionally be +provided via a `--loader ./loader-name.mjs` argument to Node.js. + +When hooks are used they only apply to ES module loading and not to any +CommonJS modules loaded. + diff --git a/esm/mandatory_file_extensions.md b/esm/mandatory_file_extensions.md new file mode 100644 index 00000000..8b33bb9a --- /dev/null +++ b/esm/mandatory_file_extensions.md @@ -0,0 +1,7 @@ + +A file extension must be provided when using the `import` keyword. Directory +indexes (e.g. `'./startup/index.js'`) must also be fully specified. + +This behavior matches how `import` behaves in browser environments, assuming a +typically configured server. + diff --git a/esm/no_code_node_path_code.md b/esm/no_code_node_path_code.md new file mode 100644 index 00000000..c2590455 --- /dev/null +++ b/esm/no_code_node_path_code.md @@ -0,0 +1,4 @@ + +`NODE_PATH` is not part of resolving `import` specifiers. Please use symlinks +if this behavior is desired. + diff --git a/esm/no_code_require_cache_code.md b/esm/no_code_require_cache_code.md new file mode 100644 index 00000000..3d3f4e13 --- /dev/null +++ b/esm/no_code_require_cache_code.md @@ -0,0 +1,3 @@ + +`require.cache` is not used by `import`. It has a separate cache. + diff --git a/esm/no_code_require_code_code_exports_code_code_module_exports_code_code_filename_code_code_dirname_code.md b/esm/no_code_require_code_code_exports_code_code_module_exports_code_code_filename_code_code_dirname_code.md new file mode 100644 index 00000000..dcaaba11 --- /dev/null +++ b/esm/no_code_require_code_code_exports_code_code_module_exports_code_code_filename_code_code_dirname_code.md @@ -0,0 +1,16 @@ + +These CommonJS variables are not available in ES modules. + +`require` can be imported into an ES module using [`module.createRequire()`][]. + +Equivalents of `__filename` and `__dirname` can be created inside of each file +via [`import.meta.url`][]. + +```js +import { fileURLToPath } from 'url'; +import { dirname } from 'path'; + +const __filename = fileURLToPath(import.meta.url); +const __dirname = dirname(__filename); +``` + diff --git a/esm/no_code_require_extensions_code.md b/esm/no_code_require_extensions_code.md new file mode 100644 index 00000000..051ece78 --- /dev/null +++ b/esm/no_code_require_extensions_code.md @@ -0,0 +1,4 @@ + +`require.extensions` is not used by `import`. The expectation is that loader +hooks can provide this workflow in the future. + diff --git a/esm/no_node_path.md b/esm/no_node_path.md new file mode 100644 index 00000000..c2590455 --- /dev/null +++ b/esm/no_node_path.md @@ -0,0 +1,4 @@ + +`NODE_PATH` is not part of resolving `import` specifiers. Please use symlinks +if this behavior is desired. + diff --git a/esm/no_require_cache.md b/esm/no_require_cache.md new file mode 100644 index 00000000..3d3f4e13 --- /dev/null +++ b/esm/no_require_cache.md @@ -0,0 +1,3 @@ + +`require.cache` is not used by `import`. It has a separate cache. + diff --git a/esm/no_require_extensions.md b/esm/no_require_extensions.md new file mode 100644 index 00000000..051ece78 --- /dev/null +++ b/esm/no_require_extensions.md @@ -0,0 +1,4 @@ + +`require.extensions` is not used by `import`. The expectation is that loader +hooks can provide this workflow in the future. + diff --git a/api-docs/ef222060d1b8e83b366f1b615d6e5a97e0f7b2c9b32f5ef65b04807351533d4b.md b/esm/notable_differences_between_import_and_require.md similarity index 100% rename from api-docs/ef222060d1b8e83b366f1b615d6e5a97e0f7b2c9b32f5ef65b04807351533d4b.md rename to esm/notable_differences_between_import_and_require.md diff --git a/esm/package_entry_points.md b/esm/package_entry_points.md new file mode 100644 index 00000000..5637b060 --- /dev/null +++ b/esm/package_entry_points.md @@ -0,0 +1,41 @@ + +The `package.json` `"main"` field defines the entry point for a package, +whether the package is included into CommonJS via `require` or into an ES +module via `import`. + + +```js +// ./node_modules/es-module-package/package.json +{ + "type": "module", + "main": "./src/index.js" +} +``` +```js +// ./my-app.mjs + +import { something } from 'es-module-package'; +// Loads from ./node_modules/es-module-package/src/index.js +``` + +An attempt to `require` the above `es-module-package` would attempt to load +`./node_modules/es-module-package/src/index.js` as CommonJS, which would throw +an error as Node.js would not be able to parse the `export` statement in +CommonJS. + +As with `import` statements, for ES module usage the value of `"main"` must be +a full path including extension: `"./index.mjs"`, not `"./index"`. + +If the `package.json` `"type"` field is omitted, a `.js` file in `"main"` will +be interpreted as CommonJS. + +The `"main"` field can point to exactly one file, regardless of whether the +package is referenced via `require` (in a CommonJS context) or `import` (in an +ES module context). Package authors who want to publish a package to be used in +both contexts can do so by setting `"main"` to point to the CommonJS entry point +and informing the package’s users of the path to the ES module entry point. Such +a package would be accessible like `require('pkg')` and `import +'pkg/module.mjs'`. Alternatively the package `"main"` could point to the ES +module entry point and legacy users could be informed of the CommonJS entry +point path, e.g. `require('pkg/commonjs')`. + diff --git a/esm/package_exports.md b/esm/package_exports.md new file mode 100644 index 00000000..3de5f3f2 --- /dev/null +++ b/esm/package_exports.md @@ -0,0 +1,54 @@ + +By default, all subpaths from a package can be imported (`import 'pkg/x.js'`). +Custom subpath aliasing and encapsulation can be provided through the +`"exports"` field. + + +```js +// ./node_modules/es-module-package/package.json +{ + "exports": { + "./submodule": "./src/submodule.js" + } +} +``` + +```js +import submodule from 'es-module-package/submodule'; +// Loads ./node_modules/es-module-package/src/submodule.js +``` + +In addition to defining an alias, subpaths not defined by `"exports"` will +throw when an attempt is made to import them: + +```js +import submodule from 'es-module-package/private-module.js'; +// Throws - Package exports error +``` + +> Note: this is not a strong encapsulation as any private modules can still be +> loaded by absolute paths. + +Folders can also be mapped with package exports as well: + + +```js +// ./node_modules/es-module-package/package.json +{ + "exports": { + "./features/": "./src/features/" + } +} +``` + +```js +import feature from 'es-module-package/features/x.js'; +// Loads ./node_modules/es-module-package/src/features/x.js +``` + +If a package has no exports, setting `"exports": false` can be used instead of +`"exports": {}` to indicate the package does not intend for submodules to be +exposed. +This is just a convention that works because `false`, just like `{}`, has no +iterable own properties. + diff --git a/esm/package_scope_and_file_extensions.md b/esm/package_scope_and_file_extensions.md new file mode 100644 index 00000000..89d3b11b --- /dev/null +++ b/esm/package_scope_and_file_extensions.md @@ -0,0 +1,58 @@ + +A folder containing a `package.json` file, and all subfolders below that +folder down until the next folder containing another `package.json`, is +considered a _package scope_. The `"type"` field defines how `.js` and +extensionless files should be treated within a particular `package.json` file’s +package scope. Every package in a project’s `node_modules` folder contains its +own `package.json` file, so each project’s dependencies have their own package +scopes. A `package.json` lacking a `"type"` field is treated as if it contained +`"type": "commonjs"`. + +The package scope applies not only to initial entry points (`node +--experimental-modules my-app.js`) but also to files referenced by `import` +statements and `import()` expressions. + +```js +// my-app.js, in an ES module package scope because there is a package.json +// file in the same folder with "type": "module". + +import './startup/init.js'; +// Loaded as ES module since ./startup contains no package.json file, +// and therefore inherits the ES module package scope from one level up. + +import 'commonjs-package'; +// Loaded as CommonJS since ./node_modules/commonjs-package/package.json +// lacks a "type" field or contains "type": "commonjs". + +import './node_modules/commonjs-package/index.js'; +// Loaded as CommonJS since ./node_modules/commonjs-package/package.json +// lacks a "type" field or contains "type": "commonjs". +``` + +Files ending with `.mjs` are always loaded as ES modules regardless of package +scope. + +Files ending with `.cjs` are always loaded as CommonJS regardless of package +scope. + +```js +import './legacy-file.cjs'; +// Loaded as CommonJS since .cjs is always loaded as CommonJS. + +import 'commonjs-package/src/index.mjs'; +// Loaded as ES module since .mjs is always loaded as ES module. +``` + +The `.mjs` and `.cjs` extensions may be used to mix types within the same +package scope: + +- Within a `"type": "module"` package scope, Node.js can be instructed to + interpret a particular file as CommonJS by naming it with a `.cjs` extension + (since both `.js` and `.mjs` files are treated as ES modules within a + `"module"` package scope). + +- Within a `"type": "commonjs"` package scope, Node.js can be instructed to + interpret a particular file as an ES module by naming it with an `.mjs` + extension (since both `.js` and `.cjs` files are treated as CommonJS within a + `"commonjs"` package scope). + diff --git a/api-docs/fb246349793d549a3bfda63a84d71f86fdd22311187ecea023e60562ed10b01e.md b/esm/resolution_algorithm.md similarity index 100% rename from api-docs/fb246349793d549a3bfda63a84d71f86fdd22311187ecea023e60562ed10b01e.md rename to esm/resolution_algorithm.md diff --git a/esm/resolve_hook.md b/esm/resolve_hook.md new file mode 100644 index 00000000..1cf4eb1c --- /dev/null +++ b/esm/resolve_hook.md @@ -0,0 +1,85 @@ + +The resolve hook returns the resolved file URL and module format for a +given module specifier and parent file URL: + +```js +const baseURL = new URL(`${process.cwd()}/`, 'file://'); + +export async function resolve(specifier, + parentModuleURL = baseURL, + defaultResolver) { + return { + url: new URL(specifier, parentModuleURL).href, + format: 'module' + }; +} +``` + +The `parentModuleURL` is provided as `undefined` when performing main Node.js +load itself. + +The default Node.js ES module resolution function is provided as a third +argument to the resolver for easy compatibility workflows. + +In addition to returning the resolved file URL value, the resolve hook also +returns a `format` property specifying the module format of the resolved +module. This can be one of the following: + +| `format` | Description | +| --- | --- | +| `'builtin'` | Load a Node.js builtin module | +| `'commonjs'` | Load a Node.js CommonJS module | +| `'dynamic'` | Use a [dynamic instantiate hook][] | +| `'json'` | Load a JSON file | +| `'module'` | Load a standard JavaScript module | +| `'wasm'` | Load a WebAssembly module | + +For example, a dummy loader to load JavaScript restricted to browser resolution +rules with only JS file extension and Node.js builtin modules support could +be written: + +```js +import path from 'path'; +import process from 'process'; +import Module from 'module'; + +const builtins = Module.builtinModules; +const JS_EXTENSIONS = new Set(['.js', '.mjs']); + +const baseURL = new URL(`${process.cwd()}/`, 'file://'); + +export function resolve(specifier, parentModuleURL = baseURL, defaultResolve) { + if (builtins.includes(specifier)) { + return { + url: specifier, + format: 'builtin' + }; + } + if (/^\.{0,2}[/]/.test(specifier) !== true && !specifier.startsWith('file:')) { + // For node_modules support: + // return defaultResolve(specifier, parentModuleURL); + throw new Error( + `imports must begin with '/', './', or '../'; '${specifier}' does not`); + } + const resolved = new URL(specifier, parentModuleURL); + const ext = path.extname(resolved.pathname); + if (!JS_EXTENSIONS.has(ext)) { + throw new Error( + `Cannot load file with non-JavaScript file extension ${ext}.`); + } + return { + url: resolved.href, + format: 'module' + }; +} +``` + +With this loader, running: + +```console +NODE_OPTIONS='--experimental-modules --loader ./custom-loader.mjs' node x.js +``` + +would load the module `x.js` as an ES module with relative resolution support +(with `node_modules` loading skipped in this example). + diff --git a/esm/resolver_algorithm.md b/esm/resolver_algorithm.md new file mode 100644 index 00000000..621e905e --- /dev/null +++ b/esm/resolver_algorithm.md @@ -0,0 +1,131 @@ + +The algorithm to load an ES module specifier is given through the +**ESM_RESOLVE** method below. It returns the resolved URL for a +module specifier relative to a parentURL, in addition to the unique module +format for that resolved URL given by the **ESM_FORMAT** routine. + +The _"module"_ format is returned for an ECMAScript Module, while the +_"commonjs"_ format is used to indicate loading through the legacy +CommonJS loader. Additional formats such as _"addon"_ can be extended in future +updates. + +In the following algorithms, all subroutine errors are propagated as errors +of these top-level routines. + +_isMain_ is **true** when resolving the Node.js application entry point. + +
+Resolver algorithm specification + +**ESM_RESOLVE(_specifier_, _parentURL_, _isMain_)** +> 1. Let _resolvedURL_ be **undefined**. +> 1. If _specifier_ is a valid URL, then +> 1. Set _resolvedURL_ to the result of parsing and reserializing +> _specifier_ as a URL. +> 1. Otherwise, if _specifier_ starts with _"/"_, then +> 1. Throw an _Invalid Specifier_ error. +> 1. Otherwise, if _specifier_ starts with _"./"_ or _"../"_, then +> 1. Set _resolvedURL_ to the URL resolution of _specifier_ relative to +> _parentURL_. +> 1. Otherwise, +> 1. Note: _specifier_ is now a bare specifier. +> 1. Set _resolvedURL_ the result of +> **PACKAGE_RESOLVE**(_specifier_, _parentURL_). +> 1. If the file at _resolvedURL_ does not exist, then +> 1. Throw a _Module Not Found_ error. +> 1. Set _resolvedURL_ to the real path of _resolvedURL_. +> 1. Let _format_ be the result of **ESM_FORMAT**(_resolvedURL_, _isMain_). +> 1. Load _resolvedURL_ as module format, _format_. + +PACKAGE_RESOLVE(_packageSpecifier_, _parentURL_) +> 1. Let _packageName_ be *undefined*. +> 1. Let _packageSubpath_ be *undefined*. +> 1. If _packageSpecifier_ is an empty string, then +> 1. Throw an _Invalid Specifier_ error. +> 1. If _packageSpecifier_ does not start with _"@"_, then +> 1. Set _packageName_ to the substring of _packageSpecifier_ until the +> first _"/"_ separator or the end of the string. +> 1. Otherwise, +> 1. If _packageSpecifier_ does not contain a _"/"_ separator, then +> 1. Throw an _Invalid Specifier_ error. +> 1. Set _packageName_ to the substring of _packageSpecifier_ +> until the second _"/"_ separator or the end of the string. +> 1. Let _packageSubpath_ be the substring of _packageSpecifier_ from the +> position at the length of _packageName_ plus one, if any. +> 1. Assert: _packageName_ is a valid package name or scoped package name. +> 1. Assert: _packageSubpath_ is either empty, or a path without a leading +> separator. +> 1. If _packageSubpath_ contains any _"."_ or _".."_ segments or percent +> encoded strings for _"/"_ or _"\\"_ then, +> 1. Throw an _Invalid Specifier_ error. +> 1. If _packageSubpath_ is empty and _packageName_ is a Node.js builtin +> module, then +> 1. Return the string _"node:"_ concatenated with _packageSpecifier_. +> 1. While _parentURL_ is not the file system root, +> 1. Let _packageURL_ be the URL resolution of "node_modules/" +> concatenated with _packageSpecifier_, relative to _parentURL_. +> 1. Set _parentURL_ to the parent folder URL of _parentURL_. +> 1. If the folder at _packageURL_ does not exist, then +> 1. Set _parentURL_ to the parent URL path of _parentURL_. +> 1. Continue the next loop iteration. +> 1. Let _pjson_ be the result of **READ_PACKAGE_JSON**(_packageURL_). +> 1. If _packageSubpath_ is empty, then +> 1. Return the result of **PACKAGE_MAIN_RESOLVE**(_packageURL_, +> _pjson_). +> 1. Otherwise, +> 1. Return the URL resolution of _packageSubpath_ in _packageURL_. +> 1. Throw a _Module Not Found_ error. + +PACKAGE_MAIN_RESOLVE(_packageURL_, _pjson_) +> 1. If _pjson_ is **null**, then +> 1. Throw a _Module Not Found_ error. +> 1. If _pjson.main_ is a String, then +> 1. Let _resolvedMain_ be the concatenation of _packageURL_, "/", and +> _pjson.main_. +> 1. If the file at _resolvedMain_ exists, then +> 1. Return _resolvedMain_. +> 1. If _pjson.type_ is equal to _"module"_, then +> 1. Throw a _Module Not Found_ error. +> 1. Let _legacyMainURL_ be the result applying the legacy +> **LOAD_AS_DIRECTORY** CommonJS resolver to _packageURL_, throwing a +> _Module Not Found_ error for no resolution. +> 1. If _legacyMainURL_ does not end in _".js"_ then, +> 1. Throw an _Unsupported File Extension_ error. +> 1. Return _legacyMainURL_. + +**ESM_FORMAT(_url_, _isMain_)** +> 1. Assert: _url_ corresponds to an existing file. +> 1. Let _pjson_ be the result of **READ_PACKAGE_SCOPE**(_url_). +> 1. If _url_ ends in _".mjs"_, then +> 1. Return _"module"_. +> 1. If _url_ ends in _".cjs"_, then +> 1. Return _"commonjs"_. +> 1. If _pjson?.type_ exists and is _"module"_, then +> 1. If _isMain_ is **true** or _url_ ends in _".js"_, then +> 1. Return _"module"_. +> 1. Throw an _Unsupported File Extension_ error. +> 1. Otherwise, +> 1. If _isMain_ is **true** or _url_ ends in _".js"_, _".json"_ or +> _".node"_, then +> 1. Return _"commonjs"_. +> 1. Throw an _Unsupported File Extension_ error. + +READ_PACKAGE_SCOPE(_url_) +> 1. Let _scopeURL_ be _url_. +> 1. While _scopeURL_ is not the file system root, +> 1. Let _pjson_ be the result of **READ_PACKAGE_JSON**(_scopeURL_). +> 1. If _pjson_ is not **null**, then +> 1. Return _pjson_. +> 1. Set _scopeURL_ to the parent URL of _scopeURL_. +> 1. Return **null**. + +READ_PACKAGE_JSON(_packageURL_) +> 1. Let _pjsonURL_ be the resolution of _"package.json"_ within _packageURL_. +> 1. If the file at _pjsonURL_ does not exist, then +> 1. Return **null**. +> 1. If the file at _packageURL_ does not parse as valid JSON, then +> 1. Throw an _Invalid Package Configuration_ error. +> 1. Return the parsed JSON source of the file at _pjsonURL_. + +
+ diff --git a/esm/supported.md b/esm/supported.md new file mode 100644 index 00000000..6de0dd61 --- /dev/null +++ b/esm/supported.md @@ -0,0 +1,5 @@ + +Only the CLI argument for the main entry point to the program can be an entry +point into an ESM graph. Dynamic import can also be used to create entry points +into ESM graphs at runtime. + diff --git a/esm/terminology.md b/esm/terminology.md new file mode 100644 index 00000000..4b5c7bb5 --- /dev/null +++ b/esm/terminology.md @@ -0,0 +1,29 @@ + +The _specifier_ of an `import` statement is the string after the `from` keyword, +e.g. `'path'` in `import { sep } from 'path'`. Specifiers are also used in +`export from` statements, and as the argument to an `import()` expression. + +There are four types of specifiers: + +- _Bare specifiers_ like `'some-package'`. They refer to an entry point of a + package by the package name. + +- _Deep import specifiers_ like `'some-package/lib/shuffle.mjs'`. They refer to + a path within a package prefixed by the package name. + +- _Relative specifiers_ like `'./startup.js'` or `'../config.mjs'`. They refer + to a path relative to the location of the importing file. + +- _Absolute specifiers_ like `'file:///opt/nodejs/config.js'`. They refer + directly and explicitly to a full path. + +Bare specifiers, and the bare specifier portion of deep import specifiers, are +strings; but everything else in a specifier is a URL. + +Only `file://` URLs are supported. A specifier like +`'https://example.com/app.js'` may be supported by browsers but it is not +supported in Node.js. + +Specifiers may not begin with `/` or `//`. These are reserved for potential +future use. The root of the current volume may be referenced via `file:///`. + diff --git a/esm/unsupported.md b/esm/unsupported.md new file mode 100644 index 00000000..bd0aef8d --- /dev/null +++ b/esm/unsupported.md @@ -0,0 +1,5 @@ + +| Feature | Reason | +| --- | --- | +| `require('./foo.mjs')` | ES Modules have differing resolution and timing, use dynamic import | + diff --git a/esm/url_based_paths.md b/esm/url_based_paths.md new file mode 100644 index 00000000..2b38feb2 --- /dev/null +++ b/esm/url_based_paths.md @@ -0,0 +1,15 @@ + +ES modules are resolved and cached based upon + +special characters such as `#` and `?` need to be escaped. + +Modules will be loaded multiple times if the `import` specifier used to resolve +them have a different query or fragment. + +```js +import './foo.mjs?query=1'; // loads ./foo.mjs with query of "?query=1" +import './foo.mjs?query=2'; // loads ./foo.mjs with query of "?query=2" +``` + +For now, only modules using the `file:` protocol can be loaded. + diff --git a/api-docs/698c5c28a02658e4f8cc009c886cb45f1a52fccf9ba555e0838310375665b943.md b/events/asynchronous_vs_synchronous.md similarity index 100% rename from api-docs/698c5c28a02658e4f8cc009c886cb45f1a52fccf9ba555e0838310375665b943.md rename to events/asynchronous_vs_synchronous.md diff --git a/api-docs/1c2e5cbccab737aa6746f02368da5faeaeec6517e9d74c2955305d717c0fde76.md b/events/class_eventemitter.md similarity index 100% rename from api-docs/1c2e5cbccab737aa6746f02368da5faeaeec6517e9d74c2955305d717c0fde76.md rename to events/class_eventemitter.md diff --git a/api-docs/6c97937b749637a200b1d9768b076575c8690f13eb2e13d93e650e25567f364c.md b/events/emitter_addlistener_eventname_listener.md similarity index 100% rename from api-docs/6c97937b749637a200b1d9768b076575c8690f13eb2e13d93e650e25567f364c.md rename to events/emitter_addlistener_eventname_listener.md diff --git a/api-docs/cf08de2a45b0712536afb3f52ec54b7ae883884d980a59e17b259469104a9dbb.md b/events/emitter_emit_eventname_args.md similarity index 100% rename from api-docs/cf08de2a45b0712536afb3f52ec54b7ae883884d980a59e17b259469104a9dbb.md rename to events/emitter_emit_eventname_args.md diff --git a/api-docs/4e428118c98d47e3cc6eb5f22f9edaa8ec0c47b093d9891cd7ad452606c51f7c.md b/events/emitter_eventnames.md similarity index 100% rename from api-docs/4e428118c98d47e3cc6eb5f22f9edaa8ec0c47b093d9891cd7ad452606c51f7c.md rename to events/emitter_eventnames.md diff --git a/api-docs/f71ab0ffff91893db72b59a65b1c0fa12ec1a09b0fa02325b2a03f080a4e1e7a.md b/events/emitter_getmaxlisteners.md similarity index 100% rename from api-docs/f71ab0ffff91893db72b59a65b1c0fa12ec1a09b0fa02325b2a03f080a4e1e7a.md rename to events/emitter_getmaxlisteners.md diff --git a/api-docs/f473a7d6fbdd0d14d7707e1cb3b64f7317b848c0da92be4cfa313c180002646f.md b/events/emitter_listenercount_eventname.md similarity index 100% rename from api-docs/f473a7d6fbdd0d14d7707e1cb3b64f7317b848c0da92be4cfa313c180002646f.md rename to events/emitter_listenercount_eventname.md diff --git a/api-docs/3596238643534f19d8ae54cd6f7e6b18913f3559889ea34aaf96b9dd79b3b774.md b/events/emitter_listeners_eventname.md similarity index 100% rename from api-docs/3596238643534f19d8ae54cd6f7e6b18913f3559889ea34aaf96b9dd79b3b774.md rename to events/emitter_listeners_eventname.md diff --git a/api-docs/39a5bb19379865775249d9038b8ed0cc61d18c165005789d43d7108a09d2a629.md b/events/emitter_off_eventname_listener.md similarity index 100% rename from api-docs/39a5bb19379865775249d9038b8ed0cc61d18c165005789d43d7108a09d2a629.md rename to events/emitter_off_eventname_listener.md diff --git a/api-docs/92ed828f5e4dad339bdcb12528ded74f8403cbcb552d59079e794bab816b3c78.md b/events/emitter_on_eventname_listener.md similarity index 100% rename from api-docs/92ed828f5e4dad339bdcb12528ded74f8403cbcb552d59079e794bab816b3c78.md rename to events/emitter_on_eventname_listener.md diff --git a/api-docs/b03ac3153fc38b0fa9ba472a08fcedb5ae501509982f56e31e4f88bb05d57239.md b/events/emitter_once_eventname_listener.md similarity index 100% rename from api-docs/b03ac3153fc38b0fa9ba472a08fcedb5ae501509982f56e31e4f88bb05d57239.md rename to events/emitter_once_eventname_listener.md diff --git a/api-docs/e56c5e1255f5dbbc755d90735c3dd1ccdc7d4ef923445af13cf97932b757d71f.md b/events/emitter_prependlistener_eventname_listener.md similarity index 100% rename from api-docs/e56c5e1255f5dbbc755d90735c3dd1ccdc7d4ef923445af13cf97932b757d71f.md rename to events/emitter_prependlistener_eventname_listener.md diff --git a/api-docs/95d09e72629da176eb8d2d52f583cb6e7fffcb0f99cdf387a4696114ee5ba041.md b/events/emitter_prependoncelistener_eventname_listener.md similarity index 100% rename from api-docs/95d09e72629da176eb8d2d52f583cb6e7fffcb0f99cdf387a4696114ee5ba041.md rename to events/emitter_prependoncelistener_eventname_listener.md diff --git a/api-docs/635bcb1e3a2aedaee69d354a3c37e00551ca14ed9b089729fb07de8944ad9394.md b/events/emitter_rawlisteners_eventname.md similarity index 100% rename from api-docs/635bcb1e3a2aedaee69d354a3c37e00551ca14ed9b089729fb07de8944ad9394.md rename to events/emitter_rawlisteners_eventname.md diff --git a/api-docs/4d2063624cb54bea09425ff1e15097dbe4a35684d2e84e5420263d34b5cc29e9.md b/events/emitter_removealllisteners_eventname.md similarity index 100% rename from api-docs/4d2063624cb54bea09425ff1e15097dbe4a35684d2e84e5420263d34b5cc29e9.md rename to events/emitter_removealllisteners_eventname.md diff --git a/api-docs/5781c6e415e8465e2ffb197c8fabe50c7cca6a3696f07776e4e40811bddee8ad.md b/events/emitter_removelistener_eventname_listener.md similarity index 100% rename from api-docs/5781c6e415e8465e2ffb197c8fabe50c7cca6a3696f07776e4e40811bddee8ad.md rename to events/emitter_removelistener_eventname_listener.md diff --git a/api-docs/d91e8cc012254d9e97ffc81e5b2a63e821a06f2d6aa96160056fc8c41c800284.md b/events/emitter_setmaxlisteners_n.md similarity index 100% rename from api-docs/d91e8cc012254d9e97ffc81e5b2a63e821a06f2d6aa96160056fc8c41c800284.md rename to events/emitter_setmaxlisteners_n.md diff --git a/api-docs/09c49c1b6196fd3fc769cc95d22716f6fccdb370e6bbdfa46a897b4617e612a5.md b/events/error_events.md similarity index 83% rename from api-docs/09c49c1b6196fd3fc769cc95d22716f6fccdb370e6bbdfa46a897b4617e612a5.md rename to events/error_events.md index db2d0a6d..8a689b60 100644 --- a/api-docs/09c49c1b6196fd3fc769cc95d22716f6fccdb370e6bbdfa46a897b4617e612a5.md +++ b/events/error_events.md @@ -1,12 +1,13 @@ 当 `EventEmitter` 实例出错时，应该触发 `'error'` 事件。 +这些在 Node.js 中被视为特殊情况。 如果没有为 `'error'` 事件注册监听器，则当 `'error'` 事件触发时，会抛出错误、打印堆栈跟踪、并退出 Node.js 进程。 ```js const myEmitter = new MyEmitter(); myEmitter.emit('error', new Error('错误信息')); -// 抛出错误 +// 抛出错误并使 Node.js 崩溃。 ``` 为了防止崩溃 Node.js 进程，可以使用 [`domain`] 模块。 @@ -19,7 +20,7 @@ const myEmitter = new MyEmitter(); myEmitter.on('error', (err) => { console.error('错误信息'); }); -myEmitter.emit('error', new Error('错误信息')); +myEmitter.emit('error', new Error('错误')); // 打印: 错误信息 ``` diff --git a/api-docs/cdb02751b824704d3a88747df3e10f1d5bf8fbad7b5ce7a8ef3b79e5cdda27b0.md b/events/event_newlistener.md similarity index 100% rename from api-docs/cdb02751b824704d3a88747df3e10f1d5bf8fbad7b5ce7a8ef3b79e5cdda27b0.md rename to events/event_newlistener.md diff --git a/api-docs/d15c595771c261c859ec7a87c46adf5a7fc274cd2e7847582cb3056392610377.md b/events/event_removelistener.md similarity index 100% rename from api-docs/d15c595771c261c859ec7a87c46adf5a7fc274cd2e7847582cb3056392610377.md rename to events/event_removelistener.md diff --git a/api-docs/58d90fedaa2fa8709825af8d17706565ff669a076d6aed6f4d4c2e2e4b76b2a7.md b/events/eventemitter_defaultmaxlisteners.md similarity index 100% rename from api-docs/58d90fedaa2fa8709825af8d17706565ff669a076d6aed6f4d4c2e2e4b76b2a7.md rename to events/eventemitter_defaultmaxlisteners.md diff --git a/events/eventemitter_listenercount_emitter_eventname.md b/events/eventemitter_listenercount_emitter_eventname.md new file mode 100644 index 00000000..c29d389c --- /dev/null +++ b/events/eventemitter_listenercount_emitter_eventname.md @@ -0,0 +1,20 @@ + +* `emitter` {EventEmitter} The emitter to query +* `eventName` {string|symbol} The event name + +> Stability: 0 - Deprecated: Use [`emitter.listenerCount()`][] instead. + +A class method that returns the number of listeners for the given `eventName` +registered on the given `emitter`. + +```js +const myEmitter = new MyEmitter(); +myEmitter.on('event', () => {}); +myEmitter.on('event', () => {}); +console.log(EventEmitter.listenerCount(myEmitter, 'event')); +// Prints: 2 +``` + diff --git a/api-docs/d65d7bc6500f7a10a317a53ad5fcd251888ae54cdf993c42d64755a0bc4f506b.md b/events/events.md similarity index 86% rename from api-docs/d65d7bc6500f7a10a317a53ad5fcd251888ae54cdf993c42d64755a0bc4f506b.md rename to events/events.md index 066b8953..3e01b7bf 100644 --- a/api-docs/d65d7bc6500f7a10a317a53ad5fcd251888ae54cdf993c42d64755a0bc4f506b.md +++ b/events/events.md @@ -11,9 +11,10 @@ 所有能触发事件的对象都是 `EventEmitter` 类的实例。 这些对象有一个 `eventEmitter.on()` 函数，用于将一个或多个函数绑定到命名事件上。 -事件的命名通常是驼峰式的字符串。 +事件的命名通常是驼峰式的字符串，但也可以使用任何有效的 JavaScript 属性键。。 当 `EventEmitter` 对象触发一个事件时，所有绑定在该事件上的函数都会被同步地调用。 +被调用的监听器返回的任何值都将会被忽略并丢弃。 例子，一个简单的 `EventEmitter` 实例，绑定了一个监听器。 `eventEmitter.on()` 用于注册监听器，`eventEmitter.emit()` 用于触发事件。 diff --git a/api-docs/ff2131866e4e7fccdcb198b7ceba56e101c2a1c3f2a95480829b9cac888bdee2.md b/events/events_once_emitter_name.md similarity index 100% rename from api-docs/ff2131866e4e7fccdcb198b7ceba56e101c2a1c3f2a95480829b9cac888bdee2.md rename to events/events_once_emitter_name.md diff --git a/api-docs/ebaa7069f053165cff1cfce786d2be62905ed9bc0be132d539071fe21f3f5ad5.md b/events/handling_events_only_once.md similarity index 100% rename from api-docs/ebaa7069f053165cff1cfce786d2be62905ed9bc0be132d539071fe21f3f5ad5.md rename to events/handling_events_only_once.md diff --git a/api-docs/03eb4c25eec7c07a5b6db4f7997bf22dd191cc9963320c877f64915866052061.md b/events/passing_arguments_and_this_to_listeners.md similarity index 100% rename from api-docs/03eb4c25eec7c07a5b6db4f7997bf22dd191cc9963320c877f64915866052061.md rename to events/passing_arguments_and_this_to_listeners.md diff --git a/api-docs/06f1d2a7dda5b7381c710c3dac9545bd1f0e93b2c4e51ddda3e3a5a4afaa3412.md b/fs/availability.md similarity index 100% rename from api-docs/06f1d2a7dda5b7381c710c3dac9545bd1f0e93b2c4e51ddda3e3a5a4afaa3412.md rename to fs/availability.md diff --git a/api-docs/3da376ca794d5e37a502b7aca2b27bd88a5ee3290ce023936eef83767e89452b.md b/fs/caveats.md similarity index 100% rename from api-docs/3da376ca794d5e37a502b7aca2b27bd88a5ee3290ce023936eef83767e89452b.md rename to fs/caveats.md diff --git a/api-docs/b05314a5c8daf5ac0a2dacccd9463c5fec0d9c9561536a50060c4e37e86ff602.md b/fs/class_filehandle.md similarity index 100% rename from api-docs/b05314a5c8daf5ac0a2dacccd9463c5fec0d9c9561536a50060c4e37e86ff602.md rename to fs/class_filehandle.md diff --git a/api-docs/4b1d90a8ad0ddfa97a0f84959d7a3df94144ae207453143d4eec4e3a6351daf8.md b/fs/class_fs_dirent.md similarity index 100% rename from api-docs/4b1d90a8ad0ddfa97a0f84959d7a3df94144ae207453143d4eec4e3a6351daf8.md rename to fs/class_fs_dirent.md diff --git a/api-docs/7f4465b879637b0322f13c5781cda63896f0d8a4ce3e7ca8d2e26708143de075.md b/fs/class_fs_fswatcher.md similarity index 100% rename from api-docs/7f4465b879637b0322f13c5781cda63896f0d8a4ce3e7ca8d2e26708143de075.md rename to fs/class_fs_fswatcher.md diff --git a/api-docs/d154a75912f1614e5fcb7407eda0a502f0e9ea795132602bf8506e439ccb4eb3.md b/fs/class_fs_readstream.md similarity index 100% rename from api-docs/d154a75912f1614e5fcb7407eda0a502f0e9ea795132602bf8506e439ccb4eb3.md rename to fs/class_fs_readstream.md diff --git a/api-docs/7f8f0c59bab263f15e7db3dcd5efdb14c005fc76f3fdfe836a8a51be987b2366.md b/fs/class_fs_stats.md similarity index 100% rename from api-docs/7f8f0c59bab263f15e7db3dcd5efdb14c005fc76f3fdfe836a8a51be987b2366.md rename to fs/class_fs_stats.md diff --git a/api-docs/157fb4d1b0175ed12a833280b186fd58c909b916aa58fafa348fb7e3a67d478c.md b/fs/class_fs_writestream.md similarity index 100% rename from api-docs/157fb4d1b0175ed12a833280b186fd58c909b916aa58fafa348fb7e3a67d478c.md rename to fs/class_fs_writestream.md diff --git a/api-docs/367e665ae3a84b45c9ffccb3d675c1c78add1e94ed05a208234f2abf9bcdaca8.md b/fs/dirent_isblockdevice.md similarity index 100% rename from api-docs/367e665ae3a84b45c9ffccb3d675c1c78add1e94ed05a208234f2abf9bcdaca8.md rename to fs/dirent_isblockdevice.md diff --git a/api-docs/8915f030697a729b89be95d64a846c00fdab2d25911d1e791efe599f094afc83.md b/fs/dirent_ischaracterdevice.md similarity index 100% rename from api-docs/8915f030697a729b89be95d64a846c00fdab2d25911d1e791efe599f094afc83.md rename to fs/dirent_ischaracterdevice.md diff --git a/api-docs/cdec1acc24c93f9e86c8221de807fd4ebf990836e352257d316bd739d61aecf6.md b/fs/dirent_isdirectory.md similarity index 100% rename from api-docs/cdec1acc24c93f9e86c8221de807fd4ebf990836e352257d316bd739d61aecf6.md rename to fs/dirent_isdirectory.md diff --git a/api-docs/9b0f9fceb92fe219269fef9b03d409b650cc3531a0d6a66507ae6fdd272369c8.md b/fs/dirent_isfifo.md similarity index 100% rename from api-docs/9b0f9fceb92fe219269fef9b03d409b650cc3531a0d6a66507ae6fdd272369c8.md rename to fs/dirent_isfifo.md diff --git a/api-docs/9399d15a8017bd07d03d55b9b7c7a7964fb670a18c4567958acaa09bb6aeaf8b.md b/fs/dirent_isfile.md similarity index 100% rename from api-docs/9399d15a8017bd07d03d55b9b7c7a7964fb670a18c4567958acaa09bb6aeaf8b.md rename to fs/dirent_isfile.md diff --git a/api-docs/ae4c52cbe3b2925cd04a79128f9b4c07b0c284924940ad31d2ec0ba5da8f3f52.md b/fs/dirent_issocket.md similarity index 100% rename from api-docs/ae4c52cbe3b2925cd04a79128f9b4c07b0c284924940ad31d2ec0ba5da8f3f52.md rename to fs/dirent_issocket.md diff --git a/api-docs/d737490dabb6f11583a77c8c65ad1503893df9ead323a2c524c5c483c98bf8b0.md b/fs/dirent_issymboliclink.md similarity index 100% rename from api-docs/d737490dabb6f11583a77c8c65ad1503893df9ead323a2c524c5c483c98bf8b0.md rename to fs/dirent_issymboliclink.md diff --git a/api-docs/5b2f90172417c719a1c54f7a0d6061bbe074ef261baf04d8396804092522f606.md b/fs/dirent_name.md similarity index 100% rename from api-docs/5b2f90172417c719a1c54f7a0d6061bbe074ef261baf04d8396804092522f606.md rename to fs/dirent_name.md diff --git a/api-docs/4c250397167b1a66d113e5fd52135047561a283e631e0d9b81e5f47066931e71.md b/fs/event_change.md similarity index 100% rename from api-docs/4c250397167b1a66d113e5fd52135047561a283e631e0d9b81e5f47066931e71.md rename to fs/event_change.md diff --git a/api-docs/ee17763e8cd939dda5a29c4a778fd520d55ad2a7f043d8bd552470cd5cb3fe4d.md b/fs/event_close.md similarity index 100% rename from api-docs/ee17763e8cd939dda5a29c4a778fd520d55ad2a7f043d8bd552470cd5cb3fe4d.md rename to fs/event_close.md diff --git a/api-docs/b59912adfcfb878a8030720073e8a74c4459b5b0ef144712605d512dc4a0945c.md b/fs/event_close_1.md similarity index 100% rename from api-docs/b59912adfcfb878a8030720073e8a74c4459b5b0ef144712605d512dc4a0945c.md rename to fs/event_close_1.md diff --git a/api-docs/acedfcb9581ee908aa8b0ece562ea09599455789115faa38c62d758be22b961a.md b/fs/event_close_2.md similarity index 100% rename from api-docs/acedfcb9581ee908aa8b0ece562ea09599455789115faa38c62d758be22b961a.md rename to fs/event_close_2.md diff --git a/api-docs/913234d06bbd21fd0d6cf37536a65733524755b9f78e9145b695a312ac9c7b24.md b/fs/event_error.md similarity index 100% rename from api-docs/913234d06bbd21fd0d6cf37536a65733524755b9f78e9145b695a312ac9c7b24.md rename to fs/event_error.md diff --git a/api-docs/8f0c31ad3908ab3e82b2ba6e69791859fb2f2b4aae30b365246a0af84f1e3974.md b/fs/event_open.md similarity index 100% rename from api-docs/8f0c31ad3908ab3e82b2ba6e69791859fb2f2b4aae30b365246a0af84f1e3974.md rename to fs/event_open.md diff --git a/api-docs/c0f95dc18b45704d6553c4a788c3e842c610872d762e07e863f5e05f2b408b71.md b/fs/event_open_1.md similarity index 100% rename from api-docs/c0f95dc18b45704d6553c4a788c3e842c610872d762e07e863f5e05f2b408b71.md rename to fs/event_open_1.md diff --git a/api-docs/7e55fb5379c2cbc895b7428ea622f58cbd3ef70a60262665fa6530359f5c7dad.md b/fs/event_ready.md similarity index 100% rename from api-docs/7e55fb5379c2cbc895b7428ea622f58cbd3ef70a60262665fa6530359f5c7dad.md rename to fs/event_ready.md diff --git a/api-docs/fedd65ef944c0370bfb2d3a47013459e18162c58831f957e32aaf198b5ea2ac6.md b/fs/event_ready_1.md similarity index 100% rename from api-docs/fedd65ef944c0370bfb2d3a47013459e18162c58831f957e32aaf198b5ea2ac6.md rename to fs/event_ready_1.md diff --git a/api-docs/3c7888e66ae60914aaec7028f41dc053778bdf62544de5b01c1276ef7d8b390b.md b/fs/file_access_constants.md similarity index 100% rename from api-docs/3c7888e66ae60914aaec7028f41dc053778bdf62544de5b01c1276ef7d8b390b.md rename to fs/file_access_constants.md diff --git a/api-docs/9f134ee72eb2dae6a4b39a9ad6b2ebe535bab5421eb70074d4c95f7d02132702.md b/fs/file_copy_constants.md similarity index 100% rename from api-docs/9f134ee72eb2dae6a4b39a9ad6b2ebe535bab5421eb70074d4c95f7d02132702.md rename to fs/file_copy_constants.md diff --git a/api-docs/51e3a0a2ca3ff4a04fea33d58fe494005353d7b4ed7aaa120fe3cb5ae192d659.md b/fs/file_descriptors.md similarity index 100% rename from api-docs/51e3a0a2ca3ff4a04fea33d58fe494005353d7b4ed7aaa120fe3cb5ae192d659.md rename to fs/file_descriptors.md diff --git a/api-docs/aa688ca28691534d23dc2f1370c716337f6416f9cf27803cc64096f7ad69b728.md b/fs/file_descriptors_1.md similarity index 100% rename from api-docs/aa688ca28691534d23dc2f1370c716337f6416f9cf27803cc64096f7ad69b728.md rename to fs/file_descriptors_1.md diff --git a/api-docs/cfa9d1d142aa5c41a58ce87e61470377afdc83829d415b4419f59b8b3721e515.md b/fs/file_mode_constants.md similarity index 100% rename from api-docs/cfa9d1d142aa5c41a58ce87e61470377afdc83829d415b4419f59b8b3721e515.md rename to fs/file_mode_constants.md diff --git a/api-docs/2dc72e18f334fbefaaebab5b53cb72fed851a1ca6f91308b0e6743f9d27358ea.md b/fs/file_modes.md similarity index 100% rename from api-docs/2dc72e18f334fbefaaebab5b53cb72fed851a1ca6f91308b0e6743f9d27358ea.md rename to fs/file_modes.md diff --git a/api-docs/6cf02bb51b9a6acb48cb2682c83def6bf0ad34876fe3b53188af756056956368.md b/fs/file_open_constants.md similarity index 100% rename from api-docs/6cf02bb51b9a6acb48cb2682c83def6bf0ad34876fe3b53188af756056956368.md rename to fs/file_open_constants.md diff --git a/api-docs/e8372122afa70fd1c15a467c3e90254a8afe8d582009e0d545e9d217ca3843ec.md b/fs/file_paths.md similarity index 100% rename from api-docs/e8372122afa70fd1c15a467c3e90254a8afe8d582009e0d545e9d217ca3843ec.md rename to fs/file_paths.md diff --git a/api-docs/76367e53909110f69c9f49c9f3518acbff73250914cab73de7dc15bbf7abfa66.md b/fs/file_system.md similarity index 94% rename from api-docs/76367e53909110f69c9f49c9f3518acbff73250914cab73de7dc15bbf7abfa66.md rename to fs/file_system.md index 133b2d46..53c718a7 100644 --- a/api-docs/76367e53909110f69c9f49c9f3518acbff73250914cab73de7dc15bbf7abfa66.md +++ b/fs/file_system.md @@ -28,7 +28,7 @@ fs.unlink('/tmp/hello', (err) => { }); ``` -使用同步的操作发生的异常会立即抛出，可以使用 `try`/`catch` 处理，也可以允许冒泡。 +使用同步的操作发生的异常会立即抛出，可以使用 `try…catch` 处理，也可以允许冒泡。 ```js const fs = require('fs'); diff --git a/api-docs/b6069fff095bd3595266651702b1feeacbc26c82c346a6ef6b71d402baeb0e27.md b/fs/file_system_flags.md similarity index 100% rename from api-docs/b6069fff095bd3595266651702b1feeacbc26c82c346a6ef6b71d402baeb0e27.md rename to fs/file_system_flags.md diff --git a/api-docs/852e0acb25496bcdf001d8f72db7758f471f09d6220039138b16c738fd7d544c.md b/fs/file_type_constants.md similarity index 100% rename from api-docs/852e0acb25496bcdf001d8f72db7758f471f09d6220039138b16c738fd7d544c.md rename to fs/file_type_constants.md diff --git a/api-docs/3c6d60af6b30a1dcc86ad17ec047bea1ce00cad4ac8312f88927b083f8c13d87.md b/fs/filehandle_appendfile_data_options.md similarity index 100% rename from api-docs/3c6d60af6b30a1dcc86ad17ec047bea1ce00cad4ac8312f88927b083f8c13d87.md rename to fs/filehandle_appendfile_data_options.md diff --git a/api-docs/a9ecd948801d14f66054fcef6f97d2b758809eb1803cd965d24c6420132351bb.md b/fs/filehandle_chmod_mode.md similarity index 100% rename from api-docs/a9ecd948801d14f66054fcef6f97d2b758809eb1803cd965d24c6420132351bb.md rename to fs/filehandle_chmod_mode.md diff --git a/api-docs/1368af7f2deb1028ceab9c8000a28bd970c0a3ca9132e6feda9980a29ec2d6f5.md b/fs/filehandle_chown_uid_gid.md similarity index 100% rename from api-docs/1368af7f2deb1028ceab9c8000a28bd970c0a3ca9132e6feda9980a29ec2d6f5.md rename to fs/filehandle_chown_uid_gid.md diff --git a/api-docs/b9bf9f7db7fb1faa49998c79e89bbba944725e0391dd87a3df33c45a3df6cd14.md b/fs/filehandle_close.md similarity index 100% rename from api-docs/b9bf9f7db7fb1faa49998c79e89bbba944725e0391dd87a3df33c45a3df6cd14.md rename to fs/filehandle_close.md diff --git a/api-docs/80fb3b4b932b68157a6ca7583c27f368d3fe6216b99470136b2bf984d11535a8.md b/fs/filehandle_datasync.md similarity index 100% rename from api-docs/80fb3b4b932b68157a6ca7583c27f368d3fe6216b99470136b2bf984d11535a8.md rename to fs/filehandle_datasync.md diff --git a/api-docs/dc5dede731acb2c12084987ad492be79e219b2baacea62fa262d477b18e23de0.md b/fs/filehandle_fd.md similarity index 100% rename from api-docs/dc5dede731acb2c12084987ad492be79e219b2baacea62fa262d477b18e23de0.md rename to fs/filehandle_fd.md diff --git a/api-docs/56f7fcb94e6c827147ec1f9631d3165b41dcba75b449625cbc3fbf2d86da6db0.md b/fs/filehandle_read_buffer_offset_length_position.md similarity index 100% rename from api-docs/56f7fcb94e6c827147ec1f9631d3165b41dcba75b449625cbc3fbf2d86da6db0.md rename to fs/filehandle_read_buffer_offset_length_position.md diff --git a/api-docs/2613110dd422ac10a9c8e262627e0186cb7efdcc2b8e00035f4a2d7c144412a9.md b/fs/filehandle_readfile_options.md similarity index 100% rename from api-docs/2613110dd422ac10a9c8e262627e0186cb7efdcc2b8e00035f4a2d7c144412a9.md rename to fs/filehandle_readfile_options.md diff --git a/api-docs/a4d29e9b9a9a432767b7f61cb8492272808c5691f65ea924e06230a0518f1368.md b/fs/filehandle_stat_options.md similarity index 100% rename from api-docs/a4d29e9b9a9a432767b7f61cb8492272808c5691f65ea924e06230a0518f1368.md rename to fs/filehandle_stat_options.md diff --git a/api-docs/5323e5db5d6801bc74a53bc34f0f19167e6113150b0ac90523047412f16f57ee.md b/fs/filehandle_sync.md similarity index 100% rename from api-docs/5323e5db5d6801bc74a53bc34f0f19167e6113150b0ac90523047412f16f57ee.md rename to fs/filehandle_sync.md diff --git a/api-docs/c5e350b7b1453299e4dcf5f8e56e7ab695e174ed375865a4fc9f9f0af8811f2c.md b/fs/filehandle_truncate_len.md similarity index 100% rename from api-docs/c5e350b7b1453299e4dcf5f8e56e7ab695e174ed375865a4fc9f9f0af8811f2c.md rename to fs/filehandle_truncate_len.md diff --git a/api-docs/e58a9216140f9cb4ff05b40251e4f7c255c8f9347a83c750b35290824e86e799.md b/fs/filehandle_utimes_atime_mtime.md similarity index 100% rename from api-docs/e58a9216140f9cb4ff05b40251e4f7c255c8f9347a83c750b35290824e86e799.md rename to fs/filehandle_utimes_atime_mtime.md diff --git a/api-docs/4a62f0ba887d457f4bb03030161f59a6172b0a04df362896e095f732cb56cb5b.md b/fs/filehandle_write_buffer_offset_length_position.md similarity index 100% rename from api-docs/4a62f0ba887d457f4bb03030161f59a6172b0a04df362896e095f732cb56cb5b.md rename to fs/filehandle_write_buffer_offset_length_position.md diff --git a/api-docs/df8c94e058640ab61542b5fff0a4c2bbdef4b5e7287751df7e2c43459d654b4b.md b/fs/filehandle_write_string_position_encoding.md similarity index 100% rename from api-docs/df8c94e058640ab61542b5fff0a4c2bbdef4b5e7287751df7e2c43459d654b4b.md rename to fs/filehandle_write_string_position_encoding.md diff --git a/api-docs/0cb5e900a786b9d9082a25065b749993ab851dfa83ce7d4246cbaaa004422a43.md b/fs/filehandle_writefile_data_options.md similarity index 100% rename from api-docs/0cb5e900a786b9d9082a25065b749993ab851dfa83ce7d4246cbaaa004422a43.md rename to fs/filehandle_writefile_data_options.md diff --git a/api-docs/713e38b7da8ad144f03fe957afd35e2d6f9327f63314e34ae9d6d13bfb6cb634.md b/fs/filename_argument.md similarity index 100% rename from api-docs/713e38b7da8ad144f03fe957afd35e2d6f9327f63314e34ae9d6d13bfb6cb634.md rename to fs/filename_argument.md diff --git a/api-docs/35802eb0fe58de116a35fe6ae72dda65b1ddf6cfaad7911116829144c1473562.md b/fs/fs_access_path_mode_callback.md similarity index 100% rename from api-docs/35802eb0fe58de116a35fe6ae72dda65b1ddf6cfaad7911116829144c1473562.md rename to fs/fs_access_path_mode_callback.md diff --git a/api-docs/71efb04779a1b4664f14cf7820398c1d0eacd551e7b206ee81a2cdfc45e8bcde.md b/fs/fs_accesssync_path_mode.md similarity index 100% rename from api-docs/71efb04779a1b4664f14cf7820398c1d0eacd551e7b206ee81a2cdfc45e8bcde.md rename to fs/fs_accesssync_path_mode.md diff --git a/api-docs/be77c79bf0a1189c70116c49924ed0a431b242f4f20034a9346f1d244319f983.md b/fs/fs_appendfile_path_data_options_callback.md similarity index 100% rename from api-docs/be77c79bf0a1189c70116c49924ed0a431b242f4f20034a9346f1d244319f983.md rename to fs/fs_appendfile_path_data_options_callback.md diff --git a/api-docs/45480cbf83e2c4ccf5e4f3919c8252d592b4b01f2ddc26a3cb470ce8a10148b5.md b/fs/fs_appendfilesync_path_data_options.md similarity index 100% rename from api-docs/45480cbf83e2c4ccf5e4f3919c8252d592b4b01f2ddc26a3cb470ce8a10148b5.md rename to fs/fs_appendfilesync_path_data_options.md diff --git a/api-docs/bb92a301e10101b35fad8744d4568a3ccc980fb1b3c5af663e84f38a6f6019b7.md b/fs/fs_chmod_path_mode_callback.md similarity index 86% rename from api-docs/bb92a301e10101b35fad8744d4568a3ccc980fb1b3c5af663e84f38a6f6019b7.md rename to fs/fs_chmod_path_mode_callback.md index 16ac0b0c..d0f39df7 100644 --- a/api-docs/bb92a301e10101b35fad8744d4568a3ccc980fb1b3c5af663e84f38a6f6019b7.md +++ b/fs/fs_chmod_path_mode_callback.md @@ -25,3 +25,10 @@ changes: 也可参阅 chmod(2)。 +```js +fs.chmod('my_file.txt', 0o775, (err) => { + if (err) throw err; + console.log('文件 “my_file.txt” 的权限已被更改'); +}); +``` + diff --git a/api-docs/531aa9b80966fae6bade138b2ea0a0a570fb613e0f4f39fcd3327990052b1c79.md b/fs/fs_chmodsync_path_mode.md similarity index 100% rename from api-docs/531aa9b80966fae6bade138b2ea0a0a570fb613e0f4f39fcd3327990052b1c79.md rename to fs/fs_chmodsync_path_mode.md diff --git a/api-docs/8f97bdb0f7390c98ae588bef75b3e335e20758e0901ef154b05141461bd86995.md b/fs/fs_chown_path_uid_gid_callback.md similarity index 100% rename from api-docs/8f97bdb0f7390c98ae588bef75b3e335e20758e0901ef154b05141461bd86995.md rename to fs/fs_chown_path_uid_gid_callback.md diff --git a/api-docs/d5f400de40722cf3d09a05cb400bf56f8825de6a5dc61926bb84724c190626d0.md b/fs/fs_chownsync_path_uid_gid.md similarity index 100% rename from api-docs/d5f400de40722cf3d09a05cb400bf56f8825de6a5dc61926bb84724c190626d0.md rename to fs/fs_chownsync_path_uid_gid.md diff --git a/api-docs/c64abeb1b899db6f9d793befbb2ab239f0035b3d2a754eb05150aedad51a9ac9.md b/fs/fs_close_fd_callback.md similarity index 100% rename from api-docs/c64abeb1b899db6f9d793befbb2ab239f0035b3d2a754eb05150aedad51a9ac9.md rename to fs/fs_close_fd_callback.md diff --git a/api-docs/e635ae1c24e6bd29b9f97cef1a951a6232591849364856a2b0214972e2b46710.md b/fs/fs_closesync_fd.md similarity index 100% rename from api-docs/e635ae1c24e6bd29b9f97cef1a951a6232591849364856a2b0214972e2b46710.md rename to fs/fs_closesync_fd.md diff --git a/api-docs/80493ac8641268e677eae8029b5dce445d61749f2171fb4d19aab9fb5dc83c15.md b/fs/fs_constants.md similarity index 100% rename from api-docs/80493ac8641268e677eae8029b5dce445d61749f2171fb4d19aab9fb5dc83c15.md rename to fs/fs_constants.md diff --git a/api-docs/aa0a14ab96d08fde34d9a822f3d832ee5752cd8f7601f52c5f60bdb6571fcea6.md b/fs/fs_constants_1.md similarity index 100% rename from api-docs/aa0a14ab96d08fde34d9a822f3d832ee5752cd8f7601f52c5f60bdb6571fcea6.md rename to fs/fs_constants_1.md diff --git a/api-docs/07040bbfc29a723a9c71b198888d38f81bab8eb2585923e8e9f5110bb3d08a34.md b/fs/fs_copyfile_src_dest_flags_callback.md similarity index 100% rename from api-docs/07040bbfc29a723a9c71b198888d38f81bab8eb2585923e8e9f5110bb3d08a34.md rename to fs/fs_copyfile_src_dest_flags_callback.md diff --git a/api-docs/582339f530324a581cb0a798168dfaf0d1ca17c43f3d752f07aaec5378df64ef.md b/fs/fs_copyfilesync_src_dest_flags.md similarity index 100% rename from api-docs/582339f530324a581cb0a798168dfaf0d1ca17c43f3d752f07aaec5378df64ef.md rename to fs/fs_copyfilesync_src_dest_flags.md diff --git a/api-docs/d2059fea94113af3bcb596414b4d0d47c6e0159e4ee205e990895cf6927b9a21.md b/fs/fs_createreadstream_path_options.md similarity index 100% rename from api-docs/d2059fea94113af3bcb596414b4d0d47c6e0159e4ee205e990895cf6927b9a21.md rename to fs/fs_createreadstream_path_options.md diff --git a/api-docs/8bf8daccafc1b5ce32792524d3c25491da9111f893dda41eeabc5f86da1be8e6.md b/fs/fs_createwritestream_path_options.md similarity index 100% rename from api-docs/8bf8daccafc1b5ce32792524d3c25491da9111f893dda41eeabc5f86da1be8e6.md rename to fs/fs_createwritestream_path_options.md diff --git a/api-docs/b96b5fdf929a05633b75d520149d1bc45b7598a0740de3c2eeb65ca0161e544a.md b/fs/fs_exists_path_callback.md similarity index 100% rename from api-docs/b96b5fdf929a05633b75d520149d1bc45b7598a0740de3c2eeb65ca0161e544a.md rename to fs/fs_exists_path_callback.md diff --git a/api-docs/0db9222d1b91e8335de7e1c0b37d3975ed3b6f47aec64c57c4c811882afbf79e.md b/fs/fs_existssync_path.md similarity index 100% rename from api-docs/0db9222d1b91e8335de7e1c0b37d3975ed3b6f47aec64c57c4c811882afbf79e.md rename to fs/fs_existssync_path.md diff --git a/api-docs/14ac864133b5a08ebd5378a1db7f85985dc3d0b2b5705f84ac0db504bd44de6a.md b/fs/fs_fchmod_fd_mode_callback.md similarity index 100% rename from api-docs/14ac864133b5a08ebd5378a1db7f85985dc3d0b2b5705f84ac0db504bd44de6a.md rename to fs/fs_fchmod_fd_mode_callback.md diff --git a/api-docs/83116c5f07693b3a9d35ea9c82ec7bfa667531d5e48ad9a0266609c0d2b97a32.md b/fs/fs_fchmodsync_fd_mode.md similarity index 100% rename from api-docs/83116c5f07693b3a9d35ea9c82ec7bfa667531d5e48ad9a0266609c0d2b97a32.md rename to fs/fs_fchmodsync_fd_mode.md diff --git a/api-docs/faaf3b2f50ea4d044983f7161c207117c77dd3a57d1ffc9a7bcf2057afef04cc.md b/fs/fs_fchown_fd_uid_gid_callback.md similarity index 100% rename from api-docs/faaf3b2f50ea4d044983f7161c207117c77dd3a57d1ffc9a7bcf2057afef04cc.md rename to fs/fs_fchown_fd_uid_gid_callback.md diff --git a/api-docs/402e03338e5350fd6af6ccafb79711b7d0bd5a987e736822446df407d61d5bd1.md b/fs/fs_fchownsync_fd_uid_gid.md similarity index 100% rename from api-docs/402e03338e5350fd6af6ccafb79711b7d0bd5a987e736822446df407d61d5bd1.md rename to fs/fs_fchownsync_fd_uid_gid.md diff --git a/api-docs/3c235dac15cea3299b7ae5673cb51a18e94363c46dfbf0e068aba07b86a57ccc.md b/fs/fs_fdatasync_fd_callback.md similarity index 100% rename from api-docs/3c235dac15cea3299b7ae5673cb51a18e94363c46dfbf0e068aba07b86a57ccc.md rename to fs/fs_fdatasync_fd_callback.md diff --git a/api-docs/a7bb87b12c9dfbcf26fc941f51782d850d96126614dba3297af5295b7df5a34a.md b/fs/fs_fdatasyncsync_fd.md similarity index 100% rename from api-docs/a7bb87b12c9dfbcf26fc941f51782d850d96126614dba3297af5295b7df5a34a.md rename to fs/fs_fdatasyncsync_fd.md diff --git a/api-docs/0063902be8ec0a0b80ba44ff62f30e55ddcb7101b82735a54d12a30f1adf7d56.md b/fs/fs_fstat_fd_options_callback.md similarity index 100% rename from api-docs/0063902be8ec0a0b80ba44ff62f30e55ddcb7101b82735a54d12a30f1adf7d56.md rename to fs/fs_fstat_fd_options_callback.md diff --git a/api-docs/59e26f1ce794d12b3b267faac1c852b84500d3769f590f224c322f895690d67c.md b/fs/fs_fstatsync_fd_options.md similarity index 100% rename from api-docs/59e26f1ce794d12b3b267faac1c852b84500d3769f590f224c322f895690d67c.md rename to fs/fs_fstatsync_fd_options.md diff --git a/api-docs/c44d8e8aa5398c05b119c8c2941c6170bbc48e38576f2c20357725c41081a4c7.md b/fs/fs_fsync_fd_callback.md similarity index 100% rename from api-docs/c44d8e8aa5398c05b119c8c2941c6170bbc48e38576f2c20357725c41081a4c7.md rename to fs/fs_fsync_fd_callback.md diff --git a/api-docs/8ffed1a221eb092f4d7785f70710f42e0d26e1f81f3778f63263e761f280dba8.md b/fs/fs_fsyncsync_fd.md similarity index 100% rename from api-docs/8ffed1a221eb092f4d7785f70710f42e0d26e1f81f3778f63263e761f280dba8.md rename to fs/fs_fsyncsync_fd.md diff --git a/api-docs/83108f48863cd56f1256ac6bc42fdaf72a2dab89234f83449189b61be93ef3e2.md b/fs/fs_ftruncate_fd_len_callback.md similarity index 100% rename from api-docs/83108f48863cd56f1256ac6bc42fdaf72a2dab89234f83449189b61be93ef3e2.md rename to fs/fs_ftruncate_fd_len_callback.md diff --git a/api-docs/df472271f69eef9802e6b998116fbfc5e531a2db952cd96e5e0684ecf2ee0124.md b/fs/fs_ftruncatesync_fd_len.md similarity index 100% rename from api-docs/df472271f69eef9802e6b998116fbfc5e531a2db952cd96e5e0684ecf2ee0124.md rename to fs/fs_ftruncatesync_fd_len.md diff --git a/api-docs/4cfae0226d9f9b0ae1f43e4eca4d7fa22874d51545a60677d3d28113f9fa2feb.md b/fs/fs_futimes_fd_atime_mtime_callback.md similarity index 100% rename from api-docs/4cfae0226d9f9b0ae1f43e4eca4d7fa22874d51545a60677d3d28113f9fa2feb.md rename to fs/fs_futimes_fd_atime_mtime_callback.md diff --git a/api-docs/c37494a716940c576053818d573ec71bf5a32b7e54c63d7384644c3aef32de9d.md b/fs/fs_futimessync_fd_atime_mtime.md similarity index 100% rename from api-docs/c37494a716940c576053818d573ec71bf5a32b7e54c63d7384644c3aef32de9d.md rename to fs/fs_futimessync_fd_atime_mtime.md diff --git a/api-docs/121fb160125d7d651af229d6eaa29f0a3617a207cf0d4744d4b8c5f966b216bf.md b/fs/fs_lchmod_path_mode_callback.md similarity index 100% rename from api-docs/121fb160125d7d651af229d6eaa29f0a3617a207cf0d4744d4b8c5f966b216bf.md rename to fs/fs_lchmod_path_mode_callback.md diff --git a/api-docs/2a2a644d212f4eea6bb3070bf64ca4cd1b2a09e3d5994b15e588fcd513e17b1a.md b/fs/fs_lchmodsync_path_mode.md similarity index 100% rename from api-docs/2a2a644d212f4eea6bb3070bf64ca4cd1b2a09e3d5994b15e588fcd513e17b1a.md rename to fs/fs_lchmodsync_path_mode.md diff --git a/api-docs/2f140914a056deb8a8c6502b7374f24b8a42a69a5d7bbd58a83a47c18dec8aa7.md b/fs/fs_lchown_path_uid_gid_callback.md similarity index 100% rename from api-docs/2f140914a056deb8a8c6502b7374f24b8a42a69a5d7bbd58a83a47c18dec8aa7.md rename to fs/fs_lchown_path_uid_gid_callback.md diff --git a/api-docs/3ec5f27abcbe4bddad003023aefb37b9460fc15ff9e0abb3bbfe6b5fe427718b.md b/fs/fs_lchownsync_path_uid_gid.md similarity index 100% rename from api-docs/3ec5f27abcbe4bddad003023aefb37b9460fc15ff9e0abb3bbfe6b5fe427718b.md rename to fs/fs_lchownsync_path_uid_gid.md diff --git a/api-docs/1cccecbdcc50e758e510e5fb066c1ccdd114c18c669258db426887131ff832d5.md b/fs/fs_link_existingpath_newpath_callback.md similarity index 100% rename from api-docs/1cccecbdcc50e758e510e5fb066c1ccdd114c18c669258db426887131ff832d5.md rename to fs/fs_link_existingpath_newpath_callback.md diff --git a/api-docs/00609e317ed1df5146845c5792390df8224a055a21e6cc41cfc5434186796d81.md b/fs/fs_linksync_existingpath_newpath.md similarity index 100% rename from api-docs/00609e317ed1df5146845c5792390df8224a055a21e6cc41cfc5434186796d81.md rename to fs/fs_linksync_existingpath_newpath.md diff --git a/api-docs/5879cef1dee7bac8378fd9fb7e9e6703666653be79744d8ff5873d322fad50a1.md b/fs/fs_lstat_path_options_callback.md similarity index 100% rename from api-docs/5879cef1dee7bac8378fd9fb7e9e6703666653be79744d8ff5873d322fad50a1.md rename to fs/fs_lstat_path_options_callback.md diff --git a/api-docs/ce1468a18df43d789eb70fb1443b757464d7efc9ab15b71e8d105174335c7f77.md b/fs/fs_lstatsync_path_options.md similarity index 100% rename from api-docs/ce1468a18df43d789eb70fb1443b757464d7efc9ab15b71e8d105174335c7f77.md rename to fs/fs_lstatsync_path_options.md diff --git a/api-docs/916ef5ec05626db650365463385b847cdaa7bb962b048c59e39406221145e7d1.md b/fs/fs_mkdir_path_options_callback.md similarity index 100% rename from api-docs/916ef5ec05626db650365463385b847cdaa7bb962b048c59e39406221145e7d1.md rename to fs/fs_mkdir_path_options_callback.md diff --git a/api-docs/412345d4635f085d527a217366000a16bb2841351ece3954cf38698fb7272e69.md b/fs/fs_mkdirsync_path_options.md similarity index 100% rename from api-docs/412345d4635f085d527a217366000a16bb2841351ece3954cf38698fb7272e69.md rename to fs/fs_mkdirsync_path_options.md diff --git a/api-docs/fec33cee170318596fbd8e1dbb3297d832f08759f330672b96286e613a3a7cbc.md b/fs/fs_mkdtemp_prefix_options_callback.md similarity index 100% rename from api-docs/fec33cee170318596fbd8e1dbb3297d832f08759f330672b96286e613a3a7cbc.md rename to fs/fs_mkdtemp_prefix_options_callback.md diff --git a/api-docs/f8b0307c824049e3a3810dc94c50b9551cd32f5f9d43d0aca426f9d520c7c0b6.md b/fs/fs_mkdtempsync_prefix_options.md similarity index 100% rename from api-docs/f8b0307c824049e3a3810dc94c50b9551cd32f5f9d43d0aca426f9d520c7c0b6.md rename to fs/fs_mkdtempsync_prefix_options.md diff --git a/api-docs/04c00d2f179cb71a7c218a8c99aed1a5d2a1cc0fec778c5da2a1496379d7e61b.md b/fs/fs_open_path_flags_mode_callback.md similarity index 100% rename from api-docs/04c00d2f179cb71a7c218a8c99aed1a5d2a1cc0fec778c5da2a1496379d7e61b.md rename to fs/fs_open_path_flags_mode_callback.md diff --git a/api-docs/d3144ae47790e106fad923f8bef365a4477a92bc48c86f6f84305958ff658958.md b/fs/fs_opensync_path_flags_mode.md similarity index 100% rename from api-docs/d3144ae47790e106fad923f8bef365a4477a92bc48c86f6f84305958ff658958.md rename to fs/fs_opensync_path_flags_mode.md diff --git a/api-docs/37a83e64b538311950dc81ad65c041946c2117b541ef9646c7a7743fa55caf17.md b/fs/fs_promises_api.md similarity index 87% rename from api-docs/37a83e64b538311950dc81ad65c041946c2117b541ef9646c7a7743fa55caf17.md rename to fs/fs_promises_api.md index 34906c6f..6cfd33c4 100644 --- a/api-docs/37a83e64b538311950dc81ad65c041946c2117b541ef9646c7a7743fa55caf17.md +++ b/fs/fs_promises_api.md @@ -1,6 +1,4 @@ -> 稳定性: 2 - 稳定 - `fs.promises` API 提供了一组备用的异步文件系统的方法，它们返回 `Promise` 对象而不是使用回调。 API 可通过 `require('fs').promises` 访问。 diff --git a/api-docs/f8305bd0aa22fd075a19877f5be201e0999cc58bdc271435779e7ce3a7897b75.md b/fs/fs_read_fd_buffer_offset_length_position_callback.md similarity index 100% rename from api-docs/f8305bd0aa22fd075a19877f5be201e0999cc58bdc271435779e7ce3a7897b75.md rename to fs/fs_read_fd_buffer_offset_length_position_callback.md diff --git a/api-docs/ed50d1a85e1dd4364d6d61a3ec7f15fdc9d482dacc64b9c3280da7505fb34383.md b/fs/fs_readdir_path_options_callback.md similarity index 100% rename from api-docs/ed50d1a85e1dd4364d6d61a3ec7f15fdc9d482dacc64b9c3280da7505fb34383.md rename to fs/fs_readdir_path_options_callback.md diff --git a/api-docs/6680fb1ec8d52a092a1467a69c51a4ab81ffcfd9801bcb320be95b38842463e5.md b/fs/fs_readdirsync_path_options.md similarity index 100% rename from api-docs/6680fb1ec8d52a092a1467a69c51a4ab81ffcfd9801bcb320be95b38842463e5.md rename to fs/fs_readdirsync_path_options.md diff --git a/api-docs/721b3c35bb181e42bb7737337704652df6a6ac628c605d6e59d51ba2aceb823f.md b/fs/fs_readfile_path_options_callback.md similarity index 100% rename from api-docs/721b3c35bb181e42bb7737337704652df6a6ac628c605d6e59d51ba2aceb823f.md rename to fs/fs_readfile_path_options_callback.md diff --git a/api-docs/a4acd63883f0621713b831172d4ae63ca9b5d831d2c776285091d04e967559a0.md b/fs/fs_readfilesync_path_options.md similarity index 100% rename from api-docs/a4acd63883f0621713b831172d4ae63ca9b5d831d2c776285091d04e967559a0.md rename to fs/fs_readfilesync_path_options.md diff --git a/api-docs/4df15c956e17610a73bfa29a7e36168999a0a249a6d6aa6603a0256d16183850.md b/fs/fs_readlink_path_options_callback.md similarity index 100% rename from api-docs/4df15c956e17610a73bfa29a7e36168999a0a249a6d6aa6603a0256d16183850.md rename to fs/fs_readlink_path_options_callback.md diff --git a/api-docs/412a5fb2b8ea26241470388dd00c9ec455555fef0f22b738c779adf097eb7250.md b/fs/fs_readlinksync_path_options.md similarity index 100% rename from api-docs/412a5fb2b8ea26241470388dd00c9ec455555fef0f22b738c779adf097eb7250.md rename to fs/fs_readlinksync_path_options.md diff --git a/api-docs/939bacbd4f707d5eb09b90810f167bdfd7013d7fec58cab90f72dc4e33a6d665.md b/fs/fs_readsync_fd_buffer_offset_length_position.md similarity index 100% rename from api-docs/939bacbd4f707d5eb09b90810f167bdfd7013d7fec58cab90f72dc4e33a6d665.md rename to fs/fs_readsync_fd_buffer_offset_length_position.md diff --git a/api-docs/68aea7934e351f888e7af89470eca48ad4705c84c9d4148bf6510d69f41ea563.md b/fs/fs_realpath_native_path_options_callback.md similarity index 100% rename from api-docs/68aea7934e351f888e7af89470eca48ad4705c84c9d4148bf6510d69f41ea563.md rename to fs/fs_realpath_native_path_options_callback.md diff --git a/api-docs/b5cd66d2d7d9b4bf2da7293dab785a8ea375a8eb4246e29d9d252b6532ebc162.md b/fs/fs_realpath_path_options_callback.md similarity index 100% rename from api-docs/b5cd66d2d7d9b4bf2da7293dab785a8ea375a8eb4246e29d9d252b6532ebc162.md rename to fs/fs_realpath_path_options_callback.md diff --git a/api-docs/e5a52949bbba5296185eebfae9b67eb73cedc8794d32e4bc0a93cef388648003.md b/fs/fs_realpathsync_native_path_options.md similarity index 100% rename from api-docs/e5a52949bbba5296185eebfae9b67eb73cedc8794d32e4bc0a93cef388648003.md rename to fs/fs_realpathsync_native_path_options.md diff --git a/api-docs/91927323979b620a75ac23a95fa596e53d4c6855b7826c337b39d0d95712307e.md b/fs/fs_realpathsync_path_options.md similarity index 100% rename from api-docs/91927323979b620a75ac23a95fa596e53d4c6855b7826c337b39d0d95712307e.md rename to fs/fs_realpathsync_path_options.md diff --git a/api-docs/68cda89f0fd16502a83d90f0f42df23c26abb8fc596978dd0ccb4447a537b191.md b/fs/fs_rename_oldpath_newpath_callback.md similarity index 100% rename from api-docs/68cda89f0fd16502a83d90f0f42df23c26abb8fc596978dd0ccb4447a537b191.md rename to fs/fs_rename_oldpath_newpath_callback.md diff --git a/api-docs/2650eae316acf488a4afb312648ae73dca5901664bb2009d0c5130095ebe6e36.md b/fs/fs_renamesync_oldpath_newpath.md similarity index 100% rename from api-docs/2650eae316acf488a4afb312648ae73dca5901664bb2009d0c5130095ebe6e36.md rename to fs/fs_renamesync_oldpath_newpath.md diff --git a/api-docs/ce2e7cb68f9506fd6e33011db4f8fca4f133d00437e41b297b9b639c1328157d.md b/fs/fs_rmdir_path_callback.md similarity index 100% rename from api-docs/ce2e7cb68f9506fd6e33011db4f8fca4f133d00437e41b297b9b639c1328157d.md rename to fs/fs_rmdir_path_callback.md diff --git a/api-docs/bb575f0cfffada79e3c81ead4d60c1d9aab520294d0d79b8ed34de9ccf3bcd9c.md b/fs/fs_rmdirsync_path.md similarity index 100% rename from api-docs/bb575f0cfffada79e3c81ead4d60c1d9aab520294d0d79b8ed34de9ccf3bcd9c.md rename to fs/fs_rmdirsync_path.md diff --git a/api-docs/9f7c5733510465d53b6b70e9f9a92c50f0888ad049143e0735139e40f2589d5b.md b/fs/fs_stat_path_options_callback.md similarity index 56% rename from api-docs/9f7c5733510465d53b6b70e9f9a92c50f0888ad049143e0735139e40f2589d5b.md rename to fs/fs_stat_path_options_callback.md index aa76c449..22312be7 100644 --- a/api-docs/9f7c5733510465d53b6b70e9f9a92c50f0888ad049143e0735139e40f2589d5b.md +++ b/fs/fs_stat_path_options_callback.md @@ -36,4 +36,73 @@ changes: 要检查文件是否存在但随后并不对其进行操作，则建议使用 [`fs.access()`]。 +例如，给定以下的文件夹结构： + +```fundamental +- txtDir +-- file.txt +- app.js +``` + +以下程序将会检查给定路径的统计信息： + +```js +const fs = require('fs'); + +const pathsToCheck = ['./txtDir', './txtDir/file.txt']; + +for (let i = 0; i < pathsToCheck.length; i++) { + fs.stat(pathsToCheck[i], function(err, stats) { + console.log(stats.isDirectory()); + console.log(stats); + }); +} +``` + +得到的输出将会类似于： + +```console +true +Stats { + dev: 16777220, + mode: 16877, + nlink: 3, + uid: 501, + gid: 20, + rdev: 0, + blksize: 4096, + ino: 14214262, + size: 96, + blocks: 0, + atimeMs: 1561174653071.963, + mtimeMs: 1561174614583.3518, + ctimeMs: 1561174626623.5366, + birthtimeMs: 1561174126937.2893, + atime: 2019-06-22T03:37:33.072Z, + mtime: 2019-06-22T03:36:54.583Z, + ctime: 2019-06-22T03:37:06.624Z, + birthtime: 2019-06-22T03:28:46.937Z +} +false +Stats { + dev: 16777220, + mode: 33188, + nlink: 1, + uid: 501, + gid: 20, + rdev: 0, + blksize: 4096, + ino: 14214074, + size: 8, + blocks: 8, + atimeMs: 1561174616618.8555, + mtimeMs: 1561174614584, + ctimeMs: 1561174614583.8145, + birthtimeMs: 1561174007710.7478, + atime: 2019-06-22T03:36:56.619Z, + mtime: 2019-06-22T03:36:54.584Z, + ctime: 2019-06-22T03:36:54.584Z, + birthtime: 2019-06-22T03:26:47.711Z +} +``` diff --git a/api-docs/c72a8cc3c5294600189f25a570008fd94e3325851e42f5be91907b3bec0d10ac.md b/fs/fs_statsync_path_options.md similarity index 100% rename from api-docs/c72a8cc3c5294600189f25a570008fd94e3325851e42f5be91907b3bec0d10ac.md rename to fs/fs_statsync_path_options.md diff --git a/api-docs/a40417d4bb65fdab7669a8d4c8ed83644aa69c4be8510566e161974b6d28cb89.md b/fs/fs_symlink_target_path_type_callback.md similarity index 100% rename from api-docs/a40417d4bb65fdab7669a8d4c8ed83644aa69c4be8510566e161974b6d28cb89.md rename to fs/fs_symlink_target_path_type_callback.md diff --git a/api-docs/ad396322a893c2f9b0cabe158a4a977f8b377962b6dd3fcf2b731e45c26a507e.md b/fs/fs_symlinksync_target_path_type.md similarity index 100% rename from api-docs/ad396322a893c2f9b0cabe158a4a977f8b377962b6dd3fcf2b731e45c26a507e.md rename to fs/fs_symlinksync_target_path_type.md diff --git a/api-docs/3b8c01e5652fcb10048a991985d4ebc89588dc8d33f528959a11eca02d80e22b.md b/fs/fs_truncate_path_len_callback.md similarity index 100% rename from api-docs/3b8c01e5652fcb10048a991985d4ebc89588dc8d33f528959a11eca02d80e22b.md rename to fs/fs_truncate_path_len_callback.md diff --git a/api-docs/1ae43d987e1df530b1e71f9792039d482a09d383bc7f13278f194290d6ad77c6.md b/fs/fs_truncatesync_path_len.md similarity index 100% rename from api-docs/1ae43d987e1df530b1e71f9792039d482a09d383bc7f13278f194290d6ad77c6.md rename to fs/fs_truncatesync_path_len.md diff --git a/api-docs/3a112b7d3166c7792b8ff3237c83169b25c9d467676935e10db700bc1c54723a.md b/fs/fs_unlink_path_callback.md similarity index 100% rename from api-docs/3a112b7d3166c7792b8ff3237c83169b25c9d467676935e10db700bc1c54723a.md rename to fs/fs_unlink_path_callback.md diff --git a/api-docs/a157ecd4b37db05b2271e71763137bf617ef3dfca92428643036b65b9a4d777e.md b/fs/fs_unlinksync_path.md similarity index 100% rename from api-docs/a157ecd4b37db05b2271e71763137bf617ef3dfca92428643036b65b9a4d777e.md rename to fs/fs_unlinksync_path.md diff --git a/api-docs/c5123d298e551e107cd1b96d901a8d485765314b57d6f45888262e61610de90c.md b/fs/fs_unwatchfile_filename_listener.md similarity index 100% rename from api-docs/c5123d298e551e107cd1b96d901a8d485765314b57d6f45888262e61610de90c.md rename to fs/fs_unwatchfile_filename_listener.md diff --git a/api-docs/52b788f43a5a77484f39a228f19b50e3c66bdd24c7f032196b13a48652e6bf57.md b/fs/fs_utimes_path_atime_mtime_callback.md similarity index 100% rename from api-docs/52b788f43a5a77484f39a228f19b50e3c66bdd24c7f032196b13a48652e6bf57.md rename to fs/fs_utimes_path_atime_mtime_callback.md diff --git a/api-docs/84ab11d74d703d63a80e0f998edd1a98d394b6f79f7634b5042a475818476a50.md b/fs/fs_utimessync_path_atime_mtime.md similarity index 100% rename from api-docs/84ab11d74d703d63a80e0f998edd1a98d394b6f79f7634b5042a475818476a50.md rename to fs/fs_utimessync_path_atime_mtime.md diff --git a/api-docs/c65d07367a826be5809004c5b70490d70435377e1b9f0b6c5439008f57597f9f.md b/fs/fs_watch_filename_options_listener.md similarity index 100% rename from api-docs/c65d07367a826be5809004c5b70490d70435377e1b9f0b6c5439008f57597f9f.md rename to fs/fs_watch_filename_options_listener.md diff --git a/api-docs/a20afc2673fd35bcff64115340ee0af6f013ab45f06820e31ea61231f2fc2e1a.md b/fs/fs_watchfile_filename_options_listener.md similarity index 100% rename from api-docs/a20afc2673fd35bcff64115340ee0af6f013ab45f06820e31ea61231f2fc2e1a.md rename to fs/fs_watchfile_filename_options_listener.md diff --git a/api-docs/db04fbf2e448bcfc967e95b1234acb51ce77b8839181f207c73b260be218cdbe.md b/fs/fs_write_fd_buffer_offset_length_position_callback.md similarity index 100% rename from api-docs/db04fbf2e448bcfc967e95b1234acb51ce77b8839181f207c73b260be218cdbe.md rename to fs/fs_write_fd_buffer_offset_length_position_callback.md diff --git a/api-docs/7f0d63d2db4e79fc9f97879764798aac2056f73f1b681626318b8614a05db59c.md b/fs/fs_write_fd_string_position_encoding_callback.md similarity index 100% rename from api-docs/7f0d63d2db4e79fc9f97879764798aac2056f73f1b681626318b8614a05db59c.md rename to fs/fs_write_fd_string_position_encoding_callback.md diff --git a/api-docs/528c640b24a47ad7684dae19d4071a9d87ea55a4638f074d3dee9844ab661425.md b/fs/fs_writefile_file_data_options_callback.md similarity index 100% rename from api-docs/528c640b24a47ad7684dae19d4071a9d87ea55a4638f074d3dee9844ab661425.md rename to fs/fs_writefile_file_data_options_callback.md diff --git a/api-docs/aab8f1590ec716b398e844e585de788ae5d41d5ce032a34d1748cdc286ad7eeb.md b/fs/fs_writefilesync_file_data_options.md similarity index 100% rename from api-docs/aab8f1590ec716b398e844e585de788ae5d41d5ce032a34d1748cdc286ad7eeb.md rename to fs/fs_writefilesync_file_data_options.md diff --git a/api-docs/4282088f43d57e7fbf6761cc096af30ed4e8e8903dd6ed3273d4d05c189b5c51.md b/fs/fs_writesync_fd_buffer_offset_length_position.md similarity index 100% rename from api-docs/4282088f43d57e7fbf6761cc096af30ed4e8e8903dd6ed3273d4d05c189b5c51.md rename to fs/fs_writesync_fd_buffer_offset_length_position.md diff --git a/api-docs/ed7ab4dc181014d34648f66f7fff409734cb563b8f0c2a2438fe5ecbd8b3a63c.md b/fs/fs_writesync_fd_string_position_encoding.md similarity index 100% rename from api-docs/ed7ab4dc181014d34648f66f7fff409734cb563b8f0c2a2438fe5ecbd8b3a63c.md rename to fs/fs_writesync_fd_string_position_encoding.md diff --git a/api-docs/8d5d961d3bff703fc3e33fb7fc9625394786cedb27bfa90c2393c0492393bd63.md b/fs/fspromises_access_path_mode.md similarity index 100% rename from api-docs/8d5d961d3bff703fc3e33fb7fc9625394786cedb27bfa90c2393c0492393bd63.md rename to fs/fspromises_access_path_mode.md diff --git a/api-docs/3dd4a20021f24239a23efa16f5c921cfff2c291eea7823e7f6c8258d71f2e769.md b/fs/fspromises_appendfile_path_data_options.md similarity index 100% rename from api-docs/3dd4a20021f24239a23efa16f5c921cfff2c291eea7823e7f6c8258d71f2e769.md rename to fs/fspromises_appendfile_path_data_options.md diff --git a/api-docs/19d613633709fdd7e0cc764b39e689df1e6854b73caedbb6d2de21522722e061.md b/fs/fspromises_chmod_path_mode.md similarity index 100% rename from api-docs/19d613633709fdd7e0cc764b39e689df1e6854b73caedbb6d2de21522722e061.md rename to fs/fspromises_chmod_path_mode.md diff --git a/api-docs/f3d2ce7793e566d310ee50802842b3249a01a3080fea38aac5a233c507a020d0.md b/fs/fspromises_chown_path_uid_gid.md similarity index 100% rename from api-docs/f3d2ce7793e566d310ee50802842b3249a01a3080fea38aac5a233c507a020d0.md rename to fs/fspromises_chown_path_uid_gid.md diff --git a/api-docs/41340051524c62354ed172d2332564d785a42d24174f89dea2a8521a395ca094.md b/fs/fspromises_copyfile_src_dest_flags.md similarity index 100% rename from api-docs/41340051524c62354ed172d2332564d785a42d24174f89dea2a8521a395ca094.md rename to fs/fspromises_copyfile_src_dest_flags.md diff --git a/api-docs/cb7babe0d202ef301c73fe1522082fe704eece0414726d86033aef9113f4a5b2.md b/fs/fspromises_lchmod_path_mode.md similarity index 100% rename from api-docs/cb7babe0d202ef301c73fe1522082fe704eece0414726d86033aef9113f4a5b2.md rename to fs/fspromises_lchmod_path_mode.md diff --git a/api-docs/c49dd6b00e2c21f256a96a5564e843a32eb1f4ff79cb070b93d5fb3ed47b3bdf.md b/fs/fspromises_lchown_path_uid_gid.md similarity index 100% rename from api-docs/c49dd6b00e2c21f256a96a5564e843a32eb1f4ff79cb070b93d5fb3ed47b3bdf.md rename to fs/fspromises_lchown_path_uid_gid.md diff --git a/api-docs/4c1da95e67ee9bc7db4b7e119f5c834b70798f5bc05fe52535355e8cfbbfa194.md b/fs/fspromises_link_existingpath_newpath.md similarity index 100% rename from api-docs/4c1da95e67ee9bc7db4b7e119f5c834b70798f5bc05fe52535355e8cfbbfa194.md rename to fs/fspromises_link_existingpath_newpath.md diff --git a/api-docs/13d330dce7d38f3bfd2305eaeef8e705e0cbc189ad81b060af65673032f4c758.md b/fs/fspromises_lstat_path_options.md similarity index 100% rename from api-docs/13d330dce7d38f3bfd2305eaeef8e705e0cbc189ad81b060af65673032f4c758.md rename to fs/fspromises_lstat_path_options.md diff --git a/api-docs/32ec6a071562bd1d524a042203adbd1730f7bbdade776e00af48773bab2cab23.md b/fs/fspromises_mkdir_path_options.md similarity index 100% rename from api-docs/32ec6a071562bd1d524a042203adbd1730f7bbdade776e00af48773bab2cab23.md rename to fs/fspromises_mkdir_path_options.md diff --git a/api-docs/dfda47b6fb1dcb092a437c5ae82da6e06f3b4dbdc63ad1a563b9a413f4e0f0ef.md b/fs/fspromises_mkdtemp_prefix_options.md similarity index 100% rename from api-docs/dfda47b6fb1dcb092a437c5ae82da6e06f3b4dbdc63ad1a563b9a413f4e0f0ef.md rename to fs/fspromises_mkdtemp_prefix_options.md diff --git a/api-docs/2de1e3b00f838ce0faf8377cf4837f4b9edcddba7cb353f922c7f1d5119e8016.md b/fs/fspromises_open_path_flags_mode.md similarity index 100% rename from api-docs/2de1e3b00f838ce0faf8377cf4837f4b9edcddba7cb353f922c7f1d5119e8016.md rename to fs/fspromises_open_path_flags_mode.md diff --git a/api-docs/ef8106cb082c1a20d5a17cdc0a5b3befa30090c9c979de0768155db92e2cae5d.md b/fs/fspromises_readdir_path_options.md similarity index 100% rename from api-docs/ef8106cb082c1a20d5a17cdc0a5b3befa30090c9c979de0768155db92e2cae5d.md rename to fs/fspromises_readdir_path_options.md diff --git a/api-docs/85ba8db3453d86d00985d5e59cd1435473d17cd1458e736ec3960acec3e196c0.md b/fs/fspromises_readfile_path_options.md similarity index 100% rename from api-docs/85ba8db3453d86d00985d5e59cd1435473d17cd1458e736ec3960acec3e196c0.md rename to fs/fspromises_readfile_path_options.md diff --git a/api-docs/c899a2e3b1a34158de5eb2b0c1854d3bc3b766c639fd4faf634e2a7fd00b374f.md b/fs/fspromises_readlink_path_options.md similarity index 100% rename from api-docs/c899a2e3b1a34158de5eb2b0c1854d3bc3b766c639fd4faf634e2a7fd00b374f.md rename to fs/fspromises_readlink_path_options.md diff --git a/api-docs/ebbf4f2e3301b7f75d0aeec97f9fc9659be84fc147249909496f0bdd5c75c4b9.md b/fs/fspromises_realpath_path_options.md similarity index 100% rename from api-docs/ebbf4f2e3301b7f75d0aeec97f9fc9659be84fc147249909496f0bdd5c75c4b9.md rename to fs/fspromises_realpath_path_options.md diff --git a/api-docs/0792d2fb3d84f061d29ef0eec783cb7349ad1d88d2858a798562e8d654943e4c.md b/fs/fspromises_rename_oldpath_newpath.md similarity index 100% rename from api-docs/0792d2fb3d84f061d29ef0eec783cb7349ad1d88d2858a798562e8d654943e4c.md rename to fs/fspromises_rename_oldpath_newpath.md diff --git a/api-docs/894900a9d7f401edddd691af91396b5ac37cbef8ffe302316931004fc60acd60.md b/fs/fspromises_rmdir_path.md similarity index 100% rename from api-docs/894900a9d7f401edddd691af91396b5ac37cbef8ffe302316931004fc60acd60.md rename to fs/fspromises_rmdir_path.md diff --git a/api-docs/45a720886dc4124ac45c4fb1034df46c3fb3f44668535c40a89b9b507ae76659.md b/fs/fspromises_stat_path_options.md similarity index 100% rename from api-docs/45a720886dc4124ac45c4fb1034df46c3fb3f44668535c40a89b9b507ae76659.md rename to fs/fspromises_stat_path_options.md diff --git a/api-docs/9494cd21840cbb9e20bff6d79af618884dbddc48b3eb30b01e1be23446be36f0.md b/fs/fspromises_symlink_target_path_type.md similarity index 100% rename from api-docs/9494cd21840cbb9e20bff6d79af618884dbddc48b3eb30b01e1be23446be36f0.md rename to fs/fspromises_symlink_target_path_type.md diff --git a/api-docs/b46d1aa1232f2116181f2df58e279fd5b09d2d0e64134b0b949b70e7a3229d81.md b/fs/fspromises_truncate_path_len.md similarity index 100% rename from api-docs/b46d1aa1232f2116181f2df58e279fd5b09d2d0e64134b0b949b70e7a3229d81.md rename to fs/fspromises_truncate_path_len.md diff --git a/api-docs/6cff32a0eeb5c1d38a84b212f1b88d6f7621ccbb613b1b9264fec80e7856609d.md b/fs/fspromises_unlink_path.md similarity index 100% rename from api-docs/6cff32a0eeb5c1d38a84b212f1b88d6f7621ccbb613b1b9264fec80e7856609d.md rename to fs/fspromises_unlink_path.md diff --git a/api-docs/29bf83abfa3ad48fbd6ed16bbb017ad23cf8ec84deabb4b9f52bb82a2dd7704b.md b/fs/fspromises_utimes_path_atime_mtime.md similarity index 100% rename from api-docs/29bf83abfa3ad48fbd6ed16bbb017ad23cf8ec84deabb4b9f52bb82a2dd7704b.md rename to fs/fspromises_utimes_path_atime_mtime.md diff --git a/api-docs/8f02cdd17405f2d44120ed99734da2d238636483b9d55b507afa93c71040be94.md b/fs/fspromises_writefile_file_data_options.md similarity index 100% rename from api-docs/8f02cdd17405f2d44120ed99734da2d238636483b9d55b507afa93c71040be94.md rename to fs/fspromises_writefile_file_data_options.md diff --git a/api-docs/ae07c316c53e4e433c340306a5d419541998569b0df86d118d6acdfd42cde31d.md b/fs/inodes.md similarity index 100% rename from api-docs/ae07c316c53e4e433c340306a5d419541998569b0df86d118d6acdfd42cde31d.md rename to fs/inodes.md diff --git a/api-docs/b5b4c81794296ece3da94eba88d603bbae0f41be889bbb913068fbc501cc5266.md b/fs/readstream_bytesread.md similarity index 100% rename from api-docs/b5b4c81794296ece3da94eba88d603bbae0f41be889bbb913068fbc501cc5266.md rename to fs/readstream_bytesread.md diff --git a/api-docs/d0a4009dfe754ed27d6f05c7978dbf5cea408d418909dd5cacf29677ef130ebd.md b/fs/readstream_path.md similarity index 100% rename from api-docs/d0a4009dfe754ed27d6f05c7978dbf5cea408d418909dd5cacf29677ef130ebd.md rename to fs/readstream_path.md diff --git a/api-docs/15c579b76794b525eb9096d29f13918055e876db85edad825ebce45e2ebce95a.md b/fs/readstream_pending.md similarity index 100% rename from api-docs/15c579b76794b525eb9096d29f13918055e876db85edad825ebce45e2ebce95a.md rename to fs/readstream_pending.md diff --git a/api-docs/b0316afe28d9693c95d0b185ae3e7b9eae271baf6ade020545ae6a351076cbee.md b/fs/stat_time_values.md similarity index 100% rename from api-docs/b0316afe28d9693c95d0b185ae3e7b9eae271baf6ade020545ae6a351076cbee.md rename to fs/stat_time_values.md diff --git a/api-docs/313eee8428d583f55db44ac791ebea77dea56c1988953b81ece0be3c2cda9ca8.md b/fs/stats_atime.md similarity index 100% rename from api-docs/313eee8428d583f55db44ac791ebea77dea56c1988953b81ece0be3c2cda9ca8.md rename to fs/stats_atime.md diff --git a/api-docs/a6bec46f071d8fee8182c506d0a90e6eb9a0ba49fb77219c6d99cefa6dcc66fc.md b/fs/stats_atimems.md similarity index 100% rename from api-docs/a6bec46f071d8fee8182c506d0a90e6eb9a0ba49fb77219c6d99cefa6dcc66fc.md rename to fs/stats_atimems.md diff --git a/api-docs/d3caaf2b713000d5b384e2781c702e00ebe6e406510afd107c722a6703a8ee88.md b/fs/stats_birthtime.md similarity index 100% rename from api-docs/d3caaf2b713000d5b384e2781c702e00ebe6e406510afd107c722a6703a8ee88.md rename to fs/stats_birthtime.md diff --git a/api-docs/3dae62f7d7062d035d8d2dc3053f65bdd59e414aa90ef8384933dd0e09b38cb4.md b/fs/stats_birthtimems.md similarity index 100% rename from api-docs/3dae62f7d7062d035d8d2dc3053f65bdd59e414aa90ef8384933dd0e09b38cb4.md rename to fs/stats_birthtimems.md diff --git a/api-docs/d568dc2cad4c0afc134457287434c3c822a597d48a34a9616ae8ad1755532883.md b/fs/stats_blksize.md similarity index 100% rename from api-docs/d568dc2cad4c0afc134457287434c3c822a597d48a34a9616ae8ad1755532883.md rename to fs/stats_blksize.md diff --git a/api-docs/ad11441334bbbc9ac4c1fd11bd166dbca1b870a1133ad517948d7f3766cee6b9.md b/fs/stats_blocks.md similarity index 100% rename from api-docs/ad11441334bbbc9ac4c1fd11bd166dbca1b870a1133ad517948d7f3766cee6b9.md rename to fs/stats_blocks.md diff --git a/api-docs/8db6253c159122bdb8ab23cf838578fd573280df02aeecda726075995f993a79.md b/fs/stats_ctime.md similarity index 100% rename from api-docs/8db6253c159122bdb8ab23cf838578fd573280df02aeecda726075995f993a79.md rename to fs/stats_ctime.md diff --git a/api-docs/1d6bc9736273fbf42587f81b39fa9b956d379070fc6e36e4dde52f7a9e2997b1.md b/fs/stats_ctimems.md similarity index 100% rename from api-docs/1d6bc9736273fbf42587f81b39fa9b956d379070fc6e36e4dde52f7a9e2997b1.md rename to fs/stats_ctimems.md diff --git a/api-docs/c8ffe59115d2b327ffe00b6ba5fc45ab0db600421f0d78c0a46d28b675caba77.md b/fs/stats_dev.md similarity index 100% rename from api-docs/c8ffe59115d2b327ffe00b6ba5fc45ab0db600421f0d78c0a46d28b675caba77.md rename to fs/stats_dev.md diff --git a/api-docs/11d77e0692b07e7539818434b327aa7adc2ed7af469819552ce88267e11bb26d.md b/fs/stats_gid.md similarity index 100% rename from api-docs/11d77e0692b07e7539818434b327aa7adc2ed7af469819552ce88267e11bb26d.md rename to fs/stats_gid.md diff --git a/api-docs/434d52eb97baa59ed3cfd6d20f9ce18dfa5669d709b7dd32e06ea99c1c264f70.md b/fs/stats_ino.md similarity index 100% rename from api-docs/434d52eb97baa59ed3cfd6d20f9ce18dfa5669d709b7dd32e06ea99c1c264f70.md rename to fs/stats_ino.md diff --git a/api-docs/4815c56553ee650e77b39dca44fa182b3945b564d623d63f3025dbc3c5d7fb35.md b/fs/stats_isblockdevice.md similarity index 100% rename from api-docs/4815c56553ee650e77b39dca44fa182b3945b564d623d63f3025dbc3c5d7fb35.md rename to fs/stats_isblockdevice.md diff --git a/api-docs/0d7b26f3ed32b13edd46a0b2d9de225e946ade4452e3aed62072608fd535c88b.md b/fs/stats_ischaracterdevice.md similarity index 100% rename from api-docs/0d7b26f3ed32b13edd46a0b2d9de225e946ade4452e3aed62072608fd535c88b.md rename to fs/stats_ischaracterdevice.md diff --git a/api-docs/62534a6dae206742631c36bb615b0a48e3f347ee377bf4037590f1c156ba78da.md b/fs/stats_isdirectory.md similarity index 100% rename from api-docs/62534a6dae206742631c36bb615b0a48e3f347ee377bf4037590f1c156ba78da.md rename to fs/stats_isdirectory.md diff --git a/api-docs/19ca0acb2739a76668ad993959487e7912e18f063e00e1982d1209f041a3b54d.md b/fs/stats_isfifo.md similarity index 100% rename from api-docs/19ca0acb2739a76668ad993959487e7912e18f063e00e1982d1209f041a3b54d.md rename to fs/stats_isfifo.md diff --git a/api-docs/74fd45741f39f7701a6bc15d4e1a7f76708307f6bce626ef6de71e28dbe237cb.md b/fs/stats_isfile.md similarity index 100% rename from api-docs/74fd45741f39f7701a6bc15d4e1a7f76708307f6bce626ef6de71e28dbe237cb.md rename to fs/stats_isfile.md diff --git a/api-docs/f359c1fd60b9b51efa6d657db6c0dc6462ba503e3f7eba9ec8549bb4401c8245.md b/fs/stats_issocket.md similarity index 100% rename from api-docs/f359c1fd60b9b51efa6d657db6c0dc6462ba503e3f7eba9ec8549bb4401c8245.md rename to fs/stats_issocket.md diff --git a/api-docs/3166671dfb9acfe5a28ab14cac167d304365a0c466f84f1f85b14cf7beaac6fc.md b/fs/stats_issymboliclink.md similarity index 100% rename from api-docs/3166671dfb9acfe5a28ab14cac167d304365a0c466f84f1f85b14cf7beaac6fc.md rename to fs/stats_issymboliclink.md diff --git a/api-docs/2560e43c994542414e5f7dd71e406abe8fdca909547226824e73d029844bd2f5.md b/fs/stats_mode.md similarity index 100% rename from api-docs/2560e43c994542414e5f7dd71e406abe8fdca909547226824e73d029844bd2f5.md rename to fs/stats_mode.md diff --git a/api-docs/b8a0ed356b7c13e08cbf0b7d24b95575a24d101ef3e59334227b35c621d9f947.md b/fs/stats_mtime.md similarity index 100% rename from api-docs/b8a0ed356b7c13e08cbf0b7d24b95575a24d101ef3e59334227b35c621d9f947.md rename to fs/stats_mtime.md diff --git a/api-docs/6f99bbb276eebbbb31f67d2acf696c98ef5a8d33c8d0b3b832a34e1e8b17924a.md b/fs/stats_mtimems.md similarity index 100% rename from api-docs/6f99bbb276eebbbb31f67d2acf696c98ef5a8d33c8d0b3b832a34e1e8b17924a.md rename to fs/stats_mtimems.md diff --git a/api-docs/c64c9d108c566f4f3e5a0302fac97b1cc591c8d3bfd84d1c8c9a6f1c091e4e76.md b/fs/stats_nlink.md similarity index 100% rename from api-docs/c64c9d108c566f4f3e5a0302fac97b1cc591c8d3bfd84d1c8c9a6f1c091e4e76.md rename to fs/stats_nlink.md diff --git a/api-docs/fb836c98861bfa34fc147831d0743d40e801a1edc38d82c3451ea00882116306.md b/fs/stats_rdev.md similarity index 100% rename from api-docs/fb836c98861bfa34fc147831d0743d40e801a1edc38d82c3451ea00882116306.md rename to fs/stats_rdev.md diff --git a/api-docs/0ed3c0c79dd6f094207fb89605a39d35dc0484b12eca6ed987a269d09d247382.md b/fs/stats_size.md similarity index 100% rename from api-docs/0ed3c0c79dd6f094207fb89605a39d35dc0484b12eca6ed987a269d09d247382.md rename to fs/stats_size.md diff --git a/api-docs/f25bd3f24ed9e9e85073386f7e93bc1beeafa37bfe3112615cf431934e20443f.md b/fs/stats_uid.md similarity index 100% rename from api-docs/f25bd3f24ed9e9e85073386f7e93bc1beeafa37bfe3112615cf431934e20443f.md rename to fs/stats_uid.md diff --git a/api-docs/1ee6e7e8b68b8434ff74fa1676f2533a38940793a55c7d456091fb7f2151bde3.md b/fs/threadpool_usage.md similarity index 100% rename from api-docs/1ee6e7e8b68b8434ff74fa1676f2533a38940793a55c7d456091fb7f2151bde3.md rename to fs/threadpool_usage.md diff --git a/api-docs/61a0048dfe69f03559e530b72bda771ead34e8af177f196017098dacc981a66f.md b/fs/url_object_support.md similarity index 100% rename from api-docs/61a0048dfe69f03559e530b72bda771ead34e8af177f196017098dacc981a66f.md rename to fs/url_object_support.md diff --git a/api-docs/81870c1cc67b268305329d8f992460dfc6faebc13aa19df7c7a83860816b2e0d.md b/fs/using_fs_writefile_with_file_descriptors.md similarity index 100% rename from api-docs/81870c1cc67b268305329d8f992460dfc6faebc13aa19df7c7a83860816b2e0d.md rename to fs/using_fs_writefile_with_file_descriptors.md diff --git a/api-docs/3d19d50c363be1093fcf35393bff8af7fadda457a32712b18192ba60da5bb6fa.md b/fs/watcher_close.md similarity index 100% rename from api-docs/3d19d50c363be1093fcf35393bff8af7fadda457a32712b18192ba60da5bb6fa.md rename to fs/watcher_close.md diff --git a/api-docs/8785adc50c0e9feefad3703fe97218378940b0556afdef9c905f145430375f3c.md b/fs/writestream_byteswritten.md similarity index 100% rename from api-docs/8785adc50c0e9feefad3703fe97218378940b0556afdef9c905f145430375f3c.md rename to fs/writestream_byteswritten.md diff --git a/api-docs/4f2ab61a00debed03d83e620fbc53772b36731cd285ee29b6bfe450b855d34fe.md b/fs/writestream_path.md similarity index 100% rename from api-docs/4f2ab61a00debed03d83e620fbc53772b36731cd285ee29b6bfe450b855d34fe.md rename to fs/writestream_path.md diff --git a/api-docs/657947b58e14b964b6bdb7cb9a7aee48014349928b0f04dd4af25c420e614a43.md b/fs/writestream_pending.md similarity index 100% rename from api-docs/657947b58e14b964b6bdb7cb9a7aee48014349928b0f04dd4af25c420e614a43.md rename to fs/writestream_pending.md diff --git a/api-docs/3de5eb4fdfb099b5d4ecaf6e8178a5f2b8a96c1bc23275d69c46d21952149a2a.md b/globals/class_buffer.md similarity index 100% rename from api-docs/3de5eb4fdfb099b5d4ecaf6e8178a5f2b8a96c1bc23275d69c46d21952149a2a.md rename to globals/class_buffer.md diff --git a/api-docs/ee6946b3ea2aff10881ae6ae536c24617b3a03e5f0c23e9c17644533d5302cb0.md b/globals/clearimmediate_immediateobject.md similarity index 100% rename from api-docs/ee6946b3ea2aff10881ae6ae536c24617b3a03e5f0c23e9c17644533d5302cb0.md rename to globals/clearimmediate_immediateobject.md diff --git a/api-docs/8835e04ccfaac00d2e959b6d9a9023afbe7eaf0d8b8c2ab94ba9e56f865a86f3.md b/globals/clearinterval_intervalobject.md similarity index 100% rename from api-docs/8835e04ccfaac00d2e959b6d9a9023afbe7eaf0d8b8c2ab94ba9e56f865a86f3.md rename to globals/clearinterval_intervalobject.md diff --git a/api-docs/e2a85edce5db169cc2b7cf97521616e565513cf5160e2a94dc7c025e15a19bb0.md b/globals/cleartimeout_timeoutobject.md similarity index 100% rename from api-docs/e2a85edce5db169cc2b7cf97521616e565513cf5160e2a94dc7c025e15a19bb0.md rename to globals/cleartimeout_timeoutobject.md diff --git a/api-docs/8d6b52ccc7ea6c53382dca0777bdeab12bc8fa897606d2d9fec935b547c6e5f5.md b/globals/console.md similarity index 100% rename from api-docs/8d6b52ccc7ea6c53382dca0777bdeab12bc8fa897606d2d9fec935b547c6e5f5.md rename to globals/console.md diff --git a/api-docs/c507ee04df5e514ff4972c811b034b893e2a11db651b0b3661b4ef7b15648263.md b/globals/dirname.md similarity index 100% rename from api-docs/c507ee04df5e514ff4972c811b034b893e2a11db651b0b3661b4ef7b15648263.md rename to globals/dirname.md diff --git a/api-docs/292843cc529cdee1df624a16f6685fb0972cd34e6711393ed0ca7c75345aad82.md b/globals/exports.md similarity index 100% rename from api-docs/292843cc529cdee1df624a16f6685fb0972cd34e6711393ed0ca7c75345aad82.md rename to globals/exports.md diff --git a/api-docs/7dcbbaae9fd367c1710cafd0ba93be6f279be63bb0b36e3fc528419146bc2505.md b/globals/filename.md similarity index 100% rename from api-docs/7dcbbaae9fd367c1710cafd0ba93be6f279be63bb0b36e3fc528419146bc2505.md rename to globals/filename.md diff --git a/api-docs/c454c4abb819b34076c4a43202b23c923e4ebaf4ad05e0bcb7e407df5d4b4b6d.md b/globals/global.md similarity index 100% rename from api-docs/c454c4abb819b34076c4a43202b23c923e4ebaf4ad05e0bcb7e407df5d4b4b6d.md rename to globals/global.md diff --git a/api-docs/8e338fc4c9eddfe4f21e8efb71a2370bd831824a9d83c692dae5be092e4e81c9.md b/globals/global_objects.md similarity index 100% rename from api-docs/8e338fc4c9eddfe4f21e8efb71a2370bd831824a9d83c692dae5be092e4e81c9.md rename to globals/global_objects.md diff --git a/api-docs/1105895455e196838d64afa2ea6e446355afea30ef7d78a1a85dfacec1665325.md b/globals/module.md similarity index 100% rename from api-docs/1105895455e196838d64afa2ea6e446355afea30ef7d78a1a85dfacec1665325.md rename to globals/module.md diff --git a/api-docs/5135b13d18ff1e3fb5fde27d788aa8e6b570fed99b62f54dc07c89a50d730aa8.md b/globals/process.md similarity index 100% rename from api-docs/5135b13d18ff1e3fb5fde27d788aa8e6b570fed99b62f54dc07c89a50d730aa8.md rename to globals/process.md diff --git a/api-docs/c5dc748e5d6dff4c64f8023354e7f650a68341676c9e90e78810212d5c1c806f.md b/globals/queuemicrotask_callback.md similarity index 100% rename from api-docs/c5dc748e5d6dff4c64f8023354e7f650a68341676c9e90e78810212d5c1c806f.md rename to globals/queuemicrotask_callback.md diff --git a/api-docs/3dbd813b689c3cf27d7aabe3b02050110758b1906c4a4def11dd1490da18ef8f.md b/globals/require.md similarity index 100% rename from api-docs/3dbd813b689c3cf27d7aabe3b02050110758b1906c4a4def11dd1490da18ef8f.md rename to globals/require.md diff --git a/api-docs/f2d681e42106412a88036800387bc955050c4dd317a82549f5ba9699b6746c65.md b/globals/setimmediate_callback_args.md similarity index 100% rename from api-docs/f2d681e42106412a88036800387bc955050c4dd317a82549f5ba9699b6746c65.md rename to globals/setimmediate_callback_args.md diff --git a/api-docs/de52da2485de51455325512ca375e582efedbde1c6247ffe9cac222acb4a90c3.md b/globals/setinterval_callback_delay_args.md similarity index 100% rename from api-docs/de52da2485de51455325512ca375e582efedbde1c6247ffe9cac222acb4a90c3.md rename to globals/setinterval_callback_delay_args.md diff --git a/api-docs/9aacbf1fe96bb24a0f46d4c2986727014f450dc7baa858121e034da7c31a0d9e.md b/globals/settimeout_callback_delay_args.md similarity index 100% rename from api-docs/9aacbf1fe96bb24a0f46d4c2986727014f450dc7baa858121e034da7c31a0d9e.md rename to globals/settimeout_callback_delay_args.md diff --git a/api-docs/1b318aa5878b18cf2ce6789ace778126ba6a1f5ef4121fcc9f5b5a5b4300e4e9.md b/globals/textdecoder.md similarity index 100% rename from api-docs/1b318aa5878b18cf2ce6789ace778126ba6a1f5ef4121fcc9f5b5a5b4300e4e9.md rename to globals/textdecoder.md diff --git a/api-docs/e564d4bbada5930ef06c87378f8de8acd5e30acd3bcfa0967f08423f3a8854ff.md b/globals/textencoder.md similarity index 100% rename from api-docs/e564d4bbada5930ef06c87378f8de8acd5e30acd3bcfa0967f08423f3a8854ff.md rename to globals/textencoder.md diff --git a/api-docs/1b28da49e5d2bb032bc32144ca546f3b5fc45f0bfbe097f71e01d8ccfc49c621.md b/globals/url.md similarity index 100% rename from api-docs/1b28da49e5d2bb032bc32144ca546f3b5fc45f0bfbe097f71e01d8ccfc49c621.md rename to globals/url.md diff --git a/api-docs/d5e5d23e551240c2e9f316b505d3ae4af3c9b0da42e095577fb19cdb2454d529.md b/globals/urlsearchparams.md similarity index 100% rename from api-docs/d5e5d23e551240c2e9f316b505d3ae4af3c9b0da42e095577fb19cdb2454d529.md rename to globals/urlsearchparams.md diff --git a/api-docs/7bacf20adde608d8d9760053f5aed694e0a30c7179783afc5d9eb0abdfc72ef4.md b/globals/webassembly.md similarity index 100% rename from api-docs/7bacf20adde608d8d9760053f5aed694e0a30c7179783afc5d9eb0abdfc72ef4.md rename to globals/webassembly.md diff --git a/api-docs/ce500c4c7ea1e728639ec1d4b9d92e9c4bd39b49cbed57a45a97fadf87b243dc.md b/http/agent_createconnection_options_callback.md similarity index 100% rename from api-docs/ce500c4c7ea1e728639ec1d4b9d92e9c4bd39b49cbed57a45a97fadf87b243dc.md rename to http/agent_createconnection_options_callback.md diff --git a/api-docs/8769c88f3059f209dafa1f4d1eb5d9362c2d425a14ee536fced8eb38b5553af5.md b/http/agent_destroy.md similarity index 100% rename from api-docs/8769c88f3059f209dafa1f4d1eb5d9362c2d425a14ee536fced8eb38b5553af5.md rename to http/agent_destroy.md diff --git a/api-docs/b04eeca13fe13238fab209f52278a6872737b6682e8c977012199b718e2941a5.md b/http/agent_freesockets.md similarity index 100% rename from api-docs/b04eeca13fe13238fab209f52278a6872737b6682e8c977012199b718e2941a5.md rename to http/agent_freesockets.md diff --git a/api-docs/7bfa2b0797a469d08d040afdf67a22b926bf2895fb2b58d65cf350a17fdab61d.md b/http/agent_getname_options.md similarity index 100% rename from api-docs/7bfa2b0797a469d08d040afdf67a22b926bf2895fb2b58d65cf350a17fdab61d.md rename to http/agent_getname_options.md diff --git a/api-docs/116648aad4a291d4412105130a3ec7dad3ad215816d41abfebcb007403a90f1b.md b/http/agent_keepsocketalive_socket.md similarity index 100% rename from api-docs/116648aad4a291d4412105130a3ec7dad3ad215816d41abfebcb007403a90f1b.md rename to http/agent_keepsocketalive_socket.md diff --git a/api-docs/2e56dac0f04ef37429aa099cb80d724ec825d3068e5c64ebfab22ea364a2f340.md b/http/agent_maxfreesockets.md similarity index 100% rename from api-docs/2e56dac0f04ef37429aa099cb80d724ec825d3068e5c64ebfab22ea364a2f340.md rename to http/agent_maxfreesockets.md diff --git a/api-docs/eadb3bde0f2414d0b0fc123bb9b574a238151a851c8d9089f3329b5be30d7504.md b/http/agent_maxsockets.md similarity index 100% rename from api-docs/eadb3bde0f2414d0b0fc123bb9b574a238151a851c8d9089f3329b5be30d7504.md rename to http/agent_maxsockets.md diff --git a/api-docs/c7a2714c62b4978fdb1bd069579a8c31673d02b56e27bcd3d9e3642a387233ff.md b/http/agent_requests.md similarity index 100% rename from api-docs/c7a2714c62b4978fdb1bd069579a8c31673d02b56e27bcd3d9e3642a387233ff.md rename to http/agent_requests.md diff --git a/api-docs/6495eb6681357514e80321974c90ce2457c73eb961796c8efd99153ba98edc24.md b/http/agent_reusesocket_socket_request.md similarity index 100% rename from api-docs/6495eb6681357514e80321974c90ce2457c73eb961796c8efd99153ba98edc24.md rename to http/agent_reusesocket_socket_request.md diff --git a/api-docs/7a1d7d93d624d9226eb2a3fc01fa9609be6faa7acddbcb57dc7fb8be0ddfcccc.md b/http/agent_sockets.md similarity index 100% rename from api-docs/7a1d7d93d624d9226eb2a3fc01fa9609be6faa7acddbcb57dc7fb8be0ddfcccc.md rename to http/agent_sockets.md diff --git a/api-docs/453010d63d3040376f2c189af365bfe8ee8c2c0797e6beaaa34decb01b6fb671.md b/http/class_http_agent.md similarity index 100% rename from api-docs/453010d63d3040376f2c189af365bfe8ee8c2c0797e6beaaa34decb01b6fb671.md rename to http/class_http_agent.md diff --git a/api-docs/ff2afeb1ba2c3a8bd6ac2f8a36f815c49e0930e429108179e21ca751578e6b04.md b/http/class_http_clientrequest.md similarity index 100% rename from api-docs/ff2afeb1ba2c3a8bd6ac2f8a36f815c49e0930e429108179e21ca751578e6b04.md rename to http/class_http_clientrequest.md diff --git a/api-docs/32260b8e95af9d81468bc514616b5e35d3fc99a2c964843ea438b34db7cf6246.md b/http/class_http_incomingmessage.md similarity index 100% rename from api-docs/32260b8e95af9d81468bc514616b5e35d3fc99a2c964843ea438b34db7cf6246.md rename to http/class_http_incomingmessage.md diff --git a/api-docs/e97cb7c211a2efe85d1c4cf78e385baa790f3e84b944aa8fa7335b93aa98f2f3.md b/http/class_http_server.md similarity index 100% rename from api-docs/e97cb7c211a2efe85d1c4cf78e385baa790f3e84b944aa8fa7335b93aa98f2f3.md rename to http/class_http_server.md diff --git a/api-docs/eb34066c055c76f1cee0b2b0a15ca6ef00fd3aa6e859bf13cd341e5cfc9e36c4.md b/http/class_http_serverresponse.md similarity index 100% rename from api-docs/eb34066c055c76f1cee0b2b0a15ca6ef00fd3aa6e859bf13cd341e5cfc9e36c4.md rename to http/class_http_serverresponse.md diff --git a/api-docs/1bb4f6b5fe82efdee700f69470fa486c4198f421ef96857c1b4256a88ab9d12f.md b/http/event_abort.md similarity index 100% rename from api-docs/1bb4f6b5fe82efdee700f69470fa486c4198f421ef96857c1b4256a88ab9d12f.md rename to http/event_abort.md diff --git a/api-docs/0a11c32ee19c094d26156e495b5be17d31635ec4786ce1b02493937bc7262f56.md b/http/event_aborted.md similarity index 100% rename from api-docs/0a11c32ee19c094d26156e495b5be17d31635ec4786ce1b02493937bc7262f56.md rename to http/event_aborted.md diff --git a/api-docs/08f52a52fbbd0f545733704800a5fce85279b84aa3a2c2b9dd6cae16ed828857.md b/http/event_checkcontinue.md similarity index 100% rename from api-docs/08f52a52fbbd0f545733704800a5fce85279b84aa3a2c2b9dd6cae16ed828857.md rename to http/event_checkcontinue.md diff --git a/api-docs/278e0c6bafd98a2b9449d875fe83a570ceaecb2dd547fbacfa4fa4936a52afdc.md b/http/event_checkexpectation.md similarity index 100% rename from api-docs/278e0c6bafd98a2b9449d875fe83a570ceaecb2dd547fbacfa4fa4936a52afdc.md rename to http/event_checkexpectation.md diff --git a/api-docs/675786ab2d9ac12d18af6ca2dab7017db93ba6815eb798575e7e667fb42fbcfc.md b/http/event_clienterror.md similarity index 100% rename from api-docs/675786ab2d9ac12d18af6ca2dab7017db93ba6815eb798575e7e667fb42fbcfc.md rename to http/event_clienterror.md diff --git a/api-docs/d286da78c794e3b027bb72f2334209ec19661bf3e869a0bdf1c9dfae08384ff3.md b/http/event_close.md similarity index 100% rename from api-docs/d286da78c794e3b027bb72f2334209ec19661bf3e869a0bdf1c9dfae08384ff3.md rename to http/event_close.md diff --git a/api-docs/6ae6ca539884c926332f5386d33e41968f61f4aefd529d115772f81401feea00.md b/http/event_close_1.md similarity index 100% rename from api-docs/6ae6ca539884c926332f5386d33e41968f61f4aefd529d115772f81401feea00.md rename to http/event_close_1.md diff --git a/api-docs/f92e71bd0964773124f2713281a4cf160c2357d82269bc155c588d56450e2491.md b/http/event_close_2.md similarity index 100% rename from api-docs/f92e71bd0964773124f2713281a4cf160c2357d82269bc155c588d56450e2491.md rename to http/event_close_2.md diff --git a/api-docs/351eb648dac62fd73f3866e791948e3cff09341d08149a7e5ec56d15c082f932.md b/http/event_connect.md similarity index 100% rename from api-docs/351eb648dac62fd73f3866e791948e3cff09341d08149a7e5ec56d15c082f932.md rename to http/event_connect.md diff --git a/api-docs/06cba8a36846306fe393c5edde54cfeed40b9996b3379272432891e973fba2e0.md b/http/event_connect_1.md similarity index 100% rename from api-docs/06cba8a36846306fe393c5edde54cfeed40b9996b3379272432891e973fba2e0.md rename to http/event_connect_1.md diff --git a/api-docs/1685866bac152c3868115334dcb69566a7501e98f041a4e5272e45bcac5ee421.md b/http/event_connection.md similarity index 100% rename from api-docs/1685866bac152c3868115334dcb69566a7501e98f041a4e5272e45bcac5ee421.md rename to http/event_connection.md diff --git a/api-docs/0f3c59df854bcd73f44a5665453f3dbc15b6ff3c83d2784f7752f5f6baa951a0.md b/http/event_continue.md similarity index 100% rename from api-docs/0f3c59df854bcd73f44a5665453f3dbc15b6ff3c83d2784f7752f5f6baa951a0.md rename to http/event_continue.md diff --git a/api-docs/03893567418a0d7bf9ea5f8543777288afe1989fba46c2e0496b4c77a407eece.md b/http/event_finish.md similarity index 100% rename from api-docs/03893567418a0d7bf9ea5f8543777288afe1989fba46c2e0496b4c77a407eece.md rename to http/event_finish.md diff --git a/api-docs/d09d498b6cd681aa68151be12146c5e5e5aa618240c4131c25692b0f36ff2836.md b/http/event_information.md similarity index 100% rename from api-docs/d09d498b6cd681aa68151be12146c5e5e5aa618240c4131c25692b0f36ff2836.md rename to http/event_information.md diff --git a/api-docs/4b5df391cb28361bd4496bba599bdb44b1f5ccc0cfcf9e7e4617d8df96b3c355.md b/http/event_request.md similarity index 100% rename from api-docs/4b5df391cb28361bd4496bba599bdb44b1f5ccc0cfcf9e7e4617d8df96b3c355.md rename to http/event_request.md diff --git a/api-docs/d21773086917fbd6ed441d08971bffba2ce4ec77ee66ad6f1ccacccc6a1530c2.md b/http/event_response.md similarity index 100% rename from api-docs/d21773086917fbd6ed441d08971bffba2ce4ec77ee66ad6f1ccacccc6a1530c2.md rename to http/event_response.md diff --git a/api-docs/d36530a1f8b7a31ce76ea6c4ab830d70fd5bb3223788e16b2b99668f8e029b5a.md b/http/event_socket.md similarity index 100% rename from api-docs/d36530a1f8b7a31ce76ea6c4ab830d70fd5bb3223788e16b2b99668f8e029b5a.md rename to http/event_socket.md diff --git a/api-docs/ee91a1b1f5118fc8de3de75f781105a56d96fd5c51b342d7e9aa1cbd711b4383.md b/http/event_timeout.md similarity index 100% rename from api-docs/ee91a1b1f5118fc8de3de75f781105a56d96fd5c51b342d7e9aa1cbd711b4383.md rename to http/event_timeout.md diff --git a/api-docs/c1df2e6b106a136a4c552c398a34fd6095da8c9705463c6f44cc95f236e7aff6.md b/http/event_upgrade.md similarity index 100% rename from api-docs/c1df2e6b106a136a4c552c398a34fd6095da8c9705463c6f44cc95f236e7aff6.md rename to http/event_upgrade.md diff --git a/api-docs/2e75e51033d3b4296cbf60de76803b056fffa88c10aaf81f84e970f54889a84f.md b/http/event_upgrade_1.md similarity index 100% rename from api-docs/2e75e51033d3b4296cbf60de76803b056fffa88c10aaf81f84e970f54889a84f.md rename to http/event_upgrade_1.md diff --git a/api-docs/6d2aadbc30e9f52b12aeafae1e4c28b0c8a432d8be93ebd95ba98d1285bd89ab.md b/http/http.md similarity index 100% rename from api-docs/6d2aadbc30e9f52b12aeafae1e4c28b0c8a432d8be93ebd95ba98d1285bd89ab.md rename to http/http.md diff --git a/api-docs/9d3a1e3d4f032d7d18ab446f94746a2152d473c03a7f4ca7cbc45b82b313ed62.md b/http/http_createserver_options_requestlistener.md similarity index 100% rename from api-docs/9d3a1e3d4f032d7d18ab446f94746a2152d473c03a7f4ca7cbc45b82b313ed62.md rename to http/http_createserver_options_requestlistener.md diff --git a/api-docs/e10441d39a4b460ac9306038a4fc0e7638f40d17313978f8bf4cb2d4c1919390.md b/http/http_get_options_callback.md similarity index 100% rename from api-docs/e10441d39a4b460ac9306038a4fc0e7638f40d17313978f8bf4cb2d4c1919390.md rename to http/http_get_options_callback.md diff --git a/api-docs/179988cba8e00026a684528eb2ddef6cb8462e28c6c3f2f9c31b29c714ee3b82.md b/http/http_get_url_options_callback.md similarity index 100% rename from api-docs/179988cba8e00026a684528eb2ddef6cb8462e28c6c3f2f9c31b29c714ee3b82.md rename to http/http_get_url_options_callback.md diff --git a/api-docs/c2e737782fb2d91c36b96f5a0a1e8d7c4c2ddafac1fb2da00f4f02b1023e0815.md b/http/http_globalagent.md similarity index 100% rename from api-docs/c2e737782fb2d91c36b96f5a0a1e8d7c4c2ddafac1fb2da00f4f02b1023e0815.md rename to http/http_globalagent.md diff --git a/api-docs/8e49e14d41243ec1c454664aa78db2f9b8d4ac27d698ec69c9d72bf518b24ab5.md b/http/http_maxheadersize.md similarity index 100% rename from api-docs/8e49e14d41243ec1c454664aa78db2f9b8d4ac27d698ec69c9d72bf518b24ab5.md rename to http/http_maxheadersize.md diff --git a/api-docs/236ee0e91ecc6caf53c08b5eb039bc989a744970b177cb7cb83c04dd5a15026e.md b/http/http_methods.md similarity index 100% rename from api-docs/236ee0e91ecc6caf53c08b5eb039bc989a744970b177cb7cb83c04dd5a15026e.md rename to http/http_methods.md diff --git a/api-docs/eaf292c2440b3e8a44bcb40e6e214057b63d260a6f8f865bedb1f214bcd2f98c.md b/http/http_request_options_callback.md similarity index 100% rename from api-docs/eaf292c2440b3e8a44bcb40e6e214057b63d260a6f8f865bedb1f214bcd2f98c.md rename to http/http_request_options_callback.md diff --git a/api-docs/f0d56ab76410c777ce8e49eb77e25f1e55035905ab29f5413b6638e596e26681.md b/http/http_request_url_options_callback.md similarity index 100% rename from api-docs/f0d56ab76410c777ce8e49eb77e25f1e55035905ab29f5413b6638e596e26681.md rename to http/http_request_url_options_callback.md diff --git a/api-docs/9ca9732be7bfbb60ec436a1a737d04138120ca62b266a614106db7658e288244.md b/http/http_status_codes.md similarity index 100% rename from api-docs/9ca9732be7bfbb60ec436a1a737d04138120ca62b266a614106db7658e288244.md rename to http/http_status_codes.md diff --git a/api-docs/1ec1dcabb2bd68d07247ec29b05221bee9e9842cf47823d7d9ce3d2bffdca888.md b/http/message_aborted.md similarity index 100% rename from api-docs/1ec1dcabb2bd68d07247ec29b05221bee9e9842cf47823d7d9ce3d2bffdca888.md rename to http/message_aborted.md diff --git a/api-docs/e372aa54acdaac6f6b9dcf4e9775f1432d9f376b4fa512adb7079743707631aa.md b/http/message_complete.md similarity index 100% rename from api-docs/e372aa54acdaac6f6b9dcf4e9775f1432d9f376b4fa512adb7079743707631aa.md rename to http/message_complete.md diff --git a/api-docs/5ab1844cc5c000e89b76457a63d265fcaf6f27d33237f2a1b6eb6260251995a5.md b/http/message_destroy_error.md similarity index 100% rename from api-docs/5ab1844cc5c000e89b76457a63d265fcaf6f27d33237f2a1b6eb6260251995a5.md rename to http/message_destroy_error.md diff --git a/api-docs/995142f5bb788e26d3a5b09907a0af56f01aa1bb15928a21eeb507db777d8249.md b/http/message_headers.md similarity index 100% rename from api-docs/995142f5bb788e26d3a5b09907a0af56f01aa1bb15928a21eeb507db777d8249.md rename to http/message_headers.md diff --git a/api-docs/2a51b0b1ba4f749763c2e2d6965ab38abc5a4109bbc5034e2d051b7827dfcc7d.md b/http/message_httpversion.md similarity index 100% rename from api-docs/2a51b0b1ba4f749763c2e2d6965ab38abc5a4109bbc5034e2d051b7827dfcc7d.md rename to http/message_httpversion.md diff --git a/api-docs/b640b0a733582baadc85024092cf4cdd67bbe1a406a23579adbf5d92a1ebbc10.md b/http/message_method.md similarity index 100% rename from api-docs/b640b0a733582baadc85024092cf4cdd67bbe1a406a23579adbf5d92a1ebbc10.md rename to http/message_method.md diff --git a/api-docs/98be2b31bdd0c7faab81a76aee63783cad9ed7c40bf0b54068447a03c6563911.md b/http/message_rawheaders.md similarity index 100% rename from api-docs/98be2b31bdd0c7faab81a76aee63783cad9ed7c40bf0b54068447a03c6563911.md rename to http/message_rawheaders.md diff --git a/api-docs/18e19a4347482832484e3250ba1f11d8c6ec189fe2dabd23a34c22e80fbbbf03.md b/http/message_rawtrailers.md similarity index 100% rename from api-docs/18e19a4347482832484e3250ba1f11d8c6ec189fe2dabd23a34c22e80fbbbf03.md rename to http/message_rawtrailers.md diff --git a/api-docs/d29736955c2aa9b833403b86e299aab3ad1713bbcc5d3b7eed1b6524bd4097f1.md b/http/message_settimeout_msecs_callback.md similarity index 100% rename from api-docs/d29736955c2aa9b833403b86e299aab3ad1713bbcc5d3b7eed1b6524bd4097f1.md rename to http/message_settimeout_msecs_callback.md diff --git a/api-docs/101358c48f5c3c762b7ab5255bf87b3a667f3b8d21c3576624d50c8c740d5033.md b/http/message_socket.md similarity index 100% rename from api-docs/101358c48f5c3c762b7ab5255bf87b3a667f3b8d21c3576624d50c8c740d5033.md rename to http/message_socket.md diff --git a/api-docs/48051ffac2c6393810f801b55dacb5ceac12554bcbad3b9fb49bce79958e4a47.md b/http/message_statuscode.md similarity index 100% rename from api-docs/48051ffac2c6393810f801b55dacb5ceac12554bcbad3b9fb49bce79958e4a47.md rename to http/message_statuscode.md diff --git a/api-docs/d1a07bbd146734bde90cb08ec01f4d288b9b390974a346a1ee12641decb2461a.md b/http/message_statusmessage.md similarity index 100% rename from api-docs/d1a07bbd146734bde90cb08ec01f4d288b9b390974a346a1ee12641decb2461a.md rename to http/message_statusmessage.md diff --git a/api-docs/a957f55dd161861171fc6e1cf7b6e7f7b7a1c732389ceb163e7319c63df20713.md b/http/message_trailers.md similarity index 100% rename from api-docs/a957f55dd161861171fc6e1cf7b6e7f7b7a1c732389ceb163e7319c63df20713.md rename to http/message_trailers.md diff --git a/api-docs/e3db24bb19b48ed83bc1688318f95924e713637d7d9806311c5d04a6d1e1c543.md b/http/message_url.md similarity index 100% rename from api-docs/e3db24bb19b48ed83bc1688318f95924e713637d7d9806311c5d04a6d1e1c543.md rename to http/message_url.md diff --git a/api-docs/c20e60ac142d8dbe01f71979fe7cad89b3f05ce5b6e01e952cb5eb9c436100e0.md b/http/new_agent_options.md similarity index 100% rename from api-docs/c20e60ac142d8dbe01f71979fe7cad89b3f05ce5b6e01e952cb5eb9c436100e0.md rename to http/new_agent_options.md diff --git a/api-docs/e2c2cafdce7214936b7056c14fd359ab0e9692dfca33bb17ccd9f6655239550f.md b/http/request_abort.md similarity index 100% rename from api-docs/e2c2cafdce7214936b7056c14fd359ab0e9692dfca33bb17ccd9f6655239550f.md rename to http/request_abort.md diff --git a/api-docs/45decd7616782bfdf8b3ba41513c9d8541b42bc007a3f145054f435cbfd51162.md b/http/request_aborted.md similarity index 100% rename from api-docs/45decd7616782bfdf8b3ba41513c9d8541b42bc007a3f145054f435cbfd51162.md rename to http/request_aborted.md diff --git a/api-docs/77fe86860288e89660c446e7b7b4d014d060dfaa8bc64db726c8c784ad2be805.md b/http/request_connection.md similarity index 100% rename from api-docs/77fe86860288e89660c446e7b7b4d014d060dfaa8bc64db726c8c784ad2be805.md rename to http/request_connection.md diff --git a/api-docs/0fb8a18ec5366e6aede5b5426ad50269896e9376c7327efea5efe16f4bfde6ed.md b/http/request_end_data_encoding_callback.md similarity index 100% rename from api-docs/0fb8a18ec5366e6aede5b5426ad50269896e9376c7327efea5efe16f4bfde6ed.md rename to http/request_end_data_encoding_callback.md diff --git a/api-docs/10fe5db160bc530f59764b33c24e56e23c1d122677607e2ebc02dabd45f98a82.md b/http/request_finished.md similarity index 100% rename from api-docs/10fe5db160bc530f59764b33c24e56e23c1d122677607e2ebc02dabd45f98a82.md rename to http/request_finished.md diff --git a/api-docs/53f26d15ec71e8b73a37bbb6d455e38ac55cb3ce882b352b09e172f73971f476.md b/http/request_flushheaders.md similarity index 100% rename from api-docs/53f26d15ec71e8b73a37bbb6d455e38ac55cb3ce882b352b09e172f73971f476.md rename to http/request_flushheaders.md diff --git a/api-docs/d974591079e84c3375421bc0b7bb12b0ddbfa9f4d69ad7c232c768920384dbbd.md b/http/request_getheader_name.md similarity index 100% rename from api-docs/d974591079e84c3375421bc0b7bb12b0ddbfa9f4d69ad7c232c768920384dbbd.md rename to http/request_getheader_name.md diff --git a/api-docs/441246d7e53e7ae4881a2596423398b14672228950d88d67d1180565b65d3b66.md b/http/request_maxheaderscount.md similarity index 100% rename from api-docs/441246d7e53e7ae4881a2596423398b14672228950d88d67d1180565b65d3b66.md rename to http/request_maxheaderscount.md diff --git a/api-docs/4a3c5bf8be3a0073b007381b1b71ba071c6e1dfd06ec165863bce382640531f6.md b/http/request_removeheader_name.md similarity index 100% rename from api-docs/4a3c5bf8be3a0073b007381b1b71ba071c6e1dfd06ec165863bce382640531f6.md rename to http/request_removeheader_name.md diff --git a/api-docs/59ec62e14d69e7f1f2405426e0f5728145b195006328e82644badc5d71c43ef1.md b/http/request_setheader_name_value.md similarity index 100% rename from api-docs/59ec62e14d69e7f1f2405426e0f5728145b195006328e82644badc5d71c43ef1.md rename to http/request_setheader_name_value.md diff --git a/api-docs/15423169bee6526b85f917d642011edb5b7186b8250513a140115b0e0341ea1c.md b/http/request_setnodelay_nodelay.md similarity index 100% rename from api-docs/15423169bee6526b85f917d642011edb5b7186b8250513a140115b0e0341ea1c.md rename to http/request_setnodelay_nodelay.md diff --git a/api-docs/56c7fd719d14ec02f130e605e98626fad70d0ac4455bb08dbec846f10f018598.md b/http/request_setsocketkeepalive_enable_initialdelay.md similarity index 100% rename from api-docs/56c7fd719d14ec02f130e605e98626fad70d0ac4455bb08dbec846f10f018598.md rename to http/request_setsocketkeepalive_enable_initialdelay.md diff --git a/api-docs/84573ba00d0a02f0b48d0b9b89890f23951e1667a6390003df3fd11a51d01e7b.md b/http/request_settimeout_timeout_callback.md similarity index 100% rename from api-docs/84573ba00d0a02f0b48d0b9b89890f23951e1667a6390003df3fd11a51d01e7b.md rename to http/request_settimeout_timeout_callback.md diff --git a/api-docs/8e3f7168c33c99a77ddd6b6fe7af4b74e3772efb91a22fb6f6c1679bbc622721.md b/http/request_socket.md similarity index 100% rename from api-docs/8e3f7168c33c99a77ddd6b6fe7af4b74e3772efb91a22fb6f6c1679bbc622721.md rename to http/request_socket.md diff --git a/api-docs/9ad4ed215a2d7ac5b1e96d24db60c89f142419439e90815a946452a315eebe6a.md b/http/request_write_chunk_encoding_callback.md similarity index 100% rename from api-docs/9ad4ed215a2d7ac5b1e96d24db60c89f142419439e90815a946452a315eebe6a.md rename to http/request_write_chunk_encoding_callback.md diff --git a/api-docs/3d25a8fb8ae2e6e031a6b030e23b6c67be4c26de91e205fa8526e748597e5851.md b/http/response_addtrailers_headers.md similarity index 100% rename from api-docs/3d25a8fb8ae2e6e031a6b030e23b6c67be4c26de91e205fa8526e748597e5851.md rename to http/response_addtrailers_headers.md diff --git a/api-docs/87e629982b3dc31a5d62524eb0b4a94bdc7b1f684a58b7b523f7e65b50180e37.md b/http/response_connection.md similarity index 100% rename from api-docs/87e629982b3dc31a5d62524eb0b4a94bdc7b1f684a58b7b523f7e65b50180e37.md rename to http/response_connection.md diff --git a/api-docs/d74ffc41f489c76a0dab18402940f61cd75e9fdde7422e7d41f7a9af2eb2727f.md b/http/response_end_data_encoding_callback.md similarity index 100% rename from api-docs/d74ffc41f489c76a0dab18402940f61cd75e9fdde7422e7d41f7a9af2eb2727f.md rename to http/response_end_data_encoding_callback.md diff --git a/api-docs/f7ec173391de3d1560920ef2c06769b42f8164e26c85bca0a8ea9fcca2b80640.md b/http/response_finished.md similarity index 100% rename from api-docs/f7ec173391de3d1560920ef2c06769b42f8164e26c85bca0a8ea9fcca2b80640.md rename to http/response_finished.md diff --git a/api-docs/895775b24f32f6ad2cb7e694e86b85c54e80194d97dc3b2bb326e0c355a5a478.md b/http/response_getheader_name.md similarity index 100% rename from api-docs/895775b24f32f6ad2cb7e694e86b85c54e80194d97dc3b2bb326e0c355a5a478.md rename to http/response_getheader_name.md diff --git a/api-docs/9af385517a076f57235f3cada0263b00fb3e5881b32ec9beedca24530ccb4218.md b/http/response_getheadernames.md similarity index 100% rename from api-docs/9af385517a076f57235f3cada0263b00fb3e5881b32ec9beedca24530ccb4218.md rename to http/response_getheadernames.md diff --git a/api-docs/771d162854da79767509405fe7cf381343e19158ec2d11db7dfedc0ba5f54d10.md b/http/response_getheaders.md similarity index 100% rename from api-docs/771d162854da79767509405fe7cf381343e19158ec2d11db7dfedc0ba5f54d10.md rename to http/response_getheaders.md diff --git a/api-docs/789ccb45f801b491481f3751f418cdf38abd1bbc818ec8b9704bac046e1b99f9.md b/http/response_hasheader_name.md similarity index 100% rename from api-docs/789ccb45f801b491481f3751f418cdf38abd1bbc818ec8b9704bac046e1b99f9.md rename to http/response_hasheader_name.md diff --git a/api-docs/71046a691834660c9512754fdafd747766edbc5f4fe6c40abcda666db397cdff.md b/http/response_headerssent.md similarity index 100% rename from api-docs/71046a691834660c9512754fdafd747766edbc5f4fe6c40abcda666db397cdff.md rename to http/response_headerssent.md diff --git a/api-docs/39dce3a2a3ce849a34bf3098cfa7889d983bbce3eb788b823cd7686115493237.md b/http/response_removeheader_name.md similarity index 100% rename from api-docs/39dce3a2a3ce849a34bf3098cfa7889d983bbce3eb788b823cd7686115493237.md rename to http/response_removeheader_name.md diff --git a/api-docs/95b037f2a05090b1073d010edd9fda515dcb54b2bbb05432b2a57df457cf210b.md b/http/response_senddate.md similarity index 100% rename from api-docs/95b037f2a05090b1073d010edd9fda515dcb54b2bbb05432b2a57df457cf210b.md rename to http/response_senddate.md diff --git a/api-docs/07cc20f0cad3c39df06c166f3e473ee6280b4a4e955cee997f1127fc59891252.md b/http/response_setheader_name_value.md similarity index 100% rename from api-docs/07cc20f0cad3c39df06c166f3e473ee6280b4a4e955cee997f1127fc59891252.md rename to http/response_setheader_name_value.md diff --git a/api-docs/88da343cc7d5133e40229b048b4df22117e6cb211bbd6228db52f2b1ca04fd8e.md b/http/response_settimeout_msecs_callback.md similarity index 100% rename from api-docs/88da343cc7d5133e40229b048b4df22117e6cb211bbd6228db52f2b1ca04fd8e.md rename to http/response_settimeout_msecs_callback.md diff --git a/api-docs/acc03edd0c0dbed92603ad6d9c09e02d1edc24fd1a72f369d4488bc4893ba5f3.md b/http/response_socket.md similarity index 100% rename from api-docs/acc03edd0c0dbed92603ad6d9c09e02d1edc24fd1a72f369d4488bc4893ba5f3.md rename to http/response_socket.md diff --git a/api-docs/7b589e54030c7eaa1a9a08704c69a96cea90763248f38e46f2635ef6ad771bc3.md b/http/response_statuscode.md similarity index 100% rename from api-docs/7b589e54030c7eaa1a9a08704c69a96cea90763248f38e46f2635ef6ad771bc3.md rename to http/response_statuscode.md diff --git a/api-docs/eddc92d3c7c3b84e11fb151c8cdd280ad970879bc684f9ef5ec17e7a0f49ece0.md b/http/response_statusmessage.md similarity index 100% rename from api-docs/eddc92d3c7c3b84e11fb151c8cdd280ad970879bc684f9ef5ec17e7a0f49ece0.md rename to http/response_statusmessage.md diff --git a/api-docs/a6a17b792ec5efcb71aadf2dd86ab4712611c71d90a9fd6e4fa6524a99409c4a.md b/http/response_write_chunk_encoding_callback.md similarity index 100% rename from api-docs/a6a17b792ec5efcb71aadf2dd86ab4712611c71d90a9fd6e4fa6524a99409c4a.md rename to http/response_write_chunk_encoding_callback.md diff --git a/api-docs/f207af64a613d2b5cde5911be776938cde2cc861af63ab2b1e3c9e4fc5c0c48f.md b/http/response_writecontinue.md similarity index 100% rename from api-docs/f207af64a613d2b5cde5911be776938cde2cc861af63ab2b1e3c9e4fc5c0c48f.md rename to http/response_writecontinue.md diff --git a/api-docs/08a2e652b10f07489d045ae974b1835cd73e38f7f8f99244912ed2dbe12f1d16.md b/http/response_writehead_statuscode_statusmessage_headers.md similarity index 100% rename from api-docs/08a2e652b10f07489d045ae974b1835cd73e38f7f8f99244912ed2dbe12f1d16.md rename to http/response_writehead_statuscode_statusmessage_headers.md diff --git a/api-docs/c765a9822eb45a2a0b2e73f2f1c104f484ff5ed4853d26c8b03798b8fead0174.md b/http/response_writeprocessing.md similarity index 100% rename from api-docs/c765a9822eb45a2a0b2e73f2f1c104f484ff5ed4853d26c8b03798b8fead0174.md rename to http/response_writeprocessing.md diff --git a/api-docs/95bd13c79fe95df71b9793d5c4706b5eac05ba444004fd8a52fa77f9b3c1db3c.md b/http/server_close_callback.md similarity index 100% rename from api-docs/95bd13c79fe95df71b9793d5c4706b5eac05ba444004fd8a52fa77f9b3c1db3c.md rename to http/server_close_callback.md diff --git a/api-docs/5cf583ffb4851a3f30d24f5ebc1105e1bee7a728e72178c8ecf2c875d8b0f572.md b/http/server_headerstimeout.md similarity index 100% rename from api-docs/5cf583ffb4851a3f30d24f5ebc1105e1bee7a728e72178c8ecf2c875d8b0f572.md rename to http/server_headerstimeout.md diff --git a/api-docs/547fa94ef5e4b4f3736d371b61d288fba7ab7a2a6447cb139967ba87ec97ebf1.md b/http/server_keepalivetimeout.md similarity index 100% rename from api-docs/547fa94ef5e4b4f3736d371b61d288fba7ab7a2a6447cb139967ba87ec97ebf1.md rename to http/server_keepalivetimeout.md diff --git a/api-docs/3b93e0da853980a6c44858e284aaf93dac8f6c5d9b97872f684c031f5ec85b77.md b/http/server_listen.md similarity index 100% rename from api-docs/3b93e0da853980a6c44858e284aaf93dac8f6c5d9b97872f684c031f5ec85b77.md rename to http/server_listen.md diff --git a/api-docs/25f2d4f08a4245e818a455c4538d25895a7a09eddf79e8ef82fd67751929c90a.md b/http/server_listening.md similarity index 100% rename from api-docs/25f2d4f08a4245e818a455c4538d25895a7a09eddf79e8ef82fd67751929c90a.md rename to http/server_listening.md diff --git a/api-docs/b02e592d54b9ed65ddb7b5f5465088c41e31d1a67aa422449fefe63a1a9d5f83.md b/http/server_maxheaderscount.md similarity index 100% rename from api-docs/b02e592d54b9ed65ddb7b5f5465088c41e31d1a67aa422449fefe63a1a9d5f83.md rename to http/server_maxheaderscount.md diff --git a/api-docs/cae0b651a5d7ca43e86d272670406b9a62f9f4087e7348210e9102af1727579e.md b/http/server_settimeout_msecs_callback.md similarity index 100% rename from api-docs/cae0b651a5d7ca43e86d272670406b9a62f9f4087e7348210e9102af1727579e.md rename to http/server_settimeout_msecs_callback.md diff --git a/api-docs/2a9afb1f82a57c99272be38856dc51306f2d9b441ee69edb7c8fa68df1a3ff6e.md b/http/server_timeout.md similarity index 100% rename from api-docs/2a9afb1f82a57c99272be38856dc51306f2d9b441ee69edb7c8fa68df1a3ff6e.md rename to http/server_timeout.md diff --git a/http2/alpn_negotiation.md b/http2/alpn_negotiation.md new file mode 100644 index 00000000..356bb824 --- /dev/null +++ b/http2/alpn_negotiation.md @@ -0,0 +1,36 @@ + +ALPN negotiation allows supporting both [HTTPS][] and HTTP/2 over +the same socket. The `req` and `res` objects can be either HTTP/1 or +HTTP/2, and an application **must** restrict itself to the public API of +[HTTP/1][], and detect if it is possible to use the more advanced +features of HTTP/2. + +The following example creates a server that supports both protocols: + +```js +const { createSecureServer } = require('http2'); +const { readFileSync } = require('fs'); + +const cert = readFileSync('./cert.pem'); +const key = readFileSync('./key.pem'); + +const server = createSecureServer( + { cert, key, allowHTTP1: true }, + onRequest +).listen(4443); + +function onRequest(req, res) { + // detects if it is a HTTPS request or HTTP/2 + const { socket: { alpnProtocol } } = req.httpVersion === '2.0' ? + req.stream.session : req; + res.writeHead(200, { 'content-type': 'application/json' }); + res.end(JSON.stringify({ + alpnProtocol, + httpVersion: req.httpVersion + })); +} +``` + +The `'request'` event works identically on both [HTTPS][] and +HTTP/2. + diff --git a/http2/class_clienthttp2session.md b/http2/class_clienthttp2session.md new file mode 100644 index 00000000..538121c0 --- /dev/null +++ b/http2/class_clienthttp2session.md @@ -0,0 +1,4 @@ + + diff --git a/http2/class_clienthttp2stream.md b/http2/class_clienthttp2stream.md new file mode 100644 index 00000000..59bd63e1 --- /dev/null +++ b/http2/class_clienthttp2stream.md @@ -0,0 +1,11 @@ + + +* Extends {Http2Stream} + +The `ClientHttp2Stream` class is an extension of `Http2Stream` that is +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. + diff --git a/http2/class_http2_http2serverrequest.md b/http2/class_http2_http2serverrequest.md new file mode 100644 index 00000000..a744c571 --- /dev/null +++ b/http2/class_http2_http2serverrequest.md @@ -0,0 +1,12 @@ + + +A `Http2ServerRequest` object is created by [`http2.Server`][] or +[`http2.SecureServer`][] and passed as the first argument to the +[`'request'`][] event. It may be used to access a request status, headers, and +data. + +It implements the [Readable Stream][] interface, as well as the +following additional events, methods, and properties. + diff --git a/http2/class_http2_http2serverresponse.md b/http2/class_http2_http2serverresponse.md new file mode 100644 index 00000000..4fd07320 --- /dev/null +++ b/http2/class_http2_http2serverresponse.md @@ -0,0 +1,10 @@ + + +This object is created internally by an HTTP server — not by the user. It is +passed as the second parameter to the [`'request'`][] event. + +The response inherits from [Stream][], and additionally implements the +following: + diff --git a/http2/class_http2secureserver.md b/http2/class_http2secureserver.md new file mode 100644 index 00000000..7501fba0 --- /dev/null +++ b/http2/class_http2secureserver.md @@ -0,0 +1,10 @@ + + +* Extends: {tls.Server} + +Instances of `Http2SecureServer` are created using the +`http2.createSecureServer()` function. The `Http2SecureServer` class is not +exported directly by the `http2` module. + diff --git a/http2/class_http2server.md b/http2/class_http2server.md new file mode 100644 index 00000000..5a260236 --- /dev/null +++ b/http2/class_http2server.md @@ -0,0 +1,10 @@ + + +* Extends: {net.Server} + +Instances of `Http2Server` are created using the `http2.createServer()` +function. The `Http2Server` class is not exported directly by the `http2` +module. + diff --git a/http2/class_http2session.md b/http2/class_http2session.md new file mode 100644 index 00000000..d8116475 --- /dev/null +++ b/http2/class_http2session.md @@ -0,0 +1,23 @@ + + +* Extends: {EventEmitter} + +Instances of the `http2.Http2Session` class represent an active communications +session between an HTTP/2 client and server. Instances of this class are *not* +intended to be constructed directly by user code. + +Each `Http2Session` instance will exhibit slightly different behaviors +depending on whether it is operating as a server or a client. The +`http2session.type` property can be used to determine the mode in which an +`Http2Session` is operating. On the server side, user code should rarely +have occasion to work with the `Http2Session` object directly, with most +actions typically taken through interactions with either the `Http2Server` or +`Http2Stream` objects. + +User code will not create `Http2Session` instances directly. Server-side +`Http2Session` instances are created by the `Http2Server` instance when a +new HTTP/2 connection is received. Client-side `Http2Session` instances are +created using the `http2.connect()` method. + diff --git a/http2/class_http2stream.md b/http2/class_http2stream.md new file mode 100644 index 00000000..6ae1b819 --- /dev/null +++ b/http2/class_http2stream.md @@ -0,0 +1,27 @@ + + +* Extends: {stream.Duplex} + +Each instance of the `Http2Stream` class represents a bidirectional HTTP/2 +communications stream over an `Http2Session` instance. Any single `Http2Session` +may have up to 231-1 `Http2Stream` instances over its lifetime. + +User code will not construct `Http2Stream` instances directly. Rather, these +are created, managed, and provided to user code through the `Http2Session` +instance. On the server, `Http2Stream` instances are created either in response +to an incoming HTTP request (and handed off to user code via the `'stream'` +event), or in response to a call to the `http2stream.pushStream()` method. +On the client, `Http2Stream` instances are created and returned when either the +`http2session.request()` method is called, or in response to an incoming +`'push'` event. + +The `Http2Stream` class is a base for the [`ServerHttp2Stream`][] and +[`ClientHttp2Stream`][] classes, each of which is used specifically by either +the Server or Client side, respectively. + +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. + diff --git a/http2/class_serverhttp2session.md b/http2/class_serverhttp2session.md new file mode 100644 index 00000000..538121c0 --- /dev/null +++ b/http2/class_serverhttp2session.md @@ -0,0 +1,4 @@ + + diff --git a/http2/class_serverhttp2stream.md b/http2/class_serverhttp2stream.md new file mode 100644 index 00000000..2e4b75af --- /dev/null +++ b/http2/class_serverhttp2stream.md @@ -0,0 +1,11 @@ + + +* Extends: {Http2Stream} + +The `ServerHttp2Stream` class is an extension of [`Http2Stream`][] that is +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. + diff --git a/http2/client_side_example.md b/http2/client_side_example.md new file mode 100644 index 00000000..e23279dc --- /dev/null +++ b/http2/client_side_example.md @@ -0,0 +1,29 @@ + +The following illustrates an HTTP/2 client: + +```js +const http2 = require('http2'); +const fs = require('fs'); +const client = http2.connect('https://localhost:8443', { + ca: fs.readFileSync('localhost-cert.pem') +}); +client.on('error', (err) => console.error(err)); + +const req = client.request({ ':path': '/' }); + +req.on('response', (headers, flags) => { + for (const name in headers) { + console.log(`${name}: ${headers[name]}`); + } +}); + +req.setEncoding('utf8'); +let data = ''; +req.on('data', (chunk) => { data += chunk; }); +req.on('end', () => { + console.log(`\n${data}`); + client.close(); +}); +req.end(); +``` + diff --git a/http2/clienthttp2session_request_headers_options.md b/http2/clienthttp2session_request_headers_options.md new file mode 100644 index 00000000..4d8eb954 --- /dev/null +++ b/http2/clienthttp2session_request_headers_options.md @@ -0,0 +1,62 @@ + + +* `headers` {HTTP/2 Headers Object} +* `options` {Object} + * `endStream` {boolean} `true` if the `Http2Stream` *writable* side should + be closed initially, such as when sending a `GET` request that should not + expect a payload body. + * `exclusive` {boolean} When `true` and `parent` identifies a parent Stream, + the created stream is made the sole direct dependency of the parent, with + all other existing dependents made a dependent of the newly created stream. + **Default:** `false`. + * `parent` {number} Specifies the numeric identifier of a stream the newly + created stream is dependent on. + * `weight` {number} Specifies the relative dependency of a stream in relation + to other streams with the same `parent`. The value is a number between `1` + and `256` (inclusive). + * `waitForTrailers` {boolean} When `true`, the `Http2Stream` will emit the + `'wantTrailers'` event after the final `DATA` frame has been sent. + +* Returns: {ClientHttp2Stream} + +For HTTP/2 Client `Http2Session` instances only, the `http2session.request()` +creates and returns an `Http2Stream` instance that can be used to send an +HTTP/2 request to the connected server. + +This method is only available if `http2session.type` is equal to +`http2.constants.NGHTTP2_SESSION_CLIENT`. + +```js +const http2 = require('http2'); +const clientSession = http2.connect('https://localhost:1234'); +const { + HTTP2_HEADER_PATH, + HTTP2_HEADER_STATUS +} = http2.constants; + +const req = clientSession.request({ [HTTP2_HEADER_PATH]: '/' }); +req.on('response', (headers) => { + console.log(headers[HTTP2_HEADER_STATUS]); + req.on('data', (chunk) => { /* .. */ }); + req.on('end', () => { /* .. */ }); +}); +``` + +When the `options.waitForTrailers` option is set, the `'wantTrailers'` event +is emitted immediately after queuing the last chunk of payload data to be sent. +The `http2stream.sendTrailers()` method can then be called to send trailing +headers to the peer. + +When `options.waitForTrailers` is set, the `Http2Stream` will not automatically +close when the final `DATA` frame is transmitted. User code must call either +`http2stream.sendTrailers()` or `http2stream.close()` to close the +`Http2Stream`. + +The `:method` and `:path` pseudo-headers are not specified within `headers`, +they respectively default to: + +* `:method` = `'GET'` +* `:path` = `/` + diff --git a/api-docs/5385316dce563775e308844ecc7a9696d430ab012d3d061bdd2ee6b4a53d2921.md b/http2/collecting_http_2_performance_metrics.md similarity index 99% rename from api-docs/5385316dce563775e308844ecc7a9696d430ab012d3d061bdd2ee6b4a53d2921.md rename to http2/collecting_http_2_performance_metrics.md index 3ea20a17..17ff65e2 100644 --- a/api-docs/5385316dce563775e308844ecc7a9696d430ab012d3d061bdd2ee6b4a53d2921.md +++ b/http2/collecting_http_2_performance_metrics.md @@ -105,5 +105,6 @@ following additional properties: + diff --git a/http2/compatibility_api.md b/http2/compatibility_api.md new file mode 100644 index 00000000..6cdc39b8 --- /dev/null +++ b/http2/compatibility_api.md @@ -0,0 +1,30 @@ + +The Compatibility API has the goal of providing a similar developer experience +of HTTP/1 when using HTTP/2, making it possible to develop applications +that support both [HTTP/1][] and HTTP/2. This API targets only the +**public API** of the [HTTP/1][]. However many modules use internal +methods or state, and those _are not supported_ as it is a completely +different implementation. + +The following example creates an HTTP/2 server using the compatibility +API: + +```js +const http2 = require('http2'); +const server = http2.createServer((req, res) => { + res.setHeader('Content-Type', 'text/html'); + res.setHeader('X-Foo', 'bar'); + res.writeHead(200, { 'Content-Type': 'text/plain' }); + res.end('ok'); +}); +``` + +In order to create a mixed [HTTPS][] and HTTP/2 server, refer to the +[ALPN negotiation][] section. +Upgrading from non-tls HTTP/1 servers is not supported. + +The HTTP/2 compatibility API is composed of [`Http2ServerRequest`]() and +[`Http2ServerResponse`](). They aim at API compatibility with HTTP/1, but +they do not hide the differences between the protocols. As an example, +the status message for HTTP codes is ignored. + diff --git a/http2/core_api.md b/http2/core_api.md new file mode 100644 index 00000000..0ac421f7 --- /dev/null +++ b/http2/core_api.md @@ -0,0 +1,10 @@ + +The Core API provides a low-level interface designed specifically around +support for HTTP/2 protocol features. It is specifically *not* designed for +compatibility with the existing [HTTP/1][] module API. However, +the [Compatibility API][] is. + +The `http2` Core API is much more symmetric between client and server than the +`http` API. For instance, most events, like `'error'`, `'connect'` and +`'stream'`, can be emitted either by client-side code or server-side code. + diff --git a/http2/creation.md b/http2/creation.md new file mode 100644 index 00000000..1ffabfed --- /dev/null +++ b/http2/creation.md @@ -0,0 +1,18 @@ + +On the server side, instances of [`ServerHttp2Stream`][] are created either +when: + +* A new HTTP/2 `HEADERS` frame with a previously unused stream ID is received; +* The `http2stream.pushStream()` method is called. + +On the client side, instances of [`ClientHttp2Stream`][] are created when the +`http2session.request()` method is called. + +On the client, the `Http2Stream` instance returned by `http2session.request()` +may not be immediately ready for use if the parent `Http2Session` has not yet +been fully established. In such cases, operations called on the `Http2Stream` +will be buffered until the `'ready'` event is emitted. User code should rarely, +if ever, need to handle the `'ready'` event directly. The ready status of an +`Http2Stream` can be determined by checking the value of `http2stream.id`. If +the value is `undefined`, the stream is not yet ready for use. + diff --git a/http2/destruction.md b/http2/destruction.md new file mode 100644 index 00000000..de09efb7 --- /dev/null +++ b/http2/destruction.md @@ -0,0 +1,21 @@ + +All [`Http2Stream`][] instances are destroyed either when: + +* An `RST_STREAM` frame for the stream is received by the connected peer. +* The `http2stream.close()` method is called. +* The `http2stream.destroy()` or `http2session.destroy()` methods are called. + +When an `Http2Stream` instance is destroyed, an attempt will be made to send an +`RST_STREAM` frame will be sent to the connected peer. + +When the `Http2Stream` instance is destroyed, the `'close'` event will +be emitted. Because `Http2Stream` is an instance of `stream.Duplex`, the +`'end'` event will also be emitted if the stream data is currently flowing. +The `'error'` event may also be emitted if `http2stream.destroy()` was called +with an `Error` passed as the first argument. + +After the `Http2Stream` has been destroyed, the `http2stream.destroyed` +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. + diff --git a/http2/error_codes_for_rst_stream_and_goaway.md b/http2/error_codes_for_rst_stream_and_goaway.md new file mode 100644 index 00000000..8e47cbea --- /dev/null +++ b/http2/error_codes_for_rst_stream_and_goaway.md @@ -0,0 +1,22 @@ + + +| Value | Name | Constant | +|--------|---------------------|-----------------------------------------------| +| `0x00` | No Error | `http2.constants.NGHTTP2_NO_ERROR` | +| `0x01` | Protocol Error | `http2.constants.NGHTTP2_PROTOCOL_ERROR` | +| `0x02` | Internal Error | `http2.constants.NGHTTP2_INTERNAL_ERROR` | +| `0x03` | Flow Control Error | `http2.constants.NGHTTP2_FLOW_CONTROL_ERROR` | +| `0x04` | Settings Timeout | `http2.constants.NGHTTP2_SETTINGS_TIMEOUT` | +| `0x05` | Stream Closed | `http2.constants.NGHTTP2_STREAM_CLOSED` | +| `0x06` | Frame Size Error | `http2.constants.NGHTTP2_FRAME_SIZE_ERROR` | +| `0x07` | Refused Stream | `http2.constants.NGHTTP2_REFUSED_STREAM` | +| `0x08` | Cancel | `http2.constants.NGHTTP2_CANCEL` | +| `0x09` | Compression Error | `http2.constants.NGHTTP2_COMPRESSION_ERROR` | +| `0x0a` | Connect Error | `http2.constants.NGHTTP2_CONNECT_ERROR` | +| `0x0b` | Enhance Your Calm | `http2.constants.NGHTTP2_ENHANCE_YOUR_CALM` | +| `0x0c` | Inadequate Security | `http2.constants.NGHTTP2_INADEQUATE_SECURITY` | +| `0x0d` | HTTP/1.1 Required | `http2.constants.NGHTTP2_HTTP_1_1_REQUIRED` | + +The `'timeout'` event is emitted when there is no activity on the Server for +a given number of milliseconds set using `http2server.setTimeout()`. + diff --git a/http2/error_handling.md b/http2/error_handling.md new file mode 100644 index 00000000..c3ec4cf5 --- /dev/null +++ b/http2/error_handling.md @@ -0,0 +1,21 @@ + +There are several types of error conditions that may arise when using the +`http2` module: + +Validation errors occur when an incorrect argument, option, or setting value is +passed in. These will always be reported by a synchronous `throw`. + +State errors occur when an action is attempted at an incorrect time (for +instance, attempting to send data on a stream after it has closed). These will +be reported using either a synchronous `throw` or via an `'error'` event on +the `Http2Stream`, `Http2Session` or HTTP/2 Server objects, depending on where +and when the error occurs. + +Internal errors occur when an HTTP/2 session fails unexpectedly. These will be +reported via an `'error'` event on the `Http2Session` or HTTP/2 Server objects. + +Protocol errors occur when various HTTP/2 protocol constraints are violated. +These will be reported using either a synchronous `throw` or via an `'error'` +event on the `Http2Stream`, `Http2Session` or HTTP/2 Server objects, depending +on where and when the error occurs. + diff --git a/http2/event_aborted.md b/http2/event_aborted.md new file mode 100644 index 00000000..0dace590 --- /dev/null +++ b/http2/event_aborted.md @@ -0,0 +1,10 @@ + + +The `'aborted'` event is emitted whenever a `Http2Stream` instance is +abnormally aborted in mid-communication. + +The `'aborted'` event will only be emitted if the `Http2Stream` writable side +has not been ended. + diff --git a/http2/event_aborted_1.md b/http2/event_aborted_1.md new file mode 100644 index 00000000..419b86cc --- /dev/null +++ b/http2/event_aborted_1.md @@ -0,0 +1,10 @@ + + +The `'aborted'` event is emitted whenever a `Http2ServerRequest` instance is +abnormally aborted in mid-communication. + +The `'aborted'` event will only be emitted if the `Http2ServerRequest` writable +side has not been ended. + diff --git a/http2/event_altsvc.md b/http2/event_altsvc.md new file mode 100644 index 00000000..1b9913e9 --- /dev/null +++ b/http2/event_altsvc.md @@ -0,0 +1,24 @@ + + +* `alt` {string} +* `origin` {string} +* `streamId` {number} + +The `'altsvc'` event is emitted whenever an `ALTSVC` frame is received by +the client. The event is emitted with the `ALTSVC` value, origin, and stream +ID. If no `origin` is provided in the `ALTSVC` frame, `origin` will +be an empty string. + +```js +const http2 = require('http2'); +const client = http2.connect('https://example.org'); + +client.on('altsvc', (alt, origin, streamId) => { + console.log(alt); + console.log(origin); + console.log(streamId); +}); +``` + diff --git a/http2/event_checkcontinue.md b/http2/event_checkcontinue.md new file mode 100644 index 00000000..e4b69e0b --- /dev/null +++ b/http2/event_checkcontinue.md @@ -0,0 +1,21 @@ + + +* `request` {http2.Http2ServerRequest} +* `response` {http2.Http2ServerResponse} + +If a [`'request'`][] listener is registered or [`http2.createServer()`][] is +supplied a callback function, the `'checkContinue'` event is emitted each time +a request with an HTTP `Expect: 100-continue` is received. If this event is +not listened for, the server will automatically respond with a status +`100 Continue` as appropriate. + +Handling this event involves calling [`response.writeContinue()`][] if the +client should continue to send the request body, or generating an appropriate +HTTP response (e.g. 400 Bad Request) if the client should not continue to send +the request body. + +Note that when this event is emitted and handled, the [`'request'`][] event will +not be emitted. + diff --git a/http2/event_checkcontinue_1.md b/http2/event_checkcontinue_1.md new file mode 100644 index 00000000..c2ad3e87 --- /dev/null +++ b/http2/event_checkcontinue_1.md @@ -0,0 +1,21 @@ + + +* `request` {http2.Http2ServerRequest} +* `response` {http2.Http2ServerResponse} + +If a [`'request'`][] listener is registered or [`http2.createSecureServer()`][] +is supplied a callback function, the `'checkContinue'` event is emitted each +time a request with an HTTP `Expect: 100-continue` is received. If this event +is not listened for, the server will automatically respond with a status +`100 Continue` as appropriate. + +Handling this event involves calling [`response.writeContinue()`][] if the +client should continue to send the request body, or generating an appropriate +HTTP response (e.g. 400 Bad Request) if the client should not continue to send +the request body. + +Note that when this event is emitted and handled, the [`'request'`][] event will +not be emitted. + diff --git a/http2/event_close.md b/http2/event_close.md new file mode 100644 index 00000000..18ab93de --- /dev/null +++ b/http2/event_close.md @@ -0,0 +1,7 @@ + + +The `'close'` event is emitted once the `Http2Session` has been destroyed. Its +listener does not expect any arguments. + diff --git a/http2/event_close_1.md b/http2/event_close_1.md new file mode 100644 index 00000000..e29a04ee --- /dev/null +++ b/http2/event_close_1.md @@ -0,0 +1,11 @@ + + +The `'close'` event is emitted when the `Http2Stream` is destroyed. Once +this event is emitted, the `Http2Stream` instance is no longer usable. + +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. + diff --git a/http2/event_close_2.md b/http2/event_close_2.md new file mode 100644 index 00000000..eea28094 --- /dev/null +++ b/http2/event_close_2.md @@ -0,0 +1,7 @@ + + +Indicates that the underlying [`Http2Stream`][] was closed. +Just like `'end'`, this event occurs only once per response. + diff --git a/http2/event_close_3.md b/http2/event_close_3.md new file mode 100644 index 00000000..3ebaf931 --- /dev/null +++ b/http2/event_close_3.md @@ -0,0 +1,7 @@ + + +Indicates that the underlying [`Http2Stream`]() was terminated before +[`response.end()`][] was called or able to flush. + diff --git a/http2/event_connect.md b/http2/event_connect.md new file mode 100644 index 00000000..0a0af300 --- /dev/null +++ b/http2/event_connect.md @@ -0,0 +1,12 @@ + + +* `session` {Http2Session} +* `socket` {net.Socket} + +The `'connect'` event is emitted once the `Http2Session` has been successfully +connected to the remote peer and communication may begin. + +User code will typically not listen for this event directly. + diff --git a/http2/event_continue.md b/http2/event_continue.md new file mode 100644 index 00000000..909e1d91 --- /dev/null +++ b/http2/event_continue.md @@ -0,0 +1,8 @@ + + +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. + diff --git a/http2/event_error.md b/http2/event_error.md new file mode 100644 index 00000000..663eb057 --- /dev/null +++ b/http2/event_error.md @@ -0,0 +1,9 @@ + + +* `error` {Error} + +The `'error'` event is emitted when an error occurs during the processing of +an `Http2Session`. + diff --git a/http2/event_error_1.md b/http2/event_error_1.md new file mode 100644 index 00000000..ffc6457d --- /dev/null +++ b/http2/event_error_1.md @@ -0,0 +1,9 @@ + + +* `error` {Error} + +The `'error'` event is emitted when an error occurs during the processing of +an `Http2Stream`. + diff --git a/http2/event_finish.md b/http2/event_finish.md new file mode 100644 index 00000000..b4ea1c95 --- /dev/null +++ b/http2/event_finish.md @@ -0,0 +1,11 @@ + + +Emitted when the response has been sent. More specifically, this event is +emitted when the last segment of the response headers and body have been +handed off to the HTTP/2 multiplexing for transmission over the network. It +does not imply that the client has received anything yet. + +After this event, no more events will be emitted on the response object. + diff --git a/http2/event_frameerror.md b/http2/event_frameerror.md new file mode 100644 index 00000000..e0732fa6 --- /dev/null +++ b/http2/event_frameerror.md @@ -0,0 +1,19 @@ + + +* `type` {integer} The frame type. +* `code` {integer} The error code. +* `id` {integer} The stream id (or `0` if the frame isn't associated with a + stream). + +The `'frameError'` event is emitted when an error occurs while attempting to +send a frame on the session. If the frame that could not be sent is associated +with a specific `Http2Stream`, an attempt to emit `'frameError'` event on the +`Http2Stream` is made. + +If the `'frameError'` event is associated with a stream, the stream will be +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. + diff --git a/http2/event_frameerror_1.md b/http2/event_frameerror_1.md new file mode 100644 index 00000000..0276383b --- /dev/null +++ b/http2/event_frameerror_1.md @@ -0,0 +1,10 @@ + + +The `'frameError'` event is emitted when an error occurs while attempting to +send a frame. When invoked, the handler function will receive an integer +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. + diff --git a/http2/event_goaway.md b/http2/event_goaway.md new file mode 100644 index 00000000..2d2caaa1 --- /dev/null +++ b/http2/event_goaway.md @@ -0,0 +1,15 @@ + + +* `errorCode` {number} The HTTP/2 error code specified in the `GOAWAY` frame. +* `lastStreamID` {number} The ID of the last stream the remote peer successfully + processed (or `0` if no ID is specified). +* `opaqueData` {Buffer} If additional opaque data was included in the `GOAWAY` + frame, a `Buffer` instance will be passed containing that data. + +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. + diff --git a/http2/event_headers.md b/http2/event_headers.md new file mode 100644 index 00000000..4d9db65c --- /dev/null +++ b/http2/event_headers.md @@ -0,0 +1,15 @@ + + +The `'headers'` event is emitted when an additional block of headers is received +for a stream, such as when a block of `1xx` informational headers is received. +The listener callback is passed the [HTTP/2 Headers Object][] and flags +associated with the headers. + +```js +stream.on('headers', (headers, flags) => { + console.log(headers); +}); +``` + diff --git a/http2/event_localsettings.md b/http2/event_localsettings.md new file mode 100644 index 00000000..c949a4a7 --- /dev/null +++ b/http2/event_localsettings.md @@ -0,0 +1,20 @@ + + +* `settings` {HTTP/2 Settings Object} A copy of the `SETTINGS` frame received. + +The `'localSettings'` event is emitted when an acknowledgment `SETTINGS` frame +has been received. + +When using `http2session.settings()` to submit new settings, the modified +settings do not take effect until the `'localSettings'` event is emitted. + +```js +session.settings({ enablePush: false }); + +session.on('localSettings', (settings) => { + /* Use the new settings */ +}); +``` + diff --git a/http2/event_origin.md b/http2/event_origin.md new file mode 100644 index 00000000..71d3e7c9 --- /dev/null +++ b/http2/event_origin.md @@ -0,0 +1,23 @@ + + +* `origins` {string[]} + +The `'origin'` event is emitted whenever an `ORIGIN` frame is received by +the client. The event is emitted with an array of `origin` strings. The +`http2session.originSet` will be updated to include the received +origins. + +```js +const http2 = require('http2'); +const client = http2.connect('https://example.org'); + +client.on('origin', (origins) => { + for (let n = 0; n < origins.length; n++) + console.log(origins[n]); +}); +``` + +The `'origin'` event is only emitted when using a secure TLS connection. + diff --git a/http2/event_ping.md b/http2/event_ping.md new file mode 100644 index 00000000..9c6af8d4 --- /dev/null +++ b/http2/event_ping.md @@ -0,0 +1,9 @@ + + +* `payload` {Buffer} The `PING` frame 8-byte payload + +The `'ping'` event is emitted whenever a `PING` frame is received from the +connected peer. + diff --git a/http2/event_push.md b/http2/event_push.md new file mode 100644 index 00000000..31e6ba75 --- /dev/null +++ b/http2/event_push.md @@ -0,0 +1,14 @@ + + +The `'push'` event is emitted when response headers for a Server Push stream +are received. The listener callback is passed the [HTTP/2 Headers Object][] and +flags associated with the headers. + +```js +stream.on('push', (headers, flags) => { + console.log(headers); +}); +``` + diff --git a/http2/event_remotesettings.md b/http2/event_remotesettings.md new file mode 100644 index 00000000..0d66ad26 --- /dev/null +++ b/http2/event_remotesettings.md @@ -0,0 +1,15 @@ + + +* `settings` {HTTP/2 Settings Object} A copy of the `SETTINGS` frame received. + +The `'remoteSettings'` event is emitted when a new `SETTINGS` frame is received +from the connected peer. + +```js +session.on('remoteSettings', (settings) => { + /* Use the new settings */ +}); +``` + diff --git a/http2/event_request.md b/http2/event_request.md new file mode 100644 index 00000000..870c9990 --- /dev/null +++ b/http2/event_request.md @@ -0,0 +1,10 @@ + + +* `request` {http2.Http2ServerRequest} +* `response` {http2.Http2ServerResponse} + +Emitted each time there is a request. Note that there may be multiple requests +per session. See the [Compatibility API][]. + diff --git a/http2/event_request_1.md b/http2/event_request_1.md new file mode 100644 index 00000000..870c9990 --- /dev/null +++ b/http2/event_request_1.md @@ -0,0 +1,10 @@ + + +* `request` {http2.Http2ServerRequest} +* `response` {http2.Http2ServerResponse} + +Emitted each time there is a request. Note that there may be multiple requests +per session. See the [Compatibility API][]. + diff --git a/http2/event_response.md b/http2/event_response.md new file mode 100644 index 00000000..4fb2d82a --- /dev/null +++ b/http2/event_response.md @@ -0,0 +1,18 @@ + + +The `'response'` event is emitted when a response `HEADERS` frame has been +received for this stream from the connected HTTP/2 server. The listener is +invoked with two arguments: an `Object` containing the received +[HTTP/2 Headers Object][], and flags associated with the headers. + +```js +const http2 = require('http2'); +const client = http2.connect('https://localhost'); +const req = client.request({ ':path': '/' }); +req.on('response', (headers, flags) => { + console.log(headers[':status']); +}); +``` + diff --git a/http2/event_session.md b/http2/event_session.md new file mode 100644 index 00000000..4fb63a07 --- /dev/null +++ b/http2/event_session.md @@ -0,0 +1,7 @@ + + +The `'session'` event is emitted when a new `Http2Session` is created by the +`Http2Server`. + diff --git a/http2/event_session_1.md b/http2/event_session_1.md new file mode 100644 index 00000000..0ccdd973 --- /dev/null +++ b/http2/event_session_1.md @@ -0,0 +1,7 @@ + + +The `'session'` event is emitted when a new `Http2Session` is created by the +`Http2SecureServer`. + diff --git a/http2/event_sessionerror.md b/http2/event_sessionerror.md new file mode 100644 index 00000000..6057add7 --- /dev/null +++ b/http2/event_sessionerror.md @@ -0,0 +1,7 @@ + + +The `'sessionError'` event is emitted when an `'error'` event is emitted by +an `Http2Session` object associated with the `Http2Server`. + diff --git a/http2/event_sessionerror_1.md b/http2/event_sessionerror_1.md new file mode 100644 index 00000000..b0fa40fb --- /dev/null +++ b/http2/event_sessionerror_1.md @@ -0,0 +1,7 @@ + + +The `'sessionError'` event is emitted when an `'error'` event is emitted by +an `Http2Session` object associated with the `Http2SecureServer`. + diff --git a/http2/event_stream.md b/http2/event_stream.md new file mode 100644 index 00000000..d63f75e8 --- /dev/null +++ b/http2/event_stream.md @@ -0,0 +1,54 @@ + + +* `stream` {Http2Stream} A reference to the stream +* `headers` {HTTP/2 Headers Object} An object describing the headers +* `flags` {number} The associated numeric flags +* `rawHeaders` {Array} An array containing the raw header names followed by + their respective values. + +The `'stream'` event is emitted when a new `Http2Stream` is created. + +```js +const http2 = require('http2'); +session.on('stream', (stream, headers, flags) => { + const method = headers[':method']; + const path = headers[':path']; + // ... + stream.respond({ + ':status': 200, + 'content-type': 'text/plain' + }); + stream.write('hello '); + stream.end('world'); +}); +``` + +On the server side, user code will typically not listen for this event directly, +and would instead register a handler for the `'stream'` event emitted by the +`net.Server` or `tls.Server` instances returned by `http2.createServer()` and +`http2.createSecureServer()`, respectively, as in the example below: + +```js +const http2 = require('http2'); + +// Create an unencrypted HTTP/2 server +const server = http2.createServer(); + +server.on('stream', (stream, headers) => { + stream.respond({ + 'content-type': 'text/html', + ':status': 200 + }); + stream.on('error', (error) => console.error(error)); + stream.end('

Hello World

'); +}); + +server.listen(80); +``` + +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. + diff --git a/http2/event_stream_1.md b/http2/event_stream_1.md new file mode 100644 index 00000000..40e6a799 --- /dev/null +++ b/http2/event_stream_1.md @@ -0,0 +1,30 @@ + + +The `'stream'` event is emitted when a `'stream'` event has been emitted by +an `Http2Session` associated with the server. + +```js +const http2 = require('http2'); +const { + HTTP2_HEADER_METHOD, + HTTP2_HEADER_PATH, + HTTP2_HEADER_STATUS, + HTTP2_HEADER_CONTENT_TYPE +} = http2.constants; + +const server = http2.createServer(); +server.on('stream', (stream, headers, flags) => { + const method = headers[HTTP2_HEADER_METHOD]; + const path = headers[HTTP2_HEADER_PATH]; + // ... + stream.respond({ + [HTTP2_HEADER_STATUS]: 200, + [HTTP2_HEADER_CONTENT_TYPE]: 'text/plain' + }); + stream.write('hello '); + stream.end('world'); +}); +``` + diff --git a/http2/event_stream_2.md b/http2/event_stream_2.md new file mode 100644 index 00000000..626521fe --- /dev/null +++ b/http2/event_stream_2.md @@ -0,0 +1,32 @@ + + +The `'stream'` event is emitted when a `'stream'` event has been emitted by +an `Http2Session` associated with the server. + +```js +const http2 = require('http2'); +const { + HTTP2_HEADER_METHOD, + HTTP2_HEADER_PATH, + HTTP2_HEADER_STATUS, + HTTP2_HEADER_CONTENT_TYPE +} = http2.constants; + +const options = getOptionsSomehow(); + +const server = http2.createSecureServer(options); +server.on('stream', (stream, headers, flags) => { + const method = headers[HTTP2_HEADER_METHOD]; + const path = headers[HTTP2_HEADER_PATH]; + // ... + stream.respond({ + [HTTP2_HEADER_STATUS]: 200, + [HTTP2_HEADER_CONTENT_TYPE]: 'text/plain' + }); + stream.write('hello '); + stream.end('world'); +}); +``` + diff --git a/http2/event_timeout.md b/http2/event_timeout.md new file mode 100644 index 00000000..8519ccee --- /dev/null +++ b/http2/event_timeout.md @@ -0,0 +1,13 @@ + + +After the `http2session.setTimeout()` method is used to set the timeout period +for this `Http2Session`, the `'timeout'` event is emitted if there is no +activity on the `Http2Session` after the configured number of milliseconds. + +```js +session.setTimeout(2000); +session.on('timeout', () => { /* .. */ }); +``` + diff --git a/http2/event_timeout_1.md b/http2/event_timeout_1.md new file mode 100644 index 00000000..c8b62901 --- /dev/null +++ b/http2/event_timeout_1.md @@ -0,0 +1,8 @@ + + +The `'timeout'` event is emitted after no activity is received for this +`Http2Stream` within the number of milliseconds set using +`http2stream.setTimeout()`. + diff --git a/http2/event_timeout_2.md b/http2/event_timeout_2.md new file mode 100644 index 00000000..95f29a34 --- /dev/null +++ b/http2/event_timeout_2.md @@ -0,0 +1,8 @@ + + +The `'timeout'` event is emitted when there is no activity on the Server for +a given number of milliseconds set using `http2server.setTimeout()`. +**Default:** 2 minutes. + diff --git a/http2/event_timeout_3.md b/http2/event_timeout_3.md new file mode 100644 index 00000000..bfcb80bd --- /dev/null +++ b/http2/event_timeout_3.md @@ -0,0 +1,8 @@ + + +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. + diff --git a/http2/event_trailers.md b/http2/event_trailers.md new file mode 100644 index 00000000..6196627a --- /dev/null +++ b/http2/event_trailers.md @@ -0,0 +1,18 @@ + + +The `'trailers'` event is emitted when a block of headers associated with +trailing header fields is received. The listener callback is passed the +[HTTP/2 Headers Object][] and flags associated with the headers. + +Note that this event might not be emitted if `http2stream.end()` is called +before trailers are received and the incoming data is not being read or +listened for. + +```js +stream.on('trailers', (headers, flags) => { + console.log(headers); +}); +``` + diff --git a/http2/event_unknownprotocol.md b/http2/event_unknownprotocol.md new file mode 100644 index 00000000..44d577d5 --- /dev/null +++ b/http2/event_unknownprotocol.md @@ -0,0 +1,9 @@ + + +The `'unknownProtocol'` event is emitted when a connecting client fails to +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][]. + diff --git a/http2/event_wanttrailers.md b/http2/event_wanttrailers.md new file mode 100644 index 00000000..a0dbe4fe --- /dev/null +++ b/http2/event_wanttrailers.md @@ -0,0 +1,9 @@ + + +The `'wantTrailers'` event is emitted when the `Http2Stream` has queued the +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. + diff --git a/http2/headers_object.md b/http2/headers_object.md new file mode 100644 index 00000000..cbd8ae6c --- /dev/null +++ b/http2/headers_object.md @@ -0,0 +1,46 @@ + +Headers are represented as own-properties on JavaScript objects. The property +keys will be serialized to lower-case. Property values should be strings (if +they are not they will be coerced to strings) or an `Array` of strings (in order +to send more than one value per header field). + +```js +const headers = { + ':status': '200', + 'content-type': 'text-plain', + 'ABC': ['has', 'more', 'than', 'one', 'value'] +}; + +stream.respond(headers); +``` + +Header objects passed to callback functions will have a `null` prototype. This +means that normal JavaScript object methods such as +`Object.prototype.toString()` and `Object.prototype.hasOwnProperty()` will +not work. + +For incoming headers: +* The `:status` header is converted to `number`. +* Duplicates of `:status`, `:method`, `:authority`, `:scheme`, `:path`, +`:protocol`, `age`, `authorization`, `access-control-allow-credentials`, +`access-control-max-age`, `access-control-request-method`, `content-encoding`, +`content-language`, `content-length`, `content-location`, `content-md5`, +`content-range`, `content-type`, `date`, `dnt`, `etag`, `expires`, `from`, +`if-match`, `if-modified-since`, `if-none-match`, `if-range`, +`if-unmodified-since`, `last-modified`, `location`, `max-forwards`, +`proxy-authorization`, `range`, `referer`,`retry-after`, `tk`, +`upgrade-insecure-requests`, `user-agent` or `x-content-type-options` are +discarded. +* `set-cookie` is always an array. Duplicates are added to the array. +* For duplicate `cookie` headers, the values are joined together with '; '. +* For all other headers, the values are joined together with ', '. + +```js +const http2 = require('http2'); +const server = http2.createServer(); +server.on('stream', (stream, headers) => { + console.log(headers[':path']); + console.log(headers.ABC); +}); +``` + diff --git a/http2/http2_connect_authority_options_listener.md b/http2/http2_connect_authority_options_listener.md new file mode 100644 index 00000000..ad02b8f3 --- /dev/null +++ b/http2/http2_connect_authority_options_listener.md @@ -0,0 +1,83 @@ + + +* `authority` {string|URL} +* `options` {Object} + * `maxDeflateDynamicTableSize` {number} Sets the maximum dynamic table size + for deflating header fields. **Default:** `4Kib`. + * `maxSessionMemory`{number} Sets the maximum memory that the `Http2Session` + is permitted to use. The value is expressed in terms of number of megabytes, + e.g. `1` equal 1 megabyte. The minimum value allowed is `1`. + This is a credit based limit, existing `Http2Stream`s may cause this + limit to be exceeded, but new `Http2Stream` instances will be rejected + while this limit is exceeded. The current number of `Http2Stream` sessions, + the current memory use of the header compression tables, current data + queued to be sent, and unacknowledged `PING` and `SETTINGS` frames are all + counted towards the current limit. **Default:** `10`. + * `maxHeaderListPairs` {number} Sets the maximum number of header entries. + The minimum value is `1`. **Default:** `128`. + * `maxOutstandingPings` {number} Sets the maximum number of outstanding, + unacknowledged pings. **Default:** `10`. + * `maxReservedRemoteStreams` {number} Sets the maximum number of reserved push + streams the client will accept at any given time. Once the current number of + currently reserved push streams exceeds reaches this limit, new push streams + sent by the server will be automatically rejected. + * `maxSendHeaderBlockLength` {number} Sets the maximum allowed size for a + serialized, compressed block of headers. Attempts to send headers that + exceed this limit will result in a `'frameError'` event being emitted + and the stream being closed and destroyed. + * `paddingStrategy` {number} Identifies the strategy used for determining the + amount of padding to use for `HEADERS` and `DATA` frames. **Default:** + `http2.constants.PADDING_STRATEGY_NONE`. Value may be one of: + * `http2.constants.PADDING_STRATEGY_NONE` - Specifies that no padding is + to be applied. + * `http2.constants.PADDING_STRATEGY_MAX` - Specifies that the maximum + amount of padding, as determined by the internal implementation, is to + be applied. + * `http2.constants.PADDING_STRATEGY_CALLBACK` - Specifies that the user + provided `options.selectPadding()` callback is to be used to determine + the amount of padding. + * `http2.constants.PADDING_STRATEGY_ALIGNED` - Will *attempt* to apply + enough padding to ensure that the total frame length, including the + 9-byte header, is a multiple of 8. For each frame, however, there is a + maximum allowed number of padding bytes that is determined by current + flow control state and settings. If this maximum is less than the + calculated amount needed to ensure alignment, the maximum will be used + and the total frame length will *not* necessarily be aligned at 8 bytes. + * `peerMaxConcurrentStreams` {number} Sets the maximum number of concurrent + streams for the remote peer as if a `SETTINGS` frame had been received. Will + be overridden if the remote peer sets its own value for + `maxConcurrentStreams`. **Default:** `100`. + * `selectPadding` {Function} When `options.paddingStrategy` is equal to + `http2.constants.PADDING_STRATEGY_CALLBACK`, provides the callback function + used to determine the padding. See [Using `options.selectPadding()`][]. + * `settings` {HTTP/2 Settings Object} The initial settings to send to the + remote peer upon connection. + * `createConnection` {Function} An optional callback that receives the `URL` + instance passed to `connect` and the `options` object, and returns any + [`Duplex`][] stream that is to be used as the connection for this session. + * ...: Any [`net.connect()`][] or [`tls.connect()`][] options can be provided. +* `listener` {Function} +* Returns: {ClientHttp2Session} + +Returns a `ClientHttp2Session` instance. + +```js +const http2 = require('http2'); +const client = http2.connect('https://localhost:1234'); + +/* Use the client */ + +client.close(); +``` + diff --git a/http2/http2_constants.md b/http2/http2_constants.md new file mode 100644 index 00000000..538121c0 --- /dev/null +++ b/http2/http2_constants.md @@ -0,0 +1,4 @@ + + diff --git a/http2/http2_createsecureserver_options_onrequesthandler.md b/http2/http2_createsecureserver_options_onrequesthandler.md new file mode 100644 index 00000000..8a82d045 --- /dev/null +++ b/http2/http2_createsecureserver_options_onrequesthandler.md @@ -0,0 +1,101 @@ + + +* `options` {Object} + * `allowHTTP1` {boolean} Incoming client connections that do not support + HTTP/2 will be downgraded to HTTP/1.x when set to `true`. + See the [`'unknownProtocol'`][] event. See [ALPN negotiation][]. + **Default:** `false`. + * `maxDeflateDynamicTableSize` {number} Sets the maximum dynamic table size + for deflating header fields. **Default:** `4Kib`. + * `maxSessionMemory`{number} Sets the maximum memory that the `Http2Session` + is permitted to use. The value is expressed in terms of number of megabytes, + e.g. `1` equal 1 megabyte. The minimum value allowed is `1`. This is a + credit based limit, existing `Http2Stream`s may cause this + limit to be exceeded, but new `Http2Stream` instances will be rejected + while this limit is exceeded. The current number of `Http2Stream` sessions, + the current memory use of the header compression tables, current data + queued to be sent, and unacknowledged `PING` and `SETTINGS` frames are all + counted towards the current limit. **Default:** `10`. + * `maxHeaderListPairs` {number} Sets the maximum number of header entries. + The minimum value is `4`. **Default:** `128`. + * `maxOutstandingPings` {number} Sets the maximum number of outstanding, + unacknowledged pings. **Default:** `10`. + * `maxSendHeaderBlockLength` {number} Sets the maximum allowed size for a + serialized, compressed block of headers. Attempts to send headers that + exceed this limit will result in a `'frameError'` event being emitted + and the stream being closed and destroyed. + * `paddingStrategy` {number} Identifies the strategy used for determining the + amount of padding to use for `HEADERS` and `DATA` frames. **Default:** + `http2.constants.PADDING_STRATEGY_NONE`. Value may be one of: + * `http2.constants.PADDING_STRATEGY_NONE` - Specifies that no padding is + to be applied. + * `http2.constants.PADDING_STRATEGY_MAX` - Specifies that the maximum + amount of padding, as determined by the internal implementation, is to + be applied. + * `http2.constants.PADDING_STRATEGY_CALLBACK` - Specifies that the user + provided `options.selectPadding()` callback is to be used to determine + the amount of padding. + * `http2.constants.PADDING_STRATEGY_ALIGNED` - Will *attempt* to apply + enough padding to ensure that the total frame length, including the + 9-byte header, is a multiple of 8. For each frame, however, there is a + maximum allowed number of padding bytes that is determined by current + flow control state and settings. If this maximum is less than the + calculated amount needed to ensure alignment, the maximum will be used + and the total frame length will *not* necessarily be aligned at 8 bytes. + * `peerMaxConcurrentStreams` {number} Sets the maximum number of concurrent + streams for the remote peer as if a `SETTINGS` frame had been received. Will + be overridden if the remote peer sets its own value for + `maxConcurrentStreams`. **Default:** `100`. + * `selectPadding` {Function} When `options.paddingStrategy` is equal to + `http2.constants.PADDING_STRATEGY_CALLBACK`, provides the callback function + used to determine the padding. See [Using `options.selectPadding()`][]. + * `settings` {HTTP/2 Settings Object} The initial settings to send to the + remote peer upon connection. + * ...: Any [`tls.createServer()`][] options can be provided. For + servers, the identity options (`pfx` or `key`/`cert`) are usually required. + * `origins` {string[]} An array of origin strings to send within an `ORIGIN` + frame immediately following creation of a new server `Http2Session`. +* `onRequestHandler` {Function} See [Compatibility API][] +* Returns: {Http2SecureServer} + +Returns a `tls.Server` instance that creates and manages `Http2Session` +instances. + +```js +const http2 = require('http2'); +const fs = require('fs'); + +const options = { + key: fs.readFileSync('server-key.pem'), + cert: fs.readFileSync('server-cert.pem') +}; + +// Create a secure HTTP/2 server +const server = http2.createSecureServer(options); + +server.on('stream', (stream, headers) => { + stream.respond({ + 'content-type': 'text/html', + ':status': 200 + }); + stream.end('

Hello World

'); +}); + +server.listen(80); +``` + diff --git a/http2/http2_createserver_options_onrequesthandler.md b/http2/http2_createserver_options_onrequesthandler.md new file mode 100644 index 00000000..b88f349d --- /dev/null +++ b/http2/http2_createserver_options_onrequesthandler.md @@ -0,0 +1,109 @@ + + +* `options` {Object} + * `maxDeflateDynamicTableSize` {number} Sets the maximum dynamic table size + for deflating header fields. **Default:** `4Kib`. + * `maxSessionMemory`{number} Sets the maximum memory that the `Http2Session` + is permitted to use. The value is expressed in terms of number of megabytes, + e.g. `1` equal 1 megabyte. The minimum value allowed is `1`. + This is a credit based limit, existing `Http2Stream`s may cause this + limit to be exceeded, but new `Http2Stream` instances will be rejected + while this limit is exceeded. The current number of `Http2Stream` sessions, + the current memory use of the header compression tables, current data + queued to be sent, and unacknowledged `PING` and `SETTINGS` frames are all + counted towards the current limit. **Default:** `10`. + * `maxHeaderListPairs` {number} Sets the maximum number of header entries. + The minimum value is `4`. **Default:** `128`. + * `maxOutstandingPings` {number} Sets the maximum number of outstanding, + unacknowledged pings. **Default:** `10`. + * `maxSendHeaderBlockLength` {number} Sets the maximum allowed size for a + serialized, compressed block of headers. Attempts to send headers that + exceed this limit will result in a `'frameError'` event being emitted + and the stream being closed and destroyed. + * `paddingStrategy` {number} Identifies the strategy used for determining the + amount of padding to use for `HEADERS` and `DATA` frames. **Default:** + `http2.constants.PADDING_STRATEGY_NONE`. Value may be one of: + * `http2.constants.PADDING_STRATEGY_NONE` - Specifies that no padding is + to be applied. + * `http2.constants.PADDING_STRATEGY_MAX` - Specifies that the maximum + amount of padding, as determined by the internal implementation, is to + be applied. + * `http2.constants.PADDING_STRATEGY_CALLBACK` - Specifies that the user + provided `options.selectPadding()` callback is to be used to determine + the amount of padding. + * `http2.constants.PADDING_STRATEGY_ALIGNED` - Will *attempt* to apply + enough padding to ensure that the total frame length, including the + 9-byte header, is a multiple of 8. For each frame, however, there is a + maximum allowed number of padding bytes that is determined by current + flow control state and settings. If this maximum is less than the + calculated amount needed to ensure alignment, the maximum will be used + and the total frame length will *not* necessarily be aligned at 8 bytes. + * `peerMaxConcurrentStreams` {number} Sets the maximum number of concurrent + streams for the remote peer as if a `SETTINGS` frame had been received. Will + be overridden if the remote peer sets its own value for + `maxConcurrentStreams`. **Default:** `100`. + * `selectPadding` {Function} When `options.paddingStrategy` is equal to + `http2.constants.PADDING_STRATEGY_CALLBACK`, provides the callback function + used to determine the padding. See [Using `options.selectPadding()`][]. + * `settings` {HTTP/2 Settings Object} The initial settings to send to the + remote peer upon connection. + * `Http1IncomingMessage` {http.IncomingMessage} Specifies the + `IncomingMessage` class to used for HTTP/1 fallback. Useful for extending + the original `http.IncomingMessage`. **Default:** `http.IncomingMessage`. + * `Http1ServerResponse` {http.ServerResponse} Specifies the `ServerResponse` + class to used for HTTP/1 fallback. Useful for extending the original + `http.ServerResponse`. **Default:** `http.ServerResponse`. + * `Http2ServerRequest` {http2.Http2ServerRequest} Specifies the + `Http2ServerRequest` class to use. + Useful for extending the original `Http2ServerRequest`. + **Default:** `Http2ServerRequest`. + * `Http2ServerResponse` {http2.Http2ServerResponse} Specifies the + `Http2ServerResponse` class to use. + Useful for extending the original `Http2ServerResponse`. + **Default:** `Http2ServerResponse`. +* `onRequestHandler` {Function} See [Compatibility API][] +* Returns: {Http2Server} + +Returns a `net.Server` instance that creates and manages `Http2Session` +instances. + +Since there are no browsers known that support +[unencrypted HTTP/2][HTTP/2 Unencrypted], the use of +[`http2.createSecureServer()`][] is necessary when communicating +with browser clients. + +```js +const http2 = require('http2'); + +// Create an unencrypted HTTP/2 server. +// Since there are no browsers known that support +// unencrypted HTTP/2, the use of `http2.createSecureServer()` +// is necessary when communicating with browser clients. +const server = http2.createServer(); + +server.on('stream', (stream, headers) => { + stream.respond({ + 'content-type': 'text/html', + ':status': 200 + }); + stream.end('

Hello World

'); +}); + +server.listen(80); +``` + diff --git a/http2/http2_getdefaultsettings.md b/http2/http2_getdefaultsettings.md new file mode 100644 index 00000000..50874e19 --- /dev/null +++ b/http2/http2_getdefaultsettings.md @@ -0,0 +1,10 @@ + + +* Returns: {HTTP/2 Settings Object} + +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. + diff --git a/http2/http2_getpackedsettings_settings.md b/http2/http2_getpackedsettings_settings.md new file mode 100644 index 00000000..1f975487 --- /dev/null +++ b/http2/http2_getpackedsettings_settings.md @@ -0,0 +1,20 @@ + + +* `settings` {HTTP/2 Settings Object} +* Returns: {Buffer} + +Returns a `Buffer` instance containing serialized representation of the given +HTTP/2 settings as specified in the [HTTP/2][] specification. This is intended +for use with the `HTTP2-Settings` header field. + +```js +const http2 = require('http2'); + +const packed = http2.getPackedSettings({ enablePush: false }); + +console.log(packed.toString('base64')); +// Prints: AAIAAAAA +``` + diff --git a/http2/http2_getunpackedsettings_buf.md b/http2/http2_getunpackedsettings_buf.md new file mode 100644 index 00000000..262e67ac --- /dev/null +++ b/http2/http2_getunpackedsettings_buf.md @@ -0,0 +1,10 @@ + + +* `buf` {Buffer|Uint8Array} The packed settings. +* Returns: {HTTP/2 Settings Object} + +Returns a [HTTP/2 Settings Object][] containing the deserialized settings from +the given `Buffer` as generated by `http2.getPackedSettings()`. + diff --git a/http2/http2session_alpnprotocol.md b/http2/http2session_alpnprotocol.md new file mode 100644 index 00000000..613ae368 --- /dev/null +++ b/http2/http2session_alpnprotocol.md @@ -0,0 +1,11 @@ + + +* {string|undefined} + +Value will be `undefined` if the `Http2Session` is not yet connected to a +socket, `h2c` if the `Http2Session` is not connected to a `TLSSocket`, or +will return the value of the connected `TLSSocket`'s own `alpnProtocol` +property. + diff --git a/http2/http2session_and_sockets.md b/http2/http2session_and_sockets.md new file mode 100644 index 00000000..6bb41989 --- /dev/null +++ b/http2/http2session_and_sockets.md @@ -0,0 +1,14 @@ + +Every `Http2Session` instance is associated with exactly one [`net.Socket`][] or +[`tls.TLSSocket`][] when it is created. When either the `Socket` or the +`Http2Session` are destroyed, both will be destroyed. + +Because of the specific serialization and processing requirements imposed +by the HTTP/2 protocol, it is not recommended for user code to read data from +or write data to a `Socket` instance bound to a `Http2Session`. Doing so can +put the HTTP/2 session into an indeterminate state causing the session and +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`. + diff --git a/http2/http2session_close_callback.md b/http2/http2session_close_callback.md new file mode 100644 index 00000000..b3c162f4 --- /dev/null +++ b/http2/http2session_close_callback.md @@ -0,0 +1,14 @@ + + +* `callback` {Function} + +Gracefully closes the `Http2Session`, allowing any existing streams to +complete on their own and preventing new `Http2Stream` instances from being +created. Once closed, `http2session.destroy()` *might* be called if there +are no open `Http2Stream` instances. + +If specified, the `callback` function is registered as a handler for the +`'close'` event. + diff --git a/http2/http2session_closed.md b/http2/http2session_closed.md new file mode 100644 index 00000000..398d7556 --- /dev/null +++ b/http2/http2session_closed.md @@ -0,0 +1,9 @@ + + +* {boolean} + +Will be `true` if this `Http2Session` instance has been closed, otherwise +`false`. + diff --git a/http2/http2session_connecting.md b/http2/http2session_connecting.md new file mode 100644 index 00000000..4986e82f --- /dev/null +++ b/http2/http2session_connecting.md @@ -0,0 +1,10 @@ + + +* {boolean} + +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. + diff --git a/http2/http2session_destroy_error_code.md b/http2/http2session_destroy_error_code.md new file mode 100644 index 00000000..1934bba4 --- /dev/null +++ b/http2/http2session_destroy_error_code.md @@ -0,0 +1,20 @@ + + +* `error` {Error} An `Error` object if the `Http2Session` is being destroyed + due to an error. +* `code` {number} The HTTP/2 error code to send in the final `GOAWAY` frame. + If unspecified, and `error` is not undefined, the default is `INTERNAL_ERROR`, + otherwise defaults to `NO_ERROR`. + +Immediately terminates the `Http2Session` and the associated `net.Socket` or +`tls.TLSSocket`. + +Once destroyed, the `Http2Session` will emit the `'close'` event. If `error` +is not undefined, an `'error'` event will be emitted immediately before the +`'close'` event. + +If there are any remaining open `Http2Streams` associated with the +`Http2Session`, those will also be destroyed. + diff --git a/http2/http2session_destroyed.md b/http2/http2session_destroyed.md new file mode 100644 index 00000000..e00f1bea --- /dev/null +++ b/http2/http2session_destroyed.md @@ -0,0 +1,9 @@ + + +* {boolean} + +Will be `true` if this `Http2Session` instance has been destroyed and must no +longer be used, otherwise `false`. + diff --git a/http2/http2session_encrypted.md b/http2/http2session_encrypted.md new file mode 100644 index 00000000..ceb57652 --- /dev/null +++ b/http2/http2session_encrypted.md @@ -0,0 +1,11 @@ + + +* {boolean|undefined} + +Value is `undefined` if the `Http2Session` session socket has not yet been +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. + diff --git a/http2/http2session_goaway_code_laststreamid_opaquedata.md b/http2/http2session_goaway_code_laststreamid_opaquedata.md new file mode 100644 index 00000000..d39e0ffa --- /dev/null +++ b/http2/http2session_goaway_code_laststreamid_opaquedata.md @@ -0,0 +1,12 @@ + + +* `code` {number} An HTTP/2 error code +* `lastStreamID` {number} The numeric ID of the last processed `Http2Stream` +* `opaqueData` {Buffer|TypedArray|DataView} A `TypedArray` or `DataView` + instance containing additional data to be carried within the `GOAWAY` frame. + +Transmits a `GOAWAY` frame to the connected peer *without* shutting down the +`Http2Session`. + diff --git a/http2/http2session_localsettings.md b/http2/http2session_localsettings.md new file mode 100644 index 00000000..27d67b1c --- /dev/null +++ b/http2/http2session_localsettings.md @@ -0,0 +1,9 @@ + + +* {HTTP/2 Settings Object} + +A prototype-less object describing the current local settings of this +`Http2Session`. The local settings are local to *this* `Http2Session` instance. + diff --git a/http2/http2session_originset.md b/http2/http2session_originset.md new file mode 100644 index 00000000..7c7a3691 --- /dev/null +++ b/http2/http2session_originset.md @@ -0,0 +1,12 @@ + + +* {string[]|undefined} + +If the `Http2Session` is connected to a `TLSSocket`, the `originSet` property +will return an `Array` of origins for which the `Http2Session` may be +considered authoritative. + +The `originSet` property is only available when using a secure TLS connection. + diff --git a/http2/http2session_pendingsettingsack.md b/http2/http2session_pendingsettingsack.md new file mode 100644 index 00000000..b3227619 --- /dev/null +++ b/http2/http2session_pendingsettingsack.md @@ -0,0 +1,11 @@ + + +* {boolean} + +Indicates whether or not the `Http2Session` is currently waiting for an +acknowledgment for a sent `SETTINGS` frame. Will be `true` after calling the +`http2session.settings()` method. Will be `false` once all sent SETTINGS +frames have been acknowledged. + diff --git a/http2/http2session_ping_payload_callback.md b/http2/http2session_ping_payload_callback.md new file mode 100644 index 00000000..010f57bc --- /dev/null +++ b/http2/http2session_ping_payload_callback.md @@ -0,0 +1,37 @@ + + +* `payload` {Buffer|TypedArray|DataView} Optional ping payload. +* `callback` {Function} +* Returns: {boolean} + +Sends a `PING` frame to the connected HTTP/2 peer. A `callback` function must +be provided. The method will return `true` if the `PING` was sent, `false` +otherwise. + +The maximum number of outstanding (unacknowledged) pings is determined by the +`maxOutstandingPings` configuration option. The default maximum is 10. + +If provided, the `payload` must be a `Buffer`, `TypedArray`, or `DataView` +containing 8 bytes of data that will be transmitted with the `PING` and +returned with the ping acknowledgment. + +The callback will be invoked with three arguments: an error argument that will +be `null` if the `PING` was successfully acknowledged, a `duration` argument +that reports the number of milliseconds elapsed since the ping was sent and the +acknowledgment was received, and a `Buffer` containing the 8-byte `PING` +payload. + +```js +session.ping(Buffer.from('abcdefgh'), (err, duration, payload) => { + if (!err) { + console.log(`Ping acknowledged in ${duration} milliseconds`); + console.log(`With payload '${payload.toString()}'`); + } +}); +``` + +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. + diff --git a/http2/http2session_ref.md b/http2/http2session_ref.md new file mode 100644 index 00000000..42148933 --- /dev/null +++ b/http2/http2session_ref.md @@ -0,0 +1,7 @@ + + +Calls [`ref()`][`net.Socket.prototype.ref()`] on this `Http2Session` +instance's underlying [`net.Socket`]. + diff --git a/http2/http2session_remotesettings.md b/http2/http2session_remotesettings.md new file mode 100644 index 00000000..ca66802d --- /dev/null +++ b/http2/http2session_remotesettings.md @@ -0,0 +1,9 @@ + + +* {HTTP/2 Settings Object} + +A prototype-less object describing the current remote settings of this +`Http2Session`. The remote settings are set by the *connected* HTTP/2 peer. + diff --git a/http2/http2session_settimeout_msecs_callback.md b/http2/http2session_settimeout_msecs_callback.md new file mode 100644 index 00000000..5486e75e --- /dev/null +++ b/http2/http2session_settimeout_msecs_callback.md @@ -0,0 +1,11 @@ + + +* `msecs` {number} +* `callback` {Function} + +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. + diff --git a/http2/http2session_settings_settings.md b/http2/http2session_settings_settings.md new file mode 100644 index 00000000..2f779f09 --- /dev/null +++ b/http2/http2session_settings_settings.md @@ -0,0 +1,17 @@ + + +* `settings` {HTTP/2 Settings Object} + +Updates the current local settings for this `Http2Session` and sends a new +`SETTINGS` frame to the connected HTTP/2 peer. + +Once called, the `http2session.pendingSettingsAck` property will be `true` +while the session is waiting for the remote peer to acknowledge the new +settings. + +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. + diff --git a/http2/http2session_socket.md b/http2/http2session_socket.md new file mode 100644 index 00000000..7aca2769 --- /dev/null +++ b/http2/http2session_socket.md @@ -0,0 +1,17 @@ + + +* {net.Socket|tls.TLSSocket} + +Returns a `Proxy` object that acts as a `net.Socket` (or `tls.TLSSocket`) but +limits available methods to ones safe to use with HTTP/2. + +`destroy`, `emit`, `end`, `pause`, `read`, `resume`, and `write` will throw +an error with code `ERR_HTTP2_NO_SOCKET_MANIPULATION`. See +[`Http2Session` and Sockets][] for more information. + +`setTimeout` method will be called on this `Http2Session`. + +All other interactions will be routed directly to the socket. + diff --git a/http2/http2session_state.md b/http2/http2session_state.md new file mode 100644 index 00000000..6ae6d7f6 --- /dev/null +++ b/http2/http2session_state.md @@ -0,0 +1,29 @@ + + +Provides miscellaneous information about the current state of the +`Http2Session`. + +* {Object} + * `effectiveLocalWindowSize` {number} The current local (receive) + flow control window size for the `Http2Session`. + * `effectiveRecvDataLength` {number} The current number of bytes + that have been received since the last flow control `WINDOW_UPDATE`. + * `nextStreamID` {number} The numeric identifier to be used the + next time a new `Http2Stream` is created by this `Http2Session`. + * `localWindowSize` {number} The number of bytes that the remote peer can + send without receiving a `WINDOW_UPDATE`. + * `lastProcStreamID` {number} The numeric id of the `Http2Stream` + for which a `HEADERS` or `DATA` frame was most recently received. + * `remoteWindowSize` {number} The number of bytes that this `Http2Session` + may send without receiving a `WINDOW_UPDATE`. + * `outboundQueueSize` {number} The number of frames currently within the + outbound queue for this `Http2Session`. + * `deflateDynamicTableSize` {number} The current size in bytes of the + outbound header compression state table. + * `inflateDynamicTableSize` {number} The current size in bytes of the + inbound header compression state table. + +An object describing the current status of this `Http2Session`. + diff --git a/http2/http2session_type.md b/http2/http2session_type.md new file mode 100644 index 00000000..54f37ce1 --- /dev/null +++ b/http2/http2session_type.md @@ -0,0 +1,11 @@ + + +* {number} + +The `http2session.type` will be equal to +`http2.constants.NGHTTP2_SESSION_SERVER` if this `Http2Session` instance is a +server, and `http2.constants.NGHTTP2_SESSION_CLIENT` if the instance is a +client. + diff --git a/http2/http2session_unref.md b/http2/http2session_unref.md new file mode 100644 index 00000000..1b281958 --- /dev/null +++ b/http2/http2session_unref.md @@ -0,0 +1,7 @@ + + +Calls [`unref()`][`net.Socket.prototype.unref()`] on this `Http2Session` +instance's underlying [`net.Socket`]. + diff --git a/http2/http2stream_aborted.md b/http2/http2stream_aborted.md new file mode 100644 index 00000000..fb8db063 --- /dev/null +++ b/http2/http2stream_aborted.md @@ -0,0 +1,9 @@ + + +* {boolean} + +Set to `true` if the `Http2Stream` instance was aborted abnormally. When set, +the `'aborted'` event will have been emitted. + diff --git a/http2/http2stream_additionalheaders_headers.md b/http2/http2stream_additionalheaders_headers.md new file mode 100644 index 00000000..41520ff6 --- /dev/null +++ b/http2/http2stream_additionalheaders_headers.md @@ -0,0 +1,8 @@ + + +* `headers` {HTTP/2 Headers Object} + +Sends an additional informational `HEADERS` frame to the connected HTTP/2 peer. + diff --git a/http2/http2stream_buffersize.md b/http2/http2stream_buffersize.md new file mode 100644 index 00000000..59cb78ca --- /dev/null +++ b/http2/http2stream_buffersize.md @@ -0,0 +1,8 @@ + +* {number} + +This property shows the number of characters currently buffered to be written. +See [`net.Socket.bufferSize`][] for details. + diff --git a/http2/http2stream_close_code_callback.md b/http2/http2stream_close_code_callback.md new file mode 100644 index 00000000..95f749f0 --- /dev/null +++ b/http2/http2stream_close_code_callback.md @@ -0,0 +1,12 @@ + + +* `code` {number} Unsigned 32-bit integer identifying the error code. + **Default:** `http2.constants.NGHTTP2_NO_ERROR` (`0x00`). +* `callback` {Function} An optional function registered to listen for the + `'close'` event. + +Closes the `Http2Stream` instance by sending an `RST_STREAM` frame to the +connected HTTP/2 peer. + diff --git a/http2/http2stream_closed.md b/http2/http2stream_closed.md new file mode 100644 index 00000000..94fb3fc8 --- /dev/null +++ b/http2/http2stream_closed.md @@ -0,0 +1,8 @@ + + +* {boolean} + +Set to `true` if the `Http2Stream` instance has been closed. + diff --git a/http2/http2stream_destroyed.md b/http2/http2stream_destroyed.md new file mode 100644 index 00000000..6477f9f2 --- /dev/null +++ b/http2/http2stream_destroyed.md @@ -0,0 +1,9 @@ + + +* {boolean} + +Set to `true` if the `Http2Stream` instance has been destroyed and is no longer +usable. + diff --git a/http2/http2stream_endafterheaders.md b/http2/http2stream_endafterheaders.md new file mode 100644 index 00000000..9cc9a92c --- /dev/null +++ b/http2/http2stream_endafterheaders.md @@ -0,0 +1,10 @@ + + +* {boolean} + +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. + diff --git a/http2/http2stream_headerssent.md b/http2/http2stream_headerssent.md new file mode 100644 index 00000000..d75edca3 --- /dev/null +++ b/http2/http2stream_headerssent.md @@ -0,0 +1,8 @@ + + +* {boolean} + +True if headers were sent, false otherwise (read-only). + diff --git a/http2/http2stream_lifecycle.md b/http2/http2stream_lifecycle.md new file mode 100644 index 00000000..8b137891 --- /dev/null +++ b/http2/http2stream_lifecycle.md @@ -0,0 +1 @@ + diff --git a/http2/http2stream_pending.md b/http2/http2stream_pending.md new file mode 100644 index 00000000..312f9d34 --- /dev/null +++ b/http2/http2stream_pending.md @@ -0,0 +1,9 @@ + + +* {boolean} + +Set to `true` if the `Http2Stream` instance has not yet been assigned a +numeric stream identifier. + diff --git a/http2/http2stream_priority_options.md b/http2/http2stream_priority_options.md new file mode 100644 index 00000000..78902f4f --- /dev/null +++ b/http2/http2stream_priority_options.md @@ -0,0 +1,19 @@ + + +* `options` {Object} + * `exclusive` {boolean} When `true` and `parent` identifies a parent Stream, + this stream is made the sole direct dependency of the parent, with + all other existing dependents made a dependent of this stream. **Default:** + `false`. + * `parent` {number} Specifies the numeric identifier of a stream this stream + is dependent on. + * `weight` {number} Specifies the relative dependency of a stream in relation + to other streams with the same `parent`. The value is a number between `1` + and `256` (inclusive). + * `silent` {boolean} When `true`, changes the priority locally without + sending a `PRIORITY` frame to the connected peer. + +Updates the priority for this `Http2Stream` instance. + diff --git a/http2/http2stream_pushallowed.md b/http2/http2stream_pushallowed.md new file mode 100644 index 00000000..47454809 --- /dev/null +++ b/http2/http2stream_pushallowed.md @@ -0,0 +1,11 @@ + + +* {boolean} + +Read-only property mapped to the `SETTINGS_ENABLE_PUSH` flag of the remote +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`. + diff --git a/http2/http2stream_pushstream_headers_options_callback.md b/http2/http2stream_pushstream_headers_options_callback.md new file mode 100644 index 00000000..cd24384f --- /dev/null +++ b/http2/http2stream_pushstream_headers_options_callback.md @@ -0,0 +1,44 @@ + + +* `headers` {HTTP/2 Headers Object} +* `options` {Object} + * `exclusive` {boolean} When `true` and `parent` identifies a parent Stream, + the created stream is made the sole direct dependency of the parent, with + all other existing dependents made a dependent of the newly created stream. + **Default:** `false`. + * `parent` {number} Specifies the numeric identifier of a stream the newly + created stream is dependent on. +* `callback` {Function} Callback that is called once the push stream has been + initiated. + * `err` {Error} + * `pushStream` {ServerHttp2Stream} The returned `pushStream` object. + * `headers` {HTTP/2 Headers Object} Headers object the `pushStream` was + initiated with. + +Initiates a push stream. The callback is invoked with the new `Http2Stream` +instance created for the push stream passed as the second argument, or an +`Error` passed as the first argument. + +```js +const http2 = require('http2'); +const server = http2.createServer(); +server.on('stream', (stream) => { + stream.respond({ ':status': 200 }); + stream.pushStream({ ':path': '/' }, (err, pushStream, headers) => { + if (err) throw err; + pushStream.respond({ ':status': 200 }); + pushStream.end('some pushed data'); + }); + stream.end('some data'); +}); +``` + +Setting the weight of a push stream is not allowed in the `HEADERS` frame. Pass +a `weight` value to `http2stream.priority` with the `silent` option set to +`true` to enable server-side bandwidth balancing between concurrent streams. + +Calling `http2stream.pushStream()` from within a pushed stream is not permitted +and will throw an error. + diff --git a/http2/http2stream_respond_headers_options.md b/http2/http2stream_respond_headers_options.md new file mode 100644 index 00000000..a0521ce3 --- /dev/null +++ b/http2/http2stream_respond_headers_options.md @@ -0,0 +1,42 @@ + + +* `headers` {HTTP/2 Headers Object} +* `options` {Object} + * `endStream` {boolean} Set to `true` to indicate that the response will not + include payload data. + * `waitForTrailers` {boolean} When `true`, the `Http2Stream` will emit the + `'wantTrailers'` event after the final `DATA` frame has been sent. + +```js +const http2 = require('http2'); +const server = http2.createServer(); +server.on('stream', (stream) => { + stream.respond({ ':status': 200 }); + stream.end('some data'); +}); +``` + +When the `options.waitForTrailers` option is set, the `'wantTrailers'` event +will be emitted immediately after queuing the last chunk of payload data to be +sent. The `http2stream.sendTrailers()` method can then be used to sent trailing +header fields to the peer. + +When `options.waitForTrailers` is set, the `Http2Stream` will not automatically +close when the final `DATA` frame is transmitted. User code must call either +`http2stream.sendTrailers()` or `http2stream.close()` to close the +`Http2Stream`. + +```js +const http2 = require('http2'); +const server = http2.createServer(); +server.on('stream', (stream) => { + stream.respond({ ':status': 200 }, { waitForTrailers: true }); + stream.on('wantTrailers', () => { + stream.sendTrailers({ ABC: 'some value to send' }); + }); + stream.end('some data'); +}); +``` + diff --git a/http2/http2stream_respondwithfd_fd_headers_options.md b/http2/http2stream_respondwithfd_fd_headers_options.md new file mode 100644 index 00000000..7308d956 --- /dev/null +++ b/http2/http2stream_respondwithfd_fd_headers_options.md @@ -0,0 +1,94 @@ + + +* `fd` {number} A readable file descriptor. +* `headers` {HTTP/2 Headers Object} +* `options` {Object} + * `statCheck` {Function} + * `waitForTrailers` {boolean} When `true`, the `Http2Stream` will emit the + `'wantTrailers'` event after the final `DATA` frame has been sent. + * `offset` {number} The offset position at which to begin reading. + * `length` {number} The amount of data from the fd to send. + +Initiates a response whose data is read from the given file descriptor. No +validation is performed on the given file descriptor. If an error occurs while +attempting to read data using the file descriptor, the `Http2Stream` will be +closed using an `RST_STREAM` frame using the standard `INTERNAL_ERROR` code. + +When used, the `Http2Stream` object's `Duplex` interface will be closed +automatically. + +```js +const http2 = require('http2'); +const fs = require('fs'); + +const server = http2.createServer(); +server.on('stream', (stream) => { + const fd = fs.openSync('/some/file', 'r'); + + const stat = fs.fstatSync(fd); + const headers = { + 'content-length': stat.size, + 'last-modified': stat.mtime.toUTCString(), + 'content-type': 'text/plain' + }; + stream.respondWithFD(fd, headers); + stream.on('close', () => fs.closeSync(fd)); +}); +``` + +The optional `options.statCheck` function may be specified to give user code +an opportunity to set additional content headers based on the `fs.Stat` details +of the given fd. If the `statCheck` function is provided, the +`http2stream.respondWithFD()` method will perform an `fs.fstat()` call to +collect details on the provided file descriptor. + +The `offset` and `length` options may be used to limit the response to a +specific range subset. This can be used, for instance, to support HTTP Range +requests. + +The file descriptor is not closed when the stream is closed, so it will need +to be closed manually once it is no longer needed. +Note that using the same file descriptor concurrently for multiple streams +is not supported and may result in data loss. Re-using a file descriptor +after a stream has finished is supported. + +When the `options.waitForTrailers` option is set, the `'wantTrailers'` event +will be emitted immediately after queuing the last chunk of payload data to be +sent. The `http2stream.sendTrailers()` method can then be used to sent trailing +header fields to the peer. + +When `options.waitForTrailers` is set, the `Http2Stream` will not automatically +close when the final `DATA` frame is transmitted. User code *must* call either +`http2stream.sendTrailers()` or `http2stream.close()` to close the +`Http2Stream`. + +```js +const http2 = require('http2'); +const fs = require('fs'); + +const server = http2.createServer(); +server.on('stream', (stream) => { + const fd = fs.openSync('/some/file', 'r'); + + const stat = fs.fstatSync(fd); + const headers = { + 'content-length': stat.size, + 'last-modified': stat.mtime.toUTCString(), + 'content-type': 'text/plain' + }; + stream.respondWithFD(fd, headers, { waitForTrailers: true }); + stream.on('wantTrailers', () => { + stream.sendTrailers({ ABC: 'some value to send' }); + }); + + stream.on('close', () => fs.closeSync(fd)); +}); +``` + diff --git a/http2/http2stream_respondwithfile_path_headers_options.md b/http2/http2stream_respondwithfile_path_headers_options.md new file mode 100644 index 00000000..50593088 --- /dev/null +++ b/http2/http2stream_respondwithfile_path_headers_options.md @@ -0,0 +1,113 @@ + + +* `path` {string|Buffer|URL} +* `headers` {HTTP/2 Headers Object} +* `options` {Object} + * `statCheck` {Function} + * `onError` {Function} Callback function invoked in the case of an + error before send. + * `waitForTrailers` {boolean} When `true`, the `Http2Stream` will emit the + `'wantTrailers'` event after the final `DATA` frame has been sent. + * `offset` {number} The offset position at which to begin reading. + * `length` {number} The amount of data from the fd to send. + +Sends a regular file as the response. The `path` must specify a regular file +or an `'error'` event will be emitted on the `Http2Stream` object. + +When used, the `Http2Stream` object's `Duplex` interface will be closed +automatically. + +The optional `options.statCheck` function may be specified to give user code +an opportunity to set additional content headers based on the `fs.Stat` details +of the given file: + +If an error occurs while attempting to read the file data, the `Http2Stream` +will be closed using an `RST_STREAM` frame using the standard `INTERNAL_ERROR` +code. If the `onError` callback is defined, then it will be called. Otherwise +the stream will be destroyed. + +Example using a file path: + +```js +const http2 = require('http2'); +const server = http2.createServer(); +server.on('stream', (stream) => { + function statCheck(stat, headers) { + headers['last-modified'] = stat.mtime.toUTCString(); + } + + function onError(err) { + if (err.code === 'ENOENT') { + stream.respond({ ':status': 404 }); + } else { + stream.respond({ ':status': 500 }); + } + stream.end(); + } + + stream.respondWithFile('/some/file', + { 'content-type': 'text/plain' }, + { statCheck, onError }); +}); +``` + +The `options.statCheck` function may also be used to cancel the send operation +by returning `false`. For instance, a conditional request may check the stat +results to determine if the file has been modified to return an appropriate +`304` response: + +```js +const http2 = require('http2'); +const server = http2.createServer(); +server.on('stream', (stream) => { + function statCheck(stat, headers) { + // Check the stat here... + stream.respond({ ':status': 304 }); + return false; // Cancel the send operation + } + stream.respondWithFile('/some/file', + { 'content-type': 'text/plain' }, + { statCheck }); +}); +``` + +The `content-length` header field will be automatically set. + +The `offset` and `length` options may be used to limit the response to a +specific range subset. This can be used, for instance, to support HTTP Range +requests. + +The `options.onError` function may also be used to handle all the errors +that could happen before the delivery of the file is initiated. The +default behavior is to destroy the stream. + +When the `options.waitForTrailers` option is set, the `'wantTrailers'` event +will be emitted immediately after queuing the last chunk of payload data to be +sent. The `http2stream.sendTrailers()` method can then be used to sent trailing +header fields to the peer. + +When `options.waitForTrailers` is set, the `Http2Stream` will not automatically +close when the final `DATA` frame is transmitted. User code must call either +`http2stream.sendTrailers()` or `http2stream.close()` to close the +`Http2Stream`. + +```js +const http2 = require('http2'); +const server = http2.createServer(); +server.on('stream', (stream) => { + stream.respondWithFile('/some/file', + { 'content-type': 'text/plain' }, + { waitForTrailers: true }); + stream.on('wantTrailers', () => { + stream.sendTrailers({ ABC: 'some value to send' }); + }); +}); +``` + diff --git a/http2/http2stream_rstcode.md b/http2/http2stream_rstcode.md new file mode 100644 index 00000000..2e9f3148 --- /dev/null +++ b/http2/http2stream_rstcode.md @@ -0,0 +1,11 @@ + + +* {number} + +Set to the `RST_STREAM` [error code][] reported when the `Http2Stream` is +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. + diff --git a/http2/http2stream_sendtrailers_headers.md b/http2/http2stream_sendtrailers_headers.md new file mode 100644 index 00000000..48154169 --- /dev/null +++ b/http2/http2stream_sendtrailers_headers.md @@ -0,0 +1,28 @@ + + +* `headers` {HTTP/2 Headers Object} + +Sends a trailing `HEADERS` frame to the connected HTTP/2 peer. This method +will cause the `Http2Stream` to be immediately closed and must only be +called after the `'wantTrailers'` event has been emitted. When sending a +request or sending a response, the `options.waitForTrailers` option must be set +in order to keep the `Http2Stream` open after the final `DATA` frame so that +trailers can be sent. + +```js +const http2 = require('http2'); +const server = http2.createServer(); +server.on('stream', (stream) => { + stream.respond(undefined, { waitForTrailers: true }); + stream.on('wantTrailers', () => { + stream.sendTrailers({ xyz: 'abc' }); + }); + stream.end('Hello World'); +}); +``` + +The HTTP/1 specification forbids trailers from containing HTTP/2 pseudo-header +fields (e.g. `':method'`, `':path'`, etc). + diff --git a/http2/http2stream_sentheaders.md b/http2/http2stream_sentheaders.md new file mode 100644 index 00000000..19826fdc --- /dev/null +++ b/http2/http2stream_sentheaders.md @@ -0,0 +1,8 @@ + + +* {HTTP/2 Headers Object} + +An object containing the outbound headers sent for this `Http2Stream`. + diff --git a/http2/http2stream_sentinfoheaders.md b/http2/http2stream_sentinfoheaders.md new file mode 100644 index 00000000..20fa930e --- /dev/null +++ b/http2/http2stream_sentinfoheaders.md @@ -0,0 +1,9 @@ + + +* {HTTP/2 Headers Object[]} + +An array of objects containing the outbound informational (additional) headers +sent for this `Http2Stream`. + diff --git a/http2/http2stream_senttrailers.md b/http2/http2stream_senttrailers.md new file mode 100644 index 00000000..1d556dca --- /dev/null +++ b/http2/http2stream_senttrailers.md @@ -0,0 +1,8 @@ + + +* {HTTP/2 Headers Object} + +An object containing the outbound trailers sent for this `HttpStream`. + diff --git a/http2/http2stream_session.md b/http2/http2stream_session.md new file mode 100644 index 00000000..d8d1bac3 --- /dev/null +++ b/http2/http2stream_session.md @@ -0,0 +1,9 @@ + + +* {Http2Session} + +A reference to the `Http2Session` instance that owns this `Http2Stream`. The +value will be `undefined` after the `Http2Stream` instance is destroyed. + diff --git a/http2/http2stream_settimeout_msecs_callback.md b/http2/http2stream_settimeout_msecs_callback.md new file mode 100644 index 00000000..4d53c0d8 --- /dev/null +++ b/http2/http2stream_settimeout_msecs_callback.md @@ -0,0 +1,17 @@ + + +* `msecs` {number} +* `callback` {Function} + +```js +const http2 = require('http2'); +const client = http2.connect('http://example.org:8000'); +const { NGHTTP2_CANCEL } = http2.constants; +const req = client.request({ ':path': '/' }); + +// Cancel the stream if there's no activity after 5 seconds +req.setTimeout(5000, () => req.close(NGHTTP2_CANCEL)); +``` + diff --git a/http2/http2stream_state.md b/http2/http2stream_state.md new file mode 100644 index 00000000..74b639aa --- /dev/null +++ b/http2/http2stream_state.md @@ -0,0 +1,21 @@ + +Provides miscellaneous information about the current state of the +`Http2Stream`. + +* {Object} + * `localWindowSize` {number} The number of bytes the connected peer may send + for this `Http2Stream` without receiving a `WINDOW_UPDATE`. + * `state` {number} A flag indicating the low-level current state of the + `Http2Stream` as determined by `nghttp2`. + * `localClose` {number} `true` if this `Http2Stream` has been closed locally. + * `remoteClose` {number} `true` if this `Http2Stream` has been closed + remotely. + * `sumDependencyWeight` {number} The sum weight of all `Http2Stream` + instances that depend on this `Http2Stream` as specified using + `PRIORITY` frames. + * `weight` {number} The priority weight of this `Http2Stream`. + +A current state of this `Http2Stream`. + diff --git a/api-docs/8af95f4c6766b2c26f46157a3b970b7af72e54b061a37f2a0eb5a601d181ecb2.md b/http2/http_2.md similarity index 100% rename from api-docs/8af95f4c6766b2c26f46157a3b970b7af72e54b061a37f2a0eb5a601d181ecb2.md rename to http2/http_2.md diff --git a/http2/invalid_character_handling_in_header_names_and_values.md b/http2/invalid_character_handling_in_header_names_and_values.md new file mode 100644 index 00000000..75f445d1 --- /dev/null +++ b/http2/invalid_character_handling_in_header_names_and_values.md @@ -0,0 +1,20 @@ + +The HTTP/2 implementation applies stricter handling of invalid characters in +HTTP header names and values than the HTTP/1 implementation. + +Header field names are *case-insensitive* and are transmitted over the wire +strictly as lower-case strings. The API provided by Node.js allows header +names to be set as mixed-case strings (e.g. `Content-Type`) but will convert +those to lower-case (e.g. `content-type`) upon transmission. + +Header field-names *must only* contain one or more of the following ASCII +characters: `a`-`z`, `A`-`Z`, `0`-`9`, `!`, `#`, `$`, `%`, `&`, `'`, `*`, `+`, +`-`, `.`, `^`, `_`, `` ` `` (backtick), `|`, and `~`. + +Using invalid characters within an HTTP header field name will cause the +stream to be closed with a protocol error being reported. + +Header field values are handled with more leniency but *should* not contain +new-line or carriage return characters and *should* be limited to US-ASCII +characters, per the requirements of the HTTP specification. + diff --git a/http2/push_streams_on_the_client.md b/http2/push_streams_on_the_client.md new file mode 100644 index 00000000..c85550ef --- /dev/null +++ b/http2/push_streams_on_the_client.md @@ -0,0 +1,19 @@ + +To receive pushed streams on the client, set a listener for the `'stream'` +event on the `ClientHttp2Session`: + +```js +const http2 = require('http2'); + +const client = http2.connect('http://localhost'); + +client.on('stream', (pushedStream, requestHeaders) => { + pushedStream.on('push', (responseHeaders) => { + // process response headers + }); + pushedStream.on('data', (chunk) => { /* handle pushed data */ }); +}); + +const req = client.request({ ':path': '/' }); +``` + diff --git a/http2/request_aborted.md b/http2/request_aborted.md new file mode 100644 index 00000000..74972eda --- /dev/null +++ b/http2/request_aborted.md @@ -0,0 +1,9 @@ + + +* {boolean} + +The `request.aborted` property will be `true` if the request has +been aborted. + diff --git a/http2/request_authority.md b/http2/request_authority.md new file mode 100644 index 00000000..70946058 --- /dev/null +++ b/http2/request_authority.md @@ -0,0 +1,9 @@ + + +* {string} + +The request authority pseudo header field. It can also be accessed via +`req.headers[':authority']`. + diff --git a/http2/request_destroy_error.md b/http2/request_destroy_error.md new file mode 100644 index 00000000..eeb6d715 --- /dev/null +++ b/http2/request_destroy_error.md @@ -0,0 +1,12 @@ + + +* `error` {Error} + +Calls `destroy()` on the [`Http2Stream`][] that received +the [`Http2ServerRequest`][]. If `error` is provided, an `'error'` event +is emitted and `error` is passed as an argument to any listeners on the event. + +It does nothing if the stream was already destroyed. + diff --git a/http2/request_headers.md b/http2/request_headers.md new file mode 100644 index 00000000..27594c97 --- /dev/null +++ b/http2/request_headers.md @@ -0,0 +1,32 @@ + + +* {Object} + +The request/response headers object. + +Key-value pairs of header names and values. Header names are lower-cased. + +```js +// Prints something like: +// +// { 'user-agent': 'curl/7.22.0', +// host: '127.0.0.1:8000', +// accept: '*/*' } +console.log(request.headers); +``` + +See [HTTP/2 Headers Object][]. + +In HTTP/2, the request path, hostname, protocol, and method are represented as +special headers prefixed with the `:` character (e.g. `':path'`). These special +headers will be included in the `request.headers` object. Care must be taken not +to inadvertently modify these special headers or errors may occur. For instance, +removing all headers from the request will cause errors to occur: + +```js +removeAllHeaders(request.headers); +assert(request.url); // Fails because the :path header has been removed +``` + diff --git a/http2/request_httpversion.md b/http2/request_httpversion.md new file mode 100644 index 00000000..10ab6d91 --- /dev/null +++ b/http2/request_httpversion.md @@ -0,0 +1,13 @@ + + +* {string} + +In case of server request, the HTTP version sent by the client. In the case of +client response, the HTTP version of the connected-to server. Returns +`'2.0'`. + +Also `message.httpVersionMajor` is the first integer and +`message.httpVersionMinor` is the second. + diff --git a/http2/request_method.md b/http2/request_method.md new file mode 100644 index 00000000..3b3b9105 --- /dev/null +++ b/http2/request_method.md @@ -0,0 +1,8 @@ + + +* {string} + +The request method as a string. Read-only. Examples: `'GET'`, `'DELETE'`. + diff --git a/http2/request_rawheaders.md b/http2/request_rawheaders.md new file mode 100644 index 00000000..c5883d05 --- /dev/null +++ b/http2/request_rawheaders.md @@ -0,0 +1,28 @@ + + +* {string[]} + +The raw request/response headers list exactly as they were received. + +Note that the keys and values are in the same list. It is *not* a +list of tuples. So, the even-numbered offsets are key values, and the +odd-numbered offsets are the associated values. + +Header names are not lowercased, and duplicates are not merged. + +```js +// Prints something like: +// +// [ 'user-agent', +// 'this is invalid because there can be only one', +// 'User-Agent', +// 'curl/7.22.0', +// 'Host', +// '127.0.0.1:8000', +// 'ACCEPT', +// '*/*' ] +console.log(request.rawHeaders); +``` + diff --git a/http2/request_rawtrailers.md b/http2/request_rawtrailers.md new file mode 100644 index 00000000..ec7155da --- /dev/null +++ b/http2/request_rawtrailers.md @@ -0,0 +1,9 @@ + + +* {string[]} + +The raw request/response trailer keys and values exactly as they were +received. Only populated at the `'end'` event. + diff --git a/http2/request_scheme.md b/http2/request_scheme.md new file mode 100644 index 00000000..b404604c --- /dev/null +++ b/http2/request_scheme.md @@ -0,0 +1,9 @@ + + +* {string} + +The request scheme pseudo header field indicating the scheme +portion of the target URL. + diff --git a/http2/request_settimeout_msecs_callback.md b/http2/request_settimeout_msecs_callback.md new file mode 100644 index 00000000..ca5720ff --- /dev/null +++ b/http2/request_settimeout_msecs_callback.md @@ -0,0 +1,17 @@ + + +* `msecs` {number} +* `callback` {Function} +* Returns: {http2.Http2ServerRequest} + +Sets the [`Http2Stream`]()'s timeout value to `msecs`. If a callback is +provided, then it is added as a listener on the `'timeout'` event on +the response object. + +If no `'timeout'` listener is added to the request, the response, or +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. + diff --git a/http2/request_socket.md b/http2/request_socket.md new file mode 100644 index 00000000..b86d94d5 --- /dev/null +++ b/http2/request_socket.md @@ -0,0 +1,25 @@ + + +* {net.Socket|tls.TLSSocket} + +Returns a `Proxy` object that acts as a `net.Socket` (or `tls.TLSSocket`) but +applies getters, setters, and methods based on HTTP/2 logic. + +`destroyed`, `readable`, and `writable` properties will be retrieved from and +set on `request.stream`. + +`destroy`, `emit`, `end`, `on` and `once` methods will be called on +`request.stream`. + +`setTimeout` method will be called on `request.stream.session`. + +`pause`, `read`, `resume`, and `write` will throw an error with code +`ERR_HTTP2_NO_SOCKET_MANIPULATION`. See [`Http2Session` and Sockets][] for +more information. + +All other interactions will be routed directly to the socket. With TLS support, +use [`request.socket.getPeerCertificate()`][] to obtain the client's +authentication details. + diff --git a/http2/request_stream.md b/http2/request_stream.md new file mode 100644 index 00000000..9669a50d --- /dev/null +++ b/http2/request_stream.md @@ -0,0 +1,8 @@ + + +* {Http2Stream} + +The [`Http2Stream`][] object backing the request. + diff --git a/http2/request_trailers.md b/http2/request_trailers.md new file mode 100644 index 00000000..0283b893 --- /dev/null +++ b/http2/request_trailers.md @@ -0,0 +1,8 @@ + + +* {Object} + +The request/response trailers object. Only populated at the `'end'` event. + diff --git a/http2/request_url.md b/http2/request_url.md new file mode 100644 index 00000000..5e5b1c65 --- /dev/null +++ b/http2/request_url.md @@ -0,0 +1,65 @@ + + +* {string} + +Request URL string. This contains only the URL that is +present in the actual HTTP request. If the request is: + +```txt +GET /status?name=ryan HTTP/1.1\r\n +Accept: text/plain\r\n +\r\n +``` + +Then `request.url` will be: + + +```js +'/status?name=ryan' +``` + +To parse the url into its parts `require('url').parse(request.url)` +can be used: + +```txt +$ 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', + 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`. + +```txt +$ 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' } +``` + diff --git a/http2/response_addtrailers_headers.md b/http2/response_addtrailers_headers.md new file mode 100644 index 00000000..a01bde5d --- /dev/null +++ b/http2/response_addtrailers_headers.md @@ -0,0 +1,12 @@ + + +* `headers` {Object} + +This method adds HTTP trailing headers (a header but at the end of the +message) to the response. + +Attempting to set a header field name or value that contains invalid characters +will result in a [`TypeError`][] being thrown. + diff --git a/http2/response_connection.md b/http2/response_connection.md new file mode 100644 index 00000000..095d02e3 --- /dev/null +++ b/http2/response_connection.md @@ -0,0 +1,8 @@ + + +* {net.Socket|tls.TLSSocket} + +See [`response.socket`][]. + diff --git a/http2/response_createpushresponse_headers_callback.md b/http2/response_createpushresponse_headers_callback.md new file mode 100644 index 00000000..7d643dd2 --- /dev/null +++ b/http2/response_createpushresponse_headers_callback.md @@ -0,0 +1,16 @@ + +* `headers` {HTTP/2 Headers Object} An object describing the headers +* `callback` {Function} Called once `http2stream.pushStream()` is finished, + or either when the attempt to create the pushed `Http2Stream` has failed or + has been rejected, or the state of `Http2ServerRequest` is closed prior to + calling the `http2stream.pushStream()` method + * `err` {Error} + * `stream` {ServerHttp2Stream} The newly-created `ServerHttp2Stream` object + +Call [`http2stream.pushStream()`][] with the given headers, and wrap the +given [`Http2Stream`] on a newly created `Http2ServerResponse` as the callback +parameter if successful. When `Http2ServerRequest` is closed, the callback is +called with an error `ERR_HTTP2_INVALID_STREAM`. + diff --git a/http2/response_end_data_encoding_callback.md b/http2/response_end_data_encoding_callback.md new file mode 100644 index 00000000..a52ac2c6 --- /dev/null +++ b/http2/response_end_data_encoding_callback.md @@ -0,0 +1,23 @@ + + +* `data` {string|Buffer} +* `encoding` {string} +* `callback` {Function} +* Returns: {this} + +This method signals to the server that all of the response headers and body +have been sent; that server should consider this message complete. +The method, `response.end()`, MUST be called on each response. + +If `data` is specified, it is equivalent to calling +[`response.write(data, encoding)`][] followed by `response.end(callback)`. + +If `callback` is specified, it will be called when the response stream +is finished. + diff --git a/http2/response_finished.md b/http2/response_finished.md new file mode 100644 index 00000000..cc47c215 --- /dev/null +++ b/http2/response_finished.md @@ -0,0 +1,9 @@ + + +* {boolean} + +Boolean value that indicates whether the response has completed. Starts +as `false`. After [`response.end()`][] executes, the value will be `true`. + diff --git a/http2/response_getheader_name.md b/http2/response_getheader_name.md new file mode 100644 index 00000000..df82e584 --- /dev/null +++ b/http2/response_getheader_name.md @@ -0,0 +1,14 @@ + + +* `name` {string} +* Returns: {string} + +Reads out a header that has already been queued but not sent to the client. +Note that the name is case insensitive. + +```js +const contentType = response.getHeader('content-type'); +``` + diff --git a/http2/response_getheadernames.md b/http2/response_getheadernames.md new file mode 100644 index 00000000..b4414032 --- /dev/null +++ b/http2/response_getheadernames.md @@ -0,0 +1,17 @@ + + +* Returns: {string[]} + +Returns an array containing the unique names of the current outgoing headers. +All header names are lowercase. + +```js +response.setHeader('Foo', 'bar'); +response.setHeader('Set-Cookie', ['foo=bar', 'bar=baz']); + +const headerNames = response.getHeaderNames(); +// headerNames === ['foo', 'set-cookie'] +``` + diff --git a/http2/response_getheaders.md b/http2/response_getheaders.md new file mode 100644 index 00000000..a855b886 --- /dev/null +++ b/http2/response_getheaders.md @@ -0,0 +1,25 @@ + + +* Returns: {Object} + +Returns a shallow copy of the current outgoing headers. Since a shallow copy +is used, array values may be mutated without additional calls to various +header-related http module methods. The keys of the returned object are the +header names and the values are the respective header values. All header names +are lowercase. + +The object returned by the `response.getHeaders()` method _does not_ +prototypically inherit from the JavaScript `Object`. This means that typical +`Object` methods such as `obj.toString()`, `obj.hasOwnProperty()`, and others +are not defined and *will not work*. + +```js +response.setHeader('Foo', 'bar'); +response.setHeader('Set-Cookie', ['foo=bar', 'bar=baz']); + +const headers = response.getHeaders(); +// headers === { foo: 'bar', 'set-cookie': ['foo=bar', 'bar=baz'] } +``` + diff --git a/http2/response_hasheader_name.md b/http2/response_hasheader_name.md new file mode 100644 index 00000000..4c139509 --- /dev/null +++ b/http2/response_hasheader_name.md @@ -0,0 +1,14 @@ + + +* `name` {string} +* Returns: {boolean} + +Returns `true` if the header identified by `name` is currently set in the +outgoing headers. Note that the header name matching is case-insensitive. + +```js +const hasContentType = response.hasHeader('content-type'); +``` + diff --git a/http2/response_headerssent.md b/http2/response_headerssent.md new file mode 100644 index 00000000..d75edca3 --- /dev/null +++ b/http2/response_headerssent.md @@ -0,0 +1,8 @@ + + +* {boolean} + +True if headers were sent, false otherwise (read-only). + diff --git a/http2/response_removeheader_name.md b/http2/response_removeheader_name.md new file mode 100644 index 00000000..237cf787 --- /dev/null +++ b/http2/response_removeheader_name.md @@ -0,0 +1,12 @@ + + +* `name` {string} + +Removes a header that has been queued for implicit sending. + +```js +response.removeHeader('Content-Encoding'); +``` + diff --git a/http2/response_senddate.md b/http2/response_senddate.md new file mode 100644 index 00000000..03fb9218 --- /dev/null +++ b/http2/response_senddate.md @@ -0,0 +1,12 @@ + + +* {boolean} + +When true, the Date header will be automatically generated and sent in +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. + diff --git a/http2/response_setheader_name_value.md b/http2/response_setheader_name_value.md new file mode 100644 index 00000000..6865de48 --- /dev/null +++ b/http2/response_setheader_name_value.md @@ -0,0 +1,38 @@ + + +* `name` {string} +* `value` {string|string[]} + +Sets a single header value for implicit headers. If this header already exists +in the to-be-sent headers, its value will be replaced. Use an array of strings +here to send multiple headers with the same name. + +```js +response.setHeader('Content-Type', 'text/html'); +``` + +or + +```js +response.setHeader('Set-Cookie', ['type=ninja', 'language=javascript']); +``` + +Attempting to set a header field name or value that contains invalid characters +will result in a [`TypeError`][] being thrown. + +When headers have been set with [`response.setHeader()`][], they will be merged +with any headers passed to [`response.writeHead()`][], with the headers passed +to [`response.writeHead()`][] given precedence. + +```js +// returns content-type = text/plain +const server = http2.createServer((req, res) => { + res.setHeader('Content-Type', 'text/html'); + res.setHeader('X-Foo', 'bar'); + res.writeHead(200, { 'Content-Type': 'text/plain' }); + res.end('ok'); +}); +``` + diff --git a/http2/response_settimeout_msecs_callback.md b/http2/response_settimeout_msecs_callback.md new file mode 100644 index 00000000..77f1c60d --- /dev/null +++ b/http2/response_settimeout_msecs_callback.md @@ -0,0 +1,17 @@ + + +* `msecs` {number} +* `callback` {Function} +* Returns: {http2.Http2ServerResponse} + +Sets the [`Http2Stream`]()'s timeout value to `msecs`. If a callback is +provided, then it is added as a listener on the `'timeout'` event on +the response object. + +If no `'timeout'` listener is added to the request, the response, or +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. + diff --git a/http2/response_socket.md b/http2/response_socket.md new file mode 100644 index 00000000..bec838bb --- /dev/null +++ b/http2/response_socket.md @@ -0,0 +1,32 @@ + + +* {net.Socket|tls.TLSSocket} + +Returns a `Proxy` object that acts as a `net.Socket` (or `tls.TLSSocket`) but +applies getters, setters, and methods based on HTTP/2 logic. + +`destroyed`, `readable`, and `writable` properties will be retrieved from and +set on `response.stream`. + +`destroy`, `emit`, `end`, `on` and `once` methods will be called on +`response.stream`. + +`setTimeout` method will be called on `response.stream.session`. + +`pause`, `read`, `resume`, and `write` will throw an error with code +`ERR_HTTP2_NO_SOCKET_MANIPULATION`. See [`Http2Session` and Sockets][] for +more information. + +All other interactions will be routed directly to the socket. + +```js +const http2 = require('http2'); +const server = http2.createServer((req, res) => { + const ip = req.socket.remoteAddress; + const port = req.socket.remotePort; + res.end(`Your IP address is ${ip} and your source port is ${port}.`); +}).listen(3000); +``` + diff --git a/http2/response_statuscode.md b/http2/response_statuscode.md new file mode 100644 index 00000000..cf36c898 --- /dev/null +++ b/http2/response_statuscode.md @@ -0,0 +1,17 @@ + + +* {number} + +When using implicit headers (not calling [`response.writeHead()`][] explicitly), +this property controls the status code that will be sent to the client when +the headers get flushed. + +```js +response.statusCode = 404; +``` + +After response header was sent to the client, this property indicates the +status code which was sent out. + diff --git a/http2/response_statusmessage.md b/http2/response_statusmessage.md new file mode 100644 index 00000000..97409276 --- /dev/null +++ b/http2/response_statusmessage.md @@ -0,0 +1,9 @@ + + +* {string} + +Status message is not supported by HTTP/2 (RFC7540 8.1.2.4). It returns +an empty string. + diff --git a/http2/response_stream.md b/http2/response_stream.md new file mode 100644 index 00000000..ec16da1d --- /dev/null +++ b/http2/response_stream.md @@ -0,0 +1,8 @@ + + +* {Http2Stream} + +The [`Http2Stream`][] object backing the response. + diff --git a/http2/response_write_chunk_encoding_callback.md b/http2/response_write_chunk_encoding_callback.md new file mode 100644 index 00000000..5655a77a --- /dev/null +++ b/http2/response_write_chunk_encoding_callback.md @@ -0,0 +1,37 @@ + + +* `chunk` {string|Buffer} +* `encoding` {string} +* `callback` {Function} +* Returns: {boolean} + +If this method is called and [`response.writeHead()`][] has not been called, +it will switch to implicit header mode and flush the implicit headers. + +This sends a chunk of the response body. This method may +be called multiple times to provide successive parts of the body. + +Note that in the `http` module, the response body is omitted when the +request is a HEAD request. Similarly, the `204` and `304` responses +_must not_ include a message body. + +`chunk` can be a string or a buffer. If `chunk` is a string, +the second parameter specifies how to encode it into a byte stream. +By default the `encoding` is `'utf8'`. `callback` will be called when this chunk +of data is flushed. + +This is the raw HTTP body and has nothing to do with higher-level multi-part +body encodings that may be used. + +The first time [`response.write()`][] is called, it will send the buffered +header information and the first chunk of the body to the client. The second +time [`response.write()`][] is called, Node.js assumes data will be streamed, +and sends the new data separately. That is, the response is buffered up to the +first chunk of the body. + +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. + diff --git a/http2/response_writecontinue.md b/http2/response_writecontinue.md new file mode 100644 index 00000000..8cf79b8d --- /dev/null +++ b/http2/response_writecontinue.md @@ -0,0 +1,8 @@ + + +Sends a status `100 Continue` to the client, indicating that the request body +should be sent. See the [`'checkContinue'`][] event on `Http2Server` and +`Http2SecureServer`. + diff --git a/http2/response_writehead_statuscode_statusmessage_headers.md b/http2/response_writehead_statuscode_statusmessage_headers.md new file mode 100644 index 00000000..3ff8b4ec --- /dev/null +++ b/http2/response_writehead_statuscode_statusmessage_headers.md @@ -0,0 +1,53 @@ + + +* `statusCode` {number} +* `statusMessage` {string} +* `headers` {Object} + +Sends a response header to the request. The status code is a 3-digit HTTP +status code, like `404`. The last argument, `headers`, are the response headers. + +For compatibility with [HTTP/1][], a human-readable `statusMessage` may be +passed as the second argument. However, because the `statusMessage` has no +meaning within HTTP/2, the argument will have no effect and a process warning +will be emitted. + +```js +const body = 'hello world'; +response.writeHead(200, { + 'Content-Length': Buffer.byteLength(body), + 'Content-Type': 'text/plain' }); +``` + +Note that Content-Length is given in bytes not characters. The +`Buffer.byteLength()` API may be used to determine the number of bytes in a +given encoding. On outbound messages, Node.js does not check if Content-Length +and the length of the body being transmitted are equal or not. However, when +receiving messages, Node.js will automatically reject messages when the +Content-Length does not match the actual payload size. + +This method may be called at most one time on a message before +[`response.end()`][] is called. + +If [`response.write()`][] or [`response.end()`][] are called before calling +this, the implicit/mutable headers will be calculated and call this function. + +When headers have been set with [`response.setHeader()`][], they will be merged +with any headers passed to [`response.writeHead()`][], with the headers passed +to [`response.writeHead()`][] given precedence. + +```js +// returns content-type = text/plain +const server = http2.createServer((req, res) => { + res.setHeader('Content-Type', 'text/html'); + res.setHeader('X-Foo', 'bar'); + res.writeHead(200, { 'Content-Type': 'text/plain' }); + res.end('ok'); +}); +``` + +Attempting to set a header field name or value that contains invalid characters +will result in a [`TypeError`][] being thrown. + diff --git a/http2/server_close_callback.md b/http2/server_close_callback.md new file mode 100644 index 00000000..9d943c08 --- /dev/null +++ b/http2/server_close_callback.md @@ -0,0 +1,11 @@ + +* `callback` {Function} + +Stops the server from accepting new connections. See [`net.Server.close()`][]. + +Note that this is not analogous to restricting new requests since HTTP/2 +connections are persistent. To achieve a similar graceful shutdown behavior, +consider also using [`http2session.close()`] on active sessions. + diff --git a/http2/server_close_callback_1.md b/http2/server_close_callback_1.md new file mode 100644 index 00000000..78949431 --- /dev/null +++ b/http2/server_close_callback_1.md @@ -0,0 +1,11 @@ + +* `callback` {Function} + +Stops the server from accepting new connections. See [`tls.Server.close()`][]. + +Note that this is not analogous to restricting new requests since HTTP/2 +connections are persistent. To achieve a similar graceful shutdown behavior, +consider also using [`http2session.close()`] on active sessions. + diff --git a/http2/server_settimeout_msecs_callback.md b/http2/server_settimeout_msecs_callback.md new file mode 100644 index 00000000..24ce4eb9 --- /dev/null +++ b/http2/server_settimeout_msecs_callback.md @@ -0,0 +1,17 @@ + + +* `msecs` {number} **Default:** `120000` (2 minutes) +* `callback` {Function} +* Returns: {Http2Server} + +Used to set the timeout value for http2 server requests, +and sets a callback function that is called when there is no activity +on the `Http2Server` after `msecs` milliseconds. + +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. + diff --git a/http2/server_settimeout_msecs_callback_1.md b/http2/server_settimeout_msecs_callback_1.md new file mode 100644 index 00000000..1761544d --- /dev/null +++ b/http2/server_settimeout_msecs_callback_1.md @@ -0,0 +1,17 @@ + + +* `msecs` {number} **Default:** `120000` (2 minutes) +* `callback` {Function} +* Returns: {Http2SecureServer} + +Used to set the timeout value for http2 secure server requests, +and sets a callback function that is called when there is no activity +on the `Http2SecureServer` after `msecs` milliseconds. + +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. + diff --git a/http2/server_side_example.md b/http2/server_side_example.md new file mode 100644 index 00000000..d922e5a1 --- /dev/null +++ b/http2/server_side_example.md @@ -0,0 +1,36 @@ + +The following illustrates a simple HTTP/2 server using the Core API. +Since there are no browsers known that support +[unencrypted HTTP/2][HTTP/2 Unencrypted], the use of +[`http2.createSecureServer()`][] is necessary when communicating +with browser clients. + +```js +const http2 = require('http2'); +const fs = require('fs'); + +const server = http2.createSecureServer({ + key: fs.readFileSync('localhost-privkey.pem'), + cert: fs.readFileSync('localhost-cert.pem') +}); +server.on('error', (err) => console.error(err)); + +server.on('stream', (stream, headers) => { + // stream is a Duplex + stream.respond({ + 'content-type': 'text/html', + ':status': 200 + }); + stream.end('

Hello World

'); +}); + +server.listen(8443); +``` + +To generate the certificate and key for this example, run: + +```bash +openssl req -x509 -newkey rsa:2048 -nodes -sha256 -subj '/CN=localhost' \ + -keyout localhost-privkey.pem -out localhost-cert.pem +``` + diff --git a/http2/serverhttp2session_altsvc_alt_originorstream.md b/http2/serverhttp2session_altsvc_alt_originorstream.md new file mode 100644 index 00000000..890851be --- /dev/null +++ b/http2/serverhttp2session_altsvc_alt_originorstream.md @@ -0,0 +1,47 @@ + + +* `alt` {string} A description of the alternative service configuration as + defined by [RFC 7838][]. +* `originOrStream` {number|string|URL|Object} Either a URL string specifying + the origin (or an `Object` with an `origin` property) or the numeric + identifier of an active `Http2Stream` as given by the `http2stream.id` + property. + +Submits an `ALTSVC` frame (as defined by [RFC 7838][]) to the connected client. + +```js +const http2 = require('http2'); + +const server = http2.createServer(); +server.on('session', (session) => { + // Set altsvc for origin https://example.org:80 + session.altsvc('h2=":8000"', 'https://example.org:80'); +}); + +server.on('stream', (stream) => { + // Set altsvc for a specific stream + stream.session.altsvc('h2=":8000"', stream.id); +}); +``` + +Sending an `ALTSVC` frame with a specific stream ID indicates that the alternate +service is associated with the origin of the given `Http2Stream`. + +The `alt` and origin string *must* contain only ASCII bytes and are +strictly interpreted as a sequence of ASCII bytes. The special value `'clear'` +may be passed to clear any previously set alternative service for a given +domain. + +When a string is passed for the `originOrStream` argument, it will be parsed as +a URL and the origin will be derived. For instance, the origin for the +HTTP URL `'https://example.org/foo/bar'` is the ASCII string +`'https://example.org'`. An error will be thrown if either the given string +cannot be parsed as a URL or if a valid origin cannot be derived. + +A `URL` object, or any object with an `origin` property, may be passed as +`originOrStream`, in which case the value of the `origin` property will be +used. The value of the `origin` property *must* be a properly serialized +ASCII origin. + diff --git a/http2/serverhttp2session_origin_origins.md b/http2/serverhttp2session_origin_origins.md new file mode 100644 index 00000000..9c7d4499 --- /dev/null +++ b/http2/serverhttp2session_origin_origins.md @@ -0,0 +1,49 @@ + + +* `origins` { string | URL | Object } One or more URL Strings passed as + separate arguments. + +Submits an `ORIGIN` frame (as defined by [RFC 8336][]) to the connected client +to advertise the set of origins for which the server is capable of providing +authoritative responses. + +```js +const http2 = require('http2'); +const options = getSecureOptionsSomehow(); +const server = http2.createSecureServer(options); +server.on('stream', (stream) => { + stream.respond(); + stream.end('ok'); +}); +server.on('session', (session) => { + session.origin('https://example.com', 'https://example.org'); +}); +``` + +When a string is passed as an `origin`, it will be parsed as a URL and the +origin will be derived. For instance, the origin for the HTTP URL +`'https://example.org/foo/bar'` is the ASCII string +`'https://example.org'`. An error will be thrown if either the given string +cannot be parsed as a URL or if a valid origin cannot be derived. + +A `URL` object, or any object with an `origin` property, may be passed as +an `origin`, in which case the value of the `origin` property will be +used. The value of the `origin` property *must* be a properly serialized +ASCII origin. + +Alternatively, the `origins` option may be used when creating a new HTTP/2 +server using the `http2.createSecureServer()` method: + +```js +const http2 = require('http2'); +const options = getSecureOptionsSomehow(); +options.origins = ['https://example.com', 'https://example.org']; +const server = http2.createSecureServer(options); +server.on('stream', (stream) => { + stream.respond(); + stream.end('ok'); +}); +``` + diff --git a/http2/settings_object.md b/http2/settings_object.md new file mode 100644 index 00000000..ef408e4b --- /dev/null +++ b/http2/settings_object.md @@ -0,0 +1,41 @@ + +The `http2.getDefaultSettings()`, `http2.getPackedSettings()`, +`http2.createServer()`, `http2.createSecureServer()`, +`http2session.settings()`, `http2session.localSettings`, and +`http2session.remoteSettings` APIs either return or receive as input an +object that defines configuration settings for an `Http2Session` object. +These objects are ordinary JavaScript objects containing the following +properties. + +* `headerTableSize` {number} Specifies the maximum number of bytes used for + 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. +* `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`. +* `maxFrameSize` {number} Specifies the size of the largest frame payload. + The minimum allowed value is 16,384. The maximum allowed value + is 224-1. **Default:** `16,384 bytes`. +* `maxConcurrentStreams` {number} Specifies the maximum number of concurrent + streams permitted on an `Http2Session`. There is no default value which + implies, at least theoretically, 231-1 streams may be open + concurrently at any given time in an `Http2Session`. The minimum value + is 0. The maximum allowed value is 231-1. +* `maxHeaderListSize` {number} Specifies the maximum size (uncompressed octets) + of header list that will be accepted. The minimum allowed value is 0. The + maximum allowed value is 232-1. **Default:** `65535`. +* `enableConnectProtocol`{boolean} Specifies `true` if the "Extended Connect + 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. + +All additional properties on the settings object are ignored. + diff --git a/http2/specifying_alternative_services.md b/http2/specifying_alternative_services.md new file mode 100644 index 00000000..f2c7e4e5 --- /dev/null +++ b/http2/specifying_alternative_services.md @@ -0,0 +1,18 @@ + +The format of the `alt` parameter is strictly defined by [RFC 7838][] as an +ASCII string containing a comma-delimited list of "alternative" protocols +associated with a specific host and port. + +For example, the value `'h2="example.org:81"'` indicates that the HTTP/2 +protocol is available on the host `'example.org'` on TCP/IP port 81. The +host and port *must* be contained within the quote (`"`) characters. + +Multiple alternatives may be specified, for instance: `'h2="example.org:81", +h2=":82"'`. + +The protocol identifier (`'h2'` in the examples) may be any valid +[ALPN Protocol ID][]. + +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. + diff --git a/http2/supporting_the_connect_method.md b/http2/supporting_the_connect_method.md new file mode 100644 index 00000000..2c88d826 --- /dev/null +++ b/http2/supporting_the_connect_method.md @@ -0,0 +1,75 @@ + +The `CONNECT` method is used to allow an HTTP/2 server to be used as a proxy +for TCP/IP connections. + +A simple TCP Server: +```js +const net = require('net'); + +const server = net.createServer((socket) => { + let name = ''; + socket.setEncoding('utf8'); + socket.on('data', (chunk) => name += chunk); + socket.on('end', () => socket.end(`hello ${name}`)); +}); + +server.listen(8000); +``` + +An HTTP/2 CONNECT proxy: + +```js +const http2 = require('http2'); +const { NGHTTP2_REFUSED_STREAM } = http2.constants; +const net = require('net'); + +const proxy = http2.createServer(); +proxy.on('stream', (stream, headers) => { + if (headers[':method'] !== 'CONNECT') { + // Only accept CONNECT requests + stream.close(NGHTTP2_REFUSED_STREAM); + return; + } + const auth = new URL(`tcp://${headers[':authority']}`); + // It's a very good idea to verify that hostname and port are + // things this proxy should be connecting to. + const socket = net.connect(auth.port, auth.hostname, () => { + stream.respond(); + socket.pipe(stream); + stream.pipe(socket); + }); + socket.on('error', (error) => { + stream.close(http2.constants.NGHTTP2_CONNECT_ERROR); + }); +}); + +proxy.listen(8001); +``` + +An HTTP/2 CONNECT client: + +```js +const http2 = require('http2'); + +const client = http2.connect('http://localhost:8001'); + +// Must not specify the ':path' and ':scheme' headers +// for CONNECT requests or an error will be thrown. +const req = client.request({ + ':method': 'CONNECT', + ':authority': `localhost:${port}` +}); + +req.on('response', (headers) => { + console.log(headers[http2.constants.HTTP2_HEADER_STATUS]); +}); +let data = ''; +req.setEncoding('utf8'); +req.on('data', (chunk) => data += chunk); +req.on('end', () => { + console.log(`The server says: ${data}`); + client.close(); +}); +req.end('Jane'); +``` + diff --git a/http2/the_extended_connect_protocol.md b/http2/the_extended_connect_protocol.md new file mode 100644 index 00000000..6a6c4e58 --- /dev/null +++ b/http2/the_extended_connect_protocol.md @@ -0,0 +1,29 @@ + +[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` +method as a tunnel for other communication protocols (such as WebSockets). + +The use of the Extended CONNECT Protocol is enabled by HTTP/2 servers by using +the `enableConnectProtocol` setting: + +```js +const http2 = require('http2'); +const settings = { enableConnectProtocol: true }; +const server = http2.createServer({ settings }); +``` + +Once the client receives the `SETTINGS` frame from the server indicating that +the extended CONNECT may be used, it may send `CONNECT` requests that use the +`':protocol'` HTTP/2 pseudo-header: + +```js +const http2 = require('http2'); +const client = http2.connect('http://localhost:8080'); +client.on('remoteSettings', (settings) => { + if (settings.enableConnectProtocol) { + const req = client.request({ ':method': 'CONNECT', ':protocol': 'foo' }); + // ... + } +}); +``` + diff --git a/http2/using_options_selectpadding.md b/http2/using_options_selectpadding.md new file mode 100644 index 00000000..f2b37ce4 --- /dev/null +++ b/http2/using_options_selectpadding.md @@ -0,0 +1,23 @@ + +When `options.paddingStrategy` is equal to +`http2.constants.PADDING_STRATEGY_CALLBACK`, the HTTP/2 implementation will +consult the `options.selectPadding()` callback function, if provided, to +determine the specific amount of padding to use per `HEADERS` and `DATA` frame. + +The `options.selectPadding()` function receives two numeric arguments, +`frameLen` and `maxFrameLen` and must return a number `N` such that +`frameLen <= N <= maxFrameLen`. + +```js +const http2 = require('http2'); +const server = http2.createServer({ + paddingStrategy: http2.constants.PADDING_STRATEGY_CALLBACK, + selectPadding(frameLen, maxFrameLen) { + return maxFrameLen; + } +}); +``` + +The `options.selectPadding()` function is invoked once for *every* `HEADERS` and +`DATA` frame. This has a definite noticeable impact on performance. + diff --git a/api-docs/aaa7e5ca9d0bb0b0a8aeb9d4a03259bafc3643f880d17d33e8d2f45629e90056.md b/https/class_https_agent.md similarity index 100% rename from api-docs/aaa7e5ca9d0bb0b0a8aeb9d4a03259bafc3643f880d17d33e8d2f45629e90056.md rename to https/class_https_agent.md diff --git a/api-docs/98ca4006cbdac3566ebcba56194280d2bddac44b8e42359b3e34f789694b77d1.md b/https/class_https_server.md similarity index 100% rename from api-docs/98ca4006cbdac3566ebcba56194280d2bddac44b8e42359b3e34f789694b77d1.md rename to https/class_https_server.md diff --git a/api-docs/ead806d292a605e0521b93fa58434c12a430f5357d1998562642ad4048bb9f9d.md b/https/https.md similarity index 100% rename from api-docs/ead806d292a605e0521b93fa58434c12a430f5357d1998562642ad4048bb9f9d.md rename to https/https.md diff --git a/api-docs/f4c0cf712b6d0608533afbcbdf7481ea5f4be3b711d19745d512d2c78b56c92e.md b/https/https_createserver_options_requestlistener.md similarity index 100% rename from api-docs/f4c0cf712b6d0608533afbcbdf7481ea5f4be3b711d19745d512d2c78b56c92e.md rename to https/https_createserver_options_requestlistener.md diff --git a/api-docs/ef0f3572dedf72037ab8c6e06109142e4f58c12289ea5df9401219e968e29344.md b/https/https_get_options_callback.md similarity index 100% rename from api-docs/ef0f3572dedf72037ab8c6e06109142e4f58c12289ea5df9401219e968e29344.md rename to https/https_get_options_callback.md diff --git a/api-docs/ee777f7205144f9b6addd4d167e7cde92d96b6a7a57c62710f77c290ca3e7dd6.md b/https/https_get_url_options_callback.md similarity index 100% rename from api-docs/ee777f7205144f9b6addd4d167e7cde92d96b6a7a57c62710f77c290ca3e7dd6.md rename to https/https_get_url_options_callback.md diff --git a/api-docs/fecbcdabec551f491adc89ef70a25213b1f98423996487c1b9dc5730d84ea56d.md b/https/https_globalagent.md similarity index 100% rename from api-docs/fecbcdabec551f491adc89ef70a25213b1f98423996487c1b9dc5730d84ea56d.md rename to https/https_globalagent.md diff --git a/api-docs/f2b9655f8754b467b5de0d71d4868f4cdc0dfb60a17f0c48555c4a1bde97f28b.md b/https/https_request_options_callback.md similarity index 100% rename from api-docs/f2b9655f8754b467b5de0d71d4868f4cdc0dfb60a17f0c48555c4a1bde97f28b.md rename to https/https_request_options_callback.md diff --git a/api-docs/9726adbd6932c36947e96c84aaec2a185488cdf2928139f67f38233051d18c74.md b/https/https_request_url_options_callback.md similarity index 100% rename from api-docs/9726adbd6932c36947e96c84aaec2a185488cdf2928139f67f38233051d18c74.md rename to https/https_request_url_options_callback.md diff --git a/api-docs/b76f1af153dd1239bad0510a9f637718b878bee73122027ea8b65297b79ebfa0.md b/https/new_agent_options.md similarity index 100% rename from api-docs/b76f1af153dd1239bad0510a9f637718b878bee73122027ea8b65297b79ebfa0.md rename to https/new_agent_options.md diff --git a/api-docs/1887e833ad585b57276859acb3ade424ba21aa51fe90cb799c60131c530394a1.md b/https/server_close_callback.md similarity index 100% rename from api-docs/1887e833ad585b57276859acb3ade424ba21aa51fe90cb799c60131c530394a1.md rename to https/server_close_callback.md diff --git a/api-docs/e7058f3a5547a20227857a47536a317563dcd9f509345b8906c5e328630cf4a9.md b/https/server_headerstimeout.md similarity index 100% rename from api-docs/e7058f3a5547a20227857a47536a317563dcd9f509345b8906c5e328630cf4a9.md rename to https/server_headerstimeout.md diff --git a/api-docs/8b2ff1f9c54e1fbae4c3a68c41cb5eff2bd231f59452ac0cfa9a728e1fe098c6.md b/https/server_keepalivetimeout.md similarity index 100% rename from api-docs/8b2ff1f9c54e1fbae4c3a68c41cb5eff2bd231f59452ac0cfa9a728e1fe098c6.md rename to https/server_keepalivetimeout.md diff --git a/api-docs/2fd72a0b848f780892dd27b2525a5aea01b89197c49319d82b91e458451dbc4a.md b/https/server_listen.md similarity index 100% rename from api-docs/2fd72a0b848f780892dd27b2525a5aea01b89197c49319d82b91e458451dbc4a.md rename to https/server_listen.md diff --git a/api-docs/6f79c6edf794f667dbb04099bc03588d533b5d8bd11168468aadeea11d2e48a3.md b/https/server_maxheaderscount.md similarity index 100% rename from api-docs/6f79c6edf794f667dbb04099bc03588d533b5d8bd11168468aadeea11d2e48a3.md rename to https/server_maxheaderscount.md diff --git a/api-docs/8db056ca6ba916bedda766e241ed7651c3ca72da811315664870ad94ef437299.md b/https/server_settimeout_msecs_callback.md similarity index 100% rename from api-docs/8db056ca6ba916bedda766e241ed7651c3ca72da811315664870ad94ef437299.md rename to https/server_settimeout_msecs_callback.md diff --git a/api-docs/35dd71ff5865252df3e92207ce0371dddb56ee13a2a5d19e505e144ae0b4e284.md b/https/server_timeout.md similarity index 100% rename from api-docs/35dd71ff5865252df3e92207ce0371dddb56ee13a2a5d19e505e144ae0b4e284.md rename to https/server_timeout.md diff --git a/inspector/class_inspector_session.md b/inspector/class_inspector_session.md new file mode 100644 index 00000000..756f0e9c --- /dev/null +++ b/inspector/class_inspector_session.md @@ -0,0 +1,4 @@ + +The `inspector.Session` is used for dispatching messages to the V8 inspector +back-end and receiving message responses and notifications. + diff --git a/inspector/constructor_new_inspector_session.md b/inspector/constructor_new_inspector_session.md new file mode 100644 index 00000000..b84b4948 --- /dev/null +++ b/inspector/constructor_new_inspector_session.md @@ -0,0 +1,10 @@ + + +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. + +`inspector.Session` is an [`EventEmitter`][] with the following events: + diff --git a/api-docs/ce8825a92b1baf182696ca8759a7037a2507ed73d95658136a71dedb94c12f6b.md b/inspector/cpu_profiler.md similarity index 61% rename from api-docs/ce8825a92b1baf182696ca8759a7037a2507ed73d95658136a71dedb94c12f6b.md rename to inspector/cpu_profiler.md index 0c8e152c..1e601843 100644 --- a/api-docs/ce8825a92b1baf182696ca8759a7037a2507ed73d95658136a71dedb94c12f6b.md +++ b/inspector/cpu_profiler.md @@ -1,6 +1,5 @@ -Apart from the debugger, various V8 Profilers are available through the DevTools -protocol. Here's a simple example showing how to use the [CPU profiler][]: +Here's an example showing how to use the [CPU Profiler][]: ```js const inspector = require('inspector'); @@ -10,11 +9,11 @@ session.connect(); session.post('Profiler.enable', () => { session.post('Profiler.start', () => { - // invoke business logic under measurement here... + // Invoke business logic under measurement here... // some time later... session.post('Profiler.stop', (err, { profile }) => { - // write profile to disk, upload, etc. + // Write profile to disk, upload, etc. if (!err) { fs.writeFileSync('./profile.cpuprofile', JSON.stringify(profile)); } @@ -23,8 +22,3 @@ session.post('Profiler.enable', () => { }); ``` - - - - - diff --git a/inspector/event_inspectornotification.md b/inspector/event_inspectornotification.md new file mode 100644 index 00000000..f079e1d6 --- /dev/null +++ b/inspector/event_inspectornotification.md @@ -0,0 +1,16 @@ + + +* {Object} The notification message object + +Emitted when any notification from the V8 Inspector is received. + +```js +session.on('inspectorNotification', (message) => console.log(message.method)); +// Debugger.paused +// Debugger.resumed +``` + +It is also possible to subscribe only to notifications with specific method: + diff --git a/inspector/event_lt_inspector_protocol_method_gt.md b/inspector/event_lt_inspector_protocol_method_gt.md new file mode 100644 index 00000000..fe7fc241 --- /dev/null +++ b/inspector/event_lt_inspector_protocol_method_gt.md @@ -0,0 +1,20 @@ + + +* {Object} The notification message object + +Emitted when an inspector notification is received that has its method field set +to the `` value. + +The following snippet installs a listener on the [`'Debugger.paused'`][] +event, and prints the reason for program suspension whenever program +execution is suspended (through breakpoints, for example): + +```js +session.on('Debugger.paused', ({ params }) => { + console.log(params.hitBreakpoints); +}); +// [ '/the/file/that/has/the/breakpoint.js:11:0' ] +``` + diff --git a/inspector/example_usage.md b/inspector/example_usage.md new file mode 100644 index 00000000..1d9e9267 --- /dev/null +++ b/inspector/example_usage.md @@ -0,0 +1,4 @@ + +Apart from the debugger, various V8 Profilers are available through the DevTools +protocol. + diff --git a/inspector/heap_profiler.md b/inspector/heap_profiler.md new file mode 100644 index 00000000..6abba380 --- /dev/null +++ b/inspector/heap_profiler.md @@ -0,0 +1,29 @@ + +Here's an example showing how to use the [Heap Profiler][]: + +```js +const inspector = require('inspector'); +const fs = require('fs'); +const session = new inspector.Session(); + +const fd = fs.openSync('profile.heapsnapshot', 'w'); + +session.connect(); + +session.on('HeapProfiler.addHeapSnapshotChunk', (m) => { + fs.writeSync(fd, m.params.chunk); +}); + +session.post('HeapProfiler.takeHeapSnapshot', null, (err, r) => { + console.log('Runtime.takeHeapSnapshot done:', err, r); + session.disconnect(); + fs.closeSync(fd); +}); +``` + + + + + + + diff --git a/inspector/inspector.md b/inspector/inspector.md new file mode 100644 index 00000000..832d867c --- /dev/null +++ b/inspector/inspector.md @@ -0,0 +1,13 @@ + + + +> Stability: 1 - Experimental + +The `inspector` module provides an API for interacting with the V8 inspector. + +It can be accessed using: + +```js +const inspector = require('inspector'); +``` + diff --git a/inspector/inspector_close.md b/inspector/inspector_close.md new file mode 100644 index 00000000..87d9c936 --- /dev/null +++ b/inspector/inspector_close.md @@ -0,0 +1,3 @@ + +Deactivate the inspector. Blocks until there are no active connections. + diff --git a/inspector/inspector_console.md b/inspector/inspector_console.md new file mode 100644 index 00000000..d29e90cb --- /dev/null +++ b/inspector/inspector_console.md @@ -0,0 +1,10 @@ + +* {Object} An object to send messages to the remote inspector console. + +```js +require('inspector').console.log('a message'); +``` + +The inspector console does not have API parity with Node.js +console. + diff --git a/inspector/inspector_open_port_host_wait.md b/inspector/inspector_open_port_host_wait.md new file mode 100644 index 00000000..8690af71 --- /dev/null +++ b/inspector/inspector_open_port_host_wait.md @@ -0,0 +1,18 @@ + +* `port` {number} Port to listen on for inspector connections. Optional. + **Default:** what was specified on the CLI. +* `host` {string} Host to listen on for inspector connections. Optional. + **Default:** what was specified on the CLI. +* `wait` {boolean} Block until a client has connected. Optional. + **Default:** `false`. + +Activate inspector on host and port. Equivalent to `node +--inspect=[[host:]port]`, but can be done programmatically after node has +started. + +If wait is `true`, will block until a client has connected to the inspect port +and flow control has been passed to the debugger client. + +See the [security warning](cli.html#inspector_security) regarding the `host` +parameter usage. + diff --git a/inspector/inspector_url.md b/inspector/inspector_url.md new file mode 100644 index 00000000..8817376f --- /dev/null +++ b/inspector/inspector_url.md @@ -0,0 +1,5 @@ + +* Returns: {string|undefined} + +Return the URL of the active inspector, or `undefined` if there is none. + diff --git a/inspector/inspector_waitfordebugger.md b/inspector/inspector_waitfordebugger.md new file mode 100644 index 00000000..90f1fa9d --- /dev/null +++ b/inspector/inspector_waitfordebugger.md @@ -0,0 +1,9 @@ + + +Blocks until a client (existing or connected later) has sent +`Runtime.runIfWaitingForDebugger` command. + +An exception will be thrown if there is no active inspector. + diff --git a/inspector/session_connect.md b/inspector/session_connect.md new file mode 100644 index 00000000..c6cb1d49 --- /dev/null +++ b/inspector/session_connect.md @@ -0,0 +1,8 @@ + + +Connects a session to the inspector back-end. An exception will be thrown +if there is already a connected session established either through the API or by +a front-end connected to the Inspector WebSocket port. + diff --git a/inspector/session_disconnect.md b/inspector/session_disconnect.md new file mode 100644 index 00000000..dcb4ce2e --- /dev/null +++ b/inspector/session_disconnect.md @@ -0,0 +1,9 @@ + + +Immediately close the session. All pending message callbacks will be called +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. + diff --git a/inspector/session_post_method_params_callback.md b/inspector/session_post_method_params_callback.md new file mode 100644 index 00000000..b0fa102d --- /dev/null +++ b/inspector/session_post_method_params_callback.md @@ -0,0 +1,26 @@ + + +* `method` {string} +* `params` {Object} +* `callback` {Function} + +Posts a message to the inspector back-end. `callback` will be notified when +a response is received. `callback` is a function that accepts two optional +arguments - error and message-specific result. + +```js +session.post('Runtime.evaluate', { expression: '2 + 2' }, + (error, { result }) => console.log(result)); +// Output: { type: 'number', value: 4, description: '4' } +``` + +The latest version of the V8 inspector protocol is published on the +[Chrome DevTools Protocol Viewer][]. + +Node.js inspector supports all the Chrome DevTools Protocol domains declared +by V8. Chrome DevTools Protocol domain provides an interface for interacting +with one of the runtime agents used to inspect the application state and listen +to the run-time events. + diff --git a/intl/build_with_a_pre_installed_icu_system_icu.md b/intl/build_with_a_pre_installed_icu_system_icu.md new file mode 100644 index 00000000..a919aa91 --- /dev/null +++ b/intl/build_with_a_pre_installed_icu_system_icu.md @@ -0,0 +1,13 @@ + +Node.js can link against an ICU build already installed on the system. In fact, +most Linux distributions already come with ICU installed, and this option would +make it possible to reuse the same set of data used by other components in the +OS. + +Functionalities that only require the ICU library itself, such as +[`String.prototype.normalize()`][] and the [WHATWG URL parser][], are fully +supported under `system-icu`. Features that require ICU locale data in +addition, such as [`Intl.DateTimeFormat`][] *may* be fully or partially +supported, depending on the completeness of the ICU data installed on the +system. + diff --git a/api-docs/bb621fde38ee0d8cbf62d7fe0c6462349c1ff6e0ec32e31ae46fc6c9651957b9.md b/intl/detecting_internationalization_support.md similarity index 100% rename from api-docs/bb621fde38ee0d8cbf62d7fe0c6462349c1ff6e0ec32e31ae46fc6c9651957b9.md rename to intl/detecting_internationalization_support.md diff --git a/intl/disable_all_internationalization_features_none.md b/intl/disable_all_internationalization_features_none.md new file mode 100644 index 00000000..211a5d5e --- /dev/null +++ b/intl/disable_all_internationalization_features_none.md @@ -0,0 +1,4 @@ + +If this option is chosen, most internationalization features mentioned above +will be **unavailable** in the resulting `node` binary. + diff --git a/intl/embed_a_limited_set_of_icu_data_small_icu.md b/intl/embed_a_limited_set_of_icu_data_small_icu.md new file mode 100644 index 00000000..5cc58195 --- /dev/null +++ b/intl/embed_a_limited_set_of_icu_data_small_icu.md @@ -0,0 +1,26 @@ + +This option makes the resulting binary link against the ICU library statically, +and includes a subset of ICU data (typically only the English locale) within +the `node` executable. + +Functionalities that only require the ICU library itself, such as +[`String.prototype.normalize()`][] and the [WHATWG URL parser][], are fully +supported under `small-icu`. Features that require ICU locale data in addition, +such as [`Intl.DateTimeFormat`][], generally only work with the English locale: + +```js +const january = new Date(9e8); +const english = new Intl.DateTimeFormat('en', { month: 'long' }); +const spanish = new Intl.DateTimeFormat('es', { month: 'long' }); + +console.log(english.format(january)); +// Prints "January" +console.log(spanish.format(january)); +// Prints "M01" on small-icu +// Should print "enero" +``` + +This mode provides a good balance between features and binary size, and it is +the default behavior if no `--with-intl` flag is passed. The official binaries +are also built in this mode. + diff --git a/intl/embed_the_entire_icu_full_icu.md b/intl/embed_the_entire_icu_full_icu.md new file mode 100644 index 00000000..c686633d --- /dev/null +++ b/intl/embed_the_entire_icu_full_icu.md @@ -0,0 +1,6 @@ + +This option makes the resulting binary link against ICU statically and include +a full set of ICU data. A binary created this way has no further external +dependencies and supports all locales, but might be rather large. See +[BUILDING.md][BUILDING.md#full-icu] on how to compile a binary using this mode. + diff --git a/intl/internationalization_support.md b/intl/internationalization_support.md new file mode 100644 index 00000000..471d7d86 --- /dev/null +++ b/intl/internationalization_support.md @@ -0,0 +1,31 @@ + + + + +Node.js has many features that make it easier to write internationalized +programs. Some of them are: + +- Locale-sensitive or Unicode-aware functions in the [ECMAScript Language + Specification][ECMA-262]: + - [`String.prototype.normalize()`][] + - [`String.prototype.toLowerCase()`][] + - [`String.prototype.toUpperCase()`][] +- All functionality described in the [ECMAScript Internationalization API + Specification][ECMA-402] (aka ECMA-402): + - [`Intl`][] object + - Locale-sensitive methods like [`String.prototype.localeCompare()`][] and + [`Date.prototype.toLocaleString()`][] +- The [WHATWG URL parser][]'s [internationalized domain names][] (IDNs) support +- [`require('buffer').transcode()`][] +- More accurate [REPL][] line editing +- [`require('util').TextDecoder`][] +- [`RegExp` Unicode Property Escapes][] + +Node.js (and its underlying V8 engine) uses [ICU][] to implement these features +in native C/C++ code. However, some of them require a very large ICU data file +in order to support all locales of the world. Because it is expected that most +Node.js users will make use of only a small portion of ICU functionality, only +a subset of the full ICU data set is provided by Node.js by default. Several +options are provided for customizing and expanding the ICU data set either when +building or running Node.js. + diff --git a/intl/options_for_building_node_js.md b/intl/options_for_building_node_js.md new file mode 100644 index 00000000..dfb9f26f --- /dev/null +++ b/intl/options_for_building_node_js.md @@ -0,0 +1,33 @@ + +To control how ICU is used in Node.js, four `configure` options are available +during compilation. Additional details on how to compile Node.js are documented +in [BUILDING.md][]. + +- `--with-intl=none`/`--without-intl` +- `--with-intl=system-icu` +- `--with-intl=small-icu` (default) +- `--with-intl=full-icu` + +An overview of available Node.js and JavaScript features for each `configure` +option: + +| | `none` | `system-icu` | `small-icu` | `full-icu` | +|-----------------------------------------|-----------------------------------|------------------------------|------------------------|------------| +| [`String.prototype.normalize()`][] | none (function is no-op) | full | full | full | +| `String.prototype.to*Case()` | full | full | full | full | +| [`Intl`][] | none (object does not exist) | partial/full (depends on OS) | partial (English-only) | full | +| [`String.prototype.localeCompare()`][] | partial (not locale-aware) | full | full | full | +| `String.prototype.toLocale*Case()` | partial (not locale-aware) | full | full | full | +| [`Number.prototype.toLocaleString()`][] | partial (not locale-aware) | partial/full (depends on OS) | partial (English-only) | full | +| `Date.prototype.toLocale*String()` | partial (not locale-aware) | partial/full (depends on OS) | partial (English-only) | full | +| [WHATWG URL Parser][] | partial (no IDN support) | full | full | full | +| [`require('buffer').transcode()`][] | none (function does not exist) | full | full | full | +| [REPL][] | partial (inaccurate line editing) | full | full | full | +| [`require('util').TextDecoder`][] | partial (basic encodings support) | partial/full (depends on OS) | partial (Unicode-only) | full | +| [`RegExp` Unicode Property Escapes][] | none (invalid `RegExp` error) | full | full | full | + +The "(not locale-aware)" designation denotes that the function carries out its +operation just like the non-`Locale` version of the function, if one +exists. For example, under `none` mode, `Date.prototype.toLocaleString()`'s +operation is identical to that of `Date.prototype.toString()`. + diff --git a/intl/providing_icu_data_at_runtime.md b/intl/providing_icu_data_at_runtime.md new file mode 100644 index 00000000..bbddc8bd --- /dev/null +++ b/intl/providing_icu_data_at_runtime.md @@ -0,0 +1,34 @@ + +If the `small-icu` option is used, one can still provide additional locale data +at runtime so that the JS methods would work for all ICU locales. Assuming the +data file is stored at `/some/directory`, it can be made available to ICU +through either: + +* The [`NODE_ICU_DATA`][] environment variable: + + ```shell + env NODE_ICU_DATA=/some/directory node + ``` + +* The [`--icu-data-dir`][] CLI parameter: + + ```shell + node --icu-data-dir=/some/directory + ``` + +(If both are specified, the `--icu-data-dir` CLI parameter takes precedence.) + +ICU is able to automatically find and load a variety of data formats, but the +data must be appropriate for the ICU version, and the file correctly named. +The most common name for the data file is `icudt6X[bl].dat`, where `6X` denotes +the intended ICU version, and `b` or `l` indicates the system's endianness. +Check ["ICU Data"][] article in the ICU User Guide for other supported formats +and more details on ICU data in general. + +The [full-icu][] npm module can greatly simplify ICU data installation by +detecting the ICU version of the running `node` executable and downloading the +appropriate data file. After installing the module through `npm i full-icu`, +the data file will be available at `./node_modules/full-icu`. This path can be +then passed either to `NODE_ICU_DATA` or `--icu-data-dir` as shown above to +enable full `Intl` support. + diff --git a/api-docs/c825ec215740679473e33b20323eb43a025076ab4f267e6398c58d57a91508d3.md b/modules/accessing_the_main_module.md similarity index 100% rename from api-docs/c825ec215740679473e33b20323eb43a025076ab4f267e6398c58d57a91508d3.md rename to modules/accessing_the_main_module.md diff --git a/api-docs/8a876b15e77441e1fa78f9686acae5dd2527b8ad667d0a1ccd27c8b07e303632.md b/modules/addenda_package_manager_tips.md similarity index 100% rename from api-docs/8a876b15e77441e1fa78f9686acae5dd2527b8ad667d0a1ccd27c8b07e303632.md rename to modules/addenda_package_manager_tips.md diff --git a/api-docs/f720cca5e19429bdfc0bcccc3be1cdc07cf3f1a1f6925ee1ef5cffd2ef5b3ef4.md b/modules/all_together.md similarity index 100% rename from api-docs/f720cca5e19429bdfc0bcccc3be1cdc07cf3f1a1f6925ee1ef5cffd2ef5b3ef4.md rename to modules/all_together.md diff --git a/api-docs/3475d60f3140a0e1d09fd05433aea6bfea4403b289c50e8b9f00138b37d2d98d.md b/modules/caching.md similarity index 100% rename from api-docs/3475d60f3140a0e1d09fd05433aea6bfea4403b289c50e8b9f00138b37d2d98d.md rename to modules/caching.md diff --git a/api-docs/7a3dbba501ed63b6196b4a89bf4a78729b2a0d414599dcf83890d698cdb9aaa1.md b/modules/core_modules.md similarity index 100% rename from api-docs/7a3dbba501ed63b6196b4a89bf4a78729b2a0d414599dcf83890d698cdb9aaa1.md rename to modules/core_modules.md diff --git a/api-docs/fdaa0dc0642e3222c92487bc4d6c1216c107f45d152d9eee025eb4ddf263780d.md b/modules/cycles.md similarity index 100% rename from api-docs/fdaa0dc0642e3222c92487bc4d6c1216c107f45d152d9eee025eb4ddf263780d.md rename to modules/cycles.md diff --git a/api-docs/7e0eae9c5d5565a48b43a9ee469b5fa53345057b1eca02cf7fd56430460dd74d.md b/modules/dirname.md similarity index 100% rename from api-docs/7e0eae9c5d5565a48b43a9ee469b5fa53345057b1eca02cf7fd56430460dd74d.md rename to modules/dirname.md diff --git a/api-docs/d76417028281a458229b66301cdba6a9573131a27f7a426466545a84bfb0e9ad.md b/modules/exports.md similarity index 100% rename from api-docs/d76417028281a458229b66301cdba6a9573131a27f7a426466545a84bfb0e9ad.md rename to modules/exports.md diff --git a/api-docs/b367dd291233e0f3b82fd198e69b794fc74e100d183a5eaa58ff31d84cecc20d.md b/modules/exports_shortcut.md similarity index 100% rename from api-docs/b367dd291233e0f3b82fd198e69b794fc74e100d183a5eaa58ff31d84cecc20d.md rename to modules/exports_shortcut.md diff --git a/api-docs/97262a922a6ee7d869963d4564da6320bb399f7939ff36c1abb2b8884fe7f6dd.md b/modules/file_modules.md similarity index 100% rename from api-docs/97262a922a6ee7d869963d4564da6320bb399f7939ff36c1abb2b8884fe7f6dd.md rename to modules/file_modules.md diff --git a/api-docs/2d633ad9124f045caac524c3627491f96bd4dd31d62a77615579127aeda1c984.md b/modules/filename.md similarity index 100% rename from api-docs/2d633ad9124f045caac524c3627491f96bd4dd31d62a77615579127aeda1c984.md rename to modules/filename.md diff --git a/api-docs/d222d96c6b93cd37fdf6cf845709d95ec23dba1d1d18db90d02b32b8dfe7c100.md b/modules/folders_as_modules.md similarity index 100% rename from api-docs/d222d96c6b93cd37fdf6cf845709d95ec23dba1d1d18db90d02b32b8dfe7c100.md rename to modules/folders_as_modules.md diff --git a/api-docs/aacfea57f72d1f4ef3bc5903cedfb8dda63d53c7ac4645c3a009bf014b7bbc69.md b/modules/loading_from_node_modules_folders.md similarity index 100% rename from api-docs/aacfea57f72d1f4ef3bc5903cedfb8dda63d53c7ac4645c3a009bf014b7bbc69.md rename to modules/loading_from_node_modules_folders.md diff --git a/api-docs/e64b2b6cfd80209ca12cb5e4e2092b53b2e1b963f860b2df7ba936246f8ae0fd.md b/modules/loading_from_the_global_folders.md similarity index 100% rename from api-docs/e64b2b6cfd80209ca12cb5e4e2092b53b2e1b963f860b2df7ba936246f8ae0fd.md rename to modules/loading_from_the_global_folders.md diff --git a/api-docs/6353077bb923007e427b50c2120b2340a3630cd6f3b28758b0421e442a017945.md b/modules/module.md similarity index 100% rename from api-docs/6353077bb923007e427b50c2120b2340a3630cd6f3b28758b0421e442a017945.md rename to modules/module.md diff --git a/api-docs/e430919874022bf2446bed2acc324baf4b1fe750a1e8a0a8d69966011f7d6d04.md b/modules/module_builtinmodules.md similarity index 100% rename from api-docs/e430919874022bf2446bed2acc324baf4b1fe750a1e8a0a8d69966011f7d6d04.md rename to modules/module_builtinmodules.md diff --git a/api-docs/0f80609c097b2c7a9660a8f19f6291ddff1b6e76fbc19abf49ede216e8ca7d8a.md b/modules/module_caching_caveats.md similarity index 100% rename from api-docs/0f80609c097b2c7a9660a8f19f6291ddff1b6e76fbc19abf49ede216e8ca7d8a.md rename to modules/module_caching_caveats.md diff --git a/api-docs/8c911d35915f2167055eb3167c912ddb559acd9780bf883b0837d0a5eb195a16.md b/modules/module_children.md similarity index 100% rename from api-docs/8c911d35915f2167055eb3167c912ddb559acd9780bf883b0837d0a5eb195a16.md rename to modules/module_children.md diff --git a/api-docs/81bd974c906b3dcad3b4fb964d736732a161f15cee8eb5248c4f5dea2c7b0833.md b/modules/module_createrequirefrompath_filename.md similarity index 100% rename from api-docs/81bd974c906b3dcad3b4fb964d736732a161f15cee8eb5248c4f5dea2c7b0833.md rename to modules/module_createrequirefrompath_filename.md diff --git a/api-docs/8cd7a8f0b9d653c6ede0c258d0da9611a7d15503cfdf4a5cbedc59259690cf13.md b/modules/module_exports.md similarity index 100% rename from api-docs/8cd7a8f0b9d653c6ede0c258d0da9611a7d15503cfdf4a5cbedc59259690cf13.md rename to modules/module_exports.md diff --git a/api-docs/ed35d054964b09af3f3a84f76a05cc66ed31e2573612d32ac41636b68e0b0509.md b/modules/module_filename.md similarity index 100% rename from api-docs/ed35d054964b09af3f3a84f76a05cc66ed31e2573612d32ac41636b68e0b0509.md rename to modules/module_filename.md diff --git a/api-docs/88c5d88f3c259a07079fef3eb736b864eacc2e2a668cc70d29df899c85ecc080.md b/modules/module_id.md similarity index 100% rename from api-docs/88c5d88f3c259a07079fef3eb736b864eacc2e2a668cc70d29df899c85ecc080.md rename to modules/module_id.md diff --git a/api-docs/3d77f1b691cd0bc6fc81a3cbe347348a6476d4c2d028513d3653b27179a9ac94.md b/modules/module_loaded.md similarity index 100% rename from api-docs/3d77f1b691cd0bc6fc81a3cbe347348a6476d4c2d028513d3653b27179a9ac94.md rename to modules/module_loaded.md diff --git a/api-docs/2f4ef906d9a62fc72ef5b5376ac99283eddf05fd2986379dc95d3ff836842432.md b/modules/module_parent.md similarity index 100% rename from api-docs/2f4ef906d9a62fc72ef5b5376ac99283eddf05fd2986379dc95d3ff836842432.md rename to modules/module_parent.md diff --git a/api-docs/7cefbb784b97bd286bd68669dcf6c99cccaf387de3639ae8aa72879e47008936.md b/modules/module_paths.md similarity index 100% rename from api-docs/7cefbb784b97bd286bd68669dcf6c99cccaf387de3639ae8aa72879e47008936.md rename to modules/module_paths.md diff --git a/api-docs/043c3950b7de3c884f1b838dc27b1552c1e7289aa6d0f079231e3ca2f2b35050.md b/modules/module_require_id.md similarity index 100% rename from api-docs/043c3950b7de3c884f1b838dc27b1552c1e7289aa6d0f079231e3ca2f2b35050.md rename to modules/module_require_id.md diff --git a/api-docs/2223afe329c7ca2d53fbc344b3941320fce54b77710c82dd0b3a6b52fbb2966b.md b/modules/modules.md similarity index 100% rename from api-docs/2223afe329c7ca2d53fbc344b3941320fce54b77710c82dd0b3a6b52fbb2966b.md rename to modules/modules.md diff --git a/api-docs/f3850923fc884ea7c0245d672eb0e25a78beda9306654005d16ff1af33c55c28.md b/modules/require.md similarity index 100% rename from api-docs/f3850923fc884ea7c0245d672eb0e25a78beda9306654005d16ff1af33c55c28.md rename to modules/require.md diff --git a/api-docs/f1c1ca7b569e08893ea2780acbe5a6180be78f039a866d9e0bf82cb89c684944.md b/modules/require_cache.md similarity index 100% rename from api-docs/f1c1ca7b569e08893ea2780acbe5a6180be78f039a866d9e0bf82cb89c684944.md rename to modules/require_cache.md diff --git a/modules/require_extensions.md b/modules/require_extensions.md new file mode 100644 index 00000000..51749385 --- /dev/null +++ b/modules/require_extensions.md @@ -0,0 +1,34 @@ + + +> Stability: 0 - Deprecated + +* {Object} + +Instruct `require` on how to handle certain file extensions. + +Process files with the extension `.sjs` as `.js`: + +```js +require.extensions['.sjs'] = require.extensions['.js']; +``` + +**Deprecated** In the past, this list has been used to load +non-JavaScript modules into Node.js by compiling them on-demand. +However, in practice, there are much better ways to do this, such as +loading modules via some other Node.js program, or compiling them to +JavaScript ahead of time. + +Since the module system is locked, this feature will probably never go +away. However, it may have subtle bugs and complexities that are best +left untouched. + +Note that the number of file system operations that the module system +has to perform in order to resolve a `require(...)` statement to a +filename scales linearly with the number of registered extensions. + +In other words, adding extensions slows down the module loader and +should be discouraged. + diff --git a/api-docs/cefca2083b7e66c2502ae3c2afc096e608af5afeb306951a8bc0a4d3dcd21c1d.md b/modules/require_main.md similarity index 100% rename from api-docs/cefca2083b7e66c2502ae3c2afc096e608af5afeb306951a8bc0a4d3dcd21c1d.md rename to modules/require_main.md diff --git a/api-docs/4c8e29a5c3d430692f8fbc451b3fe292c1a732653053dab696e92cd02723688a.md b/modules/require_resolve_paths_request.md similarity index 100% rename from api-docs/4c8e29a5c3d430692f8fbc451b3fe292c1a732653053dab696e92cd02723688a.md rename to modules/require_resolve_paths_request.md diff --git a/api-docs/324bc8f982cb9af6091ca8dbe7cf0a2237f092ae27298b5b9c22a66d6bb4c34b.md b/modules/require_resolve_request_options.md similarity index 100% rename from api-docs/324bc8f982cb9af6091ca8dbe7cf0a2237f092ae27298b5b9c22a66d6bb4c34b.md rename to modules/require_resolve_request_options.md diff --git a/api-docs/68e811c5ef5b5a90566c071432630ed5ebcc8744d713b86d98a1119d90fcf847.md b/modules/the_module_object.md similarity index 100% rename from api-docs/68e811c5ef5b5a90566c071432630ed5ebcc8744d713b86d98a1119d90fcf847.md rename to modules/the_module_object.md diff --git a/api-docs/1fa13b8db5fcdbad1b3f384867cf157cee70eb0b2ab4b582b1de77d7c79bbf00.md b/modules/the_module_object_1.md similarity index 100% rename from api-docs/1fa13b8db5fcdbad1b3f384867cf157cee70eb0b2ab4b582b1de77d7c79bbf00.md rename to modules/the_module_object_1.md diff --git a/modules/the_module_scope.md b/modules/the_module_scope.md new file mode 100644 index 00000000..8b137891 --- /dev/null +++ b/modules/the_module_scope.md @@ -0,0 +1 @@ + diff --git a/api-docs/a29bca58a82697cbee081132132c444f1d618861fcf21a46df756529baba94e4.md b/modules/the_module_wrapper.md similarity index 100% rename from api-docs/a29bca58a82697cbee081132132c444f1d618861fcf21a46df756529baba94e4.md rename to modules/the_module_wrapper.md diff --git a/n-api/asynchronous_thread_safe_function_calls.md b/n-api/asynchronous_thread_safe_function_calls.md new file mode 100644 index 00000000..0b073eab --- /dev/null +++ b/n-api/asynchronous_thread_safe_function_calls.md @@ -0,0 +1,108 @@ + +> Stability: 1 - Experimental + +JavaScript functions can normally only be called from a native addon's main +thread. If an addon creates additional threads, then N-API functions that +require a `napi_env`, `napi_value`, or `napi_ref` must not be called from those +threads. + +When an addon has additional threads and JavaScript functions need to be invoked +based on the processing completed by those threads, those threads must +communicate with the addon's main thread so that the main thread can invoke the +JavaScript function on their behalf. The thread-safe function APIs provide an +easy way to do this. + +These APIs provide the type `napi_threadsafe_function` as well as APIs to +create, destroy, and call objects of this type. +`napi_create_threadsafe_function()` creates a persistent reference to a +`napi_value` that holds a JavaScript function which can be called from multiple +threads. The calls happen asynchronously. This means that values with which the +JavaScript callback is to be called will be placed in a queue, and, for each +value in the queue, a call will eventually be made to the JavaScript function. + +Upon creation of a `napi_threadsafe_function` a `napi_finalize` callback can be +provided. This callback will be invoked on the main thread when the thread-safe +function is about to be destroyed. It receives the context and the finalize data +given during construction, and provides an opportunity for cleaning up after the +threads e.g. by calling `uv_thread_join()`. **It is important that, aside from +the main loop thread, there be no threads left using the thread-safe function +after the finalize callback completes.** + +The `context` given during the call to `napi_create_threadsafe_function()` can +be retrieved from any thread with a call to +`napi_get_threadsafe_function_context()`. + +`napi_call_threadsafe_function()` can then be used for initiating a call into +JavaScript. `napi_call_threadsafe_function()` accepts a parameter which controls +whether the API behaves blockingly. If set to `napi_tsfn_nonblocking`, the API +behaves non-blockingly, returning `napi_queue_full` if the queue was full, +preventing data from being successfully added to the queue. If set to +`napi_tsfn_blocking`, the API blocks until space becomes available in the queue. +`napi_call_threadsafe_function()` never blocks if the thread-safe function was +created with a maximum queue size of 0. + +The actual call into JavaScript is controlled by the callback given via the +`call_js_cb` parameter. `call_js_cb` is invoked on the main thread once for each +value that was placed into the queue by a successful call to +`napi_call_threadsafe_function()`. If such a callback is not given, a default +callback will be used, and the resulting JavaScript call will have no arguments. +The `call_js_cb` callback receives the JavaScript function to call as a +`napi_value` in its parameters, as well as the `void*` context pointer used when +creating the `napi_threadsafe_function`, and the next data pointer that was +created by one of the secondary threads. The callback can then use an API such +as `napi_call_function()` to call into JavaScript. + +The callback may also be invoked with `env` and `call_js_cb` both set to `NULL` +to indicate that calls into JavaScript are no longer possible, while items +remain in the queue that may need to be freed. This normally occurs when the +Node.js process exits while there is a thread-safe function still active. + +It is not necessary to call into JavaScript via `napi_make_callback()` because +N-API runs `call_js_cb` in a context appropriate for callbacks. + +Threads can be added to and removed from a `napi_threadsafe_function` object +during its existence. Thus, in addition to specifying an initial number of +threads upon creation, `napi_acquire_threadsafe_function` can be called to +indicate that a new thread will start making use of the thread-safe function. +Similarly, `napi_release_threadsafe_function` can be called to indicate that an +existing thread will stop making use of the thread-safe function. + +`napi_threadsafe_function` objects are destroyed when every thread which uses +the object has called `napi_release_threadsafe_function()` or has received a +return status of `napi_closing` in response to a call to +`napi_call_threadsafe_function`. The queue is emptied before the +`napi_threadsafe_function` is destroyed. It is important that +`napi_release_threadsafe_function()` be the last API call made in conjunction +with a given `napi_threadsafe_function`, because after the call completes, there +is no guarantee that the `napi_threadsafe_function` is still allocated. For the +same reason it is also important that no more use be made of a thread-safe +function after receiving a return value of `napi_closing` in response to a call +to `napi_call_threadsafe_function`. Data associated with the +`napi_threadsafe_function` can be freed in its `napi_finalize` callback which +was passed to `napi_create_threadsafe_function()`. + +Once the number of threads making use of a `napi_threadsafe_function` reaches +zero, no further threads can start making use of it by calling +`napi_acquire_threadsafe_function()`. In fact, all subsequent API calls +associated with it, except `napi_release_threadsafe_function()`, will return an +error value of `napi_closing`. + +The thread-safe function can be "aborted" by giving a value of `napi_tsfn_abort` +to `napi_release_threadsafe_function()`. This will cause all subsequent APIs +associated with the thread-safe function except +`napi_release_threadsafe_function()` to return `napi_closing` even before its +reference count reaches zero. In particular, `napi_call_threadsafe_function()` +will return `napi_closing`, thus informing the threads that it is no longer +possible to make asynchronous calls to the thread-safe function. This can be +used as a criterion for terminating the thread. **Upon receiving a return value +of `napi_closing` from `napi_call_threadsafe_function()` a thread must make no +further use of the thread-safe function because it is no longer guaranteed to +be allocated.** + +Similarly to libuv handles, thread-safe functions can be "referenced" and +"unreferenced". A "referenced" thread-safe function will cause the event loop on +the thread on which it is created to remain alive until the thread-safe function +is destroyed. In contrast, an "unreferenced" thread-safe function will not +prevent the event loop from exiting. The APIs `napi_ref_threadsafe_function` and +`napi_unref_threadsafe_function` exist for this purpose. + diff --git a/n-api/basic_n_api_data_types.md b/n-api/basic_n_api_data_types.md new file mode 100644 index 00000000..d4a4abf4 --- /dev/null +++ b/n-api/basic_n_api_data_types.md @@ -0,0 +1,5 @@ + +N-API exposes the following fundamental datatypes as abstractions that are +consumed by the various APIs. These APIs should be treated as opaque, +introspectable only with other N-API calls. + diff --git a/n-api/cleanup_on_exit_of_the_current_node_js_instance.md b/n-api/cleanup_on_exit_of_the_current_node_js_instance.md new file mode 100644 index 00000000..fab835c0 --- /dev/null +++ b/n-api/cleanup_on_exit_of_the_current_node_js_instance.md @@ -0,0 +1,9 @@ + +While a Node.js process typically releases all its resources when exiting, +embedders of Node.js, or future Worker support, may require addons to register +clean-up hooks that will be run once the current Node.js instance exits. + +N-API provides functions for registering and un-registering such callbacks. +When those callbacks are run, all resources that are being held by the addon +should be freed up. + diff --git a/n-api/custom_asynchronous_operations.md b/n-api/custom_asynchronous_operations.md new file mode 100644 index 00000000..127065a5 --- /dev/null +++ b/n-api/custom_asynchronous_operations.md @@ -0,0 +1,5 @@ +The simple asynchronous work APIs above may not be appropriate for every +scenario. When using any other asynchronous mechanism, the following APIs +are necessary to ensure an asynchronous operation is properly tracked by +the runtime. + diff --git a/api-docs/fa0d9236fe4ac3ddc16cd4449a9c96811e1390a3349709b5fe1724758632dc85.md b/n-api/enum_types.md similarity index 100% rename from api-docs/fa0d9236fe4ac3ddc16cd4449a9c96811e1390a3349709b5fe1724758632dc85.md rename to n-api/enum_types.md diff --git a/n-api/error_handling.md b/n-api/error_handling.md new file mode 100644 index 00000000..5f5ce806 --- /dev/null +++ b/n-api/error_handling.md @@ -0,0 +1,3 @@ +N-API uses both return values and JavaScript exceptions for error handling. +The following sections explain the approach for each case. + diff --git a/n-api/exceptions.md b/n-api/exceptions.md new file mode 100644 index 00000000..da3986ee --- /dev/null +++ b/n-api/exceptions.md @@ -0,0 +1,79 @@ +Any N-API function call may result in a pending JavaScript exception. This is +obviously the case for any function that may cause the execution of +JavaScript, but N-API specifies that an exception may be pending +on return from any of the API functions. + +If the `napi_status` returned by a function is `napi_ok` then no +exception is pending and no additional action is required. If the +`napi_status` returned is anything other than `napi_ok` or +`napi_pending_exception`, in order to try to recover and continue +instead of simply returning immediately, [`napi_is_exception_pending`][] +must be called in order to determine if an exception is pending or not. + +In many cases when an N-API function is called and an exception is +already pending, the function will return immediately with a +`napi_status` of `napi_pending_exception`. However, this is not the case +for all functions. N-API allows a subset of the functions to be +called to allow for some minimal cleanup before returning to JavaScript. +In that case, `napi_status` will reflect the status for the function. It +will not reflect previous pending exceptions. To avoid confusion, check +the error status after every function call. + +When an exception is pending one of two approaches can be employed. + +The first approach is to do any appropriate cleanup and then return so that +execution will return to JavaScript. As part of the transition back to +JavaScript the exception will be thrown at the point in the JavaScript +code where the native method was invoked. The behavior of most N-API calls +is unspecified while an exception is pending, and many will simply return +`napi_pending_exception`, so it is important to do as little as possible +and then return to JavaScript where the exception can be handled. + +The second approach is to try to handle the exception. There will be cases +where the native code can catch the exception, take the appropriate action, +and then continue. This is only recommended in specific cases +where it is known that the exception can be safely handled. In these +cases [`napi_get_and_clear_last_exception`][] can be used to get and +clear the exception. On success, result will contain the handle to +the last JavaScript `Object` thrown. If it is determined, after +retrieving the exception, the exception cannot be handled after all +it can be re-thrown it with [`napi_throw`][] where error is the +JavaScript `Error` object to be thrown. + +The following utility functions are also available in case native code +needs to throw an exception or determine if a `napi_value` is an instance +of a JavaScript `Error` object: [`napi_throw_error`][], +[`napi_throw_type_error`][], [`napi_throw_range_error`][] and +[`napi_is_error`][]. + +The following utility functions are also available in case native +code needs to create an `Error` object: [`napi_create_error`][], +[`napi_create_type_error`][], and [`napi_create_range_error`][], +where result is the `napi_value` that refers to the newly created +JavaScript `Error` object. + +The Node.js project is adding error codes to all of the errors +generated internally. The goal is for applications to use these +error codes for all error checking. The associated error messages +will remain, but will only be meant to be used for logging and +display with the expectation that the message can change without +SemVer applying. In order to support this model with N-API, both +in internal functionality and for module specific functionality +(as its good practice), the `throw_` and `create_` functions +take an optional code parameter which is the string for the code +to be added to the error object. If the optional parameter is NULL +then no code will be associated with the error. If a code is provided, +the name associated with the error is also updated to be: + +```text +originalName [code] +``` + +where `originalName` is the original name associated with the error +and `code` is the code that was provided. For example, if the code +is `'ERR_ERROR_1'` and a `TypeError` is being created the name will be: + +```text +TypeError [ERR_ERROR_1] +``` + diff --git a/n-api/fatal_errors.md b/n-api/fatal_errors.md new file mode 100644 index 00000000..cb1f6763 --- /dev/null +++ b/n-api/fatal_errors.md @@ -0,0 +1,4 @@ + +In the event of an unrecoverable error in a native module, a fatal error can be +thrown to immediately terminate the process. + diff --git a/n-api/functions.md b/n-api/functions.md new file mode 100644 index 00000000..e69de29b diff --git a/n-api/functions_to_convert_from_c_types_to_n_api.md b/n-api/functions_to_convert_from_c_types_to_n_api.md new file mode 100644 index 00000000..e69de29b diff --git a/n-api/functions_to_convert_from_n_api_to_c_types.md b/n-api/functions_to_convert_from_n_api_to_c_types.md new file mode 100644 index 00000000..e69de29b diff --git a/n-api/functions_to_get_global_instances.md b/n-api/functions_to_get_global_instances.md new file mode 100644 index 00000000..e69de29b diff --git a/n-api/implications_of_abi_stability.md b/n-api/implications_of_abi_stability.md new file mode 100644 index 00000000..87711308 --- /dev/null +++ b/n-api/implications_of_abi_stability.md @@ -0,0 +1,29 @@ + +Although N-API provides an ABI stability guarantee, other parts of Node.js do +not, and any external libraries used from the addon may not. In particular, +none of the following APIs provide an ABI stability guarantee across major +versions: +* the Node.js C++ APIs available via any of + ```C++ + #include + #include + #include + #include + ``` +* the libuv APIs which are also included with Node.js and available via + ```C++ + #include + ``` +* the V8 API available via + ```C++ + #include + ``` + +Thus, for an addon to remain ABI-compatible across Node.js major versions, it +must make use exclusively of N-API by restricting itself to using +```C +#include +``` +and by checking, for all external libraries that it uses, that the external +library makes ABI stability guarantees similar to N-API. + diff --git a/n-api/libuv_event_loop.md b/n-api/libuv_event_loop.md new file mode 100644 index 00000000..ed7282b2 --- /dev/null +++ b/n-api/libuv_event_loop.md @@ -0,0 +1,4 @@ + +N-API provides a function for getting the current event loop associated with +a specific `napi_env`. + diff --git a/n-api/making_handle_lifespan_shorter_than_that_of_the_native_method.md b/n-api/making_handle_lifespan_shorter_than_that_of_the_native_method.md new file mode 100644 index 00000000..3f83ac5c --- /dev/null +++ b/n-api/making_handle_lifespan_shorter_than_that_of_the_native_method.md @@ -0,0 +1,70 @@ +It is often necessary to make the lifespan of handles shorter than +the lifespan of a native method. For example, consider a native method +that has a loop which iterates through the elements in a large array: + +```C +for (int i = 0; i < 1000000; i++) { + napi_value result; + napi_status status = napi_get_element(env, object, i, &result); + if (status != napi_ok) { + break; + } + // do something with element +} +``` + +This would result in a large number of handles being created, consuming +substantial resources. In addition, even though the native code could only +use the most recent handle, all of the associated objects would also be +kept alive since they all share the same scope. + +To handle this case, N-API provides the ability to establish a new 'scope' to +which newly created handles will be associated. Once those handles +are no longer required, the scope can be 'closed' and any handles associated +with the scope are invalidated. The methods available to open/close scopes are +[`napi_open_handle_scope`][] and [`napi_close_handle_scope`][]. + +N-API only supports a single nested hierarchy of scopes. There is only one +active scope at any time, and all new handles will be associated with that +scope while it is active. Scopes must be closed in the reverse order from +which they are opened. In addition, all scopes created within a native method +must be closed before returning from that method. + +Taking the earlier example, adding calls to [`napi_open_handle_scope`][] and +[`napi_close_handle_scope`][] would ensure that at most a single handle +is valid throughout the execution of the loop: + +```C +for (int i = 0; i < 1000000; i++) { + napi_handle_scope scope; + napi_status status = napi_open_handle_scope(env, &scope); + if (status != napi_ok) { + break; + } + napi_value result; + status = napi_get_element(env, object, i, &result); + if (status != napi_ok) { + break; + } + // do something with element + status = napi_close_handle_scope(env, scope); + if (status != napi_ok) { + break; + } +} +``` + +When nesting scopes, there are cases where a handle from an +inner scope needs to live beyond the lifespan of that scope. N-API supports an +'escapable scope' in order to support this case. An escapable scope +allows one handle to be 'promoted' so that it 'escapes' the +current scope and the lifespan of the handle changes from the current +scope to that of the outer scope. + +The methods available to open/close escapable scopes are +[`napi_open_escapable_handle_scope`][] and +[`napi_close_escapable_handle_scope`][]. + +The request to promote a handle is made through [`napi_escape_handle`][] which +can only be called once. + diff --git a/n-api/memory_management.md b/n-api/memory_management.md new file mode 100644 index 00000000..8b137891 --- /dev/null +++ b/n-api/memory_management.md @@ -0,0 +1 @@ + diff --git a/api-docs/e7b601e90dea936763a4a2a1b0bb9040adea79bb6c48da4d5c266f9383651bc9.md b/n-api/module_registration.md similarity index 100% rename from api-docs/e7b601e90dea936763a4a2a1b0bb9040adea79bb6c48da4d5c266f9383651bc9.md rename to n-api/module_registration.md diff --git a/api-docs/a2cd3c40d74db8d39e1646a13bbd5dada1d3cdb1396eef4071c11be8941a6e1e.md b/n-api/n_api.md similarity index 97% rename from api-docs/a2cd3c40d74db8d39e1646a13bbd5dada1d3cdb1396eef4071c11be8941a6e1e.md rename to n-api/n_api.md index d00375f5..973f5fa9 100644 --- a/api-docs/a2cd3c40d74db8d39e1646a13bbd5dada1d3cdb1396eef4071c11be8941a6e1e.md +++ b/n-api/n_api.md @@ -59,7 +59,7 @@ if (status != napi_ok) { return; } -status = napi_crate_string_utf8(env, "bar", NAPI_AUTO_LENGTH, &string); +status = napi_create_string_utf8(env, "bar", NAPI_AUTO_LENGTH, &string); if (status != napi_ok) { napi_throw_error(env, ...); return; diff --git a/n-api/n_api_callback_types.md b/n-api/n_api_callback_types.md new file mode 100644 index 00000000..e69de29b diff --git a/n-api/n_api_memory_management_types.md b/n-api/n_api_memory_management_types.md new file mode 100644 index 00000000..e69de29b diff --git a/n-api/n_api_version_matrix.md b/n-api/n_api_version_matrix.md new file mode 100644 index 00000000..99d36792 --- /dev/null +++ b/n-api/n_api_version_matrix.md @@ -0,0 +1,11 @@ + +| | 1 | 2 | 3 | 4 | +|:-----:|:-------:|:--------:|:--------:|:--------:| +| v6.x | | | v6.14.2* | | +| v8.x | v8.0.0* | v8.10.0* | v8.11.2 | | +| v9.x | v9.0.0* | v9.3.0* | v9.11.0* | | +| v10.x | | | v10.0.0 | v10.16.0 | +| v11.x | | | v11.0.0 | v11.8.0 | + +\* Indicates that the N-API version was released as experimental + diff --git a/n-api/napi_acquire_threadsafe_function.md b/n-api/napi_acquire_threadsafe_function.md new file mode 100644 index 00000000..6999949f --- /dev/null +++ b/n-api/napi_acquire_threadsafe_function.md @@ -0,0 +1,21 @@ + +> Stability: 2 - Stable + + +```C +NAPI_EXTERN napi_status +napi_acquire_threadsafe_function(napi_threadsafe_function func); +``` + +- `[in] func`: The asynchronous thread-safe JavaScript function to start making +use of. + +A thread should call this API before passing `func` to any other thread-safe +function APIs to indicate that it will be making use of `func`. This prevents +`func` from being destroyed when all other threads have stopped making use of +it. + +This API may be called from any thread which will start making use of `func`. + diff --git a/n-api/napi_add_env_cleanup_hook.md b/n-api/napi_add_env_cleanup_hook.md new file mode 100644 index 00000000..a1dc36ff --- /dev/null +++ b/n-api/napi_add_env_cleanup_hook.md @@ -0,0 +1,26 @@ + + +```C +NODE_EXTERN napi_status napi_add_env_cleanup_hook(napi_env env, + void (*fun)(void* arg), + void* arg); +``` + +Registers `fun` as a function to be run with the `arg` parameter once the +current Node.js environment exits. + +A function can safely be specified multiple times with different +`arg` values. In that case, it will be called multiple times as well. +Providing the same `fun` and `arg` values multiple times is not allowed +and will lead the process to abort. + +The hooks will be called in reverse order, i.e. the most recently added one +will be called first. + +Removing this hook can be done by using `napi_remove_env_cleanup_hook`. +Typically, that happens when the resource for which this hook was added +is being torn down anyway. + diff --git a/n-api/napi_add_finalizer.md b/n-api/napi_add_finalizer.md new file mode 100644 index 00000000..2b9cbf05 --- /dev/null +++ b/n-api/napi_add_finalizer.md @@ -0,0 +1,43 @@ + +> Stability: 1 - Experimental + + +```C +napi_status napi_add_finalizer(napi_env env, + napi_value js_object, + void* native_object, + napi_finalize finalize_cb, + void* finalize_hint, + napi_ref* result); +``` + + - `[in] env`: The environment that the API is invoked under. + - `[in] js_object`: The JavaScript object to which the native data will be + attached. + - `[in] native_object`: The native data that will be attached to the JavaScript + object. + - `[in] finalize_cb`: Native callback that will be used to free the + native data when the JavaScript object is ready for garbage-collection. + - `[in] finalize_hint`: Optional contextual hint that is passed to the + finalize callback. + - `[out] result`: Optional reference to the JavaScript object. + +Returns `napi_ok` if the API succeeded. + +Adds a `napi_finalize` callback which will be called when the JavaScript object +in `js_object` is ready for garbage collection. This API is similar to +`napi_wrap()` except that +* the native data cannot be retrieved later using `napi_unwrap()`, +* nor can it be removed later using `napi_remove_wrap()`, and +* the API can be called multiple times with different data items in order to + attach each of them to the JavaScript object. + +*Caution*: The optional returned reference (if obtained) should be deleted via +[`napi_delete_reference`][] ONLY in response to the finalize callback +invocation. If it is deleted before then, then the finalize callback may never +be invoked. Therefore, when obtaining a reference a finalize callback is also +required in order to enable correct disposal of the reference. + diff --git a/n-api/napi_adjust_external_memory.md b/n-api/napi_adjust_external_memory.md new file mode 100644 index 00000000..d3af7033 --- /dev/null +++ b/n-api/napi_adjust_external_memory.md @@ -0,0 +1,25 @@ + +```C +NAPI_EXTERN napi_status napi_adjust_external_memory(napi_env env, + int64_t change_in_bytes, + int64_t* result); +``` + +- `[in] env`: The environment that the API is invoked under. +- `[in] change_in_bytes`: The change in externally allocated memory that is +kept alive by JavaScript objects. +- `[out] result`: The adjusted value + +Returns `napi_ok` if the API succeeded. + +This function gives V8 an indication of the amount of externally allocated +memory that is kept alive by JavaScript objects (i.e. a JavaScript object +that points to its own memory allocated by a native module). Registering +externally allocated memory will trigger global garbage collections more +often than it would otherwise. + + + diff --git a/n-api/napi_async_complete_callback.md b/n-api/napi_async_complete_callback.md new file mode 100644 index 00000000..871dc7ae --- /dev/null +++ b/n-api/napi_async_complete_callback.md @@ -0,0 +1,9 @@ +Function pointer used with functions that support asynchronous +operations. Callback functions must statisfy the following signature: + +```C +typedef void (*napi_async_complete_callback)(napi_env env, + napi_status status, + void* data); +``` + diff --git a/n-api/napi_async_destroy.md b/n-api/napi_async_destroy.md new file mode 100644 index 00000000..e8646d03 --- /dev/null +++ b/n-api/napi_async_destroy.md @@ -0,0 +1,16 @@ + +```C +napi_status napi_async_destroy(napi_env env, + napi_async_context async_context); +``` + +- `[in] env`: The environment that the API is invoked under. +- `[in] async_context`: The async context to be destroyed. + +Returns `napi_ok` if the API succeeded. + +This API can be called even if there is a pending JavaScript exception. + diff --git a/n-api/napi_async_execute_callback.md b/n-api/napi_async_execute_callback.md new file mode 100644 index 00000000..c3e92508 --- /dev/null +++ b/n-api/napi_async_execute_callback.md @@ -0,0 +1,12 @@ +Function pointer used with functions that support asynchronous +operations. Callback functions must statisfy the following signature: + +```C +typedef void (*napi_async_execute_callback)(napi_env env, void* data); +``` + +Implementations of this type of function should avoid making any N-API calls +that could result in the execution of JavaScript or interaction with +JavaScript objects. Most often, any code that needs to make N-API +calls should be made in `napi_async_complete_callback` instead. + diff --git a/n-api/napi_async_init.md b/n-api/napi_async_init.md new file mode 100644 index 00000000..04d951cf --- /dev/null +++ b/n-api/napi_async_init.md @@ -0,0 +1,21 @@ + +```C +napi_status napi_async_init(napi_env env, + napi_value async_resource, + napi_value async_resource_name, + napi_async_context* result) +``` + +- `[in] env`: The environment that the API is invoked under. +- `[in] async_resource`: An optional object associated with the async work + that will be passed to possible `async_hooks` [`init` hooks][]. +- `[in] async_resource_name`: Identifier for the kind of resource + that is being provided for diagnostic information exposed by the + `async_hooks` API. +- `[out] result`: The initialized async context. + +Returns `napi_ok` if the API succeeded. + diff --git a/n-api/napi_call_function.md b/n-api/napi_call_function.md new file mode 100644 index 00000000..b34b3fd7 --- /dev/null +++ b/n-api/napi_call_function.md @@ -0,0 +1,66 @@ + +```C +napi_status napi_call_function(napi_env env, + napi_value recv, + napi_value func, + int argc, + const napi_value* argv, + napi_value* result) +``` + +- `[in] env`: The environment that the API is invoked under. +- `[in] recv`: The `this` object passed to the called function. +- `[in] func`: `napi_value` representing the JavaScript function +to be invoked. +- `[in] argc`: The count of elements in the `argv` array. +- `[in] argv`: Array of `napi_values` representing JavaScript values passed +in as arguments to the function. +- `[out] result`: `napi_value` representing the JavaScript object returned. + +Returns `napi_ok` if the API succeeded. + +This method allows a JavaScript function object to be called from a native +add-on. This is the primary mechanism of calling back *from* the add-on's +native code *into* JavaScript. For the special case of calling into JavaScript +after an async operation, see [`napi_make_callback`][]. + +A sample use case might look as follows. Consider the following JavaScript +snippet: +```js +function AddTwo(num) { + return num + 2; +} +``` + +Then, the above function can be invoked from a native add-on using the +following code: +```C +// Get the function named "AddTwo" on the global object +napi_value global, add_two, arg; +napi_status status = napi_get_global(env, &global); +if (status != napi_ok) return; + +status = napi_get_named_property(env, global, "AddTwo", &add_two); +if (status != napi_ok) return; + +// const arg = 1337 +status = napi_create_int32(env, 1337, &arg); +if (status != napi_ok) return; + +napi_value* argv = &arg; +size_t argc = 1; + +// AddTwo(arg); +napi_value return_val; +status = napi_call_function(env, global, add_two, argc, argv, &return_val); +if (status != napi_ok) return; + +// Convert the result back to a native type +int32_t result; +status = napi_get_value_int32(env, return_val, &result); +if (status != napi_ok) return; +``` + diff --git a/n-api/napi_call_threadsafe_function.md b/n-api/napi_call_threadsafe_function.md new file mode 100644 index 00000000..a63a26db --- /dev/null +++ b/n-api/napi_call_threadsafe_function.md @@ -0,0 +1,27 @@ + +> Stability: 2 - Stable + + +```C +NAPI_EXTERN napi_status +napi_call_threadsafe_function(napi_threadsafe_function func, + void* data, + napi_threadsafe_function_call_mode is_blocking); +``` + +- `[in] func`: The asynchronous thread-safe JavaScript function to invoke. +- `[in] data`: Data to send into JavaScript via the callback `call_js_cb` +provided during the creation of the thread-safe JavaScript function. +- `[in] is_blocking`: Flag whose value can be either `napi_tsfn_blocking` to +indicate that the call should block if the queue is full or +`napi_tsfn_nonblocking` to indicate that the call should return immediately with +a status of `napi_queue_full` whenever the queue is full. + +This API will return `napi_closing` if `napi_release_threadsafe_function()` was +called with `abort` set to `napi_tsfn_abort` from any thread. The value is only +added to the queue if the API returns `napi_ok`. + +This API may be called from any thread which makes use of `func`. + diff --git a/n-api/napi_callback.md b/n-api/napi_callback.md new file mode 100644 index 00000000..500a8712 --- /dev/null +++ b/n-api/napi_callback.md @@ -0,0 +1,7 @@ +Function pointer type for user-provided native functions which are to be +exposed to JavaScript via N-API. Callback functions should satisfy the +following signature: +```C +typedef napi_value (*napi_callback)(napi_env, napi_callback_info); +``` + diff --git a/n-api/napi_callback_info.md b/n-api/napi_callback_info.md new file mode 100644 index 00000000..33e329b4 --- /dev/null +++ b/n-api/napi_callback_info.md @@ -0,0 +1,4 @@ +Opaque datatype that is passed to a callback function. It can be used for +getting additional information about the context in which the callback was +invoked. + diff --git a/n-api/napi_cancel_async_work.md b/n-api/napi_cancel_async_work.md new file mode 100644 index 00000000..ef7f3706 --- /dev/null +++ b/n-api/napi_cancel_async_work.md @@ -0,0 +1,23 @@ + +```C +napi_status napi_cancel_async_work(napi_env env, + napi_async_work work); +``` + +- `[in] env`: The environment that the API is invoked under. +- `[in] work`: The handle returned by the call to `napi_create_async_work`. + +Returns `napi_ok` if the API succeeded. + +This API cancels queued work if it has not yet +been started. If it has already started executing, it cannot be +cancelled and `napi_generic_failure` will be returned. If successful, +the `complete` callback will be invoked with a status value of +`napi_cancelled`. The work should not be deleted before the `complete` +callback invocation, even if it has been successfully cancelled. + +This API can be called even if there is a pending JavaScript exception. + diff --git a/n-api/napi_close_callback_scope.md b/n-api/napi_close_callback_scope.md new file mode 100644 index 00000000..9099429b --- /dev/null +++ b/n-api/napi_close_callback_scope.md @@ -0,0 +1,13 @@ + +```C +NAPI_EXTERN napi_status napi_close_callback_scope(napi_env env, + napi_callback_scope scope) +``` +- `[in] env`: The environment that the API is invoked under. +- `[in] scope`: The scope to be closed. + +This API can be called even if there is a pending JavaScript exception. + diff --git a/n-api/napi_close_escapable_handle_scope.md b/n-api/napi_close_escapable_handle_scope.md new file mode 100644 index 00000000..917cedf8 --- /dev/null +++ b/n-api/napi_close_escapable_handle_scope.md @@ -0,0 +1,19 @@ + +```C +NAPI_EXTERN napi_status + napi_close_escapable_handle_scope(napi_env env, + napi_handle_scope scope); +``` +- `[in] env`: The environment that the API is invoked under. +- `[in] scope`: `napi_value` representing the scope to be closed. + +Returns `napi_ok` if the API succeeded. + +This API closes the scope passed in. Scopes must be closed in the +reverse order from which they were created. + +This API can be called even if there is a pending JavaScript exception. + diff --git a/n-api/napi_close_handle_scope.md b/n-api/napi_close_handle_scope.md new file mode 100644 index 00000000..4f968df6 --- /dev/null +++ b/n-api/napi_close_handle_scope.md @@ -0,0 +1,18 @@ + +```C +NAPI_EXTERN napi_status napi_close_handle_scope(napi_env env, + napi_handle_scope scope); +``` +- `[in] env`: The environment that the API is invoked under. +- `[in] scope`: `napi_value` representing the scope to be closed. + +Returns `napi_ok` if the API succeeded. + +This API closes the scope passed in. Scopes must be closed in the +reverse order from which they were created. + +This API can be called even if there is a pending JavaScript exception. + diff --git a/api-docs/1f83ddb922248b9a879c079ea905145a77e48a1e01f02696aa0f48c776a14e3e.md b/n-api/napi_coerce_to_bool.md similarity index 100% rename from api-docs/1f83ddb922248b9a879c079ea905145a77e48a1e01f02696aa0f48c776a14e3e.md rename to n-api/napi_coerce_to_bool.md diff --git a/api-docs/cfdc8851e81e9fc2c3fbbf9c17a406b72cf1dd79860f6f3880c3cc710fddc0c7.md b/n-api/napi_coerce_to_number.md similarity index 100% rename from api-docs/cfdc8851e81e9fc2c3fbbf9c17a406b72cf1dd79860f6f3880c3cc710fddc0c7.md rename to n-api/napi_coerce_to_number.md diff --git a/api-docs/c25dacfb70b9d5f46b2d2aa4c8840c18167f42ce7ed0d3666161c8fc4f41880f.md b/n-api/napi_coerce_to_object.md similarity index 100% rename from api-docs/c25dacfb70b9d5f46b2d2aa4c8840c18167f42ce7ed0d3666161c8fc4f41880f.md rename to n-api/napi_coerce_to_object.md diff --git a/api-docs/55f4596ded90455a033a49433d6e19b2392c9bccd3e40ddc70981dd863743b1a.md b/n-api/napi_coerce_to_string.md similarity index 100% rename from api-docs/55f4596ded90455a033a49433d6e19b2392c9bccd3e40ddc70981dd863743b1a.md rename to n-api/napi_coerce_to_string.md diff --git a/n-api/napi_create_array.md b/n-api/napi_create_array.md new file mode 100644 index 00000000..b70ef9eb --- /dev/null +++ b/n-api/napi_create_array.md @@ -0,0 +1,17 @@ + +```C +napi_status napi_create_array(napi_env env, napi_value* result) +``` + +- `[in] env`: The environment that the N-API call is invoked under. +- `[out] result`: A `napi_value` representing a JavaScript `Array`. + +Returns `napi_ok` if the API succeeded. + +This API returns an N-API value corresponding to a JavaScript `Array` type. +JavaScript arrays are described in +[Section 22.1][] of the ECMAScript Language Specification. + diff --git a/n-api/napi_create_array_with_length.md b/n-api/napi_create_array_with_length.md new file mode 100644 index 00000000..07ab7d93 --- /dev/null +++ b/n-api/napi_create_array_with_length.md @@ -0,0 +1,28 @@ + +```C +napi_status napi_create_array_with_length(napi_env env, + size_t length, + napi_value* result) +``` + +- `[in] env`: The environment that the API is invoked under. +- `[in] length`: The initial length of the `Array`. +- `[out] result`: A `napi_value` representing a JavaScript `Array`. + +Returns `napi_ok` if the API succeeded. + +This API returns an N-API value corresponding to a JavaScript `Array` type. +The `Array`'s length property is set to the passed-in length parameter. +However, the underlying buffer is not guaranteed to be pre-allocated by the VM +when the array is created - that behavior is left to the underlying VM +implementation. +If the buffer must be a contiguous block of memory that can be +directly read and/or written via C, consider using +[`napi_create_external_arraybuffer`][]. + +JavaScript arrays are described in +[Section 22.1][] of the ECMAScript Language Specification. + diff --git a/n-api/napi_create_arraybuffer.md b/n-api/napi_create_arraybuffer.md new file mode 100644 index 00000000..d2abd2b8 --- /dev/null +++ b/n-api/napi_create_arraybuffer.md @@ -0,0 +1,31 @@ + +```C +napi_status napi_create_arraybuffer(napi_env env, + size_t byte_length, + void** data, + napi_value* result) +``` + +- `[in] env`: The environment that the API is invoked under. +- `[in] length`: The length in bytes of the array buffer to create. +- `[out] data`: Pointer to the underlying byte buffer of the `ArrayBuffer`. +- `[out] result`: A `napi_value` representing a JavaScript `ArrayBuffer`. + +Returns `napi_ok` if the API succeeded. + +This API returns an N-API value corresponding to a JavaScript `ArrayBuffer`. +`ArrayBuffer`s are used to represent fixed-length binary data buffers. They are +normally used as a backing-buffer for `TypedArray` objects. +The `ArrayBuffer` allocated will have an underlying byte buffer whose size is +determined by the `length` parameter that's passed in. +The underlying buffer is optionally returned back to the caller in case the +caller wants to directly manipulate the buffer. This buffer can only be +written to directly from native code. To write to this buffer from JavaScript, +a typed array or `DataView` object would need to be created. + +JavaScript `ArrayBuffer` objects are described in +[Section 24.1][] of the ECMAScript Language Specification. + diff --git a/n-api/napi_create_async_work.md b/n-api/napi_create_async_work.md new file mode 100644 index 00000000..5d5f4e0c --- /dev/null +++ b/n-api/napi_create_async_work.md @@ -0,0 +1,47 @@ + +```C +napi_status napi_create_async_work(napi_env env, + napi_value async_resource, + napi_value async_resource_name, + napi_async_execute_callback execute, + napi_async_complete_callback complete, + void* data, + napi_async_work* result); +``` + +- `[in] env`: The environment that the API is invoked under. +- `[in] async_resource`: An optional object associated with the async work + that will be passed to possible `async_hooks` [`init` hooks][]. +- `[in] async_resource_name`: Identifier for the kind of resource that is +being provided for diagnostic information exposed by the `async_hooks` API. +- `[in] execute`: The native function which should be called to execute +the logic asynchronously. The given function is called from a worker pool +thread and can execute in parallel with the main event loop thread. +- `[in] complete`: The native function which will be called when the +asynchronous logic is completed or is cancelled. The given function is called +from the main event loop thread. +- `[in] data`: User-provided data context. This will be passed back into the +execute and complete functions. +- `[out] result`: `napi_async_work*` which is the handle to the newly created +async work. + +Returns `napi_ok` if the API succeeded. + +This API allocates a work object that is used to execute logic asynchronously. +It should be freed using [`napi_delete_async_work`][] once the work is no longer +required. + +`async_resource_name` should be a null-terminated, UTF-8-encoded string. + +The `async_resource_name` identifier is provided by the user and should be +representative of the type of async work being performed. It is also recommended +to apply namespacing to the identifier, e.g. by including the module name. See +the [`async_hooks` documentation][async_hooks `type`] for more information. + diff --git a/n-api/napi_create_bigint_int64.md b/n-api/napi_create_bigint_int64.md new file mode 100644 index 00000000..f13eecf4 --- /dev/null +++ b/n-api/napi_create_bigint_int64.md @@ -0,0 +1,20 @@ + + +> Stability: 1 - Experimental + +```C +napi_status napi_create_bigint_int64(napi_env env, + int64_t value, + napi_value* result); +``` + +- `[in] env`: The environment that the API is invoked under. +- `[in] value`: Integer value to be represented in JavaScript. +- `[out] result`: A `napi_value` representing a JavaScript `BigInt`. + +Returns `napi_ok` if the API succeeded. + +This API converts the C `int64_t` type to the JavaScript `BigInt` type. + diff --git a/n-api/napi_create_bigint_uint64.md b/n-api/napi_create_bigint_uint64.md new file mode 100644 index 00000000..59050f58 --- /dev/null +++ b/n-api/napi_create_bigint_uint64.md @@ -0,0 +1,20 @@ + + +> Stability: 1 - Experimental + +```C +napi_status napi_create_bigint_uint64(napi_env env, + uint64_t value, + napi_value* result); +``` + +- `[in] env`: The environment that the API is invoked under. +- `[in] value`: Unsigned integer value to be represented in JavaScript. +- `[out] result`: A `napi_value` representing a JavaScript `BigInt`. + +Returns `napi_ok` if the API succeeded. + +This API converts the C `uint64_t` type to the JavaScript `BigInt` type. + diff --git a/n-api/napi_create_bigint_words.md b/n-api/napi_create_bigint_words.md new file mode 100644 index 00000000..940c5555 --- /dev/null +++ b/n-api/napi_create_bigint_words.md @@ -0,0 +1,29 @@ + + +> Stability: 1 - Experimental + +```C +napi_status napi_create_bigint_words(napi_env env, + int sign_bit, + size_t word_count, + const uint64_t* words, + napi_value* result); +``` + +- `[in] env`: The environment that the API is invoked under. +- `[in] sign_bit`: Determines if the resulting `BigInt` will be positive or + negative. +- `[in] word_count`: The length of the `words` array. +- `[in] words`: An array of `uint64_t` little-endian 64-bit words. +- `[out] result`: A `napi_value` representing a JavaScript `BigInt`. + +Returns `napi_ok` if the API succeeded. + +This API converts an array of unsigned 64-bit words into a single `BigInt` +value. + +The resulting `BigInt` is calculated as: (–1)`sign_bit` (`words[0]` +× (264)0 + `words[1]` × (264)1 + …) + diff --git a/n-api/napi_create_buffer.md b/n-api/napi_create_buffer.md new file mode 100644 index 00000000..5202d3d9 --- /dev/null +++ b/n-api/napi_create_buffer.md @@ -0,0 +1,21 @@ + +```C +napi_status napi_create_buffer(napi_env env, + size_t size, + void** data, + napi_value* result) +``` + +- `[in] env`: The environment that the API is invoked under. +- `[in] size`: Size in bytes of the underlying buffer. +- `[out] data`: Raw pointer to the underlying buffer. +- `[out] result`: A `napi_value` representing a `node::Buffer`. + +Returns `napi_ok` if the API succeeded. + +This API allocates a `node::Buffer` object. While this is still a +fully-supported data structure, in most cases using a `TypedArray` will suffice. + diff --git a/n-api/napi_create_buffer_copy.md b/n-api/napi_create_buffer_copy.md new file mode 100644 index 00000000..169b5712 --- /dev/null +++ b/n-api/napi_create_buffer_copy.md @@ -0,0 +1,25 @@ + +```C +napi_status napi_create_buffer_copy(napi_env env, + size_t length, + const void* data, + void** result_data, + napi_value* result) +``` + +- `[in] env`: The environment that the API is invoked under. +- `[in] size`: Size in bytes of the input buffer (should be the same as the + size of the new buffer). +- `[in] data`: Raw pointer to the underlying buffer to copy from. +- `[out] result_data`: Pointer to the new `Buffer`'s underlying data buffer. +- `[out] result`: A `napi_value` representing a `node::Buffer`. + +Returns `napi_ok` if the API succeeded. + +This API allocates a `node::Buffer` object and initializes it with data copied +from the passed-in buffer. While this is still a fully-supported data +structure, in most cases using a `TypedArray` will suffice. + diff --git a/n-api/napi_create_dataview.md b/n-api/napi_create_dataview.md new file mode 100644 index 00000000..de6ba97f --- /dev/null +++ b/n-api/napi_create_dataview.md @@ -0,0 +1,33 @@ + + +```C +napi_status napi_create_dataview(napi_env env, + size_t byte_length, + napi_value arraybuffer, + size_t byte_offset, + napi_value* result) +``` + +- `[in] env`: The environment that the API is invoked under. +- `[in] length`: Number of elements in the `DataView`. +- `[in] arraybuffer`: `ArrayBuffer` underlying the `DataView`. +- `[in] byte_offset`: The byte offset within the `ArrayBuffer` from which to + start projecting the `DataView`. +- `[out] result`: A `napi_value` representing a JavaScript `DataView`. + +Returns `napi_ok` if the API succeeded. + +This API creates a JavaScript `DataView` object over an existing `ArrayBuffer`. +`DataView` objects provide an array-like view over an underlying data buffer, +but one which allows items of different size and type in the `ArrayBuffer`. + +It is required that `byte_length + byte_offset` is less than or equal to the +size in bytes of the array passed in. If not, a `RangeError` exception is +raised. + +JavaScript `DataView` objects are described in +[Section 24.3][] of the ECMAScript Language Specification. + diff --git a/n-api/napi_create_double.md b/n-api/napi_create_double.md new file mode 100644 index 00000000..0b5d2e72 --- /dev/null +++ b/n-api/napi_create_double.md @@ -0,0 +1,20 @@ + +```C +napi_status napi_create_double(napi_env env, double value, napi_value* result) +``` + +- `[in] env`: The environment that the API is invoked under. +- `[in] value`: Double-precision value to be represented in JavaScript. +- `[out] result`: A `napi_value` representing a JavaScript `Number`. + +Returns `napi_ok` if the API succeeded. + +This API is used to convert from the C `double` type to the JavaScript +`Number` type. + +The JavaScript `Number` type is described in +[Section 6.1.6][] of the ECMAScript Language Specification. + diff --git a/n-api/napi_create_error.md b/n-api/napi_create_error.md new file mode 100644 index 00000000..679be2a8 --- /dev/null +++ b/n-api/napi_create_error.md @@ -0,0 +1,21 @@ + +```C +NAPI_EXTERN napi_status napi_create_error(napi_env env, + napi_value code, + napi_value msg, + napi_value* result); +``` +- `[in] env`: The environment that the API is invoked under. +- `[in] code`: Optional `napi_value` with the string for the error code to +be associated with the error. +- `[in] msg`: `napi_value` that references a JavaScript `String` to be +used as the message for the `Error`. +- `[out] result`: `napi_value` representing the error created. + +Returns `napi_ok` if the API succeeded. + +This API returns a JavaScript `Error` with the text provided. + diff --git a/n-api/napi_create_external.md b/n-api/napi_create_external.md new file mode 100644 index 00000000..3d892489 --- /dev/null +++ b/n-api/napi_create_external.md @@ -0,0 +1,32 @@ + +```C +napi_status napi_create_external(napi_env env, + void* data, + napi_finalize finalize_cb, + void* finalize_hint, + napi_value* result) +``` + +- `[in] env`: The environment that the API is invoked under. +- `[in] data`: Raw pointer to the external data. +- `[in] finalize_cb`: Optional callback to call when the external value +is being collected. +- `[in] finalize_hint`: Optional hint to pass to the finalize callback +during collection. +- `[out] result`: A `napi_value` representing an external value. + +Returns `napi_ok` if the API succeeded. + +This API allocates a JavaScript value with external data attached to it. This +is used to pass external data through JavaScript code, so it can be retrieved +later by native code. The API allows the caller to pass in a finalize callback, +in case the underlying native resource needs to be cleaned up when the external +JavaScript value gets collected. + +The created value is not an object, and therefore does not support additional +properties. It is considered a distinct value type: calling `napi_typeof()` with +an external value yields `napi_external`. + diff --git a/n-api/napi_create_external_arraybuffer.md b/n-api/napi_create_external_arraybuffer.md new file mode 100644 index 00000000..8a8a14d7 --- /dev/null +++ b/n-api/napi_create_external_arraybuffer.md @@ -0,0 +1,34 @@ + +```C +napi_status +napi_create_external_arraybuffer(napi_env env, + void* external_data, + size_t byte_length, + napi_finalize finalize_cb, + void* finalize_hint, + napi_value* result) +``` + +- `[in] env`: The environment that the API is invoked under. +- `[in] external_data`: Pointer to the underlying byte buffer of the +`ArrayBuffer`. +- `[in] byte_length`: The length in bytes of the underlying buffer. +- `[in] finalize_cb`: Optional callback to call when the `ArrayBuffer` is +being collected. +- `[in] finalize_hint`: Optional hint to pass to the finalize callback +during collection. +- `[out] result`: A `napi_value` representing a JavaScript `ArrayBuffer`. + +Returns `napi_ok` if the API succeeded. + +This API returns an N-API value corresponding to a JavaScript `ArrayBuffer`. +The underlying byte buffer of the `ArrayBuffer` is externally allocated and +managed. The caller must ensure that the byte buffer remains valid until the +finalize callback is called. + +JavaScript `ArrayBuffer`s are described in +[Section 24.1][] of the ECMAScript Language Specification. + diff --git a/n-api/napi_create_external_buffer.md b/n-api/napi_create_external_buffer.md new file mode 100644 index 00000000..d45e1469 --- /dev/null +++ b/n-api/napi_create_external_buffer.md @@ -0,0 +1,31 @@ + +```C +napi_status napi_create_external_buffer(napi_env env, + size_t length, + void* data, + napi_finalize finalize_cb, + void* finalize_hint, + napi_value* result) +``` + +- `[in] env`: The environment that the API is invoked under. +- `[in] length`: Size in bytes of the input buffer (should be the same as +the size of the new buffer). +- `[in] data`: Raw pointer to the underlying buffer to copy from. +- `[in] finalize_cb`: Optional callback to call when the `ArrayBuffer` is +being collected. +- `[in] finalize_hint`: Optional hint to pass to the finalize callback +during collection. +- `[out] result`: A `napi_value` representing a `node::Buffer`. + +Returns `napi_ok` if the API succeeded. + +This API allocates a `node::Buffer` object and initializes it with data +backed by the passed in buffer. While this is still a fully-supported data +structure, in most cases using a `TypedArray` will suffice. + +For Node.js >=4 `Buffers` are `Uint8Array`s. + diff --git a/api-docs/3e2490006544f214fb01d85bbc0fa964acc930b39d490e5160fc418b16685833.md b/n-api/napi_create_function.md similarity index 100% rename from api-docs/3e2490006544f214fb01d85bbc0fa964acc930b39d490e5160fc418b16685833.md rename to n-api/napi_create_function.md diff --git a/n-api/napi_create_function_1.md b/n-api/napi_create_function_1.md new file mode 100644 index 00000000..c21aa30c --- /dev/null +++ b/n-api/napi_create_function_1.md @@ -0,0 +1,66 @@ + +```C +napi_status napi_create_function(napi_env env, + const char* utf8name, + napi_callback cb, + void* data, + napi_value* result); +``` + +- `[in] env`: The environment that the API is invoked under. +- `[in] utf8Name`: The name of the function encoded as UTF8. This is visible +within JavaScript as the new function object's `name` property. +- `[in] cb`: The native function which should be called when this function +object is invoked. +- `[in] data`: User-provided data context. This will be passed back into the +function when invoked later. +- `[out] result`: `napi_value` representing the JavaScript function object for +the newly created function. + +Returns `napi_ok` if the API succeeded. + +This API allows an add-on author to create a function object in native code. +This is the primary mechanism to allow calling *into* the add-on's native code +*from* JavaScript. + +The newly created function is not automatically visible from script after this +call. Instead, a property must be explicitly set on any object that is visible +to JavaScript, in order for the function to be accessible from script. + +In order to expose a function as part of the +add-on's module exports, set the newly created function on the exports +object. A sample module might look as follows: +```C +napi_value SayHello(napi_env env, napi_callback_info info) { + printf("Hello\n"); + return NULL; +} + +napi_value Init(napi_env env, napi_value exports) { + napi_status status; + + napi_value fn; + status = napi_create_function(env, NULL, 0, SayHello, NULL, &fn); + if (status != napi_ok) return NULL; + + status = napi_set_named_property(env, exports, "sayHello", fn); + if (status != napi_ok) return NULL; + + return exports; +} + +NAPI_MODULE(NODE_GYP_MODULE_NAME, Init) +``` + +Given the above code, the add-on can be used from JavaScript as follows: +```js +const myaddon = require('./addon'); +myaddon.sayHello(); +``` + +The string passed to require is not necessarily the name passed into +`NAPI_MODULE` in the earlier snippet but the name of the target in `binding.gyp` +responsible for creating the `.node` file. + diff --git a/n-api/napi_create_int32.md b/n-api/napi_create_int32.md new file mode 100644 index 00000000..deb4d2c9 --- /dev/null +++ b/n-api/napi_create_int32.md @@ -0,0 +1,20 @@ + +```C +napi_status napi_create_int32(napi_env env, int32_t value, napi_value* result) +``` + +- `[in] env`: The environment that the API is invoked under. +- `[in] value`: Integer value to be represented in JavaScript. +- `[out] result`: A `napi_value` representing a JavaScript `Number`. + +Returns `napi_ok` if the API succeeded. + +This API is used to convert from the C `int32_t` type to the JavaScript +`Number` type. + +The JavaScript `Number` type is described in +[Section 6.1.6][] of the ECMAScript Language Specification. + diff --git a/api-docs/4f2706b464478595b53de36706b68fa861efec02f84ea2d1d54bb076f5965fd4.md b/n-api/napi_create_int64.md similarity index 100% rename from api-docs/4f2706b464478595b53de36706b68fa861efec02f84ea2d1d54bb076f5965fd4.md rename to n-api/napi_create_int64.md diff --git a/api-docs/ea6d5336ee41a37f617d07f87cf66d46a16e71a6d1cc1809deca71fe3c613346.md b/n-api/napi_create_object.md similarity index 100% rename from api-docs/ea6d5336ee41a37f617d07f87cf66d46a16e71a6d1cc1809deca71fe3c613346.md rename to n-api/napi_create_object.md diff --git a/n-api/napi_create_promise.md b/n-api/napi_create_promise.md new file mode 100644 index 00000000..f71e20cd --- /dev/null +++ b/n-api/napi_create_promise.md @@ -0,0 +1,20 @@ + +```C +napi_status napi_create_promise(napi_env env, + napi_deferred* deferred, + napi_value* promise); +``` + +- `[in] env`: The environment that the API is invoked under. +- `[out] deferred`: A newly created deferred object which can later be passed to +`napi_resolve_deferred()` or `napi_reject_deferred()` to resolve resp. reject +the associated promise. +- `[out] promise`: The JavaScript promise associated with the deferred object. + +Returns `napi_ok` if the API succeeded. + +This API creates a deferred object and a JavaScript promise. + diff --git a/n-api/napi_create_range_error.md b/n-api/napi_create_range_error.md new file mode 100644 index 00000000..67312443 --- /dev/null +++ b/n-api/napi_create_range_error.md @@ -0,0 +1,21 @@ + +```C +NAPI_EXTERN napi_status napi_create_range_error(napi_env env, + napi_value code, + napi_value msg, + napi_value* result); +``` +- `[in] env`: The environment that the API is invoked under. +- `[in] code`: Optional `napi_value` with the string for the error code to +be associated with the error. +- `[in] msg`: `napi_value` that references a JavaScript `String` to be +used as the message for the `Error`. +- `[out] result`: `napi_value` representing the error created. + +Returns `napi_ok` if the API succeeded. + +This API returns a JavaScript `RangeError` with the text provided. + diff --git a/n-api/napi_create_reference.md b/n-api/napi_create_reference.md new file mode 100644 index 00000000..ad07d1cc --- /dev/null +++ b/n-api/napi_create_reference.md @@ -0,0 +1,22 @@ + +```C +NAPI_EXTERN napi_status napi_create_reference(napi_env env, + napi_value value, + int initial_refcount, + napi_ref* result); +``` + +- `[in] env`: The environment that the API is invoked under. +- `[in] value`: `napi_value` representing the `Object` to which we want +a reference. +- `[in] initial_refcount`: Initial reference count for the new reference. +- `[out] result`: `napi_ref` pointing to the new reference. + +Returns `napi_ok` if the API succeeded. + +This API create a new reference with the specified reference count +to the `Object` passed in. + diff --git a/n-api/napi_create_string_latin1.md b/n-api/napi_create_string_latin1.md new file mode 100644 index 00000000..e20f9963 --- /dev/null +++ b/n-api/napi_create_string_latin1.md @@ -0,0 +1,25 @@ + +```C +napi_status napi_create_string_latin1(napi_env env, + const char* str, + size_t length, + napi_value* result); +``` + +- `[in] env`: The environment that the API is invoked under. +- `[in] str`: Character buffer representing an ISO-8859-1-encoded string. +- `[in] length`: The length of the string in bytes, or +`NAPI_AUTO_LENGTH` if it is null-terminated. +- `[out] result`: A `napi_value` representing a JavaScript `String`. + +Returns `napi_ok` if the API succeeded. + +This API creates a JavaScript `String` object from an ISO-8859-1-encoded C +string. The native string is copied. + +The JavaScript `String` type is described in +[Section 6.1.4][] of the ECMAScript Language Specification. + diff --git a/n-api/napi_create_string_utf16.md b/n-api/napi_create_string_utf16.md new file mode 100644 index 00000000..d3cd0ecb --- /dev/null +++ b/n-api/napi_create_string_utf16.md @@ -0,0 +1,25 @@ + +```C +napi_status napi_create_string_utf16(napi_env env, + const char16_t* str, + size_t length, + napi_value* result) +``` + +- `[in] env`: The environment that the API is invoked under. +- `[in] str`: Character buffer representing a UTF16-LE-encoded string. +- `[in] length`: The length of the string in two-byte code units, or +`NAPI_AUTO_LENGTH` if it is null-terminated. +- `[out] result`: A `napi_value` representing a JavaScript `String`. + +Returns `napi_ok` if the API succeeded. + +This API creates a JavaScript `String` object from a UTF16-LE-encoded C string. +The native string is copied. + +The JavaScript `String` type is described in +[Section 6.1.4][] of the ECMAScript Language Specification. + diff --git a/n-api/napi_create_string_utf8.md b/n-api/napi_create_string_utf8.md new file mode 100644 index 00000000..292f8416 --- /dev/null +++ b/n-api/napi_create_string_utf8.md @@ -0,0 +1,25 @@ + +```C +napi_status napi_create_string_utf8(napi_env env, + const char* str, + size_t length, + napi_value* result) +``` + +- `[in] env`: The environment that the API is invoked under. +- `[in] str`: Character buffer representing a UTF8-encoded string. +- `[in] length`: The length of the string in bytes, or `NAPI_AUTO_LENGTH` +if it is null-terminated. +- `[out] result`: A `napi_value` representing a JavaScript `String`. + +Returns `napi_ok` if the API succeeded. + +This API creates a JavaScript `String` object from a UTF8-encoded C string. +The native string is copied. + +The JavaScript `String` type is described in +[Section 6.1.4][] of the ECMAScript Language Specification. + diff --git a/api-docs/7729ef83f2346532e112ff58b908be49e4fd8d170492070ff26fb7a04f4eba33.md b/n-api/napi_create_symbol.md similarity index 100% rename from api-docs/7729ef83f2346532e112ff58b908be49e4fd8d170492070ff26fb7a04f4eba33.md rename to n-api/napi_create_symbol.md diff --git a/n-api/napi_create_threadsafe_function.md b/n-api/napi_create_threadsafe_function.md new file mode 100644 index 00000000..4db81274 --- /dev/null +++ b/n-api/napi_create_threadsafe_function.md @@ -0,0 +1,42 @@ + +> Stability: 2 - Stable + + +```C +NAPI_EXTERN napi_status +napi_create_threadsafe_function(napi_env env, + napi_value func, + napi_value async_resource, + napi_value async_resource_name, + size_t max_queue_size, + size_t initial_thread_count, + void* thread_finalize_data, + napi_finalize thread_finalize_cb, + void* context, + napi_threadsafe_function_call_js call_js_cb, + napi_threadsafe_function* result); +``` + +- `[in] env`: The environment that the API is invoked under. +- `[in] func`: The JavaScript function to call from another thread. +- `[in] async_resource`: An optional object associated with the async work that +will be passed to possible `async_hooks` [`init` hooks][]. +- `[in] async_resource_name`: A JavaScript string to provide an identifier for +the kind of resource that is being provided for diagnostic information exposed +by the `async_hooks` API. +- `[in] max_queue_size`: Maximum size of the queue. `0` for no limit. +- `[in] initial_thread_count`: The initial number of threads, including the main +thread, which will be making use of this function. +- `[in] thread_finalize_data`: Optional data to be passed to `thread_finalize_cb`. +- `[in] thread_finalize_cb`: Optional function to call when the +`napi_threadsafe_function` is being destroyed. +- `[in] context`: Optional data to attach to the resulting +`napi_threadsafe_function`. +- `[in] call_js_cb`: Optional callback which calls the JavaScript function in +response to a call on a different thread. This callback will be called on the +main thread. If not given, the JavaScript function will be called with no +parameters and with `undefined` as its `this` value. +- `[out] result`: The asynchronous thread-safe JavaScript function. + diff --git a/n-api/napi_create_type_error.md b/n-api/napi_create_type_error.md new file mode 100644 index 00000000..5daaa9a4 --- /dev/null +++ b/n-api/napi_create_type_error.md @@ -0,0 +1,21 @@ + +```C +NAPI_EXTERN napi_status napi_create_type_error(napi_env env, + napi_value code, + napi_value msg, + napi_value* result); +``` +- `[in] env`: The environment that the API is invoked under. +- `[in] code`: Optional `napi_value` with the string for the error code to +be associated with the error. +- `[in] msg`: `napi_value` that references a JavaScript `String` to be +used as the message for the `Error`. +- `[out] result`: `napi_value` representing the error created. + +Returns `napi_ok` if the API succeeded. + +This API returns a JavaScript `TypeError` with the text provided. + diff --git a/n-api/napi_create_typedarray.md b/n-api/napi_create_typedarray.md new file mode 100644 index 00000000..a99ac537 --- /dev/null +++ b/n-api/napi_create_typedarray.md @@ -0,0 +1,35 @@ + +```C +napi_status napi_create_typedarray(napi_env env, + napi_typedarray_type type, + size_t length, + napi_value arraybuffer, + size_t byte_offset, + napi_value* result) +``` + +- `[in] env`: The environment that the API is invoked under. +- `[in] type`: Scalar datatype of the elements within the `TypedArray`. +- `[in] length`: Number of elements in the `TypedArray`. +- `[in] arraybuffer`: `ArrayBuffer` underlying the typed array. +- `[in] byte_offset`: The byte offset within the `ArrayBuffer` from which to +start projecting the `TypedArray`. +- `[out] result`: A `napi_value` representing a JavaScript `TypedArray`. + +Returns `napi_ok` if the API succeeded. + +This API creates a JavaScript `TypedArray` object over an existing +`ArrayBuffer`. `TypedArray` objects provide an array-like view over an +underlying data buffer where each element has the same underlying binary scalar +datatype. + +It's required that `(length * size_of_element) + byte_offset` should +be <= the size in bytes of the array passed in. If not, a `RangeError` exception +is raised. + +JavaScript `TypedArray` objects are described in +[Section 22.2][] of the ECMAScript Language Specification. + diff --git a/n-api/napi_create_uint32.md b/n-api/napi_create_uint32.md new file mode 100644 index 00000000..a9f7d5d2 --- /dev/null +++ b/n-api/napi_create_uint32.md @@ -0,0 +1,20 @@ + +```C +napi_status napi_create_uint32(napi_env env, uint32_t value, napi_value* result) +``` + +- `[in] env`: The environment that the API is invoked under. +- `[in] value`: Unsigned integer value to be represented in JavaScript. +- `[out] result`: A `napi_value` representing a JavaScript `Number`. + +Returns `napi_ok` if the API succeeded. + +This API is used to convert from the C `uint32_t` type to the JavaScript +`Number` type. + +The JavaScript `Number` type is described in +[Section 6.1.6][] of the ECMAScript Language Specification. + diff --git a/n-api/napi_define_class.md b/n-api/napi_define_class.md new file mode 100644 index 00000000..f6c95007 --- /dev/null +++ b/n-api/napi_define_class.md @@ -0,0 +1,62 @@ + +```C +napi_status napi_define_class(napi_env env, + const char* utf8name, + size_t length, + napi_callback constructor, + void* data, + size_t property_count, + const napi_property_descriptor* properties, + napi_value* result); +``` + + - `[in] env`: The environment that the API is invoked under. + - `[in] utf8name`: Name of the JavaScript constructor function; this is + not required to be the same as the C++ class name, though it is recommended + for clarity. + - `[in] length`: The length of the `utf8name` in bytes, or `NAPI_AUTO_LENGTH` +if it is null-terminated. + - `[in] constructor`: Callback function that handles constructing instances + of the class. (This should be a static method on the class, not an actual + C++ constructor function.) + - `[in] data`: Optional data to be passed to the constructor callback as + the `data` property of the callback info. + - `[in] property_count`: Number of items in the `properties` array argument. + - `[in] properties`: Array of property descriptors describing static and + instance data properties, accessors, and methods on the class + See `napi_property_descriptor`. + - `[out] result`: A `napi_value` representing the constructor function for + the class. + +Returns `napi_ok` if the API succeeded. + +Defines a JavaScript class that corresponds to a C++ class, including: + - A JavaScript constructor function that has the class name and invokes the + provided C++ constructor callback. + - Properties on the constructor function corresponding to _static_ data + properties, accessors, and methods of the C++ class (defined by + property descriptors with the `napi_static` attribute). + - Properties on the constructor function's `prototype` object corresponding to + _non-static_ data properties, accessors, and methods of the C++ class + (defined by property descriptors without the `napi_static` attribute). + +The C++ constructor callback should be a static method on the class that calls +the actual class constructor, then wraps the new C++ instance in a JavaScript +object, and returns the wrapper object. See `napi_wrap()` for details. + +The JavaScript constructor function returned from [`napi_define_class`][] is +often saved and used later, to construct new instances of the class from native +code, and/or check whether provided values are instances of the class. In that +case, to prevent the function value from being garbage-collected, create a +persistent reference to it using [`napi_create_reference`][] and ensure the +reference count is kept >= 1. + +Any non-`NULL` data which is passed to this API via the `data` parameter or via +the `data` field of the `napi_property_descriptor` array items can be associated +with the resulting JavaScript constructor (which is returned in the `result` +parameter) and freed whenever the class is garbage-collected by passing both +the JavaScript function and the data to [`napi_add_finalizer`][]. + diff --git a/n-api/napi_define_properties.md b/n-api/napi_define_properties.md new file mode 100644 index 00000000..3b57bcbe --- /dev/null +++ b/n-api/napi_define_properties.md @@ -0,0 +1,25 @@ + +```C +napi_status napi_define_properties(napi_env env, + napi_value object, + size_t property_count, + const napi_property_descriptor* properties); +``` + +- `[in] env`: The environment that the N-API call is invoked under. +- `[in] object`: The object from which to retrieve the properties. +- `[in] property_count`: The number of elements in the `properties` array. +- `[in] properties`: The array of property descriptors. + +Returns `napi_ok` if the API succeeded. + +This method allows the efficient definition of multiple properties on a given +object. The properties are defined using property descriptors (see +[`napi_property_descriptor`][]). Given an array of such property descriptors, +this API will set the properties on the object one at a time, as defined by +`DefineOwnProperty()` (described in [Section 9.1.6][] of the ECMA262 +specification). + diff --git a/n-api/napi_delete_async_work.md b/n-api/napi_delete_async_work.md new file mode 100644 index 00000000..770446bb --- /dev/null +++ b/n-api/napi_delete_async_work.md @@ -0,0 +1,18 @@ + +```C +napi_status napi_delete_async_work(napi_env env, + napi_async_work work); +``` + +- `[in] env`: The environment that the API is invoked under. +- `[in] work`: The handle returned by the call to `napi_create_async_work`. + +Returns `napi_ok` if the API succeeded. + +This API frees a previously allocated work object. + +This API can be called even if there is a pending JavaScript exception. + diff --git a/n-api/napi_delete_element.md b/n-api/napi_delete_element.md new file mode 100644 index 00000000..199ebbc0 --- /dev/null +++ b/n-api/napi_delete_element.md @@ -0,0 +1,21 @@ + +```C +napi_status napi_delete_element(napi_env env, + napi_value object, + uint32_t index, + bool* result); +``` + +- `[in] env`: The environment that the N-API call is invoked under. +- `[in] object`: The object to query. +- `[in] index`: The index of the property to delete. +- `[out] result`: Whether the element deletion succeeded or not. `result` can +optionally be ignored by passing `NULL`. + +Returns `napi_ok` if the API succeeded. + +This API attempts to delete the specified `index` from `object`. + diff --git a/n-api/napi_delete_property.md b/n-api/napi_delete_property.md new file mode 100644 index 00000000..12f70b9c --- /dev/null +++ b/n-api/napi_delete_property.md @@ -0,0 +1,21 @@ + +```C +napi_status napi_delete_property(napi_env env, + napi_value object, + napi_value key, + bool* result); +``` + +- `[in] env`: The environment that the N-API call is invoked under. +- `[in] object`: The object to query. +- `[in] key`: The name of the property to delete. +- `[out] result`: Whether the property deletion succeeded or not. `result` can +optionally be ignored by passing `NULL`. + +Returns `napi_ok` if the API succeeded. + +This API attempts to delete the `key` own property from `object`. + diff --git a/n-api/napi_delete_reference.md b/n-api/napi_delete_reference.md new file mode 100644 index 00000000..b5229c31 --- /dev/null +++ b/n-api/napi_delete_reference.md @@ -0,0 +1,17 @@ + +```C +NAPI_EXTERN napi_status napi_delete_reference(napi_env env, napi_ref ref); +``` + +- `[in] env`: The environment that the API is invoked under. +- `[in] ref`: `napi_ref` to be deleted. + +Returns `napi_ok` if the API succeeded. + +This API deletes the reference passed in. + +This API can be called even if there is a pending JavaScript exception. + diff --git a/n-api/napi_env.md b/n-api/napi_env.md new file mode 100644 index 00000000..89e21b0c --- /dev/null +++ b/n-api/napi_env.md @@ -0,0 +1,8 @@ +`napi_env` is used to represent a context that the underlying N-API +implementation can use to persist VM-specific state. This structure is passed +to native functions when they're invoked, and it must be passed back when +making N-API calls. Specifically, the same `napi_env` that was passed in when +the initial native function was called must be passed to any subsequent +nested N-API calls. Caching the `napi_env` for the purpose of general reuse is +not allowed. + diff --git a/n-api/napi_escapable_handle_scope.md b/n-api/napi_escapable_handle_scope.md new file mode 100644 index 00000000..97b18e7c --- /dev/null +++ b/n-api/napi_escapable_handle_scope.md @@ -0,0 +1,3 @@ +Escapable handle scopes are a special type of handle scope to return values +created within a particular handle scope to a parent scope. + diff --git a/n-api/napi_escape_handle.md b/n-api/napi_escape_handle.md new file mode 100644 index 00000000..4bd13b14 --- /dev/null +++ b/n-api/napi_escape_handle.md @@ -0,0 +1,26 @@ + +```C +napi_status napi_escape_handle(napi_env env, + napi_escapable_handle_scope scope, + napi_value escapee, + napi_value* result); +``` + +- `[in] env`: The environment that the API is invoked under. +- `[in] scope`: `napi_value` representing the current scope. +- `[in] escapee`: `napi_value` representing the JavaScript `Object` to be +escaped. +- `[out] result`: `napi_value` representing the handle to the escaped +`Object` in the outer scope. + +Returns `napi_ok` if the API succeeded. + +This API promotes the handle to the JavaScript object so that it is valid +for the lifetime of the outer scope. It can only be called once per scope. +If it is called more than once an error will be returned. + +This API can be called even if there is a pending JavaScript exception. + diff --git a/n-api/napi_extended_error_info.md b/n-api/napi_extended_error_info.md new file mode 100644 index 00000000..2446952e --- /dev/null +++ b/n-api/napi_extended_error_info.md @@ -0,0 +1,19 @@ +```C +typedef struct { + const char* error_message; + void* engine_reserved; + uint32_t engine_error_code; + napi_status error_code; +} napi_extended_error_info; +``` + +- `error_message`: UTF8-encoded string containing a VM-neutral description of + the error. +- `engine_reserved`: Reserved for VM-specific error details. This is currently + not implemented for any VM. +- `engine_error_code`: VM-specific error code. This is currently + not implemented for any VM. +- `error_code`: The N-API status code that originated with the last error. + +See the [Error Handling][] section for additional information. + diff --git a/n-api/napi_fatal_error.md b/n-api/napi_fatal_error.md new file mode 100644 index 00000000..e84c9de1 --- /dev/null +++ b/n-api/napi_fatal_error.md @@ -0,0 +1,23 @@ + +```C +NAPI_NO_RETURN void napi_fatal_error(const char* location, + size_t location_len, + const char* message, + size_t message_len); +``` + +- `[in] location`: Optional location at which the error occurred. +- `[in] location_len`: The length of the location in bytes, or +`NAPI_AUTO_LENGTH` if it is null-terminated. +- `[in] message`: The message associated with the error. +- `[in] message_len`: The length of the message in bytes, or +`NAPI_AUTO_LENGTH` if it is +null-terminated. + +The function call does not return, the process will be terminated. + +This API can be called even if there is a pending JavaScript exception. + diff --git a/n-api/napi_fatal_exception.md b/n-api/napi_fatal_exception.md new file mode 100644 index 00000000..52e0865f --- /dev/null +++ b/n-api/napi_fatal_exception.md @@ -0,0 +1,15 @@ + + +```C +napi_status napi_fatal_exception(napi_env env, napi_value err); +``` + +- `[in] env`: The environment that the API is invoked under. +- `[in] err`: The error that is passed to `'uncaughtException'`. + +Trigger an `'uncaughtException'` in JavaScript. Useful if an async +callback throws an exception with no way to recover. + diff --git a/n-api/napi_finalize.md b/n-api/napi_finalize.md new file mode 100644 index 00000000..bd5d9c7a --- /dev/null +++ b/n-api/napi_finalize.md @@ -0,0 +1,13 @@ +Function pointer type for add-on provided functions that allow the user to be +notified when externally-owned data is ready to be cleaned up because the +object with which it was associated with, has been garbage-collected. The user +must provide a function satisfying the following signature which would get +called upon the object's collection. Currently, `napi_finalize` can be used for +finding out when objects that have external data are collected. + +```C +typedef void (*napi_finalize)(napi_env env, + void* finalize_data, + void* finalize_hint); +``` + diff --git a/n-api/napi_get_and_clear_last_exception.md b/n-api/napi_get_and_clear_last_exception.md new file mode 100644 index 00000000..711159c7 --- /dev/null +++ b/n-api/napi_get_and_clear_last_exception.md @@ -0,0 +1,18 @@ + +```C +napi_status napi_get_and_clear_last_exception(napi_env env, + napi_value* result); +``` + +- `[in] env`: The environment that the API is invoked under. +- `[out] result`: The exception if one is pending, NULL otherwise. + +Returns `napi_ok` if the API succeeded. + +This API returns true if an exception is pending. + +This API can be called even if there is a pending JavaScript exception. + diff --git a/api-docs/a117879e9fecce14f072a7f585ce758d9c9f99eaf2054439e1302b38cc418d95.md b/n-api/napi_get_array_length.md similarity index 100% rename from api-docs/a117879e9fecce14f072a7f585ce758d9c9f99eaf2054439e1302b38cc418d95.md rename to n-api/napi_get_array_length.md diff --git a/n-api/napi_get_arraybuffer_info.md b/n-api/napi_get_arraybuffer_info.md new file mode 100644 index 00000000..e1d143d4 --- /dev/null +++ b/n-api/napi_get_arraybuffer_info.md @@ -0,0 +1,29 @@ + +```C +napi_status napi_get_arraybuffer_info(napi_env env, + napi_value arraybuffer, + void** data, + size_t* byte_length) +``` + +- `[in] env`: The environment that the API is invoked under. +- `[in] arraybuffer`: `napi_value` representing the `ArrayBuffer` being queried. +- `[out] data`: The underlying data buffer of the `ArrayBuffer`. +- `[out] byte_length`: Length in bytes of the underlying data buffer. + +Returns `napi_ok` if the API succeeded. + +This API is used to retrieve the underlying data buffer of an `ArrayBuffer` and +its length. + +*WARNING*: Use caution while using this API. The lifetime of the underlying data +buffer is managed by the `ArrayBuffer` even after it's returned. A +possible safe way to use this API is in conjunction with +[`napi_create_reference`][], which can be used to guarantee control over the +lifetime of the `ArrayBuffer`. It's also safe to use the returned data buffer +within the same callback as long as there are no calls to other APIs that might +trigger a GC. + diff --git a/n-api/napi_get_boolean.md b/n-api/napi_get_boolean.md new file mode 100644 index 00000000..ea626c19 --- /dev/null +++ b/n-api/napi_get_boolean.md @@ -0,0 +1,18 @@ + +```C +napi_status napi_get_boolean(napi_env env, bool value, napi_value* result) +``` + +- `[in] env`: The environment that the API is invoked under. +- `[in] value`: The value of the boolean to retrieve. +- `[out] result`: `napi_value` representing JavaScript `Boolean` singleton to +retrieve. + +Returns `napi_ok` if the API succeeded. + +This API is used to return the JavaScript singleton object that is used to +represent the given boolean value. + diff --git a/n-api/napi_get_buffer_info.md b/n-api/napi_get_buffer_info.md new file mode 100644 index 00000000..3ba59184 --- /dev/null +++ b/n-api/napi_get_buffer_info.md @@ -0,0 +1,24 @@ + +```C +napi_status napi_get_buffer_info(napi_env env, + napi_value value, + void** data, + size_t* length) +``` + +- `[in] env`: The environment that the API is invoked under. +- `[in] value`: `napi_value` representing the `node::Buffer` being queried. +- `[out] data`: The underlying data buffer of the `node::Buffer`. +- `[out] length`: Length in bytes of the underlying data buffer. + +Returns `napi_ok` if the API succeeded. + +This API is used to retrieve the underlying data buffer of a `node::Buffer` +and it's length. + +*Warning*: Use caution while using this API since the underlying data buffer's +lifetime is not guaranteed if it's managed by the VM. + diff --git a/n-api/napi_get_cb_info.md b/n-api/napi_get_cb_info.md new file mode 100644 index 00000000..9cfe8db5 --- /dev/null +++ b/n-api/napi_get_cb_info.md @@ -0,0 +1,30 @@ + +```C +napi_status napi_get_cb_info(napi_env env, + napi_callback_info cbinfo, + size_t* argc, + napi_value* argv, + napi_value* thisArg, + void** data) +``` + +- `[in] env`: The environment that the API is invoked under. +- `[in] cbinfo`: The callback info passed into the callback function. +- `[in-out] argc`: Specifies the size of the provided `argv` array +and receives the actual count of arguments. +- `[out] argv`: Buffer to which the `napi_value` representing the +arguments are copied. If there are more arguments than the provided +count, only the requested number of arguments are copied. If there are fewer +arguments provided than claimed, the rest of `argv` is filled with `napi_value` +values that represent `undefined`. +- `[out] this`: Receives the JavaScript `this` argument for the call. +- `[out] data`: Receives the data pointer for the callback. + +Returns `napi_ok` if the API succeeded. + +This method is used within a callback function to retrieve details about the +call like the arguments and the `this` pointer from a given callback info. + diff --git a/n-api/napi_get_dataview_info.md b/n-api/napi_get_dataview_info.md new file mode 100644 index 00000000..268000dc --- /dev/null +++ b/n-api/napi_get_dataview_info.md @@ -0,0 +1,27 @@ + + +```C +napi_status napi_get_dataview_info(napi_env env, + napi_value dataview, + size_t* byte_length, + void** data, + napi_value* arraybuffer, + size_t* byte_offset) +``` + +- `[in] env`: The environment that the API is invoked under. +- `[in] dataview`: `napi_value` representing the `DataView` whose + properties to query. +- `[out] byte_length`: `Number` of bytes in the `DataView`. +- `[out] data`: The data buffer underlying the `DataView`. +- `[out] arraybuffer`: `ArrayBuffer` underlying the `DataView`. +- `[out] byte_offset`: The byte offset within the data buffer from which + to start projecting the `DataView`. + +Returns `napi_ok` if the API succeeded. + +This API returns various properties of a `DataView`. + diff --git a/n-api/napi_get_element.md b/n-api/napi_get_element.md new file mode 100644 index 00000000..744958dd --- /dev/null +++ b/n-api/napi_get_element.md @@ -0,0 +1,20 @@ + +```C +napi_status napi_get_element(napi_env env, + napi_value object, + uint32_t index, + napi_value* result); +``` + +- `[in] env`: The environment that the N-API call is invoked under. +- `[in] object`: The object from which to retrieve the property. +- `[in] index`: The index of the property to get. +- `[out] result`: The value of the property. + +Returns `napi_ok` if the API succeeded. + +This API gets the element at the requested index. + diff --git a/n-api/napi_get_global.md b/n-api/napi_get_global.md new file mode 100644 index 00000000..8d6487d4 --- /dev/null +++ b/n-api/napi_get_global.md @@ -0,0 +1,15 @@ + +```C +napi_status napi_get_global(napi_env env, napi_value* result) +``` + +- `[in] env`: The environment that the API is invoked under. +- `[out] result`: `napi_value` representing JavaScript `global` object. + +Returns `napi_ok` if the API succeeded. + +This API returns the `global` object. + diff --git a/n-api/napi_get_last_error_info.md b/n-api/napi_get_last_error_info.md new file mode 100644 index 00000000..d5a53de9 --- /dev/null +++ b/n-api/napi_get_last_error_info.md @@ -0,0 +1,27 @@ + +```C +napi_status +napi_get_last_error_info(napi_env env, + const napi_extended_error_info** result); +``` +- `[in] env`: The environment that the API is invoked under. +- `[out] result`: The `napi_extended_error_info` structure with more +information about the error. + +Returns `napi_ok` if the API succeeded. + +This API retrieves a `napi_extended_error_info` structure with information +about the last error that occurred. + +The content of the `napi_extended_error_info` returned is only valid up until +an n-api function is called on the same `env`. + +Do not rely on the content or format of any of the extended information as it +is not subject to SemVer and may change at any time. It is intended only for +logging purposes. + +This API can be called even if there is a pending JavaScript exception. + diff --git a/n-api/napi_get_named_property.md b/n-api/napi_get_named_property.md new file mode 100644 index 00000000..9cbb6b56 --- /dev/null +++ b/n-api/napi_get_named_property.md @@ -0,0 +1,21 @@ + +```C +napi_status napi_get_named_property(napi_env env, + napi_value object, + const char* utf8Name, + napi_value* result); +``` + +- `[in] env`: The environment that the N-API call is invoked under. +- `[in] object`: The object from which to retrieve the property. +- `[in] utf8Name`: The name of the property to get. +- `[out] result`: The value of the property. + +Returns `napi_ok` if the API succeeded. + +This method is equivalent to calling [`napi_get_property`][] with a `napi_value` +created from the string passed in as `utf8Name`. + diff --git a/n-api/napi_get_new_target.md b/n-api/napi_get_new_target.md new file mode 100644 index 00000000..2925bb04 --- /dev/null +++ b/n-api/napi_get_new_target.md @@ -0,0 +1,19 @@ + +```C +napi_status napi_get_new_target(napi_env env, + napi_callback_info cbinfo, + napi_value* result) +``` + +- `[in] env`: The environment that the API is invoked under. +- `[in] cbinfo`: The callback info passed into the callback function. +- `[out] result`: The `new.target` of the constructor call. + +Returns `napi_ok` if the API succeeded. + +This API returns the `new.target` of the constructor call. If the current +callback is not a constructor call, the result is `NULL`. + diff --git a/n-api/napi_get_node_version.md b/n-api/napi_get_node_version.md new file mode 100644 index 00000000..49795719 --- /dev/null +++ b/n-api/napi_get_node_version.md @@ -0,0 +1,28 @@ + + +```C +typedef struct { + uint32_t major; + uint32_t minor; + uint32_t patch; + const char* release; +} napi_node_version; + +napi_status napi_get_node_version(napi_env env, + const napi_node_version** version); +``` + +- `[in] env`: The environment that the API is invoked under. +- `[out] version`: A pointer to version information for Node.js itself. + +Returns `napi_ok` if the API succeeded. + +This function fills the `version` struct with the major, minor, and patch +version of Node.js that is currently running, and the `release` field with the +value of [`process.release.name`][`process.release`]. + +The returned buffer is statically allocated and does not need to be freed. + diff --git a/n-api/napi_get_null.md b/n-api/napi_get_null.md new file mode 100644 index 00000000..708b8568 --- /dev/null +++ b/n-api/napi_get_null.md @@ -0,0 +1,15 @@ + +```C +napi_status napi_get_null(napi_env env, napi_value* result) +``` + +- `[in] env`: The environment that the API is invoked under. +- `[out] result`: `napi_value` representing JavaScript `null` object. + +Returns `napi_ok` if the API succeeded. + +This API returns the `null` object. + diff --git a/n-api/napi_get_property.md b/n-api/napi_get_property.md new file mode 100644 index 00000000..14775834 --- /dev/null +++ b/n-api/napi_get_property.md @@ -0,0 +1,20 @@ + +```C +napi_status napi_get_property(napi_env env, + napi_value object, + napi_value key, + napi_value* result); +``` + +- `[in] env`: The environment that the N-API call is invoked under. +- `[in] object`: The object from which to retrieve the property. +- `[in] key`: The name of the property to retrieve. +- `[out] result`: The value of the property. + +Returns `napi_ok` if the API succeeded. + +This API gets the requested property from the `Object` passed in. + diff --git a/n-api/napi_get_property_names.md b/n-api/napi_get_property_names.md new file mode 100644 index 00000000..634cc132 --- /dev/null +++ b/n-api/napi_get_property_names.md @@ -0,0 +1,23 @@ + +```C +napi_status napi_get_property_names(napi_env env, + napi_value object, + napi_value* result); +``` + +- `[in] env`: The environment that the N-API call is invoked under. +- `[in] object`: The object from which to retrieve the properties. +- `[out] result`: A `napi_value` representing an array of JavaScript values +that represent the property names of the object. The API can be used to +iterate over `result` using [`napi_get_array_length`][] +and [`napi_get_element`][]. + +Returns `napi_ok` if the API succeeded. + +This API returns the names of the enumerable properties of `object` as an array +of strings. The properties of `object` whose key is a symbol will not be +included. + diff --git a/n-api/napi_get_prototype.md b/n-api/napi_get_prototype.md new file mode 100644 index 00000000..1f84643e --- /dev/null +++ b/n-api/napi_get_prototype.md @@ -0,0 +1,18 @@ + +```C +napi_status napi_get_prototype(napi_env env, + napi_value object, + napi_value* result) +``` + +- `[in] env`: The environment that the API is invoked under. +- `[in] object`: `napi_value` representing JavaScript `Object` whose prototype +to return. This returns the equivalent of `Object.getPrototypeOf` (which is +not the same as the function's `prototype` property). +- `[out] result`: `napi_value` representing prototype of the given object. + +Returns `napi_ok` if the API succeeded. + diff --git a/n-api/napi_get_reference_value.md b/n-api/napi_get_reference_value.md new file mode 100644 index 00000000..7e284989 --- /dev/null +++ b/n-api/napi_get_reference_value.md @@ -0,0 +1,23 @@ + +```C +NAPI_EXTERN napi_status napi_get_reference_value(napi_env env, + napi_ref ref, + napi_value* result); +``` + +the `napi_value passed` in or out of these methods is a handle to the +object to which the reference is related. +- `[in] env`: The environment that the API is invoked under. +- `[in] ref`: `napi_ref` for which we requesting the corresponding `Object`. +- `[out] result`: The `napi_value` for the `Object` referenced by the +`napi_ref`. + +Returns `napi_ok` if the API succeeded. + +If still valid, this API returns the `napi_value` representing the +JavaScript `Object` associated with the `napi_ref`. Otherwise, result +will be NULL. + diff --git a/n-api/napi_get_threadsafe_function_context.md b/n-api/napi_get_threadsafe_function_context.md new file mode 100644 index 00000000..9586f9ba --- /dev/null +++ b/n-api/napi_get_threadsafe_function_context.md @@ -0,0 +1,17 @@ + +> Stability: 2 - Stable + + +```C +NAPI_EXTERN napi_status +napi_get_threadsafe_function_context(napi_threadsafe_function func, + void** result); +``` + +- `[in] func`: The thread-safe function for which to retrieve the context. +- `[out] result`: The location where to store the context. + +This API may be called from any thread which makes use of `func`. + diff --git a/n-api/napi_get_typedarray_info.md b/n-api/napi_get_typedarray_info.md new file mode 100644 index 00000000..908dc41a --- /dev/null +++ b/n-api/napi_get_typedarray_info.md @@ -0,0 +1,36 @@ + +```C +napi_status napi_get_typedarray_info(napi_env env, + napi_value typedarray, + napi_typedarray_type* type, + size_t* length, + void** data, + napi_value* arraybuffer, + size_t* byte_offset) +``` + +- `[in] env`: The environment that the API is invoked under. +- `[in] typedarray`: `napi_value` representing the `TypedArray` whose +properties to query. +- `[out] type`: Scalar datatype of the elements within the `TypedArray`. +- `[out] length`: The number of elements in the `TypedArray`. +- `[out] data`: The data buffer underlying the `TypedArray` adjusted by +the `byte_offset` value so that it points to the first element in the +`TypedArray`. +- `[out] arraybuffer`: The `ArrayBuffer` underlying the `TypedArray`. +- `[out] byte_offset`: The byte offset within the underlying native array +at which the first element of the arrays is located. The value for the data +parameter has already been adjusted so that data points to the first element +in the array. Therefore, the first byte of the native array would be at +data - `byte_offset`. + +Returns `napi_ok` if the API succeeded. + +This API returns various properties of a typed array. + +*Warning*: Use caution while using this API since the underlying data buffer +is managed by the VM. + diff --git a/n-api/napi_get_undefined.md b/n-api/napi_get_undefined.md new file mode 100644 index 00000000..95513167 --- /dev/null +++ b/n-api/napi_get_undefined.md @@ -0,0 +1,15 @@ + +```C +napi_status napi_get_undefined(napi_env env, napi_value* result) +``` + +- `[in] env`: The environment that the API is invoked under. +- `[out] result`: `napi_value` representing JavaScript Undefined value. + +Returns `napi_ok` if the API succeeded. + +This API returns the Undefined object. + diff --git a/n-api/napi_get_uv_event_loop.md b/n-api/napi_get_uv_event_loop.md new file mode 100644 index 00000000..705950d6 --- /dev/null +++ b/n-api/napi_get_uv_event_loop.md @@ -0,0 +1,16 @@ + +```C +NAPI_EXTERN napi_status napi_get_uv_event_loop(napi_env env, + uv_loop_t** loop); +``` + +- `[in] env`: The environment that the API is invoked under. +- `[out] loop`: The current libuv loop instance. + + + diff --git a/n-api/napi_get_value_bigint_int64.md b/n-api/napi_get_value_bigint_int64.md new file mode 100644 index 00000000..50f541c4 --- /dev/null +++ b/n-api/napi_get_value_bigint_int64.md @@ -0,0 +1,27 @@ + + +> Stability: 1 - Experimental + +```C +napi_status napi_get_value_bigint_int64(napi_env env, + napi_value value, + int64_t* result, + bool* lossless); +``` + +- `[in] env`: The environment that the API is invoked under +- `[in] value`: `napi_value` representing JavaScript `BigInt`. +- `[out] result`: C `int64_t` primitive equivalent of the given JavaScript + `BigInt`. +- `[out] lossless`: Indicates whether the `BigInt` value was converted + losslessly. + +Returns `napi_ok` if the API succeeded. If a non-`BigInt` is passed in it +returns `napi_bigint_expected`. + +This API returns the C `int64_t` primitive equivalent of the given JavaScript +`BigInt`. If needed it will truncate the value, setting `lossless` to `false`. + + diff --git a/n-api/napi_get_value_bigint_uint64.md b/n-api/napi_get_value_bigint_uint64.md new file mode 100644 index 00000000..3c3779f9 --- /dev/null +++ b/n-api/napi_get_value_bigint_uint64.md @@ -0,0 +1,27 @@ + + +> Stability: 1 - Experimental + +```C +napi_status napi_get_value_bigint_uint64(napi_env env, + napi_value value, + uint64_t* result, + bool* lossless); +``` + +- `[in] env`: The environment that the API is invoked under. +- `[in] value`: `napi_value` representing JavaScript `BigInt`. +- `[out] result`: C `uint64_t` primitive equivalent of the given JavaScript + `BigInt`. +- `[out] lossless`: Indicates whether the `BigInt` value was converted + losslessly. + +Returns `napi_ok` if the API succeeded. If a non-`BigInt` is passed in it +returns `napi_bigint_expected`. + +This API returns the C `uint64_t` primitive equivalent of the given JavaScript +`BigInt`. If needed it will truncate the value, setting `lossless` to `false`. + + diff --git a/n-api/napi_get_value_bigint_words.md b/n-api/napi_get_value_bigint_words.md new file mode 100644 index 00000000..3fe62b55 --- /dev/null +++ b/n-api/napi_get_value_bigint_words.md @@ -0,0 +1,29 @@ + + +> Stability: 1 - Experimental + +```C +napi_status napi_get_value_bigint_words(napi_env env, + napi_value value, + size_t* word_count, + int* sign_bit, + uint64_t* words); +``` + +- `[in] env`: The environment that the API is invoked under. +- `[in] value`: `napi_value` representing JavaScript `BigInt`. +- `[out] sign_bit`: Integer representing if the JavaScript `BigInt` is positive + or negative. +- `[in/out] word_count`: Must be initialized to the length of the `words` + array. Upon return, it will be set to the actual number of words that + would be needed to store this `BigInt`. +- `[out] words`: Pointer to a pre-allocated 64-bit word array. + +Returns `napi_ok` if the API succeeded. + +This API converts a single `BigInt` value into a sign bit, 64-bit little-endian +array, and the number of elements in the array. `sign_bit` and `words` may be +both set to `NULL`, in order to get only `word_count`. + diff --git a/n-api/napi_get_value_bool.md b/n-api/napi_get_value_bool.md new file mode 100644 index 00000000..755289be --- /dev/null +++ b/n-api/napi_get_value_bool.md @@ -0,0 +1,19 @@ + +```C +napi_status napi_get_value_bool(napi_env env, napi_value value, bool* result) +``` + +- `[in] env`: The environment that the API is invoked under. +- `[in] value`: `napi_value` representing JavaScript `Boolean`. +- `[out] result`: C boolean primitive equivalent of the given JavaScript +`Boolean`. + +Returns `napi_ok` if the API succeeded. If a non-boolean `napi_value` is +passed in it returns `napi_boolean_expected`. + +This API returns the C boolean primitive equivalent of the given JavaScript +`Boolean`. + diff --git a/n-api/napi_get_value_double.md b/n-api/napi_get_value_double.md new file mode 100644 index 00000000..425b0040 --- /dev/null +++ b/n-api/napi_get_value_double.md @@ -0,0 +1,21 @@ + +```C +napi_status napi_get_value_double(napi_env env, + napi_value value, + double* result) +``` + +- `[in] env`: The environment that the API is invoked under. +- `[in] value`: `napi_value` representing JavaScript `Number`. +- `[out] result`: C double primitive equivalent of the given JavaScript +`Number`. + +Returns `napi_ok` if the API succeeded. If a non-number `napi_value` is passed +in it returns `napi_number_expected`. + +This API returns the C double primitive equivalent of the given JavaScript +`Number`. + diff --git a/n-api/napi_get_value_external.md b/n-api/napi_get_value_external.md new file mode 100644 index 00000000..6a0f2b40 --- /dev/null +++ b/n-api/napi_get_value_external.md @@ -0,0 +1,20 @@ + +```C +napi_status napi_get_value_external(napi_env env, + napi_value value, + void** result) +``` + +- `[in] env`: The environment that the API is invoked under. +- `[in] value`: `napi_value` representing JavaScript external value. +- `[out] result`: Pointer to the data wrapped by the JavaScript external value. + +Returns `napi_ok` if the API succeeded. If a non-external `napi_value` is +passed in it returns `napi_invalid_arg`. + +This API retrieves the external data pointer that was previously passed to +`napi_create_external()`. + diff --git a/n-api/napi_get_value_int32.md b/n-api/napi_get_value_int32.md new file mode 100644 index 00000000..0651c504 --- /dev/null +++ b/n-api/napi_get_value_int32.md @@ -0,0 +1,28 @@ + +```C +napi_status napi_get_value_int32(napi_env env, + napi_value value, + int32_t* result) +``` + +- `[in] env`: The environment that the API is invoked under. +- `[in] value`: `napi_value` representing JavaScript `Number`. +- `[out] result`: C `int32` primitive equivalent of the given JavaScript + `Number`. + +Returns `napi_ok` if the API succeeded. If a non-number `napi_value` +is passed in `napi_number_expected`. + +This API returns the C `int32` primitive equivalent +of the given JavaScript `Number`. + +If the number exceeds the range of the 32 bit integer, then the result is +truncated to the equivalent of the bottom 32 bits. This can result in a large +positive number becoming a negative number if the value is > 2^31 -1. + +Non-finite number values (`NaN`, `+Infinity`, or `-Infinity`) set the +result to zero. + diff --git a/api-docs/68aeb6f6fcef19ce80a126e5c8ca47a9bdcfd1416a30905eaeb46283578eec91.md b/n-api/napi_get_value_int64.md similarity index 100% rename from api-docs/68aeb6f6fcef19ce80a126e5c8ca47a9bdcfd1416a30905eaeb46283578eec91.md rename to n-api/napi_get_value_int64.md diff --git a/n-api/napi_get_value_string_latin1.md b/n-api/napi_get_value_string_latin1.md new file mode 100644 index 00000000..3650331d --- /dev/null +++ b/n-api/napi_get_value_string_latin1.md @@ -0,0 +1,27 @@ + +```C +napi_status napi_get_value_string_latin1(napi_env env, + napi_value value, + char* buf, + size_t bufsize, + size_t* result) +``` + +- `[in] env`: The environment that the API is invoked under. +- `[in] value`: `napi_value` representing JavaScript string. +- `[in] buf`: Buffer to write the ISO-8859-1-encoded string into. If NULL is +passed in, the length of the string (in bytes) is returned. +- `[in] bufsize`: Size of the destination buffer. When this value is +insufficient, the returned string will be truncated. +- `[out] result`: Number of bytes copied into the buffer, excluding the null +terminator. + +Returns `napi_ok` if the API succeeded. If a non-`String` `napi_value` +is passed in it returns `napi_string_expected`. + +This API returns the ISO-8859-1-encoded string corresponding the value passed +in. + diff --git a/n-api/napi_get_value_string_utf16.md b/n-api/napi_get_value_string_utf16.md new file mode 100644 index 00000000..656292ac --- /dev/null +++ b/n-api/napi_get_value_string_utf16.md @@ -0,0 +1,26 @@ + +```C +napi_status napi_get_value_string_utf16(napi_env env, + napi_value value, + char16_t* buf, + size_t bufsize, + size_t* result) +``` + +- `[in] env`: The environment that the API is invoked under. +- `[in] value`: `napi_value` representing JavaScript string. +- `[in] buf`: Buffer to write the UTF16-LE-encoded string into. If NULL is +passed in, the length of the string (in 2-byte code units) is returned. +- `[in] bufsize`: Size of the destination buffer. When this value is +insufficient, the returned string will be truncated. +- `[out] result`: Number of 2-byte code units copied into the buffer, excluding +the null terminator. + +Returns `napi_ok` if the API succeeded. If a non-`String` `napi_value` +is passed in it returns `napi_string_expected`. + +This API returns the UTF16-encoded string corresponding the value passed in. + diff --git a/n-api/napi_get_value_string_utf8.md b/n-api/napi_get_value_string_utf8.md new file mode 100644 index 00000000..8a8310ad --- /dev/null +++ b/n-api/napi_get_value_string_utf8.md @@ -0,0 +1,26 @@ + +```C +napi_status napi_get_value_string_utf8(napi_env env, + napi_value value, + char* buf, + size_t bufsize, + size_t* result) +``` + +- `[in] env`: The environment that the API is invoked under. +- `[in] value`: `napi_value` representing JavaScript string. +- `[in] buf`: Buffer to write the UTF8-encoded string into. If NULL is passed + in, the length of the string (in bytes) is returned. +- `[in] bufsize`: Size of the destination buffer. When this value is +insufficient, the returned string will be truncated. +- `[out] result`: Number of bytes copied into the buffer, excluding the null +terminator. + +Returns `napi_ok` if the API succeeded. If a non-`String` `napi_value` +is passed in it returns `napi_string_expected`. + +This API returns the UTF8-encoded string corresponding the value passed in. + diff --git a/n-api/napi_get_value_uint32.md b/n-api/napi_get_value_uint32.md new file mode 100644 index 00000000..b48a1f07 --- /dev/null +++ b/n-api/napi_get_value_uint32.md @@ -0,0 +1,21 @@ + +```C +napi_status napi_get_value_uint32(napi_env env, + napi_value value, + uint32_t* result) +``` + +- `[in] env`: The environment that the API is invoked under. +- `[in] value`: `napi_value` representing JavaScript `Number`. +- `[out] result`: C primitive equivalent of the given `napi_value` as a +`uint32_t`. + +Returns `napi_ok` if the API succeeded. If a non-number `napi_value` +is passed in it returns `napi_number_expected`. + +This API returns the C primitive equivalent of the given `napi_value` as a +`uint32_t`. + diff --git a/n-api/napi_get_version.md b/n-api/napi_get_version.md new file mode 100644 index 00000000..c24df088 --- /dev/null +++ b/n-api/napi_get_version.md @@ -0,0 +1,28 @@ + +```C +napi_status napi_get_version(napi_env env, + uint32_t* result); +``` + +- `[in] env`: The environment that the API is invoked under. +- `[out] result`: The highest version of N-API supported. + +Returns `napi_ok` if the API succeeded. + +This API returns the highest N-API version supported by the +Node.js runtime. N-API is planned to be additive such that +newer releases of Node.js may support additional API functions. +In order to allow an addon to use a newer function when running with +versions of Node.js that support it, while providing +fallback behavior when running with Node.js versions that don't +support it: + +* Call `napi_get_version()` to determine if the API is available. +* If available, dynamically load a pointer to the function using `uv_dlsym()`. +* Use the dynamically loaded pointer to invoke the function. +* If the function is not available, provide an alternate implementation + that does not use the function. + diff --git a/n-api/napi_handle_scope.md b/n-api/napi_handle_scope.md new file mode 100644 index 00000000..3100c6c0 --- /dev/null +++ b/n-api/napi_handle_scope.md @@ -0,0 +1,17 @@ +This is an abstraction used to control and modify the lifetime of objects +created within a particular scope. In general, N-API values are created within +the context of a handle scope. When a native method is called from +JavaScript, a default handle scope will exist. If the user does not explicitly +create a new handle scope, N-API values will be created in the default handle +scope. For any invocations of code outside the execution of a native method +(for instance, during a libuv callback invocation), the module is required to +create a scope before invoking any functions that can result in the creation +of JavaScript values. + +Handle scopes are created using [`napi_open_handle_scope`][] and are destroyed +using [`napi_close_handle_scope`][]. Closing the scope can indicate to the GC +that all `napi_value`s created during the lifetime of the handle scope are no +longer referenced from the current stack frame. + +For more details, review the [Object Lifetime Management][]. + diff --git a/n-api/napi_has_element.md b/n-api/napi_has_element.md new file mode 100644 index 00000000..54951796 --- /dev/null +++ b/n-api/napi_has_element.md @@ -0,0 +1,21 @@ + +```C +napi_status napi_has_element(napi_env env, + napi_value object, + uint32_t index, + bool* result); +``` + +- `[in] env`: The environment that the N-API call is invoked under. +- `[in] object`: The object to query. +- `[in] index`: The index of the property whose existence to check. +- `[out] result`: Whether the property exists on the object or not. + +Returns `napi_ok` if the API succeeded. + +This API returns if the `Object` passed in has an element at the +requested index. + diff --git a/n-api/napi_has_named_property.md b/n-api/napi_has_named_property.md new file mode 100644 index 00000000..84c9ba1e --- /dev/null +++ b/n-api/napi_has_named_property.md @@ -0,0 +1,21 @@ + +```C +napi_status napi_has_named_property(napi_env env, + napi_value object, + const char* utf8Name, + bool* result); +``` + +- `[in] env`: The environment that the N-API call is invoked under. +- `[in] object`: The object to query. +- `[in] utf8Name`: The name of the property whose existence to check. +- `[out] result`: Whether the property exists on the object or not. + +Returns `napi_ok` if the API succeeded. + +This method is equivalent to calling [`napi_has_property`][] with a `napi_value` +created from the string passed in as `utf8Name`. + diff --git a/n-api/napi_has_own_property.md b/n-api/napi_has_own_property.md new file mode 100644 index 00000000..e9c91f51 --- /dev/null +++ b/n-api/napi_has_own_property.md @@ -0,0 +1,22 @@ + +```C +napi_status napi_has_own_property(napi_env env, + napi_value object, + napi_value key, + bool* result); +``` + +- `[in] env`: The environment that the N-API call is invoked under. +- `[in] object`: The object to query. +- `[in] key`: The name of the own property whose existence to check. +- `[out] result`: Whether the own property exists on the object or not. + +Returns `napi_ok` if the API succeeded. + +This API checks if the `Object` passed in has the named own property. `key` must +be a string or a `Symbol`, or an error will be thrown. N-API will not perform +any conversion between data types. + diff --git a/n-api/napi_has_property.md b/n-api/napi_has_property.md new file mode 100644 index 00000000..1eb5ae5f --- /dev/null +++ b/n-api/napi_has_property.md @@ -0,0 +1,20 @@ + +```C +napi_status napi_has_property(napi_env env, + napi_value object, + napi_value key, + bool* result); +``` + +- `[in] env`: The environment that the N-API call is invoked under. +- `[in] object`: The object to query. +- `[in] key`: The name of the property whose existence to check. +- `[out] result`: Whether the property exists on the object or not. + +Returns `napi_ok` if the API succeeded. + +This API checks if the `Object` passed in has the named property. + diff --git a/api-docs/82febf1b2d5dd2780d964b70478b531c5fb9f2b283a24c395d7a0be58290628f.md b/n-api/napi_instanceof.md similarity index 100% rename from api-docs/82febf1b2d5dd2780d964b70478b531c5fb9f2b283a24c395d7a0be58290628f.md rename to n-api/napi_instanceof.md diff --git a/n-api/napi_is_array.md b/n-api/napi_is_array.md new file mode 100644 index 00000000..d30d89b3 --- /dev/null +++ b/n-api/napi_is_array.md @@ -0,0 +1,18 @@ + +```C +napi_status napi_is_array(napi_env env, napi_value value, bool* result) +``` + +- `[in] env`: The environment that the API is invoked under. +- `[in] value`: The JavaScript value to check. +- `[out] result`: Whether the given object is an array. + +Returns `napi_ok` if the API succeeded. + +This API represents invoking the `IsArray` operation on the object +as defined in [Section 7.2.2](https://tc39.github.io/ecma262/#sec-isarray) +of the ECMAScript Language Specification. + diff --git a/n-api/napi_is_arraybuffer.md b/n-api/napi_is_arraybuffer.md new file mode 100644 index 00000000..293db4d9 --- /dev/null +++ b/n-api/napi_is_arraybuffer.md @@ -0,0 +1,16 @@ + +```C +napi_status napi_is_arraybuffer(napi_env env, napi_value value, bool* result) +``` + +- `[in] env`: The environment that the API is invoked under. +- `[in] value`: The JavaScript value to check. +- `[out] result`: Whether the given object is an `ArrayBuffer`. + +Returns `napi_ok` if the API succeeded. + +This API checks if the `Object` passed in is an array buffer. + diff --git a/n-api/napi_is_buffer.md b/n-api/napi_is_buffer.md new file mode 100644 index 00000000..3e04938a --- /dev/null +++ b/n-api/napi_is_buffer.md @@ -0,0 +1,17 @@ + +```C +napi_status napi_is_buffer(napi_env env, napi_value value, bool* result) +``` + +- `[in] env`: The environment that the API is invoked under. +- `[in] value`: The JavaScript value to check. +- `[out] result`: Whether the given `napi_value` represents a `node::Buffer` +object. + +Returns `napi_ok` if the API succeeded. + +This API checks if the `Object` passed in is a buffer. + diff --git a/n-api/napi_is_dataview.md b/n-api/napi_is_dataview.md new file mode 100644 index 00000000..51ff64eb --- /dev/null +++ b/n-api/napi_is_dataview.md @@ -0,0 +1,17 @@ + + +```C +napi_status napi_is_dataview(napi_env env, napi_value value, bool* result) +``` + +- `[in] env`: The environment that the API is invoked under. +- `[in] value`: The JavaScript value to check. +- `[out] result`: Whether the given `napi_value` represents a `DataView`. + +Returns `napi_ok` if the API succeeded. + +This API checks if the `Object` passed in is a `DataView`. + diff --git a/n-api/napi_is_error.md b/n-api/napi_is_error.md new file mode 100644 index 00000000..528ae009 --- /dev/null +++ b/n-api/napi_is_error.md @@ -0,0 +1,18 @@ + +```C +NAPI_EXTERN napi_status napi_is_error(napi_env env, + napi_value value, + bool* result); +``` +- `[in] env`: The environment that the API is invoked under. +- `[in] value`: The `napi_value` to be checked. +- `[out] result`: Boolean value that is set to true if `napi_value` represents +an error, false otherwise. + +Returns `napi_ok` if the API succeeded. + +This API queries a `napi_value` to check if it represents an error object. + diff --git a/n-api/napi_is_error_1.md b/n-api/napi_is_error_1.md new file mode 100644 index 00000000..fd737082 --- /dev/null +++ b/n-api/napi_is_error_1.md @@ -0,0 +1,16 @@ + +```C +napi_status napi_is_error(napi_env env, napi_value value, bool* result) +``` + +- `[in] env`: The environment that the API is invoked under. +- `[in] value`: The JavaScript value to check. +- `[out] result`: Whether the given `napi_value` represents an `Error` object. + +Returns `napi_ok` if the API succeeded. + +This API checks if the `Object` passed in is an `Error`. + diff --git a/n-api/napi_is_exception_pending.md b/n-api/napi_is_exception_pending.md new file mode 100644 index 00000000..8d0e1621 --- /dev/null +++ b/n-api/napi_is_exception_pending.md @@ -0,0 +1,17 @@ + +```C +napi_status napi_is_exception_pending(napi_env env, bool* result); +``` + +- `[in] env`: The environment that the API is invoked under. +- `[out] result`: Boolean value that is set to true if an exception is pending. + +Returns `napi_ok` if the API succeeded. + +This API returns true if an exception is pending. + +This API can be called even if there is a pending JavaScript exception. + diff --git a/n-api/napi_is_promise.md b/n-api/napi_is_promise.md new file mode 100644 index 00000000..cec74b38 --- /dev/null +++ b/n-api/napi_is_promise.md @@ -0,0 +1,15 @@ + +```C +napi_status napi_is_promise(napi_env env, + napi_value promise, + bool* is_promise); +``` + +- `[in] env`: The environment that the API is invoked under. +- `[in] promise`: The promise to examine +- `[out] is_promise`: Flag indicating whether `promise` is a native promise +object - that is, a promise object created by the underlying engine. + diff --git a/n-api/napi_is_typedarray.md b/n-api/napi_is_typedarray.md new file mode 100644 index 00000000..7ee3e0c3 --- /dev/null +++ b/n-api/napi_is_typedarray.md @@ -0,0 +1,16 @@ + +```C +napi_status napi_is_typedarray(napi_env env, napi_value value, bool* result) +``` + +- `[in] env`: The environment that the API is invoked under. +- `[in] value`: The JavaScript value to check. +- `[out] result`: Whether the given `napi_value` represents a `TypedArray`. + +Returns `napi_ok` if the API succeeded. + +This API checks if the `Object` passed in is a typed array. + diff --git a/n-api/napi_make_callback.md b/n-api/napi_make_callback.md new file mode 100644 index 00000000..22b6e0fe --- /dev/null +++ b/n-api/napi_make_callback.md @@ -0,0 +1,46 @@ + +```C +napi_status napi_make_callback(napi_env env, + napi_async_context async_context, + napi_value recv, + napi_value func, + int argc, + const napi_value* argv, + napi_value* result) +``` + +- `[in] env`: The environment that the API is invoked under. +- `[in] async_context`: Context for the async operation that is + invoking the callback. This should normally be a value previously + obtained from [`napi_async_init`][]. However `NULL` is also allowed, + which indicates the current async context (if any) is to be used + for the callback. +- `[in] recv`: The `this` object passed to the called function. +- `[in] func`: `napi_value` representing the JavaScript function +to be invoked. +- `[in] argc`: The count of elements in the `argv` array. +- `[in] argv`: Array of JavaScript values as `napi_value` +representing the arguments to the function. +- `[out] result`: `napi_value` representing the JavaScript object returned. + +Returns `napi_ok` if the API succeeded. + +This method allows a JavaScript function object to be called from a native +add-on. This API is similar to `napi_call_function`. However, it is used to call +*from* native code back *into* JavaScript *after* returning from an async +operation (when there is no other script on the stack). It is a fairly simple +wrapper around `node::MakeCallback`. + +Note it is *not* necessary to use `napi_make_callback` from within a +`napi_async_complete_callback`; in that situation the callback's async +context has already been set up, so a direct call to `napi_call_function` +is sufficient and appropriate. Use of the `napi_make_callback` function +may be required when implementing custom async behavior that does not use +`napi_create_async_work`. + diff --git a/n-api/napi_new_instance.md b/n-api/napi_new_instance.md new file mode 100644 index 00000000..ab459e9b --- /dev/null +++ b/n-api/napi_new_instance.md @@ -0,0 +1,56 @@ + +```C +napi_status napi_new_instance(napi_env env, + napi_value cons, + size_t argc, + napi_value* argv, + napi_value* result) +``` + +- `[in] env`: The environment that the API is invoked under. +- `[in] cons`: `napi_value` representing the JavaScript function +to be invoked as a constructor. +- `[in] argc`: The count of elements in the `argv` array. +- `[in] argv`: Array of JavaScript values as `napi_value` +representing the arguments to the constructor. +- `[out] result`: `napi_value` representing the JavaScript object returned, +which in this case is the constructed object. + +This method is used to instantiate a new JavaScript value using a given +`napi_value` that represents the constructor for the object. For example, +consider the following snippet: +```js +function MyObject(param) { + this.param = param; +} + +const arg = 'hello'; +const value = new MyObject(arg); +``` + +The following can be approximated in N-API using the following snippet: +```C +// Get the constructor function MyObject +napi_value global, constructor, arg, value; +napi_status status = napi_get_global(env, &global); +if (status != napi_ok) return; + +status = napi_get_named_property(env, global, "MyObject", &constructor); +if (status != napi_ok) return; + +// const arg = "hello" +status = napi_create_string_utf8(env, "hello", NAPI_AUTO_LENGTH, &arg); +if (status != napi_ok) return; + +napi_value* argv = &arg; +size_t argc = 1; + +// const value = new MyObject(arg) +status = napi_new_instance(env, constructor, argc, argv, &value); +``` + +Returns `napi_ok` if the API succeeded. + diff --git a/n-api/napi_open_callback_scope.md b/n-api/napi_open_callback_scope.md new file mode 100644 index 00000000..e10cd143 --- /dev/null +++ b/n-api/napi_open_callback_scope.md @@ -0,0 +1,25 @@ + +```C +NAPI_EXTERN napi_status napi_open_callback_scope(napi_env env, + napi_value resource_object, + napi_async_context context, + napi_callback_scope* result) +``` +- `[in] env`: The environment that the API is invoked under. +- `[in] resource_object`: An object associated with the async work + that will be passed to possible `async_hooks` [`init` hooks][]. +- `[in] context`: Context for the async operation that is +invoking the callback. This should be a value previously obtained +from [`napi_async_init`][]. +- `[out] result`: The newly created scope. + +There are cases (for example, resolving promises) where it is +necessary to have the equivalent of the scope associated with a callback +in place when making certain N-API calls. If there is no other script on +the stack the [`napi_open_callback_scope`][] and +[`napi_close_callback_scope`][] functions can be used to open/close +the required scope. + diff --git a/n-api/napi_open_escapable_handle_scope.md b/n-api/napi_open_escapable_handle_scope.md new file mode 100644 index 00000000..0dbe31a8 --- /dev/null +++ b/n-api/napi_open_escapable_handle_scope.md @@ -0,0 +1,17 @@ + +```C +NAPI_EXTERN napi_status + napi_open_escapable_handle_scope(napi_env env, + napi_handle_scope* result); +``` +- `[in] env`: The environment that the API is invoked under. +- `[out] result`: `napi_value` representing the new scope. + +Returns `napi_ok` if the API succeeded. + +This API open a new scope from which one object can be promoted +to the outer scope. + diff --git a/n-api/napi_open_handle_scope.md b/n-api/napi_open_handle_scope.md new file mode 100644 index 00000000..b45e5873 --- /dev/null +++ b/n-api/napi_open_handle_scope.md @@ -0,0 +1,15 @@ + +```C +NAPI_EXTERN napi_status napi_open_handle_scope(napi_env env, + napi_handle_scope* result); +``` +- `[in] env`: The environment that the API is invoked under. +- `[out] result`: `napi_value` representing the new scope. + +Returns `napi_ok` if the API succeeded. + +This API open a new scope. + diff --git a/n-api/napi_property_attributes.md b/n-api/napi_property_attributes.md new file mode 100644 index 00000000..a2281bbf --- /dev/null +++ b/n-api/napi_property_attributes.md @@ -0,0 +1,31 @@ +```C +typedef enum { + napi_default = 0, + napi_writable = 1 << 0, + napi_enumerable = 1 << 1, + napi_configurable = 1 << 2, + + // Used with napi_define_class to distinguish static properties + // from instance properties. Ignored by napi_define_properties. + napi_static = 1 << 10, +} napi_property_attributes; +``` + +`napi_property_attributes` are flags used to control the behavior of properties +set on a JavaScript object. Other than `napi_static` they correspond to the +attributes listed in [Section 6.1.7.1][] +of the [ECMAScript Language Specification][]. +They can be one or more of the following bitflags: + +- `napi_default` - Used to indicate that no explicit attributes are set on the +given property. By default, a property is read only, not enumerable and not +configurable. +- `napi_writable` - Used to indicate that a given property is writable. +- `napi_enumerable` - Used to indicate that a given property is enumerable. +- `napi_configurable` - Used to indicate that a given property is configurable, +as defined in [Section 6.1.7.1][] of the [ECMAScript Language Specification][]. +- `napi_static` - Used to indicate that the property will be defined as +a static property on a class as opposed to an instance property, which is the +default. This is used only by [`napi_define_class`][]. It is ignored by +`napi_define_properties`. + diff --git a/n-api/napi_property_descriptor.md b/n-api/napi_property_descriptor.md new file mode 100644 index 00000000..446735aa --- /dev/null +++ b/n-api/napi_property_descriptor.md @@ -0,0 +1,44 @@ +```C +typedef struct { + // One of utf8name or name should be NULL. + const char* utf8name; + napi_value name; + + napi_callback method; + napi_callback getter; + napi_callback setter; + napi_value value; + + napi_property_attributes attributes; + void* data; +} napi_property_descriptor; +``` + +- `utf8name`: Optional `String` describing the key for the property, +encoded as UTF8. One of `utf8name` or `name` must be provided for the +property. +- `name`: Optional `napi_value` that points to a JavaScript string or symbol +to be used as the key for the property. One of `utf8name` or `name` must +be provided for the property. +- `value`: The value that's retrieved by a get access of the property if the + property is a data property. If this is passed in, set `getter`, `setter`, + `method` and `data` to `NULL` (since these members won't be used). +- `getter`: A function to call when a get access of the property is performed. +If this is passed in, set `value` and `method` to `NULL` (since these members +won't be used). The given function is called implicitly by the runtime when the +property is accessed from JavaScript code (or if a get on the property is +performed using a N-API call). +- `setter`: A function to call when a set access of the property is performed. +If this is passed in, set `value` and `method` to `NULL` (since these members +won't be used). The given function is called implicitly by the runtime when the +property is set from JavaScript code (or if a set on the property is +performed using a N-API call). +- `method`: Set this to make the property descriptor object's `value` +property to be a JavaScript function represented by `method`. If this is +passed in, set `value`, `getter` and `setter` to `NULL` (since these members +won't be used). +- `attributes`: The attributes associated with the particular property. +See [`napi_property_attributes`](#n_api_napi_property_attributes). +- `data`: The callback data passed into `method`, `getter` and `setter` if +this function is invoked. + diff --git a/n-api/napi_queue_async_work.md b/n-api/napi_queue_async_work.md new file mode 100644 index 00000000..500e3513 --- /dev/null +++ b/n-api/napi_queue_async_work.md @@ -0,0 +1,17 @@ + +```C +napi_status napi_queue_async_work(napi_env env, + napi_async_work work); +``` + +- `[in] env`: The environment that the API is invoked under. +- `[in] work`: The handle returned by the call to `napi_create_async_work`. + +Returns `napi_ok` if the API succeeded. + +This API requests that the previously allocated work be scheduled +for execution. + diff --git a/n-api/napi_ref.md b/n-api/napi_ref.md new file mode 100644 index 00000000..baa79ee6 --- /dev/null +++ b/n-api/napi_ref.md @@ -0,0 +1,6 @@ +This is the abstraction to use to reference a `napi_value`. This allows for +users to manage the lifetimes of JavaScript values, including defining their +minimum lifetimes explicitly. + +For more details, review the [Object Lifetime Management][]. + diff --git a/n-api/napi_ref_threadsafe_function.md b/n-api/napi_ref_threadsafe_function.md new file mode 100644 index 00000000..396d534e --- /dev/null +++ b/n-api/napi_ref_threadsafe_function.md @@ -0,0 +1,20 @@ + +> Stability: 2 - Stable + + +```C +NAPI_EXTERN napi_status +napi_ref_threadsafe_function(napi_env env, napi_threadsafe_function func); +``` + +- `[in] env`: The environment that the API is invoked under. +- `[in] func`: The thread-safe function to reference. + +This API is used to indicate that the event loop running on the main thread +should not exit until `func` has been destroyed. Similar to [`uv_ref`][] it is +also idempotent. + +This API may only be called from the main thread. + diff --git a/n-api/napi_reference_ref.md b/n-api/napi_reference_ref.md new file mode 100644 index 00000000..4da6ed75 --- /dev/null +++ b/n-api/napi_reference_ref.md @@ -0,0 +1,18 @@ + +```C +NAPI_EXTERN napi_status napi_reference_ref(napi_env env, + napi_ref ref, + int* result); +``` +- `[in] env`: The environment that the API is invoked under. +- `[in] ref`: `napi_ref` for which the reference count will be incremented. +- `[out] result`: The new reference count. + +Returns `napi_ok` if the API succeeded. + +This API increments the reference count for the reference +passed in and returns the resulting reference count. + diff --git a/n-api/napi_reference_unref.md b/n-api/napi_reference_unref.md new file mode 100644 index 00000000..b0013d82 --- /dev/null +++ b/n-api/napi_reference_unref.md @@ -0,0 +1,18 @@ + +```C +NAPI_EXTERN napi_status napi_reference_unref(napi_env env, + napi_ref ref, + int* result); +``` +- `[in] env`: The environment that the API is invoked under. +- `[in] ref`: `napi_ref` for which the reference count will be decremented. +- `[out] result`: The new reference count. + +Returns `napi_ok` if the API succeeded. + +This API decrements the reference count for the reference +passed in and returns the resulting reference count. + diff --git a/n-api/napi_reject_deferred.md b/n-api/napi_reject_deferred.md new file mode 100644 index 00000000..7220c680 --- /dev/null +++ b/n-api/napi_reject_deferred.md @@ -0,0 +1,23 @@ + +```C +napi_status napi_reject_deferred(napi_env env, + napi_deferred deferred, + napi_value rejection); +``` + +- `[in] env`: The environment that the API is invoked under. +- `[in] deferred`: The deferred object whose associated promise to resolve. +- `[in] rejection`: The value with which to reject the promise. + +This API rejects a JavaScript promise by way of the deferred object +with which it is associated. Thus, it can only be used to reject JavaScript +promises for which the corresponding deferred object is available. This +effectively means that the promise must have been created using +`napi_create_promise()` and the deferred object returned from that call must +have been retained in order to be passed to this API. + +The deferred object is freed upon successful completion. + diff --git a/n-api/napi_release_threadsafe_function.md b/n-api/napi_release_threadsafe_function.md new file mode 100644 index 00000000..828e0fde --- /dev/null +++ b/n-api/napi_release_threadsafe_function.md @@ -0,0 +1,27 @@ + +> Stability: 2 - Stable + + +```C +NAPI_EXTERN napi_status +napi_release_threadsafe_function(napi_threadsafe_function func, + napi_threadsafe_function_release_mode mode); +``` + +- `[in] func`: The asynchronous thread-safe JavaScript function whose reference +count to decrement. +- `[in] mode`: Flag whose value can be either `napi_tsfn_release` to indicate +that the current thread will make no further calls to the thread-safe function, +or `napi_tsfn_abort` to indicate that in addition to the current thread, no +other thread should make any further calls to the thread-safe function. If set +to `napi_tsfn_abort`, further calls to `napi_call_threadsafe_function()` will +return `napi_closing`, and no further values will be placed in the queue. + +A thread should call this API when it stops making use of `func`. Passing `func` +to any thread-safe APIs after having called this API has undefined results, as +`func` may have been destroyed. + +This API may be called from any thread which will stop making use of `func`. + diff --git a/n-api/napi_remove_env_cleanup_hook.md b/n-api/napi_remove_env_cleanup_hook.md new file mode 100644 index 00000000..db04e6d4 --- /dev/null +++ b/n-api/napi_remove_env_cleanup_hook.md @@ -0,0 +1,18 @@ + + +```C +NAPI_EXTERN napi_status napi_remove_env_cleanup_hook(napi_env env, + void (*fun)(void* arg), + void* arg); +``` + +Unregisters `fun` as a function to be run with the `arg` parameter once the +current Node.js environment exits. Both the argument and the function value +need to be exact matches. + +The function must have originally been registered +with `napi_add_env_cleanup_hook`, otherwise the process will abort. + diff --git a/n-api/napi_remove_wrap.md b/n-api/napi_remove_wrap.md new file mode 100644 index 00000000..8ceeb3fb --- /dev/null +++ b/n-api/napi_remove_wrap.md @@ -0,0 +1,21 @@ + +```C +napi_status napi_remove_wrap(napi_env env, + napi_value js_object, + void** result); +``` + + - `[in] env`: The environment that the API is invoked under. + - `[in] js_object`: The object associated with the native instance. + - `[out] result`: Pointer to the wrapped native instance. + +Returns `napi_ok` if the API succeeded. + +Retrieves a native instance that was previously wrapped in the JavaScript +object `js_object` using `napi_wrap()` and removes the wrapping. If a finalize +callback was associated with the wrapping, it will no longer be called when the +JavaScript object becomes garbage-collected. + diff --git a/n-api/napi_resolve_deferred.md b/n-api/napi_resolve_deferred.md new file mode 100644 index 00000000..fb30ca42 --- /dev/null +++ b/n-api/napi_resolve_deferred.md @@ -0,0 +1,23 @@ + +```C +napi_status napi_resolve_deferred(napi_env env, + napi_deferred deferred, + napi_value resolution); +``` + +- `[in] env`: The environment that the API is invoked under. +- `[in] deferred`: The deferred object whose associated promise to resolve. +- `[in] resolution`: The value with which to resolve the promise. + +This API resolves a JavaScript promise by way of the deferred object +with which it is associated. Thus, it can only be used to resolve JavaScript +promises for which the corresponding deferred object is available. This +effectively means that the promise must have been created using +`napi_create_promise()` and the deferred object returned from that call must +have been retained in order to be passed to this API. + +The deferred object is freed upon successful completion. + diff --git a/n-api/napi_run_script.md b/n-api/napi_run_script.md new file mode 100644 index 00000000..ff6a6af9 --- /dev/null +++ b/n-api/napi_run_script.md @@ -0,0 +1,14 @@ + +```C +NAPI_EXTERN napi_status napi_run_script(napi_env env, + napi_value script, + napi_value* result); +``` + +- `[in] env`: The environment that the API is invoked under. +- `[in] script`: A JavaScript string containing the script to execute. +- `[out] result`: The value resulting from having executed the script. + diff --git a/n-api/napi_set_element.md b/n-api/napi_set_element.md new file mode 100644 index 00000000..4d8ca37e --- /dev/null +++ b/n-api/napi_set_element.md @@ -0,0 +1,20 @@ + +```C +napi_status napi_set_element(napi_env env, + napi_value object, + uint32_t index, + napi_value value); +``` + +- `[in] env`: The environment that the N-API call is invoked under. +- `[in] object`: The object from which to set the properties. +- `[in] index`: The index of the property to set. +- `[in] value`: The property value. + +Returns `napi_ok` if the API succeeded. + +This API sets and element on the `Object` passed in. + diff --git a/n-api/napi_set_named_property.md b/n-api/napi_set_named_property.md new file mode 100644 index 00000000..fa6d8003 --- /dev/null +++ b/n-api/napi_set_named_property.md @@ -0,0 +1,21 @@ + +```C +napi_status napi_set_named_property(napi_env env, + napi_value object, + const char* utf8Name, + napi_value value); +``` + +- `[in] env`: The environment that the N-API call is invoked under. +- `[in] object`: The object on which to set the property. +- `[in] utf8Name`: The name of the property to set. +- `[in] value`: The property value. + +Returns `napi_ok` if the API succeeded. + +This method is equivalent to calling [`napi_set_property`][] with a `napi_value` +created from the string passed in as `utf8Name`. + diff --git a/n-api/napi_set_property.md b/n-api/napi_set_property.md new file mode 100644 index 00000000..0e70d917 --- /dev/null +++ b/n-api/napi_set_property.md @@ -0,0 +1,20 @@ + +```C +napi_status napi_set_property(napi_env env, + napi_value object, + napi_value key, + napi_value value); +``` + +- `[in] env`: The environment that the N-API call is invoked under. +- `[in] object`: The object on which to set the property. +- `[in] key`: The name of the property to set. +- `[in] value`: The property value. + +Returns `napi_ok` if the API succeeded. + +This API set a property on the `Object` passed in. + diff --git a/n-api/napi_status.md b/n-api/napi_status.md new file mode 100644 index 00000000..7080fbf3 --- /dev/null +++ b/n-api/napi_status.md @@ -0,0 +1,27 @@ +Integral status code indicating the success or failure of a N-API call. +Currently, the following status codes are supported. +```C +typedef enum { + napi_ok, + napi_invalid_arg, + napi_object_expected, + napi_string_expected, + napi_name_expected, + napi_function_expected, + napi_number_expected, + napi_boolean_expected, + napi_array_expected, + napi_generic_failure, + napi_pending_exception, + napi_cancelled, + napi_escape_called_twice, + napi_handle_scope_mismatch, + napi_callback_scope_mismatch, + napi_queue_full, + napi_closing, + napi_bigint_expected, +} napi_status; +``` +If additional information is required upon an API returning a failed status, +it can be obtained by calling `napi_get_last_error_info`. + diff --git a/api-docs/5e724763a1713f8559dee2c34783003636539a4d5c305efe67ed9332084591c2.md b/n-api/napi_strict_equals.md similarity index 100% rename from api-docs/5e724763a1713f8559dee2c34783003636539a4d5c305efe67ed9332084591c2.md rename to n-api/napi_strict_equals.md diff --git a/n-api/napi_threadsafe_function.md b/n-api/napi_threadsafe_function.md new file mode 100644 index 00000000..cb3500b7 --- /dev/null +++ b/n-api/napi_threadsafe_function.md @@ -0,0 +1,7 @@ + +> Stability: 2 - Stable + +This is an opaque pointer that represents a JavaScript function which can be +called asynchronously from multiple threads via +`napi_call_threadsafe_function()`. + diff --git a/n-api/napi_threadsafe_function_call_js.md b/n-api/napi_threadsafe_function_call_js.md new file mode 100644 index 00000000..e3a874a8 --- /dev/null +++ b/n-api/napi_threadsafe_function_call_js.md @@ -0,0 +1,36 @@ + +> Stability: 2 - Stable + +Function pointer used with asynchronous thread-safe function calls. The callback +will be called on the main thread. Its purpose is to use a data item arriving +via the queue from one of the secondary threads to construct the parameters +necessary for a call into JavaScript, usually via `napi_call_function`, and then +make the call into JavaScript. + +The data arriving from the secondary thread via the queue is given in the `data` +parameter and the JavaScript function to call is given in the `js_callback` +parameter. + +N-API sets up the environment prior to calling this callback, so it is +sufficient to call the JavaScript function via `napi_call_function` rather than +via `napi_make_callback`. + +Callback functions must satisfy the following signature: +```C +typedef void (*napi_threadsafe_function_call_js)(napi_env env, + napi_value js_callback, + void* context, + void* data); +``` +- `[in] env`: The environment to use for API calls, or `NULL` if the thread-safe +function is being torn down and `data` may need to be freed. +- `[in] js_callback`: The JavaScript function to call, or `NULL` if the +thread-safe function is being torn down and `data` may need to be freed. +- `[in] context`: The optional data with which the thread-safe function was +created. +- `[in] data`: Data created by the secondary thread. It is the responsibility of +the callback to convert this native data to JavaScript values (with N-API +functions) that can be passed as parameters when `js_callback` is invoked. This +pointer is managed entirely by the threads and this callback. Thus this callback +should free the data. + diff --git a/n-api/napi_threadsafe_function_call_mode.md b/n-api/napi_threadsafe_function_call_mode.md new file mode 100644 index 00000000..17c57f66 --- /dev/null +++ b/n-api/napi_threadsafe_function_call_mode.md @@ -0,0 +1,13 @@ + +> Stability: 2 - Stable + +A value to be given to `napi_call_threadsafe_function()` to indicate whether +the call should block whenever the queue associated with the thread-safe +function is full. +```C +typedef enum { + napi_tsfn_nonblocking, + napi_tsfn_blocking +} napi_threadsafe_function_call_mode; +``` + diff --git a/n-api/napi_threadsafe_function_release_mode.md b/n-api/napi_threadsafe_function_release_mode.md new file mode 100644 index 00000000..9d23d741 --- /dev/null +++ b/n-api/napi_threadsafe_function_release_mode.md @@ -0,0 +1,14 @@ + +> Stability: 2 - Stable + +A value to be given to `napi_release_threadsafe_function()` to indicate whether +the thread-safe function is to be closed immediately (`napi_tsfn_abort`) or +merely released (`napi_tsfn_release`) and thus available for subsequent use via +`napi_acquire_threadsafe_function()` and `napi_call_threadsafe_function()`. +```C +typedef enum { + napi_tsfn_release, + napi_tsfn_abort +} napi_threadsafe_function_release_mode; +``` + diff --git a/n-api/napi_throw.md b/n-api/napi_throw.md new file mode 100644 index 00000000..912f1b38 --- /dev/null +++ b/n-api/napi_throw.md @@ -0,0 +1,14 @@ + +```C +NAPI_EXTERN napi_status napi_throw(napi_env env, napi_value error); +``` +- `[in] env`: The environment that the API is invoked under. +- `[in] error`: The JavaScript value to be thrown. + +Returns `napi_ok` if the API succeeded. + +This API throws the JavaScript value provided. + diff --git a/n-api/napi_throw_error.md b/n-api/napi_throw_error.md new file mode 100644 index 00000000..07c740ee --- /dev/null +++ b/n-api/napi_throw_error.md @@ -0,0 +1,18 @@ + +```C +NAPI_EXTERN napi_status napi_throw_error(napi_env env, + const char* code, + const char* msg); +``` +- `[in] env`: The environment that the API is invoked under. +- `[in] code`: Optional error code to be set on the error. +- `[in] msg`: C string representing the text to be associated with +the error. + +Returns `napi_ok` if the API succeeded. + +This API throws a JavaScript `Error` with the text provided. + diff --git a/n-api/napi_throw_range_error.md b/n-api/napi_throw_range_error.md new file mode 100644 index 00000000..97dc9eee --- /dev/null +++ b/n-api/napi_throw_range_error.md @@ -0,0 +1,18 @@ + +```C +NAPI_EXTERN napi_status napi_throw_range_error(napi_env env, + const char* code, + const char* msg); +``` +- `[in] env`: The environment that the API is invoked under. +- `[in] code`: Optional error code to be set on the error. +- `[in] msg`: C string representing the text to be associated with +the error. + +Returns `napi_ok` if the API succeeded. + +This API throws a JavaScript `RangeError` with the text provided. + diff --git a/n-api/napi_throw_type_error.md b/n-api/napi_throw_type_error.md new file mode 100644 index 00000000..3fdb23e5 --- /dev/null +++ b/n-api/napi_throw_type_error.md @@ -0,0 +1,18 @@ + +```C +NAPI_EXTERN napi_status napi_throw_type_error(napi_env env, + const char* code, + const char* msg); +``` +- `[in] env`: The environment that the API is invoked under. +- `[in] code`: Optional error code to be set on the error. +- `[in] msg`: C string representing the text to be associated with +the error. + +Returns `napi_ok` if the API succeeded. + +This API throws a JavaScript `TypeError` with the text provided. + diff --git a/n-api/napi_typedarray_type.md b/n-api/napi_typedarray_type.md new file mode 100644 index 00000000..6a931dcc --- /dev/null +++ b/n-api/napi_typedarray_type.md @@ -0,0 +1,20 @@ +```C +typedef enum { + napi_int8_array, + napi_uint8_array, + napi_uint8_clamped_array, + napi_int16_array, + napi_uint16_array, + napi_int32_array, + napi_uint32_array, + napi_float32_array, + napi_float64_array, + napi_bigint64_array, + napi_biguint64_array, +} napi_typedarray_type; +``` + +This represents the underlying binary scalar datatype of the `TypedArray`. +Elements of this enum correspond to +[Section 22.2][] of the [ECMAScript Language Specification][]. + diff --git a/n-api/napi_typeof.md b/n-api/napi_typeof.md new file mode 100644 index 00000000..3cbbc80b --- /dev/null +++ b/n-api/napi_typeof.md @@ -0,0 +1,21 @@ + +```C +napi_status napi_typeof(napi_env env, napi_value value, napi_valuetype* result) +``` + +- `[in] env`: The environment that the API is invoked under. +- `[in] value`: The JavaScript value whose type to query. +- `[out] result`: The type of the JavaScript value. + +Returns `napi_ok` if the API succeeded. +- `napi_invalid_arg` if the type of `value` is not a known ECMAScript type and + `value` is not an External value. + +This API represents behavior similar to invoking the `typeof` Operator on +the object as defined in [Section 12.5.5][] of the ECMAScript Language +Specification. However, it has support for detecting an External value. +If `value` has a type that is invalid, an error is returned. + diff --git a/api-docs/c397b3c464d7c852c3d93e99085e35fd3b0d07fa050aa7b7685552cf3c139d3a.md b/n-api/napi_unref_threadsafe_function.md similarity index 94% rename from api-docs/c397b3c464d7c852c3d93e99085e35fd3b0d07fa050aa7b7685552cf3c139d3a.md rename to n-api/napi_unref_threadsafe_function.md index fd861069..7a445a18 100644 --- a/api-docs/c397b3c464d7c852c3d93e99085e35fd3b0d07fa050aa7b7685552cf3c139d3a.md +++ b/n-api/napi_unref_threadsafe_function.md @@ -1,5 +1,5 @@ -> Stability: 1 - Experimental +> Stability: 2 - Stable +```C +napi_status napi_unwrap(napi_env env, + napi_value js_object, + void** result); +``` + + - `[in] env`: The environment that the API is invoked under. + - `[in] js_object`: The object associated with the native instance. + - `[out] result`: Pointer to the wrapped native instance. + +Returns `napi_ok` if the API succeeded. + +Retrieves a native instance that was previously wrapped in a JavaScript +object using `napi_wrap()`. + +When JavaScript code invokes a method or property accessor on the class, the +corresponding `napi_callback` is invoked. If the callback is for an instance +method or accessor, then the `this` argument to the callback is the wrapper +object; the wrapped C++ instance that is the target of the call can be obtained +then by calling `napi_unwrap()` on the wrapper object. + diff --git a/n-api/napi_value.md b/n-api/napi_value.md new file mode 100644 index 00000000..a3331bf4 --- /dev/null +++ b/n-api/napi_value.md @@ -0,0 +1,2 @@ +This is an opaque pointer that is used to represent a JavaScript value. + diff --git a/api-docs/f869a8020af621cbd86dd33805d00e3a2bb5f9d5b423c0a4392bcccfa125da45.md b/n-api/napi_valuetype.md similarity index 100% rename from api-docs/f869a8020af621cbd86dd33805d00e3a2bb5f9d5b423c0a4392bcccfa125da45.md rename to n-api/napi_valuetype.md diff --git a/n-api/napi_wrap.md b/n-api/napi_wrap.md new file mode 100644 index 00000000..8e396e8d --- /dev/null +++ b/n-api/napi_wrap.md @@ -0,0 +1,55 @@ + +```C +napi_status napi_wrap(napi_env env, + napi_value js_object, + void* native_object, + napi_finalize finalize_cb, + void* finalize_hint, + napi_ref* result); +``` + + - `[in] env`: The environment that the API is invoked under. + - `[in] js_object`: The JavaScript object that will be the wrapper for the + native object. + - `[in] native_object`: The native instance that will be wrapped in the + JavaScript object. + - `[in] finalize_cb`: Optional native callback that can be used to free the + native instance when the JavaScript object is ready for garbage-collection. + - `[in] finalize_hint`: Optional contextual hint that is passed to the + finalize callback. + - `[out] result`: Optional reference to the wrapped object. + +Returns `napi_ok` if the API succeeded. + +Wraps a native instance in a JavaScript object. The native instance can be +retrieved later using `napi_unwrap()`. + +When JavaScript code invokes a constructor for a class that was defined using +`napi_define_class()`, the `napi_callback` for the constructor is invoked. +After constructing an instance of the native class, the callback must then call +`napi_wrap()` to wrap the newly constructed instance in the already-created +JavaScript object that is the `this` argument to the constructor callback. +(That `this` object was created from the constructor function's `prototype`, +so it already has definitions of all the instance properties and methods.) + +Typically when wrapping a class instance, a finalize callback should be +provided that simply deletes the native instance that is received as the `data` +argument to the finalize callback. + +The optional returned reference is initially a weak reference, meaning it +has a reference count of 0. Typically this reference count would be incremented +temporarily during async operations that require the instance to remain valid. + +*Caution*: The optional returned reference (if obtained) should be deleted via +[`napi_delete_reference`][] ONLY in response to the finalize callback +invocation. If it is deleted before then, then the finalize callback may never +be invoked. Therefore, when obtaining a reference a finalize callback is also +required in order to enable correct disposal of the reference. + +Calling `napi_wrap()` a second time on an object will return an error. To +associate another native instance with the object, use `napi_remove_wrap()` +first. + diff --git a/n-api/object_creation_functions.md b/n-api/object_creation_functions.md new file mode 100644 index 00000000..e69de29b diff --git a/n-api/object_lifetime_management.md b/n-api/object_lifetime_management.md new file mode 100644 index 00000000..4aacb833 --- /dev/null +++ b/n-api/object_lifetime_management.md @@ -0,0 +1,18 @@ + +As N-API calls are made, handles to objects in the heap for the underlying +VM may be returned as `napi_values`. These handles must hold the +objects 'live' until they are no longer required by the native code, +otherwise the objects could be collected before the native code was +finished using them. + +As object handles are returned they are associated with a +'scope'. The lifespan for the default scope is tied to the lifespan +of the native method call. The result is that, by default, handles +remain valid and the objects associated with these handles will be +held live for the lifespan of the native method call. + +In many cases, however, it is necessary that the handles remain valid for +either a shorter or longer lifespan than that of the native method. +The sections which follow describe the N-API functions that can be used +to change the handle lifespan from the default. + diff --git a/n-api/object_wrap.md b/n-api/object_wrap.md new file mode 100644 index 00000000..925f0cf3 --- /dev/null +++ b/n-api/object_wrap.md @@ -0,0 +1,36 @@ + +N-API offers a way to "wrap" C++ classes and instances so that the class +constructor and methods can be called from JavaScript. + + 1. The [`napi_define_class`][] API defines a JavaScript class with constructor, + static properties and methods, and instance properties and methods that + correspond to the C++ class. + 2. When JavaScript code invokes the constructor, the constructor callback + uses [`napi_wrap`][] to wrap a new C++ instance in a JavaScript object, + then returns the wrapper object. + 3. When JavaScript code invokes a method or property accessor on the class, + the corresponding `napi_callback` C++ function is invoked. For an instance + callback, [`napi_unwrap`][] obtains the C++ instance that is the target of + the call. + +For wrapped objects it may be difficult to distinguish between a function +called on a class prototype and a function called on an instance of a class. +A common pattern used to address this problem is to save a persistent +reference to the class constructor for later `instanceof` checks. + +```C +napi_value MyClass_constructor = NULL; +status = napi_get_reference_value(env, MyClass::es_constructor, &MyClass_constructor); +assert(napi_ok == status); +bool is_instance = false; +status = napi_instanceof(env, es_this, MyClass_constructor, &is_instance); +assert(napi_ok == status); +if (is_instance) { + // napi_unwrap() ... +} else { + // otherwise... +} +``` + +The reference must be freed once it is no longer needed. + diff --git a/n-api/promises.md b/n-api/promises.md new file mode 100644 index 00000000..012fa843 --- /dev/null +++ b/n-api/promises.md @@ -0,0 +1,53 @@ + +N-API provides facilities for creating `Promise` objects as described in +[Section 25.4][] of the ECMA specification. It implements promises as a pair of +objects. When a promise is created by `napi_create_promise()`, a "deferred" +object is created and returned alongside the `Promise`. The deferred object is +bound to the created `Promise` and is the only means to resolve or reject the +`Promise` using `napi_resolve_deferred()` or `napi_reject_deferred()`. The +deferred object that is created by `napi_create_promise()` is freed by +`napi_resolve_deferred()` or `napi_reject_deferred()`. The `Promise` object may +be returned to JavaScript where it can be used in the usual fashion. + +For example, to create a promise and pass it to an asynchronous worker: +```c +napi_deferred deferred; +napi_value promise; +napi_status status; + +// Create the promise. +status = napi_create_promise(env, &deferred, &promise); +if (status != napi_ok) return NULL; + +// Pass the deferred to a function that performs an asynchronous action. +do_something_asynchronous(deferred); + +// Return the promise to JS +return promise; +``` + +The above function `do_something_asynchronous()` would perform its asynchronous +action and then it would resolve or reject the deferred, thereby concluding the +promise and freeing the deferred: +```c +napi_deferred deferred; +napi_value undefined; +napi_status status; + +// Create a value with which to conclude the deferred. +status = napi_get_undefined(env, &undefined); +if (status != napi_ok) return NULL; + +// Resolve or reject the promise associated with the deferred depending on +// whether the asynchronous action succeeded. +if (asynchronous_action_succeeded) { + status = napi_resolve_deferred(env, deferred, undefined); +} else { + status = napi_reject_deferred(env, deferred, undefined); +} +if (status != napi_ok) return NULL; + +// At this point the deferred has been freed, so we should assign NULL to it. +deferred = NULL; +``` + diff --git a/n-api/references_to_objects_with_a_lifespan_longer_than_that_of_the_native_method.md b/n-api/references_to_objects_with_a_lifespan_longer_than_that_of_the_native_method.md new file mode 100644 index 00000000..8d87aea7 --- /dev/null +++ b/n-api/references_to_objects_with_a_lifespan_longer_than_that_of_the_native_method.md @@ -0,0 +1,38 @@ + +In some cases an addon will need to be able to create and reference objects +with a lifespan longer than that of a single native method invocation. For +example, to create a constructor and later use that constructor +in a request to creates instances, it must be possible to reference +the constructor object across many different instance creation requests. This +would not be possible with a normal handle returned as a `napi_value` as +described in the earlier section. The lifespan of a normal handle is +managed by scopes and all scopes must be closed before the end of a native +method. + +N-API provides methods to create persistent references to an object. +Each persistent reference has an associated count with a value of 0 +or higher. The count determines if the reference will keep +the corresponding object live. References with a count of 0 do not +prevent the object from being collected and are often called 'weak' +references. Any count greater than 0 will prevent the object +from being collected. + +References can be created with an initial reference count. The count can +then be modified through [`napi_reference_ref`][] and +[`napi_reference_unref`][]. If an object is collected while the count +for a reference is 0, all subsequent calls to +get the object associated with the reference [`napi_get_reference_value`][] +will return NULL for the returned `napi_value`. An attempt to call +[`napi_reference_ref`][] for a reference whose object has been collected +will result in an error. + +References must be deleted once they are no longer required by the addon. When +a reference is deleted it will no longer prevent the corresponding object from +being collected. Failure to delete a persistent reference will result in +a 'memory leak' with both the native memory for the persistent reference and +the corresponding object on the heap being retained forever. + +There can be multiple persistent references created which refer to the same +object, each of which will either keep the object live or not based on its +individual count. + diff --git a/n-api/return_values.md b/n-api/return_values.md new file mode 100644 index 00000000..21a94229 --- /dev/null +++ b/n-api/return_values.md @@ -0,0 +1,46 @@ +All of the N-API functions share the same error handling pattern. The +return type of all API functions is `napi_status`. + +The return value will be `napi_ok` if the request was successful and +no uncaught JavaScript exception was thrown. If an error occurred AND +an exception was thrown, the `napi_status` value for the error +will be returned. If an exception was thrown, and no error occurred, +`napi_pending_exception` will be returned. + +In cases where a return value other than `napi_ok` or +`napi_pending_exception` is returned, [`napi_is_exception_pending`][] +must be called to check if an exception is pending. +See the section on exceptions for more details. + +The full set of possible `napi_status` values is defined +in `napi_api_types.h`. + +The `napi_status` return value provides a VM-independent representation of +the error which occurred. In some cases it is useful to be able to get +more detailed information, including a string representing the error as well as +VM (engine)-specific information. + +In order to retrieve this information [`napi_get_last_error_info`][] +is provided which returns a `napi_extended_error_info` structure. +The format of the `napi_extended_error_info` structure is as follows: + +```C +typedef struct napi_extended_error_info { + const char* error_message; + void* engine_reserved; + uint32_t engine_error_code; + napi_status error_code; +}; +``` +- `error_message`: Textual representation of the error that occurred. +- `engine_reserved`: Opaque handle reserved for engine use only. +- `engine_error_code`: VM specific error code. +- `error_code`: n-api status code for the last error. + +[`napi_get_last_error_info`][] returns the information for the last +N-API call that was made. + +Do not rely on the content or format of any of the extended information as it +is not subject to SemVer and may change at any time. It is intended only for +logging purposes. + diff --git a/n-api/script_execution.md b/n-api/script_execution.md new file mode 100644 index 00000000..41c956fd --- /dev/null +++ b/n-api/script_execution.md @@ -0,0 +1,4 @@ + +N-API provides an API for executing a string containing JavaScript using the +underlying JavaScript engine. + diff --git a/n-api/simple_asynchronous_operations.md b/n-api/simple_asynchronous_operations.md new file mode 100644 index 00000000..76bd4ca2 --- /dev/null +++ b/n-api/simple_asynchronous_operations.md @@ -0,0 +1,53 @@ + +Addon modules often need to leverage async helpers from libuv as part of their +implementation. This allows them to schedule work to be executed asynchronously +so that their methods can return in advance of the work being completed. This +is important in order to allow them to avoid blocking overall execution +of the Node.js application. + +N-API provides an ABI-stable interface for these +supporting functions which covers the most common asynchronous use cases. + +N-API defines the `napi_work` structure which is used to manage +asynchronous workers. Instances are created/deleted with +[`napi_create_async_work`][] and [`napi_delete_async_work`][]. + +The `execute` and `complete` callbacks are functions that will be +invoked when the executor is ready to execute and when it completes its +task respectively. + +The `execute` function should avoid making any N-API calls +that could result in the execution of JavaScript or interaction with +JavaScript objects. Most often, any code that needs to make N-API +calls should be made in `complete` callback instead. + +These functions implement the following interfaces: + +```C +typedef void (*napi_async_execute_callback)(napi_env env, + void* data); +typedef void (*napi_async_complete_callback)(napi_env env, + napi_status status, + void* data); +``` + +When these methods are invoked, the `data` parameter passed will be the +addon-provided `void*` data that was passed into the +`napi_create_async_work` call. + +Once created the async worker can be queued +for execution using the [`napi_queue_async_work`][] function: + +```C +napi_status napi_queue_async_work(napi_env env, + napi_async_work work); +``` + +[`napi_cancel_async_work`][] can be used if the work needs +to be cancelled before the work has started execution. + +After calling [`napi_cancel_async_work`][], the `complete` callback +will be invoked with a status value of `napi_cancelled`. +The work should not be deleted before the `complete` +callback invocation, even when it was cancelled. + diff --git a/n-api/structures.md b/n-api/structures.md new file mode 100644 index 00000000..e69de29b diff --git a/api-docs/feb8894dbede8ccd0a9b9d00f5ad6839355d50030cf84e50f7b9c9af47b0aea8.md b/n-api/usage.md similarity index 100% rename from api-docs/feb8894dbede8ccd0a9b9d00f5ad6839355d50030cf84e50f7b9c9af47b0aea8.md rename to n-api/usage.md diff --git a/n-api/version_management.md b/n-api/version_management.md new file mode 100644 index 00000000..8b137891 --- /dev/null +++ b/n-api/version_management.md @@ -0,0 +1 @@ + diff --git a/n-api/working_with_javascript_functions.md b/n-api/working_with_javascript_functions.md new file mode 100644 index 00000000..30ff3a73 --- /dev/null +++ b/n-api/working_with_javascript_functions.md @@ -0,0 +1,22 @@ + +N-API provides a set of APIs that allow JavaScript code to +call back into native code. N-API APIs that support calling back +into native code take in a callback functions represented by +the `napi_callback` type. When the JavaScript VM calls back to +native code, the `napi_callback` function provided is invoked. The APIs +documented in this section allow the callback function to do the +following: +- Get information about the context in which the callback was invoked. +- Get the arguments passed into the callback. +- Return a `napi_value` back from the callback. + +Additionally, N-API provides a set of functions which allow calling +JavaScript functions from native code. One can either call a function +like a regular JavaScript function call, or as a constructor +function. + +Any non-`NULL` data which is passed to this API via the `data` field of the +`napi_property_descriptor` items can be associated with `object` and freed +whenever `object` is garbage-collected by passing both `object` and the data to +[`napi_add_finalizer`][]. + diff --git a/api-docs/8530f657f0e7d4f66be505fa2d6d5d7bd3441a92cfa53690449bddaddcb85de1.md b/n-api/working_with_javascript_properties.md similarity index 100% rename from api-docs/8530f657f0e7d4f66be505fa2d6d5d7bd3441a92cfa53690449bddaddcb85de1.md rename to n-api/working_with_javascript_properties.md diff --git a/api-docs/d3f36f48f25bad0e620685b71279a17b4198c79fe869621bff513a40dfbc7c08.md b/n-api/working_with_javascript_values.md similarity index 100% rename from api-docs/d3f36f48f25bad0e620685b71279a17b4198c79fe869621bff513a40dfbc7c08.md rename to n-api/working_with_javascript_values.md diff --git a/api-docs/6a04770d26c39d6907675e72ea60239f8311dccf85f9a5dd632eaf67c07345ae.md b/n-api/working_with_javascript_values_abstract_operations.md similarity index 100% rename from api-docs/6a04770d26c39d6907675e72ea60239f8311dccf85f9a5dd632eaf67c07345ae.md rename to n-api/working_with_javascript_values_abstract_operations.md diff --git a/api-docs/444fe4e3536fd87196b94b73692173a828c475fc7179f09c2a4ae471217998eb.md b/net/class_net_server.md similarity index 100% rename from api-docs/444fe4e3536fd87196b94b73692173a828c475fc7179f09c2a4ae471217998eb.md rename to net/class_net_server.md diff --git a/api-docs/b655f5b44ec7e3caa219705578c3f83592e32f8e5484a0f5cc656c6c7415af8f.md b/net/class_net_socket.md similarity index 100% rename from api-docs/b655f5b44ec7e3caa219705578c3f83592e32f8e5484a0f5cc656c6c7415af8f.md rename to net/class_net_socket.md diff --git a/api-docs/7594fc36670ab5ed081dbe14f7d64b7d6a37a662cc9300131f90fc6de79e534d.md b/net/event_close.md similarity index 100% rename from api-docs/7594fc36670ab5ed081dbe14f7d64b7d6a37a662cc9300131f90fc6de79e534d.md rename to net/event_close.md diff --git a/api-docs/272a5b50c8c926c653806ced6a2d81b0fee3ab7c56f7c270719fa0f5089b8737.md b/net/event_close_1.md similarity index 100% rename from api-docs/272a5b50c8c926c653806ced6a2d81b0fee3ab7c56f7c270719fa0f5089b8737.md rename to net/event_close_1.md diff --git a/api-docs/871ab4afded427b3676d4b4a43878b07d06c580e27bb20b0f09a5418894793d6.md b/net/event_connect.md similarity index 100% rename from api-docs/871ab4afded427b3676d4b4a43878b07d06c580e27bb20b0f09a5418894793d6.md rename to net/event_connect.md diff --git a/api-docs/f36cab84b6b4a90029789a92443b65243060a180ace7a793b5262bbc35f129e5.md b/net/event_connection.md similarity index 100% rename from api-docs/f36cab84b6b4a90029789a92443b65243060a180ace7a793b5262bbc35f129e5.md rename to net/event_connection.md diff --git a/api-docs/ef50ab823a43066dff280368000b18029692aea813cf0d561efc9064c4836521.md b/net/event_data.md similarity index 100% rename from api-docs/ef50ab823a43066dff280368000b18029692aea813cf0d561efc9064c4836521.md rename to net/event_data.md diff --git a/api-docs/0b4b90e9dc8cce01c60fbba11801a0c638190377bf03582e361ffc8e693f5f77.md b/net/event_drain.md similarity index 100% rename from api-docs/0b4b90e9dc8cce01c60fbba11801a0c638190377bf03582e361ffc8e693f5f77.md rename to net/event_drain.md diff --git a/api-docs/3a0e5de7e0fbda65763538682e33588b2722369a8aa59c8cfa9b40f72b241712.md b/net/event_end.md similarity index 100% rename from api-docs/3a0e5de7e0fbda65763538682e33588b2722369a8aa59c8cfa9b40f72b241712.md rename to net/event_end.md diff --git a/api-docs/b06a9a774d016dcc5b8beeae8b47fa24bb911ab56453b3536101c242cf6702c9.md b/net/event_error.md similarity index 100% rename from api-docs/b06a9a774d016dcc5b8beeae8b47fa24bb911ab56453b3536101c242cf6702c9.md rename to net/event_error.md diff --git a/api-docs/d93a6b71bd3efc4a38a4c5e7322d8dd511de948538397b61e4a4cf0cd73cc07e.md b/net/event_error_1.md similarity index 100% rename from api-docs/d93a6b71bd3efc4a38a4c5e7322d8dd511de948538397b61e4a4cf0cd73cc07e.md rename to net/event_error_1.md diff --git a/api-docs/12fda2ea712c8fea31c57bd138926b998145976cfa8af87f3c3eae317fb3b139.md b/net/event_listening.md similarity index 100% rename from api-docs/12fda2ea712c8fea31c57bd138926b998145976cfa8af87f3c3eae317fb3b139.md rename to net/event_listening.md diff --git a/api-docs/7a4b12d80dbb54713ebb341d29760df11716b307ece9731b865d1617c92da36e.md b/net/event_lookup.md similarity index 100% rename from api-docs/7a4b12d80dbb54713ebb341d29760df11716b307ece9731b865d1617c92da36e.md rename to net/event_lookup.md diff --git a/api-docs/92e99347b810cfd9ed9f3e1752477cfd657b808c672b37c9ecdc813e2abc4d96.md b/net/event_ready.md similarity index 100% rename from api-docs/92e99347b810cfd9ed9f3e1752477cfd657b808c672b37c9ecdc813e2abc4d96.md rename to net/event_ready.md diff --git a/api-docs/690ce8b67821316f68085b6cb8b0b148d9310115b8860d2deac42a73e6d12f93.md b/net/event_timeout.md similarity index 100% rename from api-docs/690ce8b67821316f68085b6cb8b0b148d9310115b8860d2deac42a73e6d12f93.md rename to net/event_timeout.md diff --git a/api-docs/1d799c7e59bfbeb55423d44b40b14cbb0d8dce632a3e152ba0b00166eff7654b.md b/net/identifying_paths_for_ipc_connections.md similarity index 100% rename from api-docs/1d799c7e59bfbeb55423d44b40b14cbb0d8dce632a3e152ba0b00166eff7654b.md rename to net/identifying_paths_for_ipc_connections.md diff --git a/api-docs/eaabde7088c5dc35de0e99da7b7e7bfadcf06e447b5fa4a1f8be6f08bd959f44.md b/net/ipc_support.md similarity index 100% rename from api-docs/eaabde7088c5dc35de0e99da7b7e7bfadcf06e447b5fa4a1f8be6f08bd959f44.md rename to net/ipc_support.md diff --git a/api-docs/d49e34ad4f7a70a59e8a535e5132e9703f70e3a5dd3395037385dfc45a532342.md b/net/net.md similarity index 100% rename from api-docs/d49e34ad4f7a70a59e8a535e5132e9703f70e3a5dd3395037385dfc45a532342.md rename to net/net.md diff --git a/api-docs/abfc54517f9cf18b758db4ab4dec088de4e1655519575553d4b696e3a4bd7d4e.md b/net/net_connect.md similarity index 100% rename from api-docs/abfc54517f9cf18b758db4ab4dec088de4e1655519575553d4b696e3a4bd7d4e.md rename to net/net_connect.md diff --git a/api-docs/5ecc6b331051b6107a39db85e55e978d82212d7caab0a7e7c6c21a67ed6e6105.md b/net/net_connect_options_connectlistener.md similarity index 100% rename from api-docs/5ecc6b331051b6107a39db85e55e978d82212d7caab0a7e7c6c21a67ed6e6105.md rename to net/net_connect_options_connectlistener.md diff --git a/api-docs/33c24e63616b01b4796e350e07455709fbe13e3cda453c6a82c3c6028da28a72.md b/net/net_connect_path_connectlistener.md similarity index 100% rename from api-docs/33c24e63616b01b4796e350e07455709fbe13e3cda453c6a82c3c6028da28a72.md rename to net/net_connect_path_connectlistener.md diff --git a/api-docs/54849e546a0ecc87a0d9ba84b2a70bcc8f964935ed234508a5733729ddec44a4.md b/net/net_connect_port_host_connectlistener.md similarity index 100% rename from api-docs/54849e546a0ecc87a0d9ba84b2a70bcc8f964935ed234508a5733729ddec44a4.md rename to net/net_connect_port_host_connectlistener.md diff --git a/api-docs/27a161adcaf65083cbf9969afe5ca563f5f4b89c0ccf0742051cd4da4353836f.md b/net/net_createconnection.md similarity index 100% rename from api-docs/27a161adcaf65083cbf9969afe5ca563f5f4b89c0ccf0742051cd4da4353836f.md rename to net/net_createconnection.md diff --git a/api-docs/22b664d8a4d37c2e25d1053bcfec76c71cacd457608a40863013e95b1e29e9b7.md b/net/net_createconnection_options_connectlistener.md similarity index 100% rename from api-docs/22b664d8a4d37c2e25d1053bcfec76c71cacd457608a40863013e95b1e29e9b7.md rename to net/net_createconnection_options_connectlistener.md diff --git a/api-docs/eb803effce9071c948179dce54aa943f4fa5f8dbc56bc487ee97bd13f28e03a0.md b/net/net_createconnection_path_connectlistener.md similarity index 100% rename from api-docs/eb803effce9071c948179dce54aa943f4fa5f8dbc56bc487ee97bd13f28e03a0.md rename to net/net_createconnection_path_connectlistener.md diff --git a/api-docs/1dcf406ca190a8c67d4868037f701c67fdb0beccee1ff62ca4e54972efb805fa.md b/net/net_createconnection_port_host_connectlistener.md similarity index 100% rename from api-docs/1dcf406ca190a8c67d4868037f701c67fdb0beccee1ff62ca4e54972efb805fa.md rename to net/net_createconnection_port_host_connectlistener.md diff --git a/api-docs/f07c7ddf8de02140ee09940658ccf4f3db0a4a6c929214547c57691be8a33b2f.md b/net/net_createserver_options_connectionlistener.md similarity index 100% rename from api-docs/f07c7ddf8de02140ee09940658ccf4f3db0a4a6c929214547c57691be8a33b2f.md rename to net/net_createserver_options_connectionlistener.md diff --git a/api-docs/bef8d98b512bb81462adde5be0a145b6c51d66b13ef8ee403551e9e01632447b.md b/net/net_isip_input.md similarity index 100% rename from api-docs/bef8d98b512bb81462adde5be0a145b6c51d66b13ef8ee403551e9e01632447b.md rename to net/net_isip_input.md diff --git a/api-docs/28bf351349d1211508b0f1b1d3b8225cd9412e9f5fd7a94c18ec3159c1473fb6.md b/net/net_isipv4_input.md similarity index 100% rename from api-docs/28bf351349d1211508b0f1b1d3b8225cd9412e9f5fd7a94c18ec3159c1473fb6.md rename to net/net_isipv4_input.md diff --git a/api-docs/024e685bf36d3c27c7bc6cf5140caac0dcfb4484651837832a54e3cf8676bc12.md b/net/net_isipv6_input.md similarity index 100% rename from api-docs/024e685bf36d3c27c7bc6cf5140caac0dcfb4484651837832a54e3cf8676bc12.md rename to net/net_isipv6_input.md diff --git a/api-docs/7a4375fc896ec1898343d110fede91f38fa3802dd44dbd23c3eb5411b46fc25d.md b/net/new_net_server_options_connectionlistener.md similarity index 100% rename from api-docs/7a4375fc896ec1898343d110fede91f38fa3802dd44dbd23c3eb5411b46fc25d.md rename to net/new_net_server_options_connectionlistener.md diff --git a/api-docs/3da1caa780e309db4af0b0c8d3aee98dbda54be3b91b93157464312ca1246a36.md b/net/new_net_socket_options.md similarity index 100% rename from api-docs/3da1caa780e309db4af0b0c8d3aee98dbda54be3b91b93157464312ca1246a36.md rename to net/new_net_socket_options.md diff --git a/api-docs/fee3760400a14b1512dae184d64d000f61c4c30dbd2ed2e4b84317a8a61401a8.md b/net/server_address.md similarity index 100% rename from api-docs/fee3760400a14b1512dae184d64d000f61c4c30dbd2ed2e4b84317a8a61401a8.md rename to net/server_address.md diff --git a/api-docs/2321cbd1cc1c61140a55b7336046e77280fa6bec30f13dd31b6afa30c166a208.md b/net/server_close_callback.md similarity index 100% rename from api-docs/2321cbd1cc1c61140a55b7336046e77280fa6bec30f13dd31b6afa30c166a208.md rename to net/server_close_callback.md diff --git a/net/server_connections.md b/net/server_connections.md new file mode 100644 index 00000000..5198bbc8 --- /dev/null +++ b/net/server_connections.md @@ -0,0 +1,13 @@ + + +> Stability: 0 - Deprecated: Use [`server.getConnections()`][] instead. + +The number of concurrent connections on the server. + +This becomes `null` when sending a socket to a child with +[`child_process.fork()`][]. To poll forks and get current number of active +connections, use asynchronous [`server.getConnections()`][] instead. + diff --git a/api-docs/cfead7c597dacd63856f5fea37e083544c9522397ea31692dfbf206e1b53d86c.md b/net/server_getconnections_callback.md similarity index 100% rename from api-docs/cfead7c597dacd63856f5fea37e083544c9522397ea31692dfbf206e1b53d86c.md rename to net/server_getconnections_callback.md diff --git a/api-docs/036b75b27ce96ca229d4387f0e0b9a2847986b29338c37f6488d4ae2a4906e77.md b/net/server_listen.md similarity index 100% rename from api-docs/036b75b27ce96ca229d4387f0e0b9a2847986b29338c37f6488d4ae2a4906e77.md rename to net/server_listen.md diff --git a/api-docs/0ff3e4e934a445526f0bbcb784efeb5ea4d1474f9510e807ad7661a0b47a4052.md b/net/server_listen_handle_backlog_callback.md similarity index 100% rename from api-docs/0ff3e4e934a445526f0bbcb784efeb5ea4d1474f9510e807ad7661a0b47a4052.md rename to net/server_listen_handle_backlog_callback.md diff --git a/api-docs/86fb6e901c15274e5f5e5c26e5f274f17fa499a2386e94b9a1379c89d1617d36.md b/net/server_listen_options_callback.md similarity index 100% rename from api-docs/86fb6e901c15274e5f5e5c26e5f274f17fa499a2386e94b9a1379c89d1617d36.md rename to net/server_listen_options_callback.md diff --git a/api-docs/5c296092decf69fe83e929ed56cf2f1f69c391aff1b243be8524ae5765a05785.md b/net/server_listen_path_backlog_callback.md similarity index 100% rename from api-docs/5c296092decf69fe83e929ed56cf2f1f69c391aff1b243be8524ae5765a05785.md rename to net/server_listen_path_backlog_callback.md diff --git a/api-docs/05d9b40850e93c64326f2a4adf7f69a1e5cffa7a6c646f73c09c6c0fb73f6b49.md b/net/server_listen_port_host_backlog_callback.md similarity index 100% rename from api-docs/05d9b40850e93c64326f2a4adf7f69a1e5cffa7a6c646f73c09c6c0fb73f6b49.md rename to net/server_listen_port_host_backlog_callback.md diff --git a/api-docs/56bad574a2964b23841f7f92316f9a77274c1e20f4ff4c88bcc7efb04bae0abe.md b/net/server_listening.md similarity index 100% rename from api-docs/56bad574a2964b23841f7f92316f9a77274c1e20f4ff4c88bcc7efb04bae0abe.md rename to net/server_listening.md diff --git a/api-docs/f016b343aa640b3d167c2e3dac3ccb81ebd426ace7eb801c5fe663f61c9df1f1.md b/net/server_maxconnections.md similarity index 100% rename from api-docs/f016b343aa640b3d167c2e3dac3ccb81ebd426ace7eb801c5fe663f61c9df1f1.md rename to net/server_maxconnections.md diff --git a/api-docs/10e4ae5c397a35936f0533a4f7c7a22b29736aaa9c24e5c22727d2996c660841.md b/net/server_ref.md similarity index 100% rename from api-docs/10e4ae5c397a35936f0533a4f7c7a22b29736aaa9c24e5c22727d2996c660841.md rename to net/server_ref.md diff --git a/api-docs/f5ab9abf859749a46cecf2db5ee7084c9670ea53edba6f8cba5fe205bf051fa1.md b/net/server_unref.md similarity index 100% rename from api-docs/f5ab9abf859749a46cecf2db5ee7084c9670ea53edba6f8cba5fe205bf051fa1.md rename to net/server_unref.md diff --git a/api-docs/b788a39973a4ce3300dad344a7232ea1a634b73531e153802ce7b0069e194ba2.md b/net/socket_address.md similarity index 100% rename from api-docs/b788a39973a4ce3300dad344a7232ea1a634b73531e153802ce7b0069e194ba2.md rename to net/socket_address.md diff --git a/api-docs/6f64ec068d51b70d161572791dee2735539342a9ccd1703477b45d8074bcc7ef.md b/net/socket_buffersize.md similarity index 100% rename from api-docs/6f64ec068d51b70d161572791dee2735539342a9ccd1703477b45d8074bcc7ef.md rename to net/socket_buffersize.md diff --git a/api-docs/15a23393a532fdaeaeb47781e2689aa55ad662b49706dd2d7f126a528dc6a993.md b/net/socket_bytesread.md similarity index 100% rename from api-docs/15a23393a532fdaeaeb47781e2689aa55ad662b49706dd2d7f126a528dc6a993.md rename to net/socket_bytesread.md diff --git a/api-docs/259dbf28e6c972b7f2681fb9858a8af6b064c2cdb85012fa41a09e03403cbb02.md b/net/socket_byteswritten.md similarity index 100% rename from api-docs/259dbf28e6c972b7f2681fb9858a8af6b064c2cdb85012fa41a09e03403cbb02.md rename to net/socket_byteswritten.md diff --git a/api-docs/efd763da70df3610c23663b590a772ce76b3d60700a967dbf9ac31ec7f470733.md b/net/socket_connect.md similarity index 100% rename from api-docs/efd763da70df3610c23663b590a772ce76b3d60700a967dbf9ac31ec7f470733.md rename to net/socket_connect.md diff --git a/api-docs/4425bee0bf5cbe0fa06d187aaa0cf57a342baf05523b2c70c54f6b7711b28ff3.md b/net/socket_connect_options_connectlistener.md similarity index 100% rename from api-docs/4425bee0bf5cbe0fa06d187aaa0cf57a342baf05523b2c70c54f6b7711b28ff3.md rename to net/socket_connect_options_connectlistener.md diff --git a/api-docs/7bede44491d353530f69bd95c4dc81213e46a4a975575e193a3670cfce2e9663.md b/net/socket_connect_path_connectlistener.md similarity index 100% rename from api-docs/7bede44491d353530f69bd95c4dc81213e46a4a975575e193a3670cfce2e9663.md rename to net/socket_connect_path_connectlistener.md diff --git a/api-docs/e880aeb3743e5544ac5e1ccbe918a178ecc96a16335828bc38132a40b7250ce0.md b/net/socket_connect_port_host_connectlistener.md similarity index 100% rename from api-docs/e880aeb3743e5544ac5e1ccbe918a178ecc96a16335828bc38132a40b7250ce0.md rename to net/socket_connect_port_host_connectlistener.md diff --git a/api-docs/6d063d1391436ad115937ef894e320c8c92e32d22aeeeb5646fdebfb28201cc7.md b/net/socket_connecting.md similarity index 100% rename from api-docs/6d063d1391436ad115937ef894e320c8c92e32d22aeeeb5646fdebfb28201cc7.md rename to net/socket_connecting.md diff --git a/api-docs/f06292a73ef0b8a5fe0e29963dccc4f04c6367805489badea9d71330cf413d7b.md b/net/socket_destroy_exception.md similarity index 100% rename from api-docs/f06292a73ef0b8a5fe0e29963dccc4f04c6367805489badea9d71330cf413d7b.md rename to net/socket_destroy_exception.md diff --git a/api-docs/7ca31052b3d7ca7a37d4606c095ba163c19ac330cb6286be3e5df3526afbd312.md b/net/socket_destroyed.md similarity index 100% rename from api-docs/7ca31052b3d7ca7a37d4606c095ba163c19ac330cb6286be3e5df3526afbd312.md rename to net/socket_destroyed.md diff --git a/api-docs/904cc1029a3d76a273cc5276bdb15a9ddfb91a5b65c0bcfa43e6e24b02dfefd1.md b/net/socket_end_data_encoding_callback.md similarity index 100% rename from api-docs/904cc1029a3d76a273cc5276bdb15a9ddfb91a5b65c0bcfa43e6e24b02dfefd1.md rename to net/socket_end_data_encoding_callback.md diff --git a/api-docs/352d60c425c9b3ba61928417f35a9b5a58eba9cb78333c9d1b69ce80bed75c02.md b/net/socket_localaddress.md similarity index 100% rename from api-docs/352d60c425c9b3ba61928417f35a9b5a58eba9cb78333c9d1b69ce80bed75c02.md rename to net/socket_localaddress.md diff --git a/api-docs/24be03367457fc7669889ca225b02994040a2bc07b1a8cc499fc8779441b6fcc.md b/net/socket_localport.md similarity index 100% rename from api-docs/24be03367457fc7669889ca225b02994040a2bc07b1a8cc499fc8779441b6fcc.md rename to net/socket_localport.md diff --git a/api-docs/94eb8af7865aedd82657adb46f2611239c41ecc25781a5b7e918f523eaba4253.md b/net/socket_pause.md similarity index 100% rename from api-docs/94eb8af7865aedd82657adb46f2611239c41ecc25781a5b7e918f523eaba4253.md rename to net/socket_pause.md diff --git a/api-docs/53763898af1fe59a3bcf5c983e9af0425686603421d528cb3c1230893e096197.md b/net/socket_pending.md similarity index 100% rename from api-docs/53763898af1fe59a3bcf5c983e9af0425686603421d528cb3c1230893e096197.md rename to net/socket_pending.md diff --git a/api-docs/9aa2484d3a4f2a2fc775e836997795db4986c2e34b0694dbb278f11ad1c539f2.md b/net/socket_ref.md similarity index 100% rename from api-docs/9aa2484d3a4f2a2fc775e836997795db4986c2e34b0694dbb278f11ad1c539f2.md rename to net/socket_ref.md diff --git a/api-docs/40c9b34870519fe6b712e07fa140ab334bb349b61b3833445e5c1ddddb58e085.md b/net/socket_remoteaddress.md similarity index 100% rename from api-docs/40c9b34870519fe6b712e07fa140ab334bb349b61b3833445e5c1ddddb58e085.md rename to net/socket_remoteaddress.md diff --git a/api-docs/a0dd9b8289fb391e928938638418cac0890ef28382dd6f86f2f406a4669e635a.md b/net/socket_remotefamily.md similarity index 100% rename from api-docs/a0dd9b8289fb391e928938638418cac0890ef28382dd6f86f2f406a4669e635a.md rename to net/socket_remotefamily.md diff --git a/api-docs/cc3fc0b4f3293d0f33737e08474712a09dd63df38f3722dd1ddbfecfd01fd04f.md b/net/socket_remoteport.md similarity index 100% rename from api-docs/cc3fc0b4f3293d0f33737e08474712a09dd63df38f3722dd1ddbfecfd01fd04f.md rename to net/socket_remoteport.md diff --git a/api-docs/b533e39586b978866f5300515107c493487f1324b929f3220893c4e94d985e4e.md b/net/socket_resume.md similarity index 100% rename from api-docs/b533e39586b978866f5300515107c493487f1324b929f3220893c4e94d985e4e.md rename to net/socket_resume.md diff --git a/api-docs/13542394ac6d3c953dac87f968b49c0ab2f7363d7abe0e867d81c4145cc575f5.md b/net/socket_setencoding_encoding.md similarity index 100% rename from api-docs/13542394ac6d3c953dac87f968b49c0ab2f7363d7abe0e867d81c4145cc575f5.md rename to net/socket_setencoding_encoding.md diff --git a/api-docs/be7e4cefbc3a692277738abf70c99ad409b5fa5f7641623412aaf1dd61f27be2.md b/net/socket_setkeepalive_enable_initialdelay.md similarity index 100% rename from api-docs/be7e4cefbc3a692277738abf70c99ad409b5fa5f7641623412aaf1dd61f27be2.md rename to net/socket_setkeepalive_enable_initialdelay.md diff --git a/api-docs/2fa588864f64a10f07c4173e4b3352d36ed8a1d4191c98461d7b4044f20cd78a.md b/net/socket_setnodelay_nodelay.md similarity index 100% rename from api-docs/2fa588864f64a10f07c4173e4b3352d36ed8a1d4191c98461d7b4044f20cd78a.md rename to net/socket_setnodelay_nodelay.md diff --git a/api-docs/0839882605bae74ecf8223be5441dbddfdbeecc79e023943989505eb97076835.md b/net/socket_settimeout_timeout_callback.md similarity index 100% rename from api-docs/0839882605bae74ecf8223be5441dbddfdbeecc79e023943989505eb97076835.md rename to net/socket_settimeout_timeout_callback.md diff --git a/api-docs/149ffa5002f33ae8d53c8af9c3325ed67fe1de5a8eab1801c929124503514d0c.md b/net/socket_unref.md similarity index 100% rename from api-docs/149ffa5002f33ae8d53c8af9c3325ed67fe1de5a8eab1801c929124503514d0c.md rename to net/socket_unref.md diff --git a/api-docs/8dd9f2b563d58596376c682f1fbf9e106f55c2cec2e5218695d0dc6ce4e6bbe1.md b/net/socket_write_data_encoding_callback.md similarity index 100% rename from api-docs/8dd9f2b563d58596376c682f1fbf9e106f55c2cec2e5218695d0dc6ce4e6bbe1.md rename to net/socket_write_data_encoding_callback.md diff --git a/api-docs/191356d1c1b5179bbbee88d9c04493e381028c0465421870a43b2714203b2cea.md b/os/dlopen_constants.md similarity index 100% rename from api-docs/191356d1c1b5179bbbee88d9c04493e381028c0465421870a43b2714203b2cea.md rename to os/dlopen_constants.md diff --git a/api-docs/12364dce27a0712f33809f90bcea9ea384511020674c6478ef1270e93ace4645.md b/os/error_constants.md similarity index 100% rename from api-docs/12364dce27a0712f33809f90bcea9ea384511020674c6478ef1270e93ace4645.md rename to os/error_constants.md diff --git a/api-docs/30b9fa0e4f88542f2fefbd7dae8b810dbbff9412bd4e38d896205ca19d323d98.md b/os/libuv_constants.md similarity index 100% rename from api-docs/30b9fa0e4f88542f2fefbd7dae8b810dbbff9412bd4e38d896205ca19d323d98.md rename to os/libuv_constants.md diff --git a/api-docs/e0f075acaafe67278fd54f72500956b5bf5b30cd77eef0cfeb59856ebe36053e.md b/os/os.md similarity index 100% rename from api-docs/e0f075acaafe67278fd54f72500956b5bf5b30cd77eef0cfeb59856ebe36053e.md rename to os/os.md diff --git a/api-docs/60e7755b387cda29f22c7da7eac155365a0618afb5962b9eac01ff5fefe6795a.md b/os/os_arch.md similarity index 100% rename from api-docs/60e7755b387cda29f22c7da7eac155365a0618afb5962b9eac01ff5fefe6795a.md rename to os/os_arch.md diff --git a/api-docs/9e03bb377765b06984c4333180fee69350762a3cc2d4f2af1c72d757f4cf2e30.md b/os/os_constants.md similarity index 100% rename from api-docs/9e03bb377765b06984c4333180fee69350762a3cc2d4f2af1c72d757f4cf2e30.md rename to os/os_constants.md diff --git a/api-docs/62442b41fbfa65dc041f987636de1ff0c70728241be7382222f179902c93b146.md b/os/os_constants_1.md similarity index 100% rename from api-docs/62442b41fbfa65dc041f987636de1ff0c70728241be7382222f179902c93b146.md rename to os/os_constants_1.md diff --git a/api-docs/1504ccb0dc31908579c56cfe9add079117375f2b37f54e94e79a22df8c587f08.md b/os/os_cpus.md similarity index 100% rename from api-docs/1504ccb0dc31908579c56cfe9add079117375f2b37f54e94e79a22df8c587f08.md rename to os/os_cpus.md diff --git a/api-docs/c7a05accd6eda46089046852407110aa1cb3145946e2e1063426862c0b67e5e0.md b/os/os_endianness.md similarity index 100% rename from api-docs/c7a05accd6eda46089046852407110aa1cb3145946e2e1063426862c0b67e5e0.md rename to os/os_endianness.md diff --git a/api-docs/f72e2197f641b9c06102b7eefeeb2c8e92262c392bec981eee5009cf2d17b0da.md b/os/os_eol.md similarity index 100% rename from api-docs/f72e2197f641b9c06102b7eefeeb2c8e92262c392bec981eee5009cf2d17b0da.md rename to os/os_eol.md diff --git a/api-docs/b38234650ad5bc39a3a08d7baabe6d1760d613ff5f506aeefef905ffef1cd717.md b/os/os_freemem.md similarity index 100% rename from api-docs/b38234650ad5bc39a3a08d7baabe6d1760d613ff5f506aeefef905ffef1cd717.md rename to os/os_freemem.md diff --git a/api-docs/2b8732a8fa9745057c2db256bb28cb8814ec89866e1e5f2a0485d494ef8c772b.md b/os/os_getpriority_pid.md similarity index 100% rename from api-docs/2b8732a8fa9745057c2db256bb28cb8814ec89866e1e5f2a0485d494ef8c772b.md rename to os/os_getpriority_pid.md diff --git a/api-docs/2ba53310c87e58d6cc9dfdf1c367cec9f3bc02fbb4bb127d8f5c5fd8a8809cfa.md b/os/os_homedir.md similarity index 100% rename from api-docs/2ba53310c87e58d6cc9dfdf1c367cec9f3bc02fbb4bb127d8f5c5fd8a8809cfa.md rename to os/os_homedir.md diff --git a/api-docs/8604c165dc91f0c8bdad77df2fe6f67fb1ce1b1eb4f885748539c98d5f6fca1a.md b/os/os_hostname.md similarity index 100% rename from api-docs/8604c165dc91f0c8bdad77df2fe6f67fb1ce1b1eb4f885748539c98d5f6fca1a.md rename to os/os_hostname.md diff --git a/api-docs/a45f731a6d5ef36d868bb5faec5d51d940e5482bfafd063490c6c9a954cedd4a.md b/os/os_loadavg.md similarity index 100% rename from api-docs/a45f731a6d5ef36d868bb5faec5d51d940e5482bfafd063490c6c9a954cedd4a.md rename to os/os_loadavg.md diff --git a/api-docs/4139ab9561e3d314851c58a5f8d2eae7e05fea23291dfac2455fd1e69764e042.md b/os/os_networkinterfaces.md similarity index 100% rename from api-docs/4139ab9561e3d314851c58a5f8d2eae7e05fea23291dfac2455fd1e69764e042.md rename to os/os_networkinterfaces.md diff --git a/api-docs/5df3cff8ad738171b84628225242a9bde874886321af4b27b48381f72bbe61b4.md b/os/os_platform.md similarity index 100% rename from api-docs/5df3cff8ad738171b84628225242a9bde874886321af4b27b48381f72bbe61b4.md rename to os/os_platform.md diff --git a/api-docs/1443e1c16c4335b1b01a358b24468403dde4d8f286a2ca3f2a973be137a18a61.md b/os/os_release.md similarity index 100% rename from api-docs/1443e1c16c4335b1b01a358b24468403dde4d8f286a2ca3f2a973be137a18a61.md rename to os/os_release.md diff --git a/api-docs/806b1e03c470dae878ac5f89428d635e129d8db710f27aaa7c279f1769fbc25c.md b/os/os_setpriority_pid_priority.md similarity index 100% rename from api-docs/806b1e03c470dae878ac5f89428d635e129d8db710f27aaa7c279f1769fbc25c.md rename to os/os_setpriority_pid_priority.md diff --git a/api-docs/ff7ccaf9950a8113fea571607b06694954ca90e35f542167545d2315f57bdc62.md b/os/os_tmpdir.md similarity index 100% rename from api-docs/ff7ccaf9950a8113fea571607b06694954ca90e35f542167545d2315f57bdc62.md rename to os/os_tmpdir.md diff --git a/api-docs/130fc7c43ea4d2939a9c398968ba59146ab277b1771f1be8137203f78850932e.md b/os/os_totalmem.md similarity index 100% rename from api-docs/130fc7c43ea4d2939a9c398968ba59146ab277b1771f1be8137203f78850932e.md rename to os/os_totalmem.md diff --git a/api-docs/c19660ab1f347883e4a14ff87cdaf0a6ff25752e02d379a5a274a1f910834d65.md b/os/os_type.md similarity index 100% rename from api-docs/c19660ab1f347883e4a14ff87cdaf0a6ff25752e02d379a5a274a1f910834d65.md rename to os/os_type.md diff --git a/api-docs/554bfdabc61a42fb3c9a43a247fc79148da73e20e10e132f278d76af71251fd6.md b/os/os_uptime.md similarity index 100% rename from api-docs/554bfdabc61a42fb3c9a43a247fc79148da73e20e10e132f278d76af71251fd6.md rename to os/os_uptime.md diff --git a/api-docs/42d6216c3d086ace6b05792743a7cd88613cabb8692e83c0332f5d023d0ffd64.md b/os/os_userinfo_options.md similarity index 100% rename from api-docs/42d6216c3d086ace6b05792743a7cd88613cabb8692e83c0332f5d023d0ffd64.md rename to os/os_userinfo_options.md diff --git a/api-docs/a3a493ed378e1201cdecb3c4cc17574bcc29206423835b00bc9ac44d72db8ed6.md b/os/posix_error_constants.md similarity index 100% rename from api-docs/a3a493ed378e1201cdecb3c4cc17574bcc29206423835b00bc9ac44d72db8ed6.md rename to os/posix_error_constants.md diff --git a/api-docs/6ee753e14c23b1cca6ea15d0eb367eb8585fa5001dd9841467fcc66434b7321e.md b/os/priority_constants.md similarity index 100% rename from api-docs/6ee753e14c23b1cca6ea15d0eb367eb8585fa5001dd9841467fcc66434b7321e.md rename to os/priority_constants.md diff --git a/api-docs/41fe7ec871be098f0c6b09237bbd4f347819f3956e3a0e8203907919921ee5f8.md b/os/signal_constants.md similarity index 100% rename from api-docs/41fe7ec871be098f0c6b09237bbd4f347819f3956e3a0e8203907919921ee5f8.md rename to os/signal_constants.md diff --git a/api-docs/06ccb11bce48e14eb91f9c81c90b4c62490a4f55517110a4523cab5142d7c818.md b/os/windows_specific_error_constants.md similarity index 100% rename from api-docs/06ccb11bce48e14eb91f9c81c90b4c62490a4f55517110a4523cab5142d7c818.md rename to os/windows_specific_error_constants.md diff --git a/api-docs/cd868ed33b6f69c2e88b29e999bbacc1ddd72f6fe994b7883d3052ccb6bf5342.md b/path/path.md similarity index 100% rename from api-docs/cd868ed33b6f69c2e88b29e999bbacc1ddd72f6fe994b7883d3052ccb6bf5342.md rename to path/path.md diff --git a/api-docs/4b96f0b1ddd792a30c8cddbf737b76021667451e56d09375574228098672e955.md b/path/path_basename_path_ext.md similarity index 100% rename from api-docs/4b96f0b1ddd792a30c8cddbf737b76021667451e56d09375574228098672e955.md rename to path/path_basename_path_ext.md diff --git a/api-docs/89aa6eae0d36124291e5a2f2b292ac6ebef7872981234e46f71ea113b05db08b.md b/path/path_delimiter.md similarity index 100% rename from api-docs/89aa6eae0d36124291e5a2f2b292ac6ebef7872981234e46f71ea113b05db08b.md rename to path/path_delimiter.md diff --git a/api-docs/225518d8e55bfaa2a5be01fcc82e6326f7a3fa2d61f2c10d584e4f8e3946681e.md b/path/path_dirname_path.md similarity index 100% rename from api-docs/225518d8e55bfaa2a5be01fcc82e6326f7a3fa2d61f2c10d584e4f8e3946681e.md rename to path/path_dirname_path.md diff --git a/api-docs/a321b713a9e93c556ed34cd50218a7ee7b1a49ce546d966d0dd9e1c9169ff390.md b/path/path_extname_path.md similarity index 100% rename from api-docs/a321b713a9e93c556ed34cd50218a7ee7b1a49ce546d966d0dd9e1c9169ff390.md rename to path/path_extname_path.md diff --git a/api-docs/4c8b64d7f79d4344b1db5bfd3cbf5373b4ed5124b5cba35fdb99b3da9a429f91.md b/path/path_format_pathobject.md similarity index 100% rename from api-docs/4c8b64d7f79d4344b1db5bfd3cbf5373b4ed5124b5cba35fdb99b3da9a429f91.md rename to path/path_format_pathobject.md diff --git a/api-docs/e5e3ace2d4df737a025503fb2059530d9fd8b594dbd1a7ad8cc56ceb4c34375e.md b/path/path_isabsolute_path.md similarity index 100% rename from api-docs/e5e3ace2d4df737a025503fb2059530d9fd8b594dbd1a7ad8cc56ceb4c34375e.md rename to path/path_isabsolute_path.md diff --git a/api-docs/fa1adad0f3a3b9ddf5142b9a456d9cf33c9b89a21c59119858124828ff1404c4.md b/path/path_join_paths.md similarity index 100% rename from api-docs/fa1adad0f3a3b9ddf5142b9a456d9cf33c9b89a21c59119858124828ff1404c4.md rename to path/path_join_paths.md diff --git a/api-docs/b96ccf9ae83f10a3636b4ade13983214708924dfc5dded787778e9e7aeb88f83.md b/path/path_normalize_path.md similarity index 100% rename from api-docs/b96ccf9ae83f10a3636b4ade13983214708924dfc5dded787778e9e7aeb88f83.md rename to path/path_normalize_path.md diff --git a/api-docs/99b69617f87e69ff2271d13cc6620d9594464cfbcc38f607033855cd0dd2a2af.md b/path/path_parse_path.md similarity index 100% rename from api-docs/99b69617f87e69ff2271d13cc6620d9594464cfbcc38f607033855cd0dd2a2af.md rename to path/path_parse_path.md diff --git a/api-docs/e3475461353ed369b54c75655e72f5dc4b6502ee4edfb0f8e852cfe849bceae6.md b/path/path_posix.md similarity index 100% rename from api-docs/e3475461353ed369b54c75655e72f5dc4b6502ee4edfb0f8e852cfe849bceae6.md rename to path/path_posix.md diff --git a/api-docs/6db526ec4edd349fee40ad44b655678a3b7cf5fcefd31addda3d5804a1eb7706.md b/path/path_relative_from_to.md similarity index 100% rename from api-docs/6db526ec4edd349fee40ad44b655678a3b7cf5fcefd31addda3d5804a1eb7706.md rename to path/path_relative_from_to.md diff --git a/api-docs/eaa58fbb6ccc10579c07208c56949c7e054cbe3d036c7cf04a79920ed9575930.md b/path/path_resolve_paths.md similarity index 100% rename from api-docs/eaa58fbb6ccc10579c07208c56949c7e054cbe3d036c7cf04a79920ed9575930.md rename to path/path_resolve_paths.md diff --git a/api-docs/2583a383f987d37806fecfd83ed804b8207208273b8ed462eb28ea63962f5755.md b/path/path_sep.md similarity index 100% rename from api-docs/2583a383f987d37806fecfd83ed804b8207208273b8ed462eb28ea63962f5755.md rename to path/path_sep.md diff --git a/api-docs/3beac2760f193428250e95f3698d28c5bffdf9432c5b0ed598d6d2eb2324a130.md b/path/path_tonamespacedpath_path.md similarity index 100% rename from api-docs/3beac2760f193428250e95f3698d28c5bffdf9432c5b0ed598d6d2eb2324a130.md rename to path/path_tonamespacedpath_path.md diff --git a/api-docs/2124970b564f9a5715ce44230e71b51babb57d34cb16229d8d43c107dec5dc9e.md b/path/path_win32.md similarity index 100% rename from api-docs/2124970b564f9a5715ce44230e71b51babb57d34cb16229d8d43c107dec5dc9e.md rename to path/path_win32.md diff --git a/api-docs/b08cfd163b6bdcf8eea96829927c01ec9655d981ff2495cb9dfa3288210ea57a.md b/path/windows_vs_posix.md similarity index 100% rename from api-docs/b08cfd163b6bdcf8eea96829927c01ec9655d981ff2495cb9dfa3288210ea57a.md rename to path/windows_vs_posix.md diff --git a/perf_hooks/class_histogram.md b/perf_hooks/class_histogram.md new file mode 100644 index 00000000..595f0f26 --- /dev/null +++ b/perf_hooks/class_histogram.md @@ -0,0 +1,5 @@ + +Tracks the event loop delay at a given sampling rate. + diff --git a/perf_hooks/class_performance.md b/perf_hooks/class_performance.md new file mode 100644 index 00000000..5734aabe --- /dev/null +++ b/perf_hooks/class_performance.md @@ -0,0 +1,4 @@ + + diff --git a/perf_hooks/class_performanceentry.md b/perf_hooks/class_performanceentry.md new file mode 100644 index 00000000..5734aabe --- /dev/null +++ b/perf_hooks/class_performanceentry.md @@ -0,0 +1,4 @@ + + diff --git a/perf_hooks/class_performancenodetiming_extends_performanceentry.md b/perf_hooks/class_performancenodetiming_extends_performanceentry.md new file mode 100644 index 00000000..75efba21 --- /dev/null +++ b/perf_hooks/class_performancenodetiming_extends_performanceentry.md @@ -0,0 +1,6 @@ + + +Provides timing details for Node.js itself. + diff --git a/perf_hooks/class_performanceobserver.md b/perf_hooks/class_performanceobserver.md new file mode 100644 index 00000000..8b137891 --- /dev/null +++ b/perf_hooks/class_performanceobserver.md @@ -0,0 +1 @@ + diff --git a/perf_hooks/class_performanceobserverentrylist.md b/perf_hooks/class_performanceobserverentrylist.md new file mode 100644 index 00000000..1692cad3 --- /dev/null +++ b/perf_hooks/class_performanceobserverentrylist.md @@ -0,0 +1,7 @@ + + +The `PerformanceObserverEntryList` class is used to provide access to the +`PerformanceEntry` instances passed to a `PerformanceObserver`. + diff --git a/perf_hooks/examples.md b/perf_hooks/examples.md new file mode 100644 index 00000000..8b137891 --- /dev/null +++ b/perf_hooks/examples.md @@ -0,0 +1 @@ + diff --git a/perf_hooks/histogram_disable.md b/perf_hooks/histogram_disable.md new file mode 100644 index 00000000..f7ff495b --- /dev/null +++ b/perf_hooks/histogram_disable.md @@ -0,0 +1,9 @@ + + +* Returns: {boolean} + +Disables the event loop delay sample timer. Returns `true` if the timer was +stopped, `false` if it was already stopped. + diff --git a/perf_hooks/histogram_enable.md b/perf_hooks/histogram_enable.md new file mode 100644 index 00000000..9c22da04 --- /dev/null +++ b/perf_hooks/histogram_enable.md @@ -0,0 +1,9 @@ + + +* Returns: {boolean} + +Enables the event loop delay sample timer. Returns `true` if the timer was +started, `false` if it was already started. + diff --git a/perf_hooks/histogram_exceeds.md b/perf_hooks/histogram_exceeds.md new file mode 100644 index 00000000..dc5f789c --- /dev/null +++ b/perf_hooks/histogram_exceeds.md @@ -0,0 +1,9 @@ + + +* {number} + +The number of times the event loop delay exceeded the maximum 1 hour event +loop delay threshold. + diff --git a/perf_hooks/histogram_max.md b/perf_hooks/histogram_max.md new file mode 100644 index 00000000..17c8f0be --- /dev/null +++ b/perf_hooks/histogram_max.md @@ -0,0 +1,8 @@ + + +* {number} + +The maximum recorded event loop delay. + diff --git a/perf_hooks/histogram_mean.md b/perf_hooks/histogram_mean.md new file mode 100644 index 00000000..8d6dc5e9 --- /dev/null +++ b/perf_hooks/histogram_mean.md @@ -0,0 +1,8 @@ + + +* {number} + +The mean of the recorded event loop delays. + diff --git a/perf_hooks/histogram_min.md b/perf_hooks/histogram_min.md new file mode 100644 index 00000000..5903b0f1 --- /dev/null +++ b/perf_hooks/histogram_min.md @@ -0,0 +1,8 @@ + + +* {number} + +The minimum recorded event loop delay. + diff --git a/perf_hooks/histogram_percentile_percentile.md b/perf_hooks/histogram_percentile_percentile.md new file mode 100644 index 00000000..91e5977d --- /dev/null +++ b/perf_hooks/histogram_percentile_percentile.md @@ -0,0 +1,9 @@ + + +* `percentile` {number} A percentile value between 1 and 100. +* Returns: {number} + +Returns the value at the given percentile. + diff --git a/perf_hooks/histogram_percentiles.md b/perf_hooks/histogram_percentiles.md new file mode 100644 index 00000000..e7700f29 --- /dev/null +++ b/perf_hooks/histogram_percentiles.md @@ -0,0 +1,8 @@ + + +* {Map} + +Returns a `Map` object detailing the accumulated percentile distribution. + diff --git a/perf_hooks/histogram_reset.md b/perf_hooks/histogram_reset.md new file mode 100644 index 00000000..591ab96c --- /dev/null +++ b/perf_hooks/histogram_reset.md @@ -0,0 +1,6 @@ + + +Resets the collected histogram data. + diff --git a/perf_hooks/histogram_stddev.md b/perf_hooks/histogram_stddev.md new file mode 100644 index 00000000..fc6b75fd --- /dev/null +++ b/perf_hooks/histogram_stddev.md @@ -0,0 +1,8 @@ + + +* {number} + +The standard deviation of the recorded event loop delays. + diff --git a/api-docs/cd2c01cd7b1350c27b5849394eb48537be8f47013cf19ae5cbea871ef70f49a6.md b/perf_hooks/measuring_how_long_it_takes_to_load_dependencies.md similarity index 100% rename from api-docs/cd2c01cd7b1350c27b5849394eb48537be8f47013cf19ae5cbea871ef70f49a6.md rename to perf_hooks/measuring_how_long_it_takes_to_load_dependencies.md diff --git a/perf_hooks/measuring_the_duration_of_async_operations.md b/perf_hooks/measuring_the_duration_of_async_operations.md new file mode 100644 index 00000000..4c662f43 --- /dev/null +++ b/perf_hooks/measuring_the_duration_of_async_operations.md @@ -0,0 +1,43 @@ + +The following example uses the [Async Hooks][] and Performance APIs to measure +the actual duration of a Timeout operation (including the amount of time it +to execute the callback). + +```js +'use strict'; +const async_hooks = require('async_hooks'); +const { + performance, + PerformanceObserver +} = require('perf_hooks'); + +const set = new Set(); +const hook = async_hooks.createHook({ + init(id, type) { + if (type === 'Timeout') { + performance.mark(`Timeout-${id}-Init`); + set.add(id); + } + }, + destroy(id) { + if (set.has(id)) { + set.delete(id); + performance.mark(`Timeout-${id}-Destroy`); + performance.measure(`Timeout-${id}`, + `Timeout-${id}-Init`, + `Timeout-${id}-Destroy`); + } + } +}); +hook.enable(); + +const obs = new PerformanceObserver((list, observer) => { + console.log(list.getEntries()[0]); + performance.clearMarks(); + observer.disconnect(); +}); +obs.observe({ entryTypes: ['measure'], buffered: true }); + +setTimeout(() => {}, 1000); +``` + diff --git a/perf_hooks/new_performanceobserver_callback.md b/perf_hooks/new_performanceobserver_callback.md new file mode 100644 index 00000000..2799a0c7 --- /dev/null +++ b/perf_hooks/new_performanceobserver_callback.md @@ -0,0 +1,35 @@ + + +* `callback` {Function} + * `list` {PerformanceObserverEntryList} + * `observer` {PerformanceObserver} + +`PerformanceObserver` objects provide notifications when new +`PerformanceEntry` instances have been added to the Performance Timeline. + +```js +const { + performance, + PerformanceObserver +} = require('perf_hooks'); + +const obs = new PerformanceObserver((list, observer) => { + console.log(list.getEntries()); + observer.disconnect(); +}); +obs.observe({ entryTypes: ['mark'], buffered: true }); + +performance.mark('test'); +``` +Because `PerformanceObserver` instances introduce their own additional +performance overhead, instances should not be left subscribed to notifications +indefinitely. Users should disconnect observers as soon as they are no +longer needed. + +The `callback` is invoked when a `PerformanceObserver` is +notified about new `PerformanceEntry` instances. The callback receives a +`PerformanceObserverEntryList` instance and a reference to the +`PerformanceObserver`. + diff --git a/perf_hooks/perf_hooks_monitoreventloopdelay_options.md b/perf_hooks/perf_hooks_monitoreventloopdelay_options.md new file mode 100644 index 00000000..020b29ec --- /dev/null +++ b/perf_hooks/perf_hooks_monitoreventloopdelay_options.md @@ -0,0 +1,33 @@ + + +* `options` {Object} + * `resolution` {number} The sampling rate in milliseconds. Must be greater + than zero. **Default:** `10`. +* Returns: {Histogram} + +Creates a `Histogram` object that samples and reports the event loop delay +over time. The delays will be reported in nanoseconds. + +Using a timer to detect approximate event loop delay works because the +execution of timers is tied specifically to the lifecycle of the libuv +event loop. That is, a delay in the loop will cause a delay in the execution +of the timer, and those delays are specifically what this API is intended to +detect. + +```js +const { monitorEventLoopDelay } = require('perf_hooks'); +const h = monitorEventLoopDelay({ resolution: 20 }); +h.enable(); +// Do something. +h.disable(); +console.log(h.min); +console.log(h.max); +console.log(h.mean); +console.log(h.stddev); +console.log(h.percentiles); +console.log(h.percentile(50)); +console.log(h.percentile(99)); +``` + diff --git a/perf_hooks/performance_clearmarks_name.md b/perf_hooks/performance_clearmarks_name.md new file mode 100644 index 00000000..f6ed9953 --- /dev/null +++ b/perf_hooks/performance_clearmarks_name.md @@ -0,0 +1,9 @@ + + +* `name` {string} + +If `name` is not provided, removes all `PerformanceMark` objects from the +Performance Timeline. If `name` is provided, removes only the named mark. + diff --git a/perf_hooks/performance_mark_name.md b/perf_hooks/performance_mark_name.md new file mode 100644 index 00000000..de336293 --- /dev/null +++ b/perf_hooks/performance_mark_name.md @@ -0,0 +1,12 @@ + + +* `name` {string} + +Creates a new `PerformanceMark` entry in the Performance Timeline. A +`PerformanceMark` is a subclass of `PerformanceEntry` whose +`performanceEntry.entryType` is always `'mark'`, and whose +`performanceEntry.duration` is always `0`. Performance marks are used +to mark specific significant moments in the Performance Timeline. + diff --git a/perf_hooks/performance_measure_name_startmark_endmark.md b/perf_hooks/performance_measure_name_startmark_endmark.md new file mode 100644 index 00000000..d7e34ab1 --- /dev/null +++ b/perf_hooks/performance_measure_name_startmark_endmark.md @@ -0,0 +1,24 @@ + + +* `name` {string} +* `startMark` {string} +* `endMark` {string} + +Creates a new `PerformanceMeasure` entry in the Performance Timeline. A +`PerformanceMeasure` is a subclass of `PerformanceEntry` whose +`performanceEntry.entryType` is always `'measure'`, and whose +`performanceEntry.duration` measures the number of milliseconds elapsed since +`startMark` and `endMark`. + +The `startMark` argument may identify any *existing* `PerformanceMark` in the +Performance Timeline, or *may* identify any of the timestamp properties +provided by the `PerformanceNodeTiming` class. If the named `startMark` does +not exist, then `startMark` is set to [`timeOrigin`][] by default. + +The `endMark` argument must identify any *existing* `PerformanceMark` in the +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. + diff --git a/perf_hooks/performance_nodetiming.md b/perf_hooks/performance_nodetiming.md new file mode 100644 index 00000000..c0b95fc3 --- /dev/null +++ b/perf_hooks/performance_nodetiming.md @@ -0,0 +1,9 @@ + + +* {PerformanceNodeTiming} + +An instance of the `PerformanceNodeTiming` class that provides performance +metrics for specific Node.js operational milestones. + diff --git a/perf_hooks/performance_now.md b/perf_hooks/performance_now.md new file mode 100644 index 00000000..6f31c3e2 --- /dev/null +++ b/perf_hooks/performance_now.md @@ -0,0 +1,9 @@ + + +* Returns: {number} + +Returns the current high resolution millisecond timestamp, where 0 represents +the start of the current `node` process. + diff --git a/perf_hooks/performance_timeorigin.md b/perf_hooks/performance_timeorigin.md new file mode 100644 index 00000000..75f46d4e --- /dev/null +++ b/perf_hooks/performance_timeorigin.md @@ -0,0 +1,9 @@ + + +* {number} + +The [`timeOrigin`][] specifies the high resolution millisecond timestamp at +which the current `node` process began, measured in Unix time. + diff --git a/perf_hooks/performance_timerify_fn.md b/perf_hooks/performance_timerify_fn.md new file mode 100644 index 00000000..a52dede2 --- /dev/null +++ b/perf_hooks/performance_timerify_fn.md @@ -0,0 +1,32 @@ + + +* `fn` {Function} + +Wraps a function within a new function that measures the running time of the +wrapped function. A `PerformanceObserver` must be subscribed to the `'function'` +event type in order for the timing details to be accessed. + +```js +const { + performance, + PerformanceObserver +} = require('perf_hooks'); + +function someFunction() { + console.log('hello world'); +} + +const wrapped = performance.timerify(someFunction); + +const obs = new PerformanceObserver((list) => { + console.log(list.getEntries()[0].duration); + obs.disconnect(); +}); +obs.observe({ entryTypes: ['function'] }); + +// A performance timeline entry will be created +wrapped(); +``` + diff --git a/perf_hooks/performance_timing_api.md b/perf_hooks/performance_timing_api.md new file mode 100644 index 00000000..f4639868 --- /dev/null +++ b/perf_hooks/performance_timing_api.md @@ -0,0 +1,26 @@ + + + +> Stability: 1 - Experimental + +The Performance Timing API provides an implementation of the +[W3C Performance Timeline][] specification. The purpose of the API +is to support collection of high resolution performance metrics. +This is the same Performance API as implemented in modern Web browsers. + +```js +const { PerformanceObserver, performance } = require('perf_hooks'); + +const obs = new PerformanceObserver((items) => { + console.log(items.getEntries()[0].duration); + performance.clearMarks(); +}); +obs.observe({ entryTypes: ['measure'] }); + +performance.mark('A'); +doSomeLongRunningProcess(() => { + performance.mark('B'); + performance.measure('A to B', 'A', 'B'); +}); +``` + diff --git a/perf_hooks/performanceentry_duration.md b/perf_hooks/performanceentry_duration.md new file mode 100644 index 00000000..fb9ee1ff --- /dev/null +++ b/perf_hooks/performanceentry_duration.md @@ -0,0 +1,9 @@ + + +* {number} + +The total number of milliseconds elapsed for this entry. This value will not +be meaningful for all Performance Entry types. + diff --git a/perf_hooks/performanceentry_entrytype.md b/perf_hooks/performanceentry_entrytype.md new file mode 100644 index 00000000..e944847e --- /dev/null +++ b/perf_hooks/performanceentry_entrytype.md @@ -0,0 +1,9 @@ + + +* {string} + +The type of the performance entry. Currently it may be one of: `'node'`, +`'mark'`, `'measure'`, `'gc'`, `'function'`, `'http2'` or `'http'`. + diff --git a/perf_hooks/performanceentry_kind.md b/perf_hooks/performanceentry_kind.md new file mode 100644 index 00000000..c76b8679 --- /dev/null +++ b/perf_hooks/performanceentry_kind.md @@ -0,0 +1,15 @@ + + +* {number} + +When `performanceEntry.entryType` is equal to `'gc'`, the `performance.kind` +property identifies the type of garbage collection operation that occurred. +The value may be one of: + +* `perf_hooks.constants.NODE_PERFORMANCE_GC_MAJOR` +* `perf_hooks.constants.NODE_PERFORMANCE_GC_MINOR` +* `perf_hooks.constants.NODE_PERFORMANCE_GC_INCREMENTAL` +* `perf_hooks.constants.NODE_PERFORMANCE_GC_WEAKCB` + diff --git a/perf_hooks/performanceentry_name.md b/perf_hooks/performanceentry_name.md new file mode 100644 index 00000000..c2f32fb6 --- /dev/null +++ b/perf_hooks/performanceentry_name.md @@ -0,0 +1,8 @@ + + +* {string} + +The name of the performance entry. + diff --git a/perf_hooks/performanceentry_starttime.md b/perf_hooks/performanceentry_starttime.md new file mode 100644 index 00000000..7df9fabd --- /dev/null +++ b/perf_hooks/performanceentry_starttime.md @@ -0,0 +1,9 @@ + + +* {number} + +The high resolution millisecond timestamp marking the starting time of the +Performance Entry. + diff --git a/perf_hooks/performancenodetiming_bootstrapcomplete.md b/perf_hooks/performancenodetiming_bootstrapcomplete.md new file mode 100644 index 00000000..43cf6814 --- /dev/null +++ b/perf_hooks/performancenodetiming_bootstrapcomplete.md @@ -0,0 +1,10 @@ + + +* {number} + +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. + diff --git a/perf_hooks/performancenodetiming_environment.md b/perf_hooks/performancenodetiming_environment.md new file mode 100644 index 00000000..fce00ed0 --- /dev/null +++ b/perf_hooks/performancenodetiming_environment.md @@ -0,0 +1,9 @@ + + +* {number} + +The high resolution millisecond timestamp at which the Node.js environment was +initialized. + diff --git a/perf_hooks/performancenodetiming_loopexit.md b/perf_hooks/performancenodetiming_loopexit.md new file mode 100644 index 00000000..e11638e6 --- /dev/null +++ b/perf_hooks/performancenodetiming_loopexit.md @@ -0,0 +1,10 @@ + + +* {number} + +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. + diff --git a/perf_hooks/performancenodetiming_loopstart.md b/perf_hooks/performancenodetiming_loopstart.md new file mode 100644 index 00000000..3da2ab27 --- /dev/null +++ b/perf_hooks/performancenodetiming_loopstart.md @@ -0,0 +1,10 @@ + + +* {number} + +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. + diff --git a/perf_hooks/performancenodetiming_nodestart.md b/perf_hooks/performancenodetiming_nodestart.md new file mode 100644 index 00000000..a0ce294e --- /dev/null +++ b/perf_hooks/performancenodetiming_nodestart.md @@ -0,0 +1,9 @@ + + +* {number} + +The high resolution millisecond timestamp at which the Node.js process was +initialized. + diff --git a/perf_hooks/performancenodetiming_v8start.md b/perf_hooks/performancenodetiming_v8start.md new file mode 100644 index 00000000..01c8b4ee --- /dev/null +++ b/perf_hooks/performancenodetiming_v8start.md @@ -0,0 +1,9 @@ + + +* {number} + +The high resolution millisecond timestamp at which the V8 platform was +initialized. + diff --git a/perf_hooks/performanceobserver_disconnect.md b/perf_hooks/performanceobserver_disconnect.md new file mode 100644 index 00000000..a51aa2f2 --- /dev/null +++ b/perf_hooks/performanceobserver_disconnect.md @@ -0,0 +1,5 @@ + +Disconnects the `PerformanceObserver` instance from all notifications. + diff --git a/perf_hooks/performanceobserver_observe_options.md b/perf_hooks/performanceobserver_observe_options.md new file mode 100644 index 00000000..d72a9c16 --- /dev/null +++ b/perf_hooks/performanceobserver_observe_options.md @@ -0,0 +1,48 @@ + +* `options` {Object} + * `entryTypes` {string[]} An array of strings identifying the types of + `PerformanceEntry` instances the observer is interested in. If not + provided an error will be thrown. + * `buffered` {boolean} If true, the notification callback will be + called using `setImmediate()` and multiple `PerformanceEntry` instance + notifications will be buffered internally. If `false`, notifications will + be immediate and synchronous. **Default:** `false`. + +Subscribes the `PerformanceObserver` instance to notifications of new +`PerformanceEntry` instances identified by `options.entryTypes`. + +When `options.buffered` is `false`, the `callback` will be invoked once for +every `PerformanceEntry` instance: + +```js +const { + performance, + PerformanceObserver +} = require('perf_hooks'); + +const obs = new PerformanceObserver((list, observer) => { + // Called three times synchronously. `list` contains one item. +}); +obs.observe({ entryTypes: ['mark'] }); + +for (let n = 0; n < 3; n++) + performance.mark(`test${n}`); +``` + +```js +const { + performance, + PerformanceObserver +} = require('perf_hooks'); + +const obs = new PerformanceObserver((list, observer) => { + // Called once. `list` contains three items. +}); +obs.observe({ entryTypes: ['mark'], buffered: true }); + +for (let n = 0; n < 3; n++) + performance.mark(`test${n}`); +``` + diff --git a/perf_hooks/performanceobserverentrylist_getentries.md b/perf_hooks/performanceobserverentrylist_getentries.md new file mode 100644 index 00000000..83fd6463 --- /dev/null +++ b/perf_hooks/performanceobserverentrylist_getentries.md @@ -0,0 +1,9 @@ + + +* Returns: {PerformanceEntry[]} + +Returns a list of `PerformanceEntry` objects in chronological order +with respect to `performanceEntry.startTime`. + diff --git a/perf_hooks/performanceobserverentrylist_getentriesbyname_name_type.md b/perf_hooks/performanceobserverentrylist_getentriesbyname_name_type.md new file mode 100644 index 00000000..1bf516ad --- /dev/null +++ b/perf_hooks/performanceobserverentrylist_getentriesbyname_name_type.md @@ -0,0 +1,13 @@ + + +* `name` {string} +* `type` {string} +* Returns: {PerformanceEntry[]} + +Returns a list of `PerformanceEntry` objects in chronological order +with respect to `performanceEntry.startTime` whose `performanceEntry.name` is +equal to `name`, and optionally, whose `performanceEntry.entryType` is equal to +`type`. + diff --git a/perf_hooks/performanceobserverentrylist_getentriesbytype_type.md b/perf_hooks/performanceobserverentrylist_getentriesbytype_type.md new file mode 100644 index 00000000..55e9a270 --- /dev/null +++ b/perf_hooks/performanceobserverentrylist_getentriesbytype_type.md @@ -0,0 +1,11 @@ + + +* `type` {string} +* Returns: {PerformanceEntry[]} + +Returns a list of `PerformanceEntry` objects in chronological order +with respect to `performanceEntry.startTime` whose `performanceEntry.entryType` +is equal to `type`. + diff --git a/api-docs/28bea02395c1d549daf62e4aa012aecaf21f95142fb876802d863fb06abeb694.md b/process/a_note_on_process_i_o.md similarity index 100% rename from api-docs/28bea02395c1d549daf62e4aa012aecaf21f95142fb876802d863fb06abeb694.md rename to process/a_note_on_process_i_o.md diff --git a/api-docs/47f6f91b54ebcc40d78b4cad843a60a2972a2a52af9771d8952eceb3ffcf3846.md b/process/avoiding_duplicate_warnings.md similarity index 100% rename from api-docs/47f6f91b54ebcc40d78b4cad843a60a2972a2a52af9771d8952eceb3ffcf3846.md rename to process/avoiding_duplicate_warnings.md diff --git a/api-docs/54773306acd25d1fed77e2f71fc4b0078a08289020e0b13e2723639938c95624.md b/process/emitting_custom_warnings.md similarity index 100% rename from api-docs/54773306acd25d1fed77e2f71fc4b0078a08289020e0b13e2723639938c95624.md rename to process/emitting_custom_warnings.md diff --git a/api-docs/674c49b411ef75ff5bec512180e56d2b0debff05d7c2a104789b56d34edc032d.md b/process/event_beforeexit.md similarity index 100% rename from api-docs/674c49b411ef75ff5bec512180e56d2b0debff05d7c2a104789b56d34edc032d.md rename to process/event_beforeexit.md diff --git a/api-docs/761ecd9dea1f810a2e1b3248526de2765e3d669dd84ea300bece4431616e108d.md b/process/event_disconnect.md similarity index 100% rename from api-docs/761ecd9dea1f810a2e1b3248526de2765e3d669dd84ea300bece4431616e108d.md rename to process/event_disconnect.md diff --git a/api-docs/07042aa4217de4e68dd13c33058d7dc538eb536bc5d81f7d5f2712ea24b7e591.md b/process/event_exit.md similarity index 100% rename from api-docs/07042aa4217de4e68dd13c33058d7dc538eb536bc5d81f7d5f2712ea24b7e591.md rename to process/event_exit.md diff --git a/api-docs/f853afa54d1fb76a6f0c3f5e24ef850a2dd69cfb76554d329a1a71f83106d626.md b/process/event_message.md similarity index 100% rename from api-docs/f853afa54d1fb76a6f0c3f5e24ef850a2dd69cfb76554d329a1a71f83106d626.md rename to process/event_message.md diff --git a/api-docs/b91270cf223502b04a53a25abd8e76425f6b4e4b8159c25c7ef06ea398cb2785.md b/process/event_multipleresolves.md similarity index 100% rename from api-docs/b91270cf223502b04a53a25abd8e76425f6b4e4b8159c25c7ef06ea398cb2785.md rename to process/event_multipleresolves.md diff --git a/api-docs/1d74d54bde4cbc66c1ad0c8ea8e03e44341dd68b84f018346648f56e491bc9f9.md b/process/event_rejectionhandled.md similarity index 100% rename from api-docs/1d74d54bde4cbc66c1ad0c8ea8e03e44341dd68b84f018346648f56e491bc9f9.md rename to process/event_rejectionhandled.md diff --git a/api-docs/1661f77d12ca37e3ad0765f4ab18c39e7cc5e9f1fef4093600a93d0f339f7158.md b/process/event_uncaughtexception.md similarity index 100% rename from api-docs/1661f77d12ca37e3ad0765f4ab18c39e7cc5e9f1fef4093600a93d0f339f7158.md rename to process/event_uncaughtexception.md diff --git a/api-docs/0dafad7c01e059a8306145355ae677ff7eaafc3c21f6f9e1fd61c86e1c8ed6b0.md b/process/event_unhandledrejection.md similarity index 100% rename from api-docs/0dafad7c01e059a8306145355ae677ff7eaafc3c21f6f9e1fd61c86e1c8ed6b0.md rename to process/event_unhandledrejection.md diff --git a/api-docs/ec6410dfa760326064bbd02d18170be748fd1af8153b226fca6b58ab79c73d09.md b/process/event_warning.md similarity index 100% rename from api-docs/ec6410dfa760326064bbd02d18170be748fd1af8153b226fca6b58ab79c73d09.md rename to process/event_warning.md diff --git a/api-docs/e4e42c574b9f918a3cf7841bf106da265138233c97626d3b4411dfb372061ad1.md b/process/exit_codes.md similarity index 100% rename from api-docs/e4e42c574b9f918a3cf7841bf106da265138233c97626d3b4411dfb372061ad1.md rename to process/exit_codes.md diff --git a/api-docs/9fa3873789fabd2d6208cb99e042b11b110433f8ffb378f0d5992eb2fcbe0925.md b/process/process.md similarity index 100% rename from api-docs/9fa3873789fabd2d6208cb99e042b11b110433f8ffb378f0d5992eb2fcbe0925.md rename to process/process.md diff --git a/api-docs/24e295361407faedfcd50b3dff41f3af336bbdec698e98fcb764655918b83185.md b/process/process_abort.md similarity index 100% rename from api-docs/24e295361407faedfcd50b3dff41f3af336bbdec698e98fcb764655918b83185.md rename to process/process_abort.md diff --git a/api-docs/676af81f3d4c08a58f804867a7605790e8661d7aa47f3434126615fdec13c577.md b/process/process_allowednodeenvironmentflags.md similarity index 100% rename from api-docs/676af81f3d4c08a58f804867a7605790e8661d7aa47f3434126615fdec13c577.md rename to process/process_allowednodeenvironmentflags.md diff --git a/api-docs/4c635b3dd2fc8109b7fb4040f002a2c52420381ad4d933a1ffb9742ef6aba8d9.md b/process/process_arch.md similarity index 100% rename from api-docs/4c635b3dd2fc8109b7fb4040f002a2c52420381ad4d933a1ffb9742ef6aba8d9.md rename to process/process_arch.md diff --git a/api-docs/5371fe1e5b25a7f1f9a8617181c75a0d5b5bef78f9e0def62b79dc6d5ce61f28.md b/process/process_argv.md similarity index 100% rename from api-docs/5371fe1e5b25a7f1f9a8617181c75a0d5b5bef78f9e0def62b79dc6d5ce61f28.md rename to process/process_argv.md diff --git a/api-docs/c817ec0b6ba605b556d6546fff9424be6e2c5c8338fbff53d4e9902d1d36f3cc.md b/process/process_argv0.md similarity index 100% rename from api-docs/c817ec0b6ba605b556d6546fff9424be6e2c5c8338fbff53d4e9902d1d36f3cc.md rename to process/process_argv0.md diff --git a/api-docs/7aeaabdac1d4cd2b4745f986ad5c21573187bfcedf4c1907810df96a73aef952.md b/process/process_channel.md similarity index 100% rename from api-docs/7aeaabdac1d4cd2b4745f986ad5c21573187bfcedf4c1907810df96a73aef952.md rename to process/process_channel.md diff --git a/api-docs/c742c3d5d27b3395e8228cdead34be36054bbfe095b2b55bc8ac7e75b9a551a3.md b/process/process_chdir_directory.md similarity index 100% rename from api-docs/c742c3d5d27b3395e8228cdead34be36054bbfe095b2b55bc8ac7e75b9a551a3.md rename to process/process_chdir_directory.md diff --git a/api-docs/2da908f11b230f6b1bec77a34ba7c79bcd6e6d288f6235315c523908fe5aeb37.md b/process/process_config.md similarity index 100% rename from api-docs/2da908f11b230f6b1bec77a34ba7c79bcd6e6d288f6235315c523908fe5aeb37.md rename to process/process_config.md diff --git a/api-docs/21ec675c79e949864b3623206792056ded496a059cbdb7f8d70cebaa10768fe3.md b/process/process_connected.md similarity index 100% rename from api-docs/21ec675c79e949864b3623206792056ded496a059cbdb7f8d70cebaa10768fe3.md rename to process/process_connected.md diff --git a/api-docs/72873d2fe638c6df8283727d3d218b295bf6b4c11c89ef5149db1180dec05474.md b/process/process_cpuusage_previousvalue.md similarity index 100% rename from api-docs/72873d2fe638c6df8283727d3d218b295bf6b4c11c89ef5149db1180dec05474.md rename to process/process_cpuusage_previousvalue.md diff --git a/api-docs/3532c04941d8e817770a12dde5177d1e866328284f48967e7c9d61780611167f.md b/process/process_cwd.md similarity index 100% rename from api-docs/3532c04941d8e817770a12dde5177d1e866328284f48967e7c9d61780611167f.md rename to process/process_cwd.md diff --git a/api-docs/7f1486463b20008b2d34141826000587d3dafd97308c9fadf0e49d9c8c110f38.md b/process/process_debugport.md similarity index 100% rename from api-docs/7f1486463b20008b2d34141826000587d3dafd97308c9fadf0e49d9c8c110f38.md rename to process/process_debugport.md diff --git a/api-docs/8ccd1da2949858cc1d2e5edd8a642039ee71af3a7d2aea5a8ce20ac410f34ef9.md b/process/process_disconnect.md similarity index 100% rename from api-docs/8ccd1da2949858cc1d2e5edd8a642039ee71af3a7d2aea5a8ce20ac410f34ef9.md rename to process/process_disconnect.md diff --git a/api-docs/6ca5ac22c194f4b1dd0524ef6a7bfc644b6289eb504a21bfcc7de378b666ae54.md b/process/process_dlopen_module_filename_flags.md similarity index 100% rename from api-docs/6ca5ac22c194f4b1dd0524ef6a7bfc644b6289eb504a21bfcc7de378b666ae54.md rename to process/process_dlopen_module_filename_flags.md diff --git a/api-docs/432b41174fe90c991fb0a557d9dc8be399da93144a87613a4ccf29fa88adb9db.md b/process/process_emitwarning_warning_options.md similarity index 100% rename from api-docs/432b41174fe90c991fb0a557d9dc8be399da93144a87613a4ccf29fa88adb9db.md rename to process/process_emitwarning_warning_options.md diff --git a/api-docs/74c08dca325d75831696464410f6fced1476c01a546b98e19d815439be926420.md b/process/process_emitwarning_warning_type_code_ctor.md similarity index 100% rename from api-docs/74c08dca325d75831696464410f6fced1476c01a546b98e19d815439be926420.md rename to process/process_emitwarning_warning_type_code_ctor.md diff --git a/api-docs/adf09e20cd53cc77490e5d3ed59d31d48159001f5b3200f638d67ccdea91b172.md b/process/process_env.md similarity index 100% rename from api-docs/adf09e20cd53cc77490e5d3ed59d31d48159001f5b3200f638d67ccdea91b172.md rename to process/process_env.md diff --git a/api-docs/98f6480e9331cb8fdc23ca39c8ef1455397cf7a2481961e94f485e8d38e6c49d.md b/process/process_events.md similarity index 100% rename from api-docs/98f6480e9331cb8fdc23ca39c8ef1455397cf7a2481961e94f485e8d38e6c49d.md rename to process/process_events.md diff --git a/api-docs/c869dedd28e28895bcf6ebfcdfa75977d73fb5187970c18f5ba25490dda330ea.md b/process/process_execargv.md similarity index 100% rename from api-docs/c869dedd28e28895bcf6ebfcdfa75977d73fb5187970c18f5ba25490dda330ea.md rename to process/process_execargv.md diff --git a/api-docs/63f5092b7567f05abdf02e814f76587c79bf5b8b5253978e2d0fd395631020bb.md b/process/process_execpath.md similarity index 100% rename from api-docs/63f5092b7567f05abdf02e814f76587c79bf5b8b5253978e2d0fd395631020bb.md rename to process/process_execpath.md diff --git a/api-docs/dba9e952213e46cb4ba25843de72799637ff5919028661f17406faffd7ccd197.md b/process/process_exit_code.md similarity index 100% rename from api-docs/dba9e952213e46cb4ba25843de72799637ff5919028661f17406faffd7ccd197.md rename to process/process_exit_code.md diff --git a/api-docs/395e32357fb316b3e2d8dccb2cabb1c3adf0042288d8dc03727485b5122a703f.md b/process/process_exitcode.md similarity index 100% rename from api-docs/395e32357fb316b3e2d8dccb2cabb1c3adf0042288d8dc03727485b5122a703f.md rename to process/process_exitcode.md diff --git a/api-docs/8cd6a9d196c316fc669b0cbdcab568b4d9676f74e98421b35fc4dbf20d09c3f3.md b/process/process_getegid.md similarity index 100% rename from api-docs/8cd6a9d196c316fc669b0cbdcab568b4d9676f74e98421b35fc4dbf20d09c3f3.md rename to process/process_getegid.md diff --git a/api-docs/66d9140de717b18418b5228d87c9714fe2b6fde65b61a3c8394de528af9b52da.md b/process/process_geteuid.md similarity index 100% rename from api-docs/66d9140de717b18418b5228d87c9714fe2b6fde65b61a3c8394de528af9b52da.md rename to process/process_geteuid.md diff --git a/api-docs/0ce9d983e7d493c4aa250cc8da19e00efc1cd0eb917ff3f148f98e2b53cdee31.md b/process/process_getgid.md similarity index 100% rename from api-docs/0ce9d983e7d493c4aa250cc8da19e00efc1cd0eb917ff3f148f98e2b53cdee31.md rename to process/process_getgid.md diff --git a/api-docs/4d19201b271263092515688407a7cb1cb5d8977d6495ff4720bb9f475e42df3f.md b/process/process_getgroups.md similarity index 100% rename from api-docs/4d19201b271263092515688407a7cb1cb5d8977d6495ff4720bb9f475e42df3f.md rename to process/process_getgroups.md diff --git a/api-docs/a31bb4797db30070ce58f9a091d0e76105c4588bcc53b2008038f0021a7e1135.md b/process/process_getuid.md similarity index 100% rename from api-docs/a31bb4797db30070ce58f9a091d0e76105c4588bcc53b2008038f0021a7e1135.md rename to process/process_getuid.md diff --git a/api-docs/5a0670737f1a16fbbb97363d5d07d6f93db6be603fc0754008432ca6c5ffbe16.md b/process/process_hasuncaughtexceptioncapturecallback.md similarity index 100% rename from api-docs/5a0670737f1a16fbbb97363d5d07d6f93db6be603fc0754008432ca6c5ffbe16.md rename to process/process_hasuncaughtexceptioncapturecallback.md diff --git a/api-docs/4e261bd284bf0e76930383500990757fabb0c623b1fd58dcdd776763709714c5.md b/process/process_hrtime_bigint.md similarity index 100% rename from api-docs/4e261bd284bf0e76930383500990757fabb0c623b1fd58dcdd776763709714c5.md rename to process/process_hrtime_bigint.md diff --git a/api-docs/87fafea5fb8b99769b68ff2ee7d6506d033a0a29af66bec29b10f9498a9037f6.md b/process/process_hrtime_time.md similarity index 100% rename from api-docs/87fafea5fb8b99769b68ff2ee7d6506d033a0a29af66bec29b10f9498a9037f6.md rename to process/process_hrtime_time.md diff --git a/api-docs/43852d7124c08c0b5012a2c96bcf7fccdaeb6d45e8314c12d95353a502699fce.md b/process/process_initgroups_user_extragroup.md similarity index 100% rename from api-docs/43852d7124c08c0b5012a2c96bcf7fccdaeb6d45e8314c12d95353a502699fce.md rename to process/process_initgroups_user_extragroup.md diff --git a/api-docs/c89d93f4e44b93918930d4e11509906a7efa6721a4562350ed85f34d7848d9fe.md b/process/process_kill_pid_signal.md similarity index 100% rename from api-docs/c89d93f4e44b93918930d4e11509906a7efa6721a4562350ed85f34d7848d9fe.md rename to process/process_kill_pid_signal.md diff --git a/api-docs/53ff81cd8c42504a1580f53b8e62769ab7ddf26c92990caa9475fc0f95e79dc5.md b/process/process_mainmodule.md similarity index 100% rename from api-docs/53ff81cd8c42504a1580f53b8e62769ab7ddf26c92990caa9475fc0f95e79dc5.md rename to process/process_mainmodule.md diff --git a/api-docs/af34cf02f4a20b3df7ed0aa10b7e946f500b8d3f7630a3b37f5362f7f63e9e59.md b/process/process_memoryusage.md similarity index 100% rename from api-docs/af34cf02f4a20b3df7ed0aa10b7e946f500b8d3f7630a3b37f5362f7f63e9e59.md rename to process/process_memoryusage.md diff --git a/api-docs/6ac5b5faf61fa8242960eb22dfd0d4d53037eaddbc36b9dc997624cfddfa8d49.md b/process/process_nexttick_callback_args.md similarity index 100% rename from api-docs/6ac5b5faf61fa8242960eb22dfd0d4d53037eaddbc36b9dc997624cfddfa8d49.md rename to process/process_nexttick_callback_args.md diff --git a/api-docs/bc61502b3f85b7be5d5c0906e50c4d215b187295e061c2f94bed694d89438586.md b/process/process_nodeprecation.md similarity index 100% rename from api-docs/bc61502b3f85b7be5d5c0906e50c4d215b187295e061c2f94bed694d89438586.md rename to process/process_nodeprecation.md diff --git a/api-docs/4247837660aaf5fb5d59e7cce00b58cd864a9d1a19f063bd45275681288327fe.md b/process/process_pid.md similarity index 100% rename from api-docs/4247837660aaf5fb5d59e7cce00b58cd864a9d1a19f063bd45275681288327fe.md rename to process/process_pid.md diff --git a/api-docs/5f89dcdd1e6c3a09f590eaa5f829338cc57e5a486646a456fa9f8d6632febc97.md b/process/process_platform.md similarity index 100% rename from api-docs/5f89dcdd1e6c3a09f590eaa5f829338cc57e5a486646a456fa9f8d6632febc97.md rename to process/process_platform.md diff --git a/api-docs/7fab3e80a47bc91c22e808fc122275a0c0b6fa661cb05fdd957b224c5dd1a27a.md b/process/process_ppid.md similarity index 100% rename from api-docs/7fab3e80a47bc91c22e808fc122275a0c0b6fa661cb05fdd957b224c5dd1a27a.md rename to process/process_ppid.md diff --git a/api-docs/2b92da029f4d67bb6d2e6ee3397f4cd88861bc4b73c48d8265ab57065cce251d.md b/process/process_release.md similarity index 100% rename from api-docs/2b92da029f4d67bb6d2e6ee3397f4cd88861bc4b73c48d8265ab57065cce251d.md rename to process/process_release.md diff --git a/api-docs/011d3c24edd99704336ba0cff5ab84486ace76c838fd69e8b1eb738dc053a502.md b/process/process_send_message_sendhandle_options_callback.md similarity index 100% rename from api-docs/011d3c24edd99704336ba0cff5ab84486ace76c838fd69e8b1eb738dc053a502.md rename to process/process_send_message_sendhandle_options_callback.md diff --git a/api-docs/7675a5e4fc854b990873d53ba480b05b9a8953e5c23406d9b49d01c05c297f1b.md b/process/process_setegid_id.md similarity index 100% rename from api-docs/7675a5e4fc854b990873d53ba480b05b9a8953e5c23406d9b49d01c05c297f1b.md rename to process/process_setegid_id.md diff --git a/api-docs/3b8d61cf437701ae4c569377ee775caf61e27424398811c478bb8fe9e713dd23.md b/process/process_seteuid_id.md similarity index 100% rename from api-docs/3b8d61cf437701ae4c569377ee775caf61e27424398811c478bb8fe9e713dd23.md rename to process/process_seteuid_id.md diff --git a/api-docs/15a35e12445d6a79187a7436ba4e4fdaf11c11224a8ed8787ca8649ac969e3de.md b/process/process_setgid_id.md similarity index 100% rename from api-docs/15a35e12445d6a79187a7436ba4e4fdaf11c11224a8ed8787ca8649ac969e3de.md rename to process/process_setgid_id.md diff --git a/api-docs/7944ef77a1630cbc413fa9429ffee7d89393e8dfe446dd4312cbb378ab2beb68.md b/process/process_setgroups_groups.md similarity index 100% rename from api-docs/7944ef77a1630cbc413fa9429ffee7d89393e8dfe446dd4312cbb378ab2beb68.md rename to process/process_setgroups_groups.md diff --git a/api-docs/9aaae1e4e115a6a7e6ad70ff6a242cf37129cb209d91e168b1f25a70698dfc1e.md b/process/process_setuid_id.md similarity index 100% rename from api-docs/9aaae1e4e115a6a7e6ad70ff6a242cf37129cb209d91e168b1f25a70698dfc1e.md rename to process/process_setuid_id.md diff --git a/api-docs/a685b5c60183261c5404933139c1f7c5545b9cc5cf0de9c6f2b908034d23a138.md b/process/process_setuncaughtexceptioncapturecallback_fn.md similarity index 100% rename from api-docs/a685b5c60183261c5404933139c1f7c5545b9cc5cf0de9c6f2b908034d23a138.md rename to process/process_setuncaughtexceptioncapturecallback_fn.md diff --git a/api-docs/ad590e9c16919b2f400a8cb8b3b70ebcae7da66edcc438819247139631c33ee7.md b/process/process_stderr.md similarity index 100% rename from api-docs/ad590e9c16919b2f400a8cb8b3b70ebcae7da66edcc438819247139631c33ee7.md rename to process/process_stderr.md diff --git a/api-docs/eaebeb520e8c0db9d81007e3a5f330301f74ca6e079d5c111509f9c12399dc5b.md b/process/process_stdin.md similarity index 100% rename from api-docs/eaebeb520e8c0db9d81007e3a5f330301f74ca6e079d5c111509f9c12399dc5b.md rename to process/process_stdin.md diff --git a/api-docs/f99b7b116e71b1a4aa7908d6741787db42dde8947592b0ef0526cd75f395120f.md b/process/process_stdout.md similarity index 100% rename from api-docs/f99b7b116e71b1a4aa7908d6741787db42dde8947592b0ef0526cd75f395120f.md rename to process/process_stdout.md diff --git a/api-docs/24cb21256d8fe967c0a8d321ca8a142e3cbaba7ed3847d579e6d0952e54d9e56.md b/process/process_throwdeprecation.md similarity index 100% rename from api-docs/24cb21256d8fe967c0a8d321ca8a142e3cbaba7ed3847d579e6d0952e54d9e56.md rename to process/process_throwdeprecation.md diff --git a/api-docs/15f6fd28de6aa59fa85be7ae8a03d7c55102e4373314c56a61921d857902dea1.md b/process/process_title.md similarity index 100% rename from api-docs/15f6fd28de6aa59fa85be7ae8a03d7c55102e4373314c56a61921d857902dea1.md rename to process/process_title.md diff --git a/api-docs/9736ea2f36e088caedaf89a0a9b9073b38b7581888484b7e2c1c6f6339963b61.md b/process/process_tracedeprecation.md similarity index 100% rename from api-docs/9736ea2f36e088caedaf89a0a9b9073b38b7581888484b7e2c1c6f6339963b61.md rename to process/process_tracedeprecation.md diff --git a/api-docs/f9ad655a9c1731fcce721d80597b96278fdcf680abb740e042e1b028aae9d1a9.md b/process/process_umask_mask.md similarity index 100% rename from api-docs/f9ad655a9c1731fcce721d80597b96278fdcf680abb740e042e1b028aae9d1a9.md rename to process/process_umask_mask.md diff --git a/api-docs/b0bf4a4664d29528ef45819ab70357a3033631d0ccfd9ffa8fda70cee6247470.md b/process/process_uptime.md similarity index 100% rename from api-docs/b0bf4a4664d29528ef45819ab70357a3033631d0ccfd9ffa8fda70cee6247470.md rename to process/process_uptime.md diff --git a/api-docs/b4fbe201fe7cb00461f5d4b84ee9495aa4fafcb4afe11b96508b03ea11f8872b.md b/process/process_version.md similarity index 100% rename from api-docs/b4fbe201fe7cb00461f5d4b84ee9495aa4fafcb4afe11b96508b03ea11f8872b.md rename to process/process_version.md diff --git a/api-docs/45b9d818f9dd913ababbd86fc1d0f96294a1cab417be14f235578ed0b5efed98.md b/process/process_versions.md similarity index 100% rename from api-docs/45b9d818f9dd913ababbd86fc1d0f96294a1cab417be14f235578ed0b5efed98.md rename to process/process_versions.md diff --git a/api-docs/80337e1e8a21c41b96c72ee97ff4a1eaa799c267f59ad78fa90784eae6236152.md b/process/signal_events.md similarity index 100% rename from api-docs/80337e1e8a21c41b96c72ee97ff4a1eaa799c267f59ad78fa90784eae6236152.md rename to process/signal_events.md diff --git a/api-docs/cfb2c33c0b6fb5b95d9eb089c9e24e23ab452bd6cb687620fc5b5f2ac470dbf9.md b/process/warning_using_uncaughtexception_correctly.md similarity index 100% rename from api-docs/cfb2c33c0b6fb5b95d9eb089c9e24e23ab452bd6cb687620fc5b5f2ac470dbf9.md rename to process/warning_using_uncaughtexception_correctly.md diff --git a/punycode/punycode.md b/punycode/punycode.md new file mode 100644 index 00000000..d02ea0f0 --- /dev/null +++ b/punycode/punycode.md @@ -0,0 +1,38 @@ + + + + +> Stability: 0 - Deprecated + +**The version of the punycode module bundled in Node.js is being deprecated**. +In a future major version of Node.js this module will be removed. Users +currently depending on the `punycode` module should switch to using the +userland-provided [Punycode.js][] module instead. + +The `punycode` module is a bundled version of the [Punycode.js][] module. It +can be accessed using: + +```js +const punycode = require('punycode'); +``` + +[Punycode][] is a character encoding scheme defined by RFC 3492 that is +primarily intended for use in Internationalized Domain Names. Because host +names in URLs are limited to ASCII characters only, Domain Names that contain +non-ASCII characters must be converted into ASCII using the Punycode scheme. +For instance, the Japanese character that translates into the English word, +`'example'` is `'例'`. The Internationalized Domain Name, `'例.com'` (equivalent +to `'example.com'`) is represented by Punycode as the ASCII string +`'xn--fsq.com'`. + +The `punycode` module provides a simple implementation of the Punycode standard. + +The `punycode` module is a third-party dependency used by Node.js and +made available to developers as a convenience. Fixes or other modifications to +the module must be directed to the [Punycode.js][] project. + diff --git a/punycode/punycode_decode_string.md b/punycode/punycode_decode_string.md new file mode 100644 index 00000000..ac98b0f1 --- /dev/null +++ b/punycode/punycode_decode_string.md @@ -0,0 +1,14 @@ + + +* `string` {string} + +The `punycode.decode()` method converts a [Punycode][] string of ASCII-only +characters to the equivalent string of Unicode codepoints. + +```js +punycode.decode('maana-pta'); // 'mañana' +punycode.decode('--dqo34k'); // '☃-⌘' +``` + diff --git a/punycode/punycode_encode_string.md b/punycode/punycode_encode_string.md new file mode 100644 index 00000000..8ea525f0 --- /dev/null +++ b/punycode/punycode_encode_string.md @@ -0,0 +1,14 @@ + + +* `string` {string} + +The `punycode.encode()` method converts a string of Unicode codepoints to a +[Punycode][] string of ASCII-only characters. + +```js +punycode.encode('mañana'); // 'maana-pta' +punycode.encode('☃-⌘'); // '--dqo34k' +``` + diff --git a/punycode/punycode_toascii_domain.md b/punycode/punycode_toascii_domain.md new file mode 100644 index 00000000..030e2d03 --- /dev/null +++ b/punycode/punycode_toascii_domain.md @@ -0,0 +1,18 @@ + + +* `domain` {string} + +The `punycode.toASCII()` method converts a Unicode string representing an +Internationalized Domain Name to [Punycode][]. Only the non-ASCII parts of the +domain name will be converted. Calling `punycode.toASCII()` on a string that +already only contains ASCII characters will have no effect. + +```js +// encode domain names +punycode.toASCII('mañana.com'); // 'xn--maana-pta.com' +punycode.toASCII('☃-⌘.com'); // 'xn----dqo34k.com' +punycode.toASCII('example.com'); // 'example.com' +``` + diff --git a/punycode/punycode_tounicode_domain.md b/punycode/punycode_tounicode_domain.md new file mode 100644 index 00000000..769c66d1 --- /dev/null +++ b/punycode/punycode_tounicode_domain.md @@ -0,0 +1,17 @@ + + +* `domain` {string} + +The `punycode.toUnicode()` method converts a string representing a domain name +containing [Punycode][] encoded characters into Unicode. Only the [Punycode][] +encoded parts of the domain name are be converted. + +```js +// decode domain names +punycode.toUnicode('xn--maana-pta.com'); // 'mañana.com' +punycode.toUnicode('xn----dqo34k.com'); // '☃-⌘.com' +punycode.toUnicode('example.com'); // 'example.com' +``` + diff --git a/punycode/punycode_ucs2.md b/punycode/punycode_ucs2.md new file mode 100644 index 00000000..d47a4549 --- /dev/null +++ b/punycode/punycode_ucs2.md @@ -0,0 +1,4 @@ + + diff --git a/punycode/punycode_ucs2_decode_string.md b/punycode/punycode_ucs2_decode_string.md new file mode 100644 index 00000000..b524bd6b --- /dev/null +++ b/punycode/punycode_ucs2_decode_string.md @@ -0,0 +1,15 @@ + + +* `string` {string} + +The `punycode.ucs2.decode()` method returns an array containing the numeric +codepoint values of each Unicode symbol in the string. + +```js +punycode.ucs2.decode('abc'); // [0x61, 0x62, 0x63] +// surrogate pair for U+1D306 tetragram for centre: +punycode.ucs2.decode('\uD834\uDF06'); // [0x1D306] +``` + diff --git a/punycode/punycode_ucs2_encode_codepoints.md b/punycode/punycode_ucs2_encode_codepoints.md new file mode 100644 index 00000000..89a33db4 --- /dev/null +++ b/punycode/punycode_ucs2_encode_codepoints.md @@ -0,0 +1,14 @@ + + +* `codePoints` {integer[]} + +The `punycode.ucs2.encode()` method returns a string based on an array of +numeric code point values. + +```js +punycode.ucs2.encode([0x61, 0x62, 0x63]); // 'abc' +punycode.ucs2.encode([0x1D306]); // '\uD834\uDF06' +``` + diff --git a/api-docs/30a5dfd54e7d520597b8a92686c80c3c31048ea5253462331867de3d59ce0782.md b/punycode/punycode_version.md similarity index 100% rename from api-docs/30a5dfd54e7d520597b8a92686c80c3c31048ea5253462331867de3d59ce0782.md rename to punycode/punycode_version.md diff --git a/api-docs/23bab50ab1a71ad09d2d18f576f02b367493257ec6fd836c9f05152b5d99f701.md b/querystring/query_string.md similarity index 100% rename from api-docs/23bab50ab1a71ad09d2d18f576f02b367493257ec6fd836c9f05152b5d99f701.md rename to querystring/query_string.md diff --git a/api-docs/09115765dbb86d2081df67a645cf60cb1f1d59ef775a4972215fa64bfbf38cc2.md b/querystring/querystring_decode.md similarity index 100% rename from api-docs/09115765dbb86d2081df67a645cf60cb1f1d59ef775a4972215fa64bfbf38cc2.md rename to querystring/querystring_decode.md diff --git a/api-docs/c41b67e1a7bffc48795bd7ef615289ef4c36af0e58c2e3a192adcc8479b368f3.md b/querystring/querystring_encode.md similarity index 100% rename from api-docs/c41b67e1a7bffc48795bd7ef615289ef4c36af0e58c2e3a192adcc8479b368f3.md rename to querystring/querystring_encode.md diff --git a/api-docs/d02331af6f102a9cda9e3da3feb43a4a22e43096a73016553d8fe177485f1a82.md b/querystring/querystring_escape_str.md similarity index 100% rename from api-docs/d02331af6f102a9cda9e3da3feb43a4a22e43096a73016553d8fe177485f1a82.md rename to querystring/querystring_escape_str.md diff --git a/api-docs/b7c8b05576235a696b3474e74b23e5c43f1f457dae75ba74a7e5b2e97084edfe.md b/querystring/querystring_parse_str_sep_eq_options.md similarity index 100% rename from api-docs/b7c8b05576235a696b3474e74b23e5c43f1f457dae75ba74a7e5b2e97084edfe.md rename to querystring/querystring_parse_str_sep_eq_options.md diff --git a/api-docs/774dd6ea216eb228a8ae5d9e4e4e6a9cd72d033748eb5a6936d079133032e450.md b/querystring/querystring_stringify_obj_sep_eq_options.md similarity index 100% rename from api-docs/774dd6ea216eb228a8ae5d9e4e4e6a9cd72d033748eb5a6936d079133032e450.md rename to querystring/querystring_stringify_obj_sep_eq_options.md diff --git a/api-docs/c64e3e3edbb75965ef21e2254964c14125691035bb45dc26bc7f26cea5a08df9.md b/querystring/querystring_unescape_str.md similarity index 100% rename from api-docs/c64e3e3edbb75965ef21e2254964c14125691035bb45dc26bc7f26cea5a08df9.md rename to querystring/querystring_unescape_str.md diff --git a/api-docs/101d7ed98c3e300a8f27760249a5dc48f460d1099dbf466f2c228c059873fef7.md b/readline/class_interface.md similarity index 100% rename from api-docs/101d7ed98c3e300a8f27760249a5dc48f460d1099dbf466f2c228c059873fef7.md rename to readline/class_interface.md diff --git a/api-docs/39922cf2955aea20c1fc2d0e58302071c3f3d8d5fadfecc592769c6cd1ff40aa.md b/readline/event_close.md similarity index 100% rename from api-docs/39922cf2955aea20c1fc2d0e58302071c3f3d8d5fadfecc592769c6cd1ff40aa.md rename to readline/event_close.md diff --git a/api-docs/a8832f0aba102f9df5f360eff232f388f0f200ea47bc8d6ceee2c031e958a2fa.md b/readline/event_line.md similarity index 100% rename from api-docs/a8832f0aba102f9df5f360eff232f388f0f200ea47bc8d6ceee2c031e958a2fa.md rename to readline/event_line.md diff --git a/api-docs/26fd2825724708b317ccab00bcaac04821624c910ff7448be195f1221975000a.md b/readline/event_pause.md similarity index 100% rename from api-docs/26fd2825724708b317ccab00bcaac04821624c910ff7448be195f1221975000a.md rename to readline/event_pause.md diff --git a/api-docs/be267aa07fc24d703dea00ab829d234348b7ba2fffd64409d9964a789d42ce57.md b/readline/event_resume.md similarity index 100% rename from api-docs/be267aa07fc24d703dea00ab829d234348b7ba2fffd64409d9964a789d42ce57.md rename to readline/event_resume.md diff --git a/api-docs/d613e2f0fff10bbb3d89fc550c927040516236c7ffa6169e8dfa32325cd69c6b.md b/readline/event_sigcont.md similarity index 100% rename from api-docs/d613e2f0fff10bbb3d89fc550c927040516236c7ffa6169e8dfa32325cd69c6b.md rename to readline/event_sigcont.md diff --git a/api-docs/ac5abb1b22694ce3e679cefaad0ca00085a1742a4432da8e7fadfa7b20985b5e.md b/readline/event_sigint.md similarity index 100% rename from api-docs/ac5abb1b22694ce3e679cefaad0ca00085a1742a4432da8e7fadfa7b20985b5e.md rename to readline/event_sigint.md diff --git a/api-docs/67c8c24b82a8d9dd754f11a61f8c2784dc15c0a9c80a4fa6131ccaac68987ef0.md b/readline/event_sigtstp.md similarity index 100% rename from api-docs/67c8c24b82a8d9dd754f11a61f8c2784dc15c0a9c80a4fa6131ccaac68987ef0.md rename to readline/event_sigtstp.md diff --git a/api-docs/65ee1bfdc50c4e7ff3c3b60c6b02fc0887ebccedd5862de7d300b8ba39b9aaff.md b/readline/example_read_file_stream_line_by_line.md similarity index 100% rename from api-docs/65ee1bfdc50c4e7ff3c3b60c6b02fc0887ebccedd5862de7d300b8ba39b9aaff.md rename to readline/example_read_file_stream_line_by_line.md diff --git a/api-docs/2a3cccee40b46a9d15ccceb10938bee74a9263b79c314c5e81e68bf1261a1e49.md b/readline/example_tiny_cli.md similarity index 100% rename from api-docs/2a3cccee40b46a9d15ccceb10938bee74a9263b79c314c5e81e68bf1261a1e49.md rename to readline/example_tiny_cli.md diff --git a/api-docs/aa209bb28d671cbc5cf482a6042f5495e6149743f8cb82f3dcfa5aa636782e6b.md b/readline/readline.md similarity index 100% rename from api-docs/aa209bb28d671cbc5cf482a6042f5495e6149743f8cb82f3dcfa5aa636782e6b.md rename to readline/readline.md diff --git a/readline/readline_clearline_stream_dir_callback.md b/readline/readline_clearline_stream_dir_callback.md new file mode 100644 index 00000000..18351cb1 --- /dev/null +++ b/readline/readline_clearline_stream_dir_callback.md @@ -0,0 +1,18 @@ + + +* `stream` {stream.Writable} +* `dir` {number} + * `-1` - 从光标向左。 + * `1` - 从光标向右 + * `0` - 整行。 +* `callback` {Function} 操作完成后调用。 +* 返回: {boolean} 如果 `stream` 希望调用的代码在继续写入附加的数据之前等待 `'drain'` 事件触发，则为 `false`，否则为 `true`。 + +`readline.clearLine()` 方法在由 `dir` 标识的指定方向上清除给定的 [TTY] 流的当前行。 + diff --git a/readline/readline_clearscreendown_stream_callback.md b/readline/readline_clearscreendown_stream_callback.md new file mode 100644 index 00000000..56b854cc --- /dev/null +++ b/readline/readline_clearscreendown_stream_callback.md @@ -0,0 +1,14 @@ + + +* `stream` {stream.Writable} +* `callback` {Function} 操作完成后调用。 +* 返回: {boolean} 如果 `stream` 希望调用的代码在继续写入附加的数据之前等待 `'drain'` 事件触发，则为 `false`，否则为 `true`。 + +`readline.clearScreenDown()` 方法从光标的当前位置向下清除给定的 [TTY] 流。 + diff --git a/api-docs/7b97aa3880f3a720e2113cc95634975b8b0e936a79e75b9ab7b7d239f5c0d847.md b/readline/readline_createinterface_options.md similarity index 100% rename from api-docs/7b97aa3880f3a720e2113cc95634975b8b0e936a79e75b9ab7b7d239f5c0d847.md rename to readline/readline_createinterface_options.md diff --git a/readline/readline_cursorto_stream_x_y_callback.md b/readline/readline_cursorto_stream_x_y_callback.md new file mode 100644 index 00000000..80ec328e --- /dev/null +++ b/readline/readline_cursorto_stream_x_y_callback.md @@ -0,0 +1,16 @@ + + +* `stream` {stream.Writable} +* `x` {number} +* `y` {number} +* `callback` {Function} 操作完成后调用。 +* 返回: {boolean} 如果 `stream` 希望调用的代码在继续写入附加的数据之前等待 `'drain'` 事件触发，则为 `false`，否则为 `true`。 + +`readline.cursorTo()` 方法将光标移动到给定的 [TTY] `stream` 中的指定位置。 + diff --git a/api-docs/e1c234dab96513e66051c13eadd71ea93d99d5eade730d5cfb2648409052ad54.md b/readline/readline_emitkeypressevents_stream_interface.md similarity index 100% rename from api-docs/e1c234dab96513e66051c13eadd71ea93d99d5eade730d5cfb2648409052ad54.md rename to readline/readline_emitkeypressevents_stream_interface.md diff --git a/readline/readline_movecursor_stream_dx_dy_callback.md b/readline/readline_movecursor_stream_dx_dy_callback.md new file mode 100644 index 00000000..c8591687 --- /dev/null +++ b/readline/readline_movecursor_stream_dx_dy_callback.md @@ -0,0 +1,16 @@ + + +* `stream` {stream.Writable} +* `dx` {number} +* `dy` {number} +* `callback` {Function} 操作完成后调用。 +* 返回: {boolean} 如果 `stream` 希望调用的代码在继续写入附加的数据之前等待 `'drain'` 事件触发，则为 `false`，否则为 `true`。 + +`readline.moveCursor()` 方法相对于给定的 [TTY] `stream` 中的当前位置移动光标。 + diff --git a/api-docs/2d6c71a263c12645c7b2687ae632c1198f697a8511914fed36049b740e7cd00e.md b/readline/rl_close.md similarity index 100% rename from api-docs/2d6c71a263c12645c7b2687ae632c1198f697a8511914fed36049b740e7cd00e.md rename to readline/rl_close.md diff --git a/api-docs/aed713d64423e9ea4ab4e0873687dd4881c1de4a57200c60505b0044950240a9.md b/readline/rl_pause.md similarity index 100% rename from api-docs/aed713d64423e9ea4ab4e0873687dd4881c1de4a57200c60505b0044950240a9.md rename to readline/rl_pause.md diff --git a/api-docs/536e535cbe3c5cdc3c1336f35f819f7cc0a12d368ece389753e578b78a544546.md b/readline/rl_prompt_preservecursor.md similarity index 100% rename from api-docs/536e535cbe3c5cdc3c1336f35f819f7cc0a12d368ece389753e578b78a544546.md rename to readline/rl_prompt_preservecursor.md diff --git a/api-docs/8b777f74635465fb1bbae96732e2d56f981f72438aab8721e362fdf6071bc405.md b/readline/rl_question_query_callback.md similarity index 100% rename from api-docs/8b777f74635465fb1bbae96732e2d56f981f72438aab8721e362fdf6071bc405.md rename to readline/rl_question_query_callback.md diff --git a/api-docs/951eac5c627f4423f80910364c3baa4ea308af5de90eaacfec1dd58a182d4950.md b/readline/rl_resume.md similarity index 100% rename from api-docs/951eac5c627f4423f80910364c3baa4ea308af5de90eaacfec1dd58a182d4950.md rename to readline/rl_resume.md diff --git a/api-docs/29a41187dc43d495359a7ab98d5cacac61e4f7cbfa9099297118d8b2baf96ce5.md b/readline/rl_setprompt_prompt.md similarity index 100% rename from api-docs/29a41187dc43d495359a7ab98d5cacac61e4f7cbfa9099297118d8b2baf96ce5.md rename to readline/rl_setprompt_prompt.md diff --git a/api-docs/2774854b6d9e401c9184046b475a5a4b51028ad6b0abad22ab17b02b52700f06.md b/readline/rl_symbol_asynciterator.md similarity index 100% rename from api-docs/2774854b6d9e401c9184046b475a5a4b51028ad6b0abad22ab17b02b52700f06.md rename to readline/rl_symbol_asynciterator.md diff --git a/api-docs/29b2537ddc07ac549fadc61e51964243c78a857e5f7129c7aac2bd4de3379288.md b/readline/rl_write_data_key.md similarity index 100% rename from api-docs/29b2537ddc07ac549fadc61e51964243c78a857e5f7129c7aac2bd4de3379288.md rename to readline/rl_write_data_key.md diff --git a/api-docs/ee0cc8116036d8502ab9a07b5a3b600a0f21f4de429766215e94a2421fd0d0b6.md b/readline/use_of_the_completer_function.md similarity index 100% rename from api-docs/ee0cc8116036d8502ab9a07b5a3b600a0f21f4de429766215e94a2421fd0d0b6.md rename to readline/use_of_the_completer_function.md diff --git a/api-docs/8f9b7f58b31744617b718561a7c21815452b0213178794cb68c7f9902dcbfc48.md b/repl/accessing_core_node_js_modules.md similarity index 91% rename from api-docs/8f9b7f58b31744617b718561a7c21815452b0213178794cb68c7f9902dcbfc48.md rename to repl/accessing_core_node_js_modules.md index dd7e92eb..1594a715 100644 --- a/api-docs/8f9b7f58b31744617b718561a7c21815452b0213178794cb68c7f9902dcbfc48.md +++ b/repl/accessing_core_node_js_modules.md @@ -2,8 +2,7 @@ 默认的解释器会自动加载被调用的 Node.js 核心模块到 REPL 环境中。 例如，除非被声明为一个全局变量或一个有限范围的变量，否则输入 `fs` 会被解释为 `global.fs = require('fs')`。 - -```js +```console > fs.createReadStream('./some/file'); ``` diff --git a/api-docs/2b47f7766ee103b7a1e69b74204de2e746d3bca0586f0012540d6607e4b4e0bc.md b/repl/assignment_of_the_underscore_variable.md similarity index 91% rename from api-docs/2b47f7766ee103b7a1e69b74204de2e746d3bca0586f0012540d6607e4b4e0bc.md rename to repl/assignment_of_the_underscore_variable.md index 97e4b889..817be927 100644 --- a/api-docs/2b47f7766ee103b7a1e69b74204de2e746d3bca0586f0012540d6607e4b4e0bc.md +++ b/repl/assignment_of_the_underscore_variable.md @@ -8,8 +8,7 @@ changes: 默认的解释器会把最近一次解释的表达式的结果赋值给变量 `_` （下划线）。 显式地设置 `_` 为某个值能禁用该特性。 - -```js +```console > [ 'a', 'b', 'c' ] [ 'a', 'b', 'c' ] > _.length @@ -26,8 +25,7 @@ Expression assignment to _ now disabled. 同样，`_error` 将指向最后一次看到的错误（如果有的话）。 将 `_error` 显式设置为值将禁用此行为。 - -```js +```console > throw new Error('foo'); Error: foo > _error.message diff --git a/api-docs/b5aa2159416937b05a89eae7443667cc7fa12c27742fb4d2b5ec8d3239beecc3.md b/repl/await_keyword.md similarity index 93% rename from api-docs/b5aa2159416937b05a89eae7443667cc7fa12c27742fb4d2b5ec8d3239beecc3.md rename to repl/await_keyword.md index cf63d5cf..f6105c9a 100644 --- a/api-docs/b5aa2159416937b05a89eae7443667cc7fa12c27742fb4d2b5ec8d3239beecc3.md +++ b/repl/await_keyword.md @@ -1,8 +1,7 @@ 使用 [`--experimental-repl-await`] 命令行选项，将启用对 `await` 关键字的实验性支持。 - -```js +```console > await Promise.resolve(123) 123 > await Promise.reject(new Error('REPL await')) diff --git a/api-docs/74b21508952c74ee628ef1e0094fafec09e3514f41607dc098962a80c240fd01.md b/repl/class_replserver.md similarity index 100% rename from api-docs/74b21508952c74ee628ef1e0094fafec09e3514f41607dc098962a80c240fd01.md rename to repl/class_replserver.md diff --git a/api-docs/332d03b986cb855d0872b950c307906aa80652f6f25a3741c21ad0a6eab1a838.md b/repl/commands_and_special_keys.md similarity index 97% rename from api-docs/332d03b986cb855d0872b950c307906aa80652f6f25a3741c21ad0a6eab1a838.md rename to repl/commands_and_special_keys.md index 70c417ab..60216072 100644 --- a/api-docs/332d03b986cb855d0872b950c307906aa80652f6f25a3741c21ad0a6eab1a838.md +++ b/repl/commands_and_special_keys.md @@ -11,8 +11,7 @@ `> .load ./file/to/load.js` * `.editor` 进入编辑模式（`-D` 完成，`-C` 取消） - -```js +```console > .editor // 进入编辑模式（^D 完成，^C 取消） function welcome(name) { diff --git a/api-docs/d92fdb582d9f54f8d9cc49cb54d02a9242d683e49df3c57863bc5ef173bd7e70.md b/repl/custom_evaluation_functions.md similarity index 100% rename from api-docs/d92fdb582d9f54f8d9cc49cb54d02a9242d683e49df3c57863bc5ef173bd7e70.md rename to repl/custom_evaluation_functions.md diff --git a/api-docs/57e50967944bd6b6c66ba10363adb75ab0aaa93ae223c0fd90866cb05929188c.md b/repl/customizing_repl_output.md similarity index 100% rename from api-docs/57e50967944bd6b6c66ba10363adb75ab0aaa93ae223c0fd90866cb05929188c.md rename to repl/customizing_repl_output.md diff --git a/api-docs/eb1440b698e6254f56e4ad8e8c6af76ac59175f332081d75dda0c6810afe5bb1.md b/repl/default_evaluation.md similarity index 100% rename from api-docs/eb1440b698e6254f56e4ad8e8c6af76ac59175f332081d75dda0c6810afe5bb1.md rename to repl/default_evaluation.md diff --git a/api-docs/91d9d8a6da1cf7e4d7af6b915ddff3493b8cb57190550a2d33584a28d52dc781.md b/repl/design_and_features.md similarity index 100% rename from api-docs/91d9d8a6da1cf7e4d7af6b915ddff3493b8cb57190550a2d33584a28d52dc781.md rename to repl/design_and_features.md diff --git a/repl/environment_variable_options.md b/repl/environment_variable_options.md new file mode 100644 index 00000000..9d855893 --- /dev/null +++ b/repl/environment_variable_options.md @@ -0,0 +1,11 @@ + +使用以下环境变量，可以自定义 Node.js REPL 的各种行为： + + - `NODE_REPL_HISTORY` - 当给定了一个有效的路径，则 REPL 的历史记录将被保存到指定的文件，而不是用户目录下的 `.node_repl_history` 文件。 + 设为 `''`（空字符串）将会禁用持久的 REPL 历史记录。 + 值两头的空格键会被去掉。 + 在 Windows 平台上，具有空值的环境变量是无效的，因此将此变量设置为一个或多个空格可以禁用持久的 REPL 历史记录。 + - `NODE_REPL_HISTORY_SIZE` - 控制历史记录的最大行数。必须是正数。**默认值:** `1000`。 + - `NODE_REPL_MODE` - 可以是 `'sloppy'` 或 `'strict'`。 +  **默认值:** `'sloppy'`，允许代码在非严格模式下运行。 + diff --git a/api-docs/8218d71c273ece4474f8c04885ff8dd4aaa01d49a053cab3b8eb8b62ea3eb012.md b/repl/event_exit.md similarity index 100% rename from api-docs/8218d71c273ece4474f8c04885ff8dd4aaa01d49a053cab3b8eb8b62ea3eb012.md rename to repl/event_exit.md diff --git a/api-docs/69fba70ff612377c98bc28165402c48aee5bf25a0fbe797789b17ed5f944e450.md b/repl/event_reset.md similarity index 97% rename from api-docs/69fba70ff612377c98bc28165402c48aee5bf25a0fbe797789b17ed5f944e450.md rename to repl/event_reset.md index 946937d8..a3d3ae05 100644 --- a/api-docs/69fba70ff612377c98bc28165402c48aee5bf25a0fbe797789b17ed5f944e450.md +++ b/repl/event_reset.md @@ -23,8 +23,7 @@ r.on('reset', initializeContext); 当代码被执行时，全局的 `'m'` 变量可以被修改，但随后的 `.clear` 命令会把它重置回初始值： - -```js +```console $ ./node example.js > m 'test' diff --git a/api-docs/9dd5a9bf8b2765b9497133b4c1d92f4d42e7f97233cb276a0949c2aa186c689a.md b/repl/global_and_local_scope.md similarity index 96% rename from api-docs/9dd5a9bf8b2765b9497133b4c1d92f4d42e7f97233cb276a0949c2aa186c689a.md rename to repl/global_and_local_scope.md index 858db5e5..4f261f54 100644 --- a/api-docs/9dd5a9bf8b2765b9497133b4c1d92f4d42e7f97233cb276a0949c2aa186c689a.md +++ b/repl/global_and_local_scope.md @@ -12,8 +12,7 @@ repl.start('> ').context.m = msg; `context` 对象的属性表现为 REPL 中的局部变量： - -```js +```console $ node repl_test.js > m 'message' diff --git a/api-docs/dd5312afb24e99bef283b7385e484422cc73a22eb386be4d4fde152774a3dfe3.md b/repl/global_uncaught_exceptions.md similarity index 100% rename from api-docs/dd5312afb24e99bef283b7385e484422cc73a22eb386be4d4fde152774a3dfe3.md rename to repl/global_uncaught_exceptions.md diff --git a/api-docs/7d7ad0459d355ee8ff56110c572e83e6e52b2aeacfd9fd9ada7ecba5dd20b880.md b/repl/javascript_expressions.md similarity index 91% rename from api-docs/7d7ad0459d355ee8ff56110c572e83e6e52b2aeacfd9fd9ada7ecba5dd20b880.md rename to repl/javascript_expressions.md index 0f791f57..a4f52572 100644 --- a/api-docs/7d7ad0459d355ee8ff56110c572e83e6e52b2aeacfd9fd9ada7ecba5dd20b880.md +++ b/repl/javascript_expressions.md @@ -1,8 +1,7 @@ 默认的解释器支持直接解释 JavaScript 表达式： - -```js +```console > 1 + 1 2 > const m = 2 diff --git a/api-docs/b7adb916f85eba548f8644d218fa188bbc3f1449fa6f485fed4190ee84e0b491.md b/repl/persistent_history.md similarity index 100% rename from api-docs/b7adb916f85eba548f8644d218fa188bbc3f1449fa6f485fed4190ee84e0b491.md rename to repl/persistent_history.md diff --git a/api-docs/8408c9129870b06d5dba5d575dfcbc9988a263d07e62fe218375ca105fb414a7.md b/repl/recoverable_errors.md similarity index 100% rename from api-docs/8408c9129870b06d5dba5d575dfcbc9988a263d07e62fe218375ca105fb414a7.md rename to repl/recoverable_errors.md diff --git a/api-docs/342a45db98381f1331b23b59058a5d576648e6eefe27ce63433f50cf690a1124.md b/repl/repl.md similarity index 100% rename from api-docs/342a45db98381f1331b23b59058a5d576648e6eefe27ce63433f50cf690a1124.md rename to repl/repl.md diff --git a/api-docs/9e9a0a67c6b810f896cd662bf4a949420c3efa5ee36d34e3b843513202d133bd.md b/repl/repl_start_options.md similarity index 72% rename from api-docs/9e9a0a67c6b810f896cd662bf4a949420c3efa5ee36d34e3b843513202d133bd.md rename to repl/repl_start_options.md index 0aa35db4..e658ac51 100644 --- a/api-docs/9e9a0a67c6b810f896cd662bf4a949420c3efa5ee36d34e3b843513202d133bd.md +++ b/repl/repl_start_options.md @@ -1,6 +1,10 @@ * `options` {Object|string} - * `prompt` {string} 要显示的输入提示符。默认为 `'> '`（末尾有一个空格）。 - * `input` {stream.Readable} REPL 输入要被读取的可读流。默认为 `process.stdin`。 - * `output` {stream.Writable} REPL 输出要被写入的可写流。默认为 `process.stdout`。 - * `terminal` {boolean} 如果为 `true`，则指定 `output` 应被当作一个 TTY 终端，并且可以使用 ANSI/VT100 转义码写入。 - 默认值为初始化时 `output` 流的 `isTTY` 属性的值。 - * `eval` {Function} 当解释每行输入时使用的函数。默认为 JavaScript `eval()` 函数的异步封装。 + * `prompt` {string} 要显示的输入提示符。**默认值:** `'> '`（末尾有一个空格）。 + * `input` {stream.Readable} REPL 输入要被读取的可读流。**默认值:** `process.stdin`。 + * `output` {stream.Writable} REPL 输出要被写入的可写流。**默认值:** `process.stdout`。 + * `terminal` {boolean} 如果为 `true`，则指定 `output` 应被当作一个 TTY 终端。 + **默认值:** 初始化时检查 `output` 流的 `isTTY` 属性的值。 + * `eval` {Function} 当解释每行输入时使用的函数。**默认值:** JavaScript `eval()` 函数的异步封装。 `eval` 函数出错时会返回 `repl.Recoverable`，表明输入不完整并提示用户完成输入。 * `useColors` {boolean} 如果为 `true`，则指定默认的 `writer` 函数可以在 REPL 输出中包含 ANSI 颜色风格。 如果提供了自定义的 `writer` 函数，则该参数无效。 - 默认为 REPL 实例的 `terminal` 属性的值。 + **默认值:** 如果 REPL 实例的 `terminal` 值为 `true`，则检查 `output` 流上的颜色支持。 * `useGlobal` {boolean} 如果为 `true`，则指定默认的解释函数使用 JavaScript `global` 作为上下文，而不是为 REPL 实例创建一个新的独立的上下文。 -    在node命令行(node CLI)交互解释器中，这个值为 `true`. - 默认为 `false`。 +    在node命令行(node CLI)交互解释器中，这个值为 `true`。 + **默认值:** `false`。 * `ignoreUndefined` {boolean} 如果为 `true`，则指定默认的输出器不会输出命令返回的 `undefined` 值。 - 默认为 `false`。 + **默认值:** `false`。 * `writer` {Function} 在写入到 `output` 之前，该函数被调用用来格式化每个命令的输出。 - 默认为 [`util.inspect()`]。 + **默认值:** [`util.inspect()`]。 * `completer` {Function} 可选的函数，用来自定义 Tab 键的自动补全。 详见 [`readline.InterfaceCompleter`]。 * `replMode` {symbol} 一个标志位，指定默认的解释器使用严格模式或默认（sloppy）模式来执行 JavaScript 命令。 @@ -35,7 +39,7 @@ changes: * `repl.REPL_MODE_STRICT` - 使用严格模式解释表达式。该模式等同于在每个 repl 声明前加上 `'use strict'`。 * `breakEvalOnSigint` - 当接收到 `SIGINT` 时停止解释当前代码，比如按下 `Ctrl+C`。 不能与自定义的 `eval` 函数同时使用。 - 默认为 `false`。 + **默认值:** `false`。 * 返回: {repl.REPLServer} `repl.start()` 方法创建并启动一个 [`repl.REPLServer`] 实例。 @@ -45,7 +49,7 @@ changes: ```js const repl = require('repl'); -// 一个 Unix 风格的提示符 +// 一个 Unix 风格的提示符。 repl.start('$ '); ``` diff --git a/api-docs/9f32eabe660f533875b022c0ba478e045e1291d166f38d0ea19584bd6a113263.md b/repl/replserver_clearbufferedcommand.md similarity index 100% rename from api-docs/9f32eabe660f533875b022c0ba478e045e1291d166f38d0ea19584bd6a113263.md rename to repl/replserver_clearbufferedcommand.md diff --git a/api-docs/7dbcae02efba2c1380c65a5b1f5a7d18a1c8e5fb028ca1a9a9848c26aba595bc.md b/repl/replserver_definecommand_keyword_cmd.md similarity index 100% rename from api-docs/7dbcae02efba2c1380c65a5b1f5a7d18a1c8e5fb028ca1a9a9848c26aba595bc.md rename to repl/replserver_definecommand_keyword_cmd.md diff --git a/api-docs/d0d03b4183473ce81dad154e7c52965eff5d7688b879138c9a3f9b632683ff39.md b/repl/replserver_displayprompt_preservecursor.md similarity index 100% rename from api-docs/d0d03b4183473ce81dad154e7c52965eff5d7688b879138c9a3f9b632683ff39.md rename to repl/replserver_displayprompt_preservecursor.md diff --git a/repl/replserver_parsereplkeyword_keyword_rest.md b/repl/replserver_parsereplkeyword_keyword_rest.md new file mode 100644 index 00000000..bc7d8adc --- /dev/null +++ b/repl/replserver_parsereplkeyword_keyword_rest.md @@ -0,0 +1,14 @@ + + +* `keyword` {string} the potential keyword to parse and execute +* `rest` {any} any parameters to the keyword command +* Returns: {boolean} + +> Stability: 0 - Deprecated. + +An internal method used to parse and execute `REPLServer` keywords. +Returns `true` if `keyword` is a valid keyword, otherwise `false`. + diff --git a/repl/replserver_setuphistory_historypath_callback.md b/repl/replserver_setuphistory_historypath_callback.md new file mode 100644 index 00000000..e0bac4bc --- /dev/null +++ b/repl/replserver_setuphistory_historypath_callback.md @@ -0,0 +1,14 @@ + + +* `historyPath` {string} 历史文件的路径。 +* `callback` {Function} 当历史记录写入已准备好或出错时调用。 + * `err` {Error} + * `repl` {repl.REPLServer} + +初始化 REPL 实例的历史记录日志文件。 +当执行 Node.js 二进制文件并使用命令行 REPL 时，默认情况下会初始化历史记录文件。 +但是，以编程方式创建 REPL 时不是这种情况。 +当以编程方式使用 REPL 实例时，使用此方法初始化历史记录日志文件。 + diff --git a/api-docs/9f45a741bdb08a2be6dcc13fb1df7bc787069e632dfa3010d77e967930fa5997.md b/repl/starting_multiple_repl_instances_against_a_single_running_instance.md similarity index 100% rename from api-docs/9f45a741bdb08a2be6dcc13fb1df7bc787069e632dfa3010d77e967930fa5997.md rename to repl/starting_multiple_repl_instances_against_a_single_running_instance.md diff --git a/api-docs/595ab05402f9e16b84fa67fade3aad79c87f059b78a5de3a185cd5a68553a930.md b/repl/the_node_js_repl.md similarity index 92% rename from api-docs/595ab05402f9e16b84fa67fade3aad79c87f059b78a5de3a185cd5a68553a930.md rename to repl/the_node_js_repl.md index 3fb0ea68..7d9f85c7 100644 --- a/api-docs/595ab05402f9e16b84fa67fade3aad79c87f059b78a5de3a185cd5a68553a930.md +++ b/repl/the_node_js_repl.md @@ -2,8 +2,7 @@ Node.js 自身也使用 `repl` 模块为执行 JavaScript 代码提供交互接口。 可以通过不带任何参数（或使用 `-i` 参数）地执行 Node.js 二进制文件来使用它： - -```js +```console $ node > const a = [1, 2, 3]; undefined diff --git a/api-docs/165f53ee3a78635fc8f2ae25107affa81e9e3bd8e0064ce7b6812921ed31d05f.md b/repl/using_the_node_js_repl_with_advanced_line_editors.md similarity index 100% rename from api-docs/165f53ee3a78635fc8f2ae25107affa81e9e3bd8e0064ce7b6812921ed31d05f.md rename to repl/using_the_node_js_repl_with_advanced_line_editors.md diff --git a/api-docs/bae01d969f37fe48cec8522300e3fd17ed9459cd9fc26ab1cb63426f6e0f1a46.md b/stream/additional_notes.md similarity index 100% rename from api-docs/bae01d969f37fe48cec8522300e3fd17ed9459cd9fc26ab1cb63426f6e0f1a46.md rename to stream/additional_notes.md diff --git a/api-docs/54266b736bfffcc5e6108baae123d8896c0cbc87fd4b9994725cc6a931ecfcfd.md b/stream/an_example_counting_stream.md similarity index 100% rename from api-docs/54266b736bfffcc5e6108baae123d8896c0cbc87fd4b9994725cc6a931ecfcfd.md rename to stream/an_example_counting_stream.md diff --git a/api-docs/f5443490ed55beadcae8df04866f766672215cf8a7e776d0b7bf81200d4c7ccc.md b/stream/an_example_duplex_stream.md similarity index 100% rename from api-docs/f5443490ed55beadcae8df04866f766672215cf8a7e776d0b7bf81200d4c7ccc.md rename to stream/an_example_duplex_stream.md diff --git a/api-docs/a3d6a23746fee94e411ac0cfbe171538062425ddd47739fabbd40272aa0373eb.md b/stream/an_example_writable_stream.md similarity index 100% rename from api-docs/a3d6a23746fee94e411ac0cfbe171538062425ddd47739fabbd40272aa0373eb.md rename to stream/an_example_writable_stream.md diff --git a/api-docs/a65d8f642c0df82c2508d53d56b89608ad7115ec5c10caa94d37141dfb55395c.md b/stream/api_for_stream_consumers.md similarity index 100% rename from api-docs/a65d8f642c0df82c2508d53d56b89608ad7115ec5c10caa94d37141dfb55395c.md rename to stream/api_for_stream_consumers.md diff --git a/api-docs/988a083e77853aa771d9a5b34536951a80a10d24e7d367ffbd43840647473af1.md b/stream/api_for_stream_implementers.md similarity index 100% rename from api-docs/988a083e77853aa771d9a5b34536951a80a10d24e7d367ffbd43840647473af1.md rename to stream/api_for_stream_implementers.md diff --git a/api-docs/123a972083c283de96e65cad9f411ea726d18b9014c2aa46568b8d406e1a11c3.md b/stream/buffering.md similarity index 100% rename from api-docs/123a972083c283de96e65cad9f411ea726d18b9014c2aa46568b8d406e1a11c3.md rename to stream/buffering.md diff --git a/api-docs/f51fec6e48b14d1faa595f489da42598790bd21fd8e2ac8fb2e3537b3fb304ad.md b/stream/choose_one_api_style.md similarity index 100% rename from api-docs/f51fec6e48b14d1faa595f489da42598790bd21fd8e2ac8fb2e3537b3fb304ad.md rename to stream/choose_one_api_style.md diff --git a/api-docs/36a6e1f6fc22a1d1cf4555038994705653b96d1df2ba7db6222d51940c778e2c.md b/stream/class_stream_duplex.md similarity index 100% rename from api-docs/36a6e1f6fc22a1d1cf4555038994705653b96d1df2ba7db6222d51940c778e2c.md rename to stream/class_stream_duplex.md diff --git a/api-docs/822fa9e5d5c9d9ba47abcc4767b15b17f204f6613a9278ef6c092946b29b0e92.md b/stream/class_stream_passthrough.md similarity index 100% rename from api-docs/822fa9e5d5c9d9ba47abcc4767b15b17f204f6613a9278ef6c092946b29b0e92.md rename to stream/class_stream_passthrough.md diff --git a/api-docs/cda18bbb7ab19030d9016943cbcfba6d5aa0dc8d3c019266629b52a12a21b041.md b/stream/class_stream_readable.md similarity index 100% rename from api-docs/cda18bbb7ab19030d9016943cbcfba6d5aa0dc8d3c019266629b52a12a21b041.md rename to stream/class_stream_readable.md diff --git a/api-docs/62ede25e233d213c92916c2e4f675617826ae8721efce8df87bf3debd80133f5.md b/stream/class_stream_transform.md similarity index 100% rename from api-docs/62ede25e233d213c92916c2e4f675617826ae8721efce8df87bf3debd80133f5.md rename to stream/class_stream_transform.md diff --git a/api-docs/fe563cd28e5bfe5cf7028cdd95acfbb0ca6288924df369d325244e00fb31e712.md b/stream/class_stream_writable.md similarity index 100% rename from api-docs/fe563cd28e5bfe5cf7028cdd95acfbb0ca6288924df369d325244e00fb31e712.md rename to stream/class_stream_writable.md diff --git a/api-docs/cee7251be393e14d35efe589c6426fbf60c799e2c13ae4349d00d02e7cfb3fcd.md b/stream/compatibility_with_older_node_js_versions.md similarity index 100% rename from api-docs/cee7251be393e14d35efe589c6426fbf60c799e2c13ae4349d00d02e7cfb3fcd.md rename to stream/compatibility_with_older_node_js_versions.md diff --git a/api-docs/9a2e15e37c6fdcca4c48405ba715b0044b964947594834e8a13ab74c3b6cde46.md b/stream/constructor_new_stream_writable_options.md similarity index 100% rename from api-docs/9a2e15e37c6fdcca4c48405ba715b0044b964947594834e8a13ab74c3b6cde46.md rename to stream/constructor_new_stream_writable_options.md diff --git a/api-docs/1b01bec2a80494a21be9cb7d7e20b39edb1240dedec83edb658fdbbfbb489657.md b/stream/decoding_buffers_in_a_writable_stream.md similarity index 100% rename from api-docs/1b01bec2a80494a21be9cb7d7e20b39edb1240dedec83edb658fdbbfbb489657.md rename to stream/decoding_buffers_in_a_writable_stream.md diff --git a/stream/duplex_and_transform_streams.md b/stream/duplex_and_transform_streams.md new file mode 100644 index 00000000..8b137891 --- /dev/null +++ b/stream/duplex_and_transform_streams.md @@ -0,0 +1 @@ + diff --git a/api-docs/8d226d34ba8ad6d67158e5db160d2efd4b089d4ab969269a89e5fb31b0bb8fc3.md b/stream/errors_while_reading.md similarity index 100% rename from api-docs/8d226d34ba8ad6d67158e5db160d2efd4b089d4ab969269a89e5fb31b0bb8fc3.md rename to stream/errors_while_reading.md diff --git a/api-docs/54df7f1bed9e573fae185922f28e16bf0b66ec00d1d5b28ec358a27a63063dbe.md b/stream/errors_while_writing.md similarity index 100% rename from api-docs/54df7f1bed9e573fae185922f28e16bf0b66ec00d1d5b28ec358a27a63063dbe.md rename to stream/errors_while_writing.md diff --git a/api-docs/5eb1a0079a5a0a6808c037a00c12bba85136cac804778c93babb6de4c804eaaa.md b/stream/event_close.md similarity index 100% rename from api-docs/5eb1a0079a5a0a6808c037a00c12bba85136cac804778c93babb6de4c804eaaa.md rename to stream/event_close.md diff --git a/api-docs/059455255187dadbfa70b7e033596e858ecfa6f6098855f9c16604e54eb50656.md b/stream/event_close_1.md similarity index 100% rename from api-docs/059455255187dadbfa70b7e033596e858ecfa6f6098855f9c16604e54eb50656.md rename to stream/event_close_1.md diff --git a/api-docs/0036943e72486fb004ecd56450044a205829a33d86d9e2c7cf6abddda07a40b8.md b/stream/event_data.md similarity index 100% rename from api-docs/0036943e72486fb004ecd56450044a205829a33d86d9e2c7cf6abddda07a40b8.md rename to stream/event_data.md diff --git a/api-docs/25ef5af0320742f7c0c35cdbb83b850ba3939675844a3b6724f59eec305ab305.md b/stream/event_drain.md similarity index 100% rename from api-docs/25ef5af0320742f7c0c35cdbb83b850ba3939675844a3b6724f59eec305ab305.md rename to stream/event_drain.md diff --git a/api-docs/23f19d31d92c479a0655cbf98ae17bb53c82cff770b57c00e21229af421c2fc9.md b/stream/event_end.md similarity index 100% rename from api-docs/23f19d31d92c479a0655cbf98ae17bb53c82cff770b57c00e21229af421c2fc9.md rename to stream/event_end.md diff --git a/api-docs/47d0f33b47a6a1f8415ec02f61475f78851a2a15a1ada10bd9e6f6fd856398a8.md b/stream/event_error.md similarity index 100% rename from api-docs/47d0f33b47a6a1f8415ec02f61475f78851a2a15a1ada10bd9e6f6fd856398a8.md rename to stream/event_error.md diff --git a/api-docs/807632fac465e0a6375999bf132e880af7f61d8342467adf74ed3a01c52fa82a.md b/stream/event_error_1.md similarity index 100% rename from api-docs/807632fac465e0a6375999bf132e880af7f61d8342467adf74ed3a01c52fa82a.md rename to stream/event_error_1.md diff --git a/api-docs/93bcc5b82d645148b0c76a37db2ef19e703b51bfe05fb2ba54cabc8d3cee7cdd.md b/stream/event_finish.md similarity index 100% rename from api-docs/93bcc5b82d645148b0c76a37db2ef19e703b51bfe05fb2ba54cabc8d3cee7cdd.md rename to stream/event_finish.md diff --git a/api-docs/0cc84011e78994a49f25f429e65f55bf7fe00d43d3c74048d4313b2ff14f0dea.md b/stream/event_pipe.md similarity index 100% rename from api-docs/0cc84011e78994a49f25f429e65f55bf7fe00d43d3c74048d4313b2ff14f0dea.md rename to stream/event_pipe.md diff --git a/api-docs/2a0637fe7bd4ca8ea152bca9a6773dd0994daa1e36e20286110d4340862deb3b.md b/stream/event_readable.md similarity index 100% rename from api-docs/2a0637fe7bd4ca8ea152bca9a6773dd0994daa1e36e20286110d4340862deb3b.md rename to stream/event_readable.md diff --git a/api-docs/55d5e00f3f0ca0ea9f17c6af297a9d54481a7bfea5941915b0502c3a9224311b.md b/stream/event_unpipe.md similarity index 100% rename from api-docs/55d5e00f3f0ca0ea9f17c6af297a9d54481a7bfea5941915b0502c3a9224311b.md rename to stream/event_unpipe.md diff --git a/api-docs/34e1e77396cb979bf9d146f4895c4a82efa2dc4370b1f2a22a48b7a7f0d8bb23.md b/stream/events_finish_and_end.md similarity index 100% rename from api-docs/34e1e77396cb979bf9d146f4895c4a82efa2dc4370b1f2a22a48b7a7f0d8bb23.md rename to stream/events_finish_and_end.md diff --git a/api-docs/af93d25b29b56b5fb313fb072c24338542f6fd659c563cc9065ea9ea70f6c189.md b/stream/highwatermark_discrepancy_after_calling_readable_setencoding.md similarity index 100% rename from api-docs/af93d25b29b56b5fb313fb072c24338542f6fd659c563cc9065ea9ea70f6c189.md rename to stream/highwatermark_discrepancy_after_calling_readable_setencoding.md diff --git a/api-docs/2b4ec7cf318c8bb610c21d23025e9a3bac9c832ae9bc805d571b7d9a180b421f.md b/stream/implementing_a_duplex_stream.md similarity index 100% rename from api-docs/2b4ec7cf318c8bb610c21d23025e9a3bac9c832ae9bc805d571b7d9a180b421f.md rename to stream/implementing_a_duplex_stream.md diff --git a/api-docs/9db1692324a11f512d45ef5f5ad74552b609af7556620f267df11efa249e6daf.md b/stream/implementing_a_readable_stream.md similarity index 100% rename from api-docs/9db1692324a11f512d45ef5f5ad74552b609af7556620f267df11efa249e6daf.md rename to stream/implementing_a_readable_stream.md diff --git a/api-docs/69686b61b25a5dfc717469182bed706b90d2ff916d84e0d547b6e4f41d6faa54.md b/stream/implementing_a_transform_stream.md similarity index 100% rename from api-docs/69686b61b25a5dfc717469182bed706b90d2ff916d84e0d547b6e4f41d6faa54.md rename to stream/implementing_a_transform_stream.md diff --git a/api-docs/45c5092b11a70fcaefad8a08b08b04f916affae439600d2fcc8a3b1c98134708.md b/stream/implementing_a_writable_stream.md similarity index 100% rename from api-docs/45c5092b11a70fcaefad8a08b08b04f916affae439600d2fcc8a3b1c98134708.md rename to stream/implementing_a_writable_stream.md diff --git a/api-docs/835a4304dd65fbe5561055506f83646fc7f87081ea12c5b025a311f11dd3b618.md b/stream/new_stream_duplex_options.md similarity index 100% rename from api-docs/835a4304dd65fbe5561055506f83646fc7f87081ea12c5b025a311f11dd3b618.md rename to stream/new_stream_duplex_options.md diff --git a/api-docs/a9522c060463dfd9e235f24f1a7b30e0600e45e152183c8544475d7e087b8026.md b/stream/new_stream_readable_options.md similarity index 100% rename from api-docs/a9522c060463dfd9e235f24f1a7b30e0600e45e152183c8544475d7e087b8026.md rename to stream/new_stream_readable_options.md diff --git a/api-docs/88b55153f065aad4ab2f8e415c63d704e3b7aa2dfb87fe100a4ecb38f2f55228.md b/stream/new_stream_transform_options.md similarity index 100% rename from api-docs/88b55153f065aad4ab2f8e415c63d704e3b7aa2dfb87fe100a4ecb38f2f55228.md rename to stream/new_stream_transform_options.md diff --git a/api-docs/8cd83dd5c64de6b186331514a23298ca014054b584a538d5ced02f1f3de6d036.md b/stream/object_mode.md similarity index 100% rename from api-docs/8cd83dd5c64de6b186331514a23298ca014054b584a538d5ced02f1f3de6d036.md rename to stream/object_mode.md diff --git a/api-docs/e35a0fbae894c252a3d82ae41b0039aaec1905dc7d59e00b20c179feb83ff17b.md b/stream/object_mode_duplex_streams.md similarity index 100% rename from api-docs/e35a0fbae894c252a3d82ae41b0039aaec1905dc7d59e00b20c179feb83ff17b.md rename to stream/object_mode_duplex_streams.md diff --git a/api-docs/6401a597b6312d85d638a2ce97d70528e8b4f1f96c8e756551a394c41e8f298e.md b/stream/organization_of_this_document.md similarity index 100% rename from api-docs/6401a597b6312d85d638a2ce97d70528e8b4f1f96c8e756551a394c41e8f298e.md rename to stream/organization_of_this_document.md diff --git a/api-docs/12d127f0fdccc806d319032e99c1b2cb254680ffd69750929e6f1e89ac8033f9.md b/stream/readable_destroy_err_callback.md similarity index 100% rename from api-docs/12d127f0fdccc806d319032e99c1b2cb254680ffd69750929e6f1e89ac8033f9.md rename to stream/readable_destroy_err_callback.md diff --git a/api-docs/d6fc7db2ad86df8cebac5223593cf3dfa2d15d8c77711563873c560517596eeb.md b/stream/readable_destroy_error.md similarity index 100% rename from api-docs/d6fc7db2ad86df8cebac5223593cf3dfa2d15d8c77711563873c560517596eeb.md rename to stream/readable_destroy_error.md diff --git a/api-docs/908f9633c13c175055f6622835961cf9698ccd350e11e68814fe9d04c7c2eb4f.md b/stream/readable_ispaused.md similarity index 100% rename from api-docs/908f9633c13c175055f6622835961cf9698ccd350e11e68814fe9d04c7c2eb4f.md rename to stream/readable_ispaused.md diff --git a/api-docs/99a14cc699387e5fd2affabeecb697f1f84d2215cc8f8e496ecc5d686887db41.md b/stream/readable_pause.md similarity index 100% rename from api-docs/99a14cc699387e5fd2affabeecb697f1f84d2215cc8f8e496ecc5d686887db41.md rename to stream/readable_pause.md diff --git a/api-docs/bb8bb77fdcfbc9d373eda5996cc75f8913654d416095ce286daf2abe2fb4c4ee.md b/stream/readable_pipe_destination_options.md similarity index 100% rename from api-docs/bb8bb77fdcfbc9d373eda5996cc75f8913654d416095ce286daf2abe2fb4c4ee.md rename to stream/readable_pipe_destination_options.md diff --git a/api-docs/9cd7a11a0889ad907c8b778168e043c66f0ffd3224150964096d69d751245fb1.md b/stream/readable_push.md similarity index 100% rename from api-docs/9cd7a11a0889ad907c8b778168e043c66f0ffd3224150964096d69d751245fb1.md rename to stream/readable_push.md diff --git a/api-docs/922bc8e7bc8014125b60f74a6fae7d092a8ae7c6af425dc50e72d432ed7ede78.md b/stream/readable_push_chunk_encoding.md similarity index 100% rename from api-docs/922bc8e7bc8014125b60f74a6fae7d092a8ae7c6af425dc50e72d432ed7ede78.md rename to stream/readable_push_chunk_encoding.md diff --git a/api-docs/a027c055cfd30c8d3bbe112e7d9f4d7fc6193eb32e1ffffffb4e541908fa6101.md b/stream/readable_read_0.md similarity index 100% rename from api-docs/a027c055cfd30c8d3bbe112e7d9f4d7fc6193eb32e1ffffffb4e541908fa6101.md rename to stream/readable_read_0.md diff --git a/api-docs/5066351e88a11de2dc1bdd6ca8e2567dcdae1241aac4b7688df2819f9806bd2f.md b/stream/readable_read_size.md similarity index 100% rename from api-docs/5066351e88a11de2dc1bdd6ca8e2567dcdae1241aac4b7688df2819f9806bd2f.md rename to stream/readable_read_size.md diff --git a/api-docs/95ba70d014489b8dbdda349a142af21876adf6fbdaabb89884423c68275b4ad5.md b/stream/readable_read_size_1.md similarity index 100% rename from api-docs/95ba70d014489b8dbdda349a142af21876adf6fbdaabb89884423c68275b4ad5.md rename to stream/readable_read_size_1.md diff --git a/api-docs/4746acc96bef11b5bcb9238caa40a373da3aaa5c833a8b4c8101aefd86b2206f.md b/stream/readable_readable.md similarity index 100% rename from api-docs/4746acc96bef11b5bcb9238caa40a373da3aaa5c833a8b4c8101aefd86b2206f.md rename to stream/readable_readable.md diff --git a/api-docs/5ea9f27c7e5a1e27e83244f905e1b549c18881775c77013c04b39eb19836296d.md b/stream/readable_readablehighwatermark.md similarity index 100% rename from api-docs/5ea9f27c7e5a1e27e83244f905e1b549c18881775c77013c04b39eb19836296d.md rename to stream/readable_readablehighwatermark.md diff --git a/api-docs/2076759d63cefb2843a0f09f7dd212038545534d6e900f33b465fe3b0b0bc5c7.md b/stream/readable_readablelength.md similarity index 100% rename from api-docs/2076759d63cefb2843a0f09f7dd212038545534d6e900f33b465fe3b0b0bc5c7.md rename to stream/readable_readablelength.md diff --git a/api-docs/0eb4762a3ed5a51edbd89d14f695b7dd0808556a8b7b2f8a354dd2ecf53b6edf.md b/stream/readable_resume.md similarity index 100% rename from api-docs/0eb4762a3ed5a51edbd89d14f695b7dd0808556a8b7b2f8a354dd2ecf53b6edf.md rename to stream/readable_resume.md diff --git a/api-docs/cecd7a5af4777b43ad59ef12bde6e989b89ffcb26898faa82a03a3db44976ecc.md b/stream/readable_setencoding_encoding.md similarity index 100% rename from api-docs/cecd7a5af4777b43ad59ef12bde6e989b89ffcb26898faa82a03a3db44976ecc.md rename to stream/readable_setencoding_encoding.md diff --git a/api-docs/57dd161f0b1601125e0260bc0276bdb12836668221974b3cec3e63fc7bd804c5.md b/stream/readable_streams.md similarity index 100% rename from api-docs/57dd161f0b1601125e0260bc0276bdb12836668221974b3cec3e63fc7bd804c5.md rename to stream/readable_streams.md diff --git a/stream/readable_symbol_asynciterator.md b/stream/readable_symbol_asynciterator.md new file mode 100644 index 00000000..9829338d --- /dev/null +++ b/stream/readable_symbol_asynciterator.md @@ -0,0 +1,30 @@ + + +> Stability: 1 - Experimental + +* Returns: {AsyncIterator} to fully consume the stream. + +```js +const fs = require('fs'); + +async function print(readable) { + readable.setEncoding('utf8'); + let data = ''; + for await (const k of readable) { + data += k; + } + console.log(data); +} + +print(fs.createReadStream('file')).catch(console.log); +``` + +If the loop terminates with a `break` or a `throw`, the stream will be +destroyed. In other terms, iterating over a stream will consume the stream +fully. The stream will be read in chunks of size equal to the `highWaterMark` +option. In the code example above, data will be in a single chunk if the file +has less then 64kb of data because no `highWaterMark` option is provided to +[`fs.createReadStream()`][]. + diff --git a/api-docs/49d7c31f3d2e506af2730e1c873a13f35c7fecc7dc9b041033ccd9a639af9829.md b/stream/readable_unpipe_destination.md similarity index 100% rename from api-docs/49d7c31f3d2e506af2730e1c873a13f35c7fecc7dc9b041033ccd9a639af9829.md rename to stream/readable_unpipe_destination.md diff --git a/api-docs/69d0135a73af9363a44db841c9b6101bc86711c4b3ab4d9a78ffc4b9124f5003.md b/stream/readable_unshift_chunk.md similarity index 100% rename from api-docs/69d0135a73af9363a44db841c9b6101bc86711c4b3ab4d9a78ffc4b9124f5003.md rename to stream/readable_unshift_chunk.md diff --git a/api-docs/d0544207cde4e9e5ff1908b201f70199b7d1707bbfd92eb9d85a526266c4f390.md b/stream/readable_wrap_stream.md similarity index 100% rename from api-docs/d0544207cde4e9e5ff1908b201f70199b7d1707bbfd92eb9d85a526266c4f390.md rename to stream/readable_wrap_stream.md diff --git a/api-docs/063816271e305a6ab5458b61bed71ce4631885f56835d1beacb0df57d300caa1.md b/stream/simplified_construction.md similarity index 100% rename from api-docs/063816271e305a6ab5458b61bed71ce4631885f56835d1beacb0df57d300caa1.md rename to stream/simplified_construction.md diff --git a/api-docs/95c18abb1f21bb0a01bca314b2d83f9a1ef5d75c32e75637616eddb7330d6d15.md b/stream/stream.md similarity index 100% rename from api-docs/95c18abb1f21bb0a01bca314b2d83f9a1ef5d75c32e75637616eddb7330d6d15.md rename to stream/stream.md diff --git a/api-docs/867616a71591b8581fefc2b819600406eaec8ec9a6f648120bcf903424b470f2.md b/stream/stream_finished_stream_callback.md similarity index 100% rename from api-docs/867616a71591b8581fefc2b819600406eaec8ec9a6f648120bcf903424b470f2.md rename to stream/stream_finished_stream_callback.md diff --git a/api-docs/7cebc90ba63285bf8c7ef2194cd8c596879dad56f46e4a4b5083ef8fd2796baf.md b/stream/stream_pipeline_streams_callback.md similarity index 100% rename from api-docs/7cebc90ba63285bf8c7ef2194cd8c596879dad56f46e4a4b5083ef8fd2796baf.md rename to stream/stream_pipeline_streams_callback.md diff --git a/api-docs/2d2172246598a48ea56788297e3980d7cc91f11520658c461d4d69fd29f40104.md b/stream/three_states.md similarity index 100% rename from api-docs/2d2172246598a48ea56788297e3980d7cc91f11520658c461d4d69fd29f40104.md rename to stream/three_states.md diff --git a/api-docs/3772959156db79d5fbcd628100521191906e27683c88b4eee1c349841c0a4705.md b/stream/transform_destroy_error.md similarity index 100% rename from api-docs/3772959156db79d5fbcd628100521191906e27683c88b4eee1c349841c0a4705.md rename to stream/transform_destroy_error.md diff --git a/api-docs/b06d1e349e46aa8a147070fef63326c1575853adb7aa1352d9275b4b3e0eecfa.md b/stream/transform_flush_callback.md similarity index 100% rename from api-docs/b06d1e349e46aa8a147070fef63326c1575853adb7aa1352d9275b4b3e0eecfa.md rename to stream/transform_flush_callback.md diff --git a/api-docs/fe34c435cac23cac1c005d9eb3dfb52471e5e44c4382fd9ce007cad3766a810c.md b/stream/transform_transform_chunk_encoding_callback.md similarity index 100% rename from api-docs/fe34c435cac23cac1c005d9eb3dfb52471e5e44c4382fd9ce007cad3766a810c.md rename to stream/transform_transform_chunk_encoding_callback.md diff --git a/api-docs/033c217de4fc69706178ea3f805043dbf21c360265ec9d5c356bd4748f4c6a62.md b/stream/two_reading_modes.md similarity index 100% rename from api-docs/033c217de4fc69706178ea3f805043dbf21c360265ec9d5c356bd4748f4c6a62.md rename to stream/two_reading_modes.md diff --git a/api-docs/be5fbc739491186c6613463606080da3c263cda56551f04c24885da9202c18fa.md b/stream/types_of_streams.md similarity index 100% rename from api-docs/be5fbc739491186c6613463606080da3c263cda56551f04c24885da9202c18fa.md rename to stream/types_of_streams.md diff --git a/api-docs/966bb2f870e8b6dd4da4ec7d5a61bfc5ed75868f500c441c49e9d030206a890a.md b/stream/writable_cork.md similarity index 100% rename from api-docs/966bb2f870e8b6dd4da4ec7d5a61bfc5ed75868f500c441c49e9d030206a890a.md rename to stream/writable_cork.md diff --git a/api-docs/2122132664ab5a1c3bf265f6227478b76fd65d50d48abf4a874baf56734cec1b.md b/stream/writable_destroy_err_callback.md similarity index 100% rename from api-docs/2122132664ab5a1c3bf265f6227478b76fd65d50d48abf4a874baf56734cec1b.md rename to stream/writable_destroy_err_callback.md diff --git a/api-docs/ce4a65103cc43fc17ebd6750376a3b1898303a9d994b2ea8878fae3ba08900b9.md b/stream/writable_destroy_error.md similarity index 100% rename from api-docs/ce4a65103cc43fc17ebd6750376a3b1898303a9d994b2ea8878fae3ba08900b9.md rename to stream/writable_destroy_error.md diff --git a/api-docs/2c8bc900d7735dff34f5ea5c495d2a512013be891a1bb37dd6541d4bc8bd883c.md b/stream/writable_end_chunk_encoding_callback.md similarity index 100% rename from api-docs/2c8bc900d7735dff34f5ea5c495d2a512013be891a1bb37dd6541d4bc8bd883c.md rename to stream/writable_end_chunk_encoding_callback.md diff --git a/api-docs/796cab525878c2570305493ee3dfb8c7e5db8c2bc568134dbb83542c0e524294.md b/stream/writable_final_callback.md similarity index 100% rename from api-docs/796cab525878c2570305493ee3dfb8c7e5db8c2bc568134dbb83542c0e524294.md rename to stream/writable_final_callback.md diff --git a/api-docs/9b9d378ce7b553f05d4d8ad46b71cdc0b08985db6cb7be82f138edaf18f7f749.md b/stream/writable_setdefaultencoding_encoding.md similarity index 100% rename from api-docs/9b9d378ce7b553f05d4d8ad46b71cdc0b08985db6cb7be82f138edaf18f7f749.md rename to stream/writable_setdefaultencoding_encoding.md diff --git a/api-docs/328e95db073f0baee7c9f3dffadff2ae5aa10eca79aa0d298df6d083fead9302.md b/stream/writable_streams.md similarity index 100% rename from api-docs/328e95db073f0baee7c9f3dffadff2ae5aa10eca79aa0d298df6d083fead9302.md rename to stream/writable_streams.md diff --git a/api-docs/c0b9e8425fb3a72c11dc3334d7e713a8c18118c1933ba07c3fe5f47602439cd4.md b/stream/writable_uncork.md similarity index 100% rename from api-docs/c0b9e8425fb3a72c11dc3334d7e713a8c18118c1933ba07c3fe5f47602439cd4.md rename to stream/writable_uncork.md diff --git a/api-docs/2464062cba2a072db93ea60bf5264c2df2a7cb8116df5e5cd81f271f6ff5bc29.md b/stream/writable_writable.md similarity index 100% rename from api-docs/2464062cba2a072db93ea60bf5264c2df2a7cb8116df5e5cd81f271f6ff5bc29.md rename to stream/writable_writable.md diff --git a/api-docs/36bf9d10e01c08f15f9b6a5811694910f26ef4ae099b0daa881f9718247229a8.md b/stream/writable_writablehighwatermark.md similarity index 100% rename from api-docs/36bf9d10e01c08f15f9b6a5811694910f26ef4ae099b0daa881f9718247229a8.md rename to stream/writable_writablehighwatermark.md diff --git a/api-docs/ae451aaeba8606c9c607a797ed7c90babcf30897e1cee98f34edfe74c2ed7763.md b/stream/writable_writablelength.md similarity index 100% rename from api-docs/ae451aaeba8606c9c607a797ed7c90babcf30897e1cee98f34edfe74c2ed7763.md rename to stream/writable_writablelength.md diff --git a/api-docs/c59d6e276aaccca20d1bc5d300a15ec13ad66c0e96066e306b0a5046fe5bdc78.md b/stream/writable_write_chunk_encoding_callback.md similarity index 100% rename from api-docs/c59d6e276aaccca20d1bc5d300a15ec13ad66c0e96066e306b0a5046fe5bdc78.md rename to stream/writable_write_chunk_encoding_callback.md diff --git a/api-docs/c3aa3a175835d66a82adf0a2c39026dcc090fc43f3a45924a57f8031a6186a42.md b/stream/writable_write_chunk_encoding_callback_1.md similarity index 100% rename from api-docs/c3aa3a175835d66a82adf0a2c39026dcc090fc43f3a45924a57f8031a6186a42.md rename to stream/writable_write_chunk_encoding_callback_1.md diff --git a/api-docs/53a1ecad757b7b3d304453bca048e638dceb6b09e674f979de5fb211569ceeb5.md b/stream/writable_writev_chunks_callback.md similarity index 100% rename from api-docs/53a1ecad757b7b3d304453bca048e638dceb6b09e674f979de5fb211569ceeb5.md rename to stream/writable_writev_chunks_callback.md diff --git a/string_decoder/class_stringdecoder.md b/string_decoder/class_stringdecoder.md new file mode 100644 index 00000000..8b137891 --- /dev/null +++ b/string_decoder/class_stringdecoder.md @@ -0,0 +1 @@ + diff --git a/api-docs/a739672e4cd5fc91adf00c7b5c545725aa93391f33a8f4ac4945f451695c2e46.md b/string_decoder/new_stringdecoder_encoding.md similarity index 100% rename from api-docs/a739672e4cd5fc91adf00c7b5c545725aa93391f33a8f4ac4945f451695c2e46.md rename to string_decoder/new_stringdecoder_encoding.md diff --git a/api-docs/35768350655433f4a937336fa76ff3dd69dd54919192c8c979aa3f7a0a825456.md b/string_decoder/string_decoder.md similarity index 100% rename from api-docs/35768350655433f4a937336fa76ff3dd69dd54919192c8c979aa3f7a0a825456.md rename to string_decoder/string_decoder.md diff --git a/api-docs/04f026c933c33c8952aded43dfebfd011991ff92b9d6853b57d5b365c020ba31.md b/string_decoder/stringdecoder_end_buffer.md similarity index 100% rename from api-docs/04f026c933c33c8952aded43dfebfd011991ff92b9d6853b57d5b365c020ba31.md rename to string_decoder/stringdecoder_end_buffer.md diff --git a/api-docs/beee525da40964825daa3a3616c3491195466448e635d70c2dfed77c4688cc3c.md b/string_decoder/stringdecoder_write_buffer.md similarity index 100% rename from api-docs/beee525da40964825daa3a3616c3491195466448e635d70c2dfed77c4688cc3c.md rename to string_decoder/stringdecoder_write_buffer.md diff --git a/api-docs/020795248a895625e4bc13ba04936b02e14d80952e70415c1ce73e07658527c0.md b/synopsis/example.md similarity index 100% rename from api-docs/020795248a895625e4bc13ba04936b02e14d80952e70415c1ce73e07658527c0.md rename to synopsis/example.md diff --git a/api-docs/b24626213f0e4818e32de7404c57eda3b898c4f39cd3dd0ba4c6d2639ca048af.md b/synopsis/usage.md similarity index 100% rename from api-docs/b24626213f0e4818e32de7404c57eda3b898c4f39cd3dd0ba4c6d2639ca048af.md rename to synopsis/usage.md diff --git a/synopsis/usage_example.md b/synopsis/usage_example.md new file mode 100644 index 00000000..8b137891 --- /dev/null +++ b/synopsis/usage_example.md @@ -0,0 +1 @@ + diff --git a/api-docs/30b8f1d74a7d39b6ad6f467ad5dc7cb8c9d8b9e2579a14bc654ce0856b916fd8.md b/timers/cancelling_timers.md similarity index 100% rename from api-docs/30b8f1d74a7d39b6ad6f467ad5dc7cb8c9d8b9e2579a14bc654ce0856b916fd8.md rename to timers/cancelling_timers.md diff --git a/api-docs/cf8f36d4e38efaeee4391105f8251c4bbf529ccbd26c16df3899a64cf4285ec1.md b/timers/class_immediate.md similarity index 100% rename from api-docs/cf8f36d4e38efaeee4391105f8251c4bbf529ccbd26c16df3899a64cf4285ec1.md rename to timers/class_immediate.md diff --git a/api-docs/3a17aba46da038557711afaab8790343f96258d950d29af22727bfcfc71f9488.md b/timers/class_timeout.md similarity index 100% rename from api-docs/3a17aba46da038557711afaab8790343f96258d950d29af22727bfcfc71f9488.md rename to timers/class_timeout.md diff --git a/api-docs/7e2565e0f60315fd09d63c0f4380a047c9ed6bd98eec860f4ae909491fc47527.md b/timers/clearimmediate_immediate.md similarity index 100% rename from api-docs/7e2565e0f60315fd09d63c0f4380a047c9ed6bd98eec860f4ae909491fc47527.md rename to timers/clearimmediate_immediate.md diff --git a/api-docs/e411d2ca4f2a28901934b1094caceffc25d1a343a4176068fa9a26c0ac03ac51.md b/timers/clearinterval_timeout.md similarity index 100% rename from api-docs/e411d2ca4f2a28901934b1094caceffc25d1a343a4176068fa9a26c0ac03ac51.md rename to timers/clearinterval_timeout.md diff --git a/api-docs/b421a80fc3903ddd9d8cb9aa3b3c1d5c706f9f0413e70de5cc1297ef70441788.md b/timers/cleartimeout_timeout.md similarity index 100% rename from api-docs/b421a80fc3903ddd9d8cb9aa3b3c1d5c706f9f0413e70de5cc1297ef70441788.md rename to timers/cleartimeout_timeout.md diff --git a/api-docs/0df8a572b7dbefa21c101d8d8822dcd47b53aac4ce7abdde0ef9b9eadabfd086.md b/timers/immediate_hasref.md similarity index 100% rename from api-docs/0df8a572b7dbefa21c101d8d8822dcd47b53aac4ce7abdde0ef9b9eadabfd086.md rename to timers/immediate_hasref.md diff --git a/api-docs/b4cf733d7a596b9080327b934294cabb38b348215c994cb798be259a1ed9cd38.md b/timers/immediate_ref.md similarity index 100% rename from api-docs/b4cf733d7a596b9080327b934294cabb38b348215c994cb798be259a1ed9cd38.md rename to timers/immediate_ref.md diff --git a/api-docs/cc6c4b68f7eb03aaef2375aecc6411d7004ebab8123196ea159feea678d0be85.md b/timers/immediate_unref.md similarity index 100% rename from api-docs/cc6c4b68f7eb03aaef2375aecc6411d7004ebab8123196ea159feea678d0be85.md rename to timers/immediate_unref.md diff --git a/api-docs/a13faeb38e04e1c331f021c3a6c8ee1ed474d7c9a3d9de097975e3e78c12e685.md b/timers/scheduling_timers.md similarity index 100% rename from api-docs/a13faeb38e04e1c331f021c3a6c8ee1ed474d7c9a3d9de097975e3e78c12e685.md rename to timers/scheduling_timers.md diff --git a/api-docs/67f65398e8ea16305f43cee7f26bf7e1d1bdfc82174490bee78828b874858819.md b/timers/setimmediate_callback_args.md similarity index 100% rename from api-docs/67f65398e8ea16305f43cee7f26bf7e1d1bdfc82174490bee78828b874858819.md rename to timers/setimmediate_callback_args.md diff --git a/api-docs/c046594d15762a90d81acfa7db68302f4709d068ba4319f6d08362412a3d3a28.md b/timers/setinterval_callback_delay_args.md similarity index 100% rename from api-docs/c046594d15762a90d81acfa7db68302f4709d068ba4319f6d08362412a3d3a28.md rename to timers/setinterval_callback_delay_args.md diff --git a/api-docs/396f688c9c4681bf3c7d192213023be0e4bd0f7b99763c1a5e0b208e0e437ec4.md b/timers/settimeout_callback_delay_args.md similarity index 100% rename from api-docs/396f688c9c4681bf3c7d192213023be0e4bd0f7b99763c1a5e0b208e0e437ec4.md rename to timers/settimeout_callback_delay_args.md diff --git a/api-docs/a5abb5e3a18ceed4cb896c64178e5ab325218e47b7802b09e1578af46b34919d.md b/timers/timeout_hasref.md similarity index 100% rename from api-docs/a5abb5e3a18ceed4cb896c64178e5ab325218e47b7802b09e1578af46b34919d.md rename to timers/timeout_hasref.md diff --git a/api-docs/5f8f6d52cc5116c5366bc03512497eaa3a2fab7f95b219fe7c5cf5038958c317.md b/timers/timeout_ref.md similarity index 100% rename from api-docs/5f8f6d52cc5116c5366bc03512497eaa3a2fab7f95b219fe7c5cf5038958c317.md rename to timers/timeout_ref.md diff --git a/api-docs/4e17d5f02a8a5de4b3e4a5994103ef69b43b08a439442a1bfc1868190d0dd623.md b/timers/timeout_refresh.md similarity index 100% rename from api-docs/4e17d5f02a8a5de4b3e4a5994103ef69b43b08a439442a1bfc1868190d0dd623.md rename to timers/timeout_refresh.md diff --git a/api-docs/ce63c25538cbdf3b16a2a038366a53c883d33799802b6ccbf2ee7ca99de8e2fb.md b/timers/timeout_unref.md similarity index 100% rename from api-docs/ce63c25538cbdf3b16a2a038366a53c883d33799802b6ccbf2ee7ca99de8e2fb.md rename to timers/timeout_unref.md diff --git a/api-docs/ab404272c190fec3a6488ad03e947320397137d65c41b7e2714e9a818c271cea.md b/timers/timers.md similarity index 100% rename from api-docs/ab404272c190fec3a6488ad03e947320397137d65c41b7e2714e9a818c271cea.md rename to timers/timers.md diff --git a/api-docs/de0cd9e674a8a7991dfdc157c418a1a1eea98617078992a5f49d466036a06e13.md b/tls/alpn_and_sni.md similarity index 100% rename from api-docs/de0cd9e674a8a7991dfdc157c418a1a1eea98617078992a5f49d466036a06e13.md rename to tls/alpn_and_sni.md diff --git a/tls/alpn_npn_and_sni.md b/tls/alpn_npn_and_sni.md new file mode 100644 index 00000000..04446679 --- /dev/null +++ b/tls/alpn_npn_and_sni.md @@ -0,0 +1,10 @@ + + +ALPN (Application-Layer Protocol Negotiation Extension,应用层协议协商), +NPN (Next Protocol Negotiation,下一代协议协商) , +SNI (Server Name Indication,服务器名称指示)是三个TLS拓展: + +* ALPN/NPN - 允许一个TLS服务器使用多个版本的HTTP协议 (HTTP, SPDY, HTTP/2). +* SNI - 允许一个TLS服务器支持多个主机名以及证书. + +*注意*: 应优先使用ALPN而非NPN,因为NPN拓展从未正式定义或记录,一般不建议使用. diff --git a/tls/class_cryptostream.md b/tls/class_cryptostream.md new file mode 100644 index 00000000..2415e54e --- /dev/null +++ b/tls/class_cryptostream.md @@ -0,0 +1,10 @@ + + +> Stability: 0 - Deprecated: Use [`tls.TLSSocket`][] instead. + +The `tls.CryptoStream` class represents a stream of encrypted data. This class +is deprecated and should no longer be used. + diff --git a/tls/class_securepair.md b/tls/class_securepair.md new file mode 100644 index 00000000..7bd0e209 --- /dev/null +++ b/tls/class_securepair.md @@ -0,0 +1,9 @@ + + +> Stability: 0 - Deprecated: Use [`tls.TLSSocket`][] instead. + +Returned by [`tls.createSecurePair()`][]. + diff --git a/api-docs/d48cefdd506578ec7139e1669382b7127a1e11ce6fe6ec7558cddc5466b47329.md b/tls/class_tls_server.md similarity index 100% rename from api-docs/d48cefdd506578ec7139e1669382b7127a1e11ce6fe6ec7558cddc5466b47329.md rename to tls/class_tls_server.md diff --git a/api-docs/788da4d74596f9a6d2f1d11722f80eb204d6d31e585900db94e996e7252509f1.md b/tls/class_tls_tlssocket.md similarity index 100% rename from api-docs/788da4d74596f9a6d2f1d11722f80eb204d6d31e585900db94e996e7252509f1.md rename to tls/class_tls_tlssocket.md diff --git a/api-docs/6e272f55d92419b55b5da8ca4a56ffff17531c3bc62da3e8408757d4548640d9.md b/tls/client_initiated_renegotiation_attack_mitigation.md similarity index 100% rename from api-docs/6e272f55d92419b55b5da8ca4a56ffff17531c3bc62da3e8408757d4548640d9.md rename to tls/client_initiated_renegotiation_attack_mitigation.md diff --git a/tls/cryptostream_byteswritten.md b/tls/cryptostream_byteswritten.md new file mode 100644 index 00000000..1b1e4470 --- /dev/null +++ b/tls/cryptostream_byteswritten.md @@ -0,0 +1,9 @@ + + +The `cryptoStream.bytesWritten` property returns the total number of bytes +written to the underlying socket *including* the bytes required for the +implementation of the TLS protocol. + diff --git a/tls/deprecated_apis.md b/tls/deprecated_apis.md new file mode 100644 index 00000000..8b137891 --- /dev/null +++ b/tls/deprecated_apis.md @@ -0,0 +1 @@ + diff --git a/api-docs/1fe6daf2e9727f78bb4f773f8be00f26145a47ce93622e80c2533e9764a14161.md b/tls/event_newsession.md similarity index 100% rename from api-docs/1fe6daf2e9727f78bb4f773f8be00f26145a47ce93622e80c2533e9764a14161.md rename to tls/event_newsession.md diff --git a/api-docs/ce77124c777d5307b104b4e3535290f6c619838f7b6c74ef18145625706e96bf.md b/tls/event_ocsprequest.md similarity index 100% rename from api-docs/ce77124c777d5307b104b4e3535290f6c619838f7b6c74ef18145625706e96bf.md rename to tls/event_ocsprequest.md diff --git a/api-docs/e6f289c8cd7893e9ff54016a243993771e5e9b6ec3fb261f24a97d749f0a6cdb.md b/tls/event_ocspresponse.md similarity index 100% rename from api-docs/e6f289c8cd7893e9ff54016a243993771e5e9b6ec3fb261f24a97d749f0a6cdb.md rename to tls/event_ocspresponse.md diff --git a/api-docs/fc44a79ece26e63b79db5d52d16c048fd7240bb0325fe1559508efb28da5148a.md b/tls/event_resumesession.md similarity index 100% rename from api-docs/fc44a79ece26e63b79db5d52d16c048fd7240bb0325fe1559508efb28da5148a.md rename to tls/event_resumesession.md diff --git a/tls/event_secure.md b/tls/event_secure.md new file mode 100644 index 00000000..0017dfa3 --- /dev/null +++ b/tls/event_secure.md @@ -0,0 +1,13 @@ + + +The `'secure'` event is emitted by the `SecurePair` object once a secure +connection has been established. + +As with checking for the server +[`'secureConnection'`](#tls_event_secureconnection) +event, `pair.cleartext.authorized` should be inspected to confirm whether the +certificate used is properly authorized. + diff --git a/api-docs/41c6e4e1a9cb1f740a1039f9b3de916eb2f2dcc6f216d3cc9415f59d989e5080.md b/tls/event_secureconnect.md similarity index 100% rename from api-docs/41c6e4e1a9cb1f740a1039f9b3de916eb2f2dcc6f216d3cc9415f59d989e5080.md rename to tls/event_secureconnect.md diff --git a/api-docs/6265f500852b5cd6304b14f34003eed13e5d3f46da86ac604a141917fc4d4eab.md b/tls/event_secureconnection.md similarity index 100% rename from api-docs/6265f500852b5cd6304b14f34003eed13e5d3f46da86ac604a141917fc4d4eab.md rename to tls/event_secureconnection.md diff --git a/api-docs/42671e782fb01ff23b579a1a408e448a173b5406db76b61de7f7b7b837e84a37.md b/tls/event_tlsclienterror.md similarity index 100% rename from api-docs/42671e782fb01ff23b579a1a408e448a173b5406db76b61de7f7b7b837e84a37.md rename to tls/event_tlsclienterror.md diff --git a/api-docs/9abe54a3262b439799cdaee69a61d7c5b3a10fcc4b8ace08aff481de30f70f4a.md b/tls/modifying_the_default_tls_cipher_suite.md similarity index 100% rename from api-docs/9abe54a3262b439799cdaee69a61d7c5b3a10fcc4b8ace08aff481de30f70f4a.md rename to tls/modifying_the_default_tls_cipher_suite.md diff --git a/api-docs/272a51bf9f884cc8c962def3e120b6a8a1fb987ba07b0e4f3ddb8c3b8253ad10.md b/tls/new_tls_tlssocket_socket_options.md similarity index 100% rename from api-docs/272a51bf9f884cc8c962def3e120b6a8a1fb987ba07b0e4f3ddb8c3b8253ad10.md rename to tls/new_tls_tlssocket_socket_options.md diff --git a/api-docs/91c0aa798695a23db5cfe1f5dbc1c3cdef1dfa9a89a61edba0a6b5adf35a1094.md b/tls/perfect_forward_secrecy.md similarity index 100% rename from api-docs/91c0aa798695a23db5cfe1f5dbc1c3cdef1dfa9a89a61edba0a6b5adf35a1094.md rename to tls/perfect_forward_secrecy.md diff --git a/api-docs/9cc8cd651341939481f13b2820cc5261b4275a68b695471dd4e039f5660e6c61.md b/tls/server_addcontext_hostname_context.md similarity index 100% rename from api-docs/9cc8cd651341939481f13b2820cc5261b4275a68b695471dd4e039f5660e6c61.md rename to tls/server_addcontext_hostname_context.md diff --git a/api-docs/01a3bde529a2231fd0ebe3d66626cdd1733ebe06464526cf7f100483db132d10.md b/tls/server_address.md similarity index 100% rename from api-docs/01a3bde529a2231fd0ebe3d66626cdd1733ebe06464526cf7f100483db132d10.md rename to tls/server_address.md diff --git a/api-docs/e459d44e4c038a5648b46844c22e749ec2ef9adefaa42be6ea419543f699ce07.md b/tls/server_close_callback.md similarity index 100% rename from api-docs/e459d44e4c038a5648b46844c22e749ec2ef9adefaa42be6ea419543f699ce07.md rename to tls/server_close_callback.md diff --git a/tls/server_connections.md b/tls/server_connections.md new file mode 100644 index 00000000..50dbd415 --- /dev/null +++ b/tls/server_connections.md @@ -0,0 +1,11 @@ + + +> Stability: 0 - Deprecated: Use [`server.getConnections()`][] instead. + +* {number} + +Returns the current number of concurrent connections on the server. + diff --git a/api-docs/5840011c1b9bcca6181fd462053292c31c3c74a7e98cd64c50755c760e71f150.md b/tls/server_getticketkeys.md similarity index 100% rename from api-docs/5840011c1b9bcca6181fd462053292c31c3c74a7e98cd64c50755c760e71f150.md rename to tls/server_getticketkeys.md diff --git a/api-docs/4b7a45638bc0254cafd961c0d11df66813c026d1d15853b53feaab4d863282a1.md b/tls/server_listen.md similarity index 100% rename from api-docs/4b7a45638bc0254cafd961c0d11df66813c026d1d15853b53feaab4d863282a1.md rename to tls/server_listen.md diff --git a/api-docs/0d8fbeb743a212b8f34b8892ab125f3c4eca3498e808ce24a4bae0845a45e4b5.md b/tls/server_setticketkeys_keys.md similarity index 100% rename from api-docs/0d8fbeb743a212b8f34b8892ab125f3c4eca3498e808ce24a4bae0845a45e4b5.md rename to tls/server_setticketkeys_keys.md diff --git a/api-docs/f9b3317ed1ccbe0c087e758f0df4e2acc5b339bebc08113be8b2ae77a13e9b75.md b/tls/session_resumption.md similarity index 100% rename from api-docs/f9b3317ed1ccbe0c087e758f0df4e2acc5b339bebc08113be8b2ae77a13e9b75.md rename to tls/session_resumption.md diff --git a/tls/tls_checkserveridentity_host_cert.md b/tls/tls_checkserveridentity_host_cert.md new file mode 100644 index 00000000..80839d8b --- /dev/null +++ b/tls/tls_checkserveridentity_host_cert.md @@ -0,0 +1,48 @@ + + +* `host` {string} The hostname to verify the certificate against +* `cert` {Object} An object representing the peer's certificate. The returned + object has some properties corresponding to the fields of the certificate. + +Verifies the certificate `cert` is issued to host `host`. + +Returns {Error} object, populating it with the reason, host, and cert on +failure. On success, returns {undefined}. + +*Note*: This function can be overwritten by providing alternative function +as part of the `options.checkServerIdentity` option passed to `tls.connect()`. +The overwriting function can call `tls.checkServerIdentity()` of course, to augment +the checks done with additional verification. + +*Note*: This function is only called if the certificate passed all other checks, such as +being issued by trusted CA (`options.ca`). + +The cert object contains the parsed certificate and will have a structure similar to: + +```text +{ subject: + { OU: [ 'Domain Control Validated', 'PositiveSSL Wildcard' ], + CN: '*.nodejs.org' }, + issuer: + { C: 'GB', + ST: 'Greater Manchester', + L: 'Salford', + O: 'COMODO CA Limited', + CN: 'COMODO RSA Domain Validation Secure Server CA' }, + subjectaltname: 'DNS:*.nodejs.org, DNS:nodejs.org', + infoAccess: + { 'CA Issuers - URI': + [ 'http://crt.comodoca.com/COMODORSADomainValidationSecureServerCA.crt' ], + 'OCSP - URI': [ 'http://ocsp.comodoca.com' ] }, + modulus: 'B56CE45CB740B09A13F64AC543B712FF9EE8E4C284B542A1708A27E82A8D151CA178153E12E6DDA15BF70FFD96CB8A88618641BDFCCA03527E665B70D779C8A349A6F88FD4EF6557180BD4C98192872BCFE3AF56E863C09DDD8BC1EC58DF9D94F914F0369102B2870BECFA1348A0838C9C49BD1C20124B442477572347047506B1FCD658A80D0C44BCC16BC5C5496CFE6E4A8428EF654CD3D8972BF6E5BFAD59C93006830B5EB1056BBB38B53D1464FA6E02BFDF2FF66CD949486F0775EC43034EC2602AEFBF1703AD221DAA2A88353C3B6A688EFE8387811F645CEED7B3FE46E1F8B9F59FAD028F349B9BC14211D5830994D055EEA3D547911E07A0ADDEB8A82B9188E58720D95CD478EEC9AF1F17BE8141BE80906F1A339445A7EB5B285F68039B0F294598A7D1C0005FC22B5271B0752F58CCDEF8C8FD856FB7AE21C80B8A2CE983AE94046E53EDE4CB89F42502D31B5360771C01C80155918637490550E3F555E2EE75CC8C636DDE3633CFEDD62E91BF0F7688273694EEEBA20C2FC9F14A2A435517BC1D7373922463409AB603295CEB0BB53787A334C9CA3CA8B30005C5A62FC0715083462E00719A8FA3ED0A9828C3871360A73F8B04A4FC1E71302844E9BB9940B77E745C9D91F226D71AFCAD4B113AAF68D92B24DDB4A2136B55A1CD1ADF39605B63CB639038ED0F4C987689866743A68769CC55847E4A06D6E2E3F1', + exponent: '0x10001', + valid_from: 'Aug 14 00:00:00 2017 GMT', + valid_to: 'Nov 20 23:59:59 2019 GMT', + fingerprint: '01:02:59:D9:C3:D2:0D:08:F7:82:4E:44:A4:B4:53:C5:E2:3A:87:4D', + ext_key_usage: [ '1.3.6.1.5.5.7.3.1', '1.3.6.1.5.5.7.3.2' ], + serialNumber: '66593D57F20CBC573E433381B5FEC280', + raw: } +``` + diff --git a/api-docs/0930a174d9ae85dfc2c028d671e49c68e93b939c5257d5f910b2e1b9aa2747c2.md b/tls/tls_checkserveridentity_hostname_cert.md similarity index 100% rename from api-docs/0930a174d9ae85dfc2c028d671e49c68e93b939c5257d5f910b2e1b9aa2747c2.md rename to tls/tls_checkserveridentity_hostname_cert.md diff --git a/api-docs/beffb8ea86ebeba35bddde369ed32aac9609bac7c8638a0d993a86a4461b9348.md b/tls/tls_connect_options_callback.md similarity index 100% rename from api-docs/beffb8ea86ebeba35bddde369ed32aac9609bac7c8638a0d993a86a4461b9348.md rename to tls/tls_connect_options_callback.md diff --git a/api-docs/0830c23d09ccf81892af1f4a0ae4a49d0bf8d59be718bc78542cfb0032ed1e13.md b/tls/tls_connect_path_options_callback.md similarity index 100% rename from api-docs/0830c23d09ccf81892af1f4a0ae4a49d0bf8d59be718bc78542cfb0032ed1e13.md rename to tls/tls_connect_path_options_callback.md diff --git a/api-docs/f5cececf82ff1a5e895c2b645c20f49f3817d1cc513bf00253e9b2c1098f64f0.md b/tls/tls_connect_port_host_options_callback.md similarity index 100% rename from api-docs/f5cececf82ff1a5e895c2b645c20f49f3817d1cc513bf00253e9b2c1098f64f0.md rename to tls/tls_connect_port_host_options_callback.md diff --git a/api-docs/6397f0dfc61f0d1c1c88aa9db5219ec720bcbb8afa0d1a0b47cf3b1e14f849b5.md b/tls/tls_createsecurecontext_options.md similarity index 100% rename from api-docs/6397f0dfc61f0d1c1c88aa9db5219ec720bcbb8afa0d1a0b47cf3b1e14f849b5.md rename to tls/tls_createsecurecontext_options.md diff --git a/api-docs/7b386bba80ffc27a8a989ada7b159702de3c8d1ad3a2dc0cb357d432c401c85b.md b/tls/tls_createsecurepair_context_isserver_requestcert_rejectunauthorized_options.md similarity index 99% rename from api-docs/7b386bba80ffc27a8a989ada7b159702de3c8d1ad3a2dc0cb357d432c401c85b.md rename to tls/tls_createsecurepair_context_isserver_requestcert_rejectunauthorized_options.md index 94141cb0..4913e588 100644 --- a/api-docs/7b386bba80ffc27a8a989ada7b159702de3c8d1ad3a2dc0cb357d432c401c85b.md +++ b/tls/tls_createsecurepair_context_isserver_requestcert_rejectunauthorized_options.md @@ -83,6 +83,16 @@ where `secureSocket` has the same API as `pair.cleartext`. + + + + + + + + + + diff --git a/api-docs/a6a6648cee1bef30e99d2417e7aa67223584b0519dbf6d1a6eaecfc5cc36465a.md b/tls/tls_createserver_options_secureconnectionlistener.md similarity index 100% rename from api-docs/a6a6648cee1bef30e99d2417e7aa67223584b0519dbf6d1a6eaecfc5cc36465a.md rename to tls/tls_createserver_options_secureconnectionlistener.md diff --git a/api-docs/2d92c89ab205910084c39bcc2a38eebf845da3bde4f7c1e3618a8c14bd7c21c1.md b/tls/tls_default_ecdh_curve.md similarity index 100% rename from api-docs/2d92c89ab205910084c39bcc2a38eebf845da3bde4f7c1e3618a8c14bd7c21c1.md rename to tls/tls_default_ecdh_curve.md diff --git a/api-docs/882b8222ac0fda9919809cf5f02358852d5cff2a5d163a811a0c5efe2cc40406.md b/tls/tls_getciphers.md similarity index 100% rename from api-docs/882b8222ac0fda9919809cf5f02358852d5cff2a5d163a811a0c5efe2cc40406.md rename to tls/tls_getciphers.md diff --git a/api-docs/9eb30c9ff484c0bfabf6fb3c5e53434519f55b243a78d329ab3555b2f6ba6910.md b/tls/tls_ssl.md similarity index 100% rename from api-docs/9eb30c9ff484c0bfabf6fb3c5e53434519f55b243a78d329ab3555b2f6ba6910.md rename to tls/tls_ssl.md diff --git a/api-docs/cb4ae4275a553be2192d5d7bd26be793b69faf646064d983f080a17b66b82074.md b/tls/tls_ssl_concepts.md similarity index 100% rename from api-docs/cb4ae4275a553be2192d5d7bd26be793b69faf646064d983f080a17b66b82074.md rename to tls/tls_ssl_concepts.md diff --git a/api-docs/9092bdd1036379b2d81a37c9e80f1dee6c4935cd2a0d2960415d7a0c85b7fead.md b/tls/tlssocket_address.md similarity index 100% rename from api-docs/9092bdd1036379b2d81a37c9e80f1dee6c4935cd2a0d2960415d7a0c85b7fead.md rename to tls/tlssocket_address.md diff --git a/api-docs/d134f66cfeae7ce0c7a28d3d76000a4760f88c95a71aa72bb7ab120df28105c3.md b/tls/tlssocket_authorizationerror.md similarity index 100% rename from api-docs/d134f66cfeae7ce0c7a28d3d76000a4760f88c95a71aa72bb7ab120df28105c3.md rename to tls/tlssocket_authorizationerror.md diff --git a/api-docs/f31a5210b16ee232c65bdfbdd78935fcbb0a35c9321d5c1c8ac5a038bd4a1e30.md b/tls/tlssocket_authorized.md similarity index 100% rename from api-docs/f31a5210b16ee232c65bdfbdd78935fcbb0a35c9321d5c1c8ac5a038bd4a1e30.md rename to tls/tlssocket_authorized.md diff --git a/api-docs/442599fe1295b318022434d149607dfaca264a93ff69df9b9bc347cc54a375f8.md b/tls/tlssocket_disablerenegotiation.md similarity index 100% rename from api-docs/442599fe1295b318022434d149607dfaca264a93ff69df9b9bc347cc54a375f8.md rename to tls/tlssocket_disablerenegotiation.md diff --git a/api-docs/448a156e78db4656dc1e457114d4feddd083fbf6e19eb32517669abe86fa92fc.md b/tls/tlssocket_encrypted.md similarity index 100% rename from api-docs/448a156e78db4656dc1e457114d4feddd083fbf6e19eb32517669abe86fa92fc.md rename to tls/tlssocket_encrypted.md diff --git a/api-docs/49e308b328930819af9ab4fe9c0819d17b68ebe365b3280882e577390478bf02.md b/tls/tlssocket_getcipher.md similarity index 100% rename from api-docs/49e308b328930819af9ab4fe9c0819d17b68ebe365b3280882e577390478bf02.md rename to tls/tlssocket_getcipher.md diff --git a/api-docs/19390d51bcf39c276978e25b1824ba0c799eeff6035c7bb186c15d2950ab217f.md b/tls/tlssocket_getephemeralkeyinfo.md similarity index 100% rename from api-docs/19390d51bcf39c276978e25b1824ba0c799eeff6035c7bb186c15d2950ab217f.md rename to tls/tlssocket_getephemeralkeyinfo.md diff --git a/api-docs/b489540e56bac1e849a3bf9509a0167cacbeef6f8a5ed3f01e657bf63b77c499.md b/tls/tlssocket_getfinished.md similarity index 100% rename from api-docs/b489540e56bac1e849a3bf9509a0167cacbeef6f8a5ed3f01e657bf63b77c499.md rename to tls/tlssocket_getfinished.md diff --git a/api-docs/eed47d34fe0f687c87cc926fe1be379c8899d769987dc1632e0f58aa6477e08e.md b/tls/tlssocket_getpeercertificate_detailed.md similarity index 100% rename from api-docs/eed47d34fe0f687c87cc926fe1be379c8899d769987dc1632e0f58aa6477e08e.md rename to tls/tlssocket_getpeercertificate_detailed.md diff --git a/api-docs/86a675d2679a38e25f3617953d38c48a0d0bedf8162d1e75a241e4b0aba6946f.md b/tls/tlssocket_getpeerfinished.md similarity index 100% rename from api-docs/86a675d2679a38e25f3617953d38c48a0d0bedf8162d1e75a241e4b0aba6946f.md rename to tls/tlssocket_getpeerfinished.md diff --git a/api-docs/86aadda16fdc18e5ca5086a3af5b6049db79e4a0542ad4b6fd8fdca6c9bbd15a.md b/tls/tlssocket_getprotocol.md similarity index 100% rename from api-docs/86aadda16fdc18e5ca5086a3af5b6049db79e4a0542ad4b6fd8fdca6c9bbd15a.md rename to tls/tlssocket_getprotocol.md diff --git a/api-docs/c701c7895abd1a075122f93432c9c3483ae3d3fd5f5e0dd0aac6154f226360f5.md b/tls/tlssocket_getsession.md similarity index 100% rename from api-docs/c701c7895abd1a075122f93432c9c3483ae3d3fd5f5e0dd0aac6154f226360f5.md rename to tls/tlssocket_getsession.md diff --git a/api-docs/4b1d6ad8b58bc998bfd2e8d9c6a513287874cee310342824eb90331e1cbdb494.md b/tls/tlssocket_gettlsticket.md similarity index 100% rename from api-docs/4b1d6ad8b58bc998bfd2e8d9c6a513287874cee310342824eb90331e1cbdb494.md rename to tls/tlssocket_gettlsticket.md diff --git a/api-docs/213c114dd998f0b809e15ad5198f402921f9b3b564d4eb61df02e8f70bbbeb8c.md b/tls/tlssocket_issessionreused.md similarity index 100% rename from api-docs/213c114dd998f0b809e15ad5198f402921f9b3b564d4eb61df02e8f70bbbeb8c.md rename to tls/tlssocket_issessionreused.md diff --git a/api-docs/0e41feb1bb66c06442411add8dd86ec9ed4f389782c68aab3f96f6de2365f089.md b/tls/tlssocket_localaddress.md similarity index 100% rename from api-docs/0e41feb1bb66c06442411add8dd86ec9ed4f389782c68aab3f96f6de2365f089.md rename to tls/tlssocket_localaddress.md diff --git a/api-docs/594b50a9b4a5a2790583387f2878ac0cce9a6c7aab57fabf40544644a1733fd0.md b/tls/tlssocket_localport.md similarity index 100% rename from api-docs/594b50a9b4a5a2790583387f2878ac0cce9a6c7aab57fabf40544644a1733fd0.md rename to tls/tlssocket_localport.md diff --git a/api-docs/99e04cfd9343111aa91e1a093a2a4af6a3aeb082be94df30fbdaa9222bea2463.md b/tls/tlssocket_remoteaddress.md similarity index 100% rename from api-docs/99e04cfd9343111aa91e1a093a2a4af6a3aeb082be94df30fbdaa9222bea2463.md rename to tls/tlssocket_remoteaddress.md diff --git a/api-docs/2c2aafc3a935b8d4dec47f21f1bbf0976d5bcacea584d5034c3ed68ee944f52d.md b/tls/tlssocket_remotefamily.md similarity index 100% rename from api-docs/2c2aafc3a935b8d4dec47f21f1bbf0976d5bcacea584d5034c3ed68ee944f52d.md rename to tls/tlssocket_remotefamily.md diff --git a/api-docs/b2cf030808a10db1009964cc00cc1c814345e5f87ee75da0050715207b15f8d1.md b/tls/tlssocket_remoteport.md similarity index 100% rename from api-docs/b2cf030808a10db1009964cc00cc1c814345e5f87ee75da0050715207b15f8d1.md rename to tls/tlssocket_remoteport.md diff --git a/api-docs/04dcbc9d6f00066a71a2dbdd1ac92cf6a909b20421b2f3384143937c867b478a.md b/tls/tlssocket_renegotiate_options_callback.md similarity index 100% rename from api-docs/04dcbc9d6f00066a71a2dbdd1ac92cf6a909b20421b2f3384143937c867b478a.md rename to tls/tlssocket_renegotiate_options_callback.md diff --git a/api-docs/4dccca7cd481c70abbb6b5fdca4c673351615c82864a71ee13191eed8a93d1af.md b/tls/tlssocket_setmaxsendfragment_size.md similarity index 100% rename from api-docs/4dccca7cd481c70abbb6b5fdca4c673351615c82864a71ee13191eed8a93d1af.md rename to tls/tlssocket_setmaxsendfragment_size.md diff --git a/tracing/the_trace_events_module.md b/tracing/the_trace_events_module.md new file mode 100644 index 00000000..939bef88 --- /dev/null +++ b/tracing/the_trace_events_module.md @@ -0,0 +1,4 @@ + + diff --git a/tracing/trace_events.md b/tracing/trace_events.md new file mode 100644 index 00000000..fa49fa67 --- /dev/null +++ b/tracing/trace_events.md @@ -0,0 +1,86 @@ + + + +> Stability: 1 - Experimental + +Trace Event provides a mechanism to centralize tracing information generated by +V8, Node.js core, and userspace code. + +Tracing can be enabled with the `--trace-event-categories` command-line flag +or by using the `trace_events` module. The `--trace-event-categories` flag +accepts a list of comma-separated category names. + +The available categories are: + +* `node` - An empty placeholder. +* `node.async_hooks` - Enables capture of detailed [`async_hooks`] trace data. + The [`async_hooks`] events have a unique `asyncId` and a special `triggerId` + `triggerAsyncId` property. +* `node.bootstrap` - Enables capture of Node.js bootstrap milestones. +* `node.console` - Enables capture of `console.time()` and `console.count()` + output. +* `node.dns.native` - Enables capture of trace data for DNS queries. +* `node.environment` - Enables capture of Node.js Environment milestones. +* `node.fs.sync` - Enables capture of trace data for file system sync methods. +* `node.perf` - Enables capture of [Performance API] measurements. + * `node.perf.usertiming` - Enables capture of only Performance API User Timing + measures and marks. + * `node.perf.timerify` - Enables capture of only Performance API timerify + measurements. +* `node.promises.rejections` - Enables capture of trace data tracking the number + of unhandled Promise rejections and handled-after-rejections. +* `node.vm.script` - Enables capture of trace data for the `vm` module's + `runInNewContext()`, `runInContext()`, and `runInThisContext()` methods. +* `v8` - The [V8] events are GC, compiling, and execution related. + +By default the `node`, `node.async_hooks`, and `v8` categories are enabled. + +```txt +node --trace-event-categories v8,node,node.async_hooks server.js +``` + +Prior versions of Node.js required the use of the `--trace-events-enabled` +flag to enable trace events. This requirement has been removed. However, the +`--trace-events-enabled` flag *may* still be used and will enable the +`node`, `node.async_hooks`, and `v8` trace event categories by default. + +```txt +node --trace-events-enabled + +// is equivalent to + +node --trace-event-categories v8,node,node.async_hooks +``` + +Alternatively, trace events may be enabled using the `trace_events` module: + +```js +const trace_events = require('trace_events'); +const tracing = trace_events.createTracing({ categories: ['node.perf'] }); +tracing.enable(); // Enable trace event capture for the 'node.perf' category + +// do work + +tracing.disable(); // Disable trace event capture for the 'node.perf' category +``` + +Running Node.js with tracing enabled will produce log files that can be opened +in the [`chrome://tracing`](https://www.chromium.org/developers/how-tos/trace-event-profiling-tool) +tab of Chrome. + +The logging file is by default called `node_trace.${rotation}.log`, where +`${rotation}` is an incrementing log-rotation id. The filepath pattern can +be specified with `--trace-event-file-pattern` that accepts a template +string that supports `${rotation}` and `${pid}`: + +```txt +node --trace-event-categories v8 --trace-event-file-pattern '${pid}-${rotation}.log' server.js +``` + +Starting with Node.js 10.0.0, the tracing system uses the same time source +as the one used by `process.hrtime()` +however the trace-event timestamps are expressed in microseconds, +unlike `process.hrtime()` which returns nanoseconds. + +The features from this module are not available in [`Worker`][] threads. + diff --git a/tracing/trace_events_createtracing_options.md b/tracing/trace_events_createtracing_options.md new file mode 100644 index 00000000..8e56e4ac --- /dev/null +++ b/tracing/trace_events_createtracing_options.md @@ -0,0 +1,21 @@ + + +* `options` {Object} + * `categories` {string[]} An array of trace category names. Values included + in the array are coerced to a string when possible. An error will be + thrown if the value cannot be coerced. +* Returns: {Tracing}. + +Creates and returns a `Tracing` object for the given set of `categories`. + +```js +const trace_events = require('trace_events'); +const categories = ['node.perf', 'node.async_hooks']; +const tracing = trace_events.createTracing({ categories }); +tracing.enable(); +// do stuff +tracing.disable(); +``` + diff --git a/api-docs/4029f238446a2f6b27ab60bfd56f358f3ad1b1ee59a27e7917649ce224ee74f2.md b/tracing/trace_events_getenabledcategories.md similarity index 99% rename from api-docs/4029f238446a2f6b27ab60bfd56f358f3ad1b1ee59a27e7917649ce224ee74f2.md rename to tracing/trace_events_getenabledcategories.md index 417ae585..19f19803 100644 --- a/api-docs/4029f238446a2f6b27ab60bfd56f358f3ad1b1ee59a27e7917649ce224ee74f2.md +++ b/tracing/trace_events_getenabledcategories.md @@ -28,3 +28,4 @@ console.log(trace_events.getEnabledCategories()); + diff --git a/tracing/tracing_categories.md b/tracing/tracing_categories.md new file mode 100644 index 00000000..d0e0f494 --- /dev/null +++ b/tracing/tracing_categories.md @@ -0,0 +1,9 @@ + + +* {string} + +A comma-separated list of the trace event categories covered by this +`Tracing` object. + diff --git a/tracing/tracing_disable.md b/tracing/tracing_disable.md new file mode 100644 index 00000000..6722beac --- /dev/null +++ b/tracing/tracing_disable.md @@ -0,0 +1,25 @@ + + +Disables this `Tracing` object. + +Only trace event categories *not* covered by other enabled `Tracing` objects +and *not* specified by the `--trace-event-categories` flag will be disabled. + +```js +const trace_events = require('trace_events'); +const t1 = trace_events.createTracing({ categories: ['node', 'v8'] }); +const t2 = trace_events.createTracing({ categories: ['node.perf', 'node'] }); +t1.enable(); +t2.enable(); + +// Prints 'node,node.perf,v8' +console.log(trace_events.getEnabledCategories()); + +t2.disable(); // Will only disable emission of the 'node.perf' category + +// Prints 'node,v8' +console.log(trace_events.getEnabledCategories()); +``` + diff --git a/tracing/tracing_enable.md b/tracing/tracing_enable.md new file mode 100644 index 00000000..53d0781d --- /dev/null +++ b/tracing/tracing_enable.md @@ -0,0 +1,7 @@ + + +Enables this `Tracing` object for the set of categories covered by the +`Tracing` object. + diff --git a/tracing/tracing_enabled.md b/tracing/tracing_enabled.md new file mode 100644 index 00000000..c527d007 --- /dev/null +++ b/tracing/tracing_enabled.md @@ -0,0 +1,6 @@ + + +* {boolean} `true` only if the `Tracing` object has been enabled. + diff --git a/tracing/tracing_object.md b/tracing/tracing_object.md new file mode 100644 index 00000000..80070602 --- /dev/null +++ b/tracing/tracing_object.md @@ -0,0 +1,13 @@ + + +The `Tracing` object is used to enable or disable tracing for sets of +categories. Instances are created using the `trace_events.createTracing()` +method. + +When created, the `Tracing` object is disabled. Calling the +`tracing.enable()` method adds the categories to the set of enabled trace event +categories. Calling `tracing.disable()` will remove the categories from the +set of enabled trace event categories. + diff --git a/api-docs/c08611e0bc4ce5872f15335d3f90ba3815671a9899b424e11f4978c287fd3312.md b/tty/class_tty_readstream.md similarity index 100% rename from api-docs/c08611e0bc4ce5872f15335d3f90ba3815671a9899b424e11f4978c287fd3312.md rename to tty/class_tty_readstream.md diff --git a/api-docs/585dc44859dd370dc4c7ba278bf105039a2c0af173325b376ee2076fb9083ebe.md b/tty/class_tty_writestream.md similarity index 100% rename from api-docs/585dc44859dd370dc4c7ba278bf105039a2c0af173325b376ee2076fb9083ebe.md rename to tty/class_tty_writestream.md diff --git a/api-docs/1bb267d58b7c70b965155326d71590c242720b27d94f6f476beed46e28cd696f.md b/tty/event_resize.md similarity index 100% rename from api-docs/1bb267d58b7c70b965155326d71590c242720b27d94f6f476beed46e28cd696f.md rename to tty/event_resize.md diff --git a/api-docs/2517b9f886334d3476ac367c28dd4bdc1928968a8251a392df2aa08abfaedd3a.md b/tty/readstream_israw.md similarity index 100% rename from api-docs/2517b9f886334d3476ac367c28dd4bdc1928968a8251a392df2aa08abfaedd3a.md rename to tty/readstream_israw.md diff --git a/api-docs/226ae6529e1f2efc628b8452f8d574fe5c3344419669d666492fc765f4feb929.md b/tty/readstream_istty.md similarity index 100% rename from api-docs/226ae6529e1f2efc628b8452f8d574fe5c3344419669d666492fc765f4feb929.md rename to tty/readstream_istty.md diff --git a/api-docs/ae48ffdcdef915e3227f7f90e0c051ff58f34d8929724a2faae03303345bb6cf.md b/tty/readstream_setrawmode_mode.md similarity index 100% rename from api-docs/ae48ffdcdef915e3227f7f90e0c051ff58f34d8929724a2faae03303345bb6cf.md rename to tty/readstream_setrawmode_mode.md diff --git a/api-docs/7939932086ed2419115ebc9618c5d7949d25d701fb56c3c82ba6ea922916a7fa.md b/tty/tty.md similarity index 100% rename from api-docs/7939932086ed2419115ebc9618c5d7949d25d701fb56c3c82ba6ea922916a7fa.md rename to tty/tty.md diff --git a/api-docs/0e14af30be2bbc413875512fa56bcc5b2d0aac60ef66de43e47737277eef9924.md b/tty/tty_isatty_fd.md similarity index 100% rename from api-docs/0e14af30be2bbc413875512fa56bcc5b2d0aac60ef66de43e47737277eef9924.md rename to tty/tty_isatty_fd.md diff --git a/tty/writestream_clearline_dir_callback.md b/tty/writestream_clearline_dir_callback.md new file mode 100644 index 00000000..ec69d599 --- /dev/null +++ b/tty/writestream_clearline_dir_callback.md @@ -0,0 +1,17 @@ + + +* `dir` {number} + * `-1` - 从光标向左。 + * `1` - 从光标向右。 + * `0` - 整行。 +* `callback` {Function} 操作完成后调用。 +* 返回: {boolean} 如果流希望调用的代码在继续写入附加的数据之前等待 `'drain'` 事件触发，则为 `false`，否则为 `true`。 + +`writeStream.clearLine()` 在 `dir` 标识的方向上清除此 `WriteStream` 的当前行。 + diff --git a/tty/writestream_clearscreendown_callback.md b/tty/writestream_clearscreendown_callback.md new file mode 100644 index 00000000..d0084540 --- /dev/null +++ b/tty/writestream_clearscreendown_callback.md @@ -0,0 +1,13 @@ + + +* `callback` {Function} 操作完成后调用。 +* 返回: {boolean} 如果流希望调用的代码在继续写入附加的数据之前等待 `'drain'` 事件触发，则为 `false`，否则为 `true`。 + +`writeStream.clearScreenDown()` 从当前光标向下清除此 `WriteStream`。 + diff --git a/api-docs/bce90b0e01cb98e7f72617558d2100df3a9a010364c4fd1692f435fe0e110304.md b/tty/writestream_columns.md similarity index 100% rename from api-docs/bce90b0e01cb98e7f72617558d2100df3a9a010364c4fd1692f435fe0e110304.md rename to tty/writestream_columns.md diff --git a/tty/writestream_cursorto_x_y_callback.md b/tty/writestream_cursorto_x_y_callback.md new file mode 100644 index 00000000..692ba312 --- /dev/null +++ b/tty/writestream_cursorto_x_y_callback.md @@ -0,0 +1,15 @@ + + +* `x` {number} +* `y` {number} +* `callback` {Function} 操作完成后调用。 +* 返回: {boolean} 如果流希望调用的代码在继续写入附加的数据之前等待 `'drain'` 事件触发，则为 `false`，否则为 `true`。 + +`writeStream.cursorTo()` 将 `WriteStream` 的光标移动到指定的位置。 + diff --git a/api-docs/025cc96fb5366a24324a5da2368e79e4711325eb2f1283130cf01b513f78dd73.md b/tty/writestream_getcolordepth_env.md similarity index 100% rename from api-docs/025cc96fb5366a24324a5da2368e79e4711325eb2f1283130cf01b513f78dd73.md rename to tty/writestream_getcolordepth_env.md diff --git a/api-docs/cd9771f4d848b64c3929d469360010de5f76802b87646c02de4fc78df70412b4.md b/tty/writestream_getwindowsize.md similarity index 100% rename from api-docs/cd9771f4d848b64c3929d469360010de5f76802b87646c02de4fc78df70412b4.md rename to tty/writestream_getwindowsize.md diff --git a/api-docs/b0888bf97284e6ffc5a5dcae435c598647ade5c07a627be4138946339ece6bbc.md b/tty/writestream_hascolors_count_env.md similarity index 100% rename from api-docs/b0888bf97284e6ffc5a5dcae435c598647ade5c07a627be4138946339ece6bbc.md rename to tty/writestream_hascolors_count_env.md diff --git a/api-docs/3dd35e81912750ee2336c1949f88191e49a07a69056a603d4b34d8d1f34c8e57.md b/tty/writestream_istty.md similarity index 100% rename from api-docs/3dd35e81912750ee2336c1949f88191e49a07a69056a603d4b34d8d1f34c8e57.md rename to tty/writestream_istty.md diff --git a/tty/writestream_movecursor_dx_dy_callback.md b/tty/writestream_movecursor_dx_dy_callback.md new file mode 100644 index 00000000..8445564f --- /dev/null +++ b/tty/writestream_movecursor_dx_dy_callback.md @@ -0,0 +1,15 @@ + + +* `dx` {number} +* `dy` {number} +* `callback` {Function} 操作完成后调用。 +* 返回: {boolean} 如果流希望调用的代码在继续写入附加的数据之前等待 `'drain'` 事件触发，则为 `false`，否则为 `true`。 + +`writeStream.moveCursor()` 将 `WriteStream` 的光标相对于其当前位置移动。 + diff --git a/api-docs/116812abe9b5a077c6f75a6c78b6fe9a1c0a3bdca7c30de3d2f7cab1047e1c32.md b/tty/writestream_rows.md similarity index 100% rename from api-docs/116812abe9b5a077c6f75a6c78b6fe9a1c0a3bdca7c30de3d2f7cab1047e1c32.md rename to tty/writestream_rows.md diff --git a/api-docs/3eb4e134a5fd9d0edf9cc3aa7f341f7498a3119fbd00775262870fc666ea4a0e.md b/url/class_url.md similarity index 100% rename from api-docs/3eb4e134a5fd9d0edf9cc3aa7f341f7498a3119fbd00775262870fc666ea4a0e.md rename to url/class_url.md diff --git a/api-docs/a102c93f9010db1cf88d8e6df071e6ee5a1dd2b551f54931ff93178cccb55ac0.md b/url/class_urlsearchparams.md similarity index 100% rename from api-docs/a102c93f9010db1cf88d8e6df071e6ee5a1dd2b551f54931ff93178cccb55ac0.md rename to url/class_urlsearchparams.md diff --git a/api-docs/11e698ee5ca836a18cf0680fd215190e9008d7a7c689040691298d5409a786d8.md b/url/constructor_new_url_input_base.md similarity index 100% rename from api-docs/11e698ee5ca836a18cf0680fd215190e9008d7a7c689040691298d5409a786d8.md rename to url/constructor_new_url_input_base.md diff --git a/api-docs/7343a320cbba586e6fbf5e80ef31875caed5c0433f2a053afa0482f187045c70.md b/url/constructor_new_urlsearchparams.md similarity index 100% rename from api-docs/7343a320cbba586e6fbf5e80ef31875caed5c0433f2a053afa0482f187045c70.md rename to url/constructor_new_urlsearchparams.md diff --git a/api-docs/549adb0452914699d6a6538d13d0e95e30f1e73c436ca8a2b64e67384c5c2572.md b/url/constructor_new_urlsearchparams_iterable.md similarity index 100% rename from api-docs/549adb0452914699d6a6538d13d0e95e30f1e73c436ca8a2b64e67384c5c2572.md rename to url/constructor_new_urlsearchparams_iterable.md diff --git a/api-docs/e890a227e9590260d78da90040b738d787459d75f74a64535e009aba9c3b57cd.md b/url/constructor_new_urlsearchparams_obj.md similarity index 100% rename from api-docs/e890a227e9590260d78da90040b738d787459d75f74a64535e009aba9c3b57cd.md rename to url/constructor_new_urlsearchparams_obj.md diff --git a/api-docs/99e1db66ff0222aaf0d89d516858ed1fdcc340de64741b89796fdf65f1ef48ce.md b/url/constructor_new_urlsearchparams_string.md similarity index 100% rename from api-docs/99e1db66ff0222aaf0d89d516858ed1fdcc340de64741b89796fdf65f1ef48ce.md rename to url/constructor_new_urlsearchparams_string.md diff --git a/api-docs/413c7a9725e13b6e1d52a43bfb7af7ca0bf836e3a3d48d7295f092dd45d1dcf9.md b/url/legacy_api.md similarity index 100% rename from api-docs/413c7a9725e13b6e1d52a43bfb7af7ca0bf836e3a3d48d7295f092dd45d1dcf9.md rename to url/legacy_api.md diff --git a/url/legacy_url_api.md b/url/legacy_url_api.md new file mode 100644 index 00000000..8b137891 --- /dev/null +++ b/url/legacy_url_api.md @@ -0,0 +1 @@ + diff --git a/api-docs/c931157cfed8f57eee95f33af5c809c86d6c8e0dd0ca0b58a1cca0be0f87a4d0.md b/url/legacy_urlobject.md similarity index 100% rename from api-docs/c931157cfed8f57eee95f33af5c809c86d6c8e0dd0ca0b58a1cca0be0f87a4d0.md rename to url/legacy_urlobject.md diff --git a/api-docs/e92765eec2d67651a33a2d137f7b403dd76ebecf3c60f86acbae70c2b4ea68df.md b/url/percent_encoding_in_urls.md similarity index 100% rename from api-docs/e92765eec2d67651a33a2d137f7b403dd76ebecf3c60f86acbae70c2b4ea68df.md rename to url/percent_encoding_in_urls.md diff --git a/api-docs/3c9883fa039b20a94f03fb85ae09df6e9f098ec197911b20e71101a60041505c.md b/url/special_schemes.md similarity index 100% rename from api-docs/3c9883fa039b20a94f03fb85ae09df6e9f098ec197911b20e71101a60041505c.md rename to url/special_schemes.md diff --git a/url/the_whatwg_url_api.md b/url/the_whatwg_url_api.md new file mode 100644 index 00000000..8b137891 --- /dev/null +++ b/url/the_whatwg_url_api.md @@ -0,0 +1 @@ + diff --git a/api-docs/bba6c8a0b4189f6e755262542b35e760f58185c9c0053647b212beab783c9b92.md b/url/url.md similarity index 100% rename from api-docs/bba6c8a0b4189f6e755262542b35e760f58185c9c0053647b212beab783c9b92.md rename to url/url.md diff --git a/api-docs/cbb48120acbfd4a030217df775fb9d326aa6783fa5c8efa2c2b576d36139737c.md b/url/url_domaintoascii_domain.md similarity index 100% rename from api-docs/cbb48120acbfd4a030217df775fb9d326aa6783fa5c8efa2c2b576d36139737c.md rename to url/url_domaintoascii_domain.md diff --git a/api-docs/95939cff9f9952f0d809d7e58e4cc6a2bff826ad42f7f84ef19dc2104059ab31.md b/url/url_domaintounicode_domain.md similarity index 100% rename from api-docs/95939cff9f9952f0d809d7e58e4cc6a2bff826ad42f7f84ef19dc2104059ab31.md rename to url/url_domaintounicode_domain.md diff --git a/api-docs/8c92e19751c02256b8eeb671424ac8c834f2a055ad221ca9d2c32781390060d3.md b/url/url_fileurltopath_url.md similarity index 100% rename from api-docs/8c92e19751c02256b8eeb671424ac8c834f2a055ad221ca9d2c32781390060d3.md rename to url/url_fileurltopath_url.md diff --git a/api-docs/28bcca511e2181b16f1eaa1449ad6dff92ed4d389a22b5222502df203f65392d.md b/url/url_format_url_options.md similarity index 100% rename from api-docs/28bcca511e2181b16f1eaa1449ad6dff92ed4d389a22b5222502df203f65392d.md rename to url/url_format_url_options.md diff --git a/api-docs/182e19fd45f49da5b168896e287bcbaf66055acb5e56b802fc40ff344a1a45c6.md b/url/url_format_urlobject.md similarity index 100% rename from api-docs/182e19fd45f49da5b168896e287bcbaf66055acb5e56b802fc40ff344a1a45c6.md rename to url/url_format_urlobject.md diff --git a/api-docs/c4878106383f041b3756b79dd848e80c81da006a35812d417b319d0f5a36eeef.md b/url/url_hash.md similarity index 100% rename from api-docs/c4878106383f041b3756b79dd848e80c81da006a35812d417b319d0f5a36eeef.md rename to url/url_hash.md diff --git a/api-docs/44c8de19381952f5a1eb69143cf56d66646d54bf8269ebabcd0fb31b4f05ae74.md b/url/url_host.md similarity index 100% rename from api-docs/44c8de19381952f5a1eb69143cf56d66646d54bf8269ebabcd0fb31b4f05ae74.md rename to url/url_host.md diff --git a/api-docs/19e9a2962700d7caa0790918428e1432f75cbfebe0635adf515fed7435c5568a.md b/url/url_hostname.md similarity index 100% rename from api-docs/19e9a2962700d7caa0790918428e1432f75cbfebe0635adf515fed7435c5568a.md rename to url/url_hostname.md diff --git a/api-docs/665031e50b457aab6d3c3bd894b0ea6c2a93fec04a4527a9898b78af991ca52f.md b/url/url_href.md similarity index 100% rename from api-docs/665031e50b457aab6d3c3bd894b0ea6c2a93fec04a4527a9898b78af991ca52f.md rename to url/url_href.md diff --git a/api-docs/ad4586dfb39a31201b2c63b54030a11944383c1c97fde08e3cbcefe5674209a3.md b/url/url_origin.md similarity index 100% rename from api-docs/ad4586dfb39a31201b2c63b54030a11944383c1c97fde08e3cbcefe5674209a3.md rename to url/url_origin.md diff --git a/api-docs/c292139e888190d5f36ef160214f4f8d6ae4aa83b28af5a4fd9dcd6cd46e4433.md b/url/url_parse_urlstring_parsequerystring_slashesdenotehost.md similarity index 100% rename from api-docs/c292139e888190d5f36ef160214f4f8d6ae4aa83b28af5a4fd9dcd6cd46e4433.md rename to url/url_parse_urlstring_parsequerystring_slashesdenotehost.md diff --git a/api-docs/85ff3bc9c63c76ba6b81562392b5867b43e962768208f6df109bb1fd0ea13273.md b/url/url_password.md similarity index 100% rename from api-docs/85ff3bc9c63c76ba6b81562392b5867b43e962768208f6df109bb1fd0ea13273.md rename to url/url_password.md diff --git a/api-docs/951801ec1eed5fd8b0bad95bd18ac8e31b5e3256e2a294bf9c787970ffd6c6a8.md b/url/url_pathname.md similarity index 100% rename from api-docs/951801ec1eed5fd8b0bad95bd18ac8e31b5e3256e2a294bf9c787970ffd6c6a8.md rename to url/url_pathname.md diff --git a/api-docs/3d25f291ca46f4de33212f37b84fe4cb00f8dd5695e21b9f7822e1ff73e0d571.md b/url/url_pathtofileurl_path.md similarity index 100% rename from api-docs/3d25f291ca46f4de33212f37b84fe4cb00f8dd5695e21b9f7822e1ff73e0d571.md rename to url/url_pathtofileurl_path.md diff --git a/api-docs/a6a862b01ccb2b5f790eb9543aafef6275d1bcb34cc1ef080795b144734097db.md b/url/url_port.md similarity index 100% rename from api-docs/a6a862b01ccb2b5f790eb9543aafef6275d1bcb34cc1ef080795b144734097db.md rename to url/url_port.md diff --git a/api-docs/f449f886a8dee5720fd06b1b14d28637e9dddcb09cef72c878e8443e73f663d4.md b/url/url_protocol.md similarity index 100% rename from api-docs/f449f886a8dee5720fd06b1b14d28637e9dddcb09cef72c878e8443e73f663d4.md rename to url/url_protocol.md diff --git a/api-docs/2a4e777f30902381b02c08f8cfd0f0ceeef3e4e5ccc4bc22a9e4ce91aad00426.md b/url/url_resolve_from_to.md similarity index 100% rename from api-docs/2a4e777f30902381b02c08f8cfd0f0ceeef3e4e5ccc4bc22a9e4ce91aad00426.md rename to url/url_resolve_from_to.md diff --git a/api-docs/50db51d826e913941d6783c471ed94533358bd33df77c9f6b2b4a5c25ccda061.md b/url/url_search.md similarity index 100% rename from api-docs/50db51d826e913941d6783c471ed94533358bd33df77c9f6b2b4a5c25ccda061.md rename to url/url_search.md diff --git a/api-docs/15e5f3a831073ed80cda59c5973f576d96d44a2a0770c331ed0bc14729d946ea.md b/url/url_searchparams.md similarity index 100% rename from api-docs/15e5f3a831073ed80cda59c5973f576d96d44a2a0770c331ed0bc14729d946ea.md rename to url/url_searchparams.md diff --git a/api-docs/2d6f3f3d180de0d86602fbd8c08a3df69f24c4fdc1dd79f7c2f12ab8ae24a143.md b/url/url_strings_and_url_objects.md similarity index 100% rename from api-docs/2d6f3f3d180de0d86602fbd8c08a3df69f24c4fdc1dd79f7c2f12ab8ae24a143.md rename to url/url_strings_and_url_objects.md diff --git a/api-docs/5ecadafcf7af8a0aff9b733aaf0c24360157e996f49246edd5351de8460519e6.md b/url/url_tojson.md similarity index 100% rename from api-docs/5ecadafcf7af8a0aff9b733aaf0c24360157e996f49246edd5351de8460519e6.md rename to url/url_tojson.md diff --git a/api-docs/792cf961b4a46f0d11b6f82f75c794444e2f83a676b3e38301bd2217d4efb49f.md b/url/url_tostring.md similarity index 100% rename from api-docs/792cf961b4a46f0d11b6f82f75c794444e2f83a676b3e38301bd2217d4efb49f.md rename to url/url_tostring.md diff --git a/api-docs/e0ffddffe6b9adb68d623f0901cb1ddf9364f53841945ae6e75fe72a691642a5.md b/url/url_username.md similarity index 100% rename from api-docs/e0ffddffe6b9adb68d623f0901cb1ddf9364f53841945ae6e75fe72a691642a5.md rename to url/url_username.md diff --git a/api-docs/e96e0a034abc69a2bed9838ac55252f478557833c9f20cf76a4355595a4271bf.md b/url/urlobject_auth.md similarity index 100% rename from api-docs/e96e0a034abc69a2bed9838ac55252f478557833c9f20cf76a4355595a4271bf.md rename to url/urlobject_auth.md diff --git a/api-docs/14d87917bfe546e89aa8d2d1e16348bfd460475bf4ab500522f49fe650d11e18.md b/url/urlobject_hash.md similarity index 100% rename from api-docs/14d87917bfe546e89aa8d2d1e16348bfd460475bf4ab500522f49fe650d11e18.md rename to url/urlobject_hash.md diff --git a/api-docs/1cbdbd99eae15470b9768e1b9fd57830d00c1f9fafcde79edf2a6c3911c1b030.md b/url/urlobject_host.md similarity index 100% rename from api-docs/1cbdbd99eae15470b9768e1b9fd57830d00c1f9fafcde79edf2a6c3911c1b030.md rename to url/urlobject_host.md diff --git a/api-docs/4fe37877eb3229212bb0f1b91bf96f4eb584232cd924f260babfa5bb475511cb.md b/url/urlobject_hostname.md similarity index 100% rename from api-docs/4fe37877eb3229212bb0f1b91bf96f4eb584232cd924f260babfa5bb475511cb.md rename to url/urlobject_hostname.md diff --git a/api-docs/060467e4196c5e4b8771e9cfa91eebfef5f73e07659995d6ef7081cb5a2389bb.md b/url/urlobject_href.md similarity index 100% rename from api-docs/060467e4196c5e4b8771e9cfa91eebfef5f73e07659995d6ef7081cb5a2389bb.md rename to url/urlobject_href.md diff --git a/api-docs/f7edd607e2e0e9f5ab92c4a9c9ff4b1c678bdb337e3029e88d23a6f1ff69cce7.md b/url/urlobject_path.md similarity index 100% rename from api-docs/f7edd607e2e0e9f5ab92c4a9c9ff4b1c678bdb337e3029e88d23a6f1ff69cce7.md rename to url/urlobject_path.md diff --git a/api-docs/96add5b71ef27ffd5d195bd4241ea7cd22916a0f6583635de30ed02327f57970.md b/url/urlobject_pathname.md similarity index 100% rename from api-docs/96add5b71ef27ffd5d195bd4241ea7cd22916a0f6583635de30ed02327f57970.md rename to url/urlobject_pathname.md diff --git a/api-docs/9e526e95dbbdaaf914e6f35441855a5e2256be7ad844d89e23c677a00fa322de.md b/url/urlobject_port.md similarity index 100% rename from api-docs/9e526e95dbbdaaf914e6f35441855a5e2256be7ad844d89e23c677a00fa322de.md rename to url/urlobject_port.md diff --git a/api-docs/0a28ba50067f4f81281a560326f3630944f6f833c24bc92c4fc8aff2cbd3e82d.md b/url/urlobject_protocol.md similarity index 100% rename from api-docs/0a28ba50067f4f81281a560326f3630944f6f833c24bc92c4fc8aff2cbd3e82d.md rename to url/urlobject_protocol.md diff --git a/api-docs/3f53ed25686eb997a20074bf89fb642c96df2c4c19145fe927572031c130b219.md b/url/urlobject_query.md similarity index 100% rename from api-docs/3f53ed25686eb997a20074bf89fb642c96df2c4c19145fe927572031c130b219.md rename to url/urlobject_query.md diff --git a/api-docs/8bd5b49ef182b5e5dc9cd7eb2c6a9a47b2df4d723db7ffa11e630deb8d1c154d.md b/url/urlobject_search.md similarity index 100% rename from api-docs/8bd5b49ef182b5e5dc9cd7eb2c6a9a47b2df4d723db7ffa11e630deb8d1c154d.md rename to url/urlobject_search.md diff --git a/api-docs/699768a6e3d6fe237e1e9d9052f6b0f2220b31f91d08e95595648297dbb3de21.md b/url/urlobject_slashes.md similarity index 100% rename from api-docs/699768a6e3d6fe237e1e9d9052f6b0f2220b31f91d08e95595648297dbb3de21.md rename to url/urlobject_slashes.md diff --git a/api-docs/77d2c26c77383b6509b645c8a7e211af8e27bf2e4e88350eb783319a026690be.md b/url/urlsearchparams_append_name_value.md similarity index 100% rename from api-docs/77d2c26c77383b6509b645c8a7e211af8e27bf2e4e88350eb783319a026690be.md rename to url/urlsearchparams_append_name_value.md diff --git a/api-docs/33ada5fccf6d3a37cf0c73028b333d9270a4d42be9c4a13e03738bbd3602fb2e.md b/url/urlsearchparams_delete_name.md similarity index 100% rename from api-docs/33ada5fccf6d3a37cf0c73028b333d9270a4d42be9c4a13e03738bbd3602fb2e.md rename to url/urlsearchparams_delete_name.md diff --git a/api-docs/278634561f076bed166a2775ac9eb8cd7ef598aeb55a2e7f279cd2941b7ae31a.md b/url/urlsearchparams_entries.md similarity index 100% rename from api-docs/278634561f076bed166a2775ac9eb8cd7ef598aeb55a2e7f279cd2941b7ae31a.md rename to url/urlsearchparams_entries.md diff --git a/api-docs/fb9c80ba7f57da11a448979e3fd7cdb4460b2ca4239093dac2557e17a25495a9.md b/url/urlsearchparams_foreach_fn_thisarg.md similarity index 100% rename from api-docs/fb9c80ba7f57da11a448979e3fd7cdb4460b2ca4239093dac2557e17a25495a9.md rename to url/urlsearchparams_foreach_fn_thisarg.md diff --git a/api-docs/b50a69f092ed0fbefca34e9a733279d6a1802aa5677895cbb07ed3c05521e764.md b/url/urlsearchparams_get_name.md similarity index 100% rename from api-docs/b50a69f092ed0fbefca34e9a733279d6a1802aa5677895cbb07ed3c05521e764.md rename to url/urlsearchparams_get_name.md diff --git a/api-docs/d44f54ee1ed07fb3b299ad75bee4d3b5d2b6b52660dee7b68d849cc384375fd1.md b/url/urlsearchparams_getall_name.md similarity index 100% rename from api-docs/d44f54ee1ed07fb3b299ad75bee4d3b5d2b6b52660dee7b68d849cc384375fd1.md rename to url/urlsearchparams_getall_name.md diff --git a/api-docs/4392a678fde566c9b36e5b6a24a5624179123b7f7c7027dcc7daea80be1dcea4.md b/url/urlsearchparams_has_name.md similarity index 100% rename from api-docs/4392a678fde566c9b36e5b6a24a5624179123b7f7c7027dcc7daea80be1dcea4.md rename to url/urlsearchparams_has_name.md diff --git a/api-docs/593544317fb2051cb731c604a836a9c9eb894ef7bc8eb17552f04e2fb5f2f767.md b/url/urlsearchparams_keys.md similarity index 100% rename from api-docs/593544317fb2051cb731c604a836a9c9eb894ef7bc8eb17552f04e2fb5f2f767.md rename to url/urlsearchparams_keys.md diff --git a/api-docs/4ba42f052ef924a95c60819dd6d49ae1a6b25e7050953ee2fea1ab11841cc4ce.md b/url/urlsearchparams_set_name_value.md similarity index 100% rename from api-docs/4ba42f052ef924a95c60819dd6d49ae1a6b25e7050953ee2fea1ab11841cc4ce.md rename to url/urlsearchparams_set_name_value.md diff --git a/api-docs/e133730d9e0a75f34a45c4a17d5670e703e13763306628ddebfc537f9f11829e.md b/url/urlsearchparams_sort.md similarity index 100% rename from api-docs/e133730d9e0a75f34a45c4a17d5670e703e13763306628ddebfc537f9f11829e.md rename to url/urlsearchparams_sort.md diff --git a/api-docs/e7aa21c7cba96cb009d34cd9ab462a78981f55552fa3ae1ae2eb78e302b8792a.md b/url/urlsearchparams_symbol_iterator.md similarity index 100% rename from api-docs/e7aa21c7cba96cb009d34cd9ab462a78981f55552fa3ae1ae2eb78e302b8792a.md rename to url/urlsearchparams_symbol_iterator.md diff --git a/api-docs/8156968e38395c6da020c56e6bcf96be3fcb04414fe070058281c9d4f767d11b.md b/url/urlsearchparams_tostring.md similarity index 100% rename from api-docs/8156968e38395c6da020c56e6bcf96be3fcb04414fe070058281c9d4f767d11b.md rename to url/urlsearchparams_tostring.md diff --git a/api-docs/bf8fe0cffcc158ee8525a3c09e21610e1fcf2e8ff0e2b66d3f85a4af1a4a1532.md b/url/urlsearchparams_values.md similarity index 100% rename from api-docs/bf8fe0cffcc158ee8525a3c09e21610e1fcf2e8ff0e2b66d3f85a4af1a4a1532.md rename to url/urlsearchparams_values.md diff --git a/api-docs/78833a8be4c48d5d58307670b257edda2a8697dbd76d815e873d7122bba2378c.md b/url/whatwg_api.md similarity index 100% rename from api-docs/78833a8be4c48d5d58307670b257edda2a8697dbd76d815e873d7122bba2378c.md rename to url/whatwg_api.md diff --git a/api-docs/a976fa22d1c8cced8a4173368d78f3f882b487960e01d2b4f0baf83a4f38db4b.md b/util/class_util_textdecoder.md similarity index 100% rename from api-docs/a976fa22d1c8cced8a4173368d78f3f882b487960e01d2b4f0baf83a4f38db4b.md rename to util/class_util_textdecoder.md diff --git a/api-docs/ee43637b1addaa194afd29a983d4b0fb11135da10909dfc702171dee5647844d.md b/util/class_util_textencoder.md similarity index 100% rename from api-docs/ee43637b1addaa194afd29a983d4b0fb11135da10909dfc702171dee5647844d.md rename to util/class_util_textencoder.md diff --git a/api-docs/063fe6d07ffcc15dfacb46a74de0c89a996f173019cdf73c361604a9c733820c.md b/util/custom_inspection_functions_on_objects.md similarity index 100% rename from api-docs/063fe6d07ffcc15dfacb46a74de0c89a996f173019cdf73c361604a9c733820c.md rename to util/custom_inspection_functions_on_objects.md diff --git a/api-docs/851ac632b5712f9f594d96895dd5fe779f5d992b2eaa45843b12f7bed0db4828.md b/util/custom_promisified_functions.md similarity index 100% rename from api-docs/851ac632b5712f9f594d96895dd5fe779f5d992b2eaa45843b12f7bed0db4828.md rename to util/custom_promisified_functions.md diff --git a/api-docs/86a5a9274f8276b7fc96fab5d13354d688fa41c87dafc0d28511884084eab6eb.md b/util/customizing_util_inspect_colors.md similarity index 100% rename from api-docs/86a5a9274f8276b7fc96fab5d13354d688fa41c87dafc0d28511884084eab6eb.md rename to util/customizing_util_inspect_colors.md diff --git a/api-docs/c7df240b30c88460f0e623cf3d1c8fcf0512d6eea2f3fdc1ebd765d9e3c7f125.md b/util/deprecated_apis.md similarity index 100% rename from api-docs/c7df240b30c88460f0e623cf3d1c8fcf0512d6eea2f3fdc1ebd765d9e3c7f125.md rename to util/deprecated_apis.md diff --git a/api-docs/146bc50fbbfc9fe4c198916081cd9bc7c816260f93601f0dc2ddf18ba8886ff6.md b/util/encodings_requiring_full_icu_data.md similarity index 100% rename from api-docs/146bc50fbbfc9fe4c198916081cd9bc7c816260f93601f0dc2ddf18ba8886ff6.md rename to util/encodings_requiring_full_icu_data.md diff --git a/api-docs/d75cbf0fa70aadab6cd9bfe028aa24428eac42cfa8250ccd7261d85332d86297.md b/util/encodings_supported_by_default_with_icu.md similarity index 100% rename from api-docs/d75cbf0fa70aadab6cd9bfe028aa24428eac42cfa8250ccd7261d85332d86297.md rename to util/encodings_supported_by_default_with_icu.md diff --git a/api-docs/ffa9c18ba337f0e539a100a700f02e3cd4eb673ff65752f335efed5f7b742296.md b/util/encodings_supported_without_icu.md similarity index 100% rename from api-docs/ffa9c18ba337f0e539a100a700f02e3cd4eb673ff65752f335efed5f7b742296.md rename to util/encodings_supported_without_icu.md diff --git a/api-docs/bdf68f7c0610c4bed55c69fd18ef372d3a20c709391f5540db1293d30b1a4fbf.md b/util/new_textdecoder_encoding_options.md similarity index 100% rename from api-docs/bdf68f7c0610c4bed55c69fd18ef372d3a20c709391f5540db1293d30b1a4fbf.md rename to util/new_textdecoder_encoding_options.md diff --git a/api-docs/e9d2ab8bb06d1316fe76df647838ee1ec0fa38e1a007b16fc2192e707f7d1446.md b/util/textdecoder_decode_input_options.md similarity index 100% rename from api-docs/e9d2ab8bb06d1316fe76df647838ee1ec0fa38e1a007b16fc2192e707f7d1446.md rename to util/textdecoder_decode_input_options.md diff --git a/api-docs/c53fdb76de2c95668b5bb4d53465e43f6a92397e7c88d8768a3af9a38338dc97.md b/util/textdecoder_encoding.md similarity index 100% rename from api-docs/c53fdb76de2c95668b5bb4d53465e43f6a92397e7c88d8768a3af9a38338dc97.md rename to util/textdecoder_encoding.md diff --git a/api-docs/cee3081b2e8d9345218d1026cc70afd354309a3690df6afa2f34f0e82bccc4d0.md b/util/textdecoder_fatal.md similarity index 100% rename from api-docs/cee3081b2e8d9345218d1026cc70afd354309a3690df6afa2f34f0e82bccc4d0.md rename to util/textdecoder_fatal.md diff --git a/api-docs/2c228a07a5f924ca771f85c1f76ed33ec689207fce1dbec6328e526e1da2cc54.md b/util/textdecoder_ignorebom.md similarity index 100% rename from api-docs/2c228a07a5f924ca771f85c1f76ed33ec689207fce1dbec6328e526e1da2cc54.md rename to util/textdecoder_ignorebom.md diff --git a/api-docs/66ca7eaa13c80a3727c6a53ead3851420332bc3846aa3b0a6158f7695a5e4c51.md b/util/textencoder_encode_input.md similarity index 100% rename from api-docs/66ca7eaa13c80a3727c6a53ead3851420332bc3846aa3b0a6158f7695a5e4c51.md rename to util/textencoder_encode_input.md diff --git a/api-docs/f25c31cfda4d8f64aeaa0826cf5c927f20fefe9f57827bde126c6f47a03cad92.md b/util/textencoder_encoding.md similarity index 100% rename from api-docs/f25c31cfda4d8f64aeaa0826cf5c927f20fefe9f57827bde126c6f47a03cad92.md rename to util/textencoder_encoding.md diff --git a/api-docs/1a504cb478312553ea7edbe8e4b966b7f237fef1279aa07975a7fff57e81b623.md b/util/util.md similarity index 100% rename from api-docs/1a504cb478312553ea7edbe8e4b966b7f237fef1279aa07975a7fff57e81b623.md rename to util/util.md diff --git a/api-docs/023dfcc89a5894d4383903d68e7ee16b2ff6f51940384b6a188ffb8242645a42.md b/util/util_callbackify_original.md similarity index 100% rename from api-docs/023dfcc89a5894d4383903d68e7ee16b2ff6f51940384b6a188ffb8242645a42.md rename to util/util_callbackify_original.md diff --git a/util/util_debug_string.md b/util/util_debug_string.md new file mode 100644 index 00000000..f099ed1c --- /dev/null +++ b/util/util_debug_string.md @@ -0,0 +1,11 @@ + + +> Stability: 0 - Deprecated: Use [`console.error()`][] instead. + +* `string` {string} The message to print to `stderr` + +Deprecated predecessor of `console.error`. + diff --git a/api-docs/148bed88c9e1102b26f27a57450b777fa0f4d7e33cb3c68925b4a44efc731fef.md b/util/util_debuglog_section.md similarity index 100% rename from api-docs/148bed88c9e1102b26f27a57450b777fa0f4d7e33cb3c68925b4a44efc731fef.md rename to util/util_debuglog_section.md diff --git a/api-docs/05a227f0e9e1489ba9c6ad73cb85da4b02d82455e2f822864e418d4b40f014b5.md b/util/util_deprecate_fn_msg_code.md similarity index 100% rename from api-docs/05a227f0e9e1489ba9c6ad73cb85da4b02d82455e2f822864e418d4b40f014b5.md rename to util/util_deprecate_fn_msg_code.md diff --git a/util/util_error_strings.md b/util/util_error_strings.md new file mode 100644 index 00000000..60108992 --- /dev/null +++ b/util/util_error_strings.md @@ -0,0 +1,11 @@ + + +> Stability: 0 - Deprecated: Use [`console.error()`][] instead. + +* `...strings` {string} The message to print to `stderr` + +Deprecated predecessor of `console.error`. + diff --git a/util/util_extend_target_source.md b/util/util_extend_target_source.md new file mode 100644 index 00000000..8f073a47 --- /dev/null +++ b/util/util_extend_target_source.md @@ -0,0 +1,15 @@ + +* `target` {Object} +* `source` {Object} + +> Stability: 0 - Deprecated: Use [`Object.assign()`] instead. + +The `util._extend()` method was never intended to be used outside of internal +Node.js modules. The community found and used it anyway. + +It is deprecated and should not be used in new code. JavaScript comes with very +similar built-in functionality through [`Object.assign()`]. + diff --git a/api-docs/29bc80cc6b583aa9ffdb4aed1cc2ad937cc33f26a34bde279ffa6356ec7be453.md b/util/util_format_format_args.md similarity index 100% rename from api-docs/29bc80cc6b583aa9ffdb4aed1cc2ad937cc33f26a34bde279ffa6356ec7be453.md rename to util/util_format_format_args.md diff --git a/api-docs/6052a34f8d7d97b465216a46a9553cba1eccf2113a0a3dd99a6ecde4d172b258.md b/util/util_formatwithoptions_inspectoptions_format_args.md similarity index 100% rename from api-docs/6052a34f8d7d97b465216a46a9553cba1eccf2113a0a3dd99a6ecde4d172b258.md rename to util/util_formatwithoptions_inspectoptions_format_args.md diff --git a/api-docs/15b8dae01fd32bef9258cd5932ae4f99b3a242901e6238fc1026cf3730bc810d.md b/util/util_getsystemerrorname_err.md similarity index 100% rename from api-docs/15b8dae01fd32bef9258cd5932ae4f99b3a242901e6238fc1026cf3730bc810d.md rename to util/util_getsystemerrorname_err.md diff --git a/api-docs/d3b6c09218f8fbf5c41b9ef63591c3d896f3c98d4748645b0424b3f1e7f729cc.md b/util/util_inherits_constructor_superconstructor.md similarity index 100% rename from api-docs/d3b6c09218f8fbf5c41b9ef63591c3d896f3c98d4748645b0424b3f1e7f729cc.md rename to util/util_inherits_constructor_superconstructor.md diff --git a/api-docs/e20c7e6f7340e3d8aeddfe6a8ffa5865e0137db7347c149bf7f962b9d2757188.md b/util/util_inspect_custom.md similarity index 100% rename from api-docs/e20c7e6f7340e3d8aeddfe6a8ffa5865e0137db7347c149bf7f962b9d2757188.md rename to util/util_inspect_custom.md diff --git a/api-docs/d7c8236633842574518de3138256e1fd19519cebac361e184524ead338b2262a.md b/util/util_inspect_defaultoptions.md similarity index 100% rename from api-docs/d7c8236633842574518de3138256e1fd19519cebac361e184524ead338b2262a.md rename to util/util_inspect_defaultoptions.md diff --git a/util/util_inspect_object_options.md b/util/util_inspect_object_options.md new file mode 100644 index 00000000..e69de29b diff --git a/api-docs/58106c2f6334b68ea39fc223b09dc7986e2b186475598bcc6bf32f06428f5b12.md b/util/util_inspect_object_showhidden_depth_colors.md similarity index 100% rename from api-docs/58106c2f6334b68ea39fc223b09dc7986e2b186475598bcc6bf32f06428f5b12.md rename to util/util_inspect_object_showhidden_depth_colors.md diff --git a/util/util_isarray_object.md b/util/util_isarray_object.md new file mode 100644 index 00000000..0972e497 --- /dev/null +++ b/util/util_isarray_object.md @@ -0,0 +1,25 @@ + + +> Stability: 0 - Deprecated: Use [`Array.isArray()`][] instead. + +* `object` {any} +* Returns: {boolean} + +Alias for [`Array.isArray()`][]. + +Returns `true` if the given `object` is an `Array`. Otherwise, returns `false`. + +```js +const util = require('util'); + +util.isArray([]); +// Returns: true +util.isArray(new Array()); +// Returns: true +util.isArray({}); +// Returns: false +``` + diff --git a/util/util_isboolean_object.md b/util/util_isboolean_object.md new file mode 100644 index 00000000..d14ffb87 --- /dev/null +++ b/util/util_isboolean_object.md @@ -0,0 +1,23 @@ + + +> Stability: 0 - Deprecated: Use `typeof value === 'boolean'` instead. + +* `object` {any} +* Returns: {boolean} + +Returns `true` if the given `object` is a `Boolean`. Otherwise, returns `false`. + +```js +const util = require('util'); + +util.isBoolean(1); +// Returns: false +util.isBoolean(0); +// Returns: false +util.isBoolean(false); +// Returns: true +``` + diff --git a/util/util_isbuffer_object.md b/util/util_isbuffer_object.md new file mode 100644 index 00000000..f0672873 --- /dev/null +++ b/util/util_isbuffer_object.md @@ -0,0 +1,23 @@ + + +> Stability: 0 - Deprecated: Use [`Buffer.isBuffer()`][] instead. + +* `object` {any} +* Returns: {boolean} + +Returns `true` if the given `object` is a `Buffer`. Otherwise, returns `false`. + +```js +const util = require('util'); + +util.isBuffer({ length: 0 }); +// Returns: false +util.isBuffer([]); +// Returns: false +util.isBuffer(Buffer.from('hello world')); +// Returns: true +``` + diff --git a/util/util_isdate_object.md b/util/util_isdate_object.md new file mode 100644 index 00000000..fb02bf80 --- /dev/null +++ b/util/util_isdate_object.md @@ -0,0 +1,23 @@ + + +> Stability: 0 - Deprecated: Use [`util.types.isDate()`][] instead. + +* `object` {any} +* Returns: {boolean} + +Returns `true` if the given `object` is a `Date`. Otherwise, returns `false`. + +```js +const util = require('util'); + +util.isDate(new Date()); +// Returns: true +util.isDate(Date()); +// false (without 'new' returns a String) +util.isDate({}); +// Returns: false +``` + diff --git a/api-docs/5e90802f95d113c1f69810b65dfa62709602d8c5694fd54be63a248471416833.md b/util/util_isdeepstrictequal_val1_val2.md similarity index 100% rename from api-docs/5e90802f95d113c1f69810b65dfa62709602d8c5694fd54be63a248471416833.md rename to util/util_isdeepstrictequal_val1_val2.md diff --git a/util/util_iserror_object.md b/util/util_iserror_object.md new file mode 100644 index 00000000..0a621f2d --- /dev/null +++ b/util/util_iserror_object.md @@ -0,0 +1,39 @@ + + +> Stability: 0 - Deprecated: Use [`util.types.isNativeError()`][] instead. + +* `object` {any} +* Returns: {boolean} + +Returns `true` if the given `object` is an [`Error`][]. Otherwise, returns +`false`. + +```js +const util = require('util'); + +util.isError(new Error()); +// Returns: true +util.isError(new TypeError()); +// Returns: true +util.isError({ name: 'Error', message: 'an error occurred' }); +// Returns: false +``` + +Note that this method relies on `Object.prototype.toString()` behavior. It is +possible to obtain an incorrect result when the `object` argument manipulates +`@@toStringTag`. + +```js +const util = require('util'); +const obj = { name: 'Error', message: 'an error occurred' }; + +util.isError(obj); +// Returns: false +obj[Symbol.toStringTag] = 'Error'; +util.isError(obj); +// Returns: true +``` + diff --git a/util/util_isfunction_object.md b/util/util_isfunction_object.md new file mode 100644 index 00000000..5633a9a5 --- /dev/null +++ b/util/util_isfunction_object.md @@ -0,0 +1,27 @@ + + +> Stability: 0 - Deprecated: Use `typeof value === 'function'` instead. + +* `object` {any} +* Returns: {boolean} + +Returns `true` if the given `object` is a `Function`. Otherwise, returns +`false`. + +```js +const util = require('util'); + +function Foo() {} +const Bar = () => {}; + +util.isFunction({}); +// Returns: false +util.isFunction(Foo); +// Returns: true +util.isFunction(Bar); +// Returns: true +``` + diff --git a/util/util_isnull_object.md b/util/util_isnull_object.md new file mode 100644 index 00000000..810dd99b --- /dev/null +++ b/util/util_isnull_object.md @@ -0,0 +1,24 @@ + + +> Stability: 0 - Deprecated: Use `value === null` instead. + +* `object` {any} +* Returns: {boolean} + +Returns `true` if the given `object` is strictly `null`. Otherwise, returns +`false`. + +```js +const util = require('util'); + +util.isNull(0); +// Returns: false +util.isNull(undefined); +// Returns: false +util.isNull(null); +// Returns: true +``` + diff --git a/util/util_isnullorundefined_object.md b/util/util_isnullorundefined_object.md new file mode 100644 index 00000000..fb936192 --- /dev/null +++ b/util/util_isnullorundefined_object.md @@ -0,0 +1,25 @@ + + +> Stability: 0 - Deprecated: Use +> `value === undefined || value === null` instead. + +* `object` {any} +* Returns: {boolean} + +Returns `true` if the given `object` is `null` or `undefined`. Otherwise, +returns `false`. + +```js +const util = require('util'); + +util.isNullOrUndefined(0); +// Returns: false +util.isNullOrUndefined(undefined); +// Returns: true +util.isNullOrUndefined(null); +// Returns: true +``` + diff --git a/util/util_isnumber_object.md b/util/util_isnumber_object.md new file mode 100644 index 00000000..a2fa21b1 --- /dev/null +++ b/util/util_isnumber_object.md @@ -0,0 +1,25 @@ + + +> Stability: 0 - Deprecated: Use `typeof value === 'number'` instead. + +* `object` {any} +* Returns: {boolean} + +Returns `true` if the given `object` is a `Number`. Otherwise, returns `false`. + +```js +const util = require('util'); + +util.isNumber(false); +// Returns: false +util.isNumber(Infinity); +// Returns: true +util.isNumber(0); +// Returns: true +util.isNumber(NaN); +// Returns: true +``` + diff --git a/util/util_isobject_object.md b/util/util_isobject_object.md new file mode 100644 index 00000000..108b41a4 --- /dev/null +++ b/util/util_isobject_object.md @@ -0,0 +1,28 @@ + + +> Stability: 0 - Deprecated: +> Use `value !== null && typeof value === 'object'` instead. + +* `object` {any} +* Returns: {boolean} + +Returns `true` if the given `object` is strictly an `Object` **and** not a +`Function` (even though functions are objects in JavaScript). +Otherwise, returns `false`. + +```js +const util = require('util'); + +util.isObject(5); +// Returns: false +util.isObject(null); +// Returns: false +util.isObject({}); +// Returns: true +util.isObject(() => {}); +// Returns: false +``` + diff --git a/util/util_isprimitive_object.md b/util/util_isprimitive_object.md new file mode 100644 index 00000000..2301e05d --- /dev/null +++ b/util/util_isprimitive_object.md @@ -0,0 +1,38 @@ + + +> Stability: 0 - Deprecated: Use +> `(typeof value !== 'object' && typeof value !== 'function') || value === null` +> instead. + +* `object` {any} +* Returns: {boolean} + +Returns `true` if the given `object` is a primitive type. Otherwise, returns +`false`. + +```js +const util = require('util'); + +util.isPrimitive(5); +// Returns: true +util.isPrimitive('foo'); +// Returns: true +util.isPrimitive(false); +// Returns: true +util.isPrimitive(null); +// Returns: true +util.isPrimitive(undefined); +// Returns: true +util.isPrimitive({}); +// Returns: false +util.isPrimitive(() => {}); +// Returns: false +util.isPrimitive(/^$/); +// Returns: false +util.isPrimitive(new Date()); +// Returns: false +``` + diff --git a/util/util_isregexp_object.md b/util/util_isregexp_object.md new file mode 100644 index 00000000..5ff1449c --- /dev/null +++ b/util/util_isregexp_object.md @@ -0,0 +1,23 @@ + + +> Stability: 0 - Deprecated + +* `object` {any} +* Returns: {boolean} + +Returns `true` if the given `object` is a `RegExp`. Otherwise, returns `false`. + +```js +const util = require('util'); + +util.isRegExp(/some regexp/); +// Returns: true +util.isRegExp(new RegExp('another regexp')); +// Returns: true +util.isRegExp({}); +// Returns: false +``` + diff --git a/util/util_isstring_object.md b/util/util_isstring_object.md new file mode 100644 index 00000000..7afcbbfb --- /dev/null +++ b/util/util_isstring_object.md @@ -0,0 +1,25 @@ + + +> Stability: 0 - Deprecated: Use `typeof value === 'string'` instead. + +* `object` {any} +* Returns: {boolean} + +Returns `true` if the given `object` is a `string`. Otherwise, returns `false`. + +```js +const util = require('util'); + +util.isString(''); +// Returns: true +util.isString('foo'); +// Returns: true +util.isString(String('foo')); +// Returns: true +util.isString(5); +// Returns: false +``` + diff --git a/util/util_issymbol_object.md b/util/util_issymbol_object.md new file mode 100644 index 00000000..a252d08e --- /dev/null +++ b/util/util_issymbol_object.md @@ -0,0 +1,23 @@ + + +> Stability: 0 - Deprecated: Use `typeof value === 'symbol'` instead. + +* `object` {any} +* Returns: {boolean} + +Returns `true` if the given `object` is a `Symbol`. Otherwise, returns `false`. + +```js +const util = require('util'); + +util.isSymbol(5); +// Returns: false +util.isSymbol('foo'); +// Returns: false +util.isSymbol(Symbol('foo')); +// Returns: true +``` + diff --git a/util/util_isundefined_object.md b/util/util_isundefined_object.md new file mode 100644 index 00000000..f5cb196f --- /dev/null +++ b/util/util_isundefined_object.md @@ -0,0 +1,24 @@ + + +> Stability: 0 - Deprecated: Use `value === undefined` instead. + +* `object` {any} +* Returns: {boolean} + +Returns `true` if the given `object` is `undefined`. Otherwise, returns `false`. + +```js +const util = require('util'); + +const foo = undefined; +util.isUndefined(5); +// Returns: false +util.isUndefined(foo); +// Returns: true +util.isUndefined(null); +// Returns: false +``` + diff --git a/util/util_log_string.md b/util/util_log_string.md new file mode 100644 index 00000000..1929467e --- /dev/null +++ b/util/util_log_string.md @@ -0,0 +1,18 @@ + + +> Stability: 0 - Deprecated: Use a third party module instead. + +* `string` {string} + +The `util.log()` method prints the given `string` to `stdout` with an included +timestamp. + +```js +const util = require('util'); + +util.log('Timestamped message.'); +``` + diff --git a/util/util_print_strings.md b/util/util_print_strings.md new file mode 100644 index 00000000..e3447784 --- /dev/null +++ b/util/util_print_strings.md @@ -0,0 +1,9 @@ + + +> Stability: 0 - Deprecated: Use [`console.log()`][] instead. + +Deprecated predecessor of `console.log`. + diff --git a/api-docs/45d26744ba35f1a5004f55d1c1b2686e43335ddea8c3947079ce94889aa05e96.md b/util/util_promisify_custom.md similarity index 100% rename from api-docs/45d26744ba35f1a5004f55d1c1b2686e43335ddea8c3947079ce94889aa05e96.md rename to util/util_promisify_custom.md diff --git a/api-docs/b736add93423ca49415021ee533fa343cfe0b9e75cbd3b7b726ee353b10a7009.md b/util/util_promisify_original.md similarity index 100% rename from api-docs/b736add93423ca49415021ee533fa343cfe0b9e75cbd3b7b726ee353b10a7009.md rename to util/util_promisify_original.md diff --git a/api-docs/1d69362b8a9c36dff0dbb66529132c0d2850c4b9fbb32bcd39defce21e142e90.md b/util/util_puts_strings.md similarity index 100% rename from api-docs/1d69362b8a9c36dff0dbb66529132c0d2850c4b9fbb32bcd39defce21e142e90.md rename to util/util_puts_strings.md diff --git a/api-docs/bb0596a5a393e0324e891f94b4110c89cece254707c58889b5dca07dc674fea4.md b/util/util_types.md similarity index 100% rename from api-docs/bb0596a5a393e0324e891f94b4110c89cece254707c58889b5dca07dc674fea4.md rename to util/util_types.md diff --git a/api-docs/6bbe0dea108aca4cdc342ceae457e20cb61f704aae2335ddb9c1acf3eee061e4.md b/util/util_types_isanyarraybuffer_value.md similarity index 100% rename from api-docs/6bbe0dea108aca4cdc342ceae457e20cb61f704aae2335ddb9c1acf3eee061e4.md rename to util/util_types_isanyarraybuffer_value.md diff --git a/api-docs/a09fbe9d387930e11736860ad8c7f295b8ff4e0c8fdeb59534194a7df44f0629.md b/util/util_types_isargumentsobject_value.md similarity index 100% rename from api-docs/a09fbe9d387930e11736860ad8c7f295b8ff4e0c8fdeb59534194a7df44f0629.md rename to util/util_types_isargumentsobject_value.md diff --git a/api-docs/6a90b2ad07e13415528f3adbc7cebd1888ca630e1dd7fcaa588bb3fefd93cd4f.md b/util/util_types_isarraybuffer_value.md similarity index 100% rename from api-docs/6a90b2ad07e13415528f3adbc7cebd1888ca630e1dd7fcaa588bb3fefd93cd4f.md rename to util/util_types_isarraybuffer_value.md diff --git a/api-docs/2f57f890f16ac485a2d73f27a204ca534763eaf2016077eae3ea32785808c5cc.md b/util/util_types_isasyncfunction_value.md similarity index 100% rename from api-docs/2f57f890f16ac485a2d73f27a204ca534763eaf2016077eae3ea32785808c5cc.md rename to util/util_types_isasyncfunction_value.md diff --git a/api-docs/ff14d1dfb2376ece2a5f81c3a288b33cd2f72522d48eca40a9105f857a5d66f2.md b/util/util_types_isbigint64array_value.md similarity index 100% rename from api-docs/ff14d1dfb2376ece2a5f81c3a288b33cd2f72522d48eca40a9105f857a5d66f2.md rename to util/util_types_isbigint64array_value.md diff --git a/api-docs/caf310fa39f9f001a9ee361ac94d02bac7aae1655b909c9e9ff3a8c1cddb8dc7.md b/util/util_types_isbiguint64array_value.md similarity index 100% rename from api-docs/caf310fa39f9f001a9ee361ac94d02bac7aae1655b909c9e9ff3a8c1cddb8dc7.md rename to util/util_types_isbiguint64array_value.md diff --git a/api-docs/bbb9d81c3b20cfb50583eeac7e0b19d8d74b37eb2fc4f028b972b7e84fb0e9d7.md b/util/util_types_isbooleanobject_value.md similarity index 100% rename from api-docs/bbb9d81c3b20cfb50583eeac7e0b19d8d74b37eb2fc4f028b972b7e84fb0e9d7.md rename to util/util_types_isbooleanobject_value.md diff --git a/api-docs/1ddc6a7b61aca27f395aef77cb9c5b5e69eb77eaa85cf2e446026c103c8bac4d.md b/util/util_types_isboxedprimitive_value.md similarity index 100% rename from api-docs/1ddc6a7b61aca27f395aef77cb9c5b5e69eb77eaa85cf2e446026c103c8bac4d.md rename to util/util_types_isboxedprimitive_value.md diff --git a/api-docs/c8bfae0dd8e2e617218d9b66b594bd323c9349100d3f2142e5d8402ca821583b.md b/util/util_types_isdataview_value.md similarity index 100% rename from api-docs/c8bfae0dd8e2e617218d9b66b594bd323c9349100d3f2142e5d8402ca821583b.md rename to util/util_types_isdataview_value.md diff --git a/api-docs/bca00eb54b238e332e0242faf3a510cc626110b6919df0b7925c7e08a542a280.md b/util/util_types_isdate_value.md similarity index 100% rename from api-docs/bca00eb54b238e332e0242faf3a510cc626110b6919df0b7925c7e08a542a280.md rename to util/util_types_isdate_value.md diff --git a/api-docs/9d5bbf0bff759a5acc7182e18c254f1a72196f0149cc9ec48bc3e0e1c6397f86.md b/util/util_types_isexternal_value.md similarity index 100% rename from api-docs/9d5bbf0bff759a5acc7182e18c254f1a72196f0149cc9ec48bc3e0e1c6397f86.md rename to util/util_types_isexternal_value.md diff --git a/api-docs/463eb39e45c729e74bfd64b33c01862a9bbc9573c9a6ef1ba08d639ca3d51b48.md b/util/util_types_isfloat32array_value.md similarity index 100% rename from api-docs/463eb39e45c729e74bfd64b33c01862a9bbc9573c9a6ef1ba08d639ca3d51b48.md rename to util/util_types_isfloat32array_value.md diff --git a/api-docs/ff6af44d053e796bd83c798c9c9157496f6eca04c49d4876303f7d92ec948f11.md b/util/util_types_isfloat64array_value.md similarity index 100% rename from api-docs/ff6af44d053e796bd83c798c9c9157496f6eca04c49d4876303f7d92ec948f11.md rename to util/util_types_isfloat64array_value.md diff --git a/api-docs/d11f5e3e077c3dc84ec427a90342bd2e3d2606b7d05681bb759f83901396309d.md b/util/util_types_isgeneratorfunction_value.md similarity index 100% rename from api-docs/d11f5e3e077c3dc84ec427a90342bd2e3d2606b7d05681bb759f83901396309d.md rename to util/util_types_isgeneratorfunction_value.md diff --git a/api-docs/8499086fdbec2a9aa246e50c42200bbe81fd121058c6704e6f006544079bd889.md b/util/util_types_isgeneratorobject_value.md similarity index 100% rename from api-docs/8499086fdbec2a9aa246e50c42200bbe81fd121058c6704e6f006544079bd889.md rename to util/util_types_isgeneratorobject_value.md diff --git a/api-docs/6a7da71f66ce635df5c631939ddc00d38cadf823d148093221a7cc1ab47ed45b.md b/util/util_types_isint16array_value.md similarity index 100% rename from api-docs/6a7da71f66ce635df5c631939ddc00d38cadf823d148093221a7cc1ab47ed45b.md rename to util/util_types_isint16array_value.md diff --git a/api-docs/fbf381dfc0cf7bebcb8363abd0cf684d14051e3f37f195797a1363da5b587781.md b/util/util_types_isint32array_value.md similarity index 100% rename from api-docs/fbf381dfc0cf7bebcb8363abd0cf684d14051e3f37f195797a1363da5b587781.md rename to util/util_types_isint32array_value.md diff --git a/api-docs/d6855328fd88c95940b2ce9597a0629e3c50d3e6050209acff437059947fae4a.md b/util/util_types_isint8array_value.md similarity index 100% rename from api-docs/d6855328fd88c95940b2ce9597a0629e3c50d3e6050209acff437059947fae4a.md rename to util/util_types_isint8array_value.md diff --git a/api-docs/5fdacd5d7e84bf2010a345a9c092ed7a545695569c0fa4194f29e80e73b8a81d.md b/util/util_types_ismap_value.md similarity index 100% rename from api-docs/5fdacd5d7e84bf2010a345a9c092ed7a545695569c0fa4194f29e80e73b8a81d.md rename to util/util_types_ismap_value.md diff --git a/api-docs/71828db2c7bddbcbeb17be4a4294c74685f00b3d4d3593fa4c94bb7831dd3559.md b/util/util_types_ismapiterator_value.md similarity index 100% rename from api-docs/71828db2c7bddbcbeb17be4a4294c74685f00b3d4d3593fa4c94bb7831dd3559.md rename to util/util_types_ismapiterator_value.md diff --git a/api-docs/f61e148caaa23a0dbcc11e0668b648d759dbb686656ffb2ef4a05b08cd7c3913.md b/util/util_types_ismodulenamespaceobject_value.md similarity index 100% rename from api-docs/f61e148caaa23a0dbcc11e0668b648d759dbb686656ffb2ef4a05b08cd7c3913.md rename to util/util_types_ismodulenamespaceobject_value.md diff --git a/api-docs/4e779419dae70cbad29e249f679788d784d4148f21fc48ef9f29bef2168ce7e0.md b/util/util_types_isnativeerror_value.md similarity index 100% rename from api-docs/4e779419dae70cbad29e249f679788d784d4148f21fc48ef9f29bef2168ce7e0.md rename to util/util_types_isnativeerror_value.md diff --git a/api-docs/d838be7f25347f60b80e19f3b88a6999ca96d313edc9d0a8c2bbfdf4cfc5750f.md b/util/util_types_isnumberobject_value.md similarity index 100% rename from api-docs/d838be7f25347f60b80e19f3b88a6999ca96d313edc9d0a8c2bbfdf4cfc5750f.md rename to util/util_types_isnumberobject_value.md diff --git a/api-docs/791de0e0a01f46cd1d9616b52ecb76e0f6c1675e0fa48b0ffffa88b7268e6929.md b/util/util_types_ispromise_value.md similarity index 100% rename from api-docs/791de0e0a01f46cd1d9616b52ecb76e0f6c1675e0fa48b0ffffa88b7268e6929.md rename to util/util_types_ispromise_value.md diff --git a/api-docs/77d6557e981361f37cad7bc8aa5eac629f8b65b54c1bb480f855929cae084520.md b/util/util_types_isproxy_value.md similarity index 100% rename from api-docs/77d6557e981361f37cad7bc8aa5eac629f8b65b54c1bb480f855929cae084520.md rename to util/util_types_isproxy_value.md diff --git a/api-docs/1f8464c72d2b589d2d7b2aa7406f01b69edbe67435931858f3b4270f43f62e21.md b/util/util_types_isregexp_value.md similarity index 100% rename from api-docs/1f8464c72d2b589d2d7b2aa7406f01b69edbe67435931858f3b4270f43f62e21.md rename to util/util_types_isregexp_value.md diff --git a/api-docs/48a093e578ad0d868366652871eaca79c94f4d1d1c8f781a8c764e75bededc9e.md b/util/util_types_isset_value.md similarity index 100% rename from api-docs/48a093e578ad0d868366652871eaca79c94f4d1d1c8f781a8c764e75bededc9e.md rename to util/util_types_isset_value.md diff --git a/api-docs/efdd6e87e9a330968ad6510a2e80c7f8e5cf85c0a95d53d577400c9d1179bc24.md b/util/util_types_issetiterator_value.md similarity index 100% rename from api-docs/efdd6e87e9a330968ad6510a2e80c7f8e5cf85c0a95d53d577400c9d1179bc24.md rename to util/util_types_issetiterator_value.md diff --git a/api-docs/092a3e6e8ce3d4f8a688b44327f8a2adca39f1a7e06fcec0bd4b0eebb9780226.md b/util/util_types_issharedarraybuffer_value.md similarity index 100% rename from api-docs/092a3e6e8ce3d4f8a688b44327f8a2adca39f1a7e06fcec0bd4b0eebb9780226.md rename to util/util_types_issharedarraybuffer_value.md diff --git a/api-docs/4f4ca1e627c2583a3695653ae858ec563c1ddb3e4210bb44688d4099af943c67.md b/util/util_types_isstringobject_value.md similarity index 100% rename from api-docs/4f4ca1e627c2583a3695653ae858ec563c1ddb3e4210bb44688d4099af943c67.md rename to util/util_types_isstringobject_value.md diff --git a/api-docs/1b9f3a34f1645a69c55d5796d8547190c4fe8e6403ce8d8c12b157ac7b40aee0.md b/util/util_types_issymbolobject_value.md similarity index 100% rename from api-docs/1b9f3a34f1645a69c55d5796d8547190c4fe8e6403ce8d8c12b157ac7b40aee0.md rename to util/util_types_issymbolobject_value.md diff --git a/api-docs/452d3a8aac7c649230cb5a20ad242cbd2cb0ceb45c286cec7c4f562752d2dc43.md b/util/util_types_istypedarray_value.md similarity index 100% rename from api-docs/452d3a8aac7c649230cb5a20ad242cbd2cb0ceb45c286cec7c4f562752d2dc43.md rename to util/util_types_istypedarray_value.md diff --git a/api-docs/5d5590deb8897e677c09ec40b37e72f5b741969c442641f2af0921d6a0fb10d0.md b/util/util_types_isuint16array_value.md similarity index 100% rename from api-docs/5d5590deb8897e677c09ec40b37e72f5b741969c442641f2af0921d6a0fb10d0.md rename to util/util_types_isuint16array_value.md diff --git a/api-docs/ed1f994de444a3b258864ad26d60d483805906ec620f6d75b4ef507757cff54c.md b/util/util_types_isuint32array_value.md similarity index 100% rename from api-docs/ed1f994de444a3b258864ad26d60d483805906ec620f6d75b4ef507757cff54c.md rename to util/util_types_isuint32array_value.md diff --git a/api-docs/c010493c5d280da9fa2ffdc5280af4585a3eab094e9b11b5ee129198d74d0f53.md b/util/util_types_isuint8array_value.md similarity index 100% rename from api-docs/c010493c5d280da9fa2ffdc5280af4585a3eab094e9b11b5ee129198d74d0f53.md rename to util/util_types_isuint8array_value.md diff --git a/api-docs/94aa9c959acf4ac4079a6764005718bc43d2d11cf834b5982ffc7ca72360aa3e.md b/util/util_types_isuint8clampedarray_value.md similarity index 100% rename from api-docs/94aa9c959acf4ac4079a6764005718bc43d2d11cf834b5982ffc7ca72360aa3e.md rename to util/util_types_isuint8clampedarray_value.md diff --git a/api-docs/0553c5e07a3ff7a3bb681bf8fe66f574f7ca0f206135ac758bd4105cfae56b15.md b/util/util_types_isweakmap_value.md similarity index 100% rename from api-docs/0553c5e07a3ff7a3bb681bf8fe66f574f7ca0f206135ac758bd4105cfae56b15.md rename to util/util_types_isweakmap_value.md diff --git a/api-docs/ecb320839f68d3465173f32fd6162d164ab5ea6ab49b01c3a41c94a32c6cab20.md b/util/util_types_isweakset_value.md similarity index 100% rename from api-docs/ecb320839f68d3465173f32fd6162d164ab5ea6ab49b01c3a41c94a32c6cab20.md rename to util/util_types_isweakset_value.md diff --git a/api-docs/d8504bceaa4094bb34f26266afdd4a945fc0c301801c83d4424d22ce90eec9dd.md b/util/util_types_iswebassemblycompiledmodule_value.md similarity index 100% rename from api-docs/d8504bceaa4094bb34f26266afdd4a945fc0c301801c83d4424d22ce90eec9dd.md rename to util/util_types_iswebassemblycompiledmodule_value.md diff --git a/api-docs/23f8bb96caa0376b868309de7e1abc36f2a70c3dad05f3fdd29d2f525c225e36.md b/util/whatwg_supported_encodings.md similarity index 100% rename from api-docs/23f8bb96caa0376b868309de7e1abc36f2a70c3dad05f3fdd29d2f525c225e36.md rename to util/whatwg_supported_encodings.md diff --git a/api-docs/a57284006cd4a083281ab280888acabd632977699c76b88e04adce3fa4d02a73.md b/v8/class_v8_defaultdeserializer.md similarity index 100% rename from api-docs/a57284006cd4a083281ab280888acabd632977699c76b88e04adce3fa4d02a73.md rename to v8/class_v8_defaultdeserializer.md diff --git a/v8/class_v8_defaultserializer.md b/v8/class_v8_defaultserializer.md new file mode 100644 index 00000000..0c55f19e --- /dev/null +++ b/v8/class_v8_defaultserializer.md @@ -0,0 +1,8 @@ + + +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. + diff --git a/v8/class_v8_deserializer.md b/v8/class_v8_deserializer.md new file mode 100644 index 00000000..a6dfdf44 --- /dev/null +++ b/v8/class_v8_deserializer.md @@ -0,0 +1,4 @@ + + diff --git a/v8/class_v8_serializer.md b/v8/class_v8_serializer.md new file mode 100644 index 00000000..a6dfdf44 --- /dev/null +++ b/v8/class_v8_serializer.md @@ -0,0 +1,4 @@ + + diff --git a/v8/deserializer_getwireformatversion.md b/v8/deserializer_getwireformatversion.md new file mode 100644 index 00000000..56430e76 --- /dev/null +++ b/v8/deserializer_getwireformatversion.md @@ -0,0 +1,7 @@ + +* Returns: {integer} + +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()`. + diff --git a/v8/deserializer_readdouble.md b/v8/deserializer_readdouble.md new file mode 100644 index 00000000..169b0685 --- /dev/null +++ b/v8/deserializer_readdouble.md @@ -0,0 +1,6 @@ + +* Returns: {number} + +Read a JS `number` value. +For use inside of a custom [`deserializer._readHostObject()`][]. + diff --git a/v8/deserializer_readheader.md b/v8/deserializer_readheader.md new file mode 100644 index 00000000..cb5e4803 --- /dev/null +++ b/v8/deserializer_readheader.md @@ -0,0 +1,5 @@ + +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. + diff --git a/v8/deserializer_readhostobject.md b/v8/deserializer_readhostobject.md new file mode 100644 index 00000000..3adbec3c --- /dev/null +++ b/v8/deserializer_readhostobject.md @@ -0,0 +1,8 @@ + +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, +a suitable exception should be thrown. + +This method is not present on the `Deserializer` class itself but can be +provided by subclasses. + diff --git a/v8/deserializer_readrawbytes_length.md b/v8/deserializer_readrawbytes_length.md new file mode 100644 index 00000000..6fb43fd9 --- /dev/null +++ b/v8/deserializer_readrawbytes_length.md @@ -0,0 +1,9 @@ + +* `length` {integer} +* Returns: {Buffer} + +Read raw bytes from the deserializer’s internal buffer. The `length` parameter +must correspond to the length of the buffer that was passed to +[`serializer.writeRawBytes()`][]. +For use inside of a custom [`deserializer._readHostObject()`][]. + diff --git a/v8/deserializer_readuint32.md b/v8/deserializer_readuint32.md new file mode 100644 index 00000000..e310dca5 --- /dev/null +++ b/v8/deserializer_readuint32.md @@ -0,0 +1,6 @@ + +* Returns: {integer} + +Read a raw 32-bit unsigned integer and return it. +For use inside of a custom [`deserializer._readHostObject()`][]. + diff --git a/v8/deserializer_readuint64.md b/v8/deserializer_readuint64.md new file mode 100644 index 00000000..1eb75a24 --- /dev/null +++ b/v8/deserializer_readuint64.md @@ -0,0 +1,7 @@ + +* Returns: {integer[]} + +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()`][]. + diff --git a/v8/deserializer_readvalue.md b/v8/deserializer_readvalue.md new file mode 100644 index 00000000..2a7e59ab --- /dev/null +++ b/v8/deserializer_readvalue.md @@ -0,0 +1,3 @@ + +Deserializes a JavaScript value from the buffer and returns it. + diff --git a/v8/deserializer_transferarraybuffer_id_arraybuffer.md b/v8/deserializer_transferarraybuffer_id_arraybuffer.md new file mode 100644 index 00000000..61d203d2 --- /dev/null +++ b/v8/deserializer_transferarraybuffer_id_arraybuffer.md @@ -0,0 +1,9 @@ + +* `id` {integer} A 32-bit unsigned integer. +* `arrayBuffer` {ArrayBuffer|SharedArrayBuffer} An `ArrayBuffer` instance. + +Marks an `ArrayBuffer` as having its contents transferred out of band. +Pass the corresponding `ArrayBuffer` in the serializing context to +[`serializer.transferArrayBuffer()`][] (or return the `id` from +[`serializer._getSharedArrayBufferId()`][] in the case of `SharedArrayBuffer`s). + diff --git a/v8/new_deserializer_buffer.md b/v8/new_deserializer_buffer.md new file mode 100644 index 00000000..fa63beb1 --- /dev/null +++ b/v8/new_deserializer_buffer.md @@ -0,0 +1,6 @@ + +* `buffer` {Buffer|TypedArray|DataView} A buffer returned by + [`serializer.releaseBuffer()`][]. + +Creates a new `Deserializer` object. + diff --git a/v8/new_serializer.md b/v8/new_serializer.md new file mode 100644 index 00000000..f8882205 --- /dev/null +++ b/v8/new_serializer.md @@ -0,0 +1,2 @@ +Creates a new `Serializer` object. + diff --git a/v8/serialization_api.md b/v8/serialization_api.md new file mode 100644 index 00000000..e2acb2d5 --- /dev/null +++ b/v8/serialization_api.md @@ -0,0 +1,10 @@ + +> Stability: 1 - Experimental + +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). + +This API is under development, and changes (including incompatible +changes to the API or wire format) may occur until this warning is removed. + diff --git a/v8/serializer_getdatacloneerror_message.md b/v8/serializer_getdatacloneerror_message.md new file mode 100644 index 00000000..133526c8 --- /dev/null +++ b/v8/serializer_getdatacloneerror_message.md @@ -0,0 +1,9 @@ + +* `message` {string} + +This method is called to generate error objects that will be thrown when an +object can not be cloned. + +This method defaults to the [`Error`][] constructor and can be overridden on +subclasses. + diff --git a/v8/serializer_getsharedarraybufferid_sharedarraybuffer.md b/v8/serializer_getsharedarraybufferid_sharedarraybuffer.md new file mode 100644 index 00000000..09ea383b --- /dev/null +++ b/v8/serializer_getsharedarraybufferid_sharedarraybuffer.md @@ -0,0 +1,14 @@ + +* `sharedArrayBuffer` {SharedArrayBuffer} + +This method is called when the serializer is going to serialize a +`SharedArrayBuffer` object. It must return an unsigned 32-bit integer ID for +the object, using the same ID if this `SharedArrayBuffer` has already been +serialized. When deserializing, this ID will be passed to +[`deserializer.transferArrayBuffer()`][]. + +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. + diff --git a/v8/serializer_releasebuffer.md b/v8/serializer_releasebuffer.md new file mode 100644 index 00000000..6346dd70 --- /dev/null +++ b/v8/serializer_releasebuffer.md @@ -0,0 +1,7 @@ + +* Returns: {Buffer} + +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. + diff --git a/v8/serializer_settreatarraybufferviewsashostobjects_flag.md b/v8/serializer_settreatarraybufferviewsashostobjects_flag.md new file mode 100644 index 00000000..35c05cbb --- /dev/null +++ b/v8/serializer_settreatarraybufferviewsashostobjects_flag.md @@ -0,0 +1,6 @@ + +* `flag` {boolean} **Default:** `false` + +Indicate whether to treat `TypedArray` and `DataView` objects as +host objects, i.e. pass them to [`serializer._writeHostObject()`][]. + diff --git a/v8/serializer_transferarraybuffer_id_arraybuffer.md b/v8/serializer_transferarraybuffer_id_arraybuffer.md new file mode 100644 index 00000000..58bccd63 --- /dev/null +++ b/v8/serializer_transferarraybuffer_id_arraybuffer.md @@ -0,0 +1,8 @@ + +* `id` {integer} A 32-bit unsigned integer. +* `arrayBuffer` {ArrayBuffer} An `ArrayBuffer` instance. + +Marks an `ArrayBuffer` as having its contents transferred out of band. +Pass the corresponding `ArrayBuffer` in the deserializing context to +[`deserializer.transferArrayBuffer()`][]. + diff --git a/v8/serializer_writedouble_value.md b/v8/serializer_writedouble_value.md new file mode 100644 index 00000000..f14179fc --- /dev/null +++ b/v8/serializer_writedouble_value.md @@ -0,0 +1,6 @@ + +* `value` {number} + +Write a JS `number` value. +For use inside of a custom [`serializer._writeHostObject()`][]. + diff --git a/v8/serializer_writeheader.md b/v8/serializer_writeheader.md new file mode 100644 index 00000000..f45c8f79 --- /dev/null +++ b/v8/serializer_writeheader.md @@ -0,0 +1,3 @@ + +Writes out a header, which includes the serialization format version. + diff --git a/v8/serializer_writehostobject_object.md b/v8/serializer_writehostobject_object.md new file mode 100644 index 00000000..07a2541e --- /dev/null +++ b/v8/serializer_writehostobject_object.md @@ -0,0 +1,10 @@ + +* `object` {Object} + +This method is called to write some kind of host object, i.e. an object created +by native C++ bindings. If it is not possible to serialize `object`, a suitable +exception should be thrown. + +This method is not present on the `Serializer` class itself but can be provided +by subclasses. + diff --git a/v8/serializer_writerawbytes_buffer.md b/v8/serializer_writerawbytes_buffer.md new file mode 100644 index 00000000..68523a81 --- /dev/null +++ b/v8/serializer_writerawbytes_buffer.md @@ -0,0 +1,7 @@ + +* `buffer` {Buffer|TypedArray|DataView} + +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()`][]. + diff --git a/v8/serializer_writeuint32_value.md b/v8/serializer_writeuint32_value.md new file mode 100644 index 00000000..7f85e603 --- /dev/null +++ b/v8/serializer_writeuint32_value.md @@ -0,0 +1,6 @@ + +* `value` {integer} + +Write a raw 32-bit unsigned integer. +For use inside of a custom [`serializer._writeHostObject()`][]. + diff --git a/v8/serializer_writeuint64_hi_lo.md b/v8/serializer_writeuint64_hi_lo.md new file mode 100644 index 00000000..f6b74fc7 --- /dev/null +++ b/v8/serializer_writeuint64_hi_lo.md @@ -0,0 +1,7 @@ + +* `hi` {integer} +* `lo` {integer} + +Write a raw 64-bit unsigned integer, split into high and low 32-bit parts. +For use inside of a custom [`serializer._writeHostObject()`][]. + diff --git a/v8/serializer_writevalue_value.md b/v8/serializer_writevalue_value.md new file mode 100644 index 00000000..04959d24 --- /dev/null +++ b/v8/serializer_writevalue_value.md @@ -0,0 +1,8 @@ + +* `value` {any} + +Serializes a JavaScript value and adds the serialized representation to the +internal buffer. + +This throws an error if `value` cannot be serialized. + diff --git a/api-docs/058ec521c7638a78ace88f7c3501c5087953dc3eff79966bd3f2452a6ee5c1ce.md b/v8/v8.md similarity index 100% rename from api-docs/058ec521c7638a78ace88f7c3501c5087953dc3eff79966bd3f2452a6ee5c1ce.md rename to v8/v8.md diff --git a/api-docs/434a6069cd9e705fa3b0f75267bc01d2b48f897f6c15eb5bdd2736f2e6d1e51c.md b/v8/v8_cacheddataversiontag.md similarity index 100% rename from api-docs/434a6069cd9e705fa3b0f75267bc01d2b48f897f6c15eb5bdd2736f2e6d1e51c.md rename to v8/v8_cacheddataversiontag.md diff --git a/v8/v8_deserialize_buffer.md b/v8/v8_deserialize_buffer.md new file mode 100644 index 00000000..4edac627 --- /dev/null +++ b/v8/v8_deserialize_buffer.md @@ -0,0 +1,9 @@ + + +* `buffer` {Buffer|TypedArray|DataView} A buffer returned by [`serialize()`][]. + +Uses a [`DefaultDeserializer`][] with default options to read a JS value +from a buffer. + diff --git a/api-docs/9b96cb5adb765942f292953779b86bec06d2946fb3be72d357bbe50a18a6a37c.md b/v8/v8_getheapsnapshot.md similarity index 100% rename from api-docs/9b96cb5adb765942f292953779b86bec06d2946fb3be72d357bbe50a18a6a37c.md rename to v8/v8_getheapsnapshot.md diff --git a/api-docs/f3fca35576f8ff02567805744af2afb6aff3bbfa926917bd948b6cabd6e31991.md b/v8/v8_getheapspacestatistics.md similarity index 100% rename from api-docs/f3fca35576f8ff02567805744af2afb6aff3bbfa926917bd948b6cabd6e31991.md rename to v8/v8_getheapspacestatistics.md diff --git a/api-docs/a905f5e97552b5740be72caebb9e8110451f980680e71d55e143bfca72d2f777.md b/v8/v8_getheapstatistics.md similarity index 100% rename from api-docs/a905f5e97552b5740be72caebb9e8110451f980680e71d55e143bfca72d2f777.md rename to v8/v8_getheapstatistics.md diff --git a/v8/v8_serialize_value.md b/v8/v8_serialize_value.md new file mode 100644 index 00000000..974682e0 --- /dev/null +++ b/v8/v8_serialize_value.md @@ -0,0 +1,9 @@ + + +* `value` {any} +* Returns: {Buffer} + +Uses a [`DefaultSerializer`][] to serialize `value` into a buffer. + diff --git a/api-docs/e545317c41c8a0b49c71fd696aa67c653c4cc4d95babc85dd2fd09020556ef94.md b/v8/v8_setflagsfromstring_flags.md similarity index 100% rename from api-docs/e545317c41c8a0b49c71fd696aa67c653c4cc4d95babc85dd2fd09020556ef94.md rename to v8/v8_setflagsfromstring_flags.md diff --git a/api-docs/47553fafd6680b7a6ec34486ef34780126785a9032df717951231922086107e8.md b/v8/v8_writeheapsnapshot_filename.md similarity index 100% rename from api-docs/47553fafd6680b7a6ec34486ef34780126785a9032df717951231922086107e8.md rename to v8/v8_writeheapsnapshot_filename.md diff --git a/vm/class_vm_module.md b/vm/class_vm_module.md new file mode 100644 index 00000000..2283e718 --- /dev/null +++ b/vm/class_vm_module.md @@ -0,0 +1,111 @@ + + +> Stability: 1 - Experimental + +*This feature is only available with the `--experimental-vm-modules` command +flag enabled.* + +The `vm.Module` class provides a low-level interface for using ECMAScript +modules in VM contexts. It is the counterpart of the `vm.Script` class that +closely mirrors [Source Text Module Record][]s as defined in the ECMAScript +specification. + +Unlike `vm.Script` however, every `vm.Module` object is bound to a context from +its creation. Operations on `vm.Module` objects are intrinsically asynchronous, +in contrast with the synchronous nature of `vm.Script` objects. With the help +of async functions, however, manipulating `vm.Module` objects is fairly +straightforward. + +Using a `vm.Module` object requires four distinct steps: creation/parsing, +linking, instantiation, and evaluation. These four steps are illustrated in the +following example. + +This implementation lies at a lower level than the [ECMAScript Module +loader][]. There is also currently no way to interact with the Loader, though +support is planned. + +```js +const vm = require('vm'); + +const contextifiedSandbox = vm.createContext({ secret: 42 }); + +(async () => { + // Step 1 + // + // Create a Module by constructing a new `vm.Module` 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. + // + // Here, we attempt to obtain the default export from the module "foo", and + // put it into local binding "secret". + + const bar = new vm.Module(` + import s from 'foo'; + s; + `, { context: contextifiedSandbox }); + + // Step 2 + // + // "Link" the imported dependencies of this Module to it. + // + // The provided linking callback (the "linker") accepts two arguments: the + // parent module (`bar` in this case) and the string that is the specifier of + // the imported module. The callback is expected to return a Module that + // corresponds to the provided specifier, with certain requirements documented + // in `module.link()`. + // + // If linking has not started for the returned Module, the same linker + // callback will be called on the returned Module. + // + // Even top-level Modules without dependencies must be explicitly linked. The + // callback provided would never be called, however. + // + // The link() method returns a Promise that will be resolved when all the + // Promises returned by the linker resolve. + // + // Note: This is a contrived example in that the linker function creates a new + // "foo" module every time it is called. In a full-fledged module system, a + // cache would probably be used to avoid duplicated modules. + + async function linker(specifier, referencingModule) { + if (specifier === 'foo') { + return new vm.Module(` + // The "secret" variable refers to the global variable we added to + // "contextifiedSandbox" when creating the context. + export default secret; + `, { context: referencingModule.context }); + + // Using `contextifiedSandbox` instead of `referencingModule.context` + // here would work as well. + } + throw new Error(`Unable to resolve dependency: ${specifier}`); + } + await bar.link(linker); + + // Step 3 + // + // Instantiate the top-level Module. + // + // Only the top-level Module needs to be explicitly instantiated; its + // dependencies will be recursively instantiated by instantiate(). + + bar.instantiate(); + + // Step 4 + // + // Evaluate the Module. The evaluate() method returns a Promise with a single + // property "result" that contains the result of the very last statement + // executed in the Module. In the case of `bar`, it is `s;`, which refers to + // the default export of the `foo` module, the `secret` we set in the + // beginning to 42. + + const { result } = await bar.evaluate(); + + console.log(result); + // Prints 42. +})(); +``` + diff --git a/api-docs/eec1b6bba47a8d7896a41d7c252c02a45d515a3df2113786d5a1d8a9c92f2cdc.md b/vm/class_vm_script.md similarity index 100% rename from api-docs/eec1b6bba47a8d7896a41d7c252c02a45d515a3df2113786d5a1d8a9c92f2cdc.md rename to vm/class_vm_script.md diff --git a/vm/class_vm_sourcetextmodule.md b/vm/class_vm_sourcetextmodule.md new file mode 100644 index 00000000..b0cfa6b3 --- /dev/null +++ b/vm/class_vm_sourcetextmodule.md @@ -0,0 +1,111 @@ + + +> Stability: 1 - Experimental + +*This feature is only available with the `--experimental-vm-modules` command +flag enabled.* + +The `vm.SourceTextModule` class provides a low-level interface for using +ECMAScript modules in VM contexts. It is the counterpart of the `vm.Script` +class that closely mirrors [Source Text Module Record][]s as defined in the +ECMAScript specification. + +Unlike `vm.Script` however, every `vm.SourceTextModule` object is bound to a +context from its creation. Operations on `vm.SourceTextModule` objects are +intrinsically asynchronous, in contrast with the synchronous nature of +`vm.Script` objects. With the help of async functions, however, manipulating +`vm.SourceTextModule` objects is fairly straightforward. + +Using a `vm.SourceTextModule` object requires four distinct steps: +creation/parsing, linking, instantiation, and evaluation. These four steps are +illustrated in the following example. + +This implementation lies at a lower level than the [ECMAScript Module +loader][]. There is also currently no way to interact with the Loader, though +support is planned. + +```js +const vm = require('vm'); + +const contextifiedSandbox = vm.createContext({ secret: 42 }); + +(async () => { + // Step 1 + // + // 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. + // + // Here, we attempt to obtain the default export from the module "foo", and + // put it into local binding "secret". + + const bar = new vm.SourceTextModule(` + import s from 'foo'; + s; + `, { context: contextifiedSandbox }); + + // Step 2 + // + // "Link" the imported dependencies of this Module to it. + // + // The provided linking callback (the "linker") accepts two arguments: the + // parent module (`bar` in this case) and the string that is the specifier of + // the imported module. The callback is expected to return a Module that + // corresponds to the provided specifier, with certain requirements documented + // in `module.link()`. + // + // If linking has not started for the returned Module, the same linker + // callback will be called on the returned Module. + // + // Even top-level Modules without dependencies must be explicitly linked. The + // callback provided would never be called, however. + // + // The link() method returns a Promise that will be resolved when all the + // Promises returned by the linker resolve. + // + // Note: This is a contrived example in that the linker function creates a new + // "foo" module every time it is called. In a full-fledged module system, a + // cache would probably be used to avoid duplicated modules. + + async function linker(specifier, referencingModule) { + if (specifier === 'foo') { + return new vm.SourceTextModule(` + // The "secret" variable refers to the global variable we added to + // "contextifiedSandbox" when creating the context. + export default secret; + `, { context: referencingModule.context }); + + // Using `contextifiedSandbox` instead of `referencingModule.context` + // here would work as well. + } + throw new Error(`Unable to resolve dependency: ${specifier}`); + } + await bar.link(linker); + + // Step 3 + // + // Instantiate the top-level Module. + // + // Only the top-level Module needs to be explicitly instantiated; its + // dependencies will be recursively instantiated by instantiate(). + + bar.instantiate(); + + // Step 4 + // + // Evaluate the Module. The evaluate() method returns a Promise with a single + // property "result" that contains the result of the very last statement + // executed in the Module. In the case of `bar`, it is `s;`, which refers to + // the default export of the `foo` module, the `secret` we set in the + // beginning to 42. + + const { result } = await bar.evaluate(); + + console.log(result); + // Prints 42. +})(); +``` + diff --git a/vm/constructor_new_vm_module_code_options.md b/vm/constructor_new_vm_module_code_options.md new file mode 100644 index 00000000..974039c0 --- /dev/null +++ b/vm/constructor_new_vm_module_code_options.md @@ -0,0 +1,54 @@ + +* `code` {string} JavaScript Module code to parse +* `options` + * `url` {string} URL used in module resolution and stack traces. **Default:** + `'vm:module(i)'` where `i` is a context-specific ascending index. + * `context` {Object} The [contextified][] object as returned by the + `vm.createContext()` method, to compile and evaluate this `Module` in. + * `lineOffset` {integer} Specifies the line number offset that is displayed + in stack traces produced by this `Module`. + * `columnOffset` {integer} Specifies the column number offset that is + displayed in stack traces produced by this `Module`. + * `initalizeImportMeta` {Function} Called during evaluation of this `Module` + to initialize the `import.meta`. This function has the signature `(meta, + module)`, where `meta` is the `import.meta` object in the `Module`, and + `module` is this `vm.Module` object. + +Creates a new ES `Module` object. + +Properties assigned to the `import.meta` object that are objects may +allow the `Module` to access information outside the specified `context`, if the +object is created in the top level context. Use `vm.runInContext()` to create +objects in a specific context. + +```js +const vm = require('vm'); + +const contextifiedSandbox = vm.createContext({ secret: 42 }); + +(async () => { + const module = new vm.Module( + 'Object.getPrototypeOf(import.meta.prop).secret = secret;', + { + initializeImportMeta(meta) { + // 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. + meta.prop = {}; + } + }); + // Since module has no dependencies, the linker function will never be called. + await module.link(() => {}); + module.initialize(); + await module.evaluate(); + + // Now, Object.prototype.secret will be equal to 42. + // + // To fix this problem, replace + // meta.prop = {}; + // above with + // meta.prop = vm.runInContext('{}', contextifiedSandbox); +})(); +``` + diff --git a/vm/constructor_new_vm_sourcetextmodule_code_options.md b/vm/constructor_new_vm_sourcetextmodule_code_options.md new file mode 100644 index 00000000..47ad58c7 --- /dev/null +++ b/vm/constructor_new_vm_sourcetextmodule_code_options.md @@ -0,0 +1,63 @@ + +* `code` {string} JavaScript Module code to parse +* `options` + * `url` {string} URL used in module resolution and stack traces. **Default:** + `'vm:module(i)'` where `i` is a context-specific ascending index. + * `context` {Object} The [contextified][] object as returned by the + `vm.createContext()` method, to compile and evaluate this `Module` in. + * `lineOffset` {integer} Specifies the line number offset that is displayed + in stack traces produced by this `Module`. + * `columnOffset` {integer} Specifies the column number offset that is + displayed in stack traces produced by this `Module`. + * `initializeImportMeta` {Function} Called during evaluation of this `Module` + to initialize the `import.meta`. This function has the signature `(meta, + module)`, where `meta` is the `import.meta` object in the `Module`, and + `module` is this `vm.SourceTextModule` object. + * `importModuleDynamically` {Function} Called during evaluation of this + module when `import()` is called. This function has the signature + `(specifier, module)` where `specifier` is the specifier passed to + `import()` and `module` is this `vm.SourceTextModule`. If this option is + not specified, calls to `import()` will reject with + [`ERR_VM_DYNAMIC_IMPORT_CALLBACK_MISSING`][]. This method can return a + [Module Namespace Object][], but returning a `vm.SourceTextModule` is + recommended in order to take advantage of error tracking, and to avoid + issues with namespaces that contain `then` function exports. + +Creates a new ES `Module` object. + +Properties assigned to the `import.meta` object that are objects may +allow the `Module` to access information outside the specified `context`, if the +object is created in the top level context. Use `vm.runInContext()` to create +objects in a specific context. + +```js +const vm = require('vm'); + +const contextifiedSandbox = vm.createContext({ secret: 42 }); + +(async () => { + const module = new vm.SourceTextModule( + 'Object.getPrototypeOf(import.meta.prop).secret = secret;', + { + initializeImportMeta(meta) { + // 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. + meta.prop = {}; + } + }); + // Since module has no dependencies, the linker function will never be called. + await module.link(() => {}); + module.instantiate(); + await module.evaluate(); + + // Now, Object.prototype.secret will be equal to 42. + // + // To fix this problem, replace + // meta.prop = {}; + // above with + // meta.prop = vm.runInContext('{}', contextifiedSandbox); +})(); +``` + diff --git a/api-docs/fd805f0c66ffda53a1871f64b0b5b5cd3a22f4511ad4cb50d8469d7ddd28a7f0.md b/vm/example_running_an_http_server_within_a_vm.md similarity index 100% rename from api-docs/fd805f0c66ffda53a1871f64b0b5b5cd3a22f4511ad4cb50d8469d7ddd28a7f0.md rename to vm/example_running_an_http_server_within_a_vm.md diff --git a/vm/executing_javascript.md b/vm/executing_javascript.md new file mode 100644 index 00000000..e4f278eb --- /dev/null +++ b/vm/executing_javascript.md @@ -0,0 +1,15 @@ + + + +> 稳定性: 2 - 稳定 + + + +`vm`模块提供了一系列API用于在V8引擎的环境中编译和运行代码。它可以被如下使用： + +```js +const vm = require('vm'); +``` + +JavaScript代码可以被立刻编译，保存并运行。 + diff --git a/vm/module_dependencyspecifiers.md b/vm/module_dependencyspecifiers.md new file mode 100644 index 00000000..5ad8ddbc --- /dev/null +++ b/vm/module_dependencyspecifiers.md @@ -0,0 +1,9 @@ + +* {string[]} + +The specifiers of all dependencies of this module. The returned array is frozen +to disallow any changes to it. + +Corresponds to the `[[RequestedModules]]` field of +[Source Text Module Record][]s in the ECMAScript specification. + diff --git a/vm/module_error.md b/vm/module_error.md new file mode 100644 index 00000000..d2f16eec --- /dev/null +++ b/vm/module_error.md @@ -0,0 +1,13 @@ + +* {any} + +If the `module.status` is `'errored'`, this property contains the exception +thrown by the module during evaluation. If the status is anything else, +accessing this property will result in a thrown exception. + +The value `undefined` cannot be used for cases where there is not a thrown +exception due to possible ambiguity with `throw undefined;`. + +Corresponds to the `[[EvaluationError]]` field of [Source Text Module Record][]s +in the ECMAScript specification. + diff --git a/vm/module_evaluate_options.md b/vm/module_evaluate_options.md new file mode 100644 index 00000000..fd7a407d --- /dev/null +++ b/vm/module_evaluate_options.md @@ -0,0 +1,29 @@ + +* `options` {Object} + * `timeout` {integer} Specifies the number of milliseconds to evaluate + before terminating execution. If execution is interrupted, an [`Error`][] + will be thrown. This value must be a strictly positive integer. + * `breakOnSigint` {boolean} If `true`, the execution will be terminated when + `SIGINT` (Ctrl+C) is received. Existing handlers for the event that have + been attached via `process.on('SIGINT')` will be disabled during script + execution, but will continue to work after that. If execution is + interrupted, an [`Error`][] will be thrown. +* Returns: {Promise} + +Evaluate the module. + +This must be called after the module has been instantiated; otherwise it will +throw an error. It could be called also when the module has already been +evaluated, in which case it will do one of the following two things: + +- return `undefined` if the initial evaluation ended in success (`module.status` + is `'evaluated'`) +- rethrow the same exception the initial evaluation threw if the initial + evaluation ended in an error (`module.status` is `'errored'`) + +This method cannot be called while the module is being evaluated +(`module.status` is `'evaluating'`) to prevent infinite recursion. + +Corresponds to the [Evaluate() concrete method][] field of [Source Text Module +Record][]s in the ECMAScript specification. + diff --git a/vm/module_instantiate.md b/vm/module_instantiate.md new file mode 100644 index 00000000..5f304568 --- /dev/null +++ b/vm/module_instantiate.md @@ -0,0 +1,16 @@ + +Instantiate the module. This must be called after linking has completed +(`linkingStatus` is `'linked'`); otherwise it will throw an error. It may also +throw an exception if one of the dependencies does not provide an export the +parent module requires. + +However, if this function succeeded, further calls to this function after the +initial instantiation will be no-ops, to be consistent with the ECMAScript +specification. + +Unlike other methods operating on `Module`, this function completes +synchronously and returns nothing. + +Corresponds to the [Instantiate() concrete method][] field of [Source Text +Module Record][]s in the ECMAScript specification. + diff --git a/vm/module_link_linker.md b/vm/module_link_linker.md new file mode 100644 index 00000000..d5f96ee8 --- /dev/null +++ b/vm/module_link_linker.md @@ -0,0 +1,48 @@ + +* `linker` {Function} +* Returns: {Promise} + +Link module dependencies. This method must be called before instantiation, and +can only be called once per module. + +Two parameters will be passed to the `linker` function: + +- `specifier` The specifier of the requested module: + + ```js + import foo from 'foo'; + // ^^^^^ the module specifier + ``` +- `referencingModule` The `Module` object `link()` is called on. + +The function is expected to return a `Module` object or a `Promise` that +eventually resolves to a `Module` object. The returned `Module` must satisfy the +following two invariants: + +- It must belong to the same context as the parent `Module`. +- Its `linkingStatus` must not be `'errored'`. + +If the returned `Module`'s `linkingStatus` is `'unlinked'`, this method will be +recursively called on the returned `Module` with the same provided `linker` +function. + +`link()` returns a `Promise` that will either get resolved when all linking +instances resolve to a valid `Module`, or rejected if the linker function either +throws an exception or returns an invalid `Module`. + +The linker function roughly corresponds to the implementation-defined +[HostResolveImportedModule][] abstract operation in the ECMAScript +specification, with a few key differences: + +- The linker function is allowed to be asynchronous while + [HostResolveImportedModule][] is synchronous. +- The linker function is executed during linking, a Node.js-specific stage + before instantiation, while [HostResolveImportedModule][] is called during + instantiation. + +The actual [HostResolveImportedModule][] implementation used during module +instantiation is one that returns the modules linked during linking. Since at +that point all modules would have been fully linked already, the +[HostResolveImportedModule][] implementation is fully synchronous per +specification. + diff --git a/vm/module_linkingstatus.md b/vm/module_linkingstatus.md new file mode 100644 index 00000000..f131ca06 --- /dev/null +++ b/vm/module_linkingstatus.md @@ -0,0 +1,14 @@ + +* {string} + +The current linking status of `module`. It will be one of the following values: + +- `'unlinked'`: `module.link()` has not yet been called. +- `'linking'`: `module.link()` has been called, but not all Promises returned by + the linker function have been resolved yet. +- `'linked'`: `module.link()` has been called, and all its dependencies have + been successfully linked. +- `'errored'`: `module.link()` has been called, but at least one of its + dependencies failed to link, either because the callback returned a `Promise` + that is rejected, or because the `Module` the callback returned is invalid. + diff --git a/vm/module_namespace.md b/vm/module_namespace.md new file mode 100644 index 00000000..eb8d949b --- /dev/null +++ b/vm/module_namespace.md @@ -0,0 +1,9 @@ + +* {Object} + +The namespace object of the module. This is only available after instantiation +(`module.instantiate()`) has completed. + +Corresponds to the [GetModuleNamespace][] abstract operation in the ECMAScript +specification. + diff --git a/vm/module_status.md b/vm/module_status.md new file mode 100644 index 00000000..b124a7bb --- /dev/null +++ b/vm/module_status.md @@ -0,0 +1,33 @@ + +* {string} + +The current status of the module. Will be one of: + +- `'uninstantiated'`: The module is not instantiated. It may because of any of + the following reasons: + + - The module was just created. + - `module.instantiate()` has been called on this module, but it failed for + some reason. + + This status does not convey any information regarding if `module.link()` has + been called. See `module.linkingStatus` for that. + +- `'instantiating'`: The module is currently being instantiated through a + `module.instantiate()` call on itself or a parent module. + +- `'instantiated'`: The module has been instantiated successfully, but + `module.evaluate()` has not yet been called. + +- `'evaluating'`: The module is being evaluated through a `module.evaluate()` on + itself or a parent module. + +- `'evaluated'`: The module has been successfully evaluated. + +- `'errored'`: The module has been evaluated, but an exception was thrown. + +Other than `'errored'`, this status string corresponds to the specification's +[Source Text Module Record][]'s `[[Status]]` field. `'errored'` corresponds to +`'evaluated'` in the specification, but with `[[EvaluationError]]` set to a +value that is not `undefined`. + diff --git a/vm/module_url.md b/vm/module_url.md new file mode 100644 index 00000000..a38c2a05 --- /dev/null +++ b/vm/module_url.md @@ -0,0 +1,5 @@ + +* {string} + +The URL of the current module, as set in the constructor. + diff --git a/api-docs/e61daeeeee245cbdc2cb2f24e788fa956ac0f7e9722cbbb269d43944ca357961.md b/vm/new_vm_script_code_options.md similarity index 100% rename from api-docs/e61daeeeee245cbdc2cb2f24e788fa956ac0f7e9722cbbb269d43944ca357961.md rename to vm/new_vm_script_code_options.md diff --git a/api-docs/c11b2ee97d0df4c0cfef152d358b551219831680738a96b86c86ac5ed2c7de62.md b/vm/script_createcacheddata.md similarity index 100% rename from api-docs/c11b2ee97d0df4c0cfef152d358b551219831680738a96b86c86ac5ed2c7de62.md rename to vm/script_createcacheddata.md diff --git a/api-docs/8934956ce87b703627f770f3a8cc3c1f6b1ef15a88701d3a66f8b7dd9f47be13.md b/vm/script_runincontext_contextifiedsandbox_options.md similarity index 100% rename from api-docs/8934956ce87b703627f770f3a8cc3c1f6b1ef15a88701d3a66f8b7dd9f47be13.md rename to vm/script_runincontext_contextifiedsandbox_options.md diff --git a/api-docs/cbfb396932d182ac1c20f5b46e10ad2426b18d70fc53174ea45fe757618f248c.md b/vm/script_runinnewcontext_sandbox_options.md similarity index 100% rename from api-docs/cbfb396932d182ac1c20f5b46e10ad2426b18d70fc53174ea45fe757618f248c.md rename to vm/script_runinnewcontext_sandbox_options.md diff --git a/api-docs/118005f677e18db9f4654aabce1e17df8cb38025c70b71ffc002ce09652bc124.md b/vm/script_runinthiscontext_options.md similarity index 100% rename from api-docs/118005f677e18db9f4654aabce1e17df8cb38025c70b71ffc002ce09652bc124.md rename to vm/script_runinthiscontext_options.md diff --git a/api-docs/e969df99e31338408369802428efe13400907791cbda5dcc68fb8da5390fca04.md b/vm/timeout_limitations_when_using_process_nexttick_and_promises.md similarity index 100% rename from api-docs/e969df99e31338408369802428efe13400907791cbda5dcc68fb8da5390fca04.md rename to vm/timeout_limitations_when_using_process_nexttick_and_promises.md diff --git a/api-docs/b43f94216c9e9b09bd005648649bd7daf92db45b4c8f4fd37ed479ad85787cbf.md b/vm/vm_compilefunction_code_params_options.md similarity index 100% rename from api-docs/b43f94216c9e9b09bd005648649bd7daf92db45b4c8f4fd37ed479ad85787cbf.md rename to vm/vm_compilefunction_code_params_options.md diff --git a/vm/vm_createcontext_sandbox.md b/vm/vm_createcontext_sandbox.md new file mode 100644 index 00000000..ee6bc9cd --- /dev/null +++ b/vm/vm_createcontext_sandbox.md @@ -0,0 +1,28 @@ + + +* `sandbox` {Object} + +给定一个`sandbox`对象， `vm.createContext()`会[设置此`sandbox`][contextified]，从而让它具备在[`vm.runInContext()`][]或者[`script.runInContext()`][]中被使用的能力。对于此二方法中所调用的脚本，他们的全局对象不仅拥有我们提供的`sandbox`对象的所有属性，同时还有任何[global object][]所拥有的属性。对于这些脚本之外的所有代码，他们的全局变量将保持不变。 + +```js +const util = require('util'); +const vm = require('vm'); + +global.globalVar = 3; + +const sandbox = { globalVar: 1 }; +vm.createContext(sandbox); + +vm.runInContext('globalVar *= 2;', sandbox); + +console.log(util.inspect(sandbox)); // { globalVar: 2 } + +console.log(util.inspect(globalVar)); // 3 +``` + +如果未提供`sandbox`（或者传入`undefined`），那么会返回一个全新的，空的，[上下文隔离化][contextified]后的`sandbox`对象。 + +`vm.createContext()`主要是用于创建一个能运行多个脚本的`sandbox`。比如说，在模拟一个网页浏览器时，此方法可以被用于创建一个单独的`sandbox`来代表一个窗口的全局对象，然后所有的`