bizdays-toolkit 0.17.1 → 0.18.0

package/CHANGELOG.md

@@ -4,6 +4,31 @@
 
 ## [Unreleased]
 
+## [0.18.0] - 2026-10-25
+
+### 移行
+
+動作が変わる既存の API はない。同梱の提供元が返す祝日に省略可能な項目 `key` が加わるので、`dayInfo` の結果や `holidaysInYear` の要素を `deepEqual` で比べているテストは期待値に足す（国民の休日・臨時の祝日には付かない）。祝日の規則に省略可能な `keys` が加わる。版ごとの作業は [docs/migration.md](./docs/migration.md) にまとめた。
+
+### Added
+
+- 祝日の識別子 `Holiday.key`（省略可能。`/^[a-z0-9][a-z0-9-]*$/`）と、祝日の規則の絞り込み `{ holiday: true, keys: [...] }`（`kinds`・`weekdays`・`months` との AND）を追加した。春分の日・復活祭に連動する日・太陰暦の祝日のように月日や曜日では書けない祝日を、名称に依存せず個別に指せる。同梱の提供元は毎年繰り返す祝日に `key` を付け（日本 16・英国 12・シンガポール 10。`docs/guide.md` の「Holiday keys」）、振替日は元の祝日の `key` を持ち、国民の休日・一度きりの祝日は持たない。`key` は日付の移動や公式の改名があっても変えない。補完用の型 `KnownJapaneseHolidayKey`・`KnownUkHolidayKey`・`KnownSgHolidayKey` を追加した（`@beta`）。利用者の提供元が付けた `key` は形式だけ検証し、複製・凍結して返す。診断は対応年に現れない `key` を `never-matches`、`key` の集合の包含を `shadowed` で扱う
+- `bizdays-toolkit/provider` に、週末に当たった祝日の振替日を計算する `substituteDays(holidays, { rules, kind, name?, original? })` を追加した（`@beta`。型 `SubstituteDaysOptions`・`SubstituteDirection`）。`rules` は曜日ごとの向き（`"next"`・`"previous"`）で、振替先は「入力の祝日でも、決めた振替日でも、`rules` の曜日でもない最初の日」。振替日は元の祝日の `key`・`names`・`confirmed` を引き継ぐ。日本（2007 年以降）・英国・シンガポールの同梱の提供元の振替日を再現することをテストで確かめている（内部の実装は置き換えていない）
+
+### Changed
+
+- `docs/guide.md`・`docs/guide.ja.md`: 「Holiday keys」（祝日の識別子）の節と、繰り返しの規則の `keys` を足した。コード例の結果に `key` が増えた
+- `docs/providers.md`・`docs/providers.ja.md`: `substituteDays` と、自作の提供元に `key` を付ける方法を足した
+- README: 規則の表と機能の箇条書きに `key`・振替の計算を足し、クイックスタートのコメントの "Labour Thanksgiving Day" を `nameEn` の綴り "Labor Thanksgiving Day" に直した
+- `RELEASING.md`: 区分の表で「対応年の拡大」を規則で計算する提供元（日本・英国）に限り、年ごとの表で持つ提供元（シンガポール）に告示済みの新しい年を足すことはパッチに置く、と線を引いた（これまでは 2 つの行が同時に当てはまる状態だった）。「毎年の作業（日本）」を「日本のデータの更新」に改め、監視の差分の種類と対応の表を足した
+- `docs/decisions.md`: 46 番（祝日の識別子と絞り込み、`substituteDays`、内閣府 CSV の毎日の照合、区分の線引き）を追加し、37 番の理由（存在しない「将来の非純粋な判定関数」を前提にしていた）と 44 番の `asOf` の理由（`Date` を断る理由としてタイムゾーンは成り立たなかった）を改めた
+
+### 開発
+
+- 監視のワークフロー `data-watch.yml` に内閣府「国民の祝日」CSV の照合を足した（issue のラベル `cao-data`。ハートビートは 3 つの照合がすべて動いたときだけ）。`scripts/verify-cao.ts` を英国・シンガポールと同じ形（`--report`・`--simulate`、終了コード 0・1・2、取得の再試行、「New years published」・フィクスチャの差分の節）にした。翌年の春分・秋分の日の公表が issue で届くので、2 月の作業を記憶に頼らない
+- テスト: `test/holiday-key.test.ts` を追加し、`test/provider.test.ts` に `substituteDays`（同梱の 3 か国との同値・向き・名称・入力の検証）を足した。`test/types.check.ts`・利用者の型チェックに `keys`・既知の `key` の型・`substituteDays` を足した
+- サイズの上限（`size-limits.json`）を上げた。`./provider` 4,500 → 6,500（`substituteDays` と入力の検証のため。測定 6,019）、`./diagnose` 32,000 → 33,000（`keys` の判定と診断のため。測定 31,645）（gzip）
+
 ## [0.17.1] - 2026-10-25
 
 ### Changed
@@ -469,7 +494,8 @@
 
 - 日本: 2026 年 2 月の官報（2027 年の春分・秋分の日）まで反映（`dataVersion: "2026-02"`、`confirmedThrough: 2027`）
 
-[Unreleased]: https://github.com/inohan77/bizdays-toolkit/compare/v0.17.1...HEAD
+[Unreleased]: https://github.com/inohan77/bizdays-toolkit/compare/v0.18.0...HEAD
+[0.18.0]: https://github.com/inohan77/bizdays-toolkit/compare/v0.17.1...v0.18.0
 [0.17.1]: https://github.com/inohan77/bizdays-toolkit/compare/v0.17.0...v0.17.1
 [0.17.0]: https://github.com/inohan77/bizdays-toolkit/compare/v0.16.0...v0.17.0
 [0.16.0]: https://github.com/inohan77/bizdays-toolkit/compare/v0.15.0...v0.16.0

package/README.md

@@ -25,7 +25,7 @@ A business-day calendar that combines public holidays with company or store clos
 - **Day-by-day values and combined calendars**: store hours that change by weekday, holiday and date; a business-day calendar made from such a schedule; and the days on which all (or any) of several calendars are open
 - **Option diagnostics**: `bizdays-toolkit/diagnose` lists rules that never apply, rules that are shadowed or redundant, rules that have ended, typos in option names and options with no business day at all, without throwing. One line in a test keeps options honest
 - **Lightweight, zero dependencies, time-zone safe**: about 10.0 KB min+gzip (about 11.8 KB with Japanese holidays, about 11.7 KB with UK bank holidays, about 10.9 KB with Singapore holidays; measured for 0.17.0). Standard JavaScript and `Intl` only, ESM with bundled types; tested on Node.js, Chrome, Firefox, Edge, Safari, Cloudflare Workers, Bun and Deno. Instants such as `Date` are converted to a civil date in the calendar's time zone before evaluation
-- **Extensible to other countries and regions**: holiday providers are pluggable through the `HolidayProvider` interface, and `bizdays-toolkit/provider` exposes the calendar arithmetic (nth weekday of a month, Easter) that most countries' holidays are built from
+- **Extensible to other countries and regions**: holiday providers are pluggable through the `HolidayProvider` interface, and `bizdays-toolkit/provider` exposes the calendar arithmetic (nth weekday of a month, Easter, substitute days for holidays on a weekend) that most countries' holidays are built from
 
 ## Installation
 
@@ -43,7 +43,7 @@ Types are bundled. CI type-checks a consumer project against the published type
 import { createCalendar } from "bizdays-toolkit";
 import { isHoliday, jp } from "bizdays-toolkit/jp";
 
-isHoliday("2026-11-23"); // true (Labour Thanksgiving Day)
+isHoliday("2026-11-23"); // true (Labor Thanksgiving Day)
 
 const calendar = createCalendar({
   holidays: jp,
@@ -79,12 +79,12 @@ A calendar is built from the holiday provider and your closures: `closedWeekdays
 | `{ weekday: 3, nth: 3 }`                                  | The 3rd Wednesday (`nth` is 1–5 or -1 for the last; an array for several)       |
 | `{ weekday: 3, interval: 2, anchor: "2026-01-07" }`       | Every other Wednesday, counted from the anchor                                  |
 | `{ day: 20 }`, `{ day: -1 }`                              | The 20th, the last day of the month                                             |
-| `{ holiday: true, kinds: ["substitute"] }`                | Holidays, optionally narrowed by kind                                           |
+| `{ holiday: true, kinds: ["substitute"] }`                | Holidays, optionally narrowed by kind or by key (`keys: ["vernal-equinox"]`)    |
 | `{ dayAfterHoliday: true }`, `{ dayBeforeHoliday: true }` | The day after (or before) a holiday or a run of holidays                        |
 | `onHolidayRule: "after-holiday"`                          | "Closed on Mondays, or the next weekday when Monday is a holiday" (museum rule) |
 | `effectiveFrom`, `effectiveTo`                            | The period the rule is in effect                                                |
 
-`dayInfo` tells you why a day is open or closed (`reason`, `name`, `rulePath`). Details: [Business-day calendars](https://github.com/inohan77/bizdays-toolkit/blob/main/docs/guide.md#business-day-calendars), [Recurring rules](https://github.com/inohan77/bizdays-toolkit/blob/main/docs/guide.md#recurring-rules), [Common recipes](https://github.com/inohan77/bizdays-toolkit/blob/main/docs/guide.md#common-recipes).
+`dayInfo` tells you why a day is open or closed (`reason`, `name`, `rulePath`). Every bundled holiday that recurs each year has a stable `key` (`vernal-equinox`, `good-friday`, `hari-raya-puasa`, …), so a rule can select individual holidays that no date pattern can express. Details: [Business-day calendars](https://github.com/inohan77/bizdays-toolkit/blob/main/docs/guide.md#business-day-calendars), [Recurring rules](https://github.com/inohan77/bizdays-toolkit/blob/main/docs/guide.md#recurring-rules), [Holiday keys](https://github.com/inohan77/bizdays-toolkit/blob/main/docs/guide.md#holiday-keys), [Common recipes](https://github.com/inohan77/bizdays-toolkit/blob/main/docs/guide.md#common-recipes).
 
 ### Due dates, schedules and combined calendars
 

package/dist/core/diagnose.js

@@ -393,7 +393,7 @@ function analyze(c, compiled, isCalendar) {
                 ? source.providers.length === 0
                     ? "This rule matches no day: there are no holidays without a holiday provider"
                     : rule.holiday
-                        ? "This rule matches no day: no holiday of the selected kinds, weekdays and months within its effective period"
+                        ? "This rule matches no day: no holiday of the selected kinds, keys, weekdays and months within its effective period"
                         : rule.dayAfterHoliday
                             ? "This rule matches no day: no day after a holiday on the selected weekdays and months within its effective period"
                             : "This rule matches no day: no day before a holiday on the selected weekdays and months within its effective period"
@@ -402,13 +402,14 @@ function analyze(c, compiled, isCalendar) {
                     : "This rule matches no day within its effective period");
             return;
         }
-        // 祝日・祝日の翌日・祝前日の規則は祝日次第で年ごとに変わるので、形の包含は同じ形の規則どうし（種別・曜日・月の絞り込み）だけで調べる
+        // 祝日・祝日の翌日・祝前日の規則は祝日次第で年ごとに変わるので、形の包含は同じ形の規則どうし（種別・識別子・曜日・月の絞り込み）だけで調べる
         const k = recurring.findIndex((r, i) => i < j &&
             canCover(r, rule) &&
             periodCovers(r, rule) &&
             (rule.holiday
                 ? r.holiday &&
                     setCovers(r.kinds, rule.kinds) &&
+                    setCovers(r.keys, rule.keys) &&
                     setCovers(r.weekdays, rule.weekdays) &&
                     setCovers(r.months, rule.months)
                 : rule.dayAfterHoliday || rule.dayBeforeHoliday

package/dist/core/schedule.d.ts

@@ -14,7 +14,7 @@
  * 毎年の月日・繰り返しの規則の有効期間（effectiveFrom・effectiveTo）の外では、その規則は書かれていないのと同じ。
  * 祝日の翌日の規則（dayAfterHoliday）は、前日が祝日でその日自身は祝日でない日に当てはまる（提供元の祝日だけで判定）。
  * 祝前日の規則（dayBeforeHoliday）は、翌日が祝日でその日自身は祝日でない日に当てはまる（同じく提供元の祝日だけ）。
- * 祝日の規則（holiday: true。kinds で種別を絞れる）は、「祝日の上」の段階で判定する
+ * 祝日の規則（holiday: true。kinds で種別を、keys で個別の祝日を絞れる）は、「祝日の上」の段階で判定する
  *
  * 営業日カレンダー（createCalendar）は、このスケジュールの真偽値版として作られている。
  */
@@ -22,7 +22,7 @@ import { type DateString, type Weekday } from "./date.ts";
 import { IssueCollector } from "./errors.ts";
 import { type CivilDateTimeParts, type DateInput, type DateTimeInput } from "./input.ts";
 export type { CivilDateTimeParts } from "./input.ts";
-import type { Holiday, HolidayProvider } from "./types.ts";
+import { type Holiday, type HolidayProvider } from "./types.ts";
 /**
  * 祝日の値の決め方（スケジュールの holiday の設定）。
  * @public
@@ -95,6 +95,7 @@ export interface WeekdayPattern {
     readonly holiday?: never;
     readonly weekdays?: never;
     readonly kinds?: never;
+    readonly keys?: never;
 }
 /**
  * 毎月の日の繰り返し（例: 毎月 20 日、毎月末日）。その月にない日（2 月 30 日など）は当てはまらない。
@@ -114,6 +115,7 @@ export interface DayOfMonthPattern {
     readonly holiday?: never;
     readonly weekdays?: never;
     readonly kinds?: never;
+    readonly keys?: never;
 }
 /**
  * 祝日の翌日（祝日が続く場合は連休が明けた日。その日自身は祝日でない）。「祝日」は提供元の祝日だけ。
@@ -134,6 +136,7 @@ export interface DayAfterHolidayPattern {
     readonly dayBeforeHoliday?: never;
     readonly holiday?: never;
     readonly kinds?: never;
+    readonly keys?: never;
 }
 /**
  * 祝前日（翌日が祝日で、その日自身は祝日でない日。連休なら連休の初日の前日）。「祝日」は提供元の祝日だけ。
@@ -155,9 +158,10 @@ export interface DayBeforeHolidayPattern {
     readonly dayAfterHoliday?: never;
     readonly holiday?: never;
     readonly kinds?: never;
+    readonly keys?: never;
 }
 /**
- * 祝日（提供元の祝日である日）。kinds で祝日の種別を絞れる（省略時はすべての祝日）。
+ * 祝日（提供元の祝日である日）。kinds で祝日の種別を、keys で個別の祝日を絞れる（省略時はすべての祝日）。
  * 「祝日の上」の段階（holidayPolicy・スケジュールの holiday より先）で判定し、祝日の既定の扱いの例外を書く
  * （例: 「2027 年 4 月から祝日も営業」「振替休日は診療」「5 月の祝日は特別営業時間」）。
  * 当てはまる日は祝日なので、onHolidayRule は指定できない（指定すると invalid-option）。
@@ -167,6 +171,14 @@ export interface HolidayPattern<Kind extends string = string> {
     readonly holiday: true;
     /** 当てはめる祝日の種別（Holiday.kind。省略時はすべて）。提供元の種別の型で補完が効く（型は開いているので他の文字列も通る） */
     readonly kinds?: readonly Kind[];
+    /**
+     * 当てはめる祝日の識別子（Holiday.key。省略時はすべて）。kinds・weekdays・months との AND。
+     * 春分の日・復活祭に連動する日・太陰暦の祝日のように月日や第 n 曜日では書けない祝日を個別に指す
+     * （例: 「春分の日・秋分の日は営業」は { holiday: true, keys: ["vernal-equinox", "autumnal-equinox"] }）。
+     * 振替日は元の祝日の key を持つので「成人の日とその振替」を指せる。当日だけなら kinds を併せて指定する。
+     * key を持たない祝日（国民の休日・臨時の祝日）には当てはまらない
+     */
+    readonly keys?: readonly string[];
     /** 当てはめる曜日（省略時はすべての曜日。例: [6] で土曜の祝日だけ） */
     readonly weekdays?: readonly Weekday[];
     /** 当てはめる月（省略時はすべての月） */
@@ -417,6 +429,8 @@ export interface RecurringRuleCompiled<T> extends CompiledPeriod {
     readonly holiday: boolean;
     /** 祝日の規則で絞る種別（null はすべての祝日） */
     readonly kinds: ReadonlySet<string> | null;
+    /** 祝日の規則で絞る識別子（null はすべての祝日） */
+    readonly keys: ReadonlySet<string> | null;
     /** 祝日・祝日の翌日・祝前日の規則で絞る曜日（null はすべての曜日） */
     readonly weekdays: ReadonlySet<number> | null;
     /** 月の集合（null はすべての月） */

package/dist/core/schedule.js

@@ -14,13 +14,14 @@
  * 毎年の月日・繰り返しの規則の有効期間（effectiveFrom・effectiveTo）の外では、その規則は書かれていないのと同じ。
  * 祝日の翌日の規則（dayAfterHoliday）は、前日が祝日でその日自身は祝日でない日に当てはまる（提供元の祝日だけで判定）。
  * 祝前日の規則（dayBeforeHoliday）は、翌日が祝日でその日自身は祝日でない日に当てはまる（同じく提供元の祝日だけ）。
- * 祝日の規則（holiday: true。kinds で種別を絞れる）は、「祝日の上」の段階で判定する
+ * 祝日の規則（holiday: true。kinds で種別を、keys で個別の祝日を絞れる）は、「祝日の上」の段階で判定する
  *
  * 営業日カレンダー（createCalendar）は、このスケジュールの真偽値版として作られている。
  */
 import { addDays, daysInMonth, fromDayNumber, isValidDate, parseDate, toDayNumber, weekdayOf, } from "./date.js";
 import { checkUnknownKeys, IssueCollector, rangeError } from "./errors.js";
 import { instantToCivil, toCivil, toDateTimeParts, toInstant, validateTimeZone, } from "./input.js";
+import { HOLIDAY_KEY_PATTERN } from "./types.js";
 // ------------------------------------------------------------
 // 入力チェック（誤りを集める。作成時は最初の誤りを例外にする）
 // ------------------------------------------------------------
@@ -318,6 +319,24 @@ export function compileRecurringRules(c, path, entries, valueOf, keys) {
             c.error("invalid-option", `${p}.kinds`, '"kinds" can be used only with "holiday"');
             ok = false;
         }
+        let holidayKeys = null;
+        if ("keys" in entry) {
+            if (!hasHoliday) {
+                c.error("invalid-option", `${p}.keys`, '"keys" can be used only with "holiday"');
+                ok = false;
+            }
+            else if (!Array.isArray(entry["keys"])) {
+                c.error("invalid-option", `${p}.keys`, "must be a non-empty array of holiday keys (Holiday.key)");
+                ok = false;
+            }
+            else {
+                const set = checkSet(c, `${p}.keys`, entry["keys"], (v) => typeof v === "string" && HOLIDAY_KEY_PATTERN.test(v), "a holiday key (Holiday.key: lowercase letters, digits and hyphens)");
+                if (set)
+                    holidayKeys = set;
+                else
+                    ok = false;
+            }
+        }
         let weekdays = null;
         if ("weekdays" in entry) {
             if (!hasHoliday && !hasAfter && !hasBefore) {
@@ -369,6 +388,7 @@ export function compileRecurringRules(c, path, entries, valueOf, keys) {
                 dayBeforeHoliday: hasBefore,
                 holiday: hasHoliday,
                 kinds,
+                keys: holidayKeys,
                 weekdays,
                 months,
                 onHolidayRule: onHoliday,
@@ -396,7 +416,9 @@ export function matchPattern(rule, date, holidayOf) {
             return false;
         if (rule.holiday) {
             const h = holidayOf(date);
-            return h !== undefined && (rule.kinds === null || rule.kinds.has(h.kind));
+            return (h !== undefined &&
+                (rule.kinds === null || rule.kinds.has(h.kind)) &&
+                (rule.keys === null || (h.key !== undefined && rule.keys.has(h.key))));
         }
         // 祝日の翌日は前日が祝日、祝前日は翌日が祝日（どちらもその日自身は祝日でない）
         if (holidayOf(date) !== undefined)
@@ -546,6 +568,12 @@ function loadProviderYear(provider, year) {
                 throw providerDataError(provider, year, `item ${i} (${date}) names: ${problem}`);
             holiday.names = Object.freeze(Object.fromEntries(Object.entries(h["names"])));
         }
+        if (h["key"] !== undefined) {
+            if (typeof h["key"] !== "string" || !HOLIDAY_KEY_PATTERN.test(h["key"])) {
+                throw providerDataError(provider, year, `item ${i} (${date}) key must match ${String(HOLIDAY_KEY_PATTERN)}: ${JSON.stringify(h["key"])}`);
+            }
+            holiday.key = h["key"];
+        }
         return Object.freeze(holiday);
     });
 }
@@ -674,6 +702,7 @@ export const RECURRING_RULE_KEYS = [
     "dayBeforeHoliday",
     "holiday",
     "kinds",
+    "keys",
     "weekdays",
     "months",
     "name",

package/dist/core/types.d.ts

@@ -1,4 +1,6 @@
 import type { DateString } from "./date.ts";
+/** @internal 祝日の識別子（Holiday.key）の形式 */
+export declare const HOLIDAY_KEY_PATTERN: RegExp;
 /**
  * 祝日・休日 1 日分。
  * @public
@@ -17,6 +19,14 @@ export interface Holiday<Kind extends string = string> {
     readonly names?: Readonly<Record<string, string>>;
     /** 種別（国ごとに定義。日本は JapaneseHolidayKind） */
     readonly kind: Kind;
+    /**
+     * その日が観測している祝日の識別子（省略可能）。/^[a-z0-9][a-z0-9-]*$/ に限る。
+     * name が公式データの呼び方を写すのに対し、key は規則（{ holiday: true, keys: [...] }）から祝日を指すための安定した
+     * 識別子で、提供元が決め、版をまたいで変えない（日付の移動・公式の改名があっても同じ祝日なら同じ key）。
+     * 振替日は元の祝日の key を持つ。種別と同じ情報しか持たない日（日本の国民の休日）や一度きりの日（臨時の祝日）は持たない。
+     * 同じ年に同じ key が複数回現れることはある（振替日と元の祝日、年に 2 回ある振替休日）
+     */
+    readonly key?: string;
     /**
      * 公式に確定しているか。
      * 例: 日本の春分・秋分の日は前年 2 月の官報で確定するため、それより先の年は false（計算による予測）
@@ -29,7 +39,7 @@ export interface Holiday<Kind extends string = string> {
  * 他の国・地域の祝日はこのインターフェースを実装して createCalendar・createSchedule に渡す。
  * holidaysInYear が返すデータは、年ごとに初めて使うときに検証され、誤りがあれば
  * code: "invalid-provider-data" の例外になる。返した祝日は、契約の項目（date・name・nameEn・names・
- * kind・confirmed）だけを持つ変更できないオブジェクトに複製される。
+ * kind・confirmed・key）だけを持つ変更できないオブジェクトに複製される。
  *
  * 互換性の約束: このインターフェースに項目を足すときは、メジャー版以外では省略可能な項目に限る。
  * @public

package/dist/core/types.js

@@ -1 +1,2 @@
-export {};
+/** @internal 祝日の識別子（Holiday.key）の形式 */
+export const HOLIDAY_KEY_PATTERN = /^[a-z0-9][a-z0-9-]*$/;

package/dist/jp/index.d.ts

@@ -14,7 +14,7 @@ import type { DateString } from "../core/date.ts";
 import type { CivilDateTimeParts, DateInput, DateTimeInput } from "../core/input.ts";
 import type { Holiday, HolidayProvider } from "../core/types.ts";
 import { type JapaneseHolidayKind } from "./rules.ts";
-export type { JapaneseHolidayKind, KnownJapaneseHolidayKind } from "./rules.ts";
+export type { JapaneseHolidayKind, KnownJapaneseHolidayKey, KnownJapaneseHolidayKind, } from "./rules.ts";
 /**
  * 日本の祝日。
  * @public

package/dist/jp/rules.d.ts

@@ -5,6 +5,7 @@
  * - 皇室行事による休日: 特例法ごとの日付をテーブルで持つ
  * - 振替休日: 1973-04-12 以降。2007 年からは「その日後で最も近い国民の祝日でない日」
  * - 国民の休日: 1985-12-27 以降。前日と翌日が国民の祝日である日
+ * - 識別子（key）: 祝日法の各祝日に 1 つ（KnownJapaneseHolidayKey）。振替休日は元の祝日の key、国民の休日・特例の休日は持たない
  * - 春分・秋分の日: 天文計算による近似式。官報公表済みの年（CONFIRMED_THROUGH）までは確定値と一致することを
  *   内閣府の CSV で検証している。それより後の年は confirmed: false
  */
@@ -28,6 +29,14 @@ export type KnownJapaneseHolidayKind =
  * @public
  */
 export type JapaneseHolidayKind = KnownJapaneseHolidayKind | (string & {});
+/**
+ * 日本の国民の祝日の識別子（Holiday.key。既知の値）。祝日法の各祝日に 1 つで、日付の移動や改名があっても同じ祝日なら同じ値
+ * （天皇誕生日は 4/29・12/23・2/23 とも "emperors-birthday"、体育の日とスポーツの日は "sports"）。
+ * 振替休日は元の祝日の key を持ち、国民の休日と特例の休日は key を持たない。
+ * 規則の keys に書くときの補完に使う（型は開いているので他の文字列も通る）。
+ * @beta
+ */
+export type KnownJapaneseHolidayKey = "new-year" | "coming-of-age" | "national-foundation" | "emperors-birthday" | "vernal-equinox" | "showa" | "constitution-memorial" | "greenery" | "childrens" | "marine" | "mountain" | "respect-for-the-aged" | "autumnal-equinox" | "sports" | "culture" | "labor-thanksgiving";
 /** @internal 対応年 */
 export declare const SUPPORTED_YEARS: Readonly<{
     from: 1955;

package/dist/jp/rules.js

@@ -5,6 +5,7 @@
  * - 皇室行事による休日: 特例法ごとの日付をテーブルで持つ
  * - 振替休日: 1973-04-12 以降。2007 年からは「その日後で最も近い国民の祝日でない日」
  * - 国民の休日: 1985-12-27 以降。前日と翌日が国民の祝日である日
+ * - 識別子（key）: 祝日法の各祝日に 1 つ（KnownJapaneseHolidayKey）。振替休日は元の祝日の key、国民の休日・特例の休日は持たない
  * - 春分・秋分の日: 天文計算による近似式。官報公表済みの年（CONFIRMED_THROUGH）までは確定値と一致することを
  *   内閣府の CSV で検証している。それより後の年は confirmed: false
  */
@@ -55,64 +56,64 @@ export function autumnalEquinoxDay(year) {
 /** 国民の祝日と特例の休日（振替休日・国民の休日を除く） */
 function baseHolidays(y) {
     const list = [];
-    const add = (date, name, nameEn, equinox = false) => {
-        list.push({ date, name, nameEn, kind: "national", equinox });
+    const add = (date, name, nameEn, key, equinox = false) => {
+        list.push({ date, name, nameEn, kind: "national", equinox, key });
     };
     const md = (month, day) => formatDate(y, month, day);
     const monday = (month, n) => nthWeekdayOfMonth(y, month, 1, n);
-    add(md(1, 1), "元日", "New Year's Day");
-    add(y <= 1999 ? md(1, 15) : monday(1, 2), "成人の日", "Coming of Age Day");
+    add(md(1, 1), "元日", "New Year's Day", "new-year");
+    add(y <= 1999 ? md(1, 15) : monday(1, 2), "成人の日", "Coming of Age Day", "coming-of-age");
     if (y >= 1967)
-        add(md(2, 11), "建国記念の日", "National Foundation Day");
+        add(md(2, 11), "建国記念の日", "National Foundation Day", "national-foundation");
     if (y >= 2020)
-        add(md(2, 23), "天皇誕生日", "The Emperor's Birthday");
-    add(md(3, vernalEquinoxDay(y)), "春分の日", "Vernal Equinox Day", true);
+        add(md(2, 23), "天皇誕生日", "The Emperor's Birthday", "emperors-birthday");
+    add(md(3, vernalEquinoxDay(y)), "春分の日", "Vernal Equinox Day", "vernal-equinox", true);
     if (y <= 1988)
-        add(md(4, 29), "天皇誕生日", "The Emperor's Birthday");
+        add(md(4, 29), "天皇誕生日", "The Emperor's Birthday", "emperors-birthday");
     else if (y <= 2006)
-        add(md(4, 29), "みどりの日", "Greenery Day");
+        add(md(4, 29), "みどりの日", "Greenery Day", "greenery");
     else
-        add(md(4, 29), "昭和の日", "Showa Day");
-    add(md(5, 3), "憲法記念日", "Constitution Memorial Day");
+        add(md(4, 29), "昭和の日", "Showa Day", "showa");
+    add(md(5, 3), "憲法記念日", "Constitution Memorial Day", "constitution-memorial");
     if (y >= 2007)
-        add(md(5, 4), "みどりの日", "Greenery Day");
-    add(md(5, 5), "こどもの日", "Children's Day");
+        add(md(5, 4), "みどりの日", "Greenery Day", "greenery");
+    add(md(5, 5), "こどもの日", "Children's Day", "childrens");
     // 海の日（1996〜）。2020・2021 年は五輪特措法による移動
     if (y === 2020)
-        add(md(7, 23), "海の日", "Marine Day");
+        add(md(7, 23), "海の日", "Marine Day", "marine");
     else if (y === 2021)
-        add(md(7, 22), "海の日", "Marine Day");
+        add(md(7, 22), "海の日", "Marine Day", "marine");
     else if (y >= 2003)
-        add(monday(7, 3), "海の日", "Marine Day");
+        add(monday(7, 3), "海の日", "Marine Day", "marine");
     else if (y >= 1996)
-        add(md(7, 20), "海の日", "Marine Day");
+        add(md(7, 20), "海の日", "Marine Day", "marine");
     // スポーツの日（2020〜）。2020・2021 年は五輪特措法による移動
     if (y === 2020)
-        add(md(7, 24), "スポーツの日", "Sports Day");
+        add(md(7, 24), "スポーツの日", "Sports Day", "sports");
     else if (y === 2021)
-        add(md(7, 23), "スポーツの日", "Sports Day");
+        add(md(7, 23), "スポーツの日", "Sports Day", "sports");
     // 山の日（2016〜）。2020・2021 年は五輪特措法による移動
     if (y === 2020)
-        add(md(8, 10), "山の日", "Mountain Day");
+        add(md(8, 10), "山の日", "Mountain Day", "mountain");
     else if (y === 2021)
-        add(md(8, 8), "山の日", "Mountain Day");
+        add(md(8, 8), "山の日", "Mountain Day", "mountain");
     else if (y >= 2016)
-        add(md(8, 11), "山の日", "Mountain Day");
+        add(md(8, 11), "山の日", "Mountain Day", "mountain");
     if (y >= 2003)
-        add(monday(9, 3), "敬老の日", "Respect for the Aged Day");
+        add(monday(9, 3), "敬老の日", "Respect for the Aged Day", "respect-for-the-aged");
     else if (y >= 1966)
-        add(md(9, 15), "敬老の日", "Respect for the Aged Day");
-    add(md(9, autumnalEquinoxDay(y)), "秋分の日", "Autumnal Equinox Day", true);
+        add(md(9, 15), "敬老の日", "Respect for the Aged Day", "respect-for-the-aged");
+    add(md(9, autumnalEquinoxDay(y)), "秋分の日", "Autumnal Equinox Day", "autumnal-equinox", true);
     if (y >= 2022)
-        add(monday(10, 2), "スポーツの日", "Sports Day");
+        add(monday(10, 2), "スポーツの日", "Sports Day", "sports");
     else if (y >= 2000 && y <= 2019)
-        add(monday(10, 2), "体育の日", "Health and Sports Day");
+        add(monday(10, 2), "体育の日", "Health and Sports Day", "sports");
     else if (y >= 1966 && y <= 1999)
-        add(md(10, 10), "体育の日", "Health and Sports Day");
-    add(md(11, 3), "文化の日", "Culture Day");
-    add(md(11, 23), "勤労感謝の日", "Labor Thanksgiving Day");
+        add(md(10, 10), "体育の日", "Health and Sports Day", "sports");
+    add(md(11, 3), "文化の日", "Culture Day", "culture");
+    add(md(11, 23), "勤労感謝の日", "Labor Thanksgiving Day", "labor-thanksgiving");
     if (y >= 1989 && y <= 2018)
-        add(md(12, 23), "天皇誕生日", "The Emperor's Birthday");
+        add(md(12, 23), "天皇誕生日", "The Emperor's Birthday", "emperors-birthday");
     for (const s of SPECIAL_DAYS) {
         if (s.date.startsWith(`${y}-`))
             list.push({ ...s, kind: "special", equinox: false });
@@ -147,6 +148,7 @@ export function computeJapaneseHolidays(year) {
             nameEn: "Substitute Holiday",
             kind: "substitute",
             equinox: h.equinox,
+            ...(h.key === undefined ? {} : { key: h.key }),
         });
     }
     // 国民の休日（前日と翌日が国民の祝日である日）
@@ -177,5 +179,6 @@ export function computeJapaneseHolidays(year) {
         nameEn: e.nameEn,
         kind: e.kind,
         confirmed: year <= CONFIRMED_THROUGH || !e.equinox,
+        ...(e.key === undefined ? {} : { key: e.key }),
     }));
 }

package/dist/provider/index.d.ts

@@ -4,11 +4,14 @@
  * 多くの国・地域の祝日は「月の第 n 何曜日」（米国の連邦祝日など）と「復活祭からの日数」（ヨーロッパの多くの国）で
  * 書ける。この 2 種類の計算と、月の日数・うるう年の判定を、ライブラリ内部で使っている実装のまま公開する
  * （復活祭の計算は英国の祝日で GOV.UK のデータと照合済み）。ルートの addDays・weekdayOf と組み合わせて使う。
+ * 週末に当たった祝日の振替（substituteDays）は、同梱の 3 つの提供元が使う計算と同じ定義で、同梱の提供元の
+ * 照合済みの結果と一致することをテストで確かめている（同梱の提供元の実装そのものは置き換えていない）。
  * 同梱の提供元の実装とは別に、アプリの本体に不要なものが入らないようサブパスに分けている。
  *
  * 公開する関数は @beta（マイナー版で変わりうる）。使われ方が固まったら @public にする。
  */
 import { type DateString, type Weekday } from "../core/date.ts";
+import { type Holiday } from "../core/types.ts";
 /**
  * 復活祭の日曜日（グレゴリオ暦）。Good Friday は −2 日、Easter Monday は +1 日、Ascension は +39 日、
  * Whit Monday は +50 日、Corpus Christi は +60 日（ルートの addDays で求める）。
@@ -33,3 +36,57 @@ export declare function daysInMonth(year: number, month: number): number;
  * @beta
  */
 export declare function isLeapYear(year: number): boolean;
+/**
+ * 振替の向き。"next" はその日より後で最初の振替先、"previous" はその日より前で最初の振替先。
+ * @beta
+ */
+export type SubstituteDirection = "next" | "previous";
+/**
+ * substituteDays の設定。
+ * @beta
+ */
+export interface SubstituteDaysOptions<Kind extends string> {
+    /**
+     * 振り替える曜日と向き（0 = 日曜日〜6 = 土曜日）。書いた曜日に当たる祝日だけを振り替える。
+     * 例: 日本・シンガポールは { 0: "next" }、英国は { 6: "next", 0: "next" }、米国の連邦祝日は { 6: "previous", 0: "next" }。
+     * 振替先は、入力の祝日でも、それまでに決めた振替日でも、ここに書いた曜日でもない最初の日
+     */
+    readonly rules: Readonly<Partial<Record<Weekday, SubstituteDirection>>>;
+    /** 振替日に付ける種別（Holiday.kind。例: "substitute"、"observed"） */
+    readonly kind: Kind;
+    /**
+     * 振替日の名称。省略時は元の祝日の name・nameEn（と names）を引き継ぐ（GOV.UK・MOM の流儀）。
+     * 変えるなら元の祝日を受け取って返す関数で（例: 日本の「振替休日」、米国の "(observed)"）
+     */
+    readonly name?: (holiday: Holiday<Kind>) => {
+        readonly name: string;
+        readonly nameEn: string;
+    };
+    /**
+     * 元の祝日（振り替えた曜日に当たった日）を結果に残すか。"keep"（既定）は残す（日本・シンガポール）、
+     * "drop" は振替日だけにする（GOV.UK の一覧は週末の日を載せない）
+     */
+    readonly original?: "keep" | "drop";
+}
+/**
+ * 週末などに当たった祝日の振替日を計算し、入力の祝日に振替日を足して日付順に返す（提供元を実装するための道具）。
+ *
+ * 定義（英国の附則・シンガポールの Holidays Act・日本の祝日法と同じ）: 入力を日付順に走査し、rules の曜日に当たる祝日ごとに、
+ * 指定の向きで「入力の祝日でも、それまでに決めた振替日でも、rules の曜日でもない最初の日」を振替日にする。祝日が続く
+ * 週末（Christmas Day が土曜日、Boxing Day が日曜日）は順に先へ送られる。振替日自身は別の祝日の振替の対象にならない。
+ * 振替日は元の祝日の key・names・confirmed を引き継ぎ、kind は options.kind、名称は省略時は元の祝日のもの。
+ *
+ * 入力は同じ年の祝日で、日付が有効・重複がないこと（誤りは invalid-argument・invalid-date・invalid-weekday の例外）。
+ * 振替日は年をまたぐことがある（12 月 31 日が祝日の国で日曜日なら翌年の 1 月 1 日）。提供元の holidaysInYear は
+ * その年の日付だけを返す契約なので、そうなる国では翌年の分として扱うこと。
+ * 国民の休日（2 つの祝日に挟まれた日）のような国に固有の規則は含まない。
+ *
+ * @example 米国の連邦祝日（土曜日は前の金曜日、日曜日は次の月曜日）
+ * substituteDays(federal, { rules: { 6: "previous", 0: "next" }, kind: "observed",
+ *   name: (h) => ({ name: `${h.name} (observed)`, nameEn: `${h.nameEn} (observed)` }) });
+ * @example 日本の振替休日（日曜日の祝日を、その日の後で最も近い祝日でない日へ）
+ * substituteDays(holidays, { rules: { 0: "next" }, kind: "substitute",
+ *   name: () => ({ name: "振替休日", nameEn: "Substitute Holiday" }) });
+ * @beta
+ */
+export declare function substituteDays<Kind extends string>(holidays: readonly Holiday<Kind>[], options: SubstituteDaysOptions<Kind>): Holiday<Kind>[];

package/dist/provider/index.js

@@ -4,12 +4,15 @@
  * 多くの国・地域の祝日は「月の第 n 何曜日」（米国の連邦祝日など）と「復活祭からの日数」（ヨーロッパの多くの国）で
  * 書ける。この 2 種類の計算と、月の日数・うるう年の判定を、ライブラリ内部で使っている実装のまま公開する
  * （復活祭の計算は英国の祝日で GOV.UK のデータと照合済み）。ルートの addDays・weekdayOf と組み合わせて使う。
+ * 週末に当たった祝日の振替（substituteDays）は、同梱の 3 つの提供元が使う計算と同じ定義で、同梱の提供元の
+ * 照合済みの結果と一致することをテストで確かめている（同梱の提供元の実装そのものは置き換えていない）。
  * 同梱の提供元の実装とは別に、アプリの本体に不要なものが入らないようサブパスに分けている。
  *
  * 公開する関数は @beta（マイナー版で変わりうる）。使われ方が固まったら @public にする。
  */
-import { daysInMonth as daysInMonthOf, easterSunday as easterSundayOf, formatDate, isLeapYear as isLeapYearOf, nthWeekdayOfMonth as nthWeekdayOfMonthIn, weekdayOf, } from "../core/date.js";
-import { rangeError } from "../core/errors.js";
+import { addDays, daysInMonth as daysInMonthOf, easterSunday as easterSundayOf, formatDate, isLeapYear as isLeapYearOf, isValidDate, nthWeekdayOfMonth as nthWeekdayOfMonthIn, parseDate, weekdayOf, } from "../core/date.js";
+import { rangeError, typeError } from "../core/errors.js";
+import { HOLIDAY_KEY_PATTERN } from "../core/types.js";
 function checkYear(year) {
     if (!Number.isInteger(year) || year < 1000 || year > 9999) {
         throw rangeError("invalid-argument", `year must be an integer from 1000 to 9999: ${String(year)}`);
@@ -74,3 +77,114 @@ export function isLeapYear(year) {
     checkYear(year);
     return isLeapYearOf(year);
 }
+function checkHolidays(holidays) {
+    if (!Array.isArray(holidays)) {
+        throw typeError("invalid-argument", "holidays must be an array of Holiday");
+    }
+    let year;
+    const seen = new Set();
+    holidays.forEach((h, i) => {
+        if (typeof h !== "object" || h === null) {
+            throw typeError("invalid-argument", `holidays[${i}] is not an object`);
+        }
+        const { date, name, nameEn, kind, confirmed, key } = h;
+        if (!isValidDate(date)) {
+            throw rangeError("invalid-date", `holidays[${i}] has an invalid date ${JSON.stringify(date)}`);
+        }
+        const y = parseDate(date).year;
+        if (year === undefined)
+            year = y;
+        else if (y !== year) {
+            throw rangeError("invalid-argument", `holidays must be in one year: ${holidays[0].date} and ${date}`);
+        }
+        if (seen.has(date))
+            throw rangeError("invalid-argument", `holidays has a duplicate date ${date}`);
+        seen.add(date);
+        if (typeof name !== "string" || typeof nameEn !== "string" || typeof kind !== "string") {
+            throw typeError("invalid-argument", `holidays[${i}] (${date}) must have string name, nameEn and kind`);
+        }
+        if (typeof confirmed !== "boolean") {
+            throw typeError("invalid-argument", `holidays[${i}] (${date}) must have boolean confirmed`);
+        }
+        if (key !== undefined && (typeof key !== "string" || !HOLIDAY_KEY_PATTERN.test(key))) {
+            throw typeError("invalid-argument", `holidays[${i}] (${date}) key must match ${String(HOLIDAY_KEY_PATTERN)}: ${JSON.stringify(key)}`);
+        }
+    });
+    return holidays;
+}
+function checkOptions(options) {
+    if (typeof options !== "object" || options === null) {
+        throw typeError("invalid-argument", "options must be an object");
+    }
+    const { rules, kind, name, original } = options;
+    if (typeof rules !== "object" || rules === null) {
+        throw typeError("invalid-argument", 'options.rules must be an object of { [weekday]: "next" | "previous" }');
+    }
+    for (const [weekday, direction] of Object.entries(rules)) {
+        if (!/^[0-6]$/.test(weekday)) {
+            throw rangeError("invalid-weekday", `options.rules has a weekday that is not 0 (Sunday) to 6 (Saturday): ${JSON.stringify(weekday)}`);
+        }
+        if (direction !== "next" && direction !== "previous") {
+            throw rangeError("invalid-argument", `options.rules[${weekday}] must be "next" or "previous": ${JSON.stringify(direction)}`);
+        }
+    }
+    if (typeof kind !== "string" || kind === "") {
+        throw typeError("invalid-argument", "options.kind must be a non-empty string (Holiday.kind)");
+    }
+    if (name !== undefined && typeof name !== "function") {
+        throw typeError("invalid-argument", "options.name must be a function (holiday) => { name, nameEn }");
+    }
+    if (original !== undefined && original !== "keep" && original !== "drop") {
+        throw rangeError("invalid-argument", 'options.original must be "keep" or "drop"');
+    }
+    return options;
+}
+/**
+ * 週末などに当たった祝日の振替日を計算し、入力の祝日に振替日を足して日付順に返す（提供元を実装するための道具）。
+ *
+ * 定義（英国の附則・シンガポールの Holidays Act・日本の祝日法と同じ）: 入力を日付順に走査し、rules の曜日に当たる祝日ごとに、
+ * 指定の向きで「入力の祝日でも、それまでに決めた振替日でも、rules の曜日でもない最初の日」を振替日にする。祝日が続く
+ * 週末（Christmas Day が土曜日、Boxing Day が日曜日）は順に先へ送られる。振替日自身は別の祝日の振替の対象にならない。
+ * 振替日は元の祝日の key・names・confirmed を引き継ぎ、kind は options.kind、名称は省略時は元の祝日のもの。
+ *
+ * 入力は同じ年の祝日で、日付が有効・重複がないこと（誤りは invalid-argument・invalid-date・invalid-weekday の例外）。
+ * 振替日は年をまたぐことがある（12 月 31 日が祝日の国で日曜日なら翌年の 1 月 1 日）。提供元の holidaysInYear は
+ * その年の日付だけを返す契約なので、そうなる国では翌年の分として扱うこと。
+ * 国民の休日（2 つの祝日に挟まれた日）のような国に固有の規則は含まない。
+ *
+ * @example 米国の連邦祝日（土曜日は前の金曜日、日曜日は次の月曜日）
+ * substituteDays(federal, { rules: { 6: "previous", 0: "next" }, kind: "observed",
+ *   name: (h) => ({ name: `${h.name} (observed)`, nameEn: `${h.nameEn} (observed)` }) });
+ * @example 日本の振替休日（日曜日の祝日を、その日の後で最も近い祝日でない日へ）
+ * substituteDays(holidays, { rules: { 0: "next" }, kind: "substitute",
+ *   name: () => ({ name: "振替休日", nameEn: "Substitute Holiday" }) });
+ * @beta
+ */
+export function substituteDays(holidays, options) {
+    const input = checkHolidays(holidays);
+    const { rules, kind, name, original } = checkOptions(options);
+    const sorted = [...input].sort((a, b) => (a.date < b.date ? -1 : 1));
+    const taken = new Set(sorted.map((h) => h.date));
+    const result = sorted.filter((h) => original !== "drop" || rules[weekdayOf(h.date)] === undefined);
+    for (const h of sorted) {
+        const direction = rules[weekdayOf(h.date)];
+        if (direction === undefined)
+            continue;
+        const step = direction === "next" ? 1 : -1;
+        let day = addDays(h.date, step);
+        while (taken.has(day) || rules[weekdayOf(day)] !== undefined)
+            day = addDays(day, step);
+        taken.add(day);
+        const named = name === undefined ? { name: h.name, nameEn: h.nameEn } : name(h);
+        result.push(Object.freeze({
+            date: day,
+            name: named.name,
+            nameEn: named.nameEn,
+            ...(h.names === undefined ? {} : { names: h.names }),
+            kind,
+            confirmed: h.confirmed,
+            ...(h.key === undefined ? {} : { key: h.key }),
+        }));
+    }
+    return result.sort((a, b) => (a.date < b.date ? -1 : 1));
+}

package/dist/sg/index.d.ts

@@ -8,7 +8,7 @@
  */
 import type { Holiday, HolidayProvider } from "../core/types.ts";
 import { type SgHolidayKind } from "./rules.ts";
-export type { KnownSgHolidayKind, SgHolidayKind } from "./rules.ts";
+export type { KnownSgHolidayKey, KnownSgHolidayKind, SgHolidayKind } from "./rules.ts";
 /**
  * シンガポールの祝日。
  * @public

package/dist/sg/rules.d.ts

@@ -6,6 +6,7 @@
  * 振替だけは Holidays Act（1998 年版）第 4 条の規則「日曜日に当たる祝日は、その翌日のうちそれ自体が祝日でない
  * 最初の日を祝日とする」で計算し、表には書かない。土曜日に当たる祝日は振替にならない（雇用主が休みか手当を与える）。
  *
+ * 識別子（key）は 11 の祝日に 1 つずつ（KnownSgHolidayKey）。振替日は元の祝日の key、Polling Day は持たない。
  * 名称は MOM の報道発表の綴り（アポストロフィは ’）。data.gov.sg のコレクション 691（MOM）のデータで
  * 全日照合している（test/fixtures/datagovsg-public-holidays.json）。data.gov.sg の 2022 年分は MOM の改定後の告示と
  * 食い違う（scripts/verify-datagovsg.ts の KNOWN_DIFFERENCES）ため、告示を正としている。
@@ -28,6 +29,13 @@ export type KnownSgHolidayKind =
  * @public
  */
 export type SgHolidayKind = KnownSgHolidayKind | (string & {});
+/**
+ * シンガポールの毎年の祝日の識別子（Holiday.key。既知の値）。11 の祝日に 1 つずつ。
+ * 振替日は元の祝日の key を持ち、臨時の祝日（Polling Day）は key を持たない。
+ * 規則の keys に書くときの補完に使う（型は開いているので他の文字列も通る）。
+ * @beta
+ */
+export type KnownSgHolidayKey = "new-year" | "chinese-new-year" | "good-friday" | "labour-day" | "hari-raya-puasa" | "vesak" | "hari-raya-haji" | "national-day" | "deepavali" | "christmas";
 /** @internal 対応年（表のある年。それより後は予測できないので out-of-range） */
 export declare const SUPPORTED_YEARS: Readonly<{
     from: 2020;

package/dist/sg/rules.js

@@ -6,6 +6,7 @@
  * 振替だけは Holidays Act（1998 年版）第 4 条の規則「日曜日に当たる祝日は、その翌日のうちそれ自体が祝日でない
  * 最初の日を祝日とする」で計算し、表には書かない。土曜日に当たる祝日は振替にならない（雇用主が休みか手当を与える）。
  *
+ * 識別子（key）は 11 の祝日に 1 つずつ（KnownSgHolidayKey）。振替日は元の祝日の key、Polling Day は持たない。
  * 名称は MOM の報道発表の綴り（アポストロフィは ’）。data.gov.sg のコレクション 691（MOM）のデータで
  * 全日照合している（test/fixtures/datagovsg-public-holidays.json）。data.gov.sg の 2022 年分は MOM の改定後の告示と
  * 食い違う（scripts/verify-datagovsg.ts の KNOWN_DIFFERENCES）ため、告示を正としている。
@@ -29,6 +30,19 @@ const NATIONAL = "National Day";
 const DEEPAVALI = "Deepavali";
 const CHRISTMAS = "Christmas Day";
 const POLLING = "Polling Day";
+/** 名称から識別子へ（Polling Day は持たない） */
+const KEY_OF = {
+    [NEW_YEAR]: "new-year",
+    [CNY]: "chinese-new-year",
+    [GOOD_FRIDAY]: "good-friday",
+    [LABOUR]: "labour-day",
+    [PUASA]: "hari-raya-puasa",
+    [VESAK]: "vesak",
+    [HAJI]: "hari-raya-haji",
+    [NATIONAL]: "national-day",
+    [DEEPAVALI]: "deepavali",
+    [CHRISTMAS]: "christmas",
+};
 /** 年ごとに動く祝日（月日と名前）。固定日の祝日（1/1・5/1・8/9・12/25）は表に書かず、下で足す */
 const MOVABLE = {
     2020: [
@@ -152,5 +166,15 @@ export function computeSgHolidays(year) {
     }
     return entries
         .sort((a, b) => (a.date < b.date ? -1 : 1))
-        .map((e) => Object.freeze({ date: e.date, name: e.name, nameEn: e.name, kind: e.kind, confirmed: true }));
+        .map((e) => {
+        const key = KEY_OF[e.name];
+        return Object.freeze({
+            date: e.date,
+            name: e.name,
+            nameEn: e.name,
+            kind: e.kind,
+            confirmed: true,
+            ...(key === undefined ? {} : { key }),
+        });
+    });
 }

package/dist/uk/index.d.ts

@@ -11,7 +11,7 @@
  */
 import type { Holiday, HolidayProvider } from "../core/types.ts";
 import { type UkHolidayKind } from "./rules.ts";
-export type { KnownUkHolidayKind, UkHolidayKind } from "./rules.ts";
+export type { KnownUkHolidayKey, KnownUkHolidayKind, UkHolidayKind } from "./rules.ts";
 /**
  * 英国の祝日。
  * @public

package/dist/uk/rules.d.ts

@@ -5,6 +5,7 @@
  *   （England and Wales・Northern Ireland の Good Friday と Christmas Day は慣習法上の休日だが、GOV.UK の一覧と同じく含める）
  * - 振替: 土曜日・日曜日に当たる固定日の祝日は、その後で最も近い、祝日でない平日に振り替える（日付順に割り当てる）
  * - 臨時の祝日・移動: 布告ごとの日付をテーブルで持つ
+ * - 識別子（key）: 毎年の祝日に GOV.UK の区分名から 1 つ（KnownUkHolidayKey）。振替日は元の祝日の key、臨時の祝日は持たない
  *
  * 対応年のすべての日付と名称が GOV.UK のデータと一致することを、テスト用フィクスチャ
  * （test/fixtures/govuk-bank-holidays.json）で検証している。CONFIRMED_THROUGH より後の年は、
@@ -28,6 +29,13 @@ export type KnownUkHolidayKind =
  * @public
  */
 export type UkHolidayKind = KnownUkHolidayKind | (string & {});
+/**
+ * 英国の毎年の bank holiday の識別子（Holiday.key。既知の値）。GOV.UK の区分名から付け、布告で日付が移った年も同じ値。
+ * 振替日は元の祝日の key を持ち、臨時の祝日（special）は key を持たない。
+ * 規則の keys に書くときの補完に使う（型は開いているので他の文字列も通る）。
+ * @beta
+ */
+export type KnownUkHolidayKey = "new-year" | "2nd-january" | "st-patricks" | "good-friday" | "easter-monday" | "early-may" | "spring" | "battle-of-the-boyne" | "summer" | "st-andrews" | "christmas" | "boxing-day";
 /** @internal GOV.UK の区分 */
 export type UkDivision = "england-and-wales" | "scotland" | "northern-ireland";
 /** @internal 対応年 */

package/dist/uk/rules.js

@@ -5,6 +5,7 @@
  *   （England and Wales・Northern Ireland の Good Friday と Christmas Day は慣習法上の休日だが、GOV.UK の一覧と同じく含める）
  * - 振替: 土曜日・日曜日に当たる固定日の祝日は、その後で最も近い、祝日でない平日に振り替える（日付順に割り当てる）
  * - 臨時の祝日・移動: 布告ごとの日付をテーブルで持つ
+ * - 識別子（key）: 毎年の祝日に GOV.UK の区分名から 1 つ（KnownUkHolidayKey）。振替日は元の祝日の key、臨時の祝日は持たない
  *
  * 対応年のすべての日付と名称が GOV.UK のデータと一致することを、テスト用フィクスチャ
  * （test/fixtures/govuk-bank-holidays.json）で検証している。CONFIRMED_THROUGH より後の年は、
@@ -59,8 +60,14 @@ const SPECIAL_DAYS = [
  * 同じ曜日の並びの 2012・2017 年は、附則どおり 1/2 が 2nd January、1/3 が New Year’s Day の振替
  */
 const RENAMED = [
-    { division: "scotland", date: "2023-01-02", name: NEW_YEAR, kind: "substitute" },
-    { division: "scotland", date: "2023-01-03", name: SECOND_JANUARY, kind: "substitute" },
+    { division: "scotland", date: "2023-01-02", name: NEW_YEAR, kind: "substitute", key: "new-year" },
+    {
+        division: "scotland",
+        date: "2023-01-03",
+        name: SECOND_JANUARY,
+        kind: "substitute",
+        key: "2nd-january",
+    },
 ];
 function lastMonday(year, month) {
     const last = formatDate(year, month, daysInMonth(year, month));
@@ -77,33 +84,40 @@ export function computeUkHolidays(division, year) {
     }
     const scotland = division === "scotland";
     const ni = division === "northern-ireland";
-    const fixed = [{ month: 1, day: 1, name: NEW_YEAR }];
+    const fixed = [{ month: 1, day: 1, name: NEW_YEAR, key: "new-year" }];
     if (scotland)
-        fixed.push({ month: 1, day: 2, name: SECOND_JANUARY });
+        fixed.push({ month: 1, day: 2, name: SECOND_JANUARY, key: "2nd-january" });
     if (ni)
-        fixed.push({ month: 3, day: 17, name: ST_PATRICK });
+        fixed.push({ month: 3, day: 17, name: ST_PATRICK, key: "st-patricks" });
     if (ni)
-        fixed.push({ month: 7, day: 12, name: BOYNE });
+        fixed.push({ month: 7, day: 12, name: BOYNE, key: "battle-of-the-boyne" });
     if (scotland)
-        fixed.push({ month: 11, day: 30, name: ST_ANDREW });
-    fixed.push({ month: 12, day: 25, name: CHRISTMAS }, { month: 12, day: 26, name: BOXING });
+        fixed.push({ month: 11, day: 30, name: ST_ANDREW, key: "st-andrews" });
+    fixed.push({ month: 12, day: 25, name: CHRISTMAS, key: "christmas" }, { month: 12, day: 26, name: BOXING, key: "boxing-day" });
     const easter = easterSunday(year);
     const movable = [
-        { date: addDays(easter, -2), name: GOOD_FRIDAY, kind: "regular" },
-        { date: nthWeekdayOfMonth(year, 5, 1, 1), name: EARLY_MAY, kind: "regular" },
-        { date: lastMonday(year, 5), name: SPRING, kind: "regular" },
+        { date: addDays(easter, -2), name: GOOD_FRIDAY, kind: "regular", key: "good-friday" },
+        { date: nthWeekdayOfMonth(year, 5, 1, 1), name: EARLY_MAY, kind: "regular", key: "early-may" },
+        { date: lastMonday(year, 5), name: SPRING, kind: "regular", key: "spring" },
         {
             date: scotland ? nthWeekdayOfMonth(year, 8, 1, 1) : lastMonday(year, 8),
             name: SUMMER,
             kind: "regular",
+            key: "summer",
         },
     ];
-    if (!scotland)
-        movable.push({ date: addDays(easter, 1), name: EASTER_MONDAY, kind: "regular" });
+    if (!scotland) {
+        movable.push({
+            date: addDays(easter, 1),
+            name: EASTER_MONDAY,
+            kind: "regular",
+            key: "easter-monday",
+        });
+    }
     const entries = [];
     for (const e of movable) {
         const moved = MOVED.find((m) => m.year === year && m.from === e.name);
-        entries.push(moved ? { date: moved.date, name: moved.name ?? e.name, kind: e.kind } : e);
+        entries.push(moved ? { ...e, date: moved.date, name: moved.name ?? e.name } : e);
     }
     for (const s of SPECIAL_DAYS) {
         if (s.date.startsWith(`${year}-`) && s.divisions.includes(division)) {
@@ -112,10 +126,14 @@ export function computeUkHolidays(division, year) {
     }
     // 平日に当たる固定日の祝日を先に置き、土曜日・日曜日に当たるものを日付順に振り替える
     const taken = new Set(entries.map((e) => e.date));
-    const fixedDates = fixed.map((f) => ({ date: formatDate(year, f.month, f.day), name: f.name }));
+    const fixedDates = fixed.map((f) => ({
+        date: formatDate(year, f.month, f.day),
+        name: f.name,
+        key: f.key,
+    }));
     for (const f of fixedDates) {
         if (!isWeekend(f.date)) {
-            entries.push({ date: f.date, name: f.name, kind: "regular" });
+            entries.push({ date: f.date, name: f.name, kind: "regular", key: f.key });
             taken.add(f.date);
         }
     }
@@ -125,7 +143,7 @@ export function computeUkHolidays(division, year) {
         let day = addDays(f.date, 1);
         while (isWeekend(day) || taken.has(day))
             day = addDays(day, 1);
-        entries.push({ date: day, name: f.name, kind: "substitute" });
+        entries.push({ date: day, name: f.name, kind: "substitute", key: f.key });
         taken.add(day);
     }
     for (const r of RENAMED) {
@@ -133,7 +151,7 @@ export function computeUkHolidays(division, year) {
             continue;
         const i = entries.findIndex((e) => e.date === r.date);
         if (i >= 0)
-            entries[i] = { date: r.date, name: r.name, kind: r.kind };
+            entries[i] = { date: r.date, name: r.name, kind: r.kind, key: r.key };
     }
     return entries
         .sort((a, b) => (a.date < b.date ? -1 : 1))
@@ -143,5 +161,6 @@ export function computeUkHolidays(division, year) {
         nameEn: e.name,
         kind: e.kind,
         confirmed: year <= CONFIRMED_THROUGH,
+        ...(e.key === undefined ? {} : { key: e.key }),
     }));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bizdays-toolkit",
-  "version": "0.17.1",
+  "version": "0.18.0",
   "description": "Holidays, business-day calendar and day-by-day schedules (e.g. store hours) with time zone support. Japanese holidays verified against the Cabinet Office data; UK bank holidays (England, Wales, Scotland, Northern Ireland) verified against GOV.UK; Singapore public holidays verified against data.gov.sg. / 祝日と営業日のカレンダー（タイムゾーン対応・日本の祝日は内閣府、英国の bank holidays は GOV.UK、シンガポールの祝日は data.gov.sg のデータで全日照合）",
   "keywords": [
     "bank-holidays",