Parsing || Timestamp

Timestamp

v0.1.0-rc.5

Parsing

parseTimestamp() is the main parser for user-facing date and date-time values.

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.@categoryparsingparseTimestamp } from '@timestamp-js/core'

const const dateOnly: Timestamp | nulldateOnly = 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 dateTime: Timestamp | nulldateTime = 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 iso: Timestamp | nulliso = 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-08T09:30:15.250Z')

Supported shapes

2026-06-08
2026-06-08 09:30
2026-06-08T09:30
2026-06-08T09:30:15
2026-06-08T09:30:15.250Z
2026-06-08T09:30:15.250-07:00

Seconds, milliseconds, and timezone suffixes are optional.

Parser choices

Helper	Use it when
`parseTimestamp(value)`	You need a complete Timestamp with formatted and calendar metadata.
`parsed(value)`	You need a faster, minimal Timestamp and do not need derived fields.
`parseDate(date, calendar)`	You already have a JavaScript `Date` and want host-local Timestamp fields.
`parseDateUTC(date, calendar)`	You already have a JavaScript `Date` and want UTC Timestamp fields.
`parseTime(value)`	You need a time-only object from `HH`, `HH:mm`, `HH:mm:ss`, or milliseconds.

Omit calendar for Gregorian fields, or pass a CalendarSystem when the returned timestamp should use adapter-native date fields.

Timezone suffixes

Timezone suffixes are preserved, but parsing does not convert the wall-clock values into another zone.

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.@categoryparsingparseTimestamp } from '@timestamp-js/core'

const const timestamp: Timestamp | nulltimestamp = 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-08T09:30:15.250-07:00')

const timestamp: Timestamp | nulltimestamp?.Timestamp.timezone?: string | undefinedOptional parsed ISO timezone suffix such as `Z`, `+06:00`, or `-0700`.

The suffix is preserved for callers, but parsing does not convert the
wall-clock values into another timezone.timezone
// "-07:00"

That behavior keeps calendar-style wall-clock parsing stable and avoids silent date shifts during parsing.

Ready for more?

Caught a mistake?Edit this page in browser

1. Introduction

2. Supported shapes

3. Parser choices

4. Timezone suffixes