oakscriptjs 0.8.1 → 0.9.0

package/src/runtime/inputs.ts

@@ -0,0 +1,377 @@
+/**
+ * @fileoverview Idempotent input registration functions
+ * These functions mirror PineScript's input functions with idempotent semantics:
+ * - First call registers the input with default value
+ * - Subsequent calls return the current stored value (possibly user-updated)
+ * @module runtime/inputs
+ */
+
+import type { InputConfig, InputOptions } from './types.js';
+import { getContext, recalculate } from './runtime.js';
+
+// Track registered inputs for idempotent registration
+const registeredInputs = new Map<string, boolean>();
+
+// Track if we should auto-recalculate on input change
+let autoRecalculateEnabled = false;
+
+/**
+ * Enable automatic recalculation when inputs change
+ */
+export function enableAutoRecalculate(): void {
+  autoRecalculateEnabled = true;
+}
+
+/**
+ * Disable automatic recalculation
+ */
+export function disableAutoRecalculate(): void {
+  autoRecalculateEnabled = false;
+}
+
+/**
+ * Reset registered inputs (for testing or context changes)
+ * @internal
+ */
+export function resetInputs(): void {
+  registeredInputs.clear();
+  inputCounter = 0;
+}
+
+// Counter for generating unique input IDs when no title is provided
+let inputCounter = 0;
+
+/**
+ * Generate a unique input ID from title or default
+ * @param title - Optional title
+ * @param defval - Default value for fallback
+ * @param type - Input type
+ * @returns Unique input ID
+ */
+function generateInputId(title: string | undefined, defval: unknown, type: string): string {
+  if (title) {
+    return title.replace(/\s+/g, '_');
+  }
+  // Use counter to ensure uniqueness when no title is provided
+  return `${type}_${inputCounter++}_${String(defval)}`;
+}
+
+/**
+ * Register an integer input
+ * First call registers with defval, subsequent calls return current value
+ * @param defval - Default value
+ * @param title - Display title (optional)
+ * @param options - Additional options: min, max, step (optional)
+ * @returns Current integer value
+ */
+export function input_int(defval: number, title?: string, options?: InputOptions): number {
+  const context = getContext();
+  if (!context) {
+    // No context - return default value
+    return Math.floor(defval);
+  }
+
+  const id = generateInputId(title, defval, 'int');
+  const config: InputConfig = {
+    id,
+    type: 'int',
+    defval: Math.floor(defval),
+    title,
+    min: options?.min,
+    max: options?.max,
+    step: options?.step ?? 1,
+  };
+
+  // Check if already registered (idempotent)
+  if (!registeredInputs.has(id)) {
+    // First call - register the input
+    context.inputs.registerInput(config);
+    registeredInputs.set(id, true);
+
+    // Set up auto-recalculate on change if not already done
+    if (autoRecalculateEnabled) {
+      context.inputs.onInputChange((changedId) => {
+        if (changedId === id) {
+          recalculate();
+        }
+      });
+    }
+  }
+
+  // Return current value (may have been updated by user)
+  const value = context.inputs.getValue(id);
+  return typeof value === 'number' ? Math.floor(value) : Math.floor(defval);
+}
+
+/**
+ * Register a float input
+ * First call registers with defval, subsequent calls return current value
+ * @param defval - Default value
+ * @param title - Display title (optional)
+ * @param options - Additional options: min, max, step (optional)
+ * @returns Current float value
+ */
+export function input_float(defval: number, title?: string, options?: InputOptions): number {
+  const context = getContext();
+  if (!context) {
+    // No context - return default value
+    return defval;
+  }
+
+  const id = generateInputId(title, defval, 'float');
+  const config: InputConfig = {
+    id,
+    type: 'float',
+    defval,
+    title,
+    min: options?.min,
+    max: options?.max,
+    step: options?.step ?? 0.1,
+  };
+
+  // Check if already registered (idempotent)
+  if (!registeredInputs.has(id)) {
+    context.inputs.registerInput(config);
+    registeredInputs.set(id, true);
+
+    if (autoRecalculateEnabled) {
+      context.inputs.onInputChange((changedId) => {
+        if (changedId === id) {
+          recalculate();
+        }
+      });
+    }
+  }
+
+  const value = context.inputs.getValue(id);
+  return typeof value === 'number' ? value : defval;
+}
+
+/**
+ * Register a boolean input
+ * First call registers with defval, subsequent calls return current value
+ * @param defval - Default value
+ * @param title - Display title (optional)
+ * @returns Current boolean value
+ */
+export function input_bool(defval: boolean, title?: string): boolean {
+  const context = getContext();
+  if (!context) {
+    return defval;
+  }
+
+  const id = generateInputId(title, defval, 'bool');
+  const config: InputConfig = {
+    id,
+    type: 'bool',
+    defval,
+    title,
+  };
+
+  if (!registeredInputs.has(id)) {
+    context.inputs.registerInput(config);
+    registeredInputs.set(id, true);
+
+    if (autoRecalculateEnabled) {
+      context.inputs.onInputChange((changedId) => {
+        if (changedId === id) {
+          recalculate();
+        }
+      });
+    }
+  }
+
+  const value = context.inputs.getValue(id);
+  return typeof value === 'boolean' ? value : defval;
+}
+
+/**
+ * Register a string input
+ * First call registers with defval, subsequent calls return current value
+ * @param defval - Default value
+ * @param title - Display title (optional)
+ * @param options - Array of string options for dropdown (optional)
+ * @returns Current string value
+ */
+export function input_string(defval: string, title?: string, options?: string[]): string {
+  const context = getContext();
+  if (!context) {
+    return defval;
+  }
+
+  const id = generateInputId(title, defval, 'string');
+  const config: InputConfig = {
+    id,
+    type: 'string',
+    defval,
+    title,
+    options,
+  };
+
+  if (!registeredInputs.has(id)) {
+    context.inputs.registerInput(config);
+    registeredInputs.set(id, true);
+
+    if (autoRecalculateEnabled) {
+      context.inputs.onInputChange((changedId) => {
+        if (changedId === id) {
+          recalculate();
+        }
+      });
+    }
+  }
+
+  const value = context.inputs.getValue(id);
+  return typeof value === 'string' ? value : defval;
+}
+
+/**
+ * Registers `config` once (idempotent) and returns the current stored value.
+ */
+function registerOnce(config: InputConfig): unknown {
+  const context = getContext()!;
+  if (!registeredInputs.has(config.id)) {
+    context.inputs.registerInput(config);
+    registeredInputs.set(config.id, true);
+
+    if (autoRecalculateEnabled) {
+      context.inputs.onInputChange((changedId) => {
+        if (changedId === config.id) {
+          recalculate();
+        }
+      });
+    }
+  }
+  return context.inputs.getValue(config.id);
+}
+
+/**
+ * Register a timeframe input (PineScript `input.timeframe`)
+ * First call registers with defval, subsequent calls return current value
+ * @param defval - Default timeframe string ("60", "1D", "W"); "" means the chart timeframe
+ * @param title - Display title (optional)
+ * @param options - Array of timeframe options for dropdown (optional)
+ * @returns Current timeframe string
+ */
+export function input_timeframe(defval: string, title?: string, options?: string[]): string {
+  if (!getContext()) {
+    return defval;
+  }
+  const value = registerOnce({ id: generateInputId(title, defval, 'timeframe'), type: 'timeframe', defval, title, options });
+  return typeof value === 'string' ? value : defval;
+}
+
+/**
+ * Register a session input (PineScript `input.session`)
+ * First call registers with defval, subsequent calls return current value
+ * @param defval - Default session string ("0930-1600", "0930-1600:23456")
+ * @param title - Display title (optional)
+ * @param options - Array of session options for dropdown (optional)
+ * @returns Current session string
+ */
+export function input_session(defval: string, title?: string, options?: string[]): string {
+  if (!getContext()) {
+    return defval;
+  }
+  const value = registerOnce({ id: generateInputId(title, defval, 'session'), type: 'session', defval, title, options });
+  return typeof value === 'string' ? value : defval;
+}
+
+/**
+ * Register a date/time input (PineScript `input.time`)
+ * First call registers with defval, subsequent calls return current value
+ * @param defval - Default UNIX time in milliseconds, e.g. `time.timestamp("2024-01-01")`
+ * @param title - Display title (optional)
+ * @returns Current UNIX time in milliseconds
+ */
+export function input_time(defval: number, title?: string): number {
+  if (!getContext()) {
+    return defval;
+  }
+  const value = registerOnce({ id: generateInputId(title, defval, 'time'), type: 'time', defval, title });
+  return typeof value === 'number' ? value : defval;
+}
+
+/**
+ * Register a source input (returns a data series from OHLCV)
+ * First call registers with defval, subsequent calls return current value
+ * @param defval - Default source name ('close', 'open', 'high', 'low', 'volume', 'hl2', 'hlc3', 'ohlc4')
+ * @param title - Display title (optional)
+ * @returns Array of values for the selected source
+ */
+export function input_source(defval: string, title?: string): number[] {
+  const context = getContext();
+  if (!context) {
+    return [];
+  }
+
+  const id = generateInputId(title, defval, 'source');
+  const config: InputConfig = {
+    id,
+    type: 'source',
+    defval,
+    title,
+    options: ['open', 'high', 'low', 'close', 'volume', 'hl2', 'hlc3', 'ohlc4'],
+  };
+
+  if (!registeredInputs.has(id)) {
+    context.inputs.registerInput(config);
+    registeredInputs.set(id, true);
+
+    if (autoRecalculateEnabled) {
+      context.inputs.onInputChange((changedId) => {
+        if (changedId === id) {
+          recalculate();
+        }
+      });
+    }
+  }
+
+  const sourceName = (context.inputs.getValue(id) as string) ?? defval;
+  
+  return getSourceData(context.ohlcv, sourceName);
+}
+
+/**
+ * Get data array for a source name
+ * @param ohlcv - OHLCV data
+ * @param sourceName - Source name
+ * @returns Array of values
+ */
+function getSourceData(
+  ohlcv: { open: number[]; high: number[]; low: number[]; close: number[]; volume: number[] },
+  sourceName: string
+): number[] {
+  switch (sourceName) {
+    case 'open':
+      return ohlcv.open;
+    case 'high':
+      return ohlcv.high;
+    case 'low':
+      return ohlcv.low;
+    case 'close':
+      return ohlcv.close;
+    case 'volume':
+      return ohlcv.volume;
+    case 'hl2':
+      return ohlcv.high.map((h, i) => {
+        const l = ohlcv.low[i];
+        return l !== undefined ? (h + l) / 2 : NaN;
+      });
+    case 'hlc3':
+      return ohlcv.high.map((h, i) => {
+        const l = ohlcv.low[i];
+        const c = ohlcv.close[i];
+        return l !== undefined && c !== undefined ? (h + l + c) / 3 : NaN;
+      });
+    case 'ohlc4':
+      return ohlcv.open.map((o, i) => {
+        const h = ohlcv.high[i];
+        const l = ohlcv.low[i];
+        const c = ohlcv.close[i];
+        return h !== undefined && l !== undefined && c !== undefined ? (o + h + l + c) / 4 : NaN;
+      });
+    default:
+      return ohlcv.close;
+  }
+}

package/src/runtime/runtime.ts

@@ -0,0 +1,241 @@
+/**
+ * @fileoverview OakScriptJS Runtime - Context management and plot functions
+ * This module provides the global runtime context for indicator execution
+ * @module runtime/runtime
+ */
+
+import type { OakScriptContext, SeriesHandle, SeriesOptions } from './types.js';
+
+// Global context state
+let context: OakScriptContext | null = null;
+
+// Registered calculate function for recalculation
+let calculateFn: (() => void) | null = null;
+
+// Track active plots for cleanup
+interface ActivePlot {
+  id: string;
+  series: SeriesHandle;
+}
+
+const activePlots: ActivePlot[] = [];
+
+// Counter for generating unique plot IDs
+let plotCounter = 0;
+
+/**
+ * Set the global OakScript context
+ * Must be called by host application before any indicator calculation
+ * @param ctx - The context object with chart and input adapters
+ */
+export function setContext(ctx: OakScriptContext): void {
+  context = ctx;
+  // Reset plot counter and clear active plots when context changes
+  plotCounter = 0;
+  clearPlots();
+}
+
+/**
+ * Clear the global context
+ * Call when detaching/removing an indicator
+ */
+export function clearContext(): void {
+  clearPlots();
+  context = null;
+  calculateFn = null;
+  plotCounter = 0;
+}
+
+/**
+ * Get the current global context
+ * @returns The current context or null if not set
+ */
+export function getContext(): OakScriptContext | null {
+  return context;
+}
+
+/**
+ * Register the calculate function for recalculation
+ * Indicators call this to enable automatic recalculation on input changes
+ * @param fn - The calculate function to register
+ */
+export function registerCalculate(fn: () => void): void {
+  calculateFn = fn;
+}
+
+/**
+ * Trigger recalculation of the current indicator
+ * Clears existing plots and re-invokes the registered calculate function
+ */
+export function recalculate(): void {
+  if (calculateFn) {
+    clearPlots();
+    plotCounter = 0;
+    calculateFn();
+  }
+}
+
+/**
+ * Clear all active plots from the chart
+ * Called internally before recalculation
+ */
+export function clearPlots(): void {
+  if (context) {
+    for (const plot of activePlots) {
+      try {
+        context.chart.removeSeries(plot.series);
+      } catch {
+        // Ignore errors during cleanup
+      }
+    }
+  }
+  activePlots.length = 0;
+}
+
+/**
+ * Map plot style string to lightweight-charts series type
+ * @param style - Plot style string
+ * @returns Series type string
+ */
+function getSeriesType(style?: string): string {
+  switch (style) {
+    case 'histogram':
+    case 'columns':
+      return 'histogram';
+    case 'area':
+    case 'areabr':
+      return 'area';
+    case 'circles':
+    case 'cross':
+      return 'line'; // Use line with markers
+    default:
+      return 'line';
+  }
+}
+
+/**
+ * Map line style string to numeric value
+ * @param style - Line style string
+ * @returns Numeric line style
+ */
+function getLineStyle(style?: string): number {
+  switch (style) {
+    case 'dotted':
+      return 1;
+    case 'dashed':
+      return 2;
+    case 'solid':
+    default:
+      return 0;
+  }
+}
+
+/**
+ * Plot a series on the chart
+ * @param series - Array of values to plot
+ * @param title - Plot title (optional)
+ * @param color - Plot color (optional)
+ * @param linewidth - Line width (optional)
+ * @param style - Plot style (optional)
+ * @returns Unique plot ID for this plot
+ */
+export function plot(
+  series: number[],
+  title?: string,
+  color?: string,
+  linewidth?: number,
+  style?: string,
+  colors?: string[]
+): string {
+  if (!context) {
+    throw new Error('OakScript context not set. Call setContext() before plotting.');
+  }
+
+  const plotId = `plot_${plotCounter++}${title ? '_' + title.replace(/\s+/g, '_') : ''}`;
+  
+  const seriesType = getSeriesType(style);
+  const options: SeriesOptions = {
+    color: color,
+    lineWidth: linewidth,
+    lineStyle: getLineStyle(style),
+  };
+
+  // Create series on chart
+  const seriesHandle = context.chart.addSeries(seriesType, options);
+  
+  // Convert series data to time-value pairs
+  const data: Array<{ time: number; value: number; color?: string }> = [];
+  for (let index = 0; index < series.length; index++) {
+    const value = series[index];
+    const time = context.ohlcv.time[index];
+    if (time !== undefined && value !== undefined && !Number.isNaN(value)) {
+      const point: { time: number; value: number; color?: string } = { time, value };
+      if (colors && colors[index]) {
+        point.color = colors[index];
+      }
+      data.push(point);
+    }
+  }
+
+  // Set the data
+  seriesHandle.setData(data);
+
+  // Track the plot for cleanup
+  activePlots.push({ id: plotId, series: seriesHandle });
+
+  return plotId;
+}
+
+/**
+ * Draw a horizontal line on the chart
+ * @param price - Y-axis value for the line
+ * @param title - Line title (optional)
+ * @param color - Line color (optional)
+ * @param linestyle - Line style (optional, default dashed as PineScript)
+ * @param linewidth - Line width (optional)
+ * @returns Unique hline ID
+ */
+export function hline(
+  price: number,
+  title?: string,
+  color?: string,
+  linestyle?: string,
+  linewidth?: number
+): string {
+  if (!context) {
+    throw new Error('OakScript context not set. Call setContext() before creating hlines.');
+  }
+
+  const hlineId = `hline_${plotCounter++}${title ? '_' + title.replace(/\s+/g, '_') : ''}`;
+
+  const options: SeriesOptions = {
+    color: color,
+    lineWidth: linewidth,
+    lineStyle: getLineStyle(linestyle ?? 'dashed'),
+  };
+
+  // Create a line series for the hline
+  const seriesHandle = context.chart.addSeries('line', options);
+
+  // Create horizontal line data (constant value across all time points)
+  const data = context.ohlcv.time.map(time => ({
+    time: time,
+    value: price,
+  }));
+
+  seriesHandle.setData(data);
+
+  // Track the hline for cleanup
+  activePlots.push({ id: hlineId, series: seriesHandle });
+
+  return hlineId;
+}
+
+/**
+ * Get the active plots array (for testing purposes)
+ * @returns Array of active plots
+ * @internal
+ */
+export function getActivePlots(): ReadonlyArray<ActivePlot> {
+  return activePlots;
+}