docs: Specify technical indicator types (#316)

README.md

@@ -14,7 +14,14 @@ Provide a TypeScript implementation for common technical indicators with arbitra
 - **Typed.** Source code is 100% TypeScript. No need to install external typings.
 - **Tested.** Code coverage is 100%. No surprises when using it.
 
-## Supported Indicators
+## Technical Indicator Types
+
+- Trend indicators: Measure the direction of a trend
+- Volume indicators: Measure the strength of a trend (based on volume)
+- Volatility indicators: Measure the strength of a trend (based on price)
+- Momentum indicators: Measure the speed of price movement
+
+## Supported Technical Indicators
 
 1. Acceleration Bands (ABANDS)
 1. Accelerator Oscillator (AC)
@@ -24,7 +31,7 @@ Provide a TypeScript implementation for common technical indicators with arbitra
 1. Bollinger Bands (BBANDS)
 1. Center of Gravity (CG)
 1. Double Exponential Moving Average (DEMA)
-1. Double Moving Average (DMA)
+1. Dual Moving Average (DMA)
 1. Exponential Moving Average (EMA)
 1. Momentum (MOM)
 1. Moving Average Convergence Divergence (MACD)
@@ -88,6 +95,12 @@ sma.update(70);
 console.log(sma.getResult().valueOf()); // "40"
 ```
 
+## Disclaimer
+
+The information and publications of [trading-signals](https://github.com/bennycode/trading-signals) do not constitute financial advice, investment advice, trading advice or any other form of advice. All results from [trading-signals](https://github.com/bennycode/trading-signals) are intended for information purposes only.
+
+It is very important to do your own analysis before making any investment based on your own personal circumstances. If you need financial advice or further advice in general, it is recommended that you identify a relevantly qualified individual in your jurisdiction who can advise you accordingly.
+
 ## Alternatives
 
 - [Tulip Indicators (ANSI C)](https://github.com/TulipCharts/tulipindicators)

src/AC/AC.ts

@@ -6,11 +6,16 @@ import {SMA} from '../SMA/SMA';
 import {MOM} from '../MOM/MOM';
 
 /**
+ * Accelerator Oscillator (AC)
+ * Type: Momentum
+ *
  * The Accelerator Oscillator (AC) is an indicator used to detect when a momentum changes. It has been developed by
  * Bill Williams. If the momentum in an uptrend is starting to slow down, that could suggest that there is less
  * interest in the asset. This typically leads to selling. In the inverse, momentum to the downside will start to slow
  * down before buy orders come in. The Accelerator Oscillator also looks at whether there is an acceleration in the
  * change of momentum.
+ *
+ * @see https://www.thinkmarkets.com/en/indicators/bill-williams-accelerator/
  */
 export class AC extends SimpleIndicator {
   public readonly ao: AO;

src/ADX/ADX.ts

@@ -14,16 +14,20 @@ export type ADXResult = {
 };
 
 /**
- * Average Directional Index (Trend Strength)
+ * Average Directional Index (ADX)
+ * Type: Volatility
  *
- * The ADX does not indicate trend direction or momentum, only trend strength. It is a lagging indicator; that is, a
+ * The ADX was developed by **John Welles Wilder, Jr.**. It is a lagging indicator; that is, a
  * trend must have established itself before the ADX will generate a signal that a trend is under way.
  *
  * ADX will range between 0 and 100.
  *
  * Generally, ADX readings below 20 indicate trend weakness, and readings above 40 indicate trend strength.
  * A strong trend is indicated by readings above 50. ADX values of 75-100 signal an extremely strong trend.
  *
+ * If ADX increases, it means that volatility is increasing and indicating the beginning of a new trend.
+ * If ADX decreases, it means that volatility is decreasing, and the current trend is slowing down and may even reverse.
+ *
  * @see https://www.investopedia.com/terms/a/adx.asp
  * @see https://learn.tradimo.com/technical-analysis-how-to-work-with-indicators/adx-determing-the-strength-of-price-movement
  */

src/AO/AO.ts

@@ -4,8 +4,17 @@ import {SMA} from '../SMA/SMA';
 import {NotEnoughDataError} from '../error';
 
 /**
+ * Awesome Oscillator (AO)
+ * Type: Momentum
+ *
  * The Awesome Oscillator (AO) is an indicator used to measure market momentum.
  * It has been developed by the technical analyst and charting enthusiast Bill Williams.
+ *
+ * When AO crosses above Zero, short term momentum is rising faster than long term momentum which signals a bullish buying opportunity.
+ * When AO crosses below Zero, short term momentum is falling faster then the long term momentum which signals a bearish selling opportunity.
+ *
+ * @see https://www.tradingview.com/support/solutions/43000501826-awesome-oscillator-ao/
+ * @see https://tradingstrategyguides.com/bill-williams-awesome-oscillator-strategy/
  */
 export class AO extends SimpleIndicator {
   public readonly long: SMA;

src/ATR/ATR.ts

@@ -7,11 +7,12 @@ import {MovingAverageTypeContext} from '../MA/MovingAverageTypeContext';
 export type ATRCandle = {close: BigSource; high: BigSource; low: BigSource};
 
 /**
- * Average True Range (Volatility)
+ * Average True Range (ATR)
+ * Type: Volatility
  *
- * The idea of ranges is that they show the commitment or enthusiasm of traders. Large or increasing ranges suggest
- * traders prepared to continue to bid up or sell down a stock through the course of the day. Decreasing range suggests
- * waning interest.
+ * The ATR was developed by **John Welles Wilder, Jr.**. The idea of ranges is that they show the commitment or
+ * enthusiasm of traders. Large or increasing ranges suggest traders prepared to continue to bid up or sell down a
+ * stock through the course of the day. Decreasing range indicates declining interest.
  *
  * @see https://www.investopedia.com/terms/a/atr.asp
  */

src/BANDS/AccelerationBands.ts

@@ -1,22 +1,30 @@
 import {SMA} from '../SMA/SMA';
-import {EMA} from '../EMA/EMA';
 import Big, {BigSource} from 'big.js';
 import {NotEnoughDataError} from '../error';
 import {BandsResult} from './BandsResult';
 import {Indicator} from '../Indicator';
+import {MovingAverageTypeContext} from '../MA/MovingAverageTypeContext';
+import {MovingAverage} from '../MA/MovingAverage';
 
 export class AccelerationBands implements Indicator<BandsResult> {
-  private readonly lowerBand: EMA | SMA;
-  private readonly middleBand: EMA | SMA;
-  private readonly upperBand: EMA | SMA;
+  private readonly lowerBand: MovingAverage;
+  private readonly middleBand: MovingAverage;
+  private readonly upperBand: MovingAverage;
 
   /**
-   * Acceleration Bands
+   * Acceleration Bands (ABANDS)
+   * Type: Volatility
+   *
+   * Acceleration bands are set as an envelope around a moving average. The upper and lower bands are of equal distance
+   * from the middle band.
+   *
+   * Two consecutive closes outside Acceleration Bands suggest an entry point in the direction of the breakout (either
+   * bullish or bearish). A long position is usually kept till the first close back inside the bands.
    *
    * @param interval The interval that is being used for the three moving averages which create lower, middle and upper
    *   bands
    * @param width A coefficient specifying the distance between the middle band and upper/lower bands
-   * @param Indicator Which average (SMA, EMA) to use
+   * @param Indicator Which moving average (SMA, EMA, ...) to use
    *
    * @see https://www.tradingtechnologies.com/xtrader-help/x-study/technical-indicator-definitions/acceleration-bands-abands/
    * @see https://www.motivewave.com/studies/acceleration_bands.htm
@@ -26,7 +34,7 @@ export class AccelerationBands implements Indicator<BandsResult> {
   constructor(
     public readonly interval: number,
     public readonly width: number,
-    Indicator: typeof EMA | typeof SMA = SMA
+    Indicator: MovingAverageTypeContext = SMA
   ) {
     this.lowerBand = new Indicator(interval);
     this.middleBand = new Indicator(interval);

src/BANDS/BollingerBands.ts

@@ -5,21 +5,36 @@ import {BandsResult} from './BandsResult';
 import {Indicator} from '../Indicator';
 import {getAverage} from '../util/getAverage';
 
+/**
+ * Bollinger Bands (BBANDS)
+ * Type: Volatility
+ *
+ * Bollinger bands are set as an envelope around a moving average. Narrow bands indicate a sideways trend (ranging
+ * markets). To determine a breakout direction, [Investopia.com
+ * suggests](https://www.investopedia.com/articles/technical/04/030304.asp) to use the relative strength index (RSI)
+ * along with one or two volume-based indicators such as the intraday intensity index (developed by David Bostian) or
+ * the accumulation/distribution index (developed by Larry William).
+ *
+ * When the upper and lower bands expand, there can be "M" and "W" formations. The "W" formation indicates a bullish
+ * movement and the "M" formation indicates a bearish movement.
+ *
+ * @see https://www.investopedia.com/terms/b/bollingerbands.asp
+ */
 export class BollingerBands implements Indicator<BandsResult> {
   public readonly prices: Big[] = [];
-  private readonly middleSMA: SMA;
+  private readonly middle: SMA;
   private result: BandsResult | undefined;
 
   constructor(public readonly interval: number = 0, public readonly deviationMultiplier: number = 2) {
-    this.middleSMA = new SMA(this.interval);
+    this.middle = new SMA(this.interval);
   }
 
   get isStable(): boolean {
     return this.prices.length >= this.interval;
   }
 
   update(price: BigSource): void {
-    this.middleSMA.update(price);
+    this.middle.update(price);
     this.prices.push(new Big(price));
 
     while (this.prices.length > this.interval) {
@@ -30,14 +45,14 @@ export class BollingerBands implements Indicator<BandsResult> {
       return;
     }
 
-    const avg = this.middleSMA.getResult();
-    const squareDiffs = this.prices.map((price: Big) => price.sub(avg).pow(2));
+    const middle = this.middle.getResult();
+    const squareDiffs = this.prices.map((price: Big) => price.sub(middle).pow(2));
     const standardDeviation = getAverage(squareDiffs).sqrt();
 
     this.result = {
-      lower: avg.sub(standardDeviation.times(this.deviationMultiplier)),
-      middle: avg,
-      upper: avg.add(standardDeviation.times(this.deviationMultiplier)),
+      lower: middle.sub(standardDeviation.times(this.deviationMultiplier)),
+      middle,
+      upper: middle.add(standardDeviation.times(this.deviationMultiplier)),
     };
   }
 

src/CG/CG.ts

@@ -4,6 +4,9 @@ import {SMA} from '../SMA/SMA';
 import {NotEnoughDataError} from '../error';
 
 /**
+ * Center of Gravity (CG)
+ * Type: Trend
+ *
  * Implementation of the Center of Gravity (CG) oscillator by John Ehlers.
  *
  * @note According to the specification, the price inputs shall be calculated the following way:

src/DEMA/DEMA.ts

@@ -2,6 +2,16 @@ import Big, {BigSource} from 'big.js';
 import {EMA, NotEnoughDataError} from '..';
 import {SimpleIndicator} from '../Indicator';
 
+/**
+ * Double Exponential Moving Average (DEMA)
+ * Type: Trend
+ *
+ * The Double Exponential Moving Average (DEMA) was developed by Patrick G. Mulloy. It attempts to remove the lag
+ * associated with Moving Averages by placing more weight on recent values. It has its name because the value of an EMA
+ * is doubled which makes it responds more quickly to short-term price changes than a normal EMA.
+ *
+ * @see https://www.investopedia.com/terms/d/double-exponential-moving-average.asp
+ */
 export class DEMA extends SimpleIndicator {
   private readonly inner: EMA;
   private readonly outer: EMA;

src/DMA/DMA.ts

@@ -1,16 +1,27 @@
 import Big, {BigSource} from 'big.js';
-import {EMA, SMA} from '..';
-import {MovingAverage} from '../MA/MovingAverage';
+import {MovingAverage, MovingAverageTypeContext, SMA} from '..';
 import {Indicator} from '../Indicator';
 
 export type DMAResult = {long: Big; short: Big};
 
+/**
+ * Dual Moving Average (DMA)
+ * Type: Trend
+ *
+ * The DMA consists of two moving averages: Short-term & long-term.
+ *
+ * Dual Moving Average Crossover:
+ * A short-term MA crossing above a long-term MA indicates a bullish buying opportunity.
+ * A short-term MA crossing below a long-term MA indicates a bearish selling opportunity.
+ *
+ * @see https://faculty.fuqua.duke.edu/~charvey/Teaching/BA453_2002/CCAM/CCAM.htm#_Toc2634228
+ */
 export class DMA implements Indicator<DMAResult> {
   public readonly long: MovingAverage;
   public readonly short: MovingAverage;
   private received: number = 0;
 
-  constructor(short: number, long: number, Indicator: typeof EMA | typeof SMA = SMA) {
+  constructor(short: number, long: number, Indicator: MovingAverageTypeContext = SMA) {
     this.short = new Indicator(short);
     this.long = new Indicator(long);
   }

src/EMA/EMA.ts

@@ -2,6 +2,14 @@ import Big, {BigSource} from 'big.js';
 import {MovingAverage} from '../MA/MovingAverage';
 import {NotEnoughDataError} from '../error';
 
+/**
+ * Exponential Moving Average (EMA)
+ * Type: Trend
+ *
+ * Compared to SMA, the EMA puts more emphasis on the recent prices to reduce lag. Due to its responsiveness to price changes, it rises faster and falls faster than the SMA when the price is inclining or declining.
+ *
+ * @see https://www.investopedia.com/terms/e/ema.asp
+ */
 export class EMA extends MovingAverage {
   private pricesCounter = 0;
 

src/MA/MovingAverage.ts

@@ -2,6 +2,14 @@ import Big, {BigSource} from 'big.js';
 import {NotEnoughDataError} from '../error';
 import {SimpleIndicator} from '../Indicator';
 
+/**
+ * Moving Average (MA)
+ * Type: Trend
+ *
+ * Base class for trend-following (lagging) indicators. The longer the moving average interval, the greater the lag.
+ *
+ * @see https://www.investopedia.com/terms/m/movingaverage.asp
+ */
 export abstract class MovingAverage extends SimpleIndicator {
   constructor(public readonly interval: number) {
     super();

src/MACD/MACD.ts

@@ -16,6 +16,14 @@ export type MACDResult = {
   signal: Big;
 };
 
+/**
+ * Moving Average Convergence Divergence (MACD)
+ * Type: Momentum
+ *
+ * The MACD triggers trading signals when it crosses above (bullish buying opportunity) or below (bearish selling opportunity) its signal line. MACD can be used together with the RSI to provide a more accurate trading signal.
+ *
+ * @see https://www.investopedia.com/terms/m/macd.asp
+ */
 export class MACD implements Indicator<MACDResult> {
   public readonly long: EMA | DEMA;
   public readonly short: EMA | DEMA;

src/MOM/MOM.ts

@@ -4,7 +4,12 @@ import {getFixedArray} from '../util/getFixedArray';
 import {NotEnoughDataError} from '../error';
 
 /**
+ * Momentum Indicator (MOM)
+ * Type: Momentum
+ *
  * The Momentum indicator returns the change between the current price and the price n times ago.
+ *
+ * @see https://www.warriortrading.com/momentum-indicator/
  */
 export class MOM extends SimpleIndicator {
   private readonly history: BigSource[];