From 13b5ace4dbcfae422fa1a1d347a4b994973987bd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tobias=20Nie=C3=9Fen?= Date: Mon, 9 Dec 2019 01:16:54 -0400 Subject: [PATCH] doc: explain napi_run_script PR-URL: https://github.com/nodejs/node/pull/30918 Reviewed-By: Luigi Pinca Reviewed-By: Anna Henningsen Reviewed-By: Rich Trott Reviewed-By: Chengzhong Wu Reviewed-By: Ruben Bridgewater Reviewed-By: James M Snell --- doc/api/n-api.md | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/doc/api/n-api.md b/doc/api/n-api.md index 1eecb7f1129c40..ffb8eb8e9714a7 100644 --- a/doc/api/n-api.md +++ b/doc/api/n-api.md @@ -4929,6 +4929,19 @@ NAPI_EXTERN napi_status napi_run_script(napi_env env, * `[in] script`: A JavaScript string containing the script to execute. * `[out] result`: The value resulting from having executed the script. +This function executes a string of JavaScript code and returns its result with +the following caveats: + +* Unlike `eval`, this function does not allow the script to access the current + lexical scope, and therefore also does not allow to access the + [module scope][], meaning that pseudo-globals such as `require` will not be + available. +* The script can access the [global scope][]. Function and `var` declarations + in the script will be added to the [`global`][] object. Variable declarations + made using `let` and `const` will be visible globally, but will not be added + to the [`global`][] object. +* The value of `this` is [`global`][] within the script. + ## libuv event loop N-API provides a function for getting the current event loop associated with @@ -5291,6 +5304,7 @@ This API may only be called from the main thread. [Xcode]: https://developer.apple.com/xcode/ [`Number.MAX_SAFE_INTEGER`]: https://tc39.github.io/ecma262/#sec-number.max_safe_integer [`Number.MIN_SAFE_INTEGER`]: https://tc39.github.io/ecma262/#sec-number.min_safe_integer +[`global`]: globals.html#globals_global [`init` hooks]: async_hooks.html#async_hooks_init_asyncid_type_triggerasyncid_resource [`napi_add_finalizer`]: #n_api_napi_add_finalizer [`napi_async_init`]: #n_api_napi_async_init @@ -5341,6 +5355,8 @@ This API may only be called from the main thread. [async_hooks `type`]: async_hooks.html#async_hooks_type [context-aware addons]: addons.html#addons_context_aware_addons [docs]: https://github.com/nodejs/node-addon-api#api-documentation +[global scope]: globals.html +[module scope]: modules.html#modules_the_module_scope [node-addon-api]: https://github.com/nodejs/node-addon-api [node-gyp]: https://github.com/nodejs/node-gyp [node-pre-gyp]: https://github.com/mapbox/node-pre-gyp