UNPKG

6.06 kBMarkdownView Raw
1# Jalaali JavaScript
2
3A few javascript functions for converting Jalaali (Jalali, Persian, Khayyami, Khorshidi, Shamsi) and Gregorian calendar systems to each other.
4
5## Note (Feb 2022)
6
7If you just need to display date and time in Persian calendar, you may use `Intl` which is ECMAScript Internationalization API with a [very good browser support](https://caniuse.com/mdn-javascript_builtins_intl_datetimeformat_format). For example:
8
9```js
10const d = new Date(2022,2,21)
11
12// Simple format
13console.log(new Intl.DateTimeFormat('fa-IR').format(d));
14// => ۱۴۰۱/۱/۱
15
16// Full long format
17console.log(new Intl.DateTimeFormat('fa-IR', {dateStyle: 'full', timeStyle: 'long'}).format(d));
18// => ۱۴۰۱ فروردین ۱, دوشنبه، ساعت ۰:۰۰:۰۰ (‎+۳:۳۰ گرینویچ)
19
20// Latin numbers
21console.log(new Intl.DateTimeFormat('fa-IR-u-nu-latn', {dateStyle: 'full', timeStyle: 'long'}).format(d));
22// => 1401 فروردین 1, دوشنبه، ساعت 0:00:00 (‎+3:30 گرینویچ)
23
24// English US locale with Persian calendar
25console.log(new Intl.DateTimeFormat('en-US-u-ca-persian', {dateStyle: 'full', timeStyle: 'long'}).format(d));
26// => Monday, Farvardin 1, 1401 AP at 12:00:00 AM GMT+3:30
27
28// Just year
29console.log(new Intl.DateTimeFormat('en-US-u-ca-persian', {year: 'numeric'}).format(d));
30// => 1401 AP
31
32// Just month
33console.log(new Intl.DateTimeFormat('en-US-u-ca-persian', {month: 'short'}).format(d));
34// Farvardin
35
36// Just day
37console.log(new Intl.DateTimeFormat('en-US-u-ca-persian', {day: 'numeric'}).format(d));
38// => 1
39```
40
41> **Notice**: the current implementation of `jalaali-js` algorithms diverge from the `Intl` API results after the Gregorian year 2256 (or Jalali year 1634) due to different approaches to calculating the leap years. However, this shouldn't affect the usage of the library, as the results are the same from 1800 to 2256. (for more information, see [this comparison](https://runkit.com/sinakhx/625929b1a90c8d0007b539a3))
42
43## About
44
45Jalali calendar is a solar calendar that was used in Persia, variants of which today are still in use in Iran as well as Afghanistan. [Read more on Wikipedia](http://en.wikipedia.org/wiki/Jalali_calendar) or see [Calendar Converter](http://www.fourmilab.ch/documents/calendar/).
46
47Calendar conversion is based on the [algorithm provided by Kazimierz M. Borkowski](http://www.astro.uni.torun.pl/~kb/Papers/EMP/PersianC-EMP.htm) and has a very good performance.
48
49## Install
50
51### Node.js
52
53Use [`npm`](https://npmjs.org) to install:
54
55```sh
56$ npm install --save jalaali-js
57```
58
59Then import it:
60
61```js
62var jalaali = require('jalaali-js')
63```
64
65
66### Browser
67
68Use [`component`](https://github.com/component/component) to install:
69
70```sh
71$ component install jalaali/jalaali-js
72```
73
74Then import it:
75
76```js
77var jalaali = require('jalaali-js')
78```
79
80Or use a CDN:
81```
82<script src="https://cdn.jsdelivr.net/npm/jalaali-js/dist/jalaali.js"></script>
83<script src="https://cdn.jsdelivr.net/npm/jalaali-js/dist/jalaali.min.js"></script>
84
85<script src="https://unpkg.com/jalaali-js/dist/jalaali.js"></script>
86<script src="https://unpkg.com/jalaali-js/dist/jalaali.min.js"></script>
87```
88
89## API
90
91### toJalaali(gy, gm, gd)
92
93Converts a Gregorian date to Jalaali.
94
95```js
96jalaali.toJalaali(2016, 4, 11) // { jy: 1395, jm: 1, jd: 23 }
97```
98
99### toJalaali(date)
100
101Converts a JavaScript Date object to Jalaali.
102
103```js
104jalaali.toJalaali(new Date(2016, 3, 11)) // { jy: 1395, jm: 1, jd: 23 }
105```
106
107### toGregorian(jy, jm, jd)
108
109Converts a Jalaali date to Gregorian.
110
111```js
112jalaali.toGregorian(1395, 1, 23) // { gy: 2016, gm: 4, gd: 11 }
113```
114
115### isValidJalaaliDate(jy, jm, jd)
116
117Checks whether a Jalaali date is valid or not.
118
119```js
120jalaali.isValidJalaaliDate(1394, 12, 30) // false
121jalaali.isValidJalaaliDate(1395, 12, 30) // true
122```
123
124### isLeapJalaaliYear(jy)
125
126Is this a leap year or not?
127
128```js
129jalaali.isLeapJalaaliYear(1394) // false
130jalaali.isLeapJalaaliYear(1395) // true
131```
132
133### jalaaliMonthLength(jy, jm)
134
135Number of days in a given month in a Jalaali year.
136
137```js
138jalaali.jalaaliMonthLength(1394, 12) // 29
139jalaali.jalaaliMonthLength(1395, 12) // 30
140```
141
142### jalCal(jy)
143
144This function determines if the Jalaali (Persian) year is leap (366-day long) or is the common year (365 days), and finds the day in March (Gregorian calendar) of the first day of the Jalaali year (jy).
145
146```js
147jalaali.jalCal(1390) // { leap: 3, gy: 2011, march: 21 }
148jalaali.jalCal(1391) // { leap: 0, gy: 2012, march: 20 }
149jalaali.jalCal(1392) // { leap: 1, gy: 2013, march: 21 }
150jalaali.jalCal(1393) // { leap: 2, gy: 2014, march: 21 }
151jalaali.jalCal(1394) // { leap: 3, gy: 2015, march: 21 }
152jalaali.jalCal(1395) // { leap: 0, gy: 2016, march: 20 }
153```
154
155### j2d(jy, jm, jd)
156
157Converts a date of the Jalaali calendar to the Julian Day number.
158
159```js
160jalaali.j2d(1395, 1, 23) // 2457490
161```
162
163### d2j(jdn)
164
165Converts the Julian Day number to a date in the Jalaali calendar.
166
167```js
168jalaali.d2j(2457490) // { jy: 1395, jm: 1, jd: 23 }
169```
170
171### g2d(gy, gm, gd)
172
173Calculates the Julian Day number from Gregorian or Julian calendar dates. This integer number corresponds to the noon of the date (i.e. 12 hours of Universal Time). The procedure was tested to be good since 1 March, -100100 (of both calendars) up to a few million years into the future.
174
175```js
176jalaali.g2d(2016, 4, 11) // 2457490
177```
178
179### d2g(jdn)
180
181Calculates Gregorian and Julian calendar dates from the Julian Day number (jdn) for the period since jdn=-34839655 (i.e. the year -100100 of both calendars) to some millions years ahead of the present.
182
183```js
184jalaali.d2g(2457490) // { gy: 2016, gm: 4, gd: 11 }
185```
186
187### jalaaliToDateObject(jy, jm, jd)
188
189Convert Jalaali calendar date to javascript Date object by giving Jalaali year, month, and day.
190
191```js
192jalaali.jalaaliToDateObject(1400, 4, 30) // new Date(2021, 6, 21)
193```
194
195### jalaaliWeek(jy, jm, jd)
196
197Return Saturday and Friday day of current week(week start in Saturday)
198
199```js
200jalaali.jalaaliWeek(1400, 4, 30) // { saturday: { jy: 1400, jm: 4, jd: 26 }, friday: { jy: 1400, jm: 5, jd: 1 } }
201```
202
203## License
204
205MIT