Parsing And Formatting

Timestamp

v0.1.0-rc.5

Use these examples when app code receives date strings from forms, APIs, route params, or persisted state.

Timestamp does not need a UI playground like CodePen because the package has no visual component. The useful examples are small, copyable TypeScript flows with known output.

Parse common inputs

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`.@categoryconversiongetDate, function getDateTime(timestamp: Timestamp): stringFormats a Timestamp as date plus time.
@paramtimestamp Timestamp object to format.@returnsDate-time string such as `YYYY-MM-DD HH:mm`.@categoryconversiongetDateTime, 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: TimestampdateOnly = 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: TimestampdateTime = 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: Timestampiso = 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')!

function getDate(timestamp: Timestamp): stringFormats the date portion of a Timestamp object.
@paramtimestamp Timestamp object to format.@returnsDate string such as `YYYY-MM-DD`.@categoryconversiongetDate(const dateOnly: TimestampdateOnly) // "2026-06-08"
function getDateTime(timestamp: Timestamp): stringFormats a Timestamp as date plus time.
@paramtimestamp Timestamp object to format.@returnsDate-time string such as `YYYY-MM-DD HH:mm`.@categoryconversiongetDateTime(const dateTime: TimestampdateTime) // "2026-06-08 09:30"
function getDateTime(timestamp: Timestamp): stringFormats a Timestamp as date plus time.
@paramtimestamp Timestamp object to format.@returnsDate-time string such as `YYYY-MM-DD HH:mm`.@categoryconversiongetDateTime(const iso: Timestampiso) // "2026-06-08 09:30:15.250Z"

Preserve timezone suffixes

Timestamp keeps parsed wall-clock fields stable. Timezone suffixes are stored on the object, but parsing does not convert the date or time into the local runtime timezone.

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: Timestamptimestamp = 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-07:00')!

const timestamp: Timestamptimestamp.Timestamp.hour: numberHour in 24-hour format.hour // 9
const timestamp: Timestamptimestamp.Timestamp.minute: numberMinute of the hour.minute // 30
const timestamp: Timestamptimestamp.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"

Convert native Date values explicitly

Use parseDate(date, calendar) when the input is already a JavaScript Date and you want host-local fields. Use parseDateUTC(date, calendar) when the Date represents an instant and you want UTC fields. Omit calendar for Gregorian output, or pass a CalendarSystem for adapter-native date fields.

import { function getDateTime(timestamp: Timestamp): stringFormats a Timestamp as date plus time.
@paramtimestamp Timestamp object to format.@returnsDate-time string such as `YYYY-MM-DD HH:mm`.@categoryconversiongetDateTime, function parseDate(date: Date, calendar?: CalendarSystem): Timestamp | nullConverts a JavaScript Date into a formatted Timestamp using host-local fields.

Use parseDateUTC() when the Date represents an instant that should be read
with UTC getters instead of host-local getters.
@paramdate JavaScript Date to convert.@paramcalendar Calendar system to use. Defaults to Gregorian; pass an adapter such as islamicCivilCalendar for native calendar fields.@returnsFormatted Timestamp object, or `null` for invalid input.@categoryparsingparseDate, function parseDateUTC(date: Date, calendar?: CalendarSystem): Timestamp | nullConverts a JavaScript Date into a formatted Timestamp using UTC fields.

Use this when server and client output should agree on the same UTC calendar
and time fields for a native Date instant.
@paramdate JavaScript Date to convert.@paramcalendar Calendar system to use. Defaults to Gregorian; pass an adapter such as islamicCivilCalendar for native calendar fields.@returnsFormatted Timestamp object, or `null` for invalid input.@categoryparsingparseDateUTC } from '@timestamp-js/core'

const const instant: Dateinstant = new var Date: DateConstructor
new (value: number | string | Date) => Date (+4 overloads)Date('2026-06-08T09:30:00.000Z')

const const localTimestamp: TimestamplocalTimestamp = function parseDate(date: Date, calendar?: CalendarSystem): Timestamp | nullConverts a JavaScript Date into a formatted Timestamp using host-local fields.

Use parseDateUTC() when the Date represents an instant that should be read
with UTC getters instead of host-local getters.
@paramdate JavaScript Date to convert.@paramcalendar Calendar system to use. Defaults to Gregorian; pass an adapter such as islamicCivilCalendar for native calendar fields.@returnsFormatted Timestamp object, or `null` for invalid input.@categoryparsingparseDate(const instant: Dateinstant)!
const const utcTimestamp: TimestamputcTimestamp = function parseDateUTC(date: Date, calendar?: CalendarSystem): Timestamp | nullConverts a JavaScript Date into a formatted Timestamp using UTC fields.

Use this when server and client output should agree on the same UTC calendar
and time fields for a native Date instant.
@paramdate JavaScript Date to convert.@paramcalendar Calendar system to use. Defaults to Gregorian; pass an adapter such as islamicCivilCalendar for native calendar fields.@returnsFormatted Timestamp object, or `null` for invalid input.@categoryparsingparseDateUTC(const instant: Dateinstant)!

function getDateTime(timestamp: Timestamp): stringFormats a Timestamp as date plus time.
@paramtimestamp Timestamp object to format.@returnsDate-time string such as `YYYY-MM-DD HH:mm`.@categoryconversiongetDateTime(const localTimestamp: TimestamplocalTimestamp) // Depends on the host timezone.
function getDateTime(timestamp: Timestamp): stringFormats a Timestamp as date plus time.
@paramtimestamp Timestamp object to format.@returnsDate-time string such as `YYYY-MM-DD HH:mm`.@categoryconversiongetDateTime(const utcTimestamp: TimestamputcTimestamp) // "2026-06-08 09:30"

Parse time-only values

Use parseTime() for controls or APIs that only carry time-of-day data.

import { function parseTime(input: number | string | {
    hour: number;
    minute: number;
}): number | falseConverts time input into minutes since midnight.

Strings may include seconds or milliseconds, but sub-minute precision is
ignored for this minute-oriented helper.
@paraminput - Minutes since midnight, a time string, or an object with hour and minute fields.@returnsMinutes since midnight, or `false` when the input cannot be parsed.@categoryparsingparseTime } from '@timestamp-js/core'

function parseTime(input: number | string | {
    hour: number;
    minute: number;
}): number | falseConverts time input into minutes since midnight.

Strings may include seconds or milliseconds, but sub-minute precision is
ignored for this minute-oriented helper.
@paraminput - Minutes since midnight, a time string, or an object with hour and minute fields.@returnsMinutes since midnight, or `false` when the input cannot be parsed.@categoryparsingparseTime('09') // 540

function parseTime(input: number | string | {
    hour: number;
    minute: number;
}): number | falseConverts time input into minutes since midnight.

Strings may include seconds or milliseconds, but sub-minute precision is
ignored for this minute-oriented helper.
@paraminput - Minutes since midnight, a time string, or an object with hour and minute fields.@returnsMinutes since midnight, or `false` when the input cannot be parsed.@categoryparsingparseTime('09:30:15.250') // 570

Format individual pieces

Use getDate(), getTime(), and getDateTime() when you need stable string output for inputs, route params, storage, or display.

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`.@categoryconversiongetDate, function getDateTime(timestamp: Timestamp): stringFormats a Timestamp as date plus time.
@paramtimestamp Timestamp object to format.@returnsDate-time string such as `YYYY-MM-DD HH:mm`.@categoryconversiongetDateTime, function getTime(timestamp: Timestamp): stringFormats the time portion of a Timestamp object.

Minute precision is formatted as `HH:mm`; second precision as `HH:mm:ss`;
millisecond precision as `HH:mm:ss.SSS`.
@paramtimestamp Timestamp object to format.@returnsTime string, or an empty string when the timestamp has no time.@categoryconversiongetTime, 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: Timestamptimestamp = 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('2036-06-08T09:30:15.250Z')!

function getDate(timestamp: Timestamp): stringFormats the date portion of a Timestamp object.
@paramtimestamp Timestamp object to format.@returnsDate string such as `YYYY-MM-DD`.@categoryconversiongetDate(const timestamp: Timestamptimestamp) // "2036-06-08"
function getTime(timestamp: Timestamp): stringFormats the time portion of a Timestamp object.

Minute precision is formatted as `HH:mm`; second precision as `HH:mm:ss`;
millisecond precision as `HH:mm:ss.SSS`.
@paramtimestamp Timestamp object to format.@returnsTime string, or an empty string when the timestamp has no time.@categoryconversiongetTime(const timestamp: Timestamptimestamp) // "09:30:15.250"
function getDateTime(timestamp: Timestamp): stringFormats a Timestamp as date plus time.
@paramtimestamp Timestamp object to format.@returnsDate-time string such as `YYYY-MM-DD HH:mm`.@categoryconversiongetDateTime(const timestamp: Timestamptimestamp) // "2036-06-08 09:30:15.250"

Format compact masks

Use formatTimestamp() when fixed numeric output is enough and you do not need a locale formatter. Supported tokens are YYYY, MM, DD, HH, mm, ss, and SSS. Unknown text is preserved as literal output.

import { function formatTimestamp(timestamp: Timestamp, mask: TimestampFormatMask): stringFormats a Timestamp with a compact numeric mask.

This helper is intentionally small and deterministic. It supports fixed
numeric tokens only: `YYYY`, `MM`, `DD`, `HH`, `mm`, `ss`, and `SSS`. Use
Intl-backed helpers when you need localized month names, weekday names, or
calendar-specific display labels.
@paramtimestamp Timestamp object to format.@parammask Formatting mask such as `YYYY-MM-DD`, `HH:mm:ss`, or `YYYYMMDD`.@returnsFormatted string.@categoryformattingformatTimestamp, 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: Timestamptimestamp = 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('2036-06-08T09:30:15.250Z')!

function formatTimestamp(timestamp: Timestamp, mask: TimestampFormatMask): stringFormats a Timestamp with a compact numeric mask.

This helper is intentionally small and deterministic. It supports fixed
numeric tokens only: `YYYY`, `MM`, `DD`, `HH`, `mm`, `ss`, and `SSS`. Use
Intl-backed helpers when you need localized month names, weekday names, or
calendar-specific display labels.
@paramtimestamp Timestamp object to format.@parammask Formatting mask such as `YYYY-MM-DD`, `HH:mm:ss`, or `YYYYMMDD`.@returnsFormatted string.@categoryformattingformatTimestamp(const timestamp: Timestamptimestamp, 'YYYY-MM-DD') // "2036-06-08"
function formatTimestamp(timestamp: Timestamp, mask: TimestampFormatMask): stringFormats a Timestamp with a compact numeric mask.

This helper is intentionally small and deterministic. It supports fixed
numeric tokens only: `YYYY`, `MM`, `DD`, `HH`, `mm`, `ss`, and `SSS`. Use
Intl-backed helpers when you need localized month names, weekday names, or
calendar-specific display labels.
@paramtimestamp Timestamp object to format.@parammask Formatting mask such as `YYYY-MM-DD`, `HH:mm:ss`, or `YYYYMMDD`.@returnsFormatted string.@categoryformattingformatTimestamp(const timestamp: Timestamptimestamp, 'YYYYMMDD') // "20360608"
function formatTimestamp(timestamp: Timestamp, mask: TimestampFormatMask): stringFormats a Timestamp with a compact numeric mask.

This helper is intentionally small and deterministic. It supports fixed
numeric tokens only: `YYYY`, `MM`, `DD`, `HH`, `mm`, `ss`, and `SSS`. Use
Intl-backed helpers when you need localized month names, weekday names, or
calendar-specific display labels.
@paramtimestamp Timestamp object to format.@parammask Formatting mask such as `YYYY-MM-DD`, `HH:mm:ss`, or `YYYYMMDD`.@returnsFormatted string.@categoryformattingformatTimestamp(const timestamp: Timestamptimestamp, 'HH:mm:ss.SSS') // "09:30:15.250"
function formatTimestamp(timestamp: Timestamp, mask: TimestampFormatMask): stringFormats a Timestamp with a compact numeric mask.

This helper is intentionally small and deterministic. It supports fixed
numeric tokens only: `YYYY`, `MM`, `DD`, `HH`, `mm`, `ss`, and `SSS`. Use
Intl-backed helpers when you need localized month names, weekday names, or
calendar-specific display labels.
@paramtimestamp Timestamp object to format.@parammask Formatting mask such as `YYYY-MM-DD`, `HH:mm:ss`, or `YYYYMMDD`.@returnsFormatted string.@categoryformattingformatTimestamp(const timestamp: Timestamptimestamp, 'date=YYYY-MM-DD time=HH:mm') // "date=2036-06-08 time=09:30"

Use formatDateLocal() when a JavaScript Date should be read with host-local getters. Use formatDateUTC() when the same instant should produce deterministic UTC fields in every runtime.

import { function formatDateLocal(date: Date, mask: TimestampFormatMask): string | nullFormats a JavaScript Date with host-local fields and a compact numeric mask.

Use formatDateUTC() when server and client output should agree on UTC
fields for the same instant.
@paramdate JavaScript Date to format.@parammask Formatting mask such as `YYYY-MM-DD`, `HH:mm:ss`, or `YYYYMMDD`.@returnsFormatted string, or `null` for an invalid Date.@categoryformattingformatDateLocal, function formatDateUTC(date: Date, mask: TimestampFormatMask): string | nullFormats a JavaScript Date with UTC fields and a compact numeric mask.

Use this for deterministic output when a Date represents a portable instant
and the formatted fields should not depend on the host timezone.
@paramdate JavaScript Date to format.@parammask Formatting mask such as `YYYY-MM-DD`, `HH:mm:ss`, or `YYYYMMDD`.@returnsFormatted string, or `null` for an invalid Date.@categoryformattingformatDateUTC } from '@timestamp-js/core'

const const instant: Dateinstant = new var Date: DateConstructor
new (value: number | string | Date) => Date (+4 overloads)Date('2036-06-08T09:30:15.250Z')

function formatDateLocal(date: Date, mask: TimestampFormatMask): string | nullFormats a JavaScript Date with host-local fields and a compact numeric mask.

Use formatDateUTC() when server and client output should agree on UTC
fields for the same instant.
@paramdate JavaScript Date to format.@parammask Formatting mask such as `YYYY-MM-DD`, `HH:mm:ss`, or `YYYYMMDD`.@returnsFormatted string, or `null` for an invalid Date.@categoryformattingformatDateLocal(const instant: Dateinstant, 'YYYY-MM-DD HH:mm') // Depends on the host timezone.
function formatDateUTC(date: Date, mask: TimestampFormatMask): string | nullFormats a JavaScript Date with UTC fields and a compact numeric mask.

Use this for deterministic output when a Date represents a portable instant
and the formatted fields should not depend on the host timezone.
@paramdate JavaScript Date to format.@parammask Formatting mask such as `YYYY-MM-DD`, `HH:mm:ss`, or `YYYYMMDD`.@returnsFormatted string, or `null` for an invalid Date.@categoryformattingformatDateUTC(const instant: Dateinstant, 'YYYY-MM-DD HH:mm:ss.SSS') // "2036-06-08 09:30:15.250"

Compact masks are intentionally not a replacement for Intl.DateTimeFormat. Use the native locale formatter helpers when you need localized month names, weekday names, numbering systems, or calendar-specific display labels.

Refresh formatted fields after custom transforms

Most helpers already return formatted timestamps. Reach for updateFormatted(timestamp, calendar) only when you intentionally build or alter a timestamp-like object yourself. Pass the calendar when the timestamp fields belong to an adapter.

import { function copyTimestamp(timestamp: Timestamp): TimestampReturns an immutable copy of a Timestamp object.
@paramtimestamp Timestamp object to copy.@returnsFrozen Timestamp copy.@categorystatecopyTimestamp, 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, function updateFormatted(timestamp: Timestamp, calendar?: CalendarSystem): TimestampUpdates the passed Timestamp with formatted data (time string, date string, weekday, day of year and workweek)
@paramtimestamp The Timestamp to transform@paramcalendar Calendar system to use. Defaults to Gregorian; pass an adapter such as islamicCivilCalendar for native calendar fields.@returnsA new Timestamp@categoryformattingupdateFormatted } from '@timestamp-js/core'

const const source: Timestampsource = 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('2036-06-08 09:30')!
const const copied: Timestampcopied = function copyTimestamp(timestamp: Timestamp): TimestampReturns an immutable copy of a Timestamp object.
@paramtimestamp Timestamp object to copy.@returnsFrozen Timestamp copy.@categorystatecopyTimestamp(const source: Timestampsource)

const const refreshed: Timestamprefreshed = function updateFormatted(timestamp: Timestamp, calendar?: CalendarSystem): TimestampUpdates the passed Timestamp with formatted data (time string, date string, weekday, day of year and workweek)
@paramtimestamp The Timestamp to transform@paramcalendar Calendar system to use. Defaults to Gregorian; pass an adapter such as islamicCivilCalendar for native calendar fields.@returnsA new Timestamp@categoryformattingupdateFormatted({ ...const copied: Timestampcopied, Timestamp.hour: numberHour in 24-hour format.hour: 14, Timestamp.minute: numberMinute of the hour.minute: 45 })

const refreshed: Timestamprefreshed.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 // "14:45"
const copied: Timestampcopied.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"

Convert back to native Date values

Use UTC output when the Date represents a portable instant. Use local output when you specifically need host-local Date behavior.

import {
  function getDateObject(timestamp: Timestamp): DateConverts a Timestamp to a local JavaScript Date.

This is equivalent to `makeDateTime(timestamp)`.
@paramtimestamp Timestamp object to convert.@returnsLocal JavaScript Date object.@categoryconversiongetDateObject,
  function makeDate(timestamp: Timestamp): DateConverts a Timestamp date into a host-local JavaScript Date.
@paramtimestamp Timestamp object to convert.@returnsHost-local JavaScript Date object.@categoryconversionmakeDate,
  function makeDateTime(timestamp: Timestamp): DateConverts a Timestamp date and time into a host-local JavaScript Date.
@paramtimestamp Timestamp object to convert.@returnsHost-local JavaScript Date object.@categoryconversionmakeDateTime,
  function makeDateTimeUTC(timestamp: Timestamp): DateConverts a Timestamp date and time into a UTC JavaScript Date.
@paramtimestamp Timestamp object to convert.@returnsJavaScript Date object built with `Date.UTC()`.@categoryconversionmakeDateTimeUTC,
  function makeDateUTC(timestamp: Timestamp): DateConverts a Timestamp date into a UTC JavaScript Date.
@paramtimestamp Timestamp object to convert.@returnsJavaScript Date object built with `Date.UTC()`.@categoryconversionmakeDateUTC,
  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: Timestamptimestamp = 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('2036-06-08 09:30')!

function makeDate(timestamp: Timestamp): DateConverts a Timestamp date into a host-local JavaScript Date.
@paramtimestamp Timestamp object to convert.@returnsHost-local JavaScript Date object.@categoryconversionmakeDate(const timestamp: Timestamptimestamp).Date.getHours(): numberGets the hours in a date, using local time.getHours() // 0
function makeDateTime(timestamp: Timestamp): DateConverts a Timestamp date and time into a host-local JavaScript Date.
@paramtimestamp Timestamp object to convert.@returnsHost-local JavaScript Date object.@categoryconversionmakeDateTime(const timestamp: Timestamptimestamp).Date.getMinutes(): numberGets the minutes of a Date object, using local time.getMinutes() // 30

function makeDateUTC(timestamp: Timestamp): DateConverts a Timestamp date into a UTC JavaScript Date.
@paramtimestamp Timestamp object to convert.@returnsJavaScript Date object built with `Date.UTC()`.@categoryconversionmakeDateUTC(const timestamp: Timestamptimestamp).Date.toISOString(): stringReturns a date as a string value in ISO format.toISOString() // "2036-06-08T00:00:00.000Z"
function makeDateTimeUTC(timestamp: Timestamp): DateConverts a Timestamp date and time into a UTC JavaScript Date.
@paramtimestamp Timestamp object to convert.@returnsJavaScript Date object built with `Date.UTC()`.@categoryconversionmakeDateTimeUTC(const timestamp: Timestamptimestamp).Date.toISOString(): stringReturns a date as a string value in ISO format.toISOString() // "2036-06-08T09:30:00.000Z"

const const localDate: DatelocalDate = function getDateObject(timestamp: Timestamp): DateConverts a Timestamp to a local JavaScript Date.

This is equivalent to `makeDateTime(timestamp)`.
@paramtimestamp Timestamp object to convert.@returnsLocal JavaScript Date object.@categoryconversiongetDateObject(const timestamp: Timestamptimestamp)
const localDate: DatelocalDate instanceof var Date: DateConstructorEnables basic storage and retrieval of dates and times.Date // true

Type your application boundaries

Import types from the same package when your app accepts or returns Timestamp 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'
import type { const TimeObject: TimeObjectTime-only value used when callers need hour/minute input without a date.


Frozen empty time-object template.TimeObject, const Timestamp: TimestampImmutable timestamp data used by all parser, comparison, and date math helpers.

Core parser helpers produce Gregorian calendar fields and preserve optional
ISO timezone suffixes without converting the wall-clock values into another
zone. Calendar adapter helpers can also produce timestamp-shaped values whose
year/month/day fields belong to the adapter identified by `calendarId`.


Frozen empty timestamp template.

Use copyTimestamp or parser helpers to create new timestamp objects
instead of mutating this shared default.Timestamp } from '@timestamp-js/core'

function function asStorageKey(timestamp: Timestamp): stringasStorageKey(timestamp: Timestamptimestamp: Timestamp): string {
  return `${timestamp: Timestamptimestamp.Timestamp.date: stringDate string in `YYYY-MM-DD` form when the timestamp has a day.date} ${timestamp: Timestamptimestamp.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 ?? '00:00'}`
}

function function toMinutes(time: TimeObject): numbertoMinutes(time: TimeObjecttime: TimeObject): number {
  return time: TimeObjecttime.TimeObject.hour: numberHour in 24-hour format.hour * 60 + time: TimeObjecttime.TimeObject.minute: numberMinute of the hour.minute
}

const const timestamp: Timestamptimestamp = 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('2036-06-08 09:30')!

function asStorageKey(timestamp: Timestamp): stringasStorageKey(const timestamp: Timestamptimestamp) // "2036-06-08 09:30"
function toMinutes(time: TimeObject): numbertoMinutes({ TimeObject.hour: numberHour in 24-hour format.hour: 9, TimeObject.minute: numberMinute of the hour.minute: 30 }) // 570

Ready for more?

API

Comparisons

Developing

Validation + Boundaries

Caught a mistake?Edit this page in browser

1. Introduction

2. Parse common inputs

3. Preserve timezone suffixes

4. Convert native Date values explicitly

5. Parse time-only values

6. Format individual pieces

7. Format compact masks

8. Refresh formatted fields after custom transforms

9. Convert back to native Date values

10. Type your application boundaries