openalgo-script 0.1.0-alpha.0 → 0.2.0

package/src/adapters/charts/markers.ts

@@ -0,0 +1,119 @@
+/**
+ * Declared markers into the chart's bar anchored markers.
+ *
+ * **A marker is a discrete event with a label, not a column of prices.** Its
+ * declaration fixes where it sits, what shape it is drawn as and what colour it
+ * is, all before bar 0; only the text is read per bar, and a bar whose channel
+ * holds no string has no marker at all (`compiled-program.md` 2.8). So this
+ * walks one string channel per call site and produces an entry for each bar that
+ * wrote one, which is why a `signal()` under an `if` marks the bars the branch
+ * was taken and nothing anywhere else.
+ *
+ * **The text cannot travel in the values table**, which holds numbers, so the
+ * markers are built here, once per calculation, and left in the run record that
+ * `produced.ts` keeps for the hook to read.
+ *
+ * **Two of the chart's words are not the language's, and the translation is
+ * here.** A position is `"above"` in the language and `aboveBar` on the chart;
+ * `"price"` names no price for the language to put a marker at, so it becomes
+ * the chart's in-bar position rather than a price this module chose. A shape is
+ * the same word in both worlds for nine of the ten, and the tenth, `"label"`, is
+ * a plate whose tail points at the anchor, so the side the marker sits on is
+ * what decides which of the chart's two plates it is.
+ *
+ * A marker is anchored to a bar's time rather than to its index, because an
+ * index moves when more history loads and a time does not.
+ */
+import type { CompiledProgram, Marker } from '../../core/emit/index.js';
+import { cssColour } from './colours.js';
+import type { ChartBar } from './contract.js';
+import { colourField, stringField } from './fields.js';
+import type { InputLookup } from './fields.js';
+import type { Columns } from './run.js';
+import type { ChartMarker, ChartMarkerPosition, ChartMarkerShape } from './surfaces.js';
+
+/** The language's three positions, in the chart's own words. */
+const POSITIONS: Readonly<Record<string, ChartMarkerPosition>> = {
+  above: 'aboveBar',
+  below: 'belowBar',
+  price: 'inBar',
+};
+
+/** The nine shapes both worlds spell the same way. */
+const SHAPES: readonly string[] = [
+  'arrowUp',
+  'arrowDown',
+  'triangleUp',
+  'triangleDown',
+  'circle',
+  'square',
+  'diamond',
+  'cross',
+  'flag',
+];
+
+/** Which plate a `"label"` is: the tail points at the bar from where it sits. */
+const PLATES: Readonly<Record<ChartMarkerPosition, ChartMarkerShape>> = {
+  aboveBar: 'labelDown',
+  belowBar: 'labelUp',
+  inBar: 'text',
+};
+
+/**
+ * Every marker the run produced, oldest bar first.
+ *
+ * The bars are walked once per call site rather than once in total, so the
+ * entries of one call site are contiguous; the sort afterwards is what puts the
+ * whole set in bar order, and it is stable, so two call sites that marked one
+ * bar stay in declaration order on it.
+ */
+export function buildMarkers(
+  program: CompiledProgram,
+  lookup: InputLookup,
+  bars: readonly ChartBar[],
+  columns: Columns,
+  defaultColour: string,
+): readonly ChartMarker[] {
+  const out: { readonly marker: ChartMarker; readonly index: number }[] = [];
+  for (const declared of program.outputs.markers) {
+    const style = styleOf(declared, lookup, defaultColour);
+    const column = columns[declared.channel] ?? [];
+    for (let index = 0; index < bars.length; index += 1) {
+      const text = column[index];
+      const bar = bars[index];
+      if (typeof text !== 'string' || bar === undefined) continue;
+      out.push({ index, marker: { ...style, time: bar.time, text } });
+    }
+  }
+  return out.sort((a, b) => a.index - b.index).map((one) => one.marker);
+}
+
+/** The part of a marker that is declared once and is the same on every bar. */
+function styleOf(
+  declared: Marker,
+  lookup: InputLookup,
+  defaultColour: string,
+): Omit<ChartMarker, 'time' | 'text'> {
+  const colour = colourField(declared.color, lookup);
+  const written = stringField(declared.position, lookup, 'above');
+  // A declaration a host cannot draw takes the default rather than stopping the
+  // study: the compiler refuses an unknown one with OS3008, so a value arriving
+  // here that is not in the set came from a hand edited program.
+  const position = POSITIONS[written] ?? 'aboveBar';
+  return {
+    position,
+    shape: shapeOf(stringField(declared.shape, lookup, 'label'), position),
+    // The language has no marker size and the chart needs one, so every marker
+    // is drawn at the size the chart's own studies use.
+    size: 'small',
+    // `signal`'s colour defaults to absence, which `stdlib.md` 14.3 reads as the
+    // host's own default for a marker. The chart has no default of its own to
+    // fall back to, so a host that has one states it.
+    color: colour === undefined ? defaultColour : cssColour(colour),
+  };
+}
+
+function shapeOf(written: string, position: ChartMarkerPosition): ChartMarkerShape {
+  if (SHAPES.includes(written)) return written as ChartMarkerShape;
+  return PLATES[position];
+}

package/src/adapters/charts/paint.ts

@@ -0,0 +1,101 @@
+/**
+ * Bar colouring and the pane background, and the rule for who owns the candles.
+ *
+ * Both are one colour per bar on one channel, so both ride the values table as
+ * the two number columns a colour packs into, and both are read back as a column
+ * of colours the length of the bars. A bar the script left alone has an absent
+ * channel, and absence on a drawing surface is a gap: the bar keeps its own
+ * colour and the column behind it stays unshaded, which is the `null` the chart
+ * reads for exactly that.
+ *
+ * **Bar colouring is a statement about the price bars themselves, and they are
+ * not the study's to own.** A pane may hold several studies and the instrument's
+ * candles are one object, so two studies painting them is not two drawings that
+ * overlap, it is two answers to one question. The rule is
+ * `compiled-program.md` 11's: the owner is the study latest in the chart's own
+ * study order that paints, and every other study's bar colouring is not drawn.
+ *
+ * Two things follow, and both are the point of having a rule at all. It is
+ * decided from the list of studies, which is what the legend shows and what the
+ * user reorders, rather than from the order the calculations happened to return
+ * in, so it does not change when one study is slower than another on one frame.
+ * And it changes only when the user adds, removes or reorders a study, so the
+ * candles do not flicker between two colourings while both studies keep
+ * recomputing. A chart that arbitrates between publishers itself applies that
+ * rule from its own list and this descriptor simply states what it wants;
+ * `candleOwner` is the same rule for a host whose chart does not.
+ *
+ * A background needs no such rule. It is drawn behind everything in its own
+ * pane, a colour carries its own alpha in this language, and two translucent
+ * shadings compose the way any two drawings in a pane do.
+ */
+import type { CompiledProgram, Paint } from '../../core/emit/index.js';
+import { colourAt, colourColumns } from './columns.js';
+import type { ColumnSpec } from './columns.js';
+import type { ChartSurfaceContext } from './surfaces.js';
+
+/** The key each paint channel's two colour columns travel under. */
+const BAR_COLOR = 'openscript:barColor';
+const BACKGROUND = 'openscript:background';
+
+/** A column of colours, one per bar, `null` where the script painted none. */
+export type Painting = (ctx: ChartSurfaceContext) => readonly (string | null)[];
+
+export interface PaintBuild {
+  readonly columns: readonly ColumnSpec[];
+  readonly barColors: Painting | undefined;
+  readonly background: Painting | undefined;
+}
+
+export function buildPaint(program: CompiledProgram): PaintBuild {
+  const bar = oneOf(program.outputs.barColor, BAR_COLOR);
+  const pane = oneOf(program.outputs.background, BACKGROUND);
+  return {
+    columns: [...bar.columns, ...pane.columns],
+    barColors: bar.read,
+    background: pane.read,
+  };
+}
+
+function oneOf(
+  paint: Paint | null,
+  key: string,
+): { readonly columns: readonly ColumnSpec[]; readonly read: Painting | undefined } {
+  if (paint === null) return { columns: [], read: undefined };
+  return {
+    columns: colourColumns(key, paint.channel),
+    read: (ctx: ChartSurfaceContext): readonly (string | null)[] => {
+      const out = new Array<string | null>(ctx.bars.length);
+      for (let index = 0; index < out.length; index += 1) {
+        out[index] = colourAt(ctx.values, index, key) ?? null;
+      }
+      return out;
+    },
+  };
+}
+
+/** A study on the chart, as the ownership rule reads one. */
+export interface Painter {
+  readonly id: string;
+  /** The study's own `barColors`, or nothing where it declares none. */
+  readonly barColors?: unknown;
+}
+
+/**
+ * Which study's bar colouring is drawn, given the chart's own study order.
+ *
+ * The list is the host's, oldest first, which is the order a legend lists them
+ * and the order a user changes deliberately. The answer is the last study in it
+ * that paints: a study added on top of another is the one whose colouring the
+ * user just asked to see, and adding a study that paints nothing changes
+ * nothing.
+ *
+ * Nothing is returned when no study paints, which is the ordinary case.
+ */
+export function candleOwner(studies: readonly Painter[]): string | undefined {
+  for (let index = studies.length - 1; index >= 0; index -= 1) {
+    const study = studies[index];
+    if (study !== undefined && study.barColors !== undefined) return study.id;
+  }
+  return undefined;
+}

package/src/adapters/charts/plots.ts

@@ -0,0 +1,185 @@
+/**
+ * Declared plots into the chart's plots.
+ *
+ * This is the part of the mapping that is a rename and a table. A plot names a
+ * style, a width, a dash pattern, a scale, an offset and a colour, and every one
+ * of those is a field the chart's plot spec already has. Three places are not a
+ * rename and are worth knowing:
+ *
+ * **A colour a script wrote as an `input()` becomes the settings key rather than
+ * a value.** The chart generates an appearance row per plot, and a descriptor
+ * that already declares a colour input owns that key, so pointing the plot at
+ * the script's own key makes one row drive both the drawn line and the value the
+ * engine computes with. A generated row beside it would shadow the script's, and
+ * changing the script's would silently stop working.
+ *
+ * **A colour a script computed per bar is not a value at all.** It arrives on a
+ * channel, travels as two number columns and is read back by the per-bar colour
+ * callback, which is the only shape a chart's values table has room for.
+ *
+ * **Scale formatting belongs to a scale and not to a series.** A study's own
+ * `precision` and `format` are its pane's, so they reach only the plots that
+ * stay in that pane: setting them on a plot drawn over the price pane would
+ * reformat the instrument's own axis, which is what OS8007 warns a script about
+ * at compile time.
+ */
+import type { CompiledProgram, Plot } from '../../core/emit/index.js';
+import { buildCandle } from './candles.js';
+import { cssColour } from './colours.js';
+import { colourAt, colourColumns } from './columns.js';
+import type { ColumnSpec } from './columns.js';
+import type {
+  ChartColorContext,
+  ChartLineStyle,
+  ChartPlot,
+  ChartPriceFormat,
+  ChartPriceScaleId,
+  ChartSeriesStyle,
+  ChartSeriesType,
+} from './contract.js';
+import { boolField, colourField, isReference, numberField, stringField } from './fields.js';
+import type { InputLookup } from './fields.js';
+
+/**
+ * The seven styles a plot declaration may carry, in the chart's spelling.
+ *
+ * A name that is not one of them is drawn as a line. Load-time verification
+ * enumerates a channel's type and not a plot's, so a program can reach here
+ * carrying a style no engine has, and there is no catalogue code for a declared
+ * plot style a host cannot draw. A line is the least wrong thing to draw and
+ * inventing a code to refuse it is not this adapter's to do.
+ */
+const SERIES_TYPES: Readonly<Record<string, ChartSeriesType>> = {
+  line: 'line',
+  lineWithMarkers: 'line-markers',
+  step: 'step',
+  area: 'area',
+  histogram: 'histogram',
+  column: 'column',
+  candle: 'candlestick',
+};
+
+const SCALES: Readonly<Record<string, ChartPriceScaleId>> = {
+  right: 'right',
+  left: 'left',
+  none: '',
+};
+
+const LINE_STYLES: readonly string[] = ['solid', 'dashed', 'dotted'];
+
+export interface PlotsBuild {
+  readonly plots: readonly ChartPlot[];
+  readonly columns: readonly ColumnSpec[];
+}
+
+/**
+ * `ownPane` is whether the study draws in a pane of its own, which is what
+ * decides whether the study's own scale formatting reaches a plot at all.
+ */
+export function buildPlots(
+  program: CompiledProgram,
+  lookup: InputLookup,
+  ownPane: boolean,
+): PlotsBuild {
+  const plots: ChartPlot[] = [];
+  const columns: ColumnSpec[] = [];
+  for (const declared of program.outputs.plots) {
+    const built = onePlot(program, declared, lookup, ownPane);
+    plots.push(built.plot);
+    columns.push(...built.columns);
+  }
+  return { plots, columns };
+}
+
+function onePlot(
+  program: CompiledProgram,
+  declared: Plot,
+  lookup: InputLookup,
+  ownPane: boolean,
+): { readonly plot: ChartPlot; readonly columns: readonly ColumnSpec[] } {
+  const key = declared.key;
+  const title = stringField(declared.title, lookup, key);
+  const overlay = boolField(declared.overlay, lookup);
+  const inOwnPane = ownPane && overlay !== true;
+  const offset = numberField(declared.offset, lookup, 0);
+
+  const columns: ColumnSpec[] = [{ key, channel: declared.channel, part: 'value' }];
+  const candle = declared.ohlc === null ? undefined : buildCandle(key, declared.ohlc, lookup);
+  if (candle !== undefined) columns.push(...candle.columns);
+  if (declared.colorChannel !== null) columns.push(...colourColumns(key, declared.colorChannel));
+
+  // A constant colour is nothing when the script named none, which leaves the
+  // colour to the host's palette, and nothing when a channel carries it per bar,
+  // because a constant beside a per-bar colour is a colour the plot never draws.
+  const constant =
+    candle === undefined && declared.colorChannel === null
+      ? colourField(declared.color, lookup)
+      : undefined;
+
+  const style: ChartSeriesStyle = {
+    title,
+    lineWidth: numberField(declared.width, lookup, 1.5),
+    lineStyle: lineStyleOf(stringField(declared.lineStyle, lookup, 'solid')),
+    ...(candle?.style ?? {}),
+    ...(constant === undefined ? {} : { color: cssColour(constant) }),
+  };
+
+  const format = priceFormatOf(program, declared, lookup, inOwnPane);
+  const plot: ChartPlot = {
+    key,
+    type: SERIES_TYPES[declared.type] ?? 'line',
+    title,
+    style,
+    priceScaleId: SCALES[stringField(declared.scale, lookup, 'right')] ?? 'right',
+    ...(format === undefined ? {} : { priceFormat: format }),
+    ...(overlay === undefined ? {} : { overlay }),
+    ...(offset === 0 ? {} : { offset }),
+    ...(isReference(declared.color) ? { colorKey: declared.color.input } : {}),
+    ...(candle === undefined ? {} : { ohlc: candle.ohlc }),
+    ...(candle?.colorParts === undefined ? {} : { colorParts: candle.colorParts }),
+    ...(declared.colorChannel === null
+      ? {}
+      : {
+          colorBy: (ctx: ChartColorContext): string | undefined =>
+            colourAt(ctx.values, ctx.index, key),
+        }),
+  };
+  return { plot, columns };
+}
+
+function lineStyleOf(value: string): ChartLineStyle {
+  return LINE_STYLES.includes(value) ? (value as ChartLineStyle) : 'solid';
+}
+
+/**
+ * The value formatting of the scale this plot maps to.
+ *
+ * The plot's own `format` and `precision` win. The study's own are applied only
+ * where the plot stays in the study's pane, so an overlaid column leaves the
+ * instrument's axis exactly as the chart already formats it.
+ */
+function priceFormatOf(
+  program: CompiledProgram,
+  declared: Plot,
+  lookup: InputLookup,
+  inOwnPane: boolean,
+): ChartPriceFormat | undefined {
+  const format =
+    declared.priceFormat !== null
+      ? stringField(declared.priceFormat, lookup, 'price')
+      : inOwnPane
+        ? stringField(program.meta.format, lookup, 'price')
+        : undefined;
+  if (format === undefined) return undefined;
+  if (format === 'volume') return { type: 'volume' };
+
+  const precision =
+    declared.precision !== null
+      ? numberField(declared.precision, lookup, 4)
+      : inOwnPane
+        ? numberField(program.meta.precision, lookup, 4)
+        : undefined;
+
+  const type = format === 'percent' ? 'percent' : 'price';
+  return precision === undefined ? { type } : { type, precision };
+}

package/src/adapters/charts/produced.ts

@@ -0,0 +1,68 @@
+/**
+ * What one calculation produced that no column of numbers can carry.
+ *
+ * A chart's calculation returns a table of numbers, and five of the things a
+ * study emits are not numbers: a marker's text, a cell's text, a drawing's
+ * caption, a drawing's geometry and an alert's message. The chart reads each of
+ * those from its own hook, and **those hooks are handed the run rather than the
+ * study**: the bars, the table the calculation just returned, and the settings
+ * it was run with. There is no per-instance store among them, so there is
+ * nowhere for the calculation to leave the answer and nowhere for the hook to
+ * pick it up.
+ *
+ * This is that place, and it is deliberately the only one. An alert's message
+ * was thought to have no way across for exactly the reason above, and was
+ * dropped for the life of this adapter: the entry carried the declared title
+ * and every notification a user received was the same sentence, whatever the
+ * script had computed from the bar that fired. The alert's own context carries
+ * the settings, so it reaches this record like every other hook.
+ *
+ * **The settings object is the instance.** A chart resolves one settings object
+ * per study instance and hands the same object to the calculation and to every
+ * hook that follows it, so its identity is what tells three moving averages of
+ * one script apart. A map keyed on it therefore holds one record per instance,
+ * and holds it only while the chart still holds the settings: the map is weak,
+ * so an instance the chart has dropped takes its record with it and nothing
+ * here has to be told about removal.
+ *
+ * **A hook that finds no record draws nothing.** That is the honest answer to a
+ * hook called before any calculation has run, and it is a gap rather than
+ * somebody else's markers, which is what a single latched record would give on
+ * a chart holding two studies.
+ */
+import type { Value } from '../../core/engine/index.js';
+import type { ChartSettings } from './contract.js';
+import type { ChartDrawing, ChartGrid, ChartMarker } from './surfaces.js';
+
+/**
+ * One declared alert's message channel, whole, as the run left it.
+ *
+ * It is the engine's own column and not a copy of it. A message is a string per
+ * bar and the alert that carries it fires on a handful of bars out of a hundred
+ * thousand, so building a second column here would cost the length of the
+ * history to answer a question about one bar.
+ */
+export type MessageColumn = readonly Value[];
+
+/** One run's non-numeric output, as the hooks that follow it read it. */
+export interface Produced {
+  readonly markers: readonly ChartMarker[];
+  readonly table: ChartGrid | null;
+  readonly drawings: readonly ChartDrawing[];
+  /** One entry per declared alert, in the order `outputs.alerts` declares them. */
+  readonly messages: readonly MessageColumn[];
+}
+
+const NOTHING: Produced = { markers: [], table: null, drawings: [], messages: [] };
+
+const runs = new WeakMap<ChartSettings, Produced>();
+
+/** What the calculation just produced, against the settings it was run with. */
+export function remember(settings: ChartSettings, produced: Produced): void {
+  runs.set(settings, produced);
+}
+
+/** What the last calculation for this instance produced, or nothing. */
+export function producedFor(settings: ChartSettings): Produced {
+  return runs.get(settings) ?? NOTHING;
+}