@ball-lang/engine

Tree-walking interpreter for the Ball programming language. Runs Ball programs directly from their proto3 JSON representation in Node.js and browsers -- no protobuf dependency required.

Install

npm install @ball-lang/engine

Quick start

import { BallEngine } from '@ball-lang/engine';

// A minimal Ball program that prints "Hello, World!"
const program = {
  name: 'hello',
  version: '1.0.0',
  entryModule: 'main',
  entryFunction: 'main',
  modules: [
    {
      name: 'std',
      functions: [
        { name: 'print', isBase: true },
        { name: 'add', isBase: true },
      ],
    },
    {
      name: 'main',
      moduleImports: [{ name: 'std' }],
      functions: [
        {
          name: 'main',
          body: {
            call: {
              module: 'std',
              function: 'print',
              input: {
                messageCreation: {
                  fields: [
                    {
                      name: 'value',
                      value: { literal: { stringValue: 'Hello, World!' } },
                    },
                  ],
                },
              },
            },
          },
        },
      ],
    },
  ],
};

// `run()` is async — `await` it (inside an async function, or at the
// top level of an ESM module / `--experimental-strip-types` script).
const engine = new BallEngine(program);
await engine.run();
console.log(engine.getOutput()); // ["Hello, World!"]

You can also pass a JSON string instead of an object:

import { readFileSync } from 'node:fs';

const json = readFileSync('my_program.ball.json', 'utf-8');
const engine = new BallEngine(json);
await engine.run();
console.log(engine.getOutput());

API reference

new BallEngine(program, options?)

Creates an engine instance.

| Parameter | Type | Description | |-----------|------|-------------| | program | object \| string | A Ball program object or its JSON string representation. | | options.stdout | (msg: string) => void | Callback for std.print output. Defaults to collecting into an internal array. | | options.stderr | (msg: string) => void | Callback for error output. Defaults to no-op. | | options.sandbox | boolean | Run in sandbox mode (blocks file I/O, env access, etc.). Default false. | | options.timeoutMs | number \| null | Maximum execution time in milliseconds (null = unbounded). Default null. | | options.maxMemoryBytes | number \| null | Maximum memory usage in bytes (null = unbounded). Default null. | | options.maxRecursionDepth | number | Maximum recursion depth. Default 100000. | | options.maxExpressionDepth | number | Maximum expression nesting depth. Default 1000000. | | options.maxModules | number | Maximum number of modules allowed in the program. Default 1000000. | | options.maxProgramSizeBytes | number \| null | Maximum program JSON size in bytes (null = skip check). Default null. |

See BallEngineOptions in src/index.ts for the authoritative list.

engine.run(): Promise<string[]>

Executes the program starting from the entry function. The compiled engine is async internally, so run() returns a Promise — always await it. Resolves to the collected stdout output array.

engine.getOutput(): string[]

Returns the stdout output collected so far (same array returned by run()).

Supported standard library functions

The engine implements the universal Ball std module (arithmetic, comparison, logic, bitwise ops, string manipulation, math, control flow — if, for, while, for_in, switch, try, etc.) plus the std_collections, std_io, and std_memory modules. The exact function set is whatever the self-hosted dart/self_host/engine.ball.json implements; see the Ball repository (CLAUDE.md → Standard library modules) for the authoritative list.

Usage without a build step

The published package's exports map exposes only the main entry (@ball-lang/engine → the prebuilt dist/index.js), so always import from the bare package specifier — subpath imports such as @ball-lang/engine/src/index.ts are blocked by Node's package encapsulation (ERR_PACKAGE_PATH_NOT_EXPORTED):

import { BallEngine } from '@ball-lang/engine';

If you are using Node.js >= 22.6.0, you can run a .ts consumer script directly with --experimental-strip-types; the import above still resolves to the prebuilt entry:

node --experimental-strip-types your_script.ts

To consume the raw TypeScript source instead, work from a checkout of the Ball repository and import ts/engine/src/index.ts by relative path.

License

MIT