@timestamp-js/core 0.1.0-rc.0 → 0.1.0-rc.1

package/dist/index.js

@@ -1,3 +1,5 @@
+import { formatCalendarDate, gregorianCalendar } from './calendar.js';
+export { formatCalendarDate, gregorianCalendar } from './calendar.js';
 /**
  * Matches supported date and date-time input.
  *
@@ -132,7 +134,7 @@ export const SECONDS_IN_DAY = TIME_CONSTANTS.SECONDS_IN.DAY;
  * instead of mutating this shared default.
  */
 export const Timestamp = freezeTimestamp({
-    date: "",
+    date: '',
     hasDay: false,
     year: 0,
     month: 0,
@@ -161,17 +163,46 @@ function freezeTimestamp(timestamp) {
 function cloneTimestamp(timestamp) {
     return { ...timestamp };
 }
+/**
+ * Extracts calendar date fields from a timestamp-shaped value.
+ *
+ * @param timestamp Timestamp or timestamp-like object to read.
+ * @returns Plain calendar date fields.
+ * @category calendar
+ */
+export function toCalendarDateParts(timestamp) {
+    return {
+        year: timestamp.year,
+        month: timestamp.month,
+        day: timestamp.day,
+    };
+}
+function getCalendarTimestampOptions(timestamp) {
+    return {
+        hasTime: timestamp.hasTime,
+        hour: timestamp.hour,
+        minute: timestamp.minute,
+        second: timestamp.second,
+        millisecond: timestamp.millisecond,
+        timezone: timestamp.timezone,
+    };
+}
+function getCalendarWorkWeek(date, calendar) {
+    const firstWeekday = calendar.getWeekday({ year: date.year, month: 1, day: 1 });
+    return Math.floor((calendar.getDayOfYear(date) + firstWeekday - 1) / 7) + 1;
+}
 function parseMillisecond(value) {
-    return value === undefined ? undefined : parseInt(value.padEnd(3, "0"), 10);
+    return value === undefined ? undefined : parseInt(value.padEnd(3, '0'), 10);
 }
 /**
  * Validates whether an input string matches the supported timestamp grammar.
  *
  * @param {string} input A string in the form `YYYY-MM-DD`, `YYYY-MM-DD HH:mm`, or a full ISO-like date time.
  * @returns {boolean} True if parseable
+ * @category validation
  */
 export function validateTimestamp(input) {
-    if (typeof input !== "string")
+    if (typeof input !== 'string')
         return false;
     return PARSE_DATETIME.test(input);
 }
@@ -184,18 +215,19 @@ export function validateTimestamp(input) {
  *
  * @param {string} input In the form `YYYY-MM-DD`, `YYYY-MM-DD HH:mm:ss`, or an ISO-like date time with optional milliseconds and timezone suffix.
  * @returns {Timestamp} Minimal Timestamp object, or `null` when the input cannot be parsed.
+ * @category parsing
  */
 export function parsed(input) {
-    if (typeof input !== "string")
+    if (typeof input !== 'string')
         return null;
     const parts = PARSE_DATETIME.exec(input);
     if (!parts || !parts[1] || !parts[2])
         return null;
     const year = parseInt(parts[1], 10);
     const month = parseInt(parts[2], 10);
-    const day = parseInt(parts[3] || "1", 10);
-    const hour = parseInt(parts[4] || "0", 10);
-    const minute = parseInt(parts[5] || "0", 10);
+    const day = parseInt(parts[3] || '1', 10);
+    const hour = parseInt(parts[4] || '0', 10);
+    const minute = parseInt(parts[5] || '0', 10);
     const second = parts[6] === undefined ? undefined : parseInt(parts[6], 10);
     const millisecond = parseMillisecond(parts[7]);
     const timestamp = {
@@ -232,17 +264,17 @@ function parseDateByMode(date, utc) {
         return null;
     if (Number.isNaN(date.getTime()))
         return null;
-    const UTC = utc ? "UTC" : "";
+    const UTC = utc ? 'UTC' : '';
     const second = date[`get${UTC}Seconds`]();
     const millisecond = date[`get${UTC}Milliseconds`]();
     const timestamp = {
         date: padNumber(date[`get${UTC}FullYear`](), 4) +
-            "-" +
+            '-' +
             padNumber(date[`get${UTC}Month`]() + 1, 2) +
-            "-" +
+            '-' +
             padNumber(date[`get${UTC}Date`](), 2),
         time: padNumber(date[`get${UTC}Hours`]() || 0, 2) +
-            ":" +
+            ':' +
             padNumber(date[`get${UTC}Minutes`]() || 0, 2),
         year: date[`get${UTC}FullYear`](),
         month: date[`get${UTC}Month`]() + 1,
@@ -275,6 +307,7 @@ function parseDateByMode(date, utc) {
  *
  * @param {Date} date JavaScript Date to convert.
  * @returns {Timestamp} Formatted Timestamp object, or `null` for invalid input.
+ * @category parsing
  */
 export function parseDate(date) {
     return parseDateByMode(date, false);
@@ -287,6 +320,7 @@ export function parseDate(date) {
  *
  * @param {Date} date JavaScript Date to convert.
  * @returns {Timestamp} Formatted Timestamp object, or `null` for invalid input.
+ * @category parsing
  */
 export function parseDateUTC(date) {
     return parseDateByMode(date, true);
@@ -298,11 +332,12 @@ export function parseDateUTC(date) {
  * @param {number} x The number to pad
  * @param {number} length The length of the required number as a string
  * @returns {string} The padded number (as a string). (ie: 5 = '05')
+ * @category formatting
  */
 export function padNumber(x, length) {
     let padded = String(x);
     while (padded.length < length) {
-        padded = "0" + padded;
+        padded = '0' + padded;
     }
     return padded;
 }
@@ -310,34 +345,35 @@ export function padNumber(x, length) {
  * Returns if the passed year is a leap year
  * @param {number} year The year to check (ie: 1999, 2020)
  * @returns {boolean} True if the year is a leap year
+ * @category calendar
  */
 export function isLeapYear(year) {
-    // A year is a Gregorian leap year if it is divisible by 4,
-    // but not by 100, unless it is also divisible by 400.
-    return (year % 4 === 0 && year % 100 !== 0) || year % 400 === 0;
+    return gregorianCalendar.isLeapYear(year);
 }
 /**
  * Returns the days of the specified month in a year
  * @param {number} year The year (ie: 1999, 2020)
  * @param {number} month The Gregorian month number, where January is `1`
  * @returns {number} The number of days in the month (corrected for leap years)
+ * @category calendar
  */
 export function daysInMonth(year, month) {
-    return (isLeapYear(year) ? DAYS_IN_MONTH_LEAP[month] : DAYS_IN_MONTH[month]);
+    return gregorianCalendar.daysInMonth(year, month);
 }
 /**
  * Returns a new Timestamp for the next calendar day.
  *
  * @param {Timestamp} timestamp Base Timestamp object.
  * @returns {Timestamp} New Timestamp representing the next day.
+ * @category arithmetic
  */
 export function nextDay(timestamp) {
-    const date = new Date(timestamp.year, timestamp.month - 1, timestamp.day + 1);
+    const date = gregorianCalendar.nextDay(toCalendarDateParts(timestamp));
     return updateFormatted(normalizeTimestamp({
         ...timestamp,
-        year: date.getFullYear(),
-        month: date.getMonth() + 1,
-        day: date.getDate(),
+        year: date.year,
+        month: date.month,
+        day: date.day,
     }));
 }
 /**
@@ -345,14 +381,15 @@ export function nextDay(timestamp) {
  *
  * @param {Timestamp} timestamp Base Timestamp object.
  * @returns {Timestamp} New Timestamp representing the previous day.
+ * @category arithmetic
  */
 export function prevDay(timestamp) {
-    const date = new Date(timestamp.year, timestamp.month - 1, timestamp.day - 1);
+    const date = gregorianCalendar.prevDay(toCalendarDateParts(timestamp));
     return updateFormatted(normalizeTimestamp({
         ...timestamp,
-        year: date.getFullYear(),
-        month: date.getMonth() + 1,
-        day: date.getDate(),
+        year: date.year,
+        month: date.month,
+        day: date.day,
     }));
 }
 /**
@@ -363,10 +400,11 @@ export function prevDay(timestamp) {
  * wants a stable UTC calendar date instead.
  *
  * @returns {string} Date string in the form `YYYY-MM-DD`
+ * @category state
  */
 export function today() {
     const d = new Date(), month = d.getMonth() + 1, day = d.getDate(), year = d.getFullYear();
-    return [year, padNumber(month, 2), padNumber(day, 2)].join("-");
+    return [year, padNumber(month, 2), padNumber(day, 2)].join('-');
 }
 /**
  * Returns today's date using UTC calendar fields.
@@ -377,13 +415,14 @@ export function today() {
  *
  * @param {Date} date Date source to read. Defaults to the current Date.
  * @returns {string} UTC date string in the form `YYYY-MM-DD`
+ * @category state
  */
 export function todayUTC(date = new Date()) {
     return [
         padNumber(date.getUTCFullYear(), 4),
         padNumber(date.getUTCMonth() + 1, 2),
         padNumber(date.getUTCDate(), 2),
-    ].join("-");
+    ].join('-');
 }
 /**
  * Returns the current date-time as an immutable Timestamp using UTC fields.
@@ -394,6 +433,7 @@ export function todayUTC(date = new Date()) {
  *
  * @param {Date} date Date source to read. Defaults to the current Date.
  * @returns {Timestamp} Immutable Timestamp built from UTC fields.
+ * @category state
  */
 export function nowUTC(date = new Date()) {
     return parseDateUTC(date);
@@ -402,6 +442,7 @@ export function nowUTC(date = new Date()) {
  * Takes a date string ('YYYY-MM-DD') and validates if it is today's date
  * @param {string} date Date string in the form 'YYYY-MM-DD'
  * @returns {boolean} True if the date is today's date
+ * @category comparison
  */
 export function isToday(date) {
     return date === today();
@@ -415,6 +456,7 @@ export function isToday(date) {
  * @param {string} date Date string in the form `YYYY-MM-DD`.
  * @param {Date} now Date source to read. Defaults to the current Date.
  * @returns {boolean} True when the date matches the UTC date.
+ * @category comparison
  */
 export function isTodayUTC(date, now = new Date()) {
     return date === todayUTC(now);
@@ -426,6 +468,7 @@ export function isTodayUTC(date, now = new Date()) {
  * @param {number[]} weekdays The array is [0,1,2,3,4,5,6] where 0=Sunday and 6=Saturday
  * @param {Timestamp=} today Current timestamp used to update relative information
  * @returns {Timestamp} A new Timestamp representing the start of the week
+ * @category ranges
  */
 export function getStartOfWeek(timestamp, weekdays, today) {
     let start = cloneTimestamp(timestamp);
@@ -451,6 +494,7 @@ export function getStartOfWeek(timestamp, weekdays, today) {
  * @param {number[]} weekdays The array is [0,1,2,3,4,5,6] where 0=Sunday and 6=Saturday
  * @param {Timestamp=} today Current timestamp used to update relative information
  * @returns {Timestamp} A new Timestamp representing the end of the week
+ * @category ranges
  */
 export function getEndOfWeek(timestamp, weekdays, today) {
     let end = cloneTimestamp(timestamp);
@@ -475,6 +519,7 @@ export function getEndOfWeek(timestamp, weekdays, today) {
  * Finds the start of the month based on the passed in Timestamp
  * @param {Timestamp} timestamp The Timestamp to use to find the start of the month
  * @returns {Timestamp} A Timestamp of the start of the month
+ * @category ranges
  */
 export function getStartOfMonth(timestamp) {
     let start = cloneTimestamp(timestamp);
@@ -486,6 +531,7 @@ export function getStartOfMonth(timestamp) {
  * Finds the end of the month based on the passed in Timestamp
  * @param {Timestamp} timestamp The Timestamp to use to find the end of the month
  * @returns {Timestamp} A Timestamp of the end of the month
+ * @category ranges
  */
 export function getEndOfMonth(timestamp) {
     let end = cloneTimestamp(timestamp);
@@ -501,29 +547,30 @@ export function getEndOfMonth(timestamp) {
  *
  * @param input - Minutes since midnight, a time string, or an object with hour and minute fields.
  * @returns Minutes since midnight, or `false` when the input cannot be parsed.
+ * @category parsing
  */
 export function parseTime(input) {
     const type = Object.prototype.toString.call(input);
     switch (type) {
-        case "[object Number]":
+        case '[object Number]':
             // when a number is given, it's minutes since 12:00am
             return input;
-        case "[object String]": {
+        case '[object String]': {
             // when a string is given, it's a hh:mm:ss format where seconds are optional, but not used for minute math
             const parts = PARSE_TIME.exec(input);
             if (!parts) {
                 return false;
             }
-            return parseInt(parts[1], 10) * 60 + parseInt(parts[2] || "0", 10);
+            return parseInt(parts[1], 10) * 60 + parseInt(parts[2] || '0', 10);
         }
-        case "[object Object]":
+        case '[object Object]':
             // when an object is given, it must have hour and minute
-            if (typeof input !== "object" ||
-                typeof input.hour !== "number" ||
-                typeof input.minute !== "number") {
+            if (typeof input !== 'object' ||
+                typeof input.hour !== 'number' ||
+                typeof input.minute !== 'number') {
                 return false;
             }
-            if (typeof input === "object" && "hour" in input && "minute" in input) {
+            if (typeof input === 'object' && 'hour' in input && 'minute' in input) {
                 return input.hour * 60 + input.minute;
             }
             return false;
@@ -536,6 +583,7 @@ export function parseTime(input) {
  * @param {Timestamp} ts1 First Timestamp object.
  * @param {Timestamp} ts2 Second Timestamp object.
  * @returns {boolean} True when both timestamps match exactly.
+ * @category comparison
  */
 export function compareTimestamps(ts1, ts2) {
     if (!ts1 || !ts2)
@@ -555,6 +603,7 @@ export function compareTimestamps(ts1, ts2) {
  * @param {Timestamp} ts1 First Timestamp object.
  * @param {Timestamp} ts2 Second Timestamp object.
  * @returns {boolean} True when both dates are the same.
+ * @category comparison
  */
 export function compareDate(ts1, ts2) {
     return getDate(ts1) === getDate(ts2);
@@ -565,6 +614,7 @@ export function compareDate(ts1, ts2) {
  * @param {Timestamp} ts1 First Timestamp object.
  * @param {Timestamp} ts2 Second Timestamp object.
  * @returns {boolean} True when both times are the same.
+ * @category comparison
  */
 export function compareTime(ts1, ts2) {
     return getTime(ts1) === getTime(ts2);
@@ -575,6 +625,7 @@ export function compareTime(ts1, ts2) {
  * @param {Timestamp} ts1 First Timestamp object.
  * @param {Timestamp} ts2 Second Timestamp object.
  * @returns {boolean} True when both date-time values are the same.
+ * @category comparison
  */
 export function compareDateTime(ts1, ts2) {
     return getDateTime(ts1) === getDateTime(ts2);
@@ -588,6 +639,7 @@ export function compareDateTime(ts1, ts2) {
  * @param {string} input Date or date-time string, such as `YYYY-MM-DD`, `YYYY-MM-DD HH:mm:ss`, or an ISO-like value with optional milliseconds and timezone suffix.
  * @param {Timestamp} now Optional Timestamp used to calculate relative flags.
  * @returns {Timestamp} Formatted Timestamp object, or `null` when the input cannot be parsed.
+ * @category parsing
  */
 export function parseTimestamp(input, now = null) {
     let timestamp = parsed(input);
@@ -604,17 +656,418 @@ export function parseTimestamp(input, now = null) {
  *
  * @param {Timestamp} timestamp Timestamp object to read.
  * @returns {number} Numeric date identifier.
+ * @category conversion
  */
 export function getDayIdentifier(timestamp) {
     return ((timestamp.year ?? 0) * 100000000 +
         (timestamp.month ?? 0) * 1000000 +
         (timestamp.day ?? 0) * 10000);
 }
+/**
+ * Converts a Timestamp date into a stable serial day for a calendar system.
+ *
+ * The default Gregorian value is the number of UTC days since 1970-01-01.
+ * Alternate calendar adapters should map their year/month/day fields to the
+ * same serial day space so ranges and comparisons can be calendar-agnostic.
+ *
+ * @param {Timestamp} timestamp Timestamp object to read.
+ * @param {CalendarSystem=} calendar Calendar implementation to use.
+ * @returns {number} Stable serial day.
+ * @category conversion
+ */
+export function getEpochDay(timestamp, calendar = gregorianCalendar) {
+    return calendar.toEpochDay(toCalendarDateParts(timestamp));
+}
+/**
+ * Converts a Timestamp date into a stable serial-day identifier for a calendar system.
+ *
+ * This is an alias-friendly helper for calendar views that need sorted keys,
+ * range comparisons, or virtualized day rows across different calendar adapters.
+ *
+ * @param timestamp Timestamp object to read.
+ * @param calendar Calendar implementation to use.
+ * @returns Stable serial day.
+ * @category calendar
+ */
+export function getCalendarDayIdentifier(timestamp, calendar = gregorianCalendar) {
+    return getEpochDay(timestamp, calendar);
+}
+/**
+ * Returns true when calendar date fields are valid for a calendar system.
+ *
+ * @param date Calendar date fields to validate.
+ * @param calendar Calendar implementation to use.
+ * @returns True when year, month, and day can exist in the calendar.
+ * @category calendar
+ */
+export function isValidCalendarDate(date, calendar = gregorianCalendar) {
+    if (date.year < 1)
+        return false;
+    if (date.month < 1 || date.month > calendar.monthsInYear(date.year))
+        return false;
+    return date.day >= 1 && date.day <= calendar.daysInMonth(date.year, date.month);
+}
+/**
+ * Creates an immutable Timestamp-shaped value from calendar adapter fields.
+ *
+ * The returned timestamp uses adapter year/month/day fields, is tagged with
+ * `calendarId`, and derives weekday/day-of-year values from the adapter.
+ *
+ * @param date Calendar date fields.
+ * @param calendar Calendar implementation to use.
+ * @param options Optional time and relative comparison settings.
+ * @returns Timestamp-shaped calendar value.
+ * @category calendar
+ */
+export function createCalendarTimestamp(date, calendar = gregorianCalendar, options = {}) {
+    const timestamp = {
+        calendarId: calendar.id,
+        date: formatCalendarDate(date),
+        hasDay: true,
+        year: date.year,
+        month: date.month,
+        day: date.day,
+        hasTime: options.hasTime ?? true,
+        hour: options.hour ?? 0,
+        minute: options.minute ?? 0,
+        past: false,
+        current: false,
+        future: false,
+        disabled: false,
+        weekday: calendar.getWeekday(date),
+        doy: calendar.getDayOfYear(date),
+        workweek: getCalendarWorkWeek(date, calendar),
+    };
+    if (options.second !== undefined) {
+        timestamp.second = options.second;
+    }
+    if (options.millisecond !== undefined) {
+        timestamp.millisecond = options.millisecond;
+    }
+    if (options.timezone !== undefined) {
+        timestamp.timezone = options.timezone;
+    }
+    timestamp.time = getTime(timestamp);
+    const formatted = freezeTimestamp(timestamp);
+    return options.now
+        ? updateCalendarRelative(formatted, options.now, calendar, formatted.hasTime)
+        : formatted;
+}
+/**
+ * Parses a date or date-time string as calendar adapter fields.
+ *
+ * Unlike parseTimestamp(), this helper validates the date against the supplied
+ * calendar and derives weekday/day-of-year values through the adapter.
+ *
+ * @param input Date or date-time string.
+ * @param calendar Calendar implementation to use.
+ * @param now Optional comparison timestamp from the same calendar system.
+ * @returns Calendar timestamp, or `null` when the input cannot be parsed or validated.
+ * @category calendar
+ */
+export function parseCalendarTimestamp(input, calendar = gregorianCalendar, now = null) {
+    const timestamp = parsed(input);
+    if (timestamp === null)
+        return null;
+    const date = toCalendarDateParts(timestamp);
+    if (isValidCalendarDate(date, calendar) === false)
+        return null;
+    return createCalendarTimestamp(date, calendar, {
+        ...getCalendarTimestampOptions(timestamp),
+        now,
+    });
+}
+/**
+ * Creates a calendar timestamp from a stable serial day.
+ *
+ * @param epochDay Stable serial day.
+ * @param calendar Calendar implementation to use.
+ * @param options Optional time and relative comparison settings.
+ * @returns Timestamp-shaped calendar value.
+ * @category calendar
+ */
+export function createCalendarTimestampFromEpochDay(epochDay, calendar = gregorianCalendar, options = {}) {
+    return createCalendarTimestamp(calendar.fromEpochDay(epochDay), calendar, options);
+}
+/**
+ * Updates formatted calendar metadata on a timestamp-shaped value.
+ *
+ * @param timestamp Timestamp object to transform.
+ * @param calendar Calendar implementation to use.
+ * @returns Timestamp with adapter date formatting and metadata.
+ * @category calendar
+ */
+export function updateCalendarFormatted(timestamp, calendar = gregorianCalendar) {
+    return createCalendarTimestamp(toCalendarDateParts(timestamp), calendar, getCalendarTimestampOptions(timestamp));
+}
+/**
+ * Returns a timestamp with relative flags compared through a calendar adapter.
+ *
+ * @param timestamp Timestamp object to update.
+ * @param now Timestamp representing the comparison point in the same calendar.
+ * @param calendar Calendar implementation to use.
+ * @param time Include time-of-day in the comparison when true.
+ * @returns New Timestamp object with relative flags.
+ * @category calendar
+ */
+export function updateCalendarRelative(timestamp, now, calendar = gregorianCalendar, time = false) {
+    const ts = cloneTimestamp(timestamp);
+    let a = getCalendarDayIdentifier(now, calendar);
+    let b = getCalendarDayIdentifier(ts, calendar);
+    let current = a === b;
+    if (ts.hasTime && time && current) {
+        a = getTimeComparisonValue(now);
+        b = getTimeComparisonValue(ts);
+        current = a === b;
+    }
+    ts.past = b < a;
+    ts.current = current;
+    ts.future = b > a;
+    ts.currentWeekday = ts.weekday === now.weekday;
+    return freezeTimestamp(ts);
+}
+/**
+ * Returns a calendar timestamp for the next day.
+ *
+ * @param timestamp Base timestamp.
+ * @param calendar Calendar implementation to use.
+ * @returns New timestamp for the next adapter day.
+ * @category calendar
+ */
+export function nextCalendarDay(timestamp, calendar = gregorianCalendar) {
+    return createCalendarTimestamp(calendar.nextDay(toCalendarDateParts(timestamp)), calendar, getCalendarTimestampOptions(timestamp));
+}
+/**
+ * Returns a calendar timestamp for the previous day.
+ *
+ * @param timestamp Base timestamp.
+ * @param calendar Calendar implementation to use.
+ * @returns New timestamp for the previous adapter day.
+ * @category calendar
+ */
+export function prevCalendarDay(timestamp, calendar = gregorianCalendar) {
+    return createCalendarTimestamp(calendar.prevDay(toCalendarDateParts(timestamp)), calendar, getCalendarTimestampOptions(timestamp));
+}
+/**
+ * Adds a number of days through a calendar adapter.
+ *
+ * @param timestamp Base timestamp.
+ * @param amount Number of days to move.
+ * @param calendar Calendar implementation to use.
+ * @returns New timestamp after moving.
+ * @category calendar
+ */
+export function addCalendarDays(timestamp, amount, calendar = gregorianCalendar) {
+    return createCalendarTimestamp(calendar.addDays(toCalendarDateParts(timestamp), amount), calendar, getCalendarTimestampOptions(timestamp));
+}
+/**
+ * Adds a number of months through a calendar adapter and clamps invalid days.
+ *
+ * @param timestamp Base timestamp.
+ * @param amount Number of calendar months to move.
+ * @param calendar Calendar implementation to use.
+ * @returns New timestamp after moving.
+ * @category calendar
+ */
+export function addCalendarMonths(timestamp, amount, calendar = gregorianCalendar) {
+    let { year, month, day } = toCalendarDateParts(timestamp);
+    let remaining = Math.trunc(amount);
+    while (remaining > 0) {
+        month += 1;
+        if (month > calendar.monthsInYear(year)) {
+            year += 1;
+            month = 1;
+        }
+        remaining -= 1;
+    }
+    while (remaining < 0) {
+        month -= 1;
+        if (month < 1) {
+            year -= 1;
+            month = calendar.monthsInYear(year);
+        }
+        remaining += 1;
+    }
+    day = Math.min(day, calendar.daysInMonth(year, month));
+    return createCalendarTimestamp({ year, month, day }, calendar, getCalendarTimestampOptions(timestamp));
+}
+/**
+ * Adds a number of years through a calendar adapter and clamps invalid days.
+ *
+ * @param timestamp Base timestamp.
+ * @param amount Number of calendar years to move.
+ * @param calendar Calendar implementation to use.
+ * @returns New timestamp after moving.
+ * @category calendar
+ */
+export function addCalendarYears(timestamp, amount, calendar = gregorianCalendar) {
+    let { year, month, day } = toCalendarDateParts(timestamp);
+    year += Math.trunc(amount);
+    month = Math.min(month, calendar.monthsInYear(year));
+    day = Math.min(day, calendar.daysInMonth(year, month));
+    return createCalendarTimestamp({ year, month, day }, calendar, getCalendarTimestampOptions(timestamp));
+}
+/**
+ * Returns the start of the calendar month for a timestamp.
+ *
+ * @param timestamp Base timestamp.
+ * @param calendar Calendar implementation to use.
+ * @returns First day of the adapter month.
+ * @category calendar
+ */
+export function getCalendarStartOfMonth(timestamp, calendar = gregorianCalendar) {
+    return createCalendarTimestamp({ ...toCalendarDateParts(timestamp), day: 1 }, calendar, getCalendarTimestampOptions(timestamp));
+}
+/**
+ * Returns the end of the calendar month for a timestamp.
+ *
+ * @param timestamp Base timestamp.
+ * @param calendar Calendar implementation to use.
+ * @returns Last day of the adapter month.
+ * @category calendar
+ */
+export function getCalendarEndOfMonth(timestamp, calendar = gregorianCalendar) {
+    const date = toCalendarDateParts(timestamp);
+    return createCalendarTimestamp({
+        ...date,
+        day: calendar.daysInMonth(date.year, date.month),
+    }, calendar, getCalendarTimestampOptions(timestamp));
+}
+/**
+ * Returns the start of the calendar year for a timestamp.
+ *
+ * @param timestamp Base timestamp.
+ * @param calendar Calendar implementation to use.
+ * @returns First day of the adapter year.
+ * @category calendar
+ */
+export function getCalendarStartOfYear(timestamp, calendar = gregorianCalendar) {
+    return createCalendarTimestamp({ year: timestamp.year, month: 1, day: 1 }, calendar, getCalendarTimestampOptions(timestamp));
+}
+/**
+ * Returns the end of the calendar year for a timestamp.
+ *
+ * @param timestamp Base timestamp.
+ * @param calendar Calendar implementation to use.
+ * @returns Last day of the adapter year.
+ * @category calendar
+ */
+export function getCalendarEndOfYear(timestamp, calendar = gregorianCalendar) {
+    const month = calendar.monthsInYear(timestamp.year);
+    return createCalendarTimestamp({ year: timestamp.year, month, day: calendar.daysInMonth(timestamp.year, month) }, calendar, getCalendarTimestampOptions(timestamp));
+}
+/**
+ * Finds the nearest matching weekday through a calendar adapter.
+ *
+ * @param timestamp Base timestamp.
+ * @param weekday Weekday number to find.
+ * @param calendar Calendar implementation to use.
+ * @param direction Direction to search.
+ * @param maxDays Maximum days to inspect.
+ * @returns Matching timestamp, or the last inspected timestamp.
+ * @category calendar
+ */
+export function findCalendarWeekday(timestamp, weekday, calendar = gregorianCalendar, direction = 'next', maxDays = 6) {
+    let ts = copyTimestamp(timestamp);
+    const mover = direction === 'next' ? nextCalendarDay : prevCalendarDay;
+    while (ts.weekday !== weekday && --maxDays >= 0) {
+        ts = mover(ts, calendar);
+    }
+    return ts;
+}
+/**
+ * Returns the start of a calendar week for a timestamp and weekday set.
+ *
+ * @param timestamp Base timestamp.
+ * @param weekdays Weekday numbers to include, from `0` Sunday to `6` Saturday.
+ * @param calendar Calendar implementation to use.
+ * @param now Optional comparison timestamp from the same calendar.
+ * @returns Start of the adapter week.
+ * @category calendar
+ */
+export function getCalendarStartOfWeek(timestamp, weekdays, calendar = gregorianCalendar, now = null) {
+    let start = updateCalendarFormatted(timestamp, calendar);
+    if (!weekdays || !Array.isArray(weekdays)) {
+        return start;
+    }
+    if (start.day === 1 || start.weekday === 0) {
+        while (!weekdays.includes(Number(start.weekday))) {
+            start = nextCalendarDay(start, calendar);
+        }
+    }
+    start = findCalendarWeekday(start, weekdays[0], calendar, 'prev');
+    return now ? updateCalendarRelative(start, now, calendar, start.hasTime) : start;
+}
+/**
+ * Returns the end of a calendar week for a timestamp and weekday set.
+ *
+ * @param timestamp Base timestamp.
+ * @param weekdays Weekday numbers to include, from `0` Sunday to `6` Saturday.
+ * @param calendar Calendar implementation to use.
+ * @param now Optional comparison timestamp from the same calendar.
+ * @returns End of the adapter week.
+ * @category calendar
+ */
+export function getCalendarEndOfWeek(timestamp, weekdays, calendar = gregorianCalendar, now = null) {
+    let end = updateCalendarFormatted(timestamp, calendar);
+    if (!weekdays || !Array.isArray(weekdays)) {
+        return end;
+    }
+    const lastDay = calendar.daysInMonth(end.year, end.month);
+    if (lastDay === end.day || end.weekday === weekdays[weekdays.length - 1]) {
+        while (!weekdays.includes(Number(end.weekday))) {
+            end = prevCalendarDay(end, calendar);
+        }
+    }
+    end = findCalendarWeekday(end, weekdays[weekdays.length - 1], calendar, 'next');
+    return now ? updateCalendarRelative(end, now, calendar, end.hasTime) : end;
+}
+/**
+ * Creates an inclusive list of calendar adapter days between start and end.
+ *
+ * @param start First day in the list.
+ * @param end Last day boundary for the list.
+ * @param now Timestamp used to calculate relative flags.
+ * @param calendar Calendar implementation to use.
+ * @param options Optional weekday, disabled, and size filters.
+ * @returns Timestamp days for the adapter calendar.
+ * @category calendar
+ */
+export function createCalendarDayList(start, end, now, calendar = gregorianCalendar, options = {}) {
+    const { weekdays = [0, 1, 2, 3, 4, 5, 6], disabledBefore, disabledAfter, disabledWeekdays = [], disabledDays = [], max = 42, min = 0, } = options;
+    const begin = getCalendarDayIdentifier(start, calendar);
+    const stop = getCalendarDayIdentifier(end, calendar);
+    const days = [];
+    let current = updateCalendarFormatted(start, calendar);
+    let currentIdentifier = 0;
+    let stopped = currentIdentifier === stop;
+    if (stop < begin) {
+        return days;
+    }
+    while ((!stopped || days.length < min) && days.length < max) {
+        currentIdentifier = getCalendarDayIdentifier(current, calendar);
+        stopped = stopped || (currentIdentifier > stop && days.length >= min);
+        if (stopped) {
+            break;
+        }
+        if (!weekdays.includes(Number(current.weekday))) {
+            current = nextCalendarDay(current, calendar);
+            continue;
+        }
+        let day = updateCalendarFormatted(current, calendar);
+        day = updateCalendarRelative(day, now, calendar);
+        day = updateDisabled(day, disabledBefore, disabledAfter, disabledWeekdays, disabledDays);
+        days.push(day);
+        current = nextCalendarDay(current, calendar);
+    }
+    return days;
+}
 /**
  * Converts a Timestamp time into a sortable numeric identifier.
  *
  * @param {Timestamp} timestamp Timestamp object to read.
  * @returns {number} Numeric time identifier.
+ * @category conversion
  */
 export function getTimeIdentifier(timestamp) {
     return (timestamp.hour ?? 0) * 100 + (timestamp.minute ?? 0);
@@ -631,6 +1084,7 @@ function getTimeComparisonValue(timestamp) {
  *
  * @param {Timestamp} timestamp Timestamp object to read.
  * @returns {number} Numeric date-time identifier.
+ * @category conversion
  */
 export function getDayTimeIdentifier(timestamp) {
     return getDayIdentifier(timestamp) + getTimeIdentifier(timestamp);
@@ -641,6 +1095,7 @@ export function getDayTimeIdentifier(timestamp) {
  * @param {Timestamp} ts2 The second Timestamp
  * @param {boolean=} strict Optional flag to not to return negative numbers
  * @returns {number} The difference
+ * @category arithmetic
  */
 export function diffTimestamp(ts1, ts2, strict = false) {
     const utc1 = Date.UTC(ts1.year ?? 0, (ts1.month ?? 1) - 1, ts1.day ?? 1, ts1.hour ?? 0, ts1.minute ?? 0, ts1.second ?? 0, ts1.millisecond ?? 0);
@@ -663,6 +1118,7 @@ export function diffTimestamp(ts1, ts2, strict = false) {
  * @param {Timestamp} now Timestamp representing the comparison point.
  * @param {boolean=} time Include time-of-day in the comparison when true.
  * @returns {Timestamp} New Timestamp object with relative flags.
+ * @category state
  */
 export function updateRelative(timestamp, now, time = false) {
     const ts = cloneTimestamp(timestamp);
@@ -690,6 +1146,7 @@ export function updateRelative(timestamp, now, time = false) {
  * @param {number} minutes The number of minutes to set from midnight
  * @param {Timestamp=} now Optional Timestamp representing current date and time
  * @returns {Timestamp} A new Timestamp
+ * @category arithmetic
  */
 export function updateMinutes(timestamp, minutes, now = null) {
     let ts = cloneTimestamp(timestamp);
@@ -708,6 +1165,7 @@ export function updateMinutes(timestamp, minutes, now = null) {
  * Updates the Timestamp with the weekday
  * @param {Timestamp} timestamp The Timestamp to transform
  * @returns A new Timestamp
+ * @category formatting
  */
 export function updateWeekday(timestamp) {
     const ts = cloneTimestamp(timestamp);
@@ -718,6 +1176,7 @@ export function updateWeekday(timestamp) {
  * Updates the Timestamp with the day of the year (doy)
  * @param {Timestamp} timestamp The Timestamp to transform
  * @returns A new Timestamp
+ * @category formatting
  */
 export function updateDayOfYear(timestamp) {
     const ts = cloneTimestamp(timestamp);
@@ -728,6 +1187,7 @@ export function updateDayOfYear(timestamp) {
  * Updates the Timestamp with the workweek
  * @param {Timestamp} timestamp The Timestamp to transform
  * @returns A new Timestamp
+ * @category formatting
  */
 export function updateWorkWeek(timestamp) {
     const ts = cloneTimestamp(timestamp);
@@ -735,7 +1195,7 @@ export function updateWorkWeek(timestamp) {
     return freezeTimestamp(ts);
 }
 function isDisabledDayConfig(value) {
-    return typeof value === "object" && value !== null && Array.isArray(value) === false;
+    return typeof value === 'object' && value !== null && Array.isArray(value) === false;
 }
 function applyDisabledDayConfig(timestamp, config) {
     timestamp.disabled = true;
@@ -787,6 +1247,7 @@ function isTimestampInDisabledDay(timestamp, day) {
  * @param {number[]} [disabledWeekdays] An array of numbers representing weekdays [0 = Sun, ..., 6 = Sat]
  * @param {DisabledDays} [disabledDays] An array of days in 'YYYY-MM-DD' format. If an array with a pair of dates is in first array, then this is treated as a range. Object entries can include date/from/to plus color metadata.
  * @returns A new Timestamp
+ * @category state
  */
 export function updateDisabled(timestamp, disabledBefore, disabledAfter, disabledWeekdays, disabledDays) {
     let ts = cloneTimestamp(timestamp);
@@ -831,6 +1292,7 @@ export function updateDisabled(timestamp, disabledBefore, disabledAfter, disable
  * Updates the passed Timestamp with formatted data (time string, date string, weekday, day of year and workweek)
  * @param {Timestamp} timestamp The Timestamp to transform
  * @returns A new Timestamp
+ * @category formatting
  */
 export function updateFormatted(timestamp) {
     const ts = cloneTimestamp(timestamp);
@@ -846,21 +1308,18 @@ export function updateFormatted(timestamp) {
  * Returns day of the year (doy) for the passed in Timestamp
  * @param {Timestamp} timestamp The Timestamp to use
  * @returns {number} The day of the year
+ * @category formatting
  */
 export function getDayOfYear(timestamp) {
     if (timestamp.year === 0)
         return;
-    return ((Date.UTC(timestamp.year, timestamp.month - 1, timestamp.day) -
-        Date.UTC(timestamp.year, 0, 0)) /
-        24 /
-        60 /
-        60 /
-        1000);
+    return gregorianCalendar.getDayOfYear(toCalendarDateParts(timestamp));
 }
 /**
  * Returns workweek for the passed in Timestamp
  * @param {Timestamp} timestamp The Timestamp to use
  * @returns {number} The work week
+ * @category formatting
  */
 export function getWorkWeek(timestamp) {
     let ts = timestamp;
@@ -888,25 +1347,12 @@ export function getWorkWeek(timestamp) {
  * Returns weekday for the passed in Timestamp
  * @param {Timestamp} timestamp The Timestamp to use
  * @returns {number} The weekday
+ * @category formatting
  */
 export function getWeekday(timestamp) {
     let weekday = timestamp.weekday;
     if (timestamp.hasDay) {
-        const floor = Math.floor;
-        const day = timestamp.day;
-        const month = ((timestamp.month + 9) % MONTH_MAX) + 1;
-        const century = floor(timestamp.year / 100);
-        const year = (timestamp.year % 100) - (timestamp.month <= 2 ? 1 : 0);
-        weekday =
-            (((day +
-                floor(2.6 * month - 0.2) -
-                2 * century +
-                year +
-                floor(year / 4) +
-                floor(century / 4)) %
-                7) +
-                7) %
-                7;
+        weekday = gregorianCalendar.getWeekday(toCalendarDateParts(timestamp));
     }
     return weekday ?? 0;
 }
@@ -915,6 +1361,7 @@ export function getWeekday(timestamp) {
  *
  * @param {Timestamp} timestamp Timestamp object to copy.
  * @returns {Timestamp} Frozen Timestamp copy.
+ * @category state
  */
 export function copyTimestamp(timestamp) {
     return freezeTimestamp(timestamp);
@@ -943,6 +1390,7 @@ function setTimeParts(timestamp, hour, minute, second, millisecond) {
  *
  * @param {Timestamp} timestamp Timestamp object to transform.
  * @returns {Timestamp} New Timestamp at `00:00`.
+ * @category ranges
  */
 export function getStartOfDay(timestamp) {
     return setTimeParts(timestamp, 0, 0);
@@ -952,6 +1400,7 @@ export function getStartOfDay(timestamp) {
  *
  * @param {Timestamp} timestamp Timestamp object to transform.
  * @returns {Timestamp} New Timestamp at `23:59:59.999`.
+ * @category ranges
  */
 export function getEndOfDay(timestamp) {
     return setTimeParts(timestamp, 23, 59, 59, 999);
@@ -961,6 +1410,7 @@ export function getEndOfDay(timestamp) {
  *
  * @param {Timestamp} timestamp Timestamp object to transform.
  * @returns {Timestamp} New Timestamp for January 1 at `00:00`.
+ * @category ranges
  */
 export function getStartOfYear(timestamp) {
     const ts = cloneTimestamp(timestamp);
@@ -973,6 +1423,7 @@ export function getStartOfYear(timestamp) {
  *
  * @param {Timestamp} timestamp Timestamp object to transform.
  * @returns {Timestamp} New Timestamp for December 31 at `23:59:59.999`.
+ * @category ranges
  */
 export function getEndOfYear(timestamp) {
     const ts = cloneTimestamp(timestamp);
@@ -985,6 +1436,7 @@ export function getEndOfYear(timestamp) {
  *
  * @param {Timestamp} timestamp Timestamp object to format.
  * @returns {string} Date string such as `YYYY-MM-DD`.
+ * @category conversion
  */
 export function getDate(timestamp) {
     let str = `${padNumber(timestamp.year, 4)}-${padNumber(timestamp.month, 2)}`;
@@ -1000,10 +1452,11 @@ export function getDate(timestamp) {
  *
  * @param {Timestamp} timestamp Timestamp object to format.
  * @returns {string} Time string, or an empty string when the timestamp has no time.
+ * @category conversion
  */
 export function getTime(timestamp) {
     if (!timestamp.hasTime) {
-        return "";
+        return '';
     }
     let time = `${padNumber(timestamp.hour, 2)}:${padNumber(timestamp.minute, 2)}`;
     if (timestamp.second !== undefined || timestamp.millisecond !== undefined) {
@@ -1019,9 +1472,10 @@ export function getTime(timestamp) {
  *
  * @param {Timestamp} timestamp Timestamp object to format.
  * @returns {string} Date-time string such as `YYYY-MM-DD HH:mm`.
+ * @category conversion
  */
 export function getDateTime(timestamp) {
-    return getDate(timestamp) + " " + (timestamp.hasTime ? getTime(timestamp) : "00:00");
+    return getDate(timestamp) + ' ' + (timestamp.hasTime ? getTime(timestamp) : '00:00');
 }
 /**
  * Alias for relativeDays.
@@ -1030,6 +1484,7 @@ export function getDateTime(timestamp) {
  * @param {number} [days=1] The number of days to move.
  * @param {number[]} [allowedWeekdays=[ 0, 1, 2, 3, 4, 5, 6 ]] An array of numbers representing the weekdays. ie: [0 = Sun, ..., 6 = Sat].
  * @returns A new Timestamp
+ * @category ranges
  */
 export function moveRelativeDays(timestamp, mover = nextDay, days = 1, allowedWeekdays = [0, 1, 2, 3, 4, 5, 6]) {
     return relativeDays(timestamp, mover, days, allowedWeekdays);
@@ -1041,6 +1496,7 @@ export function moveRelativeDays(timestamp, mover = nextDay, days = 1, allowedWe
  * @param {number} [days=1] The number of days to move.
  * @param {number[]} [allowedWeekdays=[ 0, 1, 2, 3, 4, 5, 6 ]] An array of numbers representing the weekdays. ie: [0 = Sun, ..., 6 = Sat].
  * @returns A new Timestamp
+ * @category ranges
  */
 export function relativeDays(timestamp, mover = nextDay, days = 1, allowedWeekdays = [0, 1, 2, 3, 4, 5, 6]) {
     let ts = copyTimestamp(timestamp);
@@ -1062,6 +1518,7 @@ export function relativeDays(timestamp, mover = nextDay, days = 1, allowedWeekda
  * @param {function} [mover=nextDay] The function to use ({prevDay} or {nextDay}).
  * @param {number} [maxDays=6] The number of days to look forward or back.
  * @returns A new Timestamp
+ * @category ranges
  */
 export function findWeekday(timestamp, weekday, mover = nextDay, maxDays = 6) {
     let ts = copyTimestamp(timestamp);
@@ -1086,6 +1543,7 @@ export function findWeekday(timestamp, weekday, mover = nextDay, maxDays = 6) {
  * @param {number} [max=42] Maximum number of days to return.
  * @param {number} [min=0] Minimum number of days to return.
  * @returns {Timestamp[]} Timestamp days.
+ * @category ranges
  */
 export function createDayList(start, end, now, weekdays = [0, 1, 2, 3, 4, 5, 6], disabledBefore = undefined, disabledAfter = undefined, disabledWeekdays = [], disabledDays = [], max = 42, min = 0) {
     const begin = getDayIdentifier(start);
@@ -1125,6 +1583,7 @@ export function createDayList(start, end, now, weekdays = [0, 1, 2, 3, 4, 5, 6],
  * @param {number} count Number of intervals to create.
  * @param {Timestamp} now Timestamp used to calculate relative flags.
  * @returns {Timestamp[]} Interval Timestamp objects.
+ * @category ranges
  */
 export function createIntervalList(timestamp, first, minutes, count, now) {
     const intervals = [];
@@ -1147,8 +1606,8 @@ export function createIntervalList(timestamp, first, minutes, count, now) {
  * @returns {string} The localized string of the formatted Timestamp
  */
 function createNativeLocaleFormatterByMode(locale, cb, toDate) {
-    const emptyFormatter = () => "";
-    if (typeof Intl === "undefined" || typeof Intl.DateTimeFormat === "undefined") {
+    const emptyFormatter = () => '';
+    if (typeof Intl === 'undefined' || typeof Intl.DateTimeFormat === 'undefined') {
         return emptyFormatter;
     }
     return (timestamp, short) => {
@@ -1158,7 +1617,7 @@ function createNativeLocaleFormatterByMode(locale, cb, toDate) {
         }
         catch (e) {
             console.error(`Intl.DateTimeFormat: ${e.message} -> ${getDateTime(timestamp)}`);
-            return "";
+            return '';
         }
     };
 }
@@ -1175,6 +1634,7 @@ function createNativeLocaleFormatterByMode(locale, cb, toDate) {
  * @param {string} locale The locale to use (ie: en-US)
  * @param {getOptions} cb The function to call for options. This function should return an Intl formatted object. The function is passed (timestamp, short).
  * @returns {formatter} The function has params (timestamp, short). The short is to use the short options.
+ * @category locale
  */
 export function createNativeLocaleFormatter(locale, cb) {
     return createNativeLocaleFormatterByMode(locale, cb, makeDateTime);
@@ -1189,15 +1649,50 @@ export function createNativeLocaleFormatter(locale, cb) {
  * @param {string} locale The locale to use (ie: en-US)
  * @param {getOptions} cb The function to call for options. This function should return an Intl formatted object. The function is passed (timestamp, short).
  * @returns {formatter} The function has params (timestamp, short). The short is to use the short options.
+ * @category locale
  */
 export function createNativeLocaleFormatterUTC(locale, cb) {
     return createNativeLocaleFormatterByMode(locale, cb, makeDateTimeUTC);
 }
+/**
+ * Returns a UTC locale formatter for a calendar adapter.
+ *
+ * The formatter converts adapter date fields through the adapter's serial day
+ * before constructing the native Date. When the adapter has an Intl calendar id,
+ * it is supplied to Intl.DateTimeFormat unless the caller already provided a
+ * `calendar` option. The helper supplies `timeZone: "UTC"` unless the caller
+ * provides a different timezone.
+ *
+ * @param calendar Calendar implementation to use.
+ * @param locale The locale to use.
+ * @param cb Callback that returns Intl formatting options.
+ * @returns Function that formats a calendar timestamp.
+ * @category calendar
+ */
+export function createCalendarLocaleFormatterUTC(calendar, locale, cb) {
+    return createNativeLocaleFormatterByMode(locale, (timestamp, short) => {
+        const options = cb(timestamp, short);
+        const resolvedOptions = options.timeZone === undefined
+            ? {
+                ...options,
+                timeZone: 'UTC',
+            }
+            : options;
+        if (calendar.intlCalendar === undefined || resolvedOptions.calendar !== undefined) {
+            return resolvedOptions;
+        }
+        return {
+            ...resolvedOptions,
+            calendar: calendar.intlCalendar,
+        };
+    }, (timestamp) => makeCalendarDateTimeUTC(timestamp, calendar));
+}
 /**
  * Converts a Timestamp date into a host-local JavaScript Date.
  *
  * @param {Timestamp} timestamp Timestamp object to convert.
  * @returns {Date} Host-local JavaScript Date object.
+ * @category conversion
  */
 export function makeDate(timestamp) {
     return new Date(timestamp.year, timestamp.month - 1, timestamp.day, 0, 0);
@@ -1207,24 +1702,54 @@ export function makeDate(timestamp) {
  *
  * @param {Timestamp} timestamp Timestamp object to convert.
  * @returns {Date} JavaScript Date object built with `Date.UTC()`.
+ * @category conversion
  */
 export function makeDateUTC(timestamp) {
     return new Date(Date.UTC(timestamp.year, timestamp.month - 1, timestamp.day, 0, 0));
 }
+/**
+ * Converts an adapter calendar timestamp date into a UTC JavaScript Date.
+ *
+ * The native Date always represents the equivalent Gregorian civil day so Intl
+ * can format the adapter date correctly when paired with a calendar option.
+ *
+ * @param timestamp Calendar timestamp object to convert.
+ * @param calendar Calendar implementation to use.
+ * @returns JavaScript Date object built with `Date.UTC()`.
+ * @category calendar
+ */
+export function makeCalendarDateUTC(timestamp, calendar = gregorianCalendar) {
+    const date = gregorianCalendar.fromEpochDay(getCalendarDayIdentifier(timestamp, calendar));
+    return new Date(Date.UTC(date.year, date.month - 1, date.day, 0, 0));
+}
 /**
  * Converts a Timestamp date and time into a host-local JavaScript Date.
  *
  * @param {Timestamp} timestamp Timestamp object to convert.
  * @returns {Date} Host-local JavaScript Date object.
+ * @category conversion
  */
 export function makeDateTime(timestamp) {
     return new Date(timestamp.year, timestamp.month - 1, timestamp.day, timestamp.hour, timestamp.minute, timestamp.second ?? 0, timestamp.millisecond ?? 0);
 }
+/**
+ * Converts an adapter calendar timestamp date-time into a UTC JavaScript Date.
+ *
+ * @param timestamp Calendar timestamp object to convert.
+ * @param calendar Calendar implementation to use.
+ * @returns JavaScript Date object built with `Date.UTC()`.
+ * @category calendar
+ */
+export function makeCalendarDateTimeUTC(timestamp, calendar = gregorianCalendar) {
+    const date = gregorianCalendar.fromEpochDay(getCalendarDayIdentifier(timestamp, calendar));
+    return new Date(Date.UTC(date.year, date.month - 1, date.day, timestamp.hour, timestamp.minute, timestamp.second ?? 0, timestamp.millisecond ?? 0));
+}
 /**
  * Converts a Timestamp date and time into a UTC JavaScript Date.
  *
  * @param {Timestamp} timestamp Timestamp object to convert.
  * @returns {Date} JavaScript Date object built with `Date.UTC()`.
+ * @category conversion
  */
 export function makeDateTimeUTC(timestamp) {
     return new Date(Date.UTC(timestamp.year, timestamp.month - 1, timestamp.day, timestamp.hour, timestamp.minute, timestamp.second ?? 0, timestamp.millisecond ?? 0));
@@ -1237,6 +1762,7 @@ export function makeDateTimeUTC(timestamp) {
  *
  * @param {Timestamp} timestamp Timestamp object to convert.
  * @returns {number} Unix milliseconds.
+ * @category conversion
  */
 export function toUnixMilliseconds(timestamp) {
     return makeDateTimeUTC(timestamp).getTime();
@@ -1248,6 +1774,7 @@ export function toUnixMilliseconds(timestamp) {
  *
  * @param {Timestamp} timestamp Timestamp object to convert.
  * @returns {number} Unix seconds.
+ * @category conversion
  */
 export function toUnixSeconds(timestamp) {
     return Math.floor(toUnixMilliseconds(timestamp) / MILLISECONDS_IN_SECOND);
@@ -1257,6 +1784,7 @@ export function toUnixSeconds(timestamp) {
  *
  * @param {number} milliseconds Unix milliseconds.
  * @returns {Timestamp | null} Timestamp built from UTC fields, or `null` for invalid input.
+ * @category conversion
  */
 export function fromUnixMilliseconds(milliseconds) {
     return parseDateUTC(new Date(milliseconds));
@@ -1266,6 +1794,7 @@ export function fromUnixMilliseconds(milliseconds) {
  *
  * @param {number} seconds Unix seconds.
  * @returns {Timestamp | null} Timestamp built from UTC fields, or `null` for invalid input.
+ * @category conversion
  */
 export function fromUnixSeconds(seconds) {
     return fromUnixMilliseconds(seconds * MILLISECONDS_IN_SECOND);
@@ -1277,6 +1806,7 @@ export function fromUnixSeconds(seconds) {
  *
  * @param {Timestamp} timestamp Timestamp object to convert.
  * @returns {Date} Local JavaScript Date object.
+ * @category conversion
  */
 export function getDateObject(timestamp) {
     return makeDateTime(timestamp);
@@ -1287,6 +1817,7 @@ export function getDateObject(timestamp) {
  * @param input - The value to be validated. Can be a string or a number.
  * @returns A boolean indicating whether the input is a finite number.
  *          Returns true if the input is a finite number, false otherwise.
+ * @category validation
  */
 export function validateNumber(input) {
     return isFinite(Number(input));
@@ -1297,6 +1828,7 @@ export function validateNumber(input) {
  * @param {Timestamp[]} timestamps Timestamp objects to compare.
  * @param {boolean=} useTime Include time-of-day in the comparison when true.
  * @returns Latest Timestamp object.
+ * @category comparison
  */
 export function maxTimestamp(timestamps, useTime = false) {
     const func = useTime === true ? getDayTimeIdentifier : getDayIdentifier;
@@ -1310,6 +1842,7 @@ export function maxTimestamp(timestamps, useTime = false) {
  * @param {Timestamp[]} timestamps Timestamp objects to compare.
  * @param {boolean=} useTime Include time-of-day in the comparison when true.
  * @returns Earliest Timestamp object.
+ * @category comparison
  */
 export function minTimestamp(timestamps, useTime = false) {
     const func = useTime === true ? getDayTimeIdentifier : getDayIdentifier;
@@ -1321,7 +1854,7 @@ function getTimestampSortValue(timestamp, useTime) {
     if (useTime === true) {
         return toUnixMilliseconds(timestamp);
     }
-    return Date.UTC(timestamp.year, timestamp.month - 1, timestamp.day);
+    return getEpochDay(timestamp) * MILLISECONDS_IN_DAY;
 }
 function compareTimestampOrder(first, second, useTime) {
     return getTimestampSortValue(first, useTime) - getTimestampSortValue(second, useTime);
@@ -1346,6 +1879,7 @@ function moveBoundary(timestamp, amount, useTime) {
  * @param {Timestamp} end Second boundary.
  * @param {boolean=} useTime Include time-of-day when ordering boundaries.
  * @returns {TimestampRange} Frozen inclusive Timestamp range.
+ * @category ranges
  */
 export function createTimestampRange(start, end, useTime = false) {
     if (compareTimestampOrder(start, end, useTime) <= 0) {
@@ -1360,6 +1894,7 @@ export function createTimestampRange(start, end, useTime = false) {
  * @param {TimestampRange} range Inclusive range to test against.
  * @param {boolean=} useTime Include time-of-day in the comparison.
  * @returns {boolean} True when the timestamp is inside the range.
+ * @category comparison
  */
 export function isTimestampInRange(timestamp, range, useTime = false) {
     return isBetweenDates(timestamp, range.start, range.end, useTime);
@@ -1371,6 +1906,7 @@ export function isTimestampInRange(timestamp, range, useTime = false) {
  * @param {TimestampRange} second Second range.
  * @param {boolean=} useTime Include time-of-day in the comparison.
  * @returns {boolean} True when the ranges overlap.
+ * @category comparison
  */
 export function isRangeOverlapping(first, second, useTime = false) {
     const firstRange = createTimestampRange(first.start, first.end, useTime);
@@ -1387,6 +1923,7 @@ export function isRangeOverlapping(first, second, useTime = false) {
  * @param {TimestampRange} second Second range.
  * @param {boolean=} useTime Include time-of-day in the comparison.
  * @returns {TimestampRange | null} Intersected range, or `null` when the ranges do not overlap.
+ * @category ranges
  */
 export function intersectRanges(first, second, useTime = false) {
     if (isRangeOverlapping(first, second, useTime) === false) {
@@ -1406,6 +1943,7 @@ export function intersectRanges(first, second, useTime = false) {
  * @param {TimestampRange[]} ranges Ranges to merge.
  * @param {boolean=} useTime Include time-of-day in the comparison.
  * @returns {TimestampRange[]} Merged ranges sorted by start boundary.
+ * @category ranges
  */
 export function mergeRanges(ranges, useTime = false) {
     const sorted = ranges
@@ -1433,6 +1971,7 @@ export function mergeRanges(ranges, useTime = false) {
  * @param {TimestampRange[]} blocked Ranges to remove from the source.
  * @param {boolean=} useTime Include time-of-day in the comparison.
  * @returns {TimestampRange[]} Remaining ranges.
+ * @category ranges
  */
 export function subtractRanges(source, blocked, useTime = false) {
     const normalizedSource = createTimestampRange(source.start, source.end, useTime);
@@ -1467,6 +2006,7 @@ export function subtractRanges(source, blocked, useTime = false) {
  * @param {TimestampRange[]} occupied Ranges that are not available.
  * @param {boolean=} useTime Include time-of-day in the comparison.
  * @returns {TimestampRange[]} Gap ranges.
+ * @category ranges
  */
 export function findRangeGaps(source, occupied, useTime = false) {
     return subtractRanges(source, occupied, useTime);
@@ -1479,6 +2019,7 @@ export function findRangeGaps(source, occupied, useTime = false) {
  * @param {Timestamp} endTimestamp Inclusive end boundary.
  * @param {boolean=} useTime Include time-of-day in the comparison when true.
  * @returns {boolean} True when the timestamp is inside the range.
+ * @category comparison
  */
 export function isBetweenDates(timestamp, startTimestamp, endTimestamp, useTime = false) {
     const cd = getDayIdentifier(timestamp) + (useTime === true ? getTimeIdentifier(timestamp) : 0);
@@ -1494,6 +2035,7 @@ export function isBetweenDates(timestamp, startTimestamp, endTimestamp, useTime
  * @param {Timestamp} firstTimestamp Start of the second range.
  * @param {Timestamp} lastTimestamp End of the second range.
  * @returns {boolean} True when the ranges overlap.
+ * @category comparison
  */
 export function isOverlappingDates(startTimestamp, endTimestamp, firstTimestamp, lastTimestamp) {
     const start = getDayIdentifier(startTimestamp);
@@ -1522,6 +2064,7 @@ export function isOverlappingDates(startTimestamp, endTimestamp, firstTimestamp,
  * @param {number=} options.second If positive, adds seconds. If negative, removes seconds.
  * @param {number=} options.millisecond If positive, adds milliseconds. If negative, removes milliseconds.
  * @returns {Timestamp} New normalized Timestamp object.
+ * @category arithmetic
  */
 export function addToDate(timestamp, options) {
     const ts = cloneTimestamp(timestamp);
@@ -1563,6 +2106,7 @@ export function addToDate(timestamp, options) {
  * @param {number=} options.second If positive, adds seconds. If negative, removes seconds.
  * @param {number=} options.millisecond If positive, adds milliseconds. If negative, removes milliseconds.
  * @returns {Timestamp} New normalized Timestamp object.
+ * @category arithmetic
  */
 export function addToDateClamped(timestamp, options) {
     const ts = cloneTimestamp(timestamp);
@@ -1588,6 +2132,7 @@ export function addToDateClamped(timestamp, options) {
  * Normalizes a year/month pair while keeping the day out of the calculation.
  * This lets clamped date math choose the final day explicitly instead of
  * letting JavaScript Date roll an overflowing day into the next month.
+ * @category arithmetic
  */
 function normalizeYearMonth(year, month) {
     const date = new Date(year, month - 1, 1);
@@ -1633,6 +2178,7 @@ function normalizeTimestamp(ts) {
  * @param {Timestamp} ts1 The first Timestamp
  * @param {Timestamp} ts2 The second Timestamp
  * @returns Number of days
+ * @category arithmetic
  */
 export function daysBetween(ts1, ts2) {
     const diff = diffTimestamp(ts1, ts2, true);
@@ -1642,6 +2188,7 @@ export function daysBetween(ts1, ts2) {
  * Returns number of weeks between two Timestamps
  * @param {Timestamp} ts1 The first Timestamp
  * @param {Timestamp} ts2 The second Timestamp
+ * @category arithmetic
  */
 export function weeksBetween(ts1, ts2) {
     let t1 = copyTimestamp(ts1);
@@ -1655,6 +2202,7 @@ export function weeksBetween(ts1, ts2) {
  *
  * @param {number} milliseconds Signed elapsed milliseconds.
  * @returns {TimestampDuration} Frozen duration object.
+ * @category duration
  */
 export function createDuration(milliseconds) {
     const sign = milliseconds === 0 ? 0 : milliseconds < 0 ? -1 : 1;
@@ -1687,6 +2235,7 @@ export function createDuration(milliseconds) {
  * @param {Timestamp} start Start timestamp.
  * @param {Timestamp} end End timestamp.
  * @returns {TimestampDuration} Frozen duration object.
+ * @category duration
  */
 export function durationBetween(start, end) {
     return createDuration(toUnixMilliseconds(end) - toUnixMilliseconds(start));
@@ -1701,9 +2250,10 @@ export function durationBetween(start, end) {
  * @param {Timestamp} timestamp Timestamp object to offset.
  * @param {TimestampDuration | number} duration Duration object or signed milliseconds.
  * @returns {Timestamp} Offset Timestamp.
+ * @category duration
  */
 export function addDuration(timestamp, duration) {
-    const milliseconds = typeof duration === "number" ? duration : duration.totalMilliseconds;
+    const milliseconds = typeof duration === 'number' ? duration : duration.totalMilliseconds;
     return fromUnixMilliseconds(toUnixMilliseconds(timestamp) + milliseconds);
 }
 /**
@@ -1712,9 +2262,10 @@ export function addDuration(timestamp, duration) {
  * @param {Timestamp} timestamp Timestamp object to offset.
  * @param {TimestampDuration | number} duration Duration object or signed milliseconds.
  * @returns {Timestamp} Offset Timestamp.
+ * @category duration
  */
 export function subtractDuration(timestamp, duration) {
-    const milliseconds = typeof duration === "number" ? duration : duration.totalMilliseconds;
+    const milliseconds = typeof duration === 'number' ? duration : duration.totalMilliseconds;
     return addDuration(timestamp, -milliseconds);
 }
 /**
@@ -1725,11 +2276,12 @@ export function subtractDuration(timestamp, duration) {
  * @param {TimestampDuration | number} duration Duration object or signed milliseconds.
  * @param {FormatDurationOptions=} options Formatting options.
  * @returns {string} Formatted duration.
+ * @category duration
  */
 export function formatDuration(duration, options = {}) {
-    const value = typeof duration === "number" ? createDuration(duration) : duration;
+    const value = typeof duration === 'number' ? createDuration(duration) : duration;
     const hours = value.days * HOURS_IN_DAY + value.hours;
-    const sign = options.signed === true && value.sign < 0 ? "-" : "";
+    const sign = options.signed === true && value.sign < 0 ? '-' : '';
     let formatted = `${sign}${padNumber(hours, 2)}:${padNumber(value.minutes, 2)}:${padNumber(value.seconds, 2)}`;
     if (options.milliseconds === true) {
         formatted += `.${padNumber(value.milliseconds, 3)}`;
@@ -1750,6 +2302,7 @@ function roundTimestampToInterval(timestamp, minutes, rounder) {
  * @param {Timestamp} timestamp Timestamp object to round.
  * @param {number} minutes Interval size in minutes.
  * @returns {Timestamp} Rounded Timestamp.
+ * @category arithmetic
  */
 export function floorToInterval(timestamp, minutes) {
     return roundTimestampToInterval(timestamp, minutes, Math.floor);
@@ -1760,6 +2313,7 @@ export function floorToInterval(timestamp, minutes) {
  * @param {Timestamp} timestamp Timestamp object to round.
  * @param {number} minutes Interval size in minutes.
  * @returns {Timestamp} Rounded Timestamp.
+ * @category arithmetic
  */
 export function ceilToInterval(timestamp, minutes) {
     return roundTimestampToInterval(timestamp, minutes, Math.ceil);
@@ -1770,22 +2324,23 @@ export function ceilToInterval(timestamp, minutes) {
  * @param {Timestamp} timestamp Timestamp object to round.
  * @param {number} minutes Interval size in minutes.
  * @returns {Timestamp} Rounded Timestamp.
+ * @category arithmetic
  */
 export function roundToInterval(timestamp, minutes) {
     return roundTimestampToInterval(timestamp, minutes, Math.round);
 }
 // Known dates
 const weekdayDateMap = {
-    Sun: new Date("2020-01-05T00:00:00.000Z"),
-    Mon: new Date("2020-01-06T00:00:00.000Z"),
-    Tue: new Date("2020-01-07T00:00:00.000Z"),
-    Wed: new Date("2020-01-08T00:00:00.000Z"),
-    Thu: new Date("2020-01-09T00:00:00.000Z"),
-    Fri: new Date("2020-01-10T00:00:00.000Z"),
-    Sat: new Date("2020-01-11T00:00:00.000Z"),
+    Sun: new Date('2020-01-05T00:00:00.000Z'),
+    Mon: new Date('2020-01-06T00:00:00.000Z'),
+    Tue: new Date('2020-01-07T00:00:00.000Z'),
+    Wed: new Date('2020-01-08T00:00:00.000Z'),
+    Thu: new Date('2020-01-09T00:00:00.000Z'),
+    Fri: new Date('2020-01-10T00:00:00.000Z'),
+    Sat: new Date('2020-01-11T00:00:00.000Z'),
 };
 function resolveIntlNameFormat(options, type) {
-    if (type === "long" || type === "short" || type === "narrow") {
+    if (type === 'long' || type === 'short' || type === 'narrow') {
         return options[type];
     }
     return options.long;
@@ -1806,15 +2361,16 @@ function resolveIntlNameFormat(options, type) {
  * @param {string} [locale=''] - The locale to use for formatting.
  *
  * @returns {string} The formatted weekday.
+ * @category locale
  */
 export function getWeekdayFormatter() {
-    const emptyFormatter = () => "";
+    const emptyFormatter = () => '';
     const options = {
-        long: { timeZone: "UTC", weekday: "long" },
-        short: { timeZone: "UTC", weekday: "short" },
-        narrow: { timeZone: "UTC", weekday: "narrow" },
+        long: { timeZone: 'UTC', weekday: 'long' },
+        short: { timeZone: 'UTC', weekday: 'short' },
+        narrow: { timeZone: 'UTC', weekday: 'narrow' },
     };
-    if (typeof Intl === "undefined" || typeof Intl.DateTimeFormat === "undefined") {
+    if (typeof Intl === 'undefined' || typeof Intl.DateTimeFormat === 'undefined') {
         return emptyFormatter;
     }
     /**
@@ -1834,7 +2390,7 @@ export function getWeekdayFormatter() {
             if (e instanceof Error) {
                 console.error(`Intl.DateTimeFormat: ${e.message} -> day of week: ${weekday}`);
             }
-            return "";
+            return '';
         }
     }
     return weekdayFormatter;
@@ -1845,6 +2401,7 @@ export function getWeekdayFormatter() {
  * @param {string} type Format type: `narrow`, `short`, or `long`.
  * @param {string} locale Locale to use for formatting, such as `en-US`.
  * @returns {string[]} Localized weekday names in Sunday-first order.
+ * @category locale
  */
 export function getWeekdayNames(type, locale) {
     const shortWeekdays = Object.keys(weekdayDateMap);
@@ -1862,15 +2419,16 @@ export function getWeekdayNames(type, locale) {
  *   @returns {string} The formatted month name.
  *
  * @throws {Error} If Intl or Intl.DateTimeFormat is not supported in the environment.
+ * @category locale
  */
 export function getMonthFormatter() {
-    const emptyFormatter = () => "";
+    const emptyFormatter = () => '';
     const options = {
-        long: { timeZone: "UTC", month: "long" },
-        short: { timeZone: "UTC", month: "short" },
-        narrow: { timeZone: "UTC", month: "narrow" },
+        long: { timeZone: 'UTC', month: 'long' },
+        short: { timeZone: 'UTC', month: 'short' },
+        narrow: { timeZone: 'UTC', month: 'narrow' },
     };
-    if (typeof Intl === "undefined" || typeof Intl.DateTimeFormat === "undefined") {
+    if (typeof Intl === 'undefined' || typeof Intl.DateTimeFormat === 'undefined') {
         return emptyFormatter;
     }
     /**
@@ -1881,7 +2439,7 @@ export function getMonthFormatter() {
      * @param {string} [locale] - The locale to use for formatting (defaults to the system locale if not provided).
      * @returns {string} The formatted month string.
      */
-    function monthFormatter(month, type = "long", locale) {
+    function monthFormatter(month, type = 'long', locale) {
         try {
             const intlFormatter = new Intl.DateTimeFormat(locale || undefined, resolveIntlNameFormat(options, type));
             const date = new Date();
@@ -1893,7 +2451,7 @@ export function getMonthFormatter() {
             if (e instanceof Error) {
                 console.error(`Intl.DateTimeFormat: ${e.message} -> month: ${month}`);
             }
-            return "";
+            return '';
         }
     }
     return monthFormatter;
@@ -1904,6 +2462,7 @@ export function getMonthFormatter() {
  * @param {string} type Format type: `narrow`, `short`, or `long`.
  * @param {string} locale Locale to use for formatting, such as `en-US`.
  * @returns {string[]} Localized month names in January-first order.
+ * @category locale
  */
 export function getMonthNames(type, locale) {
     const monthFormatter = getMonthFormatter();