@se-oss/jalaali is a modern, lightweight, and tree-shakable Jalaali (Persian) calendar library for TypeScript and JavaScript, featuring a chainable API and native Intl support.

• Installation
• Usage
• Documentation
• Contributing
• License

📦 Installation

pnpm add @se-oss/jalaali

npm

npm install @se-oss/jalaali

yarn

yarn add @se-oss/jalaali

📖 Usage

Basic Usage

Chainable API for intuitive date manipulation and formatting.

import { jalaali } from '@se-oss/jalaali';

const date = jalaali('2023-10-27');
console.log(date.format('YYYY/MM/DD')); // 1402/08/05

The JalaaliDate Class

The core of the library is the JalaaliDate class, which extends the native Date. This offers seamless interoperability with existing libraries (logging, ORMs, etc.) while providing high-performance Jalaali features.

import { jalaali, JalaaliDate } from '@se-oss/jalaali';

// Factory function returns a JalaaliDate instance
const date = jalaali('2023-10-27');

// Direct instantiation (Jalaali year, month, day)
const d2 = new JalaaliDate(1402, 8, 5);

// Parsing from a custom format
const d3 = JalaaliDate.fromFormat('1402-08-05 14:30', 'YYYY-MM-DD HH:mm');

console.log(date instanceof Date); // true
console.log(date.jy); // 1402

Advanced Formatting

Support for localized month names and weekdays using native Intl.

const date = jalaali('2023-03-21');
console.log(date.format('D MMMM dddd')); // ۱ فروردین Tuesday

Holidays

Detect Iran's official holidays and events (including dynamic religious holidays for the current year).

// Access the full list of events
import { CALENDAR_EVENTS } from '@se-oss/jalaali';

const date = jalaali({ jy: 1404, jm: 1, jd: 1 });
console.log(date.isHoliday()); // true (Nowruz)

console.log(CALENDAR_EVENTS[0]); // { month: 1, day: 1, title: '...', is_holiday: true }

Date Arithmetic

Manipulation that respects Jalaali month lengths and leap years. Note: add() mutates the instance to match native Date behavior. Use .clone() for immutable-style operations.

const date = jalaali({ jy: 1402, jm: 6, jd: 31 });
date.add(1, 'month');

console.log(date.format('YYYY/MM/DD')); // 1402/07/30 (Mehr has 30 days)

// Immutable example:
const nextMonth = jalaali({ jy: 1402, jm: 6, jd: 31 }).clone().add(1, 'month');

Advanced Setting

Update multiple components at once using the Luxon-inspired set() API. This method handles complex edge cases like day clamping when changing months.

const date = jalaali();

// Set multiple Jalaali components (chainable)
date.set({ year: 1403, month: 12, hour: 10, minute: 30 });

// Or set Gregorian components
date.set({ gy: 2024, gm: 5, gd: 25 });

Persian Digits

Built-in utility for converting digits to Persian.

import { toPersianDigits } from '@se-oss/jalaali';

console.log(toPersianDigits(1402)); // ۱۴۰۲

Relative Time

Leverage native Intl.RelativeTimeFormat with a simple wrapper.

import { relativeTime } from '@se-oss/jalaali';

console.log(relativeTime(-2, 'day')); // ۲ روز پیش

CLI

Quickly check dates or convert them from your terminal.

# Show today's date (includes holiday status)
npx jalaali today

# Convert Jalaali to Gregorian
npx jalaali convert 1402/08/05

📚 Documentation

For all configuration options and detailed API references, please see the API docs.

🤝 Contributing

Want to contribute? Awesome! To show your support is to star the project, or to raise issues on GitHub.

Thanks again for your support, it is much appreciated! 🙏

License

MIT © Shahrad Elahi and contributors.