Skip to content

Update Node-API files #15

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Oct 15, 2025
Merged

Update Node-API files #15

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 21 additions & 0 deletions node-api/LICENSE
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
MIT License

Copyright (c) 2021 Node.js

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
14 changes: 14 additions & 0 deletions node-api/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
# Node-API header files

Files in this folder are the Node-API from Node.js project.
https://github.com/nodejs/node-api-headers/tree/main/include

They are augmented with the experiemental APIs from the Node.js project
https://github.com/nodejs/node

See the copy of the license file in this folder.

# Additional files

The js_runtime_api.h file is part of this project and
licensed under Microsoft MIT license.
75 changes: 44 additions & 31 deletions node-api/js_native_api.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,18 @@
#endif
#endif

#if defined(NAPI_EXPERIMENTAL) && \
!defined(NODE_API_EXPERIMENTAL_NO_WARNING) && \
!defined(NODE_WANT_INTERNALS)
#ifdef _MSC_VER
#pragma message("NAPI_EXPERIMENTAL is enabled. " \
"Experimental features may be unstable.")
#else
#warning "NAPI_EXPERIMENTAL is enabled. " \
"Experimental features may be unstable."
#endif
#endif

#include "js_native_api_types.h"

// If you need __declspec(dllimport), either include <node_api.h> instead, or
Expand Down Expand Up @@ -50,7 +62,7 @@
EXTERN_C_START

NAPI_EXTERN napi_status NAPI_CDECL napi_get_last_error_info(
node_api_nogc_env env, const napi_extended_error_info** result);
node_api_basic_env env, const napi_extended_error_info** result);

// Getters for defined singletons
NAPI_EXTERN napi_status NAPI_CDECL napi_get_undefined(napi_env env,
Expand Down Expand Up @@ -92,31 +104,31 @@ NAPI_EXTERN napi_status NAPI_CDECL napi_create_string_utf16(napi_env env,
const char16_t* str,
size_t length,
napi_value* result);
#ifdef NAPI_EXPERIMENTAL
#define NODE_API_EXPERIMENTAL_HAS_EXTERNAL_STRINGS
NAPI_EXTERN napi_status NAPI_CDECL
node_api_create_external_string_latin1(napi_env env,
char* str,
size_t length,
node_api_nogc_finalize finalize_callback,
void* finalize_hint,
napi_value* result,
bool* copied);
#if NAPI_VERSION >= 10
NAPI_EXTERN napi_status NAPI_CDECL node_api_create_external_string_latin1(
napi_env env,
char* str,
size_t length,
node_api_basic_finalize finalize_callback,
void* finalize_hint,
napi_value* result,
bool* copied);
NAPI_EXTERN napi_status NAPI_CDECL
node_api_create_external_string_utf16(napi_env env,
char16_t* str,
size_t length,
node_api_nogc_finalize finalize_callback,
node_api_basic_finalize finalize_callback,
void* finalize_hint,
napi_value* result,
bool* copied);
#endif // NAPI_EXPERIMENTAL

#ifdef NAPI_EXPERIMENTAL
#define NODE_API_EXPERIMENTAL_HAS_PROPERTY_KEYS
NAPI_EXTERN napi_status NAPI_CDECL node_api_create_property_key_latin1(
napi_env env, const char* str, size_t length, napi_value* result);
NAPI_EXTERN napi_status NAPI_CDECL node_api_create_property_key_utf8(
napi_env env, const char* str, size_t length, napi_value* result);
NAPI_EXTERN napi_status NAPI_CDECL node_api_create_property_key_utf16(
napi_env env, const char16_t* str, size_t length, napi_value* result);
#endif // NAPI_EXPERIMENTAL
#endif // NAPI_VERSION >= 10

NAPI_EXTERN napi_status NAPI_CDECL napi_create_symbol(napi_env env,
napi_value description,
Expand Down Expand Up @@ -318,12 +330,13 @@ napi_define_class(napi_env env,
napi_value* result);

// Methods to work with external data objects
NAPI_EXTERN napi_status NAPI_CDECL napi_wrap(napi_env env,
napi_value js_object,
void* native_object,
node_api_nogc_finalize finalize_cb,
void* finalize_hint,
napi_ref* result);
NAPI_EXTERN napi_status NAPI_CDECL
napi_wrap(napi_env env,
napi_value js_object,
void* native_object,
node_api_basic_finalize finalize_cb,
void* finalize_hint,
napi_ref* result);
NAPI_EXTERN napi_status NAPI_CDECL napi_unwrap(napi_env env,
napi_value js_object,
void** result);
Expand All @@ -333,7 +346,7 @@ NAPI_EXTERN napi_status NAPI_CDECL napi_remove_wrap(napi_env env,
NAPI_EXTERN napi_status NAPI_CDECL
napi_create_external(napi_env env,
void* data,
node_api_nogc_finalize finalize_cb,
node_api_basic_finalize finalize_cb,
void* finalize_hint,
napi_value* result);
NAPI_EXTERN napi_status NAPI_CDECL napi_get_value_external(napi_env env,
Expand Down Expand Up @@ -432,7 +445,7 @@ NAPI_EXTERN napi_status NAPI_CDECL
napi_create_external_arraybuffer(napi_env env,
void* external_data,
size_t byte_length,
node_api_nogc_finalize finalize_cb,
node_api_basic_finalize finalize_cb,
void* finalize_hint,
napi_value* result);
#endif // NODE_API_NO_EXTERNAL_BUFFERS_ALLOWED
Expand Down Expand Up @@ -474,7 +487,7 @@ napi_get_dataview_info(napi_env env,
size_t* byte_offset);

// version management
NAPI_EXTERN napi_status NAPI_CDECL napi_get_version(node_api_nogc_env env,
NAPI_EXTERN napi_status NAPI_CDECL napi_get_version(node_api_basic_env env,
uint32_t* result);

// Promises
Expand All @@ -498,7 +511,7 @@ NAPI_EXTERN napi_status NAPI_CDECL napi_run_script(napi_env env,

// Memory management
NAPI_EXTERN napi_status NAPI_CDECL napi_adjust_external_memory(
node_api_nogc_env env, int64_t change_in_bytes, int64_t* adjusted_value);
node_api_basic_env env, int64_t change_in_bytes, int64_t* adjusted_value);

#if NAPI_VERSION >= 5

Expand All @@ -520,7 +533,7 @@ NAPI_EXTERN napi_status NAPI_CDECL
napi_add_finalizer(napi_env env,
napi_value js_object,
void* finalize_data,
node_api_nogc_finalize finalize_cb,
node_api_basic_finalize finalize_cb,
void* finalize_hint,
napi_ref* result);

Expand All @@ -530,7 +543,7 @@ napi_add_finalizer(napi_env env,
#define NODE_API_EXPERIMENTAL_HAS_POST_FINALIZER

NAPI_EXTERN napi_status NAPI_CDECL
node_api_post_finalizer(node_api_nogc_env env,
node_api_post_finalizer(node_api_basic_env env,
napi_finalize finalize_cb,
void* finalize_data,
void* finalize_hint);
Expand Down Expand Up @@ -575,13 +588,13 @@ napi_get_all_property_names(napi_env env,

// Instance data
NAPI_EXTERN napi_status NAPI_CDECL
napi_set_instance_data(node_api_nogc_env env,
napi_set_instance_data(node_api_basic_env env,
void* data,
napi_finalize finalize_cb,
void* finalize_hint);

NAPI_EXTERN napi_status NAPI_CDECL napi_get_instance_data(node_api_nogc_env env,
void** data);
NAPI_EXTERN napi_status NAPI_CDECL
napi_get_instance_data(node_api_basic_env env, void** data);
#endif // NAPI_VERSION >= 6

#if NAPI_VERSION >= 7
Expand Down
27 changes: 13 additions & 14 deletions node-api/js_native_api_types.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,11 +7,6 @@
#include <stddef.h> // NOLINT(modernize-deprecated-headers)
#include <stdint.h> // NOLINT(modernize-deprecated-headers)

// TODO: (vmoroz) NODE_API_EXPERIMENTAL_NOGC_ENV_OPT_OUT is not part of this
// Node-API file. It is here temporary to enable compilation. Remove it after
// updating tests.
#define NODE_API_EXPERIMENTAL_NOGC_ENV_OPT_OUT

#if !defined __cplusplus || (defined(_MSC_VER) && _MSC_VER < 1900)
typedef uint16_t char16_t;
#endif
Expand All @@ -32,7 +27,7 @@ typedef struct napi_env__* napi_env;
// meaning that they do not affect the state of the JS engine, and can
// therefore be called synchronously from a finalizer that itself runs
// synchronously during GC. Such APIs can receive either a `napi_env` or a
// `node_api_nogc_env` as their first parameter, because we should be able to
// `node_api_basic_env` as their first parameter, because we should be able to
// also call them during normal, non-garbage-collecting operations, whereas
// APIs that affect the state of the JS engine can only receive a `napi_env` as
// their first parameter, because we must not call them during GC. In lieu of
Expand All @@ -42,19 +37,21 @@ typedef struct napi_env__* napi_env;
// expecting a non-const value.
//
// In conjunction with appropriate CFLAGS to warn us if we're passing a const
// (nogc) environment into an API that expects a non-const environment, and the
// definition of nogc finalizer function pointer types below, which receive a
// nogc environment as their first parameter, and can thus only call nogc APIs
// (unless the user explicitly casts the environment), we achieve the ability
// to ensure at compile time that we do not call APIs that affect the state of
// the JS engine from a synchronous (nogc) finalizer.
// (basic) environment into an API that expects a non-const environment, and
// the definition of basic finalizer function pointer types below, which
// receive a basic environment as their first parameter, and can thus only call
// basic APIs (unless the user explicitly casts the environment), we achieve
// the ability to ensure at compile time that we do not call APIs that affect
// the state of the JS engine from a synchronous (basic) finalizer.
#if !defined(NAPI_EXPERIMENTAL) || \
(defined(NAPI_EXPERIMENTAL) && \
defined(NODE_API_EXPERIMENTAL_NOGC_ENV_OPT_OUT))
(defined(NODE_API_EXPERIMENTAL_NOGC_ENV_OPT_OUT) || \
defined(NODE_API_EXPERIMENTAL_BASIC_ENV_OPT_OUT)))
typedef struct napi_env__* node_api_nogc_env;
#else
typedef const struct napi_env__* node_api_nogc_env;
#endif
typedef node_api_nogc_env node_api_basic_env;

typedef struct napi_value__* napi_value;
typedef struct napi_ref__* napi_ref;
Expand Down Expand Up @@ -152,13 +149,15 @@ typedef void(NAPI_CDECL* napi_finalize)(napi_env env,

#if !defined(NAPI_EXPERIMENTAL) || \
(defined(NAPI_EXPERIMENTAL) && \
defined(NODE_API_EXPERIMENTAL_NOGC_ENV_OPT_OUT))
(defined(NODE_API_EXPERIMENTAL_NOGC_ENV_OPT_OUT) || \
defined(NODE_API_EXPERIMENTAL_BASIC_ENV_OPT_OUT)))
typedef napi_finalize node_api_nogc_finalize;
#else
typedef void(NAPI_CDECL* node_api_nogc_finalize)(node_api_nogc_env env,
void* finalize_data,
void* finalize_hint);
#endif
typedef node_api_nogc_finalize node_api_basic_finalize;

typedef struct {
// One of utf8name or name should be NULL.
Expand Down
23 changes: 19 additions & 4 deletions node-api/js_runtime_api.h
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@
#ifndef SRC_JS_RUNTIME_API_H_
#define SRC_JS_RUNTIME_API_H_

#include "js_native_api.h"
#include "node_api.h"

//
// Node-API extensions required for JavaScript engine hosting.
Expand Down Expand Up @@ -51,6 +51,16 @@ JSR_API jsr_config_enable_gc_api(jsr_config config, bool value);

JSR_API jsr_config_set_explicit_microtasks(jsr_config config, bool value);

// A callback to process unhandled JS error
typedef void(NAPI_CDECL* jsr_unhandled_error_cb)(void* cb_data,
napi_env env,
napi_value error);

JSR_API jsr_config_on_unhandled_error(
jsr_config config,
void* cb_data,
jsr_unhandled_error_cb unhandled_error_cb);

//=============================================================================
// jsr_config task runner
//=============================================================================
Expand Down Expand Up @@ -187,13 +197,18 @@ JSR_API jsr_get_and_clear_last_unhandled_promise_rejection(napi_env env,
napi_value* result);

// Create new napi_env for the runtime.
JSR_API jsr_create_node_api_env(napi_env root_env,
int32_t api_version,
napi_env* env);
JSR_API
jsr_create_node_api_env(napi_env root_env, int32_t api_version, napi_env* env);

// Run task in the environment context.
JSR_API jsr_run_task(napi_env env, jsr_task_run_cb task_cb, void* data);

// Initializes native module.
JSR_API jsr_initialize_native_module(napi_env env,
napi_addon_register_func register_module,
int32_t api_version,
napi_value* exports);

EXTERN_C_END

#endif // !SRC_JS_RUNTIME_API_H_
Loading