Timestamp
v0.1.0-rc.0
Developing
Parsing + Formatting
Validation + Boundaries
Date Math
Intervals + Lists
Comparisons + Ranges
SSR + Runtime
Timezone Model
Comparisons And Ranges

Comparison helpers avoid repeatedly converting Timestamp objects back into native Date values.

Compare date and time separately

import { function compareDate(ts1: Timestamp, ts2: Timestamp): boolean
Compares the calendar date portion of two Timestamp objects.
@paramts1 First Timestamp object.@paramts2 Second Timestamp object.@returnsTrue when both dates are the same.
compareDate, function compareDateTime(ts1: Timestamp, ts2: Timestamp): boolean
Compares the formatted date and time portions of two Timestamp objects.
@paramts1 First Timestamp object.@paramts2 Second Timestamp object.@returnsTrue when both date-time values are the same.
compareDateTime, function compareTime(ts1: Timestamp, ts2: Timestamp): boolean
Compares the formatted time portion of two Timestamp objects.
@paramts1 First Timestamp object.@paramts2 Second Timestamp object.@returnsTrue when both times are the same.
compareTime, function parseTimestamp(input: string, now?: Timestamp | null): Timestamp | null
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`.
@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 first: Timestampfirst = function parseTimestamp(input: string, now?: Timestamp | null): Timestamp | null
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`.
@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 09:30')!
const const second: Timestampsecond = function parseTimestamp(input: string, now?: Timestamp | null): Timestamp | null
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`.
@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 10:00')!

function compareDate(ts1: Timestamp, ts2: Timestamp): boolean
Compares the calendar date portion of two Timestamp objects.
@paramts1 First Timestamp object.@paramts2 Second Timestamp object.@returnsTrue when both dates are the same.
compareDate(const first: Timestampfirst, const second: Timestampsecond) // true
function compareTime(ts1: Timestamp, ts2: Timestamp): boolean
Compares the formatted time portion of two Timestamp objects.
@paramts1 First Timestamp object.@paramts2 Second Timestamp object.@returnsTrue when both times are the same.
compareTime(const first: Timestampfirst, const second: Timestampsecond) // false
function compareDateTime(ts1: Timestamp, ts2: Timestamp): boolean
Compares the formatted date and time portions of two Timestamp objects.
@paramts1 First Timestamp object.@paramts2 Second Timestamp object.@returnsTrue when both date-time values are the same.
compareDateTime(const first: Timestampfirst, const second: Timestampsecond) // false

Comparison helpers return booleans. Use identifiers or min/max helpers when you need ordering.

import {
  function getDayIdentifier(timestamp: Timestamp): number
Converts a Timestamp date into a sortable numeric identifier.
@paramtimestamp Timestamp object to read.@returnsNumeric date identifier.
getDayIdentifier,
  function getDayTimeIdentifier(timestamp: Timestamp): number
Converts a Timestamp date and time into a sortable numeric identifier.
@paramtimestamp Timestamp object to read.@returnsNumeric date-time identifier.
getDayTimeIdentifier,
  function getTimeIdentifier(timestamp: Timestamp): number
Converts a Timestamp time into a sortable numeric identifier.
@paramtimestamp Timestamp object to read.@returnsNumeric time identifier.
getTimeIdentifier,
  function parseTimestamp(input: string, now?: Timestamp | null): Timestamp | null
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`.
@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 first: Timestampfirst = function parseTimestamp(input: string, now?: Timestamp | null): Timestamp | null
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`.
@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 09:30')!
const const second: Timestampsecond = function parseTimestamp(input: string, now?: Timestamp | null): Timestamp | null
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`.
@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 10:00')!

function getDayIdentifier(timestamp: Timestamp): number
Converts a Timestamp date into a sortable numeric identifier.
@paramtimestamp Timestamp object to read.@returnsNumeric date identifier.
getDayIdentifier(const first: Timestampfirst) // 202606080000
function getTimeIdentifier(timestamp: Timestamp): number
Converts a Timestamp time into a sortable numeric identifier.
@paramtimestamp Timestamp object to read.@returnsNumeric time identifier.
getTimeIdentifier(const first: Timestampfirst) // 930
function getDayTimeIdentifier(timestamp: Timestamp): number
Converts a Timestamp date and time into a sortable numeric identifier.
@paramtimestamp Timestamp object to read.@returnsNumeric date-time identifier.
getDayTimeIdentifier(const first: Timestampfirst) < function getDayTimeIdentifier(timestamp: Timestamp): number
Converts a Timestamp date and time into a sortable numeric identifier.
@paramtimestamp Timestamp object to read.@returnsNumeric date-time identifier.
getDayTimeIdentifier(const second: Timestampsecond) // true

Compare exact timestamps

Use compareTimestamps() when timezone suffixes and sub-minute precision matter too.

import { function compareDateTime(ts1: Timestamp, ts2: Timestamp): boolean
Compares the formatted date and time portions of two Timestamp objects.
@paramts1 First Timestamp object.@paramts2 Second Timestamp object.@returnsTrue when both date-time values are the same.
compareDateTime, function compareTimestamps(ts1: Timestamp, ts2: Timestamp): boolean
Compares two Timestamp objects for exact date, time, and timezone equality.
@paramts1 First Timestamp object.@paramts2 Second Timestamp object.@returnsTrue when both timestamps match exactly.
compareTimestamps, function parseTimestamp(input: string, now?: Timestamp | null): Timestamp | null
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`.
@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 utc: Timestamputc = function parseTimestamp(input: string, now?: Timestamp | null): Timestamp | null
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`.
@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:30:15.250Z')!
const const offset: Timestampoffset = function parseTimestamp(input: string, now?: Timestamp | null): Timestamp | null
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`.
@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:30:15.250-07:00')!

function compareDateTime(ts1: Timestamp, ts2: Timestamp): boolean
Compares the formatted date and time portions of two Timestamp objects.
@paramts1 First Timestamp object.@paramts2 Second Timestamp object.@returnsTrue when both date-time values are the same.
compareDateTime(const utc: Timestamputc, const offset: Timestampoffset) // true
function compareTimestamps(ts1: Timestamp, ts2: Timestamp): boolean
Compares two Timestamp objects for exact date, time, and timezone equality.
@paramts1 First Timestamp object.@paramts2 Second Timestamp object.@returnsTrue when both timestamps match exactly.
compareTimestamps(const utc: Timestamputc, const offset: Timestampoffset) // false

Check inclusive date ranges

import { function isBetweenDates(timestamp: Timestamp, startTimestamp: Timestamp, endTimestamp: Timestamp, useTime?: boolean): boolean
Checks whether a Timestamp falls inside an inclusive range.
@paramtimestamp Timestamp object to test.@paramstartTimestamp Inclusive start boundary.@paramendTimestamp Inclusive end boundary.@paramuseTime Include time-of-day in the comparison when true.@returnsTrue when the timestamp is inside the range.
isBetweenDates, function parseTimestamp(input: string, now?: Timestamp | null): Timestamp | null
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`.
@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 start: Timestampstart = function parseTimestamp(input: string, now?: Timestamp | null): Timestamp | null
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`.
@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-01')!
const const end: Timestampend = function parseTimestamp(input: string, now?: Timestamp | null): Timestamp | null
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`.
@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-30')!
const const target: Timestamptarget = function parseTimestamp(input: string, now?: Timestamp | null): Timestamp | null
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`.
@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 isBetweenDates(timestamp: Timestamp, startTimestamp: Timestamp, endTimestamp: Timestamp, useTime?: boolean): boolean
Checks whether a Timestamp falls inside an inclusive range.
@paramtimestamp Timestamp object to test.@paramstartTimestamp Inclusive start boundary.@paramendTimestamp Inclusive end boundary.@paramuseTime Include time-of-day in the comparison when true.@returnsTrue when the timestamp is inside the range.
isBetweenDates(const target: Timestamptarget, const start: Timestampstart, const end: Timestampend) // true

Create reusable range objects

Use TimestampRange when the same inclusive boundaries need to flow through several helpers.

import {
  function createTimestampRange(start: Timestamp, end: Timestamp, useTime?: boolean): TimestampRange
Creates an inclusive Timestamp range and normalizes start/end order.
@paramstart First boundary.@paramend Second boundary.@paramuseTime Include time-of-day when ordering boundaries.@returnsFrozen inclusive Timestamp range.
createTimestampRange,
  function getDate(timestamp: Timestamp): string
Formats the date portion of a Timestamp object.
@paramtimestamp Timestamp object to format.@returnsDate string such as `YYYY-MM-DD`.
getDate,
  function isTimestampInRange(timestamp: Timestamp, range: TimestampRange, useTime?: boolean): boolean
Checks whether a Timestamp falls inside an inclusive TimestampRange.
@paramtimestamp Timestamp object to test.@paramrange Inclusive range to test against.@paramuseTime Include time-of-day in the comparison.@returnsTrue when the timestamp is inside the range.
isTimestampInRange,
  function parseTimestamp(input: string, now?: Timestamp | null): Timestamp | null
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`.
@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 june: TimestampRangejune = function createTimestampRange(start: Timestamp, end: Timestamp, useTime?: boolean): TimestampRange
Creates an inclusive Timestamp range and normalizes start/end order.
@paramstart First boundary.@paramend Second boundary.@paramuseTime Include time-of-day when ordering boundaries.@returnsFrozen inclusive Timestamp range.
createTimestampRange(function parseTimestamp(input: string, now?: Timestamp | null): Timestamp | null
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`.
@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-01')!, function parseTimestamp(input: string, now?: Timestamp | null): Timestamp | null
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`.
@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-30')!)
const const target: Timestamptarget = function parseTimestamp(input: string, now?: Timestamp | null): Timestamp | null
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`.
@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 isTimestampInRange(timestamp: Timestamp, range: TimestampRange, useTime?: boolean): boolean
Checks whether a Timestamp falls inside an inclusive TimestampRange.
@paramtimestamp Timestamp object to test.@paramrange Inclusive range to test against.@paramuseTime Include time-of-day in the comparison.@returnsTrue when the timestamp is inside the range.
isTimestampInRange(const target: Timestamptarget, const june: TimestampRangejune) // true
function getDate(timestamp: Timestamp): string
Formats the date portion of a Timestamp object.
@paramtimestamp Timestamp object to format.@returnsDate string such as `YYYY-MM-DD`.
getDate(const june: TimestampRangejune.TimestampRange.start: Timestamp
Inclusive range start.
start) // "2036-06-01"
function getDate(timestamp: Timestamp): string
Formats the date portion of a Timestamp object.
@paramtimestamp Timestamp object to format.@returnsDate string such as `YYYY-MM-DD`.
getDate(const june: TimestampRangejune.TimestampRange.end: Timestamp
Inclusive range end.
end) // "2036-06-30"

Check overlap between ranges

import { function isOverlappingDates(startTimestamp: Timestamp, endTimestamp: Timestamp, firstTimestamp: Timestamp, lastTimestamp: Timestamp): boolean
Checks whether two inclusive Timestamp ranges overlap.
@paramstartTimestamp Start of the first range.@paramendTimestamp End of the first range.@paramfirstTimestamp Start of the second range.@paramlastTimestamp End of the second range.@returnsTrue when the ranges overlap.
isOverlappingDates, function parseTimestamp(input: string, now?: Timestamp | null): Timestamp | null
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`.
@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 vacationStart: TimestampvacationStart = function parseTimestamp(input: string, now?: Timestamp | null): Timestamp | null
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`.
@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-10')!
const const vacationEnd: TimestampvacationEnd = function parseTimestamp(input: string, now?: Timestamp | null): Timestamp | null
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`.
@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-14')!
const const blackoutStart: TimestampblackoutStart = function parseTimestamp(input: string, now?: Timestamp | null): Timestamp | null
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`.
@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-12')!
const const blackoutEnd: TimestampblackoutEnd = function parseTimestamp(input: string, now?: Timestamp | null): Timestamp | null
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`.
@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-18')!

function isOverlappingDates(startTimestamp: Timestamp, endTimestamp: Timestamp, firstTimestamp: Timestamp, lastTimestamp: Timestamp): boolean
Checks whether two inclusive Timestamp ranges overlap.
@paramstartTimestamp Start of the first range.@paramendTimestamp End of the first range.@paramfirstTimestamp Start of the second range.@paramlastTimestamp End of the second range.@returnsTrue when the ranges overlap.
isOverlappingDates(const vacationStart: TimestampvacationStart, const vacationEnd: TimestampvacationEnd, const blackoutStart: TimestampblackoutStart, const blackoutEnd: TimestampblackoutEnd) // true

Check overlap between reusable range objects

Use isRangeOverlapping() when your app already passes around TimestampRange values.

import { function createTimestampRange(start: Timestamp, end: Timestamp, useTime?: boolean): TimestampRange
Creates an inclusive Timestamp range and normalizes start/end order.
@paramstart First boundary.@paramend Second boundary.@paramuseTime Include time-of-day when ordering boundaries.@returnsFrozen inclusive Timestamp range.
createTimestampRange, function isRangeOverlapping(first: TimestampRange, second: TimestampRange, useTime?: boolean): boolean
Checks whether two inclusive TimestampRange values overlap.
@paramfirst First range.@paramsecond Second range.@paramuseTime Include time-of-day in the comparison.@returnsTrue when the ranges overlap.
isRangeOverlapping, function parseTimestamp(input: string, now?: Timestamp | null): Timestamp | null
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`.
@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 planningWindow: TimestampRangeplanningWindow = function createTimestampRange(start: Timestamp, end: Timestamp, useTime?: boolean): TimestampRange
Creates an inclusive Timestamp range and normalizes start/end order.
@paramstart First boundary.@paramend Second boundary.@paramuseTime Include time-of-day when ordering boundaries.@returnsFrozen inclusive Timestamp range.
createTimestampRange(
  function parseTimestamp(input: string, now?: Timestamp | null): Timestamp | null
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`.
@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-01')!,
  function parseTimestamp(input: string, now?: Timestamp | null): Timestamp | null
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`.
@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-30')!,
)
const const blackout: TimestampRangeblackout = function createTimestampRange(start: Timestamp, end: Timestamp, useTime?: boolean): TimestampRange
Creates an inclusive Timestamp range and normalizes start/end order.
@paramstart First boundary.@paramend Second boundary.@paramuseTime Include time-of-day when ordering boundaries.@returnsFrozen inclusive Timestamp range.
createTimestampRange(function parseTimestamp(input: string, now?: Timestamp | null): Timestamp | null
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`.
@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-12')!, function parseTimestamp(input: string, now?: Timestamp | null): Timestamp | null
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`.
@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-18')!)

function isRangeOverlapping(first: TimestampRange, second: TimestampRange, useTime?: boolean): boolean
Checks whether two inclusive TimestampRange values overlap.
@paramfirst First range.@paramsecond Second range.@paramuseTime Include time-of-day in the comparison.@returnsTrue when the ranges overlap.
isRangeOverlapping(const planningWindow: TimestampRangeplanningWindow, const blackout: TimestampRangeblackout) // true

Intersect two ranges

intersectRanges() returns the shared section of two ranges, or null when they do not overlap.

import { function createTimestampRange(start: Timestamp, end: Timestamp, useTime?: boolean): TimestampRange
Creates an inclusive Timestamp range and normalizes start/end order.
@paramstart First boundary.@paramend Second boundary.@paramuseTime Include time-of-day when ordering boundaries.@returnsFrozen inclusive Timestamp range.
createTimestampRange, function getDate(timestamp: Timestamp): string
Formats the date portion of a Timestamp object.
@paramtimestamp Timestamp object to format.@returnsDate string such as `YYYY-MM-DD`.
getDate, function intersectRanges(first: TimestampRange, second: TimestampRange, useTime?: boolean): TimestampRange | null
Returns the inclusive intersection of two TimestampRange values.
@paramfirst First range.@paramsecond Second range.@paramuseTime Include time-of-day in the comparison.@returnsIntersected range, or `null` when the ranges do not overlap.
intersectRanges, function parseTimestamp(input: string, now?: Timestamp | null): Timestamp | null
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`.
@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 sprint: TimestampRangesprint = function createTimestampRange(start: Timestamp, end: Timestamp, useTime?: boolean): TimestampRange
Creates an inclusive Timestamp range and normalizes start/end order.
@paramstart First boundary.@paramend Second boundary.@paramuseTime Include time-of-day when ordering boundaries.@returnsFrozen inclusive Timestamp range.
createTimestampRange(function parseTimestamp(input: string, now?: Timestamp | null): Timestamp | null
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`.
@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-01')!, function parseTimestamp(input: string, now?: Timestamp | null): Timestamp | null
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`.
@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-20')!)
const const blackout: TimestampRangeblackout = function createTimestampRange(start: Timestamp, end: Timestamp, useTime?: boolean): TimestampRange
Creates an inclusive Timestamp range and normalizes start/end order.
@paramstart First boundary.@paramend Second boundary.@paramuseTime Include time-of-day when ordering boundaries.@returnsFrozen inclusive Timestamp range.
createTimestampRange(function parseTimestamp(input: string, now?: Timestamp | null): Timestamp | null
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`.
@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-10')!, function parseTimestamp(input: string, now?: Timestamp | null): Timestamp | null
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`.
@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-30')!)

const const overlap: TimestampRange | nulloverlap = function intersectRanges(first: TimestampRange, second: TimestampRange, useTime?: boolean): TimestampRange | null
Returns the inclusive intersection of two TimestampRange values.
@paramfirst First range.@paramsecond Second range.@paramuseTime Include time-of-day in the comparison.@returnsIntersected range, or `null` when the ranges do not overlap.
intersectRanges(const sprint: TimestampRangesprint, const blackout: TimestampRangeblackout)

function getDate(timestamp: Timestamp): string
Formats the date portion of a Timestamp object.
@paramtimestamp Timestamp object to format.@returnsDate string such as `YYYY-MM-DD`.
getDate(const overlap: TimestampRange | nulloverlap!.TimestampRange.start: Timestamp
Inclusive range start.
start) // "2036-06-10"
function getDate(timestamp: Timestamp): string
Formats the date portion of a Timestamp object.
@paramtimestamp Timestamp object to format.@returnsDate string such as `YYYY-MM-DD`.
getDate(const overlap: TimestampRange | nulloverlap!.TimestampRange.end: Timestamp
Inclusive range end.
end) // "2036-06-20"

Merge touching ranges

mergeRanges() sorts the ranges and joins ranges that overlap or touch. Date-only ranges touch when the next range starts on the next calendar day.

import { function createTimestampRange(start: Timestamp, end: Timestamp, useTime?: boolean): TimestampRange
Creates an inclusive Timestamp range and normalizes start/end order.
@paramstart First boundary.@paramend Second boundary.@paramuseTime Include time-of-day when ordering boundaries.@returnsFrozen inclusive Timestamp range.
createTimestampRange, function getDate(timestamp: Timestamp): string
Formats the date portion of a Timestamp object.
@paramtimestamp Timestamp object to format.@returnsDate string such as `YYYY-MM-DD`.
getDate, function mergeRanges(ranges: TimestampRange[], useTime?: boolean): TimestampRange[]
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.
@paramranges Ranges to merge.@paramuseTime Include time-of-day in the comparison.@returnsMerged ranges sorted by start boundary.
mergeRanges, function parseTimestamp(input: string, now?: Timestamp | null): Timestamp | null
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`.
@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 merged: TimestampRange[]merged = function mergeRanges(ranges: TimestampRange[], useTime?: boolean): TimestampRange[]
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.
@paramranges Ranges to merge.@paramuseTime Include time-of-day in the comparison.@returnsMerged ranges sorted by start boundary.
mergeRanges([
  function createTimestampRange(start: Timestamp, end: Timestamp, useTime?: boolean): TimestampRange
Creates an inclusive Timestamp range and normalizes start/end order.
@paramstart First boundary.@paramend Second boundary.@paramuseTime Include time-of-day when ordering boundaries.@returnsFrozen inclusive Timestamp range.
createTimestampRange(function parseTimestamp(input: string, now?: Timestamp | null): Timestamp | null
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`.
@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-10')!, function parseTimestamp(input: string, now?: Timestamp | null): Timestamp | null
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`.
@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-12')!),
  function createTimestampRange(start: Timestamp, end: Timestamp, useTime?: boolean): TimestampRange
Creates an inclusive Timestamp range and normalizes start/end order.
@paramstart First boundary.@paramend Second boundary.@paramuseTime Include time-of-day when ordering boundaries.@returnsFrozen inclusive Timestamp range.
createTimestampRange(function parseTimestamp(input: string, now?: Timestamp | null): Timestamp | null
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`.
@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-01')!, function parseTimestamp(input: string, now?: Timestamp | null): Timestamp | null
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`.
@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-04')!),
  function createTimestampRange(start: Timestamp, end: Timestamp, useTime?: boolean): TimestampRange
Creates an inclusive Timestamp range and normalizes start/end order.
@paramstart First boundary.@paramend Second boundary.@paramuseTime Include time-of-day when ordering boundaries.@returnsFrozen inclusive Timestamp range.
createTimestampRange(function parseTimestamp(input: string, now?: Timestamp | null): Timestamp | null
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`.
@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-05')!, function parseTimestamp(input: string, now?: Timestamp | null): Timestamp | null
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`.
@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-07')!),
])

function getDate(timestamp: Timestamp): string
Formats the date portion of a Timestamp object.
@paramtimestamp Timestamp object to format.@returnsDate string such as `YYYY-MM-DD`.
getDate(const merged: TimestampRange[]merged[0]!.TimestampRange.start: Timestamp
Inclusive range start.
start) // "2036-06-01"
function getDate(timestamp: Timestamp): string
Formats the date portion of a Timestamp object.
@paramtimestamp Timestamp object to format.@returnsDate string such as `YYYY-MM-DD`.
getDate(const merged: TimestampRange[]merged[0]!.TimestampRange.end: Timestamp
Inclusive range end.
end) // "2036-06-07"
const merged: TimestampRange[]merged.Array<TimestampRange>.length: number
Gets or sets the length of the array. This is a number one higher than the highest index in the array.
length // 2

Subtract blocked dates

subtractRanges() returns the pieces of a source range that remain after blocked ranges are removed.

import { function createTimestampRange(start: Timestamp, end: Timestamp, useTime?: boolean): TimestampRange
Creates an inclusive Timestamp range and normalizes start/end order.
@paramstart First boundary.@paramend Second boundary.@paramuseTime Include time-of-day when ordering boundaries.@returnsFrozen inclusive Timestamp range.
createTimestampRange, function getDate(timestamp: Timestamp): string
Formats 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 | null
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`.
@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 subtractRanges(source: TimestampRange, blocked: 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.
@paramsource Source range.@paramblocked Ranges to remove from the source.@paramuseTime Include time-of-day in the comparison.@returnsRemaining ranges.
subtractRanges } from '@timestamp-js/core'

const const month: TimestampRangemonth = function createTimestampRange(start: Timestamp, end: Timestamp, useTime?: boolean): TimestampRange
Creates an inclusive Timestamp range and normalizes start/end order.
@paramstart First boundary.@paramend Second boundary.@paramuseTime Include time-of-day when ordering boundaries.@returnsFrozen inclusive Timestamp range.
createTimestampRange(function parseTimestamp(input: string, now?: Timestamp | null): Timestamp | null
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`.
@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-01')!, function parseTimestamp(input: string, now?: Timestamp | null): Timestamp | null
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`.
@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-30')!)
const const maintenance: TimestampRange[]maintenance = [
  function createTimestampRange(start: Timestamp, end: Timestamp, useTime?: boolean): TimestampRange
Creates an inclusive Timestamp range and normalizes start/end order.
@paramstart First boundary.@paramend Second boundary.@paramuseTime Include time-of-day when ordering boundaries.@returnsFrozen inclusive Timestamp range.
createTimestampRange(function parseTimestamp(input: string, now?: Timestamp | null): Timestamp | null
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`.
@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-10')!, function parseTimestamp(input: string, now?: Timestamp | null): Timestamp | null
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`.
@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-12')!),
]

const const available: TimestampRange[]available = function subtractRanges(source: TimestampRange, blocked: 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.
@paramsource Source range.@paramblocked Ranges to remove from the source.@paramuseTime Include time-of-day in the comparison.@returnsRemaining ranges.
subtractRanges(const month: TimestampRangemonth, const maintenance: TimestampRange[]maintenance)

function getDate(timestamp: Timestamp): string
Formats the date portion of a Timestamp object.
@paramtimestamp Timestamp object to format.@returnsDate string such as `YYYY-MM-DD`.
getDate(const available: TimestampRange[]available[0]!.TimestampRange.end: Timestamp
Inclusive range end.
end) // "2036-06-09"
function getDate(timestamp: Timestamp): string
Formats the date portion of a Timestamp object.
@paramtimestamp Timestamp object to format.@returnsDate string such as `YYYY-MM-DD`.
getDate(const available: TimestampRange[]available[1]!.TimestampRange.start: Timestamp
Inclusive range start.
start) // "2036-06-13"

Find time-aware gaps

Pass true for useTime when ranges represent instants inside a day. Time-aware gaps use millisecond boundaries so adjacent ranges stay precise.

import { function createTimestampRange(start: Timestamp, end: Timestamp, useTime?: boolean): TimestampRange
Creates an inclusive Timestamp range and normalizes start/end order.
@paramstart First boundary.@paramend Second boundary.@paramuseTime Include time-of-day when ordering boundaries.@returnsFrozen inclusive Timestamp range.
createTimestampRange, function findRangeGaps(source: TimestampRange, occupied: 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.
@paramsource Source range.@paramoccupied Ranges that are not available.@paramuseTime Include time-of-day in the comparison.@returnsGap ranges.
findRangeGaps, function parseTimestamp(input: string, now?: Timestamp | null): Timestamp | null
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`.
@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 workBlock: TimestampRangeworkBlock = function createTimestampRange(start: Timestamp, end: Timestamp, useTime?: boolean): TimestampRange
Creates an inclusive Timestamp range and normalizes start/end order.
@paramstart First boundary.@paramend Second boundary.@paramuseTime Include time-of-day when ordering boundaries.@returnsFrozen inclusive Timestamp range.
createTimestampRange(
  function parseTimestamp(input: string, now?: Timestamp | null): Timestamp | null
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`.
@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')!,
  function parseTimestamp(input: string, now?: Timestamp | null): Timestamp | null
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`.
@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:00')!,
  true,
)
const const booked: TimestampRange[]booked = [
  function createTimestampRange(start: Timestamp, end: Timestamp, useTime?: boolean): TimestampRange
Creates an inclusive Timestamp range and normalizes start/end order.
@paramstart First boundary.@paramend Second boundary.@paramuseTime Include time-of-day when ordering boundaries.@returnsFrozen inclusive Timestamp range.
createTimestampRange(
    function parseTimestamp(input: string, now?: Timestamp | null): Timestamp | null
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`.
@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:15')!,
    function parseTimestamp(input: string, now?: Timestamp | null): Timestamp | null
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`.
@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:29:59.999')!,
    true,
  ),
]

const const gaps: TimestampRange[]gaps = function findRangeGaps(source: TimestampRange, occupied: 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.
@paramsource Source range.@paramoccupied Ranges that are not available.@paramuseTime Include time-of-day in the comparison.@returnsGap ranges.
findRangeGaps(const workBlock: TimestampRangeworkBlock, const booked: TimestampRange[]booked, true)

const gaps: TimestampRange[]gaps[0]!.TimestampRange.end: Timestamp
Inclusive range end.
end.Timestamp.time?: string | undefined
Formatted time string.

Minute precision is formatted as `HH:mm`; second precision as `HH:mm:ss`;
millisecond precision as `HH:mm:ss.SSS`.
time // "09:14:59.999"
const gaps: TimestampRange[]gaps[1]!.TimestampRange.start: Timestamp
Inclusive range start.
start.Timestamp.time?: string | undefined
Formatted 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"

Pick min and max values

import { function getDate(timestamp: Timestamp): string
Formats the date portion of a Timestamp object.
@paramtimestamp Timestamp object to format.@returnsDate string such as `YYYY-MM-DD`.
getDate, function maxTimestamp(timestamps: Timestamp[], useTime?: boolean): Timestamp
Finds the latest Timestamp in an array.
@paramtimestamps Timestamp objects to compare.@paramuseTime Include time-of-day in the comparison when true.@returnsLatest Timestamp object.
maxTimestamp, function minTimestamp(timestamps: Timestamp[], useTime?: boolean): Timestamp
Finds the earliest Timestamp in an array.
@paramtimestamps Timestamp objects to compare.@paramuseTime Include time-of-day in the comparison when true.@returnsEarliest Timestamp object.
minTimestamp, function parseTimestamp(input: string, now?: Timestamp | null): Timestamp | null
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`.
@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 dates: Timestamp[]dates = [
  function parseTimestamp(input: string, now?: Timestamp | null): Timestamp | null
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`.
@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 parseTimestamp(input: string, now?: Timestamp | null): Timestamp | null
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`.
@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-12')!,
  function parseTimestamp(input: string, now?: Timestamp | null): Timestamp | null
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`.
@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-01')!,
]

function getDate(timestamp: Timestamp): string
Formats the date portion of a Timestamp object.
@paramtimestamp Timestamp object to format.@returnsDate string such as `YYYY-MM-DD`.
getDate(function minTimestamp(timestamps: Timestamp[], useTime?: boolean): Timestamp
Finds the earliest Timestamp in an array.
@paramtimestamps Timestamp objects to compare.@paramuseTime Include time-of-day in the comparison when true.@returnsEarliest Timestamp object.
minTimestamp(const dates: Timestamp[]dates)) // "2026-06-01"
function getDate(timestamp: Timestamp): string
Formats the date portion of a Timestamp object.
@paramtimestamp Timestamp object to format.@returnsDate string such as `YYYY-MM-DD`.
getDate(function maxTimestamp(timestamps: Timestamp[], useTime?: boolean): Timestamp
Finds the latest Timestamp in an array.
@paramtimestamps Timestamp objects to compare.@paramuseTime Include time-of-day in the comparison when true.@returnsLatest Timestamp object.
maxTimestamp(const dates: Timestamp[]dates)) // "2026-06-12"

Measure differences

diffTimestamp() returns milliseconds. daysBetween() and weeksBetween() provide common calendar-sized measurements.

import { function daysBetween(ts1: Timestamp, ts2: Timestamp): number
Returns number of days between two Timestamps
@paramts1 The first Timestamp@paramts2 The second Timestamp@returnsNumber of days
daysBetween, function diffTimestamp(ts1: Timestamp, ts2: Timestamp, strict?: boolean): number
Returns the difference between two Timestamps
@paramts1 The first Timestamp@paramts2 The second Timestamp@paramstrict Optional flag to not to return negative numbers@returnsThe difference
diffTimestamp, function parseTimestamp(input: string, now?: Timestamp | null): Timestamp | null
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`.
@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 weeksBetween(ts1: Timestamp, ts2: Timestamp): number
Returns number of weeks between two Timestamps
@paramts1 The first Timestamp@paramts2 The second Timestamp
weeksBetween } from '@timestamp-js/core'

const const start: Timestampstart = function parseTimestamp(input: string, now?: Timestamp | null): Timestamp | null
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`.
@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-01')!
const const end: Timestampend = function parseTimestamp(input: string, now?: Timestamp | null): Timestamp | null
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`.
@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-15')!

function diffTimestamp(ts1: Timestamp, ts2: Timestamp, strict?: boolean): number
Returns the difference between two Timestamps
@paramts1 The first Timestamp@paramts2 The second Timestamp@paramstrict Optional flag to not to return negative numbers@returnsThe difference
diffTimestamp(const start: Timestampstart, const end: Timestampend) // 1209600000
function daysBetween(ts1: Timestamp, ts2: Timestamp): number
Returns number of days between two Timestamps
@paramts1 The first Timestamp@paramts2 The second Timestamp@returnsNumber of days
daysBetween(const start: Timestampstart, const end: Timestampend) // 14
function weeksBetween(ts1: Timestamp, ts2: Timestamp): number
Returns number of weeks between two Timestamps
@paramts1 The first Timestamp@paramts2 The second Timestamp
weeksBetween(const start: Timestampstart, const end: Timestampend) // 3
Ready for more?
Developing
Intervals + Lists
Developing
SSR + Runtime
Caught a mistake?Edit this page in browser
1. Introduction
2. Compare date and time separately
3. Compare exact timestamps
4. Check inclusive date ranges
5. Create reusable range objects
6. Check overlap between ranges
7. Check overlap between reusable range objects
8. Intersect two ranges
9. Merge touching ranges
10. Subtract blocked dates
11. Find time-aware gaps
12. Pick min and max values
13. Measure differences
MIT License
Copyright (c) Jeff Galbraith
MITPrivacy