oakscriptjs 0.11.0 → 0.11.2

package/dist/esm/script/index.js

@@ -55,11 +55,12 @@ import * as strCore from '../str/index.js';
 import { formatMessage } from '../str/messageformat.js';
 import { tickScale } from '../str/numberformat.js';
 import { TradingCalendar } from '../session/calendar.js';
-import { SessionBars, sessionFlags } from '../session/bars.js';
+import { SessionBars, sessionFlags, strayPeriods } from '../session/bars.js';
 import { afterCompletion, heikinAshi, mapToChart, periodsOf, resample } from '../security/resample.js';
+import { securityLowerTf, securityOther } from '../security/other.js';
 import { position } from '../types/index.js';
 import { STRATEGY_CONSTANTS, STRATEGY_DEFAULTS, STRATEGY_NUMBER_VARIABLES, STRATEGY_TEXT_VARIABLES, } from '../strategy/index.js';
-import { parsePineSession } from '../time/session.js';
+import { sessionPeriods } from '../session/context.js';
 /** Bars for the current run. Module-level and REUSED across runs so builtins
  *  and every Series derived from them keep their version-keyed memoization. */
 const ctxBars = new BarData([]);
@@ -126,8 +127,11 @@ export function executeScript(body, barsInput, inputs = {}, chart = {}, options
     ctx = freshCollector(inputs);
     resetDrawings();
     mathCore.resetRandom();
+    missingSymbols = [];
     try {
         body();
+        if (missingSymbols.length)
+            throw new MissingSymbolDataError(missingSymbols);
         const c = ctx;
         return {
             metadata: {
@@ -254,6 +258,10 @@ export const input = {
     session(defval, title, opts = {}) {
         return registerInput({ type: 'session', defval, title, options: opts.options, ...common(opts) }, 'input_session');
     },
+    /** Ticker id ("NASDAQ:MSFT"), for `request.security` of another symbol (#180). */
+    symbol(defval, title, opts = {}) {
+        return registerInput({ 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, title, opts = {}) {
         const v = registerInput({ type: 'time', defval, title, ...common(opts) }, 'input_time');
@@ -317,12 +325,12 @@ export const ta = {
     lowestbars: (sourceOrLength, length) => 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, anchor, stdev_mult) => {
-        // 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);
     }),
     /** `ta.mfi(source, length)` with the chart volume (PineScript takes 2 arguments). */
@@ -818,7 +826,7 @@ export function eachBar(fn) {
             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
@@ -1018,6 +1026,21 @@ for (const name of [...STRATEGY_NUMBER_VARIABLES, ...STRATEGY_TEXT_VARIABLES]) {
  * ```
  */
 export const strategy = Object.defineProperties(Object.assign((title, options) => declareStrategy(title, options), strategyMembers), variableGetters);
+/**
+ * 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 {
+    requests;
+    constructor(requests) {
+        super(`request.security needs the bars of ${requests.map((r) => `${r.symbol} (${r.timeframe})`).join(', ')}: ` +
+            'pass them with ChartContext.bars.');
+        this.requests = requests;
+        this.name = 'MissingSymbolDataError';
+    }
+}
+/** Requests of other symbols without bars in the current run. */
+let missingSymbols = [];
 let chartCtx = {};
 function chartTimeframe() {
     collector();
@@ -1113,8 +1136,8 @@ function symbolScale() {
 }
 /**
  * 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() {
@@ -1152,6 +1175,12 @@ export const syminfo = {
     get currency() {
         return chartText('currency', 'syminfo.currency');
     },
+    get basecurrency() {
+        return chartText('basecurrency', 'syminfo.basecurrency');
+    },
+    get root() {
+        return chartText('root', 'syminfo.root');
+    },
 };
 function calendar(fn) {
     return ((time, timezone) => {
@@ -1228,33 +1257,6 @@ function 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, timezone) {
-    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) {
     const times = ctxBars.bars.map(barTime);
     return Series.fromArray(ctxBars, times.map((t, i) => fn(t, i, times)));
@@ -1265,17 +1267,20 @@ function callableSeries(series, fn) {
     Object.assign(fn, series);
     return fn;
 }
+/** `time(tf, session, timezone)` / `time_close(...)` periods of the run's chart (see session/context `sessionPeriods`). */
+function chartSessionPeriods(timeframeString, session, timezone) {
+    const { bars } = sessionBars();
+    return sessionPeriods(bars, { ...chartCtx, timezone: exchangeTimezone() }, timeframeString, session, timezone);
+}
 function timeFunction(tf, session, timezone) {
     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, session, timezone) {
     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));
 }
 /**
  * PineScript `time`: the bar open time in ms (a Series), and `time(timeframe?, session?, timezone?)`:
@@ -1299,6 +1304,27 @@ function changeOf(tf, firstBar = false) {
     const changed = (a, b) => !Number.isNaN(a) && !Number.isNaN(b) && a !== b;
     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() {
+    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) {
     const { bars, regular } = sessionBars();
     const values = sessionFlags(ctxBars.bars.map(barTime), bars, regular)[key];
@@ -1374,26 +1400,31 @@ function valuesOf(value, length) {
     return value.toArray().slice();
 }
 /**
- * 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.
  * Built bars can differ from the exchange's bars (official open / close, volume).
  */
-function security(symbol, timeframe, expression, gaps = barmerge.gaps_off, lookahead = barmerge.lookahead_off) {
+function security(symbol, timeframe, expression, gaps = barmerge.gaps_off, lookahead = barmerge.lookahead_off, ignore_invalid_symbol = false) {
     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;
     const times = chartBars.map(barTime);
@@ -1415,6 +1446,8 @@ function security(symbol, timeframe, expression, gaps = barmerge.gaps_off, looka
             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;
@@ -1442,8 +1475,108 @@ function security(symbol, timeframe, expression, gaps = barmerge.gaps_off, looka
     const mapped = values.map((v) => Series.fromArray(ctxBars, mapToChart(v, group, latest, lookahead === barmerge.lookahead_on, gaps === barmerge.gaps_on)));
     return (Array.isArray(result) ? mapped : mapped[0]);
 }
-/** PineScript `request.*`: `security` for the chart symbol (issue #101). */
-export const request = { security };
+/**
+ * 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(symbol, heikin, tf, expression, ignoreInvalid, own) {
+    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 = own ? { ...chartCtx, ...given } : (given ?? {});
+    const chartBars = ctxBars.bars;
+    const savedCtx = chartCtx;
+    let result;
+    let values;
+    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() {
+    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(symbol, heikin, tf, expression, gaps, lookahead, ignoreInvalid, own) {
+    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]);
+}
+/**
+ * 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(symbol, timeframe, expression, ignore_invalid_symbol = false) {
+    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]);
+}
+/** 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
 // executeScript() resets. `line.all` etc. are read like PineScript variables.