Timestamp
v0.1.0-rc.5
Getting Started
Introduction
Installation
Quick Start
Parsing
Immutability
SSR
Immutability

Timestamp objects are immutable. Parsers and update helpers return frozen objects, and functions that change fields return a new Timestamp instead of mutating the original.

import { function addToDate(timestamp: Timestamp, options: AddToDateOptions, calendar?: CalendarSystem): Timestamp
Adds or subtracts date/time units from a timestamp.

This function returns a new frozen Timestamp; it does not mutate the
timestamp passed in. Gregorian dates are normalized through JavaScript Date
rules. Adapter-native dates use the supplied calendar system for year,
month, and day math.
@paramtimestamp Timestamp object to offset.@paramoptions Date/time units to add or subtract.@paramoptions.year If positive, adds years. If negative, removes years.@paramoptions.month If positive, adds months. If negative, removes month.@paramoptions.day If positive, adds days. If negative, removes days.@paramoptions.hour If positive, adds hours. If negative, removes hours.@paramoptions.minute If positive, adds minutes. If negative, removes minutes.@paramoptions.second If positive, adds seconds. If negative, removes seconds.@paramoptions.millisecond If positive, adds milliseconds. If negative, removes milliseconds.@paramcalendar Calendar system to use. Defaults to Gregorian; pass an adapter such as islamicCivilCalendar for native calendar fields.@returnsNew normalized Timestamp object.@categoryarithmetic
addToDate, function parseTimestamp(input: string, now?: Timestamp | null): Timestamp | null
Converts 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.@categoryparsing
parseTimestamp } from '@timestamp-js/core'

const const start: Timestampstart = function parseTimestamp(input: string, now?: Timestamp | null): Timestamp | null
Converts 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.@categoryparsing
parseTimestamp('2026-06-08 09:30')!
const const next: Timestampnext = function addToDate(timestamp: Timestamp, options: AddToDateOptions, calendar?: CalendarSystem): Timestamp
Adds or subtracts date/time units from a timestamp.

This function returns a new frozen Timestamp; it does not mutate the
timestamp passed in. Gregorian dates are normalized through JavaScript Date
rules. Adapter-native dates use the supplied calendar system for year,
month, and day math.
@paramtimestamp Timestamp object to offset.@paramoptions Date/time units to add or subtract.@paramoptions.year If positive, adds years. If negative, removes years.@paramoptions.month If positive, adds months. If negative, removes month.@paramoptions.day If positive, adds days. If negative, removes days.@paramoptions.hour If positive, adds hours. If negative, removes hours.@paramoptions.minute If positive, adds minutes. If negative, removes minutes.@paramoptions.second If positive, adds seconds. If negative, removes seconds.@paramoptions.millisecond If positive, adds milliseconds. If negative, removes milliseconds.@paramcalendar Calendar system to use. Defaults to Gregorian; pass an adapter such as islamicCivilCalendar for native calendar fields.@returnsNew normalized Timestamp object.@categoryarithmetic
addToDate(const start: Timestampstart, { AddToDateOptions.day?: number | undefined
Number of days to add or subtract.
day: 1 })
const const lastYear: TimestamplastYear = function addToDate(timestamp: Timestamp, options: AddToDateOptions, calendar?: CalendarSystem): Timestamp
Adds or subtracts date/time units from a timestamp.

This function returns a new frozen Timestamp; it does not mutate the
timestamp passed in. Gregorian dates are normalized through JavaScript Date
rules. Adapter-native dates use the supplied calendar system for year,
month, and day math.
@paramtimestamp Timestamp object to offset.@paramoptions Date/time units to add or subtract.@paramoptions.year If positive, adds years. If negative, removes years.@paramoptions.month If positive, adds months. If negative, removes month.@paramoptions.day If positive, adds days. If negative, removes days.@paramoptions.hour If positive, adds hours. If negative, removes hours.@paramoptions.minute If positive, adds minutes. If negative, removes minutes.@paramoptions.second If positive, adds seconds. If negative, removes seconds.@paramoptions.millisecond If positive, adds milliseconds. If negative, removes milliseconds.@paramcalendar Calendar system to use. Defaults to Gregorian; pass an adapter such as islamicCivilCalendar for native calendar fields.@returnsNew normalized Timestamp object.@categoryarithmetic
addToDate(const start: Timestampstart, { AddToDateOptions.year?: number | undefined
Number of years to add or subtract.
year: -1 })

var console: Consoleconsole.Console.log(...data: any[]): void
The **`console.log()`** static method outputs a message to the console.

[MDN Reference](https://developer.mozilla.org/docs/Web/API/console/log_static)
log(const start: Timestampstart.Timestamp.date: string
Date string in `YYYY-MM-DD` form when the timestamp has a day.
date) // 2026-06-08
var console: Consoleconsole.Console.log(...data: any[]): void
The **`console.log()`** static method outputs a message to the console.

[MDN Reference](https://developer.mozilla.org/docs/Web/API/console/log_static)
log(const next: Timestampnext.Timestamp.date: string
Date string in `YYYY-MM-DD` form when the timestamp has a day.
date) // 2026-06-09
var console: Consoleconsole.Console.log(...data: any[]): void
The **`console.log()`** static method outputs a message to the console.

[MDN Reference](https://developer.mozilla.org/docs/Web/API/console/log_static)
log(const lastYear: TimestamplastYear.Timestamp.date: string
Date string in `YYYY-MM-DD` form when the timestamp has a day.
date) // 2025-06-08

Calendar math normalizes through JavaScript date rules by default. For example, addToDate() with one year added to a leap-day value such as 2020-02-29 produces 2021-03-01, because February 29 does not exist in 2021.

Use addToDateClamped() when month-end workflows should stay inside the target month:

import { function addToDateClamped(timestamp: Timestamp, options: AddToDateOptions, calendar?: CalendarSystem): Timestamp
Adds or subtracts date/time units from a timestamp while clamping invalid
target month days to the last valid day in the target month.

This helper is useful for calendar and billing workflows where adding one
month to January 31 should produce February 28/29 instead of rolling into
March. Day and time offsets still use normal JavaScript Date normalization
after the year/month clamp is applied.

This function returns a new frozen Timestamp; it does not mutate the
timestamp passed in.
@paramtimestamp Timestamp object to offset.@paramoptions Date/time units to add or subtract.@paramoptions.year If positive, adds years. If negative, removes years.@paramoptions.month If positive, adds months. If negative, removes month.@paramoptions.day If positive, adds days. If negative, removes days.@paramoptions.hour If positive, adds hours. If negative, removes hours.@paramoptions.minute If positive, adds minutes. If negative, removes minutes.@paramoptions.second If positive, adds seconds. If negative, removes seconds.@paramoptions.millisecond If positive, adds milliseconds. If negative, removes milliseconds.@paramcalendar Calendar system to use. Defaults to Gregorian; pass an adapter such as islamicCivilCalendar for native calendar fields.@returnsNew normalized Timestamp object.@categoryarithmetic
addToDateClamped, function parseTimestamp(input: string, now?: Timestamp | null): Timestamp | null
Converts 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.@categoryparsing
parseTimestamp } from '@timestamp-js/core'

const const leapDay: TimestampleapDay = function parseTimestamp(input: string, now?: Timestamp | null): Timestamp | null
Converts 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.@categoryparsing
parseTimestamp('2020-02-29')!
const const renewalDate: TimestamprenewalDate = function addToDateClamped(timestamp: Timestamp, options: AddToDateOptions, calendar?: CalendarSystem): Timestamp
Adds or subtracts date/time units from a timestamp while clamping invalid
target month days to the last valid day in the target month.

This helper is useful for calendar and billing workflows where adding one
month to January 31 should produce February 28/29 instead of rolling into
March. Day and time offsets still use normal JavaScript Date normalization
after the year/month clamp is applied.

This function returns a new frozen Timestamp; it does not mutate the
timestamp passed in.
@paramtimestamp Timestamp object to offset.@paramoptions Date/time units to add or subtract.@paramoptions.year If positive, adds years. If negative, removes years.@paramoptions.month If positive, adds months. If negative, removes month.@paramoptions.day If positive, adds days. If negative, removes days.@paramoptions.hour If positive, adds hours. If negative, removes hours.@paramoptions.minute If positive, adds minutes. If negative, removes minutes.@paramoptions.second If positive, adds seconds. If negative, removes seconds.@paramoptions.millisecond If positive, adds milliseconds. If negative, removes milliseconds.@paramcalendar Calendar system to use. Defaults to Gregorian; pass an adapter such as islamicCivilCalendar for native calendar fields.@returnsNew normalized Timestamp object.@categoryarithmetic
addToDateClamped(const leapDay: TimestampleapDay, { AddToDateOptions.year?: number | undefined
Number of years to add or subtract.
year: 1 })

var console: Consoleconsole.Console.log(...data: any[]): void
The **`console.log()`** static method outputs a message to the console.

[MDN Reference](https://developer.mozilla.org/docs/Web/API/console/log_static)
log(const renewalDate: TimestamprenewalDate.Timestamp.date: string
Date string in `YYYY-MM-DD` form when the timestamp has a day.
date) // 2021-02-28

Manual copies

Use copyTimestamp() when you need to derive a value manually.

import { function copyTimestamp(timestamp: Timestamp): Timestamp
Returns an immutable copy of a Timestamp object.
@paramtimestamp Timestamp object to copy.@returnsFrozen Timestamp copy.@categorystate
copyTimestamp, function parseTimestamp(input: string, now?: Timestamp | null): Timestamp | null
Converts 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.@categoryparsing
parseTimestamp } from '@timestamp-js/core'

const const original: Timestamporiginal = function parseTimestamp(input: string, now?: Timestamp | null): Timestamp | null
Converts 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.@categoryparsing
parseTimestamp('2026-05-30')!
const const firstOfMonth: TimestampfirstOfMonth = function copyTimestamp(timestamp: Timestamp): Timestamp
Returns an immutable copy of a Timestamp object.
@paramtimestamp Timestamp object to copy.@returnsFrozen Timestamp copy.@categorystate
copyTimestamp({ ...const original: Timestamporiginal, Timestamp.day: number
Calendar day of the month.
day: 1 })

var console: Consoleconsole.Console.log(...data: any[]): void
The **`console.log()`** static method outputs a message to the console.

[MDN Reference](https://developer.mozilla.org/docs/Web/API/console/log_static)
log(const original: Timestamporiginal.Timestamp.day: number
Calendar day of the month.
day) // 30
var console: Consoleconsole.Console.log(...data: any[]): void
The **`console.log()`** static method outputs a message to the console.

[MDN Reference](https://developer.mozilla.org/docs/Web/API/console/log_static)
log(const firstOfMonth: TimestampfirstOfMonth.Timestamp.day: number
Calendar day of the month.
day) // 1

Why immutability matters

Immutability helps avoid accidental shared-state bugs in:

  • Reactive UI state
  • SSR and hydration
  • Test fixtures
  • Calendar range generation
  • Shared utility functions used by multiple consumers
Ready for more?
Getting Started
Parsing
Getting Started
SSR
Caught a mistake?Edit this page in browser
1. Introduction
2. Manual copies
3. Why immutability matters
MIT License
Copyright (c) Jeff Galbraith
MITPrivacy