xypriss 9.10.19 → 9.10.21

package/dist/src/xhsc/utils/DateUtils.js

@@ -1,956 +0,0 @@
-/**
- * @file DateUtils.ts
- * @description XyPriss Date & Time Utilities — A comprehensive, zero-dependency
- * date/time utility class built on the native `Date` object and the `Intl` API.
- *
- * @remarks
- * All methods are pure and side-effect-free unless otherwise noted.
- * Timestamps can be provided in either **seconds** (Unix) or **milliseconds**
- * (JavaScript). The class auto-detects the unit using the heuristic:
- * values below `1e11` are treated as seconds; values at or above `1e11` are
- * treated as milliseconds. This heuristic is valid until **November 2286**.
- *
- * @example
- * ```ts
- * const du = new DateUtils();
- *
- * du.format(Date.now());            // "Apr 15, 2026"
- * du.timeAgo(Date.now() - 90_000); // "2 minutes ago"
- * du.formatDuration(3_661_000);    // "1h 1m 1s"
- * du.startOf("month");             // 2026-04-01T00:00:00.000Z
- * ```
- */
-export class DateUtils {
-    // ─────────────────────────────────────────────
-    //  Internal helpers
-    // ─────────────────────────────────────────────
-    /**
-     * Converts any supported input value to a `Date` object.
-     *
-     * Supported inputs:
-     * - `Date` — returned as-is (not cloned).
-     * - `number` — auto-detected as Unix seconds (`< 1e11`) or milliseconds.
-     * - `string` — parsed via `new Date(string)` (ISO 8601 recommended).
-     *
-     * @param date - The value to convert.
-     * @returns The corresponding `Date` object.
-     * @throws {RangeError} If the resulting `Date` is invalid.
-     *
-     * @internal
-     */
-    toDate(date) {
-        let d;
-        if (date instanceof Date) {
-            d = date;
-        }
-        else if (typeof date === "number") {
-            // Heuristic: Unix timestamps (seconds) are currently ~1.7e9.
-            // JavaScript timestamps (ms) are ~1.7e12.
-            // Values below 1e11 are assumed to be in seconds.
-            const ms = date < 100000000000 ? date * 1000 : date;
-            d = new Date(ms);
-        }
-        else {
-            d = new Date(date);
-        }
-        if (isNaN(d.getTime())) {
-            throw new RangeError(`DateUtils: invalid date value — "${date}"`);
-        }
-        return d;
-    }
-    /**
-     * Converts any supported input value to a millisecond timestamp.
-     *
-     * @param date - The value to convert.
-     * @returns Milliseconds since the Unix epoch.
-     *
-     * @internal
-     */
-    toMs(date) {
-        return this.toDate(date).getTime();
-    }
-    // ─────────────────────────────────────────────
-    //  Current time
-    // ─────────────────────────────────────────────
-    /**
-     * Returns the current Unix timestamp in **seconds**.
-     *
-     * @returns The current time as a Unix timestamp (integer seconds).
-     *
-     * @example
-     * ```ts
-     * du.now(); // e.g. 1776287197
-     * ```
-     */
-    now() {
-        return Math.floor(Date.now() / 1000);
-    }
-    /**
-     * Returns the current time as a JavaScript timestamp in **milliseconds**.
-     *
-     * Equivalent to `Date.now()`.
-     *
-     * @returns The current time in milliseconds since the Unix epoch.
-     *
-     * @example
-     * ```ts
-     * du.nowMs(); // e.g. 1776287197000
-     * ```
-     */
-    nowMs() {
-        return Date.now();
-    }
-    /**
-     * Returns the current time as a `Date` object.
-     *
-     * @returns A new `Date` representing the current instant.
-     *
-     * @example
-     * ```ts
-     * du.today(); // Date { ... }
-     * ```
-     */
-    today() {
-        return new Date();
-    }
-    // ─────────────────────────────────────────────
-    //  Formatting
-    // ─────────────────────────────────────────────
-    /**
-     * Serializes a date value into a localized string using `Intl.DateTimeFormat`.
-     *
-     * Automatically handles Unix timestamps (seconds) and JavaScript timestamps
-     * (milliseconds) via the `< 1e11` heuristic.
-     *
-     * @param date    - The input to format: `Date`, number (timestamp), or ISO string.
-     * @param locale  - BCP 47 locale tag (default: `"en-US"`).
-     * @param options - `Intl.DateTimeFormatOptions` to customize the output.
-     * @returns A localized date string.
-     *
-     * @example
-     * ```ts
-     * du.format(1776287197);
-     * // → "Apr 15, 2026"
-     *
-     * du.format(new Date(), "fr-FR", { dateStyle: "full" });
-     * // → "mercredi 15 avril 2026"
-     *
-     * du.format("2026-04-15T12:00:00Z", "en-GB", { timeStyle: "short" });
-     * // → "12:00"
-     * ```
-     */
-    format(date, locale = "en-US", options = { dateStyle: "long" }) {
-        return new Intl.DateTimeFormat(locale, options).format(this.toDate(date));
-    }
-    /**
-     * Formats a date as an ISO 8601 string (`YYYY-MM-DDTHH:mm:ss.sssZ`).
-     *
-     * This is the format recommended for data interchange and storage.
-     *
-     * @param date - The date to format (default: current time).
-     * @returns An ISO 8601 UTC string.
-     *
-     * @example
-     * ```ts
-     * du.toISO();
-     * // → "2026-04-15T10:30:00.000Z"
-     *
-     * du.toISO(1776287197);
-     * // → "2026-04-15T..."
-     * ```
-     */
-    toISO(date = new Date()) {
-        return this.toDate(date).toISOString();
-    }
-    /**
-     * Formats a date as a plain date string: `YYYY-MM-DD`.
-     *
-     * The date is rendered in **local time** unless a UTC flag is set.
-     *
-     * @param date - The date to format (default: current time).
-     * @param utc  - If `true`, use UTC date components instead of local time (default: `false`).
-     * @returns A date-only string in `YYYY-MM-DD` format.
-     *
-     * @example
-     * ```ts
-     * du.toDateString();
-     * // → "2026-04-15"
-     *
-     * du.toDateString(new Date("2026-12-31T23:59:00Z"), true);
-     * // → "2026-12-31"
-     * ```
-     */
-    toDateString(date = new Date(), utc = false) {
-        const d = this.toDate(date);
-        const y = utc ? d.getUTCFullYear() : d.getFullYear();
-        const m = String(utc ? d.getUTCMonth() + 1 : d.getMonth() + 1).padStart(2, "0");
-        const day = String(utc ? d.getUTCDate() : d.getDate()).padStart(2, "0");
-        return `${y}-${m}-${day}`;
-    }
-    /**
-     * Formats a date as a time string: `HH:mm:ss`.
-     *
-     * The time is rendered in **local time** unless the UTC flag is set.
-     *
-     * @param date - The date to format (default: current time).
-     * @param utc  - If `true`, use UTC time components (default: `false`).
-     * @returns A time-only string in `HH:mm:ss` format.
-     *
-     * @example
-     * ```ts
-     * du.toTimeString(new Date("2026-04-15T08:05:03Z"), true);
-     * // → "08:05:03"
-     * ```
-     */
-    toTimeString(date = new Date(), utc = false) {
-        const d = this.toDate(date);
-        const h = String(utc ? d.getUTCHours() : d.getHours()).padStart(2, "0");
-        const min = String(utc ? d.getUTCMinutes() : d.getMinutes()).padStart(2, "0");
-        const sec = String(utc ? d.getUTCSeconds() : d.getSeconds()).padStart(2, "0");
-        return `${h}:${min}:${sec}`;
-    }
-    /**
-     * Converts a duration into a human-readable string (e.g., `"1d 2h 30m 5s"`).
-     *
-     * Components are omitted when their value is zero, except for seconds which
-     * always appear when the total duration is less than one minute.
-     *
-     * @param value - The duration to format.
-     * @param unit  - The unit of `value`: `"ms"` (milliseconds, default) or `"s"` (seconds).
-     * @returns A compact, space-separated duration string.
-     *
-     * @example
-     * ```ts
-     * du.formatDuration(3_661_000);       // → "1h 1m 1s"
-     * du.formatDuration(90, "s");         // → "1m 30s"
-     * du.formatDuration(0);              // → "0s"
-     * du.formatDuration(86_400_000);     // → "1d"
-     * ```
-     */
-    formatDuration(value, unit = "ms") {
-        const ms = unit === "s" ? value * 1000 : value;
-        const seconds = Math.floor((ms / 1000) % 60);
-        const minutes = Math.floor((ms / (1000 * 60)) % 60);
-        const hours = Math.floor((ms / (1000 * 60 * 60)) % 24);
-        const days = Math.floor(ms / (1000 * 60 * 60 * 24));
-        const parts = [];
-        if (days > 0)
-            parts.push(`${days}d`);
-        if (hours > 0)
-            parts.push(`${hours}h`);
-        if (minutes > 0)
-            parts.push(`${minutes}m`);
-        if (seconds > 0 || parts.length === 0)
-            parts.push(`${seconds}s`);
-        return parts.join(" ");
-    }
-    /**
-     * Returns a relative time string (e.g., `"5 minutes ago"`, `"in 2 hours"`).
-     *
-     * Uses `Intl.RelativeTimeFormat` for locale-aware output. Automatically
-     * selects the most appropriate unit (second → minute → hour → day → month → year).
-     *
-     * @param date   - The reference date, in the past or future.
-     * @param locale - BCP 47 locale tag (default: `"en-US"`).
-     * @returns A localized relative time string.
-     *
-     * @example
-     * ```ts
-     * du.timeAgo(Date.now() - 90_000);       // → "2 minutes ago"
-     * du.timeAgo(Date.now() + 3_600_000);    // → "in 1 hour"
-     * du.timeAgo(Date.now() - 90_000, "fr"); // → "il y a 2 minutes"
-     * ```
-     */
-    timeAgo(date, locale = "en-US") {
-        const ms = this.toMs(date);
-        const deltaSeconds = Math.floor((Date.now() - ms) / 1000);
-        const rtf = new Intl.RelativeTimeFormat(locale, { numeric: "auto" });
-        if (Math.abs(deltaSeconds) < 60)
-            return rtf.format(-deltaSeconds, "second");
-        const minutes = Math.floor(deltaSeconds / 60);
-        if (Math.abs(minutes) < 60)
-            return rtf.format(-minutes, "minute");
-        const hours = Math.floor(minutes / 60);
-        if (Math.abs(hours) < 24)
-            return rtf.format(-hours, "hour");
-        const days = Math.floor(hours / 24);
-        if (Math.abs(days) < 30)
-            return rtf.format(-days, "day");
-        const months = Math.floor(days / 30);
-        if (Math.abs(months) < 12)
-            return rtf.format(-months, "month");
-        const years = Math.floor(months / 12);
-        return rtf.format(-years, "year");
-    }
-    // ─────────────────────────────────────────────
-    //  Arithmetic
-    // ─────────────────────────────────────────────
-    /**
-     * Adds a given amount of time to a date and returns a new `Date`.
-     *
-     * Supported units: `"ms"`, `"s"` (seconds), `"m"` (minutes), `"h"` (hours),
-     * `"d"` (days), `"w"` (weeks), `"mo"` (months), `"y"` (years).
-     *
-     * Month and year arithmetic is handled using `setMonth` / `setFullYear`,
-     * which correctly accounts for varying month lengths (e.g., adding 1 month
-     * to January 31 yields February 28/29).
-     *
-     * @param date  - The starting date.
-     * @param value - The amount to add (can be negative to subtract).
-     * @param unit  - The time unit.
-     * @returns A new `Date` offset by the specified amount.
-     *
-     * @example
-     * ```ts
-     * du.add(new Date("2026-01-31"), 1, "mo");
-     * // → Date("2026-02-28") — accounts for shorter February
-     *
-     * du.add(new Date("2026-04-15"), -7, "d");
-     * // → Date("2026-04-08")
-     *
-     * du.add(Date.now(), 2, "h");
-     * // → Date 2 hours from now
-     * ```
-     */
-    add(date, value, unit) {
-        const d = new Date(this.toMs(date));
-        switch (unit) {
-            case "ms":
-                d.setMilliseconds(d.getMilliseconds() + value);
-                break;
-            case "s":
-                d.setSeconds(d.getSeconds() + value);
-                break;
-            case "m":
-                d.setMinutes(d.getMinutes() + value);
-                break;
-            case "h":
-                d.setHours(d.getHours() + value);
-                break;
-            case "d":
-                d.setDate(d.getDate() + value);
-                break;
-            case "w":
-                d.setDate(d.getDate() + value * 7);
-                break;
-            case "mo": {
-                const day = d.getDate();
-                d.setMonth(d.getMonth() + value);
-                if (d.getDate() !== day) {
-                    d.setDate(0);
-                }
-                break;
-            }
-            case "y": {
-                const day = d.getDate();
-                const month = d.getMonth();
-                d.setFullYear(d.getFullYear() + value);
-                if (d.getMonth() !== month) {
-                    d.setDate(0);
-                }
-                break;
-            }
-        }
-        return d;
-    }
-    /**
-     * Subtracts a given amount of time from a date and returns a new `Date`.
-     *
-     * This is a convenience wrapper around {@link add} with a negated `value`.
-     *
-     * @param date  - The starting date.
-     * @param value - The amount to subtract (must be positive).
-     * @param unit  - The time unit (same options as {@link add}).
-     * @returns A new `Date` shifted back by the specified amount.
-     *
-     * @example
-     * ```ts
-     * du.subtract(new Date("2026-03-01"), 1, "mo");
-     * // → Date("2026-02-01")
-     * ```
-     */
-    subtract(date, value, unit) {
-        return this.add(date, -value, unit);
-    }
-    // ─────────────────────────────────────────────
-    //  Difference & comparison
-    // ─────────────────────────────────────────────
-    /**
-     * Returns the difference between two dates in the specified unit.
-     *
-     * The result is the **signed** difference `(dateA - dateB)` truncated
-     * toward zero. A positive value means `dateA` is later than `dateB`.
-     *
-     * Supported units: `"ms"`, `"s"`, `"m"`, `"h"`, `"d"`, `"w"`.
-     * Month and year differences are intentionally excluded because their
-     * variable length makes a lossless inverse impossible; use {@link add}
-     * and calendar-aware logic for those cases.
-     *
-     * @param dateA - The first date.
-     * @param dateB - The second date.
-     * @param unit  - The unit for the result (default: `"ms"`).
-     * @returns The signed integer difference in the requested unit.
-     *
-     * @example
-     * ```ts
-     * du.diff("2026-04-20", "2026-04-15", "d");  // → 5
-     * du.diff("2026-04-10", "2026-04-15", "d");  // → -5
-     * du.diff(Date.now(), Date.now() - 3600_000, "h"); // → 1
-     * ```
-     */
-    diff(dateA, dateB, unit = "ms") {
-        const delta = this.toMs(dateA) - this.toMs(dateB);
-        const divisors = {
-            ms: 1,
-            s: 1000,
-            m: 60000,
-            h: 3600000,
-            d: 86400000,
-            w: 604800000,
-        };
-        return Math.trunc(delta / divisors[unit]);
-    }
-    /**
-     * Returns `true` if `dateA` is strictly before `dateB`.
-     *
-     * @param dateA - The first date.
-     * @param dateB - The second date.
-     * @returns `true` if `dateA < dateB`.
-     *
-     * @example
-     * ```ts
-     * du.isBefore("2026-01-01", "2026-06-01"); // → true
-     * ```
-     */
-    isBefore(dateA, dateB) {
-        return this.toMs(dateA) < this.toMs(dateB);
-    }
-    /**
-     * Returns `true` if `dateA` is strictly after `dateB`.
-     *
-     * @param dateA - The first date.
-     * @param dateB - The second date.
-     * @returns `true` if `dateA > dateB`.
-     *
-     * @example
-     * ```ts
-     * du.isAfter("2026-12-31", "2026-06-01"); // → true
-     * ```
-     */
-    isAfter(dateA, dateB) {
-        return this.toMs(dateA) > this.toMs(dateB);
-    }
-    /**
-     * Returns `true` if two dates represent the same instant in time.
-     *
-     * Comparison is performed at millisecond precision.
-     *
-     * @param dateA - The first date.
-     * @param dateB - The second date.
-     * @returns `true` if both dates resolve to the same millisecond.
-     *
-     * @example
-     * ```ts
-     * du.isSame(new Date("2026-04-15"), 1776268800000); // → true (if same instant)
-     * ```
-     */
-    isSame(dateA, dateB) {
-        return this.toMs(dateA) === this.toMs(dateB);
-    }
-    /**
-     * Returns `true` if `date` falls within the range `[start, end]` (inclusive).
-     *
-     * @param date  - The date to test.
-     * @param start - The start of the range.
-     * @param end   - The end of the range.
-     * @returns `true` if `start ≤ date ≤ end`.
-     *
-     * @example
-     * ```ts
-     * du.isBetween("2026-04-15", "2026-01-01", "2026-12-31"); // → true
-     * du.isBetween("2025-12-31", "2026-01-01", "2026-12-31"); // → false
-     * ```
-     */
-    isBetween(date, start, end) {
-        const ms = this.toMs(date);
-        return ms >= this.toMs(start) && ms <= this.toMs(end);
-    }
-    // ─────────────────────────────────────────────
-    //  Boundary helpers
-    // ─────────────────────────────────────────────
-    /**
-     * Returns a new `Date` set to the **start** of the specified unit
-     * (i.e., all smaller components zeroed out).
-     *
-     * Supported units: `"day"`, `"week"` (Monday = start), `"month"`, `"year"`.
-     *
-     * @param unit - The boundary unit.
-     * @param date - The reference date (default: current time).
-     * @returns A new `Date` at the beginning of the unit.
-     *
-     * @example
-     * ```ts
-     * du.startOf("day");
-     * // → 2026-04-15T00:00:00.000 (local)
-     *
-     * du.startOf("month", new Date("2026-04-15"));
-     * // → 2026-04-01T00:00:00.000
-     *
-     * du.startOf("year", "2026-06-15");
-     * // → 2026-01-01T00:00:00.000
-     * ```
-     */
-    startOf(unit, date = new Date()) {
-        const d = new Date(this.toMs(date));
-        switch (unit) {
-            case "day":
-                d.setHours(0, 0, 0, 0);
-                break;
-            case "week": {
-                const day = d.getDay(); // 0 = Sunday
-                const diff = day === 0 ? -6 : 1 - day; // shift to Monday
-                d.setDate(d.getDate() + diff);
-                d.setHours(0, 0, 0, 0);
-                break;
-            }
-            case "month":
-                d.setDate(1);
-                d.setHours(0, 0, 0, 0);
-                break;
-            case "year":
-                d.setMonth(0, 1);
-                d.setHours(0, 0, 0, 0);
-                break;
-        }
-        return d;
-    }
-    /**
-     * Returns a new `Date` set to the **end** of the specified unit
-     * (i.e., the last millisecond of that unit).
-     *
-     * Supported units: `"day"`, `"week"` (Sunday = end), `"month"`, `"year"`.
-     *
-     * @param unit - The boundary unit.
-     * @param date - The reference date (default: current time).
-     * @returns A new `Date` at the very last millisecond of the unit.
-     *
-     * @example
-     * ```ts
-     * du.endOf("month", new Date("2026-02-01"));
-     * // → 2026-02-28T23:59:59.999
-     *
-     * du.endOf("year", "2026-01-01");
-     * // → 2026-12-31T23:59:59.999
-     * ```
-     */
-    endOf(unit, date = new Date()) {
-        const d = new Date(this.toMs(date));
-        switch (unit) {
-            case "day":
-                d.setHours(23, 59, 59, 999);
-                break;
-            case "week": {
-                const day = d.getDay();
-                const diff = day === 0 ? 0 : 7 - day; // shift to next Sunday
-                d.setDate(d.getDate() + diff);
-                d.setHours(23, 59, 59, 999);
-                break;
-            }
-            case "month":
-                d.setMonth(d.getMonth() + 1, 0); // day 0 of next month = last day of current
-                d.setHours(23, 59, 59, 999);
-                break;
-            case "year":
-                d.setMonth(11, 31);
-                d.setHours(23, 59, 59, 999);
-                break;
-        }
-        return d;
-    }
-    // ─────────────────────────────────────────────
-    //  Calendar queries
-    // ─────────────────────────────────────────────
-    /**
-     * Returns `true` if the given year is a leap year.
-     *
-     * A year is a leap year if it is divisible by 4, except for century years,
-     * which must also be divisible by 400.
-     *
-     * @param year - The four-digit year to test (default: current year).
-     * @returns `true` if the year is a leap year.
-     *
-     * @example
-     * ```ts
-     * du.isLeapYear(2024); // → true
-     * du.isLeapYear(2100); // → false
-     * du.isLeapYear(2000); // → true
-     * ```
-     */
-    isLeapYear(year = new Date().getFullYear()) {
-        return (year % 4 === 0 && year % 100 !== 0) || year % 400 === 0;
-    }
-    /**
-     * Returns the number of days in a given month of a given year.
-     *
-     * Correctly accounts for leap years when querying February.
-     *
-     * @param month - The 1-based month index (1 = January, 12 = December).
-     * @param year  - The four-digit year (default: current year).
-     * @returns The number of days in the specified month (28–31).
-     *
-     * @example
-     * ```ts
-     * du.daysInMonth(2, 2024); // → 29  (leap year)
-     * du.daysInMonth(2, 2023); // → 28
-     * du.daysInMonth(1, 2026); // → 31
-     * ```
-     */
-    daysInMonth(month, year = new Date().getFullYear()) {
-        // Day 0 of the next month equals the last day of the given month.
-        return new Date(year, month, 0).getDate();
-    }
-    /**
-     * Returns the ISO 8601 week number (1–53) for a given date.
-     *
-     * ISO 8601 defines Week 1 as the week containing the year's first Thursday.
-     * Weeks run Monday–Sunday. A date in early January may belong to the
-     * final week of the previous year (e.g., January 1, 2016 → Week 53 of 2015).
-     *
-     * @param date - The reference date (default: current time).
-     * @returns The ISO week number.
-     *
-     * @example
-     * ```ts
-     * du.weekNumber(new Date("2026-01-01")); // → 1
-     * du.weekNumber(new Date("2016-01-03")); // → 53 (belongs to 2015)
-     * ```
-     */
-    weekNumber(date = new Date()) {
-        const d = new Date(this.toMs(date));
-        // Set to nearest Thursday: current date + 4 - current day number (Mon=1 .. Sun=7)
-        d.setUTCDate(d.getUTCDate() + 4 - (d.getUTCDay() || 7));
-        const yearStart = new Date(Date.UTC(d.getUTCFullYear(), 0, 1));
-        return Math.ceil(((d.getTime() - yearStart.getTime()) / 86400000 + 1) / 7);
-    }
-    /**
-     * Returns the day of the year (1–366) for a given date.
-     *
-     * @param date - The reference date (default: current time).
-     * @returns An integer from 1 to 366.
-     *
-     * @example
-     * ```ts
-     * du.dayOfYear(new Date("2026-02-01")); // → 32
-     * du.dayOfYear(new Date("2026-12-31")); // → 365
-     * ```
-     */
-    dayOfYear(date = new Date()) {
-        const d = this.toDate(date);
-        const start = new Date(d.getFullYear(), 0, 0);
-        const diff = d.getTime() - start.getTime();
-        return Math.floor(diff / 86400000);
-    }
-    /**
-     * Returns the ISO 8601 quarter (1–4) in which the given date falls.
-     *
-     * @param date - The reference date (default: current time).
-     * @returns A quarter number: `1`, `2`, `3`, or `4`.
-     *
-     * @example
-     * ```ts
-     * du.quarter(new Date("2026-04-15")); // → 2  (Apr–Jun)
-     * du.quarter(new Date("2026-11-01")); // → 4  (Oct–Dec)
-     * ```
-     */
-    quarter(date = new Date()) {
-        return (Math.floor(this.toDate(date).getMonth() / 3) + 1);
-    }
-    /**
-     * Returns `true` if the given date falls on a weekend (Saturday or Sunday).
-     *
-     * The check uses **local time**.
-     *
-     * @param date - The date to check (default: current time).
-     * @returns `true` if the date is a Saturday or Sunday.
-     *
-     * @example
-     * ```ts
-     * du.isWeekend(new Date("2026-04-18")); // → true  (Saturday)
-     * du.isWeekend(new Date("2026-04-15")); // → false (Wednesday)
-     * ```
-     */
-    isWeekend(date = new Date()) {
-        const day = this.toDate(date).getDay();
-        return day === 0 || day === 6;
-    }
-    /**
-     * Returns `true` if the given date falls on a weekday (Monday–Friday).
-     *
-     * @param date - The date to check (default: current time).
-     * @returns `true` if the date is Monday through Friday.
-     *
-     * @example
-     * ```ts
-     * du.isWeekday(new Date("2026-04-15")); // → true
-     * du.isWeekday(new Date("2026-04-19")); // → false (Sunday)
-     * ```
-     */
-    isWeekday(date = new Date()) {
-        return !this.isWeekend(date);
-    }
-    /**
-     * Returns `true` if two dates fall on the same calendar day (in local time).
-     *
-     * Only the year, month, and date components are compared; time is ignored.
-     *
-     * @param dateA - The first date.
-     * @param dateB - The second date.
-     * @returns `true` if both dates share the same year, month, and day.
-     *
-     * @example
-     * ```ts
-     * du.isSameDay("2026-04-15T08:00:00", "2026-04-15T22:00:00"); // → true
-     * du.isSameDay("2026-04-15", "2026-04-16");                   // → false
-     * ```
-     */
-    isSameDay(dateA, dateB) {
-        const a = this.toDate(dateA);
-        const b = this.toDate(dateB);
-        return (a.getFullYear() === b.getFullYear() &&
-            a.getMonth() === b.getMonth() &&
-            a.getDate() === b.getDate());
-    }
-    /**
-     * Returns `true` if the given date is today (in local time).
-     *
-     * @param date - The date to test.
-     * @returns `true` if `date` falls on the current calendar day.
-     *
-     * @example
-     * ```ts
-     * du.isToday(new Date()); // → true
-     * du.isToday("2020-01-01"); // → false
-     * ```
-     */
-    isToday(date) {
-        return this.isSameDay(date, new Date());
-    }
-    /**
-     * Returns `true` if the given date is in the past (before the current instant).
-     *
-     * @param date - The date to check.
-     * @returns `true` if `date` is strictly before `Date.now()`.
-     *
-     * @example
-     * ```ts
-     * du.isPast("2020-01-01"); // → true
-     * du.isPast(Date.now() + 1000); // → false
-     * ```
-     */
-    isPast(date) {
-        return this.toMs(date) < Date.now();
-    }
-    /**
-     * Returns `true` if the given date is in the future (after the current instant).
-     *
-     * @param date - The date to check.
-     * @returns `true` if `date` is strictly after `Date.now()`.
-     *
-     * @example
-     * ```ts
-     * du.isFuture(Date.now() + 5000); // → true
-     * du.isFuture("2020-01-01");       // → false
-     * ```
-     */
-    isFuture(date) {
-        return this.toMs(date) > Date.now();
-    }
-    // ─────────────────────────────────────────────
-    //  Clamp & range utilities
-    // ─────────────────────────────────────────────
-    /**
-     * Clamps a date to a `[min, max]` range.
-     *
-     * If `date` is before `min`, `min` is returned.
-     * If `date` is after `max`, `max` is returned.
-     * Otherwise, `date` is returned unchanged (as a new `Date`).
-     *
-     * @param date - The date to clamp.
-     * @param min  - The lower bound.
-     * @param max  - The upper bound.
-     * @returns A new `Date` clamped within `[min, max]`.
-     *
-     * @example
-     * ```ts
-     * du.clamp("2025-01-01", "2026-01-01", "2026-12-31");
-     * // → Date("2026-01-01")  — clamped to min
-     *
-     * du.clamp("2026-06-15", "2026-01-01", "2026-12-31");
-     * // → Date("2026-06-15")  — within range, unchanged
-     * ```
-     */
-    clamp(date, min, max) {
-        const ms = Math.min(Math.max(this.toMs(date), this.toMs(min)), this.toMs(max));
-        return new Date(ms);
-    }
-    /**
-     * Generates an array of `Date` objects representing each day in the range
-     * `[start, end]`, inclusive.
-     *
-     * The range is capped at **3 650 days** (~10 years) to prevent accidental
-     * allocation of enormous arrays.
-     *
-     * @param start - The first day of the range.
-     * @param end   - The last day of the range.
-     * @returns An ordered array of `Date` objects, one per day.
-     * @throws {RangeError} If the range exceeds 3 650 days.
-     *
-     * @example
-     * ```ts
-     * du.dateRange("2026-04-13", "2026-04-15");
-     * // → [Date("2026-04-13"), Date("2026-04-14"), Date("2026-04-15")]
-     * ```
-     */
-    dateRange(start, end) {
-        const startMs = this.toMs(this.startOf("day", start));
-        const endMs = this.toMs(this.startOf("day", end));
-        const days = Math.round((endMs - startMs) / 86400000);
-        if (days < 0)
-            return [];
-        if (days > 3650) {
-            throw new RangeError(`DateUtils.dateRange: range of ${days} days exceeds the 3,650-day limit.`);
-        }
-        return Array.from({ length: days + 1 }, (_, i) => new Date(startMs + i * 86400000));
-    }
-    // ─────────────────────────────────────────────
-    //  Validation & parsing
-    // ─────────────────────────────────────────────
-    /**
-     * Returns `true` if the given value can be successfully interpreted
-     * as a valid, finite date.
-     *
-     * Accepts `Date`, `number`, and `string` inputs. A `Date` whose
-     * `getTime()` returns `NaN` is considered invalid.
-     *
-     * @param value - The value to validate.
-     * @returns `true` if the value represents a valid date.
-     *
-     * @example
-     * ```ts
-     * du.isValid(new Date());           // → true
-     * du.isValid("2026-04-15");         // → true
-     * du.isValid("not-a-date");         // → false
-     * du.isValid(new Date("invalid"));  // → false
-     * du.isValid(NaN);                  // → false
-     * ```
-     */
-    isValid(value) {
-        try {
-            if (typeof value !== "string" &&
-                typeof value !== "number" &&
-                !(value instanceof Date)) {
-                return false;
-            }
-            const d = this.toDate(value);
-            return !isNaN(d.getTime());
-        }
-        catch {
-            return false;
-        }
-    }
-    /**
-     * Parses a date string using an ordered list of format patterns and returns
-     * the first successfully parsed `Date`, or `null` if none match.
-     *
-     * Supported format tokens:
-     * - `YYYY` — 4-digit year
-     * - `MM`   — 2-digit month (01–12)
-     * - `DD`   — 2-digit day (01–31)
-     * - `HH`   — 2-digit hours (00–23)
-     * - `mm`   — 2-digit minutes (00–59)
-     * - `ss`   — 2-digit seconds (00–59)
-     *
-     * @param value   - The date string to parse.
-     * @param formats - An ordered list of format strings to attempt.
-     * @returns The first successfully parsed `Date`, or `null`.
-     *
-     * @example
-     * ```ts
-     * du.parse("15/04/2026", ["DD/MM/YYYY"]);
-     * // → Date("2026-04-15")
-     *
-     * du.parse("2026-04-15 08:30:00", ["YYYY-MM-DD HH:mm:ss"]);
-     * // → Date("2026-04-15T08:30:00")
-     *
-     * du.parse("bad-input", ["YYYY-MM-DD"]);
-     * // → null
-     * ```
-     */
-    parse(value, formats) {
-        for (const fmt of formats) {
-            const tokens = {};
-            let regexStr = fmt
-                .replace("YYYY", "(?<YYYY>\\d{4})")
-                .replace("MM", "(?<MM>\\d{2})")
-                .replace("DD", "(?<DD>\\d{2})")
-                .replace("HH", "(?<HH>\\d{2})")
-                .replace("mm", "(?<mm>\\d{2})")
-                .replace("ss", "(?<ss>\\d{2})");
-            const match = new RegExp(`^${regexStr}$`).exec(value);
-            if (!match?.groups)
-                continue;
-            const g = match.groups;
-            const year = parseInt(g.YYYY ?? "1970", 10);
-            const month = parseInt(g.MM ?? "1", 10) - 1;
-            const day = parseInt(g.DD ?? "1", 10);
-            const hour = parseInt(g.HH ?? "0", 10);
-            const minute = parseInt(g.mm ?? "0", 10);
-            const second = parseInt(g.ss ?? "0", 10);
-            const d = new Date(year, month, day, hour, minute, second);
-            if (!isNaN(d.getTime()))
-                return d;
-        }
-        return null;
-    }
-    // ─────────────────────────────────────────────
-    //  Timezone utilities
-    // ─────────────────────────────────────────────
-    /**
-     * Returns the UTC offset of the local environment in minutes.
-     *
-     * Positive values indicate zones **behind** UTC (e.g., UTC-5 → `300`),
-     * mirroring the behaviour of `Date.prototype.getTimezoneOffset()`.
-     *
-     * @returns The UTC offset in minutes.
-     *
-     * @example
-     * ```ts
-     * du.timezoneOffset(); // → -120 for UTC+2, 300 for UTC-5
-     * ```
-     */
-    timezoneOffset() {
-        return new Date().getTimezoneOffset();
-    }
-    /**
-     * Formats a date in a specific IANA timezone using `Intl.DateTimeFormat`.
-     *
-     * Requires the runtime to support the `timeZone` option (all modern
-     * environments do).
-     *
-     * @param date     - The date to format.
-     * @param timeZone - A valid IANA timezone identifier (e.g., `"America/New_York"`).
-     * @param locale   - BCP 47 locale tag (default: `"en-US"`).
-     * @param options  - Additional `Intl.DateTimeFormatOptions`.
-     * @returns A localized date string in the given timezone.
-     *
-     * @example
-     * ```ts
-     * du.formatInTimezone(Date.now(), "Asia/Tokyo", "ja-JP", { dateStyle: "full", timeStyle: "short" });
-     * // → "2026年4月15日水曜日 19:00"
-     * ```
-     */
-    formatInTimezone(date, timeZone, locale = "en-US", options) {
-        return new Intl.DateTimeFormat(locale, { ...options, timeZone }).format(this.toDate(date));
-    }
-}
-//# sourceMappingURL=DateUtils.js.map