oakscriptjs 0.8.1 → 0.9.0

package/src/str/numberformat.ts

@@ -0,0 +1,197 @@
+/**
+ * Number patterns ("#.##", "#,##0.00", "0.00E0", "#.##%", "'#'#.##") as PineScript formats them.
+ *
+ * The pattern syntax is Java's DecimalFormat: `0` required digit, `#` optional digit, `,` grouping,
+ * `.` decimal point, `E0` exponent, `%` multiplies by 100, `'...'` quoted literal text.
+ * PineScript rules:
+ * - `str.tostring` rounds half away from zero on the shortest decimal form of the number
+ *   (`1.005` with "#.##" gives "1.01", `2.5` with "#" gives "3")
+ * - `str.format` rounds half to even on the exact binary value (`0.25` with "#.#" gives "0.2")
+ * - a negative number that rounds to zero loses its sign; "#.00" writes `.50` (no leading zero),
+ *   but "#.##" writes `0.5` (a pattern without any '0' shows one integer digit)
+ * - with an exponent, the value is first rounded to the fraction digits ("0.00E0": 0.125 gives "1.30E-1")
+ * - a pattern without digit characters (`format.price` is "price") formats like "#" after its text,
+ *   and keeps the sign: -0.004 gives "-price0"
+ */
+
+export type Rounding = 'halfUpShortest' | 'halfEvenExact';
+
+interface Pattern {
+  prefix: string;
+  suffix: string;
+  minInt: number;
+  minFrac: number;
+  maxFrac: number;
+  /** Digits per group, 0 without grouping */
+  grouping: number;
+  percent: boolean;
+  /** Minimum exponent digits, or null without exponent */
+  exponent: number | null;
+  hasDigits: boolean;
+}
+
+const patterns = new Map<string, Pattern>();
+
+function parsePattern(pattern: string): Pattern {
+  const cached = patterns.get(pattern);
+  if (cached) return cached;
+
+  let prefix = '';
+  let suffix = '';
+  let number = '';
+  let percent = false;
+  let phase: 'prefix' | 'number' | 'suffix' = 'prefix';
+  for (let i = 0; i < pattern.length; i++) {
+    const ch = pattern[i]!;
+    let literal: string;
+    if (ch === "'") {
+      const end = pattern.indexOf("'", i + 1);
+      if (end === i + 1) {
+        literal = "'";
+        i = end;
+      } else {
+        literal = pattern.slice(i + 1, end === -1 ? undefined : end);
+        i = end === -1 ? pattern.length : end;
+      }
+    } else if (phase !== 'suffix' && ('#0,.'.includes(ch) || (phase === 'number' && ch === 'E'))) {
+      phase = 'number';
+      number += ch;
+      continue;
+    } else {
+      if (ch === '%') percent = true;
+      literal = ch;
+    }
+    if (phase === 'number') phase = 'suffix';
+    if (phase === 'prefix') prefix += literal;
+    else suffix += literal;
+  }
+
+  const [mantissa = '', exp] = number.split('E');
+  const [intPart = '', fracPart = ''] = mantissa.split('.');
+  const lastComma = intPart.lastIndexOf(',');
+  const parsed: Pattern = {
+    prefix,
+    suffix,
+    // as in Java, a pattern with a decimal point and no '0' at all ("#.##") shows one integer digit
+    minInt: !mantissa.includes('0') && mantissa.includes('.') ? 1 : [...intPart].filter((c) => c === '0').length,
+    minFrac: [...fracPart].filter((c) => c === '0').length,
+    maxFrac: [...fracPart].filter((c) => c === '0' || c === '#').length,
+    grouping: lastComma === -1 ? 0 : intPart.length - lastComma - 1,
+    percent,
+    exponent: exp === undefined ? null : exp.length,
+    hasDigits: /[0#]/.test(mantissa),
+  };
+  patterns.set(pattern, parsed);
+  return parsed;
+}
+
+/** Decimal digits of |x|: value = 0.d1d2d3... × 10^intLen (no leading zero digit; "" for 0). */
+interface Digits {
+  digits: string;
+  intLen: number;
+}
+
+function shortestDigits(x: number): Digits {
+  const m = /^(\d+)(?:\.(\d+))?(?:e([+-]\d+))?$/.exec(String(Math.abs(x)))!;
+  const all = m[1]! + (m[2] ?? '');
+  let intLen = m[1]!.length + Number(m[3] ?? 0);
+  const lead = all.length - all.replace(/^0+/, '').length;
+  intLen -= lead;
+  const digits = all.slice(lead).replace(/0+$/, '');
+  return { digits, intLen: digits ? intLen : 0 };
+}
+
+/** Exact decimal expansion of the double |x|. */
+function exactDigits(x: number): Digits {
+  const abs = Math.abs(x);
+  if (abs === 0) return { digits: '', intLen: 0 };
+  const view = new DataView(new ArrayBuffer(8));
+  view.setFloat64(0, abs);
+  const bits = view.getBigUint64(0);
+  const expBits = Number((bits >> 52n) & 0x7ffn);
+  let mant = bits & 0xfffffffffffffn;
+  const e2 = expBits === 0 ? -1074 : expBits - 1075;
+  if (expBits !== 0) mant |= 1n << 52n;
+  let str: string;
+  let fracDigits: number;
+  if (e2 >= 0) {
+    str = (mant << BigInt(e2)).toString();
+    fracDigits = 0;
+  } else {
+    str = (mant * 5n ** BigInt(-e2)).toString();
+    fracDigits = -e2;
+  }
+  const intLen = str.length - fracDigits;
+  const lead = str.length - str.replace(/^0+/, '').length;
+  const digits = str.slice(lead).replace(/0+$/, '');
+  return { digits, intLen: intLen - lead };
+}
+
+/** Rounds to `frac` digits after the point. */
+function roundDigits(d: Digits, frac: number, mode: Rounding): Digits {
+  const keep = d.intLen + frac;
+  if (keep >= d.digits.length) return d;
+  if (keep < 0) return { digits: '', intLen: 0 };
+  const first = d.digits.charCodeAt(keep) - 48;
+  let up: boolean;
+  if (mode === 'halfUpShortest') up = first >= 5;
+  else if (first !== 5) up = first > 5;
+  else if (d.digits.length > keep + 1) up = true;
+  else up = keep > 0 && (d.digits.charCodeAt(keep - 1) - 48) % 2 === 1;
+  let kept = d.digits.slice(0, keep);
+  let intLen = d.intLen;
+  if (up) {
+    const n = (BigInt(kept || '0') + 1n).toString();
+    if (n.length > kept.length) intLen += 1;
+    kept = n;
+  }
+  kept = kept.replace(/0+$/, '');
+  return { digits: kept, intLen: kept ? intLen : 0 };
+}
+
+function group(int: string, size: number): string {
+  if (!size || int.length <= size) return int;
+  const parts: string[] = [];
+  for (let end = int.length; end > 0; end -= size) parts.unshift(int.slice(Math.max(0, end - size), end));
+  return parts.join(',');
+}
+
+function layout(d: Digits, p: Pattern): string {
+  let int = d.intLen > 0 ? d.digits.slice(0, d.intLen).padEnd(d.intLen, '0') : '';
+  int = int.replace(/^0+/, '').padStart(p.minInt, '0');
+  let frac = d.intLen < 0 ? '0'.repeat(-d.intLen) + d.digits : d.digits.slice(Math.max(0, d.intLen));
+  frac = frac.slice(0, p.maxFrac).replace(/0+$/, '').padEnd(p.minFrac, '0');
+  if (!int && !frac) int = '0';
+  return group(int, p.grouping) + (frac ? '.' + frac : '');
+}
+
+/** Formats a number with a DecimalFormat pattern. */
+export function formatNumber(value: number, pattern: string, mode: Rounding): string {
+  if (Number.isNaN(value)) return 'NaN';
+  const p = parsePattern(pattern);
+  if (!Number.isFinite(value)) return (value < 0 ? '-' : '') + p.prefix + '∞' + p.suffix;
+  const x = p.percent ? value * 100 : value;
+  const toDigits = mode === 'halfUpShortest' ? shortestDigits : exactDigits;
+
+  let body: string;
+  let isZero: boolean;
+  if (p.exponent !== null) {
+    const rounded = roundDigits(toDigits(x), p.maxFrac, mode);
+    const intDigits = Math.max(p.minInt, 1);
+    isZero = rounded.digits === '';
+    let exponent = isZero ? 0 : rounded.intLen - intDigits;
+    let mant = roundDigits({ digits: rounded.digits, intLen: isZero ? 0 : intDigits }, p.maxFrac, mode);
+    if (mant.intLen > intDigits) {
+      exponent += 1;
+      mant = { digits: mant.digits, intLen: intDigits };
+    }
+    const e = String(Math.abs(exponent)).padStart(p.exponent, '0');
+    body = layout(mant, p) + 'E' + (exponent < 0 ? '-' : '') + e;
+  } else {
+    const rounded = roundDigits(toDigits(x), p.hasDigits ? p.maxFrac : 0, mode);
+    isZero = rounded.digits === '';
+    body = p.hasDigits ? layout(rounded, p) : layout(rounded, { ...p, minInt: 0, maxFrac: 0, minFrac: 0 });
+  }
+  const negative = x < 0 && (!isZero || !p.hasDigits);
+  return (negative ? '-' : '') + p.prefix + body + p.suffix;
+}

package/src/strategy/index.ts

@@ -0,0 +1,281 @@
+/**
+ * @fileoverview Types and constants of the PineScript `strategy.*` API.
+ *
+ * OakScriptJS does not simulate orders. The script API (`oakscriptjs/script`) declares the strategy,
+ * forwards every `strategy.*` call to a {@link StrategyEngine} that the host supplies, and reads the
+ * `strategy.*` variables from it. The engine fills the orders, keeps the trades and computes the
+ * results.
+ *
+ * Names follow PineScript v6: option objects use the PineScript argument names, and the engine
+ * receives them unchanged. An `na` (NaN) numeric argument is removed before the call, since in
+ * PineScript it means "not given". The deprecated `when` argument does not exist: use `if`.
+ *
+ * @module strategy
+ */
+
+export type StrategyDirection = 'long' | 'short';
+export type StrategyQtyType = 'fixed' | 'cash' | 'percent_of_equity';
+export type StrategyCommissionType = 'percent' | 'cash_per_contract' | 'cash_per_order';
+export type StrategyOcaType = 'none' | 'cancel' | 'reduce';
+/** `strategy.direction.*`, for `strategy.risk.allow_entry_in`. */
+export type StrategyRiskDirection = 'all' | 'long' | 'short';
+export type StrategyRiskValueType = 'percent_of_equity' | 'cash';
+
+/** PineScript `strategy.*` constants. */
+export const STRATEGY_CONSTANTS = {
+  long: 'long',
+  short: 'short',
+  fixed: 'fixed',
+  cash: 'cash',
+  percent_of_equity: 'percent_of_equity',
+  commission: { percent: 'percent', cash_per_contract: 'cash_per_contract', cash_per_order: 'cash_per_order' },
+  direction: { all: 'all', long: 'long', short: 'short' },
+  oca: { none: 'none', cancel: 'cancel', reduce: 'reduce' },
+} as const;
+
+/** Arguments of the PineScript `strategy()` declaration, after `title`. */
+export interface StrategyOptions {
+  shorttitle?: string;
+  overlay?: boolean;
+  format?: string;
+  precision?: number;
+  scale?: string;
+  pyramiding?: number;
+  calc_on_order_fills?: boolean;
+  calc_on_every_tick?: boolean;
+  max_bars_back?: number;
+  backtest_fill_limits_assumption?: number;
+  default_qty_type?: StrategyQtyType;
+  default_qty_value?: number;
+  initial_capital?: number;
+  /** Account currency; default: the symbol currency. */
+  currency?: string;
+  /** Ticks added to market and stop fills. */
+  slippage?: number;
+  commission_type?: StrategyCommissionType;
+  commission_value?: number;
+  process_orders_on_close?: boolean;
+  close_entries_rule?: 'FIFO' | 'ANY';
+  margin_long?: number;
+  margin_short?: number;
+  explicit_plot_zorder?: boolean;
+  max_lines_count?: number;
+  max_labels_count?: number;
+  max_boxes_count?: number;
+  calc_bars_count?: number;
+  risk_free_rate?: number;
+  use_bar_magnifier?: boolean;
+  fill_orders_on_standard_ohlc?: boolean;
+  max_polylines_count?: number;
+}
+
+/** Strategy properties passed to the engine: the declared values, else the PineScript defaults. */
+export interface StrategyProperties {
+  pyramiding: number;
+  calc_on_order_fills: boolean;
+  calc_on_every_tick: boolean;
+  backtest_fill_limits_assumption: number;
+  default_qty_type: StrategyQtyType;
+  default_qty_value: number;
+  initial_capital: number;
+  /** undefined: the symbol currency. */
+  currency?: string;
+  slippage: number;
+  commission_type: StrategyCommissionType;
+  commission_value: number;
+  process_orders_on_close: boolean;
+  close_entries_rule: 'FIFO' | 'ANY';
+  margin_long: number;
+  margin_short: number;
+  calc_bars_count: number;
+  risk_free_rate: number;
+  use_bar_magnifier: boolean;
+  fill_orders_on_standard_ohlc: boolean;
+}
+
+/** PineScript defaults of the `strategy()` arguments (v6 reference). */
+export const STRATEGY_DEFAULTS: StrategyProperties = {
+  pyramiding: 0,
+  calc_on_order_fills: false,
+  calc_on_every_tick: false,
+  backtest_fill_limits_assumption: 0,
+  // v6 values; PineScript v5: fixed / 1 / 1000000 and margins 0
+  default_qty_type: 'percent_of_equity',
+  default_qty_value: 100,
+  initial_capital: 100000,
+  slippage: 0,
+  commission_type: 'percent',
+  commission_value: 0,
+  process_orders_on_close: false,
+  close_entries_rule: 'FIFO',
+  margin_long: 100,
+  margin_short: 100,
+  calc_bars_count: 0,
+  risk_free_rate: 2,
+  use_bar_magnifier: false,
+  fill_orders_on_standard_ohlc: false,
+};
+
+/** `strategy.entry()` / `strategy.order()` arguments after `id` and `direction`. */
+export interface StrategyEntryOptions {
+  qty?: number;
+  limit?: number;
+  stop?: number;
+  oca_name?: string;
+  oca_type?: StrategyOcaType;
+  comment?: string;
+  alert_message?: string;
+  disable_alert?: boolean;
+}
+
+/** `strategy.exit()` arguments after `id`. `profit`, `loss`, `trail_points` and `trail_offset` are in ticks. */
+export interface StrategyExitOptions {
+  from_entry?: string;
+  qty?: number;
+  qty_percent?: number;
+  profit?: number;
+  limit?: number;
+  loss?: number;
+  stop?: number;
+  trail_price?: number;
+  trail_points?: number;
+  trail_offset?: number;
+  oca_name?: string;
+  comment?: string;
+  comment_profit?: string;
+  comment_loss?: string;
+  comment_trailing?: string;
+  alert_message?: string;
+  alert_profit?: string;
+  alert_loss?: string;
+  alert_trailing?: string;
+  disable_alert?: boolean;
+}
+
+/** `strategy.close()` arguments after `id`. */
+export interface StrategyCloseOptions {
+  comment?: string;
+  qty?: number;
+  qty_percent?: number;
+  alert_message?: string;
+  immediately?: boolean;
+  disable_alert?: boolean;
+}
+
+/** `strategy.close_all()` arguments. */
+export interface StrategyCloseAllOptions {
+  comment?: string;
+  alert_message?: string;
+  immediately?: boolean;
+  disable_alert?: boolean;
+}
+
+/** A `strategy.risk.*` rule. */
+export type StrategyRiskRule =
+  | { rule: 'allow_entry_in'; direction: StrategyRiskDirection }
+  | { rule: 'max_cons_loss_days'; count: number; alert_message?: string }
+  | { rule: 'max_drawdown'; value: number; type: StrategyRiskValueType; alert_message?: string }
+  | { rule: 'max_intraday_filled_orders'; count: number; alert_message?: string }
+  | { rule: 'max_intraday_loss'; value: number; type: StrategyRiskValueType; alert_message?: string }
+  | { rule: 'max_position_size'; contracts: number };
+
+/**
+ * One trade, as the PineScript `strategy.opentrades.*(i)` / `strategy.closedtrades.*(i)` functions
+ * return it. Times are UNIX milliseconds. The `exit_*` fields are for closed trades only; `exit_id` and the
+ * comments are undefined when the engine does not provide them.
+ */
+export interface StrategyTrade {
+  entry_id: string;
+  entry_price: number;
+  entry_bar_index: number;
+  entry_time: number;
+  /** undefined when the order had no comment, or when the engine does not keep it apart from the id. */
+  entry_comment?: string;
+  /** Signed quantity: positive for a long trade, negative for a short trade. */
+  size: number;
+  profit: number;
+  profit_percent: number;
+  commission: number;
+  max_runup: number;
+  max_runup_percent: number;
+  max_drawdown: number;
+  max_drawdown_percent: number;
+  exit_id?: string;
+  exit_price?: number;
+  exit_bar_index?: number;
+  exit_time?: number;
+  exit_comment?: string;
+}
+
+/** Numeric `strategy.*` variables. */
+export const STRATEGY_NUMBER_VARIABLES = [
+  'position_size',
+  'position_avg_price',
+  'equity',
+  'initial_capital',
+  'netprofit',
+  'netprofit_percent',
+  'openprofit',
+  'openprofit_percent',
+  'grossprofit',
+  'grossprofit_percent',
+  'grossloss',
+  'grossloss_percent',
+  'opentrades',
+  'closedtrades',
+  'wintrades',
+  'losstrades',
+  'eventrades',
+  'avg_trade',
+  'avg_trade_percent',
+  'avg_winning_trade',
+  'avg_winning_trade_percent',
+  'avg_losing_trade',
+  'avg_losing_trade_percent',
+  'max_drawdown',
+  'max_drawdown_percent',
+  'max_runup',
+  'max_runup_percent',
+  'max_contracts_held_all',
+  'max_contracts_held_long',
+  'max_contracts_held_short',
+  'margin_liquidation_price',
+] as const;
+
+/** Text `strategy.*` variables. */
+export const STRATEGY_TEXT_VARIABLES = ['position_entry_name', 'account_currency'] as const;
+
+export type StrategyNumberVariable = (typeof STRATEGY_NUMBER_VARIABLES)[number];
+export type StrategyTextVariable = (typeof STRATEGY_TEXT_VARIABLES)[number];
+export type StrategyVariable = StrategyNumberVariable | StrategyTextVariable;
+
+/**
+ * The order engine the host supplies. OakScriptJS calls it in this order on each bar `i` of
+ * `strategy.eachBar()`:
+ *
+ * 1. `processBar(i)`: fill the orders placed before bar `i` (at the open and inside the bar);
+ * 2. the script runs at the close of bar `i`: order calls and variable reads;
+ * 3. `processClose(i)`: after the script; with `process_orders_on_close`, fill the new market orders
+ *    at the close.
+ */
+export interface StrategyEngine {
+  processBar(bar: number): void;
+  processClose(bar: number): void;
+  entry(id: string, direction: StrategyDirection, options: StrategyEntryOptions): void;
+  order(id: string, direction: StrategyDirection, options: StrategyEntryOptions): void;
+  exit(id: string, options: StrategyExitOptions): void;
+  close(id: string, options: StrategyCloseOptions): void;
+  close_all(options: StrategyCloseAllOptions): void;
+  cancel(id: string): void;
+  cancel_all(): void;
+  /** Current value of a `strategy.*` variable; undefined when the engine does not provide it. */
+  get(variable: StrategyVariable): number | string | undefined;
+  /** Open trade number `index` (0 = oldest); undefined when it does not exist. */
+  openTrade(index: number): StrategyTrade | undefined;
+  /** Closed trade number `index` (0 = oldest); undefined when it does not exist. */
+  closedTrade(index: number): StrategyTrade | undefined;
+  /** `strategy.risk.*` rules; optional. */
+  risk?(rule: StrategyRiskRule): void;
+  /** `strategy.default_entry_qty(fill_price)`; optional. */
+  defaultEntryQty?(fillPrice: number): number;
+}