oakscriptjs 0.8.1 → 0.9.0

package/src/security/resample.ts

@@ -0,0 +1,119 @@
+/**
+ * Same-symbol `request.security` by resampling the chart bars (issue #101).
+ * PineScript rules:
+ *
+ * - `lookahead_off` (default): the value of a higher-timeframe period appears on the chart bar that
+ *   completes the period; before that, the chart bars show the previous period's value
+ * - `lookahead_on`: every chart bar of a period shows the value of that period
+ * - `gaps_on`: only the bar where the value appears has it (the completing bar with lookahead off, the
+ *   first bar of the period with lookahead on); the other bars are `na`
+ * - a bar completes its period only if it closes at or after the end of the period (a period still
+ *   trading keeps showing the previous completed value); when the bars at the end of a period are missing
+ *   (data gap, a day off not in the calendar), the period completes on the first bar of the next period
+ * - D / W / M periods follow the regular hours: on extended-hours charts the premarket bars still show
+ *   the previous period, which completes on the last bar of its trading day
+ * - a higher-timeframe bar only holds the chart bars up to the bar that completes it: the premarket bars
+ *   that still show the previous period are not part of its bar (no value from after the completion)
+ */
+
+import type { Bar } from '../types/index.js';
+
+/** Higher-timeframe bars and the period index of each chart bar. */
+export interface Resampled {
+  bars: Bar[];
+  /** Index in `bars` of the period of each chart bar */
+  group: number[];
+}
+
+/**
+ * Groups consecutive chart bars with the same period start into higher-timeframe bars.
+ * @param bars - Chart bars (in order)
+ * @param periodStart - Period start of each chart bar, in the unit of `Bar.time`
+ */
+export function resample(bars: Bar[], periodStart: number[]): Resampled {
+  const out: Bar[] = [];
+  const group: number[] = [];
+  bars.forEach((b, i) => {
+    const start = periodStart[i]!;
+    const last = out[out.length - 1];
+    if (!last || last.time !== start) {
+      out.push({ time: start, open: b.open, high: b.high, low: b.low, close: b.close, volume: b.volume ?? NaN });
+    } else {
+      last.high = Math.max(last.high, b.high);
+      last.low = Math.min(last.low, b.low);
+      last.close = b.close;
+      last.volume = (last.volume ?? 0) + (b.volume ?? NaN);
+    }
+    group.push(out.length - 1);
+  });
+  return { bars: out, group };
+}
+
+/**
+ * Period index of each chart bar, and the latest completed period at each chart bar.
+ * @param starts - Period start of each chart bar (the higher-timeframe bar it belongs to)
+ * @param dayPeriods - Period of the trading day of each chart bar in the loaded session: on extended-hours
+ *   charts the premarket bars still belong to the previous daily period, but a new trading day completes it
+ * @param reaches - True when the chart bar closes at or after the end of its period
+ */
+export function periodsOf(starts: number[], dayPeriods: number[], reaches: boolean[]): { group: number[]; latest: number[] } {
+  const n = starts.length;
+  const group: number[] = [];
+  starts.forEach((s, i) => group.push(i === 0 ? 0 : group[i - 1]! + (s !== starts[i - 1] ? 1 : 0)));
+  const latest: number[] = [];
+  starts.forEach((s, i) => {
+    let done = i === 0 ? -1 : latest[i - 1]!;
+    // a new period completes all the earlier ones (their last bars may be missing)
+    if (i > 0 && group[i] !== group[i - 1]) done = Math.max(done, group[i]! - 1);
+    // the last bar of its period in the loaded session (the premarket bars after it do not complete it again)
+    const ends = i < n - 1 ? starts[i + 1] !== s || dayPeriods[i + 1] !== dayPeriods[i] : true;
+    if (ends && reaches[i]) done = Math.max(done, group[i]!);
+    latest.push(done);
+  });
+  return { group, latest };
+}
+
+/**
+ * True for the chart bars that come after the bar that completed their period: on extended-hours charts
+ * the premarket bars of the next trading day still show the previous D / W / M period, but they are not
+ * part of its higher-timeframe bar. A period's first bar is never after its completion.
+ * @param group - Period index of each chart bar
+ * @param latest - Latest completed period at each chart bar
+ */
+export function afterCompletion(group: number[], latest: number[]): boolean[] {
+  return group.map((g, i) => i > 0 && group[i - 1] === g && latest[i - 1]! >= g);
+}
+
+/**
+ * Maps values computed on the higher-timeframe bars to the chart bars.
+ * @param values - One value per higher-timeframe bar
+ * @param group - Period index of each chart bar
+ * @param latest - Latest completed period at each chart bar (-1: none yet)
+ */
+export function mapToChart(values: number[], group: number[], latest: number[], lookahead: boolean, gaps: boolean): number[] {
+  return group.map((g, i) => {
+    if (lookahead) {
+      const first = i === 0 || group[i - 1] !== g;
+      return gaps && !first ? NaN : (values[g] ?? NaN);
+    }
+    const done = latest[i]!;
+    if (done < 0 || (gaps && i > 0 && latest[i - 1] === done)) return NaN;
+    return values[done] ?? NaN;
+  });
+}
+
+/**
+ * Heikin Ashi bars (PineScript `ticker.heikinashi`): close = (open + high + low + close) / 4, open = the
+ * average of the previous Heikin Ashi open and close ((open + close) / 2 on the first bar),
+ * high / low = the extremes of high / low and the Heikin Ashi open and close.
+ */
+export function heikinAshi(bars: Bar[]): Bar[] {
+  const out: Bar[] = [];
+  bars.forEach((b, i) => {
+    const close = (b.open + b.high + b.low + b.close) / 4;
+    const prev = out[i - 1];
+    const open = prev ? (prev.open + prev.close) / 2 : (b.open + b.close) / 2;
+    out.push({ time: b.time, open, high: Math.max(b.high, open, close), low: Math.min(b.low, open, close), close, volume: b.volume });
+  });
+  return out;
+}

package/src/session/bars.ts

@@ -0,0 +1,262 @@
+/**
+ * PineScript values that depend on the chart timeframe and the symbol session (issue #100):
+ * `time(tf)`, `time_close(tf)`, `timeframe.change(tf)`, `time_tradingday`, `session.*`.
+ * PineScript rules:
+ *
+ * - intraday periods are aligned on the start of the session period of the trading day: 240 minutes from
+ *   09:30 gives 09:30, 13:30; `time(tf)` is the start of the period that contains the bar open
+ * - "D" is the session start of the trading day; "W" / "M" the session start of the first trading day
+ *   of the week (Monday to Sunday) / month
+ * - intraday closes are cut at the end of the session period; the "D" close is the session end
+ * - on intraday charts the "W" / "M" (and "nD") close is the session start of the next period's first
+ *   trading day; on D / W / M charts it is the session end of the last trading day of the week / month
+ * - on D / W / M charts, intraday timeframes give the chart bar's time, and the end of the session
+ *   period that contains the bar open as close
+ * - `time_tradingday` is 00:00 UTC of the trading day (on W / M charts, of the last trading day)
+ *
+ * Multipliers above one day (issue #100 follow-up): periods restart each
+ * calendar year. "nD" groups n trading days from the first trading day of the year; "nW" groups n weeks from
+ * the first week whose Monday is in the year; "nM" groups n months from January. The last group of a year
+ * can be shorter.
+ */
+
+import { info, in_seconds, type TimeframeInfo } from '../timeframe/index.js';
+import {
+  TradingCalendar,
+  addDays,
+  dateUtcMs,
+  monthEnd,
+  monthStart,
+  weekStart,
+  type DateNum,
+} from './calendar.js';
+
+type Unit = 'D' | 'W' | 'M';
+
+function unitOf(tf: TimeframeInfo): { unit: Unit; n: number } {
+  return { unit: tf.isdaily ? 'D' : tf.isweekly ? 'W' : 'M', n: tf.multiplier };
+}
+
+const yearOf = (date: DateNum): number => Math.floor(date / 10000);
+
+/** Monday of the first week of `year` (the first Monday on or after 1 January). */
+const firstMonday = (year: number): DateNum => {
+  const jan1 = year * 10000 + 101;
+  const monday = weekStart(jan1);
+  return monday === jan1 ? jan1 : addDays(monday, 7);
+};
+
+/** Values of the bars of one chart, for a trading calendar. */
+export class SessionBars {
+  readonly chart: TimeframeInfo;
+
+  private readonly yearDays = new Map<number, DateNum[]>();
+
+  constructor(
+    readonly calendar: TradingCalendar,
+    chartTimeframe: string
+  ) {
+    this.chart = info(chartTimeframe);
+  }
+
+  /** Trading days of a calendar year, in order. */
+  private tradingDaysOf(year: number): DateNum[] {
+    let days = this.yearDays.get(year);
+    if (!days) {
+      days = [];
+      for (let date = year * 10000 + 101; yearOf(date) === year; date = addDays(date, 1)) {
+        if (this.calendar.isTradingDay(date)) days.push(date);
+      }
+      this.yearDays.set(year, days);
+    }
+    return days;
+  }
+
+  /**
+   * Dates [from, to] of the `n`-`unit` period that contains `date` (for "D": its first and last trading days).
+   * Periods restart each calendar year.
+   */
+  private periodRange(date: DateNum, unit: Unit, n: number): [DateNum, DateNum] {
+    if (unit === 'D') {
+      if (n === 1) return [date, date];
+      const days = this.tradingDaysOf(yearOf(date));
+      let k = days.findIndex((d) => d >= date);
+      if (k === -1) return this.periodRange(yearOf(date) * 10000 + 10000 + 101, unit, n);
+      k -= k % n;
+      return [days[k]!, days[Math.min(k + n, days.length) - 1]!];
+    }
+    if (unit === 'W') {
+      const monday = weekStart(date);
+      const year = yearOf(monday);
+      const first = firstMonday(year);
+      const next = firstMonday(year + 1);
+      const k = Math.round((dateUtcMs(monday) - dateUtcMs(first)) / (7 * 86_400_000));
+      const from = addDays(first, (k - (k % n)) * 7);
+      const to = addDays(from, n * 7 - 1);
+      return [from, to < next ? to : addDays(next, -1)];
+    }
+    const year = yearOf(date);
+    const month = Math.floor(date / 100) % 100;
+    const firstMonth = month - ((month - 1) % n);
+    const lastMonth = Math.min(firstMonth + n - 1, 12);
+    return [monthStart(year * 10000 + firstMonth * 100 + 1), monthEnd(year * 10000 + lastMonth * 100 + 1)];
+  }
+
+  private dayStart(date: DateNum): number {
+    return this.calendar.periods(date)[0]![0];
+  }
+
+  private dayEnd(date: DateNum): number {
+    const p = this.calendar.periods(date);
+    return p[p.length - 1]![1];
+  }
+
+  /** PineScript `time(tf)` for a bar that opens at `time`; NaN when no trading day is found. */
+  timeOf(time: number, timeframe: string): number {
+    const tf = info(timeframe);
+    const at = this.calendar.locate(time);
+    if (!at) return NaN;
+    if (tf.isintraday) {
+      if (this.chart.isdwm) return time;
+      const [start] = this.calendar.periods(at.date)[at.index]!;
+      const ms = in_seconds(tf.period) * 1000;
+      return start + Math.floor((time - start) / ms) * ms;
+    }
+    const { unit, n } = unitOf(tf);
+    const [from, to] = this.periodRange(at.date, unit, n);
+    const first = this.calendar.firstTradingDay(from, to);
+    return first === null ? NaN : this.dayStart(first);
+  }
+
+  /** PineScript `time_close(tf)` for a bar that opens at `time`. */
+  closeOf(time: number, timeframe: string): number {
+    const tf = info(timeframe);
+    const at = this.calendar.locate(time);
+    if (!at) return NaN;
+    if (tf.isintraday) {
+      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;
+      return Math.min(this.timeOf(time, timeframe) + in_seconds(tf.period) * 1000, end);
+    }
+    const { unit, n } = unitOf(tf);
+    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)) {
+      const [nextFrom, nextTo] = this.periodRange(addDays(to, 1), unit, n);
+      const first = this.calendar.firstTradingDay(nextFrom, addDays(nextTo, 31));
+      return first === null ? NaN : this.dayStart(first);
+    }
+    const last = this.calendar.lastTradingDay(from, to);
+    return last === null ? NaN : this.dayEnd(last);
+  }
+
+  /** 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 (this.chart.isdwm) {
+      const { unit, n } = unitOf(this.chart);
+      const [from, to] = this.periodRange(at.date, unit, n);
+      return this.calendar.lastTradingDay(from, to);
+    }
+    return at.date;
+  }
+
+  /**
+   * End of the `timeframe` period that contains `time`: the intraday close, the session end of the day,
+   * or the session end of the last trading day of the period. Used to know whether the last loaded
+   * bar completes a higher-timeframe period (request.security).
+   */
+  periodEnd(time: number, timeframe: string): number {
+    const tf = info(timeframe);
+    const at = this.calendar.locate(time);
+    if (!at) return NaN;
+    if (tf.isintraday) {
+      const [, end] = this.calendar.periods(at.date)[at.index]!;
+      return Math.min(this.timeOf(time, timeframe) + in_seconds(tf.period) * 1000, end);
+    }
+    const { unit, n } = unitOf(tf);
+    const [from, to] = this.periodRange(at.date, unit, n);
+    const last = this.calendar.lastTradingDay(from, to);
+    return last === null ? NaN : this.dayEnd(last);
+  }
+
+  /** PineScript `time_tradingday`: 00:00 UTC of the trading day. */
+  tradingDayTime(time: number): number {
+    const day = this.tradingDay(time);
+    return day === null ? NaN : dateUtcMs(day);
+  }
+
+  /** True when the bar at `time` is inside the session. */
+  inside(time: number): boolean {
+    return this.calendar.locate(time)?.inside ?? false;
+  }
+
+  /** Session start and end of the trading day of `time`, or null. */
+  dayBounds(time: number): { date: DateNum; start: number; end: number } | null {
+    const at = this.calendar.locate(time);
+    return at ? { date: at.date, start: this.dayStart(at.date), end: this.dayEnd(at.date) } : null;
+  }
+}
+
+/** PineScript `session.*` flags of each bar. */
+export interface SessionFlags {
+  isfirstbar: boolean[];
+  islastbar: boolean[];
+  ismarket: boolean[];
+  ispremarket: boolean[];
+  ispostmarket: boolean[];
+  isfirstbar_regular: boolean[];
+  islastbar_regular: boolean[];
+}
+
+/**
+ * `session.*` flags for bars that open at `times` (in order). `regular` gives the regular trading
+ * hours when the bars include extended hours. PineScript rules: flags use the bar open
+ * 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).
+ */
+export function sessionFlags(times: number[], bars: SessionBars, regular: SessionBars): SessionFlags {
+  const n = times.length;
+  const flag = () => new Array<boolean>(n).fill(false);
+  const out: SessionFlags = {
+    isfirstbar: flag(), islastbar: flag(), ismarket: flag(), ispremarket: flag(), ispostmarket: flag(),
+    isfirstbar_regular: flag(), islastbar_regular: flag(),
+  };
+  const chart = bars.chart;
+  let previousPeriod = '';
+  let previousRegular = '';
+  for (let i = 0; i < n; i++) {
+    const t = times[i]!;
+    if (chart.isdwm) {
+      for (const k of ['isfirstbar', 'islastbar', 'ismarket', 'isfirstbar_regular', 'islastbar_regular'] as const) out[k][i] = true;
+      continue;
+    }
+    const at = bars.calendar.locate(t);
+    if (!at) {
+      previousPeriod = previousRegular = '';
+      continue;
+    }
+    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 regularPeriods = regular.calendar.periods(at.date);
+    const r = regularPeriods.findIndex(([s, e]) => s <= t && t < e);
+    const market = r !== -1;
+    out.ismarket[i] = market;
+    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.islastbar_regular[i] = market && close >= regularPeriods[r]![1];
+    previousPeriod = period;
+    previousRegular = regularPeriod;
+  }
+  return out;
+}

package/src/session/calendar.ts

@@ -0,0 +1,199 @@
+/**
+ * Trading calendar: the session periods of each trading day of a symbol, from the symbol session
+ * information (issue #100).
+ *
+ * Session format (symbol session information, also PineScript session strings):
+ * - 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")
+ * - 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)
+ * - "#YYYYMMDD/<session>" changes the session from that date ("0900-1746#20251201/0800-2200")
+ * - corrections ("session-correction"): "<session>:<dates>;dayoff:<dates>" replace the session of these
+ *   dates (early closes, days off); holidays ("session_holidays") are dates without session
+ */
+
+import { zonedFields, zonedToUnix } from '../time/timezone.js';
+
+/** Session information of a symbol (hours, corrections, holidays). */
+export interface SessionSpec {
+  /** Session hours: "0930-1600", "1700-1600", "24x7", "0400-2000" ... */
+  session: string;
+  /** Exceptions by date (symbol info "session-correction"): "0930-1300:20251128,20251224;dayoff:20250109" */
+  corrections?: string;
+  /** Exchange holidays as "YYYYMMDD" (symbol info "session_holidays"), comma-separated or as an array */
+  holidays?: string | string[];
+}
+
+/** Date as YYYYMMDD. */
+export type DateNum = number;
+
+interface Period {
+  /** Minutes after midnight */
+  start: number;
+  end: number;
+  /** Days before the trading day */
+  startOffset: number;
+  endOffset: number;
+}
+
+interface Version {
+  from: DateNum;
+  periods: Period[];
+  /** Index 1 (Sunday) to 7 (Saturday) */
+  days: boolean[];
+}
+
+export const toDateNum = (y: number, m: number, d: number): DateNum => y * 10000 + m * 100 + d;
+const utcOf = (date: DateNum): number => Date.UTC(Math.floor(date / 10000), Math.floor(date / 100) % 100 - 1, date % 100);
+const fromUtc = (ms: number): DateNum => {
+  const d = new Date(ms);
+  return toDateNum(d.getUTCFullYear(), d.getUTCMonth() + 1, d.getUTCDate());
+};
+export const addDays = (date: DateNum, n: number): DateNum => fromUtc(utcOf(date) + n * 86_400_000);
+/** 1 = Sunday ... 7 = Saturday */
+export const weekdayOf = (date: DateNum): number => new Date(utcOf(date)).getUTCDay() + 1;
+/** 00:00 UTC of the date, in ms (PineScript `time_tradingday`). */
+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());
+  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]) };
+}
+
+function parsePeriods(text: string, spec: string): Period[] {
+  if (text.trim() === '24x7') return [{ start: 0, end: 1440, startOffset: 0, endOffset: 0 }];
+  return text.split(',').map((p) => {
+    const [a = '', b = ''] = p.split('-');
+    const s = parseTime(a, spec);
+    const e = parseTime(b, spec);
+    if (s.minutes === 0 && e.minutes === 0 && s.offset === undefined && e.offset === undefined) {
+      return { start: 0, end: 1440, startOffset: 0, endOffset: 0 };
+    }
+    return {
+      start: s.minutes,
+      end: e.minutes,
+      startOffset: s.offset ?? (e.minutes <= s.minutes ? 1 : 0),
+      endOffset: e.offset ?? 0,
+    };
+  });
+}
+
+function parseVersion(text: string, from: DateNum, spec: string, rule: 'symbol' | 'pine'): Version {
+  const [periodText = '', dayText] = text.trim().split(':');
+  const periods = parsePeriods(periodText, spec);
+  const allDays = periodText.trim() === '24x7' || (rule === 'pine' && periods.length === 1);
+  const digits = dayText ?? (allDays ? '1234567' : '23456');
+  if (!/^[1-7]+$/.test(digits)) throw new SyntaxError(`Invalid session days in "${spec}"`);
+  const days = new Array<boolean>(8).fill(false);
+  for (const d of digits) days[Number(d)] = true;
+  return { from, periods, days };
+}
+
+/** Session periods of every trading day of a symbol, as UNIX times (ms). */
+export class TradingCalendar {
+  private readonly versions: Version[];
+  private readonly corrections = new Map<DateNum, Period[] | null>();
+  private readonly holidays: Set<DateNum>;
+  private readonly cache = new Map<DateNum, Array<[number, number]>>();
+
+  /**
+   * @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)
+   */
+  constructor(
+    readonly timezone: string,
+    spec: SessionSpec,
+    rule: 'symbol' | 'pine' = 'symbol'
+  ) {
+    const [first = '', ...changes] = spec.session.split('#');
+    this.versions = [parseVersion(first, 0, spec.session, rule)];
+    for (const change of changes) {
+      const m = /^(\d{8})\/(.+)$/.exec(change.trim());
+      if (!m) throw new SyntaxError(`Invalid session change in "${spec.session}"`);
+      this.versions.push(parseVersion(m[2]!, Number(m[1]), spec.session, rule));
+    }
+    for (const part of (spec.corrections ?? '').split(';').filter((p) => p.trim())) {
+      const i = part.lastIndexOf(':');
+      const text = part.slice(0, i).trim();
+      const periods = text === 'dayoff' ? null : parsePeriods(text, part);
+      for (const date of part.slice(i + 1).split(',')) this.corrections.set(Number(date), periods);
+    }
+    const holidays = Array.isArray(spec.holidays) ? spec.holidays : (spec.holidays ?? '').split(',');
+    this.holidays = new Set(holidays.filter((h) => h.trim()).map(Number));
+  }
+
+  /** Session periods [start, end) of the trading day `date`; empty when the day has no session. */
+  periods(date: DateNum): Array<[number, number]> {
+    let out = this.cache.get(date);
+    if (out) return out;
+    let periods: Period[] = [];
+    const correction = this.corrections.get(date);
+    if (correction !== undefined) {
+      periods = correction ?? [];
+    } else if (!this.holidays.has(date)) {
+      const version = [...this.versions].reverse().find((v) => v.from <= date)!;
+      if (version.days[weekdayOf(date)]) periods = version.periods;
+    }
+    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),
+    ]);
+    this.cache.set(date, out);
+    return out;
+  }
+
+  isTradingDay(date: DateNum): boolean {
+    return this.periods(date).length > 0;
+  }
+
+  /**
+   * 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.
+   */
+  locate(time: number): { date: DateNum; index: number; inside: boolean } | null {
+    const f = zonedFields(time, this.timezone);
+    const local = toDateNum(f.year, f.month, f.day);
+    for (let k = 0; k <= 5; k++) {
+      const date = addDays(local, k);
+      const index = this.periods(date).findIndex(([s, e]) => s <= time && time < e);
+      if (index !== -1) return { date, index, inside: true };
+    }
+    for (let k = 5; k >= -7; k--) {
+      const date = addDays(local, k);
+      const periods = this.periods(date);
+      let index = -1;
+      periods.forEach(([s], i) => {
+        if (s <= time) index = i;
+      });
+      if (index !== -1) return { date, index, inside: false };
+    }
+    return null;
+  }
+
+  /** First trading day in [from, to] (dates), or null. */
+  firstTradingDay(from: DateNum, to: DateNum): DateNum | null {
+    for (let date = from; date <= to; date = addDays(date, 1)) if (this.isTradingDay(date)) return date;
+    return null;
+  }
+
+  /** Last trading day in [from, to] (dates), or null. */
+  lastTradingDay(from: DateNum, to: DateNum): DateNum | null {
+    for (let date = to; date >= from; date = addDays(date, -1)) if (this.isTradingDay(date)) return date;
+    return null;
+  }
+}
+
+/** Monday of the week of `date` (weeks run Monday to Sunday). */
+export const weekStart = (date: DateNum): DateNum => addDays(date, -((weekdayOf(date) + 5) % 7));
+/** First day of the month of `date`. */
+export const monthStart = (date: DateNum): DateNum => Math.floor(date / 100) * 100 + 1;
+/** Last day of the month of `date`. */
+export const monthEnd = (date: DateNum): DateNum => addDays(monthStart(addDays(monthStart(date), 32)), -1);

package/src/str/dateformat.ts

@@ -0,0 +1,104 @@
+/**
+ * Date patterns of `str.format_time` and `str.format("{0,date,...}")`, as PineScript formats them
+ * (Java SimpleDateFormat letters, English names):
+ *
+ * y year, M month (M, MM, MMM, MMMM), d day, E weekday (EEE, EEEE), u weekday number (1 = Monday),
+ * D day of year, w week of year (weeks start on Sunday, week 1 contains 1 January), H hour 0-23,
+ * k hour 1-24, K hour 0-11, h hour 1-12, a AM/PM, m minute, s second, S millisecond,
+ * Z offset (+0530), z time zone name, 'text' literal text ('' is a quote).
+ *
+ * `z` gives "UTC" for Etc/UTC, "GMT" for "UTC"/"GMT", "GMT+05:00" for other offsets, and the
+ * host's short English name for IANA zones (PineScript's names can differ, e.g. "IST" for Asia/Kolkata).
+ */
+
+import { zonedFields, zoneOffset } from '../time/timezone.js';
+
+const MONTHS = ['January', 'February', 'March', 'April', 'May', 'June', 'July', 'August', 'September',
+  'October', 'November', 'December'];
+const DAYS = ['Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday'];
+
+const pad = (n: number, width: number): string => String(n).padStart(width, '0');
+
+function zoneName(time: number, timezone: string, offsetMs: number): string {
+  if (timezone === 'Etc/UTC') return 'UTC';
+  if (/^(UTC|GMT)/.test(timezone)) {
+    if (offsetMs === 0) return 'GMT';
+    const minutes = Math.abs(offsetMs) / 60000;
+    return `GMT${offsetMs < 0 ? '-' : '+'}${pad(Math.floor(minutes / 60), 2)}:${pad(minutes % 60, 2)}`;
+  }
+  const part = new Intl.DateTimeFormat('en-US', { timeZone: timezone, timeZoneName: 'short' })
+    .formatToParts(time)
+    .find((p) => p.type === 'timeZoneName');
+  return part?.value ?? timezone;
+}
+
+/** Week of year: weeks start on Sunday and week 1 is the week that contains 1 January. */
+function weekOfYear(year: number, month: number, day: number): number {
+  const date = Date.UTC(year, month - 1, day);
+  const dow = new Date(date).getUTCDay();
+  const weekStart = date - dow * 86_400_000;
+  // the week that contains 1 January of the next year is week 1
+  if (weekStart + 6 * 86_400_000 >= Date.UTC(year + 1, 0, 1)) return 1;
+  const jan1 = Date.UTC(year, 0, 1);
+  const jan1Dow = new Date(jan1).getUTCDay();
+  return Math.floor((date - jan1 + jan1Dow * 86_400_000) / (7 * 86_400_000)) + 1;
+}
+
+/** Formats a UNIX time (ms) with a SimpleDateFormat pattern in `timezone`. */
+export function formatDate(time: number, pattern: string, timezone: string): string {
+  if (Number.isNaN(time)) return 'NaN';
+  const f = zonedFields(time, timezone);
+  const offset = zoneOffset(time, timezone);
+  const ms = ((time % 1000) + 1000) % 1000;
+  const dayOfYear = (Date.UTC(f.year, f.month - 1, f.day) - Date.UTC(f.year, 0, 1)) / 86_400_000 + 1;
+
+  let out = '';
+  for (let i = 0; i < pattern.length; ) {
+    const ch = pattern[i]!;
+    if (ch === "'") {
+      const end = pattern.indexOf("'", i + 1);
+      if (end === i + 1) {
+        out += "'";
+        i += 2;
+      } else {
+        out += pattern.slice(i + 1, end === -1 ? undefined : end);
+        i = end === -1 ? pattern.length : end + 1;
+      }
+      continue;
+    }
+    if (!/[A-Za-z]/.test(ch)) {
+      out += ch;
+      i++;
+      continue;
+    }
+    let n = 1;
+    while (pattern[i + n] === ch) n++;
+    i += n;
+    const hour12 = f.hour % 12;
+    switch (ch) {
+      case 'y': out += n === 2 ? pad(f.year % 100, 2) : pad(f.year, n); break;
+      case 'M': out += n >= 4 ? MONTHS[f.month - 1] : n === 3 ? MONTHS[f.month - 1]!.slice(0, 3) : pad(f.month, n); break;
+      case 'd': out += pad(f.day, n); break;
+      case 'E': out += n >= 4 ? DAYS[f.dayOfWeek - 1] : DAYS[f.dayOfWeek - 1]!.slice(0, 3); break;
+      case 'u': out += pad(f.dayOfWeek === 1 ? 7 : f.dayOfWeek - 1, n); break;
+      case 'D': out += pad(dayOfYear, n); break;
+      case 'w': out += pad(weekOfYear(f.year, f.month, f.day), n); break;
+      case 'H': out += pad(f.hour, n); break;
+      case 'k': out += pad(f.hour === 0 ? 24 : f.hour, n); break;
+      case 'K': out += pad(hour12, n); break;
+      case 'h': out += pad(hour12 === 0 ? 12 : hour12, n); break;
+      case 'a': out += f.hour < 12 ? 'AM' : 'PM'; break;
+      case 'm': out += pad(f.minute, n); break;
+      case 's': out += pad(f.second, n); break;
+      case 'S': out += pad(ms, n); break;
+      case 'Z': {
+        const minutes = Math.abs(offset) / 60000;
+        out += (offset < 0 ? '-' : '+') + pad(Math.floor(minutes / 60), 2) + pad(minutes % 60, 2);
+        break;
+      }
+      case 'z': out += zoneName(time, timezone, offset); break;
+      default: throw new SyntaxError(`Unsupported date pattern letter "${ch}" in "${pattern}"`);
+    }
+  }
+  return out;
+}