holidays-jp-gen/README.md

A CLI tool to generate lightweight TypeScript holiday data modules for Japan based on official government CSV data.

# holidays-jp-gen

`holidays-jp-gen` は、日本の祝日データ（内閣府提供のCSV）を元に、  
指定年以降の祝日を抽出し、軽量なTypeScriptモジュールファイルを自動生成するCLIツールです。

## 特長

- 内閣府の公式CSVデータを自動ダウンロード・解析
- 指定年から最新までの祝日だけを含む軽量モジュールを生成
- 簡易な日付判定ロジックを含む

## 使い方

```bash
npx holidays-jp-gen --year 2020
```

上記コマンドで `holidays-jp-from-2020.ts` ファイルが生成されます。

### オプション

- `--year <year>` : 祝日データの開始年を指定（デフォルト: 1955 ※データ上一番古い年）
- `--output <path>` : 出力ファイルパス（デフォルト：`holidays-jp-from-<year>.ts`）

## 生成されるファイル例

```ts
// holidays-jp-from-2020.ts
export const holidays: { [key: string]: string } = {
  "2020-01-01": "元日",
  "2020-01-13": "成人の日",
  // ...
};
export const isHoliday = (date: Date | string): boolean => { ... }
export const getHolidayName = (date: Date | string): string | null => { ... }
export const isBusinessDay = (date: Date | string): boolean => { ... }
export const offsetInBusinessDays = (
  date: Date | string,
  days: number,
  adjustment?: "next" | "previous" | "none"
): string | null => { ... }
```

## 生成されたモジュールの利用方法

### `isHoliday(date: Date | string): boolean`

指定された日付が日本の祝日であるかどうかを判定します。

- `date`: 判定する日付。文字列の場合は'YYYY-MM-DD'形式。

**戻り値**: 祝日であれば `true`、そうでなければ `false`。

**例**:

```ts
import { isHoliday } from './holidays-jp-from-2020';

console.log(isHoliday('2025-01-01')); // true (元日)
console.log(isHoliday(new Date('2025-01-02'))); // false
```

### `getHolidayName(date: Date | string): string | null`

指定された日付の祝日名を取得します。

- `date`: 祝日名を取得する日付。文字列の場合は'YYYY-MM-DD'形式。

**戻り値**: 祝日名。祝日でない場合は `null`。

**例**:

```ts
import { getHolidayName } from './holidays-jp-from-2020';

console.log(getHolidayName('2025-01-01')); // "元日"
console.log(getHolidayName(new Date('2025-05-05'))); // "こどもの日"
console.log(getHolidayName('2025-01-02')); // null
```

### `isBusinessDay(date: Date | string): boolean`

指定された日付が営業日（土日祝以外）であるかどうかを判定します。

- `date`: 判定する日付。文字列の場合は'YYYY-MM-DD'形式。

**戻り値**: 営業日であれば `true`、そうでなければ `false`。

**例**:

```ts
import { isBusinessDay } from './holidays-jp-from-2020';

console.log(isBusinessDay('2025-01-02')); // true (平日)
console.log(isBusinessDay('2025-01-04')); // false (土曜日)
console.log(isBusinessDay('2025-01-01')); // false (祝日)
```

### `offsetInBusinessDays(date: Date | string, days: number, adjustment?: "next" | "previous" | "none"): string | null`

指定された日付からN営業日後（前）の日付を計算します。

- `date`: 基準となる日付。文字列の場合は'YYYY-MM-DD'形式。
- `days`: 加算する営業日数（正なら未来方向、負なら過去方向）。
- `adjustment`: 基準日の調整方法。省略時は days >= 0 なら "next"、days < 0 なら "previous"。
  - `"next"`: 基準日が営業日でない場合、次の営業日に調整してから計算
  - `"previous"`: 基準日が営業日でない場合、前の営業日に調整してから計算
  - `"none"`: 基準日をそのまま使用（営業日でなくても調整しない）

**戻り値**: 計算結果の日付（'YYYY-MM-DD'形式）。無効な日付の場合は `null`。

**例**:

```ts
import { offsetInBusinessDays } from './holidays-jp-from-2020';

// 2025-01-02(木)から3営業日後 → 2025-01-07(火)
console.log(offsetInBusinessDays('2025-01-02', 3)); // "2025-01-07"

// 2025-01-04(土)から1営業日後 → 次の営業日(月)から1営業日後
console.log(offsetInBusinessDays('2025-01-04', 1)); // "2025-01-07"

// 基準日を調整しない場合
console.log(offsetInBusinessDays('2025-01-04', 1, 'none')); // "2025-01-06"
```

## 注意事項

このツールは内閣府提供のオープンデータを利用していますが、  
ツール自体は非公式の個人製作ソフトウェアです。

## ライセンス

MIT License

## 開発者

momo-lab (<momotaro.n@gmail.com>)