Banking Holiday Detection

A TypeScript package for detecting banking holidays and calculating business days in USA, Puerto Rico (PR), and Dominican Republic (RD). Perfect for financial applications, trade settlements, and payment processing.

Installation

npm install @kiwicredito/banking-holidays

Usage

import { 
  getDateStatus, 
  isHoliday, 
  isWorkingDay, 
  getHolidays,
  getNextWorkingDay,
  getPreviousWorkingDay,
  getNextWorkingNDays,
  getPreviousWorkingNDays
} from '@kiwicredito/banking-holidays';

// Check if a date is a holiday and get its status
const status = getDateStatus('2024-01-01', 'USA');
console.log(status);
// {
//   isHoliday: true,
//   holiday: { name: "New Year's Day", date: "2024-01-01", ... },
//   isWorkingDay: false,
//   isWeekend: false
// }

// Check if a date is a working day
const isWorking = isWorkingDay('2024-01-02', 'USA');
console.log(isWorking); // true

// Get next working day (skip holidays and weekends)
const nextWorkingDay = getNextWorkingDay('2025-07-04', 'USA'); // Independence Day
console.log(nextWorkingDay); // 2025-07-07 (Monday)

// Banking: T+5 settlement calculation
const tradeDate = '2025-07-03'; // Thursday
const settlementDate = getNextWorkingNDays(tradeDate, 5, 'USA');
console.log(settlementDate); // 2025-07-11 (Friday, skips July 4th + weekend)

// Calculate payment due date (Net 30 business days)
const invoiceDate = '2025-07-01';
const dueDate = getNextWorkingNDays(invoiceDate, 30, 'USA');
console.log(dueDate); // 30 business days after invoice

// Get all holidays for a country
const holidays = getHolidays({ country: 'USA' });
console.log(holidays.map(h => h.name));
// ["New Year's Day", "Martin Luther King Jr. Day", ...]

Features

✅ Holiday Detection

• Check if a specific date is a banking holiday
• Check if a date is a working day (not weekend and not holiday)
• Check if a date is a weekend
• Get all holidays for a specific country
• Filter holidays by date range

🗓️ Business Day Calculations

• Get next/previous working day - Skip holidays and weekends
• Add/subtract N business days - Perfect for T+N settlements
• Trade settlement calculations - T+1, T+2, T+5, etc.
• Payment due date calculations - Net 30, Net 60 business days
• Cross-year boundary handling - Works across different years

🌎 Multi-Country Support

• USA - Federal banking holidays
• Puerto Rico (PR) - Including Three Kings Day, etc.
• Dominican Republic (RD) - Local banking holidays
• Proper timezone handling for each country

🔧 Developer Friendly

• TypeScript support - Full type definitions included
• Multiple input formats - ISO strings, Date objects, legacy timestamps
• Comprehensive testing - 72+ tests covering edge cases
• Zero dependencies - Lightweight and fast

API Reference

Holiday Detection Functions

getDateStatus(date: string | Date, country: Country): DateStatus

Returns complete status of a date including holiday and working day information.

const status = getDateStatus('2025-07-04', 'USA');
// { isHoliday: true, holiday: {...}, isWorkingDay: false, isWeekend: false }

isHoliday(date: string | Date, country: Country): HolidayResponse

Returns whether a date is a holiday and the holiday details if it is.

isWorkingDay(date: string | Date, country: Country): boolean

Returns whether a date is a working day (not weekend and not holiday).

getHolidays(options?: HolidayOptions): Holiday[]

Returns holidays based on the provided options.

Business Day Calculation Functions

getNextWorkingDay(date: string | Date, country: Country): Date

Returns the next working day, skipping weekends and holidays.

const next = getNextWorkingDay('2025-07-04', 'USA'); // 2025-07-07 (Monday)

getPreviousWorkingDay(date: string | Date, country: Country): Date

Returns the previous working day, skipping weekends and holidays.

getNextWorkingNDays(date: string | Date, days: number, country: Country): Date

NEW! Adds N business days to a date. Perfect for settlement calculations.

// T+5 settlement
const settlement = getNextWorkingNDays('2025-07-03', 5, 'USA'); // 2025-07-11

// Payment terms (Net 30 business days)
const dueDate = getNextWorkingNDays(invoiceDate, 30, 'USA');

getPreviousWorkingNDays(date: string | Date, days: number, country: Country): Date

NEW! Subtracts N business days from a date.

// Find original trade date from settlement
const tradeDate = getPreviousWorkingNDays('2025-07-11', 5, 'USA'); // 2025-07-03

Types

• Country: 'USA' | 'PR' | 'RD'
• DateStatus: Object with holiday and working day information
• Holiday: Holiday object with name, date, and type information

Banking Use Cases

Trade Settlement (T+N)

const tradeDate = '2025-07-03';
const t1 = getNextWorkingNDays(tradeDate, 1, 'USA'); // T+1: 2025-07-07
const t2 = getNextWorkingNDays(tradeDate, 2, 'USA'); // T+2: 2025-07-08  
const t5 = getNextWorkingNDays(tradeDate, 5, 'USA'); // T+5: 2025-07-11

Payment Processing

// Invoice with Net 30 business days terms
const invoiceDate = '2025-07-01';
const dueDate = getNextWorkingNDays(invoiceDate, 30, 'USA');

// Late fee calculation (5 business days after due date)
const lateFeeDate = getNextWorkingNDays(dueDate, 5, 'USA');

Loan Calculations

// Loan approval: 3 business days processing
const applicationDate = '2025-07-04'; // Holiday
const approvalDate = getNextWorkingNDays(applicationDate, 3, 'USA');

// First payment due: 30 business days after funding
const fundingDate = '2025-07-15';
const firstPaymentDate = getNextWorkingNDays(fundingDate, 30, 'USA');

Input Formats Supported

// ISO date string
getNextWorkingNDays('2025-07-03', 5, 'USA');

// Date object
getNextWorkingNDays(new Date('2025-07-03'), 5, 'USA');

// Date constructor
getNextWorkingNDays(new Date(2025, 6, 3), 5, 'USA'); // Month is 0-indexed

// ISO datetime string
getNextWorkingNDays('2025-07-03T10:30:00.000Z', 5, 'USA');

// Legacy timestamp format (for .NET compatibility)
getNextWorkingNDays('/Date(1751515200000)/', 5, 'USA');

Development

1. Clone the repository
2. Install dependencies:

   npm install

3. Build the package:

   npm run build

4. Run tests:

   npm test

Scripts

• npm run build - Build the package
• npm test - Run tests
• npm run dev - Watch mode for development

License

ISC