openalgo-script 0.1.0-alpha.0 → 0.2.0

package/src/core/stdlib/averages/exponential.ts

@@ -0,0 +1,119 @@
+/**
+ * The exponential family: `ema`, `rma`, `dema` and `tema`.
+ *
+ * All four share one seeding rule, which `stdlib.md` section 4 states for `ema`
+ * and then refers `rma` to: the average is seeded on bar `len - 1` with the
+ * simple average of those `len` values, and is absent before it. Seeding from
+ * bar 0 instead, which is common and cheaper, draws a line where there should
+ * be a gap and stays materially wrong until the seed decays away. The seeding
+ * itself is `smoothed` in `lookback.ts`, which every seeded average here and in
+ * the studies built on them goes through.
+ *
+ * **Two arrangements, deliberately.** `ema` steps as `value * k + prev * (1 - k)`
+ * and `rma` steps as `(prev * (len - 1) + value) / len`. Those are the same
+ * function in exact arithmetic and two different numbers in binary64, and each
+ * is the arrangement its name has always meant. Writing `rma` as a weight of
+ * `1 / len` in `ema`'s shape would disagree in the last bits with every
+ * implementation of the classic oscillators, which is precisely what this
+ * project treats as a release blocker.
+ */
+import type { Series, StateRecord, Tail, Value } from '../values/index.js';
+import { NONE, fold, isPresent, result, smoothed, tailOf } from '../values/index.js';
+
+/** `ema(src, len)`: exponential mean, weight `2 / (len + 1)`, from bar `len - 1`. */
+export function emaStep(
+  state: StateRecord,
+  key: string,
+  value: Value,
+  len: number | null,
+): Value {
+  if (len === null) return NONE;
+  const weight = 2 / (len + 1);
+  const rest = 1 - weight;
+  return smoothed(state, key, len, value, (previous, next) => next * weight + previous * rest);
+}
+
+/** `ema(src, len)` as a tail. */
+export function emaTail(len: number): Tail<Value, Value> {
+  return tailOf((state, value: Value) => emaStep(state, 'e', value, len));
+}
+
+/** `ema(src, len)` over a whole series. */
+export function ema(src: Series, len: number): Value[] {
+  return fold(emaTail(len), src);
+}
+
+/** `rma(src, len)`: the smoothing the classic oscillators use, from bar `len - 1`. */
+export function rmaStep(
+  state: StateRecord,
+  key: string,
+  value: Value,
+  len: number | null,
+): Value {
+  if (len === null) return NONE;
+  return smoothed(state, key, len, value, (previous, next) => (previous * (len - 1) + next) / len);
+}
+
+/** `rma(src, len)` as a tail. */
+export function rmaTail(len: number): Tail<Value, Value> {
+  return tailOf((state, value: Value) => rmaStep(state, 'r', value, len));
+}
+
+/** `rma(src, len)` over a whole series. */
+export function rma(src: Series, len: number): Value[] {
+  return fold(rmaTail(len), src);
+}
+
+/**
+ * `dema(src, len)`: `2 * ema - ema(ema)`, from bar `2 * len - 2`.
+ *
+ * The second average is fed the first one's output, absences and all, so it
+ * seeds on the first `len` values the first average produced. That is where the
+ * declared warmup comes from rather than being asserted alongside it.
+ */
+export function demaStep(
+  state: StateRecord,
+  key: string,
+  value: Value,
+  len: number | null,
+): Value {
+  const once = emaStep(state, `${key}a`, value, len);
+  const twice = emaStep(state, `${key}b`, once, len);
+  if (!isPresent(once) || !isPresent(twice)) return NONE;
+  return result(2 * once - twice);
+}
+
+/** `dema(src, len)` as a tail. */
+export function demaTail(len: number): Tail<Value, Value> {
+  return tailOf((state, value: Value) => demaStep(state, 'e', value, len));
+}
+
+/** `dema(src, len)` over a whole series. */
+export function dema(src: Series, len: number): Value[] {
+  return fold(demaTail(len), src);
+}
+
+/** `tema(src, len)`: `3 * e1 - 3 * e2 + e3`, from bar `3 * len - 3`. */
+export function temaStep(
+  state: StateRecord,
+  key: string,
+  value: Value,
+  len: number | null,
+): Value {
+  const once = emaStep(state, `${key}a`, value, len);
+  const twice = emaStep(state, `${key}b`, once, len);
+  const thrice = emaStep(state, `${key}c`, twice, len);
+  if (!isPresent(once) || !isPresent(twice) || !isPresent(thrice)) return NONE;
+  // Left to right, as written: 3 * e1, less 3 * e2, plus e3.
+  return result(3 * once - 3 * twice + thrice);
+}
+
+/** `tema(src, len)` as a tail. */
+export function temaTail(len: number): Tail<Value, Value> {
+  return tailOf((state, value: Value) => temaStep(state, 'e', value, len));
+}
+
+/** `tema(src, len)` over a whole series. */
+export function tema(src: Series, len: number): Value[] {
+  return fold(temaTail(len), src);
+}

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

@@ -0,0 +1,45 @@
+export type { Weighted } from './simple.js';
+export {
+  sma,
+  smaStep,
+  smaTail,
+  swma,
+  swmaStep,
+  swmaTail,
+  vwma,
+  vwmaStep,
+  vwmaTail,
+  wma,
+  wmaStep,
+  wmaTail,
+} from './simple.js';
+
+export {
+  dema,
+  demaStep,
+  demaTail,
+  ema,
+  emaStep,
+  emaTail,
+  rma,
+  rmaStep,
+  rmaTail,
+  tema,
+  temaStep,
+  temaTail,
+} from './exponential.js';
+
+export {
+  alma,
+  almaStep,
+  almaTail,
+  hma,
+  hmaStep,
+  hmaTail,
+  linreg,
+  linregStep,
+  linregTail,
+} from './shaped.js';
+
+export type { MaType } from './select.js';
+export { isMaType, ma, maStep, maTail } from './select.js';

package/src/core/stdlib/averages/select.ts

@@ -0,0 +1,71 @@
+/**
+ * `ma(src, len, type)`: one call whose shape a select input can switch.
+ *
+ * The point of it is that a study can offer its user a choice of average
+ * without the script branching six ways, and without the six branches each
+ * owning their own state. One call site, one state region, one line on the
+ * chart.
+ *
+ * The step takes a source paired with its volume because one of the types is
+ * volume weighted. A caller that will never select that type passes absence for
+ * the volume and loses nothing.
+ *
+ * **Each type keeps its own corner of the region.** The key carries the type
+ * name, so a run that switched type halfway would start the new average from
+ * its own warmup rather than from whatever the old one had left in the record.
+ */
+import type { Series, StateRecord, Tail, Value } from '../values/index.js';
+import { NONE, fold, tailOf } from '../values/index.js';
+
+import type { Weighted } from './simple.js';
+import { smaStep, vwmaStep, wmaStep } from './simple.js';
+import { emaStep, rmaStep } from './exponential.js';
+import { hmaStep } from './shaped.js';
+
+/** The averages `ma` can be switched to, as `stdlib.md` section 4 lists them. */
+export type MaType = 'sma' | 'ema' | 'wma' | 'rma' | 'hma' | 'vwma';
+
+const TYPES: readonly string[] = ['sma', 'ema', 'wma', 'rma', 'hma', 'vwma'];
+
+/** Whether a string names one of the six averages `ma` accepts. */
+export function isMaType(name: string | null): name is MaType {
+  return name !== null && TYPES.includes(name);
+}
+
+/**
+ * `ma(src, len, type)`, with the warmup of whichever type was named.
+ *
+ * An unrecognised type is absence throughout, not a silent fall back to the
+ * simple mean. A study that quietly drew a different average from the one its
+ * settings say would be wrong in a way nobody could see.
+ */
+export function maStep(
+  state: StateRecord,
+  key: string,
+  input: Weighted,
+  len: number | null,
+  type: MaType | null,
+): Value {
+  if (type === null) return NONE;
+  const mine = `${key}${type}`;
+  if (type === 'vwma') return vwmaStep(state, mine, input, len);
+  if (type === 'sma') return smaStep(state, mine, input.src, len);
+  if (type === 'ema') return emaStep(state, mine, input.src, len);
+  if (type === 'wma') return wmaStep(state, mine, input.src, len);
+  if (type === 'rma') return rmaStep(state, mine, input.src, len);
+  if (type === 'hma') return hmaStep(state, mine, input.src, len);
+  return NONE;
+}
+
+/** `ma(src, len, type)` as a tail. */
+export function maTail(len: number, type: MaType): Tail<Weighted, Value> {
+  return tailOf((state, input: Weighted) => maStep(state, 'q', input, len, type));
+}
+
+/** `ma(src, len, type)` over a whole series. */
+export function ma(src: Series, volume: Series, len: number, type: MaType): Value[] {
+  return fold(
+    maTail(len, type),
+    src.map((value, index) => ({ src: value, volume: volume[index] ?? NONE })),
+  );
+}

package/src/core/stdlib/averages/shaped.ts

@@ -0,0 +1,161 @@
+/**
+ * The averages with a shape to them: `hma`, `alma` and `linreg`.
+ *
+ * Each one is a weighted lookback like `wma`, and each accumulates oldest bar
+ * first, in index order, for the reason `lookback.ts` gives.
+ */
+import type { Series, StateRecord, Tail, Value } from '../values/index.js';
+import {
+  NONE,
+  fold,
+  isLength,
+  isPresent,
+  result,
+  ring,
+  tailOf,
+} from '../values/index.js';
+import { roundHalfAway } from '../maths/index.js';
+
+import { wmaStep } from './simple.js';
+
+/**
+ * `hma(src, len)`: from bar `len + round(sqrt(len)) - 2`.
+ *
+ * `wma` of twice the half length average less the full length one, smoothed
+ * again over the square root of the length.
+ *
+ * **The half length is not stated.** `stdlib.md` section 4 fixes the outer
+ * length as `round(sqrt(len))`, which the declared warmup confirms, and says
+ * nothing about the inner one. `floor(len / 2)` is used here, held at a minimum
+ * of 1 so a length of 1 or 2 still has a lookback, and the declared warmup holds
+ * for any inner length at or below `len`, so nothing in the warmup column
+ * settles it. This is recorded as a gap rather than presented as a reading.
+ */
+export function hmaStep(
+  state: StateRecord,
+  key: string,
+  value: Value,
+  len: number | null,
+): Value {
+  if (len === null) return NONE;
+  const half = Math.max(1, Math.floor(len / 2));
+  const outer = Math.max(1, roundHalfAway(Math.sqrt(len)));
+  const near = wmaStep(state, `${key}f`, value, half);
+  const far = wmaStep(state, `${key}s`, value, len);
+  const raw = isPresent(near) && isPresent(far) ? result(2 * near - far) : NONE;
+  return wmaStep(state, `${key}o`, raw, outer);
+}
+
+/** `hma(src, len)` as a tail. */
+export function hmaTail(len: number): Tail<Value, Value> {
+  return tailOf((state, value: Value) => hmaStep(state, '', value, len));
+}
+
+/** `hma(src, len)` over a whole series. */
+export function hma(src: Series, len: number): Value[] {
+  return fold(hmaTail(len), src);
+}
+
+/**
+ * `alma(src, len, offset, sigma)`: the Gaussian weighted mean, from bar `len - 1`.
+ *
+ * `offset` slides the kernel's peak between lag and smoothness and `sigma` sets
+ * how sharply it falls away.
+ *
+ * The kernel depends only on the position in the lookback, so it could be built
+ * once; it is rebuilt each bar instead, because the region 2.11 requires holds
+ * numbers and queues and not a cached array of weights, and a step that reads
+ * its own arguments every bar is the only form an engine can drive. The
+ * accumulation is over the lookback in index order either way, so the number is
+ * the same one.
+ */
+export function almaStep(
+  state: StateRecord,
+  key: string,
+  value: Value,
+  len: number | null,
+  offset: number | null,
+  sigma: number | null,
+): Value {
+  const lookback = ring(state, key, len);
+  lookback.push(value);
+  if (len === null || offset === null || sigma === null) return NONE;
+  if (!lookback.complete()) return NONE;
+  if (!(sigma > 0) || !isLength(len)) return NONE;
+  const peak = offset * (len - 1);
+  const spread = len / sigma;
+  const weights: number[] = [];
+  let norm = 0;
+  // Index order: position 0 is the oldest bar in the lookback.
+  for (let position = 0; position < len; position += 1) {
+    const gap = position - peak;
+    const weight = Math.exp(-(gap * gap) / (2 * spread * spread));
+    weights.push(weight);
+    norm += weight;
+  }
+  if (norm === 0) return NONE;
+  let total = 0;
+  for (let position = 0; position < len; position += 1) {
+    total += (lookback.at(len - 1 - position) as number) * (weights[position] as number);
+  }
+  return result(total / norm);
+}
+
+/** `alma(src, len, offset, sigma)` as a tail. */
+export function almaTail(len: number, offset = 0.85, sigma = 6): Tail<Value, Value> {
+  return tailOf((state, value: Value) => almaStep(state, 'q', value, len, offset, sigma));
+}
+
+/** `alma(src, len, offset, sigma)` over a whole series. */
+export function alma(src: Series, len: number, offset = 0.85, sigma = 6): Value[] {
+  return fold(almaTail(len, offset, sigma), src);
+}
+
+/**
+ * `linreg(src, len, offset)`: the least squares line through the last `len`
+ * points, read `offset` bars back along it, from bar `len - 1`.
+ *
+ * `x` runs 0 at the oldest bar of the lookback to `len - 1` at the current one,
+ * so the value at the current bar is `intercept + slope * (len - 1)` and a
+ * positive `offset` steps back down the line without refitting it.
+ *
+ * A length of 1 has no line through it: the normal equations are singular, and
+ * the answer is absence rather than the single point, because a line fitted to
+ * one point is not a fit.
+ */
+export function linregStep(
+  state: StateRecord,
+  key: string,
+  value: Value,
+  len: number | null,
+  offset: number | null,
+): Value {
+  const lookback = ring(state, key, len);
+  lookback.push(value);
+  if (len === null || offset === null || !lookback.complete()) return NONE;
+  // The x values are the same lookback every bar, so their sums are constants.
+  const sumX = ((len - 1) * len) / 2;
+  const sumXSquared = ((len - 1) * len * (2 * len - 1)) / 6;
+  const divisor = len * sumXSquared - sumX * sumX;
+  if (divisor === 0) return NONE;
+  let sumY = 0;
+  let sumXY = 0;
+  for (let position = 0; position < len; position += 1) {
+    const y = lookback.at(len - 1 - position) as number;
+    sumY += y;
+    sumXY += y * position;
+  }
+  const slope = (len * sumXY - sumX * sumY) / divisor;
+  const intercept = (sumY - slope * sumX) / len;
+  return result(intercept + slope * (len - 1 - offset));
+}
+
+/** `linreg(src, len, offset)` as a tail. */
+export function linregTail(len: number, offset = 0): Tail<Value, Value> {
+  return tailOf((state, value: Value) => linregStep(state, 'q', value, len, offset));
+}
+
+/** `linreg(src, len, offset)` over a whole series. */
+export function linreg(src: Series, len: number, offset = 0): Value[] {
+  return fold(linregTail(len, offset), src);
+}

package/src/core/stdlib/averages/simple.ts

@@ -0,0 +1,139 @@
+/**
+ * The lookback averages: `sma`, `wma`, `swma` and `vwma`.
+ *
+ * Each is a fresh accumulation over the lookback in index order, oldest bar
+ * first, for the reason `lookback.ts` sets out: a sum has an order as well as a
+ * value, and a running total that subtracts the bar leaving the lookback is a
+ * different number.
+ *
+ * Each is written once, as a step over a state region, and its tail is that
+ * step over a region of its own. An engine calls the same step against the
+ * region it holds for the call site, so there is no second arrangement of the
+ * arithmetic anywhere for the two to drift apart in.
+ */
+import type { Series, StateRecord, Tail, Value } from '../values/index.js';
+import { NONE, fold, isPresent, result, ring, tailOf } from '../values/index.js';
+
+/** A bar's source value paired with its volume, for the volume weighted forms. */
+export interface Weighted {
+  readonly src: Value;
+  readonly volume: Value;
+}
+
+/** `sma(src, len)`: the arithmetic mean of the last `len` values, from bar `len - 1`. */
+export function smaStep(
+  state: StateRecord,
+  key: string,
+  value: Value,
+  len: number | null,
+): Value {
+  const lookback = ring(state, key, len);
+  lookback.push(value);
+  return lookback.mean();
+}
+
+/** `sma(src, len)` as a tail. */
+export function smaTail(len: number): Tail<Value, Value> {
+  return tailOf((state, value: Value) => smaStep(state, 'q', value, len));
+}
+
+/** `sma(src, len)` over a whole series. */
+export function sma(src: Series, len: number): Value[] {
+  return fold(smaTail(len), src);
+}
+
+/**
+ * `wma(src, len)`: linearly weighted, the newest value weighted `len`, from bar
+ * `len - 1`.
+ *
+ * `stdlib.md` section 4 fixes the weights and not the order they are summed in,
+ * so the order is this library's own and is the one stated in `lookback.ts`:
+ * oldest bar first, which is weight 1 first and weight `len` last.
+ */
+export function wmaStep(
+  state: StateRecord,
+  key: string,
+  value: Value,
+  len: number | null,
+): Value {
+  const lookback = ring(state, key, len);
+  lookback.push(value);
+  if (len === null || !lookback.complete()) return NONE;
+  const divisor = (len * (len + 1)) / 2;
+  let total = 0;
+  for (let back = len - 1; back >= 0; back -= 1) {
+    total += (lookback.at(back) as number) * (len - back);
+  }
+  return result(total / divisor);
+}
+
+/** `wma(src, len)` as a tail. */
+export function wmaTail(len: number): Tail<Value, Value> {
+  return tailOf((state, value: Value) => wmaStep(state, 'w', value, len));
+}
+
+/** `wma(src, len)` over a whole series. */
+export function wma(src: Series, len: number): Value[] {
+  return fold(wmaTail(len), src);
+}
+
+/** `swma(src)`: the fixed four bar symmetric mean, weights 1, 2, 2, 1 over 6, from bar 3. */
+export function swmaStep(state: StateRecord, key: string, value: Value): Value {
+  const lookback = ring(state, key, 4);
+  lookback.push(value);
+  if (!lookback.complete()) return NONE;
+  const oldest = lookback.at(3) as number;
+  const second = lookback.at(2) as number;
+  const third = lookback.at(1) as number;
+  const newest = lookback.at(0) as number;
+  return result((oldest + 2 * second + 2 * third + newest) / 6);
+}
+
+/** `swma(src)` as a tail. */
+export function swmaTail(): Tail<Value, Value> {
+  return tailOf((state, value: Value) => swmaStep(state, 'q', value));
+}
+
+/** `swma(src)` over a whole series. */
+export function swma(src: Series): Value[] {
+  return fold(swmaTail(), src);
+}
+
+/**
+ * `vwma(src, len)`: the mean weighted by each bar's volume, from bar `len - 1`.
+ *
+ * The total of `src * volume` over the total of `volume`, which is what "mean
+ * weighted by volume" says. Dividing two means by `len` first and then dividing
+ * one by the other is the same quantity with two extra roundings in it, and
+ * this is the arrangement without them.
+ */
+export function vwmaStep(
+  state: StateRecord,
+  key: string,
+  input: Weighted,
+  len: number | null,
+): Value {
+  const flow = ring(state, `${key}f`, len);
+  const quantity = ring(state, `${key}v`, len);
+  const product =
+    isPresent(input.src) && isPresent(input.volume) ? result(input.src * input.volume) : NONE;
+  flow.push(product);
+  quantity.push(input.volume);
+  const numerator = flow.sum();
+  const denominator = quantity.sum();
+  if (!isPresent(numerator) || !isPresent(denominator) || denominator === 0) return NONE;
+  return result(numerator / denominator);
+}
+
+/** `vwma(src, len)` as a tail. */
+export function vwmaTail(len: number): Tail<Weighted, Value> {
+  return tailOf((state, input: Weighted) => vwmaStep(state, 'q', input, len));
+}
+
+/** `vwma(src, len)` over a whole series. */
+export function vwma(src: Series, volume: Series, len: number): Value[] {
+  return fold(
+    vwmaTail(len),
+    src.map((value, index) => ({ src: value, volume: volume[index] ?? NONE })),
+  );
+}

package/src/core/stdlib/calendar/civil.ts

@@ -0,0 +1,89 @@
+/**
+ * Calendar arithmetic on civil dates: no zone, no instant, no clock.
+ *
+ * A civil date is a year, a month and a day as a person writes them. Turning
+ * one into an instant needs a zone and lives in `zone.ts`; everything here is
+ * counting days, and it is separated for that reason: the day number of the
+ * fifteenth of March is the same fact in every zone on earth, and mixing the
+ * two questions is how a calendar ends up right in one half of the year.
+ *
+ * The day number is days since 1970-01-01, positive after it and negative
+ * before. The conversion both ways is the standard proleptic Gregorian one,
+ * shifted so the leap day falls at the end of an internal year that starts in
+ * March: that is what removes the special case for February and makes the
+ * inverse exact rather than iterative.
+ */
+
+/** A date and a time of day as a person writes them, with no zone attached. */
+export interface Civil {
+  readonly year: number;
+  /** 1 to 12. */
+  readonly month: number;
+  /** 1 to 31. */
+  readonly day: number;
+  readonly hour: number;
+  readonly minute: number;
+  readonly second: number;
+}
+
+/** Days from 1970-01-01 to this civil date. */
+export function dayNumber(year: number, month: number, day: number): number {
+  const shifted = month <= 2 ? year - 1 : year;
+  const era = Math.floor((shifted >= 0 ? shifted : shifted - 399) / 400);
+  const yearOfEra = shifted - era * 400;
+  const dayOfYear = Math.floor((153 * (month + (month > 2 ? -3 : 9)) + 2) / 5) + day - 1;
+  const dayOfEra = yearOfEra * 365 + Math.floor(yearOfEra / 4) - Math.floor(yearOfEra / 100) + dayOfYear;
+  return era * 146097 + dayOfEra - 719468;
+}
+
+/** The civil date a day number names, the exact inverse of `dayNumber`. */
+export function dateOfDay(days: number): { year: number; month: number; day: number } {
+  const shifted = days + 719468;
+  const era = Math.floor((shifted >= 0 ? shifted : shifted - 146096) / 146097);
+  const dayOfEra = shifted - era * 146097;
+  const yearOfEra = Math.floor(
+    (dayOfEra - Math.floor(dayOfEra / 1460) + Math.floor(dayOfEra / 36524) - Math.floor(dayOfEra / 146096)) / 365,
+  );
+  const year = yearOfEra + era * 400;
+  const dayOfYear =
+    dayOfEra - (365 * yearOfEra + Math.floor(yearOfEra / 4) - Math.floor(yearOfEra / 100));
+  const monthPart = Math.floor((5 * dayOfYear + 2) / 153);
+  const day = dayOfYear - Math.floor((153 * monthPart + 2) / 5) + 1;
+  const month = monthPart + (monthPart < 10 ? 3 : -9);
+  return { year: month <= 2 ? year + 1 : year, month, day };
+}
+
+/**
+ * The day of the week, 1 for Monday through 7 for Sunday.
+ *
+ * Monday is 1 so that a weekday test reads `date.dayOfWeek(time) <= 5` and a
+ * trading week is a contiguous range, which `stdlib.md` section 12.2 states and
+ * gives the reason for.
+ */
+export function weekdayOfDay(days: number): number {
+  // 1970-01-01 was a Thursday, which is 4 on this numbering.
+  const shifted = (days + 3) % 7;
+  return (shifted < 0 ? shifted + 7 : shifted) + 1;
+}
+
+/** The day of the year, 1 to 366. */
+export function dayOfYearOf(year: number, month: number, day: number): number {
+  return dayNumber(year, month, day) - dayNumber(year, 1, 1) + 1;
+}
+
+/**
+ * The week number, weeks starting Monday.
+ *
+ * Read as the ISO 8601 week: week 1 is the week holding the year's first
+ * Thursday, so a week that straddles the new year belongs to the year holding
+ * most of it and no year ever has a week 0. `stdlib.md` section 12.2 fixes the
+ * Monday start and this settles the rest of it, because the alternatives differ
+ * by a whole week at the turn of every year and a reader has no way to tell
+ * which one a chart drew.
+ */
+export function weekOfYearOf(year: number, month: number, day: number): number {
+  const days = dayNumber(year, month, day);
+  const thursday = days + (4 - weekdayOfDay(days));
+  const owner = dateOfDay(thursday).year;
+  return Math.floor((thursday - dayNumber(owner, 1, 1)) / 7) + 1;
+}