oakscriptjs 0.8.1 → 0.9.0

package/src/drawing/registry.ts

@@ -0,0 +1,106 @@
+/**
+ * Registry of the live drawing objects (lines, labels, boxes, polylines, linefills), as PineScript
+ * keeps them. PineScript rules:
+ *
+ * - `line.all`, `label.all`, ... list the live objects in creation order (a copy of the list)
+ * - `delete` removes an object; the object becomes `na`: its getters return NaN and its setters
+ *   do nothing. Deleting a line with `line.delete` also deletes the linefills that use it
+ * - when a creation brings the count above `max_*_count + 5`, the oldest objects are deleted until
+ *   `max_*_count` remain (default 50). Copies count as creations. Linefills follow the same rule with
+ *   `max_lines_count`; lines deleted by this rule do not delete their linefills
+ *
+ * The script API (`executeScript`) resets the registry at the start of every run and applies the
+ * `max_*_count` values of `indicator()`. Outside a script run the registry is global to the module.
+ *
+ * @module drawing/registry
+ */
+
+import type { Box, Label, Line, Linefill, Polyline } from '../types/index.js';
+
+export type DrawingKind = 'line' | 'label' | 'box' | 'polyline' | 'linefill';
+
+interface DrawingTypes {
+  line: Line;
+  label: Label;
+  box: Box;
+  polyline: Polyline;
+  linefill: Linefill;
+}
+
+/** Default `max_lines_count`, `max_labels_count`, `max_boxes_count`, `max_polylines_count`. */
+export const DEFAULT_MAX_COUNT = 50;
+/** Objects above the maximum that PineScript keeps before it deletes the oldest ones. */
+const SLACK = 5;
+
+export type DrawingLimits = Partial<Record<Exclude<DrawingKind, 'linefill'>, number>>;
+
+const live: { [K in DrawingKind]: Array<DrawingTypes[K]> } = { line: [], label: [], box: [], polyline: [], linefill: [] };
+let limits: Required<DrawingLimits> = {
+  line: DEFAULT_MAX_COUNT,
+  label: DEFAULT_MAX_COUNT,
+  box: DEFAULT_MAX_COUNT,
+  polyline: DEFAULT_MAX_COUNT,
+};
+const deleted = new WeakSet<object>();
+
+/** Numeric fields that become NaN when an object is deleted, so that its getters return `na`. */
+const COORDINATES: { [K in DrawingKind]: Array<keyof DrawingTypes[K]> } = {
+  line: ['x1', 'y1', 'x2', 'y2'],
+  label: ['x', 'y'],
+  box: ['left', 'top', 'right', 'bottom'],
+  polyline: [],
+  linefill: [],
+};
+
+function markDeleted<K extends DrawingKind>(kind: K, obj: DrawingTypes[K], explicit: boolean): void {
+  deleted.add(obj);
+  for (const field of COORDINATES[kind]) (obj as unknown as Record<string, unknown>)[field as string] = NaN;
+  if (kind === 'line' && explicit) {
+    for (const fill of live.linefill.filter((f) => f.line1 === obj || f.line2 === obj)) remove('linefill', fill);
+  }
+}
+
+/** Records a new object and deletes the oldest objects of its kind when the count is too high. */
+export function register<K extends DrawingKind>(kind: K, obj: DrawingTypes[K]): DrawingTypes[K] {
+  const list = live[kind];
+  list.push(obj);
+  const max = limits[kind === 'linefill' ? 'line' : (kind as Exclude<DrawingKind, 'linefill'>)];
+  if (list.length > max + SLACK) {
+    for (const old of list.splice(0, list.length - max)) markDeleted(kind, old, false);
+  }
+  return obj;
+}
+
+/** Deletes an object (no effect when it is already deleted). */
+export function remove<K extends DrawingKind>(kind: K, obj: DrawingTypes[K]): void {
+  const list = live[kind];
+  const index = list.indexOf(obj);
+  if (index !== -1) list.splice(index, 1);
+  if (!deleted.has(obj)) markDeleted(kind, obj, true);
+}
+
+/** True when the object was deleted (by `delete` or by the maximum count). */
+export function isDeleted(obj: unknown): boolean {
+  return typeof obj === 'object' && obj !== null && deleted.has(obj);
+}
+
+/** The live objects of a kind, in creation order (a new array). */
+export function all<K extends DrawingKind>(kind: K): Array<DrawingTypes[K]> {
+  return [...live[kind]] as Array<DrawingTypes[K]>;
+}
+
+/** Forgets all objects (without deleting them) and sets the maximum counts (default 50). */
+export function resetDrawings(newLimits: DrawingLimits = {}): void {
+  for (const kind of Object.keys(live) as DrawingKind[]) live[kind].length = 0;
+  limits = {
+    line: newLimits.line ?? DEFAULT_MAX_COUNT,
+    label: newLimits.label ?? DEFAULT_MAX_COUNT,
+    box: newLimits.box ?? DEFAULT_MAX_COUNT,
+    polyline: newLimits.polyline ?? DEFAULT_MAX_COUNT,
+  };
+}
+
+/** Changes the maximum counts without forgetting the objects (PineScript `indicator(max_*_count)`). */
+export function setDrawingLimits(newLimits: DrawingLimits): void {
+  limits = { ...limits, ...Object.fromEntries(Object.entries(newLimits).filter(([, v]) => v !== undefined)) };
+}

package/src/index.ts

@@ -0,0 +1,201 @@
+/**
+ * OakScriptJS - Simplified PineScript-like library for JavaScript
+ *
+ * This library provides Series-based lazy evaluation and technical analysis functions
+ * for building trading indicators. The PineScript-style script API is in `oakscriptjs/script`.
+ *
+ * Key features:
+ * - Series class for lazy evaluation and method chaining
+ * - Core TA functions (array-based)
+ * - TA-Series wrappers (Series-based)
+ *
+ * @packageDocumentation
+ */
+
+// Export all types
+export * from './types/index.js';
+export * from './types/metadata.js';
+
+// Export core namespaces (array-based functions)
+import * as taCore from './ta/index.js';
+import * as math from './math/index.js';
+import * as array from './array/index.js';
+import * as map from './map/index.js';
+import * as str from './str/index.js';
+import * as color from './color/index.js';
+import * as time from './time/index.js';
+import * as timeframe from './timeframe/index.js';
+import * as matrix from './matrix/index.js';
+import * as line from './line/index.js';
+import * as box from './box/index.js';
+import * as label from './label/index.js';
+import * as linefill from './linefill/index.js';
+import * as chartPoint from './chartpoint/index.js';
+import * as polyline from './polyline/index.js';
+import * as text from './text/index.js';
+import * as compare from './compare/index.js';
+import * as callsite from './callsite/index.js';
+
+export { taCore, math, array, map, str, color, time, timeframe, matrix, line, box, label, linefill, chartPoint, polyline, text, compare, callsite };
+
+// Export Series class (self-contained, no context)
+export { Series, BarData } from './runtime/series.js';
+export type { SeriesExtractor } from './runtime/series.js';
+
+// Export TA-Series namespace (Series-based wrappers)
+import * as ta from './ta-series.js';
+export { ta };
+
+// Export metadata types for indicator return values
+export type {
+  PlotOptions,
+  HLineOptions,
+  FillOptions,
+  InputMetadata,
+  PlotMetadata,
+  IndicatorMetadata,
+  TimeValue,
+  PlotData,
+  HLineData,
+  FillData,
+  FillGradient,
+  IndicatorResult,
+  IndicatorFactory,
+  PlotStyle,
+  LineStyle,
+  PlotDisplay,
+  InputType
+} from './types/metadata.js';
+
+// Re-export commonly used functions for convenience
+export { sma, ema, rsi, macd, bb, stdev, crossover, crossunder, change, tr, atr, cum, vwap } from './ta-series.js';
+export { abs, ceil, floor, round, max, min, avg, sum, sqrt, pow, exp, log, sin, cos, tan } from './math/index.js';
+export { rgb, from_hex as color_from_hex, new_color } from './color/index.js';
+
+// Export chart data utilities
+export { ohlcFromBars, getClose, getHigh, getLow, getOpen, getSource, getSourceSeries, at, div } from './utils/index.js';
+
+// Export libraries (ZigZag, etc.)
+export * from './lib/index.js';
+
+// Export helper functions for generated indicators (PineScript compatibility)
+export {isNA as na, nz, fixnan} from './utils/index.js';
+
+// Export indicator infrastructure
+export {
+  indicator,
+  type IndicatorMetadataConfig,
+  type InputDefinition,
+  type IndicatorContext,
+  type IndicatorInstance,
+  type IndicatorConstructor,
+} from './indicator.js';
+
+export {
+  input,
+  type InputValue,
+  type IntInputOptions,
+  type FloatInputOptions,
+  type SourceInputOptions,
+  type BoolInputOptions,
+  type StringInputOptions,
+  type TimeInputOptions,
+  type SourceType,
+} from './input.js';
+
+export {
+  plot as plotHelper,
+  createPlot,
+  type Time,
+  type TimeValuePair,
+  type PlotOptions as PlotHelperOptions,
+  type PlotResult,
+} from './plot.js';
+
+// Runtime exports - global context runtime (setContext, plot, hline) drawing through a ChartAdapter
+export {
+  setContext,
+  clearContext,
+  getContext,
+  registerCalculate,
+  recalculate,
+  plot,
+  hline,
+  clearPlots,
+} from './runtime/runtime.js';
+
+export {
+  input_int,
+  input_float,
+  input_bool,
+  input_string,
+  input_source,
+  input_timeframe,
+  input_session,
+  input_time,
+} from './runtime/inputs.js';
+
+export type {
+  OakScriptContext,
+  ChartAdapter,
+  InputAdapter,
+  SeriesHandle,
+  SeriesOptions,
+  InputConfig,
+  InputOptions,
+  OhlcvData,
+  PlotConfig,
+  HLineConfig,
+  FillConfig,
+  ArrowConfig,
+} from './runtime/types.js';
+
+// Strategy types and constants (the script API forwards strategy.* calls to a host engine)
+export {
+  STRATEGY_CONSTANTS,
+  STRATEGY_DEFAULTS,
+  STRATEGY_NUMBER_VARIABLES,
+  STRATEGY_TEXT_VARIABLES,
+} from './strategy/index.js';
+export type * from './strategy/index.js';
+
+export { LightweightChartsAdapter } from './runtime/adapters/LightweightChartsAdapter.js';
+export type { LightweightSeriesDefinitions } from './runtime/adapters/LightweightChartsAdapter.js';
+export { SimpleInputAdapter } from './runtime/adapters/SimpleInputAdapter.js';
+
+// Version
+export const VERSION = '0.9.0';
+
+/**
+ * Library information
+ */
+export const info = {
+  name: 'OakScriptJS',
+  version: VERSION,
+  description: 'Simplified PineScript-like library - Series + TA functions',
+  features: {
+    series: 'Lazy evaluation with Series class',
+    ta: 'Technical analysis functions (Series and array-based)',
+    script: 'PineScript-style script API (oakscriptjs/script): indicator, strategy, inputs, plots, request.security',
+    runtime: 'Global context runtime drawing through a ChartAdapter',
+    indicator: 'Indicator function with automatic pane management'
+  },
+  namespaces: {
+    core: ['ta', 'math', 'array', 'map', 'str', 'color', 'time', 'timeframe', 'matrix'],
+    drawing: ['line', 'box', 'label', 'linefill', 'chartPoint', 'polyline', 'text'],
+    runtime: ['setContext', 'plot', 'hline', 'input_*'],
+    indicator: ['indicator', 'input', 'plotHelper', 'createPlot']
+  }
+};
+
+// PineScript compatibility stubs - functions that have no runtime effect
+// These are no-ops so that PineScript-style code runs without modification
+
+/**
+ * alertcondition() - Stub for PineScript alert configuration
+ * In PineScript, this registers an alert condition. In oakscriptjs, it's a no-op
+ * since alert configuration is handled by the host application.
+ */
+export function alertcondition(_condition: unknown, _title?: string, _message?: string): void {
+  // No-op: Alert conditions are handled by the host application
+}

package/src/indicator.ts

@@ -0,0 +1,185 @@
+/**
+ * @fileoverview Indicator function for creating reusable technical indicators
+ * This module provides the `indicator()` function that handles pane management
+ * automatically based on the overlay metadata.
+ * @module indicator
+ */
+
+import type { Bar } from './types/index.js';
+
+/**
+ * Indicator metadata that defines how the indicator should be displayed
+ */
+export interface IndicatorMetadataConfig {
+  /** Full title of the indicator */
+  title: string;
+  /** Short title (for compact display) */
+  shortTitle?: string;
+  /** If true, overlay on price chart; if false, create separate pane (default: false) */
+  overlay?: boolean;
+  /** Number format for values */
+  format?: 'price' | 'percent' | 'volume';
+  /** Decimal precision for displayed values */
+  precision?: number;
+}
+
+/**
+ * Input definition for indicator parameters
+ */
+export interface InputDefinition {
+  /** Unique identifier for the input */
+  name: string;
+  /** Input type */
+  type: 'int' | 'float' | 'source' | 'bool' | 'string';
+  /** Display title */
+  title: string;
+  /** Default value */
+  defaultValue: number | string | boolean;
+  /** Minimum value (for numeric inputs) */
+  min?: number;
+  /** Maximum value (for numeric inputs) */
+  max?: number;
+  /** Step size (for numeric inputs) */
+  step?: number;
+  /** Available options (for source/string types) */
+  options?: string[];
+}
+
+/**
+ * Context provided to indicator setup/compute functions
+ */
+export interface IndicatorContext {
+  /** Bar data for calculation */
+  readonly data: Bar[];
+  /** Open prices array */
+  readonly open: number[];
+  /** High prices array */
+  readonly high: number[];
+  /** Low prices array */
+  readonly low: number[];
+  /** Close prices array */
+  readonly close: number[];
+  /** Volume array */
+  readonly volume: number[];
+  /** Time values array */
+  readonly time: number[];
+  /** Pane index (0 for overlay, higher for separate panes) */
+  readonly paneIndex: number;
+}
+
+/**
+ * Instance of a created indicator
+ */
+export interface IndicatorInstance {
+  /** Indicator metadata */
+  readonly metadata: IndicatorMetadataConfig;
+  /** Get the pane index for this indicator */
+  getPaneIndex(): number;
+  /** Check if this is an overlay indicator */
+  isOverlay(): boolean;
+  /** Get input definitions */
+  getInputs(): InputDefinition[];
+  /** Update input values */
+  updateInputs(inputs: Record<string, number | string | boolean>): void;
+  /** Get current input values */
+  getInputValues(): Record<string, number | string | boolean>;
+  /** Calculate indicator with given bar data */
+  calculate(data: Bar[]): void;
+}
+
+/**
+ * Indicator class constructor type
+ */
+export interface IndicatorConstructor {
+  new (): IndicatorInstance;
+}
+
+/**
+ * Creates an indicator class that handles pane management automatically.
+ * 
+ * When `overlay: false` (default), the indicator will be displayed in a separate pane.
+ * When `overlay: true`, the indicator will be overlaid on the main price chart.
+ * 
+ * @param metadata - Indicator metadata (title, overlay setting, etc.)
+ * @param setup - Setup function that receives the indicator context and defines calculations
+ * @returns A class constructor for creating indicator instances
+ * 
+ * @example
+ * ```typescript
+ * const SMAIndicator = indicator({
+ *   title: 'Simple Moving Average',
+ *   shortTitle: 'SMA',
+ *   overlay: true, // Display on price chart
+ * }, (ctx) => {
+ *   const length = 9;
+ *   const sma = ta.sma(ctx.close, length);
+ *   // Plot or return data...
+ * });
+ * 
+ * const instance = new SMAIndicator();
+ * instance.calculate(barData);
+ * ```
+ */
+export function indicator(
+  metadata: IndicatorMetadataConfig,
+  setup: (ctx: IndicatorContext) => void
+): IndicatorConstructor {
+  // Normalize metadata with defaults
+  const normalizedMetadata: IndicatorMetadataConfig = {
+    title: metadata.title,
+    shortTitle: metadata.shortTitle ?? metadata.title,
+    overlay: metadata.overlay ?? false, // Default to separate pane
+    format: metadata.format ?? 'price',
+    precision: metadata.precision ?? 2,
+  };
+
+  return class implements IndicatorInstance {
+    readonly metadata = normalizedMetadata;
+    private inputDefinitions: InputDefinition[] = [];
+    private inputValues: Record<string, number | string | boolean> = {};
+    private paneIndex: number = 0;
+
+    constructor() {
+      // Calculate initial pane index based on overlay setting
+      this.paneIndex = normalizedMetadata.overlay ? 0 : 1;
+    }
+
+    getPaneIndex(): number {
+      return this.paneIndex;
+    }
+
+    isOverlay(): boolean {
+      return normalizedMetadata.overlay ?? false;
+    }
+
+    getInputs(): InputDefinition[] {
+      return [...this.inputDefinitions];
+    }
+
+    updateInputs(inputs: Record<string, number | string | boolean>): void {
+      this.inputValues = { ...this.inputValues, ...inputs };
+    }
+
+    getInputValues(): Record<string, number | string | boolean> {
+      return { ...this.inputValues };
+    }
+
+    calculate(data: Bar[]): void {
+      const ctx = this.createContext(data);
+      setup(ctx);
+    }
+
+    private createContext(data: Bar[]): IndicatorContext {
+      return {
+        data,
+        open: data.map(d => d.open),
+        high: data.map(d => d.high),
+        low: data.map(d => d.low),
+        close: data.map(d => d.close),
+        volume: data.map(d => d.volume ?? 0),
+        time: data.map(d => d.time),
+        paneIndex: this.paneIndex,
+      };
+    }
+  };
+}