message-nexus 1.0.0

package/dist/index.js

@@ -0,0 +1,530 @@
+// src/drivers/BaseDriver.ts
+var BaseDriver = class {
+  constructor() {
+    this.onMessage = null;
+  }
+  send(data) {
+    throw new Error("Not implemented");
+  }
+  destroy() {
+  }
+};
+
+// src/drivers/BroadcastDriver.ts
+var MESSAGE_NEXUS_PROTOCOL = "message-nexus-v1";
+function isBridgeMessage(data) {
+  return typeof data === "object" && data !== null && "__messageBridge" in data && data.__messageBridge === MESSAGE_NEXUS_PROTOCOL;
+}
+var BroadcastDriver = class extends BaseDriver {
+  constructor(options) {
+    super();
+    this.messageHandler = null;
+    if (!options.channel) {
+      throw new Error("BroadcastDriver requires a channel name");
+    }
+    this.channel = new BroadcastChannel(options.channel);
+    this.messageHandler = (event) => {
+      if (!isBridgeMessage(event.data)) {
+        return;
+      }
+      const { __messageBridge, ...message } = event.data;
+      this.onMessage?.(message);
+    };
+    this.channel.addEventListener("message", this.messageHandler);
+  }
+  send(data) {
+    const bridgeMessage = {
+      ...data,
+      __messageBridge: MESSAGE_NEXUS_PROTOCOL
+    };
+    this.channel.postMessage(bridgeMessage);
+  }
+  destroy() {
+    if (this.channel) {
+      this.channel.close();
+    }
+    if (this.messageHandler) {
+      this.channel.removeEventListener("message", this.messageHandler);
+      this.messageHandler = null;
+    }
+    this.onMessage = null;
+  }
+};
+
+// src/drivers/MittDriver.ts
+var eventIndicator = "message_bridge_message_event";
+var MittDriver = class extends BaseDriver {
+  constructor(emitter) {
+    super();
+    this.emitter = emitter;
+    this.listener = () => {
+    };
+    const handler = (data) => {
+      if (data) this.onMessage?.(data);
+    };
+    this.emitter.on(eventIndicator, handler);
+    this.listener = () => {
+      this.emitter.off(eventIndicator, handler);
+    };
+  }
+  send(data) {
+    this.emitter.emit(eventIndicator, data);
+  }
+  destroy() {
+    this.listener();
+    this.onMessage = null;
+  }
+};
+
+// src/drivers/PostMessageDriver.ts
+var MESSAGE_NEXUS_PROTOCOL2 = "message-nexus-v1";
+function isBridgeMessage2(data) {
+  return typeof data === "object" && data !== null && "__messageBridge" in data && data.__messageBridge === MESSAGE_NEXUS_PROTOCOL2;
+}
+var PostMessageDriver = class extends BaseDriver {
+  constructor(targetWindow, targetOrigin) {
+    super();
+    this.messageHandler = null;
+    if (!targetOrigin || targetOrigin === "*") {
+      throw new Error(
+        'PostMessageDriver requires explicit targetOrigin for security. Do not use "*" as it allows any origin.'
+      );
+    }
+    this.targetWindow = targetWindow;
+    this.targetOrigin = targetOrigin;
+    this.messageHandler = (event) => {
+      if (event.origin !== this.targetOrigin) {
+        return;
+      }
+      if (!isBridgeMessage2(event.data)) {
+        return;
+      }
+      const { __messageBridge, ...message } = event.data;
+      this.onMessage?.(message);
+    };
+    window.addEventListener("message", this.messageHandler);
+  }
+  send(data) {
+    const bridgeMessage = {
+      ...data,
+      __messageBridge: MESSAGE_NEXUS_PROTOCOL2
+    };
+    this.targetWindow.postMessage(bridgeMessage, this.targetOrigin);
+  }
+  destroy() {
+    if (this.messageHandler) {
+      window.removeEventListener("message", this.messageHandler);
+      this.messageHandler = null;
+    }
+    this.onMessage = null;
+  }
+};
+
+// src/utils/logger.ts
+var Logger = class {
+  constructor(context, minLevel = "info" /* INFO */) {
+    this.handlers = [];
+    this.context = context;
+    this.minLevel = minLevel;
+  }
+  addHandler(handler) {
+    this.handlers.push(handler);
+  }
+  setMinLevel(level) {
+    this.minLevel = level;
+  }
+  shouldLog(level) {
+    const levels = ["debug" /* DEBUG */, "info" /* INFO */, "warn" /* WARN */, "error" /* ERROR */];
+    return levels.indexOf(level) >= levels.indexOf(this.minLevel);
+  }
+  log(level, message, metadata) {
+    if (!this.shouldLog(level)) return;
+    const entry = {
+      level,
+      timestamp: Date.now(),
+      message,
+      metadata,
+      context: this.context
+    };
+    this.handlers.forEach((handler) => handler(entry));
+  }
+  debug(message, metadata) {
+    this.log("debug" /* DEBUG */, message, metadata);
+  }
+  info(message, metadata) {
+    this.log("info" /* INFO */, message, metadata);
+  }
+  warn(message, metadata) {
+    this.log("warn" /* WARN */, message, metadata);
+  }
+  error(message, metadata) {
+    this.log("error" /* ERROR */, message, metadata);
+  }
+};
+var createConsoleHandler = () => {
+  return (entry) => {
+    const timestamp = new Date(entry.timestamp).toISOString();
+    const prefix = `[${timestamp}] [${entry.level.toUpperCase()}] [${entry.context || "app"}]`;
+    const logFn = entry.level === "debug" /* DEBUG */ ? console.debug : entry.level === "info" /* INFO */ ? console.info : entry.level === "warn" /* WARN */ ? console.warn : console.error;
+    if (entry.metadata) {
+      logFn(prefix, entry.message, entry.metadata);
+    } else {
+      logFn(prefix, entry.message);
+    }
+  };
+};
+
+// src/drivers/WebSocktDriver.ts
+var MESSAGE_NEXUS_PROTOCOL3 = "message-nexus-v1";
+var WebSocketDriver = class extends BaseDriver {
+  constructor(options) {
+    super();
+    this.ws = null;
+    this.retryCount = 0;
+    this.reconnectTimer = null;
+    this.isManuallyClosed = false;
+    this.url = options.url;
+    this.reconnectEnabled = options.reconnect !== false;
+    this.maxRetries = (typeof options.reconnect === "object" ? options.reconnect.maxRetries : void 0) ?? Infinity;
+    this.retryInterval = (typeof options.reconnect === "object" ? options.reconnect.retryInterval : void 0) ?? 5e3;
+    this.logger = options.logger || new Logger("WebSocketDriver");
+    this.logger.addHandler(createConsoleHandler());
+    this.connect();
+  }
+  connect() {
+    this.ws = new WebSocket(this.url);
+    this.ws.addEventListener("open", () => {
+      this.logger.info("WebSocket connected", { url: this.url });
+      this.retryCount = 0;
+    });
+    this.ws.addEventListener("message", (event) => {
+      try {
+        const rawData = JSON.parse(event.data);
+        if (typeof rawData === "object" && rawData !== null && "__messageBridge" in rawData && rawData.__messageBridge === MESSAGE_NEXUS_PROTOCOL3) {
+          const { __messageBridge, ...data } = rawData;
+          this.logger.debug("Message received", { data });
+          this.onMessage?.(data);
+        } else {
+          this.logger.debug("Ignored non-bridge message", { data: rawData });
+        }
+      } catch (error) {
+        this.logger.error("Failed to parse WebSocket message", { error, data: event.data });
+      }
+    });
+    this.ws.addEventListener("error", (event) => {
+      this.logger.error("WebSocket error", { event });
+    });
+    this.ws.addEventListener("close", () => {
+      this.logger.info("WebSocket connection closed", {
+        manuallyClosed: this.isManuallyClosed,
+        retryCount: this.retryCount,
+        maxRetries: this.maxRetries
+      });
+      if (!this.isManuallyClosed && this.reconnectEnabled && this.retryCount < this.maxRetries) {
+        this.scheduleReconnect();
+      }
+    });
+  }
+  scheduleReconnect() {
+    this.retryCount++;
+    const delay = this.retryInterval * this.retryCount;
+    this.logger.info("Reconnecting scheduled", {
+      delay,
+      attempt: this.retryCount,
+      maxRetries: this.maxRetries,
+      url: this.url
+    });
+    this.reconnectTimer = window.setTimeout(() => {
+      this.connect();
+    }, delay);
+  }
+  send(data) {
+    if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+      this.logger.error("WebSocket is not open", {
+        state: this.ws?.readyState,
+        url: this.url
+      });
+      throw new Error("WebSocket is not open");
+    }
+    this.logger.debug("Sending message", { data });
+    const bridgeMessage = {
+      ...data,
+      __messageBridge: MESSAGE_NEXUS_PROTOCOL3
+    };
+    this.ws.send(JSON.stringify(bridgeMessage));
+  }
+  close() {
+    this.logger.info("Closing WebSocket connection", { url: this.url });
+    this.isManuallyClosed = true;
+    if (this.reconnectTimer) {
+      clearTimeout(this.reconnectTimer);
+      this.reconnectTimer = null;
+    }
+    if (this.ws) {
+      this.ws.close();
+      this.ws = null;
+    }
+  }
+  destroy() {
+    this.close();
+    this.onMessage = null;
+  }
+};
+
+// src/utils/emitter.ts
+import mitt from "mitt";
+function createEmitter() {
+  return mitt();
+}
+
+// src/index.ts
+var MessageBridge = class {
+  constructor(driver, options) {
+    this.cleanupInterval = null;
+    this.messageQueue = [];
+    this.maxQueueSize = 100;
+    this.errorHandler = null;
+    this.metrics = {
+      messagesSent: 0,
+      messagesReceived: 0,
+      messagesFailed: 0,
+      pendingMessages: 0,
+      queuedMessages: 0,
+      totalLatency: 0,
+      averageLatency: 0
+    };
+    this.metricsCallbacks = /* @__PURE__ */ new Set();
+    this.driver = driver;
+    this.instanceId = options?.instanceId || crypto.randomUUID();
+    this.timeout = options?.timeout ?? 1e4;
+    this.logger = options?.logger || new Logger("MessageBridge");
+    this.logger.addHandler(createConsoleHandler());
+    this.pendingTasks = /* @__PURE__ */ new Map();
+    this.incomingMessages = /* @__PURE__ */ new Map();
+    this.messageHandlers = /* @__PURE__ */ new Set();
+    this.cleanupInterval = null;
+    this.driver.onMessage = (data) => this._handleIncoming(data);
+    this.logger.info("MessageBridge initialized", {
+      instanceId: this.instanceId,
+      timeout: this.timeout
+    });
+    this.cleanupInterval = window.setInterval(() => {
+      const now = Date.now();
+      for (const [id, msg] of this.incomingMessages.entries()) {
+        if (now - msg.timestamp > this.timeout * 2) {
+          this.incomingMessages.delete(id);
+        }
+      }
+    }, 6e4);
+  }
+  async request(typeOrOptions) {
+    const id = crypto.randomUUID();
+    let type;
+    let payload;
+    let to;
+    let metadata;
+    let timeout;
+    let retryCount = 0;
+    let retryDelay = 1e3;
+    if (typeof typeOrOptions === "string") {
+      type = typeOrOptions;
+      payload = void 0;
+      to = void 0;
+      metadata = {};
+      timeout = this.timeout;
+    } else {
+      const opts = typeOrOptions;
+      type = opts.type;
+      payload = opts.payload;
+      to = opts.to;
+      metadata = opts.metadata || {};
+      timeout = opts.timeout ?? this.timeout;
+      retryCount = opts.retryCount ?? 0;
+      retryDelay = opts.retryDelay ?? 1e3;
+    }
+    const attempt = async (attemptNumber) => {
+      return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+          this.pendingTasks.delete(id);
+          this.metrics.messagesFailed++;
+          this.metrics.pendingMessages--;
+          reject(new Error(`Message timeout: ${type} (${id})`));
+        }, timeout);
+        this.pendingTasks.set(id, { resolve, reject, timer, timestamp: Date.now() });
+        const message = {
+          id,
+          type,
+          payload,
+          from: this.instanceId,
+          to,
+          metadata: { ...metadata, timestamp: Date.now() }
+        };
+        this._sendMessage(message);
+      }).catch((error) => {
+        if (attemptNumber < retryCount) {
+          return new Promise(
+            (resolve) => setTimeout(() => resolve(attempt(attemptNumber + 1)), retryDelay * (attemptNumber + 1))
+          );
+        }
+        this.metrics.messagesFailed++;
+        this.metrics.pendingMessages--;
+        throw error;
+      });
+    };
+    return attempt(0);
+  }
+  _sendMessage(message) {
+    try {
+      this.driver.send(message);
+      this.metrics.messagesSent++;
+      this.metrics.pendingMessages++;
+      this.logger.debug("Message sent", { messageId: message.id, type: message.type });
+    } catch (error) {
+      const err = error instanceof Error ? error : new Error(String(error));
+      this.metrics.messagesFailed++;
+      this.logger.error("Failed to send message", { error: err.message, messageId: message.id });
+      this.errorHandler?.(err, { message });
+      if (this.messageQueue.length < this.maxQueueSize) {
+        this.messageQueue.push(message);
+        this.logger.debug("Message queued", {
+          messageId: message.id,
+          queueSize: this.messageQueue.length + 1
+        });
+      } else {
+        this.logger.warn("Message queue full, dropping oldest message", {
+          queueSize: this.messageQueue.length
+        });
+        this.messageQueue.shift();
+        this.messageQueue.push(message);
+      }
+    }
+    this.metrics.queuedMessages = this.messageQueue.length;
+    this._notifyMetrics();
+  }
+  onError(handler) {
+    this.errorHandler = handler;
+    return () => {
+      this.errorHandler = null;
+    };
+  }
+  flushQueue() {
+    while (this.messageQueue.length > 0) {
+      const message = this.messageQueue.shift();
+      if (message) {
+        try {
+          this.driver.send(message);
+        } catch (error) {
+          this.messageQueue.unshift(message);
+          break;
+        }
+      }
+    }
+  }
+  _validateMessage(data) {
+    if (!data || typeof data !== "object") return false;
+    const msg = data;
+    if (typeof msg.id !== "string") return false;
+    if (typeof msg.type !== "string") return false;
+    if (msg.from && typeof msg.from !== "string") return false;
+    if (msg.to && typeof msg.to !== "string") return false;
+    if (msg.metadata && typeof msg.metadata !== "object") return false;
+    if (msg.isResponse !== void 0 && typeof msg.isResponse !== "boolean") return false;
+    return true;
+  }
+  _handleIncoming(data) {
+    if (!this._validateMessage(data)) {
+      this.logger.error("Invalid message format received", { data });
+      this.errorHandler?.(new Error("Invalid message format received"), { data });
+      this.metrics.messagesFailed++;
+      return;
+    }
+    const { id, to, type, payload, isResponse, error, from } = data;
+    if (to && to !== this.instanceId) {
+      this.logger.debug("Message filtered: not for this instance", {
+        messageId: id,
+        to,
+        instanceId: this.instanceId
+      });
+      return;
+    }
+    if (isResponse && this.pendingTasks.has(id)) {
+      const { resolve, reject, timer, timestamp } = this.pendingTasks.get(id);
+      clearTimeout(timer);
+      this.pendingTasks.delete(id);
+      const latency = Date.now() - timestamp;
+      this.metrics.messagesReceived++;
+      this.metrics.pendingMessages--;
+      this.metrics.totalLatency += latency;
+      this.metrics.averageLatency = this.metrics.totalLatency / this.metrics.messagesReceived;
+      this.logger.debug("Response received", { messageId: id, latency });
+      if (error) reject(error);
+      else resolve(payload);
+      this._notifyMetrics();
+      return;
+    }
+    if (isResponse) {
+      this.logger.warn("Orphaned response received", { messageId: id });
+      return;
+    }
+    this.logger.debug("Command message received", { messageId: id, type, from });
+    this.incomingMessages.set(id, { from, type, timestamp: Date.now() });
+    this.messageHandlers.forEach((handler) => handler(data));
+  }
+  getMetrics() {
+    return { ...this.metrics, pendingMessages: this.pendingTasks.size };
+  }
+  onMetrics(callback) {
+    this.metricsCallbacks.add(callback);
+    return () => this.metricsCallbacks.delete(callback);
+  }
+  _notifyMetrics() {
+    const metrics = this.getMetrics();
+    this.metricsCallbacks.forEach((callback) => callback(metrics));
+  }
+  onCommand(handler) {
+    this.messageHandlers.add(handler);
+    return () => this.messageHandlers.delete(handler);
+  }
+  reply(messageId, payload, error) {
+    const incoming = this.incomingMessages.get(messageId);
+    if (!incoming) {
+      throw new Error(`Message not found: ${messageId}`);
+    }
+    const responsePayload = payload;
+    const responseError = error;
+    this.driver.send({
+      id: messageId,
+      type: `${incoming.type}_RESPONSE`,
+      payload: responsePayload,
+      error: responseError,
+      isResponse: true,
+      from: this.instanceId,
+      to: incoming.from
+    });
+    this.incomingMessages.delete(messageId);
+  }
+  destroy() {
+    this.logger.info("MessageBridge destroying", {
+      instanceId: this.instanceId,
+      pendingMessages: this.pendingTasks.size,
+      queuedMessages: this.messageQueue.length,
+      metrics: this.getMetrics()
+    });
+    this.driver.destroy?.();
+    if (this.cleanupInterval) {
+      clearInterval(this.cleanupInterval);
+      this.cleanupInterval = null;
+    }
+    this.messageHandlers.clear();
+    this.metricsCallbacks.clear();
+  }
+};
+export {
+  BaseDriver,
+  BroadcastDriver,
+  MittDriver,
+  PostMessageDriver,
+  WebSocketDriver,
+  createEmitter,
+  MessageBridge as default
+};

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "message-nexus",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "A unified, type-safe, multi-protocol cross-context message communication library",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "keywords": [
+    "message",
+    "nexus",
+    "communication",
+    "postmessage",
+    "websocket",
+    "mitt",
+    "broadcast"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "mitt": "^3.0.0"
+  },
+  "peerDependenciesMeta": {
+    "mitt": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^24.10.9",
+    "tsup": "^8.4.0",
+    "typescript": "~5.9.3",
+    "vitest": "^4.0.18",
+    "jsdom": "^27.4.0"
+  },
+  "engines": {
+    "node": "^20.19.0 || >=22.12.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest",
+    "test:run": "vitest run",
+    "type-check": "tsc --noEmit"
+  }
+}