bizdays-toolkit 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -4,6 +4,25 @@
 
 ## [Unreleased]
 
+## [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 +148,8 @@
 
 - 日本: 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.6.0...HEAD
+[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 で約 7KB（日本の祝日込みで約 8.3KB）。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` は、曜日・祝日・特定日の規則から、日ごとに任意の値を返します。値の型は自由なので、営業時間のほか、受付枠や配送料の区分などにも使えます。
@@ -274,7 +325,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,9 +413,10 @@ 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`
+- **Lightweight, zero dependencies**: about 7 KB min+gzip (about 8.3 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

@@ -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/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.6.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",