Time Window Service
Component Detail
Description
Utility service that converts a TimeWindow enum value into concrete start and end DateTime boundaries for use in database queries. Handles month, quarter, and year calculations relative to the current date, including edge cases such as year boundaries and varying month lengths.
time-window-service
Summaries
The Time Window Service ensures that all activity reports and dashboards display data for the correct time periods — monthly, quarterly, or yearly — providing coordinators and stakeholders with accurate, timely insights for decision-making. Consistent and correct date boundary calculations reduce the risk of reporting errors that could mislead leadership on program performance or membership trends. By centralizing this logic, the organization avoids duplicated, inconsistent date handling scattered across different features, which in turn reduces the cost of future reporting enhancements and lowers the likelihood of subtle data discrepancies surfacing in audits or reviews.
The Time Window Service is a low-complexity utility with no external dependencies, making it a low-risk deliverable that can be completed and tested early in the project timeline. Its primary value is as a shared calculation layer for any feature that filters data by time period. Development effort is minimal, but correctness is important — edge cases such as year-end boundaries (e.g., Q4 spanning October–December) and variable month lengths (February, 30/31-day months) must be explicitly tested. Unit tests should cover all three window types plus boundary dates.
Because this service is stateless and side-effect free, it carries no deployment risk and can be shipped independently without coordination overhead.
The Time Window Service is a stateless mobile utility that converts a `TimeWindow` enum (month, quarter, year) into a concrete `DateTimeRange` used directly in Supabase query filters. The three core methods — `getMonthRange`, `getQuarterRange`, `getYearRange` — each accept a `DateTime now` parameter, enabling straightforward unit testing by injecting arbitrary reference dates. The top-level `getDateRange(TimeWindow window)` method dispatches to the appropriate range calculator. `formatWindowLabel` provides a display string for UI labels.
Since the service is pure computation with no I/O or side effects, it is fully deterministic and should be 100% unit-testable. Special care is required for quarter boundary logic (ensure Q1 starts January 1, Q4 ends December 31 inclusive) and for month-end calculations using `DateTime`'s last-day-of-month behavior in Dart.
Responsibilities
- Calculate start and end dates for month, quarter, and year windows
- Return DateTimeRange for use in Supabase query filters
- Handle year boundary and month-length edge cases
Interfaces
getDateRange(TimeWindow window) DateTimeRange
getMonthRange(DateTime now) DateTimeRange
getQuarterRange(DateTime now) DateTimeRange
getYearRange(DateTime now) DateTimeRange
formatWindowLabel(TimeWindow window) String