oakscriptjs 0.11.0 → 0.11.2

package/src/security/other.ts

@@ -0,0 +1,269 @@
+/**
+ * PineScript `request.security(symbol, timeframe, expression, gaps, lookahead)` of another symbol: which bar of the
+ * other symbol each chart bar shows (#179). The bars of the other symbol are given by the caller, already on the
+ * requested timeframe; the expression is computed on them and its values are mapped to the chart bars with the index
+ * given here. The script API does this with the `bars` accessor of its chart context.
+ *
+ * PineScript rules (measured on stocks, crypto and an exchange whose trading day starts on the previous UTC day; the
+ * chart timeframe, D, W and M on intraday and daily charts; the four gaps / lookahead combinations):
+ * - lookahead off: the last bar of the other symbol whose close time is at or before the close time of the chart bar
+ *   (a daily stock bar closes at the session end, a crypto daily bar at 00:00 UTC: a stock chart shows the crypto
+ *   bar of the day before, a crypto chart the stock bar of the same day)
+ * - lookahead on, intraday chart or intraday request: the last bar of the other symbol that opened at or before the
+ *   open of the chart bar
+ * - lookahead on, D / W / M chart and request: the last bar of the other symbol whose period starts at or before the trading day
+ *   of the chart bar: the trading day of a D bar, the Monday of a W bar, the first day of the month of an M bar, each
+ *   in the exchange time zone of its symbol (a week that opens on a Tuesday after a holiday still starts on Monday)
+ * - before the first bar of the other symbol: na; on chart bars where the other symbol has no bar (weekends,
+ *   holidays, closed hours), gaps off repeats the last value
+ * - gaps on: a value only on the chart bar where the shown bar changes (and on the first chart bar), na on the others
+ * - the last bar while it is open (`lastBarConfirmed` false) with gaps off: the realtime update shows the bar given by
+ *   lookahead on (the open bar of a higher timeframe), with lookahead off as well
+ *
+ * Close times, trading days and time zones come from the exchange calendars of the chart and of the other symbol
+ * (time zone and session, read by the session functions). Without them:
+ * - a symbol that trades every day (bars on Saturdays or Sundays; W bars at Monday 00:00 UTC; M bars on the first day
+ *   at 00:00 UTC) is on the "24x7" UTC calendar
+ * - another symbol whose bars open where the chart calendar starts its periods is on the calendar of the chart
+ * - else the UTC rule: an intraday bar closes one bar interval after its open (or at the next bar), a D / W / M bar at
+ *   the end of the last weekday (UTC) of its day / week / month; the trading day is the UTC date of the bar
+ * The fallback is exact between symbols of the same calendar and with 24x7 symbols; between a stock and a 24x7 symbol,
+ * or an exchange whose trading day starts on the previous UTC day, it needs the session of the stock.
+ *
+ * @module security/other
+ */
+
+import * as timeframe from '../timeframe/index.js';
+import { chartSessions, periodClose, periodTime, tradingDayTime, type SessionContext } from '../session/context.js';
+import type { SessionSpec } from '../session/calendar.js';
+
+const DAY = 86_400_000;
+
+/** Exchange calendar of a symbol: time zone and session (hours, corrections, holidays). */
+export interface SymbolCalendar {
+  timezone?: string;
+  session?: SessionSpec | string;
+}
+
+/** Options of {@link securityOther}. */
+export interface OtherSymbolOptions {
+  /** PineScript `barmerge.lookahead_on`; default false */
+  lookahead?: boolean;
+  /** PineScript `barmerge.gaps_on`; default false */
+  gaps?: boolean;
+  /** Calendar of the other symbol; see the module notes for the fallback */
+  other?: SymbolCalendar;
+}
+
+/** The chart: its timeframe, calendar, time unit and whether its last bar is closed. */
+export interface OtherSymbolChart extends SymbolCalendar {
+  /** Chart timeframe ("60", "1D"...) */
+  timeframe: string;
+  /** Unit of the bar times: 's' (default) or 'ms' */
+  timeUnit?: 's' | 'ms';
+  /** false: the last chart bar is still open (realtime rule) */
+  lastBarConfirmed?: boolean;
+}
+
+interface Zone {
+  timezone: string;
+  session: SessionSpec | string;
+}
+
+const calendars = new Map<string, SessionContext | null>();
+
+/** The session context of a zone and a timeframe (bar times in ms); null when the session cannot be read. */
+function calendarOf(zone: Zone | null, tf: string): SessionContext | null {
+  if (!zone) return null;
+  const key = `${zone.timezone}|${typeof zone.session === 'string' ? zone.session : JSON.stringify(zone.session)}|${tf}`;
+  let context = calendars.get(key);
+  if (context === undefined) {
+    context = { timeframe: tf, timezone: zone.timezone, session: zone.session, timeUnit: 'ms' };
+    try {
+      chartSessions(context);
+    } catch {
+      context = null;
+    }
+    if (calendars.size > 64) calendars.clear();
+    calendars.set(key, context);
+  }
+  return context;
+}
+
+const UTC_24X7: Zone = { timezone: 'Etc/UTC', session: '24x7' };
+
+/** True when bars of timeframe `tf` opening at `times` (ms) are those of a symbol that trades every day in UTC. */
+function tradesEveryDay(times: number[], tf: string): boolean {
+  if (times.length === 0) return false;
+  const info = timeframe.info(tf);
+  if (info.isweekly) return times.every((t) => t % DAY === 0 && new Date(t).getUTCDay() === 1);
+  if (info.ismonthly) return times.every((t) => t % DAY === 0 && new Date(t).getUTCDate() === 1);
+  return times.some((t) => {
+    const wd = new Date(t).getUTCDay();
+    return wd === 0 || wd === 6;
+  });
+}
+
+/** True when most of the last bars open at the start of a period of `tf` on the calendar `zone`. */
+function onCalendar(times: number[], tf: string, zone: Zone | null): boolean {
+  const calendar = calendarOf(zone, tf);
+  if (!calendar || times.length === 0) return false;
+  const last = times.slice(-50);
+  return last.filter((t) => periodTime(t, tf, calendar) === t).length >= 0.9 * last.length;
+}
+
+const utcDay = (t: number): number => Math.floor(t / DAY) * DAY;
+/** Monday 00:00 UTC of the week of the day `day` (00:00 UTC, ms). */
+const weekStart = (day: number): number => day - ((new Date(day).getUTCDay() + 6) % 7) * DAY;
+const monthStart = (day: number): number => {
+  const d = new Date(day);
+  return Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), 1);
+};
+
+/** 00:00 UTC after the last weekday before `end` (00:00 UTC, ms): the end of a period of a Monday-to-Friday symbol. */
+function afterLastWeekday(end: number): number {
+  let day = end - DAY;
+  while (new Date(day).getUTCDay() % 6 === 0) day -= DAY;
+  return day + DAY;
+}
+
+/** Close time (ms) of each bar of timeframe `tf` opening at `times` (ms). */
+function closeTimes(times: number[], tf: string, zone: Zone | null): number[] {
+  const calendar = calendarOf(zone, tf);
+  const info = timeframe.info(tf);
+  const len = timeframe.in_seconds(tf) * 1000;
+  return times.map((t, i) => {
+    if (calendar) {
+      const c = periodClose(t, tf, calendar);
+      if (!Number.isNaN(c)) return c;
+    }
+    if (info.isintraday) return i + 1 < times.length ? Math.min(t + len, times[i + 1]!) : t + len;
+    const day = utcDay(t);
+    if (info.isweekly) return afterLastWeekday(weekStart(day) + 7 * DAY * info.multiplier);
+    if (info.ismonthly) {
+      const d = new Date(day);
+      return afterLastWeekday(Date.UTC(d.getUTCFullYear(), d.getUTCMonth() + info.multiplier, 1));
+    }
+    return day + DAY * info.multiplier;
+  });
+}
+
+/** Trading day (00:00 UTC, ms) of each bar opening at `times` (ms): its date in the exchange time zone. */
+function tradingDays(times: number[], zone: Zone | null): number[] {
+  const calendar = calendarOf(zone, '1D');
+  return times.map((t) => {
+    const d = calendar ? tradingDayTime(t, calendar) : NaN;
+    return Number.isNaN(d) ? utcDay(t) : d;
+  });
+}
+
+/** For each element of `at` (non-decreasing), the index of the last element of `keys` (non-decreasing) <= it; -1: none. */
+function latestAtOrBefore(keys: number[], at: number[]): number[] {
+  let j = -1;
+  return at.map((x) => {
+    while (j + 1 < keys.length && keys[j + 1]! <= x) j++;
+    return j;
+  });
+}
+
+const zoneOf = (c: SymbolCalendar | undefined): Zone | null =>
+  c?.timezone && c.session ? { timezone: c.timezone, session: c.session } : null;
+
+/** Timeframes and exchange calendars of a merge: given, 24x7, the chart's, else the UTC rule. */
+function setup(
+  ct: number[],
+  ot: number[],
+  tf: string,
+  chart: OtherSymbolChart,
+  options: OtherSymbolOptions
+): { chartTf: string; otherTf: string; chartZone: Zone | null; otherZone: Zone | null } {
+  const chartTf = timeframe.info(chart.timeframe).period;
+  const otherTf = tf.trim() === '' ? chartTf : timeframe.info(tf).period;
+  if (timeframe.info(otherTf).isticks) throw new RangeError(`request.security: tick timeframe "${tf}" is not supported.`);
+  const chartZone = zoneOf(chart) ?? (tradesEveryDay(ct, chartTf) ? UTC_24X7 : null);
+  const otherZone =
+    zoneOf(options.other) ??
+    (tradesEveryDay(ot, otherTf) ? UTC_24X7 : chartZone && onCalendar(ot, otherTf, chartZone) ? chartZone : null);
+  return { chartTf, otherTf, chartZone, otherZone };
+}
+
+/**
+ * PineScript `request.security` of another symbol: the index in `otherBars` of the bar shown on each chart bar, -1
+ * for na (#179). `otherBars` are the bars of the other symbol on `tf` ("" for the chart timeframe, or a higher
+ * or a lower one), with times in the unit of the chart bars. Rules in the module notes; the same rules hold for a
+ * lower timeframe (#181): lookahead off shows the last lower bar that closes by the close of the chart bar, lookahead
+ * on the last one that opened by its open. It also serves the chart symbol on a lower timeframe.
+ * @throws RangeError for a tick timeframe
+ */
+export function securityOther(
+  chartBars: ReadonlyArray<{ time: number }>,
+  otherBars: ReadonlyArray<{ time: number }>,
+  tf: string,
+  chart: OtherSymbolChart,
+  options: OtherSymbolOptions = {}
+): number[] {
+  const n = chartBars.length;
+  if (n === 0) return [];
+  const unit = chart.timeUnit === 'ms' ? 1 : 1000;
+  const ct = chartBars.map((b) => b.time * unit);
+  const ot = otherBars.map((b) => b.time * unit);
+  const { chartTf, otherTf, chartZone, otherZone } = setup(ct, ot, tf, chart, options);
+  if (ot.length === 0) return new Array<number>(n).fill(-1);
+
+  // by trading day when both timeframes are D / W / M; by open time with an intraday side (#181)
+  const daily = timeframe.info(chartTf).isdwm && timeframe.info(otherTf).isdwm;
+  const realtime = chart.lastBarConfirmed === false && !options.gaps;
+  let on: number[] = [];
+  if (options.lookahead || realtime) {
+    if (daily) {
+      const info = timeframe.info(otherTf);
+      const starts = tradingDays(ot, otherZone).map((d) => (info.isweekly ? weekStart(d) : info.ismonthly ? monthStart(d) : d));
+      on = latestAtOrBefore(starts, tradingDays(ct, chartZone));
+    } else {
+      on = latestAtOrBefore(ot, ct);
+    }
+  }
+  const index = options.lookahead ? on : latestAtOrBefore(closeTimes(ot, otherTf, otherZone), closeTimes(ct, chartTf, chartZone));
+  // realtime updates of the open last bar: lookahead off shows the bar of lookahead on
+  if (realtime) index[n - 1] = on[n - 1]!;
+  if (!options.gaps) return index;
+  return index.map((j, i) => (i === 0 || j !== index[i - 1] ? j : -1));
+}
+
+/**
+ * PineScript `request.security_lower_tf` (#181): for each chart bar, the range `[from, to)` of the bars of
+ * `otherBars` (a lower timeframe, the chart symbol or another one) that it contains: the bars whose close time is
+ * after the open of the chart bar and at or before its close (a 13:00 hourly bar of a 24x7 symbol is in a 13:30 stock
+ * day, which closes at 20:00). An empty range for a chart bar without such bars.
+ */
+export function securityLowerTf(
+  chartBars: ReadonlyArray<{ time: number }>,
+  otherBars: ReadonlyArray<{ time: number }>,
+  tf: string,
+  chart: OtherSymbolChart,
+  options: Pick<OtherSymbolOptions, 'other'> = {}
+): Array<[number, number]> {
+  const unit = chart.timeUnit === 'ms' ? 1 : 1000;
+  const ct = chartBars.map((b) => b.time * unit);
+  const ot = otherBars.map((b) => b.time * unit);
+  const { chartTf, otherTf, chartZone, otherZone } = setup(ct, ot, tf, chart, options);
+  const oc = closeTimes(ot, otherTf, otherZone);
+  const from = latestAtOrBefore(oc, ct);
+  const to = latestAtOrBefore(oc, closeTimes(ct, chartTf, chartZone));
+  return ct.map((_, i) => [from[i]! + 1, Math.max(from[i]! + 1, to[i]! + 1)]);
+}
+
+/**
+ * {@link securityOther} with the values of an expression: `values` has one value per bar of the other symbol; the
+ * result has one value per chart bar, NaN for na.
+ */
+export function securityOtherValues(
+  chartBars: ReadonlyArray<{ time: number }>,
+  otherBars: ReadonlyArray<{ time: number }>,
+  tf: string,
+  values: ArrayLike<number>,
+  chart: OtherSymbolChart,
+  options: OtherSymbolOptions = {}
+): number[] {
+  return securityOther(chartBars, otherBars, tf, chart, options).map((j) => (j < 0 ? NaN : (values[j] ?? NaN)));
+}

package/src/session/bars.ts

@@ -113,7 +113,8 @@ export class SessionBars {
 
   /**
    * 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).
+   * opens after an early close has no day and no intraday period: `time("D")`, `time("240")` and `time("60")` are
+   * NaN on it (measured; `time("W")` keeps its value).
    */
   timeOf(time: number, timeframe: string): number {
     const tf = info(timeframe);
@@ -121,6 +122,8 @@ export class SessionBars {
     if (!at) return NaN;
     if (tf.isintraday) {
       if (this.chart.isdwm) return time;
+      // a bar after an early close has no intraday period either (#173)
+      if (this.stray(time)) return NaN;
       const [start] = this.calendar.periods(at.date)[at.index]!;
       const ms = in_seconds(tf.period) * 1000;
       return start + Math.floor((time - start) / ms) * ms;
@@ -141,6 +144,7 @@ export class SessionBars {
       const [, end] = this.calendar.periods(at.date)[at.index]!;
       // on D / W / M charts: the end of the session period that contains the bar open
       if (this.chart.isdwm) return end;
+      if (this.stray(time)) return NaN;
       return Math.min(this.timeOf(time, timeframe) + in_seconds(tf.period) * 1000, end);
     }
     const { unit, n } = unitOf(tf);
@@ -234,6 +238,25 @@ export class SessionBars {
   }
 }
 
+/**
+ * Periods of the chart bars that open after an early close, for `request.security` (#173): such a bar has no period
+ * (`time("D")` and `time("240")` are na on it), but PineScript resamples it into the D / W / M bar of the bar before
+ * it, and into an intraday bar of its own (opening at the bar's time). The bar before it still completes its period
+ * (its day period is cut there). `intradayMs` is the duration of an intraday timeframe, null for D / W / M.
+ * Changes `starts` and `dayPeriods` in place.
+ */
+export function strayPeriods(starts: number[], dayPeriods: number[], times: number[], bars: SessionBars, intradayMs: number | null): void {
+  for (let i = 1; i < starts.length; i++) {
+    if (!bars.stray(times[i]!)) continue;
+    if (Number.isNaN(starts[i]!)) {
+      // intraday: periods of `intradayMs` from the first such bar ("240": 18:30 and 20:30 are one bar)
+      const run = Number.isNaN(dayPeriods[i - 1]!) && times[i]! < starts[i - 1]! + (intradayMs ?? 0);
+      starts[i] = intradayMs === null || run ? starts[i - 1]! : times[i]!;
+    }
+    dayPeriods[i] = NaN;
+  }
+}
+
 /** PineScript `session.*` flags of each bar. */
 export interface SessionFlags {
   isfirstbar: boolean[];

package/src/session/calendar.ts

@@ -94,11 +94,16 @@ function pineVersion(text: string, from: DateNum): Version {
   const ranges = parsePineSession(text);
   if (ranges === null) throw new SyntaxError(`Session "${text}" is the symbol session`);
   const byDay: Period[][] = Array.from({ length: 8 }, () => []);
-  for (const { start, end, days } of ranges) {
+  for (const { start, end, days, startDays } of ranges) {
+    // a run that ends at 0000 ends at 24:00 of the day it starts and belongs to that day (#173)
     const period: Period =
       start === 0 && end === 0
         ? { start: 0, end: 1440, startOffset: 0, endOffset: 0 }
-        : { start, end, startOffset: end <= start ? 1 : 0, endOffset: 0 };
+        : startDays !== undefined
+          ? { start, end, startOffset: startDays, endOffset: 0 }
+          : end === 0
+            ? { start, end: 1440, startOffset: 0, endOffset: 0 }
+            : { start, end, startOffset: end <= start ? 1 : 0, endOffset: 0 };
     for (const d of days) byDay[d]!.push(period);
   }
   return { from, periods: [], days: byDay.map((p) => p.length > 0), byDay };
@@ -133,17 +138,22 @@ export class TradingCalendar {
   private readonly corrections = new Map<DateNum, Period[] | null>();
   private readonly holidays: Set<DateNum>;
   private readonly cache = new Map<DateNum, Array<[number, number]>>();
+  private readonly pine: boolean;
 
   /**
    * @param timezone - Time zone of the session hours (the exchange time zone)
    * @param spec - Session information (hours, corrections, holidays)
    * @param rule - Days without ":days": 'symbol' (Monday to Friday) or 'pine' (PineScript session strings)
+   * @param dayPlacement - PineScript session strings read for `time("D", session)`: the wall times of a clock-change
+   *   day are placed as the JVM does (see `periods`); without it, as `time.inSession` places them
    */
   constructor(
     readonly timezone: string,
     spec: SessionSpec,
-    rule: 'symbol' | 'pine' = 'symbol'
+    rule: 'symbol' | 'pine' = 'symbol',
+    dayPlacement = false
   ) {
+    this.pine = rule === 'pine' && dayPlacement;
     const [first = '', ...changes] = spec.session.split('#');
     this.versions = [parseVersion(first, 0, spec.session, rule)];
     for (const change of changes) {
@@ -177,10 +187,19 @@ export class TradingCalendar {
     const y = Math.floor(date / 10000);
     const m = Math.floor(date / 100) % 100;
     const d = date % 100;
-    out = periods.map((p) => [
-      zonedToUnix(this.timezone, y, m, d - p.startOffset, Math.floor(p.start / 60), p.start % 60),
-      zonedToUnix(this.timezone, y, m, d - p.endOffset, Math.floor(p.end / 60), p.end % 60),
-    ]);
+    const at = (dd: number, minutes: number, earlier = false): number =>
+      zonedToUnix(this.timezone, y, m, dd, Math.floor(minutes / 60), minutes % 60, 0, earlier);
+    // for "D", PineScript session strings place the wall times of a clock-change day as the JVM does: a skipped time moves
+    // past the gap, a repeated time is its first pass, and the end is the minute before it plus one minute ("0000-0300"
+    // on a 02:00 -> 03:00 night ends at 03:00 of the old offset, "0000-0400" at 04:00 of the new one) (#173)
+    out = periods.map((p) =>
+      this.pine
+        ? [at(d - p.startOffset, p.start, true), at(d - p.endOffset, p.end - 1, true) + 60_000]
+        : [at(d - p.startOffset, p.start), at(d - p.endOffset, p.end)]
+    );
+    // for "D", the runs of a PineScript session string on one day are one period, from the earliest start to the
+    // latest end: the time between two runs is inside the day (#182)
+    if (this.pine && out.length > 1) out = [[Math.min(...out.map((p) => p[0])), Math.max(...out.map((p) => p[1]))]];
     this.cache.set(date, out);
     return out;
   }

package/src/session/context.ts

@@ -11,7 +11,8 @@
 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 { parsePineSession, sessionRun } from '../time/session.js';
+import { SessionBars, sessionFlags, strayPeriods, 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). */
@@ -61,16 +62,107 @@ export function chartSessions(chart: SessionContext): ChartSessions {
   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);
+/** Open and close (ms) of the period that contains a bar opening at a time in ms; NaN outside the session. */
+export interface SessionPeriods {
+  open: (time: number) => number;
+  close: (time: number) => number;
+}
+
+/**
+ * Calendar for the `session` / `timezone` arguments of `time(tf, session, timezone)`. Without both: 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(
+  bars: SessionBars,
+  chart: SessionContext,
+  session: string | undefined,
+  timezone: string | undefined,
+  dayPlacement: boolean
+): { bars: SessionBars; test: boolean; inside?: (time: number) => boolean } {
+  if (!session && !timezone) return { bars, test: false };
+  const tz = timezone ?? chart.timezone!;
+  // 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' && chart.regularSession ? chart.regularSession : chart.session!;
+    return { bars: new SessionBars(new TradingCalendar(tz, { session: toSpec(symbol).session }, 'symbol'), bars.chart.period), test: true };
+  }
+  const spec = session ? { session } : { session: toSpec(chart.session!).session };
+  return {
+    bars: new SessionBars(new TradingCalendar(tz, spec, session ? 'pine' : 'symbol', dayPlacement), 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) => sessionRun(time, session, tz, in_seconds(bars.chart.period) * 1000) !== null : undefined,
+  };
+}
+
+/**
+ * `time(tf, session, timezone)` / `time_close(tf, session, timezone)` of a bar, as PineScript computes them (#173):
+ * an intraday timeframe tests the bar with the session rules of time.inSession and aligns its periods on the start
+ * of the run that contains the bar; "D" tests the bar against the day's session period (the calendar; the time
+ * between two runs of a day is inside it, #182); a timeframe of more than one day ("2D", "W", "M") has no test and
+ * keeps the period's time. `bars` is the calendar of the loaded session (`chartSessions(chart).bars`).
+ */
+export function sessionPeriods(
+  bars: SessionBars,
+  chart: SessionContext,
+  timeframe: string,
+  session?: string,
+  timezone?: string
+): SessionPeriods {
+  const tf = info(timeframe);
+  const { bars: calendar, test, inside } = calendarFor(bars, chart, session, timezone, !tf.isintraday);
+  const open = (t: number): number => calendar.timeOf(t, timeframe);
+  const close = (t: number): number => calendar.closeOf(t, timeframe);
+  if (!test) return { open, close };
+  if (tf.isintraday) {
+    if (session !== undefined && parsePineSession(session) !== null && !calendar.chart.isdwm) {
+      const tz = timezone ?? chart.timezone!;
+      const barMs = in_seconds(calendar.chart.period) * 1000;
+      const ms = in_seconds(tf.period) * 1000;
+      const run = (t: number) => sessionRun(t, session, tz, barMs);
+      const start = (t: number, r: [number, number]) => r[0] + Math.floor((t - r[0]) / ms) * ms;
+      return {
+        open: (t) => { const r = run(t); return r ? start(t, r) : NaN; },
+        close: (t) => { const r = run(t); return r ? Math.min(start(t, r) + ms, r[1]) : NaN; },
+      };
+    }
+    const isIn = (t: number) => (inside ? inside(t) : calendar.inside(t));
+    return { open: (t) => (isIn(t) ? open(t) : NaN), close: (t) => (isIn(t) ? close(t) : NaN) };
+  }
+  if (tf.isdaily && tf.multiplier === 1) {
+    return { open: (t) => (calendar.inside(t) ? open(t) : NaN), close: (t) => (calendar.inside(t) ? close(t) : NaN) };
+  }
+  return { open, close };
 }
 
-/** PineScript `time_close(timeframe)` (ms) of a bar that opens at `time`. */
-export function periodClose(time: number, timeframe: string, chart: SessionContext): number {
+const periodCache = new WeakMap<object, Map<string, SessionPeriods>>();
+
+function periodsOfChart(chart: SessionContext, timeframe: string, session?: string, timezone?: string): { s: ChartSessions; p: SessionPeriods } {
   const s = chartSessions(chart);
-  return s.bars.closeOf(time * s.unit, timeframe);
+  let byKey = periodCache.get(chart);
+  if (!byKey) periodCache.set(chart, (byKey = new Map()));
+  const key = `${timeframe}|${session ?? ''}|${timezone ?? ''}`;
+  let p = byKey.get(key);
+  if (!p) byKey.set(key, (p = sessionPeriods(s.bars, chart, timeframe, session, timezone)));
+  return { s, p };
+}
+
+/**
+ * PineScript `time(timeframe, session, timezone)` (ms) of a bar that opens at `time`: the start of its period; NaN
+ * without one or outside `session` (#182). Without `session` and `timezone`, the periods of the loaded session.
+ */
+export function periodTime(time: number, timeframe: string, chart: SessionContext, session?: string, timezone?: string): number {
+  const { s, p } = periodsOfChart(chart, timeframe, session, timezone);
+  return p.open(time * s.unit);
+}
+
+/** PineScript `time_close(timeframe, session, timezone)` (ms) of a bar that opens at `time` (#182). */
+export function periodClose(time: number, timeframe: string, chart: SessionContext, session?: string, timezone?: string): number {
+  const { s, p } = periodsOfChart(chart, timeframe, session, timezone);
+  return p.close(time * s.unit);
 }
 
 /** PineScript `time_tradingday` (ms, 00:00 UTC of the trading day) of a bar that opens at `time`. */
@@ -120,6 +212,7 @@ export function resampleSession(bars: Bar[], timeframe: string, chart: SessionCo
     const periods = at ? calendar.calendar.periods(at.date) : [];
     return periods.length ? calendar.timeOf(periods[0]![0], tf.period) : starts[i]!;
   });
+  strayPeriods(starts, dayPeriods, times, s.bars, tf.isdwm ? null : in_seconds(tf.period) * 1000);
   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)
@@ -144,11 +237,12 @@ export function barTimeAfter(time: number, count: number, chart: SessionContext)
  * 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.
+ * holidays skipped. `to` is first rounded to the nearest second, a half second going up (#174: 15 ms before a bar
+ * opens is on that bar, 501 ms before is on the bar before). 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;
+  const target = Math.floor((to * s.unit) / 1000 + 0.5) * 1000;
   let t = from * s.unit;
   for (let k = 0; k < 100_000; k++) {
     const next = s.bars.nextBarTime(t);