@foxystar/molang 0.1.0

package/README.md

@@ -0,0 +1,82 @@
+## `@foxystar/molang`
+A fast, extensible, and safe implementation of the [Molang](https://learn.microsoft.com/en-us/minecraft/creator/documents/molang/introduction) expression language.
+
+## Installation
+```bash
+npm install @foxystar/molang
+```
+
+## Overview
+`@foxystar/molang` is a full Molang interpreter written in TypeScript, designed for:
+- Minecraft: Bedrock Edition's Scripting API
+- Expression evaluation for custom components, systems, and tooling
+
+It includes a parser, runtime, context system, and error handling, all built with strong typing and extensibility in mind.
+
+## Features
+- Full Molang parser (AST-based)
+- Runtime interpreter with control flow support
+- Context system with inheritance and scoping
+- Safe evaluation (restricted mutation rules)
+- Helpful error messages with suggestions
+- Easily extensible (custom queries, variables, functions)
+- Built-in math + random utilities
+
+## Quick Example
+
+```ts
+import * as Molang from "@foxystar/molang";
+
+const result = Molang.evaluate("1 + 2 * 3");
+console.log(result); // 7
+```
+
+### Using Context
+```ts
+import * as Molang from "@foxystar/molang";
+
+const context = Molang.createMolangContext({
+    variable: {
+        health: 10,
+    }
+});
+
+Molang.evaluate("v.health + 5", context); // 15
+```
+
+### Custom functions
+```ts
+import * as Molang from "@foxystar/molang";
+
+const context = Molang.createMolangContext({
+    query: {
+        double: (x: number) => x * 2,
+    }
+});
+
+Molang.evaluate("q.double(5)", context); // 10
+```
+
+---
+
+> [!NOTE]
+> - Only `variable` and `temp` namespaces can be mutated
+> - Prevents accidental writes to unsafe scopes
+> - Strict mode available for additional validation
+
+## Error Handling
+Errors are descriptive and include helpful context:
+
+```ts
+Molang.evaluate("q.doubl(5)");
+```
+
+```
+Cannot call 'q.doubl' because it is undefined. Did you mean 'query.double'?
+```
+
+## Design Goals
+- Predictable and safe runtime behavior
+- Clear and actionable error messages
+- Minimal overhead with good performance
+- Easy integration into existing systems

package/esm/LRUCache.d.ts

@@ -0,0 +1,6 @@
+export default class LRUCache<K, V> extends Map<K, V> {
+    private maxSize;
+    constructor(maxSize: number);
+    get(key: K): V | undefined;
+    set(key: K, value: V): this;
+}

package/esm/LRUCache.js

@@ -0,0 +1,30 @@
+export default class LRUCache extends Map {
+    constructor(maxSize) {
+        super();
+        Object.defineProperty(this, "maxSize", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: maxSize
+        });
+    }
+    get(key) {
+        const value = super.get(key);
+        if (value !== undefined) {
+            super.delete(key);
+            super.set(key, value);
+        }
+        return value;
+    }
+    set(key, value) {
+        if (this.has(key)) {
+            super.delete(key);
+        }
+        super.set(key, value);
+        if (this.size > this.maxSize) {
+            const firstKey = this.keys().next().value;
+            super.delete(firstKey);
+        }
+        return this;
+    }
+}

package/esm/diagnostics/error.d.ts

@@ -0,0 +1,12 @@
+import { ExprBase } from "../parser/expression.js";
+declare class MolangError extends Error {
+    constructor(message: string, start: number, end: number, source: string);
+    private static formatError;
+}
+export declare class MolangParseError extends MolangError {
+    constructor(message: string, position: number, source: string);
+}
+export declare class MolangRuntimeError extends MolangError {
+    constructor(message: string, expr: ExprBase, source: string);
+}
+export {};

package/esm/diagnostics/error.js

@@ -0,0 +1,37 @@
+class MolangError extends Error {
+    constructor(message, start, end, source) {
+        super(MolangError.formatError(message, start, end, source));
+        this.name = this.constructor.name;
+    }
+    static formatError(message, pos, end, src) {
+        let line = 1;
+        let lastLineStart = 0;
+        for (let i = 0; i < pos; i++) {
+            if (src[i] === "\n") {
+                line++;
+                lastLineStart = i + 1;
+            }
+        }
+        const column = pos - lastLineStart + 1;
+        const lines = src.split("\n");
+        const lineText = lines[line - 1] ?? "";
+        //const pointer = " ".repeat(column - 1) + "^";
+        const span = Math.max(1, end - pos);
+        const underlineLength = Math.min(span, Math.max(1, lineText.length - column + 1));
+        const pointer = " ".repeat(column - 1) +
+            "^".repeat(underlineLength);
+        return (`${message} at line ${line - 1}, column ${column}\n` +
+            `${lineText}\n` +
+            `${pointer}`);
+    }
+}
+export class MolangParseError extends MolangError {
+    constructor(message, position, source) {
+        super(message, position, position + 1, source);
+    }
+}
+export class MolangRuntimeError extends MolangError {
+    constructor(message, expr, source) {
+        super(message, expr.start, expr.end, source);
+    }
+}

package/esm/diagnostics/suggestions.d.ts

@@ -0,0 +1,2 @@
+export declare function levenshtein(a: string, b: string): number;
+export declare function findBestMatch(name: string, candidates: string[]): string | null;

package/esm/diagnostics/suggestions.js

@@ -0,0 +1,35 @@
+export function levenshtein(a, b) {
+    const dp = Array.from({ length: a.length + 1 }, () => new Array(b.length + 1).fill(0));
+    for (let i = 0; i <= a.length; i++) {
+        dp[i][0] = i;
+    }
+    for (let j = 0; j <= b.length; j++) {
+        dp[0][j] = j;
+    }
+    for (let i = 1; i <= a.length; i++) {
+        for (let j = 1; j <= b.length; j++) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            dp[i][j] = Math.min(dp[i - 1][j] + 1, // deletion
+            dp[i][j - 1] + 1, // insertion
+            dp[i - 1][j - 1] + cost // substitution
+            );
+        }
+    }
+    return dp[a.length][b.length];
+}
+export function findBestMatch(name, candidates) {
+    let best = null;
+    let bestScore = Infinity;
+    for (const c of candidates) {
+        const d = levenshtein(name.toLowerCase(), c.toLowerCase());
+        if (d < bestScore) {
+            bestScore = d;
+            best = c;
+        }
+    }
+    // Heuristic: only suggest if it's "close enough"
+    if (best !== null && bestScore <= 2) {
+        return best;
+    }
+    return null;
+}

package/esm/index.d.ts

@@ -0,0 +1,8 @@
+export { evaluate } from "./molang.js";
+export { MolangParser } from "./parser/parser.js";
+export type { Expr, ExprBase, Program, Statement, Token, TokenType } from "./parser/expression.js";
+export * from "./runtime/context.js";
+export { MolangMath } from "./runtime/math.js";
+export { MolangRuntime } from "./runtime/runtime.js";
+export type { MolangOptions } from "./runtime/runtime.js";
+export * from "./diagnostics/error.js";

package/esm/index.js

@@ -0,0 +1,6 @@
+export { evaluate } from "./molang.js";
+export { MolangParser } from "./parser/parser.js";
+export * from "./runtime/context.js";
+export { MolangMath } from "./runtime/math.js";
+export { MolangRuntime } from "./runtime/runtime.js";
+export * from "./diagnostics/error.js";

package/esm/molang.d.ts

@@ -0,0 +1,2 @@
+import { MolangContext } from "./runtime/context.js";
+export declare function evaluate(input: string, context?: MolangContext): unknown;

package/esm/molang.js

@@ -0,0 +1,22 @@
+import { MolangParser } from "./parser/parser.js";
+import { MolangRuntime } from "./runtime/runtime.js";
+import { DEFAULT_CONTEXT, mergeContext } from "./runtime/context.js";
+import LRUCache from "./LRUCache.js";
+const MAX_CACHE_SIZE = 2048;
+const cache = new LRUCache(MAX_CACHE_SIZE);
+export function evaluate(input, context = {}) {
+    if (context === DEFAULT_CONTEXT) {
+        context = mergeContext(DEFAULT_CONTEXT, {});
+    }
+    else if (!Object.prototype.isPrototypeOf.call(DEFAULT_CONTEXT, context)) {
+        Object.setPrototypeOf(context, DEFAULT_CONTEXT);
+    }
+    let program = cache.get(input);
+    if (!program) {
+        const parser = new MolangParser(input);
+        program = parser.parseProgram();
+        cache.set(input, program);
+    }
+    const runtime = new MolangRuntime(context, input, { strict: false });
+    return runtime.evaluateProgram(program);
+}

package/esm/package.json

@@ -0,0 +1,3 @@
+{
+  "type": "module"
+}

package/esm/parser/expression.d.ts

@@ -0,0 +1,87 @@
+export declare const TOKEN_REGEX: RegExp;
+export type ExprBase = {
+    start: number;
+    end: number;
+};
+export type Expr = ({
+    type: "Literal";
+    value: unknown;
+} & ExprBase) | ({
+    type: "Identifier";
+    name: string;
+    path: string[];
+} & ExprBase) | ({
+    type: "BinaryExpression";
+    operator: string;
+    left: Expr;
+    right: Expr;
+} & ExprBase) | ({
+    type: "CallExpression";
+    callee: Expr;
+    arguments: Expr[];
+} & ExprBase) | ({
+    type: "UnaryExpression";
+    operator: string;
+    expression: Expr;
+} & ExprBase) | ({
+    type: "ArrayLiteral";
+    elements: Expr[];
+} & ExprBase) | ({
+    type: "IndexExpression";
+    array: Expr;
+    index: Expr;
+} & ExprBase) | ({
+    type: "ArrowExpression";
+    left: Expr;
+    right: Expr;
+} & ExprBase) | ({
+    type: "ConditionalExpression";
+    condition: Expr;
+    then: Expr;
+    else?: Expr;
+} & ExprBase);
+export type Statement = ({
+    type: "ExprStatement";
+    expr: Expr;
+} & ExprBase) | ({
+    type: "AssignStatement";
+    target: Expr;
+    value: Expr;
+} & ExprBase) | ({
+    type: "ReturnStatement";
+    value?: Expr;
+} & ExprBase) | ({
+    type: "BreakStatement";
+} & ExprBase) | ({
+    type: "ContinueStatement";
+} & ExprBase) | ({
+    type: "LoopStatement";
+    count: Expr;
+    body: Statement;
+} & ExprBase) | ({
+    type: "ForEachStatement";
+    iterator: Expr;
+    iterable: Expr;
+    body: Statement;
+} & ExprBase) | ({
+    type: "ConditionalStatement";
+    condition: Expr;
+    then: Statement;
+    else?: Statement;
+} & ExprBase) | ({
+    type: "BlockStatement";
+    body: Statement[];
+} & ExprBase);
+export type Program = {
+    type: "Program";
+    body: Statement[];
+    start: number;
+    end: number;
+};
+export type TokenType = "number" | "string" | "identifier" | "assignment" | "operator" | "parenthesis" | "brace" | "comma" | "bracket" | "semicolon" | "eof";
+export type Token = {
+    type: TokenType;
+    value: string;
+    start: number;
+    end: number;
+};

package/esm/parser/expression.js

@@ -0,0 +1,19 @@
+export const TOKEN_REGEX = new RegExp([
+    // number
+    "^(?<number>-?\\d+(?:\\.\\d+)?)",
+    // string (double OR single quotes)
+    "(?<string>\"[^\"]*\"|'[^']*')",
+    // identifier + dotted path
+    "(?<identifier>[a-zA-Z_][a-zA-Z0-9_]*(?:\\.[a-zA-Z_][a-zA-Z0-9_]*)*)",
+    "(?<assignment>=(?!=))",
+    "(?<operator>\\?\\?|->|>>>|>>|<<|\\|\\||&&|==|!=|<=|>=|\\^|\\||&|\\?|:|[+\\-*/<>!])",
+    // grouping
+    "(?<parenthesis>[()])",
+    "(?<bracket>[\\[\\]])",
+    "(?<brace>[{}])",
+    // punctuation
+    "(?<comma>,)",
+    "(?<semicolon>;)",
+    // whitespace
+    "(?<whitespace>\\s+)"
+].join("|^"));

package/esm/parser/parser.d.ts

@@ -0,0 +1,20 @@
+import { Program } from "./expression.js";
+export declare class MolangParser {
+    private input;
+    private tokens;
+    private position;
+    constructor(input: string);
+    private tokenize;
+    private peek;
+    private consume;
+    parseProgram(): Program;
+    private parseStatement;
+    private parseExpression;
+    private parseBinaryExpression;
+    private tryFold;
+    private getOperatorPrecedence;
+    private parseConditionalExpression;
+    private parsePrimaryExpression;
+    private parseUnary;
+    private parseAtom;
+}