oakscriptjs 0.13.0 → 0.13.2

package/skills/oakscript/reference/strategies.md

@@ -0,0 +1,140 @@
+# Strategies
+
+A strategy is a script declared with `strategy()` whose orders go to an order engine. OakScriptJS does not fill
+orders itself: the host supplies the engine (an app's backtester, or your own), which fills the orders, keeps the
+trades and computes the results the host shows (net profit, drawdown, list of trades...).
+
+## Declaration and sizing
+
+```js
+strategy("Breakout", {
+  overlay: true,                                   // default false
+  initial_capital: 10000,                          // default 100000
+  default_qty_type: strategy.percent_of_equity,    // or strategy.fixed (units), strategy.cash (amount)
+  default_qty_value: 25,                           // default 100 (% of equity)
+  pyramiding: 0,                                   // entries allowed in the same direction beyond the first
+  commission_type: strategy.commission.percent,    // or .cash_per_contract, .cash_per_order
+  commission_value: 0.1,
+  slippage: 2,                                     // ticks added to market and stop fills
+});
+const length = input.int(20, "Channel length", { minval: 2 });
+const upper = ta.highest(high, length).offset(1);
+const lower = ta.lowest(low, length).offset(1);
+plot(upper, "Upper", { color: color.green });
+plot(lower, "Lower", { color: color.red });
+strategy.eachBar((c) => {
+  if (strategy.position_size <= 0) strategy.entry("Long", strategy.long, { stop: c.get(upper) });
+  if (strategy.position_size >= 0) strategy.entry("Short", strategy.short, { stop: c.get(lower) });
+});
+```
+
+Other properties, with the Pine Script v6 names and defaults: `currency`, `margin_long` / `margin_short` (100),
+`process_orders_on_close` (false), `close_entries_rule` (`"FIFO"`), `calc_on_order_fills`, `calc_on_every_tick`,
+`use_bar_magnifier`, `fill_orders_on_standard_ohlc`, `backtest_fill_limits_assumption`, `risk_free_rate` (2).
+A host can override them from its settings.
+
+Order size: the `qty` option of an order (units) wins over `default_qty_type` / `default_qty_value`.
+
+## The bar loop
+
+`strategy.eachBar((c) => ...)` is the strategy's `eachBar` (same `c`, returns a Series) and runs once per script.
+On each bar:
+
+1. the engine fills the orders placed before (market orders at the bar's open; stop / limit orders when the
+   bar reaches their price);
+2. the callback runs at the bar's close: read the state, place, change or cancel orders;
+3. with `process_orders_on_close: true`, new market orders fill at that close; else at the next bar's open.
+
+Order calls and per-bar `strategy.*` reads throw outside `strategy.eachBar()`. Compute every Series before it.
+
+## Orders
+
+| Call | Use |
+|---|---|
+| `strategy.entry(id, strategy.long / strategy.short, { qty, limit, stop, oca_name, oca_type, comment, alert_message })` | open a position; an entry in the other direction reverses the position; market order without `limit` / `stop` |
+| `strategy.order(id, direction, { qty, limit, stop, ... })` | a raw order: adds to or reduces the position, no reversal logic |
+| `strategy.exit(id, { from_entry, qty, qty_percent, stop, limit, loss, profit, trail_price, trail_points, trail_offset, comment, ... })` | stop loss / take profit / trailing stop for an entry; `stop` / `limit` / `trail_price` are prices, `loss` / `profit` / `trail_points` / `trail_offset` are in ticks |
+| `strategy.close(id, { qty, qty_percent, comment, immediately })` | close the trades of entry `id` at market |
+| `strategy.close_all({ comment, immediately })` | close the whole position at market |
+| `strategy.cancel(id)`, `strategy.cancel_all()` | cancel pending orders |
+
+- A call with the id of a pending order changes that order (calling `strategy.exit` on every bar with new prices
+  moves the stop).
+- `NaN` in an option means "not given" (it is removed), as `na` in Pine.
+- `strategy.exit` placed while the entry is still pending waits for it (`from_entry`).
+
+```js
+strategy("Trailing exit", { overlay: true, initial_capital: 10000, default_qty_type: strategy.fixed, default_qty_value: 10 });
+const fast = ta.ema(close, 12);
+const slow = ta.ema(close, 26);
+const atr = ta.atr(14);
+const goLong = ta.crossover(fast, slow);
+const goFlat = ta.crossunder(fast, slow);
+strategy.eachBar((c) => {
+  if (c.get(goLong) === 1) strategy.entry("Long", strategy.long, { comment: "EMA cross" });
+  if (c.get(goFlat) === 1) strategy.close("Long", { comment: "Cross down" });
+  if (strategy.position_size > 0) {
+    const trade = strategy.opentrade(0);                     // Pine strategy.opentrades.*(0)
+    const stop = trade.entry_price - 2 * c.get(atr);
+    strategy.exit("Stop", { from_entry: "Long", stop, comment: "ATR stop" });
+  }
+});
+plot(fast, "Fast");
+plot(slow, "Slow");
+```
+
+## Reading the results
+
+Inside `strategy.eachBar()`, from the engine, for the current bar:
+
+| Variable | Meaning |
+|---|---|
+| `strategy.position_size` | signed quantity: > 0 long, < 0 short, 0 flat |
+| `strategy.position_avg_price`, `strategy.position_entry_name` | average entry price (NaN when flat), entry id |
+| `strategy.equity`, `strategy.initial_capital` | initial capital + net profit + open profit |
+| `strategy.netprofit`, `strategy.openprofit`, `strategy.grossprofit`, `strategy.grossloss` (and `_percent`) | profits |
+| `strategy.opentrades`, `strategy.closedtrades`, `strategy.wintrades`, `strategy.losstrades`, `strategy.eventrades` | trade counts |
+| `strategy.max_drawdown`, `strategy.max_runup`, `strategy.avg_trade`... | statistics |
+| `strategy.opentrade(i)`, `strategy.closedtrade(i)` | trade `i` (0 = oldest): `{ entry_id, entry_price, entry_bar_index, entry_time, size, profit, commission, exit_price, exit_bar_index, ... }`, undefined when there is none |
+| `strategy.default_entry_qty(price)` | the quantity a default-size entry would get |
+
+Pine's `strategy.closedtrades.profit(i)` is `strategy.closedtrade(i)?.profit`. `strategy.initial_capital` and
+`strategy.account_currency` can be read anywhere.
+
+```js
+strategy("Equity curve", { overlay: false, initial_capital: 5000, default_qty_type: strategy.cash, default_qty_value: 1000 });
+strategy.risk.allow_entry_in(strategy.direction.long);   // risk rules: top level, after strategy()
+const rsi = ta.rsi(close, 14);
+const equity = strategy.eachBar((c) => {
+  if (c.get(rsi) < 30) strategy.entry("Long", strategy.long);
+  if (c.get(rsi) > 70) strategy.close_all({ comment: "RSI > 70" });
+  const last = strategy.closedtrade(strategy.closedtrades - 1);
+  if (last && last.exit_bar_index === c.i && last.profit < 0) alert("Losing trade closed");
+  return strategy.equity;                                // the loop's Series: equity per bar
+});
+plot(equity, "Equity", { color: color.teal });
+hline(5000, "Initial capital", { color: color.gray });
+```
+
+Risk rules: `strategy.risk.allow_entry_in(dir)`, `max_drawdown(value, type)`, `max_intraday_loss(value, type)`,
+`max_cons_loss_days(count)`, `max_intraday_filled_orders(count)`, `max_position_size(contracts)` (type:
+`"percent_of_equity"` or `"cash"`). An engine that does not support a rule or a variable throws
+"... is not provided by the strategy engine".
+
+## The host side
+
+A host passes an engine factory to `executeScript`:
+
+```ts
+import { executeScript, type StrategyEngine } from 'oakscriptjs/script';
+
+const run = executeScript(body, bars, inputs, chart, {
+  strategyEngine: ({ properties, bars, chart }) => new MyEngine(properties, bars), // implements StrategyEngine
+});
+// run.strategyConfig: the resolved properties
+```
+
+`StrategyEngine` methods: `processBar(i)`, `processClose(i)`, `entry`, `order`, `exit`, `close`, `close_all`,
+`cancel`, `cancel_all`, `get(variable)`, `openTrade(i)`, `closedTrade(i)`, and optionally `risk(rule)`,
+`defaultEntryQty(price)`. The option objects keep the Pine names. Without an engine, `strategy()` declares the
+strategy and `strategy.eachBar()` throws "no strategy engine".

package/skills/oakscript/reference/timeframes-symbols.md

@@ -0,0 +1,93 @@
+# Other timeframes and symbols
+
+## request.security
+
+`request.security(symbol, timeframe, expression, gaps?, lookahead?, ignore_invalid_symbol?)` runs `expression` on
+the bars of `symbol` on `timeframe` and returns its values aligned on the chart bars (a Series).
+
+- `symbol`: `""` or `syminfo.tickerid` for the chart symbol, a ticker id (`"NASDAQ:AAPL"`, from
+  `input.symbol`) for another one, `ticker.heikinashi(syminfo.tickerid)` for Heikin Ashi bars.
+- `timeframe`: `"1"`, `"5"`, `"60"`, `"240"`, `"D"`, `"W"`, `"M"`, `"2D"`...; `""` is the chart timeframe.
+- `expression`: a **function** that computes the series. Everything it needs on that timeframe is computed
+  inside it: `() => ta.ema(close, 20)`. A Series computed outside runs on the chart bars, and the call throws
+  "the expression returned a series computed on the chart bars".
+- Return an array for several values (a Pine tuple): `const [h, l] = request.security("", "D", () => [high, low]);`
+- Inputs and plain numbers from outside can be used inside (`() => ta.ema(close, length)`).
+
+```js
+indicator("Daily levels", { overlay: true });
+const length = input.int(20, "Daily EMA length", { minval: 1 });
+const dailyEma = request.security("", "D", () => ta.ema(close, length));
+const [prevHigh, prevLow] = request.security("", "D", () => [high.offset(1), low.offset(1)]);
+plot(dailyEma, "Daily EMA", { color: color.orange, style: plot.style_stepline });
+plot(prevHigh, "Previous day high", { color: color.green, style: plot.style_linebr });
+plot(prevLow, "Previous day low", { color: color.red, style: plot.style_linebr });
+```
+
+### Lookahead and gaps
+
+- `barmerge.lookahead_off` (default): a higher-timeframe value appears on the chart bar that completes its
+  period; before that, the bars show the previous period's value. This is the setting without future leak.
+- `barmerge.lookahead_on`: the value of the period appears from its first chart bar. With a series that is not
+  offset (`close`, `ta.ema(close, 20)`) this reads the future on history bars: use it only with
+  `high.offset(1)`-style expressions (the previous period) or for display.
+- `barmerge.gaps_on`: the value only on the bar where it appears, NaN elsewhere (use `plot.style_linebr`).
+
+```js
+indicator("Weekly open", { overlay: true });
+const weekOpen = request.security("", "W", () => open, barmerge.gaps_off, barmerge.lookahead_on);
+plot(weekOpen, "Week open", { color: color.purple, style: plot.style_stepline });
+```
+
+### Other symbols
+
+```js
+indicator("Relative strength", { overlay: false });
+const other = input.symbol("NASDAQ:AAPL", "Compare with");
+const otherClose = request.security(other, "", () => close);
+const ratio = close.div(otherClose);
+plot(ratio, "Ratio", { color: color.blue });
+plot(ta.sma(ratio, 50), "Ratio SMA", { color: color.orange });
+```
+
+The library fetches nothing: the host gives the bars of the other symbol. An app loads them when the script asks
+(the first run reports what it needs, the app loads it and runs again); in your own `executeScript` call, pass
+`bars(symbol, timeframe)` and `symbolInfo(symbol)` in the chart context and catch `MissingSymbolDataError`
+(`error.requests` lists the `{ symbol, timeframe }` to load). A symbol with no bars stops the script with
+"Invalid symbol: X" (or gives NaN with `ignore_invalid_symbol = true`).
+
+The values are merged by time: with lookahead off a chart bar shows the last bar of the other symbol that closed
+at or before its own close.
+
+### Lower timeframes
+
+`request.security` on a timeframe below the chart's reads the lower-timeframe bars (given by the host as for
+another symbol) and shows, per chart bar, the value on the last lower bar inside it.
+`request.security_lower_tf(symbol, timeframe, expression)` returns, for each chart bar, an **array of numbers**:
+the values on all the lower bars inside that bar (a plain `number[][]`, not a Series). Read it in a bar loop:
+
+```js
+indicator("Intrabar up volume", { overlay: false });
+const vols = request.security_lower_tf("", "15", () => volume.mul(close.gt(open).iff(1, 0)));
+const upVolume = eachBar((c) => vols[c.i].reduce((sum, v) => sum + v, 0));
+plot(upVolume, "Up volume", { style: plot.style_columns, color: color.teal });
+```
+
+## Timeframe values
+
+- `timeframe.period` (`"60"`, `"1D"`...), `timeframe.multiplier`, `timeframe.isintraday`, `timeframe.isdaily`,
+  `timeframe.isweekly`, `timeframe.ismonthly`, `timeframe.isdwm`, `timeframe.isminutes`, `timeframe.isseconds`.
+- `timeframe.change("D")`: 1 on the first chart bar of each new period.
+- `timeframe.in_seconds(tf?)`, `timeframe.from_seconds(s)`.
+- `input.timeframe("D", "Timeframe")` lets the user choose; `""` is the chart timeframe.
+- `time("D")`, `time("240", "0930-1600")`: open time of the period of each bar, NaN outside the session.
+
+A timeframe below the chart's with `request.security_lower_tf` and a higher one with `request.security` are the
+normal cases; `request.security_lower_tf` on a higher timeframe throws.
+
+## What the host must give
+
+Session-aware values (`request.security` on another timeframe, `time()`, `timeframe.change`, `session.*`,
+`ta.vwap` on an intraday chart) need the chart timeframe, the exchange time zone and the session. An app gives
+them; a direct `executeScript` call passes `{ timeframe, timezone, session }` in the chart context
+(`session: "24x7"` for a symbol that always trades, `"0930-1600"` for regular stock hours).

package/src/index.ts

@@ -224,7 +224,7 @@ export type { LightweightSeriesDefinitions } from './runtime/adapters/Lightweigh
 export { SimpleInputAdapter } from './runtime/adapters/SimpleInputAdapter.js';
 
 // Version
-export const VERSION = '0.12.3';
+export const VERSION = '0.13.2';
 
 /**
  * Library information

package/src/script/index.ts

@@ -338,6 +338,9 @@ export interface ScriptOptions {
 
 let scriptOptions: ScriptOptions = {};
 
+/** The `varip` values of a replayed bar in a script without `varip`. */
+const NO_VARIP: unknown[] = [];
+
 /** Intrabar run of the current run (see {@link executeIntrabar}); null in a main run. */
 interface IntrabarRun {
   /** The bar calculated inside the bar: the last bar of the run. */
@@ -474,7 +477,7 @@ export function executeScript(
         barColors: c.barColors.length ? c.barColors : undefined,
         plotCandles: Object.keys(c.plotCandles).length ? c.plotCandles : undefined,
         plotBars: Object.keys(c.plotBars).length ? c.plotBars : undefined,
-        ...drawingOutputs(ctxBars.bars, chartCtx.timeUnit),
+        ...(intrabarRun ? {} : drawingOutputs(ctxBars.bars, chartCtx.timeUnit)),
         alerts: c.alerts.length ? c.alerts : undefined,
         alertCalls: c.alertCalls.length ? c.alertCalls : undefined,
       },
@@ -943,6 +946,7 @@ export const DEFAULT_OUTPUT_TITLES = {
 
 /** PineScript `plot()` — declares the plot and supplies its data in one call. */
 function plotImpl(series: Series, title: string = DEFAULT_OUTPUT_TITLES.plot, options: ScriptPlotOptions = {}): PlotHandle {
+  if (intrabarRun) return { id: '', kind: 'plot' }; // dropped: an intrabar run's outputs aren't read
   const c = collector();
   const id = `plot${c.plotConfig.length}`;
   const perBar = Array.isArray(options.color) ? options.color : undefined;
@@ -1077,6 +1081,7 @@ export function fill(
   ...rest: unknown[]
 ): void;
 export function fill(a: PlotHandle, b: PlotHandle, ...args: unknown[]): void {
+  if (intrabarRun) return; // dropped: an intrabar run's outputs aren't read
   const c = collector();
   const third = args[0];
   let perBar: string[] | undefined;
@@ -1219,6 +1224,7 @@ function emitMarkers(
   title: string | undefined,
   options: PlotShapeOptions & PlotCharOptions
 ): void {
+  if (intrabarRun) return; // dropped: an intrabar run's outputs aren't read
   const c = collector();
   const id = `${kind}${c.shapeConfig.filter((s) => s.kind === kind).length}`;
   title ??= DEFAULT_OUTPUT_TITLES[kind];
@@ -1302,6 +1308,7 @@ export interface PlotArrowOptions {
  * `arrowConfig`; the renderer scales the height with the absolute value between minheight and maxheight.
  */
 export function plotarrow(series: Series, title?: string, options: PlotArrowOptions = {}): void {
+  if (intrabarRun) return; // dropped: an intrabar run's outputs aren't read
   const c = collector();
   const id = `arrow${c.arrowConfig.length}`;
   title ??= DEFAULT_OUTPUT_TITLES.arrow;
@@ -1345,6 +1352,7 @@ function emitBarColors(
   colors: string | Array<string | undefined>,
   options: { offset?: number; title?: string; force_overlay?: boolean; editable?: boolean }
 ): void {
+  if (intrabarRun) return; // dropped: an intrabar run's outputs aren't read
   const c = collector();
   const id = `${kind}${c.barColorConfig.filter((x) => x.kind === kind).length}`;
   c.barColorConfig.push({
@@ -1478,6 +1486,7 @@ export function plotcandle(
   title?: string,
   options: PlotCandleOptions = {}
 ): void {
+  if (intrabarRun) return; // dropped: an intrabar run's outputs aren't read
   const c = collector();
   const color = orDefault(options.color, DEFAULT_CANDLE_COLORS.color);
   const wickcolor = orDefault(options.wickcolor, DEFAULT_CANDLE_COLORS.wickColor);
@@ -1523,6 +1532,7 @@ export function plotbar(
   title?: string,
   options: PlotBarOptions = {}
 ): void {
+  if (intrabarRun) return; // dropped: an intrabar run's outputs aren't read
   const c = collector();
   const barColor = orDefault(options.color, DEFAULT_CANDLE_COLORS.color);
   const id = `plotbar${c.candleConfig.filter((x) => x.kind === 'bar').length}`;
@@ -1800,11 +1810,18 @@ function strategyEachBar(fn: (c: BarContext) => number | boolean | void): Series
     // Intrabar run: the bars before replay the main run's answers, the bar itself calls the engine (whose
     // orders the host is filling: no processBar / processClose).
     const varipState = varipRun;
+    const replayLog: { answers: readonly unknown[]; next: number } = { answers: [], next: 0 };
+    const replayed = replayEngine(replayLog);
     return eachBar((c) => {
       const replay = c.i < intrabar.bar;
-      run.engine = replay ? replayEngine(intrabar.recorder.answers[c.i] ?? []) : intrabar.engine;
+      if (replay) {
+        replayLog.answers = intrabar.recorder.answers[c.i] ?? [];
+        replayLog.next = 0;
+      }
+      run.engine = replay ? replayed : intrabar.engine;
       varipState.mode = replay ? 'replay' : 'live';
-      varipState.scratch = replay ? [...(intrabar.recorder.varipStarts[c.i] ?? intrabar.recorder.varip)] : null;
+      const starts = replay ? intrabar.recorder.varipStarts[c.i] ?? intrabar.recorder.varip : null;
+      varipState.scratch = starts ? (starts.length ? [...starts] : NO_VARIP) : null;
       run.inLoop = true;
       try {
         return fn(c);
@@ -1850,9 +1867,8 @@ function recordingEngine(engine: StrategyEngine, log: unknown[]): StrategyEngine
 }
 
 /** An engine that gives back recorded answers in order and drops the order calls (a replayed bar). */
-function replayEngine(log: readonly unknown[]): StrategyEngine {
-  let k = 0;
-  const next = <T>(): T => log[k++] as T;
+function replayEngine(log: { answers: readonly unknown[]; next: number }): StrategyEngine {
+  const next = <T>(): T => log.answers[log.next++] as T;
   const none = (): void => {};
   return {
     processBar: none,
@@ -2477,6 +2493,27 @@ function barFlag(test: (i: number, n: number) => boolean): Series {
   return Series.fromArray(ctxBars, Array.from({ length: n }, (_, i) => (test(i, n) ? 1 : 0)));
 }
 
+/**
+ * An intrabar run reads the flag on the same bars as the run before, with at most one bar more, and the flags only
+ * differ on their last bars: the values are kept between runs (the series only reads them).
+ */
+const FLAG_TAIL = 3;
+const flagValues = new Map<string, number[]>();
+function namedFlag(name: string, test: (i: number, n: number) => boolean): Series {
+  if (!intrabarRun) return barFlag(test);
+  const n = ctxBars.bars.length;
+  let values = flagValues.get(name);
+  if (!values || values.length > n) {
+    values = Array.from({ length: n }, (_, i) => (test(i, n) ? 1 : 0));
+    flagValues.set(name, values);
+  } else {
+    const from = Math.max(0, Math.min(values.length, n) - FLAG_TAIL);
+    values.length = n;
+    for (let i = from; i < n; i++) values[i] = test(i, n) ? 1 : 0;
+  }
+  return Series.fromArray(ctxBars, values);
+}
+
 /** Number of bars of the chart: an intrabar run ends before the chart's last bar. */
 const chartBarCount = (n: number): number => (intrabarRun ? intrabarRun.lastBarIndex + 1 : n);
 
@@ -2490,14 +2527,14 @@ const lastRealtime = (i: number, n: number): boolean => i === n - 1 && chartCtx.
  * `islastconfirmedhistory` is the last bar when it is confirmed and not realtime, else the bar before it.
  */
 export const barstate = {
-  get isfirst(): Series { return barFlag((i) => i === 0); },
-  get islast(): Series { return barFlag((i, n) => i === chartBarCount(n) - 1); },
-  get isconfirmed(): Series { return barFlag((i, n) => i < n - 1 || chartCtx.lastBarConfirmed === true); },
-  get isrealtime(): Series { return barFlag(lastRealtime); },
-  get ishistory(): Series { return barFlag((i, n) => !lastRealtime(i, n)); },
-  get isnew(): Series { return barFlag((i, n) => !lastRealtime(i, n) || chartCtx.lastBarNew !== false); },
+  get isfirst(): Series { return namedFlag('isfirst', (i) => i === 0); },
+  get islast(): Series { return namedFlag('islast', (i, n) => i === chartBarCount(n) - 1); },
+  get isconfirmed(): Series { return namedFlag('isconfirmed', (i, n) => i < n - 1 || chartCtx.lastBarConfirmed === true); },
+  get isrealtime(): Series { return namedFlag('isrealtime', lastRealtime); },
+  get ishistory(): Series { return namedFlag('ishistory', (i, n) => !lastRealtime(i, n)); },
+  get isnew(): Series { return namedFlag('isnew', (i, n) => !lastRealtime(i, n) || chartCtx.lastBarNew !== false); },
   get islastconfirmedhistory(): Series {
-    return barFlag((i, n) => {
+    return namedFlag('islastconfirmedhistory', (i, n) => {
       const lastConfirmed = chartCtx.lastBarConfirmed === true && chartCtx.realtime !== true;
       const count = chartBarCount(n);
       return i === (lastConfirmed ? count - 1 : count - 2);