Timestamp is designed to work in SSR, SSG, browser, and backend contexts.
The package does not touch window, document, storage APIs, or framework-specific globals. That keeps imports safe during server rendering and static builds.
Server and client timezones
The expected reality is simple: helpers that use the host clock use the timezone of the runtime where they execute.
That means a server in UTC and a browser in America/Edmonton can produce different values if both call today() during render.
For deterministic SSR output:
- Prefer passing explicit timestamps into helpers.
- Use caller-provided
nowvalues for relative comparisons. - Use
todayUTC()ornowUTC()when the application wants server and client to agree on UTC calendar fields. - Use
parseDateUTC()when converting nativeDateinstances that represent instants. - Pass a
CalendarSystemtotodayUTC(),nowUTC(),parseDateUTC(), orupdateRelative()when the rendered date fields should be native to an adapter.
import { function nowUTC(date?: Date, calendar?: CalendarSystem): TimestampReturns the current date-time as an immutable Timestamp using UTC fields.
Use this when server and client output should agree on UTC calendar and time
values. For fully deterministic SSR output, pass a Date captured by the
caller instead of allowing each runtime to create its own current Date.nowUTC, 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 updateRelative(timestamp: Timestamp, now: Timestamp, time?: boolean, calendar?: CalendarSystem): TimestampReturns a Timestamp with relative flags compared to a supplied `now` value.
The returned object includes `past`, `current`, `future`, and
`currentWeekday` flags. Pass `true` for `time` when both values should be
compared at time-of-day precision.updateRelative } from '@timestamp-js/core'
const const now: Timestampnow = function nowUTC(date?: Date, calendar?: CalendarSystem): TimestampReturns the current date-time as an immutable Timestamp using UTC fields.
Use this when server and client output should agree on UTC calendar and time
values. For fully deterministic SSR output, pass a Date captured by the
caller instead of allowing each runtime to create its own current Date.nowUTC(new var Date: DateConstructor
new (value: number | string | Date) => Date (+4 overloads)
const target: Timestamptarget = 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('2036-06-09')!
const const stable: Timestampstable = function updateRelative(timestamp: Timestamp, now: Timestamp, time?: boolean, calendar?: CalendarSystem): TimestampReturns a Timestamp with relative flags compared to a supplied `now` value.
The returned object includes `past`, `current`, `future`, and
`currentWeekday` flags. Pass `true` for `time` when both values should be
compared at time-of-day precision.updateRelative(const target: Timestamptarget, const now: Timestampnow)If the render needs to be stable even when time passes between server render and client hydration, capture the date once in app code and pass it to nowUTC(date) or todayUTC(date). Adapter code can pass the calendar as the second argument.
Date objects
parseDateUTC(date, calendar) reads a native Date using UTC fields and returns fields for the requested calendar. parseDate(date, calendar) reads host-local fields.
import { function nowUTC(date?: Date, calendar?: CalendarSystem): TimestampReturns the current date-time as an immutable Timestamp using UTC fields.
Use this when server and client output should agree on UTC calendar and time
values. For fully deterministic SSR output, pass a Date captured by the
caller instead of allowing each runtime to create its own current Date.nowUTC, 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.parseDate, 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.parseDateUTC, function todayUTC(date?: Date, calendar?: CalendarSystem): stringReturns today's date using UTC calendar fields.
Pass a Date fixture to make SSR, tests, and hydration-sensitive render paths
deterministic. This helper reads UTC fields only; it does not convert an
existing Timestamp or timezone-suffixed string. Pass a calendar system to
return today's UTC date in that calendar's native `YYYY-MM-DD` fields.todayUTC } from '@timestamp-js/core'
const const instant: Dateinstant = new var Date: DateConstructor
new (value: number | string | Date) => Date (+4 overloads)
const localTimestamp: Timestamp | nulllocalTimestamp = 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.parseDate(const instant: Dateinstant)
const const utcTimestamp: Timestamp | nullutcTimestamp = 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.parseDateUTC(const instant: Dateinstant)
const const dateOnly: stringdateOnly = function todayUTC(date?: Date, calendar?: CalendarSystem): stringReturns today's date using UTC calendar fields.
Pass a Date fixture to make SSR, tests, and hydration-sensitive render paths
deterministic. This helper reads UTC fields only; it does not convert an
existing Timestamp or timezone-suffixed string. Pass a calendar system to
return today's UTC date in that calendar's native `YYYY-MM-DD` fields.todayUTC(const instant: Dateinstant)
const const dateTime: TimestampdateTime = function nowUTC(date?: Date, calendar?: CalendarSystem): TimestampReturns the current date-time as an immutable Timestamp using UTC fields.
Use this when server and client output should agree on UTC calendar and time
values. For fully deterministic SSR output, pass a Date captured by the
caller instead of allowing each runtime to create its own current Date.nowUTC(const instant: Dateinstant)