ts-time-utils 1.0.0 → 1.1.0

package/dist/esm/dateRange.d.ts

@@ -0,0 +1,266 @@
+/**
+ * @fileoverview Extended date range operations and utilities
+ * Provides advanced operations for working with date ranges beyond basic intervals
+ */
+import type { DateRange, DateInput } from './types.js';
+/**
+ * Checks if two date ranges overlap
+ * @param range1 - First date range
+ * @param range2 - Second date range
+ * @returns True if the ranges overlap
+ *
+ * @example
+ * ```ts
+ * const range1 = { start: new Date('2024-01-01'), end: new Date('2024-01-10') };
+ * const range2 = { start: new Date('2024-01-05'), end: new Date('2024-01-15') };
+ *
+ * dateRangeOverlap(range1, range2); // true
+ * ```
+ */
+export declare function dateRangeOverlap(range1: DateRange, range2: DateRange): boolean;
+/**
+ * Checks if multiple date ranges have any overlaps
+ * @param ranges - Array of date ranges
+ * @returns True if any two ranges overlap
+ *
+ * @example
+ * ```ts
+ * 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') }
+ * ];
+ *
+ * hasOverlappingRanges(ranges); // true
+ * ```
+ */
+export declare function hasOverlappingRanges(ranges: DateRange[]): boolean;
+/**
+ * Merges overlapping or adjacent date ranges
+ * @param ranges - Array of date ranges to merge
+ * @returns Array of merged, non-overlapping ranges
+ *
+ * @example
+ * ```ts
+ * 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') }
+ * ];
+ *
+ * mergeDateRanges(ranges);
+ * // [
+ * //   { start: Date('2024-01-01'), end: Date('2024-01-15') },
+ * //   { start: Date('2024-01-20'), end: Date('2024-01-25') }
+ * // ]
+ * ```
+ */
+export declare function mergeDateRanges(ranges: DateRange[]): DateRange[];
+/**
+ * Finds gaps between date ranges within specified bounds
+ * @param ranges - Array of date ranges
+ * @param bounds - Optional bounds to search within
+ * @returns Array of date ranges representing gaps
+ *
+ * @example
+ * ```ts
+ * const ranges = [
+ *   { start: new Date('2024-01-01'), end: new Date('2024-01-05') },
+ *   { start: new Date('2024-01-10'), end: new Date('2024-01-15') }
+ * ];
+ *
+ * findGaps(ranges, {
+ *   start: new Date('2024-01-01'),
+ *   end: new Date('2024-01-20')
+ * });
+ * // [
+ * //   { start: Date('2024-01-06'), end: Date('2024-01-09') },
+ * //   { start: Date('2024-01-16'), end: Date('2024-01-20') }
+ * // ]
+ * ```
+ */
+export declare function findGaps(ranges: DateRange[], bounds?: DateRange): DateRange[];
+/**
+ * Splits a date range into smaller chunks
+ * @param range - The date range to split
+ * @param chunkSize - Size of each chunk
+ * @param unit - Unit for chunk size
+ * @returns Array of date ranges
+ *
+ * @example
+ * ```ts
+ * const range = {
+ *   start: new Date('2024-01-01'),
+ *   end: new Date('2024-01-10')
+ * };
+ *
+ * splitRange(range, 3, 'day');
+ * // Returns 4 ranges: 3 days, 3 days, 3 days, 1 day
+ * ```
+ */
+export declare function splitRange(range: DateRange, chunkSize: number, unit: 'millisecond' | 'second' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'year'): DateRange[];
+/**
+ * Checks if a date falls within a date range
+ * @param range - The date range
+ * @param date - The date to check
+ * @param inclusive - Whether to include boundary dates (default: true)
+ * @returns True if date is within range
+ *
+ * @example
+ * ```ts
+ * const range = {
+ *   start: new Date('2024-01-01'),
+ *   end: new Date('2024-01-31')
+ * };
+ *
+ * containsDate(range, new Date('2024-01-15')); // true
+ * containsDate(range, new Date('2024-02-01')); // false
+ * ```
+ */
+export declare function containsDate(range: DateRange, date: DateInput, inclusive?: boolean): boolean;
+/**
+ * Gets the intersection of two date ranges
+ * @param range1 - First date range
+ * @param range2 - Second date range
+ * @returns The overlapping range, or null if no overlap
+ *
+ * @example
+ * ```ts
+ * const range1 = { start: new Date('2024-01-01'), end: new Date('2024-01-15') };
+ * const range2 = { start: new Date('2024-01-10'), end: new Date('2024-01-20') };
+ *
+ * getIntersection(range1, range2);
+ * // { start: Date('2024-01-10'), end: Date('2024-01-15') }
+ * ```
+ */
+export declare function getIntersection(range1: DateRange, range2: DateRange): DateRange | null;
+/**
+ * Gets the union (combined coverage) of two date ranges
+ * @param range1 - First date range
+ * @param range2 - Second date range
+ * @returns The combined range covering both inputs
+ *
+ * @example
+ * ```ts
+ * const range1 = { start: new Date('2024-01-01'), end: new Date('2024-01-15') };
+ * const range2 = { start: new Date('2024-01-10'), end: new Date('2024-01-20') };
+ *
+ * getUnion(range1, range2);
+ * // { start: Date('2024-01-01'), end: Date('2024-01-20') }
+ * ```
+ */
+export declare function getUnion(range1: DateRange, range2: DateRange): DateRange;
+/**
+ * Subtracts one date range from another
+ * @param range - The range to subtract from
+ * @param subtract - The range to subtract
+ * @returns Array of remaining date ranges (0-2 ranges)
+ *
+ * @example
+ * ```ts
+ * const range = { start: new Date('2024-01-01'), end: new Date('2024-01-31') };
+ * const subtract = { start: new Date('2024-01-10'), end: new Date('2024-01-20') };
+ *
+ * subtractRange(range, subtract);
+ * // [
+ * //   { start: Date('2024-01-01'), end: Date('2024-01-09') },
+ * //   { start: Date('2024-01-21'), end: Date('2024-01-31') }
+ * // ]
+ * ```
+ */
+export declare function subtractRange(range: DateRange, subtract: DateRange): DateRange[];
+/**
+ * Calculates the duration of a date range in milliseconds
+ * @param range - The date range
+ * @returns Duration in milliseconds
+ *
+ * @example
+ * ```ts
+ * const range = {
+ *   start: new Date('2024-01-01'),
+ *   end: new Date('2024-01-02')
+ * };
+ *
+ * getRangeDuration(range); // 86400000 (1 day in ms)
+ * ```
+ */
+export declare function getRangeDuration(range: DateRange): number;
+/**
+ * Expands a date range by a specified amount
+ * @param range - The date range to expand
+ * @param amount - Amount to expand by
+ * @param unit - Unit for expansion
+ * @param options - Expansion options
+ * @returns Expanded date range
+ *
+ * @example
+ * ```ts
+ * const range = {
+ *   start: new Date('2024-01-10'),
+ *   end: new Date('2024-01-20')
+ * };
+ *
+ * expandRange(range, 5, 'day');
+ * // { start: Date('2024-01-05'), end: Date('2024-01-25') }
+ *
+ * expandRange(range, 5, 'day', { direction: 'before' });
+ * // { start: Date('2024-01-05'), end: Date('2024-01-20') }
+ * ```
+ */
+export declare function expandRange(range: DateRange, amount: number, unit: 'millisecond' | 'second' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'year', options?: {
+    direction?: 'both' | 'before' | 'after';
+}): DateRange;
+/**
+ * Shrinks a date range by a specified amount
+ * @param range - The date range to shrink
+ * @param amount - Amount to shrink by
+ * @param unit - Unit for shrinking
+ * @param options - Shrink options
+ * @returns Shrunk date range, or null if result would be invalid
+ *
+ * @example
+ * ```ts
+ * const range = {
+ *   start: new Date('2024-01-01'),
+ *   end: new Date('2024-01-31')
+ * };
+ *
+ * shrinkRange(range, 5, 'day');
+ * // { start: Date('2024-01-06'), end: Date('2024-01-26') }
+ * ```
+ */
+export declare function shrinkRange(range: DateRange, amount: number, unit: 'millisecond' | 'second' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'year', options?: {
+    direction?: 'both' | 'start' | 'end';
+}): DateRange | null;
+/**
+ * Checks if one date range completely contains another
+ * @param outer - The potentially containing range
+ * @param inner - The potentially contained range
+ * @returns True if outer completely contains inner
+ *
+ * @example
+ * ```ts
+ * const outer = { start: new Date('2024-01-01'), end: new Date('2024-01-31') };
+ * const inner = { start: new Date('2024-01-10'), end: new Date('2024-01-20') };
+ *
+ * rangeContains(outer, inner); // true
+ * ```
+ */
+export declare function rangeContains(outer: DateRange, inner: DateRange): boolean;
+/**
+ * Sorts an array of date ranges by start date
+ * @param ranges - Array of date ranges
+ * @param order - Sort order ('asc' or 'desc')
+ * @returns Sorted array of date ranges
+ *
+ * @example
+ * ```ts
+ * const ranges = [
+ *   { start: new Date('2024-01-15'), end: new Date('2024-01-20') },
+ *   { start: new Date('2024-01-01'), end: new Date('2024-01-10') }
+ * ];
+ *
+ * sortRanges(ranges); // Sorted by start date ascending
+ * ```
+ */
+export declare function sortRanges(ranges: DateRange[], order?: 'asc' | 'desc'): DateRange[];
+//# sourceMappingURL=dateRange.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"dateRange.d.ts","sourceRoot":"","sources":["../../src/dateRange.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAGvD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,GAAG,OAAO,CAE9E;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,SAAS,EAAE,GAAG,OAAO,CASjE;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,SAAS,EAAE,GAAG,SAAS,EAAE,CA0BhE;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,SAAS,EAAE,EAAE,MAAM,CAAC,EAAE,SAAS,GAAG,SAAS,EAAE,CA2C7E;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,UAAU,CACxB,KAAK,EAAE,SAAS,EAChB,SAAS,EAAE,MAAM,EACjB,IAAI,EAAE,aAAa,GAAG,QAAQ,GAAG,QAAQ,GAAG,MAAM,GAAG,KAAK,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,GACrF,SAAS,EAAE,CA2Bb;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,SAAS,EAChB,IAAI,EAAE,SAAS,EACf,SAAS,UAAO,GACf,OAAO,CAQT;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,GAAG,SAAS,GAAG,IAAI,CAStF;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,GAAG,SAAS,CAKxE;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,SAAS,GAAG,SAAS,EAAE,CAyBhF;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,SAAS,GAAG,MAAM,CAEzD;AAED;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,SAAS,EAChB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,aAAa,GAAG,QAAQ,GAAG,QAAQ,GAAG,MAAM,GAAG,KAAK,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,EACtF,OAAO,GAAE;IACP,SAAS,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,OAAO,CAAA;CACnC,GACL,SAAS,CAkBX;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,SAAS,EAChB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,aAAa,GAAG,QAAQ,GAAG,QAAQ,GAAG,MAAM,GAAG,KAAK,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,EACtF,OAAO,GAAE;IACP,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,GAAG,KAAK,CAAA;CAChC,GACL,SAAS,GAAG,IAAI,CAuBlB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,SAAS,GAAG,OAAO,CAEzE;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,SAAS,EAAE,EAAE,KAAK,GAAE,KAAK,GAAG,MAAc,GAAG,SAAS,EAAE,CAO1F"}

package/dist/esm/dateRange.js

@@ -0,0 +1,433 @@
+/**
+ * @fileoverview Extended date range operations and utilities
+ * Provides advanced operations for working with date ranges beyond basic intervals
+ */
+import { addTime } from './calculate.js';
+/**
+ * Checks if two date ranges overlap
+ * @param range1 - First date range
+ * @param range2 - Second date range
+ * @returns True if the ranges overlap
+ *
+ * @example
+ * ```ts
+ * const range1 = { start: new Date('2024-01-01'), end: new Date('2024-01-10') };
+ * const range2 = { start: new Date('2024-01-05'), end: new Date('2024-01-15') };
+ *
+ * dateRangeOverlap(range1, range2); // true
+ * ```
+ */
+export function dateRangeOverlap(range1, range2) {
+    return range1.start <= range2.end && range2.start <= range1.end;
+}
+/**
+ * Checks if multiple date ranges have any overlaps
+ * @param ranges - Array of date ranges
+ * @returns True if any two ranges overlap
+ *
+ * @example
+ * ```ts
+ * 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') }
+ * ];
+ *
+ * hasOverlappingRanges(ranges); // true
+ * ```
+ */
+export function hasOverlappingRanges(ranges) {
+    for (let i = 0; i < ranges.length; i++) {
+        for (let j = i + 1; j < ranges.length; j++) {
+            if (dateRangeOverlap(ranges[i], ranges[j])) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+/**
+ * Merges overlapping or adjacent date ranges
+ * @param ranges - Array of date ranges to merge
+ * @returns Array of merged, non-overlapping ranges
+ *
+ * @example
+ * ```ts
+ * 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') }
+ * ];
+ *
+ * mergeDateRanges(ranges);
+ * // [
+ * //   { start: Date('2024-01-01'), end: Date('2024-01-15') },
+ * //   { start: Date('2024-01-20'), end: Date('2024-01-25') }
+ * // ]
+ * ```
+ */
+export function mergeDateRanges(ranges) {
+    if (ranges.length === 0)
+        return [];
+    // Sort ranges by start date
+    const sorted = [...ranges].sort((a, b) => a.start.getTime() - b.start.getTime());
+    const merged = [{ ...sorted[0] }];
+    for (let i = 1; i < sorted.length; i++) {
+        const current = sorted[i];
+        const lastMerged = merged[merged.length - 1];
+        // Check if current range overlaps or is adjacent to last merged range
+        if (current.start <= lastMerged.end ||
+            current.start.getTime() === lastMerged.end.getTime() + 1) {
+            // Merge by extending the end date if needed
+            if (current.end > lastMerged.end) {
+                lastMerged.end = new Date(current.end);
+            }
+        }
+        else {
+            // No overlap, add as new range
+            merged.push({ ...current });
+        }
+    }
+    return merged;
+}
+/**
+ * Finds gaps between date ranges within specified bounds
+ * @param ranges - Array of date ranges
+ * @param bounds - Optional bounds to search within
+ * @returns Array of date ranges representing gaps
+ *
+ * @example
+ * ```ts
+ * const ranges = [
+ *   { start: new Date('2024-01-01'), end: new Date('2024-01-05') },
+ *   { start: new Date('2024-01-10'), end: new Date('2024-01-15') }
+ * ];
+ *
+ * findGaps(ranges, {
+ *   start: new Date('2024-01-01'),
+ *   end: new Date('2024-01-20')
+ * });
+ * // [
+ * //   { start: Date('2024-01-06'), end: Date('2024-01-09') },
+ * //   { start: Date('2024-01-16'), end: Date('2024-01-20') }
+ * // ]
+ * ```
+ */
+export function findGaps(ranges, bounds) {
+    if (ranges.length === 0) {
+        return bounds ? [{ ...bounds }] : [];
+    }
+    // Merge overlapping ranges first
+    const merged = mergeDateRanges(ranges);
+    // Sort by start date
+    const sorted = merged.sort((a, b) => a.start.getTime() - b.start.getTime());
+    const gaps = [];
+    // Check gap before first range if bounds provided
+    if (bounds && sorted[0].start > bounds.start) {
+        gaps.push({
+            start: new Date(bounds.start),
+            end: addTime(sorted[0].start, -1, 'millisecond')
+        });
+    }
+    // Find gaps between ranges
+    for (let i = 0; i < sorted.length - 1; i++) {
+        const currentEnd = sorted[i].end;
+        const nextStart = sorted[i + 1].start;
+        if (nextStart > currentEnd) {
+            gaps.push({
+                start: addTime(currentEnd, 1, 'day'),
+                end: addTime(nextStart, -1, 'day')
+            });
+        }
+    }
+    // Check gap after last range if bounds provided
+    if (bounds && sorted[sorted.length - 1].end < bounds.end) {
+        gaps.push({
+            start: addTime(sorted[sorted.length - 1].end, 1, 'millisecond'),
+            end: new Date(bounds.end)
+        });
+    }
+    return gaps;
+}
+/**
+ * Splits a date range into smaller chunks
+ * @param range - The date range to split
+ * @param chunkSize - Size of each chunk
+ * @param unit - Unit for chunk size
+ * @returns Array of date ranges
+ *
+ * @example
+ * ```ts
+ * const range = {
+ *   start: new Date('2024-01-01'),
+ *   end: new Date('2024-01-10')
+ * };
+ *
+ * splitRange(range, 3, 'day');
+ * // Returns 4 ranges: 3 days, 3 days, 3 days, 1 day
+ * ```
+ */
+export function splitRange(range, chunkSize, unit) {
+    const chunks = [];
+    let current = new Date(range.start);
+    const rangeEnd = new Date(range.end);
+    // Keep looping while current hasn't passed the end
+    while (current.getTime() <= rangeEnd.getTime()) {
+        const chunkEnd = addTime(current, chunkSize, unit);
+        // Don't go past the range end
+        const effectiveEnd = chunkEnd > rangeEnd ? new Date(rangeEnd) : new Date(chunkEnd);
+        chunks.push({
+            start: new Date(current),
+            end: effectiveEnd
+        });
+        // Move to the next chunk
+        current = chunkEnd;
+        // If the next chunk would start after the range end, we're done
+        if (current.getTime() > rangeEnd.getTime()) {
+            break;
+        }
+    }
+    return chunks;
+}
+/**
+ * Checks if a date falls within a date range
+ * @param range - The date range
+ * @param date - The date to check
+ * @param inclusive - Whether to include boundary dates (default: true)
+ * @returns True if date is within range
+ *
+ * @example
+ * ```ts
+ * const range = {
+ *   start: new Date('2024-01-01'),
+ *   end: new Date('2024-01-31')
+ * };
+ *
+ * containsDate(range, new Date('2024-01-15')); // true
+ * containsDate(range, new Date('2024-02-01')); // false
+ * ```
+ */
+export function containsDate(range, date, inclusive = true) {
+    const checkDate = new Date(date);
+    if (inclusive) {
+        return checkDate >= range.start && checkDate <= range.end;
+    }
+    return checkDate > range.start && checkDate < range.end;
+}
+/**
+ * Gets the intersection of two date ranges
+ * @param range1 - First date range
+ * @param range2 - Second date range
+ * @returns The overlapping range, or null if no overlap
+ *
+ * @example
+ * ```ts
+ * const range1 = { start: new Date('2024-01-01'), end: new Date('2024-01-15') };
+ * const range2 = { start: new Date('2024-01-10'), end: new Date('2024-01-20') };
+ *
+ * getIntersection(range1, range2);
+ * // { start: Date('2024-01-10'), end: Date('2024-01-15') }
+ * ```
+ */
+export function getIntersection(range1, range2) {
+    if (!dateRangeOverlap(range1, range2)) {
+        return null;
+    }
+    return {
+        start: new Date(Math.max(range1.start.getTime(), range2.start.getTime())),
+        end: new Date(Math.min(range1.end.getTime(), range2.end.getTime()))
+    };
+}
+/**
+ * Gets the union (combined coverage) of two date ranges
+ * @param range1 - First date range
+ * @param range2 - Second date range
+ * @returns The combined range covering both inputs
+ *
+ * @example
+ * ```ts
+ * const range1 = { start: new Date('2024-01-01'), end: new Date('2024-01-15') };
+ * const range2 = { start: new Date('2024-01-10'), end: new Date('2024-01-20') };
+ *
+ * getUnion(range1, range2);
+ * // { start: Date('2024-01-01'), end: Date('2024-01-20') }
+ * ```
+ */
+export function getUnion(range1, range2) {
+    return {
+        start: new Date(Math.min(range1.start.getTime(), range2.start.getTime())),
+        end: new Date(Math.max(range1.end.getTime(), range2.end.getTime()))
+    };
+}
+/**
+ * Subtracts one date range from another
+ * @param range - The range to subtract from
+ * @param subtract - The range to subtract
+ * @returns Array of remaining date ranges (0-2 ranges)
+ *
+ * @example
+ * ```ts
+ * const range = { start: new Date('2024-01-01'), end: new Date('2024-01-31') };
+ * const subtract = { start: new Date('2024-01-10'), end: new Date('2024-01-20') };
+ *
+ * subtractRange(range, subtract);
+ * // [
+ * //   { start: Date('2024-01-01'), end: Date('2024-01-09') },
+ * //   { start: Date('2024-01-21'), end: Date('2024-01-31') }
+ * // ]
+ * ```
+ */
+export function subtractRange(range, subtract) {
+    // No overlap, return original range
+    if (!dateRangeOverlap(range, subtract)) {
+        return [{ ...range }];
+    }
+    const result = [];
+    // Check if there's a range before the subtraction
+    if (range.start < subtract.start) {
+        result.push({
+            start: new Date(range.start),
+            end: addTime(subtract.start, -1, 'day')
+        });
+    }
+    // Check if there's a range after the subtraction
+    if (range.end > subtract.end) {
+        result.push({
+            start: addTime(subtract.end, 1, 'day'),
+            end: new Date(range.end)
+        });
+    }
+    return result;
+}
+/**
+ * Calculates the duration of a date range in milliseconds
+ * @param range - The date range
+ * @returns Duration in milliseconds
+ *
+ * @example
+ * ```ts
+ * const range = {
+ *   start: new Date('2024-01-01'),
+ *   end: new Date('2024-01-02')
+ * };
+ *
+ * getRangeDuration(range); // 86400000 (1 day in ms)
+ * ```
+ */
+export function getRangeDuration(range) {
+    return range.end.getTime() - range.start.getTime();
+}
+/**
+ * Expands a date range by a specified amount
+ * @param range - The date range to expand
+ * @param amount - Amount to expand by
+ * @param unit - Unit for expansion
+ * @param options - Expansion options
+ * @returns Expanded date range
+ *
+ * @example
+ * ```ts
+ * const range = {
+ *   start: new Date('2024-01-10'),
+ *   end: new Date('2024-01-20')
+ * };
+ *
+ * expandRange(range, 5, 'day');
+ * // { start: Date('2024-01-05'), end: Date('2024-01-25') }
+ *
+ * expandRange(range, 5, 'day', { direction: 'before' });
+ * // { start: Date('2024-01-05'), end: Date('2024-01-20') }
+ * ```
+ */
+export function expandRange(range, amount, unit, options = {}) {
+    const { direction = 'both' } = options;
+    let newStart = new Date(range.start);
+    let newEnd = new Date(range.end);
+    if (direction === 'both' || direction === 'before') {
+        newStart = addTime(newStart, -amount, unit);
+    }
+    if (direction === 'both' || direction === 'after') {
+        newEnd = addTime(newEnd, amount, unit);
+    }
+    return {
+        start: newStart,
+        end: newEnd
+    };
+}
+/**
+ * Shrinks a date range by a specified amount
+ * @param range - The date range to shrink
+ * @param amount - Amount to shrink by
+ * @param unit - Unit for shrinking
+ * @param options - Shrink options
+ * @returns Shrunk date range, or null if result would be invalid
+ *
+ * @example
+ * ```ts
+ * const range = {
+ *   start: new Date('2024-01-01'),
+ *   end: new Date('2024-01-31')
+ * };
+ *
+ * shrinkRange(range, 5, 'day');
+ * // { start: Date('2024-01-06'), end: Date('2024-01-26') }
+ * ```
+ */
+export function shrinkRange(range, amount, unit, options = {}) {
+    const { direction = 'both' } = options;
+    let newStart = new Date(range.start);
+    let newEnd = new Date(range.end);
+    if (direction === 'both' || direction === 'start') {
+        newStart = addTime(newStart, amount, unit);
+    }
+    if (direction === 'both' || direction === 'end') {
+        newEnd = addTime(newEnd, -amount, unit);
+    }
+    // Check if result is valid
+    if (newStart >= newEnd) {
+        return null;
+    }
+    return {
+        start: newStart,
+        end: newEnd
+    };
+}
+/**
+ * Checks if one date range completely contains another
+ * @param outer - The potentially containing range
+ * @param inner - The potentially contained range
+ * @returns True if outer completely contains inner
+ *
+ * @example
+ * ```ts
+ * const outer = { start: new Date('2024-01-01'), end: new Date('2024-01-31') };
+ * const inner = { start: new Date('2024-01-10'), end: new Date('2024-01-20') };
+ *
+ * rangeContains(outer, inner); // true
+ * ```
+ */
+export function rangeContains(outer, inner) {
+    return outer.start <= inner.start && outer.end >= inner.end;
+}
+/**
+ * Sorts an array of date ranges by start date
+ * @param ranges - Array of date ranges
+ * @param order - Sort order ('asc' or 'desc')
+ * @returns Sorted array of date ranges
+ *
+ * @example
+ * ```ts
+ * const ranges = [
+ *   { start: new Date('2024-01-15'), end: new Date('2024-01-20') },
+ *   { start: new Date('2024-01-01'), end: new Date('2024-01-10') }
+ * ];
+ *
+ * sortRanges(ranges); // Sorted by start date ascending
+ * ```
+ */
+export function sortRanges(ranges, order = 'asc') {
+    const sorted = [...ranges].sort((a, b) => {
+        const diff = a.start.getTime() - b.start.getTime();
+        return order === 'asc' ? diff : -diff;
+    });
+    return sorted;
+}