@hypen-space/core 0.4.2 → 0.4.5

package/dist/remote/server.d.ts

@@ -0,0 +1,173 @@
+/**
+ * RemoteServer - Stream Hypen apps over WebSocket with Session Management
+ *
+ * Usage with inline UI:
+ * ```typescript
+ * import { RemoteServer, app } from "@hypen-space/core";
+ *
+ * const counter = app
+ *   .defineState({ count: 0 })
+ *   .onAction("increment", ({ state }) => state.count++)
+ *   .build();
+ *
+ * new RemoteServer()
+ *   .module("Counter", counter)
+ *   .ui(`Column { Text("Count: \${state.count}") }`)
+ *   .listen(3000);
+ * ```
+ *
+ * Usage with directory-based discovery (auto-resolves imports):
+ * ```typescript
+ * import { RemoteServer } from "@hypen-space/core";
+ * import chatModule from "./apps/chat/Chat/component.js";
+ *
+ * await new RemoteServer()
+ *   .source("./apps/chat")
+ *   .module("Chat", chatModule)
+ *   .listen(3001);
+ * ```
+ */
+import type { HypenModule } from "../app.js";
+import type { RemoteMessage, RemoteClient, RemoteServerConfig, SessionConfig } from "./types.js";
+/**
+ * Builder pattern for hosting Hypen apps over WebSocket
+ */
+export declare class RemoteServer {
+    private _module;
+    private _moduleName;
+    private _ui;
+    private _sourceDir;
+    private _discoveredComponents;
+    private _config;
+    private _sessionConfig;
+    private _onConnectionCallbacks;
+    private _onDisconnectionCallbacks;
+    private clients;
+    private nextClientId;
+    private server;
+    private sessionManager;
+    /**
+     * Set the module for this app
+     */
+    module(name: string, module: HypenModule<any>): this;
+    /**
+     * Set the UI DSL string
+     */
+    ui(dsl: string): this;
+    /**
+     * Set a source directory for automatic component discovery.
+     *
+     * All .hypen and .ts components in the directory (and subdirectories) are
+     * discovered automatically. The entry component's template is used as the
+     * UI, so calling .ui() is optional when .source() is set.
+     *
+     * @example
+     * ```typescript
+     * new RemoteServer()
+     *   .source("./apps/chat")
+     *   .module("Chat", chatModule)
+     *   .listen(3001);
+     * ```
+     */
+    source(dir: string): this;
+    /**
+     * Set server configuration
+     */
+    config(config: RemoteServerConfig): this;
+    /**
+     * Configure session management
+     */
+    session(config: SessionConfig): this;
+    /**
+     * Register connection callback
+     */
+    onConnection(callback: (client: RemoteClient) => void): this;
+    /**
+     * Register disconnection callback
+     */
+    onDisconnection(callback: (client: RemoteClient) => void): this;
+    /**
+     * Start the WebSocket server
+     */
+    listen(port?: number): Promise<this>;
+    /**
+     * Stop the server
+     */
+    stop(): void;
+    /**
+     * Get the server URL
+     */
+    get url(): string | null;
+    /**
+     * Discover components from the source directory.
+     * Populates _discoveredComponents and sets _ui from the entry component
+     * if not already set via .ui().
+     */
+    private discoverFromSource;
+    /**
+     * Set up a component resolver on a client engine so that imports
+     * and component references in templates are resolved from discovered
+     * components.
+     */
+    private setupComponentResolver;
+    /**
+     * Handle new WebSocket connection
+     * Waits for hello message before fully initializing
+     */
+    private handleOpen;
+    /**
+     * Initialize session for a client (new or resumed)
+     */
+    private initializeSession;
+    /**
+     * Set up the render callback for streaming patches
+     */
+    private setupRenderCallback;
+    /**
+     * Handle concurrent connection based on policy
+     * Returns true if connection is allowed, false if rejected
+     */
+    private handleConcurrentConnection;
+    /**
+     * Trigger onReconnect hook
+     */
+    private triggerReconnect;
+    /**
+     * Handle incoming WebSocket message
+     */
+    private handleMessage;
+    /**
+     * Handle WebSocket close - suspend session instead of destroying
+     */
+    private handleClose;
+    /**
+     * Get current client count
+     */
+    getClientCount(): number;
+    /**
+     * Get session stats
+     */
+    getSessionStats(): {
+        activeSessions: number;
+        pendingSessions: number;
+        totalConnections: number;
+    };
+    /**
+     * Broadcast a message to all connected clients
+     */
+    broadcast(message: RemoteMessage): void;
+}
+/**
+ * Convenience function to create and start a RemoteServer
+ */
+export declare function serve(options: {
+    module: HypenModule<any>;
+    moduleName?: string;
+    ui?: string;
+    source?: string;
+    port?: number;
+    hostname?: string;
+    session?: SessionConfig;
+    onConnection?: (client: RemoteClient) => void;
+    onDisconnection?: (client: RemoteClient) => void;
+}): Promise<RemoteServer>;