Skip to main content

zero_client/
keys.rs

1//! Storage keys (`packages/zero-client/src/client/keys.ts`) and the names of
2//! synthetic aggregate tables.
3
4use crate::hash::xxhash32;
5use crate::json::{Object, Value, number, stringify};
6use std::fmt;
7
8pub const DESIRED_QUERIES_PREFIX: &str = "d/";
9pub const GOT_QUERIES_PREFIX: &str = "g/";
10pub const ENTITIES_PREFIX: &str = "e/";
11/// Synced aggregate rows live outside `e/`, which a client from before them
12/// loads into its schema's tables: both can share a database.
13pub const AGGREGATES_PREFIX: &str = "a/";
14pub const MUTATIONS_PREFIX: &str = "m/";
15/// The row-version column the server stamps on synced rows; not part of an
16/// aggregate row's key.
17pub const ROW_VERSION_COLUMN: &str = "_0_version";
18
19/// The prefix of every synthetic aggregate table's name.
20pub const AGGREGATE_TABLE_PREFIX: &str = "aggregate:";
21
22/// The columns of an aggregate's rows.
23pub mod aggregate_columns {
24    /// The aggregate's result. A view shows it as the bare value.
25    pub const VALUE: &str = "_0_value";
26    /// The constant key of a top-level aggregate's single row.
27    pub const KEY: &str = "_0_key";
28    /// A sum or average's running sum and count of non-null values.
29    pub const SUM: &str = "_0_sum";
30    pub const COUNT: &str = "_0_count";
31    /// A grouped sum or average's number of rows, nulls included.
32    pub const ROWS: &str = "_0_rows";
33    /// The payload columns, which aren't part of a row's key.
34    pub const PAYLOAD: [&str; 4] = [VALUE, SUM, COUNT, ROWS];
35}
36
37/// A primary key column whose value isn't a string, number, or boolean.
38#[derive(Clone, Debug, PartialEq)]
39pub struct InvalidPrimaryKeyValue {
40    pub column: String,
41    pub value: Option<Value>,
42}
43
44impl fmt::Display for InvalidPrimaryKeyValue {
45    /// valita's message for `primaryKeyValueSchema`, which JS throws as a
46    /// `TypeError`.
47    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
48        write!(
49            f,
50            "Expected string, number or boolean. Got {}",
51            valita_display(self.value.as_ref())
52        )
53    }
54}
55
56impl std::error::Error for InvalidPrimaryKeyValue {}
57
58/// `toDisplay` in valita.ts: how its messages show a value.
59pub fn valita_display(v: Option<&Value>) -> String {
60    match v {
61        None => "undefined".into(),
62        Some(Value::Null) => "null".into(),
63        Some(Value::Array(_)) => "array".into(),
64        Some(Value::Object(_)) => "object".into(),
65        Some(v) => stringify(v),
66    }
67}
68
69/// `toPrimaryKeyString`: `e/<table>/<id>`. A single-column key is the value
70/// as JS `String()` prints it; a compound key is the decimal `h128` of the
71/// JSON array of its values.
72pub fn primary_key_string(
73    table: &str,
74    primary_key: &[impl AsRef<str>],
75    row: &Object,
76) -> Result<String, InvalidPrimaryKeyValue> {
77    key_string(ENTITIES_PREFIX, table, primary_key, row)
78}
79
80/// `aggregateRowKey`: `a/`, the table name without its `aggregate:`, and the
81/// row's key, from [`aggregate_row_key_columns`]. A `put`'s full row, a
82/// `del`'s key, and an optimistic delta all give the same key.
83pub fn aggregate_row_key(table: &str, row: &Object) -> Result<String, InvalidPrimaryKeyValue> {
84    let columns = aggregate_row_key_columns(table, row.keys());
85    let name = table.strip_prefix(AGGREGATE_TABLE_PREFIX).unwrap_or(table);
86    key_string(AGGREGATES_PREFIX, name, &columns, row)
87}
88
89/// `aggregateRowKeyColumns`: `_0_key` for a top-level aggregate's or a
90/// grouped query's row, and otherwise every column but the payload and the
91/// row version, sorted by UTF-16 code unit. The table name decides, not the
92/// row.
93pub fn aggregate_row_key_columns<'a>(
94    table: &str,
95    columns: impl IntoIterator<Item = &'a String>,
96) -> Vec<String> {
97    if is_keyed_aggregate_table_name(table) {
98        return vec![aggregate_columns::KEY.to_owned()];
99    }
100    let mut out: Vec<String> = columns
101        .into_iter()
102        .filter(|c| !aggregate_columns::PAYLOAD.contains(&c.as_str()) && *c != ROW_VERSION_COLUMN)
103        .cloned()
104        .collect();
105    out.sort_by(|a, b| crate::strings::utf16(a, b));
106    out
107}
108
109fn key_string(
110    prefix: &str,
111    table: &str,
112    primary_key: &[impl AsRef<str>],
113    row: &Object,
114) -> Result<String, InvalidPrimaryKeyValue> {
115    let scalar = |column: &str| match row.get(column) {
116        Some(v @ (Value::String(_) | Value::Number(_) | Value::Bool(_))) => Ok(v.clone()),
117        v => Err(InvalidPrimaryKeyValue {
118            column: column.to_owned(),
119            value: v.cloned(),
120        }),
121    };
122    if let [column] = primary_key {
123        let v = scalar(column.as_ref())?;
124        return Ok(format!("{prefix}{table}/{}", js_string(&v)));
125    }
126    let values = primary_key
127        .iter()
128        .map(|c| scalar(c.as_ref()))
129        .collect::<Result<Vec<_>, _>>()?;
130    let hash = xxhash32::h128(&stringify(&Value::Array(values)));
131    Ok(format!("{prefix}{table}/{hash}"))
132}
133
134/// JS `String(v)` for a scalar.
135pub fn js_string(v: &Value) -> String {
136    match v {
137        Value::String(s) => s.clone(),
138        Value::Number(n) => number::format(*n),
139        Value::Bool(b) => b.to_string(),
140        Value::Null => "null".into(),
141        Value::Array(_) | Value::Object(_) => stringify(v),
142    }
143}
144
145/// `isAggregateTableName`: a synthetic aggregate table, of any kind.
146pub fn is_aggregate_table_name(name: &str) -> bool {
147    name.starts_with(AGGREGATE_TABLE_PREFIX)
148}
149
150/// `isTopLevelAggregateTableName`: `aggregate:<queryID>`, with no further
151/// `:`, unlike a relationship aggregate's or a grouped query's.
152pub fn is_top_level_aggregate_table_name(name: &str) -> bool {
153    name.strip_prefix(AGGREGATE_TABLE_PREFIX)
154        .is_some_and(|rest| !rest.contains(':'))
155}
156
157/// `isKeyedAggregateTableName`: a table whose rows `_0_key` alone keys: a
158/// top-level aggregate's or a grouped query's.
159pub fn is_keyed_aggregate_table_name(name: &str) -> bool {
160    is_top_level_aggregate_table_name(name)
161        || (is_aggregate_table_name(name) && name.ends_with(":#group"))
162}
163
164/// `sourceNameFromKey`: the source of an `e/` or `a/` row key. An `a/` key
165/// leaves out the `aggregate:` of the table's name.
166pub fn source_name(key: &str) -> String {
167    // Both prefixes are two characters long.
168    let rest = &key[ENTITIES_PREFIX.len()..];
169    let name = rest.split('/').next().unwrap_or(rest);
170    if key.starts_with(AGGREGATES_PREFIX) {
171        format!("{AGGREGATE_TABLE_PREFIX}{name}")
172    } else {
173        name.to_owned()
174    }
175}
176
177pub fn desired_queries_key(client_id: &str, hash: &str) -> String {
178    format!("{DESIRED_QUERIES_PREFIX}{client_id}/{hash}")
179}
180
181pub fn got_queries_key(hash: &str) -> String {
182    format!("{GOT_QUERIES_PREFIX}{hash}")
183}
184
185pub fn mutation_response_key(client_id: &str, id: f64) -> String {
186    format!("{MUTATIONS_PREFIX}{client_id}/{}", number::format(id))
187}