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, TaskPaper)
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//! - `export-taskpaper`: Enable TaskPaper export support
48//! - `export-ical`: Enable iCalendar (.ics) export support
49//! - `observability`: Enable metrics, tracing, and health checks
50//! - `full`: Enable all optional features
51//! - `test-utils`: Enable test utilities (for testing only)
52
53pub mod backup;
54pub mod cache;
55pub mod cache_invalidation_middleware;
56pub mod config;
57pub mod config_hot_reload;
58pub mod config_loader;
59pub mod database;
60pub mod disk_cache;
61pub mod error;
62
63#[cfg(feature = "advanced-queries")]
64pub mod filter_expr;
65
66#[cfg(feature = "batch-operations")]
67pub(crate) mod batch;
68
69#[cfg(feature = "batch-operations")]
70pub mod cursor;
71
72#[cfg(any(
73    feature = "export-csv",
74    feature = "export-opml",
75    feature = "export-taskpaper",
76    feature = "export-ical"
77))]
78pub mod export;
79
80pub mod mcp_cache_middleware;
81pub mod mcp_config;
82pub mod models;
83pub mod mutations;
84
85#[cfg(feature = "observability")]
86pub mod observability;
87
88pub mod performance;
89pub mod query;
90pub mod query_cache;
91pub mod query_performance;
92
93#[cfg(feature = "advanced-queries")]
94pub mod saved_queries;
95
96#[cfg(any(test, feature = "test-utils"))]
97pub mod test_utils;
98
99pub use backup::{BackupManager, BackupMetadata, BackupStats};
100pub use cache::{CacheConfig, CachePreloader, CacheStats, DefaultPreloader, ThingsCache};
101pub use cache_invalidation_middleware::{
102    CacheInvalidationHandler, CacheInvalidationMiddleware, InvalidationConfig, InvalidationEvent,
103    InvalidationEventType, InvalidationRule, InvalidationStats, InvalidationStrategy,
104    ThingsCacheInvalidationHandler,
105};
106pub use config::ThingsConfig;
107pub use config_hot_reload::{
108    ConfigChangeHandler, ConfigHotReloader, ConfigHotReloaderWithHandler,
109    DefaultConfigChangeHandler,
110};
111pub use config_loader::{load_config, load_config_from_env, load_config_with_paths, ConfigLoader};
112pub use database::{
113    get_default_database_path, ComprehensiveHealthStatus, DatabasePoolConfig, DatabaseStats,
114    PoolHealthStatus, PoolMetrics, SqliteOptimizations, ThingsDatabase,
115};
116pub use disk_cache::{DiskCache, DiskCacheConfig, DiskCacheStats};
117pub use error::{Result, ThingsError};
118
119#[cfg(any(
120    feature = "export-csv",
121    feature = "export-opml",
122    feature = "export-taskpaper",
123    feature = "export-ical"
124))]
125pub use export::{DataExporter, ExportConfig, ExportData, ExportFormat};
126
127pub use mcp_cache_middleware::{MCPCacheConfig, MCPCacheEntry, MCPCacheMiddleware, MCPCacheStats};
128pub use mcp_config::McpServerConfig;
129#[cfg(feature = "advanced-queries")]
130pub use models::RankedTask;
131pub use models::{
132    Area, BulkCompleteRequest, BulkCreateTasksRequest, BulkDeleteRequest, BulkMoveRequest,
133    BulkOperationResult, BulkUpdateDatesRequest, CreateAreaRequest, CreateProjectRequest,
134    CreateTagRequest, CreateTaskRequest, DeleteChildHandling, Project, ProjectChildHandling, Tag,
135    TagAssignmentResult, TagCompletion, TagCreationResult, TagMatch, TagMatchType, TagPair,
136    TagStatistics, Task, TaskFilters, TaskStatus, TaskType, ThingsId, UpdateAreaRequest,
137    UpdateProjectRequest, UpdateTagRequest, UpdateTaskRequest,
138};
139#[cfg(target_os = "macos")]
140pub use mutations::AppleScriptBackend;
141pub use mutations::{MutationBackend, SqlxBackend};
142
143#[cfg(feature = "observability")]
144pub use observability::{
145    CheckResult, HealthStatus, ObservabilityConfig, ObservabilityError, ObservabilityManager,
146    ThingsMetrics,
147};
148
149pub use performance::{
150    CacheMetrics, ComprehensivePerformanceSummary, OperationMetrics, PerformanceMonitor,
151    PerformanceStats, PerformanceSummary, QueryMetrics,
152};
153pub use query_cache::{QueryCache, QueryCacheConfig, QueryCacheStats};
154
155#[cfg(feature = "advanced-queries")]
156pub use filter_expr::{FilterExpr, FilterPredicate};
157
158#[cfg(feature = "batch-operations")]
159pub use cursor::{Cursor, Page};
160pub use query_performance::{
161    ImplementationEffort, OptimizationPriority, OptimizationType, QueryContext,
162    QueryOptimizationSuggestion, QueryPerformanceMetrics, QueryPerformanceStats,
163    QueryPerformanceSummary, QueryPerformanceTracker,
164};
165#[cfg(feature = "advanced-queries")]
166pub use saved_queries::{SavedQuery, SavedQueryStore};
167
168/// Re-export commonly used types
169pub use chrono::{DateTime, NaiveDate, Utc};
170pub use serde::{Deserialize, Serialize};
171pub use uuid::Uuid;
things3_core/lib.rs

things3_core/
lib.rs
