temporal-hijri/.wiki/API-Reference.md

# 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)