nz-holidays/README.md

Lightweight New Zealand public holidays library

# nz-holidays

A lightweight, zero-dependency library for New Zealand public holidays. 

## Installation

```bash
npm install nz-holidays
```

## Quick Start

```javascript
import { isHoliday, getHolidays, getNextHoliday } from 'nz-holidays';

// Check if today is a holiday
const today = new Date();
console.log(isHoliday(today)); // true/false

// Get all holidays for 2024
const holidays2024 = getHolidays(2024);
console.log(holidays2024);

// Get the next upcoming holiday
const nextHoliday = getNextHoliday();
console.log(`Next holiday: ${nextHoliday.name} on ${nextHoliday.date}`);
```

## API Reference

### `getHolidays(year, options?)`

Returns all holidays for a given year.

```javascript
const holidays = getHolidays(2024, {
  includeObserved: true,  // Include observed dates for weekend holidays
  region: 'auckland'      // Include regional holidays
});
```

**Options:**
- `includeObserved`: Include observed dates when holidays fall on weekends (default: `true`)
- `region`: Include regional anniversary days:
  - `'auckland'` - Auckland Anniversary Day
  - `'wellington'` - Wellington Anniversary Day  
  - `'canterbury'` - Canterbury Anniversary Day
  - `'otago'` - Otago Anniversary Day
  - `'southland'` - Southland Anniversary Day
  - `'westland'` - Westland Anniversary Day
  - `'nelson'` - Nelson Anniversary Day
  - `'marlborough'` - Marlborough Anniversary Day
  - `'taranaki'` - Taranaki Anniversary Day
  - `'hawkes-bay'` - Hawke's Bay Anniversary Day
  - `'south-canterbury'` - South Canterbury Anniversary Day
  - `'chatham-islands'` - Chatham Islands Anniversary Day

### `isHoliday(date: Date, options?: HolidayOptions): boolean`

Check if a specific date is a holiday.

```javascript
const christmas = new Date(2024, 11, 25);
console.log(isHoliday(christmas)); // true

// Include regional holidays
console.log(isHoliday(date, { region: 'auckland' }));
```

### `getNextHoliday(from?: Date, options?: HolidayOptions): Holiday | null`

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

```javascript
const next = getNextHoliday();
const nextFromDate = getNextHoliday(new Date(2024, 6, 1));
```

### `isBusinessDay(date: Date, options?: HolidayOptions): boolean`

Check if a date is a business day (not weekend or holiday).

```javascript
const monday = new Date(2024, 5, 17);
console.log(isBusinessDay(monday)); // true (if not a holiday)

```
### `countBusinessDays(start: Date, end, options?): number`

Count the number of business days between two dates exclusive
```javascript
const start = new Date()
const end = new Date(2025, 11, 25);
console.log(countBusinessDays(start, end)); // how long til xmas?
```

## Supported Holidays

### National Holidays
- New Year's Day (1 January)
- Day after New Year's Day (2 January)
- Waitangi Day (6 February)
- Good Friday (Easter-based)
- Easter Monday (Easter-based)
- ANZAC Day (25 April)
- Matariki (Mid-winter, became holiday in 2022)
- King's Birthday (First Monday in June) *
- Labour Day (Fourth Monday in October)
- Christmas Day (25 December)
- Boxing Day (26 December)

*\*Called "Queen's Birthday" before 2023*

### Regional Holidays (Anniversary Days)
- **Auckland** - Monday closest to 29 January
- **Wellington** - Monday closest to 22 January  
- **Canterbury** - Second Friday after first Tuesday in November
- **Otago** - Monday closest to 23 March
- **Southland** - Easter Tuesday (day after Easter Monday)
- **Westland** - Monday closest to 1 December
- **Nelson** - Monday closest to 1 February
- **Marlborough** - First Monday after Labour Day
- **Taranaki** - Second Monday in March
- **Hawke's Bay** - Friday before Labour Day
- **South Canterbury** - Fourth Monday in September
- **Chatham Islands** - Monday closest to 30 November

*Note: Each region observes only their own anniversary day plus the national holidays.*

## Features

### Mondayisation
When holidays fall on weekends, they're automatically "mondayised" (observed on Monday) according to NZ law.

**Special Case - Consecutive Holidays:**
When Christmas Day and Boxing Day (or New Year's Day and Day After New Year's Day) both fall on weekends:
- If the first holiday moves to Monday, the second holiday moves to Tuesday
- This prevents both holidays from being observed on the same day

Example: Christmas 2022 (Sunday) → observed Monday, Boxing Day 2022 (Monday) → observed Tuesday

### TypeScript Support
Full TypeScript definitions included:

```typescript
interface Holiday {
  name: string;
  date: Date;
  type: 'national' | 'regional';
  observed?: Date;
}

interface HolidayOptions {
  includeObserved?: boolean;
  region?: 'auckland' 
  | 'wellington' 
  | 'canterbury' 
  | 'otago' 
  | 'southland' 
  | 'westland' 
  | 'nelson' 
  | 'marlborough' 
  | 'taranaki' 
  | 'hawkes-bay' 
  | 'south-canterbury' 
  | 'chatham-islands';
}

```