ts-time-utils 2.0.0 → 3.0.0

package/README.md

@@ -8,7 +8,7 @@ A lightweight TypeScript utility library for time formatting, calculations, and
 - **⚡ Fast** - Zero dependencies, pure JavaScript functions
 - **🔧 TypeScript** - Full type safety and IntelliSense support
 - **🌳 Tree-shakable** - Import individual functions to minimize bundle size
-- **📚 Comprehensive** - 25 utility categories with 287+ functions
+- **📚 Comprehensive** - 26 utility categories with 320+ functions
 
 ### 🔄 Recurrence utilities **(NEW!)**
 
@@ -198,6 +198,34 @@ A lightweight TypeScript utility library for time formatting, calculations, and
 
 - Sort date arrays ascending or descending
 - Find min/max/median/average dates in arrays
+- Find closest/farthest dates from target
+- Remove duplicate dates
+- Group dates by year/month/day/weekday
+- Snap dates to grid and round to nearest unit
+- Validate chronological order
+- Get date span and partition into groups
+- Select nth dates from sorted arrays
+
+### ⏭️ Date Iteration & Counting **(NEW!)**
+
+- Iterate through date sequences: days, weekdays, weekends, weeks, months, quarters, years
+- Count dates in ranges: count all days, weekdays, weekend days, weeks, months
+- Lazy iteration with generators for memory efficiency
+- Filter dates by custom conditions
+- Iterate specific day patterns (e.g., all Mondays)
+- Get month-end dates in range
+- Get nth day of each month in range
+
+### 🌍 International Holidays **(NEW!)**
+
+- Calculate public holidays for 9 countries: UK, Netherlands, Germany, Canada, Australia, Italy, Spain, China, India
+- Fixed holidays (New Year, Christmas, National Days)
+- Easter-based holidays (Good Friday, Easter Monday, Whit Monday)
+- Movable holidays (Victoria Day, Thanksgiving, Spring Bank Holiday)
+- Unified API: check if date is holiday, get holiday name, find next holiday
+- Weekend adjustment for substitute holidays
+- Get upcoming holidays within timeframe
+- Support for both federal and regional observances
 - Find closest date to a target (past, future, or any)
 - Clamp dates to ranges
 - Remove duplicate dates with precision control
@@ -295,6 +323,13 @@ import {
   countWeekdays,
   iterateDays,
 } from "ts-time-utils/iterate";
+// NEW: International holidays
+import {
+  getHolidays,
+  isHoliday,
+  getNextHoliday,
+  getSupportedCountries,
+} from "ts-time-utils/holidays";
 ```
 
 ## 📖 Examples
@@ -927,6 +962,60 @@ eachInterval(start, end, { days: 7 }); // Every 7 days
 eachInterval(start, end, { hours: 6 }); // Every 6 hours
 ```
 
+### International Holidays (NEW!)
+
+```ts
+import {
+  getHolidays,
+  isHoliday,
+  getHolidayName,
+  getNextHoliday,
+  getUpcomingHolidays,
+  getSupportedCountries,
+  getUKHolidays,
+  getCanadaHolidays,
+} from "ts-time-utils/holidays";
+
+// Get all holidays for a country and year
+const ukHolidays2024 = getHolidays(2024, "UK");
+console.log(ukHolidays2024);
+// [
+//   { name: "New Year's Day", date: Date, countryCode: "UK", type: "bank" },
+//   { name: "Good Friday", date: Date, countryCode: "UK", type: "bank" },
+//   { name: "Easter Monday", date: Date, countryCode: "UK", type: "bank" },
+//   ...
+// ]
+
+// Check if a date is a holiday
+const christmas = new Date(2024, 11, 25);
+isHoliday(christmas, "UK"); // true
+isHoliday(new Date(2024, 5, 15), "UK"); // false
+
+// Get holiday name for a date
+getHolidayName(christmas, "UK"); // "Christmas Day"
+getHolidayName(new Date(2024, 0, 1), "CA"); // "New Year's Day"
+
+// Find next holiday from a date
+const today = new Date();
+const nextHoliday = getNextHoliday(today, "CA");
+console.log(`Next holiday: ${nextHoliday?.name} on ${nextHoliday?.date}`);
+
+// Get upcoming holidays in the next 90 days
+const upcoming = getUpcomingHolidays(today, 90, "AU");
+upcoming.forEach((h) => {
+  console.log(`${h.name} - ${h.date.toDateString()}`);
+});
+
+// Get supported countries
+getSupportedCountries(); // ["UK", "NL", "DE", "CA", "AU", "IT", "ES", "CN", "IN", "US"]
+
+// Country-specific functions
+const nlHolidays = getHolidays(2024, "NL"); // Netherlands holidays (includes King's Day)
+const deHolidays = getHolidays(2024, "DE"); // German holidays (includes German Unity Day)
+const itHolidays = getHolidays(2024, "IT"); // Italian holidays (includes Republic Day)
+const esHolidays = getHolidays(2024, "ES"); // Spanish holidays (includes Constitution Day)
+```
+
 ### Locale Utilities
 
 ```ts
@@ -1289,6 +1378,26 @@ console.log(comparison.weekStartsOn);
 - `iterateMonths(start, end)` - Lazy month iterator
 - `filterDays(start, end, filter)` - Filter days by predicate
 
+### Holidays Functions
+
+- `getHolidays(year, countryCode)` - Get all holidays for a country and year
+- `isHoliday(date, countryCode)` - Check if date is a holiday
+- `getHolidayName(date, countryCode)` - Get holiday name for date (or null)
+- `getNextHoliday(date, countryCode)` - Find next holiday after date
+- `getUpcomingHolidays(date, days, countryCode)` - Get holidays in next N days
+- `getSupportedCountries()` - Get array of supported country codes
+- `getUKHolidays(year)` - Get UK bank holidays (New Year, Easter, Spring/Summer Bank Holiday, Christmas)
+- `getNetherlandsHolidays(year)` - Get Netherlands holidays (King's Day, Liberation Day, Easter, Ascension, Whit)
+- `getGermanyHolidays(year)` - Get German holidays (Unity Day, Labour Day, Easter, Ascension, Whit, Christmas)
+- `getCanadaHolidays(year)` - Get Canadian federal holidays (Victoria Day, Canada Day, Labour Day, Thanksgiving)
+- `getAustraliaHolidays(year)` - Get Australian holidays (Australia Day, Anzac Day, Queen's Birthday)
+- `getItalyHolidays(year)` - Get Italian holidays (Epiphany, Liberation Day, Republic Day, Assumption)
+- `getSpainHolidays(year)` - Get Spanish holidays (National Day, Constitution Day, Immaculate Conception)
+- `getChinaHolidays(year)` - Get Chinese holidays (Spring Festival, National Day, New Year) - simplified
+- `getIndiaHolidays(year)` - Get Indian holidays (Republic Day, Independence Day, Gandhi Jayanti) - simplified
+- **Types**: `CountryCode` = "UK" | "NL" | "DE" | "CA" | "AU" | "IT" | "ES" | "CN" | "IN" | "US"
+- **Holiday Interface**: `{ name: string, date: Date, countryCode: CountryCode, type: string }`
+
 ### Calculate Functions
 
 - `differenceInUnits(date1, date2, unit?, precise?)` - Calculate difference between dates

package/dist/chain.d.ts

@@ -0,0 +1,269 @@
+/**
+ * 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 type { TimeUnit, DateInput, FormatOptions } from './types.js';
+/** Units accepted by startOf/endOf */
+type StartOfUnit = 'day' | 'week' | 'month' | 'year' | 'hour' | 'minute';
+/**
+ * Immutable chainable date wrapper
+ * All transformation methods return a new ChainedDate instance
+ */
+export declare class ChainedDate {
+    private readonly _date;
+    constructor(date?: DateInput);
+    /**
+     * Add time to the date
+     * @example chain(date).add(1, 'day').add(2, 'hours')
+     */
+    add(amount: number, unit: TimeUnit): ChainedDate;
+    /**
+     * Subtract time from the date
+     * @example chain(date).subtract(1, 'week')
+     */
+    subtract(amount: number, unit: TimeUnit): ChainedDate;
+    /**
+     * Get the start of a time period
+     * @example chain(date).startOf('month')
+     */
+    startOf(unit: StartOfUnit): ChainedDate;
+    /**
+     * Get the end of a time period
+     * @example chain(date).endOf('day')
+     */
+    endOf(unit: StartOfUnit): ChainedDate;
+    /**
+     * Set specific date/time components
+     * @example chain(date).set({ year: 2025, month: 1 })
+     */
+    set(values: {
+        year?: number;
+        month?: number;
+        day?: number;
+        hours?: number;
+        minutes?: number;
+        seconds?: number;
+        milliseconds?: number;
+    }): ChainedDate;
+    /**
+     * Clone the ChainedDate
+     */
+    clone(): ChainedDate;
+    /**
+     * Format date using pattern string
+     * @example chain(date).format('YYYY-MM-DD') // "2025-01-15"
+     */
+    format(pattern: string): string;
+    /**
+     * Format time in 12h, 24h, or ISO format
+     * @example chain(date).formatTime('12h') // "2:30 PM"
+     */
+    formatTime(fmt?: '12h' | '24h' | 'iso'): string;
+    /**
+     * Format as calendar date (Today, Yesterday, Monday, etc.)
+     * @example chain(date).calendar() // "Tomorrow"
+     */
+    calendar(): string;
+    /**
+     * Get relative time string
+     * @example chain(pastDate).ago() // "3 hours ago"
+     */
+    ago(options?: FormatOptions): string;
+    /**
+     * Get ISO string
+     */
+    toISOString(): string;
+    /**
+     * Get locale string
+     */
+    toLocaleString(locale?: string, options?: Intl.DateTimeFormatOptions): string;
+    /**
+     * Format day as ordinal
+     * @example chain(date).dayOrdinal() // "15th"
+     */
+    dayOrdinal(): string;
+    /**
+     * Check if date is valid
+     */
+    isValid(): boolean;
+    /**
+     * Check if date is today
+     */
+    isToday(): boolean;
+    /**
+     * Check if date is yesterday
+     */
+    isYesterday(): boolean;
+    /**
+     * Check if date is tomorrow
+     */
+    isTomorrow(): boolean;
+    /**
+     * Check if date is in the past
+     */
+    isPast(): boolean;
+    /**
+     * Check if date is in the future
+     */
+    isFuture(): boolean;
+    /**
+     * Check if date is a weekend
+     */
+    isWeekend(): boolean;
+    /**
+     * Check if date is a weekday
+     */
+    isWeekday(): boolean;
+    /**
+     * Check if date is in this week
+     */
+    isThisWeek(): boolean;
+    /**
+     * Check if date is in this month
+     */
+    isThisMonth(): boolean;
+    /**
+     * Check if date is in this year
+     */
+    isThisYear(): boolean;
+    /**
+     * Check if year is a leap year
+     */
+    isLeapYear(): boolean;
+    /**
+     * Check if date is a business day
+     */
+    isBusinessDay(holidays?: Date[]): boolean;
+    /**
+     * Check if date is same day as another
+     */
+    isSameDay(other: DateInput): boolean;
+    /**
+     * Check if date is same week as another
+     */
+    isSameWeek(other: DateInput): boolean;
+    /**
+     * Check if date is same month as another
+     */
+    isSameMonth(other: DateInput): boolean;
+    /**
+     * Check if date is same year as another
+     */
+    isSameYear(other: DateInput): boolean;
+    /**
+     * Check if date is before another
+     */
+    isBefore(other: DateInput): boolean;
+    /**
+     * Check if date is after another
+     */
+    isAfter(other: DateInput): boolean;
+    /**
+     * Check if date is between two dates
+     */
+    isBetween(start: DateInput, end: DateInput, inclusive?: boolean): boolean;
+    /**
+     * Get difference from another date
+     * @example chain(date).diff(other, 'days') // 5
+     */
+    diff(other: DateInput, unit?: TimeUnit, precise?: boolean): number;
+    /**
+     * Get the timestamp (milliseconds since epoch)
+     */
+    valueOf(): number;
+    /**
+     * Get year
+     */
+    year(): number;
+    /**
+     * Get month (1-12)
+     */
+    month(): number;
+    /**
+     * Get day of month (1-31)
+     */
+    day(): number;
+    /**
+     * Get day of week (0-6, 0=Sunday)
+     */
+    weekday(): number;
+    /**
+     * Get hours (0-23)
+     */
+    hours(): number;
+    /**
+     * Get minutes (0-59)
+     */
+    minutes(): number;
+    /**
+     * Get seconds (0-59)
+     */
+    seconds(): number;
+    /**
+     * Get milliseconds (0-999)
+     */
+    milliseconds(): number;
+    /**
+     * Get day of year (1-366)
+     */
+    dayOfYear(): number;
+    /**
+     * Get ISO week number (1-53)
+     */
+    week(): number;
+    /**
+     * Get quarter (1-4)
+     */
+    quarter(): number;
+    /**
+     * Get days in month
+     */
+    daysInMonth(): number;
+    /**
+     * Get the underlying Date object
+     */
+    toDate(): Date;
+    /**
+     * Get Unix timestamp (seconds)
+     */
+    unix(): number;
+    /**
+     * Convert to array [year, month, day, hours, minutes, seconds, ms]
+     */
+    toArray(): [number, number, number, number, number, number, number];
+    /**
+     * Convert to object
+     */
+    toObject(): {
+        year: number;
+        month: number;
+        day: number;
+        hours: number;
+        minutes: number;
+        seconds: number;
+        milliseconds: number;
+    };
+}
+/**
+ * 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 declare function chain(date?: DateInput): ChainedDate;
+/**
+ * Format a duration in milliseconds
+ * Convenience export for use with chain().diff()
+ * @example formatMs(chain(a).diff(b)) // "2 days, 3 hours"
+ */
+export declare function formatMs(ms: number, options?: FormatOptions): string;
+export {};
+//# sourceMappingURL=chain.d.ts.map

package/dist/chain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chain.d.ts","sourceRoot":"","sources":["../src/chain.ts"],"names":[],"mappings":"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"}