ts-time-utils 0.0.1

package/dist/esm/calculate.js

@@ -0,0 +1,179 @@
+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';
+/**
+ * Calculate difference between two dates in specified unit
+ * @param date1 - first date
+ * @param date2 - second date
+ * @param unit - unit to return the difference in
+ * @param precise - if true, returns decimal values; if false, returns integers
+ */
+export function differenceInUnits(date1, date2, unit = 'milliseconds', precise = true) {
+    const diffMs = Math.abs(date1.getTime() - date2.getTime());
+    let result;
+    switch (unit) {
+        case 'years':
+            result = diffMs / MILLISECONDS_PER_YEAR;
+            break;
+        case 'months':
+            result = diffMs / MILLISECONDS_PER_MONTH;
+            break;
+        case 'weeks':
+            result = diffMs / MILLISECONDS_PER_WEEK;
+            break;
+        case 'days':
+            result = diffMs / MILLISECONDS_PER_DAY;
+            break;
+        case 'hours':
+            result = diffMs / MILLISECONDS_PER_HOUR;
+            break;
+        case 'minutes':
+            result = diffMs / MILLISECONDS_PER_MINUTE;
+            break;
+        case 'seconds':
+            result = diffMs / MILLISECONDS_PER_SECOND;
+            break;
+        case 'milliseconds':
+        default:
+            result = diffMs;
+            break;
+    }
+    return precise ? result : Math.floor(result);
+}
+/**
+ * Add time to a date
+ * @param date - base date
+ * @param amount - amount to add
+ * @param unit - unit of the amount
+ */
+export function addTime(date, amount, unit) {
+    const result = new Date(date);
+    let milliseconds;
+    switch (unit) {
+        case 'years':
+            milliseconds = amount * MILLISECONDS_PER_YEAR;
+            break;
+        case 'months':
+            milliseconds = amount * MILLISECONDS_PER_MONTH;
+            break;
+        case 'weeks':
+            milliseconds = amount * MILLISECONDS_PER_WEEK;
+            break;
+        case 'days':
+            milliseconds = amount * MILLISECONDS_PER_DAY;
+            break;
+        case 'hours':
+            milliseconds = amount * MILLISECONDS_PER_HOUR;
+            break;
+        case 'minutes':
+            milliseconds = amount * MILLISECONDS_PER_MINUTE;
+            break;
+        case 'seconds':
+            milliseconds = amount * MILLISECONDS_PER_SECOND;
+            break;
+        case 'milliseconds':
+        default:
+            milliseconds = amount;
+            break;
+    }
+    result.setTime(result.getTime() + milliseconds);
+    return result;
+}
+/**
+ * Subtract time from a date
+ * @param date - base date
+ * @param amount - amount to subtract
+ * @param unit - unit of the amount
+ */
+export function subtractTime(date, amount, unit) {
+    return addTime(date, -amount, unit);
+}
+/**
+ * Get the start of a time period for a given date
+ * @param date - input date
+ * @param unit - time unit to get the start of
+ */
+export function startOf(date, unit) {
+    const result = new Date(date);
+    switch (unit) {
+        case 'minute':
+            result.setSeconds(0, 0);
+            break;
+        case 'hour':
+            result.setMinutes(0, 0, 0);
+            break;
+        case 'day':
+            result.setHours(0, 0, 0, 0);
+            break;
+        case 'week':
+            result.setHours(0, 0, 0, 0);
+            result.setDate(result.getDate() - result.getDay());
+            break;
+        case 'month':
+            result.setHours(0, 0, 0, 0);
+            result.setDate(1);
+            break;
+        case 'year':
+            result.setHours(0, 0, 0, 0);
+            result.setMonth(0, 1);
+            break;
+    }
+    return result;
+}
+/**
+ * Get the end of a time period for a given date
+ * @param date - input date
+ * @param unit - time unit to get the end of
+ */
+export function endOf(date, unit) {
+    const result = new Date(date);
+    switch (unit) {
+        case 'minute':
+            result.setSeconds(59, 999);
+            break;
+        case 'hour':
+            result.setMinutes(59, 59, 999);
+            break;
+        case 'day':
+            result.setHours(23, 59, 59, 999);
+            break;
+        case 'week':
+            result.setHours(23, 59, 59, 999);
+            result.setDate(result.getDate() + (6 - result.getDay()));
+            break;
+        case 'month':
+            result.setHours(23, 59, 59, 999);
+            result.setMonth(result.getMonth() + 1, 0);
+            break;
+        case 'year':
+            result.setHours(23, 59, 59, 999);
+            result.setMonth(11, 31);
+            break;
+    }
+    return result;
+}
+/**
+ * Check if a date is between two other dates
+ * @param date - date to check
+ * @param start - start date (inclusive)
+ * @param end - end date (inclusive)
+ */
+export function isBetween(date, start, end) {
+    const time = date.getTime();
+    return time >= start.getTime() && time <= end.getTime();
+}
+/**
+ * Get the number of business days between two dates (excludes weekends)
+ * @param startDate - start date
+ * @param endDate - end date
+ */
+export function businessDaysBetween(startDate, endDate) {
+    let count = 0;
+    const current = new Date(startDate);
+    while (current <= endDate) {
+        const dayOfWeek = current.getDay();
+        if (dayOfWeek !== 0 && dayOfWeek !== 6) { // Not Sunday (0) or Saturday (6)
+            count++;
+        }
+        current.setDate(current.getDate() + 1);
+    }
+    return count;
+}

package/dist/esm/calendar.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Calendar and holiday utilities
+ */
+/**
+ * Get the week number of the year (ISO 8601)
+ * @param date - date to get week number for
+ */
+export declare function getWeekNumber(date: Date): number;
+/**
+ * Get the week of the month (1-6)
+ * @param date - date to get week of month for
+ */
+export declare function getWeekOfMonth(date: Date): number;
+/**
+ * Get the quarter of the year (1-4)
+ * @param date - date to get quarter for
+ */
+export declare function getQuarter(date: Date): number;
+/**
+ * Get the day of the year (1-366)
+ * @param date - date to get day of year for
+ */
+export declare function getDayOfYear(date: Date): number;
+/**
+ * Get the number of weeks in a year
+ * @param year - year to check
+ */
+export declare function getWeeksInYear(year: number): number;
+/**
+ * Get the number of days in a month
+ * @param year - year
+ * @param month - month (0-11)
+ */
+export declare function getDaysInMonth(year: number, month: number): number;
+/**
+ * Get the number of days in a year
+ * @param year - year to check
+ */
+export declare function getDaysInYear(year: number): number;
+/**
+ * Calculate Easter Sunday for a given year (Western/Gregorian calendar)
+ * @param year - year to calculate Easter for
+ */
+export declare function getEaster(year: number): Date;
+/**
+ * Get all months in a year
+ * @param year - year to get months for
+ */
+export declare function getMonthsInYear(year: number): Date[];
+/**
+ * Get all days in a month
+ * @param year - year
+ * @param month - month (0-11)
+ */
+export declare function getDaysInMonthArray(year: number, month: number): Date[];
+/**
+ * Get all weekdays in a month
+ * @param year - year
+ * @param month - month (0-11)
+ */
+export declare function getWeekdaysInMonth(year: number, month: number): Date[];
+/**
+ * Get the first day of the month
+ * @param date - any date in the month
+ */
+export declare function getFirstDayOfMonth(date: Date): Date;
+/**
+ * Get the last day of the month
+ * @param date - any date in the month
+ */
+export declare function getLastDayOfMonth(date: Date): Date;
+/**
+ * Get the first day of the year
+ * @param year - year
+ */
+export declare function getFirstDayOfYear(year: number): Date;
+/**
+ * Get the last day of the year
+ * @param year - year
+ */
+export declare function getLastDayOfYear(year: number): Date;
+//# sourceMappingURL=calendar.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"calendar.d.ts","sourceRoot":"","sources":["../../src/calendar.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;GAGG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,CAMhD;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,CAKjD;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,CAE7C;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,CAI/C;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAYnD;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAElE;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAElD;AAUD;;;GAGG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAkB5C;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,EAAE,CAEpD;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,EAAE,CAGvE;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI,EAAE,CAKtE;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,CAEnD;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,IAAI,GAAG,IAAI,CAElD;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAEpD;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAEnD"}

package/dist/esm/calendar.js

@@ -0,0 +1,154 @@
+/**
+ * Calendar and holiday utilities
+ */
+/**
+ * Get the week number of the year (ISO 8601)
+ * @param date - date to get week number for
+ */
+export function getWeekNumber(date) {
+    const d = new Date(Date.UTC(date.getFullYear(), date.getMonth(), date.getDate()));
+    const dayNum = d.getUTCDay() || 7;
+    d.setUTCDate(d.getUTCDate() + 4 - dayNum);
+    const yearStart = new Date(Date.UTC(d.getUTCFullYear(), 0, 1));
+    return Math.ceil(((d.getTime() - yearStart.getTime()) / 86400000 + 1) / 7);
+}
+/**
+ * Get the week of the month (1-6)
+ * @param date - date to get week of month for
+ */
+export function getWeekOfMonth(date) {
+    const firstDay = new Date(date.getFullYear(), date.getMonth(), 1);
+    const firstWeekday = firstDay.getDay();
+    const offsetDate = date.getDate() + firstWeekday - 1;
+    return Math.floor(offsetDate / 7) + 1;
+}
+/**
+ * Get the quarter of the year (1-4)
+ * @param date - date to get quarter for
+ */
+export function getQuarter(date) {
+    return Math.floor(date.getMonth() / 3) + 1;
+}
+/**
+ * Get the day of the year (1-366)
+ * @param date - date to get day of year for
+ */
+export function getDayOfYear(date) {
+    const start = new Date(date.getFullYear(), 0, 0);
+    const diff = date.getTime() - start.getTime();
+    return Math.floor(diff / (1000 * 60 * 60 * 24));
+}
+/**
+ * Get the number of weeks in a year
+ * @param year - year to check
+ */
+export function getWeeksInYear(year) {
+    const jan1 = new Date(year, 0, 1);
+    const dec31 = new Date(year, 11, 31);
+    // If Jan 1 is Thu-Sun or Dec 31 is Mon-Wed, there are 53 weeks
+    const jan1Day = jan1.getDay();
+    const dec31Day = dec31.getDay();
+    if (jan1Day === 4 || (jan1Day === 3 && dec31Day === 4)) {
+        return 53;
+    }
+    return 52;
+}
+/**
+ * Get the number of days in a month
+ * @param year - year
+ * @param month - month (0-11)
+ */
+export function getDaysInMonth(year, month) {
+    return new Date(year, month + 1, 0).getDate();
+}
+/**
+ * Get the number of days in a year
+ * @param year - year to check
+ */
+export function getDaysInYear(year) {
+    return isLeapYear(year) ? 366 : 365;
+}
+/**
+ * Check if a year is a leap year
+ * @param year - year to check
+ */
+function isLeapYear(year) {
+    return (year % 4 === 0 && year % 100 !== 0) || (year % 400 === 0);
+}
+/**
+ * Calculate Easter Sunday for a given year (Western/Gregorian calendar)
+ * @param year - year to calculate Easter for
+ */
+export function getEaster(year) {
+    // Anonymous Gregorian algorithm
+    const a = year % 19;
+    const b = Math.floor(year / 100);
+    const c = year % 100;
+    const d = Math.floor(b / 4);
+    const e = b % 4;
+    const f = Math.floor((b + 8) / 25);
+    const g = Math.floor((b - f + 1) / 3);
+    const h = (19 * a + b - d - g + 15) % 30;
+    const i = Math.floor(c / 4);
+    const k = c % 4;
+    const l = (32 + 2 * e + 2 * i - h - k) % 7;
+    const m = Math.floor((a + 11 * h + 22 * l) / 451);
+    const month = Math.floor((h + l - 7 * m + 114) / 31);
+    const day = ((h + l - 7 * m + 114) % 31) + 1;
+    return new Date(year, month - 1, day);
+}
+/**
+ * Get all months in a year
+ * @param year - year to get months for
+ */
+export function getMonthsInYear(year) {
+    return Array.from({ length: 12 }, (_, i) => new Date(year, i, 1));
+}
+/**
+ * Get all days in a month
+ * @param year - year
+ * @param month - month (0-11)
+ */
+export function getDaysInMonthArray(year, month) {
+    const daysCount = getDaysInMonth(year, month);
+    return Array.from({ length: daysCount }, (_, i) => new Date(year, month, i + 1));
+}
+/**
+ * Get all weekdays in a month
+ * @param year - year
+ * @param month - month (0-11)
+ */
+export function getWeekdaysInMonth(year, month) {
+    return getDaysInMonthArray(year, month).filter(date => {
+        const day = date.getDay();
+        return day !== 0 && day !== 6; // Not Sunday or Saturday
+    });
+}
+/**
+ * Get the first day of the month
+ * @param date - any date in the month
+ */
+export function getFirstDayOfMonth(date) {
+    return new Date(date.getFullYear(), date.getMonth(), 1);
+}
+/**
+ * Get the last day of the month
+ * @param date - any date in the month
+ */
+export function getLastDayOfMonth(date) {
+    return new Date(date.getFullYear(), date.getMonth() + 1, 0);
+}
+/**
+ * Get the first day of the year
+ * @param year - year
+ */
+export function getFirstDayOfYear(year) {
+    return new Date(year, 0, 1);
+}
+/**
+ * Get the last day of the year
+ * @param year - year
+ */
+export function getLastDayOfYear(year) {
+    return new Date(year, 11, 31);
+}

package/dist/esm/constants.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Time constants for millisecond conversions
+ */
+export declare const MILLISECONDS_PER_SECOND = 1000;
+export declare const MILLISECONDS_PER_MINUTE: number;
+export declare const MILLISECONDS_PER_HOUR: number;
+export declare const MILLISECONDS_PER_DAY: number;
+export declare const MILLISECONDS_PER_WEEK: number;
+export declare const MILLISECONDS_PER_MONTH: number;
+export declare const MILLISECONDS_PER_YEAR: number;
+/**
+ * Second-based constants
+ */
+export declare const SECONDS_PER_MINUTE = 60;
+export declare const SECONDS_PER_HOUR: number;
+export declare const SECONDS_PER_DAY: number;
+export declare const SECONDS_PER_WEEK: number;
+/**
+ * Common time units
+ */
+export type TimeUnit = 'milliseconds' | 'seconds' | 'minutes' | 'hours' | 'days' | 'weeks' | 'months' | 'years';
+/**
+ * Formatting options
+ */
+export interface FormatOptions {
+    /** Include milliseconds in output */
+    includeMs?: boolean;
+    /** Use short format (e.g., "1h" vs "1 hour") */
+    short?: boolean;
+    /** Maximum number of units to show */
+    maxUnits?: number;
+    /** Round to nearest unit instead of floor */
+    round?: boolean;
+}
+//# sourceMappingURL=constants.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../src/constants.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,eAAO,MAAM,uBAAuB,OAAO,CAAC;AAC5C,eAAO,MAAM,uBAAuB,QAA+B,CAAC;AACpE,eAAO,MAAM,qBAAqB,QAA+B,CAAC;AAClE,eAAO,MAAM,oBAAoB,QAA6B,CAAC;AAC/D,eAAO,MAAM,qBAAqB,QAA2B,CAAC;AAC9D,eAAO,MAAM,sBAAsB,QAA4B,CAAC;AAChE,eAAO,MAAM,qBAAqB,QAA6B,CAAC;AAEhE;;GAEG;AACH,eAAO,MAAM,kBAAkB,KAAK,CAAC;AACrC,eAAO,MAAM,gBAAgB,QAA0B,CAAC;AACxD,eAAO,MAAM,eAAe,QAAwB,CAAC;AACrD,eAAO,MAAM,gBAAgB,QAAsB,CAAC;AAEpD;;GAEG;AACH,MAAM,MAAM,QAAQ,GAAG,cAAc,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,GAAG,OAAO,CAAC;AAEhH;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,qCAAqC;IACrC,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,gDAAgD;IAChD,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,sCAAsC;IACtC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,6CAA6C;IAC7C,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB"}

package/dist/esm/constants.js

@@ -0,0 +1,17 @@
+/**
+ * Time constants for millisecond conversions
+ */
+export const MILLISECONDS_PER_SECOND = 1000;
+export const MILLISECONDS_PER_MINUTE = 60 * MILLISECONDS_PER_SECOND;
+export const MILLISECONDS_PER_HOUR = 60 * MILLISECONDS_PER_MINUTE;
+export const MILLISECONDS_PER_DAY = 24 * MILLISECONDS_PER_HOUR;
+export const MILLISECONDS_PER_WEEK = 7 * MILLISECONDS_PER_DAY;
+export const MILLISECONDS_PER_MONTH = 30 * MILLISECONDS_PER_DAY; // Approximate
+export const MILLISECONDS_PER_YEAR = 365 * MILLISECONDS_PER_DAY; // Approximate
+/**
+ * Second-based constants
+ */
+export const SECONDS_PER_MINUTE = 60;
+export const SECONDS_PER_HOUR = 60 * SECONDS_PER_MINUTE;
+export const SECONDS_PER_DAY = 24 * SECONDS_PER_HOUR;
+export const SECONDS_PER_WEEK = 7 * SECONDS_PER_DAY;

package/dist/esm/format.d.ts

@@ -0,0 +1,25 @@
+import { FormatOptions } from './constants.js';
+/**
+ * Convert milliseconds to a human-readable duration.
+ * @param ms - milliseconds
+ * @param options - formatting options
+ */
+export declare function formatDuration(ms: number, options?: FormatOptions): string;
+/**
+ * Return a human-readable "time ago" string.
+ * @param date - past or future date
+ * @param options - formatting options
+ */
+export declare function timeAgo(date: Date, options?: FormatOptions): string;
+/**
+ * Format a date to a human-readable time string
+ * @param date - date to format
+ * @param format - format type
+ */
+export declare function formatTime(date: Date, format?: '12h' | '24h' | 'iso'): string;
+/**
+ * Parse a duration string like "1h 30m" into milliseconds
+ * @param duration - duration string (e.g., "1h 30m", "2d", "45s")
+ */
+export declare function parseDuration(duration: string): number;
+//# sourceMappingURL=format.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../../src/format.ts"],"names":[],"mappings":"AAAA,OAAO,EAQL,aAAa,EACd,MAAM,gBAAgB,CAAC;AAExB;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,GAAE,aAAkB,GAAG,MAAM,CA2E9E;AAED;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,GAAE,aAAkB,GAAG,MAAM,CA+CvE;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,GAAE,KAAK,GAAG,KAAK,GAAG,KAAa,GAAG,MAAM,CAcpF;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAyDtD"}