mirror of
https://github.com/acamarata/date-fns-hijri.git
synced 2026-07-01 11:14:26 +00:00
202 lines
7 KiB
Markdown
202 lines
7 KiB
Markdown
# date-fns-hijri
|
||
|
||
[](https://www.npmjs.com/package/date-fns-hijri)
|
||
[](https://github.com/acamarata/date-fns-hijri/actions/workflows/ci.yml)
|
||
[](LICENSE)
|
||
|
||
date-fns-style functions for Hijri calendar operations. Works with any date library.
|
||
|
||
Each function is a pure, stateless utility. No classes. No configuration object. Pass a `Date`, get a result. Pass options to switch calendar systems. The API mirrors date-fns conventions so the learning curve is minimal.
|
||
|
||
## Installation
|
||
|
||
```bash
|
||
pnpm add date-fns-hijri hijri-core
|
||
```
|
||
|
||
`hijri-core` is a peer dependency. It provides the underlying calendar engine and must be installed alongside this package.
|
||
|
||
## Quick Start
|
||
|
||
```typescript
|
||
import {
|
||
toHijriDate,
|
||
fromHijriDate,
|
||
formatHijriDate,
|
||
addHijriMonths,
|
||
getHijriMonthName,
|
||
} from 'date-fns-hijri';
|
||
|
||
// Convert a Gregorian date to Hijri
|
||
const hijri = toHijriDate(new Date(2023, 2, 23));
|
||
// { hy: 1444, hm: 9, hd: 1 } - 1 Ramadan 1444
|
||
|
||
// Convert back
|
||
const gregorian = fromHijriDate(1444, 9, 1);
|
||
// Date: 2023-03-23T00:00:00.000Z
|
||
|
||
// Format with Hijri tokens
|
||
const label = formatHijriDate(new Date(2023, 2, 23), 'iDD iMMMM iYYYY');
|
||
// '01 Ramadan 1444'
|
||
|
||
// Get the month name directly
|
||
const name = getHijriMonthName(9);
|
||
// 'Ramadan'
|
||
|
||
// Add months in the Hijri calendar
|
||
const nextMonth = addHijriMonths(new Date(2023, 2, 23), 1);
|
||
// Date in Shawwal 1444
|
||
```
|
||
|
||
## API
|
||
|
||
All functions accept an optional `options` argument for selecting the calendar system. When omitted, Umm al-Qura (UAQ) is used.
|
||
|
||
### Conversion
|
||
|
||
| Function | Signature | Description |
|
||
| --- | --- | --- |
|
||
| `toHijriDate` | `(date: Date, options?) => HijriDate \| null` | Convert Gregorian to Hijri. Returns `null` if out of range. |
|
||
| `fromHijriDate` | `(hy, hm, hd, options?) => Date` | Convert Hijri to Gregorian. Throws if invalid. |
|
||
|
||
### Validation
|
||
|
||
| Function | Signature | Description |
|
||
| --- | --- | --- |
|
||
| `isValidHijriDate` | `(hy, hm, hd, options?) => boolean` | Check if a Hijri date exists in the calendar table. |
|
||
|
||
### Field Getters
|
||
|
||
| Function | Signature | Description |
|
||
| --- | --- | --- |
|
||
| `getHijriYear` | `(date, options?) => number \| null` | Hijri year. Null if out of range. |
|
||
| `getHijriMonth` | `(date, options?) => number \| null` | Hijri month (1-12). Null if out of range. |
|
||
| `getHijriDay` | `(date, options?) => number \| null` | Hijri day of month. Null if out of range. |
|
||
| `getDaysInHijriMonth` | `(hy, hm, options?) => number` | Days in a Hijri month (29 or 30). |
|
||
| `getHijriQuarter` | `(date, options?) => number \| null` | Quarter (1-4). Null if out of range. |
|
||
|
||
### Names
|
||
|
||
| Function | Signature | Description |
|
||
| --- | --- | --- |
|
||
| `getHijriMonthName` | `(hm, length?) => string` | English month name. `length`: `'long'` (default), `'medium'`, `'short'`. |
|
||
| `getHijriWeekdayName` | `(date, length?) => string` | Arabic weekday name. `length`: `'long'` (default), `'short'`. |
|
||
|
||
### Formatting
|
||
|
||
| Function | Signature | Description |
|
||
| --- | --- | --- |
|
||
| `formatHijriDate` | `(date, formatStr, options?) => string` | Format a date with Hijri tokens. Returns `''` if out of range. |
|
||
|
||
### Arithmetic
|
||
|
||
| Function | Signature | Description |
|
||
| --- | --- | --- |
|
||
| `addHijriMonths` | `(date, months, options?) => Date` | Add N Hijri months. Clamps day to month length. |
|
||
| `addHijriYears` | `(date, years, options?) => Date` | Add N Hijri years. Clamps day to month length. |
|
||
|
||
### Month Boundaries
|
||
|
||
| Function | Signature | Description |
|
||
| --- | --- | --- |
|
||
| `startOfHijriMonth` | `(date, options?) => Date` | First day of the containing Hijri month. |
|
||
| `endOfHijriMonth` | `(date, options?) => Date` | Last day of the containing Hijri month. |
|
||
|
||
### Comparisons
|
||
|
||
| Function | Signature | Description |
|
||
| --- | --- | --- |
|
||
| `isSameHijriMonth` | `(dateA, dateB, options?) => boolean` | Both dates in the same Hijri month. |
|
||
| `isSameHijriYear` | `(dateA, dateB, options?) => boolean` | Both dates in the same Hijri year. |
|
||
|
||
## Calendar Systems
|
||
|
||
Two calendar systems are available via the `options.calendar` property.
|
||
|
||
**Umm al-Qura (default):**
|
||
The official calendar of Saudi Arabia. Covers 1318–1500 AH (1900–2076 CE). Tabular data; deterministic.
|
||
|
||
```typescript
|
||
import { toHijriDate } from 'date-fns-hijri';
|
||
|
||
const uaq = toHijriDate(new Date(2023, 2, 23));
|
||
// uses UAQ by default
|
||
```
|
||
|
||
**FCNA/ISNA:**
|
||
The calendar used by the Fiqh Council of North America. Astronomical calculation; extends slightly beyond UAQ's range.
|
||
|
||
```typescript
|
||
const fcna = toHijriDate(new Date(2023, 2, 23), { calendar: 'fcna' });
|
||
```
|
||
|
||
## Format Tokens
|
||
|
||
| Token | Output | Example |
|
||
| --- | --- | --- |
|
||
| `iYYYY` | 4-digit Hijri year | `1444` |
|
||
| `iYY` | 2-digit Hijri year | `44` |
|
||
| `iMMMM` | Long month name | `Ramadan` |
|
||
| `iMMM` | Medium month name | `Ramadan` |
|
||
| `iMM` | Zero-padded month | `09` |
|
||
| `iM` | Month number | `9` |
|
||
| `iDD` | Zero-padded day | `01` |
|
||
| `iD` | Day number | `1` |
|
||
| `iEEEE` | Long weekday name | `Yawm al-Khamis` |
|
||
| `iEEE` | Short weekday name | `Kham` |
|
||
| `iE` | Numeric weekday (1=Sun) | `5` |
|
||
| `ioooo` | Long era | `AH` |
|
||
| `iooo` | Short era | `AH` |
|
||
|
||
Non-token text in the format string passes through unchanged:
|
||
|
||
```typescript
|
||
formatHijriDate(new Date(2023, 2, 23), 'iYYYY-iMM-iDD')
|
||
// '1444-09-01'
|
||
|
||
formatHijriDate(new Date(2023, 2, 23), 'iD iMMMM iYYYY ioooo')
|
||
// '1 Ramadan 1444 AH'
|
||
```
|
||
|
||
## TypeScript
|
||
|
||
Full type definitions are included. Re-exported from `hijri-core`:
|
||
|
||
```typescript
|
||
import type { HijriDate, ConversionOptions } from 'date-fns-hijri';
|
||
|
||
const h: HijriDate = { hy: 1444, hm: 9, hd: 1 };
|
||
const opts: ConversionOptions = { calendar: 'fcna' };
|
||
```
|
||
|
||
## Architecture
|
||
|
||
A thin adapter over [hijri-core](https://github.com/acamarata/hijri-core). Each function is a stateless wrapper that delegates to the registered calendar engine. No global state, no configuration object: pass options per call.
|
||
|
||
For more detail see the [Architecture wiki page](https://github.com/acamarata/date-fns-hijri/wiki/Architecture).
|
||
|
||
## Documentation
|
||
|
||
Full API reference, architecture notes, and examples: [Wiki](https://github.com/acamarata/date-fns-hijri/wiki)
|
||
|
||
## Related
|
||
|
||
- [hijri-core](https://github.com/acamarata/hijri-core) - Zero-dependency Hijri engine powering this library
|
||
- [luxon-hijri](https://github.com/acamarata/luxon-hijri) - Hijri support for Luxon DateTime objects
|
||
- [pray-calc](https://github.com/acamarata/pray-calc) - Islamic prayer times
|
||
- [nrel-spa](https://github.com/acamarata/nrel-spa) - Solar position algorithm
|
||
|
||
## Compatibility
|
||
|
||
- Node.js 20, 22, 24
|
||
- ESM and CJS builds included
|
||
- TypeScript definitions bundled
|
||
- Works in browsers and all major bundlers
|
||
|
||
## Acknowledgments
|
||
|
||
Calendar data and algorithms provided by [hijri-core](https://github.com/acamarata/hijri-core). The Umm al-Qura table is derived from data published by the King Abdulaziz City for Science and Technology (KACST). FCNA new moon calculations follow Jean Meeus, "Astronomical Algorithms," 2nd ed., Chapter 49.
|
||
|
||
## License
|
||
|
||
MIT. Copyright (c) 2026 Aric Camarata.
|