bizdays-toolkit 0.5.0 → 0.7.0

package/CHANGELOG.md

@@ -4,6 +4,35 @@
 
 ## [Unreleased]
 
+## [0.7.0] - 2026-10-16
+
+### Added
+
+- 祝日（`Holiday`）に、ほかの言語の名称 `names`（省略可能。キーは BCP 47 の言語タグの正規の形。例: `{ "zh-Hant": "…", ko: "…" }`）を追加した。利用者が実装した提供元が付けた `names` を、提供元のデータの検証で確かめ（誤りは `invalid-provider-data`）、複製・凍結して返す。同梱の日本の祝日は `names` を持たない（公式の出典がある日本語・英語の名称だけを同梱する）
+
+### 開発
+
+- `size-limits.json` の値を上げるときの理由は、コミットメッセージではなく CHANGELOG の「開発」に書く取り決めにした。`pnpm check`（`scripts/check-size.ts`）が前の版のタグの `size-limits.json` と比べ、値が上がっているのに記載がなければ失敗する（0.6.0 で理由をコミットメッセージに書き漏らしたため）。CI とリリースのワークフローは履歴とタグを取得して（`fetch-depth: 0`）この確認を行い、リリースのワークフローではタグを付けたコミットを 1 つ前の版のタグと比べる
+
+## [0.6.0] - 2026-10-16
+
+### Added
+
+- 日付の調整 `adjust(input, { convention })`（営業日カレンダー）: 休業日を `"following"`（翌営業日）・`"preceding"`（前営業日）・`"modified-following"`（翌営業日。月が変わるなら前営業日）・`"modified-preceding"`（前営業日。月が変わるなら翌営業日）で調整する。月が変わるかは調整する前の日付の月と比べる
+- 月の営業日（営業日カレンダー）: `nthBusinessDayOfMonth(month, n)`（負なら月末から数える。-1 は最終営業日）・`firstBusinessDayOfMonth(month)`・`lastBusinessDayOfMonth(month)`
+- 月の期日 `dueDate(month, { day, convention })`（営業日カレンダー）: その月の `day` 日（-1 は末日。その月にない日は末日に読み替える）を `convention` で調整する
+- 月の計算（ルート）: `monthOf(dateOrMonth, offset?)`（n か月後の月 `"YYYY-MM"`）・`closingMonth(date, closingDay)`（締め日で区切ったときの月）
+- 例外のコード `invalid-month`（月 `"YYYY-MM"` の誤り）
+- 型: `BusinessDayConvention`・`AdjustOptions`・`DueDateOptions`・`MonthString`
+
+### 開発
+
+- `pnpm check`（`scripts/check-package.ts`）で、CHANGELOG の版の節の並び・日付と、末尾のリンク定義が節とそろっていることを確かめるようにした（0.5.0 でリンク定義の更新漏れがあったため）
+- リリースのワークフローで、CHANGELOG の日付が `YYYY-MM-DD` のまま・見出しがないときの表示を分かりやすくした（止まる条件は変わらない）
+- 月の計算と日付の調整の性質のテストを追加
+- サイズの上限を上げた（`.` 16500・`./jp` 19500・`./diagnose` 22000。月の計算の追加。minify + gzip ではルートが約 7.2KB、日本の祝日込みで約 8.3KB）
+- `docs/decisions.md` に 16 番目（日付の調整と月の期日の設計）を追加
+
 ## [0.5.0] - 2026-10-16
 
 ### Added
@@ -129,7 +158,9 @@
 
 - 日本: 2026 年 2 月の官報（2027 年の春分・秋分の日）まで反映（`dataVersion: "2026-02"`、`confirmedThrough: 2027`）
 
-[Unreleased]: https://github.com/inohan77/bizdays-toolkit/compare/v0.5.0...HEAD
+[Unreleased]: https://github.com/inohan77/bizdays-toolkit/compare/v0.7.0...HEAD
+[0.7.0]: https://github.com/inohan77/bizdays-toolkit/compare/v0.6.0...v0.7.0
+[0.6.0]: https://github.com/inohan77/bizdays-toolkit/compare/v0.5.0...v0.6.0
 [0.5.0]: https://github.com/inohan77/bizdays-toolkit/compare/v0.4.0...v0.5.0
 [0.4.0]: https://github.com/inohan77/bizdays-toolkit/compare/v0.3.1...v0.4.0
 [0.3.1]: https://github.com/inohan77/bizdays-toolkit/compare/v0.3.0...v0.3.1

package/README.md

@@ -20,9 +20,10 @@
 - **繰り返しの規則**: 「第 3 水曜定休」「毎月末日は棚卸」「月曜休館（祝日の場合は翌平日）」のような規則を、祝日に当たったときの扱い（祝日に従う・祝日でも当てはめる・翌日に振り替える）とあわせて指定できます
 - **日ごとの値（営業時間など）**: 「火曜定休、祝日は日曜の営業時間、元日は休業、大晦日は短縮営業」のように、曜日・祝日・特定日で変わる値を同じ規則で引けます
 - **設定の診断**: `bizdays-toolkit/diagnose` の `diagnoseCalendar`・`diagnoseSchedule` が、決して使われない規則・取り除いても結果が変わらない規則・キーの打ち間違い・営業日が 1 日もない設定などを、例外を投げずに一覧で返します。テストに 1 行足せば、設定の変更で規則が死んでいないかを確かめられます
+- **月の期日**: 「20 日締め翌月 10 日払い（休業日なら翌営業日）」「月末の最終営業日」のような期日を、金融で使われる 4 つの調整方法（following・preceding・modified-following・modified-preceding）で計算します
 - **営業日の計算**: 定休日の曜日・毎年の休業日（年末年始のような年をまたぐ期間も可）・臨時休業日・臨時営業日と祝日を組み合わせ、「N 営業日後」「締め時刻を過ぎたら翌営業日」などを計算します
 - **タイムゾーンを間違えない**: `Date` などの瞬間は、カレンダーのタイムゾーン（日本は `Asia/Tokyo`）で暦日に変換してから判定します。UTC で動くサーバーでも、日本時間 0〜9 時が前日扱いになりません
-- **軽量・依存ゼロ**: minify + gzip で約 6.5KB（日本の祝日込みで約 7.5KB）。ESM・型定義同梱・`sideEffects: false` で、Node.js・ブラウザー・Edge ランタイムで動作します
+- **軽量・依存ゼロ**: minify + gzip で約 7.4KB（日本の祝日込みで約 8.5KB）。ESM・型定義同梱・`sideEffects: false` で、Node.js・ブラウザー・Edge ランタイムで動作します
 - **他の国・地域に拡張できる**: 祝日の提供元はインターフェース（`HolidayProvider`）で差し替えられます。現在は日本のみ同梱しています
 
 [English](#english)
@@ -177,6 +178,56 @@ const shibuya = createCalendar({ ...base, openDates: ["2026-12-27"] });
 const yokohama = createCalendar({ ...base, closedRecurring: [{ weekday: 3, nth: 3 }] });
 ```
 
+### 月の期日と日付の調整
+
+休業日に当たった日付を、指定した方法で営業日に調整します。月の第 n 営業日や、「毎月 n 日（休業日なら翌営業日）」のような期日も求められます。
+
+```ts
+import { closingMonth, createCalendar, monthOf } from "bizdays-toolkit";
+import { jp } from "bizdays-toolkit/jp";
+
+const calendar = createCalendar({
+  holidays: jp,
+  closedWeekdays: [0, 6],
+  closedAnnual: [{ from: "12-31", to: "01-03", name: "年末年始" }],
+});
+
+calendar.adjust("2026-10-31", { convention: "following" }); // "2026-11-02"（10/31 は土曜日）
+calendar.adjust("2026-10-31", { convention: "modified-following" }); // "2026-10-30"（月が変わるので前へ）
+
+calendar.firstBusinessDayOfMonth("2027-01"); // "2027-01-04"
+calendar.lastBusinessDayOfMonth("2026-12"); // "2026-12-30"
+calendar.nthBusinessDayOfMonth("2026-10", 5); // "2026-10-07"（-1 は最終、-2 は最後から 2 番目）
+
+// 毎月 10 日払い（休業日なら翌営業日）
+calendar.dueDate("2026-10", { day: 10, convention: "following" }); // "2026-10-13"（12 日はスポーツの日）
+
+// 20 日締め・翌月末払い（休業日なら前営業日）
+const billing = closingMonth("2026-10-21", 20); // "2026-11"（10/21〜11/20 が 11 月分）
+calendar.dueDate(monthOf(billing, 1), { day: -1, convention: "preceding" }); // "2026-12-30"
+```
+
+**調整の方法**（`convention`、必須）
+
+| 方法                   | 休業日のとき                           |
+| ---------------------- | -------------------------------------- |
+| `"following"`          | 翌営業日                               |
+| `"preceding"`          | 前営業日                               |
+| `"modified-following"` | 翌営業日。ただし月が変わるなら前営業日 |
+| `"modified-preceding"` | 前営業日。ただし月が変わるなら翌営業日 |
+
+- 営業日ならどの方法でもその日のままです
+- 月が変わるかは、**調整する前の日付の月**と比べます。`dueDate` では、末日に読み替えた後の日付の月です（例: 2 月の 31 日払いは 2 月末日を基準にし、`"modified-following"` なら 2 月の中で調整します）
+- `modified-…` で、同じ月に反対向きの営業日もない（その月が全部休業日）ときは、月が変わっても元の向きに調整します
+- 「最も近い営業日」（nearest）はありません。前後が同じ距離のときの決め方が業種ごとに違うためです
+
+**月の計算**（ルートの関数。営業日は考えません）
+
+- `monthOf(dateOrMonth, offset?)`: 日付または月 `"YYYY-MM"` の、`offset` か月後（負なら前）の月
+- `closingMonth(date, closingDay)`: 締め日（1〜31、`-1` は末日）で区切ったときに日付が属する月。締め日の翌日から次の締め日までを、次の締め日の月とします。締め日がその月にない日（31 日締めの 2 月など）は末日締めです
+
+`dueDate` の `day` も、その月にない日（2 月 30 日など）は末日に読み替えます。繰り返しの規則（`{ day: 31 }`）はその月にない日に当てはまらないので、扱いが異なります。期日は「その月のどこか」に必ず決まる必要があるためです。
+
 ### 日ごとの値（営業時間など）
 
 `createSchedule` は、曜日・祝日・特定日の規則から、日ごとに任意の値を返します。値の型は自由なので、営業時間のほか、受付枠や配送料の区分などにも使えます。
@@ -254,6 +305,23 @@ const myCountry: HolidayProvider = {
 const calendar = createCalendar({ holidays: myCountry, closedWeekdays: [0, 6] });
 ```
 
+祝日には、ほかの言語の名称を `names` で付けられます。キーは BCP 47 の言語タグの正規の形（`"zh-Hant"`・`"ko"` など）です。同梱の日本の祝日は `names` を持ちません（公式の出典がある日本語・英語だけを同梱しています）。必要な場合は、提供元を包んで付けます。
+
+```ts
+import { jp } from "bizdays-toolkit/jp";
+
+const zhHant: Record<string, string> = { "2026-01-01": "元日" /* … 利用者が用意した訳 */ };
+const jpWithNames = {
+  ...jp,
+  holidaysInYear: (year: number) =>
+    jp.holidaysInYear(year).map((h) => {
+      const name = zhHant[h.date];
+      return name === undefined ? h : { ...h, names: { "zh-Hant": name } };
+    }),
+};
+createCalendar({ holidays: jpWithNames }).getHoliday("2026-01-01")?.names; // { "zh-Hant": "元日" }
+```
+
 ### 対応年の外
 
 祝日の提供元の対応年（日本は 1955〜2099 年）を外れた日付を判定すると `RangeError` になります。祝日がない日として扱いたい場合は `outOfRange: "ignore"` を指定してください。
@@ -274,7 +342,7 @@ try {
 }
 ```
 
-主なコード: `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`。将来の版でコードが増えることがあります。
+主なコード: `invalid-date`・`invalid-month`・`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`。将来の版でコードが増えることがあります。
 
 ### 設定の診断
 
@@ -362,10 +430,11 @@ 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
 - **Recurring rules**: weekly, nth-weekday-of-month (`{ weekday: 3, nth: 3 }`) and day-of-month (`{ day: -1 }`) rules, with per-rule holiday handling (`onHolidayRule`: `"under-holiday"`, `"over-holiday"`, or `"after-holiday"` to move the rule to the next non-holiday, e.g. "closed on Mondays; if Monday is a holiday, closed on the next weekday")
 - **Option diagnostics**: `diagnoseCalendar` / `diagnoseSchedule` from `bizdays-toolkit/diagnose` return a list of problems without throwing: rules that can never apply (`shadowed`, `never-matches`), rules whose removal changes nothing (`redundant`), typos in option keys with a suggestion (`unknown-option`), dates outside the holiday provider's years (`out-of-range`), and calendars with no business day. Use `code` to branch; `message` is for humans
+- **Month-based due dates**: `adjust` with `following` / `preceding` / `modified-following` / `modified-preceding`, the nth / first / last business day of a month, `dueDate(month, { day, convention })`, and the calendar helpers `closingMonth` and `monthOf`
 - **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 6.5 KB min+gzip (about 7.5 KB with Japanese holidays), ESM, bundled types, `sideEffects: false`
-- **Extensible** through the `HolidayProvider` interface (only Japan is bundled for now)
+- **Lightweight, zero dependencies**: about 7.4 KB min+gzip (about 8.5 KB with Japanese holidays), ESM, bundled types, `sideEffects: false`
+- **Extensible** through the `HolidayProvider` interface (only Japan is bundled for now). Holidays can carry names in other languages via the optional `names` field (keys are canonical BCP 47 language tags); the bundled Japanese data includes only the officially sourced Japanese and English names
 
 ```ts
 import { createCalendar } from "bizdays-toolkit";

package/dist/core/calendar.d.ts

@@ -19,7 +19,8 @@
 import { type DateString, type Weekday } from "./date.ts";
 import { IssueCollector } from "./errors.ts";
 import { type DateInput } from "./input.ts";
-import { type CompiledSchedule, type RecurringRule, type HolidayLookup, type HolidaySourceOptions } from "./schedule.ts";
+import { type MonthString } from "./month.ts";
+import { type CompiledSchedule, type DayOfMonth, type RecurringRule, type HolidayLookup, type HolidaySourceOptions } from "./schedule.ts";
 import type { Holiday } from "./types.ts";
 /**
  * 祝日の扱い。
@@ -124,6 +125,35 @@ export interface BusinessDayOptions {
      */
     readonly cutoff?: string;
 }
+/**
+ * 休業日に当たった日付の調整の方法（営業日の慣行）。
+ * - "following": 翌営業日
+ * - "preceding": 前営業日
+ * - "modified-following": 翌営業日。ただし月が変わるなら前営業日
+ * - "modified-preceding": 前営業日。ただし月が変わるなら翌営業日
+ *
+ * 月が変わるかは、調整する前の日付の月と比べる。
+ * @public
+ */
+export type BusinessDayConvention = "following" | "preceding" | "modified-following" | "modified-preceding";
+/**
+ * 日付の調整のオプション。
+ * @public
+ */
+export interface AdjustOptions {
+    /** 調整の方法 */
+    readonly convention: BusinessDayConvention;
+}
+/**
+ * 月の期日のオプション。
+ * @public
+ */
+export interface DueDateOptions {
+    /** 期日の日（1〜31、-1 は末日）。その月にない日（2 月 30 日など）は末日に読み替える */
+    readonly day: DayOfMonth;
+    /** 期日が休業日のときの調整の方法 */
+    readonly convention: BusinessDayConvention;
+}
 /**
  * 営業日カレンダー。
  * @public
@@ -150,6 +180,25 @@ export interface Calendar<Kind extends string = string> extends HolidayLookup<Ki
     businessDaysBetween(from: DateInput, to: DateInput): number;
     /** 期間内の営業日（両端を含む） */
     listBusinessDays(from: DateInput, to: DateInput): readonly DateString[];
+    /**
+     * 営業日ならその日、休業日なら convention に従って調整した営業日。
+     * 月が変わるか（modified-…）は、調整する前の日付の月と比べる
+     */
+    adjust(input: DateInput, options: AdjustOptions): DateString;
+    /**
+     * 月 "YYYY-MM" の第 n 営業日。n が負なら月末から数える（-1 は最終営業日）。
+     * その月の営業日が足りなければ code: "no-business-day" の Error
+     */
+    nthBusinessDayOfMonth(month: MonthString, n: number): DateString;
+    /** 月 "YYYY-MM" の最初の営業日（nthBusinessDayOfMonth(month, 1)） */
+    firstBusinessDayOfMonth(month: MonthString): DateString;
+    /** 月 "YYYY-MM" の最後の営業日（nthBusinessDayOfMonth(month, -1)） */
+    lastBusinessDayOfMonth(month: MonthString): DateString;
+    /**
+     * 月 "YYYY-MM" の day 日を期日とし、休業日なら convention で調整した日。
+     * その月にない日は末日に読み替えてから調整する（例: 2 月の 30 日払いは 2 月末日）
+     */
+    dueDate(month: MonthString, options: DueDateOptions): DateString;
 }
 interface CompiledCalendar<Kind extends string> {
     readonly schedule: CompiledSchedule<boolean, Kind>;

package/dist/core/calendar.js

@@ -16,9 +16,10 @@
  *
  * 内部では、営業日かどうか（真偽値）を返すスケジュール（createSchedule）として作っている。
  */
-import { addDays, fromDayNumber, toDayNumber } from "./date.js";
+import { addDays, daysInMonth, formatDate, fromDayNumber, toDayNumber, } from "./date.js";
 import { checkUnknownKeys, IssueCollector, plainError, rangeError } from "./errors.js";
 import { parseTimeOfDay, toCivil } from "./input.js";
+import { dayOfMonth, isDayOfMonthValue, parseMonth } from "./month.js";
 import { buildSchedule, compileAnnualRules, compileDateRules, compileHolidaySource, compileRecurringRules, isWeekday, RECURRING_RULE_KEYS, } from "./schedule.js";
 const CALENDAR_OPTION_KEYS = [
     "holidays",
@@ -156,6 +157,74 @@ export function createCalendar(options = {}) {
                 count++;
         return count;
     }
+    const CONVENTIONS = [
+        "following",
+        "preceding",
+        "modified-following",
+        "modified-preceding",
+    ];
+    function adjustDate(date, options) {
+        const convention = options?.convention;
+        if (!CONVENTIONS.includes(convention)) {
+            throw rangeError("invalid-argument", `convention must be one of ${CONVENTIONS.map((v) => `"${v}"`).join(", ")}`);
+        }
+        if (isOpen(date))
+            return date;
+        const month = date.slice(0, 7);
+        switch (convention) {
+            case "following":
+                return search(date, 1);
+            case "preceding":
+                return search(date, -1);
+            case "modified-following": {
+                const next = search(date, 1);
+                if (next.startsWith(month))
+                    return next;
+                // 同じ月に前営業日がなければ、月が変わっても翌営業日にする
+                const previous = searchWithin(date, -1, month);
+                return previous ?? next;
+            }
+            case "modified-preceding": {
+                const previous = search(date, -1);
+                if (previous.startsWith(month))
+                    return previous;
+                const next = searchWithin(date, 1, month);
+                return next ?? previous;
+            }
+            default:
+                throw rangeError("invalid-argument", `Unknown convention: ${String(convention)}`);
+        }
+    }
+    /** 同じ月の中だけで営業日を探す（なければ undefined） */
+    function searchWithin(start, step, month) {
+        for (let date = start; date.startsWith(month); date = addDays(date, step)) {
+            if (isOpen(date))
+                return date;
+        }
+        return undefined;
+    }
+    /** 月の営業日（月初から順） */
+    function businessDaysOfMonth(month) {
+        const { year, month: m } = parseMonth(month);
+        const result = [];
+        for (let d = 1; d <= daysInMonth(year, m); d++) {
+            const date = formatDate(year, m, d);
+            if (isOpen(date))
+                result.push(date);
+        }
+        return result;
+    }
+    function nthOfMonth(month, n) {
+        if (!Number.isInteger(n) || n === 0) {
+            throw rangeError("invalid-argument", `n must be a non-zero integer: ${n}`);
+        }
+        const days = businessDaysOfMonth(month);
+        const found = n > 0 ? days[n - 1] : days[days.length + n];
+        if (found === undefined) {
+            throw plainError("no-business-day", `${month} has ${days.length} business day(s); requested ${n > 0 ? "" : "last "}#${Math.abs(n)}`);
+        }
+        return found;
+    }
     const calendar = {
         timeZone: schedule.timeZone,
         providers: schedule.providers,
@@ -211,6 +280,17 @@ export function createCalendar(options = {}) {
             }
             return Object.freeze(result);
         },
+        adjust: (input, options) => adjustDate(dateOf(input), options),
+        nthBusinessDayOfMonth: nthOfMonth,
+        firstBusinessDayOfMonth: (month) => nthOfMonth(month, 1),
+        lastBusinessDayOfMonth: (month) => nthOfMonth(month, -1),
+        dueDate(month, options) {
+            const day = options?.day;
+            if (!isDayOfMonthValue(day)) {
+                throw rangeError("invalid-argument", `day must be an integer from 1 to 31, or -1 (last day): ${String(day)}`);
+            }
+            return adjustDate(dayOfMonth(parseMonth(month), day), options);
+        },
     };
     return Object.freeze(calendar);
 }

package/dist/core/errors.d.ts

@@ -12,6 +12,8 @@
 export type KnownErrorCode = 
 /** 日付 "YYYY-MM-DD" の形式・値の誤り */
 "invalid-date"
+/** 月 "YYYY-MM" の形式・値の誤り */
+ | "invalid-month"
 /** 毎年の月日 "MM-DD" の形式・値の誤り */
  | "invalid-month-day"
 /** 時刻・日時の形式・値の誤り */

package/dist/core/month.d.ts

@@ -0,0 +1,50 @@
+/**
+ * 月（"YYYY-MM"）の計算。締め日の月（closingMonth）や、n か月後の月（monthOf）。
+ *
+ * 営業日を考えない暦の計算なので、カレンダーなしで使える。営業日を考えた月の計算
+ * （月の第 n 営業日・期日）は営業日カレンダーのメソッドにある。
+ */
+import { type DateString } from "./date.ts";
+/**
+ * 月を表す "YYYY-MM" 文字列。
+ * @public
+ */
+export type MonthString = string;
+/** @internal 年と月 */
+export interface YearMonth {
+    readonly year: number;
+    readonly month: number;
+}
+/** @internal "YYYY-MM" を年と月に分解する（誤りは code: "invalid-month"） */
+export declare function parseMonth(value: unknown): YearMonth;
+/** @internal 年と月を "YYYY-MM" にする（年が 1000〜9999 の外なら code: "out-of-range"） */
+export declare function formatMonth({ year, month }: YearMonth): MonthString;
+/** @internal n か月後（負なら前）の年と月 */
+export declare function shiftMonth({ year, month }: YearMonth, offset: number): YearMonth;
+/** @internal その月の d 日（その月にない日・-1 は末日に読み替える） */
+export declare function dayOfMonth({ year, month }: YearMonth, day: number): DateString;
+/** @internal 月の日（1〜31、-1 は末日）として正しいか */
+export declare const isDayOfMonthValue: (v: unknown) => v is number;
+/**
+ * 日付または月の、offset か月後（負なら前）の月 "YYYY-MM"。
+ *
+ * @example
+ * monthOf("2026-10-16"); // "2026-10"
+ * monthOf("2026-10-16", 1); // "2026-11"
+ * monthOf("2026-01", -1); // "2025-12"
+ * @public
+ */
+export declare function monthOf(input: DateString | MonthString, offset?: number): MonthString;
+/**
+ * 締め日で区切ったときに、日付が属する月 "YYYY-MM"。
+ *
+ * 締め日の翌日から次の締め日までを、次の締め日の月とする（例: 20 日締めなら 10 月 21 日〜11 月 20 日が 11 月分）。
+ * closingDay が -1 またはその月の日数以上なら、締め日はその月の末日（例: 31 日締めの 2 月は 28 日か 29 日締め）。
+ *
+ * @example
+ * closingMonth("2026-10-20", 20); // "2026-10"
+ * closingMonth("2026-10-21", 20); // "2026-11"
+ * closingMonth("2026-10-31", -1); // "2026-10"（末日締め）
+ * @public
+ */
+export declare function closingMonth(date: DateString, closingDay: number): MonthString;

package/dist/core/month.js

@@ -0,0 +1,76 @@
+/**
+ * 月（"YYYY-MM"）の計算。締め日の月（closingMonth）や、n か月後の月（monthOf）。
+ *
+ * 営業日を考えない暦の計算なので、カレンダーなしで使える。営業日を考えた月の計算
+ * （月の第 n 営業日・期日）は営業日カレンダーのメソッドにある。
+ */
+import { daysInMonth, formatDate, parseDate } from "./date.js";
+import { rangeError } from "./errors.js";
+const MONTH_RE = /^(\d{4})-(\d{2})$/;
+/** @internal "YYYY-MM" を年と月に分解する（誤りは code: "invalid-month"） */
+export function parseMonth(value) {
+    const m = typeof value === "string" ? MONTH_RE.exec(value) : null;
+    const year = Number(m?.[1]);
+    const month = Number(m?.[2]);
+    if (!m || year < 1000 || month < 1 || month > 12) {
+        throw rangeError("invalid-month", `Invalid month: ${JSON.stringify(value)} (expected YYYY-MM)`);
+    }
+    return { year, month };
+}
+/** @internal 年と月を "YYYY-MM" にする（年が 1000〜9999 の外なら code: "out-of-range"） */
+export function formatMonth({ year, month }) {
+    if (year < 1000 || year > 9999) {
+        throw rangeError("out-of-range", `Year out of range (1000-9999): ${year}`);
+    }
+    return `${year}-${String(month).padStart(2, "0")}`;
+}
+/** @internal n か月後（負なら前）の年と月 */
+export function shiftMonth({ year, month }, offset) {
+    const index = year * 12 + (month - 1) + offset;
+    return { year: Math.floor(index / 12), month: (index % 12) + 1 };
+}
+/** @internal その月の d 日（その月にない日・-1 は末日に読み替える） */
+export function dayOfMonth({ year, month }, day) {
+    const last = daysInMonth(year, month);
+    return formatDate(year, month, day === -1 || day > last ? last : day);
+}
+/** @internal 月の日（1〜31、-1 は末日）として正しいか */
+export const isDayOfMonthValue = (v) => v === -1 || (Number.isInteger(v) && v >= 1 && v <= 31);
+/**
+ * 日付または月の、offset か月後（負なら前）の月 "YYYY-MM"。
+ *
+ * @example
+ * monthOf("2026-10-16"); // "2026-10"
+ * monthOf("2026-10-16", 1); // "2026-11"
+ * monthOf("2026-01", -1); // "2025-12"
+ * @public
+ */
+export function monthOf(input, offset = 0) {
+    if (!Number.isInteger(offset)) {
+        throw rangeError("invalid-argument", `offset must be an integer: ${offset}`);
+    }
+    const base = typeof input === "string" && input.split("-").length === 3
+        ? parseDate(input)
+        : parseMonth(input);
+    return formatMonth(shiftMonth(base, offset));
+}
+/**
+ * 締め日で区切ったときに、日付が属する月 "YYYY-MM"。
+ *
+ * 締め日の翌日から次の締め日までを、次の締め日の月とする（例: 20 日締めなら 10 月 21 日〜11 月 20 日が 11 月分）。
+ * closingDay が -1 またはその月の日数以上なら、締め日はその月の末日（例: 31 日締めの 2 月は 28 日か 29 日締め）。
+ *
+ * @example
+ * closingMonth("2026-10-20", 20); // "2026-10"
+ * closingMonth("2026-10-21", 20); // "2026-11"
+ * closingMonth("2026-10-31", -1); // "2026-10"（末日締め）
+ * @public
+ */
+export function closingMonth(date, closingDay) {
+    if (!isDayOfMonthValue(closingDay)) {
+        throw rangeError("invalid-argument", `closingDay must be an integer from 1 to 31, or -1 (last day): ${closingDay}`);
+    }
+    const { year, month, day } = parseDate(date);
+    const closing = closingDay === -1 ? daysInMonth(year, month) : closingDay;
+    return formatMonth(shiftMonth({ year, month }, day <= closing ? 0 : 1));
+}

package/dist/core/schedule.js

@@ -373,9 +373,46 @@ function loadProviderYear(provider, year) {
         if (typeof confirmed !== "boolean") {
             throw providerDataError(provider, year, `item ${i} (${date}) must have boolean confirmed`);
         }
-        return Object.freeze({ date, name, nameEn, kind: kind, confirmed });
+        const holiday = {
+            date,
+            name,
+            nameEn,
+            kind: kind,
+            confirmed,
+        };
+        if (h["names"] !== undefined) {
+            const problem = checkNames(h["names"]);
+            if (problem)
+                throw providerDataError(provider, year, `item ${i} (${date}) names: ${problem}`);
+            holiday.names = Object.freeze(Object.fromEntries(Object.entries(h["names"])));
+        }
+        return Object.freeze(holiday);
     });
 }
+/** 祝日のほかの言語の名称を検証する（誤りがあれば理由を返す） */
+function checkNames(names) {
+    // 普通のオブジェクト（別の実行環境で作られたものも可）。継承した項目を持つものは受け付けない
+    const proto = isObject(names) ? Object.getPrototypeOf(names) : undefined;
+    if (!isObject(names) || (proto !== null && Object.getPrototypeOf(proto) !== null)) {
+        return "must be a plain object of { [language tag]: name }";
+    }
+    for (const [tag, value] of Object.entries(names)) {
+        let canonical;
+        try {
+            canonical = Intl.getCanonicalLocales(tag)[0];
+        }
+        catch {
+            return `${JSON.stringify(tag)} is not a BCP 47 language tag`;
+        }
+        if (canonical !== tag) {
+            return `${JSON.stringify(tag)} must be written in canonical form ${JSON.stringify(canonical)}`;
+        }
+        if (typeof value !== "string" || value === "") {
+            return `${JSON.stringify(tag)} must be a non-empty string`;
+        }
+    }
+    return undefined;
+}
 /** @internal 祝日を調べる機能を作る（設定は検証済みであること） */
 export function createHolidayLookup(source) {
     const { providers, timeZone, outOfRange } = source;

package/dist/core/types.d.ts

@@ -10,6 +10,11 @@ export interface Holiday<Kind extends string = string> {
     readonly name: string;
     /** 英語の名称 */
     readonly nameEn: string;
+    /**
+     * ほかの言語の名称（省略可能）。キーは BCP 47 の言語タグの正規の形（例: "zh-Hant", "ko"）。
+     * 同梱の提供元（日本）は持たない。利用者が実装した提供元が付けた場合に、検証して複製・凍結して返す
+     */
+    readonly names?: Readonly<Record<string, string>>;
     /** 種別（国ごとに定義。日本は JapaneseHolidayKind） */
     readonly kind: Kind;
     /**
@@ -23,7 +28,8 @@ export interface Holiday<Kind extends string = string> {
  *
  * 他の国・地域の祝日はこのインターフェースを実装して createCalendar・createSchedule に渡す。
  * holidaysInYear が返すデータは、年ごとに初めて使うときに検証され、誤りがあれば
- * code: "invalid-provider-data" の例外になる。
+ * code: "invalid-provider-data" の例外になる。返した祝日は、契約の項目（date・name・nameEn・names・
+ * kind・confirmed）だけを持つ変更できないオブジェクトに複製される。
  *
  * 互換性の約束: このインターフェースに項目を足すときは、メジャー版以外では省略可能な項目に限る。
  * @public

package/dist/index.d.ts

@@ -7,9 +7,10 @@
  * 公開する API には TSDoc の @public（安定）または @beta（マイナー版で変わりうる）を付ける。
  * 公開する名前と型は etc/api.md に記録し、pnpm check で意図しない変化を検出する。
  */
-export { createCalendar, type AnnualDate, type AnnualRange, type BusinessDayOptions, type Calendar, type CalendarOptions, type DateRange, type DayInfo, type DayReason, type HolidayPolicy, type KnownDayReason, type SpecificDate, } from "./core/calendar.ts";
+export { createCalendar, type AdjustOptions, type AnnualDate, type AnnualRange, type BusinessDayConvention, type BusinessDayOptions, type Calendar, type CalendarOptions, type DateRange, type DayInfo, type DayReason, type DueDateOptions, type HolidayPolicy, type KnownDayReason, type SpecificDate, } from "./core/calendar.ts";
 export { createSchedule, type AnnualRangeValue, type AnnualValue, type CivilDateTimeParts, type DateRangeValue, type DateValue, type DayOfMonth, type DayOfMonthPattern, type HolidayLookup, 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";
 export { addDays, diffDays, isValidDate, weekdayOf, type DateString, type Weekday, } from "./core/date.ts";
+export { closingMonth, monthOf, type MonthString } from "./core/month.ts";
 export { isBizdaysError, type ErrorCode, type KnownErrorCode } from "./core/errors.ts";
 export { toDateString, toDateTimeParts, type DateInput, type TemporalDateLike, type TemporalInstantLike, } from "./core/input.ts";
 export type { Holiday, HolidayProvider } from "./core/types.ts";

package/dist/index.js

@@ -10,5 +10,6 @@
 export { createCalendar, } from "./core/calendar.js";
 export { createSchedule, } from "./core/schedule.js";
 export { addDays, diffDays, isValidDate, weekdayOf, } from "./core/date.js";
+export { closingMonth, monthOf } from "./core/month.js";
 export { isBizdaysError } from "./core/errors.js";
 export { toDateString, toDateTimeParts, } from "./core/input.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bizdays-toolkit",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "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. / 祝日と営業日のカレンダー（タイムゾーン対応・日本の祝日は内閣府データで全日照合）",
   "keywords": [
     "bizdays",