evaluator api proposal

evaluator.ts

interface EvaluatorInit {
    importHook(name, referrer): Promise<ParsedModule>;
    isDirectEvalHook(evalFunctionRef: any): boolean;
    randomHook(): number; // Use for Math.random()
    nowHook(): number; // Use for both Date.now() and new Date(),
    localeHook(): string; // e.g.: 'fr-FR' - Affects appropriate ECMA-402 APIs within Realm
    LocalTZAHook(): string; // This is important to be able to override for deterministic testing and such
    canCompileStringsHook(source: String): boolean; // mimic CSP including nounces
    thisValue?: object;
}

interface EvaluateOptions {
    // the type of source to be evaluated, "program" or "expression"
    type: string;
    // object or proxy used to resolve bindings on the global execution context
    globalContour?: object;
}

interface Evaluator {
    intrinsics(): Record<string, IntrinsicObject>; // current realm's intrinsics + those redefined by the evaluator (Function, eval, Realm, etc)
    evaluate(sourceText: string, options: EvaluateOptions): CompletionRecord;
    import(specifier: string): Promise<ModuleNamespace>;
}

declare var Evaluator: {
    prototype: Evaluator;
    new(options?: EvaluatorInit): Evaluator;
    parseModule(sourceText: String): ParsedModule;
};

// inspired by https://gist.github.com/dherman/1555894a09ca188d4d3ca0c96fb44311
interface ParsedModule {
    link(specifier: string, parsedModule: ParsedModule);
    requestedNames(): string[];
}

// Other potential hooks (dialect explained here: https://gist.github.com/dherman/9146568)
// - transformSourceHook(source: string, type: Script | Module | ...): string;
// - importMetaHook(parsedModule: ParsedModule): ImportMetaObject;