Quick Start || Timestamp

Timestamp

v1.0.0

Quick Start

Getting Started

This page covers the core Timestamp workflows most applications need first. The examples use @timestamp-js/core; optional calendar adapters use the same helper surface when you want adapter-native date fields.

Install

pnpm

bun

yarn

npm

pnpm add @timestamp-js/core

Timestamp is ESM, side-effect free, and ships TypeScript declarations.

Parse a date

parseTimestamp() turns a date or date-time string into an immutable Timestamp object.

import { parseTimestamp } from '@timestamp-js/core'

const timestamp = parseTimestamp('2026-06-08 09:30')

timestamp?.date // '2026-06-08'
timestamp?.time // '09:30'
timestamp?.weekday // 1

Supported input includes date-only strings, space-separated date/time strings, ISO-style T separators, optional seconds, optional milliseconds, and optional timezone suffixes.

Get today

Use host-local helpers when the current runtime timezone should decide the date. Use UTC helpers when SSR, SSG, tests, or server/client parity need stable UTC fields.

import { nowUTC, today, todayUTC } from '@timestamp-js/core'

const localDate = today()
const utcDate = todayUTC()
const utcTimestamp = nowUTC()

For deterministic rendering, pass the Date source yourself:

import { nowUTC } from '@timestamp-js/core'

const renderedAt = new Date('2026-06-08T12:00:00.000Z')
const now = nowUTC(renderedAt)

Store a shared meeting time

Use instant helpers when users in different timezones should see the same meeting in their own local time. Convert the selected wall-clock time into UTC for storage, then convert it back for each viewer.

import { fromInstant, parseTimestamp, toInstant } from '@timestamp-js/core'

const selected = parseTimestamp('2026-07-03 09:00')!
const stored = toInstant(selected, 'America/Edmonton')

stored // '2026-07-03T15:00:00.000Z'
fromInstant(stored!, 'Europe/London')?.time // '16:00'

Invalid IANA timezone names and daylight-saving gaps return null, which lets forms reject times that cannot become a real UTC instant. When a fall-back transition repeats a local time, Timestamp chooses the earlier matching instant.

Format fields

Timestamp stores common formatted values directly on the object, and helper functions return the string forms used by UI components, routes, and storage keys.

import { getDate, getDateTime, getTime, parseTimestamp } from '@timestamp-js/core'

const timestamp = parseTimestamp('2026-06-08 09:30')!

getDate(timestamp) // '2026-06-08'
getTime(timestamp) // '09:30'
getDateTime(timestamp) // '2026-06-08 09:30'

Do date math

Timestamp helpers return new frozen objects. The original timestamp is not mutated.

import { addToDate, addToDateClamped, nextDay, parseTimestamp, prevDay } from '@timestamp-js/core'

const start = parseTimestamp('2026-01-31')!

nextDay(start).date // '2026-02-01'
prevDay(start).date // '2026-01-30'
addToDate(start, { month: 1 }).date // '2026-03-03'
addToDateClamped(start, { month: 1 }).date // '2026-02-28'

Use addToDateClamped() for month-end workflows where the result should stay inside the target month.

Create a day list

Calendar-style views often need a list of immutable day objects.

import { createDayList, parseTimestamp } from '@timestamp-js/core'

const start = parseTimestamp('2026-06-01')!
const end = parseTimestamp('2026-06-07')!

const days = createDayList(start, end)

days.map((day) => day.date)
// [
//   '2026-06-01',
//   '2026-06-02',
//   '2026-06-03',
//   '2026-06-04',
//   '2026-06-05',
//   '2026-06-06',
//   '2026-06-07',
// ]

Use a calendar adapter

Gregorian is the default. Pass a CalendarSystem when date fields should be native to another calendar.

pnpm

bun

yarn

npm

pnpm add @timestamp-js/core @timestamp-js/calendar-islamic

import {
  getCalendarDirection,
  getCalendarWeekdays,
  parseCalendarTimestamp,
  today,
} from '@timestamp-js/core'
import { islamicCivilCalendar } from '@timestamp-js/calendar-islamic'

const visible = parseCalendarTimestamp('1445-09-15', islamicCivilCalendar)!
const currentHijriDate = today(islamicCivilCalendar)

visible.calendarId // 'islamic-civil'
visible.date // '1445-09-15'
currentHijriDate // current date in Islamic civil fields
getCalendarDirection(islamicCivilCalendar) // 'rtl'
getCalendarWeekdays(islamicCivilCalendar) // [6, 0, 1, 2, 3, 4, 5]

Adapter presentation defaults are recommendations. Components can use them when an app omits locale, dir, or weekdays, and the app can still override them for another language, direction, or a five-day work week.

Build adapter-native ranges

Use calendar-aware helpers when input and output dates belong to an adapter.

import {
  createCalendarDayList,
  getCalendarEndOfWeek,
  getCalendarStartOfWeek,
  getCalendarWeekdays,
  parseCalendarTimestamp,
} from '@timestamp-js/core'
import { islamicCivilCalendar } from '@timestamp-js/calendar-islamic'

const visible = parseCalendarTimestamp('1445-09-15', islamicCivilCalendar)!
const weekdays = getCalendarWeekdays(islamicCivilCalendar)

const weekStart = getCalendarStartOfWeek(visible, weekdays, islamicCivilCalendar)
const weekEnd = getCalendarEndOfWeek(visible, weekdays, islamicCivilCalendar)
const days = createCalendarDayList(weekStart, weekEnd, visible, islamicCivilCalendar)

weekStart.date // '1445-09-14'
weekEnd.date // '1445-09-20'
days.length // 7

Browser global usage

For CodePen-style usage, load the IIFE bundle and read helpers from the global object.

<script src="https://cdn.jsdelivr.net/npm/@timestamp-js/core@latest/dist/index.global.min.js"></script>
<script>
  const timestamp = TimestampJsCore.parseTimestamp('2026-06-08')

  console.log(timestamp?.date)
</script>