API V3

API V3 consist of JavaScript functions and objects bundled in ECMAScript Modules (ES Modules).

API V3 can only be used with the Graal.JS scripting engine. It can’t be used with other scripting engines, neither with the Nashorn nor with the Rhino engine.

API V3 replaces API V2 which was based on CommonJS module.

The scripting context

The scripting context is populated with the following objects:

  • require()

    require() is a global function to load CommonJS Modules. You can use require() to load custom CommonJS-modules. However, API V3 is implemented as ES Modules. Its modules are loaded with ECMAScript import-statements.

In contrast to the API V1 there is no global josm object in the context. You have to explicitly load it as an ES Module:

// import josm from an ES Module
import josm from 'josm'

JavaScript version

Graal.JS supports the latest JavaScript version, ECMAScript 2015, and later.

For instance, the following JavaScript features are now supported:

// import of ES Modules and object destructuring; trailing semicolons not necessary
// anymore
import { Api } from 'josm/api'

// let assignment
let counter = 0
// constants
const value = "foo"

We recommend to use the JavaScript Standard Style. The API V3, for instance,

  • uses 2 spaces for indentation
  • uses single quotes for strings
  • doesn’t use semicolons