Timezone Model || Timestamp

Timestamp

v0.1.0-rc.0

Timezone Model

Timestamp currently treats parsed strings as calendar-style wall-clock values.

That means a timezone suffix is preserved for caller awareness, but it does not trigger automatic conversion.

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.parseTimestamp } 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.parseTimestamp('2026-06-08T09:30:15.250-07:00')

const timestamp: Timestamp | nulltimestamp?.Timestamp.hour: number | undefinedHour in 24-hour format.hour // 9
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

Why no automatic conversion?

Calendar UIs and scheduling workflows often care about the visible wall-clock value. Automatically converting 2026-06-08T00:30:00Z into a local timezone can unexpectedly move the date to the previous day.

Timestamp keeps parsing stable and explicit: parsing records the suffix and preserves the wall-clock fields.

SSR note

If server and client timezone differences matter, pass explicit timestamps or use UTC parsing behavior with native Date input.

Ready for more?

Caught a mistake?Edit this page in browser

1. Introduction

2. Why no automatic conversion?

3. SSR note