verani 0.8.0 → 0.8.2

package/README.md

@@ -30,12 +30,17 @@ bun add verani @cloudflare/actors
 
 ### Server Side (Cloudflare Worker)
 
+**Suggested folder structure** (optional, for clarity):
+- `src/actors/chat.actor.ts` - Room definitions
+- `src/index.ts` - Export Durable Object classes
+
 ```typescript
+// src/actors/chat.actor.ts
 import { defineRoom, createActorHandler } from "verani";
 
 // Define your room with lifecycle hooks
 export const chatRoom = defineRoom({
-  name: "chat",
+  name: "chatRoom",
   websocketPath: "/chat",
 
   onConnect(ctx) {
@@ -64,13 +69,26 @@ chatRoom.on("chat.message", (ctx, data) => {
   });
 });
 
-// Create the Durable Object class
+// Create the Durable Object class from the room definition
+// Important: Each defineRoom() creates a room definition object.
+// createActorHandler() converts it into a Durable Object class that must be exported.
+export const ChatRoom = createActorHandler(chatRoom);
+```
+
+```typescript
+// src/index.ts
+import { createActorHandler } from "verani";
+import { chatRoom } from "./actors/chat.actor";
+
+// Create and export the Durable Object class
 export const ChatRoom = createActorHandler(chatRoom);
 ```
 
 ### Wrangler Configuration
 
-**Critical**: Your Durable Object export names in `src/index.ts` **must match** the `class_name` in `wrangler.jsonc`:
+**Critical**: Each `defineRoom()` creates a room definition, and `createActorHandler()` converts it into a Durable Object class. This class **must be exported** and **declared in Wrangler configuration**.
+
+The export name in `src/index.ts` **must match** the `class_name` in `wrangler.jsonc`:
 
 ```jsonc
 {
@@ -91,10 +109,18 @@ export const ChatRoom = createActorHandler(chatRoom);
 }
 ```
 
-The three-way relationship:
-1. **Export** in `src/index.ts`: `export { ChatRoom }`
-2. **Class name** in `wrangler.jsonc`: `"class_name": "ChatRoom"`
-3. **Env binding**: Access via `env.ChatRoom` in your fetch handler
+**Three-way relationship** - these must all align:
+
+1. **Room definition**: `defineRoom({ name: "ChatRoom" })` - The `name` property is optional but recommended for consistency
+2. **Export** in `src/index.ts`: `export const ChatRoom = createActorHandler(chatRoom)` - The export name becomes the class name
+3. **Class name** in `wrangler.jsonc`: `"class_name": "ChatRoom"` - Must match the export name exactly
+
+**Important Notes:**
+- `defineRoom()` returns a room definition object, **not** a Durable Object class
+- `createActorHandler(room)` creates the actual Durable Object class
+- Each room definition must be converted to a class with `createActorHandler()` and exported
+- For multiple rooms, you need multiple exports and multiple bindings in `wrangler.jsonc`
+- The export name (e.g., `ChatRoom`) becomes the class name and must match `class_name` in configuration
 
 ### Client Side
 
@@ -181,6 +207,9 @@ Verani handles Cloudflare's hibernation automatically:
 - **[Concepts](./docs/concepts/)** - Architecture, hibernation, and core concepts
 - **[Security](./docs/security/)** - Authentication, authorization, and best practices
 
+## More Examples
+**[Vchats](https://github.com/v0id-user/vchats)** - A simple chat application built with Verani
+
 ## Features
 
 ### Server (Actor) Side

package/dist/{actor-runtime-Dkz-u49p.d.mts → actor-runtime-1TpQk-wg.d.cts}

@@ -1,4 +1,4 @@
-import { n as ConnectionMeta, r as MessageFrame } from "./types-Ds_V-GWZ.mjs";
+import { n as ConnectionMeta, r as MessageFrame } from "./types-DOI6EHQJ.cjs";
 import { Actor, ActorConfiguration } from "@cloudflare/actors";
 
 //#region src/actor/persist.d.ts

package/dist/{actor-runtime-gMSqKdY5.d.cts → actor-runtime-BOmyu8Vl.d.mts}

@@ -1,4 +1,4 @@
-import { n as ConnectionMeta, r as MessageFrame } from "./types-BefWc1M_.cjs";
+import { n as ConnectionMeta, r as MessageFrame } from "./types-_41fL9Dn.mjs";
 import { Actor, ActorConfiguration } from "@cloudflare/actors";
 
 //#region src/actor/persist.d.ts

package/dist/{client-BaMxxGWr.d.cts → client-C3BlxAY_.d.cts}

@@ -17,7 +17,9 @@ interface ReconnectionConfig {
 }
 declare const DEFAULT_RECONNECTION_CONFIG: ReconnectionConfig;
 /**
- * Manages WebSocket connection lifecycle and reconnection logic
+ * Manages WebSocket connection lifecycle and reconnection logic.
+ * Tracks connection state transitions, schedules reconnection attempts with exponential backoff,
+ * and validates state transitions to ensure consistency.
  */
 declare class ConnectionManager {
   private config;
@@ -28,43 +30,69 @@ declare class ConnectionManager {
   private currentDelay;
   constructor(config?: ReconnectionConfig, onStateChange?: ((state: ConnectionState) => void) | undefined);
   /**
-   * Gets the current connection state
+   * Gets the current connection state.
+   *
+   * @returns The current connection state ("connecting", "connected", "disconnected", "reconnecting", or "error")
    */
   getState(): ConnectionState;
   /**
-   * Validates if a state transition is valid
+   * Validates if a state transition is valid.
+   * Ensures that state changes follow a logical flow and prevents invalid transitions.
+   *
+   * @param from - The current state
+   * @param to - The target state
+   * @returns True if the transition is valid, false otherwise
    */
   private isValidStateTransition;
   /**
-   * Updates the connection state and notifies listeners
+   * Updates the connection state and notifies listeners.
+   * Validates the state transition and logs warnings for invalid transitions.
+   * Only triggers callbacks if the state actually changes.
+   *
+   * @param newState - The new connection state to transition to
    */
   setState(newState: ConnectionState): void;
   /**
-   * Resets reconnection state (called on successful connection)
+   * Resets reconnection state (called on successful connection).
+   * Clears the reconnection attempt counter and resets the delay to the initial value.
+   * Also cancels any pending reconnection timers.
    */
   resetReconnection(): void;
   /**
-   * Schedules a reconnection attempt
+   * Schedules a reconnection attempt with exponential backoff.
+   * Checks if reconnection is enabled and if max attempts haven't been reached.
+   * Updates the delay for the next attempt using exponential backoff.
+   *
+   * @param connectFn - Function to call when it's time to reconnect
+   * @returns True if reconnection was scheduled, false if reconnection is disabled or max attempts reached
    */
   scheduleReconnect(connectFn: () => void): boolean;
   /**
-   * Cancels any pending reconnection
+   * Cancels any pending reconnection attempt.
+   * Clears the reconnection timer and transitions state from "reconnecting" to "disconnected" if applicable.
    */
   cancelReconnect(): void;
   /**
-   * Clears the reconnect timer
+   * Clears the reconnect timer if one is set.
+   * Internal helper method used to clean up pending reconnection attempts.
    */
   private clearReconnectTimer;
   /**
-   * Gets the current reconnection attempt count
+   * Gets the current reconnection attempt count.
+   *
+   * @returns The number of reconnection attempts made so far
    */
   getReconnectAttempts(): number;
   /**
-   * Gets the next reconnection delay
+   * Gets the next reconnection delay in milliseconds.
+   * This value increases with each attempt due to exponential backoff.
+   *
+   * @returns The delay in milliseconds before the next reconnection attempt
    */
   getNextDelay(): number;
   /**
-   * Cleanup method
+   * Cleanup method that clears all timers and resources.
+   * Should be called when the ConnectionManager is no longer needed.
    */
   destroy(): void;
 }

package/dist/{client-DxcWUNF7.d.mts → client-CV5RrpZX.d.mts}

@@ -17,7 +17,9 @@ interface ReconnectionConfig {
 }
 declare const DEFAULT_RECONNECTION_CONFIG: ReconnectionConfig;
 /**
- * Manages WebSocket connection lifecycle and reconnection logic
+ * Manages WebSocket connection lifecycle and reconnection logic.
+ * Tracks connection state transitions, schedules reconnection attempts with exponential backoff,
+ * and validates state transitions to ensure consistency.
  */
 declare class ConnectionManager {
   private config;
@@ -28,43 +30,69 @@ declare class ConnectionManager {
   private currentDelay;
   constructor(config?: ReconnectionConfig, onStateChange?: ((state: ConnectionState) => void) | undefined);
   /**
-   * Gets the current connection state
+   * Gets the current connection state.
+   *
+   * @returns The current connection state ("connecting", "connected", "disconnected", "reconnecting", or "error")
    */
   getState(): ConnectionState;
   /**
-   * Validates if a state transition is valid
+   * Validates if a state transition is valid.
+   * Ensures that state changes follow a logical flow and prevents invalid transitions.
+   *
+   * @param from - The current state
+   * @param to - The target state
+   * @returns True if the transition is valid, false otherwise
    */
   private isValidStateTransition;
   /**
-   * Updates the connection state and notifies listeners
+   * Updates the connection state and notifies listeners.
+   * Validates the state transition and logs warnings for invalid transitions.
+   * Only triggers callbacks if the state actually changes.
+   *
+   * @param newState - The new connection state to transition to
    */
   setState(newState: ConnectionState): void;
   /**
-   * Resets reconnection state (called on successful connection)
+   * Resets reconnection state (called on successful connection).
+   * Clears the reconnection attempt counter and resets the delay to the initial value.
+   * Also cancels any pending reconnection timers.
    */
   resetReconnection(): void;
   /**
-   * Schedules a reconnection attempt
+   * Schedules a reconnection attempt with exponential backoff.
+   * Checks if reconnection is enabled and if max attempts haven't been reached.
+   * Updates the delay for the next attempt using exponential backoff.
+   *
+   * @param connectFn - Function to call when it's time to reconnect
+   * @returns True if reconnection was scheduled, false if reconnection is disabled or max attempts reached
    */
   scheduleReconnect(connectFn: () => void): boolean;
   /**
-   * Cancels any pending reconnection
+   * Cancels any pending reconnection attempt.
+   * Clears the reconnection timer and transitions state from "reconnecting" to "disconnected" if applicable.
    */
   cancelReconnect(): void;
   /**
-   * Clears the reconnect timer
+   * Clears the reconnect timer if one is set.
+   * Internal helper method used to clean up pending reconnection attempts.
    */
   private clearReconnectTimer;
   /**
-   * Gets the current reconnection attempt count
+   * Gets the current reconnection attempt count.
+   *
+   * @returns The number of reconnection attempts made so far
    */
   getReconnectAttempts(): number;
   /**
-   * Gets the next reconnection delay
+   * Gets the next reconnection delay in milliseconds.
+   * This value increases with each attempt due to exponential backoff.
+   *
+   * @returns The delay in milliseconds before the next reconnection attempt
    */
   getNextDelay(): number;
   /**
-   * Cleanup method
+   * Cleanup method that clears all timers and resources.
+   * Should be called when the ConnectionManager is no longer needed.
    */
   destroy(): void;
 }

package/dist/client.d.cts

@@ -1,4 +1,4 @@
-import { a as DEFAULT_RECONNECTION_CONFIG, i as ConnectionState, n as VeraniClientOptions, o as ReconnectionConfig, r as ConnectionManager, t as VeraniClient } from "./client-BaMxxGWr.cjs";
-import { a as ServerMessage, i as PROTOCOL_VERSION, o as VeraniMessage, t as ClientMessage } from "./types-BefWc1M_.cjs";
-import { a as encodeFrame, i as encodeClientMessage, n as decodeFrame, o as encodeServerMessage, r as decodeServerMessage, t as decodeClientMessage } from "./decode-D5ZPxqwe.cjs";
+import { a as DEFAULT_RECONNECTION_CONFIG, i as ConnectionState, n as VeraniClientOptions, o as ReconnectionConfig, r as ConnectionManager, t as VeraniClient } from "./client-C3BlxAY_.cjs";
+import { a as ServerMessage, i as PROTOCOL_VERSION, o as VeraniMessage, t as ClientMessage } from "./types-DOI6EHQJ.cjs";
+import { a as encodeFrame, i as encodeClientMessage, n as decodeFrame, o as encodeServerMessage, r as decodeServerMessage, t as decodeClientMessage } from "./decode--RaAAv0U.cjs";
 export { type ClientMessage, ConnectionManager, type ConnectionState, DEFAULT_RECONNECTION_CONFIG, PROTOCOL_VERSION, type ReconnectionConfig, type ServerMessage, VeraniClient, type VeraniClientOptions, type VeraniMessage, decodeClientMessage, decodeFrame, decodeServerMessage, encodeClientMessage, encodeFrame, encodeServerMessage };

package/dist/client.d.mts

@@ -1,4 +1,4 @@
-import { a as DEFAULT_RECONNECTION_CONFIG, i as ConnectionState, n as VeraniClientOptions, o as ReconnectionConfig, r as ConnectionManager, t as VeraniClient } from "./client-DxcWUNF7.mjs";
-import { a as ServerMessage, i as PROTOCOL_VERSION, o as VeraniMessage, t as ClientMessage } from "./types-Ds_V-GWZ.mjs";
-import { a as encodeFrame, i as encodeClientMessage, n as decodeFrame, o as encodeServerMessage, r as decodeServerMessage, t as decodeClientMessage } from "./decode-E39NapB5.mjs";
+import { a as DEFAULT_RECONNECTION_CONFIG, i as ConnectionState, n as VeraniClientOptions, o as ReconnectionConfig, r as ConnectionManager, t as VeraniClient } from "./client-CV5RrpZX.mjs";
+import { a as ServerMessage, i as PROTOCOL_VERSION, o as VeraniMessage, t as ClientMessage } from "./types-_41fL9Dn.mjs";
+import { a as encodeFrame, i as encodeClientMessage, n as decodeFrame, o as encodeServerMessage, r as decodeServerMessage, t as decodeClientMessage } from "./decode-BUzd77kA.mjs";
 export { type ClientMessage, ConnectionManager, type ConnectionState, DEFAULT_RECONNECTION_CONFIG, PROTOCOL_VERSION, type ReconnectionConfig, type ServerMessage, VeraniClient, type VeraniClientOptions, type VeraniMessage, decodeClientMessage, decodeFrame, decodeServerMessage, encodeClientMessage, encodeFrame, encodeServerMessage };

package/dist/{decode-D5ZPxqwe.d.cts → decode--RaAAv0U.d.cts}

@@ -1,22 +1,28 @@
-import { r as MessageFrame } from "./types-BefWc1M_.cjs";
+import { r as MessageFrame } from "./types-DOI6EHQJ.cjs";
 
 //#region src/shared/encode.d.ts
 
 /**
- * Encodes a message frame to JSON string for transmission
+ * Encodes a message frame to JSON string for transmission over WebSocket.
+ * This is the core encoding function used by both client and server.
+ *
  * @param frame - The message frame to encode
  * @returns JSON string representation of the frame
- * @throws Error if encoding fails
+ * @throws Error if JSON serialization fails
  */
 declare function encodeFrame(frame: MessageFrame): string;
 /**
- * Encodes a client message to JSON string
+ * Encodes a client message to JSON string.
+ * Alias for encodeFrame, provided for semantic clarity when encoding client messages.
+ *
  * @param message - The client message to encode
  * @returns JSON string representation
  */
 declare function encodeClientMessage(message: MessageFrame): string;
 /**
- * Encodes a server message to JSON string
+ * Encodes a server message to JSON string.
+ * Alias for encodeFrame, provided for semantic clarity when encoding server messages.
+ *
  * @param message - The server message to encode
  * @returns JSON string representation
  */
@@ -24,19 +30,26 @@ declare function encodeServerMessage(message: MessageFrame): string;
 //#endregion
 //#region src/shared/decode.d.ts
 /**
- * Decodes a raw message into a MessageFrame
+ * Decodes a raw message into a MessageFrame.
+ * This is the core decoding function used by both client and server.
+ * Handles JSON parsing and validates the resulting object structure.
+ *
  * @param raw - Raw data from WebSocket (string, ArrayBuffer, etc)
- * @returns Decoded MessageFrame or null if invalid
+ * @returns Decoded MessageFrame or null if parsing or validation fails
  */
 declare function decodeFrame(raw: any): MessageFrame | null;
 /**
- * Decodes a client message
+ * Decodes a client message.
+ * Alias for decodeFrame, provided for semantic clarity when decoding client messages.
+ *
  * @param raw - Raw data from client WebSocket
  * @returns Decoded message or null if invalid
  */
 declare function decodeClientMessage(raw: any): MessageFrame | null;
 /**
- * Decodes a server message
+ * Decodes a server message.
+ * Alias for decodeFrame, provided for semantic clarity when decoding server messages.
+ *
  * @param raw - Raw data from server WebSocket
  * @returns Decoded message or null if invalid
  */

package/dist/{decode-E39NapB5.d.mts → decode-BUzd77kA.d.mts}

@@ -1,22 +1,28 @@
-import { r as MessageFrame } from "./types-Ds_V-GWZ.mjs";
+import { r as MessageFrame } from "./types-_41fL9Dn.mjs";
 
 //#region src/shared/encode.d.ts
 
 /**
- * Encodes a message frame to JSON string for transmission
+ * Encodes a message frame to JSON string for transmission over WebSocket.
+ * This is the core encoding function used by both client and server.
+ *
  * @param frame - The message frame to encode
  * @returns JSON string representation of the frame
- * @throws Error if encoding fails
+ * @throws Error if JSON serialization fails
  */
 declare function encodeFrame(frame: MessageFrame): string;
 /**
- * Encodes a client message to JSON string
+ * Encodes a client message to JSON string.
+ * Alias for encodeFrame, provided for semantic clarity when encoding client messages.
+ *
  * @param message - The client message to encode
  * @returns JSON string representation
  */
 declare function encodeClientMessage(message: MessageFrame): string;
 /**
- * Encodes a server message to JSON string
+ * Encodes a server message to JSON string.
+ * Alias for encodeFrame, provided for semantic clarity when encoding server messages.
+ *
  * @param message - The server message to encode
  * @returns JSON string representation
  */
@@ -24,19 +30,26 @@ declare function encodeServerMessage(message: MessageFrame): string;
 //#endregion
 //#region src/shared/decode.d.ts
 /**
- * Decodes a raw message into a MessageFrame
+ * Decodes a raw message into a MessageFrame.
+ * This is the core decoding function used by both client and server.
+ * Handles JSON parsing and validates the resulting object structure.
+ *
  * @param raw - Raw data from WebSocket (string, ArrayBuffer, etc)
- * @returns Decoded MessageFrame or null if invalid
+ * @returns Decoded MessageFrame or null if parsing or validation fails
  */
 declare function decodeFrame(raw: any): MessageFrame | null;
 /**
- * Decodes a client message
+ * Decodes a client message.
+ * Alias for decodeFrame, provided for semantic clarity when decoding client messages.
+ *
  * @param raw - Raw data from client WebSocket
  * @returns Decoded message or null if invalid
  */
 declare function decodeClientMessage(raw: any): MessageFrame | null;
 /**
- * Decodes a server message
+ * Decodes a server message.
+ * Alias for decodeFrame, provided for semantic clarity when decoding server messages.
+ *
  * @param raw - Raw data from server WebSocket
  * @returns Decoded message or null if invalid
  */

package/dist/typed-client.d.cts

@@ -1,4 +1,4 @@
-import { i as ConnectionState, n as VeraniClientOptions, t as VeraniClient } from "./client-BaMxxGWr.cjs";
+import { i as ConnectionState, n as VeraniClientOptions, t as VeraniClient } from "./client-C3BlxAY_.cjs";
 import { B as payload, C as InferServerEvents, D as ServerPayloadMap, E as ServerPayload, F as EventPayloads, I as ExtractPayload, L as PayloadMarker, M as Contract, N as ContractDefinition, P as EventMap, R as defineContract, S as InferClientEvents, T as ServerEventNames, _ as ClientEventHandler, a as ValidationResult, b as ClientPayloadMap, d as getServerValidator, g as AllEventNames, h as withValidation, i as ValidationIssue, l as createValidatedListener, m as validateData, o as Validator, p as isValidatedContract, r as ValidationError, t as ValidatedContract, v as ClientEventNames, w as ServerEventHandler, x as InferChannels, y as ClientPayload, z as isContract } from "./validation-Dw-KMz9Q.cjs";
 
 //#region src/typed/client.d.ts

package/dist/typed-client.d.mts

@@ -1,4 +1,4 @@
-import { i as ConnectionState, n as VeraniClientOptions, t as VeraniClient } from "./client-DxcWUNF7.mjs";
+import { i as ConnectionState, n as VeraniClientOptions, t as VeraniClient } from "./client-CV5RrpZX.mjs";
 import { B as payload, C as InferServerEvents, D as ServerPayloadMap, E as ServerPayload, F as EventPayloads, I as ExtractPayload, L as PayloadMarker, M as Contract, N as ContractDefinition, P as EventMap, R as defineContract, S as InferClientEvents, T as ServerEventNames, _ as ClientEventHandler, a as ValidationResult, b as ClientPayloadMap, d as getServerValidator, g as AllEventNames, h as withValidation, i as ValidationIssue, l as createValidatedListener, m as validateData, o as Validator, p as isValidatedContract, r as ValidationError, t as ValidatedContract, v as ClientEventNames, w as ServerEventHandler, x as InferChannels, y as ClientPayload, z as isContract } from "./validation-DCongzPL.mjs";
 
 //#region src/typed/client.d.ts

package/dist/typed.d.cts

@@ -1,6 +1,6 @@
-import { n as ConnectionMeta } from "./types-BefWc1M_.cjs";
+import { n as ConnectionMeta } from "./types-DOI6EHQJ.cjs";
 import { A as TypedServerEmit, B as payload, C as InferServerEvents, D as ServerPayloadMap, E as ServerPayload, F as EventPayloads, I as ExtractPayload, L as PayloadMarker, M as Contract, N as ContractDefinition, O as TypedClientEmit, P as EventMap, R as defineContract, S as InferClientEvents, T as ServerEventNames, _ as ClientEventHandler, a as ValidationResult, b as ClientPayloadMap, c as createValidatedHandler, f as getValidationErrorHandler, g as AllEventNames, h as withValidation, i as ValidationIssue, j as TypedServerListener, k as TypedClientListener, m as validateData, n as ValidationConfig, o as Validator, p as isValidatedContract, r as ValidationError, s as ValidatorMap, t as ValidatedContract, u as getClientValidator, v as ClientEventNames, w as ServerEventHandler, x as InferChannels, y as ClientPayload, z as isContract } from "./validation-Dw-KMz9Q.cjs";
-import { c as RoomDefinition, n as createActorHandler, r as ActorStub, u as VeraniActor } from "./actor-runtime-gMSqKdY5.cjs";
+import { c as RoomDefinition, n as createActorHandler, r as ActorStub, u as VeraniActor } from "./actor-runtime-1TpQk-wg.cjs";
 
 //#region src/typed/server.d.ts
 

package/dist/typed.d.mts

@@ -1,6 +1,6 @@
-import { n as ConnectionMeta } from "./types-Ds_V-GWZ.mjs";
+import { n as ConnectionMeta } from "./types-_41fL9Dn.mjs";
 import { A as TypedServerEmit, B as payload, C as InferServerEvents, D as ServerPayloadMap, E as ServerPayload, F as EventPayloads, I as ExtractPayload, L as PayloadMarker, M as Contract, N as ContractDefinition, O as TypedClientEmit, P as EventMap, R as defineContract, S as InferClientEvents, T as ServerEventNames, _ as ClientEventHandler, a as ValidationResult, b as ClientPayloadMap, c as createValidatedHandler, f as getValidationErrorHandler, g as AllEventNames, h as withValidation, i as ValidationIssue, j as TypedServerListener, k as TypedClientListener, m as validateData, n as ValidationConfig, o as Validator, p as isValidatedContract, r as ValidationError, s as ValidatorMap, t as ValidatedContract, u as getClientValidator, v as ClientEventNames, w as ServerEventHandler, x as InferChannels, y as ClientPayload, z as isContract } from "./validation-DCongzPL.mjs";
-import { c as RoomDefinition, n as createActorHandler, r as ActorStub, u as VeraniActor } from "./actor-runtime-Dkz-u49p.mjs";
+import { c as RoomDefinition, n as createActorHandler, r as ActorStub, u as VeraniActor } from "./actor-runtime-BOmyu8Vl.mjs";
 
 //#region src/typed/server.d.ts
 

package/dist/types-DOI6EHQJ.d.cts

@@ -0,0 +1,54 @@
+//#region src/shared/types.d.ts
+/**
+ * Core message types shared between client and server.
+ * These types define the protocol used for WebSocket communication in Verani.
+ */
+/**
+ * Base message frame structure used for all WebSocket communication.
+ * All messages sent over WebSocket follow this structure.
+ */
+interface MessageFrame {
+  type: string;
+  channel?: string;
+  data?: any;
+}
+/**
+ * Message sent from client to server.
+ * Extends MessageFrame with no additional fields, but semantically represents client-originated messages.
+ */
+interface ClientMessage extends MessageFrame {
+  type: string;
+  channel?: string;
+  data?: any;
+}
+/**
+ * Message sent from server to client.
+ * Extends MessageFrame with no additional fields, but semantically represents server-originated messages.
+ */
+interface ServerMessage extends MessageFrame {
+  type: string;
+  channel?: string;
+  data?: any;
+}
+/**
+ * Connection metadata attached to each WebSocket.
+ * This metadata is stored as a WebSocket attachment and survives actor hibernation.
+ * It identifies the user, client, and channels the connection is subscribed to.
+ */
+interface ConnectionMeta {
+  userId: string;
+  clientId: string;
+  channels: string[];
+}
+/**
+ * Unified message type for both directions.
+ * Represents any message that can be sent over the Verani WebSocket protocol.
+ */
+type VeraniMessage = ClientMessage | ServerMessage;
+/**
+ * Protocol version for future compatibility.
+ * Used to identify the protocol version for potential future protocol upgrades.
+ */
+declare const PROTOCOL_VERSION = "1.0.0";
+//#endregion
+export { ServerMessage as a, PROTOCOL_VERSION as i, ConnectionMeta as n, VeraniMessage as o, MessageFrame as r, ClientMessage as t };

package/dist/types-_41fL9Dn.d.mts

@@ -0,0 +1,54 @@
+//#region src/shared/types.d.ts
+/**
+ * Core message types shared between client and server.
+ * These types define the protocol used for WebSocket communication in Verani.
+ */
+/**
+ * Base message frame structure used for all WebSocket communication.
+ * All messages sent over WebSocket follow this structure.
+ */
+interface MessageFrame {
+  type: string;
+  channel?: string;
+  data?: any;
+}
+/**
+ * Message sent from client to server.
+ * Extends MessageFrame with no additional fields, but semantically represents client-originated messages.
+ */
+interface ClientMessage extends MessageFrame {
+  type: string;
+  channel?: string;
+  data?: any;
+}
+/**
+ * Message sent from server to client.
+ * Extends MessageFrame with no additional fields, but semantically represents server-originated messages.
+ */
+interface ServerMessage extends MessageFrame {
+  type: string;
+  channel?: string;
+  data?: any;
+}
+/**
+ * Connection metadata attached to each WebSocket.
+ * This metadata is stored as a WebSocket attachment and survives actor hibernation.
+ * It identifies the user, client, and channels the connection is subscribed to.
+ */
+interface ConnectionMeta {
+  userId: string;
+  clientId: string;
+  channels: string[];
+}
+/**
+ * Unified message type for both directions.
+ * Represents any message that can be sent over the Verani WebSocket protocol.
+ */
+type VeraniMessage = ClientMessage | ServerMessage;
+/**
+ * Protocol version for future compatibility.
+ * Used to identify the protocol version for potential future protocol upgrades.
+ */
+declare const PROTOCOL_VERSION = "1.0.0";
+//#endregion
+export { ServerMessage as a, PROTOCOL_VERSION as i, ConnectionMeta as n, VeraniMessage as o, MessageFrame as r, ClientMessage as t };

package/dist/verani.d.cts

@@ -1,6 +1,6 @@
-import { a as ServerMessage, i as PROTOCOL_VERSION, n as ConnectionMeta, o as VeraniMessage, r as MessageFrame, t as ClientMessage } from "./types-BefWc1M_.cjs";
-import { a as encodeFrame, i as encodeClientMessage, n as decodeFrame, o as encodeServerMessage, r as decodeServerMessage, t as decodeClientMessage } from "./decode-D5ZPxqwe.cjs";
-import { C as safeSerialize, S as safeDeserialize, _ as getPersistedKeys, a as EventHandler, b as isStateReady, c as RoomDefinition, d as PersistError, f as PersistNotReadyError, g as deletePersistedKey, h as clearPersistedState, i as BroadcastOptions, l as RpcBroadcastOptions, m as SafePersistOptions, n as createActorHandler, o as MessageContext, p as PersistableActor, r as ActorStub, s as RoomContext, t as ActorHandlerClass, u as VeraniActor, v as getPersistedState, w as setPeristErrorHandler, x as persistKey, y as initializePersistedState } from "./actor-runtime-gMSqKdY5.cjs";
+import { a as ServerMessage, i as PROTOCOL_VERSION, n as ConnectionMeta, o as VeraniMessage, r as MessageFrame, t as ClientMessage } from "./types-DOI6EHQJ.cjs";
+import { a as encodeFrame, i as encodeClientMessage, n as decodeFrame, o as encodeServerMessage, r as decodeServerMessage, t as decodeClientMessage } from "./decode--RaAAv0U.cjs";
+import { C as safeSerialize, S as safeDeserialize, _ as getPersistedKeys, a as EventHandler, b as isStateReady, c as RoomDefinition, d as PersistError, f as PersistNotReadyError, g as deletePersistedKey, h as clearPersistedState, i as BroadcastOptions, l as RpcBroadcastOptions, m as SafePersistOptions, n as createActorHandler, o as MessageContext, p as PersistableActor, r as ActorStub, s as RoomContext, t as ActorHandlerClass, u as VeraniActor, v as getPersistedState, w as setPeristErrorHandler, x as persistKey, y as initializePersistedState } from "./actor-runtime-1TpQk-wg.cjs";
 
 //#region src/actor/router.d.ts
 /**
@@ -21,14 +21,47 @@ interface RoomDefinitionWithHandlers<TMeta extends ConnectionMeta = ConnectionMe
   off(event: string, handler?: EventHandler<TMeta, E, TState>): void;
 }
 /**
- * Defines a room with lifecycle hooks and metadata extraction
- * @param def - Room definition with optional hooks
+ * Defines a room with lifecycle hooks and metadata extraction.
+ * Creates a normalized room definition with default values and socket.io-like event handler methods.
+ * The returned room object supports `.on()` and `.off()` methods for event handling.
+ *
+ * @param def - Room definition with optional hooks, state, and configuration
  * @returns Normalized room definition with defaults and socket.io-like event handler methods
+ * @example
+ * ```typescript
+ * const room = defineRoom({
+ *   websocketPath: "/ws",
+ *   onConnect: (ctx) => console.log("User connected:", ctx.meta.userId),
+ *   onMessage: (ctx, frame) => console.log("Message:", frame.type)
+ * });
+ *
+ * // Register event handlers
+ * room.on("chat", (ctx, data) => {
+ *   ctx.emit.emit("message", data);
+ * });
+ * ```
  */
 declare function defineRoom<TMeta extends ConnectionMeta = ConnectionMeta, E = unknown, TState extends Record<string, unknown> = Record<string, unknown>>(def: RoomDefinition<TMeta, E, TState>): RoomDefinitionWithHandlers<TMeta, E, TState>;
 //#endregion
 //#region src/actor/attachment.d.ts
+/**
+ * Stores connection metadata as a WebSocket attachment for hibernation survival.
+ * This allows the actor to restore session information when it wakes from hibernation.
+ *
+ * @param ws - The WebSocket connection to attach metadata to
+ * @param meta - Connection metadata containing userId, clientId, and channels
+ * @throws Error if serialization fails
+ */
 declare function storeAttachment(ws: WebSocket, meta: ConnectionMeta): void;
+/**
+ * Restores WebSocket sessions from hibernation by deserializing attachments.
+ * Only restores sessions that are in OPEN state and have valid metadata.
+ * Sessions with invalid or missing metadata are skipped.
+ *
+ * @param actor - The actor instance with a sessions Map and ctx.getWebSockets() method
+ * @returns void - Sessions are added directly to actor.sessions Map
+ * @throws Error if deserialization fails critically (individual failures are logged and skipped)
+ */
 declare function restoreSessions(actor: any): void;
 //#endregion
 export { type ActorHandlerClass, type ActorStub, type BroadcastOptions, type ClientMessage, type ConnectionMeta, type MessageContext, type MessageFrame, PROTOCOL_VERSION, PersistError, PersistNotReadyError, type PersistableActor, type RoomContext, type RoomDefinition, type RpcBroadcastOptions, type SafePersistOptions, type ServerMessage, type VeraniActor, type VeraniMessage, clearPersistedState, createActorHandler, decodeClientMessage, decodeFrame, decodeServerMessage, defineRoom, deletePersistedKey, encodeClientMessage, encodeFrame, encodeServerMessage, getPersistedKeys, getPersistedState, initializePersistedState, isStateReady, persistKey, restoreSessions, safeDeserialize, safeSerialize, setPeristErrorHandler, storeAttachment };

package/dist/verani.d.mts

@@ -1,6 +1,6 @@
-import { a as ServerMessage, i as PROTOCOL_VERSION, n as ConnectionMeta, o as VeraniMessage, r as MessageFrame, t as ClientMessage } from "./types-Ds_V-GWZ.mjs";
-import { a as encodeFrame, i as encodeClientMessage, n as decodeFrame, o as encodeServerMessage, r as decodeServerMessage, t as decodeClientMessage } from "./decode-E39NapB5.mjs";
-import { C as safeSerialize, S as safeDeserialize, _ as getPersistedKeys, a as EventHandler, b as isStateReady, c as RoomDefinition, d as PersistError, f as PersistNotReadyError, g as deletePersistedKey, h as clearPersistedState, i as BroadcastOptions, l as RpcBroadcastOptions, m as SafePersistOptions, n as createActorHandler, o as MessageContext, p as PersistableActor, r as ActorStub, s as RoomContext, t as ActorHandlerClass, u as VeraniActor, v as getPersistedState, w as setPeristErrorHandler, x as persistKey, y as initializePersistedState } from "./actor-runtime-Dkz-u49p.mjs";
+import { a as ServerMessage, i as PROTOCOL_VERSION, n as ConnectionMeta, o as VeraniMessage, r as MessageFrame, t as ClientMessage } from "./types-_41fL9Dn.mjs";
+import { a as encodeFrame, i as encodeClientMessage, n as decodeFrame, o as encodeServerMessage, r as decodeServerMessage, t as decodeClientMessage } from "./decode-BUzd77kA.mjs";
+import { C as safeSerialize, S as safeDeserialize, _ as getPersistedKeys, a as EventHandler, b as isStateReady, c as RoomDefinition, d as PersistError, f as PersistNotReadyError, g as deletePersistedKey, h as clearPersistedState, i as BroadcastOptions, l as RpcBroadcastOptions, m as SafePersistOptions, n as createActorHandler, o as MessageContext, p as PersistableActor, r as ActorStub, s as RoomContext, t as ActorHandlerClass, u as VeraniActor, v as getPersistedState, w as setPeristErrorHandler, x as persistKey, y as initializePersistedState } from "./actor-runtime-BOmyu8Vl.mjs";
 
 //#region src/actor/router.d.ts
 /**
@@ -21,14 +21,47 @@ interface RoomDefinitionWithHandlers<TMeta extends ConnectionMeta = ConnectionMe
   off(event: string, handler?: EventHandler<TMeta, E, TState>): void;
 }
 /**
- * Defines a room with lifecycle hooks and metadata extraction
- * @param def - Room definition with optional hooks
+ * Defines a room with lifecycle hooks and metadata extraction.
+ * Creates a normalized room definition with default values and socket.io-like event handler methods.
+ * The returned room object supports `.on()` and `.off()` methods for event handling.
+ *
+ * @param def - Room definition with optional hooks, state, and configuration
  * @returns Normalized room definition with defaults and socket.io-like event handler methods
+ * @example
+ * ```typescript
+ * const room = defineRoom({
+ *   websocketPath: "/ws",
+ *   onConnect: (ctx) => console.log("User connected:", ctx.meta.userId),
+ *   onMessage: (ctx, frame) => console.log("Message:", frame.type)
+ * });
+ *
+ * // Register event handlers
+ * room.on("chat", (ctx, data) => {
+ *   ctx.emit.emit("message", data);
+ * });
+ * ```
  */
 declare function defineRoom<TMeta extends ConnectionMeta = ConnectionMeta, E = unknown, TState extends Record<string, unknown> = Record<string, unknown>>(def: RoomDefinition<TMeta, E, TState>): RoomDefinitionWithHandlers<TMeta, E, TState>;
 //#endregion
 //#region src/actor/attachment.d.ts
+/**
+ * Stores connection metadata as a WebSocket attachment for hibernation survival.
+ * This allows the actor to restore session information when it wakes from hibernation.
+ *
+ * @param ws - The WebSocket connection to attach metadata to
+ * @param meta - Connection metadata containing userId, clientId, and channels
+ * @throws Error if serialization fails
+ */
 declare function storeAttachment(ws: WebSocket, meta: ConnectionMeta): void;
+/**
+ * Restores WebSocket sessions from hibernation by deserializing attachments.
+ * Only restores sessions that are in OPEN state and have valid metadata.
+ * Sessions with invalid or missing metadata are skipped.
+ *
+ * @param actor - The actor instance with a sessions Map and ctx.getWebSockets() method
+ * @returns void - Sessions are added directly to actor.sessions Map
+ * @throws Error if deserialization fails critically (individual failures are logged and skipped)
+ */
 declare function restoreSessions(actor: any): void;
 //#endregion
 export { type ActorHandlerClass, type ActorStub, type BroadcastOptions, type ClientMessage, type ConnectionMeta, type MessageContext, type MessageFrame, PROTOCOL_VERSION, PersistError, PersistNotReadyError, type PersistableActor, type RoomContext, type RoomDefinition, type RpcBroadcastOptions, type SafePersistOptions, type ServerMessage, type VeraniActor, type VeraniMessage, clearPersistedState, createActorHandler, decodeClientMessage, decodeFrame, decodeServerMessage, defineRoom, deletePersistedKey, encodeClientMessage, encodeFrame, encodeServerMessage, getPersistedKeys, getPersistedState, initializePersistedState, isStateReady, persistKey, restoreSessions, safeDeserialize, safeSerialize, setPeristErrorHandler, storeAttachment };

package/package.json

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

package/dist/types-BefWc1M_.d.cts

@@ -1,46 +0,0 @@
-//#region src/shared/types.d.ts
-/**
- * Core message types shared between client and server
- */
-/**
- * Base message frame structure used for all WebSocket communication
- */
-interface MessageFrame {
-  type: string;
-  channel?: string;
-  data?: any;
-}
-/**
- * Message sent from client to server
- */
-interface ClientMessage extends MessageFrame {
-  type: string;
-  channel?: string;
-  data?: any;
-}
-/**
- * Message sent from server to client
- */
-interface ServerMessage extends MessageFrame {
-  type: string;
-  channel?: string;
-  data?: any;
-}
-/**
- * Connection metadata attached to each WebSocket
- */
-interface ConnectionMeta {
-  userId: string;
-  clientId: string;
-  channels: string[];
-}
-/**
- * Unified message type for both directions
- */
-type VeraniMessage = ClientMessage | ServerMessage;
-/**
- * Protocol version for future compatibility
- */
-declare const PROTOCOL_VERSION = "1.0.0";
-//#endregion
-export { ServerMessage as a, PROTOCOL_VERSION as i, ConnectionMeta as n, VeraniMessage as o, MessageFrame as r, ClientMessage as t };

package/dist/types-Ds_V-GWZ.d.mts

@@ -1,46 +0,0 @@
-//#region src/shared/types.d.ts
-/**
- * Core message types shared between client and server
- */
-/**
- * Base message frame structure used for all WebSocket communication
- */
-interface MessageFrame {
-  type: string;
-  channel?: string;
-  data?: any;
-}
-/**
- * Message sent from client to server
- */
-interface ClientMessage extends MessageFrame {
-  type: string;
-  channel?: string;
-  data?: any;
-}
-/**
- * Message sent from server to client
- */
-interface ServerMessage extends MessageFrame {
-  type: string;
-  channel?: string;
-  data?: any;
-}
-/**
- * Connection metadata attached to each WebSocket
- */
-interface ConnectionMeta {
-  userId: string;
-  clientId: string;
-  channels: string[];
-}
-/**
- * Unified message type for both directions
- */
-type VeraniMessage = ClientMessage | ServerMessage;
-/**
- * Protocol version for future compatibility
- */
-declare const PROTOCOL_VERSION = "1.0.0";
-//#endregion
-export { ServerMessage as a, PROTOCOL_VERSION as i, ConnectionMeta as n, VeraniMessage as o, MessageFrame as r, ClientMessage as t };