From 70535d7051fb4e5b703700625c954aa360a5b64c Mon Sep 17 00:00:00 2001 From: Nick Schonning Date: Thu, 29 Aug 2019 09:28:03 -0400 Subject: [PATCH] doc: add blanks around code fences Addresses Markdownlint MD031 rule warnings --- BUILDING.md | 3 + CPP_STYLE_GUIDE.md | 1 + doc/api/child_process.md | 1 + doc/api/cli.md | 1 + doc/api/console.md | 1 + doc/api/crypto.md | 1 + doc/api/dgram.md | 1 + doc/api/errors.md | 1 + doc/api/esm.md | 1 + doc/api/fs.md | 2 + doc/api/http2.md | 1 + doc/api/https.md | 1 + doc/api/n-api.md | 174 ++++++++++++++++++++++++++++++ doc/api/perf_hooks.md | 1 + doc/api/process.md | 3 + doc/api/stream.md | 1 + doc/api/tls.md | 1 + doc/api/util.md | 3 + doc/api/vm.md | 1 + doc/api/zlib.md | 1 + doc/guides/updating-root-certs.md | 3 + doc/guides/writing-tests.md | 3 + doc/onboarding-extras.md | 11 +- 23 files changed, 212 insertions(+), 5 deletions(-) diff --git a/BUILDING.md b/BUILDING.md index 8725db965eb0e4..c56be2ad54e9cb 100644 --- a/BUILDING.md +++ b/BUILDING.md @@ -665,16 +665,19 @@ during configuration if the ICU version is too old. #### Unix/macOS From an already-unpacked ICU: + ```console $ ./configure --with-intl=[small-icu,full-icu] --with-icu-source=/path/to/icu ``` From a local ICU tarball: + ```console $ ./configure --with-intl=[small-icu,full-icu] --with-icu-source=/path/to/icu.tgz ``` From a tarball URL: + ```console $ ./configure --with-intl=full-icu --with-icu-source=http://url/to/icu.tgz ``` diff --git a/CPP_STYLE_GUIDE.md b/CPP_STYLE_GUIDE.md index d624156b97a2ca..bb230ce7ee83c0 100644 --- a/CPP_STYLE_GUIDE.md +++ b/CPP_STYLE_GUIDE.md @@ -186,6 +186,7 @@ class FancyContainer { ... } ``` + ## Memory Management ### Memory allocation diff --git a/doc/api/child_process.md b/doc/api/child_process.md index 02ffce72388c04..412092d7d13c50 100644 --- a/doc/api/child_process.md +++ b/doc/api/child_process.md @@ -168,6 +168,7 @@ generated output. The `command` string passed to the exec function is processed directly by the shell and special characters (vary based on [shell](https://en.wikipedia.org/wiki/List_of_command-line_interpreters)) need to be dealt with accordingly: + ```js exec('"/path/to/test file/test.sh" arg1 arg2'); // Double quotes are used so that the space in the path is not interpreted as diff --git a/doc/api/cli.md b/doc/api/cli.md index 57754c57614847..24cf04055398ad 100644 --- a/doc/api/cli.md +++ b/doc/api/cli.md @@ -70,6 +70,7 @@ added: v10.12.0 --> Print source-able bash completion script for Node.js. + ```console $ node --completion-bash > node_bash_completion $ source node_bash_completion diff --git a/doc/api/console.md b/doc/api/console.md index 190e03007acc11..c03e7b82331ba8 100644 --- a/doc/api/console.md +++ b/doc/api/console.md @@ -498,6 +498,7 @@ This method does not display anything unless used in the inspector. The `console.profile()` method starts a JavaScript CPU profile with an optional label until [`console.profileEnd()`][] is called. The profile is then added to the **Profile** panel of the inspector. + ```js console.profile('MyLabel'); // Some code diff --git a/doc/api/crypto.md b/doc/api/crypto.md index 9dadac3946447d..3f3f1e62107155 100644 --- a/doc/api/crypto.md +++ b/doc/api/crypto.md @@ -712,6 +712,7 @@ const dh = crypto.createDiffieHellmanGroup(name); ``` `name` is taken from [RFC 2412][] (modp1 and 2) and [RFC 3526][]: + ```console $ perl -ne 'print "$1\n" if /"(modp\d+)"/' src/node_crypto_groups.h modp1 # 768 bits diff --git a/doc/api/dgram.md b/doc/api/dgram.md index d0af318117863a..dfd9c4d2ea5b70 100644 --- a/doc/api/dgram.md +++ b/doc/api/dgram.md @@ -528,6 +528,7 @@ socket.bind(1234, () => { #### Example: IPv4 Outgoing Multicast Interface All systems use an IP of the host on the desired physical interface: + ```js const socket = dgram.createSocket('udp4'); diff --git a/doc/api/errors.md b/doc/api/errors.md index b2dafd42de9765..3ce5abf8de2e11 100644 --- a/doc/api/errors.md +++ b/doc/api/errors.md @@ -70,6 +70,7 @@ Errors that occur within _Asynchronous APIs_ may be reported in multiple ways: // Otherwise handle the data }); ``` + - When an asynchronous method is called on an object that is an [`EventEmitter`][], errors can be routed to that object's `'error'` event. diff --git a/doc/api/esm.md b/doc/api/esm.md index 159dcc678c74f7..0ed0d7d1b4dab2 100644 --- a/doc/api/esm.md +++ b/doc/api/esm.md @@ -188,6 +188,7 @@ module via `import`. "main": "./src/index.js" } ``` + ```js // ./my-app.mjs diff --git a/doc/api/fs.md b/doc/api/fs.md index 1dc2c6841cc0a5..d5093af24d8a24 100644 --- a/doc/api/fs.md +++ b/doc/api/fs.md @@ -231,6 +231,7 @@ fs.readFileSync(new URL('file:///p/a/t/h/%2f')); /* TypeError [ERR_INVALID_FILE_URL_PATH]: File URL path must not include encoded / characters */ ``` + On Windows, `file:` URLs having encoded backslash will result in a throw: ```js @@ -3816,6 +3817,7 @@ recommended. When `file` is a file descriptor, the behavior is almost identical to directly calling `fs.write()` like: + ```javascript fs.write(fd, Buffer.from(data, options.encoding), callback); ``` diff --git a/doc/api/http2.md b/doc/api/http2.md index 6c280f4e86eb63..315e6808252157 100644 --- a/doc/api/http2.md +++ b/doc/api/http2.md @@ -2459,6 +2459,7 @@ 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'); diff --git a/doc/api/https.md b/doc/api/https.md index 172c91bbfa9fae..beaf2e6897d46e 100644 --- a/doc/api/https.md +++ b/doc/api/https.md @@ -256,6 +256,7 @@ req.on('error', (e) => { }); req.end(); ``` + Example using options from [`tls.connect()`][]: ```js diff --git a/doc/api/n-api.md b/doc/api/n-api.md index 2bc1218fd9cffe..d013dedb4bd7e4 100644 --- a/doc/api/n-api.md +++ b/doc/api/n-api.md @@ -87,26 +87,33 @@ 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. @@ -340,6 +347,7 @@ napiVersion: 1 --> 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, @@ -363,6 +371,7 @@ typedef enum { napi_date_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`. @@ -371,6 +380,7 @@ it can be obtained by calling `napi_get_last_error_info`. added: v8.0.0 napiVersion: 1 --> + ```C typedef struct { const char* error_message; @@ -422,6 +432,7 @@ 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, @@ -438,6 +449,7 @@ napiVersion: 4 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, @@ -501,6 +513,7 @@ napiVersion: 1 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); ``` @@ -577,12 +590,14 @@ 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 @@ -631,6 +646,7 @@ The format of the `napi_extended_error_info` structure is as follows: added: v10.6.0 napiVersion: 4 --> + ```C typedef struct napi_extended_error_info { const char* error_message; @@ -639,6 +655,7 @@ typedef struct napi_extended_error_info { 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. @@ -656,11 +673,13 @@ logging purposes. added: v8.0.0 napiVersion: 1 --> + ```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. @@ -764,9 +783,11 @@ TypeError [ERR_ERROR_1] added: v8.0.0 napiVersion: 1 --> + ```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. @@ -779,11 +800,13 @@ This API throws the JavaScript value provided. added: v8.0.0 napiVersion: 1 --> + ```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 @@ -798,11 +821,13 @@ This API throws a JavaScript `Error` with the text provided. added: v8.0.0 napiVersion: 1 --> + ```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 @@ -817,11 +842,13 @@ This API throws a JavaScript `TypeError` with the text provided. added: v8.0.0 napiVersion: 1 --> + ```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 @@ -836,11 +863,13 @@ This API throws a JavaScript `RangeError` with the text provided. added: v8.0.0 napiVersion: 1 --> + ```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 @@ -855,12 +884,14 @@ This API queries a `napi_value` to check if it represents an error object. added: v8.0.0 napiVersion: 1 --> + ```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. @@ -877,12 +908,14 @@ This API returns a JavaScript `Error` with the text provided. added: v8.0.0 napiVersion: 1 --> + ```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. @@ -899,12 +932,14 @@ This API returns a JavaScript `TypeError` with the text provided. added: v8.0.0 napiVersion: 1 --> + ```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. @@ -921,6 +956,7 @@ This API returns a JavaScript `RangeError` with the text provided. added: v8.0.0 napiVersion: 1 --> + ```C napi_status napi_get_and_clear_last_exception(napi_env env, napi_value* result); @@ -940,6 +976,7 @@ This API can be called even if there is a pending JavaScript exception. added: v8.0.0 napiVersion: 1 --> + ```C napi_status napi_is_exception_pending(napi_env env, bool* result); ``` @@ -979,6 +1016,7 @@ thrown to immediately terminate the process. added: v8.2.0 napiVersion: 1 --> + ```C NAPI_NO_RETURN void napi_fatal_error(const char* location, size_t location_len, @@ -1093,10 +1131,12 @@ can only be called once. added: v8.0.0 napiVersion: 1 --> + ```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. @@ -1109,10 +1149,12 @@ This API open a new scope. added: v8.0.0 napiVersion: 1 --> + ```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. @@ -1128,11 +1170,13 @@ This API can be called even if there is a pending JavaScript exception. added: v8.0.0 napiVersion: 1 --> + ```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. @@ -1146,11 +1190,13 @@ to the outer scope. added: v8.0.0 napiVersion: 1 --> + ```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. @@ -1166,6 +1212,7 @@ This API can be called even if there is a pending JavaScript exception. added: v8.0.0 napiVersion: 1 --> + ```C napi_status napi_escape_handle(napi_env env, napi_escapable_handle_scope scope, @@ -1232,6 +1279,7 @@ individual count. added: v8.0.0 napiVersion: 1 --> + ```C NAPI_EXTERN napi_status napi_create_reference(napi_env env, napi_value value, @@ -1255,6 +1303,7 @@ to the `Object` passed in. added: v8.0.0 napiVersion: 1 --> + ```C NAPI_EXTERN napi_status napi_delete_reference(napi_env env, napi_ref ref); ``` @@ -1273,11 +1322,13 @@ This API can be called even if there is a pending JavaScript exception. added: v8.0.0 napiVersion: 1 --> + ```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. @@ -1292,11 +1343,13 @@ passed in and returns the resulting reference count. added: v8.0.0 napiVersion: 1 --> + ```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. @@ -1311,6 +1364,7 @@ passed in and returns the resulting reference count. added: v8.0.0 napiVersion: 1 --> + ```C NAPI_EXTERN napi_status napi_get_reference_value(napi_env env, napi_ref ref, @@ -1517,6 +1571,7 @@ the `napi_value` in question is of the JavaScript type expected by the API. ### Enum types #### napi_valuetype + ```C typedef enum { // ES6 types (corresponds to typeof) @@ -1544,6 +1599,7 @@ A JavaScript value of type `napi_external` appears in JavaScript as a plain object such that no properties can be set on it, and no prototype. #### napi_typedarray_type + ```C typedef enum { napi_int8_array, @@ -1570,6 +1626,7 @@ Elements of this enum correspond to added: v8.0.0 napiVersion: 1 --> + ```C napi_status napi_create_array(napi_env env, napi_value* result) ``` @@ -1588,6 +1645,7 @@ JavaScript arrays are described in added: v8.0.0 napiVersion: 1 --> + ```C napi_status napi_create_array_with_length(napi_env env, size_t length, @@ -1617,6 +1675,7 @@ JavaScript arrays are described in added: v8.0.0 napiVersion: 1 --> + ```C napi_status napi_create_arraybuffer(napi_env env, size_t byte_length, @@ -1649,6 +1708,7 @@ JavaScript `ArrayBuffer` objects are described in added: v8.0.0 napiVersion: 1 --> + ```C napi_status napi_create_buffer(napi_env env, size_t size, @@ -1671,6 +1731,7 @@ fully-supported data structure, in most cases using a `TypedArray` will suffice. added: v8.0.0 napiVersion: 1 --> + ```C napi_status napi_create_buffer_copy(napi_env env, size_t length, @@ -1721,6 +1782,7 @@ JavaScript `Date` objects are described in added: v8.0.0 napiVersion: 1 --> + ```C napi_status napi_create_external(napi_env env, void* data, @@ -1754,6 +1816,7 @@ an external value yields `napi_external`. added: v8.0.0 napiVersion: 1 --> + ```C napi_status napi_create_external_arraybuffer(napi_env env, @@ -1789,6 +1852,7 @@ JavaScript `ArrayBuffer`s are described in added: v8.0.0 napiVersion: 1 --> + ```C napi_status napi_create_external_buffer(napi_env env, size_t length, @@ -1821,6 +1885,7 @@ For Node.js >=4 `Buffers` are `Uint8Array`s. added: v8.0.0 napiVersion: 1 --> + ```C napi_status napi_create_object(napi_env env, napi_value* result) ``` @@ -1842,6 +1907,7 @@ ECMAScript Language Specification. added: v8.0.0 napiVersion: 1 --> + ```C napi_status napi_create_symbol(napi_env env, napi_value description, @@ -1866,6 +1932,7 @@ of the ECMAScript Language Specification. added: v8.0.0 napiVersion: 1 --> + ```C napi_status napi_create_typedarray(napi_env env, napi_typedarray_type type, @@ -1937,6 +2004,7 @@ JavaScript `DataView` objects are described in added: v8.4.0 napiVersion: 1 --> + ```C napi_status napi_create_int32(napi_env env, int32_t value, napi_value* result) ``` @@ -1958,6 +2026,7 @@ The JavaScript `Number` type is described in added: v8.4.0 napiVersion: 1 --> + ```C napi_status napi_create_uint32(napi_env env, uint32_t value, napi_value* result) ``` @@ -1979,6 +2048,7 @@ The JavaScript `Number` type is described in added: v8.4.0 napiVersion: 1 --> + ```C napi_status napi_create_int64(napi_env env, int64_t value, napi_value* result) ``` @@ -2006,6 +2076,7 @@ outside the range of added: v8.4.0 napiVersion: 1 --> + ```C napi_status napi_create_double(napi_env env, double value, napi_value* result) ``` @@ -2099,6 +2170,7 @@ The resulting `BigInt` is calculated as: (–1)`sign_bit` (`words[0]` added: v8.0.0 napiVersion: 1 --> + ```C napi_status napi_create_string_latin1(napi_env env, const char* str, @@ -2125,6 +2197,7 @@ The JavaScript `String` type is described in added: v8.0.0 napiVersion: 1 --> + ```C napi_status napi_create_string_utf16(napi_env env, const char16_t* str, @@ -2151,6 +2224,7 @@ The JavaScript `String` type is described in added: v8.0.0 napiVersion: 1 --> + ```C napi_status napi_create_string_utf8(napi_env env, const char* str, @@ -2178,6 +2252,7 @@ The JavaScript `String` type is described in added: v8.0.0 napiVersion: 1 --> + ```C napi_status napi_get_array_length(napi_env env, napi_value value, @@ -2202,6 +2277,7 @@ of the ECMAScript Language Specification. added: v8.0.0 napiVersion: 1 --> + ```C napi_status napi_get_arraybuffer_info(napi_env env, napi_value arraybuffer, @@ -2232,6 +2308,7 @@ trigger a GC. added: v8.0.0 napiVersion: 1 --> + ```C napi_status napi_get_buffer_info(napi_env env, napi_value value, @@ -2257,6 +2334,7 @@ lifetime is not guaranteed if it's managed by the VM. added: v8.0.0 napiVersion: 1 --> + ```C napi_status napi_get_prototype(napi_env env, napi_value object, @@ -2276,6 +2354,7 @@ Returns `napi_ok` if the API succeeded. added: v8.0.0 napiVersion: 1 --> + ```C napi_status napi_get_typedarray_info(napi_env env, napi_value typedarray, @@ -2365,6 +2444,7 @@ This API returns the C double primitive of time value for the given JavaScript added: v8.0.0 napiVersion: 1 --> + ```C napi_status napi_get_value_bool(napi_env env, napi_value value, bool* result) ``` @@ -2385,6 +2465,7 @@ This API returns the C boolean primitive equivalent of the given JavaScript added: v8.0.0 napiVersion: 1 --> + ```C napi_status napi_get_value_double(napi_env env, napi_value value, @@ -2493,6 +2574,7 @@ both set to `NULL`, in order to get only `word_count`. added: v8.0.0 napiVersion: 1 --> + ```C napi_status napi_get_value_external(napi_env env, napi_value value, @@ -2514,6 +2596,7 @@ This API retrieves the external data pointer that was previously passed to added: v8.0.0 napiVersion: 1 --> + ```C napi_status napi_get_value_int32(napi_env env, napi_value value, @@ -2543,6 +2626,7 @@ result to zero. added: v8.0.0 napiVersion: 1 --> + ```C napi_status napi_get_value_int64(napi_env env, napi_value value, @@ -2574,6 +2658,7 @@ result to zero. added: v8.0.0 napiVersion: 1 --> + ```C napi_status napi_get_value_string_latin1(napi_env env, napi_value value, @@ -2602,6 +2687,7 @@ in. added: v8.0.0 napiVersion: 1 --> + ```C napi_status napi_get_value_string_utf8(napi_env env, napi_value value, @@ -2629,6 +2715,7 @@ This API returns the UTF8-encoded string corresponding the value passed in. added: v8.0.0 napiVersion: 1 --> + ```C napi_status napi_get_value_string_utf16(napi_env env, napi_value value, @@ -2656,6 +2743,7 @@ This API returns the UTF16-encoded string corresponding the value passed in. added: v8.0.0 napiVersion: 1 --> + ```C napi_status napi_get_value_uint32(napi_env env, napi_value value, @@ -2679,6 +2767,7 @@ This API returns the C primitive equivalent of the given `napi_value` as a added: v8.0.0 napiVersion: 1 --> + ```C napi_status napi_get_boolean(napi_env env, bool value, napi_value* result) ``` @@ -2698,6 +2787,7 @@ represent the given boolean value. added: v8.0.0 napiVersion: 1 --> + ```C napi_status napi_get_global(napi_env env, napi_value* result) ``` @@ -2714,6 +2804,7 @@ This API returns the `global` object. added: v8.0.0 napiVersion: 1 --> + ```C napi_status napi_get_null(napi_env env, napi_value* result) ``` @@ -2730,6 +2821,7 @@ This API returns the `null` object. added: v8.0.0 napiVersion: 1 --> + ```C napi_status napi_get_undefined(napi_env env, napi_value* result) ``` @@ -2759,6 +2851,7 @@ These APIs support doing one of the following: added: v8.0.0 napiVersion: 1 --> + ```C napi_status napi_coerce_to_bool(napi_env env, napi_value value, @@ -2781,6 +2874,7 @@ This API can be re-entrant if getters are defined on the passed-in `Object`. added: v8.0.0 napiVersion: 1 --> + ```C napi_status napi_coerce_to_number(napi_env env, napi_value value, @@ -2803,6 +2897,7 @@ This API can be re-entrant if getters are defined on the passed-in `Object`. added: v8.0.0 napiVersion: 1 --> + ```C napi_status napi_coerce_to_object(napi_env env, napi_value value, @@ -2825,6 +2920,7 @@ This API can be re-entrant if getters are defined on the passed-in `Object`. added: v8.0.0 napiVersion: 1 --> + ```C napi_status napi_coerce_to_string(napi_env env, napi_value value, @@ -2847,6 +2943,7 @@ This API can be re-entrant if getters are defined on the passed-in `Object`. added: v8.0.0 napiVersion: 1 --> + ```C napi_status napi_typeof(napi_env env, napi_value value, napi_valuetype* result) ``` @@ -2869,6 +2966,7 @@ If `value` has a type that is invalid, an error is returned. added: v8.0.0 napiVersion: 1 --> + ```C napi_status napi_instanceof(napi_env env, napi_value object, @@ -2895,6 +2993,7 @@ of the ECMAScript Language Specification. added: v8.0.0 napiVersion: 1 --> + ```C napi_status napi_is_array(napi_env env, napi_value value, bool* result) ``` @@ -2914,6 +3013,7 @@ of the ECMAScript Language Specification. added: v8.0.0 napiVersion: 1 --> + ```C napi_status napi_is_arraybuffer(napi_env env, napi_value value, bool* result) ``` @@ -2931,6 +3031,7 @@ This API checks if the `Object` passed in is an array buffer. added: v8.0.0 napiVersion: 1 --> + ```C napi_status napi_is_buffer(napi_env env, napi_value value, bool* result) ``` @@ -2969,6 +3070,7 @@ This API checks if the `Object` passed in is a date. added: v8.0.0 napiVersion: 1 --> + ```C napi_status napi_is_error(napi_env env, napi_value value, bool* result) ``` @@ -2986,6 +3088,7 @@ This API checks if the `Object` passed in is an `Error`. added: v8.0.0 napiVersion: 1 --> + ```C napi_status napi_is_typedarray(napi_env env, napi_value value, bool* result) ``` @@ -3021,6 +3124,7 @@ This API checks if the `Object` passed in is a `DataView`. added: v8.0.0 napiVersion: 1 --> + ```C napi_status napi_strict_equals(napi_env env, napi_value lhs, @@ -3065,11 +3169,14 @@ get and set properties on arbitrary JavaScript objects represented by `napi_value`. For instance, consider the following JavaScript code snippet: + ```js const obj = {}; obj.myProp = 123; ``` + The equivalent can be done using N-API values with the following snippet: + ```C napi_status status = napi_generic_failure; @@ -3089,11 +3196,14 @@ if (status != napi_ok) return status; Indexed properties can be set in a similar manner. Consider the following JavaScript snippet: + ```js const arr = []; arr[123] = 'hello'; ``` + The equivalent can be done using N-API values with the following snippet: + ```C napi_status status = napi_generic_failure; @@ -3113,12 +3223,14 @@ if (status != napi_ok) return status; Properties can be retrieved using the APIs described in this section. Consider the following JavaScript snippet: + ```js const arr = []; const value = arr[123]; ``` The following is the approximate equivalent of the N-API counterpart: + ```C napi_status status = napi_generic_failure; @@ -3134,6 +3246,7 @@ if (status != napi_ok) return status; Finally, multiple properties can also be defined on an object for performance reasons. Consider the following JavaScript: + ```js const obj = {}; Object.defineProperties(obj, { @@ -3143,6 +3256,7 @@ Object.defineProperties(obj, { ``` The following is the approximate equivalent of the N-API counterpart: + ```C napi_status status = napi_status_generic_failure; @@ -3172,6 +3286,7 @@ if (status != napi_ok) return status; ### Structures #### napi_property_attributes + ```C typedef enum { napi_default = 0, @@ -3204,6 +3319,7 @@ default. This is used only by [`napi_define_class`][]. It is ignored by `napi_define_properties`. #### napi_property_descriptor + ```C typedef struct { // One of utf8name or name should be NULL. @@ -3254,6 +3370,7 @@ this function is invoked. added: v8.0.0 napiVersion: 1 --> + ```C napi_status napi_get_property_names(napi_env env, napi_value object, @@ -3278,6 +3395,7 @@ included. added: v8.0.0 napiVersion: 1 --> + ```C napi_status napi_set_property(napi_env env, napi_value object, @@ -3299,6 +3417,7 @@ This API set a property on the `Object` passed in. added: v8.0.0 napiVersion: 1 --> + ```C napi_status napi_get_property(napi_env env, napi_value object, @@ -3320,6 +3439,7 @@ This API gets the requested property from the `Object` passed in. added: v8.0.0 napiVersion: 1 --> + ```C napi_status napi_has_property(napi_env env, napi_value object, @@ -3341,6 +3461,7 @@ This API checks if the `Object` passed in has the named property. added: v8.2.0 napiVersion: 1 --> + ```C napi_status napi_delete_property(napi_env env, napi_value object, @@ -3363,6 +3484,7 @@ This API attempts to delete the `key` own property from `object`. added: v8.2.0 napiVersion: 1 --> + ```C napi_status napi_has_own_property(napi_env env, napi_value object, @@ -3386,6 +3508,7 @@ any conversion between data types. added: v8.0.0 napiVersion: 1 --> + ```C napi_status napi_set_named_property(napi_env env, napi_value object, @@ -3408,6 +3531,7 @@ created from the string passed in as `utf8Name`. added: v8.0.0 napiVersion: 1 --> + ```C napi_status napi_get_named_property(napi_env env, napi_value object, @@ -3430,6 +3554,7 @@ created from the string passed in as `utf8Name`. added: v8.0.0 napiVersion: 1 --> + ```C napi_status napi_has_named_property(napi_env env, napi_value object, @@ -3452,6 +3577,7 @@ created from the string passed in as `utf8Name`. added: v8.0.0 napiVersion: 1 --> + ```C napi_status napi_set_element(napi_env env, napi_value object, @@ -3473,6 +3599,7 @@ This API sets and element on the `Object` passed in. added: v8.0.0 napiVersion: 1 --> + ```C napi_status napi_get_element(napi_env env, napi_value object, @@ -3494,6 +3621,7 @@ This API gets the element at the requested index. added: v8.0.0 napiVersion: 1 --> + ```C napi_status napi_has_element(napi_env env, napi_value object, @@ -3516,6 +3644,7 @@ requested index. added: v8.2.0 napiVersion: 1 --> + ```C napi_status napi_delete_element(napi_env env, napi_value object, @@ -3538,6 +3667,7 @@ This API attempts to delete the specified `index` from `object`. added: v8.0.0 napiVersion: 1 --> + ```C napi_status napi_define_properties(napi_env env, napi_value object, @@ -3587,6 +3717,7 @@ whenever `object` is garbage-collected by passing both `object` and the data to added: v8.0.0 napiVersion: 1 --> + ```C napi_status napi_call_function(napi_env env, napi_value recv, @@ -3614,6 +3745,7 @@ 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; @@ -3622,6 +3754,7 @@ function AddTwo(num) { 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; @@ -3654,6 +3787,7 @@ if (status != napi_ok) return; added: v8.0.0 napiVersion: 1 --> + ```C napi_status napi_create_function(napi_env env, const char* utf8name, @@ -3688,6 +3822,7 @@ 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"); @@ -3711,6 +3846,7 @@ 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(); @@ -3733,6 +3869,7 @@ of the ECMAScript Language Specification. added: v8.0.0 napiVersion: 1 --> + ```C napi_status napi_get_cb_info(napi_env env, napi_callback_info cbinfo, @@ -3764,6 +3901,7 @@ call like the arguments and the `this` pointer from a given callback info. added: v8.6.0 napiVersion: 1 --> + ```C napi_status napi_get_new_target(napi_env env, napi_callback_info cbinfo, @@ -3784,6 +3922,7 @@ callback is not a constructor call, the result is `NULL`. added: v8.0.0 napiVersion: 1 --> + ```C napi_status napi_new_instance(napi_env env, napi_value cons, @@ -3804,6 +3943,7 @@ 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; @@ -3814,6 +3954,7 @@ 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; @@ -3878,6 +4019,7 @@ The reference must be freed once it is no longer needed. added: v8.0.0 napiVersion: 1 --> + ```C napi_status napi_define_class(napi_env env, const char* utf8name, @@ -3941,6 +4083,7 @@ the JavaScript function and the data to [`napi_add_finalizer`][]. added: v8.0.0 napiVersion: 1 --> + ```C napi_status napi_wrap(napi_env env, napi_value js_object, @@ -3997,6 +4140,7 @@ first. added: v8.0.0 napiVersion: 1 --> + ```C napi_status napi_unwrap(napi_env env, napi_value js_object, @@ -4023,6 +4167,7 @@ then by calling `napi_unwrap()` on the wrapper object. added: v8.5.0 napiVersion: 1 --> + ```C napi_status napi_remove_wrap(napi_env env, napi_value js_object, @@ -4047,6 +4192,7 @@ JavaScript object becomes garbage-collected. + ```C napi_status napi_add_finalizer(napi_env env, napi_value js_object, @@ -4148,6 +4294,7 @@ changes: pr-url: https://github.com/nodejs/node/pull/14697 description: Added `async_resource` and `async_resource_name` parameters. --> + ```C napi_status napi_create_async_work(napi_env env, napi_value async_resource, @@ -4192,6 +4339,7 @@ the [`async_hooks` documentation][async_hooks `type`] for more information. added: v8.0.0 napiVersion: 1 --> + ```C napi_status napi_delete_async_work(napi_env env, napi_async_work work); @@ -4211,6 +4359,7 @@ This API can be called even if there is a pending JavaScript exception. added: v8.0.0 napiVersion: 1 --> + ```C napi_status napi_queue_async_work(napi_env env, napi_async_work work); @@ -4230,6 +4379,7 @@ with the same `napi_async_work` item or the result will be undefined. added: v8.0.0 napiVersion: 1 --> + ```C napi_status napi_cancel_async_work(napi_env env, napi_async_work work); @@ -4260,6 +4410,7 @@ the runtime. added: v8.6.0 napiVersion: 1 --> + ```C napi_status napi_async_init(napi_env env, napi_value async_resource, @@ -4282,6 +4433,7 @@ Returns `napi_ok` if the API succeeded. added: v8.6.0 napiVersion: 1 --> + ```C napi_status napi_async_destroy(napi_env env, napi_async_context async_context); @@ -4302,6 +4454,7 @@ changes: - version: v8.6.0 description: Added `async_context` parameter. --> + ```C napi_status napi_make_callback(napi_env env, napi_async_context async_context, @@ -4346,12 +4499,14 @@ may be required when implementing custom async behavior that does not use added: v9.6.0 napiVersion: 3 --> + ```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][]. @@ -4372,10 +4527,12 @@ the required scope. added: v9.6.0 napiVersion: 3 --> + ```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. @@ -4417,6 +4574,7 @@ The returned buffer is statically allocated and does not need to be freed. added: v8.0.0 napiVersion: 1 --> + ```C napi_status napi_get_version(napi_env env, uint32_t* result); @@ -4448,6 +4606,7 @@ support it: added: v8.5.0 napiVersion: 1 --> + ```C NAPI_EXTERN napi_status napi_adjust_external_memory(napi_env env, int64_t change_in_bytes, @@ -4482,6 +4641,7 @@ deferred object that is created by `napi_create_promise()` is freed by 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; @@ -4501,6 +4661,7 @@ 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; @@ -4528,6 +4689,7 @@ deferred = NULL; added: v8.5.0 napiVersion: 1 --> + ```C napi_status napi_create_promise(napi_env env, napi_deferred* deferred, @@ -4549,6 +4711,7 @@ This API creates a deferred object and a JavaScript promise. added: v8.5.0 napiVersion: 1 --> + ```C napi_status napi_resolve_deferred(napi_env env, napi_deferred deferred, @@ -4573,6 +4736,7 @@ The deferred object is freed upon successful completion. added: v8.5.0 napiVersion: 1 --> + ```C napi_status napi_reject_deferred(napi_env env, napi_deferred deferred, @@ -4597,6 +4761,7 @@ The deferred object is freed upon successful completion. added: v8.5.0 napiVersion: 1 --> + ```C napi_status napi_is_promise(napi_env env, napi_value promise, @@ -4618,6 +4783,7 @@ underlying JavaScript engine. added: v8.5.0 napiVersion: 1 --> + ```C NAPI_EXTERN napi_status napi_run_script(napi_env env, napi_value script, @@ -4640,6 +4806,7 @@ added: - v9.3.0 napiVersion: 2 --> + ```C NAPI_EXTERN napi_status napi_get_uv_event_loop(napi_env env, uv_loop_t** loop); @@ -4767,6 +4934,7 @@ changes: pr-url: https://github.com/nodejs/node/pull/27791 description: Made `func` parameter optional with custom `call_js_cb`. --> + ```C NAPI_EXTERN napi_status napi_create_threadsafe_function(napi_env env, @@ -4810,6 +4978,7 @@ parameters and with `undefined` as its `this` value. added: v10.6.0 napiVersion: 4 --> + ```C NAPI_EXTERN napi_status napi_get_threadsafe_function_context(napi_threadsafe_function func, @@ -4827,6 +4996,7 @@ This API may be called from any thread which makes use of `func`. added: v10.6.0 napiVersion: 4 --> + ```C NAPI_EXTERN napi_status napi_call_threadsafe_function(napi_threadsafe_function func, @@ -4854,6 +5024,7 @@ This API may be called from any thread which makes use of `func`. added: v10.6.0 napiVersion: 4 --> + ```C NAPI_EXTERN napi_status napi_acquire_threadsafe_function(napi_threadsafe_function func); @@ -4875,6 +5046,7 @@ This API may be called from any thread which will start making use of `func`. added: v10.6.0 napiVersion: 4 --> + ```C NAPI_EXTERN napi_status napi_release_threadsafe_function(napi_threadsafe_function func, @@ -4902,6 +5074,7 @@ This API may be called from any thread which will stop making use of `func`. added: v10.6.0 napiVersion: 4 --> + ```C NAPI_EXTERN napi_status napi_ref_threadsafe_function(napi_env env, napi_threadsafe_function func); @@ -4922,6 +5095,7 @@ This API may only be called from the main thread. added: v10.6.0 napiVersion: 4 --> + ```C NAPI_EXTERN napi_status napi_unref_threadsafe_function(napi_env env, napi_threadsafe_function func); diff --git a/doc/api/perf_hooks.md b/doc/api/perf_hooks.md index c143b161a3ff10..b382ae2332a8fc 100644 --- a/doc/api/perf_hooks.md +++ b/doc/api/perf_hooks.md @@ -299,6 +299,7 @@ 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 diff --git a/doc/api/process.md b/doc/api/process.md index aa7477d3bc5962..7c156e94923308 100644 --- a/doc/api/process.md +++ b/doc/api/process.md @@ -760,6 +760,7 @@ process. ```js console.log(`Current directory: ${process.cwd()}`); ``` + ## process.debugPort