tablo-core 0.10.0

//! What Tablo reads off a model's schema: its fields, their columns, its indices and relations
//! (tablo#183).
//!
//! Toasty exposes a model's schema only as its internal `app`, `mapping` and `db` structures. This
//! module is the one reader of them, and answers in Tablo's own terms: [`FieldInfo`],
//! [`LeafField`], [`EnumShape`], [`BelongsTo`].

use std::{
    collections::HashMap,
    sync::{Arc, LazyLock, Mutex, OnceLock, PoisonError},
};

use toasty::{
    schema::{app, mapping},
    stmt::{IntoExpr, IntoInsert, Path},
};
use toasty_core::{driver::Capability, stmt::PathRoot};
use topcoat::context::Cx;

use crate::{DeclarationErrorKind, Text};

/// A model's id in the app schema.
pub(crate) type ModelId = app::ModelId;

/// A compiled schema: an app `Db`'s, or the one a `Db` registering a model would compile.
///
/// It gives all three halves the walk needs: `.app` carries the embedded models the owned
/// `Model::schema()` cannot see, `.mapping` records which physical column each field resolves to,
/// and `.db` holds the physical table and column names. So an embedded lens binds without opening
/// a connection.
#[derive(Clone)]
pub(crate) struct AppSchema(Arc<toasty_core::Schema>);

impl AppSchema {
    /// `db`'s compiled schema.
    pub(crate) fn of_db(db: &toasty::Db) -> Self {
        Self(db.schema().clone())
    }

    /// The schema a `Db` registering `M` compiles for `M` and every model its fields reach,
    /// compiled once per process.
    ///
    /// A column's name depends only on the models: Toasty joins an embedded field's steps with
    /// `_`, and neither the driver nor the table-name prefix enters it. So an embedded lens binds
    /// when it is declared, and to the column the app's own `Db` stores it in. The compile still
    /// checks each model against a driver, so this tries Toasty's PostgreSQL, SQLite, MySQL and
    /// DynamoDB drivers until one takes the models.
    ///
    /// # Errors
    ///
    /// Each of those drivers' reasons to refuse the models.
    pub(crate) fn of_model<M: toasty::schema::Model>() -> Result<Self, String> {
        type Compiled = Arc<OnceLock<Result<AppSchema, String>>>;
        static COMPILED: LazyLock<Mutex<HashMap<ModelId, Compiled>>> =
            LazyLock::new(Mutex::default);
        // The lock guards the lookup only: a model compiles outside it, and once.
        let entry = COMPILED
            .lock()
            .unwrap_or_else(PoisonError::into_inner)
            .entry(M::id())
            .or_default()
            .clone();
        entry.get_or_init(Self::compile::<M>).clone()
    }

    fn compile<M: toasty::schema::Model>() -> Result<Self, String> {
        let mut models = app::ModelSet::new();
        M::register(&mut models);
        let builder = toasty_core::schema::Builder::new();
        let mut refusals = Vec::new();
        for driver in [
            &Capability::POSTGRESQL,
            &Capability::SQLITE,
            &Capability::MYSQL,
            &Capability::DYNAMODB,
        ] {
            // `app::Schema` is no `Clone`: each driver gets its own.
            let app = app::Schema::from_macro(models.clone()).map_err(|error| error.to_string())?;
            match builder.build(app, driver) {
                Ok(schema) => return Ok(Self(Arc::new(schema))),
                Err(refused) => refusals.push(format!("{}: {refused}", driver.driver_name)),
            }
        }
        Err(refusals.join("; "))
    }

    /// The compiled schema of the `Db` the context carries, if it carries one.
    pub(crate) fn of(cx: &Cx) -> Option<Self> {
        topcoat::context::try_context::<toasty::Db>(cx).map(Self::of_db)
    }

    /// The compiled schema itself, for the walks of [`super::join`].
    pub(crate) fn inner(&self) -> &toasty_core::Schema {
        &self.0
    }

    /// Whether the schema registers a model named `name`, in upper camel case.
    pub(crate) fn registers(&self, name: &str) -> bool {
        self.0
            .app
            .models()
            .any(|model| model.name().upper_camel_case() == name)
    }
}

/// A typed path with its model and value types erased: the steps a declaration resolves.
#[derive(Debug, Clone)]
pub(crate) struct ModelPath(toasty_core::stmt::Path);

impl ModelPath {
    pub(crate) fn of<M, T>(path: &Path<M, T>) -> Self {
        Self(path.clone().into())
    }

    /// The field index of each step, from the path's root.
    pub(crate) fn steps(&self) -> &[usize] {
        self.0.projection.as_slice()
    }

    /// Whether the path steps into an embedded value: more than one step, or an enum variant's
    /// root.
    ///
    /// A variant root is an embedded-enum payload accessor *whatever* its projection length: the
    /// generated accessor rebases onto the variant, so the steps are variant-local and a
    /// single-step projection is the payload field. Only a model root with one step is a plain
    /// field.
    pub(crate) fn is_embedded(&self) -> bool {
        self.steps().len() > 1 || matches!(self.0.root, PathRoot::Variant { .. })
    }

    /// The index of the model's root field the path starts at: its first step, or, under an
    /// embedded enum variant's root, the first step of the path to the enum's field.
    pub(crate) fn root_step(&self) -> Option<usize> {
        match &self.0.root {
            PathRoot::Variant { parent, .. } => Self((**parent).clone()).root_step(),
            _ => self.steps().first().copied(),
        }
    }

    /// `<path> = value`, with the value typed as the path's own field.
    pub(crate) fn eq<T: IntoExpr<T>>(&self, value: T) -> toasty::stmt::Expr<bool> {
        let rhs: toasty_core::stmt::Expr = value.into_expr().into();
        toasty::stmt::Expr::from_untyped(toasty_core::stmt::Expr::eq(
            self.0.clone().into_stmt(),
            rhs,
        ))
    }
}

/// One named field of a model's root, as a declaration check reads it.
#[derive(Debug, Clone, PartialEq, Eq)]
pub(crate) struct FieldInfo {
    /// The field's index in its model, which the create builder and the insert use too.
    pub(crate) index: usize,
    /// The field's name, which is also its form key.
    pub(crate) name: String,
    /// The label a declaration defaults to: [`Text::field`] of [`label_name`].
    pub(crate) label: Text,
    pub(crate) nullable: bool,
    /// Whether a unique index covers the field.
    ///
    /// A **composite** unique index counts too: `#[unique(tenant_id, email)]` is how a
    /// tenant-scoped resource expresses "unique within the tenant", and the app-side pre-check
    /// has to recognise it or the field's `unique()` declaration is silently dead. The pre-check
    /// probes it on all its fields, through [`unique_with`](Self::unique_with).
    ///
    /// The primary key is excluded: a key column is unique by construction, not by a declared
    /// constraint. This reports declared schema uniqueness, not a global guarantee: SQL permits
    /// multiple `NULL`s in a unique index, so a nullable unique field can still repeat.
    pub(crate) unique: bool,
    /// Each unique index covering the field, as the names of its other fields: an empty list
    /// for a single-field index. The pre-check probes a composite index on all its fields, or a
    /// slug another row holds under another locale of `#[unique(slug, locale)]` reads as taken.
    pub(crate) unique_with: Vec<Vec<String>>,
    /// Whether the field is a relation, which stores no column of its own.
    pub(crate) relation: bool,
}

/// Every named field of `M`'s root, in declaration order.
pub(crate) fn fields<M: toasty::schema::Model>() -> Vec<FieldInfo> {
    let model = M::schema();
    let root = model.as_root_unwrap();
    root.fields
        .iter()
        .filter_map(|field| field_info(field, root))
        .collect()
}

/// Whether `M`'s field `name` is a `#[has_many(via = ..)]`, which stores no column and reads
/// through other relations.
pub(crate) fn is_via<M: toasty::schema::Model>(name: &str) -> bool {
    M::schema().as_root().is_some_and(|root| {
        root.fields.iter().any(|field| {
            field.name.app.as_deref() == Some(name) && matches!(field.ty, app::FieldTy::Via(_))
        })
    })
}

/// Whether `M`'s field `name` stores a list of values in its column: a `Vec` of a scalar.
pub(crate) fn is_list<M: toasty::schema::Model>(name: &str) -> bool {
    M::schema().as_root().is_some_and(|root| {
        root.fields.iter().any(|field| {
            field.name.app.as_deref() == Some(name)
                && matches!(&field.ty, app::FieldTy::Primitive(p) if p.ty.is_list())
        })
    })
}

/// Whether `M`'s field `name` is the inverse side of a relation, `#[has_many]` or `#[has_one]`
/// with or without `via`: it stores nothing on `M`'s rows.
pub(crate) fn is_inverse<M: toasty::schema::Model>(name: &str) -> bool {
    M::schema().as_root().is_some_and(|root| {
        root.fields.iter().any(|field| {
            field.name.app.as_deref() == Some(name)
                && matches!(field.ty, app::FieldTy::Has(_) | app::FieldTy::Via(_))
        })
    })
}

/// The name of `M`'s root field `path` starts at.
pub(crate) fn root_field<M: toasty::schema::Model>(path: &ModelPath) -> Option<String> {
    let index = path.root_step()?;
    M::schema().as_root()?.fields.get(index)?.name.app.clone()
}

/// The one field of `M` a single-step `path` names.
///
/// # Errors
///
/// A traversal path: it has no single field name, and silently binding its first segment
/// misbinds in release.
pub(crate) fn field<M: toasty::schema::Model>(
    path: &ModelPath,
) -> Result<FieldInfo, DeclarationErrorKind> {
    let model = M::schema();
    let root = model.as_root_unwrap();
    let index = single_segment(path)?;
    let field = root.fields.get(index).unwrap_or_else(|| {
        panic!(
            "field index {index} out of bounds for {}",
            std::any::type_name::<M>()
        )
    });
    Ok(field_info(field, root).expect("a model root's fields are named"))
}

fn field_info(field: &app::Field, root: &app::ModelRoot) -> Option<FieldInfo> {
    let name = field.name.app.as_deref()?;
    Some(FieldInfo {
        index: field.id.index,
        name: name.to_string(),
        label: Text::field(belongs_to::label_name(field, root)),
        nullable: field.nullable(),
        unique: root.indices.iter().any(|index| {
            index.unique && !index.primary_key && index.fields.iter().any(|f| f.field == field.id)
        }),
        unique_with: root
            .indices
            .iter()
            .filter(|index| {
                index.unique
                    && !index.primary_key
                    && index.fields.iter().any(|f| f.field == field.id)
            })
            .map(|index| {
                index
                    .fields
                    .iter()
                    .filter(|f| f.field != field.id)
                    .filter_map(|f| root.fields.get(f.field.index)?.name.app.clone())
                    .collect()
            })
            .collect(),
        relation: field.is_relation(),
    })
}

/// The one step a path takes.
///
/// # Errors
///
/// A path of any other length than one.
pub(crate) fn single_segment(path: &ModelPath) -> Result<usize, DeclarationErrorKind> {
    match path.steps() {
        [index] => Ok(*index),
        steps => Err(DeclarationErrorKind::TraversalLens { steps: steps.len() }),
    }
}

/// Which of `M`'s root fields a create fills when no setter does, by field index: `#[auto]`
/// fields, which the database fills, `#[default(..)]` ones, and the `#[version]` field, which
/// Toasty's insert starts at 1.
///
/// Read off `M::Create::default()`, because toasty keeps a `#[default]` in its generated code
/// only, never in the app schema, and the version off the schema, since the insert fills it.
pub(crate) fn prefilled_fields<M: toasty::schema::Model>() -> Vec<bool> {
    let insert = <M::Create as Default>::default().into_insert();
    let toasty_core::stmt::Expr::Stmt(statement) = toasty_core::stmt::Expr::from(insert) else {
        return Vec::new();
    };
    statement
        .stmt
        .as_insert()
        .and_then(|insert| insert.source.body.as_values())
        .and_then(|values| values.rows.last())
        .and_then(|row| row.as_record())
        .map(|record| {
            let model = M::schema();
            (record.fields.iter().zip(model.fields()))
                .map(|(expr, field)| !expr.is_value_null() || field.is_versionable())
                .collect()
        })
        .unwrap_or_default()
}

/// The storage column a lens resolves to, plus the metadata field constructors need.
#[derive(Debug, Clone)]
pub(crate) struct LeafField {
    /// The flattened storage column (`application_seo_title`), or the field's own name for a
    /// single-segment path.
    pub(crate) name: String,
    /// The label a declaration defaults to.
    pub(crate) label: crate::Text,
    /// Whether the leaf is nullable. Every leaf the embedded walk resolves reports `true`,
    /// because only the matching enum variant writes a variant payload's column. That is this
    /// walk's policy rather than the compiled column's own nullability — the flattened column of
    /// a required embedded struct is `NOT NULL` — so it is the *binding* default, not a storage
    /// fact.
    pub(crate) nullable: bool,
    /// Whether a unique index covers the column. Always `false` for an embedded leaf, which
    /// declares no index of its own.
    pub(crate) unique: bool,
    /// Each unique index covering the column, as [`FieldInfo::unique_with`] reads it.
    pub(crate) unique_with: Vec<Vec<String>>,
}

impl From<FieldInfo> for LeafField {
    fn from(field: FieldInfo) -> Self {
        Self {
            label: field.label,
            name: field.name,
            nullable: field.nullable,
            unique: field.unique,
            unique_with: field.unique_with,
        }
    }
}

/// Resolve a single-field path against its own model, which needs no app schema.
///
/// # Errors
///
/// A traversal path.
pub(crate) fn single_field<M: toasty::schema::Model>(
    path: &ModelPath,
) -> Result<LeafField, DeclarationErrorKind> {
    field::<M>(path).map(LeafField::from)
}

/// Resolve an embedded path of the model named `model` through `schema`.
///
/// # Errors
///
/// A path that reaches no single column.
pub(crate) fn embedded_leaf(
    AppSchema(schema): &AppSchema,
    path: &ModelPath,
    model: &'static str,
) -> Result<LeafField, DeclarationErrorKind> {
    walk_embedded(schema, &path.0).ok_or_else(|| DeclarationErrorKind::UnresolvedLens {
        model,
        steps: path.steps().to_vec(),
    })
}

/// Walk a lens path to the physical column it names.
///
/// Two sources, each authoritative for one thing:
///
/// - the **app schema** drives the traversal, because it is the only side that knows a field is a
///   `#[document]` — a *primitive* whose storage is a model, so its inner fields collapse into the
///   one column named after it;
/// - the **compiled mapping** names the column. `Db::schema().mapping` records, per model, which
///   column every field resolves to — flattened embedded structs, enum discriminant and payload
///   columns, shared columns, and a document's single column alike — so this reads the name off
///   `db::Table` rather than re-deriving Toasty's naming rules.
///
/// Two roots reach here: a **model** root for a plain path (`seo.title`), and a **variant** root
/// for an enum payload accessor (`media.video().poster().url()`), where the generated accessor
/// rebases onto the variant and the projection's steps are variant-local.
///
/// Only embedded steps are followed. A relation hop yields `None`: this exists for embedded
/// binding, and binding anything else would reintroduce the misbind the single-segment rule guards
/// against.
fn walk_embedded(
    schema: &toasty_core::Schema,
    path: &toasty_core::stmt::Path,
) -> Option<LeafField> {
    match &path.root {
        PathRoot::Model(id) => {
            let root = schema.app.get_model(*id)?.as_root()?;
            let model = schema.mapping.models.get(&root.id)?;
            descend(
                schema,
                &root.fields,
                &model.fields,
                path.projection.as_slice(),
            )
        }
        // An enum payload: resolve the parent path (it ends at the enum field), then descend into
        // the variant the accessor selected.
        PathRoot::Variant { parent, variant_id } => {
            let root = schema
                .app
                .get_model(parent.root.as_model_unwrap())?
                .as_root()?;
            let model = schema.mapping.models.get(&root.id)?;
            let parent_steps = parent.projection.as_slice();
            // The app side supplies the enum's payload field list, the mapping side its
            // per-variant column mappings.
            let app_field = app_field_at(schema, &root.fields, parent_steps)?;
            let Some(app::Model::EmbeddedEnum(e)) = app_embedded(schema, app_field) else {
                return None;
            };
            let MappingField::Enum(me) = mapping_field_at(&model.fields, parent_steps)? else {
                return None;
            };
            let variant = me.variants.get(variant_id.index)?;
            let payloads: Vec<_> = e.variant_fields(variant_id.index).iter().collect();
            descend(
                schema,
                &payloads,
                &variant.fields,
                path.projection.as_slice(),
            )
        }
    }
}

/// An embedded enum's discriminant column and its variants.
///
/// A variant carries two things, and they are not interchangeable: the **value** its discriminant
/// column stores (`2`, or a string discriminant's own text), which is the form's transport, and
/// the **name** a person reads (`Published`), which is the variant control's label: the message
/// `option-{enum}.{variant}`, else the name in sentence case (`In progress`), as a derived field
/// label is. It is a label, never a handle, since the normalization is lossy (`OK` reads `Ok`).
/// Code addresses variants by **declaration index**, the handle the schema itself uses (`VariantId
/// { index }`).
#[derive(Debug, Clone)]
pub(crate) struct EnumShape {
    /// The discriminant column the form carries (`publication`).
    pub(crate) discriminant: String,
    /// Each variant's stored value and label, in declaration order.
    pub(crate) variants: Vec<(String, Text)>,
}

/// The discriminant column and variants of the embedded **enum** at `path`, or `None` when `path`
/// names anything else.
///
/// [`embedded_leaf`] answers "which column does this one leaf occupy"; this answers "which column
/// carries the variant, and what does each variant store there", which is what an embedded enum's
/// variant control needs. Its payload leaves resolve one at a time through [`embedded_leaf`].
///
/// `path` addresses the embedded field itself (`Post::fields().publication()`), not one of its
/// leaves: a variant-rooted path names a *variant* of a value, not the value, and yields `None`.
pub(crate) fn embedded_enum(schema: &AppSchema, path: &ModelPath) -> Option<EnumShape> {
    let AppSchema(schema) = schema;
    let PathRoot::Model(id) = path.0.root else {
        return None;
    };
    let root = schema.app.get_model(id)?.as_root()?;
    let mapping = schema.mapping.models.get(&root.id)?;
    let steps = path.steps();
    let app_field = app_field_at(schema, &root.fields, steps)?;
    let (app::Model::EmbeddedEnum(e), MappingField::Enum(me)) = (
        app_embedded(schema, app_field)?,
        mapping_field_at(&mapping.fields, steps)?,
    ) else {
        return None;
    };
    let discriminant = column_of(schema, &MappingField::Primitive(me.discriminant.clone()))?.name;
    let variants = e
        .variants
        .iter()
        .map(|v| {
            super::value_text(&v.discriminant).map(|value| {
                (
                    value,
                    Text::option(&e.name.snake_case(), &v.name.snake_case()),
                )
            })
        })
        .collect::<Option<Vec<_>>>()?;
    Some(EnumShape {
        discriminant,
        variants,
    })
}

/// A `mapping::Field`, aliased so the traversal signatures stay readable.
type MappingField = mapping::Field;

/// Walk the path down to the column that stores it.
///
/// `app_fields` and `mapping_fields` are indexed by the same field index, so every step reads
/// both: the app side decides *whether to descend*, the mapping side names *the column*. Neither
/// alone is enough — the mapping cannot say a field is a `#[document]`, and the app schema cannot
/// say which column a leaf occupies without re-deriving Toasty's naming.
fn descend<F>(
    schema: &toasty_core::Schema,
    app_fields: &[F],
    mapping_fields: &[MappingField],
    steps: &[usize],
) -> Option<LeafField>
where
    F: std::borrow::Borrow<app::Field>,
{
    let (first, rest) = steps.split_first()?;
    let app_field: &app::Field = app_fields.get(*first)?.borrow();
    let mapping_field = mapping_fields.get(*first)?;
    // A `#[document]`'s inner fields share its one column, so reaching the document is reaching
    // the leaf, however many steps remain.
    if rest.is_empty() || is_document(app_field) {
        return column_of(schema, mapping_field);
    }
    let app::FieldTy::Embedded(embedded) = &app_field.ty else {
        // A relation hop, or a primitive with steps left over: not an embedded leaf either way.
        return None;
    };
    match schema.app.get_model(embedded.target)? {
        app::Model::EmbeddedStruct(e) => {
            let MappingField::Struct(ms) = mapping_field else {
                return None;
            };
            descend(schema, &e.fields, &ms.fields, rest)
        }
        app::Model::EmbeddedEnum(e) => {
            let MappingField::Enum(me) = mapping_field else {
                return None;
            };
            // A variant consumes two steps: the variant index, then the field.
            let (variant_index, tail) = rest.split_first()?;
            let variant = me.variants.get(*variant_index)?;
            let payloads: Vec<_> = e.variant_fields(*variant_index).iter().collect();
            descend(schema, &payloads, &variant.fields, tail)
        }
        _ => None,
    }
}

/// The column a single mapping field occupies, if it is a leaf.
fn column_of(schema: &toasty_core::Schema, field: &MappingField) -> Option<LeafField> {
    let MappingField::Primitive(p) = field else {
        // A path stopping on a struct or enum names no single column, and a relation stores none.
        return None;
    };
    let column = &schema.db.tables[p.column.table.0].columns[p.column.index];
    Some(LeafField {
        name: column.name.clone(),
        label: crate::Text::field(&column.name),
        // Reported nullable by policy, not read off the column: only the matching enum variant
        // writes a variant payload's column. The compiled column can be `NOT NULL` — an embedded
        // struct's flattened column is.
        nullable: true,
        unique: false,
        unique_with: Vec::new(),
    })
}

/// Whether `field` is a `#[document]`: a *primitive* whose storage is a model, so its inner fields
/// collapse into the one column named after it.
fn is_document(field: &app::Field) -> bool {
    matches!(
        &field.ty,
        app::FieldTy::Primitive(p) if matches!(p.ty, toasty::stmt::Type::Model(_))
    )
}

/// The embedded model an app field targets, if it is embedded.
fn app_embedded<'a>(schema: &'a toasty_core::Schema, field: &app::Field) -> Option<&'a app::Model> {
    let app::FieldTy::Embedded(embedded) = &field.ty else {
        return None;
    };
    schema.app.get_model(embedded.target)
}

mod belongs_to;
mod lookup;
mod reach;
pub(crate) use belongs_to::{BelongsTo, belongs_to, belongs_tos};
use lookup::{app_field_at, mapping_field_at};
pub(crate) use reach::{included_models, read_relations};

#[cfg(test)]
mod tests;