Calendar Alignment Utility

Transforms recurring and partial date inputs into full target-calendar dates while preserving calendar semantics. All conversions use the provided target calendar unless a swap entry supplies its own override. Output collections preserve the ordering of the corresponding inputs, and date strings include a calendar annotation whenever the calendar is not the ISO default.

Capabilities

Build dates from month/day recurrence

• When given month/day 2/29 in source calendar "iso8601" and anchor year 2024 with target calendar "gregory", the resulting month-day list includes the date text 2024-02-29[u-ca=gregory]. @test
• When given month/day 2/29 with anchor year 2023, the request is rejected with a clear error because the anchor year lacks that day. @test

Complete dates from year/month slots

• Year-month 2025-03 with day 10 in calendar "gregory" appears in the year-month list as 2025-03-10[u-ca=gregory]. @test

Swap calendar on full dates

• A base date of 2025-03-01 in calendar "iso8601" converted to calendar "japanese" preserves the same absolute day and returns 2025-03-01[u-ca=japanese]. @test

Implementation

@generates

API

type MonthDayInput = {
  month: number;
  day: number;
  calendar: string;
  label?: string;
};

type YearMonthInput = {
  year: number;
  month: number;
  day: number;
  calendar: string;
  label?: string;
};

type FullDateInput = {
  date: string; // YYYY-MM-DD
  calendar: string;
  label?: string;
};

type CalendarPlan = {
  monthDays: Array<{ label?: string; date: string; calendar: string }>;
  yearMonths: Array<{ label?: string; date: string; calendar: string }>;
  convertedDates: Array<{ label?: string; date: string; calendar: string }>;
};

export function buildCalendarPlan(options: {
  targetCalendar: string;
  anchorYear: number;
  monthDays: MonthDayInput[];
  yearMonths: YearMonthInput[];
  swapDates: Array<
    FullDateInput & { targetCalendar?: string } // defaults to options.targetCalendar when omitted
  >;
}): CalendarPlan;

Dependencies { .dependencies }

temporal-polyfill { .dependency }

Calendar-aware date/time transformations.