@forthix/forthic 0.7.0 → 0.7.2

package/dist/esm/websocket/client.d.ts

@@ -0,0 +1,103 @@
+/**
+ * WebSocket Client for Forthic
+ * Browser-compatible client that mirrors GrpcClient API
+ * Connects to Rails ActionCable server and executes remote words
+ */
+import { StackValue } from './serializer.js';
+export interface ModuleSummary {
+    name: string;
+    description: string;
+    word_count: number;
+}
+export interface WordInfo {
+    name: string;
+    stack_effect: string;
+    description: string;
+}
+export interface ModuleInfo {
+    module_name: string;
+    words: WordInfo[];
+}
+export interface ProgressUpdate {
+    step: number;
+    total_steps: number;
+    current_word: string;
+    message?: string;
+    partial_stack?: StackValue[];
+}
+export interface WebSocketClientConfig {
+    url: string;
+    timezone?: string;
+    reconnect?: boolean;
+    reconnectDelay?: number;
+    channel?: string;
+}
+/**
+ * WebSocket client for executing words in remote Forthic runtimes
+ * Mirrors the GrpcClient API for compatibility
+ */
+export declare class WebSocketClient {
+    private ws?;
+    private config;
+    private pendingRequests;
+    private messageId;
+    private connected;
+    private connectionPromise?;
+    constructor(config: WebSocketClientConfig);
+    /**
+     * Connect to the WebSocket server
+     */
+    private connect;
+    /**
+     * Handle incoming WebSocket messages
+     */
+    private handleMessage;
+    /**
+     * Generate next message ID
+     */
+    private nextMessageId;
+    /**
+     * Send a request and wait for response
+     */
+    private sendRequest;
+    /**
+     * Send a streaming request with progress callbacks
+     */
+    private sendStreamingRequest;
+    /**
+     * Ensure WebSocket is connected
+     */
+    private ensureConnected;
+    /**
+     * Execute a word in the remote runtime
+     * Mirrors GrpcClient.executeWord
+     */
+    executeWord(word: string, stack: any[]): Promise<any[]>;
+    /**
+     * Execute a sequence of words (batched execution)
+     * Mirrors GrpcClient.executeSequence
+     */
+    executeSequence(words: string[], stack: any[]): Promise<any[]>;
+    /**
+     * List available runtime-specific modules
+     * Mirrors GrpcClient.listModules
+     */
+    listModules(): Promise<ModuleSummary[]>;
+    /**
+     * Get detailed information about a specific module
+     * Mirrors GrpcClient.getModuleInfo
+     */
+    getModuleInfo(moduleName: string): Promise<ModuleInfo>;
+    /**
+     * Execute code with streaming progress updates (NEW capability)
+     */
+    streamingExecute(code: string, stack: any[], onProgress?: (progress: ProgressUpdate) => void): Promise<any[]>;
+    /**
+     * Close the WebSocket connection
+     */
+    close(): void;
+    /**
+     * Check if the client is connected
+     */
+    isConnected(): boolean;
+}

package/dist/esm/websocket/client.js

@@ -0,0 +1,262 @@
+/**
+ * WebSocket Client for Forthic
+ * Browser-compatible client that mirrors GrpcClient API
+ * Connects to Rails ActionCable server and executes remote words
+ */
+import { serializeStack, deserializeStack } from './serializer.js';
+import { RemoteRuntimeError } from './errors.js';
+/**
+ * WebSocket client for executing words in remote Forthic runtimes
+ * Mirrors the GrpcClient API for compatibility
+ */
+export class WebSocketClient {
+    ws;
+    config;
+    pendingRequests = new Map();
+    messageId = 0;
+    connected = false;
+    connectionPromise;
+    constructor(config) {
+        this.config = {
+            url: config.url,
+            timezone: config.timezone || 'UTC',
+            reconnect: config.reconnect ?? true,
+            reconnectDelay: config.reconnectDelay || 3000,
+            channel: config.channel || 'ForthicRuntimeChannel',
+        };
+        this.connect();
+    }
+    /**
+     * Connect to the WebSocket server
+     */
+    connect() {
+        if (this.connectionPromise) {
+            return this.connectionPromise;
+        }
+        this.connectionPromise = new Promise((resolve, reject) => {
+            try {
+                this.ws = new WebSocket(this.config.url);
+                this.ws.onopen = () => {
+                    this.connected = true;
+                    // Subscribe to ActionCable channel
+                    const subscribeMessage = {
+                        command: 'subscribe',
+                        identifier: JSON.stringify({
+                            channel: this.config.channel,
+                            timezone: this.config.timezone,
+                        }),
+                    };
+                    this.ws.send(JSON.stringify(subscribeMessage));
+                    resolve();
+                };
+                this.ws.onmessage = (event) => {
+                    this.handleMessage(event);
+                };
+                this.ws.onerror = (error) => {
+                    console.error('WebSocket error:', error);
+                    reject(new Error('WebSocket connection error'));
+                };
+                this.ws.onclose = () => {
+                    this.connected = false;
+                    this.connectionPromise = undefined;
+                    // Reject all pending requests
+                    for (const [id, pending] of this.pendingRequests.entries()) {
+                        pending.reject(new Error('WebSocket connection closed'));
+                    }
+                    this.pendingRequests.clear();
+                    // Attempt reconnect if enabled
+                    if (this.config.reconnect) {
+                        setTimeout(() => this.connect(), this.config.reconnectDelay);
+                    }
+                };
+            }
+            catch (error) {
+                reject(error);
+            }
+        });
+        return this.connectionPromise;
+    }
+    /**
+     * Handle incoming WebSocket messages
+     */
+    handleMessage(event) {
+        try {
+            const data = JSON.parse(event.data);
+            // Handle ActionCable control messages
+            if (data.type === 'welcome' || data.type === 'ping' || data.type === 'confirm_subscription') {
+                return;
+            }
+            // Extract the actual message from ActionCable envelope
+            const message = data.message || data;
+            if (!message.id) {
+                console.warn('Received message without ID:', message);
+                return;
+            }
+            // Handle streaming progress updates
+            if (message.type === 'streaming_progress') {
+                const pending = this.pendingRequests.get(message.id);
+                if (pending?.onProgress) {
+                    pending.onProgress(message.progress);
+                }
+                return;
+            }
+            // Handle final responses
+            const pending = this.pendingRequests.get(message.id);
+            if (!pending) {
+                console.warn('Received response for unknown request:', message.id);
+                return;
+            }
+            if (message.error) {
+                pending.reject(new RemoteRuntimeError(message.error));
+            }
+            else {
+                pending.resolve(message.result);
+            }
+            this.pendingRequests.delete(message.id);
+        }
+        catch (error) {
+            console.error('Error handling WebSocket message:', error);
+        }
+    }
+    /**
+     * Generate next message ID
+     */
+    nextMessageId() {
+        return `msg-${++this.messageId}-${Date.now()}`;
+    }
+    /**
+     * Send a request and wait for response
+     */
+    async sendRequest(message) {
+        await this.ensureConnected();
+        return new Promise((resolve, reject) => {
+            this.pendingRequests.set(message.id, { resolve, reject });
+            // Wrap message in ActionCable format
+            const actionCableMessage = {
+                command: 'message',
+                identifier: JSON.stringify({
+                    channel: this.config.channel,
+                }),
+                data: JSON.stringify(message),
+            };
+            this.ws.send(JSON.stringify(actionCableMessage));
+        });
+    }
+    /**
+     * Send a streaming request with progress callbacks
+     */
+    async sendStreamingRequest(message, onProgress) {
+        await this.ensureConnected();
+        return new Promise((resolve, reject) => {
+            this.pendingRequests.set(message.id, { resolve, reject, onProgress });
+            // Wrap message in ActionCable format
+            const actionCableMessage = {
+                command: 'message',
+                identifier: JSON.stringify({
+                    channel: this.config.channel,
+                }),
+                data: JSON.stringify(message),
+            };
+            this.ws.send(JSON.stringify(actionCableMessage));
+        });
+    }
+    /**
+     * Ensure WebSocket is connected
+     */
+    async ensureConnected() {
+        if (!this.connected) {
+            await this.connect();
+        }
+    }
+    /**
+     * Execute a word in the remote runtime
+     * Mirrors GrpcClient.executeWord
+     */
+    async executeWord(word, stack) {
+        const message = {
+            type: 'execute_word',
+            id: this.nextMessageId(),
+            params: {
+                word,
+                stack: serializeStack(stack),
+            },
+        };
+        const result = await this.sendRequest(message);
+        return deserializeStack(result.stack);
+    }
+    /**
+     * Execute a sequence of words (batched execution)
+     * Mirrors GrpcClient.executeSequence
+     */
+    async executeSequence(words, stack) {
+        const message = {
+            type: 'execute_sequence',
+            id: this.nextMessageId(),
+            params: {
+                words,
+                stack: serializeStack(stack),
+            },
+        };
+        const result = await this.sendRequest(message);
+        return deserializeStack(result.stack);
+    }
+    /**
+     * List available runtime-specific modules
+     * Mirrors GrpcClient.listModules
+     */
+    async listModules() {
+        const message = {
+            type: 'list_modules',
+            id: this.nextMessageId(),
+        };
+        const result = await this.sendRequest(message);
+        return result.modules || [];
+    }
+    /**
+     * Get detailed information about a specific module
+     * Mirrors GrpcClient.getModuleInfo
+     */
+    async getModuleInfo(moduleName) {
+        const message = {
+            type: 'get_module_info',
+            id: this.nextMessageId(),
+            params: {
+                module_name: moduleName,
+            },
+        };
+        return await this.sendRequest(message);
+    }
+    /**
+     * Execute code with streaming progress updates (NEW capability)
+     */
+    async streamingExecute(code, stack, onProgress) {
+        const message = {
+            type: 'streaming_execute',
+            id: this.nextMessageId(),
+            params: {
+                code,
+                stack: serializeStack(stack),
+            },
+        };
+        const result = await this.sendStreamingRequest(message, onProgress);
+        return deserializeStack(result.stack);
+    }
+    /**
+     * Close the WebSocket connection
+     */
+    close() {
+        if (this.ws) {
+            this.config.reconnect = false; // Disable auto-reconnect
+            this.ws.close();
+            this.ws = undefined;
+            this.connected = false;
+        }
+    }
+    /**
+     * Check if the client is connected
+     */
+    isConnected() {
+        return this.connected;
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/esm/websocket/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../../src/websocket/client.ts"],"names":[],"mappings":"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"}

package/dist/esm/websocket/remote_module.d.ts

@@ -0,0 +1,68 @@
+/**
+ * WebSocketRemoteModule - Module that wraps runtime-specific words from a remote runtime
+ * Mirrors RemoteModule from gRPC implementation
+ */
+import { Module } from '../forthic/module.js';
+import { Interpreter } from '../forthic/interpreter.js';
+import { ActionCableClient, type ModuleInfo } from './action_cable_client.js';
+/**
+ * WebSocketRemoteModule - Module containing proxy words that execute in a remote runtime
+ *
+ * This module discovers words from a remote runtime (e.g., pandas module in Ruby)
+ * and creates WebSocketRemoteWord proxies for each discovered word. When used in TypeScript
+ * Forthic code, these words execute in the remote runtime via ActionCable.
+ *
+ * Example usage:
+ * ```typescript
+ * const client = new ActionCableClient({ url: 'ws://localhost:3000/cable' });
+ * const pandasModule = new WebSocketRemoteModule('pandas', client, 'rails');
+ * await pandasModule.initialize();
+ * interp.register_module(pandasModule);
+ * interp.use_modules(['pandas']);
+ *
+ * // Now pandas words execute in Rails runtime
+ * await interp.run(`
+ *   [ [[.name "Alice"]  [.age 30]] REC]
+ *   DF-FROM-RECORDS  # Executes in Rails!
+ * `);
+ * ```
+ */
+export declare class WebSocketRemoteModule extends Module {
+    private client;
+    private runtimeName;
+    private initialized;
+    private moduleInfo;
+    /**
+     * @param moduleName - Name of the module in the remote runtime (e.g., "pandas")
+     * @param client - ActionCable client connected to the remote runtime
+     * @param runtimeName - Name of the runtime (e.g., "rails") for debugging
+     */
+    constructor(moduleName: string, client: ActionCableClient, runtimeName?: string);
+    /**
+     * Initialize the module by discovering words from the remote runtime
+     *
+     * This must be called before the module is registered with an interpreter.
+     * It fetches the module metadata and creates WebSocketRemoteWord proxies for each word.
+     */
+    initialize(): Promise<void>;
+    /**
+     * Override set_interp to ensure module is initialized
+     */
+    set_interp(interp: Interpreter): void;
+    /**
+     * Get the module metadata from the remote runtime
+     */
+    getModuleInfo(): ModuleInfo | null;
+    /**
+     * Get runtime name for debugging
+     */
+    getRuntimeName(): string;
+    /**
+     * Check if module is initialized
+     */
+    isInitialized(): boolean;
+    /**
+     * Get count of discovered words
+     */
+    getWordCount(): number;
+}

package/dist/esm/websocket/remote_module.js

@@ -0,0 +1,103 @@
+/**
+ * WebSocketRemoteModule - Module that wraps runtime-specific words from a remote runtime
+ * Mirrors RemoteModule from gRPC implementation
+ */
+import { Module } from '../forthic/module.js';
+import { WebSocketRemoteWord } from './remote_word.js';
+/**
+ * WebSocketRemoteModule - Module containing proxy words that execute in a remote runtime
+ *
+ * This module discovers words from a remote runtime (e.g., pandas module in Ruby)
+ * and creates WebSocketRemoteWord proxies for each discovered word. When used in TypeScript
+ * Forthic code, these words execute in the remote runtime via ActionCable.
+ *
+ * Example usage:
+ * ```typescript
+ * const client = new ActionCableClient({ url: 'ws://localhost:3000/cable' });
+ * const pandasModule = new WebSocketRemoteModule('pandas', client, 'rails');
+ * await pandasModule.initialize();
+ * interp.register_module(pandasModule);
+ * interp.use_modules(['pandas']);
+ *
+ * // Now pandas words execute in Rails runtime
+ * await interp.run(`
+ *   [ [[.name "Alice"]  [.age 30]] REC]
+ *   DF-FROM-RECORDS  # Executes in Rails!
+ * `);
+ * ```
+ */
+export class WebSocketRemoteModule extends Module {
+    client;
+    runtimeName;
+    initialized = false;
+    moduleInfo = null;
+    /**
+     * @param moduleName - Name of the module in the remote runtime (e.g., "pandas")
+     * @param client - ActionCable client connected to the remote runtime
+     * @param runtimeName - Name of the runtime (e.g., "rails") for debugging
+     */
+    constructor(moduleName, client, runtimeName = 'remote') {
+        super(moduleName);
+        this.client = client;
+        this.runtimeName = runtimeName;
+    }
+    /**
+     * Initialize the module by discovering words from the remote runtime
+     *
+     * This must be called before the module is registered with an interpreter.
+     * It fetches the module metadata and creates WebSocketRemoteWord proxies for each word.
+     */
+    async initialize() {
+        if (this.initialized) {
+            return;
+        }
+        try {
+            // Discover module info from remote runtime
+            this.moduleInfo = await this.client.getModuleInfo(this.name);
+            // Create WebSocketRemoteWord for each discovered word
+            for (const wordInfo of this.moduleInfo.words) {
+                const remoteWord = new WebSocketRemoteWord(wordInfo.name, this.client, this.runtimeName, this.name, wordInfo.stack_effect, wordInfo.description);
+                // Add as exportable word (visible when module is imported)
+                this.add_exportable_word(remoteWord);
+            }
+            this.initialized = true;
+        }
+        catch (error) {
+            throw new Error(`Failed to initialize remote module '${this.name}' from ${this.runtimeName} runtime: ${error.message}`);
+        }
+    }
+    /**
+     * Override set_interp to ensure module is initialized
+     */
+    set_interp(interp) {
+        if (!this.initialized) {
+            throw new Error(`WebSocketRemoteModule '${this.name}' must be initialized before being registered with an interpreter. Call await module.initialize() first.`);
+        }
+        super.set_interp(interp);
+    }
+    /**
+     * Get the module metadata from the remote runtime
+     */
+    getModuleInfo() {
+        return this.moduleInfo;
+    }
+    /**
+     * Get runtime name for debugging
+     */
+    getRuntimeName() {
+        return this.runtimeName;
+    }
+    /**
+     * Check if module is initialized
+     */
+    isInitialized() {
+        return this.initialized;
+    }
+    /**
+     * Get count of discovered words
+     */
+    getWordCount() {
+        return this.moduleInfo?.words?.length || 0;
+    }
+}
+//# sourceMappingURL=remote_module.js.map

package/dist/esm/websocket/remote_module.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"remote_module.js","sourceRoot":"","sources":["../../../src/websocket/remote_module.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAG9C,OAAO,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAEvD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,MAAM,OAAO,qBAAsB,SAAQ,MAAM;IACvC,MAAM,CAAoB;IAC1B,WAAW,CAAS;IACpB,WAAW,GAAY,KAAK,CAAC;IAC7B,UAAU,GAAsB,IAAI,CAAC;IAE7C;;;;OAIG;IACH,YAAY,UAAkB,EAAE,MAAyB,EAAE,cAAsB,QAAQ;QACvF,KAAK,CAAC,UAAU,CAAC,CAAC;QAClB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,WAAW,GAAG,WAAW,CAAC;IACjC,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,UAAU;QACd,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;YACrB,OAAO;QACT,CAAC;QAED,IAAI,CAAC;YACH,2CAA2C;YAC3C,IAAI,CAAC,UAAU,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAE7D,sDAAsD;YACtD,KAAK,MAAM,QAAQ,IAAI,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE,CAAC;gBAC7C,MAAM,UAAU,GAAG,IAAI,mBAAmB,CACxC,QAAQ,CAAC,IAAI,EACb,IAAI,CAAC,MAAM,EACX,IAAI,CAAC,WAAW,EAChB,IAAI,CAAC,IAAI,EACT,QAAQ,CAAC,YAAY,EACrB,QAAQ,CAAC,WAAW,CACrB,CAAC;gBAEF,2DAA2D;gBAC3D,IAAI,CAAC,mBAAmB,CAAC,UAAU,CAAC,CAAC;YACvC,CAAC;YAED,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC;QAC1B,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,IAAI,KAAK,CACb,uCAAuC,IAAI,CAAC,IAAI,UAAU,IAAI,CAAC,WAAW,aAAc,KAAe,CAAC,OAAO,EAAE,CAClH,CAAC;QACJ,CAAC;IACH,CAAC;IAED;;OAEG;IACH,UAAU,CAAC,MAAmB;QAC5B,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC;YACtB,MAAM,IAAI,KAAK,CACb,0BAA0B,IAAI,CAAC,IAAI,0GAA0G,CAC9I,CAAC;QACJ,CAAC;QACD,KAAK,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;IAC3B,CAAC;IAED;;OAEG;IACH,aAAa;QACX,OAAO,IAAI,CAAC,UAAU,CAAC;IACzB,CAAC;IAED;;OAEG;IACH,cAAc;QACZ,OAAO,IAAI,CAAC,WAAW,CAAC;IAC1B,CAAC;IAED;;OAEG;IACH,aAAa;QACX,OAAO,IAAI,CAAC,WAAW,CAAC;IAC1B,CAAC;IAED;;OAEG;IACH,YAAY;QACV,OAAO,IAAI,CAAC,UAAU,EAAE,KAAK,EAAE,MAAM,IAAI,CAAC,CAAC;IAC7C,CAAC;CACF"}

package/dist/esm/websocket/remote_word.d.ts

@@ -0,0 +1,53 @@
+/**
+ * WebSocketRemoteWord - Word that executes in a remote runtime via ActionCable
+ * Mirrors RemoteWord from gRPC implementation
+ */
+import { Word, RuntimeInfo } from '../forthic/module.js';
+import { Interpreter } from '../forthic/interpreter.js';
+import { ActionCableClient } from './action_cable_client.js';
+/**
+ * WebSocketRemoteWord - Proxy word that delegates execution to a remote runtime
+ *
+ * When executed:
+ * 1. Captures current interpreter stack
+ * 2. Sends word name + stack to remote runtime via ActionCable
+ * 3. Replaces local stack with result stack from remote execution
+ *
+ * This allows seamless integration of remote runtime words
+ * into the local TypeScript interpreter.
+ */
+export declare class WebSocketRemoteWord extends Word {
+    private client;
+    private runtimeName;
+    private moduleName;
+    stackEffect: string;
+    description: string;
+    /**
+     * @param name - Word name (e.g., "DF_FROM_RECORDS")
+     * @param client - ActionCable client connected to remote runtime
+     * @param runtimeName - Name of remote runtime (e.g., "rails", "ruby")
+     * @param moduleName - Module name (e.g., "pandas")
+     * @param stackEffect - Stack notation (e.g., "( records:array -- df:DataFrame )")
+     * @param description - Human-readable description
+     */
+    constructor(name: string, client: ActionCableClient, runtimeName: string, moduleName: string, stackEffect?: string, description?: string);
+    /**
+     * Execute word in remote runtime
+     *
+     * Captures entire stack, sends to remote runtime, and replaces stack with result.
+     */
+    execute(interp: Interpreter): Promise<void>;
+    /**
+     * Get runtime name for debugging/introspection
+     */
+    getRuntimeName(): string;
+    /**
+     * Get module name for debugging/introspection
+     */
+    getModuleName(): string;
+    /**
+     * Get runtime execution information
+     * RemoteWords are runtime-specific and can only execute in their designated runtime
+     */
+    getRuntimeInfo(): RuntimeInfo;
+}