Initial Commit

packages/foundation/timing/datetime/src/recurrence/recurrence-helpers.md

@@ -0,0 +1,98 @@
+# recurrence-helpers
+
+## Purpose
+
+`recurrence-helpers` provides the internal constants and low-level date arithmetic utilities shared across the recurrence sub-modules of `@suaveplan/datetime`. It contains the frequency/day-name mappings used by the RRULE parser and formatter, and the `addDays`, `addMonths`, `addYears`, `daysInMonth`, `toRRuleDate`, and `fromRRuleDate` helpers used by the candidate generators.
+
+This module is an internal implementation detail. All public API is exposed through `recurrence.ts`. Direct imports are supported but not part of the documented public surface.
+
+## Features
+
+- `FREQ_MAP` — maps RRULE `FREQ` strings to `Frequency` values
+- `FREQ_RRULE` — maps `Frequency` values back to RRULE strings
+- `DAY_NAME` / `DAY_INDEX` — bidirectional weekday ↔ abbreviation maps
+- `toRRuleDate` — format a `Date` as `YYYYMMDD`
+- `fromRRuleDate` — parse `YYYYMMDD` (or `YYYYMMDDTHHmmssZ`) into a `Date`
+- `daysInMonth` — days in a 1-indexed month (local copy for recurrence module independence)
+- `addDays` / `addMonths` / `addYears` — safe date arithmetic with month-end clamping
+
+## Usage: Basic Example
+
+```ts
+import { toRRuleDate, fromRRuleDate, addDays } from "./recurrence-helpers.js";
+
+const d = new Date(2024, 0, 31);
+console.log(toRRuleDate(d));   // "20240131"
+
+const parsed = fromRRuleDate("20241231");
+console.log(parsed.getMonth()); // 11 (December)
+
+const next = addDays(d, 7);
+console.log(next.getDate()); // 7 (Feb 7 2024)
+```
+
+## Usage: Advanced Example
+
+```ts
+import { addMonths, addYears, daysInMonth } from "./recurrence-helpers.js";
+
+// Month-end clamping: Jan 31 + 1 month = Feb 29 (leap year 2024)
+const jan31 = new Date(2024, 0, 31);
+const feb = addMonths(jan31, 1);
+console.log(feb.getDate()); // 29
+
+// Year addition uses addMonths internally
+const twoYearsLater = addYears(jan31, 2);
+console.log(twoYearsLater.getFullYear()); // 2026
+
+// Days in February 2024 (leap year)
+console.log(daysInMonth(2024, 2)); // 29
+```
+
+## API Reference
+
+### `FREQ_MAP: Record<string, Frequency>`
+
+Maps uppercase RRULE frequency strings (`"DAILY"`, `"WEEKLY"`, `"MONTHLY"`, `"YEARLY"`) to their `Frequency` type values.
+
+### `FREQ_RRULE: Record<Frequency, string>`
+
+Inverse of `FREQ_MAP`. Maps `Frequency` type values back to uppercase RRULE strings.
+
+### `DAY_NAME: Record<Weekday, string>`
+
+Maps weekday indices (0–6) to two-letter RRULE abbreviations (`"SU"` … `"SA"`).
+
+### `DAY_INDEX: Record<string, Weekday>`
+
+Maps RRULE day abbreviations to weekday indices.
+
+### `toRRuleDate(d: Date): string`
+
+Format `d` as `YYYYMMDD` with zero-padded year, month, and day.
+
+### `fromRRuleDate(s: string): Date`
+
+Parse `s` (either `YYYYMMDD` or `YYYYMMDDTHHmmssZ`) into a local-midnight `Date`. The time and timezone suffix are stripped.
+
+### `daysInMonth(year: number, month: number): number`
+
+Returns the number of days in the given 1-indexed month. Mirrors the implementation in `calendar-core` to keep this module self-contained.
+
+### `addDays(d: Date, n: number): Date`
+
+Add `n` days to `d` using millisecond arithmetic.
+
+### `addMonths(d: Date, n: number): Date`
+
+Add `n` months with day clamping to the last valid day of the resulting month.
+
+### `addYears(d: Date, n: number): Date`
+
+Add `n` years by delegating to `addMonths(d, n * 12)`.
+
+## Implementation Notes
+
+`addMonths` is the source of truth for month-end clamping in the recurrence engine. It handles month overflow (month > 12 rolls the year forward) and clamps the day to `daysInMonth(year, month)` using `Math.min`, ensuring that e.g. Jan 31 + 1 month → Feb 28/29 rather than Mar 2/3.
+
+`daysInMonth` is intentionally duplicated from `calendar-core` rather than imported, to keep `recurrence-helpers` self-contained and free of cross-category imports.