n-api.md - OpenGrok cross reference for /third

Lines Matching refs:JavaScript
10 independent from the underlying JavaScript runtime (for example, V8) and is
13 addons from changes in the underlying JavaScript engine and allow modules
23 JavaScript values. Concepts and operations generally map to ideas specified
30 * All JavaScript values are abstracted behind an opaque type named
126 Unlike modules written in JavaScript, developing and deploying Node.js
339 exposes the actual functionality to the JavaScript environment so that the
425 of an "Agent" as a self-contained environment in which JavaScript code runs.
600 not access the state of the JavaScript engine and are thus safe to call from
603 access the JavaScript engine state is not allowed. Attempting to do so without
611 This is an opaque pointer that is used to represent a JavaScript value.
620 This is an opaque pointer that represents a JavaScript function which can be
668 JavaScript, a default handle scope will exist. If the user does not explicitly
673 of JavaScript values.
700 users to manage the lifetimes of JavaScript values, including defining their
715 with which JavaScript objects or [externals][] can be "tagged" in order to
721 type tag that had been previously applied to the JavaScript object.
763 exposed to JavaScript via Node-API. Callback functions should satisfy the
797 Since these functions may be called while the JavaScript engine is in a state
798 where it cannot execute JavaScript code, only Node-APIs which accept a
801 require access to the JavaScript engine's state to run after the current
860 JavaScript or interact with JavaScript objects. Node-API calls should be in the
862 it will likely result in execution of JavaScript.
893 necessary for a call into JavaScript, usually via `napi_call_function`, and then
894 make the call into JavaScript.
897 parameter and the JavaScript function to call is given in the `js_callback`
901 sufficient to call the JavaScript function via `napi_call_function` rather than
915 * `[in] js_callback`: The JavaScript function to call, or `NULL` if the
922   the callback to convert this native data to JavaScript values (with Node-API
977 Node-API uses both return values and JavaScript exceptions for error handling.
986 no uncaught JavaScript exception was thrown. If an error occurred AND
1068 This API can be called even if there is a pending JavaScript exception.
1072 Any Node-API function call may result in a pending JavaScript exception. This is
1074 execution of JavaScript.
1087 called to allow for some minimal cleanup before returning to JavaScript.
1095 execution will return to JavaScript. As part of the transition back to
1096 JavaScript, the exception will be thrown at the point in the JavaScript
1100 JavaScript where the exception can be handled.
1108 the last JavaScript `Object` thrown. If it is determined, after
1111 JavaScript value to be thrown.
1115 of a JavaScript `Error` object: [`napi_throw_error`][],
1122 JavaScript `Error` object.
1161 * `[in] error`: The JavaScript value to be thrown.
1165 This API throws the JavaScript value provided.
1186 This API throws a JavaScript `Error` with the text provided.
1207 This API throws a JavaScript `TypeError` with the text provided.
1228 This API throws a JavaScript `RangeError` with the text provided.
1251 This API throws a JavaScript `SyntaxError` with the text provided.
1292 * `[in] msg`: `napi_value` that references a JavaScript `string` to be used as
1298 This API returns a JavaScript `Error` with the text provided.
1317 * `[in] msg`: `napi_value` that references a JavaScript `string` to be used as
1323 This API returns a JavaScript `TypeError` with the text provided.
1342 * `[in] msg`: `napi_value` that references a JavaScript `string` to be used as
1348 This API returns a JavaScript `RangeError` with the text provided.
1369 * `[in] msg`: `napi_value` that references a JavaScript `string` to be used as
1375 This API returns a JavaScript `SyntaxError` with the text provided.
1394 This API can be called even if there is a pending JavaScript exception.
1412 This API can be called even if there is a pending JavaScript exception.
1428 Trigger an `'uncaughtException'` in JavaScript. Useful if an async
1459 This API can be called even if there is a pending JavaScript exception.
1591 This API can be called even if there is a pending JavaScript exception.
1635 This API can be called even if there is a pending JavaScript exception.
1653 * `[in] escapee`: `napi_value` representing the JavaScript `Object` to be
1660 This API promotes the handle to the JavaScript object so that it is valid
1664 This API can be called even if there is a pending JavaScript exception.
1691 or the JavaScript `Symbol()` constructor calls. Globally registered symbols
1692 created with the `node_api_symbol_for` function or JavaScript `Symbol.for()`
1774 This API can be called even if there is a pending JavaScript exception.
1841 JavaScript value associated with the `napi_ref`. Otherwise, result
1977 possible with JavaScript execution disallowed, like on the request of
1979 registered `napi_finalize` callbacks of JavaScript objects, thread-safe
2104 [Working with JavaScript properties][].
2109 ## Working with JavaScript values
2111 Node-API exposes a set of APIs to create all types of JavaScript values.
2117 1. Create a new JavaScript object
2123 Any Node-API call that requires a JavaScript value takes in a `napi_value`.
2126 the `napi_value` in question is of the JavaScript type expected by the API.
2222 A JavaScript value of type `napi_external` appears in JavaScript as a plain
2261 * `[out] result`: A `napi_value` representing a JavaScript `Array`.
2265 This API returns a Node-API value corresponding to a JavaScript `Array` type.
2266 JavaScript arrays are described in
2284 * `[out] result`: A `napi_value` representing a JavaScript `Array`.
2288 This API returns a Node-API value corresponding to a JavaScript `Array` type.
2296 JavaScript arrays are described in
2317 * `[out] result`: A `napi_value` representing a JavaScript `ArrayBuffer`.
2321 This API returns a Node-API value corresponding to a JavaScript `ArrayBuffer`.
2328 written to directly from native code. To write to this buffer from JavaScript,
2331 JavaScript `ArrayBuffer` objects are described in
2405 * `[out] result`: A `napi_value` representing a JavaScript `Date`.
2412 This API allocates a JavaScript `Date` object.
2414 JavaScript `Date` objects are described in
2442 This API allocates a JavaScript value with external data attached to it. This
2443 is used to pass external data through JavaScript code, so it can be retrieved
2446 The API adds a `napi_finalize` callback which will be called when the JavaScript
2478 * `[out] result`: A `napi_value` representing a JavaScript `ArrayBuffer`.
2495 This API returns a Node-API value corresponding to a JavaScript `ArrayBuffer`.
2500 The API adds a `napi_finalize` callback which will be called when the JavaScript
2503 JavaScript `ArrayBuffer`s are described in
2525 * `[in] data`: Raw pointer to the underlying buffer to expose to JavaScript.
2551 The API adds a `napi_finalize` callback which will be called when the JavaScript
2568 * `[out] result`: A `napi_value` representing a JavaScript `Object`.
2572 This API allocates a default JavaScript `Object`.
2573 It is the equivalent of doing `new Object()` in JavaScript.
2575 The JavaScript `Object` type is described in [Section 6.1.7][] of the
2592 * `[in] description`: Optional `napi_value` which refers to a JavaScript
2594 * `[out] result`: A `napi_value` representing a JavaScript `symbol`.
2598 This API creates a JavaScript `symbol` value from a UTF8-encoded C string.
2600 The JavaScript `symbol` type is described in [Section 19.4][]
2622 * `[out] result`: A `napi_value` representing a JavaScript `symbol`.
2630 The JavaScript `symbol` type is described in [Section 19.4][] of the ECMAScript
2655 * `[out] result`: A `napi_value` representing a JavaScript `TypedArray`.
2659 This API creates a JavaScript `TypedArray` object over an existing
2668 JavaScript `TypedArray` objects are described in
2691 * `[out] result`: A `napi_value` representing a JavaScript `DataView`.
2695 This API creates a JavaScript `DataView` object over an existing `ArrayBuffer`.
2703 JavaScript `DataView` objects are described in
2720 * `[in] value`: Integer value to be represented in JavaScript.
2721 * `[out] result`: A `napi_value` representing a JavaScript `number`.
2725 This API is used to convert from the C `int32_t` type to the JavaScript
2728 The JavaScript `number` type is described in
2743 * `[in] value`: Unsigned integer value to be represented in JavaScript.
2744 * `[out] result`: A `napi_value` representing a JavaScript `number`.
2748 This API is used to convert from the C `uint32_t` type to the JavaScript
2751 The JavaScript `number` type is described in
2766 * `[in] value`: Integer value to be represented in JavaScript.
2767 * `[out] result`: A `napi_value` representing a JavaScript `number`.
2771 This API is used to convert from the C `int64_t` type to the JavaScript
2774 The JavaScript `number` type is described in [Section 6.1.6][]
2776 cannot be represented with full precision in JavaScript. Integer values
2792 * `[in] value`: Double-precision value to be represented in JavaScript.
2793 * `[out] result`: A `napi_value` representing a JavaScript `number`.
2797 This API is used to convert from the C `double` type to the JavaScript
2800 The JavaScript `number` type is described in
2817 * `[in] value`: Integer value to be represented in JavaScript.
2818 * `[out] result`: A `napi_value` representing a JavaScript `BigInt`.
2822 This API converts the C `int64_t` type to the JavaScript `BigInt` type.
2838 * `[in] value`: Unsigned integer value to be represented in JavaScript.
2839 * `[out] result`: A `napi_value` representing a JavaScript `BigInt`.
2843 This API converts the C `uint64_t` type to the JavaScript `BigInt` type.
2865 * `[out] result`: A `napi_value` representing a JavaScript `BigInt`.
2893 * `[out] result`: A `napi_value` representing a JavaScript `string`.
2897 This API creates a JavaScript `string` value from an ISO-8859-1-encoded C
2900 The JavaScript `string` type is described in
2936     doesn't need to be notified when the corresponding JavaScript string is
2940 * `[out] result`: A `napi_value` representing a JavaScript `string`.
2946 This API creates a JavaScript `string` value from an ISO-8859-1-encoded C
2948 life cycle of the JavaScript value.
2950 The JavaScript `string` type is described in
2971 * `[out] result`: A `napi_value` representing a JavaScript `string`.
2975 This API creates a JavaScript `string` value from a UTF16-LE-encoded C string.
2978 The JavaScript `string` type is described in
3014     doesn't need to be notified when the corresponding JavaScript string is
3018 * `[out] result`: A `napi_value` representing a JavaScript `string`.
3024 This API creates a JavaScript `string` value from a UTF16-LE-encoded C string.
3026 cycle of the JavaScript value.
3028 The JavaScript `string` type is described in
3049 * `[out] result`: A `napi_value` representing a JavaScript `string`.
3053 This API creates a JavaScript `string` value from a UTF8-encoded C string.
3056 The JavaScript `string` type is described in
3075 * `[in] value`: `napi_value` representing the JavaScript `Array` whose length is
3166 * `[in] object`: `napi_value` representing JavaScript `Object` whose prototype
3263 * `[in] value`: `napi_value` representing a JavaScript `Date`.
3273 This API returns the C double primitive of time value for the given JavaScript
3288 * `[in] value`: `napi_value` representing JavaScript `Boolean`.
3289 * `[out] result`: C boolean primitive equivalent of the given JavaScript
3295 This API returns the C boolean primitive equivalent of the given JavaScript
3312 * `[in] value`: `napi_value` representing JavaScript `number`.
3313 * `[out] result`: C double primitive equivalent of the given JavaScript
3319 This API returns the C double primitive equivalent of the given JavaScript
3337 * `[in] value`: `napi_value` representing JavaScript `BigInt`.
3338 * `[out] result`: C `int64_t` primitive equivalent of the given JavaScript
3346 This API returns the C `int64_t` primitive equivalent of the given JavaScript
3364 * `[in] value`: `napi_value` representing JavaScript `BigInt`.
3365 * `[out] result`: C `uint64_t` primitive equivalent of the given JavaScript
3373 This API returns the C `uint64_t` primitive equivalent of the given JavaScript
3392 * `[in] value`: `napi_value` representing JavaScript `BigInt`.
3393 * `[out] sign_bit`: Integer representing if the JavaScript `BigInt` is positive
3420 * `[in] value`: `napi_value` representing JavaScript external value.
3421 * `[out] result`: Pointer to the data wrapped by the JavaScript external value.
3443 * `[in] value`: `napi_value` representing JavaScript `number`.
3444 * `[out] result`: C `int32` primitive equivalent of the given JavaScript
3451 of the given JavaScript `number`.
3474 * `[in] value`: `napi_value` representing JavaScript `number`.
3475 * `[out] result`: C `int64` primitive equivalent of the given JavaScript
3481 This API returns the C `int64` primitive equivalent of the given JavaScript
3507 * `[in] value`: `napi_value` representing JavaScript string.
3538 * `[in] value`: `napi_value` representing JavaScript string.
3568 * `[in] value`: `napi_value` representing JavaScript string.
3596 * `[in] value`: `napi_value` representing JavaScript `number`.
3621 * `[out] result`: `napi_value` representing JavaScript `Boolean` singleton to
3626 This API is used to return the JavaScript singleton object that is used to
3641 * `[out] result`: `napi_value` representing JavaScript `global` object.
3659 * `[out] result`: `napi_value` representing JavaScript `null` object.
3677 * `[out] result`: `napi_value` representing JavaScript Undefined value.
3683 ## Working with JavaScript values and abstract operations
3685 Node-API exposes a set of APIs to perform some abstract operations on JavaScript
3691 1. Coerce JavaScript values to specific JavaScript types (such as `number` or
3693 2. Check the type of a JavaScript value.
3694 3. Check for equality between two JavaScript values.
3710 * `[in] value`: The JavaScript value to coerce.
3711 * `[out] result`: `napi_value` representing the coerced JavaScript `Boolean`.
3732 * `[in] value`: The JavaScript value to coerce.
3733 * `[out] result`: `napi_value` representing the coerced JavaScript `number`.
3756 * `[in] value`: The JavaScript value to coerce.
3757 * `[out] result`: `napi_value` representing the coerced JavaScript `Object`.
3778 * `[in] value`: The JavaScript value to coerce.
3779 * `[out] result`: `napi_value` representing the coerced JavaScript `string`.
3800 * `[in] value`: The JavaScript value whose type to query.
3801 * `[out] result`: The type of the JavaScript value.
3833 * `[in] object`: The JavaScript value to check.
3834 * `[in] constructor`: The JavaScript function object of the constructor function
3856 * `[in] value`: The JavaScript value to check.
3876 * `[in] value`: The JavaScript value to check.
3895 * `[in] value`: The JavaScript value to check.
3919 * `[in] value`: The JavaScript value to check.
3920 * `[out] result`: Whether the given `napi_value` represents a JavaScript `Date`
3939 * `[in] value`: The JavaScript value to check.
3958 * `[in] value`: The JavaScript value to check.
3977 * `[in] value`: The JavaScript value to check.
3999 * `[in] lhs`: The JavaScript value to check.
4000 * `[in] rhs`: The JavaScript value to check against.
4024 * `[in] arraybuffer`: The JavaScript `ArrayBuffer` to be detached.
4054 * `[in] arraybuffer`: The JavaScript `ArrayBuffer` to be checked.
4065 ## Working with JavaScript properties
4067 Node-API exposes a set of APIs to get and set properties on JavaScript
4071 Properties in JavaScript are represented as a tuple of a key and a value.
4077 * JavaScript value: these are represented in Node-API by `napi_value`. This can
4081 Any Node-API call that requires a JavaScript value takes in a `napi_value`.
4083 `napi_value` in question is of the JavaScript type expected by the API.
4086 get and set properties on arbitrary JavaScript objects represented by
4089 For instance, consider the following JavaScript code snippet:
4116 JavaScript snippet:
4143 Consider the following JavaScript snippet:
4166 reasons. Consider the following JavaScript:
4238 set on a JavaScript object. Other than `napi_static` they correspond to the
4254 * `napi_default_jsproperty`: Like a property set via assignment in JavaScript,
4278 * `name`: Optional `napi_value` that points to a JavaScript string or symbol
4287   the property is accessed from JavaScript code (or if a get on the property is
4292   the property is set from JavaScript code (or if a set on the property is
4295   property to be a JavaScript function represented by `method`. If this is
4320 * `[out] result`: A `napi_value` representing an array of JavaScript values
4356 * `[out] result`: A `napi_value` representing an array of JavaScript values
4728 ## Working with JavaScript functions
4730 Node-API provides a set of APIs that allow JavaScript code to
4733 the `napi_callback` type. When the JavaScript VM calls back to
4743 JavaScript functions from native code. One can either call a function
4744 like a regular JavaScript function call, or as a constructor
4770 * `[in] func`: `napi_value` representing the JavaScript function to be invoked.
4772 * `[in] argv`: Array of `napi_values` representing JavaScript values passed in
4774 * `[out] result`: `napi_value` representing the JavaScript object returned.
4778 This method allows a JavaScript function object to be called from a native
4780 native code _into_ JavaScript. For the special case of calling into JavaScript
4783 A sample use case might look as follows. Consider the following JavaScript
4841   visible within JavaScript as the new function object's `name` property.
4848 * `[out] result`: `napi_value` representing the JavaScript function object for
4855 _from_ JavaScript.
4859 to JavaScript, in order for the function to be accessible from script.
4887 Given the above code, the add-on can be used from JavaScript as follows:
4898 be associated with the resulting JavaScript function (which is returned in the
4900 passing both the JavaScript function and the data to [`napi_add_finalizer`][].
4902 JavaScript `Function`s are described in [Section 19.2][] of the ECMAScript
4932 * `[out] thisArg`: Receives the JavaScript `this` argument for the call.
4980 * `[in] cons`: `napi_value` representing the JavaScript function to be invoked
4983 * `[in] argv`: Array of JavaScript values as `napi_value` representing the
4986 * `[out] result`: `napi_value` representing the JavaScript object returned,
4989 This method is used to instantiate a new JavaScript value using a given
5029 constructor and methods can be called from JavaScript.
5031 1. The [`napi_define_class`][] API defines a JavaScript class with constructor,
5034 2. When JavaScript code invokes the constructor, the constructor callback
5035    uses [`napi_wrap`][] to wrap a new C++ instance in a JavaScript object,
5037 3. When JavaScript code invokes a method or property accessor on the class,
5064 a JavaScript object is a wrapper for a certain native type. This is the case
5065 especially when wrapped JavaScript objects are passed back into the addon via
5072 // `openDatabase()` returns a JavaScript object that wraps a native database
5076 // `query()` returns a JavaScript object that wraps a native query handle.
5102 `queryHasRecords()` has to perform a type validation. Retaining the JavaScript
5119 along with a JavaScript object or [external][] stored in a `napi_value` to
5120 `napi_type_tag_object()`, the JavaScript object will be "marked" with the
5121 type tag. The "mark" is invisible on the JavaScript side. When a JavaScript
5123 along with the original type tag to determine whether the JavaScript object was
5170 // Later when we receive a JavaScript object purporting to be a database handle
5219 * `[in] utf8name`: Name of the JavaScript constructor function. For clarity,
5238 Defines a JavaScript class, including:
5240 * A JavaScript constructor function that has the class name. When wrapping a
5243   JavaScript object instance being constructed using [`napi_wrap`][].
5251   instance placed inside the JavaScript object instance by using
5256 then wraps the new C++ instance in a JavaScript object, and returns the wrapper
5259 The JavaScript constructor function returned from [`napi_define_class`][] is
5268 with the resulting JavaScript constructor (which is returned in the `result`
5270 the JavaScript function and the data to [`napi_add_finalizer`][].
5289 * `[in] js_object`: The JavaScript object that will be the wrapper for the
5292   JavaScript object.
5294   native instance when the JavaScript object has been garbage-collected.
5302 Wraps a native instance in a JavaScript object. The native instance can be
5305 When JavaScript code invokes a constructor for a class that was defined using
5309 JavaScript object that is the `this` argument to the constructor callback.
5355 Retrieves a native instance that was previously wrapped in a JavaScript
5358 When JavaScript code invokes a method or property accessor on the class, the
5383 Retrieves a native instance that was previously wrapped in the JavaScript
5386 JavaScript object becomes garbage-collected.
5404 * `[in] js_object`: The JavaScript object or [external][] to be marked.
5409 Associates the value of the `type_tag` pointer with the JavaScript object or
5434 * `[in] js_object`: The JavaScript object or [external][] whose type tag to
5464 * `[in] js_object`: The JavaScript object to which the native data will be
5468   native data when the JavaScript object has been garbage-collected.
5472 * `[out] result`: Optional reference to the JavaScript object.
5476 Adds a `napi_finalize` callback which will be called when the JavaScript object
5479 This API can be called multiple times on a single JavaScript object.
5504   native data when the JavaScript object has been garbage-collected.
5542 that could result in the execution of JavaScript or interaction with
5543 JavaScript objects. Most often, any code that needs to make Node-API
5546 it will likely execute JavaScript.
5648 This API can be called even if there is a pending JavaScript exception.
5695 This API can be called even if there is a pending JavaScript exception.
5733 garbage collected by JavaScript engine before the `napi_async_context` was
5762 This API can be called even if there is a pending JavaScript exception.
5794 * `[in] func`: `napi_value` representing the JavaScript function to be invoked.
5796 * `[in] argv`: Array of JavaScript values as `napi_value` representing the
5799 * `[out] result`: `napi_value` representing the JavaScript object returned.
5803 This method allows a JavaScript function object to be called from a native
5805 _from_ native code back _into_ JavaScript _after_ returning from an async
5817 JavaScript during the callback are ran before returning back to C/C++.
5864 This API can be called even if there is a pending JavaScript exception.
5946   alive by JavaScript objects.
5952 memory that is kept alive by JavaScript objects (i.e. a JavaScript object
5967 be returned to JavaScript where it can be used in the usual fashion.
6030 * `[out] promise`: The JavaScript promise associated with the deferred object.
6034 This API creates a deferred object and a JavaScript promise.
6053 This API resolves a JavaScript promise by way of the deferred object
6054 with which it is associated. Thus, it can only be used to resolve JavaScript
6079 This API rejects a JavaScript promise by way of the deferred object
6080 with which it is associated. Thus, it can only be used to reject JavaScript
6108 Node-API provides an API for executing a string containing JavaScript using the
6109 underlying JavaScript engine.
6125 * `[in] script`: A JavaScript string containing the script to execute.
6128 This function executes a string of JavaScript code and returns its result with
6165 JavaScript functions can normally only be called from a native addon's main
6170 When an addon has additional threads and JavaScript functions need to be invoked
6173 JavaScript function on their behalf. The thread-safe function APIs provide an
6179 `napi_value` that holds a JavaScript function which can be called from multiple
6181 JavaScript callback is to be called will be placed in a queue, and, for each
6182 value in the queue, a call will eventually be made to the JavaScript function.
6199 JavaScript. `napi_call_threadsafe_function()` accepts a parameter which controls
6208 from a JavaScript thread, because, if the queue is full, it may cause the
6209 JavaScript thread to deadlock.
6211 The actual call into JavaScript is controlled by the callback given via the
6215 callback will be used, and the resulting JavaScript call will have no arguments.
6216 The `call_js_cb` callback receives the JavaScript function to call as a
6220 as `napi_call_function()` to call into JavaScript.
6223 to indicate that calls into JavaScript are no longer possible, while items
6227 It is not necessary to call into JavaScript via `napi_make_callback()` because
6321 * `[in] func`: An optional JavaScript function to call from another thread. It
6325 * `[in] async_resource_name`: A JavaScript string to provide an identifier for
6337 * `[in] call_js_cb`: Optional callback which calls the JavaScript function in
6339   main thread. If not given, the JavaScript function will be called with no
6342 * `[out] result`: The asynchronous thread-safe JavaScript function.
6392 * `[in] func`: The asynchronous thread-safe JavaScript function to invoke.
6393 * `[in] data`: Data to send into JavaScript via the callback `call_js_cb`
6394   provided during the creation of the thread-safe JavaScript function.
6400 This API should not be called with `napi_tsfn_blocking` from a JavaScript
6401 thread, because, if the queue is full, it may cause the JavaScript thread to
6422 * `[in] func`: The asynchronous thread-safe JavaScript function to start making
6445 * `[in] func`: The asynchronous thread-safe JavaScript function whose reference
6579 [Working with JavaScript properties]: #working-with-javascript-properties