@mathislair/mtbreactive-client

Browser/Node WebSocket client for @mathislair/mtbreactive servers.

• Auto-reconnect with exponential backoff, capped delay, optional max attempts.
• Auto-resubscribe on reconnect — every active subscription is replayed against the new socket so callers don't have to wire that boilerplate.
• Normalized frames — the server's change frame can carry either a single event or a batched events: [...]; this client always delivers events: [...].

Install

npm install @mathislair/mtbreactive-client

Quick start

import { ReactiveClient } from '@mathislair/mtbreactive-client';

const client = new ReactiveClient('ws://localhost:8080/ws');

const off = client.subscribe(
  'message',
  { col: 'conversation_id', value: 42 },
  (frame) => {
    if (frame.type === 'snapshot') {
      // initial rows
    } else if (frame.type === 'change') {
      for (const ev of frame.events) {
        // ev.type is 'afterInsert' | 'afterUpdate' | 'afterDelete'
        // ev.row, ev.primaryKey, ev.changed (update only)
      }
    } else if (frame.type === 'error') {
      console.warn('subscribe failed:', frame.code);
    }
  },
);

In Node (no global WebSocket)

Native WebSocket is available in browsers and Node ≥ 22. In older Node, pass ws.WebSocket:

import { ReactiveClient } from '@mathislair/mtbreactive-client';
import WebSocket from 'ws';

const client = new ReactiveClient('ws://localhost:8080/ws', {
  websocket: WebSocket,
});

Options

| Option | Default | Purpose | | ----------------------- | ------------ | --------------------------------------------------------- | | websocket | globalThis.WebSocket | WebSocket constructor. | | protocols | — | Subprotocols. | | reconnectInitialMs | 500 | First reconnect delay. | | reconnectMaxMs | 30_000 | Cap on reconnect delay. | | reconnectBackoff | 2 | Multiplier between attempts. | | reconnectMaxAttempts | Infinity | Stops trying after this many failures. | | onStateChange(state) | — | 'connecting' / 'open' / 'reconnecting' / 'closed'. | | onError(err) | — | Underlying socket / send / handler errors. |

License

MIT