quran-meta/dist/index.d.ts

Library with meta data and functionality related to Holy Quran

//#region src/const.d.ts
declare const meta: {
  readonly numAyahs: 6236;
  readonly numSurahs: 114;
  readonly numPages: 604;
  readonly numJuzs: 30;
  readonly numHizbs: 60;
  readonly numRubAlHizbs: 240;
  readonly numRubsInJuz: 8;
  readonly numSajdas: 15;
  readonly numRukus: 556;
  readonly numManzils: 7;
};
/**
 * The maximum number of ayahs (verses) that can exist in any surah (chapter) of the Quran.
 * This maximum occurs in Surah Al-Baqarah (2), which has 286 ayahs.
 */
declare const maxAyahsInSurah = 286;
/**
 * Represents the type derived from the `meta` constant containing Quranic metadata.
 * This type encompasses the structure and properties of Quranic information.
 */
type QuranMeta = typeof meta;
//#endregion
//#region src/ts-utils.d.ts
type GrowToSize<T, N extends number, A extends T[]> = A["length"] extends N ? A : GrowToSize<T, N, [...A, T]>;
type FixedArray<T, N extends number> = GrowToSize<T, N, []>;
type ArrayOfSameLength<T extends unknown[], U> = { [K in keyof T]: U };
type LessThan<TNumber extends number, TArray extends unknown[] = []> = TNumber extends TArray["length"] ? TArray[number] : LessThan<TNumber, [...TArray, TArray["length"]]>;
//#endregion
//#region src/lists/surahList.d.ts
declare const SurahList: FixedArray<SurahInfo, 116>;
type SurahListType = typeof SurahList;
//#endregion
//#region src/types.d.ts
/**
 * Creates a type representing a range of numbers from TStart to TEnd (inclusive).
 *
 * @typeParam TStart - The starting number of the range
 * @typeParam TEnd - The ending number of the range
 *
 *
 * @remarks
 * This type uses the Exclude utility type along with a LessThan helper type
 * to generate a union of all numbers within the specified range.
 */
type NumericRange<TStart extends number, TEnd extends number> = Exclude<TEnd | LessThan<TEnd>, LessThan<TStart>>;
/**
 * Represents a valid Surah number in the Quran.
 * A type that ensures the number is within the valid range of Surahs (1 to the total number of Surahs).
 */
type Surah = NumericRange<1, typeof meta.numSurahs>;
/**
 * Represents the number of an ayah (verse) within a surah.
 * Valid values are between 1 and the maximum number of ayahs in any surah.
 *
 */
type AyahNo = NumericRange<1, typeof maxAyahsInSurah>;
/**
 * Represents a valid Rub al-Hizb (quarter of a Hizb) identifier.
 * The value must be a number between 0 and the total number of Rub al-Hizbs in the Quran.
 */
type RubAlHizbId = NumericRange<0, typeof meta.numRubAlHizbs>;
/**
 * Represents a valid Hizb number in the Quran.
 * A Hizb is one of 60 equal divisions of the Quran.
 * A number between 0 and the total number of Hizbs in the Quran
 */
type HizbId = NumericRange<0, typeof meta.numHizbs>;
/**
 * Represents a numeric identifier for an Ayah (verse) in the Quran.
 * The value should be between 0 and the total number of Ayahs.
 */
type AyahId = number;
/**
 * Represents a valid page number within the Quran.
 * The value must be within the range of 0 to the total number of pages (inclusive).
 *
 */
type Page = NumericRange<0, typeof meta.numPages>;
/**
 * Represents a Manzil number in the Quran.
 * A Manzil is one of seven roughly equal parts of the Quran used for sequential reading over seven days.
 * A number between 0 and the total number of Manzils (7)
 */
type Manzil = NumericRange<0, typeof meta.numManzils>;
/**
 * A type representing a valid Ruku (section) number in the Quran.
 * The value must be a number between 0 and the total number of Rukus defined in meta.
 */
type Ruku = NumericRange<0, typeof meta.numRukus>;
/**
 * Represents a Juz (part) number in the Quran.
 * A numeric value ranging from 0 to the total number of Juzs in the Quran.
 * The Quran is traditionally divided into 30 Juzs for ease of recitation and memorization.
 *
 */
type Juz = NumericRange<0, typeof meta.numJuzs>;
/**
 * Represents a part (rub') number within a Juz.
 * A numeric value ranging from 1 to the total number of rub's (quarters) in a Juz.
 * A number constrained between 1 and the total number of rub's in a Juz
 */
type JuzPart = NumericRange<1, typeof meta.numRubsInJuz>;
type SurahInfo = [startAyahId: AyahId, ayahCount: AyahNo, surahOrder: Surah, rukuCount: Ruku, name: string, isMeccan: boolean];
type SurahName = [name: string, translitName: string];
type RangeMeta = {
  firstAyahId: AyahId;
  lastAyahId: AyahId;
  first: SurahAyah;
  last: SurahAyah;
};
/**
 * Represents the structure of a Juz and Hizb combination in the Quran
 */
type RubAlHizb = {
  juz: Juz;
  juzPart: JuzPart;
  hizbId: HizbId;
  rubAlHizbId: RubAlHizbId;
};
type RubAlHizbMeta = RubAlHizb & RangeMeta;
type SurahAyah = [Surah, AyahNo];
type AyahRange = [AyahId, AyahId];
type SurahAyahSegment = [Surah, AyahNo | [AyahNo, AyahNo]];
type SurahMeta = {
  name: string;
  surahNum: Surah;
  ayahCount: AyahNo;
  surahOrder: Surah;
  rukuCount: Ruku;
  isMeccan: boolean;
} & RangeMeta;
type PageMeta = {
  pageNum: Page;
} & RangeMeta;
type ManzilMeta = {
  manzilNum: Manzil;
} & RangeMeta;
type JuzMeta = {
  juzNum: Juz;
} & RangeMeta;
type RukuMeta = {
  rukuNum: Ruku;
} & RangeMeta;
type AyahCountBetweenJuzSurah = NumericRange<0, typeof maxAyahsInSurah>;
type SurahJuzMeta = {
  leftjuz: Juz;
  ayahsBetweenJuzSurah: AyahCountBetweenJuzSurah;
  rightJuz: Juz;
  leftAyahId: AyahId;
  rightAyahId: AyahId;
};
type SajdaType = "recommended" | "obligatory";
type Sajda = [AyahId, SajdaType];
type RangeMode = "juz" | "surah" | "ayah" | "page" | "ruku" | "all";
type AyahMeta = {
  juz: Juz;
  juzPart: JuzPart;
  hizbId: HizbId;
  rubAlHizbId: RubAlHizbId;
  page: Page;
  ruku: number;
  surah: Surah;
  ayah: AyahNo;
  isStartOfQuarter: boolean;
  isEndOfQuarter: boolean;
  isSajdahAyah: boolean;
  isStartOfPage: boolean;
  isEndOfPage: boolean;
  isStartOfJuz: boolean;
  isEndOfJuz: boolean;
  isStartOfSurah: boolean;
  isEndOfSurah: boolean;
  isStartOfRuku: boolean;
  isEndOfRuku: boolean;
};
//#endregion
//#region src/ayahStringSplitter.d.ts
/**
 * Splits a string representation of Quran reference into surah and ayah components
 * @param str - The string to parse, expected format: "surah:ayah" or "surah:ayahStart-ayahEnd"
 * @param isStrict - If true, enforces strict format checking. Defaults to true. If false, allows for additional characters in the string
 * @returns A tuple containing surah number and either a single ayah number or a range [start, end]
 * @throws {@link Error} If the string format is invalid
 * @throws {@link Error} If surah number is invalid
 * @throws {@link Error} If ayah number(s) are invalid
 * @throws {@link sError} If ayah range is invalid (start should be less than end)
 * @example
 * ```ts
 * ayahStringSplitter("2:255") // returns [2, 255]
 * ayahStringSplitter("1:1-7") // returns [1, [1, 7]]
 * ```
 */
declare function ayahStringSplitter(str: string, isStrict?: boolean): SurahAyahSegment;
/**
 * Splits a string containing surah and ayah numbers into their numeric components.
 *
 * @param str - Input string containing numbers separated by non-digits (e.g., "2:255" or "2 255" or "2-255")
 * @returns An object containing the parsed numbers, or null if parsing fails
 *          - ayah: The ayah number if present
 *          - ayahTo: The ending ayah number if a range is specified
 *          - surahOrAyah: The surah number
 * @example
 * stringNumberSplitter("2:255") // returns { ayah: 255, ayahTo: 0, surahOrAyah: 2 }
 * stringNumberSplitter("2:255-260") // returns { ayah: 255, ayahTo: 260, surahOrAyah: 2 }
 * stringNumberSplitter("invalid") // returns null
 */
declare function string2NumberSplitter(str: string): {
  ayah?: number;
  ayahTo?: number;
  surahOrAyah?: number;
} | null;
/**
 * Splits a string in the format "surah:ayah" or "surah:ayah-ayah" into its numeric components.
 *
 * @param str - The input string to parse in the format "surah:ayah" or "surah:ayah-ayah"
 * @returns An object containing the parsed numbers:
 *          - surahOrAyah: The surah number
 *          - ayah: The first or only ayah number
 *          - ayahTo: The ending ayah number (if range specified)
 * @throws {@link Error} When the input string format is invalid or contains non-numeric values
 *
 * @example
 * string2NumberSplitterStrict("2:255")    // returns { surahOrAyah: 2, ayah: 255, ayahTo: NaN }
 * string2NumberSplitterStrict("2:255-260") // returns { surahOrAyah: 2, ayah: 255, ayahTo: 260 }
 */
declare function string2NumberSplitterStrict(str: string): {
  ayah?: number;
  ayahTo?: number;
  surahOrAyah?: number;
} | null;
//#endregion
//#region src/surahStringParser.d.ts
/**
 * Parses a string representation of a Surah number and converts it to a valid Surah type
 * @param str - The string containing the Surah number to parse
 * @returns The parsed Surah number as a Surah type
 * @throws {@link Error} If the string cannot be parsed as a number or if the number is not a valid Surah number
 */
declare function surahStringParser(str: string, isStrict?: boolean): Surah;
//#endregion
//#region src/findAyahIdBySurah.d.ts
/**
 * 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;
//#endregion
//#region src/findJuz.d.ts
/**
 * 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.
 * @returns The Juz (part) number that the given Ayah belongs to.
 */
declare function findJuz(surah: Surah, ayah?: AyahNo): Juz;
//#endregion
//#region src/findJuzAndShift.d.ts
/**
 * 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.
 * @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): {
  juz: Juz;
  leftAyahId: AyahId;
  ayahsBetweenJuzSurah: AyahCountBetweenJuzSurah;
};
/**
 * Finds the Juz number and calculates the shift between Juz start and Surah start for a given Ayah ID
 *
 * @param ayahId - The unique identifier of an Ayah (verse) in the Quran
 *
 * @returns An object containing:
 * - juz: The Juz number where the Ayah is located
 * - leftAyahId: The starting Ayah ID of the Juz
 * - ayahsBetweenJuzSurah: The number of Ayahs between the Juz start and the Surah start
 *
 * @throws Error If the provided Ayah ID is invalid
 */
declare function findJuzAndShiftByAyahId(ayahId: AyahId): {
  juz: Juz;
  leftAyahId: AyahId;
  ayahsBetweenJuzSurah: AyahCountBetweenJuzSurah;
};
//#endregion
//#region src/findJuzByAyahId.d.ts
/**
 * 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;
//#endregion
//#region src/findJuzMetaBySurah.d.ts
/**
 * Finds the SurahJuzMeta for a given Surah and Ayah.
 *
 * @param surah - The Surah (chapter) number.
 * @param ayah - The Ayah (verse) number.
 * @returns The SurahJuzMeta object containing the left juz, ayahs between juz and surah, right juz, ayah ID of first ayah in left juz, and last ayah ID of right juz .
 */
declare function findJuzMetaBySurah(surah: Surah, ayah?: AyahNo): SurahJuzMeta;
//#endregion
//#region src/findManzil.d.ts
/**
 * Finds the Manzil number for a given Surah and Ayah
 * @param surah - The Surah number or object
 * @param ayah - Optional Ayah number (defaults to 1)
 * @returns The Manzil number (1-7) containing the specified Ayah
 */
declare function findManzil(surah: Surah, ayah?: AyahNo): Manzil;
//#endregion
//#region src/findManzilByAyahId.d.ts
/**
 * Finds the Manzil number for a given Ayah ID using binary search.
 * A Manzil is one of seven approximately equal divisions of the Quran.
 *
 * @param ayahId - The ID of the Ayah to find the Manzil for
 * @returns The Manzil number (1-7) containing the specified Ayah
 * @throws {@link Error} If the provided Ayah ID is invalid
 *
 * @example
 * ```typescript
 * const manzil = findManzilByAyahId(2345); // Returns the Manzil containing Ayah 2345
 * ```
 */
declare function findManzilByAyahId(ayahId: AyahId): Manzil;
//#endregion
//#region src/findPage.d.ts
/**
 * 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.
 * @returns The page number for the given Surah and Ayah.
 */
declare function findPage(surah: Surah, ayah?: AyahNo | AyahId): Page;
//#endregion
//#region src/findPagebyAyahId.d.ts
/**
 * Returns the page number for a given ayah ID in the Quran.
 *
 * @param ayahId - A numeric identifier representing a verse (ayah) in the Quran
 * @returns The page number where the specified ayah can be found
 * @throws Will throw an error if the ayahId is invalid
 *
 * @example
 * ```ts
 * const page = findPagebyAyahId(142); // Returns the page number containing ayah 142
 * ```
 */
declare function findPagebyAyahId(ayahId: AyahId): Page;
//#endregion
//#region src/findRangeAroundAyah.d.ts
/**
 * Finds the range of ayahs surrounding a given ayah based on specified mode
 * @param ayahId - The unique identifier of the ayah
 * @param mode - The scope for finding the range:
 *   - "juz": Returns range of ayahs in the same juz
 *   - "surah": Returns range of ayahs in the same surah
 *   - "ayah": Returns the single ayah as both start and end of range
 *   - "page": Returns range of ayahs on the same page
 *   - "ruku": Returns range of ayahs on the same ruku
 *   - "all": Returns range covering all ayahs (1 to total number of ayahs)
 * @returns An array of two numbers representing the start and end ayah IDs of the range [startAyahId, endAyahId]
 */
declare function findRangeAroundAyah(ayahId: AyahId, mode: RangeMode): AyahRange;
//#endregion
//#region src/findRangeAroundSurahAyah.d.ts
/**
 * 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
 * @param mode - The range mode: "juz", "surah", "ayah", "page", "ruku" or "all"
 * @returns A tuple containing the start and end ayah IDs of the range
 */
declare function findRangeAroundSurahAyah(surah: Surah, ayah: AyahNo, mode: RangeMode): AyahRange;
//#endregion
//#region src/findRubAlHizb.d.ts
/**
 * 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.

 * @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): RubAlHizbId;
//#endregion
//#region src/findRubAlHizbByAyahId.d.ts
/**
 * 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): RubAlHizbId;
//#endregion
//#region src/findRukuByAyahId.d.ts
/**
 * Finds the Ruku number for a given Ayah ID using binary search.
 *
 * @param ayahId - The unique identifier of an Ayah in format: surah:ayah (e.g., "2:255")
 * @returns The Ruku number corresponding to the given Ayah ID
 * @throws {@link Error} If the provided Ayah ID is invalid
 *
 * @example
 * ```ts
 * const ruku = findRukuByAyahId("2:255");
 * // Returns the Ruku number containing Ayah 255 of Surah 2
 * ```
 */
declare function findRukuByAyahId(ayahId: AyahId): Ruku;
//#endregion
//#region src/findSurahAyahByAyahId.d.ts
/**
 * Finds the Surah (chapter) and Ayah (verse) numbers that the given Ayah ID belongs to.
 *
 * @param ayahId - 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 findSurahAyahByAyahId(ayahId: AyahId): SurahAyah;
//#endregion
//#region src/findSurahByAyahId.d.ts
/**
 * Finds a Surah based on the provided Ayah ID.
 *
 * @param ayaId - The unique identifier of the Ayah
 * @returns The Surah that contains the specified Ayah
 *
 * @example
 * const surah = findSurahByAyahId(1234);
 */
declare function findSurahByAyahId(ayaId: AyahId): Surah;
//#endregion
//#region src/getAyahCountInSurah.d.ts
/**
 * 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): AyahNo;
//#endregion
//#region src/getAyahMeta.d.ts
/**
 * 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: AyahId): AyahMeta;
//#endregion
//#region src/getAyahMetasForSurah.d.ts
/**
 * Retrieves metadata for all ayahs in a specific surah.
 *
 * @param surahNumber - The surah number (1-114)
 * @returns Array of AyahMeta objects for each ayah in the surah
 * @throws RangeError If the surah number is not between 1 and 114
 */
declare function getAyahMetasForSurah(surahNumber: Surah): AyahMeta[];
//#endregion
//#region src/getJuzMeta.d.ts
/**
 * Retrieves metadata for a specific Juz of the Quran.
 *
 * @param juzNum - The Juz number to retrieve metadata for (1-30)
 * @returns An object containing the Juz number, first ayah, and last ayah in the Juz
 * @throws RangeError If the Juz number is not between 1 and 30
 */
declare function getJuzMeta(juzNum: Juz): JuzMeta;
//#endregion
//#region src/getList.d.ts
declare const partNames: readonly ["surah", "juz", "page", "manzil", "rubAlHizb", "ruku"];
type PartType = (typeof partNames)[number];
/**
 * An object that maps part types to their corresponding data lists.
 */

/**
 * Represents a block or section of the Quran with its starting ayah and length
 * startAyahId - The identifier of the first ayah in the block
 * ayahCount - The number of ayahs contained in this block
 */
type PartBlock = {
  startAyahId: AyahId;
  ayahCount: AyahId | AyahNo;
};
/**
 * Retrieves a formatted list of Quran parts based on the specified type.
 * @param type - The type of parts to retrieve (e.g., juz, hizb, rub)
 * @returns An array of formatted part blocks, excluding the first and last elements
 */
declare function getList(type: PartType): PartBlock[];
//#endregion
//#region src/getManzilMeta.d.ts
/**
 * Retrieves metadata for a specific Manzil (section) of the Quran
 *
 * @param manzilNum - The number of the Manzil (1-7)
 * @returns The metadata for the specified Manzil containing:
 *  - manzilNum: The Manzil number
 *  - firstAyahId: ID of the first ayah in the Manzil
 *  - lastAyahId: ID of the last ayah in the Manzil
 *  - first: Surah and ayah details of the first ayah
 *  - last: Surah and ayah details of the last ayah
 * @throws Will throw an error if manzilNum is invalid
 */
declare function getManzilMeta(manzilNum: number): ManzilMeta;
//#endregion
//#region src/getPageMeta.d.ts
/**
 * Retrieves metadata for a specific page of the Quran.
 *
 * @param pageNum - The page number to retrieve metadata for (1-604)
 * @returns {@link PageMeta} An object containing the page number, first ayah, and last ayah on the page
 * @throws {@link RangeError} If the page number is not between 1 and 604
 */
declare function getPageMeta(pageNum: Page): PageMeta;
//#endregion
//#region src/getRukuMeta.d.ts
/**
 * Retrieves metadata for a specific Ruku (section) of the Quran.
 * @param rukuNum - The number of the Ruku to retrieve metadata for
 * @returns {@link RukuMeta} An object containing metadata about the Ruku including:
 *  - rukuNum: The Ruku number
 *  - firstAyahId: The global Ayah ID of the first verse in this Ruku
 *  - lastAyahId: The global Ayah ID of the last verse in this Ruku
 *  - first: The Surah and Ayah numbers for the first verse
 *  - last: The Surah and Ayah numbers for the last verse
 * @throws Will throw an error if the provided Ruku number is invalid
 */
declare function getRukuMeta(rukuNum: number): RukuMeta;
//#endregion
//#region src/getRubAlHizb.d.ts
/**
 * Retrieves the basic 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 getRubAlHizb(quarterIndex: RubAlHizbId): RubAlHizb;
//#endregion
//#region src/getRubAlHizbMeta.d.ts
/**
 * 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: RubAlHizbId): RubAlHizbMeta;
//#endregion
//#region src/getRubAlHizbMetaByAyahId.d.ts
/**
 * 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): RubAlHizbMeta;
//#endregion
//#region src/getRubAlHizbByAyahId.d.ts
/**
 * 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 getRubAlHizbByAyahId(ayahId: AyahId): RubAlHizb;
//#endregion
//#region src/getSurahMeta.d.ts
/**
 * Gets the metadata for the specified Surah.
 *
 * @param surahNum - The Surah to get the metadata for.
 * @returns The metadata for the specified Surah.
 */
declare function getSurahMeta(surahNum: Surah): SurahMeta;
//#endregion
//#region src/isAyahJuzFirst.d.ts
/**
 * Returns the Juz (part) number that the given Ayah (verse) belongs to.
 *
 *
 * @param ayahId - The Ayah Id (verse) 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(ayahId: AyahId): Juz | number;
//#endregion
//#region src/isAyahPageFirst.d.ts
/**
 * Determines if the given ayah is the first ayah of a juz.
 *
 * @param ayahId - The ayah id .
 * @returns The page number if the ayah is the first ayah of the page, otherwise -1.
 */
declare function isAyahPageFirst(ayahId: AyahId): Page | number;
//#endregion
//#region src/isSurahAyahJuzFirst.d.ts
/**
 * Determines if a given Surah and Ayah combination marks the beginning of a Juz.
 *
 * @param surah - The Surah number to check
 * @param ayah - The Ayah number within the Surah to check
 * @returns The Juz number if the combination marks the start of a Juz, -1 otherwise
 * @throws Error When the provided Surah number is invalid
 *
 * @example
 * ```typescript
 * isSurahAyahJuzFirst(2, 142) // Returns 2
 * isSurahAyahJuzFirst(2, 143) // Returns -1
 * ```
 */
declare function isSurahAyahJuzFirst(surah: Surah, ayah: AyahNo): Juz | number;
//#endregion
//#region src/isSurahAyahPageFirst.d.ts
/**
 * Determines if an ayah is the first ayah on its page in the Quran
 * @param surah - The surah number (1-114)
 * @param ayah - The ayah number within the surah
 * @returns The page number if the ayah is first on its page, -1 otherwise
 * @throws Error If surah number is invalid
 */
declare function isSurahAyahPageFirst(surah: Surah, ayah: AyahNo): Page | number;
//#endregion
//#region src/lists/hizbQuarterList.d.ts
declare const HizbQuarterList: AyahId[];
//#endregion
//#region src/lists/juzList.d.ts
declare const JuzList: AyahId[];
//#endregion
//#region src/lists/manzilList.d.ts
declare const ManzilList: AyahId[];
//#endregion
//#region src/lists/pageList.d.ts
declare const PageList: AyahId[];
//#endregion
//#region src/lists/rukuList.d.ts
declare const RukuList: AyahId[];
//#endregion
//#region src/lists/sajdaList.d.ts
declare const SajdaList: Sajda[];
//#endregion
//#region src/nextAyah.d.ts
/**
 * 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;
//#endregion
//#region src/prevAyah.d.ts
/**
 * 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;
//#endregion
//#region src/typeGuards.d.ts
/**
 * Checks if the given value is a valid AyahId.
 *
 * @param x - The value to check.
 * @returns True if the value is a valid AyahId, otherwise false.
 */
declare function isValidAyahId(x: unknown): x is AyahId;
/**
 * Checks if the given value is a valid Ayah number.
 *
 * @param x - The value to check.
 * @returns True if the value is a valid Ayah number, otherwise false.
 */
declare function isValidAyahNo(x: unknown): x is AyahNo;
/**
 * Checks if the given value is a valid Surah number.
 *
 * @param x - The value to check.
 * @returns `true` if the value is a valid Surah number, otherwise `false`.
 */
declare function isValidSurah(x: unknown): x is Surah;
/**
 * Type guard function that checks if a tuple of two numbers represents a valid Surah and Ayah combination.
 *
 * @param x - A tuple containing [surahNumber, ayahNumber]
 * @returns True if the tuple represents a valid Surah-Ayah combination, false otherwise
 *
 * @example
 * ```ts
 * isValidSurahAyah([1, 7]) // true - Al-Fatiha has 7 ayahs
 * isValidSurahAyah([1, 8]) // false - Al-Fatiha only has 7 ayahs
 * isValidSurahAyah([115, 1]) // false - there are only 114 surahs
 * ```
 */
declare function isValidSurahAyah(x: [unknown, unknown]): x is SurahAyah;
/**
 * Type guard that checks if a number is a valid Juz number
 * @param x - The number to check
 * @returns True if the number is an integer between 1 and the total number of Juzs (inclusive)
 */
declare function isValidJuz(x: unknown): x is Juz;
/**
 * Type guard to check if a number is a valid Hizb number
 * @param x - The number to check
 * @returns True if the number is an integer between 1 and the total number of Hizbs (inclusive)
 */

/**
 * Type guard to check if a number is a valid Quran page number
 * @param x - The number to check
 * @returns True if the number is an integer between 1 and the total number of pages (inclusive)
 */
declare function isValidPage(x: unknown): x is Juz;
/**
 * Type guard that checks if a value is a valid Ruku number
 * @param x - The value to check
 * @returns True if x is an integer between 1 and the total number of Rukus
 * @example
 * ```ts
 * if (isValidRuku(5)) {
 *   // 5 is a valid Ruku number
 * }
 * ```
 */
declare function isValidRuku(x: unknown): x is Ruku;
/**
 * Type guard to check if a value is a valid Manzil number
 *
 * @param x - The value to check
 * @returns True if the value is an integer between 1 and the total number of Manzils
 *
 * @example
 * ```ts
 * if (isValidManzil(3)) {
 *   // value is a valid Manzil number
 * }
 * ```
 */
declare function isValidManzil(x: unknown): x is Manzil;
//#endregion
//#region src/validation.d.ts
/**
 * Validates if the provided value is a valid Surah number.
 *
 * @param surah - The value to validate, can be a Surah object, number, or unknown type
 * @throws TypeError When the provided value is not an integer
 * @throws RangeError When the provided surah number is outside the valid range (1 to total number of surahs)
 * @remarks This is a type assertion function that ensures the input is a valid Surah
 */
declare function checkValidSurah(surah: Surah | number | unknown): asserts surah is Surah;
/**
 * Validates if the given surah and ayah numbers form a valid combination.
 * @param surah - The surah number or Surah object to validate
 * @param ayah - The ayah number or AyahNo object to validate
 * @throws Error If the surah-ayah combination is invalid
 */
declare function checkValidSurahAyah(surah: Surah | number | unknown, ayah: number | AyahNo | unknown): void;
/**
 * Validates that a surah-ayah pair contains valid values
 * @param surahAyah - A tuple containing surah number/object and ayah number
 * @throws RangeError If ayah number is not between 1 and the maximum ayah count for the given surah
 * @throws If surah is invalid (from checkValidSurah)
 * @example
 * ```ts
 * checkValidSurahAyahPair([1, 7]) // Valid
 * checkValidSurahAyahPair([1, 8]) // Throws RangeError
 * ```
 */

/**
 * Validates and asserts that the given value is a valid Ayah ID.
 * An Ayah ID must be an integer between 1 and the total number of Ayahs.
 *
 * @param ayahId - The value to check as an Ayah ID
 * @throws TypeError If the value is not an integer
 * @throws RangeError If the value is not within valid Ayah ID range
 */
declare function checkValidAyahId(ayahId: unknown | number | AyahId): asserts ayahId is AyahId;
/**
 * Checks if a value is a valid Page number.
 * @param x - The value to check
 * @throws {@link TypeError} When the value is not an integer
 * @throws {@link RangeError} When the value is not within valid page range (1 to numPages)
 * @remarks This is a type assertion function that ensures a value is a valid Page number
 */
declare function checkValidPage(x: unknown | number | Page): asserts x is Page;
/**
 * Type guard that checks if a value is a valid Juz number.
 * Throws TypeError if value is not an integer.
 * Throws RangeError if value is outside valid Juz range.
 *
 * @param x - Value to check
 * @throws {@link TypeError} If value is not an integer
 * @throws {@link RangeError} If value is not between 1 and the total number of Juz
 */
declare function checkValidJuz(x: unknown | number | Juz): asserts x is Juz;
/**
 * Type guard that checks if a value is a valid Ruku number.
 * @param x - The value to check
 * @throws {@link TypeError} If the value is not an integer number
 * @throws {@link RangeError} If the number is not within valid Ruku range
 * @example
 * ```ts
 * checkValidRuku(5); // OK
 * checkValidRuku("5"); // Throws TypeError
 * checkValidRuku(999); // Throws RangeError
 * ```
 */
declare function checkValidRuku(x: unknown | number | Ruku): asserts x is Ruku;
/**
 * Type guard that checks if a value is a valid Manzil number.
 * @param x - The value to check
 * @throws {@link TypeError} If the value is not an integer
 * @throws {@link RangeError} If the value is not within valid Manzil range (1 to max manzils)
 * @remarks This is an assertion function that ensures the input is a valid Manzil type
 */
declare function checkValidManzil(x: unknown | number | Manzil): asserts x is Manzil;
//#endregion
//#region src/i18n/types.d.ts
type SurahNames = ArrayOfSameLength<SurahListType, SurahName | []>;
declare const languages: readonly ["en", "az", "ru", "tr"];
type Lang = typeof languages[number];
type SurahNamesI18n = { [K in Lang]: SurahNames };
//#endregion
//#region src/i18n/surah.en.d.ts
declare const surahNamesEn: SurahNames;
//#endregion
//#region src/i18n/surah.az.d.ts
declare const surahNamesAz: SurahNames;
//#endregion
//#region src/i18n/surah.ru.d.ts
declare const surahNamesRu: SurahNames;
//#endregion
//#region src/i18n/surah.tr.d.ts
declare const surahNamesTr: SurahNames;
//#endregion
//#region src/i18n/getSurahNames.d.ts
/**
 * Retrieves the list of Surah names in the specified language.
 *
 * @param lang - The language code for which to retrieve the Surah names
 * @returns An array of Surah names in the specified language
 *
 * @example
 * ```typescript
 * const arabicNames = getSurahNames('ar');
 * const englishNames = getSurahNames('en');
 * ```
 */
declare function getSurahNames(lang: Lang): [[] | SurahName, [] | SurahName, [] | SurahName, [] | SurahName, [] | SurahName, [] | SurahName, [] | SurahName, [] | SurahName, [] | SurahName, [] | SurahName, [] | SurahName, [] | SurahName, [] | SurahName, [] | SurahName, [] | SurahName, [] | SurahName, [] | SurahName, [] | SurahName, [] | SurahName, [] | SurahName, [] | SurahName, [] | SurahName, [] | SurahName, [] | SurahName, [] | SurahName, [] | SurahName, [] | SurahName, [] | SurahName, [] | SurahName, [] | SurahName, [] | SurahName, [] | SurahName, [] | SurahName, [] | SurahName, [] | SurahName, [] | SurahName, [] | SurahName, [] | SurahName, [] | SurahName, [] | SurahName, [] | SurahName, [] | SurahName, [] | SurahName, [] | SurahName, [] | SurahName, [] | SurahName, [] | SurahName, [] | SurahName, [] | SurahName, [] | SurahName, [] | SurahName, [] | SurahName, [] | SurahName, [] | SurahName, [] | SurahName, [] | SurahName, [] | SurahName, [] | SurahName, [] | SurahName, [] | SurahName, [] | SurahName, [] | SurahName, [] | SurahName, [] | SurahName, [] | SurahName, [] | SurahName, [] | SurahName, [] | SurahName, [] | SurahName, [] | SurahName, [] | SurahName, [] | SurahName, [] | SurahName, [] | SurahName, [] | SurahName, [] | SurahName, [] | SurahName, [] | SurahName, [] | SurahName, [] | SurahName, [] | SurahName, [] | SurahName, [] | SurahName, [] | SurahName, [] | SurahName, [] | SurahName, [] | SurahName, [] | SurahName, [] | SurahName, [] | SurahName, [] | SurahName, [] | SurahName, [] | SurahName, [] | SurahName, [] | SurahName, [] | SurahName, [] | SurahName, [] | SurahName, [] | SurahName, [] | SurahName, [] | SurahName, [] | SurahName, [] | SurahName, [] | SurahName, [] | SurahName, [] | SurahName, [] | SurahName, [] | SurahName, [] | SurahName, [] | SurahName, [] | SurahName, [] | SurahName, [] | SurahName, [] | SurahName, [] | SurahName, [] | SurahName];
//#endregion
//#region src/i18n/index.d.ts
declare const surahNames: SurahNamesI18n;
//#endregion
export { type AyahCountBetweenJuzSurah, type AyahId, type AyahMeta, type AyahNo, type AyahRange, type HizbId, HizbQuarterList, type Juz, JuzList, type JuzMeta, type JuzPart, type Lang, type Manzil, ManzilList, type ManzilMeta, type Page, PageList, type PageMeta, type PartType, type QuranMeta, type RangeMeta, type RangeMode, type RubAlHizb, type RubAlHizbId, type RubAlHizbMeta, type Ruku, RukuList, type RukuMeta, type Sajda, SajdaList, type SajdaType, type Surah, type SurahAyah, type SurahAyahSegment, type SurahInfo, type SurahJuzMeta, SurahList, type SurahListType, type SurahMeta, type SurahName, type SurahNames, type SurahNamesI18n, ayahStringSplitter, checkValidAyahId, checkValidJuz, checkValidManzil, checkValidPage, checkValidRuku, checkValidSurah, checkValidSurahAyah, findAyahIdBySurah, findJuz, findJuzAndShift, findJuzAndShiftByAyahId, findJuzByAyahId, findJuzMetaBySurah, findManzil, findManzilByAyahId, findPage, findPagebyAyahId, findRangeAroundAyah, findRangeAroundSurahAyah, findRubAlHizb, findRubAlHizbByAyahId, findRukuByAyahId, findSurahAyahByAyahId, findSurahByAyahId, getAyahCountInSurah, getAyahMeta, getAyahMetasForSurah, getJuzMeta, getList, getManzilMeta, getPageMeta, getRubAlHizb, getRubAlHizbByAyahId, getRubAlHizbMeta, getRubAlHizbMetaByAyahId, getRukuMeta, getSurahMeta, getSurahNames, isAyahJuzFirst, isAyahPageFirst, isSurahAyahJuzFirst, isSurahAyahPageFirst, isValidAyahId, isValidAyahNo, isValidJuz, isValidManzil, isValidPage, isValidRuku, isValidSurah, isValidSurahAyah, meta, nextAyah, partNames, prevAyah, string2NumberSplitter, string2NumberSplitterStrict, surahNames, surahNamesAz, surahNamesEn, surahNamesRu, surahNamesTr, surahStringParser };