doc: clarify N-API version 1

[mhdawson]

Refs: nodejs/node-addon-api#760

Clarify which version of 8.x in which N-API version 1
matches the shape in later versions like 10.x

Signed-off-by: Michael Dawson michael_dawson@ca.ibm.com

Checklist

• make -j4 test (UNIX), or vcbuild test (Windows) passes
• documentation is changed or added
• commit message follows commit guidelines

[mhdawson]

hmm, meant to delete my suggestion that made no change but seem to have deleted other comments as well. @Trott sorry about that.

In any case, hopefully fixed up the linting issue now, we'll see if the linters pass.

[gabrielschulhof]

LGTM with a few comments.

[gabrielschulhof]

Suggested change

	We recommend version 3 or later.
	This also means that our ABI stability guarantee starts at version v8.7.0.
	We recommend version 3 or later.

Feel free to rephrase or even discard. The objective I'm trying to achieve with the suggestion is that the final phrasing include a reference to ABI stability and the earliest version which is ABI-compatible with what we have today.

Is v8.7.0 truly the first version of Node.js whose N-API implementation is ABI-compatible with today's? IIRC we had the final ABI in place even while we were still in experimental. Of course, it may not be worth pushing back the documented number a couple of minor versions just to "maximize our coverage".

[mhdawson]

@gabrielschulhof 8.7.0 is the earliest level that @devsnek reported as being compatible so believe it was the earliest.

[mhdawson]

@gabrielschulhof I think I'd also prefer to leave out the extra sentence as I think it restates what the earlier lines say in a bit more detail.

[devsnek]

I don't know exactly. I gauged it based on when node-addon-api headers didn't have undefined symbols and such. I don't exhaustively test if it actually works.

[mhdawson]

The diff between 8.7.0 and the last 8.x version (8.17.0) for node_api.h is:

iff --git a/src/node_api.h b/src/node_api.h
index a3a07a6..f683f8d 100644
--- a/src/node_api.h
+++ b/src/node_api.h
@@ -1,19 +1,23 @@
-/******************************************************************************
- * Experimental prototype for demonstrating VM agnostic and ABI stable API
- * for native modules to use instead of using Nan and V8 APIs directly.
- *
- * The current status is "Experimental" and should not be used for
- * production applications.  The API is still subject to change
- * and as an experimental feature is NOT subject to semver.
- *
- ******************************************************************************/
 #ifndef SRC_NODE_API_H_
 #define SRC_NODE_API_H_

 #include <stddef.h>
 #include <stdbool.h>
+
+#ifndef NAPI_VERSION
+#ifdef NAPI_EXPERIMENTAL
+// Use INT_MAX, this should only be consumed by the pre-processor anyway.
+#define NAPI_VERSION 2147483647
+#else
+// The baseline version for N-API
+#define NAPI_VERSION 4
+#endif
+#endif
+
 #include "node_api_types.h"

+struct uv_loop_s;  // Forward declaration.
+
 #ifdef _WIN32
   #ifdef BUILDING_NODE_EXTENSION
     #ifdef EXTERNAL_NAPI
@@ -98,7 +102,7 @@ typedef struct {
   EXTERN_C_END

 #define NAPI_MODULE(modname, regfunc) \
-  NAPI_MODULE_X(modname, regfunc, NULL, 0)
+  NAPI_MODULE_X(modname, regfunc, NULL, 0)  // NOLINT (readability/null_usage)

 #define NAPI_AUTO_LENGTH SIZE_MAX

@@ -175,7 +179,7 @@ NAPI_EXTERN napi_status napi_create_range_error(napi_env env,
                                                 napi_value msg,
                                                 napi_value* result);

-// Methods to get the the native napi_value from Primitive type
+// Methods to get the native napi_value from Primitive type
 NAPI_EXTERN napi_status napi_typeof(napi_env env,
                                     napi_value value,
                                     napi_valuetype* result);
@@ -581,6 +585,76 @@ NAPI_EXTERN napi_status napi_run_script(napi_env env,
                                         napi_value script,
                                         napi_value* result);

+#if NAPI_VERSION >= 2
+
+// Return the current libuv event loop for a given environment
+NAPI_EXTERN napi_status napi_get_uv_event_loop(napi_env env,
+                                               struct uv_loop_s** loop);
+
+#endif  // NAPI_VERSION >= 2
+
+#if NAPI_VERSION >= 3
+
+NAPI_EXTERN napi_status napi_open_callback_scope(napi_env env,
+                                                 napi_value resource_object,
+                                                 napi_async_context context,
+                                                 napi_callback_scope* result);
+
+NAPI_EXTERN napi_status napi_close_callback_scope(napi_env env,
+                                                  napi_callback_scope scope);
+
+NAPI_EXTERN napi_status napi_fatal_exception(napi_env env, napi_value err);
+
+NAPI_EXTERN napi_status napi_add_env_cleanup_hook(napi_env env,
+                                                  void (*fun)(void* arg),
+                                                  void* arg);
+
+NAPI_EXTERN napi_status napi_remove_env_cleanup_hook(napi_env env,
+                                                     void (*fun)(void* arg),
+                                                     void* arg);
+
+#endif  // NAPI_VERSION >= 3
+
+#if NAPI_VERSION >= 4
+
+// Calling into JS from other threads
+NAPI_EXTERN napi_status
+napi_create_threadsafe_function(napi_env env,
+                                napi_value func,
+                                napi_value async_resource,
+                                napi_value async_resource_name,
+                                size_t max_queue_size,
+                                size_t initial_thread_count,
+                                void* thread_finalize_data,
+                                napi_finalize thread_finalize_cb,
+                                void* context,
+                                napi_threadsafe_function_call_js call_js_cb,
+                                napi_threadsafe_function* result);
+
+NAPI_EXTERN napi_status
+napi_get_threadsafe_function_context(napi_threadsafe_function func,
+                                     void** result);
+
+
+NAPI_EXTERN napi_status
+napi_call_threadsafe_function(napi_threadsafe_function func,
+                              void* data,
+                              napi_threadsafe_function_call_mode is_blocking);
+
+NAPI_EXTERN napi_status
+napi_acquire_threadsafe_function(napi_threadsafe_function func);
+
+NAPI_EXTERN napi_status
+napi_release_threadsafe_function(napi_threadsafe_function func,
+                                 napi_threadsafe_function_release_mode mode);
+
+NAPI_EXTERN napi_status
+napi_unref_threadsafe_function(napi_env env, napi_threadsafe_function func);
+
+NAPI_EXTERN napi_status
+napi_ref_threadsafe_function(napi_env env, napi_threadsafe_function func);
+
+#endif  // NAPI_VERSION >= 4
+
 EXTERN_C_END

 #endif  // SRC_NODE_API_H_

[mhdawson]

Looking at the additions I don't see any API changes from 8.7.0 and the last 8.x version in the diff above (+struct uv_loop_s; // Forward declaration. was added as part of the NAPI_VERSION_2 addition, not sure why we did that but that's a separate issue)

[mhdawson]

git diff v8.6.0..v8.7.0 src/node_api.h shows no changes

[mhdawson]

git diff v8.5.0..v8.6.0 src/node_api.h show a number of changes in the API.

I think that would likely say that v8.6.0 is the right one to specify. There don't seem to be any changes in the api file between v8.6.0 that and the last 8.x version which would affect the API shape. It was still experimental so there would be no guarantees about it working properly or internal behavior changing but that is not relevant to us adding the comment about when the shape of V1 was finalized.

@devsnek I'll update to v8.6.0 unless what you saw contradicts that.

[devsnek]

checking this again, it appears to be 8.6.0, not 8.7.0. 8.5.0 is missing napi_async_context and NAPI_AUTO_LENGTH which are both in version 1.

[mhdawson]

@devsnek thanks for confirming, we must have both been investigating at the same time.

[mhdawson]

@gabrielf , @devsnek updated to say v8.6.0 and I think that's correct based on the info I pasted above.

[mhdawson]

Only changes doc, so once linters complete running on the latest change I'll go ahead and land.

[mhdawson]

Landed in 15333ad