Outer and Left joins

Signed-off-by: Andrew Stein <steinlink@gmail.com>

Author: texodus

rust/metadata/main.rs

@@ -32,8 +32,8 @@ use std::fs;
 
 use perspective_client::config::*;
 use perspective_client::{
-    ColumnWindow, DeleteOptions, OnUpdateData, OnUpdateOptions, SystemInfo, TableInitOptions,
-    UpdateOptions, ViewWindow,
+    ColumnWindow, DeleteOptions, JoinOptions, OnUpdateData, OnUpdateOptions, SystemInfo,
+    TableInitOptions, UpdateOptions, ViewWindow,
 };
 use perspective_viewer::config::ViewerConfigUpdate;
 use ts_rs::TS;
@@ -71,6 +71,7 @@ pub fn generate_type_bindings_js() -> Result<(), Box<dyn Error>> {
     ViewConfigUpdate::export_all_to(&path)?;
     OnUpdateData::export_all_to(&path)?;
     OnUpdateOptions::export_all_to(&path)?;
+    JoinOptions::export_all_to(&path)?;
     UpdateOptions::export_all_to(&path)?;
     DeleteOptions::export_all_to(&path)?;
     ViewWindow::export_all_to(&path)?;

rust/perspective-client/build.rs

@@ -57,6 +57,10 @@ fn prost_build() -> Result<()> {
             .field_attribute("ViewOnUpdateResp.delta", "#[ts(as = \"Vec::<u8>\")]")
             .field_attribute("ViewOnUpdateResp.delta", "#[serde(with = \"serde_bytes\")]")
             .type_attribute("ColumnType", "#[derive(ts_rs::TS)]")
+            .type_attribute(
+                "JoinType",
+                "#[derive(serde::Deserialize, ts_rs::TS)] #[serde(rename_all = \"snake_case\")]",
+            )
             .field_attribute("ViewToArrowResp.arrow", "#[serde(skip)]")
             .field_attribute("from_arrow", "#[serde(skip)]")
             .type_attribute(".", "#[derive(serde::Serialize)]")

rust/perspective-client/perspective.proto

@@ -337,11 +337,19 @@ message MakeTableReq {
 }
 message MakeTableResp {}
 
-// `Client::join` — create a read-only table from an INNER JOIN of two tables.
+enum JoinType {
+    INNER = 0;
+    LEFT = 1;
+    OUTER = 2;
+}
+
+// `Client::join` — create a read-only table from a JOIN of two tables.
 message MakeJoinTableReq {
     string left_table_id = 1;
     string right_table_id = 2;
     string on_column = 3;
+    JoinType join_type = 4;
+    string right_on_column = 5;
 }
 message MakeJoinTableResp {}
 

rust/perspective-client/src/rust/client.rs

@@ -26,11 +26,12 @@ use crate::proto::request::ClientReq;
 use crate::proto::response::ClientResp;
 use crate::proto::{
     ColumnType, GetFeaturesReq, GetFeaturesResp, GetHostedTablesReq, GetHostedTablesResp,
-    HostedTable, MakeJoinTableReq, MakeTableReq, RemoveHostedTablesUpdateReq, Request, Response,
-    ServerError, ServerSystemInfoReq,
+    HostedTable, JoinType, MakeJoinTableReq, MakeTableReq, RemoveHostedTablesUpdateReq, Request,
+    Response, ServerError, ServerSystemInfoReq,
 };
-use crate::table::{Table, TableInitOptions, TableOptions};
+use crate::table::{JoinOptions, Table, TableInitOptions, TableOptions};
 use crate::table_data::{TableData, UpdateData};
+use crate::table_ref::TableRef;
 use crate::utils::*;
 use crate::view::{OnUpdateData, ViewWindow};
 use crate::{OnUpdateMode, OnUpdateOptions, asyncfn, clone};
@@ -589,32 +590,36 @@ impl Client {
         }
     }
 
-    /// Create 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.
+    /// Create a new read-only [`Table`] by performing a 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.
-    /// * `right` - The right source table.
+    /// * `left` - The left source table (as a [`Table`] or name string).
+    /// * `right` - The right source table (as a [`Table`] or name string).
     /// * `on` - The column name to join on. Must exist in both tables with the
     ///   same type.
-    /// * `name` - Optional name for the resulting table.
+    /// * `options` - Join configuration (join type, table name).
     pub async fn join(
         &self,
-        left: &Table,
-        right: &Table,
+        left: TableRef,
+        right: TableRef,
         on: &str,
-        name: Option<String>,
+        options: JoinOptions,
     ) -> ClientResult<Table> {
-        let entity_id = name.unwrap_or_else(randid);
+        let entity_id = options.name.unwrap_or_else(randid);
+        let join_type: JoinType = options.join_type.unwrap_or_default();
+        let right_on_column = options.right_on.unwrap_or_default();
         let msg = Request {
             msg_id: self.gen_id(),
             entity_id: entity_id.clone(),
             client_req: Some(ClientReq::MakeJoinTableReq(MakeJoinTableReq {
-                left_table_id: left.get_name().to_owned(),
-                right_table_id: right.get_name().to_owned(),
+                left_table_id: left.table_name().to_owned(),
+                right_table_id: right.table_name().to_owned(),
                 on_column: on.to_owned(),
+                join_type: join_type.into(),
+                right_on_column,
             })),
         };
 

rust/perspective-client/src/rust/lib.rs

@@ -38,6 +38,7 @@ mod client;
 mod session;
 mod table;
 mod table_data;
+mod table_ref;
 mod view;
 pub mod virtual_server;
 
@@ -51,11 +52,14 @@ pub mod utils;
 
 pub use crate::client::{Client, ClientHandler, Features, ReconnectCallback, SystemInfo};
 use crate::proto::HostedTable;
+pub use crate::proto::JoinType;
 pub use crate::session::{ProxySession, Session};
 pub use crate::table::{
-    DeleteOptions, ExprValidationResult, Table, TableInitOptions, TableReadFormat, UpdateOptions,
+    DeleteOptions, ExprValidationResult, JoinOptions, Table, TableInitOptions, TableReadFormat,
+    UpdateOptions,
 };
 pub use crate::table_data::{TableData, UpdateData};
+pub use crate::table_ref::TableRef;
 pub use crate::view::{
     ColumnWindow, OnUpdateData, OnUpdateMode, OnUpdateOptions, View, ViewWindow,
 };

rust/perspective-client/src/rust/table.rs

@@ -137,6 +137,22 @@ impl From<TableInitOptions> for TableOptions {
     }
 }
 
+/// Options for [`Client::join`].
+#[derive(Clone, Debug, Default, Serialize, Deserialize, TS)]
+pub struct JoinOptions {
+    #[serde(default)]
+    #[ts(optional)]
+    pub join_type: Option<crate::proto::JoinType>,
+
+    #[serde(default)]
+    #[ts(optional)]
+    pub name: Option<String>,
+
+    #[serde(default)]
+    #[ts(optional)]
+    pub right_on: Option<String>,
+}
+
 /// Options for [`Table::delete`].
 #[derive(Clone, Debug, Default, Deserialize, TS)]
 pub struct DeleteOptions {

rust/perspective-client/src/rust/table_ref.rs

@@ -0,0 +1,53 @@
+// ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+// ┃ ██████ ██████ ██████       █      █      █      █      █ █▄  ▀███ █       ┃
+// ┃ ▄▄▄▄▄█ █▄▄▄▄▄ ▄▄▄▄▄█  ▀▀▀▀▀█▀▀▀▀▀ █ ▀▀▀▀▀█ ████████▌▐███ ███▄  ▀█ █ ▀▀▀▀▀ ┃
+// ┃ █▀▀▀▀▀ █▀▀▀▀▀ █▀██▀▀ ▄▄▄▄▄ █ ▄▄▄▄▄█ ▄▄▄▄▄█ ████████▌▐███ █████▄   █ ▄▄▄▄▄ ┃
+// ┃ █      ██████ █  ▀█▄       █ ██████      █      ███▌▐███ ███████▄ █       ┃
+// ┣━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┫
+// ┃ 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). ┃
+// ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
+
+use crate::Table;
+
+/// A reference to a table, either by handle or by name.
+#[derive(Clone)]
+pub enum TableRef {
+    Table(Table),
+    Name(String),
+}
+
+impl TableRef {
+    pub fn table_name(&self) -> &str {
+        match self {
+            TableRef::Table(table) => table.get_name(),
+            TableRef::Name(name) => name,
+        }
+    }
+}
+
+impl From<&Table> for TableRef {
+    fn from(table: &Table) -> Self {
+        TableRef::Table(table.clone())
+    }
+}
+
+impl From<Table> for TableRef {
+    fn from(table: Table) -> Self {
+        TableRef::Table(table)
+    }
+}
+
+impl From<String> for TableRef {
+    fn from(name: String) -> Self {
+        TableRef::Name(name)
+    }
+}
+
+impl From<&str> for TableRef {
+    fn from(name: &str) -> Self {
+        TableRef::Name(name.to_owned())
+    }
+}

rust/perspective-js/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]
@@ -388,26 +417,38 @@ impl Client {
     ///
     /// # Arguments
     ///
-    /// - `left` - The left source table.
-    /// - `right` - The right source table.
+    /// - `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.
-    /// - `name` - Optional name for the resulting table.
+    /// - `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");
+    /// 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: &Table,
-        right: &Table,
+        left: JsValue,
+        right: JsValue,
         on: &str,
-        name: Option<String>,
+        options: Option<JsJoinOptions>,
     ) -> ApiResult<Table> {
-        Ok(Table(self.client.join(&left.0, &right.0, on, name).await?))
+        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

rust/perspective-js/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";

rust/perspective-js/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]",