bizdays-toolkit 0.1.2 → 0.3.0

package/dist/core/schedule.js

@@ -0,0 +1,426 @@
+/**
+ * 日ごとに値を返すスケジュール（営業時間・受付枠など、曜日・祝日・特定日で変わるもの）。
+ *
+ * 1 日の値は次の優先順位で決まる（上が優先）:
+ *   1. dates   … 個別の日付・期間（配列で先に書いたものが優先）
+ *   2. annual  … 毎年の月日・月日の期間（年をまたぐ期間も可。配列で先に書いたものが優先）
+ *   3. 祝日     … holiday の規則（"weekday": 曜日どおり / { sameAs: 曜日 }: その曜日の値 / { value }: 指定の値）
+ *   4. weekly  … 曜日ごとの値
+ *
+ * 営業日カレンダー（createCalendar）は、このスケジュールの真偽値版として作られている。
+ */
+import { isValidDate, parseDate, toDayNumber, weekdayOf, } from "./date.js";
+import { checkUnknownKeys, IssueCollector, rangeError } from "./errors.js";
+import { instantToCivil, toCivil, toDateTimeParts, validateTimeZone, } from "./input.js";
+// ------------------------------------------------------------
+// 入力チェック（誤りを集める。作成時は最初の誤りを例外にする）
+// ------------------------------------------------------------
+const MONTH_DAY_RE = /^(\d{2})-(\d{2})$/;
+const MAX_DAYS_IN_MONTH = [31, 29, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
+const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/** @internal "MM-DD" として正しいか（2 月 29 日は可） */
+export function isValidMonthDay(value) {
+    if (typeof value !== "string")
+        return false;
+    const m = MONTH_DAY_RE.exec(value);
+    if (!m)
+        return false;
+    const month = Number(m[1]);
+    const day = Number(m[2]);
+    return month >= 1 && month <= 12 && day >= 1 && day <= MAX_DAYS_IN_MONTH[month - 1];
+}
+/** @internal 曜日の番号として正しいか */
+export const isWeekday = (value) => Number.isInteger(value) && value >= 0 && value <= 6;
+function checkName(c, path, name) {
+    if (name === undefined)
+        return undefined;
+    if (typeof name !== "string") {
+        c.error("invalid-option", `${path}.name`, "name must be a string");
+        return undefined;
+    }
+    return name;
+}
+function checkDate(c, path, value) {
+    if (!isValidDate(value)) {
+        c.error("invalid-date", path, `Invalid date ${JSON.stringify(value)} (expected YYYY-MM-DD)`);
+        return undefined;
+    }
+    return toDayNumber(value);
+}
+function checkMonthDay(c, path, value) {
+    if (!isValidMonthDay(value)) {
+        c.error("invalid-month-day", path, `Invalid month-day ${JSON.stringify(value)} (expected MM-DD)`);
+        return undefined;
+    }
+    return value;
+}
+/**
+ * @internal 個別の日付の規則を検証して取り込む。
+ * entry は "YYYY-MM-DD"・{ date }・{ from, to } のいずれか。値は valueOf で決める
+ */
+export function compileDateRules(c, path, entries, valueOf, allowString) {
+    if (entries === undefined)
+        return [];
+    if (!Array.isArray(entries)) {
+        c.error("invalid-option", path, "must be an array");
+        return [];
+    }
+    const rules = [];
+    entries.forEach((raw, i) => {
+        const p = `${path}[${i}]`;
+        const entry = allowString && typeof raw === "string" ? { date: raw } : raw;
+        if (!isObject(entry)) {
+            c.error("invalid-option", p, allowString ? "must be a date string or an object" : "must be an object");
+            return;
+        }
+        const value = valueOf(entry, p);
+        const name = checkName(c, p, entry["name"]);
+        if ("date" in entry) {
+            checkUnknownKeys(c, p, entry, ["date", "name", "value"]);
+            const n = checkDate(c, `${p}.date`, entry["date"]);
+            if (n !== undefined && value !== undefined)
+                rules.push({ from: n, to: n, value, name });
+            return;
+        }
+        if (!("from" in entry) || !("to" in entry)) {
+            c.error("invalid-option", p, 'must have "date" or both "from" and "to"');
+            return;
+        }
+        checkUnknownKeys(c, p, entry, ["from", "to", "name", "value"]);
+        const from = checkDate(c, `${p}.from`, entry["from"]);
+        const to = checkDate(c, `${p}.to`, entry["to"]);
+        if (from === undefined || to === undefined)
+            return;
+        if (from > to) {
+            c.error("invalid-range", p, `"from" must not be after "to" (${String(entry["from"])} > ${String(entry["to"])})`);
+            return;
+        }
+        if (value !== undefined)
+            rules.push({ from, to, value, name });
+    });
+    return rules;
+}
+/** @internal 毎年の月日の規則を検証して取り込む（entry は "MM-DD"・{ date }・{ from, to }） */
+export function compileAnnualRules(c, path, entries, valueOf, allowString) {
+    if (entries === undefined)
+        return [];
+    if (!Array.isArray(entries)) {
+        c.error("invalid-option", path, "must be an array");
+        return [];
+    }
+    const rules = [];
+    entries.forEach((raw, i) => {
+        const p = `${path}[${i}]`;
+        const entry = allowString && typeof raw === "string" ? { date: raw } : raw;
+        if (!isObject(entry)) {
+            c.error("invalid-option", p, allowString ? "must be a month-day string or an object" : "must be an object");
+            return;
+        }
+        const value = valueOf(entry, p);
+        const name = checkName(c, p, entry["name"]);
+        if ("date" in entry) {
+            checkUnknownKeys(c, p, entry, ["date", "name", "value"]);
+            const md = checkMonthDay(c, `${p}.date`, entry["date"]);
+            if (md !== undefined && value !== undefined)
+                rules.push({ from: md, to: md, value, name });
+            return;
+        }
+        if (!("from" in entry) || !("to" in entry)) {
+            c.error("invalid-option", p, 'must have "date" or both "from" and "to"');
+            return;
+        }
+        checkUnknownKeys(c, p, entry, ["from", "to", "name", "value"]);
+        const from = checkMonthDay(c, `${p}.from`, entry["from"]);
+        const to = checkMonthDay(c, `${p}.to`, entry["to"]);
+        if (from !== undefined && to !== undefined && value !== undefined) {
+            rules.push({ from, to, value, name });
+        }
+    });
+    return rules;
+}
+/** 規則の value を取り出す（value が必須の規則用） */
+function requiredValue(c) {
+    return (entry, path) => {
+        if (!("value" in entry)) {
+            c.error("invalid-option", path, 'must have "value"');
+            return undefined;
+        }
+        return entry["value"];
+    };
+}
+function validateProvider(c, path, p) {
+    const bad = (message) => {
+        c.error("invalid-provider", path, message);
+        return false;
+    };
+    if (!isObject(p))
+        return bad("must be a holiday provider object");
+    if (typeof p["id"] !== "string" || p["id"] === "")
+        return bad('"id" must be a non-empty string');
+    if (typeof p["timeZone"] !== "string")
+        return bad('"timeZone" must be a string');
+    try {
+        validateTimeZone(p["timeZone"]);
+    }
+    catch {
+        return bad(`"timeZone" is not a valid IANA time zone: ${JSON.stringify(p["timeZone"])}`);
+    }
+    const years = p["supportedYears"];
+    if (!isObject(years) ||
+        !Number.isInteger(years["from"]) ||
+        !Number.isInteger(years["to"]) ||
+        years["from"] < 1000 ||
+        years["to"] > 9999 ||
+        years["from"] > years["to"]) {
+        return bad('"supportedYears" must be { from, to } with integer years in 1000-9999 and from <= to');
+    }
+    if (typeof p["dataVersion"] !== "string")
+        return bad('"dataVersion" must be a string');
+    if (p["confirmedThrough"] !== undefined && !Number.isInteger(p["confirmedThrough"])) {
+        return bad('"confirmedThrough" must be an integer year');
+    }
+    if (typeof p["holidaysInYear"] !== "function")
+        return bad('"holidaysInYear" must be a function');
+    return true;
+}
+/** @internal 祝日の提供元とタイムゾーンの設定を検証する */
+export function compileHolidaySource(c, options) {
+    const raw = options["holidays"];
+    const list = raw === undefined ? [] : Array.isArray(raw) ? raw : [raw];
+    const providers = [];
+    list.forEach((p, i) => {
+        const path = Array.isArray(raw) ? `holidays[${i}]` : "holidays";
+        if (validateProvider(c, path, p))
+            providers.push(p);
+    });
+    let timeZone = "UTC";
+    if (options["timeZone"] !== undefined) {
+        try {
+            timeZone = validateTimeZone(options["timeZone"]);
+        }
+        catch {
+            c.error("invalid-time-zone", "timeZone", `Invalid time zone: ${JSON.stringify(options["timeZone"])}`);
+        }
+    }
+    else {
+        const zones = [...new Set(providers.map((p) => validateTimeZone(p.timeZone)))];
+        if (zones.length > 1) {
+            c.error("time-zone-conflict", "timeZone", `Holiday providers use different time zones (${zones.join(", ")}); specify timeZone`);
+        }
+        timeZone = zones[0] ?? "UTC";
+    }
+    const outOfRange = options["outOfRange"] ?? "throw";
+    if (outOfRange !== "throw" && outOfRange !== "ignore") {
+        c.error("invalid-option", "outOfRange", 'must be "throw" or "ignore"');
+    }
+    return {
+        providers: Object.freeze(providers),
+        timeZone,
+        outOfRange: outOfRange === "ignore" ? "ignore" : "throw",
+    };
+}
+// ------------------------------------------------------------
+// 祝日を調べる機能
+// ------------------------------------------------------------
+function providerDataError(provider, year, message) {
+    return rangeError("invalid-provider-data", `Holiday provider ${provider.id} returned invalid data for ${year}: ${message}`);
+}
+/** 提供元が返したデータを検証し、契約の項目だけを持つ変更できないオブジェクトにする */
+function loadProviderYear(provider, year) {
+    const list = provider.holidaysInYear(year);
+    if (!Array.isArray(list))
+        throw providerDataError(provider, year, "holidaysInYear must return an array");
+    const seen = new Set();
+    return list.map((h, i) => {
+        if (!isObject(h))
+            throw providerDataError(provider, year, `item ${i} is not an object`);
+        const { date, name, nameEn, kind, confirmed } = h;
+        if (!isValidDate(date) || parseDate(date).year !== year) {
+            throw providerDataError(provider, year, `item ${i} has an invalid date ${JSON.stringify(date)}`);
+        }
+        if (seen.has(date))
+            throw providerDataError(provider, year, `duplicate date ${date}`);
+        seen.add(date);
+        if (typeof name !== "string" || typeof nameEn !== "string" || typeof kind !== "string") {
+            throw providerDataError(provider, year, `item ${i} (${date}) must have string name, nameEn and kind`);
+        }
+        if (typeof confirmed !== "boolean") {
+            throw providerDataError(provider, year, `item ${i} (${date}) must have boolean confirmed`);
+        }
+        return Object.freeze({ date, name, nameEn, kind: kind, confirmed });
+    });
+}
+/** @internal 祝日を調べる機能を作る（設定は検証済みであること） */
+export function createHolidayLookup(source) {
+    const { providers, timeZone, outOfRange } = source;
+    const yearCache = new Map();
+    function holidayMap(year) {
+        let map = yearCache.get(year);
+        if (!map) {
+            map = new Map();
+            for (const provider of providers) {
+                const { from, to } = provider.supportedYears;
+                if (year < from || year > to) {
+                    if (outOfRange === "ignore")
+                        continue;
+                    throw rangeError("out-of-range", `Holidays for ${provider.id} are supported for ${from}-${to}; requested ${year}`);
+                }
+                for (const h of loadProviderYear(provider, year)) {
+                    // 同じ日に複数の提供元の祝日がある場合は、先に渡した提供元を優先する
+                    if (!map.has(h.date))
+                        map.set(h.date, h);
+                }
+            }
+            yearCache.set(year, map);
+        }
+        return map;
+    }
+    function holidayOn(date) {
+        if (providers.length === 0)
+            return undefined;
+        return holidayMap(parseDate(date).year).get(date);
+    }
+    const dateOf = (input) => toCivil(input, timeZone).date;
+    function holidaysInYear(year) {
+        if (!Number.isInteger(year))
+            throw rangeError("invalid-argument", `Invalid year: ${year}`);
+        return Object.freeze([...holidayMap(year).values()].sort((a, b) => a.date < b.date ? -1 : a.date > b.date ? 1 : 0));
+    }
+    return {
+        timeZone,
+        providers,
+        holidayOn,
+        dateOf,
+        civilOf: (input) => toDateTimeParts(input, timeZone),
+        today: (now = new Date()) => instantToCivil(now.getTime(), timeZone).date,
+        isHoliday: (input) => holidayOn(dateOf(input)) !== undefined,
+        getHoliday: (input) => holidayOn(dateOf(input)),
+        holidaysInYear,
+        holidaysBetween(from, to) {
+            const a = dateOf(from);
+            const b = dateOf(to);
+            if (a > b)
+                throw rangeError("invalid-range", `"from" must not be after "to" (${a} > ${b})`);
+            const result = [];
+            for (let y = parseDate(a).year; y <= parseDate(b).year; y++) {
+                for (const h of holidaysInYear(y))
+                    if (h.date >= a && h.date <= b)
+                        result.push(h);
+            }
+            return Object.freeze(result);
+        },
+    };
+}
+const SCHEDULE_OPTION_KEYS = [
+    "holidays",
+    "timeZone",
+    "outOfRange",
+    "weekly",
+    "holiday",
+    "annual",
+    "dates",
+];
+/** @internal スケジュールの設定を検証して取り込む（誤りは c に集める） */
+export function compileScheduleOptions(c, options) {
+    if (!isObject(options)) {
+        c.error("invalid-option", "", "options must be an object");
+        return undefined;
+    }
+    checkUnknownKeys(c, "", options, SCHEDULE_OPTION_KEYS);
+    const source = compileHolidaySource(c, options);
+    const weeklyRaw = options["weekly"];
+    let weekly = [];
+    if (!Array.isArray(weeklyRaw) || weeklyRaw.length !== 7) {
+        c.error("invalid-option", "weekly", "must have 7 values ([Sunday, Monday, ..., Saturday])");
+    }
+    else {
+        weekly = Object.freeze([...weeklyRaw]);
+    }
+    let holiday = "weekday";
+    const holidayRaw = options["holiday"];
+    if (holidayRaw === undefined || holidayRaw === "weekday") {
+        holiday = "weekday";
+    }
+    else if (isObject(holidayRaw) && "sameAs" in holidayRaw) {
+        if (isWeekday(holidayRaw["sameAs"]))
+            holiday = Object.freeze({ sameAs: holidayRaw["sameAs"] });
+        else
+            c.error("invalid-weekday", "holiday.sameAs", "must be an integer from 0 (Sunday) to 6 (Saturday)");
+    }
+    else if (isObject(holidayRaw) && "value" in holidayRaw) {
+        holiday = Object.freeze({ value: holidayRaw["value"] });
+    }
+    else {
+        c.error("invalid-option", "holiday", 'must be "weekday", { sameAs: weekday } or { value }');
+    }
+    const annual = compileAnnualRules(c, "annual", options["annual"], requiredValue(c), false);
+    const dates = compileDateRules(c, "dates", options["dates"], requiredValue(c), false);
+    return { source, weekly, holiday, annual, dates };
+}
+function matchAnnual(rule, monthDay) {
+    return rule.from <= rule.to
+        ? monthDay >= rule.from && monthDay <= rule.to
+        : monthDay >= rule.from || monthDay <= rule.to;
+}
+/** @internal 検証済みの規則からスケジュールを作る */
+export function buildSchedule(compiled) {
+    const { weekly, holiday: holidayRule, annual, dates } = compiled;
+    const lookup = createHolidayLookup(compiled.source);
+    function info(date) {
+        const dayNumber = toDayNumber(date);
+        const weekday = weekdayOf(date);
+        const holiday = lookup.holidayOn(date);
+        const make = (value, reason, name) => {
+            const result = {
+                date,
+                weekday,
+                value,
+                reason,
+            };
+            if (name !== undefined)
+                result.name = name;
+            if (holiday !== undefined)
+                result.holiday = holiday;
+            return Object.freeze(result);
+        };
+        const byDate = dates.find((r) => dayNumber >= r.from && dayNumber <= r.to);
+        if (byDate)
+            return make(byDate.value, "date", byDate.name);
+        const monthDay = date.slice(5);
+        const byAnnual = annual.find((r) => matchAnnual(r, monthDay));
+        if (byAnnual)
+            return make(byAnnual.value, "annual", byAnnual.name);
+        if (holiday && holidayRule !== "weekday") {
+            const value = "sameAs" in holidayRule ? weekly[holidayRule.sameAs] : holidayRule.value;
+            return make(value, "holiday", holiday.name);
+        }
+        return make(weekly[weekday], "weekday", undefined);
+    }
+    const schedule = {
+        timeZone: lookup.timeZone,
+        providers: lookup.providers,
+        dateOf: lookup.dateOf,
+        civilOf: lookup.civilOf,
+        today: lookup.today,
+        isHoliday: lookup.isHoliday,
+        getHoliday: lookup.getHoliday,
+        holidaysInYear: lookup.holidaysInYear,
+        holidaysBetween: lookup.holidaysBetween,
+        valueOn: (input) => info(lookup.dateOf(input)).value,
+        dayInfo: (input) => info(lookup.dateOf(input)),
+    };
+    return Object.freeze(schedule);
+}
+/**
+ * 曜日・祝日・特定日の規則から、日ごとに値を返すスケジュールを作る。
+ *
+ * 設定は作る時点で複製されるので、あとから元の配列やオブジェクトを書き換えても結果は変わらない
+ * （値 T そのものは複製しない）。設定の誤りは code 付きの RangeError になる。
+ * @public
+ */
+export function createSchedule(options) {
+    const c = new IssueCollector();
+    const compiled = compileScheduleOptions(c, options);
+    c.throwFirstError();
+    return buildSchedule(compiled);
+}

package/dist/core/types.d.ts

@@ -1,5 +1,8 @@
 import type { DateString } from "./date.ts";
-/** 祝日・休日 1 日分 */
+/**
+ * 祝日・休日 1 日分。
+ * @public
+ */
 export interface Holiday<Kind extends string = string> {
     /** 暦日 "YYYY-MM-DD" */
     readonly date: DateString;
@@ -18,7 +21,12 @@ export interface Holiday<Kind extends string = string> {
 /**
  * 祝日の提供元（国・地域ごとのルール）。
  *
- * 他の国・地域の祝日はこのインターフェースを実装して createCalendar に渡す。
+ * 他の国・地域の祝日はこのインターフェースを実装して createCalendar・createSchedule に渡す。
+ * holidaysInYear が返すデータは、年ごとに初めて使うときに検証され、誤りがあれば
+ * code: "invalid-provider-data" の例外になる。
+ *
+ * 互換性の約束: このインターフェースに項目を足すときは、メジャー版以外では省略可能な項目に限る。
+ * @public
  */
 export interface HolidayProvider<Kind extends string = string> {
     /** ISO 3166-1 alpha-2（国）または ISO 3166-2（地域）のコード。例: "JP", "US-CA" */
@@ -34,6 +42,6 @@ export interface HolidayProvider<Kind extends string = string> {
     readonly dataVersion: string;
     /** この年までは公式に確定している（それより後は confirmed: false を含みうる） */
     readonly confirmedThrough?: number;
-    /** その年の祝日・休日を日付順に返す */
+    /** その年の祝日・休日（同じ日付は 1 件まで。順序は問わない） */
     holidaysInYear(year: number): readonly Holiday<Kind>[];
 }

package/dist/index.d.ts

@@ -1,9 +1,15 @@
 /**
- * 祝日と、会社・店舗の休業日を組み合わせた営業日カレンダー。
+ * 祝日と、会社・店舗の休業日を組み合わせた営業日カレンダー（createCalendar）と、
+ * 曜日・祝日・特定日で変わる値（営業時間など）のスケジュール（createSchedule）。
  *
  * 国ごとの祝日はサブパスから読み込む（例: "bizdays-toolkit/jp"）。
+ *
+ * 公開する 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 SpecificDate, } from "./core/calendar.ts";
-export { addDays, diffDays, isValidDate, nthWeekdayOfMonth, weekdayOf, type DateString, type Weekday, } from "./core/date.ts";
-export { toDateString, type DateInput, type TemporalDateLike, type TemporalInstantLike, } from "./core/input.ts";
+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 { createSchedule, type AnnualRangeValue, type AnnualValue, type CivilDateTimeParts, type DateRangeValue, type DateValue, type HolidayLookup, type HolidayRule, type HolidaySourceOptions, type KnownScheduleReason, type Schedule, type ScheduleDay, type ScheduleOptions, type ScheduleReason, } from "./core/schedule.ts";
+export { addDays, diffDays, isValidDate, weekdayOf, type DateString, type Weekday, } from "./core/date.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

@@ -1,8 +1,14 @@
 /**
- * 祝日と、会社・店舗の休業日を組み合わせた営業日カレンダー。
+ * 祝日と、会社・店舗の休業日を組み合わせた営業日カレンダー（createCalendar）と、
+ * 曜日・祝日・特定日で変わる値（営業時間など）のスケジュール（createSchedule）。
  *
  * 国ごとの祝日はサブパスから読み込む（例: "bizdays-toolkit/jp"）。
+ *
+ * 公開する API には TSDoc の @public（安定）または @beta（マイナー版で変わりうる）を付ける。
+ * 公開する名前と型は etc/api.md に記録し、pnpm check で意図しない変化を検出する。
  */
 export { createCalendar, } from "./core/calendar.js";
-export { addDays, diffDays, isValidDate, nthWeekdayOfMonth, weekdayOf, } from "./core/date.js";
-export { toDateString, } from "./core/input.js";
+export { createSchedule, } from "./core/schedule.js";
+export { addDays, diffDays, isValidDate, weekdayOf, } from "./core/date.js";
+export { isBizdaysError } from "./core/errors.js";
+export { toDateString, toDateTimeParts, } from "./core/input.js";

package/dist/jp/index.d.ts

@@ -14,23 +14,57 @@ import type { DateString } from "../core/date.ts";
 import type { DateInput } from "../core/input.ts";
 import type { Holiday, HolidayProvider } from "../core/types.ts";
 import { type JapaneseHolidayKind } from "./rules.ts";
-export type { JapaneseHolidayKind } from "./rules.ts";
-export { autumnalEquinoxDay, vernalEquinoxDay } from "./rules.ts";
-/** 日本の祝日 */
+export type { JapaneseHolidayKind, KnownJapaneseHolidayKind } from "./rules.ts";
+/**
+ * 日本の祝日。
+ * @public
+ */
 export type JapaneseHoliday = Holiday<JapaneseHolidayKind>;
-/** 日本の祝日の提供元（createCalendar の holidays に渡す） */
+/**
+ * 日本の祝日の提供元（createCalendar・createSchedule の holidays に渡す）。
+ * @public
+ */
 export declare const jp: HolidayProvider<JapaneseHolidayKind>;
-/** 祝日か（Date などの瞬間は日本時間で判定する） */
+/**
+ * 祝日か（Date などの瞬間は日本時間で判定する）。
+ * @public
+ */
 export declare function isHoliday(input: DateInput): boolean;
-/** 祝日なら祝日を返す */
+/**
+ * 祝日なら祝日を返す。
+ * @public
+ */
 export declare function getHoliday(input: DateInput): JapaneseHoliday | undefined;
-/** その年の祝日 */
+/**
+ * その年の祝日。
+ * @public
+ */
 export declare function holidaysInYear(year: number): readonly JapaneseHoliday[];
-/** 期間内の祝日（両端を含む） */
+/**
+ * 期間内の祝日（両端を含む）。
+ * @public
+ */
 export declare function holidaysBetween(from: DateInput, to: DateInput): readonly JapaneseHoliday[];
-/** 日本時間での暦日 */
+/**
+ * 日本時間での暦日。
+ * @public
+ */
 export declare function toJapanDate(input: DateInput): DateString;
-/** 反映済みの官報の年月 */
+/**
+ * 日本時間での暦日と時刻（"HH:mm"。暦日だけの入力では null）。
+ * @public
+ */
+export declare function toJapanDateTime(input: DateInput): {
+    readonly date: DateString;
+    readonly time: string | null;
+};
+/**
+ * 反映済みの官報の年月。
+ * @public
+ */
 export declare const dataVersion: string;
-/** 春分・秋分の日が官報で確定している最後の年 */
+/**
+ * 春分・秋分の日が官報で確定している最後の年。
+ * @public
+ */
 export declare const confirmedThrough: number;

package/dist/jp/index.js

@@ -12,9 +12,11 @@
  */
 import { createCalendar } from "../core/calendar.js";
 import { CONFIRMED_THROUGH, DATA_VERSION, SUPPORTED_YEARS, computeJapaneseHolidays, } from "./rules.js";
-export { autumnalEquinoxDay, vernalEquinoxDay } from "./rules.js";
 const cache = new Map();
-/** 日本の祝日の提供元（createCalendar の holidays に渡す） */
+/**
+ * 日本の祝日の提供元（createCalendar・createSchedule の holidays に渡す）。
+ * @public
+ */
 export const jp = Object.freeze({
     id: "JP",
     timeZone: "Asia/Tokyo",
@@ -32,27 +34,55 @@ export const jp = Object.freeze({
 });
 let defaultCalendar;
 const calendar = () => (defaultCalendar ??= createCalendar({ holidays: jp }));
-/** 祝日か（Date などの瞬間は日本時間で判定する） */
+/**
+ * 祝日か（Date などの瞬間は日本時間で判定する）。
+ * @public
+ */
 export function isHoliday(input) {
     return calendar().isHoliday(input);
 }
-/** 祝日なら祝日を返す */
+/**
+ * 祝日なら祝日を返す。
+ * @public
+ */
 export function getHoliday(input) {
     return calendar().getHoliday(input);
 }
-/** その年の祝日 */
+/**
+ * その年の祝日。
+ * @public
+ */
 export function holidaysInYear(year) {
     return calendar().holidaysInYear(year);
 }
-/** 期間内の祝日（両端を含む） */
+/**
+ * 期間内の祝日（両端を含む）。
+ * @public
+ */
 export function holidaysBetween(from, to) {
     return calendar().holidaysBetween(from, to);
 }
-/** 日本時間での暦日 */
+/**
+ * 日本時間での暦日。
+ * @public
+ */
 export function toJapanDate(input) {
     return calendar().dateOf(input);
 }
-/** 反映済みの官報の年月 */
+/**
+ * 日本時間での暦日と時刻（"HH:mm"。暦日だけの入力では null）。
+ * @public
+ */
+export function toJapanDateTime(input) {
+    return calendar().civilOf(input);
+}
+/**
+ * 反映済みの官報の年月。
+ * @public
+ */
 export const dataVersion = DATA_VERSION;
-/** 春分・秋分の日が官報で確定している最後の年 */
+/**
+ * 春分・秋分の日が官報で確定している最後の年。
+ * @public
+ */
 export const confirmedThrough = CONFIRMED_THROUGH;