webext-messenger 0.24.0 → 0.25.0

package/distribution/events.d.ts

@@ -0,0 +1 @@
+export declare const events: EventTarget;

package/distribution/events.js

@@ -0,0 +1 @@
+export const events = new EventTarget();

package/distribution/index.d.ts

@@ -1,5 +1,6 @@
 export * from "./receiver.js";
 export * from "./sender.js";
 export * from "./types.js";
+export * from "./events.js";
 export { getThisFrame, getTopLevelFrame } from "./thisTarget.js";
 export { toggleLogging } from "./logging.js";

package/distribution/index.js

@@ -2,7 +2,10 @@
 export * from "./receiver.js";
 export * from "./sender.js";
 export * from "./types.js";
+export * from "./events.js";
 export { getThisFrame, getTopLevelFrame } from "./thisTarget.js";
 export { toggleLogging } from "./logging.js";
 import { initPrivateApi } from "./thisTarget.js";
+// Required side effect to better track errors:
+// https://github.com/pixiebrix/webext-messenger/pull/80
 initPrivateApi();

package/distribution/sender.d.ts

@@ -1,5 +1,5 @@
 import { type PublicMethod, type PublicMethodWithTarget, type Options, type Target, type PageTarget } from "./types.js";
-import { type SetReturnType } from "type-fest";
+import { type Promisable, type SetReturnType } from "type-fest";
 export declare const errorTargetClosedEarly = "The target was closed before receiving a response";
 export declare const errorTabDoesntExist = "The tab doesn't exist";
 export declare const errorTabWasDiscarded = "The tab was discarded";
@@ -7,9 +7,9 @@ declare function messenger<Type extends keyof MessengerMethods, Method extends M
     isNotification: true;
 }, target: Target | PageTarget, ...args: Parameters<Method>): void;
 declare function messenger<Type extends keyof MessengerMethods, Method extends MessengerMethods[Type], ReturnValue extends Promise<ReturnType<Method>>>(type: Type, options: Options, target: Target | PageTarget, ...args: Parameters<Method>): ReturnValue;
-declare function getMethod<Type extends keyof MessengerMethods, Method extends MessengerMethods[Type], PublicMethodType extends PublicMethod<Method>>(type: Type, target: Target | PageTarget): PublicMethodType;
+declare function getMethod<Type extends keyof MessengerMethods, Method extends MessengerMethods[Type], PublicMethodType extends PublicMethod<Method>>(type: Type, target: Promisable<Target | PageTarget>): PublicMethodType;
 declare function getMethod<Type extends keyof MessengerMethods, Method extends MessengerMethods[Type], PublicMethodWithDynamicTarget extends PublicMethodWithTarget<Method>>(type: Type): PublicMethodWithDynamicTarget;
-declare function getNotifier<Type extends keyof MessengerMethods, Method extends MessengerMethods[Type], PublicMethodType extends SetReturnType<PublicMethod<Method>, void>>(type: Type, target: Target | PageTarget): PublicMethodType;
+declare function getNotifier<Type extends keyof MessengerMethods, Method extends MessengerMethods[Type], PublicMethodType extends SetReturnType<PublicMethod<Method>, void>>(type: Type, target: Promisable<Target | PageTarget>): PublicMethodType;
 declare function getNotifier<Type extends keyof MessengerMethods, Method extends MessengerMethods[Type], PublicMethodWithDynamicTarget extends SetReturnType<PublicMethodWithTarget<Method>, void>>(type: Type): PublicMethodWithDynamicTarget;
 export { messenger, getMethod, getNotifier };
 export declare const backgroundTarget: PageTarget;

package/distribution/sender.js

@@ -4,6 +4,7 @@ import { deserializeError } from "serialize-error";
 import { isObject, MessengerError, __webextMessenger } from "./shared.js";
 import { log } from "./logging.js";
 import { handlers } from "./handlers.js";
+import { events } from "./events.js";
 const _errorNonExistingTarget = "Could not establish connection. Receiving end does not exist.";
 // https://github.com/mozilla/webextension-polyfill/issues/384
 const _errorTargetClosedEarly = "A listener indicated an asynchronous response by returning true, but the message channel closed before a response was received";
@@ -16,6 +17,9 @@ function isMessengerResponse(response) {
 function attemptLog(attemptCount) {
     return attemptCount > 1 ? `(try: ${attemptCount})` : "";
 }
+function wasContextInvalidated() {
+    return !chrome.runtime?.id;
+}
 function makeMessage(type, args, target, options) {
     return {
         __webextMessenger,
@@ -26,15 +30,16 @@ function makeMessage(type, args, target, options) {
     };
 }
 // Do not turn this into an `async` function; Notifications must turn `void`
-function manageConnection(type, { seq, isNotification }, target, sendMessage) {
+function manageConnection(type, { seq, isNotification, retry }, target, sendMessage) {
     if (!isNotification) {
-        return manageMessage(type, target, seq, sendMessage);
+        return manageMessage(type, target, seq, retry ?? true, sendMessage);
     }
     void sendMessage(1).catch((error) => {
         log.debug(type, seq, "notification failed", { error });
     });
 }
-async function manageMessage(type, target, seq, sendMessage) {
+async function manageMessage(type, target, seq, retry, sendMessage) {
+    // TODO: Split this up a bit because it's too long. Probably drop p-retry
     const response = await pRetry(async (attemptCount) => {
         const response = await sendMessage(attemptCount);
         if (isMessengerResponse(response)) {
@@ -61,8 +66,25 @@ async function manageMessage(type, target, seq, sendMessage) {
     }, {
         minTimeout: 100,
         factor: 1.3,
+        // Do not set this to undefined or Infinity, it doesn't work the same way
+        ...(retry ? {} : { retries: 0 }),
         maxRetryTime: 4000,
         async onFailedAttempt(error) {
+            events.dispatchEvent(new CustomEvent("failed-attempt", {
+                detail: {
+                    type,
+                    seq,
+                    target,
+                    error,
+                    attemptCount: error.attemptNumber,
+                },
+            }));
+            if (wasContextInvalidated()) {
+                // The error matches the native context invalidated error
+                // *.sendMessage() might fail with a message-specific error that is less useful,
+                // like "Sender closed without responding"
+                throw new Error("Extension context invalidated.");
+            }
             if (error.message === _errorTargetClosedEarly) {
                 throw new Error(errorTargetClosedEarly);
             }
@@ -94,6 +116,9 @@ async function manageMessage(type, target, seq, sendMessage) {
         if (error?.message === _errorNonExistingTarget) {
             throw new MessengerError(`The target ${JSON.stringify(target)} for ${type} was not found`);
         }
+        events.dispatchEvent(new CustomEvent("attempts-exhausted", {
+            detail: { type, seq, target, error },
+        }));
         throw error;
     });
     if ("error" in response) {
@@ -141,20 +166,21 @@ function messenger(type, options, target, ...args) {
     });
 }
 function getMethod(type, target) {
-    if (arguments.length === 1) {
+    if (!target) {
         return messenger.bind(undefined, type, {});
     }
-    // @ts-expect-error `bind` types are junk
-    return messenger.bind(undefined, type, {}, target);
+    return (async (...args) => messenger(type, {}, await target, ...args));
 }
 function getNotifier(type, target) {
     const options = { isNotification: true };
-    if (arguments.length === 1) {
+    if (!target) {
         // @ts-expect-error `bind` types are junk
         return messenger.bind(undefined, type, options);
     }
-    // @ts-expect-error `bind` types are junk
-    return messenger.bind(undefined, type, options, target);
+    return ((...args) => {
+        // Async wrapper needed to use `await` while preserving a non-Promise return type
+        (async () => messenger(type, options, await target, ...args))();
+    });
 }
 export { messenger, getMethod, getNotifier };
 export const backgroundTarget = { page: "background" };

package/distribution/shared.js

@@ -4,15 +4,7 @@ export function isObject(value) {
     return typeof value === "object" && value !== null;
 }
 export class MessengerError extends Error {
-    constructor() {
-        super(...arguments);
-        Object.defineProperty(this, "name", {
-            enumerable: true,
-            configurable: true,
-            writable: true,
-            value: "MessengerError"
-        });
-    }
+    name = "MessengerError";
 }
 // @ts-expect-error Wrong `errorConstructors` types
 errorConstructors.set("MessengerError", MessengerError);

package/distribution/thisTarget.js

@@ -106,9 +106,7 @@ const storeTabData = once(async () => {
     }
     catch (error) {
         tabDataStatus = "error";
-        throw new MessengerError("Tab registration failed. This page won’t be able to receive messages that require tab information", 
-        // @ts-expect-error TODO: update lib to accept Error#cause
-        { cause: error });
+        throw new MessengerError("Tab registration failed. This page won’t be able to receive messages that require tab information", { cause: error });
     }
 });
 export function __getTabData() {
@@ -131,6 +129,16 @@ export async function getTopLevelFrame() {
     };
 }
 export function initPrivateApi() {
+    // Improve DX by informing the developer that it's being loaded the wrong way
+    // https://github.com/pixiebrix/webext-messenger/issues/88
+    if (globalThis.__webextMessenger) {
+        // TODO: Use Error#cause after https://bugs.chromium.org/p/chromium/issues/detail?id=1211260
+        console.log(globalThis.__webextMessenger.replace(/^Error/, "webext-messenger"));
+        console.error("webext-messenger: Duplicate execution. This is a fatal error.\nhttps://github.com/pixiebrix/webext-messenger/issues/88");
+        return;
+    }
+    // Use Error to capture the stack and make it easier to find the cause
+    globalThis.__webextMessenger = new Error("First execution").stack;
     if (isExtensionContext()) {
         // Only `runtime` pages can handle this message but I can't remove it because its listener
         // also serves the purpose of throwing a specific error when no methods have been registered.

package/distribution/types.d.ts

@@ -37,6 +37,7 @@ export interface Options {
      */
     isNotification?: boolean;
     trace?: Sender[];
+    retry?: boolean;
     /** Automatically generated internally */
     seq?: number;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "webext-messenger",
-  "version": "0.24.0",
+  "version": "0.25.0",
   "description": "Browser Extension component messaging framework",
   "keywords": [],
   "repository": "pixiebrix/webext-messenger",
@@ -25,29 +25,29 @@
     "watch": "tsc --watch"
   },
   "dependencies": {
-    "p-retry": "^6.0.0",
+    "p-retry": "^6.2.0",
     "serialize-error": "^11.0.2",
-    "type-fest": "^4.3.1",
-    "webext-detect-page": "^4.1.1"
+    "type-fest": "^4.9.0",
+    "webext-detect-page": "^4.2.1"
   },
   "devDependencies": {
     "@parcel/config-webextension": "^2.6.2",
-    "@sindresorhus/tsconfig": "^4.0.0",
-    "@types/chrome": "^0.0.245",
-    "@types/tape": "^5.6.1",
-    "@types/webextension-polyfill": "^0.10.2",
+    "@sindresorhus/tsconfig": "^5.0.0",
+    "@types/chrome": "^0.0.254",
+    "@types/tape": "^5.6.4",
+    "@types/webextension-polyfill": "^0.10.7",
     "buffer": "^6.0.3",
-    "eslint": "^8.50.0",
-    "eslint-config-pixiebrix": "^0.27.2",
+    "eslint": "^8.56.0",
+    "eslint-config-pixiebrix": "^0.32.0",
     "events": "^3.3.0",
     "npm-run-all": "^4.1.5",
     "parcel": "^2.6.2",
     "path-browserify": "^1.0.1",
     "process": "^0.11.10",
     "stream-browserify": "^3.0.0",
-    "tape": "^5.7.0",
-    "typescript": "^5.2.2",
-    "webext-content-scripts": "^2.5.5",
+    "tape": "^5.7.2",
+    "typescript": "^5.3.3",
+    "webext-content-scripts": "^2.6.0",
     "webextension-polyfill": "^0.10.0"
   },
   "alias": {