> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cocobase.cc/llms.txt
> Use this file to discover all available pages before exploring further.

# Real-time Updates

> Build reactive applications with WebSocket-based real-time data synchronization

# Real-time Updates

Cocobase provides real-time features through the
db.realtime namespace. All connections use automatic
reconnection with exponential backoff built in.

## Collection Watcher

Watch a collection for live document changes.

### Basic Usage

```javascript theme={null}
import { Cocobase } from "cocobase";
const db = new Cocobase({ apiKey: "YOUR_API_KEY", projectId: "YOUR_PROJECT_ID" });

const watcher = db.realtime.collection("posts");

watcher.onConnected((data) => {
  console.log("Connected to collection");
});

watcher.onCreate((data) => {
  console.log("Document created:", data);
});

watcher.onUpdate((data) => {
  console.log("Document updated:", data);
});

watcher.onDelete((data) => {
  console.log("Document deleted:", data);
});

watcher.onError((error) => {
  console.error("Error:", error);
});

watcher.connect();

watcher.disconnect();
```

### Watch with Filters

```javascript theme={null}
const watcher = db.realtime.collection("posts", {
  status: "published",
  author_id: "user-123"
});

watcher.onCreate((data) => {
  console.log("New published post:", data);
});

watcher.connect();
```

## Project Broadcast

Send and receive messages across all connected clients.

```javascript theme={null}
const broadcast = db.realtime.broadcast(
  "user-123",
  "John"
);

broadcast.onMessage((data) => {
  console.log("Message received:", data);
});

broadcast.connect();

broadcast.send({
  type: "announcement",
  text: "Hello everyone!"
});

broadcast.disconnect();
```

## Room Chat

Create or join rooms for isolated real-time communication.

```javascript theme={null}
const room = db.realtime.room(
  "chat-room-1",
  "user-123",
  "John"
);

room.on("message", (data) => {
  console.log("New message:", data);
});

room.on("user_joined", (data) => {
  console.log("User joined:", data);
});

room.create("My Chat Room");

room.join();

room.sendMessage({
  text: "Hello room!",
  timestamp: new Date().toISOString()
});

room.leave();
```

## List Rooms

```javascript theme={null}
const rooms = await db.realtime.listRooms();
console.log(rooms);
```

## Game Client

The `GameClient` supports WebSocket-based game rooms. Use `db.realtime.game()` to connect:

```javascript theme={null}
const game = db.realtime.game("my-game-function");

game.on("connected", (data) => {
  console.log("Connected! My ID:", data.your_id);
});

game.on("player_joined", (data) => {
  console.log("Player joined:", data.player_id);
});

await game.connect({ roomId: "game-room-1" });
game.send({ action: "move", x: 100, y: 200 });
game.disconnect();
```

## Auto-Reconnection

All real-time connections automatically reconnect if
dropped, using exponential backoff from 1 second up
to 30 seconds maximum. No configuration needed.

## CollectionWatcher API Reference

| Method          | Description                        |
| --------------- | ---------------------------------- |
| connect()       | Start watching the collection      |
| disconnect()    | Stop watching                      |
| onConnected(cb) | Called when connection established |
| onCreate(cb)    | Called when document is created    |
| onUpdate(cb)    | Called when document is updated    |
| onDelete(cb)    | Called when document is deleted    |
| onError(cb)     | Called on connection error         |

## ProjectBroadcast API Reference

| Method        | Description                  |
| ------------- | ---------------------------- |
| connect()     | Connect to broadcast channel |
| disconnect()  | Disconnect                   |
| send(data)    | Send message to all clients  |
| onMessage(cb) | Called when message received |

## RoomChat API Reference

| Method               | Description           |
| -------------------- | --------------------- |
| create(roomTitle?)   | Create a new room     |
| join()               | Join existing room    |
| leave()              | Leave the room        |
| sendMessage(content) | Send a message        |
| on(event, cb)        | Listen to room events |

## Best Practices

1. Always set up event handlers before calling connect()
2. Always call disconnect() or leave() when done
3. Use filters in CollectionWatcher to reduce events
4. Use RoomChat for isolated group communication
5. Use ProjectBroadcast for project-wide announcements

***