openalgo-script 0.1.0-alpha.0 → 0.2.0

package/src/core/stdlib/values/lookback.ts

@@ -0,0 +1,198 @@
+/**
+ * The rolling lookback and the seeded recurrence: the two pieces every length
+ * taking function in this library is built from.
+ *
+ * "Lookback" rather than the other word for the same thing: that one names a
+ * browser global, and the layering check refuses it anywhere in the text of a
+ * file under `src/core`, which is what keeps this tier runnable in a worker and
+ * on a server rather than only in a page.
+ *
+ * Both are held in a state region (`region.ts`) rather than in local variables,
+ * so one implementation serves a library call folded over a series and an
+ * engine advancing a chart a bar at a time.
+ *
+ * **The accumulation order is part of the contract.** Binary64 addition is not
+ * associative, so a sum has a value and an order, and two engines that add the
+ * same lookback two ways disagree in the last bits. This library fixes one
+ * order and uses it everywhere:
+ *
+ *   **oldest bar first, newest bar last, in index order.**
+ *
+ * That is the order `compiled-program.md` section 8.2 gives for iteration, and
+ * it is the order a reader assumes when they see a lookback written down.
+ *
+ * **The sum is taken fresh over the lookback on every bar.** The tempting
+ * alternative, carrying a running total and subtracting the value that leaves,
+ * is O(1) instead of O(len) but it is a different number: the error in a
+ * running total accumulates without bound over forty thousand bars, and it is
+ * not bit-identical to a fresh sum, which `compiled-program.md` section 8.3
+ * refuses outright. A lookback costs `len` additions per bar, which is bounded by
+ * the length the script asked for rather than by how much history is loaded,
+ * and that is the property a live chart actually needs.
+ */
+import type { StateField, StateRecord } from './region.js';
+import { newState } from './region.js';
+import type { Value } from './value.js';
+import { NONE, isLength, isPresent, result } from './value.js';
+
+/** A fixed length view of the most recent bars. */
+export interface Lookback {
+  /** Advance by one bar. */
+  push(value: Value): void;
+  /** True once `len` bars have gone by, present or not: this is warmup. */
+  filled(): boolean;
+  /** True when the lookback is filled and every bar in it has a value. */
+  complete(): boolean;
+  /** The value `back` bars ago, 0 being the bar just pushed. */
+  at(back: number): Value;
+  /** How many bars of the lookback have a value. */
+  presentCount(): number;
+  /** The sum over the lookback, oldest first, absent unless the lookback is complete. */
+  sum(): Value;
+  /** The sum over the lookback with absent bars left out, absent when it is not filled. */
+  sumPresent(): Value;
+  /** The arithmetic mean over the lookback, absent unless the lookback is complete. */
+  mean(): Value;
+}
+
+/**
+ * A lookback of `len` bars, held in a region under `key`.
+ *
+ * A length outside its contract yields a lookback that never fills, so every
+ * function built on it returns absence rather than a number computed from a
+ * nonsense length. See `isLength` for why that is absence and not a diagnostic.
+ */
+export function ring(record: StateRecord, key: string, len: number | null): Lookback {
+  const size = len !== null && isLength(len) ? len : 0;
+  const bars = `${key}:q`;
+  const nextKey = `${key}:n`;
+  const seenKey = `${key}:s`;
+  const held = record[bars];
+  let items: StateField[];
+  if (Array.isArray(held) && held.length === size) {
+    items = held;
+  } else {
+    items = new Array<StateField>(size).fill(NONE);
+    record[bars] = items;
+    record[nextKey] = 0;
+    record[seenKey] = 0;
+  }
+
+  const count = (name: string): number => {
+    const value = record[name];
+    return typeof value === 'number' ? value : 0;
+  };
+  const index = (back: number): number => {
+    const from = count(nextKey) - 1 - back;
+    return ((from % size) + size) % size;
+  };
+
+  const lookback: Lookback = {
+    push(value: Value): void {
+      if (size === 0) return;
+      items[count(nextKey)] = value;
+      const next = count(nextKey) + 1;
+      record[nextKey] = next === size ? 0 : next;
+      if (count(seenKey) < size) record[seenKey] = count(seenKey) + 1;
+    },
+
+    filled(): boolean {
+      return size > 0 && count(seenKey) === size;
+    },
+
+    at(back: number): Value {
+      if (size === 0 || back < 0 || back >= size) return NONE;
+      const value = items[index(back)];
+      return typeof value === 'number' ? value : NONE;
+    },
+
+    presentCount(): number {
+      let counted = 0;
+      for (let back = size - 1; back >= 0; back -= 1) {
+        if (isPresent(lookback.at(back))) counted += 1;
+      }
+      return counted;
+    },
+
+    complete(): boolean {
+      return lookback.filled() && lookback.presentCount() === size;
+    },
+
+    sum(): Value {
+      if (!lookback.complete()) return NONE;
+      let total = 0;
+      // Oldest first: `back` counts down to the bar just pushed.
+      for (let back = size - 1; back >= 0; back -= 1) {
+        total += lookback.at(back) as number;
+      }
+      return result(total);
+    },
+
+    sumPresent(): Value {
+      if (!lookback.filled()) return NONE;
+      let total = 0;
+      for (let back = size - 1; back >= 0; back -= 1) {
+        const value = lookback.at(back);
+        if (isPresent(value)) total += value;
+      }
+      return result(total);
+    },
+
+    mean(): Value {
+      const total = lookback.sum();
+      return isPresent(total) ? result(total / size) : NONE;
+    },
+  };
+
+  return lookback;
+}
+
+/** A lookback of `len` bars in a region of its own, for a caller that has none. */
+export function makeLookback(len: number): Lookback {
+  return ring(newState(), 'q', len);
+}
+
+/** One step of a recurrence, from the previous running value and this bar's. */
+export type Recurrence = (previous: number, value: number) => number;
+
+/**
+ * Seeded smoothing: the mean of the first complete lookback, then one step per
+ * bar.
+ *
+ * The seed lookback is complete only when it holds `len` present values, so an
+ * average taken over another study's output starts counting at that study's
+ * first value rather than at bar 0. That is what makes the warmups of
+ * `stdlib.md` compose, and it is why `ema(sma(close, 10), 10)` is absent until
+ * bar 18 rather than bar 9.
+ *
+ * A hole in the input freezes the recurrence: an absent bar after seeding
+ * produces an absent bar out and leaves the running value untouched, so the
+ * next present bar continues from where the last one left off. The alternatives
+ * are worse: consuming absence as zero would drag the average toward nothing,
+ * and re-seeding would let one missing bar restart a two hundred bar average.
+ */
+export function smoothed(
+  record: StateRecord,
+  key: string,
+  len: number | null,
+  value: Value,
+  step: Recurrence,
+): Value {
+  const seed = ring(record, `${key}~`, len);
+  const runningKey = `${key}:r`;
+  const startedKey = `${key}:o`;
+  if (record[startedKey] !== true) {
+    seed.push(value);
+    const mean = seed.mean();
+    if (!isPresent(mean)) return NONE;
+    record[startedKey] = true;
+    record[runningKey] = mean;
+    return result(mean);
+  }
+  if (!isPresent(value)) return NONE;
+  const previous = record[runningKey];
+  if (typeof previous !== 'number') return NONE;
+  const next = step(previous, value);
+  record[runningKey] = next;
+  return result(next);
+}

package/src/core/stdlib/values/region.ts

@@ -0,0 +1,86 @@
+/**
+ * What a stateful function remembers between bars, and why it is a record
+ * rather than a closure.
+ *
+ * A closure is the obvious way to hold a running average and it is the wrong
+ * way here. `compiled-program.md` 2.11 requires a state region to be
+ * **snapshottable by a mechanical copy**: an engine copies and restores one
+ * without knowing which function owns it, because the rollback and replay rules
+ * of section 6 apply to every region at once. Nothing can copy a closure
+ * without knowing what is inside it, and rebuilding one by replaying its inputs
+ * is what 6.2 refuses in as many words: an engine does not re-seed an average
+ * from history, it puts back the record it copied.
+ *
+ * So a region is a flat record of numbers, booleans, strings and fixed length
+ * queues, and `copyState` is the mechanical copy. Every function in this
+ * library is written against one, and the tail form in `tail.ts` is the same
+ * step over a region nobody else can reach. That is what lets the one
+ * implementation serve both a library call folded over a series and an engine
+ * advancing a chart one bar at a time.
+ *
+ * Several functions share one region by taking different key prefixes, which is
+ * how a study built from three others keeps one flat record rather than a tree
+ * of them.
+ */
+
+/** One field of a state region. A queue is the one compound form 2.11 allows. */
+export type StateField = number | boolean | string | null;
+
+/** What a single key holds. */
+export type StateSlot = StateField | StateField[];
+
+/** A state region: a flat record, copyable without knowing what owns it. */
+export type StateRecord = Record<string, StateSlot | undefined>;
+
+/** A region with nothing in it yet, which is what bar 0 finds. */
+export function newState(): StateRecord {
+  return {};
+}
+
+/** The mechanical copy 2.11 asks for: one level, with queues cloned. */
+export function copyState(record: StateRecord): StateRecord {
+  const out: StateRecord = {};
+  for (const key of Object.keys(record)) {
+    const value = record[key];
+    out[key] = Array.isArray(value) ? [...value] : value;
+  }
+  return out;
+}
+
+/** A number held in a region, with a default for the bar it is first read on. */
+export function slot(record: StateRecord, key: string, fallback: number): number {
+  const value = record[key];
+  return typeof value === 'number' ? value : fallback;
+}
+
+/** A condition held in a region, false until something sets it. */
+export function flag(record: StateRecord, key: string): boolean {
+  return record[key] === true;
+}
+
+/**
+ * A queue held in a region, created on the bar it is first read on.
+ *
+ * The caller keeps it bounded. A queue that grew with the dataset would not be
+ * copyable in the sense 2.11 requires.
+ */
+export function queue(record: StateRecord, key: string): StateField[] {
+  const held = record[key];
+  if (Array.isArray(held)) return held;
+  const made: StateField[] = [];
+  record[key] = made;
+  return made;
+}
+
+/**
+ * A number held in a region that may honestly have none yet.
+ *
+ * `slot` answers with a fallback, which is what a running total wants. A study
+ * that remembers the previous bar's high wants the other answer: absence until
+ * a present value has been put there, so the bar after a hole is treated as the
+ * bar after a hole rather than as one following a zero.
+ */
+export function held(record: StateRecord, key: string): number | null {
+  const value = record[key];
+  return typeof value === 'number' ? value : null;
+}

package/src/core/stdlib/values/tail.ts

@@ -0,0 +1,58 @@
+/**
+ * The tail path, and why the whole-series form is defined in terms of it.
+ *
+ * A live chart recomputes on every tick. A study that rescans its whole history
+ * to produce one more bar makes a terminal slow in proportion to how much
+ * history the trader has loaded, and nobody notices until the day somebody
+ * scrolls back five years.
+ *
+ * So every function here is written once, as a tail: a small piece of state
+ * plus a step that takes this bar's input and returns this bar's output. The
+ * whole-series form is that step folded over the series and nothing else.
+ *
+ * That is not a convenience. `compiled-program.md` section 8.3 requires the two
+ * to agree to the last bit, and the only way to be sure of that is to have one
+ * implementation rather than two that are meant to match. A second batch
+ * implementation, however carefully written, is a second accumulation order
+ * waiting to drift.
+ *
+ * The state lives in a region (`region.ts`) rather than in the closure's own
+ * variables, so the same step an engine advances over a live chart is the step
+ * this folds over a series. `tailOf` is the whole of the tail form: a region
+ * nobody else can reach, and the step applied to it.
+ */
+import type { StateRecord } from './region.js';
+import { newState } from './region.js';
+
+/**
+ * One bar in, one bar out, with everything the function remembers held inside.
+ *
+ * A tail is stateful and single use: it is fed bars in order, from bar 0, and
+ * each call advances it by one bar.
+ */
+export interface Tail<In, Out> {
+  /** Advance by one bar and return that bar's output. */
+  next(input: In): Out;
+}
+
+/** A tail's step applied to a whole series, oldest bar first. */
+export function fold<In, Out>(tail: Tail<In, Out>, inputs: readonly In[]): Out[] {
+  const out: Out[] = [];
+  for (const input of inputs) out.push(tail.next(input));
+  return out;
+}
+
+/**
+ * A tail from a step: a private region, advanced one bar per call.
+ *
+ * The region is the same shape an engine hands a stateful call, so the function
+ * underneath does not know which of the two is driving it.
+ */
+export function tailOf<In, Out>(step: (state: StateRecord, input: In) => Out): Tail<In, Out> {
+  const state = newState();
+  return {
+    next(input: In): Out {
+      return step(state, input);
+    },
+  };
+}

package/src/core/stdlib/values/value.ts

@@ -0,0 +1,82 @@
+/**
+ * The absent value, and the two rules every result in this library obeys.
+ *
+ * Absence is a value of its own and is never a number. A warmup bar is absent,
+ * and anything computed from an absent value is absent. Returning zero instead
+ * would draw a line along the axis that looks exactly like data, and a reader
+ * has no way to tell the two apart.
+ *
+ * Not-a-number is not used as the sentinel, for the reason `compiled-program.md`
+ * section 3.4 gives: it would propagate through arithmetic by accident, which
+ * is the right answer for some operators and the wrong one for others, and it
+ * would turn an absence test into a floating point comparison.
+ */
+
+/** A number, or absence. */
+export type Value = number | null;
+
+/** A series is one value per bar, oldest first. */
+export type Series = readonly Value[];
+
+/**
+ * A condition, one per bar: true, false, or absent.
+ *
+ * Absence is its own answer here too. A comparison against a warmup bar is
+ * absent rather than false, and the functions that consume a condition say
+ * which of the two they treat it as.
+ */
+export type Flag = boolean | null;
+
+/** A series of conditions, one per bar, oldest first. */
+export type Flags = readonly Flag[];
+
+/** Absence, written `none` in a script. */
+export const NONE: Value = null;
+
+/** True when the value is present, narrowing it to a number. */
+export function isPresent(value: Value): value is number {
+  return value !== null;
+}
+
+/**
+ * A computed number, made safe to return.
+ *
+ * Two rules from `compiled-program.md` section 3.1, applied at every value this
+ * library hands back:
+ *
+ * - A result with no finite real value is absent, not an infinity and not a
+ *   not-a-number. `log(0)` and a division by zero inside a ratio study are the
+ *   everyday cases.
+ * - Negative zero is normalised to positive zero, so nothing downstream can
+ *   observe the sign of a zero and two engines cannot differ over it.
+ */
+export function result(x: number): Value {
+  if (!Number.isFinite(x)) return NONE;
+  return x === 0 ? 0 : x;
+}
+
+/**
+ * Element `index` of a series, or absence when the index falls off either end.
+ *
+ * Reading before the start of the dataset is absent rather than an error, which
+ * is what makes `history` and every lookback function fall out of one rule
+ * instead of a special case each.
+ */
+export function at(values: Series, index: number): Value {
+  const value = values[index];
+  return value === undefined ? NONE : value;
+}
+
+/**
+ * Whether a length argument is inside its contract: a whole number of one or
+ * more, per `stdlib.md` section 2.5.
+ *
+ * This library raises nothing. A length outside the contract is OS3004 at
+ * compile time when it is a literal and OS4003 at run time when it is computed,
+ * and both are raised before a call reaches here. The functions below use this
+ * only as a backstop, and a backstop returns absence rather than a guess: a
+ * wrong number drawn on a chart is worse than a gap.
+ */
+export function isLength(length: number): boolean {
+  return Number.isInteger(length) && length >= 1;
+}

package/src/core/stdlib/volatility/bands.ts

@@ -0,0 +1,178 @@
+/**
+ * The channel studies: `bollinger`, its two readings, `keltner` and `donchian`.
+ *
+ * Each returns an array holding this bar's outputs, in the order its entry in
+ * `stdlib.md` documents. **The array itself is never absent and never changes
+ * length**, per section 2.3: each element carries its own warmup and is absent
+ * until it is reached. An array that grew as warmup completed would make an
+ * index an out-of-range error at the left edge of a chart and nowhere else.
+ */
+import type { Bar, Series, StateRecord, Tail, Value } from '../values/index.js';
+import { NONE, at, fold, isPresent, result, tailOf } from '../values/index.js';
+import type { MaType } from '../averages/index.js';
+import { maStep, smaStep } from '../averages/index.js';
+import { extremeStep } from '../series/index.js';
+
+import { stdevStep } from './deviation.js';
+import type { Gap } from './range.js';
+import { atrStep, gapOf } from './range.js';
+
+/** `bollinger(src, len, mult)`: `[basis, upper, lower]`, all from bar `len - 1`. */
+export function bollingerStep(
+  state: StateRecord,
+  key: string,
+  value: Value,
+  len: number | null,
+  mult: number | null,
+): Value[] {
+  const middle = smaStep(state, `${key}q`, value, len);
+  const deviation = stdevStep(state, `${key}d`, value, len, false);
+  if (!isPresent(middle) || !isPresent(deviation) || mult === null) return [middle, NONE, NONE];
+  return [middle, result(middle + mult * deviation), result(middle - mult * deviation)];
+}
+
+/** `bollinger(src, len, mult)` as a tail. */
+export function bollingerTail(len = 20, mult = 2): Tail<Value, Value[]> {
+  return tailOf((state, value: Value) => bollingerStep(state, '', value, len, mult));
+}
+
+/** `bollinger(src, len, mult)` over a whole series. */
+export function bollinger(src: Series, len = 20, mult = 2): Value[][] {
+  return fold(bollingerTail(len, mult), src);
+}
+
+/** `bbWidth(src, len, mult)`: band width over the basis, from bar `len - 1`. */
+export function bbWidthStep(
+  state: StateRecord,
+  key: string,
+  value: Value,
+  len: number | null,
+  mult: number | null,
+): Value {
+  const trio = bollingerStep(state, key, value, len, mult);
+  const basis = at(trio, 0);
+  const upper = at(trio, 1);
+  const lower = at(trio, 2);
+  if (!isPresent(basis) || !isPresent(upper) || !isPresent(lower)) return NONE;
+  if (basis === 0) return NONE;
+  return result((upper - lower) / basis);
+}
+
+/** `bbWidth(src, len, mult)` as a tail. */
+export function bbWidthTail(len = 20, mult = 2): Tail<Value, Value> {
+  return tailOf((state, value: Value) => bbWidthStep(state, '', value, len, mult));
+}
+
+/** `bbWidth(src, len, mult)` over a whole series. */
+export function bbWidth(src: Series, len = 20, mult = 2): Value[] {
+  return fold(bbWidthTail(len, mult), src);
+}
+
+/** `bbPercent(src, len, mult)`: where price sits between the bands, from bar `len - 1`. */
+export function bbPercentStep(
+  state: StateRecord,
+  key: string,
+  value: Value,
+  len: number | null,
+  mult: number | null,
+): Value {
+  const trio = bollingerStep(state, key, value, len, mult);
+  const upper = at(trio, 1);
+  const lower = at(trio, 2);
+  if (!isPresent(value) || !isPresent(upper) || !isPresent(lower)) return NONE;
+  const span = upper - lower;
+  if (span === 0) return NONE;
+  return result((value - lower) / span);
+}
+
+/** `bbPercent(src, len, mult)` as a tail. */
+export function bbPercentTail(len = 20, mult = 2): Tail<Value, Value> {
+  return tailOf((state, value: Value) => bbPercentStep(state, '', value, len, mult));
+}
+
+/** `bbPercent(src, len, mult)` over a whole series. */
+export function bbPercent(src: Series, len = 20, mult = 2): Value[] {
+  return fold(bbPercentTail(len, mult), src);
+}
+
+/**
+ * `keltner(len, mult, atrLen, maType)`: `[basis, upper, lower]`, all from bar
+ * `max(len, atrLen) - 1`.
+ *
+ * The same picture as `bollinger` built from average true range instead of
+ * deviation, so the rails widen on how far the instrument travels rather than
+ * on how dispersed its closes were.
+ */
+export function keltnerStep(
+  state: StateRecord,
+  key: string,
+  gap: Gap,
+  close: Value,
+  volume: Value,
+  len: number | null,
+  mult: number | null,
+  atrLen: number | null,
+  maType: MaType | null,
+): Value[] {
+  const middle = maStep(state, `${key}m`, { src: close, volume }, len, maType);
+  const width = atrStep(state, `${key}r`, gap, atrLen);
+  if (!isPresent(middle) || !isPresent(width) || mult === null) return [middle, NONE, NONE];
+  return [middle, result(middle + mult * width), result(middle - mult * width)];
+}
+
+/** `keltner(len, mult, atrLen, maType)` as a tail. */
+export function keltnerTail(
+  len = 20,
+  mult = 2,
+  atrLen = 10,
+  maType: MaType = 'ema',
+): Tail<Bar, Value[]> {
+  return tailOf((state, bar: Bar) =>
+    keltnerStep(
+      state,
+      '',
+      gapOf(state, 'g', bar),
+      bar.close,
+      bar.volume,
+      len,
+      mult,
+      atrLen,
+      maType,
+    ),
+  );
+}
+
+/** `keltner(len, mult, atrLen, maType)` over a run of bars. */
+export function keltner(
+  bars: readonly Bar[],
+  len = 20,
+  mult = 2,
+  atrLen = 10,
+  maType: MaType = 'ema',
+): Value[][] {
+  return fold(keltnerTail(len, mult, atrLen, maType), bars);
+}
+
+/** `donchian(len)`: `[upper, basis, lower]`, all from bar `len - 1`. */
+export function donchianStep(
+  state: StateRecord,
+  key: string,
+  high: Value,
+  low: Value,
+  len: number | null,
+): Value[] {
+  const upper = extremeStep(state, `${key}h`, high, len, true, false);
+  const lower = extremeStep(state, `${key}l`, low, len, false, false);
+  if (!isPresent(upper) || !isPresent(lower)) return [upper, NONE, lower];
+  return [upper, result((upper + lower) / 2), lower];
+}
+
+/** `donchian(len)` as a tail. */
+export function donchianTail(len = 20): Tail<Bar, Value[]> {
+  return tailOf((state, bar: Bar) => donchianStep(state, '', bar.high, bar.low, len));
+}
+
+/** `donchian(len)` over a run of bars. */
+export function donchian(bars: readonly Bar[], len = 20): Value[][] {
+  return fold(donchianTail(len), bars);
+}