feat: add getRukuMeta

Author: husayt

src/findRangeAroundAyah.ts

@@ -1,11 +1,13 @@
 import { meta } from "./const"
 import { findJuzByAyahId } from "./findJuzByAyahId"
 import { findPagebyAyahId } from "./findPagebyAyahId"
+import { findRukuByAyahId } from "./findRukuByAyahId"
 import { findSurahByAyahId } from "./findSurahByAyahId"
 import { JuzList } from "./lists/juzList"
 import { PageList } from "./lists/pageList"
+import { RukuList } from "./lists/rukuList"
 import { SurahList } from "./lists/surahList"
-import { AyahId, AyahRange, Juz, Page, Surah } from "./types"
+import { AyahId, AyahRange, Juz, Page, Ruku, Surah } from "./types"
 
 /**
  * Finds the range of ayahs surrounding a given ayah based on specified mode
@@ -15,12 +17,13 @@ import { AyahId, AyahRange, Juz, Page, Surah } from "./types"
  *   - "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]
  */
 export function findRangeAroundAyah(
   ayahId: AyahId,
-  mode: "juz" | "surah" | "ayah" | "page" | "all"
+  mode: "juz" | "surah" | "ayah" | "page" | "ruku" | "all"
 ): AyahRange {
   switch (mode) {
     case "juz": {
@@ -42,6 +45,11 @@ export function findRangeAroundAyah(
       return [PageList[page], PageList[page + 1] - 1]
     }
 
+    case "ruku": {
+      const ruku: Ruku = findRukuByAyahId(ayahId)
+      return [RukuList[ruku], RukuList[ruku + 1] - 1]
+    }
+
     case "all":
     default:
       return [1, meta.numAyahs]

src/getJuzMeta.ts

@@ -13,14 +13,16 @@ import { checkValidJuz } from "./validation"
 export function getJuzMeta(juzNum: number): JuzMeta {
   checkValidJuz(juzNum)
 
-  const [curJuzAyahId, nextJuzAyahId]: [AyahId, AyahId] = [
+  const [firstAyahId, nextJuzAyahId]: [AyahId, AyahId] = [
     JuzList[juzNum],
     JuzList[juzNum + 1]
   ]
-
+  const lastAyahId = nextJuzAyahId - 1
   return {
     juzNum,
-    first: findSurahAyahByAyahId(curJuzAyahId),
-    last: findSurahAyahByAyahId(nextJuzAyahId - 1)
+    firstAyahId,
+    lastAyahId,
+    first: findSurahAyahByAyahId(firstAyahId),
+    last: findSurahAyahByAyahId(lastAyahId)
   }
 }

src/getPageMeta.ts

@@ -13,14 +13,17 @@ import { checkValidPage } from "./validation"
 export function getPageMeta(pageNum: Page): PageMeta {
   checkValidPage(pageNum)
 
-  const [curPage, nextPage]: [AyahId, AyahId] = [
+  const [firstAyahId, nextPage]: [AyahId, AyahId] = [
     PageList[pageNum],
     PageList[pageNum + 1]
   ]
+  const lastAyahId = nextPage - 1
 
   return {
     pageNum,
-    first: findSurahAyahByAyahId(curPage),
-    last: findSurahAyahByAyahId(nextPage - 1)
+    firstAyahId,
+    lastAyahId,
+    first: findSurahAyahByAyahId(firstAyahId),
+    last: findSurahAyahByAyahId(lastAyahId)
   }
 }

src/getRukuMeta.ts

@@ -0,0 +1,32 @@
+import { findSurahAyahByAyahId } from "./findSurahAyahByAyahId"
+import { RukuList } from "./lists/rukuList"
+import { AyahId, RukuMeta } from "./types"
+import { checkValidRuku } from "./validation"
+
+/**
+ * Retrieves metadata for a specific Ruku (section) of the Quran.
+ * @param rukuNum - The number of the Ruku to retrieve metadata for
+ * @returns {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
+ */
+export function getRukuMeta(rukuNum: number): RukuMeta {
+  checkValidRuku(rukuNum)
+
+  const [firstAyahId, nextRukuAyahId]: [AyahId, AyahId] = [
+    RukuList[rukuNum],
+    RukuList[rukuNum + 1]
+  ]
+  const lastAyahId = nextRukuAyahId - 1
+  return {
+    rukuNum,
+    firstAyahId,
+    lastAyahId,
+    first: findSurahAyahByAyahId(firstAyahId),
+    last: findSurahAyahByAyahId(lastAyahId)
+  }
+}

src/index.ts

@@ -25,6 +25,7 @@ export { getAyahMeta } from "./getAyahMeta"
 export { getAyahMetasForSurah } from "./getAyahMetasForSurah"
 export { getList } from "./getList"
 export { getPageMeta } from "./getPageMeta"
+export { getRukuMeta } from "./getRukuMeta"
 export { getRubAlHizbMeta } from "./getRubAlHizbMeta"
 export { getRubAlHizbMetaByAyahId } from "./getRubAlHizbMetaByAyahId"
 export { getSurahMeta } from "./getSurahMeta"

src/types.ts

@@ -95,17 +95,26 @@ export type JuzHizb = {
 export type SurahAyah = [Surah, AyahNo]
 export type AyahRange = [AyahId, AyahId]
 export type SurahAyahSegment = [Surah, AyahNo | [AyahNo, AyahNo]]
-export type PageMeta = {
-  pageNum: Page
+
+export type RangeMeta = {
+  firstAyahId: AyahId
+  lastAyahId: AyahId
   first: SurahAyah
   last: SurahAyah
 }
 
+export type PageMeta = {
+  pageNum: Page
+} & RangeMeta
+
 export type JuzMeta = {
   juzNum: Juz
-  first: SurahAyah
-  last: SurahAyah
-}
+} & RangeMeta
+
+export type RukuMeta = {
+  rukuNum: Ruku
+} & RangeMeta
+
 // [leftjuz, ayahsFromStartOfJuz, rightJuz, ayahsinJuz]
 export type AyahCountBetweenJuzSurah = NumericRange<0, typeof maxAyahsInSurah>
 export type SurahJuzMeta = {

tests/getJuzMeta.test.ts renamed to tests/getJuzMeta.spec.ts

@@ -7,6 +7,8 @@ describe("getJuzMeta", () => {
 
     expect(result).toEqual({
       juzNum: 1,
+      firstAyahId: 1,
+      lastAyahId: 148,
       first: [1, 1],
       last: [2, 141]
     })

tests/getRukuMeta.spec.ts

@@ -0,0 +1,31 @@
+import { describe, expect, it } from "vitest"
+import { getRukuMeta } from "../src/getRukuMeta"
+
+describe("getRukuMeta", () => {
+  it("should return correct metadata for first ruku", () => {
+    const result = getRukuMeta(1)
+    expect(result).toEqual({
+      rukuNum: 1,
+      firstAyahId: 1,
+      lastAyahId: 7,
+      first: [1, 1],
+      last: [1, 7]
+    })
+  })
+
+  it("should return correct metadata for a middle ruku", () => {
+    const result = getRukuMeta(100)
+    expect(result).toMatchObject({
+      rukuNum: 100,
+      first: expect.any(Object),
+      last: expect.any(Object)
+    })
+    expect(result.firstAyahId).toBeLessThan(result.lastAyahId)
+  })
+
+  it("should throw error for invalid ruku number", () => {
+    expect(() => getRukuMeta(0)).toThrow()
+    expect(() => getRukuMeta(-1)).toThrow()
+    expect(() => getRukuMeta(557)).toThrow()
+  })
+})