webextension-messages 1.0.2 → 1.0.4

package/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2026 Morozov Igor (ismorozs)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,89 @@
+# 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
+```sh
+npm install webextension-messages
+```
+then import with
+```js
+import WebextensionMessages from 'webextension-messages'
+```
+in your script file.
+
+## Usage
+Library has only one method ```setup```, which creates all message-sending functions and sets up listeners.  
+With such a signature:
+```js
+WebextensionMessages.setup (
+  MessageHandlersMap {
+    MessageSenderFunctionName1: MessageHandler1 (...MessageParameters1) => ResultToSendBack1
+    MessageSenderFunctionName2: MessageHandler2 (...MessageParameters2) => ResultToSendBack2
+    MessageSenderFunctionName3: MessageHandler3 (...MessageParameters3) => ResultToSendBack3
+    ...
+  },
+  CommunicationId
+) =>
+  MessageSendersMap {
+    MessageSenderFunctionName1: (...MessageParameters1) => PromiseWithResult1
+    MessageSenderFunctionName2: (...MessageParameters2) => PromiseWithResult2
+    MessageSenderFunctionName3: (...MessageParameters3) => PromiseWithResult3
+    ...
+    stopCommunication ()
+  }
+```
+Where:  
+```MessageHandlersMap``` - map linking sender and handler function on the receiving end  
+```MessageSendersMap``` - map of sender functions  
+  
+```MessageSenderFunctionName``` - name of the function that will send the message  
+```MessageHandler``` - function that will handle the message on the receiving end  
+```MessageParameters``` - payload to the sender function and parameters for the handler function   
+```ResultToSendBack``` - return value of the handler function that will be sent back to the sender  
+```PromiseWithResult``` - return value of the sender function, a promise that will be resolved to ```ResultToSendBack``` from the receiver  
+
+```CommunicationId``` (optional) - string identifying the declared communication, used only for removing listeners  
+```stopCommunication ()``` - special predefined method for stopping messaging and removing listeners, works only if ```CommunicationId``` is given  
+
+  
+
+  
+**Important: the exact same ```setup``` method with the exact same arguments must run on both sides to ensure their proper communication!**
+
+## Examples
+Basic usage:
+```js
+// shared.js =>
+// code that must be shared between the background and page scripts
+import WebextensionMessages from 'webextension-messages'
+const { sum } = WebextensionMessages.setup({
+  sum: (x, y) => x + y, 
+})
+export { sum };
+
+
+// background-script.js =>
+// if there's no sender functions for one of the ends, just import the file to set up listeners
+import from "./shared.js"
+
+
+// content-script.js =>
+import { sum } from "./shared.js"; // import sender function
+const result = await sum(1, 2); // send a message to the background and wait for the response
+console.log(result);
+// 3
+```
+
+Stop messaging and remove listeners:
+```js
+// setting up communication
+cosnt { stopCommunication } = WebextensionMessages.setup({
+  sum: (x, y) => x + y, 
+}, "Math correspondence");
+// give the communication an identifier for both sides to know what set of functions is under discussion
+
+// stopping it somewhere lower in the code
+stopCommunication();
+// no more listening for sum() message 
+```