@casual-simulation/aux-runtime/runtime/AuxCompiler.d.ts

Runtime for AUX projects

import type { TranspilerResult } from './Transpiler';
import type { BotModule } from '@casual-simulation/aux-common/bots';
import type { Breakpoint, ConstructedFunction, Interpreter, InterpreterContinuation, InterpreterStop, PossibleBreakpointLocation } from '@casual-simulation/js-interpreter';
import type { CodeLocation } from './TranspilerUtils';
/**
 * A symbol that identifies a function as having been compiled using the AuxCompiler.
 */
export declare const COMPILED_SCRIPT_SYMBOL: unique symbol;
/**
 * The symbol that is used to tag specific functions as interpretable.
 */
export declare const INTERPRETABLE_FUNCTION: unique symbol;
/**
 * The symbol that is used to tag function modules with the metadata for a function.
 */
export declare const FUNCTION_METADATA: unique symbol;
/**
 * Creates a new interpretable function based on the given function.
 * @param interpretableFunc
 */
export declare function createInterpretableFunction<TArg extends Array<any>, R>(interpretableFunc: (...args: TArg) => Generator<any, R, any>): {
    (...args: TArg): R;
    [INTERPRETABLE_FUNCTION]: (...args: TArg) => Generator<any, R, any>;
};
/**
 * Sets the INTERPRETABLE_FUNCTION property on the given object (semantically a function) to the given interpretable version and returns the object.
 * @param interpretableFunc The version of the function that should be used as the interpretable version of the function.
 * @param normalFunc The function that should be tagged.
 */
export declare function tagAsInterpretableFunction<T, N>(interpretableFunc: T, normalFunc: N): N & {
    [INTERPRETABLE_FUNCTION]: T;
};
/**
 * Determines if the given object has been tagged with the GENERATOR_FUNCTION_TAG.
 * @param obj The object.
 */
export declare function isInterpretableFunction(obj: unknown): boolean;
/**
 * Gets the interpretable version of the given function.
 */
export declare function getInterpretableFunction<T extends Function>(obj: unknown): T;
export declare const IMPORT_FACTORY = "___importModule";
export declare const IMPORT_META_FACTORY = "___importMeta";
export declare const EXPORT_FACTORY = "___exportModule";
/**
 * Defines a class that can compile scripts and formulas
 * into functions.
 */
export declare class AuxCompiler {
    private _transpiler;
    private _functionCache;
    /**
     * The offset that should be applied to error line numbers when calculating their original
     * position. Needed because Node.js Windows produces different line numbers than Mac/Linux.
     *
     * Node.js versions greater than v12.14.0 have an issue with identifying the correct line number
     * for errors and stack traces. This issue is fixed in Node.js v14 and later (possibly also fixed in v13 but I didn't check that).
     */
    functionErrorLineOffset: number;
    /**
     * Calculates the "original" stack trace that the given error occurred at
     * within the given function.
     * Returns null if the original stack trace was unable to be determined.
     * @param functionNameMap A map of function names to their scripts.
     * @param error The error that occurred.
     */
    calculateOriginalStackTrace(functionNameMap: Map<string, AuxCompiledScript>, error: Error): string;
    private _calculateInterpreterErrorOriginalStackTrace;
    private _calculateNativeErrorOriginalStackTrace;
    /**
     * Calculates the original location within the given function for the given location.
     * The returned location uses zero-based line and column numbers.
     * @param func The function.
     * @param location The location. Line and column numbers are one-based.
     */
    calculateOriginalLineLocation(func: AuxCompiledScript, location: CodeLocation): CodeLocation;
    /**
     * Calculates the final location within the given function for the given location.
     * @param func The function.
     * @param location The location. Line and column numbers are zero based.
     */
    calculateFinalLineLocation(func: AuxCompiledScript, location: CodeLocation): CodeLocation;
    /**
     * Compiles the given script into a function.
     * @param script The script to compile.
     * @param options The options that should be used to compile the script.
     */
    compile<T>(script: string, options?: AuxCompileOptions<T>): AuxCompiledScript;
    /**
     * Finds the line number information for a function created with this compiler using the
     * given stack trace and metadata.
     * @param stackTrace The stack trace.
     * @param metadata The metadata.
     */
    findLineInfo(stackTrace: NodeJS.CallSite[], metadata: AuxScriptMetadata): LineInfo;
    /**
     * Sets the given breakpoint.
     * @param breakpoint The breakpoint that should be set.
     */
    setBreakpoint(breakpoint: AuxCompilerBreakpoint): void;
    listPossibleBreakpoints(func: AuxCompiledScript, interpreter: Interpreter): PossibleBreakpointLocation[];
    private _parseScript;
    private _parseModule;
    private _compileFunction;
    private _buildFunction;
    private __constructFunction;
}
/**
 * Parses the line and column numbers from the the given syntax error, transforms them with the given function,
 * and returns a new syntax error that contains the new location. Returns null if the line and column numbers could not be parsed.
 * @param error The error to transform.
 * @param transform The function that should be used to transform the errors.
 * @returns
 */
export declare function replaceSyntaxErrorLineNumber(error: SyntaxError, transform: (location: CodeLocation) => CodeLocation): SyntaxError;
/**
 * A script that has been compiled.
 */
export interface AuxCompiledScript {
    (...args: any[]): any;
    [INTERPRETABLE_FUNCTION]: ((...args: any[]) => Generator<InterpreterStop, any, InterpreterContinuation>) | null;
    /**
     * The metadata for the script.
     */
    metadata: AuxScriptMetadata;
}
/**
 * Line information that has been calculated from a stack trace.
 */
export interface LineInfo {
    /**
     * The line number.
     */
    line: number | null;
    /**
     * The column number.
     */
    column: number | null;
}
/**
 * Metadata about the script.
 */
export interface AuxScriptMetadata {
    /**
     * The function that directly wraps the script.
     */
    scriptFunction: Function;
    /**
     * The number of lines that the user's script is offset inside the returned function source.
     */
    scriptLineOffset: number;
    /**
     * The number of lines that the user's script is offset from the tranpiler's output.
     */
    transpilerLineOffset: number;
    /**
     * The transpiler result;
     */
    transpilerResult: TranspilerResult;
    /**
     * The name that should be used for the function in stack traces.
     */
    diagnosticFunctionName: string;
    /**
     * The file name that was specified for the script.
     */
    fileName: string;
    /**
     * Whether the function is asynchronous and returns a promise.
     */
    isAsync: boolean;
    /**
     * Whether the function contains a module.
     */
    isModule: boolean;
    /**
     * The function that was constructed by the interpreter.
     */
    constructedFunction: ConstructedFunction;
    /**
     * The context that the function was created with.
     */
    context: any;
}
export interface CompiledBotModule extends BotModule, AuxCompiledScript {
}
/**
 * The set of options that a script should be compiled with.
 */
export interface AuxCompileOptions<T> {
    /**
     * The context that should be used.
     */
    context?: T;
    /**
     * The realm that should be used for the script.
     * If provided, then the script will be parsed and executed in the context of this realm and
     * the corresponding engine262 agent.
     */
    interpreter?: Interpreter;
    /**
     * The variables that should be made available to the script.
     */
    variables?: {
        [name: string]: (context?: T) => any;
    };
    /**
     * The constant values that should be made available to the script.
     */
    constants?: {
        [name: string]: any;
    };
    /**
     * The names that each argument should be assigned.
     */
    arguments?: (string | string[])[];
    /**
     * A function that should be called before the compiled function is executed.
     */
    before?: (context?: T) => void;
    /**
     * A function that should be called after the compiled function is executed.
     */
    after?: (context?: T) => void;
    /**
     * A function that should be called to invoke the compiled function.
     */
    invoke?: (func: Function, context?: T) => any;
    /**
     * A function that should be called when an error occurs.
     */
    onError?: (error: any, context?: T, meta?: AuxScriptMetadata) => void;
    /**
     * The name that should be given to the function.
     */
    functionName?: string;
    /**
     * The name that should be used for the function in stack traces.
     */
    diagnosticFunctionName?: string;
    /**
     * The file name that should be used for transformed error stack traces.
     */
    fileName?: string;
    /**
     * Whether to force the output function to be synchronous.
     * This will compile out any async/await code.
     */
    forceSync?: boolean;
    /**
     * The global object that the function should be compiled to reference.
     *
     */
    globalObj?: any;
}
/**
 * The set of options that a breakpoint should use.
 */
export interface AuxCompilerBreakpoint extends Omit<Breakpoint, 'func'> {
    /**
     * The script that the breakpoint should be set for.
     */
    func: AuxCompiledScript;
    /**
     * The interpreter that the breakpoint should be set on.
     */
    interpreter: Interpreter;
}
//# sourceMappingURL=AuxCompiler.d.ts.map