tabus-js 0.1.0

package/README.md

@@ -0,0 +1,104 @@
+<div align="center">
+  <img src="./public/tabus-logo.png" alt="tabus" width="200" />
+</div>
+
+# tabus
+
+> Type-safe cross-tab message bus for the browser, built on the native `BroadcastChannel` API.
+
+[![npm](https://img.shields.io/npm/v/tabus)](https://www.npmjs.com/package/tabus)
+[![license](https://img.shields.io/npm/l/tabus)](./LICENSE)
+[![types](https://img.shields.io/npm/types/tabus)](./src/core/types.ts)
+
+## Why
+
+When a user signs out in one tab, other open tabs keep showing sensitive data.  
+`tabus` solves this by letting tabs broadcast events to each other instantly — no server, no WebSockets, no polling.
+
+## Install
+
+```bash
+npm install tabus-js
+# or
+pnpm add tabus-js
+```
+
+## Quick start
+
+```ts
+import { Tabus } from "tabus-js";
+
+type MyEvents = {
+  logout: { userId: number };
+  ping: { ts: number };
+};
+
+const bus = new Tabus<MyEvents>("my-app");
+
+// Listen for events from other tabs
+bus.on("logout", ({ userId }) => {
+  console.log("User logged out:", userId);
+  redirectToLogin();
+});
+
+// Broadcast to all other tabs
+bus.emit("logout", { userId: 42 });
+
+// Clean up
+bus.destroy();
+```
+
+## API
+
+### `new Tabus<Events>(channelName?)`
+
+Creates a new instance. All instances with the same `channelName` share a channel.  
+Defaults to `'tabus'` if no name is provided.
+
+### `bus.on(event, handler)`
+
+Subscribes to an event. Returns `this` for chaining.  
+Also accepts internal events: `tab:join` and `tab:leave`.
+
+### `bus.emit(event, payload)`
+
+Broadcasts an event to all other tabs on the same channel.  
+The emitting tab does **not** receive its own events.
+
+### `bus.off(event, handler)`
+
+Removes a previously registered handler. Returns `this` for chaining.
+
+### `bus.destroy()`
+
+Closes the channel, emits `tab:leave`, and removes all handlers. Safe to call multiple times.
+
+### `bus.tabId`
+
+A unique UUID identifying this tab instance. Read-only.
+
+## Lifecycle events
+
+```ts
+bus.on("tab:join", ({ tabId }) => console.log("Tab joined:", tabId));
+bus.on("tab:leave", ({ tabId }) => console.log("Tab left:", tabId));
+```
+
+These are emitted automatically — you cannot emit them manually.
+
+## Fallback
+
+If `BroadcastChannel` is not available (old browsers, some WebViews), `tabus` falls back to an in-memory bus automatically. Events will still work within the same tab. A `console.warn` is emitted once per channel to notify you.
+
+## Browser support
+
+| Browser | Version |
+| ------- | ------- |
+| Chrome  | 54+     |
+| Firefox | 38+     |
+| Safari  | 15.4+   |
+| Edge    | 79+     |
+
+## License
+
+MIT © [Rody Huancas](https://github.com/rody-huancas)

package/dist/index.d.mts

@@ -0,0 +1,139 @@
+type Handler<T = unknown> = (payload: T) => void;
+type EventMap = Record<string, unknown>;
+interface TabusMessage<T = unknown> {
+    tabId: string;
+    event: string;
+    payload: T;
+}
+type InternalEvents = {
+    "tab:join": {
+        tabId: string;
+    };
+    "tab:leave": {
+        tabId: string;
+    };
+};
+/** Merges user-defined events with internal lifecycle events. */
+type FullEventMap<T extends EventMap> = T & InternalEvents;
+
+declare class Tabus<Events extends EventMap = EventMap> {
+    /**
+     * Unique identifier for this tab / instance.
+     * Generated once per instance using `crypto.randomUUID()` or a manual fallback.
+     *
+     * @example
+     * ```ts
+     * const bus = new Tabus();
+     * console.log(bus.tabId); // "3f2a…"
+     * ```
+     */
+    readonly tabId: string;
+    private readonly transport;
+    private readonly localHandlers;
+    private destroyed;
+    private joinTimer;
+    /**
+     * Creates a new Tabus instance on the given channel.
+     *
+     * Uses `BroadcastChannel` when available (cross-tab communication); falls
+     * back to an in-process in-memory bus otherwise.
+     *
+     * **`tab:join` is emitted asynchronously** (via `setTimeout 0`) so handlers
+     * can be registered on the instance before the event is broadcast.
+     *
+     * @param channelName - Shared channel name (default: `"tabus"`). All
+     *   instances with the same channel name can communicate with each other.
+     *
+     * @example
+     * ```ts
+     * type MyEvents = { data: { value: number }; reset: void };
+     * const bus = new Tabus<MyEvents>("my-app");
+     * bus.on("tab:join", ({ tabId }) => console.log("peer joined:", tabId));
+     * ```
+     */
+    constructor(channelName?: string);
+    /**
+     * Subscribes to an event, including internal lifecycle events
+     * `"tab:join"` and `"tab:leave"`.
+     *
+     * @param event - The event name to listen to.
+     * @param handler - Callback invoked with the event payload when the event fires.
+     * @returns `this` for chaining.
+     *
+     * @example
+     * ```ts
+     * bus
+     *   .on("data", ({ value }) => console.log(value))
+     *   .on("tab:join", ({ tabId }) => console.log("new peer:", tabId));
+     * ```
+     */
+    on<K extends keyof FullEventMap<Events>>(event: K, handler: Handler<FullEventMap<Events>[K]>): this;
+    /**
+     * Unsubscribes a previously registered handler.
+     *
+     * @param event - The event name.
+     * @param handler - The exact same handler reference passed to `on()`.
+     * @returns `this` for chaining.
+     *
+     * @example
+     * ```ts
+     * const handler = (p: { value: number }) => console.log(p.value);
+     * bus.on("data", handler);
+     * // later:
+     * bus.off("data", handler);
+     * ```
+     */
+    off<K extends keyof FullEventMap<Events>>(event: K, handler: Handler<FullEventMap<Events>[K]>): this;
+    /**
+     * Broadcasts an event to **all other instances** on the same channel.
+     *
+     * **The emitting instance does NOT receive its own event.** If local handling
+     * is needed, call the handler directly after emitting.
+     *
+     * @param event - A user-defined event name (internal events cannot be emitted).
+     * @param payload - The value to broadcast.
+     * @returns `this` for chaining.
+     *
+     * @example
+     * ```ts
+     * bus.emit("data", { value: 42 });
+     * // other tabs receive { value: 42 }; this tab does not.
+     * ```
+     */
+    emit<K extends keyof Events>(event: K, payload: Events[K]): this;
+    /**
+     * Broadcasts `"tab:leave"`, closes the transport, and removes all handlers.
+     * Safe to call multiple times — subsequent calls are no-ops.
+     *
+     * If the deferred `"tab:join"` has not yet fired (i.e., the instance is
+     * destroyed within the same tick it was created), neither `"tab:join"` nor
+     * `"tab:leave"` are sent to peers.
+     *
+     * @example
+     * ```ts
+     * window.addEventListener("beforeunload", () => bus.destroy());
+     * ```
+     */
+    destroy(): void;
+    /** Invokes all registered handlers for the given event with the payload. */
+    private dispatch;
+}
+
+interface ITransport {
+    /**
+     * Sends a message to all listeners registered on the channel.
+     * @param msg - The message to broadcast.
+     */
+    send(msg: TabusMessage): void;
+    /**
+     * Registers an incoming-message listener.
+     * @param listener - Callback invoked with each incoming message.
+     */
+    onMessage(listener: (msg: TabusMessage) => void): void;
+    /**
+     * Tears down the transport and releases all held resources.
+     */
+    destroy(): void;
+}
+
+export { type EventMap, type Handler, type ITransport, type InternalEvents, Tabus, type TabusMessage };

package/dist/index.d.ts

@@ -0,0 +1,139 @@
+type Handler<T = unknown> = (payload: T) => void;
+type EventMap = Record<string, unknown>;
+interface TabusMessage<T = unknown> {
+    tabId: string;
+    event: string;
+    payload: T;
+}
+type InternalEvents = {
+    "tab:join": {
+        tabId: string;
+    };
+    "tab:leave": {
+        tabId: string;
+    };
+};
+/** Merges user-defined events with internal lifecycle events. */
+type FullEventMap<T extends EventMap> = T & InternalEvents;
+
+declare class Tabus<Events extends EventMap = EventMap> {
+    /**
+     * Unique identifier for this tab / instance.
+     * Generated once per instance using `crypto.randomUUID()` or a manual fallback.
+     *
+     * @example
+     * ```ts
+     * const bus = new Tabus();
+     * console.log(bus.tabId); // "3f2a…"
+     * ```
+     */
+    readonly tabId: string;
+    private readonly transport;
+    private readonly localHandlers;
+    private destroyed;
+    private joinTimer;
+    /**
+     * Creates a new Tabus instance on the given channel.
+     *
+     * Uses `BroadcastChannel` when available (cross-tab communication); falls
+     * back to an in-process in-memory bus otherwise.
+     *
+     * **`tab:join` is emitted asynchronously** (via `setTimeout 0`) so handlers
+     * can be registered on the instance before the event is broadcast.
+     *
+     * @param channelName - Shared channel name (default: `"tabus"`). All
+     *   instances with the same channel name can communicate with each other.
+     *
+     * @example
+     * ```ts
+     * type MyEvents = { data: { value: number }; reset: void };
+     * const bus = new Tabus<MyEvents>("my-app");
+     * bus.on("tab:join", ({ tabId }) => console.log("peer joined:", tabId));
+     * ```
+     */
+    constructor(channelName?: string);
+    /**
+     * Subscribes to an event, including internal lifecycle events
+     * `"tab:join"` and `"tab:leave"`.
+     *
+     * @param event - The event name to listen to.
+     * @param handler - Callback invoked with the event payload when the event fires.
+     * @returns `this` for chaining.
+     *
+     * @example
+     * ```ts
+     * bus
+     *   .on("data", ({ value }) => console.log(value))
+     *   .on("tab:join", ({ tabId }) => console.log("new peer:", tabId));
+     * ```
+     */
+    on<K extends keyof FullEventMap<Events>>(event: K, handler: Handler<FullEventMap<Events>[K]>): this;
+    /**
+     * Unsubscribes a previously registered handler.
+     *
+     * @param event - The event name.
+     * @param handler - The exact same handler reference passed to `on()`.
+     * @returns `this` for chaining.
+     *
+     * @example
+     * ```ts
+     * const handler = (p: { value: number }) => console.log(p.value);
+     * bus.on("data", handler);
+     * // later:
+     * bus.off("data", handler);
+     * ```
+     */
+    off<K extends keyof FullEventMap<Events>>(event: K, handler: Handler<FullEventMap<Events>[K]>): this;
+    /**
+     * Broadcasts an event to **all other instances** on the same channel.
+     *
+     * **The emitting instance does NOT receive its own event.** If local handling
+     * is needed, call the handler directly after emitting.
+     *
+     * @param event - A user-defined event name (internal events cannot be emitted).
+     * @param payload - The value to broadcast.
+     * @returns `this` for chaining.
+     *
+     * @example
+     * ```ts
+     * bus.emit("data", { value: 42 });
+     * // other tabs receive { value: 42 }; this tab does not.
+     * ```
+     */
+    emit<K extends keyof Events>(event: K, payload: Events[K]): this;
+    /**
+     * Broadcasts `"tab:leave"`, closes the transport, and removes all handlers.
+     * Safe to call multiple times — subsequent calls are no-ops.
+     *
+     * If the deferred `"tab:join"` has not yet fired (i.e., the instance is
+     * destroyed within the same tick it was created), neither `"tab:join"` nor
+     * `"tab:leave"` are sent to peers.
+     *
+     * @example
+     * ```ts
+     * window.addEventListener("beforeunload", () => bus.destroy());
+     * ```
+     */
+    destroy(): void;
+    /** Invokes all registered handlers for the given event with the payload. */
+    private dispatch;
+}
+
+interface ITransport {
+    /**
+     * Sends a message to all listeners registered on the channel.
+     * @param msg - The message to broadcast.
+     */
+    send(msg: TabusMessage): void;
+    /**
+     * Registers an incoming-message listener.
+     * @param listener - Callback invoked with each incoming message.
+     */
+    onMessage(listener: (msg: TabusMessage) => void): void;
+    /**
+     * Tears down the transport and releases all held resources.
+     */
+    destroy(): void;
+}
+
+export { type EventMap, type Handler, type ITransport, type InternalEvents, Tabus, type TabusMessage };

package/dist/index.js

@@ -0,0 +1,237 @@
+"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, {
+  Tabus: () => Tabus
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/core/generate-id.ts
+var generateId = () => {
+  if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") {
+    return crypto.randomUUID();
+  }
+  return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (c) => {
+    const r = Math.random() * 16 | 0;
+    return (c === "x" ? r : r & 3 | 8).toString(16);
+  });
+};
+
+// src/transport/memory.transport.ts
+var channels = /* @__PURE__ */ new Map();
+var warnedChannels = /* @__PURE__ */ new Set();
+var MemoryTransport = class {
+  constructor(channelName) {
+    this.listener = null;
+    this.channelName = channelName;
+    if (!channels.has(channelName)) {
+      channels.set(channelName, /* @__PURE__ */ new Set());
+    }
+    if (!warnedChannels.has(channelName)) {
+      console.warn(
+        `[tabus] BroadcastChannel is not available. Falling back to in-memory bus (channel: "${channelName}").`
+      );
+      warnedChannels.add(channelName);
+    }
+  }
+  send(msg) {
+    channels.get(this.channelName)?.forEach((l) => l(msg));
+  }
+  onMessage(listener) {
+    if (this.listener) {
+      channels.get(this.channelName)?.delete(this.listener);
+    }
+    this.listener = listener;
+    channels.get(this.channelName)?.add(listener);
+  }
+  destroy() {
+    if (this.listener) {
+      channels.get(this.channelName)?.delete(this.listener);
+      this.listener = null;
+    }
+  }
+};
+
+// src/transport/broadcast.transport.ts
+var BroadcastTransport = class {
+  constructor(channelName) {
+    this.bc = new BroadcastChannel(channelName);
+  }
+  send(msg) {
+    this.bc.postMessage(msg);
+  }
+  onMessage(listener) {
+    this.bc.addEventListener(
+      "message",
+      (ev) => listener(ev.data)
+    );
+  }
+  destroy() {
+    this.bc.close();
+  }
+};
+
+// src/core/tabus.ts
+var Tabus = class {
+  /**
+   * Creates a new Tabus instance on the given channel.
+   *
+   * Uses `BroadcastChannel` when available (cross-tab communication); falls
+   * back to an in-process in-memory bus otherwise.
+   *
+   * **`tab:join` is emitted asynchronously** (via `setTimeout 0`) so handlers
+   * can be registered on the instance before the event is broadcast.
+   *
+   * @param channelName - Shared channel name (default: `"tabus"`). All
+   *   instances with the same channel name can communicate with each other.
+   *
+   * @example
+   * ```ts
+   * type MyEvents = { data: { value: number }; reset: void };
+   * const bus = new Tabus<MyEvents>("my-app");
+   * bus.on("tab:join", ({ tabId }) => console.log("peer joined:", tabId));
+   * ```
+   */
+  constructor(channelName) {
+    this.localHandlers = /* @__PURE__ */ new Map();
+    this.destroyed = false;
+    this.joinTimer = null;
+    this.tabId = generateId();
+    const name = channelName ?? "tabus";
+    this.transport = typeof BroadcastChannel !== "undefined" ? new BroadcastTransport(name) : new MemoryTransport(name);
+    this.transport.onMessage((msg) => {
+      if (msg.tabId === this.tabId) return;
+      this.dispatch(msg.event, msg.payload);
+    });
+    this.joinTimer = setTimeout(() => {
+      this.joinTimer = null;
+      if (!this.destroyed) {
+        this.transport.send({
+          tabId: this.tabId,
+          event: "tab:join",
+          payload: { tabId: this.tabId }
+        });
+      }
+    }, 0);
+  }
+  /**
+   * Subscribes to an event, including internal lifecycle events
+   * `"tab:join"` and `"tab:leave"`.
+   *
+   * @param event - The event name to listen to.
+   * @param handler - Callback invoked with the event payload when the event fires.
+   * @returns `this` for chaining.
+   *
+   * @example
+   * ```ts
+   * bus
+   *   .on("data", ({ value }) => console.log(value))
+   *   .on("tab:join", ({ tabId }) => console.log("new peer:", tabId));
+   * ```
+   */
+  on(event, handler) {
+    if (this.destroyed) return this;
+    const key = String(event);
+    if (!this.localHandlers.has(key)) {
+      this.localHandlers.set(key, /* @__PURE__ */ new Set());
+    }
+    this.localHandlers.get(key).add(handler);
+    return this;
+  }
+  /**
+   * Unsubscribes a previously registered handler.
+   *
+   * @param event - The event name.
+   * @param handler - The exact same handler reference passed to `on()`.
+   * @returns `this` for chaining.
+   *
+   * @example
+   * ```ts
+   * const handler = (p: { value: number }) => console.log(p.value);
+   * bus.on("data", handler);
+   * // later:
+   * bus.off("data", handler);
+   * ```
+   */
+  off(event, handler) {
+    this.localHandlers.get(String(event))?.delete(handler);
+    return this;
+  }
+  /**
+   * Broadcasts an event to **all other instances** on the same channel.
+   *
+   * **The emitting instance does NOT receive its own event.** If local handling
+   * is needed, call the handler directly after emitting.
+   *
+   * @param event - A user-defined event name (internal events cannot be emitted).
+   * @param payload - The value to broadcast.
+   * @returns `this` for chaining.
+   *
+   * @example
+   * ```ts
+   * bus.emit("data", { value: 42 });
+   * // other tabs receive { value: 42 }; this tab does not.
+   * ```
+   */
+  emit(event, payload) {
+    if (this.destroyed) return this;
+    this.transport.send({ tabId: this.tabId, event: String(event), payload });
+    return this;
+  }
+  /**
+   * Broadcasts `"tab:leave"`, closes the transport, and removes all handlers.
+   * Safe to call multiple times — subsequent calls are no-ops.
+   *
+   * If the deferred `"tab:join"` has not yet fired (i.e., the instance is
+   * destroyed within the same tick it was created), neither `"tab:join"` nor
+   * `"tab:leave"` are sent to peers.
+   *
+   * @example
+   * ```ts
+   * window.addEventListener("beforeunload", () => bus.destroy());
+   * ```
+   */
+  destroy() {
+    if (this.destroyed) return;
+    this.destroyed = true;
+    if (this.joinTimer !== null) {
+      clearTimeout(this.joinTimer);
+      this.joinTimer = null;
+    } else {
+      this.transport.send({
+        tabId: this.tabId,
+        event: "tab:leave",
+        payload: { tabId: this.tabId }
+      });
+    }
+    this.transport.destroy();
+    this.localHandlers.clear();
+  }
+  /** Invokes all registered handlers for the given event with the payload. */
+  dispatch(event, payload) {
+    this.localHandlers.get(event)?.forEach((h) => h(payload));
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Tabus
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/core/generate-id.ts","../src/transport/memory.transport.ts","../src/transport/broadcast.transport.ts","../src/core/tabus.ts"],"sourcesContent":["export { Tabus } from \"./core/tabus\";\r\nexport type { ITransport } from \"./transport/transport.interface\";\r\nexport type { EventMap, InternalEvents, Handler, TabusMessage } from \"./core/types\";\r\n","/**\r\n * Generates a RFC-4122 v4 UUID string.\r\n * Uses `crypto.randomUUID()` when available; falls back to a `Math.random`-based\r\n * implementation for environments that lack the Web Crypto API.\r\n */\r\nexport const generateId = (): string => {\r\n  if (\r\n    typeof crypto !== \"undefined\" &&\r\n    typeof (crypto as Crypto).randomUUID === \"function\"\r\n  ) {\r\n    return (crypto as Crypto).randomUUID();\r\n  }\r\n\r\n  return \"xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx\".replace(/[xy]/g, (c) => {\r\n    const r = (Math.random() * 16) | 0;\r\n    return (c === \"x\" ? r : (r & 0x3) | 0x8).toString(16);\r\n  });\r\n}\r\n","import type { ITransport } from \"./transport.interface\";\r\nimport type { TabusMessage } from \"../core/types\";\r\n\r\n// Module-level registries shared across all MemoryTransport instances.\r\nconst channels = new Map<string, Set<(msg: TabusMessage) => void>>();\r\n// Tracks which channels have already been warned, so the warning fires once per channel.\r\nconst warnedChannels = new Set<string>();\r\n\r\n/**\r\n * In-process transport used when `BroadcastChannel` is unavailable.\r\n * All instances sharing the same `channelName` communicate via a shared Set\r\n * of listeners. Unlike `BroadcastTransport`, the sender's own listener IS\r\n * called by `send()` — deduplication is the responsibility of the caller\r\n * (i.e. `Tabus`).\r\n */\r\nexport class MemoryTransport implements ITransport {\r\n  private readonly channelName: string;\r\n  private listener: ((msg: TabusMessage) => void) | null = null;\r\n\r\n  constructor(channelName: string) {\r\n    this.channelName = channelName;\r\n\r\n    if (!channels.has(channelName)) {\r\n      channels.set(channelName, new Set());\r\n    }\r\n\r\n    if (!warnedChannels.has(channelName)) {\r\n      console.warn(\r\n        `[tabus] BroadcastChannel is not available. Falling back to in-memory bus (channel: \"${channelName}\").`,\r\n      );\r\n      warnedChannels.add(channelName);\r\n    }\r\n  }\r\n\r\n  send(msg: TabusMessage): void {\r\n    channels.get(this.channelName)?.forEach((l) => l(msg));\r\n  }\r\n\r\n  onMessage(listener: (msg: TabusMessage) => void): void {\r\n    // Remove any previously registered listener before swapping in the new one.\r\n    if (this.listener) {\r\n      channels.get(this.channelName)?.delete(this.listener);\r\n    }\r\n\r\n    this.listener = listener;\r\n    channels.get(this.channelName)?.add(listener);\r\n  }\r\n\r\n  destroy(): void {\r\n    if (this.listener) {\r\n      channels.get(this.channelName)?.delete(this.listener);\r\n      this.listener = null;\r\n    }\r\n  }\r\n}\r\n\r\n/**\r\n * Resets all module-level state.\r\n * @internal Only for use in unit tests.\r\n */\r\nexport function __resetMemoryBus(): void {\r\n  channels.clear();\r\n  warnedChannels.clear();\r\n}\r\n","import type { ITransport } from \"./transport.interface\";\r\nimport type { TabusMessage } from \"../core/types\";\r\n\r\n/** Transport backed by the browser / worker `BroadcastChannel` API. */\r\nexport class BroadcastTransport implements ITransport {\r\n  private readonly bc: BroadcastChannel;\r\n\r\n  constructor(channelName: string) {\r\n    this.bc = new BroadcastChannel(channelName);\r\n  }\r\n\r\n  send(msg: TabusMessage): void {\r\n    this.bc.postMessage(msg);\r\n  }\r\n\r\n  onMessage(listener: (msg: TabusMessage) => void): void {\r\n    this.bc.addEventListener(\"message\", (ev: MessageEvent<TabusMessage>) =>\r\n      listener(ev.data),\r\n    );\r\n  }\r\n\r\n  destroy(): void {\r\n    this.bc.close();\r\n  }\r\n}\r\n","import { generateId } from \"./generate-id\";\r\nimport { MemoryTransport } from \"../transport/memory.transport\";\r\nimport { BroadcastTransport } from \"../transport/broadcast.transport\";\r\nimport type { ITransport } from \"../transport/transport.interface\";\r\nimport type { Handler, EventMap, TabusMessage, FullEventMap } from \"./types\";\r\n\r\nexport class Tabus<Events extends EventMap = EventMap> {\r\n  /**\r\n   * Unique identifier for this tab / instance.\r\n   * Generated once per instance using `crypto.randomUUID()` or a manual fallback.\r\n   *\r\n   * @example\r\n   * ```ts\r\n   * const bus = new Tabus();\r\n   * console.log(bus.tabId); // \"3f2a…\"\r\n   * ```\r\n   */\r\n  readonly tabId: string;\r\n\r\n  private readonly transport: ITransport;\r\n  private readonly localHandlers = new Map<string, Set<Handler>>();\r\n  private destroyed = false;\r\n  private joinTimer: ReturnType<typeof setTimeout> | null = null;\r\n\r\n  /**\r\n   * Creates a new Tabus instance on the given channel.\r\n   *\r\n   * Uses `BroadcastChannel` when available (cross-tab communication); falls\r\n   * back to an in-process in-memory bus otherwise.\r\n   *\r\n   * **`tab:join` is emitted asynchronously** (via `setTimeout 0`) so handlers\r\n   * can be registered on the instance before the event is broadcast.\r\n   *\r\n   * @param channelName - Shared channel name (default: `\"tabus\"`). All\r\n   *   instances with the same channel name can communicate with each other.\r\n   *\r\n   * @example\r\n   * ```ts\r\n   * type MyEvents = { data: { value: number }; reset: void };\r\n   * const bus = new Tabus<MyEvents>(\"my-app\");\r\n   * bus.on(\"tab:join\", ({ tabId }) => console.log(\"peer joined:\", tabId));\r\n   * ```\r\n   */\r\n  constructor(channelName?: string) {\r\n    this.tabId = generateId();\r\n    const name = channelName ?? \"tabus\";\r\n\r\n    this.transport = typeof BroadcastChannel !== \"undefined\" ? new BroadcastTransport(name) : new MemoryTransport(name);\r\n\r\n    // Deduplication: ignore messages that originated from this instance.\r\n    this.transport.onMessage((msg: TabusMessage) => {\r\n      if (msg.tabId === this.tabId) return;\r\n      this.dispatch(msg.event, msg.payload);\r\n    });\r\n\r\n    // Defer so callers can register tab:join handlers synchronously after\r\n    // the constructor returns before the broadcast goes out.\r\n    this.joinTimer = setTimeout(() => {\r\n      this.joinTimer = null;\r\n      if (!this.destroyed) {\r\n        this.transport.send({\r\n          tabId  : this.tabId,\r\n          event  : \"tab:join\",\r\n          payload: { tabId: this.tabId },\r\n        });\r\n      }\r\n    }, 0);\r\n  }\r\n\r\n  /**\r\n   * Subscribes to an event, including internal lifecycle events\r\n   * `\"tab:join\"` and `\"tab:leave\"`.\r\n   *\r\n   * @param event - The event name to listen to.\r\n   * @param handler - Callback invoked with the event payload when the event fires.\r\n   * @returns `this` for chaining.\r\n   *\r\n   * @example\r\n   * ```ts\r\n   * bus\r\n   *   .on(\"data\", ({ value }) => console.log(value))\r\n   *   .on(\"tab:join\", ({ tabId }) => console.log(\"new peer:\", tabId));\r\n   * ```\r\n   */\r\n  on<K extends keyof FullEventMap<Events>>(\r\n    event: K,\r\n    handler: Handler<FullEventMap<Events>[K]>,\r\n  ): this {\r\n    if (this.destroyed) return this;\r\n\r\n    const key = String(event);\r\n\r\n    if (!this.localHandlers.has(key)) {\r\n      this.localHandlers.set(key, new Set());\r\n    }\r\n\r\n    this.localHandlers.get(key)!.add(handler as Handler);\r\n    return this;\r\n  }\r\n\r\n  /**\r\n   * Unsubscribes a previously registered handler.\r\n   *\r\n   * @param event - The event name.\r\n   * @param handler - The exact same handler reference passed to `on()`.\r\n   * @returns `this` for chaining.\r\n   *\r\n   * @example\r\n   * ```ts\r\n   * const handler = (p: { value: number }) => console.log(p.value);\r\n   * bus.on(\"data\", handler);\r\n   * // later:\r\n   * bus.off(\"data\", handler);\r\n   * ```\r\n   */\r\n  off<K extends keyof FullEventMap<Events>>(\r\n    event: K,\r\n    handler: Handler<FullEventMap<Events>[K]>,\r\n  ): this {\r\n    this.localHandlers.get(String(event))?.delete(handler as Handler);\r\n    return this;\r\n  }\r\n\r\n  /**\r\n   * Broadcasts an event to **all other instances** on the same channel.\r\n   *\r\n   * **The emitting instance does NOT receive its own event.** If local handling\r\n   * is needed, call the handler directly after emitting.\r\n   *\r\n   * @param event - A user-defined event name (internal events cannot be emitted).\r\n   * @param payload - The value to broadcast.\r\n   * @returns `this` for chaining.\r\n   *\r\n   * @example\r\n   * ```ts\r\n   * bus.emit(\"data\", { value: 42 });\r\n   * // other tabs receive { value: 42 }; this tab does not.\r\n   * ```\r\n   */\r\n  emit<K extends keyof Events>(event: K, payload: Events[K]): this {\r\n    if (this.destroyed) return this;\r\n    this.transport.send({ tabId: this.tabId, event: String(event), payload });\r\n    return this;\r\n  }\r\n\r\n  /**\r\n   * Broadcasts `\"tab:leave\"`, closes the transport, and removes all handlers.\r\n   * Safe to call multiple times — subsequent calls are no-ops.\r\n   *\r\n   * If the deferred `\"tab:join\"` has not yet fired (i.e., the instance is\r\n   * destroyed within the same tick it was created), neither `\"tab:join\"` nor\r\n   * `\"tab:leave\"` are sent to peers.\r\n   *\r\n   * @example\r\n   * ```ts\r\n   * window.addEventListener(\"beforeunload\", () => bus.destroy());\r\n   * ```\r\n   */\r\n  destroy(): void {\r\n    if (this.destroyed) return;\r\n    this.destroyed = true;\r\n\r\n    if (this.joinTimer !== null) {\r\n      // tab:join hasn't fired yet — cancel it; peers don't know we existed,\r\n      // so there is nothing to announce on departure either.\r\n      clearTimeout(this.joinTimer);\r\n      this.joinTimer = null;\r\n    } else {\r\n      // tab:join already fired — announce departure to peers.\r\n      this.transport.send({\r\n        tabId  : this.tabId,\r\n        event  : \"tab:leave\",\r\n        payload: { tabId: this.tabId },\r\n      });\r\n    }\r\n\r\n    this.transport.destroy();\r\n    this.localHandlers.clear();\r\n  }\r\n\r\n  /** Invokes all registered handlers for the given event with the payload. */\r\n  private dispatch(event: string, payload: unknown): void {\r\n    this.localHandlers.get(event)?.forEach((h) => h(payload));\r\n  }\r\n}\r\n"],"mappings":"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","names":[]}

package/dist/index.mjs

@@ -0,0 +1,210 @@
+// src/core/generate-id.ts
+var generateId = () => {
+  if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") {
+    return crypto.randomUUID();
+  }
+  return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (c) => {
+    const r = Math.random() * 16 | 0;
+    return (c === "x" ? r : r & 3 | 8).toString(16);
+  });
+};
+
+// src/transport/memory.transport.ts
+var channels = /* @__PURE__ */ new Map();
+var warnedChannels = /* @__PURE__ */ new Set();
+var MemoryTransport = class {
+  constructor(channelName) {
+    this.listener = null;
+    this.channelName = channelName;
+    if (!channels.has(channelName)) {
+      channels.set(channelName, /* @__PURE__ */ new Set());
+    }
+    if (!warnedChannels.has(channelName)) {
+      console.warn(
+        `[tabus] BroadcastChannel is not available. Falling back to in-memory bus (channel: "${channelName}").`
+      );
+      warnedChannels.add(channelName);
+    }
+  }
+  send(msg) {
+    channels.get(this.channelName)?.forEach((l) => l(msg));
+  }
+  onMessage(listener) {
+    if (this.listener) {
+      channels.get(this.channelName)?.delete(this.listener);
+    }
+    this.listener = listener;
+    channels.get(this.channelName)?.add(listener);
+  }
+  destroy() {
+    if (this.listener) {
+      channels.get(this.channelName)?.delete(this.listener);
+      this.listener = null;
+    }
+  }
+};
+
+// src/transport/broadcast.transport.ts
+var BroadcastTransport = class {
+  constructor(channelName) {
+    this.bc = new BroadcastChannel(channelName);
+  }
+  send(msg) {
+    this.bc.postMessage(msg);
+  }
+  onMessage(listener) {
+    this.bc.addEventListener(
+      "message",
+      (ev) => listener(ev.data)
+    );
+  }
+  destroy() {
+    this.bc.close();
+  }
+};
+
+// src/core/tabus.ts
+var Tabus = class {
+  /**
+   * Creates a new Tabus instance on the given channel.
+   *
+   * Uses `BroadcastChannel` when available (cross-tab communication); falls
+   * back to an in-process in-memory bus otherwise.
+   *
+   * **`tab:join` is emitted asynchronously** (via `setTimeout 0`) so handlers
+   * can be registered on the instance before the event is broadcast.
+   *
+   * @param channelName - Shared channel name (default: `"tabus"`). All
+   *   instances with the same channel name can communicate with each other.
+   *
+   * @example
+   * ```ts
+   * type MyEvents = { data: { value: number }; reset: void };
+   * const bus = new Tabus<MyEvents>("my-app");
+   * bus.on("tab:join", ({ tabId }) => console.log("peer joined:", tabId));
+   * ```
+   */
+  constructor(channelName) {
+    this.localHandlers = /* @__PURE__ */ new Map();
+    this.destroyed = false;
+    this.joinTimer = null;
+    this.tabId = generateId();
+    const name = channelName ?? "tabus";
+    this.transport = typeof BroadcastChannel !== "undefined" ? new BroadcastTransport(name) : new MemoryTransport(name);
+    this.transport.onMessage((msg) => {
+      if (msg.tabId === this.tabId) return;
+      this.dispatch(msg.event, msg.payload);
+    });
+    this.joinTimer = setTimeout(() => {
+      this.joinTimer = null;
+      if (!this.destroyed) {
+        this.transport.send({
+          tabId: this.tabId,
+          event: "tab:join",
+          payload: { tabId: this.tabId }
+        });
+      }
+    }, 0);
+  }
+  /**
+   * Subscribes to an event, including internal lifecycle events
+   * `"tab:join"` and `"tab:leave"`.
+   *
+   * @param event - The event name to listen to.
+   * @param handler - Callback invoked with the event payload when the event fires.
+   * @returns `this` for chaining.
+   *
+   * @example
+   * ```ts
+   * bus
+   *   .on("data", ({ value }) => console.log(value))
+   *   .on("tab:join", ({ tabId }) => console.log("new peer:", tabId));
+   * ```
+   */
+  on(event, handler) {
+    if (this.destroyed) return this;
+    const key = String(event);
+    if (!this.localHandlers.has(key)) {
+      this.localHandlers.set(key, /* @__PURE__ */ new Set());
+    }
+    this.localHandlers.get(key).add(handler);
+    return this;
+  }
+  /**
+   * Unsubscribes a previously registered handler.
+   *
+   * @param event - The event name.
+   * @param handler - The exact same handler reference passed to `on()`.
+   * @returns `this` for chaining.
+   *
+   * @example
+   * ```ts
+   * const handler = (p: { value: number }) => console.log(p.value);
+   * bus.on("data", handler);
+   * // later:
+   * bus.off("data", handler);
+   * ```
+   */
+  off(event, handler) {
+    this.localHandlers.get(String(event))?.delete(handler);
+    return this;
+  }
+  /**
+   * Broadcasts an event to **all other instances** on the same channel.
+   *
+   * **The emitting instance does NOT receive its own event.** If local handling
+   * is needed, call the handler directly after emitting.
+   *
+   * @param event - A user-defined event name (internal events cannot be emitted).
+   * @param payload - The value to broadcast.
+   * @returns `this` for chaining.
+   *
+   * @example
+   * ```ts
+   * bus.emit("data", { value: 42 });
+   * // other tabs receive { value: 42 }; this tab does not.
+   * ```
+   */
+  emit(event, payload) {
+    if (this.destroyed) return this;
+    this.transport.send({ tabId: this.tabId, event: String(event), payload });
+    return this;
+  }
+  /**
+   * Broadcasts `"tab:leave"`, closes the transport, and removes all handlers.
+   * Safe to call multiple times — subsequent calls are no-ops.
+   *
+   * If the deferred `"tab:join"` has not yet fired (i.e., the instance is
+   * destroyed within the same tick it was created), neither `"tab:join"` nor
+   * `"tab:leave"` are sent to peers.
+   *
+   * @example
+   * ```ts
+   * window.addEventListener("beforeunload", () => bus.destroy());
+   * ```
+   */
+  destroy() {
+    if (this.destroyed) return;
+    this.destroyed = true;
+    if (this.joinTimer !== null) {
+      clearTimeout(this.joinTimer);
+      this.joinTimer = null;
+    } else {
+      this.transport.send({
+        tabId: this.tabId,
+        event: "tab:leave",
+        payload: { tabId: this.tabId }
+      });
+    }
+    this.transport.destroy();
+    this.localHandlers.clear();
+  }
+  /** Invokes all registered handlers for the given event with the payload. */
+  dispatch(event, payload) {
+    this.localHandlers.get(event)?.forEach((h) => h(payload));
+  }
+};
+export {
+  Tabus
+};
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/core/generate-id.ts","../src/transport/memory.transport.ts","../src/transport/broadcast.transport.ts","../src/core/tabus.ts"],"sourcesContent":["/**\r\n * Generates a RFC-4122 v4 UUID string.\r\n * Uses `crypto.randomUUID()` when available; falls back to a `Math.random`-based\r\n * implementation for environments that lack the Web Crypto API.\r\n */\r\nexport const generateId = (): string => {\r\n  if (\r\n    typeof crypto !== \"undefined\" &&\r\n    typeof (crypto as Crypto).randomUUID === \"function\"\r\n  ) {\r\n    return (crypto as Crypto).randomUUID();\r\n  }\r\n\r\n  return \"xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx\".replace(/[xy]/g, (c) => {\r\n    const r = (Math.random() * 16) | 0;\r\n    return (c === \"x\" ? r : (r & 0x3) | 0x8).toString(16);\r\n  });\r\n}\r\n","import type { ITransport } from \"./transport.interface\";\r\nimport type { TabusMessage } from \"../core/types\";\r\n\r\n// Module-level registries shared across all MemoryTransport instances.\r\nconst channels = new Map<string, Set<(msg: TabusMessage) => void>>();\r\n// Tracks which channels have already been warned, so the warning fires once per channel.\r\nconst warnedChannels = new Set<string>();\r\n\r\n/**\r\n * In-process transport used when `BroadcastChannel` is unavailable.\r\n * All instances sharing the same `channelName` communicate via a shared Set\r\n * of listeners. Unlike `BroadcastTransport`, the sender's own listener IS\r\n * called by `send()` — deduplication is the responsibility of the caller\r\n * (i.e. `Tabus`).\r\n */\r\nexport class MemoryTransport implements ITransport {\r\n  private readonly channelName: string;\r\n  private listener: ((msg: TabusMessage) => void) | null = null;\r\n\r\n  constructor(channelName: string) {\r\n    this.channelName = channelName;\r\n\r\n    if (!channels.has(channelName)) {\r\n      channels.set(channelName, new Set());\r\n    }\r\n\r\n    if (!warnedChannels.has(channelName)) {\r\n      console.warn(\r\n        `[tabus] BroadcastChannel is not available. Falling back to in-memory bus (channel: \"${channelName}\").`,\r\n      );\r\n      warnedChannels.add(channelName);\r\n    }\r\n  }\r\n\r\n  send(msg: TabusMessage): void {\r\n    channels.get(this.channelName)?.forEach((l) => l(msg));\r\n  }\r\n\r\n  onMessage(listener: (msg: TabusMessage) => void): void {\r\n    // Remove any previously registered listener before swapping in the new one.\r\n    if (this.listener) {\r\n      channels.get(this.channelName)?.delete(this.listener);\r\n    }\r\n\r\n    this.listener = listener;\r\n    channels.get(this.channelName)?.add(listener);\r\n  }\r\n\r\n  destroy(): void {\r\n    if (this.listener) {\r\n      channels.get(this.channelName)?.delete(this.listener);\r\n      this.listener = null;\r\n    }\r\n  }\r\n}\r\n\r\n/**\r\n * Resets all module-level state.\r\n * @internal Only for use in unit tests.\r\n */\r\nexport function __resetMemoryBus(): void {\r\n  channels.clear();\r\n  warnedChannels.clear();\r\n}\r\n","import type { ITransport } from \"./transport.interface\";\r\nimport type { TabusMessage } from \"../core/types\";\r\n\r\n/** Transport backed by the browser / worker `BroadcastChannel` API. */\r\nexport class BroadcastTransport implements ITransport {\r\n  private readonly bc: BroadcastChannel;\r\n\r\n  constructor(channelName: string) {\r\n    this.bc = new BroadcastChannel(channelName);\r\n  }\r\n\r\n  send(msg: TabusMessage): void {\r\n    this.bc.postMessage(msg);\r\n  }\r\n\r\n  onMessage(listener: (msg: TabusMessage) => void): void {\r\n    this.bc.addEventListener(\"message\", (ev: MessageEvent<TabusMessage>) =>\r\n      listener(ev.data),\r\n    );\r\n  }\r\n\r\n  destroy(): void {\r\n    this.bc.close();\r\n  }\r\n}\r\n","import { generateId } from \"./generate-id\";\r\nimport { MemoryTransport } from \"../transport/memory.transport\";\r\nimport { BroadcastTransport } from \"../transport/broadcast.transport\";\r\nimport type { ITransport } from \"../transport/transport.interface\";\r\nimport type { Handler, EventMap, TabusMessage, FullEventMap } from \"./types\";\r\n\r\nexport class Tabus<Events extends EventMap = EventMap> {\r\n  /**\r\n   * Unique identifier for this tab / instance.\r\n   * Generated once per instance using `crypto.randomUUID()` or a manual fallback.\r\n   *\r\n   * @example\r\n   * ```ts\r\n   * const bus = new Tabus();\r\n   * console.log(bus.tabId); // \"3f2a…\"\r\n   * ```\r\n   */\r\n  readonly tabId: string;\r\n\r\n  private readonly transport: ITransport;\r\n  private readonly localHandlers = new Map<string, Set<Handler>>();\r\n  private destroyed = false;\r\n  private joinTimer: ReturnType<typeof setTimeout> | null = null;\r\n\r\n  /**\r\n   * Creates a new Tabus instance on the given channel.\r\n   *\r\n   * Uses `BroadcastChannel` when available (cross-tab communication); falls\r\n   * back to an in-process in-memory bus otherwise.\r\n   *\r\n   * **`tab:join` is emitted asynchronously** (via `setTimeout 0`) so handlers\r\n   * can be registered on the instance before the event is broadcast.\r\n   *\r\n   * @param channelName - Shared channel name (default: `\"tabus\"`). All\r\n   *   instances with the same channel name can communicate with each other.\r\n   *\r\n   * @example\r\n   * ```ts\r\n   * type MyEvents = { data: { value: number }; reset: void };\r\n   * const bus = new Tabus<MyEvents>(\"my-app\");\r\n   * bus.on(\"tab:join\", ({ tabId }) => console.log(\"peer joined:\", tabId));\r\n   * ```\r\n   */\r\n  constructor(channelName?: string) {\r\n    this.tabId = generateId();\r\n    const name = channelName ?? \"tabus\";\r\n\r\n    this.transport = typeof BroadcastChannel !== \"undefined\" ? new BroadcastTransport(name) : new MemoryTransport(name);\r\n\r\n    // Deduplication: ignore messages that originated from this instance.\r\n    this.transport.onMessage((msg: TabusMessage) => {\r\n      if (msg.tabId === this.tabId) return;\r\n      this.dispatch(msg.event, msg.payload);\r\n    });\r\n\r\n    // Defer so callers can register tab:join handlers synchronously after\r\n    // the constructor returns before the broadcast goes out.\r\n    this.joinTimer = setTimeout(() => {\r\n      this.joinTimer = null;\r\n      if (!this.destroyed) {\r\n        this.transport.send({\r\n          tabId  : this.tabId,\r\n          event  : \"tab:join\",\r\n          payload: { tabId: this.tabId },\r\n        });\r\n      }\r\n    }, 0);\r\n  }\r\n\r\n  /**\r\n   * Subscribes to an event, including internal lifecycle events\r\n   * `\"tab:join\"` and `\"tab:leave\"`.\r\n   *\r\n   * @param event - The event name to listen to.\r\n   * @param handler - Callback invoked with the event payload when the event fires.\r\n   * @returns `this` for chaining.\r\n   *\r\n   * @example\r\n   * ```ts\r\n   * bus\r\n   *   .on(\"data\", ({ value }) => console.log(value))\r\n   *   .on(\"tab:join\", ({ tabId }) => console.log(\"new peer:\", tabId));\r\n   * ```\r\n   */\r\n  on<K extends keyof FullEventMap<Events>>(\r\n    event: K,\r\n    handler: Handler<FullEventMap<Events>[K]>,\r\n  ): this {\r\n    if (this.destroyed) return this;\r\n\r\n    const key = String(event);\r\n\r\n    if (!this.localHandlers.has(key)) {\r\n      this.localHandlers.set(key, new Set());\r\n    }\r\n\r\n    this.localHandlers.get(key)!.add(handler as Handler);\r\n    return this;\r\n  }\r\n\r\n  /**\r\n   * Unsubscribes a previously registered handler.\r\n   *\r\n   * @param event - The event name.\r\n   * @param handler - The exact same handler reference passed to `on()`.\r\n   * @returns `this` for chaining.\r\n   *\r\n   * @example\r\n   * ```ts\r\n   * const handler = (p: { value: number }) => console.log(p.value);\r\n   * bus.on(\"data\", handler);\r\n   * // later:\r\n   * bus.off(\"data\", handler);\r\n   * ```\r\n   */\r\n  off<K extends keyof FullEventMap<Events>>(\r\n    event: K,\r\n    handler: Handler<FullEventMap<Events>[K]>,\r\n  ): this {\r\n    this.localHandlers.get(String(event))?.delete(handler as Handler);\r\n    return this;\r\n  }\r\n\r\n  /**\r\n   * Broadcasts an event to **all other instances** on the same channel.\r\n   *\r\n   * **The emitting instance does NOT receive its own event.** If local handling\r\n   * is needed, call the handler directly after emitting.\r\n   *\r\n   * @param event - A user-defined event name (internal events cannot be emitted).\r\n   * @param payload - The value to broadcast.\r\n   * @returns `this` for chaining.\r\n   *\r\n   * @example\r\n   * ```ts\r\n   * bus.emit(\"data\", { value: 42 });\r\n   * // other tabs receive { value: 42 }; this tab does not.\r\n   * ```\r\n   */\r\n  emit<K extends keyof Events>(event: K, payload: Events[K]): this {\r\n    if (this.destroyed) return this;\r\n    this.transport.send({ tabId: this.tabId, event: String(event), payload });\r\n    return this;\r\n  }\r\n\r\n  /**\r\n   * Broadcasts `\"tab:leave\"`, closes the transport, and removes all handlers.\r\n   * Safe to call multiple times — subsequent calls are no-ops.\r\n   *\r\n   * If the deferred `\"tab:join\"` has not yet fired (i.e., the instance is\r\n   * destroyed within the same tick it was created), neither `\"tab:join\"` nor\r\n   * `\"tab:leave\"` are sent to peers.\r\n   *\r\n   * @example\r\n   * ```ts\r\n   * window.addEventListener(\"beforeunload\", () => bus.destroy());\r\n   * ```\r\n   */\r\n  destroy(): void {\r\n    if (this.destroyed) return;\r\n    this.destroyed = true;\r\n\r\n    if (this.joinTimer !== null) {\r\n      // tab:join hasn't fired yet — cancel it; peers don't know we existed,\r\n      // so there is nothing to announce on departure either.\r\n      clearTimeout(this.joinTimer);\r\n      this.joinTimer = null;\r\n    } else {\r\n      // tab:join already fired — announce departure to peers.\r\n      this.transport.send({\r\n        tabId  : this.tabId,\r\n        event  : \"tab:leave\",\r\n        payload: { tabId: this.tabId },\r\n      });\r\n    }\r\n\r\n    this.transport.destroy();\r\n    this.localHandlers.clear();\r\n  }\r\n\r\n  /** Invokes all registered handlers for the given event with the payload. */\r\n  private dispatch(event: string, payload: unknown): void {\r\n    this.localHandlers.get(event)?.forEach((h) => h(payload));\r\n  }\r\n}\r\n"],"mappings":"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","names":[]}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "tabus-js",
+  "version": "0.1.0",
+  "description": "Type-safe cross-tab message bus using BroadcastChannel, with in-memory fallback.",
+  "author": "Rody Huancas <rodyhuancas.04@gmail.com>",
+  "license": "MIT",
+  "homepage": "https://github.com/rody-huancas/tabus#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/rody-huancas/tabus.git"
+  },
+  "bugs": {
+    "url": "https://github.com/rody-huancas/tabus/issues"
+  },
+  "keywords": [
+    "broadcast",
+    "tab",
+    "cross-tab",
+    "BroadcastChannel",
+    "sync",
+    "message-bus",
+    "typescript"
+  ],
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "tsc --noEmit",
+    "prepublishOnly": "pnpm run lint && pnpm run test && pnpm run build"
+  },
+  "devDependencies": {
+    "typescript": "^5.4.0",
+    "tsup": "^8.0.0",
+    "vitest": "^3.0.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "sideEffects": false
+}