Skip to main content

vantage_table/table/base/
computed.rs

1//! Columns a table computes rather than stores: server-side expressions,
2//! lazy (post-fetch) expressions, imported implicit-reference columns and
3//! the columns a `Vista` computes after each read.
4
5use std::sync::Arc;
6
7use vantage_core::Result;
8use vantage_expressions::Expression;
9use vantage_types::{Entity, Record};
10use vantage_vista::forbidden_column;
11
12use super::{EXPRESSION_COLUMN, EXPRESSION_TABLE, ExpressionFn, Table};
13use crate::traits::table_source::TableSource;
14
15impl<T: TableSource, E: Entity<T::Value>> Table<T, E> {
16    /// The expression of expression column `name`, from its callback; `None`
17    /// when `name` isn't one. A failing callback's error gains the column
18    /// ([`EXPRESSION_COLUMN`]) and the table ([`EXPRESSION_TABLE`]) as
19    /// context, unless a callback it ran already named its own.
20    pub fn try_expression_column(&self, name: &str) -> Result<Option<Expression<T::Value>>> {
21        let Some(expr_fn) = self.expressions.get(name) else {
22            return Ok(None);
23        };
24        match expr_fn(self.as_entity_erased()) {
25            Ok(expr) => Ok(Some(expr)),
26            Err(mut e) => {
27                if !e.context.contains_key(EXPRESSION_COLUMN) {
28                    e.context
29                        .insert(EXPRESSION_COLUMN.to_string(), name.to_string());
30                    e.context
31                        .insert(EXPRESSION_TABLE.to_string(), self.table_name().to_string());
32                }
33                Err(e)
34            }
35        }
36    }
37
38    /// Run the callback of every expression column a read would include,
39    /// discarding the results, so a column that can't be built fails here
40    /// instead of at the first read. Building a callback's expression may
41    /// build related tables; call this on a finished table, not while
42    /// another is being built.
43    pub fn check_expressions(&self) -> Result<()> {
44        for name in self.expressions.keys() {
45            if self.is_active_column(name) {
46                self.try_expression_column(name)?;
47            }
48        }
49        Ok(())
50    }
51
52    /// Whether `name` is projected by [`try_select`](Self::try_select). With
53    /// no active set every column is active; otherwise only the set's members
54    /// are, plus the id column (always projected — consumers key rows by it).
55    pub fn is_active_column(&self, name: &str) -> bool {
56        match &self.active_columns {
57            None => true,
58            Some(set) => set.contains(name) || self.id_field.as_deref() == Some(name),
59        }
60    }
61
62    /// Apply lazy expressions to one returned record, in declaration order.
63    /// Each callback borrows the record as built so far; the value it
64    /// returns is inserted under the expression's name before the next
65    /// callback runs. See [`Self::with_lazy_expression`].
66    /// Public so driver shells that bypass the `list_values` read path
67    /// (e.g. a REST shell's windowed fetch) can still apply lazy columns.
68    pub async fn apply_lazy_expressions(
69        &self,
70        record: &mut vantage_types::Record<T::Value>,
71    ) -> vantage_core::Result<()> {
72        for (name, f) in &self.lazy_expressions {
73            let value = f(record).await?;
74            record.insert(name.clone(), value);
75        }
76        Ok(())
77    }
78
79    /// Drop imported implicit-reference columns (`"country.name"`) from a write
80    /// payload. They are read-only, expression-backed projections that no
81    /// backend can honestly store; a round-trip (read → modify → save) would
82    /// otherwise carry them back, and a SCHEMALESS store would create a literal
83    /// `country.name` field. Called before invariants on the full-record write
84    /// paths (insert, insert-returning-id, replace); `patch_value` instead
85    /// rejects imported keys outright, since a partial payload is explicit
86    /// intent per key.
87    pub(in crate::table) fn strip_imported_columns(
88        &self,
89        record: &mut vantage_types::Record<T::Value>,
90    ) {
91        for name in &self.imported_columns {
92            record.shift_remove(name);
93        }
94    }
95
96    /// Drop expression and lazy columns from a full-record write payload, as
97    /// [`Self::strip_imported_columns`] does for imported ones: a row read
98    /// and saved back carries values the table computes, not stores.
99    pub(in crate::table) fn strip_expression_columns(&self, record: &mut Record<T::Value>) {
100        record.retain(|name, _| !self.is_expression_column(name));
101    }
102
103    /// A patch is explicit intent per key, so a column it can't write is
104    /// refused rather than dropped: one a rule made read-only, or an
105    /// expression or lazy column.
106    pub(in crate::table) fn refuse_read_only_columns(
107        &self,
108        partial: &Record<T::Value>,
109    ) -> Result<()> {
110        for name in partial.keys() {
111            if let Some(rule) = self.denials.column_rule(name) {
112                return forbidden_column(name, rule, self.table_name());
113            }
114            if self.is_expression_column(name) {
115                return forbidden_column(name, "expression column", self.table_name());
116            }
117        }
118        Ok(())
119    }
120
121    /// Whether `name` is a server-side expression or lazy column.
122    pub(in crate::table) fn is_expression_column(&self, name: &str) -> bool {
123        self.expressions.contains_key(name) || self.lazy_expressions.contains_key(name)
124    }
125
126    /// Whether `name` is an imported implicit-reference column
127    /// (`"country.name"`) — an expression-backed traversal projection that is
128    /// read-only and must never be persisted, ordered, or searched as if it
129    /// were a physical field.
130    pub fn is_imported_column(&self, name: &str) -> bool {
131        self.imported_columns.contains(name)
132    }
133
134    /// Whether `name` is in the SELECT: every column is, until
135    /// `with_active_columns` restricts the projection.
136    pub(crate) fn is_projected(&self, name: &str) -> bool {
137        self.active_columns
138            .as_ref()
139            .is_none_or(|active| active.contains(name))
140    }
141
142    /// Whether `name` is computed rather than stored: an imported
143    /// implicit-reference column, a server-side expression column, or a lazy
144    /// (post-fetch) computed column. Driver factories flag such columns
145    /// `calculated` in vista metadata so consumers render them read-only.
146    pub fn is_calculated_column(&self, name: &str) -> bool {
147        self.imported_columns.contains(name) || self.is_expression_column(name)
148    }
149
150    /// Register a column the `Vista` computes after each read, positioned
151    /// after every column added so far. Driver factories fold these into
152    /// `VistaMetadata`. A stored column of the same name (one inherited by a
153    /// derived table) is replaced, so the column is never both read and
154    /// computed.
155    pub fn add_computed_column(&mut self, column: vantage_vista::Column) {
156        if let Some((stored_index, _, _)) = self.columns.shift_remove_full(&column.name) {
157            let removed = self.position_of_stored(stored_index);
158            for (at, _) in self.computed_columns.values_mut() {
159                if *at > removed {
160                    *at -= 1;
161                }
162            }
163        }
164        let at = self.columns.len() + self.computed_columns.len();
165        self.computed_columns
166            .insert(column.name.clone(), (at, column));
167    }
168
169    /// Register `spec`'s column as computed when it declares a `lazy:` script
170    /// (see [`vantage_vista::ColumnSpec::lazy_column`]). Returns `false` for a
171    /// stored column, leaving the caller to add it.
172    pub fn add_lazy_spec_column<C>(
173        &mut self,
174        spec: &vantage_vista::ColumnSpec<C>,
175        name: &str,
176    ) -> vantage_core::Result<bool> {
177        let Some(column) = spec.lazy_column(name)? else {
178            return Ok(false);
179        };
180        self.add_computed_column(column);
181        Ok(true)
182    }
183
184    /// Position among all columns of the stored column at `stored_index`:
185    /// computed columns occupy their recorded positions, stored columns fill
186    /// the remaining slots in order.
187    pub(in crate::table) fn position_of_stored(&self, stored_index: usize) -> usize {
188        let mut computed: Vec<usize> = self.computed_columns.values().map(|(at, _)| *at).collect();
189        computed.sort_unstable();
190        let mut at = stored_index;
191        for position in computed {
192            if position <= at {
193                at += 1;
194            }
195        }
196        at
197    }
198
199    /// Columns registered via [`Self::add_computed_column`], in order, each
200    /// with its position among all columns.
201    pub fn computed_columns(&self) -> impl Iterator<Item = (usize, &vantage_vista::Column)> {
202        self.computed_columns.values().map(|(at, c)| (*at, c))
203    }
204}
205
206impl<T: TableSource + 'static, E: Entity<T::Value> + 'static> Table<T, E> {
207    /// Add a computed expression field using builder pattern.
208    ///
209    /// The closure receives `&Table<T, E>` and returns an `Expression<T::Value>`.
210    /// It is evaluated lazily when `select()` builds the query.
211    pub fn with_expression(
212        self,
213        name: &str,
214        expr_fn: impl Fn(&Table<T, E>) -> Expression<T::Value> + Send + Sync + 'static,
215    ) -> Self
216    where
217        T: 'static,
218        E: 'static,
219    {
220        self.with_try_expression(name, move |table| Ok(expr_fn(table)))
221    }
222
223    /// [`with_expression`](Self::with_expression) whose closure can fail. It
224    /// runs only when a query that includes the column is built; its error
225    /// fails that query ([`Self::try_select`]) and
226    /// [`Self::check_expressions`], never the table's build.
227    pub fn with_try_expression(
228        mut self,
229        name: &str,
230        expr_fn: impl Fn(&Table<T, E>) -> Result<Expression<T::Value>> + Send + Sync + 'static,
231    ) -> Self
232    where
233        T: 'static,
234        E: 'static,
235    {
236        // Adapt the caller's `Fn(&Table<T, E>)` into the entity-erased
237        // `ExpressionFn<T>` we store, so it survives `into_entity`. The closure
238        // never touches entity-typed fields, only name-keyed table state.
239        let wrapped: ExpressionFn<T> =
240            Arc::new(move |erased: &Table<T, vantage_types::EmptyEntity>| {
241                // SAFETY: layout-identical (E is PhantomData only); shared borrow.
242                let typed: &Table<T, E> = unsafe {
243                    &*(erased as *const Table<T, vantage_types::EmptyEntity> as *const Table<T, E>)
244                };
245                expr_fn(typed)
246            });
247        self.expressions.insert(name.to_string(), wrapped);
248        self
249    }
250
251    /// Add a lazy computed column using builder pattern.
252    ///
253    /// Unlike [`Self::with_expression`] (which lowers into the data source's
254    /// query), a lazy expression runs in Rust on the record the data source
255    /// *returned*. Callbacks apply in declaration order: each borrows the
256    /// record as built so far, and the value it returns is inserted under
257    /// `name` before the next callback runs — so one expensive fetch (a
258    /// file's contents) can feed several cheap derived columns declared
259    /// after it.
260    ///
261    /// The name is also registered as a column, so the computed field shows
262    /// up in the table's schema (and in Vista metadata derived from it).
263    /// Because the callback's future must not borrow the record, clone what
264    /// you need from `record` before going async.
265    ///
266    /// Lazy expressions run on the `list`/`get` read paths (both raw-record
267    /// and entity forms). They never participate in queries — no conditions,
268    /// ordering, or pushdown — they exist only on returned data.
269    pub fn with_lazy_expression<F, Fut>(mut self, name: &str, f: F) -> Self
270    where
271        F: Fn(&vantage_types::Record<T::Value>) -> Fut + Send + Sync + 'static,
272        Fut: std::future::Future<Output = Result<T::Value>> + Send + 'static,
273    {
274        if !self.columns.contains_key(name) {
275            let column = self.data_source.create_column::<T::AnyType>(name);
276            self.add_column(column);
277        }
278        self.add_lazy_expression(name, Arc::new(move |record| Box::pin(f(record))));
279        self
280    }
281
282    /// Register a pre-boxed lazy expression callback under `name`, without
283    /// touching the column set. Factories lowering a spec (which declares
284    /// its columns separately) use this; application code should prefer
285    /// [`Self::with_lazy_expression`].
286    pub fn add_lazy_expression(&mut self, name: &str, f: crate::table::base::LazyExpressionFn<T>) {
287        self.lazy_expressions.insert(name.to_string(), f);
288    }
289}