Configuration - Ramadan CLI

Overview

The configuration API provides functions to manage persistent storage of user preferences. All settings are stored using the conf library in a local configuration file.

Location Management

getStoredLocation

Retrieve the stored location from configuration.

import { getStoredLocation } from 'ramadan-cli';

const location = getStoredLocation();

console.log(location.city);      // "Lahore" or undefined
console.log(location.country);   // "Pakistan" or undefined
console.log(location.latitude);  // 31.5204 or undefined
console.log(location.longitude); // 74.3587 or undefined

return

StoredLocation

Show properties

city

string | undefined

Stored city name

country

string | undefined

Stored country name

latitude

number | undefined

Stored latitude coordinate

longitude

number | undefined

Stored longitude coordinate

setStoredLocation

Save location data to configuration.

import { setStoredLocation } from 'ramadan-cli';

setStoredLocation({
  city: 'Istanbul',
  country: 'Turkey',
  latitude: 41.0082,
  longitude: 28.9784,
});

console.log('Location saved');

location

StoredLocation

required

Show properties

city

string

City name to store

country

string

Country name to store

latitude

number

Latitude coordinate

longitude

number

Longitude coordinate

All fields are optional. You can update individual fields without overwriting others.

hasStoredLocation

Check if a valid location is stored.

import { hasStoredLocation } from 'ramadan-cli';

if (hasStoredLocation()) {
  console.log('Location is configured');
} else {
  console.log('No location stored');
}

return

boolean

true if either city/country or coordinates are stored

Prayer Settings

getStoredPrayerSettings

Get calculation method, school, and timezone settings.

import { getStoredPrayerSettings } from 'ramadan-cli';

const settings = getStoredPrayerSettings();

console.log(settings.method);   // 2 (ISNA)
console.log(settings.school);   // 0 (Shafi)
console.log(settings.timezone); // "America/New_York" or undefined

return

StoredPrayerSettings

Show properties

method

number

Calculation method ID (0-23). Defaults to 2 (ISNA)

school

number

Asr calculation school: 0 (Shafi) or 1 (Hanafi). Defaults to 0

timezone

string | undefined

IANA timezone string, if set

setStoredMethod

Set the calculation method.

import { setStoredMethod } from 'ramadan-cli';

setStoredMethod(13); // Turkey method

method

number

required

Calculation method ID (0-23). See prayer times methods

setStoredSchool

Set the Asr calculation school.

import { setStoredSchool } from 'ramadan-cli';

setStoredSchool(1); // Hanafi school (later Asr)

school

number

required

School ID: 0 for Shafi (standard) or 1 for Hanafi (later Asr)

setStoredTimezone

Set the timezone override.

import { setStoredTimezone } from 'ramadan-cli';

setStoredTimezone('Asia/Dubai');

timezone

string

IANA timezone string (e.g., “Asia/Karachi”, “Europe/London”)

Ramadan Date Settings

getStoredFirstRozaDate

Get the configured first roza date (for custom Ramadan tracking).

import { getStoredFirstRozaDate } from 'ramadan-cli';

const date = getStoredFirstRozaDate();

if (date) {
  console.log(date); // "2024-03-11" (ISO format)
}

return

string | undefined

ISO date string (YYYY-MM-DD) or undefined if not set

setStoredFirstRozaDate

Set the first roza date for custom Ramadan tracking.

import { setStoredFirstRozaDate } from 'ramadan-cli';

try {
  setStoredFirstRozaDate('2024-03-11');
  console.log('First roza date saved');
} catch (error) {
  console.error('Invalid date format');
}

date

string

required

ISO date string in YYYY-MM-DD format

The date must be in ISO format (YYYY-MM-DD). Invalid formats will throw an error.

clearStoredFirstRozaDate

Remove the stored first roza date.

import { clearStoredFirstRozaDate } from 'ramadan-cli';

clearStoredFirstRozaDate();
console.log('First roza date cleared');

Bulk Operations

saveAutoDetectedSetup

Save location and apply recommended settings based on country.

import { guessLocation, saveAutoDetectedSetup } from 'ramadan-cli';

const location = await guessLocation();

if (location) {
  saveAutoDetectedSetup(location);
  console.log('Setup complete with recommended settings');
}

location

GeoLocation

required

Location data from guessLocation()

This function:

Saves city, country, coordinates
Saves timezone
Applies recommended calculation method for the country
Applies recommended school (Hanafi/Shafi) for the country

clearRamadanConfig

Clear all stored configuration.

import { clearRamadanConfig } from 'ramadan-cli';

clearRamadanConfig();
console.log('All configuration cleared');

This deletes all stored settings including location, method, school, timezone, and first roza date.

Recommendations System

getRecommendedMethod

Get the recommended calculation method for a country.

import { getRecommendedMethod } from 'ramadan-cli';

const method = getRecommendedMethod('Pakistan');
console.log(method); // 1 (Karachi method)

const method2 = getRecommendedMethod('United States');
console.log(method2); // 2 (ISNA)

const method3 = getRecommendedMethod('Unknown Country');
console.log(method3); // null (no recommendation)

country

string

required

Country name (case-insensitive)

return

number | null

Recommended method ID or null if no recommendation

getRecommendedSchool

Get the recommended Asr school for a country.

import { getRecommendedSchool } from 'ramadan-cli';

const school = getRecommendedSchool('Pakistan');
console.log(school); // 1 (Hanafi)

const school2 = getRecommendedSchool('Saudi Arabia');
console.log(school2); // 0 (Shafi)

country

string

required

Country name (case-insensitive)

return

number

0 for Shafi (standard) or 1 for Hanafi (later Asr)

Hanafi Countries

The following countries default to Hanafi school:

Pakistan
Bangladesh
India
Afghanistan
Turkey
Iraq
Syria
Jordan
Palestine
Central Asian countries (Kazakhstan, Uzbekistan, Tajikistan, etc.)

All other countries default to Shafi school.

shouldApplyRecommendedMethod

Check if a recommended method should be applied based on current and recommended values.

import { shouldApplyRecommendedMethod } from 'ramadan-cli';

// Returns true if current is default (2) or matches recommended
const shouldApply = shouldApplyRecommendedMethod(2, 1);
console.log(shouldApply); // true

// Returns false if user has customized to a different method
const shouldApply2 = shouldApplyRecommendedMethod(3, 1);
console.log(shouldApply2); // false

currentMethod

number

required

Current method ID

recommendedMethod

number

required

Recommended method ID

return

boolean

True if recommendation should be applied

shouldApplyRecommendedSchool

Check if a recommended school should be applied based on current and recommended values.

import { shouldApplyRecommendedSchool } from 'ramadan-cli';

// Returns true if current is default (0=Shafi) or matches recommended
const shouldApply = shouldApplyRecommendedSchool(0, 1);
console.log(shouldApply); // true

// Returns false if user has customized to a different school
const shouldApply2 = shouldApplyRecommendedSchool(1, 0);
console.log(shouldApply2); // false

currentSchool

number

required

Current school (0=Shafi, 1=Hanafi)

recommendedSchool

number

required

Recommended school

return

boolean

True if recommendation should be applied

applyRecommendedSettingsIfUnset

Apply recommended settings only if user hasn’t customized them.

import { applyRecommendedSettingsIfUnset } from 'ramadan-cli';

applyRecommendedSettingsIfUnset('Turkey');

country

string

required

Country name

Usage Examples

Complete Setup Flow

import {
  guessLocation,
  saveAutoDetectedSetup,
  getStoredLocation,
  getStoredPrayerSettings,
  hasStoredLocation,
} from 'ramadan-cli';

// Check if already configured
if (hasStoredLocation()) {
  console.log('Already configured');
  
  const location = getStoredLocation();
  const settings = getStoredPrayerSettings();
  
  console.log(`Location: ${location.city}, ${location.country}`);
  console.log(`Method: ${settings.method}, School: ${settings.school}`);
} else {
  // Auto-detect and save
  const location = await guessLocation();
  
  if (location) {
    saveAutoDetectedSetup(location);
    console.log('Configuration saved with recommendations');
  } else {
    console.log('Could not auto-detect location');
  }
}

Manual Configuration

import {
  setStoredLocation,
  setStoredMethod,
  setStoredSchool,
  setStoredTimezone,
  getRecommendedMethod,
  getRecommendedSchool,
} from 'ramadan-cli';

// Set location
setStoredLocation({
  city: 'Cairo',
  country: 'Egypt',
  latitude: 30.0444,
  longitude: 31.2357,
});

// Apply recommended settings
const method = getRecommendedMethod('Egypt');
if (method !== null) {
  setStoredMethod(method); // 5 (Egypt method)
}

const school = getRecommendedSchool('Egypt');
setStoredSchool(school); // 0 (Shafi)

setStoredTimezone('Africa/Cairo');

console.log('Configuration complete');

Update Individual Settings

import {
  getStoredLocation,
  setStoredLocation,
  getStoredPrayerSettings,
  setStoredMethod,
} from 'ramadan-cli';

// Update only the city, keep everything else
const current = getStoredLocation();
setStoredLocation({
  ...current,
  city: 'Ankara',
});

// Update only the method
setStoredMethod(13); // Turkey method

console.log('Settings updated');

Custom Ramadan Dates

import {
  setStoredFirstRozaDate,
  getStoredFirstRozaDate,
  clearStoredFirstRozaDate,
} from 'ramadan-cli';

// Set custom Ramadan start date
setStoredFirstRozaDate('2024-03-11');

const date = getStoredFirstRozaDate();
console.log(`Ramadan starts: ${date}`);

// Clear it later
clearStoredFirstRozaDate();
console.log('Now using Hijri calendar for Ramadan dates');

Configuration Location

Configuration is stored in:

Linux: ~/.config/ramadan-cli/config.json
macOS: ~/Library/Preferences/ramadan-cli/config.json
Windows: %APPDATA%\ramadan-cli\Config\config.json

You can override the config directory using the RAMADAN_CLI_CONFIG_DIR environment variable:

export RAMADAN_CLI_CONFIG_DIR=/custom/path

TypeScript Types

interface StoredLocation {
  readonly city?: string | undefined;
  readonly country?: string | undefined;
  readonly latitude?: number | undefined;
  readonly longitude?: number | undefined;
}

interface StoredPrayerSettings {
  readonly method: number;
  readonly school: number;
  readonly timezone?: string | undefined;
}

Core API

Types

​Overview

​Location Management

​getStoredLocation

​setStoredLocation

​hasStoredLocation

​Prayer Settings

​getStoredPrayerSettings

​setStoredMethod

​setStoredSchool

​setStoredTimezone

​Ramadan Date Settings

​getStoredFirstRozaDate

​setStoredFirstRozaDate

​clearStoredFirstRozaDate

​Bulk Operations

​saveAutoDetectedSetup

​clearRamadanConfig

​Recommendations System

​getRecommendedMethod

​getRecommendedSchool

​Hanafi Countries

​shouldApplyRecommendedMethod

​shouldApplyRecommendedSchool

​applyRecommendedSettingsIfUnset

​Usage Examples

​Complete Setup Flow

​Manual Configuration

​Update Individual Settings

​Custom Ramadan Dates

​Configuration Location

​TypeScript Types

Overview

Location Management

getStoredLocation

setStoredLocation

hasStoredLocation

Prayer Settings

getStoredPrayerSettings

setStoredMethod

setStoredSchool

setStoredTimezone

Ramadan Date Settings

getStoredFirstRozaDate

setStoredFirstRozaDate

clearStoredFirstRozaDate

Bulk Operations

saveAutoDetectedSetup

clearRamadanConfig

Recommendations System

getRecommendedMethod

getRecommendedSchool

Hanafi Countries

shouldApplyRecommendedMethod

shouldApplyRecommendedSchool

applyRecommendedSettingsIfUnset

Usage Examples

Complete Setup Flow

Manual Configuration

Update Individual Settings

Custom Ramadan Dates

Configuration Location

TypeScript Types