Webextension Messages

Easily and neatly describe all communication instances between the background process and tabs in one place. Wait for the result from the message sent in the same instruction flow.

How to install and prepare

Install the library through

npm install webextension-messages

then import with

import WebextensionMessages from 'webextension-messages'

in your script file.

Usage

Actually, the library exports only one function, so when importing, you can name it however you want. For the sake of explanation, let's give it the same name as the library WebextensionMessages. Calling it creates all message-sending functions and sets up listeners.
It has such a signature:

WebextensionMessages (MessagesNames[], CommunicationId)
 =>
  MessagesActions {
    MessageName1: MessageAction1 (MessagePayload1 | MessageHandler1) => Result1
    MessageName2: MessageAction2 (MessagePayload2 | MessageHandler2) => Result2
    MessageName3: MessageAction3 (MessagePayload3 | MessageHandler3) => Result3
    ...
    stop ()
    resume ()
  }

Where:
MessagesNames - names for functions for sending messages and/or setting up handlers
MessagesActions - map of functions for sending messages and/or setting up handlers

MessageAction - function that will send the message with MessagePayload or register a MessageHandler function on the receiving end to handle such a message
MessagePayload - payload from the sender. Can be a primitive, or Array, or Object, anything that can be serialized.
MessageHandler - function to handle an incoming message
Result - return value from the message handler

CommunicationId (optional) - string identifying the declared communication, used only for removing listeners
stop () - special predefined method for stopping the work of message listeners
resume () - special predefined method for resuming the work of message listeners

stop () and resume () methods are only going to work correctly if CommunicationId is given

Important: WebextensionMessages function must be called with the exact same arguments on both sides to ensure their proper communication!

How MessageAction works

MessageAction function behaves differently depending on the argument with which it's called.

If the argument is not a function, it will be treated as MessagePayload, and MessageAction will effectively send a message. MessageAction will also become async, so you have to wait for the Result or use Promise.then.

If the argument is a MessageHandler function, this function will be registered as the handler for the message.
It will receive MessagePayload as an argument, work its way, and return any serializable Result.

Examples

Basic usage:

// shared.js =>
// code that must be shared between the background and page scripts
import WebextensionMessages from 'webextension-messages'
// setting up just one message 
export default WebextensionMessages(["multiply"]);


// background-script.js =>
import Messages from "./shared.js"
// registering the message handler on the receiving end, because the argument is a function
Messages.multiply((num) => num * 2);


// content-script.js =>
import Messages from "./shared.js";
// actually sending a message to the background and waiting for the result; the result Promise will be fulfilled with the background answer at some point
const result = await Messages.multiply(1); 
console.log(result);
// 2

Stop listening for messages, and then resume:

// shared.js =>
// setting up communication
export default WebextensionMessages(["doSomething"], "Some messages");
// give the communication an identifier "Some messages" for both sides to know what set of functions is under discussion

// background-script.js =>
import Messages from "./shared.js"
Messages.doSomething(() => "Done something");


// content-script.js =>
// stopping messaging somewhere lower in the code
Messages.stop();
// no more listening for doSomething() messages
const noResult = await Messages.doSomething();
// return value is undefined 
console.log(noResult);
// undefined


// resuming it somewhere even lower in the code
Messages.resume();
const result = await Messages.doSomething();
// message came through with an actual result
console.log(result);
// "Done something"