Skip to main content

zero_client/
schema.rs

1//! A Zero schema's tables and columns (`packages/zero-types/src/schema.ts`),
2//! and the names they map to on the server
3//! (`packages/zero-types/src/name-mapper.ts`).
4
5use crate::ast::*;
6use crate::decode::{self, DecodeError, Reader, Result};
7use crate::json::{Object, Value};
8use crate::map::OrderedMap;
9use std::collections::{HashMap, HashSet};
10use std::fmt;
11
12crate::ast::string_enum!(
13    /// The type of a column value (`ValueType` in `schema-value.ts`).
14    ValueType { String = "string", Number = "number", Boolean = "boolean", Null = "null", Json = "json" }
15);
16
17/// A column (`SchemaValue`).
18#[derive(Clone, Debug, PartialEq)]
19pub struct Column {
20    pub type_: ValueType,
21    pub optional: bool,
22    pub server_name: Option<String>,
23}
24
25#[derive(Clone, Debug, PartialEq)]
26pub struct Table {
27    pub name: String,
28    pub server_name: Option<String>,
29    /// In declaration order.
30    pub columns: OrderedMap<Column>,
31    pub primary_key: Vec<String>,
32}
33
34crate::ast::string_enum!(
35    /// How many rows a relationship hop leads to.
36    Cardinality { One = "one", Many = "many" }
37);
38
39/// One hop of a relationship: from `source_field` of the table to
40/// `dest_field` of `dest_schema`.
41#[derive(Clone, Debug, PartialEq)]
42pub struct RelationshipHop {
43    pub source_field: Vec<String>,
44    pub dest_field: Vec<String>,
45    pub dest_schema: String,
46    pub cardinality: Cardinality,
47}
48
49/// A relationship: one hop, or two through a junction table.
50pub type Relationship = Vec<RelationshipHop>;
51
52/// The tables of a schema and their relationships, in declaration order.
53#[derive(Clone, Debug, PartialEq, Default)]
54pub struct Schema {
55    pub tables: OrderedMap<Table>,
56    /// By table, then by name.
57    pub relationships: OrderedMap<OrderedMap<Relationship>>,
58}
59
60impl Schema {
61    /// A schema in the JSON form JS's schema object has (`tables`, each with
62    /// `name`, `serverName`, `columns`, and `primaryKey`, and optionally
63    /// `relationships`).
64    pub fn from_json(v: &Value) -> Result<Schema> {
65        let r = Reader::new(v, "schema")?;
66        let tables = r.required("tables", |v| {
67            decode::record(v, |t| {
68                let t = Reader::new(t, "table")?;
69                Ok(Table {
70                    name: t.string("name")?,
71                    server_name: t.optional_string("serverName")?,
72                    columns: t
73                        .required("columns", |v| {
74                            decode::record(v, |c| {
75                                let c = Reader::new(c, "column")?;
76                                let ty = c.string("type")?;
77                                Ok(Column {
78                                    type_: ValueType::parse(&ty).ok_or_else(|| {
79                                        DecodeError::new(format!("Invalid type \"{ty}\""))
80                                            .at("type")
81                                    })?,
82                                    optional: c.optional_bool("optional")?.unwrap_or(false),
83                                    server_name: c.optional_string("serverName")?,
84                                })
85                            })
86                        })?
87                        .into_iter()
88                        .collect(),
89                    primary_key: t.required("primaryKey", decode::compound_key)?,
90                })
91            })
92        })?;
93        let relationships = r
94            .optional("relationships", |v| {
95                decode::record(v, |rels| {
96                    Ok(
97                        decode::record(rels, |hops| decode::array(hops, hop_from_json))?
98                            .into_iter()
99                            .collect::<OrderedMap<_>>(),
100                    )
101                })
102            })?
103            .unwrap_or_default();
104        Ok(Schema {
105            tables: tables.into_iter().collect(),
106            relationships: relationships.into_iter().collect(),
107        })
108    }
109
110    /// The schema zero-cache checks the client's against, with server names
111    /// (`clientSchemaFrom` in `packages/zero-schema/src/builder/schema-builder.ts`).
112    pub fn client_schema(&self) -> crate::protocol::ClientSchema {
113        use crate::protocol::{ClientSchema, ClientTable};
114        let tables = self
115            .tables
116            .iter()
117            .map(|(name, t)| {
118                let server = |c: &str| {
119                    t.columns
120                        .get(c)
121                        .and_then(|c| c.server_name.clone())
122                        .unwrap_or_else(|| c.to_owned())
123                };
124                let table = ClientTable {
125                    columns: t
126                        .columns
127                        .iter()
128                        .map(|(c, col)| (server(c), col.type_))
129                        .collect(),
130                    primary_key: t.primary_key.iter().map(|k| server(k)).collect(),
131                };
132                (t.server_name.clone().unwrap_or_else(|| name.clone()), table)
133            })
134            .collect();
135        ClientSchema { tables }.normalized()
136    }
137
138    /// The relationship `name` of `table`.
139    pub fn relationship(&self, table: &str, name: &str) -> Option<&Relationship> {
140        self.relationships.get(table)?.get(name)
141    }
142}
143
144fn hop_from_json(v: &Value) -> Result<RelationshipHop> {
145    let h = Reader::new(v, "relationship")?;
146    let cardinality = h.string("cardinality")?;
147    Ok(RelationshipHop {
148        source_field: h.required("sourceField", decode::strings)?,
149        dest_field: h.required("destField", decode::strings)?,
150        dest_schema: h.string("destSchema")?,
151        cardinality: Cardinality::parse(&cardinality).ok_or_else(|| {
152            DecodeError::new(format!("Invalid cardinality \"{cardinality}\"")).at("cardinality")
153        })?,
154    })
155}
156
157/// An unknown table or column met while mapping names.
158#[derive(Clone, Debug, PartialEq, Eq)]
159pub struct NameMappingError(pub String);
160
161impl fmt::Display for NameMappingError {
162    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
163        f.write_str(&self.0)
164    }
165}
166
167impl std::error::Error for NameMappingError {}
168
169type MapResult<T> = std::result::Result<T, NameMappingError>;
170
171struct Destination {
172    table_name: String,
173    columns: HashMap<String, String>,
174    all_columns_same: bool,
175    /// The source names of the table's `json` columns.
176    json_columns: HashSet<String>,
177}
178
179/// Maps table and column names between the client and the server
180/// (`NameMapper`).
181pub struct NameMapper {
182    tables: HashMap<String, Destination>,
183}
184
185impl NameMapper {
186    /// `clientToServer`.
187    pub fn client_to_server(schema: &Schema) -> Self {
188        Self::new(schema, true)
189    }
190
191    /// `serverToClient`.
192    pub fn server_to_client(schema: &Schema) -> Self {
193        Self::new(schema, false)
194    }
195
196    fn new(schema: &Schema, from_client: bool) -> Self {
197        let mut tables = HashMap::new();
198        for (name, table) in &schema.tables {
199            let mut all_columns_same = true;
200            let mut columns = HashMap::new();
201            let mut json_columns = HashSet::new();
202            for (column, c) in &table.columns {
203                let server = c.server_name.as_deref().unwrap_or(column);
204                if server != column {
205                    all_columns_same = false;
206                }
207                let (src, dst) = if from_client {
208                    (column.as_str(), server)
209                } else {
210                    (server, column.as_str())
211                };
212                columns.insert(src.to_owned(), dst.to_owned());
213                if c.type_ == ValueType::Json {
214                    json_columns.insert(src.to_owned());
215                }
216            }
217            let server_name = table.server_name.as_deref().unwrap_or(name);
218            let (src, dst) = if from_client {
219                (name.as_str(), server_name)
220            } else {
221                (server_name, name.as_str())
222            };
223            tables.insert(
224                src.to_owned(),
225                Destination {
226                    table_name: dst.to_owned(),
227                    columns,
228                    all_columns_same,
229                    json_columns,
230                },
231            );
232        }
233        NameMapper { tables }
234    }
235
236    fn table(&self, src: &str) -> MapResult<&Destination> {
237        self.tables
238            .get(src)
239            .ok_or_else(|| NameMappingError(format!("unknown table \"{src}\"")))
240    }
241
242    pub fn table_name(&self, src: &str) -> MapResult<String> {
243        Ok(self.table(src)?.table_name.clone())
244    }
245
246    pub fn column_name(&self, table: &str, src: &str) -> MapResult<String> {
247        self.table(table)?.columns.get(src).cloned().ok_or_else(|| {
248            NameMappingError(format!("unknown column \"{src}\" of \"{table}\" table"))
249        })
250    }
251
252    /// `jsonColumnName`: the column a JSON path reads, which must be a `json`
253    /// column. An unknown column fails the same way as a known one that
254    /// isn't json.
255    pub fn json_column_name(&self, table: &str, src: &str) -> MapResult<String> {
256        if !self.table(table)?.json_columns.contains(src) {
257            return Err(NameMappingError(format!(
258                "column \"{src}\" of \"{table}\" table is not a json column"
259            )));
260        }
261        self.column_name(table, src)
262    }
263
264    /// The mapped name of table `src`, or `None` for a table the schema
265    /// doesn't have.
266    pub fn table_name_if_known(&self, src: &str) -> Option<String> {
267        self.tables.get(src).map(|t| t.table_name.clone())
268    }
269
270    /// Renames the known columns of `table`; others keep their names.
271    pub fn columns(&self, table: &str, columns: &[String]) -> MapResult<Vec<String>> {
272        let dest = self.table(table)?;
273        Ok(columns
274            .iter()
275            .map(|c| dest.columns.get(c).unwrap_or(c).clone())
276            .collect())
277    }
278
279    fn column_names(&self, table: &str, columns: &[String]) -> MapResult<Vec<String>> {
280        columns.iter().map(|c| self.column_name(table, c)).collect()
281    }
282
283    /// Renames the known columns of `row`; others keep their names.
284    pub fn row(&self, table: &str, row: &Object) -> MapResult<Object> {
285        let dest = self.table(table)?;
286        if dest.all_columns_same {
287            return Ok(row.clone());
288        }
289        Ok(row
290            .iter()
291            .map(|(c, v)| (dest.columns.get(c).unwrap_or(c).clone(), v.clone()))
292            .collect())
293    }
294
295    /// `mapAST`: the AST with its table and column names mapped.
296    pub fn map(&self, ast: &Ast) -> MapResult<Ast> {
297        let mut out = ast.clone();
298        out.table = self.table_name(&ast.table)?;
299        out.where_ = ast
300            .where_
301            .as_ref()
302            .map(|w| self.map_condition(w, &ast.table))
303            .transpose()?;
304        if let Some(related) = &ast.related {
305            let mut mapped = Vec::with_capacity(related.len());
306            for r in related {
307                let mut r2 = r.clone();
308                r2.correlation =
309                    self.map_correlation(&r.correlation, &ast.table, &r.subquery.table)?;
310                r2.subquery = Box::new(self.map(&r.subquery)?);
311                // A junction aggregate's field is a column of the destination.
312                let field_table = r
313                    .subquery
314                    .related
315                    .as_ref()
316                    .and_then(|rel| rel.first())
317                    .map_or(&r.subquery.table, |j| &j.subquery.table);
318                r2.aggregate = r
319                    .aggregate
320                    .as_ref()
321                    .map(|a| self.map_aggregate(a, field_table))
322                    .transpose()?;
323                mapped.push(r2);
324            }
325            out.related = Some(mapped);
326        }
327        if let Some(start) = &ast.start {
328            let mut row = Object::new();
329            for (column, value) in &start.row {
330                row.insert(self.column_name(&ast.table, column)?, value.clone());
331            }
332            out.start = Some(Bound {
333                row,
334                exclusive: start.exclusive,
335            });
336        }
337        if let Some(order_by) = &ast.order_by {
338            out.order_by = Some(
339                order_by
340                    .iter()
341                    .map(|p| {
342                        Ok(OrderPart {
343                            field: self.column_name(&ast.table, &p.field)?,
344                            direction: p.direction,
345                        })
346                    })
347                    .collect::<MapResult<_>>()?,
348            );
349        }
350        out.aggregate = ast
351            .aggregate
352            .as_ref()
353            .map(|a| self.map_aggregate(a, &ast.table))
354            .transpose()?;
355        out.group_by = ast
356            .group_by
357            .as_ref()
358            .map(|g| self.column_names(&ast.table, g))
359            .transpose()?;
360        Ok(out)
361    }
362
363    /// `transformAggregate`: the field maps, and must be a `json` column when
364    /// there is a path; the path is data.
365    fn map_aggregate(&self, a: &Aggregate, table: &str) -> MapResult<Aggregate> {
366        let mut out = Aggregate::new(a.fn_);
367        if let Some(distinct) = &a.distinct {
368            out.distinct = Some(self.column_names(table, distinct)?);
369        } else if let Some(field) = &a.field {
370            match &a.path {
371                None => out.field = Some(self.column_name(table, field)?),
372                Some(path) => {
373                    out.field = Some(self.json_column_name(table, field)?);
374                    out.path = Some(path.clone());
375                }
376            }
377        }
378        Ok(out)
379    }
380
381    /// `mapCondition`. Only the left side of a comparison names a column.
382    pub fn map_condition(&self, condition: &Condition, table: &str) -> MapResult<Condition> {
383        Ok(match condition {
384            Condition::Simple { op, left, right } => {
385                let left = match left {
386                    ValuePosition::Column(name) => {
387                        ValuePosition::Column(self.column_name(table, name)?)
388                    }
389                    ValuePosition::Json { column, path } => ValuePosition::Json {
390                        column: self.json_column_name(table, column)?,
391                        path: path.clone(),
392                    },
393                    _ => return Ok(condition.clone()),
394                };
395                Condition::Simple {
396                    op: *op,
397                    left,
398                    right: right.clone(),
399                }
400            }
401            Condition::CorrelatedSubquery {
402                related,
403                op,
404                flip,
405                scalar,
406            } => {
407                let mut related = related.clone();
408                related.correlation =
409                    self.map_correlation(&related.correlation, table, &related.subquery.table)?;
410                related.subquery = Box::new(self.map(&related.subquery)?);
411                Condition::CorrelatedSubquery {
412                    related,
413                    op: *op,
414                    flip: *flip,
415                    scalar: *scalar,
416                }
417            }
418            Condition::And(c) => Condition::And(
419                c.iter()
420                    .map(|c| self.map_condition(c, table))
421                    .collect::<MapResult<_>>()?,
422            ),
423            Condition::Or(c) => Condition::Or(
424                c.iter()
425                    .map(|c| self.map_condition(c, table))
426                    .collect::<MapResult<_>>()?,
427            ),
428        })
429    }
430
431    fn map_correlation(
432        &self,
433        c: &Correlation,
434        parent: &str,
435        child: &str,
436    ) -> MapResult<Correlation> {
437        Ok(Correlation {
438            parent_field: self.column_names(parent, &c.parent_field)?,
439            child_field: self.column_names(child, &c.child_field)?,
440        })
441    }
442}