oakscriptjs 0.10.0 → 0.11.0

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

@@ -9,10 +9,9 @@
  * @version 6
  */
 
-import { formatNumber } from './numberformat.js';
+import { formatNumber, tickScale } from './numberformat.js';
 import { formatMessage } from './messageformat.js';
 import { formatDate } from './dateformat.js';
-import { round_to_mintick } from '../math/index.js';
 import type { int, bool, float, simple_int, simple_string } from '../types/index.js';
 
 /**
@@ -40,11 +39,15 @@ export function length(str: simple_string): int {
  *   `format.price` / `format.inherit`
  * @param mintick - Tick size for `format.mintick` (PineScript `syminfo.mintick`, implicit there). Not part of the
  *   PineScript signature: the core function cannot see the chart, so pass it, as for `math.round_to_mintick`
+ * @param pricescale - Price scale of the symbol for `format.mintick` (PineScript `syminfo.pricescale`), needed for a
+ *   symbol priced in fractions (32 for a 1/32 tick). Default: 10^(decimals of `mintick`)
  * @returns String representation of the value
  *
  * @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)")
@@ -53,8 +56,12 @@ export function length(str: simple_string): int {
  * - `format.percent` shows 2 decimals and "%" without multiplying; `format.volume` uses K, M, B, T
  * - `format.price` and `format.inherit` give "price1" / "inherit1" in PineScript: they are patterns
  *   without digit characters, and oakscriptjs does the same
- * - `format.mintick` rounds to the tick (`math.round_to_mintick`) and shows the tick's decimals ("#.##" for 0.01);
- *   it throws without `mintick`
+ * - `format.mintick` shows floor(log10(pricescale)) decimals, zeros included ("1.00", "0.40" for tick 0.01), and
+ *   rounds in two steps, with mintick = minmove / pricescale: the double quotient `|x| / (1 / pricescale)` half away
+ *   from zero (140.355 / 0.01 = 14035.499999999998 gives "140.35", where `math.round_to_mintick` gives 140.36),
+ *   then `floor(units / minmove + 0.5)` ticks (tick 0.02: 0.005 gives "0.02", -0.01 gives "0.00"). With a
+ *   pricescale that is no power of 10 the tick value is then rounded half even to those decimals (1/32: 25.25 gives
+ *   "25.2", -0.02 gives "-0.0"). It throws without `mintick`
  * - na gives "NaN" ("NaN%" with `format.percent`); an infinity gives "NaN" too ("NaN%" for `format.percent`,
  *   "NaNT" for `format.volume`), except `format.mintick`, which gives "Infinity" / "-Infinity"
  *
@@ -66,7 +73,9 @@ export function length(str: simple_string): int {
  * str.tostring(12345.678, format.volume) // "12.346K"
  * ```
  */
-export function tostring(value: any, format?: simple_string, mintick?: float): string {
+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)) {
@@ -78,7 +87,8 @@ export function tostring(value: any, format?: simple_string, mintick?: float): s
     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':
@@ -94,11 +104,19 @@ export function tostring(value: any, format?: simple_string, mintick?: float): s
       if (mintick === undefined) {
         throw new Error('str.tostring(x, format.mintick) needs the tick size: pass it as str.tostring(x, format.mintick, syminfo.mintick)');
       }
-      // mask: one '#' per decimal of the tick ("#.##" for 0.01, "#" for 1)
-      const m = /^\d+(?:\.(\d+))?(?:e-(\d+))?$/.exec(String(mintick));
-      const decimals = m ? (m[1]?.length ?? 0) + Number(m[2] ?? 0) : 0;
-      const mask = decimals ? '#.' + '#'.repeat(decimals) : '#';
-      return formatNumber(round_to_mintick(value, mintick), mask, 'halfUpShortest');
+      const [minmove, scale] = tickScale(mintick, pricescale);
+      const decimals = Math.floor(Math.log10(scale) + 1e-9);
+      const mask = decimals > 0 ? '0.' + '0'.repeat(decimals) : '0';
+      if (!(minmove >= 1)) return formatNumber(value, mask, 'halfUpShortest');
+      // 1. the double quotient |x| / (1 / pricescale), half away from zero (not math.round_to_mintick's exact decimal)
+      const scaled = Math.abs(value) / (1 / scale);
+      let units = Math.trunc(scaled);
+      if (scaled - units >= 0.5) units++;
+      // 2. to the tick, a half going up (minmove 2: -0.01 gives "0.00", 0.01 gives "0.02")
+      const ticks = Math.floor((value < 0 ? -units : units) / minmove + 0.5);
+      // 3. the tick value at the scale's decimals; a negative one keeps its sign when it prints as zero ("-0.0")
+      const text = formatNumber((Math.abs(ticks) * minmove) / scale, mask, 'halfEvenExact');
+      return ticks < 0 ? '-' + text : text;
     }
     default:
       return formatNumber(value, format, 'halfUpShortest');

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;
@@ -230,3 +232,16 @@ function affixes(p: Pattern, negative: boolean, body: string): string {
   if (p.negPrefix === null) return '-' + p.prefix + body + p.suffix;
   return p.negPrefix + body + p.negSuffix!;
 }
+
+/**
+ * `[minmove, pricescale]` of a tick (PineScript `syminfo.mintick = syminfo.minmove / syminfo.pricescale`).
+ * Without `pricescale` it is 10^(decimals of the tick): 0.02 is 2 / 100, 0.25 is 25 / 100. A symbol priced in
+ * fractions needs its own (1/32 is 1 / 32).
+ */
+export function tickScale(mintick: number, pricescale?: number): [number, number] {
+  if (pricescale === undefined) {
+    const m = /^\d+(?:\.(\d+))?(?:e-(\d+))?$/.exec(String(mintick));
+    pricescale = Number(`1e${m ? (m[1]?.length ?? 0) + Number(m[2] ?? 0) : 0}`);
+  }
+  return [Math.round(mintick * pricescale), pricescale];
+}