bizdays-toolkit 0.31.3 → 0.31.4

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
@@ -6,6 +6,19 @@ Entries from 0.31.0 are in English. Earlier entries remain in Japanese (their **
6
6
 
7
7
  ## [Unreleased]
8
8
 
9
+ ## [0.31.4] - 2026-11-10
10
+
11
+ This version fixes calls that threw on days that do not affect their result, makes duplicate holiday providers count once as the design decisions say, and corrects type descriptions, messages and documents. Results of calls that did not throw do not change.
12
+
13
+ ### Fixed
14
+
15
+ - `adjust` with `"modified-following"` or `"modified-preceding"`, and `dueDate`, `closingMonth` and `closingPeriod` that use these conventions, looked at the next (or previous) month before searching the current month, so they threw on a day outside the month that cannot change the result: for example, `adjust("2028-12-30", { convention: "modified-following" })` on an English calendar with `unconfirmedHolidayPolicy: "throw"` threw `unconfirmed-holiday` for 1 January 2029, and on a Japanese calendar closed from 29 December to 3 January the same call for 2099-12-31 threw `out-of-range`; with a small `searchDayLimit`, a call threw `no-business-day` while searching a closed next month although the current month had a business day. They now search the current month first and cross the month only when it has no business day (design decisions 21). Returned dates are unchanged. A call that still throws may now throw a different code (`unconfirmed-holiday`, `out-of-range` or `no-business-day`), because the days are evaluated in a different order
16
+ - A calendar or a schedule given the same holiday provider object more than once (such as `[jp, jp]`) counted it twice, while the design decisions (24) say it is counted once: `providers` listed it twice and the option diagnostics reported the same provider error for each occurrence. Duplicates are now removed; diagnostics keep the position you wrote (`holidayProvider[2]` for the third entry), and when only one provider remains, as with `[jp, jp]`, they use `holidayProvider` as for a single provider. Holidays and business days are unchanged
17
+ - Error messages: `unconfirmed-holiday` said that "the result would depend on a predicted holiday", which is not always true (a search or an nth-business-day rule may look up a predicted holiday that does not change the result); it now says that the evaluation looked up a predicted holiday. The guide lists the days an nth-business-day rule evaluates
18
+ - Type descriptions: `unconfirmedHolidayPolicy` described when it matters with an outdated condition; it now refers to the guide. `ScheduleDayInfo.name` and `holiday` used option names from before 0.30.0. `outOfRangePolicy` and `unconfirmedHolidayPolicy` of `HolidayLookup` now say that a combined calendar shows a summary. `closedRecurringRules` and `recurringRules` listed only some of the rule forms; they now refer to the guide. `renameSubstitute` now says that `names` are kept even when the names are changed, as the design decisions (26) say
19
+ - Documentation: the provider guide and `withSubstituteDays` said only that a substitute day can move into the next year; with `"previous"` it can also move into the previous year, and the provider returns it as part of the year it falls in. The design decisions (2) now explain why the policies of a combined calendar have the closed type of the options
20
+ - Documentation: the type description of `combineCalendars` and the design decisions (18) still described the holidays of a combined calendar as the union of the providers; they now describe the current behaviour (each calendar is asked, and the holiday of the earlier calendar is taken). The design decisions (24) now state that the holidays of several providers given to one calendar are their union, keeping the holiday of the earlier provider on the same date. Results are unchanged
21
+
9
22
  ## [0.31.3] - 2026-11-09
10
23
 
11
24
  This version fixes results that did not keep what the guide, the type descriptions and the design decisions promise. The results of valid calendars and schedules do not change, except that combined calendars no longer throw on days when none of their calendars throws.
@@ -885,7 +898,8 @@ This version rebuilds the `redundant` diagnostic so that the reported rules can
885
898
 
886
899
  - 日本: 2026 年 2 月の官報(2027 年の春分・秋分の日)まで反映(`dataVersion: "2026-02"`、`confirmedThrough: 2027`)
887
900
 
888
- [Unreleased]: https://github.com/inohan77/bizdays-toolkit/compare/v0.31.3...HEAD
901
+ [Unreleased]: https://github.com/inohan77/bizdays-toolkit/compare/v0.31.4...HEAD
902
+ [0.31.4]: https://github.com/inohan77/bizdays-toolkit/compare/v0.31.3...v0.31.4
889
903
  [0.31.3]: https://github.com/inohan77/bizdays-toolkit/compare/v0.31.2...v0.31.3
890
904
  [0.31.2]: https://github.com/inohan77/bizdays-toolkit/compare/v0.31.1...v0.31.2
891
905
  [0.31.1]: https://github.com/inohan77/bizdays-toolkit/compare/v0.31.0...v0.31.1
@@ -64,7 +64,7 @@ export interface CalendarOptions<Kind extends string = string> extends HolidaySo
64
64
  /** 臨時営業日(ほかのすべての規則より優先) */
65
65
  readonly openDates?: readonly (SpecificDate | DateRange)[];
66
66
  /**
67
- * 繰り返しの休業日(毎週・隔週などの周期・毎月の第 n 曜日・毎月の日)。
67
+ * 繰り返しの休業日。書ける規則の形はガイドの「Recurring rules」の表(曜日・周期・月の日・第 n 営業日・祝日・祝日の前後など)。
68
68
  * 祝日に当たったときの扱いは規則ごとに holidayOverlapPolicy で指定する(既定: "under-holiday")。
69
69
  * 有効期間(effectiveFrom・effectiveTo)を付けると、期間の外では書かれていないのと同じに扱う
70
70
  */
@@ -290,8 +290,8 @@ export declare function createCalendar<Kind extends string = string>(options?: C
290
290
  *
291
291
  * - dayInfoOn の reason・name・shiftedFrom・optionPath は、合成結果と同じ判定をした最初のカレンダーの結果で、
292
292
  * その番号を decidedBy で返す。入れ子の合成では、内側の番号まで含めた列を decidedByPath で返す。
293
- * holiday・isHoliday・holidaysInYear などは、すべてのカレンダーの同じ参照を呼び、日付ごとに先のカレンダーの祝日を採る
294
- * (同じ提供元は 1 回だけ数え、同じ日付なら先のカレンダーの提供元の祝日)。どれかのカレンダーが投げる日だけ投げる
293
+ * holiday・isHoliday・holidaysInYear などは、すべてのカレンダーの同じ参照を呼び、日付ごとに先のカレンダー
294
+ * (その中では先の提供元)の祝日を採る。方針は各カレンダーのもので、どれかのカレンダーが投げる日だけ投げる
295
295
  * - タイムゾーンはすべてのカレンダーで同じでなければならない(time-zone-conflict)。
296
296
  * 2 つ未満、同じカレンダーを 2 回渡した場合は invalid-argument
297
297
  * - 合成したカレンダーをさらに合成することもできる。規則の診断(diagnoseCalendar)の対象にはならないので、
@@ -133,9 +133,12 @@ function buildCalendar(lookup, isOpen, info, searchDayLimit) {
133
133
  return date;
134
134
  }
135
135
  throw open
136
- ? rangeError("no-business-day", `No business day found within ${searchDayLimit} days from ${start}`)
136
+ ? noBusinessDay(start)
137
137
  : rangeError("no-closed-day", `No closed day found within ${searchDayLimit} days from ${start}`);
138
138
  }
139
+ function noBusinessDay(start) {
140
+ return rangeError("no-business-day", `No business day found within ${searchDayLimit} days from ${start}`);
141
+ }
139
142
  function countOpen(from, toExclusive) {
140
143
  let count = 0;
141
144
  for (let n = from; n < toExclusive; n++)
@@ -169,32 +172,28 @@ function buildCalendar(lookup, isOpen, info, searchDayLimit) {
169
172
  }
170
173
  if (isOpen(date))
171
174
  return date;
172
- const month = date.slice(0, 7);
173
175
  switch (convention) {
174
176
  case "following":
175
177
  return search(date, 1);
176
178
  case "preceding":
177
179
  return search(date, -1);
178
- case "modified-following": {
179
- const next = search(date, 1);
180
- if (next.startsWith(month))
181
- return next;
182
- const previous = searchWithin(date, -1, month);
183
- return previous ?? next;
184
- }
185
- case "modified-preceding": {
186
- const previous = search(date, -1);
187
- if (previous.startsWith(month))
188
- return previous;
189
- const next = searchWithin(date, 1, month);
190
- return next ?? previous;
191
- }
180
+ case "modified-following":
181
+ return searchInMonth(date, 1, true) ?? searchInMonth(date, -1, false) ?? search(date, 1);
182
+ case "modified-preceding":
183
+ return searchInMonth(date, -1, true) ?? searchInMonth(date, 1, false) ?? search(date, -1);
192
184
  default:
193
185
  throw rangeError("invalid-argument", `Unknown convention: ${String(convention)}`);
194
186
  }
195
187
  }
196
- function searchWithin(start, step, month) {
197
- for (let date = start; date.startsWith(month); date = addDays(date, step)) {
188
+ function searchInMonth(start, step, limited) {
189
+ const { year, month } = parseMonth(start.slice(0, 7));
190
+ const first = toDayNumber(formatDate(year, month, 1));
191
+ const last = first + lengthOfMonth(year, month) - 1;
192
+ let n = toDayNumber(start);
193
+ for (let i = 0; n >= first && n <= last; i++, n += step) {
194
+ if (limited && i >= searchDayLimit)
195
+ throw noBusinessDay(start);
196
+ const date = fromDayNumber(n);
198
197
  if (isOpen(date))
199
198
  return date;
200
199
  }
@@ -4,25 +4,14 @@
4
4
  * 設定を作るときと同じ検証(IssueCollector)で誤りと知らないキーを集め、誤りがなければ
5
5
  * 規則どうしの関係を調べる。例外は投げず、見つけた問題を配列で返す。
6
6
  *
7
- * - error … createCalendar・createSchedule で例外になる誤り(code は例外と同じ)
8
- * - warning … 作れるが、意図と違う可能性が高いもの
9
- * unknown-option … 知らないキー(作成時は無視される)。近い既知のキーがあれば message に候補を挙げる
10
- * shadowed … 同じ種類の先の規則に完全に覆われ、決して使われない(relatedPath に先の規則)
11
- * never-matches … 当てはまる日がない繰り返しの規則(2 月 30 日、有効期間の中に第 5 水曜日がない、提供元のない設定の祝日の翌日・祝前日、など)
12
- * out-of-range … 個別の日付、または規則の有効期間が祝日の提供元の対応年の外にある(relatedPath に提供元)
13
- * no-business-day … 営業日が 1 日もない設定(営業日カレンダーのみ)
14
- * - info … redundant: 取り除いても結果が変わらない規則・設定(判定に祝日を使わない設定の unconfirmedHolidayPolicy: "throw" を含む)。
15
- * 出た規則はまとめて取り除ける(逐次除去。relatedPath に代わりに決める規則、1 つに定まるときだけ。decisions.md の 31 番)
16
- * expired: 第 2 引数の asOf より前に終わった規則・日付(asOf を渡したときだけ)
17
- * counting-basis: 第 n 営業日の規則(businessDayOfMonth・businessDayOfWeek)の数える基準は繰り返しの規則を除くので、
18
- * 同じ設定の毎週の曜日の規則({ weekday })の曜日は営業日として数えられる(relatedPath にその規則)。
19
- * 有効期間が重なり、使われている曜日の規則ごとに 1 件
7
+ * 重さは error(createCalendar・createSchedule で例外になる誤り。code は例外と同じ)・warning(作れるが、意図と違う可能性が
8
+ * 高いもの)・info(知らせ)の 3 つ。診断のコードと重さの一覧はガイドの診断の表(docs/guide.md の「Option diagnostics」)、
9
+ * redundant の逐次除去と relatedPath は decisions.md の 31 番
20
10
  *
21
11
  * 未確定の祝日の扱い(unconfirmedHolidayPolicy)は診断では常に "accept" で評価する。診断は設定の形を調べるもので、
22
12
  * 祝日が確定しているかどうかは関係がなく、"throw" のまま評価すると例外を握りつぶして「当てはまらない」と誤判定するため
23
13
  *
24
- * 判定の順番(個別の日付 → 毎年の月日 → 繰り返し(over)→ 祝日 → 繰り返し(under・振替先)→ 曜日)は
25
- * 固定なので、shadowed は同じ種類の規則どうしに限って調べる。種類をまたいで使われない規則は
14
+ * 判定の順番は固定(decisions.md の 11 番)なので、shadowed は同じ種類の規則どうしに限って調べる。種類をまたいで使われない規則は
26
15
  * redundant(取り除いても結果が変わらない)として見つかる。
27
16
  * 有効期間(effectiveFrom・effectiveTo)のある規則は期間の包含も、周期(interval・cycle)のある規則は周期の包含も
28
17
  * shadowed の条件にする。redundant の走査の範囲は、周期がそろう長さと、範囲の外にある有効期間まで広げる
@@ -225,10 +225,13 @@ function without(compiled, rule, dropDates) {
225
225
  recurring: compiled.recurring.filter((r) => r !== rule),
226
226
  };
227
227
  }
228
+ const providerPath = (source, i) => source.providers.length === 1
229
+ ? "holidayProvider"
230
+ : `holidayProvider[${source.providerIndexes?.[i] ?? i}]`;
228
231
  function checkProviderData(c, source) {
229
232
  let ok = true;
230
233
  source.providers.forEach((provider, i) => {
231
- const path = source.providers.length === 1 ? "holidayProvider" : `holidayProvider[${i}]`;
234
+ const path = providerPath(source, i);
232
235
  const lookup = createHolidayLookup({
233
236
  ...source,
234
237
  providers: [provider],
@@ -405,7 +408,7 @@ function analyzeRules(c, compiled, isCalendar, unsure = () => false) {
405
408
  const { from, to } = p.supportedYears;
406
409
  if (fromYear >= from && toYear <= to)
407
410
  return;
408
- const related = source.providers.length === 1 ? "holidayProvider" : `holidayProvider[${i}]`;
411
+ const related = providerPath(source, i);
409
412
  c.warning("out-of-range", rule.path, `The date is outside the years supported by holiday provider ${p.id} (${from}-${to}); ` +
410
413
  (source.outOfRangePolicy === "throw"
411
414
  ? "looking up this date throws"
@@ -431,7 +434,7 @@ function analyzeRules(c, compiled, isCalendar, unsure = () => false) {
431
434
  c.warning("out-of-range", rule.path, `The effective period is outside the years supported by holiday provider ${p.id} (${from}-${to}); ` +
432
435
  (source.outOfRangePolicy === "throw"
433
436
  ? "looking up these dates throws, so this rule is never used"
434
- : "holidays are not considered for these dates"), source.providers.length === 1 ? "holidayProvider" : `holidayProvider[${i}]`);
437
+ : "holidays are not considered for these dates"), providerPath(source, i));
435
438
  });
436
439
  }
437
440
  const annualMatches = annual.map(annualBits);
@@ -465,7 +465,7 @@ export interface HolidaySourceOptions<Kind extends string = string> {
465
465
  * "throw" にすると、dayInfoOn・isBusinessDay に限らず、営業日の探索・調整・期日の計算の途中で評価した日や、祝日の翌日・祝前日の
466
466
  * 規則が見る隣の日を含め、祝日を引いた日が未確定の祝日なら unconfirmed-holiday の RangeError を投げる。
467
467
  * holidaysInYear・holidaysBetween は投げないので、影響する日の列挙に使える。
468
- * 判定に祝日を使う設定(holidayPolicy が "ignore" でない、または祝日に従属する規則がある)でだけ意味がある
468
+ * 判定が祝日に依存する設定でだけ意味がある(条件はガイドの「Unconfirmed holidays」。decisions.md の 17 番)
469
469
  */
470
470
  readonly unconfirmedHolidayPolicy?: "accept" | "throw";
471
471
  }
@@ -478,7 +478,7 @@ export interface ScheduleOptions<Value, Kind extends string = string> extends Ho
478
478
  readonly weekdayValues: readonly [Value, Value, Value, Value, Value, Value, Value];
479
479
  /** 祝日の値の決め方(既定: "ignore") */
480
480
  readonly holidayPolicy?: ScheduleHolidayPolicy<Value>;
481
- /** 繰り返しの規則(毎週・毎月の第 n 曜日・毎月の日)の値 */
481
+ /** 繰り返しの規則の値(書ける規則の形はガイドの「Recurring rules」の表) */
482
482
  readonly recurringRules?: readonly ScheduleRecurringRule<Value, Kind>[];
483
483
  /** 毎年の月日の値 */
484
484
  readonly annualDates?: readonly (ScheduleAnnualDate<Value> | ScheduleAnnualRange<Value>)[];
@@ -512,9 +512,9 @@ export interface ScheduleDayInfo<Value, Kind extends string = string> {
512
512
  readonly value: Value;
513
513
  /** 値を決めた規則 */
514
514
  readonly reason: ScheduleDayReason;
515
- /** 値を決めた規則の名前(dates・annual・recurring の name、祝日なら祝日名) */
515
+ /** 値を決めた規則の名前(dates・annualDates・recurringRules の name、祝日なら祝日名) */
516
516
  readonly name?: string;
517
- /** その日が祝日なら祝日(holiday の規則に関係なく付く) */
517
+ /** その日が祝日なら祝日(holidayPolicy に関係なく付く) */
518
518
  readonly holiday?: Holiday<Kind>;
519
519
  /** 祝日から振り替えられた規則で値が決まった場合、振替の元の日付(holidayOverlapPolicy: "after-holiday") */
520
520
  readonly shiftedFrom?: DateString;
@@ -536,9 +536,9 @@ export interface HolidayLookup<Kind extends string = string> {
536
536
  readonly timeZone: string;
537
537
  /** 祝日の提供元 */
538
538
  readonly providers: readonly HolidayProvider<Kind>[];
539
- /** 祝日の提供元の対応年を外れた日付の扱い(設定の outOfRangePolicy) */
539
+ /** 祝日の提供元の対応年を外れた日付の扱い(設定の値。合成したカレンダーでは構成カレンダーの要約で、どれかが "throw" なら "throw"。decisions.md の 17 番) */
540
540
  readonly outOfRangePolicy: "throw" | "ignore";
541
- /** 未確定の祝日に触れたときの扱い(設定の unconfirmedHolidayPolicy) */
541
+ /** 未確定の祝日に触れたときの扱い(設定の値。合成したカレンダーでは構成カレンダーの要約で、どれかが "throw" なら "throw"。decisions.md の 17 番) */
542
542
  readonly unconfirmedHolidayPolicy: "accept" | "throw";
543
543
  /** @deprecated 0.30.0 で outOfRangePolicy に改名した(同じ値)。1.0.0 で削除する */
544
544
  readonly outOfRange: "throw" | "ignore";
@@ -707,10 +707,13 @@ export function compileHolidaySource(c, options) {
707
707
  const raw = options["holidayProvider"];
708
708
  const list = raw === undefined ? [] : Array.isArray(raw) ? raw : [raw];
709
709
  const providers = [];
710
+ const providerIndexes = [];
710
711
  list.forEach((p, i) => {
711
712
  const path = Array.isArray(raw) ? `holidayProvider[${i}]` : "holidayProvider";
712
- if (validateProvider(c, path, p))
713
+ if (validateProvider(c, path, p) && !providers.includes(p)) {
713
714
  providers.push(p);
715
+ providerIndexes.push(i);
716
+ }
714
717
  });
715
718
  let timeZone = "UTC";
716
719
  if (options["timeZone"] !== undefined) {
@@ -738,6 +741,7 @@ export function compileHolidaySource(c, options) {
738
741
  }
739
742
  return {
740
743
  providers: Object.freeze(providers),
744
+ providerIndexes: Object.freeze(providerIndexes),
741
745
  timeZone,
742
746
  outOfRangePolicy: outOfRangePolicy === "ignore" ? "ignore" : "throw",
743
747
  unconfirmedHolidayPolicy: unconfirmed === "throw" ? "throw" : "accept",
@@ -833,7 +837,7 @@ export function createHolidayLookup(source) {
833
837
  const through = provider?.confirmedThrough === undefined
834
838
  ? ""
835
839
  : ` (${provider.id} is confirmed through ${provider.confirmedThrough})`;
836
- throw rangeError("unconfirmed-holiday", `${date} ${h.name} is not yet confirmed${through}; the result would depend on a predicted holiday`);
840
+ throw rangeError("unconfirmed-holiday", `${date} ${h.name} is not yet confirmed${through}; this evaluation looked up a predicted holiday`);
837
841
  }
838
842
  return h;
839
843
  }
@@ -54,7 +54,8 @@ export interface WithSubstituteDaysOptions<Kind extends string> {
54
54
  /** 振替日に付ける種別(Holiday.kind。例: "substitute"、"observed") */
55
55
  readonly kind: Kind;
56
56
  /**
57
- * 振替日の名称。省略時は元の祝日の name・nameEn(と names)を引き継ぐ(GOV.UK・MOM の流儀)。
57
+ * 振替日の名称(name・nameEn)。省略時は元の祝日のものを引き継ぐ(GOV.UK・MOM の流儀)。names は、名称を変えたときも
58
+ * 元の祝日のものを引き継ぐ(decisions.md の 26 番)。
58
59
  * 変えるなら元の祝日を受け取って返す関数で(例: 日本の「振替休日」、米国の "(observed)")
59
60
  */
60
61
  readonly renameSubstitute?: (holiday: Holiday<Kind>) => {
@@ -83,8 +84,8 @@ export interface WithSubstituteDaysOptions<Kind extends string> {
83
84
  * 振替日は元の祝日の key・names・confirmed を引き継ぎ、kind は options.kind、名称は省略時は元の祝日のもの。
84
85
  *
85
86
  * 入力は同じ年の祝日で、日付が有効・重複がないこと(誤りは invalid-argument・invalid-date・invalid-weekday の例外)。
86
- * 振替日は年をまたぐことがある(12 月 31 日が祝日の国で日曜日なら翌年の 1 月 1 日)。提供元の holidaysInYear は
87
- * その年の日付だけを返す契約なので、そうなる国では翌年の分として扱うこと。
87
+ * 振替日は前後の年に移ることがある(日曜日の 12 月 31 日の振替は翌年の 1 月 1 日、"previous" で土曜日の 1 月 1 日の振替は
88
+ * 前年の 12 月 31 日)。提供元の holidaysInYear はその年の日付だけを返す契約なので、振替日はその日が属する年の分として返すこと。
88
89
  * 国民の休日(2 つの祝日に挟まれた日)のような国に固有の規則は含まない。
89
90
  * 返す祝日はどれも凍結している(入力のまま返す祝日も、契約の項目だけを持つ複製)。
90
91
  *
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "bizdays-toolkit",
3
- "version": "0.31.3",
3
+ "version": "0.31.4",
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",