openalgo-script 0.1.0-alpha.1 → 0.2.0

package/src/core/engine/library/series.ts

@@ -0,0 +1,236 @@
+/**
+ * The series calls that hold state, `stdlib.md` sections 4 and 9.
+ *
+ * **Every number here is the numeric library's.** The arithmetic is computed
+ * under `src/core/stdlib`, which depends on nothing else in the repository and
+ * is tested against reference vectors on its own, and this file is the wiring
+ * that hands it the arguments a call site supplied and the state region the
+ * machine holds for that call site. A second arrangement of the same formula
+ * here would be a second accumulation order waiting to drift, and
+ * `compiled-program.md` section 8.3 makes that a release blocker rather than a
+ * tidiness problem.
+ *
+ * That is possible because every function in the numeric library is written as
+ * a step over a state region rather than as a closure: 2.11 requires a region
+ * to be snapshottable by a mechanical copy, and a closure is not one. The key
+ * each step is given is its address inside the region, so a study built from
+ * three others keeps one flat record rather than a tree of them.
+ */
+import type { Direction } from '../../stdlib/index.js';
+import {
+  avgSkipStep,
+  barsSinceStep,
+  changeStep,
+  correlationStep,
+  countPresentStep,
+  countStep,
+  covarianceStep,
+  crossStep,
+  cumStep,
+  emaStep,
+  extremeStep,
+  hmaStep,
+  historyStep,
+  percentRankStep,
+  percentileStep,
+  pivotStep,
+  rmaStep,
+  rocStep,
+  runStep,
+  smaStep,
+  sumSkipStep,
+  sumStep,
+  valueWhenStep,
+  wmaStep,
+} from '../../stdlib/index.js';
+import { boolAt, lengthAt, numberAt } from './binding.js';
+import type { ManifestEntry } from './binding.js';
+import { stateful } from './state.js';
+
+/** The three crossing tests, which differ only in which direction counts. */
+function crossing(name: string, direction: Direction): ManifestEntry {
+  return stateful(name, 'a b', (ctx, args) =>
+    crossStep(ctx.state, '', { a: numberAt(args, 0), b: numberAt(args, 1) }, direction),
+  );
+}
+
+export const SERIES_ENTRIES: readonly ManifestEntry[] = [
+  stateful('sma', 'src len', (ctx, args) =>
+    smaStep(ctx.state, 'q', numberAt(args, 0), lengthAt(ctx, 'sma', 'len', args, 1)),
+  ),
+  stateful('ema', 'src len', (ctx, args) =>
+    emaStep(ctx.state, 'e', numberAt(args, 0), lengthAt(ctx, 'ema', 'len', args, 1)),
+  ),
+  stateful('rma', 'src len', (ctx, args) =>
+    rmaStep(ctx.state, 'r', numberAt(args, 0), lengthAt(ctx, 'rma', 'len', args, 1)),
+  ),
+  stateful('wma', 'src len', (ctx, args) =>
+    wmaStep(ctx.state, 'w', numberAt(args, 0), lengthAt(ctx, 'wma', 'len', args, 1)),
+  ),
+  stateful('hma', 'src len', (ctx, args) =>
+    hmaStep(ctx.state, '', numberAt(args, 0), lengthAt(ctx, 'hma', 'len', args, 1)),
+  ),
+
+  stateful('highest', 'src len', (ctx, args) =>
+    extremeStep(
+      ctx.state,
+      'q',
+      numberAt(args, 0),
+      lengthAt(ctx, 'highest', 'len', args, 1),
+      true,
+      false,
+    ),
+  ),
+  stateful('lowest', 'src len', (ctx, args) =>
+    extremeStep(
+      ctx.state,
+      'q',
+      numberAt(args, 0),
+      lengthAt(ctx, 'lowest', 'len', args, 1),
+      false,
+      false,
+    ),
+  ),
+  stateful('highestBars', 'src len', (ctx, args) =>
+    extremeStep(
+      ctx.state,
+      'q',
+      numberAt(args, 0),
+      lengthAt(ctx, 'highestBars', 'len', args, 1),
+      true,
+      true,
+    ),
+  ),
+  stateful('lowestBars', 'src len', (ctx, args) =>
+    extremeStep(
+      ctx.state,
+      'q',
+      numberAt(args, 0),
+      lengthAt(ctx, 'lowestBars', 'len', args, 1),
+      false,
+      true,
+    ),
+  ),
+
+  stateful('change', 'src', (ctx, args) => changeStep(ctx.state, 'c', numberAt(args, 0), 1)),
+  stateful('change', 'src len', (ctx, args) =>
+    changeStep(ctx.state, 'c', numberAt(args, 0), lengthAt(ctx, 'change', 'len', args, 1)),
+  ),
+  stateful('mom', 'src len', (ctx, args) =>
+    changeStep(ctx.state, 'c', numberAt(args, 0), lengthAt(ctx, 'mom', 'len', args, 1)),
+  ),
+  stateful('roc', 'src len', (ctx, args) =>
+    rocStep(ctx.state, '', numberAt(args, 0), lengthAt(ctx, 'roc', 'len', args, 1)),
+  ),
+  stateful('history', 'src n', (ctx, args) =>
+    historyStep(ctx.state, 'h', numberAt(args, 0), lengthAt(ctx, 'history', 'n', args, 1)),
+  ),
+
+  stateful('sum', 'src len', (ctx, args) =>
+    sumStep(ctx.state, 'q', numberAt(args, 0), lengthAt(ctx, 'sum', 'len', args, 1)),
+  ),
+  stateful('sumSkip', 'src len', (ctx, args) =>
+    sumSkipStep(ctx.state, 'q', numberAt(args, 0), lengthAt(ctx, 'sumSkip', 'len', args, 1)),
+  ),
+  stateful('avgSkip', 'src len', (ctx, args) =>
+    avgSkipStep(ctx.state, 'q', numberAt(args, 0), lengthAt(ctx, 'avgSkip', 'len', args, 1)),
+  ),
+  stateful('countPresent', 'src len', (ctx, args) =>
+    countPresentStep(
+      ctx.state,
+      'q',
+      numberAt(args, 0),
+      lengthAt(ctx, 'countPresent', 'len', args, 1),
+    ),
+  ),
+  stateful('count', 'cond len', (ctx, args) =>
+    countStep(ctx.state, 'q', boolAt(args, 0), lengthAt(ctx, 'count', 'len', args, 1)),
+  ),
+
+  stateful('cum', 'src', (ctx, args) => cumStep(ctx.state, 't', numberAt(args, 0))),
+
+  stateful('rising', 'src len', (ctx, args) =>
+    runStep(ctx.state, 'q', numberAt(args, 0), lengthAt(ctx, 'rising', 'len', args, 1), true),
+  ),
+  stateful('falling', 'src len', (ctx, args) =>
+    runStep(ctx.state, 'q', numberAt(args, 0), lengthAt(ctx, 'falling', 'len', args, 1), false),
+  ),
+
+  crossing('crossUp', 'up'),
+  crossing('crossDown', 'down'),
+  crossing('cross', 'either'),
+
+  stateful('barsSince', 'cond', (ctx, args) => barsSinceStep(ctx.state, 's', boolAt(args, 0))),
+
+  // An absent occurrence is the most recent hit, which is what the declared
+  // default of the call says.
+  stateful('valueWhen', 'cond src occurrence', (ctx, args) =>
+    valueWhenStep(
+      ctx.state,
+      'v',
+      { cond: boolAt(args, 0), src: numberAt(args, 1) },
+      numberAt(args, 2) ?? 0,
+    ),
+  ),
+
+  stateful('median', 'src len', (ctx, args) =>
+    percentileStep(ctx.state, 'q', numberAt(args, 0), lengthAt(ctx, 'median', 'len', args, 1), 50),
+  ),
+  stateful('percentile', 'src len p', (ctx, args) =>
+    percentileStep(
+      ctx.state,
+      'q',
+      numberAt(args, 0),
+      lengthAt(ctx, 'percentile', 'len', args, 1),
+      numberAt(args, 2),
+    ),
+  ),
+
+  stateful('pivotHigh', 'src left right', (ctx, args) =>
+    pivotStep(
+      ctx.state,
+      'q',
+      numberAt(args, 0),
+      lengthAt(ctx, 'pivotHigh', 'left', args, 1),
+      lengthAt(ctx, 'pivotHigh', 'right', args, 2),
+      true,
+    ),
+  ),
+  stateful('pivotLow', 'src left right', (ctx, args) =>
+    pivotStep(
+      ctx.state,
+      'q',
+      numberAt(args, 0),
+      lengthAt(ctx, 'pivotLow', 'left', args, 1),
+      lengthAt(ctx, 'pivotLow', 'right', args, 2),
+      false,
+    ),
+  ),
+
+  stateful('percentRank', 'src len', (ctx, args) =>
+    percentRankStep(
+      ctx.state,
+      'q',
+      numberAt(args, 0),
+      lengthAt(ctx, 'percentRank', 'len', args, 1),
+    ),
+  ),
+
+  stateful('correlation', 'a b len', (ctx, args) =>
+    correlationStep(
+      ctx.state,
+      '',
+      { a: numberAt(args, 0), b: numberAt(args, 1) },
+      lengthAt(ctx, 'correlation', 'len', args, 2),
+    ),
+  ),
+
+  stateful('covariance', 'a b len', (ctx, args) =>
+    covarianceStep(
+      ctx.state,
+      '',
+      { a: numberAt(args, 0), b: numberAt(args, 1) },
+      lengthAt(ctx, 'covariance', 'len', args, 2),
+    ),
+  ),
+];

package/src/core/engine/library/state.ts

@@ -0,0 +1,47 @@
+/**
+ * The seam between the machine and the numeric library.
+ *
+ * A stateful call is three things put together: a state region the machine
+ * holds for the call site, the arguments the call site pushed, and the facts
+ * about the bar that are not arithmetic. The arithmetic itself is not here and
+ * is not anywhere else in the engine: every formula is computed under
+ * `src/core/stdlib`, and `series.ts` and `studies.ts` are tables of call sites
+ * pointing at it.
+ *
+ * **The region is the library's own shape.** `compiled-program.md` 2.11
+ * requires a region to be snapshottable by a mechanical copy, so it is a flat
+ * record rather than a closure, and the numeric library is written against that
+ * record rather than against variables of its own. That is what lets one
+ * implementation serve a chart advancing a bar at a time and a library call
+ * folded over a whole series: there is no second arrangement of any formula for
+ * the two to drift apart in. `copyState` is the mechanical copy, and `memory.ts`
+ * is its only caller.
+ */
+import type { Gap } from '../../stdlib/index.js';
+import { entry } from './binding.js';
+import type { CallContext, ManifestEntry } from './binding.js';
+
+export type { StateField, StateRecord, StateSlot } from '../../stdlib/index.js';
+export { copyState } from '../../stdlib/index.js';
+
+/** An entry for a call that keeps a region between bars. */
+export function stateful(
+  name: string,
+  params: string,
+  call: ManifestEntry['call'],
+): ManifestEntry {
+  return entry(name, params, call, { state: true });
+}
+
+/**
+ * What a true range needs, taken from the bar the machine is executing.
+ *
+ * The previous close comes from the bar rather than from the region on purpose:
+ * it is a fact about the dataset, the same for every call on the bar, and a
+ * call inside a branch does not see every bar, so the close of the bar that
+ * call last ran on would be a different number.
+ */
+export function gapAt(ctx: CallContext): Gap {
+  const { high, low, previousClose, index } = ctx.bar;
+  return { high, low, previousClose, isFirstBar: index === 0 };
+}

package/src/core/engine/library/studies.ts

@@ -0,0 +1,150 @@
+/**
+ * The studies: range, deviation, bands, the strength reading and the two trend
+ * calls.
+ *
+ * **Every number here is the numeric library's**, for the reason `series.ts`
+ * sets out beside the same wiring. Each study is a composition there and
+ * nothing more, which is the point of writing the library as steps over a state
+ * region: `atr` is `rma` over true range, `rsi` is two `rma`s over the two
+ * halves of a change, `bollinger` is `sma` and `stdev`, and `macd` is three
+ * `ema`s. A composition keeps one accumulation order rather than inventing a
+ * second, and it is why the warmups in `stdlib.md` compose instead of being
+ * asserted.
+ *
+ * The several calls that return more than one number return an array, which is
+ * the language's own way of handing back a trio (`stdlib.md` sections 5 and 6),
+ * so the value they push is a fresh reference into the heap on every bar.
+ */
+import {
+  atrStep,
+  bbPercentStep,
+  bbWidthStep,
+  bollingerStep,
+  donchianStep,
+  macdStep,
+  natrStep,
+  rsiStep,
+  stdevStep,
+  supertrendStep,
+  trueRangeOf,
+  varianceStep,
+} from '../../stdlib/index.js';
+import { boolAt, entry, lengthAt, multi, numberAt } from './binding.js';
+import type { ManifestEntry } from './binding.js';
+import { gapAt, stateful } from './state.js';
+
+export const STUDY_ENTRIES: readonly ManifestEntry[] = [
+  entry('trueRange', '', (ctx) => trueRangeOf(gapAt(ctx), true)),
+
+  stateful('atr', 'len', (ctx, args) =>
+    atrStep(ctx.state, '', gapAt(ctx), lengthAt(ctx, 'atr', 'len', args, 0)),
+  ),
+
+  stateful('natr', 'len', (ctx, args) =>
+    natrStep(
+      ctx.state,
+      '',
+      gapAt(ctx),
+      ctx.bar.close,
+      lengthAt(ctx, 'natr', 'len', args, 0),
+    ),
+  ),
+
+  stateful('stdev', 'src len sample', (ctx, args) =>
+    stdevStep(
+      ctx.state,
+      'q',
+      numberAt(args, 0),
+      lengthAt(ctx, 'stdev', 'len', args, 1),
+      boolAt(args, 2) === true,
+    ),
+  ),
+
+  stateful('variance', 'src len sample', (ctx, args) =>
+    varianceStep(
+      ctx.state,
+      'q',
+      numberAt(args, 0),
+      lengthAt(ctx, 'variance', 'len', args, 1),
+      boolAt(args, 2) === true,
+    ),
+  ),
+
+  stateful('rsi', 'src len', (ctx, args) =>
+    rsiStep(ctx.state, '', numberAt(args, 0), lengthAt(ctx, 'rsi', 'len', args, 1)),
+  ),
+
+  stateful('bollinger', 'src len mult', (ctx, args) =>
+    multi(
+      ctx,
+      bollingerStep(
+        ctx.state,
+        '',
+        numberAt(args, 0),
+        lengthAt(ctx, 'bollinger', 'len', args, 1),
+        numberAt(args, 2),
+      ),
+    ),
+  ),
+
+  stateful('bbWidth', 'src len mult', (ctx, args) =>
+    bbWidthStep(
+      ctx.state,
+      '',
+      numberAt(args, 0),
+      lengthAt(ctx, 'bbWidth', 'len', args, 1),
+      numberAt(args, 2),
+    ),
+  ),
+
+  stateful('bbPercent', 'src len mult', (ctx, args) =>
+    bbPercentStep(
+      ctx.state,
+      '',
+      numberAt(args, 0),
+      lengthAt(ctx, 'bbPercent', 'len', args, 1),
+      numberAt(args, 2),
+    ),
+  ),
+
+  stateful('macd', 'src fast slow signal', (ctx, args) =>
+    multi(
+      ctx,
+      macdStep(
+        ctx.state,
+        '',
+        numberAt(args, 0),
+        lengthAt(ctx, 'macd', 'fast', args, 1),
+        lengthAt(ctx, 'macd', 'slow', args, 2),
+        lengthAt(ctx, 'macd', 'signal', args, 3),
+      ),
+    ),
+  ),
+
+  stateful('supertrend', 'factor atrLen', (ctx, args) =>
+    multi(
+      ctx,
+      supertrendStep(
+        ctx.state,
+        '',
+        gapAt(ctx),
+        ctx.bar.close,
+        numberAt(args, 0),
+        lengthAt(ctx, 'supertrend', 'atrLen', args, 1),
+      ),
+    ),
+  ),
+
+  stateful('donchian', 'len', (ctx, args) =>
+    multi(
+      ctx,
+      donchianStep(
+        ctx.state,
+        '',
+        ctx.bar.high,
+        ctx.bar.low,
+        lengthAt(ctx, 'donchian', 'len', args, 0),
+      ),
+    ),
+  ),
+];