bizdays-toolkit 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -4,6 +4,35 @@
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-10-15
+
+1.0.0 に向けて、将来の機能追加で利用者のコードが壊れにくい作りにしました。機能の追加はありません。
+
+### Added
+
+- 例外に `code` を付けた（`invalid-date`・`invalid-range`・`no-business-day` など）。例外は従来どおり `RangeError`・`TypeError`・`Error` のインスタンス。`isBizdaysError()` で判定できる
+- `KnownDayReason`・`KnownScheduleReason`・`KnownJapaneseHolidayKind`・`KnownErrorCode`: 既知の値だけの閉じた型（網羅を型で確かめたい場合に使う）
+- 祝日の提供元（`HolidayProvider`）の形式を作る時点で、返したデータを年ごとに初めて使うときに検証する（誤りは `invalid-provider`・`invalid-provider-data`）
+
+### Changed
+
+- `DayReason`・`ScheduleReason`・`JapaneseHolidayKind` を「開いた型」にした（将来の版で値が増えても、利用者のコードがコンパイルエラーにならない）。値を列挙して分岐しているコードは「その他」の分岐が必要になる
+- 設定の誤りのメッセージに、設定の中の位置（例: `closedDates[1].date`）を入れた
+- 設定は作る時点で複製するようにした（作ったあとに元の配列を書き換えても、結果が変わらない）
+- 提供元が返した祝日は、契約の項目だけを持つ変更できないオブジェクトにして返す
+- 別の実行環境（iframe・`vm`）で作られた `Date` も受け付けるようにした
+
+### Removed
+
+- `vernalEquinoxDay`・`autumnalEquinoxDay`（`bizdays-toolkit/jp`）: 祝日の計算の内部の手段のため非公開にした
+- `nthWeekdayOfMonth`: 内部の関数のため非公開にした
+
+### 開発
+
+- 品質の確認を追加: タイムゾーン（`TZ`）を変えたテスト、性質のテスト、型のテスト、サイズの上限（`size-limits.json`）、公開 API のスナップショット（`etc/api.md`）
+- 互換性の約束と安定度の表示（`@public`・`@beta`）を RELEASING.md に、設計上の決定を `docs/decisions.md` に記載
+- `SECURITY.md` を追加（脆弱性の非公開の報告先）
+
 ## [0.2.0] - 2026-10-14
 
 ### Added
@@ -50,7 +79,8 @@
 
 - 日本: 2026 年 2 月の官報（2027 年の春分・秋分の日）まで反映（`dataVersion: "2026-02"`、`confirmedThrough: 2027`）
 
-[Unreleased]: https://github.com/inohan77/bizdays-toolkit/compare/v0.2.0...HEAD
+[Unreleased]: https://github.com/inohan77/bizdays-toolkit/compare/v0.3.0...HEAD
+[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
 [0.1.2]: https://github.com/inohan77/bizdays-toolkit/compare/v0.1.1...v0.1.2
 [0.1.1]: https://github.com/inohan77/bizdays-toolkit/compare/v0.1.0...v0.1.1

package/README.md

@@ -20,7 +20,7 @@
 - **日ごとの値（営業時間など）**: 「火曜定休、祝日は日曜の営業時間、元日は休業、大晦日は短縮営業」のように、曜日・祝日・特定日で変わる値を同じ規則で引けます
 - **営業日の計算**: 定休日の曜日・毎年の休業日（年末年始のような年をまたぐ期間も可）・臨時休業日・臨時営業日と祝日を組み合わせ、「N 営業日後」「締め時刻を過ぎたら翌営業日」などを計算します
 - **タイムゾーンを間違えない**: `Date` などの瞬間は、カレンダーのタイムゾーン（日本は `Asia/Tokyo`）で暦日に変換してから判定します。UTC で動くサーバーでも、日本時間 0〜9 時が前日扱いになりません
-- **軽量・依存ゼロ**: minify + gzip で約 4KB（日本の祝日込みで約 5.5KB）。ESM・型定義同梱・`sideEffects: false` で、Node.js・ブラウザー・Edge ランタイムで動作します
+- **軽量・依存ゼロ**: minify + gzip で約 5.5KB（日本の祝日込みで約 7KB）。ESM・型定義同梱・`sideEffects: false` で、Node.js・ブラウザー・Edge ランタイムで動作します
 - **他の国・地域に拡張できる**: 祝日の提供元はインターフェース（`HolidayProvider`）で差し替えられます。現在は日本のみ同梱しています
 
 [English](#english)
@@ -169,6 +169,24 @@ const calendar = createCalendar({ holidays: myCountry, closedWeekdays: [0, 6] })
 
 祝日の提供元の対応年（日本は 1955〜2099 年）を外れた日付を判定すると `RangeError` になります。祝日がない日として扱いたい場合は `outOfRange: "ignore"` を指定してください。
 
+### エラー
+
+設定や入力の誤りは、従来どおり `RangeError`・`TypeError` などの例外になり、`code` を持ちます。メッセージの文言は変わることがあるので、判定には `code` を使ってください。
+
+```ts
+import { createCalendar, isBizdaysError } from "bizdays-toolkit";
+
+try {
+  createCalendar({ closedDates: ["2026-12-32"] });
+} catch (error) {
+  if (isBizdaysError(error) && error.code === "invalid-date") {
+    // 日付の誤り（メッセージには設定の中の位置 "closedDates[0].date" が入る）
+  }
+}
+```
+
+主なコード: `invalid-date`・`invalid-month-day`・`invalid-time`・`invalid-range`・`invalid-weekday`・`invalid-time-zone`・`invalid-option`・`out-of-range`・`invalid-provider`・`invalid-provider-data`・`no-business-day`。将来の版でコードが増えることがあります。
+
 ## バージョン番号とデータの更新
 
 [Semantic Versioning](https://semver.org/lang/ja/) に従います。詳しくは [RELEASING.md](./RELEASING.md) を参照してください。
@@ -177,6 +195,7 @@ const calendar = createCalendar({ holidays: myCountry, closedWeekdays: [0, 6] })
 - 祝日の判定結果を固定したい場合は、版を完全一致で指定してください（例: `"bizdays-toolkit": "0.1.0"`）
 - 反映済みのデータは `dataVersion`（日本は反映済みの官報の年月）と `confirmedThrough` で確認できます
 - 1.0.0 までは、マイナー版で破壊的変更を行うことがあります
+- 判定の理由（`reason`）・祝日の種別（`kind`）・エラーコードは、将来の版で値が増えることがあります。値を列挙して分岐するときは「その他」も扱ってください（[RELEASING.md](./RELEASING.md) の「互換性の約束」）
 
 ## 出典
 
@@ -196,7 +215,7 @@ A business-day calendar that combines public holidays with company or store clos
 - **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
 - **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 4 KB min+gzip (about 5.5 KB with Japanese holidays), ESM, bundled types, `sideEffects: false`
+- **Lightweight, zero dependencies**: about 5.5 KB min+gzip (about 7 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

@@ -12,33 +12,53 @@
  * 内部では、営業日かどうか（真偽値）を返すスケジュール（createSchedule）として作っている。
  */
 import { type DateString, type Weekday } from "./date.ts";
+import { IssueCollector } from "./errors.ts";
 import { type DateInput } from "./input.ts";
-import { type HolidayLookup, type HolidaySourceOptions } from "./schedule.ts";
+import { type CompiledSchedule, type HolidayLookup, type HolidaySourceOptions } from "./schedule.ts";
 import type { Holiday } from "./types.ts";
-/** 祝日の扱い */
+/**
+ * 祝日の扱い。
+ * @public
+ */
 export type HolidayPolicy = "closed" | "open" | "ignore";
-/** 毎年の月日 "MM-DD"（名前付きも可） */
+/**
+ * 毎年の月日 "MM-DD"（名前付きも可）。
+ * @public
+ */
 export type AnnualDate = string | {
     readonly date: string;
     readonly name?: string;
 };
-/** 毎年の月日の期間（from > to なら年をまたぐ。例: 12-31 〜 01-03） */
+/**
+ * 毎年の月日の期間（from > to なら年をまたぐ。例: 12-31 〜 01-03）。
+ * @public
+ */
 export interface AnnualRange {
     readonly from: string;
     readonly to: string;
     readonly name?: string;
 }
-/** 個別の日付 "YYYY-MM-DD"（名前付きも可） */
+/**
+ * 個別の日付 "YYYY-MM-DD"（名前付きも可）。
+ * @public
+ */
 export type SpecificDate = DateString | {
     readonly date: DateString;
     readonly name?: string;
 };
-/** 個別の日付の期間（両端を含む） */
+/**
+ * 個別の日付の期間（両端を含む）。
+ * @public
+ */
 export interface DateRange {
     readonly from: DateString;
     readonly to: DateString;
     readonly name?: string;
 }
+/**
+ * 営業日カレンダーの設定。
+ * @public
+ */
 export interface CalendarOptions<Kind extends string = string> extends HolidaySourceOptions<Kind> {
     /** 定休日の曜日（0 = 日曜日） */
     readonly closedWeekdays?: readonly Weekday[];
@@ -53,9 +73,21 @@ export interface CalendarOptions<Kind extends string = string> extends HolidaySo
     /** 営業日を探すときに調べる最大日数（既定: 3660）。超えたら Error */
     readonly maxSearchDays?: number;
 }
-/** 営業・休業を決めた規則 */
-export type DayReason = "open-date" | "closed-date" | "closed-annual" | "holiday" | "closed-weekday" | "regular";
-/** 1 日分の判定結果 */
+/**
+ * 営業・休業を決めた規則（既知の値）。
+ * @public
+ */
+export type KnownDayReason = "open-date" | "closed-date" | "closed-annual" | "holiday" | "closed-weekday" | "regular";
+/**
+ * 営業・休業を決めた規則。将来の版で値が増えることがあるので、分岐では「その他」も扱うこと。
+ * すべての値を網羅したことを型で確かめたい場合は KnownDayReason を使う。
+ * @public
+ */
+export type DayReason = KnownDayReason | (string & {});
+/**
+ * 1 日分の判定結果。
+ * @public
+ */
 export interface DayInfo<Kind extends string = string> {
     readonly date: DateString;
     readonly weekday: Weekday;
@@ -67,6 +99,10 @@ export interface DayInfo<Kind extends string = string> {
     /** その日が祝日なら祝日（holidayPolicy に関係なく付く） */
     readonly holiday?: Holiday<Kind>;
 }
+/**
+ * 営業日を探すときのオプション。
+ * @public
+ */
 export interface BusinessDayOptions {
     /**
      * 締め時刻 "HH:mm"（カレンダーのタイムゾーン）。
@@ -74,6 +110,10 @@ export interface BusinessDayOptions {
      */
     readonly cutoff?: string;
 }
+/**
+ * 営業日カレンダー。
+ * @public
+ */
 export interface Calendar<Kind extends string = string> extends HolidayLookup<Kind> {
     /** 1 日分の判定結果（営業日か・理由・祝日） */
     dayInfo(input: DateInput): DayInfo<Kind>;
@@ -97,5 +137,18 @@ export interface Calendar<Kind extends string = string> extends HolidayLookup<Ki
     /** 期間内の営業日（両端を含む） */
     listBusinessDays(from: DateInput, to: DateInput): readonly DateString[];
 }
-/** 祝日と休業日の規則から営業日カレンダーを作る */
+interface CompiledCalendar<Kind extends string> {
+    readonly schedule: CompiledSchedule<boolean, Kind>;
+    readonly maxSearchDays: number;
+}
+/** @internal 営業日カレンダーの設定を検証して取り込む（誤りは c に集める） */
+export declare function compileCalendarOptions<Kind extends string>(c: IssueCollector, options: unknown): CompiledCalendar<Kind> | undefined;
+/**
+ * 祝日と休業日の規則から営業日カレンダーを作る。
+ *
+ * 設定は作る時点で取り込まれるので、あとから元の配列を書き換えても結果は変わらない。
+ * 設定の誤りは code 付きの RangeError になる。
+ * @public
+ */
 export declare function createCalendar<Kind extends string = string>(options?: CalendarOptions<Kind>): Calendar<Kind>;
+export {};

package/dist/core/calendar.js

@@ -12,59 +12,86 @@
  * 内部では、営業日かどうか（真偽値）を返すスケジュール（createSchedule）として作っている。
  */
 import { addDays, fromDayNumber, toDayNumber } from "./date.js";
+import { checkUnknownKeys, IssueCollector, plainError, rangeError } from "./errors.js";
 import { parseTimeOfDay, toCivil } from "./input.js";
-import { createSchedule, parseMonthDay, } from "./schedule.js";
-function toDateValues(entries, value) {
-    return (entries ?? []).map((e) => {
-        if (typeof e === "string")
-            return { date: e, value };
-        if ("date" in e)
-            return e.name === undefined ? { date: e.date, value } : { ...e, value };
-        return e.name === undefined ? { from: e.from, to: e.to, value } : { ...e, value };
-    });
-}
-/** 祝日と休業日の規則から営業日カレンダーを作る */
-export function createCalendar(options = {}) {
+import { buildSchedule, compileAnnualRules, compileDateRules, compileHolidaySource, isWeekday, } from "./schedule.js";
+const CALENDAR_OPTION_KEYS = [
+    "holidays",
+    "timeZone",
+    "outOfRange",
+    "closedWeekdays",
+    "closedAnnual",
+    "closedDates",
+    "openDates",
+    "holidayPolicy",
+    "maxSearchDays",
+];
+/** @internal 営業日カレンダーの設定を検証して取り込む（誤りは c に集める） */
+export function compileCalendarOptions(c, options) {
+    if (typeof options !== "object" || options === null || Array.isArray(options)) {
+        c.error("invalid-option", "", "options must be an object");
+        return undefined;
+    }
+    const o = options;
+    checkUnknownKeys(c, "", o, CALENDAR_OPTION_KEYS);
+    const source = compileHolidaySource(c, o);
     const closedWeekdays = new Set();
-    for (const w of options.closedWeekdays ?? []) {
-        if (!Number.isInteger(w) || w < 0 || w > 6)
-            throw new RangeError(`Invalid weekday: ${w}`);
-        closedWeekdays.add(w);
+    const rawWeekdays = o["closedWeekdays"];
+    if (rawWeekdays !== undefined) {
+        if (!Array.isArray(rawWeekdays)) {
+            c.error("invalid-option", "closedWeekdays", "must be an array");
+        }
+        else {
+            rawWeekdays.forEach((w, i) => {
+                if (isWeekday(w))
+                    closedWeekdays.add(w);
+                else
+                    c.error("invalid-weekday", `closedWeekdays[${i}]`, "must be an integer from 0 (Sunday) to 6 (Saturday)");
+            });
+        }
     }
-    const holidayPolicy = options.holidayPolicy ?? "closed";
-    if (!["closed", "open", "ignore"].includes(holidayPolicy)) {
-        throw new RangeError(`Invalid holidayPolicy: ${String(holidayPolicy)}`);
+    const holidayPolicy = o["holidayPolicy"] ?? "closed";
+    if (holidayPolicy !== "closed" && holidayPolicy !== "open" && holidayPolicy !== "ignore") {
+        c.error("invalid-option", "holidayPolicy", 'must be "closed", "open" or "ignore"');
     }
-    const maxSearchDays = options.maxSearchDays ?? 3660;
+    const maxSearchDays = o["maxSearchDays"] ?? 3660;
     if (!Number.isInteger(maxSearchDays) || maxSearchDays < 1) {
-        throw new RangeError(`Invalid maxSearchDays: ${maxSearchDays}`);
+        c.error("invalid-option", "maxSearchDays", "must be a positive integer");
     }
-    const weekly = [0, 1, 2, 3, 4, 5, 6].map((w) => !closedWeekdays.has(w));
-    const sourceOptions = {
-        ...(options.holidays !== undefined && { holidays: options.holidays }),
-        ...(options.timeZone !== undefined && { timeZone: options.timeZone }),
-        ...(options.outOfRange !== undefined && { outOfRange: options.outOfRange }),
+    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);
+    return {
+        schedule: {
+            source,
+            weekly: Object.freeze([0, 1, 2, 3, 4, 5, 6].map((w) => !closedWeekdays.has(w))),
+            holiday: holidayPolicy === "ignore" ? "weekday" : { value: holidayPolicy === "open" },
+            annual,
+            // 臨時営業日を先に並べて、臨時休業日より優先する
+            dates: [...open, ...closed],
+        },
+        maxSearchDays: Number.isInteger(maxSearchDays) ? maxSearchDays : 3660,
     };
-    const schedule = createSchedule({
-        ...sourceOptions,
-        weekly,
-        holiday: holidayPolicy === "ignore" ? "weekday" : { value: holidayPolicy === "open" },
-        annual: (options.closedAnnual ?? []).map((e) => {
-            if (typeof e === "string")
-                return { date: parseMonthDay(e), value: false };
-            if ("date" in e)
-                return e.name === undefined ? { date: e.date, value: false } : { ...e, value: false };
-            return e.name === undefined
-                ? { from: e.from, to: e.to, value: false }
-                : { ...e, value: false };
-        }),
-        // 臨時営業日を先に並べて、臨時休業日より優先する
-        dates: [...toDateValues(options.openDates, true), ...toDateValues(options.closedDates, false)],
-    });
+}
+/**
+ * 祝日と休業日の規則から営業日カレンダーを作る。
+ *
+ * 設定は作る時点で取り込まれるので、あとから元の配列を書き換えても結果は変わらない。
+ * 設定の誤りは code 付きの RangeError になる。
+ * @public
+ */
+export function createCalendar(options = {}) {
+    const c = new IssueCollector();
+    const compiled = compileCalendarOptions(c, options);
+    c.throwFirstError();
+    const { maxSearchDays } = compiled;
+    const schedule = buildSchedule(compiled.schedule);
     function info(date) {
         const day = schedule.dayInfo(date);
         let reason;
-        switch (day.reason) {
+        // 内部では閉じた型（KnownScheduleReason）で分岐し、値が増えたときの対応漏れを型で検出する
+        const known = day.reason;
+        switch (known) {
             case "date":
                 reason = day.value ? "open-date" : "closed-date";
                 break;
@@ -77,6 +104,10 @@ export function createCalendar(options = {}) {
             case "weekday":
                 reason = day.value ? "regular" : "closed-weekday";
                 break;
+            default: {
+                const unreachable = known;
+                throw plainError("invalid-option", `Unexpected schedule reason: ${String(unreachable)}`);
+            }
         }
         const result = {
             date: day.date,
@@ -100,7 +131,7 @@ export function createCalendar(options = {}) {
             if (isOpen(date))
                 return date;
         }
-        throw new Error(`No business day found within ${maxSearchDays} days from ${start}`);
+        throw plainError("no-business-day", `No business day found within ${maxSearchDays} days from ${start}`);
     }
     function countOpen(from, toExclusive) {
         let count = 0;
@@ -136,7 +167,7 @@ export function createCalendar(options = {}) {
         businessDayOnOrBefore: (input) => search(dateOf(input), -1),
         addBusinessDays(input, n) {
             if (!Number.isInteger(n))
-                throw new RangeError(`n must be an integer: ${n}`);
+                throw rangeError("invalid-argument", `n must be an integer: ${n}`);
             let date = dateOf(input);
             if (n === 0)
                 return search(date, 1);
@@ -155,7 +186,7 @@ export function createCalendar(options = {}) {
             const a = dateOf(from);
             const b = dateOf(to);
             if (a > b)
-                throw new RangeError(`"from" must not be after "to" (${a} > ${b})`);
+                throw rangeError("invalid-range", `"from" must not be after "to" (${a} > ${b})`);
             const result = [];
             for (let n = toDayNumber(a); n <= toDayNumber(b); n++) {
                 const date = fromDayNumber(n);

package/dist/core/date.d.ts

@@ -4,9 +4,15 @@
  * 日付は常に "YYYY-MM-DD" 文字列で扱い、内部では 1970-01-01 からの日数（day number）に
  * 変換して計算する。Date オブジェクトのローカル時刻は使わない。
  */
-/** 暦日を表す "YYYY-MM-DD" 文字列 */
+/**
+ * 暦日を表す "YYYY-MM-DD" 文字列。
+ * @public
+ */
 export type DateString = string;
-/** 曜日（0 = 日曜日 … 6 = 土曜日。Date#getDay と同じ） */
+/**
+ * 曜日（0 = 日曜日 … 6 = 土曜日。Date#getDay と同じ）。
+ * @public
+ */
 export type Weekday = 0 | 1 | 2 | 3 | 4 | 5 | 6;
 /** 年月日に分解する。形式または暦として不正なら RangeError */
 export declare function parseDate(value: string): {
@@ -14,7 +20,10 @@ export declare function parseDate(value: string): {
     month: number;
     day: number;
 };
-/** "YYYY-MM-DD" として正しい暦日か */
+/**
+ * "YYYY-MM-DD" として正しい暦日か。
+ * @public
+ */
 export declare function isValidDate(value: unknown): value is DateString;
 /** 年月日から "YYYY-MM-DD" を作る（範囲外なら RangeError） */
 export declare function formatDate(year: number, month: number, day: number): DateString;
@@ -26,11 +35,20 @@ export declare function daysInMonth(year: number, month: number): number;
 export declare function toDayNumber(date: DateString): number;
 /** 1970-01-01 からの日数を "YYYY-MM-DD" に戻す */
 export declare function fromDayNumber(dayNumber: number): DateString;
-/** n 日後（負なら前）の日付 */
+/**
+ * n 日後（負なら前）の日付。
+ * @public
+ */
 export declare function addDays(date: DateString, days: number): DateString;
-/** from から to までの日数（to が後なら正） */
+/**
+ * from から to までの日数（to が後なら正）。
+ * @public
+ */
 export declare function diffDays(from: DateString, to: DateString): number;
-/** 曜日（0 = 日曜日） */
+/**
+ * 曜日（0 = 日曜日）。
+ * @public
+ */
 export declare function weekdayOf(date: DateString): Weekday;
 /** その月の第 n 何曜日（n は 1 始まり） */
 export declare function nthWeekdayOfMonth(year: number, month: number, weekday: Weekday, n: number): DateString;

package/dist/core/date.js

@@ -4,6 +4,7 @@
  * 日付は常に "YYYY-MM-DD" 文字列で扱い、内部では 1970-01-01 からの日数（day number）に
  * 変換して計算する。Date オブジェクトのローカル時刻は使わない。
  */
+import { rangeError } from "./errors.js";
 const DATE_RE = /^(\d{4})-(\d{2})-(\d{2})$/;
 const MS_PER_DAY = 86_400_000;
 const MONTH_DAYS = [31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
@@ -11,17 +12,20 @@ const MONTH_DAYS = [31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
 export function parseDate(value) {
     const m = DATE_RE.exec(value);
     if (!m) {
-        throw new RangeError(`Invalid date string: ${JSON.stringify(value)} (expected YYYY-MM-DD)`);
+        throw rangeError("invalid-date", `Invalid date string: ${JSON.stringify(value)} (expected YYYY-MM-DD)`);
     }
     const year = Number(m[1]);
     const month = Number(m[2]);
     const day = Number(m[3]);
     if (year < 1000 || month < 1 || month > 12 || day < 1 || day > daysInMonth(year, month)) {
-        throw new RangeError(`Invalid date: ${value}`);
+        throw rangeError("invalid-date", `Invalid date: ${value}`);
     }
     return { year, month, day };
 }
-/** "YYYY-MM-DD" として正しい暦日か */
+/**
+ * "YYYY-MM-DD" として正しい暦日か。
+ * @public
+ */
 export function isValidDate(value) {
     if (typeof value !== "string")
         return false;
@@ -36,7 +40,7 @@ export function isValidDate(value) {
 /** 年月日から "YYYY-MM-DD" を作る（範囲外なら RangeError） */
 export function formatDate(year, month, day) {
     if (!Number.isInteger(year) || year < 1000 || year > 9999) {
-        throw new RangeError(`Year out of range (1000-9999): ${year}`);
+        throw rangeError("out-of-range", `Year out of range (1000-9999): ${year}`);
     }
     const s = `${year}-${String(month).padStart(2, "0")}-${String(day).padStart(2, "0")}`;
     parseDate(s);
@@ -52,7 +56,7 @@ export function daysInMonth(year, month) {
         return isLeapYear(year) ? 29 : 28;
     const days = MONTH_DAYS[month - 1];
     if (days === undefined)
-        throw new RangeError(`Invalid month: ${month}`);
+        throw rangeError("invalid-date", `Invalid month: ${month}`);
     return days;
 }
 /** 1970-01-01 からの日数 */
@@ -65,17 +69,27 @@ export function fromDayNumber(dayNumber) {
     const d = new Date(dayNumber * MS_PER_DAY);
     return formatDate(d.getUTCFullYear(), d.getUTCMonth() + 1, d.getUTCDate());
 }
-/** n 日後（負なら前）の日付 */
+/**
+ * n 日後（負なら前）の日付。
+ * @public
+ */
 export function addDays(date, days) {
-    if (!Number.isInteger(days))
-        throw new RangeError(`days must be an integer: ${days}`);
+    if (!Number.isInteger(days)) {
+        throw rangeError("invalid-argument", `days must be an integer: ${days}`);
+    }
     return fromDayNumber(toDayNumber(date) + days);
 }
-/** from から to までの日数（to が後なら正） */
+/**
+ * from から to までの日数（to が後なら正）。
+ * @public
+ */
 export function diffDays(from, to) {
     return toDayNumber(to) - toDayNumber(from);
 }
-/** 曜日（0 = 日曜日） */
+/**
+ * 曜日（0 = 日曜日）。
+ * @public
+ */
 export function weekdayOf(date) {
     // 1970-01-01 は木曜日（4）
     return ((((toDayNumber(date) + 4) % 7) + 7) % 7);

package/dist/core/errors.d.ts

@@ -0,0 +1,78 @@
+/**
+ * コード付きの例外と、入力の問題を集める仕組み。
+ *
+ * 例外は従来どおり RangeError・TypeError・Error のインスタンスで、code プロパティを持つ。
+ * 例外のメッセージの文言は API に含まない（変わることがある）。判定には code を使う。
+ */
+/**
+ * 既知のエラーコード（増えることがある）。
+ * @public
+ */
+export type KnownErrorCode = 
+/** 日付 "YYYY-MM-DD" の形式・値の誤り */
+"invalid-date"
+/** 毎年の月日 "MM-DD" の形式・値の誤り */
+ | "invalid-month-day"
+/** 時刻・日時の形式・値の誤り */
+ | "invalid-time"
+/** 受け付けない種類の入力 */
+ | "invalid-input"
+/** IANA タイムゾーン名の誤り */
+ | "invalid-time-zone"
+/** 期間の開始が終了より後 */
+ | "invalid-range"
+/** 曜日の番号（0〜6）の誤り */
+ | "invalid-weekday"
+/** 引数の値の誤り（整数でない日数など） */
+ | "invalid-argument"
+/** 設定の値の誤り */
+ | "invalid-option"
+/** 祝日の提供元どうしのタイムゾーンが異なり、timeZone の指定が必要 */
+ | "time-zone-conflict"
+/** 対応している年の範囲の外 */
+ | "out-of-range"
+/** 祝日の提供元の形式の誤り */
+ | "invalid-provider"
+/** 祝日の提供元が返したデータの誤り */
+ | "invalid-provider-data"
+/** 指定した日数の範囲に営業日がない */
+ | "no-business-day";
+/**
+ * エラーコード。将来の版で値が増えることがある。
+ * @public
+ */
+export type ErrorCode = KnownErrorCode | (string & {});
+/**
+ * このライブラリが投げた例外（code 付き）か。
+ * @public
+ */
+export declare function isBizdaysError(error: unknown): error is Error & {
+    readonly code: ErrorCode;
+};
+/** @internal */
+export declare function rangeError(code: KnownErrorCode, message: string): RangeError;
+/** @internal */
+export declare function typeError(code: KnownErrorCode, message: string): TypeError;
+/** @internal */
+export declare function plainError(code: KnownErrorCode, message: string): Error;
+/** @internal 問題の重さ */
+export type IssueSeverity = "error" | "warning" | "info";
+/** @internal 設定の問題 1 件 */
+export interface Issue {
+    readonly severity: IssueSeverity;
+    readonly code: string;
+    /** 設定の中の位置（例: "dates[1].from"） */
+    readonly path: string;
+    readonly message: string;
+}
+/** @internal 問題を集める */
+export declare class IssueCollector {
+    readonly issues: Issue[];
+    error(code: KnownErrorCode, path: string, message: string): void;
+    warning(code: string, path: string, message: string): void;
+    get hasErrors(): boolean;
+    /** 最初の誤りを例外にして投げる（誤りがなければ何もしない） */
+    throwFirstError(): void;
+}
+/** @internal 設定のオブジェクトに、知らないキーがあれば警告として記録する */
+export declare function checkUnknownKeys(collector: IssueCollector, path: string, value: object, known: readonly string[]): void;