@timestamp-js/core 0.1.0-alpha.2 → 0.1.0-beta.0

package/dist/index.js

@@ -97,6 +97,10 @@ export const HOURS_IN_DAY = TIME_CONSTANTS.HOURS_IN.DAY;
  * Number of milliseconds in one minute.
  */
 export const MILLISECONDS_IN_MINUTE = TIME_CONSTANTS.MILLISECONDS_IN.MINUTE;
+/**
+ * Number of milliseconds in one second.
+ */
+export const MILLISECONDS_IN_SECOND = TIME_CONSTANTS.MILLISECONDS_IN.SECOND;
 /**
  * Number of milliseconds in one hour.
  */
@@ -109,10 +113,22 @@ export const MILLISECONDS_IN_DAY = TIME_CONSTANTS.MILLISECONDS_IN.DAY;
  * Number of milliseconds in one week.
  */
 export const MILLISECONDS_IN_WEEK = TIME_CONSTANTS.MILLISECONDS_IN.WEEK;
+/**
+ * Number of seconds in one minute.
+ */
+export const SECONDS_IN_MINUTE = TIME_CONSTANTS.SECONDS_IN.MINUTE;
+/**
+ * Number of seconds in one hour.
+ */
+export const SECONDS_IN_HOUR = TIME_CONSTANTS.SECONDS_IN.HOUR;
+/**
+ * Number of seconds in one day.
+ */
+export const SECONDS_IN_DAY = TIME_CONSTANTS.SECONDS_IN.DAY;
 /**
  * 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 +179,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,15 +227,11 @@ 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;
+    if (Number.isNaN(date.getTime()))
+        return null;
     const UTC = utc ? "UTC" : "";
     const second = date[`get${UTC}Seconds`]();
     const millisecond = date[`get${UTC}Milliseconds`]();
@@ -255,6 +267,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 +326,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 +341,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 +356,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 +407,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 +445,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 +472,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 +483,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 +531,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 +550,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 +600,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 +611,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 +627,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 +653,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 +686,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 +705,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 +715,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 +725,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 +780,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 +828,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 +843,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 +858,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 +885,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 +911,80 @@ 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);
 }
+function setTimeParts(timestamp, hour, minute, second, millisecond) {
+    const ts = cloneTimestamp(timestamp);
+    ts.hasTime = true;
+    ts.hour = hour;
+    ts.minute = minute;
+    if (second === undefined) {
+        delete ts.second;
+    }
+    else {
+        ts.second = second;
+    }
+    if (millisecond === undefined) {
+        delete ts.millisecond;
+    }
+    else {
+        ts.millisecond = millisecond;
+    }
+    return updateFormatted(ts);
+}
+/**
+ * Returns a Timestamp at the start of the same calendar day.
+ *
+ * @param {Timestamp} timestamp Timestamp object to transform.
+ * @returns {Timestamp} New Timestamp at `00:00`.
+ */
+export function getStartOfDay(timestamp) {
+    return setTimeParts(timestamp, 0, 0);
+}
+/**
+ * Returns a Timestamp at the end of the same calendar day.
+ *
+ * @param {Timestamp} timestamp Timestamp object to transform.
+ * @returns {Timestamp} New Timestamp at `23:59:59.999`.
+ */
+export function getEndOfDay(timestamp) {
+    return setTimeParts(timestamp, 23, 59, 59, 999);
+}
+/**
+ * Returns a Timestamp at the start of the same Gregorian year.
+ *
+ * @param {Timestamp} timestamp Timestamp object to transform.
+ * @returns {Timestamp} New Timestamp for January 1 at `00:00`.
+ */
+export function getStartOfYear(timestamp) {
+    const ts = cloneTimestamp(timestamp);
+    ts.month = MONTH_MIN;
+    ts.day = DAY_MIN;
+    return getStartOfDay(updateFormatted(ts));
+}
+/**
+ * Returns a Timestamp at the end of the same Gregorian year.
+ *
+ * @param {Timestamp} timestamp Timestamp object to transform.
+ * @returns {Timestamp} New Timestamp for December 31 at `23:59:59.999`.
+ */
+export function getEndOfYear(timestamp) {
+    const ts = cloneTimestamp(timestamp);
+    ts.month = MONTH_MAX;
+    ts.day = daysInMonth(ts.year, MONTH_MAX);
+    return getEndOfDay(updateFormatted(ts));
+}
 /**
- * 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 +993,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 +1015,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 +1056,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 +1070,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 +1117,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 +1136,150 @@ 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 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, 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 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.
+ *
+ * @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 into Unix milliseconds by reading its fields as UTC.
+ *
+ * This is deterministic across server and client runtimes. It does not read or
+ * convert the optional `timezone` suffix stored on the Timestamp.
+ *
+ * @param {Timestamp} timestamp Timestamp object to convert.
+ * @returns {number} Unix milliseconds.
+ */
+export function toUnixMilliseconds(timestamp) {
+    return makeDateTimeUTC(timestamp).getTime();
+}
+/**
+ * Converts a Timestamp into Unix seconds by reading its fields as UTC.
+ *
+ * Milliseconds are floored because Unix seconds are integer-oriented.
+ *
+ * @param {Timestamp} timestamp Timestamp object to convert.
+ * @returns {number} Unix seconds.
+ */
+export function toUnixSeconds(timestamp) {
+    return Math.floor(toUnixMilliseconds(timestamp) / MILLISECONDS_IN_SECOND);
+}
+/**
+ * Converts Unix milliseconds into an immutable Timestamp using UTC fields.
+ *
+ * @param {number} milliseconds Unix milliseconds.
+ * @returns {Timestamp | null} Timestamp built from UTC fields, or `null` for invalid input.
+ */
+export function fromUnixMilliseconds(milliseconds) {
+    return parseDateUTC(new Date(milliseconds));
+}
+/**
+ * Converts Unix seconds into an immutable Timestamp using UTC fields.
+ *
+ * @param {number} seconds Unix seconds.
+ * @returns {Timestamp | null} Timestamp built from UTC fields, or `null` for invalid input.
+ */
+export function fromUnixSeconds(seconds) {
+    return fromUnixMilliseconds(seconds * MILLISECONDS_IN_SECOND);
+}
+/**
+ * Converts a Timestamp to a local JavaScript Date.
  *
- * This is equivalent to `makeDateTime(timestamp, false)`.
+ * This is equivalent to `makeDateTime(timestamp)`.
  *
- * @param {Timestamp} timestamp The {@link Timestamp} to convert
- * @returns {Date} A local JavaScript Date
+ * @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 +1292,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 +1305,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;
@@ -1070,13 +1317,168 @@ export function minTimestamp(timestamps, useTime = false) {
         return Math.min(func(prev), func(cur)) === func(prev) ? prev : cur;
     });
 }
+function getTimestampSortValue(timestamp, useTime) {
+    if (useTime === true) {
+        return toUnixMilliseconds(timestamp);
+    }
+    return Date.UTC(timestamp.year, timestamp.month - 1, timestamp.day);
+}
+function compareTimestampOrder(first, second, useTime) {
+    return getTimestampSortValue(first, useTime) - getTimestampSortValue(second, useTime);
+}
+function createFrozenRange(start, end) {
+    return Object.freeze({ start: copyTimestamp(start), end: copyTimestamp(end) });
+}
+function isRangeTouchingOrOverlapping(first, second, useTime) {
+    const step = useTime ? 1 : MILLISECONDS_IN_DAY;
+    return (getTimestampSortValue(second.start, useTime) <= getTimestampSortValue(first.end, useTime) + step);
+}
+function moveBoundary(timestamp, amount, useTime) {
+    if (useTime === true) {
+        return fromUnixMilliseconds(toUnixMilliseconds(timestamp) + amount);
+    }
+    return addToDate(timestamp, { day: amount });
+}
+/**
+ * Creates an inclusive Timestamp range and normalizes start/end order.
+ *
+ * @param {Timestamp} start First boundary.
+ * @param {Timestamp} end Second boundary.
+ * @param {boolean=} useTime Include time-of-day when ordering boundaries.
+ * @returns {TimestampRange} Frozen inclusive Timestamp range.
+ */
+export function createTimestampRange(start, end, useTime = false) {
+    if (compareTimestampOrder(start, end, useTime) <= 0) {
+        return createFrozenRange(start, end);
+    }
+    return createFrozenRange(end, start);
+}
+/**
+ * Checks whether a Timestamp falls inside an inclusive TimestampRange.
+ *
+ * @param {Timestamp} timestamp Timestamp object to test.
+ * @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.
+ */
+export function isTimestampInRange(timestamp, range, useTime = false) {
+    return isBetweenDates(timestamp, range.start, range.end, useTime);
+}
+/**
+ * Checks whether two inclusive TimestampRange values overlap.
+ *
+ * @param {TimestampRange} first First range.
+ * @param {TimestampRange} second Second range.
+ * @param {boolean=} useTime Include time-of-day in the comparison.
+ * @returns {boolean} True when the ranges overlap.
+ */
+export function isRangeOverlapping(first, second, useTime = false) {
+    const firstRange = createTimestampRange(first.start, first.end, useTime);
+    const secondRange = createTimestampRange(second.start, second.end, useTime);
+    return (getTimestampSortValue(firstRange.start, useTime) <=
+        getTimestampSortValue(secondRange.end, useTime) &&
+        getTimestampSortValue(secondRange.start, useTime) <=
+            getTimestampSortValue(firstRange.end, useTime));
+}
 /**
- * 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)
+ * Returns the inclusive intersection of two TimestampRange values.
+ *
+ * @param {TimestampRange} first First range.
+ * @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.
+ */
+export function intersectRanges(first, second, useTime = false) {
+    if (isRangeOverlapping(first, second, useTime) === false) {
+        return null;
+    }
+    const start = compareTimestampOrder(first.start, second.start, useTime) >= 0 ? first.start : second.start;
+    const end = compareTimestampOrder(first.end, second.end, useTime) <= 0 ? first.end : second.end;
+    return createTimestampRange(start, end, useTime);
+}
+/**
+ * Merges overlapping or touching TimestampRange values.
+ *
+ * Date-only ranges touch when the next range starts on the next calendar day.
+ * Time-aware ranges touch when the next range starts one millisecond after the
+ * previous range ends.
+ *
+ * @param {TimestampRange[]} ranges Ranges to merge.
+ * @param {boolean=} useTime Include time-of-day in the comparison.
+ * @returns {TimestampRange[]} Merged ranges sorted by start boundary.
+ */
+export function mergeRanges(ranges, useTime = false) {
+    const sorted = ranges
+        .map((range) => createTimestampRange(range.start, range.end, useTime))
+        .sort((a, b) => compareTimestampOrder(a.start, b.start, useTime));
+    const merged = [];
+    for (const range of sorted) {
+        const last = merged[merged.length - 1];
+        if (last === undefined || isRangeTouchingOrOverlapping(last, range, useTime) === false) {
+            merged.push(range);
+            continue;
+        }
+        const end = compareTimestampOrder(last.end, range.end, useTime) >= 0 ? last.end : range.end;
+        merged[merged.length - 1] = createFrozenRange(last.start, end);
+    }
+    return merged;
+}
+/**
+ * Subtracts blocked ranges from a source range.
+ *
+ * The result is useful for availability windows because it returns the pieces
+ * of the source range that remain after each blocked range is removed.
+ *
+ * @param {TimestampRange} source Source range.
+ * @param {TimestampRange[]} blocked Ranges to remove from the source.
+ * @param {boolean=} useTime Include time-of-day in the comparison.
+ * @returns {TimestampRange[]} Remaining ranges.
+ */
+export function subtractRanges(source, blocked, useTime = false) {
+    const normalizedSource = createTimestampRange(source.start, source.end, useTime);
+    const blockers = mergeRanges(blocked, useTime);
+    let available = [normalizedSource];
+    for (const blocker of blockers) {
+        const nextAvailable = [];
+        for (const range of available) {
+            const overlap = intersectRanges(range, blocker, useTime);
+            if (overlap === null) {
+                nextAvailable.push(range);
+                continue;
+            }
+            if (compareTimestampOrder(range.start, overlap.start, useTime) < 0) {
+                nextAvailable.push(createTimestampRange(range.start, moveBoundary(overlap.start, -1, useTime), useTime));
+            }
+            if (compareTimestampOrder(overlap.end, range.end, useTime) < 0) {
+                nextAvailable.push(createTimestampRange(moveBoundary(overlap.end, 1, useTime), range.end, useTime));
+            }
+        }
+        available = nextAvailable;
+    }
+    return available;
+}
+/**
+ * Finds open gaps inside a source range after occupied ranges are removed.
+ *
+ * This is an alias for subtractRanges() with naming that reads naturally in
+ * booking, resource, and availability workflows.
+ *
+ * @param {TimestampRange} source Source range.
+ * @param {TimestampRange[]} occupied Ranges that are not available.
+ * @param {boolean=} useTime Include time-of-day in the comparison.
+ * @returns {TimestampRange[]} Gap ranges.
+ */
+export function findRangeGaps(source, occupied, useTime = false) {
+    return subtractRanges(source, occupied, useTime);
+}
+/**
+ * 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 +1487,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 +1508,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 +1521,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);
@@ -1146,11 +1550,11 @@ export function addToDate(timestamp, options) {
  * March. Day and time offsets still use normal JavaScript Date normalization
  * after the year/month clamp is applied.
  *
- * This function returns a new frozen {@link Timestamp}; it does not mutate the
+ * This function returns a new frozen Timestamp; it does not mutate the
  * timestamp passed in.
  *
- * @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.
@@ -1158,7 +1562,7 @@ export function addToDate(timestamp, options) {
  * @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 addToDateClamped(timestamp, options) {
     const ts = cloneTimestamp(timestamp);
@@ -1225,9 +1629,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) {
@@ -1235,9 +1639,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);
@@ -1246,6 +1650,130 @@ export function weeksBetween(ts1, ts2) {
     t2 = findWeekday(t2, 6);
     return Math.ceil(daysBetween(t1, t2) / TIME_CONSTANTS.DAYS_IN.WEEK);
 }
+/**
+ * Creates a TimestampDuration from signed milliseconds.
+ *
+ * @param {number} milliseconds Signed elapsed milliseconds.
+ * @returns {TimestampDuration} Frozen duration object.
+ */
+export function createDuration(milliseconds) {
+    const sign = milliseconds === 0 ? 0 : milliseconds < 0 ? -1 : 1;
+    let remaining = Math.abs(milliseconds);
+    const days = Math.floor(remaining / MILLISECONDS_IN_DAY);
+    remaining -= days * MILLISECONDS_IN_DAY;
+    const hours = Math.floor(remaining / MILLISECONDS_IN_HOUR);
+    remaining -= hours * MILLISECONDS_IN_HOUR;
+    const minutes = Math.floor(remaining / MILLISECONDS_IN_MINUTE);
+    remaining -= minutes * MILLISECONDS_IN_MINUTE;
+    const seconds = Math.floor(remaining / MILLISECONDS_IN_SECOND);
+    remaining -= seconds * MILLISECONDS_IN_SECOND;
+    return Object.freeze({
+        totalMilliseconds: milliseconds,
+        absoluteMilliseconds: Math.abs(milliseconds),
+        sign,
+        days,
+        hours,
+        minutes,
+        seconds,
+        milliseconds: remaining,
+    });
+}
+/**
+ * Measures the elapsed duration between two Timestamp values.
+ *
+ * Timestamp fields are read as UTC so the result is deterministic across
+ * server and client runtimes.
+ *
+ * @param {Timestamp} start Start timestamp.
+ * @param {Timestamp} end End timestamp.
+ * @returns {TimestampDuration} Frozen duration object.
+ */
+export function durationBetween(start, end) {
+    return createDuration(toUnixMilliseconds(end) - toUnixMilliseconds(start));
+}
+/**
+ * Adds an elapsed duration to a Timestamp.
+ *
+ * This helper treats the Timestamp fields as UTC and returns a Timestamp built
+ * from UTC fields. Use addToDate() for calendar-unit arithmetic such as
+ * "one month from now".
+ *
+ * @param {Timestamp} timestamp Timestamp object to offset.
+ * @param {TimestampDuration | number} duration Duration object or signed milliseconds.
+ * @returns {Timestamp} Offset Timestamp.
+ */
+export function addDuration(timestamp, duration) {
+    const milliseconds = typeof duration === "number" ? duration : duration.totalMilliseconds;
+    return fromUnixMilliseconds(toUnixMilliseconds(timestamp) + milliseconds);
+}
+/**
+ * Subtracts an elapsed duration from a Timestamp.
+ *
+ * @param {Timestamp} timestamp Timestamp object to offset.
+ * @param {TimestampDuration | number} duration Duration object or signed milliseconds.
+ * @returns {Timestamp} Offset Timestamp.
+ */
+export function subtractDuration(timestamp, duration) {
+    const milliseconds = typeof duration === "number" ? duration : duration.totalMilliseconds;
+    return addDuration(timestamp, -milliseconds);
+}
+/**
+ * Formats a duration as `HH:mm:ss` or `HH:mm:ss.SSS`.
+ *
+ * Hours include full days, so a two-day duration formats as `48:00:00`.
+ *
+ * @param {TimestampDuration | number} duration Duration object or signed milliseconds.
+ * @param {FormatDurationOptions=} options Formatting options.
+ * @returns {string} Formatted duration.
+ */
+export function formatDuration(duration, options = {}) {
+    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 ? "-" : "";
+    let formatted = `${sign}${padNumber(hours, 2)}:${padNumber(value.minutes, 2)}:${padNumber(value.seconds, 2)}`;
+    if (options.milliseconds === true) {
+        formatted += `.${padNumber(value.milliseconds, 3)}`;
+    }
+    return formatted;
+}
+function roundTimestampToInterval(timestamp, minutes, rounder) {
+    if (minutes <= 0 || Number.isFinite(minutes) === false) {
+        return copyTimestamp(timestamp);
+    }
+    const interval = minutes * MILLISECONDS_IN_MINUTE;
+    const value = toUnixMilliseconds(timestamp);
+    return fromUnixMilliseconds(rounder(value / interval) * interval);
+}
+/**
+ * Floors a Timestamp down to the nearest interval.
+ *
+ * @param {Timestamp} timestamp Timestamp object to round.
+ * @param {number} minutes Interval size in minutes.
+ * @returns {Timestamp} Rounded Timestamp.
+ */
+export function floorToInterval(timestamp, minutes) {
+    return roundTimestampToInterval(timestamp, minutes, Math.floor);
+}
+/**
+ * Ceils a Timestamp up to the nearest interval.
+ *
+ * @param {Timestamp} timestamp Timestamp object to round.
+ * @param {number} minutes Interval size in minutes.
+ * @returns {Timestamp} Rounded Timestamp.
+ */
+export function ceilToInterval(timestamp, minutes) {
+    return roundTimestampToInterval(timestamp, minutes, Math.ceil);
+}
+/**
+ * Rounds a Timestamp to the nearest interval.
+ *
+ * @param {Timestamp} timestamp Timestamp object to round.
+ * @param {number} minutes Interval size in minutes.
+ * @returns {Timestamp} Rounded Timestamp.
+ */
+export function roundToInterval(timestamp, minutes) {
+    return roundTimestampToInterval(timestamp, minutes, Math.round);
+}
 // Known dates
 const weekdayDateMap = {
     Sun: new Date("2020-01-05T00:00:00.000Z"),
@@ -1286,7 +1814,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;
     }
@@ -1303,7 +1830,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}`);
             }
@@ -1313,11 +1840,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);
@@ -1343,7 +1870,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;
     }
@@ -1363,7 +1889,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}`);
             }
@@ -1373,94 +1899,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,
-    addToDateClamped,
-    compareTimestamps,
-    compareDate,
-    compareTime,
-    compareDateTime,
-    getWeekdayFormatter,
-    getWeekdayNames,
-    getMonthFormatter,
-    getMonthNames,
-};
 //# sourceMappingURL=index.js.map