bizdays-toolkit 0.1.2 → 0.3.0

package/dist/core/input.d.ts

@@ -9,7 +9,10 @@
  * - Temporal.PlainDate / PlainDateTime / ZonedDateTime / Instant（ダックタイピング。依存は持たない）
  */
 import { type DateString } from "./date.ts";
-/** Temporal のオブジェクトとして受け付ける最小限の形 */
+/**
+ * Temporal.PlainDate / PlainDateTime として受け付ける最小限の形。
+ * @public
+ */
 export interface TemporalDateLike {
     readonly year: number;
     readonly month: number;
@@ -18,25 +21,42 @@ export interface TemporalDateLike {
     readonly minute?: number;
     readonly calendarId?: string;
 }
-/** Temporal.Instant / ZonedDateTime として受け付ける最小限の形 */
+/**
+ * Temporal.Instant / ZonedDateTime として受け付ける最小限の形。
+ * @public
+ */
 export interface TemporalInstantLike {
     readonly epochMilliseconds: number;
 }
-/** 日付・日時として受け付ける入力 */
+/**
+ * 日付・日時として受け付ける入力。
+ * @public
+ */
 export type DateInput = string | Date | TemporalDateLike | TemporalInstantLike;
-/** 暦日と、分かる場合は 0 時からの経過分 */
+/** @internal 暦日と、分かる場合は 0 時からの経過分 */
 export interface CivilDateTime {
     readonly date: DateString;
     /** 0 時からの経過分。暦日だけの入力では null */
     readonly minutes: number | null;
 }
-/** IANA タイムゾーン名として使えるか確かめ、正規化した名前を返す（不正なら RangeError） */
+/** @internal IANA タイムゾーン名として使えるか確かめ、正規化した名前を返す（不正なら RangeError） */
 export declare function validateTimeZone(timeZone: string): string;
-/** 瞬間（エポックミリ秒）を、タイムゾーンでの暦日と時刻に変換する */
+/** @internal 瞬間（エポックミリ秒）を、タイムゾーンでの暦日と時刻に変換する */
 export declare function instantToCivil(epochMilliseconds: number, timeZone: string): CivilDateTime;
-/** 入力をタイムゾーンでの暦日と時刻に変換する */
+/** @internal 入力をタイムゾーンでの暦日と時刻に変換する */
 export declare function toCivil(input: DateInput, timeZone: string): CivilDateTime;
-/** 入力を、タイムゾーンでの暦日 "YYYY-MM-DD" に変換する */
+/**
+ * 入力を、タイムゾーンでの暦日 "YYYY-MM-DD" に変換する。
+ * @public
+ */
 export declare function toDateString(input: DateInput, timeZone: string): DateString;
-/** "HH:mm" を 0 時からの経過分に変換する（00:00〜23:59） */
+/**
+ * 入力を、タイムゾーンでの暦日と時刻（"HH:mm"。暦日だけの入力では null）に変換する。
+ * @public
+ */
+export declare function toDateTimeParts(input: DateInput, timeZone: string): {
+    readonly date: DateString;
+    readonly time: string | null;
+};
+/** @internal "HH:mm" を 0 時からの経過分に変換する（00:00〜23:59） */
 export declare function parseTimeOfDay(value: string): number;

package/dist/core/input.js

@@ -9,6 +9,7 @@
  * - Temporal.PlainDate / PlainDateTime / ZonedDateTime / Instant（ダックタイピング。依存は持たない）
  */
 import { formatDate, parseDate } from "./date.js";
+import { rangeError, typeError } from "./errors.js";
 const DATETIME_RE = /^(\d{4}-\d{2}-\d{2})[T ](\d{2}):(\d{2})(?::(\d{2})(?:\.\d{1,9})?)?(Z|[+-]\d{2}:?\d{2})?$/i;
 const formatters = new Map();
 function formatterFor(timeZone) {
@@ -27,24 +28,27 @@ function formatterFor(timeZone) {
     }
     return f;
 }
-/** IANA タイムゾーン名として使えるか確かめ、正規化した名前を返す（不正なら RangeError） */
+/** @internal IANA タイムゾーン名として使えるか確かめ、正規化した名前を返す（不正なら RangeError） */
 export function validateTimeZone(timeZone) {
+    if (typeof timeZone !== "string" || timeZone === "") {
+        throw rangeError("invalid-time-zone", `Invalid time zone: ${JSON.stringify(timeZone)}`);
+    }
     try {
         return formatterFor(timeZone).resolvedOptions().timeZone;
     }
     catch {
-        throw new RangeError(`Invalid time zone: ${JSON.stringify(timeZone)}`);
+        throw rangeError("invalid-time-zone", `Invalid time zone: ${JSON.stringify(timeZone)}`);
     }
 }
-/** 瞬間（エポックミリ秒）を、タイムゾーンでの暦日と時刻に変換する */
+/** @internal 瞬間（エポックミリ秒）を、タイムゾーンでの暦日と時刻に変換する */
 export function instantToCivil(epochMilliseconds, timeZone) {
     if (!Number.isFinite(epochMilliseconds))
-        throw new RangeError("Invalid instant");
+        throw rangeError("invalid-time", "Invalid instant");
     const parts = formatterFor(timeZone).formatToParts(new Date(epochMilliseconds));
     const get = (type) => {
         const p = parts.find((x) => x.type === type);
         if (!p)
-            throw new RangeError(`Cannot resolve ${type} in ${timeZone}`);
+            throw rangeError("invalid-time-zone", `Cannot resolve ${type} in ${timeZone}`);
         return Number(p.value);
     };
     return {
@@ -59,7 +63,7 @@ function wallTime(hour, minute) {
         !Number.isInteger(minute) ||
         minute < 0 ||
         minute > 59) {
-        throw new RangeError(`Invalid time: ${hour}:${minute}`);
+        throw rangeError("invalid-time", `Invalid time: ${hour}:${minute}`);
     }
     return hour * 60 + minute;
 }
@@ -70,21 +74,23 @@ function parseString(value, timeZone) {
     }
     const m = DATETIME_RE.exec(value);
     if (!m) {
-        throw new RangeError(`Invalid date/time string: ${JSON.stringify(value)} (expected YYYY-MM-DD or ISO 8601 date-time)`);
+        throw rangeError(/^\d{4}-\d{2}-\d{2}[T ]/i.test(value) ? "invalid-time" : "invalid-date", `Invalid date/time string: ${JSON.stringify(value)} (expected YYYY-MM-DD or ISO 8601 date-time)`);
     }
     const date = m[1];
     parseDate(date);
     const minutes = wallTime(Number(m[2]), Number(m[3]));
-    if (m[4] !== undefined && Number(m[4]) > 59)
-        throw new RangeError(`Invalid time: ${value}`);
+    if (m[4] !== undefined && Number(m[4]) > 59) {
+        throw rangeError("invalid-time", `Invalid time: ${value}`);
+    }
     const offset = m[5];
     if (offset === undefined)
         return { date, minutes };
     // オフセット付きは瞬間として扱う
     const normalized = value.replace(" ", "T").replace(/([+-]\d{2})(\d{2})$/, "$1:$2");
     const ms = Date.parse(normalized);
-    if (Number.isNaN(ms))
-        throw new RangeError(`Invalid date/time string: ${JSON.stringify(value)}`);
+    if (Number.isNaN(ms)) {
+        throw rangeError("invalid-time", `Invalid date/time string: ${JSON.stringify(value)}`);
+    }
     return instantToCivil(ms, timeZone);
 }
 function isInstantLike(value) {
@@ -94,18 +100,25 @@ function isDateLike(value) {
     const v = value;
     return typeof v.year === "number" && typeof v.month === "number" && typeof v.day === "number";
 }
-/** 入力をタイムゾーンでの暦日と時刻に変換する */
+/**
+ * Date か（iframe や vm など、別の実行環境で作られた Date も含む）。
+ * instanceof は実行環境ごとに Date が別物になるため使わない
+ */
+function isDate(value) {
+    return Object.prototype.toString.call(value) === "[object Date]";
+}
+/** @internal 入力をタイムゾーンでの暦日と時刻に変換する */
 export function toCivil(input, timeZone) {
     if (typeof input === "string")
         return parseString(input, timeZone);
-    if (input instanceof Date)
-        return instantToCivil(input.getTime(), timeZone);
+    if (isDate(input))
+        return instantToCivil(Date.prototype.getTime.call(input), timeZone);
     if (typeof input === "object" && input !== null) {
         if (isInstantLike(input))
             return instantToCivil(input.epochMilliseconds, timeZone);
         if (isDateLike(input)) {
             if (input.calendarId !== undefined && input.calendarId !== "iso8601") {
-                throw new RangeError(`Unsupported calendar: ${input.calendarId} (only iso8601)`);
+                throw rangeError("invalid-input", `Unsupported calendar: ${input.calendarId} (only iso8601)`);
             }
             const date = formatDate(input.year, input.month, input.day);
             if (typeof input.hour === "number") {
@@ -114,16 +127,31 @@ export function toCivil(input, timeZone) {
             return { date, minutes: null };
         }
     }
-    throw new TypeError("Unsupported date input: expected a YYYY-MM-DD string, an ISO 8601 date-time string, a Date, or a Temporal object");
+    throw typeError("invalid-input", "Unsupported date input: expected a YYYY-MM-DD string, an ISO 8601 date-time string, a Date, or a Temporal object");
 }
-/** 入力を、タイムゾーンでの暦日 "YYYY-MM-DD" に変換する */
+/**
+ * 入力を、タイムゾーンでの暦日 "YYYY-MM-DD" に変換する。
+ * @public
+ */
 export function toDateString(input, timeZone) {
     return toCivil(input, validateTimeZone(timeZone)).date;
 }
-/** "HH:mm" を 0 時からの経過分に変換する（00:00〜23:59） */
+/**
+ * 入力を、タイムゾーンでの暦日と時刻（"HH:mm"。暦日だけの入力では null）に変換する。
+ * @public
+ */
+export function toDateTimeParts(input, timeZone) {
+    const civil = toCivil(input, validateTimeZone(timeZone));
+    const time = civil.minutes === null
+        ? null
+        : `${String(Math.floor(civil.minutes / 60)).padStart(2, "0")}:${String(civil.minutes % 60).padStart(2, "0")}`;
+    return Object.freeze({ date: civil.date, time });
+}
+/** @internal "HH:mm" を 0 時からの経過分に変換する（00:00〜23:59） */
 export function parseTimeOfDay(value) {
     const m = /^(\d{2}):(\d{2})$/.exec(value);
-    if (!m)
-        throw new RangeError(`Invalid time of day: ${JSON.stringify(value)} (expected HH:mm)`);
+    if (!m) {
+        throw rangeError("invalid-time", `Invalid time of day: ${JSON.stringify(value)} (expected HH:mm)`);
+    }
     return wallTime(Number(m[1]), Number(m[2]));
 }

package/dist/core/schedule.d.ts

@@ -0,0 +1,224 @@
+/**
+ * 日ごとに値を返すスケジュール（営業時間・受付枠など、曜日・祝日・特定日で変わるもの）。
+ *
+ * 1 日の値は次の優先順位で決まる（上が優先）:
+ *   1. dates   … 個別の日付・期間（配列で先に書いたものが優先）
+ *   2. annual  … 毎年の月日・月日の期間（年をまたぐ期間も可。配列で先に書いたものが優先）
+ *   3. 祝日     … holiday の規則（"weekday": 曜日どおり / { sameAs: 曜日 }: その曜日の値 / { value }: 指定の値）
+ *   4. weekly  … 曜日ごとの値
+ *
+ * 営業日カレンダー（createCalendar）は、このスケジュールの真偽値版として作られている。
+ */
+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";
+/**
+ * 祝日の値の決め方。
+ * @public
+ */
+export type HolidayRule<T> = 
+/** 祝日を考えず、曜日の値を使う */
+"weekday"
+/** 指定した曜日の値を使う（例: 祝日は日曜日の営業時間） */
+ | {
+    readonly sameAs: Weekday;
+}
+/** 指定した値を使う */
+ | {
+    readonly value: T;
+};
+/**
+ * 毎年の月日 "MM-DD" の値。
+ * @public
+ */
+export interface AnnualValue<T> {
+    readonly date: string;
+    readonly value: T;
+    readonly name?: string;
+}
+/**
+ * 毎年の月日の期間の値（from > to なら年をまたぐ。例: 12-31 〜 01-03）。
+ * @public
+ */
+export interface AnnualRangeValue<T> {
+    readonly from: string;
+    readonly to: string;
+    readonly value: T;
+    readonly name?: string;
+}
+/**
+ * 個別の日付 "YYYY-MM-DD" の値。
+ * @public
+ */
+export interface DateValue<T> {
+    readonly date: DateString;
+    readonly value: T;
+    readonly name?: string;
+}
+/**
+ * 個別の日付の期間（両端を含む）の値。
+ * @public
+ */
+export interface DateRangeValue<T> {
+    readonly from: DateString;
+    readonly to: DateString;
+    readonly value: T;
+    readonly name?: string;
+}
+/**
+ * 祝日の提供元とタイムゾーンの設定（スケジュールと営業日カレンダーで共通）。
+ * @public
+ */
+export interface HolidaySourceOptions<Kind extends string = string> {
+    /** 祝日の提供元（例: jp）。複数渡すと和集合になる */
+    readonly holidays?: HolidayProvider<Kind> | readonly HolidayProvider<Kind>[];
+    /**
+     * 日時の入力（Date・オフセット付き文字列など）を暦日に変換するタイムゾーン。
+     * 省略時は祝日の提供元のタイムゾーン、提供元もなければ "UTC"
+     */
+    readonly timeZone?: string;
+    /** 祝日の提供元の対応年を外れた日付の扱い（既定: "throw"） */
+    readonly outOfRange?: "throw" | "ignore";
+}
+/**
+ * スケジュールの設定。
+ * @public
+ */
+export interface ScheduleOptions<T, Kind extends string = string> extends HolidaySourceOptions<Kind> {
+    /** 曜日ごとの値（[日, 月, 火, 水, 木, 金, 土]） */
+    readonly weekly: readonly [T, T, T, T, T, T, T];
+    /** 祝日の値の決め方（既定: "weekday"） */
+    readonly holiday?: HolidayRule<T>;
+    /** 毎年の月日の値 */
+    readonly annual?: readonly (AnnualValue<T> | AnnualRangeValue<T>)[];
+    /** 個別の日付の値 */
+    readonly dates?: readonly (DateValue<T> | DateRangeValue<T>)[];
+}
+/**
+ * 値を決めた規則（既知の値）。
+ * @public
+ */
+export type KnownScheduleReason = "date" | "annual" | "holiday" | "weekday";
+/**
+ * 値を決めた規則。将来の版で値が増えることがあるので、分岐では「その他」も扱うこと。
+ * すべての値を網羅したことを型で確かめたい場合は KnownScheduleReason を使う。
+ * @public
+ */
+export type ScheduleReason = KnownScheduleReason | (string & {});
+/**
+ * 1 日分の値と、その値を決めた規則。
+ * @public
+ */
+export interface ScheduleDay<T, Kind extends string = string> {
+    readonly date: DateString;
+    readonly weekday: Weekday;
+    readonly value: T;
+    /** 値を決めた規則 */
+    readonly reason: ScheduleReason;
+    /** 値を決めた規則の名前（dates・annual の name、祝日なら祝日名） */
+    readonly name?: string;
+    /** その日が祝日なら祝日（holiday の規則に関係なく付く） */
+    readonly holiday?: Holiday<Kind>;
+}
+/**
+ * 暦日と時刻（カレンダーのタイムゾーン）。
+ * @public
+ */
+export interface CivilDateTimeParts {
+    /** 暦日 "YYYY-MM-DD" */
+    readonly date: DateString;
+    /** 時刻 "HH:mm"。暦日だけの入力では null */
+    readonly time: string | null;
+}
+/**
+ * 祝日を調べる機能（スケジュールと営業日カレンダーで共通）。
+ * @public
+ */
+export interface HolidayLookup<Kind extends string = string> {
+    /** 日時の入力を暦日に変換するタイムゾーン */
+    readonly timeZone: string;
+    /** 祝日の提供元 */
+    readonly providers: readonly HolidayProvider<Kind>[];
+    /** 入力をタイムゾーンでの暦日に変換する */
+    dateOf(input: DateInput): DateString;
+    /** 入力をタイムゾーンでの暦日と時刻に変換する */
+    civilOf(input: DateInput): CivilDateTimeParts;
+    /** 今日の日付（タイムゾーン） */
+    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 Schedule<T, Kind extends string = string> extends HolidayLookup<Kind> {
+    /** その日の値 */
+    valueOn(input: DateInput): T;
+    /** その日の値と、値を決めた規則 */
+    dayInfo(input: DateInput): ScheduleDay<T, Kind>;
+}
+/** @internal "MM-DD" として正しいか（2 月 29 日は可） */
+export declare function isValidMonthDay(value: unknown): value is string;
+/** @internal 曜日の番号として正しいか */
+export declare const isWeekday: (value: unknown) => value is Weekday;
+/** @internal 個別の日付の規則（日数で表した期間） */
+export interface DateRule<T> {
+    readonly from: number;
+    readonly to: number;
+    readonly value: T;
+    readonly name: string | undefined;
+}
+/** @internal 毎年の月日の規則 */
+export interface AnnualRule<T> {
+    readonly from: string;
+    readonly to: string;
+    readonly value: T;
+    readonly name: string | undefined;
+}
+/**
+ * @internal 個別の日付の規則を検証して取り込む。
+ * entry は "YYYY-MM-DD"・{ date }・{ from, to } のいずれか。値は valueOf で決める
+ */
+export declare function compileDateRules<T>(c: IssueCollector, path: string, entries: unknown, valueOf: (entry: Record<string, unknown>, path: string) => T | undefined, allowString: boolean): DateRule<T>[];
+/** @internal 毎年の月日の規則を検証して取り込む（entry は "MM-DD"・{ date }・{ from, to }） */
+export declare function compileAnnualRules<T>(c: IssueCollector, path: string, entries: unknown, valueOf: (entry: Record<string, unknown>, path: string) => T | undefined, allowString: boolean): AnnualRule<T>[];
+/** @internal 祝日の提供元とタイムゾーンの設定を検証した結果 */
+export interface HolidaySource<Kind extends string> {
+    readonly providers: readonly HolidayProvider<Kind>[];
+    readonly timeZone: string;
+    readonly outOfRange: "throw" | "ignore";
+}
+/** @internal 祝日の提供元とタイムゾーンの設定を検証する */
+export declare function compileHolidaySource<Kind extends string>(c: IssueCollector, options: Record<string, unknown>): HolidaySource<Kind>;
+/** @internal 祝日を調べる機能を作る（設定は検証済みであること） */
+export declare function createHolidayLookup<Kind extends string>(source: HolidaySource<Kind>): HolidayLookup<Kind> & {
+    holidayOn(date: DateString): Holiday<Kind> | undefined;
+};
+/** @internal 検証済みのスケジュールの規則 */
+export interface CompiledSchedule<T, Kind extends string> {
+    readonly source: HolidaySource<Kind>;
+    readonly weekly: readonly T[];
+    readonly holiday: HolidayRule<T>;
+    readonly annual: readonly AnnualRule<T>[];
+    readonly dates: readonly DateRule<T>[];
+}
+/** @internal スケジュールの設定を検証して取り込む（誤りは c に集める） */
+export declare function compileScheduleOptions<T, Kind extends string>(c: IssueCollector, options: unknown): CompiledSchedule<T, Kind> | undefined;
+/** @internal 検証済みの規則からスケジュールを作る */
+export declare function buildSchedule<T, Kind extends string>(compiled: CompiledSchedule<T, Kind>): Schedule<T, Kind>;
+/**
+ * 曜日・祝日・特定日の規則から、日ごとに値を返すスケジュールを作る。
+ *
+ * 設定は作る時点で複製されるので、あとから元の配列やオブジェクトを書き換えても結果は変わらない
+ * （値 T そのものは複製しない）。設定の誤りは code 付きの RangeError になる。
+ * @public
+ */
+export declare function createSchedule<T, Kind extends string = string>(options: ScheduleOptions<T, Kind>): Schedule<T, Kind>;