oakscriptjs 0.9.4 → 0.9.6

package/src/callsite/index.ts

@@ -11,7 +11,9 @@
  *   loops, called only on the bars where the Pine call runs.
  * - {@link lowest} / {@link highest}: `ta.lowest` / `ta.highest` with a series length (a different length on each
  *   call), which PineScript computes with a state kept between calls.
- * - {@link linreg}: `ta.linreg` in a conditional block, whose window is kept by bar (not by call).
+ * - {@link lowestByBar} / {@link highestByBar} / {@link linreg}: `ta.lowest` / `ta.highest` / `ta.linreg` in a
+ *   conditional block, whose history is kept by bar (not by call).
+ * - {@link sum} / {@link sma}: `math.sum` / `ta.sma` in a `for` / `while` loop, called several times on one bar.
  *
  * Since PineScript v6, `and` / `or` are lazy: the right operand runs only when the left operand does not decide
  * the result. A ta.* call in the right operand of `a or b` runs on the bars where `a` is false, in `a and b` on the
@@ -42,6 +44,8 @@
 
 import type { Source } from '../types/index.js';
 import { linreg as linregSeries } from '../ta/index.js';
+import { RunningSum, isNa } from '../ta/running-sum.js';
+import { seededRandom } from '../math/index.js';
 
 /**
  * Runs `fn` on the bars where `called` is true only, like a ta.* call inside an `if` block.
@@ -67,24 +71,35 @@ export function whenCalled<T extends number | boolean>(
   return out;
 }
 
-/** A call site that keeps the two previous arguments (na before the first call). */
+/**
+ * A call site that keeps the arguments of the last call where both were not na (na before such a call), as
+ * ta.crossover / ta.crossunder / ta.cross.
+ */
 function twoSeriesSite(test: (a: number, b: number, prevA: number, prevB: number) => boolean) {
   let prevA = NaN;
   let prevB = NaN;
   return (a: number, b: number): boolean => {
     const result = test(a, b, prevA, prevB);
-    prevA = a;
-    prevB = b;
+    if (!Number.isNaN(a) && !Number.isNaN(b)) {
+      prevA = a;
+      prevB = b;
+    }
     return result;
   };
 }
 
-/** One `ta.crossover(a, b)` call site: false on its first call, as its history is na. */
+/**
+ * One `ta.crossover(a, b)` call site: compared with the last call where both arguments were not na; false before
+ * such a call.
+ */
 export function crossover(): (a: number, b: number) => boolean {
   return twoSeriesSite((a, b, pa, pb) => a > b && pa <= pb);
 }
 
-/** One `ta.crossunder(a, b)` call site: false on its first call, as its history is na. */
+/**
+ * One `ta.crossunder(a, b)` call site: compared with the last call where both arguments were not na; false before
+ * such a call.
+ */
 export function crossunder(): (a: number, b: number) => boolean {
   return twoSeriesSite((a, b, pa, pb) => a < b && pa >= pb);
 }
@@ -102,9 +117,20 @@ export function barssince(): (condition: boolean | number) => number {
   };
 }
 
-/** One `ta.cross(a, b)` call site: false on its first call, as its history is na. */
+/**
+ * One `ta.cross(a, b)` call site, rules of `ta.cross`: the site keeps the side of the last call where `a` was
+ * strictly above or strictly below `b` (none before such a call; equal values and na arguments do not change it),
+ * and is true when the arguments are strictly on the other side. False with an na argument.
+ */
 export function cross(): (a: number, b: number) => boolean {
-  return twoSeriesSite((a, b, pa, pb) => (a > b && pa <= pb) || (a < b && pa >= pb));
+  let side = 0; // -1: last strictly below, 1: last strictly above, 0: none yet
+  return (a, b) => {
+    if (Number.isNaN(a) || Number.isNaN(b)) return false;
+    const result = (side < 0 && a > b) || (side > 0 && a < b);
+    if (a < b) side = -1;
+    else if (a > b) side = 1;
+    return result;
+  };
 }
 
 /** One `ta.lowest` / `ta.highest` call site with a series length; rules in {@link lowest}. */
@@ -179,6 +205,71 @@ export function highest(): (value: number, length: number) => number {
   return extremeSite(false);
 }
 
+/** One `ta.lowest` / `ta.highest` call site whose history is kept by bar; rules in {@link lowestByBar}. */
+function extremeByBarSite(isLowest: boolean): (barIndex: number, value: number, length: number) => number {
+  const better = isLowest ? (a: number, b: number) => a < b : (a: number, b: number) => a > b;
+  let ring: number[] = [];
+  let extreme = NaN;
+  let extremeAt = -1;
+  return (barIndex, value, length) => {
+    const len = Math.floor(length);
+    if (ring.length !== len + 1) {
+      ring = new Array<number>(len + 1).fill(0);
+      extreme = NaN;
+    }
+    ring[barIndex % (len + 1)] = value;
+    if (Number.isNaN(extreme) || better(value, extreme)) {
+      extreme = value;
+      extremeAt = barIndex;
+    } else if (barIndex - extremeAt >= len) {
+      extreme = NaN;
+      for (let b = barIndex - len + 1; b <= barIndex; b++) {
+        const v = ring[b % (len + 1)]!;
+        if (!Number.isNaN(v) && (Number.isNaN(extreme) || better(v, extreme))) {
+          extreme = v;
+          extremeAt = b;
+        }
+      }
+    }
+    return barIndex < len - 1 ? NaN : extreme;
+  };
+}
+
+/**
+ * One `ta.lowest(source, length)` call site in a conditional block whose history is kept by bar (not by call), called
+ * with `(barIndex, value, length)` on the bars where the Pine call runs.
+ *
+ * PineScript rules (measured on a call in a ternary branch, length 6):
+ * - the values are kept in a ring of `length + 1` slots indexed by the bar index, filled with 0 at the start and
+ *   written only on the bars where the call runs: a bar before the first call counts as 0, and a bar without a call
+ *   holds the value of the call `length + 1` bars earlier (0 if there was none)
+ * - on a call, the value replaces the kept extreme when there is none or when it is strictly lower; only otherwise,
+ *   when the kept extreme is `length` bars old, the last `length` bars are read again from the ring (the oldest bar
+ *   wins a tie)
+ * - na before bar `length - 1` (by bar, not by call)
+ *
+ * {@link lowest} keeps the history by call instead; both rules were measured, on different scripts.
+ *
+ * @example
+ * ```typescript
+ * // Pine:  lo = cond ? ta.lowest(low, 6) : na
+ * const site = callsite.lowestByBar();
+ * const lo = lows.map((v, i) => (cond[i] ? site(i, v, 6) : NaN));
+ * ```
+ */
+export function lowestByBar(): (barIndex: number, value: number, length: number) => number {
+  return extremeByBarSite(true);
+}
+
+/**
+ * One `ta.highest(source, length)` call site in a conditional block whose history is kept by bar, called with
+ * `(barIndex, value, length)`. Same rules as {@link lowestByBar} (a value replaces the kept extreme when it is
+ * strictly higher).
+ */
+export function highestByBar(): (barIndex: number, value: number, length: number) => number {
+  return extremeByBarSite(false);
+}
+
 /**
  * One `ta.linreg(source, length, offset)` call site in a conditional block, called with
  * `(barIndex, value, length, offset)` on the bars where the Pine call runs.
@@ -209,3 +300,136 @@ export function linreg(): (barIndex: number, value: number, length: number, offs
   };
 }
 
+
+/**
+ * One `math.sum` call site in a loop; rules in {@link sum}. With `squares`, it also keeps the running sum of the
+ * squared values (for {@link stdev}). Returns `[sum, sumOfSquares]` (NaN when not kept).
+ */
+function loopSumSite(
+  name: string,
+  squares: boolean
+): (barIndex: number, value: number, length: number) => [number, number] {
+  const running = new RunningSum();
+  const runningSq = new RunningSum();
+  let lastBar = NaN;
+  let pending = false;
+  return (barIndex, value, length) => {
+    const len = Math.floor(length);
+    if (!(len >= 1)) throw new Error(`callsite.${name}: length must be at least 1 (got ${length})`);
+    if (barIndex !== lastBar) {
+      if (pending) {
+        running.commit();
+        if (squares) runningSq.commit();
+      }
+      pending = false;
+      lastBar = barIndex;
+    }
+    if (isNa(value)) {
+      pending = false;
+      return [running.stepNa(len), squares ? runningSq.stepNa(len) : NaN];
+    }
+    const x = value;
+    const out: [number, number] = [running.step(x, len), squares ? runningSq.step(x * x, len) : NaN];
+    pending = true;
+    return out;
+  };
+}
+
+/**
+ * One `math.sum(source, length)` call site inside a `for` / `while` loop, called with `(barIndex, value, length)` on
+ * each call.
+ *
+ * PineScript rules (measured on calls in loops, 1 to 3 calls per bar, and bars without a call):
+ * - the call site keeps one history value per bar: the value of its last call on that bar
+ * - every call on a bar starts from the state of the earlier bars, so it gives the sum of its value and the last
+ *   `length - 1` kept values; the last call of the bar is the one kept for the later bars
+ * - the length can change from one call to the next (also on the same bar): each call first moves the kept sum to
+ *   its own length as `math.sum` with a series length does (Kahan steps of the raw values)
+ * - a bar without a call is not in the history (as a call in an `if` block)
+ * - the sum is the same compensated running sum as `math.sum` (bit for bit)
+ *
+ * An na value is skipped as in `math.sum` (it returns the sum of the last `length` earlier values); when it is the
+ * last call of a bar, the bar is not in the history (not measured).
+ *
+ * @example
+ * ```typescript
+ * // Pine:  for i = 0 to 2
+ * //            s = math.sum(close * (1 + 0.01 * i), 7)
+ * const site = callsite.sum();
+ * for (let b = 0; b < closes.length; b++) {
+ *   for (let i = 0; i <= 2; i++) {
+ *     const s = site(b, closes[b]! * (1 + 0.01 * i), 7);
+ *   }
+ * }
+ * ```
+ */
+export function sum(): (barIndex: number, value: number, length: number) => number {
+  const site = loopSumSite('sum', false);
+  return (barIndex, value, length) => site(barIndex, value, length)[0];
+}
+
+/**
+ * One `ta.sma(source, length)` call site inside a `for` / `while` loop, called with `(barIndex, value, length)` on
+ * each call: {@link sum} divided by the length (same rules).
+ *
+ * @example
+ * ```typescript
+ * // Pine:  evaluate(ratio) => ta.sma(gann(ratio), n)   // called once per ratio in a while loop
+ * const site = callsite.sma();
+ * for (let b = 0; b < closes.length; b++) {
+ *   for (const ratio of ratios) {
+ *     const avg = site(b, gann(b, ratio), n);
+ *   }
+ * }
+ * ```
+ */
+export function sma(): (barIndex: number, value: number, length: number) => number {
+  const site = loopSumSite('sma', false);
+  return (barIndex, value, length) => site(barIndex, value, length)[0] / Math.floor(length);
+}
+
+/**
+ * One `ta.stdev(source, length, biased)` call site inside a `for` / `while` loop, called with
+ * `(barIndex, value, length, biased?)` on each call: the running sums of the values and of their squares follow the
+ * rules of {@link sum}; the result is computed from them as `ta.stdev` (bit for bit).
+ *
+ * @example
+ * ```typescript
+ * // Pine:  for len in lengths
+ * //            [mid, up, lo] = ta.bb(close, len, 2)
+ * const avgSite = callsite.sma();
+ * const devSite = callsite.stdev();
+ * for (let b = 0; b < closes.length; b++) {
+ *   for (const len of lengths) {
+ *     const mid = avgSite(b, closes[b]!, len);
+ *     const dev = devSite(b, closes[b]!, len);
+ *   }
+ * }
+ * ```
+ */
+export function stdev(): (barIndex: number, value: number, length: number, biased?: boolean) => number {
+  const site = loopSumSite('stdev', true);
+  return (barIndex, value, length, biased = true) => {
+    const len = Math.floor(length);
+    const [s, sq] = site(barIndex, value, length);
+    const mean = s / len;
+    const variance = biased ? sq / len - mean * mean : sq / (len - 1) - (mean * s) / (len - 1);
+    if (!biased && len <= 1) return NaN;
+    return Number.isNaN(variance) ? NaN : variance > 0 ? Math.sqrt(variance) : 0;
+  };
+}
+
+/**
+ * One `math.random(min, max, seed)` call site: PineScript keeps one generator per call site, so two call sites
+ * with the same seed give the same sequence. Called with `(min?, max?)` once per bar.
+ *
+ * @example
+ * ```typescript
+ * // Pine: a = math.random(0, 1, 42), b = math.random(0, 1, 42)   // a == b on every bar
+ * const a = callsite.random(42);
+ * const b = callsite.random(42);
+ * ```
+ */
+export function random(seed: number): (min?: number, max?: number) => number {
+  return seededRandom(seed);
+}

package/src/color/index.ts

@@ -107,7 +107,10 @@ export function from_hex(hex: string, transp?: simple_float): string {
  * - Replaces the transparency with the new value
  * - Useful for creating semi-transparent versions of existing colors
  * - PineScript clamps the transparency to 0..100 (`color.new(c, 140)` is fully transparent, `color.new(c, -5)` is
- *   opaque); an `na` transparency is fully transparent
+ *   opaque); an `na` transparency is fully transparent (measured: the colour is not na, its RGB is kept)
+ * - an `na` colour (null / undefined) gives black with the new transparency: `color.new(na, 30)` is
+ *   `rgba(0, 0, 0, 0.7)`, as PineScript does for an na colour variable (measured, #150). In PineScript, the constant
+ *   `color.new(color(na), 30)` is computed at compile time and stays na; a JS function cannot tell the two apart.
  *
  * @example
  * ```typescript
@@ -117,7 +120,8 @@ export function from_hex(hex: string, transp?: simple_float): string {
  * color.new_color(red, 100) // Returns: "rgba(255, 0, 0, 0)" - Fully transparent
  * ```
  */
-export function new_color(baseColor: color, transp: simple_float): string {
+export function new_color(baseColor: color | null | undefined, transp: simple_float): string {
+  if (baseColor === null || baseColor === undefined) return rgb(0, 0, 0, transp); // na colour: black
   // Parse the color and apply transparency
   const rgba = parseColor(baseColor);
   return rgb(rgba.r, rgba.g, rgba.b, transp);
@@ -185,6 +189,7 @@ export function b(clr: color): int {
  * - Converts alpha channel (0-1) to transparency (0-100)
  * - PineScript stores the alpha as a byte (0-255) and returns an integer transparency:
  *   `color.t(color.new(c, 33.3))` is 33
+ * - an `na` colour (null / undefined) is fully transparent: 100
  *
  * @example
  * ```typescript
@@ -193,7 +198,8 @@ export function b(clr: color): int {
  * color.t(color.rgb(255, 0, 0, 100)) // Returns: 100 (fully transparent)
  * ```
  */
-export function t(clr: color): float {
+export function t(clr: color | null | undefined): float {
+  if (clr === null || clr === undefined) return 100;
   return Math.round((1 - alphaByte(parseColor(clr).a) / 255) * 100);
 }
 
@@ -362,8 +368,12 @@ export function from_gradient(
   const c2 = rgba(top_color);
   const a = c1.a * (1 - k) + c2.a * k;
   if (a === 0) return transparent;
-  // operation order with the fewest differences to PineScript (channels as 0-1, alpha as a byte)
-  const mix = (x1: number, x2: number) => Math.floor((((x1 / 255) * c1.a) * (1 - k) + ((x2 / 255) * c2.a) * k) / (a / 255));
+  // PineScript order (bit for bit, #146): premultiplied channels ((alpha / 255) * channel) * weight, divided by the
+  // byte-alpha mix / 255, truncated. At an end (k = 0 / 1) this is floor(x * a / a): the end colour or one unit less.
+  const scale = a / 255;
+  const w1 = c1.a / 255;
+  const w2 = c2.a / 255;
+  const mix = (x1: number, x2: number) => Math.floor(((w1 * x1) * (1 - k) + (w2 * x2) * k) / scale);
   const [r, g, b] = [mix(c1.r, c2.r), mix(c1.g, c2.g), mix(c1.b, c2.b)];
   const alpha = Math.floor(a);
   return alpha === 255 ? `rgb(${r}, ${g}, ${b})` : `rgba(${r}, ${g}, ${b}, ${alpha / 255})`;

package/src/index.ts

@@ -164,7 +164,7 @@ export type { LightweightSeriesDefinitions } from './runtime/adapters/Lightweigh
 export { SimpleInputAdapter } from './runtime/adapters/SimpleInputAdapter.js';
 
 // Version
-export const VERSION = '0.9.4';
+export const VERSION = '0.9.6';
 
 /**
  * Library information

package/src/label/index.ts

@@ -85,7 +85,8 @@ export function new_label(...args: unknown[]): Label {
     y,
     xloc: xloc ?? 'bar_index',
     yloc: yloc ?? 'price',
-    text,
+    // PineScript: a label without text has the text "" (label.get_text gives "")
+    text: text ?? '',
     tooltip,
     color: labelColor,
     style,

package/src/linefill/index.ts

@@ -40,6 +40,8 @@ import type { Linefill, Line, color } from '../types/index.js';
  * ```
  */
 export function new_linefill(line1: Line, line2: Line, fillColor?: color): Linefill {
+  // PineScript: an na line gives an na linefill
+  if (line1 === null || line1 === undefined || line2 === null || line2 === undefined) return null as unknown as Linefill;
   return register('linefill', {
     line1,
     line2,