More strictly type JSON APIs.

Author: ignatz

docs/src/content/docs/reference/benchmarks.mdx

@@ -22,7 +22,7 @@ alternatives such as SupaBase, PocketBase, and vanilla SQLite.
 
 ## Disclaimer
 
-In general, benchmarks are tricky, both to do well and to interpret.
+Generally benchmarks are tricky, both to do well and to interpret.
 Benchmarks never show how fast something can theoretically go but merely how
 fast the author managed to make it go.
 Micro-benchmarks, especially, offer a selective key-hole insights, which may be

trailbase-core/bindings/InsertRowRequest.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 { JsonValue } from "./serde_json/JsonValue";
+
+export type InsertRowRequest = { 
+/**
+ * Row data, which is expected to be a map from column name to value.
+ */
+row: { [key in string]?: JsonValue }, };

trailbase-core/bindings/UpdateRowRequest.ts

@@ -1,10 +1,11 @@
 // This file was generated by [ts-rs](https://github.com/Aleph-Alpha/ts-rs). Do not edit this file manually.
+import type { JsonValue } from "./serde_json/JsonValue";
 
 export type UpdateRowRequest = { primary_key_column: string, primary_key_value: Object, 
 /**
- * This is expected to be a map from column name to value.
+ * Row data, which is expected to be a map from column name to value.
  *
- * Note that using an array here wouldn't make sense. The map allows for sparseness and only
- * updating specific cells.
+ * Note that the row is represented as a map to allow selective cells as opposed to
+ * Vec<serde_json::Value>. Absence is different from setting a column to NULL.
  */
-row: { [key: string]: Object | undefined }, };
+row: { [key in string]?: JsonValue }, };

trailbase-core/bindings/serde_json/JsonValue.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 JsonValue = number | string | Array<JsonValue> | { [key in string]?: JsonValue };

trailbase-core/src/admin/rows/delete_rows.rs

@@ -102,11 +102,12 @@ mod tests {
   use trailbase_sqlite::query_one_row;
 
   use super::*;
-  use crate::admin::rows::insert_row::insert_row_handler;
+  use crate::admin::rows::insert_row::insert_row;
   use crate::admin::rows::list_rows::list_rows_handler;
   use crate::admin::rows::update_row::{update_row_handler, UpdateRowRequest};
   use crate::admin::table::{create_table_handler, CreateTableRequest};
   use crate::app_state::*;
+  use crate::records::test_utils::json_row_from_value;
   use crate::schema::{Column, ColumnDataType, ColumnOption, Table};
   use crate::util::{b64_to_uuid, uuid_to_b64};
 
@@ -152,12 +153,13 @@ mod tests {
     .unwrap();
 
     let insert = |value: &str| {
-      insert_row_handler(
-        State(state.clone()),
-        Path(table_name.clone()),
-        Json(serde_json::json!({
+      insert_row(
+        &state,
+        table_name.clone(),
+        json_row_from_value(serde_json::json!({
           "col0": value,
-        })),
+        }))
+        .unwrap(),
       )
     };
 
@@ -171,12 +173,12 @@ mod tests {
     };
 
     let id0 = {
-      let Json(row) = insert("row0").await.unwrap();
+      let row = insert("row0").await.unwrap();
       assert_eq!(&row[1], "row0");
       get_id(row)
     };
     let id1 = {
-      let Json(row) = insert("row1").await.unwrap();
+      let row = insert("row1").await.unwrap();
       assert_eq!(&row[1], "row1");
       get_id(row)
     };
@@ -198,9 +200,10 @@ mod tests {
       Json(UpdateRowRequest {
         primary_key_column: pk_col.clone(),
         primary_key_value: serde_json::Value::String(uuid_to_b64(&id0)),
-        row: serde_json::json!({
+        row: json_row_from_value(serde_json::json!({
           "col0": updated_value.to_string(),
-        }),
+        }))
+        .unwrap(),
       }),
     )
     .await

trailbase-core/src/admin/rows/insert_row.rs

@@ -1,34 +1,41 @@
 use axum::extract::{Path, State};
 use axum::Json;
+use serde::{Deserialize, Serialize};
+use ts_rs::TS;
 
 use crate::admin::AdminError as Error;
 use crate::app_state::AppState;
-use crate::records::json_to_sql::{InsertQueryBuilder, Params};
+use crate::records::json_to_sql::{InsertQueryBuilder, JsonRow, Params};
 use crate::records::sql_to_json::row_to_json_array;
 
-type Row = Vec<serde_json::Value>;
+#[derive(Debug, Serialize, Deserialize, Default, TS)]
+#[ts(export)]
+pub struct InsertRowRequest {
+  /// Row data, which is expected to be a map from column name to value.
+  pub row: JsonRow,
+}
 
 pub async fn insert_row_handler(
   State(state): State<AppState>,
   Path(table_name): Path<String>,
-  Json(request): Json<serde_json::Value>,
-) -> Result<Json<Row>, Error> {
-  let row = insert_row(&state, table_name, request).await?;
-  return Ok(Json(row));
+  Json(request): Json<InsertRowRequest>,
+) -> Result<(), Error> {
+  let _row = insert_row(&state, table_name, request.row).await?;
+  return Ok(());
 }
 
-pub async fn insert_row(
+pub(crate) async fn insert_row(
   state: &AppState,
   table_name: String,
-  value: serde_json::Value,
-) -> Result<Row, Error> {
+  json_row: JsonRow,
+) -> Result<Vec<serde_json::Value>, Error> {
   let Some(table_metadata) = state.table_metadata().get(&table_name) else {
     return Err(Error::Precondition(format!("Table {table_name} not found")));
   };
 
   let row = InsertQueryBuilder::run(
     state,
-    Params::from(&table_metadata, value, None)?,
+    Params::from(&table_metadata, json_row, None)?,
     None,
     Some("*"),
   )

trailbase-core/src/admin/rows/update_row.rs

@@ -5,7 +5,9 @@ use ts_rs::TS;
 
 use crate::admin::AdminError as Error;
 use crate::app_state::AppState;
-use crate::records::json_to_sql::{simple_json_value_to_param, Params, UpdateQueryBuilder};
+use crate::records::json_to_sql::{
+  simple_json_value_to_param, JsonRow, Params, UpdateQueryBuilder,
+};
 
 #[derive(Debug, Serialize, Deserialize, Default, TS)]
 #[ts(export)]
@@ -15,12 +17,11 @@ pub struct UpdateRowRequest {
   #[ts(type = "Object")]
   pub primary_key_value: serde_json::Value,
 
-  /// This is expected to be a map from column name to value.
+  /// Row data, which is expected to be a map from column name to value.
   ///
-  /// Note that using an array here wouldn't make sense. The map allows for sparseness and only
-  /// updating specific cells.
-  #[ts(type = "{ [key: string]: Object | undefined }")]
-  pub row: serde_json::Value,
+  /// Note that the row is represented as a map to allow selective cells as opposed to
+  /// Vec<serde_json::Value>. Absence is different from setting a column to NULL.
+  pub row: JsonRow,
 }
 
 pub async fn update_row_handler(

trailbase-core/src/records/create_record.rs

@@ -7,7 +7,7 @@ use utoipa::{IntoParams, ToSchema};
 use crate::app_state::AppState;
 use crate::auth::user::User;
 use crate::extract::Either;
-use crate::records::json_to_sql::{InsertQueryBuilder, LazyParams};
+use crate::records::json_to_sql::{InsertQueryBuilder, JsonRow, LazyParams};
 use crate::records::{Permission, RecordError};
 use crate::schema::ColumnDataType;
 
@@ -27,6 +27,7 @@ pub struct CreateRecordResponse {
   post,
   path = "/:name",
   params(CreateRecordQuery),
+  request_body = serde_json::Value,
   responses(
     (status = 200, description = "Record id of successful insertion.", body = CreateRecordResponse),
   )
@@ -36,7 +37,7 @@ pub async fn create_record_handler(
   Path(api_name): Path<String>,
   Query(create_record_query): Query<CreateRecordQuery>,
   user: Option<User>,
-  either_request: Either<serde_json::Value>,
+  either_request: Either<JsonRow>,
 ) -> Result<Response, RecordError> {
   let Some(api) = state.lookup_record_api(&api_name) else {
     return Err(RecordError::ApiNotFound);
@@ -184,7 +185,7 @@ mod test {
         Path("messages_api".to_string()),
         Query(CreateRecordQuery::default()),
         User::from_auth_token(&state, &user_x_token.auth_token),
-        Either::Json(json),
+        Either::Json(json_row_from_value(json).unwrap()),
       )
       .await;
       assert!(response.is_ok(), "{response:?}");
@@ -202,7 +203,7 @@ mod test {
         Path("messages_api".to_string()),
         Query(CreateRecordQuery::default()),
         User::from_auth_token(&state, &user_x_token.auth_token),
-        Either::Json(json),
+        Either::Json(json_row_from_value(json).unwrap()),
       )
       .await;
       assert!(response.is_err(), "{response:?}");
@@ -219,7 +220,7 @@ mod test {
         Path("messages_api".to_string()),
         Query(CreateRecordQuery::default()),
         User::from_auth_token(&state, &user_y_token.auth_token),
-        Either::Json(json),
+        Either::Json(json_row_from_value(json).unwrap()),
       )
       .await;
       assert!(response.is_err(), "{response:?}");
@@ -275,7 +276,7 @@ mod test {
         Path("messages_api".to_string()),
         Query(CreateRecordQuery::default()),
         User::from_auth_token(&state, &user_x_token.auth_token),
-        Either::Json(json),
+        Either::Json(json_row_from_value(json).unwrap()),
       )
       .await;
       assert!(response.is_ok(), "{response:?}");

trailbase-core/src/records/delete_record.rs

@@ -165,7 +165,7 @@ mod test {
       Path("messages_api".to_string()),
       Query(CreateRecordQuery::default()),
       User::from_auth_token(state, auth_token),
-      Either::Json(create_json),
+      Either::Json(json_row_from_value(create_json).unwrap()),
     )
     .await;
 

trailbase-core/src/records/json_to_sql.rs

@@ -107,6 +107,9 @@ impl From<crate::records::files::FileError> for QueryError {
 
 type FileMetadataContents = Vec<(FileUpload, Vec<u8>)>;
 
+// JSON type use to represent rows. Note that we use a map to represent rows sparsely.
+pub type JsonRow = serde_json::Map<String, serde_json::Value>;
+
 #[derive(Default)]
 pub struct Params {
   table_name: String,
@@ -149,19 +152,15 @@ impl Params {
   /// value itself in contrast to when the original request was an actual JSON request.
   pub fn from(
     metadata: &TableMetadata,
-    json: serde_json::Value,
+    json: JsonRow,
     multipart_files: Option<Vec<FileUploadInput>>,
   ) -> Result<Self, ParamsError> {
-    let serde_json::Value::Object(map) = json else {
-      return Err(ParamsError::NotAnObject);
-    };
-
     let mut params = Params {
       table_name: metadata.name().to_string(),
       ..Default::default()
     };
 
-    for (key, value) in map {
+    for (key, value) in json {
       // We simply skip unknown columns, this could simply be malformed input or version skew. This
       // is similar in spirit to protobuf's unknown fields behavior.
       let Some((col, col_meta)) = Self::column_by_name(metadata, &key) else {
@@ -836,7 +835,7 @@ fn extract_params_and_files_from_json(
 /// streams at all.
 pub struct LazyParams<'a> {
   // Input
-  request: serde_json::Value,
+  json_row: JsonRow,
   metadata: &'a TableMetadata,
   multipart_files: Option<Vec<FileUploadInput>>,
 
@@ -847,11 +846,11 @@ pub struct LazyParams<'a> {
 impl<'a> LazyParams<'a> {
   pub fn new(
     metadata: &'a TableMetadata,
-    request: serde_json::Value,
+    json_row: JsonRow,
     multipart_files: Option<Vec<FileUploadInput>>,
   ) -> Self {
     LazyParams {
-      request,
+      json_row,
       metadata,
       multipart_files,
       params: None,
@@ -863,20 +862,20 @@ impl<'a> LazyParams<'a> {
       return params.as_ref().map_err(|err| err.clone());
     }
 
-    let request = std::mem::take(&mut self.request);
+    let json_row = std::mem::take(&mut self.json_row);
     let multipart_files = std::mem::take(&mut self.multipart_files);
 
     let params = self
       .params
-      .insert(Params::from(self.metadata, request, multipart_files));
+      .insert(Params::from(self.metadata, json_row, multipart_files));
     return params.as_ref().map_err(|err| err.clone());
   }
 
   pub fn consume(self) -> Result<Params, ParamsError> {
     if let Some(params) = self.params {
       return params;
     }
-    return Params::from(self.metadata, self.request, self.multipart_files);
+    return Params::from(self.metadata, self.json_row, self.multipart_files);
   }
 }
 
@@ -887,6 +886,7 @@ mod tests {
   use serde_json::json;
 
   use super::*;
+  use crate::records::test_utils::json_row_from_value;
   use crate::schema::Table;
   use crate::table_metadata::{sqlite3_parse_into_statement, TableMetadata};
   use crate::util::id_to_b64;
@@ -980,7 +980,11 @@ mod tests {
         "real": real,
       });
 
-      assert_params(Params::from(&metadata, value, None)?);
+      assert_params(Params::from(
+        &metadata,
+        json_row_from_value(value).unwrap(),
+        None,
+      )?);
     }
 
     {
@@ -993,7 +997,11 @@ mod tests {
         "real": "3",
       });
 
-      assert_params(Params::from(&metadata, value, None)?);
+      assert_params(Params::from(
+        &metadata,
+        json_row_from_value(value).unwrap(),
+        None,
+      )?);
     }
 
     {
@@ -1007,7 +1015,7 @@ mod tests {
         "real": "3",
       });
 
-      assert!(Params::from(&metadata, value, None).is_err());
+      assert!(Params::from(&metadata, json_row_from_value(value).unwrap(), None).is_err());
 
       // Test that nested JSON object can be passed.
       let value = json!({
@@ -1021,7 +1029,7 @@ mod tests {
         "real": "3",
       });
 
-      let params = Params::from(&metadata, value, None).unwrap();
+      let params = Params::from(&metadata, json_row_from_value(value).unwrap(), None).unwrap();
       assert_params(params);
     }
 
@@ -1034,7 +1042,7 @@ mod tests {
         "real": "3",
       });
 
-      assert!(Params::from(&metadata, value, None).is_err());
+      assert!(Params::from(&metadata, json_row_from_value(value).unwrap(), None).is_err());
 
       // Test that nested JSON array can be passed.
       let nested_json_blob: Vec<u8> = vec![65, 66, 67, 68];
@@ -1051,7 +1059,7 @@ mod tests {
         "real": "3",
       });
 
-      let params = Params::from(&metadata, value, None).unwrap();
+      let params = Params::from(&metadata, json_row_from_value(value).unwrap(), None).unwrap();
 
       let json_col: Vec<libsql::Value> = params
         .params