@perspective-dev/client 4.2.0 → 4.4.0

package/dist/wasm/perspective-js.wasm.d.ts

@@ -12,6 +12,7 @@ export const client___getClassname: (a: number, b: number) => void;
 export const client_get_hosted_table_names: (a: number) => number;
 export const client_handle_error: (a: number, b: number, c: number, d: number) => number;
 export const client_handle_response: (a: number, b: number) => number;
+export const client_join: (a: number, b: number, c: number, d: number, e: number, f: number) => number;
 export const client_new: (a: number, b: number, c: number) => void;
 export const client_new_proxy_session: (a: number, b: number) => number;
 export const client_on_error: (a: number, b: number) => number;
@@ -30,6 +31,7 @@ export const genericsqlvirtualservermodel_tableValidateExpression: (a: number, b
 export const genericsqlvirtualservermodel_viewColumnSize: (a: number, b: number, c: number, d: number) => void;
 export const genericsqlvirtualservermodel_viewDelete: (a: number, b: number, c: number, d: number) => void;
 export const genericsqlvirtualservermodel_viewGetData: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => void;
+export const genericsqlvirtualservermodel_viewGetMinMax: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => void;
 export const genericsqlvirtualservermodel_viewSchema: (a: number, b: number, c: number, d: number) => void;
 export const genericsqlvirtualservermodel_viewSize: (a: number, b: number, c: number, d: number) => void;
 export const init: () => void;
@@ -78,6 +80,7 @@ export const view_to_csv: (a: number, b: number) => number;
 export const view_to_json: (a: number, b: number) => number;
 export const view_to_json_string: (a: number, b: number) => number;
 export const view_to_ndjson: (a: number, b: number) => number;
+export const virtualdataslice_fromArrowIpc: (a: number, b: number, c: number) => void;
 export const virtualdataslice_new: (a: number) => number;
 export const virtualdataslice_setBooleanCol: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => void;
 export const virtualdataslice_setCol: (a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number, i: number) => void;
@@ -87,11 +90,11 @@ export const virtualdataslice_setIntegerCol: (a: number, b: number, c: number, d
 export const virtualdataslice_setStringCol: (a: number, b: number, c: number, d: number, e: number, f: number, g: number) => void;
 export const virtualserver_handleRequest: (a: number, b: number, c: number) => number;
 export const virtualserver_new: (a: number, b: number) => void;
-export const __wasm_bindgen_func_elem_1421: (a: number, b: number) => void;
-export const __wasm_bindgen_func_elem_3793: (a: number, b: number) => void;
-export const __wasm_bindgen_func_elem_5384: (a: number, b: number, c: number, d: number) => void;
-export const __wasm_bindgen_func_elem_3795: (a: number, b: number, c: number) => void;
-export const __wasm_bindgen_func_elem_1668: (a: number, b: number) => number;
+export const __wasm_bindgen_func_elem_838: (a: number, b: number) => void;
+export const __wasm_bindgen_func_elem_3910: (a: number, b: number) => void;
+export const __wasm_bindgen_func_elem_10782: (a: number, b: number, c: number, d: number) => void;
+export const __wasm_bindgen_func_elem_3927: (a: number, b: number, c: number) => void;
+export const __wasm_bindgen_func_elem_1727: (a: number, b: number) => number;
 export const __wbindgen_export: (a: number, b: number) => number;
 export const __wbindgen_export2: (a: number, b: number, c: number, d: number) => number;
 export const __wbindgen_export3: (a: number) => void;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@perspective-dev/client",
-  "version": "4.2.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>
@@ -90,12 +94,7 @@ where
     Result<T, JsValue>: IntoJsResult + 'static,
 {
     fn from(fut: ApiFuture<T>) -> Self {
-        future_to_promise(async move {
-            match fut.0.await.ignore_view_delete()? {
-                Some(x) => Ok(x).into_js_result(),
-                None => Err("View not found".into()).into_js_result(),
-            }
-        })
+        future_to_promise(async move { Ok(fut.0.await?).into_js_result() })
     }
 }
 

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/GroupRollupMode.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 GroupRollupMode = "rollup" | "flat" | "total";

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/ts-rs/ViewConfig.ts

@@ -3,6 +3,7 @@ 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 { GroupRollupMode } from "./GroupRollupMode.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, };
+export type ViewConfig = { group_by: Array<string>, split_by: Array<string>, sort: Array<Sort>, filter: Array<Filter>, group_rollup_mode: GroupRollupMode, filter_op?: FilterReducer, expressions: Expressions, columns: Array<string | null>, aggregates: { [key in string]?: Aggregate }, group_by_depth?: number | null, };

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

@@ -3,6 +3,7 @@ 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 { GroupRollupMode } from "./GroupRollupMode.js";
 import type { Sort } from "./Sort.js";
 
 export type ViewConfigUpdate = { 
@@ -84,4 +85,4 @@ expressions?: Expressions,
  * 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, };
+aggregates?: { [key in string]?: Aggregate }, group_by_depth?: number, filter_op?: FilterReducer, group_rollup_mode?: GroupRollupMode, };

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

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

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

@@ -223,6 +223,7 @@ export class ClickhouseHandler implements perspective.VirtualServerHandler {
             split_by: false,
             sort: true,
             expressions: true,
+            group_rollup_mode: ["rollup", "flat", "total"],
             filter_ops: {
                 integer: FILTER_OPS,
                 float: FILTER_OPS,
@@ -308,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,
@@ -322,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]);
                 }