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
19pub mod many;
20pub mod one;
21
22pub use many::HasMany;
23pub use one::HasOne;
24
25/// Describes a relationship between two tables.
26pub trait Reference: Send + Sync {
27    /// Given source and target id field names, return (source_column, target_column).
28    fn columns(&self, source_id: &str, target_id: &str) -> (String, String);
29
30    /// The foreign-key column carried by this relation. For `HasOne` it names a
31    /// column on the *source* table (set to the related row's id after the
32    /// related row is inserted); for `HasMany` it names a column on the *target*
33    /// table (set to the parent's id when inserting each child). Drives nested
34    /// insert at the Vista layer.
35    fn foreign_key(&self) -> &str;
36
37    /// Produce a fresh target table (no conditions applied), wrapped in
38    /// `Box<dyn Any>` so callers can downcast back to the concrete
39    /// `Table<T, TargetE>`. Used by [`crate::table::Table::get_ref_as`] and
40    /// [`crate::table::Table::get_subquery_as`] to build the target before
41    /// applying the join condition.
42    fn build_target(&self, data_source: &dyn Any) -> Box<dyn Any>;
43
44    /// Cardinality of this relation. `HasOne` if traversing yields at most
45    /// one record (the FK lives on the source); `HasMany` if it can yield
46    /// any number (the FK lives on the target). Surfaced by
47    /// `Vista::list_references` so CLIs / UIs can pick a record-card vs
48    /// list-grid renderer.
49    fn cardinality(&self) -> vantage_vista::ReferenceKind;
50
51    /// Resolve traversal using a known source row. Returns the target table
52    /// (entity type erased to `EmptyEntity`) wrapped in `Box<dyn Any>`, with
53    /// one eq-condition applied that selects the related rows.
54    ///
55    /// `data_source` is `&T` for the source's `TableSource`; `source_id_field`
56    /// is the name of the source table's id column (needed by `HasMany` to
57    /// pull the join value out of the row); `source_row` is `&Record<T::Value>`.
58    /// `HasOne` ignores `source_id_field` and reads its stored `foreign_key`
59    /// instead.
60    ///
61    /// Callers immediately downcast the result to `Table<T, EmptyEntity>`.
62    fn resolve_from_row(
63        &self,
64        data_source: &dyn Any,
65        source_id_field: &str,
66        source_row: &dyn Any,
67    ) -> Result<Box<dyn Any>>;
68
69    /// Type name of the target table (for error messages).
70    fn target_type_name(&self) -> &'static str;
71}
vantage_table/references.rs

vantage_table/
references.rs
