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        let row: Row = Rc::new(row);
179        self.write
180            .borrow_mut()
181            .set(&key, Value::Object((*row).clone()));
182        self.rows.borrow_mut().insert(key, row.clone());
183        Self::push(&self.source(table_name), SourceChange::Add(row.clone()))?;
184        self.apply_optimistic_aggregate_deltas(table_name, None, Some(&row))
185    }
186
187    fn upsert(&self, table_name: &str, value: &Object) -> Result<(), Error> {
188        let table = self.table_schema(table_name)?;
189        if self.write.borrow().has(&Self::key(table, value)?) {
190            self.update(table_name, value)
191        } else {
192            self.insert(table_name, value)
193        }
194    }
195
196    /// Merges the value's columns into the row; a missing row is left alone.
197    fn update(&self, table_name: &str, value: &Object) -> Result<(), Error> {
198        let table = self.table_schema(table_name)?;
199        let key = Self::key(table, value)?;
200        let Some(prev) = self
201            .write
202            .borrow()
203            .get(&key)
204            .and_then(|v| v.as_object().cloned())
205        else {
206            return Ok(());
207        };
208        let mut next = prev.clone();
209        for (k, v) in value.iter() {
210            next.insert(k.clone(), v.clone());
211        }
212        self.write
213            .borrow_mut()
214            .set(&key, Value::Object(next.clone()));
215        let row: Row = Rc::new(next);
216        let old_row: Row = Rc::new(prev);
217        self.rows.borrow_mut().insert(key, row.clone());
218        Self::push(
219            &self.source(table_name),
220            SourceChange::Edit {
221                row: row.clone(),
222                old_row: old_row.clone(),
223            },
224        )?;
225        self.apply_optimistic_aggregate_deltas(table_name, Some(&old_row), Some(&row))
226    }
227
228    fn delete(&self, table_name: &str, id: &Object) -> Result<(), Error> {
229        let table = self.table_schema(table_name)?;
230        let key = Self::key(table, id)?;
231        let Some(prev) = self
232            .write
233            .borrow()
234            .get(&key)
235            .and_then(|v| v.as_object().cloned())
236        else {
237            return Ok(());
238        };
239        self.write.borrow_mut().delete(&key);
240        self.rows.borrow_mut().remove(&key);
241        let old_row: Row = Rc::new(prev);
242        Self::push(
243            &self.source(table_name),
244            SourceChange::Remove(old_row.clone()),
245        )?;
246        self.apply_optimistic_aggregate_deltas(table_name, Some(&old_row), None)
247    }
248
249    /// `applyOptimisticAggregateDeltas`: moves the synced aggregates whose
250    /// child rows live in `table` by a child row's change, in this
251    /// transaction, so views and `run` see it at once. The rebase replays
252    /// it until the server confirms the mutation, whose value then replaces
253    /// it. An aggregate row not on the client is left alone, except that a
254    /// grouped query's group is added by its first row.
255    fn apply_optimistic_aggregate_deltas(
256        &self,
257        table: &str,
258        old: Option<&Row>,
259        new: Option<&Row>,
260    ) -> Result<(), Error> {
261        for agg in self.branch.optimistic_aggregates(table) {
262            let old_key = old.map(|r| aggregate_key(&agg, r)).transpose()?.flatten();
263            let new_key = new.map(|r| aggregate_key(&agg, r)).transpose()?.flatten();
264            if old_key == new_key {
265                if let Some(k) = old_key {
266                    self.apply_aggregate_delta(&agg, &k, old, new)?;
267                }
268            } else {
269                // The child leaves one aggregate and joins another; either
270                // may be none.
271                if let Some(k) = old_key {
272                    self.apply_aggregate_delta(&agg, &k, old, None)?;
273                }
274                if let Some(k) = new_key {
275                    self.apply_aggregate_delta(&agg, &k, None, new)?;
276                }
277            }
278        }
279        Ok(())
280    }
281
282    /// `applyAggregateDelta`: writes the aggregate row at `key` as one child
283    /// change moves it, if the row is on the client, and pushes it to the
284    /// branch so a later `run` reads it. A grouped query's row is added by a
285    /// group's first row and removed with its last.
286    fn apply_aggregate_delta(
287        &self,
288        agg: &OptimisticAggregate,
289        key: &str,
290        old: Option<&Row>,
291        new: Option<&Row>,
292    ) -> Result<(), Error> {
293        // The branch holds the row when a view of its query reads it.
294        let source = self.branch.source(&agg.aggregate_table);
295        let cur = self
296            .write
297            .borrow()
298            .get(key)
299            .and_then(|v| v.as_object().cloned());
300        let Some(cur) = cur else {
301            if agg.grouped
302                && let Some(added) = new_group_row(agg, old, new)
303            {
304                self.write
305                    .borrow_mut()
306                    .set(key, Value::Object(added.clone()));
307                if let Some(source) = &source {
308                    Self::push(source, SourceChange::Add(Rc::new(added)))?;
309                }
310            }
311            return Ok(());
312        };
313        let Some(updated) = next_aggregate_row(agg, &cur, old, new) else {
314            return Ok(());
315        };
316        let cur_row: Row = Rc::new(cur);
317        let in_branch = source.as_ref().is_some_and(|s| s.contains(&cur_row));
318        if agg.grouped && group_row_count(agg, &updated) == Some(&Value::Number(0.0)) {
319            self.write.borrow_mut().delete(key);
320            if in_branch && let Some(source) = &source {
321                Self::push(source, SourceChange::Remove(cur_row))?;
322            }
323            return Ok(());
324        }
325        self.write
326            .borrow_mut()
327            .set(key, Value::Object(updated.clone()));
328        if in_branch && let Some(source) = &source {
329            Self::push(
330                source,
331                SourceChange::Edit {
332                    row: Rc::new(updated),
333                    old_row: cur_row,
334                },
335            )?;
336        }
337        Ok(())
338    }
339}
340
341/// `aggregateKeyFor`: the key of the aggregate row `child` counts in;
342/// `None` when a correlation value is null, which gives the child no
343/// parent. A grouped query's group can have null values.
344fn aggregate_key(agg: &OptimisticAggregate, child: &Row) -> Result<Option<String>, Error> {
345    if agg.grouped {
346        let values: Vec<Value> = agg
347            .child_field
348            .iter()
349            .map(|c| child.get(c).cloned().unwrap_or(Value::Null))
350            .collect();
351        let mut row = Object::new();
352        row.insert(cols::KEY, Value::String(group_key(&values)));
353        return Ok(Some(aggregate_row_key(&agg.aggregate_table, &row)?));
354    }
355    let mut row = Object::new();
356    for (i, column) in agg.child_field.iter().enumerate() {
357        match child.get(column) {
358            None | Some(Value::Null) => return Ok(None),
359            Some(v) => {
360                row.insert(agg.key_field[i].clone(), v.clone());
361            }
362        }
363    }
364    Ok(Some(aggregate_row_key(&agg.aggregate_table, &row)?))
365}
366
367/// `groupRowCount`: the number of rows of a group, `None` for a sum or
368/// average row stored before the rows carried it.
369fn group_row_count<'a>(agg: &OptimisticAggregate, row: &'a Object) -> Option<&'a Value> {
370    row.get(if agg.aggregate.fn_ == AggregateFunction::Count {
371        cols::VALUE
372    } else {
373        cols::ROWS
374    })
375}
376
377fn counted(agg: &OptimisticAggregate, row: Option<&Row>) -> bool {
378    row.is_some_and(|r| agg.predicate.as_ref().is_none_or(|p| p(r)))
379}
380
381/// `newGroupRow`: the row of a group not on the client that `new` is the
382/// first row of: it passes the `where`, and `old` wasn't counted already.
383fn new_group_row(
384    agg: &OptimisticAggregate,
385    old: Option<&Row>,
386    new: Option<&Row>,
387) -> Option<Object> {
388    if !counted(agg, new) || counted(agg, old) {
389        return None;
390    }
391    let new = new?;
392    let values: Vec<Value> = agg
393        .child_field
394        .iter()
395        .map(|c| new.get(c).cloned().unwrap_or(Value::Null))
396        .collect();
397    // The group with no rows, which `new` then joins.
398    let mut empty = Object::new();
399    for (i, column) in agg.key_field.iter().enumerate() {
400        empty.insert(column.clone(), values[i].clone());
401    }
402    empty.insert(cols::KEY, Value::String(group_key(&values)));
403    if agg.aggregate.fn_ == AggregateFunction::Count {
404        empty.insert(cols::VALUE, Value::Number(0.0));
405    } else {
406        empty.insert(cols::VALUE, Value::Null);
407        empty.insert(cols::SUM, Value::Number(0.0));
408        empty.insert(cols::COUNT, Value::Number(0.0));
409        empty.insert(cols::ROWS, Value::Number(0.0));
410    }
411    next_aggregate_row(agg, &empty, None, Some(new))
412}
413
414fn number(v: Option<&Value>) -> f64 {
415    match v {
416        Some(Value::Number(n)) => *n,
417        _ => 0.0,
418    }
419}
420
421/// `nextAggregateRow`: the aggregate row after a child changes from `old`
422/// to `new`, `None` when it doesn't move. A row the `where` rejects counts
423/// as absent, so a row entering or leaving the filtered set moves it too.
424fn next_aggregate_row(
425    agg: &OptimisticAggregate,
426    cur: &Object,
427    old: Option<&Row>,
428    new: Option<&Row>,
429) -> Option<Object> {
430    let passes = |r: &&Row| agg.predicate.as_ref().is_none_or(|p| p(r));
431    let old = old.filter(passes);
432    let new = new.filter(passes);
433    let contribution = |r: Option<&Row>| r.map(|r| aggregate_value(&agg.aggregate, r));
434    let contributes = |r: Option<&Row>| matches!(contribution(r), Some(Value::Number(_)));
435    let present = |r: Option<&Row>| if r.is_some() { 1.0 } else { 0.0 };
436    let mut next = cur.clone();
437    match agg.aggregate.fn_ {
438        AggregateFunction::Count => {
439            let delta = present(new) - present(old);
440            if delta == 0.0 {
441                return None;
442            }
443            next.insert(
444                cols::VALUE,
445                Value::Number(number(cur.get(cols::VALUE)) + delta),
446            );
447            Some(next)
448        }
449        AggregateFunction::Sum | AggregateFunction::Avg => {
450            agg.aggregate.field.as_ref()?;
451            // The row carries the sum of the non-null values and their
452            // count, so both move and the value follows: SQL's sum and avg
453            // skip nulls and are null over none. A group's row also carries
454            // its number of rows, nulls included, unless it was stored
455            // before it did.
456            let sum_delta = number(contribution(new).as_ref()) - number(contribution(old).as_ref());
457            let count_delta = (contributes(new) as u8 as f64) - (contributes(old) as u8 as f64);
458            let has_rows = cur.contains_key(cols::ROWS);
459            let rows_delta = if has_rows {
460                present(new) - present(old)
461            } else {
462                0.0
463            };
464            if sum_delta == 0.0 && count_delta == 0.0 && rows_delta == 0.0 {
465                return None;
466            }
467            let sum = number(cur.get(cols::SUM)) + sum_delta;
468            let count = number(cur.get(cols::COUNT)) + count_delta;
469            let result = if agg.aggregate.fn_ == AggregateFunction::Sum {
470                sum
471            } else {
472                sum / count
473            };
474            next.insert(
475                cols::VALUE,
476                if count > 0.0 {
477                    Value::Number(result)
478                } else {
479                    Value::Null
480                },
481            );
482            next.insert(cols::SUM, Value::Number(sum));
483            next.insert(cols::COUNT, Value::Number(count));
484            if has_rows {
485                next.insert(
486                    cols::ROWS,
487                    Value::Number(number(cur.get(cols::ROWS)) + rows_delta),
488                );
489            }
490            Some(next)
491        }
492        // Not invertible: the server's next poke moves them.
493        AggregateFunction::Min | AggregateFunction::Max => None,
494    }
495}
496
497/// The CRUD operations on one table (`TableCRUD` in
498/// `packages/zql/src/mutate/crud.ts`). Values are keyed by client column
499/// name.
500pub struct TableMutator<'a> {
501    tx: &'a Transaction,
502    table: &'a str,
503}
504
505impl TableMutator<'_> {
506    /// Inserts a row unless one with its primary key exists. Columns it
507    /// leaves out are null.
508    pub fn insert(&self, value: &Object) -> Result<(), Error> {
509        self.tx.insert(self.table, value)
510    }
511
512    /// Inserts a row, or merges the value into the existing one.
513    pub fn upsert(&self, value: &Object) -> Result<(), Error> {
514        self.tx.upsert(self.table, value)
515    }
516
517    /// Merges the value's columns into the row with its primary key, if any.
518    pub fn update(&self, value: &Object) -> Result<(), Error> {
519        self.tx.update(self.table, value)
520    }
521
522    /// Deletes the row with the primary key in `id`, if any.
523    pub fn delete(&self, id: &Object) -> Result<(), Error> {
524        self.tx.delete(self.table, id)
525    }
526}