@novahelm/realtime

Typed realtime layer for NovaHelm — Socket.io server and client with Redis adapter, presence tracking, room management, message ordering, and reconnection backoff.

Quick Start

pnpm add @novahelm/realtime

Server

import { createRealtimeServer } from "@novahelm/realtime";
import { createServer } from "http";

const httpServer = createServer();

const io = createRealtimeServer({
  httpServer,
  redisUrl: "redis://localhost:6379",
  cors: { origin: "http://localhost:3000" },
});

io.on("connection", (socket) => {
  console.log("connected:", socket.id);
});

httpServer.listen(3001);

Client

import { createRealtimeClient } from "@novahelm/realtime/client";

const socket = createRealtimeClient({
  url: "http://localhost:3001",
});

socket.on("entity:updated", (data) => {
  console.log("Entity updated:", data);
});

Presence Tracking

Track online users per project with Redis-backed presence:

import { createPresenceTracker } from "@novahelm/realtime";

const presence = createPresenceTracker(redis, io);

// In socket handler
presence.join(socket, { userId: "u_123", projectSlug: "my-app" });

// Query who's online
const online = await presence.getOnline("my-app");

Room Management

Manage named rooms with metadata and member counts:

import { createRoomManager } from "@novahelm/realtime";

const rooms = createRoomManager(redis, io);

await rooms.join(socket, "project:my-app:chat");
const info = await rooms.getRoom("project:my-app:chat");
const summary = await rooms.listRooms("project:my-app:*");

Message Ordering

Guarantee in-order delivery with sequence numbers and gap detection:

import { createMessageSequencer } from "@novahelm/realtime";

const sequencer = createMessageSequencer({
  onMessage: (msg) => applyUpdate(msg),
  onGap: (expected, received) => requestMissing(expected, received),
});

socket.on("entity:updated", (data) => {
  sequencer.receive(data);
});

Platform Event Bridge

Bridge platform events from Redis pub/sub into Socket.io rooms:

import { bridgePlatformEvents } from "@novahelm/realtime";

bridgePlatformEvents({
  io,
  redis: subscriberRedis,
  channelPrefix: "nova:",
});

API Reference

| Export | Description | |--------|-------------| | createRealtimeServer(config) | Create Socket.io server with Redis adapter | | createRealtimeClient(config) | Create typed Socket.io client (from /client) | | registerProjectNamespace(io, slug) | Register a /project:{slug} namespace | | bridgePlatformEvents(config) | Bridge Redis pub/sub to Socket.io | | createPresenceTracker(redis, io) | Redis-backed presence tracking | | createRoomManager(redis, io) | Named room management | | createMessageSequencer(opts) | In-order message delivery | | createBackoffStrategy(opts) | Exponential backoff for reconnection | | applyBackoff(socket) | Apply backoff strategy to a socket | | recordRealtimeEvent(redis, event) | Record event throughput metrics | | readRealtimeEventStats(redis) | Read rolling-window event stats |