@robinpath/robinpath 0.30.0

package/dist/index.d.ts

@@ -0,0 +1,485 @@
+import { extractNamedArgs, Value, AttributePathSegment } from './utils';
+import { RobinPathThread, ExecutionStateTracker, ExecutionLog } from './classes';
+import { Statement, Arg, DefineFunction, OnBlock } from './types/Ast.type';
+/**
+ * RobinPath Interpreter
+ *
+ * See README.md for full documentation and usage examples.
+ */
+export declare const ROBINPATH_VERSION = "0.30.0";
+export interface ModuleAdapter {
+    name: string;
+    functions: Record<string, BuiltinHandler>;
+    functionMetadata: Record<string, FunctionMetadata>;
+    moduleMetadata: ModuleMetadata;
+    global?: boolean;
+}
+export { Parser, Printer, LineIndexImpl } from './classes';
+export type { PrintContext, LineIndex } from './classes';
+export { formatErrorWithContext, createErrorWithContext } from './utils';
+export type { ExecutionLog, ExecutionStepInfo, LogCallback } from './classes';
+export type { Value, AttributePathSegment };
+export type { Statement, Arg, CommandCall, Assignment, ShorthandAssignment, InlineIf, IfBlock, IfTrue, IfFalse, DefineFunction, ScopeBlock, TogetherBlock, ForLoop, ReturnStatement, BreakStatement, OnBlock, CommentStatement, ChunkMarkerStatement, CellBlock, PromptBlockStatement, CommentWithPosition, CodePosition, DecoratorCall, } from './types/Ast.type';
+export type BuiltinCallback = (callbackArgs: Value[]) => Promise<Value> | Value | null;
+export type BuiltinHandler = (args: Value[], callback?: BuiltinCallback | null) => Promise<Value> | Value | null;
+export type DecoratorHandler = (targetName: string, func: DefineFunction | null, originalArgs: Value[], decoratorArgs: Value[], originalDecoratorArgs?: Arg[]) => Promise<Value[] | Value | null | undefined>;
+export type ParseDecoratorHandler = (targetName: string, func: DefineFunction | null, decoratorArgs: Arg[], environment: Environment) => Promise<void> | void;
+export interface Environment {
+    variables: Map<string, Value>;
+    functions: Map<string, DefineFunction>;
+    builtins: Map<string, BuiltinHandler>;
+    decorators: Map<string, DecoratorHandler>;
+    parseDecorators: Map<string, ParseDecoratorHandler>;
+    metadata: Map<string, FunctionMetadata>;
+    moduleMetadata: Map<string, ModuleMetadata>;
+    currentModule: string | null;
+    variableMetadata: Map<string, Map<string, Value>>;
+    functionMetadata: Map<string, Map<string, Value>>;
+    constants: Set<string>;
+    eventHandlers: Map<string, OnBlock[]>;
+    stateTracker?: ExecutionStateTracker;
+}
+export interface Frame {
+    locals: Map<string, Value>;
+    lastValue: Value;
+    isFunctionFrame?: boolean;
+    forgotten?: Set<string>;
+    isIsolatedScope?: boolean;
+}
+export { extractNamedArgs };
+export type DataType = "string" | "number" | "boolean" | "object" | "array" | "null" | "any";
+export type FormInputType = "text" | "number" | "textarea" | "select" | "checkbox" | "radio" | "date" | "datetime" | "file" | "json" | "code" | "varname";
+export interface ParameterMetadata {
+    name: string;
+    label?: string;
+    dataType: DataType;
+    description: string;
+    formInputType: FormInputType;
+    required?: boolean;
+    defaultValue?: Value;
+    allowedTypes?: string[];
+    children?: ParameterMetadata;
+}
+export interface FunctionMetadata {
+    description: string;
+    parameters: ParameterMetadata[];
+    returnType: DataType;
+    returnDescription: string;
+    example?: string;
+}
+export interface ModuleMetadata {
+    description: string;
+    methods: string[];
+    author?: string;
+    category?: string;
+    doc_url?: string;
+}
+export declare class RobinPath {
+    private static versionLogged;
+    private environment;
+    private persistentExecutor;
+    private lastExecutor;
+    private activeExecutor;
+    private threads;
+    private currentThread;
+    private threadControl;
+    private replBuffer;
+    private astToCodeConverter;
+    private serializer;
+    private stateTracker;
+    constructor(options?: {
+        threadControl?: boolean;
+    });
+    /**
+     * Get execution steps from the last execution
+     */
+    getExecutionSteps(): import('./classes').ExecutionStepInfo[];
+    /**
+     * Get execution logs from the last execution
+     */
+    getExecutionLogs(): ExecutionLog[];
+    /**
+     * Set a callback for real-time log notifications
+     * The callback is called immediately when a log is added during execution
+     */
+    setLogCallback(callback: ((log: ExecutionLog) => void) | null): void;
+    /**
+     * Clear execution state
+     */
+    clearExecutionState(): void;
+    /**
+     * Native modules registry
+     * Add new modules here to auto-load them
+     */
+    private static readonly NATIVE_MODULES;
+    /**
+     * Load a single module using the adapter pattern
+     */
+    private loadModule;
+    /**
+     * Load all native modules
+     */
+    private loadNativeModules;
+    /**
+     * Register a builtin function
+     */
+    registerBuiltin(name: string, handler: BuiltinHandler): void;
+    /**
+     * Register a runtime decorator function that can be used to modify function calls at execution time
+     * Runtime decorators execute during function execution and can modify arguments or behavior
+     * Decorators are only available via API registration, not in scripts
+     * @param name Decorator name (without @ prefix)
+     * @param handler Decorator handler function
+     */
+    registerDecorator(name: string, handler: DecoratorHandler): void;
+    /**
+     * Register a parse-time decorator function that executes during parsing
+     * Parse decorators inject metadata into AST nodes (def, on, var, const)
+     * They run during parsing, not execution, and work with AST arguments
+     * @param name Decorator name (without @ prefix)
+     * @param handler Parse decorator handler function
+     */
+    registerParseDecorator(name: string, handler: ParseDecoratorHandler): void;
+    /**
+     * Register built-in parse-time decorators (@desc/@description, @title, @param, @arg, @required)
+     * These decorators execute during parsing and inject metadata into AST nodes
+     */
+    private registerBuiltinDecorators;
+    /**
+     * Register a module with multiple functions
+     * @example
+     * rp.registerModule('fs', {
+     *   read: (args) => { ... },
+     *   write: (args) => { ... }
+     * });
+     */
+    registerModule(moduleName: string, functions: Record<string, BuiltinHandler>): void;
+    /**
+     * Register a module function (e.g., 'fs.read')
+     */
+    registerModuleFunction(module: string, func: string, handler: BuiltinHandler): void;
+    /**
+     * Register an external class constructor (e.g., 'Client', 'Database')
+     */
+    registerConstructor(name: string, handler: BuiltinHandler): void;
+    /**
+     * Register metadata for a module with multiple functions
+     * @example
+     * rp.registerModuleMeta('fs', {
+     *   read: {
+     *     description: 'Reads a file from the filesystem',
+     *     parameters: [
+     *       {
+     *         name: 'filename',
+     *         dataType: 'string',
+     *         description: 'Path to the file to read',
+     *         formInputType: 'text',
+     *         required: true
+     *       }
+     *     ],
+     *     returnType: 'string',
+     *     returnDescription: 'Contents of the file'
+     *   },
+     *   write: {
+     *     description: 'Writes content to a file',
+     *     parameters: [
+     *       {
+     *         name: 'filename',
+     *         dataType: 'string',
+     *         description: 'Path to the file to write',
+     *         formInputType: 'text',
+     *         required: true
+     *       },
+     *       {
+     *         name: 'content',
+     *         dataType: 'string',
+     *         description: 'Content to write to the file',
+     *         formInputType: 'textarea',
+     *         required: true
+     *       }
+     *     ],
+     *     returnType: 'boolean',
+     *     returnDescription: 'True if write was successful'
+     *   }
+     * });
+     */
+    registerModuleMeta(moduleName: string, functions: Record<string, FunctionMetadata>): void;
+    /**
+     * Register metadata for a single module function (e.g., 'fs.read')
+     * @example
+     * rp.registerModuleFunctionMeta('fs', 'read', {
+     *   description: 'Reads a file from the filesystem',
+     *   parameters: [
+     *     {
+     *       name: 'filename',
+     *       dataType: 'string',
+     *       description: 'Path to the file to read',
+     *       formInputType: 'text',
+     *       required: true
+     *     }
+     *   ],
+     *   returnType: 'string',
+     *   returnDescription: 'Contents of the file'
+     * });
+     */
+    registerModuleFunctionMeta(module: string, func: string, metadata: FunctionMetadata): void;
+    /**
+     * Get metadata for a function (builtin or module function)
+     * Returns null if no metadata is registered
+     */
+    getFunctionMetadata(functionName: string): FunctionMetadata | null;
+    /**
+     * Get all registered function metadata
+     */
+    getAllFunctionMetadata(): Map<string, FunctionMetadata>;
+    /**
+     * Register module-level metadata (description and list of methods)
+     * @example
+     * rp.registerModuleInfo('fs', {
+     *   description: 'File system operations for reading and writing files',
+     *   methods: ['read', 'write', 'exists', 'delete']
+     * });
+     */
+    registerModuleInfo(moduleName: string, metadata: ModuleMetadata): void;
+    /**
+     * Get module metadata (description and methods list)
+     * Returns null if no metadata is registered
+     */
+    getModuleInfo(moduleName: string): ModuleMetadata | null;
+    /**
+     * Get all registered module metadata
+     */
+    getAllModuleInfo(): Map<string, ModuleMetadata>;
+    /**
+     * Get syntax context for available commands
+     * Determines what commands are valid based on the current syntax position
+     */
+    private getSyntaxContext;
+    /**
+     * Get all available commands, modules, and functions
+     * Returns a structured object with categories, each containing objects with:
+     * - name: The command/function name
+     * - type: The type (native, builtin, module, moduleFunction, userFunction)
+     * - description: Description if available
+     *
+     * @param context Optional syntax context to filter commands based on what's valid next
+     */
+    getAvailableCommands(context?: {
+        inIfBlock?: boolean;
+        inDefBlock?: boolean;
+        afterIf?: boolean;
+        afterDef?: boolean;
+        afterElseif?: boolean;
+    }): {
+        native: Array<{
+            name: string;
+            type: string;
+            description: string;
+        }>;
+        builtin: Array<{
+            name: string;
+            type: string;
+            description: string;
+        }>;
+        modules: Array<{
+            name: string;
+            type: string;
+            description: string;
+            author?: string;
+            category?: string;
+        }>;
+        moduleFunctions: Array<{
+            name: string;
+            type: string;
+            description: string;
+        }>;
+        userFunctions: Array<{
+            name: string;
+            type: string;
+            description: string;
+        }>;
+    };
+    /**
+     * Check if a script needs more input (incomplete block)
+     * Returns { needsMore: true, waitingFor: 'endif' | 'enddef' | 'endfor' | 'enddo' | 'endon' | 'subexpr' | 'paren' | 'object' | 'array' } if incomplete,
+     * or { needsMore: false } if complete.
+     */
+    needsMoreInput(script: string): Promise<{
+        needsMore: boolean;
+        waitingFor?: "endif" | "enddef" | "endfor" | "enddo" | "endon" | "subexpr" | "paren" | "object" | "array";
+    }>;
+    /**
+     * Get the AST without execution state
+     * Returns a JSON-serializable AST array
+     *
+     * Note: This method only parses the script, it does not execute it.
+     */
+    getAST(script: string): Promise<any[]>;
+    /**
+     * Get extracted function definitions (def/enddef blocks) from a script
+     * Returns a JSON-serializable array of function definitions
+     *
+     * Note: This method only parses the script, it does not execute it.
+     */
+    getExtractedFunctions(script: string): Promise<any[]>;
+    /**
+     * Serialize a statement to JSON
+     * @param stmt The statement to serialize
+     * @param currentModuleContext Optional module context
+     * @param lastValue Optional execution state
+     * @param nodeKey Optional node key
+     */
+    private serializeStatement;
+    /**
+     * Get the complete structure of the script in a tree format
+     * Includes main body, functions, event handlers, and variables
+     */
+    getScriptStructure(script: string): Promise<any>;
+    /**
+     * Get extracted variables from the script (parsed, not executed)
+     * Returns variable names with optional description and initial value
+     */
+    getExtractedVariables(script: string): Promise<Array<{
+        name: string;
+        description?: string;
+        initialValue?: any;
+    }>>;
+    /**
+     * Update source code based on AST changes
+     * Uses precise character-level positions (codePos.startRow/startCol/endRow/endCol) to update code
+     * Nested nodes are reconstructed as part of their parent's code
+     * @param originalScript The original source code
+     * @param ast The modified AST array (top-level nodes only)
+     * @returns Updated source code
+     */
+    updateCodeFromAST(originalScript: string, ast: any[]): Promise<string>;
+    /**
+     * Reconstruct code from an AST node
+     * @param node The AST node (serialized)
+     * @param indentLevel Indentation level for nested code
+     * @returns Reconstructed code string, or null if cannot be reconstructed
+     */
+    reconstructCodeFromASTNode(node: any, indentLevel?: number): string | null;
+    /**
+     * Execute a RobinPath script
+     */
+    executeScript(script: string): Promise<Value>;
+    /**
+     * Execute a single line (for REPL)
+     * Uses a persistent executor to maintain state ($, variables) between calls.
+     * Functions and builtins persist across calls.
+     */
+    executeLine(line: string): Promise<Value>;
+    /**
+     * Get the last value ($)
+     * Returns the value from the most recent execution (script or REPL line).
+     */
+    getLastValue(): Value;
+    /**
+     * REPL-friendly execution that supports multi-line blocks (if/def/for and $( ... )).
+     *
+     * Usage pattern:
+     *  - Call this for every user-entered line.
+     *  - If done === false, keep collecting lines.
+     *  - When done === true, value is the execution result and the buffer is cleared.
+     */
+    executeReplLine(line: string): Promise<{
+        done: boolean;
+        value: Value | null;
+        waitingFor?: string;
+    }>;
+    /**
+     * Generate a UUID v4
+     */
+    private generateUUID;
+    /**
+     * Create a new thread/session.
+     * Each thread has its own variables, functions, and $,
+     * but shares builtins and metadata with the root interpreter.
+     *
+     * @param id Optional thread ID. If not provided, a UUID will be generated.
+     * @returns The created thread
+     *
+     * @example
+     * const rp = new RobinPath();
+     * const thread = rp.createThread('my-thread');
+     * await thread.executeScript('math.add 5 5');
+     * console.log(thread.getLastValue()); // 10
+     */
+    createThread(id?: string): RobinPathThread;
+    /**
+     * Get a thread by ID
+     */
+    getThread(id: string): RobinPathThread | null;
+    /**
+     * List all threads with their IDs
+     */
+    listThreads(): Array<{
+        id: string;
+        isCurrent: boolean;
+    }>;
+    /**
+     * Switch to a different thread
+     */
+    useThread(id: string): void;
+    /**
+     * Get the current thread
+     */
+    getCurrentThread(): RobinPathThread | null;
+    /**
+     * Check if thread control is enabled
+     */
+    isThreadControlEnabled(): boolean;
+    /**
+     * Close a thread by ID
+     * If the closed thread is the current thread, currentThread is set to null
+     */
+    closeThread(id: string): void;
+    /**
+     * Trigger an event, executing all registered event handlers for the event name
+     * @param eventName The name of the event to trigger
+     * @param args Arguments to pass to event handlers (available as $1, $2, $3, etc.)
+     * @returns Promise that resolves when all handlers have executed
+     */
+    trigger(eventName: string, ...args: Value[]): Promise<void>;
+    /**
+     * Get all event handlers (onBlocks) registered in the environment
+     * @returns Map of event name to array of OnBlock handlers
+     */
+    getEventHandlers(): Map<string, OnBlock[]>;
+    /**
+     * Get all event handlers as a flat array
+     * @returns Array of all OnBlock handlers
+     */
+    getAllEventHandlers(): OnBlock[];
+    /**
+     * Get event handlers as serialized AST
+     * @returns Array of serialized event handler AST nodes
+     */
+    getEventAST(): any[];
+    /**
+     * Get a variable value
+     */
+    getVariable(name: string): Value;
+    /**
+     * Set a variable value (for external use)
+     */
+    setVariable(name: string, value: Value): void;
+    /**
+     * Get all variables as a plain object
+     */
+    getVariableState(): Record<string, Value>;
+    /**
+     * Get the next statement index that would execute after a given statement.
+     * This method analyzes the AST structure to determine execution flow.
+     *
+     * @param statements The array of all statements
+     * @param currentIndex The index of the current statement
+     * @param context Optional context for conditional branches (which branch was taken)
+     * @returns The index of the next statement to execute, or -1 if execution ends
+     */
+    getNextStatementIndex(statements: Statement[], currentIndex: number, context?: {
+        ifBlockBranch?: "then" | "elseif" | "else" | null;
+        forLoopIteration?: number;
+    }): number;
+}