Use this guide when upgrading from an embedded Timestamp utility, copied source helper, or UI-package re-export to the standalone @timestamp-js/core package.

Timestamp 1.0.0 is the first stable release. The documented public API follows semantic versioning.

Install Timestamp Directly

Add @timestamp-js/core to your application dependencies. Do not rely on QCalendar, QScroller, or another UI package to provide Timestamp helpers for your app code.

pnpm add @timestamp-js/core

Import From The Standalone Package

Replace UI-package-owned or source-path Timestamp imports with direct @timestamp-js/core imports.

 // Before: your app imported Timestamp helpers from a UI package or source utility path.
-import { parseTimestamp, today } from '@quasar/quasar-ui-qcalendar'
-import { parseTimestamp, today } from '@quasar/quasar-ui-qcalendar/src/utils/Timestamp'
 
 // After: your app owns the dependency explicitly.
+import { parseTimestamp, today } from '@timestamp-js/core'

Import types from the same package:

import type { Timestamp, TimeObject, DisabledDay } from '@timestamp-js/core'

Adjust For Immutability

The standalone package treats Timestamp objects as immutable values. Parsers and update helpers return frozen objects, and date math returns a new Timestamp instead of changing the input.

If older application code changed fields directly, switch to helper functions or create a copied value.

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

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

// Prefer date math helpers when changing calendar fields.
const nextMonth = addToDate(current, { month: 1 })

// Use copyTimestamp() when you need a manual field replacement.
const firstOfMonth = copyTimestamp({ ...current, day: 1 })

Avoid mutation-style code:

const current = parseTimestamp('2026-06-08')!

// Avoid this. Timestamp objects are immutable.
current.day = 1

Keep Component Values Separate

UI components can pass timestamp-shaped slot, event, or model values where their component API documents them. Treat those objects as component data. If app-level code needs reusable date/time utilities, parse or copy values with @timestamp-js/core instead of importing helpers through a component package.

import { copyTimestamp, type Timestamp } from '@timestamp-js/core'

function useSlotTimestamp(timestamp: Timestamp): Timestamp {
  return copyTimestamp(timestamp)
}

Parsing Differences To Know

The standalone package keeps the familiar calendar-style inputs and adds fuller ISO-like input support:

• 2026-06-08
• 2026-06-08 09:30
• 2026-06-08T09:30
• 2026-06-08T09:30:15
• 2026-06-08T09:30:15.250Z
• 2026-06-08T09:30:15.250-07:00

Seconds, milliseconds, and timezone suffixes are optional. Timezone suffixes are preserved, but the parser does not convert wall-clock values into another timezone.

Migration Checklist

• Prefer importing from @timestamp-js/core.
• Treat Timestamp objects as immutable values.
• Use parser and date math helpers instead of mutating fields manually.
• Add @timestamp-js/core as a direct dependency in every app or package that uses Timestamp helpers.
• Review tests that assumed mutation because helpers now return new immutable objects.
• Review SSR-sensitive code that calls today() during render. Prefer explicit input values, todayUTC(), or nowUTC() when server/client timezone differences matter.
• Review the release notes when upgrading for timezone, UTC, calendar-system, and API changes.

Public API Stability

The 1.0.0 review retained the complete documented API surface for QCalendar, QScroller, and standalone consumers. Existing Gregorian helper names and defaults remain compatible, while explicitly named calendar helpers provide adapter-native behavior without changing those defaults.

Some exports intentionally overlap:

• parsed() is the documented low-level parser; parseTimestamp() also fills derived fields.
• Existing Gregorian helpers remain the convenient default; *Calendar* helpers make adapter-native intent explicit.
• moveRelativeDays() is retained as a compatibility alias for relativeDays().
• Frozen Timestamp and TimeObject templates, parsing expressions, calendar constants, and unit constants remain public because downstream integrations already consume the legacy utility surface.

Changing or removing a documented export requires a major release. Additive public API may ship in minor releases, and compatible fixes may ship in patch releases.