ts-time-utils 4.0.1 → 4.4.0

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":"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"}