bizdays-toolkit 0.2.0 → 0.3.0

package/dist/core/errors.js

@@ -0,0 +1,61 @@
+/**
+ * コード付きの例外と、入力の問題を集める仕組み。
+ *
+ * 例外は従来どおり RangeError・TypeError・Error のインスタンスで、code プロパティを持つ。
+ * 例外のメッセージの文言は API に含まない（変わることがある）。判定には code を使う。
+ */
+/**
+ * このライブラリが投げた例外（code 付き）か。
+ * @public
+ */
+export function isBizdaysError(error) {
+    return (error instanceof Error &&
+        typeof error.code === "string" &&
+        error.bizdays === true);
+}
+function withCode(error, code) {
+    Object.defineProperty(error, "code", { value: code, enumerable: true });
+    Object.defineProperty(error, "bizdays", { value: true, enumerable: false });
+    return error;
+}
+/** @internal */
+export function rangeError(code, message) {
+    return withCode(new RangeError(message), code);
+}
+/** @internal */
+export function typeError(code, message) {
+    return withCode(new TypeError(message), code);
+}
+/** @internal */
+export function plainError(code, message) {
+    return withCode(new Error(message), code);
+}
+/** @internal 問題を集める */
+export class IssueCollector {
+    issues = [];
+    error(code, path, message) {
+        this.issues.push({ severity: "error", code, path, message });
+    }
+    warning(code, path, message) {
+        this.issues.push({ severity: "warning", code, path, message });
+    }
+    get hasErrors() {
+        return this.issues.some((i) => i.severity === "error");
+    }
+    /** 最初の誤りを例外にして投げる（誤りがなければ何もしない） */
+    throwFirstError() {
+        const first = this.issues.find((i) => i.severity === "error");
+        if (!first)
+            return;
+        const message = first.path ? `${first.path}: ${first.message}` : first.message;
+        throw rangeError(first.code, message);
+    }
+}
+/** @internal 設定のオブジェクトに、知らないキーがあれば警告として記録する */
+export function checkUnknownKeys(collector, path, value, known) {
+    for (const key of Object.keys(value)) {
+        if (!known.includes(key)) {
+            collector.warning("unknown-option", path ? `${path}.${key}` : key, `Unknown option ${JSON.stringify(key)} is ignored`);
+        }
+    }
+}

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,30 +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"。暦日だけの入力では null）に変換する */
+/**
+ * 入力を、タイムゾーンでの暦日と時刻（"HH:mm"。暦日だけの入力では null）に変換する。
+ * @public
+ */
 export declare function toDateTimeParts(input: DateInput, timeZone: string): {
     readonly date: DateString;
     readonly time: string | null;
 };
-/** "HH:mm" を 0 時からの経過分に変換する（00:00〜23:59） */
+/** @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,13 +127,19 @@ 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"。暦日だけの入力では null）に変換する */
+/**
+ * 入力を、タイムゾーンでの暦日と時刻（"HH:mm"。暦日だけの入力では null）に変換する。
+ * @public
+ */
 export function toDateTimeParts(input, timeZone) {
     const civil = toCivil(input, validateTimeZone(timeZone));
     const time = civil.minutes === null
@@ -128,10 +147,11 @@ export function toDateTimeParts(input, timeZone) {
         : `${String(Math.floor(civil.minutes / 60)).padStart(2, "0")}:${String(civil.minutes % 60).padStart(2, "0")}`;
     return Object.freeze({ date: civil.date, time });
 }
-/** "HH:mm" を 0 時からの経過分に変換する（00:00〜23:59） */
+/** @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

@@ -10,9 +10,13 @@
  * 営業日カレンダー（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"
@@ -24,33 +28,48 @@ export type HolidayRule<T> =
  | {
     readonly value: T;
 };
-/** 毎年の月日 "MM-DD" の値 */
+/**
+ * 毎年の月日 "MM-DD" の値。
+ * @public
+ */
 export interface AnnualValue<T> {
     readonly date: string;
     readonly value: T;
     readonly name?: string;
 }
-/** 毎年の月日の期間の値（from > to なら年をまたぐ。例: 12-31 〜 01-03） */
+/**
+ * 毎年の月日の期間の値（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" の値 */
+/**
+ * 個別の日付 "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>[];
@@ -62,6 +81,10 @@ export interface HolidaySourceOptions<Kind extends string = 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];
@@ -72,9 +95,21 @@ export interface ScheduleOptions<T, Kind extends string = string> extends Holida
     /** 個別の日付の値 */
     readonly dates?: readonly (DateValue<T> | DateRangeValue<T>)[];
 }
-/** 値を決めた規則 */
-export type ScheduleReason = "date" | "annual" | "holiday" | "weekday";
-/** 1 日分の値と、その値を決めた規則 */
+/**
+ * 値を決めた規則（既知の値）。
+ * @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;
@@ -86,14 +121,20 @@ export interface ScheduleDay<T, Kind extends string = 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;
@@ -114,17 +155,70 @@ export interface HolidayLookup<Kind extends string = string> {
     /** 期間内の祝日（両端を含む） */
     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>;
 }
-/** "MM-DD" を検証する（2 月 29 日は可） */
-export declare function parseMonthDay(value: string): string;
-/** 祝日を調べる機能を作る（スケジュールと営業日カレンダーで共通） */
-export declare function createHolidayLookup<Kind extends string>(options: HolidaySourceOptions<Kind>): HolidayLookup<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>;