oakscriptjs 0.9.5 → 0.9.6

package/src/callsite/index.ts

@@ -13,6 +13,7 @@
  *   call), which PineScript computes with a state kept between calls.
  * - {@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
@@ -43,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.
@@ -115,11 +118,19 @@ export function barssince(): (condition: boolean | number) => number {
 }
 
 /**
- * One `ta.cross(a, b)` call site: compared with the last call where both arguments were not na; false before such
- * a call.
+ * 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}. */
@@ -289,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.5';
+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,