MessageBus JavaScript Client

Common errors

• GET http://your-messagebus-server.com/message-bus/poll net::ERR_CONNECTION_REFUSED

  cause The MessageBus server is not running, is inaccessible at the specified URL, or a firewall is blocking the connection.
  fix Verify that your MessageBus server (Ruby application) is actively running and reachable from the client's network. Check server logs for startup errors and ensure the `baseUrl` configured in the client matches the server's address.

• Access to fetch at 'http://your-messagebus-server.com/message-bus/poll' from origin 'http://your-client-domain.com' has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource.

  cause The browser is enforcing its Same-Origin Policy, and the MessageBus server has not sent the necessary `Access-Control-Allow-Origin` header allowing requests from your client's domain.
  fix On the MessageBus server, configure CORS to allow requests from your client's domain (e.g., `http://your-client-domain.com`). This typically involves adding middleware like `rack-cors` in Ruby Rack applications.

• TypeError: MessageBus is not a constructor

  cause This error occurs when attempting to invoke `MessageBus` as a function instead of instantiating it as a class using the `new` keyword.
  fix Ensure that `MessageBus` is instantiated correctly with `new`: `const bus = new MessageBus();`.

Warnings

• breaking The upstream MessageBus Ruby gem (server-side component) officially supports Ruby versions 3.2 and up as of March 2025. Running the server with older, unsupported Ruby versions may lead to compatibility issues or unexpected behavior with the JavaScript client.
  Fix: Ensure your MessageBus server application is running on Ruby 3.2 or a newer officially supported Ruby version. Consult the Ruby gem's documentation for current support policies.
• gotcha Optimal performance and concurrent long-polling for the MessageBus server (Ruby gem) heavily rely on specific Rack middleware and web server configurations (e.g., Rack Hijack, Thin::Async). Improper server setup can significantly degrade performance or cause connection instability for clients.
  Fix: Refer to the MessageBus Ruby gem's documentation for detailed server setup instructions, especially regarding Rack Hijack and web server configurations (Puma, Unicorn, Thin, Passenger) to ensure efficient long-polling.
• gotcha Significant version discrepancies between the `message-bus-client` and the `message_bus` Ruby gem can lead to unexpected behavior, connection failures, or protocol mismatches. It is generally recommended to keep both components updated to compatible versions.
  Fix: Review the release notes for both `message-bus-client` and the `message_bus` Ruby gem before upgrading. Aim to keep both components on closely matched or explicitly compatible major versions to avoid synchronization issues.
• gotcha If the `message-bus-client` is deployed on a different domain or port than the `message_bus` server, Cross-Origin Resource Sharing (CORS) headers must be properly configured on the server. Failure to do so will result in browser security errors blocking client-server communication.
  Fix: Configure your MessageBus server (Rack application) to include appropriate `Access-Control-Allow-Origin` headers that permit requests from your client's domain. Tools like `rack-cors` can simplify this configuration in Ruby applications.

Install

• npm install message-bus-client npm
• yarn add message-bus-client yarn
• pnpm add message-bus-client pnpm

Imports

• MessageBus
  wrong:

  import MessageBus from 'message-bus-client';

  correct:

  import { MessageBus } from 'message-bus-client';

  MessageBus is a named export, not a default export. This is the primary way to import the client in modern JavaScript environments.
• MessageBus
  wrong:

  const MessageBus = require('message-bus-client');

  correct:

  const { MessageBus } = require('message-bus-client');

  For CommonJS environments, the MessageBus class is a named export and should be destructured from the require call.
• MessageBusOptions
  wrong:

  import { MessageBusOptions } from 'message-bus-client';

  correct:

  import type { MessageBusOptions } from 'message-bus-client';

  This is a type-only import for TypeScript users to define the constructor options for the MessageBus client instance.

Quickstart

Demonstrates how to initialize the MessageBus client, subscribe to multiple channels, and receive real-time messages. It includes optional server URL configuration.

import { MessageBus } from 'message-bus-client';

// Configure the MessageBus client with your server's base URL if different from current origin
const bus = new MessageBus({
  baseUrl: 'http://localhost:9292/message-bus' // Replace with your MessageBus server URL
});

bus.start(); // Start polling for messages immediately

bus.subscribe('/global-channel', (data, messageId) => {
  console.log(`Received message on /global-channel (ID: ${messageId}):`, data);
});

bus.subscribe('/user-channel-123', (data) => {
  console.log('Received targeted message:', data);
});

// To stop listening and disconnect
// setTimeout(() => {
//   bus.unsubscribe('/global-channel');
//   bus.stop();
//   console.log('MessageBus stopped and unsubscribed.');
// }, 60000);