quran-meta/lib_cjs/types.d.cts

Library with meta data and functionality related to Holy Quran

import { maxAyahsInSurah, meta } from "./const.cjs";
import { LessThan } from "./ts-utils.cjs";
import { SurahListType } from "./lists/surahList.cjs";

//#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
export { AyahCountBetweenJuzSurah, AyahId, AyahMeta, AyahNo, AyahRange, HizbId, Juz, JuzMeta, JuzPart, Manzil, ManzilMeta, Page, PageMeta, RangeMeta, RangeMode, RubAlHizb, RubAlHizbId, RubAlHizbMeta, Ruku, RukuMeta, Sajda, SajdaType, Surah, SurahAyah, SurahAyahSegment, SurahInfo, SurahJuzMeta, SurahMeta, SurahName };