@perspective-dev/client 4.3.0 → 4.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@perspective-dev/client",
-  "version": "4.3.0",
+  "version": "4.4.0",
   "description": "",
   "repository": {
     "type": "git",
@@ -49,13 +49,13 @@
     "@perspective-dev/metadata": "",
     "@perspective-dev/test": "",
     "@clickhouse/client-web": "^1.12.0",
-    "@duckdb/duckdb-wasm": "^1.30.0",
-    "@playwright/experimental-ct-react": "=1.52.0",
-    "@playwright/test": "=1.52.0",
+    "@duckdb/duckdb-wasm": "1.33.1-dev18.0",
+    "@playwright/experimental-ct-react": "=1.58.0",
+    "@playwright/test": "=1.58.0",
     "@types/node": ">=22",
     "@types/ws": ">=8",
     "@types/stoppable": ">=1",
-    "apache-arrow": "18.1.0",
+    "apache-arrow": "17.0.0",
     "superstore-arrow": "3.2.0",
     "lodash": "^4.17.20",
     "moment": "^2.30.1",

package/src/rust/client.rs

@@ -20,7 +20,7 @@ use js_sys::{Function, Uint8Array};
 #[cfg(doc)]
 use perspective_client::SystemInfo;
 use perspective_client::{
-    ClientError, ReconnectCallback, Session, TableData, TableInitOptions, asyncfn,
+    ClientError, ReconnectCallback, Session, TableData, TableInitOptions, TableRef, asyncfn,
 };
 use wasm_bindgen::prelude::*;
 use wasm_bindgen_derive::TryFromJsValue;
@@ -35,6 +35,35 @@ extern "C" {
     #[derive(Clone)]
     #[wasm_bindgen(typescript_type = "TableInitOptions")]
     pub type JsTableInitOptions;
+
+    #[derive(Clone)]
+    #[wasm_bindgen(typescript_type = "JoinOptions")]
+    pub type JsJoinOptions;
+}
+
+async fn js_to_table_ref(val: &JsValue) -> ApiResult<TableRef> {
+    if let Some(name) = val.as_string() {
+        Ok(TableRef::from(name))
+    } else {
+        let get_name = js_sys::Reflect::get(val, &wasm_bindgen::intern("get_name").into())
+            .map_err(|_| apierror!(TableRefError))?
+            .dyn_into::<js_sys::Function>()
+            .map_err(|_| apierror!(TableRefError))?;
+
+        let promise = get_name
+            .call0(val)
+            .map_err(|_| apierror!(TableRefError))?
+            .dyn_into::<js_sys::Promise>()
+            .map_err(|_| apierror!(TableRefError))?;
+
+        let name = wasm_bindgen_futures::JsFuture::from(promise)
+            .await
+            .map_err(|_| apierror!(TableRefError))?
+            .as_string()
+            .ok_or_else(|| apierror!(TableRefError))?;
+
+        Ok(TableRef::from(name))
+    }
 }
 
 #[wasm_bindgen]
@@ -382,6 +411,46 @@ impl Client {
         Ok(Table(self.client.table(args, options).await?))
     }
 
+    /// Creates a new read-only [`Table`] by performing an INNER JOIN on two
+    /// source tables. The resulting table is reactive: when either source
+    /// table is updated, the join is automatically recomputed.
+    ///
+    /// # Arguments
+    ///
+    /// - `left` - The left source table (a [`Table`] instance or a table name
+    ///   string).
+    /// - `right` - The right source table (a [`Table`] instance or a table name
+    ///   string).
+    /// - `on` - The column name to join on. Must exist in both tables with the
+    ///   same type.
+    /// - `options` - Optional join configuration: `{ join_type?: "inner" |
+    ///   "left" | "outer", name?: string }`.
+    ///
+    /// # JavaScript Examples
+    ///
+    /// ```javascript
+    /// const joined = await client.join(orders_table, products_table, "Product ID", { join_type: "left" });
+    /// const joined = await client.join("orders", "products", "Product ID", { join_type: "left" });
+    /// ```
+    #[wasm_bindgen]
+    pub async fn join(
+        &self,
+        left: JsValue,
+        right: JsValue,
+        on: &str,
+        options: Option<JsJoinOptions>,
+    ) -> ApiResult<Table> {
+        let options = options
+            .into_serde_ext::<Option<perspective_client::JoinOptions>>()?
+            .unwrap_or_default();
+
+        let left_ref = js_to_table_ref(&left).await?;
+        let right_ref = js_to_table_ref(&right).await?;
+        Ok(Table(
+            self.client.join(left_ref, right_ref, on, options).await?,
+        ))
+    }
+
     /// Terminates this [`Client`], cleaning up any [`crate::View`] handles the
     /// [`Client`] has open as well as its callbacks.
     #[wasm_bindgen]

package/src/rust/generic_sql_model.rs

@@ -157,6 +157,22 @@ impl GenericSQLVirtualServerModel {
             .view_size(view_id)
             .map_err(|e| JsValue::from_str(&e.to_string()))
     }
+
+    /// Returns the SQL query to get the min and max values of a column.
+    #[wasm_bindgen(js_name = "viewGetMinMax")]
+    pub fn view_get_min_max(
+        &self,
+        view_id: &str,
+        column_name: &str,
+        config: JsValue,
+    ) -> Result<String, JsValue> {
+        let config: ViewConfig = serde_wasm_bindgen::from_value(config)
+            .map_err(|e| JsValue::from_str(&e.to_string()))?;
+
+        self.inner
+            .view_get_min_max(view_id, column_name, &config)
+            .map_err(|e| JsValue::from_str(&e.to_string()))
+    }
 }
 
 impl GenericSQLVirtualServerModel {

package/src/rust/lib.rs

@@ -59,11 +59,15 @@ export type * from "../../src/ts/ts-rs/SystemInfo.d.ts";
 export type * from "../../src/ts/ts-rs/SortDir.d.ts";
 export type * from "../../src/ts/ts-rs/Filter.d.ts";
 export type * from "../../src/ts/ts-rs/ViewConfig.d.ts";
+export type * from "../../src/ts/ts-rs/JoinOptions.ts";
+export type * from "../../src/ts/ts-rs/JoinType.ts";
 
 import type {ColumnWindow} from "../../src/ts/ts-rs/ColumnWindow.d.ts";
 import type {ColumnType} from "../../src/ts/ts-rs/ColumnType.d.ts";
 import type {ViewWindow} from "../../src/ts/ts-rs/ViewWindow.d.ts";
 import type {TableInitOptions} from "../../src/ts/ts-rs/TableInitOptions.d.ts";
+import type {JoinOptions} from "../../src/ts/ts-rs/JoinOptions.ts";
+import type {JoinType} from "../../src/ts/ts-rs/JoinType.ts";
 import type {ViewConfigUpdate} from "../../src/ts/ts-rs/ViewConfigUpdate.d.ts";
 import type * as on_update_args from "../../src/ts/ts-rs/ViewOnUpdateResp.d.ts";
 import type {OnUpdateOptions} from "../../src/ts/ts-rs/OnUpdateOptions.d.ts";

package/src/rust/utils/errors.rs

@@ -97,6 +97,9 @@ pub enum ApiErrorType {
     #[error("Invalid `expressions` {}", format_valid_exprs(.0))]
     InvalidViewerConfigExpressionsError(Rc<ExprValidationResult>),
 
+    #[error("Expected a Table or string table name")]
+    TableRefError,
+
     #[error("No `Table` attached")]
     NoTableError,
 
@@ -134,6 +137,7 @@ impl ApiError {
             ApiErrorType::ProstError(_) => "[ProstError]",
             ApiErrorType::InvalidViewerConfigError(..) => "[InvalidViewerConfigError]",
             ApiErrorType::InvalidViewerConfigExpressionsError(_) => "[InvalidViewerConfigError]",
+            ApiErrorType::TableRefError => "[TableRefError]",
             ApiErrorType::NoTableError => "[NoTableError]",
             ApiErrorType::SerdeWasmBindgenError(_) => "[SerdeWasmBindgenError]",
             ApiErrorType::Utf8Error(_) => "[FromUtf8Error]",

package/src/rust/utils/futures.rs

@@ -64,6 +64,10 @@ where
     pub fn spawn<U: Future<Output = ApiResult<T>> + 'static>(x: U) {
         drop(js_sys::Promise::from(Self::new(x)))
     }
+
+    pub fn spawn_throttled<U: Future<Output = ApiResult<T>> + 'static>(x: U) {
+        drop(js_sys::Promise::from(Self::new_throttled(x)))
+    }
 }
 
 impl<T> Default for ApiFuture<T>

package/src/rust/view.rs

@@ -47,6 +47,15 @@ impl From<ViewWindow> for JsViewWindow {
     }
 }
 
+fn scalar_to_jsvalue(scalar: &perspective_client::config::Scalar) -> JsValue {
+    match scalar {
+        perspective_client::config::Scalar::Float(x) => JsValue::from_f64(*x),
+        perspective_client::config::Scalar::String(x) => JsValue::from_str(x),
+        perspective_client::config::Scalar::Bool(x) => JsValue::from_bool(*x),
+        perspective_client::config::Scalar::Null => JsValue::NULL,
+    }
+}
+
 /// The [`View`] struct is Perspective's query and serialization interface. It
 /// represents a query on the `Table`'s dataset and is always created from an
 /// existing `Table` instance via the [`Table::view`] method.
@@ -147,10 +156,10 @@ impl View {
     #[wasm_bindgen]
     pub async fn get_min_max(&self, name: String) -> ApiResult<Array> {
         let result = self.0.get_min_max(name).await?;
-        Ok([result.0, result.1]
-            .iter()
-            .map(|x| js_sys::JSON::parse(x))
-            .collect::<Result<_, _>>()?)
+        let arr = Array::new();
+        arr.push(&scalar_to_jsvalue(&result.0));
+        arr.push(&scalar_to_jsvalue(&result.1));
+        Ok(arr)
     }
 
     /// The number of aggregated rows in this [`View`]. This is affected by the

package/src/rust/virtual_server.rs

@@ -18,7 +18,7 @@ use std::str::FromStr;
 use std::sync::{Arc, Mutex};
 
 use indexmap::IndexMap;
-use js_sys::{Array, Date, Object, Reflect};
+use js_sys::{Array, Date, Object, Reflect, Uint8Array};
 use perspective_client::proto::{ColumnType, HostedTable};
 use perspective_client::virtual_server;
 use perspective_client::virtual_server::{Features, ResultExt, VirtualServerHandler};
@@ -60,6 +60,20 @@ impl From<serde_wasm_bindgen::Error> for JsError {
     }
 }
 
+fn jsvalue_to_scalar(val: &JsValue) -> perspective_client::config::Scalar {
+    if val.is_null() || val.is_undefined() {
+        perspective_client::config::Scalar::Null
+    } else if let Some(b) = val.as_bool() {
+        perspective_client::config::Scalar::Bool(b)
+    } else if let Some(n) = val.as_f64() {
+        perspective_client::config::Scalar::Float(n)
+    } else if let Some(s) = val.as_string() {
+        perspective_client::config::Scalar::String(s)
+    } else {
+        perspective_client::config::Scalar::Null
+    }
+}
+
 pub struct JsServerHandler(Object);
 
 impl JsServerHandler {
@@ -452,6 +466,48 @@ impl VirtualServerHandler for JsServerHandler {
         })
     }
 
+    fn view_get_min_max(
+        &self,
+        view_id: &str,
+        column_name: &str,
+        config: &perspective_client::config::ViewConfig,
+    ) -> HandlerFuture<
+        Result<
+            (
+                perspective_client::config::Scalar,
+                perspective_client::config::Scalar,
+            ),
+            Self::Error,
+        >,
+    > {
+        let has_method = Reflect::get(&self.0, &JsValue::from_str("viewGetMinMax"))
+            .map(|val| !val.is_undefined())
+            .unwrap_or(false);
+
+        if !has_method {
+            return Box::pin(async {
+                Err(JsError(JsValue::from_str("viewGetMinMax not implemented")))
+            });
+        }
+
+        let handler = self.0.clone();
+        let view_id = view_id.to_string();
+        let column_name = column_name.to_string();
+        let config_js = serde_wasm_bindgen::to_value(config).unwrap();
+        Box::pin(async move {
+            let this = JsServerHandler(handler);
+            let args = Array::new();
+            args.push(&JsValue::from_str(&view_id));
+            args.push(&JsValue::from_str(&column_name));
+            args.push(&config_js);
+            let result = this.call_method_js_async("viewGetMinMax", &args).await?;
+            let obj = result.dyn_ref::<Object>().unwrap();
+            let min_val = Reflect::get(obj, &JsValue::from_str(wasm_bindgen::intern("min")))?;
+            let max_val = Reflect::get(obj, &JsValue::from_str(wasm_bindgen::intern("max")))?;
+            Ok((jsvalue_to_scalar(&min_val), jsvalue_to_scalar(&max_val)))
+        })
+    }
+
     fn view_get_data(
         &self,
         view_id: &str,
@@ -531,6 +587,17 @@ impl VirtualDataSlice {
         )
     }
 
+    #[wasm_bindgen(js_name = "fromArrowIpc")]
+    pub fn from_arrow_ipc(&self, ipc: Uint8Array) -> Result<(), JsValue> {
+        self.1
+            .lock()
+            .unwrap()
+            .as_mut()
+            .unwrap()
+            .from_arrow_ipc(&ipc.to_vec())
+            .map_err(|e| JsValue::from_str(&e.to_string()))
+    }
+
     #[wasm_bindgen(js_name = "setCol")]
     pub fn set_col(
         &self,

package/src/ts/perspective.node.ts

@@ -273,6 +273,23 @@ export function on_error(callback: Function) {
     return SYNC_CLIENT.on_error(callback);
 }
 
+/**
+ * Create a read-only table from a JOIN of two source tables.
+ * @param left - The left source table (a Table instance or a table name string).
+ * @param right - The right source table (a Table instance or a table name string).
+ * @param on
+ * @param options - Optional join configuration: { join_type?: "inner"|"left"|"outer", name?: string }
+ * @returns
+ */
+export function join(
+    left: perspective_client.Table | string,
+    right: perspective_client.Table | string,
+    on: string,
+    options?: perspective_client.JoinOptions,
+) {
+    return SYNC_CLIENT.join(left as any, right as any, on, options);
+}
+
 /**
  * Create a table from the global Perspective instance.
  * @param init_data
@@ -356,6 +373,7 @@ export { perspective_client as wasmModule };
 
 export default {
     table,
+    join,
     websocket,
     worker,
     get_hosted_table_names,

package/src/ts/ts-rs/JoinOptions.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 { JoinType } from "./JoinType.js";
+
+/**
+ * Options for [`Client::join`].
+ */
+export type JoinOptions = { join_type?: JoinType, name?: string, right_on?: string, };

package/src/ts/ts-rs/JoinType.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 JoinType = "inner" | "left" | "outer";

package/src/ts/virtual_server.ts

@@ -68,6 +68,11 @@ export interface VirtualServerHandler {
         tableId: string,
         expression: string,
     ): ColumnType | Promise<ColumnType>;
+    viewGetMinMax?(
+        viewId: string,
+        columnName: string,
+        config: ViewConfig,
+    ): { min: any; max: any } | Promise<{ min: any; max: any }>;
     getFeatures?(): ServerFeatures | Promise<ServerFeatures>;
     makeTable?(
         tableId: string,

package/src/ts/virtual_servers/clickhouse.ts

@@ -309,8 +309,6 @@ export class ClickhouseHandler implements perspective.VirtualServerHandler {
         viewport: ViewWindow,
         dataSlice: perspective.VirtualDataSlice,
     ) {
-        const is_group_by = config.group_by?.length > 0;
-        const is_split_by = config.split_by?.length > 0;
         const query = this.sqlBuilder.viewGetData(
             viewId,
             config,
@@ -323,23 +321,14 @@ export class ClickhouseHandler implements perspective.VirtualServerHandler {
         });
 
         for (let cidx = 0; cidx < columns.length; cidx++) {
-            if (cidx === 0 && is_group_by && !is_split_by) {
-                // This is the grouping_id column, skip it
-                continue;
-            }
-
-            let col = columns[cidx];
-            if (is_split_by && !col.startsWith("__ROW_PATH_")) {
-                col = col.replaceAll("_", "|");
-            }
-
+            const col = columns[cidx];
             const dtype = duckdbTypeToPsp(dtypes[cidx]) as ColumnType;
 
             const isDecimal = dtypes[cidx].startsWith("Decimal");
             for (let ridx = 0; ridx < rows.length; ridx++) {
                 const row = rows[ridx];
                 const grouping_id = row["__GROUPING_ID__"];
-                let value = row[columns[cidx]];
+                let value = row[col];
                 if (isDecimal) {
                     value = convertDecimalToNumber(value, dtypes[cidx]);
                 }

package/src/ts/virtual_servers/duckdb.ts

@@ -119,25 +119,6 @@ function duckdbTypeToPsp(name: string): ColumnType {
     return "string";
 }
 
-function convertDecimalToNumber(value: any, dtypeString: string) {
-    if (!(value instanceof Uint32Array || value instanceof Int32Array)) {
-        return value;
-    }
-
-    let bigIntValue = BigInt(0);
-    for (let i = 0; i < value.length; i++) {
-        bigIntValue |= BigInt(value[i]) << BigInt(i * 32);
-    }
-
-    const scaleMatch = dtypeString.match(/Decimal\[\d+e(\d+)\]/);
-    if (scaleMatch) {
-        const scale = parseInt(scaleMatch[1]);
-        return Number(bigIntValue) / Math.pow(10, scale);
-    } else {
-        return Number(bigIntValue);
-    }
-}
-
 async function runQuery(
     db: duckdb.AsyncDuckDBConnection,
     query: string,
@@ -290,6 +271,20 @@ export class DuckDBHandler implements perspective.VirtualServerHandler {
         await runQuery(this.db, query);
     }
 
+    async viewGetMinMax(
+        viewId: string,
+        columnName: string,
+        config: ViewConfig,
+    ) {
+        const query = this.sqlBuilder.viewGetMinMax(viewId, columnName, config);
+        const results = await runQuery(this.db, query);
+        const row = results[0].toJSON();
+        let [min, max] = Object.values(row);
+        if (typeof min === "bigint") min = Number(min);
+        if (typeof max === "bigint") max = Number(max);
+        return { min: min ?? null, max: max ?? null };
+    }
+
     async viewGetData(
         viewId: string,
         config: ViewConfig,
@@ -297,10 +292,6 @@ export class DuckDBHandler implements perspective.VirtualServerHandler {
         viewport: ViewWindow,
         dataSlice: perspective.VirtualDataSlice,
     ) {
-        const is_group_by = config.group_by?.length > 0;
-        const is_split_by = config.split_by?.length > 0;
-        const is_flat = config.group_rollup_mode === "flat";
-        const has_grouping_id = is_group_by && !is_flat;
         const query = this.sqlBuilder.viewGetData(
             viewId,
             config,
@@ -308,47 +299,10 @@ export class DuckDBHandler implements perspective.VirtualServerHandler {
             schema,
         );
 
-        const { rows, columns, dtypes } = await runQuery(this.db, query, {
-            columns: true,
-        });
-
-        for (let cidx = 0; cidx < columns.length; cidx++) {
-            if (cidx === 0 && has_grouping_id) {
-                // This is the grouping_id column, skip it
-                continue;
-            }
-
-            let col = columns[cidx];
-            if (is_split_by && !col.startsWith("__")) {
-                col = col.replaceAll("_", "|");
-            }
-
-            const dtype = duckdbTypeToPsp(dtypes[cidx]) as ColumnType;
-            const isDecimal = dtypes[cidx].startsWith("Decimal");
-            for (let ridx = 0; ridx < rows.length; ridx++) {
-                const rowArray = rows[ridx].toArray();
-                const grouping_id = has_grouping_id
-                    ? Number(rowArray[0])
-                    : undefined;
-                let value = rowArray[cidx];
-                if (isDecimal) {
-                    value = convertDecimalToNumber(value, dtypes[cidx]);
-                }
-
-                if (typeof value === "bigint") {
-                    value = Number(value);
-                }
-
-                if (typeof value !== "string" && dtype === "string") {
-                    try {
-                        value = JSON.stringify(value);
-                    } catch (e) {
-                        value = `${value}`;
-                    }
-                }
+        const ipc = await this.db.useUnsafe((bindings, conn) =>
+            bindings.runQuery(conn, query),
+        );
 
-                dataSlice.setCol(dtype, col, ridx, value, grouping_id);
-            }
-        }
+        dataSlice.fromArrowIpc(ipc);
     }
 }