mongo-collection 0.3.3

A trait and derive macro for mapping Rust types to MongoDB collections with automatic pluralization
Documentation
use mongodb::bson::{doc, Document};

/// Lookup 构建器,用于构建 MongoDB $lookup 聚合阶段
///
/// $lookup 用于执行左外连接操作,从另一个集合中获取相关文档
///
/// # 示例
///
/// ```ignore
/// use mongo_collection::aggregate::LookupBuilder;
///
/// // 基本用法:关联订单
/// let lookup = LookupBuilder::new("orders", "_id", "user_id", "user_orders")
///     .build();
///
/// // 带子管道过滤
/// let lookup = LookupBuilder::new("orders", "_id", "user_id", "orders")
///     .with_pipeline(vec![
///         doc! { "$match": { "status": "completed" } },
///         doc! { "$sort": { "created_at": -1 } }
///     ])
///     .build();
///
/// // 一对一关系,展开数组为单个对象
/// let lookup = LookupBuilder::new("profiles", "_id", "user_id", "profile")
///     .unwind()
///     .build();
/// ```
pub struct LookupBuilder {
    from: String,
    local_field: String,
    foreign_field: String,
    as_field: String,
    pipeline: Option<Vec<Document>>,
    unwind: bool,
    preserve_null: bool,
}

impl LookupBuilder {
    /// 创建新的 Lookup 构建器
    ///
    /// # 参数
    ///
    /// * `from` - 要关联的集合名称
    /// * `local_field` - 本地集合中的字段名
    /// * `foreign_field` - 外部集合中的字段名
    /// * `as_field` - 关联结果存储的字段名
    ///
    /// # 示例
    ///
    /// ```ignore
    /// // 将 users._id 关联到 orders.user_id,结果存储在 user_orders 字段
    /// let lookup = LookupBuilder::new("orders", "_id", "user_id", "user_orders");
    /// ```
    pub fn new(from: &str, local_field: &str, foreign_field: &str, as_field: &str) -> Self {
        Self {
            from: from.to_string(),
            local_field: local_field.to_string(),
            foreign_field: foreign_field.to_string(),
            as_field: as_field.to_string(),
            pipeline: None,
            unwind: false,
            preserve_null: false,
        }
    }

    /// 添加子管道,用于过滤或处理关联的文档
    ///
    /// # 参数
    ///
    /// * `pipeline` - 聚合管道阶段数组
    ///
    /// # 示例
    ///
    /// ```ignore
    /// let lookup = LookupBuilder::new("orders", "_id", "user_id", "orders")
    ///     .with_pipeline(vec![
    ///         doc! { "$match": { "status": "completed" } },
    ///         doc! { "$sort": { "created_at": -1 } },
    ///         doc! { "$limit": 10 }
    ///     ]);
    /// ```
    pub fn with_pipeline(mut self, pipeline: Vec<Document>) -> Self {
        self.pipeline = Some(pipeline);
        self
    }

    /// 自动展开关联结果数组为单个对象
    ///
    /// 适用于一对一关系,将结果数组的第一个元素提取出来
    ///
    /// # 示例
    ///
    /// ```ignore
    /// // 用户只有一个个人资料,展开为单个对象而不是数组
    /// let lookup = LookupBuilder::new("profiles", "_id", "user_id", "profile")
    ///     .unwind();
    /// ```
    pub fn unwind(mut self) -> Self {
        self.unwind = true;
        self
    }

    /// 展开时保留 null 值和空数组
    ///
    /// 当关联的文档不存在时,保留该记录并将关联字段设为 null
    ///
    /// # 示例
    ///
    /// ```ignore
    /// let lookup = LookupBuilder::new("profiles", "_id", "user_id", "profile")
    ///     .unwind()
    ///     .preserve_null_and_empty();
    /// ```
    pub fn preserve_null_and_empty(mut self) -> Self {
        self.preserve_null = true;
        self
    }

    /// 构建 $lookup 阶段文档
    ///
    /// 如果设置了 unwind,返回包含 $lookup 和 $unwind 的多个阶段
    ///
    /// # 返回值
    ///
    /// 返回一个或多个聚合阶段的 Document 数组
    pub fn build(self) -> Vec<Document> {
        let mut stages = Vec::new();

        // 构建 $lookup 阶段
        let mut lookup_doc = doc! {
            "$lookup": {
                "from": self.from,
                "localField": self.local_field,
                "foreignField": self.foreign_field,
                "as": self.as_field.clone()
            }
        };

        // 如果有子管道,添加到 lookup 中
        if let Some(pipeline) = self.pipeline {
            if let Some(lookup_obj) = lookup_doc.get_document_mut("$lookup").ok() {
                lookup_obj.insert("pipeline", pipeline);
            }
        }

        stages.push(lookup_doc);

        // 如果需要展开,添加 $unwind 阶段
        if self.unwind {
            let unwind_doc = if self.preserve_null {
                doc! {
                    "$unwind": {
                        "path": format!("${}", self.as_field),
                        "preserveNullAndEmptyArrays": true
                    }
                }
            } else {
                doc! {
                    "$unwind": format!("${}", self.as_field)
                }
            };
            stages.push(unwind_doc);
        }

        stages
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_basic_lookup() {
        let stages = LookupBuilder::new("orders", "_id", "user_id", "user_orders").build();

        assert_eq!(stages.len(), 1);
        let lookup = stages[0].get_document("$lookup").unwrap();
        assert_eq!(lookup.get_str("from").unwrap(), "orders");
        assert_eq!(lookup.get_str("localField").unwrap(), "_id");
        assert_eq!(lookup.get_str("foreignField").unwrap(), "user_id");
        assert_eq!(lookup.get_str("as").unwrap(), "user_orders");
    }

    #[test]
    fn test_lookup_with_unwind() {
        let stages = LookupBuilder::new("profiles", "_id", "user_id", "profile")
            .unwind()
            .build();

        assert_eq!(stages.len(), 2);
        assert!(stages[0].contains_key("$lookup"));
        assert!(stages[1].contains_key("$unwind"));
    }

    #[test]
    fn test_lookup_with_preserve_null() {
        let stages = LookupBuilder::new("profiles", "_id", "user_id", "profile")
            .unwind()
            .preserve_null_and_empty()
            .build();

        assert_eq!(stages.len(), 2);
        let unwind = stages[1].get_document("$unwind").unwrap();
        assert_eq!(
            unwind.get_bool("preserveNullAndEmptyArrays").unwrap(),
            true
        );
    }

    #[test]
    fn test_lookup_with_pipeline() {
        let stages = LookupBuilder::new("orders", "_id", "user_id", "orders")
            .with_pipeline(vec![
                doc! { "$match": { "status": "completed" } },
                doc! { "$limit": 10 },
            ])
            .build();

        assert_eq!(stages.len(), 1);
        let lookup = stages[0].get_document("$lookup").unwrap();
        assert!(lookup.contains_key("pipeline"));
    }
}