bizdays-toolkit 0.3.1 → 0.4.0

package/CHANGELOG.md

@@ -4,6 +4,25 @@
 
 ## [Unreleased]
 
+## [0.4.0] - 2026-10-16
+
+### Added
+
+- 繰り返しの規則: 毎週（`{ weekday }`）・毎月の第 n 曜日（`{ weekday, nth }`。`nth` は 1〜5 と -1（最終））・毎月の日（`{ day }`。`day` は 1〜31 と -1（末日））。どれにも月の絞り込み（`months`）を付けられる。営業日カレンダーの `closedRecurring`・`openRecurring`、スケジュールの `recurring`
+- 祝日に当たったときの扱いを規則ごとに選ぶ `onHolidayRule`: `"under-holiday"`（祝日の扱いに従う。既定）・`"over-holiday"`（祝日でも当てはめる）・`"after-holiday"`（祝日でない翌日に振り替える。「月曜休館（祝日の場合は翌平日）」など）
+- `dayInfo()` の `shiftedFrom`: 振替で決まった日の、振替の元の日付
+- 判定の理由に `"recurring"`（スケジュール）・`"open-recurring"`・`"closed-recurring"`（営業日カレンダー）を追加
+- 型: `RecurringRule`・`RecurringValue`・`RecurringPattern`・`WeekdayPattern`・`DayOfMonthPattern`・`OnHolidayRule`・`Nth`・`DayOfMonth`・`Month`・`HolidayValueRule`
+
+### Deprecated
+
+- `HolidayRule` 型: `HolidayValueRule` に改名した（繰り返しの規則の `onHolidayRule` と紛れないため）。旧名は同じ型の別名として残し、次以降のマイナー版で削除する
+
+### 開発
+
+- 性能の計測（`pnpm bench`、依存なし）を追加
+- README に繰り返しの規則の節と、よくある設定の例（国民の休日を営業日として扱う、共通の設定から店舗ごとのカレンダーを作る）を追加。`docs/decisions.md` に 12〜14 番目（判定の順番を固定する理由、「第 n 何曜日」の定義、振替先の定義）を追加
+
 ## [0.3.1] - 2026-10-15
 
 ライブラリのコード・公開する API・祝日データに変更はありません。開発の検査を強めた版です。
@@ -90,7 +109,8 @@
 
 - 日本: 2026 年 2 月の官報（2027 年の春分・秋分の日）まで反映（`dataVersion: "2026-02"`、`confirmedThrough: 2027`）
 
-[Unreleased]: https://github.com/inohan77/bizdays-toolkit/compare/v0.3.1...HEAD
+[Unreleased]: https://github.com/inohan77/bizdays-toolkit/compare/v0.4.0...HEAD
+[0.4.0]: https://github.com/inohan77/bizdays-toolkit/compare/v0.3.1...v0.4.0
 [0.3.1]: https://github.com/inohan77/bizdays-toolkit/compare/v0.3.0...v0.3.1
 [0.3.0]: https://github.com/inohan77/bizdays-toolkit/compare/v0.2.0...v0.3.0
 [0.2.0]: https://github.com/inohan77/bizdays-toolkit/compare/v0.1.2...v0.2.0

package/README.md

@@ -17,10 +17,11 @@
 祝日と、会社・店舗の休業日を組み合わせた営業日カレンダーです。
 
 - **日本の祝日を内閣府のデータで全日照合**: 1955 年〜官報公表済みの年まで、内閣府「国民の祝日」CSV のすべての日付と一致することをテストで確かめています（振替休日・国民の休日・皇室行事による休日・五輪特措法による移動を含む）
+- **繰り返しの規則**: 「第 3 水曜定休」「毎月末日は棚卸」「月曜休館（祝日の場合は翌平日）」のような規則を、祝日に当たったときの扱い（祝日に従う・祝日でも当てはめる・翌日に振り替える）とあわせて指定できます
 - **日ごとの値（営業時間など）**: 「火曜定休、祝日は日曜の営業時間、元日は休業、大晦日は短縮営業」のように、曜日・祝日・特定日で変わる値を同じ規則で引けます
 - **営業日の計算**: 定休日の曜日・毎年の休業日（年末年始のような年をまたぐ期間も可）・臨時休業日・臨時営業日と祝日を組み合わせ、「N 営業日後」「締め時刻を過ぎたら翌営業日」などを計算します
 - **タイムゾーンを間違えない**: `Date` などの瞬間は、カレンダーのタイムゾーン（日本は `Asia/Tokyo`）で暦日に変換してから判定します。UTC で動くサーバーでも、日本時間 0〜9 時が前日扱いになりません
-- **軽量・依存ゼロ**: minify + gzip で約 5.5KB（日本の祝日込みで約 7KB）。ESM・型定義同梱・`sideEffects: false` で、Node.js・ブラウザー・Edge ランタイムで動作します
+- **軽量・依存ゼロ**: minify + gzip で約 6.5KB（日本の祝日込みで約 7.5KB）。ESM・型定義同梱・`sideEffects: false` で、Node.js・ブラウザー・Edge ランタイムで動作します
 - **他の国・地域に拡張できる**: 祝日の提供元はインターフェース（`HolidayProvider`）で差し替えられます。現在は日本のみ同梱しています
 
 [English](#english)
@@ -84,9 +85,96 @@ shipping.dayInfo("2027-01-01");
 1. `openDates`（臨時営業日）
 2. `closedDates`（臨時休業日）
 3. `closedAnnual`（毎年の休業日）
-4. 祝日（`holidayPolicy` に従う。`"open"` は定休日の曜日より優先して営業日にする）
-5. `closedWeekdays`（定休日の曜日）
-6. それ以外は営業日
+4. `openRecurring`・`closedRecurring` のうち `onHolidayRule: "over-holiday"` の規則（祝日でも当てはめる）
+5. 祝日（`holidayPolicy` に従う。`"open"` は定休日の曜日より優先して営業日にする）
+6. `openRecurring`・`closedRecurring`（既定の `"under-holiday"` と、`"after-holiday"` の振替先）
+7. `closedWeekdays`（定休日の曜日）
+8. それ以外は営業日
+
+この順番は固定です。繰り返しの規則と祝日の関係だけは、規則ごとに `onHolidayRule` で選べます（次の節）。
+
+### 繰り返しの規則（毎週・毎月の第 n 曜日・毎月の日）
+
+「第 3 水曜定休」「第 2・第 4 土曜休業」「毎月末日は棚卸」「月曜休館（祝日の場合は翌平日）」のような繰り返しの休業日・営業日は、`closedRecurring`・`openRecurring` で指定します。
+
+```ts
+const museum = createCalendar({
+  holidays: jp,
+  holidayPolicy: "open", // 祝日は開館
+  closedRecurring: [
+    { weekday: 1, name: "月曜休館", onHolidayRule: "after-holiday" }, // 祝日の場合は翌平日に休館
+    { weekday: 3, nth: 3, months: [2, 8], name: "2 月・8 月の第 3 水曜は臨時休館" },
+    { day: -1, name: "月末棚卸", onHolidayRule: "over-holiday" }, // 祝日でも休館
+  ],
+});
+
+museum.isBusinessDay("2026-10-12"); // true（スポーツの日の月曜は開館）
+museum.dayInfo("2026-10-13");
+// { date: "2026-10-13", weekday: 2, businessDay: false, reason: "closed-recurring",
+//   name: "月曜休館", shiftedFrom: "2026-10-12" }
+```
+
+| 書き方                   | 意味                                                                            |
+| ------------------------ | ------------------------------------------------------------------------------- |
+| `{ weekday: 1 }`         | 毎週月曜日                                                                      |
+| `{ weekday: 3, nth: 3 }` | 第 3 水曜日。`nth` は 1〜5 と -1（最終）。`[2, 4]` のように配列で複数指定できる |
+| `{ day: 20 }`            | 毎月 20 日。`day` は 1〜31 と -1（末日）。配列で複数指定できる                  |
+| `months: [8, 12]`        | どの書き方にも付けられる、月の絞り込み                                          |
+
+- **第 n 何曜日**は「その月で n 回目のその曜日」です（1〜7 日が第 1）。カレンダーの第 n 週の行にある曜日ではありません
+- **その月にない日**（`nth: 5` がない月、`day: 31` がない月）は当てはまりません。末日は `day: -1` で指定します
+- 繰り返しの規則どうしは配列で先に書いたものが優先で、`openRecurring` は `closedRecurring` より優先です
+
+**祝日に当たったときの扱い**（`onHolidayRule`）は、規則ごとに選べます。
+
+| 値                        | 意味                                                     | 店舗の告知での書き方                  |
+| ------------------------- | -------------------------------------------------------- | ------------------------------------- |
+| `"under-holiday"`（既定） | 祝日の下。祝日の扱い（`holidayPolicy`）に従う            | 「第 3 水曜定休（祝日の場合は営業）」 |
+| `"over-holiday"`          | 祝日の上。祝日でも当てはめる                             | 「第 3 水曜定休（祝日も休み）」       |
+| `"after-holiday"`         | 祝日の後。祝日には当てはめず、祝日でない翌日に振り替える | 「月曜休館（祝日の場合は翌平日）」    |
+
+- `"under-holiday"` の規則は、`holidayPolicy: "ignore"`（祝日を判定に使わない）なら祝日にも当てはまります
+- `"after-holiday"` の振替先は「その日以降で最初の祝日でない日」です。祝日が続く場合（GW など）は連休が明けた日になります。振替先の日に臨時営業日・臨時休業日・毎年の休業日があれば、そちらが優先です。振替で決まった日の `dayInfo()` には、振替の元の日付 `shiftedFrom` が付きます
+- 振替の判断に使う「祝日」は、祝日の提供元（`jp` など）の祝日だけです（毎年の休業日などは含みません）
+
+スケジュールでは、同じ書き方の規則に `value` を付けて `recurring` に指定します。
+
+```ts
+const hours = createSchedule<Hours>({
+  holidays: jp,
+  weekly: [sunday, weekday, weekday, weekday, weekday, weekday, weekday],
+  recurring: [
+    { weekday: 1, value: null, name: "月曜休業", onHolidayRule: "after-holiday" },
+    { day: -1, value: { open: "10:00", close: "17:00" }, name: "月末は短縮営業" },
+  ],
+});
+```
+
+### よくある設定の例
+
+**国民の休日（祝日に挟まれた日）を営業日として扱う**：祝日の提供元を包んで、種別で除外します。
+
+```ts
+import { jp } from "bizdays-toolkit/jp";
+
+const jpWithoutCitizensHoliday = {
+  ...jp,
+  holidaysInYear: (year: number) => jp.holidaysInYear(year).filter((h) => h.kind !== "citizens"),
+};
+const calendar = createCalendar({ holidays: jpWithoutCitizensHoliday, closedWeekdays: [0, 6] });
+```
+
+**共通の設定から店舗ごとのカレンダーを作る**：設定は普通のオブジェクトなので、展開して足します。
+
+```ts
+const base = {
+  holidays: jp,
+  closedWeekdays: [0],
+  closedAnnual: [{ from: "12-31", to: "01-03" }],
+} as const;
+const shibuya = createCalendar({ ...base, openDates: ["2026-12-27"] });
+const yokohama = createCalendar({ ...base, closedRecurring: [{ weekday: 3, nth: 3 }] });
+```
 
 ### 日ごとの値（営業時間など）
 
@@ -113,7 +201,7 @@ storeHours.dayInfo("2027-01-01");
 // { date: "2027-01-01", weekday: 5, value: null, reason: "annual", name: "元日休業", holiday: {…} }
 ```
 
-値は `dates`（個別の日付・期間）→ `annual`（毎年の月日・期間）→ 祝日 → `weekly`（曜日）の順に決まります。同じ種類の規則が重なる場合は、配列で先に書いたものが優先です。
+値は `dates`（個別の日付・期間）→ `annual`（毎年の月日・期間）→ `recurring`（`"over-holiday"`）→ 祝日 → `recurring`（既定・振替先）→ `weekly`（曜日）の順に決まります。同じ種類の規則が重なる場合は、配列で先に書いたものが優先です。
 
 「今、営業時間内か」のような時刻の範囲の判定は、業種ごとの決まり（深夜をまたぐ営業、休憩時間など）があるためライブラリでは行いません。`civilOf` でタイムゾーンでの暦日と時刻を取り出せば、アプリ側で簡単に書けます。
 
@@ -213,9 +301,10 @@ A business-day calendar that combines public holidays with company or store clos
 
 - **Japanese holidays verified day by day** against the Cabinet Office CSV, from 1955 through the latest year officially announced (substitute holidays, citizens' holidays, imperial ceremonies, and the Olympic moves included)
 - **Day-by-day schedules**: `createSchedule` returns any value per day (e.g. store hours) from weekly values, a holiday rule (`"weekday"`, `{ sameAs: 0 }`, or `{ value }`), annual dates and specific dates
+- **Recurring rules**: weekly, nth-weekday-of-month (`{ weekday: 3, nth: 3 }`) and day-of-month (`{ day: -1 }`) rules, with per-rule holiday handling (`onHolidayRule`: `"under-holiday"`, `"over-holiday"`, or `"after-holiday"` to move the rule to the next non-holiday, e.g. "closed on Mondays; if Monday is a holiday, closed on the next weekday")
 - **Business-day arithmetic**: closed weekdays, annual closures (including ranges across the new year), specific closed/open dates, holiday policy, `addBusinessDays`, cut-off times, and more
 - **Time-zone safe**: instants (`Date`, ISO strings with offsets, Temporal) are converted to a civil date in the calendar's time zone before evaluation
-- **Lightweight, zero dependencies**: about 5.5 KB min+gzip (about 7 KB with Japanese holidays), ESM, bundled types, `sideEffects: false`
+- **Lightweight, zero dependencies**: about 6.5 KB min+gzip (about 7.5 KB with Japanese holidays), ESM, bundled types, `sideEffects: false`
 - **Extensible** through the `HolidayProvider` interface (only Japan is bundled for now)
 
 ```ts

package/dist/core/calendar.d.ts

@@ -5,16 +5,21 @@
  *   1. openDates      … 臨時営業日（個別の日付・期間）
  *   2. closedDates    … 臨時休業日（個別の日付・期間）
  *   3. closedAnnual   … 毎年の休業日（月日・月日の期間。年をまたぐ期間も可）
- *   4. 祝日            … holidayPolicy に従う（closed: 休業 / open: 営業 / ignore: 判定に使わない）
- *   5. closedWeekdays … 定休日の曜日
- *   6. それ以外は営業日
+ *   4. openRecurring・closedRecurring（onHolidayRule: "over-holiday"）… 祝日でも当てはめる繰り返しの規則
+ *   5. 祝日            … holidayPolicy に従う（closed: 休業 / open: 営業 / ignore: 判定に使わない）
+ *   6. openRecurring・closedRecurring（"under-holiday"・"after-holiday" の振替先）… 繰り返しの規則
+ *   7. closedWeekdays … 定休日の曜日
+ *   8. それ以外は営業日
+ *
+ * 繰り返しの規則は openRecurring が closedRecurring より優先。"after-holiday" の規則は、
+ * 祝日には当てはめず、その日以降で最初の祝日でない日に当てはめる（振替）
  *
  * 内部では、営業日かどうか（真偽値）を返すスケジュール（createSchedule）として作っている。
  */
 import { type DateString, type Weekday } from "./date.ts";
 import { IssueCollector } from "./errors.ts";
 import { type DateInput } from "./input.ts";
-import { type CompiledSchedule, type HolidayLookup, type HolidaySourceOptions } from "./schedule.ts";
+import { type CompiledSchedule, type RecurringRule, type HolidayLookup, type HolidaySourceOptions } from "./schedule.ts";
 import type { Holiday } from "./types.ts";
 /**
  * 祝日の扱い。
@@ -68,6 +73,13 @@ export interface CalendarOptions<Kind extends string = string> extends HolidaySo
     readonly closedDates?: readonly (SpecificDate | DateRange)[];
     /** 臨時営業日（ほかのすべての規則より優先） */
     readonly openDates?: readonly (SpecificDate | DateRange)[];
+    /**
+     * 繰り返しの休業日（毎週・毎月の第 n 曜日・毎月の日）。
+     * 祝日に当たったときの扱いは規則ごとに onHolidayRule で指定する（既定: "under-holiday"）
+     */
+    readonly closedRecurring?: readonly RecurringRule[];
+    /** 繰り返しの営業日。closedRecurring と同じ日に当たる場合はこちらが優先 */
+    readonly openRecurring?: readonly RecurringRule[];
     /** 祝日の扱い（既定: "closed"） */
     readonly holidayPolicy?: HolidayPolicy;
     /** 営業日を探すときに調べる最大日数（既定: 3660）。超えたら Error */
@@ -77,7 +89,7 @@ export interface CalendarOptions<Kind extends string = string> extends HolidaySo
  * 営業・休業を決めた規則（既知の値）。
  * @public
  */
-export type KnownDayReason = "open-date" | "closed-date" | "closed-annual" | "holiday" | "closed-weekday" | "regular";
+export type KnownDayReason = "open-date" | "closed-date" | "closed-annual" | "open-recurring" | "closed-recurring" | "holiday" | "closed-weekday" | "regular";
 /**
  * 営業・休業を決めた規則。将来の版で値が増えることがあるので、分岐では「その他」も扱うこと。
  * すべての値を網羅したことを型で確かめたい場合は KnownDayReason を使う。
@@ -98,6 +110,8 @@ export interface DayInfo<Kind extends string = string> {
     readonly name?: string;
     /** その日が祝日なら祝日（holidayPolicy に関係なく付く） */
     readonly holiday?: Holiday<Kind>;
+    /** 祝日から振り替えられた繰り返しの規則で決まった場合、振替の元の日付（onHolidayRule: "after-holiday"） */
+    readonly shiftedFrom?: DateString;
 }
 /**
  * 営業日を探すときのオプション。

package/dist/core/calendar.js

@@ -5,16 +5,21 @@
  *   1. openDates      … 臨時営業日（個別の日付・期間）
  *   2. closedDates    … 臨時休業日（個別の日付・期間）
  *   3. closedAnnual   … 毎年の休業日（月日・月日の期間。年をまたぐ期間も可）
- *   4. 祝日            … holidayPolicy に従う（closed: 休業 / open: 営業 / ignore: 判定に使わない）
- *   5. closedWeekdays … 定休日の曜日
- *   6. それ以外は営業日
+ *   4. openRecurring・closedRecurring（onHolidayRule: "over-holiday"）… 祝日でも当てはめる繰り返しの規則
+ *   5. 祝日            … holidayPolicy に従う（closed: 休業 / open: 営業 / ignore: 判定に使わない）
+ *   6. openRecurring・closedRecurring（"under-holiday"・"after-holiday" の振替先）… 繰り返しの規則
+ *   7. closedWeekdays … 定休日の曜日
+ *   8. それ以外は営業日
+ *
+ * 繰り返しの規則は openRecurring が closedRecurring より優先。"after-holiday" の規則は、
+ * 祝日には当てはめず、その日以降で最初の祝日でない日に当てはめる（振替）
  *
  * 内部では、営業日かどうか（真偽値）を返すスケジュール（createSchedule）として作っている。
  */
 import { addDays, fromDayNumber, toDayNumber } from "./date.js";
 import { checkUnknownKeys, IssueCollector, plainError, rangeError } from "./errors.js";
 import { parseTimeOfDay, toCivil } from "./input.js";
-import { buildSchedule, compileAnnualRules, compileDateRules, compileHolidaySource, isWeekday, } from "./schedule.js";
+import { buildSchedule, compileAnnualRules, compileDateRules, compileHolidaySource, compileRecurringRules, isWeekday, RECURRING_RULE_KEYS, } from "./schedule.js";
 const CALENDAR_OPTION_KEYS = [
     "holidays",
     "timeZone",
@@ -23,6 +28,8 @@ const CALENDAR_OPTION_KEYS = [
     "closedAnnual",
     "closedDates",
     "openDates",
+    "closedRecurring",
+    "openRecurring",
     "holidayPolicy",
     "maxSearchDays",
 ];
@@ -61,6 +68,8 @@ export function compileCalendarOptions(c, options) {
     const annual = compileAnnualRules(c, "closedAnnual", o["closedAnnual"], () => false, true);
     const open = compileDateRules(c, "openDates", o["openDates"], () => true, true);
     const closed = compileDateRules(c, "closedDates", o["closedDates"], () => false, true);
+    const openRecurring = compileRecurringRules(c, "openRecurring", o["openRecurring"], () => true, RECURRING_RULE_KEYS);
+    const closedRecurring = compileRecurringRules(c, "closedRecurring", o["closedRecurring"], () => false, RECURRING_RULE_KEYS);
     return {
         schedule: {
             source,
@@ -69,6 +78,8 @@ export function compileCalendarOptions(c, options) {
             annual,
             // 臨時営業日を先に並べて、臨時休業日より優先する
             dates: [...open, ...closed],
+            // 繰り返しの営業日を先に並べて、繰り返しの休業日より優先する
+            recurring: [...openRecurring, ...closedRecurring],
         },
         maxSearchDays: Number.isInteger(maxSearchDays) ? maxSearchDays : 3660,
     };
@@ -98,6 +109,9 @@ export function createCalendar(options = {}) {
             case "annual":
                 reason = "closed-annual";
                 break;
+            case "recurring":
+                reason = day.value ? "open-recurring" : "closed-recurring";
+                break;
             case "holiday":
                 reason = "holiday";
                 break;
@@ -120,6 +134,8 @@ export function createCalendar(options = {}) {
             result.name = day.name;
         if (day.holiday !== undefined)
             result.holiday = day.holiday;
+        if (day.shiftedFrom !== undefined)
+            result.shiftedFrom = day.shiftedFrom;
         return Object.freeze(result);
     }
     const isOpen = (date) => schedule.valueOn(date);

package/dist/core/schedule.d.ts

@@ -4,8 +4,13 @@
  * 1 日の値は次の優先順位で決まる（上が優先）:
  *   1. dates   … 個別の日付・期間（配列で先に書いたものが優先）
  *   2. annual  … 毎年の月日・月日の期間（年をまたぐ期間も可。配列で先に書いたものが優先）
- *   3. 祝日     … holiday の規則（"weekday": 曜日どおり / { sameAs: 曜日 }: その曜日の値 / { value }: 指定の値）
- *   4. weekly  … 曜日ごとの値
+ *   3. recurring（onHolidayRule: "over-holiday"）… 祝日でも当てはめる繰り返しの規則
+ *   4. 祝日     … holiday の規則（"weekday": 曜日どおり / { sameAs: 曜日 }: その曜日の値 / { value }: 指定の値）
+ *   5. recurring（"under-holiday"・"after-holiday" の振替先）… 繰り返しの規則（配列で先に書いたものが優先）
+ *   6. weekly  … 曜日ごとの値
+ *
+ * "under-holiday" の規則は、祝日の扱いが "weekday"（曜日どおり）なら祝日にも当てはまる。
+ * "after-holiday" の規則は、祝日には当てはめず、その日以降で最初の祝日でない日に当てはめる（振替）
  *
  * 営業日カレンダー（createCalendar）は、このスケジュールの真偽値版として作られている。
  */
@@ -14,10 +19,10 @@ import { IssueCollector } from "./errors.ts";
 import { type DateInput } from "./input.ts";
 import type { Holiday, HolidayProvider } from "./types.ts";
 /**
- * 祝日の値の決め方。
+ * 祝日の値の決め方（スケジュールの holiday の設定）。
  * @public
  */
-export type HolidayRule<T> = 
+export type HolidayValueRule<T> = 
 /** 祝日を考えず、曜日の値を使う */
 "weekday"
 /** 指定した曜日の値を使う（例: 祝日は日曜日の営業時間） */
@@ -28,6 +33,80 @@ export type HolidayRule<T> =
  | {
     readonly value: T;
 };
+/**
+ * HolidayValueRule の旧名。繰り返しの規則の onHolidayRule と紛れないよう改名した。
+ * @deprecated HolidayValueRule を使うこと。次以降のマイナー版で削除する
+ * @public
+ */
+export type HolidayRule<T> = HolidayValueRule<T>;
+/**
+ * 月の第 n 回目（1〜5）。-1 は最終（その月の最後のその曜日）。
+ * @public
+ */
+export type Nth = 1 | 2 | 3 | 4 | 5 | -1;
+/**
+ * 月の日（1〜31）。-1 は末日。
+ * @public
+ */
+export type DayOfMonth = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | 31 | -1;
+/**
+ * 月（1〜12）。
+ * @public
+ */
+export type Month = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12;
+/**
+ * 繰り返しの規則が祝日に当たったときの扱い。
+ * - "under-holiday": 祝日の下。祝日の扱いに従う（既定）
+ * - "over-holiday": 祝日の上。祝日でも当てはめる
+ * - "after-holiday": 祝日の後。祝日には当てはめず、祝日でない翌日に振り替える
+ * @public
+ */
+export type OnHolidayRule = "under-holiday" | "over-holiday" | "after-holiday";
+/**
+ * 曜日の繰り返し。nth を省略すると毎週、指定すると月の第 n 回目（例: 第 3 水曜日）。
+ * @public
+ */
+export interface WeekdayPattern {
+    readonly weekday: Weekday;
+    /** 月の第 n 回目（その月で n 回目のその曜日。1〜7 日が第 1）。配列で複数指定できる */
+    readonly nth?: Nth | readonly Nth[];
+    /** 当てはめる月（省略時はすべての月） */
+    readonly months?: readonly Month[];
+    readonly day?: never;
+}
+/**
+ * 毎月の日の繰り返し（例: 毎月 20 日、毎月末日）。その月にない日（2 月 30 日など）は当てはまらない。
+ * @public
+ */
+export interface DayOfMonthPattern {
+    /** 月の日（1〜31、-1 は末日）。配列で複数指定できる */
+    readonly day: DayOfMonth | readonly DayOfMonth[];
+    /** 当てはめる月（省略時はすべての月） */
+    readonly months?: readonly Month[];
+    readonly weekday?: never;
+    readonly nth?: never;
+}
+/**
+ * 繰り返しのパターン。
+ * @public
+ */
+export type RecurringPattern = WeekdayPattern | DayOfMonthPattern;
+/**
+ * 繰り返しの規則（営業日カレンダーの closedRecurring・openRecurring）。
+ * @public
+ */
+export type RecurringRule = RecurringPattern & {
+    readonly name?: string;
+    /** 祝日に当たったときの扱い（既定: "under-holiday"） */
+    readonly onHolidayRule?: OnHolidayRule;
+};
+/**
+ * 繰り返しの規則の値（スケジュールの recurring）。
+ * @public
+ */
+export type RecurringValue<T> = RecurringRule & {
+    readonly value: T;
+};
 /**
  * 毎年の月日 "MM-DD" の値。
  * @public
@@ -89,7 +168,9 @@ export interface ScheduleOptions<T, Kind extends string = string> extends Holida
     /** 曜日ごとの値（[日, 月, 火, 水, 木, 金, 土]） */
     readonly weekly: readonly [T, T, T, T, T, T, T];
     /** 祝日の値の決め方（既定: "weekday"） */
-    readonly holiday?: HolidayRule<T>;
+    readonly holiday?: HolidayValueRule<T>;
+    /** 繰り返しの規則（毎週・毎月の第 n 曜日・毎月の日）の値 */
+    readonly recurring?: readonly RecurringValue<T>[];
     /** 毎年の月日の値 */
     readonly annual?: readonly (AnnualValue<T> | AnnualRangeValue<T>)[];
     /** 個別の日付の値 */
@@ -99,7 +180,7 @@ export interface ScheduleOptions<T, Kind extends string = string> extends Holida
  * 値を決めた規則（既知の値）。
  * @public
  */
-export type KnownScheduleReason = "date" | "annual" | "holiday" | "weekday";
+export type KnownScheduleReason = "date" | "annual" | "recurring" | "holiday" | "weekday";
 /**
  * 値を決めた規則。将来の版で値が増えることがあるので、分岐では「その他」も扱うこと。
  * すべての値を網羅したことを型で確かめたい場合は KnownScheduleReason を使う。
@@ -116,10 +197,12 @@ export interface ScheduleDay<T, Kind extends string = string> {
     readonly value: T;
     /** 値を決めた規則 */
     readonly reason: ScheduleReason;
-    /** 値を決めた規則の名前（dates・annual の name、祝日なら祝日名） */
+    /** 値を決めた規則の名前（dates・annual・recurring の name、祝日なら祝日名） */
     readonly name?: string;
     /** その日が祝日なら祝日（holiday の規則に関係なく付く） */
     readonly holiday?: Holiday<Kind>;
+    /** 祝日から振り替えられた規則で値が決まった場合、振替の元の日付（onHolidayRule: "after-holiday"） */
+    readonly shiftedFrom?: DateString;
 }
 /**
  * 暦日と時刻（カレンダーのタイムゾーン）。
@@ -190,6 +273,24 @@ export interface AnnualRule<T> {
 export declare function compileDateRules<T>(c: IssueCollector, path: string, entries: unknown, valueOf: (entry: Record<string, unknown>, path: string) => T | undefined, allowString: boolean): DateRule<T>[];
 /** @internal 毎年の月日の規則を検証して取り込む（entry は "MM-DD"・{ date }・{ from, to }） */
 export declare function compileAnnualRules<T>(c: IssueCollector, path: string, entries: unknown, valueOf: (entry: Record<string, unknown>, path: string) => T | undefined, allowString: boolean): AnnualRule<T>[];
+/** @internal 繰り返しの規則（検証済み） */
+export interface RecurringRuleCompiled<T> {
+    /** 曜日の規則なら曜日、日の規則なら null */
+    readonly weekday: Weekday | null;
+    /** 第 n 回目の集合（null は毎週） */
+    readonly nth: ReadonlySet<number> | null;
+    /** 日の集合（曜日の規則では null） */
+    readonly days: ReadonlySet<number> | null;
+    /** 月の集合（null はすべての月） */
+    readonly months: ReadonlySet<number> | null;
+    readonly onHolidayRule: OnHolidayRule;
+    readonly value: T;
+    readonly name: string | undefined;
+}
+/** @internal 繰り返しの規則を検証して取り込む */
+export declare function compileRecurringRules<T>(c: IssueCollector, path: string, entries: unknown, valueOf: (entry: Record<string, unknown>, path: string) => T | undefined, keys: readonly string[]): RecurringRuleCompiled<T>[];
+/** @internal 繰り返しの規則がその日に当てはまるか（祝日かどうかは考えない） */
+export declare function matchRecurring(rule: RecurringRuleCompiled<unknown>, date: DateString): boolean;
 /** @internal 祝日の提供元とタイムゾーンの設定を検証した結果 */
 export interface HolidaySource<Kind extends string> {
     readonly providers: readonly HolidayProvider<Kind>[];
@@ -206,10 +307,13 @@ export declare function createHolidayLookup<Kind extends string>(source: Holiday
 export interface CompiledSchedule<T, Kind extends string> {
     readonly source: HolidaySource<Kind>;
     readonly weekly: readonly T[];
-    readonly holiday: HolidayRule<T>;
+    readonly holiday: HolidayValueRule<T>;
     readonly annual: readonly AnnualRule<T>[];
     readonly dates: readonly DateRule<T>[];
+    readonly recurring: readonly RecurringRuleCompiled<T>[];
 }
+/** @internal 繰り返しの規則の項目 */
+export declare const RECURRING_RULE_KEYS: string[];
 /** @internal スケジュールの設定を検証して取り込む（誤りは c に集める） */
 export declare function compileScheduleOptions<T, Kind extends string>(c: IssueCollector, options: unknown): CompiledSchedule<T, Kind> | undefined;
 /** @internal 検証済みの規則からスケジュールを作る */

package/dist/core/schedule.js

@@ -4,12 +4,17 @@
  * 1 日の値は次の優先順位で決まる（上が優先）:
  *   1. dates   … 個別の日付・期間（配列で先に書いたものが優先）
  *   2. annual  … 毎年の月日・月日の期間（年をまたぐ期間も可。配列で先に書いたものが優先）
- *   3. 祝日     … holiday の規則（"weekday": 曜日どおり / { sameAs: 曜日 }: その曜日の値 / { value }: 指定の値）
- *   4. weekly  … 曜日ごとの値
+ *   3. recurring（onHolidayRule: "over-holiday"）… 祝日でも当てはめる繰り返しの規則
+ *   4. 祝日     … holiday の規則（"weekday": 曜日どおり / { sameAs: 曜日 }: その曜日の値 / { value }: 指定の値）
+ *   5. recurring（"under-holiday"・"after-holiday" の振替先）… 繰り返しの規則（配列で先に書いたものが優先）
+ *   6. weekly  … 曜日ごとの値
+ *
+ * "under-holiday" の規則は、祝日の扱いが "weekday"（曜日どおり）なら祝日にも当てはまる。
+ * "after-holiday" の規則は、祝日には当てはめず、その日以降で最初の祝日でない日に当てはめる（振替）
  *
  * 営業日カレンダー（createCalendar）は、このスケジュールの真偽値版として作られている。
  */
-import { isValidDate, parseDate, toDayNumber, weekdayOf, } from "./date.js";
+import { addDays, daysInMonth, isValidDate, parseDate, toDayNumber, weekdayOf, } from "./date.js";
 import { checkUnknownKeys, IssueCollector, rangeError } from "./errors.js";
 import { instantToCivil, toCivil, toDateTimeParts, validateTimeZone, } from "./input.js";
 // ------------------------------------------------------------
@@ -138,6 +143,125 @@ export function compileAnnualRules(c, path, entries, valueOf, allowString) {
     });
     return rules;
 }
+const NTH_VALUES = [1, 2, 3, 4, 5, -1];
+const ON_HOLIDAY_RULES = [
+    "under-holiday",
+    "over-holiday",
+    "after-holiday",
+];
+const isDayOfMonth = (v) => v === -1 || (Number.isInteger(v) && v >= 1 && v <= 31);
+const isMonth = (v) => Number.isInteger(v) && v >= 1 && v <= 12;
+/** 単独の値または空でない配列を検証し、集合にする（誤りは c に記録して undefined） */
+function checkSet(c, path, raw, valid, expected) {
+    const list = Array.isArray(raw) ? raw : [raw];
+    if (list.length === 0 || !list.every(valid)) {
+        c.error("invalid-option", path, `must be ${expected}, or a non-empty array of them`);
+        return undefined;
+    }
+    return new Set(list);
+}
+/** @internal 繰り返しの規則を検証して取り込む */
+export function compileRecurringRules(c, path, entries, valueOf, keys) {
+    if (entries === undefined)
+        return [];
+    if (!Array.isArray(entries)) {
+        c.error("invalid-option", path, "must be an array");
+        return [];
+    }
+    const rules = [];
+    entries.forEach((entry, i) => {
+        const p = `${path}[${i}]`;
+        if (!isObject(entry)) {
+            c.error("invalid-option", p, "must be an object");
+            return;
+        }
+        checkUnknownKeys(c, p, entry, keys);
+        const value = valueOf(entry, p);
+        const name = checkName(c, p, entry["name"]);
+        const hasWeekday = "weekday" in entry;
+        const hasDay = "day" in entry;
+        if (hasWeekday === hasDay) {
+            c.error("invalid-option", p, 'must have either "weekday" or "day" (not both)');
+            return;
+        }
+        let ok = true;
+        let weekday = null;
+        let nth = null;
+        let days = null;
+        if (hasWeekday) {
+            if (isWeekday(entry["weekday"]))
+                weekday = entry["weekday"];
+            else {
+                c.error("invalid-weekday", `${p}.weekday`, "must be an integer from 0 (Sunday) to 6 (Saturday)");
+                ok = false;
+            }
+            if (entry["nth"] !== undefined) {
+                const set = checkSet(c, `${p}.nth`, entry["nth"], (v) => NTH_VALUES.includes(v), "1-5 or -1 (last)");
+                if (set)
+                    nth = set;
+                else
+                    ok = false;
+            }
+        }
+        else {
+            if ("nth" in entry) {
+                c.error("invalid-option", `${p}.nth`, '"nth" can be used only with "weekday"');
+                ok = false;
+            }
+            const set = checkSet(c, `${p}.day`, entry["day"], isDayOfMonth, "1-31 or -1 (last day)");
+            if (set)
+                days = set;
+            else
+                ok = false;
+        }
+        let months = null;
+        if (entry["months"] !== undefined) {
+            if (!Array.isArray(entry["months"])) {
+                c.error("invalid-option", `${p}.months`, "must be a non-empty array of months (1-12)");
+                ok = false;
+            }
+            else {
+                const set = checkSet(c, `${p}.months`, entry["months"], isMonth, "a month (1-12)");
+                if (set)
+                    months = set;
+                else
+                    ok = false;
+            }
+        }
+        const onHoliday = entry["onHolidayRule"] ?? "under-holiday";
+        if (!ON_HOLIDAY_RULES.includes(onHoliday)) {
+            c.error("invalid-option", `${p}.onHolidayRule`, `must be one of ${ON_HOLIDAY_RULES.map((v) => `"${v}"`).join(", ")}`);
+            ok = false;
+        }
+        if (ok && value !== undefined) {
+            rules.push(Object.freeze({
+                weekday,
+                nth,
+                days,
+                months,
+                onHolidayRule: onHoliday,
+                value,
+                name,
+            }));
+        }
+    });
+    return rules;
+}
+/** @internal 繰り返しの規則がその日に当てはまるか（祝日かどうかは考えない） */
+export function matchRecurring(rule, date) {
+    const { year, month, day } = parseDate(date);
+    if (rule.months && !rule.months.has(month))
+        return false;
+    const dim = daysInMonth(year, month);
+    if (rule.weekday !== null) {
+        if (weekdayOf(date) !== rule.weekday)
+            return false;
+        if (rule.nth === null)
+            return true;
+        return rule.nth.has(Math.ceil(day / 7)) || (rule.nth.has(-1) && day + 7 > dim);
+    }
+    return rule.days.has(day) || (rule.days.has(-1) && day === dim);
+}
 /** 規則の value を取り出す（value が必須の規則用） */
 function requiredValue(c) {
     return (entry, path) => {
@@ -319,7 +443,10 @@ const SCHEDULE_OPTION_KEYS = [
     "holiday",
     "annual",
     "dates",
+    "recurring",
 ];
+/** @internal 繰り返しの規則の項目 */
+export const RECURRING_RULE_KEYS = ["weekday", "nth", "day", "months", "name", "onHolidayRule"];
 /** @internal スケジュールの設定を検証して取り込む（誤りは c に集める） */
 export function compileScheduleOptions(c, options) {
     if (!isObject(options)) {
@@ -355,8 +482,11 @@ export function compileScheduleOptions(c, options) {
     }
     const annual = compileAnnualRules(c, "annual", options["annual"], requiredValue(c), false);
     const dates = compileDateRules(c, "dates", options["dates"], requiredValue(c), false);
-    return { source, weekly, holiday, annual, dates };
+    const recurring = compileRecurringRules(c, "recurring", options["recurring"], requiredValue(c), [...RECURRING_RULE_KEYS, "value"]);
+    return { source, weekly, holiday, annual, dates, recurring };
 }
+/** 振替元をさかのぼる最大日数（祝日が続く日数の上限。2019 年の大型連休でも 10 日） */
+const MAX_HOLIDAY_RUN = 31;
 function matchAnnual(rule, monthDay) {
     return rule.from <= rule.to
         ? monthDay >= rule.from && monthDay <= rule.to
@@ -364,13 +494,37 @@ function matchAnnual(rule, monthDay) {
 }
 /** @internal 検証済みの規則からスケジュールを作る */
 export function buildSchedule(compiled) {
-    const { weekly, holiday: holidayRule, annual, dates } = compiled;
+    const { weekly, holiday: holidayRule, annual, dates, recurring } = compiled;
     const lookup = createHolidayLookup(compiled.source);
+    const hasShift = recurring.some((r) => r.onHolidayRule === "after-holiday");
+    /** 振替の判断に使う「祝日」か。提供元の対応年の外は祝日でないとみなす（振替元をさかのぼる途中で範囲を出る場合のため） */
+    function isHolidaySafe(date) {
+        try {
+            return lookup.holidayOn(date) !== undefined;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * "after-holiday" の規則が、date（祝日でない日）に振り替えられてきたか。
+     * date の前日からさかのぼって祝日が続く間に、規則に当たる日があれば、その日付を返す
+     */
+    function shiftedOrigin(rule, date) {
+        for (let k = 1; k <= MAX_HOLIDAY_RUN; k++) {
+            const prev = addDays(date, -k);
+            if (!isHolidaySafe(prev))
+                return undefined;
+            if (matchRecurring(rule, prev))
+                return prev;
+        }
+        return undefined;
+    }
     function info(date) {
         const dayNumber = toDayNumber(date);
         const weekday = weekdayOf(date);
         const holiday = lookup.holidayOn(date);
-        const make = (value, reason, name) => {
+        const make = (value, reason, name, shiftedFrom) => {
             const result = {
                 date,
                 weekday,
@@ -381,8 +535,11 @@ export function buildSchedule(compiled) {
                 result.name = name;
             if (holiday !== undefined)
                 result.holiday = holiday;
+            if (shiftedFrom !== undefined)
+                result.shiftedFrom = shiftedFrom;
             return Object.freeze(result);
         };
+        // 1. 個別の日付  2. 毎年の月日
         const byDate = dates.find((r) => dayNumber >= r.from && dayNumber <= r.to);
         if (byDate)
             return make(byDate.value, "date", byDate.name);
@@ -390,10 +547,34 @@ export function buildSchedule(compiled) {
         const byAnnual = annual.find((r) => matchAnnual(r, monthDay));
         if (byAnnual)
             return make(byAnnual.value, "annual", byAnnual.name);
-        if (holiday && holidayRule !== "weekday") {
-            const value = "sameAs" in holidayRule ? weekly[holidayRule.sameAs] : holidayRule.value;
-            return make(value, "holiday", holiday.name);
+        if (holiday) {
+            // 3. 祝日の上（"over-holiday"）
+            const over = recurring.find((r) => r.onHolidayRule === "over-holiday" && matchRecurring(r, date));
+            if (over)
+                return make(over.value, "recurring", over.name);
+            // 4. 祝日
+            if (holidayRule !== "weekday") {
+                const value = "sameAs" in holidayRule ? weekly[holidayRule.sameAs] : holidayRule.value;
+                return make(value, "holiday", holiday.name);
+            }
+            // 祝日の扱いが「曜日どおり」なら、祝日の下（"under-holiday"）の規則も当てはまる。
+            // "after-holiday" の規則は祝日には当てはめない（振り替える）
+            const under = recurring.find((r) => r.onHolidayRule === "under-holiday" && matchRecurring(r, date));
+            if (under)
+                return make(under.value, "recurring", under.name);
+            return make(weekly[weekday], "weekday", undefined);
+        }
+        // 5. 繰り返しの規則（祝日でない日。配列で先に書いたものが優先）。振替先も同じ段階で判定する
+        for (const rule of recurring) {
+            if (matchRecurring(rule, date))
+                return make(rule.value, "recurring", rule.name);
+            if (hasShift && rule.onHolidayRule === "after-holiday") {
+                const origin = shiftedOrigin(rule, date);
+                if (origin !== undefined)
+                    return make(rule.value, "recurring", rule.name, origin);
+            }
         }
+        // 6. 曜日
         return make(weekly[weekday], "weekday", undefined);
     }
     const schedule = {

package/dist/index.d.ts

@@ -8,7 +8,7 @@
  * 公開する名前と型は etc/api.md に記録し、pnpm check で意図しない変化を検出する。
  */
 export { createCalendar, type AnnualDate, type AnnualRange, type BusinessDayOptions, type Calendar, type CalendarOptions, type DateRange, type DayInfo, type DayReason, type HolidayPolicy, type KnownDayReason, type SpecificDate, } from "./core/calendar.ts";
-export { createSchedule, type AnnualRangeValue, type AnnualValue, type CivilDateTimeParts, type DateRangeValue, type DateValue, type HolidayLookup, type HolidayRule, type HolidaySourceOptions, type KnownScheduleReason, type Schedule, type ScheduleDay, type ScheduleOptions, type ScheduleReason, } from "./core/schedule.ts";
+export { createSchedule, type AnnualRangeValue, type AnnualValue, type CivilDateTimeParts, type DateRangeValue, type DateValue, type DayOfMonth, type DayOfMonthPattern, type HolidayLookup, type HolidayRule, type HolidaySourceOptions, type HolidayValueRule, type KnownScheduleReason, type Month, type Nth, type OnHolidayRule, type RecurringPattern, type RecurringRule, type RecurringValue, type Schedule, type ScheduleDay, type ScheduleOptions, type ScheduleReason, type WeekdayPattern, } from "./core/schedule.ts";
 export { addDays, diffDays, isValidDate, weekdayOf, type DateString, type Weekday, } from "./core/date.ts";
 export { isBizdaysError, type ErrorCode, type KnownErrorCode } from "./core/errors.ts";
 export { toDateString, toDateTimeParts, type DateInput, type TemporalDateLike, type TemporalInstantLike, } from "./core/input.ts";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bizdays-toolkit",
-  "version": "0.3.1",
+  "version": "0.4.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. / 祝日と営業日のカレンダー（タイムゾーン対応・日本の祝日は内閣府データで全日照合）",
   "keywords": [
     "bizdays",
@@ -48,6 +48,7 @@
     "lint": "oxlint --deny-warnings src scripts test",
     "test": "node --test \"test/**/*.test.ts\"",
     "test:tz": "node scripts/test-tz.ts",
+    "bench": "node scripts/bench.ts",
     "fmt": "oxfmt",
     "fmt:check": "oxfmt --check",
     "check": "pnpm typecheck && pnpm lint && pnpm test && pnpm test:tz && pnpm build && pnpm fmt:check && node scripts/check-package.ts && node scripts/check-size.ts && node scripts/api-report.ts",