@adaptic/utils 0.0.984 → 0.0.985

package/dist/index.cjs

@@ -8522,6 +8522,11 @@ const fetchPrices = async (params, options) => {
         try {
             let allResults = [];
             let nextUrl = `${baseUrl}?${urlParams.toString()}`;
+            // DE-006: track upstream freshness across pagination. If any page
+            // reports DELAYED, the whole batch is treated as DELAYED — this is the
+            // safer default for downstream latency-sensitive logic (e.g., trade
+            // execution should refuse stale prices, not silently mix them).
+            let aggregatedStatus = "OK";
             while (nextUrl) {
                 //getLogger().info(`Debug: Fetching ${nextUrl}`);
                 await rateLimiters.massive.acquire();
@@ -8531,6 +8536,7 @@ const fetchPrices = async (params, options) => {
                     throw new Error(`Massive.com API responded with status: ${data.status}`);
                 }
                 if (data.status === "DELAYED") {
+                    aggregatedStatus = "DELAYED";
                     const now = Date.now();
                     const lastWarn = delayedWarnTimestamps.get(params.ticker) ?? 0;
                     if (now - lastWarn > DELAYED_WARN_COOLDOWN_MS) {
@@ -8544,6 +8550,14 @@ const fetchPrices = async (params, options) => {
                 // Check if there's a next page and append API key
                 nextUrl = data.next_url ? `${data.next_url}&apiKey=${apiKey}` : "";
             }
+            // DE-006: stamp each bar with the upstream freshness so downstream
+            // consumers (engine pricing pipeline, performance metrics, risk gates)
+            // can branch on `bar._freshness?.status === "DELAYED"`.
+            const freshness = {
+                status: aggregatedStatus,
+                receivedAt: new Date(),
+                ...(aggregatedStatus === "DELAYED" ? { delayedSince: null } : {}),
+            };
             return allResults.map((entry) => ({
                 date: new Date(entry.t).toLocaleString("en-US", {
                     year: "numeric",
@@ -8564,6 +8578,7 @@ const fetchPrices = async (params, options) => {
                 vol: entry.v,
                 vwap: entry.vw,
                 trades: entry.n,
+                _freshness: freshness,
             }));
         }
         catch (error) {
@@ -8604,6 +8619,43 @@ const fetchPrices = async (params, options) => {
         }
     });
 };
+/**
+ * Variant of {@link fetchPrices} that returns a discriminated
+ * {@link MassiveResult} wrapper, surfacing the upstream feed status (`OK` vs
+ * `DELAYED`) at the result level. This is the preferred entry point for new
+ * code that needs to gate latency-sensitive decisions on freshness.
+ *
+ * The underlying bars are still stamped with `_freshness` so consumers that
+ * already destructure the array can branch per-bar; the wrapper simply
+ * promotes that information to the top of the result for clarity.
+ *
+ * DE-006: closes the loop for callers that need to know when the Massive feed
+ * is on a delayed plan (e.g. free tier, market-data outage downgrade).
+ *
+ * @param params - Same parameters accepted by {@link fetchPrices}.
+ * @param options - Same options accepted by {@link fetchPrices}.
+ * @returns A {@link MassiveResult} carrying the bar array plus freshness
+ *          metadata.
+ */
+const fetchPricesWithFreshness = async (params, options) => {
+    const data = await fetchPrices(params, options);
+    // Bars are stamped uniformly inside `fetchPrices`; reading the first one is
+    // sufficient. If the result is empty (no bars in the requested window) we
+    // default to OK with the current wall clock — there is no upstream signal
+    // to contradict it.
+    const sampleFreshness = data[0]?._freshness;
+    const status = sampleFreshness?.status ?? "OK";
+    const receivedAt = sampleFreshness?.receivedAt ?? new Date();
+    if (status === "DELAYED") {
+        return {
+            status: "DELAYED",
+            data,
+            receivedAt,
+            delayedSince: sampleFreshness?.delayedSince ?? null,
+        };
+    }
+    return { status: "OK", data, receivedAt };
+};
 /**
  * Analyzes the price data for a given stock.
  * @param {MassivePriceData[]} priceData - The price data to analyze.
@@ -9247,7 +9299,11 @@ function getEquityValues(equityData, portfolioHistory, marketTimeUtil, period) {
         initialEquity = Number(validData[0].value);
     }
     return {
-        latestEquity: Number(latestPoint.valueOf),
+        // DE-005: previously `Number(latestPoint.valueOf)`, which read the
+        // un-invoked function reference and silently returned NaN. `latestPoint`
+        // is already a number (see line above; sourced from `point.value` which
+        // is typed `number` in EquityPoint), so use it directly.
+        latestEquity: latestPoint,
         initialEquity,
         latestTimestamp: validData[validData.length - 1].time,
         initialTimestamp: validData[0].time,
@@ -9346,25 +9402,42 @@ async function fetchTreasuryBillRate() {
     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;
+ * Provenance-aware variant of {@link getRiskFreeRate} that returns the rate
+ * AND tells the caller where it came from. Use this in any code path that
+ * publishes performance metrics (Sharpe, alpha, Sortino) so downstream
+ * reports can flag computations made against a fictional fallback rate.
+ *
+ * Behavior is identical to {@link getRiskFreeRate} for the cache and
+ * deduplication semantics; only the return shape differs:
+ *
+ * - Fresh cache hit: `{ source: "cached", fetchedAt: <original fetch time> }`
+ * - Cold or stale cache + successful fetch: `{ source: "live", fetchedAt: <now> }`
+ * - Cold or stale cache + failed fetch but cached value present:
+ *   `{ source: "cached", fetchedAt: <original fetch time> }` — the stale
+ *   value is reused so existing alpha calculations keep working through a
+ *   transient outage. The provenance still says `cached`, not `live`.
+ * - Cold cache + failed fetch + no cached value:
+ *   `{ source: "default", fetchedAt: <now> }` — the 2% fallback is used. This
+ *   is the case downstream reports MUST flag, because Sharpe / alpha computed
+ *   against a 2% floor that was never observed in market data is a fiction.
+ *
+ * DE-029: closes the silent-failure loop where a first-fetch network failure
+ * propagated `DEFAULT_RISK_FREE_RATE` indistinguishable from a live
+ * observation.
+ *
+ * @returns The annualized risk-free rate plus its provenance.
+ */
+async function getRiskFreeRateWithProvenance() {
+    // Snapshot the cache reference before the freshness check so the type
+    // narrows correctly without a non-null assertion (the check itself uses a
+    // mutable module-level variable, which TypeScript will not narrow across).
+    const snapshot = cache;
+    if (snapshot !== null && isFresh(snapshot)) {
+        return {
+            rate: snapshot.rate,
+            source: "cached",
+            fetchedAt: new Date(snapshot.fetchedAt),
+        };
     }
     if (inflight !== null) {
         return inflight;
@@ -9372,8 +9445,13 @@ async function getRiskFreeRate() {
     inflight = (async () => {
         try {
             const rate = await fetchTreasuryBillRate();
-            cache = { rate, fetchedAt: Date.now() };
-            return rate;
+            const fetchedAtMs = Date.now();
+            cache = { rate, fetchedAt: fetchedAtMs };
+            return {
+                rate,
+                source: "live",
+                fetchedAt: new Date(fetchedAtMs),
+            };
         }
         catch (error) {
             const message = error instanceof Error ? error.message : String(error);
@@ -9383,10 +9461,18 @@ async function getRiskFreeRate() {
                     cachedRate: cache.rate,
                     cacheAgeMs: Date.now() - cache.fetchedAt,
                 });
-                return cache.rate;
+                return {
+                    rate: cache.rate,
+                    source: "cached",
+                    fetchedAt: new Date(cache.fetchedAt),
+                };
             }
             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;
+            return {
+                rate: DEFAULT_RISK_FREE_RATE,
+                source: "default",
+                fetchedAt: new Date(),
+            };
         }
         finally {
             inflight = null;
@@ -9394,6 +9480,31 @@ async function getRiskFreeRate() {
     })();
     return inflight;
 }
+/**
+ * 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.
+ *
+ * For provenance-aware callers (performance reports, audit logging) prefer
+ * {@link getRiskFreeRateWithProvenance}, which returns both the rate AND
+ * whether it came from a live fetch, the cache, or the fallback default.
+ *
+ * @returns Annualized risk-free rate as a decimal.
+ */
+async function getRiskFreeRate() {
+    const result = await getRiskFreeRateWithProvenance();
+    return result.rate;
+}
 /**
  * Synchronous accessor that returns the most recent cached risk-free rate
  * without performing I/O. If the cache is stale, a background refresh is
@@ -9408,22 +9519,53 @@ async function getRiskFreeRate() {
  *          {@link DEFAULT_RISK_FREE_RATE} if no value has been cached yet.
  */
 function getCachedRiskFreeRateSync() {
+    return getCachedRiskFreeRateSyncWithProvenance().rate;
+}
+/**
+ * Provenance-aware sibling of {@link getCachedRiskFreeRateSync}. Returns the
+ * cached rate plus a flag indicating whether a real value has been cached
+ * (`"cached"`) or whether the caller is being given the {@link DEFAULT_RISK_FREE_RATE}
+ * fallback (`"default"`).
+ *
+ * Use this in synchronous hot paths that nonetheless need to flag computations
+ * made against the fallback (e.g., real-time alpha streaming where async
+ * round-trips are not viable but downstream reports must still distinguish
+ * live from fictional rates).
+ *
+ * As with the original sync accessor, a stale cache triggers a fire-and-forget
+ * background refresh so the next synchronous call sees fresh data; the call
+ * itself remains synchronous and returns the last-known-good value.
+ *
+ * DE-029: closes the silent-failure loop where the synchronous fallback was
+ * indistinguishable from a real cache hit.
+ *
+ * @returns A {@link RiskFreeRateResult} carrying the rate and its provenance.
+ */
+function getCachedRiskFreeRateSyncWithProvenance() {
     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.
+        void getRiskFreeRateWithProvenance().catch(() => {
+            // Errors are already logged inside getRiskFreeRateWithProvenance;
+            // swallow here to keep this truly fire-and-forget.
         });
-        return DEFAULT_RISK_FREE_RATE;
+        return {
+            rate: DEFAULT_RISK_FREE_RATE,
+            source: "default",
+            fetchedAt: new Date(),
+        };
     }
     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.
+        void getRiskFreeRateWithProvenance().catch(() => {
+            // Errors are already logged inside getRiskFreeRateWithProvenance.
         });
     }
-    return cache.rate;
+    return {
+        rate: cache.rate,
+        source: "cached",
+        fetchedAt: new Date(cache.fetchedAt),
+    };
 }
 
 // metric-calcs.ts
@@ -68581,6 +68723,7 @@ const adaptic = {
         fetchLastQuote: fetchLastQuote,
         fetchTrades: fetchTrades,
         fetchPrices: fetchPrices,
+        fetchPricesWithFreshness: fetchPricesWithFreshness,
         analyseMassivePriceData: analyseMassivePriceData,
         formatPriceData: formatPriceData,
         fetchDailyOpenClose: fetchDailyOpenClose,
@@ -68804,6 +68947,7 @@ exports.getAverageDailyVolume = getAverageDailyVolume;
 exports.getBars = getBars;
 exports.getBuyingPower = getBuyingPower;
 exports.getCachedRiskFreeRateSync = getCachedRiskFreeRateSync;
+exports.getCachedRiskFreeRateSyncWithProvenance = getCachedRiskFreeRateSyncWithProvenance;
 exports.getCrypto24HourChange = getCrypto24HourChange;
 exports.getCryptoBars = getCryptoBars;
 exports.getCryptoDailyPrices = getCryptoDailyPrices;
@@ -68861,6 +69005,7 @@ exports.getPortfolioHistory = getPortfolioHistory;
 exports.getPreviousClose = getPreviousClose;
 exports.getPriceRange = getPriceRange;
 exports.getRiskFreeRate = getRiskFreeRate;
+exports.getRiskFreeRateWithProvenance = getRiskFreeRateWithProvenance;
 exports.getSpread = getSpread;
 exports.getSpreads = getSpreads;
 exports.getStockStreamUrl = getStockStreamUrl;