korean-holidays

대한민국 공휴일 라이브러리 - 대체공휴일 지원

Korean holidays library with substitute holidays (대체공휴일) support.

Features

• 모든 대한민국 공휴일 지원 (음력 공휴일 포함)
• 대체공휴일 자동 계산
  • 2014년~: 설날/추석/어린이날
  • 2021년~: 3·1절, 광복절, 개천절, 한글날
  • 2023년~: 석가탄신일, 성탄절
• 제헌절 2026년부터 공휴일 복원 지원
• 영업일 계산 유틸리티

Installation

npm install korean-holidays

Usage

공휴일 목록 조회

import { getHolidays } from 'korean-holidays'

const holidays = getHolidays(2026)

holidays.forEach(holiday => {
  console.log(`${holiday.date.toISOString().split('T')[0]} - ${holiday.nameKo}`)
})

특정 날짜가 공휴일인지 확인

import { isHoliday } from 'korean-holidays'

const holiday = isHoliday(new Date(2026, 0, 1))
if (holiday) {
  console.log(`${holiday.nameKo}입니다!`) // 신정입니다!
}

영업일 확인

import { isBusinessDay } from 'korean-holidays'

const date = new Date(2026, 0, 1) // 신정
console.log(isBusinessDay(date)) // false (공휴일)

const date2 = new Date(2026, 0, 2) // 금요일
console.log(isBusinessDay(date2)) // true

영업일 계산

import { addBusinessDays } from 'korean-holidays'

// 2026년 1월 2일(금) + 2영업일
const result = addBusinessDays(new Date(2026, 0, 2), 2)
// 주말을 건너뛰어 1월 6일(화)

영업일 수 계산

import { countBusinessDays } from 'korean-holidays'

const start = new Date(2026, 0, 1)
const end = new Date(2026, 0, 10)
const businessDays = countBusinessDays(start, end)

API

getHolidays(year: number, options?: HolidayOptions): Holiday[]

주어진 연도의 모든 공휴일을 반환합니다.

Options:

• includeSubstitute: 대체공휴일 포함 여부 (기본값: true)

isHoliday(date: Date, options?: HolidayOptions): Holiday | null

특정 날짜가 공휴일인지 확인합니다.

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

특정 날짜가 영업일(평일이면서 공휴일이 아닌 날)인지 확인합니다.

addBusinessDays(startDate: Date, days: number, options?: HolidayOptions): Date

시작일로부터 n 영업일 후의 날짜를 반환합니다.

countBusinessDays(startDate: Date, endDate: Date, options?: HolidayOptions): number

두 날짜 사이의 영업일 수를 반환합니다.

Holiday Interface

interface Holiday {
  date: Date
  name: string      // 영문 이름
  nameKo: string    // 한글 이름
  isSubstitute: boolean  // 대체공휴일 여부
  isLunar: boolean  // 음력 공휴일 여부
}

지원하는 공휴일

고정 공휴일

| 날짜 | 공휴일 | |------|--------| | 1월 1일 | 신정 | | 3월 1일 | 3·1절 | | 5월 5일 | 어린이날 | | 6월 6일 | 현충일 | | 7월 17일 | 제헌절 (2026년~) | | 8월 15일 | 광복절 | | 10월 3일 | 개천절 | | 10월 9일 | 한글날 | | 12월 25일 | 성탄절 |

음력 공휴일

| 음력 날짜 | 공휴일 | |-----------|--------| | 1월 1일 ± 1일 | 설날 연휴 (3일) | | 4월 8일 | 석가탄신일 | | 8월 15일 ± 1일 | 추석 연휴 (3일) |

License

MIT