quran/node_modules/@umalqura/core

umalqura

Zero dependency Hijri calendar based on Um AlQura

Getting Started

Run the following npm or yran command:

npm i @umalqura/core
-or-
yarn add @umalqura/core

You can also use the library directly in the browser by adding the following to your html:

<script src="https://unpkg.com/@umalqura/core@0.0.7/dist/umalqura.min.js"></script>

Usage

NodeJS

import uq from '@umalqura/core';

// Initializes a new umalqura instance using current date and time.
const now = uq();
// Do more stuff
// ...

Browser

A global var named umalqura will be available.

// Initializes a new umalqura instance using current date and time.
var now = umalqura();
// Do more stuff
// ...

API

Construction

// Initializes using current date and time.
umalqura();
// Initializes using provided date and time.
umalqura(date: Date);
// Initializes using provided Hijri year, month, day and the optionally provided time.
umalqura(hy: number, hm: number, hd: number, hour?: number, minute?: number, second?: number, millisecond?: number);

The umalqura(...) function returns an initialized umalqura.UmAlQura object which exposes the following properties and methods:

Properties

Name	Description
date	Returns the Date object.
hy	Returns the Hijri year.
hm	Returns the Hijri month.
hd	Returns the Hijri day of month.
dayOfYear	Returns the Hijri day of year.
dayOfWeek	Returns the day of week.
weekOfYear	Returns the Hijri week of year.
daysInYear	Returns the number of days in current Hijri year.
daysInMonth	Returns the number of days in current Hijri month and year.
isLeapYear	Returns true if leap year, false otherwise.
monthArray	Returns the dates of month arranged in a 2D array.

Examples:

import uq from '@umalqura/core';

const d = uq(new Date(2019, 6, 3));  // July 3rd 2019
console.log(d.hy, d.hm, d.hd);       // Outputs 1440, 10, 30

// -or

const d = uq(1440, 10, 30);
console.log(d.date);                 // Outputs Wed Jul 03 2019 00:00:00 TZ...

Methods

Note that all methods are immutably.

Name	Arguments	Description
add	v:number u:unitMs	Returns a new UmAlQura object adding the specified number of Hijri units to the current instance.
subtract	v:number u:unitMs	Returns a new UmAlQura object subtracting the specified number of Hijri units to the current instance.
startOf	u:unit	Returns a new UmAlQura object starting at the specified Hijri unit of time.
endOf	u:unit	Returns a new UmAlQura object ending at the specified Hijri unit of time.
isBefore	cmp:UmAlQura\|Date unit?:unitMs	Returns whether current instance is before cmp. Check can be pinned down to unitMs which defaults to milliseconds.
isAfter	cmp:UmAlQura\|Date unit?:unitMs	Returns whether current instance is after cmp. Check can be pinned down to unitMs which defaults to milliseconds.
isSame	cmp:UmAlQura\|Date unit?:unitMs	Returns whether current instance is same as cmp. Check can be pinned down to unitMs which defaults to milliseconds.
isSameOrBefore	cmp:UmAlQura\|Date unit?:unitMs	Returns whether current instance is same as or before cmp. Check can be pinned down to unitMs which defaults to milliseconds.
isSameOrAfter	cmp:UmAlQura\|Date unit?:unitMs	Returns whether current instance is same as or after cmp. Check can be pinned down to unitMs which defaults to milliseconds.
isBetween	from:UmAlQura\|Date to:UmAlQura\|Date fromIncl?:boolean toIncl?:boolean unit?:unitMs	Returns whether current instance is between from and to. Check can be pinned down to unitMs which defaults to milliseconds. By, default the match is exclusive of both ends. This can be controlled via fromIncl and toIncl.
format	mask:string locale?:string	Returns a formatted string of the Hijri date and time using the specified mask and optionally a locale.

unitMs can be any of the following strings: year, month, week, day, hour, minute, second, millisecond.

unit can be any of the following string: year, month, week, day, hour, minute, second.

Examples:

import uq from '@umalqura/core';

const d = uq(new Date(2019, 6, 3));
// Add 5 Hijri months
const after5HijriMonths = d.add(5, 'month');

// ٣٠/١٠/١٤٤٠
d.format('dd/MM/yyyy', 'ar');
// 30/03/1441
after5HijriMonths.format('dd/MM/yyyy');
// True
after5HijriMonths.isAfter(d);
// Shawwāl 1, 1440
d.startOf('month').format('longDate');

const endOf1440H = d.endOf('year');
// الجمعة، ٢٩ ذو الحجة، ١٤٤٠
endOf1440H.format('fullDate', 'ar');
// Fri Aug 30 2019 23:59:59 TZ...
endOf1440H.date;

The following properties and functions exist directly on the export umalqura object:

Name	Description
VERSION	Returns the library version.
$	Gives access to static methods.
min	Returns the minimum supported Hijri date.
max	Returns the maximum supported Hijri date.
locale(locale?: string)	Gets or sets the local to be used globally.
rtl()	Returns whether current locale supports RTL.
times()	Returns the times names array according to currently set global locale.
days()	Returns the days names array according to currently set global locale.
daysShort()	Returns the short days names array according to currently set global locale.
months()	Returns the Hijri months names array according to currently set global locale.
monthsShort()	Returns the short Hijri month names array according to currently set global locale.
localizeNum(n: number)	Returns a localized string representing the specified number according to currently set global locale.

Examples:

import uq from '@umalqura/core';

// Set global locale to Arabic so that we no longer need to specify a locale when calling format() function.
uq.locale('ar');
// Returns true
uq.rtl();
// Returns ['محرم', 'صفر', 'ربيع الأول', 'ربيع الثاني', 'جمادى الأولى', 'جمادى الآخرة', 'رجب', 'شعبان', 'رمضان', 'شوال', 'ذو القعدة', 'ذو الحجة']
uq.months();

Pre-defined Formatting Masks

Name	Format
default	ddd dd MMM yyyy HH:mm:ss for ar ddd MMM dd yyyy HH:mm:ss for en
shortDate	yy/M/d for ar M/d/yy for en
mediumDate	d MMM, yyyy for ar MMM d, yyyy for en
longDate	d MMMM, yyyy for ar MMMM d, yyyy for en
fullDate	dddd, d MMMM, yyyy for ar dddd, MMMM d, yyyy for en
shortTime	h:mm TT
mediumTime	h:mm:ss TT
longTime	h:mm:ss.l TT

Sample

An HTML-based sample is available in ./sample/browser.html locally or online @ https://umalqura.github.io/.