🎊 Chinese Holidays

A lightweight library to determine Chinese public holidays and workdays

English | 中文

✨ Features

• 🎯 Accurate - Based on official Chinese government holiday announcements
• 🚀 Lightweight - Zero dependencies, minimal footprint
• 📅 Up-to-date - Regularly updated with latest holiday data
• 💪 TypeScript - Full TypeScript support with type definitions
• 🔄 Comprehensive - Handles both holidays and workdays (including adjusted workdays)

📦 Installation

pnpm install @kang8/chinese-holidays

Or using npm:

npm install @kang8/chinese-holidays

Or using yarn:

yarn add @kang8/chinese-holidays

🚀 Quick Start

import { holiday } from '@kang8/chinese-holidays'

const nationalDay = new Date('2022-10-01')

// Check if it's a holiday
holiday.isHoliday(nationalDay) // true

// Check if it's a workday
holiday.isWorkday(nationalDay) // false

// Get the holiday name
holiday.publicHolidayName(nationalDay) // '国庆节'

📖 API Reference

isHoliday(date: Date): boolean

Check if the given date is a holiday (including weekends and public holidays).

holiday.isHoliday(new Date('2022-10-01')) // true - National Day
holiday.isHoliday(new Date('2022-10-08')) // true - Weekend (Saturday)

isWorkday(date: Date): boolean

Check if the given date is a workday.

holiday.isWorkday(new Date('2022-10-07')) // false - National Day holiday period
holiday.isWorkday(new Date('2022-10-11')) // true - Regular workday

isPublicHoliday(date: Date): boolean

Check if the given date is an official public holiday (excluding regular weekends).

holiday.isPublicHoliday(new Date('2022-10-01')) // true - National Day
holiday.isPublicHoliday(new Date('2022-10-08')) // false - Regular weekend

isPublicWorkday(date: Date): boolean

Check if the given date is an adjusted workday (working on weekend due to holiday scheduling).

// October 8, 2022 (Saturday) was a working day to compensate for National Day holiday
holiday.isPublicWorkday(new Date('2022-10-08')) // true

publicHolidayName(date: Date): string | null

Get the name of the public holiday. Returns null if the date is not a public holiday.

holiday.publicHolidayName(new Date('2022-10-01')) // '国庆节'
holiday.publicHolidayName(new Date('2022-09-30')) // null

📅 Data Source

Holiday data is sourced from NateScarlet/holiday-cn, which aggregates official announcements from the State Council of China. The data is regularly updated to reflect the latest official holiday schedules.

🛠️ Development

This project uses pnpm as the package manager.

# Install dependencies
pnpm install

# Build the project
pnpm build

# Run tests
pnpm test

🤝 Contributing

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

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -am 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🔗 Related Projects

• chinese-workday - Another Chinese workday library
• chinese-holidays-node - Node.js Chinese holidays library
• chinese-holidays - Alternative Chinese holidays implementation