@timestamp-js/core 0.1.0-alpha.1 → 0.1.0-alpha.3

package/dist/index.js

@@ -112,7 +112,7 @@ export const MILLISECONDS_IN_WEEK = TIME_CONSTANTS.MILLISECONDS_IN.WEEK;
 /**
  * Frozen empty timestamp template.
  *
- * Use {@link copyTimestamp} or parser helpers to create new timestamp objects
+ * Use copyTimestamp or parser helpers to create new timestamp objects
  * instead of mutating this shared default.
  */
 export const Timestamp = freezeTimestamp({
@@ -163,11 +163,11 @@ export function validateTimestamp(input) {
  * Fast low-level parser for date and date-time strings.
  *
  * This parser fills numeric fields, but does not update formatted date,
- * weekday, day-of-year, workweek, or relative flags. Use
- * {@link parseTimestamp} when those derived fields are needed.
+ * weekday, day-of-year, workweek, or relative flags. Use parseTimestamp()
+ * when those derived fields are needed.
  *
  * @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} This {@link Timestamp} is minimally filled in. The {@link Timestamp.date} and {@link Timestamp.time} as well as relative data will not be filled in.
+ * @returns {Timestamp} Minimal Timestamp object, or `null` when the input cannot be parsed.
  */
 export function parsed(input) {
     if (typeof input !== "string")
@@ -211,13 +211,7 @@ export function parsed(input) {
     timestamp.time = getTime(timestamp);
     return freezeTimestamp(timestamp);
 }
-/**
- * Takes a JavaScript Date and returns a {@link Timestamp}. The {@link Timestamp} is not updated with relative information.
- * @param {Date} date JavaScript Date
- * @param {boolean} utc If set the {@link Timestamp} will parse the Date as UTC
- * @returns {Timestamp} A minimal {@link Timestamp} without updated or relative updates.
- */
-export function parseDate(date, utc = false) {
+function parseDateByMode(date, utc) {
     if (!(date instanceof Date))
         return null;
     const UTC = utc ? "UTC" : "";
@@ -255,6 +249,30 @@ export function parseDate(date, utc = false) {
     }
     return updateFormatted(timestamp);
 }
+/**
+ * Converts a JavaScript Date into a formatted Timestamp using host-local fields.
+ *
+ * Use parseDateUTC() when the Date represents an instant that should be read
+ * with UTC getters instead of host-local getters.
+ *
+ * @param {Date} date JavaScript Date to convert.
+ * @returns {Timestamp} Formatted Timestamp object, or `null` for invalid input.
+ */
+export function parseDate(date) {
+    return parseDateByMode(date, false);
+}
+/**
+ * Converts a JavaScript Date into a formatted Timestamp using UTC fields.
+ *
+ * Use this when server and client output should agree on the same UTC calendar
+ * and time fields for a native Date instant.
+ *
+ * @param {Date} date JavaScript Date to convert.
+ * @returns {Timestamp} Formatted Timestamp object, or `null` for invalid input.
+ */
+export function parseDateUTC(date) {
+    return parseDateByMode(date, true);
+}
 /**
  * Pads a number to a requested string length.
  *
@@ -290,9 +308,10 @@ export function daysInMonth(year, month) {
     return (isLeapYear(year) ? DAYS_IN_MONTH_LEAP[month] : DAYS_IN_MONTH[month]);
 }
 /**
- * Returns a {@link Timestamp} of next day from passed in {@link Timestamp}
- * @param {Timestamp} timestamp The {@link Timestamp} to use
- * @returns {Timestamp} A new {@link Timestamp} representing the next day
+ * Returns a new Timestamp for the next calendar day.
+ *
+ * @param {Timestamp} timestamp Base Timestamp object.
+ * @returns {Timestamp} New Timestamp representing the next day.
  */
 export function nextDay(timestamp) {
     const date = new Date(timestamp.year, timestamp.month - 1, timestamp.day + 1);
@@ -304,9 +323,10 @@ export function nextDay(timestamp) {
     }));
 }
 /**
- * Returns a {@link Timestamp} of previous day from passed in {@link Timestamp}
- * @param {Timestamp} timestamp The {@link Timestamp} to use
- * @returns {Timestamp} A new {@link Timestamp} representing the previous day
+ * Returns a new Timestamp for the previous calendar day.
+ *
+ * @param {Timestamp} timestamp Base Timestamp object.
+ * @returns {Timestamp} New Timestamp representing the previous day.
  */
 export function prevDay(timestamp) {
     const date = new Date(timestamp.year, timestamp.month - 1, timestamp.day - 1);
@@ -318,13 +338,48 @@ export function prevDay(timestamp) {
     }));
 }
 /**
- * Returns today's date
+ * Returns today's date using the host runtime timezone.
+ *
+ * For SSR or static rendering, server and client runtimes can produce different
+ * values when they run in different timezones. Use todayUTC() when the app
+ * wants a stable UTC calendar date instead.
+ *
  * @returns {string} Date string in the form `YYYY-MM-DD`
  */
 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("-");
 }
+/**
+ * Returns today's date using UTC calendar fields.
+ *
+ * Pass a Date fixture to make SSR, tests, and hydration-sensitive render paths
+ * deterministic. This helper reads UTC fields only; it does not convert an
+ * existing Timestamp or timezone-suffixed string.
+ *
+ * @param {Date} date Date source to read. Defaults to the current Date.
+ * @returns {string} UTC date string in the form `YYYY-MM-DD`
+ */
+export function todayUTC(date = new Date()) {
+    return [
+        padNumber(date.getUTCFullYear(), 4),
+        padNumber(date.getUTCMonth() + 1, 2),
+        padNumber(date.getUTCDate(), 2),
+    ].join("-");
+}
+/**
+ * Returns the current date-time as an immutable Timestamp using UTC fields.
+ *
+ * Use this when server and client output should agree on UTC calendar and time
+ * values. For fully deterministic SSR output, pass a Date captured by the
+ * caller instead of allowing each runtime to create its own current Date.
+ *
+ * @param {Date} date Date source to read. Defaults to the current Date.
+ * @returns {Timestamp} Immutable Timestamp built from UTC fields.
+ */
+export function nowUTC(date = new Date()) {
+    return parseDateUTC(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'
@@ -334,12 +389,25 @@ export function isToday(date) {
     return date === today();
 }
 /**
- * Returns the start of the week give a {@link Timestamp} and weekdays (in which it finds the day representing the start of the week).
- * If today {@link Timestamp} is passed in then this is used to update relative information in the returned {@link Timestamp}.
- * @param {Timestamp} timestamp The {@link Timestamp} to use to find the start of the week
+ * Checks whether a date string matches today's UTC date.
+ *
+ * Pass a Date fixture when SSR, tests, or hydration-sensitive render paths need
+ * deterministic behavior.
+ *
+ * @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.
+ */
+export function isTodayUTC(date, now = new Date()) {
+    return date === todayUTC(now);
+}
+/**
+ * Returns the start of the week for a Timestamp and weekday set.
+ * If a current Timestamp is provided, the returned Timestamp includes updated relative information.
+ * @param {Timestamp} timestamp The Timestamp to use to find the start of the week
  * @param {number[]} weekdays The array is [0,1,2,3,4,5,6] where 0=Sunday and 6=Saturday
- * @param {Timestamp=} today If passed in then the {@link Timestamp} is updated with relative information
- * @returns {Timestamp} A new {@link Timestamp} representing the start of the week
+ * @param {Timestamp=} today Current timestamp used to update relative information
+ * @returns {Timestamp} A new Timestamp representing the start of the week
  */
 export function getStartOfWeek(timestamp, weekdays, today) {
     let start = cloneTimestamp(timestamp);
@@ -359,12 +427,12 @@ export function getStartOfWeek(timestamp, weekdays, today) {
     return start;
 }
 /**
- * Returns the end of the week give a {@link Timestamp} and weekdays (in which it finds the day representing the last of the week).
- * If today {@link Timestamp} is passed in then this is used to update relative information in the returned {@link Timestamp}.
- * @param {Timestamp} timestamp The {@link Timestamp} to use to find the end of the week
+ * Returns the end of the week for a Timestamp and weekday set.
+ * If a current Timestamp is provided, the returned Timestamp includes updated relative information.
+ * @param {Timestamp} timestamp The Timestamp to use to find the end of the week
  * @param {number[]} weekdays The array is [0,1,2,3,4,5,6] where 0=Sunday and 6=Saturday
- * @param {Timestamp=} today If passed in then the {@link Timestamp} is updated with relative information
- * @returns {Timestamp} A new {@link Timestamp} representing the end of the week
+ * @param {Timestamp=} today Current timestamp used to update relative information
+ * @returns {Timestamp} A new Timestamp representing the end of the week
  */
 export function getEndOfWeek(timestamp, weekdays, today) {
     let end = cloneTimestamp(timestamp);
@@ -386,9 +454,9 @@ export function getEndOfWeek(timestamp, weekdays, today) {
     return end;
 }
 /**
- * Finds the start of the month based on the passed in {@link Timestamp}
- * @param {Timestamp} timestamp The {@link Timestamp} to use to find the start of the month
- * @returns {Timestamp} A {@link Timestamp} of the start of the month
+ * 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
  */
 export function getStartOfMonth(timestamp) {
     let start = cloneTimestamp(timestamp);
@@ -397,9 +465,9 @@ export function getStartOfMonth(timestamp) {
     return start;
 }
 /**
- * Finds the end of the month based on the passed in {@link Timestamp}
- * @param {Timestamp} timestamp The {@link Timestamp} to use to find the end of the month
- * @returns {Timestamp} A {@link Timestamp} of the end of the month
+ * 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
  */
 export function getEndOfMonth(timestamp) {
     let end = cloneTimestamp(timestamp);
@@ -445,10 +513,11 @@ export function parseTime(input) {
     return false;
 }
 /**
- * Compares two {@link Timestamp}s for exactness
- * @param {Timestamp} ts1 The first {@link Timestamp}
- * @param {Timestamp} ts2 The second {@link Timestamp}
- * @returns {boolean} True if the two {@link Timestamp}s are an exact match
+ * Compares two Timestamp objects for exact date, time, and timezone equality.
+ *
+ * @param {Timestamp} ts1 First Timestamp object.
+ * @param {Timestamp} ts2 Second Timestamp object.
+ * @returns {boolean} True when both timestamps match exactly.
  */
 export function compareTimestamps(ts1, ts2) {
     if (!ts1 || !ts2)
@@ -463,41 +532,44 @@ export function compareTimestamps(ts1, ts2) {
         ts1.timezone === ts2.timezone);
 }
 /**
- * Compares the date of two {@link Timestamp}s that have been updated with relative data
- * @param {Timestamp} ts1 The first {@link Timestamp}
- * @param {Timestamp} ts2 The second {@link Timestamp}
- * @returns {boolean} True if the two dates are the same
+ * Compares the calendar date portion of two Timestamp objects.
+ *
+ * @param {Timestamp} ts1 First Timestamp object.
+ * @param {Timestamp} ts2 Second Timestamp object.
+ * @returns {boolean} True when both dates are the same.
  */
 export function compareDate(ts1, ts2) {
     return getDate(ts1) === getDate(ts2);
 }
 /**
- * Compares the time of two {@link Timestamp}s that have been updated with relative data
- * @param {Timestamp} ts1 The first {@link Timestamp}
- * @param {Timestamp} ts2 The second {@link Timestamp}
- * @returns {boolean} True if the two times are an exact match
+ * Compares the formatted time portion of two Timestamp objects.
+ *
+ * @param {Timestamp} ts1 First Timestamp object.
+ * @param {Timestamp} ts2 Second Timestamp object.
+ * @returns {boolean} True when both times are the same.
  */
 export function compareTime(ts1, ts2) {
     return getTime(ts1) === getTime(ts2);
 }
 /**
- * Compares the date and time of two {@link Timestamp}s that have been updated with relative data
- * @param {Timestamp} ts1 The first {@link Timestamp}
- * @param {Timestamp} ts2 The second {@link Timestamp}
- * @returns {boolean} True if the date and time are an exact match
+ * Compares the formatted date and time portions of two Timestamp objects.
+ *
+ * @param {Timestamp} ts1 First Timestamp object.
+ * @param {Timestamp} ts2 Second Timestamp object.
+ * @returns {boolean} True when both date-time values are the same.
  */
 export function compareDateTime(ts1, ts2) {
     return getDateTime(ts1) === getDateTime(ts2);
 }
 /**
- * High-level parser that converts a string to a fully formatted {@link Timestamp}.
+ * Converts a supported date or date-time string into a formatted Timestamp object.
  *
  * If `now` is supplied, the returned timestamp also includes relative flags
  * such as `past`, `current`, `future`, and `currentWeekday`.
  *
- * @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.
- * @param {Timestamp} now A {@link Timestamp} to use for relative data updates
- * @returns {Timestamp} The {@link Timestamp.date} will be filled in as well as the {@link Timestamp.time} if a time is supplied and formatted fields (doy, weekday, workweek, etc). If 'now' is supplied, then relative data will also be updated.
+ * @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.
  */
 export function parseTimestamp(input, now = null) {
     let timestamp = parsed(input);
@@ -510,9 +582,10 @@ export function parseTimestamp(input, now = null) {
     return timestamp;
 }
 /**
- * Converts a {@link Timestamp} into a numeric date identifier based on the passed {@link Timestamp}'s date
- * @param {Timestamp} timestamp The {@link Timestamp} to use
- * @returns {number} The numeric date identifier
+ * Converts a Timestamp date into a sortable numeric identifier.
+ *
+ * @param {Timestamp} timestamp Timestamp object to read.
+ * @returns {number} Numeric date identifier.
  */
 export function getDayIdentifier(timestamp) {
     return ((timestamp.year ?? 0) * 100000000 +
@@ -520,9 +593,10 @@ export function getDayIdentifier(timestamp) {
         (timestamp.day ?? 0) * 10000);
 }
 /**
- * Converts a {@link Timestamp} into a numeric time identifier based on the passed {@link Timestamp}'s time
- * @param {Timestamp} timestamp The {@link Timestamp} to use
- * @returns {number} The numeric time identifier
+ * Converts a Timestamp time into a sortable numeric identifier.
+ *
+ * @param {Timestamp} timestamp Timestamp object to read.
+ * @returns {number} Numeric time identifier.
  */
 export function getTimeIdentifier(timestamp) {
     return (timestamp.hour ?? 0) * 100 + (timestamp.minute ?? 0);
@@ -535,17 +609,18 @@ function getTimeComparisonValue(timestamp) {
         (timestamp.millisecond ?? 0));
 }
 /**
- * Converts a {@link Timestamp} into a numeric date and time identifier based on the passed {@link Timestamp}'s date and time
- * @param {Timestamp} timestamp The {@link Timestamp} to use
- * @returns {number} The numeric date+time identifier
+ * Converts a Timestamp date and time into a sortable numeric identifier.
+ *
+ * @param {Timestamp} timestamp Timestamp object to read.
+ * @returns {number} Numeric date-time identifier.
  */
 export function getDayTimeIdentifier(timestamp) {
     return getDayIdentifier(timestamp) + getTimeIdentifier(timestamp);
 }
 /**
- * Returns the difference between two {@link Timestamp}s
- * @param {Timestamp} ts1 The first {@link Timestamp}
- * @param {Timestamp} ts2 The second {@link Timestamp}
+ * Returns the difference between two Timestamps
+ * @param {Timestamp} ts1 The first Timestamp
+ * @param {Timestamp} ts2 The second Timestamp
  * @param {boolean=} strict Optional flag to not to return negative numbers
  * @returns {number} The difference
  */
@@ -560,11 +635,16 @@ export function diffTimestamp(ts1, ts2, strict = false) {
     return utc2 - utc1;
 }
 /**
- * Updates a {@link Timestamp} with relative data (past, current and future)
- * @param {Timestamp} timestamp The {@link Timestamp} that needs relative data updated
- * @param {Timestamp} now {@link Timestamp} that represents the current date (optional time)
- * @param {boolean=} time Optional flag to include time ('timestamp' and 'now' params should have time values)
- * @returns {Timestamp} A new {@link Timestamp}
+ * Returns a Timestamp with relative flags compared to a supplied `now` value.
+ *
+ * The returned object includes `past`, `current`, `future`, and
+ * `currentWeekday` flags. Pass `true` for `time` when both values should be
+ * compared at time-of-day precision.
+ *
+ * @param {Timestamp} timestamp Timestamp object to update.
+ * @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.
  */
 export function updateRelative(timestamp, now, time = false) {
     const ts = cloneTimestamp(timestamp);
@@ -588,10 +668,10 @@ export function updateRelative(timestamp, now, time = false) {
  * The returned timestamp has updated hour/minute fields and clears second and
  * millisecond precision because this helper is minute-oriented.
  *
- * @param {Timestamp} timestamp The {@link Timestamp} to transform
+ * @param {Timestamp} timestamp The Timestamp to transform
  * @param {number} minutes The number of minutes to set from midnight
- * @param {Timestamp=} now Optional {@link Timestamp} representing current date and time
- * @returns {Timestamp} A new {@link Timestamp}
+ * @param {Timestamp=} now Optional Timestamp representing current date and time
+ * @returns {Timestamp} A new Timestamp
  */
 export function updateMinutes(timestamp, minutes, now = null) {
     let ts = cloneTimestamp(timestamp);
@@ -607,8 +687,8 @@ export function updateMinutes(timestamp, minutes, now = null) {
     return freezeTimestamp(ts);
 }
 /**
- * Updates the {@link Timestamp} with the weekday
- * @param {Timestamp} timestamp The {@link Timestamp} to transform
+ * Updates the Timestamp with the weekday
+ * @param {Timestamp} timestamp The Timestamp to transform
  * @returns A new Timestamp
  */
 export function updateWeekday(timestamp) {
@@ -617,8 +697,8 @@ export function updateWeekday(timestamp) {
     return freezeTimestamp(ts);
 }
 /**
- * Updates the {@link Timestamp} with the day of the year (doy)
- * @param {Timestamp} timestamp The {@link Timestamp} to transform
+ * Updates the Timestamp with the day of the year (doy)
+ * @param {Timestamp} timestamp The Timestamp to transform
  * @returns A new Timestamp
  */
 export function updateDayOfYear(timestamp) {
@@ -627,9 +707,9 @@ export function updateDayOfYear(timestamp) {
     return freezeTimestamp(ts);
 }
 /**
- * Updates the {@link Timestamp} with the workweek
- * @param {Timestamp} timestamp The {@link Timestamp} to transform
- * @returns A new {@link Timestamp}
+ * Updates the Timestamp with the workweek
+ * @param {Timestamp} timestamp The Timestamp to transform
+ * @returns A new Timestamp
  */
 export function updateWorkWeek(timestamp) {
     const ts = cloneTimestamp(timestamp);
@@ -682,13 +762,13 @@ function isTimestampInDisabledDay(timestamp, day) {
     return disabledDay !== null && getDayIdentifier(disabledDay) === target;
 }
 /**
- * Updates the passed {@link Timestamp} with disabled, if needed
- * @param {Timestamp} timestamp The {@link Timestamp} to transform
+ * Updates the passed Timestamp with disabled, if needed
+ * @param {Timestamp} timestamp The Timestamp to transform
  * @param {string} [disabledBefore] In `YYYY-MM-DD` format
  * @param {string} [disabledAfter] In `YYYY-MM-DD` format
  * @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 {@link Timestamp}
+ * @returns A new Timestamp
  */
 export function updateDisabled(timestamp, disabledBefore, disabledAfter, disabledWeekdays, disabledDays) {
     let ts = cloneTimestamp(timestamp);
@@ -730,9 +810,9 @@ export function updateDisabled(timestamp, disabledBefore, disabledAfter, disable
     return freezeTimestamp(ts);
 }
 /**
- * Updates the passed {@link Timestamp} with formatted data (time string, date string, weekday, day of year and workweek)
- * @param {Timestamp} timestamp The {@link Timestamp} to transform
- * @returns A new {@link Timestamp}
+ * 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
  */
 export function updateFormatted(timestamp) {
     const ts = cloneTimestamp(timestamp);
@@ -745,8 +825,8 @@ export function updateFormatted(timestamp) {
     return freezeTimestamp(ts);
 }
 /**
- * Returns day of the year (doy) for the passed in {@link Timestamp}
- * @param {Timestamp} timestamp The {@link Timestamp} to use
+ * 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
  */
 export function getDayOfYear(timestamp) {
@@ -760,8 +840,8 @@ export function getDayOfYear(timestamp) {
         1000);
 }
 /**
- * Returns workweek for the passed in {@link Timestamp}
- * @param {Timestamp} timestamp The {@link Timestamp} to use
+ * Returns workweek for the passed in Timestamp
+ * @param {Timestamp} timestamp The Timestamp to use
  * @returns {number} The work week
  */
 export function getWorkWeek(timestamp) {
@@ -787,8 +867,8 @@ export function getWorkWeek(timestamp) {
     return weekNumber;
 }
 /**
- * Returns weekday for the passed in {@link Timestamp}
- * @param {Timestamp} timestamp The {@link Timestamp} to use
+ * Returns weekday for the passed in Timestamp
+ * @param {Timestamp} timestamp The Timestamp to use
  * @returns {number} The weekday
  */
 export function getWeekday(timestamp) {
@@ -813,17 +893,19 @@ export function getWeekday(timestamp) {
     return weekday ?? 0;
 }
 /**
- * Makes a copy of the passed in {@link Timestamp}
- * @param {Timestamp} timestamp The original {@link Timestamp}
- * @returns {Timestamp} A copy of the original {@link Timestamp}
+ * Returns an immutable copy of a Timestamp object.
+ *
+ * @param {Timestamp} timestamp Timestamp object to copy.
+ * @returns {Timestamp} Frozen Timestamp copy.
  */
 export function copyTimestamp(timestamp) {
     return freezeTimestamp(timestamp);
 }
 /**
- * Used internally to convert {@link Timestamp} used with 'parsed' or 'parseDate' so the 'date' portion of the {@link Timestamp} is correct.
- * @param {Timestamp} timestamp The (raw) {@link Timestamp}
- * @returns {string} A formatted date ('YYYY-MM-DD')
+ * Formats the date portion of a Timestamp object.
+ *
+ * @param {Timestamp} timestamp Timestamp object to format.
+ * @returns {string} Date string such as `YYYY-MM-DD`.
  */
 export function getDate(timestamp) {
     let str = `${padNumber(timestamp.year, 4)}-${padNumber(timestamp.month, 2)}`;
@@ -832,9 +914,13 @@ export function getDate(timestamp) {
     return str;
 }
 /**
- * Used internally to convert {@link Timestamp} with 'parsed' or 'parseDate' so the 'time' portion of the {@link Timestamp} is correct.
- * @param {Timestamp} timestamp The (raw) {@link Timestamp}
- * @returns {string} A formatted time ('hh:mm')
+ * Formats the time portion of a Timestamp object.
+ *
+ * Minute precision is formatted as `HH:mm`; second precision as `HH:mm:ss`;
+ * millisecond precision as `HH:mm:ss.SSS`.
+ *
+ * @param {Timestamp} timestamp Timestamp object to format.
+ * @returns {string} Time string, or an empty string when the timestamp has no time.
  */
 export function getTime(timestamp) {
     if (!timestamp.hasTime) {
@@ -850,31 +936,32 @@ export function getTime(timestamp) {
     return time;
 }
 /**
- * Returns a formatted string date and time ('YYYY-YY-MM hh:mm')
- * @param {Timestamp} timestamp The {@link Timestamp}
- * @returns {string} A formatted date time ('YYYY-MM-DD HH:mm')
+ * Formats a Timestamp as date plus time.
+ *
+ * @param {Timestamp} timestamp Timestamp object to format.
+ * @returns {string} Date-time string such as `YYYY-MM-DD HH:mm`.
  */
 export function getDateTime(timestamp) {
     return getDate(timestamp) + " " + (timestamp.hasTime ? getTime(timestamp) : "00:00");
 }
 /**
- * An alias for {relativeDays}
- * @param {Timestamp} timestamp The {@link Timestamp} to transform
+ * Alias for relativeDays.
+ * @param {Timestamp} timestamp The Timestamp to transform
  * @param {function} [mover=nextDay] The mover function to use (ie: {nextDay} or {prevDay}).
  * @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 {@link Timestamp}
+ * @returns A new Timestamp
  */
 export function moveRelativeDays(timestamp, mover = nextDay, days = 1, allowedWeekdays = [0, 1, 2, 3, 4, 5, 6]) {
     return relativeDays(timestamp, mover, days, allowedWeekdays);
 }
 /**
- * Moves the {@link Timestamp} the number of relative days
- * @param {Timestamp} timestamp The {@link Timestamp} to transform
+ * Moves the Timestamp the number of relative days
+ * @param {Timestamp} timestamp The Timestamp to transform
  * @param {function} [mover=nextDay] The mover function to use (ie: {nextDay} or {prevDay}).
  * @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 {@link Timestamp}
+ * @returns A new Timestamp
  */
 export function relativeDays(timestamp, mover = nextDay, days = 1, allowedWeekdays = [0, 1, 2, 3, 4, 5, 6]) {
     let ts = copyTimestamp(timestamp);
@@ -890,12 +977,12 @@ export function relativeDays(timestamp, mover = nextDay, days = 1, allowedWeekda
     return ts;
 }
 /**
- * Finds the specified weekday (forward or back) based on the {@link Timestamp}
- * @param {Timestamp} timestamp The {@link Timestamp} to transform
+ * Finds the specified weekday (forward or back) based on the Timestamp
+ * @param {Timestamp} timestamp The Timestamp to transform
  * @param {number} weekday The weekday number (Sun = 0, ..., Sat = 6)
  * @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 {@link Timestamp}
+ * @returns A new Timestamp
  */
 export function findWeekday(timestamp, weekday, mover = nextDay, maxDays = 6) {
     let ts = copyTimestamp(timestamp);
@@ -904,18 +991,22 @@ export function findWeekday(timestamp, weekday, mover = nextDay, maxDays = 6) {
     return ts;
 }
 /**
- * Creates an array of {@link Timestamp}s based on start and end params
- * @param {Timestamp} start The starting {@link Timestamp}
- * @param {Timestamp} end The ending {@link Timestamp}
- * @param {Timestamp} now The relative day
- * @param {number[]} weekdays An array of numbers (representing days of the week) that are 0 (=Sunday) to 6 (=Saturday)
- * @param {string} [disabledBefore] Days before this date are disabled (YYYY-MM-DD)
- * @param {string} [disabledAfter] Days after this date are disabled (YYYY-MM-DD)
- * @param {number[]} [disabledWeekdays] An array representing weekdays that are disabled [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.
- * @param {number} [max=42] Max days to do
- * @param {number} [min=0]  Min days to do
- * @returns {Timestamp[]} The requested array of {@link Timestamp}s
+ * Creates an inclusive list of Timestamp days between start and end.
+ *
+ * The returned days are formatted, marked with relative flags against `now`,
+ * and can include disabled metadata when disabled options are supplied.
+ *
+ * @param {Timestamp} start First day in the list.
+ * @param {Timestamp} end Last day boundary for the list.
+ * @param {Timestamp} now Timestamp used to calculate relative flags.
+ * @param {number[]} weekdays Weekday numbers to include, from `0` Sunday to `6` Saturday.
+ * @param {string} [disabledBefore] Disable days before this `YYYY-MM-DD` date.
+ * @param {string} [disabledAfter] Disable days after this `YYYY-MM-DD` date.
+ * @param {number[]} [disabledWeekdays] Weekday numbers to mark disabled.
+ * @param {DisabledDays} [disabledDays] Specific dates or date ranges to mark disabled.
+ * @param {number} [max=42] Maximum number of days to return.
+ * @param {number} [min=0] Minimum number of days to return.
+ * @returns {Timestamp[]} Timestamp days.
  */
 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);
@@ -947,13 +1038,14 @@ export function createDayList(start, end, now, weekdays = [0, 1, 2, 3, 4, 5, 6],
     return days;
 }
 /**
- * Creates an array of interval {@link Timestamp}s based on params
- * @param {Timestamp} timestamp The starting {@link Timestamp}
- * @param {number} first The starting interval time
- * @param {number} minutes How many minutes between intervals (ie: 60, 30, 15 would be common ones)
- * @param {number} count The number of intervals needed
- * @param {Timestamp} now A relative {@link Timestamp} with time
- * @returns {Timestamp[]} The requested array of interval {@link Timestamp}s
+ * Creates an array of interval Timestamp objects for one day.
+ *
+ * @param {Timestamp} timestamp Base date for the intervals.
+ * @param {number} first Starting interval index.
+ * @param {number} minutes Minutes between intervals, such as 60, 30, or 15.
+ * @param {number} count Number of intervals to create.
+ * @param {Timestamp} now Timestamp used to calculate relative flags.
+ * @returns {Timestamp[]} Interval Timestamp objects.
  */
 export function createIntervalList(timestamp, first, minutes, count, now) {
     const intervals = [];
@@ -965,76 +1057,109 @@ export function createIntervalList(timestamp, first, minutes, count, now) {
 }
 /**
  * @callback getOptions
- * @param {Timestamp} timestamp A {@link Timestamp} object
+ * @param {Timestamp} timestamp A Timestamp object
  * @param {boolean} short True if using short options
  * @returns {Object} An Intl object representing options to be used
  */
 /**
  * @callback formatter
- * @param {Timestamp} timestamp The {@link Timestamp} being used
+ * @param {Timestamp} timestamp The Timestamp being used
  * @param {boolean} short If short format is being requested
- * @returns {string} The localized string of the formatted {@link Timestamp}
+ * @returns {string} The localized string of the formatted Timestamp
  */
-/**
- * Returns a locale formatter backed by `Intl.DateTimeFormat`.
- *
- * The helper is SSR-safe: if `Intl.DateTimeFormat` is unavailable in a target
- * runtime, it returns a formatter that produces an empty string instead of
- * throwing during module load.
- *
- * @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.
- */
-export function createNativeLocaleFormatter(locale, cb) {
+function createNativeLocaleFormatterByMode(locale, cb, toDate) {
     const emptyFormatter = () => "";
-    /* istanbul ignore next */
     if (typeof Intl === "undefined" || typeof Intl.DateTimeFormat === "undefined") {
         return emptyFormatter;
     }
     return (timestamp, short) => {
         try {
             const intlFormatter = new Intl.DateTimeFormat(locale || undefined, cb(timestamp, short));
-            return intlFormatter.format(makeDateTime(timestamp));
+            return intlFormatter.format(toDate(timestamp));
         }
-        catch (e) /* istanbul ignore next */ {
+        catch (e) {
             console.error(`Intl.DateTimeFormat: ${e.message} -> ${getDateTime(timestamp)}`);
             return "";
         }
     };
 }
 /**
- * Makes a JavaScript Date from the passed {@link Timestamp}
- * @param {Timestamp} timestamp The {@link Timestamp} to use
- * @param {boolean} utc True to get Date object using UTC
- * @returns {Date} A JavaScript Date
+ * Returns a host-local locale formatter backed by `Intl.DateTimeFormat`.
+ *
+ * The helper is SSR-safe: if `Intl.DateTimeFormat` is unavailable in a target
+ * runtime, it returns a formatter that produces an empty string instead of
+ * throwing during module load.
+ *
+ * Use `createNativeLocaleFormatterUTC()` when Timestamp values should be read
+ * as UTC fields before formatting.
+ *
+ * @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.
+ */
+export function createNativeLocaleFormatter(locale, cb) {
+    return createNativeLocaleFormatterByMode(locale, cb, makeDateTime);
+}
+/**
+ * Returns a UTC locale formatter backed by `Intl.DateTimeFormat`.
+ *
+ * This helper constructs the native `Date` with UTC fields before formatting.
+ * Pair it with `timeZone: "UTC"` when calendar labels must remain pinned to
+ * the Timestamp's UTC date instead of the viewer's local timezone.
+ *
+ * @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.
+ */
+export function createNativeLocaleFormatterUTC(locale, cb) {
+    return createNativeLocaleFormatterByMode(locale, cb, makeDateTimeUTC);
+}
+/**
+ * Converts a Timestamp date into a host-local JavaScript Date.
+ *
+ * @param {Timestamp} timestamp Timestamp object to convert.
+ * @returns {Date} Host-local JavaScript Date object.
  */
-export function makeDate(timestamp, utc = true) {
-    if (utc)
-        return new Date(Date.UTC(timestamp.year, timestamp.month - 1, timestamp.day, 0, 0));
+export function makeDate(timestamp) {
     return new Date(timestamp.year, timestamp.month - 1, timestamp.day, 0, 0);
 }
 /**
- * Makes a JavaScript Date from the passed {@link Timestamp} (with time)
- * @param {Timestamp} timestamp The {@link Timestamp} to use
- * @param {boolean} utc True to get Date object using UTC
- * @returns {Date} A JavaScript Date
+ * Converts a Timestamp date into a UTC JavaScript Date.
+ *
+ * @param {Timestamp} timestamp Timestamp object to convert.
+ * @returns {Date} JavaScript Date object built with `Date.UTC()`.
  */
-export function makeDateTime(timestamp, utc = true) {
-    if (utc)
-        return new Date(Date.UTC(timestamp.year, timestamp.month - 1, timestamp.day, timestamp.hour, timestamp.minute, timestamp.second ?? 0, timestamp.millisecond ?? 0));
+export function makeDateUTC(timestamp) {
+    return new Date(Date.UTC(timestamp.year, timestamp.month - 1, timestamp.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.
+ */
+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 a {@link Timestamp} to a local JavaScript `Date`.
+ * Converts a Timestamp date and time into a UTC JavaScript Date.
  *
- * This is equivalent to `makeDateTime(timestamp, false)`.
+ * @param {Timestamp} timestamp Timestamp object to convert.
+ * @returns {Date} JavaScript Date object built with `Date.UTC()`.
+ */
+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));
+}
+/**
+ * Converts a Timestamp to a local JavaScript Date.
  *
- * @param {Timestamp} timestamp The {@link Timestamp} to convert
- * @returns {Date} A local JavaScript Date
+ * This is equivalent to `makeDateTime(timestamp)`.
+ *
+ * @param {Timestamp} timestamp Timestamp object to convert.
+ * @returns {Date} Local JavaScript Date object.
  */
 export function getDateObject(timestamp) {
-    return makeDateTime(timestamp, false);
+    return makeDateTime(timestamp);
 }
 /**
  * Validates if the input is a finite number.
@@ -1047,10 +1172,11 @@ export function validateNumber(input) {
     return isFinite(Number(input));
 }
 /**
- * Given an array of {@link Timestamp}s, finds the max date (and possible time)
- * @param {Timestamp[]} timestamps This is an array of {@link Timestamp}s
- * @param {boolean=} useTime Default false; if true, uses time in the comparison as well
- * @returns The {@link Timestamp} with the highest date (and possibly time) value
+ * Finds the latest Timestamp in an array.
+ *
+ * @param {Timestamp[]} timestamps Timestamp objects to compare.
+ * @param {boolean=} useTime Include time-of-day in the comparison when true.
+ * @returns Latest Timestamp object.
  */
 export function maxTimestamp(timestamps, useTime = false) {
     const func = useTime === true ? getDayTimeIdentifier : getDayIdentifier;
@@ -1059,10 +1185,11 @@ export function maxTimestamp(timestamps, useTime = false) {
     });
 }
 /**
- * Given an array of {@link Timestamp}s, finds the min date (and possible time)
- * @param {Timestamp[]} timestamps This is an array of {@link Timestamp}s
- * @param {boolean=} useTime Default false; if true, uses time in the comparison as well
- * @returns The {@link Timestamp} with the lowest date (and possibly time) value
+ * Finds the earliest Timestamp in an array.
+ *
+ * @param {Timestamp[]} timestamps Timestamp objects to compare.
+ * @param {boolean=} useTime Include time-of-day in the comparison when true.
+ * @returns Earliest Timestamp object.
  */
 export function minTimestamp(timestamps, useTime = false) {
     const func = useTime === true ? getDayTimeIdentifier : getDayIdentifier;
@@ -1071,12 +1198,13 @@ export function minTimestamp(timestamps, useTime = false) {
     });
 }
 /**
- * Determines if the passed {@link Timestamp} is between (or equal) to two {@link Timestamp}s (range)
- * @param {Timestamp} timestamp The {@link Timestamp} for testing
- * @param {Timestamp} startTimestamp The starting {@link Timestamp}
- * @param {Timestamp} endTimestamp The ending {@link Timestamp}
- * @param {boolean=} useTime If true, use time from the {@link Timestamp}s
- * @returns {boolean} True if {@link Timestamp} is between (or equal) to two {@link Timestamp}s (range)
+ * Checks whether a Timestamp falls inside an inclusive range.
+ *
+ * @param {Timestamp} timestamp Timestamp object to test.
+ * @param {Timestamp} startTimestamp Inclusive start boundary.
+ * @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.
  */
 export function isBetweenDates(timestamp, startTimestamp, endTimestamp, useTime = false) {
     const cd = getDayIdentifier(timestamp) + (useTime === true ? getTimeIdentifier(timestamp) : 0);
@@ -1085,12 +1213,13 @@ export function isBetweenDates(timestamp, startTimestamp, endTimestamp, useTime
     return cd >= sd && cd <= ed;
 }
 /**
- * Determine if two ranges of {@link Timestamp}s overlap each other
- * @param {Timestamp} startTimestamp The starting {@link Timestamp} of first range
- * @param {Timestamp} endTimestamp The endinging {@link Timestamp} of first range
- * @param {Timestamp} firstTimestamp The starting {@link Timestamp} of second range
- * @param {Timestamp} lastTimestamp The ending {@link Timestamp} of second range
- * @returns {boolean} True if the two ranges overlap each other
+ * Checks whether two inclusive Timestamp ranges overlap.
+ *
+ * @param {Timestamp} startTimestamp Start of the first range.
+ * @param {Timestamp} endTimestamp End of the first range.
+ * @param {Timestamp} firstTimestamp Start of the second range.
+ * @param {Timestamp} lastTimestamp End of the second range.
+ * @returns {boolean} True when the ranges overlap.
  */
 export function isOverlappingDates(startTimestamp, endTimestamp, firstTimestamp, lastTimestamp) {
     const start = getDayIdentifier(startTimestamp);
@@ -1105,11 +1234,12 @@ export function isOverlappingDates(startTimestamp, endTimestamp, firstTimestamp,
 /**
  * Adds or subtracts date/time units from a timestamp.
  *
- * This function returns a new frozen {@link Timestamp}; it does not mutate the
- * timestamp passed in.
+ * This function returns a new frozen Timestamp; it does not mutate the
+ * timestamp passed in. Invalid target dates are normalized through JavaScript
+ * Date rules, so month overflow can roll into the following month.
  *
- * @param {Timestamp} timestamp The {@link Timestamp} object
- * @param {Object} options configuration data
+ * @param {Timestamp} timestamp Timestamp object to offset.
+ * @param {Object} options Date/time units to add or subtract.
  * @param {number=} options.year If positive, adds years. If negative, removes years.
  * @param {number=} options.month If positive, adds months. If negative, removes month.
  * @param {number=} options.day If positive, adds days. If negative, removes days.
@@ -1117,7 +1247,7 @@ export function isOverlappingDates(startTimestamp, endTimestamp, firstTimestamp,
  * @param {number=} options.minute If positive, adds minutes. If negative, removes minutes.
  * @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} A new normalized {@link Timestamp}
+ * @returns {Timestamp} New normalized Timestamp object.
  */
 export function addToDate(timestamp, options) {
     const ts = cloneTimestamp(timestamp);
@@ -1137,6 +1267,61 @@ export function addToDate(timestamp, options) {
         ts.millisecond = (ts.millisecond ?? 0) + options.millisecond;
     return updateFormatted(normalizeTimestamp(ts));
 }
+/**
+ * Adds or subtracts date/time units from a timestamp while clamping invalid
+ * target month days to the last valid day in the target month.
+ *
+ * This helper is useful for calendar and billing workflows where adding one
+ * month to January 31 should produce February 28/29 instead of rolling into
+ * March. Day and time offsets still use normal JavaScript Date normalization
+ * after the year/month clamp is applied.
+ *
+ * This function returns a new frozen Timestamp; it does not mutate the
+ * timestamp passed in.
+ *
+ * @param {Timestamp} timestamp Timestamp object to offset.
+ * @param {Object} options Date/time units to add or subtract.
+ * @param {number=} options.year If positive, adds years. If negative, removes years.
+ * @param {number=} options.month If positive, adds months. If negative, removes month.
+ * @param {number=} options.day If positive, adds days. If negative, removes days.
+ * @param {number=} options.hour If positive, adds hours. If negative, removes hours.
+ * @param {number=} options.minute If positive, adds minutes. If negative, removes minutes.
+ * @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.
+ */
+export function addToDateClamped(timestamp, options) {
+    const ts = cloneTimestamp(timestamp);
+    if (options.year || options.month) {
+        const target = normalizeYearMonth(ts.year + (options.year ?? 0), ts.month + (options.month ?? 0));
+        ts.year = target.year;
+        ts.month = target.month;
+        ts.day = Math.min(ts.day, daysInMonth(ts.year, ts.month));
+    }
+    if (options.day)
+        ts.day += options.day;
+    if (options.hour)
+        ts.hour += options.hour;
+    if (options.minute)
+        ts.minute += options.minute;
+    if (options.second)
+        ts.second = (ts.second ?? 0) + options.second;
+    if (options.millisecond)
+        ts.millisecond = (ts.millisecond ?? 0) + options.millisecond;
+    return updateFormatted(normalizeTimestamp(ts));
+}
+/**
+ * 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.
+ */
+function normalizeYearMonth(year, month) {
+    const date = new Date(year, month - 1, 1);
+    return {
+        year: date.getFullYear(),
+        month: date.getMonth() + 1,
+    };
+}
 /**
  * Normalizes a timestamp object by creating a JavaScript Date object and extracting standardized values.
  * This function ensures that the timestamp values are consistent and correctly represent a valid date and time.
@@ -1170,9 +1355,9 @@ function normalizeTimestamp(ts) {
     return freezeTimestamp(timestamp);
 }
 /**
- * Returns number of days between two {@link Timestamp}s
- * @param {Timestamp} ts1 The first {@link Timestamp}
- * @param {Timestamp} ts2 The second {@link Timestamp}
+ * Returns number of days between two Timestamps
+ * @param {Timestamp} ts1 The first Timestamp
+ * @param {Timestamp} ts2 The second Timestamp
  * @returns Number of days
  */
 export function daysBetween(ts1, ts2) {
@@ -1180,9 +1365,9 @@ export function daysBetween(ts1, ts2) {
     return Math.floor(diff / TIME_CONSTANTS.MILLISECONDS_IN.DAY);
 }
 /**
- * Returns number of weeks between two {@link Timestamp}s
- * @param {Timestamp} ts1 The first {@link Timestamp}
- * @param {Timestamp} ts2 The second {@link Timestamp}
+ * Returns number of weeks between two Timestamps
+ * @param {Timestamp} ts1 The first Timestamp
+ * @param {Timestamp} ts2 The second Timestamp
  */
 export function weeksBetween(ts1, ts2) {
     let t1 = copyTimestamp(ts1);
@@ -1231,7 +1416,6 @@ export function getWeekdayFormatter() {
         short: { timeZone: "UTC", weekday: "short" },
         narrow: { timeZone: "UTC", weekday: "narrow" },
     };
-    /* istanbul ignore next */
     if (typeof Intl === "undefined" || typeof Intl.DateTimeFormat === "undefined") {
         return emptyFormatter;
     }
@@ -1248,7 +1432,7 @@ export function getWeekdayFormatter() {
             const intlFormatter = new Intl.DateTimeFormat(locale || undefined, resolveIntlNameFormat(options, type));
             return intlFormatter.format(weekdayDateMap[weekday]);
         }
-        catch (e) /* istanbul ignore next */ {
+        catch (e) {
             if (e instanceof Error) {
                 console.error(`Intl.DateTimeFormat: ${e.message} -> day of week: ${weekday}`);
             }
@@ -1258,11 +1442,11 @@ export function getWeekdayFormatter() {
     return weekdayFormatter;
 }
 /**
- * Retrieves an array of localized weekday names.
+ * Retrieves localized weekday names.
  *
- * @param {string} type - The format type for the weekday names. Can be 'narrow', 'short', or 'long'.
- * @param {string} [locale] - The locale to use for formatting. If not provided, the default locale is used.
- * @returns {string[]} An array of localized weekday names in the specified format.
+ * @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.
  */
 export function getWeekdayNames(type, locale) {
     const shortWeekdays = Object.keys(weekdayDateMap);
@@ -1288,7 +1472,6 @@ export function getMonthFormatter() {
         short: { timeZone: "UTC", month: "short" },
         narrow: { timeZone: "UTC", month: "narrow" },
     };
-    /* istanbul ignore next */
     if (typeof Intl === "undefined" || typeof Intl.DateTimeFormat === "undefined") {
         return emptyFormatter;
     }
@@ -1308,7 +1491,7 @@ export function getMonthFormatter() {
             date.setMonth(month);
             return intlFormatter.format(date);
         }
-        catch (e) /* istanbul ignore next */ {
+        catch (e) {
             if (e instanceof Error) {
                 console.error(`Intl.DateTimeFormat: ${e.message} -> month: ${month}`);
             }
@@ -1318,93 +1501,14 @@ export function getMonthFormatter() {
     return monthFormatter;
 }
 /**
- * Retrieves an array of localized month names.
+ * Retrieves localized month names.
  *
- * @param {string} type - The format type for the month names. Can be 'narrow', 'short', or 'long'.
- * @param {string} [locale] - The locale to use for formatting. If not provided, the default locale is used.
- * @returns {string[]} An array of localized month names in the specified format.
+ * @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.
  */
 export function getMonthNames(type, locale) {
     const monthFormatter = getMonthFormatter();
     return [...Array(12).keys()].map((month) => monthFormatter(month, type, locale));
 }
-// the exports...
-export default {
-    PARSE_DATETIME,
-    PARSE_DATE,
-    PARSE_TIME,
-    DAYS_IN_MONTH,
-    DAYS_IN_MONTH_LEAP,
-    DAYS_IN_MONTH_MIN,
-    DAYS_IN_MONTH_MAX,
-    MONTH_MAX,
-    MONTH_MIN,
-    DAY_MIN,
-    TIME_CONSTANTS,
-    DAYS_IN_WEEK,
-    MINUTES_IN_HOUR,
-    HOURS_IN_DAY,
-    FIRST_HOUR,
-    MILLISECONDS_IN_MINUTE,
-    MILLISECONDS_IN_HOUR,
-    MILLISECONDS_IN_DAY,
-    MILLISECONDS_IN_WEEK,
-    Timestamp,
-    TimeObject,
-    today,
-    getStartOfWeek,
-    getEndOfWeek,
-    getStartOfMonth,
-    getEndOfMonth,
-    parseTime,
-    validateTimestamp,
-    parsed,
-    parseTimestamp,
-    parseDate,
-    getDayIdentifier,
-    getTimeIdentifier,
-    getDayTimeIdentifier,
-    diffTimestamp,
-    updateRelative,
-    updateMinutes,
-    updateWeekday,
-    updateDayOfYear,
-    updateWorkWeek,
-    updateDisabled,
-    updateFormatted,
-    getDayOfYear,
-    getWorkWeek,
-    getWeekday,
-    isLeapYear,
-    daysInMonth,
-    copyTimestamp,
-    padNumber,
-    getDate,
-    getTime,
-    getDateTime,
-    nextDay,
-    prevDay,
-    relativeDays,
-    findWeekday,
-    createDayList,
-    createIntervalList,
-    createNativeLocaleFormatter,
-    makeDate,
-    makeDateTime,
-    getDateObject,
-    validateNumber,
-    isBetweenDates,
-    isOverlappingDates,
-    daysBetween,
-    weeksBetween,
-    addToDate,
-    compareTimestamps,
-    compareDate,
-    compareTime,
-    compareDateTime,
-    getWeekdayFormatter,
-    getWeekdayNames,
-    getMonthFormatter,
-    getMonthNames,
-};
 //# sourceMappingURL=index.js.map