@perspective-dev/client 4.0.0

package/src/ts/perspective.node.ts

@@ -0,0 +1,315 @@
+// ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+// ┃ ██████ ██████ ██████       █      █      █      █      █ █▄  ▀███ █       ┃
+// ┃ ▄▄▄▄▄█ █▄▄▄▄▄ ▄▄▄▄▄█  ▀▀▀▀▀█▀▀▀▀▀ █ ▀▀▀▀▀█ ████████▌▐███ ███▄  ▀█ █ ▀▀▀▀▀ ┃
+// ┃ █▀▀▀▀▀ █▀▀▀▀▀ █▀██▀▀ ▄▄▄▄▄ █ ▄▄▄▄▄█ ▄▄▄▄▄█ ████████▌▐███ █████▄   █ ▄▄▄▄▄ ┃
+// ┃ █      ██████ █  ▀█▄       █ ██████      █      ███▌▐███ ███████▄ █       ┃
+// ┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
+// ┃ 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). ┃
+// ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
+
+export type * from "../../dist/wasm/perspective-js.d.ts";
+
+import WebSocket, { WebSocketServer as HttpWebSocketServer } from "ws";
+import stoppable from "stoppable";
+import { promises as fs } from "node:fs";
+import http from "node:http";
+import path from "node:path";
+import { webcrypto } from "node:crypto";
+import type * as net from "node:net";
+import * as url from "node:url";
+import { createRequire } from "node:module";
+
+import * as perspective_client from "../../dist/wasm/perspective-js.js";
+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";
+
+const __dirname = path.dirname(url.fileURLToPath(import.meta.url));
+
+const { resolve } = createRequire(import.meta.url);
+
+if (!globalThis.crypto) {
+    globalThis.crypto = webcrypto as Crypto;
+}
+
+const uncompressed_client_wasm = await fs
+    .readFile(path.join(__dirname, "../../dist/wasm/perspective-js.wasm"))
+    .then((buffer) => load_wasm_stage_0(buffer.buffer as ArrayBuffer));
+
+await perspective_client.default({ module_or_path: uncompressed_client_wasm });
+const SYNC_MODULE = await fs
+    .readFile(
+        resolve("@perspective-dev/server/dist/wasm/perspective-server.wasm"),
+    )
+    .then((buffer) => load_wasm_stage_0(buffer.buffer as ArrayBuffer))
+    .then((buffer) => compile_perspective(buffer.buffer as ArrayBuffer));
+
+let SYNC_CLIENT: perspective_client.Client;
+
+const SYNC_SERVER = new engine.PerspectiveServer(SYNC_MODULE);
+
+// const SYNC_SERVER = new engine.PerspectiveServer(SYNC_MODULE, {
+//     on_poll_request: () => SYNC_POLL_HANDLE.on_poll_request(),
+// });
+
+// const SYNC_POLL_HANDLE: engine.PerspectivePollThread =
+//     new engine.PerspectivePollThread(SYNC_SERVER);
+
+const SYNC_SESSION = SYNC_SERVER.make_session(
+    async (resp) => await SYNC_CLIENT.handle_response(resp),
+);
+
+SYNC_CLIENT = new perspective_client.Client(async (req: Uint8Array) => {
+    await SYNC_SESSION.handle_request(req);
+});
+
+export class PerspectiveServer extends engine.PerspectiveServer {
+    constructor(options?: engine.PerspectiveServerOptions) {
+        super(SYNC_MODULE, options);
+    }
+}
+
+export const make_session = async (
+    send_response: (buffer: Uint8Array) => Promise<void>,
+) => SYNC_SERVER.make_session(send_response);
+
+// Helper function to create client emitter/receiver pairs
+export function make_client(
+    send_request: (buffer: Uint8Array) => Promise<void>,
+    close?: Function,
+) {
+    return new perspective_client.Client(send_request, close);
+}
+
+const CONTENT_TYPES: Record<string, string> = {
+    ".js": "text/javascript",
+    ".mjs": "text/javascript",
+    ".css": "text/css; charset=utf-8",
+    ".json": "application/json",
+    ".arrow": "arraybuffer",
+    ".feather": "arraybuffer",
+    ".wasm": "application/wasm",
+};
+
+/**
+ * Host a Perspective server that hosts data, code files, etc.
+ * Strip version numbers from the URL so we can handle CDN-like requests
+ * of the form @[^~]major.minor.patch when testing local versions of
+ * Perspective against Voila.
+ */
+export async function cwd_static_file_handler(
+    request: http.IncomingMessage,
+    response: http.ServerResponse<http.IncomingMessage>,
+    assets = ["./"],
+    { debug = true } = {},
+) {
+    let url =
+        request.url
+            ?.split(/[\?\#]/)[0]
+            .replace(/@[\^~]?\d+.[\d\*]*.[\d\*]*/, "") || "/";
+
+    if (url === "/") {
+        url = "/index.html";
+    }
+
+    let extname = path.extname(url);
+    let contentType = CONTENT_TYPES[extname] || "text/html";
+    try {
+        for (const root of assets) {
+            let filePath = root + url;
+            try {
+                let content = await fs.readFile(filePath);
+                if (typeof content !== "undefined") {
+                    if (debug) {
+                        console.log(`200 ${url}`);
+                    }
+                    response.writeHead(200, {
+                        "Content-Type": contentType,
+                        "Access-Control-Allow-Origin": "*",
+                    });
+                    if (extname === ".arrow" || extname === ".feather") {
+                        response.end(content, "utf-8");
+                    } else {
+                        response.end(content);
+                    }
+
+                    return;
+                }
+            } catch (e) {}
+        }
+
+        if (debug) {
+            console.error(`404 ${url}`);
+        }
+
+        response.writeHead(404);
+        response.end("", "utf-8");
+    } catch (error) {
+        if (debug) {
+            console.error(`500 ${url} ${error}`);
+        }
+
+        response.writeHead(500);
+        response.end("", "utf-8");
+    }
+}
+
+function buffer_to_arraybuffer(
+    buffer: string | Buffer | ArrayBuffer | Buffer[] | Uint8Array,
+): Uint8Array {
+    if (typeof buffer === "string") {
+        throw new Error("Unknown websocket message: " + buffer);
+    } else if (buffer instanceof ArrayBuffer) {
+        return new Uint8Array(buffer);
+    } else if (buffer instanceof Array) {
+        throw new Error("Unknown websocket message: " + buffer);
+    } else {
+        return new Uint8Array(
+            buffer.buffer.slice(
+                buffer.byteOffset,
+                buffer.byteOffset + buffer.length,
+            ),
+        );
+    }
+}
+
+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;
+    constructor({ port = 8080, assets = ["./"], server = undefined } = {}) {
+        const perspective_server =
+            typeof server === "undefined" ? SYNC_SERVER : server;
+
+        port = typeof port === "undefined" ? 8080 : port;
+        this._server = stoppable(
+            http.createServer((x, y) => cwd_static_file_handler(x, y, assets)),
+        );
+
+        this._wss = new HttpWebSocketServer({
+            noServer: true,
+            perMessageDeflate: true,
+        });
+
+        this._wss.on("connection", (ws) => {
+            console.log("... Connecting websocket");
+            const session = perspective_server.make_session(
+                async (proto: Uint8Array) => {
+                    ws.send(buffer_to_arraybuffer(proto));
+                },
+            );
+
+            ws.on("message", (proto) => {
+                session.handle_request(buffer_to_arraybuffer(proto));
+            });
+
+            ws.on("close", () => {
+                session.close();
+            });
+        });
+
+        this._server.on(
+            "upgrade",
+            (
+                request: http.IncomingMessage,
+                socket: net.Socket,
+                head: Buffer,
+            ) => {
+                console.log("200 Websocket upgrade");
+                this._wss.handleUpgrade(
+                    request,
+                    socket as net.Socket,
+                    head,
+                    (sock) => this._wss.emit("connection", sock, request),
+                );
+            },
+        );
+
+        this._server.listen(port, () => {
+            console.log(`Listening on ${this._server.address().port}`);
+        });
+    }
+
+    async close() {
+        await new Promise((x) => this._server.stop(x));
+    }
+}
+
+export function get_hosted_table_names() {
+    return SYNC_CLIENT.get_hosted_table_names();
+}
+
+export function on_hosted_tables_update(cb: () => void) {
+    return SYNC_CLIENT.on_hosted_tables_update(cb);
+}
+
+export function remove_hosted_tables_update(id: number) {
+    return SYNC_CLIENT.remove_hosted_tables_update(id);
+}
+
+export function system_info() {
+    return SYNC_CLIENT.system_info();
+}
+
+export function on_error(callback: Function) {
+    return SYNC_CLIENT.on_error(callback);
+}
+
+/**
+ * Create a table from the global Perspective instance.
+ * @param init_data
+ * @param options
+ * @returns
+ */
+export function table(
+    init_data:
+        | string
+        | ArrayBuffer
+        | Record<string, any>
+        | Record<string, unknown>[],
+    options?: perspective_client.TableInitOptions,
+) {
+    return SYNC_CLIENT.table(init_data, options);
+}
+
+/**
+ * Create a new client connected via WebSocket to a server implemnting the
+ * Perspective Protocol.
+ * @param module
+ * @param url
+ * @returns
+ */
+export async function websocket(
+    url: string,
+): Promise<perspective_client.Client> {
+    return await psp_websocket.websocket(
+        WebSocket as unknown as typeof window.WebSocket,
+        perspective_client.Client,
+        url,
+    );
+}
+
+export default {
+    table,
+    websocket,
+    get_hosted_table_names,
+    on_hosted_tables_update,
+    remove_hosted_tables_update,
+    on_error,
+    system_info,
+    WebSocketServer,
+};

package/src/ts/ts-rs/Aggregate.ts

@@ -0,0 +1,3 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+
+export type Aggregate = string | [string, Array<string>];

package/src/ts/ts-rs/ColumnWindow.ts

@@ -0,0 +1,3 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+
+export type ColumnWindow = { start_col: number | null, end_col: number | null, };

package/src/ts/ts-rs/DeleteOptions.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.
+
+/**
+ * Options for [`Table::delete`].
+ */
+export type DeleteOptions = { lazy: boolean, };

package/src/ts/ts-rs/Expressions.ts

@@ -0,0 +1,3 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+
+export type Expressions = { [key in string]?: string };

package/src/ts/ts-rs/Filter.ts

@@ -0,0 +1,4 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+import type { FilterTerm } from "./FilterTerm.js";
+
+export type Filter = [string, string, FilterTerm];

package/src/ts/ts-rs/FilterReducer.ts

@@ -0,0 +1,3 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+
+export type FilterReducer = "and" | "or";

package/src/ts/ts-rs/FilterTerm.ts

@@ -0,0 +1,4 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+import type { Scalar } from "./Scalar.js";
+
+export type FilterTerm = Array<Scalar> | Scalar;

package/src/ts/ts-rs/OnUpdateData.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 { ViewOnUpdateResp } from "./ViewOnUpdateResp.js";
+
+/**
+ * Rows updated and port ID corresponding to an update batch, provided to the
+ * callback argument to [`View::on_update`] with the "rows" mode.
+ */
+export type OnUpdateData = ViewOnUpdateResp;

package/src/ts/ts-rs/OnUpdateMode.ts

@@ -0,0 +1,11 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+
+/**
+ * The update mode for [`View::on_update`].
+ *
+ * `Row` mode calculates and provides the update batch new rows/columns as an
+ * Apache Arrow to the callback provided to [`View::on_update`]. This allows
+ * incremental updates if your callbakc can read this format, but should be
+ * disabled otherwise.
+ */
+export type OnUpdateMode = "row";

package/src/ts/ts-rs/OnUpdateOptions.ts

@@ -0,0 +1,7 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+import type { OnUpdateMode } from "./OnUpdateMode.js";
+
+/**
+ * Options for [`View::on_update`].
+ */
+export type OnUpdateOptions = { mode: OnUpdateMode | null, };

package/src/ts/ts-rs/Scalar.ts

@@ -0,0 +1,7 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+
+/**
+ * This type represents the ViewConfig serializable type, which must be JSON
+ * safe.
+ */
+export type Scalar = number | string | boolean | null;

package/src/ts/ts-rs/Sort.ts

@@ -0,0 +1,4 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+import type { SortDir } from "./SortDir.js";
+
+export type Sort = [string, SortDir];

package/src/ts/ts-rs/SortDir.ts

@@ -0,0 +1,3 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+
+export type SortDir = "none" | "desc" | "asc" | "col desc" | "col asc" | "desc abs" | "asc abs" | "col desc abs" | "col asc abs";

package/src/ts/ts-rs/SystemInfo.ts

@@ -0,0 +1,41 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+
+/**
+ * Metadata about the engine runtime (such as total heap utilization).
+ */
+export type SystemInfo<T = bigint> = { 
+/**
+ * Total available bytes for allocation on the [`Server`].
+ */
+heap_size: T, 
+/**
+ * Bytes allocated for use on the [`Server`].
+ */
+used_size: T, 
+/**
+ * Wall-clock time spent processing requests on the [`Server`], in
+ * milliseconds (estimated). This does not properly account for the
+ * internal thread pool (which enables column-parallel processing of
+ * individual requests).
+ */
+cpu_time: number, 
+/**
+ * Milliseconds since internal CPU time accumulator was reset.
+ */
+cpu_time_epoch: number, 
+/**
+ * Timestamp (POSIX) this request was made. This field may be omitted
+ * for wasm due to `perspective-client` lacking a dependency on
+ * `wasm_bindgen`.
+ */
+timestamp: T | null, 
+/**
+ * Total available bytes for allocation on the [`Client`]. This is only
+ * available if `trace-allocator` is enabled.
+ */
+client_heap: T | null, 
+/**
+ * Bytes allocated for use on the [`Client`].  This is only
+ * available if `trace-allocator` is enabled.
+ */
+client_used: T | null, };

package/src/ts/ts-rs/TableInitOptions.ts

@@ -0,0 +1,21 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+import type { TableReadFormat } from "./TableReadFormat.js";
+
+/**
+ * Options which impact the behavior of [`Client::table`], as well as
+ * subsequent calls to [`Table::update`].
+ */
+export type TableInitOptions = { name?: string, format?: TableReadFormat, 
+/**
+ * This [`Table`] should use the column named by the `index` parameter as
+ * the `index`, which causes [`Table::update`] and [`Client::table`] input
+ * to either insert or update existing rows based on `index` column
+ * value equality.
+ */
+index?: string, 
+/**
+ * This [`Table`] should be limited to `limit` rows, after which the
+ * _earliest_ rows will be overwritten (where _earliest_ is defined as
+ * relative to insertion order).
+ */
+limit?: number, };

package/src/ts/ts-rs/TableReadFormat.ts

@@ -0,0 +1,9 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+
+/**
+ * The format to interpret data preovided to [`Client::table`].
+ *
+ * When serialized, these values are `"csv"`, `"json"`, `"columns"`, `"arrow"`
+ * and `"ndjson"`.
+ */
+export type TableReadFormat = "csv" | "json" | "columns" | "arrow" | "ndjson";

package/src/ts/ts-rs/UpdateOptions.ts

@@ -0,0 +1,7 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+import type { TableReadFormat } from "./TableReadFormat.js";
+
+/**
+ * Options for [`Table::update`].
+ */
+export type UpdateOptions = { port_id: number | null, format: TableReadFormat | null, };

package/src/ts/ts-rs/ViewConfigUpdate.ts

@@ -0,0 +1,87 @@
+// 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 ViewConfigUpdate = { 
+/**
+ * A group by _groups_ the dataset by the unique values of each column used
+ * as a group by - a close analogue in SQL to the `GROUP BY` statement.
+ * The underlying dataset is aggregated to show the values belonging to
+ * each group, and a total row is calculated for each group, showing
+ * the currently selected aggregated value (e.g. `sum`) of the column.
+ * Group by are useful for hierarchies, categorizing data and
+ * attributing values, i.e. showing the number of units sold based on
+ * State and City. In Perspective, group by are represented as an array
+ * of string column names to pivot, are applied in the order provided;
+ * For example, a group by of `["State", "City", "Postal Code"]` shows
+ * the values for each Postal Code, which are grouped by City,
+ * which are in turn grouped by State.
+ */
+group_by?: Array<string>, 
+/**
+ * A split by _splits_ the dataset by the unique values of each column used
+ * as a split by. The underlying dataset is not aggregated, and a new
+ * column is created for each unique value of the split by. Each newly
+ * created column contains the parts of the dataset that correspond to
+ * the column header, i.e. a `View` that has `["State"]` as its split
+ * by will have a new column for each state. In Perspective, Split By
+ * are represented as an array of string column names to pivot.
+ */
+split_by?: Array<string>, 
+/**
+ * The `columns` property specifies which columns should be included in the
+ * [`crate::View`]'s output. This allows users to show or hide a specific
+ * subset of columns, as well as control the order in which columns
+ * appear to the user. This is represented in Perspective as an array
+ * of string column names.
+ */
+columns?: Array<string | null>, 
+/**
+ * The `filter` property specifies columns on which the query can be
+ * filtered, returning rows that pass the specified filter condition.
+ * This is analogous to the `WHERE` clause in SQL. There is no limit on
+ * the number of columns where `filter` is applied, but the resulting
+ * dataset is one that passes all the filter conditions, i.e. the
+ * filters are joined with an `AND` condition.
+ *
+ * Perspective represents `filter` as an array of arrays, with the values
+ * of each inner array being a string column name, a string filter
+ * operator, and a filter operand in the type of the column.
+ */
+filter?: Array<Filter>, 
+/**
+ * The `sort` property specifies columns on which the query should be
+ * sorted, analogous to `ORDER BY` in SQL. A column can be sorted
+ * regardless of its data type, and sorts can be applied in ascending
+ * or descending order. Perspective represents `sort` as an array of
+ * arrays, with the values of each inner array being a string column
+ * name and a string sort direction. When `column-pivots` are applied,
+ * the additional sort directions `"col asc"` and `"col desc"` will
+ * determine the order of pivot columns groups.
+ */
+sort?: Array<Sort>, 
+/**
+ * The `expressions` property specifies _new_ columns in Perspective that
+ * are created using existing column values or arbitary scalar values
+ * defined within the expression. In `<perspective-viewer>`,
+ * expressions are added using the "New Column" button in the side
+ * panel.
+ */
+expressions?: Expressions, 
+/**
+ * Aggregates perform a calculation over an entire column, and are
+ * displayed when one or more [Group By](#group-by) are applied to the
+ * `View`. Aggregates can be specified by the user, or Perspective will
+ * use the following sensible default aggregates based on column type:
+ *
+ * - "sum" for `integer` and `float` columns
+ * - "count" for all other columns
+ *
+ * Perspective provides a selection of aggregate functions that can be
+ * applied to columns in the `View` constructor using a dictionary of
+ * column name to aggregate function name.
+ */
+aggregates?: { [key in string]?: Aggregate }, group_by_depth?: number, filter_op?: FilterReducer, };

package/src/ts/ts-rs/ViewOnUpdateResp.ts

@@ -0,0 +1,3 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+
+export type ViewOnUpdateResp = { delta: Array<number>, port_id: number, };

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

@@ -0,0 +1,17 @@
+// This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+
+/**
+ * Options for serializing a window of data from a [`View`].
+ *
+ * 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, 
+/**
+ * Only impacts [`View::to_csv`]
+ */
+formatted: boolean | null, 
+/**
+ * Only impacts [`View::to_arrow`]
+ */
+compression: string | null, };