@engine262/engine262 0.0.1-01e9fa95a4e8a1c042efd00492309a2de4998fd0

package/lib-src/node/bin.mts

@@ -0,0 +1,339 @@
+#!/usr/bin/env node
+
+import { start } from 'node:repl';
+import { readFileSync, writeSync } from 'node:fs';
+import { resolve } from 'node:path';
+import {
+  format as _format, inspect as _inspect, parseArgs, styleText,
+} from 'node:util';
+// let's try if the following message on old node causes test failure on test262.fyi
+// "ExperimentalWarning: Importing JSON modules is an experimental feature and might change at any time"
+// import packageJson from '../../package.json' with { type: 'json' };
+import { createRequire } from 'node:module';
+import { createConsole } from '../inspector/utils.mts';
+import type { NodeWebsocketInspector } from './inspector.mts';
+import { fileSystemModuleLoader } from './module.mts';
+import {
+  setSurroundingAgent, FEATURES, inspect, Value,
+  type Arguments,
+  Agent,
+  ManagedRealm,
+  createTest262Intrinsics,
+  surroundingAgent,
+  ThrowCompletion,
+  ValueOfNormalCompletion,
+  type PlainEvaluator,
+  importBundledTest262Harness,
+  boostTest262Harness,
+  ModuleCache,
+  PerformPromiseThen,
+  CreateBuiltinFunction,
+  composeModuleLoaders,
+  Descriptor,
+  isFunctionObject,
+  Throw,
+  ToNumber,
+  R,
+  Call,
+  GetActiveScriptOrModule,
+  type PlainCompletion,
+  NormalCompletion,
+  type PromiseObject,
+} from '#self';
+
+const packageJson = createRequire(import.meta.url)('../../package.json');
+const writeStdout = (text: string) => writeSync(process.stdout.fd, text);
+const writeStderr = (text: string) => writeSync(process.stderr.fd, text);
+const help = () => `
+engine262 v${packageJson.version}
+
+Usage:
+
+    engine262 [options]
+    engine262 [options] [input file]
+    engine262 [input file]
+
+Options:
+  ${((str) => {
+    const options = [
+      ['-h, --help', 'Show help'],
+      ['-m, --module', 'Evaluate contents of input-file as a module.'],
+      ['-e, --eval', 'Evaluate the given string. (can be used with --module)'],
+      ['--features=...', 'A comma separated list of features.'],
+      ['-a, --features=all', 'Enable all features.'],
+      ['--no-test262', 'Do not expose $ and $262 for test262.'],
+      ['--[no-]inspect', 'Do [not] attach an inspector.'],
+      ['--no-preview', 'Do not enable preview in the inspector.'],
+      ['-t, --test262-harness', 'Import test262 harness files.'],
+    ];
+    const maxOptionLength = options.reduce((max, [flag]) => Math.max(max, flag.length), 0);
+    options.forEach(([flag, description]) => {
+      str += `    ${styleText('green', flag.padEnd(maxOptionLength))}  ${description}\n`;
+    });
+    return str;
+  })('\n')}
+Features:
+  ${((str) => {
+    const supportColor = styleText('red', 'test') !== 'test';
+    function link(text: string, url: string) {
+      if (!supportColor || !url) return text;
+      const OSC = '\u001B]';
+      const BEL = '\u0007';
+      return `${OSC}8;;${url}${BEL}${text}${OSC}8;;${BEL}`;
+    }
+
+    let maxFlagLength = 0;
+    for (const f of FEATURES) {
+      if (f.flag.length > maxFlagLength) maxFlagLength = f.flag.length;
+    }
+    FEATURES.forEach((f) => {
+      str += `    ${styleText('redBright', f.flag.padEnd(maxFlagLength))}  ${link(f.name, f.url)}\n`;
+    });
+    return str;
+  })('\n')}
+`;
+
+const argv = parseArgs({
+  args: process.argv.slice(2),
+  allowPositionals: true,
+  allowNegative: true,
+  strict: true,
+  options: {
+    'help': { type: 'boolean', short: 'h' },
+    'eval': { type: 'string', short: 'e' },
+    'module': { type: 'boolean', short: 'm' },
+    'features': { type: 'string' },
+    'features-all': { type: 'boolean', short: 'a' },
+    'inspect': { type: 'boolean' },
+    'test262': { type: 'boolean', default: true },
+    'test262-harness': { type: 'boolean', short: 't' },
+    // hidden options
+    'preview-debug': { type: 'boolean' },
+  },
+});
+
+if (argv.values.help) {
+  writeStdout(help());
+  process.exit(0);
+}
+
+let features: string[];
+if (argv.values.features === 'all' || argv.values['features-all']) {
+  features = FEATURES.map((f) => f.flag);
+} else if (argv.values.features) {
+  features = argv.values.features.split(',');
+} else {
+  features = [];
+}
+
+// exit code 1 if at least 1 unhandled rejection in the end.
+let unhandledExceptionCount = 0;
+process.on('exit', () => {
+  if (unhandledExceptionCount > 0) process.exitCode = 1;
+});
+const unhandledRejectionPendingLog = new Set<PromiseObject>();
+
+const agent = new Agent({
+  features,
+  supportedImportAttributes: ['type'],
+  hostHooks: {
+    HostLoadImportedModule: composeModuleLoaders([fileSystemModuleLoader]),
+    HostPromiseRejectionTrackers: new Set([(promise, operation) => {
+      if (operation === 'reject') {
+        unhandledExceptionCount += 1;
+        unhandledRejectionPendingLog.add(promise);
+        const realm = surroundingAgent.currentRealmRecord as ManagedRealm;
+        setTimeout(() => {
+          if (!unhandledRejectionPendingLog.has(promise)) return;
+          unhandledRejectionPendingLog.delete(promise);
+          const pop = realm.pushTopContext();
+          const err = inspect(promise.PromiseResult!);
+          pop?.();
+          writeStderr(`Unhandled promise rejection: ${err}\n`);
+        }, 10);
+      } else if (operation === 'handle') {
+        unhandledExceptionCount -= 1;
+        unhandledRejectionPendingLog.delete(promise);
+      }
+    }]),
+  },
+  uncaughtExceptionTrackers: new Set([(error) => {
+    unhandledExceptionCount += 1;
+    const pop = realm.pushTopContext();
+    const err = inspect(error);
+    pop?.();
+    writeStderr(`Uncaught exception: ${err}\n`);
+  }]),
+});
+setSurroundingAgent(agent);
+
+const realm = new ManagedRealm({ resolverCache: new ModuleCache(), name: 'repl', specifier: process.cwd() });
+{
+  const pop = realm.pushTopContext();
+  realm.GlobalObject.properties.set('setTimeout', Descriptor({
+    Value: CreateBuiltinFunction.from(function* timeout(f = Value.undefined, time = Value.undefined) {
+      if (!isFunctionObject(f)) return Throw.TypeError('setTimeout($1, ...) should be a function', f);
+      const delay = yield* ToNumber(time);
+      if (delay instanceof ThrowCompletion) return delay;
+      const delayTime = R(ValueOfNormalCompletion(delay));
+
+      const job = {
+        queueName: 'setTimeout resolve',
+        job: () => Call(f, Value.undefined, []),
+        callerRealm: surroundingAgent.runningExecutionContext.Realm,
+        callerScriptOrModule: GetActiveScriptOrModule(),
+      };
+      surroundingAgent.eventLoop.enqueueAsync('timers', job, (enqueue) => {
+        setTimeout(enqueue, delayTime);
+      });
+      return Value.undefined;
+    }),
+  }));
+  pop?.();
+}
+
+// Define console.log
+{
+  const format = (function* format(args: Arguments): PlainEvaluator<string> {
+    const str = [];
+    for (const arg of args.values()) {
+      // TODO: inspect should return a PlainEvaluator so debugger can hook in.
+      str.push(inspect(arg));
+    }
+    return str.join(' ');
+  });
+  createConsole(realm, {
+    * log(args) {
+      writeStdout(`${yield* format(args)}\n`);
+    },
+    * error(args) {
+      writeStderr(`${yield* format(args)}\n`);
+    },
+    * debug(args) {
+      writeStderr(`${yield* format(args)}\n`);
+    },
+  });
+}
+
+if (argv.values.test262) {
+  // eslint-disable-next-line no-console
+  createTest262Intrinsics(realm, argv.values.test262, (...args) => {
+    writeStdout(`${_format(...args)}\n`);
+  });
+}
+
+if (argv.values['test262-harness']) {
+  importBundledTest262Harness(realm);
+  boostTest262Harness(realm);
+}
+
+async function setupInspector(mode: 'file' | 'eval' | 'pipe' | 'repl') {
+  const inspectArg = argv.values.inspect;
+  if (mode !== 'repl' && !inspectArg) return undefined;
+  if (inspectArg === false) return undefined;
+
+  let has_ws = false;
+  try {
+    await import('ws');
+    has_ws = true;
+  } catch {
+    if (inspectArg) {
+      writeStderr('--inspect requires the "ws" package to be installed.\n');
+      process.exit(1);
+    }
+  }
+  if (!has_ws) return undefined;
+  const { NodeWebsocketInspector } = await import('./inspector.mts');
+  const inspector = await NodeWebsocketInspector.new();
+  inspector.attachAgent(surroundingAgent, [realm]);
+  inspector.preference.previewDebug = argv.values['preview-debug'] || false;
+  writeStdout([
+    `Inspector attached at 127.0.0.1:${inspector.port}${inspectArg ? '' : ', use --no-inspect to disable'}`,
+    'Paste this URL into Chromium to open DevTools:',
+    `    ${inspector.devtoolsFrontendUrl}`,
+    '\n',
+  ].join('\n'));
+  return inspector;
+}
+
+
+function oneShotEval(inspector: NodeWebsocketInspector | undefined, source: string, filename: string) {
+  if (argv.values.module || filename.endsWith('.mjs')) {
+    realm.evaluateModule(source, filename, (promise) => {
+      if (promise instanceof ThrowCompletion) {
+        handleResult(promise);
+        return;
+      }
+      PerformPromiseThen(ValueOfNormalCompletion(promise), Value.null, CreateBuiltinFunction.from((error = Value.undefined) => {
+        handleResult(ThrowCompletion(error));
+      }));
+    });
+  } else {
+    realm.evaluateScript(source, { specifier: filename }, (completion) => {
+      handleResult(completion);
+    });
+  }
+
+
+  function handleResult(completion: PlainCompletion<void | Value>) {
+    if (completion instanceof ThrowCompletion) {
+      const pop = surroundingAgent.hasRunningExecutionContext ? undefined : realm.pushTopContext();
+      const inspected = inspect(completion);
+      pop?.();
+      writeStderr(`${inspected}\n`);
+      unhandledExceptionCount += 1;
+    }
+    // Note: we don't have exit callback (process.on('beforeExit')), so it is impossible
+    // to have more code running after onNoPendingJob is fired.
+    surroundingAgent.eventLoop.onNoPendingJob.add(() => {
+      inspector?.stop();
+    });
+  }
+}
+
+if (argv.positionals[0]) {
+  const inspector = await setupInspector('file');
+  const source = readFileSync(argv.positionals[0], 'utf8');
+  oneShotEval(inspector, source, resolve(argv.positionals[0]));
+} else if (argv.values.eval) {
+  const inspector = await setupInspector('eval');
+  oneShotEval(inspector, argv.values.eval, '<eval>');
+} else if (!process.stdin.isTTY) {
+  const inspector = await setupInspector('pipe');
+  process.stdin.setEncoding('utf8');
+  let source = '';
+  process.stdin.on('data', (data) => {
+    source += data;
+  });
+  process.stdin.once('end', () => {
+    oneShotEval(inspector, source, '<pipe>');
+  });
+} else {
+  const inspector = await setupInspector('repl');
+  writeStdout(`Welcome to ${packageJson.name} v${String(packageJson.version).replace('0.0.1-', '')} Please report bugs to ${packageJson.bugs.url}\nType ".help" for more information.\n`);
+  const server = start({
+    prompt: '> ',
+    eval: (cmd, _context, _filename, callback) => {
+      try {
+        realm.evaluateScript(cmd, {}, (completion) => {
+          callback(null, completion);
+        });
+      } catch (e) {
+        callback(e as Error, null);
+      }
+    },
+    preview: false,
+    writer: (o) => {
+      if (o instanceof ThrowCompletion) o = o.Value;
+      if (o instanceof NormalCompletion && o.Value instanceof Value) o = o.Value;
+      let out;
+      const pop = realm.pushTopContext();
+      if (o instanceof Value) out = o === Value.undefined ? '' : inspect(o);
+      else out = _inspect(o);
+      pop?.();
+      return out;
+    },
+  });
+
+  server.on('exit', () => surroundingAgent.eventLoop.onNoPendingJob.add(() => inspector?.stop()));
+}

package/lib-src/node/example.mts

@@ -0,0 +1,173 @@
+/* eslint-disable no-console */
+import { NodeWebsocketInspector } from './inspector.mts';
+import { fileSystemModuleLoader } from './module.mts';
+import {
+  Agent, composeModuleLoaders, CreateBuiltinFunction, createBuiltinModuleLoader, EnsureCompletion, inspect, ManagedRealm, ModuleCache, ModuleEnvironmentRecord, PerformPromiseThen, setSurroundingAgent, surroundingAgent, SyntheticModuleRecord, ThrowCompletion, ToString, X, Value, ValueOfNormalCompletion, type Arguments, type PlainEvaluator,
+  type ValueCompletion,
+  CreateNonEnumerableDataPropertyOrThrow,
+  Throw,
+  IsCallable,
+  type Job,
+  GetActiveScriptOrModule,
+  Call,
+  NumberValue,
+} from '#self';
+import { createConsole } from '#self/inspector';
+
+// Agent is the running environment.
+const agent = new Agent({
+  uncaughtExceptionTrackers: new Set([(error) => {
+    console.error('Uncaught exception:', inspect(error));
+  }]),
+  hostHooks: {
+    HostLoadImportedModule: composeModuleLoaders([
+      fileSystemModuleLoader,
+      createBuiltinModuleLoader({
+        builtinModules: new Map([[{ Specifier: 'builtin', Attributes: [] }, (realm) => {
+          const env = new ModuleEnvironmentRecord(null);
+          const module = new SyntheticModuleRecord({
+            Environment: env,
+            ExportNames: [Value('foo')],
+            EvaluationSteps() {
+              // Create built-in function
+              const foo = CreateBuiltinFunction.from(function* foo(value = Value.undefined) {
+                console.log('Native function foo called with argument:', inspect(yield* ToString(value)));
+              }, 'foo');
+              X(module.SetSyntheticExport(Value('foo'), foo));
+              console.log('Builtin module evaluated');
+            },
+            HostDefined: {},
+            Namespace: undefined,
+            ModuleSource: undefined,
+            Realm: realm,
+          });
+          return module;
+        }]]),
+      }),
+    ]),
+  },
+});
+// Only one agent can be active at a time.
+setSurroundingAgent(agent);
+
+// A Realm is a separate global environment.
+// In Web browsers, each iframe has its own Realm and they may interact with each other.
+const realm = new ManagedRealm({ resolverCache: new ModuleCache(), name: 'My Realm', specifier: process.cwd() });
+
+// Define console.log
+{
+  const format = (function* format(args: Arguments): PlainEvaluator<string> {
+    const str = [];
+    for (const arg of args.values()) {
+      str.push(inspect(arg));
+    }
+    return str.join(' ');
+  });
+  createConsole(realm, {
+    * log(args) {
+      process.stdout.write(`${yield* format(args)}\n`);
+    },
+    * error(args) {
+      process.stderr.write(`${yield* format(args)}\n`);
+    },
+    * debug(args) {
+      process.stderr.write(`${yield* format(args)}\n`);
+    },
+    * default(method, args) {
+      process.stdout.write(`[console.${method}] ${yield* format(args)}\n`);
+    },
+  });
+}
+
+// Create a new inspector (devtools console)
+const inspector = await NodeWebsocketInspector.new();
+
+function printResult(value: ValueCompletion) {
+  const pop = realm.pushTopContext();
+  if (value instanceof ThrowCompletion) {
+    console.error('Error: ', inspect(value.Value));
+  } else {
+    console.log('Result:', inspect(ValueOfNormalCompletion(value)));
+  }
+  pop?.();
+}
+
+// Run a script and skip debugger infra (get the result synchronously).
+{
+  console.log('--------- evaluateScriptSkipDebugger ---------');
+  const result = EnsureCompletion(realm.evaluateScriptSkipDebugger(`
+    console.log('Hello from engine262!');
+    console.log('2 + 2 =', 2 + 2);
+  `, { specifier: 'example.mjs' }));
+  printResult(result);
+}
+
+// Run the jobQueue (Promise/other tasks).
+{
+  console.log('--------- jobQueue ---------');
+  const result = EnsureCompletion(realm.evaluateScriptSkipDebugger(`
+    Promise.resolve('Hello from Promise!').then(console.log);
+  `, { specifier: 'example2.mjs' }));
+
+  // define an async built-in function
+  const pop = realm.pushTopContext();
+  const sleep = CreateBuiltinFunction.from(function* sleep(ms = Value.undefined, callback = Value.undefined) {
+    if (!(ms instanceof NumberValue)) return Throw.TypeError('First argument must be a number');
+    if (!IsCallable(callback)) return Throw.TypeError('Second argument must be a function');
+    const job: Job = {
+      queueName: 'setTimeout',
+      callerRealm: surroundingAgent.currentRealmRecord,
+      callerScriptOrModule: GetActiveScriptOrModule(),
+      job: function* setTimeoutResolve() {
+        return yield* Call(callback, Value.undefined, []);
+      },
+    };
+    surroundingAgent.eventLoop.enqueueAsync('timers', job, (enqueue) => {
+      setTimeout(enqueue, ms.value);
+    });
+    return Value.undefined;
+  }, 'sleep');
+  X(CreateNonEnumerableDataPropertyOrThrow(realm.GlobalObject, Value('sleep'), sleep));
+  pop?.();
+
+  const result2 = realm.evaluateScriptSkipDebugger(`
+    sleep(500, () => console.log('Hello from sleep!'));
+  `, { specifier: 'example3.mjs' });
+  printResult(result);
+  printResult(result2);
+}
+
+inspector.attachAgent(surroundingAgent, [realm]);
+// Run a script with debugger support
+// the evaluation may be sync or async.
+console.log('--------- evaluateScript ---------');
+realm.evaluateScript(`
+  function f() { debugger; return 1; }
+  f();
+`, { specifier: 'vm://1' }, (result) => {
+  printResult(result);
+});
+// resume from the debugger;
+surroundingAgent.resumeEvaluate();
+
+// Run a module
+console.log('--------- evaluateModule ---------');
+realm.evaluateModule(`
+  import { foo } from "builtin";
+  foo({ toString() { return "X" } });
+`, undefined, (result) => {
+  if (result instanceof ThrowCompletion) {
+    console.error('Module evaluate error: ', inspect(result.Value));
+  } else {
+    PerformPromiseThen(
+      ValueOfNormalCompletion(result),
+      CreateBuiltinFunction.from(() => {
+        console.log('Module evaluated successfully');
+      }),
+      CreateBuiltinFunction.from((error = Value.undefined) => {
+        console.error('Module evaluation error:', inspect(error));
+      }),
+    );
+  }
+});
+inspector.stop();

package/lib-src/node/inspector.mts

@@ -0,0 +1,152 @@
+import http from 'node:http';
+import https from 'node:https';
+import { WebSocketServer, type AddressInfo } from 'ws';
+import packageJson from '../../package.json' with { type: 'json' };
+// Note: typescript will not copy json files, so it will not appear in the lib directory
+import protocol from '../../lib-src/inspector/js_protocol.json' with { type: 'json' };
+import { Inspector } from '../inspector/index.mts';
+
+const ANSI = {
+  reset: '\u001b[0m',
+  red: '\u001b[31m',
+  green: '\u001b[32m',
+  yellow: '\u001b[33m',
+  blue: '\u001b[34m',
+};
+
+export class NodeWebsocketInspector extends Inspector {
+  _server: http.Server | https.Server;
+
+  _ws: WebSocketServer;
+
+  isDebug = false;
+
+  protected override send(data: object): void {
+    const s = JSON.stringify(data);
+    this._ws.clients.forEach((ws) => {
+      ws.send(s);
+    });
+  }
+
+  protected constructor(httpServer: http.Server | https.Server, isDebug: boolean) {
+    super();
+    this._server = httpServer;
+    httpServer.on('request', this.onRequest);
+    const websocketServer = new WebSocketServer({ server: httpServer });
+    this._ws = websocketServer;
+    websocketServer.on('connection', (ws) => {
+      const send = (obj: unknown) => {
+        const s = JSON.stringify(obj);
+        ws.send(s);
+      };
+
+      const sendEvent = Object.create(new Proxy({}, {
+        get: (_, key: string) => {
+          const f = (params: Record<string, unknown>) => {
+            send({ method: key, params });
+          };
+          Object.defineProperty(sendEvent, key, { value: key });
+          return f;
+        },
+      }));
+
+      ws.on('message', (data: string) => {
+        const { id, method, params } = JSON.parse(data);
+        if (isDebug) {
+          process.stdout.write(`${ANSI.green}${method}${ANSI.reset}: ${JSON.stringify(params)}\n`);
+        }
+        this.onMessage(id, method, params);
+      });
+      ws.on('close', () => {
+        this.onDebuggerDisconnect();
+      });
+    });
+  }
+
+  get devtoolsFrontendUrl() {
+    return `devtools://devtools/bundled/js_app.html?experiments=true&v8only=true&ws=localhost:${this.port}`;
+  }
+
+  private onRequest = (req: http.IncomingMessage, res: http.ServerResponse<http.IncomingMessage>) => {
+    if (req.method !== 'GET') {
+      res.writeHead(405);
+      res.end();
+      return;
+    }
+
+    const json = (obj: unknown) => {
+      const s = JSON.stringify(obj);
+      res.writeHead(200, {
+        'Content-Type': 'application/json',
+        'Content-Length': Buffer.byteLength(s),
+      });
+      res.end(s);
+    };
+
+    switch (req.url) {
+      case '/json':
+      case '/json/list': {
+        const devtoolsFrontendUrl = this.devtoolsFrontendUrl;
+        json([{
+          description: `${packageJson.name} instance`,
+          devtoolsFrontendUrl,
+          devtoolsFrontendUrlCompat: devtoolsFrontendUrl,
+          faviconUrl: 'https://avatars0.githubusercontent.com/u/51185628',
+          id: 'inspector.0',
+          title: 'engine262',
+          type: 'node',
+          url: `file://${process.cwd()}`,
+          webSocketDebuggerUrl: `ws://localhost:${this.port}/`,
+        }]);
+        break;
+      }
+      case '/json/version':
+        json({
+          'Browser': `${packageJson.name}/v${packageJson.version}`,
+          'Protocol-Version': `${protocol.version.major}.${protocol.version.minor}`,
+        });
+        break;
+      case '/json/protocol':
+        json(protocol);
+        break;
+      default:
+        res.writeHead(404);
+        res.end();
+        break;
+    }
+  };
+
+  get port() {
+    return (this._server.address() as AddressInfo).port;
+  }
+
+  static async new(port: number | 'auto' = 'auto', host = '127.0.0.1', isDebug = !!process.env.DEBUG) {
+    const server = http.createServer();
+    await new Promise<void>((resolve, reject) => {
+      if (typeof port === 'number') {
+        server.listen(port, host, () => {
+          resolve();
+        });
+      } else {
+        server.once('error', (error: NodeJS.ErrnoException) => {
+          if (error.code !== 'EADDRINUSE') {
+            reject(error);
+            return;
+          }
+
+          server.listen(0, host, () => {
+            resolve();
+          });
+        }).listen(9229, host, () => {
+          resolve();
+        });
+      }
+    });
+    return new NodeWebsocketInspector(server, isDebug);
+  }
+
+  stop() {
+    this._server.close();
+    this._ws.close();
+  }
+}