unistore-sqlite 0.1.0

//! # unistore-sqlite: SQLite 嵌入式数据库能力
//!
//! 为用户提供轻量级嵌入式数据库能力，适用于中小型应用。
//!
//! ## 设计哲学
//!
//! - **配置权交付**：提供 SQLite 能力而非强制使用
//! - **零配置启动**：合理的默认配置，开箱即用
//! - **类型安全**：Rust 类型系统保护，减少运行时错误
//!
//! ## 快速开始
//!
//! ```ignore
//! use unistore_sqlite::EmbeddedDb;
//!
//! // 创建应用数据库
//! let db = EmbeddedDb::open("my_inventory")?;
//!
//! // 定义表结构
//! db.migrate(|m| {
//!     m.version(1, "初始化库存表", |s| {
//!         s.create_table("items", |t| {
//!             t.id()
//!              .text_not_null("name")
//!              .integer_not_null("quantity")
//!              .real("price")
//!              .created_at();
//!         })?;
//!         Ok(())
//!     });
//! })?;
//!
//! // 插入数据
//! let item_id = db.insert("items")
//!     .set("name", "笔记本电脑")
//!     .set("quantity", 10)
//!     .set("price", 5999.0)
//!     .execute()?;
//!
//! // 查询数据
//! let items = db.select("items")
//!     .filter("quantity > ?", 0)
//!     .order_desc("created_at")
//!     .fetch_all()?;
//! ```

// ============================================================================
// 内部模块
// ============================================================================

mod config;
mod connection;
mod db;
mod error;
mod migration;
mod query;
mod transaction;
mod types;

// ============================================================================
// 公开 API
// ============================================================================

// 核心类型
pub use db::EmbeddedDb;
pub use error::SqliteError;

// 配置
pub use config::{SqliteConfig, SynchronousMode};

// 类型系统
pub use types::{Param, Row, Rows, SqlValue};

// 查询构建器
pub use query::{DeleteBuilder, InsertBuilder, SelectBuilder, UpdateBuilder};

// 迁移
pub use migration::{
    Migration, MigrationBuilder, MigrationReport, SchemaBuilder, TableBuilder, Migrator,
};

// 事务
pub use transaction::{
    IsolationLevel, Transaction, TransactionState,
    with_transaction, with_immediate_transaction,
};

// 连接状态
pub use connection::ConnectionState;

// ============================================================================
// Capability 实现
// ============================================================================

use async_trait::async_trait;
use unistore_core::{Capability, CapabilityError, CapabilityInfo};

/// SQLite 嵌入式数据库能力
///
/// 实现 `Capability` trait，可被 UniStore 运行时管理
pub struct SqliteCapability {
    db: Option<EmbeddedDb>,
    config: SqliteConfig,
}

impl SqliteCapability {
    /// 创建 SQLite 能力实例（内存数据库）
    pub fn memory() -> Self {
        Self {
            db: None,
            config: SqliteConfig::memory(),
        }
    }

    /// 创建 SQLite 能力实例（文件数据库）
    pub fn file(path: impl Into<std::path::PathBuf>) -> Self {
        Self {
            db: None,
            config: SqliteConfig::file(path),
        }
    }

    /// 使用自定义配置创建
    pub fn with_config(config: SqliteConfig) -> Self {
        Self {
            db: None,
            config,
        }
    }

    /// 获取数据库（能力必须已启动）
    pub fn db(&self) -> Option<&EmbeddedDb> {
        self.db.as_ref()
    }
}

#[async_trait]
impl Capability for SqliteCapability {
    fn info(&self) -> CapabilityInfo {
        CapabilityInfo::new("sqlite", env!("CARGO_PKG_VERSION"))
            .with_description("SQLite embedded database capability")
            .with_author("UniStore Team")
    }

    async fn start(&mut self) -> Result<(), CapabilityError> {
        if self.db.is_some() {
            return Ok(()); // 已启动
        }

        let db = EmbeddedDb::open_with_config("unistore", self.config.clone())
            .map_err(|e: SqliteError| CapabilityError::start_failed("sqlite", e.to_string()))?;
        self.db = Some(db);
        Ok(())
    }

    async fn stop(&mut self) -> Result<(), CapabilityError> {
        self.db = None;
        Ok(())
    }

    async fn health_check(&self) -> Result<(), CapabilityError> {
        match &self.db {
            Some(db) => {
                // 执行简单查询验证连接
                db.execute("SELECT 1", &[])
                    .map_err(|e: SqliteError| CapabilityError::unhealthy("sqlite", e.to_string()))?;
                Ok(())
            }
            None => Err(CapabilityError::unhealthy("sqlite", "数据库未初始化")),
        }
    }
}

// ============================================================================
// 便捷宏
// ============================================================================

/// 参数列表构建宏
///
/// # 示例
/// ```ignore
/// use unistore_sqlite::params;
/// let params = params![1, "hello", 3.14];
/// ```
#[macro_export]
macro_rules! params {
    () => {
        vec![]
    };
    ($($param:expr),+ $(,)?) => {
        vec![$($crate::Param::from($param)),+]
    };
}