openalgo-script 0.1.0-alpha.0 → 0.2.0

package/src/core/check/library-orders.ts

@@ -0,0 +1,290 @@
+/**
+ * The part of the library that spends money: `stdlib.md` section 17.
+ *
+ * Every entry here is marked `strategyOnly`, which is the whole of what the
+ * checker has to know about the section's opening rule: a `study()` file that
+ * reaches for one of these is OS7001, and the fix names the declaration to
+ * change rather than the call to delete.
+ *
+ * A leg is named by a string rather than by a handle, so nothing in this file
+ * carries a type the rest of the language does not already have.
+ *
+ * **What is marked `planned` here is what no engine can run yet**, and it is
+ * marked rather than left to be discovered. The legs and the book of sections
+ * 17.6 and 17.9 to 17.11 are rules evaluated over the ledger, and the money
+ * figures need a cost model; neither exists in an engine in this release. A name
+ * left unmarked would compile and then be refused at load with OS6004, which
+ * names a function and not a reason. Marked, it is OS2020 at the call, at the
+ * point a reader can see what they wrote, with a message that says it is
+ * planned.
+ *
+ * The nine order functions and the five position facts are not marked, because
+ * those do run: the ledger of section 17.7 is folded from the intents those nine
+ * send and the frames a host reports back for them, and the five read it. None
+ * of them reads a host's position row, and section 17.1 is why.
+ */
+import { DATA_DRIVEN, entry } from './library.js';
+import type { LibraryEntry } from './library.js';
+
+const SIDES = ['buy', 'sell'];
+const ORDER_TYPES = ['market', 'limit', 'stop', 'stopLimit'];
+const DIRECTIONS = ['up', 'down'];
+const BOOK_DIRECTIONS = ['long', 'short', 'both'];
+const LEG_KINDS = ['future', 'option'];
+const RIGHTS = ['call', 'put'];
+
+const strategyOnly = { strategyOnly: true } as const;
+
+/**
+ * Every order function names the leg it acts on, and no file can declare one.
+ *
+ * A leg is declared before the run with `leg.fixed` or `leg.relative`
+ * (`stdlib.md` 17.6), and both of those are planned below. So the set of names
+ * a `leg` argument may take is empty in this release, and a file that declares
+ * no leg has exactly one, which every order acts on with no leg named.
+ *
+ * Which makes the argument a refusal rather than a set check. The value never
+ * comes into it: `close(leg = "b")` after `buy(leg = "a")` flattened the
+ * position on the only leg there is, and a name the script computed was
+ * ignored just as quietly. OS3023 says so at the call, whichever of the two it
+ * is, and the day a leg can be declared this becomes the set check OS3008
+ * already is for every other argument with a fixed set of values.
+ */
+const onOneLeg = { strategyOnly: true, undeclared: ['leg'] } as const;
+
+/** The bare order functions of stdlib.md 17.2, which `close` is one of. */
+export const ORDER_NAMES: readonly string[] = [
+  'buy',
+  'sell',
+  'close',
+  'exit',
+  'cancel',
+  'cancelAll',
+];
+
+const placing: readonly LibraryEntry[] = [
+  entry(
+    'buy(qty?: number, limit?: number = none, stop?: number = none, tag?: string = "", leg?: string) -> nothing',
+    onOneLeg,
+  ),
+  entry(
+    'sell(qty?: number, limit?: number = none, stop?: number = none, tag?: string = "", leg?: string) -> nothing',
+    onOneLeg,
+  ),
+  entry('close(tag?: string = none, qty?: number = none, leg?: string) -> nothing', onOneLeg),
+  entry(
+    'exit(tag?: string = "", qty?: number = none, limit?: number = none, stop?: number = none, profit?: number = none, loss?: number = none, leg?: string) -> nothing',
+    {
+      ...onOneLeg,
+      // An absolute price and a distance from the entry state the same level,
+      // and reconciling them would need a rule (stdlib.md 17.2).
+      conflicts: [
+        ['limit', 'profit'],
+        ['stop', 'loss'],
+      ],
+    },
+  ),
+  entry('cancel(tag: string) -> nothing', strategyOnly),
+  entry('cancelAll() -> nothing', strategyOnly),
+];
+
+const orders: readonly LibraryEntry[] = [
+  entry(
+    'order.place(side: string, qty: number, type?: string = "market", price?: number = none, trigger?: number = none, tag?: string = "", leg?: string) -> nothing',
+    { ...onOneLeg, values: { side: SIDES, type: ORDER_TYPES } },
+  ),
+  entry('order.reverse(qty?: number = none, tag?: string = "", leg?: string) -> nothing', onOneLeg),
+  entry(
+    'order.bracket(tag?: string = "", profit?: number = none, loss?: number = none, leg?: string) -> nothing',
+    onOneLeg,
+  ),
+  entry('order.working(tag: string) -> series bool', { ...strategyOnly, planned: true }),
+  entry('order.pending -> series number', { ...strategyOnly, planned: true }),
+  entry('order.id(tag: string) -> series string', { ...strategyOnly, planned: true }),
+  entry('order.status(tag: string) -> series string', { ...strategyOnly, planned: true }),
+  entry('order.filled(tag: string) -> series number', { ...strategyOnly, planned: true }),
+  entry('order.avgFill(tag: string) -> series number', {
+    ...strategyOnly,
+    planned: true,
+    warmup: DATA_DRIVEN,
+  }),
+  entry('order.rejection(tag: string) -> series string', { ...strategyOnly, planned: true }),
+  entry('order.qtyForCash(cash: number, price?: number = close) -> number', {
+    ...strategyOnly,
+    planned: true,
+  }),
+  entry('order.qtyForRisk(risk: number, entry: number, stop: number) -> number', {
+    ...strategyOnly,
+    planned: true,
+  }),
+  entry('order.qtyForEquityPercent(percent: number, price?: number = close) -> number', {
+    ...strategyOnly,
+    planned: true,
+  }),
+  entry('order.roundToLot(qty: number, direction?: string = "down", leg?: string) -> number', {
+    ...strategyOnly,
+    planned: true,
+    values: { direction: DIRECTIONS },
+  }),
+  entry('order.modify(tag: string) -> nothing', { ...strategyOnly, planned: true }),
+  entry('order.oco(tagA: string, tagB: string) -> nothing', { ...strategyOnly, planned: true }),
+];
+
+const position: readonly LibraryEntry[] = [
+  entry('pos.size -> series number', strategyOnly),
+  entry('pos.isLong -> series bool', strategyOnly),
+  entry('pos.isShort -> series bool', strategyOnly),
+  entry('pos.isFlat -> series bool', strategyOnly),
+  entry('pos.avgPrice -> series number', { ...strategyOnly, warmup: DATA_DRIVEN }),
+  entry('pos.entryTime -> series number', {
+    ...strategyOnly,
+    planned: true,
+    warmup: DATA_DRIVEN,
+  }),
+  entry('pos.barsHeld -> series number', {
+    ...strategyOnly,
+    planned: true,
+    warmup: DATA_DRIVEN,
+  }),
+  entry('pos.entries -> series number', { ...strategyOnly, planned: true }),
+  entry('pos.openProfit -> series number', {
+    ...strategyOnly,
+    planned: true,
+    warmup: DATA_DRIVEN,
+  }),
+  entry('pos.openProfitPercent -> series number', {
+    ...strategyOnly,
+    planned: true,
+    warmup: DATA_DRIVEN,
+  }),
+  entry('pos.maxProfit -> series number', {
+    ...strategyOnly,
+    planned: true,
+    warmup: DATA_DRIVEN,
+  }),
+  entry('pos.maxLoss -> series number', {
+    ...strategyOnly,
+    planned: true,
+    warmup: DATA_DRIVEN,
+  }),
+  entry('pos.isShared -> series bool', { ...strategyOnly, planned: true }),
+  entry('pos.equity -> series number', { ...strategyOnly, planned: true }),
+  entry('pos.netProfit -> series number', { ...strategyOnly, planned: true }),
+  entry('pos.tradeCount -> series number', { ...strategyOnly, planned: true }),
+  entry('pos.winRate -> series number', { ...strategyOnly, planned: true }),
+  entry('pos.profitFactor -> series number', { ...strategyOnly, planned: true }),
+  entry('pos.maxDrawdown -> series number', { ...strategyOnly, planned: true }),
+];
+
+const legs: readonly LibraryEntry[] = [
+  entry(
+    'leg.fixed(name: string, symbol: string, exchange?: string = chart.exchange, product?: string, qty?: number, side?: string = "buy") -> nothing',
+    {
+      ...strategyOnly,
+      planned: true,
+      topLevel: true,
+      values: { side: SIDES },
+      constant: ['name', 'symbol', 'exchange', 'product', 'qty', 'side'],
+    },
+  ),
+  entry(
+    'leg.relative(name: string, underlying: string, kind: string, expiryRank?: number = 0, expiryCycle?: string = none, strikeOffset?: number = 0, right?: string = none, reference?: number = none, exchange?: string = chart.exchange, product?: string, qty?: number, side?: string = "buy") -> nothing',
+    {
+      ...strategyOnly,
+      planned: true,
+      topLevel: true,
+      values: { kind: LEG_KINDS, right: RIGHTS, side: SIDES },
+      constant: [
+        'name',
+        'underlying',
+        'kind',
+        'expiryRank',
+        'expiryCycle',
+        'strikeOffset',
+        'right',
+        'reference',
+        'exchange',
+        'product',
+        'qty',
+        'side',
+      ],
+    },
+  ),
+  entry('leg.symbol(name: string) -> string', { ...strategyOnly, planned: true }),
+  entry('leg.exchange(name: string) -> string', { ...strategyOnly, planned: true }),
+  entry('leg.product(name: string) -> string', { ...strategyOnly, planned: true }),
+  entry('leg.expiry(name: string) -> number', { ...strategyOnly, planned: true }),
+  entry('leg.strike(name: string) -> number', { ...strategyOnly, planned: true }),
+  entry('leg.size(name: string) -> series number', { ...strategyOnly, planned: true }),
+  entry('leg.avgPrice(name: string) -> series number', {
+    ...strategyOnly,
+    planned: true,
+    warmup: DATA_DRIVEN,
+  }),
+  entry('leg.entryTime(name: string) -> series number', {
+    ...strategyOnly,
+    planned: true,
+    warmup: DATA_DRIVEN,
+  }),
+  entry('leg.profit(name: string) -> series number', { ...strategyOnly, planned: true }),
+  entry('leg.isOpen(name: string) -> series bool', { ...strategyOnly, planned: true }),
+  entry('leg.stopPrice(name: string) -> series number', {
+    ...strategyOnly,
+    planned: true,
+    warmup: DATA_DRIVEN,
+  }),
+  entry('leg.targetPrice(name: string) -> series number', {
+    ...strategyOnly,
+    planned: true,
+    warmup: DATA_DRIVEN,
+  }),
+  entry('leg.stop(name: string, price: number) -> nothing', { ...strategyOnly, planned: true }),
+  entry('leg.target(name: string, price: number) -> nothing', { ...strategyOnly, planned: true }),
+  entry('leg.trail(name: string, distance: number, arm?: number = none) -> nothing', {
+    ...strategyOnly,
+    planned: true,
+  }),
+  entry(
+    'leg.enter(name: string, side?: string, qty?: number, limit?: number = none, stop?: number = none, tag?: string = "") -> nothing',
+    { ...strategyOnly, planned: true, values: { side: SIDES } },
+  ),
+  entry(
+    'leg.exit(name: string, qty?: number = none, limit?: number = none, stop?: number = none, tag?: string = "") -> nothing',
+    { ...strategyOnly, planned: true },
+  ),
+];
+
+const book: readonly LibraryEntry[] = [
+  entry('book.stop(amount: number) -> nothing', { ...strategyOnly, planned: true }),
+  entry('book.target(amount: number) -> nothing', { ...strategyOnly, planned: true }),
+  entry(
+    'book.lockProfit(arm: number, lock: number, step?: number = none, advance?: number = none) -> nothing',
+    { ...strategyOnly, planned: true },
+  ),
+  entry('book.trailStopsToEntry(at: number) -> nothing', { ...strategyOnly, planned: true }),
+  entry('book.direction(filter: string) -> nothing', {
+    ...strategyOnly,
+    planned: true,
+    values: { filter: BOOK_DIRECTIONS },
+  }),
+  entry('book.entryWindow(spec: string) -> nothing', { ...strategyOnly, planned: true }),
+  entry('book.exitAt(time: string) -> nothing', { ...strategyOnly, planned: true }),
+  entry('book.squareOffAtExpiry(minutesBefore?: number = 0) -> nothing', {
+    ...strategyOnly,
+    planned: true,
+  }),
+  entry('book.dailyLoss(amount: number) -> nothing', { ...strategyOnly, planned: true }),
+  entry('book.profit -> series number', { ...strategyOnly, planned: true }),
+  entry('book.dayProfit -> series number', { ...strategyOnly, planned: true }),
+  entry('book.isOpen -> series bool', { ...strategyOnly, planned: true }),
+  entry('book.enter(tag?: string = "") -> nothing', { ...strategyOnly, planned: true }),
+  entry('book.exit(tag?: string = "") -> nothing', { ...strategyOnly, planned: true }),
+];
+
+export const ORDER_ENTRIES: readonly LibraryEntry[] = [
+  ...placing,
+  ...orders,
+  ...position,
+  ...legs,
+  ...book,
+];

package/src/core/check/library-output.ts

@@ -0,0 +1,241 @@
+/**
+ * The part of the library that reaches the chart or the host: `stdlib.md`
+ * sections 13 to 16.
+ *
+ * Two facts about this group drive most of the checking around it. The four
+ * declaration calls and `table` and `input` are top level only, because they
+ * describe the study's fixed shape and that shape is settled before bar 0
+ * (`language.md` 15.3). And the arguments that land in a declaration rather
+ * than in a bar are marked constant, so a value computed from bar data in one
+ * of them is OS3003 rather than something the host discovers it cannot honour.
+ */
+import { DATA_DRIVEN, entry, wholeRange } from './library.js';
+import type { LibraryEntry } from './library.js';
+
+const PLOT_STYLES = ['line', 'lineWithMarkers', 'step', 'area', 'histogram', 'column'];
+const SCALES = ['right', 'left', 'none'];
+const FORMATS = ['price', 'percent', 'volume'];
+const MARKER_AT = ['above', 'below', 'price'];
+const MARKER_SHAPES = [
+  'label',
+  'arrowUp',
+  'arrowDown',
+  'triangleUp',
+  'triangleDown',
+  'circle',
+  'square',
+  'diamond',
+  'cross',
+  'flag',
+];
+const CORNERS = ['topLeft', 'topRight', 'bottomLeft', 'bottomRight'];
+const CELL_ALIGN = ['left', 'center', 'right'];
+const LINE_STYLES = ['solid', 'dashed', 'dotted'];
+const REQUEST_MODES = ['confirmed', 'developing', 'lookahead'];
+const ALERT_FREQUENCIES = ['oncePerBar', 'once', 'everyUpdate'];
+
+/** The two reads of stdlib.md 15.1, which are the only calls that can repaint. */
+export const REQUEST_NAMES: readonly string[] = ['req.timeframe', 'req.symbol'];
+
+/** The calls `language.md` 15.3 puts at the top level, minus `input` and the legs. */
+export const TOP_LEVEL_NAMES: readonly string[] = [
+  'plot',
+  'plotCandles',
+  'fill',
+  'level',
+  'table',
+  'leg.fixed',
+  'leg.relative',
+];
+
+const inputs: readonly LibraryEntry[] = [
+  entry(
+    'input(value: any, title?: string, min?: number, max?: number, step?: number, options?: array<string>, kind?: string, group?: string, tooltip?: string, inline?: string, confirm?: bool) -> any',
+    {
+      topLevel: true,
+      values: { kind: ['interval', 'time', 'symbol', 'price', 'session'] },
+      constant: [
+        'title',
+        'min',
+        'max',
+        'step',
+        'options',
+        'kind',
+        'group',
+        'tooltip',
+        'inline',
+        'confirm',
+      ],
+    },
+  ),
+];
+
+const declarations: readonly LibraryEntry[] = [
+  entry(
+    'plot(value: series number, title: string, color?: color, width?: number, style?: string, offset?: number, overlay?: bool, precision?: number, format?: string, scale?: string) -> plot',
+    {
+      topLevel: true,
+      values: { style: PLOT_STYLES, format: FORMATS, scale: SCALES },
+      constant: ['title', 'width', 'style', 'offset', 'overlay', 'precision', 'format', 'scale'],
+      whole: { precision: wholeRange(0, 10), offset: wholeRange() },
+    },
+  ),
+  entry(
+    'plotCandles(open: series number, high: series number, low: series number, close: series number, title: string, colorUp?: color, colorDown?: color, wickColor?: color, borderColor?: color) -> plot',
+    { topLevel: true, constant: ['title'] },
+  ),
+  entry(
+    'fill(plotA: plot, plotB: plot, color?: color, colorUp?: color, colorDown?: color, opacity?: number, overlay?: bool) -> fill',
+    {
+      topLevel: true,
+      constant: ['opacity', 'overlay'],
+      // One colour for the whole band or one for each side, never both: any
+      // rule for reconciling them surprises somebody (stdlib.md 14.2).
+      conflicts: [
+        ['color', 'colorUp'],
+        ['color', 'colorDown'],
+      ],
+    },
+  ),
+  entry(
+    'level(price: series number, title?: string, color?: color, style?: string, width?: number) -> level',
+    {
+      topLevel: true,
+      values: { style: LINE_STYLES },
+      // A level's colour is one field of the declaration and the format gives it
+      // no per-bar channel, unlike a plot's, so a bar-dependent one has nowhere
+      // to land (`compiled-program.md` 2.8).
+      constant: ['title', 'color', 'style', 'width'],
+    },
+  ),
+  entry(
+    'table(title: string, rows: number, cols: number, position?: string, textColor?: color, bgColor?: color, borderWidth?: number) -> table',
+    {
+      topLevel: true,
+      values: { position: CORNERS },
+      // The grid's own style is declared once, in `options`. A cell's colours
+      // are the per-bar ones, and `cell` takes them.
+      constant: ['title', 'rows', 'cols', 'position', 'textColor', 'bgColor', 'borderWidth'],
+      whole: { rows: wholeRange(1), cols: wholeRange(1) },
+    },
+  ),
+];
+
+const perBar: readonly LibraryEntry[] = [
+  entry('signal(text: string, color?: color, at?: string, shape?: string) -> nothing', {
+    values: { at: MARKER_AT, shape: MARKER_SHAPES },
+    constant: ['color', 'at', 'shape'],
+  }),
+  entry('barColor(color: color) -> nothing'),
+  entry('background(color: color) -> nothing'),
+  entry(
+    'cell(t: table, row: number, col: number, text: string, textColor?: color = none, bgColor?: color = none, align?: string = "left") -> nothing',
+    { values: { align: CELL_ALIGN }, whole: { row: wholeRange(0), col: wholeRange(0) } },
+  ),
+  entry('clear(t: table) -> nothing'),
+  entry('print(value: any) -> nothing'),
+  // Only the message is read per bar. The other three are the entry's own
+  // identity and its firing rule, written into `outputs.alerts` before bar 0,
+  // so a bar-dependent one has nowhere to land (`compiled-program.md` 2.8).
+  entry('alert(message: string, id?: string, title?: string, frequency?: string) -> nothing', {
+    values: { frequency: ALERT_FREQUENCIES },
+    constant: ['id', 'title', 'frequency'],
+  }),
+  entry('notify(message: string, channel: string) -> nothing', { planned: true }),
+];
+
+/**
+ * The four creation calls, with the defaults of `stdlib.md` 14.4 written out.
+ *
+ * These four were the only entries in the library that said what their optional
+ * arguments default to, on the reasoning that a calculation reading an absent
+ * length answers absence, which was thought to be a truthful answer that cost
+ * nothing, while an object created with an absent width is a drawing with no
+ * thickness and nothing is drawn (`language.md` 6.7).
+ *
+ * **The first half of that reasoning was wrong and cost more than the second.**
+ * A length the specification gave and the call dropped is not a length nobody
+ * gave: `atr()` is `atr(14)` in `stdlib.md`, it drew no value on any bar, and
+ * unlike a drawing with no thickness there was nothing on the chart to notice.
+ * Every optional parameter in the library now carries its default, these four
+ * included, and `scripts/check-defaults.mjs` refuses one that does not.
+ *
+ * **A setter says which objects it takes, and takes no others.** Eleven of them
+ * used to write `obj: any` because the real type is a set of kinds and there
+ * was no way to spell one, so `draw.setFrom(aLabel, t, p)` type checked, wrote
+ * an anchor a label has no field for, and drew nothing with nothing reported;
+ * `draw.setColor(5, red)` type checked as readily. The sets below are the
+ * properties each kind actually carries, which is `stdlib.md` 14.4's own table
+ * read down its last column, and a call that misses one is OS3011 at the
+ * argument, before any bar runs.
+ */
+const drawing: readonly LibraryEntry[] = [
+  entry(
+    'draw.line(t1: number, p1: number, t2: number, p2: number, color?: color = gray, width?: number = 1, style?: string = "solid", extendLeft?: bool = false, extendRight?: bool = false) -> line',
+    { values: { style: LINE_STYLES } },
+  ),
+  entry(
+    'draw.label(t: number, p: number, text: string, color?: color = none, textColor?: color = white, align?: string = "center", tooltip?: string = "") -> label',
+  ),
+  entry(
+    'draw.box(t1: number, p1: number, t2: number, p2: number, color?: color = none, fillColor?: color = none, opacity?: number = 0.12, width?: number = 1, text?: string = "", textColor?: color = white, tooltip?: string = "") -> box',
+  ),
+  entry(
+    'draw.polyline(times: array<number>, prices: array<number>, color?: color = gray, width?: number = 1, closed?: bool = false, fillColor?: color = none, opacity?: number = 0.12) -> polyline',
+  ),
+  entry('draw.setFrom(obj: line | box, t: number, p: number) -> nothing'),
+  entry('draw.setTo(obj: line | box, t: number, p: number) -> nothing'),
+  entry(
+    'draw.setBounds(obj: line | box, t1: number, p1: number, t2: number, p2: number) -> nothing',
+  ),
+  entry('draw.setAt(label: label, t: number, p: number) -> nothing'),
+  entry(
+    'draw.setPoints(polyline: polyline, times: array<number>, prices: array<number>) -> nothing',
+  ),
+  entry('draw.setText(obj: label | box, text: string) -> nothing'),
+  entry('draw.setColor(obj: line | label | box | polyline, color: color) -> nothing'),
+  entry('draw.setTextColor(obj: label | box, color: color) -> nothing'),
+  entry('draw.setFillColor(obj: box | polyline, color: color) -> nothing'),
+  entry('draw.setWidth(obj: line | box | polyline, width: number) -> nothing'),
+  entry('draw.setStyle(obj: line, style: string) -> nothing', { values: { style: LINE_STYLES } }),
+  entry('draw.setExtend(line: line, left: bool, right: bool) -> nothing'),
+  entry('draw.setTooltip(obj: label | box, text: string) -> nothing'),
+  entry('draw.delete(obj: line | label | box | polyline) -> nothing'),
+  entry('draw.deleteAll() -> nothing'),
+  entry('draw.count() -> number'),
+];
+
+const requests: readonly LibraryEntry[] = [
+  // Not planned, and deliberately so: a target script uses a higher timeframe
+  // read, so the language has it in version one and the checker accepts it.
+  //
+  // The engine is what does not execute a request body yet, and the format
+  // already has the honest way to say that: the program carries a `req.timeframe`
+  // capability tag, and an engine without it refuses at load with OS6006 naming
+  // the capability. That is a third legitimate state beside "runs" and
+  // "planned", and it is the one the compiled format was designed for, because
+  // it is how an old engine tells a new program what it is missing.
+  entry('req.timeframe(timeframe: string, expr: T, mode?: string = "confirmed") -> T', {
+    warmup: DATA_DRIVEN,
+    values: { mode: REQUEST_MODES },
+  }),
+  entry(
+    'req.symbol(symbol: string, timeframe: string, expr: T, exchange?: string = chart.exchange, mode?: string = "confirmed") -> T',
+    {
+      warmup: DATA_DRIVEN,
+      values: { mode: REQUEST_MODES },
+    },
+  ),
+  entry('req.isReady(read: any) -> series bool'),
+  entry('req.error(read: any) -> series string'),
+  entry('req.candle(timeframe: string, mode?: string) -> array<number>', { planned: true }),
+  entry('req.events(kind: string) -> series number', { planned: true }),
+];
+
+export const OUTPUT_ENTRIES: readonly LibraryEntry[] = [
+  ...inputs,
+  ...declarations,
+  ...perBar,
+  ...drawing,
+  ...requests,
+];