ts-time-utils 1.0.0 → 1.1.0

package/dist/countdown.js

@@ -0,0 +1,298 @@
+/**
+ * @fileoverview Countdown and timer utilities for tracking time until/since a target date
+ * Provides countdown timers, remaining time calculations, and progress tracking
+ */
+/**
+ * Creates a countdown timer to a target date
+ * @param targetDate - The date to count down to
+ * @param options - Countdown options and callbacks
+ * @returns A countdown instance with control methods
+ *
+ * @example
+ * ```ts
+ * const countdown = createCountdown(
+ *   new Date('2024-12-31T23:59:59'),
+ *   {
+ *     onTick: (remaining) => {
+ *       console.log(`${remaining.days}d ${remaining.hours}h ${remaining.minutes}m ${remaining.seconds}s`);
+ *     },
+ *     onComplete: () => {
+ *       console.log('Happy New Year!');
+ *     }
+ *   }
+ * );
+ *
+ * countdown.start();
+ * // Later...
+ * countdown.stop();
+ * ```
+ */
+export function createCountdown(targetDate, options = {}) {
+    let target = new Date(targetDate);
+    let intervalId = null;
+    let running = false;
+    const { onTick, onComplete, onExpired, interval = 1000, immediate = true } = options;
+    const getRemaining = () => {
+        return getRemainingTime(target);
+    };
+    const tick = () => {
+        const remaining = getRemaining();
+        if (onTick) {
+            onTick(remaining);
+        }
+        if (remaining.isExpired) {
+            stop();
+            if (onComplete) {
+                onComplete();
+            }
+        }
+    };
+    const start = () => {
+        if (running)
+            return;
+        const remaining = getRemaining();
+        if (remaining.totalMilliseconds < 0) {
+            if (onExpired) {
+                onExpired();
+            }
+            return;
+        }
+        running = true;
+        if (immediate) {
+            tick();
+        }
+        intervalId = setInterval(tick, interval);
+    };
+    const stop = () => {
+        if (!running)
+            return;
+        running = false;
+        if (intervalId !== null) {
+            clearInterval(intervalId);
+            intervalId = null;
+        }
+    };
+    const reset = (newTarget) => {
+        stop();
+        target = new Date(newTarget);
+    };
+    const isRunning = () => running;
+    const isExpiredCheck = () => {
+        return getRemaining().isExpired;
+    };
+    return {
+        start,
+        stop,
+        reset,
+        getRemaining,
+        isRunning,
+        isExpired: isExpiredCheck
+    };
+}
+/**
+ * Gets the remaining time until/since a target date
+ * @param targetDate - The target date
+ * @param fromDate - The date to calculate from (defaults to now)
+ * @returns Object with remaining time broken down by units
+ *
+ * @example
+ * ```ts
+ * const remaining = getRemainingTime(new Date('2024-12-31'));
+ * console.log(`${remaining.days} days, ${remaining.hours} hours remaining`);
+ *
+ * // Check if expired
+ * if (remaining.isExpired) {
+ *   console.log('Target date has passed');
+ * }
+ * ```
+ */
+export function getRemainingTime(targetDate, fromDate = new Date()) {
+    const target = new Date(targetDate);
+    const from = new Date(fromDate);
+    const totalMilliseconds = target.getTime() - from.getTime();
+    const isExpired = totalMilliseconds <= 0;
+    // Use absolute values for calculations
+    const absTotalMs = Math.abs(totalMilliseconds);
+    const totalSeconds = Math.floor(absTotalMs / 1000);
+    const totalMinutes = Math.floor(totalSeconds / 60);
+    const totalHours = Math.floor(totalMinutes / 60);
+    const totalDays = Math.floor(totalHours / 24);
+    const milliseconds = Math.floor(absTotalMs % 1000);
+    const seconds = totalSeconds % 60;
+    const minutes = totalMinutes % 60;
+    const hours = totalHours % 24;
+    const days = totalDays; // Don't mod by 7 - let the formatter decide
+    const weeks = Math.floor(totalDays / 7);
+    return {
+        totalMilliseconds,
+        totalSeconds: totalMilliseconds >= 0 ? totalSeconds : -totalSeconds,
+        totalMinutes: totalMilliseconds >= 0 ? totalMinutes : -totalMinutes,
+        totalHours: totalMilliseconds >= 0 ? totalHours : -totalHours,
+        totalDays: totalMilliseconds >= 0 ? totalDays : -totalDays,
+        milliseconds,
+        seconds,
+        minutes,
+        hours,
+        days,
+        weeks,
+        isExpired
+    };
+}
+/**
+ * Formats the remaining time as a human-readable string
+ * @param targetDate - The target date
+ * @param options - Formatting options
+ * @returns Formatted countdown string
+ *
+ * @example
+ * ```ts
+ * formatCountdown(new Date('2024-12-31'));
+ * // "45d 12h 30m 15s"
+ *
+ * formatCountdown(new Date('2024-12-31'), { units: ['days', 'hours'] });
+ * // "45 days, 12 hours"
+ *
+ * formatCountdown(new Date('2024-12-31'), { short: false });
+ * // "45 days 12 hours 30 minutes 15 seconds"
+ * ```
+ */
+export function formatCountdown(targetDate, options = {}) {
+    const { from, units = ['days', 'hours', 'minutes', 'seconds'], short = true, maxUnits, showZero = false, separator = ' ' } = options;
+    const remaining = getRemainingTime(targetDate, from);
+    if (remaining.isExpired) {
+        return 'Expired';
+    }
+    const parts = [];
+    for (const unit of units) {
+        const value = remaining[unit];
+        if (value === 0 && !showZero && parts.length === 0) {
+            continue;
+        }
+        if (value === 0 && !showZero) {
+            continue;
+        }
+        if (maxUnits && parts.length >= maxUnits) {
+            break;
+        }
+        if (short) {
+            const shortUnit = unit[0];
+            parts.push(`${value}${shortUnit}`);
+        }
+        else {
+            const unitName = value === 1 ? unit.slice(0, -1) : unit;
+            parts.push(`${value} ${unitName}`);
+        }
+    }
+    return parts.length > 0 ? parts.join(separator) : '0s';
+}
+/**
+ * Checks if a date has expired (is in the past)
+ * @param date - The date to check
+ * @param fromDate - The reference date (defaults to now)
+ * @returns True if the date is in the past
+ *
+ * @example
+ * ```ts
+ * isExpired(new Date('2020-01-01')); // true
+ * isExpired(new Date('2030-01-01')); // false
+ * ```
+ */
+export function isExpired(date, fromDate = new Date()) {
+    const checkDate = new Date(date);
+    const from = new Date(fromDate);
+    return checkDate.getTime() < from.getTime();
+}
+/**
+ * Calculates the progress percentage between two dates
+ * @param startDate - The start date
+ * @param endDate - The end date
+ * @param currentDate - The current date (defaults to now)
+ * @returns Progress percentage (0-100), clamped to range
+ *
+ * @example
+ * ```ts
+ * const progress = getProgressPercentage(
+ *   new Date('2024-01-01'),
+ *   new Date('2024-12-31'),
+ *   new Date('2024-07-01')
+ * );
+ * console.log(`${progress}% complete`); // ~50% complete
+ * ```
+ */
+export function getProgressPercentage(startDate, endDate, currentDate = new Date()) {
+    const start = new Date(startDate).getTime();
+    const end = new Date(endDate).getTime();
+    const current = new Date(currentDate).getTime();
+    if (start >= end) {
+        throw new Error('Start date must be before end date');
+    }
+    const total = end - start;
+    const elapsed = current - start;
+    const percentage = (elapsed / total) * 100;
+    // Clamp between 0 and 100
+    return Math.max(0, Math.min(100, percentage));
+}
+/**
+ * Gets time until a target date in a specific unit
+ * @param targetDate - The target date
+ * @param unit - The unit to return
+ * @param fromDate - The date to calculate from (defaults to now)
+ * @returns Time remaining in the specified unit
+ *
+ * @example
+ * ```ts
+ * getTimeUntil(new Date('2024-12-31'), 'days'); // 45.5
+ * getTimeUntil(new Date('2024-12-31'), 'hours'); // 1092
+ * getTimeUntil(new Date('2024-12-31'), 'weeks'); // 6.5
+ * ```
+ */
+export function getTimeUntil(targetDate, unit, fromDate = new Date()) {
+    const remaining = getRemainingTime(targetDate, fromDate);
+    switch (unit) {
+        case 'milliseconds':
+            return remaining.totalMilliseconds;
+        case 'seconds':
+            return remaining.totalSeconds;
+        case 'minutes':
+            return remaining.totalMinutes;
+        case 'hours':
+            return remaining.totalHours;
+        case 'days':
+            return remaining.totalDays;
+        case 'weeks':
+            return remaining.totalDays / 7;
+        default:
+            return remaining.totalMilliseconds;
+    }
+}
+/**
+ * Creates a deadline object with useful methods
+ * @param targetDate - The deadline date
+ * @returns An object with deadline-related methods
+ *
+ * @example
+ * ```ts
+ * const deadline = createDeadline(new Date('2024-12-31'));
+ *
+ * deadline.isExpired(); // false
+ * deadline.daysRemaining(); // 45
+ * deadline.hoursRemaining(); // 1092
+ * deadline.formatRemaining(); // "45d 12h 30m"
+ * deadline.progressFrom(new Date('2024-01-01')); // 67.5%
+ * ```
+ */
+export function createDeadline(targetDate) {
+    const target = new Date(targetDate);
+    return {
+        target,
+        isExpired: () => isExpired(target),
+        getRemaining: () => getRemainingTime(target),
+        daysRemaining: () => getTimeUntil(target, 'days'),
+        hoursRemaining: () => getTimeUntil(target, 'hours'),
+        minutesRemaining: () => getTimeUntil(target, 'minutes'),
+        secondsRemaining: () => getTimeUntil(target, 'seconds'),
+        formatRemaining: (options) => formatCountdown(target, options),
+        progressFrom: (startDate) => getProgressPercentage(startDate, target),
+        countdown: (options) => createCountdown(target, options)
+    };
+}

package/dist/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/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"}