@adaptic/utils 0.0.981 → 0.0.982

package/dist/index.cjs

@@ -9257,6 +9257,172 @@ function getEquityValues(equityData, portfolioHistory, marketTimeUtil, period) {
     };
 }
 
+// risk-free-rate.ts
+/**
+ * Conservative fallback annual risk-free rate used when no live rate has been
+ * fetched yet AND the remote source is unreachable. Chosen to roughly match the
+ * longer-run (post-2000) average of the 3-month US Treasury bill yield.
+ *
+ * This is the rate of LAST resort. Callers that need a live number should
+ * prefer {@link getRiskFreeRate} (async) and only rely on
+ * {@link getCachedRiskFreeRateSync} for hot paths that cannot be made async.
+ */
+const DEFAULT_RISK_FREE_RATE = 0.02;
+/**
+ * Cache TTL for the risk-free rate: 24 hours. Treasury yields update daily
+ * (auction + close), so refreshing more aggressively provides no useful signal
+ * and risks rate-limiting the public endpoint.
+ */
+const RISK_FREE_RATE_TTL_MS = 24 * 60 * 60 * 1000;
+/**
+ * US Treasury Fiscal Data API — Daily Treasury Bill Rates. Free, no API key,
+ * updated each business day. Returns the most recent 4-, 8-, 13-, 17-, 26-,
+ * and 52-week T-Bill rates. We use the 13-week ("3-month") field for Sharpe /
+ * alpha, which is the industry-standard short risk-free proxy.
+ *
+ * See https://fiscaldata.treasury.gov/datasets/daily-treasury-bill-rates/
+ */
+const TREASURY_BILL_RATES_URL = "https://api.fiscaldata.treasury.gov/services/api/fiscal_service/v2/accounting/od/daily_treasury_bill_rates" +
+    "?sort=-record_date&page%5Bsize%5D=1" +
+    "&fields=record_date,security_term_week_num,avg_inv_rate";
+let cache = null;
+let inflight = null;
+/**
+ * Clears the cached risk-free rate. Exported for tests and for callers that
+ * want to force a re-fetch (e.g., at the start of a backtest run with a
+ * different asOf date).
+ */
+function resetRiskFreeRateCache() {
+    cache = null;
+    inflight = null;
+}
+/**
+ * Explicitly sets the cached risk-free rate. Useful for deterministic tests,
+ * backtests (where rf should be pinned to the asOf date), and environments
+ * where an upstream service already provides the rate.
+ *
+ * @param rate - Annualized decimal rate (e.g. 0.0452 for 4.52%).
+ */
+function setRiskFreeRate(rate) {
+    if (!Number.isFinite(rate) || rate < 0 || rate > 1) {
+        throw new Error(`Invalid risk-free rate: ${rate}. Must be a finite decimal in [0, 1].`);
+    }
+    cache = { rate, fetchedAt: Date.now() };
+}
+/**
+ * Returns true iff the cached entry is present and younger than the TTL.
+ */
+function isFresh(entry) {
+    return entry !== null && Date.now() - entry.fetchedAt < RISK_FREE_RATE_TTL_MS;
+}
+/**
+ * Fetches the latest 3-month (13-week) T-Bill annualized rate from the US
+ * Treasury Fiscal Data API. Returns the rate as a decimal (e.g. 0.0452 for
+ * 4.52%). Throws on any failure (network, parse, or missing field) — callers
+ * are expected to handle fallback via {@link getRiskFreeRate}.
+ */
+async function fetchTreasuryBillRate() {
+    const signal = createTimeoutSignal(DEFAULT_TIMEOUTS.GENERAL);
+    const res = await fetch(TREASURY_BILL_RATES_URL, {
+        headers: { Accept: "application/json" },
+        signal,
+    });
+    if (!res.ok) {
+        throw new Error(`Treasury Fiscal Data API returned HTTP ${res.status} ${res.statusText}`);
+    }
+    const body = (await res.json());
+    const rows = Array.isArray(body.data) ? body.data : [];
+    if (rows.length === 0) {
+        throw new Error("Treasury Fiscal Data API returned no rows");
+    }
+    // Prefer the 13-week (3-month) bill; fall back to the shortest term
+    // available on that record date if 13-week is missing.
+    const preferred = rows.find((row) => row.security_term_week_num === "13") ?? rows[0];
+    const percent = Number.parseFloat(preferred.avg_inv_rate);
+    if (!Number.isFinite(percent)) {
+        throw new Error(`Treasury Fiscal Data API returned non-numeric rate: ${preferred.avg_inv_rate}`);
+    }
+    // avg_inv_rate is quoted as a percentage (e.g. "4.52"); normalize to a
+    // decimal for downstream math.
+    return percent / 100;
+}
+/**
+ * Returns the current annualized risk-free rate (decimal, e.g. 0.0452 for
+ * 4.52%), fetching from the US Treasury Fiscal Data API and caching for 24h.
+ *
+ * Behavior:
+ * - If a fresh cached value exists (<24h old), returns it without a network
+ *   round-trip.
+ * - If the cache is stale or empty, fetches the latest 13-week T-Bill rate,
+ *   updates the cache, and returns it.
+ * - If the fetch fails, returns the last-known-good cached value (even if
+ *   expired) or {@link DEFAULT_RISK_FREE_RATE} as a last resort, logging a
+ *   warning in both cases.
+ * - Concurrent calls during a cold cache are deduplicated so only one network
+ *   request is in flight at a time.
+ *
+ * @returns Annualized risk-free rate as a decimal.
+ */
+async function getRiskFreeRate() {
+    if (isFresh(cache)) {
+        return cache.rate;
+    }
+    if (inflight !== null) {
+        return inflight;
+    }
+    inflight = (async () => {
+        try {
+            const rate = await fetchTreasuryBillRate();
+            cache = { rate, fetchedAt: Date.now() };
+            return rate;
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            if (cache !== null) {
+                getLogger().warn("Failed to refresh risk-free rate; using last-known-good cached value", { error: message, cachedRate: cache.rate, cacheAgeMs: Date.now() - cache.fetchedAt });
+                return cache.rate;
+            }
+            getLogger().warn("Failed to fetch risk-free rate and no cached value available; falling back to DEFAULT_RISK_FREE_RATE", { error: message, fallback: DEFAULT_RISK_FREE_RATE });
+            return DEFAULT_RISK_FREE_RATE;
+        }
+        finally {
+            inflight = null;
+        }
+    })();
+    return inflight;
+}
+/**
+ * Synchronous accessor that returns the most recent cached risk-free rate
+ * without performing I/O. If the cache is stale, a background refresh is
+ * kicked off (fire-and-forget) so the next synchronous call sees a fresh
+ * value. Intended for hot paths (e.g., Sharpe/alpha calculation inside tight
+ * loops) where the existing function signature cannot be made async.
+ *
+ * Callers that can tolerate an async boundary should prefer
+ * {@link getRiskFreeRate}.
+ *
+ * @returns The cached annualized risk-free rate as a decimal, or
+ *          {@link DEFAULT_RISK_FREE_RATE} if no value has been cached yet.
+ */
+function getCachedRiskFreeRateSync() {
+    if (cache === null) {
+        // Kick off a background fetch so the next sync caller has a real number.
+        void getRiskFreeRate().catch(() => {
+            // Errors are already logged inside getRiskFreeRate; swallow here to
+            // keep this truly fire-and-forget.
+        });
+        return DEFAULT_RISK_FREE_RATE;
+    }
+    if (!isFresh(cache)) {
+        // Stale: trigger background refresh but still return the last-known-good
+        // value so the call remains synchronous.
+        void getRiskFreeRate().catch(() => {
+            // Errors are already logged inside getRiskFreeRate.
+        });
+    }
+    return cache.rate;
+}
+
 // metric-calcs.ts
 /**
  * Calculates daily returns from an array of closing prices
@@ -9418,9 +9584,11 @@ function calculateBetaFromReturns$1(portfolioReturns, benchmarkReturns) {
         covariance += portfolioDiff * benchmarkDiff;
         variance += benchmarkDiff * benchmarkDiff;
     }
-    // Finalize calculations
-    covariance /= n;
-    variance /= n;
+    // Finalize calculations using sample (Bessel-corrected) estimators —
+    // divide by (n - 1), not n. The guard above (validIndices.length < 2)
+    // already ensures n >= 2, so (n - 1) is always safe.
+    covariance /= n - 1;
+    variance /= n - 1;
     // Handle zero variance case
     if (Math.abs(variance) < 1e-10) {
         getLogger().warn("Benchmark variance is effectively zero. Setting beta to 0.");
@@ -9489,8 +9657,9 @@ async function calculateRiskAdjustedReturn$1(tradeBars) {
         getLogger().warn("Standard deviation is zero or non-finite, cannot calculate Sharpe ratio.");
         return "N/A";
     }
-    // Assume a risk-free rate, e.g., 2%
-    const riskFreeRate = 0.02; // Annual risk-free rate (2%)
+    // Fetch live annualized risk-free rate (3-month T-Bill), cached daily.
+    // See src/risk-free-rate.ts for source + fallback behavior.
+    const riskFreeRate = await getRiskFreeRate();
     // Calculate Sharpe Ratio
     const sharpeRatio = (avgAnnualReturn - riskFreeRate) / stdDevAnnual;
     if (!isFinite(sharpeRatio)) {
@@ -9538,7 +9707,10 @@ async function calculateAlphaAndBeta$1(tradeBars, benchmarkBars, isShort) {
         alignedTradeReturns.length;
     const avgBenchmarkReturn = alignedBenchmarkReturns.reduce((sum, ret) => sum + ret, 0) /
         alignedBenchmarkReturns.length;
-    const riskFreeRateDaily = 0.02 / 252; // Assuming 2% annual risk-free rate
+    // Fetch live annualized risk-free rate (3-month T-Bill), cached daily.
+    // See src/risk-free-rate.ts for source + fallback behavior.
+    const riskFreeRateAnnual = await getRiskFreeRate();
+    const riskFreeRateDaily = riskFreeRateAnnual / 252;
     // Alpha calculation adjusts based on position direction
     const alpha = avgTradeReturn -
         (riskFreeRateDaily +
@@ -9842,8 +10014,9 @@ async function calculateRiskAdjustedReturn(portfolioHistory) {
         getLogger().warn("Standard deviation is zero or non-finite, cannot calculate Sharpe ratio.");
         return "N/A";
     }
-    // Assume a risk-free rate, e.g., 2%
-    const riskFreeRate = 0.02; // Annual risk-free rate (2%)
+    // Fetch live annualized risk-free rate (3-month T-Bill), cached daily.
+    // See src/risk-free-rate.ts for source + fallback behavior.
+    const riskFreeRate = await getRiskFreeRate();
     // Calculate Sharpe Ratio
     const sharpeRatio = (avgAnnualReturn - riskFreeRate) / stdDevAnnual;
     if (!isFinite(sharpeRatio)) {
@@ -10027,7 +10200,9 @@ async function calculateAlphaAndBeta(portfolioHistory, benchmarkBars) {
         };
     }
     // **Calculate alpha**
-    const riskFreeRateAnnual = 0.02; // 2%
+    // Fetch live annualized risk-free rate (3-month T-Bill), cached daily.
+    // See src/risk-free-rate.ts for source + fallback behavior.
+    const riskFreeRateAnnual = await getRiskFreeRate();
     const tradingDaysPerYear = 252;
     const riskFreeRateDaily = riskFreeRateAnnual / tradingDaysPerYear;
     const alpha = portfolioAvgReturn -
@@ -10291,8 +10466,12 @@ function calculateBetaFromReturns(portfolioReturns, benchmarkReturns) {
         covariance += portfolioDiff * benchmarkDiff;
         variance += benchmarkDiff ** 2;
     }
-    covariance /= n;
-    variance /= n;
+    // Use sample (Bessel-corrected) estimators — divide by (n - 1), not n.
+    // For n === 1 there is no degrees-of-freedom left; treat as zero variance
+    // so beta falls through to the zero-variance guard below.
+    const denom = n > 1 ? n - 1 : 1;
+    covariance /= denom;
+    variance /= denom;
     // Handle zero variance
     if (variance === 0) {
         getLogger().warn("Benchmark variance is zero. Setting beta to 0.");
@@ -68498,6 +68677,7 @@ exports.BarError = BarError;
 exports.CryptoDataError = CryptoDataError;
 exports.CryptoOrderError = CryptoOrderError;
 exports.DEFAULT_CACHE_OPTIONS = DEFAULT_CACHE_OPTIONS;
+exports.DEFAULT_RISK_FREE_RATE = DEFAULT_RISK_FREE_RATE;
 exports.DEFAULT_TIMEOUTS = DEFAULT_TIMEOUTS;
 exports.DEFAULT_TRADING_POLICY = DEFAULT_TRADING_POLICY;
 exports.DataFormatError = DataFormatError;
@@ -68520,6 +68700,7 @@ exports.NewsError = NewsError;
 exports.OptionStrategyError = OptionStrategyError;
 exports.OptionsDataError = OptionsDataError;
 exports.QuoteError = QuoteError;
+exports.RISK_FREE_RATE_TTL_MS = RISK_FREE_RATE_TTL_MS;
 exports.RateLimitError = RateLimitError;
 exports.RawMassivePriceDataSchema = RawMassivePriceDataSchema;
 exports.StampedeProtectedCache = StampedeProtectedCache;
@@ -68619,6 +68800,7 @@ exports.getAlpacaClock = getAlpacaClock;
 exports.getAverageDailyVolume = getAverageDailyVolume;
 exports.getBars = getBars;
 exports.getBuyingPower = getBuyingPower;
+exports.getCachedRiskFreeRateSync = getCachedRiskFreeRateSync;
 exports.getCrypto24HourChange = getCrypto24HourChange;
 exports.getCryptoBars = getCryptoBars;
 exports.getCryptoDailyPrices = getCryptoDailyPrices;
@@ -68675,6 +68857,7 @@ exports.getPopularCryptoPairs = getPopularCryptoPairs;
 exports.getPortfolioHistory = getPortfolioHistory;
 exports.getPreviousClose = getPreviousClose;
 exports.getPriceRange = getPriceRange;
+exports.getRiskFreeRate = getRiskFreeRate;
 exports.getSpread = getSpread;
 exports.getSpreads = getSpreads;
 exports.getStockStreamUrl = getStockStreamUrl;
@@ -68718,6 +68901,7 @@ exports.protectLongPosition = protectLongPosition;
 exports.protectShortPosition = protectShortPosition;
 exports.rateLimiters = rateLimiters;
 exports.resetLogger = resetLogger;
+exports.resetRiskFreeRateCache = resetRiskFreeRateCache;
 exports.rollOptionPosition = rollOptionPosition;
 exports.roundPriceForAlpaca = roundPriceForAlpaca$3;
 exports.roundPriceForAlpacaNumber = roundPriceForAlpacaNumber;
@@ -68728,6 +68912,7 @@ exports.sellCryptoNotional = sellCryptoNotional;
 exports.sellToClose = sellToClose;
 exports.sellToOpen = sellToOpen;
 exports.setLogger = setLogger;
+exports.setRiskFreeRate = setRiskFreeRate;
 exports.shortWithStopLoss = shortWithStopLoss;
 exports.sortOrdersByDate = sortOrdersByDate;
 exports.tradingPolicy = index;