verani 0.11.1 → 0.12.2

package/dist/connection-actor-B5AzPIkG.mjs

@@ -0,0 +1 @@
+import{n as encodeFrame$1}from"./encode-CFndA-BQ.mjs";import{Actor}from"@cloudflare/actors";function storeAttachment(e,f){e.serializeAttachment(f)}function encodeFrame(f){return encodeFrame$1(f)}const PERSIST_ERROR_HANDLER=Symbol(`PERSIST_ERROR_HANDLER`),PERSISTED_STATE=Symbol(`PERSISTED_STATE`),STATE_READY=Symbol(`STATE_READY`);var PersistNotReadyError=class extends Error{constructor(e){super(`Cannot access persisted state key "${e}" before storage is initialized. Wait for onInit to complete or check actor.isStateReady().`),this.name=`PersistNotReadyError`}},PersistError=class extends Error{constructor(e,f){super(`Failed to persist key "${e}": ${f.message}`),this.name=`PersistError`,this.originalCause=f}};function safeSerialize(e){let f=new WeakSet;return JSON.stringify(e,(e,p)=>{if(p instanceof Date)return{__type:`Date`,value:p.toISOString()};if(p instanceof RegExp)return{__type:`RegExp`,source:p.source,flags:p.flags};if(p instanceof Map)return{__type:`Map`,entries:Array.from(p.entries())};if(p instanceof Set)return{__type:`Set`,values:Array.from(p.values())};if(p instanceof Error)return{__type:`Error`,name:p.name,message:p.message};if(typeof p==`object`&&p){if(f.has(p))return;f.add(p)}if(!(typeof p==`function`||typeof p==`symbol`))return p})}function safeDeserialize(e){return JSON.parse(e,(e,f)=>{if(f&&typeof f==`object`&&f.__type)switch(f.__type){case`Date`:return new Date(f.value);case`RegExp`:return new RegExp(f.source,f.flags);case`Map`:return new Map(f.entries);case`Set`:return new Set(f.values);case`Error`:{let e=Error(f.message);return e.name=f.name,e}}return f})}function createShallowProxy(e,f,p){return new Proxy(e,{set(e,p,m){let h=Reflect.set(e,p,m);return h&&typeof p==`string`&&f(p,m),h},deleteProperty(e,f){let m=Reflect.deleteProperty(e,f);return m&&typeof f==`string`&&p(f),m}})}async function initializePersistedState(e,f,p=[],m={}){let{shallow:v=!0,throwOnError:b=!0}=m,x=e.ctx.storage,S=p.length>0?p.map(String):Object.keys(f),C={...f};for(let e of S)try{let f=await x.get(`_verani_persist:${e}`);if(f!==void 0)try{C[e]=safeDeserialize(f)}catch(f){if(b)throw new PersistError(e,f)}}catch(f){if(b&&!(f instanceof PersistError))throw new PersistError(e,f)}let w=async(f,p)=>{if(S.includes(f))try{let e=safeSerialize(p);await x.put(`_verani_persist:${f}`,e)}catch(p){let m=e[PERSIST_ERROR_HANDLER];if(m&&m(f,p),b)throw new PersistError(f,p)}},T=async f=>{if(S.includes(f))try{await x.delete(`_verani_persist:${f}`)}catch(p){let m=e[PERSIST_ERROR_HANDLER];if(m&&m(f,p),b)throw new PersistError(f,p)}},E;return E=v?createShallowProxy(C,(e,f)=>{w(String(e),f)},e=>{T(String(e))}):createDeepProxy(C,(e,f)=>{w(e,f)},e=>{T(e)},S),e[STATE_READY]=!0,e[PERSISTED_STATE]=E,E}function createDeepProxy(e,f,p,m,h,g){return new Proxy(e,{get(_,v){let y=Reflect.get(_,v);if(y&&typeof y==`object`&&!Array.isArray(y)){let _=g??String(v);if(m.includes(_)||g!==void 0)return createDeepProxy(y,f,p,m,h??e,_)}return y},set(e,p,_){let v=Reflect.set(e,p,_);if(v){let e=g??String(p);m.includes(e)&&(g&&h?f(g,h[g]):f(String(p),_))}return v},deleteProperty(e,_){let v=Reflect.deleteProperty(e,_);if(v){let e=g??String(_);m.includes(e)&&(g&&h?f(g,h[g]):p(String(_)))}return v}})}function isStateReady(e){return e[STATE_READY]===!0}function getPersistedState(e){if(!isStateReady(e))throw new PersistNotReadyError(`state`);return e[PERSISTED_STATE]}function setPersistErrorHandler(e,f){e[PERSIST_ERROR_HANDLER]=f}const setPeristErrorHandler=setPersistErrorHandler;async function persistKey(e,f,p){let m=safeSerialize(p);await e.ctx.storage.put(`_verani_persist:${f}`,m)}async function deletePersistedKey(e,f){await e.ctx.storage.delete(`_verani_persist:${f}`)}async function getPersistedKeys(e){let f=await e.ctx.storage.list({prefix:`_verani_persist:`});return Array.from(f.keys()).map(e=>e.replace(`_verani_persist:`,``))}async function clearPersistedState(e){let f=await e.ctx.storage.list({prefix:`_verani_persist:`}),p=Array.from(f.keys());await e.ctx.storage.delete(p)}const WS=Symbol(`WS`),META=Symbol(`META`),ROOMS=Symbol(`ROOMS`);function createConnectionHandler(e){let h=e.name||`VeraniConnectionDO`,v=e.websocketPath||`/ws`;class y extends Actor{constructor(...f){super(...f),this[WS]=null,this[META]=null,this[ROOMS]=new Map,this[STATE_READY]=!1,this[PERSISTED_STATE]=e.state?{...e.state}:{},this.handlers=new Map}get connectionState(){return this[PERSISTED_STATE]}isStateReady(){return isStateReady(this)}static configuration(e){return{sockets:{upgradePath:v}}}getRoomBinding(f){if(!e.rooms)throw Error(`Cannot access room "${f}": no "rooms" config provided in ConnectionDefinition. Add rooms: { "${f}": "YourRoomBinding" } to your definition.`);let p=e.rooms[f]??e.rooms[f.split(`:`,1)[0]];if(!p)throw Error(`Cannot access room "${f}": not found in "rooms" config. Available rooms: ${Object.keys(e.rooms).join(`, `)}`);let m=this.env[p];if(!m)throw Error(`Room "${f}" binding "${p}" not found in environment. Check your wrangler.toml durable_objects bindings.`);return m}getConnectionBinding(){if(!e.connectionBinding)throw Error(`Cannot resolve ConnectionDO: no "connectionBinding" provided in ConnectionDefinition. Add connectionBinding: "YourConnectionBinding" to your definition.`);let f=this.env[e.connectionBinding];if(!f)throw Error(`ConnectionDO binding "${e.connectionBinding}" not found in environment. Check your wrangler.toml durable_objects bindings.`);return f}createEmit(){let e=this;return{emit(f,p){e.sendToWebSocket(f,p)},to(f){return f.startsWith(`room:`)?e.createRoomEmitBuilder(f.slice(5)):e.createUserEmitBuilder(f)},toRoom(f,p){return e.createRoomEmitBuilder(f,p)},toUser(f){return e.createUserEmitBuilder(f)}}}createRoomEmitBuilder(e,f){let p=this;return{async emit(m,h){try{let g=p.getRoomBinding(e).get(e),_=f?.includeSelf||!p[META]?.userId?void 0:{exceptUserId:p[META].userId};return await g.broadcast(m,h,_)}catch{return 0}}}}createUserEmitBuilder(e){let f=this;return{async emit(p,m){try{return await f.getConnectionBinding().get(e).deliverMessage(p,m)?1:0}catch{return 0}}}}sendToWebSocket(e,f){let p=this[WS];if(!p||p.readyState!==WebSocket.OPEN)return!1;try{let h={type:`event`,channel:`default`,data:{type:e,...f}};return p.send(encodeFrame(h)),!0}catch{return!1}}createContext(){return{actor:this,ws:this[WS],meta:this[META],emit:this.createEmit(),state:this.connectionState}}async onInit(){e.state&&(e.onPersistError&&setPeristErrorHandler(this,e.onPersistError),this[PERSISTED_STATE]=await initializePersistedState(this,e.state,e.persistedKeys,e.persistOptions));let f=await this.ctx.storage.get(`_connection_rooms`);if(f&&Array.isArray(f)&&(this[ROOMS]=new Map(f.map(e=>[e.roomName,e.metadata]))),e.handlers)for(let[f,p]of e.handlers.entries())this.handlers.set(f,p);let p=this.ctx.getWebSockets();if(p.length>0){let f=p[0];if(f.readyState===WebSocket.OPEN){this[WS]=f;let p=f.deserializeAttachment();p&&(this[META]=p,await this.rejoinRoomsAfterHibernation(),e.onHibernationRestore&&await e.onHibernationRestore(this))}}}shouldUpgradeSocket(e){return!0}onWebSocketUpgrade(e){let f=new WebSocketPair,[p,m]=Object.values(f);this.ctx.acceptWebSocket(m);let h=new Response(null,{status:101,webSocket:p});return Promise.resolve().then(()=>{this.onWebSocketConnect(m,e)}),h}async onWebSocketConnect(f,m){this[WS]&&this[WS].readyState===WebSocket.OPEN&&this[WS].close(1e3,`New connection established`);let h;if(h=e.extractMeta?await e.extractMeta(m):{userId:`anonymous`,clientId:crypto.randomUUID(),channels:[`default`]},storeAttachment(f,h),this[WS]=f,this[META]=h,e.onConnect)try{await e.onConnect(this.createContext())}catch(p){e.onError&&await e.onError(p,this.createContext()),f.close(1011,`Connection handler error`);return}}async onWebSocketMessage(f,p){if(this[META])try{let f=typeof p==`string`?p:p.toString(),m=JSON.parse(f),h=m,g=h.data,_=g?.type||h.type,v=this.handlers.get(_);if(v){await v(this.createContext(),g);return}e.onMessage&&await e.onMessage(this.createContext(),m)}catch(f){e.onError&&await e.onError(f,this.createContext())}}async onWebSocketDisconnect(f){if(this[META]&&e.onDisconnect)try{await e.onDisconnect(this.createContext())}catch{}for(let e of this[ROOMS].keys())try{await this.leaveRoomInternal(e)}catch{}this[WS]=null}async deliverMessage(e,f){return this.sendToWebSocket(e,f)}async deliverSystemEvent(e,f){this.sendToWebSocket(`system:${e}`,f)}async getUserId(){return this[META]?.userId??null}async isConnected(){return this[WS]!==null&&this[WS].readyState===WebSocket.OPEN}async joinRoom(e,f){if(!this[META])throw Error(`Cannot join room: not connected`);await this.getRoomBinding(e).get(e).join(this[META].userId,f),this[ROOMS].set(e,f),await this.persistRooms()}async persistRooms(){let e=Array.from(this[ROOMS].entries()).map(([e,f])=>({roomName:e,metadata:f}));await this.ctx.storage.put(`_connection_rooms`,e)}async rejoinRoomsAfterHibernation(){if(this[ROOMS].size===0)return;let e=this[META]?.userId;if(!e)return;let f=[];for(let[p,m]of this[ROOMS].entries())try{await this.getRoomBinding(p).get(p).join(e,m)}catch{f.push(p)}if(f.length>0){for(let e of f)this[ROOMS].delete(e);await this.persistRooms()}}async leaveRoomInternal(e){this[META]&&await this.getRoomBinding(e).get(e).leave(this[META].userId)}async leaveRoom(e){if(!this[META])throw Error(`Cannot leave room: not connected`);await this.leaveRoomInternal(e),this[ROOMS].delete(e),await this.persistRooms()}async getRooms(){return Array.from(this[ROOMS].keys())}getStorage(){return this.ctx.storage}on(e,f){this.handlers.set(e,f)}off(e){this.handlers.delete(e)}async destroy(){for(let e of this[ROOMS].keys())try{await this.leaveRoomInternal(e)}catch{}this[WS]&&this[WS].readyState===WebSocket.OPEN&&this[WS].close(1e3,`Actor destroyed`),e.onDestroy&&this[META]&&await e.onDestroy(this.createContext()),await super.destroy()}}return Object.defineProperty(y,`name`,{value:h,writable:!1,configurable:!0}),y}function defineConnection(e){let f=new Map;return{...e,handlers:f,on(e,p){f.set(e,p)},off(e){f.delete(e)}}}export{clearPersistedState as a,getPersistedState as c,persistKey as d,safeDeserialize as f,storeAttachment as g,setPersistErrorHandler as h,PersistNotReadyError as i,initializePersistedState as l,setPeristErrorHandler as m,defineConnection as n,deletePersistedKey as o,safeSerialize as p,PersistError as r,getPersistedKeys as s,createConnectionHandler as t,isStateReady as u};

package/dist/connection-actor-D1QRniw1.d.mts

@@ -0,0 +1,404 @@
+import { n as ConnectionMeta } from "./types-6m1L8QLb.mjs";
+import { Actor, ActorConfiguration } from "@cloudflare/actors";
+
+//#region src/actor/types.d.ts
+
+/**
+ * Options for broadcasting messages to connections
+ */
+interface BroadcastOptions {
+  /** Exclude specific WebSocket from receiving the broadcast (local only) */
+  except?: WebSocket;
+  /** Exclude a specific userId from receiving the broadcast (RPC-safe) */
+  exceptUserId?: string;
+  /** Only send to specific user IDs */
+  userIds?: string[];
+  /** Only send to specific client IDs */
+  clientIds?: string[];
+}
+interface RoomEmitOptions {
+  /** Include the sender when broadcasting to a room */
+  includeSelf?: boolean;
+}
+/**
+ * RPC-safe version of BroadcastOptions for use over RPC calls.
+ * Excludes the `except` field since WebSocket cannot be serialized over RPC.
+ */
+interface RpcBroadcastOptions {
+  /** Exclude a specific userId from receiving the broadcast */
+  exceptUserId?: string;
+  /** Only send to specific user IDs */
+  userIds?: string[];
+  /** Only send to specific client IDs */
+  clientIds?: string[];
+}
+/**
+ * Represents a member in a RoomDO
+ */
+interface RoomMember {
+  /** The user's unique identifier */
+  userId: string;
+  /** Timestamp when the user joined this room */
+  joinedAt: number;
+  /** Optional metadata associated with this member */
+  metadata?: Record<string, unknown>;
+}
+/**
+ * Definition for creating a RoomDO (coordination Durable Object)
+ *
+ * RoomDOs manage room membership and coordinate message delivery between
+ * ConnectionDOs. They do NOT hold WebSocket connections directly.
+ */
+interface RoomCoordinatorDefinition<E = unknown> {
+  /** Optional room name for debugging */
+  name?: string;
+  /**
+   * Environment binding key for the ConnectionDO class.
+   * Must match the binding name in wrangler.toml/wrangler.jsonc.
+   * Required for broadcast message delivery to work.
+   *
+   * @example "UserConnection"
+   */
+  connectionBinding?: string;
+  /**
+   * Maximum consecutive delivery failures before a member is considered stale
+   * and automatically removed from the room. Default: 3
+   */
+  maxDeliveryFailures?: number;
+  /**
+   * Called when the RoomDO initializes or wakes from hibernation
+   */
+  onInit?(roomState: Record<string, unknown>): void | Promise<void>;
+  /**
+   * Called when a user joins this room
+   */
+  onJoin?(roomState: Record<string, unknown>, userId: string, metadata?: Record<string, unknown>): void | Promise<void>;
+  /**
+   * Called when a user leaves this room
+   */
+  onLeave?(roomState: Record<string, unknown>, userId: string): void | Promise<void>;
+  /**
+   * Called before the actor is destroyed and all storage is cleared.
+   * Use for cleanup logic (e.g., notifying other services).
+   */
+  onDestroy?(roomState: Record<string, unknown>): void | Promise<void>;
+}
+/**
+ * Stub interface for ConnectionDO - supports RPC calls from other DOs
+ *
+ * ConnectionDOs own a single WebSocket connection and receive messages
+ * from RoomDOs via RPC for delivery to their connected client.
+ */
+interface ConnectionActorStub {
+  /**
+   * Standard fetch method for handling HTTP requests and WebSocket upgrades
+   */
+  fetch(request: Request): Promise<Response>;
+  /**
+   * Deliver a message to this connection's WebSocket (called via RPC from RoomDO)
+   * @param event - Event name
+   * @param data - Event data
+   * @returns Promise resolving to true if delivered, false if connection is closed
+   */
+  deliverMessage<TData = unknown>(event: string, data?: TData): Promise<boolean>;
+  /**
+   * Deliver a system event to this connection (presence updates, room events, etc.)
+   * @param type - System event type
+   * @param payload - Event payload
+   */
+  deliverSystemEvent<TPayload = unknown>(type: string, payload?: TPayload): Promise<void>;
+  /**
+   * Get the userId this connection belongs to
+   */
+  getUserId(): Promise<string | null>;
+  /**
+   * Check if this connection is still active
+   */
+  isConnected(): Promise<boolean>;
+  /**
+   * Join a room (registers with the RoomDO)
+   * @param roomName - Name of the room to join
+   * @param metadata - Optional metadata to include with membership
+   */
+  joinRoom(roomName: string, metadata?: Record<string, unknown>): Promise<void>;
+  /**
+   * Leave a room (unregisters from the RoomDO)
+   * @param roomName - Name of the room to leave
+   */
+  leaveRoom(roomName: string): Promise<void>;
+  /**
+   * Get list of rooms this connection is a member of
+   */
+  getRooms(): Promise<string[]>;
+}
+/**
+ * Environment type with Durable Object bindings for Verani.
+ * Users should extend this with their actual binding names from wrangler.toml.
+ *
+ * @example
+ * ```typescript
+ * interface Env extends VeraniEnv {
+ *   UserConnection: DurableObjectNamespace;
+ *   PresenceRoom: DurableObjectNamespace;
+ *   ChatRoom: DurableObjectNamespace;
+ * }
+ * ```
+ */
+interface VeraniEnv {
+  [key: string]: unknown;
+}
+/**
+ * ConnectionActor interface for single-WebSocket-per-DO model
+ *
+ * Each ConnectionActor owns exactly one WebSocket connection for a single user.
+ */
+interface ConnectionActor<TMeta extends ConnectionMeta = ConnectionMeta, E = unknown, TState extends Record<string, unknown> = Record<string, unknown>> extends Actor<E> {
+  /**
+   * The single WebSocket connection owned by this DO (null if not connected)
+   */
+  ws: WebSocket | null;
+  /**
+   * Connection metadata for this user
+   */
+  meta: TMeta | null;
+  /**
+   * Set of room names this connection is a member of
+   */
+  rooms: Set<string>;
+  /**
+   * User-defined persisted state for this connection actor
+   */
+  connectionState: TState;
+  /**
+   * Check if this connection has an active WebSocket
+   */
+  isConnected(): boolean;
+  /**
+   * Deliver a message to this connection's WebSocket
+   * Called via RPC from RoomDO
+   */
+  deliverMessage<TData = unknown>(event: string, data?: TData): Promise<boolean>;
+  /**
+   * Deliver a system event (presence, room events, etc.)
+   */
+  deliverSystemEvent<TPayload = unknown>(type: string, payload?: TPayload): Promise<void>;
+  /**
+   * Join a room (register with RoomDO)
+   */
+  joinRoom(roomName: string, metadata?: Record<string, unknown>): Promise<void>;
+  /**
+   * Leave a room (unregister from RoomDO)
+   */
+  leaveRoom(roomName: string): Promise<void>;
+  /**
+   * Socket.io-like emit API for this connection
+   */
+  emit: ConnectionEmit<TMeta, E>;
+  /**
+   * Access the Durable Object storage API
+   */
+  getStorage(): DurableObjectStorage;
+}
+/**
+ * Connection-level emit API (for single-connection DO)
+ * Routes to appropriate RoomDO or ConnectionDO via RPC
+ */
+interface ConnectionEmit<TMeta extends ConnectionMeta = ConnectionMeta, E = unknown> {
+  /**
+   * Emit to this connection's WebSocket
+   * @param event - Event name
+   * @param data - Event data
+   */
+  emit<TData = unknown>(event: string, data?: TData): void;
+  /**
+   * Target a specific room or user for emitting
+   * @param target - Room name (if starts with "room:") or userId
+   * @returns Builder for emitting to the target via RPC
+   */
+  to(target: string): AsyncEmitBuilder;
+  /**
+   * Target a specific room for broadcasting
+   * @param roomName - Room name
+   * @returns Builder for broadcasting to the room via RPC
+   */
+  toRoom(roomName: string, options?: RoomEmitOptions): AsyncEmitBuilder;
+  /**
+   * Target a specific user for direct messaging
+   * @param userId - User ID
+   * @returns Builder for sending to the user via RPC
+   */
+  toUser(userId: string): AsyncEmitBuilder;
+}
+/**
+ * Async emit builder for RPC-based emit operations
+ */
+interface AsyncEmitBuilder {
+  /**
+   * Emit to the targeted scope via RPC
+   * @param event - Event name
+   * @param data - Event data
+   * @returns Promise resolving to number of recipients
+   */
+  emit<TData = unknown>(event: string, data?: TData): Promise<number>;
+}
+//#endregion
+//#region src/actor/connection-actor.d.ts
+/**
+ * Definition for creating a ConnectionDO (per-user connection handler)
+ */
+interface ConnectionDefinition<TMeta extends ConnectionMeta = ConnectionMeta, E = unknown, TState extends Record<string, unknown> = Record<string, unknown>> {
+  /** Optional name for debugging */
+  name?: string;
+  /** WebSocket upgrade path (default: "/ws") */
+  websocketPath?: string;
+  /**
+   * Map of room names to their environment binding keys.
+   * Must match binding names in wrangler.toml/wrangler.jsonc.
+   * Required for room features (joinRoom, toRoom, etc.).
+   *
+   * @example { "presence": "PresenceRoom", "chat": "ChatRoom" }
+   */
+  rooms?: Record<string, string>;
+  /**
+   * Environment binding key for the ConnectionDO class.
+   * Must match the binding name in wrangler.toml/wrangler.jsonc.
+   * Required for user-to-user messaging (toUser).
+   *
+   * @example "UserConnection"
+   */
+  connectionBinding?: string;
+  /**
+   * Extract metadata from the connection request
+   */
+  extractMeta?(req: Request): TMeta | Promise<TMeta>;
+  /**
+   * Called when a WebSocket connection is established
+   */
+  onConnect?(ctx: ConnectionContext<TMeta, E, TState>): void | Promise<void>;
+  /**
+   * Called when the WebSocket connection is closed
+   */
+  onDisconnect?(ctx: ConnectionContext<TMeta, E, TState>): void | Promise<void>;
+  /**
+   * Called when a message is received from the WebSocket
+   */
+  onMessage?(ctx: ConnectionContext<TMeta, E, TState>, frame: unknown): void | Promise<void>;
+  /**
+   * Called when an error occurs
+   */
+  onError?(error: Error, ctx: ConnectionContext<TMeta, E, TState>): void | Promise<void>;
+  /**
+   * Called after waking from hibernation
+   */
+  onHibernationRestore?(actor: ConnectionHandlerInstance<TMeta, E, TState>): void | Promise<void>;
+  /**
+   * Event handlers map (socket.io-like)
+   */
+  handlers?: Map<string, (ctx: ConnectionContext<TMeta, E, TState>, data: unknown) => void | Promise<void>>;
+  /**
+   * Initial state for this connection
+   */
+  state?: TState;
+  /**
+   * Keys to persist to storage
+   */
+  persistedKeys?: (string & keyof TState)[];
+  /**
+   * Persistence options
+   */
+  persistOptions?: {
+    shallow?: boolean;
+    throwOnError?: boolean;
+  };
+  /**
+   * Called when persistence fails
+   */
+  onPersistError?(key: string, error: Error): void;
+  /**
+   * Called before the actor is destroyed and all storage is cleared.
+   * Use for cleanup (e.g., leaving rooms, notifying services).
+   */
+  onDestroy?(ctx: ConnectionContext<TMeta, E, TState>): void | Promise<void>;
+}
+/**
+ * Instance interface for ConnectionHandler actors
+ * Used for typing the actor parameter in lifecycle hooks
+ */
+interface ConnectionHandlerInstance<TMeta extends ConnectionMeta = ConnectionMeta, E = unknown, TState extends Record<string, unknown> = Record<string, unknown>> {
+  connectionState: TState;
+  isStateReady(): boolean;
+  getStorage(): DurableObjectStorage;
+  joinRoom(roomName: string, metadata?: Record<string, unknown>): Promise<void>;
+  leaveRoom(roomName: string): Promise<void>;
+  getRooms(): Promise<string[]>;
+}
+/**
+ * Context provided to connection lifecycle hooks
+ */
+interface ConnectionContext<TMeta extends ConnectionMeta = ConnectionMeta, E = unknown, TState extends Record<string, unknown> = Record<string, unknown>> {
+  /** The connection actor instance */
+  actor: ConnectionHandlerInstance<TMeta, E, TState>;
+  /** The WebSocket connection (may be null after disconnect) */
+  ws: WebSocket | null;
+  /** Connection metadata */
+  meta: TMeta;
+  /** Socket.io-like emit API */
+  emit: ConnectionEmit<TMeta, E>;
+  /** Persisted state */
+  state: TState;
+}
+/**
+ * Return type for createConnectionHandler
+ */
+type ConnectionHandlerClass<E = unknown> = {
+  new (state: any, env: E): Actor<E>;
+  get(userId: string): ConnectionActorStub;
+  configuration(request?: Request): ActorConfiguration;
+};
+/**
+ * Creates a Connection handler (per-user Durable Object)
+ *
+ * Each ConnectionDO owns exactly ONE WebSocket connection for a single user.
+ * Messages are received via RPC from RoomDOs and delivered to the WebSocket.
+ *
+ * @param definition - Connection definition with lifecycle hooks
+ * @returns ConnectionDO class for Cloudflare Workers
+ *
+ * @example
+ * ```typescript
+ * const UserConnection = createConnectionHandler({
+ *   name: "user-connection",
+ *   extractMeta: (req) => ({
+ *     userId: extractUserIdFromToken(req),
+ *     clientId: crypto.randomUUID(),
+ *     channels: ["default"]
+ *   }),
+ *   onConnect: (ctx) => {
+ *     console.log(`User ${ctx.meta.userId} connected`);
+ *     ctx.actor.joinRoom("presence");
+ *   },
+ *   onDisconnect: (ctx) => {
+ *     console.log(`User ${ctx.meta.userId} disconnected`);
+ *   }
+ * });
+ *
+ * // In Worker:
+ * const userId = extractUserId(request);
+ * const stub = UserConnection.get(userId);
+ * return stub.fetch(request);
+ * ```
+ */
+declare function createConnectionHandler<TMeta extends ConnectionMeta = ConnectionMeta, E = unknown, TState extends Record<string, unknown> = Record<string, unknown>>(definition: ConnectionDefinition<TMeta, E, TState>): ConnectionHandlerClass<E>;
+/**
+ * Helper to define a connection with socket.io-like event handlers
+ */
+interface ConnectionDefinitionWithHandlers<TMeta extends ConnectionMeta = ConnectionMeta, E = unknown, TState extends Record<string, unknown> = Record<string, unknown>> extends ConnectionDefinition<TMeta, E, TState> {
+  on<TData = unknown>(event: string, handler: (ctx: ConnectionContext<TMeta, E, TState>, data: TData) => void | Promise<void>): void;
+  off(event: string): void;
+}
+/**
+ * Define a connection with socket.io-like convenience methods
+ */
+declare function defineConnection<TMeta extends ConnectionMeta = ConnectionMeta, E = unknown, TState extends Record<string, unknown> = Record<string, unknown>>(def: ConnectionDefinition<TMeta, E, TState>): ConnectionDefinitionWithHandlers<TMeta, E, TState>;
+//#endregion
+export { VeraniEnv as _, ConnectionHandlerInstance as a, AsyncEmitBuilder as c, ConnectionActorStub as d, ConnectionEmit as f, RpcBroadcastOptions as g, RoomMember as h, ConnectionHandlerClass as i, BroadcastOptions as l, RoomEmitOptions as m, ConnectionDefinition as n, createConnectionHandler as o, RoomCoordinatorDefinition as p, ConnectionDefinitionWithHandlers as r, defineConnection as s, ConnectionContext as t, ConnectionActor as u };