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

Lines Matching refs:JavaScript
9 independent from the underlying JavaScript runtime (for example, V8) and is
12 addons from changes in the underlying JavaScript engine and allow modules
22 JavaScript values. Concepts and operations generally map to ideas specified
29 * All JavaScript values are abstracted behind an opaque type named
124 Unlike modules written in JavaScript, developing and deploying Node.js
376 exposes the actual functionality to the JavaScript environment so that the
460 of an "Agent" as a self-contained environment in which JavaScript code runs.
623 This is an opaque pointer that is used to represent a JavaScript value.
631 This is an opaque pointer that represents a JavaScript function which can be
676 JavaScript, a default handle scope will exist. If the user does not explicitly
681 of JavaScript values.
704 users to manage the lifetimes of JavaScript values, including defining their
718 with which JavaScript objects can be "tagged" in order to ensure that they are
724 previously applied to the JavaScript object.
759 exposed to JavaScript via Node-API. Callback functions should satisfy the
803 JavaScript or interact with JavaScript objects. Node-API calls should be in the
805 it will likely result in execution of JavaScript.
833 necessary for a call into JavaScript, usually via `napi_call_function`, and then
834 make the call into JavaScript.
837 parameter and the JavaScript function to call is given in the `js_callback`
841 sufficient to call the JavaScript function via `napi_call_function` rather than
855 * `[in] js_callback`: The JavaScript function to call, or `NULL` if the
862   the callback to convert this native data to JavaScript values (with Node-API
896 Node-API uses both return values and JavaScript exceptions for error handling.
905 no uncaught JavaScript exception was thrown. If an error occurred AND
981 This API can be called even if there is a pending JavaScript exception.
985 Any Node-API function call may result in a pending JavaScript exception. This is
987 execution of JavaScript.
1000 called to allow for some minimal cleanup before returning to JavaScript.
1008 execution will return to JavaScript. As part of the transition back to
1009 JavaScript, the exception will be thrown at the point in the JavaScript
1013 JavaScript where the exception can be handled.
1021 the last JavaScript `Object` thrown. If it is determined, after
1024 JavaScript value to be thrown.
1028 of a JavaScript `Error` object: [`napi_throw_error`][],
1036 JavaScript `Error` object.
1074 * `[in] error`: The JavaScript value to be thrown.
1078 This API throws the JavaScript value provided.
1098 This API throws a JavaScript `Error` with the text provided.
1118 This API throws a JavaScript `TypeError` with the text provided.
1138 This API throws a JavaScript `RangeError` with the text provided.
1177 * `[in] msg`: `napi_value` that references a JavaScript `string` to be used as
1183 This API returns a JavaScript `Error` with the text provided.
1201 * `[in] msg`: `napi_value` that references a JavaScript `string` to be used as
1207 This API returns a JavaScript `TypeError` with the text provided.
1225 * `[in] msg`: `napi_value` that references a JavaScript `string` to be used as
1231 This API returns a JavaScript `RangeError` with the text provided.
1249 This API can be called even if there is a pending JavaScript exception.
1266 This API can be called even if there is a pending JavaScript exception.
1281 Trigger an `'uncaughtException'` in JavaScript. Useful if an async
1311 This API can be called even if there is a pending JavaScript exception.
1440 This API can be called even if there is a pending JavaScript exception.
1482 This API can be called even if there is a pending JavaScript exception.
1499 * `[in] escapee`: `napi_value` representing the JavaScript `Object` to be
1506 This API promotes the handle to the JavaScript object so that it is valid
1510 This API can be called even if there is a pending JavaScript exception.
1592 This API can be called even if there is a pending JavaScript exception.
1659 JavaScript `Object` associated with the `napi_ref`. Otherwise, result
1892 [Working with JavaScript properties][].
1897 ## Working with JavaScript values
1898 Node-API exposes a set of APIs to create all types of JavaScript values.
1904 1. Create a new JavaScript object
1910 Any Node-API call that requires a JavaScript value takes in a `napi_value`.
1913 the `napi_value` in question is of the JavaScript type expected by the API.
2002 A JavaScript value of type `napi_external` appears in JavaScript as a plain
2039 * `[out] result`: A `napi_value` representing a JavaScript `Array`.
2043 This API returns a Node-API value corresponding to a JavaScript `Array` type.
2044 JavaScript arrays are described in
2061 * `[out] result`: A `napi_value` representing a JavaScript `Array`.
2065 This API returns a Node-API value corresponding to a JavaScript `Array` type.
2073 JavaScript arrays are described in
2092 * `[out] result`: A `napi_value` representing a JavaScript `ArrayBuffer`.
2096 This API returns a Node-API value corresponding to a JavaScript `ArrayBuffer`.
2103 written to directly from native code. To write to this buffer from JavaScript,
2106 JavaScript `ArrayBuffer` objects are described in
2175 * `[out] result`: A `napi_value` representing a JavaScript `Date`.
2182 This API allocates a JavaScript `Date` object.
2184 JavaScript `Date` objects are described in
2211 This API allocates a JavaScript value with external data attached to it. This
2212 is used to pass external data through JavaScript code, so it can be retrieved
2215 The API adds a `napi_finalize` callback which will be called when the JavaScript
2251 * `[out] result`: A `napi_value` representing a JavaScript `ArrayBuffer`.
2255 This API returns a Node-API value corresponding to a JavaScript `ArrayBuffer`.
2260 The API adds a `napi_finalize` callback which will be called when the JavaScript
2268 JavaScript `ArrayBuffer`s are described in
2289 * `[in] data`: Raw pointer to the underlying buffer to expose to JavaScript.
2302 The API adds a `napi_finalize` callback which will be called when the JavaScript
2323 * `[out] result`: A `napi_value` representing a JavaScript `Object`.
2327 This API allocates a default JavaScript `Object`.
2328 It is the equivalent of doing `new Object()` in JavaScript.
2330 The JavaScript `Object` type is described in [Section 6.1.7][] of the
2346 * `[in] description`: Optional `napi_value` which refers to a JavaScript
2348 * `[out] result`: A `napi_value` representing a JavaScript `symbol`.
2352 This API creates a JavaScript `symbol` value from a UTF8-encoded C string.
2354 The JavaScript `symbol` type is described in [Section 19.4][]
2378 * `[out] result`: A `napi_value` representing a JavaScript `TypedArray`.
2382 This API creates a JavaScript `TypedArray` object over an existing
2391 JavaScript `TypedArray` objects are described in
2413 * `[out] result`: A `napi_value` representing a JavaScript `DataView`.
2417 This API creates a JavaScript `DataView` object over an existing `ArrayBuffer`.
2425 JavaScript `DataView` objects are described in
2440 * `[in] value`: Integer value to be represented in JavaScript.
2441 * `[out] result`: A `napi_value` representing a JavaScript `number`.
2445 This API is used to convert from the C `int32_t` type to the JavaScript
2448 The JavaScript `number` type is described in
2462 * `[in] value`: Unsigned integer value to be represented in JavaScript.
2463 * `[out] result`: A `napi_value` representing a JavaScript `number`.
2467 This API is used to convert from the C `uint32_t` type to the JavaScript
2470 The JavaScript `number` type is described in
2484 * `[in] value`: Integer value to be represented in JavaScript.
2485 * `[out] result`: A `napi_value` representing a JavaScript `number`.
2489 This API is used to convert from the C `int64_t` type to the JavaScript
2492 The JavaScript `number` type is described in [Section 6.1.6][]
2494 cannot be represented with full precision in JavaScript. Integer values
2509 * `[in] value`: Double-precision value to be represented in JavaScript.
2510 * `[out] result`: A `napi_value` representing a JavaScript `number`.
2514 This API is used to convert from the C `double` type to the JavaScript
2517 The JavaScript `number` type is described in
2533 * `[in] value`: Integer value to be represented in JavaScript.
2534 * `[out] result`: A `napi_value` representing a JavaScript `BigInt`.
2538 This API converts the C `int64_t` type to the JavaScript `BigInt` type.
2553 * `[in] value`: Unsigned integer value to be represented in JavaScript.
2554 * `[out] result`: A `napi_value` representing a JavaScript `BigInt`.
2558 This API converts the C `uint64_t` type to the JavaScript `BigInt` type.
2579 * `[out] result`: A `napi_value` representing a JavaScript `BigInt`.
2606 * `[out] result`: A `napi_value` representing a JavaScript `string`.
2610 This API creates a JavaScript `string` value from an ISO-8859-1-encoded C
2613 The JavaScript `string` type is described in
2633 * `[out] result`: A `napi_value` representing a JavaScript `string`.
2637 This API creates a JavaScript `string` value from a UTF16-LE-encoded C string.
2640 The JavaScript `string` type is described in
2660 * `[out] result`: A `napi_value` representing a JavaScript `string`.
2664 This API creates a JavaScript `string` value from a UTF8-encoded C string.
2667 The JavaScript `string` type is described in
2684 * `[in] value`: `napi_value` representing the JavaScript `Array` whose length is
2767 * `[in] object`: `napi_value` representing JavaScript `Object` whose prototype
2857 * `[in] value`: `napi_value` representing a JavaScript `Date`.
2867 This API returns the C double primitive of time value for the given JavaScript
2881 * `[in] value`: `napi_value` representing JavaScript `Boolean`.
2882 * `[out] result`: C boolean primitive equivalent of the given JavaScript
2888 This API returns the C boolean primitive equivalent of the given JavaScript
2904 * `[in] value`: `napi_value` representing JavaScript `number`.
2905 * `[out] result`: C double primitive equivalent of the given JavaScript
2911 This API returns the C double primitive equivalent of the given JavaScript
2928 * `[in] value`: `napi_value` representing JavaScript `BigInt`.
2929 * `[out] result`: C `int64_t` primitive equivalent of the given JavaScript
2937 This API returns the C `int64_t` primitive equivalent of the given JavaScript
2954 * `[in] value`: `napi_value` representing JavaScript `BigInt`.
2955 * `[out] result`: C `uint64_t` primitive equivalent of the given JavaScript
2963 This API returns the C `uint64_t` primitive equivalent of the given JavaScript
2981 * `[in] value`: `napi_value` representing JavaScript `BigInt`.
2982 * `[out] sign_bit`: Integer representing if the JavaScript `BigInt` is positive
3008 * `[in] value`: `napi_value` representing JavaScript external value.
3009 * `[out] result`: Pointer to the data wrapped by the JavaScript external value.
3030 * `[in] value`: `napi_value` representing JavaScript `number`.
3031 * `[out] result`: C `int32` primitive equivalent of the given JavaScript
3038 of the given JavaScript `number`.
3060 * `[in] value`: `napi_value` representing JavaScript `number`.
3061 * `[out] result`: C `int64` primitive equivalent of the given JavaScript
3067 This API returns the C `int64` primitive equivalent of the given JavaScript
3092 * `[in] value`: `napi_value` representing JavaScript string.
3122 * `[in] value`: `napi_value` representing JavaScript string.
3151 * `[in] value`: `napi_value` representing JavaScript string.
3178 * `[in] value`: `napi_value` representing JavaScript `number`.
3201 * `[out] result`: `napi_value` representing JavaScript `Boolean` singleton to
3206 This API is used to return the JavaScript singleton object that is used to
3220 * `[out] result`: `napi_value` representing JavaScript `global` object.
3237 * `[out] result`: `napi_value` representing JavaScript `null` object.
3254 * `[out] result`: `napi_value` representing JavaScript Undefined value.
3260 ## Working with JavaScript values and abstract operations
3262 Node-API exposes a set of APIs to perform some abstract operations on JavaScript
3268 1. Coerce JavaScript values to specific JavaScript types (such as `number` or
3270 2. Check the type of a JavaScript value.
3271 3. Check for equality between two JavaScript values.
3286 * `[in] value`: The JavaScript value to coerce.
3287 * `[out] result`: `napi_value` representing the coerced JavaScript `Boolean`.
3308 * `[in] value`: The JavaScript value to coerce.
3309 * `[out] result`: `napi_value` representing the coerced JavaScript `number`.
3330 * `[in] value`: The JavaScript value to coerce.
3331 * `[out] result`: `napi_value` representing the coerced JavaScript `Object`.
3352 * `[in] value`: The JavaScript value to coerce.
3353 * `[out] result`: `napi_value` representing the coerced JavaScript `string`.
3372 * `[in] value`: The JavaScript value whose type to query.
3373 * `[out] result`: The type of the JavaScript value.
3404 * `[in] object`: The JavaScript value to check.
3405 * `[in] constructor`: The JavaScript function object of the constructor function
3426 * `[in] value`: The JavaScript value to check.
3445 * `[in] value`: The JavaScript value to check.
3463 * `[in] value`: The JavaScript value to check.
3484 * `[in] value`: The JavaScript value to check.
3485 * `[out] result`: Whether the given `napi_value` represents a JavaScript `Date`
3503 * `[in] value`: The JavaScript value to check.
3521 * `[in] value`: The JavaScript value to check.
3539 * `[in] value`: The JavaScript value to check.
3560 * `[in] lhs`: The JavaScript value to check.
3561 * `[in] rhs`: The JavaScript value to check against.
3584 * `[in] arraybuffer`: The JavaScript `ArrayBuffer` to be detached.
3613 * `[in] arraybuffer`: The JavaScript `ArrayBuffer` to be checked.
3624 ## Working with JavaScript properties
3626 Node-API exposes a set of APIs to get and set properties on JavaScript
3630 Properties in JavaScript are represented as a tuple of a key and a value.
3636 * JavaScript value: these are represented in Node-API by `napi_value`. This can
3640 Any Node-API call that requires a JavaScript value takes in a `napi_value`.
3642 `napi_value` in question is of the JavaScript type expected by the API.
3645 get and set properties on arbitrary JavaScript objects represented by
3648 For instance, consider the following JavaScript code snippet:
3675 JavaScript snippet:
3702 Consider the following JavaScript snippet:
3725 reasons. Consider the following JavaScript:
3795 set on a JavaScript object. Other than `napi_static` they correspond to the
3811 * `napi_default_jsproperty`: Like a property set via assignment in JavaScript,
3835 * `name`: Optional `napi_value` that points to a JavaScript string or symbol
3844   the property is accessed from JavaScript code (or if a get on the property is
3849   the property is set from JavaScript code (or if a set on the property is
3852   property to be a JavaScript function represented by `method`. If this is
3875 * `[out] result`: A `napi_value` representing an array of JavaScript values
3909 * `[out] result`: A `napi_value` representing an array of JavaScript values
4266 ## Working with JavaScript functions
4268 Node-API provides a set of APIs that allow JavaScript code to
4271 the `napi_callback` type. When the JavaScript VM calls back to
4281 JavaScript functions from native code. One can either call a function
4282 like a regular JavaScript function call, or as a constructor
4307 * `[in] func`: `napi_value` representing the JavaScript function to be invoked.
4309 * `[in] argv`: Array of `napi_values` representing JavaScript values passed in
4311 * `[out] result`: `napi_value` representing the JavaScript object returned.
4315 This method allows a JavaScript function object to be called from a native
4317 native code *into* JavaScript. For the special case of calling into JavaScript
4320 A sample use case might look as follows. Consider the following JavaScript
4376   within JavaScript as the new function object's `name` property.
4383 * `[out] result`: `napi_value` representing the JavaScript function object for
4390 *from* JavaScript.
4394 to JavaScript, in order for the function to be accessible from script.
4422 Given the above code, the add-on can be used from JavaScript as follows:
4433 be associated with the resulting JavaScript function (which is returned in the
4435 passing both the JavaScript function and the data to [`napi_add_finalizer`][].
4437 JavaScript `Function`s are described in [Section 19.2][] of the ECMAScript
4464 * `[out] this`: Receives the JavaScript `this` argument for the call.
4508 * `[in] cons`: `napi_value` representing the JavaScript function to be invoked
4511 * `[in] argv`: Array of JavaScript values as `napi_value` representing the
4513 * `[out] result`: `napi_value` representing the JavaScript object returned,
4516 This method is used to instantiate a new JavaScript value using a given
4556 constructor and methods can be called from JavaScript.
4558 1. The [`napi_define_class`][] API defines a JavaScript class with constructor,
4561 2. When JavaScript code invokes the constructor, the constructor callback
4562     uses [`napi_wrap`][] to wrap a new C++ instance in a JavaScript object,
4564 3. When JavaScript code invokes a method or property accessor on the class,
4591 a JavaScript object is a wrapper for a certain native type. This is the case
4592 especially when wrapped JavaScript objects are passed back into the addon via
4599 // `openDatabase()` returns a JavaScript object that wraps a native database
4603 // `query()` returns a JavaScript object that wraps a native query handle.
4629 `queryHasRecords()` has to perform a type validation. Retaining the JavaScript
4646 along with a JavaScript object stored in a `napi_value` to
4647 `napi_type_tag_object()`, the JavaScript object will be "marked" with the
4648 type tag. The "mark" is invisible on the JavaScript side. When a JavaScript
4650 along with the original type tag to determine whether the JavaScript object was
4697 // Later when we receive a JavaScript object purporting to be a database handle
4745 * `[in] utf8name`: Name of the JavaScript constructor function; When wrapping a
4765 Defines a JavaScript class, including:
4767 * A JavaScript constructor function that has the class name. When wrapping a
4770   JavaScript object instance being constructed using [`napi_wrap`][].
4778   instance placed inside the JavaScript object instance by using
4783 then wraps the new C++ instance in a JavaScript object, and returns the wrapper
4786 The JavaScript constructor function returned from [`napi_define_class`][] is
4795 with the resulting JavaScript constructor (which is returned in the `result`
4797 the JavaScript function and the data to [`napi_add_finalizer`][].
4815 * `[in] js_object`: The JavaScript object that will be the wrapper for the
4818   JavaScript object.
4820   native instance when the JavaScript object is ready for garbage-collection.
4828 Wraps a native instance in a JavaScript object. The native instance can be
4831 When JavaScript code invokes a constructor for a class that was defined using
4835 JavaScript object that is the `this` argument to the constructor callback.
4875 Retrieves a native instance that was previously wrapped in a JavaScript
4878 When JavaScript code invokes a method or property accessor on the class, the
4902 Retrieves a native instance that was previously wrapped in the JavaScript
4905 JavaScript object becomes garbage-collected.
4922 * `[in] js_object`: The JavaScript object to be marked.
4927 Associates the value of the `type_tag` pointer with the JavaScript object.
4951 * `[in] js_object`: The JavaScript object whose type tag to examine.
4980 * `[in] js_object`: The JavaScript object to which the native data will be
4982 * `[in] native_object`: The native data that will be attached to the JavaScript
4985   native data when the JavaScript object is ready for garbage-collection.
4989 * `[out] result`: Optional reference to the JavaScript object.
4993 Adds a `napi_finalize` callback which will be called when the JavaScript object
5000   attach each of them to the JavaScript object, and
5028 that could result in the execution of JavaScript or interaction with
5029 JavaScript objects. Most often, any code that needs to make Node-API
5032 it will likely execute JavaScript.
5132 This API can be called even if there is a pending JavaScript exception.
5177 This API can be called even if there is a pending JavaScript exception.
5214 garbage collected by JavaScript engine before the `napi_async_context` was
5242 This API can be called even if there is a pending JavaScript exception.
5273 * `[in] func`: `napi_value` representing the JavaScript function to be invoked.
5275 * `[in] argv`: Array of JavaScript values as `napi_value` representing the
5277 * `[out] result`: `napi_value` representing the JavaScript object returned.
5281 This method allows a JavaScript function object to be called from a native
5283 *from* native code back *into* JavaScript *after* returning from an async
5295 JavaScript during the callback are ran before returning back to C/C++.
5340 This API can be called even if there is a pending JavaScript exception.
5419   alive by JavaScript objects.
5425 memory that is kept alive by JavaScript objects (i.e. a JavaScript object
5440 be returned to JavaScript where it can be used in the usual fashion.
5502 * `[out] promise`: The JavaScript promise associated with the deferred object.
5506 This API creates a deferred object and a JavaScript promise.
5524 This API resolves a JavaScript promise by way of the deferred object
5525 with which it is associated. Thus, it can only be used to resolve JavaScript
5549 This API rejects a JavaScript promise by way of the deferred object
5550 with which it is associated. Thus, it can only be used to reject JavaScript
5577 Node-API provides an API for executing a string containing JavaScript using the
5578 underlying JavaScript engine.
5593 * `[in] script`: A JavaScript string containing the script to execute.
5596 This function executes a string of JavaScript code and returns its result with
5632 JavaScript functions can normally only be called from a native addon's main
5637 When an addon has additional threads and JavaScript functions need to be invoked
5640 JavaScript function on their behalf. The thread-safe function APIs provide an
5646 `napi_value` that holds a JavaScript function which can be called from multiple
5648 JavaScript callback is to be called will be placed in a queue, and, for each
5649 value in the queue, a call will eventually be made to the JavaScript function.
5666 JavaScript. `napi_call_threadsafe_function()` accepts a parameter which controls
5675 from a JavaScript thread, because, if the queue is full, it may cause the
5676 JavaScript thread to deadlock.
5678 The actual call into JavaScript is controlled by the callback given via the
5682 callback will be used, and the resulting JavaScript call will have no arguments.
5683 The `call_js_cb` callback receives the JavaScript function to call as a
5687 as `napi_call_function()` to call into JavaScript.
5690 to indicate that calls into JavaScript are no longer possible, while items
5694 It is not necessary to call into JavaScript via `napi_make_callback()` because
5783 * `[in] func`: An optional JavaScript function to call from another thread. It
5787 * `[in] async_resource_name`: A JavaScript string to provide an identifier for
5799 * `[in] call_js_cb`: Optional callback which calls the JavaScript function in
5801   main thread. If not given, the JavaScript function will be called with no
5804 * `[out] result`: The asynchronous thread-safe JavaScript function.
5847 * `[in] func`: The asynchronous thread-safe JavaScript function to invoke.
5848 * `[in] data`: Data to send into JavaScript via the callback `call_js_cb`
5849   provided during the creation of the thread-safe JavaScript function.
5855 This API should not be called with `napi_tsfn_blocking` from a JavaScript
5856 thread, because, if the queue is full, it may cause the JavaScript thread to
5877 * `[in] func`: The asynchronous thread-safe JavaScript function to start making
5900 * `[in] func`: The asynchronous thread-safe JavaScript function whose reference
6031 [Working with JavaScript properties]: #n_api_working_with_javascript_properties