ts-time-utils 0.0.1

package/dist/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/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/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/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/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/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/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/age.d.ts

@@ -0,0 +1,49 @@
+import { TimeUnit } from './constants.js';
+/**
+ * Age calculation result
+ */
+export interface AgeResult {
+    years: number;
+    months: number;
+    days: number;
+    totalDays: number;
+    totalMonths: number;
+}
+/**
+ * Calculate detailed age from birth date
+ * @param birthDate - date of birth
+ * @param referenceDate - date to calculate age from (defaults to now)
+ */
+export declare function calculateAge(birthDate: Date, referenceDate?: Date): AgeResult;
+/**
+ * Get age in specific units
+ * @param birthDate - date of birth
+ * @param unit - unit to return age in
+ * @param referenceDate - date to calculate from (defaults to now)
+ */
+export declare function getAgeInUnits(birthDate: Date, unit: TimeUnit, referenceDate?: Date): number;
+/**
+ * Determine life stage based on age
+ * @param birthDate - date of birth
+ * @param referenceDate - date to calculate from (defaults to now)
+ */
+export declare function getLifeStage(birthDate: Date, referenceDate?: Date): 'infant' | 'child' | 'teen' | 'adult' | 'senior';
+/**
+ * Get the next birthday date
+ * @param birthDate - date of birth
+ * @param referenceDate - date to calculate from (defaults to now)
+ */
+export declare function getNextBirthday(birthDate: Date, referenceDate?: Date): Date;
+/**
+ * Get days until next birthday
+ * @param birthDate - date of birth
+ * @param referenceDate - date to calculate from (defaults to now)
+ */
+export declare function getDaysUntilBirthday(birthDate: Date, referenceDate?: Date): number;
+/**
+ * Check if today is someone's birthday
+ * @param birthDate - date of birth
+ * @param referenceDate - date to check (defaults to now)
+ */
+export declare function isBirthday(birthDate: Date, referenceDate?: Date): boolean;
+//# sourceMappingURL=age.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"age.d.ts","sourceRoot":"","sources":["../../src/age.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE1C;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,SAAS,EAAE,IAAI,EAAE,aAAa,GAAE,IAAiB,GAAG,SAAS,CAyBzF;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAC3B,SAAS,EAAE,IAAI,EACf,IAAI,EAAE,QAAQ,EACd,aAAa,GAAE,IAAiB,GAC/B,MAAM,CAsBR;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAC1B,SAAS,EAAE,IAAI,EACf,aAAa,GAAE,IAAiB,GAC/B,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,CAQlD;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,SAAS,EAAE,IAAI,EAAE,aAAa,GAAE,IAAiB,GAAG,IAAI,CAYvF;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,IAAI,EAAE,aAAa,GAAE,IAAiB,GAAG,MAAM,CAG9F;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,SAAS,EAAE,IAAI,EAAE,aAAa,GAAE,IAAiB,GAAG,OAAO,CAQrF"}

package/dist/esm/age.js

@@ -0,0 +1,106 @@
+/**
+ * Calculate detailed age from birth date
+ * @param birthDate - date of birth
+ * @param referenceDate - date to calculate age from (defaults to now)
+ */
+export function calculateAge(birthDate, referenceDate = new Date()) {
+    const birth = new Date(birthDate);
+    const reference = new Date(referenceDate);
+    let years = reference.getFullYear() - birth.getFullYear();
+    let months = reference.getMonth() - birth.getMonth();
+    let days = reference.getDate() - birth.getDate();
+    // Adjust for negative days
+    if (days < 0) {
+        months--;
+        const lastMonth = new Date(reference.getFullYear(), reference.getMonth(), 0);
+        days += lastMonth.getDate();
+    }
+    // Adjust for negative months
+    if (months < 0) {
+        years--;
+        months += 12;
+    }
+    const totalDays = Math.floor((reference.getTime() - birth.getTime()) / (1000 * 60 * 60 * 24));
+    const totalMonths = years * 12 + months;
+    return { years, months, days, totalDays, totalMonths };
+}
+/**
+ * Get age in specific units
+ * @param birthDate - date of birth
+ * @param unit - unit to return age in
+ * @param referenceDate - date to calculate from (defaults to now)
+ */
+export function getAgeInUnits(birthDate, unit, referenceDate = new Date()) {
+    const diffMs = referenceDate.getTime() - birthDate.getTime();
+    switch (unit) {
+        case 'years':
+            return Math.floor(diffMs / (1000 * 60 * 60 * 24 * 365.25));
+        case 'months':
+            return Math.floor(diffMs / (1000 * 60 * 60 * 24 * 30.44));
+        case 'weeks':
+            return Math.floor(diffMs / (1000 * 60 * 60 * 24 * 7));
+        case 'days':
+            return Math.floor(diffMs / (1000 * 60 * 60 * 24));
+        case 'hours':
+            return Math.floor(diffMs / (1000 * 60 * 60));
+        case 'minutes':
+            return Math.floor(diffMs / (1000 * 60));
+        case 'seconds':
+            return Math.floor(diffMs / 1000);
+        case 'milliseconds':
+        default:
+            return diffMs;
+    }
+}
+/**
+ * Determine life stage based on age
+ * @param birthDate - date of birth
+ * @param referenceDate - date to calculate from (defaults to now)
+ */
+export function getLifeStage(birthDate, referenceDate = new Date()) {
+    const ageInYears = getAgeInUnits(birthDate, 'years', referenceDate);
+    if (ageInYears < 2)
+        return 'infant';
+    if (ageInYears < 13)
+        return 'child';
+    if (ageInYears < 18)
+        return 'teen';
+    if (ageInYears < 65)
+        return 'adult';
+    return 'senior';
+}
+/**
+ * Get the next birthday date
+ * @param birthDate - date of birth
+ * @param referenceDate - date to calculate from (defaults to now)
+ */
+export function getNextBirthday(birthDate, referenceDate = new Date()) {
+    const birth = new Date(birthDate);
+    const reference = new Date(referenceDate);
+    const nextBirthday = new Date(reference.getFullYear(), birth.getMonth(), birth.getDate());
+    // If birthday has passed this year, get next year's birthday
+    if (nextBirthday <= reference) {
+        nextBirthday.setFullYear(reference.getFullYear() + 1);
+    }
+    return nextBirthday;
+}
+/**
+ * Get days until next birthday
+ * @param birthDate - date of birth
+ * @param referenceDate - date to calculate from (defaults to now)
+ */
+export function getDaysUntilBirthday(birthDate, referenceDate = new Date()) {
+    const nextBirthday = getNextBirthday(birthDate, referenceDate);
+    return Math.ceil((nextBirthday.getTime() - referenceDate.getTime()) / (1000 * 60 * 60 * 24));
+}
+/**
+ * Check if today is someone's birthday
+ * @param birthDate - date of birth
+ * @param referenceDate - date to check (defaults to now)
+ */
+export function isBirthday(birthDate, referenceDate = new Date()) {
+    const birth = new Date(birthDate);
+    const reference = new Date(referenceDate);
+    return (birth.getMonth() === reference.getMonth() &&
+        birth.getDate() === reference.getDate());
+}

package/dist/esm/calculate.d.ts

@@ -0,0 +1,49 @@
+import { TimeUnit } 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 declare function differenceInUnits(date1: Date, date2: Date, unit?: TimeUnit, precise?: boolean): number;
+/**
+ * Add time to a date
+ * @param date - base date
+ * @param amount - amount to add
+ * @param unit - unit of the amount
+ */
+export declare function addTime(date: Date, amount: number, unit: TimeUnit): Date;
+/**
+ * Subtract time from a date
+ * @param date - base date
+ * @param amount - amount to subtract
+ * @param unit - unit of the amount
+ */
+export declare function subtractTime(date: Date, amount: number, unit: TimeUnit): Date;
+/**
+ * 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 declare function startOf(date: Date, unit: 'day' | 'week' | 'month' | 'year' | 'hour' | 'minute'): Date;
+/**
+ * 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 declare function endOf(date: Date, unit: 'day' | 'week' | 'month' | 'year' | 'hour' | 'minute'): Date;
+/**
+ * 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 declare function isBetween(date: Date, start: Date, end: Date): boolean;
+/**
+ * Get the number of business days between two dates (excludes weekends)
+ * @param startDate - start date
+ * @param endDate - end date
+ */
+export declare function businessDaysBetween(startDate: Date, endDate: Date): number;
+//# sourceMappingURL=calculate.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"calculate.d.ts","sourceRoot":"","sources":["../../src/calculate.ts"],"names":[],"mappings":"AAAA,OAAO,EAQL,QAAQ,EACT,MAAM,gBAAgB,CAAC;AAExB;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,IAAI,EACX,KAAK,EAAE,IAAI,EACX,IAAI,GAAE,QAAyB,EAC/B,OAAO,GAAE,OAAc,GACtB,MAAM,CAkCR;AAED;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,GAAG,IAAI,CAmCxE;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,GAAG,IAAI,CAE7E;AAED;;;;GAIG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,QAAQ,GAAG,IAAI,CA4BrG;AAED;;;;GAIG;AACH,wBAAgB,KAAK,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,QAAQ,GAAG,IAAI,CA4BnG;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,GAAG,OAAO,CAGrE;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,GAAG,MAAM,CAa1E"}