js2lua 🚀

A robust, enterprise-grade JavaScript-to-Lua AST compiler. Transpiles modern ECMAScript (ES6+) syntax directly into executable Lua code.

Features • How It Works • Installation • CLI Usage • API Reference • Running Tests • License

---

What is js2lua?

js2lua is a zero-dependency (excluding acorn) compiler designed to bridge JavaScript applications and Lua environments. It doesn't just match regexes; it parses JavaScript source code into a standardized ESTree AST (Abstract Syntax Tree) and compiles it block-by-block into syntactically valid and performant Lua code.

---

How It Works

The compilation pipeline translates JavaScript constructs by executing three main phases:

graph TD
    A[JS Source Code] -->|Acorn Parser| B[ESTree AST Representation]
    B -->|AST Compiler Walk| C[Lua Code Generator]
    C -->|Bundled Output| D[Target Lua Code]
    E[Lua OOP Metatable Runtime] -->|Prepended| D

Loading

1. Parsing: Uses the standard Acorn parser to generate a highly detailed ESTree compliance tree from input JavaScript code.
2. Translation: Recursively visits AST nodes to rewrite them into equivalent Lua syntax. It handles syntax adjustments such as loops, variables, try-catch scopes, and conditional expressions (e.g., using a safe Lua ternary pattern: ((cond) and {a} or {b})[1]).
3. Runtime Support: An embedded, optimized runtime is prepended to the compiled code, providing a metatable class prototype model and standard array helper methods (indexOf, slice, map, forEach, etc.).

---

Features

• Object-Oriented Programming: Full class emulation including constructors, class methods, inheritance (extends), and super constructor/method calling.
• Scope & Variables: Standard mapping of lexical blocks (let, const, var) to Lua's local variables.
• Control Flow Emulation: Includes loop wrappers using nested repeat ... until true constructs to support ES6 continue and break keywords.
• Array Methods Optimizations: Automatically inlines JS array methods (like push, pop, shift, unshift, join) to high-speed native Lua table operations.
• Import/Export Modules: Transpiles ES import and export modules directly into Lua table-scoped objects and require modules.
• Array Index Shifting: Optional support to shift 0-indexed JS arrays to Lua's conventional 1-indexed tables.

---

Installation

Clone the repository and install the dependencies:

git clone https://github.com/Grovvik/js2lua.git
cd js2lua
npm install

---

CLI Usage

Install the command line tool or execute it directly using Node:

node bin/cli.js <input-file.js> [options]

Options

• -o, --output <file>: Specify target output path (default outputs to stdout).
• --no-runtime: Exclude the embedded class metatable and array helpers runtime.
• --adjust-indices: Auto-adjusts zero-based array indexing to 1-based index access (adds +1).
• --safe-operators: Enables safe operator helpers for dynamic operations.
• -h, --help: Displays help information.

---

API Reference

Import js2lua into your Node.js application:

import { compile } from 'js2lua';

const jsCode = `
class Dog {
    constructor(name) {
        this.name = name;
    }
    bark() {
        console.log(this.name + " says Woof!");
    }
}
const myDog = new Dog("Buddy");
myDog.bark();
`;

// Compile JS to Lua
const luaCode = compile(jsCode, {
    addRuntime: true,
    adjustIndices: false,
    safeOperators: false
});

console.log(luaCode);

---

Running Tests

Execute the compiler test suite to verify the transpilation correctness of basic operations, control flow, functions, OOP classes, imports, exports, and destructuring:

npm run test

---

License

Distributed under the MIT License. See LICENSE for more information.