vantage_table/
references.rs

1//! Table reference system for relationships between tables.
2//!
3//! The `Reference` trait describes a relationship (field names, target factory).
4//! Same-persistence resolution happens in `Table::get_ref_from_row` via
5//! `Reference::resolve_from_row` — the join value is read out of a known source
6//! row and pushed as a plain eq-condition on the target.
7//!
8//! Two concrete types:
9//! - `HasOne` — foreign key on source table (e.g. Client.bakery_id → Bakery)
10//! - `HasMany` — foreign key on target table (e.g. Bakery → Client.bakery_id)
11//!
12//! Cross-persistence references live at the Vista layer (`Vista::with_foreign`),
13//! not here. Typed `Table<T, E>` is single-backend by construction.
14
15use std::any::Any;
16
17use vantage_core::Result;
18
19use crate::any::AnyTable;
20
21pub mod many;
22pub mod one;
23
24pub use many::HasMany;
25pub use one::HasOne;
26
27/// Describes a relationship between two tables.
28pub trait Reference: Send + Sync {
29    /// Given source and target id field names, return (source_column, target_column).
30    fn columns(&self, source_id: &str, target_id: &str) -> (String, String);
31
32    /// Produce a fresh target table (no conditions applied).
33    fn build_target(&self, data_source: &dyn Any) -> Box<dyn Any>;
34
35    /// Cardinality of this relation. `HasOne` if traversing yields at most
36    /// one record (the FK lives on the source); `HasMany` if it can yield
37    /// any number (the FK lives on the target). Surfaced by
38    /// `Vista::list_references` so CLIs / UIs can pick a record-card vs
39    /// list-grid renderer.
40    fn cardinality(&self) -> vantage_vista::ReferenceKind;
41
42    /// Resolve traversal using a known source row. Returns the target table
43    /// (entity type erased to `EmptyEntity`) wrapped in `Box<dyn Any>`, with
44    /// one eq-condition applied that selects the related rows.
45    ///
46    /// `data_source` is `&T` for the source's `TableSource`; `source_id_field`
47    /// is the name of the source table's id column (needed by `HasMany` to
48    /// pull the join value out of the row); `source_row` is `&Record<T::Value>`.
49    /// `HasOne` ignores `source_id_field` and reads its stored `foreign_key`
50    /// instead.
51    ///
52    /// Callers immediately downcast the result to `Table<T, EmptyEntity>`.
53    fn resolve_from_row(
54        &self,
55        data_source: &dyn Any,
56        source_id_field: &str,
57        source_row: &dyn Any,
58    ) -> Result<Box<dyn Any>>;
59
60    /// Resolve this reference and return an AnyTable.
61    ///
62    /// Legacy path used by `Table::get_ref` / `get_ref_as` / `get_subquery_as`.
63    /// Slated for deletion in Stage 9 alongside `AnyTable`; new callers should
64    /// use `resolve_from_row` (typed) or `Vista::get_ref` (erased) instead.
65    fn resolve_as_any(&self, source_table: &dyn Any) -> Result<AnyTable>;
66
67    /// Type name of the target table (for error messages).
68    fn target_type_name(&self) -> &'static str;
69}
vantage_table/references.rs

vantage_table/
references.rs
