Intl Date

Convert, format, compare, and manipulate dates across Gregorian, Hijri (Islamic), Umm al-Qura, and Persian (Jalali) calendar systems in JavaScript and TypeScript.

Intl Date is an immutable, dependency-free, ESM-only date library with a small, type-safe API for applications that need calendar conversion, localized date handling, or date arithmetic.

Features

• Simple and type-safe API
• Immutable objects
• Supports 7 calendar systems
• Date conversion, formatting, comparison, and arithmetic
• Tiny: 1kB (minified + gzipped)
• Zero runtime dependencies

Supported Calendars

Identifier	Calendar
gregorian	Gregorian calendar
islamic	Islamic calendar
islamic-umalqura	Umm al-Qura calendar
islamic-rgsa	Islamic calendar for Saudi Arabia
islamic-civil	Islamic civil calendar
islamic-tbla	Islamic tabular calendar
persian	Persian (Jalali) calendar

Installation

npm install intl-date

Example

import { IntlDate } from 'intl-date';

const date = IntlDate.of('islamic-umalqura', 1377, 3, 22);

date.toString('gregorian'); // 1957-10-16
date.getYear('gregorian'); // 1957
date.getMonth('gregorian'); // 10
date.getDay('gregorian'); // 16

date.toString('islamic-umalqura'); // 1377-03-22
date.getYear('islamic-umalqura'); // 1377
date.getMonth('islamic-umalqura'); // 3
date.getDay('islamic-umalqura'); // 22

date.toString('persian'); // 1336-07-24
date.getYear('persian'); // 1336
date.getMonth('persian'); // 7
date.getDay('persian'); // 24

API

Different ways to create IntlDate objects

of - Create IntlDate from a year, month, and day

const date = IntlDate.of('islamic-umalqura', 1377, 3, 22);

from - Create IntlDate from a Javascript Date object

const jsDate = new Date(2017, 11, 25);
const intlDate = IntlDate.from(jsDate);

parse - Create IntlDate from a string

const date = IntlDate.parse('gregorian', '1957-05-16');

today - Create IntlDate for today's date

const date = IntlDate.today();

Getters

getYear

const year = date.getYear('islamic-umalqura');

getMonth

const month = date.getMonth('gregorian');

getDay

const day = date.getDay('persian');

getDayOfWeek

const dayOfWeek = date.getDayOfWeek();

getQuarter

const quarter = date.getQuarter('gregorian');

Manipulative operations (produces new immutable IntlDate objects)

plusDays

const oldDate = IntlDate.of('gregorian', 1957, 10, 16);
const newDate = oldDate.plusDays(20);

oldDate.toString('gregorian'); // 1957-10-16
newDate.toString('gregorian'); // 1957-11-05

minusDays

const oldDate = IntlDate.of('gregorian', 1957, 10, 16);
const newDate = oldDate.minusDays(20);

oldDate.toString('gregorian'); // 1957-10-16
newDate.toString('gregorian'); // 1957-09-26

Comparing IntlDate objects

isEqual

const date1 = IntlDate.of('gregorian', 1957, 10, 16);
const date2 = IntlDate.of('islamic-umalqura', 1377, 3, 22);
const result = date1.isEqual(date2); // true

isBefore

const date1 = IntlDate.of('gregorian', 1957, 10, 15);
const date2 = IntlDate.of('islamic-umalqura', 1377, 3, 22);
const result = date1.isBefore(date2); // true

isAfter

const date1 = IntlDate.of('gregorian', 1957, 10, 17);
const date2 = IntlDate.of('islamic-umalqura', 1377, 3, 22);
const result = date1.isAfter(date2); // true

isBetween

const date1 = IntlDate.of('gregorian', 1957, 10, 16);
const date2 = IntlDate.of('gregorian', 1957, 10, 20);
const date3 = IntlDate.of('gregorian', 1957, 10, 25);
const result = date2.isBetween(date1, date3); // true

daysUntil

const date1 = IntlDate.of('gregorian', 1957, 10, 16);
const date2 = IntlDate.of('gregorian', 1957, 11, 20);
const days = date1.daysUntil(date2); // 35

min

const date1 = IntlDate.of('gregorian', 1957, 10, 16);
const date2 = IntlDate.of('gregorian', 1957, 10, 20);
const min = IntlDate.min(date1, date2); // date1

max

const date1 = IntlDate.of('gregorian', 1957, 10, 16);
const date2 = IntlDate.of('gregorian', 1957, 10, 20);
const max = IntlDate.max(date1, date2); // date2

String operations

format

const date = IntlDate.of('gregorian', 2022, 7, 11);
const formattedString = date.format('gregorian', 'yyyy-MM-dd'); // 2022-07-11

toString

const date = IntlDate.of('gregorian', 2022, 7, 11);
const string = date.toString('gregorian'); // 2022-07-11

License

Copyright 2022 Khalid H. Alharisi

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

    http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.