ts-time-utils 1.1.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** - 19 utility categories with 150+ functions
+- **📚 Comprehensive** - 26 utility categories with 320+ functions
 
 ### 🔄 Recurrence utilities **(NEW!)**
 
@@ -70,6 +70,9 @@ A lightweight TypeScript utility library for time formatting, calculations, and
 - Get human-friendly "time ago" strings
 - Parse duration strings back to milliseconds
 - Format time in 12h/24h/ISO formats
+- Custom date formatting with pattern strings (YYYY-MM-DD, etc.)
+- Format date ranges and ordinals
+- Calendar-friendly date formatting ("Today", "Tomorrow", "Monday")
 
 ### 🧮 Calculation utilities
 
@@ -83,7 +86,10 @@ A lightweight TypeScript utility library for time formatting, calculations, and
 
 - Validate dates and time strings
 - Check for leap years, weekends, past/future dates
-- Compare dates (same day, today, yesterday, etc.)
+- Compare dates (same day, same week, same month, same year)
+- Check relative periods (isThisWeek, isThisMonth, isThisYear)
+- Business day validation with holiday support
+- Check if date is within last/next N days
 
 ### 🎂 Age utilities
 
@@ -96,8 +102,12 @@ A lightweight TypeScript utility library for time formatting, calculations, and
 
 - ISO week numbers and week-based calculations
 - Quarter operations and fiscal year support
-- Holiday calculations (Easter, Thanksgiving, etc.)
+- Holiday calculations (Easter, US federal holidays)
 - Days in month/year calculations
+- Get nth occurrence of weekday in month
+- US holiday functions (Thanksgiving, Memorial Day, Labor Day, etc.)
+- Week start/end calculations
+- Calendar grid generation
 
 ### 🔍 Parse utilities
 
@@ -105,6 +115,10 @@ A lightweight TypeScript utility library for time formatting, calculations, and
 - Relative date parsing ("tomorrow", "next week")
 - Custom format parsing with flexible patterns
 - Smart date interpretation
+- ISO 8601 duration parsing (P1Y2M3DT4H5M6S)
+- Time string parsing (14:30, 2:30 PM)
+- Auto-detect date format
+- Parse range endpoints ("end of month", "start of year")
 
 ### ⚡ Performance utilities
 
@@ -127,14 +141,22 @@ A lightweight TypeScript utility library for time formatting, calculations, and
 - Format in specific timezone
 - Convert absolute moment to zone components
 - Reinterpret wall-clock times
+- Daylight Saving Time detection
+- Find next DST transition
+- Find common working hours across timezones
+- Convert dates between timezones
 
 ### 🕘 Working hours utilities
 
 - Define working day patterns and breaks
 - Check working day/time
 - Compute working time between dates
-- Add working hours across days
-- Find next working time
+- Add/subtract working hours and days
+- Find next/previous working day
+- Get working days in month
+- Count working days between dates
+- Break time detection
+- Work day start/end times
 
 ### 🎯 Range preset utilities
 
@@ -153,6 +175,75 @@ A lightweight TypeScript utility library for time formatting, calculations, and
 - Internationalization (i18n) support
 - **Locale conversions** - Convert between different locales and detect locale from text
 
+### ⏰ Cron utilities **(NEW!)**
+
+- Parse and validate cron expressions (5-field format)
+- Check if a date matches a cron expression
+- Get next/previous occurrence dates
+- Get multiple future occurrences
+- Human-readable cron descriptions
+- Common cron presets (every minute, hourly, daily, weekly, etc.)
+- Support for wildcards, ranges, steps, and lists
+
+### 📅 Fiscal Year utilities **(NEW!)**
+
+- Configurable fiscal year start month (calendar, UK/India April, Australia July, US Federal October)
+- Get fiscal year, quarter, month, and week for any date
+- Calculate fiscal year/quarter start and end dates
+- Track fiscal year progress and days elapsed/remaining
+- Format fiscal years and quarters (FY2024, Q1 FY2024, FY2023/24)
+- Common fiscal presets: CALENDAR, UK_INDIA, AUSTRALIA, US_FEDERAL
+
+### 🔄 Date Comparison & Sorting **(NEW!)**
+
+- 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
+- Group dates by year, month, day, or day of week
+- Round and snap dates to intervals (e.g., nearest 15 minutes)
+- Check if dates are in chronological order
+- Partition dates by predicate
+
+### 🔁 Date Iteration utilities **(NEW!)**
+
+- Generate arrays of dates: `eachDay()`, `eachWeekday()`, `eachWeekend()`
+- Iterate by period: `eachWeek()`, `eachMonth()`, `eachQuarter()`, `eachYear()`
+- Time iteration: `eachHour()`, `eachMinute()`, `eachInterval()`
+- Get specific days: `eachDayOfWeek()`, `eachNthDayOfMonth()`, `eachMonthEnd()`
+- Count functions: `countDays()`, `countWeekdays()`, `countWeekendDays()`
+- Lazy iterators for memory efficiency: `iterateDays()`, `iterateWeekdays()`, `iterateMonths()`
+- Custom filtering with `filterDays()`
+
 ### 🧱 Constants
 
 - Milliseconds & seconds per unit
@@ -175,16 +266,20 @@ import { formatDuration, timeAgo, isValidDate } from "ts-time-utils";
 ### Import by category (better for tree-shaking)
 
 ```ts
-import { formatDuration, timeAgo } from "ts-time-utils/format";
+import { formatDuration, timeAgo, formatDate } from "ts-time-utils/format";
 import { differenceInUnits, addTime } from "ts-time-utils/calculate";
-import { isValidDate, isLeapYear } from "ts-time-utils/validate";
+import { isValidDate, isLeapYear, isSameWeek } from "ts-time-utils/validate";
 import { calculateAge, getNextBirthday } from "ts-time-utils/age";
-import { getWeekNumber, getQuarter } from "ts-time-utils/calendar";
-import { parseDate, parseRelativeDate } from "ts-time-utils/parse";
+import {
+  getWeekNumber,
+  getQuarter,
+  getUSHolidays,
+} from "ts-time-utils/calendar";
+import { parseDate, parseRelativeDate, parseTime } from "ts-time-utils/parse";
 import { sleep, benchmark, Stopwatch } from "ts-time-utils/performance";
 import { createInterval, mergeIntervals } from "ts-time-utils/interval";
-import { formatInTimeZone } from "ts-time-utils/timezone";
-import { isWorkingTime, addWorkingHours } from "ts-time-utils/workingHours";
+import { formatInTimeZone, isDST } from "ts-time-utils/timezone";
+import { isWorkingTime, addWorkingDays } from "ts-time-utils/workingHours";
 import { today, lastNDays } from "ts-time-utils/rangePresets";
 import { Duration, createDuration } from "ts-time-utils/duration";
 import { serializeDate, parseJSONWithDates } from "ts-time-utils/serialize";
@@ -193,7 +288,6 @@ import {
   formatDateLocale,
   detectLocale,
 } from "ts-time-utils/locale";
-// New modules!
 import { createRecurrence, getNextOccurrence } from "ts-time-utils/recurrence";
 import { createCountdown, getRemainingTime } from "ts-time-utils/countdown";
 import { mergeDateRanges, findGaps } from "ts-time-utils/dateRange";
@@ -201,6 +295,41 @@ import {
   parseNaturalDate,
   extractDatesFromText,
 } from "ts-time-utils/naturalLanguage";
+// NEW: Cron utilities
+import {
+  matchesCron,
+  getNextCronDate,
+  isValidCron,
+  CRON_PRESETS,
+} from "ts-time-utils/cron";
+// NEW: Fiscal year utilities
+import {
+  getFiscalYear,
+  getFiscalQuarter,
+  getFiscalPeriodInfo,
+  FISCAL_PRESETS,
+} from "ts-time-utils/fiscal";
+// NEW: Date comparison & sorting
+import {
+  sortDates,
+  closestDate,
+  groupDatesByMonth,
+  snapDate,
+} from "ts-time-utils/compare";
+// NEW: Date iteration
+import {
+  eachDay,
+  eachWeekday,
+  countWeekdays,
+  iterateDays,
+} from "ts-time-utils/iterate";
+// NEW: International holidays
+import {
+  getHolidays,
+  isHoliday,
+  getNextHoliday,
+  getSupportedCountries,
+} from "ts-time-utils/holidays";
 ```
 
 ## 📖 Examples
@@ -653,6 +782,240 @@ const week = thisWeek();
 const quarter = quarterRange();
 ```
 
+### Cron Utilities
+
+```ts
+import {
+  parseCronExpression,
+  matchesCron,
+  getNextCronDate,
+  getNextCronDates,
+  describeCron,
+  isValidCron,
+  CRON_PRESETS,
+} from "ts-time-utils/cron";
+
+// Parse a cron expression
+const parsed = parseCronExpression("0 9 * * 1-5"); // 9 AM weekdays
+// { minute: [0], hour: [9], dayOfMonth: [1-31], month: [1-12], dayOfWeek: [1,2,3,4,5] }
+
+// Check if a date matches a cron expression
+matchesCron("0 9 * * *", new Date("2024-01-15T09:00:00")); // true (9 AM daily)
+matchesCron("0 9 * * *", new Date("2024-01-15T10:00:00")); // false
+
+// Get next scheduled date
+getNextCronDate("0 9 * * *"); // Next 9 AM
+getNextCronDate("0 0 1 * *"); // Next 1st of month at midnight
+
+// Get multiple upcoming dates
+getNextCronDates("0 9 * * 1-5", 5); // Next 5 weekday 9 AMs
+
+// Human-readable descriptions
+describeCron("0 9 * * *"); // "At 09:00"
+describeCron("0 9 * * 1-5"); // "At 09:00 on Monday through Friday"
+describeCron("0 0 1 * *"); // "At 00:00 on day 1 of every month"
+
+// Validate cron expressions
+isValidCron("0 9 * * *"); // true
+isValidCron("invalid"); // false
+
+// Common presets
+CRON_PRESETS.EVERY_MINUTE; // "* * * * *"
+CRON_PRESETS.HOURLY; // "0 * * * *"
+CRON_PRESETS.DAILY; // "0 0 * * *"
+CRON_PRESETS.WEEKLY; // "0 0 * * 0"
+CRON_PRESETS.MONTHLY; // "0 0 1 * *"
+CRON_PRESETS.WEEKDAYS; // "0 0 * * 1-5"
+```
+
+### Fiscal Year Utilities (NEW!)
+
+```ts
+import {
+  getFiscalYear,
+  getFiscalQuarter,
+  getFiscalYearStart,
+  getFiscalYearEnd,
+  getFiscalPeriodInfo,
+  formatFiscalYear,
+  FISCAL_PRESETS,
+} from "ts-time-utils/fiscal";
+
+// Default calendar year (January start)
+getFiscalYear(new Date("2024-06-15")); // 2024
+getFiscalQuarter(new Date("2024-06-15")); // 2
+
+// UK/India fiscal year (April start)
+getFiscalYear(new Date("2024-03-15"), FISCAL_PRESETS.UK_INDIA); // 2023
+getFiscalYear(new Date("2024-04-15"), FISCAL_PRESETS.UK_INDIA); // 2024
+
+// Australian fiscal year (July start)
+getFiscalYear(new Date("2024-06-30"), FISCAL_PRESETS.AUSTRALIA); // 2023
+getFiscalYear(new Date("2024-07-01"), FISCAL_PRESETS.AUSTRALIA); // 2024
+
+// US Federal fiscal year (October start)
+getFiscalYear(new Date("2024-09-30"), FISCAL_PRESETS.US_FEDERAL); // 2023
+getFiscalYear(new Date("2024-10-01"), FISCAL_PRESETS.US_FEDERAL); // 2024
+
+// Get fiscal year boundaries
+getFiscalYearStart(2024, FISCAL_PRESETS.UK_INDIA); // April 1, 2024
+getFiscalYearEnd(2024, FISCAL_PRESETS.UK_INDIA); // March 31, 2025
+
+// Format fiscal years
+formatFiscalYear(2024); // "FY2024"
+formatFiscalYear(2024, FISCAL_PRESETS.UK_INDIA, "long"); // "FY2024/25"
+
+// Get comprehensive fiscal info
+const info = getFiscalPeriodInfo(new Date("2024-06-15"));
+// { fiscalYear: 2024, fiscalQuarter: 2, fiscalMonth: 6, progress: 45.2, ... }
+```
+
+### Date Comparison & Sorting (NEW!)
+
+```ts
+import {
+  sortDates,
+  minDate,
+  maxDate,
+  closestDate,
+  uniqueDates,
+  groupDatesByMonth,
+  snapDate,
+  roundDate,
+  medianDate,
+} from "ts-time-utils/compare";
+
+const dates = [
+  new Date("2024-03-15"),
+  new Date("2024-01-10"),
+  new Date("2024-06-20"),
+];
+
+// Sort dates
+sortDates(dates); // [Jan 10, Mar 15, Jun 20]
+sortDates(dates, "desc"); // [Jun 20, Mar 15, Jan 10]
+
+// Find extremes
+minDate(dates); // Jan 10, 2024
+maxDate(dates); // Jun 20, 2024
+medianDate(dates); // Mar 15, 2024
+
+// Find closest to target
+const target = new Date("2024-04-01");
+closestDate(target, dates); // Mar 15, 2024
+
+// Remove duplicates
+uniqueDates([date1, date1Copy, date2]); // [date1, date2]
+uniqueDates(dates, "day"); // Unique by day precision
+
+// Group dates
+groupDatesByMonth(dates);
+// Map { "2024-01" => [Jan 10], "2024-03" => [Mar 15], "2024-06" => [Jun 20] }
+
+// Snap to intervals (e.g., 15-minute blocks)
+snapDate(new Date("2024-01-15T10:37:00"), 15); // 10:30:00
+snapDate(new Date("2024-01-15T10:37:00"), 15, "ceil"); // 10:45:00
+
+// Round to nearest unit
+roundDate(new Date("2024-01-15T10:37:00"), "hour"); // 11:00:00
+```
+
+### Date Iteration (NEW!)
+
+```ts
+import {
+  eachDay,
+  eachWeekday,
+  eachWeek,
+  eachMonth,
+  countWeekdays,
+  eachDayOfWeek,
+  iterateDays,
+  filterDays,
+} from "ts-time-utils/iterate";
+
+const start = new Date("2024-01-01");
+const end = new Date("2024-01-31");
+
+// Generate arrays of dates
+eachDay(start, end); // [Jan 1, Jan 2, ..., Jan 31] (31 dates)
+eachWeekday(start, end); // All Mon-Fri dates (23 dates)
+eachWeek(start, end); // [Jan 7, Jan 14, Jan 21, Jan 28] (Sundays)
+eachMonth(start, new Date("2024-06-30")); // [Feb 1, Mar 1, Apr 1, May 1, Jun 1]
+
+// Count dates
+countWeekdays(start, end); // 23
+
+// Get specific weekdays
+eachDayOfWeek(start, end, 1); // All Mondays in January
+
+// Lazy iteration (memory efficient for large ranges)
+for (const date of iterateDays(start, end)) {
+  console.log(date);
+}
+
+// Filter days by custom predicate
+filterDays(start, end, (d) => d.getDate() === 15); // [Jan 15]
+
+// Custom intervals
+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
@@ -848,10 +1211,193 @@ console.log(comparison.weekStartsOn);
 ### Format Functions
 
 - `formatDuration(ms, options?)` - Format milliseconds to readable duration
+- `formatDurationCompact(ms)` - Format milliseconds as HH:MM:SS
 - `timeAgo(date, options?)` - Get "time ago" string for past/future dates
 - `formatTime(date, format?)` - Format time as 12h/24h/ISO
+- `formatDate(date, pattern?)` - Format date using patterns (YYYY-MM-DD, etc.)
+- `formatRelativeTime(date, locale?, options?)` - Format as relative time ("2 days ago")
+- `formatDateRange(start, end, options?)` - Format date ranges ("Jan 1-5, 2024")
+- `formatOrdinal(n)` - Format number as ordinal ("1st", "2nd", "3rd")
+- `formatDayOrdinal(date)` - Format day with ordinal ("1st", "15th")
+- `formatCalendarDate(date)` - Format as "Today", "Tomorrow", or day name
 - `parseDuration(duration)` - Parse duration string to milliseconds
 
+### Parse Functions
+
+- `parseISO8601Duration(duration)` - Parse ISO 8601 duration to object (P1Y2M3DT4H5M6S)
+- `parseISO8601DurationToMs(duration)` - Parse ISO 8601 duration to milliseconds
+- `parseTime(timeString)` - Parse time string ("14:30", "2:30 PM") to Date
+- `guessDateFormat(dateString)` - Guess the format of a date string
+- `parseAutoFormat(dateString)` - Auto-detect and parse date string
+- `parseRangeEndpoint(endpoint)` - Parse range endpoint (date string, Date, or number)
+
+### Calendar Functions
+
+- `getCalendarDays(year, month)` - Get array of days for a calendar month
+- `getWeekNumber(date)` - Get ISO week number (1-53)
+- `getQuarter(date)` - Get quarter (1-4)
+- `getFirstDayOfMonth(date)` / `getLastDayOfMonth(date)` - Month boundaries
+- `getFirstDayOfWeek(date)` / `getLastDayOfWeek(date)` - Week boundaries
+- `getNthDayOfMonth(year, month, dayOfWeek, n)` - Get nth occurrence of weekday in month
+- `getStartOfWeek(date, startDay?)` - Get start of week (configurable start day)
+- `getEndOfWeek(date, startDay?)` - Get end of week (configurable start day)
+- `getWeeksInMonth(year, month)` - Count weeks in a month
+
+#### US Federal Holidays
+
+- `getNewYearsDay(year)` - Get New Year's Day
+- `getMLKDay(year)` - Get Martin Luther King Jr. Day (3rd Monday of January)
+- `getPresidentsDay(year)` - Get Presidents Day (3rd Monday of February)
+- `getMemorialDay(year)` - Get Memorial Day (last Monday of May)
+- `getIndependenceDay(year)` - Get Independence Day (July 4th)
+- `getLaborDay(year)` - Get Labor Day (1st Monday of September)
+- `getColumbusDay(year)` - Get Columbus Day (2nd Monday of October)
+- `getVeteransDay(year)` - Get Veterans Day (November 11th)
+- `getThanksgivingDay(year)` - Get Thanksgiving Day (4th Thursday of November)
+- `getChristmasDay(year)` - Get Christmas Day
+- `getGoodFriday(year)` - Get Good Friday
+- `getUSHolidays(year)` - Get all US federal holidays for a year
+- `isUSHoliday(date)` - Check if date is a US federal holiday
+- `getUSHolidayName(date)` - Get name of US holiday (or null)
+
+### Timezone Functions
+
+- `getTimezoneOffset(timezone, date?)` - Get timezone offset in minutes
+- `convertTimezone(date, fromTz, toTz)` - Convert date between timezones
+- `getTimezoneNames()` - Get array of valid timezone names
+- `formatWithTimezone(date, timezone, format?)` - Format date in specific timezone
+- `isDST(date, timezone?)` - Check if DST is in effect
+- `getNextDSTTransition(date?, timezone?)` - Get next DST transition date
+- `findCommonWorkingHours(tz1, tz2, workStart?, workEnd?)` - Find overlapping work hours
+- `getTimezoneAbbreviation(date, timezone?)` - Get timezone abbreviation (EST, PST, etc.)
+- `convertBetweenZones(date, fromTz, toTz)` - Convert date between zones (returns new Date)
+- `getTimezoneDifferenceHours(tz1, tz2, date?)` - Get hour difference between timezones
+- `isSameTimezone(tz1, tz2, date?)` - Check if two timezones have same offset
+
+### Working Hours Functions
+
+- `isWithinWorkingHours(date, config?)` - Check if time is within working hours
+- `getNextWorkingHour(date, config?)` - Get next available working hour
+- `addWorkingMinutes(date, minutes, config?)` - Add minutes within working hours
+- `workingMinutesBetween(start, end, config?)` - Count working minutes between dates
+- `addWorkingDays(date, days, config?)` - Add working days to date
+- `subtractWorkingDays(date, days, config?)` - Subtract working days from date
+- `getNextWorkingDay(date, config?)` - Get next working day
+- `getPreviousWorkingDay(date, config?)` - Get previous working day
+- `getWorkingDaysInMonth(year, month, config?)` - Count working days in month
+- `getWorkingDaysInMonthArray(year, month, config?)` - Get array of working days
+- `workingDaysBetween(start, end, config?)` - Count working days between dates
+- `isBreakTime(date, breakStart?, breakEnd?)` - Check if time is during break
+- `getWorkDayStart(date, config?)` - Get start time of work day
+- `getWorkDayEnd(date, config?)` - Get end time of work day
+- `getWorkingHoursPerDay(config?)` - Get working hours per day
+
+### Cron Functions
+
+- `parseCronExpression(expression)` - Parse cron expression to object
+- `matchesCron(expression, date?)` - Check if date matches cron expression
+- `getNextCronDate(expression, after?)` - Get next date matching cron
+- `getNextCronDates(expression, count, after?)` - Get multiple future cron dates
+- `getPreviousCronDate(expression, before?)` - Get previous date matching cron
+- `isValidCron(expression)` - Validate cron expression syntax
+- `describeCron(expression)` - Get human-readable cron description
+- `CRON_PRESETS` - Common cron expressions (EVERY_MINUTE, HOURLY, DAILY, etc.)
+
+### Fiscal Year Functions
+
+- `getFiscalYear(date, config?)` - Get fiscal year for a date
+- `getFiscalQuarter(date, config?)` - Get fiscal quarter (1-4)
+- `getFiscalMonth(date, config?)` - Get fiscal month (1-12 within fiscal year)
+- `getFiscalWeek(date, config?)` - Get fiscal week number
+- `getFiscalYearStart(year, config?)` - Get start date of fiscal year
+- `getFiscalYearEnd(year, config?)` - Get end date of fiscal year
+- `getFiscalQuarterStart(year, quarter, config?)` - Get start of fiscal quarter
+- `getFiscalQuarterEnd(year, quarter, config?)` - Get end of fiscal quarter
+- `isSameFiscalYear(date1, date2, config?)` - Check if dates are in same fiscal year
+- `isSameFiscalQuarter(date1, date2, config?)` - Check if dates are in same fiscal quarter
+- `getDaysElapsedInFiscalYear(date, config?)` - Days elapsed in fiscal year
+- `getDaysRemainingInFiscalYear(date, config?)` - Days remaining in fiscal year
+- `getFiscalYearProgress(date, config?)` - Percentage of fiscal year completed
+- `formatFiscalYear(year, config?, format?)` - Format as "FY2024" or "FY2023/24"
+- `formatFiscalQuarter(year, quarter, config?)` - Format as "Q1 FY2024"
+- `getFiscalPeriodInfo(date, config?)` - Get comprehensive fiscal period info
+- `FISCAL_PRESETS` - CALENDAR, UK_INDIA, AUSTRALIA, US_FEDERAL
+
+### Compare Functions
+
+- `compareDates(a, b)` - Compare function for sorting dates
+- `compareDatesDesc(a, b)` - Compare function for reverse sorting
+- `sortDates(dates, direction?)` - Sort date array (asc/desc)
+- `minDate(dates)` - Find earliest date
+- `maxDate(dates)` - Find latest date
+- `dateExtent(dates)` - Get { min, max } from date array
+- `uniqueDates(dates, precision?)` - Remove duplicate dates
+- `closestDate(target, candidates)` - Find closest date to target
+- `closestFutureDate(target, candidates)` - Find closest future date
+- `closestPastDate(target, candidates)` - Find closest past date
+- `clampDate(date, min, max)` - Constrain date to range
+- `isDateInRange(date, min, max)` - Check if date is in range
+- `filterDatesInRange(dates, min, max)` - Filter dates in range
+- `groupDates(dates, keyFn)` - Group dates by custom key
+- `groupDatesByYear(dates)` - Group by year
+- `groupDatesByMonth(dates)` - Group by month (YYYY-MM)
+- `groupDatesByDay(dates)` - Group by day (YYYY-MM-DD)
+- `groupDatesByDayOfWeek(dates)` - Group by day of week (0-6)
+- `medianDate(dates)` - Calculate median date
+- `averageDate(dates)` - Calculate average/mean date
+- `roundDate(date, unit)` - Round to nearest minute/hour/day
+- `snapDate(date, intervalMinutes, mode?)` - Snap to interval grid
+- `isChronological(dates, strict?)` - Check if dates are in order
+- `dateSpan(dates)` - Get duration between min and max
+- `partitionDates(dates, predicate)` - Split into [matching, non-matching]
+- `nthDate(dates, n)` - Get nth date (supports negative indices)
+
+### Iterate Functions
+
+- `eachDay(start, end)` - Array of each day in range
+- `eachWeekday(start, end)` - Array of weekdays (Mon-Fri)
+- `eachWeekend(start, end)` - Array of weekend days (Sat-Sun)
+- `eachWeek(start, end, weekStartsOn?)` - Array of week starts
+- `eachMonth(start, end)` - Array of month starts
+- `eachMonthEnd(start, end)` - Array of month ends
+- `eachQuarter(start, end)` - Array of quarter starts
+- `eachYear(start, end)` - Array of year starts
+- `eachHour(start, end, step?)` - Array of hourly intervals
+- `eachMinute(start, end, step?)` - Array of minute intervals
+- `eachDayOfWeek(start, end, dayOfWeek)` - Array of specific weekday
+- `eachNthDayOfMonth(start, end, day)` - Array of nth day of each month
+- `eachInterval(start, end, interval)` - Array at custom intervals
+- `countDays(start, end)` - Count days in range
+- `countWeekdays(start, end)` - Count weekdays in range
+- `countWeekendDays(start, end)` - Count weekend days
+- `countWeeks(start, end)` - Count weeks in range
+- `countMonths(start, end)` - Count months in range
+- `iterateDates(start, end, step?)` - Lazy date generator
+- `iterateDays(start, end)` - Lazy day iterator
+- `iterateWeekdays(start, end)` - Lazy weekday iterator
+- `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
@@ -869,7 +1415,16 @@ console.log(comparison.weekStartsOn);
 - `isPast(date)` / `isFuture(date)` - Check if date is past/future
 - `isToday(date)` / `isYesterday(date)` / `isTomorrow(date)` - Date comparisons
 - `isSameDay(date1, date2)` - Check if dates are same day
+- `isSameWeek(date1, date2)` - Check if dates are in same week
+- `isSameMonth(date1, date2)` - Check if dates are in same month
+- `isSameYear(date1, date2)` - Check if dates are in same year
+- `isThisWeek(date)` - Check if date is in current week
+- `isThisMonth(date)` - Check if date is in current month
+- `isThisYear(date)` - Check if date is in current year
 - `isWeekend(date)` / `isWeekday(date)` - Check day type
+- `isBusinessDay(date)` - Check if date is a business day (weekday, not a US holiday)
+- `isInLastNDays(date, n)` - Check if date is within last N days
+- `isInNextNDays(date, n)` - Check if date is within next N days
 - `isValidTimeString(time)` - Validate HH:MM time format
 - `isValidISOString(dateString)` - Validate ISO 8601 date string