feat: new module recommendationsBySymbol

[pudgereyem]

This PR adds a new module recommendationsBySymbol that retrieves "Similar instruments" to the one's you pass.

How it's used on Yahoo Finance

When you view a specific symbol on Yahoo Finance they will show a widget on the right hand side; "People also watch" - which the user might be interested in. Below you can see what is shown when browsing Activision Blizzard ($ATVI).

About the endpoint

https://query2.finance.yahoo.com/v6/finance/recommendationsbysymbol/${symbols}

• Accepts multiple symbols, comma separated
• No other query parameters as far as I know

The response

The response back from Yahoo looks like this:

{
  "finance": {
    "result": [
      {
        "symbol": "AAPL",
        "recommendedSymbols": [
          { "symbol": "AMZN", "score": 0.292276 },
          { "symbol": "FB", "score": 0.274045 },
          { "symbol": "GOOG", "score": 0.272778 },
          { "symbol": "TSLA", "score": 0.270931 },
          { "symbol": "NFLX", "score": 0.209186 }
        ]
      },
      {
        "symbol": "BMW.DE",
        "recommendedSymbols": [
          { "symbol": "DAI.DE", "score": 0.1927 },
          { "symbol": "VOW.DE", "score": 0.105787 },
          { "symbol": "SIE.DE", "score": 0.102734 },
          { "symbol": "VOW3.DE", "score": 0.098733 },
          { "symbol": "BAS.DE", "score": 0.098715 }
        ]
      }
    ],
    "error": null
  }
}

Changes

• Add new module recommendationsBySymbol
• Add basic tests for recommendationsBySymbol
• Add documentation for the module

Example usage

// Get similar symbols to "AAPL" and "BMW.DE"
const recommendationsBySymbol = await yahooFinance2.recommendationsBySymbol([
  'AAPL',
  'BMW.DE',
]);
recommendationsBySymbol.map((result) => {
  console.log(
    `If you like ${result.symbol}, you might also like`,
    result.recommendedSymbols.map((item) => item.symbol),
  );
});

// will output:
// If you like AAPL, you might also like [ 'AMZN', 'FB', 'GOOG', 'TSLA', 'NFLX' ]
// If you like BMW.DE, you might also like [ 'DAI.DE', 'VOW.DE', 'SIE.DE', 'VOW3.DE', 'BAS.DE' ]

Tests

yarn test --verbose --t recommendationsBySymbol

 PASS  src/modules/recommendationsBySymbol.spec.ts (6.685 s)
  recommendationsBySymbol
    ✓ passes validation for symbol: AAPL (14 ms)
    ✓ passes validation for symbol: OCDO.L (1 ms)
    ✓ passes validation for symbol: BABA (2 ms)
    ✓ passes validation for symbol: QQQ (1 ms)
    ✓ passes validation for symbol: 0P000071W8.TO (1 ms)
    ✓ passes validation for multiple symbols ("AAPL" and "BMW.DE") (2 ms)

[pudgereyem]

@gadicc feel free to have a look when you have time! :)

[gadicc]

@pudgereyem! This is phenomenal work!! You really checked all the boxes on this one... styling, approach, docs, tests... it really is such a pleasure for a project maintainer when contributors fit in so well. Thanks also for getting up to date on all the latest conventions and noticing the new quote module... I know there have been no few changes in the last week 😅 I only have two minor comments:

1. As per 1806e61, could you switch the order of the overloading functions so that it defaults to returning the interface and not any? This was my bad, sorry about that 😅

2. I decided early on (but need to document somewhere, maybe in the contributing doc?) that I like the lib to clean up the result as much as possible before passing off to the user. Do you think you could adapt the code to just return an array of results like we do in quote? It's basically just the result transformWith (but result.finance instead of result.quoteResponse). And then for convenience we can return just a single result if that's all they asked for (and types e.g. lines 11, 115/118, 129/132). The quote API is obviously just a day or two old but I think it's comfortable to work with like that?

Anyway, thanks again for this amazing work! Not sure how long you spent on this but it's super appreciated 😀 Keep up the awesome work 🙌

[pudgereyem]

@gadicc ah, thanks! It was super simple to create the new module. Thanks to the great architecture 💯
Both your comments make total sense, I'll update the PR and request a review once done.

[pudgereyem]

@gadicc please have a look now, I've addressed your two comments above.

[gadicc]

Legend! This is really great, @pudgereyem! Pleasure working with you 😁

[gadicc]

🎉 This PR is included in version 1.7.0 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀