/ 01
Introduction
公式データを正とし、利用者が誤判定リスクを背負わないことを最優先にした設計。
What is @liha-labs/holiday?
@liha-labs/holiday は、日本の祝日データを扱うための TypeScript ライブラリです。 春分・秋分などの計算ロジックは持たず、公式データの結果だけを返します。
Design goals
- official-first祝日判定は公式データ準拠
- strict input日付文字列は YYYY-MM-DD / YYYY-MM を厳密検証
- runtime-lightランタイム依存ゼロ
- portablefetch差し替えで Node / Browser 対応
Non-goals
- 祝日計算独自アルゴリズムで祝日を算出しない
- 曖昧な日付変換YYYY-MM-DD 以外の文字列は受け付けない
- データの自動補完存在しない年を推測して生成しない
Features
運用をシンプルに保ちながら、実利用に必要な機能を提供します。
holidayName祝日名（string | null）を返却。
getHolidaydate/name/weekday を返却。
listYear/listMonth/listRange用途別の一覧取得。
createClientremoteBaseUrl / fetch / cache を差し替え。
default/full entry通常版とフル同梱版を選択可能。
info()生成時刻・対応範囲・データソースを確認。
Compatibility
Runtime
Browser (Modern)Node.jsESM
Input
DateYYYY-MM-DDYYYY-MM (listMonth)
/ 02
Quick Start
最小限の導入で、公式データ準拠の祝日判定をすぐ利用できます。
STEP 01
Install
標準として pnpm を推奨します。
$ pnpm add @liha-labs/holidaySTEP 02
Basic Lookup
祝日名と詳細（曜日付き）を取得します。
basic.ts
import { holidayName, getHoliday } from '@liha-labs/holiday'
const name = await holidayName('2026-01-01')
const detail = await getHoliday('2026-01-01')STEP 03
List APIs
月・範囲で一覧取得できます。
list.ts
import { listMonth, listRange } from '@liha-labs/holiday'
const january = await listMonth('2026-01')
const spring = await listRange('2026-03-01', '2026-05-31')STEP 04
Strict Input
文字列入力は厳密に検証されます。
strict.ts
import { holidayName } from '@liha-labs/holiday'
await holidayName('2026-01-01') // OK
await holidayName('2026-1-1') // Error: YYYY-MM-DD のみ許可
await holidayName('2026-02-30') // Error: 暦上不正/ 03
Usage
実運用で使う主要パターンを、実装仕様に沿って整理。
Top-level Functions
最小コードで使うならトップレベル関数が最短です。
top-level.ts
import { holidayName, isHoliday, getHoliday } from '@liha-labs/holiday'
await holidayName('2026-01-01')
await isHoliday('2026-01-02')
await getHoliday('2026-01-01')createClient(options)
remote base URL / fetch 実装 / キャッシュ戦略を差し替える場合はクライアントを生成します。
client.ts
import { createClient } from '@liha-labs/holiday'
const client = createClient({
remoteBaseUrl: 'https://raw.githubusercontent.com/liha-labs/holiday/main',
fetch: globalThis.fetch,
cache: 'memory',
})
await client.listYear(2023)Date Input Rules
input.ts
import { listMonth, holidayName } from '@liha-labs/holiday'
await holidayName(new Date())
await holidayName('2026-01-01')
await listMonth('2026-01')
// 以下は例外
await holidayName('2026/01/01')
await holidayName('2026-1-1')Range and All
range.ts
import { listRange, listAll, info } from '@liha-labs/holiday'
const selected = await listRange('2026-01-01', '2026-12-31')
const all = await listAll()
const meta = info()
console.log(meta.fullRange)Full Entry
@liha-labs/holiday/full は全期間同梱で、remote 取得を使いません。
full.ts
import { listYear, createClient } from '@liha-labs/holiday/full'
await listYear(1960)
const fullClient = createClient()
await fullClient.listAll()/ 04
API Reference
実装済みAPIと返り値仕様。
createClient(options?)
HolidayClient インスタンスを生成します。
createClient(options?: ClientOptions): HolidayClientTop-level Functions
holidayName(input): Promise<string | null>isHoliday(input): Promise<boolean>getHoliday(input): Promise<HolidayDetail | null>listYear(year): Promise<HolidayDetail[]>listMonth(ym): Promise<HolidayDetail[]>listRange(start, end): Promise<HolidayDetail[]>listAll(): Promise<HolidayDetail[]>info(): InfoCore Types
Holiday
{ date: "YYYY-MM-DD"; name: string }HolidayDetail
Holiday & { weekday: 0 | 1 | 2 | 3 | 4 | 5 | 6 }Info
generatedAt, bundledYears, fullRange, source, remote を返しま す。
ClientOptions
remoteBaseUrl
string年別JSON取得先のベースURL。
fetch
typeof globalThis.fetch取得時に使う fetch 実装。
cache
"memory" | "none"memory は年ごとに Promise をメモ化し、同時多重fetchを抑止します。
Behavior Notes
文字列入力:
YYYY-MM-DD（または listMonth の YYYY-MM）以外は例外。Date 入力: ローカル日付の
getFullYear/getMonth/getDate で正規化。weekday:
new Date(y, m - 1, d).getDay() でランタイム算出。listRange: 終端日を含む範囲取得です。
/ 05
Examples
実装済みAPIのみを使ったサンプル。
Basic Lookup
holidayNamegetHoliday
祝日名と詳細（weekday付き）を取得します。
basic.ts
import { holidayName, getHoliday } from '@liha-labs/holiday'
const name = await holidayName('2026-01-01')
const detail = await getHoliday('2026-01-01')Date Input
Datelocal date
Date オブジェクトはローカル日付として解釈されます。
date-input.ts
import { isHoliday } from '@liha-labs/holiday'
const today = new Date()
const result = await isHoliday(today)Custom Client
createClientcachefetch
取得先URLやキャッシュ戦略を差し替える例です。
client.ts
import { createClient } from '@liha-labs/holiday'
const client = createClient({
remoteBaseUrl: 'https://raw.githubusercontent.com/liha-labs/holiday/main',
cache: 'memory',
fetch: globalThis.fetch,
})
const holidays = await client.listYear(2023)Full Entry
/fulllocal only
@liha-labs/holiday/full は remote 取得を使わず、同じAPIで返します。
full.ts
import { listAll, listYear } from '@liha-labs/holiday/full'
await listYear(1968)
await listAll()