@mu-utils/persian-date

A modern, high-performance TypeScript/JavaScript library for working with Persian (Jalali / Shamsi) dates. It can be used as a zero-dependency, ultra-lightweight standalone replacement for Day.js / Moment.js, or as a first-class Day.js plugin (jalaliday).

✨ Features

• 🪶 Zero Runtime Dependencies: Ultra-lightweight core with 0 external dependencies.
• 🎯 100% Test Coverage Across All Metrics: 100% Statements, 100% Branches, 100% Functions, and 100% Lines verified.
• ⚡ Why Replace Day.js / Moment with persianDate?:
  • Native Persian-first calculations without requiring bloated plugin chains or Intl timezone workarounds.
  • Zero dependencies vs. Day.js + plugins + locale files.
  • Chainable, intuitive syntax: persianDate('1403/06/12').add(1, 'week').formatFa().
  • Extends native Date: works directly with standard JS APIs, date pickers, React components, and JSON serializers.
• 🔄 Pure Integer Calendar Converters: Direct, ultra-fast gregorianToPersian(gy, gm, gd) and persianToGregorian(jy, jm, jd) without creating Date objects.
• 🔢 Native Persian Digits Support: Convert English digits to Persian (۰-۹) seamlessly with .formatFa() or { digits: "fa" }.
• ⏱️ Relative Time Humanizer (fromNow, toNow, from): Full Persian relative strings ("چند ثانیه پیش", "۳ روز پیش", "یک ماه بعد").
• 📅 Calendar Helpers for Building Real UIs:
  • getDayOfWeek(): Saturday (شنبه) = 0 .. Friday (جمعه) = 6.
  • isWeekend(): Checks if the day is Friday (جمعه).
  • quarter(): Persian quarters (Q1 Farvardin–Khordad to Q4 Dey–Esfand).
  • startOf("week") / endOf("week"): Snap directly to Saturday or Friday.
• 🗓️ Accurate Astronomical Leap Years: Uses the official Iranian 33-year solar cycle (correctly identifies 1403 as a leap year with 30 days in Esfand).

⚔️ Why @mu-utils/persian-date? (Comprehensive Ecosystem Comparison)

If you have used other Persian date libraries in JavaScript or TypeScript, here is how @mu-utils/persian-date compares:

| Feature / Criteria | @mu-utils/persian-date | Day.js + jalaliday | moment-jalaali / jalali-moment | persian-date (babakhani) | date-fns-jalali | | :--- | :---: | :---: | :---: | :---: | :---: | | Dependencies | 0 (Zero Runtime Deps) | Requires Day.js + Plugins | moment (~70 KB minified) | 0 (Legacy JS) | Multiple packages | | Throughput (instantiation) | ~3.8M ops/sec | ~1.9M ops/sec | ~250k ops/sec (Slow) | Untyped & slow | Functional | | 1403 Leap Year Accuracy | ✅ Exact (30 Esfand) | ❌ 1404 bug in many plugins | ❌ 1404 bug in older versions | ❌ Legacy 2820 cycle | ⚠️ Inconsistent | | Extends Native Date | ✅ Yes (instanceof Date) | ❌ No (requires .toDate()) | ❌ No (requires .toDate()) | ❌ No | ❌ Functions only | | Native Persian Digits | ✅ Built-in (formatFa()) | ❌ Requires custom regex | ⚠️ Incomplete | ⚠️ Separate config | ❌ No | | Relative Time Humanizer | ✅ Built-in (fromNow()) | ❌ Extra plugin required | ⚠️ English defaults | ❌ No | ❌ Functional only | | Calendar UI Helpers | ✅ getDayOfWeek, isWeekend | ❌ Manual math | ❌ No | ❌ No | ⚠️ Complex | | Modern TypeScript | ✅ 100% Strict TS + Types | ⚠️ Plugin Augmentation | ⚠️ Deprecated types | ❌ Untyped JS | ✅ Typed | | Test Coverage | 🎯 100% Across All Metrics | ~80% | ~85% | Untested | ~90% |

Key Architectural Advantages

1. Zero Runtime Dependencies vs Heavy Legacy Frameworks:

   • moment-jalaali and jalali-moment drag in the entire Moment.js bundle (>70KB minified and gzipped), which is officially in maintenance mode and discouraged for modern web apps.
   • jalali-plugin-dayjs requires Day.js plus plugin dependencies (utc, timezone, relativeTime, locale files).
   • @mu-utils/persian-date delivers all features out-of-the-box in a single, tree-shakable package with 0 dependencies.

2. 2.1x Faster Instantiation Than Day.js, 38M+ Conversion ops/sec:

   • Benchmarked at over 3.8 million instantiation operations per second vs Day.js's ~1.9M ops/sec, thanks to our pure integer astronomical math engine (no Intl parsing on the hot path).
   • Formatting throughput is in the same range as Day.js (~200–260k ops/sec), with zero plugin overhead.
   • Pure conversion functions (gregorianToPersian / persianToGregorian) run at 22–38 million ops/sec — pure integer math with zero heap allocations.

3. True Native JavaScript Date Integration:

   • Unlike Day.js and Moment which wrap dates in custom class instances, persianDate instanceof Date === true.
   • Passes instanceof Date prop validations in React, Vue, Svelte, Ant Design, Material UI, Shadcn UI, standard HTML <input type="date">, and JSON.stringify() without needing conversions.

4. Fixing the Infamous 1403 vs 1404 Leap Year Bug:

   • Ahmad Birashk's theoretical 2820-year cycle mistakenly placed a leap year at 1404. In reality, Iran's official astronomical calendar determined that 1403 is the leap year (30 days in Esfand) and 1404 has 29 days.
   • Older libraries create off-by-one calendar errors for all dates after March 2024. @mu-utils/persian-date uses the official 33-year solar cycle calculation with astronomical accuracy.

5. Built-in Persian Localization:

   • Direct Persian digits support via .formatFa() or { digits: 'fa' } without string replacement hacks.
   • Built-in humanized relative time (.fromNow(), .toNow()) with natural Persian grammar ("۳ روز پیش", "یک ساعت بعد").

6. Dual Mode for Painless Migration:

   • Use it standalone (persianDate(...)) OR as a Day.js plugin (dayjs.extend(jalaliday)).

🔀 Migration Guides

Migrating from moment-jalaali

// BEFORE (moment-jalaali — 70KB+ bundle, maintenance mode)
import momentJalaali from 'moment-jalaali';
momentJalaali.loadPersian();
const m = momentJalaali('1403/06/12', 'jYYYY/jMM/jDD');
console.log(m.format('jYYYY/jMM/jDD')); // "1403/06/12"
console.log(m.add(10, 'jDay').format('jYYYY/jMM/jDD'));
console.log(m.jDaysInMonth()); // 31

// AFTER (@mu-utils/persian-date — 0 dependencies, 2x faster)
import { persianDate } from '@mu-utils/persian-date';
const d = persianDate('1403/06/12');
console.log(d.format('YYYY/MM/DD'));          // "1403/06/12"
console.log(d.add(10, 'days').format('YYYY/MM/DD'));
console.log(d.daysInMonth());                 // 31

Migrating from Day.js + jalaliday

// BEFORE (Day.js + plugins — requires 3+ packages + locale files)
import dayjs from 'dayjs';
import jalaliday from 'jalali-plugin-dayjs';
import utc from 'dayjs/plugin/utc';
import relativeTime from 'dayjs/plugin/relativeTime';
import fa from 'dayjs/locale/fa';
dayjs.extend(jalaliday).extend(utc).extend(relativeTime);
dayjs.locale('fa');
const d = dayjs('1403/06/12', { jalali: true });
console.log(d.format('YYYY/MM/DD'));
console.log(d.fromNow());

// AFTER (@mu-utils/persian-date — single import, everything built in)
import { persianDate } from '@mu-utils/persian-date';
const d = persianDate('1403/06/12');
console.log(d.format('YYYY/MM/DD'));  // "1403/06/12"
console.log(d.fromNow());            // "۶ ماه پیش" (built-in, no plugin needed)
console.log(d.formatFa());           // "۱۴۰۳/۰۶/۱۲" (Persian digits, built-in)

Migrating from date-fns-jalali

// BEFORE (date-fns-jalali — functional style, no chaining)
import { format, addDays, startOfMonth } from 'date-fns-jalali';
const d = new Date('2024-09-02');
console.log(format(d, 'yyyy/MM/dd'));          // "1403/06/12"
console.log(format(addDays(d, 10), 'yyyy/MM/dd'));
console.log(format(startOfMonth(d), 'yyyy/MM/dd'));

// AFTER (@mu-utils/persian-date — chainable, native Date)
import { persianDate } from '@mu-utils/persian-date';
const d = persianDate('2024-09-02');
console.log(d.format('YYYY/MM/DD'));             // "1403/06/12"
console.log(d.clone().add(10, 'days').format('YYYY/MM/DD'));
console.log(d.clone().startOf('month').format('YYYY/MM/DD'));

📦 Installation

# npm
npm install @mu-utils/persian-date

# yarn
yarn add @mu-utils/persian-date

# pnpm
pnpm add @mu-utils/persian-date

Installing from GitHub Packages

If installing directly from GitHub Packages, add the following to your .npmrc:

@mu-utils:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}

🚀 Converting Persian ↔ Gregorian

1. Pure Integer Converters (Fastest, Zero Allocations)

import { 
  gregorianToPersian, 
  persianToGregorian 
} from "@mu-utils/persian-date";

// Gregorian → Persian [year, month, day]
const [jy, jm, jd] = gregorianToPersian(2024, 9, 2);
console.log(jy, jm, jd); // 1403  6  12

// Persian → Gregorian [year, month, day]
const [gy, gm, gd] = persianToGregorian(1403, 6, 12);
console.log(gy, gm, gd); // 2024  9  2

// Round-trip verification
const [jy2, jm2, jd2] = gregorianToPersian(...persianToGregorian(1403, 6, 12));
console.log(jy2, jm2, jd2); // 1403  6  12  ✅ identical

These run at 10M+ operations per second — pure integer arithmetic with no object allocation.

2. Converting a PersianDate back to Gregorian / Native Date

Because PersianDate extends the native Date, it already is a Gregorian Date object internally. You never need a .toDate() conversion wrapper:

import { persianDate, persianToGregorian } from "@mu-utils/persian-date";

const pd = persianDate(1403, 6, 12);

// Option A: Use as a native Date directly (no conversion needed)
const nativeDate: Date = pd;               // ✅ instanceof Date === true
console.log(nativeDate.toISOString());     // "2024-09-01T20:30:00.000Z" (UTC)
console.log(nativeDate.toLocaleDateString("en-US")); // "9/2/2024"
JSON.stringify({ date: pd });              // works natively

// Option B: Extract Gregorian components via persianToGregorian
const [gy, gm, gd] = persianToGregorian(
  pd.getFullYear(),   // Persian year
  pd.getMonth(),      // Persian month
  pd.getDate()        // Persian day
);
console.log(`${gy}/${String(gm).padStart(2,"0")}/${String(gd).padStart(2,"0")}`); // "2024/09/02"

// Option C: Switch calendar mode in place
const pDate = persianDate("1403/06/12");
pDate.setCalendar("gregorian");
console.log(pDate.format("YYYY/MM/DD")); // "2024/09/02"
pDate.setCalendar("persian");
console.log(pDate.format("YYYY/MM/DD")); // "1403/06/12"

3. Building a Gregorian ISO String from a Persian Date

import { persianDate, persianToGregorian } from "@mu-utils/persian-date";

function persianToISO(jy: number, jm: number, jd: number): string {
  const [gy, gm, gd] = persianToGregorian(jy, jm, jd);
  return `${gy}-${String(gm).padStart(2,"0")}-${String(gd).padStart(2,"0")}`;
}

console.log(persianToISO(1403, 6, 12));  // "2024-09-02"
console.log(persianToISO(1402, 1, 1));   // "2023-03-21"
console.log(persianToISO(1403, 12, 30)); // "2025-03-20" (leap year Esfand 30)

4. Converting User Input (Persian String → Gregorian Date)

import { persianDate, persianToGregorian } from "@mu-utils/persian-date";

// Parse a Persian date string from an input field
function parseUserInput(persianString: string): Date {
  const pd = persianDate(persianString);          // "1403/06/12" or "1403-06-12"
  return pd;                                      // already a native Date!
}

const d = parseUserInput("1403/06/12");
console.log(d instanceof Date);                   // true
console.log(d.toISOString());                     // "2024-09-01T20:30:00.000Z"
console.log(d.toLocaleDateString("fa-IR"));       // "۱۴۰۳/۶/۱۲"  (system Intl)

💡 How to Use as a Lightweight Alternative to Day.js

Day.js requires loading multiple plugins (utc, timezone, jalaliday, locale/fa, relativeTime) to work with Persian dates, adding bundle size and configuration boilerplate.

With @mu-utils/persian-date, everything works out of the box with zero dependencies:

import { persianDate } from "@mu-utils/persian-date";

// 1. Instantiation (mimics Day.js syntax)
const d = persianDate("1403/06/12 14:30:00");

// 2. Arithmetic (supports singular and plural units)
d.add(1, "week");      // adds 7 days
d.subtract(2, "months"); // subtracts 2 Persian months
d.add(3, "days");

// 3. Formatting with Persian Digits
console.log(d.format("YYYY/MM/DD"));    // "1403/04/22" (English digits)
console.log(d.formatFa("YYYY/MM/DD"));  // "۱۴۰۳/۰۴/۲۲" (Persian digits)
console.log(d.format("dddd DD MMMM"));  // "جمعه 22 تیر"

// 4. Relative Time
console.log(persianDate().subtract(3, "days").fromNow()); // "3 روز پیش"
console.log(persianDate().add(2, "hours").fromNow());     // "2 ساعت بعد"
console.log(persianDate().subtract(5, "minutes").fromNow(false, { digits: "fa" })); // "۵ دقیقه پیش"

// 5. Period Boundaries
const start = persianDate().startOf("week"); // Saturday 00:00:00
const end = persianDate().endOf("week");     // Friday 23:59:59.999

🎨 Building a Real Persian Calendar UI

Here is an example of generating a full month calendar grid (e.g. for React, Vue, Svelte, or Vanilla JS):

import { persianDate, toPersianDigits } from "@mu-utils/persian-date";

export function generateMonthGrid(year: number, month: number) {
  const firstDay = persianDate(year, month, 1);
  const totalDays = firstDay.daysInMonth();
  const startingWeekday = firstDay.getDayOfWeek(); // 0 = شنبه, ..., 6 = جمعه

  const days = [];

  // Empty padding cells before 1st of month
  for (let i = 0; i < startingWeekday; i++) {
    days.push({ empty: true });
  }

  // Days of the month
  for (let day = 1; day <= totalDays; day++) {
    const date = persianDate(year, month, day);
    days.push({
      empty: false,
      dayNumber: day,
      dayNumberFa: toPersianDigits(day),
      isWeekend: date.isWeekend(), // Friday
      dateString: date.format("YYYY/MM/DD"),
      weekdayName: date.format("dddd"),
    });
  }

  return days;
}

// Example usage:
const grid = generateMonthGrid(1403, 6);
console.log(grid);

🔌 Day.js Plugin (jalaliday / dayjsPlugin)

If your codebase already uses Day.js, @mu-utils/persian-date is a 100% drop-in replacement:

import dayjs from "dayjs";
import { jalaliday } from "@mu-utils/persian-date";

dayjs.extend(jalaliday);

// Current Jalali date
const now = dayjs().calendar("jalali");
console.log(now.format("YYYY/MM/DD HH:mm:ss")); // "1405/06/26 12:30:00"

// Parse Persian date
const custom = dayjs("1403/06/12", { jalali: true } as any);
console.log(custom.format("jYYYY/jMM/jDD (dddd)")); // "1403/06/12 (دوشنبه)"
console.log(custom.daysInMonth()); // 31

📖 Format Tokens

Tokens can be combined with bracketed text [...] to escape literals:

persianDate.format("[امروز:] dddd DD MMMM YYYY [ساعت] HH:mm");
// "امروز: دوشنبه 12 شهریور 1403 ساعت 14:30"

| Token | Output Example | Description | | :--- | :--- | :--- | | YYYY / jYYYY | 1403 | 4-digit Persian year | | YY / jYY | 03 | 2-digit Persian year | | MMMM / jMMMM | شهریور | Full Persian month name | | MMM / jMMM | Shahrivar / فرو | Transliterated or short month name | | MM / jMM | 06 | 2-digit month (01–12) | | M / jM | 6 | 1-digit month (1–12) | | DD / jDD | 12 | 2-digit day of month (01–31) | | D / jD | 12 | 1-digit day of month (1–31) | | dddd | دوشنبه | Day of week (شنبه, یکشنبه, ...) | | ddd | د | Short day of week | | HH | 14 | 24-hour padded (00–23) | | H | 14 / 9 | 24-hour single-digit (0–23) | | hh | 02 | 12-hour padded (01–12) | | h | 2 | 12-hour format (1–12) | | mm | 30 | Minutes padded (00–59) | | m | 30 / 5 | Minutes single-digit (0–59) | | ss | 05 | Seconds padded (00–59) | | s | 5 | Seconds single-digit (0–59) | | SSS | 042 | Milliseconds (000–999) | | a | pm / am | Ante / Post meridiem | | A | PM / AM | Uppercase Ante / Post meridiem | | [...] | [Text] | Escaped literal text |

📚 Complete API Reference

Standalone Functions

• persianDate(...args): PersianDate: Factory function (supports all constructor overloads).
• gregorianToPersian(gy, gm, gd): [jy, jm, jd]: Pure integer conversion from Gregorian to Persian.
• persianToGregorian(jy, jm, jd): [gy, gm, gd]: Pure integer conversion from Persian to Gregorian.
• toPersianDigits(input: string | number): string: Replaces 0-9 with ۰-۹.
• replacePersianNumbers(input: string): string: Replaces ۰-۹ with 0-9.
• isPersianLeapYear(year: number): boolean: Checks if a Persian year is leap.
• relativeTime(fromTime, toTime, options?): string: Persian relative time generator.

PersianDate Methods

Formatting

• format(template?: string, options?: { digits?: "en" | "fa" }): string: Formats date. Default template is "YYYY/MM/DD".
• formatFa(template?: string): string: Formats directly with Persian digits.
• toArray(): [year, month, day, hour, min, sec, ms]: Returns date components.
• clone(): PersianDate: Returns a clone.

Calendar Helpers

• getDayOfWeek(): number: Persian weekday (0 = Saturday, 1 = Sunday, ..., 6 = Friday).
• isWeekend(): boolean: Returns true if the day is Friday.
• quarter(): number: Returns the Persian quarter (1–4).
• isLeapYear(): boolean: Returns true if current year is leap.
• daysInMonth(): number: Days in active month (31 for months 1–6, 30 for 7–11, 30/29 for Esfand).

Relative Time

• fromNow(withoutSuffix?, options?): string: e.g. "۳ روز پیش".
• toNow(withoutSuffix?, options?): string: e.g. "در ۳ روز".
• from(date, withoutSuffix?, options?): string: Relative time from another date.
• to(date, withoutSuffix?, options?): string: Relative time to another date.

Arithmetic & Boundaries

• add(value, unit) / add(unit, value): Adds time. Units: "year" | "years" | "month" | "months" | "week" | "weeks" | "day" | "days" | "hour" | "hours" | "minute" | "minutes" | "second" | "seconds".
• subtract(value, unit) / subtract(unit, value): Subtracts time.
• startOf(unit): Sets to beginning of "year" | "month" | "week" | "day" | "hour" | "minute" | "second".
• endOf(unit): Sets to end of "year" | "month" | "week" | "day" | "hour" | "minute" | "second".

Comparisons

• isBefore(otherDate): Checks if date is earlier.
• isAfter(otherDate): Checks if date is later.
• isSame(otherDate, unit?): Checks equality (optionally within "year", "month", "day", etc.).
• diff(otherDate, unit?): Difference in specified unit.

🔬 Leap Year Accuracy: 1403 vs 1404

Traditional algorithms (such as Ahmad Birashk's theoretical 2820-year cycle) erroneously placed the leap year at 1404 instead of 1403.

In the official astronomical calendar (and in Iranian civil calendars), 1403 is a leap year (Esfand has 30 days), and 1404 has 29 days. @mu-utils/persian-date uses the official 33-year solar cycle calculation:

persianDate(1403, 12, 1).isLeapYear();   // true (30 days in Esfand 1403)
persianDate(1403, 12, 1).daysInMonth();  // 30

persianDate(1404, 12, 1).isLeapYear();   // false (29 days in Esfand 1404)
persianDate(1404, 12, 1).daysInMonth();  // 29

🧪 Testing

# Run all 16 test suites with 100% coverage
npm test -- --coverage

# Build bundles
npm run build

# Run demonstration
npm run demo

📄 License

ISC © Muhammad Zolfaghari