diff --git a/doc/api/n-api.md b/doc/api/n-api.md index 35ad1e71a3e..77257623157 100644 --- a/doc/api/n-api.md +++ b/doc/api/n-api.md @@ -446,7 +446,7 @@ NAPI_MODULE_INIT(/* napi_env env, napi_value exports */) { ## Environment life cycle APIs -[Section 8.7][] of the [ECMAScript Language Specification][] defines the concept +[Section Agents][] of the [ECMAScript Language Specification][] defines the concept of an "Agent" as a self-contained environment in which JavaScript code runs. Multiple such Agents may be started and terminated either concurrently or in sequence by the process. @@ -2139,7 +2139,7 @@ API. ## Working with JavaScript values Node-API exposes a set of APIs to create all types of JavaScript values. -Some of these types are documented under [Section 6][] +Some of these types are documented under [Section language types][] of the [ECMAScript Language Specification][]. Fundamentally, these APIs are used to do one of the following: @@ -2245,7 +2245,7 @@ typedef enum { ``` Describes the type of a `napi_value`. This generally corresponds to the types -described in [Section 6.1][] of the ECMAScript Language Specification. +described in [Section language types][] of the ECMAScript Language Specification. In addition to types in that section, `napi_valuetype` can also represent `Function`s and `Object`s with external data. @@ -2272,7 +2272,7 @@ typedef enum { This represents the underlying binary scalar datatype of the `TypedArray`. Elements of this enum correspond to -[Section 22.2][] of the [ECMAScript Language Specification][]. +[Section TypedArray objects][] of the [ECMAScript Language Specification][]. ### Object creation functions @@ -2294,7 +2294,7 @@ Returns `napi_ok` if the API succeeded. This API returns a Node-API value corresponding to a JavaScript `Array` type. JavaScript arrays are described in -[Section 22.1][] of the ECMAScript Language Specification. +[Section Array objects][] of the ECMAScript Language Specification. #### `napi_create_array_with_length` @@ -2324,7 +2324,7 @@ 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. +[Section Array objects][] of the ECMAScript Language Specification. #### `napi_create_arraybuffer` @@ -2359,7 +2359,7 @@ 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. +[Section ArrayBuffer objects][] of the ECMAScript Language Specification. #### `napi_create_buffer` @@ -2442,7 +2442,7 @@ ECMAScript aligns with POSIX time specification. This API allocates a JavaScript `Date` object. JavaScript `Date` objects are described in -[Section 20.3][] of the ECMAScript Language Specification. +[Section Date objects][] of the ECMAScript Language Specification. #### `napi_create_external` @@ -2531,7 +2531,7 @@ The API adds a `napi_finalize` callback which will be called when the JavaScript object just created has been garbage collected. JavaScript `ArrayBuffer`s are described in -[Section 24.1][] of the ECMAScript Language Specification. +[Section ArrayBuffer objects][] of the ECMAScript Language Specification. #### `napi_create_external_buffer` @@ -2602,7 +2602,7 @@ Returns `napi_ok` if the API succeeded. This API allocates a default JavaScript `Object`. It is the equivalent of doing `new Object()` in JavaScript. -The JavaScript `Object` type is described in [Section 6.1.7][] of the +The JavaScript `Object` type is described in [Section object type][] of the ECMAScript Language Specification. #### `napi_create_symbol` @@ -2627,7 +2627,7 @@ Returns `napi_ok` if the API succeeded. This API creates a JavaScript `symbol` value from a UTF8-encoded C string. -The JavaScript `symbol` type is described in [Section 19.4][] +The JavaScript `symbol` type is described in [Section symbol type][] of the ECMAScript Language Specification. #### `node_api_symbol_for` @@ -2659,7 +2659,7 @@ This API searches in the global registry for an existing symbol with the given description. If the symbol already exists it will be returned, otherwise a new symbol will be created in the registry. -The JavaScript `symbol` type is described in [Section 19.4][] of the ECMAScript +The JavaScript `symbol` type is described in [Section symbol type][] of the ECMAScript Language Specification. #### `napi_create_typedarray` @@ -2698,7 +2698,7 @@ 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. +[Section TypedArray objects][] of the ECMAScript Language Specification. #### `node_api_create_buffer_from_arraybuffer` @@ -2765,7 +2765,7 @@ 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. +[Section DataView objects][] of the ECMAScript Language Specification. ### Functions to convert from C types to Node-API @@ -2790,7 +2790,7 @@ 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. +[Section number type][] of the ECMAScript Language Specification. #### `napi_create_uint32` @@ -2813,7 +2813,7 @@ 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. +[Section number type][] of the ECMAScript Language Specification. #### `napi_create_int64` @@ -2835,7 +2835,7 @@ Returns `napi_ok` if the API succeeded. This API is used to convert from the C `int64_t` type to the JavaScript `number` type. -The JavaScript `number` type is described in [Section 6.1.6][] +The JavaScript `number` type is described in [Section number type][] of the ECMAScript Language Specification. Note the complete range of `int64_t` cannot be represented with full precision in JavaScript. Integer values outside the range of [`Number.MIN_SAFE_INTEGER`][] `-(2**53 - 1)` - @@ -2862,7 +2862,7 @@ 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. +[Section number type][] of the ECMAScript Language Specification. #### `napi_create_bigint_int64` @@ -2962,7 +2962,7 @@ This API creates a JavaScript `string` value 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. +[Section string type][] of the ECMAScript Language Specification. #### `node_api_create_external_string_latin1` @@ -3013,7 +3013,7 @@ string. The native string may not be copied and must thus exist for the entire life cycle of the JavaScript value. The JavaScript `string` type is described in -[Section 6.1.4][] of the ECMAScript Language Specification. +[Section string type][] of the ECMAScript Language Specification. #### `napi_create_string_utf16` @@ -3041,7 +3041,7 @@ This API creates a JavaScript `string` value 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. +[Section string type][] of the ECMAScript Language Specification. #### `node_api_create_external_string_utf16` @@ -3092,7 +3092,7 @@ The native string may not be copied and must thus exist for the entire life cycle of the JavaScript value. The JavaScript `string` type is described in -[Section 6.1.4][] of the ECMAScript Language Specification. +[Section string type][] of the ECMAScript Language Specification. #### `napi_create_string_utf8` @@ -3120,7 +3120,7 @@ This API creates a JavaScript `string` value 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. +[Section string type][] of the ECMAScript Language Specification. ### Functions to create optimized property keys @@ -3169,7 +3169,7 @@ subsequent calls to this function with the same `str` pointer may benefit from a in the creation of the requested `napi_value`, depending on the engine. The JavaScript `string` type is described in -[Section 6.1.4][] of the ECMAScript Language Specification. +[Section string type][] of the ECMAScript Language Specification. #### `node_api_create_property_key_utf16` @@ -3201,7 +3201,7 @@ a UTF16-LE-encoded C string to be used as a property key for objects. The native string is copied. The JavaScript `string` type is described in -[Section 6.1.4][] of the ECMAScript Language Specification. +[Section string type][] of the ECMAScript Language Specification. #### `node_api_create_property_key_utf8` @@ -3233,7 +3233,7 @@ a UTF8-encoded C string to be used as a property key for objects. The native string is copied. The JavaScript `string` type is described in -[Section 6.1.4][] of the ECMAScript Language Specification. +[Section string type][] of the ECMAScript Language Specification. ### Functions to convert from Node-API to C types @@ -3259,7 +3259,7 @@ Returns `napi_ok` if the API succeeded. This API returns the length of an array. -`Array` length is described in [Section 22.1.4.1][] of the ECMAScript Language +`Array` length is described in [Section Array instance length][] of the ECMAScript Language Specification. #### `napi_get_arraybuffer_info` @@ -3868,8 +3868,7 @@ This API returns the Undefined object. ## Working with JavaScript values and abstract operations Node-API exposes a set of APIs to perform some abstract operations on JavaScript -values. Some of these operations are documented under [Section 7][] -of the [ECMAScript Language Specification][]. +values. These APIs support doing one of the following: @@ -3898,7 +3897,7 @@ napi_status napi_coerce_to_bool(napi_env env, Returns `napi_ok` if the API succeeded. This API implements the abstract operation `ToBoolean()` as defined in -[Section 7.1.2][] of the ECMAScript Language Specification. +[Section ToBoolean][] of the ECMAScript Language Specification. ### `napi_coerce_to_number` @@ -3920,7 +3919,7 @@ napi_status napi_coerce_to_number(napi_env env, Returns `napi_ok` if the API succeeded. This API implements the abstract operation `ToNumber()` as defined in -[Section 7.1.3][] of the ECMAScript Language Specification. +[Section ToNumber][] of the ECMAScript Language Specification. This function potentially runs JS code if the passed-in value is an object. @@ -3944,7 +3943,7 @@ napi_status napi_coerce_to_object(napi_env env, Returns `napi_ok` if the API succeeded. This API implements the abstract operation `ToObject()` as defined in -[Section 7.1.13][] of the ECMAScript Language Specification. +[Section ToObject][] of the ECMAScript Language Specification. ### `napi_coerce_to_string` @@ -3966,7 +3965,7 @@ napi_status napi_coerce_to_string(napi_env env, Returns `napi_ok` if the API succeeded. This API implements the abstract operation `ToString()` as defined in -[Section 7.1.13][] of the ECMAScript Language Specification. +[Section ToString][] of the ECMAScript Language Specification. This function potentially runs JS code if the passed-in value is an object. @@ -3991,7 +3990,7 @@ Returns `napi_ok` if the API succeeded. `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 +the object as defined in [Section typeof operator][] of the ECMAScript Language Specification. However, there are some differences: 1. It has support for detecting an External value. @@ -4024,7 +4023,7 @@ napi_status napi_instanceof(napi_env env, Returns `napi_ok` if the API succeeded. This API represents invoking the `instanceof` Operator on the object as -defined in [Section 12.10.4][] of the ECMAScript Language Specification. +defined in [Section instanceof operator][] of the ECMAScript Language Specification. ### `napi_is_array` @@ -4044,7 +4043,7 @@ napi_status napi_is_array(napi_env env, napi_value value, bool* result) Returns `napi_ok` if the API succeeded. This API represents invoking the `IsArray` operation on the object -as defined in [Section 7.2.2][] of the ECMAScript Language Specification. +as defined in [Section IsArray][] of the ECMAScript Language Specification. ### `napi_is_arraybuffer` @@ -4188,7 +4187,7 @@ napi_status napi_strict_equals(napi_env env, Returns `napi_ok` if the API succeeded. This API represents the invocation of the Strict Equality algorithm as -defined in [Section 7.2.14][] of the ECMAScript Language Specification. +defined in [Section IsStrctEqual][] of the ECMAScript Language Specification. ### `napi_detach_arraybuffer` @@ -4217,7 +4216,7 @@ detachable. For example, V8 requires that the `ArrayBuffer` be external, that is, created with [`napi_create_external_arraybuffer`][]. This API represents the invocation of the `ArrayBuffer` detach operation as -defined in [Section 24.1.1.3][] of the ECMAScript Language Specification. +defined in [Section detachArrayBuffer][] of the ECMAScript Language Specification. ### `napi_is_detached_arraybuffer` @@ -4244,14 +4243,13 @@ Returns `napi_ok` if the API succeeded. The `ArrayBuffer` is considered detached if its internal data is `null`. This API represents the invocation of the `ArrayBuffer` `IsDetachedBuffer` -operation as defined in [Section 24.1.1.2][] of the ECMAScript Language +operation as defined in [Section isDetachedBuffer][] of the ECMAScript Language Specification. ## Working with JavaScript properties Node-API exposes a set of APIs to get and set properties on JavaScript -objects. Some of these types are documented under [Section 7][] of the -[ECMAScript Language Specification][]. +objects. Properties in JavaScript are represented as a tuple of a key and a value. Fundamentally, all property keys in Node-API can be represented in one of the @@ -4421,7 +4419,7 @@ typedef enum { `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][] +attributes listed in [Section property attributes][] of the [ECMAScript Language Specification][]. They can be one or more of the following bitflags: @@ -4430,7 +4428,7 @@ They can be one or more of the following bitflags: * `napi_writable`: The property is writable. * `napi_enumerable`: The property is enumerable. * `napi_configurable`: The property is configurable as defined in - [Section 6.1.7.1][] of the [ECMAScript Language Specification][]. + [Section property attributes][] of the [ECMAScript Language Specification][]. * `napi_static`: 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`. @@ -4856,7 +4854,7 @@ 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 ECMA-262 +`DefineOwnProperty()` (described in [Section DefineOwnProperty][] of the ECMA-262 specification). #### `napi_object_freeze` @@ -5084,7 +5082,7 @@ be associated with the resulting JavaScript function (which is returned in the `result` parameter) and freed whenever the function is garbage-collected by passing both the JavaScript function and the data to [`napi_add_finalizer`][]. -JavaScript `Function`s are described in [Section 19.2][] of the ECMAScript +JavaScript `Function`s are described in [Section Function objects][] of the ECMAScript Language Specification. ### `napi_get_cb_info` @@ -6154,7 +6152,7 @@ increased the external memory. ## Promises Node-API provides facilities for creating `Promise` objects as described in -[Section 25.4][] of the ECMA specification. It implements promises as a pair of +[Section Promise objects][] 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 @@ -6740,7 +6738,7 @@ the add-on's file name during loading. [C++ Addons]: addons.md [CMake]: https://cmake.org [CMake.js]: https://github.com/cmake-js/cmake-js -[ECMAScript Language Specification]: https://tc39.github.io/ecma262/ +[ECMAScript Language Specification]: https://tc39.es/ecma262/ [Error handling]: #error-handling [GCC]: https://gcc.gnu.org [GYP]: https://gyp.gsrc.io @@ -6750,40 +6748,39 @@ the add-on's file name during loading. [Node-API Media]: https://github.com/nodejs/abi-stable-node/blob/HEAD/node-api-media.md [Object lifetime management]: #object-lifetime-management [Object wrap]: #object-wrap -[Section 12.10.4]: https://tc39.github.io/ecma262/#sec-instanceofoperator -[Section 12.5.5]: https://tc39.github.io/ecma262/#sec-typeof-operator -[Section 19.2]: https://tc39.github.io/ecma262/#sec-function-objects -[Section 19.4]: https://tc39.github.io/ecma262/#sec-symbol-objects -[Section 20.3]: https://tc39.github.io/ecma262/#sec-date-objects -[Section 22.1]: https://tc39.github.io/ecma262/#sec-array-objects -[Section 22.1.4.1]: https://tc39.github.io/ecma262/#sec-properties-of-array-instances-length -[Section 22.2]: https://tc39.github.io/ecma262/#sec-typedarray-objects -[Section 24.1]: https://tc39.github.io/ecma262/#sec-arraybuffer-objects -[Section 24.1.1.2]: https://tc39.es/ecma262/#sec-isdetachedbuffer -[Section 24.1.1.3]: https://tc39.es/ecma262/#sec-detacharraybuffer -[Section 24.3]: https://tc39.github.io/ecma262/#sec-dataview-objects -[Section 25.4]: https://tc39.github.io/ecma262/#sec-promise-objects -[Section 6]: https://tc39.github.io/ecma262/#sec-ecmascript-data-types-and-values -[Section 6.1]: https://tc39.github.io/ecma262/#sec-ecmascript-language-types -[Section 6.1.4]: https://tc39.github.io/ecma262/#sec-ecmascript-language-types-string-type -[Section 6.1.6]: https://tc39.github.io/ecma262/#sec-ecmascript-language-types-number-type -[Section 6.1.7]: https://tc39.github.io/ecma262/#sec-object-type -[Section 6.1.7.1]: https://tc39.github.io/ecma262/#table-2 -[Section 7]: https://tc39.github.io/ecma262/#sec-abstract-operations -[Section 7.1.13]: https://tc39.github.io/ecma262/#sec-toobject -[Section 7.1.2]: https://tc39.github.io/ecma262/#sec-toboolean -[Section 7.1.3]: https://tc39.github.io/ecma262/#sec-tonumber -[Section 7.2.14]: https://tc39.github.io/ecma262/#sec-strict-equality-comparison -[Section 7.2.2]: https://tc39.github.io/ecma262/#sec-isarray -[Section 8.7]: https://tc39.es/ecma262/#sec-agents -[Section 9.1.6]: https://tc39.github.io/ecma262/#sec-ordinary-object-internal-methods-and-internal-slots-defineownproperty-p-desc +[Section Agents]: https://tc39.es/ecma262/#sec-agents +[Section Array instance length]: https://tc39.es/ecma262/#sec-properties-of-array-instances-length +[Section Array objects]: https://tc39.es/ecma262/#sec-array-objects +[Section ArrayBuffer objects]: https://tc39.es/ecma262/#sec-arraybuffer-objects +[Section DataView objects]: https://tc39.es/ecma262/#sec-dataview-objects +[Section Date objects]: https://tc39.es/ecma262/#sec-date-objects +[Section DefineOwnProperty]: https://tc39.es/ecma262/#sec-ordinary-object-internal-methods-and-internal-slots-defineownproperty-p-desc +[Section Function objects]: https://tc39.es/ecma262/#sec-function-objects +[Section IsArray]: https://tc39.es/ecma262/#sec-isarray +[Section IsStrctEqual]: https://tc39.es/ecma262/#sec-strict-equality-comparison +[Section Promise objects]: https://tc39.es/ecma262/#sec-promise-objects +[Section ToBoolean]: https://tc39.es/ecma262/#sec-toboolean +[Section ToNumber]: https://tc39.es/ecma262/#sec-tonumber +[Section ToObject]: https://tc39.es/ecma262/#sec-toobject +[Section ToString]: https://tc39.es/ecma262/#sec-tostring +[Section TypedArray objects]: https://tc39.es/ecma262/#sec-typedarray-objects +[Section detachArrayBuffer]: https://tc39.es/ecma262/#sec-detacharraybuffer +[Section instanceof operator]: https://tc39.es/ecma262/#sec-instanceofoperator +[Section isDetachedBuffer]: https://tc39.es/ecma262/#sec-isdetachedbuffer +[Section language types]: https://tc39.es/ecma262/#sec-ecmascript-data-types-and-values +[Section number type]: https://tc39.es/ecma262/#sec-ecmascript-language-types-number-type +[Section object type]: https://tc39.es/ecma262/#sec-object-type +[Section property attributes]: https://tc39.es/ecma262/#sec-property-attributes +[Section string type]: https://tc39.es/ecma262/#sec-ecmascript-language-types-string-type +[Section symbol type]: https://tc39.es/ecma262/#sec-ecmascript-language-types-symbol-type +[Section typeof operator]: https://tc39.es/ecma262/#sec-typeof-operator [Travis CI]: https://travis-ci.org [Visual Studio]: https://visualstudio.microsoft.com [Working with JavaScript properties]: #working-with-javascript-properties [Xcode]: https://developer.apple.com/xcode/ [`'uncaughtException'`]: process.md#event-uncaughtexception -[`Number.MAX_SAFE_INTEGER`]: https://tc39.github.io/ecma262/#sec-number.max_safe_integer -[`Number.MIN_SAFE_INTEGER`]: https://tc39.github.io/ecma262/#sec-number.min_safe_integer +[`Number.MAX_SAFE_INTEGER`]: https://tc39.es/ecma262/#sec-number.max_safe_integer +[`Number.MIN_SAFE_INTEGER`]: https://tc39.es/ecma262/#sec-number.min_safe_integer [`Worker`]: worker_threads.md#class-worker [`async_hooks.executionAsyncResource()`]: async_hooks.md#async_hooksexecutionasyncresource [`build_with_cmake`]: https://github.com/nodejs/node-addon-examples/tree/main/src/8-tooling/build_with_cmake