feat(chart): initial release as "_chart" (#239, #328, #334)

bin/yahoo-finance.js

@@ -2,6 +2,7 @@
 
 import yahooFinance from "../dist/esm/src/index-node.js";
 const moduleNames = Object.keys(yahooFinance).filter((n) => !n.startsWith("_"));
+moduleNames.push("_chart"); // modules in development
 
 const node = process.argv[0];
 const script = process.argv[1];

docs/README.md

@@ -32,6 +32,7 @@ const result = await yahooFinance.module(query, queryOpts, moduleOpts);
 ## Modules
 
 1. [autoc](./modules/autoc.md) - autocomplete, great for symbol lookup.
+1. [_chart](./modules/chart.md) - chart, like historical on steroids.
 1. [historical](./modules/historical.md) - historical market prices.
 1. [quote](./modules/quote.md) - essential symbol info.
 1. [quoteSummary](./modules/quoteSummary.md) - comprehensive symbol info.

docs/modules/chart.md

@@ -0,0 +1,136 @@
+# _chart
+
+WARNING: the `chart` module is still in development; as such, it is currently
+prefixed with an underscore (`_`), i.e. as `_chart`, to reflect that the API
+is not final and may still change.  Until this module is available as `chart`
+(without the underscore), you should expect that package upgrades MAY break.
+
+## Usage:
+
+```js
+import yahooFinance from 'yahoo-finance2';
+
+const query = 'AAPL';
+const queryOptions = { period1: '2021-05-08', /* ... */ };
+const result = await yahooFinance._chart(query, queryOptions);
+
+{
+  meta: {
+    currency: 'USD',
+    symbol: 'AAPL',
+    exchangeName: 'NMS',
+    instrumentType: 'EQUITY',
+    firstTradeDate: new Date("1980-12-12T14:30:00.000Z"),
+    regularMarketTime: new Date("2021-11-19T21:00:02.000Z"),
+    gmtoffset: -18000,
+    timezone: 'EST',
+    exchangeTimezoneName: 'America/New_York',
+    regularMarketPrice: 160.55,
+    chartPreviousClose: 124.808,
+    priceHint: 2,
+    currentTradingPeriod: {
+      pre: {
+        timezone: 'EST',
+        start: new Date("2021-11-19T09:00:00.000Z"),
+        end: new Date("2021-11-19T14:30:00.000Z"),
+        gmtoffset: -18000
+      },
+      regular: {
+        timezone: 'EST',
+        start: new Date("2021-11-19T14:30:00.000Z"),
+        end: new Date("2021-11-19T21:00:00.000Z"),
+        gmtoffset: -18000
+      },
+      post: {
+        timezone: 'EST',
+        start: new Date("2021-11-19T21:00:00.000Z"),
+        end: new Date("2021-11-20T01:00:00.000Z"),
+        gmtoffset: -18000
+      }
+    },
+    dataGranularity: '1d',
+    range: '',
+    validRanges: [
+      '1d',  '5d',  '1mo',
+      '3mo', '6mo', '1y',
+      '2y',  '5y',  '10y',
+      'ytd', 'max'
+    ]
+  },
+  timestamp: [
+    // These are the object keys used below.
+    1598880600,
+    1598967000,
+    1599053400,
+    // ...
+  ],
+  events: {
+    dividends: {
+      '1604673000': { amount: 0.205, date: new Date("2020-11-06T14:30:00.000Z") },
+      '1612535400': { amount: 0.205, date: new Date("2021-02-05T14:30:00.000Z") },
+      '1620394200': { amount: 0.22, date: new Date("2021-05-07T13:30:00.000Z") },
+      '1628256600': { amount: 0.22, date: new Date("2021-08-06T13:30:00.000Z") },
+      '1636119000': { amount: 0.22, date: new Date("2021-11-05T13:30:00.000Z") }
+    },
+    splits: {
+      '1598880600': {
+        date: new Date("2020-08-31T13:30:00.000Z"),
+        numerator: 4,
+        denominator: 1,
+        splitRatio: '4:1'
+      }
+    }
+  },
+  indicators: {
+    quote: [
+      {
+        high: [ 131,  134.8000030517578, 137.97999572753906, /* ... */ ],
+        volume: [ 225702700, 151948100, 200119000, /* ... */ ],
+        open: [ 127.58000183105469, 132.75999450683594, 137.58999633789062, /* ... */ ],
+        low: [ 126, 130.52999877929688, 127, /* ... */ ],
+        close: [ 129.0399932861328, 134.17999267578125, 131.39999389648438, /* ... */ ]
+      }
+    ],
+    adjclose: [
+      {
+        adjclose: [ 128.0284881591797, 133.12820434570312,  130.3699951171875, /* ... */ ],
+      }
+    ]
+  }
+}
+```
+
+## API
+
+```js
+await yahooFinance._chart(query, queryOptions, moduleOptions);
+```
+
+### Query term
+
+Yahoo Symbol, e.g. "AAPL", "TSLA", etc.
+
+### Query Options
+
+| Name          | Type      | Default    | Description                       |
+| ------------- | ----------| ---------- | --------------------------------- |
+| `period1`     | Date*     | *required* | Starting period
+| `period2`     | Date*     | (today)    | Ending period
+| `useYfid`     | boolean   | true       |
+| `interval`    | string    | "1d"       | Interval period (see below)
+| `includePrePost` | boolean | true      |
+| `events`      | string    | "div\|split\|earn" | Event types to return, "\|"-separated
+| `lang`        | string    | "en-US"
+
+
+Dates* can be:
+
+* A **Date** instance, e.g. `new Date(something)`
+* A **string** that can be parsed by `Date()`, e.g. `"2020-01-01"`.
+* A **unix timestamp**, e.g. `1636119000000`
+
+Interval period can be one of 1m, 2m, 5m, 15m, 30m, 60m, 90m, 1h, **1d**, 5d, **1wk**, **1mo**, 3mo.
+
+### Module Options
+
+See [Common Options](../README.md#common-options).

docs/modules/historical.md

@@ -1,5 +1,15 @@
 # historical
 
+API for e.g. https://finance.yahoo.com/quote/AAPL/history?p=AAPL.
+
+Note: the historical API is a little limited; in
+particular:
+
+1. `events` (prices, dividends, and stock splits) must be queried in separate network requests.
+1. `interval` can be only "1d", "1wk", "1m".
+
+For this reason, many of us are instead using the [chart API](./chart.md) which addresses both these points.
+
 ## Usage:
 
 ```js