@engine262/engine262 0.0.1-07c72085c73f960bcf0aa06db807321f3b446518

package/src/engine.mts

@@ -0,0 +1,451 @@
+import { JSStringValue, NullValue, Value } from './value.mts';
+import {
+  EnsureCompletion,
+  NormalCompletion,
+  ThrowCompletion,
+  Q, X,
+  type PlainCompletion,
+  type ExpressionCompletion,
+} from './completion.mts';
+import {
+  IsCallable,
+  Call, Construct, Assert,
+  GetActiveScriptOrModule,
+  CleanupFinalizationRegistry,
+  CreateArrayFromList,
+  FinishLoadingImportedModule,
+  Realm,
+  type FunctionObject,
+  GraphLoadingState,
+  PromiseCapabilityRecord,
+} from './abstract-ops/all.mts';
+import { GlobalDeclarationInstantiation } from './runtime-semantics/all.mts';
+import { Evaluate, type YieldEvaluator } from './evaluator.mts';
+import { CallSite, kAsyncContext, unwind } from './helpers.mts';
+import {
+  AbstractModuleRecord, CyclicModuleRecord, EnvironmentRecord, ObjectValue, PrivateEnvironmentRecord, runJobQueue, type Arguments, type AsyncGeneratorObject, type ErrorType, type GeneratorObject, type Intrinsics, type ModuleRecordHostDefined, type ParseScriptHostDefined, type ScriptRecord,
+} from './api.mts';
+import * as messages from './messages.mts';
+import type { ParseNode } from './parser/ParseNode.mts';
+import type { RegExpObject } from './intrinsics/RegExp.mts';
+import type { PromiseObject } from './intrinsics/Promise.mts';
+import type { FinalizationRegistryObject } from './intrinsics/FinalizationRegistry.mts';
+
+export const FEATURES = ([
+  {
+    name: 'FinalizationRegistry.prototype.cleanupSome',
+    flag: 'cleanup-some',
+    url: 'https://github.com/tc39/proposal-cleanup-some',
+  },
+  {
+    name: 'Well-Formed Unicode Strings',
+    flag: 'is-usv-string',
+    url: 'https://github.com/tc39/proposal-is-usv-string',
+  },
+]) as const;
+Object.freeze(FEATURES);
+FEATURES.forEach(Object.freeze);
+
+class ExecutionContextStack extends Array<ExecutionContext> {
+  // This ensures that only the length taking overload is supported.
+  // This is necessary to support `ArraySpeciesCreate`, which invokes
+  // the constructor with argument `length`:
+  constructor(length = 0) {
+    super(+length);
+  }
+
+  // @ts-expect-error
+  override pop(ctx: ExecutionContext) {
+    if (!ctx.poppedForTailCall) {
+      const popped = super.pop();
+      Assert(popped === ctx);
+    }
+  }
+}
+
+let agentSignifier = 0;
+export interface AgentHostDefined {
+  hasSourceTextAvailable?(f: FunctionObject): void;
+  ensureCanCompileStrings?(callerRealm: Realm, calleeRealm: Realm): PlainCompletion<void>;
+  cleanupFinalizationRegistry?(FinalizationRegistry: FinalizationRegistryObject): PlainCompletion<void>;
+  features?: readonly string[];
+  loadImportedModule?(referrer: AbstractModuleRecord | ScriptRecord | NullValue | Realm, specifier: string, hostDefined: ModuleRecordHostDefined | undefined, finish: (res: PlainCompletion<AbstractModuleRecord>) => void): void;
+  onDebugger?(): void;
+  onNodeEvaluation?(node: ParseNode, realm: Realm): void;
+  boost?: {
+    evaluatePattern?(pattern: ParseNode.RegExp.Pattern): RegExpObject['RegExpMatcher'];
+    evaluateScript?(script: ScriptRecord): ExpressionCompletion;
+    callFunction?(thisArgument: Value, argumentsList: Arguments): ExpressionCompletion;
+    constructFunction?(this: FunctionObject, argumentsList: Arguments, newTarget: FunctionObject): ExpressionCompletion<ObjectValue>
+  }
+
+  errorStackAttachNativeStack?: boolean;
+}
+/** https://tc39.es/ecma262/#sec-agents */
+export class Agent {
+  AgentRecord;
+
+  // #execution-context-stack
+  executionContextStack = new ExecutionContextStack();
+
+  // NON-SPEC
+  readonly jobQueue: Job[] = [];
+
+  scheduledForCleanup = new Set();
+
+  hostDefinedOptions: AgentHostDefined;
+
+  constructor(options: AgentHostDefined = {}) {
+    // #table-agent-record
+    const Signifier = agentSignifier;
+    agentSignifier += 1;
+    this.AgentRecord = {
+      LittleEndian: Value.true,
+      CanBlock: Value.true,
+      Signifier,
+      IsLockFree1: Value.true,
+      IsLockFree2: Value.true,
+      CandidateExecution: undefined,
+      KeptAlive: new Set<Value>(),
+    };
+
+    this.hostDefinedOptions = {
+      ...options,
+      features: options.features,
+    };
+  }
+
+  // #running-execution-context
+  get runningExecutionContext() {
+    return this.executionContextStack[this.executionContextStack.length - 1];
+  }
+
+  // #current-realm
+  get currentRealmRecord() {
+    return this.runningExecutionContext.Realm;
+  }
+
+  // #active-function-object
+  get activeFunctionObject() {
+    return this.runningExecutionContext.Function;
+  }
+
+  // Get an intrinsic by name for the current realm
+  intrinsic<const T extends keyof Intrinsics>(name: T): Intrinsics[T] {
+    return this.currentRealmRecord.Intrinsics[name];
+  }
+
+  // Generate a throw completion using message templates
+  Throw<K extends keyof typeof messages>(type: ErrorType | Value, template: K, ...templateArgs: Parameters<typeof messages[K]>): ThrowCompletion {
+    if (type instanceof Value) {
+      return ThrowCompletion(type);
+    }
+    const message = (messages[template] as (...args: unknown[]) => string)(...templateArgs);
+    const cons = this.currentRealmRecord.Intrinsics[`%${type}%`];
+    let error;
+    if (type === 'AggregateError') {
+      error = X(Construct(cons, [
+        X(CreateArrayFromList([])),
+        Value(message),
+      ]));
+    } else {
+      error = X(Construct(cons, [Value(message)]));
+    }
+    return ThrowCompletion(error);
+  }
+
+  queueJob(queueName: string, job: () => void) {
+    const callerContext = this.runningExecutionContext;
+    const callerRealm = callerContext.Realm;
+    const callerScriptOrModule = GetActiveScriptOrModule();
+    const pending: Job = {
+      queueName,
+      job,
+      callerRealm,
+      callerScriptOrModule,
+    };
+    this.jobQueue.push(pending);
+  }
+
+  // NON-SPEC: Check if a feature is enabled in this agent.
+  feature(name: string): boolean {
+    return !!this.hostDefinedOptions.features?.includes(name);
+  }
+
+  // NON-SPEC
+  mark(m: GCMarker) {
+    this.AgentRecord.KeptAlive.forEach((v) => {
+      m(v);
+    });
+    this.executionContextStack.forEach((e) => {
+      m(e);
+    });
+    this.jobQueue.forEach((j) => {
+      m(j.callerRealm);
+      m(j.callerScriptOrModule);
+    });
+  }
+
+  /**
+   * NON-SPEC
+   */
+  #debugger_previewing = false;
+
+  #debugger_objectsCreatedDuringPreview = new Set<ObjectValue>();
+
+  get debugger_isPreviewing() {
+    return this.#debugger_previewing;
+  }
+
+  get debugger_cannotPreview() {
+    if (this.#debugger_previewing) {
+      return ThrowCompletion(X(Construct(this.currentRealmRecord.Intrinsics['%EvalError%'], [Value('Preview evaluator cannot evaluate side-effecting code')])));
+    }
+    return undefined;
+  }
+
+  debugger_tryTouchDuringPreview(object: ObjectValue) {
+    if (this.#debugger_previewing && !this.#debugger_objectsCreatedDuringPreview.has(object)) {
+      return this.debugger_cannotPreview;
+    }
+    return undefined;
+  }
+
+  debugger_markObjectCreated(object: ObjectValue) {
+    if (!this.#debugger_previewing) {
+      return;
+    }
+    this.#debugger_objectsCreatedDuringPreview.add(object);
+  }
+
+  debugger_scopePreview<T>(cb: () => T) {
+    this.#debugger_previewing = true;
+    const res = cb();
+    this.#debugger_previewing = false;
+    this.#debugger_objectsCreatedDuringPreview.clear();
+    return res;
+  }
+}
+
+export let surroundingAgent: Agent;
+export function setSurroundingAgent(a: Agent) {
+  surroundingAgent = a;
+}
+
+/** https://tc39.es/ecma262/#sec-execution-contexts */
+export class ExecutionContext {
+  codeEvaluationState?: YieldEvaluator;
+
+  Function: NullValue | FunctionObject = Value.null;
+
+  Generator?: GeneratorObject | AsyncGeneratorObject;
+
+  ScriptOrModule: AbstractModuleRecord | ScriptRecord | NullValue = Value.null;
+
+  VariableEnvironment!: EnvironmentRecord;
+
+  LexicalEnvironment!: EnvironmentRecord;
+
+  PrivateEnvironment: PrivateEnvironmentRecord | NullValue = Value.null;
+
+  HostDefined?: ParseScriptHostDefined;
+
+  // NON-SPEC
+  callSite = new CallSite(this);
+
+  promiseCapability?: PromiseCapabilityRecord;
+
+  poppedForTailCall = false;
+
+  Realm!: Realm;
+
+  copy() {
+    const e = new ExecutionContext();
+    e.codeEvaluationState = this.codeEvaluationState;
+    e.Function = this.Function;
+    e.Realm = this.Realm;
+    e.ScriptOrModule = this.ScriptOrModule;
+    e.VariableEnvironment = this.VariableEnvironment;
+    e.LexicalEnvironment = this.LexicalEnvironment;
+    e.PrivateEnvironment = this.PrivateEnvironment;
+
+    e.callSite = this.callSite.clone(e);
+    e.promiseCapability = this.promiseCapability;
+    return e;
+  }
+
+  // NON-SPEC
+  mark(m: GCMarker) {
+    m(this.Function);
+    m(this.Realm);
+    m(this.ScriptOrModule);
+    m(this.VariableEnvironment);
+    m(this.LexicalEnvironment);
+    m(this.PrivateEnvironment);
+    m(this.promiseCapability);
+  }
+}
+
+/** https://tc39.es/ecma262/#sec-runtime-semantics-scriptevaluation */
+export function ScriptEvaluation(scriptRecord: ScriptRecord): ExpressionCompletion {
+  if (surroundingAgent.hostDefinedOptions.boost?.evaluateScript) {
+    return surroundingAgent.hostDefinedOptions.boost.evaluateScript(scriptRecord);
+  }
+
+  const globalEnv = scriptRecord.Realm.GlobalEnv;
+  const scriptContext = new ExecutionContext();
+  scriptContext.Function = Value.null;
+  scriptContext.Realm = scriptRecord.Realm;
+  scriptContext.ScriptOrModule = scriptRecord;
+  scriptContext.VariableEnvironment = globalEnv;
+  scriptContext.LexicalEnvironment = globalEnv;
+  scriptContext.PrivateEnvironment = Value.null;
+  scriptContext.HostDefined = scriptRecord.HostDefined;
+  // Suspend runningExecutionContext
+  surroundingAgent.executionContextStack.push(scriptContext);
+  const scriptBody = scriptRecord.ECMAScriptCode;
+  let result: NormalCompletion<void | Value> | ThrowCompletion = EnsureCompletion(GlobalDeclarationInstantiation(scriptBody, globalEnv));
+
+  if (result.Type === 'normal') {
+    result = EnsureCompletion(unwind(Evaluate(scriptBody))) as NormalCompletion<void | Value>;
+
+    if (result.Type === 'normal' && !result.Value) {
+      result = NormalCompletion(Value.undefined);
+    }
+  }
+
+  // Suspend scriptCtx
+  surroundingAgent.executionContextStack.pop(scriptContext);
+  // Resume(surroundingAgent.runningExecutionContext);
+
+  return result as ExpressionCompletion;
+}
+
+/** https://tc39.es/ecma262/#sec-hostenqueuepromisejob */
+export function HostEnqueuePromiseJob(job: () => void, _realm: Realm | NullValue) {
+  surroundingAgent.queueJob('PromiseJobs', job);
+}
+
+/** https://tc39.es/ecma262/#sec-agentsignifier */
+export function AgentSignifier() {
+  // 1. Let AR be the Agent Record of the surrounding agent.
+  const AR = surroundingAgent.AgentRecord;
+  // 2. Return AR.[[Signifier]].
+  return AR.Signifier;
+}
+
+export function HostEnsureCanCompileStrings(callerRealm: Realm, calleeRealm: Realm): PlainCompletion<void> {
+  if (surroundingAgent.hostDefinedOptions.ensureCanCompileStrings !== undefined) {
+    Q(surroundingAgent.hostDefinedOptions.ensureCanCompileStrings(callerRealm, calleeRealm));
+  }
+  return NormalCompletion(undefined);
+}
+
+export function HostPromiseRejectionTracker(promise: PromiseObject, operation: 'reject' | 'handle') {
+  const realm = surroundingAgent.currentRealmRecord;
+  if (realm && realm.HostDefined.promiseRejectionTracker) {
+    X(realm.HostDefined.promiseRejectionTracker(promise, operation));
+  }
+}
+
+export function HostHasSourceTextAvailable(func: FunctionObject) {
+  if (surroundingAgent.hostDefinedOptions.hasSourceTextAvailable) {
+    return X(surroundingAgent.hostDefinedOptions.hasSourceTextAvailable(func));
+  }
+  return Value.true;
+}
+
+// #sec-HostLoadImportedModule
+export function HostLoadImportedModule(referrer: CyclicModuleRecord | ScriptRecord | Realm, specifier: JSStringValue, hostDefined: ModuleRecordHostDefined | undefined, payload: GraphLoadingState | PromiseCapabilityRecord) {
+  if (surroundingAgent.hostDefinedOptions.loadImportedModule) {
+    const executionContext = surroundingAgent.runningExecutionContext;
+    let result: PlainCompletion<AbstractModuleRecord> | undefined;
+    let sync = true;
+    surroundingAgent.hostDefinedOptions.loadImportedModule(referrer, specifier.stringValue(), hostDefined, (res) => {
+      result = res;
+      if (!sync) {
+        // If this callback has been called asynchronously, restore the correct execution context and enqueue a job.
+        surroundingAgent.executionContextStack.push(executionContext);
+        surroundingAgent.queueJob('FinishLoadingImportedModule', () => {
+          result = EnsureCompletion(result);
+          Assert(!!result && (result.Type === 'normal' || result.Type === 'throw'));
+          FinishLoadingImportedModule(referrer, specifier, result, payload);
+        });
+        surroundingAgent.executionContextStack.pop(executionContext);
+        runJobQueue();
+      }
+    });
+    sync = false;
+    if (result !== undefined) {
+      result = EnsureCompletion(result);
+      Assert(result.Type === 'normal' || result.Type === 'throw');
+      FinishLoadingImportedModule(referrer, specifier, result, payload);
+    }
+  } else {
+    FinishLoadingImportedModule(referrer, specifier, surroundingAgent.Throw('Error', 'CouldNotResolveModule', specifier), payload);
+  }
+}
+
+/** https://tc39.es/ecma262/#sec-hostgetimportmetaproperties */
+export function HostGetImportMetaProperties(moduleRecord: AbstractModuleRecord) {
+  const realm = surroundingAgent.currentRealmRecord;
+  if (realm.HostDefined.getImportMetaProperties) {
+    return X(realm.HostDefined.getImportMetaProperties(moduleRecord.HostDefined.public));
+  }
+  return [];
+}
+
+/** https://tc39.es/ecma262/#sec-hostfinalizeimportmeta */
+export function HostFinalizeImportMeta(importMeta: ObjectValue, moduleRecord: AbstractModuleRecord) {
+  const realm = surroundingAgent.currentRealmRecord;
+  if (realm.HostDefined.finalizeImportMeta) {
+    return X(realm.HostDefined.finalizeImportMeta(importMeta, moduleRecord.HostDefined.public));
+  }
+  return Value.undefined;
+}
+
+/** https://tc39.es/ecma262/#sec-host-cleanup-finalization-registry */
+export function HostEnqueueFinalizationRegistryCleanupJob(fg: FinalizationRegistryObject): PlainCompletion<void> {
+  if (surroundingAgent.hostDefinedOptions.cleanupFinalizationRegistry !== undefined) {
+    Q(surroundingAgent.hostDefinedOptions.cleanupFinalizationRegistry(fg));
+  } else {
+    if (!surroundingAgent.scheduledForCleanup.has(fg)) {
+      surroundingAgent.scheduledForCleanup.add(fg);
+      surroundingAgent.queueJob('FinalizationCleanup', () => {
+        surroundingAgent.scheduledForCleanup.delete(fg);
+        CleanupFinalizationRegistry(fg);
+      });
+    }
+  }
+  return NormalCompletion(undefined);
+}
+
+export interface JobCallbackRecord {
+  Callback: FunctionObject & { [kAsyncContext]?: ExecutionContext; };
+  HostDefined: undefined;
+}
+/** https://tc39.es/ecma262/#sec-hostmakejobcallback */
+export function HostMakeJobCallback(callback: FunctionObject): JobCallbackRecord {
+  // 1. Assert: IsCallable(callback) is true.
+  Assert(IsCallable(callback) === Value.true);
+  // 2. Return the JobCallback Record { [[Callback]]: callback, [[HostDefined]]: empty }.
+  return { Callback: callback, HostDefined: undefined };
+}
+
+/** https://tc39.es/ecma262/#sec-hostcalljobcallback */
+export function HostCallJobCallback(jobCallback: JobCallbackRecord, V: Value, argumentsList: Arguments): ExpressionCompletion {
+  // 1. Assert: IsCallable(jobCallback.[[Callback]]) is true.
+  Assert(IsCallable(jobCallback.Callback) === Value.true);
+  // 1. Return ? Call(jobCallback.[[Callback]], V, argumentsList).
+  return Q(Call(jobCallback.Callback, V, argumentsList));
+}
+export type GCMarker = (value: unknown) => void;
+export interface Markable {
+  mark(marker: GCMarker): void;
+}
+export interface Job {
+  readonly queueName: string;
+  readonly job: () => void;
+  readonly callerRealm: Realm;
+  readonly callerScriptOrModule: AbstractModuleRecord | ScriptRecord | NullValue;
+}