Configuration

Manage stored location and prayer calculation settings

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:

1. Saves city, country, coordinates
2. Saves timezone
3. Applies recommended calculation method for the country
4. 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;
}