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

API Reference

Exports

// 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

new HijriCalendar(engine: CalendarEngine)

Accepts any engine registered via hijri-core's registerCalendar(). The calendar's id is hijri-${engine.id}.

---

UaqCalendar

new UaqCalendar()

Wraps the uaq engine from hijri-core. Calendar ID: "hijri-uaq".

---

FcnaCalendar

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

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

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)

interface HijriDate {
  hy: number; // Hijri year
  hm: number; // Hijri month (1-12)
  hd: number; // Hijri day (1-30)
}

ConversionOptions (from hijri-core)

interface ConversionOptions {
  calendar?: string; // defaults to 'uaq'
}

HijriCalendarOptions

interface HijriCalendarOptions {
  calendar?: string;
}

---

Home · API Reference · Architecture