bizdays-toolkit 0.21.4 → 0.22.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -4,6 +4,31 @@
4
4
 
5
5
  ## [Unreleased]
6
6
 
7
+ ## [0.22.0] - 2026-10-27
8
+
9
+ ### Added
10
+
11
+ - 日単位の周期の規則 `{ cycle, anchor, positions }`(型 `CyclePattern`)。週や月にそろわない周期(4 勤 2 休のような交替制、10 日に 1 度の点検日)を、起点(`anchor`)を 1 日目として周期の中の何日目か(`positions`。1 始まり)で書く。`closedRecurring`・`openRecurring`・スケジュールの `recurring` で使え、`months`・有効期間・`name` を付けられる。`onHolidayRule` は `"under-holiday"`(既定)と `"over-holiday"`。`cycle` は 2 以上の整数、`positions` は 1〜`cycle` の重複のない配列で、空とすべての日は `invalid-option`。`"after-holiday"`・`anchor` の省略・ほかの形の項目との同居も `invalid-option`
12
+ - 祝日の翌日・祝前日の規則(`dayAfterHoliday`・`dayBeforeHoliday`)に `kinds`・`keys` を足した。隣の祝日(祝前日なら翌日の祝日、祝日の翌日なら前日の祝日)の種別・識別子で絞る(例: シンガポールの旧正月の前日は `{ dayBeforeHoliday: true, keys: ["chinese-new-year"] }`)。型 `DayAfterHolidayPattern`・`DayBeforeHolidayPattern` に既定値付きの型引数 `Kind` を足した
13
+ - 祝日の翌日・祝前日の規則に `skipWeekdays` を足した。祝日と書いた曜日が続く塊(祝日を 1 日以上含む)の前後の日に当てはまる(例: 月曜日の祝日の前の最終平日は `{ dayBeforeHoliday: true, skipWeekdays: [0, 6] }` で金曜日)。`kinds`・`keys` は塊の中でその日に最も近い祝日に当てる。すべての曜日は `invalid-option`
14
+ - 診断: 周期の規則どうしの `shadowed`(後の周期が先の周期の倍数で、後の規則のどの日も先の規則の日に当たるとき)、祝日の翌日・祝前日の規則どうしの `shadowed` に `kinds`・`keys` の包含を加えた。`redundant` の走査の範囲を、周期の規則の周期がそろう長さまで広げる(最長 200 年)
15
+
16
+ ### Changed
17
+
18
+ - 提供元向けの関数(`bizdays-toolkit/provider` の `easterSunday`・`nthWeekdayOfMonth`・`daysInMonth`・`isLeapYear`・`substituteDays` と型 `SubstituteDaysOptions`・`SubstituteDirection`)と、祝日の識別子の型(`KnownJapaneseHolidayKey`・`KnownUkHolidayKey`・`KnownSgHolidayKey`・`KnownFrHolidayKey`)を `@beta` から `@public` にした。公開してから(0.16.0〜0.20.0)形が変わっておらず、同梱の 4 か国の実装で使われ方が固まったため(`key` は 46 番で版をまたいで変えないと約束済み)
19
+ - エラーのメッセージ: 繰り返しの規則の形の数の誤り(`must have exactly one of …`)に `"cycle"` を、`kinds`・`keys`・`skipWeekdays` を使える規則の説明に祝日の翌日・祝前日を加えた(`code` と `path` は変わらない)
20
+ - README(英日)の minify + gzip のサイズを測り直した(0.22.0 で測定)
21
+ - `docs/decisions.md`: 53 番(日単位の周期の規則、祝日の翌日・祝前日の絞り込みと `skipWeekdays`、前への振替を足さない判断、`@public` への格上げ)を追加し、15・33・35・43・46・47 番に追記した
22
+ - `docs/migration.md`: 1.0.0 で削除する非推奨の API の一覧を足した
23
+
24
+ ### 移行
25
+
26
+ - 動作が変わる既存の API はない。祝日の翌日・祝前日の規則に `kinds`・`keys`・`skipWeekdays` を付けて `invalid-option` になることを確かめていたテストは、例外が出なくなるので失敗する。テストを書き換える(`docs/migration.md`)
27
+
28
+ ### 開発
29
+
30
+ - サイズの上限(`size-limits.json`)を上げた。ルート 16,500 → 17,500(測定 16,074)、`./jp` 19,000 → 19,500(測定 18,293)、`./diagnose` 22,000 → 23,000(測定 21,445)(gzip)。周期の規則の検証・判定、祝日の翌日・祝前日の絞り込みと塊の判定、診断の追加のため
31
+
7
32
  ## [0.21.4] - 2026-10-26
8
33
 
9
34
  ### Changed
@@ -615,7 +640,8 @@
615
640
 
616
641
  - 日本: 2026 年 2 月の官報(2027 年の春分・秋分の日)まで反映(`dataVersion: "2026-02"`、`confirmedThrough: 2027`)
617
642
 
618
- [Unreleased]: https://github.com/inohan77/bizdays-toolkit/compare/v0.21.4...HEAD
643
+ [Unreleased]: https://github.com/inohan77/bizdays-toolkit/compare/v0.22.0...HEAD
644
+ [0.22.0]: https://github.com/inohan77/bizdays-toolkit/compare/v0.21.4...v0.22.0
619
645
  [0.21.4]: https://github.com/inohan77/bizdays-toolkit/compare/v0.21.3...v0.21.4
620
646
  [0.21.3]: https://github.com/inohan77/bizdays-toolkit/compare/v0.21.2...v0.21.3
621
647
  [0.21.2]: https://github.com/inohan77/bizdays-toolkit/compare/v0.21.1...v0.21.2
package/README.md CHANGED
@@ -21,10 +21,10 @@ A business-day calendar that combines public holidays with company or store clos
21
21
 
22
22
  - **Holidays verified day by day against official data**: Japan (Cabinet Office, 1955 to the latest year in the Official Gazette), the UK (GOV.UK; for 1974–2011 the Royal Proclamations in The Gazette, and from 2000 the government lists of the time; England, Wales, Scotland and Northern Ireland), France (data.gouv.fr; metropolitan France and Alsace-Moselle, verified for 2006–2031) and Singapore (Ministry of Manpower on data.gov.sg, 2020 onwards). Every date is checked in the tests, differences are watched daily and shipped as patch versions
23
23
  - **Business-day arithmetic**: closed weekdays, annual closures (across the new year too), specific closed and open dates and holidays combine into "N business days later", "next business day after the cutoff" and month-based due dates with the four adjustment conventions used in finance
24
- - **Recurring rules**: "closed on the 3rd Wednesday", "every other Wednesday", "stocktaking on the last day of the month", "closed on Mondays, or the next weekday when Monday is a holiday", "the day after (or before) a holiday", each with its own behaviour on holidays and an optional effective period
24
+ - **Recurring rules**: "closed on the 3rd Wednesday", "every other Wednesday", "stocktaking on the last day of the month", "closed on Mondays, or the next weekday when Monday is a holiday", "the day after (or before) a holiday", "the last weekday before a bank holiday", shift cycles such as four days on and two days off, each with its own behaviour on holidays and an optional effective period
25
25
  - **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
26
26
  - **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
27
- - **Lightweight, zero dependencies, time-zone safe**: about 11.0 KB min+gzip (about 12.8 KB with Japanese holidays, about 13.2 KB with UK bank holidays, about 11.9 KB with French holidays, about 12.0 KB with Singapore holidays; measured for 0.21.3). 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
27
+ - **Lightweight, zero dependencies, time-zone safe**: about 11.5 KB min+gzip (about 13.2 KB with Japanese holidays, about 13.6 KB with UK bank holidays, about 12.4 KB with French holidays, about 12.4 KB with Singapore holidays; measured for 0.22.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
28
28
  - **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
29
29
 
30
30
  ## Installation
@@ -79,6 +79,7 @@ A calendar is built from the holiday provider and your closures: `closedWeekdays
79
79
  | --------------------------------------------------------- | -------------------------------------------------------------------------------- |
80
80
  | `{ weekday: 3, nth: 3 }` | The 3rd Wednesday (`nth` is 1–5 or -1 for the last; an array for several) |
81
81
  | `{ weekday: 3, interval: 2, anchor: "2026-01-07" }` | Every other Wednesday, counted from the anchor |
82
+ | `{ cycle: 6, anchor: "2026-01-05", positions: [5, 6] }` | Days 5 and 6 of every 6 days from the anchor (four days on, two days off) |
82
83
  | `{ day: 20 }`, `{ day: -1 }` | The 20th, the last day of the month |
83
84
  | `{ businessDayOfMonth: -1 }`, `{ businessDayOfMonth: 5 }` | The last business day of the month, the 5th business day |
84
85
  | `{ holiday: true, kinds: ["substitute"] }` | Holidays, optionally narrowed by kind or by key (`keys: ["vernal-equinox"]`) |
@@ -22,7 +22,7 @@
22
22
  * 判定の順番(個別の日付 → 毎年の月日 → 繰り返し(over)→ 祝日 → 繰り返し(under・振替先)→ 曜日)は
23
23
  * 固定なので、shadowed は同じ種類の規則どうしに限って調べる。種類をまたいで使われない規則は
24
24
  * redundant(取り除いても結果が変わらない)として見つかる。
25
- * 有効期間(effectiveFrom・effectiveTo)のある規則は期間の包含も、周期(interval)のある規則は周期の包含も
25
+ * 有効期間(effectiveFrom・effectiveTo)のある規則は期間の包含も、周期(interval・cycle)のある規則は周期の包含も
26
26
  * shadowed の条件にする。redundant の走査の範囲は、周期がそろう長さと、範囲の外にある有効期間まで広げる
27
27
  */
28
28
  import { type DateString } from "./date.ts";
@@ -45,11 +45,15 @@ const MAX_DATE_RULE_DAYS = 366 * MAX_WINDOW_YEARS;
45
45
  const gcd = (a, b) => (b === 0 ? a : gcd(b, a % b));
46
46
  const lcm = (a, b) => (a / gcd(a, b)) * b;
47
47
  function patternCycle(rules) {
48
- let weeks = 1;
49
- for (const rule of rules)
48
+ const max = 366 * MAX_WINDOW_YEARS;
49
+ let days = 7;
50
+ for (const rule of rules) {
50
51
  if (rule.interval !== null)
51
- weeks = lcm(weeks, rule.interval);
52
- return Math.min(lcm(PATTERN_DAYS, 7 * weeks), 366 * MAX_WINDOW_YEARS);
52
+ days = Math.min(lcm(days, 7 * rule.interval), max);
53
+ if (rule.cycle !== null)
54
+ days = Math.min(lcm(days, rule.cycle), max);
55
+ }
56
+ return Math.min(lcm(PATTERN_DAYS, days), max);
53
57
  }
54
58
  function clipYears(from, to) {
55
59
  if (to - from + 1 <= MAX_WINDOW_YEARS)
@@ -154,6 +158,15 @@ function intervalCovers(earlier, later) {
154
158
  return (later.interval % earlier.interval === 0 &&
155
159
  (later.anchor - earlier.anchor) % (7 * earlier.interval) === 0);
156
160
  }
161
+ function cycleCovers(earlier, later) {
162
+ const e = earlier.cycle;
163
+ if (later.cycle % e !== 0)
164
+ return false;
165
+ return [...later.positions].every((position) => {
166
+ const offset = (later.anchor + position - 1 - earlier.anchor) % e;
167
+ return earlier.positions.has(((offset + e) % e) + 1);
168
+ });
169
+ }
157
170
  function canCover(earlier, later) {
158
171
  switch (later.onHolidayRule) {
159
172
  case "over-holiday":
@@ -326,8 +339,8 @@ function analyze(c, compiled, isCalendar) {
326
339
  : rule.holiday
327
340
  ? "This rule matches no day: no holiday of the selected kinds, keys, weekdays and months within its effective period"
328
341
  : rule.dayAfterHoliday
329
- ? "This rule matches no day: no day after a holiday on the selected weekdays and months within its effective period"
330
- : "This rule matches no day: no day before a holiday on the selected weekdays and months within its effective period"
342
+ ? "This rule matches no day: no day after a holiday of the selected kinds and keys on the selected weekdays and months within its effective period"
343
+ : "This rule matches no day: no day before a holiday of the selected kinds and keys on the selected weekdays and months within its effective period"
331
344
  : businessDayBased
332
345
  ? "This rule matches no day: no month has that many business days of the counting basis in the selected months within its effective period"
333
346
  : rule.effectiveFrom === null && rule.effectiveTo === null
@@ -363,19 +376,24 @@ function analyze(c, compiled, isCalendar) {
363
376
  : rule.dayAfterHoliday || rule.dayBeforeHoliday
364
377
  ? r.dayAfterHoliday === rule.dayAfterHoliday &&
365
378
  r.dayBeforeHoliday === rule.dayBeforeHoliday &&
379
+ setCovers(r.kinds, rule.kinds) &&
380
+ setCovers(r.keys, rule.keys) &&
366
381
  setCovers(r.weekdays, rule.weekdays) &&
367
382
  setCovers(r.months, rule.months)
368
- : rule.businessDays !== null
369
- ? r.businessDays !== null &&
370
- r.calendar === rule.calendar &&
371
- setCovers(r.businessDays, rule.businessDays) &&
372
- setCovers(r.months, rule.months)
373
- : !r.holiday &&
374
- !r.dayAfterHoliday &&
375
- !r.dayBeforeHoliday &&
376
- r.businessDays === null &&
377
- intervalCovers(r, rule) &&
378
- isSubset(bits, recurringBits[i])));
383
+ : rule.cycle !== null
384
+ ? r.cycle !== null && cycleCovers(r, rule) && setCovers(r.months, rule.months)
385
+ : rule.businessDays !== null
386
+ ? r.businessDays !== null &&
387
+ r.calendar === rule.calendar &&
388
+ setCovers(r.businessDays, rule.businessDays) &&
389
+ setCovers(r.months, rule.months)
390
+ : !r.holiday &&
391
+ !r.dayAfterHoliday &&
392
+ !r.dayBeforeHoliday &&
393
+ r.businessDays === null &&
394
+ r.cycle === null &&
395
+ intervalCovers(r, rule) &&
396
+ isSubset(bits, recurringBits[i])));
379
397
  if (k < 0)
380
398
  return;
381
399
  unused.add(rule);
@@ -111,6 +111,8 @@ export interface WeekdayPattern {
111
111
  readonly weekdays?: never;
112
112
  readonly kinds?: never;
113
113
  readonly keys?: never;
114
+ readonly cycle?: never;
115
+ readonly positions?: never;
114
116
  }
115
117
  /**
116
118
  * 毎月の日の繰り返し(例: 毎月 20 日、毎月末日)。その月にない日(2 月 30 日など)は当てはまらない。
@@ -139,6 +141,8 @@ export interface DayOfMonthPattern {
139
141
  readonly weekdays?: never;
140
142
  readonly kinds?: never;
141
143
  readonly keys?: never;
144
+ readonly cycle?: never;
145
+ readonly positions?: never;
142
146
  }
143
147
  /**
144
148
  * 月の第 n 営業日(例: 月末最終営業日、第 5 営業日)。n は 1〜31、-1 は最後、-2 はその前。その月にない回は当てはまらない。
@@ -176,18 +180,30 @@ export interface BusinessDayOfMonthPattern {
176
180
  readonly kinds?: never;
177
181
  readonly keys?: never;
178
182
  readonly skipWeekdays?: never;
183
+ readonly cycle?: never;
184
+ readonly positions?: never;
179
185
  }
180
186
  /**
181
187
  * 祝日の翌日(祝日が続く場合は連休が明けた日。その日自身は祝日でない)。「祝日」は提供元の祝日だけ。
188
+ * kinds・keys で、前日の祝日(skipWeekdays があれば、飛ばした日の手前で最も近い祝日)の種別・識別子を絞れる。
182
189
  * 当てはまる日は祝日でないので、onHolidayRule は指定できない(指定すると invalid-option)。
183
190
  * @public
184
191
  */
185
- export interface DayAfterHolidayPattern {
192
+ export interface DayAfterHolidayPattern<Kind extends string = string> {
186
193
  readonly dayAfterHoliday: true;
187
194
  /** 当てはめる曜日(翌日の曜日。省略時はすべての曜日。例: [1, 2, 3, 4, 5] で土日に当たる翌日は除く) */
188
195
  readonly weekdays?: readonly Weekday[];
189
196
  /** 当てはめる月(翌日の月。省略時はすべての月) */
190
197
  readonly months?: readonly Month[];
198
+ /** 前日の祝日の種別(Holiday.kind。省略時はすべて) */
199
+ readonly kinds?: readonly Kind[];
200
+ /** 前日の祝日の識別子(Holiday.key。省略時はすべて。key を持たない祝日には当てはまらない) */
201
+ readonly keys?: readonly string[];
202
+ /**
203
+ * 祝日に加えて飛ばす曜日。祝日とこの曜日が続く塊(祝日を 1 日以上含む)が明けた日に当てはまる
204
+ * (例: 金曜日の祝日の翌平日は { dayAfterHoliday: true, skipWeekdays: [0, 6] } で月曜日)。すべての曜日は指定できない
205
+ */
206
+ readonly skipWeekdays?: readonly Weekday[];
191
207
  readonly weekday?: never;
192
208
  readonly nth?: never;
193
209
  readonly interval?: never;
@@ -197,22 +213,32 @@ export interface DayAfterHolidayPattern {
197
213
  readonly calendar?: never;
198
214
  readonly dayBeforeHoliday?: never;
199
215
  readonly holiday?: never;
200
- readonly kinds?: never;
201
- readonly keys?: never;
202
- readonly skipWeekdays?: never;
216
+ readonly cycle?: never;
217
+ readonly positions?: never;
203
218
  }
204
219
  /**
205
220
  * 祝前日(翌日が祝日で、その日自身は祝日でない日。連休なら連休の初日の前日)。「祝日」は提供元の祝日だけ。
206
221
  * 祝日の翌日(dayAfterHoliday)の鏡像で、祝前日料金・祝前日の営業時間の延長・締め時刻の繰り上げなどを規則として書く。
222
+ * kinds・keys で、翌日の祝日(skipWeekdays があれば、飛ばした日の先で最も近い祝日)の種別・識別子を絞れる
223
+ * (例: 旧正月の前日は { dayBeforeHoliday: true, keys: ["chinese-new-year"] })。
207
224
  * 当てはまる日は祝日でないので、onHolidayRule は指定できない(指定すると invalid-option)。
208
225
  * @public
209
226
  */
210
- export interface DayBeforeHolidayPattern {
227
+ export interface DayBeforeHolidayPattern<Kind extends string = string> {
211
228
  readonly dayBeforeHoliday: true;
212
229
  /** 当てはめる曜日(祝前日の曜日。省略時はすべての曜日。例: [1, 2, 3, 4, 5] で土日に当たる祝前日は除く) */
213
230
  readonly weekdays?: readonly Weekday[];
214
231
  /** 当てはめる月(祝前日の月。省略時はすべての月) */
215
232
  readonly months?: readonly Month[];
233
+ /** 翌日の祝日の種別(Holiday.kind。省略時はすべて) */
234
+ readonly kinds?: readonly Kind[];
235
+ /** 翌日の祝日の識別子(Holiday.key。省略時はすべて。key を持たない祝日には当てはまらない) */
236
+ readonly keys?: readonly string[];
237
+ /**
238
+ * 祝日に加えて飛ばす曜日。祝日とこの曜日が続く塊(祝日を 1 日以上含む)の前の日に当てはまる
239
+ * (例: 月曜日の祝日の前の最終平日は { dayBeforeHoliday: true, skipWeekdays: [0, 6] } で金曜日)。すべての曜日は指定できない
240
+ */
241
+ readonly skipWeekdays?: readonly Weekday[];
216
242
  readonly weekday?: never;
217
243
  readonly nth?: never;
218
244
  readonly interval?: never;
@@ -222,6 +248,36 @@ export interface DayBeforeHolidayPattern {
222
248
  readonly calendar?: never;
223
249
  readonly dayAfterHoliday?: never;
224
250
  readonly holiday?: never;
251
+ readonly cycle?: never;
252
+ readonly positions?: never;
253
+ }
254
+ /**
255
+ * 日単位の周期(例: 4 勤 2 休の交替制の休日、10 日に 1 度の定期点検)。週や月にそろわない周期を、起点からの日数で書く。
256
+ * 起点(anchor)を 1 日目として cycle 日ごとに繰り返し、positions に書いた何日目かに当てはまる
257
+ * (例: 4 勤 2 休の休日は { cycle: 6, anchor: "2026-01-05", positions: [5, 6] })。起点より前の日にも当てはまるので、
258
+ * 起点から始めるには effectiveFrom を併せて指定する。onHolidayRule は "under-holiday"(既定)と "over-holiday" を受け、
259
+ * "after-holiday" は invalid-option(周期の日を祝日の後ろへずらす意味がない)。
260
+ * @public
261
+ */
262
+ export interface CyclePattern {
263
+ /** 周期(日)。2 以上の整数 */
264
+ readonly cycle: number;
265
+ /** 周期の起点の日付 "YYYY-MM-DD"(1 日目) */
266
+ readonly anchor: DateString;
267
+ /** 当てはまる日(周期の中の何日目か。1〜cycle の重複のない整数の配列。すべての日は指定できない) */
268
+ readonly positions: readonly number[];
269
+ /** 当てはめる月(省略時はすべての月) */
270
+ readonly months?: readonly Month[];
271
+ readonly weekday?: never;
272
+ readonly nth?: never;
273
+ readonly interval?: never;
274
+ readonly day?: never;
275
+ readonly businessDayOfMonth?: never;
276
+ readonly calendar?: never;
277
+ readonly dayAfterHoliday?: never;
278
+ readonly dayBeforeHoliday?: never;
279
+ readonly holiday?: never;
280
+ readonly weekdays?: never;
225
281
  readonly kinds?: never;
226
282
  readonly keys?: never;
227
283
  readonly skipWeekdays?: never;
@@ -259,12 +315,14 @@ export interface HolidayPattern<Kind extends string = string> {
259
315
  readonly dayAfterHoliday?: never;
260
316
  readonly dayBeforeHoliday?: never;
261
317
  readonly skipWeekdays?: never;
318
+ readonly cycle?: never;
319
+ readonly positions?: never;
262
320
  }
263
321
  /**
264
322
  * 繰り返しのパターン。
265
323
  * @public
266
324
  */
267
- export type RecurringPattern<Kind extends string = string> = WeekdayPattern | DayOfMonthPattern | BusinessDayOfMonthPattern | DayAfterHolidayPattern | DayBeforeHolidayPattern | HolidayPattern<Kind>;
325
+ export type RecurringPattern<Kind extends string = string> = WeekdayPattern | DayOfMonthPattern | BusinessDayOfMonthPattern | DayAfterHolidayPattern<Kind> | DayBeforeHolidayPattern<Kind> | HolidayPattern<Kind> | CyclePattern;
268
326
  /**
269
327
  * 繰り返しの規則(営業日カレンダーの closedRecurring・openRecurring)。
270
328
  * @public
@@ -486,8 +544,12 @@ export interface RecurringRuleCompiled<T> extends CompiledPeriod {
486
544
  readonly nth: ReadonlySet<number> | null;
487
545
  /** 周期(週)。null は毎週・第 n 回目・日の規則 */
488
546
  readonly interval: number | null;
489
- /** 周期の起点(日数)。interval が null なら null */
547
+ /** 周期の起点(日数)。interval・cycle が null なら null */
490
548
  readonly anchor: number | null;
549
+ /** 日単位の周期(日)。周期の規則以外では null */
550
+ readonly cycle: number | null;
551
+ /** 周期の中で当てはまる日(1 始まり)。周期の規則以外では null */
552
+ readonly positions: ReadonlySet<number> | null;
491
553
  /** 日の集合(曜日の規則では null) */
492
554
  readonly days: ReadonlySet<number> | null;
493
555
  /** 第 n 営業日の集合(第 n 営業日の規則以外では null) */
@@ -496,7 +558,7 @@ export interface RecurringRuleCompiled<T> extends CompiledPeriod {
496
558
  readonly basis: BasisOfMonth | null;
497
559
  /** basis の元のカレンダー(診断で同じ基準かを比べるため。basis が null なら null) */
498
560
  readonly calendar: Calendar | null;
499
- /** "after-holiday" の振替で、祝日に加えて飛ばす曜日(null はなし) */
561
+ /** "after-holiday" の振替と、祝日の翌日・祝前日の塊で、祝日に加えて飛ばす曜日(null はなし) */
500
562
  readonly skipWeekdays: ReadonlySet<number> | null;
501
563
  /** 祝日の翌日の規則か */
502
564
  readonly dayAfterHoliday: boolean;
@@ -504,9 +566,9 @@ export interface RecurringRuleCompiled<T> extends CompiledPeriod {
504
566
  readonly dayBeforeHoliday: boolean;
505
567
  /** 祝日の規則か */
506
568
  readonly holiday: boolean;
507
- /** 祝日の規則で絞る種別(null はすべての祝日) */
569
+ /** 祝日・祝日の翌日・祝前日の規則で絞る種別(null はすべての祝日) */
508
570
  readonly kinds: ReadonlySet<string> | null;
509
- /** 祝日の規則で絞る識別子(null はすべての祝日) */
571
+ /** 祝日・祝日の翌日・祝前日の規則で絞る識別子(null はすべての祝日) */
510
572
  readonly keys: ReadonlySet<string> | null;
511
573
  /** 祝日・祝日の翌日・祝前日の規則で絞る曜日(null はすべての曜日) */
512
574
  readonly weekdays: ReadonlySet<number> | null;
@@ -203,14 +203,17 @@ export function compileRecurringRules(c, path, entries, valueOf, keys, context)
203
203
  const hasBefore = "dayBeforeHoliday" in entry;
204
204
  const hasHoliday = "holiday" in entry;
205
205
  const hasBusinessDay = "businessDayOfMonth" in entry;
206
+ const hasCycle = "cycle" in entry;
207
+ const holidayBased = hasHoliday || hasAfter || hasBefore;
206
208
  if (Number(hasWeekday) +
207
209
  Number(hasDay) +
208
210
  Number(hasBusinessDay) +
209
211
  Number(hasAfter) +
210
212
  Number(hasBefore) +
211
- Number(hasHoliday) !==
213
+ Number(hasHoliday) +
214
+ Number(hasCycle) !==
212
215
  1) {
213
- c.error("invalid-option", p, 'must have exactly one of "weekday", "day", "businessDayOfMonth", "dayAfterHoliday", "dayBeforeHoliday" or "holiday"');
216
+ c.error("invalid-option", p, 'must have exactly one of "weekday", "day", "businessDayOfMonth", "dayAfterHoliday", "dayBeforeHoliday", "holiday" or "cycle"');
214
217
  return;
215
218
  }
216
219
  let kinds = null;
@@ -223,6 +226,8 @@ export function compileRecurringRules(c, path, entries, valueOf, keys, context)
223
226
  let basisCalendar = null;
224
227
  let interval = null;
225
228
  let anchor = null;
229
+ let cycle = null;
230
+ let positions = null;
226
231
  const hasInterval = "interval" in entry;
227
232
  const hasAnchor = "anchor" in entry;
228
233
  if (hasWeekday) {
@@ -267,13 +272,63 @@ export function compileRecurringRules(c, path, entries, valueOf, keys, context)
267
272
  }
268
273
  }
269
274
  else {
270
- for (const key of ["nth", "interval", "anchor"]) {
275
+ for (const key of ["nth", "interval"]) {
271
276
  if (key in entry) {
272
277
  c.error("invalid-option", `${p}.${key}`, `"${key}" can be used only with "weekday"`);
273
278
  ok = false;
274
279
  }
275
280
  }
276
- if (hasDay) {
281
+ if (hasAnchor && !hasCycle) {
282
+ c.error("invalid-option", `${p}.anchor`, '"anchor" can be used only with "weekday" or "cycle"');
283
+ ok = false;
284
+ }
285
+ if (hasCycle) {
286
+ const length = entry["cycle"];
287
+ if (!Number.isInteger(length) || length < 2) {
288
+ c.error("invalid-option", `${p}.cycle`, "must be an integer of 2 or more (days)");
289
+ ok = false;
290
+ }
291
+ else
292
+ cycle = length;
293
+ if (!hasAnchor) {
294
+ c.error("invalid-option", p, '"anchor" is required with "cycle" (the first day of the cycle)');
295
+ ok = false;
296
+ }
297
+ else {
298
+ const a = checkDate(c, `${p}.anchor`, entry["anchor"]);
299
+ if (a === undefined)
300
+ ok = false;
301
+ else
302
+ anchor = a;
303
+ }
304
+ const raw = entry["positions"];
305
+ if (!Array.isArray(raw) || raw.length === 0) {
306
+ c.error("invalid-option", `${p}.positions`, "must be a non-empty array of days in the cycle (1 = the anchor day)");
307
+ ok = false;
308
+ }
309
+ else if (cycle !== null) {
310
+ const n = cycle;
311
+ if (!raw.every((v) => Number.isInteger(v) && v >= 1 && v <= n)) {
312
+ c.error("invalid-option", `${p}.positions`, `must be integers from 1 to ${n} (the cycle)`);
313
+ ok = false;
314
+ }
315
+ else if (new Set(raw).size !== raw.length) {
316
+ c.error("invalid-option", `${p}.positions`, "must not contain the same day twice");
317
+ ok = false;
318
+ }
319
+ else if (raw.length === n) {
320
+ c.error("invalid-option", `${p}.positions`, "must not contain every day of the cycle (the rule would match every day)");
321
+ ok = false;
322
+ }
323
+ else
324
+ positions = new Set(raw);
325
+ }
326
+ if (entry["onHolidayRule"] === "after-holiday") {
327
+ c.error("invalid-option", `${p}.onHolidayRule`, '"after-holiday" cannot be used with "cycle" (shifting a day of the cycle has no meaning; use "under-holiday" or "over-holiday")');
328
+ ok = false;
329
+ }
330
+ }
331
+ else if (hasDay) {
277
332
  const set = checkSet(c, `${p}.day`, entry["day"], isDayOfMonth, "1-31 or -1 (last day)");
278
333
  if (set)
279
334
  days = set;
@@ -320,11 +375,11 @@ export function compileRecurringRules(c, path, entries, valueOf, keys, context)
320
375
  : 'cannot be used with "holiday" (the rule applies on holidays; it is judged before holidayPolicy)');
321
376
  ok = false;
322
377
  }
323
- if (hasHoliday && entry["kinds"] !== undefined && !Array.isArray(entry["kinds"])) {
378
+ if (entry["kinds"] !== undefined && !Array.isArray(entry["kinds"])) {
324
379
  c.error("invalid-option", `${p}.kinds`, "must be a non-empty array of holiday kinds (Holiday.kind)");
325
380
  ok = false;
326
381
  }
327
- else if (hasHoliday && entry["kinds"] !== undefined) {
382
+ else if (entry["kinds"] !== undefined) {
328
383
  const set = checkSet(c, `${p}.kinds`, entry["kinds"], (v) => typeof v === "string" && v.length > 0, "a non-empty string (Holiday.kind)");
329
384
  if (set)
330
385
  kinds = set;
@@ -337,14 +392,18 @@ export function compileRecurringRules(c, path, entries, valueOf, keys, context)
337
392
  c.error("invalid-option", `${p}.calendar`, '"calendar" can be used only with "businessDayOfMonth"');
338
393
  ok = false;
339
394
  }
340
- if (!hasHoliday && "kinds" in entry) {
341
- c.error("invalid-option", `${p}.kinds`, '"kinds" can be used only with "holiday"');
395
+ if (!hasCycle && "positions" in entry) {
396
+ c.error("invalid-option", `${p}.positions`, '"positions" can be used only with "cycle"');
397
+ ok = false;
398
+ }
399
+ if (!holidayBased && "kinds" in entry) {
400
+ c.error("invalid-option", `${p}.kinds`, '"kinds" can be used only with "holiday", "dayAfterHoliday" or "dayBeforeHoliday"');
342
401
  ok = false;
343
402
  }
344
403
  let holidayKeys = null;
345
404
  if ("keys" in entry) {
346
- if (!hasHoliday) {
347
- c.error("invalid-option", `${p}.keys`, '"keys" can be used only with "holiday"');
405
+ if (!holidayBased) {
406
+ c.error("invalid-option", `${p}.keys`, '"keys" can be used only with "holiday", "dayAfterHoliday" or "dayBeforeHoliday"');
348
407
  ok = false;
349
408
  }
350
409
  else if (!Array.isArray(entry["keys"])) {
@@ -361,7 +420,7 @@ export function compileRecurringRules(c, path, entries, valueOf, keys, context)
361
420
  }
362
421
  let weekdays = null;
363
422
  if ("weekdays" in entry) {
364
- if (!hasHoliday && !hasAfter && !hasBefore) {
423
+ if (!holidayBased) {
365
424
  c.error("invalid-option", `${p}.weekdays`, '"weekdays" can be used only with "holiday", "dayAfterHoliday" or "dayBeforeHoliday"');
366
425
  ok = false;
367
426
  }
@@ -398,8 +457,10 @@ export function compileRecurringRules(c, path, entries, valueOf, keys, context)
398
457
  }
399
458
  let skipWeekdays = null;
400
459
  if ("skipWeekdays" in entry) {
401
- if (entry["onHolidayRule"] !== "after-holiday" || !(hasWeekday || hasDay)) {
402
- c.error("invalid-option", `${p}.skipWeekdays`, '"skipWeekdays" can be used only with onHolidayRule: "after-holiday" on a "weekday" or "day" rule');
460
+ const aroundHoliday = hasAfter || hasBefore;
461
+ if (!aroundHoliday &&
462
+ (entry["onHolidayRule"] !== "after-holiday" || !(hasWeekday || hasDay))) {
463
+ c.error("invalid-option", `${p}.skipWeekdays`, '"skipWeekdays" can be used only with "dayAfterHoliday", "dayBeforeHoliday", or onHolidayRule: "after-holiday" on a "weekday" or "day" rule');
403
464
  ok = false;
404
465
  }
405
466
  else if (!Array.isArray(entry["skipWeekdays"])) {
@@ -410,6 +471,10 @@ export function compileRecurringRules(c, path, entries, valueOf, keys, context)
410
471
  const set = checkSet(c, `${p}.skipWeekdays`, entry["skipWeekdays"], isWeekday, "a weekday (0 = Sunday to 6 = Saturday)");
411
472
  if (set === undefined)
412
473
  ok = false;
474
+ else if (set.size === 7) {
475
+ c.error("invalid-option", `${p}.skipWeekdays`, "cannot include every weekday (no day would be left)");
476
+ ok = false;
477
+ }
413
478
  else if (weekday !== null && set.has(weekday)) {
414
479
  c.error("invalid-option", `${p}.skipWeekdays`, `cannot include the rule's own weekday ${weekday} (the rule would be shifted every time)`);
415
480
  ok = false;
@@ -426,6 +491,8 @@ export function compileRecurringRules(c, path, entries, valueOf, keys, context)
426
491
  nth,
427
492
  interval,
428
493
  anchor,
494
+ cycle,
495
+ positions,
429
496
  days,
430
497
  businessDays,
431
498
  basis,
@@ -466,15 +533,29 @@ export function matchPattern(rule, date, holidayOf, basis) {
466
533
  return false;
467
534
  if (rule.weekdays && !rule.weekdays.has(weekdayOf(date)))
468
535
  return false;
536
+ const selected = (h) => (rule.kinds === null || rule.kinds.has(h.kind)) &&
537
+ (rule.keys === null || (h.key !== undefined && rule.keys.has(h.key)));
469
538
  if (rule.holiday) {
470
539
  const h = holidayOf(date);
471
- return (h !== undefined &&
472
- (rule.kinds === null || rule.kinds.has(h.kind)) &&
473
- (rule.keys === null || (h.key !== undefined && rule.keys.has(h.key))));
540
+ return h !== undefined && selected(h);
474
541
  }
475
- if (holidayOf(date) !== undefined)
542
+ const skip = rule.skipWeekdays;
543
+ if (holidayOf(date) !== undefined || skip?.has(weekdayOf(date)))
476
544
  return false;
477
- return holidayOf(addDays(date, rule.dayAfterHoliday ? -1 : 1)) !== undefined;
545
+ const step = rule.dayAfterHoliday ? -1 : 1;
546
+ for (let k = 1; k <= MAX_HOLIDAY_RUN; k++) {
547
+ const next = addDays(date, step * k);
548
+ const h = holidayOf(next);
549
+ if (h !== undefined)
550
+ return selected(h);
551
+ if (!skip?.has(weekdayOf(next)))
552
+ return false;
553
+ }
554
+ return false;
555
+ }
556
+ if (rule.cycle !== null) {
557
+ const offset = (toDayNumber(date) - rule.anchor) % rule.cycle;
558
+ return rule.positions.has(((offset + rule.cycle) % rule.cycle) + 1);
478
559
  }
479
560
  const dim = daysInMonth(year, month);
480
561
  if (rule.weekday !== null) {
@@ -750,6 +831,8 @@ export const RECURRING_RULE_KEYS = [
750
831
  "businessDayOfMonth",
751
832
  "calendar",
752
833
  "skipWeekdays",
834
+ "cycle",
835
+ "positions",
753
836
  "name",
754
837
  "onHolidayRule",
755
838
  ...PERIOD_KEYS,
@@ -31,7 +31,7 @@ export type FrHolidayKind = KnownFrHolidayKind | (string & {});
31
31
  /**
32
32
  * フランスの祝日の識別子(Holiday.key。既知の値)。英語名から 1 つずつ。
33
33
  * 規則の keys に書くときの補完に使う(型は開いているので他の文字列も通る)。
34
- * @beta
34
+ * @public
35
35
  */
36
36
  export type KnownFrHolidayKey = "new-year" | "easter-monday" | "labour-day" | "victory-in-europe" | "ascension" | "pentecost-monday" | "bastille" | "assumption" | "all-saints" | "armistice" | "christmas" | "good-friday" | "saint-stephens";
37
37
  /** @internal 地域(data.gouv.fr のゾーン) */
package/dist/index.d.ts CHANGED
@@ -8,7 +8,7 @@
8
8
  * 公開する名前と型は etc/api.md に記録し、pnpm check で意図しない変化を検出する。
9
9
  */
10
10
  export { combineCalendars, createCalendar, createCalendarFromSchedule, type AdjustOptions, type AnnualDate, type AnnualRange, type BusinessDayConvention, type BusinessDayOptions, type Calendar, type CalendarOptions, type CombineOptions, type DateRange, type DayInfo, type DayReason, type DueDateOptions, type HolidayPolicy, type KnownDayReason, type SpecificDate, } from "./core/calendar.ts";
11
- export { createSchedule, type AnnualRangeValue, type AnnualValue, type BusinessDayOfMonth, type BusinessDayOfMonthPattern, type CivilDateTimeParts, type DateRangeValue, type DateValue, type DayAfterHolidayPattern, type DayBeforeHolidayPattern, type DayOfMonth, type DayOfMonthPattern, type EffectivePeriod, type HolidayLookup, type HolidayPattern, 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";
11
+ export { createSchedule, type AnnualRangeValue, type AnnualValue, type BusinessDayOfMonth, type BusinessDayOfMonthPattern, type CivilDateTimeParts, type CyclePattern, type DateRangeValue, type DateValue, type DayAfterHolidayPattern, type DayBeforeHolidayPattern, type DayOfMonth, type DayOfMonthPattern, type EffectivePeriod, type HolidayLookup, type HolidayPattern, 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";
12
12
  export { addDays, diffDays, isValidDate, weekdayOf, type DateString, type Weekday, } from "./core/date.ts";
13
13
  export { closingMonth, closingPeriod, monthOf, type MonthString } from "./core/month.ts";
14
14
  export { isBizdaysError, type ErrorCode, type KnownErrorCode } from "./core/errors.ts";
@@ -34,7 +34,7 @@ export type JapaneseHolidayKind = KnownJapaneseHolidayKind | (string & {});
34
34
  * (天皇誕生日は 4/29・12/23・2/23 とも "emperors-birthday"、体育の日とスポーツの日は "sports")。
35
35
  * 振替休日は元の祝日の key を持ち、国民の休日と特例の休日は key を持たない。
36
36
  * 規則の keys に書くときの補完に使う(型は開いているので他の文字列も通る)。
37
- * @beta
37
+ * @public
38
38
  */
39
39
  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";
40
40
  /** @internal 対応年 */
@@ -8,7 +8,6 @@
8
8
  * 照合済みの結果と一致することをテストで確かめている(同梱の提供元の実装そのものは置き換えていない)。
9
9
  * 同梱の提供元の実装とは別に、アプリの本体に不要なものが入らないようサブパスに分けている。
10
10
  *
11
- * 公開する関数は @beta(マイナー版で変わりうる)。使われ方が固まったら @public にする。
12
11
  */
13
12
  import { type DateString, type Weekday } from "../core/date.ts";
14
13
  import { type Holiday } from "../core/types.ts";
@@ -16,34 +15,34 @@ import { type Holiday } from "../core/types.ts";
16
15
  * 復活祭の日曜日(グレゴリオ暦)。Good Friday は −2 日、Easter Monday は +1 日、Ascension は +39 日、
17
16
  * Whit Monday は +50 日、Corpus Christi は +60 日(ルートの addDays で求める)。
18
17
  * 年は 1000〜9999 の整数(それ以外は invalid-argument)。
19
- * @beta
18
+ * @public
20
19
  */
21
20
  export declare function easterSunday(year: number): DateString;
22
21
  /**
23
22
  * その月の第 n 何曜日(n は 1〜5、-1 は最後。曜日は 0 = 日曜日〜6 = 土曜日)。
24
23
  * 例: 1 月の第 3 月曜日は nthWeekdayOfMonth(2026, 1, 1, 3)、5 月の最終月曜日は nthWeekdayOfMonth(2026, 5, 1, -1)。
25
24
  * その月に n 回目のその曜日がないとき(第 5 回目)は invalid-argument。
26
- * @beta
25
+ * @public
27
26
  */
28
27
  export declare function nthWeekdayOfMonth(year: number, month: number, weekday: Weekday, n: number): DateString;
29
28
  /**
30
29
  * その月の日数(28〜31)。
31
- * @beta
30
+ * @public
32
31
  */
33
32
  export declare function daysInMonth(year: number, month: number): number;
34
33
  /**
35
34
  * うるう年か(グレゴリオ暦)。
36
- * @beta
35
+ * @public
37
36
  */
38
37
  export declare function isLeapYear(year: number): boolean;
39
38
  /**
40
39
  * 振替の向き。"next" はその日より後で最初の振替先、"previous" はその日より前で最初の振替先。
41
- * @beta
40
+ * @public
42
41
  */
43
42
  export type SubstituteDirection = "next" | "previous";
44
43
  /**
45
44
  * substituteDays の設定。
46
- * @beta
45
+ * @public
47
46
  */
48
47
  export interface SubstituteDaysOptions<Kind extends string> {
49
48
  /**
@@ -87,6 +86,6 @@ export interface SubstituteDaysOptions<Kind extends string> {
87
86
  * @example 日本の振替休日(日曜日の祝日を、その日の後で最も近い祝日でない日へ)
88
87
  * substituteDays(holidays, { rules: { 0: "next" }, kind: "substitute",
89
88
  * name: () => ({ name: "振替休日", nameEn: "Substitute Holiday" }) });
90
- * @beta
89
+ * @public
91
90
  */
92
91
  export declare function substituteDays<Kind extends string>(holidays: readonly Holiday<Kind>[], options: SubstituteDaysOptions<Kind>): Holiday<Kind>[];
@@ -33,7 +33,7 @@ export type SgHolidayKind = KnownSgHolidayKind | (string & {});
33
33
  * シンガポールの毎年の祝日の識別子(Holiday.key。既知の値)。毎年の祝日に 1 つずつ(旧正月の 2 日は同じ key)。
34
34
  * 振替日は元の祝日の key を持ち、臨時の祝日(Polling Day)は key を持たない。
35
35
  * 規則の keys に書くときの補完に使う(型は開いているので他の文字列も通る)。
36
- * @beta
36
+ * @public
37
37
  */
38
38
  export type KnownSgHolidayKey = "new-year" | "chinese-new-year" | "good-friday" | "labour-day" | "hari-raya-puasa" | "vesak" | "hari-raya-haji" | "national-day" | "deepavali" | "christmas";
39
39
  /** @internal 対応年(表のある年。それより後は予測できないので out-of-range) */
@@ -32,7 +32,7 @@ export type UkHolidayKind = KnownUkHolidayKind | (string & {});
32
32
  * 英国の毎年の bank holiday の識別子(Holiday.key。既知の値)。GOV.UK の区分名から付け、布告で日付が移った年も同じ値。
33
33
  * 振替日は元の祝日の key を持ち、臨時の祝日(special)は key を持たない。
34
34
  * 規則の keys に書くときの補完に使う(型は開いているので他の文字列も通る)。
35
- * @beta
35
+ * @public
36
36
  */
37
37
  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";
38
38
  /** @internal GOV.UK の区分 */
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "bizdays-toolkit",
3
- "version": "0.21.4",
3
+ "version": "0.22.0",
4
4
  "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 and The Gazette; French public holidays (metropole, Alsace-Moselle) verified against data.gouv.fr; Singapore public holidays verified against data.gov.sg. / 祝日と営業日のカレンダー(タイムゾーン対応・日本の祝日は内閣府、英国の bank holidays は GOV.UK と The Gazette、フランスの祝日は data.gouv.fr、シンガポールの祝日は data.gov.sg のデータで全日照合)",
5
5
  "keywords": [
6
6
  "bank-holidays",