webext-messenger 0.19.1 → 0.21.0-0

package/distribution/handlers.d.ts

@@ -0,0 +1,10 @@
+import { __getTabData } from "./thisTarget.js";
+import { Method } from "./types.js";
+declare global {
+    interface MessengerMethods {
+        __getTabData: typeof __getTabData;
+    }
+}
+export declare const privateMethods: (typeof __getTabData)[];
+export declare const handlers: Map<string, Method>;
+export declare function didUserRegisterMethods(): boolean;

package/distribution/handlers.js

@@ -0,0 +1,6 @@
+import { __getTabData } from "./thisTarget.js";
+export const privateMethods = [__getTabData];
+export const handlers = new Map();
+export function didUserRegisterMethods() {
+    return handlers.size > privateMethods.length;
+}

package/distribution/index.js

@@ -1,8 +1,4 @@
-// Imports must use the .js extension because of ESM requires it and TS refuses to rewrite .ts to .js
-// This works in TS even if the .js doesn't exist, but it breaks Parcel (the tests builder)
-// For this reason, there's an `alias` field in package.json to redirect these imports.
-// If you see "@parcel/resolver-default: Cannot load file './yourNewFile.js'" you need to add it to the `alias` list
-// 🥲
+// Imports must use the .js extension because ESM requires it and TS refuses to rewrite .ts to .js
 export * from "./receiver.js";
 export * from "./sender.js";
 export * from "./types.js";

package/distribution/receiver.js

@@ -1,8 +1,9 @@
 import { serializeError } from "serialize-error";
+import { getContextName } from "webext-detect-page";
 import { messenger } from "./sender.js";
-import { handlers, isObject, MessengerError, debug, __webextMessenger, } from "./shared.js";
-import { getContextName, isBackground } from "webext-detect-page";
-import { getActionForMessage, nameThisTarget } from "./thisTarget.js";
+import { isObject, MessengerError, debug, __webextMessenger, } from "./shared.js";
+import { getActionForMessage } from "./thisTarget.js";
+import { didUserRegisterMethods, handlers } from "./handlers.js";
 export function isMessengerMessage(message) {
     return (isObject(message) &&
         typeof message["type"] === "string" &&
@@ -16,7 +17,7 @@ function onMessageListener(message, sender) {
         return;
     }
     // Target check must be synchronous (`await` means we're handling the message)
-    const action = getActionForMessage(sender, message.target);
+    const action = getActionForMessage(sender, message);
     if (action === "ignore") {
         return;
     }
@@ -44,6 +45,11 @@ action) {
         });
         const localHandler = handlers.get(type);
         if (!localHandler) {
+            if (!didUserRegisterMethods()) {
+                // TODO: Test the handling of __getTabData in contexts that have no registered methods
+                // https://github.com/pixiebrix/webext-messenger/pull/82
+                throw new MessengerError(`No handlers registered in ${getContextName()}`);
+            }
             throw new MessengerError(`No handler registered for ${type} in ${getContextName()}`);
         }
         handleMessage = async () => localHandler.apply(meta, args);
@@ -57,9 +63,6 @@ action) {
     return { ...response, __webextMessenger };
 }
 export function registerMethods(methods) {
-    if (!isBackground()) {
-        void nameThisTarget();
-    }
     for (const [type, method] of Object.entries(methods)) {
         if (handlers.has(type)) {
             throw new MessengerError(`Handler already set for ${type}`);

package/distribution/sender.js

@@ -2,7 +2,8 @@ import pRetry from "p-retry";
 import { isBackground } from "webext-detect-page";
 import { doesTabExist } from "webext-tools";
 import { deserializeError } from "serialize-error";
-import { isObject, MessengerError, __webextMessenger, handlers, debug, warn, } from "./shared.js";
+import { isObject, MessengerError, __webextMessenger, debug, warn, } from "./shared.js";
+import { handlers } from "./handlers.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";
@@ -32,10 +33,27 @@ function manageConnection(type, options, target, sendMessage) {
 async function manageMessage(type, target, sendMessage) {
     const response = await pRetry(async () => {
         const response = await sendMessage();
-        if (!isMessengerResponse(response)) {
-            throw new MessengerError(`No handler registered for ${type} in the receiving end`);
+        if (isMessengerResponse(response)) {
+            return response;
         }
-        return response;
+        // If no one answers, `response` will be `undefined`
+        // If the target does not have any `onMessage` listener at all, it will throw
+        // Possible:
+        // - Any target exists and has onMessage handler, but never handled the message
+        // - Extension page exists and has Messenger, but never handled the message (Messenger in Runtime ignores messages when the target isn't found)
+        // Not possible:
+        // - Tab exists and has Messenger, but never handled the message (Messenger in CS always handles messages)
+        // - Any target exists, but Messenger didn't have the specific Type handler (The receiving Messenger will throw an error)
+        // - No targets exist (the browser immediately throws "Could not establish connection. Receiving end does not exist.")
+        if (response === undefined) {
+            if ("page" in target) {
+                throw new MessengerError(`The target ${JSON.stringify(target)} for ${type} was not found`);
+            }
+            throw new MessengerError(`Messenger was not available in the target ${JSON.stringify(target)} for ${type}`);
+        }
+        // Possible:
+        // - Non-Messenger handler responded
+        throw new MessengerError(`Conflict: The message ${type} was handled by a third-party listener`);
     }, {
         minTimeout: 100,
         factor: 1.3,
@@ -47,7 +65,10 @@ async function manageMessage(type, target, sendMessage) {
             if (
             // Don't retry sending to the background page unless it really hasn't loaded yet
             (target.page !== "background" && error instanceof MessengerError) ||
-                String(error.message).startsWith(_errorNonExistingTarget)) {
+                // Page or its content script not yet loaded
+                error.message === _errorNonExistingTarget ||
+                // `registerMethods` not yet loaded
+                String(error.message).startsWith("No handlers registered in ")) {
                 if (browser.tabs &&
                     typeof target.tabId === "number" &&
                     !(await doesTabExist(target.tabId))) {
@@ -59,6 +80,11 @@ async function manageMessage(type, target, sendMessage) {
                 throw error;
             }
         },
+    }).catch((error) => {
+        if (error?.message === _errorNonExistingTarget) {
+            throw new MessengerError(`The target ${JSON.stringify(target)} for ${type} was not found`);
+        }
+        throw error;
     });
     if ("error" in response) {
         debug(type, "↘️ replied with error", response.error);
@@ -76,7 +102,7 @@ function messenger(type, options, target, ...args) {
                 warn(type, "is being handled locally");
                 return handler.apply({ trace: [] }, args);
             }
-            throw new MessengerError("No handler registered for " + type);
+            throw new MessengerError("No handler registered locally for " + type);
         }
         const sendMessage = async () => {
             debug(type, "↗️ sending message to runtime");

package/distribution/shared.d.ts

@@ -1,5 +1,4 @@
 import { JsonObject } from "type-fest";
-import { Method } from "./types.js";
 declare type ErrorObject = {
     name?: string;
     stack?: string;
@@ -11,7 +10,6 @@ export declare function isObject(value: unknown): value is Record<string, unknow
 export declare class MessengerError extends Error {
     name: string;
 }
-export declare const handlers: Map<string, Method>;
 export declare const debug: (...args: any[]) => void;
 export declare const warn: (...args: any[]) => void;
 export declare function isErrorObject(error: unknown): error is ErrorObject;

package/distribution/shared.js

@@ -1,3 +1,4 @@
+import { errorConstructors } from "serialize-error";
 const logging = (() => {
     try {
         // @ts-expect-error it would break Webpack
@@ -25,13 +26,14 @@ export class MessengerError extends Error {
         });
     }
 }
-export const handlers = new Map();
+// @ts-expect-error Wrong `errorConstructors` types
+errorConstructors.set("MessengerError", MessengerError);
 // .bind preserves the call location in the console
 export const debug = logging ? console.debug.bind(console, "Messenger:") : noop;
 export const warn = logging ? console.warn.bind(console, "Messenger:") : noop;
 export function isErrorObject(error) {
     // eslint-disable-next-line @typescript-eslint/no-explicit-any -- This is a type guard function and it uses ?.
-    return typeof (error === null || error === void 0 ? void 0 : error.message) === "string";
+    return typeof error?.message === "string";
 }
 export async function delay(milliseconds) {
     return new Promise((resolve) => {

package/distribution/thisTarget.d.ts

@@ -1,11 +1,4 @@
-import { AnyTarget, MessengerMeta, Sender } from "./types.js";
-export declare function getActionForMessage(from: Sender, { ...to }: AnyTarget): "respond" | "forward" | "ignore";
-export declare function nameThisTarget(): Promise<void>;
-declare function __getTabData(this: MessengerMeta): AnyTarget;
-declare global {
-    interface MessengerMethods {
-        __getTabData: typeof __getTabData;
-    }
-}
+import { AnyTarget, Message, MessengerMeta, Sender } from "./types.js";
+export declare function getActionForMessage(from: Sender, message: Message): "respond" | "forward" | "ignore";
+export declare function __getTabData(this: MessengerMeta): AnyTarget;
 export declare function initPrivateApi(): void;
-export {};

package/distribution/thisTarget.js

@@ -1,11 +1,44 @@
 import { isBackground, isContentScript, isExtensionContext, } from "webext-detect-page";
 import { messenger } from "./sender.js";
 import { registerMethods } from "./receiver.js";
-import { debug } from "./shared.js";
+import { debug, MessengerError } from "./shared.js";
+/**
+ * @file This file exists because `runtime.sendMessage` acts as a broadcast to
+ * all open extension pages, so the receiver needs a way to figure out if the
+ * message was intended for them.
+ *
+ * If the requested target only includes a `page` (URL), then it can be determined
+ * immediately. If the target also specifies a tab, like `{tabId: 1, page: '/sidebar.html'}`,
+ * then the receiving target needs to fetch the tab information via `__getTabData`.
+ *
+ * `__getTabData` is called automatically when `webext-messenger` is imported in
+ * a context that requires this logic (most extension:// pages).
+ *
+ * If a broadcast message with `tabId` target is received before `__getTabData` is "received",
+ * the message will be ignored and it can be retried. If `__getTabData` somehow fails,
+ * the target will forever ignore any messages that require the `tabId`. In that case,
+ * an error would be thrown once and will be visible in the console, uncaught.
+ *
+ * Content scripts do not use this logic at all at the moment because they're
+ * always targeted via `tabId/frameId` combo and `tabs.sendMessage`.
+ */
 // Soft warning: Race conditions are possible.
 // This CANNOT be awaited because waiting for it means "I will handle the message."
 // If a message is received before this is ready, it will just have to be ignored.
-let thisTarget;
+const thisTarget = isBackground()
+    ? { page: "background" }
+    : {
+        get page() {
+            return location.pathname + location.search;
+        },
+    };
+let tabDataStatus = 
+// The background page doesn't have a tab
+isBackground() ||
+    // Content scripts don't use named targets yet
+    isContentScript()
+    ? "not-needed"
+    : "needed";
 function compareTargets(to, thisTarget) {
     for (const [key, value] of Object.entries(to)) {
         if (thisTarget[key] === value) {
@@ -27,9 +60,10 @@ function compareTargets(to, thisTarget) {
     }
     return true;
 }
-export function getActionForMessage(from, { ...to } // Clone object because we're editing it
-) {
-    var _a;
+// TODO: Test this in Jest, outside the browser
+export function getActionForMessage(from, message) {
+    // Clone object because we're editing it
+    const to = { ...message.target };
     if (to.page === "any") {
         return "respond";
     }
@@ -42,41 +76,49 @@ export function getActionForMessage(from, { ...to } // Clone object because we'r
     if (!to.page) {
         return "forward";
     }
-    if (!thisTarget) {
-        console.warn("A message was received before this context was ready");
-        // If this *was* the target, then probably no one else answered
-        return "ignore";
-    }
     // Set "this" tab to the current tabId
-    if (to.tabId === "this" && thisTarget.tabId === ((_a = from.tab) === null || _a === void 0 ? void 0 : _a.id)) {
+    if (to.tabId === "this" && thisTarget.tabId === from.tab?.id) {
         to.tabId = thisTarget.tabId;
     }
     // Every `target` key must match `thisTarget`
     const isThisTarget = compareTargets(to, thisTarget);
     if (!isThisTarget) {
-        debug("The message’s target is", to, "but this is", thisTarget);
+        debug(message.type, "🤫 ignored due to target mismatch", {
+            requestedTarget: to,
+            thisTarget,
+            tabDataStatus,
+        });
     }
     return isThisTarget ? "respond" : "ignore";
 }
-let nameRequested = false;
-export async function nameThisTarget() {
-    // Same as above: CS receives messages correctly
-    if (!nameRequested && !thisTarget && !isContentScript()) {
-        nameRequested = true;
-        thisTarget = await messenger("__getTabData", {}, { page: "any" });
-        thisTarget.page = location.pathname + location.search;
+async function storeTabData() {
+    if (tabDataStatus !== "needed") {
+        return;
+    }
+    try {
+        tabDataStatus = "pending";
+        Object.assign(thisTarget, {
+            ...(await messenger("__getTabData", {}, { page: "any" })),
+        });
+        tabDataStatus = "received";
+    }
+    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 });
     }
 }
-function __getTabData() {
-    var _a, _b, _c;
-    return { tabId: (_b = (_a = this.trace[0]) === null || _a === void 0 ? void 0 : _a.tab) === null || _b === void 0 ? void 0 : _b.id, frameId: (_c = this.trace[0]) === null || _c === void 0 ? void 0 : _c.frameId };
+export function __getTabData() {
+    return { tabId: this.trace[0]?.tab?.id, frameId: this.trace[0]?.frameId };
 }
 export function initPrivateApi() {
-    if (isBackground()) {
-        thisTarget = { page: "background" };
-    }
     if (isExtensionContext()) {
-        // Any context can handler this message
+        // 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.
+        // https://github.com/pixiebrix/webext-messenger/pull/80
         registerMethods({ __getTabData });
+        // `getTabInformation` includes per-context exclusion logic
+        void storeTabData();
     }
 }

package/distribution/types.d.ts

@@ -40,7 +40,9 @@ export declare type Message<LocalArguments extends Arguments = Arguments> = {
     /** If the message is being sent to an intermediary receiver, also set the options */
     options?: Options;
 };
-export declare type Sender = Runtime.MessageSender;
+export declare type Sender = Runtime.MessageSender & {
+    origin?: string;
+};
 export declare type MessengerMessage = Message & {
     /** Guarantees that a message is meant to be handled by this library */
     __webextMessenger: true;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "webext-messenger",
-  "version": "0.19.1",
+  "version": "0.21.0-0",
   "description": "Browser Extension component messaging framework",
   "keywords": [],
   "repository": "pixiebrix/webext-messenger",
@@ -18,85 +18,6 @@
     "fix": "eslint . --fix",
     "watch": "tsc --watch"
   },
-  "eslintConfig": {
-    "env": {
-      "browser": true
-    },
-    "parserOptions": {
-      "project": "tsconfig.json"
-    },
-    "plugins": [
-      "import"
-    ],
-    "extends": [
-      "plugin:@typescript-eslint/recommended",
-      "xo",
-      "xo-typescript",
-      "prettier",
-      "plugin:import/recommended",
-      "plugin:import/typescript",
-      "plugin:unicorn/recommended"
-    ],
-    "rules": {
-      "no-restricted-imports": [
-        "error",
-        {
-          "paths": [
-            {
-              "name": "./index",
-              "message": "The index file is only used to re-export internal files. Use direct imports instead."
-            }
-          ]
-        }
-      ],
-      "import/extensions": [
-        "error",
-        "always"
-      ],
-      "import/no-unresolved": "off",
-      "unicorn/filename-case": [
-        "error",
-        {
-          "case": "camelCase"
-        }
-      ],
-      "unicorn/no-useless-undefined": [
-        "error",
-        {
-          "checkArguments": false
-        }
-      ],
-      "unicorn/prevent-abbreviations": [
-        "error",
-        {
-          "allowList": {
-            "args": true
-          }
-        }
-      ]
-    },
-    "overrides": [
-      {
-        "files": [
-          "*.test.ts",
-          "testingApi.ts"
-        ],
-        "rules": {
-          "@typescript-eslint/no-explicit-any": "off",
-          "@typescript-eslint/no-non-null-assertion": "off",
-          "@typescript-eslint/no-unsafe-member-access": "off"
-        }
-      },
-      {
-        "files": [
-          "source/test/**/*"
-        ],
-        "rules": {
-          "import/extensions": "off"
-        }
-      }
-    ]
-  },
   "dependencies": {
     "p-retry": "^5.1.1",
     "serialize-error": "^11.0.0",
@@ -131,12 +52,8 @@
     "webextension-polyfill": "^0.9.0"
   },
   "alias": {
-    "./this-stuff-is-just-for-local-parcel-tests": "./package.json",
-    "./source/sender.js": "./source/sender.ts",
-    "./source/receiver.js": "./source/receiver.ts",
-    "./source/types.js": "./source/types.ts",
-    "./source/shared.js": "./source/shared.ts",
-    "./source/thisTarget.js": "./source/thisTarget.ts"
+    "./this-stuff-is-just-for-local-parcel-tests": "https://github.com/parcel-bundler/parcel/issues/4936",
+    "./source/**/*.js": "./source/$1/$2.ts"
   },
   "targets": {
     "main": false,