❤
npm
Sign UpSign In

This package has been deprecated

Author message:

Use @webilix/jalali-date-time package instead

jalali-date-time
TypeScript icon, indicating that this package has built-in type declarations

5.0.3 • Public • Published

jalali-date-time

Lightweight library for parsing and formating Jalali date with timezone functionality

Table of contents

Installation

npm install --save jalali-date-time

Usage JavaScript

// Default configuration
const config = {
    timezone: 'Asia/Tehran',
    locale: 'en',
    fullTextFormat: 'W, D N Y H:I:S',
    titleFormat: 'W, D N Y',
    dateFormat: 'Y-M-D',
    timeFormat: 'H:I:S',
};

// Load modules
const JalaliDateTime = require('jalali-date-time');
const jalali = JalaliDateTime(config);

OR

// inline configurations
const jalali = require('jalali-date-time')({
    timezone: 'Asia/Tehran',
    locale: 'en',
    fullTextFormat: 'W, D N Y H:I:S',
    titleFormat: 'W, D N Y',
    dateFormat: 'Y-M-D',
    timeFormat: 'H:I:S',
});

OR

// Without configurations / using default values
const jalali = require('jalali-date-time')();

Usage TypeScript

// Default configuration
const config = {
    timezone: 'Asia/Tehran',
    locale: 'en',
    fullTextFormat: 'W, D N Y H:I:S',
    titleFormat: 'W, D N Y',
    dateFormat: 'Y-M-D',
    timeFormat: 'H:I:S',
};

// Load modules
import { JalaliDateTime } from 'jalali-date-time';
const jalali = JalaliDateTime(config);

OR

// Without configurations / using default values
import { JalaliDateTime } from 'jalali-date-time';
const jalali = JalaliDateTime();

Default Configuration

Name Type Description Default Value
timezone String Standard timezone identifier Asia/Tehran
locale Enum en / fa Numbers locale format (en: 3, fa: ۳) en
fullTextFormat String Full-Text date format W, D N Y H:I:S
titleFormat String Date title format W, D N Y
dateFormat String Date format Y-M-D
timeFormat String Time format H:I:S

Formatting Output

Following characters can be used to specify the format of the outputted date string

Identifier Description Example
W Day of Week in persian یک‌شنبه
N Month name in persian خرداد
Y Year (4 digits) 1398
y Year (2 digits) 98
M Month number (zerofill) 03
m Month number 3
D Day of the month (zerofill) 07
d Day of the month 7
H Hour (24-hour format, zerofill) 01
h Hour (24-hour format) 1
I Minute (zerofill) 00
i Minute 0
S Second (zerofill) 06
s Second 6

API Features

Method Description
now Current jalali date
toDate Jalali date value for an specific date
toTime Time value for an specific date/timezone
toString Jalali date/time value for an specific date.
toTitle Jalali date/time persian title for an specific date
toFullText Jalali date/time persian full text for an specific date
toObject Jalali date/time object for an specific date
daysInMonth Number of days in Jalali calendar for specific month
calendar Jalali monthly calendar
gregorian Gregorian date string for an specific Jalali date
timezones List of Standard timezone identifiers

now

Current jalali date

Parameters:

Name Type Required Description
config Configuration Object No Result Configurations

Valid Operators in configration Format are: Y, M, D, H, I, S (in both uppercase and lowercase)

Return Value (String):

Current jalali date.

If format is not specified in configuration then a concatination of dateFormat and timeFormat in Default Configuration (with an space between) will be used.

Sample:

const result = jalali.now();
// 1398-01-23 01:23:45

const result = jalali.now({
    timezone: 'Asia/Tehran',
    locale: 'fa',
    format: 'Y-M-D H:I',
});
// ۱۳۹۸-۰۱-۲۳ ۰۱:۲۳

toDate

Jalali date value for an specific date

Parameters:

Name Type Required Description
date Date Yes Date Value
config Configuration Object No Result Configurations

Valid Operators in configration Format are: Y, M, D (in both uppercase and lowercase)

Return Value (String):

Jalali date value for an specific date.

If date parameter is not a valid Javascript Date then TypeError will thrown.

If format is not specified in configuration then the dateFormat in Default Configuration will be used.

Sample:

const result = jalali.toDate(new Date());
// 1398-01-23

const result = jalali.toDate(new Date(), {
    timezone: 'Asia/Tehran',
    locale: 'fa',
    format: 'Y/M/D',
});
// ۱۳۹۸/۰۱/۲۳

toTime

Time value for an specific date/timezone

Parameters:

Name Type Required Description
date Date Yes Date Value
config Configuration Object No Result Configurations

Valid Operators in configration Format are: H, I, S (in both uppercase and lowercase)

Return Value (String):

Date value for an specific date/timezone.

If date parameter is not a valid Javascript Date then TypeError will thrown.

If format is not specified in configuration then the timeFormat in Default Configuration will be used.

Sample:

const result = jalali.toTime(new Date());
// 01:23:45

const result = jalali.toTime(new Date(), {
    timezone: 'Asia/Tehran',
    locale: 'fa',
    format: 'H:I',
});
// ۰۱:۲۳

toString

Jalali date/time value for an specific date.

Parameters:

Name Type Required Description
date Date Yes Date Value
config Configuration Object No Result Configurations

Valid Operators in configration Format are: Y, M, D, H, I, S (in both uppercase and lowercase)

Return Value (String):

Jalali date/time value for an specific date.

If date parameter is not a valid Javascript Date then TypeError will thrown.

If format is not specified in configuration then a concatination of dateFormat and timeFormat in Default Configuration (with an space between) will be used.

Sample:

const result = jalali.toString(new Date());
// 1398-01-23 01:23:45

const result = jalali.toString(new Date(), {
    timezone: 'Asia/Tehran',
    locale: 'fa',
    format: 'Y-M-D H:I',
});
// ۱۳۹۸-۰۱-۲۳ ۰۱:۲۳

toTitle

Jalali date/time persian title for an specific date.

Parameters:

Name Type Required Description
date Date Yes Date Value
config Configuration Object No Result Configurations

Valid Operators in configration Format are: W, N, Y, M, D (in both uppercase and lowercase)

Default locale configuration for this method is fa. Use locale in config parameter to change it. Useing locle in Default Configuration will not effect this method's result

Return Value (String):

Jalali date/time persian title for an specific date.

If date parameter is not a valid Javascript Date then TypeError will thrown.

If format is not specified in configuration then the titleFormat in Default Configuration will be used.

Sample:

const result = jalali.toTitle(new Date());
// جمعه, ۲۳ فروردین ۱۳۹۸

const result = jalali.toTitle(new Date(), {
    timezone: 'Asia/Tehran',
    locale: 'en',
    format: 'W - D N y',
});
// جمعه - 23 فروردین 98

toFullText

Jalali date/time persian full text for an specific date

Parameters:

Name Type Required Description
date Date Yes Date Value
config Configuration Object No Result Configurations

Valid Operators in configration Format are: W, N, Y, M, D, H, I, S (in both uppercase and lowercase)

Default locale configuration for this method is fa. Use locale in config parameter to change it. Useing locle in Default Configuration will not effect this method's result

Return Value (String):

Jalali date/time persian full text for an specific date.

If date parameter is not a valid Javascript Date then TypeError will thrown.

If format is not specified in configuration then the fullTextFormat in Default Configuration will be used.

Sample:

const result = jalali.toFullText(new Date());
// ۰۱:۲۳:۴۵ جمعه, ۲۳ فروردین ۱۳۹۸

const result = jalali.toFullText(new Date(), {
    timezone: 'Asia/Tehran',
    locale: 'en',
    format: 'W - D N y ساعت h:I:S',
});
// جمعه - 23 فروردین 98 ساعت 1:23:45

toObject

Jalali date/time object for an specific date

Parameters:

Name Type Required Description
date Date Yes Date Value
timezone String No Timezone Value

Return Value (Custom Date Object):

Jalali date/time object for an specific date.

If date parameter is not a valid Javascript Date then TypeError will thrown.

Sample:

const result = jalali.toObject(new Date());
/*   {
 *      week: 6,
 *      year: 1398,
 *      month: 1,
 *      day: 23,
 *      hour: 1,
 *      minute: 23,
 *      second: 45
 *   }
 */

daysInMonth

Number of days in Jalali calendar for specific month

Parameters:

Name Type Required Description
month String No Jalali Month

Return Value (number):

If month value is not a valid month string (format: Y-M, sample: 1398-01) then TypeError will thrown.

If month value is not specified then current Jalali month will be used instead.

Sample:

const result1 = jalali.daysInMonth('1390-01'); // 31
const result2 = jalali.daysInMonth('1390-07'); // 30
const result3 = jalali.daysInMonth('1390-12'); // 29
const result4 = jalali.daysInMonth('1391-12'); // 30

calendar

Jalali monthly calendar

Parameters:

Name Type Required Description
month String No Jalali Month

Return Value (Jalali Calendar Object):

Jalali monthly calendar info.

If month value is not a valid month string (format: Y-M, sample: 1398-01) then TypeError will thrown.

If month value is not specified then current Jalali month will be used instead.

Sample:

const result = jalali.calendar('1398-01');
/*   {
 *       month: '1398-01',
 *       title: 'فروردین ۱۳۹۸',
 *       weeks:
 *          [
 *              [
 *                  { date: '1397-12-25', month: '1397-12', day: 25 },
 *                  { date: '1397-12-26', month: '1397-12', day: 26 },
 *                  { date: '1397-12-27', month: '1397-12', day: 27 },
 *                  { date: '1397-12-28', month: '1397-12', day: 28 },
 *                  { date: '1397-12-29', month: '1397-12', day: 29 },
 *                  { date: '1398-01-01', month: '1398-01', day: 1 },
 *                  { date: '1398-01-02', month: '1398-01', day: 2 }
 *              ],
 *              [
 *                  { date: '1398-01-03', month: '1398-01', day: 3 },
 *                  { date: '1398-01-04', month: '1398-01', day: 4 },
 *                  { date: '1398-01-05', month: '1398-01', day: 5 },
 *                  { date: '1398-01-06', month: '1398-01', day: 6 },
 *                  { date: '1398-01-07', month: '1398-01', day: 7 },
 *                  { date: '1398-01-08', month: '1398-01', day: 8 },
 *                  { date: '1398-01-09', month: '1398-01', day: 9 }
 *              ],
 *              [
 *                  { date: '1398-01-10', month: '1398-01', day: 10 },
 *                  { date: '1398-01-11', month: '1398-01', day: 11 },
 *                  { date: '1398-01-12', month: '1398-01', day: 12 },
 *                  { date: '1398-01-13', month: '1398-01', day: 13 },
 *                  { date: '1398-01-14', month: '1398-01', day: 14 },
 *                  { date: '1398-01-15', month: '1398-01', day: 15 },
 *                  { date: '1398-01-16', month: '1398-01', day: 16 }
 *              ],
 *              [
 *                  { date: '1398-01-17', month: '1398-01', day: 17 },
 *                  { date: '1398-01-18', month: '1398-01', day: 18 },
 *                  { date: '1398-01-19', month: '1398-01', day: 19 },
 *                  { date: '1398-01-20', month: '1398-01', day: 20 },
 *                  { date: '1398-01-21', month: '1398-01', day: 21 },
 *                  { date: '1398-01-22', month: '1398-01', day: 22 },
 *                  { date: '1398-01-23', month: '1398-01', day: 23 }
 *              ],
 *              [
 *                  { date: '1398-01-24', month: '1398-01', day: 24 },
 *                  { date: '1398-01-25', month: '1398-01', day: 25 },
 *                  { date: '1398-01-26', month: '1398-01', day: 26 },
 *                  { date: '1398-01-27', month: '1398-01', day: 27 },
 *                  { date: '1398-01-28', month: '1398-01', day: 28 },
 *                  { date: '1398-01-29', month: '1398-01', day: 29 },
 *                  { date: '1398-01-30', month: '1398-01', day: 30 }
 *              ],
 *              [
 *                  { date: '1398-01-31', month: '1398-01', day: 31 },
 *                  { date: '1398-02-01', month: '1398-02', day: 1 },
 *                  { date: '1398-02-02', month: '1398-02', day: 2 },
 *                  { date: '1398-02-03', month: '1398-02', day: 3 },
 *                  { date: '1398-02-04', month: '1398-02', day: 4 },
 *                  { date: '1398-02-05', month: '1398-02', day: 5 },
 *                  { date: '1398-02-06', month: '1398-02', day: 6 }
 *              ]
 *          ]
 *   }
 */

gregorian

Gregorian date string for an specific Jalali date

Parameters:

Name Type Required Description
jalali String Yes Jalali Date

Return Value (Gregorian Date Object):

Gregorian date string for an specific Jalali date.

If date parameter is not a valid date string (format: Y-M-D, sample: 1398-01-23 or 1398-1-23) then TypeError will thrown.

Year in date string must be 4 digits otherwise RangeError will thrown.

Month in date string must be between 1 and 12 otherwise RangeError will thrown.

Day in date string must be between 1 and 31 otherwise RangeError will thrown.

Sample:

const result = jalali.gregorian('1398-01-23');
/*   {
 *      year: 2019,
 *      month: 4,
 *      day: 12,
 *      date: '2019-04-12'
 *   }
 */

timezones

List of Standard timezone identifiers

Return Value (Stringp[]):

List of Standard timezone identifiers.

All values in returned list can be use as timezone on all methods

Sample:

const result = jalali.timezones();
/*   [
 *      'Africa/Abidjan',
 *      'Africa/Accra',
 *      'Africa/Addis_Ababa',
 *      'Africa/Algiers',
 *      'Africa/Asmara',
 *      'Africa/Asmera',
 *      'Africa/Bamako',
 *      'Africa/Bangui',
 *      ...
 *   ]
 */

nextDay

Next week day according to specific date

Parameters:

Name Type Required Description
day Number Yes Week day number (Sunday - Saturday : 0 - 6)
date Date No Date Value
timezone String No Timezone Value

Return Value (Date):

If day value is NaN or not between 0, 6 then TypeError will thrown.

If date parameter is not a valid Javascript Date then TypeError will thrown.

Sample:

const result = jalali.nextDay(0);
/* 2025-03-22T19:30:00.000Z */

const result = jalali.nextDay(2);
/* 2025-03-24T19:30:00.000Z */

nextMonth

Specific days in next month according to specific date in Jalali calendar

Parameters:

Name Type Required Description
type String, number Yes Month day type: 'FIRST', 'LAST', number (1 - 31)
date Date No Date Value
timezone String No Timezone Value

Return Value (Date):

If type value is not one of specified values then TypeError will thrown.

If date parameter is not a valid Javascript Date then TypeError will thrown.

Results:

  • FIRST: First day of next month
  • LAST: Last day of next month
  • DAY: Specific day of next month according to date (example: 1400-01-15 > 1400-02-15)

    If date is not valid for next month, first next month with valid date will be returned (example: 1400-06-31 > 1401-01-31)

Sample:

const result = jalali.nextMonth('FIRST');
/* 2025-03-20T20:30:00.000Z */

const result = jalali.nextMonth('LAST');
/* 2025-04-19T19:30:00.000Z */

nextYear

Next years date according to specific date in Jalali calendar

Parameters:

Name Type Required Description
date Date No Date Value
timezone String No Timezone Value

Return Value (Date):

If date parameter is not a valid Javascript Date then TypeError will thrown.

If date is not valid for next year, first next year with valid date will be returned (example: 1403-12-30 > 1408-12-30)

Sample:

const result = jalali.nextYear();
/* 2030-03-19T20:30:00.000Z */

periodHour

Hourly date/time period values based of number of hours

Parameters:

Name Type Required Description
hours Number Yes Nomber of hours
date Date No End Date Value
timezone String No Timezone Value

Return Value (Period Object):

If hours value is NaN or less than 1 then TypeError will thrown.

If date parameter is not a valid Javascript Date then TypeError will thrown.

Sample:

const result = jalali.periodHour(3);
/*   {
 *      from: 2021-10-05T01:30:00.000Z,
 *      to: 2021-10-05T04:29:59.999Z,
 *      periods: [
 *        { from: 2021-10-05T01:30:00.000Z, to: 2021-10-05T02:29:59.999Z },
 *        { from: 2021-10-05T02:30:00.000Z, to: 2021-10-05T03:29:59.999Z },
 *        { from: 2021-10-05T03:30:00.000Z, to: 2021-10-05T04:29:59.999Z }
 *      ]
 *    }
 */

periodDay

Daily date/time period values based of number of days

Parameters:

Name Type Required Description
days Number Yes Nomber of days
date Date No End Date Value
timezone String No Timezone Value

Return Value (Period Object):

If days value is NaN or less than 1 then TypeError will thrown.

If date parameter is not a valid Javascript Date then TypeError will thrown.

Sample:

const result = jalali.periodDays(7);
/*   {
 *      from: 2021-09-28T20:30:00.000Z,
 *      to: 2021-10-05T20:29:59.999Z,
 *      periods: [
 *        { from: 2021-09-28T20:30:00.000Z, to: 2021-09-29T20:29:59.999Z },
 *        { from: 2021-09-29T20:30:00.000Z, to: 2021-09-30T20:29:59.999Z },
 *        { from: 2021-09-30T20:30:00.000Z, to: 2021-10-01T20:29:59.999Z },
 *        { from: 2021-10-01T20:30:00.000Z, to: 2021-10-02T20:29:59.999Z },
 *        { from: 2021-10-02T20:30:00.000Z, to: 2021-10-03T20:29:59.999Z },
 *        { from: 2021-10-03T20:30:00.000Z, to: 2021-10-04T20:29:59.999Z },
 *        { from: 2021-10-04T20:30:00.000Z, to: 2021-10-05T20:29:59.999Z }
 *      ]
 *   }
 */

periodWeek

Weekly date/time period values based of number of days

Parameters:

Name Type Required Description
weeks Number Yes Nomber of weekd
date Date No End Date Value
timezone String No Timezone Value

Return Value (Period Object):

If weeks value is NaN or less than 1 then TypeError will thrown.

If date parameter is not a valid Javascript Date then TypeError will thrown.

Sample:

const result = jalali.periodWeeks(4);
/*   {
 *       from: 2021-09-24T20:30:00.000Z,
 *       to: 2021-10-22T20:29:59.999Z,
 *       periods: [
 *         { from: 2021-09-24T20:30:00.000Z, to: 2021-10-01T20:29:59.999Z },
 *         { from: 2021-10-01T20:30:00.000Z, to: 2021-10-08T20:29:59.999Z },
 *         { from: 2021-10-08T20:30:00.000Z, to: 2021-10-15T20:29:59.999Z },
 *         { from: 2021-10-15T20:30:00.000Z, to: 2021-10-22T20:29:59.999Z }
 *       ]
 *    }
 */

periodMonth

Monthly (jalali month) date/time period values based of number of months

Parameters:

Name Type Required Description
months Number Yes Nomber of months
date Date No End Date Value
timezone String No Timezone Value

Return Value (Period Object):

If months value is NaN or less than 1 then TypeError will thrown.

If date parameter is not a valid Javascript Date then TypeError will thrown.

Sample:

const result = jalali.periodMonth(4);
/*   {
 *      from: 2020-10-21T20:30:00.000Z,
 *      to: 2021-10-22T20:29:59.999Z,
 *      periods: [
 *        { from: 2021-06-21T20:30:00.000Z, to: 2021-07-22T20:29:59.999Z },
 *        { from: 2021-07-22T20:30:00.000Z, to: 2021-08-22T20:29:59.999Z },
 *        { from: 2021-08-22T20:30:00.000Z, to: 2021-09-22T20:29:59.999Z },
 *        { from: 2021-09-22T20:30:00.000Z, to: 2021-10-22T20:29:59.999Z }
 *      ]
 *    }
 */

Custom Types

Type Usage
Configuration Object Main methods configuration parameter
Custom Date Object Result value type for toObject method
Gregorian Date Object Result value type for gregorian method
Period Object Result value type for period methods

Configuration Object

Main methods configuration parameter

Property Type Description
timezone String Standard timezone identifier
locale Enum en / fa Numbers locale format (en: 3, fa: ۳)
format String Return Value Format

Custom Date Object

Result value type for toObject method

Property Type Description
week Number Week Day (saturday=0, friday=6)
year Number Year Value
month Number Month Value
day Number Day Value
hour Number Hour Value
minute Number Minute Value
second Number Second Value

Jalali Calendar Object

Result value type for calendar method

Property Type Description
month String Jalali Month Value
title String Jalali Month Title
weeks Array of Arrays Weeks Data
weeks[*][1-7].date String Day values: Jalali Date
weeks[*][1-7].month String Day values: Jalali Month
weeks[*][1-7].day Number Day values: Day Number

Gregorian Date Object

Result value type for gregorian method

Property Type Description
year Number Year Value
month Number Month Value
day Number Day Value
date String Full Date String (sample: 2019-04-12)

Period Object

Result value type for period methods

Property Type Description
from Date Start of period
to Date End of period
periods Array of Object { from: Date, to: Date } Periods list

Errors

Error Method Parameter Message
TypeError toDate date Invalid Date
TypeError toTime date Invalid Date
TypeError toString date Invalid Date
TypeError toTitle date Invalid Date
TypeError toFullText date Invalid Date
TypeError toObject date Invalid Date
TypeError gregorian jalali Date is not String
RangeError gregorian jalali Year must be 4 digits
RangeError gregorian jalali Month is not between 1, 12
RangeError gregorian jalali Day is not between 1, 31
TypeError periodHour hours Hours must be bigger than 0
TypeError periodHour date Invalid Date
TypeError periodDay days Days must be bigger than 0
TypeError periodDay date Invalid Date
TypeError periodMonth months Months must be bigger than 0
TypeError periodMonth date Invalid Date

Tests

git clone https://github.com/webilix/jalali-date-time.git
npm install
npm test

Readme

Keywords

Package Sidebar

Install

npm i jalali-date-time

Repository

github.com/webilix/jalali-date-time

Homepage

github.com/webilix/jalali-date-time#readme

Weekly Downloads

67

Version

5.0.3

License

MIT

Unpacked Size

183 kB

Total Files

156

Last publish

Collaborators

  • webilix
Try on RunKit
Report malware