@ball-lang/engine 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+# MIT License
+
+Copyright (c) 2026 Ball Language Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,113 @@
+[![npm version](https://img.shields.io/npm/v/@ball-lang/engine.svg)](https://www.npmjs.com/package/@ball-lang/engine)
+
+# @ball-lang/engine
+
+Tree-walking interpreter for the [Ball programming language](https://github.com/ball-lang/ball). Runs Ball programs directly from their proto3 JSON representation in Node.js and browsers -- no protobuf dependency required.
+
+## Install
+
+```bash
+npm install @ball-lang/engine
+```
+
+## Quick start
+
+```ts
+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!' } },
+                    },
+                  ],
+                },
+              },
+            },
+          },
+        },
+      ],
+    },
+  ],
+};
+
+const engine = new BallEngine(program);
+engine.run();
+console.log(engine.getOutput()); // ["Hello, World!"]
+```
+
+You can also pass a JSON string instead of an object:
+
+```ts
+import { readFileSync } from 'node:fs';
+
+const json = readFileSync('my_program.ball.json', 'utf-8');
+const engine = new BallEngine(json);
+engine.run();
+```
+
+## 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. |
+
+### `engine.run(): string[]`
+
+Executes the program starting from the entry function. Returns 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 Ball `std` module (~70 functions) covering arithmetic, comparison, logic, bitwise ops, string manipulation, math, control flow (`if`, `for`, `while`, `for_in`, `switch`, `try`), collections, and I/O. See the [Ball repository](https://github.com/ball-lang/ball) for the full specification.
+
+## Usage without a build step
+
+If you are using Node.js >= 22.6.0, you can import the TypeScript source directly:
+
+```bash
+node --experimental-strip-types your_script.ts
+```
+
+```ts
+import { BallEngine } from '@ball-lang/engine/src/index.ts';
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,132 @@
+/**
+ * Ball TypeScript Engine — interprets Ball programs directly from JSON.
+ *
+ * Runs in Node.js and browsers. No protobuf dependency — works with
+ * proto3 JSON representation of Ball programs.
+ *
+ * Usage:
+ *   import { BallEngine } from '@ball-lang/engine';
+ *   const engine = new BallEngine(programJson, { stdout: console.log });
+ *   engine.run();
+ */
+interface Program {
+    name?: string;
+    version?: string;
+    modules: Module[];
+    entryModule: string;
+    entryFunction: string;
+}
+interface Module {
+    name: string;
+    functions: FunctionDef[];
+    moduleImports?: ModuleImport[];
+}
+interface ModuleImport {
+    name: string;
+}
+interface FunctionDef {
+    name: string;
+    isBase?: boolean;
+    body?: Expression;
+    outputType?: string;
+    metadata?: Record<string, any>;
+}
+interface Expression {
+    call?: FunctionCall;
+    literal?: Literal;
+    reference?: {
+        name: string;
+    };
+    fieldAccess?: {
+        object: Expression;
+        field: string;
+    };
+    messageCreation?: {
+        fields: FieldValuePair[];
+    };
+    block?: Block;
+    lambda?: Lambda;
+}
+interface FunctionCall {
+    module?: string;
+    function: string;
+    input?: Expression;
+}
+interface Literal {
+    intValue?: string | number;
+    doubleValue?: number;
+    stringValue?: string;
+    boolValue?: boolean;
+    listValue?: {
+        elements: Expression[];
+    };
+}
+interface FieldValuePair {
+    name: string;
+    value: Expression;
+}
+interface Block {
+    statements: Statement[];
+    result?: Expression;
+}
+interface Statement {
+    let?: {
+        name: string;
+        value: Expression;
+        metadata?: Record<string, any>;
+    };
+    expression?: Expression;
+}
+interface Lambda {
+    body: Expression;
+    metadata?: Record<string, any>;
+}
+export interface BallEngineOptions {
+    stdout?: (msg: string) => void;
+    stderr?: (msg: string) => void;
+}
+export declare class BallEngine {
+    private program;
+    private stdout;
+    private stderr;
+    private functions;
+    private currentModule;
+    private activeException;
+    private output;
+    constructor(program: Program | string, options?: BallEngineOptions);
+    private buildLookupTables;
+    run(): string[];
+    getOutput(): string[];
+    private evalExpr;
+    private evalCall;
+    private callFunction;
+    private evalLiteral;
+    private evalReference;
+    private evalFieldAccess;
+    private evalMessageCreation;
+    private evalBlock;
+    private evalLambda;
+    private lazyFields;
+    private lazyStringField;
+    private evalLazyIf;
+    private evalLazyWhile;
+    private evalLazyDoWhile;
+    private evalLazyFor;
+    private evalLazyForIn;
+    private evalLazySwitch;
+    private evalLazyTry;
+    private evalShortCircuitAnd;
+    private evalShortCircuitOr;
+    private evalReturn;
+    private evalAssign;
+    private applyCompoundOp;
+    private evalIncDec;
+    private evalLabeled;
+    private callBaseFunction;
+    private toBool;
+    private toNum;
+    private numOp;
+    private ballToString;
+}
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}