oakscriptjs 0.8.1 → 0.9.0

package/dist/esm/array/index.d.ts

@@ -0,0 +1,701 @@
+/**
+ * Array namespace
+ * Mirrors PineScript's array.* functions
+ */
+import type { PineArray, int, float, bool, simple_int, color, Line, Box, Label, Linefill } from '../types/index.js';
+/**
+ * Creates a new array with initial size and default value
+ */
+export declare function new_array<T>(size?: simple_int, initial_value?: T): PineArray<T>;
+/**
+ * Returns the number of elements in an array
+ */
+export declare function size<T>(id: PineArray<T>): int;
+/**
+ * Returns the element at the specified index
+ */
+export declare function get<T>(id: PineArray<T>, index: simple_int): T;
+/**
+ * Sets the value of the element at the specified index
+ */
+export declare function set<T>(id: PineArray<T>, index: simple_int, value: T): void;
+/**
+ * Appends a value to the end of the array
+ */
+export declare function push<T>(id: PineArray<T>, value: T): void;
+/**
+ * Removes and returns the last element of the array
+ */
+export declare function pop<T>(id: PineArray<T>): T;
+/**
+ * Inserts a value at the beginning of the array
+ */
+export declare function unshift<T>(id: PineArray<T>, value: T): void;
+/**
+ * Removes and returns the first element of the array
+ */
+export declare function shift<T>(id: PineArray<T>): T;
+/**
+ * Removes all elements from the array
+ */
+export declare function clear<T>(id: PineArray<T>): void;
+/**
+ * Inserts a value at the specified index
+ */
+export declare function insert<T>(id: PineArray<T>, index: simple_int, value: T): void;
+/**
+ * Removes the element at the specified index
+ */
+export declare function remove<T>(id: PineArray<T>, index: simple_int): T;
+/**
+ * Returns true if the array contains the value
+ */
+export declare function includes<T>(id: PineArray<T>, value: T): bool;
+/**
+ * Returns the index of the first occurrence of the value
+ */
+export declare function indexof<T>(id: PineArray<T>, value: T): int;
+/**
+ * Returns the index of the last occurrence of the value
+ */
+export declare function lastindexof<T>(id: PineArray<T>, value: T): int;
+/**
+ * Returns a shallow copy of the array
+ */
+export declare function copy<T>(id: PineArray<T>): PineArray<T>;
+/**
+ * Concatenates two arrays
+ */
+export declare function concat<T>(id1: PineArray<T>, id2: PineArray<T>): PineArray<T>;
+/**
+ * Joins all elements into a string
+ */
+export declare function join(id: PineArray<any>, separator?: string): string;
+/**
+ * Reverses the array in place
+ */
+export declare function reverse<T>(id: PineArray<T>): void;
+/**
+ * Returns a slice of the array
+ */
+export declare function slice<T>(id: PineArray<T>, index_from: simple_int, index_to?: simple_int): PineArray<T>;
+/**
+ * Sorts array elements (numeric)
+ */
+export declare function sort<T>(id: PineArray<T>, order?: 'asc' | 'desc'): void;
+/**
+ * Returns the sum of all elements (numeric arrays only)
+ */
+export declare function sum(id: PineArray<float>): float;
+/**
+ * Returns the average of all elements (numeric arrays only)
+ */
+export declare function avg(id: PineArray<float>): float;
+/**
+ * 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.
+ */
+export declare function min(id: PineArray<float>, nth?: simple_int): float;
+/**
+ * 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.
+ */
+export declare function max(id: PineArray<float>, nth?: simple_int): float;
+/**
+ * Returns the median value (numeric arrays only)
+ */
+export declare function median(id: PineArray<float>): float;
+/**
+ * Returns the mode (most frequent value)
+ */
+export declare function mode(id: PineArray<float>): float;
+/**
+ * Standard deviation of the non-na elements (PineScript `array.stdev(id, biased)`).
+ * `biased` true (default) divides by the count, false by the count - 1.
+ */
+export declare function stdev(id: PineArray<float>, biased?: bool): float;
+/**
+ * Variance of the non-na elements (PineScript `array.variance(id, biased)`).
+ * `biased` true (default) divides by the count, false by the count - 1.
+ */
+export declare function variance(id: PineArray<float>, biased?: bool): float;
+/**
+ * Fills the array with the specified value
+ */
+export declare function fill<T>(id: PineArray<T>, value: T, index_from?: simple_int, index_to?: simple_int): void;
+/**
+ * Creates an array from its arguments (PineScript `array.from(arg0, arg1, ...)`).
+ * `na` values are kept.
+ *
+ * @example
+ * ```typescript
+ * array.from(0.236, 0.382, 0.5, 0.618); // [0.236, 0.382, 0.5, 0.618]
+ * ```
+ */
+export declare function from<T>(...values: T[]): PineArray<T>;
+/**
+ * Returns the first element of the array
+ *
+ * @param id - The array
+ * @returns The first element, or undefined if array is empty
+ *
+ * @remarks
+ * - Equivalent to `array.get(id, 0)`
+ * - Returns undefined for empty arrays
+ *
+ * @example
+ * ```typescript
+ * const arr = [1, 2, 3, 4, 5];
+ * const firstElement = array.first(arr); // Returns: 1
+ * ```
+ */
+export declare function first<T>(id: PineArray<T>): T;
+/**
+ * Returns the last element of the array
+ *
+ * @param id - The array
+ * @returns The last element, or undefined if array is empty
+ *
+ * @remarks
+ * - Equivalent to `array.get(id, array.size(id) - 1)`
+ * - Returns undefined for empty arrays
+ *
+ * @example
+ * ```typescript
+ * const arr = [1, 2, 3, 4, 5];
+ * const lastElement = array.last(arr); // Returns: 5
+ * ```
+ */
+export declare function last<T>(id: PineArray<T>): T;
+/**
+ * True when at least one element of a bool array is true (PineScript `array.some(id)`).
+ * An empty array gives false.
+ */
+export declare function some(id: PineArray<bool>): bool;
+/**
+ * True when every element of a bool array is true (PineScript `array.every(id)`).
+ * An empty array gives false, as in PineScript.
+ */
+export declare function every(id: PineArray<bool>): bool;
+/**
+ * Create new boolean array
+ *
+ * Creates a new array object of bool type elements.
+ *
+ * @param size - Initial size of array (default: 0)
+ * @param initial_value - Initial value for all elements (default: false)
+ * @returns New boolean array
+ *
+ * @example
+ * ```typescript
+ * const arr = array.new_bool(5, true);
+ * // Creates: [true, true, true, true, true]
+ * ```
+ */
+export declare function new_bool(size?: simple_int, initial_value?: bool): PineArray<bool>;
+/**
+ * Create new float array
+ *
+ * Creates a new array object of float type elements.
+ *
+ * @param size - Initial size of array (default: 0)
+ * @param initial_value - Initial value for all elements (default: NaN)
+ * @returns New float array
+ *
+ * @example
+ * ```typescript
+ * const arr = array.new_float(5, 0.0);
+ * // Creates: [0.0, 0.0, 0.0, 0.0, 0.0]
+ * ```
+ */
+export declare function new_float(size?: simple_int, initial_value?: float): PineArray<float>;
+/**
+ * Create new integer array
+ *
+ * Creates a new array object of int type elements.
+ *
+ * @param size - Initial size of array (default: 0)
+ * @param initial_value - Initial value for all elements (default: NaN)
+ * @returns New integer array
+ *
+ * @example
+ * ```typescript
+ * const arr = array.new_int(5, 0);
+ * // Creates: [0, 0, 0, 0, 0]
+ * ```
+ */
+export declare function new_int(size?: simple_int, initial_value?: int): PineArray<int>;
+/**
+ * Create new string array
+ *
+ * Creates a new array object of string type elements.
+ *
+ * @param size - Initial size of array (default: 0)
+ * @param initial_value - Initial value for all elements (default: undefined)
+ * @returns New string array
+ *
+ * @example
+ * ```typescript
+ * const arr = array.new_string(5, "text");
+ * // Creates: ["text", "text", "text", "text", "text"]
+ * ```
+ */
+export declare function new_string(size?: simple_int, initial_value?: string): PineArray<string>;
+/**
+ * Create new color array
+ *
+ * Creates a new array object of color type elements.
+ *
+ * @param size - Initial size of array (default: 0)
+ * @param initial_value - Initial value for all elements (default: undefined)
+ * @returns New color array
+ *
+ * @example
+ * ```typescript
+ * const arr = array.new_color(5, "#FF0000");
+ * // Creates: ["#FF0000", "#FF0000", "#FF0000", "#FF0000", "#FF0000"]
+ * ```
+ */
+export declare function new_color(size?: simple_int, initial_value?: color): PineArray<color>;
+/**
+ * Create new line array
+ *
+ * Creates a new array object of line type elements.
+ *
+ * @param size - Initial size of array (default: 0)
+ * @param initial_value - Initial value for all elements (default: undefined)
+ * @returns New line array
+ *
+ * @example
+ * ```typescript
+ * import { array, line } from 'oakscriptjs';
+ *
+ * // Create array to store last 15 lines
+ * const lines = array.new_line();
+ * const trendLine = line.new(0, 100, 50, 150);
+ * array.push(lines, trendLine);
+ *
+ * // Manage line count
+ * if (array.size(lines) > 15) {
+ *   const oldLine = array.shift(lines);
+ * }
+ * ```
+ *
+ * @remarks
+ * Useful for managing collections of trend lines, support/resistance levels, or channel lines.
+ * In PineScript, this is typically used with line.delete() to manage chart object limits.
+ */
+export declare function new_line(size?: simple_int, initial_value?: Line): PineArray<Line>;
+/**
+ * Create new box array
+ *
+ * Creates a new array object of box type elements.
+ *
+ * @param size - Initial size of array (default: 0)
+ * @param initial_value - Initial value for all elements (default: undefined)
+ * @returns New box array
+ *
+ * @example
+ * ```typescript
+ * import { array, box } from 'oakscriptjs';
+ *
+ * // Create array to store gap boxes
+ * const gaps = array.new_box();
+ * const gapBox = box.new(10, 120, 15, 110);
+ * array.push(gaps, gapBox);
+ *
+ * // Track multiple gaps
+ * for (let i = 0; i < array.size(gaps); i++) {
+ *   const gap = array.get(gaps, i);
+ *   const gapTop = box.get_top(gap);
+ *   const gapBottom = box.get_bottom(gap);
+ *   // Check if gap filled...
+ * }
+ * ```
+ *
+ * @remarks
+ * Useful for tracking ranges, gaps, consolidation zones, or rectangle patterns.
+ * Enables systematic analysis of multiple box objects.
+ */
+export declare function new_box(size?: simple_int, initial_value?: Box): PineArray<Box>;
+/**
+ * Create new label array
+ *
+ * Creates a new array object of label type elements.
+ *
+ * @param size - Initial size of array (default: 0)
+ * @param initial_value - Initial value for all elements (default: undefined)
+ * @returns New label array
+ *
+ * @example
+ * ```typescript
+ * import { array, label } from 'oakscriptjs';
+ *
+ * // Create array to store pivot labels
+ * const pivotLabels = array.new_label();
+ *
+ * // Add labels for pivot highs
+ * const pivotLabel = label.new(50, 155.5, 'PH', 'bar_index', 'abovebar');
+ * array.push(pivotLabels, pivotLabel);
+ *
+ * // Limit number of labels shown
+ * const maxLabels = 50;
+ * if (array.size(pivotLabels) > maxLabels) {
+ *   array.shift(pivotLabels);
+ * }
+ * ```
+ *
+ * @remarks
+ * Useful for managing collections of annotations, pivot markers, or signal labels.
+ * Helps limit the number of labels displayed by removing old ones.
+ */
+export declare function new_label(size?: simple_int, initial_value?: Label): PineArray<Label>;
+/**
+ * Create new linefill array
+ *
+ * Creates a new array object of linefill type elements.
+ *
+ * @param size - Initial size of array (default: 0)
+ * @param initial_value - Initial value for all elements (default: undefined)
+ * @returns New linefill array
+ *
+ * @example
+ * ```typescript
+ * import { array, line, linefill } from 'oakscriptjs';
+ *
+ * // Create array to store channel fills
+ * const channels = array.new_linefill();
+ *
+ * // Create channel
+ * const upperLine = line.new(0, 120, 50, 130);
+ * const lowerLine = line.new(0, 100, 50, 110);
+ * const channelFill = linefill.new(upperLine, lowerLine, '#0000FF15');
+ *
+ * array.push(channels, channelFill);
+ * ```
+ *
+ * @remarks
+ * Useful for managing collections of channel fills, Bollinger Band fills, or regression channel fills.
+ * Enables dynamic color changes across multiple channels.
+ */
+export declare function new_linefill(size?: simple_int, initial_value?: Linefill): PineArray<Linefill>;
+/**
+ * Absolute value of array elements
+ *
+ * Returns an array containing the absolute value of each element in the original array.
+ *
+ * @param id - Array of numeric values
+ * @returns New array with absolute values
+ *
+ * @example
+ * ```typescript
+ * const arr = [-1, -2, 3, -4, 5];
+ * const result = array.abs(arr);
+ * // Returns: [1, 2, 3, 4, 5]
+ * ```
+ */
+export declare function abs(id: PineArray<float>): PineArray<float>;
+/**
+ * Range of array values
+ *
+ * Returns the difference between the maximum and minimum values in the array.
+ *
+ * @param id - Array of numeric values
+ * @returns Difference between max and min (range)
+ *
+ * @example
+ * ```typescript
+ * const arr = [1, 5, 3, 9, 2];
+ * const result = array.range(arr);
+ * // Returns: 8 (9 - 1)
+ * ```
+ *
+ * @remarks
+ * Returns NaN if the array is empty.
+ */
+export declare function range(id: PineArray<float>): float;
+/**
+ * Binary Search
+ *
+ * Searches for a value in a sorted array using binary search algorithm.
+ * Returns the index of the value if found, or -1 if not found.
+ *
+ * @param id - Sorted array (ascending order)
+ * @param val - Value to search for
+ * @returns Index of the value, or -1 if not found
+ *
+ * @example
+ * ```typescript
+ * const arr = [-2, 0, 1, 5, 9]; // Must be sorted
+ * const index = array.binary_search(arr, 5);
+ * // Returns: 3
+ * ```
+ *
+ * @remarks
+ * - Array must be sorted in ascending order
+ * - Uses standard binary search algorithm
+ * - Time complexity: O(log n)
+ */
+export declare function binary_search(id: PineArray<float>, val: float): int;
+/**
+ * Binary Search Leftmost
+ *
+ * Returns the index of the value if found. When not found, returns the index
+ * of the next smallest element to the left of where the value would be.
+ *
+ * @param id - Sorted array (ascending order)
+ * @param val - Value to search for
+ * @returns Index of value or insertion point to the left
+ *
+ * @example
+ * ```typescript
+ * const arr = [-2, 0, 1, 5, 9];
+ * const index = array.binary_search_leftmost(arr, 3);
+ * // Returns: 2 (index of 1, which is left of where 3 would be)
+ * ```
+ *
+ * @example
+ * ```typescript
+ * const arr = [4, 5, 5, 5];
+ * const index = array.binary_search_leftmost(arr, 5);
+ * // Returns: 1 (index of first instance of 5)
+ * ```
+ *
+ * @remarks
+ * - Array must be sorted in ascending order
+ * - For duplicate values, returns leftmost occurrence
+ * - When value not found, returns position of next smaller element
+ */
+export declare function binary_search_leftmost(id: PineArray<float>, val: float): int;
+/**
+ * Binary Search Rightmost
+ *
+ * Returns the index of the value if found. When not found, returns the index
+ * of the element to the right of where the value would be.
+ *
+ * @param id - Sorted array (ascending order)
+ * @param val - Value to search for
+ * @returns Index of value or insertion point to the right
+ *
+ * @example
+ * ```typescript
+ * const arr = [-2, 0, 1, 5, 9];
+ * const index = array.binary_search_rightmost(arr, 3);
+ * // Returns: 3 (index of 5, which is right of where 3 would be)
+ * ```
+ *
+ * @example
+ * ```typescript
+ * const arr = [4, 5, 5, 5];
+ * const index = array.binary_search_rightmost(arr, 5);
+ * // Returns: 3 (index of last instance of 5)
+ * ```
+ *
+ * @remarks
+ * - Array must be sorted in ascending order
+ * - For duplicate values, returns rightmost occurrence
+ * - When value not found, returns position of next larger element
+ */
+export declare function binary_search_rightmost(id: PineArray<float>, val: float): int;
+/**
+ * Covariance
+ *
+ * Returns the covariance between two arrays.
+ *
+ * @param id1 - First array
+ * @param id2 - Second array
+ * @param biased - If true, uses biased estimate (population). If false, uses unbiased estimate (sample). Default: true
+ * @returns Covariance between the two arrays
+ *
+ * @example
+ * ```typescript
+ * const prices = [100, 102, 98, 105, 103];
+ * const volume = [1000, 1200, 950, 1300, 1100];
+ * const cov = array.covariance(prices, volume);
+ * // Returns covariance between price and volume
+ * ```
+ *
+ * @remarks
+ * - Biased (true): divides by n (population covariance)
+ * - 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)]
+ */
+export declare function covariance(id1: PineArray<float>, id2: PineArray<float>, biased?: bool): float;
+/**
+ * Percentile Linear Interpolation
+ *
+ * Returns the value for which the specified percentage of array values are
+ * less than or equal to it, using linear interpolation.
+ *
+ * @param id - Array of numeric values
+ * @param percentage - Percentage (0-100)
+ * @returns Percentile value using linear interpolation
+ *
+ * @example
+ * ```typescript
+ * const arr = [1, 2, 3, 4, 5];
+ * const p50 = array.percentile_linear_interpolation(arr, 50);
+ * // Returns: 3 (median)
+ * ```
+ *
+ * @remarks
+ * - Uses linear interpolation between adjacent values
+ * - Result may not be a member of the array
+ * - 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
+ * - `na` values are sorted after all numbers; with an `na` in the array, a position between two values gives `na`
+ */
+export declare function percentile_linear_interpolation(id: PineArray<float>, percentage: float): float;
+/**
+ * Percentile Nearest Rank
+ *
+ * Returns the value for which the specified percentage of array values are
+ * less than or equal to it, using the nearest-rank method.
+ *
+ * @param id - Array of numeric values
+ * @param percentage - Percentage (0-100)
+ * @returns Percentile value using nearest rank
+ *
+ * @example
+ * ```typescript
+ * const arr = [1, 2, 3, 4, 5];
+ * const p50 = array.percentile_nearest_rank(arr, 50);
+ * // Returns: 3 (median, always a member of array)
+ * ```
+ *
+ * @remarks
+ * - Result is always a member of the array
+ * - Uses nearest-rank method (no interpolation)
+ * - Returns NaN if array is empty
+ *
+ * PineScript rules:
+ * - the value at rank `ceil(percentage / 100 * size)` of the sorted array
+ * - `na` values are sorted after all numbers (na when that rank holds an `na`)
+ */
+export declare function percentile_nearest_rank(id: PineArray<float>, percentage: float): float;
+/**
+ * Percent Rank
+ *
+ * Returns the percentile rank of the element at the specified index.
+ * The percentile rank is the percentage of elements that are less than
+ * or equal to the reference value.
+ *
+ * @param id - Array of numeric values
+ * @param index - Index of element to rank
+ * @returns Percentile rank (0-100)
+ *
+ * @example
+ * ```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)
+ * ```
+ *
+ * @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
+ */
+export declare function percentrank(id: PineArray<float>, index: int): float;
+/**
+ * Sort Indices
+ *
+ * Returns an array of indices which, when used to index the original array,
+ * will access its elements in their sorted order. Does not modify the original array.
+ *
+ * @param id - Array to get sorted indices from
+ * @param order - Sort order: 'asc' or 'desc' (default: 'asc')
+ * @returns Array of indices in sorted order
+ *
+ * @example
+ * ```typescript
+ * const arr = [5, -2, 0, 9, 1];
+ * const indices = array.sort_indices(arr); // [1, 2, 4, 0, 3]
+ * // arr[1] = -2 (smallest)
+ * // arr[2] = 0
+ * // arr[4] = 1
+ * // arr[0] = 5
+ * // arr[3] = 9 (largest)
+ * ```
+ *
+ * @remarks
+ * - Original array is not modified
+ * - Returns indices that would sort the array
+ * - Useful for maintaining correspondence with other arrays
+ */
+export declare function sort_indices(id: PineArray<float>, order?: 'asc' | 'desc'): PineArray<int>;
+/**
+ * Standardize
+ *
+ * Returns an array of standardized elements (z-score normalization).
+ * Each element is transformed to (value - mean) / stddev.
+ *
+ * @param id - Array of numeric values
+ * @returns Array of standardized values (z-scores)
+ *
+ * @example
+ * ```typescript
+ * const arr = [1, 2, 3, 4, 5];
+ * const standardized = array.standardize(arr);
+ * // Mean = 3, StdDev ≈ 1.414
+ * // Result ≈ [-1.414, -0.707, 0, 0.707, 1.414]
+ * ```
+ *
+ * @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
+ */
+export declare function standardize(id: PineArray<float>): PineArray<float>;
+/**
+ * New Type (User-Defined Type Array)
+ *
+ * Creates a new array of user-defined type elements.
+ *
+ * @param size - Initial size of array (default: 0)
+ * @param initial_value - Initial value for all elements
+ * @returns New array of user-defined type
+ *
+ * @example
+ * ```typescript
+ * // NOTE: User-defined types (UDTs) are not fully supported yet
+ * // This is a placeholder for future implementation
+ * const arr = array.newtype<MyType>(5);
+ * ```
+ *
+ * @remarks
+ * - **⚠️ LIMITED SUPPORT**: User-defined types (UDTs) require a type system
+ *   that is not yet fully implemented in this library
+ * - This function currently works like `new_array<T>()` for basic types
+ * - Full UDT support will be added in a future version
+ * - See PineScript documentation for UDT usage patterns
+ */
+export declare function newtype<T>(size?: simple_int, initial_value?: T): PineArray<T>;
+/**
+ * ⚠️ RENDERING FUNCTIONS NOT IMPLEMENTED
+ *
+ * The following array constructor functions are intentionally excluded
+ * because they create arrays for rendering objects, which are outside
+ * the scope of this calculation-focused library:
+ *
+ * - `new_box()` - Creates arrays of box drawing objects
+ * - `new_label()` - Creates arrays of label objects
+ * - `new_line()` - Creates arrays of line drawing objects
+ * - `new_linefill()` - Creates arrays of line fill objects
+ * - `new_table()` - Creates arrays of table layout objects
+ *
+ * **Design Constraint**: This library focuses on calculation and indicator
+ * functions only. Rendering, visualization, and UI functions require a
+ * rendering engine and are not included.
+ *
+ * If you need these functions, consider:
+ * 1. Using PineScript directly
+ * 2. Implementing a rendering layer separately
+ * 3. Using this library for calculations and another library for visualization
+ */
+//# sourceMappingURL=index.d.ts.map