Client Management

/**
 * Client connection to a Perspective server instance
 */
class Client {
  constructor(send_request: (buffer: Uint8Array) => Promise<void>, close?: () => void);
  
  /** Create table from data or schema */
  table(data: TableInitData, options?: TableInitOptions): Promise<Table>;
  
  /** Open existing hosted table by name */
  open_table(name: string): Promise<Table>;
  
  /** Get names of all hosted tables */
  get_hosted_table_names(): Promise<string[]>;
  
  /** Register callback for hosted table changes */
  on_hosted_tables_update(callback: () => void): Promise<number>;
  
  /** Remove hosted table update callback */
  remove_hosted_tables_update(id: number): Promise<void>;
  
  /** Register error callback with reconnect support */
  on_error(callback: (error: Error, reconnect: () => Promise<void>) => void): Promise<number>;
  
  /** Get server system information */
  system_info(): Promise<SystemInfo>;
  
  /** Handle incoming protocol response */
  handle_response(data: Uint8Array): Promise<void>;
  
  /** Handle connection error with optional reconnect */
  handle_error(error: string, reconnect?: () => Promise<void>): Promise<void>;
  
  /** Create proxy session for custom protocols */
  new_proxy_session(on_response: (buffer: Uint8Array) => void): ProxySession;
  
  /** Terminate client and cleanup resources */
  terminate(): void;
}

/**
 * Create Web Worker client for browser environments
 * @param worker - Optional Web Worker instance, creates default if not provided
 * @returns Promise resolving to connected Client
 */
function worker(worker?: Promise<SharedWorker | ServiceWorker | Worker>): Promise<Client>;

import perspective from "@finos/perspective";

// Create default Web Worker client
const client = await perspective.worker();

// Use custom Web Worker
const customWorker = new Worker("./my-perspective-worker.js");
const client = await perspective.worker(Promise.resolve(customWorker));

// Use SharedWorker for cross-tab sharing
const sharedWorker = new SharedWorker("./perspective-shared-worker.js");
const client = await perspective.worker(Promise.resolve(sharedWorker));

/**
 * Create WebSocket client connection
 * @param url - WebSocket server URL
 * @returns Promise resolving to connected Client
 */
function websocket(url: string): Promise<Client>;

import perspective from "@finos/perspective";

// Connect to remote Perspective server
const client = await perspective.websocket("ws://localhost:8080/ws");

// Connect with secure WebSocket
const secureClient = await perspective.websocket("wss://api.example.com/perspective");

// Handle connection errors
try {
  const client = await perspective.websocket("ws://unreachable-server:8080");
} catch (error) {
  console.error("Failed to connect:", error);
}

/**
 * Initialize client-side WebAssembly module
 * @param wasm - WebAssembly module or ArrayBuffer
 * @param disable_stage_0 - Skip decompression stage
 */
function init_client(wasm: PerspectiveWasm, disable_stage_0?: boolean): void;

/**
 * Initialize server-side WebAssembly module  
 * @param wasm - WebAssembly module or ArrayBuffer
 * @param disable_stage_0 - Skip decompression stage
 */
function init_server(wasm: PerspectiveWasm, disable_stage_0?: boolean): void;

type PerspectiveWasm = ArrayBuffer | Response | WebAssembly.Module | Promise<ArrayBuffer | Response | Object>;

import perspective from "@finos/perspective";

// Initialize with WebAssembly file
const wasmResponse = fetch("/perspective-client.wasm");
perspective.init_client(wasmResponse);

// Initialize with ArrayBuffer
const wasmBuffer = await fetch("/perspective-server.wasm").then(r => r.arrayBuffer());
perspective.init_server(wasmBuffer, false);

/**
 * Proxy session for custom protocol handling
 */
class ProxySession {
  constructor(client: Client, on_response: (buffer: Uint8Array) => void);
  
  /** Handle incoming request */
  handle_request(data: Uint8Array): Promise<void>;
  
  /** Close session and cleanup */
  close(): Promise<void>;
}

// Create custom transport proxy
const session = client.new_proxy_session((response) => {
  // Custom response handling
  customTransport.send(response);
});

// Handle incoming requests
customTransport.onMessage = async (request) => {
  await session.handle_request(request);
};

interface SystemInfo {
  /** Total server memory usage in bytes */
  server_used?: number;
  /** Total server heap size in bytes */
  server_heap?: number;
  /** Client memory usage in bytes */
  client_used?: number;
  /** Client heap size in bytes */  
  client_heap?: number;
  /** Timestamp of measurement */
  timestamp?: number;
}

// Node.js - synchronous client access
import perspective from "@finos/perspective";

// Direct table creation (no await needed for client)
const table = perspective.table(data);

// Browser - asynchronous client creation
import perspective from "@finos/perspective";

const client = await perspective.worker();
const table = await client.table(data);