oakscriptjs 0.10.1 → 0.11.0

package/src/time/session.ts

@@ -12,11 +12,13 @@
  * - a trailing ",", ":" or "|" ends its list ("1100-1400," is "1100-1400" Monday to Friday)
  * - an end before the start is an overnight run that belongs to the day it ends; equal ends are 24 hours;
  *   "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)
  * - 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 { zonedFields } from './timezone.js';
+import { zoneOffset, zonedFields } from './timezone.js';
 
 const MINUTES_PER_DAY = 1440;
 const WEEKDAYS = [2, 3, 4, 5, 6];
@@ -103,26 +105,104 @@ export function parsePineSession(session: string): SessionRange[] | null {
   return out;
 }
 
+const MS_PER_MINUTE = 60_000;
+const MS_PER_HOUR = 3_600_000;
+const MS_PER_DAY = 86_400_000;
+/** A clock change is looked for this far on each side of the tested time. */
+const CHANGE_WINDOW = 36 * MS_PER_HOUR;
+
+/** The clock change of `timezone` within 36 hours of `time`: its UNIX time and the offsets (ms) around it. */
+function clockChangeNear(time: number, timezone: string): { at: number; before: number; after: number } | null {
+  let lo = time - CHANGE_WINDOW;
+  let hi = time + CHANGE_WINDOW;
+  const before = zoneOffset(lo, timezone);
+  const after = zoneOffset(hi, timezone);
+  if (before === after) return null;
+  while (hi - lo > MS_PER_MINUTE) {
+    const mid = Math.floor((lo + hi) / 2 / MS_PER_MINUTE) * MS_PER_MINUTE;
+    if (zoneOffset(mid, timezone) === before) lo = mid;
+    else hi = mid;
+  }
+  return { at: hi, before, after };
+}
+
 /**
  * True when `time` falls inside `session`, with the session hours read in `timezone`.
  * A run includes its start minute and excludes its end minute.
+ *
+ * On the days around a clock change PineScript does not read the wall clock of each bar; it places each run of
+ * each local day (measured on 15- and 5-minute bars, clocks going forward and back, four time zones):
+ * - a wall time of the day is placed with the offset before the change when it is before the wall time of the
+ *   change (02:00 for 02:00 -> 03:00, 03:00 for 03:00 -> 02:00), with the offset after it otherwise. Forward
+ *   change: "0100-0300" lasts one hour and "0130-0230" is empty; back change: "0230-0330" lasts two hours
+ * - a run that ends exactly on the wall time of the change is placed with the offset after the change at both ends
+ *   (forward change: "0100-0200" is one hour earlier than the wall clock says)
+ * - clocks going back: a run that ends inside the repeated hour also covers its second pass
+ * - clocks going back, the day BEFORE the change: a run with a start or an end on the wall time of the change is
+ *   also true one hour (the amount of the change) later, from one bar after its usual end. This needs the bar
+ *   duration `barMs`; without it the rule is not applied
+ *
+ * @param barMs - Duration of the bars in ms (the chart timeframe); only used by the last rule
  * @throws Error for the symbol's own session ("regular", "extended", ""), which this function does not know: use
  * `time(timeframe, session)` in a script with the chart session
  */
-export function inSession(time: number, session: string, timezone: string): boolean {
+export function inSession(time: number, session: string, timezone: string, barMs?: number): boolean {
   if (Number.isNaN(time)) return false;
   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, days } of ranges) {
-    if (start < end || (start === 0 && end === 0)) {
-      if (minute >= start && (minute < end || end === 0) && days.has(f.dayOfWeek)) return true;
-    } else {
-      // Overnight (24 hours when start === end): 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;
+  for (const { start, end: rawEnd, days } of ranges) {
+    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;
+      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) {
+      if (!overnight) {
+        if (minute >= start && minute < end && days.has(f.dayOfWeek)) return true;
+      } 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;
+      }
+      continue;
+    }
+    // local days as naive instants (wall clock read as UTC)
+    const changeWall = change.at + change.before;
+    const place = (naive: number): number => (naive < changeWall ? naive - change.before : naive - change.after);
+    const today = Math.floor((time + change.before) / MS_PER_DAY);
+    for (let day = today - 1; day <= today + 1; day++) {
+      if (!days.has(((day + 4) % 7) + 1)) continue; // 01/01/1970 is a Thursday (5)
+      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;
+        continue;
+      }
+      if (time >= place(from) && time < place(to)) return true;
+      // 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;
+      }
+    }
+    // clocks going back, the day before: a run with an end on the wall time of the change is also true one change
+    // later, from one bar after its usual end
+    if (barMs !== undefined && change.after < change.before) {
+      const day = Math.floor(changeWall / MS_PER_DAY) - 1;
+      const wallMinute = (changeWall - (day + 1) * MS_PER_DAY) / MS_PER_MINUTE;
+      if ((start === wallMinute || end === wallMinute) && days.has(((day + 4) % 7) + 1)) {
+        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;
+      }
     }
   }
   return false;

package/src/types/metadata.ts

@@ -431,17 +431,20 @@ export interface LabelData {
   /** Price; not used with yloc 'abovebar' / 'belowbar' */
   price: number;
   text: string;
-  /** Background, border and arrow colour */
+  /** Background, border and arrow colour. Omitted: #2962FF (color.blue; #2196F3 in a v4 script) */
   color?: string;
+  /** Omitted: #FFFFFF in a v6 script, #363A45 in v4 and v5 (the result does not carry the version) */
   textColor?: string;
-  /** 'none': text only, no background (PineScript label.style_none) */
+  /** 'none': text only, no background (PineScript label.style_none). Omitted: 'label_down' */
   style?: LabelStyle;
+  /** Omitted: 'normal' */
   size?: PineSize | number;
   /**
    * PineScript yloc: 'price' (default) places the label at `price`; 'abovebar' / 'belowbar' place it above the bar
    * high / below the bar low and ignore `price` (the renderer reads the bar at `time`).
    */
   yloc?: 'price' | 'abovebar' | 'belowbar';
+  /** Omitted: 'center' */
   textAlign?: 'left' | 'center' | 'right';
   tooltip?: string;
   fontFamily?: 'default' | 'monospace';
@@ -459,8 +462,11 @@ export interface LineDrawingData {
   price1: number;
   time2: number;
   price2: number;
+  /** Omitted: #2962FF (color.blue; #2196F3 in a v4 script) */
   color?: string;
+  /** Omitted: 1. A width of 0 is kept (PineScript `width = 0`) */
   width?: number;
+  /** Omitted: 'solid' */
   style?: 'solid' | 'dashed' | 'dotted' | 'arrow_left' | 'arrow_right' | 'arrow_both';
   extend?: 'none' | 'left' | 'right' | 'both';
   /** PineScript force_overlay = true: the line of a non-overlay indicator is drawn on the price pane */
@@ -475,14 +481,22 @@ export interface BoxData {
   price1: number;
   time2: number;
   price2: number;
+  /** Omitted: #2962FF (color.blue; #2196F3 in a v4 script) */
   bgColor?: string;
+  /** Omitted: #2962FF (color.blue; #2196F3 in a v4 script) */
   borderColor?: string;
+  /** Omitted: 1. A width of 0 is no border (PineScript `border_width = 0`) */
   borderWidth?: number;
+  /** Omitted: 'solid' */
   borderStyle?: 'solid' | 'dashed' | 'dotted';
   text?: string;
+  /** Omitted: #FFFFFF in a v6 script, #363A45 in v5 (the result does not carry the version) */
   textColor?: string;
+  /** Omitted: 'auto' */
   textSize?: PineSize | number;
+  /** Omitted: 'center' */
   textHAlign?: 'left' | 'center' | 'right';
+  /** Omitted: 'center' */
   textVAlign?: 'top' | 'center' | 'bottom';
   textWrap?: 'none' | 'auto';
   fontFamily?: 'default' | 'monospace';
@@ -512,10 +526,12 @@ export interface PolylineData {
   curved?: boolean;
   /** The last point is connected to the first */
   closed?: boolean;
+  /** Omitted: #2962FF (color.blue) */
   lineColor?: string;
-  /** Fill of the area inside the polyline */
+  /** Fill of the area inside the polyline. Omitted: no fill */
   fillColor?: string;
   lineStyle?: 'solid' | 'dotted' | 'dashed' | 'arrow_left' | 'arrow_right' | 'arrow_both';
+  /** Omitted: 1 */
   lineWidth?: number;
   /** PineScript force_overlay = true: the polyline of a non-overlay indicator is drawn on the price pane */
   forceOverlay?: boolean;
@@ -540,8 +556,11 @@ export interface TableCellData {
   row: number;
   column: number;
   text: string;
+  /** Omitted: no background */
   bgColor?: string;
+  /** Omitted: #363A45 (in v4, v5 and v6 scripts) */
   textColor?: string;
+  /** Omitted: 'auto' */
   textSize?: PineSize | number;
   /** Width in % of the chart width; 0 fits the text */
   width?: number;
@@ -575,10 +594,15 @@ export interface TableData {
   rows: number;
   cells: TableCellData[];
   merges?: TableMergeData[];
+  /** Omitted: no background */
   bgColor?: string;
+  /** Omitted: no frame */
   frameColor?: string;
+  /** Omitted: 0 */
   frameWidth?: number;
+  /** Omitted: no cell borders */
   borderColor?: string;
+  /** Omitted: 0 */
   borderWidth?: number;
   /** PineScript force_overlay = true: the table of a non-overlay indicator is drawn on the price pane */
   forceOverlay?: boolean;