include/node/js_native_api_types.h

0001 #ifndef SRC_JS_NATIVE_API_TYPES_H_
0002 #define SRC_JS_NATIVE_API_TYPES_H_
0003
0004 // Use INT_MAX, this should only be consumed by the pre-processor anyway.
0005 #define NAPI_VERSION_EXPERIMENTAL 2147483647
0006 #ifndef NAPI_VERSION
0007 #ifdef NAPI_EXPERIMENTAL
0008 #define NAPI_VERSION NAPI_VERSION_EXPERIMENTAL
0009 #else
0010 // The baseline version for Node-API.
0011 // NAPI_VERSION controls which version is used by default when compiling
0012 // a native addon. If the addon developer wants to use functions from a
0013 // newer Node-API version not yet available in all LTS versions, they can
0014 // set NAPI_VERSION to explicitly depend on that version.
0015 #define NAPI_VERSION 8
0016 #endif
0017 #endif
0018
0019 #if defined(NAPI_EXPERIMENTAL) &&                                              \
0020     !defined(NODE_API_EXPERIMENTAL_NO_WARNING) &&                              \
0021     !defined(NODE_WANT_INTERNALS)
0022 #ifdef _MSC_VER
0023 #pragma message("NAPI_EXPERIMENTAL is enabled. "                               \
0024                 "Experimental features may be unstable.")
0025 #else
0026 #warning "NAPI_EXPERIMENTAL is enabled. " \
0027        "Experimental features may be unstable."
0028 #endif
0029 #endif
0030
0031 // This file needs to be compatible with C compilers.
0032 // This is a public include file, and these includes have essentially
0033 // become part of its API.
0034 #include <stddef.h>  // NOLINT(modernize-deprecated-headers)
0035 #include <stdint.h>  // NOLINT(modernize-deprecated-headers)
0036
0037 #if !defined __cplusplus || (defined(_MSC_VER) && _MSC_VER < 1900)
0038 typedef uint16_t char16_t;
0039 #endif
0040
0041 #ifndef NAPI_CDECL
0042 #ifdef _WIN32
0043 #define NAPI_CDECL __cdecl
0044 #else
0045 #define NAPI_CDECL
0046 #endif
0047 #endif
0048
0049 // JSVM API types are all opaque pointers for ABI stability
0050 // typedef undefined structs instead of void* for compile time type safety
0051 typedef struct napi_env__* napi_env;
0052
0053 // We need to mark APIs which can be called during garbage collection (GC),
0054 // meaning that they do not affect the state of the JS engine, and can
0055 // therefore be called synchronously from a finalizer that itself runs
0056 // synchronously during GC. Such APIs can receive either a `napi_env` or a
0057 // `node_api_basic_env` as their first parameter, because we should be able to
0058 // also call them during normal, non-garbage-collecting operations, whereas
0059 // APIs that affect the state of the JS engine can only receive a `napi_env` as
0060 // their first parameter, because we must not call them during GC. In lieu of
0061 // inheritance, we use the properties of the const qualifier to accomplish
0062 // this, because both a const and a non-const value can be passed to an API
0063 // expecting a const value, but only a non-const value can be passed to an API
0064 // expecting a non-const value.
0065 //
0066 // In conjunction with appropriate CFLAGS to warn us if we're passing a const
0067 // (basic) environment into an API that expects a non-const environment, and
0068 // the definition of basic finalizer function pointer types below, which
0069 // receive a basic environment as their first parameter, and can thus only call
0070 // basic APIs (unless the user explicitly casts the environment), we achieve
0071 // the ability to ensure at compile time that we do not call APIs that affect
0072 // the state of the JS engine from a synchronous (basic) finalizer.
0073 #if !defined(NAPI_EXPERIMENTAL) ||                                             \
0074     (defined(NAPI_EXPERIMENTAL) &&                                             \
0075      (defined(NODE_API_EXPERIMENTAL_NOGC_ENV_OPT_OUT) ||                       \
0076       defined(NODE_API_EXPERIMENTAL_BASIC_ENV_OPT_OUT)))
0077 typedef struct napi_env__* node_api_nogc_env;
0078 #else
0079 typedef const struct napi_env__* node_api_nogc_env;
0080 #endif
0081 typedef node_api_nogc_env node_api_basic_env;
0082
0083 typedef struct napi_value__* napi_value;
0084 typedef struct napi_ref__* napi_ref;
0085 typedef struct napi_handle_scope__* napi_handle_scope;
0086 typedef struct napi_escapable_handle_scope__* napi_escapable_handle_scope;
0087 typedef struct napi_callback_info__* napi_callback_info;
0088 typedef struct napi_deferred__* napi_deferred;
0089
0090 typedef enum {
0091   napi_default = 0,
0092   napi_writable = 1 << 0,
0093   napi_enumerable = 1 << 1,
0094   napi_configurable = 1 << 2,
0095
0096   // Used with napi_define_class to distinguish static properties
0097   // from instance properties. Ignored by napi_define_properties.
0098   napi_static = 1 << 10,
0099
0100 #if NAPI_VERSION >= 8
0101   // Default for class methods.
0102   napi_default_method = napi_writable | napi_configurable,
0103
0104   // Default for object properties, like in JS obj[prop].
0105   napi_default_jsproperty = napi_writable | napi_enumerable | napi_configurable,
0106 #endif  // NAPI_VERSION >= 8
0107 } napi_property_attributes;
0108
0109 typedef enum {
0110   // ES6 types (corresponds to typeof)
0111   napi_undefined,
0112   napi_null,
0113   napi_boolean,
0114   napi_number,
0115   napi_string,
0116   napi_symbol,
0117   napi_object,
0118   napi_function,
0119   napi_external,
0120   napi_bigint,
0121 } napi_valuetype;
0122
0123 typedef enum {
0124   napi_int8_array,
0125   napi_uint8_array,
0126   napi_uint8_clamped_array,
0127   napi_int16_array,
0128   napi_uint16_array,
0129   napi_int32_array,
0130   napi_uint32_array,
0131   napi_float32_array,
0132   napi_float64_array,
0133   napi_bigint64_array,
0134   napi_biguint64_array,
0135 #define NODE_API_HAS_FLOAT16_ARRAY
0136   napi_float16_array,
0137 } napi_typedarray_type;
0138
0139 typedef enum {
0140   napi_ok,
0141   napi_invalid_arg,
0142   napi_object_expected,
0143   napi_string_expected,
0144   napi_name_expected,
0145   napi_function_expected,
0146   napi_number_expected,
0147   napi_boolean_expected,
0148   napi_array_expected,
0149   napi_generic_failure,
0150   napi_pending_exception,
0151   napi_cancelled,
0152   napi_escape_called_twice,
0153   napi_handle_scope_mismatch,
0154   napi_callback_scope_mismatch,
0155   napi_queue_full,
0156   napi_closing,
0157   napi_bigint_expected,
0158   napi_date_expected,
0159   napi_arraybuffer_expected,
0160   napi_detachable_arraybuffer_expected,
0161   napi_would_deadlock,  // unused
0162   napi_no_external_buffers_allowed,
0163   napi_cannot_run_js,
0164 } napi_status;
0165 // Note: when adding a new enum value to `napi_status`, please also update
0166 //   * `const int last_status` in the definition of `napi_get_last_error_info()'
0167 //     in file js_native_api_v8.cc.
0168 //   * `const char* error_messages[]` in file js_native_api_v8.cc with a brief
0169 //     message explaining the error.
0170 //   * the definition of `napi_status` in doc/api/n-api.md to reflect the newly
0171 //     added value(s).
0172
0173 typedef napi_value(NAPI_CDECL* napi_callback)(napi_env env,
0174                                               napi_callback_info info);
0175 typedef void(NAPI_CDECL* napi_finalize)(napi_env env,
0176                                         void* finalize_data,
0177                                         void* finalize_hint);
0178
0179 #if !defined(NAPI_EXPERIMENTAL) ||                                             \
0180     (defined(NAPI_EXPERIMENTAL) &&                                             \
0181      (defined(NODE_API_EXPERIMENTAL_NOGC_ENV_OPT_OUT) ||                       \
0182       defined(NODE_API_EXPERIMENTAL_BASIC_ENV_OPT_OUT)))
0183 typedef napi_finalize node_api_nogc_finalize;
0184 #else
0185 typedef void(NAPI_CDECL* node_api_nogc_finalize)(node_api_nogc_env env,
0186                                                  void* finalize_data,
0187                                                  void* finalize_hint);
0188 #endif
0189 typedef node_api_nogc_finalize node_api_basic_finalize;
0190
0191 // A finalizer that can be called from any thread and at any time.
0192 typedef void(NAPI_CDECL* node_api_noenv_finalize)(void* finalize_data,
0193                                                   void* finalize_hint);
0194
0195 typedef struct {
0196   // One of utf8name or name should be NULL.
0197   const char* utf8name;
0198   napi_value name;
0199
0200   napi_callback method;
0201   napi_callback getter;
0202   napi_callback setter;
0203   napi_value value;
0204
0205   napi_property_attributes attributes;
0206   void* data;
0207 } napi_property_descriptor;
0208
0209 typedef struct {
0210   const char* error_message;
0211   void* engine_reserved;
0212   uint32_t engine_error_code;
0213   napi_status error_code;
0214 } napi_extended_error_info;
0215
0216 #if NAPI_VERSION >= 6
0217 typedef enum {
0218   napi_key_include_prototypes,
0219   napi_key_own_only
0220 } napi_key_collection_mode;
0221
0222 typedef enum {
0223   napi_key_all_properties = 0,
0224   napi_key_writable = 1,
0225   napi_key_enumerable = 1 << 1,
0226   napi_key_configurable = 1 << 2,
0227   napi_key_skip_strings = 1 << 3,
0228   napi_key_skip_symbols = 1 << 4
0229 } napi_key_filter;
0230
0231 typedef enum {
0232   napi_key_keep_numbers,
0233   napi_key_numbers_to_strings
0234 } napi_key_conversion;
0235 #endif  // NAPI_VERSION >= 6
0236
0237 #if NAPI_VERSION >= 8
0238 typedef struct {
0239   uint64_t lower;
0240   uint64_t upper;
0241 } napi_type_tag;
0242 #endif  // NAPI_VERSION >= 8
0243
0244 #endif  // SRC_JS_NATIVE_API_TYPES_H_