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}