ts-time-utils 3.0.4 → 4.1.0

package/dist/esm/calendars.js

@@ -0,0 +1,348 @@
+/**
+ * @fileoverview Non-Gregorian calendar conversions using Intl.DateTimeFormat
+ * Supports Hebrew, Islamic, Buddhist, Japanese, Persian, and Chinese calendars
+ */
+/**
+ * Extracts calendar date parts using Intl.DateTimeFormat
+ */
+function extractCalendarParts(date, calendar) {
+    // First get numeric values where possible
+    const numericFormatter = new Intl.DateTimeFormat('en-u-ca-' + calendar + '-nu-latn', {
+        year: 'numeric',
+        month: 'numeric',
+        day: 'numeric',
+    });
+    const eraFormatter = new Intl.DateTimeFormat('en-u-ca-' + calendar, {
+        era: 'short',
+    });
+    const numericParts = numericFormatter.formatToParts(date);
+    const eraParts = eraFormatter.formatToParts(date);
+    const result = {
+        year: 0,
+        month: 0,
+        day: 0,
+        calendar,
+    };
+    for (const part of numericParts) {
+        switch (part.type) {
+            case 'year': {
+                // Parse year, handling relatedYear for Chinese calendar
+                const parsed = parseInt(part.value, 10);
+                result.year = isNaN(parsed) ? 0 : parsed;
+                break;
+            }
+            case 'month': {
+                // Some calendars return month names instead of numbers
+                const parsed = parseInt(part.value, 10);
+                if (!isNaN(parsed)) {
+                    result.month = parsed;
+                }
+                else {
+                    // For calendars that return month names, get month index
+                    result.month = getMonthIndexFromName(part.value, calendar) || 0;
+                }
+                break;
+            }
+            case 'day':
+                result.day = parseInt(part.value, 10);
+                break;
+        }
+    }
+    // Get era separately
+    for (const part of eraParts) {
+        if (part.type === 'era') {
+            result.era = part.value;
+        }
+    }
+    // Special handling for Chinese calendar year (uses related gregorian year)
+    if (calendar === 'chinese' && result.year === 0) {
+        const relatedFormatter = new Intl.DateTimeFormat('en-u-ca-chinese', {
+            year: 'numeric',
+        });
+        const relatedParts = relatedFormatter.formatToParts(date);
+        for (const part of relatedParts) {
+            if (part.type === 'relatedYear') {
+                result.year = parseInt(part.value, 10);
+            }
+        }
+    }
+    return result;
+}
+/**
+ * Maps month name to month number for non-numeric month calendars
+ */
+function getMonthIndexFromName(monthName, calendar) {
+    const hebrewMonths = {
+        'Tishri': 1, 'Tishrei': 1,
+        'Heshvan': 2, 'Cheshvan': 2, 'Marcheshvan': 2,
+        'Kislev': 3,
+        'Tevet': 4, 'Teves': 4,
+        'Shevat': 5, 'Shvat': 5,
+        'Adar': 6, 'Adar I': 6,
+        'Adar II': 7, 'Adar Sheni': 7,
+        'Nisan': 8, 'Nissan': 8,
+        'Iyar': 9, 'Iyyar': 9,
+        'Sivan': 10, 'Siwan': 10,
+        'Tammuz': 11, 'Tamuz': 11,
+        'Av': 12, 'Menachem Av': 12,
+        'Elul': 13,
+    };
+    if (calendar === 'hebrew') {
+        return hebrewMonths[monthName] || 0;
+    }
+    return 0;
+}
+/**
+ * Convert Gregorian date to Hebrew calendar
+ * @example toHebrewDate(new Date('2024-03-25')) // { year: 5784, month: 6, day: 15, calendar: 'hebrew' }
+ */
+export function toHebrewDate(date) {
+    return extractCalendarParts(date, 'hebrew');
+}
+/**
+ * Convert Gregorian date to Islamic calendar (default: islamic-umalqura)
+ * @param date - Date to convert
+ * @param variant - Islamic calendar variant: 'islamic', 'islamic-umalqura', 'islamic-civil'
+ * @example toIslamicDate(new Date('2024-03-25')) // { year: 1445, month: 9, day: 15, calendar: 'islamic-umalqura' }
+ */
+export function toIslamicDate(date, variant = 'islamic-umalqura') {
+    return extractCalendarParts(date, variant);
+}
+/**
+ * Convert Gregorian date to Buddhist calendar (Thai Solar)
+ * Buddhist Era = Gregorian Year + 543
+ * @example toBuddhistDate(new Date('2024-03-25')) // { year: 2567, month: 3, day: 25, calendar: 'buddhist' }
+ */
+export function toBuddhistDate(date) {
+    return extractCalendarParts(date, 'buddhist');
+}
+/**
+ * Convert Gregorian date to Japanese calendar with era
+ * @example toJapaneseDate(new Date('2024-03-25')) // { year: 6, month: 3, day: 25, era: 'Reiwa', calendar: 'japanese' }
+ */
+export function toJapaneseDate(date) {
+    const result = extractCalendarParts(date, 'japanese');
+    // Get full era name
+    const eraFormatter = new Intl.DateTimeFormat('en-u-ca-japanese', { era: 'long' });
+    const eraParts = eraFormatter.formatToParts(date);
+    const eraPart = eraParts.find(p => p.type === 'era');
+    if (eraPart) {
+        result.era = eraPart.value;
+    }
+    return result;
+}
+/**
+ * Convert Gregorian date to Persian (Jalali/Solar Hijri) calendar
+ * @example toPersianDate(new Date('2024-03-20')) // { year: 1403, month: 1, day: 1, calendar: 'persian' }
+ */
+export function toPersianDate(date) {
+    return extractCalendarParts(date, 'persian');
+}
+/**
+ * Convert Gregorian date to Chinese lunar calendar
+ * @example toChineseDate(new Date('2024-02-10')) // { year: 4721, month: 1, day: 1, calendar: 'chinese' }
+ */
+export function toChineseDate(date) {
+    return extractCalendarParts(date, 'chinese');
+}
+/**
+ * Format date in specified calendar system
+ * @param date - Date to format
+ * @param calendar - Calendar system to use
+ * @param locale - Locale for formatting (default: 'en')
+ * @param options - Additional Intl.DateTimeFormat options
+ */
+export function formatInCalendar(date, calendar, locale = 'en', options = {}) {
+    const localeWithCalendar = `${locale}-u-ca-${calendar}`;
+    const formatter = new Intl.DateTimeFormat(localeWithCalendar, {
+        dateStyle: 'long',
+        ...options,
+    });
+    return formatter.format(date);
+}
+/**
+ * Get month names for a specific calendar system
+ * @param calendar - Calendar system
+ * @param locale - Locale for month names (default: 'en')
+ * @param format - Month name format: 'long', 'short', 'narrow'
+ */
+export function getCalendarMonthNames(calendar, locale = 'en', format = 'long') {
+    const localeWithCalendar = `${locale}-u-ca-${calendar}`;
+    const formatter = new Intl.DateTimeFormat(localeWithCalendar, { month: format });
+    // Generate month names by iterating through a reference year
+    const months = [];
+    const year = 2024;
+    // Most calendars have 12 months, Hebrew has 13 in leap years
+    const maxMonths = calendar === 'hebrew' ? 13 : 12;
+    for (let month = 0; month < maxMonths; month++) {
+        try {
+            const date = new Date(year, month, 15);
+            months.push(formatter.format(date));
+        }
+        catch {
+            break;
+        }
+    }
+    return months;
+}
+/**
+ * Get era name for Japanese calendar
+ * @param date - Date to get era for
+ * @param format - Era format: 'long', 'short', 'narrow'
+ */
+export function getJapaneseEra(date, format = 'long') {
+    const formatter = new Intl.DateTimeFormat('en-u-ca-japanese', { era: format });
+    const parts = formatter.formatToParts(date);
+    const eraPart = parts.find(p => p.type === 'era');
+    return eraPart?.value || '';
+}
+/**
+ * Get all Japanese era names with their start dates
+ */
+export function getJapaneseEras() {
+    return [
+        { name: 'Meiji', start: new Date(1868, 9, 23) },
+        { name: 'Taisho', start: new Date(1912, 6, 30) },
+        { name: 'Showa', start: new Date(1926, 11, 25) },
+        { name: 'Heisei', start: new Date(1989, 0, 8) },
+        { name: 'Reiwa', start: new Date(2019, 4, 1) },
+    ];
+}
+/**
+ * Check if a Hebrew year is a leap year (has 13 months)
+ * @param hebrewYear - Year in Hebrew calendar
+ */
+export function isHebrewLeapYear(hebrewYear) {
+    // Hebrew leap years follow a 19-year cycle
+    // Years 3, 6, 8, 11, 14, 17, 19 are leap years
+    const position = hebrewYear % 19;
+    return [3, 6, 8, 11, 14, 17, 0].includes(position); // 0 = 19th year
+}
+/**
+ * Get Hebrew month name
+ * @param month - Month number (1-13)
+ * @param isLeapYear - Whether the year is a leap year
+ */
+export function getHebrewMonthName(month, isLeapYear = false) {
+    const months = [
+        'Nisan', 'Iyar', 'Sivan', 'Tammuz', 'Av', 'Elul',
+        'Tishrei', 'Cheshvan', 'Kislev', 'Tevet', 'Shevat',
+        isLeapYear ? 'Adar I' : 'Adar',
+        'Adar II'
+    ];
+    return months[month - 1] || '';
+}
+/**
+ * Get Islamic month name
+ * @param month - Month number (1-12)
+ */
+export function getIslamicMonthName(month) {
+    const months = [
+        'Muharram', 'Safar', 'Rabi\' al-Awwal', 'Rabi\' al-Thani',
+        'Jumada al-Awwal', 'Jumada al-Thani', 'Rajab', 'Sha\'ban',
+        'Ramadan', 'Shawwal', 'Dhu al-Qi\'dah', 'Dhu al-Hijjah'
+    ];
+    return months[month - 1] || '';
+}
+/**
+ * Get Persian month name
+ * @param month - Month number (1-12)
+ */
+export function getPersianMonthName(month) {
+    const months = [
+        'Farvardin', 'Ordibehesht', 'Khordad', 'Tir', 'Mordad', 'Shahrivar',
+        'Mehr', 'Aban', 'Azar', 'Dey', 'Bahman', 'Esfand'
+    ];
+    return months[month - 1] || '';
+}
+/**
+ * Check if a Persian year is a leap year
+ * Uses the 2820-year cycle algorithm
+ */
+export function isPersianLeapYear(persianYear) {
+    // Simplified 33-year cycle approximation
+    const remainder = persianYear % 33;
+    return [1, 5, 9, 13, 17, 22, 26, 30].includes(remainder);
+}
+/**
+ * Get Chinese zodiac animal for a year
+ * @param gregorianYear - Gregorian year
+ */
+export function getChineseZodiac(gregorianYear) {
+    const animals = [
+        'Rat', 'Ox', 'Tiger', 'Rabbit', 'Dragon', 'Snake',
+        'Horse', 'Goat', 'Monkey', 'Rooster', 'Dog', 'Pig'
+    ];
+    // 1900 was Year of the Rat
+    const index = (gregorianYear - 1900) % 12;
+    return animals[index >= 0 ? index : index + 12];
+}
+/**
+ * Get Chinese element for a year
+ * @param gregorianYear - Gregorian year
+ */
+export function getChineseElement(gregorianYear) {
+    const elements = ['Metal', 'Water', 'Wood', 'Fire', 'Earth'];
+    // Each element covers 2 years
+    const index = Math.floor(((gregorianYear - 1900) % 10) / 2);
+    return elements[index >= 0 ? index : index + 5];
+}
+/**
+ * Get full Chinese zodiac description (element + animal)
+ * @param gregorianYear - Gregorian year
+ */
+export function getChineseZodiacFull(gregorianYear) {
+    return `${getChineseElement(gregorianYear)} ${getChineseZodiac(gregorianYear)}`;
+}
+/**
+ * Convert calendar date to string representation
+ */
+export function calendarDateToString(calendarDate) {
+    const { year, month, day, era, calendar } = calendarDate;
+    const eraStr = era ? ` ${era}` : '';
+    return `${year}/${month}/${day}${eraStr} (${calendar})`;
+}
+/**
+ * Compare two calendar dates
+ * @returns negative if a < b, 0 if equal, positive if a > b
+ */
+export function compareCalendarDates(a, b) {
+    if (a.calendar !== b.calendar) {
+        throw new Error('Cannot compare dates from different calendar systems');
+    }
+    if (a.year !== b.year)
+        return a.year - b.year;
+    if (a.month !== b.month)
+        return a.month - b.month;
+    return a.day - b.day;
+}
+/**
+ * Get current date in specified calendar
+ */
+export function today(calendar) {
+    return extractCalendarParts(new Date(), calendar);
+}
+/**
+ * Check if two calendar dates are the same day
+ */
+export function isSameCalendarDay(a, b) {
+    return a.calendar === b.calendar &&
+        a.year === b.year &&
+        a.month === b.month &&
+        a.day === b.day;
+}
+/**
+ * Get supported calendar systems
+ */
+export function getSupportedCalendars() {
+    return [
+        'hebrew',
+        'islamic',
+        'islamic-umalqura',
+        'islamic-civil',
+        'buddhist',
+        'japanese',
+        'persian',
+        'chinese'
+    ];
+}

package/dist/esm/compare.d.ts

@@ -214,4 +214,31 @@ export declare function partitionDates(dates: Date[], predicate: (date: Date) =>
  * nthDate(dates, 2) // third earliest
  */
 export declare function nthDate(dates: Date[], n: number): Date | undefined;
+/**
+ * Find the index of the closest date to a target in an array
+ * @param dates - Array of candidate dates
+ * @param target - The target date
+ * @returns Index of the closest date, or -1 if array is empty
+ * @example
+ * closestIndexTo([date1, date2, date3], targetDate) // 1
+ */
+export declare function closestIndexTo(dates: Date[], target: Date): number;
+/**
+ * Get the number of overlapping days between two date ranges
+ * @param range1 - First range { start, end }
+ * @param range2 - Second range { start, end }
+ * @returns Number of overlapping days (0 if no overlap)
+ * @example
+ * getOverlappingDaysInIntervals(
+ *   { start: new Date('2024-01-01'), end: new Date('2024-01-10') },
+ *   { start: new Date('2024-01-05'), end: new Date('2024-01-15') }
+ * ) // 6 (Jan 5-10 inclusive)
+ */
+export declare function getOverlappingDaysInIntervals(range1: {
+    start: Date;
+    end: Date;
+}, range2: {
+    start: Date;
+    end: Date;
+}): number;
 //# sourceMappingURL=compare.d.ts.map

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

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

package/dist/esm/compare.js

@@ -415,3 +415,49 @@ export function nthDate(dates, n) {
         return undefined;
     return sorted[index];
 }
+/**
+ * Find the index of the closest date to a target in an array
+ * @param dates - Array of candidate dates
+ * @param target - The target date
+ * @returns Index of the closest date, or -1 if array is empty
+ * @example
+ * closestIndexTo([date1, date2, date3], targetDate) // 1
+ */
+export function closestIndexTo(dates, target) {
+    if (dates.length === 0)
+        return -1;
+    const targetTime = target.getTime();
+    let closestIndex = 0;
+    let minDiff = Math.abs(dates[0].getTime() - targetTime);
+    for (let i = 1; i < dates.length; i++) {
+        const diff = Math.abs(dates[i].getTime() - targetTime);
+        if (diff < minDiff) {
+            minDiff = diff;
+            closestIndex = i;
+        }
+    }
+    return closestIndex;
+}
+/**
+ * Get the number of overlapping days between two date ranges
+ * @param range1 - First range { start, end }
+ * @param range2 - Second range { start, end }
+ * @returns Number of overlapping days (0 if no overlap)
+ * @example
+ * getOverlappingDaysInIntervals(
+ *   { start: new Date('2024-01-01'), end: new Date('2024-01-10') },
+ *   { start: new Date('2024-01-05'), end: new Date('2024-01-15') }
+ * ) // 6 (Jan 5-10 inclusive)
+ */
+export function getOverlappingDaysInIntervals(range1, range2) {
+    const start1 = new Date(range1.start.getFullYear(), range1.start.getMonth(), range1.start.getDate());
+    const end1 = new Date(range1.end.getFullYear(), range1.end.getMonth(), range1.end.getDate());
+    const start2 = new Date(range2.start.getFullYear(), range2.start.getMonth(), range2.start.getDate());
+    const end2 = new Date(range2.end.getFullYear(), range2.end.getMonth(), range2.end.getDate());
+    const overlapStart = start1 > start2 ? start1 : start2;
+    const overlapEnd = end1 < end2 ? end1 : end2;
+    if (overlapStart > overlapEnd)
+        return 0;
+    const diffMs = overlapEnd.getTime() - overlapStart.getTime();
+    return Math.floor(diffMs / 86400000) + 1;
+}

package/dist/esm/finance.d.ts

@@ -0,0 +1,236 @@
+/**
+ * @fileoverview Finance utilities for market-aware date calculations
+ * Provides US market hours, trading days, settlement dates, and options expiration
+ */
+import type { DateInput } from './types.js';
+/** Supported US stock markets */
+export type USMarket = 'NYSE' | 'NASDAQ';
+/** Market trading hours configuration */
+export interface MarketHours {
+    /** Regular market open time */
+    open: {
+        hour: number;
+        minute: number;
+    };
+    /** Regular market close time */
+    close: {
+        hour: number;
+        minute: number;
+    };
+    /** Market timezone */
+    timezone: string;
+    /** Pre-market open time (optional) */
+    preMarket?: {
+        hour: number;
+        minute: number;
+    };
+    /** After-hours close time (optional) */
+    afterHours?: {
+        hour: number;
+        minute: number;
+    };
+}
+/** Options expiration type */
+export type OptionsExpirationType = 'monthly' | 'weekly' | 'quarterly';
+/** Market hours for US exchanges */
+export declare const MARKET_HOURS: Record<USMarket, MarketHours>;
+/** US market holidays (NYSE/NASDAQ follow same schedule) */
+export declare const US_MARKET_HOLIDAYS: readonly ["New Year's Day", "Martin Luther King Jr. Day", "Presidents' Day", "Good Friday", "Memorial Day", "Juneteenth", "Independence Day", "Labor Day", "Thanksgiving Day", "Christmas Day"];
+/**
+ * Check if a date is a US market holiday
+ * @param date - Date to check
+ * @param market - Market (default: NYSE)
+ * @returns True if the date is a market holiday
+ *
+ * @example
+ * ```ts
+ * isMarketHoliday(new Date('2024-12-25')); // true (Christmas)
+ * isMarketHoliday(new Date('2024-01-02')); // false
+ * ```
+ */
+export declare function isMarketHoliday(date: DateInput, market?: USMarket): boolean;
+/**
+ * Check if a date is a trading day (weekday and not a market holiday)
+ * @param date - Date to check
+ * @param market - Market (default: NYSE)
+ * @returns True if the date is a trading day
+ *
+ * @example
+ * ```ts
+ * isTradingDay(new Date('2024-01-15')); // true (Monday)
+ * isTradingDay(new Date('2024-01-13')); // false (Saturday)
+ * ```
+ */
+export declare function isTradingDay(date: DateInput, market?: USMarket): boolean;
+/**
+ * Check if the market is currently open
+ * @param date - Date/time to check
+ * @param market - Market (default: NYSE)
+ * @returns True if market is open at the specified time
+ *
+ * @example
+ * ```ts
+ * // Check if NYSE is open now
+ * isMarketOpen(new Date(), 'NYSE');
+ *
+ * // Check specific time
+ * isMarketOpen(new Date('2024-01-15T10:30:00-05:00')); // true
+ * ```
+ */
+export declare function isMarketOpen(date: DateInput, market?: USMarket): boolean;
+/**
+ * Get market hours configuration
+ * @param market - Market (default: NYSE)
+ * @returns Market hours configuration (deep copy)
+ *
+ * @example
+ * ```ts
+ * const hours = getMarketHours('NASDAQ');
+ * console.log(hours.open); // { hour: 9, minute: 30 }
+ * ```
+ */
+export declare function getMarketHours(market?: USMarket): MarketHours;
+/**
+ * Get market open time for a specific date
+ * @param date - Date to get market open for
+ * @param market - Market (default: NYSE)
+ * @returns Date set to market open time
+ *
+ * @example
+ * ```ts
+ * const open = getMarketOpen(new Date('2024-01-15'));
+ * console.log(open); // 2024-01-15T09:30:00
+ * ```
+ */
+export declare function getMarketOpen(date: DateInput, market?: USMarket): Date;
+/**
+ * Get market close time for a specific date
+ * @param date - Date to get market close for
+ * @param market - Market (default: NYSE)
+ * @returns Date set to market close time
+ *
+ * @example
+ * ```ts
+ * const close = getMarketClose(new Date('2024-01-15'));
+ * console.log(close); // 2024-01-15T16:00:00
+ * ```
+ */
+export declare function getMarketClose(date: DateInput, market?: USMarket): Date;
+/**
+ * Get next market open time after a given date
+ * @param after - Start searching after this date
+ * @param market - Market (default: NYSE)
+ * @returns Next market open date/time
+ *
+ * @example
+ * ```ts
+ * // If it's Friday evening, returns Monday 9:30 AM
+ * const nextOpen = getNextMarketOpen(new Date('2024-01-12T17:00:00'));
+ * ```
+ */
+export declare function getNextMarketOpen(after: DateInput, market?: USMarket): Date;
+/**
+ * Get next market close time after a given date
+ * @param after - Start searching after this date
+ * @param market - Market (default: NYSE)
+ * @returns Next market close date/time
+ *
+ * @example
+ * ```ts
+ * const nextClose = getNextMarketClose(new Date('2024-01-15T10:00:00'));
+ * // Returns 2024-01-15T16:00:00 (same day close)
+ * ```
+ */
+export declare function getNextMarketClose(after: DateInput, market?: USMarket): Date;
+/**
+ * Calculate settlement date (T+N) from trade date
+ * @param tradeDate - Trade date
+ * @param days - Number of business days for settlement (e.g., 1 for T+1, 2 for T+2)
+ * @param market - Market (default: NYSE)
+ * @returns Settlement date
+ *
+ * @example
+ * ```ts
+ * // T+2 settlement
+ * const settlement = getSettlementDate(new Date('2024-01-15'), 2);
+ * // Returns 2024-01-17 (skipping weekends/holidays)
+ * ```
+ */
+export declare function getSettlementDate(tradeDate: DateInput, days: number, market?: USMarket): Date;
+/**
+ * Calculate trade date from settlement date (reverse T+N)
+ * @param settlementDate - Settlement date
+ * @param days - Number of business days for settlement
+ * @param market - Market (default: NYSE)
+ * @returns Trade date
+ *
+ * @example
+ * ```ts
+ * const tradeDate = getTradeDateFromSettlement(new Date('2024-01-17'), 2);
+ * // Returns 2024-01-15
+ * ```
+ */
+export declare function getTradeDateFromSettlement(settlementDate: DateInput, days: number, market?: USMarket): Date;
+/**
+ * Iterate through each trading day in a range
+ * @param start - Start date
+ * @param end - End date
+ * @param market - Market (default: NYSE)
+ * @returns Array of trading days
+ *
+ * @example
+ * ```ts
+ * const days = eachTradingDay(new Date('2024-01-15'), new Date('2024-01-19'));
+ * // Returns Mon, Tue, Wed, Thu, Fri (if no holidays)
+ * ```
+ */
+export declare function eachTradingDay(start: DateInput, end: DateInput, market?: USMarket): Date[];
+/**
+ * Count trading days between two dates
+ * @param start - Start date
+ * @param end - End date
+ * @param market - Market (default: NYSE)
+ * @returns Number of trading days
+ *
+ * @example
+ * ```ts
+ * const count = countTradingDays(new Date('2024-01-15'), new Date('2024-01-19'));
+ * // Returns 5 (Mon-Fri if no holidays)
+ * ```
+ */
+export declare function countTradingDays(start: DateInput, end: DateInput, market?: USMarket): number;
+/**
+ * Add trading days to a date
+ * @param date - Start date
+ * @param days - Number of trading days to add (can be negative)
+ * @param market - Market (default: NYSE)
+ * @returns Resulting date
+ *
+ * @example
+ * ```ts
+ * const result = addTradingDays(new Date('2024-01-15'), 5);
+ * // Returns 5 trading days later
+ * ```
+ */
+export declare function addTradingDays(date: DateInput, days: number, market?: USMarket): Date;
+/**
+ * Get options expiration date
+ * @param year - Year
+ * @param month - Month (1-12)
+ * @param type - Expiration type (default: 'monthly')
+ * @returns Options expiration date
+ *
+ * @example
+ * ```ts
+ * // Monthly options expire on 3rd Friday
+ * const exp = getOptionsExpiration(2024, 1, 'monthly');
+ *
+ * // Weekly options expire every Friday
+ * const weekly = getOptionsExpiration(2024, 1, 'weekly');
+ *
+ * // Quarterly options expire on 3rd Friday of Mar, Jun, Sep, Dec
+ * const quarterly = getOptionsExpiration(2024, 3, 'quarterly');
+ * ```
+ */
+export declare function getOptionsExpiration(year: number, month: number, type?: OptionsExpirationType): Date;
+//# sourceMappingURL=finance.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"finance.d.ts","sourceRoot":"","sources":["../../src/finance.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C,iCAAiC;AACjC,MAAM,MAAM,QAAQ,GAAG,MAAM,GAAG,QAAQ,CAAC;AAEzC,yCAAyC;AACzC,MAAM,WAAW,WAAW;IAC1B,+BAA+B;IAC/B,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IACvC,gCAAgC;IAChC,KAAK,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IACxC,sBAAsB;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,sCAAsC;IACtC,SAAS,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAC7C,wCAAwC;IACxC,UAAU,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;CAC/C;AAED,8BAA8B;AAC9B,MAAM,MAAM,qBAAqB,GAAG,SAAS,GAAG,QAAQ,GAAG,WAAW,CAAC;AAEvE,oCAAoC;AACpC,eAAO,MAAM,YAAY,EAAE,MAAM,CAAC,QAAQ,EAAE,WAAW,CAetD,CAAC;AAEF,4DAA4D;AAC5D,eAAO,MAAM,kBAAkB,iMAWrB,CAAC;AAyHX;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,SAAS,EAAE,MAAM,GAAE,QAAiB,GAAG,OAAO,CAMnF;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,SAAS,EAAE,MAAM,GAAE,QAAiB,GAAG,OAAO,CAShF;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,SAAS,EAAE,MAAM,GAAE,QAAiB,GAAG,OAAO,CAmBhF;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,MAAM,GAAE,QAAiB,GAAG,WAAW,CASrE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,SAAS,EAAE,MAAM,GAAE,QAAiB,GAAG,IAAI,CAQ9E;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,SAAS,EAAE,MAAM,GAAE,QAAiB,GAAG,IAAI,CAQ/E;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,SAAS,EAAE,MAAM,GAAE,QAAiB,GAAG,IAAI,CAqBnF;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,SAAS,EAAE,MAAM,GAAE,QAAiB,GAAG,IAAI,CAmBpF;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,GAAE,QAAiB,GAAG,IAAI,CAcrG;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,0BAA0B,CAAC,cAAc,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,GAAE,QAAiB,GAAG,IAAI,CAcnH;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,SAAS,EAAE,GAAG,EAAE,SAAS,EAAE,MAAM,GAAE,QAAiB,GAAG,IAAI,EAAE,CAkBlG;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,SAAS,EAAE,GAAG,EAAE,SAAS,EAAE,MAAM,GAAE,QAAiB,GAAG,MAAM,CAEpG;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,GAAE,QAAiB,GAAG,IAAI,CAkB7F;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,GAAE,qBAAiC,GAAG,IAAI,CAiC/G"}