The @timestamp-js/calendar-persian package exports persianCalendar, with jalaliCalendar as a convenience alias. It models the deterministic civil Persian/Jalali calendar.

Package

import { gregorianCalendar } from '@timestamp-js/core'
import { persianCalendar } from '@timestamp-js/calendar-persian'

const nowruz = { year: 1403, month: 1, day: 1 }
const gregorian = gregorianCalendar.fromEpochDay(persianCalendar.toEpochDay(nowruz))

gregorian // { year: 2024, month: 3, day: 20 }

Calendar Rules

Timestamp uses Persian civil month numbering:

• 1 is Farvardin.
• 6 is Shahrivar.
• 7 is Mehr.
• 12 is Esfand.
• Leap years give Esfand 30 days instead of 29.

The Persian adapter recommends fa-IR, right-to-left presentation, and Saturday-through-Friday visible weeks. Apps can still pass their own locale, direction, or weekday order.

Adapter-Aware Integration

When the adapter is used by calendar, picker, or scheduling UI, pass it through as the active calendar system for views that should behave as native Persian calendars. Date-bearing values should be Persian when the adapter is active, while Gregorian interop metadata can remain available for storage, export, and debugging boundaries.

QCalendar is one adapter-aware consumer. Its adapter guide explains the integration boundary, outside-day behavior, and native month navigation:

Using Timestamp adapters with QCalendar

Calendar Ranges

Use the adapter-aware helpers when you need native Persian weeks or months: