@fluxstack/live-client 0.3.1 → 0.4.0

package/dist/index.d.cts

@@ -0,0 +1,478 @@
+import { WebSocketMessage, WebSocketResponse, FileUploadCompleteResponse, BinaryChunkHeader } from '@fluxstack/live';
+
+/** Auth credentials to send during WebSocket connection */
+interface LiveAuthOptions {
+    /** JWT or opaque token */
+    token?: string;
+    /** Provider name (if multiple auth providers configured) */
+    provider?: string;
+    /** Additional credentials (publicKey, signature, etc.) */
+    [key: string]: unknown;
+}
+interface LiveConnectionOptions {
+    /** WebSocket URL. Auto-detected from window.location if omitted. */
+    url?: string;
+    /** Auth credentials to send on connection */
+    auth?: LiveAuthOptions;
+    /** Auto-connect on creation. Default: true */
+    autoConnect?: boolean;
+    /** Reconnect interval in ms. Default: 1000 */
+    reconnectInterval?: number;
+    /** Max reconnect attempts. Default: 5 */
+    maxReconnectAttempts?: number;
+    /** Heartbeat interval in ms. Default: 30000 */
+    heartbeatInterval?: number;
+    /** Enable debug logging. Default: false */
+    debug?: boolean;
+}
+interface LiveConnectionState {
+    connected: boolean;
+    connecting: boolean;
+    error: string | null;
+    connectionId: string | null;
+    authenticated: boolean;
+}
+type StateChangeCallback$1 = (state: LiveConnectionState) => void;
+type ComponentCallback = (message: WebSocketResponse) => void;
+/**
+ * Framework-agnostic WebSocket connection manager.
+ * Handles reconnection, heartbeat, request-response pattern, and message routing.
+ */
+declare class LiveConnection {
+    private ws;
+    private options;
+    private reconnectAttempts;
+    private reconnectTimeout;
+    private heartbeatInterval;
+    private componentCallbacks;
+    private binaryCallbacks;
+    private roomBinaryHandlers;
+    private pendingRequests;
+    private stateListeners;
+    private _state;
+    constructor(options?: LiveConnectionOptions);
+    get state(): LiveConnectionState;
+    /** Subscribe to connection state changes */
+    onStateChange(callback: StateChangeCallback$1): () => void;
+    private setState;
+    private getWebSocketUrl;
+    private log;
+    /** Generate unique request ID */
+    generateRequestId(): string;
+    /** Connect to WebSocket server */
+    connect(): void;
+    /** Disconnect from WebSocket server */
+    disconnect(): void;
+    /** Manual reconnect */
+    reconnect(): void;
+    private attemptReconnect;
+    private startHeartbeat;
+    private stopHeartbeat;
+    private handleMessage;
+    /** Send message without waiting for response */
+    sendMessage(message: WebSocketMessage): Promise<void>;
+    /** Send message and wait for response */
+    sendMessageAndWait(message: WebSocketMessage, timeout?: number): Promise<WebSocketResponse>;
+    /** Send binary data and wait for response (for file uploads) */
+    sendBinaryAndWait(data: ArrayBuffer, requestId: string, timeout?: number): Promise<WebSocketResponse>;
+    /** Parse and route binary frames (state delta, room events, room state) */
+    private handleBinaryMessage;
+    /** Register a handler for binary room frames (0x02 / 0x03). Returns unsubscribe. */
+    registerRoomBinaryHandler(callback: (frame: Uint8Array) => void): () => void;
+    /** Register a binary message handler for a component */
+    registerBinaryHandler(componentId: string, callback: (payload: Uint8Array) => void): () => void;
+    /** Register a component message callback */
+    registerComponent(componentId: string, callback: ComponentCallback): () => void;
+    /** Unregister a component */
+    unregisterComponent(componentId: string): void;
+    /** Authenticate (or re-authenticate) the WebSocket connection */
+    authenticate(credentials: LiveAuthOptions): Promise<boolean>;
+    /** Get the raw WebSocket instance */
+    getWebSocket(): WebSocket | null;
+    /** Destroy the connection and clean up all resources */
+    destroy(): void;
+}
+
+interface LiveComponentOptions<TState = Record<string, any>> {
+    /** Initial state to merge with server defaults */
+    initialState?: Partial<TState>;
+    /** Room to join on mount */
+    room?: string;
+    /** User ID for component isolation */
+    userId?: string;
+    /** Auto-mount when connection is ready. Default: true */
+    autoMount?: boolean;
+    /** Enable debug logging. Default: false */
+    debug?: boolean;
+}
+type StateChangeCallback<TState> = (state: TState, delta: Partial<TState> | null) => void;
+type ErrorCallback = (error: string) => void;
+/**
+ * High-level handle for a live component instance.
+ * Manages mount lifecycle, state sync, and action calling.
+ * Framework-agnostic — works with vanilla JS, Vue, Svelte, etc.
+ */
+declare class LiveComponentHandle<TState extends Record<string, any> = Record<string, any>> {
+    private connection;
+    private componentName;
+    private options;
+    private _componentId;
+    private _state;
+    private _mounted;
+    private _mounting;
+    private _error;
+    private stateListeners;
+    private errorListeners;
+    private unregisterComponent;
+    private unsubConnection;
+    constructor(connection: LiveConnection, componentName: string, options?: LiveComponentOptions<TState>);
+    /** Current component state */
+    get state(): Readonly<TState>;
+    /** Server-assigned component ID (null before mount) */
+    get componentId(): string | null;
+    /** Whether the component has been mounted */
+    get mounted(): boolean;
+    /** Whether the component is currently mounting */
+    get mounting(): boolean;
+    /** Last error message */
+    get error(): string | null;
+    /** Mount the component on the server */
+    mount(): Promise<void>;
+    /** Unmount the component from the server */
+    unmount(): Promise<void>;
+    /** Destroy the handle and clean up all resources */
+    destroy(): void;
+    /**
+     * Call an action on the server component.
+     * Returns the action's return value.
+     */
+    call<R = any>(action: string, payload?: Record<string, any>): Promise<R>;
+    /**
+     * Fire an action without waiting for a response (fire-and-forget).
+     * Useful for high-frequency operations like game input where the
+     * server doesn't need to send back a result.
+     */
+    fire(action: string, payload?: Record<string, any>): void;
+    /**
+     * Subscribe to state changes.
+     * Callback receives the full new state and the delta (or null for full updates).
+     * Returns an unsubscribe function.
+     */
+    onStateChange(callback: StateChangeCallback<TState>): () => void;
+    /**
+     * Register a binary decoder for this component.
+     * When the server sends a BINARY_STATE_DELTA frame targeting this component,
+     * the decoder converts the raw payload into a delta object which is merged into state.
+     * Returns an unsubscribe function.
+     */
+    setBinaryDecoder(decoder: (buffer: Uint8Array) => Record<string, any>): () => void;
+    /**
+     * Subscribe to errors.
+     * Returns an unsubscribe function.
+     */
+    onError(callback: ErrorCallback): () => void;
+    private handleServerMessage;
+    private notifyStateChange;
+    private notifyError;
+    private cleanup;
+    private log;
+}
+
+type EventHandler<T = any> = (data: T) => void;
+type Unsubscribe = () => void;
+/** Reserved keys on RoomHandle/RoomProxy — cannot be state fields */
+type RoomReservedKeys = 'id' | 'joined' | 'state' | 'join' | 'leave' | 'emit' | 'on' | 'onSystem' | 'setState';
+/** State fields accessible directly on handle/proxy (excludes reserved method names) */
+type RoomStateFields<TState> = TState extends Record<string, any> ? {
+    readonly [K in Exclude<keyof TState, RoomReservedKeys>]: TState[K];
+} : unknown;
+/** Message from client to server */
+interface RoomClientMessage {
+    type: 'ROOM_JOIN' | 'ROOM_LEAVE' | 'ROOM_EMIT' | 'ROOM_STATE_GET' | 'ROOM_STATE_SET';
+    componentId: string;
+    roomId: string;
+    event?: string;
+    data?: any;
+    timestamp: number;
+}
+/** Message from server to client */
+interface RoomServerMessage {
+    type: 'ROOM_EVENT' | 'ROOM_STATE' | 'ROOM_SYSTEM' | 'ROOM_JOINED' | 'ROOM_LEFT';
+    componentId: string;
+    roomId: string;
+    event: string;
+    data: any;
+    timestamp: number;
+}
+/** Interface of an individual room handle */
+type RoomHandle<TState = any, TEvents extends Record<string, any> = Record<string, any>> = {
+    readonly id: string;
+    readonly joined: boolean;
+    readonly state: TState;
+    join: (initialState?: TState) => Promise<void>;
+    leave: () => Promise<void>;
+    emit: <K extends keyof TEvents>(event: K, data: TEvents[K]) => void;
+    on: <K extends keyof TEvents>(event: K, handler: EventHandler<TEvents[K]>) => Unsubscribe;
+    onSystem: (event: string, handler: EventHandler) => Unsubscribe;
+    setState: (updates: Partial<TState>) => void;
+} & RoomStateFields<TState>;
+/** Infer TEvents from a LiveRoom class (via $events brand) or use T directly as events map */
+type InferRoomEvents<T> = T extends {
+    $events: infer E extends Record<string, any>;
+} ? E : T extends Record<string, any> ? T : Record<string, any>;
+/** Proxy interface for $room - callable as function or object */
+type RoomProxy<TState = any, TEvents extends Record<string, any> = Record<string, any>> = {
+    /** Get a typed room handle. Pass the Room class or events interface as generic:
+     * `$room<CounterRoom>('counter:global').on('counter:updated', data => ...)` */
+    <T = TEvents>(roomId: string): RoomHandle<any, InferRoomEvents<T>>;
+    readonly id: string | null;
+    readonly joined: boolean;
+    readonly state: TState;
+    join: (initialState?: TState) => Promise<void>;
+    leave: () => Promise<void>;
+    emit: <K extends keyof TEvents>(event: K, data: TEvents[K]) => void;
+    on: <K extends keyof TEvents>(event: K, handler: EventHandler<TEvents[K]>) => Unsubscribe;
+    onSystem: (event: string, handler: EventHandler) => Unsubscribe;
+    setState: (updates: Partial<TState>) => void;
+} & RoomStateFields<TState>;
+interface RoomManagerOptions {
+    componentId: string | null;
+    defaultRoom?: string;
+    sendMessage: (msg: any) => void;
+    sendMessageAndWait: (msg: any, timeout?: number) => Promise<any>;
+    onMessage: (handler: (msg: RoomServerMessage) => void) => Unsubscribe;
+    /** Optional: register for binary room frames (0x02 ROOM_EVENT, 0x03 ROOM_STATE) */
+    onBinaryMessage?: (handler: (frame: Uint8Array) => void) => Unsubscribe;
+}
+/** Client-side room manager. Framework-agnostic. */
+declare class RoomManager<TState = any, TEvents extends Record<string, any> = Record<string, any>> {
+    private componentId;
+    private defaultRoom;
+    private rooms;
+    private handles;
+    private sendMessage;
+    private sendMessageAndWait;
+    private globalUnsubscribe;
+    private binaryUnsubscribe;
+    private onBinaryMessage;
+    private onMessageFactory;
+    constructor(options: RoomManagerOptions);
+    /** Re-subscribe message and binary handlers (needed after destroy/remount in React Strict Mode) */
+    resubscribe(): void;
+    private handleServerMessage;
+    /** Handle binary room frames (0x02 ROOM_EVENT, 0x03 ROOM_STATE) */
+    private handleBinaryFrame;
+    private getOrCreateRoom;
+    /** Create handle for a specific room (cached) */
+    createHandle(roomId: string): RoomHandle<TState, TEvents>;
+    /** Create the $room proxy */
+    createProxy(): RoomProxy<TState, TEvents>;
+    /** List of rooms currently joined */
+    getJoinedRooms(): string[];
+    /** Update componentId (when component mounts) */
+    setComponentId(id: string | null): void;
+    /** Cleanup — unsubscribes handlers but keeps factory refs for resubscribe() */
+    destroy(): void;
+}
+
+interface AdaptiveChunkConfig {
+    minChunkSize: number;
+    maxChunkSize: number;
+    initialChunkSize: number;
+    targetLatency: number;
+    adjustmentFactor: number;
+    measurementWindow: number;
+}
+interface ChunkMetrics {
+    chunkIndex: number;
+    chunkSize: number;
+    startTime: number;
+    endTime: number;
+    latency: number;
+    throughput: number;
+    success: boolean;
+}
+declare class AdaptiveChunkSizer {
+    private config;
+    private currentChunkSize;
+    private metrics;
+    private consecutiveErrors;
+    private consecutiveSuccesses;
+    constructor(config?: Partial<AdaptiveChunkConfig>);
+    getChunkSize(): number;
+    recordChunkStart(_chunkIndex: number): number;
+    recordChunkComplete(chunkIndex: number, chunkSize: number, startTime: number, success: boolean): void;
+    private adjustUp;
+    private adjustDown;
+    getAverageThroughput(): number;
+    getStats(): {
+        currentChunkSize: number;
+        averageThroughput: number;
+        consecutiveSuccesses: number;
+        consecutiveErrors: number;
+        totalMeasurements: number;
+    };
+    reset(): void;
+}
+/**
+ * Creates a binary message with header + data
+ * Format: [4 bytes header length LE][JSON header][binary data]
+ */
+declare function createBinaryChunkMessage(header: BinaryChunkHeader, chunkData: Uint8Array): ArrayBuffer;
+interface ChunkedUploadOptions {
+    chunkSize?: number;
+    maxFileSize?: number;
+    allowedTypes?: string[];
+    sendMessageAndWait: (message: any, timeout?: number) => Promise<any>;
+    sendBinaryAndWait?: (data: ArrayBuffer, requestId: string, timeout?: number) => Promise<any>;
+    onProgress?: (progress: number, bytesUploaded: number, totalBytes: number) => void;
+    onComplete?: (response: FileUploadCompleteResponse) => void;
+    onError?: (error: string) => void;
+    adaptiveChunking?: boolean;
+    adaptiveConfig?: Partial<AdaptiveChunkConfig>;
+    useBinaryProtocol?: boolean;
+}
+interface ChunkedUploadState {
+    uploading: boolean;
+    progress: number;
+    error: string | null;
+    uploadId: string | null;
+    bytesUploaded: number;
+    totalBytes: number;
+}
+/**
+ * Framework-agnostic chunked file uploader.
+ * Manages the upload lifecycle without any UI framework dependency.
+ */
+declare class ChunkedUploader {
+    private componentId;
+    private options;
+    private abortController;
+    private adaptiveSizer;
+    private _state;
+    private stateListeners;
+    constructor(componentId: string, options: ChunkedUploadOptions);
+    get state(): ChunkedUploadState;
+    onStateChange(callback: (state: ChunkedUploadState) => void): () => void;
+    private setState;
+    uploadFile(file: File): Promise<void>;
+    cancelUpload(): void;
+    reset(): void;
+}
+
+interface PersistedState {
+    componentName: string;
+    signedState: any;
+    room?: string;
+    userId?: string;
+    lastUpdate: number;
+}
+declare function persistState(enabled: boolean, name: string, signedState: any, room?: string, userId?: string): void;
+declare function getPersistedState(enabled: boolean, name: string): PersistedState | null;
+declare function clearPersistedState(enabled: boolean, name: string): void;
+
+interface StateValidation {
+    checksum: string;
+    version: number;
+    timestamp: number;
+    source: 'client' | 'server' | 'mount';
+}
+interface StateConflict {
+    property: string;
+    clientValue: any;
+    serverValue: any;
+    timestamp: number;
+    resolved: boolean;
+}
+interface HybridState<T> {
+    data: T;
+    validation: StateValidation;
+    status: 'synced' | 'pending' | 'conflict';
+}
+declare class StateValidator {
+    static generateChecksum(state: any): string;
+    static createValidation(state: any, source?: 'client' | 'server' | 'mount'): StateValidation;
+    static detectConflicts<T>(clientState: T, serverState: T, excludeFields?: string[]): StateConflict[];
+    static mergeStates<T>(clientState: T, serverState: T, conflicts: StateConflict[], strategy?: 'client' | 'server' | 'smart'): T;
+    static validateState<T>(hybridState: HybridState<T>): boolean;
+    static updateValidation<T>(hybridState: HybridState<T>, source?: 'client' | 'server' | 'mount'): HybridState<T>;
+}
+
+/** Status listeners for the shared connection */
+type ConnectionStatusCallback = (connected: boolean) => void;
+interface UseLiveOptions {
+    /** WebSocket URL. Auto-detected from window.location if omitted. */
+    url?: string;
+    /** Room to join on mount */
+    room?: string;
+    /** User ID for component isolation */
+    userId?: string;
+    /** Auto-mount when connected. Default: true */
+    autoMount?: boolean;
+    /** Enable debug logging. Default: false */
+    debug?: boolean;
+}
+interface UseLiveHandle<TState extends Record<string, any> = Record<string, any>> {
+    /** Call a server action */
+    call: <R = any>(action: string, payload?: Record<string, any>) => Promise<R>;
+    /** Subscribe to state changes. Returns unsubscribe function. */
+    on: (callback: (state: TState, delta: Partial<TState> | null) => void) => () => void;
+    /** Subscribe to errors. Returns unsubscribe function. */
+    onError: (callback: (error: string) => void) => () => void;
+    /** Current state (read-only snapshot) */
+    readonly state: Readonly<TState>;
+    /** Whether the component is mounted on the server */
+    readonly mounted: boolean;
+    /** Server-assigned component ID */
+    readonly componentId: string | null;
+    /** Last error message */
+    readonly error: string | null;
+    /** Destroy the component and clean up */
+    destroy: () => void;
+    /** Access the underlying LiveComponentHandle */
+    readonly handle: LiveComponentHandle<TState>;
+}
+/**
+ * Create a live component with minimal boilerplate.
+ * Manages the WebSocket connection automatically (singleton).
+ *
+ * @example Browser IIFE
+ * ```html
+ * <script src="/live-client.js"></script>
+ * <script>
+ *   const counter = FluxstackLive.useLive('Counter', { count: 0 })
+ *   counter.on(state => {
+ *     document.getElementById('count').textContent = state.count
+ *   })
+ *   document.querySelector('.inc').onclick = () => counter.call('increment')
+ * </script>
+ * ```
+ *
+ * @example ES modules
+ * ```ts
+ * import { useLive } from '@fluxstack/live-client'
+ * const counter = useLive('Counter', { count: 0 }, { url: 'ws://localhost:3000/api/live/ws' })
+ * counter.on(state => console.log(state.count))
+ * counter.call('increment')
+ * ```
+ */
+declare function useLive<TState extends Record<string, any> = Record<string, any>>(componentName: string, initialState: TState, options?: UseLiveOptions): UseLiveHandle<TState>;
+/**
+ * Subscribe to the shared connection status (connected/disconnected).
+ * Useful for showing a global status indicator.
+ *
+ * @example
+ * ```js
+ * FluxstackLive.onConnectionChange(connected => {
+ *   statusEl.textContent = connected ? 'Connected' : 'Disconnected'
+ * })
+ * ```
+ */
+declare function onConnectionChange(callback: ConnectionStatusCallback): () => void;
+/**
+ * Get or create the shared connection instance.
+ * Useful when you need direct access to the connection.
+ */
+declare function getConnection(url?: string): LiveConnection;
+
+export { type AdaptiveChunkConfig, AdaptiveChunkSizer, type ChunkMetrics, type ChunkedUploadOptions, type ChunkedUploadState, ChunkedUploader, type EventHandler, type HybridState, type LiveAuthOptions, LiveComponentHandle, type LiveComponentOptions, LiveConnection, type LiveConnectionOptions, type LiveConnectionState, type PersistedState, type RoomClientMessage, type RoomHandle, RoomManager, type RoomManagerOptions, type RoomProxy, type RoomServerMessage, type StateConflict, type StateValidation, StateValidator, type Unsubscribe, type UseLiveHandle, type UseLiveOptions, clearPersistedState, createBinaryChunkMessage, getConnection, getPersistedState, onConnectionChange, persistState, useLive };

package/package.json

@@ -1,15 +1,18 @@
 {
   "name": "@fluxstack/live-client",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "Browser WebSocket client for @fluxstack/live — connection, state sync, rooms, and file upload (framework-agnostic)",
   "type": "module",
-  "main": "./dist/index.js",
+  "main": "./dist/index.cjs",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
+  "sideEffects": false,
   "exports": {
     ".": {
+      "types": "./dist/index.d.ts",
+      "bun": "./src/index.ts",
       "import": "./dist/index.js",
-      "types": "./dist/index.d.ts"
+      "require": "./dist/index.cjs"
     },
     "./browser": "./dist/live-client.browser.global.js"
   },
@@ -23,7 +26,7 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@fluxstack/live": "^0.3.0"
+    "@fluxstack/live": "^0.4.0"
   },
   "devDependencies": {
     "tsup": "^8.4.0",
@@ -37,5 +40,9 @@
     "url": "https://github.com/FluxStackCore/fluxstack-live",
     "directory": "packages/client"
   },
-  "license": "MIT"
+  "license": "MIT",
+  "keywords": ["websocket", "client", "realtime", "state-sync", "live-components", "fluxstack"],
+  "engines": {
+    "node": ">=18.0.0"
+  }
 }