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

package/dist/index.d.ts

@@ -97,6 +97,10 @@ export declare const HOURS_IN_DAY: number;
  * Number of milliseconds in one minute.
  */
 export declare const MILLISECONDS_IN_MINUTE: number;
+/**
+ * Number of milliseconds in one second.
+ */
+export declare const MILLISECONDS_IN_SECOND: number;
 /**
  * Number of milliseconds in one hour.
  */
@@ -109,6 +113,18 @@ export declare const MILLISECONDS_IN_DAY: number;
  * Number of milliseconds in one week.
  */
 export declare const MILLISECONDS_IN_WEEK: number;
+/**
+ * Number of seconds in one minute.
+ */
+export declare const SECONDS_IN_MINUTE: number;
+/**
+ * Number of seconds in one hour.
+ */
+export declare const SECONDS_IN_HOUR: number;
+/**
+ * Number of seconds in one day.
+ */
+export declare const SECONDS_IN_DAY: number;
 /**
  * Inline style metadata that can be attached to disabled timestamp ranges.
  */
@@ -134,11 +150,11 @@ export interface DisabledDayConfig {
      */
     to?: string;
     /**
-     * Alias for {@link DisabledDayConfig.from}.
+     * Alias for DisabledDayConfig.from.
      */
     start?: string;
     /**
-     * Alias for {@link DisabledDayConfig.to}.
+     * Alias for DisabledDayConfig.to.
      */
     end?: string;
     /**
@@ -308,10 +324,78 @@ export interface TimeObject {
      */
     readonly millisecond?: number;
 }
+/**
+ * Immutable inclusive range between two Timestamp values.
+ *
+ * Range helpers normalize start/end order when created with createTimestampRange().
+ */
+export interface TimestampRange {
+    /**
+     * Inclusive range start.
+     */
+    readonly start: Timestamp;
+    /**
+     * Inclusive range end.
+     */
+    readonly end: Timestamp;
+}
+/**
+ * Immutable elapsed duration broken into convenient absolute components.
+ *
+ * `totalMilliseconds` is signed. The component fields are absolute values so
+ * callers can display or inspect them without repeatedly applying Math.abs().
+ */
+export interface TimestampDuration {
+    /**
+     * Signed elapsed milliseconds from the first timestamp to the second.
+     */
+    readonly totalMilliseconds: number;
+    /**
+     * Absolute elapsed milliseconds.
+     */
+    readonly absoluteMilliseconds: number;
+    /**
+     * Direction of the duration: `-1`, `0`, or `1`.
+     */
+    readonly sign: -1 | 0 | 1;
+    /**
+     * Full days in the absolute duration.
+     */
+    readonly days: number;
+    /**
+     * Remaining hours after full days are removed.
+     */
+    readonly hours: number;
+    /**
+     * Remaining minutes after full hours are removed.
+     */
+    readonly minutes: number;
+    /**
+     * Remaining seconds after full minutes are removed.
+     */
+    readonly seconds: number;
+    /**
+     * Remaining milliseconds after full seconds are removed.
+     */
+    readonly milliseconds: number;
+}
+/**
+ * Options for formatting a TimestampDuration.
+ */
+export interface FormatDurationOptions {
+    /**
+     * Include the millisecond component when true.
+     */
+    readonly milliseconds?: boolean;
+    /**
+     * Preserve a leading `-` for negative durations when true.
+     */
+    readonly signed?: boolean;
+}
 /**
  * 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 declare const Timestamp: Timestamp;
@@ -330,20 +414,33 @@ export declare function validateTimestamp(input: string): boolean;
  * 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 declare function parsed(input: string): Timestamp | null;
 /**
- * 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.
+ * 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 declare function parseDate(date: Date): Timestamp | null;
+/**
+ * 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 declare function parseDate(date: Date, utc?: boolean): Timestamp | null;
+export declare function parseDateUTC(date: Date): Timestamp | null;
 /**
  * Pads a number to a requested string length.
  *
@@ -367,22 +464,51 @@ export declare function isLeapYear(year: number): boolean;
  */
 export declare function daysInMonth(year: number, month: number): number;
 /**
- * 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 declare function nextDay(timestamp: Timestamp): 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 declare function prevDay(timestamp: Timestamp): 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 declare function today(): string;
+/**
+ * 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 declare function todayUTC(date?: Date): string;
+/**
+ * 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 declare function nowUTC(date?: Date): Timestamp;
 /**
  * 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'
@@ -390,33 +516,44 @@ export declare function today(): string;
  */
 export declare function isToday(date: string): boolean;
 /**
- * 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 declare function isTodayUTC(date: string, now?: Date): boolean;
+/**
+ * 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 declare function getStartOfWeek(timestamp: Timestamp, weekdays: number[], today: Timestamp): Timestamp;
 /**
- * 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 declare function getEndOfWeek(timestamp: Timestamp, weekdays: number[], today: Timestamp): Timestamp;
 /**
- * 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 declare function getStartOfMonth(timestamp: Timestamp): Timestamp;
 /**
- * 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 declare function getEndOfMonth(timestamp: Timestamp): Timestamp;
 /**
@@ -433,76 +570,88 @@ export declare function parseTime(input: number | string | {
     minute: number;
 }): number | 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 declare function compareTimestamps(ts1: Timestamp, ts2: Timestamp): boolean;
 /**
- * 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 declare function compareDate(ts1: Timestamp, ts2: Timestamp): boolean;
 /**
- * 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 declare function compareTime(ts1: Timestamp, ts2: Timestamp): boolean;
 /**
- * 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 declare function compareDateTime(ts1: Timestamp, ts2: Timestamp): boolean;
 /**
- * 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 declare function parseTimestamp(input: string, now?: Timestamp | null): Timestamp | null;
 /**
- * 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 declare function getDayIdentifier(timestamp: Timestamp): number;
 /**
- * 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 declare function getTimeIdentifier(timestamp: Timestamp): number;
 /**
- * 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 declare function getDayTimeIdentifier(timestamp: Timestamp): number;
 /**
- * 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
  */
 export declare function diffTimestamp(ts1: Timestamp, ts2: Timestamp, strict?: boolean): number;
 /**
- * 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 declare function updateRelative(timestamp: Timestamp, now: Timestamp, time?: boolean): Timestamp;
 /**
@@ -511,144 +660,184 @@ export declare function updateRelative(timestamp: Timestamp, now: Timestamp, tim
  * 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 declare function updateMinutes(timestamp: Timestamp, minutes: number, now?: Timestamp | null): Timestamp;
 /**
- * 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 declare function updateWeekday(timestamp: Timestamp): Timestamp;
 /**
- * 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 declare function updateDayOfYear(timestamp: Timestamp): Timestamp;
 /**
- * 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 declare function updateWorkWeek(timestamp: Timestamp): Timestamp;
 /**
- * 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 declare function updateDisabled(timestamp: Timestamp, disabledBefore?: string, disabledAfter?: string, disabledWeekdays?: number[], disabledDays?: DisabledDays): Timestamp;
 /**
- * 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 declare function updateFormatted(timestamp: Timestamp): Timestamp;
 /**
- * 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 declare function getDayOfYear(timestamp: Timestamp): number | void;
 /**
- * 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 declare function getWorkWeek(timestamp: Timestamp): number;
 /**
- * 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 declare function getWeekday(timestamp: Timestamp): number;
 /**
- * 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 declare function copyTimestamp(timestamp: Timestamp): 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')
+ * 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 declare function getStartOfDay(timestamp: Timestamp): Timestamp;
+/**
+ * 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 declare function getEndOfDay(timestamp: Timestamp): Timestamp;
+/**
+ * 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 declare function getStartOfYear(timestamp: Timestamp): Timestamp;
+/**
+ * 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 declare function getEndOfYear(timestamp: Timestamp): Timestamp;
+/**
+ * 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 declare function getDate(timestamp: Timestamp): string;
 /**
- * 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 declare function getTime(timestamp: Timestamp): string;
 /**
- * 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 declare function getDateTime(timestamp: Timestamp): string;
 /**
- * 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 declare function moveRelativeDays(timestamp: Timestamp, mover?: typeof nextDay, days?: number, allowedWeekdays?: number[]): Timestamp;
 /**
- * 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 declare function relativeDays(timestamp: Timestamp, mover?: typeof nextDay, days?: number, allowedWeekdays?: number[]): Timestamp;
 /**
- * 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 declare function findWeekday(timestamp: Timestamp, weekday: number, mover?: typeof nextDay, maxDays?: number): Timestamp;
 /**
- * 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 declare function createDayList(start: Timestamp, end: Timestamp, now: Timestamp, weekdays?: number[], disabledBefore?: string | undefined, disabledAfter?: string | undefined, disabledWeekdays?: number[], disabledDays?: DisabledDays, max?: number, min?: number): Timestamp[];
 /**
- * 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 declare function createIntervalList(timestamp: Timestamp, first: number, minutes: number, count: number, now: Timestamp): Timestamp[];
 /**
  * Callback that returns `Intl.DateTimeFormat` options for a timestamp.
  *
- * Used by {@link createNativeLocaleFormatter} to let callers switch between
+ * Used by createNativeLocaleFormatter to let callers switch between
  * long and short formatting styles per timestamp.
  */
 export type LocaleFormatter = (_timestamp: Timestamp, _short: boolean) => Intl.DateTimeFormatOptions;
@@ -661,50 +850,100 @@ export type WeekdayFormatter = (_weekday: keyof typeof weekdayDateMap, _type: st
  */
 export type MonthFormatter = (_month: number, _type?: string, _locale?: string) => string;
 /**
- * @callback getOptions
- * @param {Timestamp} timestamp A {@link 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 {boolean} short If short format is being requested
- * @returns {string} The localized string of the formatted {@link Timestamp}
- */
-/**
- * Returns a locale formatter backed by `Intl.DateTimeFormat`.
+ * 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 declare function createNativeLocaleFormatter(locale: string, cb: LocaleFormatter): (_timestamp: Timestamp, _short: boolean) => string;
 /**
- * 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 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 declare function createNativeLocaleFormatterUTC(locale: string, cb: LocaleFormatter): (_timestamp: Timestamp, _short: boolean) => string;
+/**
+ * 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 declare function makeDate(timestamp: Timestamp): 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 declare function makeDateUTC(timestamp: Timestamp): Date;
+/**
+ * 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 declare function makeDateTime(timestamp: Timestamp): 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 declare function makeDateTimeUTC(timestamp: Timestamp): Date;
+/**
+ * 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 declare function toUnixMilliseconds(timestamp: Timestamp): number;
+/**
+ * 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 declare function toUnixSeconds(timestamp: Timestamp): number;
+/**
+ * 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 declare function makeDate(timestamp: Timestamp, utc?: boolean): Date;
+export declare function fromUnixMilliseconds(milliseconds: number): Timestamp | null;
 /**
- * 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 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 declare function makeDateTime(timestamp: Timestamp, utc?: boolean): Date;
+export declare function fromUnixSeconds(seconds: number): Timestamp | null;
 /**
- * Converts a {@link Timestamp} to a local JavaScript `Date`.
+ * 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 declare function getDateObject(timestamp: Timestamp): Date;
 /**
@@ -716,39 +955,115 @@ export declare function getDateObject(timestamp: Timestamp): Date;
  */
 export declare function validateNumber(input: string | number): boolean;
 /**
- * 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 declare function maxTimestamp(timestamps: Timestamp[], useTime?: boolean): Timestamp;
 /**
- * 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 declare function minTimestamp(timestamps: Timestamp[], useTime?: boolean): Timestamp;
 /**
- * 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)
+ * 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 declare function createTimestampRange(start: Timestamp, end: Timestamp, useTime?: boolean): TimestampRange;
+/**
+ * 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 declare function isTimestampInRange(timestamp: Timestamp, range: TimestampRange, useTime?: boolean): boolean;
+/**
+ * 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 declare function isRangeOverlapping(first: TimestampRange, second: TimestampRange, useTime?: boolean): boolean;
+/**
+ * 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 declare function intersectRanges(first: TimestampRange, second: TimestampRange, useTime?: boolean): TimestampRange | null;
+/**
+ * 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 declare function mergeRanges(ranges: TimestampRange[], useTime?: boolean): TimestampRange[];
+/**
+ * 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 declare function subtractRanges(source: TimestampRange, blocked: TimestampRange[], useTime?: boolean): TimestampRange[];
+/**
+ * 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 declare function findRangeGaps(source: TimestampRange, occupied: TimestampRange[], useTime?: boolean): TimestampRange[];
+/**
+ * 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 declare function isBetweenDates(timestamp: Timestamp, startTimestamp: Timestamp, endTimestamp: Timestamp, useTime?: boolean): boolean;
 /**
- * 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 declare function isOverlappingDates(startTimestamp: Timestamp, endTimestamp: Timestamp, firstTimestamp: Timestamp, lastTimestamp: Timestamp): boolean;
 /**
- * Date and time offsets accepted by {@link addToDate} and {@link addToDateClamped}.
+ * Date and time offsets accepted by addToDate() and addToDateClamped().
  *
  * Positive values add time; negative values subtract time. The result is
  * normalized through JavaScript Date rules, so overflowing months, days,
@@ -787,11 +1102,12 @@ export interface AddToDateOptions {
 /**
  * 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.
@@ -799,7 +1115,7 @@ export interface AddToDateOptions {
  * @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 declare function addToDate(timestamp: Timestamp, options: AddToDateOptions): Timestamp;
 /**
@@ -811,11 +1127,11 @@ export declare function addToDate(timestamp: Timestamp, options: AddToDateOption
  * 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.
@@ -823,22 +1139,94 @@ export declare function addToDate(timestamp: Timestamp, options: AddToDateOption
  * @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 declare function addToDateClamped(timestamp: Timestamp, options: AddToDateOptions): 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 declare function daysBetween(ts1: Timestamp, ts2: Timestamp): number;
 /**
- * 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 declare function weeksBetween(ts1: Timestamp, ts2: Timestamp): number;
+/**
+ * Creates a TimestampDuration from signed milliseconds.
+ *
+ * @param {number} milliseconds Signed elapsed milliseconds.
+ * @returns {TimestampDuration} Frozen duration object.
+ */
+export declare function createDuration(milliseconds: number): TimestampDuration;
+/**
+ * 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 declare function durationBetween(start: Timestamp, end: Timestamp): TimestampDuration;
+/**
+ * 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 declare function addDuration(timestamp: Timestamp, duration: TimestampDuration | number): Timestamp;
+/**
+ * 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 declare function subtractDuration(timestamp: Timestamp, duration: TimestampDuration | number): Timestamp;
+/**
+ * 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 declare function formatDuration(duration: TimestampDuration | number, options?: FormatDurationOptions): string;
+/**
+ * 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 declare function floorToInterval(timestamp: Timestamp, minutes: number): Timestamp;
+/**
+ * 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 declare function ceilToInterval(timestamp: Timestamp, minutes: number): Timestamp;
+/**
+ * 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 declare function roundToInterval(timestamp: Timestamp, minutes: number): Timestamp;
 declare const weekdayDateMap: {
     Sun: Date;
     Mon: Date;
@@ -867,11 +1255,11 @@ declare const weekdayDateMap: {
  */
 export declare function getWeekdayFormatter(): 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 declare function getWeekdayNames(type: string, locale: string): string[];
 /**
@@ -888,118 +1276,12 @@ export declare function getWeekdayNames(type: string, locale: string): string[];
  */
 export declare function getMonthFormatter(): 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 declare function getMonthNames(type: string, locale: string): string[];
-declare const _default: {
-    PARSE_DATETIME: RegExp;
-    PARSE_DATE: RegExp;
-    PARSE_TIME: RegExp;
-    DAYS_IN_MONTH: number[];
-    DAYS_IN_MONTH_LEAP: number[];
-    DAYS_IN_MONTH_MIN: number;
-    DAYS_IN_MONTH_MAX: number;
-    MONTH_MAX: number;
-    MONTH_MIN: number;
-    DAY_MIN: number;
-    TIME_CONSTANTS: {
-        MILLISECONDS_IN: {
-            SECOND: number;
-            MINUTE: number;
-            HOUR: number;
-            DAY: number;
-            WEEK: number;
-        };
-        SECONDS_IN: {
-            MINUTE: number;
-            HOUR: number;
-            DAY: number;
-            WEEK: number;
-        };
-        MINUTES_IN: {
-            MINUTE: number;
-            HOUR: number;
-            DAY: number;
-            WEEK: number;
-        };
-        HOURS_IN: {
-            DAY: number;
-            WEEK: number;
-        };
-        DAYS_IN: {
-            WEEK: number;
-        };
-    };
-    DAYS_IN_WEEK: number;
-    MINUTES_IN_HOUR: number;
-    HOURS_IN_DAY: number;
-    FIRST_HOUR: number;
-    MILLISECONDS_IN_MINUTE: number;
-    MILLISECONDS_IN_HOUR: number;
-    MILLISECONDS_IN_DAY: number;
-    MILLISECONDS_IN_WEEK: number;
-    Timestamp: Timestamp;
-    TimeObject: TimeObject;
-    today: typeof today;
-    getStartOfWeek: typeof getStartOfWeek;
-    getEndOfWeek: typeof getEndOfWeek;
-    getStartOfMonth: typeof getStartOfMonth;
-    getEndOfMonth: typeof getEndOfMonth;
-    parseTime: typeof parseTime;
-    validateTimestamp: typeof validateTimestamp;
-    parsed: typeof parsed;
-    parseTimestamp: typeof parseTimestamp;
-    parseDate: typeof parseDate;
-    getDayIdentifier: typeof getDayIdentifier;
-    getTimeIdentifier: typeof getTimeIdentifier;
-    getDayTimeIdentifier: typeof getDayTimeIdentifier;
-    diffTimestamp: typeof diffTimestamp;
-    updateRelative: typeof updateRelative;
-    updateMinutes: typeof updateMinutes;
-    updateWeekday: typeof updateWeekday;
-    updateDayOfYear: typeof updateDayOfYear;
-    updateWorkWeek: typeof updateWorkWeek;
-    updateDisabled: typeof updateDisabled;
-    updateFormatted: typeof updateFormatted;
-    getDayOfYear: typeof getDayOfYear;
-    getWorkWeek: typeof getWorkWeek;
-    getWeekday: typeof getWeekday;
-    isLeapYear: typeof isLeapYear;
-    daysInMonth: typeof daysInMonth;
-    copyTimestamp: typeof copyTimestamp;
-    padNumber: typeof padNumber;
-    getDate: typeof getDate;
-    getTime: typeof getTime;
-    getDateTime: typeof getDateTime;
-    nextDay: typeof nextDay;
-    prevDay: typeof prevDay;
-    relativeDays: typeof relativeDays;
-    findWeekday: typeof findWeekday;
-    createDayList: typeof createDayList;
-    createIntervalList: typeof createIntervalList;
-    createNativeLocaleFormatter: typeof createNativeLocaleFormatter;
-    makeDate: typeof makeDate;
-    makeDateTime: typeof makeDateTime;
-    getDateObject: typeof getDateObject;
-    validateNumber: typeof validateNumber;
-    isBetweenDates: typeof isBetweenDates;
-    isOverlappingDates: typeof isOverlappingDates;
-    daysBetween: typeof daysBetween;
-    weeksBetween: typeof weeksBetween;
-    addToDate: typeof addToDate;
-    addToDateClamped: typeof addToDateClamped;
-    compareTimestamps: typeof compareTimestamps;
-    compareDate: typeof compareDate;
-    compareTime: typeof compareTime;
-    compareDateTime: typeof compareDateTime;
-    getWeekdayFormatter: typeof getWeekdayFormatter;
-    getWeekdayNames: typeof getWeekdayNames;
-    getMonthFormatter: typeof getMonthFormatter;
-    getMonthNames: typeof getMonthNames;
-};
-export default _default;
+export {};
 //# sourceMappingURL=index.d.ts.map