[GR-37716] Review the usage of NI terminology; Node version update.

PullRequest: js/2471

Author: olyagpl

docs/user/FAQ.md

@@ -89,17 +89,17 @@ Solution:
 Here are a few tips you can follow to analyse and improve peak performance:
 
 * When measuring, ensure you have given the GraalVM compiler enough time to compile all hot methods before starting to measure peak performance. A useful command line option for that is `--engine.TraceCompilation=true` -- this outputs a message whenever a (JavaScript) method is compiled. As long as this still prints frequently, measurement should not yet start.
-* Compare the performance between the Native Image and the JVM mode if possible. Depending on the characteristics of your application, one or the other might show better peak performance.
+* Compare the performance between Native Image and the JVM mode if possible. Depending on the characteristics of your application, one or the other might show better peak performance.
 * The Polyglot API comes with several tools and options to inspect the performance of your application:
     * `--cpusampler` and `--cputracer` will print a list of the hottest methods when the application is terminated. Use that list to figure out where most time is spent in your application.
     * `--experimental-options --memtracer` can help you understand the memory allocations of your application. Refer to the [Profiling Command Line Tool](https://github.com/oracle/graal/blob/master/docs/tools/profiling.md) reference for more detail.
 
-### What is the difference between running GraalVM's JavaScript in a Native Image compared to the JVM?
+### What is the difference between running GraalVM's JavaScript in Native Image compared to the JVM?
 In essence, the JavaScript engine of GraalVM is a plain Java application.
 Running it on any JVM (JDK 8 or higher) is possible, but, for a better result, it should be GraalVM or a compatible JVMCI-enabled JDK using the GraalVM compiler.
 This mode gives the JavaScript engine full access to Java at runtime, but also requires the JVM to first (just-in-time) compile the JavaScript engine when executed, just like any other Java application.
 
-Running in a Native Image means that the JavaScript engine, including all its dependencies from, e.g., the JDK, is pre-compiled into a native binary. This will tremendously speed up the startup of any JavaScript application, as GraalVM can immediately start to compile JavaScript code, without itself requiring to be compiled first.
+Running in Native Image means that the JavaScript engine, including all its dependencies from, e.g., the JDK, is pre-compiled into a native executable. This will tremendously speed up the startup of any JavaScript application, as GraalVM can immediately start to compile JavaScript code, without itself requiring to be compiled first.
 This mode, however, will only give GraalVM access to Java classes known at the time of image creation.
 Most significantly, this means that the JavaScript-to-Java interoperability features are not available in this mode, as they would require dynamic class loading and execution of arbitrary Java code at runtime.
 

docs/user/JavaInteroperability.md

@@ -14,7 +14,12 @@ See the [Embedding Reference](https://www.graalvm.org/reference-manual/embed-lan
 The [Polyglot Programming](https://www.graalvm.org/reference-manual/polyglot-programming/) guide can be of additional help in that area.
 Specific migration guides for [Rhino](RhinoMigrationGuide.md) and [Nashorn](NashornMigrationGuide.md) are also available.
 
-By default, GraalVM ships with `js` and `node` native launchers.
+GraalVM ships with the `js` native launcher.
+The Node.js support is packaged separately and can be installed with GraalVM Updater:
+```shell
+$GRAALVM/bin/gu install nodejs
+```
+Then the `node` launcher becomes available.
 Although other builds are possible, the following examples assume this setup is used.
 
 ## Enabling Java Interoperability

docs/user/Modules.md

@@ -15,7 +15,7 @@ GraalVM ships with a specific Node.js version that it is compatible with.
 Applications can therefore freely import and use NPM packages compatible with the supported Node.js version, including CommonJS, ES modules, and modules that use native bindings.
 To check and verify the Node.js version supported by GraalVM, simply run `bin/node --version`.
 
-## Java-based applications (`Context` API)
+## Java-based Applications (`Context` API)
 
 When embedded in a Java application (using the `Context` API), GraalVM JavaScript can execute JavaScript applications and modules that _do not_ depend on Node.js' built-in modules such as `'fs'`, `'events'`, or `'http'` or Node.js-specific functions such as `setTimeout()` or `setInterval()`.
 On the other hand, modules that depend on such Node.js builtins cannot be loaded in a GraalVM polyglot `Context`.

docs/user/NodeJS.md

@@ -11,7 +11,7 @@ Applications can freely import and use NPM packages, including native ones.
 
 For the differences between running the `node` native launcher and accessing Node.js/npm modules/ECMAScript modules from a Java Context, see [NodeJSVSJavaScriptContext](NodeJSVSJavaScriptContext.md).
 
-## Installing the Node.js component
+## Installing Node.js Component
 
 Since GraalVM 21.1, the Node.js support is packaged in a separate GraalVM component.
 It can be installed with the _GraalVM Updater_.
@@ -22,28 +22,28 @@ $GRAALVM/bin/gu install nodejs
 
 This installs the `node` and `npm` binaries in the `$GRAALVM/bin` directory.
 
-### Polyglot support in Node.js
+### Polyglot Support in Node.js
 
 The Node.js component is able to use the polyglot language interoperability (flag: `--polyglot`) with other installed polyglot languages.
 This feature is available by default in JVM mode (flag: `--jvm`).
 For polyglot access to the Ruby language, you can e.g. use this command:
 
 ```shell
-$GRAALVM/bin/node --jvm --polyglot -e 'var array = Polyglot.eval("ruby", "[1,2,42,4]"); console.log(array[2]);'
+$GRAALVM_HOME/bin/node --jvm --polyglot -e 'var array = Polyglot.eval("ruby", "[1,2,42,4]"); console.log(array[2]);'
 ```
 
 To use the polyglot capabilities of `node` in the native mode (flag: `--native`), the `libpolyglot` needs to be rebuilt first.
 For this, the `native-image` component and the other languages need to be installed first, before the image can be rebuilt:
 
 ```shell
-$GRAALVM/bin/gu install native-image
-$GRAALVM/bin/gu rebuild-images libpolyglot
+$GRAALVM_HOME/bin/gu install native-image
+$GRAALVM_HOME/bin/gu rebuild-images libpolyglot
 ```
 
 After a successfull rebuild, the polyglot access is also available in the `--native` mode:
 
 ```shell
-$GRAALVM/bin/node --native --polyglot -e 'var array = Polyglot.eval("ruby", "[1,2,42,4]"); console.log(array[2]);'
+$GRAALVM_HOME/bin/node --native --polyglot -e 'var array = Polyglot.eval("ruby", "[1,2,42,4]"); console.log(array[2]);'
 ```
 
 ## Running Node.js Applications

docs/user/Options.md

@@ -31,13 +31,13 @@ For a full list of options of the JavaScript engine, pass the `--help:js` flag t
 To include internal options, use `--help:js:internal`.
 Note that those lists both include stable, supported options and experimental options.
 
-### Provide options to the Launcher
+### Provide Options to the Launcher
 To the launcher, the options are passed with `--js.<option-name>=<value>`:
 ```shell
 js --js.ecmascript-version=6
 ```
 
-### Provide options programmatically using the Context API
+### Provide Options Programmatically Using the Context API
 When started from Java via GraalVM's Polyglot feature, the options are passed programmatically to the `Context` object:
 ```java
 Context context = Context.newBuilder("js")
@@ -57,7 +57,7 @@ In the native launchers (`js` and `node`), `--experimental-options` has to be pa
 When using a `Context`, the option `allowExperimentalOptions(true)` has to be called on the `Context.Builder`.
 See [ScriptEngine Implementation](ScriptEngine.md) on how to use experimental options with a `ScriptEngine`.
 
-### Frequently used Stable Options
+### Frequently Used Stable Options
 The following stable options are frequently relevant:
    * `--js.ecmascript-version`: emulate a specific ECMAScript version. Integer value (`5`, `6`, etc., `2015`-`2022`), `"latest"` (latest supported version of the spec, including finished proposals), or `"staging"` (latest version including supported unfinished proposals), default is `"latest"`.
    * `--js.foreign-object-prototype`: provide JavaScript's default prototype to foreign objects that mimic JavaScript's own types (foreign Arrays, Objects and Functions). Boolean value, default is `false`.
@@ -74,7 +74,7 @@ It expects an integer value, where both the counting version numbers (`5`, `6`,
 As of GraalVM 21.2, `latest`, `staging` are supported, too.
 The default in GraalVM 22.x is the [`ECMAScript 2022 specification`](https://tc39.es/ecma262/).
 GraalVM JavaScript implements some features of the future draft specification and of open proposals, if you explicitly select that version and/or enable specific experimental flags.
-For production settings, it is recommended to set the `ecmascript-version` to a released, finalized version of the specification (e.g. `2021`).
+For production settings, it is recommended to set the `ecmascript-version` to a released, finalized version of the specification (e.g., `2021`).
 
 Available versions are:
 * `5` for ECMAScript 5.x
@@ -99,7 +99,7 @@ It expects a Boolean value and the default is `false`.
 This option enables JavaScript's strict mode for all scripts.
 It expects a Boolean value and the default is `false`.
 
-### Frequently used Experimental Options
+### Frequently Used Experimental Options
 Note that these options are experimental and are not guaranteed to be maintained or supported in the future.
 To use them, the `--experimental-options` flag is required or the experimental options have to be enabled on the Context, see above.
 

docs/user/README.md

@@ -33,10 +33,10 @@ $GRAALVM/bin/gu install nodejs
 Alternatively, you can also download the Node.js runtime plugin installable manually and install it from a file, e.g.:
 
 ```shell
-$ $GRAALVM/bin/gu install --file ~/Downloads/nodejs-installable-svm-java17-linux-amd64-21.3.0.jar
+$ $GRAALVM/bin/gu install --file ~/Downloads/nodejs-installable-...-.jar
 ```
 
-This installs the `node` and `npm` binaries in the `$GRAALVM/bin` directory.
+This installs the `node` and `npm` binaries in the `$GRAALVM_HOME/bin` directory.
 Use the `node` utility to execute Node.js applications:
 ```shell
 node [options] [filename] [args]
@@ -45,30 +45,31 @@ node [options] [filename] [args]
 To install a Node.js package, use the `npm` launcher from the GraalVM's `/bin` folder.
 The `npm` command is equivalent to the default Node.js command and supports all Node.js APIs.
 
-1. Install the `colors` and `ansispan` packages using `npm install` as follows:
-```shell
-npm install colors ansispan
-```
-After the packages are installed, you can use them from your application.
+1. Install the `colors` and `ansispan` packages using `npm install` as follows:
+    ```shell
+    npm install colors ansispan
+    ```
+    After the packages are installed, you can use them from your application.
 
-2. Add the following code snippet to a file named `app.js` and save it in the same directory where you installed the Node.js packages:
-```js
-const http = require("http");
-const span = require("ansispan");
-require("colors");
+2. Add the following code snippet to a file named `app.js` and save it in the same directory where you installed the Node.js packages:
+    ```js
+    const http = require("http");
+    const span = require("ansispan");
+    require("colors");
 
-http.createServer(function (request, response) {
-    response.writeHead(200, {"Content-Type": "text/html"});
-    response.end(span("Hello Graal.js!".green));
-}).listen(8000, function() { console.log("Graal.js server running at http://127.0.0.1:8000/".red); });
+    http.createServer(function (request, response) {
+        response.writeHead(200, {"Content-Type": "text/html"});
+        response.end(span("Hello Graal.js!".green));
+    }).listen(8000, function() { console.log("Graal.js server running at http://127.0.0.1:8000/".red); });
 
-setTimeout(function() { console.log("DONE!"); process.exit(); }, 2000);
-```
+    setTimeout(function() { console.log("DONE!"); process.exit(); }, 2000);
+    ```
+
+3. Execute it on GraalVM using the `node` command as follows:
+    ```shell
+    node app.js
+    ```
 
-3. Execute it on GraalVM using the `node` command as follows:
-```shell
-node app.js
-```
 For more information about running Node.js, continue to [Node.js Runtime](NodeJS.md).
 Node.js functionality is available when an application is started from the `node` binary launcher.
 Certain limits apply when launching a Node.js application or accessing npm packages from a Java context, see [Node.js vs. Java Script Context](NodeJSVSJavaScriptContext.md).
@@ -82,7 +83,7 @@ To enable Node.js or JavaScript interoperability with other languages, pass the
 
 ```shell
 node --jvm --polyglot
-Welcome to Node.js v12.15.0.
+Welcome to Node.js v16.14.2.
 Type ".help" for more information.
 > var array = Polyglot.eval("python", "[1,2,42,4]")
 > console.log(array[2]);
@@ -147,7 +148,8 @@ Hello Java!
 hello from node.js
 done
 ```
-By setting the classpath, you instruct `node` to start a JVM properly. Both Node.js and JVM then run in the same process and the interoperability works using the same `Value` classes as above.
+By setting the classpath, you instruct `node` to start a JVM properly. 
+Both Node.js and JVM then run in the same process and the interoperability works using the same `Value` classes as above.
 
 Learn more about language interoperability in the [Java Interoperability](JavaInteroperability.md) guide.