@kiwicredito/banking-holidays/README.md

A TypeScript package for detecting banking holidays in USA, Puerto Rico, and Dominican Republic

# 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

```bash
npm install @kiwicredito/banking-holidays
```

## Usage

```typescript
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.

```typescript
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.

```typescript
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.

```typescript
// 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.

```typescript
// 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)
```typescript
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
```typescript
// 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
```typescript
// 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

```typescript
// 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:
   ```bash
   npm install
   ```
3. Build the package:
   ```bash
   npm run build
   ```
4. Run tests:
   ```bash
   npm test
   ```

## Scripts

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

## License

ISC