feat: william's percent r (willr) (#20)

Author: shahradelahi

README.md

@@ -35,6 +35,7 @@ For all configuration options, please see [the API docs](https://www.jsdocs.io/p
 - [Relative Strength Index (RSI)](src/momentum/RSI.ts)
 - [Stochastic Oscillator (STOCH)](src/momentum/Stochastic.ts)
 - [Stochastic RSI Oscillator (STOCHRSI)](src/momentum/StochasticRSI.ts)
+- [William's Percent R (WILLR)](src/momentum/WILLR.ts)
 
 ###### Overlap
 

src/index.ts

@@ -44,6 +44,7 @@ export {
   type StochasticRSIOutput,
   type StochasticRSITick,
 } from '@/momentum/StochasticRSI';
+export { WILLR, type WILLRInput, type WILLROutput, type WILLRTick } from '@/momentum/WILLR';
 
 // -- Candles -------------------------
 export { HA, type HAInput, type HAOutput, type HATick } from '@/candles/HA';

src/momentum/WILLR.test.ts

@@ -0,0 +1,26 @@
+import * as assert from 'assert';
+
+import { SampleBars } from '@/samples';
+
+import { WILLR, WILLRInput } from './WILLR';
+
+const input: WILLRInput = {
+  high: SampleBars.high.slice(0, 30),
+  low: SampleBars.low.slice(0, 30),
+  close: SampleBars.close.slice(0, 30),
+  period: 10,
+  decimal: 6,
+};
+
+const expectedResult = [
+  -12.398032, -10.73518, -2.746884, -13.876842, -26.181533, -9.313818, -9.076531, -3.055431,
+  -13.003592, -17.996414, -24.92776, -37.81178, -71.866846, -82.128221, -60.044732, -64.983234,
+  -49.235924, -41.520695, -49.552745, -43.346998, -43.868809,
+];
+
+describe("William's Percent R (WILLR)", function () {
+  it('should calculate WILLR and matched the expected', function () {
+    const result = WILLR.calculate(input);
+    assert.deepEqual(result, expectedResult, 'Wrong Results');
+  });
+});

src/momentum/WILLR.ts

@@ -0,0 +1,92 @@
+import { Indicator, IndicatorInput } from '@/indicator';
+import { RollingWindow } from '@/utils/RollingWindow';
+
+export interface WILLRInput extends IndicatorInput {
+  high: number[];
+  low: number[];
+  close: number[];
+
+  /**
+   * It's period.
+   * @default 14
+   */
+  period?: number;
+}
+
+export type WILLROutput = number | undefined;
+
+export interface WILLRTick {
+  high: number;
+  low: number;
+  close: number;
+}
+
+/**
+ * ### William's Percent R (WILLR)
+ *
+ * William's Percent R is a momentum oscillator similar to the Stochastic Oscillator.
+ * It attempts to identify overbought and oversold conditions.
+ *
+ * **Calculation**:
+ *
+ * ```
+ * WILLR = 100 * ((close - LL) / (HH - LL) - 1)
+ * ```
+ *
+ * Where:
+ * - `LL` is the lowest low for the look-back period.
+ * - `HH` is the highest high for the look-back period.
+ *
+ * **Sources**:
+ *
+ * - https://www.tradingview.com/wiki/Williams_%25R_(%25R)
+ */
+export class WILLR extends Indicator<WILLROutput, WILLRTick> {
+  period: number;
+
+  protected override result: WILLROutput[] = [];
+  protected override generator;
+
+  constructor(input: WILLRInput) {
+    super(input);
+
+    this.period = input.period || 14;
+
+    this.generator = this.willrGenerator();
+    this.generator.next();
+
+    input.high.forEach((high, index) => {
+      this.nextValue({
+        high,
+        low: input.low[index]!,
+        close: input.close[index]!,
+      });
+    });
+  }
+
+  private *willrGenerator(): IterableIterator<WILLROutput, never, WILLRTick> {
+    const highWindow = new RollingWindow(this.period);
+    const lowWindow = new RollingWindow(this.period);
+
+    let tick = yield;
+    let output;
+
+    while (true) {
+      highWindow.push(tick.high);
+      lowWindow.push(tick.low);
+
+      if (highWindow.filled()) {
+        const lowestLow = lowWindow.lowest();
+        const highestHigh = highWindow.highest();
+
+        output = 100 * ((tick.close - lowestLow) / (highestHigh - lowestLow) - 1);
+      }
+
+      tick = yield output;
+    }
+  }
+
+  static calculate(input: WILLRInput): WILLROutput[] {
+    return new WILLR(input).getResult();
+  }
+}