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`.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`.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:00Why 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.
UTC storage and user timezones
Use instant helpers when a workflow needs one shared moment in time.
A meeting picker usually starts as a wall-clock value in the organizer’s timezone. Convert that value to a UTC instant before storing it, then convert the stored instant back into each viewer’s timezone for display.
import { function fromInstant(instant: InstantInput, timeZone: string, calendar?: CalendarSystem): Timestamp | nullConverts a UTC instant into a Timestamp displayed in an IANA timezone.
Use this when reading UTC values from storage and showing each user the
meeting or booking time in their own timezone.fromInstant, 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`.parseTimestamp, function toInstant(timestamp: Timestamp, timeZone: string): string | nullConverts a wall-clock Timestamp in an IANA timezone into a UTC ISO instant.
This is a convenience wrapper around `toInstantMilliseconds()` for database
fields that store ISO UTC strings.toInstant } from '@timestamp-js/core'
const const selected: Timestampselected = 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`.parseTimestamp('2026-07-03 09:00')!
const const stored: string | nullstored = function toInstant(timestamp: Timestamp, timeZone: string): string | nullConverts a wall-clock Timestamp in an IANA timezone into a UTC ISO instant.
This is a convenience wrapper around `toInstantMilliseconds()` for database
fields that store ISO UTC strings.toInstant(const selected: Timestampselected, 'America/Edmonton')
const stored: string | nullstored // '2026-07-03T15:00:00.000Z'
const const london: Timestamp | nulllondon = function fromInstant(instant: InstantInput, timeZone: string, calendar?: CalendarSystem): Timestamp | nullConverts a UTC instant into a Timestamp displayed in an IANA timezone.
Use this when reading UTC values from storage and showing each user the
meeting or booking time in their own timezone.fromInstant(const stored: string | nullstored!, 'Europe/London')
const const edmonton: Timestamp | nulledmonton = function fromInstant(instant: InstantInput, timeZone: string, calendar?: CalendarSystem): Timestamp | nullConverts a UTC instant into a Timestamp displayed in an IANA timezone.
Use this when reading UTC values from storage and showing each user the
meeting or booking time in their own timezone.fromInstant(const stored: string | nullstored!, 'America/Edmonton')
const london: Timestamp | nulllondon?.Timestamp.date: string | undefinedDate string in `YYYY-MM-DD` form when the timestamp has a day.date // '2026-07-03'
const london: Timestamp | nulllondon?.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 // '16:00'
const edmonton: Timestamp | nulledmonton?.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:00'toInstant() returns a UTC ISO string for databases that store text values. toInstantMilliseconds() returns the same instant as Unix milliseconds. The matching fromInstant() and fromInstantMilliseconds() helpers convert stored UTC instants into display fields for a requested IANA timezone.
Invalid timezone names return null. Wall-clock values that do not exist because of a daylight-saving transition also return null, so forms can ask the user to choose a real local time.
Why “instant” instead of “UTC”?
The instant name describes the shared moment in time. The stored value is usually represented as UTC, but the important conversion is from a wall-clock value in one timezone into an absolute instant, then from that instant into another user’s timezone.
Names like toUTC() and fromUTC() can sound like simple formatting helpers. Timestamp already uses UTC in helpers such as todayUTC(), nowUTC(), and makeDateTimeUTC() where the fields are intentionally read as UTC. The instant helpers are for scheduling and storage workflows where the same meeting must be shown correctly to users in different timezones.
SSR note
If server and client timezone differences matter, pass explicit timestamps or use UTC parsing behavior with native Date input.