quran-meta/dist/index.d.mts

Library with meta data and functionality related to Holy Quran

type QuranMeta = {
    numAyahs: number;
    numSurahs: number;
    numPages: number;
    numJuzs: number;
    numHizbs: number;
    numRubAlHizbs: number;
    numSajdas: number;
    numRukus: number;
    numManzils: number;
};
declare const meta: Readonly<QuranMeta>;

type Surah = number;
type AyahNo = number;
type AyahId = number;
type Page = number;
type Juz = number;
type JuzHizb = {
    juz: Juz;
    juzPart: number;
    hizbId: number;
    rubAlHizbId: number;
};
type SurahAyah = [Surah, AyahNo];
type AyahRange = [AyahId, AyahId];
type SurahAyahSegment = [Surah, AyahNo | [AyahNo, AyahNo]];
type PageMeta = {
    pageNum: Page;
    first: SurahAyah;
    last: SurahAyah;
};
type JuzMeta = {
    leftjuz: Juz;
    ayahsBetweenJuzSurah: number;
    rightJuz: Juz;
    leftAyahId: AyahId;
    rightAyahId: AyahId;
};
type SajdaType = "recommended" | "obligatory";
type Sajda = [AyahId, SajdaType];
type SurahMeta = [
    startAyahId: AyahId,
    ayahCount: number,
    surahOrder: number,
    rukuCount: number,
    name: string,
    isMeccan: boolean,
    page: Page
];
type SurahName = [name: string, translitName: string];
type AyahMeta = {
    juz: number;
    juzPart: number;
    hizbId: number;
    rubAlHizbId: number;
    surah: number;
    ayah: number;
    isStartOfQuarter: boolean;
    isEndOfQuarter: boolean;
    isSajdahAyah: boolean;
    isStartOfPage: boolean;
    isEndOfPage: boolean;
    isStartOfJuz: boolean;
    isEndOfJuz: boolean;
    isStartOfSurah: boolean;
    isEndOfSurah: boolean;
};

/**
 *  Turns String of type "x:y" or "x:y1-y2" to array [x,y] or [x,[y1,y2]] respectively
 * @param str - String of type "x:y" or "x:y1-y2"
 * @returns array [x,y] or [x,[y1,y2]] respectively
 */
declare function ayahStringSplitter(str: string): SurahAyahSegment;

/**
 * Get the ayah ID for the given surah and ayah number.
 * @param surah - The surah number.
 * @param ayah - The ayah number within the surah.
 * @returns The ayah ID for the given surah and ayah number.
 */
declare function findAyahIdBySurah(surah: Surah, ayah: AyahNo): AyahId;

/**
 * Finds the Juz (part) of the Quran that the given Ayah (verse) belongs to.
 *
 * @param surah - The Surah (chapter) number.
 * @param ayah - The Ayah (verse) number. Defaults to 1 if not provided.
 * @param ayahMode - If true, the `ayah` parameter is treated as an Ayah ID instead of a Surah and Ayah number.
 * @returns The Juz (part) number that the given Ayah belongs to.
 */
declare function findJuz(surah: Surah, ayah?: AyahNo, ayahMode?: boolean): Juz;

/**
 * Finds the juz (section) that contains the specified ayah (verse) and calculates the number of ayahs between the start of the juz and the start of the surah (chapter) that contains the ayah.
 *
 * @param surah - The surah (chapter) that contains the ayah.
 * @param ayah - The ayah (verse) number.
 * @param ayahMode - A boolean flag indicating whether the `ayah` parameter represents an ayah number or an ayah ID.
 * @returns An object containing the following properties:
 *   - `juz`: The juz (section) that contains the ayah.
 *   - `leftAyahId`: The ayah ID of the first ayah in the juz.
 *   - `ayahsBetweenJuzSurah`: The number of ayahs between the start of the juz and the start of the surah (positive if the surah starts is in the juz, negative if the surah starts before the juz).
 */
declare function findJuzAndShift(surah: Surah, ayah: AyahNo, ayahMode?: boolean): {
    juz: Juz;
    leftAyahId: AyahId;
    ayahsBetweenJuzSurah: number;
};

/**
 * Finds the Juz (part) of the Quran that contains the given Ayah (verse) ID.
 *
 * @param ayahId - The ID of the Ayah (verse) to find the Juz for.
 * @returns The Juz (part) of the Quran that contains the given Ayah ID.
 */
declare function findJuzByAyahId(ayahId: AyahId): Juz;

/**
 * Finds the JuzMeta for a given Surah and Ayah.
 *
 * @param surah - The Surah (chapter) number.
 * @param ayah - The Ayah (verse) number.
 * @returns The JuzMeta object containing the left juz, ayahs between juz and surah, right juz, left ayah ID, and right ayah ID.
 */
declare function findJuzMetaBySurah(surah: Surah, ayah?: AyahNo): JuzMeta;

/**
 * Finds the page number for the given Surah and Ayah number.
 *
 * @param surah - The Surah to find the page for.
 * @param ayah - The Ayah number to find the page for.
 * @param ayahMode - If true, the `ayah` parameter is treated as an AyahId instead of an AyahNo.
 * @returns The page number for the given Surah and Ayah.
 */
declare function findPage(surah: Surah, ayah: AyahNo, ayahMode?: boolean): Page;

/**
 * Finds a range of ayahs around a given ayah based on the specified mode.
 *
 * @param surah - The surah number (1-114)
 * @param ayah - The ayah number within the surah, or the absolute ayah ID if ayahMode is true
 * @param mode - The range mode: "juz", "surah", "ayah", "page", or "all"
 * @param ayahMode - If true, treats the ayah parameter as an absolute ayah ID
 * @returns A tuple containing the start and end ayah IDs of the range
 */
declare function findRangeAroundAyah(surah: Surah, ayah: AyahNo, mode: "juz" | "surah" | "ayah" | "page" | "all", ayahMode?: boolean): AyahRange;

/**
 * Finds the Juz (part) and Rub-ul-Hizb/Maqra (quarter section) of the Quran that the given Ayah (verse) belongs to.
 *
 * @param surah - The Surah (chapter) number.
 * @param ayah - The Ayah (verse) number. Defaults to 1 if not provided.
 * @param ayahMode - If true, the `ayah` parameter is treated as an Ayah ID instead of a Surah and Ayah number.
 * @returns An object containing the Juz (part) number, Hizb (section) number, and the index of the Hizb that the given Ayah belongs to.
 */
declare function findRubAlHizb(surah: Surah, ayah?: AyahNo, ayahMode?: boolean): JuzHizb;

/**
 * Finds the Maqra/Rub-al-Hizb  of the Quran that contains the given Ayah (verse) ID.
 *
 * @param ayahId - The ID of the Ayah (verse) to find the Juz for.
 * @returns The Maqra of the Quran that contains the given Ayah ID.
 */
declare function findRubAlHizbByAyahId(ayahId: AyahId): Juz;

/**
 * Finds the Surah (chapter) and Ayah (verse) numbers that the given Ayah ID belongs to.
 *
 * @param ayaId - The Ayah ID to find the Surah and Ayah numbers for.
 * @returns An array containing the Surah number and the Ayah number within that Surah.
 */
declare function findSurahByAyahId(ayaId: AyahId): SurahAyah;

/**
 * Get the number of ayahs (verses) in the specified surah.
 * @param surah - The surah number.
 * @returns The number of ayahs in the specified surah.
 */
declare function getAyahCountInSurah(surah: Surah): number;

/**
 * Retrieves metadata for a specific ayah of the Quran.
 *
 * @param ayahId - The ayahId number to retrieve metadata for (1-6236)
 * @returns An object containing the ayah related meta, including information about the surah, juz, and quarter the ayah is in.
 * @throws RangeError If the ayahId number is not between 1 and 6236
 */
declare function getAyahMeta(ayahId: Page): AyahMeta;

declare const partNames: readonly ["surah", "juz", "page", "manzil", "rubAlHizb", "ruku"];
type PartType = (typeof partNames)[number];
type PartBlock = {
    startAyahId: AyahId;
    ayahCount: number;
};
/**
 * Retrieves a list of part blocks for the specified part type.
 *
 * @param type - The type of part to retrieve the list for, such as "surah", "juz", "page", "manzil", "ruku" or "rubAlHizb".
 * @returns An array of part blocks, where each part block contains the starting ayah ID and the ayah count for that part.
 */
declare function getList(type: PartType): PartBlock[];

/**
 * Retrieves metadata for a specific page of the Quran.
 *
 * @param pageNum - The page number to retrieve metadata for (1-604)
 * @returns An object containing the page number, first ayah, and last ayah on the page
 * @throws RangeError If the page number is not between 1 and 604
 */
declare function getPageMeta(pageNum: Page): PageMeta;

/**
 * Retrieves the metadata for a specific quarter (rub' al-hizb) of the Quran.
 *
 * @param quarterIndex - The index of the quarter (rub' al-hizb) to retrieve metadata for, where 1 is the first quarter.
 * @returns An object containing the metadata for the specified quarter, including the juz' (part), hizb (section), and the quarter (rub' al-hizb) index.
 */
declare function getRubAlHizbMeta(quarterIndex: number): JuzHizb;

/**
 * Finds the Juz, Hizb, and Rub-el-Hizb id for the given Ayah ID.
 *
 * @param ayahId - The Ayah ID to find the Juz, Hizb, and Hizb ID for.
 * @returns An object containing the Juz, Hizb, and Hizb ID for the given Ayah ID.
 */
declare function getRubAlHizbMetaByAyahId(ayahId: AyahId): JuzHizb;

/**
 * Gets the metadata for the specified Surah.
 *
 * @param surah - The Surah to get the metadata for.
 * @returns The metadata for the specified Surah.
 */
declare function getSurahMeta(surah: Surah): SurahMeta;

/**
 * Returns the Juz (part) number that the given Ayah (verse) belongs to.
 *
 *
 * @param surah - The Surah (chapter) number.
 * @param ayah - The Ayah (verse) number.
 * @param ayahMode - If true, the `ayah` parameter is treated as an Ayah ID instead of a Surah and Ayah number.
 * @returns The Juz (part) number that the given Ayah belongs to. Returns Positive number if ayah is first ayah of juz, number is juz number
 */
declare function isAyahJuzFirst(surah: Surah, ayah: AyahNo, ayahMode?: boolean): Juz;

/**
 * Determines if the given ayah is the first ayah of a juz.
 *
 * @param surah - The surah number.
 * @param ayah - The ayah number.
 * @param ayahMode - Optional flag to indicate if the ayah number is already a valid ayah ID.
 * @returns The page number if the ayah is the first ayah of the page, otherwise -1.
 */
declare function isAyahPageFirst(surah: Surah, ayah: AyahNo, ayahMode?: boolean): Page;

declare const HizbQuarterList: AyahId[];

declare const JuzList: AyahId[];

declare const ManzilList: AyahId[];

declare const PageList: AyahId[];

declare const RukuList: AyahId[];

declare const SajdaList: Sajda[];

declare const SurahList: SurahMeta[];

/**
 * Get the next ayah for the given surah and ayah number.
 * @param surah - The surah number.
 * @param ayah - The ayah number within the surah.
 * @returns The surah and ayah number of the next ayah.
 */
declare function nextAyah(surah: Surah, ayah: AyahNo): SurahAyah;

/**
 * Get the previous ayah for the given surah and ayah number.
 * @param surah - The surah number.
 * @param ayah - The ayah number within the surah.
 * @returns The surah and ayah number of the previous ayah.
 */
declare function prevAyah(surah: Surah, ayah: AyahNo): SurahAyah;

/**
 * Checks if the given Surah (chapter) number is valid.
 *
 * @param surah - The Surah (chapter) number to check.
 * @param checkOnly - If true, the function will only check the validity and not throw an error.
 * @returns True if the Surah number is valid, false otherwise.
 */
declare function checkValidSurah(surah: number, checkOnly?: boolean): boolean;
/**
 * Checks if the given Surah and Ayah (verse) numbers are valid.
 *
 * @param surah - The Surah (chapter) number to check.
 * @param ayah - The Ayah (verse) number to check.
 * @param checkOnly - If true, the function will only check the validity and not throw an error.
 * @returns True if the Surah and Ayah numbers are valid, false otherwise.
 */
declare function checkValidSurahAyah(surah: number, ayah: number, checkOnly?: boolean): boolean;
/**
 * Checks if the given Ayah (verse) ID is valid.
 *
 * @param ayahId - The Ayah (verse) ID to check.
 * @param checkOnly - If true, the function will only check the validity and not throw an error.
 * @returns True if the Ayah ID is valid, otherwise throws a RangeError.
 */
declare function checkValidAyahId(ayahId: number, checkOnly?: boolean): boolean;

declare const surahNamesAz: (SurahName | [])[];

declare const surahNamesEn: (SurahName | [])[];

declare const surahNamesRu: (SurahName | [])[];

declare const surahNamesTr: (SurahName | [])[];

export { type AyahId, type AyahMeta, type AyahNo, type AyahRange, HizbQuarterList, type Juz, type JuzHizb, JuzList, type JuzMeta, ManzilList, type Page, PageList, type PageMeta, type QuranMeta, RukuList, type Sajda, SajdaList, type SajdaType, type Surah, type SurahAyah, type SurahAyahSegment, SurahList, type SurahMeta, type SurahName, ayahStringSplitter, checkValidAyahId, checkValidSurah, checkValidSurahAyah, findAyahIdBySurah, findJuz, findJuzAndShift, findJuzByAyahId, findJuzMetaBySurah, findPage, findRangeAroundAyah, findRubAlHizb, findRubAlHizbByAyahId, findSurahByAyahId, getAyahCountInSurah, getAyahMeta, getList, getPageMeta, getRubAlHizbMeta, getRubAlHizbMetaByAyahId, getSurahMeta, isAyahJuzFirst, isAyahPageFirst, meta, nextAyah, prevAyah, surahNamesAz, surahNamesEn, surahNamesRu, surahNamesTr };