ts-time-utils 1.0.0 → 2.0.0

package/README.md

@@ -8,7 +8,43 @@ 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** - 15 utility categories with 115+ functions
+- **📚 Comprehensive** - 25 utility categories with 287+ functions
+
+### 🔄 Recurrence utilities **(NEW!)**
+
+- RRULE-inspired recurring event patterns
+- Daily, weekly, monthly, and yearly recurrences
+- Complex recurrence rules with byWeekday, byMonthDay, byMonth
+- Get next occurrence, all occurrences, or occurrences within range
+- Human-readable recurrence descriptions
+- Full support for count and until limits
+
+### ⏲️ Countdown & Timer utilities **(NEW!)**
+
+- Real-time countdown timers with callbacks
+- Get remaining time broken down by units
+- Format countdowns as human-readable strings
+- Check if dates are expired
+- Calculate progress percentage between dates
+- Deadline tracking with helper methods
+
+### 📊 Date Range utilities **(NEW!)**
+
+- Advanced range operations (overlap, intersection, union)
+- Merge overlapping ranges
+- Find gaps between ranges
+- Split ranges into chunks
+- Expand and shrink ranges
+- Subtract ranges from each other
+- Check containment and sort ranges
+
+### 💬 Natural Language Parsing **(NEW!)**
+
+- Parse human-friendly date strings ("tomorrow", "next Friday", "in 2 weeks")
+- Extract dates from text automatically
+- Context-aware date suggestions ("end of month", "EOY")
+- Support for relative phrases and absolute dates
+- Confidence scoring for extracted dates
 
 ### ⏱️ Duration utilities
 
@@ -34,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
 
@@ -47,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
 
@@ -60,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
 
@@ -69,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
 
@@ -91,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
 
@@ -117,6 +175,47 @@ 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 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
@@ -139,16 +238,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";
@@ -157,10 +260,226 @@ import {
   formatDateLocale,
   detectLocale,
 } from "ts-time-utils/locale";
+import { createRecurrence, getNextOccurrence } from "ts-time-utils/recurrence";
+import { createCountdown, getRemainingTime } from "ts-time-utils/countdown";
+import { mergeDateRanges, findGaps } from "ts-time-utils/dateRange";
+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";
 ```
 
 ## 📖 Examples
 
+### Recurrence Utilities (NEW!)
+
+```ts
+import { createRecurrence, recurrenceToString } from "ts-time-utils/recurrence";
+
+// Daily recurrence
+const daily = createRecurrence({
+  frequency: "daily",
+  interval: 2,
+  startDate: new Date("2024-01-01"),
+  count: 10,
+});
+
+const next = daily.getNextOccurrence(new Date());
+const allOccurrences = daily.getAllOccurrences();
+
+// Weekly on specific days
+const weekly = createRecurrence({
+  frequency: "weekly",
+  interval: 1,
+  startDate: new Date("2024-01-01"),
+  byWeekday: [1, 3, 5], // Monday, Wednesday, Friday
+});
+
+const description = recurrenceToString(weekly.rule);
+// "Every week on Monday, Wednesday, Friday"
+
+// Monthly on the 15th
+const monthly = createRecurrence({
+  frequency: "monthly",
+  interval: 1,
+  startDate: new Date("2024-01-01"),
+  byMonthDay: [15],
+  until: new Date("2024-12-31"),
+});
+
+const occurrencesInRange = monthly.getOccurrencesBetween(
+  new Date("2024-03-01"),
+  new Date("2024-06-30")
+);
+```
+
+### Countdown & Timer Utilities (NEW!)
+
+```ts
+import {
+  createCountdown,
+  getRemainingTime,
+  formatCountdown,
+} from "ts-time-utils/countdown";
+
+// Create a countdown timer
+const countdown = createCountdown(new Date("2024-12-31T23:59:59"), {
+  onTick: (remaining) => {
+    console.log(`${remaining.days}d ${remaining.hours}h ${remaining.minutes}m`);
+  },
+  onComplete: () => {
+    console.log("Happy New Year!");
+  },
+  interval: 1000, // Update every second
+});
+
+countdown.start();
+// Later...
+countdown.stop();
+
+// Get remaining time
+const remaining = getRemainingTime(new Date("2024-12-31"));
+console.log(`${remaining.days} days, ${remaining.hours} hours remaining`);
+
+// Format countdown
+const formatted = formatCountdown(new Date("2024-12-31"), {
+  units: ["days", "hours", "minutes"],
+  short: true,
+});
+// "45d 12h 30m"
+
+// Progress tracking
+import { getProgressPercentage } from "ts-time-utils/countdown";
+
+const progress = getProgressPercentage(
+  new Date("2024-01-01"),
+  new Date("2024-12-31"),
+  new Date("2024-07-01")
+);
+console.log(`${progress}% complete`); // ~50%
+```
+
+### Date Range Utilities (NEW!)
+
+```ts
+import {
+  mergeDateRanges,
+  findGaps,
+  dateRangeOverlap,
+  splitRange,
+} from "ts-time-utils/dateRange";
+
+// Merge overlapping ranges
+const ranges = [
+  { start: new Date("2024-01-01"), end: new Date("2024-01-10") },
+  { start: new Date("2024-01-05"), end: new Date("2024-01-15") },
+  { start: new Date("2024-01-20"), end: new Date("2024-01-25") },
+];
+
+const merged = mergeDateRanges(ranges);
+// [
+//   { start: Date('2024-01-01'), end: Date('2024-01-15') },
+//   { start: Date('2024-01-20'), end: Date('2024-01-25') }
+// ]
+
+// Find gaps between busy times
+const busyTimes = [
+  { start: new Date("2024-01-01T09:00"), end: new Date("2024-01-01T11:00") },
+  { start: new Date("2024-01-01T14:00"), end: new Date("2024-01-01T16:00") },
+];
+
+const gaps = findGaps(busyTimes, {
+  start: new Date("2024-01-01T08:00"),
+  end: new Date("2024-01-01T18:00"),
+});
+// Returns available time slots
+
+// Split into chunks
+const range = {
+  start: new Date("2024-01-01"),
+  end: new Date("2024-01-31"),
+};
+
+const weeks = splitRange(range, 1, "week");
+// Splits January into weekly chunks
+
+// Check overlap
+const overlap = dateRangeOverlap(
+  { start: new Date("2024-01-01"), end: new Date("2024-01-15") },
+  { start: new Date("2024-01-10"), end: new Date("2024-01-20") }
+); // true
+```
+
+### Natural Language Parsing (NEW!)
+
+```ts
+import {
+  parseNaturalDate,
+  extractDatesFromText,
+  suggestDateFromContext,
+} from "ts-time-utils/naturalLanguage";
+
+// Parse natural language dates
+parseNaturalDate("tomorrow at 3pm");
+// Returns Date for tomorrow at 15:00
+
+parseNaturalDate("next Friday");
+// Returns Date for next Friday
+
+parseNaturalDate("in 2 weeks");
+// Returns Date 2 weeks from now
+
+parseNaturalDate("3 days ago");
+// Returns Date 3 days ago
+
+// Extract dates from text
+const text = "Meeting tomorrow at 3pm and lunch next Friday at noon";
+const dates = extractDatesFromText(text);
+// [
+//   { date: Date(...), text: 'tomorrow at 3pm', index: 8, confidence: 0.9 },
+//   { date: Date(...), text: 'next Friday at noon', index: 35, confidence: 0.85 }
+// ]
+
+// Context-aware suggestions
+const suggestions = suggestDateFromContext("deadline is end of month");
+// [{ date: Date(last day of current month), text: 'end of month', confidence: 0.85 }]
+
+// Supported phrases:
+// - "tomorrow", "yesterday", "today"
+// - "next Monday", "last Friday"
+// - "in 2 hours", "5 days ago"
+// - "end of month/week/year" (or EOM/EOW/EOY)
+// - "beginning of month/year"
+```
+
 ### Duration Utilities
 
 ```ts
@@ -428,6 +747,186 @@ 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
+```
+
 ### Locale Utilities
 
 ```ts
@@ -623,10 +1122,173 @@ 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
+
 ### Calculate Functions
 
 - `differenceInUnits(date1, date2, unit?, precise?)` - Calculate difference between dates
@@ -644,7 +1306,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