Skip to main content

zero_client/client/
transaction.rs

1//! The transaction a mutator runs in on the client (`TransactionImpl` in
2//! `packages/zero-client/src/client/custom.ts`, with the CRUD operations of
3//! `crud-impl.ts`). Writes go to the local store and to the IVM branch the
4//! mutator reads through `run`.
5
6use super::ivm_branch::IvmBranch;
7use super::query_context::QueryContext;
8use super::replica_store::KvWrite;
9use super::{ApplicationError, Error};
10use crate::ast::AggregateFunction;
11use crate::builder::OptimisticAggregate;
12use crate::hash::query::{hash_of_ast, hash_of_name_and_args};
13use crate::ivm::{
14    MemorySource, Row, Source, SourceChange, ViewValue, aggregate_value, capture, group_key,
15};
16use crate::json::{Object, Value};
17use crate::keys::{
18    aggregate_columns as cols, aggregate_row_key, got_queries_key, primary_key_string,
19};
20use crate::query::AnyQuery;
21use crate::schema::{Schema, Table};
22use std::cell::{OnceCell, RefCell};
23use std::collections::HashMap;
24use std::rc::Rc;
25use std::sync::Arc;
26
27/// Why a mutator runs.
28#[derive(Clone, Copy, Debug, PartialEq, Eq)]
29pub enum Reason {
30    /// The first run, when the app calls `mutate`.
31    Optimistic,
32    /// A replay over newer server data while the mutation is pending.
33    Rebase,
34}
35
36impl Reason {
37    /// The reason as JS names it.
38    pub fn as_str(self) -> &'static str {
39        match self {
40            Reason::Optimistic => "optimistic",
41            Reason::Rebase => "rebase",
42        }
43    }
44}
45
46/// The transaction a mutator runs in.
47pub struct Transaction {
48    client_id: String,
49    mutation_id: f64,
50    reason: Reason,
51    token: Option<String>,
52    pub(crate) write: RefCell<KvWrite>,
53    branch: Rc<IvmBranch>,
54    schema: Arc<Schema>,
55    /// The rows written, by key, as the branch has them, so the main branch
56    /// can take the same rows rather than a copy of each.
57    pub(crate) rows: RefCell<HashMap<String, Row>>,
58    /// A mutator's query computes its aggregates from the branch's rows,
59    /// unless the server has answered it: then it reads the synced rows,
60    /// with this client's pending changes applied, as a view of it does
61    /// (`MutatorContext` in `custom.ts`).
62    context: OnceCell<Rc<QueryContext>>,
63    synced_context: OnceCell<Rc<QueryContext>>,
64}
65
66impl Transaction {
67    pub(crate) fn new(
68        client_id: String,
69        mutation_id: f64,
70        reason: Reason,
71        token: Option<String>,
72        write: KvWrite,
73        branch: Rc<IvmBranch>,
74        schema: Arc<Schema>,
75    ) -> Self {
76        Transaction {
77            client_id,
78            mutation_id,
79            reason,
80            token,
81            write: RefCell::new(write),
82            branch,
83            schema,
84            rows: RefCell::default(),
85            context: OnceCell::new(),
86            synced_context: OnceCell::new(),
87        }
88    }
89
90    /// The write and the rows it wrote, once the mutator is done.
91    pub(crate) fn finish(self) -> (KvWrite, HashMap<String, Row>) {
92        (self.write.into_inner(), self.rows.into_inner())
93    }
94
95    /// Where the mutator runs: always `client` here.
96    pub fn location(&self) -> &'static str {
97        "client"
98    }
99
100    /// The client running the mutation.
101    pub fn client_id(&self) -> &str {
102        &self.client_id
103    }
104
105    /// The mutation's ID.
106    pub fn mutation_id(&self) -> f64 {
107        self.mutation_id
108    }
109
110    /// Why the mutator is running: optimistically, or again in a rebase.
111    pub fn reason(&self) -> Reason {
112        self.reason
113    }
114
115    /// The auth token the client has.
116    pub fn token(&self) -> Option<&str> {
117        self.token.as_deref()
118    }
119
120    /// The CRUD operations on `table`: `tx.mutate.issue` in JS.
121    pub fn table<'a>(&'a self, table: &'a str) -> TableMutator<'a> {
122        TableMutator { tx: self, table }
123    }
124
125    /// The rows `query` returns over this transaction's data.
126    pub fn run(&self, query: &AnyQuery) -> Result<ViewValue, Error> {
127        let query_id = match query.custom_query_id() {
128            Some(id) => hash_of_name_and_args(&id.name, &id.args),
129            None => hash_of_ast(query.ast()),
130        };
131        let synced = self.write.borrow().has(&got_queries_key(&query_id));
132        let context = if synced {
133            self.synced_context
134                .get_or_init(|| QueryContext::local(self.branch.clone(), true))
135        } else {
136            self.context
137                .get_or_init(|| QueryContext::local(self.branch.clone(), false))
138        };
139        context.snapshot(query)
140    }
141
142    fn table_schema(&self, table: &str) -> Result<&Table, Error> {
143        self.schema
144            .tables
145            .get(table)
146            .ok_or_else(|| ApplicationError::new(format!("Unknown table: {table}")).into())
147    }
148
149    fn key(table: &Table, value: &Object) -> Result<String, Error> {
150        Ok(primary_key_string(&table.name, &table.primary_key, value)?)
151    }
152
153    fn source(&self, table: &str) -> Rc<MemorySource> {
154        self.branch
155            .source(table)
156            .unwrap_or_else(|| panic!("No source for table {table}"))
157    }
158
159    /// Pushes `change`, failing as JS's push throws when an operator does.
160    fn push(source: &MemorySource, change: SourceChange) -> Result<(), Error> {
161        Ok(capture(|| source.push(change))?)
162    }
163
164    /// `insert` in `crud-impl.ts`: a row that exists is left alone. Columns
165    /// the value leaves out are null.
166    fn insert(&self, table_name: &str, value: &Object) -> Result<(), Error> {
167        let table = self.table_schema(table_name)?;
168        let key = Self::key(table, value)?;
169        if self.write.borrow().has(&key) {
170            return Ok(());
171        }
172        let mut row = value.clone();
173        for column in table.columns.keys() {
174            if !row.contains_key(column) {
175                row.insert(column.clone(), Value::Null);
176            }
177        }
178        self.branch.layouts.share(table_name, &mut row);
179        let row: Row = Rc::new(row);
180        self.write
181            .borrow_mut()
182            .set(&key, Value::Object((*row).clone()));
183        self.rows.borrow_mut().insert(key, row.clone());
184        Self::push(&self.source(table_name), SourceChange::Add(row.clone()))?;
185        self.apply_optimistic_aggregate_deltas(table_name, None, Some(&row))
186    }
187
188    fn upsert(&self, table_name: &str, value: &Object) -> Result<(), Error> {
189        let table = self.table_schema(table_name)?;
190        if self.write.borrow().has(&Self::key(table, value)?) {
191            self.update(table_name, value)
192        } else {
193            self.insert(table_name, value)
194        }
195    }
196
197    /// Merges the value's columns into the row; a missing row is left alone.
198    fn update(&self, table_name: &str, value: &Object) -> Result<(), Error> {
199        let table = self.table_schema(table_name)?;
200        let key = Self::key(table, value)?;
201        let Some(prev) = self
202            .write
203            .borrow()
204            .get(&key)
205            .and_then(|v| v.as_object().cloned())
206        else {
207            return Ok(());
208        };
209        let mut next = prev.clone();
210        for (k, v) in value.iter() {
211            next.insert(k.clone(), v.clone());
212        }
213        self.branch.layouts.share(table_name, &mut next);
214        self.write
215            .borrow_mut()
216            .set(&key, Value::Object(next.clone()));
217        let row: Row = Rc::new(next);
218        let old_row: Row = Rc::new(prev);
219        self.rows.borrow_mut().insert(key, row.clone());
220        Self::push(
221            &self.source(table_name),
222            SourceChange::Edit {
223                row: row.clone(),
224                old_row: old_row.clone(),
225            },
226        )?;
227        self.apply_optimistic_aggregate_deltas(table_name, Some(&old_row), Some(&row))
228    }
229
230    fn delete(&self, table_name: &str, id: &Object) -> Result<(), Error> {
231        let table = self.table_schema(table_name)?;
232        let key = Self::key(table, id)?;
233        let Some(prev) = self
234            .write
235            .borrow()
236            .get(&key)
237            .and_then(|v| v.as_object().cloned())
238        else {
239            return Ok(());
240        };
241        self.write.borrow_mut().delete(&key);
242        self.rows.borrow_mut().remove(&key);
243        let old_row: Row = Rc::new(prev);
244        Self::push(
245            &self.source(table_name),
246            SourceChange::Remove(old_row.clone()),
247        )?;
248        self.apply_optimistic_aggregate_deltas(table_name, Some(&old_row), None)
249    }
250
251    /// `applyOptimisticAggregateDeltas`: moves the synced aggregates whose
252    /// child rows live in `table` by a child row's change, in this
253    /// transaction, so views and `run` see it at once. The rebase replays
254    /// it until the server confirms the mutation, whose value then replaces
255    /// it. An aggregate row not on the client is left alone, except that a
256    /// grouped query's group is added by its first row.
257    fn apply_optimistic_aggregate_deltas(
258        &self,
259        table: &str,
260        old: Option<&Row>,
261        new: Option<&Row>,
262    ) -> Result<(), Error> {
263        for agg in self.branch.optimistic_aggregates(table) {
264            let old_key = old.map(|r| aggregate_key(&agg, r)).transpose()?.flatten();
265            let new_key = new.map(|r| aggregate_key(&agg, r)).transpose()?.flatten();
266            if old_key == new_key {
267                if let Some(k) = old_key {
268                    self.apply_aggregate_delta(&agg, &k, old, new)?;
269                }
270            } else {
271                // The child leaves one aggregate and joins another; either
272                // may be none.
273                if let Some(k) = old_key {
274                    self.apply_aggregate_delta(&agg, &k, old, None)?;
275                }
276                if let Some(k) = new_key {
277                    self.apply_aggregate_delta(&agg, &k, None, new)?;
278                }
279            }
280        }
281        Ok(())
282    }
283
284    /// `applyAggregateDelta`: writes the aggregate row at `key` as one child
285    /// change moves it, if the row is on the client, and pushes it to the
286    /// branch so a later `run` reads it. A grouped query's row is added by a
287    /// group's first row and removed with its last.
288    fn apply_aggregate_delta(
289        &self,
290        agg: &OptimisticAggregate,
291        key: &str,
292        old: Option<&Row>,
293        new: Option<&Row>,
294    ) -> Result<(), Error> {
295        // The branch holds the row when a view of its query reads it.
296        let source = self.branch.source(&agg.aggregate_table);
297        let cur = self
298            .write
299            .borrow()
300            .get(key)
301            .and_then(|v| v.as_object().cloned());
302        let Some(cur) = cur else {
303            if agg.grouped
304                && let Some(added) = new_group_row(agg, old, new)
305            {
306                self.write
307                    .borrow_mut()
308                    .set(key, Value::Object(added.clone()));
309                if let Some(source) = &source {
310                    Self::push(source, SourceChange::Add(Rc::new(added)))?;
311                }
312            }
313            return Ok(());
314        };
315        let Some(updated) = next_aggregate_row(agg, &cur, old, new) else {
316            return Ok(());
317        };
318        let cur_row: Row = Rc::new(cur);
319        let in_branch = source.as_ref().is_some_and(|s| s.contains(&cur_row));
320        if agg.grouped && group_row_count(agg, &updated) == Some(&Value::Number(0.0)) {
321            self.write.borrow_mut().delete(key);
322            if in_branch && let Some(source) = &source {
323                Self::push(source, SourceChange::Remove(cur_row))?;
324            }
325            return Ok(());
326        }
327        self.write
328            .borrow_mut()
329            .set(key, Value::Object(updated.clone()));
330        if in_branch && let Some(source) = &source {
331            Self::push(
332                source,
333                SourceChange::Edit {
334                    row: Rc::new(updated),
335                    old_row: cur_row,
336                },
337            )?;
338        }
339        Ok(())
340    }
341}
342
343/// `aggregateKeyFor`: the key of the aggregate row `child` counts in;
344/// `None` when a correlation value is null, which gives the child no
345/// parent. A grouped query's group can have null values.
346fn aggregate_key(agg: &OptimisticAggregate, child: &Row) -> Result<Option<String>, Error> {
347    if agg.grouped {
348        let values: Vec<Value> = agg
349            .child_field
350            .iter()
351            .map(|c| child.get(c).cloned().unwrap_or(Value::Null))
352            .collect();
353        let mut row = Object::new();
354        row.insert(cols::KEY, Value::String(group_key(&values)));
355        return Ok(Some(aggregate_row_key(&agg.aggregate_table, &row)?));
356    }
357    let mut row = Object::new();
358    for (i, column) in agg.child_field.iter().enumerate() {
359        match child.get(column) {
360            None | Some(Value::Null) => return Ok(None),
361            Some(v) => {
362                row.insert(agg.key_field[i].clone(), v.clone());
363            }
364        }
365    }
366    Ok(Some(aggregate_row_key(&agg.aggregate_table, &row)?))
367}
368
369/// `groupRowCount`: the number of rows of a group, `None` for a sum or
370/// average row stored before the rows carried it.
371fn group_row_count<'a>(agg: &OptimisticAggregate, row: &'a Object) -> Option<&'a Value> {
372    row.get(if agg.aggregate.fn_ == AggregateFunction::Count {
373        cols::VALUE
374    } else {
375        cols::ROWS
376    })
377}
378
379fn counted(agg: &OptimisticAggregate, row: Option<&Row>) -> bool {
380    row.is_some_and(|r| agg.predicate.as_ref().is_none_or(|p| p(r)))
381}
382
383/// `newGroupRow`: the row of a group not on the client that `new` is the
384/// first row of: it passes the `where`, and `old` wasn't counted already.
385fn new_group_row(
386    agg: &OptimisticAggregate,
387    old: Option<&Row>,
388    new: Option<&Row>,
389) -> Option<Object> {
390    if !counted(agg, new) || counted(agg, old) {
391        return None;
392    }
393    let new = new?;
394    let values: Vec<Value> = agg
395        .child_field
396        .iter()
397        .map(|c| new.get(c).cloned().unwrap_or(Value::Null))
398        .collect();
399    // The group with no rows, which `new` then joins.
400    let mut empty = Object::new();
401    for (i, column) in agg.key_field.iter().enumerate() {
402        empty.insert(column.clone(), values[i].clone());
403    }
404    empty.insert(cols::KEY, Value::String(group_key(&values)));
405    if agg.aggregate.fn_ == AggregateFunction::Count {
406        empty.insert(cols::VALUE, Value::Number(0.0));
407    } else {
408        empty.insert(cols::VALUE, Value::Null);
409        empty.insert(cols::SUM, Value::Number(0.0));
410        empty.insert(cols::COUNT, Value::Number(0.0));
411        empty.insert(cols::ROWS, Value::Number(0.0));
412    }
413    next_aggregate_row(agg, &empty, None, Some(new))
414}
415
416fn number(v: Option<&Value>) -> f64 {
417    match v {
418        Some(Value::Number(n)) => *n,
419        _ => 0.0,
420    }
421}
422
423/// `nextAggregateRow`: the aggregate row after a child changes from `old`
424/// to `new`, `None` when it doesn't move. A row the `where` rejects counts
425/// as absent, so a row entering or leaving the filtered set moves it too.
426fn next_aggregate_row(
427    agg: &OptimisticAggregate,
428    cur: &Object,
429    old: Option<&Row>,
430    new: Option<&Row>,
431) -> Option<Object> {
432    let passes = |r: &&Row| agg.predicate.as_ref().is_none_or(|p| p(r));
433    let old = old.filter(passes);
434    let new = new.filter(passes);
435    let contribution = |r: Option<&Row>| r.map(|r| aggregate_value(&agg.aggregate, r));
436    let contributes = |r: Option<&Row>| matches!(contribution(r), Some(Value::Number(_)));
437    let present = |r: Option<&Row>| if r.is_some() { 1.0 } else { 0.0 };
438    let mut next = cur.clone();
439    match agg.aggregate.fn_ {
440        AggregateFunction::Count => {
441            let delta = present(new) - present(old);
442            if delta == 0.0 {
443                return None;
444            }
445            next.insert(
446                cols::VALUE,
447                Value::Number(number(cur.get(cols::VALUE)) + delta),
448            );
449            Some(next)
450        }
451        AggregateFunction::Sum | AggregateFunction::Avg => {
452            agg.aggregate.field.as_ref()?;
453            // The row carries the sum of the non-null values and their
454            // count, so both move and the value follows: SQL's sum and avg
455            // skip nulls and are null over none. A group's row also carries
456            // its number of rows, nulls included, unless it was stored
457            // before it did.
458            let sum_delta = number(contribution(new).as_ref()) - number(contribution(old).as_ref());
459            let count_delta = (contributes(new) as u8 as f64) - (contributes(old) as u8 as f64);
460            let has_rows = cur.contains_key(cols::ROWS);
461            let rows_delta = if has_rows {
462                present(new) - present(old)
463            } else {
464                0.0
465            };
466            if sum_delta == 0.0 && count_delta == 0.0 && rows_delta == 0.0 {
467                return None;
468            }
469            let sum = number(cur.get(cols::SUM)) + sum_delta;
470            let count = number(cur.get(cols::COUNT)) + count_delta;
471            let result = if agg.aggregate.fn_ == AggregateFunction::Sum {
472                sum
473            } else {
474                sum / count
475            };
476            next.insert(
477                cols::VALUE,
478                if count > 0.0 {
479                    Value::Number(result)
480                } else {
481                    Value::Null
482                },
483            );
484            next.insert(cols::SUM, Value::Number(sum));
485            next.insert(cols::COUNT, Value::Number(count));
486            if has_rows {
487                next.insert(
488                    cols::ROWS,
489                    Value::Number(number(cur.get(cols::ROWS)) + rows_delta),
490                );
491            }
492            Some(next)
493        }
494        // Not invertible: the server's next poke moves them.
495        AggregateFunction::Min | AggregateFunction::Max => None,
496    }
497}
498
499/// The CRUD operations on one table (`TableCRUD` in
500/// `packages/zql/src/mutate/crud.ts`). Values are keyed by client column
501/// name.
502pub struct TableMutator<'a> {
503    tx: &'a Transaction,
504    table: &'a str,
505}
506
507impl TableMutator<'_> {
508    /// Inserts a row unless one with its primary key exists. Columns it
509    /// leaves out are null.
510    pub fn insert(&self, value: &Object) -> Result<(), Error> {
511        self.tx.insert(self.table, value)
512    }
513
514    /// Inserts a row, or merges the value into the existing one.
515    pub fn upsert(&self, value: &Object) -> Result<(), Error> {
516        self.tx.upsert(self.table, value)
517    }
518
519    /// Merges the value's columns into the row with its primary key, if any.
520    pub fn update(&self, value: &Object) -> Result<(), Error> {
521        self.tx.update(self.table, value)
522    }
523
524    /// Deletes the row with the primary key in `id`, if any.
525    pub fn delete(&self, id: &Object) -> Result<(), Error> {
526        self.tx.delete(self.table, id)
527    }
528}