openalgo-script 0.1.0-alpha.1 → 0.2.0

package/src/adapters/charts/drawings.ts

@@ -0,0 +1,213 @@
+/**
+ * Drawing objects into the chart's free drawings.
+ *
+ * A plot is a column of one value per bar and its set is fixed before bar 0. A
+ * drawing object is neither: a script creates one on the bar it decides to, and
+ * moves, recolours and deletes it on any bar afterwards (`stdlib.md` 14.4). The
+ * chart's own field for that is a list of shapes anchored to time and price,
+ * replaced wholesale on every recompute, and that replacement is what makes the
+ * two halves fit without a protocol between them:
+ *
+ * - A script that deletes an object simply stops handing it over, and it is gone.
+ * - A moving bar rolls its objects back before re-executing, so the list handed
+ *   over after four ticks of one bar is the list after one, and a line drawn per
+ *   tick does not accumulate four times.
+ *
+ * **An anchor is a time and a price, and neither is resolved against a bar.** An
+ * anchor ten days past the newest bar crosses as the number it was written as and
+ * lands in the margin, which is what a projection is for.
+ *
+ * **Absence is a gap, and it takes two shapes here.** An anchor with no time or
+ * no price cannot be placed at all, so a line, a box or a label missing either is
+ * not drawn: `language.md` 6.7 says nothing is drawn there and nothing is
+ * invented to fill it, and a zero would be a price. A colour that is absent
+ * becomes fully transparent rather than being left out, because the chart draws a
+ * shape's border in its own ink where no colour is given, and `none` in this
+ * language means nothing is drawn rather than "you choose".
+ *
+ * **A path with a gap in it becomes several paths.** The chart's polyline is one
+ * run of points and the language's path may have a hole in it, so the path is cut
+ * at the hole and each run is drawn. A run of one point is dropped, since a path
+ * needs two, and the `closed` and `fillColor` of a path that was cut are left
+ * off: closing each run separately would draw shapes the script never described.
+ */
+import type { Drawing, Value } from '../../core/engine/index.js';
+import { MS } from './bars.js';
+import { cssOf } from './colours.js';
+import type { ChartLineStyle } from './contract.js';
+import type { ChartAnchor, ChartCellAlign, ChartDrawing } from './surfaces.js';
+
+/** A colour a script left absent: nothing is drawn there. */
+const TRANSPARENT = 'rgba(0, 0, 0, 0)';
+
+const LINE_STYLES: readonly string[] = ['solid', 'dashed', 'dotted'];
+const ALIGNMENTS: readonly string[] = ['left', 'center', 'right'];
+
+/**
+ * One point, or nothing when either half of it is absent.
+ *
+ * The time crosses the same boundary a bar's does and in the same direction: an
+ * anchor is written in the language's milliseconds and a chart counts seconds,
+ * so an anchor handed over unconverted would sit fifty thousand years past the
+ * newest bar and still draw. It is not rounded, because rounding an anchor moves
+ * it, and a chart places one between two bars perfectly well.
+ */
+function anchorOf(anchor: { readonly time: number | null; readonly price: number | null } | undefined):
+  ChartAnchor | undefined {
+  if (anchor === undefined || anchor.time === null || anchor.price === null) return undefined;
+  return { time: anchor.time / MS, price: anchor.price };
+}
+
+function colour(style: Readonly<Record<string, Value>>, key: string): string {
+  return cssOf(style[key] ?? null) ?? TRANSPARENT;
+}
+
+function number(style: Readonly<Record<string, Value>>, key: string): number | undefined {
+  const value = style[key];
+  return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+
+function text(style: Readonly<Record<string, Value>>, key: string): string | undefined {
+  const value = style[key];
+  return typeof value === 'string' && value !== '' ? value : undefined;
+}
+
+function flag(style: Readonly<Record<string, Value>>, key: string): boolean | undefined {
+  const value = style[key];
+  return typeof value === 'boolean' ? value : undefined;
+}
+
+function lineStyle(style: Readonly<Record<string, Value>>): ChartLineStyle | undefined {
+  const value = style['style'];
+  return typeof value === 'string' && LINE_STYLES.includes(value)
+    ? (value as ChartLineStyle)
+    : undefined;
+}
+
+function align(style: Readonly<Record<string, Value>>): ChartCellAlign | undefined {
+  const value = style['align'];
+  return typeof value === 'string' && ALIGNMENTS.includes(value)
+    ? (value as ChartCellAlign)
+    : undefined;
+}
+
+function oneLine(one: Drawing): readonly ChartDrawing[] {
+  const from = anchorOf(one.anchors[0]);
+  const to = anchorOf(one.anchors[1]);
+  if (from === undefined || to === undefined) return [];
+  const width = number(one.style, 'width');
+  const dash = lineStyle(one.style);
+  const left = flag(one.style, 'extendLeft');
+  const right = flag(one.style, 'extendRight');
+  return [
+    {
+      kind: 'line',
+      from,
+      to,
+      color: colour(one.style, 'color'),
+      ...(width === undefined ? {} : { lineWidth: width }),
+      ...(dash === undefined ? {} : { lineStyle: dash }),
+      ...(left === undefined ? {} : { extendLeft: left }),
+      ...(right === undefined ? {} : { extendRight: right }),
+    },
+  ];
+}
+
+function oneBox(one: Drawing): readonly ChartDrawing[] {
+  const from = anchorOf(one.anchors[0]);
+  const to = anchorOf(one.anchors[1]);
+  if (from === undefined || to === undefined) return [];
+  const opacity = number(one.style, 'opacity');
+  const width = number(one.style, 'width');
+  const caption = text(one.style, 'text');
+  const tooltip = text(one.style, 'tooltip');
+  return [
+    {
+      kind: 'box',
+      from,
+      to,
+      color: colour(one.style, 'color'),
+      fillColor: colour(one.style, 'fillColor'),
+      textColor: colour(one.style, 'textColor'),
+      ...(opacity === undefined ? {} : { opacity }),
+      ...(width === undefined ? {} : { lineWidth: width }),
+      ...(caption === undefined ? {} : { text: caption }),
+      ...(tooltip === undefined ? {} : { tooltip }),
+    },
+  ];
+}
+
+function oneLabel(one: Drawing): readonly ChartDrawing[] {
+  const at = anchorOf(one.anchors[0]);
+  const written = one.style['text'];
+  if (at === undefined || typeof written !== 'string') return [];
+  const placement = align(one.style);
+  const tooltip = text(one.style, 'tooltip');
+  return [
+    {
+      kind: 'label',
+      at,
+      text: written,
+      color: colour(one.style, 'color'),
+      textColor: colour(one.style, 'textColor'),
+      ...(placement === undefined ? {} : { align: placement }),
+      ...(tooltip === undefined ? {} : { tooltip }),
+    },
+  ];
+}
+
+/** The path cut at its gaps: one run of points per stretch that has none. */
+function runsOf(one: Drawing): readonly (readonly ChartAnchor[])[] {
+  const runs: ChartAnchor[][] = [];
+  let run: ChartAnchor[] = [];
+  for (const point of one.anchors) {
+    const anchor = anchorOf(point);
+    if (anchor === undefined) {
+      if (run.length > 1) runs.push(run);
+      run = [];
+      continue;
+    }
+    run.push(anchor);
+  }
+  if (run.length > 1) runs.push(run);
+  return runs;
+}
+
+function onePolyline(one: Drawing): readonly ChartDrawing[] {
+  const runs = runsOf(one);
+  const whole = runs.length === 1 && runs[0]?.length === one.anchors.length;
+  const width = number(one.style, 'width');
+  const opacity = number(one.style, 'opacity');
+  const closed = flag(one.style, 'closed');
+  const filled = whole
+    ? {
+        fillColor: colour(one.style, 'fillColor'),
+        ...(closed === undefined ? {} : { closed }),
+        ...(opacity === undefined ? {} : { opacity }),
+      }
+    : {};
+  return runs.map((points) => ({
+    kind: 'polyline' as const,
+    points,
+    color: colour(one.style, 'color'),
+    ...(width === undefined ? {} : { lineWidth: width }),
+    ...filled,
+  }));
+}
+
+/**
+ * Every object the script holds, in the order it created them.
+ *
+ * Creation order rather than any other, because it is the order the script wrote
+ * and therefore the order a reader expects one shape to sit over another.
+ */
+export function buildDrawings(held: readonly Drawing[]): readonly ChartDrawing[] {
+  const out: ChartDrawing[] = [];
+  for (const one of held) {
+    if (one.kind === 'line') out.push(...oneLine(one));
+    else if (one.kind === 'box') out.push(...oneBox(one));
+    else if (one.kind === 'label') out.push(...oneLabel(one));
+    else out.push(...onePolyline(one));
+  }
+  return out;
+}

package/src/adapters/charts/errors.ts

@@ -0,0 +1,45 @@
+/**
+ * How the adapter tells a chart that a study cannot be drawn.
+ *
+ * The engine's surface never throws: it returns a diagnostic. The chart's
+ * surface is the opposite, because a descriptor's `calc` has nowhere else to
+ * put a failure, so this is where the one becomes the other. Nothing is
+ * invented on the way across: the diagnostic the engine produced is carried
+ * whole, with its catalogue code, its source position and its fix, and the
+ * thrown error's message is the sentence the catalogue already wrote.
+ *
+ * **The name is what a chart reads.** The chart's runtime tells a bad input,
+ * which a user can fix from the settings dialog, from a defect, which they
+ * cannot, by the error's name. So a failure raised before any bar ran is named
+ * as an input error, because everything refused at load is a setting, a limit
+ * or a capability the host chose, and a failure raised on a bar keeps this
+ * adapter's own name, because a script that computed four thousand bars and
+ * then stopped is not something a settings dialog can repair.
+ */
+import type { Diagnostic } from '../../core/index.js';
+
+/** The name the chart's runtime reads for a condition a user can fix. */
+const INPUT_ERROR = 'IndicatorInputError';
+
+/** The name for a failure that is not about a setting. */
+const SCRIPT_ERROR = 'OpenScriptError';
+
+export class ChartAdapterError extends Error {
+  readonly diagnostic: Diagnostic;
+
+  constructor(diagnostic: Diagnostic, name: string) {
+    super(`${diagnostic.code}: ${diagnostic.message} ${diagnostic.fix}`);
+    this.name = name;
+    this.diagnostic = diagnostic;
+  }
+}
+
+/** A refusal at load: the program never ran, so a setting is what to change. */
+export function refused(diagnostic: Diagnostic): ChartAdapterError {
+  return new ChartAdapterError(diagnostic, INPUT_ERROR);
+}
+
+/** A failure on a bar: the program ran and stopped. */
+export function stopped(diagnostic: Diagnostic): ChartAdapterError {
+  return new ChartAdapterError(diagnostic, SCRIPT_ERROR);
+}

package/src/adapters/charts/fields.ts

@@ -0,0 +1,74 @@
+/**
+ * A declaration field, read.
+ *
+ * Every field of `meta` and of every declaration in `outputs` holds either a
+ * value or the reference `{ "input": key }`, and the reference is how a tunable
+ * colour, a tunable pane range or a tunable band opacity reaches a declaration
+ * that is otherwise fixed before the first bar. The engine resolves those once
+ * at load, against the settings the host handed it; this module resolves the
+ * same fields against the settings the chart currently holds, which is what a
+ * descriptor built once and restyled many times needs.
+ *
+ * The lookup is a parameter rather than a settings object because converting one
+ * stored setting into a value is the input table's job, not this module's, and
+ * passing it in is what keeps the two from having to import each other.
+ */
+import type { Colour, Field, InputReference } from '../../core/emit/index.js';
+import type { ColourValue, Value } from '../../core/engine/index.js';
+import { isColourValue } from './colours.js';
+
+/** What a field's `{ "input": key }` form is resolved through. */
+export type InputLookup = (key: string) => Value;
+
+export function isReference(field: Field): field is InputReference {
+  return typeof field === 'object' && field !== null && !Array.isArray(field);
+}
+
+/** A field as a value, with any input reference resolved. */
+export function fieldOf(field: Field, lookup: InputLookup): Value {
+  if (field === null) return null;
+  if (isReference(field)) return lookup(field.input);
+  if (Array.isArray(field)) return colourFrom(field);
+  return field as Value;
+}
+
+/** A field that holds a colour, or nothing when it holds none. */
+export function colourField(field: Field, lookup: InputLookup): ColourValue | undefined {
+  const value = fieldOf(field, lookup);
+  return isColourValue(value) ? value : undefined;
+}
+
+export function numberField(field: Field, lookup: InputLookup, fallback: number): number {
+  const value = fieldOf(field, lookup);
+  return typeof value === 'number' && Number.isFinite(value) ? value : fallback;
+}
+
+export function stringField(field: Field, lookup: InputLookup, fallback: string): string {
+  const value = fieldOf(field, lookup);
+  return typeof value === 'string' ? value : fallback;
+}
+
+export function boolField(field: Field, lookup: InputLookup): boolean | undefined {
+  const value = fieldOf(field, lookup);
+  return typeof value === 'boolean' ? value : undefined;
+}
+
+/** A field that holds `[min, max]`, or nothing when it holds no such pair. */
+export function rangeField(
+  field: Field,
+  lookup: InputLookup,
+): { readonly min: number; readonly max: number } | null {
+  const value = isReference(field) ? lookup(field.input) : field;
+  if (!Array.isArray(value) || value.length !== 2) return null;
+  const [min, max] = value as readonly unknown[];
+  if (typeof min !== 'number' || typeof max !== 'number') return null;
+  if (!Number.isFinite(min) || !Number.isFinite(max)) return null;
+  return { min, max };
+}
+
+/** The four numbers a colour field carries, as the value model holds them. */
+function colourFrom(field: readonly number[] | Colour): ColourValue | null {
+  if (field.length !== 4) return null;
+  const [r, g, b, a] = field as readonly [number, number, number, number];
+  return { tag: 'color', r, g, b, a };
+}

package/src/adapters/charts/fills.ts

@@ -0,0 +1,71 @@
+/**
+ * Declared bands into the chart's shaded bands.
+ *
+ * A band is two plot keys and two colours, which is the chart's own spec, so the
+ * pair of keys crosses unchanged. Two details do not.
+ *
+ * **Opacity is a dimmer, not a second alpha.** A colour carries its own alpha
+ * everywhere in the language, and the band's `opacity` multiplies whatever the
+ * colours already are. That is exactly what the chart does with the field, so a
+ * script that never touches it gets the colour it wrote.
+ *
+ * **A band with no colour of its own follows the first plot.** `stdlib.md` 14.2
+ * says such a band is that plot's colour faded to twelve percent, and the plot's
+ * colour may be one the host picked from its palette rather than one the script
+ * wrote, so the band is pointed at the plot's settings key rather than at a value
+ * read now. The twelve percent is then the dimmer, multiplied by whatever the
+ * script asked for.
+ */
+import type { Band, CompiledProgram } from '../../core/emit/index.js';
+import { cssColour } from './colours.js';
+import type { ChartFill } from './contract.js';
+import { boolField, colourField, isReference, numberField } from './fields.js';
+import type { InputLookup } from './fields.js';
+
+/**
+ * The fade a band with no declared colour is drawn at, `stdlib.md` 14.2.
+ *
+ * It is written here because the adapter has to multiply it by the script's own
+ * opacity, and a chart applies its own default only where the field is absent.
+ */
+const UNCOLOURED_FADE = 0.12;
+
+export function buildFills(program: CompiledProgram, lookup: InputLookup): readonly ChartFill[] {
+  const out: ChartFill[] = [];
+  for (const band of program.outputs.fills) out.push(oneBand(program, band, lookup));
+  return out;
+}
+
+function oneBand(program: CompiledProgram, band: Band, lookup: InputLookup): ChartFill {
+  const up = colourField(band.colorUp, lookup);
+  const down = colourField(band.colorDown, lookup);
+  const overlay = boolField(band.overlay, lookup);
+  const declared = up !== undefined || down !== undefined;
+  const opacity = numberField(band.opacity, lookup, 1) * (declared ? 1 : UNCOLOURED_FADE);
+  const follow = declared ? undefined : plotColourKey(program, band.between[0]);
+
+  return {
+    between: band.between,
+    ...(up === undefined ? {} : { colorUp: cssColour(up) }),
+    ...(down === undefined ? {} : { colorDown: cssColour(down) }),
+    ...(isReference(band.colorUp) ? { colorUpKey: band.colorUp.input } : {}),
+    ...(isReference(band.colorDown) ? { colorDownKey: band.colorDown.input } : {}),
+    ...(follow === undefined ? {} : { colorUpKey: follow, colorDownKey: follow }),
+    opacity,
+    ...(overlay === undefined ? {} : { overlay }),
+  };
+}
+
+/**
+ * The settings key holding a plot's colour.
+ *
+ * A chart generates one appearance row per plot and names it after the plot,
+ * except where the plot declares a colour key of its own, which is what a plot
+ * whose colour came from an `input()` does. The two cases are the same two this
+ * adapter produces in `plots.ts`.
+ */
+function plotColourKey(program: CompiledProgram, key: string): string {
+  const plot = program.outputs.plots.find((one) => one.key === key);
+  if (plot !== undefined && isReference(plot.color)) return plot.color.input;
+  return `${key}:color`;
+}

package/src/adapters/charts/index.ts

@@ -0,0 +1,78 @@
+/**
+ * The chart adapter: a compiled program becomes a chart's indicator descriptor.
+ *
+ * This is the only module in the repository allowed to know two worlds at once,
+ * and it is the piece a platform with its own chart replaces rather than the
+ * piece it patches. Everything under `src/core` stays ignorant of charts, and
+ * the layering check is what keeps it that way.
+ *
+ * **The chart library is a peer dependency, and nothing here imports it.** A
+ * package that pulled a chart into everyone's install would defeat the point of
+ * a language that a platform can take on its own, so the descriptor's shape is
+ * declared in `contract.ts` and the value this produces is assigned to the
+ * library's own type by the host, in one line, at the host's build. See that
+ * file for the line.
+ *
+ * What is mapped is the whole output surface: the declared inputs and the
+ * settings dialog a chart generates from them, the plots with their styles and
+ * scales, the bands between them, the horizontal levels, the pane's fixed range,
+ * the markers, the candle and pane painting, the summary grid, the drawing
+ * objects a script mutates over time, the watched conditions, and the lifecycle
+ * a read of another instrument fetches through.
+ *
+ * What a study can express and this descriptor has no field for is recorded,
+ * with its reason, in `spec/chart-narrowings.json`, and each one is also named
+ * in the file that would have written it. `scripts/check-chart-surface.mjs`
+ * reads that record against a compiled program, so the list cannot grow in
+ * silence.
+ */
+export { descriptorFor } from './descriptor.js';
+
+export { candleOwner } from './paint.js';
+export type { Painter } from './paint.js';
+
+export { ChartAdapterError } from './errors.js';
+
+export { release } from './run.js';
+export type { ChartAdapterOptions } from './run.js';
+
+export type {
+  ChartBar,
+  ChartCalcContext,
+  ChartDescriptor,
+  ChartFill,
+  ChartInput,
+  ChartLevel,
+  ChartLevelContext,
+  ChartLineStyle,
+  ChartPlot,
+  ChartPriceFormat,
+  ChartPriceScaleId,
+  ChartSeriesStyle,
+  ChartSeriesType,
+  ChartSettings,
+  ChartSource,
+  ChartStore,
+  ChartValues,
+} from './contract.js';
+
+export type {
+  ChartAlertContext,
+  ChartAlertSpec,
+  ChartAnchor,
+  ChartAttachContext,
+  ChartBarsRequest,
+  ChartCell,
+  ChartCellAlign,
+  ChartDataChange,
+  ChartDataStatus,
+  ChartDrawing,
+  ChartGrid,
+  ChartMarker,
+  ChartMarkerPosition,
+  ChartMarkerShape,
+  ChartMarkerSize,
+  ChartSurfaceContext,
+  ChartTableOptions,
+  ChartTablePosition,
+} from './surfaces.js';

package/src/adapters/charts/levels.ts

@@ -0,0 +1,92 @@
+/**
+ * Declared levels into the chart's horizontal levels, and the pane's range.
+ *
+ * A level's price is a channel rather than a constant, so it is evaluated on
+ * every bar and **the level drawn is the one from the last bar executed**. That
+ * is what makes a level that tracks the data possible at all, and the chart
+ * recomputes its levels after every calculation for the same reason, so the two
+ * meet without either giving anything up: the price travels in the values table
+ * like any other column and is read at its last entry.
+ *
+ * A level whose last value is absent is not drawn, which is the rule for an
+ * absent value reaching any drawn surface: a line breaks, a band stops, a level
+ * is not drawn. Returning it at some substituted price would put a line on the
+ * chart that the script did not ask for.
+ *
+ * The colour, the dash and the width are read against the settings the chart
+ * holds at the moment it asks, not against the ones it held when the descriptor
+ * was built, so a level whose colour came from an `input()` follows the dialog.
+ */
+import type { CompiledProgram } from '../../core/emit/index.js';
+import { cssColour } from './colours.js';
+import { levelKey } from './columns.js';
+import type { ColumnSpec } from './columns.js';
+import type { ChartLevel, ChartLevelContext, ChartLineStyle, ChartSettings } from './contract.js';
+import { colourField, numberField, rangeField, stringField } from './fields.js';
+import { lookupFor } from './settings.js';
+
+const LINE_STYLES: readonly string[] = ['solid', 'dashed', 'dotted'];
+
+export interface LevelsBuild {
+  readonly columns: readonly ColumnSpec[];
+  levels(ctx: ChartLevelContext): readonly ChartLevel[];
+}
+
+export function buildLevels(program: CompiledProgram): LevelsBuild {
+  const columns: ColumnSpec[] = program.outputs.levels.map((declared, index) => ({
+    key: levelKey(index),
+    channel: declared.channel,
+    part: 'value',
+  }));
+
+  return {
+    columns,
+    levels(ctx: ChartLevelContext): readonly ChartLevel[] {
+      const lookup = lookupFor(program, settingsOf(ctx));
+      const out: ChartLevel[] = [];
+      for (let index = 0; index < program.outputs.levels.length; index += 1) {
+        const declared = program.outputs.levels[index];
+        if (declared === undefined) continue;
+        const column = ctx.values?.[levelKey(index)];
+        const price = column === undefined ? undefined : column[column.length - 1];
+        if (typeof price !== 'number') continue;
+        const colour = colourField(declared.color, lookup);
+        const title = stringField(declared.title, lookup, '');
+        const style = stringField(declared.lineStyle, lookup, 'dashed');
+        out.push({
+          price,
+          ...(colour === undefined ? {} : { color: cssColour(colour) }),
+          ...(title === '' ? {} : { title }),
+          lineWidth: numberField(declared.lineWidth, lookup, 1),
+          lineStyle: LINE_STYLES.includes(style) ? (style as ChartLineStyle) : 'dashed',
+        });
+      }
+      return out;
+    },
+  };
+}
+
+/**
+ * The study's own pane range, or nothing when it fixed none.
+ *
+ * It is read per call rather than once, because `range` is one of the fields a
+ * script may write with an `input()`, and a chart asks again whenever the
+ * settings change.
+ */
+export function buildRange(
+  program: CompiledProgram,
+): (settings: ChartSettings) => { readonly min: number; readonly max: number } | null {
+  return (settings: ChartSettings) => rangeField(program.meta.range, lookupFor(program, settings));
+}
+
+/**
+ * The settings a level context carries.
+ *
+ * The context spreads the settings keys onto itself and also carries them under
+ * `settings`, so a caller that built one by hand from a settings bag alone still
+ * works: the named member when there is one, the context itself otherwise.
+ */
+function settingsOf(ctx: ChartLevelContext): ChartSettings {
+  const named = ctx.settings;
+  return named === undefined ? (ctx as ChartSettings) : (named as ChartSettings);
+}