Date Math || Timestamp

Timestamp

v0.1.0-rc.0

Date Math

Date math helpers always return new Timestamp objects. The original object stays unchanged.

Move by days, months, and years

import { function addToDate(timestamp: Timestamp, options: AddToDateOptions): TimestampAdds or subtracts date/time units from a timestamp.

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.
@paramtimestamp Timestamp object to offset.@paramoptions Date/time units to add or subtract.@paramoptions.year If positive, adds years. If negative, removes years.@paramoptions.month If positive, adds months. If negative, removes month.@paramoptions.day If positive, adds days. If negative, removes days.@paramoptions.hour If positive, adds hours. If negative, removes hours.@paramoptions.minute If positive, adds minutes. If negative, removes minutes.@paramoptions.second If positive, adds seconds. If negative, removes seconds.@paramoptions.millisecond If positive, adds milliseconds. If negative, removes milliseconds.@returnsNew normalized Timestamp object.addToDate, function getDate(timestamp: Timestamp): stringFormats the date portion of a Timestamp object.
@paramtimestamp Timestamp object to format.@returnsDate string such as `YYYY-MM-DD`.getDate, function parseTimestamp(input: string, now?: Timestamp | null): Timestamp | nullConverts 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`.
@paraminput 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.@paramnow Optional Timestamp used to calculate relative flags.@returnsFormatted Timestamp object, or `null` when the input cannot be parsed.parseTimestamp } from '@timestamp-js/core'

const const current: Timestampcurrent = function parseTimestamp(input: string, now?: Timestamp | null): Timestamp | nullConverts 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`.
@paraminput 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.@paramnow Optional Timestamp used to calculate relative flags.@returnsFormatted Timestamp object, or `null` when the input cannot be parsed.parseTimestamp('2026-06-08')!

const const nextWeek: TimestampnextWeek = function addToDate(timestamp: Timestamp, options: AddToDateOptions): TimestampAdds or subtracts date/time units from a timestamp.

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.
@paramtimestamp Timestamp object to offset.@paramoptions Date/time units to add or subtract.@paramoptions.year If positive, adds years. If negative, removes years.@paramoptions.month If positive, adds months. If negative, removes month.@paramoptions.day If positive, adds days. If negative, removes days.@paramoptions.hour If positive, adds hours. If negative, removes hours.@paramoptions.minute If positive, adds minutes. If negative, removes minutes.@paramoptions.second If positive, adds seconds. If negative, removes seconds.@paramoptions.millisecond If positive, adds milliseconds. If negative, removes milliseconds.@returnsNew normalized Timestamp object.addToDate(const current: Timestampcurrent, { AddToDateOptions.day?: number | undefinedNumber of days to add or subtract.day: 7 })
const const nextMonth: TimestampnextMonth = function addToDate(timestamp: Timestamp, options: AddToDateOptions): TimestampAdds or subtracts date/time units from a timestamp.

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.
@paramtimestamp Timestamp object to offset.@paramoptions Date/time units to add or subtract.@paramoptions.year If positive, adds years. If negative, removes years.@paramoptions.month If positive, adds months. If negative, removes month.@paramoptions.day If positive, adds days. If negative, removes days.@paramoptions.hour If positive, adds hours. If negative, removes hours.@paramoptions.minute If positive, adds minutes. If negative, removes minutes.@paramoptions.second If positive, adds seconds. If negative, removes seconds.@paramoptions.millisecond If positive, adds milliseconds. If negative, removes milliseconds.@returnsNew normalized Timestamp object.addToDate(const current: Timestampcurrent, { AddToDateOptions.month?: number | undefinedNumber of months to add or subtract.month: 1 })
const const lastYear: TimestamplastYear = function addToDate(timestamp: Timestamp, options: AddToDateOptions): TimestampAdds or subtracts date/time units from a timestamp.

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.
@paramtimestamp Timestamp object to offset.@paramoptions Date/time units to add or subtract.@paramoptions.year If positive, adds years. If negative, removes years.@paramoptions.month If positive, adds months. If negative, removes month.@paramoptions.day If positive, adds days. If negative, removes days.@paramoptions.hour If positive, adds hours. If negative, removes hours.@paramoptions.minute If positive, adds minutes. If negative, removes minutes.@paramoptions.second If positive, adds seconds. If negative, removes seconds.@paramoptions.millisecond If positive, adds milliseconds. If negative, removes milliseconds.@returnsNew normalized Timestamp object.addToDate(const current: Timestampcurrent, { AddToDateOptions.year?: number | undefinedNumber of years to add or subtract.year: -1 })

function getDate(timestamp: Timestamp): stringFormats the date portion of a Timestamp object.
@paramtimestamp Timestamp object to format.@returnsDate string such as `YYYY-MM-DD`.getDate(const nextWeek: TimestampnextWeek) // "2026-06-15"
function getDate(timestamp: Timestamp): stringFormats the date portion of a Timestamp object.
@paramtimestamp Timestamp object to format.@returnsDate string such as `YYYY-MM-DD`.getDate(const nextMonth: TimestampnextMonth) // "2026-07-08"
function getDate(timestamp: Timestamp): stringFormats the date portion of a Timestamp object.
@paramtimestamp Timestamp object to format.@returnsDate string such as `YYYY-MM-DD`.getDate(const lastYear: TimestamplastYear) // "2025-06-08"
function getDate(timestamp: Timestamp): stringFormats the date portion of a Timestamp object.
@paramtimestamp Timestamp object to format.@returnsDate string such as `YYYY-MM-DD`.getDate(const current: Timestampcurrent) // "2026-06-08"

Use clamped math for billing-style dates

JavaScript date overflow is useful for some workflows, but billing cycles and due dates often need end-of-month clamping.

import { function addToDate(timestamp: Timestamp, options: AddToDateOptions): TimestampAdds or subtracts date/time units from a timestamp.

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.
@paramtimestamp Timestamp object to offset.@paramoptions Date/time units to add or subtract.@paramoptions.year If positive, adds years. If negative, removes years.@paramoptions.month If positive, adds months. If negative, removes month.@paramoptions.day If positive, adds days. If negative, removes days.@paramoptions.hour If positive, adds hours. If negative, removes hours.@paramoptions.minute If positive, adds minutes. If negative, removes minutes.@paramoptions.second If positive, adds seconds. If negative, removes seconds.@paramoptions.millisecond If positive, adds milliseconds. If negative, removes milliseconds.@returnsNew normalized Timestamp object.addToDate, function addToDateClamped(timestamp: Timestamp, options: AddToDateOptions): TimestampAdds or subtracts date/time units from a timestamp while clamping invalid
target month days to the last valid day in the target month.

This helper is useful for calendar and billing workflows where adding one
month to January 31 should produce February 28/29 instead of rolling into
March. Day and time offsets still use normal JavaScript Date normalization
after the year/month clamp is applied.

This function returns a new frozen Timestamp; it does not mutate the
timestamp passed in.
@paramtimestamp Timestamp object to offset.@paramoptions Date/time units to add or subtract.@paramoptions.year If positive, adds years. If negative, removes years.@paramoptions.month If positive, adds months. If negative, removes month.@paramoptions.day If positive, adds days. If negative, removes days.@paramoptions.hour If positive, adds hours. If negative, removes hours.@paramoptions.minute If positive, adds minutes. If negative, removes minutes.@paramoptions.second If positive, adds seconds. If negative, removes seconds.@paramoptions.millisecond If positive, adds milliseconds. If negative, removes milliseconds.@returnsNew normalized Timestamp object.addToDateClamped, function getDate(timestamp: Timestamp): stringFormats the date portion of a Timestamp object.
@paramtimestamp Timestamp object to format.@returnsDate string such as `YYYY-MM-DD`.getDate, function parseTimestamp(input: string, now?: Timestamp | null): Timestamp | nullConverts 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`.
@paraminput 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.@paramnow Optional Timestamp used to calculate relative flags.@returnsFormatted Timestamp object, or `null` when the input cannot be parsed.parseTimestamp } from '@timestamp-js/core'

const const monthEnd: TimestampmonthEnd = function parseTimestamp(input: string, now?: Timestamp | null): Timestamp | nullConverts 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`.
@paraminput 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.@paramnow Optional Timestamp used to calculate relative flags.@returnsFormatted Timestamp object, or `null` when the input cannot be parsed.parseTimestamp('2026-01-31')!

const const overflow: Timestampoverflow = function addToDate(timestamp: Timestamp, options: AddToDateOptions): TimestampAdds or subtracts date/time units from a timestamp.

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.
@paramtimestamp Timestamp object to offset.@paramoptions Date/time units to add or subtract.@paramoptions.year If positive, adds years. If negative, removes years.@paramoptions.month If positive, adds months. If negative, removes month.@paramoptions.day If positive, adds days. If negative, removes days.@paramoptions.hour If positive, adds hours. If negative, removes hours.@paramoptions.minute If positive, adds minutes. If negative, removes minutes.@paramoptions.second If positive, adds seconds. If negative, removes seconds.@paramoptions.millisecond If positive, adds milliseconds. If negative, removes milliseconds.@returnsNew normalized Timestamp object.addToDate(const monthEnd: TimestampmonthEnd, { AddToDateOptions.month?: number | undefinedNumber of months to add or subtract.month: 1 })
const const clamped: Timestampclamped = function addToDateClamped(timestamp: Timestamp, options: AddToDateOptions): TimestampAdds or subtracts date/time units from a timestamp while clamping invalid
target month days to the last valid day in the target month.

This helper is useful for calendar and billing workflows where adding one
month to January 31 should produce February 28/29 instead of rolling into
March. Day and time offsets still use normal JavaScript Date normalization
after the year/month clamp is applied.

This function returns a new frozen Timestamp; it does not mutate the
timestamp passed in.
@paramtimestamp Timestamp object to offset.@paramoptions Date/time units to add or subtract.@paramoptions.year If positive, adds years. If negative, removes years.@paramoptions.month If positive, adds months. If negative, removes month.@paramoptions.day If positive, adds days. If negative, removes days.@paramoptions.hour If positive, adds hours. If negative, removes hours.@paramoptions.minute If positive, adds minutes. If negative, removes minutes.@paramoptions.second If positive, adds seconds. If negative, removes seconds.@paramoptions.millisecond If positive, adds milliseconds. If negative, removes milliseconds.@returnsNew normalized Timestamp object.addToDateClamped(const monthEnd: TimestampmonthEnd, { AddToDateOptions.month?: number | undefinedNumber of months to add or subtract.month: 1 })

function getDate(timestamp: Timestamp): stringFormats the date portion of a Timestamp object.
@paramtimestamp Timestamp object to format.@returnsDate string such as `YYYY-MM-DD`.getDate(const overflow: Timestampoverflow) // "2026-03-03"
function getDate(timestamp: Timestamp): stringFormats the date portion of a Timestamp object.
@paramtimestamp Timestamp object to format.@returnsDate string such as `YYYY-MM-DD`.getDate(const clamped: Timestampclamped) // "2026-02-28"

Leap-year clamping

Clamped math keeps leap-day anniversaries on the last valid day when the target year is not a leap year.

import { function addToDateClamped(timestamp: Timestamp, options: AddToDateOptions): TimestampAdds or subtracts date/time units from a timestamp while clamping invalid
target month days to the last valid day in the target month.

This helper is useful for calendar and billing workflows where adding one
month to January 31 should produce February 28/29 instead of rolling into
March. Day and time offsets still use normal JavaScript Date normalization
after the year/month clamp is applied.

This function returns a new frozen Timestamp; it does not mutate the
timestamp passed in.
@paramtimestamp Timestamp object to offset.@paramoptions Date/time units to add or subtract.@paramoptions.year If positive, adds years. If negative, removes years.@paramoptions.month If positive, adds months. If negative, removes month.@paramoptions.day If positive, adds days. If negative, removes days.@paramoptions.hour If positive, adds hours. If negative, removes hours.@paramoptions.minute If positive, adds minutes. If negative, removes minutes.@paramoptions.second If positive, adds seconds. If negative, removes seconds.@paramoptions.millisecond If positive, adds milliseconds. If negative, removes milliseconds.@returnsNew normalized Timestamp object.addToDateClamped, function getDate(timestamp: Timestamp): stringFormats the date portion of a Timestamp object.
@paramtimestamp Timestamp object to format.@returnsDate string such as `YYYY-MM-DD`.getDate, function parseTimestamp(input: string, now?: Timestamp | null): Timestamp | nullConverts 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`.
@paraminput 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.@paramnow Optional Timestamp used to calculate relative flags.@returnsFormatted Timestamp object, or `null` when the input cannot be parsed.parseTimestamp } from '@timestamp-js/core'

const const leapDay: TimestampleapDay = function parseTimestamp(input: string, now?: Timestamp | null): Timestamp | nullConverts 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`.
@paraminput 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.@paramnow Optional Timestamp used to calculate relative flags.@returnsFormatted Timestamp object, or `null` when the input cannot be parsed.parseTimestamp('2020-02-29')!
const const nextYear: TimestampnextYear = function addToDateClamped(timestamp: Timestamp, options: AddToDateOptions): TimestampAdds or subtracts date/time units from a timestamp while clamping invalid
target month days to the last valid day in the target month.

This helper is useful for calendar and billing workflows where adding one
month to January 31 should produce February 28/29 instead of rolling into
March. Day and time offsets still use normal JavaScript Date normalization
after the year/month clamp is applied.

This function returns a new frozen Timestamp; it does not mutate the
timestamp passed in.
@paramtimestamp Timestamp object to offset.@paramoptions Date/time units to add or subtract.@paramoptions.year If positive, adds years. If negative, removes years.@paramoptions.month If positive, adds months. If negative, removes month.@paramoptions.day If positive, adds days. If negative, removes days.@paramoptions.hour If positive, adds hours. If negative, removes hours.@paramoptions.minute If positive, adds minutes. If negative, removes minutes.@paramoptions.second If positive, adds seconds. If negative, removes seconds.@paramoptions.millisecond If positive, adds milliseconds. If negative, removes milliseconds.@returnsNew normalized Timestamp object.addToDateClamped(const leapDay: TimestampleapDay, { AddToDateOptions.year?: number | undefinedNumber of years to add or subtract.year: 1 })

function getDate(timestamp: Timestamp): stringFormats the date portion of a Timestamp object.
@paramtimestamp Timestamp object to format.@returnsDate string such as `YYYY-MM-DD`.getDate(const nextYear: TimestampnextYear) // "2021-02-28"

Move one day at a time

Use nextDay() and prevDay() when readability matters more than a generic offset object.

import { function getDate(timestamp: Timestamp): stringFormats the date portion of a Timestamp object.
@paramtimestamp Timestamp object to format.@returnsDate string such as `YYYY-MM-DD`.getDate, function nextDay(timestamp: Timestamp): TimestampReturns a new Timestamp for the next calendar day.
@paramtimestamp Base Timestamp object.@returnsNew Timestamp representing the next day.nextDay, function parseTimestamp(input: string, now?: Timestamp | null): Timestamp | nullConverts 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`.
@paraminput 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.@paramnow Optional Timestamp used to calculate relative flags.@returnsFormatted Timestamp object, or `null` when the input cannot be parsed.parseTimestamp, function prevDay(timestamp: Timestamp): TimestampReturns a new Timestamp for the previous calendar day.
@paramtimestamp Base Timestamp object.@returnsNew Timestamp representing the previous day.prevDay } from '@timestamp-js/core'

const const current: Timestampcurrent = function parseTimestamp(input: string, now?: Timestamp | null): Timestamp | nullConverts 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`.
@paraminput 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.@paramnow Optional Timestamp used to calculate relative flags.@returnsFormatted Timestamp object, or `null` when the input cannot be parsed.parseTimestamp('2026-06-08')!

function getDate(timestamp: Timestamp): stringFormats the date portion of a Timestamp object.
@paramtimestamp Timestamp object to format.@returnsDate string such as `YYYY-MM-DD`.getDate(function prevDay(timestamp: Timestamp): TimestampReturns a new Timestamp for the previous calendar day.
@paramtimestamp Base Timestamp object.@returnsNew Timestamp representing the previous day.prevDay(const current: Timestampcurrent)) // "2026-06-07"
function getDate(timestamp: Timestamp): stringFormats the date portion of a Timestamp object.
@paramtimestamp Timestamp object to format.@returnsDate string such as `YYYY-MM-DD`.getDate(function nextDay(timestamp: Timestamp): TimestampReturns a new Timestamp for the next calendar day.
@paramtimestamp Base Timestamp object.@returnsNew Timestamp representing the next day.nextDay(const current: Timestampcurrent)) // "2026-06-09"

Set minutes from midnight

updateMinutes() is useful for time pickers and interval grids that store time as minutes after midnight.

import { function parseTimestamp(input: string, now?: Timestamp | null): Timestamp | nullConverts 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`.
@paraminput 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.@paramnow Optional Timestamp used to calculate relative flags.@returnsFormatted Timestamp object, or `null` when the input cannot be parsed.parseTimestamp, function updateMinutes(timestamp: Timestamp, minutes: number, now?: Timestamp | null): TimestampReturns a timestamp set to a number of minutes past midnight.

The returned timestamp has updated hour/minute fields and clears second and
millisecond precision because this helper is minute-oriented.
@paramtimestamp The Timestamp to transform@paramminutes The number of minutes to set from midnight@paramnow Optional Timestamp representing current date and time@returnsA new TimestampupdateMinutes } from '@timestamp-js/core'

const const day: Timestampday = function parseTimestamp(input: string, now?: Timestamp | null): Timestamp | nullConverts 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`.
@paraminput 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.@paramnow Optional Timestamp used to calculate relative flags.@returnsFormatted Timestamp object, or `null` when the input cannot be parsed.parseTimestamp('2036-06-08')!

const const meeting: Timestampmeeting = function updateMinutes(timestamp: Timestamp, minutes: number, now?: Timestamp | null): TimestampReturns a timestamp set to a number of minutes past midnight.

The returned timestamp has updated hour/minute fields and clears second and
millisecond precision because this helper is minute-oriented.
@paramtimestamp The Timestamp to transform@paramminutes The number of minutes to set from midnight@paramnow Optional Timestamp representing current date and time@returnsA new TimestampupdateMinutes(const day: Timestampday, 9 * 60 + 30)

const meeting: Timestampmeeting.Timestamp.time?: string | undefinedFormatted time string.

Minute precision is formatted as `HH:mm`; second precision as `HH:mm:ss`;
millisecond precision as `HH:mm:ss.SSS`.time // "09:30"
const meeting: Timestampmeeting.Timestamp.hour: numberHour in 24-hour format.hour // 9
const meeting: Timestampmeeting.Timestamp.minute: numberMinute of the hour.minute // 30

Measure elapsed duration

durationBetween() reads Timestamp fields as UTC so elapsed time stays deterministic across server and client runtimes.

import { function durationBetween(start: Timestamp, end: Timestamp): TimestampDurationMeasures the elapsed duration between two Timestamp values.

Timestamp fields are read as UTC so the result is deterministic across
server and client runtimes.
@paramstart Start timestamp.@paramend End timestamp.@returnsFrozen duration object.durationBetween, function parseTimestamp(input: string, now?: Timestamp | null): Timestamp | nullConverts 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`.
@paraminput 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.@paramnow Optional Timestamp used to calculate relative flags.@returnsFormatted Timestamp object, or `null` when the input cannot be parsed.parseTimestamp } from '@timestamp-js/core'

const const startsAt: TimestampstartsAt = function parseTimestamp(input: string, now?: Timestamp | null): Timestamp | nullConverts 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`.
@paraminput 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.@paramnow Optional Timestamp used to calculate relative flags.@returnsFormatted Timestamp object, or `null` when the input cannot be parsed.parseTimestamp('2036-06-08T09:00')!
const const endsAt: TimestampendsAt = function parseTimestamp(input: string, now?: Timestamp | null): Timestamp | nullConverts 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`.
@paraminput 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.@paramnow Optional Timestamp used to calculate relative flags.@returnsFormatted Timestamp object, or `null` when the input cannot be parsed.parseTimestamp('2036-06-08T10:30:15.250')!

const const duration: TimestampDurationduration = function durationBetween(start: Timestamp, end: Timestamp): TimestampDurationMeasures the elapsed duration between two Timestamp values.

Timestamp fields are read as UTC so the result is deterministic across
server and client runtimes.
@paramstart Start timestamp.@paramend End timestamp.@returnsFrozen duration object.durationBetween(const startsAt: TimestampstartsAt, const endsAt: TimestampendsAt)

const duration: TimestampDurationduration.TimestampDuration.totalMilliseconds: numberSigned elapsed milliseconds from the first timestamp to the second.totalMilliseconds // 5415250
const duration: TimestampDurationduration.TimestampDuration.hours: numberRemaining hours after full days are removed.hours // 1
const duration: TimestampDurationduration.TimestampDuration.minutes: numberRemaining minutes after full hours are removed.minutes // 30
const duration: TimestampDurationduration.TimestampDuration.seconds: numberRemaining seconds after full minutes are removed.seconds // 15
const duration: TimestampDurationduration.TimestampDuration.milliseconds: numberRemaining milliseconds after full seconds are removed.milliseconds // 250

Create and format durations

Use createDuration() when elapsed time starts as milliseconds. formatDuration() formats full elapsed hours, including hours from full days.

import {
  function createDuration(milliseconds: number): TimestampDurationCreates a TimestampDuration from signed milliseconds.
@parammilliseconds Signed elapsed milliseconds.@returnsFrozen duration object.createDuration,
  function formatDuration(duration: TimestampDuration | number, options?: FormatDurationOptions): stringFormats 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`.
@paramduration Duration object or signed milliseconds.@paramoptions Formatting options.@returnsFormatted duration.formatDuration,
  const MILLISECONDS_IN_HOUR: numberNumber of milliseconds in one hour.MILLISECONDS_IN_HOUR,
  const MILLISECONDS_IN_MINUTE: numberNumber of milliseconds in one minute.MILLISECONDS_IN_MINUTE,
} from '@timestamp-js/core'

const const duration: TimestampDurationduration = function createDuration(milliseconds: number): TimestampDurationCreates a TimestampDuration from signed milliseconds.
@parammilliseconds Signed elapsed milliseconds.@returnsFrozen duration object.createDuration(26 * const MILLISECONDS_IN_HOUR: numberNumber of milliseconds in one hour.MILLISECONDS_IN_HOUR + 15 * const MILLISECONDS_IN_MINUTE: numberNumber of milliseconds in one minute.MILLISECONDS_IN_MINUTE)

function formatDuration(duration: TimestampDuration | number, options?: FormatDurationOptions): stringFormats 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`.
@paramduration Duration object or signed milliseconds.@paramoptions Formatting options.@returnsFormatted duration.formatDuration(const duration: TimestampDurationduration) // "26:15:00"
function formatDuration(duration: TimestampDuration | number, options?: FormatDurationOptions): stringFormats 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`.
@paramduration Duration object or signed milliseconds.@paramoptions Formatting options.@returnsFormatted duration.formatDuration(-1500, { FormatDurationOptions.signed?: boolean | undefinedPreserve a leading `-` for negative durations when true.signed: true, FormatDurationOptions.milliseconds?: boolean | undefinedInclude the millisecond component when true.milliseconds: true }) // "-00:00:01.500"

Add elapsed durations

Use elapsed durations for stopwatch-style time. Use addToDate() for calendar-unit math such as “one month”.

import { function addDuration(timestamp: Timestamp, duration: TimestampDuration | number): TimestampAdds 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".
@paramtimestamp Timestamp object to offset.@paramduration Duration object or signed milliseconds.@returnsOffset Timestamp.addDuration, function createDuration(milliseconds: number): TimestampDurationCreates a TimestampDuration from signed milliseconds.
@parammilliseconds Signed elapsed milliseconds.@returnsFrozen duration object.createDuration, function parseTimestamp(input: string, now?: Timestamp | null): Timestamp | nullConverts 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`.
@paraminput 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.@paramnow Optional Timestamp used to calculate relative flags.@returnsFormatted Timestamp object, or `null` when the input cannot be parsed.parseTimestamp, function subtractDuration(timestamp: Timestamp, duration: TimestampDuration | number): TimestampSubtracts an elapsed duration from a Timestamp.
@paramtimestamp Timestamp object to offset.@paramduration Duration object or signed milliseconds.@returnsOffset Timestamp.subtractDuration } from '@timestamp-js/core'

const const startsAt: TimestampstartsAt = function parseTimestamp(input: string, now?: Timestamp | null): Timestamp | nullConverts 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`.
@paraminput 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.@paramnow Optional Timestamp used to calculate relative flags.@returnsFormatted Timestamp object, or `null` when the input cannot be parsed.parseTimestamp('2036-06-08T09:00')!
const const ninetyMinutes: TimestampDurationninetyMinutes = function createDuration(milliseconds: number): TimestampDurationCreates a TimestampDuration from signed milliseconds.
@parammilliseconds Signed elapsed milliseconds.@returnsFrozen duration object.createDuration(90 * 60 * 1000)

function addDuration(timestamp: Timestamp, duration: TimestampDuration | number): TimestampAdds 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".
@paramtimestamp Timestamp object to offset.@paramduration Duration object or signed milliseconds.@returnsOffset Timestamp.addDuration(const startsAt: TimestampstartsAt, const ninetyMinutes: TimestampDurationninetyMinutes).Timestamp.time?: string | undefinedFormatted time string.

Minute precision is formatted as `HH:mm`; second precision as `HH:mm:ss`;
millisecond precision as `HH:mm:ss.SSS`.time // "10:30"
function subtractDuration(timestamp: Timestamp, duration: TimestampDuration | number): TimestampSubtracts an elapsed duration from a Timestamp.
@paramtimestamp Timestamp object to offset.@paramduration Duration object or signed milliseconds.@returnsOffset Timestamp.subtractDuration(const startsAt: TimestampstartsAt, const ninetyMinutes: TimestampDurationninetyMinutes).Timestamp.time?: string | undefinedFormatted time string.

Minute precision is formatted as `HH:mm`; second precision as `HH:mm:ss`;
millisecond precision as `HH:mm:ss.SSS`.time // "07:30"

Round to slot intervals

Slot helpers are useful for schedule grids, booking windows, and time pickers.

import {
  function ceilToInterval(timestamp: Timestamp, minutes: number): TimestampCeils a Timestamp up to the nearest interval.
@paramtimestamp Timestamp object to round.@paramminutes Interval size in minutes.@returnsRounded Timestamp.ceilToInterval,
  function floorToInterval(timestamp: Timestamp, minutes: number): TimestampFloors a Timestamp down to the nearest interval.
@paramtimestamp Timestamp object to round.@paramminutes Interval size in minutes.@returnsRounded Timestamp.floorToInterval,
  function parseTimestamp(input: string, now?: Timestamp | null): Timestamp | nullConverts 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`.
@paraminput 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.@paramnow Optional Timestamp used to calculate relative flags.@returnsFormatted Timestamp object, or `null` when the input cannot be parsed.parseTimestamp,
  function roundToInterval(timestamp: Timestamp, minutes: number): TimestampRounds a Timestamp to the nearest interval.
@paramtimestamp Timestamp object to round.@paramminutes Interval size in minutes.@returnsRounded Timestamp.roundToInterval,
} from '@timestamp-js/core'

const const time: Timestamptime = function parseTimestamp(input: string, now?: Timestamp | null): Timestamp | nullConverts 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`.
@paraminput 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.@paramnow Optional Timestamp used to calculate relative flags.@returnsFormatted Timestamp object, or `null` when the input cannot be parsed.parseTimestamp('2036-06-08T09:37:30')!

function floorToInterval(timestamp: Timestamp, minutes: number): TimestampFloors a Timestamp down to the nearest interval.
@paramtimestamp Timestamp object to round.@paramminutes Interval size in minutes.@returnsRounded Timestamp.floorToInterval(const time: Timestamptime, 15).Timestamp.time?: string | undefinedFormatted time string.

Minute precision is formatted as `HH:mm`; second precision as `HH:mm:ss`;
millisecond precision as `HH:mm:ss.SSS`.time // "09:30"
function ceilToInterval(timestamp: Timestamp, minutes: number): TimestampCeils a Timestamp up to the nearest interval.
@paramtimestamp Timestamp object to round.@paramminutes Interval size in minutes.@returnsRounded Timestamp.ceilToInterval(const time: Timestamptime, 15).Timestamp.time?: string | undefinedFormatted time string.

Minute precision is formatted as `HH:mm`; second precision as `HH:mm:ss`;
millisecond precision as `HH:mm:ss.SSS`.time // "09:45"
function roundToInterval(timestamp: Timestamp, minutes: number): TimestampRounds a Timestamp to the nearest interval.
@paramtimestamp Timestamp object to round.@paramminutes Interval size in minutes.@returnsRounded Timestamp.roundToInterval(const time: Timestamptime, 15).Timestamp.time?: string | undefinedFormatted time string.

Minute precision is formatted as `HH:mm`; second precision as `HH:mm:ss`;
millisecond precision as `HH:mm:ss.SSS`.time // "09:45"

Move by allowed weekdays

Use relativeDays() or moveRelativeDays() when “next day” should skip weekends or other disallowed weekdays.

import {
  function getDate(timestamp: Timestamp): stringFormats the date portion of a Timestamp object.
@paramtimestamp Timestamp object to format.@returnsDate string such as `YYYY-MM-DD`.getDate,
  function moveRelativeDays(timestamp: Timestamp, mover?: typeof nextDay, days?: number, allowedWeekdays?: number[]): TimestampAlias for relativeDays.
@paramtimestamp The Timestamp to transform@parammover The mover function to use (ie: {nextDay} or {prevDay}).@paramdays The number of days to move.@paramallowedWeekdays An array of numbers representing the weekdays. ie: [0 = Sun, ..., 6 = Sat].@returnsA new TimestampmoveRelativeDays,
  function nextDay(timestamp: Timestamp): TimestampReturns a new Timestamp for the next calendar day.
@paramtimestamp Base Timestamp object.@returnsNew Timestamp representing the next day.nextDay,
  function parseTimestamp(input: string, now?: Timestamp | null): Timestamp | nullConverts 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`.
@paraminput 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.@paramnow Optional Timestamp used to calculate relative flags.@returnsFormatted Timestamp object, or `null` when the input cannot be parsed.parseTimestamp,
  function prevDay(timestamp: Timestamp): TimestampReturns a new Timestamp for the previous calendar day.
@paramtimestamp Base Timestamp object.@returnsNew Timestamp representing the previous day.prevDay,
  function relativeDays(timestamp: Timestamp, mover?: typeof nextDay, days?: number, allowedWeekdays?: number[]): TimestampMoves the Timestamp the number of relative days
@paramtimestamp The Timestamp to transform@parammover The mover function to use (ie: {nextDay} or {prevDay}).@paramdays The number of days to move.@paramallowedWeekdays An array of numbers representing the weekdays. ie: [0 = Sun, ..., 6 = Sat].@returnsA new TimestamprelativeDays,
} from '@timestamp-js/core'

const const friday: Timestampfriday = function parseTimestamp(input: string, now?: Timestamp | null): Timestamp | nullConverts 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`.
@paraminput 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.@paramnow Optional Timestamp used to calculate relative flags.@returnsFormatted Timestamp object, or `null` when the input cannot be parsed.parseTimestamp('2036-06-13')!
const const mondayToFriday: number[]mondayToFriday = [1, 2, 3, 4, 5]

function getDate(timestamp: Timestamp): stringFormats the date portion of a Timestamp object.
@paramtimestamp Timestamp object to format.@returnsDate string such as `YYYY-MM-DD`.getDate(function relativeDays(timestamp: Timestamp, mover?: typeof nextDay, days?: number, allowedWeekdays?: number[]): TimestampMoves the Timestamp the number of relative days
@paramtimestamp The Timestamp to transform@parammover The mover function to use (ie: {nextDay} or {prevDay}).@paramdays The number of days to move.@paramallowedWeekdays An array of numbers representing the weekdays. ie: [0 = Sun, ..., 6 = Sat].@returnsA new TimestamprelativeDays(const friday: Timestampfriday, function nextDay(timestamp: Timestamp): TimestampReturns a new Timestamp for the next calendar day.
@paramtimestamp Base Timestamp object.@returnsNew Timestamp representing the next day.nextDay, 1, const mondayToFriday: number[]mondayToFriday)) // "2036-06-16"
function getDate(timestamp: Timestamp): stringFormats the date portion of a Timestamp object.
@paramtimestamp Timestamp object to format.@returnsDate string such as `YYYY-MM-DD`.getDate(function moveRelativeDays(timestamp: Timestamp, mover?: typeof nextDay, days?: number, allowedWeekdays?: number[]): TimestampAlias for relativeDays.
@paramtimestamp The Timestamp to transform@parammover The mover function to use (ie: {nextDay} or {prevDay}).@paramdays The number of days to move.@paramallowedWeekdays An array of numbers representing the weekdays. ie: [0 = Sun, ..., 6 = Sat].@returnsA new TimestampmoveRelativeDays(const friday: Timestampfriday, function prevDay(timestamp: Timestamp): TimestampReturns a new Timestamp for the previous calendar day.
@paramtimestamp Base Timestamp object.@returnsNew Timestamp representing the previous day.prevDay, 1, const mondayToFriday: number[]mondayToFriday)) // "2036-06-12"

Find a specific weekday

findWeekday() moves forward or backward until the requested weekday is found.

import { function findWeekday(timestamp: Timestamp, weekday: number, mover?: typeof nextDay, maxDays?: number): TimestampFinds the specified weekday (forward or back) based on the Timestamp
@paramtimestamp The Timestamp to transform@paramweekday The weekday number (Sun = 0, ..., Sat = 6)@parammover The function to use ({prevDay} or {nextDay}).@parammaxDays The number of days to look forward or back.@returnsA new TimestampfindWeekday, function getDate(timestamp: Timestamp): stringFormats the date portion of a Timestamp object.
@paramtimestamp Timestamp object to format.@returnsDate string such as `YYYY-MM-DD`.getDate, function nextDay(timestamp: Timestamp): TimestampReturns a new Timestamp for the next calendar day.
@paramtimestamp Base Timestamp object.@returnsNew Timestamp representing the next day.nextDay, function parseTimestamp(input: string, now?: Timestamp | null): Timestamp | nullConverts 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`.
@paraminput 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.@paramnow Optional Timestamp used to calculate relative flags.@returnsFormatted Timestamp object, or `null` when the input cannot be parsed.parseTimestamp, function prevDay(timestamp: Timestamp): TimestampReturns a new Timestamp for the previous calendar day.
@paramtimestamp Base Timestamp object.@returnsNew Timestamp representing the previous day.prevDay } from '@timestamp-js/core'

const const current: Timestampcurrent = function parseTimestamp(input: string, now?: Timestamp | null): Timestamp | nullConverts 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`.
@paraminput 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.@paramnow Optional Timestamp used to calculate relative flags.@returnsFormatted Timestamp object, or `null` when the input cannot be parsed.parseTimestamp('2036-06-08')!

function getDate(timestamp: Timestamp): stringFormats the date portion of a Timestamp object.
@paramtimestamp Timestamp object to format.@returnsDate string such as `YYYY-MM-DD`.getDate(function findWeekday(timestamp: Timestamp, weekday: number, mover?: typeof nextDay, maxDays?: number): TimestampFinds the specified weekday (forward or back) based on the Timestamp
@paramtimestamp The Timestamp to transform@paramweekday The weekday number (Sun = 0, ..., Sat = 6)@parammover The function to use ({prevDay} or {nextDay}).@parammaxDays The number of days to look forward or back.@returnsA new TimestampfindWeekday(const current: Timestampcurrent, 5, function nextDay(timestamp: Timestamp): TimestampReturns a new Timestamp for the next calendar day.
@paramtimestamp Base Timestamp object.@returnsNew Timestamp representing the next day.nextDay)) // "2036-06-13"
function getDate(timestamp: Timestamp): stringFormats the date portion of a Timestamp object.
@paramtimestamp Timestamp object to format.@returnsDate string such as `YYYY-MM-DD`.getDate(function findWeekday(timestamp: Timestamp, weekday: number, mover?: typeof nextDay, maxDays?: number): TimestampFinds the specified weekday (forward or back) based on the Timestamp
@paramtimestamp The Timestamp to transform@paramweekday The weekday number (Sun = 0, ..., Sat = 6)@parammover The function to use ({prevDay} or {nextDay}).@parammaxDays The number of days to look forward or back.@returnsA new TimestampfindWeekday(const current: Timestampcurrent, 1, function prevDay(timestamp: Timestamp): TimestampReturns a new Timestamp for the previous calendar day.
@paramtimestamp Base Timestamp object.@returnsNew Timestamp representing the previous day.prevDay)) // "2036-06-02"

Type reusable offset objects

AddToDateOptions is useful when offsets are passed through app-level helpers.

import { function addToDate(timestamp: Timestamp, options: AddToDateOptions): TimestampAdds or subtracts date/time units from a timestamp.

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.
@paramtimestamp Timestamp object to offset.@paramoptions Date/time units to add or subtract.@paramoptions.year If positive, adds years. If negative, removes years.@paramoptions.month If positive, adds months. If negative, removes month.@paramoptions.day If positive, adds days. If negative, removes days.@paramoptions.hour If positive, adds hours. If negative, removes hours.@paramoptions.minute If positive, adds minutes. If negative, removes minutes.@paramoptions.second If positive, adds seconds. If negative, removes seconds.@paramoptions.millisecond If positive, adds milliseconds. If negative, removes milliseconds.@returnsNew normalized Timestamp object.addToDate, function getDate(timestamp: Timestamp): stringFormats the date portion of a Timestamp object.
@paramtimestamp Timestamp object to format.@returnsDate string such as `YYYY-MM-DD`.getDate, function parseTimestamp(input: string, now?: Timestamp | null): Timestamp | nullConverts 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`.
@paraminput 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.@paramnow Optional Timestamp used to calculate relative flags.@returnsFormatted Timestamp object, or `null` when the input cannot be parsed.parseTimestamp } from '@timestamp-js/core'
import type { AddToDateOptions } from '@timestamp-js/core'

const const renewalOffset: AddToDateOptionsrenewalOffset: AddToDateOptions = { AddToDateOptions.year?: number | undefinedNumber of years to add or subtract.year: 1, AddToDateOptions.day?: number | undefinedNumber of days to add or subtract.day: -1 }
const const startsAt: TimestampstartsAt = function parseTimestamp(input: string, now?: Timestamp | null): Timestamp | nullConverts 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`.
@paraminput 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.@paramnow Optional Timestamp used to calculate relative flags.@returnsFormatted Timestamp object, or `null` when the input cannot be parsed.parseTimestamp('2036-06-08')!

function getDate(timestamp: Timestamp): stringFormats the date portion of a Timestamp object.
@paramtimestamp Timestamp object to format.@returnsDate string such as `YYYY-MM-DD`.getDate(function addToDate(timestamp: Timestamp, options: AddToDateOptions): TimestampAdds or subtracts date/time units from a timestamp.

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.
@paramtimestamp Timestamp object to offset.@paramoptions Date/time units to add or subtract.@paramoptions.year If positive, adds years. If negative, removes years.@paramoptions.month If positive, adds months. If negative, removes month.@paramoptions.day If positive, adds days. If negative, removes days.@paramoptions.hour If positive, adds hours. If negative, removes hours.@paramoptions.minute If positive, adds minutes. If negative, removes minutes.@paramoptions.second If positive, adds seconds. If negative, removes seconds.@paramoptions.millisecond If positive, adds milliseconds. If negative, removes milliseconds.@returnsNew normalized Timestamp object.addToDate(const startsAt: TimestampstartsAt, const renewalOffset: AddToDateOptionsrenewalOffset)) // "2037-06-07"

Ready for more?

Developing

Validation + Boundaries

Developing

Intervals + Lists

Caught a mistake?Edit this page in browser

1. Introduction

2. Move by days, months, and years

3. Use clamped math for billing-style dates

4. Leap-year clamping

5. Move one day at a time

6. Set minutes from midnight

7. Measure elapsed duration

8. Create and format durations

9. Add elapsed durations

10. Round to slot intervals

11. Move by allowed weekdays

12. Find a specific weekday

13. Type reusable offset objects