microrm/microrm/src/schema/entity.rs

use std::{fmt::Debug, hash::Hash};

use crate::{db::StatementRow, schema::datum::Datum, DBResult};

use super::datum::{ConcreteDatum, ConcreteDatumList, DatumList, QueryEquivalentList};

pub(crate) mod helpers;

/// Integral identifier for an entity.
pub trait EntityID: 'static + PartialEq + Hash + PartialOrd + Debug + Copy + ConcreteDatum {
    /// The entity that this ID is representing.
    type Entity: Entity<ID = Self>;

    /// Construct from a raw integer.
    ///
    /// Do not use this unless you are _very_ certain it is what you want.
    fn from_raw(id: i64) -> Self;
    /// Produces a raw integer from an ID. Of dubious use.
    fn into_raw(self) -> i64;
}

// ----------------------------------------------------------------------
// EntityPart and related types
// ----------------------------------------------------------------------

/// A single data field in an Entity, automatically declared and derived as part of `#[derive(Entity)]`.
pub trait EntityPart: Default + Clone + 'static {
    /// The type of the data field.
    type Datum: ConcreteDatum;
    /// The type of the struct this field is a member of.
    type Entity: Entity;

    /// String representing the field name.
    fn part_name() -> &'static str;
    /// Whether this field has a `#[unique]` attribute or not.
    fn unique() -> bool;
    /// Documentation comment for this field.
    fn desc() -> Option<&'static str>;

    /// Accessor function: given an instance of the outer struct, return this field's value in that instance.
    fn get_datum(from: &Self::Entity) -> &Self::Datum;
}

/// Visitor for traversing all [`EntityPart`]s in an [`Entity`] or [`EntityPartList`].
pub trait EntityPartVisitor {
    /// The [`Entity`] that this visitor will traverse over the parts of.
    type Entity: Entity;
    /// Visit a part, with no instance information.
    fn visit<EP: EntityPart<Entity = Self::Entity>>(&mut self) {}
    /// Visit a part, with a datum reference.
    fn visit_datum<EP: EntityPart<Entity = Self::Entity>>(&mut self, _datum: &EP::Datum) {}
    /// Visit a part, with a mutable datum reference.
    fn visit_datum_mut<EP: EntityPart<Entity = Self::Entity>>(&mut self, _datum: &mut EP::Datum) {}
}

/// List of EntityParts.
pub trait EntityPartList: 'static {
    /// The [`Entity`] that this list represents the parts of.
    type Entity: Entity;
    /// A [`ConcreteDatumList`] type that matches this part list, formed as the `EntityPart::Datum`s of
    /// each `EntityPart` in this list.
    type DatumList: ConcreteDatumList + QueryEquivalentList<Self::DatumList>;
    // + DatumList<ListTail = <Self::ListTail as EntityPartList>::DatumList>;

    /// The first element of this list. If this list is empty, this will be a generic marker type
    /// with poisoned values to be easily visible if processed.
    type ListHead: EntityPart<
        Entity = Self::Entity,
        Datum = <Self::DatumList as DatumList>::ListHead,
    >;
    /// An [`EntityPartList`] that represents all but the first element of this list.
    type ListTail: EntityPartList<
        Entity = Self::Entity,
        DatumList = <Self::DatumList as DatumList>::ListTail,
    >;
    /// Whether the current list is empty. Should be used to control recursion if iterating across
    /// the list.
    const IS_EMPTY: bool = false;

    /// Construct an instance of `Self::DatumList` from a table row.
    fn build_datum_list(stmt: &mut StatementRow) -> DBResult<Self::DatumList>;

    /// Accept a visitor to iterate across each part in the list, with no datum instances.
    fn accept_part_visitor(_: &mut impl EntityPartVisitor<Entity = Self::Entity>);
    /// Accept a visitor to iterate across each part in the list, with datum instances provided by
    /// a `Self::DatumList` instance.
    fn accept_part_visitor_ref(
        datum_list: &Self::DatumList,
        _: &mut impl EntityPartVisitor<Entity = Self::Entity>,
    );
}

// trait implementations for EntityPartList
mod part_list;

/// A sentinel type representing a zero-length [`EntityPartList`].
pub use part_list::EmptyList;

// ----------------------------------------------------------------------
// Entity and related types
// ----------------------------------------------------------------------

/// A single database entity, aka an object type that gets its own table.
pub trait Entity: 'static + std::fmt::Debug {
    /// A list of all the [`EntityPart`]s that make up the fields of the struct.
    type Parts: EntityPartList<Entity = Self>;
    /// A list of the [`EntityPart`]s that make up the list of access keys for the entity. Can be an
    /// [`EmptyList`] if no keys are defined.
    type Keys: EntityPartList<Entity = Self>;
    /// The corresponding [`EntityID`] type for this Entity.
    type ID: EntityID<Entity = Self>;
    /// The [`EntityPart`] type for `Self::ID`.
    type IDPart: EntityPart<Datum = Self::ID, Entity = Self>;

    /// Construct an instance of this entity from a list of datums that matches each part, in
    /// order.
    fn build(values: <Self::Parts as EntityPartList>::DatumList) -> Self;

    /// A static string used as the database table name for the entity.
    fn entity_name() -> &'static str;
    /// Accept a visitor to iterate across each part in the entity, with no datum instances.
    fn accept_part_visitor(visitor: &mut impl EntityPartVisitor<Entity = Self>);
    /// Accept a visitor to iterate across each part in the entity, with datum instances pulled
    /// from an instance of `Self`.
    fn accept_part_visitor_ref(&self, visitor: &mut impl EntityPartVisitor<Entity = Self>);
    /// Accept a visitor to iterate across each part in the entity, with mutable datum instances
    /// pulled from an instance of `Self`.
    fn accept_part_visitor_mut(&mut self, _: &mut impl EntityPartVisitor<Entity = Self>);
}

/// Visitor for traversing all [`Entity`]s in a container type.
pub trait EntityVisitor {
    /// Visit a particular entity.
    fn visit<E: Entity>(&mut self);
}

// ----------------------------------------------------------------------
// EntityList and related types
// ----------------------------------------------------------------------

/// A list of [`Entity`] types.
pub trait EntityList {
    const LEN: usize;

    fn accept_visitor<EV: EntityVisitor>(visitor: &mut EV);
}