Type Exports

All types exported from Verani.

Type Exports

All types are exported from the main package:

import type {
  // Server types
  RoomDefinition,
  RoomDefinitionWithHandlers,
  RoomContext,
  MessageContext,
  ConnectionMeta,
  MessageFrame,
  BroadcastOptions,
  RpcBroadcastOptions,
  VeraniActor,
  ActorStub,
  ActorHandlerClass,
  EventHandler,
  RoomEventEmitter,

  // Client types
  VeraniClientOptions,
  ConnectionState,
  ReconnectionConfig,

  // Shared types
  ClientMessage,
  ServerMessage,
  VeraniMessage
} from "verani";

Server Types

ConnectionMeta

Base metadata structure for connections.

interface ConnectionMeta {
  userId: string;
  clientId: string;
  channels: string[];
}

Extending:

interface CustomMeta extends ConnectionMeta {
  username: string;
  avatar?: string;
  role: "user" | "admin";
}

MessageFrame

Structure of messages sent over WebSocket.

interface MessageFrame {
  type: string;
  channel?: string;
  data?: any;
}

BroadcastOptions

Options for filtering broadcast recipients. Use this when calling broadcast() directly on the Actor instance (inside lifecycle hooks).

interface BroadcastOptions {
  except?: WebSocket;        // Exclude this connection (not available via RPC)
  userIds?: string[];        // Only send to these users
  clientIds?: string[];      // Only send to these clients
}

Note: For RPC calls, use RpcBroadcastOptions instead, which excludes the except option.

EventHandler<TMeta, E>

Event handler function type for socket.io-like event handling. Used with room.on() and room.off() methods.

Type Parameters:

  • TMeta extends ConnectionMeta - Custom metadata type
  • E - Actor environment type (default: unknown)
type EventHandler<TMeta extends ConnectionMeta = ConnectionMeta, E = unknown> = (
  ctx: MessageContext<TMeta, E>,
  data: any
) => void | Promise<void>;

Example:

const room = defineRoom<CustomMeta>({ /* ... */ });

// Handler receives properly typed context
room.on("chat.message", (ctx, data) => {
  // ctx is typed as MessageContext<CustomMeta, E>
  // ctx.meta has type CustomMeta with all custom properties
  console.log(ctx.meta.username); // Type-safe access
});

RoomEventEmitter<TMeta, E>

Event emitter interface for room-level event handling. Provides socket.io-like event registration and removal.

Type Parameters:

  • TMeta extends ConnectionMeta - Custom metadata type
  • E - Actor environment type (default: unknown)
interface RoomEventEmitter<TMeta extends ConnectionMeta = ConnectionMeta, E = unknown> {
  on(event: string, handler: EventHandler<TMeta, E>): void;
  off(event: string, handler?: EventHandler<TMeta, E>): void;
  emit(event: string, ctx: MessageContext<TMeta, E>, data: any): Promise<void>;
}

Example:

import { createRoomEventEmitter } from "verani";

const customEmitter = createRoomEventEmitter<CustomMeta>();

const room = defineRoom({
  eventEmitter: customEmitter,
  // ... other config
});

RoomDefinitionWithHandlers<TMeta, E>

Extended room definition returned by defineRoom() with socket.io-like convenience methods.

Type Parameters:

  • TMeta extends ConnectionMeta - Custom metadata type
  • E - Actor environment type (default: unknown)

Extends RoomDefinition<TMeta, E> and adds:

  • on(event: string, handler: EventHandler<TMeta, E>): void
  • off(event: string, handler?: EventHandler<TMeta, E>): void
  • eventEmitter: RoomEventEmitter<TMeta, E>

See Server API for complete documentation.

RpcBroadcastOptions

RPC-safe version of BroadcastOptions for use over RPC calls. Excludes the except field since WebSocket cannot be serialized.

interface RpcBroadcastOptions {
  /** Only send to specific user IDs */
  userIds?: string[];
  /** Only send to specific client IDs */
  clientIds?: string[];
}

Comparison:

// Inside lifecycle hook - can use except
ctx.actor.broadcast("default", data, {
  except: ctx.ws,           // Available
  userIds: ["alice", "bob"]
});

// Via RPC - use RpcBroadcastOptions
await stub.broadcast("default", data, {
  except: ctx.ws,           // Not available - WebSocket can't be serialized
  userIds: ["alice", "bob"] // Available
});

Client Types

ConnectionState

Connection state values.

type ConnectionState = "connecting" | "connected" | "disconnected" | "reconnecting" | "error";

VeraniClientOptions

See Client API for details.

ReconnectionConfig

See Client API for details.

Typed API Types

For type-safe contracts with full TypeScript inference, see the Typed API.

Contract Types (from verani/typed/shared):

import type {
  // Contract definition
  Contract,
  ContractDefinition,
  EventMap,
  PayloadMarker,
  
  // Type inference
  ServerEventNames,
  ClientEventNames,
  ServerPayload,
  ClientPayload,
  InferChannels,
  
  // Validation
  Validator,
  ValidatedContract,
} from "verani/typed/shared";

Server Types (from verani/typed):

import type {
  TypedRoom,
  TypedRoomConfig,
  TypedRoomContext,
  TypedMessageContext,
  TypedEventHandler,
} from "verani/typed";

Client Types (from verani/typed/client):

import type {
  TypedClient,
} from "verani/typed/client";

Related Documentation