ts-time-utils 2.0.0 → 3.0.0

package/dist/esm/chain.js

@@ -0,0 +1,422 @@
+/**
+ * Fluent chain API for ts-time-utils
+ *
+ * Provides a chainable interface for date operations:
+ * ```ts
+ * chain(new Date())
+ *   .add(1, 'day')
+ *   .startOf('month')
+ *   .format('YYYY-MM-DD')
+ * ```
+ */
+import { addTime, subtractTime, startOf, endOf, differenceInUnits, isBetween } from './calculate.js';
+import { formatDate, formatDuration, timeAgo, formatTime, formatCalendarDate, formatOrdinal } from './format.js';
+import { isValidDate, isToday, isYesterday, isTomorrow, isPast, isFuture, isWeekend, isWeekday, isSameDay, isSameWeek, isSameMonth, isSameYear, isThisWeek, isThisMonth, isThisYear, isBusinessDay, isLeapYear } from './validate.js';
+/**
+ * Immutable chainable date wrapper
+ * All transformation methods return a new ChainedDate instance
+ */
+export class ChainedDate {
+    constructor(date = new Date()) {
+        if (date instanceof Date) {
+            this._date = new Date(date.getTime());
+        }
+        else if (typeof date === 'number') {
+            this._date = new Date(date);
+        }
+        else {
+            this._date = new Date(date);
+        }
+    }
+    // ============ Transformations (return new ChainedDate) ============
+    /**
+     * Add time to the date
+     * @example chain(date).add(1, 'day').add(2, 'hours')
+     */
+    add(amount, unit) {
+        return new ChainedDate(addTime(this._date, amount, unit));
+    }
+    /**
+     * Subtract time from the date
+     * @example chain(date).subtract(1, 'week')
+     */
+    subtract(amount, unit) {
+        return new ChainedDate(subtractTime(this._date, amount, unit));
+    }
+    /**
+     * Get the start of a time period
+     * @example chain(date).startOf('month')
+     */
+    startOf(unit) {
+        return new ChainedDate(startOf(this._date, unit));
+    }
+    /**
+     * Get the end of a time period
+     * @example chain(date).endOf('day')
+     */
+    endOf(unit) {
+        return new ChainedDate(endOf(this._date, unit));
+    }
+    /**
+     * Set specific date/time components
+     * @example chain(date).set({ year: 2025, month: 1 })
+     */
+    set(values) {
+        const d = new Date(this._date.getTime());
+        if (values.year !== undefined)
+            d.setFullYear(values.year);
+        if (values.month !== undefined)
+            d.setMonth(values.month - 1); // 1-indexed input
+        if (values.day !== undefined)
+            d.setDate(values.day);
+        if (values.hours !== undefined)
+            d.setHours(values.hours);
+        if (values.minutes !== undefined)
+            d.setMinutes(values.minutes);
+        if (values.seconds !== undefined)
+            d.setSeconds(values.seconds);
+        if (values.milliseconds !== undefined)
+            d.setMilliseconds(values.milliseconds);
+        return new ChainedDate(d);
+    }
+    /**
+     * Clone the ChainedDate
+     */
+    clone() {
+        return new ChainedDate(this._date);
+    }
+    // ============ Formatters (return string) ============
+    /**
+     * Format date using pattern string
+     * @example chain(date).format('YYYY-MM-DD') // "2025-01-15"
+     */
+    format(pattern) {
+        return formatDate(this._date, pattern);
+    }
+    /**
+     * Format time in 12h, 24h, or ISO format
+     * @example chain(date).formatTime('12h') // "2:30 PM"
+     */
+    formatTime(fmt = '24h') {
+        return formatTime(this._date, fmt);
+    }
+    /**
+     * Format as calendar date (Today, Yesterday, Monday, etc.)
+     * @example chain(date).calendar() // "Tomorrow"
+     */
+    calendar() {
+        return formatCalendarDate(this._date);
+    }
+    /**
+     * Get relative time string
+     * @example chain(pastDate).ago() // "3 hours ago"
+     */
+    ago(options) {
+        return timeAgo(this._date, options);
+    }
+    /**
+     * Get ISO string
+     */
+    toISOString() {
+        return this._date.toISOString();
+    }
+    /**
+     * Get locale string
+     */
+    toLocaleString(locale, options) {
+        return this._date.toLocaleString(locale, options);
+    }
+    /**
+     * Format day as ordinal
+     * @example chain(date).dayOrdinal() // "15th"
+     */
+    dayOrdinal() {
+        return formatOrdinal(this._date.getDate());
+    }
+    // ============ Comparisons (return boolean) ============
+    /**
+     * Check if date is valid
+     */
+    isValid() {
+        return isValidDate(this._date);
+    }
+    /**
+     * Check if date is today
+     */
+    isToday() {
+        return isToday(this._date);
+    }
+    /**
+     * Check if date is yesterday
+     */
+    isYesterday() {
+        return isYesterday(this._date);
+    }
+    /**
+     * Check if date is tomorrow
+     */
+    isTomorrow() {
+        return isTomorrow(this._date);
+    }
+    /**
+     * Check if date is in the past
+     */
+    isPast() {
+        return isPast(this._date);
+    }
+    /**
+     * Check if date is in the future
+     */
+    isFuture() {
+        return isFuture(this._date);
+    }
+    /**
+     * Check if date is a weekend
+     */
+    isWeekend() {
+        return isWeekend(this._date);
+    }
+    /**
+     * Check if date is a weekday
+     */
+    isWeekday() {
+        return isWeekday(this._date);
+    }
+    /**
+     * Check if date is in this week
+     */
+    isThisWeek() {
+        return isThisWeek(this._date);
+    }
+    /**
+     * Check if date is in this month
+     */
+    isThisMonth() {
+        return isThisMonth(this._date);
+    }
+    /**
+     * Check if date is in this year
+     */
+    isThisYear() {
+        return isThisYear(this._date);
+    }
+    /**
+     * Check if year is a leap year
+     */
+    isLeapYear() {
+        return isLeapYear(this._date.getFullYear());
+    }
+    /**
+     * Check if date is a business day
+     */
+    isBusinessDay(holidays) {
+        return isBusinessDay(this._date, holidays);
+    }
+    /**
+     * Check if date is same day as another
+     */
+    isSameDay(other) {
+        return isSameDay(this._date, toDate(other));
+    }
+    /**
+     * Check if date is same week as another
+     */
+    isSameWeek(other) {
+        return isSameWeek(this._date, toDate(other));
+    }
+    /**
+     * Check if date is same month as another
+     */
+    isSameMonth(other) {
+        return isSameMonth(this._date, toDate(other));
+    }
+    /**
+     * Check if date is same year as another
+     */
+    isSameYear(other) {
+        return isSameYear(this._date, toDate(other));
+    }
+    /**
+     * Check if date is before another
+     */
+    isBefore(other) {
+        return this._date.getTime() < toDate(other).getTime();
+    }
+    /**
+     * Check if date is after another
+     */
+    isAfter(other) {
+        return this._date.getTime() > toDate(other).getTime();
+    }
+    /**
+     * Check if date is between two dates
+     */
+    isBetween(start, end, inclusive) {
+        return isBetween(this._date, toDate(start), toDate(end), inclusive);
+    }
+    // ============ Getters (return number) ============
+    /**
+     * Get difference from another date
+     * @example chain(date).diff(other, 'days') // 5
+     */
+    diff(other, unit = 'milliseconds', precise = true) {
+        return differenceInUnits(this._date, toDate(other), unit, precise);
+    }
+    /**
+     * Get the timestamp (milliseconds since epoch)
+     */
+    valueOf() {
+        return this._date.getTime();
+    }
+    /**
+     * Get year
+     */
+    year() {
+        return this._date.getFullYear();
+    }
+    /**
+     * Get month (1-12)
+     */
+    month() {
+        return this._date.getMonth() + 1;
+    }
+    /**
+     * Get day of month (1-31)
+     */
+    day() {
+        return this._date.getDate();
+    }
+    /**
+     * Get day of week (0-6, 0=Sunday)
+     */
+    weekday() {
+        return this._date.getDay();
+    }
+    /**
+     * Get hours (0-23)
+     */
+    hours() {
+        return this._date.getHours();
+    }
+    /**
+     * Get minutes (0-59)
+     */
+    minutes() {
+        return this._date.getMinutes();
+    }
+    /**
+     * Get seconds (0-59)
+     */
+    seconds() {
+        return this._date.getSeconds();
+    }
+    /**
+     * Get milliseconds (0-999)
+     */
+    milliseconds() {
+        return this._date.getMilliseconds();
+    }
+    /**
+     * Get day of year (1-366)
+     */
+    dayOfYear() {
+        const start = new Date(this._date.getFullYear(), 0, 0);
+        const diff = this._date.getTime() - start.getTime();
+        const oneDay = 1000 * 60 * 60 * 24;
+        return Math.floor(diff / oneDay);
+    }
+    /**
+     * Get ISO week number (1-53)
+     */
+    week() {
+        const d = new Date(Date.UTC(this._date.getFullYear(), this._date.getMonth(), this._date.getDate()));
+        const dayNum = d.getUTCDay() || 7;
+        d.setUTCDate(d.getUTCDate() + 4 - dayNum);
+        const yearStart = new Date(Date.UTC(d.getUTCFullYear(), 0, 1));
+        return Math.ceil((((d.getTime() - yearStart.getTime()) / 86400000) + 1) / 7);
+    }
+    /**
+     * Get quarter (1-4)
+     */
+    quarter() {
+        return Math.floor(this._date.getMonth() / 3) + 1;
+    }
+    /**
+     * Get days in month
+     */
+    daysInMonth() {
+        return new Date(this._date.getFullYear(), this._date.getMonth() + 1, 0).getDate();
+    }
+    // ============ Conversion ============
+    /**
+     * Get the underlying Date object
+     */
+    toDate() {
+        return new Date(this._date.getTime());
+    }
+    /**
+     * Get Unix timestamp (seconds)
+     */
+    unix() {
+        return Math.floor(this._date.getTime() / 1000);
+    }
+    /**
+     * Convert to array [year, month, day, hours, minutes, seconds, ms]
+     */
+    toArray() {
+        return [
+            this._date.getFullYear(),
+            this._date.getMonth() + 1,
+            this._date.getDate(),
+            this._date.getHours(),
+            this._date.getMinutes(),
+            this._date.getSeconds(),
+            this._date.getMilliseconds()
+        ];
+    }
+    /**
+     * Convert to object
+     */
+    toObject() {
+        return {
+            year: this._date.getFullYear(),
+            month: this._date.getMonth() + 1,
+            day: this._date.getDate(),
+            hours: this._date.getHours(),
+            minutes: this._date.getMinutes(),
+            seconds: this._date.getSeconds(),
+            milliseconds: this._date.getMilliseconds()
+        };
+    }
+}
+/**
+ * Helper to convert DateInput to Date
+ */
+function toDate(input) {
+    if (input instanceof Date)
+        return input;
+    return new Date(input);
+}
+/**
+ * Create a chainable date wrapper
+ * @example
+ * chain(new Date()).add(1, 'day').format('YYYY-MM-DD')
+ * chain('2025-01-15').startOf('month').toDate()
+ * chain().add(1, 'week').isWeekend()
+ */
+export function chain(date) {
+    return new ChainedDate(date);
+}
+/**
+ * Format a duration in milliseconds
+ * Convenience export for use with chain().diff()
+ * @example formatMs(chain(a).diff(b)) // "2 days, 3 hours"
+ */
+export function formatMs(ms, options) {
+    return formatDuration(ms, options);
+}
+// Initialize plugin system if it's available
+// This allows plugins to extend ChainedDate
+if (typeof globalThis !== 'undefined') {
+    globalThis.__chainedDateClass = ChainedDate;
+}

package/dist/esm/holidays.d.ts

@@ -0,0 +1,62 @@
+/**
+ * @fileoverview International holiday utilities
+ * Calculate holidays for multiple countries including fixed, movable, and lunar-based holidays
+ */
+export type CountryCode = 'UK' | 'NL' | 'DE' | 'CA' | 'AU' | 'IT' | 'ES' | 'CN' | 'IN' | 'US';
+export interface Holiday {
+    name: string;
+    date: Date;
+    countryCode: CountryCode;
+    type: 'public' | 'bank' | 'observance';
+}
+export declare function getUKHolidays(year: number): Holiday[];
+export declare function getNetherlandsHolidays(year: number): Holiday[];
+export declare function getGermanyHolidays(year: number): Holiday[];
+export declare function getCanadaHolidays(year: number): Holiday[];
+export declare function getAustraliaHolidays(year: number): Holiday[];
+export declare function getItalyHolidays(year: number): Holiday[];
+export declare function getSpainHolidays(year: number): Holiday[];
+export declare function getChinaHolidays(year: number): Holiday[];
+export declare function getIndiaHolidays(year: number): Holiday[];
+/**
+ * Get holidays for a specific country and year
+ * @param year - The year
+ * @param countryCode - ISO country code
+ * @returns Array of holidays
+ */
+export declare function getHolidays(year: number, countryCode: CountryCode): Holiday[];
+/**
+ * Check if a date is a holiday in a specific country
+ * @param date - The date to check
+ * @param countryCode - ISO country code
+ * @returns True if date is a holiday
+ */
+export declare function isHoliday(date: Date, countryCode: CountryCode): boolean;
+/**
+ * Get the holiday name for a specific date and country
+ * @param date - The date to check
+ * @param countryCode - ISO country code
+ * @returns Holiday name or null if not a holiday
+ */
+export declare function getHolidayName(date: Date, countryCode: CountryCode): string | null;
+/**
+ * Get next holiday from a given date
+ * @param date - The reference date
+ * @param countryCode - ISO country code
+ * @returns Next holiday or null
+ */
+export declare function getNextHoliday(date: Date, countryCode: CountryCode): Holiday | null;
+/**
+ * Get upcoming holidays within N days
+ * @param date - The reference date
+ * @param days - Number of days to look ahead
+ * @param countryCode - ISO country code
+ * @returns Array of upcoming holidays
+ */
+export declare function getUpcomingHolidays(date: Date, days: number, countryCode: CountryCode): Holiday[];
+/**
+ * Get all supported country codes
+ * @returns Array of country codes
+ */
+export declare function getSupportedCountries(): CountryCode[];
+//# sourceMappingURL=holidays.d.ts.map

package/dist/esm/holidays.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"holidays.d.ts","sourceRoot":"","sources":["../../src/holidays.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,MAAM,WAAW,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;AAE9F,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,IAAI,CAAC;IACX,WAAW,EAAE,WAAW,CAAC;IACzB,IAAI,EAAE,QAAQ,GAAG,MAAM,GAAG,YAAY,CAAC;CACxC;AAoED,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,EAAE,CA+ErD;AAMD,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,EAAE,CAuG9D;AAMD,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,EAAE,CA6E1D;AAMD,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,EAAE,CA+EzD;AAMD,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,EAAE,CA6E5D;AAMD,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,EAAE,CA6FxD;AAMD,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,EAAE,CAqFxD;AAMD,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,EAAE,CA8CxD;AAMD,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,EAAE,CA+BxD;AAMD;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,WAAW,GAAG,OAAO,EAAE,CA0B7E;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,WAAW,EAAE,WAAW,GAAG,OAAO,CAYvE;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,IAAI,EAAE,WAAW,EAAE,WAAW,GAAG,MAAM,GAAG,IAAI,CAalF;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,IAAI,EAAE,WAAW,EAAE,WAAW,GAAG,OAAO,GAAG,IAAI,CAYnF;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,IAAI,EACV,IAAI,EAAE,MAAM,EACZ,WAAW,EAAE,WAAW,GACvB,OAAO,EAAE,CAYX;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,IAAI,WAAW,EAAE,CAErD"}