ts-time-utils 4.0.1 → 4.4.0

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

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

package/dist/{fiscal.js → fiscal.cjs}

@@ -1,7 +1,26 @@
+"use strict";
 /**
  * @fileoverview Fiscal year and accounting period utilities
  * Supports configurable fiscal year start months for business calculations
  */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FISCAL_PRESETS = void 0;
+exports.getFiscalYear = getFiscalYear;
+exports.getFiscalQuarter = getFiscalQuarter;
+exports.getFiscalYearStart = getFiscalYearStart;
+exports.getFiscalYearEnd = getFiscalYearEnd;
+exports.getFiscalQuarterStart = getFiscalQuarterStart;
+exports.getFiscalQuarterEnd = getFiscalQuarterEnd;
+exports.isSameFiscalYear = isSameFiscalYear;
+exports.isSameFiscalQuarter = isSameFiscalQuarter;
+exports.getFiscalMonth = getFiscalMonth;
+exports.getDaysRemainingInFiscalYear = getDaysRemainingInFiscalYear;
+exports.getDaysElapsedInFiscalYear = getDaysElapsedInFiscalYear;
+exports.getFiscalYearProgress = getFiscalYearProgress;
+exports.getFiscalWeek = getFiscalWeek;
+exports.formatFiscalYear = formatFiscalYear;
+exports.formatFiscalQuarter = formatFiscalQuarter;
+exports.getFiscalPeriodInfo = getFiscalPeriodInfo;
 const DEFAULT_CONFIG = {
     startMonth: 1, // January (calendar year)
 };
@@ -22,7 +41,7 @@ const DEFAULT_CONFIG = {
  * getFiscalYear(new Date('2024-06-15'), { startMonth: 7 }) // 2023
  * getFiscalYear(new Date('2024-07-15'), { startMonth: 7 }) // 2024
  */
-export function getFiscalYear(date, config = {}) {
+function getFiscalYear(date, config = {}) {
     const { startMonth } = { ...DEFAULT_CONFIG, ...config };
     const month = date.getMonth() + 1; // 1-12
     const year = date.getFullYear();
@@ -47,7 +66,7 @@ export function getFiscalYear(date, config = {}) {
  * getFiscalQuarter(new Date('2024-04-15'), { startMonth: 4 }) // 1
  * getFiscalQuarter(new Date('2024-07-15'), { startMonth: 4 }) // 2
  */
-export function getFiscalQuarter(date, config = {}) {
+function getFiscalQuarter(date, config = {}) {
     const { startMonth } = { ...DEFAULT_CONFIG, ...config };
     const month = date.getMonth() + 1; // 1-12
     // Calculate months since fiscal year start
@@ -67,7 +86,7 @@ export function getFiscalQuarter(date, config = {}) {
  * getFiscalYearStart(2024, { startMonth: 4 }) // 2024-04-01 (FY2024 starts Apr 2024)
  * getFiscalYearStart(2024, { startMonth: 7 }) // 2024-07-01 (FY2024 starts Jul 2024)
  */
-export function getFiscalYearStart(fiscalYear, config = {}) {
+function getFiscalYearStart(fiscalYear, config = {}) {
     const { startMonth } = { ...DEFAULT_CONFIG, ...config };
     // Fiscal year N starts in the startMonth of calendar year N
     return new Date(fiscalYear, startMonth - 1, 1);
@@ -82,7 +101,7 @@ export function getFiscalYearStart(fiscalYear, config = {}) {
  * getFiscalYearEnd(2024, { startMonth: 4 }) // 2025-03-31 (FY2024 ends Mar 2025)
  * getFiscalYearEnd(2024, { startMonth: 7 }) // 2025-06-30 (FY2024 ends Jun 2025)
  */
-export function getFiscalYearEnd(fiscalYear, config = {}) {
+function getFiscalYearEnd(fiscalYear, config = {}) {
     const { startMonth } = { ...DEFAULT_CONFIG, ...config };
     if (startMonth === 1) {
         return new Date(fiscalYear, 11, 31, 23, 59, 59, 999);
@@ -107,7 +126,7 @@ export function getFiscalYearEnd(fiscalYear, config = {}) {
  * getFiscalQuarterStart(2024, 1, { startMonth: 4 }) // 2023-04-01
  * getFiscalQuarterStart(2024, 2, { startMonth: 4 }) // 2023-07-01
  */
-export function getFiscalQuarterStart(fiscalYear, quarter, config = {}) {
+function getFiscalQuarterStart(fiscalYear, quarter, config = {}) {
     if (quarter < 1 || quarter > 4) {
         throw new Error('Quarter must be between 1 and 4');
     }
@@ -129,7 +148,7 @@ export function getFiscalQuarterStart(fiscalYear, quarter, config = {}) {
  * getFiscalQuarterEnd(2024, 2) // 2024-06-30
  * getFiscalQuarterEnd(2024, 1, { startMonth: 4 }) // 2023-06-30
  */
-export function getFiscalQuarterEnd(fiscalYear, quarter, config = {}) {
+function getFiscalQuarterEnd(fiscalYear, quarter, config = {}) {
     if (quarter < 1 || quarter > 4) {
         throw new Error('Quarter must be between 1 and 4');
     }
@@ -146,7 +165,7 @@ export function getFiscalQuarterEnd(fiscalYear, quarter, config = {}) {
  * @param config - Fiscal year configuration
  * @returns True if both dates are in the same fiscal year
  */
-export function isSameFiscalYear(date1, date2, config = {}) {
+function isSameFiscalYear(date1, date2, config = {}) {
     return getFiscalYear(date1, config) === getFiscalYear(date2, config);
 }
 /**
@@ -156,7 +175,7 @@ export function isSameFiscalYear(date1, date2, config = {}) {
  * @param config - Fiscal year configuration
  * @returns True if both dates are in the same fiscal year and quarter
  */
-export function isSameFiscalQuarter(date1, date2, config = {}) {
+function isSameFiscalQuarter(date1, date2, config = {}) {
     return (getFiscalYear(date1, config) === getFiscalYear(date2, config) &&
         getFiscalQuarter(date1, config) === getFiscalQuarter(date2, config));
 }
@@ -170,7 +189,7 @@ export function isSameFiscalQuarter(date1, date2, config = {}) {
  * getFiscalMonth(new Date('2024-04-15'), { startMonth: 4 }) // 1
  * getFiscalMonth(new Date('2024-03-15'), { startMonth: 4 }) // 12
  */
-export function getFiscalMonth(date, config = {}) {
+function getFiscalMonth(date, config = {}) {
     const { startMonth } = { ...DEFAULT_CONFIG, ...config };
     const month = date.getMonth() + 1; // 1-12
     let fiscalMonth = month - startMonth + 1;
@@ -185,7 +204,7 @@ export function getFiscalMonth(date, config = {}) {
  * @param config - Fiscal year configuration
  * @returns Number of days remaining in the fiscal year
  */
-export function getDaysRemainingInFiscalYear(date, config = {}) {
+function getDaysRemainingInFiscalYear(date, config = {}) {
     const fiscalYear = getFiscalYear(date, config);
     const fyEnd = getFiscalYearEnd(fiscalYear, config);
     const startOfDay = new Date(date.getFullYear(), date.getMonth(), date.getDate());
@@ -198,7 +217,7 @@ export function getDaysRemainingInFiscalYear(date, config = {}) {
  * @param config - Fiscal year configuration
  * @returns Number of days elapsed in the fiscal year (including the given date)
  */
-export function getDaysElapsedInFiscalYear(date, config = {}) {
+function getDaysElapsedInFiscalYear(date, config = {}) {
     const fiscalYear = getFiscalYear(date, config);
     const fyStart = getFiscalYearStart(fiscalYear, config);
     const startOfDay = new Date(date.getFullYear(), date.getMonth(), date.getDate());
@@ -211,7 +230,7 @@ export function getDaysElapsedInFiscalYear(date, config = {}) {
  * @param config - Fiscal year configuration
  * @returns Percentage of fiscal year completed (0-100)
  */
-export function getFiscalYearProgress(date, config = {}) {
+function getFiscalYearProgress(date, config = {}) {
     const fiscalYear = getFiscalYear(date, config);
     const fyStart = getFiscalYearStart(fiscalYear, config);
     const fyEnd = getFiscalYearEnd(fiscalYear, config);
@@ -225,14 +244,14 @@ export function getFiscalYearProgress(date, config = {}) {
  * @param config - Fiscal year configuration
  * @returns The fiscal week number
  */
-export function getFiscalWeek(date, config = {}) {
+function getFiscalWeek(date, config = {}) {
     const elapsed = getDaysElapsedInFiscalYear(date, config);
     return Math.ceil(elapsed / 7);
 }
 /**
  * Common fiscal year configurations
  */
-export const FISCAL_PRESETS = {
+exports.FISCAL_PRESETS = {
     /** Calendar year (January start) - Default */
     CALENDAR: { startMonth: 1 },
     /** UK/India government fiscal year (April start) */
@@ -249,7 +268,7 @@ export const FISCAL_PRESETS = {
  * @param format - Format style: 'short' (FY2024) or 'long' (FY2023/24)
  * @returns Formatted fiscal year string
  */
-export function formatFiscalYear(fiscalYear, config = {}, format = 'short') {
+function formatFiscalYear(fiscalYear, config = {}, format = 'short') {
     const { startMonth } = { ...DEFAULT_CONFIG, ...config };
     if (format === 'short' || startMonth === 1) {
         return `FY${fiscalYear}`;
@@ -266,7 +285,7 @@ export function formatFiscalYear(fiscalYear, config = {}, format = 'short') {
  * @param config - Fiscal year configuration
  * @returns Formatted fiscal quarter string
  */
-export function formatFiscalQuarter(fiscalYear, quarter, config = {}) {
+function formatFiscalQuarter(fiscalYear, quarter, config = {}) {
     const fyString = formatFiscalYear(fiscalYear, config, 'short');
     return `Q${quarter} ${fyString}`;
 }
@@ -276,7 +295,7 @@ export function formatFiscalQuarter(fiscalYear, quarter, config = {}) {
  * @param config - Fiscal year configuration
  * @returns Object with fiscal period information
  */
-export function getFiscalPeriodInfo(date, config = {}) {
+function getFiscalPeriodInfo(date, config = {}) {
     const fiscalYear = getFiscalYear(date, config);
     const fiscalQuarter = getFiscalQuarter(date, config);
     return {