Overview Ramadan CLI is written in TypeScript and exports all type definitions. All API responses are validated at runtime using Zod schemas.
Prayer Data Types PrayerTimings Contains all prayer times for a day.
interface PrayerTimings { readonly Fajr : string ; readonly Sunrise : string ; readonly Dhuhr : string ; readonly Asr : string ; readonly Sunset : string ; readonly Maghrib : string ; readonly Isha : string ; readonly Imsak : string ; readonly Midnight : string ; readonly Firstthird : string ; readonly Lastthird : string ; }
Fajr prayer time (e.g., “05:30”)
Sunrise time (not a prayer)
Dhuhr (midday) prayer time
Asr (afternoon) prayer time
Sunset time (not a prayer)
Maghrib prayer time (immediately after sunset)
Imsak time (10 minutes before Fajr, used in Ramadan)
Islamic midnight (midpoint between sunset and sunrise)
End of first third of the night
Start of last third of the night
PrayerData Complete prayer data response from the API.
interface PrayerData { readonly timings : PrayerTimings ; readonly date : { readonly readable : string ; readonly timestamp : string ; readonly hijri : HijriDate ; readonly gregorian : GregorianDate ; }; readonly meta : PrayerMeta ; }
All prayer times for the day
Date information Human-readable date (e.g., “15 Mar 2024”)
Hijri (Islamic) date information
Gregorian date information
Calculation metadata (method, school, coordinates, timezone)
NextPrayerData Extends PrayerData with next prayer information.
interface NextPrayerData { readonly timings : PrayerTimings ; readonly date : PrayerData [ 'date' ]; readonly meta : PrayerMeta ; readonly nextPrayer : string ; readonly nextPrayerTime : string ; }
Name of next prayer (e.g., “Asr”, “Maghrib”)
Time of next prayer (e.g., “16:30”)
Metadata about prayer time calculation.
interface PrayerMeta { readonly latitude : number ; readonly longitude : number ; readonly timezone : string ; readonly method : { readonly id : number ; readonly name : string ; }; readonly school : | { readonly id : number ; readonly name : string ; } | string ; }
Latitude used for calculation
Longitude used for calculation
Calculation method information Method name (e.g., “University of Islamic Sciences, Karachi”)
Asr school information (may be string or object)
Date Types HijriDate Hijri (Islamic) calendar date.
interface HijriDate { readonly date : string ; readonly day : string ; readonly month : { readonly number : number ; readonly en : string ; readonly ar : string ; }; readonly year : string ; readonly weekday : { readonly en : string ; readonly ar : string ; }; }
Full date string (e.g., “15-09-1445”)
Day of month (e.g., “15”)
Month number (1-12, 9 = Ramadan)
English month name (e.g., “Ramadan”)
Arabic month name (e.g., “رَمَضان”)
Hijri year (e.g., “1445”)
GregorianDate Gregorian calendar date.
interface GregorianDate { readonly date : string ; readonly day : string ; readonly month : { readonly number : number ; readonly en : string ; }; readonly year : string ; readonly weekday : { readonly en : string ; }; }
Full date string (e.g., “15-03-2024”)
Day of month (e.g., “15”)
English month name (e.g., “March”)
Gregorian year (e.g., “2024”)
English weekday name (e.g., “Friday”)
Geolocation Types GeoLocation Complete location data with coordinates and timezone.
interface GeoLocation { readonly city : string ; readonly country : string ; readonly latitude : number ; readonly longitude : number ; readonly timezone : string ; }
CityCountryGuess City resolution result (timezone may be missing).
interface CityCountryGuess { readonly city : string ; readonly country : string ; readonly latitude : number ; readonly longitude : number ; readonly timezone ?: string ; }
IANA timezone string (may be undefined)
Calculation Method Types CalculationMethod Prayer time calculation method details.
interface CalculationMethod { readonly id : number ; readonly name : string ; readonly params : { readonly Fajr : number ; readonly Isha : number | string ; }; }
Full method name (e.g., “Islamic Society of North America (ISNA)”)
Calculation parameters Isha angle in degrees or fixed time offset
MethodsResponse Record of all available calculation methods.
type MethodsResponse = Readonly < Record < string , CalculationMethod >>;
Example:
{ "0" : { id: 0 , name: "Jafari (Shia Ithna-Ashari)" , params: { ... } }, "1" : { id: 1 , name: "University of Islamic Sciences, Karachi" , params: { ... } }, "2" : { id: 2 , name: "Islamic Society of North America (ISNA)" , params: { ... } }, // ... }
MethodId Branded type for type-safe method IDs.
type MethodId = number & { readonly __brand : 'MethodId' };
Qibla Types QiblaData Qibla direction information.
interface QiblaData { readonly latitude : number ; readonly longitude : number ; readonly direction : number ; }
Qibla bearing in degrees from North (0-360)
Configuration Types StoredLocation Stored location data (all fields optional).
interface StoredLocation { readonly city ?: string | undefined ; readonly country ?: string | undefined ; readonly latitude ?: number | undefined ; readonly longitude ?: number | undefined ; }
StoredPrayerSettings Stored prayer calculation settings.
interface StoredPrayerSettings { readonly method : number ; readonly school : number ; readonly timezone ?: string | undefined ; }
Calculation method ID (defaults to 2)
Asr school: 0 (Shafi) or 1 (Hanafi) (defaults to 0)
Function Option Types FetchByCityOptions interface FetchByCityOptions { readonly city : string ; readonly country : string ; readonly method ?: number ; readonly school ?: number ; readonly date ?: Date ; }
FetchByAddressOptions interface FetchByAddressOptions { readonly address : string ; readonly method ?: number ; readonly school ?: number ; readonly date ?: Date ; }
FetchByCoordsOptions interface FetchByCoordsOptions { readonly latitude : number ; readonly longitude : number ; readonly method ?: number ; readonly school ?: number ; readonly timezone ?: string ; readonly date ?: Date ; }
FetchNextPrayerOptions interface FetchNextPrayerOptions { readonly latitude : number ; readonly longitude : number ; readonly method ?: number ; readonly school ?: number ; readonly timezone ?: string ; }
FetchCalendarByCityOptions interface FetchCalendarByCityOptions { readonly city : string ; readonly country : string ; readonly year : number ; readonly month ?: number ; readonly method ?: number ; readonly school ?: number ; }
FetchCalendarByAddressOptions interface FetchCalendarByAddressOptions { readonly address : string ; readonly year : number ; readonly month ?: number ; readonly method ?: number ; readonly school ?: number ; }
FetchHijriCalendarByCityOptions interface FetchHijriCalendarByCityOptions { readonly city : string ; readonly country : string ; readonly year : number ; readonly month : number ; // Required for Hijri calendar readonly method ?: number ; readonly school ?: number ; }
FetchHijriCalendarByAddressOptions interface FetchHijriCalendarByAddressOptions { readonly address : string ; readonly year : number ; readonly month : number ; // Required for Hijri calendar readonly method ?: number ; readonly school ?: number ; }
Usage with TypeScript Import Types import type { PrayerData , PrayerTimings , HijriDate , GregorianDate , PrayerMeta , GeoLocation , QiblaData , CalculationMethod , MethodsResponse , } from 'ramadan-cli' ;
Type Guards All API responses are validated at runtime:
import { fetchTimingsByCity } from 'ramadan-cli' ; // Response is guaranteed to match PrayerData interface const data = await fetchTimingsByCity ({ city: 'Lahore' , country: 'Pakistan' , }); // TypeScript knows the exact shape const fajr : string = data . timings . Fajr ; const hijriMonth : string = data . date . hijri . month . en ;
Readonly Types All types use readonly modifiers to prevent accidental mutations:
const data = await fetchTimingsByCity ({ city: 'Lahore' , country: 'Pakistan' }); // TypeScript error: Cannot assign to 'Fajr' because it is a read-only property data . timings . Fajr = '06:00' ;
Runtime Validation All API responses are validated using Zod schemas. If the API returns unexpected data, an error is thrown:
try { const data = await fetchTimingsByCity ({ city: 'Invalid' , country: 'Invalid' , }); } catch ( error ) { // Error: Invalid API response: ... }