feat: add updated SurahMeta

husayt · husayt · commit 01ce7d50aabc · 2025-03-10T12:17:14.000Z
diff --git a/examples/data-check/checkQuranApi.ts b/examples/data-check/checkQuranApi.ts
@@ -5,7 +5,7 @@
  */
 
 
-import { findPagebyAyahId, findAyahIdBySurah, findJuz, findRubAlHizb, getAyahMeta, getRubAlHizbMetaByAyahId, HizbQuarterList, Juz, JuzList, ManzilList, meta, PageList, RukuList, SajdaList, Surah, SurahList, SurahInfo, getJuzMeta, getRubAlHizbMeta, getRukuMeta, getPageMeta, getManzilMeta, getSurahInfo } from "../../src"
+import { findPagebyAyahId, findAyahIdBySurah, findJuz, findRubAlHizb, getAyahMeta, getRubAlHizbMetaByAyahId, HizbQuarterList, Juz, JuzList, ManzilList, meta, PageList, RukuList, SajdaList, Surah, SurahList, SurahInfo, getJuzMeta, getRubAlHizbMeta, getRukuMeta, getPageMeta, getManzilMeta, getSurahInfo, getSurahMeta } from "../../src"
 import { AyahNo, AyahId, Manzil, Page, Ruku, RubAlHizbId } from "../../src/types"
 
 import quranApi from "./data/quran-api.json"
@@ -29,19 +29,18 @@ export function checkQuranApi() {
     }
 
     for (let surahNo: Surah = 1; surahNo <= meta.numSurahs; surahNo++) {
-        const [
-            startAyahId,
+        const {
+            firstAyahId,
             ayahCount,
             surahOrder,
             rukuCount,
             name,
-            isMeccan,
-            page
-        ]: SurahInfo = getSurahInfo(surahNo as Surah)
+            isMeccan
+        } = getSurahMeta(surahNo as Surah)
         const { chapter, name: oName, englishname, arabicname, revelation, verses } = quranApi.chapters[surahNo - 1]
 
         if (surahNo !== chapter) console.warn("error QuranApi surah: ", surahNo, chapter)
-        if (startAyahId !== verses[0].line) console.warn("error QuranApi surah: ", startAyahId, verses[0].line)
+        if (firstAyahId !== verses[0].line) console.warn("error QuranApi surah: ", firstAyahId, verses[0].line)
         if (ayahCount !== verses.length) console.warn("error QuranApi surah: ", ayahCount, verses.length)
     }
 
diff --git a/src/ayahStringSplitter.ts b/src/ayahStringSplitter.ts
@@ -7,13 +7,15 @@ import { checkValidAyahId, checkValidSurahAyah } from "./validation"
  * @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 {Error} If the string format is invalid
- * @throws {Error} If surah number is invalid
- * @throws {Error} If ayah number(s) are invalid
- * @throws {Error} If ayah range is invalid (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 > end)
  * @example
+ * ```ts
  * ayahStringSplitter("2:255") // returns [2, 255]
  * ayahStringSplitter("1:1-7") // returns [1, [1, 7]]
+ * ```
  */
 export function ayahStringSplitter(str: string, isStrict = true): SurahAyahSegment {
   const result = isStrict ? string2NumberSplitterStrict(str) : string2NumberSplitter(str)
@@ -82,7 +84,7 @@ export function string2NumberSplitter(str: string): { ayah?: number, ayahTo?: nu
  *          - surahOrAyah: The surah number
  *          - ayah: The first or only ayah number
  *          - ayahTo: The ending ayah number (if range specified)
- * @throws {Error} When the input string format is invalid or contains non-numeric values
+ * @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 }
diff --git a/src/findManzilByAyahId.ts b/src/findManzilByAyahId.ts
@@ -9,7 +9,7 @@ import { checkValidAyahId } from "./validation"
  *
  * @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
+ * @throws {@link Error} If the provided Ayah ID is invalid
  *
  * @example
  * ```typescript
diff --git a/src/findRukuByAyahId.ts b/src/findRukuByAyahId.ts
@@ -8,10 +8,10 @@ import { checkValidAyahId } from "./validation"
  *
  * @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 {Error} If the provided Ayah ID is invalid
+ * @throws {@link Error} If the provided Ayah ID is invalid
  *
  * @example
- * ```typescript
+ * ```ts
  * const ruku = findRukuByAyahId("2:255");
  * // Returns the Ruku number containing Ayah 255 of Surah 2
  * ```
diff --git a/src/getPageMeta.ts b/src/getPageMeta.ts
@@ -7,8 +7,8 @@ import { checkValidPage } from "./validation"
  * Retrieves metadata for a specific page of the Quran.
  *
  * @param pageNum - The page number to retrieve metadata for (1-604)
- * @returns An object containing the page number, first ayah, and last ayah on the page
- * @throws RangeError If the page number is not between 1 and 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
  */
 export function getPageMeta(pageNum: Page): PageMeta {
   checkValidPage(pageNum)
diff --git a/src/getRukuMeta.ts b/src/getRukuMeta.ts
@@ -6,7 +6,7 @@ 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:
+ * @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
diff --git a/src/getSurahMeta.ts b/src/getSurahMeta.ts
@@ -0,0 +1,33 @@
+import { getSurahInfo } from "./getSurahInfo"
+import { Surah, SurahMeta } from "./types"
+
+/**
+ * Gets the metadata for the specified Surah.
+ *
+ * @param surah - The Surah to get the metadata for.
+ * @returns The metadata for the specified Surah.
+ */
+export function getSurahMeta(surahNum: Surah): SurahMeta {
+  const [
+    firstAyahId,
+    ayahCount,
+    surahOrder,
+    rukuCount,
+    name,
+    isMeccan
+  ] = getSurahInfo(surahNum)
+
+  const lastAyahId = firstAyahId + ayahCount - 1
+  return {
+    surahNum,
+    ayahCount,
+    surahOrder,
+    rukuCount,
+    name,
+    isMeccan,
+    firstAyahId,
+    lastAyahId,
+    first: [surahNum, 1],
+    last: [surahNum, ayahCount]
+  }
+}
diff --git a/src/index.ts b/src/index.ts
@@ -34,7 +34,7 @@ export { getRubAlHizb } from "./getRubAlHizb"
 export { getRubAlHizbMeta } from "./getRubAlHizbMeta"
 export { getRubAlHizbMetaByAyahId } from "./getRubAlHizbMetaByAyahId"
 export { getRubAlHizbByAyahId } from "./getRubAlHizbByAyahId"
-export { getSurahInfo as getSurahInfo } from "./getSurahInfo"
+export { getSurahMeta } from "./getSurahMeta"
 export { isAyahJuzFirst } from "./isAyahJuzFirst"
 export { isAyahPageFirst } from "./isAyahPageFirst"
 export { isSurahAyahJuzFirst } from "./isSurahAyahJuzFirst"
diff --git a/src/surahStringParser.ts b/src/surahStringParser.ts
@@ -5,7 +5,7 @@ import { Surah } from "./types"
  * 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 {Error} If the string cannot be parsed as a number or if the number is not a valid Surah number
+ * @throws {@link Error} If the string cannot be parsed as a number or if the number is not a valid Surah number
  */
 export function surahStringParser(str: string, isStrict = false): Surah {
   const surahX = isStrict ? Number(str.trim()) : Number.parseInt(str.trim(), 10)
diff --git a/src/typeGuards.ts b/src/typeGuards.ts
@@ -112,9 +112,11 @@ export function isValidRuku(x: unknown): x is Ruku {
  * @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
  * }
+ * ```
  */
 export function isValidManzil(x: unknown): x is Manzil {
   return Number.isInteger(x) && 1 <= (x as number) && x as number <= meta.numManzils
diff --git a/src/types.ts b/src/types.ts
@@ -83,6 +83,17 @@ export type Juz = NumericRange<0, typeof meta.numJuzs>
  */
 export type JuzPart = NumericRange<1, typeof meta.numRubsInJuz>
 
+// [start, ayas, order, rukus, name,  isMeccan, page ]
+export type SurahInfo = [
+  startAyahId: AyahId,
+  ayahCount: AyahNo,
+  surahOrder: Surah,
+  rukuCount: Ruku,
+  name: string,
+  isMeccan: boolean
+]
+export type SurahName = [name: string, translitName: string]
+
 export type RangeMeta = {
   firstAyahId: AyahId
   lastAyahId: AyahId
@@ -106,6 +117,15 @@ export type SurahAyah = [Surah, AyahNo]
 export type AyahRange = [AyahId, AyahId]
 export type SurahAyahSegment = [Surah, AyahNo | [AyahNo, AyahNo]]
 
+export type SurahMeta = {
+  name: string
+  surahNum: Surah
+  ayahCount: AyahNo
+  surahOrder: Surah
+  rukuCount: Ruku
+  isMeccan: boolean
+} & RangeMeta
+
 export type PageMeta = {
   pageNum: Page
 } & RangeMeta
@@ -134,16 +154,6 @@ export type SurahJuzMeta = {
 }
 export type SajdaType = "recommended" | "obligatory"
 export type Sajda = [AyahId, SajdaType]
-// [start, ayas, order, rukus, name,  isMeccan, page ]
-export type SurahInfo = [
-  startAyahId: AyahId,
-  ayahCount: AyahNo,
-  surahOrder: Surah,
-  rukuCount: Ruku,
-  name: string,
-  isMeccan: boolean
-]
-export type SurahName = [name: string, translitName: string]
 
 export type RangeMode = "juz" | "surah" | "ayah" | "page" | "ruku" | "all"
 
diff --git a/src/validation.ts b/src/validation.ts
@@ -71,8 +71,8 @@ export function checkValidAyahId(ayahId: unknown | number | AyahId): asserts aya
 /**
  * Checks if a value is a valid Page number.
  * @param x - The value to check
- * @throws {TypeError} When the value is not an integer
- * @throws {RangeError} When the value is not within valid page range (1 to numPages)
+ * @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
  */
 export function checkValidPage(x: unknown | number | Page): asserts x is Page {
@@ -90,8 +90,8 @@ export function checkValidPage(x: unknown | number | Page): asserts x is Page {
  * Throws RangeError if value is outside valid Juz range.
  *
  * @param x - Value to check
- * @throws {TypeError} If value is not an integer
- * @throws {RangeError} If value is not between 1 and the total number of Juz
+ * @throws {@link TypeError} If value is not an integer
+ * @throws {@link RangeError} If value is not between 1 and the total number of Juz
  */
 export function checkValidJuz(x: unknown | number | Juz): asserts x is Juz {
   if (typeof x !== "number" || !Number.isInteger(x)) {
@@ -104,11 +104,11 @@ export 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 {TypeError} If the value is not an integer number
- * @throws {RangeError} If the number is not within valid Ruku range
+ * @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
- * ```typescript
+ * ```ts
  * checkValidRuku(5); // OK
  * checkValidRuku("5"); // Throws TypeError
  * checkValidRuku(999); // Throws RangeError
@@ -126,8 +126,8 @@ export 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 {TypeError} If the value is not an integer
- * @throws {RangeError} If the value is not within valid Manzil range (1 to max manzils)
+ * @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
  */
 export function checkValidManzil(x: unknown | number | Manzil): asserts x is Manzil {
diff --git a/tests/getManzilMeta.spec.ts b/tests/getManzilMeta.spec.ts
@@ -0,0 +1,45 @@
+import { describe, it, expect } from "vitest"
+import { getManzilMeta } from "../src/getManzilMeta"
+
+describe("getManzilMeta", () => {
+  it("should return correct metadata for Manzil 1", () => {
+    const result = getManzilMeta(1)
+    expect(result).toEqual({
+      manzilNum: 1,
+      firstAyahId: 1,
+      lastAyahId: 669,
+      first: [1, 1],
+      last: [4, 176]
+    })
+  })
+
+  it("should return correct metadata for Manzil 4", () => {
+    const result = getManzilMeta(4)
+    expect(result).toEqual({
+      manzilNum: 4,
+      firstAyahId: 2030,
+      lastAyahId: 2932,
+      first: [17, 1],
+      last: [25, 77]
+    })
+  })
+
+  it("should return correct metadata for Manzil 8", () => {
+    const result = getManzilMeta(7)
+    expect(result).toEqual({
+      manzilNum: 7,
+      firstAyahId: 4631,
+      lastAyahId: 6236,
+      first: [50, 1],
+      last: [114, 6]
+    })
+  })
+
+  it("should throw error for invalid Manzil number 0", () => {
+    expect(() => getManzilMeta(0)).toThrow()
+  })
+
+  it("should throw error for invalid Manzil number 8", () => {
+    expect(() => getManzilMeta(8)).toThrow()
+  })
+})
diff --git a/tests/getSurahInfo.spec.ts b/tests/getSurahInfo.spec.ts
@@ -1,4 +1,5 @@
-import { findPage, getSurahInfo, meta, Surah, SurahList } from "../src"
+import { SurahList } from "../src"
+import { getSurahInfo } from "../src/getSurahInfo"
 
 describe("getSurahInfo", () => {
   it("should return correct metadata for first surah", () => {
@@ -11,7 +12,6 @@ describe("getSurahInfo", () => {
     expect(result).toEqual(SurahList[114])
   })
 
-
   it("should return correct metadata for a middle surah", () => {
     const result = getSurahInfo(57)
     expect(result).toEqual(SurahList[57])
diff --git a/tests/getSurahMeta.spec.ts b/tests/getSurahMeta.spec.ts
@@ -0,0 +1,35 @@
+import { getSurahMeta } from "../src/getSurahMeta"
+
+describe("getSurahMeta", () => {
+  it("returns correct metadata for Surah Al-Fatihah (1)", () => {
+    const meta = getSurahMeta(1)
+    expect(meta).toEqual({
+      surahNum: 1,
+      ayahCount: 7,
+      surahOrder: 5,
+      rukuCount: 1,
+      name: "الفاتحة",
+      isMeccan: true,
+      firstAyahId: 1,
+      lastAyahId: 7,
+      first: [1, 1],
+      last: [1, 7]
+    })
+  })
+
+  it("returns correct metadata for Surah Al-Baqarah (2)", () => {
+    const meta = getSurahMeta(2)
+    expect(meta).toEqual({
+      surahNum: 2,
+      ayahCount: 286,
+      surahOrder: 87,
+      rukuCount: 40,
+      name: "البقرة",
+      isMeccan: false,
+      firstAyahId: 8,
+      lastAyahId: 293,
+      first: [2, 1],
+      last: [2, 286]
+    })
+  })
+})
diff --git a/tests/meta.spec.ts b/tests/meta.spec.ts
@@ -1,5 +1,6 @@
-import { meta, getList, getSurahInfo, HizbQuarterList, JuzList, ManzilList, PageList, RukuList, SajdaList, SurahList } from "../src"
+import { meta, getList, HizbQuarterList, JuzList, ManzilList, PageList, RukuList, SajdaList, SurahList } from "../src"
 import { maxAyahsInSurah } from "../src/const"
+import { getSurahInfo } from "../src/getSurahInfo"
 
 describe("Meta constants", () => {
   it("should return correct numSurahs", () => {
diff --git a/tests/quran-data.spec.ts b/tests/quran-data.spec.ts
@@ -5,11 +5,11 @@ import {
   findSurahAyahByAyahId,
   findSurahByAyahId,
   getPageMeta,
-  getSurahInfo,
   isAyahJuzFirst,
   JuzList,
   meta
 } from "../src"
+import { getSurahInfo } from "../src/getSurahInfo"
 import { AyahId, AyahNo, Surah } from "../src/types"
 
 console.log("STARING")

Original file line number	Diff line number	Diff line change
`@@ -9,7 +9,7 @@ import { checkValidAyahId } from "./validation"`
`9`	`9`	`*`
`10`	`10`	`* @param ayahId - The ID of the Ayah to find the Manzil for`
`11`	`11`	`* @returns The Manzil number (1-7) containing the specified Ayah`
`12`		`- * @throws {Error} If the provided Ayah ID is invalid`
	`12`	`+ * @throws {@link Error} If the provided Ayah ID is invalid`
`13`	`13`	`*`
`14`	`14`	`* @example`
`15`	`15`	* ```typescript
Original file line number	Diff line number	Diff line change
`@@ -8,10 +8,10 @@ import { checkValidAyahId } from "./validation"`
`8`	`8`	`*`
`9`	`9`	`* @param ayahId - The unique identifier of an Ayah in format: surah:ayah (e.g., "2:255")`
`10`	`10`	`* @returns The Ruku number corresponding to the given Ayah ID`
`11`		`- * @throws {Error} If the provided Ayah ID is invalid`
	`11`	`+ * @throws {@link Error} If the provided Ayah ID is invalid`
`12`	`12`	`*`
`13`	`13`	`* @example`
`14`		- * ```typescript
	`14`	+ * ```ts
`15`	`15`	`* const ruku = findRukuByAyahId("2:255");`
`16`	`16`	`* // Returns the Ruku number containing Ayah 255 of Surah 2`
`17`	`17`	* ```