oakscriptjs 0.8.1 → 0.9.0

package/src/plot.ts

@@ -0,0 +1,121 @@
+/**
+ * @fileoverview Plot helper functions for indicator visualization
+ * These functions help format and prepare data for plotting.
+ * @module plot
+ */
+
+/**
+ * Time value type (can be number timestamp or string date)
+ */
+export type Time = number | string;
+
+/**
+ * Time-value pair for chart data
+ */
+export interface TimeValuePair {
+  /** Time (timestamp or date string) */
+  time: Time;
+  /** Value at this time point */
+  value: number;
+}
+
+/**
+ * Options for plot function
+ */
+export interface PlotOptions {
+  /** Plot color */
+  color?: string;
+  /** Display title */
+  title?: string;
+  /** Line width (1-4) */
+  lineWidth?: number;
+  /** Line style */
+  lineStyle?: 'solid' | 'dashed' | 'dotted';
+  /** Offset from current bar */
+  offset?: number;
+}
+
+/**
+ * Prepare values for plotting by combining with time data
+ * 
+ * @param values - Array of values to plot (null values create gaps)
+ * @param times - Array of time values corresponding to each value
+ * @param options - Plot options (color, title, lineWidth, etc.)
+ * @returns Array of time-value pairs ready for charting
+ * 
+ * @example
+ * ```typescript
+ * const smaValues = ta.sma(ctx.close, 14);
+ * const plotData = plot(smaValues, ctx.time, { color: '#2196F3', title: 'SMA' });
+ * // Returns: [{ time: 1000, value: 100.5 }, { time: 2000, value: 101.2 }, ...]
+ * ```
+ */
+export function plot(
+  values: (number | null)[],
+  times: Time[],
+  options: PlotOptions = {}
+): TimeValuePair[] {
+  const result: TimeValuePair[] = [];
+  const offset = options.offset ?? 0;
+
+  for (let i = 0; i < values.length; i++) {
+    const value = values[i];
+    const timeIndex = i + offset;
+    
+    // Skip null/undefined/NaN values (creates gaps in the chart)
+    if (value === null || value === undefined || Number.isNaN(value)) {
+      continue;
+    }
+
+    // Skip if time index is out of bounds
+    if (timeIndex < 0 || timeIndex >= times.length) {
+      continue;
+    }
+
+    const time = times[timeIndex];
+    if (time !== undefined) {
+      result.push({ time, value });
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Plot result with metadata
+ */
+export interface PlotResult {
+  /** Plot identifier */
+  id: string;
+  /** Time-value data pairs */
+  data: TimeValuePair[];
+  /** Plot options */
+  options: PlotOptions;
+}
+
+/**
+ * Create a named plot with data and options
+ * 
+ * @param id - Unique identifier for this plot
+ * @param values - Array of values to plot
+ * @param times - Array of time values
+ * @param options - Plot options
+ * @returns PlotResult with id, data, and options
+ * 
+ * @example
+ * ```typescript
+ * const smaPlot = createPlot('sma', smaValues, ctx.time, { color: '#2196F3' });
+ * ```
+ */
+export function createPlot(
+  id: string,
+  values: (number | null)[],
+  times: Time[],
+  options: PlotOptions = {}
+): PlotResult {
+  return {
+    id,
+    data: plot(values, times, options),
+    options,
+  };
+}

package/src/polyline/index.ts

@@ -0,0 +1,184 @@
+/**
+ * Polyline namespace
+ * Functions for creating and manipulating polyline drawing objects.
+ *
+ * @remarks
+ * Polylines allow connecting multiple points with line segments, enabling complex chart drawings
+ * like trend channels, patterns, and custom shapes. This implementation focuses on basic
+ * polylines (straight lines) - curved polylines can be added in a future iteration.
+ *
+ * @version 6
+ */
+
+import type { ChartPoint, Polyline, color } from '../types/index.js';
+import { all as allDrawings, register, remove } from '../drawing/registry.js';
+
+// Re-export the Polyline type for convenience
+export type { Polyline };
+
+// Internal counter for generating unique IDs
+let polylineIdCounter = 0;
+
+/**
+ * Generates a unique ID for a polyline
+ */
+function generateId(): string {
+  return `polyline_${++polylineIdCounter}`;
+}
+
+/**
+ * Creates a new polyline connecting all points.
+ *
+ * @param points - Array of chart.point objects to connect
+ * @param curved - If true, use curved line segments (default: false, NOT YET SUPPORTED)
+ * @param closed - If true, connect first point to last point (default: false)
+ * @param xloc - X-coordinate mode: 'bar_index' or 'bar_time' (default: 'bar_index')
+ * @param line_color - Color of line segments (default: '#2196F3' - blue)
+ * @param fill_color - Fill color for closed polylines (default: null)
+ * @param line_style - Line style (default: 'solid')
+ * @param line_width - Line width in pixels (default: 1)
+ * @param force_overlay - Force display on main pane (default: false)
+ * @returns New Polyline object
+ *
+ * @remarks
+ * - The curved parameter is accepted but currently logs a warning as curved lines
+ *   are not yet supported. Straight-line connections are used instead.
+ * - For meaningful polylines, provide at least 2 points.
+ * - Closed polylines can be filled with a color by setting fill_color.
+ *
+ * @example
+ * ```typescript
+ * import { chartPoint, polyline } from 'oakscriptjs';
+ *
+ * // Create points
+ * const points = [
+ *   chartPoint.from_index(0, 100),
+ *   chartPoint.from_index(10, 120),
+ *   chartPoint.from_index(20, 110)
+ * ];
+ *
+ * // Create a basic polyline
+ * const myPolyline = polyline.new(points);
+ *
+ * // Create a closed polygon with fill
+ * const polygon = polyline.new(
+ *   points,
+ *   false,           // curved
+ *   true,            // closed
+ *   'bar_index',     // xloc
+ *   '#FF5722',       // line_color
+ *   'rgba(255, 87, 34, 0.3)'  // fill_color
+ * );
+ * ```
+ */
+export function new_polyline(
+  points: ChartPoint[],
+  curved: boolean = false,
+  closed: boolean = false,
+  xloc: 'bar_index' | 'bar_time' = 'bar_index',
+  line_color: color = '#2196F3',
+  fill_color: color | null = null,
+  line_style: 'solid' | 'dotted' | 'dashed' = 'solid',
+  line_width: number = 1,
+  force_overlay: boolean = false
+): Polyline {
+  // Warn about curved polylines not being supported yet
+  if (curved) {
+    console.warn(
+      'polyline.new(): curved polylines are not yet supported. Using straight-line connections.'
+    );
+  }
+
+  // Validate line_width is positive
+  if (line_width < 1) {
+    console.warn('polyline.new(): line_width must be at least 1. Using 1.');
+    line_width = 1;
+  }
+
+  const polyline: Polyline = {
+    id: generateId(),
+    points: [...points], // Create a copy of the points array
+    curved,
+    closed,
+    xloc,
+    line_color,
+    fill_color,
+    line_style,
+    line_width,
+    force_overlay,
+  };
+
+  return register('polyline', polyline);
+}
+
+/**
+ * Deletes a polyline.
+ *
+ * @param id - Polyline object to delete
+ *
+ * @remarks
+ * Removes the polyline from `polyline.all()` (the drawing registry, see drawing/registry).
+ *
+ * @example
+ * ```typescript
+ * const myPolyline = polyline.new(points);
+ * polyline.delete(myPolyline);
+ * ```
+ */
+export function delete_polyline(id: Polyline): void {
+  remove('polyline', id);
+}
+
+/**
+ * Gets all active polylines.
+ *
+ * @returns Array of all active polylines
+ *
+ * @remarks
+ * Returns a copy of the internal polylines array to prevent external modification.
+ *
+ * @example
+ * ```typescript
+ * console.log('Total polylines:', polyline.all.length);
+ *
+ * for (const p of polyline.all) {
+ *   console.log('Polyline ID:', p.id, 'Points:', p.points.length);
+ * }
+ * ```
+ */
+export function get_all(): readonly Polyline[] {
+  return allDrawings('polyline');
+}
+
+/**
+ * All live polylines, in creation order (PineScript `polyline.all`). A new array.
+ */
+export function all(): Polyline[] {
+  return allDrawings('polyline');
+}
+
+/**
+ * Deletes all polylines.
+ *
+ * @remarks
+ * This is useful for resetting state, especially in tests.
+ * Not part of the PineScript API.
+ */
+export function clear_all(): void {
+  for (const p of allDrawings('polyline')) remove('polyline', p);
+}
+
+/**
+ * Resets the polyline ID counter.
+ *
+ * @remarks
+ * This is useful for resetting state, especially in tests.
+ * Not part of the PineScript API.
+ */
+export function reset_id_counter(): void {
+  polylineIdCounter = 0;
+}
+
+// Aliases to match PineScript API
+export { new_polyline as new };
+export { delete_polyline as delete };

package/src/runtime/adapters/LightweightChartsAdapter.ts

@@ -0,0 +1,201 @@
+/**
+ * @fileoverview Lightweight-charts v5 adapter
+ * Provides integration with lightweight-charts library
+ * @module runtime/adapters/LightweightChartsAdapter
+ */
+
+import type { ChartAdapter, SeriesHandle, SeriesOptions } from '../types.js';
+
+/**
+ * Minimal interface for lightweight-charts chart API
+ * Only includes methods used by this adapter
+ */
+interface LightweightChart {
+  addSeries<T>(seriesDefinition: unknown, options?: unknown, paneIndex?: number): LightweightSeries<T>;
+  removeSeries(series: LightweightSeries<unknown>): void;
+  panes(): unknown[];
+}
+
+/**
+ * Minimal interface for lightweight-charts series
+ */
+interface LightweightSeries<T> {
+  setData(data: T[]): void;
+}
+
+/**
+ * Data point format for lightweight-charts
+ */
+interface TimeValueData {
+  time: number;
+  value: number;
+  color?: string;
+}
+
+/**
+ * The lightweight-charts v5 series definitions the adapter creates series with. Pass the library's own exports
+ * (`import { LineSeries, HistogramSeries } from 'lightweight-charts'`, or the whole module): OakScriptJS does not
+ * import lightweight-charts itself. `LineSeries` is required; the others are needed only for the series types used.
+ */
+export interface LightweightSeriesDefinitions {
+  LineSeries: unknown;
+  HistogramSeries?: unknown;
+  AreaSeries?: unknown;
+  BaselineSeries?: unknown;
+  BarSeries?: unknown;
+}
+
+/**
+ * Adapter for lightweight-charts v5
+ * Translates OakScriptJS chart operations into lightweight-charts API calls
+ *
+ * @example
+ * ```typescript
+ * import { createChart, CandlestickSeries, LineSeries, HistogramSeries } from 'lightweight-charts';
+ *
+ * const chart = createChart(container);
+ * const candles = chart.addSeries(CandlestickSeries);
+ * const adapter = new LightweightChartsAdapter(chart, { LineSeries, HistogramSeries }, candles);
+ * ```
+ */
+export class LightweightChartsAdapter implements ChartAdapter {
+  private chart: LightweightChart;
+  private definitions: LightweightSeriesDefinitions;
+  private mainSeries: SeriesHandle | undefined;
+  private paneCount: number = 0;
+
+  /**
+   * Create a new LightweightChartsAdapter
+   * @param chart - The lightweight-charts chart instance
+   * @param definitions - The lightweight-charts series definitions (`LineSeries`, `HistogramSeries`...)
+   * @param mainSeries - Optional main price series (candlestick/line series)
+   */
+  constructor(chart: unknown, definitions: LightweightSeriesDefinitions, mainSeries?: unknown) {
+    if (!definitions?.LineSeries) {
+      throw new Error(
+        'LightweightChartsAdapter: pass the lightweight-charts series definitions, ' +
+          "e.g. new LightweightChartsAdapter(chart, { LineSeries, HistogramSeries }) with the imports from 'lightweight-charts'."
+      );
+    }
+    this.chart = chart as LightweightChart;
+    this.definitions = definitions;
+    if (mainSeries) {
+      this.mainSeries = this.wrapSeries(mainSeries as LightweightSeries<TimeValueData>);
+    }
+  }
+
+  /**
+   * Wrap a lightweight-charts series to implement SeriesHandle
+   * @param lwcSeries - The lightweight-charts series
+   * @returns SeriesHandle wrapper
+   */
+  private wrapSeries(lwcSeries: LightweightSeries<TimeValueData>): SeriesHandle {
+    return {
+      setData: (data: Array<{ time: number; value: number; color?: string }>) => {
+        lwcSeries.setData(data);
+      },
+      // Store reference for removal
+      _lwcSeries: lwcSeries,
+    } as SeriesHandle & { _lwcSeries: LightweightSeries<TimeValueData> };
+  }
+
+  /**
+   * Map series type string to lightweight-charts series definition
+   * @param type - Series type ('line', 'histogram', 'area', 'baseline', 'bar')
+   * @returns Lightweight-charts series definition
+   * @throws When the definition of that series type was not given to the constructor
+   */
+  private getSeriesDefinition(type: string): unknown {
+    const key = (
+      {
+        histogram: 'HistogramSeries',
+        area: 'AreaSeries',
+        baseline: 'BaselineSeries',
+        bar: 'BarSeries',
+      } as const
+    )[type as 'histogram' | 'area' | 'baseline' | 'bar'] ?? 'LineSeries';
+    const definition = this.definitions[key];
+    if (!definition) {
+      throw new Error(`LightweightChartsAdapter: a '${type}' series needs ${key}; pass it in the constructor definitions.`);
+    }
+    return definition;
+  }
+
+  /**
+   * Convert OakScriptJS series options to lightweight-charts options
+   * @param options - OakScriptJS series options
+   * @returns Lightweight-charts compatible options
+   */
+  private convertOptions(options?: SeriesOptions): Record<string, unknown> {
+    if (!options) {
+      return {};
+    }
+
+    const lwcOptions: Record<string, unknown> = {};
+
+    if (options.color) {
+      lwcOptions.color = options.color;
+    }
+
+    if (options.lineWidth !== undefined) {
+      lwcOptions.lineWidth = options.lineWidth;
+    }
+
+    if (options.lineStyle !== undefined) {
+      lwcOptions.lineStyle = options.lineStyle;
+    }
+
+    if (options.priceScaleId) {
+      lwcOptions.priceScaleId = options.priceScaleId;
+    }
+
+    return lwcOptions;
+  }
+
+  /**
+   * Add a new series to the chart
+   * @param type - Series type ('line', 'histogram', 'area', 'baseline', 'bar')
+   * @param options - Series options (`pane` is the lightweight-charts pane index)
+   * @returns SeriesHandle for the new series
+   */
+  addSeries(type: string, options?: SeriesOptions): SeriesHandle {
+    const seriesDefinition = this.getSeriesDefinition(type);
+    const lwcOptions = this.convertOptions(options);
+
+    const lwcSeries =
+      options?.pane !== undefined
+        ? this.chart.addSeries<TimeValueData>(seriesDefinition, lwcOptions, options.pane)
+        : this.chart.addSeries<TimeValueData>(seriesDefinition, lwcOptions);
+    return this.wrapSeries(lwcSeries);
+  }
+
+  /**
+   * Remove a series from the chart
+   * @param series - SeriesHandle to remove
+   */
+  removeSeries(series: SeriesHandle): void {
+    const wrappedSeries = series as SeriesHandle & { _lwcSeries?: LightweightSeries<unknown> };
+    if (wrappedSeries._lwcSeries) {
+      this.chart.removeSeries(wrappedSeries._lwcSeries);
+    }
+  }
+
+  /**
+   * Get the main price series
+   * @returns Main series handle or undefined
+   */
+  getMainSeries(): SeriesHandle | undefined {
+    return this.mainSeries;
+  }
+
+  /**
+   * Create a new pane (if supported by the chart configuration)
+   * @returns Index of the new pane
+   */
+  createPane(): number {
+    // Lightweight-charts v5 doesn't have a direct createPane API
+    // Panes are typically created via chart configuration
+    // This returns an incremented pane count for reference
+    return ++this.paneCount;
+  }
+}

package/src/runtime/adapters/SimpleInputAdapter.ts

@@ -0,0 +1,132 @@
+/**
+ * @fileoverview Simple in-memory input adapter for demos and testing
+ * Stores input values in memory and provides change notification
+ * @module runtime/adapters/SimpleInputAdapter
+ */
+
+import type { InputAdapter, InputConfig } from '../types.js';
+
+/**
+ * Simple in-memory input adapter
+ * Stores input configurations and values in memory
+ * Useful for demos, testing, and simple applications
+ */
+export class SimpleInputAdapter implements InputAdapter {
+  private inputs: Map<string, { config: InputConfig; value: unknown }> = new Map();
+  private changeCallbacks: Array<(id: string, value: unknown) => void> = [];
+
+  /**
+   * Register an input configuration
+   * If already registered, returns current value without modifying config
+   * @param config - Input configuration
+   * @returns Current value (defval on first registration)
+   */
+  registerInput(config: InputConfig): unknown {
+    if (!this.inputs.has(config.id)) {
+      this.inputs.set(config.id, { config, value: config.defval });
+    }
+    return this.inputs.get(config.id)!.value;
+  }
+
+  /**
+   * Get current value of an input
+   * @param id - Input identifier
+   * @returns Current value or undefined if not registered
+   */
+  getValue(id: string): unknown {
+    return this.inputs.get(id)?.value;
+  }
+
+  /**
+   * Set value of an input with validation
+   * Validates against config constraints (min/max/step for numerics, options for strings)
+   * @param id - Input identifier
+   * @param value - New value
+   */
+  setValue(id: string, value: unknown): void {
+    const input = this.inputs.get(id);
+    if (!input) {
+      return;
+    }
+
+    const { config } = input;
+    let validatedValue = value;
+
+    // Validate numeric inputs
+    if ((config.type === 'int' || config.type === 'float') && typeof value === 'number') {
+      // Apply min constraint
+      if (config.min !== undefined && value < config.min) {
+        validatedValue = config.min;
+      }
+      // Apply max constraint
+      if (config.max !== undefined && value > config.max) {
+        validatedValue = config.max;
+      }
+      // Round to step for int type
+      if (config.type === 'int') {
+        validatedValue = Math.floor(validatedValue as number);
+      }
+    }
+
+    // Validate string, timeframe and session inputs with options
+    if (
+      (config.type === 'string' || config.type === 'timeframe' || config.type === 'session') &&
+      config.options &&
+      typeof value === 'string'
+    ) {
+      if (!config.options.includes(value)) {
+        // Keep current value if invalid option
+        return;
+      }
+    }
+
+    // Validate source inputs
+    if (config.type === 'source' && config.options && typeof value === 'string') {
+      if (!config.options.includes(value)) {
+        return;
+      }
+    }
+
+    // Update value
+    input.value = validatedValue;
+
+    // Notify callbacks
+    this.changeCallbacks.forEach(cb => cb(id, validatedValue));
+  }
+
+  /**
+   * Register a callback for input value changes
+   * @param callback - Function to call when any input value changes
+   */
+  onInputChange(callback: (id: string, value: unknown) => void): void {
+    this.changeCallbacks.push(callback);
+  }
+
+  /**
+   * Get all registered inputs (for UI rendering)
+   * @returns Map of input IDs to their configs and values
+   */
+  getAllInputs(): Map<string, { config: InputConfig; value: unknown }> {
+    return new Map(this.inputs);
+  }
+
+  /**
+   * Clear all registered inputs
+   * Useful for testing or resetting state
+   */
+  clear(): void {
+    this.inputs.clear();
+    this.changeCallbacks = [];
+  }
+
+  /**
+   * Remove a specific change callback
+   * @param callback - The callback to remove
+   */
+  removeChangeCallback(callback: (id: string, value: unknown) => void): void {
+    const index = this.changeCallbacks.indexOf(callback);
+    if (index !== -1) {
+      this.changeCallbacks.splice(index, 1);
+    }
+  }
+}

package/src/runtime/index.ts

@@ -0,0 +1,52 @@
+/**
+ * @fileoverview OakScriptJS Runtime Module
+ * Provides global context management, plot functions, and input handling
+ * for indicators that draw through a ChartAdapter
+ * @module runtime
+ */
+
+// Core runtime exports
+export {
+  setContext,
+  clearContext,
+  getContext,
+  registerCalculate,
+  recalculate,
+  plot,
+  hline,
+  clearPlots,
+  getActivePlots,
+} from './runtime.js';
+
+// Input function exports
+export {
+  input_int,
+  input_float,
+  input_bool,
+  input_string,
+  input_source,
+  input_timeframe,
+  input_session,
+  input_time,
+  enableAutoRecalculate,
+  disableAutoRecalculate,
+  resetInputs,
+} from './inputs.js';
+
+// Type exports
+export type {
+  OakScriptContext,
+  ChartAdapter,
+  InputAdapter,
+  SeriesHandle,
+  SeriesOptions,
+  InputConfig,
+  InputOptions,
+  OhlcvData,
+    PlotConfig,
+} from './types.js';
+
+// Adapter exports
+export { LightweightChartsAdapter } from './adapters/LightweightChartsAdapter.js';
+export type { LightweightSeriesDefinitions } from './adapters/LightweightChartsAdapter.js';
+export { SimpleInputAdapter } from './adapters/SimpleInputAdapter.js';