quran-meta/lib_cjs/QuranRiwaya.d.cts

Library with meta data and functionality related to Holy Quran

import { PartType, RiwayaName, Riwayas } from "./lists/types.cjs";
import { AyahCountBetweenJuzSurah, AyahId, AyahMeta, AyahNo, AyahRange, Juz, JuzMeta, Manzil, ManzilMeta, Page, PageMeta, QuranMeta, RangeMode, RubAlHizb, RubAlHizbId, RubAlHizbMeta, Ruku, RukuMeta, Surah, SurahAyah, SurahAyahSegment, SurahInfo, SurahJuzMeta, SurahMeta, ThumunAlHizb, ThumunAlHizbId, ThumunAlHizbMeta } from "./types.cjs";

//#region src/QuranRiwaya.d.ts

/**
 * QuranRiwaya class provides a clean API for Quran metadata operations
 * with a specific riwaya (recitation tradition) context.
 *
 * Currently provides basic Surah and Ayah operations. For advanced features
 * like Juz, Page, Manzil, RubAlHizb, etc., use the functional API directly.
 *
 * @example
 * **Basic Usage with Hafs**
 * ```typescript
 * import { quran } from 'quran-meta/hafs'
 *
 * const surahMeta = quran.getSurahMeta(2)  // Get Al-Baqarah metadata
 * const ayahCount = quran.getAyahCountInSurah(2)  // 286 ayahs
 * const [surah, ayah] = quran.findSurahAyahByAyahId(100)  // [2, 93]
 * ```
 *
 * @example
 * **Working with Qalun**
 * ```typescript
 * import { quran } from 'quran-meta/qalun'
 *
 * const meta = quran.meta
 * console.log(meta.numAyahs)  // 6214 (Qalun has fewer ayahs than Hafs)
 * ```
 *
 * @example
 * **Creating a custom instance**
 * ```typescript
 * import { QuranRiwaya } from 'quran-meta'
 * import { WarshMeta, WarshLists } from 'quran-meta/lists/WarshLists'
 *
 * const warsh = QuranRiwaya.create(WarshLists)
 * ```
 */
declare class QuranRiwaya<R extends RiwayaName = "Hafs"> {
  #private;
  private constructor();
  /**
  * Create a QuranRiwaya instance with the specified riwaya, metadata, and lists
  * @param riwaya - The riwaya name ("Hafs", "Qalun", or "Warsh")
  * @param meta - The metadata for this riwaya
  * @param rData - The Lists object for this riwaya
  */
  static create<R extends RiwayaName>(rData: Riwayas[R]): QuranRiwaya<R>;
  /**
  * Gets the metadata for the specified Surah
  */
  getSurahMeta(surahNum: Surah): SurahMeta;
  ayahStringSplitter(str: string, isStrict?: boolean): SurahAyahSegment;
  /**
  * Gets the surah info array [firstAyahId, ayahCount, surahOrder, rukuCount, name, isMeccan]
  */
  getSurahInfo(surah: Surah): SurahInfo;
  /**
  * Gets the count of ayahs in a surah
  */
  getAyahCountInSurah(surah: Surah): number;
  /**
  * Finds the surah number for a given ayah ID
  */
  findSurahByAyahId(ayahId: AyahId): Surah;
  /**
  * Finds the [surah, ayah] tuple for a given ayah ID
  */
  findSurahAyahByAyahId(ayahId: AyahId): SurahAyah;
  /**
  * Finds the ayah ID for a given surah and ayah number
  */
  findAyahIdBySurah(surah: Surah, ayah: AyahNo): AyahId;
  generatePartBlocks<P extends PartType>(type: P): {
    startAyahId: AyahId;
    ayahCount: AyahId | AyahNo;
  }[] | null;
  getList<P extends PartType>(type: P): number[] | [SurahInfo, SurahInfo, SurahInfo, SurahInfo, SurahInfo, SurahInfo, SurahInfo, SurahInfo, SurahInfo, SurahInfo, SurahInfo, SurahInfo, SurahInfo, SurahInfo, SurahInfo, SurahInfo, SurahInfo, SurahInfo, SurahInfo, SurahInfo, SurahInfo, SurahInfo, SurahInfo, SurahInfo, SurahInfo, SurahInfo, SurahInfo, SurahInfo, SurahInfo, SurahInfo, SurahInfo, SurahInfo, SurahInfo, SurahInfo, SurahInfo, SurahInfo, SurahInfo, SurahInfo, SurahInfo, SurahInfo, SurahInfo, SurahInfo, SurahInfo, SurahInfo, SurahInfo, SurahInfo, SurahInfo, SurahInfo, SurahInfo, SurahInfo, SurahInfo, SurahInfo, SurahInfo, SurahInfo, SurahInfo, SurahInfo, SurahInfo, SurahInfo, SurahInfo, SurahInfo, SurahInfo, SurahInfo, SurahInfo, SurahInfo, SurahInfo, SurahInfo, SurahInfo, SurahInfo, SurahInfo, SurahInfo, SurahInfo, SurahInfo, SurahInfo, SurahInfo, SurahInfo, SurahInfo, SurahInfo, SurahInfo, SurahInfo, SurahInfo, SurahInfo, SurahInfo, SurahInfo, SurahInfo, SurahInfo, SurahInfo, SurahInfo, SurahInfo, SurahInfo, SurahInfo, SurahInfo, SurahInfo, SurahInfo, SurahInfo, SurahInfo, SurahInfo, SurahInfo, SurahInfo, SurahInfo, SurahInfo, SurahInfo, SurahInfo, SurahInfo, SurahInfo, SurahInfo, SurahInfo, SurahInfo, SurahInfo, SurahInfo, SurahInfo, SurahInfo, SurahInfo, SurahInfo, SurahInfo, SurahInfo, SurahInfo];
  getListNormalised<P extends PartType>(type: P): {
    startAyahId: AyahId;
    ayahCount: AyahId | AyahNo;
  }[];
  /**
   * Gets the next ayah after the given surah and ayah
   */
  nextAyah(surah: Surah, ayah: AyahNo): SurahAyah;
  /**
  * Gets the previous ayah before the given surah and ayah
  */
  prevAyah(surah: Surah, ayah: AyahNo): SurahAyah;
  /**
  * Finds the juz number for a given surah and ayah
  */
  findJuz(surah: Surah, ayah?: AyahNo): Juz;
  /**
  * Finds the juz number for a given ayah ID
  */
  findJuzByAyahId(ayahId: AyahId): Juz;
  /**
  * Finds the page number for a given surah and ayah
  */
  findPage(surah: Surah, ayah?: AyahNo): Page;
  /**
  * Finds the page number for a given ayah ID
  */
  findPagebyAyahId(ayahId: AyahId): Page;
  /**
  * Gets metadata for a specific page
  */
  getPageMeta(pageNum: Page): PageMeta;
  /**
  * Finds the manzil number for a given surah and ayah
  */
  findManzil(surah: Surah, ayah?: AyahNo): Manzil;
  /**
  * Finds the manzil number for a given ayah ID
  */
  findManzilByAyahId(ayahId: AyahId): Manzil;
  /**
  * Gets metadata for a specific manzil
  */
  getManzilMeta(manzilNum: number): ManzilMeta;
  /**
  * Finds the ruku number for a given ayah ID
  */
  findRukuByAyahId(ayahId: AyahId): Ruku;
  /**
  * Gets metadata for a specific ruku
  */
  getRukuMeta(rukuNum: number): RukuMeta;
  /**
  * Gets metadata for a specific juz
  */
  getJuzMeta(juzNum: Juz): JuzMeta;
  /**
  * Finds juz metadata for a given surah and ayah
  */
  findJuzMetaBySurah(surah: Surah, ayah?: AyahNo): SurahJuzMeta;
  /**
  * Finds juz and calculates shift between juz start and surah start
  */
  findJuzAndShift(surah: Surah, ayah: AyahNo): {
    juz: Juz;
    leftAyahId: AyahId;
    ayahsBetweenJuzSurah: AyahCountBetweenJuzSurah;
  };
  /**
  * Finds juz and shift for a given ayah ID
  */
  findJuzAndShiftByAyahId(ayahId: AyahId): {
    juz: Juz;
    leftAyahId: AyahId;
    ayahsBetweenJuzSurah: AyahCountBetweenJuzSurah;
  };
  /**
  * Finds the RubAlHizb for a given surah and ayah
  */
  findRubAlHizb(surah: Surah, ayah?: AyahNo): RubAlHizbId;
  /**
  * Finds the RubAlHizb ID for a given ayah ID
  */
  findRubAlHizbByAyahId(ayahId: AyahId): RubAlHizbId;
  /**
  * Gets RubAlHizb data (juz, hizb, etc.) for a given ayah ID
  */
  getRubAlHizbByAyahId(ayahId: AyahId): RubAlHizb;
  /**
  * Gets RubAlHizb data (juz, hizb, etc.) for a given ayah ID
  */
  getRubAlHizb(quarterIndex: RubAlHizbId): RubAlHizb;
  /**
  * Gets complete RubAlHizb metadata for a given ayah ID
  */
  getRubAlHizbMetaByAyahId(ayahId: AyahId): RubAlHizbMeta;
  /**
  * Gets metadata for a specific RubAlHizb
  */
  getRubAlHizbMeta(quarterIndex: RubAlHizbId): RubAlHizbMeta;
  /**
  * Finds the ThumunAlHizb ID for a given ayah ID (Qalun/Warsh only)
  */
  findThumunAlHizbByAyahId(ayahId: AyahId): ThumunAlHizbId | null;
  /**
  * Finds the ThumunAlHizb ID for a given ayah ID (Qalun/Warsh only)
  */
  findThumunAlHizb(surah: Surah, ayah?: AyahNo): ThumunAlHizbId | null;
  /**
  * Gets metadata for a specific ThumunAlHizb (Qalun/Warsh only)
  */
  getThumunAlHizbMeta(eighthIndex: ThumunAlHizbId): ThumunAlHizbMeta | null;
  getThumunAlHizbByAyahId(ayahId: AyahId): ThumunAlHizb | null;
  getThumunAlHizbMetaByAyahId(ayahId: AyahId): ThumunAlHizb | null;
  getThumunAlHizb(eighthIndex: ThumunAlHizbId): ThumunAlHizb | null;
  /**
  * Gets comprehensive metadata for a specific ayah
  */
  getAyahMeta(ayahId: AyahId): AyahMeta;
  /**
  * Gets metadata for all ayahs in a surah
  */
  getAyahMetasForSurah(surahNumber: Surah): AyahMeta[];
  /**
  * Finds the range of ayahs around a given ayah
  */
  findRangeAroundAyah(ayahId: AyahId, mode: RangeMode): AyahRange;
  /**
  * Finds the range of ayahs around a given surah and ayah
  */
  findRangeAroundSurahAyah(surah: Surah, ayah: AyahNo, mode: RangeMode): AyahRange;
  /**
  * Checks if an ayah is the first ayah of a juz
  */
  isAyahJuzFirst(ayahId: AyahId): Juz | number;
  /**
  * Checks if an ayah is the first ayah of a page
  */
  isAyahPageFirst(ayahId: AyahId): Page | number;
  /**
  * Checks if a surah-ayah combination is the first ayah of a juz
  */
  isSurahAyahJuzFirst(surah: Surah, ayah: AyahNo): Juz | number;
  /**
  * Checks if a surah-ayah combination is the first ayah of a page
  */
  isSurahAyahPageFirst(surah: Surah, ayah: AyahNo): Page | number;
  isValidAyahId(x: unknown): x is AyahId;
  isValidPage(x: unknown): x is Page;
  isValidSurah(x: unknown): x is Surah;
  isValidJuz(x: unknown): x is Juz;
  isValidRuku(x: unknown): x is Ruku;
  isValidSurahAyah(x: [unknown, unknown]): x is SurahAyah;
  static isValidAyahNo(x: unknown): x is AyahNo;
  surahStringParser(str: string, isStrict?: boolean): Page | number;
  static string2NumberSplitter(str: string): {
    ayah?: number;
    ayahTo?: number;
    surahOrAyah?: number;
  } | null;
  /**
  * Gets the riwaya name
  */
  get riwayaName(): R;
  /**
  * Gets the metadata for this riwaya
  */
  get meta(): QuranMeta;
  /**
  * Gets the metadata for this riwaya
  */
  get lists(): Riwayas[R];
}
//#endregion
export { QuranRiwaya };