waelio-messaging

Minimal real-time WebSocket messaging hub: direct, broadcast, user list, history, optional Mongo persistence, typed API.

Live Demo: https://waelio-messaging.onrender.com/

Install

npm install @waelio/messaging

Quick Start (Server)

npm run dev       # start in dev (ts-node)
npm run build     # compile TypeScript
npm start         # run compiled server

Library Usage

import http from "http";
import express from "express";
import { MessagingHub } from "@waelio/messaging";

const app = express();
const server = http.createServer(app);

// Optional: { mongoURI: 'mongodb+srv://...' }
const hub = new MessagingHub(server);

server.listen(8080, () => console.log("ready"));

Web Component

Auto-send on connect:

<waelio-message target="USER_ID" message="hello"></waelio-message>

Broadcast:

<waelio-message message="hello everyone" broadcast></waelio-message>

Manual:

<waelio-message id="msg" send-on="manual" target="USER_ID"></waelio-message>
<script>
  msg.addEventListener("connected", () => msg.send("hi again"));
</script>

Attributes: target, message, broadcast, ws-url, send-on (connect|manual|click), reconnect. Events: connected, disconnected, sent, error.

Protocol (Summary)

Client → Server:

• route { to, payload }
• broadcast { payload }
• get-history {}
• typing: start-typing / stop-typing
• room: join-room { with }, room-message { payload }

Server → Client:

• register-success { id }
• user-list { users[] }
• message { from, payload, isBroadcast? }
• message-history { history[] }
• user-typing { id } / user-stopped-typing { id }
• joined-room { roomId, with }
• partner-left-room { roomId }
• user-joined { id, ts }
• user-left { id, ts }
• error { message }

Persistence (Optional)

Provide mongoURI to keep more than in-memory history & survive restarts.

new MessagingHub(server, { mongoURI: process.env.MONGO_URI });

Release Scripts

Patch / Minor / Major then publish:

npm run release:patch && npm run release:publish
npm run release:minor && npm run release:publish
npm run release:major && npm run release:publish

License

MIT