oakscriptjs 0.11.0 → 0.11.2

package/src/script/index.ts

@@ -96,8 +96,9 @@ import * as strCore from '../str/index.js';
 import { formatMessage } from '../str/messageformat.js';
 import { tickScale } from '../str/numberformat.js';
 import { TradingCalendar, type SessionSpec } from '../session/calendar.js';
-import { SessionBars, sessionFlags, type SessionFlags } from '../session/bars.js';
+import { SessionBars, sessionFlags, strayPeriods, type SessionFlags } from '../session/bars.js';
 import { afterCompletion, heikinAshi, mapToChart, periodsOf, resample } from '../security/resample.js';
+import { securityLowerTf, securityOther, type OtherSymbolChart } from '../security/other.js';
 import { position } from '../types/index.js';
 import type { ChartPoint } from '../types/index.js';
 import {
@@ -121,7 +122,7 @@ import {
   type StrategyTrade,
   type StrategyVariable,
 } from '../strategy/index.js';
-import { parsePineSession } from '../time/session.js';
+import { sessionPeriods, type SessionPeriods } from '../session/context.js';
 
 /** Everything one run of a script produced. */
 export interface ScriptRunResult {
@@ -302,8 +303,10 @@ export function executeScript(
   ctx = freshCollector(inputs);
   resetDrawings();
   mathCore.resetRandom();
+  missingSymbols = [];
   try {
     body();
+    if (missingSymbols.length) throw new MissingSymbolDataError(missingSymbols);
     const c = ctx;
     return {
       metadata: {
@@ -480,6 +483,10 @@ export const input = {
       'input_session'
     );
   },
+  /** Ticker id ("NASDAQ:MSFT"), for `request.security` of another symbol (#180). */
+  symbol(defval: string, title?: string, opts: StringInputOptions = {}): string {
+    return registerInput<string>({ type: 'symbol', defval, title, options: opts.options, ...common(opts) }, 'input_symbol');
+  },
   /** Date and time as a UNIX time in milliseconds, e.g. `input.time(timestamp('2024-01-01'), 'Start')`. */
   time(defval: number, title?: string, opts: InputOptions = {}): number {
     const v = registerInput<unknown>({ type: 'time', defval, title, ...common(opts) }, 'input_time');
@@ -564,12 +571,12 @@ export const ta = {
     typeof sourceOrLength === 'number'
       ? taSeries.lowestbars(low, sourceOrLength)
       : taSeries.lowestbars(sourceOrLength, length!),
-  /** `ta.vwap(source, anchor?, stdev_mult?)` with the chart volume; the default anchor is a new trading
-   *  day (`timeframe.change("1D")`), which needs the chart context (timeframe, time zone, session), and the
-   *  first bar: as in PineScript, the first loaded bars (a day in progress) have a value. */
+  /** `ta.vwap(source, anchor?, stdev_mult?)` with the chart volume; the default anchor is a new trading day
+   *  and the first bar: as in PineScript, the first loaded bars (a day in progress) have a value. On D / W / M
+   *  charts every bar is a new day (no time zone or session needed); on intraday charts it needs the chart context
+   *  (timeframe, time zone, session). */
   vwap: ((source: Series, anchor?: Series, stdev_mult?: number): Series | [Series, Series, Series] => {
-    // PineScript default: timeframe.change("1D"); the sums also start on the first bar (a day in progress)
-    const a = anchor ?? changeOf('1D', true);
+    const a = anchor ?? vwapAnchor();
     return stdev_mult === undefined ? taSeries.vwap(source, volume, a) : taSeries.vwapBands(source, volume, a, stdev_mult);
   }) as {
     (source: Series, anchor?: Series): Series;
@@ -1266,7 +1273,7 @@ export function eachBar(fn: (c: BarContext) => number | boolean | void): Series
     for (idx = 0; idx < b.length; idx++) {
       if (pendingError && pendingError.bar === idx) throw new Error(historyError(idx, pendingError.barsBack));
       currentBar = idx;
-      setDrawingBar(idx, idx === b.length - 1);
+      setDrawingBar(idx, idx === b.length - 1, b.length - 1);
       const r = fn(ctx);
       out[idx] = typeof r === 'number' ? r : typeof r === 'boolean' ? (r ? 1 : 0) : NaN;
       // grow the history buffers from the largest reference of this bar
@@ -1557,6 +1564,13 @@ export interface ChartContext {
   symbolType?: string;
   /** Currency of the symbol (PineScript `syminfo.currency`), e.g. "USD" */
   currency?: string;
+  /**
+   * Base currency of the symbol (PineScript `syminfo.basecurrency`): "BTC" for BITSTAMP:BTCUSD, BINANCE:BTCUSDT.P and
+   * CME:BTC1!, "EUR" for FX:EURUSD, "" for a stock, an index or CME_MINI:ES1! (#180)
+   */
+  basecurrency?: string;
+  /** Root of the symbol (PineScript `syminfo.root`): "BTC" for CME:BTC1!, "ES" for CME_MINI:ES1!, "AAPL" for NASDAQ:AAPL (#180) */
+  root?: string;
   /** Chart foreground colour (PineScript `chart.fg_color`), e.g. "#DBDBDB" on a dark chart */
   foregroundColor?: string;
   /** Chart background colour (PineScript `chart.bg_color`), e.g. "#0F0F0F" on a dark chart */
@@ -1572,8 +1586,60 @@ export interface ChartContext {
   realtime?: boolean;
   /** On a realtime last bar: this run is the first update of the bar (`barstate.isnew`); default true. */
   lastBarNew?: boolean;
+  /**
+   * Bars of another symbol for `request.security(symbol, timeframe, ...)` (#179): the bars of `symbol` (the ticker id
+   * as written in the script, e.g. "NASDAQ:MSFT") on `timeframe` (the chart timeframe for ""), oldest first, times in
+   * `timeUnit`. Return undefined when they are not loaded: the run then ends with a {@link MissingSymbolDataError}
+   * that lists every request, so the host can load them and run again. Return [] for a symbol that does not exist.
+   */
+  bars?: (symbol: string, timeframe: string) => Bar[] | undefined;
+  /**
+   * Calendar and properties of another symbol: its time zone and session give the close times and trading days that
+   * `request.security` merges on (#179), and the other fields its `syminfo.*` inside the expression.
+   */
+  symbolInfo?: (symbol: string) => SymbolInfo | undefined;
+}
+
+/** Calendar and properties of a symbol, as in {@link ChartContext}. */
+export type SymbolInfo = Pick<
+  ChartContext,
+  | 'timezone'
+  | 'session'
+  | 'regularSession'
+  | 'mintick'
+  | 'minmove'
+  | 'pricescale'
+  | 'pointvalue'
+  | 'mincontract'
+  | 'symbolType'
+  | 'currency'
+  | 'basecurrency'
+  | 'root'
+>;
+
+/** A request of `request.security` for another symbol whose bars the host has not given. */
+export interface SymbolDataRequest {
+  symbol: string;
+  timeframe: string;
+}
+
+/**
+ * Thrown by `executeScript` when `request.security` asked for bars of another symbol that `ChartContext.bars` did not
+ * give (#179). `requests` lists them all, once each: load them, then run the script again.
+ */
+export class MissingSymbolDataError extends Error {
+  constructor(readonly requests: SymbolDataRequest[]) {
+    super(
+      `request.security needs the bars of ${requests.map((r) => `${r.symbol} (${r.timeframe})`).join(', ')}: ` +
+        'pass them with ChartContext.bars.'
+    );
+    this.name = 'MissingSymbolDataError';
+  }
 }
 
+/** Requests of other symbols without bars in the current run. */
+let missingSymbols: SymbolDataRequest[] = [];
+
 let chartCtx: ChartContext = {};
 
 function chartTimeframe(): timeframeCore.TimeframeInfo {
@@ -1655,7 +1721,7 @@ function symbolProperty(key: 'mintick' | 'pointvalue' | 'mincontract'): number {
 }
 
 /** A text value of the chart or the symbol that the host passes in the chart context. */
-function chartText(key: 'symbolType' | 'currency' | 'foregroundColor' | 'backgroundColor', name: string): string {
+function chartText(key: 'symbolType' | 'currency' | 'basecurrency' | 'root' | 'foregroundColor' | 'backgroundColor', name: string): string {
   collector();
   const value = chartCtx[key];
   if (value === undefined) {
@@ -1675,8 +1741,8 @@ function symbolScale(): [number, number] {
 
 /**
  * PineScript `syminfo.timezone`, `syminfo.tickerid`, `syminfo.session` (session type), `syminfo.mintick`,
- * `syminfo.minmove`, `syminfo.pricescale`, `syminfo.pointvalue`, `syminfo.mincontract`, `syminfo.type` and
- * `syminfo.currency`, from the chart context.
+ * `syminfo.minmove`, `syminfo.pricescale`, `syminfo.pointvalue`, `syminfo.mincontract`, `syminfo.type`,
+ * `syminfo.currency`, `syminfo.basecurrency` and `syminfo.root`, from the chart context.
  */
 export const syminfo = {
   get mintick(): number {
@@ -1714,6 +1780,12 @@ export const syminfo = {
   get currency(): string {
     return chartText('currency', 'syminfo.currency');
   },
+  get basecurrency(): string {
+    return chartText('basecurrency', 'syminfo.basecurrency');
+  },
+  get root(): string {
+    return chartText('root', 'syminfo.root');
+  },
 };
 
 /** A calendar function: `(time, timezone?)` on a UNIX time or on a Series of times. */
@@ -1822,36 +1894,6 @@ function sessionBars(): { bars: SessionBars; regular: SessionBars } {
   return sessionCache;
 }
 
-/**
- * Calendar for `time(tf, session, timezone)` arguments. Without session and time zone: the loaded
- * session. As in PineScript, an explicit time zone reads the symbol session hours in that zone without
- * corrections and holidays, and an explicit session follows PineScript's session string rules.
- */
-function calendarFor(
-  session?: string,
-  timezone?: string
-): { bars: SessionBars; test: boolean; inside?: (time: number) => boolean } {
-  const { bars } = sessionBars();
-  if (!session && !timezone) return { bars, test: false };
-  const tz = timezone ?? exchangeTimezone();
-  // a session string that is empty or does not start with a digit is the symbol session: "regular" the regular
-  // hours, "extended" and any other name the loaded hours (PineScript)
-  if (session !== undefined && parsePineSession(session) === null) {
-    const name = session.trim();
-    const symbol = name === 'regular' && chartCtx.regularSession ? chartCtx.regularSession : chartCtx.session!;
-    return { bars: new SessionBars(new TradingCalendar(tz, { session: toSpec(symbol).session }, 'symbol'), bars.chart.period), test: true };
-  }
-  const spec = session ? { session } : { session: toSpec(chartCtx.session!).session };
-  return {
-    bars: new SessionBars(new TradingCalendar(tz, spec, session ? 'pine' : 'symbol'), bars.chart.period),
-    test: true,
-    // a PineScript session string: the rules of time.inSession (runs ending at 0000, days around a clock change)
-    inside: session
-      ? (time) => timeCore.inSession(time, session, tz, timeframeCore.in_seconds(bars.chart.period) * 1000)
-      : undefined,
-  };
-}
-
 function perBar(fn: (t: number, i: number, times: number[]) => number): Series {
   const times = ctxBars.bars.map(barTime);
   return Series.fromArray(ctxBars, times.map((t, i) => fn(t, i, times)));
@@ -1864,18 +1906,22 @@ function callableSeries<F extends (...args: never[]) => Series>(series: Series,
   return fn as Series & F;
 }
 
+/** `time(tf, session, timezone)` / `time_close(...)` periods of the run's chart (see session/context `sessionPeriods`). */
+function chartSessionPeriods(timeframeString: string, session?: string, timezone?: string): SessionPeriods {
+  const { bars } = sessionBars();
+  return sessionPeriods(bars, { ...chartCtx, timezone: exchangeTimezone() }, timeframeString, session, timezone);
+}
+
 function timeFunction(tf?: string, session?: string, timezone?: string): Series {
   collector();
-  const { bars, test, inside } = calendarFor(session, timezone);
-  const timeframeString = tf || chartTimeframe().period;
-  return perBar((t) => (test && !(inside ? inside(t) : bars.inside(t)) ? NaN : bars.timeOf(t, timeframeString)));
+  const { open } = chartSessionPeriods(tf || chartTimeframe().period, session, timezone);
+  return perBar((t) => open(t));
 }
 
 function timeCloseFunction(tf?: string, session?: string, timezone?: string): Series {
   collector();
-  const { bars, test, inside } = calendarFor(session, timezone);
-  const timeframeString = tf || chartTimeframe().period;
-  return perBar((t) => (test && !(inside ? inside(t) : bars.inside(t)) ? NaN : bars.closeOf(t, timeframeString)));
+  const { close } = chartSessionPeriods(tf || chartTimeframe().period, session, timezone);
+  return perBar((t) => close(t));
 }
 
 /**
@@ -1909,6 +1955,26 @@ function changeOf(tf: string, firstBar = false): Series {
   return perBar((t, i, times) => ((i > 0 ? changed(bars.timeOf(t, tf), bars.timeOf(times[i - 1]!, tf)) : firstBar) ? 1 : 0));
 }
 
+/**
+ * Default anchor of `ta.vwap` (#173, #178): the first bar and each bar whose trading day differs from the last bar
+ * that has one. Bars after an early close have no day: the first of them continues the day before it, each further
+ * one starts a new sum, and the next day starts on its first bar (where `timeframe.change("D")` is false). On
+ * D / W / M charts every bar.
+ */
+function vwapAnchor(): Series {
+  if (chartTimeframe().isdwm) return barFlag(() => true);
+  const { bars } = sessionBars();
+  let last = NaN;
+  let previous = NaN;
+  return perBar((t, i) => {
+    const day = bars.timeOf(t, '1D');
+    const isNew = i === 0 || (Number.isNaN(day) ? Number.isNaN(previous) : day !== last);
+    if (!Number.isNaN(day)) last = day;
+    previous = day;
+    return isNew ? 1 : 0;
+  });
+}
+
 function flag(key: keyof SessionFlags): Series {
   const { bars, regular } = sessionBars();
   const values = sessionFlags(ctxBars.bars.map(barTime), bars, regular)[key];
@@ -1998,10 +2064,14 @@ function valuesOf(value: Series | number | boolean, length: number): number[] {
 }
 
 /**
- * PineScript `request.security` for the chart symbol (`syminfo.tickerid`, `""`, `ticker.heikinashi(...)`,
- * `ticker.standard(...)`) and a timeframe equal to or higher than the chart's. The higher-timeframe bars are
- * built by grouping the chart bars, and `expression` runs on them (its `ta.*` calls, tuples and `timeframe.*`
- * see the higher timeframe). Other symbols need external data and throw; a lower timeframe throws.
+ * PineScript `request.security` on a timeframe equal to or higher than the chart's. For the chart symbol
+ * (`syminfo.tickerid`, `""`, `ticker.heikinashi(...)`, `ticker.standard(...)`) the higher-timeframe bars are built by
+ * grouping the chart bars; another symbol's bars come from `ChartContext.bars` (#179) and are merged on the chart bars
+ * by close time (lookahead off) or by open time / trading day (lookahead on), see `securityOther`. `expression` runs
+ * on those bars (its `ta.*` calls, tuples, `timeframe.*` and `syminfo.*` see them). A lower timeframe throws.
+ *
+ * A symbol that does not exist (bars []) stops the script with "Invalid symbol: X", or gives na with
+ * `ignore_invalid_symbol`.
  *
  * PineScript rules: lookahead off shows a period's value from the
  * bar that completes it; lookahead on from its first bar; gaps on keeps only the bar where the value appears.
@@ -2012,18 +2082,20 @@ function security<T extends SecurityValue>(
   timeframe: string,
   expression: () => T,
   gaps: string = barmerge.gaps_off,
-  lookahead: string = barmerge.lookahead_off
+  lookahead: string = barmerge.lookahead_off,
+  ignore_invalid_symbol: boolean = false
 ): T extends unknown[] ? Series[] : Series {
   collector();
   const heikin = symbol.startsWith(HEIKIN_ASHI);
   const base = heikin ? symbol.slice(HEIKIN_ASHI.length) : symbol;
-  if (base !== '' && base !== chartCtx.tickerid) {
-    throw new Error(`request.security: "${symbol}" is not the chart symbol; other symbols need external data.`);
-  }
   const chart = chartTimeframe();
   const tf = timeframeCore.info(timeframe || chart.period).period;
+  if (base !== '' && base !== chartCtx.tickerid) {
+    return externalSecurity(base, heikin, tf, expression, gaps, lookahead, ignore_invalid_symbol, false);
+  }
   if (timeframeCore.in_seconds(tf) < timeframeCore.in_seconds(chart.period)) {
-    throw new Error(`request.security: timeframe "${tf}" is lower than the chart timeframe "${chart.period}".`);
+    // a lower timeframe of the chart symbol: its bars come from ChartContext.bars (#181)
+    return externalSecurity(chartCtx.tickerid ?? '', heikin, tf, expression, gaps, lookahead, ignore_invalid_symbol, true);
   }
 
   const chartBars = ctxBars.bars;
@@ -2045,6 +2117,8 @@ function security<T extends SecurityValue>(
       const periods = at ? calendar.calendar.periods(at.date) : [];
       return periods.length ? calendar.timeOf(periods[0]![0], tf) : starts[i]!;
     });
+    const tfInfo = timeframeCore.info(tf);
+    strayPeriods(starts, dayPeriods, times, loaded, tfInfo.isdwm ? null : timeframeCore.in_seconds(tf) * 1000);
     const reaches = times.map((t) => loaded.closeOf(t, chart.period) >= calendar.periodEnd(t, tf));
     ({ group, latest } = periodsOf(starts, dayPeriods, reaches));
     const unit = chartCtx.timeUnit === 'ms' ? 1 : 1000;
@@ -2074,8 +2148,138 @@ function security<T extends SecurityValue>(
   return (Array.isArray(result) ? mapped : mapped[0]) as T extends unknown[] ? Series[] : Series;
 }
 
-/** PineScript `request.*`: `security` for the chart symbol (issue #101). */
-export const request = { security };
+/** Bars of a symbol on a timeframe from `ChartContext.bars`, with its calendar and the values of `expression` on them. */
+interface ExternalRun<T> {
+  bars: Bar[];
+  info: SymbolInfo;
+  result: T;
+  values: number[][];
+}
+
+/**
+ * Runs `expression` on the bars of `symbol` / `tf` given by `ChartContext.bars` (#179, #181). Bars not given: the
+ * request is recorded for the {@link MissingSymbolDataError} and the expression runs on no bar. `own`: the chart
+ * symbol, whose calendar defaults to the chart's.
+ */
+function runExternal<T extends SecurityValue>(
+  symbol: string,
+  heikin: boolean,
+  tf: string,
+  expression: () => T,
+  ignoreInvalid: boolean,
+  own: boolean
+): ExternalRun<T> {
+  let bars = chartCtx.bars?.(symbol, tf);
+  if (bars === undefined && !missingSymbols.some((r) => r.symbol === symbol && r.timeframe === tf)) {
+    missingSymbols.push({ symbol, timeframe: tf });
+  }
+  if (bars !== undefined && bars.length === 0 && !ignoreInvalid) throw new Error(`Invalid symbol: ${symbol}`);
+  bars ??= [];
+  if (heikin) bars = heikinAshi(bars);
+  const given = chartCtx.symbolInfo?.(symbol);
+  const info: SymbolInfo = own ? { ...chartCtx, ...given } : (given ?? {});
+  const chartBars = ctxBars.bars;
+  const savedCtx = chartCtx;
+  let result: T;
+  let values: number[][];
+  ctxBars.setAll(bars);
+  // the expression sees that symbol: its ticker, timeframe, calendar and properties
+  chartCtx = {
+    ...chartCtx,
+    tickerid: symbol,
+    timeframe: tf,
+    timezone: info.timezone,
+    session: info.session,
+    regularSession: info.regularSession,
+    mintick: info.mintick,
+    minmove: info.minmove,
+    pricescale: info.pricescale,
+    pointvalue: info.pointvalue,
+    mincontract: info.mincontract,
+    symbolType: info.symbolType,
+    currency: info.currency,
+    basecurrency: info.basecurrency,
+    root: info.root,
+  };
+  try {
+    result = expression();
+    const parts = Array.isArray(result) ? result : [result];
+    values = parts.map((p) => valuesOf(p, bars!.length));
+  } finally {
+    ctxBars.setAll(chartBars);
+    chartCtx = savedCtx;
+  }
+  return { bars, info, result, values };
+}
+
+/** The chart for the merge functions of `security/other`. */
+function mergeChart(): OtherSymbolChart {
+  return {
+    timeframe: chartTimeframe().period,
+    timezone: chartCtx.timezone,
+    session: chartCtx.session,
+    timeUnit: chartCtx.timeUnit,
+    // the realtime rule applies to a last bar that receives live updates
+    lastBarConfirmed: chartCtx.realtime !== true,
+  };
+}
+
+/**
+ * `request.security` of another symbol (#179), or of the chart symbol on a lower timeframe (#181): its bars from
+ * `ChartContext.bars`, merged by `securityOther`.
+ */
+function externalSecurity<T extends SecurityValue>(
+  symbol: string,
+  heikin: boolean,
+  tf: string,
+  expression: () => T,
+  gaps: string,
+  lookahead: string,
+  ignoreInvalid: boolean,
+  own: boolean
+): T extends unknown[] ? Series[] : Series {
+  const { bars, info, result, values } = runExternal(symbol, heikin, tf, expression, ignoreInvalid, own);
+  const index = securityOther(ctxBars.bars, bars, tf, mergeChart(), {
+    gaps: gaps === barmerge.gaps_on,
+    lookahead: lookahead === barmerge.lookahead_on,
+    other: info,
+  });
+  const mapped = values.map((v) => Series.fromArray(ctxBars, index.map((j) => (j < 0 ? NaN : (v[j] ?? NaN)))));
+  return (Array.isArray(result) ? mapped : mapped[0]) as T extends unknown[] ? Series[] : Series;
+}
+
+/**
+ * PineScript `request.security_lower_tf(symbol, timeframe, expression, ignore_invalid_symbol)` (#181): for each
+ * chart bar, the array of the values of `expression` on the bars of the lower timeframe that the chart bar contains
+ * (those whose close is after the open of the chart bar and at or before its close; empty when there are none).
+ * The bars come from `ChartContext.bars`, for the chart symbol (`""`, `syminfo.tickerid`) as for another symbol.
+ * Returns one array per chart bar (oldest first), or one such list per tuple part.
+ * @throws Error when `timeframe` is higher than the chart timeframe
+ */
+function security_lower_tf<T extends SecurityValue>(
+  symbol: string,
+  timeframe: string,
+  expression: () => T,
+  ignore_invalid_symbol: boolean = false
+): T extends unknown[] ? number[][][] : number[][] {
+  collector();
+  const heikin = symbol.startsWith(HEIKIN_ASHI);
+  const base = heikin ? symbol.slice(HEIKIN_ASHI.length) : symbol;
+  const chart = chartTimeframe();
+  const tf = timeframeCore.info(timeframe || chart.period).period;
+  if (timeframeCore.in_seconds(tf) > timeframeCore.in_seconds(chart.period)) {
+    throw new Error(`request.security_lower_tf: timeframe "${tf}" is higher than the chart timeframe "${chart.period}".`);
+  }
+  const own = base === '' || base === chartCtx.tickerid;
+  const ticker = own ? (chartCtx.tickerid ?? '') : base;
+  const { bars, info, result, values } = runExternal(ticker, heikin, tf, expression, ignore_invalid_symbol, own);
+  const ranges = securityLowerTf(ctxBars.bars, bars, tf, mergeChart(), { other: info });
+  const mapped = values.map((v) => ranges.map(([from, to]) => v.slice(from, to)));
+  return (Array.isArray(result) ? mapped : mapped[0]) as T extends unknown[] ? number[][][] : number[][];
+}
+
+/** PineScript `request.*`: `security` (issue #101, other symbols #179, lower timeframes #181) and `security_lower_tf`. */
+export const request = { security, security_lower_tf };
 
 // ── Drawing objects ──────────────────────────────────────────────────────────
 // The drawing namespaces come from this bundle so that they share the registry that