webext-messenger 0.22.0 → 0.23.0

package/distribution/index.d.ts

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

package/distribution/index.js

@@ -3,5 +3,6 @@ export * from "./receiver.js";
 export * from "./sender.js";
 export * from "./types.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

@@ -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.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
@@ -84,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,

package/distribution/types.d.ts

@@ -28,7 +28,7 @@ export type MessengerResponse = RawMessengerResponse & {
     /** Guarantees that the message was handled by this library */
     __webextMessenger: true;
 };
-type Arguments = any[];
+type Arguments = unknown[];
 export type Method = (this: MessengerMeta, ...args: Arguments) => Promise<unknown>;
 export interface Options {
     /**
@@ -37,6 +37,8 @@ export interface Options {
      */
     isNotification?: boolean;
     trace?: Sender[];
+    /** Automatically generated internally */
+    seq?: number;
 }
 export type Message<LocalArguments extends Arguments = Arguments> = {
     type: keyof MessengerMethods;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "webext-messenger",
-  "version": "0.22.0",
+  "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)