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.
624 This is an opaque pointer that is used to represent a JavaScript value.
632 This is an opaque pointer that represents a JavaScript function which can be
677 JavaScript, a default handle scope will exist. If the user does not explicitly
682 of JavaScript values.
705 users to manage the lifetimes of JavaScript values, including defining their
719 with which JavaScript objects can be "tagged" in order to ensure that they are
725 previously applied to the JavaScript object.
760 exposed to JavaScript via Node-API. Callback functions should satisfy the
804 JavaScript or interact with JavaScript objects. Node-API calls should be in the
806 it will likely result in execution of JavaScript.
834 necessary for a call into JavaScript, usually via `napi_call_function`, and then
835 make the call into JavaScript.
838 parameter and the JavaScript function to call is given in the `js_callback`
842 sufficient to call the JavaScript function via `napi_call_function` rather than
856 * `[in] js_callback`: The JavaScript function to call, or `NULL` if the
863   the callback to convert this native data to JavaScript values (with Node-API
897 Node-API uses both return values and JavaScript exceptions for error handling.
906 no uncaught JavaScript exception was thrown. If an error occurred AND
982 This API can be called even if there is a pending JavaScript exception.
986 Any Node-API function call may result in a pending JavaScript exception. This is
988 execution of JavaScript.
1001 called to allow for some minimal cleanup before returning to JavaScript.
1009 execution will return to JavaScript. As part of the transition back to
1010 JavaScript, the exception will be thrown at the point in the JavaScript
1014 JavaScript where the exception can be handled.
1022 the last JavaScript `Object` thrown. If it is determined, after
1025 JavaScript value to be thrown.
1029 of a JavaScript `Error` object: [`napi_throw_error`][],
1037 JavaScript `Error` object.
1075 * `[in] error`: The JavaScript value to be thrown.
1079 This API throws the JavaScript value provided.
1099 This API throws a JavaScript `Error` with the text provided.
1119 This API throws a JavaScript `TypeError` with the text provided.
1139 This API throws a JavaScript `RangeError` with the text provided.
1178 * `[in] msg`: `napi_value` that references a JavaScript `string` to be used as
1184 This API returns a JavaScript `Error` with the text provided.
1202 * `[in] msg`: `napi_value` that references a JavaScript `string` to be used as
1208 This API returns a JavaScript `TypeError` with the text provided.
1226 * `[in] msg`: `napi_value` that references a JavaScript `string` to be used as
1232 This API returns a JavaScript `RangeError` with the text provided.
1250 This API can be called even if there is a pending JavaScript exception.
1267 This API can be called even if there is a pending JavaScript exception.
1282 Trigger an `'uncaughtException'` in JavaScript. Useful if an async
1312 This API can be called even if there is a pending JavaScript exception.
1441 This API can be called even if there is a pending JavaScript exception.
1483 This API can be called even if there is a pending JavaScript exception.
1500 * `[in] escapee`: `napi_value` representing the JavaScript `Object` to be
1507 This API promotes the handle to the JavaScript object so that it is valid
1511 This API can be called even if there is a pending JavaScript exception.
1593 This API can be called even if there is a pending JavaScript exception.
1660 JavaScript `Object` associated with the `napi_ref`. Otherwise, result
1893 [Working with JavaScript properties][].
1898 ## Working with JavaScript values
1899 Node-API exposes a set of APIs to create all types of JavaScript values.
1905 1. Create a new JavaScript object
1911 Any Node-API call that requires a JavaScript value takes in a `napi_value`.
1914 the `napi_value` in question is of the JavaScript type expected by the API.
2003 A JavaScript value of type `napi_external` appears in JavaScript as a plain
2040 * `[out] result`: A `napi_value` representing a JavaScript `Array`.
2044 This API returns a Node-API value corresponding to a JavaScript `Array` type.
2045 JavaScript arrays are described in
2062 * `[out] result`: A `napi_value` representing a JavaScript `Array`.
2066 This API returns a Node-API value corresponding to a JavaScript `Array` type.
2074 JavaScript arrays are described in
2093 * `[out] result`: A `napi_value` representing a JavaScript `ArrayBuffer`.
2097 This API returns a Node-API value corresponding to a JavaScript `ArrayBuffer`.
2104 written to directly from native code. To write to this buffer from JavaScript,
2107 JavaScript `ArrayBuffer` objects are described in
2176 * `[out] result`: A `napi_value` representing a JavaScript `Date`.
2183 This API allocates a JavaScript `Date` object.
2185 JavaScript `Date` objects are described in
2212 This API allocates a JavaScript value with external data attached to it. This
2213 is used to pass external data through JavaScript code, so it can be retrieved
2216 The API adds a `napi_finalize` callback which will be called when the JavaScript
2252 * `[out] result`: A `napi_value` representing a JavaScript `ArrayBuffer`.
2269 This API returns a Node-API value corresponding to a JavaScript `ArrayBuffer`.
2274 The API adds a `napi_finalize` callback which will be called when the JavaScript
2282 JavaScript `ArrayBuffer`s are described in
2303 * `[in] data`: Raw pointer to the underlying buffer to expose to JavaScript.
2329 The API adds a `napi_finalize` callback which will be called when the JavaScript
2350 * `[out] result`: A `napi_value` representing a JavaScript `Object`.
2354 This API allocates a default JavaScript `Object`.
2355 It is the equivalent of doing `new Object()` in JavaScript.
2357 The JavaScript `Object` type is described in [Section 6.1.7][] of the
2373 * `[in] description`: Optional `napi_value` which refers to a JavaScript
2375 * `[out] result`: A `napi_value` representing a JavaScript `symbol`.
2379 This API creates a JavaScript `symbol` value from a UTF8-encoded C string.
2381 The JavaScript `symbol` type is described in [Section 19.4][]
2405 * `[out] result`: A `napi_value` representing a JavaScript `TypedArray`.
2409 This API creates a JavaScript `TypedArray` object over an existing
2418 JavaScript `TypedArray` objects are described in
2440 * `[out] result`: A `napi_value` representing a JavaScript `DataView`.
2444 This API creates a JavaScript `DataView` object over an existing `ArrayBuffer`.
2452 JavaScript `DataView` objects are described in
2467 * `[in] value`: Integer value to be represented in JavaScript.
2468 * `[out] result`: A `napi_value` representing a JavaScript `number`.
2472 This API is used to convert from the C `int32_t` type to the JavaScript
2475 The JavaScript `number` type is described in
2489 * `[in] value`: Unsigned integer value to be represented in JavaScript.
2490 * `[out] result`: A `napi_value` representing a JavaScript `number`.
2494 This API is used to convert from the C `uint32_t` type to the JavaScript
2497 The JavaScript `number` type is described in
2511 * `[in] value`: Integer value to be represented in JavaScript.
2512 * `[out] result`: A `napi_value` representing a JavaScript `number`.
2516 This API is used to convert from the C `int64_t` type to the JavaScript
2519 The JavaScript `number` type is described in [Section 6.1.6][]
2521 cannot be represented with full precision in JavaScript. Integer values
2536 * `[in] value`: Double-precision value to be represented in JavaScript.
2537 * `[out] result`: A `napi_value` representing a JavaScript `number`.
2541 This API is used to convert from the C `double` type to the JavaScript
2544 The JavaScript `number` type is described in
2560 * `[in] value`: Integer value to be represented in JavaScript.
2561 * `[out] result`: A `napi_value` representing a JavaScript `BigInt`.
2565 This API converts the C `int64_t` type to the JavaScript `BigInt` type.
2580 * `[in] value`: Unsigned integer value to be represented in JavaScript.
2581 * `[out] result`: A `napi_value` representing a JavaScript `BigInt`.
2585 This API converts the C `uint64_t` type to the JavaScript `BigInt` type.
2606 * `[out] result`: A `napi_value` representing a JavaScript `BigInt`.
2633 * `[out] result`: A `napi_value` representing a JavaScript `string`.
2637 This API creates a JavaScript `string` value from an ISO-8859-1-encoded C
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 UTF16-LE-encoded C string.
2667 The JavaScript `string` type is described in
2687 * `[out] result`: A `napi_value` representing a JavaScript `string`.
2691 This API creates a JavaScript `string` value from a UTF8-encoded C string.
2694 The JavaScript `string` type is described in
2711 * `[in] value`: `napi_value` representing the JavaScript `Array` whose length is
2794 * `[in] object`: `napi_value` representing JavaScript `Object` whose prototype
2884 * `[in] value`: `napi_value` representing a JavaScript `Date`.
2894 This API returns the C double primitive of time value for the given JavaScript
2908 * `[in] value`: `napi_value` representing JavaScript `Boolean`.
2909 * `[out] result`: C boolean primitive equivalent of the given JavaScript
2915 This API returns the C boolean primitive equivalent of the given JavaScript
2931 * `[in] value`: `napi_value` representing JavaScript `number`.
2932 * `[out] result`: C double primitive equivalent of the given JavaScript
2938 This API returns the C double primitive equivalent of the given JavaScript
2955 * `[in] value`: `napi_value` representing JavaScript `BigInt`.
2956 * `[out] result`: C `int64_t` primitive equivalent of the given JavaScript
2964 This API returns the C `int64_t` primitive equivalent of the given JavaScript
2981 * `[in] value`: `napi_value` representing JavaScript `BigInt`.
2982 * `[out] result`: C `uint64_t` primitive equivalent of the given JavaScript
2990 This API returns the C `uint64_t` primitive equivalent of the given JavaScript
3008 * `[in] value`: `napi_value` representing JavaScript `BigInt`.
3009 * `[out] sign_bit`: Integer representing if the JavaScript `BigInt` is positive
3035 * `[in] value`: `napi_value` representing JavaScript external value.
3036 * `[out] result`: Pointer to the data wrapped by the JavaScript external value.
3057 * `[in] value`: `napi_value` representing JavaScript `number`.
3058 * `[out] result`: C `int32` primitive equivalent of the given JavaScript
3065 of the given JavaScript `number`.
3087 * `[in] value`: `napi_value` representing JavaScript `number`.
3088 * `[out] result`: C `int64` primitive equivalent of the given JavaScript
3094 This API returns the C `int64` primitive equivalent of the given JavaScript
3119 * `[in] value`: `napi_value` representing JavaScript string.
3149 * `[in] value`: `napi_value` representing JavaScript string.
3178 * `[in] value`: `napi_value` representing JavaScript string.
3205 * `[in] value`: `napi_value` representing JavaScript `number`.
3228 * `[out] result`: `napi_value` representing JavaScript `Boolean` singleton to
3233 This API is used to return the JavaScript singleton object that is used to
3247 * `[out] result`: `napi_value` representing JavaScript `global` object.
3264 * `[out] result`: `napi_value` representing JavaScript `null` object.
3281 * `[out] result`: `napi_value` representing JavaScript Undefined value.
3287 ## Working with JavaScript values and abstract operations
3289 Node-API exposes a set of APIs to perform some abstract operations on JavaScript
3295 1. Coerce JavaScript values to specific JavaScript types (such as `number` or
3297 2. Check the type of a JavaScript value.
3298 3. Check for equality between two JavaScript values.
3313 * `[in] value`: The JavaScript value to coerce.
3314 * `[out] result`: `napi_value` representing the coerced JavaScript `Boolean`.
3335 * `[in] value`: The JavaScript value to coerce.
3336 * `[out] result`: `napi_value` representing the coerced JavaScript `number`.
3357 * `[in] value`: The JavaScript value to coerce.
3358 * `[out] result`: `napi_value` representing the coerced JavaScript `Object`.
3379 * `[in] value`: The JavaScript value to coerce.
3380 * `[out] result`: `napi_value` representing the coerced JavaScript `string`.
3399 * `[in] value`: The JavaScript value whose type to query.
3400 * `[out] result`: The type of the JavaScript value.
3431 * `[in] object`: The JavaScript value to check.
3432 * `[in] constructor`: The JavaScript function object of the constructor function
3453 * `[in] value`: The JavaScript value to check.
3472 * `[in] value`: The JavaScript value to check.
3490 * `[in] value`: The JavaScript value to check.
3511 * `[in] value`: The JavaScript value to check.
3512 * `[out] result`: Whether the given `napi_value` represents a JavaScript `Date`
3530 * `[in] value`: The JavaScript value to check.
3548 * `[in] value`: The JavaScript value to check.
3566 * `[in] value`: The JavaScript value to check.
3587 * `[in] lhs`: The JavaScript value to check.
3588 * `[in] rhs`: The JavaScript value to check against.
3611 * `[in] arraybuffer`: The JavaScript `ArrayBuffer` to be detached.
3640 * `[in] arraybuffer`: The JavaScript `ArrayBuffer` to be checked.
3651 ## Working with JavaScript properties
3653 Node-API exposes a set of APIs to get and set properties on JavaScript
3657 Properties in JavaScript are represented as a tuple of a key and a value.
3663 * JavaScript value: these are represented in Node-API by `napi_value`. This can
3667 Any Node-API call that requires a JavaScript value takes in a `napi_value`.
3669 `napi_value` in question is of the JavaScript type expected by the API.
3672 get and set properties on arbitrary JavaScript objects represented by
3675 For instance, consider the following JavaScript code snippet:
3702 JavaScript snippet:
3729 Consider the following JavaScript snippet:
3752 reasons. Consider the following JavaScript:
3822 set on a JavaScript object. Other than `napi_static` they correspond to the
3838 * `napi_default_jsproperty`: Like a property set via assignment in JavaScript,
3862 * `name`: Optional `napi_value` that points to a JavaScript string or symbol
3871   the property is accessed from JavaScript code (or if a get on the property is
3876   the property is set from JavaScript code (or if a set on the property is
3879   property to be a JavaScript function represented by `method`. If this is
3902 * `[out] result`: A `napi_value` representing an array of JavaScript values
3936 * `[out] result`: A `napi_value` representing an array of JavaScript values
4293 ## Working with JavaScript functions
4295 Node-API provides a set of APIs that allow JavaScript code to
4298 the `napi_callback` type. When the JavaScript VM calls back to
4308 JavaScript functions from native code. One can either call a function
4309 like a regular JavaScript function call, or as a constructor
4334 * `[in] func`: `napi_value` representing the JavaScript function to be invoked.
4336 * `[in] argv`: Array of `napi_values` representing JavaScript values passed in
4338 * `[out] result`: `napi_value` representing the JavaScript object returned.
4342 This method allows a JavaScript function object to be called from a native
4344 native code *into* JavaScript. For the special case of calling into JavaScript
4347 A sample use case might look as follows. Consider the following JavaScript
4403   within JavaScript as the new function object's `name` property.
4410 * `[out] result`: `napi_value` representing the JavaScript function object for
4417 *from* JavaScript.
4421 to JavaScript, in order for the function to be accessible from script.
4449 Given the above code, the add-on can be used from JavaScript as follows:
4460 be associated with the resulting JavaScript function (which is returned in the
4462 passing both the JavaScript function and the data to [`napi_add_finalizer`][].
4464 JavaScript `Function`s are described in [Section 19.2][] of the ECMAScript
4491 * `[out] this`: Receives the JavaScript `this` argument for the call.
4535 * `[in] cons`: `napi_value` representing the JavaScript function to be invoked
4538 * `[in] argv`: Array of JavaScript values as `napi_value` representing the
4540 * `[out] result`: `napi_value` representing the JavaScript object returned,
4543 This method is used to instantiate a new JavaScript value using a given
4583 constructor and methods can be called from JavaScript.
4585 1. The [`napi_define_class`][] API defines a JavaScript class with constructor,
4588 2. When JavaScript code invokes the constructor, the constructor callback
4589     uses [`napi_wrap`][] to wrap a new C++ instance in a JavaScript object,
4591 3. When JavaScript code invokes a method or property accessor on the class,
4618 a JavaScript object is a wrapper for a certain native type. This is the case
4619 especially when wrapped JavaScript objects are passed back into the addon via
4626 // `openDatabase()` returns a JavaScript object that wraps a native database
4630 // `query()` returns a JavaScript object that wraps a native query handle.
4656 `queryHasRecords()` has to perform a type validation. Retaining the JavaScript
4673 along with a JavaScript object stored in a `napi_value` to
4674 `napi_type_tag_object()`, the JavaScript object will be "marked" with the
4675 type tag. The "mark" is invisible on the JavaScript side. When a JavaScript
4677 along with the original type tag to determine whether the JavaScript object was
4724 // Later when we receive a JavaScript object purporting to be a database handle
4772 * `[in] utf8name`: Name of the JavaScript constructor function; When wrapping a
4792 Defines a JavaScript class, including:
4794 * A JavaScript constructor function that has the class name. When wrapping a
4797   JavaScript object instance being constructed using [`napi_wrap`][].
4805   instance placed inside the JavaScript object instance by using
4810 then wraps the new C++ instance in a JavaScript object, and returns the wrapper
4813 The JavaScript constructor function returned from [`napi_define_class`][] is
4822 with the resulting JavaScript constructor (which is returned in the `result`
4824 the JavaScript function and the data to [`napi_add_finalizer`][].
4842 * `[in] js_object`: The JavaScript object that will be the wrapper for the
4845   JavaScript object.
4847   native instance when the JavaScript object is ready for garbage-collection.
4855 Wraps a native instance in a JavaScript object. The native instance can be
4858 When JavaScript code invokes a constructor for a class that was defined using
4862 JavaScript object that is the `this` argument to the constructor callback.
4902 Retrieves a native instance that was previously wrapped in a JavaScript
4905 When JavaScript code invokes a method or property accessor on the class, the
4929 Retrieves a native instance that was previously wrapped in the JavaScript
4932 JavaScript object becomes garbage-collected.
4949 * `[in] js_object`: The JavaScript object to be marked.
4954 Associates the value of the `type_tag` pointer with the JavaScript object.
4978 * `[in] js_object`: The JavaScript object whose type tag to examine.
5007 * `[in] js_object`: The JavaScript object to which the native data will be
5009 * `[in] native_object`: The native data that will be attached to the JavaScript
5012   native data when the JavaScript object is ready for garbage-collection.
5016 * `[out] result`: Optional reference to the JavaScript object.
5020 Adds a `napi_finalize` callback which will be called when the JavaScript object
5027   attach each of them to the JavaScript object, and
5055 that could result in the execution of JavaScript or interaction with
5056 JavaScript objects. Most often, any code that needs to make Node-API
5059 it will likely execute JavaScript.
5159 This API can be called even if there is a pending JavaScript exception.
5204 This API can be called even if there is a pending JavaScript exception.
5241 garbage collected by JavaScript engine before the `napi_async_context` was
5269 This API can be called even if there is a pending JavaScript exception.
5300 * `[in] func`: `napi_value` representing the JavaScript function to be invoked.
5302 * `[in] argv`: Array of JavaScript values as `napi_value` representing the
5304 * `[out] result`: `napi_value` representing the JavaScript object returned.
5308 This method allows a JavaScript function object to be called from a native
5310 *from* native code back *into* JavaScript *after* returning from an async
5322 JavaScript during the callback are ran before returning back to C/C++.
5367 This API can be called even if there is a pending JavaScript exception.
5446   alive by JavaScript objects.
5452 memory that is kept alive by JavaScript objects (i.e. a JavaScript object
5467 be returned to JavaScript where it can be used in the usual fashion.
5529 * `[out] promise`: The JavaScript promise associated with the deferred object.
5533 This API creates a deferred object and a JavaScript promise.
5551 This API resolves a JavaScript promise by way of the deferred object
5552 with which it is associated. Thus, it can only be used to resolve JavaScript
5576 This API rejects a JavaScript promise by way of the deferred object
5577 with which it is associated. Thus, it can only be used to reject JavaScript
5604 Node-API provides an API for executing a string containing JavaScript using the
5605 underlying JavaScript engine.
5620 * `[in] script`: A JavaScript string containing the script to execute.
5623 This function executes a string of JavaScript code and returns its result with
5659 JavaScript functions can normally only be called from a native addon's main
5664 When an addon has additional threads and JavaScript functions need to be invoked
5667 JavaScript function on their behalf. The thread-safe function APIs provide an
5673 `napi_value` that holds a JavaScript function which can be called from multiple
5675 JavaScript callback is to be called will be placed in a queue, and, for each
5676 value in the queue, a call will eventually be made to the JavaScript function.
5693 JavaScript. `napi_call_threadsafe_function()` accepts a parameter which controls
5702 from a JavaScript thread, because, if the queue is full, it may cause the
5703 JavaScript thread to deadlock.
5705 The actual call into JavaScript is controlled by the callback given via the
5709 callback will be used, and the resulting JavaScript call will have no arguments.
5710 The `call_js_cb` callback receives the JavaScript function to call as a
5714 as `napi_call_function()` to call into JavaScript.
5717 to indicate that calls into JavaScript are no longer possible, while items
5721 It is not necessary to call into JavaScript via `napi_make_callback()` because
5810 * `[in] func`: An optional JavaScript function to call from another thread. It
5814 * `[in] async_resource_name`: A JavaScript string to provide an identifier for
5826 * `[in] call_js_cb`: Optional callback which calls the JavaScript function in
5828   main thread. If not given, the JavaScript function will be called with no
5831 * `[out] result`: The asynchronous thread-safe JavaScript function.
5874 * `[in] func`: The asynchronous thread-safe JavaScript function to invoke.
5875 * `[in] data`: Data to send into JavaScript via the callback `call_js_cb`
5876   provided during the creation of the thread-safe JavaScript function.
5882 This API should not be called with `napi_tsfn_blocking` from a JavaScript
5883 thread, because, if the queue is full, it may cause the JavaScript thread to
5904 * `[in] func`: The asynchronous thread-safe JavaScript function to start making
5927 * `[in] func`: The asynchronous thread-safe JavaScript function whose reference
6058 [Working with JavaScript properties]: #n_api_working_with_javascript_properties