openalgo-script 0.1.0-alpha.0 → 0.2.0

package/src/core/stdlib/volume/flow.ts

@@ -0,0 +1,173 @@
+/**
+ * The lookback volume readings: `cmf`, `mfi`, `eom`, `forceIndex` and
+ * `relativeVolume`.
+ *
+ * Each is written once, as a step over a state region, and its tail is that
+ * step over a region of its own.
+ */
+import type { Bar, StateRecord, Tail, Value } from '../values/index.js';
+import { NONE, fold, held, hl2, hlc3, isPresent, result, tailOf } from '../values/index.js';
+import { emaStep, smaStep } from '../averages/index.js';
+import { changeStep, sumStep } from '../series/index.js';
+
+import { moneyFlow } from './accumulation.js';
+
+/** `cmf(len)`: accumulation over the lookback as a fraction of its volume, from bar `len - 1`. */
+export function cmfStep(
+  state: StateRecord,
+  key: string,
+  bar: Bar,
+  len: number | null,
+): Value {
+  const flow = sumStep(state, `${key}f`, moneyFlow(bar), len);
+  const traded = sumStep(state, `${key}v`, bar.volume, len);
+  if (!isPresent(flow) || !isPresent(traded) || !(traded > 0)) return NONE;
+  return result(flow / traded);
+}
+
+/** `cmf(len)` as a tail. */
+export function cmfTail(len = 20): Tail<Bar, Value> {
+  return tailOf((state, bar: Bar) => cmfStep(state, '', bar, len));
+}
+
+/** `cmf(len)` over a run of bars. */
+export function cmf(bars: readonly Bar[], len = 20): Value[] {
+  return fold(cmfTail(len), bars);
+}
+
+/**
+ * `mfi(len)`: the strength reading computed on money flow rather than price,
+ * from bar `len`.
+ *
+ * A bar's whole flow counts on one side or the other, by whether the typical
+ * price rose or fell, so the first lookback is bars 1 to `len` and the extra bar
+ * is in the declared warmup.
+ */
+export function mfiStep(
+  state: StateRecord,
+  key: string,
+  bar: Bar,
+  len: number | null,
+): Value {
+  const typicalKey = `${key}p`;
+  const seenKey = `${key}k`;
+  const typical = hlc3(bar);
+  const before = held(state, typicalKey);
+  const started = state[seenKey] === true;
+  state[seenKey] = true;
+  state[typicalKey] = typical;
+
+  let up: Value = NONE;
+  let down: Value = NONE;
+  if (started && isPresent(typical) && isPresent(before) && isPresent(bar.volume)) {
+    const flow = result(typical * bar.volume);
+    up = typical > before ? flow : 0;
+    down = typical < before ? flow : 0;
+  }
+
+  const rise = sumStep(state, `${key}u`, up, len);
+  const fall = sumStep(state, `${key}d`, down, len);
+  if (!isPresent(rise) || !isPresent(fall)) return NONE;
+  // No down bar in the lookback is the top of the scale, as in `rsi`.
+  if (fall === 0) return 100;
+  return result(100 - 100 / (1 + rise / fall));
+}
+
+/** `mfi(len)` as a tail. */
+export function mfiTail(len = 14): Tail<Bar, Value> {
+  return tailOf((state, bar: Bar) => mfiStep(state, '', bar, len));
+}
+
+/** `mfi(len)` over a run of bars. */
+export function mfi(bars: readonly Bar[], len = 14): Value[] {
+  return fold(mfiTail(len), bars);
+}
+
+/**
+ * `eom(len)`: how far price moved per unit of volume, from bar `len`.
+ *
+ * The midpoint's move, times the bar's range, over the volume traded, then
+ * averaged over the lookback. The midpoint move needs the previous bar, so the
+ * average's lookback starts at bar 1 and the first reading is at bar `len`.
+ *
+ * **No scaling constant.** Implementations of this reading usually multiply by
+ * a large divisor whose only job is to bring the number into a readable range,
+ * and they do not agree on it. `stdlib.md` section 7 declares `eom(len = 14)`
+ * with no such argument, so there is none here and the reading is the quantity
+ * itself. That leaves it very small on a liquid instrument, which is recorded
+ * as a gap in the specification rather than papered over with a constant this
+ * library invented.
+ */
+export function eomStep(
+  state: StateRecord,
+  key: string,
+  bar: Bar,
+  len: number | null,
+): Value {
+  const travelled = changeStep(state, `${key}c`, hl2(bar), 1);
+  let term: Value = NONE;
+  if (
+    isPresent(travelled) &&
+    isPresent(bar.high) &&
+    isPresent(bar.low) &&
+    isPresent(bar.volume) &&
+    bar.volume !== 0
+  ) {
+    term = result((travelled * (bar.high - bar.low)) / bar.volume);
+  }
+  return smaStep(state, `${key}q`, term, len);
+}
+
+/** `eom(len)` as a tail. */
+export function eomTail(len = 14): Tail<Bar, Value> {
+  return tailOf((state, bar: Bar) => eomStep(state, '', bar, len));
+}
+
+/** `eom(len)` over a run of bars. */
+export function eom(bars: readonly Bar[], len = 14): Value[] {
+  return fold(eomTail(len), bars);
+}
+
+/** `forceIndex(len)`: change times volume, smoothed, from bar `len`. */
+export function forceIndexStep(
+  state: StateRecord,
+  key: string,
+  bar: Bar,
+  len: number | null,
+): Value {
+  const moved = changeStep(state, `${key}c`, bar.close, 1);
+  const force = isPresent(moved) && isPresent(bar.volume) ? result(moved * bar.volume) : NONE;
+  return emaStep(state, `${key}e`, force, len);
+}
+
+/** `forceIndex(len)` as a tail. */
+export function forceIndexTail(len = 13): Tail<Bar, Value> {
+  return tailOf((state, bar: Bar) => forceIndexStep(state, '', bar, len));
+}
+
+/** `forceIndex(len)` over a run of bars. */
+export function forceIndex(bars: readonly Bar[], len = 13): Value[] {
+  return fold(forceIndexTail(len), bars);
+}
+
+/** `relativeVolume(len)`: this bar's volume over its own recent average, from bar `len - 1`. */
+export function relativeVolumeStep(
+  state: StateRecord,
+  key: string,
+  volume: Value,
+  len: number | null,
+): Value {
+  const mean = smaStep(state, `${key}q`, volume, len);
+  if (!isPresent(mean) || !isPresent(volume) || mean === 0) return NONE;
+  return result(volume / mean);
+}
+
+/** `relativeVolume(len)` as a tail. */
+export function relativeVolumeTail(len = 20): Tail<Bar, Value> {
+  return tailOf((state, bar: Bar) => relativeVolumeStep(state, '', bar.volume, len));
+}
+
+/** `relativeVolume(len)` over a run of bars. */
+export function relativeVolume(bars: readonly Bar[], len = 20): Value[] {
+  return fold(relativeVolumeTail(len), bars);
+}

package/src/core/stdlib/volume/index.ts

@@ -0,0 +1,43 @@
+export {
+  ad,
+  adOsc,
+  adOscStep,
+  adOscTail,
+  adStep,
+  adTail,
+  moneyFlow,
+  obv,
+  obvStep,
+  obvTail,
+  pvt,
+  pvtStep,
+  pvtTail,
+} from './accumulation.js';
+
+export {
+  cmf,
+  cmfStep,
+  cmfTail,
+  eom,
+  eomStep,
+  eomTail,
+  forceIndex,
+  forceIndexStep,
+  forceIndexTail,
+  mfi,
+  mfiStep,
+  mfiTail,
+  relativeVolume,
+  relativeVolumeStep,
+  relativeVolumeTail,
+} from './flow.js';
+
+export type { Anchored } from './weighted.js';
+export {
+  vwap,
+  vwapAnchor,
+  vwapAnchorStep,
+  vwapAnchorTail,
+  vwapStep,
+  vwapTail,
+} from './weighted.js';

package/src/core/stdlib/volume/weighted.ts

@@ -0,0 +1,101 @@
+/**
+ * `vwap` and `vwapAnchor`: the volume weighted average price since an anchor.
+ *
+ * `stdlib.md` section 7 writes `vwap(src)` and says it resets at the start of
+ * each trading session **as the instrument defines it**, not at midnight,
+ * because the session is what the number means. Where a session starts follows
+ * from the instrument's own trading hours and not from any arithmetic here, so
+ * this library takes the anchor as a flag per bar and an engine derives it.
+ * `vwapAnchor` is therefore the whole of the calculation and `vwap` is that
+ * calculation with the session's first bars passed in.
+ *
+ * The running totals are carried rather than rebuilt, because that is the
+ * definition: a volume weighted average since an anchor is a pair of running
+ * totals, and a lookback over the bars since the anchor would be a different
+ * quantity with a different value.
+ */
+import type { Series, StateRecord, Tail, Value } from '../values/index.js';
+import { NONE, flag, fold, isPresent, result, slot, tailOf } from '../values/index.js';
+
+/** A bar's source price, its volume, and whether the average restarts here. */
+export interface Anchored {
+  readonly src: Value;
+  readonly volume: Value;
+  readonly reset: boolean;
+}
+
+/**
+ * `vwapAnchor(src, resetWhen)`: from the first bar `resetWhen` is true.
+ *
+ * The bar the condition holds on is the first bar of the new average, not the
+ * last bar of the old one. Absent before the condition has ever been true,
+ * because there is no anchor to measure from and zero would read as a price.
+ */
+export function vwapAnchorStep(state: StateRecord, key: string, input: Anchored): Value {
+  const flowKey = `${key}f`;
+  const tradedKey = `${key}v`;
+  const anchoredKey = `${key}a`;
+  if (input.reset) {
+    state[flowKey] = 0;
+    state[tradedKey] = 0;
+    state[anchoredKey] = true;
+  }
+  if (!flag(state, anchoredKey)) return NONE;
+  if (!isPresent(input.src) || !isPresent(input.volume)) return NONE;
+  const flow = slot(state, flowKey, 0) + input.src * input.volume;
+  const traded = slot(state, tradedKey, 0) + input.volume;
+  state[flowKey] = flow;
+  state[tradedKey] = traded;
+  if (traded === 0) return NONE;
+  return result(flow / traded);
+}
+
+/** `vwapAnchor(src, resetWhen)` as a tail. */
+export function vwapAnchorTail(): Tail<Anchored, Value> {
+  return tailOf((state, input: Anchored) => vwapAnchorStep(state, '', input));
+}
+
+/** `vwapAnchor(src, resetWhen)` over whole series. */
+export function vwapAnchor(
+  src: Series,
+  volume: Series,
+  resetWhen: readonly boolean[],
+): Value[] {
+  return fold(
+    vwapAnchorTail(),
+    src.map((value, index) => ({
+      src: value,
+      volume: volume[index] ?? NONE,
+      reset: resetWhen[index] === true,
+    })),
+  );
+}
+
+/**
+ * `vwap(src)`: the same average anchored to the session, from the session's
+ * first bar.
+ *
+ * `sessionStart` is the engine's answer to "does a new trading session begin on
+ * this bar", read off the instrument's stated trading hours, which is why it
+ * is an argument rather than something derived from the timestamps here. On a daily or longer interval every bar is its own
+ * session, so every bar is an anchor and the result equals `src`; the compiler
+ * emits warning OS8006 saying so, which is a compile-time matter and not this
+ * library's.
+ */
+export function vwapTail(): Tail<Anchored, Value> {
+  return vwapAnchorTail();
+}
+
+/** `vwap(src)` as a step, which is `vwapAnchor` anchored to the session. */
+export function vwapStep(state: StateRecord, key: string, input: Anchored): Value {
+  return vwapAnchorStep(state, key, input);
+}
+
+/** `vwap(src)` over whole series. */
+export function vwap(
+  src: Series,
+  volume: Series,
+  sessionStart: readonly boolean[],
+): Value[] {
+  return vwapAnchor(src, volume, sessionStart);
+}

package/src/core/version/index.ts

@@ -0,0 +1 @@
+export { COMPILED_FORMAT_VERSION, VERSION } from './version.generated.js';

package/src/core/version/version.generated.ts

@@ -0,0 +1,15 @@
+// Generated by scripts/generate-version.mjs. Do not edit.
+//
+// VERSION comes from package.json and COMPILED_FORMAT_VERSION from
+// spec/compiled-program.md, so neither can drift from the thing it names.
+
+/** This build's package version. The release refuses to publish unless the tag, the manifest and this agree. */
+export const VERSION = "0.2.0";
+
+/**
+ * The compiled program format this compiler emits.
+ *
+ * Deliberately not the package version. An engine written by somebody else
+ * targets this number, and it moves only when the format does.
+ */
+export const COMPILED_FORMAT_VERSION = "1.1";