Comparisons || Timestamp

Timestamp

v0.1.0-rc.5

Comparisons

Timestamp comparison helpers work with date-only, time-only, and date-time values.

import { function compareDate(ts1: Timestamp, ts2: Timestamp): booleanCompares the calendar date portion of two Timestamp objects.
@paramts1 First Timestamp object.@paramts2 Second Timestamp object.@returnsTrue when both dates are the same.@categorycomparisoncompareDate, function compareDateTime(ts1: Timestamp, ts2: Timestamp): booleanCompares 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.@categorycomparisoncompareDateTime, function compareTime(ts1: Timestamp, ts2: Timestamp): booleanCompares the formatted time portion of two Timestamp objects.
@paramts1 First Timestamp object.@paramts2 Second Timestamp object.@returnsTrue when both times are the same.@categorycomparisoncompareTime, 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.@categoryparsingparseTimestamp } from '@timestamp-js/core'

const const a: Timestampa = 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.@categoryparsingparseTimestamp('2026-06-08 09:30')!
const const b: Timestampb = 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.@categoryparsingparseTimestamp('2026-06-08 10:00')!

function compareDate(ts1: Timestamp, ts2: Timestamp): booleanCompares the calendar date portion of two Timestamp objects.
@paramts1 First Timestamp object.@paramts2 Second Timestamp object.@returnsTrue when both dates are the same.@categorycomparisoncompareDate(const a: Timestampa, const b: Timestampb)
function compareTime(ts1: Timestamp, ts2: Timestamp): booleanCompares the formatted time portion of two Timestamp objects.
@paramts1 First Timestamp object.@paramts2 Second Timestamp object.@returnsTrue when both times are the same.@categorycomparisoncompareTime(const a: Timestampa, const b: Timestampb)
function compareDateTime(ts1: Timestamp, ts2: Timestamp): booleanCompares 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.@categorycomparisoncompareDateTime(const a: Timestampa, const b: Timestampb)

Ranges

Use range helpers when inclusive date boundaries matter.

import { isBetweenDates, isOverlappingDates, parseTimestamp } from '@timestamp-js/core'

const target = parseTimestamp('2026-06-08')!
const start = parseTimestamp('2026-06-01')!
const end = parseTimestamp('2026-06-30')!

isBetweenDates(target, start, end)
isOverlappingDates(start, end, target, target)

Min and max

import { function maxTimestamp(timestamps: Timestamp[], useTime?: boolean): TimestampFinds the latest Timestamp in an array.
@paramtimestamps Timestamp objects to compare.@paramuseTime Include time-of-day in the comparison when true.@returnsLatest Timestamp object.@categorycomparisonmaxTimestamp, function minTimestamp(timestamps: Timestamp[], useTime?: boolean): TimestampFinds the earliest Timestamp in an array.
@paramtimestamps Timestamp objects to compare.@paramuseTime Include time-of-day in the comparison when true.@returnsEarliest Timestamp object.@categorycomparisonminTimestamp, 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.@categoryparsingparseTimestamp } from '@timestamp-js/core'

const const first: Timestampfirst = 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.@categoryparsingparseTimestamp('2026-06-08')!
const const second: Timestampsecond = 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.@categoryparsingparseTimestamp('2026-06-09')!

function minTimestamp(timestamps: Timestamp[], useTime?: boolean): TimestampFinds the earliest Timestamp in an array.
@paramtimestamps Timestamp objects to compare.@paramuseTime Include time-of-day in the comparison when true.@returnsEarliest Timestamp object.@categorycomparisonminTimestamp([const first: Timestampfirst, const second: Timestampsecond])
function maxTimestamp(timestamps: Timestamp[], useTime?: boolean): TimestampFinds the latest Timestamp in an array.
@paramtimestamps Timestamp objects to compare.@paramuseTime Include time-of-day in the comparison when true.@returnsLatest Timestamp object.@categorycomparisonmaxTimestamp([const first: Timestampfirst, const second: Timestampsecond])

Ready for more?

Caught a mistake?Edit this page in browser

1. Introduction

2. Ranges

3. Min and max