bizdays-toolkit 0.1.2 → 0.3.0

package/CHANGELOG.md

@@ -4,6 +4,46 @@
 
 ## [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
+
+- `createSchedule()`: 曜日・祝日・毎年の月日・個別の日付の規則から、日ごとに任意の値（営業時間など）を返すスケジュール。祝日の値は `"weekday"`（曜日どおり）・`{ sameAs: 曜日 }`（その曜日の値）・`{ value }`（指定の値）から選べる。`valueOn`・`dayInfo`（値を決めた規則と祝日の情報付き）
+- `civilOf()`（営業日カレンダー・スケジュール）、`toDateTimeParts()`、`toJapanDateTime()`（`bizdays-toolkit/jp`）: 入力を、タイムゾーンでの暦日と時刻（`"HH:mm"`）に変換する
+
+### Changed
+
+- 営業日カレンダー（`createCalendar`）を、スケジュールの真偽値版として作り直した。判定の優先順位と結果は変わらない
+
 ## [0.1.2] - 2026-10-12
 
 ライブラリのコードと祝日データに変更はありません。
@@ -39,7 +79,9 @@
 
 - 日本: 2026 年 2 月の官報（2027 年の春分・秋分の日）まで反映（`dataVersion: "2026-02"`、`confirmedThrough: 2027`）
 
-[Unreleased]: https://github.com/inohan77/bizdays-toolkit/compare/v0.1.2...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
 [0.1.0]: https://github.com/inohan77/bizdays-toolkit/releases/tag/v0.1.0

package/README.md

@@ -17,9 +17,10 @@
 祝日と、会社・店舗の休業日を組み合わせた営業日カレンダーです。
 
 - **日本の祝日を内閣府のデータで全日照合**: 1955 年〜官報公表済みの年まで、内閣府「国民の祝日」CSV のすべての日付と一致することをテストで確かめています（振替休日・国民の休日・皇室行事による休日・五輪特措法による移動を含む）
+- **日ごとの値（営業時間など）**: 「火曜定休、祝日は日曜の営業時間、元日は休業、大晦日は短縮営業」のように、曜日・祝日・特定日で変わる値を同じ規則で引けます
 - **営業日の計算**: 定休日の曜日・毎年の休業日（年末年始のような年をまたぐ期間も可）・臨時休業日・臨時営業日と祝日を組み合わせ、「N 営業日後」「締め時刻を過ぎたら翌営業日」などを計算します
 - **タイムゾーンを間違えない**: `Date` などの瞬間は、カレンダーのタイムゾーン（日本は `Asia/Tokyo`）で暦日に変換してから判定します。UTC で動くサーバーでも、日本時間 0〜9 時が前日扱いになりません
-- **軽量・依存ゼロ**: minify + gzip で約 3KB（日本の祝日込みで約 5KB）。ESM・型定義同梱・`sideEffects: false` で、Node.js・ブラウザー・Edge ランタイムで動作します
+- **軽量・依存ゼロ**: minify + gzip で約 5.5KB（日本の祝日込みで約 7KB）。ESM・型定義同梱・`sideEffects: false` で、Node.js・ブラウザー・Edge ランタイムで動作します
 - **他の国・地域に拡張できる**: 祝日の提供元はインターフェース（`HolidayProvider`）で差し替えられます。現在は日本のみ同梱しています
 
 [English](#english)
@@ -87,6 +88,43 @@ shipping.dayInfo("2027-01-01");
 5. `closedWeekdays`（定休日の曜日）
 6. それ以外は営業日
 
+### 日ごとの値（営業時間など）
+
+`createSchedule` は、曜日・祝日・特定日の規則から、日ごとに任意の値を返します。値の型は自由なので、営業時間のほか、受付枠や配送料の区分などにも使えます。
+
+```ts
+import { createSchedule } from "bizdays-toolkit";
+import { jp } from "bizdays-toolkit/jp";
+
+type Hours = { open: string; close: string } | null; // null は休業
+const weekday = { open: "10:00", close: "21:00" };
+const sunday = { open: "10:00", close: "19:00" };
+
+const storeHours = createSchedule<Hours>({
+  holidays: jp,
+  weekly: [sunday, weekday, null, weekday, weekday, weekday, weekday], // [日, 月, …, 土]。火曜定休
+  holiday: { sameAs: 0 }, // 祝日は日曜の値（"weekday": 曜日どおり / { value: … }: 指定の値）
+  annual: [{ date: "01-01", value: null, name: "元日休業" }], // 毎年の月日（期間も可）
+  dates: [{ date: "2026-12-31", value: { open: "10:00", close: "17:00" }, name: "大晦日" }],
+});
+
+storeHours.valueOn("2026-11-03"); // { open: "10:00", close: "19:00" }（文化の日は日曜の営業時間）
+storeHours.dayInfo("2027-01-01");
+// { date: "2027-01-01", weekday: 5, value: null, reason: "annual", name: "元日休業", holiday: {…} }
+```
+
+値は `dates`（個別の日付・期間）→ `annual`（毎年の月日・期間）→ 祝日 → `weekly`（曜日）の順に決まります。同じ種類の規則が重なる場合は、配列で先に書いたものが優先です。
+
+「今、営業時間内か」のような時刻の範囲の判定は、業種ごとの決まり（深夜をまたぐ営業、休憩時間など）があるためライブラリでは行いません。`civilOf` でタイムゾーンでの暦日と時刻を取り出せば、アプリ側で簡単に書けます。
+
+```ts
+const { date, time } = storeHours.civilOf(new Date()); // { date: "2026-10-14", time: "16:30" }（日本時間）
+const hours = storeHours.valueOn(date);
+const isOpen = hours !== null && time !== null && hours.open <= time && time < hours.close;
+```
+
+`civilOf` は営業日カレンダーにもあり、`bizdays-toolkit/jp` の `toJapanDateTime`、ルートの `toDateTimeParts(input, timeZone)` でも同じ変換ができます。
+
 ### 日付・日時の入力
 
 すべてのメソッドは次の入力を受け付けます。戻り値の日付は常に `"YYYY-MM-DD"` 文字列です。
@@ -131,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) を参照してください。
@@ -139,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) の「互換性の約束」）
 
 ## 出典
 
@@ -155,9 +212,10 @@ MIT
 A business-day calendar that combines public holidays with company or store closures.
 
 - **Japanese holidays verified day by day** against the Cabinet Office CSV, from 1955 through the latest year officially announced (substitute holidays, citizens' holidays, imperial ceremonies, and the Olympic moves included)
+- **Day-by-day schedules**: `createSchedule` returns any value per day (e.g. store hours) from weekly values, a holiday rule (`"weekday"`, `{ sameAs: 0 }`, or `{ value }`), annual dates and specific dates
 - **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 3 KB min+gzip (about 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

@@ -8,42 +8,58 @@
  *   4. 祝日            … holidayPolicy に従う（closed: 休業 / open: 営業 / ignore: 判定に使わない）
  *   5. closedWeekdays … 定休日の曜日
  *   6. それ以外は営業日
+ *
+ * 内部では、営業日かどうか（真偽値）を返すスケジュール（createSchedule）として作っている。
  */
 import { type DateString, type Weekday } from "./date.ts";
+import { IssueCollector } from "./errors.ts";
 import { type DateInput } from "./input.ts";
-import type { Holiday, HolidayProvider } from "./types.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;
 }
-export interface CalendarOptions<Kind extends string = string> {
-    /** 祝日の提供元（例: jp）。複数渡すと和集合になる */
-    readonly holidays?: HolidayProvider<Kind> | readonly HolidayProvider<Kind>[];
-    /**
-     * 日時の入力（Date・オフセット付き文字列など）を暦日に変換するタイムゾーン。
-     * 省略時は祝日の提供元のタイムゾーン、提供元もなければ "UTC"
-     */
-    readonly timeZone?: string;
+/**
+ * 営業日カレンダーの設定。
+ * @public
+ */
+export interface CalendarOptions<Kind extends string = string> extends HolidaySourceOptions<Kind> {
     /** 定休日の曜日（0 = 日曜日） */
     readonly closedWeekdays?: readonly Weekday[];
     /** 毎年の休業日 */
@@ -54,14 +70,24 @@ export interface CalendarOptions<Kind extends string = string> {
     readonly openDates?: readonly (SpecificDate | DateRange)[];
     /** 祝日の扱い（既定: "closed"） */
     readonly holidayPolicy?: HolidayPolicy;
-    /** 祝日の提供元の対応年を外れた日付の扱い（既定: "throw"） */
-    readonly outOfRange?: "throw" | "ignore";
     /** 営業日を探すときに調べる最大日数（既定: 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;
@@ -73,6 +99,10 @@ export interface DayInfo<Kind extends string = string> {
     /** その日が祝日なら祝日（holidayPolicy に関係なく付く） */
     readonly holiday?: Holiday<Kind>;
 }
+/**
+ * 営業日を探すときのオプション。
+ * @public
+ */
 export interface BusinessDayOptions {
     /**
      * 締め時刻 "HH:mm"（カレンダーのタイムゾーン）。
@@ -80,23 +110,11 @@ export interface BusinessDayOptions {
      */
     readonly cutoff?: string;
 }
-export interface Calendar<Kind extends string = string> {
-    /** 日時の入力を暦日に変換するタイムゾーン */
-    readonly timeZone: string;
-    /** 祝日の提供元 */
-    readonly providers: readonly HolidayProvider<Kind>[];
-    /** 入力をカレンダーのタイムゾーンでの暦日に変換する */
-    dateOf(input: DateInput): DateString;
-    /** 今日の日付（カレンダーのタイムゾーン） */
-    today(now?: Date): DateString;
-    /** 祝日か */
-    isHoliday(input: DateInput): boolean;
-    /** 祝日なら祝日を返す */
-    getHoliday(input: DateInput): Holiday<Kind> | undefined;
-    /** その年の祝日 */
-    holidaysInYear(year: number): readonly Holiday<Kind>[];
-    /** 期間内の祝日（両端を含む） */
-    holidaysBetween(from: DateInput, to: DateInput): readonly Holiday<Kind>[];
+/**
+ * 営業日カレンダー。
+ * @public
+ */
+export interface Calendar<Kind extends string = string> extends HolidayLookup<Kind> {
     /** 1 日分の判定結果（営業日か・理由・祝日） */
     dayInfo(input: DateInput): DayInfo<Kind>;
     /** 営業日か */
@@ -119,5 +137,18 @@ export interface Calendar<Kind extends string = string> {
     /** 期間内の営業日（両端を含む） */
     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 {};