Client::join API

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

Author: texodus

rust/perspective-client/perspective.proto

@@ -157,6 +157,7 @@ message Request {
         TableUpdateReq table_update_req = 33;
         ViewOnDeleteReq view_on_delete_req = 34;
         ViewRemoveDeleteReq view_remove_delete_req = 35;
+        MakeJoinTableReq make_join_table_req = 38;
     }
 }
 
@@ -199,6 +200,7 @@ message Response {
         TableUpdateResp table_update_resp = 33;
         ViewOnDeleteResp view_on_delete_resp = 34;
         ViewRemoveDeleteResp view_remove_delete_resp = 35;
+        MakeJoinTableResp make_join_table_resp = 38;
         ServerError server_error = 50;
     }
 }
@@ -335,6 +337,14 @@ message MakeTableReq {
 }
 message MakeTableResp {}
 
+// `Client::join` — create a read-only table from an INNER JOIN of two tables.
+message MakeJoinTableReq {
+    string left_table_id = 1;
+    string right_table_id = 2;
+    string on_column = 3;
+}
+message MakeJoinTableResp {}
+
 // `Table::delete`
 message TableDeleteReq { 
     bool is_immediate = 1; 

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

@@ -26,8 +26,8 @@ use crate::proto::request::ClientReq;
 use crate::proto::response::ClientResp;
 use crate::proto::{
     ColumnType, GetFeaturesReq, GetFeaturesResp, GetHostedTablesReq, GetHostedTablesResp,
-    HostedTable, MakeTableReq, RemoveHostedTablesUpdateReq, Request, Response, ServerError,
-    ServerSystemInfoReq,
+    HostedTable, MakeJoinTableReq, MakeTableReq, RemoveHostedTablesUpdateReq, Request, Response,
+    ServerError, ServerSystemInfoReq,
 };
 use crate::table::{Table, TableInitOptions, TableOptions};
 use crate::table_data::{TableData, UpdateData};
@@ -589,6 +589,45 @@ 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.
+    ///
+    /// # Arguments
+    ///
+    /// * `left` - The left source table.
+    /// * `right` - The right source table.
+    /// * `on` - The column name to join on. Must exist in both tables with the
+    ///   same type.
+    /// * `name` - Optional name for the resulting table.
+    pub async fn join(
+        &self,
+        left: &Table,
+        right: &Table,
+        on: &str,
+        name: Option<String>,
+    ) -> ClientResult<Table> {
+        let entity_id = name.unwrap_or_else(randid);
+        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(),
+                on_column: on.to_owned(),
+            })),
+        };
+
+        let client = self.clone();
+        match self.oneshot(&msg).await? {
+            ClientResp::MakeJoinTableResp(_) => Ok(Table::new(entity_id, client, TableOptions {
+                index: Some(on.to_owned()),
+                limit: None,
+            })),
+            resp => Err(resp.into()),
+        }
+    }
+
     async fn get_table_infos(&self) -> ClientResult<Vec<HostedTable>> {
         let msg = Request {
             msg_id: self.gen_id(),

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

@@ -382,6 +382,34 @@ 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.
+    /// - `right` - The right source table.
+    /// - `on` - The column name to join on. Must exist in both tables with the
+    ///   same type.
+    /// - `name` - Optional name for the resulting table.
+    ///
+    /// # JavaScript Examples
+    ///
+    /// ```javascript
+    /// const joined = await client.join(orders_table, products_table, "Product ID");
+    /// ```
+    #[wasm_bindgen]
+    pub async fn join(
+        &self,
+        left: &Table,
+        right: &Table,
+        on: &str,
+        name: Option<String>,
+    ) -> ApiResult<Table> {
+        Ok(Table(self.client.join(&left.0, &right.0, on, name).await?))
+    }
+
     /// Terminates this [`Client`], cleaning up any [`crate::View`] handles the
     /// [`Client`] has open as well as its callbacks.
     #[wasm_bindgen]

rust/perspective-js/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 an INNER JOIN of two source tables.
+ * @param left
+ * @param right
+ * @param on
+ * @param name
+ * @returns
+ */
+export function join(
+    left: perspective_client.Table,
+    right: perspective_client.Table,
+    on: string,
+    name?: string,
+) {
+    return SYNC_CLIENT.join(left, right, on, name);
+}
+
 /**
  * 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,