webext-messenger 0.22.0-5 → 0.23.0

package/distribution/index.d.ts

@@ -1,4 +1,5 @@
 export * from "./receiver.js";
 export * from "./sender.js";
 export * from "./types.js";
-export { getThisTarget, getTopLevelFrame } from "./thisTarget.js";
+export { getThisFrame, getTopLevelFrame } from "./thisTarget.js";
+export { toggleLogging } from "./shared.js";

package/distribution/index.js

@@ -2,6 +2,7 @@
 export * from "./receiver.js";
 export * from "./sender.js";
 export * from "./types.js";
-export { getThisTarget, getTopLevelFrame } from "./thisTarget.js";
+export { getThisFrame, getTopLevelFrame } from "./thisTarget.js";
+export { toggleLogging } from "./shared.js";
 import { initPrivateApi } from "./thisTarget.js";
 initPrivateApi();

package/distribution/receiver.d.ts

@@ -1,3 +1,5 @@
-import { type Message } from "./types.js";
+import { type Message, type MessengerMeta } from "./types.js";
 export declare function isMessengerMessage(message: unknown): message is Message;
 export declare function registerMethods(methods: Partial<MessengerMethods>): void;
+/** Ensure/document that the current function was called via Messenger */
+export declare function assertMessengerCall(_this: MessengerMeta): asserts _this is MessengerMeta;

package/distribution/receiver.js

@@ -1,7 +1,7 @@
 import { serializeError } from "serialize-error";
 import { getContextName } from "webext-detect-page";
 import { messenger } from "./sender.js";
-import { isObject, MessengerError, debug, __webextMessenger, } from "./shared.js";
+import { isObject, MessengerError, log, __webextMessenger } from "./shared.js";
 import { getActionForMessage } from "./thisTarget.js";
 import { didUserRegisterMethods, handlers } from "./handlers.js";
 export function isMessengerMessage(message) {
@@ -29,16 +29,16 @@ async function handleMessage(message, sender,
 // Once messages reach this function they cannot be "ignored", they're already being handled
 action) {
     const { type, target, args, options = {} } = message;
-    const { trace = [] } = options;
+    const { trace = [], seq } = options;
     trace.push(sender);
     const meta = { trace };
     let handleMessage;
     if (action === "forward") {
-        debug(type, "🔀 forwarded", { sender, target });
+        log.debug(type, seq, "🔀 forwarded", { sender, target });
         handleMessage = async () => messenger(type, meta, target, ...args);
     }
     else {
-        debug(type, "↘️ received in", getContextName(), {
+        log.debug(type, seq, "↘️ received in", getContextName(), {
             sender,
             args,
             wasForwarded: trace.length > 1,
@@ -59,7 +59,7 @@ action) {
         // and https://github.com/mozilla/webextension-polyfill/issues/210
         error: serializeError(error),
     }));
-    debug(type, "↗️ responding", response);
+    log.debug(type, seq, "↗️ responding", response);
     return { ...response, __webextMessenger };
 }
 export function registerMethods(methods) {
@@ -67,8 +67,12 @@ export function registerMethods(methods) {
         if (handlers.has(type)) {
             throw new MessengerError(`Handler already set for ${type}`);
         }
-        debug("Registered", type);
+        log.debug("Registered", type);
         handlers.set(type, method);
     }
     browser.runtime.onMessage.addListener(onMessageListener);
 }
+/** Ensure/document that the current function was called via Messenger */
+export function assertMessengerCall(_this
+// eslint-disable-next-line @typescript-eslint/no-empty-function -- TypeScript already does this, it's a documentation-only call
+) { }

package/distribution/sender.js

@@ -2,7 +2,7 @@ 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, debug, warn, } from "./shared.js";
+import { isObject, MessengerError, __webextMessenger, log } 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
@@ -12,6 +12,9 @@ export const errorTabDoesntExist = "The tab doesn't exist";
 function isMessengerResponse(response) {
     return isObject(response) && response["__webextMessenger"] === true;
 }
+function attemptLog(attemptCount) {
+    return attemptCount > 1 ? `(try: ${attemptCount})` : "";
+}
 function makeMessage(type, args, target, options) {
     return {
         __webextMessenger,
@@ -22,17 +25,17 @@ function makeMessage(type, args, target, options) {
     };
 }
 // Do not turn this into an `async` function; Notifications must turn `void`
-function manageConnection(type, options, target, sendMessage) {
-    if (!options.isNotification) {
-        return manageMessage(type, target, sendMessage);
+function manageConnection(type, { seq, isNotification }, target, sendMessage) {
+    if (!isNotification) {
+        return manageMessage(type, target, seq, sendMessage);
     }
-    void sendMessage().catch((error) => {
-        debug(type, "notification failed", { error });
+    void sendMessage(1).catch((error) => {
+        log.debug(type, seq, "notification failed", { error });
     });
 }
-async function manageMessage(type, target, sendMessage) {
-    const response = await pRetry(async () => {
-        const response = await sendMessage();
+async function manageMessage(type, target, seq, sendMessage) {
+    const response = await pRetry(async (attemptCount) => {
+        const response = await sendMessage(attemptCount);
         if (isMessengerResponse(response)) {
             return response;
         }
@@ -74,7 +77,7 @@ async function manageMessage(type, target, sendMessage) {
                     !(await doesTabExist(target.tabId))) {
                     throw new Error(errorTabDoesntExist);
                 }
-                debug(type, "will retry. Attempt", error.attemptNumber);
+                log.debug(type, seq, "will retry. Attempt", error.attemptNumber);
             }
             else {
                 throw error;
@@ -87,41 +90,44 @@ async function manageMessage(type, target, sendMessage) {
         throw error;
     });
     if ("error" in response) {
-        debug(type, "↘️ replied with error", response.error);
+        log.debug(type, seq, "↘️ replied with error", response.error);
         throw deserializeError(response.error);
     }
-    debug(type, "↘️ replied successfully", response.value);
+    log.debug(type, seq, "↘️ replied successfully", response.value);
     return response.value;
 }
 function messenger(type, options, target, ...args) {
+    // Not a UID. Signal / console noise compromise. They repeat every 100 seconds
+    options.seq = Date.now() % 100000;
+    const { seq } = options;
     // Message goes to extension page
     if ("page" in target) {
         if (target.page === "background" && isBackground()) {
             const handler = handlers.get(type);
             if (handler) {
-                warn(type, "is being handled locally");
+                log.warn(type, seq, "is being handled locally");
                 return handler.apply({ trace: [] }, args);
             }
             throw new MessengerError("No handler registered locally for " + type);
         }
-        const sendMessage = async () => {
-            debug(type, "↗️ sending message to runtime");
+        const sendMessage = async (attemptCount) => {
+            log.debug(type, seq, "↗️ sending message to runtime", attemptLog(attemptCount));
             return browser.runtime.sendMessage(makeMessage(type, args, target, options));
         };
         return manageConnection(type, options, target, sendMessage);
     }
     // Contexts without direct Tab access must go through background
     if (!browser.tabs) {
-        return manageConnection(type, options, target, async () => {
-            debug(type, "↗️ sending message to runtime");
+        return manageConnection(type, options, target, async (attemptCount) => {
+            log.debug(type, seq, "↗️ sending message to runtime", attemptLog(attemptCount));
             return browser.runtime.sendMessage(makeMessage(type, args, target, options));
         });
     }
     // `frameId` must be specified. If missing, the message is sent to every frame
     const { tabId, frameId = 0 } = target;
     // Message tab directly
-    return manageConnection(type, options, target, async () => {
-        debug(type, "↗️ sending message to tab", tabId, "frame", frameId);
+    return manageConnection(type, options, target, async (attemptCount) => {
+        log.debug(type, seq, "↗️ sending message to tab", tabId, "frame", frameId, attemptLog(attemptCount));
         return browser.tabs.sendMessage(tabId, makeMessage(type, args, target, options), {
             frameId,
         });

package/distribution/shared.d.ts

@@ -1,5 +1,5 @@
 import { type JsonObject } from "type-fest";
-declare type ErrorObject = {
+type ErrorObject = {
     name?: string;
     stack?: string;
     message?: string;
@@ -10,8 +10,11 @@ export declare function isObject(value: unknown): value is Record<string, unknow
 export declare class MessengerError extends Error {
     name: string;
 }
-export declare const debug: (...args: any[]) => void;
-export declare const warn: (...args: any[]) => void;
+export declare const log: {
+    debug: (...args: any[]) => void;
+    warn: (...args: any[]) => void;
+};
+export declare function toggleLogging(enabled: boolean): void;
 export declare function isErrorObject(error: unknown): error is ErrorObject;
 export declare function delay(milliseconds: number): Promise<void>;
 export declare function once<Callback extends (...arguments_: unknown[]) => unknown>(function_: Callback): Callback;

package/distribution/shared.js

@@ -1,20 +1,11 @@
 import { errorConstructors } from "serialize-error";
-const logging = (() => {
-    try {
-        // @ts-expect-error it would break Webpack
-        return process.env.WEBEXT_MESSENGER_LOGGING === "true";
-    }
-    catch {
-        return false;
-    }
-})();
-function noop() {
-    /* */
-}
 export const __webextMessenger = true;
 export function isObject(value) {
     return typeof value === "object" && value !== null;
 }
+function noop() {
+    /* */
+}
 export class MessengerError extends Error {
     constructor() {
         super(...arguments);
@@ -29,8 +20,15 @@ export class MessengerError extends Error {
 // @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;
+const debug = console.debug.bind(console, "Messenger:");
+const warn = console.warn.bind(console, "Messenger:");
+export const log = { debug, warn };
+export function toggleLogging(enabled) {
+    log.debug = enabled ? debug : noop;
+    log.warn = enabled ? warn : noop;
+}
+// Default to "no logs"
+toggleLogging(false);
 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?.message === "string";

package/distribution/thisTarget.d.ts

@@ -1,6 +1,6 @@
-import { type AnyTarget, type KnownTarget, type TopLevelFrame, type Message, type MessengerMeta, type Sender } from "./types.js";
+import { type AnyTarget, type TopLevelFrame, type Message, type MessengerMeta, type Sender, type FrameTarget } from "./types.js";
 export declare function getActionForMessage(from: Sender, message: Message): "respond" | "forward" | "ignore";
 export declare function __getTabData(this: MessengerMeta): AnyTarget;
-export declare function getThisTarget(): Promise<KnownTarget>;
+export declare function getThisFrame(): Promise<FrameTarget>;
 export declare function getTopLevelFrame(): Promise<TopLevelFrame>;
 export declare function initPrivateApi(): void;

package/distribution/thisTarget.js

@@ -1,7 +1,7 @@
 import { isBackground, isContentScript, isExtensionContext, } from "webext-detect-page";
 import { messenger } from "./sender.js";
 import { registerMethods } from "./receiver.js";
-import { debug, MessengerError, once } from "./shared.js";
+import { log, MessengerError, once } 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
@@ -29,16 +29,17 @@ const thisTarget = isBackground()
     ? { page: "background" }
     : {
         get page() {
-            return location.pathname + location.search;
+            // Extension pages have relative URLs to simplify comparison
+            const origin = location.protocol.startsWith("http")
+                ? location.origin
+                : "";
+            // Don't use the hash
+            return origin + 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";
+isBackground() ? "not-needed" : "needed";
 function compareTargets(to, thisTarget) {
     for (const [key, value] of Object.entries(to)) {
         if (thisTarget[key] === value) {
@@ -83,7 +84,7 @@ export function getActionForMessage(from, message) {
     // Every `target` key must match `thisTarget`
     const isThisTarget = compareTargets(to, thisTarget);
     if (!isThisTarget) {
-        debug(message.type, "🤫 ignored due to target mismatch", {
+        log.debug(message.type, "🤫 ignored due to target mismatch", {
             requestedTarget: to,
             thisTarget,
             tabDataStatus,
@@ -112,15 +113,17 @@ const storeTabData = once(async () => {
 export function __getTabData() {
     return { tabId: this.trace[0]?.tab?.id, frameId: this.trace[0]?.frameId };
 }
-export async function getThisTarget() {
+export async function getThisFrame() {
     await storeTabData(); // It should already have been called by we still need to await it
-    return thisTarget;
+    const { tabId, frameId } = thisTarget;
+    if (typeof tabId !== "number" || typeof frameId !== "number") {
+        throw new TypeError("This target is not in a frame");
+    }
+    // Rebuild object to return exactly these two properties and nothing more
+    return { tabId, frameId };
 }
 export async function getTopLevelFrame() {
-    const { tabId } = await getThisTarget();
-    if (typeof tabId !== "number") {
-        throw new TypeError("This target is not in a tab");
-    }
+    const { tabId } = await getThisFrame();
     return {
         tabId,
         frameId: 0,

package/distribution/types.d.ts

@@ -1,72 +1,83 @@
 import { type Runtime } from "webextension-polyfill";
 import { type Asyncify, type ValueOf } from "type-fest";
 import { type ErrorObject } from "serialize-error";
+/**
+ * @file Target types are a bit overlapping. That's because some are "request" targets
+ * and some are "known" targets. The difference is that you could "request" `{tabId: 1}`, but you "know" that a specific target is exactly `{tabId: 1, frameId: 5}`
+ * TODO: Cleanup, clarify, deduplicate Target types
+ */
 declare global {
     interface MessengerMethods {
         _: Method;
     }
 }
-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;
+type WithTarget<Method> = Method extends (...args: infer PreviousArguments) => infer TReturnValue ? (target: Target | PageTarget, ...args: PreviousArguments) => TReturnValue : never;
+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 declare type MessengerMeta = {
+export type PublicMethod<Method extends ValueOf<MessengerMethods>> = Asyncify<ActuallyOmitThisParameter<Method>>;
+export type PublicMethodWithTarget<Method extends ValueOf<MessengerMethods>> = WithTarget<PublicMethod<Method>>;
+export interface MessengerMeta {
     trace: Sender[];
-};
-declare type RawMessengerResponse = {
+}
+type RawMessengerResponse = {
     value: unknown;
 } | {
     error: ErrorObject;
 };
-export declare type MessengerResponse = RawMessengerResponse & {
+export type MessengerResponse = RawMessengerResponse & {
     /** Guarantees that the message was handled by this library */
     __webextMessenger: true;
 };
-declare type Arguments = any[];
-export declare type Method = (this: MessengerMeta, ...args: Arguments) => Promise<unknown>;
-export declare type Options = {
+type Arguments = unknown[];
+export type Method = (this: MessengerMeta, ...args: Arguments) => Promise<unknown>;
+export interface Options {
     /**
      * "Notifications" won't await the response, return values, attempt retries, nor throw errors
      * @default false
      */
     isNotification?: boolean;
     trace?: Sender[];
-};
-export declare type Message<LocalArguments extends Arguments = Arguments> = {
+    /** Automatically generated internally */
+    seq?: number;
+}
+export type Message<LocalArguments extends Arguments = Arguments> = {
     type: keyof MessengerMethods;
     args: LocalArguments;
     target: Target | PageTarget;
     /** If the message is being sent to an intermediary receiver, also set the options */
     options?: Options;
 };
-export declare type Sender = Runtime.MessageSender & {
+export type Sender = Runtime.MessageSender & {
     origin?: string;
 };
-export declare type MessengerMessage = Message & {
+export type MessengerMessage = Message & {
     /** Guarantees that a message is meant to be handled by this library */
     __webextMessenger: true;
 };
-export declare type AnyTarget = {
+export interface AnyTarget {
     tabId?: number | "this";
     frameId?: number;
     page?: string;
-};
-export declare type TopLevelFrame = {
+}
+export interface TopLevelFrame {
     tabId: number;
     frameId: 0;
-};
-export declare type KnownTarget = {
+}
+export interface FrameTarget {
+    tabId: number;
+    frameId: number;
+}
+export interface KnownTarget {
     tabId?: number;
     frameId?: number;
     page: string;
-};
-export declare type Target = {
+}
+export interface Target {
     tabId: number;
     frameId?: number;
-};
-export declare type PageTarget = {
+}
+export interface PageTarget {
     tabId?: number | "this";
     page: string;
-};
+}
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "webext-messenger",
-  "version": "0.22.0-5",
+  "version": "0.23.0",
   "description": "Browser Extension component messaging framework",
   "keywords": [],
   "repository": "pixiebrix/webext-messenger",
@@ -10,7 +10,7 @@
   "main": "distribution/index.js",
   "scripts": {
     "build": "tsc",
-    "demo:watch": "WEBEXT_MESSENGER_LOGGING=true parcel watch --no-cache --no-hmr",
+    "demo:watch": "parcel watch --no-cache --no-hmr",
     "demo:build": "parcel build --no-cache",
     "prepack": "tsc --sourceMap false",
     "test": "eslint . && tsc --noEmit",
@@ -19,30 +19,30 @@
     "watch": "tsc --watch"
   },
   "dependencies": {
-    "p-retry": "^5.1.1",
-    "serialize-error": "^11.0.0",
-    "type-fest": "^3.2.0",
-    "webext-detect-page": "^4.0.1",
-    "webext-tools": "^1.1.0"
+    "p-retry": "^6.0.0",
+    "serialize-error": "^11.0.2",
+    "type-fest": "^4.3.1",
+    "webext-detect-page": "^4.1.1",
+    "webext-tools": "^1.1.3"
   },
   "devDependencies": {
-    "@parcel/config-webextension": "^2.8.0",
-    "@sindresorhus/tsconfig": "^3.0.1",
-    "@types/chrome": "^0.0.203",
-    "@types/tape": "^4.13.2",
-    "@types/webextension-polyfill": "^0.9.0",
+    "@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",
     "buffer": "^6.0.3",
-    "eslint": "^8.28.0",
-    "eslint-config-pixiebrix": "^0.20.0",
+    "eslint": "^8.29.0",
+    "eslint-config-pixiebrix": "^0.27.2",
     "events": "^3.3.0",
     "npm-run-all": "^4.1.5",
-    "parcel": "^2.6.0",
+    "parcel": "^2.6.2",
     "path-browserify": "^1.0.1",
     "process": "^0.11.10",
     "stream-browserify": "^3.0.0",
-    "tape": "^5.5.3",
-    "typescript": "^4.9.3",
-    "webext-content-scripts": "^1.0.2",
+    "tape": "^5.6.6",
+    "typescript": "^5.2.2",
+    "webext-content-scripts": "^2.5.5",
     "webextension-polyfill": "^0.10.0"
   },
   "alias": {

package/readme.md

@@ -3,7 +3,7 @@
 [badge-gzip]: https://img.shields.io/bundlephobia/minzip/webext-messenger.svg?label=gzipped
 [link-bundlephobia]: https://bundlephobia.com/result?p=webext-messenger
 
-> WIP: Browser Extension component messaging framework
+> Browser Extension component messaging framework
 
 ## Install
 
@@ -17,4 +17,9 @@ import messenger from "webext-messenger";
 
 ## Context
 
-- [Initial considerations for this library](https://github.com/pixiebrix/webext-messenger/issues/1)
+- [Initial considertions for this library](https://github.com/pixiebrix/webext-messenger/issues/1)
+
+
+## npm publishing
+
+Collaborators can publish a new version of what's on main [via "workflow_dispatch"](https://github.blog/changelog/2020-07-06-github-actions-manual-triggers-with-workflow_dispatch/) under [Actions » Publish](https://github.com/pixiebrix/webext-messenger/actions/workflows/npm-publish.yml)