postrust_graphql/schema/

relationship.rs

//! Relationship to GraphQL field conversion.

use postrust_core::schema_cache::Relationship;

/// Extract constraint name from a Relationship.
fn get_constraint_name(rel: &Relationship) -> &str {
    match rel {
        Relationship::ForeignKey {
            constraint_name, ..
        } => constraint_name,
        Relationship::Computed { function, .. } => &function.name,
    }
}

/// Represents a GraphQL field derived from a database relationship.
#[derive(Debug, Clone)]
#[non_exhaustive]
pub struct RelationshipField {
    /// Field name (derived from foreign table name).
    pub name: String,
    /// Target GraphQL type name.
    pub target_type: String,
    /// Target base name for generated helper types.
    pub target_local_name: String,
    /// Whether this returns a list (O2M, M2M) or single object (M2O, O2O).
    pub is_list: bool,
    /// The original relationship.
    pub relationship: Relationship,
    /// Description for the field.
    pub description: Option<String>,
    /// The arguments a computed relationship's function takes from the caller,
    /// as `(name, PostgreSQL type, required)`.
    ///
    /// Neither the parent row nor the session is among them: the first is what
    /// makes it a relationship and the second is the server's to supply.
    /// Empty for every relationship reached by a key.
    pub arguments: Vec<(String, String, bool)>,
}

impl RelationshipField {
    /// Create a GraphQL field from a database relationship.
    pub fn from_relationship(rel: &Relationship) -> Self {
        let base_name = rel.foreign_table().name.clone();
        Self::from_relationship_named(rel, &base_name, None)
    }

    /// Create a GraphQL field using an explicit base name for the target.
    ///
    /// The base name must match the one the target table's object type was
    /// generated with, otherwise the field would reference a type that was
    /// never registered.
    pub fn from_relationship_named(
        rel: &Relationship,
        target_base_name: &str,
        given_name: Option<&str>,
    ) -> Self {
        Self::from_relationship_typed(
            rel,
            target_base_name,
            target_base_name,
            target_base_name,
            given_name,
        )
    }

    /// Create a GraphQL field with independent naming for the target object
    /// type and its generated helper types.
    pub fn from_relationship_typed(
        rel: &Relationship,
        target_base_name: &str,
        target_type: &str,
        target_local_name: &str,
        given_name: Option<&str>,
    ) -> Self {
        let is_list = !rel.is_to_one();

        // A computed relationship is named by its function, not by the table
        // it returns. Two functions may return the same table, so the table's
        // name would not tell them apart -- and where the schema also has a
        // foreign key to that table, the derived name is already taken. This
        // is the same rule the REST surface resolves embeds by.
        let name = match given_name {
            // Hasura's relationships are named in metadata rather than derived,
            // and where a schema was migrated from one, the name a client
            // already sends is whatever was written there.
            Some(given) => given.to_string(),
            None => match rel {
                Relationship::Computed { function, .. } => function.name.clone(),
                _ if is_list => pluralize(target_base_name),
                _ => singularize(target_base_name),
            },
        };

        let description = Some(format!(
            "Related {} via {}",
            if is_list { "records" } else { "record" },
            get_constraint_name(rel)
        ));

        Self {
            name,
            target_type: target_type.to_string(),
            target_local_name: target_local_name.to_string(),
            is_list,
            relationship: rel.clone(),
            description,
            arguments: Vec::new(),
        }
    }

    /// Get the GraphQL type string.
    pub fn type_string(&self) -> String {
        if self.is_list {
            format!("[{}!]!", self.target_type)
        } else {
            self.target_type.clone()
        }
    }

    /// Get the join columns for this relationship.
    pub fn join_columns(&self) -> Vec<(String, String)> {
        self.relationship.join_columns()
    }
}

/// Simple pluralization (adds 's' or 'es').
fn pluralize(s: &str) -> String {
    // If already ends with 's' (but not 'ss'), assume it's already plural
    if s.ends_with('s') && !s.ends_with("ss") {
        return s.to_string();
    }

    if s.ends_with('x') || s.ends_with("ch") || s.ends_with("sh") || s.ends_with("ss") {
        format!("{}es", s)
    } else if s.ends_with('y') && !s.ends_with("ey") && !s.ends_with("ay") && !s.ends_with("oy") {
        format!("{}ies", &s[..s.len() - 1])
    } else {
        format!("{}s", s)
    }
}

/// Simple singularization (removes trailing 's').
fn singularize(s: &str) -> String {
    if let Some(stem) = s.strip_suffix("ies") {
        format!("{}y", stem)
    } else if s.ends_with("ses") || s.ends_with("xes") || s.ends_with("ches") || s.ends_with("shes")
    {
        s.strip_suffix("es").unwrap_or(s).to_string()
    } else if s.ends_with('s') && !s.ends_with("ss") {
        s.strip_suffix('s').unwrap_or(s).to_string()
    } else {
        s.to_string()
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use postrust_core::api_request::QualifiedIdentifier;
    use postrust_core::schema_cache::Cardinality;
    use pretty_assertions::assert_eq;

    fn create_m2o_relationship() -> Relationship {
        // orders.user_id -> users.id (Many-to-One)
        Relationship::ForeignKey {
            table: QualifiedIdentifier::new("public", "orders"),
            foreign_table: QualifiedIdentifier::new("public", "users"),
            is_self: false,
            cardinality: Cardinality::M2O {
                constraint: "orders_user_id_fkey".into(),
                columns: vec![("user_id".into(), "id".into())],
            },
            table_is_view: false,
            foreign_table_is_view: false,
            constraint_name: "orders_user_id_fkey".into(),
        }
    }

    fn create_o2m_relationship() -> Relationship {
        // users.id -> orders.user_id (One-to-Many)
        Relationship::ForeignKey {
            table: QualifiedIdentifier::new("public", "users"),
            foreign_table: QualifiedIdentifier::new("public", "orders"),
            is_self: false,
            cardinality: Cardinality::O2M {
                constraint: "orders_user_id_fkey".into(),
                columns: vec![("id".into(), "user_id".into())],
            },
            table_is_view: false,
            foreign_table_is_view: false,
            constraint_name: "orders_user_id_fkey".into(),
        }
    }

    fn create_o2o_relationship() -> Relationship {
        // users.id -> user_profiles.user_id (One-to-One)
        Relationship::ForeignKey {
            table: QualifiedIdentifier::new("public", "users"),
            foreign_table: QualifiedIdentifier::new("public", "user_profiles"),
            is_self: false,
            cardinality: Cardinality::O2O {
                constraint: "user_profiles_user_id_fkey".into(),
                columns: vec![("id".into(), "user_id".into())],
                is_parent: true,
            },
            table_is_view: false,
            foreign_table_is_view: false,
            constraint_name: "user_profiles_user_id_fkey".into(),
        }
    }

    #[test]
    fn test_pluralize() {
        assert_eq!(pluralize("user"), "users");
        assert_eq!(pluralize("order"), "orders");
        assert_eq!(pluralize("category"), "categories");
        assert_eq!(pluralize("box"), "boxes");
        assert_eq!(pluralize("match"), "matches");
        assert_eq!(pluralize("dish"), "dishes");
        assert_eq!(pluralize("key"), "keys"); // 'ey' ending
        assert_eq!(pluralize("day"), "days"); // 'ay' ending
    }

    #[test]
    fn test_singularize() {
        assert_eq!(singularize("users"), "user");
        assert_eq!(singularize("orders"), "order");
        assert_eq!(singularize("categories"), "category");
        assert_eq!(singularize("boxes"), "box");
        assert_eq!(singularize("matches"), "match");
        assert_eq!(singularize("class"), "class"); // ends with 'ss'
    }

    #[test]
    fn test_m2o_relationship_field() {
        let rel = create_m2o_relationship();
        let field = RelationshipField::from_relationship(&rel);

        assert_eq!(field.name, "user"); // Singular for M2O
        assert_eq!(field.target_type, "users");
        assert!(!field.is_list); // Returns single object
    }

    #[test]
    fn test_o2m_relationship_field() {
        let rel = create_o2m_relationship();
        let field = RelationshipField::from_relationship(&rel);

        assert_eq!(field.name, "orders"); // Plural for O2M
        assert_eq!(field.target_type, "orders");
        assert!(field.is_list); // Returns list
    }

    #[test]
    fn test_o2o_relationship_field() {
        let rel = create_o2o_relationship();
        let field = RelationshipField::from_relationship(&rel);

        assert_eq!(field.name, "user_profile"); // Singular for O2O
        assert_eq!(field.target_type, "user_profiles");
        assert!(!field.is_list); // Returns single object
    }

    #[test]
    fn test_relationship_type_string_list() {
        let rel = create_o2m_relationship();
        let field = RelationshipField::from_relationship(&rel);

        assert_eq!(field.type_string(), "[orders!]!");
    }

    #[test]
    fn test_relationship_type_string_single() {
        let rel = create_m2o_relationship();
        let field = RelationshipField::from_relationship(&rel);

        assert_eq!(field.type_string(), "users");
    }

    #[test]
    fn test_relationship_join_columns() {
        let rel = create_m2o_relationship();
        let field = RelationshipField::from_relationship(&rel);

        let columns = field.join_columns();
        assert_eq!(columns.len(), 1);
        assert_eq!(columns[0], ("user_id".into(), "id".into()));
    }

    #[test]
    fn test_relationship_description() {
        let rel = create_m2o_relationship();
        let field = RelationshipField::from_relationship(&rel);

        assert!(field.description.is_some());
        assert!(field
            .description
            .as_ref()
            .unwrap()
            .contains("orders_user_id_fkey"));
    }

    #[test]
    fn test_m2m_relationship_field() {
        // users -> tags via user_tags junction
        let rel = Relationship::ForeignKey {
            table: QualifiedIdentifier::new("public", "users"),
            foreign_table: QualifiedIdentifier::new("public", "tags"),
            is_self: false,
            cardinality: Cardinality::M2M(postrust_core::schema_cache::Junction {
                table: QualifiedIdentifier::new("public", "user_tags"),
                constraint1: "user_tags_user_id_fkey".into(),
                constraint2: "user_tags_tag_id_fkey".into(),
                source_columns: vec![("id".into(), "user_id".into())],
                target_columns: vec![("tag_id".into(), "id".into())],
            }),
            table_is_view: false,
            foreign_table_is_view: false,
            constraint_name: "user_tags_user_id_fkey".into(),
        };

        let field = RelationshipField::from_relationship(&rel);

        assert_eq!(field.name, "tags"); // Plural for M2M
        assert_eq!(field.target_type, "tags");
        assert!(field.is_list);
    }
}