PersianDate vs. Gregorian: Converting Dates Easily

Mastering PersianDate: A Complete Guide for Developers

What is PersianDate?

PersianDate is a JavaScript library that provides robust support for the Persian (Jalali) calendar: parsing, formatting, converting between Persian and Gregorian dates, and common date arithmetic. It’s designed for web and Node.js environments where Persian-language or Iran-centric date handling is required.

When to use it

• Building interfaces for Persian-speaking users.
• Handling cultural date formats (e.g., 1404/01/01).
• Converting stored Gregorian dates to display in Jalali.
• Scheduling, reporting, or logging where Persian calendar semantics matter.

Installation

Use npm or yarn:

bash
Copy CodeCopied
npm install persian-date # or
yarn add persian-date 

Basic usage

javascript
Copy CodeCopied
const persianDate = require(‘persian-date’); // CommonJS
// or
import persianDate from ‘persian-date’; // ESM

const pd = new persianDate(); // now in local time
console.log(pd.format(‘YYYY/MM/DD’)); // e.g., “1404/12/16”

Creating dates

• From components:

javascript
Copy CodeCopied
const pd = new persianDate([1404, 0, 1]); // year, monthIndex (0-based), day

• From Gregorian date:

javascript
Copy CodeCopied
const pdFromG = new persianDate(new Date(‘2026-03-07’));

• From timestamp:

javascript
Copy CodeCopied
const pdFromTs = new persianDate(1678166400000);

Formatting patterns

Common tokens:

• YYYY — 4-digit Persian year
• MM — 2-digit month
• DD — 2-digit day
• dddd — weekday name
• HH:mm:ss — 24-hour time

Example:

javascript
Copy CodeCopied
pd.format(‘dddd, D MMMM YYYY HH:mm’); // “شنبه, 16 اسفند 1404 14:30”

Parsing strings

javascript
Copy CodeCopied
const pd = persianDate.fromString(‘1404/01/01’, ‘YYYY/MM/DD’);

Conversions

• To Gregorian Date:

javascript
Copy CodeCopied
const greg = pd.toDate(); // JavaScript Date in Gregorian

• From Gregorian to Persian:

javascript
Copy CodeCopied
const pd2 = new persianDate(new Date());

Date arithmetic

javascript
Copy CodeCopied
pd.add(1, ‘month’);
pd.subtract(10, ‘day’);
const diff = pd.diff(new persianDate(‘1404/01/01’), ‘day’);

Timezones

persian-date uses local JS Date timezone. For server-side or multi-timezone apps, convert to/from UTC explicitly:

javascript
Copy CodeCopied
const utc = new Date(Date.UTC(2026, 2, 7));
const pdUtc = new persianDate(utc);

Integration with UI libraries

• Use formatted strings for display in components (React, Vue).
• For date pickers, convert user-selected Jalali values to Gregorian before storing.
• Example with a React input:

javascript
Copy CodeCopied
function onSelect(jalaliArray) {
const pd = new persianDate(jalaliArray);
  const greg = pd.toDate();
  save(greg.toISOString());
}

Testing tips

• Include unit tests that verify conversion edge cases (end/start of leap years).
• Mock timezones when comparing formatted outputs.
• Test parsing for multiple input formats.

Performance and bundle size

• Import only what you need where possible.
• Consider server-side conversion if many clients request date-heavy pages.

Common pitfalls

• Months may be 0-based in some constructors; check the API.
• Be explicit about timezone when storing dates (prefer ISO UTC strings).
• Validate input formats before parsing to avoid exceptions.

Alternatives

• moment-jalaali: extends moment.js for Jalali