node-api: use c-based api for libnode embedding

doc/api/embedding.md

@@ -166,8 +166,47 @@ int RunNodeInstance(MultiIsolatePlatform* platform,
 }
 ```
 
+## Node-API Embedding
+
+<!--introduced_in=REPLACEME-->
+
+As an alternative, an embedded Node.js can also be fully controlled through
+Node-API. This API supports both C and C++ through [node-addon-api][].
+
+An example can be found [in the Node.js source tree][napi_embedding.c].
+
+```c
+  napi_platform platform;
+  napi_env env;
+  const char *main_script = "console.log('hello world')";
+
+  if (napi_create_platform(0, NULL, NULL, &platform) != napi_ok) {
+    fprintf(stderr, "Failed creating the platform\n");
+    return -1;
+  }
+
+  if (napi_create_environment(platform, NULL, main_script,
+        (napi_stdio){NULL, NULL, NULL}, NAPI_VERSION, &env) != napi_ok) {
+    fprintf(stderr, "Failed running JS\n");
+    return -1;
+  }
+
+  // Here you can interact with the environment through Node-API env
+
+  if (napi_destroy_environment(env, NULL) != napi_ok) {
+    return -1;
+  }
+
+  if (napi_destroy_platform(platform) != napi_ok) {
+    fprintf(stderr, "Failed destroying the platform\n");
+    return -1;
+  }
+```
+
 [CLI options]: cli.md
 [`process.memoryUsage()`]: process.md#processmemoryusage
 [deprecation policy]: deprecations.md
 [embedtest.cc]: https://github.com/nodejs/node/blob/HEAD/test/embedding/embedtest.cc
+[napi_embedding.c]: https://github.com/nodejs/node/blob/HEAD/test/embedding/napi_embedding.c
+[node-addon-api]: https://github.com/nodejs/node-addon-api
 [src/node.h]: https://github.com/nodejs/node/blob/HEAD/src/node.h

doc/api/n-api.md

@@ -6592,6 +6592,145 @@ idempotent.
 
 This API may only be called from the main thread.
 
+## Using embedded Node.js
+
+### `napi_create_platform`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+> Stability: 1 - Experimental
+
+```c
+napi_status napi_create_platform(int argc,
+                                    char** argv,
+                                    napi_error_message_handler err_handler,
+                                    napi_platform* result);
+```
+
+* `[in] argc`: CLI argument count, pass 0 for autofilling.
+* `[in] argv`: CLI arguments, pass NULL for autofilling.
+* `[in] err_handler`: If different than NULL, will be called back with each
+  error message. There can be multiple error messages but the API guarantees
+  that no calls will be made after the `napi_create_platform` has returned.
+  In practice, the implementation of graceful recovery is still in progress,
+  and many errors will be fatal, resulting in an `abort()`.
+* `[out] result`: A `napi_platform` result.
+
+This function must be called once to initialize V8 and Node.js when using as a
+shared library.
+
+### `napi_destroy_platform`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+> Stability: 1 - Experimental
+
+```c
+napi_status napi_destroy_platform(napi_platform platform);
+```
+
+* `[in] platform`: platform handle.
+
+Destroy the Node.js / V8 processes.
+
+### `napi_create_environment`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+> Stability: 1 - Experimental
+
+```c
+napi_status napi_create_environment(napi_platform platform,
+                                    napi_error_message_handler err_handler,
+                                    const char* main_script,
+                                    int32_t api_version,
+                                    napi_env* result);
+```
+
+* `[in] platform`: platform handle.
+* `[in] err_handler`: If different than NULL, will be called back with each
+  error message. There can be multiple error messages but the API guarantees
+  that no calls will be made after the `napi_create_platform` has returned.
+  In practice, the implementation of graceful recovery is still in progress,
+  and many errors will be fatal, resulting in an `abort()`.
+* `[in] main_script`: If different than NULL, custom JavaScript to run in
+  addition to the default bootstrap that creates an empty
+  ready-to-use CJS/ES6 environment with `global.require()` and
+  `global.import()` functions that resolve modules from the directory of
+  the compiled binary.
+  It can be used to redirect `process.stdin`/ `process.stdout` streams
+  since Node.js might switch these file descriptors to non-blocking mode.
+* `[in] api_version`: Node-API version to conform to, pass `NAPI_VERSION`
+  for the latest available.
+* `[out] result`: A `napi_env` result.
+
+Initialize a new environment. A single platform can hold multiple Node.js
+environments that will run in a separate V8 isolate each. If the returned
+value is `napi_ok` or `napi_pending_exception`, the environment must be
+destroyed with `napi_destroy_environment` to free all allocated memory.
+
+### `napi_run_environment`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+> Stability: 1 - Experimental
+
+```c
+napi_status napi_run_environment(napi_env env);
+```
+
+* `[in] env`: environment handle.
+
+Iterate the event loop of the environment. Executes all pending
+JavaScript callbacks. Cannot be called with JavaScript on the
+stack (ie in a JavaScript callback).
+
+### `napi_await_promise`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+> Stability: 1 - Experimental
+
+```c
+napi_status napi_await_promise(napi_env env,
+                            napi_value promise,
+                            napi_value *result);
+```
+
+* `[in] env`: environment handle.
+* `[in] promise`: JS Promise.
+* `[out] result`: Will receive the value that the Promise resolved with.
+
+Iterate the event loop of the environment until the `promise` has been
+resolved. Returns `napi_pending_exception` on rejection. Cannot be called
+with JavaScript on the stack (ie in a JavaScript callback).
+
+### `napi_destroy_environment`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+> Stability: 1 - Experimental
+
+```c
+napi_status napi_destroy_environment(napi_env env);
+```
+
+* `[in] env`: environment handle.
+
+Destroy the Node.js environment / V8 isolate.
+
 ## Miscellaneous utilities
 
 ### `node_api_get_module_file_name`

node.gyp

@@ -99,6 +99,7 @@
       'src/module_wrap.cc',
       'src/node.cc',
       'src/node_api.cc',
+      'src/node_api_embedding.cc',
       'src/node_binding.cc',
       'src/node_blob.cc',
       'src/node_buffer.cc',
@@ -222,6 +223,7 @@
       'src/module_wrap.h',
       'src/node.h',
       'src/node_api.h',
+      'src/node_api_embedding.h',
       'src/node_api_types.h',
       'src/node_binding.h',
       'src/node_blob.h',
@@ -1285,6 +1287,13 @@
       'sources': [
         'src/node_snapshot_stub.cc',
         'test/embedding/embedtest.cc',
+        'test/embedding/embedtest_concurrent_node_api.cc',
+        'test/embedding/embedtest_main.cc',
+        'test/embedding/embedtest_modules_node_api.cc',
+        'test/embedding/embedtest_node_api.cc',
+        'test/embedding/embedtest_node_api.h',
+        'test/embedding/embedtest_preload_node_api.cc',
+        'test/embedding/embedtest_snapshot_node_api.cc',
       ],
 
       'conditions': [