yahoo-finance2

To prevent overloading Yahoo's servers or being rate-limited, yahoo-finance2 instances include a built-in concurrency manager. By default, an instance has a concurrency limit of 4, meaning no more than 4 simultaneous network requests will be active at any time.

Key behaviors:

• Instance-wide limits: The concurrency and interval limits apply across the entire instance. If you call different methods (e.g., quote() and quoteSummary()) from different parts of your application using the same instance, they all share the same queue and limits.
• FIFO Queueing: Calls are queued in the order they are invoked.
• Process-local: Limits are local to the specific process. Multiple Node/Deno processes, worker threads, or serverless instances will each maintain their own independent queues and limits.
• Safe Parallelism: You can use Promise.all() or forEach with async callbacks to trigger many requests at once; the library will automatically manage the queue to ensure the concurrency limit is never exceeded.

The _getCrumb function in src/lib/getCrumb.ts uses recursion to handle the Yahoo EU-consent redirect flow. To prevent unbounded recursion (which can lead to stack overflow or rate-limiting) caused by misbehaving endpoints, implement a depth limit.

1. Add a depth parameter to _getCrumb (defaulting to 0).
2. Check the depth against a constant (e.g., MAX_CONSENT_REDIRECT_DEPTH = 5).
3. Increment the depth in the recursive call: return await _getCrumb(..., depth + 1).

The public getCrumb wrapper does not need to expose the depth parameter.

// Inside src/lib/getCrumb.ts
const MAX_CONSENT_REDIRECT_DEPTH = 5;

async function _getCrumb(
  cookieJar: CookieJar,
  fetch: Fetch,
  // ... other params
  depth = 0
) {
  if (depth > MAX_CONSENT_REDIRECT_DEPTH) {
    throw new Error(
      "Too many consent redirects while fetching Yahoo crumb (max " +
        MAX_CONSENT_REDIRECT_DEPTH + "). Please report."
    );
  }
  // ... logic
  return await _getCrumb(
    // ... params
    depth + 1
  );
}

In yahoo-finance2 v3+, the library uses an instance-based API via new YahooFinance(options). Each instance is intended to have its own isolated state, including its own cookieJar, logger, and queue options.

However, users should be aware of potential state leakage if multiple instances are used in a single process (e.g., in multi-tenant environments where each user has a different session, proxy, or region). Key areas where state might be shared across instances include:

1. Crumb Cache: The crumb and its associated promise are cryptographically paired with cookies in a cookieJar. If instances share a crumb but use different cookie jars, Yahoo may reject requests with a 401 "Invalid Crumb" error.
2. Request Queue: All instances may funnel through a single global _queue. If different instances have different concurrency or interval settings, they may conflict as the last instance to run assertQueueOptions wins.
3. Quote Combine Debounce Map: The slugMap used for debouncing calls might be shared. This can cause requests from one instance to be merged into a batch executed using the context (cookie jar, fetch options, logger) of a different instance.

To ensure proper isolation, ensure each YahooFinance instance is provided with its own unique cookieJar in the options object.

The quoteCombine() function batches multiple single-symbol quote() requests into a single network call to improve efficiency. It then distributes the results back to the individual callers using a symbol-based lookup.

The Symbol Mismatch Problem: Yahoo Finance may normalize symbols (e.g., converting aapl to AAPL). If the symbol returned by Yahoo does not exactly match the symbol string provided by the caller, the internal distribution loop may attempt to access an undefined entry in the symbol map. In older versions, this would throw a TypeError, causing the entire batch of pending requests to be rejected with a confusing error instead of just the mismatched symbol failing.

Current/Correct Behavior:

• If a returned symbol does not match any requested symbol (due to normalization or being unrequested), it should be ignored during the distribution phase.
• The specific caller who requested the mismatched symbol should fall through to a fallback mechanism that resolves their promise with undefined rather than rejecting the whole batch.
• A successful batch should ensure that matching symbols receive their Quote data, while unmatched or non-existent symbols resolve to undefined.

Choose a module based on your data requirements:

• search(query): Use first if a symbol is uncertain.
• quote(symbolOrSymbols): For current or near real-time data. Accepts a single symbol or an array. Use fields to limit payloads.
• quoteCombine(symbol): Debounces multiple single-symbol calls into fewer quote() requests; ideal for many independent code paths.
• chart(symbol, { period1, period2, interval }): For historical chart data (dividends/splits included). Use return: "array" for easier iteration or return: "object" to mirror Yahoo's native shape.
• historical(): For a simpler OHLCV history interface.
• quoteSummary(symbol, { modules }): For profile, price, summary detail, filings, ownership, and recommendations. Request only required modules.
• fundamentalsTimeSeries(): For financial statements.
• options(symbol): For options chains.
• screener(): Replaces deprecated gainers/losers modules. Use predefined screeners like day_gainers, day_losers, or most_actives.
• trendingSymbols(region), recommendationsBySymbol(), and insights(): For specialized endpoints.

Because the library relies on external services, you should wrap API calls in try...catch blocks. Common failure scenarios include network errors, HTTP errors, missing resources, validation errors, and delisted stocks.

Specific error types are accessible via yahooFinance.errors:

• FailedYahooValidationError: Thrown when the response does not match the expected schema. The error.result property may contain a partially validated or coerced result.
• HTTPError: Thrown for HTTP failures; the message property contains the HTTP Response statusText.
• Generic Error: Thrown when a successful HTTP request returns a JSON body containing an error shape (e.g., { error: { name: "ErrorName", description: "string" } }) that doesn't map to a specific class. The message property will contain the description.

import YahooFinance from "yahoo-finance2";
const yahooFinance = new YahooFinance();

let result;
try {
  result = await yahooFinance.quote(symbol);
} catch (error) {
  if (error instanceof yahooFinance.errors.FailedYahooValidationError) {
    // error.result will be a partially validated / coerced result.
  } else if (error instanceof yahooFinance.errors.HTTPError) {
    // Log and skip
    console.warn(`Skipping yf.quote("${symbol}"): [${error.name}] ${error.message}`);
    return;
  } else {
    // Log and skip
    console.warn(`Skipping yf.quote("${symbol}"): [${error.name}] ${error.message}`);
    return;
  }
}

doSomethingWith(result);