openalgo-script 0.1.0-alpha.1 → 0.4.0

package/src/core/stdlib/index.ts

@@ -0,0 +1,400 @@
+/**
+ * The numeric library: the calculations of `stdlib.md` sections 4 to 9.
+ *
+ * **It depends on nothing else in this repository.** Not the lexer, not the
+ * checker, not the engine. A moving average is a moving average, and keeping
+ * this tier independently testable is what makes a gate on it worth anything:
+ * a number that matches a reference implementation here matches it because the
+ * arithmetic is right, not because the rest of the compiler agreed with itself.
+ *
+ * Three properties hold across everything below, and each has a file that
+ * explains it at the place it is implemented:
+ *
+ * - **Absence is not zero and never becomes zero** (`values/value.ts`). A
+ *   warmup bar is absent, anything computed from an absent value is absent, and
+ *   the three functions that deliberately ignore absent bars say so in their
+ *   names.
+ * - **The accumulation order is part of the contract** (`values/lookback.ts`).
+ *   Binary64 addition is not associative, so two engines that sum a lookback two
+ *   ways disagree in the last bits. Lookbacks are summed fresh, oldest bar first,
+ *   and where a formula could be arranged two ways the file that implements it
+ *   says which way and why.
+ * - **Every function is written once, as a step over a state region**
+ *   (`values/region.ts`): a flat record and a step that takes one bar. The tail
+ *   form is that step over a region of its own and the whole-series form is the
+ *   tail folded, so the live path and the history path cannot disagree, because
+ *   there is only one of them. The record rather than a closure is what lets an
+ *   engine drive the same step: `compiled-program.md` 2.11 requires a region to
+ *   be copyable by something that does not know what is in it, and that is the
+ *   reason there is no second copy of any of this arithmetic in the engine.
+ *
+ * **What this library does not do: raise.** A length outside its contract is
+ * OS3004 at compile time or OS4003 at run time, raised before a call reaches
+ * here. Nothing below throws, so nothing below can throw a diagnostic without a
+ * code.
+ *
+ * Two arguments appear here that no script writes, and neither is a numeric
+ * fact: the tick size `roundToTick` rounds to, which a host states, and the
+ * per-bar flag that says where a trading session begins for `vwap`, which an
+ * engine derives from the instrument's session hours. An engine supplies
+ * both.
+ */
+
+export type {
+  Bar,
+  Flag,
+  Flags,
+  Lookback,
+  Recurrence,
+  Series,
+  StateField,
+  StateRecord,
+  StateSlot,
+  Tail,
+  Value,
+} from './values/index.js';
+export {
+  NONE,
+  at,
+  copyState,
+  flag,
+  fold,
+  held,
+  hl2,
+  hlc3,
+  hlcc4,
+  isLength,
+  isPresent,
+  makeLookback,
+  newState,
+  ohlc4,
+  queue,
+  result,
+  ring,
+  slot,
+  smoothed,
+  tailOf,
+} from './values/index.js';
+
+export {
+  E,
+  PI,
+  abs,
+  acos,
+  asin,
+  atan,
+  atan2,
+  boolOf,
+  ceil,
+  clamp,
+  cos,
+  exp,
+  floor,
+  hypot,
+  isNone,
+  log,
+  log2,
+  log10,
+  max,
+  min,
+  mod,
+  orElse,
+  pow,
+  round,
+  roundHalfAway,
+  roundTo,
+  roundToStep,
+  roundToTick,
+  sign,
+  sin,
+  sqrt,
+  tan,
+  toDegrees,
+  toRadians,
+  trunc,
+} from './maths/index.js';
+
+export type { Boundary, Civil, DateField } from './calendar/index.js';
+export {
+  civilAt,
+  dateField,
+  dateOfDay,
+  dayNumber,
+  dayOfYearOf,
+  fieldsIn,
+  instantFrom,
+  instantOf,
+  isKnownZone,
+  offsetAt,
+  renderPattern,
+  sameDay,
+  startOf,
+  utcInstantOf,
+  weekOfYearOf,
+  weekdayOfDay,
+} from './calendar/index.js';
+
+export type { MaType, Weighted } from './averages/index.js';
+export {
+  alma,
+  almaStep,
+  almaTail,
+  dema,
+  demaStep,
+  demaTail,
+  ema,
+  emaStep,
+  emaTail,
+  hma,
+  hmaStep,
+  hmaTail,
+  isMaType,
+  linreg,
+  linregStep,
+  linregTail,
+  ma,
+  maStep,
+  maTail,
+  rma,
+  rmaStep,
+  rmaTail,
+  sma,
+  smaStep,
+  smaTail,
+  swma,
+  swmaStep,
+  swmaTail,
+  tema,
+  temaStep,
+  temaTail,
+  vwma,
+  vwmaStep,
+  vwmaTail,
+  wma,
+  wmaStep,
+  wmaTail,
+} from './averages/index.js';
+
+export type { Direction, Occasion, Pair } from './series/index.js';
+export {
+  avgSkip,
+  avgSkipStep,
+  avgSkipTail,
+  barsSince,
+  barsSinceStep,
+  barsSinceTail,
+  change,
+  changeStep,
+  changeTail,
+  correlation,
+  correlationStep,
+  correlationTail,
+  count,
+  countPresent,
+  countPresentStep,
+  countPresentTail,
+  countStep,
+  countTail,
+  covariance,
+  covarianceStep,
+  covarianceTail,
+  cross,
+  crossDown,
+  crossDownTail,
+  crossEitherTail,
+  crossStep,
+  crossUp,
+  crossUpTail,
+  cum,
+  cumStep,
+  cumTail,
+  extremeStep,
+  falling,
+  fallingTail,
+  highest,
+  highestBars,
+  highestBarsTail,
+  highestTail,
+  history,
+  historyStep,
+  historyTail,
+  lowest,
+  lowestBars,
+  lowestBarsTail,
+  lowestTail,
+  median,
+  medianTail,
+  percentRank,
+  percentRankStep,
+  percentRankTail,
+  percentile,
+  percentileStep,
+  percentileTail,
+  pivotHigh,
+  pivotHighTail,
+  pivotLow,
+  pivotLowTail,
+  pivotStep,
+  rising,
+  risingTail,
+  runStep,
+  sum,
+  sumSkip,
+  sumSkipStep,
+  sumSkipTail,
+  sumStep,
+  sumTail,
+  valueWhen,
+  valueWhenStep,
+  valueWhenTail,
+} from './series/index.js';
+
+export type { Gap } from './volatility/index.js';
+export {
+  atr,
+  atrStep,
+  atrTail,
+  bbPercent,
+  bbPercentStep,
+  bbPercentTail,
+  bbWidth,
+  bbWidthStep,
+  bbWidthTail,
+  bollinger,
+  bollingerStep,
+  bollingerTail,
+  chop,
+  chopStep,
+  chopTail,
+  donchian,
+  donchianStep,
+  donchianTail,
+  gapOf,
+  gapTrueRange,
+  gapTrueRangeStep,
+  gapTrueRangeTail,
+  hv,
+  hvStep,
+  hvTail,
+  keltner,
+  keltnerStep,
+  keltnerTail,
+  meanDeviation,
+  meanDeviationStep,
+  meanDeviationTail,
+  natr,
+  natrStep,
+  natrTail,
+  stdev,
+  stdevStep,
+  stdevTail,
+  trueRange,
+  trueRangeOf,
+  trueRangeTail,
+  variance,
+  varianceStep,
+  varianceTail,
+} from './volatility/index.js';
+
+export {
+  awesomeOsc,
+  awesomeOscStep,
+  awesomeOscTail,
+  cci,
+  cciStep,
+  cciTail,
+  cmo,
+  cmoStep,
+  cmoTail,
+  dpo,
+  dpoStep,
+  dpoTail,
+  macd,
+  macdStep,
+  macdTail,
+  mom,
+  momTail,
+  ppo,
+  ppoStep,
+  ppoTail,
+  roc,
+  rocStep,
+  rocTail,
+  rsi,
+  rsiStep,
+  rsiTail,
+  stoch,
+  stochRsi,
+  stochRsiStep,
+  stochRsiTail,
+  stochStep,
+  stochTail,
+  trix,
+  trixStep,
+  trixTail,
+  tsi,
+  tsiStep,
+  tsiTail,
+  ultimateOsc,
+  ultimateOscStep,
+  ultimateOscTail,
+  williamsR,
+  williamsRStep,
+  williamsRTail,
+} from './momentum/index.js';
+
+export {
+  adx,
+  adxStep,
+  adxTail,
+  aroon,
+  aroonStep,
+  aroonTail,
+  ichimoku,
+  ichimokuStep,
+  ichimokuTail,
+  psar,
+  psarStep,
+  psarTail,
+  supertrend,
+  supertrendStep,
+  supertrendTail,
+} from './trend/index.js';
+
+export type { Anchored } from './volume/index.js';
+export {
+  ad,
+  adOsc,
+  adOscStep,
+  adOscTail,
+  adStep,
+  adTail,
+  cmf,
+  cmfStep,
+  cmfTail,
+  eom,
+  eomStep,
+  eomTail,
+  forceIndex,
+  forceIndexStep,
+  forceIndexTail,
+  mfi,
+  mfiStep,
+  mfiTail,
+  moneyFlow,
+  obv,
+  obvStep,
+  obvTail,
+  pvt,
+  pvtStep,
+  pvtTail,
+  relativeVolume,
+  relativeVolumeStep,
+  relativeVolumeTail,
+  vwap,
+  vwapAnchor,
+  vwapAnchorStep,
+  vwapAnchorTail,
+  vwapStep,
+  vwapTail,
+} from './volume/index.js';

package/src/core/stdlib/maths/arithmetic.ts

@@ -0,0 +1,74 @@
+/**
+ * The bare arithmetic of `stdlib.md` section 8.1.
+ *
+ * None of these has a warmup: they read this bar's values only, so each
+ * produces a value on bar 0 whenever its arguments do. Every one is absent when
+ * any argument is absent, and every result goes through `result`, so a value
+ * with no finite real answer is absence rather than an infinity.
+ */
+import type { Value } from '../values/index.js';
+import { NONE, isPresent, result } from '../values/index.js';
+
+/** `abs(x)`: magnitude without sign. */
+export function abs(x: Value): Value {
+  return isPresent(x) ? result(Math.abs(x)) : NONE;
+}
+
+/** `sign(x)`: -1, 0 or 1. */
+export function sign(x: Value): Value {
+  if (!isPresent(x)) return NONE;
+  if (x > 0) return 1;
+  if (x < 0) return -1;
+  return 0;
+}
+
+/** `min(a, b)`: the smaller of two. */
+export function min(a: Value, b: Value): Value {
+  if (!isPresent(a) || !isPresent(b)) return NONE;
+  return result(a < b ? a : b);
+}
+
+/** `max(a, b)`: the larger of two. */
+export function max(a: Value, b: Value): Value {
+  if (!isPresent(a) || !isPresent(b)) return NONE;
+  return result(a > b ? a : b);
+}
+
+/** `clamp(x, lo, hi)`: `x` held inside a range. */
+export function clamp(x: Value, lo: Value, hi: Value): Value {
+  if (!isPresent(x) || !isPresent(lo) || !isPresent(hi)) return NONE;
+  if (x < lo) return result(lo);
+  if (x > hi) return result(hi);
+  return result(x);
+}
+
+/**
+ * `mod(a, b)`: `a - b * floor(a / b)`, the floored remainder, whose sign
+ * follows `b`.
+ *
+ * Written out rather than described because "the modulo" names two different
+ * functions in common use. This is the floored one and the `%` operator is the
+ * truncated one: `mod(-7, 3)` is 2 where `-7 % 3` is -1. The two agree for
+ * every positive `b`, which is every use that wraps an index or a bar count.
+ * `mod(a, 0)` is absent, on the rule that a result with no finite real value is
+ * absent.
+ */
+export function mod(a: Value, b: Value): Value {
+  if (!isPresent(a) || !isPresent(b) || b === 0) return NONE;
+  return result(a - b * Math.floor(a / b));
+}
+
+/** True when the value is absent. */
+export function isNone(x: Value): boolean {
+  return !isPresent(x);
+}
+
+/** `x` when present, `fallback` when absent. */
+export function orElse(x: Value, fallback: Value): Value {
+  return isPresent(x) ? x : fallback;
+}
+
+/** `toBool(x)`: absence to false, a bool to itself. Numbers are a type error. */
+export function boolOf(x: boolean | null): boolean {
+  return x === null ? false : x;
+}

package/src/core/stdlib/maths/elementary.ts

@@ -0,0 +1,124 @@
+/**
+ * Square root, the logarithms, the powers and the trigonometry.
+ *
+ * **A gap, stated here rather than discovered later.**
+ * `compiled-program.md` section 8.3 requires that the transcendental functions
+ * not use the platform's own maths library, because a platform implementation
+ * is correct to within an ulp or so and differs between platforms in the last
+ * bit, which this project has declared a release blocker. It names the portable
+ * reference algorithm as living in the library manifest. **That manifest does
+ * not exist yet**, so there is nothing to implement against, and the functions
+ * below call the host until it does. Everything in this file except `sqrt` is
+ * therefore portable in value but not yet guaranteed in the last bit.
+ *
+ * `sqrt` is the exception and is not affected: IEEE-754 requires it to be
+ * correctly rounded, so every conforming platform returns the same bits.
+ *
+ * The consequence is worth stating plainly, because it decides what is safe to
+ * gate on today. Of the five gate studies, EMA, RSI, MACD, Bollinger Bands and
+ * Supertrend, four use only addition, subtraction, multiplication and division,
+ * and Bollinger Bands adds `sqrt`. None of them reaches this file's uncertain
+ * half. The functions that do are `alma` (exp), `hv` (log) and `chop` (log10).
+ */
+import type { Value } from '../values/index.js';
+import { NONE, isPresent, result } from '../values/index.js';
+
+/**
+ * `sqrt(x)`: square root, absent below zero.
+ *
+ * Correctly rounded on every conforming platform, so this one is bit-identical
+ * everywhere without a portable implementation of its own.
+ */
+export function sqrt(x: Value): Value {
+  if (!isPresent(x) || x < 0) return NONE;
+  return result(Math.sqrt(x));
+}
+
+/** `pow(x, y)`: absent where the result is not a finite real. */
+export function pow(x: Value, y: Value): Value {
+  if (!isPresent(x) || !isPresent(y)) return NONE;
+  return result(Math.pow(x, y));
+}
+
+/** `exp(x)`: e to the power x. */
+export function exp(x: Value): Value {
+  return isPresent(x) ? result(Math.exp(x)) : NONE;
+}
+
+/** `log(x)`: natural logarithm, absent at or below zero. */
+export function log(x: Value): Value {
+  if (!isPresent(x) || x <= 0) return NONE;
+  return result(Math.log(x));
+}
+
+/** `log10(x)`: base ten logarithm, absent at or below zero. */
+export function log10(x: Value): Value {
+  if (!isPresent(x) || x <= 0) return NONE;
+  return result(Math.log10(x));
+}
+
+/** `math.log2(x)`: base two logarithm, absent at or below zero. */
+export function log2(x: Value): Value {
+  if (!isPresent(x) || x <= 0) return NONE;
+  return result(Math.log2(x));
+}
+
+/** The circle constant. */
+export const PI: number = Math.PI;
+
+/** The base of the natural logarithm. */
+export const E: number = Math.E;
+
+/** `math.hypot(x, y)`: `sqrt(x * x + y * y)` without intermediate overflow. */
+export function hypot(x: Value, y: Value): Value {
+  if (!isPresent(x) || !isPresent(y)) return NONE;
+  return result(Math.hypot(x, y));
+}
+
+/** `math.toDegrees(x)`: radians to degrees. */
+export function toDegrees(x: Value): Value {
+  return isPresent(x) ? result((x * 180) / Math.PI) : NONE;
+}
+
+/** `math.toRadians(x)`: degrees to radians. */
+export function toRadians(x: Value): Value {
+  return isPresent(x) ? result((x * Math.PI) / 180) : NONE;
+}
+
+/** `math.sin(x)`: sine of an angle in radians. */
+export function sin(x: Value): Value {
+  return isPresent(x) ? result(Math.sin(x)) : NONE;
+}
+
+/** `math.cos(x)`: cosine. */
+export function cos(x: Value): Value {
+  return isPresent(x) ? result(Math.cos(x)) : NONE;
+}
+
+/** `math.tan(x)`: tangent. */
+export function tan(x: Value): Value {
+  return isPresent(x) ? result(Math.tan(x)) : NONE;
+}
+
+/** `math.asin(x)`: inverse sine, absent outside -1 to 1. */
+export function asin(x: Value): Value {
+  if (!isPresent(x) || x < -1 || x > 1) return NONE;
+  return result(Math.asin(x));
+}
+
+/** `math.acos(x)`: inverse cosine, absent outside -1 to 1. */
+export function acos(x: Value): Value {
+  if (!isPresent(x) || x < -1 || x > 1) return NONE;
+  return result(Math.acos(x));
+}
+
+/** `math.atan(x)`: inverse tangent. */
+export function atan(x: Value): Value {
+  return isPresent(x) ? result(Math.atan(x)) : NONE;
+}
+
+/** `math.atan2(y, x)`: angle of a vector, correct in all four quadrants. */
+export function atan2(y: Value, x: Value): Value {
+  if (!isPresent(y) || !isPresent(x)) return NONE;
+  return result(Math.atan2(y, x));
+}

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

@@ -0,0 +1,43 @@
+export {
+  abs,
+  boolOf,
+  clamp,
+  isNone,
+  max,
+  min,
+  mod,
+  orElse,
+  sign,
+} from './arithmetic.js';
+
+export {
+  ceil,
+  floor,
+  round,
+  roundHalfAway,
+  roundTo,
+  roundToStep,
+  roundToTick,
+  trunc,
+} from './rounding.js';
+
+export {
+  E,
+  PI,
+  acos,
+  asin,
+  atan,
+  atan2,
+  cos,
+  exp,
+  hypot,
+  log,
+  log2,
+  log10,
+  pow,
+  sin,
+  sqrt,
+  tan,
+  toDegrees,
+  toRadians,
+} from './elementary.js';

package/src/core/stdlib/maths/rounding.ts

@@ -0,0 +1,78 @@
+/**
+ * Rounding, and the one rule that decides every case.
+ *
+ * **Halves go away from zero, never to even.** `stdlib.md` section 8.1 fixes it
+ * there and the reason is legibility: a price rounded for display should agree
+ * with what a trader would write down, and round-half-to-even surprises people
+ * at exactly the values that matter. Fixing it also means two engines cannot
+ * differ by one tick.
+ *
+ * The implementation does not add a half and take the floor. That is the usual
+ * shortcut and it is wrong for the value just below a half, where adding 0.5
+ * rounds up to the next representable number before the floor ever runs. The
+ * fractional part is compared instead, which has no such case.
+ */
+import type { Value } from '../values/index.js';
+import { NONE, isPresent, result } from '../values/index.js';
+
+/** The nearest whole number, halves away from zero. */
+export function roundHalfAway(x: number): number {
+  const below = Math.floor(x);
+  const fraction = x - below;
+  if (fraction > 0.5) return below + 1;
+  if (fraction < 0.5) return below;
+  // Exactly a half. Away from zero: upward above zero, and `below` already is
+  // the downward answer for a negative, since floor(-2.5) is -3.
+  return x > 0 ? below + 1 : below;
+}
+
+/** `round(x)`: to the nearest whole number, halves away from zero. */
+export function round(x: Value): Value {
+  return isPresent(x) ? result(roundHalfAway(x)) : NONE;
+}
+
+/**
+ * `round(x, decimals)`: to a fixed number of decimals, halves away from zero.
+ *
+ * A digit count is a whole number of zero or more; anything else is OS3004 or
+ * OS4003 before the call reaches here, and absence is the backstop.
+ */
+export function roundTo(x: Value, decimals: number): Value {
+  if (!isPresent(x)) return NONE;
+  if (!Number.isInteger(decimals) || decimals < 0) return NONE;
+  const scale = Math.pow(10, decimals);
+  return result(roundHalfAway(x * scale) / scale);
+}
+
+/** `floor(x)`: toward negative infinity. */
+export function floor(x: Value): Value {
+  return isPresent(x) ? result(Math.floor(x)) : NONE;
+}
+
+/** `ceil(x)`: toward positive infinity. */
+export function ceil(x: Value): Value {
+  return isPresent(x) ? result(Math.ceil(x)) : NONE;
+}
+
+/** `trunc(x)`: toward zero. */
+export function trunc(x: Value): Value {
+  return isPresent(x) ? result(Math.trunc(x)) : NONE;
+}
+
+/** `roundToStep(x, step)`: to the nearest multiple of `step`. */
+export function roundToStep(x: Value, step: Value): Value {
+  if (!isPresent(x) || !isPresent(step) || step <= 0) return NONE;
+  return result(roundHalfAway(x / step) * step);
+}
+
+/**
+ * `roundToTick(price)`: to the instrument's tick.
+ *
+ * Absent when the host supplied no tick size, rather than the price unrounded.
+ * Returning the input would produce an order price that looks rounded and is
+ * not, which is a defect nothing downstream can see.
+ */
+export function roundToTick(price: Value, tickSize: Value): Value {
+  if (!isPresent(tickSize) || tickSize <= 0) return NONE;
+  return roundToStep(price, tickSize);
+}