oakscriptjs 0.11.0 → 0.11.2

package/src/ta/limits.ts

@@ -37,11 +37,38 @@ export function windowError(name: string, length: number, bar?: number, max = MA
 /** Throws RE10004 when the (truncated) length of a window function is above the limit. */
 export function checkWindowLength(name: string, length: number, bar?: number, max = MAX_WINDOW_LENGTH): void {
   const len = Math.trunc(length);
+  if (len <= 0) throw new Error(lengthError(name, len, bar));
   if (len > max) throw new Error(windowError(name, len, bar, max));
 }
 
 /** Throws RE10004 for a function of {@link SUM_FUNCTIONS} ("ta.sma", ...) with a length above 5,000. */
 export function checkSumLength(name: string, length: number, bar?: number): void {
   const fn = SUM_FUNCTIONS[name];
-  if (fn !== undefined) checkWindowLength(fn, length, bar, MAX_SUM_LENGTH);
+  if (fn === undefined) return;
+  // RE10001 names 'bb' itself, RE10004 its inner 'sma'
+  checkPositiveLength(name === 'ta.bb' ? 'bb' : fn, length, bar);
+  checkWindowLength(fn, length, bar, MAX_SUM_LENGTH);
+}
+
+/**
+ * PineScript's runtime error RE10001 text for a length that is 0 or negative. `name` is the function, or a call path
+ * "atr->rma" (printed 'atr'->'rma'); the value prints as a float ("0.0", "-1.0").
+ */
+export function lengthError(name: string, value: number, bar?: number, arg = 'length'): string {
+  const fn = name.split('->').map((part) => `'${part}'`).join('->');
+  const text = Number.isInteger(value) ? value.toFixed(1) : String(value);
+  return (
+    (bar === undefined ? '' : `Error on bar ${bar}: `) +
+    `Invalid value of the '${arg}' argument (${text}) in the ${fn} function. It must be > 0.`
+  );
+}
+
+/**
+ * Throws RE10001 when the (truncated) length is 0 or negative, as PineScript does for every window function on the
+ * bar of the call (#175): `ta.sma(close, 0)` stops on bar 0, a series length that becomes 0 on the bar where it
+ * does. `ta.hma(src, 1)` stops in its inner `wma(src, 0)`. An na length is not checked here.
+ */
+export function checkPositiveLength(name: string, length: number, bar?: number, arg = 'length'): void {
+  const len = Math.trunc(length);
+  if (len <= 0) throw new Error(lengthError(name, len, bar, arg));
 }

package/src/ta/running-sum.ts

@@ -177,8 +177,8 @@ function seriesLengths(lengths: ArrayLike<number>, count: number, name: string):
   }
   return Array.from({ length: count }, (_, i) => {
     const len = Math.floor(lengths[i]!);
-    if (!(len >= 1)) throw new Error(`${name}: length must be at least 1 (bar ${i}: ${lengths[i]})`);
     checkSumLength(name, len, i);
+    if (!(len >= 1)) throw new Error(`${name}: length must be at least 1 (bar ${i}: ${lengths[i]})`);
     return len;
   });
 }

package/src/ta-series.ts

@@ -66,10 +66,11 @@ export function rma(source: Series, length: number): Series {
  * @param length - Period length
  * @returns Series with RSI values
  */
-export function rsi(source: Series, length: number): Series {
+export function rsi(source: Series, length: number | Series): Series {
   const bars = source.bars as Bar[];
   const sourceValues = source.toArray();
-  const result = taCore.rsi(sourceValues, length);
+  // a Series as second argument: PineScript v4 rsi(x, y) of two averages (#180)
+  const result = length instanceof Series ? taCore.rsi(sourceValues, length.toArray()) : taCore.rsi(sourceValues, length);
   return Series.fromArray(bars, result);
 }
 

package/src/table/index.ts

@@ -12,6 +12,9 @@
  * - `table.cell_set_*` changes one property of a cell (a cell that was not defined is created)
  * - a column or row outside the table is a runtime error
  * - a deleted table is `na`: its functions do nothing
+ * - one live table per position and pane: `table.new` or `table.set_position` at the position of a live table with
+ *   the same `force_overlay` deletes that table (#176, #182); a table with `force_overlay = true` and one without
+ *   keep each their own position, also in an overlay script
  *
  * @version 6
  */
@@ -24,8 +27,16 @@ type HAlign = 'left' | 'center' | 'right';
 type VAlign = 'top' | 'center' | 'bottom';
 type FontFamily = 'default' | 'monospace';
 
+/** Deletes the live tables other than `keep` at `position` with the same `force_overlay` (#176, #182). */
+function freePosition(position: TablePosition, force_overlay: boolean, keep?: Table): void {
+  for (const old of allDrawings('table')) {
+    if (old !== keep && old.position === position && (old.force_overlay ?? false) === force_overlay) remove('table', old);
+  }
+}
+
 /**
- * Creates a new table (PineScript `table.new`).
+ * Creates a new table (PineScript `table.new`). A live table at the same position with the same `force_overlay` is
+ * deleted, as PineScript keeps one table per position and pane (#176, #182).
  *
  * @example
  * ```typescript
@@ -44,6 +55,7 @@ export function new_table(
   border_width?: number,
   force_overlay?: boolean
 ): Table {
+  freePosition(position, force_overlay ?? false);
   return register('table', {
     position,
     columns,
@@ -193,8 +205,15 @@ function setTable<K extends keyof Table>(field: K) {
   };
 }
 
-/** Moves the table to another position (`position.*`). */
-export const set_position = setTable('position');
+/**
+ * Moves the table to another position (`position.*`). A live table at that position with the same `force_overlay` is
+ * deleted (#182).
+ */
+export function set_position(table_id: Table, position: TablePosition): void {
+  if (isDeleted(table_id)) return;
+  freePosition(position, table_id.force_overlay ?? false, table_id);
+  table_id.position = position;
+}
 /** Sets the background colour of the table. */
 export const set_bgcolor = setTable('bgcolor');
 /** Sets the colour of the outer frame. */

package/src/time/session.ts

@@ -14,11 +14,13 @@
  *   "0000-0000" and "24x7" are the whole day, every day
  * - a run that ends at 0000 ("2000-0000") ends at 24:00 of the day it starts and belongs to that day
  *   ("2000-0000:6" is Friday 20:00 to midnight)
+ * - "F" after the start moves it one day before the day the run ends on ("1700F-1900:2": Sunday 17:00 to Monday
+ *   19:00; "1900-1900:3456|1700F-1900:2" is the TVC:DXY symbol session) (#173)
  * - a string that is empty or does not start with a digit ("regular", "extended") is the symbol's own session
  * - a malformed string ("1100 -1400", "0930-16", ":8") is an error, as the PineScript runtime error
  */
 
-import { zoneOffset, zonedFields } from './timezone.js';
+import { zoneOffset, zonedFields, zonedToUnix } from './timezone.js';
 
 const MINUTES_PER_DAY = 1440;
 const WEEKDAYS = [2, 3, 4, 5, 6];
@@ -29,17 +31,27 @@ export interface SessionRange {
   start: number;
   end: number;
   days: Set<number>;
+  /** Days between the start and the day the run ends on, given by "F" after the start (absent otherwise) */
+  startDays?: number;
 }
 
 function invalid(session: string): SyntaxError {
   return new SyntaxError(`Invalid session "${session}": expected "HHMM-HHMM[,HHMM-HHMM...][:days][|...]"`);
 }
 
-function parseRanges(text: string, session: string): Array<[number, number]> {
+function parseRanges(text: string, session: string): Array<[number, number, number?]> {
   if (!text) return [];
   const entries = text.split(',');
   if (entries.length > 1 && entries[entries.length - 1] === '') entries.pop();
-  return entries.map((entry) => {
+  return entries.map((entry): [number, number, number?] => {
+    // "HHMMF-HHMM": the start is one day before the day the run ends on
+    const f = /^(\d{4})F-(\d{4})$/.exec(entry);
+    if (f) {
+      const minutes = (hhmm: string): number => Number(hhmm.slice(0, 2)) * 60 + Number(hhmm.slice(2, 4));
+      const [start, end] = [minutes(f[1]!), minutes(f[2]!)];
+      if (start >= MINUTES_PER_DAY || end >= MINUTES_PER_DAY) throw invalid(session);
+      return [start, end, 1];
+    }
     if (!/^\d{4}-\d{4}$/.test(entry)) throw invalid(session);
     let start = Number(entry.slice(0, 2)) * 60 + Number(entry.slice(2, 4));
     let end = Number(entry.slice(5, 7)) * 60 + Number(entry.slice(7, 9));
@@ -60,6 +72,9 @@ function parseDays(text: string, session: string): Set<number> {
 
 const parsed = new Map<string, SessionRange[] | null>();
 
+const range = (start: number, end: number, days: Set<number>, startDays?: number): SessionRange =>
+  startDays === undefined ? { start, end, days } : { start, end, days, startDays };
+
 /**
  * Runs of a PineScript session string, or null for the symbol's own session (empty or not starting with a digit).
  * @throws SyntaxError when the string is malformed (a PineScript runtime error)
@@ -74,7 +89,7 @@ export function parsePineSession(session: string): SessionRange[] | null {
   } else if (spec === '24x7') {
     out = [{ start: 0, end: 0, days: new Set(ALL_DAYS) }];
   } else if (!/[:,|]/.test(spec)) {
-    out = parseRanges(spec, session).map(([start, end]) => ({ start, end, days: new Set(ALL_DAYS) }));
+    out = parseRanges(spec, session).map(([start, end, startDays]) => range(start, end, new Set(ALL_DAYS), startDays));
   } else {
     const sections = spec.split('|');
     if (sections.length > 1 && sections[sections.length - 1] === '') sections.pop();
@@ -99,7 +114,7 @@ export function parsePineSession(session: string): SessionRange[] | null {
     items.forEach((it, i) => {
       if (it.days === null) for (const d of WEEKDAYS) if (!claimed.has(d)) own[i]!.add(d);
     });
-    out = items.flatMap((it, i) => (own[i]!.size ? it.ranges.map(([start, end]) => ({ start, end, days: own[i]! })) : []));
+    out = items.flatMap((it, i) => (own[i]!.size ? it.ranges.map(([start, end, startDays]) => range(start, end, own[i]!, startDays)) : []));
   }
   parsed.set(session, out);
   return out;
@@ -147,29 +162,56 @@ function clockChangeNear(time: number, timezone: string): { at: number; before:
  * `time(timeframe, session)` in a script with the chart session
  */
 export function inSession(time: number, session: string, timezone: string, barMs?: number): boolean {
-  if (Number.isNaN(time)) return false;
+  return sessionRun(time, session, timezone, barMs) !== null;
+}
+
+/**
+ * The run of `session` that contains `time`, as [start, end) UNIX times (ms), or null outside the session; rules in
+ * {@link inSession}. PineScript aligns the intraday periods of `time(tf, session)` on the start of this run (#173).
+ */
+export function sessionRun(time: number, session: string, timezone: string, barMs?: number): [number, number] | null {
+  if (Number.isNaN(time)) return null;
   const ranges = parsePineSession(session);
   if (ranges === null) throw new Error(`Session "${session}" is the symbol session: it needs the chart session (time(timeframe, session) in a script)`);
   const change = clockChangeNear(time, timezone);
   const f = zonedFields(time, timezone);
   const minute = f.hour * 60 + f.minute;
   const nextDay = (f.dayOfWeek % 7) + 1;
-  for (const { start, end: rawEnd, days } of ranges) {
+  for (const { start, end: rawEnd, days, startDays } of ranges) {
+    if (startDays !== undefined) {
+      // "F": from `start` of `startDays` days before the end day to `end` of the end day, wall times read in the zone
+      for (let k = 0; k <= startDays + 1; k++) {
+        const endDay = Date.UTC(f.year, f.month - 1, f.day + k);
+        if (!days.has(new Date(endDay).getUTCDay() + 1)) continue;
+        const d = new Date(endDay);
+        const at = (dayShift: number, minutes: number): number =>
+          zonedToUnix(timezone, d.getUTCFullYear(), d.getUTCMonth() + 1, d.getUTCDate() - dayShift, Math.floor(minutes / 60), minutes % 60);
+        const from = at(startDays, start);
+        const to = at(0, rawEnd);
+        if (time >= from && time < to) return [from, to];
+      }
+      continue;
+    }
     if (start === rawEnd) {
       // 24 hours: the run belongs to the day it ends ("0000-0000": the day itself)
-      if (days.has(start === 0 || minute < start ? f.dayOfWeek : nextDay)) return true;
+      if (days.has(start === 0 || minute < start ? f.dayOfWeek : nextDay)) {
+        const from = time - ((minute - start + MINUTES_PER_DAY) % MINUTES_PER_DAY) * MS_PER_MINUTE - f.second * 1000 - (time % 1000);
+        return [from, from + MS_PER_DAY];
+      }
       continue;
     }
     // a run that ends at 0000 ends at 24:00 of the day it starts
     const end = rawEnd === 0 ? MINUTES_PER_DAY : rawEnd;
     const overnight = start > end;
     if (!change) {
+      // the wall-clock minute of the bar: the run is `start` to `end` minutes of the same offset
+      const midnight = time - minute * MS_PER_MINUTE - f.second * 1000 - (time % 1000);
       if (!overnight) {
-        if (minute >= start && minute < end && days.has(f.dayOfWeek)) return true;
+        if (minute >= start && minute < end && days.has(f.dayOfWeek)) return [midnight + start * MS_PER_MINUTE, midnight + end * MS_PER_MINUTE];
       } else {
         // the part from `start` belongs to the next day
-        if (minute >= start && days.has(nextDay)) return true;
-        if (minute < end && days.has(f.dayOfWeek)) return true;
+        if (minute >= start && days.has(nextDay)) return [midnight + start * MS_PER_MINUTE, midnight + (end + MINUTES_PER_DAY) * MS_PER_MINUTE];
+        if (minute < end && days.has(f.dayOfWeek)) return [midnight + (start - MINUTES_PER_DAY) * MS_PER_MINUTE, midnight + end * MS_PER_MINUTE];
       }
       continue;
     }
@@ -182,14 +224,14 @@ export function inSession(time: number, session: string, timezone: string, barMs
       const from = day * MS_PER_DAY + (overnight ? start - MINUTES_PER_DAY : start) * MS_PER_MINUTE;
       const to = day * MS_PER_DAY + end * MS_PER_MINUTE;
       if (to === changeWall) {
-        if (time >= from - change.after && time < to - change.after) return true;
+        if (time >= from - change.after && time < to - change.after) return [from - change.after, to - change.after];
         continue;
       }
-      if (time >= place(from) && time < place(to)) return true;
+      if (time >= place(from) && time < place(to)) return [place(from), place(to)];
       // clocks going back: the second pass of the repeated hour
       const repeated = change.at + change.after;
       if (change.after < change.before && to < changeWall && to > repeated) {
-        if (time >= Math.max(from, repeated) - change.after && time < to - change.after) return true;
+        if (time >= Math.max(from, repeated) - change.after && time < to - change.after) return [place(from), to - change.after];
       }
     }
     // clocks going back, the day before: a run with an end on the wall time of the change is also true one change
@@ -201,9 +243,9 @@ export function inSession(time: number, session: string, timezone: string, barMs
         const from = day * MS_PER_DAY + (overnight ? start - MINUTES_PER_DAY : start) * MS_PER_MINUTE - change.before;
         const to = day * MS_PER_DAY + end * MS_PER_MINUTE - change.before;
         const shift = change.before - change.after;
-        if (time >= from + shift && time < to + shift && time >= to + barMs) return true;
+        if (time >= from + shift && time < to + shift && time >= to + barMs) return [from + shift, to + shift];
       }
     }
   }
-  return false;
+  return null;
 }

package/src/time/timezone.ts

@@ -177,6 +177,11 @@ export function civilToUnix(year: number, month: number, day: number, hour = 0,
   return days * MS_PER_DAY + Date.UTC(1970, 0, 1, hour, minute, second);
 }
 
+/**
+ * UNIX time (ms) of a wall-clock date in `timezone`. A wall time skipped by a clock change is read with the offset
+ * before the change (02:30 on a 02:00 -> 03:00 night is 03:30 after it); a wall time that occurs twice gives the
+ * later instant, or the earlier one with `earlier`.
+ */
 export function zonedToUnix(
   timezone: string,
   year: number,
@@ -184,7 +189,8 @@ export function zonedToUnix(
   day: number,
   hour: number = 0,
   minute: number = 0,
-  second: number = 0
+  second: number = 0,
+  earlier: boolean = false
 ): number {
   const zone = resolveZone(timezone);
   const local = civilToUnix(year, month, day, hour, minute, second);
@@ -195,6 +201,7 @@ export function zonedToUnix(
   const before = offsetAt(zone, local - MS_PER_DAY);
   const after = offsetAt(zone, local + MS_PER_DAY);
   const candidates = [local - before, local - after].filter((t) => local - offsetAt(zone, t) === t);
-  if (candidates.length) return Math.max(...candidates);
+  // a wall time that occurs twice: the later instant, or the earlier one with `earlier`
+  if (candidates.length) return earlier ? Math.min(...candidates) : Math.max(...candidates);
   return local - before;
 }

package/src/types/metadata.ts

@@ -86,7 +86,7 @@ export interface FillOptions {
 /**
  * Input parameter type
  */
-export type InputType = 'int' | 'float' | 'bool' | 'string' | 'source' | 'color' | 'timeframe' | 'session' | 'time';
+export type InputType = 'int' | 'float' | 'bool' | 'string' | 'source' | 'color' | 'timeframe' | 'session' | 'time' | 'symbol';
 
 /**
  * Input parameter metadata