Using JavaScript libraries

Gallium Data runs in the GraalVM virtual machine, which includes a JavaScript engine that is fully ECMA 2020 compliant.

This includes compatibility with many, but not all, Node.js libraries. Those that are not supported are the ones that use Node's built-in modules such as fs, process, events or http.

For more information, see the GraalVM docs.

For information about the various settings governing JavaScript libraries, see the configuration documentation (in brief: you can use your own NPM repository).

JavaScript libraries can be added to the repository in three ways:

  • by using the GUI

  • by editing the repository.json file

  • by creating your own Docker image

Using the GUI

You can add a JavaScript library to a repository using the GUI:


Click on a SEE VERSIONS button to see all the available versions for that library, and add a specific version to the repository by clicking an ADD TO THIS REPOSITORY button.

Any libraries added with the GUI will be become available to your code as soon as you publish the repository. In some cases, the publishing may take a few seconds if you add a lot of libraries, or if they take a while to download from the registry.

Editing repository.json

You can also add a JavaScript library to a repository by editing that repository's repository.json file:

{
"RepositoryVersion": "1.0",
"SystemSettings": {},

"libraries": [

{

"version": "4.8.2",

"type": "javascript",

"orgId": "npm",

"artifactId": "lodash"

}

],

etc...

This will take effect as soon as you restart Gallium Data.

Creating your own Docker image

You can create your own Docker image on top of the standard Gallium Data image and add JavaScript libraries to it. This is slightly more efficient the first time Gallium Data starts, since it doesn't have to download and install the libraries. The NPM directory in the standard Docker image is /galliumdata/node_modules, so any modules added to that directory will be available to your logic. You can still add additional modules using the GUI after that.

Using a library in filter code

Once a JavaScript library has been installed and published, you can use it in your code using the require syntax, e.g.:

let _ = require('lodash');

log.debug('Reversed with lodash: ' + _.reverse([1,2,3,4]));

Some JavaScript library may cause a slight delay (like a second or two) the first time they are used because the JavaScript engine has to load and compile them. This only happens when Gallium Data starts up.

JavaScript libraries that have been tested

The GraalVM JavaScript engine does not support modules that use Node's built-in modules such as fs, events or http, at least not if they have not been substituted. Libraries that do not rely on built-in modules usually run fine.

The following libraries have been found to run out of the box, but many more should also be fine: