trading-signals 6.9.1 → 7.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -6,9 +6,7 @@ Technical indicators and overlays to run technical analysis with JavaScript / Ty
6
6
 
7
7
  ## Motivation
8
8
 
9
- The "trading-signals" library provides a TypeScript implementation for common technical indicators with arbitrary-precision decimal arithmetic. It is well-suited for algorithmic trading, allowing developers to perform accurate and reliable signal computations for automated trading strategies.
10
-
11
- The main focus of this library is on the accuracy of calculations, but using the provided [faster implementations][2] you can also use it where performance is important.
9
+ The "trading-signals" library provides a TypeScript implementation for common technical indicators. It is well-suited for algorithmic trading, allowing developers to perform signal computations for automated trading strategies.
12
10
 
13
11
  All indicators can be updated over time by streaming data (prices or [candles](https://en.wikipedia.org/wiki/Candlestick_chart)) to the `add` method. Some indicators also provide `static` batch methods for further performance improvements when providing data up-front during a backtest or historical data import. You can try it out streaming input data by running the provided [demo script](./src/start/demo.ts) with `npm start`, which uses a keyboard input stream.
14
12
 
@@ -23,19 +21,19 @@ npm install trading-signals
23
21
  **CommonJS:**
24
22
 
25
23
  ```ts
26
- const {Big, SMA} = require('trading-signals');
24
+ const {SMA} = require('trading-signals');
27
25
  ```
28
26
 
29
27
  **ESM:**
30
28
 
31
29
  ```ts
32
- import {Big, SMA} from 'trading-signals';
30
+ import {SMA} from 'trading-signals';
33
31
  ```
34
32
 
35
33
  **Example:**
36
34
 
37
35
  ```typescript
38
- import {Big, SMA} from 'trading-signals';
36
+ import {SMA} from 'trading-signals';
39
37
 
40
38
  const sma = new SMA(3);
41
39
 
@@ -47,23 +45,17 @@ sma.add(20);
47
45
  // You can add multiple values at once:
48
46
  sma.updates([20, 40, 80]);
49
47
 
50
- // You can add stringified values:
51
- sma.add('10');
52
-
53
48
  // You can replace a previous value (useful for live charting):
54
- sma.replace('40');
55
-
56
- // You can add arbitrary-precision decimals:
57
- sma.add(new Big(30.0009));
49
+ sma.replace(40);
58
50
 
59
51
  // You can check if an indicator is stable:
60
52
  console.log(sma.isStable); // true
61
53
 
62
54
  // If an indicator is stable, you can get its result:
63
- console.log(sma.getResult()?.toFixed()); // "50.0003"
55
+ console.log(sma.getResult()); // 50.0003
64
56
 
65
57
  // You can also get the result without optional chaining:
66
- console.log(sma.getResultOrThrow().toFixed()); // "50.0003"
58
+ console.log(sma.getResultOrThrow()); // 50.0003
67
59
 
68
60
  // Various precisions are available too:
69
61
  console.log(sma.getResultOrThrow().toFixed(2)); // "50.00"
@@ -80,7 +72,7 @@ To input data, you need to call the indicator's `add` method. Depending on wheth
80
72
 
81
73
  ### When to use `getResultOrThrow()`?
82
74
 
83
- You can call `getResultOrThrow()` at any point in time, but it throws errors unless an indicator has received the minimum amount of data. If you call `getResultOrThrow()`, before an indicator has received the required amount of input values, a `NotEnoughDataError` will be thrown.
75
+ You can call `getResultOrThrow()` at any point in time, but it throws errors unless an indicator has received the minimum amount of data. If you call `getResultOrThrow()` before an indicator has received the required amount of input values, a `NotEnoughDataError` will be thrown.
84
76
 
85
77
  **Example:**
86
78
 
@@ -91,8 +83,8 @@ import {SMA} from 'trading-signals';
91
83
  const sma = new SMA(3);
92
84
 
93
85
  // We supply 2 input values
94
- sma.update(10);
95
- sma.update(40);
86
+ sma.add(10);
87
+ sma.add(40);
96
88
 
97
89
  try {
98
90
  // We will get an error, because the minimum amount of inputs is 3
@@ -102,104 +94,82 @@ try {
102
94
  }
103
95
 
104
96
  // We will supply the 3rd input value
105
- sma.update(70);
97
+ sma.add(70);
106
98
 
107
99
  // Now, we will receive a proper result
108
- console.log(sma.getResultOrThrow().valueOf()); // "40"
100
+ console.log(sma.getResultOrThrow()); // 40
109
101
  ```
110
102
 
111
- Most of the time, the minimum amount of data depends on the interval / time period used.
103
+ Most of the time, the minimum amount of data depends on the interval / time period used. If you’re not sure, take a look at the test files for the indicator to see examples of correct usage.
112
104
 
113
105
  ## Technical Indicator Types
114
106
 
107
+ - Exhaustion indicators: Identify trend exhaustion and potential reversal.
108
+ - Momentum indicators: Measure the speed and strength of price movements in a particular direction
115
109
  - Trend indicators: Measure the direction of a trend (uptrend, downtrend or sideways trend)
116
- - Volume indicators: Measure the strength of a trend based on volume
117
110
  - Volatility indicators: Measure the degree of variation in prices over time, regardless of direction
118
- - Momentum indicators: Measure the speed and strength of price movements in a particular direction
111
+ - Volume indicators: Measure the strength of a trend based on volume
119
112
 
120
113
  ## Supported Technical Indicators
121
114
 
122
- 1. [Acceleration Bands](./src/ABANDS/AccelerationBands.ts) (ABANDS)
123
- 1. [Accelerator Oscillator](./src/AC/AC.ts) (AC)
124
- 1. [Average Directional Index](./src/ADX/ADX.ts) (ADX)
125
- 1. [Average True Range](./src/ATR/ATR.ts) (ATR)
126
- 1. [Awesome Oscillator](./src/AO/AO.ts) (AO)
127
- 1. [Bollinger Bands](./src/BBANDS/BollingerBands.ts) (BBANDS)
128
- 1. [Bollinger Bands Width](./src/BBW/BollingerBandsWidth.ts) (BBW)
129
- 1. [Center of Gravity](./src/CG/CG.ts) (CG)
130
- 1. [Commodity Channel Index](./src/CCI/CCI.ts) (CCI)
131
- 1. [Directional Movement Index](./src/DX/DX.ts) (DMI / DX)
132
- 1. [Double Exponential Moving Average](./src/DEMA/DEMA.ts) (DEMA)
133
- 1. [Dual Moving Average](./src/DMA/DMA.ts) (DMA)
134
- 1. [Exponential Moving Average](./src/EMA/EMA.ts) (EMA)
135
- 1. [Interquartile Range](./src/IQR/IQR.ts) (IQR)
136
- 1. [Linear Regression](./src/LINREG/LinearRegression.ts) (LINREG)
137
- 1. [Mean Absolute Deviation](./src/MAD/MAD.ts) (MAD)
138
- 1. [Momentum](./src/MOM/MOM.ts) (MOM / MTM)
139
- 1. [Moving Average Convergence Divergence](./src/MACD/MACD.ts) (MACD)
140
- 1. [On-Balance Volume](./src/OBV/OBV.ts) (OBV)
141
- 1. [Parabolic SAR](./src/PSAR/PSAR.ts) (PSAR)
142
- 1. [Range Expansion Index](./src/momentum/REI/REI.ts) (REI)
143
- 1. [Rate-of-Change](./src/ROC/ROC.ts) (ROC)
144
- 1. [Relative Moving Average](./src/RMA/RMA.ts) (RMA)
145
- 1. [Relative Strength Index](./src/RSI/RSI.ts) (RSI)
146
- 1. [Simple Moving Average](./src/SMA/SMA.ts) (SMA)
147
- 1. [Spencer's 15-Point Moving Average](./src/SMA15/SMA15.ts) (SMA15)
148
- 1. [Stochastic Oscillator](./src/STOCH/StochasticOscillator.ts) (STOCH)
149
- 1. [Stochastic RSI](./src/STOCH/StochasticRSI.ts) (STOCHRSI)
150
- 1. [Tom Demark's Sequential Indicator](./src/TDS/TDS.ts) (TDS)
151
- 1. [True Range](./src/TR/TR.ts) (TR)
152
- 1. [Volume-Weighted Average Price](./src/VWAP/VWAP.ts) (VWAP)
153
- 1. [Weighted Moving Average](./src/WMA/WMA.ts) (WMA)
154
- 1. [Wilder's Smoothed Moving Average](./src/WSMA/WSMA.ts) (WSMA / WWS / SMMA / MEMA)
155
- 1. [Zig Zag Indicator](./src/ZIGZAG/ZigZag.ts) (ZigZag)
115
+ 1. Acceleration Bands (ABANDS)
116
+ 1. Accelerator Oscillator (AC)
117
+ 1. Average Directional Index (ADX)
118
+ 1. Average True Range (ATR)
119
+ 1. Awesome Oscillator (AO)
120
+ 1. Bollinger Bands (BBANDS)
121
+ 1. Bollinger Bands Width (BBW)
122
+ 1. Center of Gravity (CG)
123
+ 1. Commodity Channel Index (CCI)
124
+ 1. Directional Movement Index (DMI / DX)
125
+ 1. Double Exponential Moving Average (DEMA)
126
+ 1. Dual Moving Average (DMA)
127
+ 1. Exponential Moving Average (EMA)
128
+ 1. Interquartile Range (IQR)
129
+ 1. Linear Regression (LINREG)
130
+ 1. Mean Absolute Deviation (MAD)
131
+ 1. Momentum (MOM / MTM)
132
+ 1. Moving Average Convergence Divergence (MACD)
133
+ 1. On-Balance Volume (OBV)
134
+ 1. Parabolic SAR (PSAR)
135
+ 1. Range Expansion Index (REI)
136
+ 1. Rate-of-Change (ROC)
137
+ 1. Relative Moving Average (RMA)
138
+ 1. Relative Strength Index (RSI)
139
+ 1. Simple Moving Average (SMA)
140
+ 1. Spencer's 15-Point Moving Average (SMA15)
141
+ 1. Stochastic Oscillator (STOCH)
142
+ 1. Stochastic RSI (STOCHRSI)
143
+ 1. Tom Demark's Sequential Indicator (TDS)
144
+ 1. True Range (TR)
145
+ 1. Volume-Weighted Average Price (VWAP)
146
+ 1. Weighted Moving Average (WMA)
147
+ 1. Wilder's Smoothed Moving Average (WSMA / WWS / SMMA / MEMA)
148
+ 1. Zig Zag Indicator (ZigZag)
156
149
 
157
150
  Utility Methods:
158
151
 
159
- 1. [Average / Mean](./src/util/getAverage.ts)
160
- 1. [Median](./src/util/getMedian.ts)
161
- 1. [Quartile](./src/util/getQuartile.ts)
162
- 1. [Standard Deviation](./src/util/getStandardDeviation.ts)
163
- 1. [Streaks](./src/util/getStreaks.ts)
152
+ 1. Average / Mean
153
+ 1. Grid Sizing (for [grid trading bots](https://b2broker.com/news/understanding-grid-trading-purpose-pros-cons/))
154
+ 1. Maximum
155
+ 1. Median
156
+ 1. Minimum
157
+ 1. Quartile
158
+ 1. Standard Deviation
159
+ 1. Streaks
160
+ 1. Weekday
164
161
 
165
162
  ## Performance
166
163
 
167
- ### Arbitrary-precision decimal arithmetic
164
+ ### Floating-point arithmetic caveats
168
165
 
169
- JavaScript is very bad with numbers. When calculating `0.1 + 0.2` it shows you `0.30000000000000004`, but the truth is `0.3`.
166
+ JavaScript uses double-precision floating-point arithmetic. For example, `0.1 + 0.2` yields `0.30000000000000004` due to binary floating-point representation.
170
167
 
171
168
  ![JavaScript arithmetic](https://raw.githubusercontent.com/bennycode/trading-signals/HEAD/js-arithmetic.png)
172
169
 
173
- As specified by the ECMAScript standard, all arithmetic in JavaScript uses [double-precision floating-point arithmetic](https://en.wikipedia.org/wiki/Double-precision_floating-point_format), which is only accurate until certain extent. To increase the accuracy and avoid miscalculations, the [trading-signals](https://github.com/bennycode/trading-signals) library uses [big.js][1] which offers arbitrary-precision decimal arithmetic. However, this arbitrary accuracy comes with a downside: Calculations with it are not as performant as with the primitive data type `number`.
174
-
175
- ### Faster implementations
176
-
177
- To get the best of both worlds (high accuracy & high performance), you will find two implementations of each indicator (e.g. `SMA` & `FasterSMA`). The standard implementation uses [big.js][1] and the `Faster`-prefixed version uses common `number` types. Use the standard one when you need high accuracy and use the `Faster`-one when you need high performance:
178
-
179
- ```ts
180
- import {FasterSMA} from './SMA/SMA';
181
-
182
- const fasterSMA = new FasterSMA(5);
183
- console.log(fasterSMA.updates([1, 2, 3, 4, 5]));
184
- ```
185
-
186
- ```ts
187
- import {FasterStochasticRSI, FasterSMA} from 'trading-signals';
188
-
189
- const fasterStochRSI = new FasterStochasticRSI(3, FasterSMA);
190
- fasterStochRSI.update(1);
191
- fasterStochRSI.update(2);
192
- fasterStochRSI.update(3);
193
- fasterStochRSI.update(4);
194
- fasterStochRSI.update(5);
195
- fasterStochRSI.update(6);
196
-
197
- console.log(fasterStochRSI.getResultOrThrow());
198
- ```
199
-
200
- ### Benchmarks
170
+ While this isn’t perfectly accurate, it usually doesn’t matter in practice since indicators often work with averages, which already smooth out precision. In test cases, you can control precision by using Vitest’s [toBeCloseTo](https://vitest.dev/api/expect.html#tobecloseto) assertion.
201
171
 
202
- You can run `npm run start:benchmark` to see the runtime performance of each technical indicator on your machine. This will give you an understanding of which indicators can be calculated faster than others.
172
+ Earlier versions of this library (up to version 6) used [big.js][1] for arbitrary-precision arithmetic, but that made calculations about 100x slower on average. For this reason, support for [big.js][1] was removed starting with version 7.
203
173
 
204
174
  ## Disclaimer
205
175
 
@@ -211,6 +181,7 @@ It is very important to do your own analysis before making any investment based
211
181
 
212
182
  - [Cloud9Trader Indicators (JavaScript)](https://github.com/Cloud9Trader/TechnicalIndicators)
213
183
  - [Crypto Trading Hub Indicators (TypeScript)](https://github.com/anandanand84/technicalindicators)
184
+ - [Highcharts Indicators (TypeScript)](https://github.com/highcharts/highcharts/tree/v12.3.0/ts/Stock/Indicators)
214
185
  - [Indicator TS (TypeScript)](https://github.com/cinar/indicatorts)
215
186
  - [Jesse Trading Bot Indicators (Python)](https://docs.jesse.trade/docs/indicators/reference.html)
216
187
  - [LEAN Indicators (C#)](https://github.com/QuantConnect/Lean/tree/master/Indicators)
@@ -218,7 +189,8 @@ It is very important to do your own analysis before making any investment based
218
189
  - [Pandas TA (Python)](https://github.com/twopirllc/pandas-ta)
219
190
  - [Stock Indicators for .NET (C#)](https://github.com/DaveSkender/Stock.Indicators)
220
191
  - [StockSharp (C#)](https://github.com/StockSharp/StockSharp)
221
- - [ta-math](https://github.com/munrocket/ta-math)
192
+ - [ta-lib (C)](https://github.com/TA-Lib/ta-lib/tree/main/src/ta_func)
193
+ - [ta-math (TypeScript)](https://github.com/munrocket/ta-math)
222
194
  - [ta4j (Java)](https://github.com/ta4j/ta4j)
223
195
  - [Technical Analysis for Rust (Rust)](https://github.com/greyblake/ta-rs)
224
196
  - [Technical Analysis Library using Pandas and Numpy (Python)](https://github.com/bukosabino/ta)
@@ -235,7 +207,6 @@ This package was built by Benny Code. Checkout my [**TypeScript course**](https:
235
207
  [<img src="https://raw.githubusercontent.com/bennycode/trading-signals/main/tstv.png">](https://typescript.tv/)
236
208
 
237
209
  [1]: http://mikemcl.github.io/big.js/
238
- [2]: #faster-implementations
239
210
  [stack_exchange_bennycode_badge]: https://stackexchange.com/users/flair/203782.png?theme=default
240
211
  [stack_exchange_bennycode_url]: https://stackexchange.com/users/203782/benny-neugebauer?tab=accounts
241
212