verani 0.7.0 → 0.8.1

package/README.md

@@ -35,7 +35,7 @@ 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 +64,17 @@ 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);
 ```
 
 ### 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 +95,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 +193,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-98JPmjaf.d.cts → actor-runtime-1TpQk-wg.d.cts}

@@ -1,8 +1,104 @@
-import { n as ConnectionMeta, r as MessageFrame } from "./types-BefWc1M_.cjs";
+import { n as ConnectionMeta, r as MessageFrame } from "./types-DOI6EHQJ.cjs";
 import { Actor, ActorConfiguration } from "@cloudflare/actors";
 
-//#region src/actor/types.d.ts
+//#region src/actor/persist.d.ts
 
+declare const PERSIST_ERROR_HANDLER: unique symbol;
+declare const PERSISTED_STATE: unique symbol;
+declare const STATE_READY: unique symbol;
+/**
+ * Error thrown when persisted state is accessed before initialization
+ */
+declare class PersistNotReadyError extends Error {
+  constructor(key: string);
+}
+/**
+ * Error thrown when persistence operation fails
+ */
+declare class PersistError extends Error {
+  readonly originalCause: Error;
+  constructor(key: string, cause: Error);
+}
+/**
+ * Options for SafePersist behavior
+ */
+interface SafePersistOptions {
+  /**
+   * If true, only track top-level property changes (no deep proxy).
+   * This is safer and more predictable. Default: true
+   */
+  shallow?: boolean;
+  /**
+   * If true, throw errors instead of swallowing them. Default: true
+   */
+  throwOnError?: boolean;
+}
+/**
+ * Safely serialize a value for storage.
+ * Handles circular references and special types gracefully.
+ */
+declare function safeSerialize(value: unknown): string;
+/**
+ * Safely deserialize a value from storage.
+ * Restores special types that were serialized.
+ */
+declare function safeDeserialize(json: string): unknown;
+/**
+ * Interface for actors that support safe persistence
+ */
+interface PersistableActor {
+  /** Durable Object storage interface */
+  ctx: {
+    storage: DurableObjectStorage;
+  };
+  /** Whether the state has been initialized from storage */
+  [STATE_READY]?: boolean;
+  /** The persisted state object */
+  [PERSISTED_STATE]?: Record<string, unknown>;
+  /** Error handler for persistence failures */
+  [PERSIST_ERROR_HANDLER]?: (key: string, error: Error) => void;
+}
+/**
+ * Initialize persisted state from Durable Object storage.
+ * Call this in the actor's onInit or constructor after storage is available.
+ *
+ * @param actor - The actor instance
+ * @param initialState - Default state values
+ * @param persistedKeys - Keys to persist (empty = all keys)
+ * @param options - Persistence options
+ */
+declare function initializePersistedState<T extends Record<string, unknown>>(actor: PersistableActor, initialState: T, persistedKeys?: (keyof T)[], options?: SafePersistOptions): Promise<T>;
+/**
+ * Helper to check if state is ready for access
+ */
+declare function isStateReady(actor: PersistableActor): boolean;
+/**
+ * Helper to get persisted state with type safety.
+ * Throws if state is not yet initialized.
+ */
+declare function getPersistedState<T extends Record<string, unknown>>(actor: PersistableActor): T;
+/**
+ * Set the error handler for persistence failures
+ */
+declare function setPeristErrorHandler(actor: PersistableActor, handler: (key: string, error: Error) => void): void;
+/**
+ * Manually persist a specific key (useful for batch updates)
+ */
+declare function persistKey(actor: PersistableActor, key: string, value: unknown): Promise<void>;
+/**
+ * Manually delete a persisted key
+ */
+declare function deletePersistedKey(actor: PersistableActor, key: string): Promise<void>;
+/**
+ * Get all persisted keys from storage
+ */
+declare function getPersistedKeys(actor: PersistableActor): Promise<string[]>;
+/**
+ * Clear all persisted state
+ */
+declare function clearPersistedState(actor: PersistableActor): Promise<void>;
+//#endregion
+//#region src/actor/types.d.ts
 /**
  * Options for broadcasting messages to connections
  */
@@ -101,7 +197,7 @@ interface ActorStub {
 /**
  * Extended Actor interface with Verani-specific methods
  */
-interface VeraniActor<TMeta extends ConnectionMeta = ConnectionMeta, E = unknown> extends Actor<E> {
+interface VeraniActor<TMeta extends ConnectionMeta = ConnectionMeta, E = unknown, TState extends Record<string, unknown> = Record<string, unknown>> extends Actor<E> {
   /**
    * Map of active WebSocket sessions keyed by their WebSocket instance.
    * Each entry contains the WebSocket and its associated metadata.
@@ -111,6 +207,17 @@ interface VeraniActor<TMeta extends ConnectionMeta = ConnectionMeta, E = unknown
     ws: WebSocket;
     meta: TMeta;
   }>;
+  /**
+   * User-defined persisted state for this actor.
+   * Access this after onInit completes. Changes to tracked keys are automatically persisted.
+   * @see RoomDefinition.state and RoomDefinition.persistedKeys
+   */
+  roomState: TState;
+  /**
+   * Check if the persisted state has been initialized.
+   * Returns true after onInit completes and state is loaded from storage.
+   */
+  isStateReady(): boolean;
   /**
    * Broadcast a message to all connections in a channel.
    * Performs channel, userId, clientId, and exclusion filtering.
@@ -161,37 +268,37 @@ interface VeraniActor<TMeta extends ConnectionMeta = ConnectionMeta, E = unknown
 /**
  * Event handler function type for socket.io-like event handling
  */
-type EventHandler<TMeta extends ConnectionMeta = ConnectionMeta, E = unknown> = (ctx: MessageContext<TMeta, E>, data: any) => void | Promise<void>;
+type EventHandler<TMeta extends ConnectionMeta = ConnectionMeta, E = unknown, TState extends Record<string, unknown> = Record<string, unknown>> = (ctx: MessageContext<TMeta, E, TState>, data: any) => void | Promise<void>;
 /**
  * Event emitter interface for room-level event handling
  */
-interface RoomEventEmitter<TMeta extends ConnectionMeta = ConnectionMeta, E = unknown> {
+interface RoomEventEmitter<TMeta extends ConnectionMeta = ConnectionMeta, E = unknown, TState extends Record<string, unknown> = Record<string, unknown>> {
   /**
    * Register an event handler
    * @param event - Event name (supports wildcard "*")
    * @param handler - Handler function
    */
-  on(event: string, handler: EventHandler<TMeta, E>): void;
+  on(event: string, handler: EventHandler<TMeta, E, TState>): void;
   /**
    * Remove an event handler
    * @param event - Event name
    * @param handler - Optional specific handler to remove, or remove all handlers for event
    */
-  off(event: string, handler?: EventHandler<TMeta, E>): void;
+  off(event: string, handler?: EventHandler<TMeta, E, TState>): void;
   /**
    * Emit an event to registered handlers
    * @param event - Event name
    * @param ctx - Message context
    * @param data - Event data
    */
-  emit(event: string, ctx: MessageContext<TMeta, E>, data: any): Promise<void>;
+  emit(event: string, ctx: MessageContext<TMeta, E, TState>, data: any): Promise<void>;
   /**
    * Rebuild handlers from static storage.
    * Called after hibernation to restore handlers from the room definition.
    * This method MUST be implemented by all event emitter implementations.
    * @param staticHandlers - Map of event names to handler sets from static storage
    */
-  rebuildHandlers(staticHandlers: Map<string, Set<EventHandler<TMeta, E>>>): void;
+  rebuildHandlers(staticHandlers: Map<string, Set<EventHandler<TMeta, E, TState>>>): void;
 }
 /**
  * Builder interface for targeting specific scopes when emitting
@@ -245,9 +352,9 @@ interface ActorEmit<TMeta extends ConnectionMeta = ConnectionMeta, E = unknown>
 /**
  * Context provided to room lifecycle hooks
  */
-interface RoomContext<TMeta extends ConnectionMeta = ConnectionMeta, E = unknown> {
+interface RoomContext<TMeta extends ConnectionMeta = ConnectionMeta, E = unknown, TState extends Record<string, unknown> = Record<string, unknown>> {
   /** The actor instance handling this connection */
-  actor: VeraniActor<TMeta, E>;
+  actor: VeraniActor<TMeta, E, TState>;
   /** The WebSocket connection */
   ws: WebSocket;
   /** Connection metadata */
@@ -258,7 +365,7 @@ interface RoomContext<TMeta extends ConnectionMeta = ConnectionMeta, E = unknown
 /**
  * Context for onMessage hook with frame included
  */
-interface MessageContext<TMeta extends ConnectionMeta = ConnectionMeta, E = unknown> extends RoomContext<TMeta, E> {
+interface MessageContext<TMeta extends ConnectionMeta = ConnectionMeta, E = unknown, TState extends Record<string, unknown> = Record<string, unknown>> extends RoomContext<TMeta, E, TState> {
   /** The received message frame */
   frame: MessageFrame;
 }
@@ -268,8 +375,12 @@ interface MessageContext<TMeta extends ConnectionMeta = ConnectionMeta, E = unkn
  * **Important:** All lifecycle hooks are properly awaited if they return a Promise.
  * This ensures async operations complete before the actor proceeds to the next step
  * or potentially enters hibernation.
+ *
+ * @template TMeta - Connection metadata type
+ * @template E - Environment type
+ * @template TState - Room state type (for persistence)
  */
-interface RoomDefinition<TMeta extends ConnectionMeta = ConnectionMeta, E = unknown> {
+interface RoomDefinition<TMeta extends ConnectionMeta = ConnectionMeta, E = unknown, TState extends Record<string, unknown> = Record<string, unknown>> {
   /** Optional room name for debugging */
   name?: string;
   /** WebSocket upgrade path (default: "/ws") */
@@ -285,13 +396,13 @@ interface RoomDefinition<TMeta extends ConnectionMeta = ConnectionMeta, E = unkn
    * sessions map after this hook completes successfully. If this hook throws, the
    * connection is closed and no orphaned session is created.
    */
-  onConnect?(ctx: RoomContext<TMeta, E>): void | Promise<void>;
+  onConnect?(ctx: RoomContext<TMeta, E, TState>): void | Promise<void>;
   /**
    * Called when a WebSocket connection is closed.
    * This hook is awaited if it returns a Promise. The session is removed from the
    * sessions map before this hook is called.
    */
-  onDisconnect?(ctx: RoomContext<TMeta, E>): void | Promise<void>;
+  onDisconnect?(ctx: RoomContext<TMeta, E, TState>): void | Promise<void>;
   /**
    * Called when a message is received from a connection.
    * This hook is awaited if it returns a Promise. The actor will not process
@@ -300,30 +411,71 @@ interface RoomDefinition<TMeta extends ConnectionMeta = ConnectionMeta, E = unkn
    * **Note:** If event handlers are registered via `eventEmitter`, they take priority.
    * This hook is used as a fallback when no matching event handler is found.
    */
-  onMessage?(ctx: MessageContext<TMeta, E>, frame: MessageFrame): void | Promise<void>;
+  onMessage?(ctx: MessageContext<TMeta, E, TState>, frame: MessageFrame): void | Promise<void>;
   /**
    * Called when an error occurs in a lifecycle hook.
    * This hook is also awaited if it returns a Promise.
    */
-  onError?(error: Error, ctx: RoomContext<TMeta, E>): void | Promise<void>;
+  onError?(error: Error, ctx: RoomContext<TMeta, E, TState>): void | Promise<void>;
   /**
    * Called after actor wakes from hibernation and sessions are restored.
    * This hook is awaited if it returns a Promise. It is called even if some
    * sessions failed to restore, allowing you to handle partial restoration scenarios.
    */
-  onHibernationRestore?(actor: VeraniActor<TMeta, E>): void | Promise<void>;
+  onHibernationRestore?(actor: VeraniActor<TMeta, E, TState>): void | Promise<void>;
   /**
    * Event emitter for socket.io-like event handling.
    * If provided, event handlers registered here will be called for matching message types.
    * If not provided, a default event emitter will be created.
    */
-  eventEmitter?: RoomEventEmitter<TMeta, E>;
+  eventEmitter?: RoomEventEmitter<TMeta, E, TState>;
   /**
    * Static handler storage that persists across hibernation.
    * Handlers registered via room.on() are stored here and rebuilt in onInit.
    * @internal
    */
-  _staticHandlers?: Map<string, Set<EventHandler<TMeta, E>>>;
+  _staticHandlers?: Map<string, Set<EventHandler<TMeta, E, TState>>>;
+  /**
+   * Initial state for this room. This object defines the default values
+   * for your room's state. Access via `actor.roomState` in lifecycle hooks.
+   *
+   * @example
+   * ```typescript
+   * const room = defineRoom({
+   *   state: {
+   *     messageCount: 0,
+   *     lastActivity: null as Date | null,
+   *     settings: { maxUsers: 100 }
+   *   },
+   *   persistedKeys: ['messageCount', 'settings'],
+   *   // ...
+   * });
+   * ```
+   */
+  state?: TState;
+  /**
+   * Keys from `state` to persist to Durable Object storage.
+   * If empty or undefined, no state is persisted.
+   * Changes to these keys are automatically saved and restored on hibernation wake.
+   *
+   * @example
+   * ```typescript
+   * persistedKeys: ['messageCount', 'settings'] // Only these keys are persisted
+   * ```
+   */
+  persistedKeys?: (string & keyof TState)[];
+  /**
+   * Options for state persistence behavior.
+   */
+  persistOptions?: SafePersistOptions;
+  /**
+   * Called when persistence fails for a key.
+   * Use this to handle errors gracefully (e.g., notify admins, fallback behavior).
+   *
+   * @param key - The state key that failed to persist
+   * @param error - The error that occurred
+   */
+  onPersistError?(key: string, error: Error): void;
 }
 //#endregion
 //#region src/actor/actor-runtime.d.ts
@@ -340,6 +492,6 @@ type ActorHandlerClass<E = unknown> = {
  * @param room - The room definition with lifecycle hooks
  * @returns Actor class for Cloudflare Workers (extends DurableObject)
  */
-declare function createActorHandler<TMeta extends ConnectionMeta = ConnectionMeta, E = unknown>(room: RoomDefinition<TMeta, E>): ActorHandlerClass<E>;
+declare function createActorHandler<TMeta extends ConnectionMeta = ConnectionMeta, E = unknown, TState extends Record<string, unknown> = Record<string, unknown>>(room: RoomDefinition<TMeta, E, TState>): ActorHandlerClass<E>;
 //#endregion
-export { EventHandler as a, RoomDefinition as c, BroadcastOptions as i, RpcBroadcastOptions as l, createActorHandler as n, MessageContext as o, ActorStub as r, RoomContext as s, ActorHandlerClass as t, VeraniActor as u };
+export { safeSerialize as C, safeDeserialize as S, getPersistedKeys as _, EventHandler as a, isStateReady as b, RoomDefinition as c, PersistError as d, PersistNotReadyError as f, deletePersistedKey as g, clearPersistedState as h, BroadcastOptions as i, RpcBroadcastOptions as l, SafePersistOptions as m, createActorHandler as n, MessageContext as o, PersistableActor as p, ActorStub as r, RoomContext as s, ActorHandlerClass as t, VeraniActor as u, getPersistedState as v, setPeristErrorHandler as w, persistKey as x, initializePersistedState as y };