jalali-date-time v5.0.3

jalali-date-time

Lightweight library for parsing and formating Jalali date with timezone functionality

Table of contents

• Installation
• Usage JavaScript
• Usage TypeScript
• Default Configuration
• Formatting Output
• API Features
  • now
  • toDate
  • toTime
  • toString
  • toTitle
  • toFullText
  • toObject
  • daysInMonth
  • calendar
  • gregorian
  • timezones
  • nextDay
  • nextMonth
  • nextYear
  • periodHour
  • periodDay
  • periodWeek
  • periodMonth
• Custom Types
• Errors
• Tests

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

Formatting Output

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

API Features

now

Current jalali date

Parameters:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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:

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

Configuration Object

Main methods configuration parameter

Custom Date Object

Result value type for toObject method

Jalali Calendar Object

Result value type for calendar method

Gregorian Date Object

Result value type for gregorian method

Period Object

Result value type for period methods

Errors

Tests

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