mevento 3.0.4 → 4.0.1

package/README.md

@@ -1,59 +1,220 @@
-# Mevento
+# MEvento TypeScript
 
-Mevento is a tiny VM one single file that handles `MEvento code` executions inside JS engine. `MEvento` is simple programming language that allows developers exposing an app host function, that way they have the ability to dynamically execute simple script that call host function.
+MEvento is a tiny single-file scripting VM for host applications. The host keeps
+control of native behavior by exposing functions, while scripts stored in a
+database or loaded at runtime can compose those functions without rebuilding the
+host app.
 
-The VM uses a AST Walker to execute MEvento script, so of course the performace is not its concern a lot.
+This module is the TypeScript implementation. It provides synchronous
+`MEvento` and async `MEventoAsync` runtimes.
 
-## MEvento code syntax
-Syntaxically MEvento is a c-like language, but very limited: no function declaration, no class, just assignation, function call and conditional check.
+## v2 Status
+
+v2 is a superset of v1 script syntax, with stricter diagnostics and new
+runtime helpers. Existing v1 scripts should still parse and execute in v2.
+
+By default, v2 is stricter: unknown host functions raise `unknown_function`
+instead of silently returning `null`. For existing database scripts that depend
+on the v1 behavior, run the VM with `{ compatV1: true }`. In that mode, missing
+host functions return `null` and instance validation does not report them as
+unknown. New scripts should prefer strict mode and wrap risky calls in `_try_`
+when a script should continue after failure.
+
+v2 additions include:
+
+- Dot property access: `user.name` is equivalent to `user['name']`.
+- `_try_` result capture and helper functions.
+- Function specs with arity, argument type hints, tags, return type hints, and
+  optional documentation metadata.
+- Script manifest validation for required host functions, inputs, and outputs.
+- Trace mode and execution step budgets.
+- v1 compatibility mode for existing scripts that call optional host functions.
+- Minimal collection built-ins for arrays and maps.
+
+## Script Syntax
+
+MEvento is intentionally small and C-like. It has no user-defined functions and
+no classes. The host application owns the real logic.
+
+Supported syntax includes assignments, expressions, host calls, object and
+array literals, bracket and dot access, `if`, `while`, numeric `for`,
+`for ... in`, `break`, `continue`, `return`, `??`, comments, and multilingual
+keyword dictionaries.
+
+Example:
 
 ```js
-a = 12
-a = 23
-b = functon1()
-c = function2()
-d = a + b
-if(a == b) {
-    log('a = b')
-} else {
-    log("a != b")
+user = loadUser()
+name = user.profile.name ?? 'anonymous'
+
+items = []
+_push_(items, name)
+
+if (_len_(items) > 0) {
+    log(items[0])
 }
 ```
 
-## How to use
-The host application can expose functions through Mevento VM that way:
+## Built-In Functions
+
+Result helpers:
+
+```text
+_try_(expression)        # returns {ok, value, error}; evaluates lazily
+_ok_(result)
+_err_(result)
+_value_(result, fallback)
+_error_(result)
+_code_(result)
+_message_(result)
+_unwrap_(result)
+```
+
+Collection helpers:
+
+```text
+_len_(array|object|string)
+_push_(array, value)        # mutates array, returns array
+_pop_(array)                # mutates array, returns removed value or null
+_insert_(array, index, value)
+_remove_at_(array, index)   # mutates array, returns removed value or null
+_has_(object, key)
+_keys_(object)
+_values_(object)
+```
+
+Invalid built-in argument types raise `invalid_argument_type` and can be
+captured with `_try_`.
+
+## Usage
+
+Register global functions:
+
+```ts
+import { MEvento } from "mevento";
+
+MEvento.register("log", (args) => {
+  console.log(...args);
+  return null;
+});
+
+MEvento.register("add", (args) => Number(args[0]) + Number(args[1]), {
+  name: "add",
+  description: "Adds two numeric values.",
+  minArgs: 2,
+  maxArgs: 2,
+  args: [
+    { name: "left", type: "number", description: "First value." },
+    { name: "right", type: "number", description: "Second value." },
+  ],
+  returnType: "number",
+  returnDescription: "The sum of the two values.",
+  examples: [{ script: "add(12, 23)", result: 35 }],
+  metadata: { category: "math" },
+});
+
+const value = MEvento.run("add(12, 23)");
+```
+
+Use one VM instance:
+
 ```ts
-import {MEvento} from 'mevento';
-MEvento.register('log', (args) => console.log); // exposes console.log through MEvento as log function
-MEvento.register('cos2', (args) => Math.cos);
+import { MEvento } from "mevento";
+
+const vm = MEvento.newInstance();
+
+vm.registerFunction("loadUser", () => ({ profile: { name: "Awa" } }), {
+  name: "loadUser",
+  maxArgs: 0,
+  returnType: "object",
+});
+
+const result = vm.execute("loadUser().profile.name");
 ```
 
-Let's assume you want to execute a `MEvento code`: 
+Use async host functions:
 
 ```ts
-import {MEvento} from 'mevento';
+import { MEventoAsync } from "mevento";
 
-const mevento = MEvento.newInstance();
+const vm = MEventoAsync.newInstance();
 
-mevento.execute(`log("molo")`)
+vm.registerFunction("fetchUser", async () => ({ name: "Awa" }), {
+  name: "fetchUser",
+  maxArgs: 0,
+  returnType: "object",
+});
 
+const name = await vm.execute("fetchUser().name");
 ```
 
-`MEvento` instance execution is syncrhrone, that's to say, if you wan to consume `async` function exposed through Mevento, you nee to use `MEventoAsync` instead.
+Inject host input for one run:
+
+```ts
+const total = MEvento.run("base + bonus", false, {
+  base: 12,
+  bonus: 23,
+});
+```
+
+## Documenting Host Functions
+
+Function and argument specs can carry optional documentation metadata:
+`description`, `returnDescription`, `examples`, and `metadata` on functions,
+plus `description` and `metadata` on arguments. The runtime exposes those fields
+through `capabilities()` for diagnostics, documentation, and UI tooling, but
+they do not change script execution.
+
+## Validation And Manifests
 
+Function specs drive preflight validation and runtime argument checks:
 
 ```ts
-import {MEvento} from 'mevento';
+const validation = vm.validate("add(12)");
+if (!validation.ok) {
+  console.log(validation.errors);
+}
+```
+
+Manifest validation checks required functions, inputs, and outputs:
+
+```ts
+const manifest = {
+  functions: {
+    add: { name: "add", minArgs: 2, maxArgs: 2, returnType: "number" },
+  },
+  inputs: [{ name: "base", type: "number" }],
+  outputs: [{ name: "result", type: "number" }],
+};
+
+const checked = MEvento.validateManifestSource(
+  "result = add(base, 2)",
+  manifest,
+);
+```
+
+## Options: Compatibility, Trace And Budgets
 
-MEvento.register('async', async (args) => await asyncF(args[0]));
-const mevento = MEventoAsync.newInstance();
+Use options to enable v1 compatibility for existing scripts, cap execution
+steps, or collect a lightweight trace:
 
-await mevento.execute(`async("molo")`)
+```ts
+const legacyVm = MEvento.newInstance({ compatV1: true });
+legacyVm.execute("optionalHostFunction()"); // returns null when missing
 
+const vm = MEvento.newInstance({ maxSteps: 1000, trace: true });
+vm.execute("log('ok')");
+
+const trace = vm.trace();
 ```
-`execute` method on `MEventoAsync` instance return a `Promise`.
 
+## Development
 
-## Notes
-MEvento does not have scope variables, all variables are visible everywhere.  
+```bash
+npm install
+npm run build
+npm run test:conformance
+```
 
+The package currently uses a custom conformance command. Do not use `npm test`
+unless package metadata is updated.

package/dist/cjs/index.d.ts

@@ -45,6 +45,7 @@ declare class TokenType {
     static CONTINUE: number;
     static nullity: number;
     static RETURN: number;
+    static dot: number;
 }
 declare class Token {
     type: number;
@@ -73,6 +74,106 @@ declare abstract class AST {
     constructor(line?: number, col?: number);
     dump(): string;
 }
+declare class MEventoRuntimeError extends Error {
+    line?: number;
+    col?: number;
+    nodeType?: string;
+    cause?: unknown;
+    detail: string;
+    code: string;
+    diagnosticName?: string;
+    argCount?: number;
+    minArgs?: number;
+    maxArgs?: number;
+    argIndex?: number;
+    expectedType?: string;
+    actualType?: string;
+    stepCount?: number;
+    maxSteps?: number;
+    constructor(detail: string, line?: number, col?: number, nodeType?: string, cause?: unknown, diagnostic?: Partial<Omit<MEventoDiagnostic, "message" | "line" | "col" | "node">>);
+    static fromNode(node: AST, error: unknown): MEventoRuntimeError;
+    private static format;
+    diagnostic(): MEventoDiagnostic;
+}
+type MEventoDiagnostic = {
+    code: string;
+    message: string;
+    name?: string;
+    line?: number;
+    col?: number;
+    node?: string;
+    argCount?: number;
+    minArgs?: number;
+    maxArgs?: number;
+    argIndex?: number;
+    expectedType?: string;
+    actualType?: string;
+    stepCount?: number;
+    maxSteps?: number;
+};
+type MEventoValidationError = MEventoDiagnostic;
+type MEventoValidationResult = {
+    ok: boolean;
+    errors: MEventoValidationError[];
+};
+type MEventoFunctionSpec = {
+    name: string;
+    minArgs?: number;
+    maxArgs?: number;
+    tags?: Iterable<string>;
+    args?: MEventoArgSpec[];
+    returnType?: string;
+    description?: string;
+    returnDescription?: string;
+    examples?: MEventoFunctionExample[];
+    metadata?: {
+        [name: string]: unknown;
+    };
+};
+type MEventoFunctionExample = {
+    title?: string;
+    script: string;
+    result?: unknown;
+    description?: string;
+};
+type MEventoArgSpec = {
+    name: string;
+    type?: string;
+    required?: boolean;
+    description?: string;
+    metadata?: {
+        [name: string]: unknown;
+    };
+};
+type MEventoOptions = {
+    maxSteps?: number;
+    trace?: boolean;
+    compatV1?: boolean;
+};
+type MEventoValueSpec = {
+    name: string;
+    type?: string;
+    required?: boolean;
+};
+type MEventoScriptManifest = {
+    functions?: MEventoFunctionList;
+    inputs?: MEventoValueSpec[];
+    outputs?: MEventoValueSpec[];
+};
+type MEventoTraceEvent = {
+    kind: string;
+    line?: number;
+    col?: number;
+    node?: string;
+    name?: string;
+    stepCount?: number;
+    detail: {
+        [name: string]: unknown;
+    };
+};
+type MEventoFunctionList = Set<string> | string[] | MEventoFunctionSpec[] | {
+    [name: string]: MEventoFunctionSpec;
+};
 declare class RootAST extends AST {
     body: AST[];
     source: string;
@@ -220,6 +321,7 @@ declare abstract class ANodeVisitor {
 declare abstract class NodeVisitor extends ANodeVisitor {
     constructor();
     visit(node: AST): any;
+    protected beforeVisit(_node: AST): void;
     protected assignProperty(owner: any, property: any, value: any): any;
     protected abstract visitRootAST(node: RootAST): any;
     protected abstract visitBlockStatementAST(node: BlockStatementAST): any;
@@ -261,17 +363,43 @@ declare class MEvento extends NodeVisitor {
     protected currentScope?: MEventScope;
     debug: boolean;
     private static _globalFunctionsRegistry;
+    private static _globalFunctionSpecs;
     private static _cache;
     protected _functionsRegistry: {
         [k: string]: MEventoFBinding;
     };
+    protected _functionSpecs: {
+        [k: string]: MEventoFunctionSpec;
+    };
     protected _functionResolver?: (name: string) => MEventoFBinding | undefined;
-    constructor();
+    protected _options: MEventoOptions;
+    private _executionStepCount;
+    private _traceEvents;
+    constructor(options?: MEventoOptions);
+    get options(): MEventoOptions;
+    get executionStepCount(): number;
+    trace(): MEventoTraceEvent[];
+    protected resetExecutionBudget(): void;
+    protected beforeVisit(node: AST): void;
+    protected clearTrace(): void;
+    protected recordTrace(kind: string, node: AST, name?: string, detail?: {
+        [name: string]: unknown;
+    }): void;
     protected resolve(name: string): any;
     protected changeVariable(name: string, value: any): any;
     protected pushScope(name: string): void;
     protected popScope(): void;
     protected log(message: any): void;
+    protected successResult(value: any): {
+        ok: boolean;
+        value: any;
+        error: any;
+    };
+    protected errorResult(error: MEventoRuntimeError): {
+        ok: boolean;
+        value: any;
+        error: MEventoDiagnostic;
+    };
     protected visitRootAST(node: RootAST): any;
     protected visitBlockStatementAST(node: BlockStatementAST): any;
     protected visitIdentifierAST(node: IdentifierAST): any;
@@ -297,23 +425,54 @@ declare class MEvento extends NodeVisitor {
     resolveArguments(args: AST[]): any;
     setFunctionResolver(resolver: (name: string) => MEventoFBinding | undefined): void;
     resolveFunction(name: string): MEventoFBinding | undefined;
-    registerFunction(id: string, fn: MEventoFBinding): void;
+    resolveFunctionSpec(name: string): MEventoFunctionSpec | undefined;
+    capabilities(): {
+        [name: string]: MEventoFunctionSpec;
+    };
+    registerFunction(id: string, fn: MEventoFBinding, spec?: MEventoFunctionSpec): void;
     unregisterFunction(id: string): void;
+    validate(source: string, functions?: MEventoFunctionList, cache?: boolean): MEventoValidationResult;
+    validateManifest(source: string, manifest: MEventoScriptManifest, cache?: boolean): MEventoValidationResult;
+    protected validationFunctionSpecs(functions?: MEventoFunctionList): Map<string, MEventoFunctionSpec>;
+    protected validateNode(node: AST | null | undefined, knownFunctions: Map<string, MEventoFunctionSpec>, errors: MEventoValidationError[], protectedByTry?: boolean): void;
+    protected validateCallExpression(node: CallExpressionAST, knownFunctions: Map<string, MEventoFunctionSpec>, errors: MEventoValidationError[], protectedByTry: boolean): void;
+    protected validateStaticArgumentTypes(node: CallExpressionAST, spec: MEventoFunctionSpec, errors: MEventoValidationError[]): void;
+    protected staticArgumentType(node: AST): string | undefined;
+    protected argumentTypeMatches(spec: MEventoArgSpec, actualType: string): boolean;
+    protected validateManifestNode(module: AST, manifest: MEventoScriptManifest, errors: MEventoValidationError[]): void;
+    protected analyzeManifestNode(node: AST | null | undefined, analysis: {
+        knownInputs: Set<string>;
+        assigned: Set<string>;
+        assignedTypes: Map<string, string>;
+        reportedInputs: Set<string>;
+    }, errors: MEventoValidationError[]): void;
+    protected markAssignedTarget(node: AST, assignedType: string | undefined, analysis: {
+        assigned: Set<string>;
+        assignedTypes: Map<string, string>;
+    }): void;
+    protected valueSpecTypeMatches(spec: MEventoValueSpec, actualType: string): boolean;
+    protected validationError(code: string, node: AST, message: string, name?: string, diagnostic?: Pick<MEventoDiagnostic, "argCount" | "minArgs" | "maxArgs" | "argIndex" | "expectedType" | "actualType">): MEventoValidationError;
+    protected validateRuntimeArgumentTypes(node: AST, spec: MEventoFunctionSpec, values: unknown[]): void;
     execute(source: string, cache?: boolean, input?: {
         [k: string]: any;
     }): any;
     static compile(source: string, cache?: boolean): AST;
-    static register(id: string, fn: MEventoFBinding): void;
+    static register(id: string, fn: MEventoFBinding, spec?: MEventoFunctionSpec): void;
     static unregister(id: string): void;
+    static capabilities(): {
+        [name: string]: MEventoFunctionSpec;
+    };
+    static validateSource(source: string, functions: MEventoFunctionList, cache?: boolean): MEventoValidationResult;
+    static validateManifestSource(source: string, manifest: MEventoScriptManifest, cache?: boolean): MEventoValidationResult;
     static run(source: string, cache?: boolean, input?: {
         [k: string]: any;
-    }): any;
-    static newInstance(): MEvento;
+    }, options?: MEventoOptions): any;
+    static newInstance(options?: MEventoOptions): MEvento;
     clone(): MEvento;
     newAsyncInstance(): MEventoAsync;
 }
 declare class MEventoAsync extends MEvento {
-    constructor();
+    constructor(options?: MEventoOptions);
     protected visitRootAST(node: RootAST): Promise<any>;
     protected visitBlockStatementAST(node: BlockStatementAST): Promise<any>;
     protected visitIdentifierAST(node: AST): Promise<any>;
@@ -334,16 +493,16 @@ declare class MEventoAsync extends MEvento {
     protected visitForOfStatement(node: ForOfStatement): Promise<any[] | ReturnBranch>;
     protected visitReturnAST(node: ReturnAST): Promise<any>;
     resolveArgumentsAsync(args: AST[]): Promise<any[]>;
-    registerFunction(id: string, fn: MEventoFBinding): void;
+    registerFunction(id: string, fn: MEventoFBinding, spec?: MEventoFunctionSpec): void;
     unregisterFunction(id: string): void;
     execute(source: string, cache?: boolean, input?: {
         [k: string]: any;
     }): Promise<any>;
     static run(source: string, cache?: boolean, input?: {
         [k: string]: any;
-    }): Promise<any>;
-    static newInstance(): MEventoAsync;
+    }, options?: MEventoOptions): Promise<any>;
+    static newInstance(options?: MEventoOptions): MEventoAsync;
     clone(): MEventoAsync;
 }
 
-export { AST, ArrayExpression, AssignmentExpressionAST, BinaryExpressionAST, BlockStatementAST, BreakAST, BreakBranch, CallExpressionAST, ContinueAST, ContinueBranch, ExpressionStatementAST, ForLoopStatement, ForOfStatement, IdentifierAST, IfStatementAST, IndexAccessorAST, LexerDictionary, LiteralAST, LogicalExpressionAST, LoopControl, MEventScope, MEvento, MEventoAsync, type MEventoFBinding, NodeVisitor, ObjectExpression, ObjectProperty, ReturnAST, ReturnBranch, RootAST, Token, TokenType, TupleExpression, UnaryExpressionAST, WhileLoopStatement };
+export { AST, ArrayExpression, AssignmentExpressionAST, BinaryExpressionAST, BlockStatementAST, BreakAST, BreakBranch, CallExpressionAST, ContinueAST, ContinueBranch, ExpressionStatementAST, ForLoopStatement, ForOfStatement, IdentifierAST, IfStatementAST, IndexAccessorAST, LexerDictionary, LiteralAST, LogicalExpressionAST, LoopControl, MEventScope, MEvento, type MEventoArgSpec, MEventoAsync, type MEventoDiagnostic, type MEventoFBinding, type MEventoFunctionExample, type MEventoFunctionList, type MEventoFunctionSpec, type MEventoOptions, MEventoRuntimeError, type MEventoScriptManifest, type MEventoTraceEvent, type MEventoValidationError, type MEventoValidationResult, type MEventoValueSpec, NodeVisitor, ObjectExpression, ObjectProperty, ReturnAST, ReturnBranch, RootAST, Token, TokenType, TupleExpression, UnaryExpressionAST, WhileLoopStatement };