TW Holiday

提供台灣政府行政機關辦公日曆表的 JavaScript/TypeScript 串接介面，輕鬆查詢國定假日與休假日資訊。

📦 安裝

npm install tw-holiday --save

或使用 yarn:

yarn add tw-holiday

📊 資料來源

新北市政府資料開放平臺 - 政府行政機關辦公日曆表

🚀 快速開始

JavaScript (CommonJS)

const { TaiwanHoliday } = require('tw-holiday');

// 查詢特定日期是否為假日
TaiwanHoliday.isHoliday('2024-01-01').then(isHoliday => {
  console.log(isHoliday); // true (元旦)
});

// 取得所有假日事件
TaiwanHoliday.fetchEvents().then(events => {
  console.log(events);
});

TypeScript (ESM)

import { TaiwanHoliday, HolidayEvent } from 'tw-holiday';

// 查詢今天是否為假日
const isToday = await TaiwanHoliday.isHoliday();
console.log('今天是假日嗎？', isToday);

// 取得所有假日資料
const events: HolidayEvent[] = await TaiwanHoliday.fetchEvents();

📘 API 文件

TaiwanHoliday.fetchEvents(forceReload?: boolean): Promise<HolidayEvent[]>

取得所有假日事件資料。

參數：

• forceReload (可選): 是否強制重新載入資料，預設為 false

回傳值： Promise<HolidayEvent[]> - 假日事件陣列

範例：

// 取得所有假日（使用快取）
const events = await TaiwanHoliday.fetchEvents();

// 強制重新載入最新資料
const latestEvents = await TaiwanHoliday.fetchEvents(true);

TaiwanHoliday.isHoliday(date?: string): Promise<boolean>

判斷指定日期是否為休假日。

參數：

• date (可選): 日期字串，格式為 YYYY-MM-DD，預設為今天

回傳值： Promise<boolean> - 是否為休假日

範例：

// 查詢今天是否為假日
const isTodayHoliday = await TaiwanHoliday.isHoliday();

// 查詢特定日期
const is2024NewYear = await TaiwanHoliday.isHoliday('2024-01-01'); // true
const isWorkday = await TaiwanHoliday.isHoliday('2024-01-02'); // false

TaiwanHoliday.clearCache(): void

手動清除快取資料與計時器。

範例：

TaiwanHoliday.clearCache();

⚙️ 設定選項

啟用快取功能

啟用快取可以減少 API 請求次數，提升效能。

// 啟用快取（預設：false）
TaiwanHoliday.enabledCache = true;

設定快取時間

// 設定快取時間為 1 小時（預設：24 小時）
// 單位：毫秒
TaiwanHoliday.cacheTime = 60 * 60 * 1000;

📝 資料型別

HolidayEvent

interface HolidayEvent {
  /** 日期 (格式: YYYY-MM-DD) */
  date: string;
  
  /** 節日或紀念日名稱 */
  name: string;
  
  /** 是否為休假日 */
  isHoliday: boolean;
  
  /** 放假類別 */
  holidayCategory: string;
  
  /** 說明 */
  description: string;
  
  /** 
   * ISO 星期編號
   * - 1: 星期一
   * - 2: 星期二
   * - 3: 星期三
   * - 4: 星期四
   * - 5: 星期五
   * - 6: 星期六
   * - 7: 星期日
   */
  week: number;
  
  /** 年份 */
  year: string;
}

💡 使用範例

範例 1：查詢連續日期的假日狀態

import { TaiwanHoliday } from 'tw-holiday';
import dayjs from 'dayjs';

let date = dayjs();

for (let i = 0; i < 30; i++) {
  const dateStr = date.format('YYYY-MM-DD');
  const isHoliday = await TaiwanHoliday.isHoliday(dateStr);
  console.log(`${dateStr}: ${isHoliday ? '假日 🎉' : '工作日 💼'}`);
  date = date.add(1, 'day');
}

範例 2：篩選特定年份的假日

import { TaiwanHoliday } from 'tw-holiday';

TaiwanHoliday.enabledCache = true;

const events = await TaiwanHoliday.fetchEvents();

// 篩選 2024 年的假日
const holidays2024 = events.filter(event => 
  event.year === '2024' && event.isHoliday
);

console.log(`2024 年共有 ${holidays2024.length} 天假日`);
holidays2024.forEach(holiday => {
  console.log(`${holiday.date} - ${holiday.name}`);
});

範例 3：匯出假日資料

import { TaiwanHoliday } from 'tw-holiday';
import { writeFileSync } from 'fs';

TaiwanHoliday.enabledCache = true;

const events = await TaiwanHoliday.fetchEvents();
writeFileSync('./events.json', JSON.stringify(events, null, 2));
console.log('假日資料已匯出到 events.json');

🔧 進階用法

快取策略建議

import { TaiwanHoliday } from 'tw-holiday';

// 長時間運行的應用（如後端服務）
TaiwanHoliday.enabledCache = true;
TaiwanHoliday.cacheTime = 24 * 60 * 60 * 1000; // 24 小時

// 短期查詢（如 CLI 工具）
TaiwanHoliday.enabledCache = false; // 每次都取得最新資料

// 定期更新快取
setInterval(() => {
  TaiwanHoliday.fetchEvents(true); // 強制重新載入
}, 24 * 60 * 60 * 1000); // 每 24 小時更新

📄 授權

MIT License - 詳見 LICENSE 檔案

🔗 連結

• GitHub Repository
• npm Package
• 資料來源

👤 作者

EJay Cheng

🤝 貢獻

歡迎提交 Issues 和 Pull Requests！