webext-messenger 0.14.0 → 0.15.0-0

package/distribution/api.d.ts

@@ -0,0 +1,10 @@
+import { Target, MessengerMeta } from "./types";
+declare function __getTabData(this: MessengerMeta): Target;
+declare global {
+    interface MessengerMethods {
+        __getTabData: typeof __getTabData;
+    }
+}
+export declare const getTabData: () => Promise<Target>;
+export declare function initPrivateApi(): void;
+export {};

package/distribution/api.js

@@ -0,0 +1,13 @@
+import { getMethod } from "./sender";
+import { registerMethods } from "./receiver";
+import { isBackgroundPage } from "webext-detect-page";
+function __getTabData() {
+    return { tabId: this.trace[0].tab.id, frameId: this.trace[0].frameId };
+}
+// First page to respond wins. Any context has this piece of information.
+export const getTabData = getMethod("__getTabData", { page: "any" });
+export function initPrivateApi() {
+    if (isBackgroundPage()) {
+        registerMethods({ __getTabData });
+    }
+}

package/distribution/index.d.ts

@@ -1,3 +1,3 @@
-export { registerMethods } from "./receiver.js";
-export { messenger, getMethod, getNotifier, backgroundTarget, } from "./sender.js";
-export { MessengerMeta, Target } from "./types.js";
+export * from "./receiver.js";
+export * from "./sender.js";
+export * from "./types.js";

package/distribution/index.js

@@ -1,2 +1,5 @@
-export { registerMethods } from "./receiver.js";
-export { messenger, getMethod, getNotifier, backgroundTarget, } from "./sender.js";
+export * from "./receiver.js";
+export * from "./sender.js";
+export * from "./types.js";
+import { initPrivateApi } from "./thisTarget";
+initPrivateApi();

package/distribution/receiver.js

@@ -1,7 +1,9 @@
 import browser from "webextension-polyfill";
 import { serializeError } from "serialize-error";
 import { messenger } from "./sender.js";
-import { handlers, isObject, MessengerError, debug, warn, __webextMessenger, } from "./shared.js";
+import { handlers, isObject, MessengerError, debug, __webextMessenger, } from "./shared.js";
+import { getContextName } from "webext-detect-page";
+import { getActionForMessage, nameThisTarget } from "./thisTarget";
 export function isMessengerMessage(message) {
     return (isObject(message) &&
         typeof message["type"] === "string" &&
@@ -14,21 +16,27 @@ function onMessageListener(message, sender) {
         // TODO: Add test for this eventuality: ignore unrelated messages
         return;
     }
-    const { type, target, args } = message;
+    // Target check must be synchronous (`await` means we're handing the message)
+    const action = getActionForMessage(message.target);
+    if (action === "ignore") {
+        return;
+    }
+    return handleMessage(message, sender, action);
+}
+// This function can only be called when the message *will* be handled locally.
+// Returning "undefined" or throwing an error will still handle it.
+async function handleMessage(message, sender, action) {
+    const { type, target, args, options: { trace } = {} } = message;
     debug(type, "↘️ received", { sender, args });
     let handleMessage;
-    if (target) {
-        if (!browser.tabs) {
-            throw new MessengerError(`Message ${type} sent to wrong context, it can't be forwarded to ${JSON.stringify(target)}`);
-        }
+    if (action === "forward") {
         debug(type, "🔀 forwarded", { sender, target });
-        handleMessage = async () => messenger(type, {}, target, ...args);
+        handleMessage = async () => messenger(type, { trace }, target, ...args);
     }
     else {
         const localHandler = handlers.get(type);
         if (!localHandler) {
-            warn(type, "⚠️ ignored, can't be handled here");
-            return;
+            throw new MessengerError(`No handler registered for ${type} in ${getContextName()}`);
         }
         debug(type, "➡️ will be handled here");
         const meta = { trace: [sender] };
@@ -46,6 +54,7 @@ function onMessageListener(message, sender) {
     });
 }
 export function registerMethods(methods) {
+    void nameThisTarget();
     for (const [type, method] of Object.entries(methods)) {
         if (handlers.has(type)) {
             throw new MessengerError(`Handler already set for ${type}`);
@@ -53,10 +62,5 @@ export function registerMethods(methods) {
         console.debug("Messenger: Registered", type);
         handlers.set(type, method);
     }
-    if ("browser" in globalThis) {
-        browser.runtime.onMessage.addListener(onMessageListener);
-    }
-    else {
-        throw new Error("`webext-messenger` requires `webextension");
-    }
+    browser.runtime.onMessage.addListener(onMessageListener);
 }

package/distribution/sender.d.ts

@@ -4,7 +4,7 @@ export declare const errorNonExistingTarget = "Could not establish connection. R
 declare function messenger<Type extends keyof MessengerMethods, Method extends MessengerMethods[Type]>(type: Type, options: {
     isNotification: true;
 }, target: Target | PageTarget, ...args: Parameters<Method>): void;
-declare function messenger<Type extends keyof MessengerMethods, Method extends MessengerMethods[Type], ReturnValue extends ReturnType<Method>>(type: Type, options: Options, target: Target | PageTarget, ...args: Parameters<Method>): ReturnValue;
+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], 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;

package/distribution/sender.js

@@ -7,12 +7,13 @@ export const errorNonExistingTarget = "Could not establish connection. Receiving
 function isMessengerResponse(response) {
     return isObject(response) && response["__webextMessenger"] === true;
 }
-function makeMessage(type, args, target) {
+function makeMessage(type, args, target, options) {
     return {
         __webextMessenger,
         type,
         args,
         target,
+        options,
     };
 }
 // Do not turn this into an `async` function; Notifications must turn `void`
@@ -30,14 +31,14 @@ async function manageMessage(type, sendMessage) {
         factor: 1.3,
         maxRetryTime: 4000,
         onFailedAttempt(error) {
-            if (!String(error === null || error === void 0 ? void 0 : error.message).startsWith(errorNonExistingTarget)) {
+            if (!String(error.message).startsWith(errorNonExistingTarget)) {
                 throw error;
             }
-            debug(type, "will retry");
+            debug(type, "will retry. Attempt", error.attemptNumber);
         },
     });
     if (!isMessengerResponse(response)) {
-        throw new MessengerError(`No handler for ${type} was registered in the receiving end`);
+        throw new MessengerError(`No handler registered for ${type} in the receiving end`);
     }
     if ("error" in response) {
         debug(type, "↘️ replied with error", response.error);
@@ -47,6 +48,7 @@ async function manageMessage(type, sendMessage) {
     return response.value;
 }
 function messenger(type, options, target, ...args) {
+    // Message goes to extension page
     if ("page" in target) {
         if (target.page === "background" && isBackgroundPage()) {
             const handler = handlers.get(type);
@@ -58,7 +60,7 @@ function messenger(type, options, target, ...args) {
         }
         const sendMessage = async () => {
             debug(type, "↗️ sending message to runtime");
-            return browser.runtime.sendMessage(makeMessage(type, args));
+            return browser.runtime.sendMessage(makeMessage(type, args, target, options));
         };
         return manageConnection(type, options, sendMessage);
     }
@@ -66,7 +68,7 @@ function messenger(type, options, target, ...args) {
     if (!browser.tabs) {
         return manageConnection(type, options, async () => {
             debug(type, "↗️ sending message to runtime");
-            return browser.runtime.sendMessage(makeMessage(type, args, target));
+            return browser.runtime.sendMessage(makeMessage(type, args, target, options));
         });
     }
     // `frameId` must be specified. If missing, the message is sent to every frame
@@ -74,7 +76,7 @@ function messenger(type, options, target, ...args) {
     // Message tab directly
     return manageConnection(type, options, async () => {
         debug(type, "↗️ sending message to tab", tabId, "frame", frameId);
-        return browser.tabs.sendMessage(tabId, makeMessage(type, args), {
+        return browser.tabs.sendMessage(tabId, makeMessage(type, args, target, options), {
             frameId,
         });
     });

package/distribution/thisTarget.d.ts

@@ -0,0 +1,12 @@
+import { Target, PageTarget, MessengerMeta } from "./types.js";
+declare type AnyTarget = Partial<Target & PageTarget>;
+export declare function getActionForMessage(target: AnyTarget): "respond" | "forward" | "ignore";
+export declare function nameThisTarget(): Promise<void>;
+declare function __getTabData(this: MessengerMeta): AnyTarget;
+declare global {
+    interface MessengerMethods {
+        __getTabData: typeof __getTabData;
+    }
+}
+export declare function initPrivateApi(): void;
+export {};

package/distribution/thisTarget.js

@@ -0,0 +1,53 @@
+import { isBackgroundPage, isContentScript } from "webext-detect-page";
+import { messenger } from "./index";
+import { registerMethods } from "./receiver.js";
+import { debug } from "./shared.js";
+// 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;
+//
+export function getActionForMessage(target) {
+    if (target.page === "any") {
+        return "respond";
+    }
+    // Content scripts only receive messages that are meant for them. In the future
+    // they'll also forward them, but that still means they need to be handled here.
+    if (isContentScript()) {
+        return "respond";
+    }
+    // We're in an extension page, but the target is not one.
+    if (!("page" in target)) {
+        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";
+    }
+    // Every `target` key must match `thisTarget`
+    const isThisTarget = Object.entries(target).every(
+    // @ts-expect-error Optional properties
+    ([key, value]) => thisTarget[key] === value);
+    if (!isThisTarget) {
+        debug("The message’s target is", target, "but this is", thisTarget);
+    }
+    return isThisTarget ? "respond" : "ignore";
+}
+export async function nameThisTarget() {
+    // Same as above: CS receives messages correctly
+    if (!thisTarget && !isContentScript()) {
+        thisTarget = await messenger("__getTabData", {}, { page: "any" });
+        thisTarget.page = location.pathname;
+    }
+}
+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 initPrivateApi() {
+    if (isBackgroundPage()) {
+        thisTarget = { page: "background" };
+        registerMethods({ __getTabData });
+    }
+}

package/distribution/types.d.ts

@@ -6,13 +6,13 @@ declare global {
         _: Method;
     }
 }
-declare type WithTarget<Method> = Method extends (...args: infer PreviousArguments) => infer TReturnValue ? (target: Target, ...args: PreviousArguments) => TReturnValue : never;
+declare type WithTarget<Method> = Method extends (...args: infer PreviousArguments) => infer TReturnValue ? (target: Target | PageTarget, ...args: PreviousArguments) => TReturnValue : never;
 declare type ActuallyOmitThisParameter<T> = T extends (...args: infer A) => infer R ? (...args: A) => R : T;
 /** Removes the `this` type and ensure it's always Promised */
 export declare type PublicMethod<Method extends ValueOf<MessengerMethods>> = Asyncify<ActuallyOmitThisParameter<Method>>;
 export declare type PublicMethodWithTarget<Method extends ValueOf<MessengerMethods>> = WithTarget<PublicMethod<Method>>;
 export interface MessengerMeta {
-    trace: Runtime.MessageSender[];
+    trace: Sender[];
 }
 declare type RawMessengerResponse = {
     value: unknown;
@@ -31,15 +31,16 @@ export interface Options {
      * @default false
      */
     isNotification?: boolean;
+    trace?: Sender[];
 }
 export declare type Message<LocalArguments extends Arguments = Arguments> = {
     type: keyof MessengerMethods;
     args: LocalArguments;
-    /** If the message is being sent to an intermediary receiver, also set the target */
-    target?: Target;
+    target: Target | PageTarget;
     /** If the message is being sent to an intermediary receiver, also set the options */
-    options?: Target;
+    options?: Options;
 };
+export declare type Sender = Runtime.MessageSender;
 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.14.0",
+  "version": "0.15.0-0",
   "description": "Browser Extension component messaging framework",
   "keywords": [],
   "repository": "pixiebrix/webext-messenger",
@@ -17,8 +17,8 @@
   },
   "scripts": {
     "build": "tsc",
-    "demo:watch": "parcel watch --no-cache --no-hmr --detailed-report 0",
-    "demo:build": "parcel build --no-cache --detailed-report 0",
+    "demo:watch": "parcel watch --no-cache --no-hmr",
+    "demo:build": "parcel build --no-cache",
     "prepack": "tsc --sourceMap false",
     "test": "eslint . && tsc --noEmit",
     "lint": "eslint .",
@@ -84,7 +84,7 @@
     "p-retry": "^4.6.1",
     "serialize-error": "^8.1.0",
     "type-fest": "^2.5.1",
-    "webext-detect-page": "^3.0.2",
+    "webext-detect-page": "^3.1.0",
     "webextension-polyfill": "^0.8.0"
   },
   "devDependencies": {
@@ -104,6 +104,7 @@
     "npm-run-all": "^4.1.5",
     "parcel": "^2.0.0",
     "typescript": "^4.4.4",
+    "webext-content-scripts": "^0.10.1",
     "xo": "^0.45.0"
   },
   "targets": {