Introduction

The Oracle® GraalVM JavaScript Runtime implements ECMAScript standards and does not include modules that are specific for Node.js such as http, fs etc., for details see https://www.graalvm.org/latest/reference-manual/js/Modules/

The Oracle® GraalVM allows to install 3rd-party packages that work as replacements for Node.js modules and as independent additions.

Use of Oracle® GraalVM for jobs is available starting from the following releases:

FEATURE AVAILABILITY STARTING FROM RELEASE 2.5.4

FEATURE AVAILABILITY STARTING FROM RELEASE 2.6.1

Installation

Users can install Node.js 3rd-party packages in any location, preferably in the default location in the Oracle® GraalVM's ./bin directory. During installation of packages the ./bin/node_modules sub-directory will be created. Consider use of a current version of the Oracle® GraalVM:

# set location of GraalVM
JAVA_HOME=/opt/java/graalvm-community-openjdk-17.0.7+7.1

# install Node.js packages in $JAVA_HOME/bin/node_modules sub-directory
$JAVA_HOME/bin/npm install url
$JAVA_HOME/bin/npm install Buffer

Note: Adding 3rd-party packages does not require restart of a JS7 Agent. Instead, the packages will be considered with the next execution of the job.

Configuration

By default JS7 configures the Oracle® GraalVM to allow 3rd-party packages to be imported using the require() function.

The default mechanism requires that 3rd-party packages are installed in the default location which is the Oracle® GraalVM's ./bin directory. 

• If this prerequisite is considered then no further configuration is required to run 3rd-party packages.
• If this prerequisite is not considered and users wish to use a different installation directory for 3rd-party packages then the below instructions apply.

Configuration of Oracle GraalVM

The following applies to users who wish to install 3rd-party packages in a location different from the default location or who want to specify settings for the Oracle® GraalVM.

• Users create a JS7 - Job Resource that holds the required settings and assign the Job Resource the job or workflow.
• Download sample Job Resource (upload .json): pdJavascript.graalvm.options.jobresource.json

In the Configuration->Inventory view navigate to the folder that should store the Job Resource.

• The Job Resource can be assigned an arbitrary name.
• The Job Resource holds a single argument with the name js7_options.graalvm.js (required):
• Users can click the icon in the input field for the argument value to open the editor:
  .

As a value to the Job Resource argument a number of options for Oracle® GraalVM can be added like this:

toFile('
{
    "options": {
        "js.commonjs-require": true,
        "js.commonjs-require-cwd": "/opt/java/graalvm-community-openjdk-17.0.7+7.1/bin/node_modules",
        "js.commonjs-core-modules-replacements": ""
     }
}','*.json')

Explanation:

• toFile: the JS7 toFile() function takes two arguments:
  • the string that holds the Oracle® GraalVM options in JSON format,
  • the file name extension *.json. A file with this extension will be created in the JS7 Agent's <data>/work directory and will be used when executing JavaScript jobs.
•  Options
  • js.commonjs-require: Is required to hold the value true in order to enable use of 3rd-party packages.
  • js.commonjs-require-cwd: Specifies the path to the node_modules directory that holds 3rd-party packages.
  • js.commonjs-core-modules-replacements: Optionally can be used to map built-in Node.js modules to 3rd-party packages. The syntax <node-built-in-module>:<3rd-party-package>[,<node-built-in-module>:<3rd-party-package>] can be used.
  • Users can add further options as suggested by Oracle® GraalVM.
  • For details see https://www.graalvm.org/latest/reference-manual/js/Modules/
• The built-in default does not require settings from a Job Resource.
  • The default settings include:
    
    • "js.commonjs-require": true
    • "js.commonjs-require-cwd:" "<JAVA_HOME>/bin/node_modules"
      • The directory for installation of 3rd-party packages is assumed in the ./bin sub-directory of the directory indicated from the value of the JAVA_HOME environment variable.
  • Consider that use of a Job Resource disables the built-in default.

Further Resources

• JS7 - Installing Oracle GraalVM