feat: add manzil related methods

Author: husayt

src/findManzil.ts

@@ -0,0 +1,15 @@
+import { findAyahIdBySurah } from "./findAyahIdBySurah"
+import { findManzilByAyahId } from "./findManzilByAyahId"
+import { AyahId, AyahNo, Manzil, Surah } from "./types"
+
+/**
+ * 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
+ */
+export function findManzil(surah: Surah, ayah: AyahNo = 1): Manzil {
+  const ayahId: AyahId = findAyahIdBySurah(surah, ayah)
+
+  return findManzilByAyahId(ayahId)
+}

src/findManzilByAyahId.ts

@@ -0,0 +1,26 @@
+import { ManzilList } from "./lists/manzilList"
+import { AyahId, Manzil } from "./types"
+import { binarySearch } from "./utils"
+import { checkValidAyahId } from "./validation"
+
+
+/**
+ * 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 {Error} If the provided Ayah ID is invalid
+ * 
+ * @example
+ * ```typescript
+ * const manzil = findManzilByAyahId(2345); // Returns the Manzil containing Ayah 2345
+ * ```
+ */
+export function findManzilByAyahId(ayahId: AyahId): Manzil {
+  checkValidAyahId(ayahId)
+
+  const jj = binarySearch(ManzilList, ayahId)
+  const juz = jj < 0 ? -jj - 2 : jj
+  return juz as Manzil
+}

src/findRangeAroundSurahAyah.ts

@@ -9,7 +9,7 @@ import { checkValidSurah } from "./validation"
  *
  * @param surah - The surah number (1-114)
  * @param ayah - The ayah number within the surah
- * @param mode - The range mode: "juz", "surah", "ayah", "page", or "all"
+ * @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
  */
 export function findRangeAroundSurahAyah(

src/getManzilMeta.ts

@@ -0,0 +1,33 @@
+import { findSurahAyahByAyahId } from "./findSurahAyahByAyahId"
+import { ManzilList } from "./lists/manzilList"
+import { AyahId, ManzilMeta } from "./types"
+import { checkValidManzil } from "./validation"
+
+/**
+ * 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
+ */
+export function getManzilMeta(manzilNum: number): ManzilMeta {
+  checkValidManzil(manzilNum)
+
+  const [firstAyahId, nextManzilAyahId]: [AyahId, AyahId] = [
+    ManzilList[manzilNum],
+    ManzilList[manzilNum + 1]
+  ]
+  const lastAyahId = nextManzilAyahId - 1
+  return {
+    manzilNum,
+    firstAyahId,
+    lastAyahId,
+    first: findSurahAyahByAyahId(firstAyahId),
+    last: findSurahAyahByAyahId(lastAyahId)
+  }
+}

src/index.ts

@@ -11,6 +11,8 @@ export { findJuz } from "./findJuz"
 export { findJuzAndShift, findJuzAndShiftByAyahId } from "./findJuzAndShift"
 export { findJuzByAyahId } from "./findJuzByAyahId"
 export { findJuzMetaBySurah } from "./findJuzMetaBySurah"
+export { findManzil } from "./findManzil"
+export { findManzilByAyahId } from "./findManzilByAyahId"
 export { findPage } from "./findPage"
 export { findPagebyAyahId } from "./findPagebyAyahId"
 export { findRangeAroundAyah } from "./findRangeAroundAyah"
@@ -25,6 +27,7 @@ export { getAyahMeta } from "./getAyahMeta"
 export { getAyahMetasForSurah } from "./getAyahMetasForSurah"
 export { getJuzMeta } from "./getJuzMeta"
 export { getList } from "./getList"
+export { getManzilMeta } from "./getManzilMeta"
 export { getPageMeta } from "./getPageMeta"
 export { getRukuMeta } from "./getRukuMeta"
 export { getRubAlHizb } from "./getRubAlHizb"
@@ -45,8 +48,8 @@ export { SajdaList } from "./lists/sajdaList"
 export { SurahList } from "./lists/surahList"
 export { nextAyah } from "./nextAyah"
 export { prevAyah } from "./prevAyah"
-export { isValidRuku, isValidAyahId, isValidAyahNo, isValidJuz, isValidPage, isValidSurah, isValidSurahAyah } from "./typeGuards"
-export { checkValidRuku, checkValidAyahId, checkValidJuz, checkValidPage, checkValidSurah, checkValidSurahAyah } from "./validation"
+export { isValidManzil, isValidRuku, isValidAyahId, isValidAyahNo, isValidJuz, isValidPage, isValidSurah, isValidSurahAyah } from "./typeGuards"
+export { checkValidManzil, checkValidRuku, checkValidAyahId, checkValidJuz, checkValidPage, checkValidSurah, checkValidSurahAyah } from "./validation"
 
 // ------------------ Sura i18 Data ---------------------
 

src/typeGuards.ts

@@ -1,6 +1,6 @@
 import { maxAyahsInSurah, meta } from "./const"
 import { getAyahCountInSurah } from "./getAyahCountInSurah"
-import { AyahId, AyahNo, HizbId, Juz, RubAlHizbId, Ruku, Surah, SurahAyah } from "./types"
+import { AyahId, AyahNo, HizbId, Juz, Manzil, RubAlHizbId, Ruku, Surah, SurahAyah } from "./types"
 
 /**
  * Checks if the given value is a valid AyahId.
@@ -104,3 +104,18 @@ export function isValidPage(x: unknown): x is Juz {
 export function isValidRuku(x: unknown): x is Ruku {
   return Number.isInteger(x) && 1 <= (x as number) && x as number <= meta.numRukus
 }
+
+/**
+ * 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
+ * if (isValidManzil(3)) {
+ *   // value is a valid Manzil number
+ * }
+ */
+export function isValidManzil(x: unknown): x is Manzil {
+  return Number.isInteger(x) && 1 <= (x as number) && x as number <= meta.numManzils
+}

src/types.ts

@@ -110,6 +110,10 @@ export type PageMeta = {
   pageNum: Page
 } & RangeMeta
 
+export type ManzilMeta = {
+  manzilNum: Manzil
+} & RangeMeta
+
 export type JuzMeta = {
   juzNum: Juz
 } & RangeMeta

src/validation.ts

@@ -1,7 +1,7 @@
 import { meta } from "./const"
 import { getAyahCountInSurah } from "./getAyahCountInSurah"
-import { isValidAyahId, isValidJuz, isValidPage, isValidRuku, isValidSurah } from "./typeGuards"
-import { AyahId, AyahNo, Juz, Page, Ruku, Surah, SurahAyah } from "./types"
+import { isValidAyahId, isValidJuz, isValidManzil, isValidPage, isValidRuku, isValidSurah } from "./typeGuards"
+import { AyahId, AyahNo, Juz, Manzil, Page, Ruku, Surah, SurahAyah } from "./types"
 
 /**
  * Validates if the provided value is a valid Surah number.
@@ -119,6 +119,22 @@ export function checkValidRuku(x: unknown | number | Ruku): asserts x is Ruku {
     throw new TypeError("Ruku must be an integer")
   }
   if (!isValidRuku(x)) {
-    throw new RangeError("Ruku must be between 1 and " + meta.numJuzs)
+    throw new RangeError("Ruku must be between 1 and " + meta.numRukus)
+  }
+}
+
+/**
+ * Type guard that checks if a value is a valid Manzil number.
+ * @param x - The value to check
+ * @throws {TypeError} If the value is not an integer
+ * @throws {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
+ */
+export function checkValidManzil(x: unknown | number | Manzil): asserts x is Manzil {
+  if (typeof x !== "number" || !Number.isInteger(x)) {
+    throw new TypeError("Manzil must be an integer")
+  }
+  if (!isValidManzil(x)) {
+    throw new RangeError("Manzil must be between 1 and " + meta.numManzils)
   }
 }

tests/findManzil.spec.ts

@@ -0,0 +1,36 @@
+import { findManzil } from "../src"
+
+describe("findManzil", () => {
+  it("should return correct manzil for surah 1", () => {
+    expect(findManzil(1)).toBe(1)
+  })
+
+  it("should return correct manzil for surah 6", () => {
+    expect(findManzil(6)).toBe(2)
+  })
+
+  it("should return correct manzil for surah 17", () => {
+    expect(findManzil(17)).toBe(4)
+  })
+
+  it("should return correct manzil for surah 26", () => {
+    expect(findManzil(26)).toBe(5)
+  })
+
+  it("should return correct manzil for surah 37", () => {
+    expect(findManzil(37)).toBe(6)
+  })
+
+  it("should return correct manzil for surah 50", () => {
+    expect(findManzil(50)).toBe(7)
+  })
+
+  it("should return correct manzil for surah 67", () => {
+    expect(findManzil(67)).toBe(7)
+  })
+
+  it("should handle specific ayah numbers", () => {
+    expect(findManzil(2, 142)).toBe(1)
+    expect(findManzil(4, 24)).toBe(1)
+  })
+})

tests/findManzilByAyahId.spec.ts

@@ -0,0 +1,30 @@
+import { findManzilByAyahId } from "../src"
+
+describe("findManzilByAyahId", () => {
+  it("should return correct manzil for beginning of Quran", () => {
+    expect(findManzilByAyahId(1)).toBe(1)
+  })
+
+  it("should return correct manzil for middle ayahs", () => {
+    expect(findManzilByAyahId(1000)).toBe(2)
+    expect(findManzilByAyahId(2000)).toBe(3)
+    expect(findManzilByAyahId(3000)).toBe(5)
+  })
+
+  it("should return correct manzil for end of Quran", () => {
+    expect(findManzilByAyahId(6236)).toBe(7)
+  })
+
+  it("should throw error for invalid ayah IDs", () => {
+    expect(() => findManzilByAyahId(0)).toThrow()
+    expect(() => findManzilByAyahId(-1)).toThrow()
+    expect(() => findManzilByAyahId(6237)).toThrow()
+  })
+
+  it("should handle boundary cases between manzils", () => {
+    expect(findManzilByAyahId(670)).toBe(2)
+    expect(findManzilByAyahId(671)).toBe(2)
+    expect(findManzilByAyahId(1365)).toBe(3)
+    expect(findManzilByAyahId(1366)).toBe(3)
+  })
+})