When Eval Becomes an Execution Engine

The string‑to‑program façade

lib/internal/process/execution.js is Node’s execution façade: a thin layer that hides a web of loaders, VM helpers, and process‑lifecycle hooks behind a small public surface. Instead of everyone poking at vm, ESM loaders, and process exit logic directly, this module offers a few focused entry points:

• evalScript — evaluate CommonJS‑style scripts.
• evalModuleEntryPoint — evaluate ESM entry points.
• evalTypeScript and helpers — TypeScript‑aware versions of those flows.
• createOnGlobalUncaughtException() — the process‑wide error dispatcher.

project-root/
  lib/
    internal/
      process/
        execution.js   <-- eval & uncaught exception orchestration
      modules/
        cjs/
          loader.js     (CommonJS loader)
        esm/
          loader.js     (ESM loader & dynamic imports)
        typescript.js   (stripTypeScriptModuleTypes)
      vm.js             (ContextifyScript, runScriptInThisContext)
      async_hooks.js    (async context & after hooks)
  src/
    node_errors.cc      (C++: error/exit wiring)
    module_wrap.cc      (C++: module wrap phases)

You can treat this file as Node’s “string‑to‑running‑program” switchboard: it decides how a chunk of text becomes live JavaScript or TypeScript, and how fatal errors from that code affect the whole process.

Choosing between ESM and CommonJS

The first decision the façade makes is whether a given input should run as a script (CommonJS) or as a module (ESM). That logic is centralized in shouldUseModuleEntryPoint:

function shouldUseModuleEntryPoint(name, body) {
  return getOptionValue('--experimental-detect-module') &&
    getOptionValue('--input-type') === '' &&
    containsModuleSyntax(body, name, null, 'no CJS variables');
}

This tells us:

1. Detection is opt‑in via --experimental-detect-module.
2. It only applies for the default --input-type (empty string).
3. It delegates syntax scanning to containsModuleSyntax in the VM layer.

Once the mode is chosen, the façade routes to the right backend. For ESM, that’s evalModuleEntryPoint:

function evalModuleEntryPoint(source, print) {
  if (print) {
    throw new ERR_EVAL_ESM_CANNOT_PRINT();
  }
  RegExpPrototypeExec(/^/, ''); // Reset RegExp statics before user code.
  return require('internal/modules/run_main').runEntryPointWithESMLoader(
    (loader) => loader.eval(source, getEvalModuleUrl(), true),
  );
}

Even this small helper enforces two invariants:

• Behavior contracts are explicit: printing is disallowed for ESM evals and rejected via ERR_EVAL_ESM_CANNOT_PRINT instead of silently doing something surprising.
• Runtime state is sanitized: RegExpPrototypeExec(/^/, '') resets RegExp statics before any user code runs, avoiding subtle leakage across evals.

That sets up the main theme of this module: centralized control over how strings enter the runtime and which invariants must hold around each execution.

TypeScript as a two‑pass translator

On top of plain JavaScript, this façade also acts as a two‑pass translator for TypeScript. The core behavior lives in evalTypeScript, which follows a strict template:

1. Try to compile and run the code as‑is.
2. If the engine chokes on TS syntax, strip types and try again.
3. If the strip/compile step fails with a TS‑specific error, splice that diagnostic into the original error and rethrow the original.

function evalTypeScript(name, source, breakFirstLine, print, shouldLoadESM = false) {
  const origModule = globalThis.module;
  const module = createModule(name);
  const baseUrl = pathToFileURL(module.filename).href;

  if (shouldUseModuleEntryPoint(name, source)) {
    return evalTypeScriptModuleEntryPoint(source, print);
  }

  let compiledScript;
  let sourceToRun = source;
  try {
    compiledScript = compileScript(name, source, baseUrl);
  } catch (originalError) {
    try {
      sourceToRun = stripTypeScriptModuleTypes(source, kEvalTag);
      if (shouldUseModuleEntryPoint(name, sourceToRun)) {
        return evalTypeScriptModuleEntryPoint(source, print);
      }
      compiledScript = compileScript(name, sourceToRun, baseUrl);
    } catch (tsError) {
      if (tsError.code === 'ERR_INVALID_TYPESCRIPT_SYNTAX' ||
          tsError.code === 'ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX') {
        originalError.stack =
          decorateCJSErrorWithTSMessage(originalError.stack, tsError.message);
        throw originalError;
      }
      throw tsError;
    }
  }

  const evalFunction = () => runScriptInContext(
    name,
    sourceToRun,
    breakFirstLine,
    print,
    module,
    baseUrl,
    compiledScript,
    origModule,
  );

  if (shouldLoadESM) {
    return require('internal/modules/run_main')
      .runEntryPointWithESMLoader(evalFunction);
  }
  evalFunction();
}

The control flow is intricate, but the policy is clear:

• Error identity is stable: the original error object is rethrown; only its stack trace is enriched with TS information.
• Fallback is scoped: only TS‑specific syntax errors (ERR_INVALID_TYPESCRIPT_SYNTAX, ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX) trigger decoration. Other failures surface as they are.
• Mode detection is revisited: after stripping types, shouldUseModuleEntryPoint is run again because types can hide or change ESM syntax.

Decorating the error, not replacing it

Instead of inventing a separate “TypeScript error” abstraction, the engine augments existing CommonJS errors using decorateCJSErrorWithTSMessage:

function decorateCJSErrorWithTSMessage(originalStack, newMessage) {
  let index;
  for (let i = 0; i < 3; i++) {
    index = StringPrototypeIndexOf(originalStack, '\n', index + 1);
  }
  return StringPrototypeSlice(originalStack, 0, index) +
         '\n' + newMessage +
         StringPrototypeSlice(originalStack, index);
}

In prose: find the third line of the stack trace, inject the TypeScript diagnostic right after it, and leave the rest untouched. Callers still see the familiar error type and stack, but with an extra line of TS context near the top.

This shows how to integrate a secondary tool (like a transpiler or linter) into an existing error model without breaking consumers: keep the original error as the primary carrier, and treat the secondary tool as a source of annotations.

Optimistic vs declared TypeScript modes

When the engine knows upfront that the input is TypeScript (via CLI --input-type), it skips the optimistic “try raw JS first” step and goes straight to stripping and running:

function parseAndEvalModuleTypeScript(source, print) {
  const strippedSource = stripTypeScriptModuleTypes(source, kEvalTag);
  evalModuleEntryPoint(strippedSource, print);
}

function parseAndEvalCommonjsTypeScript(name, source, breakFirstLine, print, shouldLoadESM = false) {
  const strippedSource = stripTypeScriptModuleTypes(source, kEvalTag);
  evalScript(name, strippedSource, breakFirstLine, print, shouldLoadESM);
}

That split captures a general rule: when the user explicitly declares a mode, do the minimal work that’s consistent with that declaration; when they don’t, try the cheaper interpretation first, then fall back to more expensive translations.

The global emergency exit

So far we’ve followed how code flows into the engine. The other axis of control is what happens when that code throws an error nobody catches. createOnGlobalUncaughtException is where this file turns into a process‑level safety system: it builds the function that C++ calls (via process._fatalException) to decide whether JS handled a fatal error or the process must die.

function createOnGlobalUncaughtException() {
  return (er, fromPromise) => {
    clearDefaultTriggerAsyncId();

    const type = fromPromise ? 'unhandledRejection' : 'uncaughtException';
    process.emit('uncaughtExceptionMonitor', er, type);
    if (exceptionHandlerState.captureFn !== null) {
      exceptionHandlerState.captureFn(er);
    } else if (!process.emit('uncaughtException', er, type)) {
      try {
        if (!process._exiting) {
          process._exiting = true;
          process.exitCode = kGenericUserError;
          process.emit('exit', kGenericUserError);
        }
      } catch {
        // Already unrecoverable.
      }
      return false;
    }

    require('timers').setImmediate(noop);

    if (afterHooksExist()) {
      do {
        const asyncId = executionAsyncId();
        if (asyncId === 0)
          popAsyncContext(0);
        else
          emitAfter(asyncId);
      } while (hasAsyncIdStack());
    }
    clearAsyncIdStack();

    return true;
  };
}

This dispatcher runs in three distinct phases:

Capture callbacks as a controlled escape hatch

The uncaught exception capture API is intentionally narrow. Through setUncaughtExceptionCaptureCallback and hasUncaughtExceptionCaptureCallback, Node enforces:

• Only one capture callback may exist; setting a second throws ERR_UNCAUGHT_EXCEPTION_CAPTURE_ALREADY_SET.
• The callback must be a function or null; any other type is rejected with ERR_INVALID_ARG_TYPE.
• Setting (or clearing) the callback coordinates with C++ via a shared toggle (shouldAbortOnUncaughtToggle[0]) so the native side knows whether to abort on uncaught errors.

This is a good example of designing a global escape hatch with a tight contract: single registration, explicit types, and synchronized behavior across JS and native layers.

Eval performance and sharp edges

Under load, this module is not a classic micro‑optimization hot path, but it still has to behave predictably: it may see many small CLI or REPL snippets, repeated TypeScript evals, and bursts of uncaught errors from unstable applications. Its main cost centers are straightforward: compilation and TS stripping are both linear in source size, and execution cost is entirely determined by user code.

The most interesting performance‑adjacent function here is runScriptInContext, which bridges the façade into the CommonJS runtime:

function runScriptInContext(name, body, breakFirstLine, print, module, baseUrl, compiledScript, origModule) {
  const script = `
      globalThis.module = module;
      globalThis.exports = exports;
      globalThis.__dirname = __dirname;
      globalThis.require = require;
      return (main) => main();
    `;
  globalThis.__filename = name;
  RegExpPrototypeExec(/^/, '');
  const result = module._compile(script, `${name}-wrapper`)(() => {
    return runScriptInThisContext(
      compiledScript ?? compileScript(name, body, baseUrl),
      true, !!breakFirstLine);
  });
  if (print) {
    const { log } = require('internal/console/global');
    process.on('exit', () => { log(result); });
  }
  if (origModule !== undefined)
    globalThis.module = origModule;
}

This wrapper does two key things:

• It creates a tiny CommonJS “bubble” by wiring module, exports, __dirname, __filename, and require onto globalThis, then compiling a wrapper that calls into runScriptInThisContext.
• It optionally hooks into process.on('exit') to print the result for CLI use cases (for example, node -p behavior).

Beyond individual helpers, the report behind this analysis suggests a set of metrics that generalize to any system that evaluates arbitrary code or expressions. For an eval engine, you’d want at least:

• A duration metric per eval (e.g., bucketed latency by input size).
• A metric for input size distribution (to detect unexpectedly huge scripts).
• A counter for global‑handler invocations (equivalent to how often the uncaught exception dispatcher fires).
• A counter for TypeScript strip‑and‑retry attempts, as a proxy for how rough the TS path is.

The broader pattern: every powerful “execute this string” capability should ship with visibility into how long calls take, how big the inputs are, and how often they end in global‑level failure.

Takeaways for your own engines

Stepping back, this file shows how Node treats eval not as a throwaway helper but as an execution engine with clear contracts around modes, translations, and failure. The primary lesson is: if your system evaluates code or expressions, wrap that capability in a focused façade that owns mode selection, translation retries, and global error handling.

1. Treat eval‑like features as first‑class products

Any place you accept user code, configuration expressions, or templates deserves its own façade, similar to Node’s evalScript/evalTypeScript pair. That façade should:

• Normalize inputs (mode selection, base URLs, flags).
• Reset or isolate process‑wide state that can leak across runs.
• Define how errors are surfaced and when they escalate to global failure.

2. Retry with more context, not different semantics

Node’s TypeScript flow illustrates a safe retry pattern: when the first attempt fails for a specific, recognized reason, retry after transformation (strip types) but keep the original error as the primary signal and only enrich its diagnostics. You can use the same pattern for things like minifiers, linters, or alternate parsers.

3. Centralize your “emergency exit”

Rather than sprinkling process exits or global aborts throughout your codebase, follow createOnGlobalUncaughtException and route catastrophic errors into a single dispatcher that:

• Classifies the failure and emits monitoring signals.
• Gives specialized handlers a chance to intervene.
• Makes one final, centralized decision about whether the system continues or shuts down.

4. Be transactional with global state

When you must patch globals for convenience (like globalThis.module and friends), snapshot the old values, apply your mutations, and always restore them. Even in an internal module, partial restoration—like we saw in runScriptInContext—is a source of subtle cross‑eval interference.

5. Pair sharp edges with guardrails and observability

Dynamic evaluation, TypeScript translation, and process‑wide hooks are sharp tools. Node contains them with:

• Flags and input types (e.g., --experimental-detect-module, --input-type) so behavioral shifts are explicit.
• Strict global APIs (a single uncaught exception capture callback with type checks and coordinated native behavior).
• Metrics that quantify eval cost and error frequency.

If you build even a small execution engine—a plugin sandbox, a custom REPL, a rule evaluator—these patterns scale down well. Put a façade in front of the scary bits, define how modes are chosen, treat transformations like TypeScript as retries that add context instead of new error models, and give yourself one clear place to decide when an error is bad enough to take the whole system down.