persidate
Version:
persidate is a lightweight package for converting and managing Shamsi (Jalali) and Gregorian dates in JavaScript/TypeScript.
187 lines (132 loc) • 6.84 kB
Markdown
# persidate
[](https://www.npmjs.com/package/persidate)
[](https://bundlephobia.com/result?p=persidate)
[](https://www.npmjs.com/package/persidate)
[](https://sonarcloud.io/summary/new_code?id=mmsafari_persidate)
[](https://sonarcloud.io/summary/new_code?id=mmsafari_persidate)
**`persidate`** is a lightweight JavaScript/TypeScript library designed for converting and managing Shamsi (Jalali) and Gregorian dates. It provides a clean and simple API for handling date conversions, formatting, and utility functions.
---
## Installation
```bash
npm install persidate
# or
yarn add persidate
```
Compatible with Node.js v14+ (tested up to v22)
>Try it in [Live Demo](https://k2xwfw.csb.app/).
## Benchmark
`persidate` delivers a cleaner, faster, and lighter solution for Jalali ↔ Gregorian date handling, making it a superior alternative to bulky or outdated libraries like **jalali-moment**, **dayjs**, and **idate**.
| Package | Bundle size (Min+Gzip) | Notes |
|---------------|-------------------------|-------|
| **persidate** | **2.3 KB** | **Fast, Lightweight, No deps** |
| jalali-moment | 78.4 KB | Verbose API, Legacy |
| dayjs | 3 KB | Plugin-based Jalali support |
| idate | 2.7 KB | Outdated, Legacy |
> Check out a small sandbox comparing **persidate**, dayjs, jalali-moment, and idate in tricky date conversion cases.
> [Open Sandbox](https://codesandbox.io/p/sandbox/inspiring-johnson-p86lrj)
## Features & Advantages
- **Fast & Lightweight** – Ultra-optimized conversions with no dependencies.
- **Full Jalali ↔ Gregorian Support** – Simple API for conversion, formatting, and utilities.
- **Developer-Friendly** – Clean TypeScript API, works for both Persian and non-Persian devs.
- **Reliable & Tested** – Verified with **SonarQube**, compatible with Node.js v14+.
## Functions
### Convert
##### Transform between Jalali and Gregorian.
• convertToStandardDateTime
• convertToISODateTime
• convertToGregorianDate
• convertToGregorianDateString
• convertToJalaliDate
### Format
##### Display in specific formats (padded, localized).
• formatToGregorianDate
• formatToGregorianDateTime
• formatToJalaliDatePadded
• formatToLocalizedDate
### Get
##### Retrieve specific details (today, timestamp, etc).
• getToday
• getTimeFromDate
• getDaysFromNow
• getJalaliTimeStamp
• getTimeAgo
### Utility
##### Miscellaneous operations (add days, compare dates).
• addDaysToDate
• isBeforeDate
• isLeapYearJalali
### Constants
##### Static month/weekday names.
• jalaliMonthNames
• jalaliWeekdayNames
## Usage
Here are some quick examples:
```ts
// Convert to local ISO string
const localISO = convertToStandardDateTime(new Date('2024-10-18T10:00:00Z'));
console.log(localISO); // 2024-10-18T13:30:00
// Convert to ISO with timezone adjustment
const isoDate = convertToISODateTime('2024-10-18T10:00:00Z');
console.log(isoDate); // 2024-10-18T11:00:00
// Convert Jalali (Shamsi) to Gregorian Date object
const miladi = convertToGregorianDate("1403-8-16");
console.log(miladi); // Wed Nov 06 2024 ...
// Convert Jalali to formatted Gregorian string
const miladiStr = convertToGregorianDateString("1403/8/16");
console.log(miladiStr); // 2024/11/6
// Convert Gregorian to Jalali with default format
const shamsi1 = convertToJalaliDate("2024-10-18");
console.log(shamsi1); // 1403-07-27
//convert Georgian date to Jalali
const shamsi2 = convertToJalaliDate(new Date());
console.log(germanDate); // 1403-07-27
// Convert Gregorian to Jalali with custom formats
console.log(convertToJalaliDate("2024-10-18", "dayMonth")); // 27 مهر
console.log(convertToJalaliDate("2024-10-18", "dayMonthYear")); // 27 مهر 1403
console.log(convertToJalaliDate("2024-10-18", "weekdayDayMonth")); // جمعه 27 مهر
console.log(convertToJalaliDate("2024-10-18", "weekdayDayMonthYear")); // جمعه 27 مهر 1403
console.log(convertToJalaliDate("2024-10-18", "day")); // 27
console.log(convertToJalaliDate("2024-10-18", "weekday")); // جمعه
console.log(convertToJalaliDate("2024-10-18", "month")); // مهر
console.log(convertToJalaliDate(1752771248824, "year")); // 1404
// Timestamp to Gregorian date string
console.log(formatToGregorianDate(1697625600000)); // 2023-10-19
// Date object to Gregorian string
console.log(formatToGregorianDate(new Date('2024-10-18'))); // 2024-10-18
// Jalali date + time to Gregorian datetime string
console.log(formatToGregorianDateTime(new Date(), '14:30')); // 2024-10-17T14:30
console.log(formatToGregorianDateTime(1697625600000, '14:30')); // 2024-10-17T14:30
// Gregorian to Jalali (padded)
console.log(formatToJalaliDatePadded('2024-10-18')); // 1403-07-26
console.log(formatToJalaliDatePadded(new Date())); // 1403-07-26
console.log(formatToJalaliDatePadded(1697625600000)); // 1403-07-26
// Gregorian to localized Jalali string
console.log(formatToLocalizedDate('2024-10-18', 'jYYYY-jM-jD')); // 1403-7-26
// Get today's date (YYYY-MM-DD)
console.log(getToday()); // e.g. 2024-10-17
// Extract time from datetime string
console.log(getTimeFromDate('2024-10-18T14:30:00')); // 14:30:00
console.log(getTimeFromDate(new Date())); // 12:43:00
console.log(getTimeFromDate(1697625600000)); // 12:43:00
// Days from now to future date
console.log(getDaysFromNow("2025-08-01T12:00:00")); // 20
console.log(getDaysFromNow(new Date("2025-07-20"))); // 8
// Convert Jalali to timestamp (ms)
console.log(getJalaliTimeStamp("1404-01-01")); // 1710873600000
// Time difference in Persian (e.g. "۲ روز پیش")
console.log(getTimeAgo(new Date()));
console.log(getTimeAgo("2025-07-20"));
console.log(getTimeAgo(1697625600000));
// Add N days to a date
const today = new Date();
const plusTen = addDaysToDate(today, 10);
console.log(plusTen);
// Compare two dates
const date1 = '2024-10-18';
const date2 = '2025-01-01';
console.log(isBeforeDate(date1, date2)); // true
// Check if the given Jalali year is a leap year
console.log(isLeapYearJalali(1403)); // true
```
## Contributors
- **mmsafari**: [GitHub](https://github.com/mmsafari) · [LinkedIn](https://www.linkedin.com/in/mmsafari/)