mirror of
https://github.com/acamarata/temporal-hijri.git
synced 2026-07-01 03:14:32 +00:00
98 lines
2.8 KiB
Markdown
98 lines
2.8 KiB
Markdown
# 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
|
|
|
|
```bash
|
|
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
|
|
|
|
```typescript
|
|
import { Temporal } from '@js-temporal/polyfill'; // or use native Temporal
|
|
import { uaqCalendar } from 'temporal-hijri';
|
|
```
|
|
|
|
## Convert an ISO date to Hijri
|
|
|
|
```typescript
|
|
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
|
|
|
|
```typescript
|
|
const ramadan = uaqCalendar.dateFromFields({ year: 1444, month: 9, day: 1 });
|
|
console.log(ramadan.toString()); // '2023-03-23'
|
|
```
|
|
|
|
## Date arithmetic in Hijri space
|
|
|
|
```typescript
|
|
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
|
|
|
|
```typescript
|
|
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:
|
|
|
|
```typescript
|
|
import { uaqCalendar, fcnaCalendar } from 'temporal-hijri';
|
|
```
|
|
|
|
If you need to construct a calendar from a custom hijri-core engine:
|
|
|
|
```typescript
|
|
import { HijriCalendar } from 'temporal-hijri';
|
|
import { registerCalendar, getCalendar } from 'hijri-core';
|
|
|
|
registerCalendar('my-engine', myEngine);
|
|
const cal = new HijriCalendar(getCalendar('my-engine'));
|
|
```
|
|
|
|
## CommonJS
|
|
|
|
```js
|
|
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](API-Reference) for all calendar protocol methods
|
|
- [Architecture](Architecture) for how the Temporal Calendar Protocol is implemented
|