things3_core/
lib.rs

1//! Things Core - Core library for Things 3 database access and data models
2//!
3//! This library provides high-performance access to the Things 3 database,
4//! with comprehensive data models and efficient querying capabilities.
5//!
6//! # Features
7//!
8//! - **Async Database Access**: Built on SQLx for type-safe, async database operations
9//! - **Comprehensive Data Models**: Full support for Tasks, Projects, Areas, and Tags
10//! - **Bulk Operations**: Efficient batch operations with transactional guarantees
11//! - **Caching Layer**: High-performance caching with configurable TTL
12//! - **Export Support**: Multiple export formats (JSON, CSV, OPML, Markdown)
13//! - **Observability**: Built-in metrics, logging, and health checks
14//! - **Performance Monitoring**: Query performance tracking and optimization suggestions
15//!
16//! # Quick Start
17//!
18//! ```no_run
19//! use things3_core::{ThingsDatabase, ThingsError};
20//! use std::path::Path;
21//!
22//! # async fn example() -> Result<(), ThingsError> {
23//! // Connect to Things 3 database
24//! let db = ThingsDatabase::new(Path::new("/path/to/things.db")).await?;
25//!
26//! // Get inbox tasks
27//! let tasks = db.get_inbox(None).await?;
28//! println!("Found {} tasks in inbox", tasks.len());
29//!
30//! // Search for tasks
31//! let results = db.search_tasks("meeting").await?;
32//! println!("Found {} matching tasks", results.len());
33//! # Ok(())
34//! # }
35//! ```
36//!
37//! # Examples
38//!
39//! See the [examples directory](https://github.com/GarthDB/rust-things3/tree/main/examples)
40//! for more comprehensive usage examples.
41//!
42//! # Crate Features
43//!
44//! - `default`: Minimal feature set (core functionality only)
45//! - `export-csv`: Enable CSV export support
46//! - `export-opml`: Enable OPML export support
47//! - `observability`: Enable metrics, tracing, and health checks
48//! - `full`: Enable all optional features
49//! - `test-utils`: Enable test utilities (for testing only)
50
51pub mod backup;
52pub mod cache;
53pub mod cache_invalidation_middleware;
54pub mod config;
55pub mod config_hot_reload;
56pub mod config_loader;
57pub mod database;
58pub mod disk_cache;
59pub mod error;
60
61#[cfg(feature = "advanced-queries")]
62pub mod filter_expr;
63
64#[cfg(feature = "batch-operations")]
65pub(crate) mod batch;
66
67#[cfg(feature = "batch-operations")]
68pub mod cursor;
69
70#[cfg(any(feature = "export-csv", feature = "export-opml"))]
71pub mod export;
72
73pub mod mcp_cache_middleware;
74pub mod mcp_config;
75pub mod models;
76
77#[cfg(feature = "observability")]
78pub mod observability;
79
80pub mod performance;
81pub mod query;
82pub mod query_cache;
83pub mod query_performance;
84
85#[cfg(feature = "advanced-queries")]
86pub mod saved_queries;
87
88#[cfg(any(test, feature = "test-utils"))]
89pub mod test_utils;
90
91pub use backup::{BackupManager, BackupMetadata, BackupStats};
92pub use cache::{CacheConfig, CachePreloader, CacheStats, DefaultPreloader, ThingsCache};
93pub use cache_invalidation_middleware::{
94    CacheInvalidationHandler, CacheInvalidationMiddleware, InvalidationConfig, InvalidationEvent,
95    InvalidationEventType, InvalidationRule, InvalidationStats, InvalidationStrategy,
96    ThingsCacheInvalidationHandler,
97};
98pub use config::ThingsConfig;
99pub use config_hot_reload::{
100    ConfigChangeHandler, ConfigHotReloader, ConfigHotReloaderWithHandler,
101    DefaultConfigChangeHandler,
102};
103pub use config_loader::{load_config, load_config_from_env, load_config_with_paths, ConfigLoader};
104pub use database::{
105    get_default_database_path, ComprehensiveHealthStatus, DatabasePoolConfig, DatabaseStats,
106    PoolHealthStatus, PoolMetrics, SqliteOptimizations, ThingsDatabase,
107};
108pub use disk_cache::{DiskCache, DiskCacheConfig, DiskCacheStats};
109pub use error::{Result, ThingsError};
110
111#[cfg(any(feature = "export-csv", feature = "export-opml"))]
112pub use export::{DataExporter, ExportConfig, ExportData, ExportFormat};
113
114pub use mcp_cache_middleware::{MCPCacheConfig, MCPCacheEntry, MCPCacheMiddleware, MCPCacheStats};
115pub use mcp_config::McpServerConfig;
116pub use models::*;
117// Explicitly re-export DeleteChildHandling for clarity
118pub use models::DeleteChildHandling;
119
120#[cfg(feature = "observability")]
121pub use observability::{
122    CheckResult, HealthStatus, ObservabilityConfig, ObservabilityError, ObservabilityManager,
123    ThingsMetrics,
124};
125
126pub use performance::{
127    CacheMetrics, ComprehensivePerformanceSummary, OperationMetrics, PerformanceMonitor,
128    PerformanceStats, PerformanceSummary, QueryMetrics,
129};
130pub use query_cache::{QueryCache, QueryCacheConfig, QueryCacheStats};
131
132#[cfg(feature = "advanced-queries")]
133pub use filter_expr::{FilterExpr, FilterPredicate};
134
135#[cfg(feature = "batch-operations")]
136pub use cursor::{Cursor, Page};
137pub use query_performance::{
138    ImplementationEffort, OptimizationPriority, OptimizationType, QueryContext,
139    QueryOptimizationSuggestion, QueryPerformanceMetrics, QueryPerformanceStats,
140    QueryPerformanceSummary, QueryPerformanceTracker,
141};
142#[cfg(feature = "advanced-queries")]
143pub use saved_queries::{SavedQuery, SavedQueryStore};
144
145/// Re-export commonly used types
146pub use chrono::{DateTime, NaiveDate, Utc};
147pub use serde::{Deserialize, Serialize};
148pub use uuid::Uuid;
things3_core/lib.rs

things3_core/
lib.rs
