verani 0.4.2 → 0.4.3

package/README.md

@@ -40,28 +40,30 @@ export const chatRoom = defineRoom({
 
   onConnect(ctx) {
     console.log(`User ${ctx.meta.userId} connected`);
-    ctx.actor.broadcast("default", {
-      type: "user.joined",
+    // Use emit API (socket.io-like)
+    ctx.actor.emit.to("default").emit("user.joined", {
       userId: ctx.meta.userId
     });
   },
 
-  onMessage(ctx, frame) {
-    if (frame.type === "chat.message") {
-      // Broadcast to everyone except sender
-      ctx.actor.broadcast("default", {
-        type: "chat.message",
-        from: ctx.meta.userId,
-        text: frame.data.text
-      }, { except: ctx.ws });
-    }
-  },
-
   onDisconnect(ctx) {
     console.log(`User ${ctx.meta.userId} disconnected`);
+    ctx.actor.emit.to("default").emit("user.left", {
+      userId: ctx.meta.userId
+    });
   }
 });
 
+// Register event handlers (socket.io-like, recommended)
+chatRoom.on("chat.message", (ctx, data) => {
+  // Broadcast to all in default channel
+  ctx.actor.emit.to("default").emit("chat.message", {
+    from: ctx.meta.userId,
+    text: data.text,
+    timestamp: Date.now()
+  });
+});
+
 // Create the Durable Object class
 export const ChatRoom = createActorHandler(chatRoom);
 ```
@@ -99,14 +101,27 @@ The three-way relationship:
 ```typescript
 import { VeraniClient } from "verani";
 
-// Connect to your Cloudflare Worker
-const client = new VeraniClient("wss://your-worker.dev/ws?userId=alice");
+// Connect to your Cloudflare Worker with ping/pong keepalive
+const client = new VeraniClient("wss://your-worker.dev/ws?userId=alice", {
+  pingInterval: 5000,  // Send ping every 5 seconds
+  pongTimeout: 5000,  // Expect pong within 5 seconds
+  reconnection: {
+    enabled: true,
+    maxAttempts: 10,
+    initialDelay: 1000,
+    maxDelay: 30000
+  }
+});
 
 // Listen for messages
 client.on("chat.message", (data) => {
   console.log(`${data.from}: ${data.text}`);
 });
 
+client.on("user.joined", (data) => {
+  console.log(`User ${data.userId} joined`);
+});
+
 // Send messages
 client.emit("chat.message", { text: "Hello, world!" });
 
@@ -118,6 +133,10 @@ client.onOpen(() => {
 client.onStateChange((state) => {
   console.log("Connection state:", state);
 });
+
+// Wait for connection before sending
+await client.waitForConnection();
+client.emit("ready", {});
 ```
 
 ## Key Concepts
@@ -135,8 +154,11 @@ Each Cloudflare Actor instance represents a **logical container** for realtime c
 Inside an Actor, connections can join **channels** for selective message routing:
 
 ```typescript
-// Server: broadcast to specific channel
-ctx.actor.broadcast("game-updates", data);
+// Server: broadcast to specific channel using emit API
+ctx.actor.emit.to("game-updates").emit("update", data);
+
+// Or send to a specific user (all their sessions)
+ctx.emit.to("alice").emit("notification", { message: "Hello!" });
 
 // Client: joins "default" channel automatically
 // You can implement join/leave for custom channels
@@ -152,37 +174,61 @@ Verani handles Cloudflare's hibernation automatically:
 
 ## Documentation
 
-- **[Getting Started](./docs/GETTING_STARTED.md)** - Step-by-step tutorial
-- **[Mental Model](./docs/MENTAL_MODEL.md)** - Understanding Verani's architecture
-- **[API Reference](./docs/API.md)** - Complete API documentation
-- **[Examples](./docs/EXAMPLES.md)** - Common usage patterns
-- **[Security Guide](./docs/SECURITY.md)** - Authentication, authorization, and best practices
-- **[Deployment](./docs/DEPLOYMENT.md)** - Deploy to Cloudflare Workers
+- **[Getting Started](./docs/getting-started/)** - Installation and quick start guide
+- **[API Reference](./docs/api/)** - Complete server and client API documentation
+- **[Guides](./docs/guides/)** - Configuration, deployment, scaling, and RPC
+- **[Examples](./docs/examples/)** - Common usage patterns and code samples
+- **[Concepts](./docs/concepts/)** - Architecture, hibernation, and core concepts
+- **[Security](./docs/security/)** - Authentication, authorization, and best practices
 
 ## Features
 
 ### Server (Actor) Side
 
-- Room-based architecture with lifecycle hooks
+- **Socket.io-like event handlers** - `room.on()` and `room.off()` for clean event handling
+- **Emit API** - `ctx.emit` and `ctx.actor.emit.to()` for intuitive message sending
+- Room-based architecture with lifecycle hooks (`onConnect`, `onDisconnect`, `onHibernationRestore`)
 - WebSocket attachment management for hibernation
-- Selective broadcasting with filters
+- Selective broadcasting with filters (userIds, clientIds, except)
 - User and client ID tracking
 - **RPC methods** - Call Actor methods remotely from Workers or other Actors
+- Durable Object storage access for persistent state
 - Error boundaries and logging
 - Flexible metadata extraction from requests
 
 ### Client Side
 
 - Automatic reconnection with exponential backoff
-- Connection state management
+- Connection state management (`getState()`, `getConnectionState()`, `isConnecting`)
 - Message queueing when disconnected
 - Event-based API (on/off/once/emit)
-- Promise-based connection waiting
-- Lifecycle callbacks
+- Promise-based connection waiting (`waitForConnection()`)
+- Lifecycle callbacks (`onOpen`, `onClose`, `onError`, `onStateChange`)
 - **Ping/pong keepalive** with automatic Page Visibility API resync
+- Configurable connection timeout and queue size
 
 ### RPC Support
 
+Call Actor methods remotely from Workers or other Actors:
+
+```typescript
+// In your Worker fetch handler
+const stub = ChatRoom.get("room-id");
+
+// Send to user
+await stub.sendToUser("alice", "notifications", {
+  type: "alert",
+  message: "You have a new message"
+});
+
+// Broadcast to channel
+await stub.broadcast("default", { type: "announcement", text: "Hello!" });
+
+// Query state
+const count = await stub.getSessionCount();
+const userIds = await stub.getConnectedUserIds();
+```
+
 - Send messages to users from HTTP endpoints
 - Query actor state remotely
 - Broadcast from external events or scheduled tasks

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "verani",
-	"version": "0.4.2",
+	"version": "0.4.3",
 	"description": "A simple, focused realtime SDK for Cloudflare Actors with Socket.io-like semantics",
 	"license": "ISC",
 	"keywords": [