@perspective-dev/client 4.0.0 → 4.1.0

package/src/ts/perspective-server.worker.ts

@@ -20,35 +20,45 @@ import { compile_perspective } from "./wasm/emscripten_api.ts";
 let GLOBAL_SERVER: PerspectiveServer;
 let POLL_THREAD: PerspectivePollThread;
 
-function bindPort(e: MessageEvent) {
-    const port = e.ports[0];
-    let session: PerspectiveSession;
-    port.addEventListener("message", async (msg) => {
-        if (msg.data.cmd === "init") {
-            const id = msg.data.id;
-            if (!GLOBAL_SERVER) {
-                const module = await compile_perspective(msg.data.args[0]);
-                GLOBAL_SERVER = new PerspectiveServer(module, {
-                    on_poll_request: () => POLL_THREAD.on_poll_request(),
-                });
-
-                POLL_THREAD = new PerspectivePollThread(GLOBAL_SERVER);
-            }
-
-            session = GLOBAL_SERVER.make_session(async (resp) => {
-                const f = resp.slice().buffer;
-                port.postMessage(f, { transfer: [f] });
+let SESSION: PerspectiveSession | undefined;
+
+async function handleMessage(this: MessagePort, msg: MessageEvent) {
+    if (msg.data.cmd === "init") {
+        const id = msg.data.id;
+        if (!GLOBAL_SERVER) {
+            const module = await compile_perspective(msg.data.args[0]);
+
+            GLOBAL_SERVER = new PerspectiveServer(module, {
+                on_poll_request: () => POLL_THREAD.on_poll_request(),
             });
 
-            port.postMessage({ id });
+            POLL_THREAD = new PerspectivePollThread(GLOBAL_SERVER);
+        }
+
+        SESSION = GLOBAL_SERVER.make_session(async (resp) => {
+            const f = resp.slice().buffer;
+            this.postMessage(f, { transfer: [f] });
+        });
+
+        this.postMessage({ id });
+    } else {
+        if (SESSION) {
+            await SESSION?.handle_request(new Uint8Array(msg.data));
         } else {
-            await session.handle_request(new Uint8Array(msg.data));
+            throw new Error("No session");
         }
-    });
+    }
+}
 
+function bindPortSharedWorker(msg: MessageEvent) {
+    const port = msg.ports[0];
+    port.addEventListener("message", handleMessage.bind(port));
     port.start();
 }
 
 // @ts-expect-error wrong scope
-self.addEventListener("connect", bindPort);
-self.addEventListener("message", bindPort);
+self.addEventListener("connect", bindPortSharedWorker);
+self.addEventListener(
+    "message",
+    handleMessage.bind(self as unknown as MessagePort),
+);

package/src/ts/perspective.browser.ts

@@ -12,6 +12,9 @@
 
 export type * from "../../dist/wasm/perspective-js.d.ts";
 import type * as psp from "../../dist/wasm/perspective-js.d.ts";
+export type * from "./virtual_server.ts";
+
+import * as psp_virtual from "./virtual_server.ts";
 
 import * as wasm_module from "../../dist/wasm/perspective-js.js";
 import * as api from "./wasm/browser.ts";
@@ -19,6 +22,12 @@ import { load_wasm_stage_0 } from "./wasm/decompress.ts";
 
 let GLOBAL_SERVER_WASM: Promise<ArrayBuffer | WebAssembly.Module>;
 
+export async function createMessageHandler(
+    handler: psp_virtual.VirtualServerHandler,
+) {
+    return psp_virtual.createMessageHandler(await get_client(), handler);
+}
+
 export function init_server(
     wasm:
         | Uint8Array
@@ -120,7 +129,7 @@ export async function websocket(url: string | URL) {
 }
 
 export async function worker(
-    worker?: Promise<SharedWorker | ServiceWorker | Worker>,
+    worker?: Promise<SharedWorker | ServiceWorker | Worker | MessagePort>,
 ) {
     if (typeof worker === "undefined") {
         worker = get_worker();
@@ -129,4 +138,10 @@ export async function worker(
     return await api.worker(get_client(), get_server(), worker);
 }
 
-export default { websocket, worker, init_client, init_server };
+export default {
+    websocket,
+    worker,
+    init_client,
+    init_server,
+    createMessageHandler,
+};

package/src/ts/perspective.node.ts

@@ -11,6 +11,7 @@
 // ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
 
 export type * from "../../dist/wasm/perspective-js.d.ts";
+export type * from "./virtual_server.ts";
 
 import WebSocket, { WebSocketServer as HttpWebSocketServer } from "ws";
 import stoppable from "stoppable";
@@ -27,6 +28,9 @@ import { load_wasm_stage_0 } from "./wasm/decompress.js";
 import * as engine from "./wasm/engine.ts";
 import { compile_perspective } from "./wasm/emscripten_api.ts";
 import * as psp_websocket from "./websocket.ts";
+import * as api from "./wasm/browser.ts";
+
+import * as virtual_server from "./virtual_server.ts";
 
 const __dirname = path.dirname(url.fileURLToPath(import.meta.url));
 
@@ -177,17 +181,6 @@ function buffer_to_arraybuffer(
     }
 }
 
-function invert_promise<T>(): [(t: T) => void, Promise<T>, (t: any) => void] {
-    let sender: ((t: T) => void) | undefined = undefined,
-        reject = undefined;
-    let receiver: Promise<T> = new Promise((x, u) => {
-        sender = x;
-        reject = u;
-    });
-
-    return [sender!, receiver, reject!];
-}
-
 export class WebSocketServer {
     _server: http.Server | any; // stoppable has no type ...
     _wss: HttpWebSocketServer;
@@ -303,9 +296,51 @@ export async function websocket(
     );
 }
 
+export async function worker(worker: Promise<MessagePort>) {
+    const port = await worker;
+    const client = new perspective_client.Client(
+        async (proto: Uint8Array) => {
+            const f = proto.slice().buffer;
+            port.postMessage(f, { transfer: [f] });
+        },
+        async () => {
+            console.debug("Closing WebWorker");
+            port.close();
+        },
+    );
+
+    const { promise, resolve, reject } = Promise.withResolvers();
+    port.onmessage = function listener(resp) {
+        port.onmessage = null;
+        resolve(null);
+    };
+
+    port.onmessageerror = function (...args) {
+        port.onmessage = null;
+        console.error(...args);
+        reject(args);
+    };
+
+    port.postMessage({ cmd: "init", args: [] });
+    await promise;
+    port.addEventListener("message", (json: MessageEvent<Uint8Array>) => {
+        client.handle_response(json.data);
+    });
+
+    console.log(client);
+    return client;
+}
+
+export function createMessageHandler(
+    handler: virtual_server.VirtualServerHandler,
+) {
+    return virtual_server.createMessageHandler(perspective_client, handler);
+}
+
 export default {
     table,
     websocket,
+    worker,
     get_hosted_table_names,
     on_hosted_tables_update,
     remove_hosted_tables_update,

package/src/ts/ts-rs/ColumnType.ts

@@ -0,0 +1,6 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+
+/**
+ * View types
+ */
+export type ColumnType = "string" | "date" | "datetime" | "integer" | "float" | "boolean";

package/src/ts/ts-rs/ViewConfig.ts

@@ -0,0 +1,8 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+import type { Aggregate } from "./Aggregate.js";
+import type { Expressions } from "./Expressions.js";
+import type { Filter } from "./Filter.js";
+import type { FilterReducer } from "./FilterReducer.js";
+import type { Sort } from "./Sort.js";
+
+export type ViewConfig = { group_by: Array<string>, split_by: Array<string>, sort: Array<Sort>, filter: Array<Filter>, filter_op?: FilterReducer, expressions: Expressions, columns: Array<string | null>, aggregates: { [key in string]?: Aggregate }, group_by_depth?: number | null, };

package/src/ts/ts-rs/ViewWindow.ts

@@ -6,12 +6,12 @@
  * Some fields of [`ViewWindow`] are only applicable to specific methods of
  * [`View`].
  */
-export type ViewWindow = { start_row: number | null, start_col: number | null, end_row: number | null, end_col: number | null, id: boolean | null, index: boolean | null, leaves_only: boolean | null, 
+export type ViewWindow = { start_row?: number, start_col?: number, end_row?: number, end_col?: number, id?: boolean, index?: boolean, leaves_only?: boolean, 
 /**
  * Only impacts [`View::to_csv`]
  */
-formatted: boolean | null, 
+formatted?: boolean, 
 /**
  * Only impacts [`View::to_arrow`]
  */
-compression: string | null, };
+compression?: string, };

package/src/ts/virtual_server.ts

@@ -0,0 +1,126 @@
+// ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+// ┃ ██████ ██████ ██████       █      █      █      █      █ █▄  ▀███ █       ┃
+// ┃ ▄▄▄▄▄█ █▄▄▄▄▄ ▄▄▄▄▄█  ▀▀▀▀▀█▀▀▀▀▀ █ ▀▀▀▀▀█ ████████▌▐███ ███▄  ▀█ █ ▀▀▀▀▀ ┃
+// ┃ █▀▀▀▀▀ █▀▀▀▀▀ █▀██▀▀ ▄▄▄▄▄ █ ▄▄▄▄▄█ ▄▄▄▄▄█ ████████▌▐███ █████▄   █ ▄▄▄▄▄ ┃
+// ┃ █      ██████ █  ▀█▄       █ ██████      █      ███▌▐███ ███████▄ █       ┃
+// ┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
+// ┃ Copyright (c) 2017, the Perspective Authors.                              ┃
+// ┃ ╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌╌ ┃
+// ┃ This file is part of the Perspective library, distributed under the terms ┃
+// ┃ of the [Apache License 2.0](https://www.apache.org/licenses/LICENSE-2.0). ┃
+// ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
+
+import { ColumnType } from "./ts-rs/ColumnType.ts";
+import { ViewConfig } from "./ts-rs/ViewConfig.ts";
+import { ViewWindow } from "./ts-rs/ViewWindow.ts";
+
+import type * as perspective from "../../dist/wasm/perspective-js.js";
+
+/**
+ * VirtualServer API for implementing custom data sources in JavaScript/WASM.
+ *
+ * The VirtualServer pattern allows you to create custom data sources that
+ * integrate with Perspective's protocol. This is useful for:
+ * - Connecting to external databases (DuckDB, PostgreSQL, etc.)
+ * - Streaming data from APIs or message queues
+ * - Implementing custom aggregation or transformation logic
+ * - Creating data adapters without copying data into Perspective tables
+ *
+ * @module virtual_server
+ */
+
+export interface ServerFeatures {
+    expressions?: boolean;
+}
+
+/**
+ * Handler interface that you implement to provide custom data sources.
+ *
+ * All methods will be called by the VirtualServer when handling protocol
+ * messages from Perspective clients. Methods can return values directly or
+ * return Promises for asynchronous operations (e.g., database queries).
+ */
+export interface VirtualServerHandler {
+    getHostedTables(): string[] | Promise<string[]>;
+    tableSchema(
+        tableId: string,
+    ): Record<string, ColumnType> | Promise<Record<string, ColumnType>>;
+    tableSize(tableId: string): number | Promise<number>;
+    tableMakeView(
+        tableId: string,
+        viewId: string,
+        config: ViewConfig,
+    ): void | Promise<void>;
+    viewDelete(viewId: string): void | Promise<void>;
+    viewGetData(
+        viewId: string,
+        config: ViewConfig,
+        viewport: ViewWindow,
+        dataSlice: perspective.JsVirtualDataSlice,
+    ): void | Promise<void>;
+    viewSchema?(
+        viewId: string,
+        config?: ViewConfig,
+    ): Record<string, ColumnType> | Promise<Record<string, ColumnType>>;
+    viewSize?(viewId: string): number | Promise<number>;
+    tableValidateExpression?(
+        tableId: string,
+        expression: string,
+    ): ColumnType | Promise<ColumnType>;
+    getFeatures?(): ServerFeatures | Promise<ServerFeatures>;
+    makeTable?(
+        tableId: string,
+        data: string | Uint8Array,
+    ): void | Promise<void>;
+}
+
+export function createMessageHandler(
+    mod: typeof perspective,
+    handler: VirtualServerHandler,
+) {
+    let virtualServer: perspective.JsVirtualServer;
+    async function postMessage(port: MessagePort, msg: MessageEvent) {
+        if (msg.data.cmd === "init") {
+            try {
+                virtualServer = new mod.JsVirtualServer(handler);
+                if (msg.data.id !== undefined) {
+                    port.postMessage({ id: msg.data.id });
+                } else {
+                    port.postMessage(null);
+                }
+            } catch (error) {
+                console.error("Error initializing worker:", error);
+                throw error;
+            }
+        } else {
+            try {
+                const requestBytes = new Uint8Array(msg.data);
+                const responseBytes =
+                    await virtualServer.handleRequest(requestBytes);
+                const buffer = responseBytes.slice().buffer;
+                port.postMessage(buffer, { transfer: [buffer] });
+            } catch (error) {
+                console.error("Error handling request in worker:", error);
+                throw error;
+            }
+        }
+    }
+
+    const channel = new MessageChannel();
+    channel.port1.onmessage = (message) => {
+        postMessage(channel.port1, message);
+    };
+
+    return channel.port2;
+}
+
+/**
+ * Re-export the WASM VirtualServer and VirtualDataSlice classes with better names.
+ *
+ * VirtualServer: Handles Perspective protocol messages using your custom handler
+ * VirtualDataSlice: Used to fill data in viewGetData callbacks
+ */
+export {
+    JsVirtualServer as VirtualServer,
+    JsVirtualDataSlice as VirtualDataSlice,
+} from "../../dist/wasm/perspective-js.js";