bizdays-toolkit 0.21.3 → 0.21.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
@@ -4,6 +4,21 @@
4
4
 
5
5
  ## [Unreleased]
6
6
 
7
+ ## [0.21.4] - 2026-10-26
8
+
9
+ ### Changed
10
+
11
+ - 公開する `dist` の `.js` からコメントを除いた(`tsc --removeComments`)。型定義(`.d.ts`)の TSDoc はこれまでどおり残すので、エディターの説明は変わらない。コメントは保守する人のためのもので、利用者には型定義の TSDoc だけが要る。`dist` の `.js` の gzip が全体で約 48 KB から約 28 KB に減った(エントリーごとは下の「開発」)。動作は変わらない(`data-compare` で前の版と祝日データの差分がないこと、テスト・README のコード例・公開物の互換性の確認が通ることを確かめた)。README の minify + gzip のサイズは minify でコメントが消えるので変わらない
12
+ - 型定義に出るコメント(TSDoc)の、現状に追いついていない記述を、国の列挙や件数を書かない形で直した。`Holiday.names` の「同梱の提供元(日本)は持たない」(Wales は持つ)を「同梱の提供元は、公式の出典がある言語の名称だけを付ける」に、`KnownSgHolidayKey` の「11 の祝日に 1 つずつ」(key は 10 種類)を「毎年の祝日に 1 つずつ(旧正月の 2 日は同じ key)」に、`bizdays-toolkit/provider` の「同梱の 3 つの提供元」(フランスが加わった)を「振替のある同梱の提供元」に、`easterSunday` の「英国の祝日の計算に使い」(フランスも使う)を「復活祭から日数で決まる祝日の計算に使い」にした
13
+ - `docs/decisions.md`: 52 番(コメントと文書の参照の検査、コメントに書くことと書かないこと、`.js` からコメントを除くこと、取り込み時の重点確認)を追加した。34 番の「決めたのは 0 番」を「0 番目のカレンダー」にした(決定の番号と紛れないように)
14
+ - `RELEASING.md`: 「品質の確認」に参照の検査とコメントの書き方の規則を、「ビルドと整形」にコメントを除くビルドを足した。ハートビートの説明の「4 つの照合」を「すべての照合」にした
15
+
16
+ ### 開発
17
+
18
+ - `pnpm check`(`scripts/check-package.ts`)に、コメントと文書の参照の検査を足した(decisions.md の 52 番)。今の状態を書いたファイルに書いたファイルのパス(`scripts/…`・`docs/…` など)が実在すること、すべての文書の「decisions.md の N 番」の N が決定の文書にあること。0.21.3 に当てると `scripts/bundled-providers.ts` のコメントの誤り(実在しない `scripts/check-docs.ts`)を検出する
19
+ - スクリプト・ワークフロー・テスト・`src` のコメント(型定義に出る TSDoc を含む)から、決定の文書と重複する理由の説明、版の経緯(「0.18.0 で追加」など)、利用元の一覧、変わりうる事実(検証のフィクスチャの一覧・TypeScript や Node.js の版の一覧・照合する国の一覧や数など)を削り、何をするか・使い方・決定の文書の番号だけを残した(52 番)
20
+ - サイズの上限(`size-limits.json`)を、コメントを除いた `.js` の実測に合わせて下げた(上限を下げるだけなので理由の記載は要らないが、記録として書く)。ルート 26,500 → 16,500(測定 15,438)、`./jp` 29,500 → 19,000(測定 17,654)、`./uk` 9,000 → 5,000(測定 4,402)、`./sg` 6,000 → 3,500(測定 3,079)、`./fr` 6,500 → 3,000(測定 2,707)、`./diagnose` 35,500 → 22,000(測定 20,648)、`./provider` 6,500 → 3,500(測定 3,111)(gzip)
21
+
7
22
  ## [0.21.3] - 2026-10-26
8
23
 
9
24
  ### Changed
@@ -600,7 +615,8 @@
600
615
 
601
616
  - 日本: 2026 年 2 月の官報(2027 年の春分・秋分の日)まで反映(`dataVersion: "2026-02"`、`confirmedThrough: 2027`)
602
617
 
603
- [Unreleased]: https://github.com/inohan77/bizdays-toolkit/compare/v0.21.3...HEAD
618
+ [Unreleased]: https://github.com/inohan77/bizdays-toolkit/compare/v0.21.4...HEAD
619
+ [0.21.4]: https://github.com/inohan77/bizdays-toolkit/compare/v0.21.3...v0.21.4
604
620
  [0.21.3]: https://github.com/inohan77/bizdays-toolkit/compare/v0.21.2...v0.21.3
605
621
  [0.21.2]: https://github.com/inohan77/bizdays-toolkit/compare/v0.21.1...v0.21.2
606
622
  [0.21.1]: https://github.com/inohan77/bizdays-toolkit/compare/v0.21.0...v0.21.1
@@ -154,7 +154,7 @@ export interface BusinessDayOptions {
154
154
  /**
155
155
  * 締め時刻 "HH:mm"(カレンダーのタイムゾーン)。
156
156
  * 入力の時刻がこの時刻以降なら、その日は対象にしない。時刻を持たない入力(暦日の文字列・Temporal の PlainDate など)
157
- * と組み合わせると code: "invalid-argument" の Error(締め時刻が黙って無視されるのを防ぐ。0.15.0 から)
157
+ * と組み合わせると code: "invalid-argument" の Error(締め時刻が黙って無視されるのを防ぐため)
158
158
  */
159
159
  readonly cutoff?: string;
160
160
  }
@@ -1,23 +1,3 @@
1
- /**
2
- * 祝日と、会社・店舗の休業日を組み合わせた営業日カレンダー。
3
- *
4
- * 1 日の判定は次の優先順位で行う(上が優先):
5
- * 1. openDates … 臨時営業日(個別の日付・期間)
6
- * 2. closedDates … 臨時休業日(個別の日付・期間)
7
- * 3. closedAnnual … 毎年の休業日(月日・月日の期間。年をまたぐ期間も可)
8
- * 4. openRecurring・closedRecurring(onHolidayRule: "over-holiday")… 祝日でも当てはめる繰り返しの規則
9
- * 5. 祝日 … holidayPolicy に従う(closed: 休業 / open: 営業 / ignore: 判定に使わない)
10
- * 6. openRecurring・closedRecurring("under-holiday"・"after-holiday" の振替先)… 繰り返しの規則
11
- * 7. closedWeekdays … 定休日の曜日
12
- * 8. それ以外は営業日
13
- *
14
- * 繰り返しの規則は openRecurring が closedRecurring より優先。"after-holiday" の規則は、
15
- * 祝日には当てはめず、その日以降で最初の祝日でない日に当てはめる(振替)
16
- *
17
- * 内部では、営業日かどうか(真偽値)を返すスケジュール(createSchedule)として作っている。
18
- * 営業日の探索・調整・月の営業日などの機能は buildCalendar に切り出し、作成済みのカレンダーを
19
- * 合成する combineCalendars(両方が営業している日・どちらかが営業している日)でも同じ実装を使う。
20
- */
21
1
  import { addDays, daysInMonth, formatDate, fromDayNumber, toDayNumber, } from "./date.js";
22
2
  import { checkUnknownKeys, IssueCollector, plainError, rangeError } from "./errors.js";
23
3
  import { parseTimeOfDay, toCivil } from "./input.js";
@@ -37,7 +17,6 @@ const CALENDAR_OPTION_KEYS = [
37
17
  "holidayPolicy",
38
18
  "maxSearchDays",
39
19
  ];
40
- /** @internal 営業日カレンダーの設定を検証して取り込む(誤りは c に集める) */
41
20
  export function compileCalendarOptions(c, options) {
42
21
  if (typeof options !== "object" || options === null || Array.isArray(options)) {
43
22
  c.error("invalid-option", "", "options must be an object");
@@ -80,21 +59,12 @@ export function compileCalendarOptions(c, options) {
80
59
  weekly: Object.freeze([0, 1, 2, 3, 4, 5, 6].map((w) => !closedWeekdays.has(w))),
81
60
  holiday: holidayPolicy === "ignore" ? "weekday" : { value: holidayPolicy === "open" },
82
61
  annual,
83
- // 臨時営業日を先に並べて、臨時休業日より優先する
84
62
  dates: [...open, ...closed],
85
- // 繰り返しの営業日を先に並べて、繰り返しの休業日より優先する
86
63
  recurring: [...openRecurring, ...closedRecurring],
87
64
  },
88
65
  maxSearchDays: Number.isInteger(maxSearchDays) ? maxSearchDays : 3660,
89
66
  };
90
67
  }
91
- /**
92
- * 祝日と休業日の規則から営業日カレンダーを作る。
93
- *
94
- * 設定は作る時点で取り込まれるので、あとから元の配列を書き換えても結果は変わらない。
95
- * 設定の誤りは code 付きの RangeError になる。
96
- * @public
97
- */
98
68
  export function createCalendar(options = {}) {
99
69
  const c = new IssueCollector();
100
70
  const compiled = compileCalendarOptions(c, options);
@@ -107,14 +77,8 @@ export function createCalendar(options = {}) {
107
77
  };
108
78
  return buildCalendar(schedule, (date) => schedule.valueOn(date), info, maxSearchDays);
109
79
  }
110
- /**
111
- * @internal スケジュールの 1 日分の結果(値は営業日か)を、営業日カレンダーの結果に変換する。
112
- * reason はスケジュールの reason と営業・休業の組み合わせで決まる。createCalendar の closedAnnual は休業だけなので
113
- * "open-annual" にはならないが、createCalendarFromSchedule では annual の値で営業になる日がある
114
- */
115
80
  function dayInfoFromScheduleDay(day, open) {
116
81
  let reason;
117
- // 内部では閉じた型(KnownScheduleReason)で分岐し、値が増えたときの対応漏れを型で検出する
118
82
  const known = day.reason;
119
83
  switch (known) {
120
84
  case "date":
@@ -143,7 +107,6 @@ function dayInfoFromScheduleDay(day, open) {
143
107
  businessDay: open,
144
108
  reason,
145
109
  };
146
- // 曜日で決まった日には名前を付けない(祝日名は holiday で分かる)
147
110
  if (day.name !== undefined && day.reason !== "weekday")
148
111
  result.name = day.name;
149
112
  if (day.holiday !== undefined)
@@ -154,10 +117,6 @@ function dayInfoFromScheduleDay(day, open) {
154
117
  result.rulePath = day.rulePath;
155
118
  return Object.freeze(result);
156
119
  }
157
- /**
158
- * @internal 祝日を調べる機能と 1 日分の判定から、営業日カレンダーの機能(探索・調整・月の営業日・期日)を組み立てる。
159
- * createCalendar・combineCalendars・createCalendarFromSchedule で共用する
160
- */
161
120
  function buildCalendar(lookup, isOpen, info, maxSearchDays) {
162
121
  const dateOf = lookup.dateOf;
163
122
  function search(start, step) {
@@ -182,16 +141,12 @@ function buildCalendar(lookup, isOpen, info, maxSearchDays) {
182
141
  "modified-following",
183
142
  "modified-preceding",
184
143
  ];
185
- /** 月 m の、営業日に調整した締め日 D(m)(decisions.md の 41 番) */
186
144
  function closingDate(month, closingDay, options) {
187
145
  return adjustDate(dayOfMonth(month, closingDayIn(month, closingDay)), options);
188
146
  }
189
- /** 営業日を考慮した締め日で日付が属する月(date ≤ D(m) となる最小の m)。暦日の締めの月の前月から順に調べる */
190
147
  function closingMonthOf(date, closingDay, options) {
191
148
  checkClosingDay(closingDay);
192
149
  let month = parseMonth(calendarClosingMonth(date, closingDay));
193
- // D は月とともに単調に増える(減らない)ので、暦日の締めの月から、後ろへ(following で前月の締め日が
194
- // 長期休業を越えて当月以降に来た場合)、前へ(preceding で当月の締め日が date より前に来た場合)順に探す
195
150
  while (date <= closingDate(shiftMonth(month, -1), closingDay, options)) {
196
151
  month = shiftMonth(month, -1);
197
152
  }
@@ -216,7 +171,6 @@ function buildCalendar(lookup, isOpen, info, maxSearchDays) {
216
171
  const next = search(date, 1);
217
172
  if (next.startsWith(month))
218
173
  return next;
219
- // 同じ月に前営業日がなければ、月が変わっても翌営業日にする
220
174
  const previous = searchWithin(date, -1, month);
221
175
  return previous ?? next;
222
176
  }
@@ -231,7 +185,6 @@ function buildCalendar(lookup, isOpen, info, maxSearchDays) {
231
185
  throw rangeError("invalid-argument", `Unknown convention: ${String(convention)}`);
232
186
  }
233
187
  }
234
- /** 同じ月の中だけで営業日を探す(なければ undefined) */
235
188
  function searchWithin(start, step, month) {
236
189
  for (let date = start; date.startsWith(month); date = addDays(date, step)) {
237
190
  if (isOpen(date))
@@ -239,7 +192,6 @@ function buildCalendar(lookup, isOpen, info, maxSearchDays) {
239
192
  }
240
193
  return undefined;
241
194
  }
242
- /** 月の営業日(月初から順) */
243
195
  function businessDaysOfMonth(month) {
244
196
  const { year, month: m } = parseMonth(month);
245
197
  const result = [];
@@ -330,7 +282,6 @@ function buildCalendar(lookup, isOpen, info, maxSearchDays) {
330
282
  closingMonth: (input, closingDay, options) => formatMonth(closingMonthOf(dateOf(input), closingDay, options)),
331
283
  closingPeriod(input, closingDay, options) {
332
284
  checkClosingDay(closingDay);
333
- // "YYYY-MM" だけを月として扱い、それ以外(暦日・日時の文字列・Date・Temporal の値)は dateOf で暦日にする
334
285
  const isMonth = typeof input === "string" && /^\d{4}-\d{2}$/.test(input);
335
286
  const month = isMonth
336
287
  ? parseMonth(input)
@@ -358,19 +309,6 @@ const isCalendarLike = (v) => typeof v === "object" &&
358
309
  typeof v.isBusinessDay === "function" &&
359
310
  typeof v.timeZone === "string" &&
360
311
  Array.isArray(v.providers);
361
- /**
362
- * 作成済みの営業日カレンダーを合成する。"all" はすべてのカレンダーが営業している日、"any" はいずれかが
363
- * 営業している日を営業日とする。返すのは通常の営業日カレンダーで、営業日の加減算・調整・期日などが合成結果で動く。
364
- *
365
- * - dayInfo の reason・name・shiftedFrom・rulePath は、合成結果と同じ判定をした最初のカレンダーの結果で、
366
- * その番号を decidedBy で返す。入れ子の合成では、内側の番号まで含めた列を decidedByPath で返す。
367
- * holiday・isHoliday などは、すべてのカレンダーの祝日の提供元の和集合で判定する
368
- * - タイムゾーンはすべてのカレンダーで同じでなければならない(time-zone-conflict)。
369
- * 2 つ未満、同じカレンダーを 2 回渡した場合は invalid-argument
370
- * - 合成したカレンダーをさらに合成することもできる。規則の診断(diagnoseCalendar)の対象にはならないので、
371
- * 元のカレンダーの設定をそれぞれ診断する
372
- * @public
373
- */
374
312
  export function combineCalendars(calendars, options) {
375
313
  if (!Array.isArray(calendars) || calendars.length < 2) {
376
314
  throw rangeError("invalid-argument", "calendars must be an array of two or more calendars");
@@ -403,7 +341,6 @@ export function combineCalendars(calendars, options) {
403
341
  providers: Object.freeze(providers),
404
342
  timeZone: zones[0],
405
343
  outOfRange: calendars.every((c) => c.outOfRange === "ignore") ? "ignore" : "throw",
406
- // 未確定の祝日も同じ考え方: どれかが "throw" なら、そのカレンダーの判定が例外になるので合成の holiday も "throw"
407
344
  unconfirmedHolidays: calendars.some((c) => c.unconfirmedHolidays === "throw")
408
345
  ? "throw"
409
346
  : "accept",
@@ -414,7 +351,6 @@ export function combineCalendars(calendars, options) {
414
351
  function info(date) {
415
352
  const results = calendars.map((c) => c.dayInfo(date));
416
353
  const open = mode === "all" ? results.every((r) => r.businessDay) : results.some((r) => r.businessDay);
417
- // 合成結果と同じ判定をした最初のカレンダー("all" で休業なら最初に休みのもの、営業ならすべて営業なので 0 番)
418
354
  const decidedBy = results.findIndex((r) => r.businessDay === open);
419
355
  const base = results[decidedBy];
420
356
  const result = {
@@ -433,26 +369,11 @@ export function combineCalendars(calendars, options) {
433
369
  if (base.rulePath !== undefined)
434
370
  result.rulePath = base.rulePath;
435
371
  result.decidedBy = decidedBy;
436
- // 内側が合成したカレンダーなら、その経路の前に自分の番号を付ける(入れ子でなければ長さ 1)
437
372
  result.decidedByPath = Object.freeze([decidedBy, ...(base.decidedByPath ?? [])]);
438
373
  return Object.freeze(result);
439
374
  }
440
375
  return buildCalendar(lookup, isOpen, info, maxSearchDays);
441
376
  }
442
- /**
443
- * スケジュール(createSchedule)から営業日カレンダーを作る。isOpen が true を返す値の日を営業日とする。
444
- * 営業時間表のような日ごとの値が設定の正本で、営業日の計算(加減算・調整・期日など)も同じ設定から行いたいときに使う
445
- * (営業日カレンダーを別に書いて同期を取る必要がなくなる)。
446
- *
447
- * - isOpen は値だけで決まる純粋な関数であること(日付・時刻・外部の状態を見ない)。営業日の探索は isOpen を繰り返し呼ぶので、
448
- * 結果が変わる関数を渡すと探索の結果が呼ぶたびに変わる。日付で変えたい条件は、スケジュールの規則(dates・recurring)に書く
449
- * - dayInfo の reason は、スケジュールの reason と営業・休業の組み合わせ(date → "open-date"/"closed-date"、annual → "open-annual"/
450
- * "closed-annual"、recurring → "open-recurring"/"closed-recurring"、holiday → "holiday"、weekday → "regular"/"closed-weekday")。
451
- * name・holiday・shiftedFrom・rulePath はスケジュールの結果をそのまま引き継ぐ
452
- * - 祝日の判定(holiday・isHoliday など)・タイムゾーン・outOfRange はスケジュールのもの。規則の診断(diagnoseSchedule)は
453
- * スケジュールの設定に対して行う
454
- * @public
455
- */
456
377
  export function createCalendarFromSchedule(schedule, isOpen, options) {
457
378
  const info = infoOfSchedule(schedule);
458
379
  if (info === undefined) {
@@ -468,7 +389,6 @@ export function createCalendarFromSchedule(schedule, isOpen, options) {
468
389
  const open = (date) => isOpen(info(date).value) === true;
469
390
  return buildCalendar(schedule, open, (date) => {
470
391
  const day = info(date);
471
- // 変換は value を読まない(営業・休業は open で渡す)ので、boolean の値として扱ってよい
472
392
  return dayInfoFromScheduleDay(day, isOpen(day.value) === true);
473
393
  }, maxSearchDays);
474
394
  }
@@ -53,7 +53,7 @@ export declare function weekdayOf(date: DateString): Weekday;
53
53
  /** その月の第 n 何曜日(n は 1 始まり) */
54
54
  export declare function nthWeekdayOfMonth(year: number, month: number, weekday: Weekday, n: number): DateString;
55
55
  /**
56
- * 復活祭の日曜日(グレゴリオ暦。Anonymous Gregorian algorithm)。英国の祝日の計算に使い、提供元の実装者向けに
56
+ * 復活祭の日曜日(グレゴリオ暦。Anonymous Gregorian algorithm)。復活祭から日数で決まる祝日の計算に使い、提供元の実装者向けに
57
57
  * bizdays-toolkit/provider からも公開する(入力の検証はそちらで行う)
58
58
  */
59
59
  export declare function easterSunday(year: number): DateString;
package/dist/core/date.js CHANGED
@@ -1,14 +1,7 @@
1
- /**
2
- * 暦日(タイムゾーンを持たない日付)の計算。
3
- *
4
- * 日付は常に "YYYY-MM-DD" 文字列で扱い、内部では 1970-01-01 からの日数(day number)に
5
- * 変換して計算する。Date オブジェクトのローカル時刻は使わない。
6
- */
7
1
  import { rangeError } from "./errors.js";
8
2
  const DATE_RE = /^(\d{4})-(\d{2})-(\d{2})$/;
9
3
  const MS_PER_DAY = 86_400_000;
10
4
  const MONTH_DAYS = [31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
11
- /** 年月日に分解する。形式または暦として不正なら RangeError */
12
5
  export function parseDate(value) {
13
6
  const m = DATE_RE.exec(value);
14
7
  if (!m) {
@@ -22,10 +15,6 @@ export function parseDate(value) {
22
15
  }
23
16
  return { year, month, day };
24
17
  }
25
- /**
26
- * "YYYY-MM-DD" として正しい暦日か。
27
- * @public
28
- */
29
18
  export function isValidDate(value) {
30
19
  if (typeof value !== "string")
31
20
  return false;
@@ -37,7 +26,6 @@ export function isValidDate(value) {
37
26
  return false;
38
27
  }
39
28
  }
40
- /** 年月日から "YYYY-MM-DD" を作る(範囲外なら RangeError) */
41
29
  export function formatDate(year, month, day) {
42
30
  if (!Number.isInteger(year) || year < 1000 || year > 9999) {
43
31
  throw rangeError("out-of-range", `Year out of range (1000-9999): ${year}`);
@@ -46,11 +34,9 @@ export function formatDate(year, month, day) {
46
34
  parseDate(s);
47
35
  return s;
48
36
  }
49
- /** うるう年か */
50
37
  export function isLeapYear(year) {
51
38
  return (year % 4 === 0 && year % 100 !== 0) || year % 400 === 0;
52
39
  }
53
- /** その月の日数 */
54
40
  export function daysInMonth(year, month) {
55
41
  if (month === 2)
56
42
  return isLeapYear(year) ? 29 : 28;
@@ -59,50 +45,30 @@ export function daysInMonth(year, month) {
59
45
  throw rangeError("invalid-date", `Invalid month: ${month}`);
60
46
  return days;
61
47
  }
62
- /** 1970-01-01 からの日数 */
63
48
  export function toDayNumber(date) {
64
49
  const { year, month, day } = parseDate(date);
65
50
  return Date.UTC(year, month - 1, day) / MS_PER_DAY;
66
51
  }
67
- /** 1970-01-01 からの日数を "YYYY-MM-DD" に戻す */
68
52
  export function fromDayNumber(dayNumber) {
69
53
  const d = new Date(dayNumber * MS_PER_DAY);
70
54
  return formatDate(d.getUTCFullYear(), d.getUTCMonth() + 1, d.getUTCDate());
71
55
  }
72
- /**
73
- * n 日後(負なら前)の日付。
74
- * @public
75
- */
76
56
  export function addDays(date, days) {
77
57
  if (!Number.isInteger(days)) {
78
58
  throw rangeError("invalid-argument", `days must be an integer: ${days}`);
79
59
  }
80
60
  return fromDayNumber(toDayNumber(date) + days);
81
61
  }
82
- /**
83
- * from から to までの日数(to が後なら正)。
84
- * @public
85
- */
86
62
  export function diffDays(from, to) {
87
63
  return toDayNumber(to) - toDayNumber(from);
88
64
  }
89
- /**
90
- * 曜日(0 = 日曜日)。
91
- * @public
92
- */
93
65
  export function weekdayOf(date) {
94
- // 1970-01-01 は木曜日(4)
95
66
  return ((((toDayNumber(date) + 4) % 7) + 7) % 7);
96
67
  }
97
- /** その月の第 n 何曜日(n は 1 始まり) */
98
68
  export function nthWeekdayOfMonth(year, month, weekday, n) {
99
69
  const offset = (weekday - weekdayOf(formatDate(year, month, 1)) + 7) % 7;
100
70
  return formatDate(year, month, 1 + offset + (n - 1) * 7);
101
71
  }
102
- /**
103
- * 復活祭の日曜日(グレゴリオ暦。Anonymous Gregorian algorithm)。英国の祝日の計算に使い、提供元の実装者向けに
104
- * bizdays-toolkit/provider からも公開する(入力の検証はそちらで行う)
105
- */
106
72
  export function easterSunday(year) {
107
73
  const a = year % 19;
108
74
  const b = Math.floor(year / 100);