Skip to main content

​
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

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

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. 
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. 
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

const rooms = await db.realtime.listRooms();
console.log(rooms);

​
Multiplayer Games

For multiplayer games use db.realtime.game() which uses the GameClient. See the Multiplayer section for full docs. 
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

MethodDescription
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

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

​
RoomChat API Reference

MethodDescription
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