Introduction || Timestamp

Timestamp

v0.1.0-rc.5

Introduction

Timestamp is a small TypeScript library for working with immutable date and time objects.

It is not tied to a UI framework, backend framework, or application platform. You can use it in browser apps, Node.js services, SSR applications, static-site builds, tests, and framework-specific libraries.

Design goals

Framework agnostic: works with Vue, React, Svelte, plain TypeScript, Node.js, and other JavaScript runtimes.
Immutable by default: parser and update helpers return frozen Timestamp objects.
Calendar-friendly: date strings, weekday metadata, day-of-year, workweek, interval generation, and range comparison are first-class.
Runtime-safe: no dependency on window, document, storage APIs, or framework state.
Small core: deterministic primitives without full date-library scope.

Basic example

import { function addToDate(timestamp: Timestamp, options: AddToDateOptions, calendar?: CalendarSystem): TimestampAdds 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.@categoryarithmeticaddToDate, 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`.@categoryconversiongetDateTime, 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.@categoryparsingparseTimestamp } from '@timestamp-js/core'

const const start: Timestamp | nullstart = 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.@categoryparsingparseTimestamp('2026-06-08T09:30:15.250Z')
const const end: Timestamp | nullend = const start: Timestamp | nullstart ? function addToDate(timestamp: Timestamp, options: AddToDateOptions, calendar?: CalendarSystem): TimestampAdds 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.@categoryarithmeticaddToDate(const start: Timestampstart, { AddToDateOptions.day?: number | undefinedNumber of days to add or subtract.day: 2, AddToDateOptions.minute?: number | undefinedNumber of minutes to add or subtract.minute: 45 }) : null

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

[MDN Reference](https://developer.mozilla.org/docs/Web/API/console/log_static)log(const end: Timestamp | nullend ? 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`.@categoryconversiongetDateTime(const end: Timestampend) : 'Invalid date')

What Timestamp is not

Timestamp is not trying to replace every date library. It does not currently provide full timezone conversion, duration phrase formatting, or relative phrase formatting. Non-Gregorian calendar support is available through optional adapter packages and is still being proven across adapter-aware calendar and picker workflows.

Ready for more?

Getting Started

Installation

Caught a mistake?Edit this page in browser

1. Introduction

2. Design goals

3. Basic example

4. What Timestamp is not