js-broadcast-channel 1.3.1

package/README.md

@@ -0,0 +1,115 @@
+# broadcaster-channel
+
+A lightweight TypeScript library for cross-tab communication using the BroadcastChannel API. This package provides a simple interface for sending and receiving messages between different browser tabs or windows.
+
+## Installation
+
+npm install broadcaster-channel
+
+## Features
+
+- 🚀 Simple and intuitive API
+- 📦 TypeScript support out of the box
+- 🔄 Cross-tab communication
+- 🎯 Message-specific callbacks
+- ⚡ Lightweight with zero dependencies
+- 🎭 Built-in message handlers and lifecycle hooks
+
+## Usage
+
+### Basic Usage
+
+```typescript
+import { BroadcastJS } from 'broadcaster-channel';
+// Initialize BroadcastJS with a channel name
+const broadcast = new BroadcastJS('my-channel');
+// Send a message
+broadcast.postMessage({
+message: 'update-count',
+data: { count: 42 }
+});
+// Listen for messages
+broadcast.onMessage('update-count', (message) => {
+console.log('Received count:', message.data.count);
+});
+
+```
+
+## API Reference
+
+### Constructor
+
+```typescript
+new BroadcastJS(name: string, handlers?: BroadcastHandlers)
+```
+
+
+#### Handlers (Optional)
+- `onBeforeSendMessage`: Called before a message is sent
+- `onAfterSendMessage`: Called after a message is sent
+- `onBeforePostMessage`: Called before posting a message
+- `onAfterPostMessage`: Called after posting a message
+- `onBeforeClose`: Called before closing the channel
+- `onAfterClose`: Called after closing the channel
+- `onError`: Called when an error occurs
+
+### Methods
+
+#### `postMessage(message: Message)`
+Sends a message to all other tabs/windows listening on the same channel.
+
+
+```typescript
+interface Message<T = unknown> {
+message: string;
+data: T;
+}
+```
+
+#### `onMessage<T>(messageName: string, callback: (message: Message<T>) => void)`
+Registers a callback for a specific message type.
+
+#### `close()`
+Closes the broadcast channel and cleans up resources.
+
+#### `hasListeners(messageName: string)`
+Checks if there are any listeners for a specific message.
+
+#### `canBrowserSupportBroadcastJS()`
+Checks if the browser supports the BroadcastChannel API.
+
+#### `removeMessage(messageName: string)`
+Removes a message listener.
+
+## Example with Handlers
+
+```typescript
+const broadcast = new BroadcastJS('my-channel', {
+onBeforeSendMessage: (message) => {
+console.log('About to send:', message);
+},
+onAfterSendMessage: (message) => {
+console.log('Message sent:', message);
+},
+onError: (message) => {
+console.error('Error processing message:', message);
+}
+});
+
+```
+
+## Browser Support
+
+This package requires browser support for the BroadcastChannel API. Check [Can I Use](https://caniuse.com/?search=broadcastchannel) for browser compatibility.
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+## License
+
+ISC
+
+## Author
+
+Alireza Valipour

package/dist/index.d.mts

@@ -0,0 +1,71 @@
+interface IBroadcastJS {
+    close: () => void;
+    postMessage: (message: Message) => void;
+    onMessage: (messageName: string, onReceive: (message: Message) => void) => void;
+    canBrowserSupportBroadcastJS: () => boolean;
+    hasListeners: (messageName: string) => boolean;
+}
+interface Message<T = unknown> {
+    message: string;
+    data: T;
+    isInternal?: boolean;
+}
+interface BroadcastHandlers {
+    onBeforeSendMessage?: (message: Message) => void;
+    onAfterSendMessage?: (message: Message) => void;
+    onBeforePostMessage?: (message: Message) => void;
+    onAfterPostMessage?: (message: Message) => void;
+    onBeforeClose?: () => void;
+    onAfterClose?: () => void;
+    onError?: (message: Message) => void;
+}
+declare class BroadcastJS implements IBroadcastJS {
+    private static bcInstance;
+    private static bcJSInstance;
+    private static messageCallbacks;
+    private static handlers;
+    constructor(name: string, handlers?: BroadcastHandlers);
+    /**
+     * Closes the broadcast channel.
+     *
+     * @returns {void}
+     *
+     * @example
+     * const broadcast = new BroadcastJS("channelName");
+     * broadcast.close();
+     */
+    close(): void;
+    /**
+     * Posts a message to the broadcast channel.
+     *
+     * @param {Message} message - The message to post.
+     * @returns {void}
+     *
+     * @example
+     * const broadcast = new BroadcastJS("channelName");
+     * broadcast.postMessage({ message: "message", data: { count: 0 } });
+     */
+    postMessage(message: Message): void;
+    /**
+     * Calls a callback when a message is received.
+     *
+     * @param {string} messageName - The name of the message to call the callback for.
+     * @param {function} onRecieve - The callback to call when a message is received.
+     * @returns {void}
+     *
+     * @example
+     * const broadcast = new BroadcastJS("channelName");
+     * broadcast.onMessage("name", (message) => {
+     *     console.log(message);
+     * });
+     */
+    onMessage<T>(messageName: string, onRecieve: (message: Message<T>) => void): void;
+    removeMessage(messageName: string): void;
+    canBrowserSupportBroadcastJS(): boolean;
+    hasListeners(messageName: string): boolean;
+    private static internalMessage;
+    private createMessage;
+    private createSerializedMessage;
+}
+
+export { BroadcastJS, type Message };

package/dist/index.d.ts

@@ -0,0 +1,71 @@
+interface IBroadcastJS {
+    close: () => void;
+    postMessage: (message: Message) => void;
+    onMessage: (messageName: string, onReceive: (message: Message) => void) => void;
+    canBrowserSupportBroadcastJS: () => boolean;
+    hasListeners: (messageName: string) => boolean;
+}
+interface Message<T = unknown> {
+    message: string;
+    data: T;
+    isInternal?: boolean;
+}
+interface BroadcastHandlers {
+    onBeforeSendMessage?: (message: Message) => void;
+    onAfterSendMessage?: (message: Message) => void;
+    onBeforePostMessage?: (message: Message) => void;
+    onAfterPostMessage?: (message: Message) => void;
+    onBeforeClose?: () => void;
+    onAfterClose?: () => void;
+    onError?: (message: Message) => void;
+}
+declare class BroadcastJS implements IBroadcastJS {
+    private static bcInstance;
+    private static bcJSInstance;
+    private static messageCallbacks;
+    private static handlers;
+    constructor(name: string, handlers?: BroadcastHandlers);
+    /**
+     * Closes the broadcast channel.
+     *
+     * @returns {void}
+     *
+     * @example
+     * const broadcast = new BroadcastJS("channelName");
+     * broadcast.close();
+     */
+    close(): void;
+    /**
+     * Posts a message to the broadcast channel.
+     *
+     * @param {Message} message - The message to post.
+     * @returns {void}
+     *
+     * @example
+     * const broadcast = new BroadcastJS("channelName");
+     * broadcast.postMessage({ message: "message", data: { count: 0 } });
+     */
+    postMessage(message: Message): void;
+    /**
+     * Calls a callback when a message is received.
+     *
+     * @param {string} messageName - The name of the message to call the callback for.
+     * @param {function} onRecieve - The callback to call when a message is received.
+     * @returns {void}
+     *
+     * @example
+     * const broadcast = new BroadcastJS("channelName");
+     * broadcast.onMessage("name", (message) => {
+     *     console.log(message);
+     * });
+     */
+    onMessage<T>(messageName: string, onRecieve: (message: Message<T>) => void): void;
+    removeMessage(messageName: string): void;
+    canBrowserSupportBroadcastJS(): boolean;
+    hasListeners(messageName: string): boolean;
+    private static internalMessage;
+    private createMessage;
+    private createSerializedMessage;
+}
+
+export { BroadcastJS, type Message };

package/dist/index.js

@@ -0,0 +1,156 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  BroadcastJS: () => BroadcastJS
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/broadcast.ts
+var _BroadcastJS = class _BroadcastJS {
+  constructor(name, handlers) {
+    if (!this.canBrowserSupportBroadcastJS()) {
+      throw new Error("BroadcastChannel API is not supported in this browser");
+    }
+    if (_BroadcastJS.bcJSInstance) {
+      return _BroadcastJS.bcJSInstance;
+    }
+    if (!_BroadcastJS.bcInstance) {
+      const broadcast = new BroadcastChannel(name);
+      _BroadcastJS.bcInstance = broadcast;
+    }
+    _BroadcastJS.handlers = handlers || {};
+    _BroadcastJS.bcJSInstance = this;
+    return _BroadcastJS.bcJSInstance;
+  }
+  /**
+   * Closes the broadcast channel.
+   *
+   * @returns {void}
+   *
+   * @example
+   * const broadcast = new BroadcastJS("channelName");
+   * broadcast.close();
+   */
+  close() {
+    var _a, _b, _c, _d;
+    (_b = (_a = _BroadcastJS.handlers).onBeforeClose) == null ? void 0 : _b.call(_a);
+    _BroadcastJS.bcInstance.close();
+    _BroadcastJS.messageCallbacks.clear();
+    _BroadcastJS.handlers = {};
+    (_d = (_c = _BroadcastJS.handlers).onAfterClose) == null ? void 0 : _d.call(_c);
+  }
+  /**
+   * Posts a message to the broadcast channel.
+   *
+   * @param {Message} message - The message to post.
+   * @returns {void}
+   * 
+   * @example
+   * const broadcast = new BroadcastJS("channelName");
+   * broadcast.postMessage({ message: "message", data: { count: 0 } });
+   */
+  postMessage(message) {
+    var _a, _b, _c, _d;
+    const serializedMessage = this.createSerializedMessage(message.message, message.data, false);
+    (_b = (_a = _BroadcastJS.handlers).onBeforePostMessage) == null ? void 0 : _b.call(_a, message);
+    _BroadcastJS.bcInstance.postMessage(serializedMessage);
+    (_d = (_c = _BroadcastJS.handlers).onAfterPostMessage) == null ? void 0 : _d.call(_c, message);
+  }
+  /**
+   * Calls a callback when a message is received.
+   *
+   * @param {string} messageName - The name of the message to call the callback for.
+   * @param {function} onRecieve - The callback to call when a message is received.
+   * @returns {void}
+   *
+   * @example
+   * const broadcast = new BroadcastJS("channelName");
+   * broadcast.onMessage("name", (message) => {
+   *     console.log(message);
+   * });
+   */
+  onMessage(messageName, onRecieve) {
+    _BroadcastJS.messageCallbacks.set(messageName, onRecieve);
+    _BroadcastJS.bcInstance.onmessage = (event) => {
+      var _a, _b, _c, _d, _e, _f, _g;
+      const receivedMessage = JSON.parse(event.data);
+      const message = this.createMessage(receivedMessage.message, receivedMessage.data, (_a = receivedMessage.isInternal) != null ? _a : false);
+      if (message.isInternal) {
+        _BroadcastJS.internalMessage(message.message, message);
+        return;
+      }
+      const callback = _BroadcastJS.messageCallbacks.get(receivedMessage.message);
+      if (callback) {
+        (_c = (_b = _BroadcastJS.handlers).onBeforeSendMessage) == null ? void 0 : _c.call(_b, message);
+        callback(message);
+        (_e = (_d = _BroadcastJS.handlers).onAfterSendMessage) == null ? void 0 : _e.call(_d, message);
+      } else {
+        (_g = (_f = _BroadcastJS.handlers).onError) == null ? void 0 : _g.call(_f, message);
+        console.error("No callback found for message with name: ", receivedMessage.message);
+      }
+    };
+  }
+  removeMessage(messageName) {
+    const serializedMessage = this.createSerializedMessage("removeMessage" /* RemoveMessage */, messageName, true);
+    _BroadcastJS.bcInstance.postMessage(serializedMessage);
+    _BroadcastJS.messageCallbacks.delete(messageName);
+  }
+  canBrowserSupportBroadcastJS() {
+    return typeof BroadcastChannel !== "undefined";
+  }
+  hasListeners(messageName) {
+    return _BroadcastJS.messageCallbacks.has(messageName);
+  }
+  static internalMessage(messageName, message) {
+    let isInternalMessage = false;
+    switch (messageName) {
+      case "removeMessage" /* RemoveMessage */:
+        _BroadcastJS.messageCallbacks.delete(message.data);
+        isInternalMessage = true;
+        break;
+      default:
+        isInternalMessage = false;
+        break;
+    }
+    return isInternalMessage;
+  }
+  // manual serialization to make it predictable
+  createMessage(name, data, isInternal) {
+    const message = {
+      message: name,
+      data,
+      isInternal
+    };
+    return message;
+  }
+  createSerializedMessage(name, data, isInternal) {
+    const message = this.createMessage(name, data, isInternal);
+    return JSON.stringify(message);
+  }
+};
+_BroadcastJS.messageCallbacks = /* @__PURE__ */ new Map();
+_BroadcastJS.handlers = {};
+var BroadcastJS = _BroadcastJS;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  BroadcastJS
+});

package/dist/index.mjs

@@ -0,0 +1,129 @@
+// src/broadcast.ts
+var _BroadcastJS = class _BroadcastJS {
+  constructor(name, handlers) {
+    if (!this.canBrowserSupportBroadcastJS()) {
+      throw new Error("BroadcastChannel API is not supported in this browser");
+    }
+    if (_BroadcastJS.bcJSInstance) {
+      return _BroadcastJS.bcJSInstance;
+    }
+    if (!_BroadcastJS.bcInstance) {
+      const broadcast = new BroadcastChannel(name);
+      _BroadcastJS.bcInstance = broadcast;
+    }
+    _BroadcastJS.handlers = handlers || {};
+    _BroadcastJS.bcJSInstance = this;
+    return _BroadcastJS.bcJSInstance;
+  }
+  /**
+   * Closes the broadcast channel.
+   *
+   * @returns {void}
+   *
+   * @example
+   * const broadcast = new BroadcastJS("channelName");
+   * broadcast.close();
+   */
+  close() {
+    var _a, _b, _c, _d;
+    (_b = (_a = _BroadcastJS.handlers).onBeforeClose) == null ? void 0 : _b.call(_a);
+    _BroadcastJS.bcInstance.close();
+    _BroadcastJS.messageCallbacks.clear();
+    _BroadcastJS.handlers = {};
+    (_d = (_c = _BroadcastJS.handlers).onAfterClose) == null ? void 0 : _d.call(_c);
+  }
+  /**
+   * Posts a message to the broadcast channel.
+   *
+   * @param {Message} message - The message to post.
+   * @returns {void}
+   * 
+   * @example
+   * const broadcast = new BroadcastJS("channelName");
+   * broadcast.postMessage({ message: "message", data: { count: 0 } });
+   */
+  postMessage(message) {
+    var _a, _b, _c, _d;
+    const serializedMessage = this.createSerializedMessage(message.message, message.data, false);
+    (_b = (_a = _BroadcastJS.handlers).onBeforePostMessage) == null ? void 0 : _b.call(_a, message);
+    _BroadcastJS.bcInstance.postMessage(serializedMessage);
+    (_d = (_c = _BroadcastJS.handlers).onAfterPostMessage) == null ? void 0 : _d.call(_c, message);
+  }
+  /**
+   * Calls a callback when a message is received.
+   *
+   * @param {string} messageName - The name of the message to call the callback for.
+   * @param {function} onRecieve - The callback to call when a message is received.
+   * @returns {void}
+   *
+   * @example
+   * const broadcast = new BroadcastJS("channelName");
+   * broadcast.onMessage("name", (message) => {
+   *     console.log(message);
+   * });
+   */
+  onMessage(messageName, onRecieve) {
+    _BroadcastJS.messageCallbacks.set(messageName, onRecieve);
+    _BroadcastJS.bcInstance.onmessage = (event) => {
+      var _a, _b, _c, _d, _e, _f, _g;
+      const receivedMessage = JSON.parse(event.data);
+      const message = this.createMessage(receivedMessage.message, receivedMessage.data, (_a = receivedMessage.isInternal) != null ? _a : false);
+      if (message.isInternal) {
+        _BroadcastJS.internalMessage(message.message, message);
+        return;
+      }
+      const callback = _BroadcastJS.messageCallbacks.get(receivedMessage.message);
+      if (callback) {
+        (_c = (_b = _BroadcastJS.handlers).onBeforeSendMessage) == null ? void 0 : _c.call(_b, message);
+        callback(message);
+        (_e = (_d = _BroadcastJS.handlers).onAfterSendMessage) == null ? void 0 : _e.call(_d, message);
+      } else {
+        (_g = (_f = _BroadcastJS.handlers).onError) == null ? void 0 : _g.call(_f, message);
+        console.error("No callback found for message with name: ", receivedMessage.message);
+      }
+    };
+  }
+  removeMessage(messageName) {
+    const serializedMessage = this.createSerializedMessage("removeMessage" /* RemoveMessage */, messageName, true);
+    _BroadcastJS.bcInstance.postMessage(serializedMessage);
+    _BroadcastJS.messageCallbacks.delete(messageName);
+  }
+  canBrowserSupportBroadcastJS() {
+    return typeof BroadcastChannel !== "undefined";
+  }
+  hasListeners(messageName) {
+    return _BroadcastJS.messageCallbacks.has(messageName);
+  }
+  static internalMessage(messageName, message) {
+    let isInternalMessage = false;
+    switch (messageName) {
+      case "removeMessage" /* RemoveMessage */:
+        _BroadcastJS.messageCallbacks.delete(message.data);
+        isInternalMessage = true;
+        break;
+      default:
+        isInternalMessage = false;
+        break;
+    }
+    return isInternalMessage;
+  }
+  // manual serialization to make it predictable
+  createMessage(name, data, isInternal) {
+    const message = {
+      message: name,
+      data,
+      isInternal
+    };
+    return message;
+  }
+  createSerializedMessage(name, data, isInternal) {
+    const message = this.createMessage(name, data, isInternal);
+    return JSON.stringify(message);
+  }
+};
+_BroadcastJS.messageCallbacks = /* @__PURE__ */ new Map();
+_BroadcastJS.handlers = {};
+var BroadcastJS = _BroadcastJS;
+export {
+  BroadcastJS
+};

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "js-broadcast-channel",
+  "version": "1.3.1",
+  "description": "Broadcast-js",
+  "main": "index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "tsup src/index.ts --dts --format cjs,esm",
+    "dev": "tsup src/index.ts --dts --format cjs,esm --watch",
+    "test": "jest",
+    "prepare": "npm run build"
+  },
+  "keywords": [
+    "BroadcastAPI"
+  ],
+  "author": "Alireza Valipou",
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AlirezaValipourm/broadcast-js.git"
+  },
+  "bugs": {
+    "url": "https://github.com/AlirezaValipourm/broadcast-js/issues"
+  },
+  "module": "dist/index.mjs",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.js",
+      "import": "./dist/index.mjs"
+    }
+  },
+  "homepage": "https://github.com/AlirezaValipourm/broadcast-js#readme",
+  "devDependencies": {
+    "@types/node": "^22.13.2",
+    "tsup": "^8.3.6",
+    "typescript": "^5.7.3"
+  }
+}