Quick Start

This guide covers the most common use cases in temporal-hijri. All examples use uaqCalendar (Umm al-Qura). For FCNA/ISNA output, substitute fcnaCalendar.

Installation

pnpm add temporal-hijri hijri-core @js-temporal/polyfill

hijri-core is required. @js-temporal/polyfill is required in environments without native Temporal support. In environments with native Temporal (Node 22+ with the flag, or future standard support), omit the polyfill.

Import

import { Temporal } from '@js-temporal/polyfill'; // or use native Temporal
import { uaqCalendar } from 'temporal-hijri';

Convert an ISO date to Hijri

const isoDate = Temporal.PlainDate.from('2023-03-23');

console.log(uaqCalendar.year(isoDate));       // 1444
console.log(uaqCalendar.month(isoDate));      // 9
console.log(uaqCalendar.day(isoDate));        // 1
console.log(uaqCalendar.monthCode(isoDate));  // 'M09'

Convert Hijri coordinates to ISO

const ramadan = uaqCalendar.dateFromFields({ year: 1444, month: 9, day: 1 });
console.log(ramadan.toString()); // '2023-03-23'

Date arithmetic in Hijri space

const { Duration } = Temporal;

const isoDate = Temporal.PlainDate.from('2023-03-23');

// Add one Hijri month
const nextMonth = uaqCalendar.dateAdd(isoDate, new Duration(0, 1));
console.log(uaqCalendar.month(nextMonth)); // 10 (Shawwal)
console.log(nextMonth.toString());          // '2023-04-21'

// Get the difference between two dates
const earlier = Temporal.PlainDate.from('2023-01-01');
const later   = Temporal.PlainDate.from('2023-03-23');
const diff = uaqCalendar.dateUntil(earlier, later, { largestUnit: 'months' });
console.log(diff.months); // 2 (in Hijri months)

Use the FCNA calendar

import { fcnaCalendar } from 'temporal-hijri';

const isoDate = Temporal.PlainDate.from('2023-03-23');
console.log(fcnaCalendar.year(isoDate));  // 1444
console.log(fcnaCalendar.month(isoDate)); // 9 or may differ by 1 near month start

Singletons vs classes

The package exports convenience singletons for the common case:

import { uaqCalendar, fcnaCalendar } from 'temporal-hijri';

If you need to construct a calendar from a custom hijri-core engine:

import { HijriCalendar } from 'temporal-hijri';
import { registerCalendar, getCalendar } from 'hijri-core';

registerCalendar('my-engine', myEngine);
const cal = new HijriCalendar(getCalendar('my-engine'));

CommonJS

const { Temporal } = require('@js-temporal/polyfill');
const { uaqCalendar } = require('temporal-hijri');

const isoDate = Temporal.PlainDate.from('2023-03-23');
console.log(uaqCalendar.year(isoDate)); // 1444

Next steps

API Reference for all calendar protocol methods
Architecture for how the Temporal Calendar Protocol is implemented

2.8 KiB Raw Blame History