Types - Ramadan CLI

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;
}

string

Fajr prayer time (e.g., “05:30”)

string

Sunrise time (not a prayer)

string

Dhuhr (midday) prayer time

string

Asr (afternoon) prayer time

string

Sunset time (not a prayer)

string

Maghrib prayer time (immediately after sunset)

string

Isha (night) prayer time

string

Imsak time (10 minutes before Fajr, used in Ramadan)

string

Islamic midnight (midpoint between sunset and sunrise)

string

End of first third of the night

string

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;
}

PrayerTimings

All prayer times for the day

object

Date information

Show properties

string

Human-readable date (e.g., “15 Mar 2024”)

string

Unix timestamp as string

HijriDate

Hijri (Islamic) date information

GregorianDate

Gregorian date information

PrayerMeta

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;
}

string

Name of next prayer (e.g., “Asr”, “Maghrib”)

string

Time of next prayer (e.g., “16:30”)

PrayerMeta

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;
}

number

Latitude used for calculation

number

Longitude used for calculation

string

IANA timezone string

object

Calculation method information

Show properties

number

Method ID (0-23)

string

Method name (e.g., “University of Islamic Sciences, Karachi”)

object | string

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;
  };
}

string

Full date string (e.g., “15-09-1445”)

string

Day of month (e.g., “15”)

object

Show properties

number

Month number (1-12, 9 = Ramadan)

string

English month name (e.g., “Ramadan”)

string

Arabic month name (e.g., “رَمَضان”)

string

Hijri year (e.g., “1445”)

object

Show properties

string

English weekday name

string

Arabic weekday name

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;
  };
}

string

Full date string (e.g., “15-03-2024”)

string

Day of month (e.g., “15”)

object

Show properties

number

Month number (1-12)

string

English month name (e.g., “March”)

string

Gregorian year (e.g., “2024”)

object

Show properties

string

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;
}

string

City name

string

Country name

number

Latitude coordinate

number

Longitude coordinate

string

IANA 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;
}

string | undefined

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;
  };
}

number

Method ID (0-23)

string

Full method name (e.g., “Islamic Society of North America (ISNA)”)

object

Calculation parameters

Show properties

number

Fajr angle in degrees

number | string

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;
}

number

Input latitude

number

Input longitude

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;
}

number

Calculation method ID (defaults to 2)

number

Asr school: 0 (Shafi) or 1 (Hanafi) (defaults to 0)

string | undefined

Timezone override

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: ...
}

​Overview

​Prayer Data Types

​PrayerTimings

​PrayerData

​NextPrayerData

​PrayerMeta

​Date Types

​HijriDate

​GregorianDate

​Geolocation Types

​GeoLocation

​CityCountryGuess

​Calculation Method Types

​CalculationMethod

​MethodsResponse

​MethodId

​Qibla Types

​QiblaData

​Configuration Types

​StoredLocation

​StoredPrayerSettings

​Function Option Types

​FetchByCityOptions

​FetchByAddressOptions

​FetchByCoordsOptions

​FetchNextPrayerOptions

​FetchCalendarByCityOptions

​FetchCalendarByAddressOptions

​FetchHijriCalendarByCityOptions

​FetchHijriCalendarByAddressOptions

​Usage with TypeScript

​Import Types

​Type Guards

​Readonly Types

​Runtime Validation

Overview

Prayer Data Types

PrayerTimings

PrayerData

NextPrayerData

PrayerMeta

Date Types

HijriDate

GregorianDate

Geolocation Types

GeoLocation

CityCountryGuess

Calculation Method Types

CalculationMethod

MethodsResponse

MethodId

Qibla Types

QiblaData

Configuration Types

StoredLocation

StoredPrayerSettings

Function Option Types

FetchByCityOptions

FetchByAddressOptions

FetchByCoordsOptions

FetchNextPrayerOptions

FetchCalendarByCityOptions

FetchCalendarByAddressOptions

FetchHijriCalendarByCityOptions

FetchHijriCalendarByAddressOptions

Usage with TypeScript

Import Types

Type Guards

Readonly Types

Runtime Validation