oakscriptjs 0.10.1 → 0.11.0

package/src/script/index.ts

@@ -87,7 +87,8 @@ import * as tableCore from '../table/index.js';
 import * as chartPointCore from '../chartpoint/index.js';
 import * as textCore from '../text/index.js';
 import * as mathCore from '../math/index.js';
-import { resetDrawings, setDrawingLimits } from '../drawing/registry.js';
+import { resetDrawings, setDrawingBar, setDrawingLimits } from '../drawing/registry.js';
+export { holdDrawing, releaseDrawing, varDrawing, type DrawingVariable } from '../drawing/registry.js';
 import { drawingOutputs } from '../drawing/output.js';
 import * as timeframeCore from '../timeframe/index.js';
 import * as timeCore from '../time/index.js';
@@ -296,6 +297,7 @@ export function executeScript(
 ): ScriptRunResult {
   ctxBars.setAll(barsInput);
   chartCtx = { ...chart };
+  runNow = chart.now ?? Date.now();
   scriptOptions = options;
   ctx = freshCollector(inputs);
   resetDrawings();
@@ -547,25 +549,27 @@ export const ta = {
   ): [Series, Series, Series, Series, Series] =>
     taSeries.ichimoku(bars(), conversionPeriods, basePeriods, laggingSpan2Periods, displacement),
   /** `ta.highest(source, length)` or `ta.highest(length)` (source = high). */
-  highest: (sourceOrLength: Series | number, length?: number): Series =>
+  highest: (sourceOrLength: Series | number, length?: number | Series): Series =>
     typeof sourceOrLength === 'number' ? taSeries.highest(high, sourceOrLength) : taSeries.highest(sourceOrLength, length!),
   /** `ta.lowest(source, length)` or `ta.lowest(length)` (source = low). */
-  lowest: (sourceOrLength: Series | number, length?: number): Series =>
+  lowest: (sourceOrLength: Series | number, length?: number | Series): Series =>
     typeof sourceOrLength === 'number' ? taSeries.lowest(low, sourceOrLength) : taSeries.lowest(sourceOrLength, length!),
   /** `ta.highestbars(source, length)` or `ta.highestbars(length)` (source = high); offsets are 0 or negative. */
-  highestbars: (sourceOrLength: Series | number, length?: number): Series =>
+  highestbars: (sourceOrLength: Series | number, length?: number | Series): Series =>
     typeof sourceOrLength === 'number'
       ? taSeries.highestbars(high, sourceOrLength)
       : taSeries.highestbars(sourceOrLength, length!),
   /** `ta.lowestbars(source, length)` or `ta.lowestbars(length)` (source = low); offsets are 0 or negative. */
-  lowestbars: (sourceOrLength: Series | number, length?: number): Series =>
+  lowestbars: (sourceOrLength: Series | number, length?: number | Series): Series =>
     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). */
+   *  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. */
   vwap: ((source: Series, anchor?: Series, stdev_mult?: number): Series | [Series, Series, Series] => {
-    const a = anchor ?? changeOf('1D'); // PineScript default: timeframe.change("1D")
+    // PineScript default: timeframe.change("1D"); the sums also start on the first bar (a day in progress)
+    const a = anchor ?? changeOf('1D', true);
     return stdev_mult === undefined ? taSeries.vwap(source, volume, a) : taSeries.vwapBands(source, volume, a, stdev_mult);
   }) as {
     (source: Series, anchor?: Series): Series;
@@ -575,12 +579,12 @@ export const ta = {
   mfi: (source: Series, length: number): Series => taSeries.mfi(source, length, volume),
   /** `ta.pivothigh(source, leftbars, rightbars)` or `ta.pivothigh(leftbars, rightbars)` (source = high).
    *  The value appears `rightbars` bars after the pivot bar, as in PineScript. */
-  pivothigh: (sourceOrLeft: Series | number, leftOrRight: number, rightbars?: number): Series =>
+  pivothigh: (sourceOrLeft: Series | number, leftOrRight: number | Series, rightbars?: number | Series): Series =>
     typeof sourceOrLeft === 'number'
       ? taSeries.pivothigh(high, sourceOrLeft, leftOrRight)
       : taSeries.pivothigh(sourceOrLeft, leftOrRight, rightbars!),
   /** `ta.pivotlow(source, leftbars, rightbars)` or `ta.pivotlow(leftbars, rightbars)` (source = low). */
-  pivotlow: (sourceOrLeft: Series | number, leftOrRight: number, rightbars?: number): Series =>
+  pivotlow: (sourceOrLeft: Series | number, leftOrRight: number | Series, rightbars?: number | Series): Series =>
     typeof sourceOrLeft === 'number'
       ? taSeries.pivotlow(low, sourceOrLeft, leftOrRight)
       : taSeries.pivotlow(sourceOrLeft, leftOrRight, rightbars!),
@@ -1262,6 +1266,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);
       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
@@ -1278,6 +1283,7 @@ export function eachBar(fn: (c: BarContext) => number | boolean | void): Series
     }
   } finally {
     currentBar = -1;
+    setDrawingBar(null);
   }
   return Series.fromArray(ctxBars, out);
 }
@@ -1547,6 +1553,16 @@ export interface ChartContext {
   pointvalue?: number;
   /** Smallest tradable quantity (PineScript `syminfo.mincontract`); 1 for whole shares */
   mincontract?: number;
+  /** Symbol type (PineScript `syminfo.type`): "stock", "crypto", "forex", "futures", "index", "fund"... */
+  symbolType?: string;
+  /** Currency of the symbol (PineScript `syminfo.currency`), e.g. "USD" */
+  currency?: 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 */
+  backgroundColor?: string;
+  /** Current time in ms (PineScript `timenow`); default: the clock of the computer at the start of the run */
+  now?: number;
   /**
    * The last bar is closed (`barstate.isconfirmed` on the last bar). Default false: PineScript treats the last bar
    * of the data as not confirmed until the data feed closes it.
@@ -1638,6 +1654,16 @@ function symbolProperty(key: 'mintick' | 'pointvalue' | 'mincontract'): number {
   return value;
 }
 
+/** 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 {
+  collector();
+  const value = chartCtx[key];
+  if (value === undefined) {
+    throw new Error(`${name} is not known: pass it as executeScript(body, bars, inputs, { ${key} }).`);
+  }
+  return value;
+}
+
 /** `[minmove, pricescale]` of the chart symbol: from the chart context, else from its mintick. */
 function symbolScale(): [number, number] {
   collector();
@@ -1649,7 +1675,8 @@ function symbolScale(): [number, number] {
 
 /**
  * PineScript `syminfo.timezone`, `syminfo.tickerid`, `syminfo.session` (session type), `syminfo.mintick`,
- * `syminfo.minmove`, `syminfo.pricescale`, `syminfo.pointvalue` and `syminfo.mincontract`, from the chart context.
+ * `syminfo.minmove`, `syminfo.pricescale`, `syminfo.pointvalue`, `syminfo.mincontract`, `syminfo.type` and
+ * `syminfo.currency`, from the chart context.
  */
 export const syminfo = {
   get mintick(): number {
@@ -1681,6 +1708,12 @@ export const syminfo = {
     collector();
     return chartCtx.sessionType ?? 'regular';
   },
+  get type(): string {
+    return chartText('symbolType', 'syminfo.type');
+  },
+  get currency(): string {
+    return chartText('currency', 'syminfo.currency');
+  },
 };
 
 /** A calendar function: `(time, timezone?)` on a UNIX time or on a Series of times. */
@@ -1794,7 +1827,10 @@ function sessionBars(): { bars: SessionBars; regular: SessionBars } {
  * 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 } {
+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();
@@ -1806,7 +1842,14 @@ function calendarFor(session?: string, timezone?: string): { bars: SessionBars;
     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 };
+  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 {
@@ -1823,22 +1866,28 @@ function callableSeries<F extends (...args: never[]) => Series>(series: Series,
 
 function timeFunction(tf?: string, session?: string, timezone?: string): Series {
   collector();
-  const { bars, test } = calendarFor(session, timezone);
+  const { bars, test, inside } = calendarFor(session, timezone);
   const timeframeString = tf || chartTimeframe().period;
-  return perBar((t) => (test && !bars.inside(t) ? NaN : bars.timeOf(t, timeframeString)));
+  return perBar((t) => (test && !(inside ? inside(t) : bars.inside(t)) ? NaN : bars.timeOf(t, timeframeString)));
 }
 
 function timeCloseFunction(tf?: string, session?: string, timezone?: string): Series {
   collector();
-  const { bars, test } = calendarFor(session, timezone);
+  const { bars, test, inside } = calendarFor(session, timezone);
   const timeframeString = tf || chartTimeframe().period;
-  return perBar((t) => (test && !bars.inside(t) ? NaN : bars.closeOf(t, timeframeString)));
+  return perBar((t) => (test && !(inside ? inside(t) : bars.inside(t)) ? NaN : bars.closeOf(t, timeframeString)));
 }
 
 /**
  * PineScript `time`: the bar open time in ms (a Series), and `time(timeframe?, session?, timezone?)`:
  * the open time of the `timeframe` period that contains the bar, `na` outside `session`.
  */
+/** Current time of the run in ms, see `ChartContext.now`. */
+let runNow = NaN;
+
+/** PineScript `timenow`: the current time in ms, the same on every bar of a run (`ChartContext.now`). */
+export const timenow = new Series(ctxBars, () => runNow);
+
 export const time = callableSeries(new Series(ctxBars, (b) => barTime(b)), timeFunction);
 
 /**
@@ -1853,9 +1902,11 @@ export const time_close = callableSeries(
 /** PineScript `time_tradingday`: 00:00 UTC of the trading day of each bar, in ms. */
 export const time_tradingday = new Series(ctxBars, (b) => sessionBars().bars.tradingDayTime(barTime(b)));
 
-function changeOf(tf: string): Series {
+function changeOf(tf: string, firstBar = false): Series {
   const { bars } = sessionBars();
-  return perBar((t, i, times) => (i > 0 && bars.timeOf(t, tf) !== bars.timeOf(times[i - 1]!, tf) ? 1 : 0));
+  // a bar without a period (after an early close) is no change, and neither is the bar after it
+  const changed = (a: number, b: number): boolean => !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));
 }
 
 function flag(key: keyof SessionFlags): Series {
@@ -2091,6 +2142,14 @@ export const text = { ...textCore };
  * (index, time, and `price`, default the close), so it runs inside eachBar().
  */
 export const chart = {
+  /** Chart foreground colour (PineScript `chart.fg_color`), from the chart context. */
+  get fg_color(): string {
+    return chartText('foregroundColor', 'chart.fg_color');
+  },
+  /** Chart background colour (PineScript `chart.bg_color`), from the chart context. */
+  get bg_color(): string {
+    return chartText('backgroundColor', 'chart.bg_color');
+  },
   point: {
     ...chartPointCore,
     now(price?: number): ChartPoint {

package/src/session/bars.ts

@@ -111,7 +111,10 @@ export class SessionBars {
     return p[p.length - 1]![1];
   }
 
-  /** PineScript `time(tf)` for a bar that opens at `time`; NaN when no trading day is found. */
+  /**
+   * PineScript `time(tf)` for a bar that opens at `time`; NaN when no trading day is found. An intraday bar that
+   * opens after an early close has no day: `time("D")` is NaN on it (measured; `time("W")` keeps its value).
+   */
   timeOf(time: number, timeframe: string): number {
     const tf = info(timeframe);
     const at = this.calendar.locate(time);
@@ -123,6 +126,7 @@ export class SessionBars {
       return start + Math.floor((time - start) / ms) * ms;
     }
     const { unit, n } = unitOf(tf);
+    if (unit === 'D' && n === 1 && this.stray(time)) return NaN;
     const [from, to] = this.periodRange(at.date, unit, n);
     const first = this.calendar.firstTradingDay(from, to);
     return first === null ? NaN : this.dayStart(first);
@@ -140,6 +144,7 @@ export class SessionBars {
       return Math.min(this.timeOf(time, timeframe) + in_seconds(tf.period) * 1000, end);
     }
     const { unit, n } = unitOf(tf);
+    if (unit === 'D' && n === 1 && this.stray(time)) return NaN;
     const [from, to] = this.periodRange(at.date, unit, n);
     // intraday charts: the start of the next period, except "1D" (the session end)
     if (this.chart.isintraday && (unit !== 'D' || n > 1)) {
@@ -154,7 +159,7 @@ export class SessionBars {
   /** Trading day of a bar: on D / W / M charts the last trading day of the chart period. */
   tradingDay(time: number): DateNum | null {
     const at = this.calendar.locate(time);
-    if (!at) return null;
+    if (!at || this.stray(time)) return null;
     if (this.chart.isdwm) {
       const { unit, n } = unitOf(this.chart);
       const [from, to] = this.periodRange(at.date, unit, n);
@@ -188,6 +193,35 @@ export class SessionBars {
     return day === null ? NaN : dateUtcMs(day);
   }
 
+  /**
+   * Open time of the bar after the bar that opens at `time`, on the trading calendar: the next bar of the session
+   * period, else the start of the next period or trading day; on D / W / M charts the session start of the first
+   * trading day of the next chart period. NaN when none is found within 400 days.
+   */
+  nextBarTime(time: number): number {
+    const at = this.calendar.locate(time);
+    if (!at) return NaN;
+    if (!this.chart.isdwm) {
+      const periods = this.calendar.periods(at.date);
+      const [start, end] = periods[at.index]!;
+      const ms = in_seconds(this.chart.period) * 1000;
+      const next = start + (Math.floor((time - start) / ms) + 1) * ms;
+      if (at.inside && next < end) return next;
+      if (at.index + 1 < periods.length) return periods[at.index + 1]![0];
+      const day = this.calendar.firstTradingDay(addDays(at.date, 1), addDays(at.date, 400));
+      return day === null ? NaN : this.dayStart(day);
+    }
+    const { unit, n } = unitOf(this.chart);
+    const [, to] = this.periodRange(at.date, unit, n);
+    const day = this.calendar.firstTradingDay(addDays(to, 1), addDays(to, 400));
+    return day === null ? NaN : this.dayStart(day);
+  }
+
+  /** An intraday bar that opens after an early close of its day (see TradingCalendar.afterEarlyClose). */
+  stray(time: number): boolean {
+    return !this.chart.isdwm && this.calendar.afterEarlyClose(time);
+  }
+
   /** True when the bar at `time` is inside the session. */
   inside(time: number): boolean {
     return this.calendar.locate(time)?.inside ?? false;
@@ -217,6 +251,9 @@ export interface SessionFlags {
  * time; first and last bars are per session period (a trading day can have two periods, e.g. after a
  * futures holiday); pre / post market compare with the regular hours of the same trading day; on
  * D / W / M charts every bar is its own session (first, last, market, first and last regular).
+ * The first loaded bar is a first bar only when no earlier bar of its period can exist (it opens less than one chart
+ * period after the period start). A bar that opens after an early close is in the market hours (the usual hours of
+ * its day) but is no last bar.
  */
 export function sessionFlags(times: number[], bars: SessionBars, regular: SessionBars): SessionFlags {
   const n = times.length;
@@ -242,18 +279,22 @@ export function sessionFlags(times: number[], bars: SessionBars, regular: Sessio
     const close = bars.closeOf(t, chart.period);
     const [, end] = bars.calendar.periods(at.date)[at.index]!;
     const period = `${at.date}/${at.index}`;
-    out.isfirstbar[i] = period !== previousPeriod;
-    out.islastbar[i] = close >= end;
+    const [start] = bars.calendar.periods(at.date)[at.index]!;
+    const barMs = in_seconds(chart.period) * 1000;
+    // the first loaded bar: a first bar only when no earlier bar of the period can exist
+    out.isfirstbar[i] = i === 0 ? t - start < barMs : period !== previousPeriod;
+    const stray = bars.stray(t);
+    out.islastbar[i] = !stray && close >= end;
     const regularPeriods = regular.calendar.periods(at.date);
     const r = regularPeriods.findIndex(([s, e]) => s <= t && t < e);
     const market = r !== -1;
-    out.ismarket[i] = market;
+    out.ismarket[i] = market || regular.stray(t);
     if (!market && regularPeriods.length) {
       out.ispremarket[i] = t < regularPeriods[0]![0];
       out.ispostmarket[i] = t >= regularPeriods[regularPeriods.length - 1]![1];
     }
     const regularPeriod = market ? `${at.date}/${r}` : '';
-    out.isfirstbar_regular[i] = market && regularPeriod !== previousRegular;
+    out.isfirstbar_regular[i] = market && (i === 0 ? t - regularPeriods[r]![0] < barMs : regularPeriod !== previousRegular);
     out.islastbar_regular[i] = market && close >= regularPeriods[r]![1];
     previousPeriod = period;
     previousRegular = regularPeriod;

package/src/session/calendar.ts

@@ -6,7 +6,10 @@
  * - periods "HHMM-HHMM", several separated by commas; "24x7" is the whole day, every day
  * - a period whose end is not after its start ("1700-1600", "1700-1700") starts the day before the
  *   trading day: the session that opens Sunday 17:00 is Monday's
- * - "HHMMF<n>" moves a time <n> days before the trading day ("1700F2-1200F1")
+ * - "HHMMF<n>" moves a time <n> days before the trading day ("1700F2-1200F1"); "F" alone is one day ("1700F-1900":
+ *   17:00 of the day before to 19:00)
+ * - several sections joined by "|", each with its own days ("1900-1900:3456|1700F-1900:2": Monday opens on Sunday
+ *   17:00, the other days at 19:00 of the day before)
  * - optional days after ":" (1 = Sunday ... 7 = Saturday); without days a symbol session trades Monday to
  *   Friday ("24x7": every day), and a PineScript session string follows PineScript's rules (one period:
  *   every day; several periods: Monday to Friday)
@@ -62,9 +65,10 @@ export const weekdayOf = (date: DateNum): number => new Date(utcOf(date)).getUTC
 export const dateUtcMs = utcOf;
 
 function parseTime(token: string, spec: string): { minutes: number; offset?: number } {
-  const m = /^(\d{2})(\d{2})(?:F(\d+))?$/.exec(token.trim());
+  const m = /^(\d{2})(\d{2})(?:F(\d*))?$/.exec(token.trim());
   if (!m) throw new SyntaxError(`Invalid session "${spec}"`);
-  return { minutes: Number(m[1]) * 60 + Number(m[2]), offset: m[3] === undefined ? undefined : Number(m[3]) };
+  // "F" without a number is one day before the trading day
+  return { minutes: Number(m[1]) * 60 + Number(m[2]), offset: m[3] === undefined ? undefined : Number(m[3] || 1) };
 }
 
 function parsePeriods(text: string, spec: string): Period[] {
@@ -102,6 +106,17 @@ function pineVersion(text: string, from: DateNum): Version {
 
 function parseVersion(text: string, from: DateNum, spec: string, rule: 'symbol' | 'pine'): Version {
   if (rule === 'pine') return pineVersion(text, from);
+  if (text.includes('|')) {
+    // sections with their own days
+    const byDay: Period[][] = Array.from({ length: 8 }, () => []);
+    for (const section of text.split('|').filter((part) => part.trim())) {
+      const one = parseVersion(section, from, spec, rule);
+      one.days.forEach((on, d) => {
+        if (on) byDay[d] = one.periods;
+      });
+    }
+    return { from, periods: [], days: byDay.map((p) => p.length > 0), byDay };
+  }
   const [periodText = '', dayText] = text.trim().split(':');
   const periods = parsePeriods(periodText, spec);
   const allDays = periodText.trim() === '24x7';
@@ -174,6 +189,25 @@ export class TradingCalendar {
     return this.periods(date).length > 0;
   }
 
+  /**
+   * True for a bar that opens after the session of its day was cut by a correction (an early close) but inside the
+   * usual hours of that day: PineScript has no period for such a bar (`time("D")` is na on it).
+   */
+  afterEarlyClose(time: number): boolean {
+    const at = this.locate(time);
+    if (!at || at.inside || !this.corrections.get(at.date)) return false;
+    const version = [...this.versions].reverse().find((v) => v.from <= at.date)!;
+    const usual = version.byDay ? version.byDay[weekdayOf(at.date)]! : version.days[weekdayOf(at.date)] ? version.periods : [];
+    const y = Math.floor(at.date / 10000);
+    const m = Math.floor(at.date / 100) % 100;
+    const d = at.date % 100;
+    return usual.some(
+      (p) =>
+        zonedToUnix(this.timezone, y, m, d - p.startOffset, Math.floor(p.start / 60), p.start % 60) <= time &&
+        time < zonedToUnix(this.timezone, y, m, d - p.endOffset, Math.floor(p.end / 60), p.end % 60)
+    );
+  }
+
   /**
    * Trading day and period of a time: the period that contains it, else the last period that started
    * before it. Null when no trading day is found near the time.

package/src/session/context.ts

@@ -0,0 +1,160 @@
+/**
+ * The session of a chart context, for code that does not run a whole script (a port with its own bar loop).
+ *
+ * The same values as the script API gives (`time(tf)`, `time_close(tf)`, `time_tradingday`, `session.*`, the periods
+ * of `request.security`), from the session, corrections and holidays of the context. Bar times are in the unit of
+ * the context (`timeUnit`, seconds by default, as `Bar.time`); PineScript time values are returned in ms.
+ *
+ * @module session/context
+ */
+
+import type { Bar } from '../types/index.js';
+import { info, in_seconds } from '../timeframe/index.js';
+import { afterCompletion, periodsOf, resample } from '../security/resample.js';
+import { SessionBars, sessionFlags, type SessionFlags } from './bars.js';
+import { TradingCalendar, type SessionSpec } from './calendar.js';
+
+/** The part of a chart context that the session functions read (a `ChartContext` of the script API fits). */
+export interface SessionContext {
+  /** Chart timeframe: "5", "60", "1D"... */
+  timeframe?: string;
+  /** Exchange time zone: "America/New_York", "Etc/UTC"... */
+  timezone?: string;
+  /** Session of the loaded bars: hours, corrections, holidays */
+  session?: SessionSpec | string;
+  /** Regular trading hours when the bars include extended hours (default: `session`) */
+  regularSession?: SessionSpec | string;
+  /** Unit of the bar times: 's' (default) or 'ms' */
+  timeUnit?: 's' | 'ms';
+}
+
+/** The session calendars of a context: the loaded bars and the regular hours. */
+export interface ChartSessions {
+  bars: SessionBars;
+  regular: SessionBars;
+  /** ms per unit of the bar times */
+  unit: number;
+}
+
+const toSpec = (s: SessionSpec | string): SessionSpec => (typeof s === 'string' ? { session: s } : s);
+const cache = new WeakMap<object, ChartSessions>();
+
+/**
+ * Session calendars of a chart context (cached per context object).
+ * @throws Error when the context has no timeframe, time zone or session
+ */
+export function chartSessions(chart: SessionContext): ChartSessions {
+  const cached = cache.get(chart);
+  if (cached) return cached;
+  const { timeframe, timezone, session } = chart;
+  if (!timeframe || !timezone || !session) {
+    throw new Error('The chart context needs timeframe, timezone and session for the session functions.');
+  }
+  const loaded = toSpec(session);
+  const regular = chart.regularSession ? toSpec(chart.regularSession) : loaded;
+  const out: ChartSessions = {
+    bars: new SessionBars(new TradingCalendar(timezone, loaded), timeframe),
+    regular: new SessionBars(new TradingCalendar(timezone, { holidays: loaded.holidays, ...regular }), timeframe),
+    unit: chart.timeUnit === 'ms' ? 1 : 1000,
+  };
+  cache.set(chart, out);
+  return out;
+}
+
+/** PineScript `time(timeframe)` (ms) of a bar that opens at `time`: the start of its period; NaN without one. */
+export function periodTime(time: number, timeframe: string, chart: SessionContext): number {
+  const s = chartSessions(chart);
+  return s.bars.timeOf(time * s.unit, timeframe);
+}
+
+/** PineScript `time_close(timeframe)` (ms) of a bar that opens at `time`. */
+export function periodClose(time: number, timeframe: string, chart: SessionContext): number {
+  const s = chartSessions(chart);
+  return s.bars.closeOf(time * s.unit, timeframe);
+}
+
+/** PineScript `time_tradingday` (ms, 00:00 UTC of the trading day) of a bar that opens at `time`. */
+export function tradingDayTime(time: number, chart: SessionContext): number {
+  const s = chartSessions(chart);
+  return s.bars.tradingDayTime(time * s.unit);
+}
+
+/** PineScript `session.*` flags of bars that open at `times` (in order). */
+export function chartSessionFlags(times: ArrayLike<number>, chart: SessionContext): SessionFlags {
+  const s = chartSessions(chart);
+  return sessionFlags(Array.from(times, (t) => t * s.unit), s.bars, s.regular);
+}
+
+/** Higher-timeframe bars of the chart bars and what `mapToChart` needs to bring values back to the chart. */
+export interface SessionResample {
+  /** Bars of `timeframe`, built from the chart bars */
+  bars: Bar[];
+  /** Period index of each chart bar */
+  group: number[];
+  /** Latest completed period at each chart bar */
+  latest: number[];
+}
+
+/**
+ * Same-symbol `request.security` on a timeframe equal to or higher than the chart's, with the session of the context:
+ * D / W / M periods follow the regular hours, corrections and holidays; intraday periods the loaded session.
+ * Compute on `bars`, then bring each value series back with `mapToChart(values, group, latest, lookahead, gaps)`.
+ * @throws Error when `timeframe` is lower than the chart timeframe
+ */
+export function resampleSession(bars: Bar[], timeframe: string, chart: SessionContext): SessionResample {
+  const s = chartSessions(chart);
+  const chartTf = s.bars.chart;
+  const tf = info(timeframe || chartTf.period);
+  if (tf.period === chartTf.period) {
+    const group = bars.map((_, i) => i);
+    return { bars, group, latest: group };
+  }
+  if (in_seconds(tf.period) < in_seconds(chartTf.period)) {
+    throw new Error(`resampleSession: timeframe "${tf.period}" is lower than the chart timeframe "${chartTf.period}".`);
+  }
+  const times = bars.map((b) => (b.time as number) * s.unit);
+  const calendar = tf.isdwm ? s.regular : s.bars;
+  const starts = times.map((t) => calendar.timeOf(t, tf.period));
+  const dayPeriods = times.map((t, i) => {
+    const at = s.bars.calendar.locate(t);
+    const periods = at ? calendar.calendar.periods(at.date) : [];
+    return periods.length ? calendar.timeOf(periods[0]![0], tf.period) : starts[i]!;
+  });
+  const reaches = times.map((t) => s.bars.closeOf(t, chartTf.period) >= calendar.periodEnd(t, tf.period));
+  const { group, latest } = periodsOf(starts, dayPeriods, reaches);
+  // a higher-timeframe bar ends at the bar that completes it (no value from after the completion)
+  const after = afterCompletion(group, latest);
+  const kept = (_: unknown, i: number): boolean => !after[i];
+  return { bars: resample(bars.filter(kept), starts.map((x) => x / s.unit).filter(kept)).bars, group, latest };
+}
+
+/**
+ * Open time of the `count`-th bar after the bar that opens at `time`, on the trading calendar of the context: the
+ * closed hours, weekends, holidays and days off are skipped. `count` 0 is the bar itself. For a drawing that ends
+ * `count` bars after the last bar (PineScript `bar_index + count`).
+ */
+export function barTimeAfter(time: number, count: number, chart: SessionContext): number {
+  const s = chartSessions(chart);
+  let t = time * s.unit;
+  for (let k = 0; k < count && !Number.isNaN(t); k++) t = s.bars.nextBarTime(t);
+  return t / s.unit;
+}
+
+/**
+ * Number of bars from the bar that opens at `from` to the bar that contains `to`, on the trading calendar of the
+ * context (0 when `to` is in the bar of `from` or before it). For a drawing placed at a time after the last bar
+ * (PineScript `time + n days` with `xloc.bar_time`): the chart shows it on the bar of that time, weekends and
+ * holidays skipped. NaN when no bar is found within 100,000 bars.
+ */
+export function barsUntil(from: number, to: number, chart: SessionContext): number {
+  const s = chartSessions(chart);
+  const target = to * s.unit;
+  let t = from * s.unit;
+  for (let k = 0; k < 100_000; k++) {
+    const next = s.bars.nextBarTime(t);
+    if (Number.isNaN(next)) return NaN;
+    if (next > target) return k;
+    t = next;
+  }
+  return NaN;
+}

package/src/str/index.ts

@@ -45,7 +45,9 @@ export function length(str: simple_string): int {
  *
  * @remarks
  * As in PineScript:
- * - without format, numbers show up to 10 decimals ("0.3333333333"); 1e21 and more use "1E21"
+ * - without format, numbers show up to 10 decimals ("0.3333333333"), rounded on the exact value of the double
+ *   (82325.10000000005 gives "82325.1"; with the format "#.##########" it gives "82325.1000000001"); 1e21 and more
+ *   use "1E21"
  * - patterns round half away from zero on the shortest decimal form: 1.005 with "#.##" gives "1.01";
  *   at most 16 decimals from 1e-3 up (0.0012345678901234567 with 20 '#' decimals gives "0.0012345678901235")
  * - "pos;neg" patterns: a negative number takes the text of the negative subpattern ("#.##;(#.##)": "(3.5)")
@@ -72,6 +74,8 @@ export function length(str: simple_string): int {
  * ```
  */
 export function tostring(value: any, format?: simple_string, mintick?: float, pricescale?: float): string {
+  // an array: "[a, b]", each element as a single value
+  if (Array.isArray(value)) return '[' + value.map((v) => tostring(v, format, mintick, pricescale)).join(', ') + ']';
   if (typeof value !== 'number') return String(value);
   if (Number.isNaN(value)) return format === 'percent' ? 'NaN%' : 'NaN';
   if (!Number.isFinite(value)) {
@@ -83,7 +87,8 @@ export function tostring(value: any, format?: simple_string, mintick?: float, pr
     if (Math.abs(value) >= 1e21 && Number.isFinite(value)) {
       return String(value).replace('e+', 'E').replace(/\.0+E/, 'E');
     }
-    return formatNumber(value, '#.##########', 'halfUpShortest');
+    // without a format the exact value is rounded (82325.10000000005 is 82325.10000000004947...: "82325.1")
+    return formatNumber(value, '#.##########', 'halfUpExact');
   }
   switch (format) {
     case 'percent':

package/src/str/numberformat.ts

@@ -4,8 +4,10 @@
  * The pattern syntax is Java's DecimalFormat: `0` required digit, `#` optional digit, `,` grouping,
  * `.` decimal point, `E0` exponent, `%` multiplies by 100, `'...'` quoted literal text.
  * PineScript rules:
- * - `str.tostring` rounds half away from zero on the shortest decimal form of the number
+ * - `str.tostring` with a format rounds half away from zero on the shortest decimal form of the number
  *   (`1.005` with "#.##" gives "1.01", `2.5` with "#" gives "3")
+ * - `str.tostring` without a format rounds the exact binary value to 10 decimals (12.34500000005 is
+ *   12.34500000004999975...: "12.345", and "12.3450000001" with the format "#.##########")
  * - `str.format` rounds half to even on the exact binary value (`0.25` with "#.#" gives "0.2")
  * - a negative number that rounds to zero loses its sign; "#.00" writes `.50` (no leading zero),
  *   but "#.##" writes `0.5` (a pattern without any '0' shows one integer digit)
@@ -18,7 +20,7 @@
  *   0.1 with 20 '#' decimals gives "0.1" in both rounding modes
  */
 
-export type Rounding = 'halfUpShortest' | 'halfEvenExact';
+export type Rounding = 'halfUpShortest' | 'halfUpExact' | 'halfEvenExact';
 
 interface Pattern {
   prefix: string;
@@ -161,7 +163,7 @@ function roundDigits(d: Digits, frac: number, mode: Rounding): Digits {
   if (keep < 0) return { digits: '', intLen: 0 };
   const first = d.digits.charCodeAt(keep) - 48;
   let up: boolean;
-  if (mode === 'halfUpShortest') up = first >= 5;
+  if (mode !== 'halfEvenExact') up = first >= 5;
   else if (first !== 5) up = first > 5;
   else if (d.digits.length > keep + 1) up = true;
   else up = keep > 0 && (d.digits.charCodeAt(keep - 1) - 48) % 2 === 1;