From 39201aa31d267f9bdd21f544e1c0260d57f85df4 Mon Sep 17 00:00:00 2001
From: Chengzhong Wu <cwu631@bloomberg.net>
Date: Fri, 12 Sep 2025 11:20:48 +0100
Subject: [PATCH] vm: expose hasTopLevelAwait on SourceTextModule

Expose `hasTopLevelAwait` and `hasAsyncGraph` on
`vm.SourceTextModule`.

`hasAsyncGraph` requires the module to be instantiated first.
---
 doc/api/vm.md                                 | 30 +++++++++
 lib/internal/vm/module.js                     | 13 ++++
 test/parallel/test-vm-module-hasasyncgraph.js | 67 +++++++++++++++++++
 .../test-vm-module-hastoplevelawait.js        | 59 ++++++++++++++++
 4 files changed, 169 insertions(+)
 create mode 100644 test/parallel/test-vm-module-hasasyncgraph.js
 create mode 100644 test/parallel/test-vm-module-hastoplevelawait.js

diff --git a/doc/api/vm.md b/doc/api/vm.md
index dd36293859fe1e..81f8c9d1f76372 100644
--- a/doc/api/vm.md
+++ b/doc/api/vm.md
@@ -920,6 +920,36 @@ to disallow any changes to it.
 Corresponds to the `[[RequestedModules]]` field of [Cyclic Module Record][]s in
 the ECMAScript specification.
 
+### `sourceTextModule.hasAsyncGraph()`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* Returns: {boolean}
+
+Iterates over the dependency graph and returns `true` if any module in its
+dependencies or this module itself contains top-level `await` expressions,
+otherwise returns `false`.
+
+The search may be slow if the graph is big enough.
+
+This requires the module to be instantiated first. If the module is not
+instantiated yet, an error will be thrown.
+
+### `sourceTextModule.hasTopLevelAwait()`
+
+<!-- YAML
+added: REPLACEME
+-->
+
+* Returns: {boolean}
+
+Returns whether the module itself contains any top-level `await` expressions.
+
+This corresponds to the field `[[HasTLA]]` in [Cyclic Module Record][] in the
+ECMAScript specification.
+
 ### `sourceTextModule.instantiate()`
 
 <!-- YAML
diff --git a/lib/internal/vm/module.js b/lib/internal/vm/module.js
index 98d015729c9039..457d26d27692a9 100644
--- a/lib/internal/vm/module.js
+++ b/lib/internal/vm/module.js
@@ -429,6 +429,19 @@ class SourceTextModule extends Module {
     return super.error;
   }
 
+  hasAsyncGraph() {
+    validateThisInternalField(this, kWrap, 'SourceTextModule');
+    if (this[kWrap].getStatus() < kInstantiated) {
+      throw new ERR_VM_MODULE_STATUS('must be instantiated');
+    }
+    return this[kWrap].hasAsyncGraph;
+  }
+
+  hasTopLevelAwait() {
+    validateThisInternalField(this, kWrap, 'SourceTextModule');
+    return this[kWrap].hasTopLevelAwait;
+  }
+
   createCachedData() {
     const { status } = this;
     if (status === 'evaluating' ||
diff --git a/test/parallel/test-vm-module-hasasyncgraph.js b/test/parallel/test-vm-module-hasasyncgraph.js
new file mode 100644
index 00000000000000..ce67d090402e7b
--- /dev/null
+++ b/test/parallel/test-vm-module-hasasyncgraph.js
@@ -0,0 +1,67 @@
+'use strict';
+
+// Flags: --experimental-vm-modules
+
+require('../common');
+
+const assert = require('assert');
+
+const { SourceTextModule } = require('vm');
+const test = require('node:test');
+
+test('module is not instantiated yet', () => {
+  const foo = new SourceTextModule(`
+    export const foo = 4
+    export default 5;
+  `);
+  assert.throws(() => foo.hasAsyncGraph(), {
+    code: 'ERR_VM_MODULE_STATUS',
+  });
+});
+
+test('simple module with top-level await', () => {
+  const foo = new SourceTextModule(`
+    export const foo = 4
+    export default 5;
+
+    await 0;
+  `);
+  foo.linkRequests([]);
+  foo.instantiate();
+
+  assert.strictEqual(foo.hasAsyncGraph(), true);
+});
+
+test('simple module with non top-level await', () => {
+  const foo = new SourceTextModule(`
+    export const foo = 4
+    export default 5;
+
+    export async function f() {
+      await 0;
+    }
+  `);
+  foo.linkRequests([]);
+  foo.instantiate();
+
+  assert.strictEqual(foo.hasAsyncGraph(), false);
+});
+
+test('module with a dependency containing top-level await', () => {
+  const foo = new SourceTextModule(`
+    export const foo = 4
+    export default 5;
+
+    await 0;
+  `);
+  foo.linkRequests([]);
+
+  const bar = new SourceTextModule(`
+    export { foo } from 'foo';
+  `);
+  bar.linkRequests([foo]);
+  bar.instantiate();
+
+  assert.strictEqual(foo.hasAsyncGraph(), true);
+  assert.strictEqual(bar.hasAsyncGraph(), true);
+});
diff --git a/test/parallel/test-vm-module-hastoplevelawait.js b/test/parallel/test-vm-module-hastoplevelawait.js
new file mode 100644
index 00000000000000..c280bf4cd2dd90
--- /dev/null
+++ b/test/parallel/test-vm-module-hastoplevelawait.js
@@ -0,0 +1,59 @@
+'use strict';
+
+// Flags: --experimental-vm-modules
+
+require('../common');
+
+const assert = require('assert');
+
+const { SourceTextModule } = require('vm');
+const test = require('node:test');
+
+test('simple module', () => {
+  const foo = new SourceTextModule(`
+    export const foo = 4
+    export default 5;
+  `);
+  assert.strictEqual(foo.hasTopLevelAwait(), false);
+});
+
+test('simple module with top-level await', () => {
+  const foo = new SourceTextModule(`
+    export const foo = 4
+    export default 5;
+
+    await 0;
+  `);
+  assert.strictEqual(foo.hasTopLevelAwait(), true);
+});
+
+test('simple module with non top-level await', () => {
+  const foo = new SourceTextModule(`
+    export const foo = 4
+    export default 5;
+
+    export async function f() {
+      await 0;
+    }
+  `);
+  assert.strictEqual(foo.hasTopLevelAwait(), false);
+});
+
+test('module with a dependency containing top-level await', () => {
+  const foo = new SourceTextModule(`
+    export const foo = 4
+    export default 5;
+
+    await 0;
+  `);
+  foo.linkRequests([]);
+
+  const bar = new SourceTextModule(`
+    export { foo } from 'foo';
+  `);
+  bar.linkRequests([foo]);
+  bar.instantiate();
+
+  assert.strictEqual(foo.hasTopLevelAwait(), true);
+  assert.strictEqual(bar.hasTopLevelAwait(), false);
+});