zerojs

ZeroJS is a JavaScript interpreter for the Zero engine, written in Luau. It parses and executes ES2017-practical JavaScript entirely inside the Luau VM — no native code, no WebAssembly, no external dependency — and marshals values back to Luau transparently.

Importing

local zerojs = require("~zerojs.api")

~zerojs is this package's alias, registered from the name in its package.yaml wherever the package sits. The same spelling therefore works from the world that authors the package and from a world that installed it, at any depth. Every module is reachable the same way — ~zerojs.parser, ~zerojs.stdlib.promise — and the package's own modules reference each other with those ids.

API surface

Module-level

VM instance

RunHandle (returned by vm:runAsync)

A runAsync stays pending while the loop has work: an armed setInterval keeps it pending exactly as an un-unref'd handle keeps Node alive — clear the interval or bound the run with timeoutMs.

Marshaling

Luau values passed to opts.env or vm:set are converted to JS values. JS values returned from run/eval are converted back to Luau: numbers, strings, and booleans are transparent; arrays become 1-based Luau tables; objects become string-keyed Luau tables; JS functions become callable Luau closures; undefined becomes nil; null becomes zerojs.null.

Step-budget sandbox

Each VM runs with a default execution budget of 1,000,000 interpreter steps. A script that exceeds the budget raises a JS RangeError: step budget exceeded, which surfaces as a Luau error. The budget resets on each run/eval call.

Language scope

• Variable declarations: var (function-scoped hoisting), let and const with full TDZ enforcement
• Functions: declarations, expressions, arrow functions, closures, rest parameters, default parameters
• Classes: declarations and expressions, inheritance via extends, super() in constructors and methods, getter and setter accessors, instance fields, static fields and methods, computed method keys, named class expressions, TDZ before declaration
• Destructuring: object and array patterns in declarations, assignment, and function parameters; nested patterns; rename, default, rest; computed keys in object patterns; elision in array patterns
• Spread: array literals, call arguments, new arguments, object literals
• Template literals (untagged)
• Optional chaining: a?.b, a?.[k], f?.(x). A null or undefined base ends the whole chain with undefined and skips every later link and argument; parentheses end the chain; the chain is not an assignment, update or new target
• Nullish coalescing ?? and the logical assignments ??=, ||= and &&=, which evaluate the right side and write only when the current value calls for it. ?? does not mix with || or && without parentheses
• Full coercion and equality semantics: ==/!= abstract equality, ===/!== strict equality, typeof, instanceof
• try/catch/finally, throw
• All loop forms: for, while, do-while, for-in, for-of; switch with fallthrough
• async/await — real event-loop semantics: an async function returns a promise, runs synchronously up to the first await, and resumes from a microtask when its awaited operand settles
• Property enumerability: for-in yields only own enumerable keys; object rest excludes prototype methods

Asynchrony and the event loop

• Promise with the full ES surface: then/catch/finally, resolve/reject, and the combinators all, allSettled, race, and any (with AggregateError when every input to any rejects)
• queueMicrotask for scheduling a microtask directly
• Timers: setTimeout/clearTimeout and setInterval/clearInterval, with extra arguments forwarded to the callback
• vm:runAsync(src, opts?) drives a script's timers, microtasks, and promise settlements across engine frames and returns a RunHandle (see the VM table above)
• A long synchronous loop under runAsync yields at each step-budget boundary and resumes on a later frame instead of raising RangeError; the same script under vm:run still raises

Standard library

• Object: callable coercion plus keys, values, entries, assign, freeze, isFrozen, create, getPrototypeOf, defineProperty, fromEntries, hasOwn, and the Object.prototype methods (hasOwnProperty, toString, isPrototypeOf)
• Function.prototype: call, apply, bind
• Global conversions and predicates: parseInt, parseFloat, isNaN, isFinite, String, Number, Boolean
• Array and Array.prototype: construction, isArray, from, of, and the iteration/mutation/query methods (map, filter, reduce, forEach, find, some, every, slice, splice, concat, join, indexOf, includes, sort, reverse, push, pop, shift, unshift, flat, fill, keys, values, entries)
• String.prototype: slice, substring, substr, split, indexOf, includes, startsWith, endsWith, repeat, padStart, padEnd, trim, trimStart, trimEnd, toUpperCase, toLowerCase, charAt, charCodeAt, codePointAt, at, concat, replace, replaceAll, match, matchAll, search
• Number: isInteger, isSafeInteger, isFinite, isNaN, parseFloat, parseInt, MAX_SAFE_INTEGER, MIN_SAFE_INTEGER, MAX_VALUE, MIN_VALUE, EPSILON, POSITIVE_INFINITY, NEGATIVE_INFINITY, NaN, and Number.prototype (toFixed, toString, toPrecision)
• Math: the constants and functions (abs, floor, ceil, round, trunc, sign, min, max, pow, sqrt, cbrt, hypot, exp, log, log2, log10, the trig family, random)
• Date: construction as new Date() (now) and new Date(ms) (epoch milliseconds), now (the wall clock at the moment of the call, never ahead of it and never moving backwards; whole-second readings of the wall clock bound it until a reading crosses a second boundary), getTime, getFullYear, getMonth, getDate, getHours, getMinutes, getSeconds, getMilliseconds, getDay, toISOString, toJSON
• JSON: parse and stringify (indent argument and array replacer whitelist)
• Map and Set: construction from iterables, get/set/has/delete/clear, add, size, forEach, keys, values, entries, insertion-order iteration
• RegExp: literals and the constructor, test, exec, lastIndex, source, flags, global, ignoreCase, multiline, dotAll, and the String regex methods above
• Errors: Error, TypeError, RangeError, ReferenceError, SyntaxError constructors and inheritance; Error.prototype.name, message and toString, so String(e), ${e} and "" + e read <name>: <message>
• console: log, info, debug, warn, error, dir and assert. Values print the way a JavaScript console prints them: strings bare at the top and quoted inside, { a: 1, b: [ 1, 2 ] }, Map(1) { 'a' => 1 }, [Function: f], errors as Error: message, nested values below depth 2 as [Object] and [Array], arrays and collections cut after 100 entries, a self-containing value as <ref *1> { self: [Circular *1] }, and a rendering wider than 80 characters across lines. A leading %s, %d, %i, %f, %j, %o, %O, %c or %% formats the arguments after it
• performance.now() (milliseconds on a monotonic clock since the VM was created) and performance.timeOrigin
• globalThis, NaN, Infinity

Out of scope by design

• Generators and iterators (function*, yield)
• Proxy and Reflect
• Labeled statements and with
• Tagged template literals

The full divergence list — where ZeroJS behavior differs from a browser engine — lives in the guide's divergence section.

Test suites

Eleven suites ship with the package, in its tests/ folder, run via tools.tests.run:

tools.tests.run({ suite = "zerojs_lexer" })        -- tokenization
tools.tests.run({ suite = "zerojs_parser" })       -- AST construction and error recovery
tools.tests.run({ suite = "zerojs_semantics" })    -- runtime semantics end-to-end
tools.tests.run({ suite = "zerojs_language" })     -- ?., ??, logical assignment, error text, console, Date.now, performance.now
tools.tests.run({ suite = "zerojs_stdlib" })       -- the standard-library surface
tools.tests.run({ suite = "zerojs_typed_arrays" }) -- typed arrays, ArrayBuffer, DataView
tools.tests.run({ suite = "zerojs_regex" })        -- the regex engine and RegExp methods
tools.tests.run({ suite = "zerojs_async" })        -- the event loop, promises, and timers
tools.tests.run({ suite = "zerojs_modules" })      -- the module graph
tools.tests.run({ suite = "zerojs_assettype" })    -- the zJs asset type
tools.tests.run({ suite = "zerojs_smoke" })        -- unmodified real-world JS programs