quran-meta/lib_cjs/validation.d.cts

Library with meta data and functionality related to Holy Quran

import { AyahId, AyahNo, Juz, Manzil, Page, Ruku, Surah } from "./types.cjs";

//#region src/validation.d.ts

/**
 * Validates if the provided value is a valid Surah number.
 *
 * @param surah - The value to validate, can be a Surah object, number, or unknown type
 * @throws TypeError When the provided value is not an integer
 * @throws RangeError When the provided surah number is outside the valid range (1 to total number of surahs)
 * @remarks This is a type assertion function that ensures the input is a valid Surah
 */
declare function checkValidSurah(surah: Surah | number | unknown): asserts surah is Surah;
/**
 * Validates if the given surah and ayah numbers form a valid combination.
 * @param surah - The surah number or Surah object to validate
 * @param ayah - The ayah number or AyahNo object to validate
 * @throws Error If the surah-ayah combination is invalid
 */
declare function checkValidSurahAyah(surah: Surah | number | unknown, ayah: number | AyahNo | unknown): void;
/**
 * Validates that a surah-ayah pair contains valid values
 * @param surahAyah - A tuple containing surah number/object and ayah number
 * @throws RangeError If ayah number is not between 1 and the maximum ayah count for the given surah
 * @throws If surah is invalid (from checkValidSurah)
 * @example
 * ```ts
 * checkValidSurahAyahPair([1, 7]) // Valid
 * checkValidSurahAyahPair([1, 8]) // Throws RangeError
 * ```
 */

/**
 * Validates and asserts that the given value is a valid Ayah ID.
 * An Ayah ID must be an integer between 1 and the total number of Ayahs.
 *
 * @param ayahId - The value to check as an Ayah ID
 * @throws TypeError If the value is not an integer
 * @throws RangeError If the value is not within valid Ayah ID range
 */
declare function checkValidAyahId(ayahId: unknown | number | AyahId): asserts ayahId is AyahId;
/**
 * Checks if a value is a valid Page number.
 * @param x - The value to check
 * @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
 */
declare function checkValidPage(x: unknown | number | Page): asserts x is Page;
/**
 * Type guard that checks if a value is a valid Juz number.
 * Throws TypeError if value is not an integer.
 * Throws RangeError if value is outside valid Juz range.
 *
 * @param x - Value to check
 * @throws {@link TypeError} If value is not an integer
 * @throws {@link RangeError} If value is not between 1 and the total number of Juz
 */
declare 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 {@link TypeError} If the value is not an integer number
 * @throws {@link RangeError} If the number is not within valid Ruku range
 * @example
 * ```ts
 * checkValidRuku(5); // OK
 * checkValidRuku("5"); // Throws TypeError
 * checkValidRuku(999); // Throws RangeError
 * ```
 */
declare 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 {@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
 */
declare function checkValidManzil(x: unknown | number | Manzil): asserts x is Manzil;
//#endregion
export { checkValidAyahId, checkValidJuz, checkValidManzil, checkValidPage, checkValidRuku, checkValidSurah, checkValidSurahAyah };