Period Calculator Service
Component Detail
Description
Determines the date ranges for the current and equivalent prior-year periods based on a given period type (half-year or quarterly) and reference date. Provides a single source of truth for period boundaries used across summary generation.
period-calculator-service
Summaries
The Period Calculator Service ensures that every performance report across the platform is based on consistent, correctly defined time boundaries — eliminating the risk of conflicting or inaccurate period definitions that could undermine trust in the data. By serving as a single authoritative source for period calculations, it guarantees that when a coordinator views a team summary and a mentor views their individual report, both are looking at exactly the same time window. This consistency is essential for fair performance assessments, credible year-over-year comparisons, and defensible reporting to programme stakeholders and funders. The service is designed for reuse across backend and shared contexts, reducing duplication and maintenance cost.
Period Calculator Service is a low-complexity, dependency-free component that can be developed and fully unit-tested early in the project timeline, unblocking higher-complexity components that depend on correct period boundaries. Because it executes in both backend and shared contexts, it must be implemented as portable, environment-agnostic code with no runtime dependencies on Node.js-specific or mobile-specific APIs. The primary delivery risk is an incorrect edge case in half-year or quarter boundary logic (e.g., fiscal year alignment, leap years, timezone handling). Invest in comprehensive parameterised unit tests covering all period types and boundary dates before this service is consumed by Summary Generation Service or any UI component.
PeriodCalculatorService is a stateless, dependency-free utility executing in both backend and shared contexts. Its four interfaces — getCurrentPeriod, getPriorYearPeriod, getPeriodLabel, and isWithinPeriod — all accept a periodType enum (half-year | quarterly) and a reference date, returning typed DateRange or boolean results. Because it is shared across mobile and backend, it must be implemented in pure TypeScript with no platform-specific imports. All date arithmetic should use a well-tested date library (e.g., date-fns) rather than manual millisecond calculations to avoid timezone and DST edge cases.
This service is the single source of truth for period boundaries — any future period types must be added here first. Ensure getPriorYearPeriod correctly handles the H1/H2 boundary rollover across year boundaries.
Responsibilities
- Calculate start and end dates for current half-year period
- Calculate start and end dates for current quarterly period
- Calculate equivalent prior-year date range for comparison
- Validate that a reference date falls within a period
Interfaces
getCurrentPeriod(periodType, referenceDate)
getPriorYearPeriod(periodType, referenceDate)
getPeriodLabel(periodType, year, quarter)
isWithinPeriod(date, periodType)
Related Data Entities (1)
Data entities managed by this component