@discomedia/utils 1.0.19 → 1.0.20

package/dist/index.mjs

@@ -160,6 +160,11 @@ const MARKET_CONFIG = {
     },
 };
 // Helper: Get NY offset for a given UTC date (DST rules for US)
+/**
+ * Returns the NY timezone offset (in hours) for a given UTC date, accounting for US DST rules.
+ * @param date - UTC date
+ * @returns offset in hours (-5 for EST, -4 for EDT)
+ */
 function getNYOffset(date) {
     // US DST starts 2nd Sunday in March, ends 1st Sunday in November
     const year = date.getUTCFullYear();
@@ -172,6 +177,14 @@ function getNYOffset(date) {
     return MARKET_CONFIG.UTC_OFFSET_STANDARD;
 }
 // Helper: Get nth weekday of month in UTC
+/**
+ * Returns the nth weekday of a given month in UTC.
+ * @param year - Year
+ * @param month - 1-based month (e.g. March = 3)
+ * @param weekday - 0=Sunday, 1=Monday, ...
+ * @param n - nth occurrence
+ * @returns Date object for the nth weekday
+ */
 function getNthWeekdayOfMonth(year, month, weekday, n) {
     let count = 0;
     for (let d = 1; d <= 31; d++) {
@@ -188,6 +201,11 @@ function getNthWeekdayOfMonth(year, month, weekday, n) {
     return new Date(Date.UTC(year, month - 1, 28));
 }
 // Helper: Convert UTC date to NY time (returns new Date object)
+/**
+ * Converts a UTC date to NY time (returns a new Date object).
+ * @param date - UTC date
+ * @returns Date object in NY time
+ */
 function toNYTime(date) {
     const offset = getNYOffset(date);
     // NY offset in hours
@@ -196,6 +214,11 @@ function toNYTime(date) {
     return new Date(nyMillis);
 }
 // Helper: Convert NY time to UTC (returns new Date object)
+/**
+ * Converts a NY time date to UTC (returns a new Date object).
+ * @param date - NY time date
+ * @returns Date object in UTC
+ */
 function fromNYTime(date) {
     const offset = getNYOffset(date);
     const nyMillis = date.getTime();
@@ -203,6 +226,12 @@ function fromNYTime(date) {
     return new Date(utcMillis);
 }
 // Helper: Format date in ISO, unix, etc.
+/**
+ * Formats a date in ISO, unix-seconds, or unix-ms format.
+ * @param date - Date object
+ * @param outputFormat - Output format ('iso', 'unix-seconds', 'unix-ms')
+ * @returns Formatted date string or number
+ */
 function formatDate(date, outputFormat = 'iso') {
     switch (outputFormat) {
         case 'unix-seconds':
@@ -215,15 +244,33 @@ function formatDate(date, outputFormat = 'iso') {
     }
 }
 // Helper: Format date in NY locale string
+/**
+ * Formats a date in NY locale string.
+ * @param date - Date object
+ * @returns NY locale string
+ */
 function formatNYLocale(date) {
     return date.toLocaleString('en-US', { timeZone: 'America/New_York' });
 }
 // Market calendar logic
+/**
+ * Market calendar logic for holidays, weekends, and market days.
+ */
 class MarketCalendar {
+    /**
+     * Checks if a date is a weekend in NY time.
+     * @param date - Date object
+     * @returns true if weekend, false otherwise
+     */
     isWeekend(date) {
         const day = toNYTime(date).getUTCDay();
         return day === 0 || day === 6;
     }
+    /**
+     * Checks if a date is a market holiday in NY time.
+     * @param date - Date object
+     * @returns true if holiday, false otherwise
+     */
     isHoliday(date) {
         const nyDate = toNYTime(date);
         const year = nyDate.getUTCFullYear();
@@ -235,6 +282,11 @@ class MarketCalendar {
             return false;
         return Object.values(yearHolidays).some(holiday => holiday.date === formattedDate);
     }
+    /**
+     * Checks if a date is an early close day in NY time.
+     * @param date - Date object
+     * @returns true if early close, false otherwise
+     */
     isEarlyCloseDay(date) {
         const nyDate = toNYTime(date);
         const year = nyDate.getUTCFullYear();
@@ -244,6 +296,11 @@ class MarketCalendar {
         const yearEarlyCloses = marketEarlyCloses[year];
         return yearEarlyCloses && yearEarlyCloses[formattedDate] !== undefined;
     }
+    /**
+     * Gets the early close time (in minutes from midnight) for a given date.
+     * @param date - Date object
+     * @returns minutes from midnight or null
+     */
     getEarlyCloseTime(date) {
         const nyDate = toNYTime(date);
         const year = nyDate.getUTCFullYear();
@@ -257,9 +314,19 @@ class MarketCalendar {
         }
         return null;
     }
+    /**
+     * Checks if a date is a market day (not weekend or holiday).
+     * @param date - Date object
+     * @returns true if market day, false otherwise
+     */
     isMarketDay(date) {
         return !this.isWeekend(date) && !this.isHoliday(date);
     }
+    /**
+     * Gets the next market day after the given date.
+     * @param date - Date object
+     * @returns Date object for next market day
+     */
     getNextMarketDay(date) {
         let nextDay = new Date(date.getTime() + 24 * 60 * 60 * 1000);
         while (!this.isMarketDay(nextDay)) {
@@ -267,6 +334,11 @@ class MarketCalendar {
         }
         return nextDay;
     }
+    /**
+     * Gets the previous market day before the given date.
+     * @param date - Date object
+     * @returns Date object for previous market day
+     */
     getPreviousMarketDay(date) {
         let prevDay = new Date(date.getTime() - 24 * 60 * 60 * 1000);
         while (!this.isMarketDay(prevDay)) {
@@ -276,6 +348,11 @@ class MarketCalendar {
     }
 }
 // Market open/close times
+/**
+ * Returns market open/close times for a given date, including extended and early closes.
+ * @param date - Date object
+ * @returns MarketOpenCloseResult
+ */
 function getMarketTimes(date) {
     const calendar = new MarketCalendar();
     const nyDate = toNYTime(date);
@@ -313,6 +390,12 @@ function getMarketTimes(date) {
     };
 }
 // Is within market hours
+/**
+ * Checks if a date/time is within market hours, extended hours, or continuous.
+ * @param date - Date object
+ * @param intradayReporting - 'market_hours', 'extended_hours', or 'continuous'
+ * @returns true if within hours, false otherwise
+ */
 function isWithinMarketHoursImpl(date, intradayReporting = 'market_hours') {
     const calendar = new MarketCalendar();
     if (!calendar.isMarketDay(date))
@@ -341,6 +424,11 @@ function isWithinMarketHoursImpl(date, intradayReporting = 'market_hours') {
     }
 }
 // Get last full trading date
+/**
+ * Returns the last full trading date (market close) for a given date.
+ * @param currentDate - Date object (default: now)
+ * @returns Date object for last full trading date
+ */
 function getLastFullTradingDateImpl(currentDate = new Date()) {
     const calendar = new MarketCalendar();
     const nyDate = toNYTime(currentDate);
@@ -373,6 +461,12 @@ function getLastFullTradingDateImpl(currentDate = new Date()) {
     return fromNYTime(new Date(Date.UTC(year, month, day, closeHour, closeMinute, 0, 0)));
 }
 // Get day boundaries
+/**
+ * Returns the start and end boundaries for a market day, extended hours, or continuous.
+ * @param date - Date object
+ * @param intradayReporting - 'market_hours', 'extended_hours', or 'continuous'
+ * @returns Object with start and end Date
+ */
 function getDayBoundaries(date, intradayReporting = 'market_hours') {
     const calendar = new MarketCalendar();
     const nyDate = toNYTime(date);
@@ -408,6 +502,12 @@ function getDayBoundaries(date, intradayReporting = 'market_hours') {
     return { start, end };
 }
 // Period calculator
+/**
+ * Calculates the start date for a given period ending at endDate.
+ * @param endDate - Date object
+ * @param period - Period string
+ * @returns Date object for period start
+ */
 function calculatePeriodStartDate(endDate, period) {
     const calendar = new MarketCalendar();
     let startDate;
@@ -449,6 +549,11 @@ function calculatePeriodStartDate(endDate, period) {
     return startDate;
 }
 // Get market time period
+/**
+ * Returns the start and end dates for a market time period.
+ * @param params - MarketTimeParams
+ * @returns PeriodDates object
+ */
 function getMarketTimePeriod(params) {
     const { period, end = new Date(), intraday_reporting = 'market_hours', outputFormat = 'iso', } = params;
     if (!period)
@@ -495,6 +600,11 @@ function getMarketTimePeriod(params) {
     };
 }
 // Market status
+/**
+ * Returns the current market status for a given date.
+ * @param date - Date object (default: now)
+ * @returns MarketStatus object
+ */
 function getMarketStatusImpl(date = new Date()) {
     const calendar = new MarketCalendar();
     const nyDate = toNYTime(date);
@@ -565,10 +675,20 @@ function getMarketStatusImpl(date = new Date()) {
     };
 }
 // API exports
+/**
+ * Returns market open/close times for a given date.
+ * @param options - { date?: Date }
+ * @returns MarketOpenCloseResult
+ */
 function getMarketOpenClose(options = {}) {
     const { date = new Date() } = options;
     return getMarketTimes(date);
 }
+/**
+ * Returns the start and end dates for a market time period as Date objects.
+ * @param params - MarketTimeParams
+ * @returns Object with start and end Date
+ */
 function getStartAndEndDates(params = {}) {
     const { start, end } = getMarketTimePeriod(params);
     return {
@@ -579,9 +699,19 @@ function getStartAndEndDates(params = {}) {
 /**
  * Returns the last full trading date as a Date object.
  */
+/**
+ * Returns the last full trading date as a Date object.
+ * @param currentDate - Date object (default: now)
+ * @returns Date object for last full trading date
+ */
 function getLastFullTradingDate(currentDate = new Date()) {
     return getLastFullTradingDateImpl(currentDate);
 }
+/**
+ * Returns the next market day after the reference date.
+ * @param referenceDate - Date object (default: now)
+ * @returns Object with date, yyyymmdd string, and ISO string
+ */
 function getNextMarketDay({ referenceDate } = {}) {
     const calendar = new MarketCalendar();
     const startDate = referenceDate || new Date();
@@ -598,19 +728,40 @@ function getNextMarketDay({ referenceDate } = {}) {
  * @param time - a string, number (unix timestamp), or Date object representing the time
  * @returns the trading date as a string in YYYY-MM-DD format
  */
+/**
+ * Returns the trading date for a given time in YYYY-MM-DD format (NY time).
+ * @param time - string, number, or Date
+ * @returns trading date string
+ */
 function getTradingDate(time) {
     const date = typeof time === 'number' ? new Date(time) : typeof time === 'string' ? new Date(time) : time;
     const nyDate = toNYTime(date);
     return `${nyDate.getUTCFullYear()}-${String(nyDate.getUTCMonth() + 1).padStart(2, '0')}-${String(nyDate.getUTCDate()).padStart(2, '0')}`;
 }
+/**
+ * Returns the NY timezone offset string for a given date.
+ * @param date - Date object (default: now)
+ * @returns '-04:00' for EDT, '-05:00' for EST
+ */
 function getNYTimeZone(date) {
     const offset = getNYOffset(date || new Date());
     return offset === -4 ? '-04:00' : '-05:00';
 }
+/**
+ * Returns the current market status for a given date.
+ * @param options - { date?: Date }
+ * @returns MarketStatus object
+ */
 function getMarketStatus(options = {}) {
     const { date = new Date() } = options;
     return getMarketStatusImpl(date);
 }
+/**
+ * Checks if a date/time is within market hours, extended hours, or continuous.
+ * @param date - Date object
+ * @param intradayReporting - 'market_hours', 'extended_hours', or 'continuous'
+ * @returns true if within hours, false otherwise
+ */
 function isWithinMarketHours(date, intradayReporting = 'market_hours') {
     return isWithinMarketHoursImpl(date, intradayReporting);
 }
@@ -619,6 +770,11 @@ function isWithinMarketHours(date, intradayReporting = 'market_hours') {
  * endDate is always the most recent market close (previous day's close if before open, today's close if after open).
  * days: 1 or not specified = that day's open; 2 = previous market day's open, etc.
  */
+/**
+ * Returns full trading days from market open to market close.
+ * @param options - { endDate?: Date, days?: number }
+ * @returns Object with startDate and endDate
+ */
 function getTradingStartAndEndDates(options = {}) {
     const { endDate = new Date(), days = 1 } = options;
     const calendar = new MarketCalendar();
@@ -654,6 +810,76 @@ function getTradingStartAndEndDates(options = {}) {
     const startOpen = getMarketOpenClose({ date: startMarketDay }).open;
     return { startDate: startOpen, endDate: endClose };
 }
+/**
+ * Counts trading time between two dates (passed as standard Date objects), excluding weekends and holidays, and closed market hours, using other functions in this library.
+ *
+ * This function calculates the actual trading time between two dates by:
+ * 1. Iterating through each calendar day between startDate and endDate (inclusive)
+ * 2. For each day that is a market day (not weekend/holiday), getting market open/close times
+ * 3. Calculating the overlap between the time range and market hours for that day
+ * 4. Summing up all the trading minutes across all days
+ *
+ * The function automatically handles:
+ * - Weekends (Saturday/Sunday) - skipped entirely
+ * - Market holidays - skipped entirely
+ * - Early close days (e.g. day before holidays) - uses early close time
+ * - Times outside market hours - only counts time within 9:30am-4pm ET (or early close)
+ *
+ * Examples:
+ * - 12pm to 3:30pm same day = 3.5 hours = 210 minutes = 0.54 days
+ * - 9:30am to 4pm same day = 6.5 hours = 390 minutes = 1 day
+ * - Friday 2pm to Monday 2pm = 6.5 hours (Friday 2pm-4pm + Monday 9:30am-2pm)
+ *
+ * @param startDate - Start date/time
+ * @param endDate - End date/time (default: now)
+ * @returns Object containing:
+ *   - days: Trading time as fraction of full trading days (6.5 hours = 1 day)
+ *   - hours: Trading time in hours
+ *   - minutes: Trading time in minutes
+ */
+function countTradingDays(startDate, endDate = new Date()) {
+    const calendar = new MarketCalendar();
+    // Ensure start is before end
+    if (startDate.getTime() > endDate.getTime()) {
+        throw new Error('Start date must be before end date');
+    }
+    let totalMinutes = 0;
+    // Get the NY dates for iteration
+    const startNY = toNYTime(startDate);
+    const endNY = toNYTime(endDate);
+    // Create date at start of first day (in NY time)
+    const currentNY = new Date(Date.UTC(startNY.getUTCFullYear(), startNY.getUTCMonth(), startNY.getUTCDate(), 0, 0, 0, 0));
+    // Iterate through each calendar day
+    while (currentNY.getTime() <= endNY.getTime()) {
+        const currentUTC = fromNYTime(currentNY);
+        // Check if this is a market day
+        if (calendar.isMarketDay(currentUTC)) {
+            // Get market hours for this day
+            const marketTimes = getMarketTimes(currentUTC);
+            if (marketTimes.marketOpen && marketTimes.open && marketTimes.close) {
+                // Calculate the overlap between our time range and market hours
+                const dayStart = Math.max(startDate.getTime(), marketTimes.open.getTime());
+                const dayEnd = Math.min(endDate.getTime(), marketTimes.close.getTime());
+                // Only count if there's actual overlap
+                if (dayStart < dayEnd) {
+                    totalMinutes += (dayEnd - dayStart) / (1000 * 60);
+                }
+            }
+        }
+        // Move to next day
+        currentNY.setUTCDate(currentNY.getUTCDate() + 1);
+    }
+    // Convert to days, hours, minutes
+    const MINUTES_PER_TRADING_DAY = 390; // 6.5 hours
+    const days = totalMinutes / MINUTES_PER_TRADING_DAY;
+    const hours = totalMinutes / 60;
+    const minutes = totalMinutes;
+    return {
+        days: Math.round(days * 1000) / 1000, // Round to 3 decimal places
+        hours: Math.round(hours * 100) / 100, // Round to 2 decimal places
+        minutes: Math.round(minutes)
+    };
+}
 // Export MARKET_TIMES for compatibility
 const MARKET_TIMES = {
     TIMEZONE: MARKET_CONFIG.TIMEZONE,
@@ -1081,6 +1307,12 @@ class Queue {
 			current = current.next;
 		}
 	}
+
+	* drain() {
+		while (this.#head) {
+			yield this.dequeue();
+		}
+	}
 }
 
 function pLimit(concurrency) {
@@ -2110,7 +2342,7 @@ const safeJSON = (text) => {
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 
-const VERSION = '5.10.1'; // x-release-please-version
+const VERSION = '5.10.2'; // x-release-please-version
 
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 const isRunningInBrowser = () => {
@@ -15230,7 +15462,7 @@ var config = {};
 
 var main = {exports: {}};
 
-var version = "17.2.0";
+var version = "17.2.1";
 var require$$4 = {
 	version: version};
 
@@ -15249,9 +15481,12 @@ function requireMain () {
 
 	// Array of tips to display randomly
 	const TIPS = [
-	  '🔐 encrypt with dotenvx: https://dotenvx.com',
+	  '🔐 encrypt with Dotenvx: https://dotenvx.com',
 	  '🔐 prevent committing .env to code: https://dotenvx.com/precommit',
 	  '🔐 prevent building .env in docker: https://dotenvx.com/prebuild',
+	  '📡 observe env with Radar: https://dotenvx.com/radar',
+	  '📡 auto-backup env with Radar: https://dotenvx.com/radar',
+	  '📡 version env with Radar: https://dotenvx.com/radar',
 	  '🛠️  run anywhere with `dotenvx run -- yourcommand`',
 	  '⚙️  specify custom .env file path with { path: \'/custom/path/.env\' }',
 	  '⚙️  enable debug logging with { debug: true }',
@@ -15552,7 +15787,7 @@ function requireMain () {
 	      }
 	    }
 
-	    _log(`injecting env (${keysCount}) from ${shortPaths.join(',')} ${dim(`(tip: ${_getRandomTip()})`)}`);
+	    _log(`injecting env (${keysCount}) from ${shortPaths.join(',')} ${dim(`-- tip: ${_getRandomTip()}`)}`);
 	  }
 
 	  if (lastError) {
@@ -18037,6 +18272,7 @@ const disco = {
         getNYTimeZone: getNYTimeZone,
         getTradingDate: getTradingDate,
         getTradingStartAndEndDates: getTradingStartAndEndDates,
+        countTradingDays: countTradingDays,
         MARKET_TIMES: MARKET_TIMES,
     },
     utils: {