@nolag/chat

Multi-room chat with presence, typing indicators, message replay, and user mapping.

Overview

@nolag/chat is a high-level SDK that turns any application into a fully-featured chat system. It handles room management, user presence, typing indicators, message history replay, and unread tracking, all on top of @nolag/js-sdk. Your app owns one core NoLag client and injects it into NoLagChat; the wrapper attaches its chat behaviour to that connection. You create a NoLagChat instance, wait for it to be ready, join rooms, and start sending messages within minutes.

Key Features

• Multi-room chat with isolated presence per room
• Typing indicators with automatic timeout
• Message replay to catch up on up to 7 days of history after reconnect
• User mapping to attach names, avatars, and metadata to each actor
• Unread message tracking with per-room badge counts
• Automatic reconnection with state restoration

How It Works

NoLagChat attaches to an injected @nolag/js-sdk client and manages a lobby for global user presence. When you call joinRoom(), it returns a ChatRoom instance that subscribes to two topics: messages for durable chat history and _typing for ephemeral typing signals. A MessageStore inside each room accumulates messages and replayed history, while a PresenceManager tracks who is currently online. The app owns the socket lifecycle; the wrapper never opens or closes it.

Installation

npm install @nolag/chat @nolag/js-sdk

Quick Start

import { NoLag } from '@nolag/js-sdk'
import { NoLagChat } from '@nolag/chat'

// The app owns one core client. In a browser, pass a token provider so the
// SDK can mint fresh short-lived client tokens from your backend.
const client = NoLag(async () => (await (await fetch('/api/nolag-token')).json()).token)

// Inject the client into the chat wrapper
const chat = new NoLagChat({ client, username: 'Alice', avatar: '/img/alice.png' })

await client.connect()   // the app owns the connection
await chat.ready()       // wrapper setup complete (identity, presence, rooms)

// Join a room
const room = chat.joinRoom('general')

// Send a message
room.sendMessage('Hello everyone!')

// Listen for messages
room.on('message', (msg) => {
  console.log(`[${msg.username}]: ${msg.text}`)
  console.log('Sent at:', new Date(msg.timestamp))
})

// Listen for typing indicators
room.on('typing', ({ users }) => {
  console.log('Typing:', users.map((u) => u.username).join(', '))
})

// Trigger typing events
room.startTyping()
// ... user stops typing
room.stopTyping()

// Get online users in this room
const users = room.getUsers()
console.log('Online:', users.length)

// Teardown: the wrapper releases its handlers and topics; the app closes the
// socket (never the other way around).
chat.detach()
client.disconnect()

API Reference

NoLagChat

The main class. Attaches to the injected core client, manages global user presence, and the room lifecycle.

Constructor Options

Events: NoLagChat

ChatRoom

Returned by joinRoom(). Scoped to a single room; handles messaging, typing, and per-room presence.

Events: ChatRoom