✨ Features

| Feature | Description | |---------|-------------| | 📅 65+ Festivals | Comprehensive data across 8 categories | | 🕉️ Multi-Religious | Hindu, Islamic, Christian, Sikh, Buddhist, Jain, Tribal & National | | 📖 Rich Information | Description, history, significance, customs & traditional foods | | 📆 Verified Dates | Year-wise dates for 2026, 2027 and 2028 | | 🗓️ Hindu Calendar | Tithi, Paksha, and Month information | | 🌙 Islamic Calendar | Day and Month in Islamic calendar | | 🔍 Powerful Search | Search by name, religion, region, date & more | | 📦 TypeScript | Full type definitions included | | ⚡ Dual Module | ESM & CommonJS support | | 🪶 Zero Dependencies | Lightweight with no external dependencies |

📦 Installation

# npm
npm install @aryanjsx/indian-festivals

# yarn
yarn add @aryanjsx/indian-festivals

# pnpm
pnpm add @aryanjsx/indian-festivals

🚀 Quick Start

ESM (ES Modules)

import { 
  allFestivals, 
  getFestivalBySlug, 
  getUpcomingFestivals 
} from '@aryanjsx/indian-festivals';

// Get total count
console.log(`Total festivals: ${allFestivals.length}`); // 65

// Get Diwali details
const diwali = getFestivalBySlug('diwali');
console.log(diwali?.name);           // "Diwali"
console.log(diwali?.dates[2025]);    // "2025-10-20"
console.log(diwali?.religion);       // "Hindu"

// Get next 5 upcoming festivals
const upcoming = getUpcomingFestivals(new Date(), 5);

CommonJS

const { 
  allFestivals, 
  getFestivalBySlug 
} = require('@aryanjsx/indian-festivals');

const holi = getFestivalBySlug('holi');
console.log(holi.dates[2025]); // "2025-03-14"

🎊 Festival Categories

| Category | Count | Key Festivals | |----------|:-----:|---------------| | 🕉️ Hindu | 24 | Diwali, Holi, Navratri, Dussehra, Ganesh Chaturthi, Janmashtami, Maha Shivaratri | | ☪️ Islamic | 5 | Eid ul-Fitr, Eid ul-Adha, Muharram, Milad-un-Nabi, Shab-e-Barat | | ✝️ Christian | 5 | Christmas, Good Friday, Easter, All Saints' Day | | 🙏 Sikh | 6 | Guru Nanak Jayanti, Baisakhi, Lohri, Hola Mohalla | | ☸️ Buddhist | 5 | Buddha Purnima, Ambedkar Jayanti, Losar, Hemis Festival | | 🙏 Jain | 5 | Mahavir Jayanti, Paryushana, Samvatsari | | 🏔️ Tribal | 7 | Bihu, Hornbill Festival, Sarhul, Wangala, Karma | | 🇮🇳 National | 8 | Republic Day, Independence Day, Gandhi Jayanti |

📚 API Reference

Festival Data Exports

import {
  // All festivals combined
  allFestivals,           // Festival[] - All 65+ festivals
  festivalsById,          // Map<string, Festival> - Lookup by ID
  festivalsByReligion,    // Record<Religion, Festival[]>

  // By religion
  hinduFestivals,         // Festival[] - 24 Hindu festivals
  islamicFestivals,       // Festival[] - 5 Islamic festivals
  christianFestivals,     // Festival[] - 5 Christian festivals
  sikhFestivals,          // Festival[] - 6 Sikh festivals
  buddhistFestivals,      // Festival[] - 5 Buddhist festivals
  jainFestivals,          // Festival[] - 5 Jain festivals
  tribalFestivals,        // Festival[] - 7 Tribal festivals
  nationalFestivals,      // Festival[] - 8 National festivals
} from '@aryanjsx/indian-festivals';

Date Data Exports

import {
  // Year-specific dates
  dates2026,              // FestivalDateEntry[] - All dates for 2026
  dates2027,              // FestivalDateEntry[] - All dates for 2027
  allDates,               // FestivalDateEntry[] - All years combined
  datesByYear,            // Record<number, FestivalDateEntry[]>

  // Helper functions
  getDatesForYear,        // (year: number) => FestivalDateEntry[]
  getAvailableYears,      // () => number[] - Returns [2025, 2026, 2027]
} from '@aryanjsx/indian-festivals';

Utility Functions

🔍 Festival Lookup

import { 
  getFestivalBySlug,      // Get by ID: getFestivalBySlug('diwali')
  getFestivalByName,      // Get by name: getFestivalByName('Deepavali')
  festivalExists          // Check: festivalExists('holi') => true
} from '@aryanjsx/indian-festivals';

🕉️ Religion-based Queries

import {
  getFestivalsByReligion,      // Get all Hindu festivals
  getFestivalsByReligions,     // Get Hindu + Sikh festivals
  getFestivalCountByReligion,  // { Hindu: 24, Islamic: 5, ... }
  getAvailableReligions,       // ['Hindu', 'Islamic', ...]
  getPublicHolidays,           // All government holidays
} from '@aryanjsx/indian-festivals';

📅 Date-based Queries

import {
  getFestivalsByMonth,         // Festivals in October 2025
  getFestivalsByMonthAllYears, // October festivals (all years)
  getFestivalsInDateRange,     // Festivals between two dates
  getFestivalsOnDate,          // Festivals on specific date
  getFullFestivalsByMonth,     // Full festival objects for month
} from '@aryanjsx/indian-festivals';

⏰ Upcoming Festivals

import {
  getUpcomingFestivals,   // Next N festivals from date
  getNextFestival,        // Next occurrence of specific festival
  getTodaysFestivals,     // Festivals happening today
  getThisWeeksFestivals,  // Festivals in next 7 days
  getThisMonthsFestivals, // Festivals this month
} from '@aryanjsx/indian-festivals';

🔎 Search & Filter

import {
  searchFestivals,        // Text search across all fields
  filterFestivals,        // Multi-criteria filter
  getFestivalsByRegion,   // Festivals in Kerala
  getFestivalsByType,     // LUNAR, SOLAR, or FIXED
  getAllRegions,          // All unique regions
  getRelatedFestivals,    // Related festivals
} from '@aryanjsx/indian-festivals';

💡 Examples

Get Upcoming Festivals

import { getUpcomingFestivals } from '@aryanjsx/indian-festivals';

const upcoming = getUpcomingFestivals(new Date('2025-10-01'), 5);

upcoming.forEach(({ festival, date, daysUntil }) => {
  console.log(`${festival.name} - ${date} (${daysUntil} days away)`);
});

// Output:
// Dussehra - 2025-10-02 (1 days away)
// Gandhi Jayanti - 2025-10-02 (1 days away)
// Karwa Chauth - 2025-10-10 (9 days away)
// Dhanteras - 2025-10-18 (17 days away)
// Diwali - 2025-10-20 (19 days away)

Search Festivals

import { searchFestivals } from '@aryanjsx/indian-festivals';

const results = searchFestivals('light');

results.slice(0, 3).forEach(({ festival, matchScore }) => {
  console.log(`${festival.name}: ${matchScore}`);
});

// Output:
// Diwali: 130 (matches "Festival of Lights")

Filter Festivals

import { filterFestivals } from '@aryanjsx/indian-festivals';

const filtered = filterFestivals({
  religion: 'Hindu',
  isPublicHoliday: true,
  year: 2025,
  month: 10  // October
});

filtered.forEach(f => console.log(f.name));
// Dussehra, Diwali

Get Festival Details

import { getFestivalBySlug } from '@aryanjsx/indian-festivals';

const diwali = getFestivalBySlug('diwali');

if (diwali) {
  console.log('Name:', diwali.name);
  console.log('Also known as:', diwali.alternateNames?.join(', '));
  console.log('Religion:', diwali.religion);
  console.log('Regions:', diwali.regions.join(', '));
  console.log('Duration:', diwali.duration, 'days');
  console.log('Public Holiday:', diwali.isPublicHoliday);
  
  // Hindu calendar details
  console.log('Tithi:', diwali.hinduCalendar?.tithi);
  console.log('Paksha:', diwali.hinduCalendar?.paksha);
  console.log('Month:', diwali.hinduCalendar?.month);
  
  // Dates
  console.log('2025:', diwali.dates[2025]);
  console.log('2026:', diwali.dates[2026]);
  console.log('2027:', diwali.dates[2027]);
  
  // Rich content
  console.log('Description:', diwali.description);
  console.log('History:', diwali.history);
  console.log('Significance:', diwali.significance);
  console.log('Customs:', diwali.customs?.join(', '));
  console.log('Foods:', diwali.foods?.join(', '));
}

Build a Festival Calendar

import { getFestivalsByMonth, monthNames } from '@aryanjsx/indian-festivals';

// Get festivals for each month of 2025
for (let month = 1; month <= 12; month++) {
  const { festivals } = getFestivalsByMonth(month, 2025);
  console.log(`\n📅 ${monthNames[month - 1]} 2025 (${festivals.length} festivals)`);
  festivals.forEach(f => {
    console.log(`  ${f.date}: ${f.name} (${f.religion})`);
  });
}

📋 Festival Object Structure

interface Festival {
  // Identity
  id: string;                    // "diwali"
  name: string;                  // "Diwali"
  alternateNames?: string[];     // ["Deepavali", "Festival of Lights"]
  
  // Classification
  religion: Religion;            // "Hindu"
  regions: Region[];             // ["Pan-India"]
  type: FestivalType;            // "LUNAR" | "SOLAR" | "FIXED"
  
  // Rich Content
  description: string;           // Detailed description
  history: string;               // Historical background
  significance: string;          // Cultural/spiritual significance
  
  // Dates
  dates: Record<number, string>; // { 2025: "2025-10-20", ... }
  
  // Calendar Systems
  hinduCalendar?: {
    tithi: Tithi;                // "Amavasya"
    paksha: Paksha;              // "Krishna"
    month: HinduMonth;           // "Kartik"
  };
  islamicCalendar?: {
    day: number;                 // 1
    month: IslamicMonth;         // "Shawwal"
  };
  
  // Metadata
  duration?: number;             // 5 (days)
  isPublicHoliday?: boolean;     // true
  relatedFestivals?: string[];   // ["dhanteras", "govardhan-puja"]
  
  // Traditions
  customs?: string[];            // ["Lighting diyas", "Lakshmi Puja", ...]
  foods?: string[];              // ["Ladoo", "Barfi", "Gulab Jamun", ...]
}

🌍 Supported Regions

The package covers festivals celebrated across:

• Pan-India - Nationwide celebrations
• Regional - North, South, East, West, Central, Northeast India
• States - All 28 states and 8 union territories
• Special Locations - Nepal, Dharamsala, Anandpur Sahib

📖 Data Sources

Festival dates and information verified from authoritative sources:

| Source | Coverage | |--------|----------| | Drik Panchang | Hindu lunar calendar, tithi, paksha | | Government of India | Official gazetted holidays | | SGPC | Sikh festivals and Gurpurabs | | Islamic Calendar | Eid, Muharram, Milad dates | | State Cultural Portals | Regional & tribal festivals |

⚠️ Note: Islamic festival dates may vary by 1-2 days based on moon sighting. Verify closer to the event.

📝 TypeScript Types

Full type definitions included:

import type {
  Festival,
  Religion,
  Region,
  FestivalType,
  FestivalDateEntry,
  HinduCalendarInfo,
  IslamicCalendarInfo,
  Tithi,
  Paksha,
  HinduMonth,
  IslamicMonth,
  FestivalFilter,
  FestivalSearchResult,
  UpcomingFestival,
  MonthlyFestivals,
} from '@aryanjsx/indian-festivals';

🤝 Contributing

Contributions are welcome! Here's how you can help:

1. 🍴 Fork the repository
2. 🌿 Create a feature branch (git checkout -b feature/add-festival)
3. ✏️ Add your changes with proper sources
4. ✅ Ensure all data is accurate and verified
5. 📝 Update documentation if needed
6. 🚀 Submit a pull request

Adding a New Festival

export const newFestival: Festival = {
  id: "festival-slug",
  name: "Festival Name",
  religion: "Hindu",
  regions: ["Region"],
  type: "LUNAR",
  description: "...",
  history: "...",
  significance: "...",
  dates: {
    2025: "2025-MM-DD",
    2026: "2026-MM-DD",
    2027: "2027-MM-DD"
  },
  // ... other fields
};

📄 License

MIT © aryanjsx