openalgo-script 0.1.0-alpha.1 → 0.2.0

package/src/adapters/charts/alerts.ts

@@ -0,0 +1,116 @@
+/**
+ * Declared alerts into the chart's watched conditions.
+ *
+ * An `alert()` call site is lifted by the compiler into one declared entry: a
+ * boolean channel carrying the chain of guards that reaches the call, a string
+ * channel carrying the message, a stable key and a title (`stdlib.md` 16.1). The
+ * chart's own watched condition is a row with a stable id, a title and a
+ * predicate it evaluates per bar, so the mapping is the boolean channel: it
+ * rides the values table as a column, and the predicate reads that column at the
+ * bar it is judging.
+ *
+ * **Nothing fires for history, and the chart is what applies that.** It judges
+ * only bars that are new since it last looked, so a study added at noon to a
+ * chart holding two years announces none of them, and a settings change, which
+ * recomputes the whole history without adding a bar, announces nothing either.
+ * That is `stdlib.md` 16.2 reached from the host's side rather than the engine's,
+ * and it is the rule the descriptor's own slot already carries.
+ *
+ * **An absent condition is not a true one.** The column holds a number where the
+ * channel published `true` and `null` everywhere else, so an alert under a guard
+ * that was absent during warmup does not fire. That is `language.md` 6.6's three
+ * valued logic reaching a surface, and it is the most common reason a new alert
+ * looks dead.
+ *
+ * **The message is computed on the bar that fired, and it travels.** It is a
+ * string per bar, so it cannot ride the table of numbers the calculation
+ * returns, and the entry's own field takes a function of the same context the
+ * predicate was judged on: the bars, the columns, the settings and the bar's
+ * index. The settings are the study instance (`produced.ts`), so the message
+ * reads the run's own string channel there, at the one bar it is asked about,
+ * and the alert a user receives carries the numbers the script put in it.
+ *
+ * A message the bar published nothing for falls back to the declared title,
+ * which is what the chart itself does for an entry that states no message. That
+ * is the honest answer for the one case that reaches it: `message` is a required
+ * argument, so the string is absent only where the expression that built it was,
+ * and absence reaching a surface draws nothing of its own (`language.md` 6.7).
+ *
+ * **One thing a declared alert carries still has no field on the chart's entry**
+ * and is left out rather than approximated. The **frequency** (`stdlib.md` 16.2)
+ * has nowhere to land: the chart evaluates each entry once for each new bar,
+ * which is `"oncePerBar"`; `"once"` would need state that lives as long as the
+ * study instance and `"everyUpdate"` would need the entry to be evaluated again
+ * on a bar that is still moving, and the entry is handed neither. It is recorded
+ * with its reason in `spec/chart-narrowings.json`, which
+ * `scripts/check-chart-surface.mjs` refuses to let grow in silence.
+ */
+import type { CompiledProgram } from '../../core/emit/index.js';
+import type { ColumnSpec } from './columns.js';
+import { stringField } from './fields.js';
+import type { InputLookup } from './fields.js';
+import type { MessageColumn } from './produced.js';
+import { producedFor } from './produced.js';
+import type { Columns } from './run.js';
+import type { ChartAlertContext, ChartAlertSpec } from './surfaces.js';
+
+/** The key one alert's condition column travels under. */
+export function alertKey(index: number): string {
+  return `openscript:alert:${index}`;
+}
+
+export interface AlertBuild {
+  readonly alerts: readonly ChartAlertSpec[];
+  readonly columns: readonly ColumnSpec[];
+}
+
+/**
+ * Each declared alert's message channel, as the run left it.
+ *
+ * Indexed by the alert's position in `outputs.alerts`, so an entry the program
+ * declares without a message channel holds an empty column rather than shifting
+ * the ones after it.
+ */
+export function alertMessages(
+  program: CompiledProgram,
+  columns: Columns,
+): readonly MessageColumn[] {
+  return program.outputs.alerts.map((declared) => {
+    const channel = declared.messageChannel;
+    return channel === null ? [] : (columns[channel] ?? []);
+  });
+}
+
+/** The rows a user subscribes to, fixed before the first bar. */
+export function buildAlerts(program: CompiledProgram, lookup: InputLookup): AlertBuild {
+  const alerts: ChartAlertSpec[] = [];
+  const columns: ColumnSpec[] = [];
+  for (let index = 0; index < program.outputs.alerts.length; index += 1) {
+    const declared = program.outputs.alerts[index];
+    if (declared === undefined) continue;
+    const key = alertKey(index);
+    const title = stringField(declared.title, lookup, '');
+    columns.push({ key, channel: declared.condChannel, part: 'flag' });
+    alerts.push({
+      id: declared.key,
+      title,
+      // A program whose alert has no message channel states no message, and the
+      // chart's own default for that is the title. Declaring a function that
+      // returned the title anyway would hide that fact behind this adapter.
+      ...(declared.messageChannel === null
+        ? {}
+        : {
+            message: (ctx: ChartAlertContext): string =>
+              messageAt(producedFor(ctx.settings).messages[index], ctx.index) ?? title,
+          }),
+      when: (ctx: ChartAlertContext): boolean => ctx.values[key]?.[ctx.index] === 1,
+    });
+  }
+  return { alerts, columns };
+}
+
+/** The message one bar published, or nothing where it published none. */
+function messageAt(column: MessageColumn | undefined, index: number): string | undefined {
+  const value = column?.[index];
+  return typeof value === 'string' ? value : undefined;
+}

package/src/adapters/charts/bars.ts

@@ -0,0 +1,63 @@
+/**
+ * A chart's bar as the engine reads one.
+ *
+ * One fact differs across the boundary and it is easy to get wrong in a way
+ * nothing catches. A chart's bar time is in **seconds** and the engine's is in
+ * **milliseconds**, so every time crosses through here and nowhere else; a study
+ * comparing `time` against an anchor would be a thousand times out and would
+ * still draw. Every other field is spelled on both sides as
+ * `host-interface.md` 3.1 spells it, so nothing here renames anything.
+ *
+ * **Absence survives the crossing.** A bar with no volume arrives with the field
+ * missing and leaves with it missing, because a script that sizes something by
+ * volume has to be able to tell "no trades" from "nobody said", and a zero put
+ * in here would answer the wrong one of those for ever.
+ *
+ * **Nothing here says where a session begins.** The session is a range of hours
+ * in the instrument record (`host-interface.md` 4.3), the engine derives the
+ * per-bar facts from it, and a chart's own host states those hours alongside
+ * the exchange and the lot size. An option here that set the flags per bar would be
+ * a second source for a fact the engine already derives, and the two would
+ * disagree on the study every intraday chart draws.
+ */
+import type { BarState, HostBar } from '../../core/engine/index.js';
+import type { ChartBar, ChartCalcContext } from './contract.js';
+
+/** Milliseconds in a second, so the conversion is named rather than a literal. */
+export const MS = 1000;
+
+export function hostBar(bar: ChartBar): HostBar {
+  return {
+    open: bar.open,
+    high: bar.high,
+    low: bar.low,
+    close: bar.close,
+    time: Number.isFinite(bar.time) ? bar.time * MS : null,
+    ...(bar.volume === undefined ? {} : { volume: bar.volume }),
+    ...(bar.oi === undefined ? {} : { oi: bar.oi }),
+  };
+}
+
+/** A chart's wall clock reading, in the units the engine's `chart.now()` uses. */
+export function hostNow(seconds: number): number {
+  return seconds * MS;
+}
+
+/**
+ * What the host states about one execution.
+ *
+ * Only the newest bar can be unconfirmed or driven by a live feed: every bar
+ * before it is history, whatever the feed behind the chart is doing now. The
+ * chart's own calculation context says which of those two the newest bar is,
+ * and says nothing at all about the ones before it, which is the same split.
+ */
+export function stateFor(
+  index: number,
+  bars: readonly ChartBar[],
+  ctx: ChartCalcContext | undefined,
+): BarState {
+  const last = index === bars.length - 1;
+  const isConfirmed = !last || ctx === undefined ? true : ctx.barState.isConfirmed;
+  const isRealtime = last && ctx !== undefined ? ctx.barState.isRealtime : false;
+  return { isConfirmed, isRealtime };
+}

package/src/adapters/charts/candles.ts

@@ -0,0 +1,137 @@
+/**
+ * A candle plot: one declaration, four columns.
+ *
+ * `plotCandles` is one entry with one key and one legend row, and the four
+ * values it draws travel as four ordinary columns that the entry names. The
+ * chart's descriptor has exactly that shape, so the mapping is a rename.
+ *
+ * The colours are where the two contracts differ and the difference is worth
+ * stating. A candle's colour is declared four ways: one for a bar that closed at
+ * or above its open, one for a bar that closed below, and two overrides for the
+ * wick and the border alone. Where all four are constants they are the series'
+ * own style and cost nothing per bar. Where a script passed a series colour
+ * instead, the value arrives on a channel and the colour is decided per bar,
+ * which is the split callback the chart takes.
+ *
+ * **A null override means the wick or the border follows the body**, which is
+ * the opposite of a null colour on a line plot: the host may choose an
+ * undecorated line's colour because nothing depends on it, and a wick the host
+ * coloured independently of the body it grows out of would draw a different
+ * candle on every chart. So an override with neither a channel nor a declared
+ * value is answered with the body's own colour for that bar, and one with a
+ * declared value is left alone for the style to carry.
+ */
+import type { CandleChannels } from '../../core/emit/index.js';
+import type { ColourValue } from '../../core/engine/index.js';
+import { cssColour } from './colours.js';
+import type { ChartBarColor, ChartColorContext, ChartSeriesStyle } from './contract.js';
+import { colourAt, colourColumns } from './columns.js';
+import type { ColumnSpec } from './columns.js';
+import { colourField } from './fields.js';
+import type { InputLookup } from './fields.js';
+
+export interface CandleBuild {
+  readonly ohlc: {
+    readonly open: string;
+    readonly high: string;
+    readonly low: string;
+    readonly close: string;
+  };
+  readonly style: ChartSeriesStyle;
+  readonly columns: readonly ColumnSpec[];
+  readonly colorParts: ((ctx: ChartColorContext) => ChartBarColor | undefined) | undefined;
+}
+
+export function buildCandle(key: string, ohlc: CandleChannels, lookup: InputLookup): CandleBuild {
+  const keys = {
+    open: `${key}:open`,
+    high: `${key}:high`,
+    low: `${key}:low`,
+    close: `${key}:close`,
+  };
+
+  const up = colourField(ohlc.colorUp, lookup);
+  const down = colourField(ohlc.colorDown, lookup);
+  const wick = colourField(ohlc.wickColor, lookup);
+  const border = colourField(ohlc.borderColor, lookup);
+
+  const borderUp = border ?? up;
+  const borderDown = border ?? down;
+  const wickUp = wick ?? up;
+  const wickDown = wick ?? down;
+
+  const style: ChartSeriesStyle = {
+    ...(up === undefined ? {} : { upColor: cssColour(up) }),
+    ...(down === undefined ? {} : { downColor: cssColour(down) }),
+    ...(borderUp === undefined ? {} : { borderUpColor: cssColour(borderUp) }),
+    ...(borderDown === undefined ? {} : { borderDownColor: cssColour(borderDown) }),
+    ...(wickUp === undefined ? {} : { wickUpColor: cssColour(wickUp) }),
+    ...(wickDown === undefined ? {} : { wickDownColor: cssColour(wickDown) }),
+  };
+
+  const columns: ColumnSpec[] = [
+    { key: keys.open, channel: ohlc.open, part: 'value' },
+    { key: keys.high, channel: ohlc.high, part: 'value' },
+    { key: keys.low, channel: ohlc.low, part: 'value' },
+    { key: keys.close, channel: ohlc.close, part: 'value' },
+  ];
+
+  const parts: { readonly name: string; readonly channel: number | null }[] = [
+    { name: `${key}:up`, channel: ohlc.colorUpChannel },
+    { name: `${key}:down`, channel: ohlc.colorDownChannel },
+    { name: `${key}:wick`, channel: ohlc.wickColorChannel },
+    { name: `${key}:border`, channel: ohlc.borderColorChannel },
+  ];
+  for (const part of parts) {
+    if (part.channel !== null) columns.push(...colourColumns(part.name, part.channel));
+  }
+
+  const perBar = parts.some((one) => one.channel !== null);
+  return {
+    ohlc: keys,
+    style,
+    columns,
+    colorParts: perBar
+      ? (ctx: ChartColorContext): ChartBarColor | undefined => {
+          const rising = isRising(ctx, keys.open, keys.close);
+          const bodyChannel = rising ? ohlc.colorUpChannel : ohlc.colorDownChannel;
+          const body =
+            bodyChannel === null
+              ? undefined
+              : colourAt(ctx.values, ctx.index, rising ? `${key}:up` : `${key}:down`);
+          const wickPart = override(ctx, `${key}:wick`, ohlc.wickColorChannel, wick, body);
+          const borderPart = override(ctx, `${key}:border`, ohlc.borderColorChannel, border, body);
+          return {
+            ...(body === undefined ? {} : { body }),
+            ...(wickPart === undefined ? {} : { wick: wickPart }),
+            ...(borderPart === undefined ? {} : { border: borderPart }),
+          };
+        }
+      : undefined,
+  };
+}
+
+/** Whether this bar closed at or above its own open, by the candle's columns. */
+function isRising(ctx: ChartColorContext, openKey: string, closeKey: string): boolean {
+  const open = ctx.values[openKey]?.[ctx.index];
+  const close = ctx.values[closeKey]?.[ctx.index];
+  if (typeof open !== 'number' || typeof close !== 'number') return true;
+  return close >= open;
+}
+
+/**
+ * The wick or the border for one bar.
+ *
+ * Its own channel wins, then a declared constant, which the series style already
+ * carries and this leaves alone, and otherwise the part follows the body.
+ */
+function override(
+  ctx: ChartColorContext,
+  name: string,
+  channel: number | null,
+  declared: ColourValue | undefined,
+  body: string | undefined,
+): string | undefined {
+  if (channel !== null) return colourAt(ctx.values, ctx.index, name);
+  return declared === undefined ? body : undefined;
+}

package/src/adapters/charts/colours.ts

@@ -0,0 +1,113 @@
+/**
+ * A colour on either side of the boundary.
+ *
+ * The language carries a colour as four numbers, three whole channels and an
+ * alpha that is an ordinary number from 0 to 1. A chart carries one as a CSS
+ * string. The two directions are not symmetric and it is worth saying why.
+ *
+ * **Out of the language, nothing is lost.** The functional form is written
+ * rather than eight hexadecimal digits, because a hexadecimal alpha is a byte
+ * and the language's is not: `fade(x, 93)` is an alpha of 0.07, which no pair of
+ * hexadecimal digits holds exactly, and a study whose band came back a shade off
+ * would be a difference nobody could account for.
+ *
+ * **Into the language, alpha is the part that goes missing.** A chart's colour
+ * control is a swatch with no alpha channel, so the value it stores back is six
+ * digits and the transparency the script asked for is gone. Rather than turn
+ * every translucent input opaque the first time somebody opens the dialog, a
+ * value with no alpha of its own keeps the alpha the script declared, and only
+ * a value that states one replaces it.
+ *
+ * A per-bar colour reaches a chart through the values table, which holds columns
+ * of numbers, so it travels as two columns: the three channels packed into one
+ * whole number, and the alpha beside them as itself. One column would have to
+ * put the alpha in a byte and lose exactly what the functional form is here to
+ * keep.
+ */
+import type { ColourValue, Value } from '../../core/engine/index.js';
+
+/** `#rgb`, `#rrggbb`, `#rrggbbaa`, and the two functional forms. */
+const HEX = /^#([0-9a-f]{3,8})$/i;
+const FUNCTIONAL = /^rgba?\(([^)]*)\)$/i;
+
+/** The CSS spelling of a colour. */
+export function cssColour(colour: ColourValue): string {
+  return `rgba(${colour.r}, ${colour.g}, ${colour.b}, ${colour.a})`;
+}
+
+/** The CSS spelling of a value that may not be a colour at all. */
+export function cssOf(value: Value): string | undefined {
+  return isColourValue(value) ? cssColour(value) : undefined;
+}
+
+export function isColourValue(value: Value): value is ColourValue {
+  return typeof value === 'object' && value !== null && value.tag === 'color';
+}
+
+export function colourOf(r: number, g: number, b: number, a: number): ColourValue {
+  return { tag: 'color', r: channel(r), g: channel(g), b: channel(b), a: a < 0 ? 0 : a > 1 ? 1 : a };
+}
+
+/**
+ * A CSS colour back into the language's four numbers.
+ *
+ * `alpha` is what a value with no alpha of its own is given: the alpha the
+ * script declared for that input, so a swatch that cannot express transparency
+ * does not remove it. Anything unparseable is nothing, which the caller turns
+ * into the refusal the input's own validation would have produced.
+ */
+export function parseColour(text: string, alpha: number): ColourValue | undefined {
+  const trimmed = text.trim();
+
+  const hex = HEX.exec(trimmed);
+  if (hex !== null) {
+    const digits = hex[1] ?? '';
+    const wide = digits.length === 3 || digits.length === 4;
+    if (!wide && digits.length !== 6 && digits.length !== 8) return undefined;
+    const at = (index: number): number => {
+      const pair = wide
+        ? `${digits.charAt(index)}${digits.charAt(index)}`
+        : digits.slice(index * 2, index * 2 + 2);
+      return Number.parseInt(pair, 16);
+    };
+    const opaque = digits.length === 4 || digits.length === 8;
+    return colourOf(at(0), at(1), at(2), opaque ? at(3) / 255 : alpha);
+  }
+
+  const functional = FUNCTIONAL.exec(trimmed);
+  if (functional === null) return undefined;
+  const parts = (functional[1] ?? '')
+    .split(/[\s,/]+/)
+    .filter((one) => one.length > 0)
+    .map((one) => Number(one));
+  if (parts.length < 3 || parts.some((one) => !Number.isFinite(one))) return undefined;
+  const [r, g, b, a] = parts as [number, number, number, number | undefined];
+  return colourOf(r, g, b, a ?? alpha);
+}
+
+/** The three channels as one whole number, for a column of per-bar colours. */
+export function packChannels(colour: ColourValue): number {
+  return (colour.r * 256 + colour.g) * 256 + colour.b;
+}
+
+/** The CSS spelling of a packed triple and the alpha that travelled beside it. */
+export function unpackColour(packed: number, alpha: number): string {
+  const b = packed % 256;
+  const g = ((packed - b) / 256) % 256;
+  const r = (packed - b - g * 256) / 65_536;
+  return `rgba(${r}, ${g}, ${b}, ${alpha})`;
+}
+
+/**
+ * A whole channel inside the range a chart can draw.
+ *
+ * A colour arriving from a chart has whole channels already: every control that
+ * writes one writes an integer. The rounding is here for a hand written string
+ * rather than as a rule of the language, whose own rounding applies where a
+ * script computes a colour and is the engine's to apply, not this module's.
+ */
+function channel(x: number): number {
+  if (!Number.isFinite(x)) return 0;
+  const whole = Math.round(x);
+  return whole < 0 ? 0 : whole > 255 ? 255 : whole;
+}

package/src/adapters/charts/columns.ts

@@ -0,0 +1,99 @@
+/**
+ * Channels into the columns a chart reads.
+ *
+ * A chart's calculation returns one table: a key to a column of numbers, every
+ * column the same length as the bars, `null` where there is no value. A plot's
+ * own column is the obvious entry in it, and everything else a study emits has
+ * to travel in the same table because there is nowhere else to put it.
+ *
+ * So three things ride here that a chart does not draw directly. A candle plot's
+ * four columns, which the plot names and the chart assembles into bars. A level's
+ * price, which is a channel evaluated on every bar and read at the last one. And
+ * a per-bar colour, which is not a number at all and travels as two columns: the
+ * three channels packed into one whole number and the alpha beside it, for the
+ * reason `colours.ts` gives.
+ *
+ * Every key a chart does not draw is prefixed or suffixed so that it cannot
+ * collide with a plot key, which the compiler writes as `p` and a number.
+ */
+import type { Value } from '../../core/engine/index.js';
+import { isColourValue, packChannels, unpackColour } from './colours.js';
+import type { ChartValues } from './contract.js';
+import type { Columns } from './run.js';
+
+/**
+ * Which part of a channel's value a column carries.
+ *
+ * `flag` is a condition rather than a number: a channel that published `true`
+ * for the bar reads 1 and everything else, absence included, reads as a gap.
+ * That is what lets a watched condition travel in a table of numbers, and it
+ * keeps `language.md` 6.6's answer intact on the way: absent is not true.
+ */
+export type ColumnPart = 'value' | 'rgb' | 'alpha' | 'flag';
+
+export interface ColumnSpec {
+  readonly key: string;
+  readonly channel: number;
+  readonly part: ColumnPart;
+}
+
+/** The key a level's price column travels under. */
+export function levelKey(index: number): string {
+  return `openscript:level:${index}`;
+}
+
+/** The two keys a per-bar colour travels under. */
+export function colourKeys(key: string): { readonly rgb: string; readonly alpha: string } {
+  return { rgb: `${key}:rgb`, alpha: `${key}:alpha` };
+}
+
+/** The colour a per-bar channel carried on one bar, as a chart spells one. */
+export function colourAt(values: ChartValues, index: number, key: string): string | undefined {
+  const keys = colourKeys(key);
+  const rgb = values[keys.rgb]?.[index];
+  const alpha = values[keys.alpha]?.[index];
+  if (typeof rgb !== 'number' || typeof alpha !== 'number') return undefined;
+  return unpackColour(rgb, alpha);
+}
+
+/** The two column specifications a per-bar colour channel needs. */
+export function colourColumns(key: string, channel: number): readonly ColumnSpec[] {
+  const keys = colourKeys(key);
+  return [
+    { key: keys.rgb, channel, part: 'rgb' },
+    { key: keys.alpha, channel, part: 'alpha' },
+  ];
+}
+
+/**
+ * The table, for bars `from` up to `to`.
+ *
+ * `from` is zero for a full recompute and the first changed bar for a tail, and
+ * the chart splices a tail onto what it already holds. Every key the full path
+ * produces is produced here too, because a key the tail leaves out is dropped
+ * from the spliced result rather than kept.
+ */
+export function valuesFrom(
+  specs: readonly ColumnSpec[],
+  columns: Columns,
+  from: number,
+  to: number,
+): ChartValues {
+  const out: Record<string, readonly (number | null)[]> = {};
+  for (const spec of specs) {
+    const column = columns[spec.channel] ?? [];
+    const built = new Array<number | null>(Math.max(0, to - from));
+    for (let bar = from; bar < to; bar += 1) {
+      built[bar - from] = partOf(column[bar] ?? null, spec.part);
+    }
+    out[spec.key] = built;
+  }
+  return out;
+}
+
+function partOf(value: Value, part: ColumnPart): number | null {
+  if (part === 'value') return typeof value === 'number' ? value : null;
+  if (part === 'flag') return value === true ? 1 : null;
+  if (!isColourValue(value)) return null;
+  return part === 'rgb' ? packChannels(value) : value.a;
+}