Installation || Timestamp

Timestamp

v0.1.0-rc.5

Installation

Install the core package from npm:

Install the package

Add @timestamp-js/core with your preferred package manager.

pnpm

bun

yarn

npm

pnpm add @timestamp-js/core

Import only the helpers you need

The package is ESM, side-effect free, and designed for tree-shaking. Prefer named imports so bundlers can keep only the helpers your app actually uses.

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.@categoryparsingparseTimestamp, 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.
@paramcalendar Calendar system to use. Defaults to Gregorian; pass an adapter such as islamicCivilCalendar for native calendar fields.@returnsDate string in the form `YYYY-MM-DD`@categorystatetoday, type const Timestamp: TimestampImmutable timestamp data used by all parser, comparison, and date math helpers.

Core parser helpers produce Gregorian calendar fields and preserve optional
ISO timezone suffixes without converting the wall-clock values into another
zone. Calendar adapter helpers can also produce timestamp-shaped values whose
year/month/day fields belong to the adapter identified by `calendarId`.


Frozen empty timestamp template.

Use copyTimestamp or parser helpers to create new timestamp objects
instead of mutating this shared default.Timestamp } from '@timestamp-js/core'

const const model: stringmodel = 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.
@paramcalendar Calendar system to use. Defaults to Gregorian; pass an adapter such as islamicCivilCalendar for native calendar fields.@returnsDate string in the form `YYYY-MM-DD`@categorystatetoday()
const const timestamp: Timestamp | nulltimestamp: Timestamp | null = 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(const model: stringmodel)

Confirm the runtime target

Timestamp uses standard JavaScript runtime APIs, so it is suitable for browser, Node.js, SSR, SSG, serverless, and edge-style environments.

Browser globals

Timestamp ships browser-global IIFE bundles for CDN and CodePen-style usage. Load @timestamp-js/core first, then any optional calendar adapters. Use the current package version or a dist tag that matches your release policy.

<script src="https://cdn.jsdelivr.net/npm/@timestamp-js/core@latest/dist/index.global.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/@timestamp-js/calendar-islamic@latest/dist/index.global.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/@timestamp-js/calendar-saka@latest/dist/index.global.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/@timestamp-js/calendar-hebrew@latest/dist/index.global.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/@timestamp-js/calendar-persian@latest/dist/index.global.min.js"></script>
<script>
  const visible = TimestampJsCore.parseCalendarTimestamp(
    '1445-09-15',
    TimestampJsCalendarIslamic.islamicCivilCalendar,
  )

  console.log(visible?.calendarId)
</script>

The globals are TimestampJsCore, TimestampJsCalendarIslamic, TimestampJsCalendarSaka, TimestampJsCalendarHebrew, and TimestampJsCalendarPersian.

Runtime support

Timestamp targets modern JavaScript runtimes. It uses standard APIs such as Date and Intl.DateTimeFormat, and it avoids browser-only globals.

That makes it suitable for:

Browser applications
Node.js applications
Server-rendered applications
Static-site generation
Serverless and edge-style runtimes that provide Date and Intl

TypeScript

Types are shipped with the package and are available from the main export:

import type { const Timestamp: TimestampImmutable timestamp data used by all parser, comparison, and date math helpers.

Core parser helpers produce Gregorian calendar fields and preserve optional
ISO timezone suffixes without converting the wall-clock values into another
zone. Calendar adapter helpers can also produce timestamp-shaped values whose
year/month/day fields belong to the adapter identified by `calendarId`.


Frozen empty timestamp template.

Use copyTimestamp or parser helpers to create new timestamp objects
instead of mutating this shared default.Timestamp, const TimeObject: TimeObjectTime-only value used when callers need hour/minute input without a date.


Frozen empty time-object template.TimeObject, type DisabledDay = string | string[] | DisabledDayConfigSupported disabled-day declaration.

A string disables a single date, a string array disables multiple dates or
an inclusive two-date range, and an object can carry display metadata.DisabledDay } from '@timestamp-js/core'

Ready for more?

Caught a mistake?Edit this page in browser

1. Introduction

2. Browser globals

3. Runtime support

4. TypeScript