Timestamp is framework-agnostic and does not read browser globals. That makes it safe to import in browser apps, Node.js, SSR builds, serverless functions, workers, and tests.
The SSR detail to watch is not the import itself. It is whether your code asks the runtime for the current date or locale-dependent labels during render.
Prefer explicit inputs during render
If server and client run in different timezones, today() can produce different 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`.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 renderedNow: TimestamprenderedNow = 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-08')!
const const event: Timestampevent = 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-10')!
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 event: Timestampevent, const renderedNow: TimestamprenderedNow)
const stable: Timestampstable.Timestamp.future?: boolean | undefinedTrue when the timestamp is after a comparison timestamp.future // trueUse today checks outside hydration-sensitive render paths
today(calendar) and isToday(date, calendar) are convenient for client-only actions, tests with mocked time, and server logic that owns its timezone. They use the host runtime’s local timezone and return/compare date fields for the requested calendar.
import { function isToday(date: string, calendar?: CalendarSystem): booleanTakes a date string ('YYYY-MM-DD') and validates if it is today's dateisToday, function today(calendar?: CalendarSystem): stringReturns today's date using the host runtime timezone.
For SSR or static rendering, server and client runtimes can produce different
values when they run in different timezones. Use todayUTC() when the app
wants a stable UTC calendar date instead. Pass a calendar system to return
today's date in that calendar's native `YYYY-MM-DD` fields.today } from '@timestamp-js/core'
const const currentDate: stringcurrentDate = function today(calendar?: CalendarSystem): stringReturns today's date using the host runtime timezone.
For SSR or static rendering, server and client runtimes can produce different
values when they run in different timezones. Use todayUTC() when the app
wants a stable UTC calendar date instead. Pass a calendar system to return
today's date in that calendar's native `YYYY-MM-DD` fields.today()
function isToday(date: string, calendar?: CalendarSystem): booleanTakes a date string ('YYYY-MM-DD') and validates if it is today's dateisToday(const currentDate: stringcurrentDate) // trueUse UTC helpers when the app wants UTC calendar fields
todayUTC(date, calendar) returns a UTC date string. nowUTC(date, calendar) returns an immutable Timestamp built from UTC date-time fields. Pass a Date fixture when SSR output must be deterministic across server render and client hydration. Pass a calendar adapter when the date fields should be native to that calendar.
import { function isTodayUTC(date: string, now?: Date, calendar?: CalendarSystem): booleanChecks whether a date string matches today's UTC date.
Pass a Date fixture when SSR, tests, or hydration-sensitive render paths need
deterministic behavior.isTodayUTC, 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 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 renderedAt: DaterenderedAt = new var Date: DateConstructor
new (value: number | string | Date) => Date (+4 overloads)
const date: stringdate = 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 renderedAt: DaterenderedAt)
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(const renderedAt: DaterenderedAt)
const const matches: booleanmatches = function isTodayUTC(date: string, now?: Date, calendar?: CalendarSystem): booleanChecks whether a date string matches today's UTC date.
Pass a Date fixture when SSR, tests, or hydration-sensitive render paths need
deterministic behavior.isTodayUTC('2036-06-08', const renderedAt: DaterenderedAt)
const date: stringdate // "2036-06-08"
const now: Timestampnow.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 // "23:59:15.250"
const matches: booleanmatches // trueUse UTC conversion when the source is an instant
When your input is a native Date, use parseDateUTC(date, calendar) to read UTC fields. Use parseDate(date, calendar) when you want host-local fields.
import { function getDateTime(timestamp: Timestamp): stringFormats a Timestamp as date plus time.getDateTime, 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 } from '@timestamp-js/core'
const const instant: Dateinstant = new var Date: DateConstructor
new (value: number | string | Date) => Date (+4 overloads)
const timestamp: Timestamp | nulltimestamp = 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)
function getDateTime(timestamp: Timestamp): stringFormats a Timestamp as date plus time.getDateTime(const timestamp: Timestamp | nulltimestamp!) // "2026-06-08 09:30"Pass locales explicitly
Intl.DateTimeFormat can use the host default locale. Pass a locale when labels are rendered on both server and client.
import { function getMonthNames(type: string, locale: string): string[]Retrieves localized month names.getMonthNames, function getWeekdayNames(type: string, locale: string): string[]Retrieves localized weekday names.getWeekdayNames } from '@timestamp-js/core'
const const weekdays: string[]weekdays = function getWeekdayNames(type: string, locale: string): string[]Retrieves localized weekday names.getWeekdayNames('long', 'en-US')
const const months: string[]months = function getMonthNames(type: string, locale: string): string[]Retrieves localized month names.getMonthNames('long', 'en-US')
const weekdays: string[]weekdays[0] // "Sunday"
const months: string[]months[0] // "January"Test with injected dates
Tests are more stable when the current date is an explicit fixture.
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, 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 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-08')!
const 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('2026-06-07')!
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).Timestamp.past?: boolean | undefinedTrue when the timestamp is before a comparison timestamp.past // true