Stack tracing / debug dump of intermediate files

documentation/docs/experimental/mapAndLogError.mdx

@@ -0,0 +1,60 @@
+---
+hide_title: false
+hide_table_of_contents: false
+pagination_next: null
+pagination_prev: null
+---
+# mapAndLogError
+
+The **`mapAndLogError()`** function calls `mapError` on an `Error` object and sends the output to standard error. This includes the error name, message, and a call stack.
+
+If `--enable-stack-traces` is specified during the build, the call stack will be mapped using source maps.
+
+If `--enable-stack-traces` is specified and `--exclude-sources` is not specified during the build, then this will also include a code dump of neighboring lines of user code.
+
+## Syntax
+
+```js
+mapAndLogError(error)
+```
+
+### Parameters
+
+- `error` _: Error _ or _string_
+  - The error to retrieve information about. If a `string` is provided, then it is first converted to an `Error`.
+
+### Return value
+
+`undefined`.
+
+## Examples
+
+In this example, build the application using the `--enable-stack-traces` flag.
+
+```js
+addEventListener('fetch', e => e.respondWith(handler(e)));
+async function handler(event) {
+  try {
+    throw new TypeError('foo');
+  } catch (err) {
+    mapAndLogError(mapError(err));
+  }
+  return new Response('ok');
+}
+```
+
+The following is output to the error log.
+
+```
+TypeError: foo
+  at handler (src/index.ts:4:11)
+      1 | addEventListener('fetch', e => e.respondWith(handler(e)));
+      2 | async function handler(event) {
+      3 |   try {
+>     4 |     throw new TypeError('foo');
+                    ^
+      5 |   } catch (err) {
+      6 |     mapAndLogError(mapError(err));
+      7 |   }
+  at src/index.ts:1:45
+```

documentation/docs/experimental/mapError.mdx

@@ -0,0 +1,60 @@
+---
+hide_title: false
+hide_table_of_contents: false
+pagination_next: null
+pagination_prev: null
+---
+# mapError
+
+The **`mapError()`** function extracts information from an `Error` object as a human-readable array of strings. This includes the error name, message, and a call stack.
+
+If `--enable-stack-traces` is specified during the build, the call stack will be mapped using source maps.
+
+If `--enable-stack-traces` is specified and `--exclude-sources` is not specified during the build, then this will also include a code dump of neighboring lines of user code.
+
+## Syntax
+
+```js
+mapError(error)
+```
+
+### Parameters
+
+- `error` _: Error _ or _string_
+  - The error to retrieve information about. If a `string` is provided, then it is first converted to an `Error`.
+
+### Return value
+
+Returns an array of `string`s.
+
+## Examples
+
+In this example, build the application using the `--enable-stack-traces` flag.
+
+```js
+addEventListener('fetch', e => e.respondWith(handler(e)));
+async function handler(event) {
+  try {
+    throw new TypeError('foo');
+  } catch (err) {
+    console.error(mapError(err));
+  }
+  return new Response('ok');
+}
+```
+
+The following is output to the error log.
+
+```
+TypeError: foo
+  at handler (src/index.ts:4:11)
+      1 | addEventListener('fetch', e => e.respondWith(handler(e)));
+      2 | async function handler(event) {
+      3 |   try {
+>     4 |     throw new TypeError('foo');
+                    ^
+      5 |   } catch (err) {
+      6 |     console.error(mapError(err));
+      7 |   }
+  at src/index.ts:1:45
+```

js-compute-runtime-cli.js

@@ -12,6 +12,9 @@ const {
   enableExperimentalHighResolutionTimeMethods,
   moduleMode,
   bundle,
+  enableStackTraces,
+  excludeSources,
+  debugIntermediateFilesDir,
   wasmEngine,
   input,
   output,
@@ -34,17 +37,20 @@ if (version) {
   const { compileApplicationToWasm } = await import(
     './src/compileApplicationToWasm.js'
   );
-  await compileApplicationToWasm(
+  await compileApplicationToWasm({
     input,
     output,
     wasmEngine,
     enableHttpCache,
     enableExperimentalHighResolutionTimeMethods,
     enableAOT,
     aotCache,
+    enableStackTraces,
+    excludeSources,
+    debugIntermediateFilesDir,
     moduleMode,
-    bundle,
+    doBundle: bundle,
     env,
-  );
+  });
   await addSdkMetadataField(output, enableAOT);
 }

package.json

@@ -57,12 +57,15 @@
   },
   "dependencies": {
     "@bytecodealliance/jco": "^1.7.0",
-    "@bytecodealliance/wizer": "^7.0.5",
     "@bytecodealliance/weval": "^0.3.2",
+    "@bytecodealliance/wizer": "^7.0.5",
+    "@jridgewell/remapping": "^2.3.5",
+    "@jridgewell/trace-mapping": "^0.3.31",
     "acorn": "^8.13.0",
     "acorn-walk": "^8.3.4",
     "esbuild": "^0.25.0",
     "magic-string": "^0.30.12",
+    "picomatch": "^4.0.3",
     "regexpu-core": "^6.1.1"
   },
   "peerDependencies": {

src/bundle.js

@@ -1,6 +1,14 @@
+import { rename } from 'node:fs/promises';
+import { dirname, basename, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { build } from 'esbuild';
 
-let fastlyPlugin = {
+import { swallowTopLevelExportsPlugin } from './swallowTopLevelExportsPlugin.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+const fastlyPlugin = {
   name: 'fastly',
   setup(build) {
     build.onResolve({ filter: /^fastly:.*/ }, (args) => {
@@ -74,6 +82,8 @@ export const setBaseURL = Object.getOwnPropertyDescriptor(globalThis.fastly, 'ba
 export const setDefaultBackend = Object.getOwnPropertyDescriptor(globalThis.fastly, 'defaultBackend').set;
 export const allowDynamicBackends = Object.getOwnPropertyDescriptor(globalThis.fastly, 'allowDynamicBackends').set;
 export const sdkVersion = globalThis.fastly.sdkVersion;
+export const mapAndLogError = (e) => globalThis.__fastlyMapAndLogError(e);
+export const mapError = (e) => globalThis.__fastlyMapError(e);
 `,
           };
         }
@@ -143,14 +153,40 @@ export const TransactionCacheEntry = globalThis.TransactionCacheEntry;
   },
 };
 
-export async function bundle(input, moduleMode = false) {
-  return await build({
+export async function bundle(
+  input,
+  outfile,
+  { moduleMode = false, enableStackTraces = false },
+) {
+  // Build output file in cwd first to build sourcemap with correct paths
+  const bundle = resolve(basename(outfile));
+
+  const plugins = [fastlyPlugin];
+  if (moduleMode) {
+    plugins.push(swallowTopLevelExportsPlugin({ entry: input }));
+  }
+
+  const inject = [];
+  if (enableStackTraces) {
+    inject.push(resolve(__dirname, './rsrc/trace-mapping.inject.js'));
+  }
+
+  await build({
     conditions: ['fastly'],
     entryPoints: [input],
     bundle: true,
-    write: false,
+    write: true,
+    outfile: bundle,
+    sourcemap: 'external',
+    sourcesContent: true,
     format: moduleMode ? 'esm' : 'iife',
     tsconfig: undefined,
-    plugins: [fastlyPlugin],
+    plugins,
+    inject,
   });
+
+  await rename(bundle, outfile);
+  if (enableStackTraces) {
+    await rename(bundle + '.map', outfile + '.map');
+  }
 }