@webilix/jalali-date-time
Version:
Lightweight library for parsing and formating Jalali date with timezone functionality
1,096 lines (793 loc) • 36.4 kB
Markdown
# @webilix/jalali-date-time
Lightweight library for parsing and formating Jalali date with timezone functionality
## Table of contents
- [Installation](#installation)
- [Usage JavaScript](#usage-javascript)
- [Usage TypeScript](#usage-typescript)
- [Default Configuration](#default-configuration)
- [Formatting Output](#formatting-output)
- [API Features](#api-features)
- [now](#now)
- [toDate](#todate)
- [toTime](#totime)
- [toString](#tostring)
- [toTitle](#totitle)
- [toFullText](#tofulltext)
- [toObject](#toobject)
- [dayOfWeek](#dayofweek)
- [daysInMonth](#daysinmonth)
- [calendar](#calendar)
- [gregorian](#gregorian)
- [timezones](#timezones)
- [nextDayOfWeek](#nextdayofweek)
- [nextDayOfMonth](#nextdayofmonth)
- [nextDayOfYear](#nextdayofyear)
- [periodHour](#periodhour)
- [periodDay](#periodday)
- [periodWeek](#periodweek)
- [periodMonth](#periodmonth)
- [periodYear](#periodyear)
- [Classes](#classes)
- [Modify](#modify)
- [Custom Types](#custom-types)
- [Errors](#errors)
- [Tests](#tests)
## Installation
```bash
npm install --save @webilix/jalali-date-time
```
## Usage JavaScript
```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('@webilix/jalali-date-time');
const jalali = JalaliDateTime(config);
```
OR
```javascript
// inline configurations
const jalali = require('@webilix/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
```javascript
// Without configurations / using default values
const jalali = require('@webilix/jalali-date-time')();
```
## Usage TypeScript
```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 '@webilix/jalali-date-time';
const jalali = JalaliDateTime(config);
```
OR
```javascript
// Without configurations / using default values
import { JalaliDateTime } from '@webilix/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](#now) | Current jalali date |
| [toDate](#todate) | Jalali date value for an specific date |
| [toTime](#totime) | Time value for an specific date/timezone |
| [toString](#tostring) | Jalali date/time value for an specific date. |
| [toTitle](#totitle) | Jalali date/time persian title for an specific date |
| [toFullText](#tofulltext) | Jalali date/time persian full text for an specific date |
| [toObject](#toobject) | Jalali date/time object for an specific date |
| [daysInMonth](#daysinmonth) | Number of days in Jalali calendar for specific month |
| [calendar](#calendar) | Jalali monthly calendar |
| [gregorian](#gregorian) | Gregorian date string for an specific Jalali date |
| [timezones](#timezones) | List of Standard timezone identifiers |
### [now](#now)
Current jalali date
**Parameters**:
| Name | Type | Required | Description |
| ------ | --------------------------------------------- | -------- | --------------------- |
| config | [Configuration Object](#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](#default-configuration) (with an space between) will be used.
**Sample:**
```javascript
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](#todate)
Jalali date value for an specific date
**Parameters:**
| Name | Type | Required | Description |
| ------ | --------------------------------------------- | -------- | --------------------- |
| date | Date | Yes | Date Value |
| config | [Configuration Object](#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](#default-configuration) will be used.
**Sample:**
```javascript
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](#totime)
Time value for an specific date/timezone
**Parameters:**
| Name | Type | Required | Description |
| ------ | --------------------------------------------- | -------- | --------------------- |
| date | Date | Yes | Date Value |
| config | [Configuration Object](#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](#default-configuration) will be used.
**Sample:**
```javascript
const result = jalali.toTime(new Date());
// 01:23:45
const result = jalali.toTime(new Date(), {
timezone: 'Asia/Tehran',
locale: 'fa',
format: 'H:I',
});
// ۰۱:۲۳
```
### [toString](#tostring)
Jalali date/time value for an specific date.
**Parameters:**
| Name | Type | Required | Description |
| ------ | --------------------------------------------- | -------- | --------------------- |
| date | Date | Yes | Date Value |
| config | [Configuration Object](#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](#default-configuration) (with an space between) will be used.
**Sample:**
```javascript
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](#totitle)
Jalali date/time persian title for an specific date.
**Parameters:**
| Name | Type | Required | Description |
| ------ | --------------------------------------------- | -------- | --------------------- |
| date | Date | Yes | Date Value |
| config | [Configuration Object](#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](#default-configuration) will be used.
**Sample:**
```javascript
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](#tofulltext)
Jalali date/time persian full text for an specific date
**Parameters:**
| Name | Type | Required | Description |
| ------ | --------------------------------------------- | -------- | --------------------- |
| date | Date | Yes | Date Value |
| config | [Configuration Object](#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](#default-configuration) will be used.
**Sample:**
```javascript
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](#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](#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:**
```javascript
const result = jalali.toObject(new Date());
/* {
* week: 6,
* year: 1398,
* month: 1,
* day: 23,
* hour: 1,
* minute: 23,
* second: 45
* }
*/
```
### [dayOfWeek](#dayofweek)
Week day number in jalali calendar
Starts with Saturday as 0 and ends with Friday as 6
**Parameters:**
| Name | Type | Required | Description |
| -------- | ------ | -------- | -------------- |
| date | Date | No | Date Value |
| timezone | String | No | Timezone Value |
**Return Value (number, 0 - 6):**
If date parameter is not a valid Javascript Date then **TypeError** will thrown.
**Sample:**
```javascript
const result = jalali.dayOfWeek();
```
### [daysInMonth](#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:**
```javascript
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](#calendar)
Jalali monthly calendar
**Parameters:**
| Name | Type | Required | Description |
| ----- | ------ | -------- | ------------ |
| month | String | No | Jalali Month |
**Return Value ([Jalali Calendar Object](#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:**
```javascript
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)
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-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:**
```javascript
const result = jalali.gregorian('1398-01-23');
/* {
* year: 2019,
* month: 4,
* day: 12,
* date: '2019-04-12'
* }
*/
```
### [timezones](#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:**
```javascript
const result = jalali.timezones();
/* [
* 'Africa/Abidjan',
* 'Africa/Accra',
* 'Africa/Addis_Ababa',
* 'Africa/Algiers',
* 'Africa/Asmara',
* 'Africa/Asmera',
* 'Africa/Bamako',
* 'Africa/Bangui',
* ...
* ]
*/
```
### [nextDayOfWeek](#nextdayofweek)
Next week day according to specific date
**Parameters:**
| Name | Type | Required | Description |
| --------- | ------ | -------- | ----------------------------------------- |
| dayOfWeek | Number | Yes | Week day number (Sunday: 0 - Saturday: 6) |
| date | Date | No | Date Value |
| timezone | String | No | Timezone Value |
**Return Value (Date):**
If dayOfWeek 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:**
```javascript
const result = jalali.nextDayOfWeek(0);
/* 2025-03-22T19:30:00.000Z */
const result = jalali.nextDayOfWeek(2);
/* 2025-03-24T19:30:00.000Z */
```
### [nextDayOfMonth](#nextdayofmonth)
Specific days in next month according to specific date in Jalali calendar
**Parameters:**
| Name | Type | Required | Description |
| ---------- | -------------- | -------- | ------------------------------------------------- |
| dayOfMonth | String, number | Yes | Month day value: 'FIRST', 'LAST', number (1 - 31) |
| date | Date | No | Date Value |
| timezone | String | No | Timezone Value |
**Return Value (Date):**
If dayOfMonth 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 month
- LAST: Last day of month
- DAY: Specific day of month according to date (example: 1400-01-15 > 1400-02-15)
> If date is not valid for next month, first month with valid date will be returned (example: 1400-06-31 > 1401-01-31)
**Sample:**
```javascript
const result = jalali.nextDayOfMonth('FIRST');
/* 2025-03-20T20:30:00.000Z */
const result = jalali.nextDayOfMonth('LAST');
/* 2025-04-19T19:30:00.000Z */
```
### [nextDayOfYear](#nextdayofyear)
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 year with valid date will be returned (example: 1403-12-30 > 1408-12-30)
**Sample:**
```javascript
const result = jalali.nextDayOfYear();
/* 2030-03-19T20:30:00.000Z */
```
### [periodHour](#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](#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:**
```javascript
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](#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](#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:**
```javascript
const result = jalali.periodDay(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](#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](#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:**
```javascript
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](#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](#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:**
```javascript
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 }
* ]
* }
*/
```
### [periodYear](#periodyear)
Yearly (jalali year) date/time period values based of number of years
**Parameters:**
| Name | Type | Required | Description |
| -------- | ------ | -------- | --------------- |
| years | Number | Yes | Nomber of years |
| date | Date | No | End Date Value |
| timezone | String | No | Timezone Value |
**Return Value ([Period Object](#period-object)):**
If years 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:**
```javascript
const result = jalali.periodYear(4);
/* {
* from: 2019-03-20T20:30:00.000Z,
* to: 2023-03-20T20:29:59.999Z,
* periods: [
* { from: 2019-03-20T20:30:00.000Z, to: 2020-03-19T20:29:59.999Z },
* { from: 2020-03-19T20:30:00.000Z, to: 2021-03-20T20:29:59.999Z },
* { from: 2021-03-20T20:30:00.000Z, to: 2022-03-20T20:29:59.999Z },
* { from: 2022-03-20T20:30:00.000Z, to: 2023-03-20T20:29:59.999Z }
* ]
* }
*/
```
## Classes
### [Modify](#modify)
Modifying date by adding or subtracting year / month / day according to jalali date-time
### Create class instance
**Parameters:**
| Name | Type | Required | Description |
| -------- | ------ | -------- | -------------------- |
| date | Date | No | Date Value to modify |
| timezone | String | No | Timezone Value |
**Return Value:**
New instance of modify class
**Sample:**
```javascript
const modify = new jalali.modify(new Date(), 'Asia/Tehran');
// or
const modify = new jalali.modify();
```
### Change year value
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------ | -------- | ----------------------------------------------------------------------- |
| change | Number | Yes | Number of years to add (positive numbers) / subtract (negative numbers) |
**Return Value:**
Instance of modify class with changed values
**Sample:**
```javascript
modify.year(10); // Add 10 years to current date
modify.year(-10); // Subtract 10 years from current date
```
### Change month value
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------ | -------- | ------------------------------------------------------------------------ |
| change | Number | Yes | Number of months to add (positive numbers) / subtract (negative numbers) |
**Return Value:**
Instance of modify class with changed values
**Sample:**
```javascript
modify.month(50); // Add 50 months to current date
modify.month(-50); // Subtract 50 months from current date
```
### Change day value
**Parameters:**
| Name | Type | Required | Description |
| ------ | ------ | -------- | ---------------------------------------------------------------------- |
| change | Number | Yes | Number of days to add (positive numbers) / subtract (negative numbers) |
**Return Value:**
Instance of modify class with changed values
**Sample:**
```javascript
modify.day(150); // Add 150 days to current date
modify.day(-150); // Subtract 150 days from current date
```
### Getting modified date value
| Name | Type | Required | Description |
| ---- | -------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| time | 'START', 'END' | No | Time of returned date<br><br>_START: Date value will be at the start of day (00:00:00)_<br>_END: Date value will be at the end of day (23:59:59)_<br>_Default: Time of date value will not change_ |
**Return Value:**
JavaScript Date object
**Sample:**
```javascript
const date: Date = modify.toDate('START');
// or
const date: Date = modify.toDate();
```
### Chain methods
**Sample:**
```javascript
const modify = new jalali.modify();
// 2025-07-08T22:38:35.000Z
// Adding 1 year and 5 months and subtracting 10 days from current date
// and returning new Date value at the start of modified date
const date: Date = modify.year(1).month(5).day(-10).toDate('START');
// 2025-07-08T20:30:00.000Z
```
## Custom Types
| Type | Usage |
| ----------------------------------------------- | ------------------------------------------ |
| [Configuration Object](#configuration-object) | Main methods configuration parameter |
| [Custom Date Object](#custom-date-object) | Result value type for **toObject** method |
| [Gregorian Date Object](#gregorian-date-object) | Result value type for **gregorian** method |
| [Period Object](#period-object) | Result value type for **period** methods |
### [Configuration Object](#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](#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](#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](#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](#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](#todate) | date | Invalid Date |
| TypeError | [toTime](#totime) | date | Invalid Date |
| TypeError | [toString](#tostring) | date | Invalid Date |
| TypeError | [toTitle](#totitle) | date | Invalid Date |
| TypeError | [toFullText](#tofulltext) | date | Invalid Date |
| TypeError | [toObject](#toobject) | date | Invalid Date |
| TypeError | [gregorian](#gregorian) | jalali | Date is not String |
| RangeError | [gregorian](#gregorian) | jalali | Year must be 4 digits |
| RangeError | [gregorian](#gregorian) | jalali | Month is not between 1, 12 |
| RangeError | [gregorian](#gregorian) | jalali | Day is not between 1, 31 |
| TypeError | [periodHour](#periodhour) | hours | Hours must be bigger than 0 |
| TypeError | [periodHour](#periodhour) | date | Invalid Date |
| TypeError | [periodDay](#periodday) | days | Days must be bigger than 0 |
| TypeError | [periodDay](#periodday) | date | Invalid Date |
| TypeError | [periodMonth](#periodmonth) | months | Months must be bigger than 0 |
| TypeError | [periodMonth](#periodmonth) | date | Invalid Date |
## Tests
```bash
git clone https://github.com/webilix/jalali-date-time.git
npm install
npm test
```