aven_core/
query.rs

1use anyhow::{Result, bail};
2use chrono::{DateTime, Utc};
3
4use crate::choices::TaskStatus;
5use crate::db::Database;
6use crate::ids::{TaskId, WorkspaceId};
7use crate::recurrence::RecurrenceSeriesId;
8use crate::refs::DisplayRefContext;
9use crate::types::Task;
10
11mod database_stats;
12mod dependencies;
13mod details;
14mod doctor;
15pub mod fragments;
16mod hydration;
17mod projects;
18mod recent_actions;
19mod recurrence;
20mod related;
21mod search;
22mod sidebar;
23mod sorting;
24mod sync_history;
25mod tasks;
26#[cfg(test)]
27mod test_support;
28mod types;
29
30pub use database_stats::{DatabaseStats, DatabaseStatsPriorityCounts, DatabaseStatsStatusCounts};
31pub use dependencies::{TaskDependencyItem, TaskDependencySummary};
32pub(crate) use dependencies::{task_dependency_summary, task_dependency_summary_with_display_refs};
33pub use details::{TaskDetail, TaskDetailConflict};
34pub(crate) use details::{conflict_display_value, task_detail, task_detail_with_display_refs};
35pub use doctor::WorkspaceTaskCounts;
36pub(crate) use doctor::{unresolved_conflict_count, workspace_task_counts};
37pub(crate) use projects::list_project_items_in_workspace;
38pub(crate) use recent_actions::{
39    list_recent_actions_in_workspace, task_activity_for_tasks_in_workspace,
40};
41pub(crate) use recurrence::task_recurrence_summaries;
42pub use related::TaskRelatedLink;
43pub(crate) use related::{related_links_for_tasks, task_related_links};
44pub use search::{
45    SearchMatchedField, TaskSearchPreviewResultSet, TaskSearchQuery, TaskSearchResult,
46};
47pub(crate) use search::{
48    search_task_items_in_workspace, search_task_occurrence_items_in_workspace,
49    search_task_preview_set_in_workspace,
50};
51pub(crate) use sidebar::sidebar_counts_for_scope_in_workspace;
52pub use sync_history::SyncHistoryStats;
53pub(crate) use sync_history::sync_history_stats;
54pub(crate) use tasks::{
55    list_bulk_update_task_items_in_workspace, list_task_items_in_workspace,
56    list_task_items_with_display_refs, list_task_items_without_activity_in_workspace,
57    list_task_summary_items_in_workspace,
58};
59pub use types::RecentActionTarget;
60pub use types::{
61    AttachmentMetadata, EpicRollup, MetadataFilter, ProjectListItem, RecentActionItem,
62    RecurrenceCounts, RecurrenceHistoryEntry, RecurrenceHistoryKind, RecurrenceHistoryPage,
63    RecurrenceOccurrenceLink, RecurrenceReconciliation, RecurrenceSeriesConflict,
64    RecurrenceSeriesDetail, RecurrenceSeriesLifecycleFilter, RecurrenceSeriesListItem,
65    RecurrenceSeriesListQuery, RecurrenceSeriesSummary, RecurrenceTaskGroup, SidebarCounts,
66    SortDirection, TaskAvailabilityFilter, TaskDependencyLink, TaskFilters, TaskIdFilter,
67    TaskItemHydration, TaskListItem, TaskNote, TaskQueryMode, TaskRecurrenceSummary, TaskSort,
68};
69
70pub const MAX_RECURRENCE_HISTORY_LIMIT: usize = 500;
71
72pub(crate) fn status_order(status: TaskStatus) -> u8 {
73    match status {
74        TaskStatus::Active => 0,
75        TaskStatus::Todo => 1,
76        TaskStatus::Inbox => 2,
77        TaskStatus::Backlog => 3,
78        TaskStatus::Done => 4,
79        TaskStatus::Canceled => 5,
80    }
81}
82
83fn validate_search_limit(limit: usize) -> Result<()> {
84    if limit == 0 {
85        bail!("error search-limit-invalid limit=0 min=1 hint=\"pass a limit of 1 or greater\"");
86    }
87    Ok(())
88}
89
90fn validate_recurrence_history_limit(limit: usize) -> Result<()> {
91    if !(1..=MAX_RECURRENCE_HISTORY_LIMIT).contains(&limit) {
92        bail!(
93            "error recurrence-history-limit-invalid limit={} min=1 max={} hint=\"pass a limit between 1 and {}\"",
94            limit,
95            MAX_RECURRENCE_HISTORY_LIMIT,
96            MAX_RECURRENCE_HISTORY_LIMIT
97        );
98    }
99    Ok(())
100}
101
102impl Database {
103    /// Reconciles recurrence projections before a report reads current state.
104    ///
105    /// The candidate count is bounded. Each changed series writes one atomic projection
106    /// transaction that can archive one superseded task and materialize one successor.
107    pub async fn reconcile_recurrence_reports_at(
108        &self,
109        workspace_id: &WorkspaceId,
110        at: DateTime<Utc>,
111    ) -> Result<RecurrenceReconciliation> {
112        let (workspace, candidates, incomplete) = {
113            let mut conn = self.acquire_reader().await?;
114            let workspace = crate::workspaces::workspace_for_id(&mut conn, workspace_id).await?;
115            let (candidates, incomplete) =
116                recurrence::recurrence_reconciliation_candidates(&mut conn, workspace_id, at)
117                    .await?;
118            (workspace, candidates, incomplete)
119        };
120        let mut report = RecurrenceReconciliation {
121            workspace_id: Some(workspace_id.clone()),
122            examined: candidates.len(),
123            incomplete,
124            ..RecurrenceReconciliation::default()
125        };
126        for series_id in candidates {
127            let result = self
128                .reconcile_recurrence_series(&workspace, &series_id, at)
129                .await?;
130            report.changed += usize::from(result.changed);
131            report.lifecycle_blocked += usize::from(result.lifecycle_blocked);
132        }
133        recurrence::validate_reconciliation(&report)?;
134        Ok(report)
135    }
136
137    pub async fn reconcile_recurrence_reports(
138        &self,
139        workspace_id: &WorkspaceId,
140    ) -> Result<RecurrenceReconciliation> {
141        let at = crate::ids::now_utc();
142        self.reconcile_recurrence_reports_at(workspace_id, at).await
143    }
144
145    pub async fn list_recurrence_series_view_at(
146        &self,
147        workspace_id: &WorkspaceId,
148        at: DateTime<Utc>,
149        query: RecurrenceSeriesListQuery,
150    ) -> Result<Vec<RecurrenceSeriesListItem>> {
151        self.reconcile_recurrence_reports_at(workspace_id, at)
152            .await?;
153        self.list_recurrence_series_view_from_current_projection(workspace_id, query)
154            .await
155    }
156
157    /// Reads the persisted recurrence projection as-is.
158    ///
159    /// Callers establish projection currency by reconciling the workspace for the report snapshot.
160    #[doc(hidden)]
161    pub async fn list_recurrence_series_view_from_current_projection(
162        &self,
163        workspace_id: &WorkspaceId,
164        query: RecurrenceSeriesListQuery,
165    ) -> Result<Vec<RecurrenceSeriesListItem>> {
166        let mut conn = self.acquire_reader().await?;
167        recurrence::list_recurrence_series_view(&mut conn, workspace_id, &query).await
168    }
169
170    pub async fn list_recurrence_series_view(
171        &self,
172        workspace_id: &WorkspaceId,
173        query: RecurrenceSeriesListQuery,
174    ) -> Result<Vec<RecurrenceSeriesListItem>> {
175        let at = crate::ids::now_utc();
176        self.list_recurrence_series_view_at(workspace_id, at, query)
177            .await
178    }
179
180    pub async fn list_recurrence_series_at(
181        &self,
182        workspace_id: &WorkspaceId,
183        at: DateTime<Utc>,
184    ) -> Result<Vec<RecurrenceSeriesSummary>> {
185        self.reconcile_recurrence_reports_at(workspace_id, at)
186            .await?;
187        let mut conn = self.acquire_reader().await?;
188        recurrence::list_recurrence_series(&mut conn, workspace_id, at).await
189    }
190
191    pub async fn recurrence_series_detail_at(
192        &self,
193        workspace_id: &WorkspaceId,
194        series_id: &RecurrenceSeriesId,
195        at: DateTime<Utc>,
196    ) -> Result<RecurrenceSeriesDetail> {
197        self.reconcile_recurrence_reports_at(workspace_id, at)
198            .await?;
199        self.recurrence_series_detail_at_from_current_projection(workspace_id, series_id, at)
200            .await
201    }
202
203    /// Reads the persisted recurrence projection as-is.
204    ///
205    /// Callers establish projection currency by reconciling the workspace for the report snapshot.
206    #[doc(hidden)]
207    pub async fn recurrence_series_detail_at_from_current_projection(
208        &self,
209        workspace_id: &WorkspaceId,
210        series_id: &RecurrenceSeriesId,
211        at: DateTime<Utc>,
212    ) -> Result<RecurrenceSeriesDetail> {
213        let mut conn = self.acquire_reader().await?;
214        recurrence::recurrence_series_detail(&mut conn, workspace_id, series_id, at).await
215    }
216
217    pub async fn recurrence_history_at(
218        &self,
219        workspace_id: &WorkspaceId,
220        series_id: &RecurrenceSeriesId,
221        at: DateTime<Utc>,
222        offset: usize,
223        limit: usize,
224    ) -> Result<RecurrenceHistoryPage> {
225        validate_recurrence_history_limit(limit)?;
226        self.reconcile_recurrence_reports_at(workspace_id, at)
227            .await?;
228        let mut conn = self.acquire_reader().await?;
229        recurrence::recurrence_history(&mut conn, workspace_id, series_id, at, offset, limit).await
230    }
231
232    pub async fn list_recurrence_series(
233        &self,
234        workspace_id: &WorkspaceId,
235    ) -> Result<Vec<RecurrenceSeriesSummary>> {
236        let at = crate::ids::now_utc();
237        self.list_recurrence_series_at(workspace_id, at).await
238    }
239
240    pub async fn recurrence_series_detail(
241        &self,
242        workspace_id: &WorkspaceId,
243        series_id: &RecurrenceSeriesId,
244    ) -> Result<RecurrenceSeriesDetail> {
245        let at = crate::ids::now_utc();
246        self.recurrence_series_detail_at(workspace_id, series_id, at)
247            .await
248    }
249
250    /// Reads the persisted recurrence projection as-is.
251    ///
252    /// Callers establish projection currency by reconciling the workspace for the report snapshot.
253    #[doc(hidden)]
254    pub async fn recurrence_series_detail_from_current_projection(
255        &self,
256        workspace_id: &WorkspaceId,
257        series_id: &RecurrenceSeriesId,
258    ) -> Result<RecurrenceSeriesDetail> {
259        let at = crate::ids::now_utc();
260        self.recurrence_series_detail_at_from_current_projection(workspace_id, series_id, at)
261            .await
262    }
263
264    pub async fn recurrence_history(
265        &self,
266        workspace_id: &WorkspaceId,
267        series_id: &RecurrenceSeriesId,
268        offset: usize,
269        limit: usize,
270    ) -> Result<RecurrenceHistoryPage> {
271        let at = crate::ids::now_utc();
272        self.recurrence_history_at(workspace_id, series_id, at, offset, limit)
273            .await
274    }
275
276    pub async fn list_project_items(
277        &self,
278        workspace_id: &WorkspaceId,
279    ) -> Result<Vec<ProjectListItem>> {
280        self.reconcile_recurrence_reports(workspace_id).await?;
281        self.list_project_items_from_current_projection(workspace_id)
282            .await
283    }
284
285    /// Reads the persisted recurrence projection as-is.
286    ///
287    /// Callers establish projection currency by reconciling the workspace for the report snapshot.
288    #[doc(hidden)]
289    pub async fn list_project_items_from_current_projection(
290        &self,
291        workspace_id: &WorkspaceId,
292    ) -> Result<Vec<ProjectListItem>> {
293        let mut conn = self.acquire_reader().await?;
294        list_project_items_in_workspace(&mut conn, workspace_id).await
295    }
296
297    pub async fn list_task_items(
298        &self,
299        workspace_id: &WorkspaceId,
300        filters: TaskFilters,
301        mode: TaskQueryMode,
302        sort: TaskSort,
303        direction: SortDirection,
304    ) -> Result<Vec<TaskListItem>> {
305        self.reconcile_recurrence_reports(workspace_id).await?;
306        self.list_task_items_from_current_projection(workspace_id, filters, mode, sort, direction)
307            .await
308    }
309
310    pub async fn list_bulk_update_task_items(
311        &self,
312        workspace_id: &WorkspaceId,
313        filters: TaskFilters,
314        mode: TaskQueryMode,
315        sort: TaskSort,
316        direction: SortDirection,
317    ) -> Result<Vec<TaskListItem>> {
318        self.reconcile_recurrence_reports(workspace_id).await?;
319        let mut conn = self.acquire_reader().await?;
320        list_bulk_update_task_items_in_workspace(
321            &mut conn,
322            workspace_id,
323            filters,
324            mode,
325            sort,
326            direction,
327        )
328        .await
329    }
330
331    /// Reads the persisted recurrence projection as-is.
332    ///
333    /// Callers establish projection currency by reconciling the workspace for the report snapshot.
334    #[doc(hidden)]
335    pub async fn list_task_items_from_current_projection(
336        &self,
337        workspace_id: &WorkspaceId,
338        filters: TaskFilters,
339        mode: TaskQueryMode,
340        sort: TaskSort,
341        direction: SortDirection,
342    ) -> Result<Vec<TaskListItem>> {
343        let mut conn = self.acquire_reader().await?;
344        list_task_items_in_workspace(&mut conn, workspace_id, filters, mode, sort, direction).await
345    }
346
347    pub async fn list_task_items_without_activity_from_current_projection(
348        &self,
349        workspace_id: &WorkspaceId,
350        filters: TaskFilters,
351        mode: TaskQueryMode,
352        sort: TaskSort,
353        direction: SortDirection,
354    ) -> Result<Vec<TaskListItem>> {
355        let mut conn = self.acquire_reader().await?;
356        list_task_items_without_activity_in_workspace(
357            &mut conn,
358            workspace_id,
359            filters,
360            mode,
361            sort,
362            direction,
363        )
364        .await
365    }
366
367    pub async fn list_task_summary_items(
368        &self,
369        workspace_id: &WorkspaceId,
370        filters: TaskFilters,
371        mode: TaskQueryMode,
372        sort: TaskSort,
373        direction: SortDirection,
374        limit: Option<usize>,
375    ) -> Result<Vec<TaskListItem>> {
376        self.reconcile_recurrence_reports(workspace_id).await?;
377        self.list_task_summary_items_from_current_projection(
378            workspace_id,
379            filters,
380            mode,
381            sort,
382            direction,
383            limit,
384        )
385        .await
386    }
387
388    /// Reads the persisted task projection as-is.
389    ///
390    /// Callers establish projection currency by reconciling the workspace for the report snapshot.
391    #[doc(hidden)]
392    pub async fn list_task_summary_items_from_current_projection(
393        &self,
394        workspace_id: &WorkspaceId,
395        filters: TaskFilters,
396        mode: TaskQueryMode,
397        sort: TaskSort,
398        direction: SortDirection,
399        limit: Option<usize>,
400    ) -> Result<Vec<TaskListItem>> {
401        let mut conn = self.acquire_reader().await?;
402        list_task_summary_items_in_workspace(
403            &mut conn,
404            workspace_id,
405            filters,
406            mode,
407            sort,
408            direction,
409            limit,
410        )
411        .await
412    }
413
414    pub async fn sidebar_counts_for_scope(
415        &self,
416        workspace_id: &WorkspaceId,
417        project_key: Option<&str>,
418    ) -> Result<SidebarCounts> {
419        self.reconcile_recurrence_reports(workspace_id).await?;
420        self.sidebar_counts_for_scope_from_current_projection(workspace_id, project_key)
421            .await
422    }
423
424    /// Reads the persisted recurrence projection as-is.
425    ///
426    /// Callers establish projection currency by reconciling the workspace for the report snapshot.
427    #[doc(hidden)]
428    pub async fn sidebar_counts_for_scope_from_current_projection(
429        &self,
430        workspace_id: &WorkspaceId,
431        project_key: Option<&str>,
432    ) -> Result<SidebarCounts> {
433        let mut conn = self.acquire_reader().await?;
434        sidebar_counts_for_scope_in_workspace(&mut conn, workspace_id, project_key).await
435    }
436
437    pub async fn list_recent_actions(
438        &self,
439        workspace_id: &WorkspaceId,
440        project_scope: Option<&str>,
441    ) -> Result<Vec<RecentActionItem>> {
442        self.reconcile_recurrence_reports(workspace_id).await?;
443        self.list_recent_actions_from_current_projection(workspace_id, project_scope)
444            .await
445    }
446
447    /// Reads the persisted recurrence projection as-is.
448    ///
449    /// Callers establish projection currency by reconciling the workspace for the report snapshot.
450    #[doc(hidden)]
451    pub async fn list_recent_actions_from_current_projection(
452        &self,
453        workspace_id: &WorkspaceId,
454        project_scope: Option<&str>,
455    ) -> Result<Vec<RecentActionItem>> {
456        let mut conn = self.acquire_reader().await?;
457        list_recent_actions_in_workspace(&mut conn, workspace_id, project_scope).await
458    }
459
460    pub async fn task_activity_for_task(
461        &self,
462        workspace_id: &WorkspaceId,
463        task_id: &TaskId,
464    ) -> Result<Vec<RecentActionItem>> {
465        let mut conn = self.acquire_reader().await?;
466        Ok(task_activity_for_tasks_in_workspace(
467            &mut conn,
468            workspace_id,
469            std::slice::from_ref(task_id),
470        )
471        .await?
472        .remove(task_id)
473        .unwrap_or_default())
474    }
475
476    pub async fn search_task_items(
477        &self,
478        workspace_id: &WorkspaceId,
479        query: TaskSearchQuery,
480    ) -> Result<Vec<TaskSearchResult>> {
481        validate_search_limit(query.limit)?;
482        self.reconcile_recurrence_reports(workspace_id).await?;
483        let mut conn = self.acquire_reader().await?;
484        search_task_items_in_workspace(&mut conn, workspace_id, query).await
485    }
486
487    pub async fn search_task_occurrence_items(
488        &self,
489        workspace_id: &WorkspaceId,
490        query: TaskSearchQuery,
491    ) -> Result<Vec<TaskSearchResult>> {
492        validate_search_limit(query.limit)?;
493        self.reconcile_recurrence_reports(workspace_id).await?;
494        let mut conn = self.acquire_reader().await?;
495        search_task_occurrence_items_in_workspace(&mut conn, workspace_id, query).await
496    }
497
498    pub async fn search_task_preview_set(
499        &self,
500        workspace_id: &WorkspaceId,
501        query: TaskSearchQuery,
502    ) -> Result<TaskSearchPreviewResultSet> {
503        validate_search_limit(query.limit)?;
504        self.reconcile_recurrence_reports(workspace_id).await?;
505        self.search_task_preview_set_from_current_projection(workspace_id, query)
506            .await
507    }
508
509    /// Reads the persisted recurrence projection as-is.
510    ///
511    /// Callers establish projection currency by reconciling the workspace for the report snapshot.
512    #[doc(hidden)]
513    pub async fn search_task_preview_set_from_current_projection(
514        &self,
515        workspace_id: &WorkspaceId,
516        query: TaskSearchQuery,
517    ) -> Result<TaskSearchPreviewResultSet> {
518        validate_search_limit(query.limit)?;
519        let mut conn = self.acquire_reader().await?;
520        search_task_preview_set_in_workspace(&mut conn, workspace_id, query).await
521    }
522
523    pub async fn task_detail(&self, task: &Task) -> Result<TaskDetail> {
524        self.reconcile_recurrence_reports(&task.workspace_id)
525            .await?;
526        let mut conn = self.acquire_reader().await?;
527        task_detail(&mut conn, task).await
528    }
529
530    pub async fn task_detail_with_display_refs(
531        &self,
532        task: &Task,
533        display_refs: &DisplayRefContext,
534    ) -> Result<TaskDetail> {
535        self.reconcile_recurrence_reports(&task.workspace_id)
536            .await?;
537        let mut conn = self.acquire_reader().await?;
538        task_detail_with_display_refs(&mut conn, task, display_refs).await
539    }
540
541    pub async fn conflict_display_value(
542        &self,
543        workspace_id: &WorkspaceId,
544        field: &str,
545        value: &str,
546    ) -> Result<String> {
547        let mut conn = self.acquire_reader().await?;
548        conflict_display_value(&mut conn, workspace_id, field, value).await
549    }
550
551    pub async fn task_dependency_summary(
552        &self,
553        workspace_id: &WorkspaceId,
554        task_id: &TaskId,
555    ) -> Result<TaskDependencySummary> {
556        let mut conn = self.acquire_reader().await?;
557        task_dependency_summary(&mut conn, workspace_id, task_id).await
558    }
559
560    pub async fn task_related_links(
561        &self,
562        workspace_id: &WorkspaceId,
563        task_id: &TaskId,
564    ) -> Result<Vec<TaskRelatedLink>> {
565        let mut conn = self.acquire_reader().await?;
566        task_related_links(&mut conn, workspace_id, task_id, None).await
567    }
568
569    pub async fn workspace_task_counts(
570        &self,
571        workspace_id: &WorkspaceId,
572    ) -> Result<WorkspaceTaskCounts> {
573        let mut conn = self.acquire_reader().await?;
574        workspace_task_counts(&mut conn, workspace_id).await
575    }
576
577    pub async fn unresolved_conflict_count(&self) -> Result<i64> {
578        let mut conn = self.acquire_reader().await?;
579        unresolved_conflict_count(&mut conn).await
580    }
581
582    pub async fn sync_history_stats(&self) -> Result<SyncHistoryStats> {
583        let mut conn = self.acquire_reader().await?;
584        sync_history_stats(&mut conn).await
585    }
586
587    pub async fn database_stats(
588        &self,
589        workspace: &crate::workspaces::Workspace,
590    ) -> Result<DatabaseStats> {
591        let mut conn = self.acquire_reader().await?;
592        database_stats::database_stats(&mut conn, workspace).await
593    }
594}
aven_core/query.rs

aven_core/
query.rs
