archive/node
1
0
Fork 0
mirror of https://github.com/nodejs/node.git synced 2025-08-15 13:48:44 +02:00
Code Issues Projects Releases Packages Wiki Activity Actions 1

node-api,doc: update links to ecma262 with section names

Browse source 
Section numbers can change over time. Use the section names as the link
text for better readability.

Also, use https://tc39.es/ecma262/ as the unified host of living version
of ECMA-262.

PR-URL: https://github.com/nodejs/node/pull/59087
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Vladimir Morozov <vmorozov@microsoft.com>
This commit is contained in:
Chengzhong Wu 2025-07-18 13:45:52 +01:00 • committed by GitHub
parent fc4a8af430
commit 0629a175c0
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
1 changed files with 73 additions and 76 deletions
Download patch file Download diff file Expand all files Collapse all files

149
doc/api/n-api.md
View file

@ -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