theater-client/src/types/client.ts

TypeScript client library for Theater actor system TCP protocol

/**
 * Client-specific types for the Theater client library
 */

import type { TheaterId, ChannelId, ChannelParticipant, ManagementError, ChainEvent, ActorError, ActorResult } from './protocol.js';

// Client configuration
export interface TheaterClientConfig {
  host?: string;
  port?: number;
  timeout?: number; // Timeout in milliseconds, 0 = no timeout, undefined = 30s default
  retryAttempts?: number;
  retryDelay?: number;
}

// Channel communication types
export interface ChannelMessage {
  senderId: ChannelParticipant;
  data: Uint8Array;
  timestamp: Date;
}

export interface ChannelStream {
  readonly channelId: ChannelId;
  readonly isOpen: boolean;
  
  // Event handling
  onMessage(handler: (message: ChannelMessage) => void): () => void;
  onClose(handler: () => void): () => void;
  onError(handler: (error: Error) => void): () => void;
  
  // Operations
  sendMessage(data: Uint8Array): Promise<void>;
  close(): void;
}

// Actor event subscription
export interface ActorEventStream {
  readonly actorId: TheaterId;
  readonly subscriptionId: string;
  readonly isActive: boolean;
  
  // Event handling
  onEvent(handler: (event: any) => void): () => void;
  onError(handler: (error: Error) => void): () => void;
  onClose(handler: () => void): () => void;
  
  // Operations
  close(): void;
}

// Error types
export class TheaterError extends Error {
  constructor(
    message: string,
    public readonly code?: string,
    public readonly details?: ManagementError
  ) {
    super(message);
    this.name = 'TheaterError';
  }
}

export class TheaterConnectionError extends TheaterError {
  constructor(message: string, public override readonly cause?: Error) {
    super(message, 'CONNECTION_ERROR');
    this.name = 'TheaterConnectionError';
  }
}

export class TheaterTimeoutError extends TheaterError {
  constructor(operation: string, timeout: number) {
    super(`Operation '${operation}' timed out after ${timeout}ms`, 'TIMEOUT');
    this.name = 'TheaterTimeoutError';
  }
}

export class TheaterProtocolError extends TheaterError {
  constructor(message: string, public override readonly details?: any) {
    super(message, 'PROTOCOL_ERROR', details);
    this.name = 'TheaterProtocolError';
  }
}

// Utility types
export interface ActorCallbacks {
  onEvent?: (event: ChainEvent) => void;
  onError?: (error: ActorError) => void;
  onActorResult?: (result: ActorResult) => void;
}

export interface StartActorParams {
  manifest: string;
  initialState?: Uint8Array;
  
  // Callbacks determine what features are enabled
  onEvent?: (event: ChainEvent) => void;           // Enables subscribe: true
  onError?: (error: ActorError) => void;           // Enables subscribe: true  
  onActorResult?: (result: ActorResult) => void;   // Enables parent: true
}

export interface ActorInfo {
  id: TheaterId;
  manifest: string;
}