oakscriptjs 0.13.2 → 0.14.0

package/src/script/constants.ts

@@ -0,0 +1,169 @@
+/**
+ * @fileoverview PineScript constant namespaces of the script API: `shape.*`, `location.*`, `size.*`, `xloc.*`,
+ * `yloc.*`, `extend.*`, `display.*`, `format.*`, `font.*`, `scale.*`, `order.*`, `currency.*`, `adjustment.*`, and the
+ * `label.style_*`, `line.style_*`, `dayofweek.*` members. Each constant is the string (or number) the functions take,
+ * so `plotshape(cond, "Buy", { style: shape.triangleup })` and `{ style: "triangleup" }` are the same.
+ *
+ * @module script/constants
+ */
+
+/** PineScript `shape.*`: the shapes of plotshape(). */
+export const shape = {
+  xcross: 'xcross',
+  cross: 'cross',
+  triangleup: 'triangleup',
+  triangledown: 'triangledown',
+  flag: 'flag',
+  circle: 'circle',
+  arrowup: 'arrowup',
+  arrowdown: 'arrowdown',
+  labelup: 'labelup',
+  labeldown: 'labeldown',
+  square: 'square',
+  diamond: 'diamond',
+} as const;
+
+/** PineScript `location.*`: where plotshape() / plotchar() draw. */
+export const location = {
+  abovebar: 'abovebar',
+  belowbar: 'belowbar',
+  top: 'top',
+  bottom: 'bottom',
+  absolute: 'absolute',
+} as const;
+
+/** PineScript `size.*`: sizes of shapes, characters, labels and table texts. */
+export const size = {
+  auto: 'auto',
+  tiny: 'tiny',
+  small: 'small',
+  normal: 'normal',
+  large: 'large',
+  huge: 'huge',
+} as const;
+
+/** PineScript `xloc.*`: the x coordinate of drawings (bar index or UNIX time in ms). */
+export const xloc = {
+  bar_index: 'bar_index',
+  bar_time: 'bar_time',
+} as const;
+
+/** PineScript `yloc.*`: the y position of labels. */
+export const yloc = {
+  price: 'price',
+  abovebar: 'abovebar',
+  belowbar: 'belowbar',
+} as const;
+
+/** PineScript `extend.*`: line extension. */
+export const extend = {
+  none: 'none',
+  left: 'left',
+  right: 'right',
+  both: 'both',
+} as const;
+
+/** PineScript `display.*`: where a plot or input is shown. */
+export const display = {
+  none: 'none',
+  all: 'all',
+  data_window: 'data_window',
+  status_line: 'status_line',
+  pane: 'pane',
+} as const;
+
+/** PineScript `format.*`: the number format of indicator() and str.tostring(). */
+export const format = {
+  inherit: 'inherit',
+  price: 'price',
+  volume: 'volume',
+  percent: 'percent',
+  mintick: 'mintick',
+} as const;
+
+/** PineScript `font.*`: font families of labels, boxes and table cells. */
+export const font = {
+  family_default: 'default',
+  family_monospace: 'monospace',
+} as const;
+
+/** PineScript `scale.*`: the price scale of indicator() (`scale` option). */
+export const scale = {
+  right: 'right',
+  left: 'left',
+  none: 'none',
+} as const;
+
+/** PineScript `order.*`: sort order of array.sort() / array.sort_indices() / matrix.sort(). */
+export const order = {
+  ascending: 'ascending',
+  descending: 'descending',
+} as const;
+
+/** PineScript `adjustment.*`: price adjustment of a ticker. */
+export const adjustment = {
+  none: 'none',
+  splits: 'splits',
+  dividends: 'dividends',
+} as const;
+
+const CURRENCIES = [
+  'AED', 'ARS', 'AUD', 'BDT', 'BHD', 'BRL', 'BTC', 'CAD', 'CHF', 'CLP', 'CNY', 'COP', 'CZK', 'DKK', 'EGP', 'ETH',
+  'EUR', 'GBP', 'GEL', 'HKD', 'HUF', 'IDR', 'ILS', 'INR', 'ISK', 'JPY', 'KES', 'KRW', 'KWD', 'LKR', 'MAD', 'MXN',
+  'MYR', 'NGN', 'NOK', 'NZD', 'PEN', 'PHP', 'PKR', 'PLN', 'QAR', 'RON', 'RSD', 'RUB', 'SAR', 'SEK', 'SGD', 'THB',
+  'TND', 'TRY', 'TWD', 'USD', 'USDT', 'VES', 'VND', 'ZAR',
+] as const;
+
+type CurrencyCode = (typeof CURRENCIES)[number];
+
+/** PineScript `currency.*`: currency codes (`strategy(..., { currency })`, `syminfo.currency`); `currency.NONE` is na. */
+export const currency = {
+  ...(Object.fromEntries(CURRENCIES.map((c) => [c, c])) as { readonly [K in CurrencyCode]: K }),
+  NONE: 'NONE',
+} as const;
+
+/** PineScript `label.style_*`. */
+export const labelStyles = {
+  style_none: 'none',
+  style_xcross: 'xcross',
+  style_cross: 'cross',
+  style_triangleup: 'triangleup',
+  style_triangledown: 'triangledown',
+  style_flag: 'flag',
+  style_circle: 'circle',
+  style_arrowup: 'arrowup',
+  style_arrowdown: 'arrowdown',
+  style_label_up: 'label_up',
+  style_label_down: 'label_down',
+  style_label_left: 'label_left',
+  style_label_right: 'label_right',
+  style_label_lower_left: 'label_lower_left',
+  style_label_lower_right: 'label_lower_right',
+  style_label_upper_left: 'label_upper_left',
+  style_label_upper_right: 'label_upper_right',
+  style_label_center: 'label_center',
+  style_square: 'square',
+  style_diamond: 'diamond',
+  style_text_outline: 'text_outline',
+} as const;
+
+/** PineScript `line.style_*` (lines, boxes, polylines). */
+export const lineStyles = {
+  style_solid: 'solid',
+  style_dotted: 'dotted',
+  style_dashed: 'dashed',
+  style_arrow_left: 'arrow_left',
+  style_arrow_right: 'arrow_right',
+  style_arrow_both: 'arrow_both',
+} as const;
+
+/** PineScript `dayofweek.*`: the values of `dayofweek` (1 = Sunday ... 7 = Saturday). */
+export const daysOfWeek = {
+  sunday: 1,
+  monday: 2,
+  tuesday: 3,
+  wednesday: 4,
+  thursday: 5,
+  friday: 6,
+  saturday: 7,
+} as const;

package/src/script/drawing-args.ts

@@ -0,0 +1,179 @@
+/**
+ * @fileoverview Arguments of the drawing functions of the script API, as PineScript writes them:
+ *
+ * - **Named arguments**: a last argument that is an object of PineScript parameter names, e.g.
+ *   `label.new(c.i, c.high, "A", { style: label.style_label_down, textcolor: color.white })`, or every argument by
+ *   name: `line.new({ x1, y1, x2, y2, extend: extend.right })`. An unknown name throws with the closest names.
+ * - **Series arguments**: inside a bar loop a Series argument (`bar_index`, `high`, `ta.sma(...)`) is its value on the
+ *   current bar, as PineScript reads a series in a call; outside a loop it throws (a drawing takes one value).
+ *
+ * @module script/drawing-args
+ */
+import { Series } from '../runtime/series.js';
+
+/** PineScript parameters of the drawing constructors, in their positional order (coordinates, then chart points). */
+export const DRAWING_PARAMETERS: Record<string, { coords: readonly string[]; point?: readonly string[] }> = {
+  'label.new': {
+    coords: ['x', 'y', 'text', 'xloc', 'yloc', 'color', 'style', 'textcolor', 'size', 'textalign', 'tooltip', 'text_font_family', 'force_overlay', 'text_formatting'],
+    point: ['point', 'text', 'xloc', 'yloc', 'color', 'style', 'textcolor', 'size', 'textalign', 'tooltip', 'text_font_family', 'force_overlay', 'text_formatting'],
+  },
+  'line.new': {
+    coords: ['x1', 'y1', 'x2', 'y2', 'xloc', 'extend', 'color', 'style', 'width', 'force_overlay'],
+    point: ['first_point', 'second_point', 'xloc', 'extend', 'color', 'style', 'width', 'force_overlay'],
+  },
+  'box.new': {
+    coords: [
+      'left', 'top', 'right', 'bottom', 'border_color', 'border_width', 'border_style', 'extend', 'xloc', 'bgcolor', 'text',
+      'text_size', 'text_color', 'text_halign', 'text_valign', 'text_wrap', 'text_font_family', 'force_overlay', 'text_formatting',
+    ],
+    point: [
+      'top_left', 'bottom_right', 'border_color', 'border_width', 'border_style', 'extend', 'xloc', 'bgcolor', 'text',
+      'text_size', 'text_color', 'text_halign', 'text_valign', 'text_wrap', 'text_font_family', 'force_overlay', 'text_formatting',
+    ],
+  },
+  'table.new': {
+    coords: ['position', 'columns', 'rows', 'bgcolor', 'frame_color', 'frame_width', 'border_color', 'border_width', 'force_overlay'],
+  },
+  'table.cell': {
+    coords: [
+      'table_id', 'column', 'row', 'text', 'width', 'height', 'text_color', 'text_halign', 'text_valign', 'text_size', 'bgcolor',
+      'tooltip', 'text_font_family', 'text_formatting',
+    ],
+  },
+  'polyline.new': {
+    coords: ['points', 'curved', 'closed', 'xloc', 'line_color', 'fill_color', 'line_style', 'line_width', 'force_overlay'],
+  },
+  'linefill.new': { coords: ['line1', 'line2', 'color'] },
+};
+
+/** Parameters that take an object: a plain object there is the argument, not named arguments. */
+const OBJECT_PARAMETERS = new Set(['point', 'first_point', 'second_point', 'top_left', 'bottom_right', 'table_id', 'line1', 'line2', 'points']);
+
+/** A plain object (an object literal): named arguments, not a Series, an array or a class instance. */
+export const isPlainObject = (v: unknown): v is Record<string, unknown> =>
+  typeof v === 'object' && v !== null && !Array.isArray(v) && !(v instanceof Series) &&
+  (Object.getPrototypeOf(v) === Object.prototype || Object.getPrototypeOf(v) === null);
+
+/** A chart point (`chart.point.*`): its keys are index / time / price. */
+const isChartPoint = (v: Record<string, unknown>): boolean => {
+  const keys = Object.keys(v);
+  return keys.length > 0 && keys.every((k) => k === 'index' || k === 'time' || k === 'price');
+};
+
+function closest(name: string, names: readonly string[]): string[] {
+  const n = name.toLowerCase();
+  const dist = (a: string, b: string): number => {
+    const row = Array.from({ length: b.length + 1 }, (_, j) => j);
+    for (let i = 1; i <= a.length; i++) {
+      let diag = row[0]!;
+      row[0] = i;
+      for (let j = 1; j <= b.length; j++) {
+        const up = row[j]!;
+        row[j] = Math.min(up + 1, row[j - 1]! + 1, diag + (a[i - 1] === b[j - 1] ? 0 : 1));
+        diag = up;
+      }
+    }
+    return row[b.length]!;
+  };
+  return names
+    .map((k) => ({ k, d: dist(n, k) }))
+    .filter(({ k, d }) => d <= Math.max(2, Math.floor(name.length / 3)) || k.includes(n) || n.includes(k))
+    .sort((a, b) => a.d - b.d)
+    .slice(0, 3)
+    .map(({ k }) => k);
+}
+
+/** The error of an unknown named argument, with the closest names and the list of the arguments. */
+export function unknownArgument(name: string, key: string, list: readonly string[]): TypeError {
+  const near = closest(key, list);
+  return new TypeError(
+    `${name}(): unknown argument "${key}".` + (near.length ? ` Did you mean ${near.join(', ')}?` : '') +
+      ` The arguments are: ${list.join(', ')}.`
+  );
+}
+
+/**
+ * The positional arguments of a call to a function of PineScript parameters `list`, whose last argument may be an
+ * object of named arguments (`request.security(sym, "D", () => close, { lookahead: barmerge.lookahead_on })`, or every
+ * argument by name). An unknown name throws with the closest names; a name given by position too throws.
+ */
+export function namedArguments(name: string, list: readonly string[], args: readonly unknown[]): unknown[] {
+  const last = args[args.length - 1];
+  if (!isPlainObject(last)) return [...args];
+  const positional = args.slice(0, -1);
+  const out = [...positional];
+  for (const [key, value] of Object.entries(last)) {
+    const index = list.indexOf(key);
+    if (index < 0) throw unknownArgument(name, key, list);
+    if (index < positional.length && positional[index] !== undefined) {
+      throw new TypeError(`${name}(): "${key}" is given twice (by position and by name).`);
+    }
+    out[index] = value;
+  }
+  return out;
+}
+
+/** The positional arguments of a call whose last argument may be named arguments. */
+export function positionalArguments(name: string, args: readonly unknown[]): unknown[] {
+  const params = DRAWING_PARAMETERS[name];
+  if (!params) return [...args];
+  const last = args[args.length - 1];
+  if (!isPlainObject(last) || isChartPoint(last)) return [...args];
+  // an object at a parameter that takes one (a chart point, a drawing, the points) is that argument
+  const at = args.length - 1;
+  const firstArg = args[0];
+  const positionalList =
+    params.point !== undefined && typeof firstArg === 'object' && firstArg !== null && !(firstArg instanceof Series) && at > 0
+      ? params.point
+      : params.coords;
+  if (at > 0 && OBJECT_PARAMETERS.has(positionalList[at] ?? '')) return [...args];
+  const positional = args.slice(0, -1);
+  const first = positional.length ? positional[0] : last.point ?? last.first_point ?? last.top_left;
+  const usesPoint = params.point !== undefined && typeof first === 'object' && first !== null && !(first instanceof Series);
+  const list = usesPoint ? params.point! : params.coords;
+  const out = [...positional];
+  for (const [key, value] of Object.entries(last)) {
+    const index = list.indexOf(key);
+    if (index < 0) throw unknownArgument(name, key, list);
+    if (index < positional.length && positional[index] !== undefined) {
+      throw new TypeError(`${name}(): "${key}" is given twice (by position and by name).`);
+    }
+    out[index] = value;
+  }
+  return out;
+}
+
+/** The value of each Series argument on the current bar (inside a bar loop); throws outside a loop. */
+export function barValues(name: string, args: unknown[], currentBar: number): unknown[] {
+  return args.map((a, k) => {
+    if (!(a instanceof Series)) return a;
+    if (currentBar < 0) {
+      throw new TypeError(
+        `${name}(): argument ${k + 1} is a Series, a drawing takes one value: call ${name}() inside eachBar() ` +
+          '(e.g. label.new(c.i, c.high, ...)) or pass a number.'
+      );
+    }
+    const v = a.toArray()[currentBar];
+    return v === undefined ? NaN : v;
+  });
+}
+
+/**
+ * Wraps the functions of a drawing namespace (`label`, `line`, `box`, `table`, `polyline`, `linefill`): named
+ * arguments for the constructors and `table.cell`, Series arguments read on the current bar for every function.
+ */
+export function drawingNamespace<T extends Record<string, unknown>>(namespace: string, members: T, currentBar: () => number): T {
+  const out: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(members)) {
+    if (typeof value !== 'function') {
+      out[key] = value;
+      continue;
+    }
+    const name = `${namespace}.${key}`;
+    const fn = value as (...args: unknown[]) => unknown;
+    out[key] = function (this: unknown, ...args: unknown[]) {
+      return fn.apply(this, barValues(name, positionalArguments(name, args), currentBar()));
+    };
+  }
+  return out as T;
+}

package/src/script/globals.ts

@@ -0,0 +1,129 @@
+/**
+ * @fileoverview Type declarations of the script globals, for type-checking a script source (plain JavaScript)
+ * before it runs. A script body uses every value export of `oakscriptjs/script` but `executeScript` (the host
+ * entry) as a global; these declarations give each global its type, so the TypeScript checker reports the
+ * mistakes of a script with their line: `close - open` (operators on a Series), a misspelt name (`ta.smaa`), a
+ * wrong argument or option, a bad shape or style string.
+ *
+ * In a project that runs scripts, a `tsconfig.json` next to the scripts, then `npx tsc -p .`:
+ *
+ * ```json
+ * {
+ *   "compilerOptions": {
+ *     "allowJs": true, "checkJs": true, "noEmit": true, "strict": true, "noImplicitAny": false,
+ *     "target": "ES2022", "module": "ESNext", "moduleResolution": "bundler", "moduleDetection": "force",
+ *     "lib": ["ES2022"], "types": ["oakscriptjs/script/globals"]
+ *   },
+ *   "include": ["*.js"]
+ * }
+ * ```
+ *
+ * - `lib` leaves out `DOM`: its `open`, `close` and `alert` are other globals.
+ * - `moduleDetection: "force"`: each script has its own top-level names (a script has no import or export).
+ * - `noImplicitAny: false`: the parameters of a script's own functions have no types (plain JavaScript).
+ *
+ * @module script/globals
+ */
+
+import type * as S from './index.js';
+
+declare global {
+  const executeIntrabar: typeof S.executeIntrabar;
+  const varip: typeof S.varip;
+  const indicator: typeof S.indicator;
+  const fixnan: typeof S.fixnan;
+  const fill: typeof S.fill;
+  const plotshape: typeof S.plotshape;
+  const plotchar: typeof S.plotchar;
+  const plotarrow: typeof S.plotarrow;
+  const bgcolor: typeof S.bgcolor;
+  const barcolor: typeof S.barcolor;
+  const plotcandle: typeof S.plotcandle;
+  const plotbar: typeof S.plotbar;
+  const eachBar: typeof S.eachBar;
+  const timestamp: typeof S.timestamp;
+  const inSession: typeof S.inSession;
+  const seriesOf: typeof S.seriesOf;
+  const alertcondition: typeof S.alertcondition;
+  const holdDrawing: typeof S.holdDrawing;
+  const releaseDrawing: typeof S.releaseDrawing;
+  const varDrawing: typeof S.varDrawing;
+  const StrategyRecorder: typeof S.StrategyRecorder;
+  const input: typeof S.input;
+  const open: typeof S.open;
+  const high: typeof S.high;
+  const low: typeof S.low;
+  const close: typeof S.close;
+  const volume: typeof S.volume;
+  const hl2: typeof S.hl2;
+  const hlc3: typeof S.hlc3;
+  const ohlc4: typeof S.ohlc4;
+  const hlcc4: typeof S.hlcc4;
+  const ta: typeof S.ta;
+  const color: typeof S.color;
+  const DEFAULT_OUTPUT_TITLES: typeof S.DEFAULT_OUTPUT_TITLES;
+  const plot: typeof S.plot;
+  const hline: typeof S.hline;
+  const DEFAULT_CANDLE_COLORS: typeof S.DEFAULT_CANDLE_COLORS;
+  const strategy: typeof S.strategy;
+  const MissingSymbolDataError: typeof S.MissingSymbolDataError;
+  const timeframe: typeof S.timeframe;
+  const syminfo: typeof S.syminfo;
+  const year: typeof S.year;
+  const month: typeof S.month;
+  const weekofyear: typeof S.weekofyear;
+  const dayofmonth: typeof S.dayofmonth;
+  const dayofweek: typeof S.dayofweek;
+  const hour: typeof S.hour;
+  const minute: typeof S.minute;
+  const second: typeof S.second;
+  const str: typeof S.str;
+  const timenow: typeof S.timenow;
+  const time: typeof S.time;
+  const time_close: typeof S.time_close;
+  const time_tradingday: typeof S.time_tradingday;
+  const barstate: typeof S.barstate;
+  const session: typeof S.session;
+  const barmerge: typeof S.barmerge;
+  const ticker: typeof S.ticker;
+  const request: typeof S.request;
+  const line: typeof S.line;
+  const label: typeof S.label;
+  const box: typeof S.box;
+  const linefill: typeof S.linefill;
+  const polyline: typeof S.polyline;
+  const table: typeof S.table;
+  const position: typeof S.position;
+  const text: typeof S.text;
+  const chart: typeof S.chart;
+  const alert: typeof S.alert;
+  const Series: typeof S.Series;
+  const BarData: typeof S.BarData;
+  const na: typeof S.na;
+  const nz: typeof S.nz;
+  const STRATEGY_DEFAULTS: typeof S.STRATEGY_DEFAULTS;
+  const math: typeof S.math;
+  const bar_index: typeof S.bar_index;
+  const last_bar_index: typeof S.last_bar_index;
+  const shape: typeof S.shape;
+  const location: typeof S.location;
+  const size: typeof S.size;
+  const xloc: typeof S.xloc;
+  const yloc: typeof S.yloc;
+  const extend: typeof S.extend;
+  const display: typeof S.display;
+  const format: typeof S.format;
+  const font: typeof S.font;
+  const scale: typeof S.scale;
+  const order: typeof S.order;
+  const currency: typeof S.currency;
+  const adjustment: typeof S.adjustment;
+  const compare: typeof S.compare;
+  const isInputActive: typeof S.isInputActive;
+  /** A Series of the script (`close`, the result of `ta.*`...), for JSDoc types: `@type {Series}`. */
+  type Series = S.Series;
+  /** The bar handed to an `eachBar()` callback, for JSDoc types. */
+  type BarContext = S.BarContext;
+}
+
+export {};