luxon-hijri/dist/index.d.mts

Hijri/Gregorian date conversion and formatting using the Umm al-Qura calendar. Built on Luxon. Supports toHijri, toGregorian, formatHijriDate, and isValidHijriDate.

import { ConversionOptions, HijriDate } from 'hijri-core';
export { ConversionOptions, HijriDate, HijriYearRecord, hDatesTable, hmLong, hmMedium, hmShort, hwLong, hwNumeric, hwShort, isValidHijriDate, toHijri } from 'hijri-core';

/**
 * Purpose: Reference map of all supported format tokens to their human-readable descriptions.
 * Inputs: n/a — static data export
 * Outputs: Record<string, string> mapping token string to description
 * Constraints: keys must match the TOKEN_RE in formatHijriDate.ts; used for documentation and introspection
 * SPORT: packages.md — luxon-hijri row
 */
declare const formatPatterns: {
    iYYYY: string;
    iYY: string;
    iMM: string;
    iM: string;
    iMMM: string;
    iMMMM: string;
    iDD: string;
    iD: string;
    iE: string;
    iEEE: string;
    iEEEE: string;
    HH: string;
    H: string;
    hh: string;
    h: string;
    mm: string;
    m: string;
    ss: string;
    s: string;
    a: string;
    iooo: string;
    ioooo: string;
    z: string;
    zz: string;
    zzz: string;
    Z: string;
    ZZ: string;
};

/**
 * Purpose: Shared type definitions for luxon-hijri's public API.
 * Inputs: n/a — type-only exports
 * Outputs: HijriDate, HijriYearRecord, ConversionOptions (re-exported from hijri-core), CalendarSystem
 * Constraints: CalendarSystem covers built-in engines only; hijri-core accepts any string via registerCalendar()
 * SPORT: packages.md — luxon-hijri row
 */

/**
 * Built-in calendar system identifiers.
 *
 * - `'uaq'`: Umm al-Qura (default). Table-based, covers 1318-1500 AH / 1900-2076 CE.
 * - `'fcna'`: FCNA/ISNA. Astronomical calculation, works for all Hijri years >= 1 AH.
 *
 * hijri-core accepts any string identifier via `registerCalendar()`. This type covers
 * the built-in defaults only.
 */
type CalendarSystem = "uaq" | "fcna";

/**
 * Convert a Hijri date to a Gregorian Date object.
 *
 * Unlike the hijri-core function (which returns null for invalid input), this
 * wrapper throws an Error so callers always receive a valid Date.
 *
 * @param hy - Hijri year
 * @param hm - Hijri month (1-12)
 * @param hd - Hijri day (1-30)
 * @param options - conversion options (calendar engine selection)
 * @returns a UTC Date corresponding to the given Hijri date
 * @throws {Error} if the Hijri date is invalid or out of range
 */
declare function toGregorian(hy: number, hm: number, hd: number, options?: ConversionOptions): Date;

/**
 * Format a Hijri date using a token-based format string.
 *
 * Hijri-specific tokens use the `i` prefix (iYYYY, iMM, iDD, iEEEE, etc.).
 * Time and timezone tokens (HH, mm, ss, a, Z, z) are delegated to Luxon via the
 * corresponding Gregorian date.
 *
 * @param hijriDate - the Hijri date to format
 * @param format - a format string containing Hijri and/or Luxon tokens
 * @returns the formatted date string
 * @throws {RangeError} if the Hijri month is outside the 1-12 range
 */
declare function formatHijriDate(hijriDate: HijriDate, format: string): string;

export { type CalendarSystem, formatHijriDate, formatPatterns, toGregorian };