ts-time-utils 1.1.0 → 3.0.0

package/dist/calculate.d.ts

@@ -37,9 +37,14 @@ export declare function endOf(date: Date, unit: 'day' | 'week' | 'month' | 'year
  * Check if a date is between two other dates
  * @param date - date to check
  * @param start - start date (inclusive)
- * @param end - end date (inclusive)
+/**
+ * Check if a date falls between two dates
+ * @param date - date to check
+ * @param start - start date
+ * @param end - end date
+ * @param inclusive - whether boundaries are inclusive (default: true)
  */
-export declare function isBetween(date: Date, start: Date, end: Date): boolean;
+export declare function isBetween(date: Date, start: Date, end: Date, inclusive?: boolean): boolean;
 /**
  * Get the number of business days between two dates (excludes weekends)
  * @param startDate - start date

package/dist/calculate.d.ts.map

@@ -1 +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,CAgDxE;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"}
+{"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,CAgDxE;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;;;;;;;;;;GAUG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,SAAS,GAAE,OAAc,GAAG,OAAO,CAShG;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,SAAS,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,GAAG,MAAM,CAa1E"}

package/dist/calculate.js

@@ -168,11 +168,21 @@ export function endOf(date, unit) {
  * Check if a date is between two other dates
  * @param date - date to check
  * @param start - start date (inclusive)
- * @param end - end date (inclusive)
+/**
+ * Check if a date falls between two dates
+ * @param date - date to check
+ * @param start - start date
+ * @param end - end date
+ * @param inclusive - whether boundaries are inclusive (default: true)
  */
-export function isBetween(date, start, end) {
+export function isBetween(date, start, end, inclusive = true) {
     const time = date.getTime();
-    return time >= start.getTime() && time <= end.getTime();
+    const startTime = start.getTime();
+    const endTime = end.getTime();
+    if (inclusive) {
+        return time >= startTime && time <= endTime;
+    }
+    return time > startTime && time < endTime;
 }
 /**
  * Get the number of business days between two dates (excludes weekends)

package/dist/calendar.d.ts

@@ -79,4 +79,107 @@ export declare function getFirstDayOfYear(year: number): Date;
  * @param year - year
  */
 export declare function getLastDayOfYear(year: number): Date;
+/**
+ * Get the nth occurrence of a day in a month (e.g., 2nd Monday)
+ * @param year - year
+ * @param month - month (0-11)
+ * @param dayOfWeek - day of week (0=Sunday, 6=Saturday)
+ * @param n - occurrence (1-5, or -1 for last)
+ */
+export declare function getNthDayOfMonth(year: number, month: number, dayOfWeek: number, n: number): Date | null;
+/**
+ * US Holiday type
+ */
+export interface USHoliday {
+    name: string;
+    date: Date;
+    type: 'federal' | 'observance';
+}
+/**
+ * Get New Year's Day
+ * @param year - year
+ */
+export declare function getNewYearsDay(year: number): Date;
+/**
+ * Get Martin Luther King Jr. Day (3rd Monday of January)
+ * @param year - year
+ */
+export declare function getMLKDay(year: number): Date | null;
+/**
+ * Get Presidents' Day (3rd Monday of February)
+ * @param year - year
+ */
+export declare function getPresidentsDay(year: number): Date | null;
+/**
+ * Get Memorial Day (last Monday of May)
+ * @param year - year
+ */
+export declare function getMemorialDay(year: number): Date | null;
+/**
+ * Get Independence Day (July 4th)
+ * @param year - year
+ */
+export declare function getIndependenceDay(year: number): Date;
+/**
+ * Get Labor Day (1st Monday of September)
+ * @param year - year
+ */
+export declare function getLaborDay(year: number): Date | null;
+/**
+ * Get Columbus Day (2nd Monday of October)
+ * @param year - year
+ */
+export declare function getColumbusDay(year: number): Date | null;
+/**
+ * Get Veterans Day (November 11th)
+ * @param year - year
+ */
+export declare function getVeteransDay(year: number): Date;
+/**
+ * Get Thanksgiving Day (4th Thursday of November)
+ * @param year - year
+ */
+export declare function getThanksgivingDay(year: number): Date | null;
+/**
+ * Get Christmas Day (December 25th)
+ * @param year - year
+ */
+export declare function getChristmasDay(year: number): Date;
+/**
+ * Get Good Friday (Friday before Easter)
+ * @param year - year
+ */
+export declare function getGoodFriday(year: number): Date;
+/**
+ * Get all US federal holidays for a year
+ * @param year - year
+ */
+export declare function getUSHolidays(year: number): USHoliday[];
+/**
+ * Check if a date is a US federal holiday
+ * @param date - date to check
+ */
+export declare function isUSHoliday(date: Date): boolean;
+/**
+ * Get the name of a US holiday for a given date
+ * @param date - date to check
+ * @returns holiday name or null if not a holiday
+ */
+export declare function getUSHolidayName(date: Date): string | null;
+/**
+ * Get the start of the week for a date (Monday)
+ * @param date - any date
+ */
+export declare function getStartOfWeek(date: Date): Date;
+/**
+ * Get the end of the week for a date (Sunday)
+ * @param date - any date
+ */
+export declare function getEndOfWeek(date: Date): Date;
+/**
+ * Get all weeks in a month as arrays of dates
+ * @param year - year
+ * @param month - month (0-11)
+ */
+export declare function getWeeksInMonth(year: number, month: number): Date[][];
 //# sourceMappingURL=calendar.d.ts.map

package/dist/calendar.d.ts.map

@@ -1 +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"}
+{"version":3,"file":"calendar.d.ts","sourceRoot":"","sources":["../src/calendar.ts"],"names":[],"mappings":"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"}

package/dist/calendar.js

@@ -152,3 +152,227 @@ export function getFirstDayOfYear(year) {
 export function getLastDayOfYear(year) {
     return new Date(year, 11, 31);
 }
+/**
+ * Get the nth occurrence of a day in a month (e.g., 2nd Monday)
+ * @param year - year
+ * @param month - month (0-11)
+ * @param dayOfWeek - day of week (0=Sunday, 6=Saturday)
+ * @param n - occurrence (1-5, or -1 for last)
+ */
+export function getNthDayOfMonth(year, month, dayOfWeek, n) {
+    if (n === 0 || n < -1 || n > 5)
+        return null;
+    const firstDay = new Date(year, month, 1);
+    const lastDay = new Date(year, month + 1, 0);
+    if (n === -1) {
+        // Last occurrence
+        let date = lastDay.getDate();
+        while (date > 0) {
+            const d = new Date(year, month, date);
+            if (d.getDay() === dayOfWeek)
+                return d;
+            date--;
+        }
+        return null;
+    }
+    // Find nth occurrence
+    let count = 0;
+    for (let date = 1; date <= lastDay.getDate(); date++) {
+        const d = new Date(year, month, date);
+        if (d.getDay() === dayOfWeek) {
+            count++;
+            if (count === n)
+                return d;
+        }
+    }
+    return null;
+}
+/**
+ * Get New Year's Day
+ * @param year - year
+ */
+export function getNewYearsDay(year) {
+    return new Date(year, 0, 1);
+}
+/**
+ * Get Martin Luther King Jr. Day (3rd Monday of January)
+ * @param year - year
+ */
+export function getMLKDay(year) {
+    return getNthDayOfMonth(year, 0, 1, 3);
+}
+/**
+ * Get Presidents' Day (3rd Monday of February)
+ * @param year - year
+ */
+export function getPresidentsDay(year) {
+    return getNthDayOfMonth(year, 1, 1, 3);
+}
+/**
+ * Get Memorial Day (last Monday of May)
+ * @param year - year
+ */
+export function getMemorialDay(year) {
+    return getNthDayOfMonth(year, 4, 1, -1);
+}
+/**
+ * Get Independence Day (July 4th)
+ * @param year - year
+ */
+export function getIndependenceDay(year) {
+    return new Date(year, 6, 4);
+}
+/**
+ * Get Labor Day (1st Monday of September)
+ * @param year - year
+ */
+export function getLaborDay(year) {
+    return getNthDayOfMonth(year, 8, 1, 1);
+}
+/**
+ * Get Columbus Day (2nd Monday of October)
+ * @param year - year
+ */
+export function getColumbusDay(year) {
+    return getNthDayOfMonth(year, 9, 1, 2);
+}
+/**
+ * Get Veterans Day (November 11th)
+ * @param year - year
+ */
+export function getVeteransDay(year) {
+    return new Date(year, 10, 11);
+}
+/**
+ * Get Thanksgiving Day (4th Thursday of November)
+ * @param year - year
+ */
+export function getThanksgivingDay(year) {
+    return getNthDayOfMonth(year, 10, 4, 4);
+}
+/**
+ * Get Christmas Day (December 25th)
+ * @param year - year
+ */
+export function getChristmasDay(year) {
+    return new Date(year, 11, 25);
+}
+/**
+ * Get Good Friday (Friday before Easter)
+ * @param year - year
+ */
+export function getGoodFriday(year) {
+    const easter = getEaster(year);
+    const goodFriday = new Date(easter);
+    goodFriday.setDate(easter.getDate() - 2);
+    return goodFriday;
+}
+/**
+ * Get all US federal holidays for a year
+ * @param year - year
+ */
+export function getUSHolidays(year) {
+    const holidays = [];
+    holidays.push({ name: "New Year's Day", date: getNewYearsDay(year), type: 'federal' });
+    const mlk = getMLKDay(year);
+    if (mlk)
+        holidays.push({ name: "Martin Luther King Jr. Day", date: mlk, type: 'federal' });
+    const presidents = getPresidentsDay(year);
+    if (presidents)
+        holidays.push({ name: "Presidents' Day", date: presidents, type: 'federal' });
+    const memorial = getMemorialDay(year);
+    if (memorial)
+        holidays.push({ name: "Memorial Day", date: memorial, type: 'federal' });
+    holidays.push({ name: "Independence Day", date: getIndependenceDay(year), type: 'federal' });
+    const labor = getLaborDay(year);
+    if (labor)
+        holidays.push({ name: "Labor Day", date: labor, type: 'federal' });
+    const columbus = getColumbusDay(year);
+    if (columbus)
+        holidays.push({ name: "Columbus Day", date: columbus, type: 'federal' });
+    holidays.push({ name: "Veterans Day", date: getVeteransDay(year), type: 'federal' });
+    const thanksgiving = getThanksgivingDay(year);
+    if (thanksgiving)
+        holidays.push({ name: "Thanksgiving Day", date: thanksgiving, type: 'federal' });
+    holidays.push({ name: "Christmas Day", date: getChristmasDay(year), type: 'federal' });
+    return holidays.sort((a, b) => a.date.getTime() - b.date.getTime());
+}
+/**
+ * Check if a date is a US federal holiday
+ * @param date - date to check
+ */
+export function isUSHoliday(date) {
+    const holidays = getUSHolidays(date.getFullYear());
+    return holidays.some(h => h.date.getFullYear() === date.getFullYear() &&
+        h.date.getMonth() === date.getMonth() &&
+        h.date.getDate() === date.getDate());
+}
+/**
+ * Get the name of a US holiday for a given date
+ * @param date - date to check
+ * @returns holiday name or null if not a holiday
+ */
+export function getUSHolidayName(date) {
+    const holidays = getUSHolidays(date.getFullYear());
+    const holiday = holidays.find(h => h.date.getFullYear() === date.getFullYear() &&
+        h.date.getMonth() === date.getMonth() &&
+        h.date.getDate() === date.getDate());
+    return holiday ? holiday.name : null;
+}
+/**
+ * Get the start of the week for a date (Monday)
+ * @param date - any date
+ */
+export function getStartOfWeek(date) {
+    const d = new Date(date);
+    const day = d.getDay();
+    const diff = d.getDate() - day + (day === 0 ? -6 : 1); // Adjust for Monday start
+    d.setDate(diff);
+    d.setHours(0, 0, 0, 0);
+    return d;
+}
+/**
+ * Get the end of the week for a date (Sunday)
+ * @param date - any date
+ */
+export function getEndOfWeek(date) {
+    const start = getStartOfWeek(date);
+    const end = new Date(start);
+    end.setDate(start.getDate() + 6);
+    end.setHours(23, 59, 59, 999);
+    return end;
+}
+/**
+ * Get all weeks in a month as arrays of dates
+ * @param year - year
+ * @param month - month (0-11)
+ */
+export function getWeeksInMonth(year, month) {
+    const weeks = [];
+    const firstDay = new Date(year, month, 1);
+    const lastDay = new Date(year, month + 1, 0);
+    let currentWeek = [];
+    const startDayOfWeek = firstDay.getDay() || 7; // Convert Sunday from 0 to 7 for ISO
+    // Add days from previous month to fill the first week
+    for (let i = 1; i < startDayOfWeek; i++) {
+        const prevDate = new Date(year, month, 1 - (startDayOfWeek - i));
+        currentWeek.push(prevDate);
+    }
+    // Add days of the current month
+    for (let day = 1; day <= lastDay.getDate(); day++) {
+        currentWeek.push(new Date(year, month, day));
+        if (currentWeek.length === 7) {
+            weeks.push(currentWeek);
+            currentWeek = [];
+        }
+    }
+    // Add days from next month to fill the last week
+    if (currentWeek.length > 0) {
+        let nextDay = 1;
+        while (currentWeek.length < 7) {
+            currentWeek.push(new Date(year, month + 1, nextDay++));
+        }
+        weeks.push(currentWeek);
+    }
+    return weeks;
+}

package/dist/chain.d.ts

@@ -0,0 +1,269 @@
+/**
+ * Fluent chain API for ts-time-utils
+ *
+ * Provides a chainable interface for date operations:
+ * ```ts
+ * chain(new Date())
+ *   .add(1, 'day')
+ *   .startOf('month')
+ *   .format('YYYY-MM-DD')
+ * ```
+ */
+import type { TimeUnit, DateInput, FormatOptions } from './types.js';
+/** Units accepted by startOf/endOf */
+type StartOfUnit = 'day' | 'week' | 'month' | 'year' | 'hour' | 'minute';
+/**
+ * Immutable chainable date wrapper
+ * All transformation methods return a new ChainedDate instance
+ */
+export declare class ChainedDate {
+    private readonly _date;
+    constructor(date?: DateInput);
+    /**
+     * Add time to the date
+     * @example chain(date).add(1, 'day').add(2, 'hours')
+     */
+    add(amount: number, unit: TimeUnit): ChainedDate;
+    /**
+     * Subtract time from the date
+     * @example chain(date).subtract(1, 'week')
+     */
+    subtract(amount: number, unit: TimeUnit): ChainedDate;
+    /**
+     * Get the start of a time period
+     * @example chain(date).startOf('month')
+     */
+    startOf(unit: StartOfUnit): ChainedDate;
+    /**
+     * Get the end of a time period
+     * @example chain(date).endOf('day')
+     */
+    endOf(unit: StartOfUnit): ChainedDate;
+    /**
+     * Set specific date/time components
+     * @example chain(date).set({ year: 2025, month: 1 })
+     */
+    set(values: {
+        year?: number;
+        month?: number;
+        day?: number;
+        hours?: number;
+        minutes?: number;
+        seconds?: number;
+        milliseconds?: number;
+    }): ChainedDate;
+    /**
+     * Clone the ChainedDate
+     */
+    clone(): ChainedDate;
+    /**
+     * Format date using pattern string
+     * @example chain(date).format('YYYY-MM-DD') // "2025-01-15"
+     */
+    format(pattern: string): string;
+    /**
+     * Format time in 12h, 24h, or ISO format
+     * @example chain(date).formatTime('12h') // "2:30 PM"
+     */
+    formatTime(fmt?: '12h' | '24h' | 'iso'): string;
+    /**
+     * Format as calendar date (Today, Yesterday, Monday, etc.)
+     * @example chain(date).calendar() // "Tomorrow"
+     */
+    calendar(): string;
+    /**
+     * Get relative time string
+     * @example chain(pastDate).ago() // "3 hours ago"
+     */
+    ago(options?: FormatOptions): string;
+    /**
+     * Get ISO string
+     */
+    toISOString(): string;
+    /**
+     * Get locale string
+     */
+    toLocaleString(locale?: string, options?: Intl.DateTimeFormatOptions): string;
+    /**
+     * Format day as ordinal
+     * @example chain(date).dayOrdinal() // "15th"
+     */
+    dayOrdinal(): string;
+    /**
+     * Check if date is valid
+     */
+    isValid(): boolean;
+    /**
+     * Check if date is today
+     */
+    isToday(): boolean;
+    /**
+     * Check if date is yesterday
+     */
+    isYesterday(): boolean;
+    /**
+     * Check if date is tomorrow
+     */
+    isTomorrow(): boolean;
+    /**
+     * Check if date is in the past
+     */
+    isPast(): boolean;
+    /**
+     * Check if date is in the future
+     */
+    isFuture(): boolean;
+    /**
+     * Check if date is a weekend
+     */
+    isWeekend(): boolean;
+    /**
+     * Check if date is a weekday
+     */
+    isWeekday(): boolean;
+    /**
+     * Check if date is in this week
+     */
+    isThisWeek(): boolean;
+    /**
+     * Check if date is in this month
+     */
+    isThisMonth(): boolean;
+    /**
+     * Check if date is in this year
+     */
+    isThisYear(): boolean;
+    /**
+     * Check if year is a leap year
+     */
+    isLeapYear(): boolean;
+    /**
+     * Check if date is a business day
+     */
+    isBusinessDay(holidays?: Date[]): boolean;
+    /**
+     * Check if date is same day as another
+     */
+    isSameDay(other: DateInput): boolean;
+    /**
+     * Check if date is same week as another
+     */
+    isSameWeek(other: DateInput): boolean;
+    /**
+     * Check if date is same month as another
+     */
+    isSameMonth(other: DateInput): boolean;
+    /**
+     * Check if date is same year as another
+     */
+    isSameYear(other: DateInput): boolean;
+    /**
+     * Check if date is before another
+     */
+    isBefore(other: DateInput): boolean;
+    /**
+     * Check if date is after another
+     */
+    isAfter(other: DateInput): boolean;
+    /**
+     * Check if date is between two dates
+     */
+    isBetween(start: DateInput, end: DateInput, inclusive?: boolean): boolean;
+    /**
+     * Get difference from another date
+     * @example chain(date).diff(other, 'days') // 5
+     */
+    diff(other: DateInput, unit?: TimeUnit, precise?: boolean): number;
+    /**
+     * Get the timestamp (milliseconds since epoch)
+     */
+    valueOf(): number;
+    /**
+     * Get year
+     */
+    year(): number;
+    /**
+     * Get month (1-12)
+     */
+    month(): number;
+    /**
+     * Get day of month (1-31)
+     */
+    day(): number;
+    /**
+     * Get day of week (0-6, 0=Sunday)
+     */
+    weekday(): number;
+    /**
+     * Get hours (0-23)
+     */
+    hours(): number;
+    /**
+     * Get minutes (0-59)
+     */
+    minutes(): number;
+    /**
+     * Get seconds (0-59)
+     */
+    seconds(): number;
+    /**
+     * Get milliseconds (0-999)
+     */
+    milliseconds(): number;
+    /**
+     * Get day of year (1-366)
+     */
+    dayOfYear(): number;
+    /**
+     * Get ISO week number (1-53)
+     */
+    week(): number;
+    /**
+     * Get quarter (1-4)
+     */
+    quarter(): number;
+    /**
+     * Get days in month
+     */
+    daysInMonth(): number;
+    /**
+     * Get the underlying Date object
+     */
+    toDate(): Date;
+    /**
+     * Get Unix timestamp (seconds)
+     */
+    unix(): number;
+    /**
+     * Convert to array [year, month, day, hours, minutes, seconds, ms]
+     */
+    toArray(): [number, number, number, number, number, number, number];
+    /**
+     * Convert to object
+     */
+    toObject(): {
+        year: number;
+        month: number;
+        day: number;
+        hours: number;
+        minutes: number;
+        seconds: number;
+        milliseconds: number;
+    };
+}
+/**
+ * Create a chainable date wrapper
+ * @example
+ * chain(new Date()).add(1, 'day').format('YYYY-MM-DD')
+ * chain('2025-01-15').startOf('month').toDate()
+ * chain().add(1, 'week').isWeekend()
+ */
+export declare function chain(date?: DateInput): ChainedDate;
+/**
+ * Format a duration in milliseconds
+ * Convenience export for use with chain().diff()
+ * @example formatMs(chain(a).diff(b)) // "2 days, 3 hours"
+ */
+export declare function formatMs(ms: number, options?: FormatOptions): string;
+export {};
+//# sourceMappingURL=chain.d.ts.map

package/dist/chain.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chain.d.ts","sourceRoot":"","sources":["../src/chain.ts"],"names":[],"mappings":"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"}