[WIP] feat: Have injectScript return the result value from the script

Author: ion1

packages/wxt/src/utils/inject-script.ts

@@ -1,5 +1,6 @@
 /** @module wxt/utils/inject-script */
 import { browser } from 'wxt/browser';
+import { waitForScriptResultEvent } from './internal/script-result';
 
 export type ScriptPublicPath = Extract<
   // @ts-expect-error: PublicPath is generated per-project
@@ -15,11 +16,13 @@ export type ScriptPublicPath = Extract<
  *
  * Make sure to add the injected script to your manifest's
  * `web_accessible_resources`.
+ *
+ * @returns The return value of the script.
  */
 export async function injectScript(
   path: ScriptPublicPath,
   options?: InjectScriptOptions,
-): Promise<void> {
+): Promise<unknown> {
   // @ts-expect-error: getURL is defined per-project, but not inside the package
   const url = browser.runtime.getURL(path);
   const script = document.createElement('script');
@@ -33,6 +36,7 @@ export async function injectScript(
   }
 
   const loadedPromise = makeLoadedPromise(script);
+  const resultPromise = waitForScriptResultEvent(script);
 
   await options?.manipulateScript?.(script);
 
@@ -43,6 +47,9 @@ export async function injectScript(
   }
 
   await loadedPromise;
+  const result = await resultPromise;
+
+  return result;
 }
 
 function makeLoadedPromise(script: HTMLScriptElement): Promise<void> {

packages/wxt/src/utils/internal/script-result.ts

@@ -0,0 +1,161 @@
+// The `MAIN` world script cannot use `browser.runtime.id`, but the uniqueness
+// of the event name is not an issue as the event is only dispatched on a
+// specific `script` element which is detached from the document.
+const SCRIPT_RESULT_EVENT_NAME = 'wxt:script-result';
+
+/**
+ * Dispatch a `CustomEvent` for a successful script result which carries a
+ * result value.
+ */
+export function dispatchScriptSuccessEvent(
+  target: EventTarget,
+  value: unknown,
+): boolean {
+  return dispatchScriptResultEvent(target, scriptSuccess(value));
+}
+
+/**
+ * Dispatch a `CustomEvent` for a failed script result which carries an `Error`
+ * value.
+ */
+export function dispatchScriptErrorEvent(
+  target: EventTarget,
+  error: Error,
+): boolean {
+  return dispatchScriptResultEvent(target, scriptError(error));
+}
+
+function dispatchScriptResultEvent(
+  target: EventTarget,
+  result: ScriptResult,
+): boolean {
+  return target.dispatchEvent(
+    new CustomEvent(SCRIPT_RESULT_EVENT_NAME, { detail: result }),
+  );
+}
+
+/**
+ * Add a one-time event listener for a script result `CustomEvent`, and return a
+ * `Promise` which either resolves with the result value or rejects with an
+ * error depending on whether the result is successful or not.
+ */
+export function waitForScriptResultEvent(
+  target: EventTarget,
+): Promise<unknown> {
+  return new Promise((resolve, reject) => {
+    target.addEventListener(
+      SCRIPT_RESULT_EVENT_NAME,
+      (event) => {
+        try {
+          resolve(parseScriptResultEvent(event));
+        } catch (err) {
+          reject(err);
+        }
+      },
+      { once: true },
+    );
+  });
+}
+
+function parseScriptResultEvent(event: Event): unknown {
+  if (!(event instanceof CustomEvent)) {
+    throw new Error(
+      `Expected a \`CustomEvent\`, got: ${JSON.stringify(event)}`,
+    );
+  }
+
+  return parseScriptResult(event.detail as unknown);
+}
+
+type ScriptResult =
+  | { type: 'success'; value: unknown }
+  | { type: 'error'; error: Error };
+
+function scriptSuccess(value: unknown): ScriptResult {
+  return { type: 'success', value };
+}
+
+function scriptError(error: Error): ScriptResult {
+  return { type: 'error', error: deconstructError(error) };
+}
+
+function parseScriptResult(result: unknown): unknown {
+  if (!isScriptResult(result)) {
+    throw new Error(
+      `Expected a \`ScriptResult\`, got: ${JSON.stringify(result)}`,
+    );
+  }
+
+  switch (result.type) {
+    case 'success':
+      return result.value;
+    case 'error':
+      throw reconstructError(result.error);
+    default:
+      throw new Error(
+        `Impossible \`ScriptResult\`: ${JSON.stringify(result satisfies never)}`,
+      );
+  }
+}
+
+function isScriptResult(result: unknown): result is ScriptResult {
+  return (
+    result != null &&
+    typeof result === 'object' &&
+    'type' in result &&
+    typeof result.type === 'string' &&
+    ((result.type === 'success' && 'value' in result) ||
+      (result.type === 'error' &&
+        'error' in result &&
+        isDeconstructedError(result.error)))
+  );
+}
+
+/**
+ * A representation of an `Error` which can be transmitted within a
+ * `CustomEvent`.
+ */
+type DeconstructedError = {
+  name: string;
+  message: string;
+  stack?: string;
+};
+
+function deconstructError(error: Error): DeconstructedError {
+  const result: DeconstructedError = {
+    name: error.name,
+    message: error.message,
+  };
+
+  if ('stack' in error) result.stack = error.stack;
+
+  return result;
+}
+
+function reconstructError(deconstructedError: DeconstructedError): Error {
+  const error = new Error(deconstructedError.message);
+  error.name = deconstructedError.name;
+
+  if ('stack' in deconstructedError) {
+    error.stack = deconstructedError.stack;
+  } else {
+    delete error.stack;
+  }
+
+  return error;
+}
+
+function isDeconstructedError(value: unknown): value is DeconstructedError {
+  return (
+    value != null &&
+    typeof value === 'object' &&
+    'name' in value &&
+    value.name != null &&
+    typeof value.name === 'string' &&
+    'message' in value &&
+    value.message != null &&
+    typeof value.message === 'string' &&
+    (!('stack' in value) ||
+      (value.stack != null && typeof value.stack === 'string'))
+  );
+}

packages/wxt/src/virtual/unlisted-script-entrypoint.ts

@@ -1,22 +1,40 @@
 import definition from 'virtual:user-unlisted-script-entrypoint';
 import { logger } from '../utils/internal/logger';
+import {
+  dispatchScriptSuccessEvent,
+  dispatchScriptErrorEvent,
+} from '../utils/internal/script-result';
 import { initPlugins } from 'virtual:wxt-plugins';
 
-const result = (async () => {
+// TODO: This only works with injectScript, not the scripting API.
+
+(async () => {
   try {
-    initPlugins();
-    return await definition.main();
-  } catch (err) {
+    const script = document.currentScript;
+    if (script === null) {
+      // This should never happen.
+      throw new Error(`\`document.currentScript\` is null!`);
+    }
+
+    try {
+      initPlugins();
+      const result = await definition.main();
+      dispatchScriptSuccessEvent(script, result);
+    } catch (error) {
+      dispatchScriptErrorEvent(
+        script,
+        error instanceof Error ? error : new Error(`${error}`),
+      );
+    }
+  } catch (outerError) {
+    // This should never happen.
     logger.error(
       `The unlisted script "${import.meta.env.ENTRYPOINT}" crashed on startup!`,
-      err,
+      outerError,
     );
-    throw err;
+    throw outerError;
   }
 })();
 
-// Return the main function's result to the background when executed via the
-// scripting API. Default export causes the IIFE to return a value.
-// https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/scripting/executeScript#return_value
-// Tested on both Chrome and Firefox
-export default result;
+// TODO: The build result fails without this.
+export default undefined;