@nolag/chat

High-level chat SDK for NoLag — multi-room chat, presence, typing indicators, and message replay.

How It Works with NoLag

NoLag is a real-time messaging platform that handles WebSocket connections, message routing, persistence, and scaling. This SDK wraps the low-level @nolag/js-sdk and gives you a purpose-built chat API — rooms, messages, typing indicators, and presence — without needing to manage topics or subscriptions yourself.

Getting Your Token

1. Sign up at nolag.app
2. Create a new project in the portal
3. Choose the Chat blueprint when creating an app — this pre-configures the topics (messages, _typing), rooms, and lobbies your chat app needs
4. Go to the app's Tokens page and generate an actor token
5. Use that token when connecting with this SDK

Each token identifies a unique user (actor) in NoLag. The blueprint handles all the infrastructure setup — you just write your chat UI.

Install

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

Quick Start

The app owns one core NoLag client; wrappers attach to it. Any number of wrapper SDKs (chat, notify, dash, ...) can share the same connection as long as each uses its own app.

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

// One client for the whole app. In a browser, use 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);
const chat = new NoLagChat({ client, username: "Alice" });

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

// Join a room and send a message
const room = chat.joinRoom("general");
room.sendMessage("Hello, everyone!");

// Listen for messages
room.on("message", (msg) => {
  console.log(`${msg.username}: ${msg.text}`);
});

// See who's online
chat.on("userOnline", (user) => {
  console.log(`${user.username} came online`);
});

// Typing indicators
room.startTyping(); // auto-stops after timeout
room.on("typing", (users) => {
  console.log("Typing:", users.map((u) => u.username).join(", "));
});

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

Lifecycle

• Construction = attach. The wrapper wires its handlers onto the injected client immediately. If the client is already connected, setup runs on the next microtask; otherwise it runs when the client's connect event fires.
• ready() resolves once the first setup completed (identity, online lobby, configured rooms). Auth failures surface via your own await client.connect(), not via ready().
• Reconnects are automatic. The wrapper restores presence and reconciles the online-user list, emitting only real deltas.
• detach() removes exactly this wrapper's handlers and topics and never touches the socket. It is terminal: construct a new instance to re-attach. Detach while the client is still connected so server-side unsubscribes go through. In frameworks, call it from your dispose hook (onUnmounted, HMR dispose).
• One wrapper per (client, app). Sharing a client across wrappers of DIFFERENT apps is the intended pattern; two wrappers on the same app would collide on topics and presence (the SDK warns if you do this).

API Reference

NoLagChat

Constructor

const chat = new NoLagChat(options: NoLagChatOptions);

Options:

| Option | Type | Default | Description | |--------|------|---------|-------------| | client | NoLagSocket | required | The injected core NoLag client | | username | string | required | Display name for this user | | avatar | string | — | Avatar URL | | metadata | Record<string, unknown> | — | Custom user data | | appName | string | 'chat' | NoLag app for topic prefixes | | rooms | string[] | — | Auto-join these rooms on connect | | typingTimeout | number | 3000 | Ms before typing indicator auto-clears | | maxMessageCache | number | 500 | Max messages kept in memory per room | | debug | boolean | false | Enable wrapper debug logging |

Methods

| Method | Returns | Description | |--------|---------|-------------| | ready() | Promise<void> | Resolves when wrapper setup completed | | detach() | void | Release handlers and topics (terminal; never closes the socket) | | joinRoom(name) | ChatRoom | Join a chat room | | leaveRoom(name) | void | Leave a room | | getRooms() | ChatRoom[] | Get all joined rooms | | getOnlineUsers() | ChatUser[] | Get all online users | | setStatus(status) | void | Set status: 'online', 'away', 'busy', 'offline' | | updateProfile(updates) | void | Update username, avatar, or metadata |

Properties

| Property | Type | Description | |----------|------|-------------| | connected | boolean | Whether currently connected | | localUser | ChatUser \| null | The current user | | rooms | Map<string, ChatRoom> | All joined rooms |

Events

| Event | Payload | Description | |-------|---------|-------------| | connected | — | Connected to NoLag | | disconnected | — | Disconnected | | reconnected | — | Reconnected after disconnect | | error | Error | Connection or protocol error | | userOnline | ChatUser | A user came online | | userOffline | ChatUser | A user went offline | | userUpdated | ChatUser | A user updated their profile/status |

ChatRoom

Methods

| Method | Returns | Description | |--------|---------|-------------| | sendMessage(text, options?) | ChatMessage | Send a message | | getMessages() | ChatMessage[] | Get cached messages | | startTyping() | void | Broadcast typing indicator | | stopTyping() | void | Clear typing indicator | | getUsers() | ChatUser[] | Get users in this room | | getUser(userId) | ChatUser \| undefined | Get a specific user | | markRead() | void | Mark all messages as read |

Properties

| Property | Type | Description | |----------|------|-------------| | name | string | Room name | | messages | ChatMessage[] | Cached messages | | typingUsers | ChatUser[] | Users currently typing | | unreadCount | number | Number of unread messages | | active | boolean | Whether currently joined |

Events

| Event | Payload | Description | |-------|---------|-------------| | message | ChatMessage | New message received | | messageSent | ChatMessage | Your message was confirmed | | userJoined | ChatUser | User joined the room | | userLeft | ChatUser | User left the room | | typing | ChatUser[] | Typing users changed | | replayStart | — | Message replay started | | replayEnd | — | Message replay finished | | unreadChanged | number | Unread count changed |

Types

interface ChatUser {
  userId: string;
  actorTokenId: string;
  username: string;
  avatar?: string;
  metadata?: Record<string, unknown>;
  status: "online" | "away" | "busy" | "offline";
  joinedAt: number;
  isLocal: boolean;
}

interface ChatMessage {
  id: string;
  userId: string;
  username: string;
  avatar?: string;
  text: string;
  data?: Record<string, unknown>;
  timestamp: number;
  status: "sending" | "sent" | "error";
  isReplay: boolean;
}

interface SendMessageOptions {
  data?: Record<string, unknown>;
}

License

MIT