Indian Banking Holiday

A lightweight, zero-dependency npm library for Indian banking holidays. Query holidays by date, state, or date range. All banks in India follow the same holidays as per RBI regulations.

Features

• Comprehensive Coverage — National, state-specific, and regional holidays (2025-2027)
• Validated Data — All holidays validated against official HDFC Bank and RBI sources
• State-wise Filtering — Get holidays for any Indian state or union territory
• TypeScript Support — Full type definitions included
• Simple API — Easy-to-use functions for common queries
• Date Range Queries — Get holidays within any date range
• Zero Dependencies — Lightweight and fast
• ESM & CommonJS — Works with both module systems
• Well Tested — Comprehensive test suite with 229+ tests

Installation

npm install indian-banking-holiday

Quick Start

import {
  getAllHolidays,
  getHolidaysByYear,
  getHolidaysByState,
  isHoliday,
  getNextHoliday,
} from 'indian-banking-holiday';

// Get all holidays
const allHolidays = getAllHolidays();

// Get holidays for a specific year
const holidays2026 = getHolidaysByYear(2026);

// Check if a date is a holiday
isHoliday('2026-01-26'); // true (Republic Day)

// Get holidays for a specific state
const maharashtraHolidays = getHolidaysByState('Maharashtra', 2026);

// Get the next upcoming holiday
const nextHoliday = getNextHoliday();

API Reference

getAllHolidays()

Returns all banking holidays in the database.

const holidays = getAllHolidays();
// Returns: Holiday[]

getHolidays(options?)

Query holidays with flexible filtering options.

// Get holidays for a year
const result = getHolidays({ year: 2026 });

// Get holidays for a specific month
const janHolidays = getHolidays({ year: 2026, month: 1 });

// Get holidays for a state
const stateHolidays = getHolidays({ 
  state: 'Maharashtra', 
  year: 2026 
});

// Get holidays in a date range
const rangeHolidays = getHolidays({
  startDate: '2026-01-01',
  endDate: '2026-03-31',
  state: 'Karnataka'
});

Options:

| Option | Type | Description | |--------|------|-------------| | year | number | Filter by year | | month | number | Filter by month (1-12) | | state | IndianState | Filter by state | | startDate | string | Start date (YYYY-MM-DD) | | endDate | string | End date (YYYY-MM-DD) |

Returns: HolidayResult with holidays, total, and query properties.

getHolidaysByYear(year)

Get all holidays for a specific year.

const holidays2026 = getHolidaysByYear(2026);

getHolidaysByMonth(year, month)

Get holidays for a specific month.

const janHolidays = getHolidaysByMonth(2026, 1);

getHolidaysByState(state, year?)

Get holidays for a specific state.

const maharashtraHolidays = getHolidaysByState('Maharashtra', 2026);
const allMaharashtraHolidays = getHolidaysByState('Maharashtra'); // all years

getHolidaysByDateRange(startDate, endDate, options?)

Get holidays within a date range.

const holidays = getHolidaysByDateRange(
  '2026-01-01',
  '2026-03-31',
  { state: 'Karnataka' }
);

isHoliday(date, state?)

Check if a specific date is a banking holiday.

// Check if a date is a holiday
isHoliday('2026-01-26'); // true (Republic Day)
isHoliday('2026-01-27'); // false

// Check for a specific state
isHoliday('2026-05-01', 'Maharashtra'); // true (Maharashtra Day)

// Accepts Date objects
isHoliday(new Date('2026-01-26')); // true

getHolidayByDate(date, state?)

Get holiday information for a specific date. Returns null if not a holiday.

const holiday = getHolidayByDate('2026-01-26');
// Returns: { date: '2026-01-26', name: 'Republic Day', type: 'National' }

const notHoliday = getHolidayByDate('2026-01-27');
// Returns: null

getNextHoliday(fromDate?, state?)

Get the next banking holiday from a given date (defaults to today).

const nextHoliday = getNextHoliday();
const nextStateHoliday = getNextHoliday(undefined, 'Maharashtra');
const nextFromDate = getNextHoliday('2026-06-01');

getUpcomingHolidays(days?, state?)

Get upcoming holidays within a specified number of days (default: 30).

// Get holidays in next 30 days
const upcoming = getUpcomingHolidays();

// Get holidays in next 60 days for Maharashtra
const stateUpcoming = getUpcomingHolidays(60, 'Maharashtra');

getHolidayCount(year, state?)

Get the count of holidays for a year.

const count = getHolidayCount(2026);
const stateCount = getHolidayCount(2026, 'Maharashtra');

Types

Holiday

interface Holiday {
  date: string;           // ISO date string (YYYY-MM-DD)
  name: string;           // Holiday name
  type: HolidayType;      // 'National' | 'State' | 'Regional'
  states?: IndianState[]; // Applicable states (undefined = all states)
  description?: string;   // Optional description
}

HolidayType

type HolidayType = 'National' | 'State' | 'Regional';

• National — Applies to all states (Republic Day, Independence Day, Gandhi Jayanti)
• State — Specific to certain states (Maharashtra Day, Karnataka Rajyotsava)
• Regional — Regional holidays that may vary by state (Diwali, Holi, Eid)

IndianState

All 28 states and 8 union territories are supported:

States: Andhra Pradesh, Arunachal Pradesh, Assam, Bihar, Chhattisgarh, Goa, Gujarat, Haryana, Himachal Pradesh, Jharkhand, Karnataka, Kerala, Madhya Pradesh, Maharashtra, Manipur, Meghalaya, Mizoram, Nagaland, Odisha, Punjab, Rajasthan, Sikkim, Tamil Nadu, Telangana, Tripura, Uttar Pradesh, Uttarakhand, West Bengal

Union Territories: Andaman and Nicobar Islands, Chandigarh, Dadra and Nagar Haveli and Daman and Diu, Delhi, Jammu and Kashmir, Ladakh, Lakshadweep, Puducherry

HolidayQueryOptions

interface HolidayQueryOptions {
  year?: number;
  month?: number;        // 1-12
  state?: IndianState;
  startDate?: string;    // YYYY-MM-DD
  endDate?: string;      // YYYY-MM-DD
}

HolidayResult

interface HolidayResult {
  holidays: Holiday[];
  total: number;
  query: HolidayQueryOptions;
}

Examples

Check if payment can be processed

import { isHoliday } from 'indian-banking-holiday';

function canProcessPayment(date: Date): boolean {
  const isWeekend = date.getDay() === 0 || date.getDay() === 6;
  return !isWeekend && !isHoliday(date);
}

const paymentDate = new Date('2026-01-26');
if (canProcessPayment(paymentDate)) {
  console.log('Payment can be processed');
} else {
  console.log('Payment date is a weekend or banking holiday');
}

Find next working day

import { isHoliday } from 'indian-banking-holiday';

function getNextWorkingDay(date: Date): Date {
  const nextDay = new Date(date);
  nextDay.setDate(nextDay.getDate() + 1);
  
  // Skip weekends and holidays
  while (nextDay.getDay() === 0 || nextDay.getDay() === 6 || isHoliday(nextDay)) {
    nextDay.setDate(nextDay.getDate() + 1);
  }
  
  return nextDay;
}

Get upcoming holidays for planning

import { getUpcomingHolidays } from 'indian-banking-holiday';

const upcoming = getUpcomingHolidays(90, 'Maharashtra');

console.log('Upcoming holidays in Maharashtra:');
upcoming.forEach(holiday => {
  console.log(`${holiday.date}: ${holiday.name}`);
});

List all state holidays

import { getHolidaysByState } from 'indian-banking-holiday';

const karnatakaHolidays = getHolidaysByState('Karnataka', 2026);
console.log(`Karnataka has ${karnatakaHolidays.length} holidays in 2026`);

karnatakaHolidays.forEach(h => {
  console.log(`${h.date} - ${h.name} (${h.type})`);
});

Data Coverage

The library includes holiday data for:

• 2025 — Complete (validated against RBI website)
• 2026 — Complete (validated against HDFC Bank holiday list)
• 2027 — Complete

Holiday data is sourced from official bank holiday lists and RBI notifications. All holidays are validated against official sources to ensure accuracy.

Data Validation

• 2026 holidays are validated against HDFC Bank's official holiday list
• 2025 holidays are validated against RBI's official holiday matrix
• The library only includes holidays that are present in official bank holiday lists
• State-specific holidays are accurately mapped to their respective states

Development

Setup

npm install

CI/CD

This project uses GitHub Actions for continuous integration:

• CI Workflow: Automatically runs on every push to main and on pull requests

  • Runs tests, linting, type checking, and builds
  • Tests on Node.js 18.x and 20.x
  • See .github/WORKFLOWS.md for details

• Release Workflow: Automatically bumps version and publishes to npm

  • Can be triggered manually via GitHub Actions UI
  • Or by pushing a version tag (e.g., v1.0.2)
  • Uses OpenID Connect (OIDC) for secure authentication with npm
  • See .github/WORKFLOWS.md for setup instructions

Available Scripts

# Build the library
npm run build

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:coverage

# Lint code
npm run lint

# Auto-fix linting issues
npm run lint:fix

# Format code with Prettier
npm run format

# Check code formatting
npm run format:check

# Type check without building
npm run type-check

# Check for extra holidays not in HDFC website
npm run check:extra

Code Quality

This project uses:

• ESLint for code linting
• Prettier for code formatting
• TypeScript for type safety
• Jest for testing

All code is automatically formatted and linted. Please ensure your code passes npm run lint and npm run format:check before submitting PRs.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Adding or Updating Holiday Data

1. Update src/holidays.ts with the new holiday data
2. Run npm run build to build the library
3. Run npm test to validate against test data
4. Run npm run lint and npm run format to ensure code quality
5. Ensure all tests pass before submitting

Validation Requirements

• All holidays must be validated against official sources (HDFC Bank, RBI, etc.)
• State-specific holidays must be accurately mapped
• Dates must be in ISO format (YYYY-MM-DD)
• Holiday names should match official sources

Testing

The test suite includes:

• Validation against HDFC Bank holiday list (2026)
• Validation against RBI holiday list (2025)
• Tests to ensure no extra holidays beyond official sources
• State-wise holiday validation
• Date format and data quality checks

Disclaimer

IMPORTANT: This library is provided for informational purposes only and is not an official source of banking holiday information.

• Not Official: This library is not affiliated with, endorsed by, or officially connected to the Reserve Bank of India (RBI), any government agency, or any banking institution.
• Verify for Critical Use: For critical applications involving financial transactions, payment processing, or legal compliance, always verify holiday dates with official RBI notifications or your bank's official holiday calendar.
• No Warranty: While we strive for accuracy and validate data against official sources, we make no guarantees about the completeness, accuracy, or timeliness of the holiday data.
• Use at Your Own Risk: The authors and contributors are not liable for any financial losses, missed transactions, or other damages resulting from the use or misuse of this library.
• Data Updates: Banking holidays can be announced or changed by RBI at any time. This library may not reflect the most recent changes immediately. Always check official sources for the most up-to-date information.
• No Legal Advice: This library does not constitute legal, financial, or professional advice. Consult with appropriate professionals for legal or financial matters.

For official banking holiday information, please refer to:

• RBI Official Holiday Matrix
• Your bank's official website or customer service
• Official government notifications

License

Apache-2.0

Links

• GitHub Repository
• Report Issues
• npm Package