oakscriptjs 0.8.1 → 0.9.0

package/src/types/metadata.ts

@@ -0,0 +1,334 @@
+/**
+ * @fileoverview Type definitions for indicator metadata
+ * These types define the structure of data returned by indicators
+ * @module types/metadata
+ */
+
+/**
+ * Plot style options
+ */
+export type PlotStyle = 'line' | 'stepline' | 'histogram' | 'area' | 'circles' | 'columns' | 'cross' | 'areabr' | 'steplinebr' | 'linebr' | 'stepline_diamond';
+
+/**
+ * Line style options
+ */
+export type LineStyle = 'solid' | 'dashed' | 'dotted';
+
+/**
+ * Plot display options
+ */
+export type PlotDisplay = 'all' | 'none' | 'data_window' | 'status_line' | 'pane';
+
+/**
+ * Options for a plot
+ */
+export interface PlotOptions {
+  /** Plot title */
+  title?: string;
+  /** Plot color (hex string or named color) */
+  color?: string;
+  /** Line width */
+  linewidth?: number;
+  /** Plot style */
+  style?: PlotStyle;
+  /** Line style (PineScript `linestyle`); default solid. A constant or an input value, not per bar */
+  linestyle?: LineStyle;
+  /** Track price on price scale */
+  trackprice?: boolean;
+  /** Histogram base value */
+  histbase?: number;
+  /** Offset from current bar */
+  offset?: number;
+  /** Join gaps in data */
+  join?: boolean;
+  /** User can edit */
+  editable?: boolean;
+  /** Display mode */
+  display?: PlotDisplay;
+  /** Transparency (0-100) */
+  transp?: number;
+  /** Draw the plot on the main chart pane even when the indicator is not an overlay; default false */
+  force_overlay?: boolean;
+}
+
+/**
+ * Options for a horizontal line
+ */
+export interface HLineOptions {
+  /** Line title */
+  title?: string;
+  /** Line color */
+  color?: string;
+  /** Line style (PineScript default: dashed) */
+  linestyle?: LineStyle;
+  /** Line width */
+  linewidth?: number;
+  /** User can edit */
+  editable?: boolean;
+}
+
+/**
+ * Options for a fill
+ */
+export interface FillOptions {
+  /** Fill color */
+  color?: string;
+  /** Transparency (0-100) */
+  transp?: number;
+  /** Fill title */
+  title?: string;
+  /** User can edit */
+  editable?: boolean;
+  /** Fill gaps in data */
+  fillgaps?: boolean;
+}
+
+/**
+ * Input parameter type
+ */
+export type InputType = 'int' | 'float' | 'bool' | 'string' | 'source' | 'color' | 'timeframe' | 'session' | 'time';
+
+/**
+ * Input parameter metadata
+ */
+export interface InputMetadata {
+  /** Input type */
+  type: InputType;
+  /** Internal name (snake_case) */
+  name: string;
+  /** Display title */
+  title: string;
+  /** Default value */
+  defval: any;
+  /** Minimum value (for numeric inputs) */
+  minval?: number;
+  /** Maximum value (for numeric inputs) */
+  maxval?: number;
+  /** Step size (for numeric inputs) */
+  step?: number;
+  /** Tooltip text */
+  tooltip?: string;
+  /** Inline group */
+  inline?: string;
+  /** Parameter group */
+  group?: string;
+  /** Options for dropdown (for string/source inputs) */
+  options?: any[];
+  /** Confirm before changing */
+  confirm?: boolean;
+}
+
+/**
+ * Plot metadata
+ */
+export interface PlotMetadata {
+  /** Variable name for the plot */
+  varName: string;
+  /** Plot title */
+  title: string;
+  /** Plot color */
+  color: string;
+  /** Line width */
+  linewidth: number;
+  /** Plot style */
+  style: PlotStyle;
+}
+
+/**
+ * Indicator metadata
+ */
+export interface IndicatorMetadata {
+  /** Indicator title */
+  title: string;
+  /** Short title */
+  shorttitle?: string;
+  /** Overlay on main chart */
+  overlay: boolean;
+  /** Number format precision */
+  precision?: number;
+  /** Number format */
+  format?: string;
+  /** Timeframe */
+  timeframe?: string;
+  /** Show gaps in timeframes */
+  timeframe_gaps?: boolean;
+  /** Input parameters */
+  inputs?: InputMetadata[];
+  /** Plots */
+  plots?: PlotMetadata[];
+}
+
+/**
+ * Time-value pair for charting
+ */
+export interface TimeValue {
+  /** Time (timestamp or string) */
+  time: any;
+  /** Value */
+  value: number;
+  /** Per-bar color override */
+  color?: string;
+}
+
+/**
+ * Plot data with options
+ */
+export interface PlotData {
+  /** Time-value pairs */
+  data: TimeValue[];
+  /** Plot options */
+  options?: PlotOptions;
+}
+
+/**
+ * Horizontal line data
+ */
+export interface HLineData {
+  /** Y-axis value */
+  value: number;
+  /** Line options */
+  options?: HLineOptions;
+}
+
+/**
+ * Fill data (area between two plots)
+ */
+export interface FillData {
+  /** First plot index or name */
+  plot1: number | string;
+  /** Second plot index or name */
+  plot2: number | string;
+  /** Fill options */
+  options?: FillOptions;
+  /** Per-bar fill colors (overrides static options.color) */
+  colors?: string[];
+  /** Gradient fill (PineScript `fill(p1, p2, top_value, bottom_value, top_color, bottom_color)`) */
+  gradient?: FillGradient;
+}
+
+/**
+ * Gradient of a fill, one entry per bar. PineScript rules: the colour
+ * changes with the price, `topColor` at `topValue` and `bottomColor` at `bottomValue`; outside that range the end
+ * colour is kept; each bar has its own gradient (the part from bar i-1 to bar i uses the values of bar i).
+ */
+export interface FillGradient {
+  /** Price of `topColor`, per bar */
+  topValue: number[];
+  /** Price of `bottomColor`, per bar */
+  bottomValue: number[];
+  /** Colour at `topValue`, per bar (null: na) */
+  topColor: Array<string | null>;
+  /** Colour at `bottomValue`, per bar (null: na) */
+  bottomColor: Array<string | null>;
+}
+
+/**
+ * Marker location on the chart (PineScript plotshape/plotchar locations)
+ */
+export type MarkerLocation = 'abovebar' | 'belowbar' | 'top' | 'bottom' | 'absolute';
+
+/**
+ * Marker size (PineScript size.* constants)
+ */
+export type MarkerSize = 'auto' | 'tiny' | 'small' | 'normal' | 'large' | 'huge';
+
+/**
+ * Shape style (PineScript shape.* constants)
+ */
+export type ShapeStyle =
+  | 'xcross'
+  | 'cross'
+  | 'triangleup'
+  | 'triangledown'
+  | 'flag'
+  | 'circle'
+  | 'arrowup'
+  | 'arrowdown'
+  | 'labelup'
+  | 'labeldown'
+  | 'square'
+  | 'diamond';
+
+/**
+ * One marker emitted by plotshape()/plotchar() on a bar where the condition held
+ */
+export interface MarkerData {
+  /** Time of the bar the marker is displayed on (offset already applied) */
+  time: any;
+  /** Id of the plotshape/plotchar declaration that produced it */
+  id: string;
+  /** Marker location relative to the bar */
+  location: MarkerLocation;
+  /** Shape style, or 'char' for plotchar markers */
+  style: ShapeStyle | 'char';
+  /** Character (plotchar only) */
+  char?: string;
+  /** Marker color */
+  color?: string;
+  /** Text shown near the marker */
+  text?: string;
+  /** Text color */
+  textcolor?: string;
+  /** Marker size */
+  size?: MarkerSize;
+  /** Hover tooltip (extension over PineScript plotshape, used by label.new ports) */
+  tooltip?: string;
+  /** Price for location 'absolute' (the series value on that bar) */
+  price?: number;
+}
+
+/**
+ * Per-bar arrow from plotarrow(): up arrow for a positive value, down arrow for a negative value
+ */
+export interface ArrowData {
+  /** Time of the bar the arrow is displayed on (offset already applied) */
+  time: any;
+  /** Id of the plotarrow declaration that produced it */
+  id: string;
+  /** Series value (non-zero): its sign gives the direction, its absolute value the height */
+  value: number;
+  /** Arrow color (colorup or colordown of that bar) */
+  color: string;
+}
+
+/**
+ * Per-bar color for bgcolor()/barcolor() output
+ */
+export interface BarColorData {
+  /** Time of the colored bar (offset already applied) */
+  time: any;
+  /** Color */
+  color: string;
+}
+
+/**
+ * Complete indicator calculation result
+ */
+export interface IndicatorResult {
+  /** Indicator metadata */
+  metadata: IndicatorMetadata;
+  /** Plot data as Record mapping plot IDs to TimeValue arrays */
+  plots: Record<string, TimeValue[]>;
+  /** Horizontal lines */
+  hlines?: HLineData[];
+  /** Fills */
+  fills?: FillData[];
+  /** Markers from plotshape()/plotchar() */
+  markers?: MarkerData[];
+  /** Arrows from plotarrow() */
+  arrows?: ArrowData[];
+  /** Background colors from bgcolor() */
+  bgcolors?: BarColorData[];
+  /** Bar colors from barcolor() */
+  barcolors?: BarColorData[];
+}
+
+/**
+ * Indicator factory function type
+ */
+export type IndicatorFactory = (options?: Record<string, any>) => {
+  /** Indicator metadata */
+  metadata: IndicatorMetadata;
+  /** Calculate function */
+  calculate: (bars: any[]) => PlotData[] | TimeValue[];
+};

package/src/utils/index.ts

@@ -0,0 +1,334 @@
+/**
+ * Utility functions for OakScriptJS
+ * These are internal helpers and not part of the PineScript API
+ */
+
+import type { series_float, int, float, Source, Bar, OHLC } from '../types/index.js';
+import { sma, ema, wma, rma } from '../ta/index.js';
+import { Series } from '../runtime/series.js';
+import { isDeleted } from '../drawing/registry.js';
+
+/**
+ * Validates that a series has sufficient data for a given length
+ */
+export function validateSeriesLength(source: Source, length: int, functionName: string): void {
+  if (source.length < length) {
+    console.warn(`${functionName}: Source length (${source.length}) is less than required length (${length})`);
+  }
+}
+
+/**
+ * Creates a series filled with NaN values
+ */
+export function createNaNSeries(length: int): series_float {
+  return new Array(length).fill(NaN);
+}
+
+/**
+ * Checks if a value is `na`: NaN, null, undefined, +/-Infinity, or a deleted drawing object
+ * (as in PineScript, `na(l)` is true after `line.delete(l)`, and `na(1 / 0)` is true).
+ */
+export function isNA(value: any): boolean {
+  return (
+    value === null ||
+    value === undefined ||
+    Number.isNaN(value) ||
+    value === Infinity ||
+    value === -Infinity ||
+    isDeleted(value)
+  );
+}
+
+/**
+ * Returns the value or a default if it's NA
+ */
+export function nz(value: any, defaultValue: any = 0): any {
+  return isNA(value) ? defaultValue : value;
+}
+
+/**
+ * PineScript `fixnan(source)`: replaces each `na` value (NaN, null or undefined) with the
+ * previous non-`na` value. Values before the first non-`na` value stay `na`.
+ * Works for numeric series and for color series (arrays of color strings with `undefined` for `na`).
+ */
+export function fixnan<T>(source: T[]): T[] {
+  let last: T | undefined;
+  let seen = false;
+  return source.map((v) => {
+    // PineScript fixnan keeps +/-Infinity (only NaN / null / undefined are replaced)
+    if (!(v === null || v === undefined || Number.isNaN(v) || isDeleted(v))) {
+      last = v;
+      seen = true;
+      return v;
+    }
+    return seen ? (last as T) : v;
+  });
+}
+
+/**
+ * PineScript history reference `x[offset]` at bar `i` of an array: the value `offset` bars back,
+ * `na` (NaN) before the first bar. A negative offset (a later bar) throws, as in PineScript.
+ */
+export function at(source: ArrayLike<number>, i: int, offset: int = 0): float {
+  if (offset < 0) {
+    throw new RangeError(`at(): the offset must be >= 0 (got ${offset}); a negative offset reads a later bar.`);
+  }
+  const j = i - offset;
+  return j >= 0 && j < source.length ? (source[j] ?? NaN) : NaN;
+}
+
+/**
+ * PineScript division: `a / 0` is +/-Infinity (0 / 0 is NaN), as in JavaScript. PineScript keeps the infinite value
+ * in comparisons (`1 / 0 > 0` is true) and treats it as `na` in `na()`, `nz()` and plots.
+ */
+export function div(a: float, b: float): float {
+  return a / b;
+}
+
+/**
+ * Ensures a value is within bounds
+ */
+export function clamp(value: float, min: float, max: float): float {
+  return Math.max(min, Math.min(max, value));
+}
+
+/**
+ * Linear interpolation
+ */
+export function lerp(start: float, end: float, t: float): float {
+  return start + (end - start) * t;
+}
+
+/**
+ * Normalize a value from one range to another
+ */
+export function normalize(value: float, min: float, max: float, newMin: float = 0, newMax: float = 1): float {
+  return newMin + ((value - min) * (newMax - newMin)) / (max - min);
+}
+
+// ===== Chart Data Utilities =====
+// These functions help convert between bar arrays and OHLC data structures
+
+/**
+ * Creates OHLC data from bar array
+ * @param bars - Array of bar data
+ * @returns OHLC data structure
+ */
+export function ohlcFromBars(bars: Bar[]): OHLC {
+  return {
+    open: bars.map(b => b.open),
+    high: bars.map(b => b.high),
+    low: bars.map(b => b.low),
+    close: bars.map(b => b.close),
+  };
+}
+
+/**
+ * Gets close prices from OHLC
+ * @param ohlc - OHLC data
+ * @returns Close price series
+ */
+export function getClose(ohlc: OHLC): series_float {
+  return ohlc.close;
+}
+
+/**
+ * Gets high prices from OHLC
+ * @param ohlc - OHLC data
+ * @returns High price series
+ */
+export function getHigh(ohlc: OHLC): series_float {
+  return ohlc.high;
+}
+
+/**
+ * Gets low prices from OHLC
+ * @param ohlc - OHLC data
+ * @returns Low price series
+ */
+export function getLow(ohlc: OHLC): series_float {
+  return ohlc.low;
+}
+
+/**
+ * Gets open prices from OHLC
+ * @param ohlc - OHLC data
+ * @returns Open price series
+ */
+export function getOpen(ohlc: OHLC): series_float {
+  return ohlc.open;
+}
+
+// ===== Source Extraction Utilities =====
+
+/**
+ * Extract a specific source from OHLC data or bar array
+ *
+ * @param data - Bar array or OHLC data
+ * @param source - Source type: 'close', 'open', 'high', 'low', 'hl2', 'hlc3', 'ohlc4'
+ * @returns Series of the requested source
+ *
+ * @example
+ * ```typescript
+ * const bars = [{ open: 100, high: 105, low: 98, close: 102 }, ...];
+ * const closes = getSource(bars, 'close'); // [102, ...]
+ * const hl2 = getSource(bars, 'hl2'); // [(105+98)/2, ...]
+ * ```
+ */
+export function getSource(
+  data: Bar[] | OHLC,
+  source: 'close' | 'open' | 'high' | 'low' | 'hl2' | 'hlc3' | 'ohlc4' | 'hlcc4' = 'close'
+): series_float {
+  // Check if data is OHLC structure
+  const isOHLC = 'open' in data && Array.isArray(data.open);
+
+  if (isOHLC) {
+    const ohlc = data as OHLC;
+    switch (source) {
+      case 'close': return ohlc.close;
+      case 'open': return ohlc.open;
+      case 'high': return ohlc.high;
+      case 'low': return ohlc.low;
+      case 'hl2': return ohlc.high.map((h, i) => (h + ohlc.low[i]!) / 2);
+      case 'hlc3': return ohlc.high.map((h, i) => (h + ohlc.low[i]! + ohlc.close[i]!) / 3);
+      case 'ohlc4': return ohlc.open.map((o, i) => (o + ohlc.high[i]! + ohlc.low[i]! + ohlc.close[i]!) / 4);
+      case 'hlcc4': return ohlc.high.map((h, i) => (h + ohlc.low[i]! + ohlc.close[i]! + ohlc.close[i]!) / 4);
+    }
+  } else {
+    const bars = data as Bar[];
+    switch (source) {
+      case 'close': return bars.map(b => b.close);
+      case 'open': return bars.map(b => b.open);
+      case 'high': return bars.map(b => b.high);
+      case 'low': return bars.map(b => b.low);
+      case 'hl2': return bars.map(b => (b.high + b.low) / 2);
+      case 'hlc3': return bars.map(b => (b.high + b.low + b.close) / 3);
+      case 'ohlc4': return bars.map(b => (b.open + b.high + b.low + b.close) / 4);
+      case 'hlcc4': return bars.map(b => (b.high + b.low + b.close + b.close) / 4);
+    }
+  }
+}
+
+/**
+ * Creates a Series from bars based on the specified source type.
+ * Unlike getSource() which returns number[], this returns a Series
+ * with chainable methods like .add(), .sub(), .mul(), .div()
+ *
+ * @param bars - Array of bar data
+ * @param source - Source type (default: 'close')
+ * @returns Series object for the requested source
+ *
+ * @example
+ * ```typescript
+ * const bars = [{ time: 1, open: 100, high: 105, low: 98, close: 102, volume: 1000 }, ...];
+ * const source = getSourceSeries(bars, 'hlc3');
+ * const smaResult = ta.sma(source, 14);
+ * ```
+ */
+export function getSourceSeries(
+  bars: Bar[],
+  source: 'open' | 'high' | 'low' | 'close' | 'hl2' | 'hlc3' | 'ohlc4' | 'hlcc4' = 'close'
+): Series {
+  const open = new Series(bars, (bar) => bar.open);
+  const high = new Series(bars, (bar) => bar.high);
+  const low = new Series(bars, (bar) => bar.low);
+  const close = new Series(bars, (bar) => bar.close);
+
+  switch (source) {
+    case 'open': return open;
+    case 'high': return high;
+    case 'low': return low;
+    case 'close': return close;
+    case 'hl2': return high.add(low).div(2);
+    case 'hlc3': return high.add(low).add(close).div(3);
+    case 'ohlc4': return open.add(high).add(low).add(close).div(4);
+    case 'hlcc4': return high.add(low).add(close).add(close).div(4);
+    default: return close;
+  }
+}
+
+// ===== Series Manipulation Utilities =====
+
+/**
+ * Shift (offset) a series forward or backward in time
+ *
+ * @param series - Series to shift
+ * @param offset - Number of bars to shift (positive = forward/right, negative = backward/left)
+ * @returns Shifted series with NaN padding
+ *
+ * @example
+ * ```typescript
+ * const values = [1, 2, 3, 4, 5];
+ * shift(values, 2);  // [NaN, NaN, 1, 2, 3]  (shift forward)
+ * shift(values, -2); // [3, 4, 5, NaN, NaN]  (shift backward)
+ * ```
+ */
+export function shift(series: series_float, offset: int): series_float {
+  if (offset === 0) return series;
+
+  if (offset > 0) {
+    // Shift forward: add NaN at start, remove from end
+    return Array(offset).fill(NaN).concat(series.slice(0, -offset));
+  } else {
+    // Shift backward: remove from start, add NaN at end
+    return series.slice(-offset).concat(Array(-offset).fill(NaN));
+  }
+}
+
+/**
+ * Apply smoothing to a series using a specified method
+ *
+ * @param series - Series to smooth
+ * @param method - Smoothing method: 'SMA', 'EMA', 'WMA', 'RMA'
+ * @param length - Smoothing length
+ * @returns Smoothed series
+ *
+ * @example
+ * ```typescript
+ * const values = [10, 11, 12, 13, 14];
+ * const smoothed = smooth(values, 'EMA', 3);
+ * ```
+ *
+ * @remarks
+ * This is a convenience function that delegates to the appropriate ta function.
+ * Import this from utils, not from ta namespace.
+ */
+export function smooth(
+  series: series_float,
+  method: 'SMA' | 'EMA' | 'WMA' | 'RMA',
+  length: int
+): series_float {
+  switch (method.toUpperCase()) {
+    case 'SMA': return sma(series, length);
+    case 'EMA': return ema(series, length);
+    case 'WMA': return wma(series, length);
+    case 'RMA': return rma(series, length);
+    default:
+      throw new Error(`Unknown smoothing method: ${method}`);
+  }
+}
+
+/**
+ * Format series values with timestamps for output
+ *
+ * @param values - Series of values to format
+ * @param timestamps - Array of timestamps (optional)
+ * @returns Array of objects with time and value properties
+ *
+ * @example
+ * ```typescript
+ * const values = [100, 101, NaN, 103];
+ * const times = [1, 2, 3, 4];
+ * const formatted = formatOutput(values, times);
+ * // [{ time: 1, value: 100 }, { time: 2, value: 101 }, { time: 3, value: null }, { time: 4, value: 103 }]
+ * ```
+ */
+export function formatOutput(
+  values: series_float,
+  timestamps?: number[]
+): Array<{ time: number; value: number | null }> {
+  return values.map((value, index) => ({
+    time: timestamps ? timestamps[index]! : index,
+    value: isNaN(value) ? null : value
+  }));
+}