SSR And Runtime || Timestamp

Timestamp

v0.1.0-rc.0

SSR And Runtime

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`.
@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 updateRelative(timestamp: Timestamp, now: Timestamp, time?: boolean): 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.
@paramtimestamp Timestamp object to update.@paramnow Timestamp representing the comparison point.@paramtime Include time-of-day in the comparison when true.@returnsNew Timestamp object with relative flags.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`.
@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')!
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`.
@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-10')!

const const stable: Timestampstable = function updateRelative(timestamp: Timestamp, now: Timestamp, time?: boolean): 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.
@paramtimestamp Timestamp object to update.@paramnow Timestamp representing the comparison point.@paramtime Include time-of-day in the comparison when true.@returnsNew Timestamp object with relative flags.updateRelative(const event: Timestampevent, const renderedNow: TimestamprenderedNow)

const stable: Timestampstable.Timestamp.future?: boolean | undefinedTrue when the timestamp is after a comparison timestamp.future // true

Use today checks outside hydration-sensitive render paths

today() and isToday() 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.

import { function isToday(date: string): booleanTakes a date string ('YYYY-MM-DD') and validates if it is today's date
@paramdate Date string in the form 'YYYY-MM-DD'@returnsTrue if the date is today's dateisToday, function today(): 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.
@returnsDate string in the form `YYYY-MM-DD`today } from '@timestamp-js/core'

const const currentDate: stringcurrentDate = function today(): 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.
@returnsDate string in the form `YYYY-MM-DD`today()

function isToday(date: string): booleanTakes a date string ('YYYY-MM-DD') and validates if it is today's date
@paramdate Date string in the form 'YYYY-MM-DD'@returnsTrue if the date is today's dateisToday(const currentDate: stringcurrentDate) // true

Use UTC helpers when the app wants UTC calendar fields

todayUTC() returns a UTC date string. nowUTC() 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.

import { function isTodayUTC(date: string, now?: Date): 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.
@paramdate Date string in the form `YYYY-MM-DD`.@paramnow Date source to read. Defaults to the current Date.@returnsTrue when the date matches the UTC date.isTodayUTC, function nowUTC(date?: Date): 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.
@paramdate Date source to read. Defaults to the current Date.@returnsImmutable Timestamp built from UTC fields.nowUTC, function todayUTC(date?: Date): 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.
@paramdate Date source to read. Defaults to the current Date.@returnsUTC date string in the form `YYYY-MM-DD`todayUTC } from '@timestamp-js/core'

const const renderedAt: DaterenderedAt = new var Date: DateConstructor
new (value: number | string | Date) => Date (+4 overloads)Date('2036-06-08T23:59:15.250Z')
const const date: stringdate = function todayUTC(date?: Date): 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.
@paramdate Date source to read. Defaults to the current Date.@returnsUTC date string in the form `YYYY-MM-DD`todayUTC(const renderedAt: DaterenderedAt)
const const now: Timestampnow = function nowUTC(date?: Date): 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.
@paramdate Date source to read. Defaults to the current Date.@returnsImmutable Timestamp built from UTC fields.nowUTC(const renderedAt: DaterenderedAt)
const const matches: booleanmatches = function isTodayUTC(date: string, now?: Date): 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.
@paramdate Date string in the form `YYYY-MM-DD`.@paramnow Date source to read. Defaults to the current Date.@returnsTrue when the date matches the UTC date.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 // true

Use UTC conversion when the source is an instant

When your input is a native Date, use parseDateUTC() to read UTC fields. Use parseDate() when you want host-local fields.

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

function getDateTime(timestamp: Timestamp): stringFormats a Timestamp as date plus time.
@paramtimestamp Timestamp object to format.@returnsDate-time string such as `YYYY-MM-DD HH:mm`.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.
@paramtype Format type: `narrow`, `short`, or `long`.@paramlocale Locale to use for formatting, such as `en-US`.@returnsLocalized month names in January-first order.getMonthNames, function getWeekdayNames(type: string, locale: string): string[]Retrieves localized weekday names.
@paramtype Format type: `narrow`, `short`, or `long`.@paramlocale Locale to use for formatting, such as `en-US`.@returnsLocalized weekday names in Sunday-first order.getWeekdayNames } from '@timestamp-js/core'

const const weekdays: string[]weekdays = function getWeekdayNames(type: string, locale: string): string[]Retrieves localized weekday names.
@paramtype Format type: `narrow`, `short`, or `long`.@paramlocale Locale to use for formatting, such as `en-US`.@returnsLocalized weekday names in Sunday-first order.getWeekdayNames('long', 'en-US')
const const months: string[]months = function getMonthNames(type: string, locale: string): string[]Retrieves localized month names.
@paramtype Format type: `narrow`, `short`, or `long`.@paramlocale Locale to use for formatting, such as `en-US`.@returnsLocalized month names in January-first order.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`.
@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 updateRelative(timestamp: Timestamp, now: Timestamp, time?: boolean): 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.
@paramtimestamp Timestamp object to update.@paramnow Timestamp representing the comparison point.@paramtime Include time-of-day in the comparison when true.@returnsNew Timestamp object with relative flags.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`.
@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 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`.
@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-07')!

function updateRelative(timestamp: Timestamp, now: Timestamp, time?: boolean): 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.
@paramtimestamp Timestamp object to update.@paramnow Timestamp representing the comparison point.@paramtime Include time-of-day in the comparison when true.@returnsNew Timestamp object with relative flags.updateRelative(const target: Timestamptarget, const now: Timestampnow).Timestamp.past?: boolean | undefinedTrue when the timestamp is before a comparison timestamp.past // true

Ready for more?

Caught a mistake?Edit this page in browser

1. Introduction

2. Prefer explicit inputs during render

3. Use today checks outside hydration-sensitive render paths

4. Use UTC helpers when the app wants UTC calendar fields

5. Use UTC conversion when the source is an instant

6. Pass locales explicitly

7. Test with injected dates