ts-time-utils 0.0.1

package/dist/esm/format.js

@@ -0,0 +1,189 @@
+import { MILLISECONDS_PER_SECOND, MILLISECONDS_PER_MINUTE, MILLISECONDS_PER_HOUR, MILLISECONDS_PER_DAY, MILLISECONDS_PER_WEEK, MILLISECONDS_PER_MONTH, MILLISECONDS_PER_YEAR } from './constants.js';
+/**
+ * Convert milliseconds to a human-readable duration.
+ * @param ms - milliseconds
+ * @param options - formatting options
+ */
+export function formatDuration(ms, options = {}) {
+    const { includeMs = false, short = false, maxUnits = 2, round = false } = options;
+    if (ms < 0)
+        return '0' + (short ? 's' : ' seconds');
+    const mathFn = round ? Math.round : Math.floor;
+    const parts = [];
+    let remaining = ms;
+    // Years
+    if (remaining >= MILLISECONDS_PER_YEAR) {
+        const years = mathFn(remaining / MILLISECONDS_PER_YEAR);
+        parts.push(years + (short ? 'y' : ` year${years !== 1 ? 's' : ''}`));
+        remaining %= MILLISECONDS_PER_YEAR;
+    }
+    // Months
+    if (remaining >= MILLISECONDS_PER_MONTH && parts.length < maxUnits) {
+        const months = mathFn(remaining / MILLISECONDS_PER_MONTH);
+        parts.push(months + (short ? 'mo' : ` month${months !== 1 ? 's' : ''}`));
+        remaining %= MILLISECONDS_PER_MONTH;
+    }
+    // Weeks
+    if (remaining >= MILLISECONDS_PER_WEEK && parts.length < maxUnits) {
+        const weeks = mathFn(remaining / MILLISECONDS_PER_WEEK);
+        parts.push(weeks + (short ? 'w' : ` week${weeks !== 1 ? 's' : ''}`));
+        remaining %= MILLISECONDS_PER_WEEK;
+    }
+    // Days
+    if (remaining >= MILLISECONDS_PER_DAY && parts.length < maxUnits) {
+        const days = mathFn(remaining / MILLISECONDS_PER_DAY);
+        parts.push(days + (short ? 'd' : ` day${days !== 1 ? 's' : ''}`));
+        remaining %= MILLISECONDS_PER_DAY;
+    }
+    // Hours
+    if (remaining >= MILLISECONDS_PER_HOUR && parts.length < maxUnits) {
+        const hours = mathFn(remaining / MILLISECONDS_PER_HOUR);
+        parts.push(hours + (short ? 'h' : ` hour${hours !== 1 ? 's' : ''}`));
+        remaining %= MILLISECONDS_PER_HOUR;
+    }
+    // Minutes
+    if (remaining >= MILLISECONDS_PER_MINUTE && parts.length < maxUnits) {
+        const minutes = mathFn(remaining / MILLISECONDS_PER_MINUTE);
+        parts.push(minutes + (short ? 'm' : ` minute${minutes !== 1 ? 's' : ''}`));
+        remaining %= MILLISECONDS_PER_MINUTE;
+    }
+    // Seconds
+    if (remaining >= MILLISECONDS_PER_SECOND && parts.length < maxUnits) {
+        const seconds = mathFn(remaining / MILLISECONDS_PER_SECOND);
+        parts.push(seconds + (short ? 's' : ` second${seconds !== 1 ? 's' : ''}`));
+        remaining %= MILLISECONDS_PER_SECOND;
+    }
+    // Milliseconds
+    if ((remaining > 0 || parts.length === 0) && includeMs && parts.length < maxUnits) {
+        const milliseconds = mathFn(remaining);
+        parts.push(milliseconds + (short ? 'ms' : ` millisecond${milliseconds !== 1 ? 's' : ''}`));
+    }
+    if (parts.length === 0) {
+        return '0' + (short ? 's' : ' seconds');
+    }
+    return short ? parts.join(' ') : parts.join(', ');
+}
+/**
+ * Return a human-readable "time ago" string.
+ * @param date - past or future date
+ * @param options - formatting options
+ */
+export function timeAgo(date, options = {}) {
+    const now = new Date();
+    const diffMs = now.getTime() - date.getTime();
+    const { short = false } = options;
+    const isFuture = diffMs < 0;
+    const absDiffMs = Math.abs(diffMs);
+    if (absDiffMs < MILLISECONDS_PER_MINUTE) {
+        const seconds = Math.floor(absDiffMs / MILLISECONDS_PER_SECOND);
+        const unit = short ? 's' : ` second${seconds !== 1 ? 's' : ''}`;
+        return isFuture ? `in ${seconds}${unit}` : `${seconds}${unit} ago`;
+    }
+    if (absDiffMs < MILLISECONDS_PER_HOUR) {
+        const minutes = Math.floor(absDiffMs / MILLISECONDS_PER_MINUTE);
+        const unit = short ? 'm' : ` minute${minutes !== 1 ? 's' : ''}`;
+        return isFuture ? `in ${minutes}${unit}` : `${minutes}${unit} ago`;
+    }
+    if (absDiffMs < MILLISECONDS_PER_DAY) {
+        const hours = Math.floor(absDiffMs / MILLISECONDS_PER_HOUR);
+        const unit = short ? 'h' : ` hour${hours !== 1 ? 's' : ''}`;
+        return isFuture ? `in ${hours}${unit}` : `${hours}${unit} ago`;
+    }
+    if (absDiffMs < MILLISECONDS_PER_WEEK) {
+        const days = Math.floor(absDiffMs / MILLISECONDS_PER_DAY);
+        const unit = short ? 'd' : ` day${days !== 1 ? 's' : ''}`;
+        return isFuture ? `in ${days}${unit}` : `${days}${unit} ago`;
+    }
+    if (absDiffMs < MILLISECONDS_PER_MONTH) {
+        const weeks = Math.floor(absDiffMs / MILLISECONDS_PER_WEEK);
+        const unit = short ? 'w' : ` week${weeks !== 1 ? 's' : ''}`;
+        return isFuture ? `in ${weeks}${unit}` : `${weeks}${unit} ago`;
+    }
+    if (absDiffMs < MILLISECONDS_PER_YEAR) {
+        const months = Math.floor(absDiffMs / MILLISECONDS_PER_MONTH);
+        const unit = short ? 'mo' : ` month${months !== 1 ? 's' : ''}`;
+        return isFuture ? `in ${months}${unit}` : `${months}${unit} ago`;
+    }
+    const years = Math.floor(absDiffMs / MILLISECONDS_PER_YEAR);
+    const unit = short ? 'y' : ` year${years !== 1 ? 's' : ''}`;
+    return isFuture ? `in ${years}${unit}` : `${years}${unit} ago`;
+}
+/**
+ * Format a date to a human-readable time string
+ * @param date - date to format
+ * @param format - format type
+ */
+export function formatTime(date, format = '24h') {
+    switch (format) {
+        case '12h':
+            return date.toLocaleTimeString('en-US', {
+                hour: 'numeric',
+                minute: '2-digit',
+                hour12: true
+            });
+        case 'iso':
+            return date.toISOString();
+        case '24h':
+        default:
+            return date.toTimeString().split(' ')[0].slice(0, 5); // HH:MM
+    }
+}
+/**
+ * Parse a duration string like "1h 30m" into milliseconds
+ * @param duration - duration string (e.g., "1h 30m", "2d", "45s")
+ */
+export function parseDuration(duration) {
+    const regex = /(\d+(?:\.\d+)?)\s*([a-zA-Z]+)/g;
+    let totalMs = 0;
+    let match;
+    while ((match = regex.exec(duration)) !== null) {
+        const value = parseFloat(match[1]);
+        const unit = match[2].toLowerCase();
+        switch (unit) {
+            case 'ms':
+            case 'millisecond':
+            case 'milliseconds':
+                totalMs += value;
+                break;
+            case 's':
+            case 'sec':
+            case 'second':
+            case 'seconds':
+                totalMs += value * MILLISECONDS_PER_SECOND;
+                break;
+            case 'm':
+            case 'min':
+            case 'minute':
+            case 'minutes':
+                totalMs += value * MILLISECONDS_PER_MINUTE;
+                break;
+            case 'h':
+            case 'hr':
+            case 'hour':
+            case 'hours':
+                totalMs += value * MILLISECONDS_PER_HOUR;
+                break;
+            case 'd':
+            case 'day':
+            case 'days':
+                totalMs += value * MILLISECONDS_PER_DAY;
+                break;
+            case 'w':
+            case 'week':
+            case 'weeks':
+                totalMs += value * MILLISECONDS_PER_WEEK;
+                break;
+            case 'mo':
+            case 'month':
+            case 'months':
+                totalMs += value * MILLISECONDS_PER_MONTH;
+                break;
+            case 'y':
+            case 'year':
+            case 'years':
+                totalMs += value * MILLISECONDS_PER_YEAR;
+                break;
+        }
+    }
+    return totalMs;
+}

package/dist/esm/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * @fileoverview Main entry point for ts-time-utils library
+ * Re-exports all functions from individual modules for convenience
+ */
+export { formatDuration, timeAgo, formatTime, parseDuration } from './format.js';
+export { differenceInUnits, addTime, subtractTime, startOf, endOf, isBetween, businessDaysBetween } from './calculate.js';
+export { isValidDate, isLeapYear, isPast, isFuture, isToday, isYesterday, isTomorrow, isSameDay, isWeekend, isWeekday, isValidTimeString, isValidISOString } from './validate.js';
+export { calculateAge, getAgeInUnits, getLifeStage, getNextBirthday, getDaysUntilBirthday, isBirthday, type AgeResult } from './age.js';
+export { getWeekNumber, getWeekOfMonth, getQuarter, getDayOfYear, getWeeksInYear, getDaysInMonth, getDaysInYear, getEaster, getMonthsInYear, getDaysInMonthArray, getWeekdaysInMonth, getFirstDayOfMonth, getLastDayOfMonth, getFirstDayOfYear, getLastDayOfYear } from './calendar.js';
+export { parseDate, parseRelativeDate, parseTimeAgo, parseCustomFormat, parseManyFormats } from './parse.js';
+export { sleep, timeout, debounce, throttle, retry, createStopwatch, measureTime, measureAsync, benchmark, Stopwatch, type BenchmarkResult } from './performance.js';
+export { createInterval, isValidInterval, intervalDuration, intervalContains, intervalsOverlap, intervalIntersection, mergeIntervals, subtractInterval, splitIntervalByDay, totalIntervalCoverage, normalizeIntervals, type Interval } from './interval.js';
+export { getTimezoneOffset, formatInTimeZone, getZonedTime, convertDateToZone, isValidTimeZone, COMMON_TIMEZONES, getLocalOffset, compareZoneOffsets, reinterpretAsZone, type ZonedTime } from './timezone.js';
+export { DEFAULT_WORKING_HOURS, isWorkingDay, isWorkingTime, nextWorkingTime, workingTimeBetween, addWorkingHours, type WorkingHoursConfig } from './workingHours.js';
+export { today, yesterday, tomorrow, lastNDays, nextNDays, thisWeek, lastWeek, nextWeek, thisMonth, lastMonth, nextMonth, thisYear, lastYear, nextYear, rollingWindowDays, quarterRange, lastQuarter, nextQuarter, RANGE_PRESETS, type DateRange } from './rangePresets.js';
+export { MILLISECONDS_PER_SECOND, MILLISECONDS_PER_MINUTE, MILLISECONDS_PER_HOUR, MILLISECONDS_PER_DAY, MILLISECONDS_PER_WEEK, MILLISECONDS_PER_MONTH, MILLISECONDS_PER_YEAR, SECONDS_PER_MINUTE, SECONDS_PER_HOUR, SECONDS_PER_DAY, SECONDS_PER_WEEK, type TimeUnit, type FormatOptions } from './constants.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EACL,cAAc,EACd,OAAO,EACP,UAAU,EACV,aAAa,EACd,MAAM,aAAa,CAAC;AAGrB,OAAO,EACL,iBAAiB,EACjB,OAAO,EACP,YAAY,EACZ,OAAO,EACP,KAAK,EACL,SAAS,EACT,mBAAmB,EACpB,MAAM,gBAAgB,CAAC;AAGxB,OAAO,EACL,WAAW,EACX,UAAU,EACV,MAAM,EACN,QAAQ,EACR,OAAO,EACP,WAAW,EACX,UAAU,EACV,SAAS,EACT,SAAS,EACT,SAAS,EACT,iBAAiB,EACjB,gBAAgB,EACjB,MAAM,eAAe,CAAC;AAGvB,OAAO,EACL,YAAY,EACZ,aAAa,EACb,YAAY,EACZ,eAAe,EACf,oBAAoB,EACpB,UAAU,EACV,KAAK,SAAS,EACf,MAAM,UAAU,CAAC;AAGlB,OAAO,EACL,aAAa,EACb,cAAc,EACd,UAAU,EACV,YAAY,EACZ,cAAc,EACd,cAAc,EACd,aAAa,EACb,SAAS,EACT,eAAe,EACf,mBAAmB,EACnB,kBAAkB,EAClB,kBAAkB,EAClB,iBAAiB,EACjB,iBAAiB,EACjB,gBAAgB,EACjB,MAAM,eAAe,CAAC;AAGvB,OAAO,EACL,SAAS,EACT,iBAAiB,EACjB,YAAY,EACZ,iBAAiB,EACjB,gBAAgB,EACjB,MAAM,YAAY,CAAC;AAGpB,OAAO,EACL,KAAK,EACL,OAAO,EACP,QAAQ,EACR,QAAQ,EACR,KAAK,EACL,eAAe,EACf,WAAW,EACX,YAAY,EACZ,SAAS,EACT,SAAS,EACT,KAAK,eAAe,EACrB,MAAM,kBAAkB,CAAC;AAG1B,OAAO,EACL,cAAc,EACd,eAAe,EACf,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,EAChB,oBAAoB,EACpB,cAAc,EACd,gBAAgB,EAChB,kBAAkB,EAClB,qBAAqB,EACrB,kBAAkB,EAClB,KAAK,QAAQ,EACd,MAAM,eAAe,CAAC;AAGvB,OAAO,EACL,iBAAiB,EACjB,gBAAgB,EAChB,YAAY,EACZ,iBAAiB,EACjB,eAAe,EACf,gBAAgB,EAChB,cAAc,EACd,kBAAkB,EAClB,iBAAiB,EACjB,KAAK,SAAS,EACf,MAAM,eAAe,CAAC;AAGvB,OAAO,EACL,qBAAqB,EACrB,YAAY,EACZ,aAAa,EACb,eAAe,EACf,kBAAkB,EAClB,eAAe,EACf,KAAK,kBAAkB,EACxB,MAAM,mBAAmB,CAAC;AAG3B,OAAO,EACL,KAAK,EACL,SAAS,EACT,QAAQ,EACR,SAAS,EACT,SAAS,EACT,QAAQ,EACR,QAAQ,EACR,QAAQ,EACR,SAAS,EACT,SAAS,EACT,SAAS,EACT,QAAQ,EACR,QAAQ,EACR,QAAQ,EACR,iBAAiB,EACjB,YAAY,EACZ,WAAW,EACX,WAAW,EACX,aAAa,EACb,KAAK,SAAS,EACf,MAAM,mBAAmB,CAAC;AAG3B,OAAO,EACL,uBAAuB,EACvB,uBAAuB,EACvB,qBAAqB,EACrB,oBAAoB,EACpB,qBAAqB,EACrB,sBAAsB,EACtB,qBAAqB,EACrB,kBAAkB,EAClB,gBAAgB,EAChB,eAAe,EACf,gBAAgB,EAChB,KAAK,QAAQ,EACb,KAAK,aAAa,EACnB,MAAM,gBAAgB,CAAC"}

package/dist/esm/index.js

@@ -0,0 +1,28 @@
+/**
+ * @fileoverview Main entry point for ts-time-utils library
+ * Re-exports all functions from individual modules for convenience
+ */
+// Format utilities
+export { formatDuration, timeAgo, formatTime, parseDuration } from './format.js';
+// Calculation utilities  
+export { differenceInUnits, addTime, subtractTime, startOf, endOf, isBetween, businessDaysBetween } from './calculate.js';
+// Validation utilities
+export { isValidDate, isLeapYear, isPast, isFuture, isToday, isYesterday, isTomorrow, isSameDay, isWeekend, isWeekday, isValidTimeString, isValidISOString } from './validate.js';
+// Age utilities
+export { calculateAge, getAgeInUnits, getLifeStage, getNextBirthday, getDaysUntilBirthday, isBirthday } from './age.js';
+// Calendar utilities
+export { getWeekNumber, getWeekOfMonth, getQuarter, getDayOfYear, getWeeksInYear, getDaysInMonth, getDaysInYear, getEaster, getMonthsInYear, getDaysInMonthArray, getWeekdaysInMonth, getFirstDayOfMonth, getLastDayOfMonth, getFirstDayOfYear, getLastDayOfYear } from './calendar.js';
+// Parse utilities
+export { parseDate, parseRelativeDate, parseTimeAgo, parseCustomFormat, parseManyFormats } from './parse.js';
+// Performance utilities
+export { sleep, timeout, debounce, throttle, retry, createStopwatch, measureTime, measureAsync, benchmark, Stopwatch } from './performance.js';
+// Interval utilities
+export { createInterval, isValidInterval, intervalDuration, intervalContains, intervalsOverlap, intervalIntersection, mergeIntervals, subtractInterval, splitIntervalByDay, totalIntervalCoverage, normalizeIntervals } from './interval.js';
+// Timezone utilities
+export { getTimezoneOffset, formatInTimeZone, getZonedTime, convertDateToZone, isValidTimeZone, COMMON_TIMEZONES, getLocalOffset, compareZoneOffsets, reinterpretAsZone } from './timezone.js';
+// Working hours utilities
+export { DEFAULT_WORKING_HOURS, isWorkingDay, isWorkingTime, nextWorkingTime, workingTimeBetween, addWorkingHours } from './workingHours.js';
+// Range preset utilities
+export { today, yesterday, tomorrow, lastNDays, nextNDays, thisWeek, lastWeek, nextWeek, thisMonth, lastMonth, nextMonth, thisYear, lastYear, nextYear, rollingWindowDays, quarterRange, lastQuarter, nextQuarter, RANGE_PRESETS } from './rangePresets.js';
+// Constants and types
+export { MILLISECONDS_PER_SECOND, MILLISECONDS_PER_MINUTE, MILLISECONDS_PER_HOUR, MILLISECONDS_PER_DAY, MILLISECONDS_PER_WEEK, MILLISECONDS_PER_MONTH, MILLISECONDS_PER_YEAR, SECONDS_PER_MINUTE, SECONDS_PER_HOUR, SECONDS_PER_DAY, SECONDS_PER_WEEK } from './constants.js';

package/dist/esm/interval.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Interval utilities: operations on time intervals [start, end)
+ */
+export interface Interval {
+    start: Date;
+    end: Date;
+}
+/** Create an interval ensuring start <= end */
+export declare function createInterval(start: Date | string | number, end: Date | string | number): Interval | null;
+/** Validate an object is a proper interval */
+export declare function isValidInterval(i: any): i is Interval;
+/** Duration of interval in ms */
+export declare function intervalDuration(i: Interval): number;
+/** Whether interval contains date (inclusive start, exclusive end) */
+export declare function intervalContains(i: Interval, date: Date | number): boolean;
+/** Whether two intervals overlap */
+export declare function intervalsOverlap(a: Interval, b: Interval): boolean;
+/** Intersection of two intervals, or null */
+export declare function intervalIntersection(a: Interval, b: Interval): Interval | null;
+/** Merge overlapping or touching intervals into a minimal set */
+export declare function mergeIntervals(intervals: Interval[]): Interval[];
+/** Subtract interval b from a (can split into 0,1,2 intervals) */
+export declare function subtractInterval(a: Interval, b: Interval): Interval[];
+/** Split an interval into day-boundary intervals (UTC based) */
+export declare function splitIntervalByDay(i: Interval): Interval[];
+/** Total covered duration of possibly overlapping intervals */
+export declare function totalIntervalCoverage(intervals: Interval[]): number;
+/** Normalize array: filter invalid and merge */
+export declare function normalizeIntervals(intervals: (Interval | null | undefined)[]): Interval[];
+//# sourceMappingURL=interval.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"interval.d.ts","sourceRoot":"","sources":["../../src/interval.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,WAAW,QAAQ;IACvB,KAAK,EAAE,IAAI,CAAC;IACZ,GAAG,EAAE,IAAI,CAAC;CACX;AAED,+CAA+C;AAC/C,wBAAgB,cAAc,CAAC,KAAK,EAAE,IAAI,GAAG,MAAM,GAAG,MAAM,EAAE,GAAG,EAAE,IAAI,GAAG,MAAM,GAAG,MAAM,GAAG,QAAQ,GAAG,IAAI,CAK1G;AAED,8CAA8C;AAC9C,wBAAgB,eAAe,CAAC,CAAC,EAAE,GAAG,GAAG,CAAC,IAAI,QAAQ,CAErD;AAED,iCAAiC;AACjC,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,QAAQ,GAAG,MAAM,CAEpD;AAED,sEAAsE;AACtE,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,QAAQ,EAAE,IAAI,EAAE,IAAI,GAAG,MAAM,GAAG,OAAO,CAG1E;AAED,oCAAoC;AACpC,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,QAAQ,GAAG,OAAO,CAElE;AAED,6CAA6C;AAC7C,wBAAgB,oBAAoB,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,QAAQ,GAAG,QAAQ,GAAG,IAAI,CAI9E;AAED,iEAAiE;AACjE,wBAAgB,cAAc,CAAC,SAAS,EAAE,QAAQ,EAAE,GAAG,QAAQ,EAAE,CAgBhE;AAED,kEAAkE;AAClE,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,EAAE,QAAQ,GAAG,QAAQ,EAAE,CAMrE;AAED,gEAAgE;AAChE,wBAAgB,kBAAkB,CAAC,CAAC,EAAE,QAAQ,GAAG,QAAQ,EAAE,CAU1D;AAED,+DAA+D;AAC/D,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,QAAQ,EAAE,GAAG,MAAM,CAEnE;AAED,gDAAgD;AAChD,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,CAAC,QAAQ,GAAG,IAAI,GAAG,SAAS,CAAC,EAAE,GAAG,QAAQ,EAAE,CAEzF"}

package/dist/esm/interval.js

@@ -0,0 +1,86 @@
+/**
+ * Interval utilities: operations on time intervals [start, end)
+ */
+/** Create an interval ensuring start <= end */
+export function createInterval(start, end) {
+    const s = new Date(start);
+    const e = new Date(end);
+    if (isNaN(s.getTime()) || isNaN(e.getTime()) || s > e)
+        return null;
+    return { start: s, end: e };
+}
+/** Validate an object is a proper interval */
+export function isValidInterval(i) {
+    return !!i && i.start instanceof Date && i.end instanceof Date && !isNaN(i.start) && !isNaN(i.end) && i.start <= i.end;
+}
+/** Duration of interval in ms */
+export function intervalDuration(i) {
+    return i.end.getTime() - i.start.getTime();
+}
+/** Whether interval contains date (inclusive start, exclusive end) */
+export function intervalContains(i, date) {
+    const d = date instanceof Date ? date : new Date(date);
+    return d >= i.start && d < i.end;
+}
+/** Whether two intervals overlap */
+export function intervalsOverlap(a, b) {
+    return a.start < b.end && b.start < a.end;
+}
+/** Intersection of two intervals, or null */
+export function intervalIntersection(a, b) {
+    const start = a.start > b.start ? a.start : b.start;
+    const end = a.end < b.end ? a.end : b.end;
+    return start < end ? { start, end } : null;
+}
+/** Merge overlapping or touching intervals into a minimal set */
+export function mergeIntervals(intervals) {
+    if (intervals.length === 0)
+        return [];
+    const sorted = [...intervals].sort((a, b) => a.start.getTime() - b.start.getTime());
+    const result = [];
+    let current = { ...sorted[0] };
+    for (let i = 1; i < sorted.length; i++) {
+        const next = sorted[i];
+        if (next.start <= current.end) { // overlap or touching
+            if (next.end > current.end)
+                current.end = next.end;
+        }
+        else {
+            result.push(current);
+            current = { ...next };
+        }
+    }
+    result.push(current);
+    return result;
+}
+/** Subtract interval b from a (can split into 0,1,2 intervals) */
+export function subtractInterval(a, b) {
+    if (!intervalsOverlap(a, b))
+        return [a];
+    const parts = [];
+    if (b.start > a.start)
+        parts.push({ start: a.start, end: b.start });
+    if (b.end < a.end)
+        parts.push({ start: b.end, end: a.end });
+    return parts;
+}
+/** Split an interval into day-boundary intervals (UTC based) */
+export function splitIntervalByDay(i) {
+    const res = [];
+    let cursor = new Date(i.start);
+    while (cursor < i.end) {
+        const dayEnd = new Date(Date.UTC(cursor.getUTCFullYear(), cursor.getUTCMonth(), cursor.getUTCDate() + 1));
+        const end = dayEnd < i.end ? dayEnd : i.end;
+        res.push({ start: new Date(cursor), end: new Date(end) });
+        cursor = end;
+    }
+    return res;
+}
+/** Total covered duration of possibly overlapping intervals */
+export function totalIntervalCoverage(intervals) {
+    return mergeIntervals(intervals).reduce((sum, i) => sum + intervalDuration(i), 0);
+}
+/** Normalize array: filter invalid and merge */
+export function normalizeIntervals(intervals) {
+    return mergeIntervals(intervals.filter(isValidInterval));
+}

package/dist/esm/parse.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Advanced date parsing utilities
+ */
+/**
+ * Parse various date formats intelligently
+ * @param input - date string, number, or Date object
+ */
+export declare function parseDate(input: string | number | Date): Date | null;
+/**
+ * Parse relative date strings like "tomorrow", "next monday", "2 weeks ago"
+ * @param input - relative date string
+ */
+export declare function parseRelativeDate(input: string): Date | null;
+/**
+ * Parse "time ago" strings like "5 minutes ago", "2 hours ago"
+ * @param input - time ago string
+ */
+export declare function parseTimeAgo(input: string): Date | null;
+/**
+ * Parse custom date format
+ * @param dateString - date string to parse
+ * @param format - format pattern (e.g., "YYYY-MM-DD", "DD/MM/YYYY")
+ */
+export declare function parseCustomFormat(dateString: string, format: string): Date | null;
+/**
+ * Try parsing with multiple formats
+ * @param dateString - date string to parse
+ * @param formats - array of format patterns to try
+ */
+export declare function parseManyFormats(dateString: string, formats: string[]): Date | null;
+//# sourceMappingURL=parse.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"parse.d.ts","sourceRoot":"","sources":["../../src/parse.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;GAGG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAuDpE;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CA6C5D;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAiBvD;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAmDjF;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,GAAG,IAAI,CAMnF"}

package/dist/esm/parse.js

@@ -0,0 +1,217 @@
+/**
+ * Advanced date parsing utilities
+ */
+/**
+ * Parse various date formats intelligently
+ * @param input - date string, number, or Date object
+ */
+export function parseDate(input) {
+    if (input instanceof Date) {
+        return isNaN(input.getTime()) ? null : input;
+    }
+    if (typeof input === 'number') {
+        const date = new Date(input);
+        return isNaN(date.getTime()) ? null : date;
+    }
+    if (typeof input !== 'string') {
+        return null;
+    }
+    // Try native Date parsing first, but validate the result
+    const nativeDate = new Date(input);
+    if (!isNaN(nativeDate.getTime())) {
+        // Additional validation for edge cases like "2025-02-30"
+        if (input.includes('-') && input.match(/^\d{4}-\d{2}-\d{2}/)) {
+            const [year, month, day] = input.split('-').map(Number);
+            const testDate = new Date(year, month - 1, day);
+            if (testDate.getFullYear() !== year || testDate.getMonth() !== month - 1 || testDate.getDate() !== day) {
+                return null;
+            }
+        }
+        return nativeDate;
+    }
+    // Try common patterns
+    const patterns = [
+        /^(\d{4})-(\d{2})-(\d{2})$/, // YYYY-MM-DD
+        /^(\d{2})\/(\d{2})\/(\d{4})$/, // MM/DD/YYYY
+        /^(\d{2})-(\d{2})-(\d{4})$/, // MM-DD-YYYY
+        /^(\d{4})(\d{2})(\d{2})$/, // YYYYMMDD
+    ];
+    for (const pattern of patterns) {
+        const match = input.match(pattern);
+        if (match) {
+            const [, first, second, third] = match;
+            // Try different interpretations based on pattern
+            if (pattern.source.includes('(\\d{4})')) {
+                // Year first format
+                const date = new Date(parseInt(first), parseInt(second) - 1, parseInt(third));
+                if (!isNaN(date.getTime()))
+                    return date;
+            }
+            else {
+                // Month/day first format (assuming US format)
+                const date = new Date(parseInt(third), parseInt(first) - 1, parseInt(second));
+                if (!isNaN(date.getTime()))
+                    return date;
+            }
+        }
+    }
+    return null;
+}
+/**
+ * Parse relative date strings like "tomorrow", "next monday", "2 weeks ago"
+ * @param input - relative date string
+ */
+export function parseRelativeDate(input) {
+    const now = new Date();
+    const lowercaseInput = input.toLowerCase().trim();
+    // Handle simple cases
+    switch (lowercaseInput) {
+        case 'now':
+        case 'today':
+            return new Date(now.getFullYear(), now.getMonth(), now.getDate());
+        case 'yesterday':
+            return new Date(now.getFullYear(), now.getMonth(), now.getDate() - 1);
+        case 'tomorrow':
+            return new Date(now.getFullYear(), now.getMonth(), now.getDate() + 1);
+    }
+    // Handle "X time ago" or "in X time"
+    const agoMatch = lowercaseInput.match(/^(\d+)\s+(second|minute|hour|day|week|month|year)s?\s+ago$/);
+    if (agoMatch) {
+        const [, amount, unit] = agoMatch;
+        return subtractTimeUnits(now, parseInt(amount), unit);
+    }
+    const inMatch = lowercaseInput.match(/^in\s+(\d+)\s+(second|minute|hour|day|week|month|year)s?$/);
+    if (inMatch) {
+        const [, amount, unit] = inMatch;
+        return addTimeUnits(now, parseInt(amount), unit);
+    }
+    // Handle "next/last weekday"
+    const weekdays = ['sunday', 'monday', 'tuesday', 'wednesday', 'thursday', 'friday', 'saturday'];
+    const nextWeekdayMatch = lowercaseInput.match(/^next\s+(sunday|monday|tuesday|wednesday|thursday|friday|saturday)$/);
+    if (nextWeekdayMatch) {
+        const targetDay = weekdays.indexOf(nextWeekdayMatch[1]);
+        const daysUntilTarget = (targetDay - now.getDay() + 7) % 7 || 7;
+        return new Date(now.getFullYear(), now.getMonth(), now.getDate() + daysUntilTarget);
+    }
+    const lastWeekdayMatch = lowercaseInput.match(/^last\s+(sunday|monday|tuesday|wednesday|thursday|friday|saturday)$/);
+    if (lastWeekdayMatch) {
+        const targetDay = weekdays.indexOf(lastWeekdayMatch[1]);
+        const daysSinceTarget = (now.getDay() - targetDay + 7) % 7 || 7;
+        return new Date(now.getFullYear(), now.getMonth(), now.getDate() - daysSinceTarget);
+    }
+    return null;
+}
+/**
+ * Parse "time ago" strings like "5 minutes ago", "2 hours ago"
+ * @param input - time ago string
+ */
+export function parseTimeAgo(input) {
+    const now = new Date();
+    const lowercaseInput = input.toLowerCase().trim();
+    // Handle simple cases
+    if (lowercaseInput === 'just now' || lowercaseInput === 'now') {
+        return now;
+    }
+    // Handle "X time ago"
+    const match = lowercaseInput.match(/^(\d+)\s+(second|minute|hour|day|week|month|year)s?\s+ago$/);
+    if (match) {
+        const [, amount, unit] = match;
+        return subtractTimeUnits(now, parseInt(amount), unit);
+    }
+    return null;
+}
+/**
+ * Parse custom date format
+ * @param dateString - date string to parse
+ * @param format - format pattern (e.g., "YYYY-MM-DD", "DD/MM/YYYY")
+ */
+export function parseCustomFormat(dateString, format) {
+    // Simple implementation for common patterns
+    const formatMap = {
+        'YYYY-MM-DD': /^(\d{4})-(\d{2})-(\d{2})$/,
+        'DD/MM/YYYY': /^(\d{2})\/(\d{2})\/(\d{4})$/,
+        'MM/DD/YYYY': /^(\d{2})\/(\d{2})\/(\d{4})$/,
+        'DD-MM-YYYY': /^(\d{2})-(\d{2})-(\d{4})$/,
+        'MM-DD-YYYY': /^(\d{2})-(\d{2})-(\d{4})$/,
+    };
+    const regex = formatMap[format];
+    if (!regex)
+        return null;
+    const match = dateString.match(regex);
+    if (!match)
+        return null;
+    const [, first, second, third] = match;
+    let year, month, day;
+    switch (format) {
+        case 'YYYY-MM-DD':
+            year = parseInt(first);
+            month = parseInt(second) - 1;
+            day = parseInt(third);
+            break;
+        case 'DD/MM/YYYY':
+        case 'DD-MM-YYYY':
+            day = parseInt(first);
+            month = parseInt(second) - 1;
+            year = parseInt(third);
+            break;
+        case 'MM/DD/YYYY':
+        case 'MM-DD-YYYY':
+            month = parseInt(first) - 1;
+            day = parseInt(second);
+            year = parseInt(third);
+            break;
+        default:
+            return null;
+    }
+    const date = new Date(year, month, day);
+    // Validate that the date components match what was parsed
+    // This catches cases like February 30th which JS converts to March 2nd
+    if (date.getFullYear() !== year || date.getMonth() !== month || date.getDate() !== day) {
+        return null;
+    }
+    return isNaN(date.getTime()) ? null : date;
+}
+/**
+ * Try parsing with multiple formats
+ * @param dateString - date string to parse
+ * @param formats - array of format patterns to try
+ */
+export function parseManyFormats(dateString, formats) {
+    for (const format of formats) {
+        const result = parseCustomFormat(dateString, format);
+        if (result)
+            return result;
+    }
+    return null;
+}
+// Helper functions
+function addTimeUnits(date, amount, unit) {
+    const result = new Date(date);
+    switch (unit) {
+        case 'second':
+            result.setSeconds(result.getSeconds() + amount);
+            break;
+        case 'minute':
+            result.setMinutes(result.getMinutes() + amount);
+            break;
+        case 'hour':
+            result.setHours(result.getHours() + amount);
+            break;
+        case 'day':
+            result.setDate(result.getDate() + amount);
+            break;
+        case 'week':
+            result.setDate(result.getDate() + (amount * 7));
+            break;
+        case 'month':
+            result.setMonth(result.getMonth() + amount);
+            break;
+        case 'year':
+            result.setFullYear(result.getFullYear() + amount);
+            break;
+    }
+    return result;
+}
+function subtractTimeUnits(date, amount, unit) {
+    return addTimeUnits(date, -amount, unit);
+}