mirror of
https://github.com/acamarata/temporal-hijri.git
synced 2026-07-01 11:24:29 +00:00
51e07a65b3
Temporal Calendar Protocol implementation for Hijri calendar via hijri-core. Provides HijriCalendar base class, UaqCalendar (UAQ engine), FcnaCalendar (FCNA engine), and convenience singletons uaqCalendar/fcnaCalendar. Calendar protocol: year, month, monthCode, day, daysInMonth, daysInYear, monthsInYear, inLeapYear, dayOfWeek, dayOfYear, weekOfYear, daysInWeek, dateFromFields, yearMonthFromFields, monthDayFromFields, dateAdd, dateUntil, mergeFields. dateAdd applies year/month increments in Hijri coordinate space (correct semantics for variable-length lunar months), then applies days/weeks in ISO space. Day-of-month clamped on month boundary changes. 18 ESM + 8 CJS tests passing. Dual CJS/ESM build.
164 lines
4.5 KiB
Markdown
164 lines
4.5 KiB
Markdown
# API Reference
|
||
|
||
## Exports
|
||
|
||
```typescript
|
||
// Classes
|
||
export { HijriCalendar } from 'temporal-hijri';
|
||
export { UaqCalendar } from 'temporal-hijri';
|
||
export { FcnaCalendar } from 'temporal-hijri';
|
||
|
||
// Singletons
|
||
export { uaqCalendar } from 'temporal-hijri'; // new UaqCalendar()
|
||
export { fcnaCalendar } from 'temporal-hijri'; // new FcnaCalendar()
|
||
|
||
// Types (re-exported from hijri-core)
|
||
export type { HijriDate, ConversionOptions } from 'temporal-hijri';
|
||
export type { HijriCalendarOptions } from 'temporal-hijri';
|
||
```
|
||
|
||
---
|
||
|
||
## `HijriCalendar`
|
||
|
||
Base class. Implements the Temporal Calendar Protocol using a `CalendarEngine` from hijri-core.
|
||
|
||
### Constructor
|
||
|
||
```typescript
|
||
new HijriCalendar(engine: CalendarEngine)
|
||
```
|
||
|
||
Accepts any engine registered via hijri-core's `registerCalendar()`. The calendar's `id` is `hijri-${engine.id}`.
|
||
|
||
---
|
||
|
||
## `UaqCalendar`
|
||
|
||
```typescript
|
||
new UaqCalendar()
|
||
```
|
||
|
||
Wraps the `uaq` engine from hijri-core. Calendar ID: `"hijri-uaq"`.
|
||
|
||
---
|
||
|
||
## `FcnaCalendar`
|
||
|
||
```typescript
|
||
new FcnaCalendar()
|
||
```
|
||
|
||
Wraps the `fcna` engine from hijri-core. Calendar ID: `"hijri-fcna"`.
|
||
|
||
---
|
||
|
||
## Calendar Protocol Methods
|
||
|
||
All methods are available on `HijriCalendar`, `UaqCalendar`, and `FcnaCalendar`. Each method receives a `Temporal.PlainDate` with the ISO (Gregorian) calendar.
|
||
|
||
### Field accessors
|
||
|
||
| Method | Signature | Returns | Notes |
|
||
|---|---|---|---|
|
||
| `year` | `(date: PlainDate) => number` | Hijri year | |
|
||
| `month` | `(date: PlainDate) => number` | Hijri month (1-12) | |
|
||
| `monthCode` | `(date: PlainDate) => string` | `"M01"` – `"M12"` | Zero-padded |
|
||
| `day` | `(date: PlainDate) => number` | Day of month (1-29/30) | |
|
||
|
||
### Year and month metrics
|
||
|
||
| Method | Signature | Returns | Notes |
|
||
|---|---|---|---|
|
||
| `daysInMonth` | `(date: PlainDate) => number` | 29 or 30 | Varies by month and calendar |
|
||
| `daysInYear` | `(date: PlainDate) => number` | 354 or 355 | Sum of all 12 months |
|
||
| `monthsInYear` | `(date: PlainDate) => number` | Always 12 | |
|
||
| `inLeapYear` | `(date: PlainDate) => boolean` | `true` if 355-day year | |
|
||
|
||
### Week and day position
|
||
|
||
| Method | Signature | Returns | Notes |
|
||
|---|---|---|---|
|
||
| `dayOfWeek` | `(date: PlainDate) => number` | 1-7 (Mon=1, Sun=7) | ISO weekday |
|
||
| `dayOfYear` | `(date: PlainDate) => number` | 1-354 or 1-355 | Within the Hijri year |
|
||
| `weekOfYear` | `(date: PlainDate) => number` | 1-51 | `ceil(dayOfYear / 7)` |
|
||
| `daysInWeek` | `(date: PlainDate) => number` | Always 7 | |
|
||
|
||
### Construction from fields
|
||
|
||
| Method | Signature | Returns |
|
||
|---|---|---|
|
||
| `dateFromFields` | `(fields: {year, month, day}, options?) => PlainDate` | ISO `PlainDate` |
|
||
| `yearMonthFromFields` | `(fields: {year, month}, options?) => PlainYearMonth` | ISO `PlainYearMonth` |
|
||
| `monthDayFromFields` | `(fields: {month, day, year?}, options?) => PlainMonthDay` | ISO `PlainMonthDay` |
|
||
|
||
`monthDayFromFields` uses year 1444 AH as a default reference if no year is supplied.
|
||
|
||
### Arithmetic
|
||
|
||
#### `dateAdd`
|
||
|
||
```typescript
|
||
dateAdd(
|
||
date: Temporal.PlainDate,
|
||
duration: Temporal.Duration,
|
||
options?: { overflow?: 'constrain' | 'reject' }
|
||
): Temporal.PlainDate
|
||
```
|
||
|
||
Adds a duration to a Hijri date. Year and month components are applied in Hijri space (preserving calendar semantics); day and week components are applied in ISO space afterward.
|
||
|
||
When a month addition causes the day-of-month to exceed the target month's length, the day is clamped to the last valid day of that month.
|
||
|
||
#### `dateUntil`
|
||
|
||
```typescript
|
||
dateUntil(
|
||
one: Temporal.PlainDate,
|
||
two: Temporal.PlainDate,
|
||
options?: { largestUnit?: 'years' | 'months' | 'weeks' | 'days' }
|
||
): Temporal.Duration
|
||
```
|
||
|
||
Computes the difference between two dates. When `largestUnit` is `'years'` or `'months'`, the difference is calculated in Hijri space. For `'days'` and `'weeks'` it delegates to ISO arithmetic, which is exact.
|
||
|
||
### Other
|
||
|
||
| Method | Signature | Returns |
|
||
|---|---|---|
|
||
| `mergeFields` | `(fields, additionalFields) => Record` | Merged field object |
|
||
| `toString` | `() => string` | Calendar identifier |
|
||
|
||
---
|
||
|
||
## Types
|
||
|
||
### `HijriDate` (from hijri-core)
|
||
|
||
```typescript
|
||
interface HijriDate {
|
||
hy: number; // Hijri year
|
||
hm: number; // Hijri month (1-12)
|
||
hd: number; // Hijri day (1-30)
|
||
}
|
||
```
|
||
|
||
### `ConversionOptions` (from hijri-core)
|
||
|
||
```typescript
|
||
interface ConversionOptions {
|
||
calendar?: string; // defaults to 'uaq'
|
||
}
|
||
```
|
||
|
||
### `HijriCalendarOptions`
|
||
|
||
```typescript
|
||
interface HijriCalendarOptions {
|
||
calendar?: string;
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
[Home](Home) · [API Reference](API-Reference) · [Architecture](Architecture)
|