oakscriptjs 0.9.4 → 0.9.6

package/dist/esm/array/index.js

@@ -18,17 +18,47 @@ export function new_array(size = 0, initial_value) {
 export function size(id) {
     return id.length;
 }
+/** True for a PineScript `na` element: NaN, null or undefined. */
+function isNa(v) {
+    return v === undefined || v === null || (typeof v === 'number' && Number.isNaN(v));
+}
+/** The `na` of the array's element type: NaN for a numeric (or empty) array, undefined otherwise. */
+function naOf(id) {
+    return (id.length === 0 || typeof id[0] === 'number' ? NaN : undefined);
+}
 /**
- * Returns the element at the specified index
+ * Position addressed by a PineScript index: truncated, a negative index counts from the end. An index outside
+ * `-size .. size - 1 + extra` is a runtime error.
+ */
+function position(name, id, index, extra = 0) {
+    const i = Math.trunc(index);
+    const n = id.length;
+    if (i < -n || i >= n + extra) {
+        throw new Error(`array.${name}: index ${i} is out of bounds, array size is ${n}`);
+    }
+    return i < 0 ? i + n : i;
+}
+/**
+ * Returns the element at the specified index.
+ *
+ * PineScript rules: a negative index counts from the end (`get(a, -1)` is the last element); an index outside
+ * `-size .. size - 1` is a runtime error (throws); an `na` index gives `na`.
  */
 export function get(id, index) {
-    return id[index];
+    if (Number.isNaN(index))
+        return naOf(id);
+    return id[position('get', id, index)];
 }
 /**
- * Sets the value of the element at the specified index
+ * Sets the value of the element at the specified index.
+ *
+ * PineScript rules: a negative index counts from the end; an index outside `-size .. size - 1` is a runtime error
+ * (throws); an `na` index does nothing.
  */
 export function set(id, index, value) {
-    id[index] = value;
+    if (Number.isNaN(index))
+        return;
+    id[position('set', id, index)] = value;
 }
 /**
  * Appends a value to the end of the array
@@ -61,34 +91,72 @@ export function clear(id) {
     id.length = 0;
 }
 /**
- * Inserts a value at the specified index
+ * Inserts a value at the specified index.
+ *
+ * PineScript rules: a negative index counts from the end and `size` appends, so `-size .. size` is valid; any other
+ * index is a runtime error (throws); an `na` index appends.
  */
 export function insert(id, index, value) {
-    id.splice(index, 0, value);
+    if (Number.isNaN(index)) {
+        id.push(value);
+        return;
+    }
+    id.splice(position('insert', id, index, 1), 0, value);
 }
 /**
- * Removes the element at the specified index
+ * Removes the element at the specified index and returns it.
+ *
+ * PineScript rules: a negative index counts from the end; an index outside `-size .. size - 1` is a runtime error
+ * (throws); an `na` index removes nothing and gives `na`.
  */
 export function remove(id, index) {
-    return id.splice(index, 1)[0];
+    if (Number.isNaN(index))
+        return naOf(id);
+    return id.splice(position('remove', id, index), 1)[0];
+}
+/** PineScript `==` of two elements: numbers are equal when |a - b| <= 1e-10; `na` never equals anything. */
+function pineEqual(a, b) {
+    if (isNa(a) || isNa(b))
+        return false;
+    if (a === b)
+        return true;
+    if (typeof a === 'number' && typeof b === 'number') {
+        const d = a - b;
+        return -1e-10 <= d && d <= 1e-10;
+    }
+    return false;
 }
 /**
- * Returns true if the array contains the value
+ * Returns true if the array contains the value.
+ *
+ * PineScript rules: numbers are compared with a 1e-10 tolerance (|a - b| <= 1e-10); `na` is never found.
  */
 export function includes(id, value) {
-    return id.includes(value);
+    return indexof(id, value) >= 0;
 }
 /**
- * Returns the index of the first occurrence of the value
+ * Returns the index of the first occurrence of the value, -1 when not found.
+ *
+ * PineScript rules: numbers are compared with a 1e-10 tolerance (|a - b| <= 1e-10); `na` is never found.
  */
 export function indexof(id, value) {
-    return id.indexOf(value);
+    for (let i = 0; i < id.length; i++) {
+        if (pineEqual(id[i], value))
+            return i;
+    }
+    return -1;
 }
 /**
- * Returns the index of the last occurrence of the value
+ * Returns the index of the last occurrence of the value, -1 when not found.
+ *
+ * PineScript rules: numbers are compared with a 1e-10 tolerance (|a - b| <= 1e-10); `na` is never found.
  */
 export function lastindexof(id, value) {
-    return id.lastIndexOf(value);
+    for (let i = id.length - 1; i >= 0; i--) {
+        if (pineEqual(id[i], value))
+            return i;
+    }
+    return -1;
 }
 /**
  * Returns a shallow copy of the array
@@ -97,10 +165,12 @@ export function copy(id) {
     return [...id];
 }
 /**
- * Concatenates two arrays
+ * Appends the elements of `id2` to `id1` and returns `id1` (PineScript `array.concat` changes `id1`).
  */
 export function concat(id1, id2) {
-    return [...id1, ...id2];
+    for (const v of Array.from(id2))
+        id1.push(v);
+    return id1;
 }
 /**
  * Joins all elements into a string
@@ -115,29 +185,139 @@ export function reverse(id) {
     id.reverse();
 }
 /**
- * Returns a slice of the array
+ * Returns the elements from `index_from` (included) to `index_to` (excluded, default: the size) as a live view of
+ * the array (PineScript `array.slice`).
+ *
+ * PineScript rules:
+ * - the slice shares the elements of the original array: a change of an element of the slice changes the original
+ *   array, and adding / removing elements of the slice adds / removes them in the original array, inside the slice
+ *   bounds (a push to the slice inserts at the end of the slice)
+ * - `index_from` must address an element (`0 .. size - 1`) and `index_to` may be `size`; other bounds, or
+ *   `index_from > index_to`, are a runtime error (throws); an `na` bound means the start / the end of the array
  */
 export function slice(id, index_from, index_to) {
-    return id.slice(index_from, index_to);
+    const n = id.length;
+    const start = Number.isNaN(index_from) ? 0 : Math.trunc(index_from);
+    const stop = index_to === undefined || Number.isNaN(index_to) ? n : Math.trunc(index_to);
+    if (start < 0 || start >= n)
+        throw new Error(`array.slice: index ${start} is out of bounds, array size is ${n}`);
+    if (stop < 0 || stop > n)
+        throw new Error(`array.slice: index ${stop} is out of bounds, array size is ${n}`);
+    if (start > stop)
+        throw new Error(`array.slice: index_from ${start} is greater than index_to ${stop}`);
+    return sliceView(id, start, stop - start);
+}
+/** Index of a property key that is an array index, -1 otherwise. */
+function indexKey(p) {
+    if (typeof p !== 'string')
+        return -1;
+    const i = Number(p);
+    return Number.isInteger(i) && i >= 0 && String(i) === p ? i : -1;
 }
 /**
- * Sorts array elements (numeric)
+ * Live view of `size` elements of `parent` from `start`: an array (a Proxy) whose element reads and writes go to
+ * `parent`, and whose size changes insert / remove elements in `parent` at the end of the view.
  */
-export function sort(id, order = 'asc') {
-    id.sort((a, b) => {
-        if (order === 'asc') {
-            return a - b;
-        }
-        else {
-            return b - a;
-        }
+function sliceView(parent, start, size) {
+    const resize = (target) => {
+        if (target > size)
+            parent.splice(start + size, 0, ...Array(target - size).fill(undefined));
+        else if (target < size)
+            parent.splice(start + target, size - target);
+        size = target;
+    };
+    return new Proxy([], {
+        get(target, p, receiver) {
+            const i = indexKey(p);
+            if (i >= 0)
+                return i < size ? parent[start + i] : undefined;
+            if (p === 'length')
+                return size;
+            return Reflect.get(target, p, receiver);
+        },
+        set(target, p, value, receiver) {
+            const i = indexKey(p);
+            if (i >= 0) {
+                if (i >= size)
+                    resize(i + 1);
+                parent[start + i] = value;
+                return true;
+            }
+            if (p === 'length') {
+                resize(Number(value));
+                return true;
+            }
+            return Reflect.set(target, p, value, receiver);
+        },
+        has(target, p) {
+            const i = indexKey(p);
+            return i >= 0 ? i < size : Reflect.has(target, p);
+        },
+        // Array methods delete the slots past the new end before they set the length, which does the removal.
+        deleteProperty(target, p) {
+            return indexKey(p) >= 0 ? true : Reflect.deleteProperty(target, p);
+        },
+        ownKeys(target) {
+            return [...Array.from({ length: size }, (_, i) => String(i)), ...Reflect.ownKeys(target)];
+        },
+        getOwnPropertyDescriptor(target, p) {
+            const i = indexKey(p);
+            if (i >= 0) {
+                return i < size ? { value: parent[start + i], writable: true, enumerable: true, configurable: true } : undefined;
+            }
+            if (p === 'length')
+                return { value: size, writable: true, enumerable: false, configurable: false };
+            return Reflect.getOwnPropertyDescriptor(target, p);
+        },
     });
 }
 /**
- * Returns the sum of all elements (numeric arrays only)
+ * Positions of the elements in PineScript sorted order: ascending values, `na` after the numbers (before the
+ * strings of a string array), stable; descending is the ascending result reversed.
+ */
+function sortedPositions(id, order) {
+    const values = [];
+    const nas = [];
+    for (let i = 0; i < id.length; i++)
+        (isNa(id[i]) ? nas : values).push(i);
+    values.sort((a, b) => {
+        const x = id[a];
+        const y = id[b];
+        return x < y ? -1 : x > y ? 1 : 0;
+    });
+    const naFirst = values.length > 0 && typeof id[values[0]] === 'string';
+    const positions = naFirst ? [...nas, ...values] : [...values, ...nas];
+    if (order === 'desc' || order === 'descending')
+        positions.reverse();
+    return positions;
+}
+/**
+ * Sorts the array in place.
+ *
+ * PineScript rules: `na` goes after the numbers in ascending order and before them in descending order (the
+ * ascending result reversed); in a string array `na` goes first in ascending order.
+ */
+export function sort(id, order = 'asc') {
+    const sorted = sortedPositions(id, order).map((p) => id[p]);
+    for (let i = 0; i < sorted.length; i++)
+        id[i] = sorted[i];
+}
+/**
+ * Sum of the non-na elements (PineScript `array.sum(id)`), added from left to right; an array without values gives NaN.
+ * As PineScript, the running sum is set to 0 after a step when its absolute value is <= 1e-10.
  */
 export function sum(id) {
-    return id.reduce((acc, val) => acc + val, 0);
+    let total = 0;
+    let count = 0;
+    for (const v of id) {
+        if (Number.isNaN(v))
+            continue;
+        count++;
+        total += v;
+        if (Math.abs(total) <= 1e-10)
+            total = 0;
+    }
+    return count ? total : NaN;
 }
 /**
  * Average of the non-na elements (PineScript `array.avg(id)`); an array without values gives NaN.
@@ -146,72 +326,115 @@ export function avg(id) {
     const values = id.filter((v) => !Number.isNaN(v));
     return values.length ? values.reduce((a, b) => a + b, 0) / values.length : NaN;
 }
+/** The `nth` value of the non-na elements sorted with `compare` (array.min / array.max). */
+function nthValue(name, id, nth, compare) {
+    const rank = Number.isNaN(nth) ? 0 : Math.trunc(nth);
+    const values = id.filter((v) => !Number.isNaN(v));
+    if (!values.length)
+        return NaN;
+    if (rank < 0 || rank >= id.length) {
+        throw new Error(`array.${name}: nth ${rank} is out of bounds, array size is ${id.length}`);
+    }
+    values.sort(compare);
+    return values[Math.min(rank, values.length - 1)];
+}
 /**
  * The `nth` smallest value (0 = the smallest) of the non-na elements (PineScript `array.min(id, nth)`).
- * An `nth` past the end gives the greatest value; an array without values gives NaN.
+ *
+ * PineScript rules: an `nth` past the non-na values but inside the array size gives the greatest value; an `nth`
+ * outside `0 .. size - 1` is a runtime error (throws); an `na` nth counts as 0; an array without values gives NaN.
  */
 export function min(id, nth = 0) {
-    const values = id.filter((v) => !Number.isNaN(v)).sort((a, b) => a - b);
-    return values.length ? values[Math.min(nth, values.length - 1)] : NaN;
+    return nthValue('min', id, nth, (a, b) => a - b);
 }
 /**
  * The `nth` greatest value (0 = the greatest) of the non-na elements (PineScript `array.max(id, nth)`).
- * An `nth` past the end gives the smallest value; an array without values gives NaN.
+ *
+ * PineScript rules: an `nth` past the non-na values but inside the array size gives the smallest value; an `nth`
+ * outside `0 .. size - 1` is a runtime error (throws); an `na` nth counts as 0; an array without values gives NaN.
  */
 export function max(id, nth = 0) {
-    const values = id.filter((v) => !Number.isNaN(v)).sort((a, b) => b - a);
-    return values.length ? values[Math.min(nth, values.length - 1)] : NaN;
+    return nthValue('max', id, nth, (a, b) => b - a);
 }
 /**
- * Returns the median value (numeric arrays only)
+ * Median of the non-na elements (PineScript `array.median(id)`): the middle value, or the mean of the two middle
+ * values for an even count; an array without values gives NaN.
  */
 export function median(id) {
-    const sorted = [...id].sort((a, b) => a - b);
+    const sorted = id.filter((v) => !Number.isNaN(v)).sort((a, b) => a - b);
+    if (!sorted.length)
+        return NaN;
     const mid = Math.floor(sorted.length / 2);
     return sorted.length % 2 === 0 ? (sorted[mid - 1] + sorted[mid]) / 2 : sorted[mid];
 }
 /**
- * Returns the mode (most frequent value)
+ * Most frequent non-na element (PineScript `array.mode(id)`), compared exactly.
+ *
+ * PineScript rules: with several values of the same frequency, the smallest one; an array without values gives NaN.
  */
 export function mode(id) {
     const frequency = new Map();
-    let maxFreq = 0;
-    let mode = id[0];
-    for (const val of id) {
-        const freq = (frequency.get(val) || 0) + 1;
-        frequency.set(val, freq);
-        if (freq > maxFreq) {
-            maxFreq = freq;
-            mode = val;
+    for (const v of id) {
+        if (!Number.isNaN(v))
+            frequency.set(v, (frequency.get(v) ?? 0) + 1);
+    }
+    let best = NaN;
+    let bestCount = 0;
+    for (const [v, count] of frequency) {
+        if (count > bestCount || (count === bestCount && v < best)) {
+            best = v;
+            bestCount = count;
         }
     }
-    return mode;
+    return best;
 }
 /**
- * Standard deviation of the non-na elements (PineScript `array.stdev(id, biased)`).
- * `biased` true (default) divides by the count, false by the count - 1.
+ * Standard deviation of the non-na elements (PineScript `array.stdev(id, biased)`): the square root of
+ * `array.variance(id, biased)`.
  */
 export function stdev(id, biased = true) {
     return Math.sqrt(variance(id, biased));
 }
+/** Sum of the values and sum of their squares, both added from the first to the last value. */
+function moments(values) {
+    let p = 0;
+    let q = 0;
+    for (const v of values)
+        p += v;
+    for (const v of values)
+        q += v * v;
+    return [p, q];
+}
 /**
  * Variance of the non-na elements (PineScript `array.variance(id, biased)`).
- * `biased` true (default) divides by the count, false by the count - 1.
+ *
+ * PineScript rule (moment form): with `p` the sum of the values, `q` the sum of their squares, `n` the count and
+ * `m = p / n`: biased (default) `max(0, q / n - m * m)`, unbiased `max(0, q / (n - 1) - (p / (n - 1)) * m)`.
+ * One value gives 0 biased and NaN unbiased; an array without values gives NaN.
  */
 export function variance(id, biased = true) {
     const values = id.filter((v) => !Number.isNaN(v));
-    if (!values.length)
+    const n = values.length;
+    if (!n)
         return NaN;
-    const mean = values.reduce((a, b) => a + b, 0) / values.length;
-    const squares = values.reduce((a, b) => a + (b - mean) * (b - mean), 0);
-    return squares / (biased ? values.length : values.length - 1);
+    if (n < 2)
+        return biased ? 0 : NaN;
+    const [p, q] = moments(values);
+    const mean = p / n;
+    return biased ? Math.max(0, q / n - mean * mean) : Math.max(0, q / (n - 1) - (p / (n - 1)) * mean);
 }
 /**
  * Fills the array with the specified value
  */
 export function fill(id, value, index_from = 0, index_to) {
-    const end = index_to ?? id.length;
-    for (let i = index_from; i < end; i++) {
+    // PineScript: an na bound is the start / the end; a bound past the end is a runtime error
+    const start = index_from === undefined || index_from === null || Number.isNaN(index_from) ? 0 : index_from;
+    const end = index_to === undefined || index_to === null || Number.isNaN(index_to) ? id.length : index_to;
+    for (const i of [start, end]) {
+        if (i < 0 || i > id.length)
+            throw new Error(`array.fill: index ${i} is out of bounds, array size is ${id.length}`);
+    }
+    for (let i = start; i < end; i++) {
         id[i] = value;
     }
 }
@@ -244,6 +467,9 @@ export function from(...values) {
  * ```
  */
 export function first(id) {
+    // PineScript: a runtime error on an empty array
+    if (id.length === 0)
+        throw new Error('Cannot call array.first() if array is empty');
     return id[0];
 }
 /**
@@ -263,6 +489,9 @@ export function first(id) {
  * ```
  */
 export function last(id) {
+    // PineScript: a runtime error on an empty array (as array.first)
+    if (id.length === 0)
+        throw new Error('Cannot call array.last() if array is empty');
     return id[id.length - 1];
 }
 /**
@@ -608,32 +837,38 @@ export function binary_search(id, val) {
  * - Array must be sorted in ascending order
  * - For duplicate values, returns leftmost occurrence
  * - When value not found, returns position of next smaller element
+ * - PineScript rules: a value below every element gives 0; `na` counts as greater than every number (an array
+ *   without na gives `size - 1`); the comparison is exact (no 1e-10 tolerance)
  */
 export function binary_search_leftmost(id, val) {
-    let left = 0;
-    let right = id.length - 1;
-    let result = -1;
-    let found = false;
-    while (left <= right) {
-        const mid = Math.floor((left + right) / 2);
-        if (id[mid] < val) {
-            if (!found) {
-                result = mid; // Track the last element smaller than val (only if not found)
-            }
-            left = mid + 1;
-        }
-        else if (id[mid] === val) {
-            result = mid;
-            found = true;
-            // Continue searching to the left for leftmost occurrence
-            right = mid - 1;
-        }
-        else {
-            // id[mid] > val
-            right = mid - 1;
-        }
+    if (id.length === 0)
+        return -1;
+    const at = searchBound(id, val, false);
+    return at < id.length && compareSorted(id[at], val) === 0 ? at : Math.max(0, at - 1);
+}
+/**
+ * Order of the PineScript binary searches: numbers in ascending order, na above every number (equal to na).
+ */
+function compareSorted(a, b) {
+    const an = Number.isNaN(a);
+    const bn = Number.isNaN(b);
+    if (an || bn)
+        return an === bn ? 0 : an ? 1 : -1;
+    return a < b ? -1 : a > b ? 1 : 0;
+}
+/** First index whose element is >= `val` (`after` false) or > `val` (`after` true); `id.length` when none. */
+function searchBound(id, val, after) {
+    let lo = 0;
+    let hi = id.length;
+    while (lo < hi) {
+        const mid = (lo + hi) >>> 1;
+        const c = compareSorted(id[mid], val);
+        if (c < 0 || (after && c === 0))
+            lo = mid + 1;
+        else
+            hi = mid;
     }
-    return result;
+    return lo;
 }
 /**
  * Binary Search Rightmost
@@ -663,31 +898,14 @@ export function binary_search_leftmost(id, val) {
  * - Array must be sorted in ascending order
  * - For duplicate values, returns rightmost occurrence
  * - When value not found, returns position of next larger element
+ * - PineScript rules: a value above every element gives `size` (the position after the last element); `na` counts
+ *   as greater than every number (an array without na gives `size`); the comparison is exact (no 1e-10 tolerance)
  */
 export function binary_search_rightmost(id, val) {
-    let left = 0;
-    let right = id.length - 1;
-    let result = -1;
-    let found = false;
-    while (left <= right) {
-        const mid = Math.floor((left + right) / 2);
-        if (id[mid] <= val) {
-            if (id[mid] === val) {
-                result = mid;
-                found = true;
-            }
-            // Continue searching to the right for rightmost occurrence
-            left = mid + 1;
-        }
-        else {
-            // id[mid] > val
-            if (!found) {
-                result = mid; // Track the first element greater than val (only if not found)
-            }
-            right = mid - 1;
-        }
-    }
-    return result;
+    if (id.length === 0)
+        return -1;
+    const at = searchBound(id, val, true);
+    return at > 0 && compareSorted(id[at - 1], val) === 0 ? at - 1 : at;
 }
 /**
  * Covariance
@@ -712,24 +930,38 @@ export function binary_search_rightmost(id, val) {
  * - Unbiased (false): divides by n-1 (sample covariance)
  * - Returns NaN if arrays are empty or have different lengths
  * - Formula: Cov(X,Y) = E[(X - μX)(Y - μY)]
+ *
+ * PineScript rules: a pair where either value is `na` is skipped and the count is the number of pairs kept; both
+ * means first, then the sum of the products from the first to the last pair. One pair gives 0 biased, NaN unbiased.
  */
 export function covariance(id1, id2, biased = true) {
-    if (id1.length === 0 || id2.length === 0) {
+    if (id1.length !== id2.length) {
         return NaN;
     }
-    if (id1.length !== id2.length) {
+    const xs = [];
+    const ys = [];
+    for (let i = 0; i < id1.length; i++) {
+        if (Number.isNaN(id1[i]) || Number.isNaN(id2[i]))
+            continue;
+        xs.push(id1[i]);
+        ys.push(id2[i]);
+    }
+    const n = xs.length;
+    if (!n || (!biased && n < 2))
         return NaN;
+    let mean1 = 0;
+    let mean2 = 0;
+    for (let i = 0; i < n; i++) {
+        mean1 += xs[i];
+        mean2 += ys[i];
     }
-    const n = id1.length;
-    const mean1 = avg(id1);
-    const mean2 = avg(id2);
+    mean1 /= n;
+    mean2 /= n;
     let sum = 0;
     for (let i = 0; i < n; i++) {
-        sum += (id1[i] - mean1) * (id2[i] - mean2);
+        sum += (xs[i] - mean1) * (ys[i] - mean2);
     }
-    // Biased: divide by n, Unbiased: divide by n-1
-    const divisor = biased ? n : n - 1;
-    return sum / divisor;
+    return sum / (biased ? n : n - 1);
 }
 /**
  * Percentile Linear Interpolation
@@ -754,32 +986,45 @@ export function covariance(id1, id2, biased = true) {
  * - Returns NaN if array is empty
  *
  * PineScript rules:
- * - position in the sorted array: `percentage / 100 * size - 0.5`, clamped to the first / last value, linear
- *   interpolation between the two neighbours
+ * - 1-based position in the sorted array: `size * percentage / 100 + 0.5` (snapped to an integer within 1e-9),
+ *   clamped to the first / last value; between two values `lo * (1 - frac) + hi * frac`
  * - `na` values are sorted after all numbers; with an `na` in the array, a position between two values gives `na`
+ * - an `na` percentage gives `na`; a percentage outside 0 .. 100 is a runtime error (throws)
  */
 export function percentile_linear_interpolation(id, percentage) {
-    if (id.length === 0) {
+    if (id.length === 0 || Number.isNaN(percentage)) {
         return NaN;
     }
+    checkPercentage('percentile_linear_interpolation', percentage);
     const s = sortedNaLast(id);
     const n = s.length;
-    const pos = (percentage / 100) * n - 0.5;
-    if (pos <= 0)
+    let pos = (n * percentage) / 100 + 0.5;
+    const nearest = Math.round(pos);
+    if (Math.abs(pos - nearest) < 1e-9)
+        pos = nearest;
+    if (pos <= 1)
         return s[0];
-    if (pos >= n - 1)
+    if (pos >= n)
         return s[n - 1];
-    const lo = Math.floor(pos);
-    const f = pos - lo;
-    if (f === 0)
-        return s[lo];
-    return Number.isNaN(s[n - 1]) ? NaN : s[lo] + f * (s[lo + 1] - s[lo]);
+    const lower = Math.floor(pos);
+    const frac = pos - lower;
+    if (frac === 0)
+        return s[lower - 1];
+    if (Number.isNaN(s[n - 1]))
+        return NaN;
+    return s[lower - 1] * (1 - frac) + s[lower] * frac;
 }
 /** Array values sorted ascending, `na` values after the numbers (array.percentile_*). */
 function sortedNaLast(id) {
     const numbers = id.filter((v) => !Number.isNaN(v)).sort((a, b) => a - b);
     return [...numbers, ...Array(id.length - numbers.length).fill(NaN)];
 }
+/** A percentage outside 0 .. 100 is a PineScript runtime error. */
+function checkPercentage(name, percentage) {
+    if (!(percentage >= 0 && percentage <= 100)) {
+        throw new Error(`array.${name}: percentage ${percentage} must be between 0 and 100`);
+    }
+}
 /**
  * Percentile Nearest Rank
  *
@@ -803,15 +1048,18 @@ function sortedNaLast(id) {
  * - Returns NaN if array is empty
  *
  * PineScript rules:
- * - the value at rank `ceil(percentage / 100 * size)` of the sorted array
+ * - the value at rank `ceil(percentage * size / 100)` (clamped to 1 .. size) of the sorted array
  * - `na` values are sorted after all numbers (na when that rank holds an `na`)
+ * - an `na` percentage counts as 0; a percentage outside 0 .. 100 is a runtime error (throws)
  */
 export function percentile_nearest_rank(id, percentage) {
     if (id.length === 0) {
         return NaN;
     }
+    const pct = Number.isNaN(percentage) ? 0 : percentage;
+    checkPercentage('percentile_nearest_rank', pct);
     const s = sortedNaLast(id);
-    const rank = Math.min(s.length, Math.max(1, Math.ceil((percentage / 100) * s.length)));
+    const rank = Math.min(s.length, Math.max(1, Math.ceil((pct * s.length) / 100)));
     return s[rank - 1];
 }
 /**
@@ -829,31 +1077,39 @@ export function percentile_nearest_rank(id, percentage) {
  * ```typescript
  * const arr = [1, 2, 3, 4, 5];
  * const rank = array.percentrank(arr, 2); // Value at index 2 is 3
- * // Returns: 40 (40% of values <= 3)
+ * // Returns: 50 ((3 - 1) * 100 / (5 - 1))
  * ```
  *
  * @remarks
- * - Returns percentage of elements <= the value at given index
  * - Range: 0 to 100
- * - Returns NaN if array is empty or index out of bounds
+ *
+ * PineScript rules:
+ * - `(count - 1) * 100 / (size - 1)`, with `count` the number of non-na elements <= the element (exact
+ *   comparison, no 1e-10 tolerance); `na` elements count in the size
+ * - an `na` element, a one-element array or an empty array gives NaN
+ * - an `na` index counts as 0; an index outside `0 .. size - 1` is a runtime error (throws)
  */
 export function percentrank(id, index) {
-    if (id.length === 0 || index < 0 || index >= id.length) {
+    const i = Number.isNaN(index) ? 0 : Math.trunc(index);
+    if (id.length === 0) {
         return NaN;
     }
-    const value = id[index];
-    if (isNaN(value)) {
+    if (i < 0 || i >= id.length) {
+        throw new Error(`array.percentrank: index ${i} is out of bounds, array size is ${id.length}`);
+    }
+    if (id.length === 1) {
+        return NaN;
+    }
+    const value = id[i];
+    if (Number.isNaN(value)) {
         return NaN;
     }
-    // Count elements less than or equal to the value
     let count = 0;
-    for (let i = 0; i < id.length; i++) {
-        if (!isNaN(id[i]) && id[i] <= value) {
+    for (const v of id) {
+        if (v <= value)
             count++;
-        }
     }
-    // Calculate percentage
-    return (count / id.length) * 100;
+    return ((count - 1) * 100) / (id.length - 1);
 }
 /**
  * Sort Indices
@@ -880,20 +1136,11 @@ export function percentrank(id, index) {
  * - Original array is not modified
  * - Returns indices that would sort the array
  * - Useful for maintaining correspondence with other arrays
+ * - PineScript rule: the indices of `na` elements go where `array.sort` puts them (after the numbers in ascending
+ *   order, in their original order: `sort_indices([na, na, 5, 1])` is `[3, 2, 0, 1]`)
  */
 export function sort_indices(id, order = 'asc') {
-    // Create array of indices
-    const indices = Array.from({ length: id.length }, (_, i) => i);
-    // Sort indices based on values in original array
-    indices.sort((a, b) => {
-        if (order === 'asc') {
-            return id[a] - id[b];
-        }
-        else {
-            return id[b] - id[a];
-        }
-    });
-    return indices;
+    return sortedPositions(id, order);
 }
 /**
  * Standardize
@@ -915,21 +1162,25 @@ export function sort_indices(id, order = 'asc') {
  * @remarks
  * - Formula: z = (x - μ) / σ
  * - Result has mean of 0 and standard deviation of 1
- * - Returns array of NaN if standard deviation is 0
  * - Useful for comparing values on different scales
+ *
+ * PineScript rules:
+ * - μ and σ are the population mean and standard deviation of the non-na elements, as `array.variance` (moment
+ *   form); `na` elements stay `na`
+ * - when σ is 0 (all values equal) every non-na element gives 1
  */
 export function standardize(id) {
-    if (id.length === 0) {
-        return [];
+    const values = id.filter((v) => !Number.isNaN(v));
+    if (!values.length) {
+        return id.map(() => NaN);
     }
-    const mean = avg(id);
-    const stdDev = stdev(id);
-    // If stddev is 0, all values are the same - return array of 0s or NaN
+    const [p, q] = moments(values);
+    const mean = p / values.length;
+    const stdDev = Math.sqrt(Math.max(0, q / values.length - mean * mean));
     if (stdDev === 0) {
-        return id.map(() => NaN);
+        return id.map((v) => (Number.isNaN(v) ? NaN : 1));
     }
-    // Calculate z-score for each element
-    return id.map(value => (value - mean) / stdDev);
+    return id.map((v) => (Number.isNaN(v) ? NaN : (v - mean) / stdDev));
 }
 /**
  * New Type (User-Defined Type Array)