ES4X Documentation

ES4X is a lightweight runtime designed for ECMAScript >= 5 applications. It runs on GraalJS using Vert.x as the underlying engine.

Key characteristics:

• No Node.js dependency: Unlike many JavaScript environments, ES4X does not use Node.js.
• Polyglot capabilities: Because it uses GraalVM (a polyglot runtime on the JVM), you can use any JVM language alongside JavaScript within your applications.
• High Performance: ES4X utilizes Vert.x to provide an optimized event loop and high-performance IO library. It has demonstrated industry-leading performance in TechEmpower Frameworks benchmarks.

When working with asynchronous code in ES4X, it is important to distinguish between Vert.x types and standard JavaScript concepts:

• Vert.x Future: Acts like a JavaScript Thenable (a Promise-like object). It represents the read-only side of an asynchronous operation.
• Vert.x Promise: Acts like a JavaScript Executor Function. It is the writable side used to complete or fail a Future.

es4x utilizes Vert.x code generation, an annotation processing tool that extracts metadata from Java source code. This process allows es4x to generate a complete JavaScript/TypeScript module from annotated Java interfaces.

A successful generation produces the following files:

• package.json: Module descriptor with Java artifact and JS dependency references.
• README.md: Basic documentation.
• index.js / index.mjs: CommonJS and ES6 module scripts exporting annotated Java interfaces.
• index.d.ts: TypeScript definitions for annotated Java interfaces.
• options.js / options.mjs / options.d.ts: CommonJS, ES6, and TypeScript files for annotated Java data objects.
• enums.js / enums.mjs / enums.d.ts: CommonJS, ES6, and TypeScript files for annotated Java enums.
• mod.js: A single ES6 module that re-exports index.mjs, options.mjs, and enums.mjs.

ES4X supports ECMAScript Modules (ESM) via .mjs files. When using .mjs, ES4X uses the GraalJS native module loader instead of CommonJS require(), allowing both import and export to work according to ES6 specifications.

To enable this:

1. Use the .mjs file extension.
2. Or, start the application with the -Desm flag.

Warning: Do not mix CommonJS and ESM in the same project.

# Example of starting with the ESM flag
$ es4x -Desm my-app.mjs

When using ESM in ES4X, the import statements do not require file extensions. The ES4X loader resolves module paths using the following lookup order:

1. The exact file name (e.g., ./routes)
2. The file name with a .mjs suffix (e.g., ./routes.mjs)
3. The file name with a .js suffix (e.g., `./routes.js")

ES4X enhances Vert.x Future objects by making them Thenable. This allows you to use standard JavaScript async/await syntax with any API that returns a Vert.x Future, without requiring a compilation step from GraalVM.

When using await on a Vert.x Future, successful completions resolve the value, while failures throw an error that can be caught using a standard try/catch block.

try {
  let server = await vertx
    .createHttpServer()
    .listen(0);

  console.log('Server Ready!');
} catch (err) {
  console.log('Server startup failed!');
}

ES4X supports .mjs files, which use GraalJS's native module loader instead of commonjs require(). In .mjs files, both import and export work according to the ES6 spec.

To enable ESM support, you can either:

1. Use the .mjs file extension.
2. Add "type": "module" to your package.json.

Warning: You cannot mix commonjs and esm in the same project. If you are unsure, stick to commonjs.

ES4X projects are defined by a package.json file. Unlike standard Node.js environments that only use npm, an ES4X project fetches dependencies from two distinct sources:

1. npm: For standard JavaScript packages.
2. Maven Central: For Java/JVM dependencies.

Because it runs on GraalVM, you can integrate Java libraries directly into your JavaScript application logic.

GraalJS is strict about single-threaded execution within a single JS context. Accessing the same script environment from multiple threads is not permitted.

• If you are using asynchronous Vert.x APIs, this is typically not an issue.
• If you need to work with multiple threads, do not attempt to share the same script environment. Instead, use the Worker API or the EventBus.