From 861de3af2768e4a9dfcc335cd11fe2f9f467e156 Mon Sep 17 00:00:00 2001 From: Pete Cornish Date: Tue, 16 Jul 2024 23:58:47 +0100 Subject: [PATCH] docs: reference GraalVM as default JavaScript engine. --- docs/index.md | 1 + docs/scripting_legacy_js.md | 66 +++++++++++++++++++++++++++++++++++++ docs/scripting_modern_js.md | 46 ++++++-------------------- mkdocs.yml | 1 + 4 files changed, 78 insertions(+), 36 deletions(-) create mode 100644 docs/scripting_legacy_js.md diff --git a/docs/index.md b/docs/index.md index 03f2b0f09..b0934419f 100644 --- a/docs/index.md +++ b/docs/index.md @@ -38,6 +38,7 @@ To begin, check out the [Getting started](getting_started.md) guide. See the _Co - [Generating fake data](fake_data.md) - [CORS](cors.md) - [Groovy scripting tips](groovy_tips.md) +- [JavaScript compatibility](scripting_modern_js.md) - [Examples](https://github.com/outofcoffee/imposter/tree/main/examples) ### Data capture and storage diff --git a/docs/scripting_legacy_js.md b/docs/scripting_legacy_js.md new file mode 100644 index 000000000..03467c11d --- /dev/null +++ b/docs/scripting_legacy_js.md @@ -0,0 +1,66 @@ +# Using legacy JavaScript engine (Nashorn) + +The [default JavaScript engine is GraalVM](./scripting_modern_js.md), which is based on ECMAScript 2022 (more formally, [ECMA-262, 13th edition](https://262.ecma-international.org/13.0/)). Whilst GraalVM provides support for modern JavaScript features, it is more resource intensive than the legacy Nashorn JavaScript engine, which only supports ECMAScript 5 (ES5). You can switch to the Nashorn JavaScript engine using its plugin. + +To use the Nashorn JavaScript engine, you need to be running Imposter v4.0.0 or later, and install the `js-nashorn` plugin. + +## Install plugin + +### Option 1: Using the CLI + +> **Note** +> This option requires the [Imposter CLI](./run_imposter_cli.md) version 0.37.0 or later. + +To use this plugin, install it with the Imposter CLI: + + imposter plugin install -d js-nashorn + +This will install the plugin version matching the current engine version used by the CLI. The next time you run `imposter up`, the plugin will be available. + +### Option 2: Install the plugin manually + +To use this plugin, download the `imposter-plugin-js-nashorn.jar` JAR file from the [Releases page](https://github.com/outofcoffee/imposter/releases). + +Enable it with the following environment variable: + + IMPOSTER_PLUGIN_DIR="/path/to/dir/containing/plugin" + +## Using the plugin + +To use Nashorn, you need to specify the `js-nashorn` engine as the JavaScript plugin. You can do this by setting the environment variable `IMPOSTER_JS_PLUGIN` to `js-nashorn`: + +```bash +export IMPOSTER_JS_PLUGIN=js-nashorn +``` + +--- + +## Example + +> **Note** +> Complete the prerequisites first. + +Start the mock server with the `js-nashorn` engine: + +```bash +imposter up examples/rest/conditional-scripted -e IMPOSTER_JS_PLUGIN=js-nashorn +``` + +Send a request to the mock server: + +```bash +curl -i http://localhost:8080/pets + +[ + { + "id": 1, + "name": "Fluffy" + }, + { + "id": 2, + "name": "Paws" + } +] +``` + +* See the `examples/rest/conditional-scripted` directory [in GitHub](https://github.com/outofcoffee/imposter/blob/main/examples/rest/conditional-scripted). diff --git a/docs/scripting_modern_js.md b/docs/scripting_modern_js.md index 44a1f0a26..0a6e5af2e 100644 --- a/docs/scripting_modern_js.md +++ b/docs/scripting_modern_js.md @@ -1,6 +1,6 @@ # Using modern JavaScript features in scripts -The default JavaScript engine is Nashorn, which is based on ECMAScript 5.1. However, you can use modern JavaScript features by switching to the GraalVM JavaScript engine. +The default JavaScript engine is GraalVM, which is based on ECMAScript 2022 (more formally, [ECMA-262, 13th edition](https://262.ecma-international.org/13.0/)). This means you can use modern JavaScript features from ECMAScript 2022 in your scripts. ### Features @@ -12,36 +12,7 @@ GraalVM enables you to use modern JavaScript features such as: - Destructuring - Classes -To use the GraalVM JavaScript engine, you need to be running Imposter v3.35.0 or later, and install the `js-graal` plugin. - -## Install plugin - -### Option 1: Using the CLI - -> **Note** -> This option requires the [Imposter CLI](./run_imposter_cli.md) version 0.37.0 or later. - -To use this plugin, install it with the Imposter CLI: - - imposter plugin install -d js-graal:zip - -This will install the plugin version matching the current engine version used by the CLI. The next time you run `imposter up`, the plugin will be available. - -### Option 2: Install the plugin manually - -To use this plugin, download the `imposter-plugin-js-graal.zip` ZIP file from the [Releases page](https://github.com/outofcoffee/imposter/releases). - -Enable it with the following environment variable: - - IMPOSTER_PLUGIN_DIR="/path/to/dir/containing/plugin" - -## Using the plugin - -To use GraalVM, you need to specify the `js-graal` engine as the JavaScript plugin. You can do this by setting the environment variable `IMPOSTER_JS_PLUGIN` to `js-graal`: - -```bash -export IMPOSTER_JS_PLUGIN=js-graal -``` +To use the GraalVM JavaScript engine, you need to be running Imposter v4.0.0 or later. --- @@ -49,15 +20,12 @@ export IMPOSTER_JS_PLUGIN=js-graal For examples, see the `examples/graal` directory [in GitHub](https://github.com/outofcoffee/imposter/blob/main/examples/graal). -> **Note** -> Complete the prerequisites first. - ### Simple example -Start the mock server with the `js-graal` engine: +Start the mock server: ```bash -imposter up examples/graal/simple -e IMPOSTER_JS_PLUGIN=js-graal +imposter up examples/graal/simple ``` Send a request to the mock server: @@ -71,3 +39,9 @@ Hello Ada ### Advanced example See the `examples/graal/es6` [directory](https://github.com/outofcoffee/imposter/blob/main/examples/graal) for an example of using modern JavaScript features in a script. + +--- + +## Further reading + +- [Using legacy JavaScript engine (Nashorn)](scripting_legacy_js.md) diff --git a/mkdocs.yml b/mkdocs.yml index 755a36104..d9c9023a1 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -42,6 +42,7 @@ nav: - Generating fake data: 'fake_data.md' - CORS: 'cors.md' - Groovy scripting tips: 'groovy_tips.md' + - JavaScript compatibility: 'scripting_modern_js.md' - Examples: 'https://github.com/outofcoffee/imposter/tree/main/examples' - Data capture and storage: