openalgo-script 0.1.0-alpha.1 → 0.2.0

package/src/adapters/charts/contract.ts

@@ -0,0 +1,320 @@
+/**
+ * The chart's indicator descriptor, as this adapter targets it.
+ *
+ * **Why the shape is declared here rather than imported.** The chart library is
+ * a peer dependency: a host that wants a chart installs it, and a host that
+ * wants only the language must not be made to. This repository therefore does
+ * not install it, cannot type check against it, and would fail its own build the
+ * moment a file here imported it. So the adapter declares the shape it produces
+ * and the host's own build is where the two are compared: assigning the result
+ * of `descriptorFor` to the library's `IndicatorDescriptor` is a one line check
+ * that fails to compile if this file has drifted, and it costs a host nothing to
+ * write.
+ *
+ * ```ts
+ * import type { IndicatorDescriptor } from "<the chart library>";
+ * const descriptor: IndicatorDescriptor = descriptorFor(program);
+ * ```
+ *
+ * **That line catches a value of the wrong shape and not an argument of the
+ * wrong shape**, and the difference is worth knowing before trusting it. A
+ * method's parameters are compared in both directions, so a hook declared here
+ * as taking something the chart never passes still assigns: the chart calls it
+ * with what it has, the hook reads nothing, and the study draws none of that
+ * output with nothing anywhere saying so. That failure is the one this module
+ * has actually made. So every hook below takes the chart's own argument, spelled
+ * as the chart spells it, and every test in `tests/adapters/charts` calls each
+ * hook with the argument the chart passes rather than with one of its own.
+ *
+ * Where the two worlds spell something differently the translation is in this
+ * module, which is the only one allowed to know both.
+ *
+ * What is declared is the whole output surface: the 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,
+ * the watched conditions, and the lifecycle a read of another instrument fetches
+ * through.
+ *
+ * **Some of what a study declares has no field on the descriptor to land in**,
+ * and it is left out rather than approximated. Which parts, and why each one
+ * has nowhere to go, is recorded in `spec/chart-narrowings.json`;
+ * `scripts/check-chart-surface.mjs` reads that record against the declarations
+ * of a compiled program and fails on anything dropped that is not in it, so a
+ * narrowing can no longer be added by forgetting to mention one. An alert's
+ * per-bar message was on that list for the life of this module and is now
+ * carried: the file that would have written it is the file that says so.
+ *
+ * Every member is narrowed to what the adapter can emit. A narrower type is
+ * still assignable to the library's wider one, and a value this adapter cannot
+ * produce is better left out than declared and never written.
+ */
+import type {
+  ChartAlertSpec,
+  ChartAttachContext,
+  ChartDrawing,
+  ChartGrid,
+  ChartMarker,
+  ChartSurfaceContext,
+} from './surfaces.js';
+
+/** One bar as the chart holds it. Its time is UTC seconds, not milliseconds. */
+export interface ChartBar {
+  readonly time: number;
+  readonly open: number;
+  readonly high: number;
+  readonly low: number;
+  readonly close: number;
+  readonly volume?: number;
+  readonly oi?: number;
+}
+
+/** The eight series a `"source"` input may select. */
+export type ChartSource = 'open' | 'high' | 'low' | 'close' | 'hl2' | 'hlc3' | 'ohlc4' | 'volume';
+
+/** The plot styles a single column of values can be drawn as, plus candles. */
+export type ChartSeriesType =
+  | 'line'
+  | 'line-markers'
+  | 'step'
+  | 'area'
+  | 'histogram'
+  | 'column'
+  | 'candlestick';
+
+export type ChartLineStyle = 'solid' | 'dashed' | 'dotted';
+
+/** Which price axis a plot maps to. The empty string is a hidden overlay scale. */
+export type ChartPriceScaleId = 'right' | 'left' | '';
+
+export type ChartPriceFormat =
+  | { readonly type: 'price'; readonly precision?: number }
+  | { readonly type: 'percent'; readonly precision?: number }
+  | { readonly type: 'volume' };
+
+/** The style fields a plot built here ever sets. */
+export interface ChartSeriesStyle {
+  readonly title?: string;
+  readonly color?: string;
+  readonly lineWidth?: number;
+  readonly lineStyle?: ChartLineStyle;
+  readonly precision?: number;
+  readonly upColor?: string;
+  readonly downColor?: string;
+  readonly borderUpColor?: string;
+  readonly borderDownColor?: string;
+  readonly wickUpColor?: string;
+  readonly wickDownColor?: string;
+}
+
+export type ChartSettings = Record<string, unknown>;
+export type ChartStore = Record<string, unknown>;
+
+/** One column per key, aligned one to one with the bars, `null` for a gap. */
+export type ChartValues = Record<string, readonly (number | null)[]>;
+
+/** One row of the generated settings dialog. */
+export type ChartInput =
+  | {
+      readonly key: string;
+      readonly type: 'number';
+      readonly label: string;
+      readonly default: number;
+      readonly min?: number;
+      readonly max?: number;
+      readonly step?: number;
+      readonly group?: string;
+      readonly tooltip?: string;
+    }
+  | {
+      readonly key: string;
+      readonly type: 'boolean';
+      readonly label: string;
+      readonly default: boolean;
+      readonly group?: string;
+      readonly tooltip?: string;
+    }
+  | {
+      readonly key: string;
+      readonly type: 'color';
+      readonly label: string;
+      readonly default: string;
+      readonly group?: string;
+      readonly tooltip?: string;
+    }
+  | {
+      readonly key: string;
+      readonly type: 'text';
+      readonly label: string;
+      readonly default: string;
+      readonly group?: string;
+      readonly tooltip?: string;
+    }
+  | {
+      readonly key: string;
+      readonly type: 'select';
+      readonly label: string;
+      readonly default: string;
+      readonly options: readonly { readonly label: string; readonly value: string }[];
+      readonly group?: string;
+      readonly tooltip?: string;
+    }
+  | {
+      readonly key: string;
+      readonly type: 'source';
+      readonly label: string;
+      readonly default: ChartSource;
+      readonly group?: string;
+      readonly tooltip?: string;
+    }
+  | {
+      readonly key: string;
+      readonly type: 'interval';
+      readonly label: string;
+      readonly default: string;
+      readonly group?: string;
+      readonly tooltip?: string;
+    }
+  | {
+      readonly key: string;
+      readonly type: 'time';
+      readonly label: string;
+      readonly default: string;
+      readonly group?: string;
+      readonly tooltip?: string;
+    };
+
+/** What a per-bar callback that has no series value of its own is handed. */
+export interface ChartPaintContext {
+  readonly index: number;
+  readonly values: ChartValues;
+  readonly settings: ChartSettings;
+}
+
+/** What a per-bar colour callback is handed. */
+export interface ChartColorContext extends ChartPaintContext {
+  readonly value: number;
+}
+
+/** A candle plot's colour, split into the three parts a candle is drawn from. */
+export interface ChartBarColor {
+  readonly body?: string;
+  readonly wick?: string;
+  readonly border?: string;
+}
+
+export interface ChartPlot {
+  readonly key: string;
+  readonly type: ChartSeriesType;
+  readonly title: string;
+  readonly style?: ChartSeriesStyle;
+  readonly priceScaleId?: ChartPriceScaleId;
+  readonly priceFormat?: ChartPriceFormat;
+  readonly overlay?: boolean;
+  readonly offset?: number;
+  readonly colorKey?: string;
+  readonly ohlc?: {
+    readonly open: string;
+    readonly high: string;
+    readonly low: string;
+    readonly close: string;
+  };
+  colorBy?(ctx: ChartColorContext): string | undefined;
+  colorParts?(ctx: ChartColorContext): ChartBarColor | undefined;
+}
+
+export interface ChartFill {
+  readonly between: readonly [string, string];
+  readonly colorUp?: string;
+  readonly colorDown?: string;
+  readonly colorUpKey?: string;
+  readonly colorDownKey?: string;
+  readonly opacity?: number;
+  readonly overlay?: boolean;
+}
+
+export interface ChartLevel {
+  readonly price: number;
+  readonly color?: string;
+  readonly title?: string;
+  readonly lineWidth?: number;
+  readonly lineStyle?: ChartLineStyle;
+}
+
+/** What `levels` is handed: the settings, with the data spread beside them. */
+export type ChartLevelContext = ChartSettings & {
+  readonly settings?: ChartSettings;
+  readonly bars?: readonly ChartBar[];
+  readonly values?: ChartValues;
+};
+
+/** What the calculation cannot read off the bars themselves. */
+export interface ChartCalcContext {
+  readonly barState: {
+    readonly isNew: boolean;
+    readonly isConfirmed: boolean;
+    readonly isRealtime: boolean;
+    readonly lastIndex: number;
+  };
+  readonly symbol?: string;
+  readonly interval?: string;
+  readonly timezone: string;
+  now(): number;
+  readonly tickSize?: number;
+}
+
+export interface ChartDescriptor {
+  readonly id: string;
+  readonly name: string;
+  readonly category?: string;
+  readonly placement: 'onchart' | 'pane';
+  readonly inputs: readonly ChartInput[];
+  readonly plots: readonly ChartPlot[];
+  readonly fills?: readonly ChartFill[];
+  /** The conditions a user may subscribe to, fixed before the first bar. */
+  readonly alerts?: readonly ChartAlertSpec[];
+  calc(
+    bars: readonly ChartBar[],
+    settings: ChartSettings,
+    store: ChartStore,
+    ctx?: ChartCalcContext,
+  ): ChartValues;
+  calcTail?(
+    bars: readonly ChartBar[],
+    settings: ChartSettings,
+    fromIndex: number,
+    previous: ChartValues,
+    store: ChartStore,
+    ctx?: ChartCalcContext,
+  ): ChartValues | null;
+  levels?(ctx: ChartLevelContext): readonly ChartLevel[];
+  range?(settings: ChartSettings): { readonly min: number; readonly max: number } | null;
+
+  /**
+   * The instrument's own candles, one colour per bar and `null` where the script
+   * painted none.
+   *
+   * Present only on a study that calls `barColor()`. Only one study may own the
+   * candles of a pane at a time, which is `compiled-program.md` 11's rule rather
+   * than whichever calculation ran last; a chart that arbitrates between
+   * publishers applies it itself, and `candleOwner` is the same rule for a host
+   * whose chart does not.
+   */
+  barColors?(ctx: ChartSurfaceContext): readonly (string | null)[];
+  /** The full height shading behind each bar's column, `null` for unshaded. */
+  background?(ctx: ChartSurfaceContext): readonly (string | null)[];
+  /** Every marker the last calculation produced, oldest bar first. */
+  markers?(ctx: ChartSurfaceContext): readonly ChartMarker[];
+  /** The declared grid as the last executed bar left it, or nothing. */
+  table?(ctx: ChartSurfaceContext): ChartGrid | null;
+  /** Every drawing object the script currently holds, oldest first. */
+  draws?(ctx: ChartSurfaceContext): readonly ChartDrawing[];
+  /**
+   * The lifecycle one instance runs, for a read of another instrument.
+   *
+   * Present only on a program that makes one. A study that computes from the
+   * chart's own bars needs no transport and declares no lifecycle, so it costs
+   * a host nothing.
+   */
+  attach?(ctx: ChartAttachContext): (() => void) | void;
+}

package/src/adapters/charts/descriptor.ts

@@ -0,0 +1,199 @@
+/**
+ * A compiled program as a chart's indicator descriptor.
+ *
+ * The whole of the mapping is here in one function, because the mapping is the
+ * adapter: every other file in this module is one column of the table this
+ * assembles. `compiled-program.md` 11 writes that table out, and the shape of
+ * this function follows it line for line.
+ *
+ * **The calculation drives the engine and computes nothing.** A descriptor's
+ * `calc` is the chart asking for one column per plot; the engine already
+ * produces exactly that, one channel at a time, so `calc` loads a program, runs
+ * the bars and reads the channels out. Nothing here knows what a moving average
+ * is, and that is the point: a second implementation of any of it would be a
+ * second thing to keep in step with the specification.
+ *
+ * **The hooks that follow a calculation read it and do not repeat it.** Markers,
+ * the grid, the drawing objects and each alert's message channel are taken once,
+ * while the engine is in hand, and left in the run record `produced.ts` keeps.
+ * The chart calls each hook after every calculation, so asking twice gives one
+ * answer and a study with a grid costs the same over a hundred thousand bars as
+ * over ten. A message is the channel itself rather than a copy of it: an alert
+ * asks about one bar, and building a column of strings to answer that would cost
+ * the history.
+ *
+ * **A declaration option written as an `input()` is resolved against the
+ * settings the host states, not against the default.** That is the whole point
+ * of writing one: `study("S", precision = input(2, "Places"))` is how a reader
+ * changes something the declaration decides. The declared shape is fixed before
+ * bar 0 and every field of it is a value rather than a call, so the settings
+ * have to be in hand when it is built; `ChartAdapterOptions.settings` is where
+ * they come from, and a descriptor built without them reads every such field at
+ * its declared default. Which parts of the descriptor are resolved here and
+ * which are asked for again per call is recorded in
+ * `spec/chart-narrowings.json` and measured by
+ * `scripts/check-chart-surface.mjs`.
+ *
+ * **The id is the source hash, not the title.** A saved layout stores the
+ * descriptor id and the settings, and two scripts can easily share a title while
+ * an edited script keeps the one it had. Hashing the source means the same
+ * script restores to the same study and an edited one does not silently inherit
+ * the settings of the study it replaced. A host that manages its own script
+ * identities passes its own id instead.
+ */
+import type { CompiledProgram } from '../../core/emit/index.js';
+import { alertMessages, buildAlerts } from './alerts.js';
+import { valuesFrom } from './columns.js';
+import type {
+  ChartBar,
+  ChartCalcContext,
+  ChartDescriptor,
+  ChartSettings,
+  ChartStore,
+  ChartValues,
+} from './contract.js';
+import { buildDrawings } from './drawings.js';
+import { buildFills } from './fills.js';
+import { boolField, stringField } from './fields.js';
+import { buildLevels, buildRange } from './levels.js';
+import { buildMarkers } from './markers.js';
+import { buildPaint } from './paint.js';
+import { buildPlots } from './plots.js';
+import { producedFor, remember } from './produced.js';
+import { stationIn } from './requests.js';
+import { fullRun, release, tailRun } from './run.js';
+import type { ChartAdapterOptions, RunOutput } from './run.js';
+import { inputRows, lookupFor } from './settings.js';
+import type {
+  ChartAttachContext,
+  ChartDrawing,
+  ChartGrid,
+  ChartMarker,
+  ChartSurfaceContext,
+} from './surfaces.js';
+import { buildTable } from './tables.js';
+
+/** The grey an unnamed marker is drawn in, where the host names no default. */
+const MARKER_COLOUR = 'rgba(128, 128, 128, 1)';
+
+export function descriptorFor(
+  program: CompiledProgram,
+  options: ChartAdapterOptions = {},
+): ChartDescriptor {
+  // The declared shape is fixed before bar 0, so the fields that make it up are
+  // read once, against the settings the host states. A host that states none
+  // gets the declared defaults, which is what a script with no `input()` in a
+  // declaration option has anyway. The ones a settings change may move
+  // afterwards carry a settings key instead of a value, and the two that cannot
+  // are read again per call: a level's style and the pane's range.
+  const declared = lookupFor(program, options.settings ?? {});
+
+  const overlay = boolField(program.meta.overlay, declared) === true;
+  const plots = buildPlots(program, declared, !overlay);
+  const levels = buildLevels(program);
+  const fills = buildFills(program, declared);
+  const paint = buildPaint(program);
+  const alerts = buildAlerts(program, declared);
+  const columns = [
+    ...plots.columns,
+    ...levels.columns,
+    ...paint.columns,
+    ...alerts.columns,
+  ];
+  const markerColour = options.markerColor ?? MARKER_COLOUR;
+
+  /**
+   * What the run produced that is not a column of numbers.
+   *
+   * It is keyed by the settings object the chart handed in, because that object
+   * is the study instance: the same one reaches every hook that follows the
+   * calculation, and `produced.ts` says why that is the only handle there is.
+   */
+  const keep = (
+    bars: readonly ChartBar[],
+    settings: ChartSettings,
+    ran: RunOutput,
+  ): void => {
+    const lookup = lookupFor(program, settings);
+    remember(settings, {
+      markers: buildMarkers(program, lookup, bars, ran.columns, markerColour),
+      table: buildTable(program, lookup, ran.tables),
+      drawings: buildDrawings(ran.drawings),
+      messages: alertMessages(program, ran.columns),
+    });
+  };
+  // A study's own group is its category, and a host may name one for a script
+  // whose author left the group blank.
+  const group = stringField(program.meta.group, declared, '');
+  const category = group === '' ? options.category : group;
+
+  return {
+    id: options.id ?? `openscript:${program.source.hash}`,
+    name: stringField(program.meta.title, declared, 'Study'),
+    ...(category === undefined ? {} : { category }),
+    placement: overlay ? 'onchart' : 'pane',
+    inputs: inputRows(program),
+    plots: plots.plots,
+    ...(fills.length === 0 ? {} : { fills }),
+
+    ...(alerts.alerts.length === 0 ? {} : { alerts: alerts.alerts }),
+
+    calc(
+      bars: readonly ChartBar[],
+      settings: ChartSettings,
+      store: ChartStore,
+      ctx?: ChartCalcContext,
+    ): ChartValues {
+      const ran = fullRun(program, bars, settings, store, ctx, options);
+      keep(bars, settings, ran);
+      return valuesFrom(columns, ran.columns, 0, bars.length);
+    },
+
+    calcTail(
+      bars: readonly ChartBar[],
+      settings: ChartSettings,
+      fromIndex: number,
+      _previous: ChartValues,
+      store: ChartStore,
+      ctx?: ChartCalcContext,
+    ): ChartValues | null {
+      const ran = tailRun(program, bars, fromIndex, settings, store, ctx, options);
+      if (ran === null) return null;
+      keep(bars, settings, ran);
+      return valuesFrom(columns, ran.columns, fromIndex, bars.length);
+    },
+
+    ...(program.outputs.levels.length === 0 ? {} : { levels: levels.levels }),
+    ...(program.meta.range === null ? {} : { range: buildRange(program) }),
+    ...(paint.barColors === undefined ? {} : { barColors: paint.barColors }),
+    ...(paint.background === undefined ? {} : { background: paint.background }),
+    ...(program.outputs.markers.length === 0
+      ? {}
+      : {
+          markers: (ctx: ChartSurfaceContext): readonly ChartMarker[] =>
+            producedFor(ctx.settings).markers,
+        }),
+    ...(program.outputs.tables.length === 0
+      ? {}
+      : { table: (ctx: ChartSurfaceContext): ChartGrid | null => producedFor(ctx.settings).table }),
+    ...(program.requires.includes('objects')
+      ? {
+          draws: (ctx: ChartSurfaceContext): readonly ChartDrawing[] =>
+            producedFor(ctx.settings).drawings,
+        }
+      : {}),
+    // A study that reads only this chart's bars needs no lifecycle: the engine
+    // folds its own, and a descriptor that declared one anyway would cost every
+    // host a subscription for a transport nothing asks to use.
+    ...(program.requires.includes('req.symbol')
+      ? {
+          attach(ctx: ChartAttachContext): () => void {
+            stationIn(ctx.store).open(ctx);
+            return (): void => {
+              release(ctx.store);
+            };
+          },
+        }
+      : {}),
+  };
+}