wiaxy-realtime

Lightweight WebSocket wrapper for browser environments.

Features

• Auto reconnect with exponential backoff
• Heartbeat ping/pong to detect dead connections
• Event emit / on semantics using JSON messages
• Presence helpers (room subscribe/join/leave)
• Send queue while disconnected
• Promise-based ack support

Install

npm install wiaxy-realtime

Quick usage

import { RealtimeClient } from "wiaxy-realtime";

const client = new RealtimeClient("wss://your-server.example/ws", {
  reconnection: { enabled: true, minDelay: 500, maxDelay: 20000 },
  heartbeat: { enabled: true, interval: 20000 }
});

client.on('__status', status => console.log('status', status));
client.on('chat.message', (m) => console.log('message', m));
client.on('__connected', () => console.log('connected'));

client.connect();

// emit an event
client.emit('chat.message', { text: 'Hello' });

// emit with ack (returns a Promise)
client.emit('chat.message', { text: 'Please ack me' }, { ack: true, timeout: 5000 })
  .then(resp => console.log('ack received', resp))
  .catch(err => console.error('ack failed', err));

// presence
client.subscribePresence('room:main', members => {
  console.log('room members:', members);
});
client.join('room:main');

Server contract

This library expects server messages in JSON form such as:

{ "event": "chat.message", "data": { "text": "Hello" } }

Control messages the client understands (you can implement these on server):

• {"type":"__pong"} — heartbeat pong
• {"type":"__clientId", "clientId":"..."}
• {"type":"__presence", "room":"room", "members":["id1","id2"]}
• Optionally you can use _ackId to request ack callbacks.

API

See index.d.ts for typed API.

License

MIT