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

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): string
Formats the date portion of a Timestamp object.
@paramtimestamp Timestamp object to format.@returnsDate string such as `YYYY-MM-DD`.
getDate, function getDateTime(timestamp: Timestamp): string
Formats a Timestamp as date plus time.
@paramtimestamp Timestamp object to format.@returnsDate-time string such as `YYYY-MM-DD HH:mm`.
getDateTime, 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 dateOnly: TimestampdateOnly = 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')!
const const dateTime: TimestampdateTime = 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 iso: Timestampiso = 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-08T09:30:15.250Z')!

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 dateOnly: TimestampdateOnly) // "2026-06-08"
function getDateTime(timestamp: Timestamp): string
Formats a Timestamp as date plus time.
@paramtimestamp Timestamp object to format.@returnsDate-time string such as `YYYY-MM-DD HH:mm`.
getDateTime(const dateTime: TimestampdateTime) // "2026-06-08 09:30"
function getDateTime(timestamp: Timestamp): string
Formats a Timestamp as date plus time.
@paramtimestamp Timestamp object to format.@returnsDate-time string such as `YYYY-MM-DD HH:mm`.
getDateTime(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 | 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 timestamp: Timestamptimestamp = 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-08T09:30:15-07:00')!

const timestamp: Timestamptimestamp.Timestamp.hour: number
Hour in 24-hour format.
hour // 9
const timestamp: Timestamptimestamp.Timestamp.minute: number
Minute of the hour.
minute // 30
const timestamp: Timestamptimestamp.Timestamp.timezone?: string | undefined
Optional 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() when the input is already a JavaScript Date and you want host-local fields. Use parseDateUTC() when the Date represents an instant and you want UTC fields.

import { function getDateTime(timestamp: Timestamp): string
Formats a Timestamp as date plus time.
@paramtimestamp Timestamp object to format.@returnsDate-time string such as `YYYY-MM-DD HH:mm`.
getDateTime, function parseDate(date: Date): Timestamp | null
Converts 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.@returnsFormatted Timestamp object, or `null` for invalid input.
parseDate, function parseDateUTC(date: Date): Timestamp | null
Converts 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.@returnsFormatted Timestamp object, or `null` for invalid input.
parseDateUTC } 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): Timestamp | null
Converts 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.@returnsFormatted Timestamp object, or `null` for invalid input.
parseDate(const instant: Dateinstant)!
const const utcTimestamp: TimestamputcTimestamp = function parseDateUTC(date: Date): Timestamp | null
Converts 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.@returnsFormatted Timestamp object, or `null` for invalid input.
parseDateUTC(const instant: Dateinstant)!

function getDateTime(timestamp: Timestamp): string
Formats a Timestamp as date plus time.
@paramtimestamp Timestamp object to format.@returnsDate-time string such as `YYYY-MM-DD HH:mm`.
getDateTime(const localTimestamp: TimestamplocalTimestamp) // Depends on the host timezone.
function getDateTime(timestamp: Timestamp): string
Formats a Timestamp as date plus time.
@paramtimestamp Timestamp object to format.@returnsDate-time string such as `YYYY-MM-DD HH:mm`.
getDateTime(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 | false
Converts 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.
parseTime } from '@timestamp-js/core'


function parseTime(input: number | string | {
    hour: number;
    minute: number;
}): number | false
Converts 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.
parseTime('09') // 540


function parseTime(input: number | string | {
    hour: number;
    minute: number;
}): number | false
Converts 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.
parseTime('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): string
Formats the date portion of a Timestamp object.
@paramtimestamp Timestamp object to format.@returnsDate string such as `YYYY-MM-DD`.
getDate, function getDateTime(timestamp: Timestamp): string
Formats a Timestamp as date plus time.
@paramtimestamp Timestamp object to format.@returnsDate-time string such as `YYYY-MM-DD HH:mm`.
getDateTime, function getTime(timestamp: Timestamp): string
Formats 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.
getTime, 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 timestamp: Timestamptimestamp = 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')!

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 timestamp: Timestamptimestamp) // "2036-06-08"
function getTime(timestamp: Timestamp): string
Formats 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.
getTime(const timestamp: Timestamptimestamp) // "09:30:15.250"
function getDateTime(timestamp: Timestamp): string
Formats a Timestamp as date plus time.
@paramtimestamp Timestamp object to format.@returnsDate-time string such as `YYYY-MM-DD HH:mm`.
getDateTime(const timestamp: Timestamptimestamp) // "2036-06-08 09:30:15.250"

Refresh formatted fields after custom transforms

Most helpers already return formatted timestamps. Reach for updateFormatted() only when you intentionally build or alter a timestamp-like object yourself.

import { function copyTimestamp(timestamp: Timestamp): Timestamp
Returns an immutable copy of a Timestamp object.
@paramtimestamp Timestamp object to copy.@returnsFrozen Timestamp copy.
copyTimestamp, 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 updateFormatted(timestamp: Timestamp): Timestamp
Updates the passed Timestamp with formatted data (time string, date string, weekday, day of year and workweek)
@paramtimestamp The Timestamp to transform@returnsA new Timestamp
updateFormatted } from '@timestamp-js/core'

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

const const refreshed: Timestamprefreshed = function updateFormatted(timestamp: Timestamp): Timestamp
Updates the passed Timestamp with formatted data (time string, date string, weekday, day of year and workweek)
@paramtimestamp The Timestamp to transform@returnsA new Timestamp
updateFormatted({ ...const copied: Timestampcopied, Timestamp.hour: number
Hour in 24-hour format.
hour: 14, Timestamp.minute: number
Minute of the hour.
minute: 45 })

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

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): Date
Converts a Timestamp to a local JavaScript Date.

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

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

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

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

This is equivalent to `makeDateTime(timestamp)`.
@paramtimestamp Timestamp object to convert.@returnsLocal JavaScript Date object.
getDateObject(const timestamp: Timestamptimestamp)
const localDate: DatelocalDate instanceof var Date: DateConstructor
Enables 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 | 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'
import type { const TimeObject: TimeObject
Time-only value used when callers need hour/minute input without a date.


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

Timestamps use Gregorian calendar fields and preserve optional ISO timezone
suffixes without converting the wall-clock values into another zone.


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: string
Date string in `YYYY-MM-DD` form when the timestamp has a day.
date} ${timestamp: Timestamptimestamp.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 ?? '00:00'}`
}

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

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

function asStorageKey(timestamp: Timestamp): stringasStorageKey(const timestamp: Timestamptimestamp) // "2036-06-08 09:30"
function toMinutes(time: TimeObject): numbertoMinutes({ TimeObject.hour: number
Hour in 24-hour format.
hour: 9, TimeObject.minute: number
Minute 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. Refresh formatted fields after custom transforms
8. Convert back to native Date values
9. Type your application boundaries
MIT License
Copyright (c) Jeff Galbraith
MITPrivacy