@mathieuc/tradingview 3.5.2 → 4.0.0-beta.1

package/dist/chart/graphics.d.ts

@@ -0,0 +1,129 @@
+/** Raw graphics as sent by TradingView, indexed by type then drawing ID. */
+export type RawGraphics = Record<string, Record<string, any>>;
+export type ExtendValue = 'right' | 'left' | 'both' | 'none';
+export type YLocValue = 'price' | 'abovebar' | 'belowbar';
+export type LabelStyleValue = 'none' | 'xcross' | 'cross' | 'triangleup' | 'triangledown' | 'flag' | 'circle' | 'arrowup' | 'arrowdown' | 'label_up' | 'label_down' | 'label_left' | 'label_right' | 'label_lower_left' | 'label_lower_right' | 'label_upper_left' | 'label_upper_right' | 'label_center' | 'square' | 'diamond';
+export type LineStyleValue = 'solid' | 'dotted' | 'dashed' | 'arrow_left' | 'arrow_right' | 'arrow_both';
+export type BoxStyleValue = 'solid' | 'dotted' | 'dashed';
+export type SizeValue = 'auto' | 'huge' | 'large' | 'normal' | 'small' | 'tiny';
+export type VAlignValue = 'top' | 'center' | 'bottom';
+export type HAlignValue = 'left' | 'center' | 'right';
+export type TextWrapValue = 'none' | 'auto';
+export type TablePositionValue = 'top_left' | 'top_center' | 'top_right' | 'middle_left' | 'middle_center' | 'middle_right' | 'bottom_left' | 'bottom_center' | 'bottom_right';
+/**
+ * X positions are expressed in bars back from the most recent bar loaded on
+ * the chart (0 = latest bar). They are `undefined` when the bar is not loaded.
+ */
+export interface GraphicLabel {
+    id: number;
+    x: number | undefined;
+    y: number;
+    yLoc: YLocValue;
+    text: string;
+    style: LabelStyleValue;
+    color: number;
+    textColor: number;
+    size: SizeValue;
+    textAlign: HAlignValue;
+    toolTip: string;
+}
+export interface GraphicLine {
+    id: number;
+    x1: number | undefined;
+    y1: number;
+    x2: number | undefined;
+    y2: number;
+    extend: ExtendValue;
+    style: LineStyleValue;
+    color: number;
+    width: number;
+}
+export interface GraphicBox {
+    id: number;
+    x1: number | undefined;
+    y1: number;
+    x2: number | undefined;
+    y2: number;
+    color: number;
+    bgColor: number;
+    extend: ExtendValue;
+    style: BoxStyleValue;
+    width: number;
+    text: string;
+    textSize: SizeValue;
+    textColor: number;
+    textVAlign: VAlignValue;
+    textHAlign: HAlignValue;
+    textWrap: TextWrapValue;
+}
+export interface TableCell {
+    id: number;
+    text: string;
+    width: number;
+    height: number;
+    textColor: number;
+    textHAlign: HAlignValue;
+    textVAlign: VAlignValue;
+    textSize: SizeValue;
+    bgColor: number;
+}
+export interface GraphicTable {
+    id: number;
+    position: TablePositionValue;
+    rows: number;
+    columns: number;
+    bgColor: number;
+    frameColor: number;
+    frameWidth: number;
+    borderColor: number;
+    borderWidth: number;
+    /** Cells as a `[row][column]` matrix. */
+    cells: TableCell[][];
+}
+export interface GraphicHorizLine {
+    id: number;
+    level: number;
+    startIndex: number | undefined;
+    endIndex: number | undefined;
+    extendRight: boolean;
+    extendLeft: boolean;
+    [key: string]: unknown;
+}
+export interface GraphicPoint {
+    index: number | undefined;
+    level: number;
+    [key: string]: unknown;
+}
+export interface GraphicPolygon {
+    id: number;
+    points: GraphicPoint[];
+    [key: string]: unknown;
+}
+export interface GraphicHorizHist {
+    id: number;
+    priceLow: number;
+    priceHigh: number;
+    firstBarTime: number | undefined;
+    lastBarTime: number | undefined;
+    rate: number[];
+    [key: string]: unknown;
+}
+/** Drawings produced by an indicator, grouped by type. */
+export interface GraphicsData {
+    labels: GraphicLabel[];
+    lines: GraphicLine[];
+    boxes: GraphicBox[];
+    tables: GraphicTable[];
+    polygons: GraphicPolygon[];
+    horizLines: GraphicHorizLine[];
+    horizHists: GraphicHorizHist[];
+    /** Unparsed graphics, including types this parser does not know. */
+    raw: RawGraphics;
+}
+/**
+ * Converts raw indicator graphics into readable objects.
+ * @param indexes Maps graphic X indexes to "bars back" positions.
+ */
+export declare function parseGraphics(raw?: RawGraphics, indexes?: ReadonlyArray<number | undefined>): GraphicsData;
+/** Applies `graphicsCmds` (erase then create) to raw graphics in place. */
+export declare function applyGraphicsCommands(graphics: RawGraphics, commands: any): void;

package/dist/chart/graphics.js

@@ -0,0 +1,153 @@
+const TRANSLATOR = {
+    extend: {
+        r: 'right', l: 'left', b: 'both', n: 'none',
+    },
+    yLoc: { pr: 'price', ab: 'abovebar', bl: 'belowbar' },
+    labelStyle: {
+        n: 'none',
+        xcr: 'xcross',
+        cr: 'cross',
+        tup: 'triangleup',
+        tdn: 'triangledown',
+        flg: 'flag',
+        cir: 'circle',
+        aup: 'arrowup',
+        adn: 'arrowdown',
+        lup: 'label_up',
+        ldn: 'label_down',
+        llf: 'label_left',
+        lrg: 'label_right',
+        llwlf: 'label_lower_left',
+        llwrg: 'label_lower_right',
+        luplf: 'label_upper_left',
+        luprg: 'label_upper_right',
+        lcn: 'label_center',
+        sq: 'square',
+        dia: 'diamond',
+    },
+    lineStyle: {
+        sol: 'solid', dot: 'dotted', dsh: 'dashed', al: 'arrow_left', ar: 'arrow_right', ab: 'arrow_both',
+    },
+    boxStyle: { sol: 'solid', dot: 'dotted', dsh: 'dashed' },
+};
+/**
+ * Converts raw indicator graphics into readable objects.
+ * @param indexes Maps graphic X indexes to "bars back" positions.
+ */
+export function parseGraphics(raw = {}, indexes = []) {
+    const values = (type) => Object.values(raw[type] ?? {});
+    const x = (index) => indexes[index];
+    return {
+        labels: values('dwglabels').map((l) => ({
+            id: l.id,
+            x: x(l.x),
+            y: l.y,
+            yLoc: TRANSLATOR.yLoc[l.yl] ?? l.yl,
+            text: l.t,
+            style: TRANSLATOR.labelStyle[l.st] ?? l.st,
+            color: l.ci,
+            textColor: l.tci,
+            size: l.sz,
+            textAlign: l.ta,
+            toolTip: l.tt,
+        })),
+        lines: values('dwglines').map((l) => ({
+            id: l.id,
+            x1: x(l.x1),
+            y1: l.y1,
+            x2: x(l.x2),
+            y2: l.y2,
+            extend: TRANSLATOR.extend[l.ex] ?? l.ex,
+            style: TRANSLATOR.lineStyle[l.st] ?? l.st,
+            color: l.ci,
+            width: l.w,
+        })),
+        boxes: values('dwgboxes').map((b) => ({
+            id: b.id,
+            x1: x(b.x1),
+            y1: b.y1,
+            x2: x(b.x2),
+            y2: b.y2,
+            color: b.c,
+            bgColor: b.bc,
+            extend: TRANSLATOR.extend[b.ex] ?? b.ex,
+            style: TRANSLATOR.boxStyle[b.st] ?? b.st,
+            width: b.w,
+            text: b.t,
+            textSize: b.ts,
+            textColor: b.tc,
+            textVAlign: b.tva,
+            textHAlign: b.tha,
+            textWrap: b.tw,
+        })),
+        tables: values('dwgtables').map((t) => {
+            const cells = [];
+            for (const cell of values('dwgtablecells')) {
+                if (cell.tid !== t.id)
+                    continue;
+                cells[cell.row] ??= [];
+                cells[cell.row][cell.col] = {
+                    id: cell.id,
+                    text: cell.t,
+                    width: cell.w,
+                    height: cell.h,
+                    textColor: cell.tc,
+                    textHAlign: cell.tha,
+                    textVAlign: cell.tva,
+                    textSize: cell.ts,
+                    bgColor: cell.bgc,
+                };
+            }
+            return {
+                id: t.id,
+                position: t.pos,
+                rows: t.rows,
+                columns: t.cols,
+                bgColor: t.bgc,
+                frameColor: t.frmc,
+                frameWidth: t.frmw,
+                borderColor: t.brdc,
+                borderWidth: t.brdw,
+                cells,
+            };
+        }),
+        horizLines: values('horizlines').map((h) => ({
+            ...h,
+            startIndex: x(h.startIndex),
+            endIndex: x(h.endIndex),
+        })),
+        polygons: values('polygons').map((p) => ({
+            ...p,
+            points: (p.points ?? []).map((point) => ({ ...point, index: x(point.index) })),
+        })),
+        horizHists: values('hhists').map((h) => ({
+            ...h,
+            firstBarTime: x(h.firstBarTime),
+            lastBarTime: x(h.lastBarTime),
+        })),
+        raw,
+    };
+}
+/** Applies `graphicsCmds` (erase then create) to raw graphics in place. */
+export function applyGraphicsCommands(graphics, commands) {
+    for (const instruction of commands?.erase ?? []) {
+        if (instruction.action === 'all') {
+            if (!instruction.type) {
+                for (const type of Object.keys(graphics))
+                    graphics[type] = {};
+            }
+            else
+                delete graphics[instruction.type];
+        }
+        else if (instruction.action === 'one' && instruction.type) {
+            delete graphics[instruction.type]?.[instruction.id];
+        }
+    }
+    for (const [type, groups] of Object.entries(commands?.create ?? {})) {
+        graphics[type] ??= {};
+        for (const group of groups ?? []) {
+            for (const item of group.data ?? [])
+                graphics[type][item.id] = item;
+        }
+    }
+}

package/dist/chart/index.d.ts

@@ -0,0 +1,11 @@
+export { ChartSession } from './chart-session.js';
+export type { ChartEvents, MarketOptions, SeriesCompletedInfo, } from './chart-session.js';
+export { Study } from './study.js';
+export type { StudyChange, StudyEvents, StudyValue } from './study.js';
+export { applyGraphicsCommands, parseGraphics, } from './graphics.js';
+export type { BoxStyleValue, ExtendValue, GraphicBox, GraphicHorizHist, GraphicHorizLine, GraphicLabel, GraphicLine, GraphicPoint, GraphicPolygon, GraphicTable, GraphicsData, HAlignValue, LabelStyleValue, LineStyleValue, RawGraphics, SizeValue, TableCell, TablePositionValue, TextWrapValue, VAlignValue, YLocValue, } from './graphics.js';
+export { mergeStrategyReport, parseTrades, summarizeStrategyReport } from './strategy.js';
+export type { FromTo, PerformanceReport, RelAbsValue, StrategyReport, StrategyReportChange, StrategySummary, TradeReport, } from './strategy.js';
+export { timeframeSeconds } from './timeframes.js';
+export { CHART_TYPE_STUDIES } from './types.js';
+export type { Adjustment, Candle, ChartType, ChartTypeInputs, MarketSymbol, Subsession, SymbolInfo, Timeframe, Timezone, TradingSession, } from './types.js';

package/dist/chart/index.js

@@ -0,0 +1,6 @@
+export { ChartSession } from './chart-session.js';
+export { Study } from './study.js';
+export { applyGraphicsCommands, parseGraphics, } from './graphics.js';
+export { mergeStrategyReport, parseTrades, summarizeStrategyReport } from './strategy.js';
+export { timeframeSeconds } from './timeframes.js';
+export { CHART_TYPE_STUDIES } from './types.js';

package/dist/chart/strategy.d.ts

@@ -0,0 +1,113 @@
+/** A value with absolute and percent forms. */
+export interface RelAbsValue {
+    v: number;
+    p: number;
+}
+export interface TradeReport {
+    entry: {
+        name: string;
+        type: 'long' | 'short';
+        value: number;
+        time: number;
+    };
+    /** `name` is '' for exits that are not explicit. */
+    exit: {
+        name: string;
+        value: number;
+        time: number;
+    };
+    quantity: number;
+    profit: RelAbsValue;
+    cumulative: RelAbsValue;
+    runup: RelAbsValue;
+    drawdown: RelAbsValue;
+}
+export interface PerformanceReport {
+    avgBarsInTrade: number;
+    avgBarsInWinTrade: number;
+    avgBarsInLossTrade: number;
+    avgTrade: number;
+    avgTradePercent: number;
+    avgLosTrade: number;
+    avgLosTradePercent: number;
+    avgWinTrade: number;
+    avgWinTradePercent: number;
+    commissionPaid: number;
+    grossLoss: number;
+    grossLossPercent: number;
+    grossProfit: number;
+    grossProfitPercent: number;
+    largestLosTrade: number;
+    largestLosTradePercent: number;
+    largestWinTrade: number;
+    largestWinTradePercent: number;
+    marginCalls: number;
+    maxContractsHeld: number;
+    netProfit: number;
+    netProfitPercent: number;
+    numberOfLosingTrades: number;
+    numberOfWiningTrades: number;
+    percentProfitable: number;
+    profitFactor: number;
+    ratioAvgWinAvgLoss: number;
+    totalOpenTrades: number;
+    totalTrades: number;
+    [key: string]: number;
+}
+export interface FromTo {
+    from: number;
+    to: number;
+}
+/** Report sent by Pine strategies (backtest results computed by TradingView). */
+export interface StrategyReport {
+    currency?: string;
+    settings?: {
+        dateRange?: {
+            backtest?: FromTo;
+            trade?: FromTo;
+        };
+        [key: string]: unknown;
+    };
+    /** Trade records, most recent first; may include open positions with an exit valuation. */
+    trades: TradeReport[];
+    history: {
+        buyHold?: number[];
+        buyHoldPercent?: number[];
+        drawDown?: number[];
+        drawDownPercent?: number[];
+        equity?: number[];
+        equityPercent?: number[];
+    };
+    performance: {
+        all?: PerformanceReport;
+        long?: PerformanceReport;
+        short?: PerformanceReport;
+        buyHoldReturn?: number;
+        buyHoldReturnPercent?: number;
+        maxDrawDown?: number;
+        maxDrawDownPercent?: number;
+        openPL?: number;
+        openPLPercent?: number;
+        sharpeRatio?: number;
+        sortinoRatio?: number;
+        [key: string]: unknown;
+    };
+}
+export type StrategyReportChange = 'report.currency' | 'report.settings' | 'report.perf' | 'report.trades' | 'report.history';
+/** Converts raw trades (oldest first) into readable trades (most recent first). */
+export declare function parseTrades(trades: any[]): TradeReport[];
+/** Merges a raw report into `target`; returns the changed parts. */
+export declare function mergeStrategyReport(target: StrategyReport, report: any): StrategyReportChange[];
+/** Aggregate counts are authoritative; an exit valuation does not prove closure. */
+export interface StrategySummary {
+    tradeRecordCount: number;
+    closedTradeCount?: number;
+    openTradeCount?: number;
+    closedNetProfit?: number;
+    openPnL?: number;
+    /** Available only when both closed and open PnL are present. */
+    totalPnL?: number;
+    currency?: string;
+}
+/** Summarizes reported aggregates without inferring missing values or trade status. */
+export declare function summarizeStrategyReport(report: StrategyReport): StrategySummary;

package/dist/chart/strategy.js

@@ -0,0 +1,78 @@
+import { TradingViewError } from '../errors.js';
+/** Converts raw trades (oldest first) into readable trades (most recent first). */
+export function parseTrades(trades) {
+    if (!Array.isArray(trades) || trades.some((trade) => !trade || typeof trade !== 'object' || Array.isArray(trade))) {
+        throw new TradingViewError('PARSE_ERROR', 'Strategy trades must be an array of records');
+    }
+    return [...trades].reverse().map((t) => ({
+        entry: {
+            name: t.e?.c,
+            type: String(t.e?.tp ?? '').startsWith('s') ? 'short' : 'long',
+            value: t.e?.p,
+            time: t.e?.tm,
+        },
+        exit: { name: t.x?.c, value: t.x?.p, time: t.x?.tm },
+        quantity: t.q,
+        profit: t.tp,
+        cumulative: t.cp,
+        runup: t.rn,
+        drawdown: t.dd,
+    }));
+}
+/** Merges a raw report into `target`; returns the changed parts. */
+export function mergeStrategyReport(target, report) {
+    const changes = [];
+    if (!report || typeof report !== 'object')
+        return changes;
+    // Parse before mutating the target so a malformed trade list cannot leave a partial merge.
+    const trades = report.trades === undefined ? undefined : parseTrades(report.trades);
+    if (report.currency) {
+        target.currency = report.currency;
+        changes.push('report.currency');
+    }
+    if (report.settings) {
+        target.settings = report.settings;
+        changes.push('report.settings');
+    }
+    if (report.performance) {
+        target.performance = report.performance;
+        changes.push('report.perf');
+    }
+    if (trades !== undefined) {
+        target.trades = trades;
+        changes.push('report.trades');
+    }
+    const historyKeys = [
+        'buyHold', 'buyHoldPercent', 'drawDown', 'drawDownPercent', 'equity', 'equityPercent',
+    ];
+    let historyChanged = false;
+    for (const key of historyKeys) {
+        if (Array.isArray(report[key])) {
+            target.history[key] = report[key];
+            historyChanged = true;
+        }
+    }
+    if (historyChanged)
+        changes.push('report.history');
+    return changes;
+}
+/** Summarizes reported aggregates without inferring missing values or trade status. */
+export function summarizeStrategyReport(report) {
+    const finite = (value) => typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+    const count = (value) => {
+        const n = finite(value);
+        return n !== undefined && Number.isInteger(n) && n >= 0 ? n : undefined;
+    };
+    const closedNetProfit = finite(report.performance.all?.netProfit);
+    const openPnL = finite(report.performance.openPL);
+    return {
+        currency: report.currency,
+        tradeRecordCount: report.trades.length,
+        closedTradeCount: count(report.performance.all?.totalTrades),
+        openTradeCount: count(report.performance.all?.totalOpenTrades),
+        closedNetProfit,
+        openPnL,
+        totalPnL: closedNetProfit !== undefined && openPnL !== undefined
+            ? finite(closedNetProfit + openPnL) : undefined,
+    };
+}

package/dist/chart/study.d.ts

@@ -0,0 +1,60 @@
+import { TradingViewError } from '../errors.js';
+import { Emitter } from '../events.js';
+import type { Indicator } from '../indicators/index.js';
+import type { ServerPacket } from '../protocol/framing.js';
+import { type GraphicsData } from './graphics.js';
+import { type StrategyReport, type StrategyReportChange } from './strategy.js';
+/** One study row: `$time` (Unix seconds) plus one entry per plot. */
+export interface StudyValue {
+    $time: number;
+    [plot: string]: number;
+}
+export type StudyChange = 'plots' | 'graphic' | StrategyReportChange;
+export interface StudyEvents {
+    [event: string]: unknown[];
+    /** The server started (re)computing the study. */
+    loading: [];
+    /** The study finished computing over the loaded bars. */
+    ready: [];
+    update: [changes: StudyChange[]];
+    error: [error: TradingViewError];
+}
+/** @internal Link between a study and its chart. */
+export interface StudyBridge {
+    chartId: string;
+    send(method: string, params: unknown[]): void;
+    barsBack(): Map<number, number>;
+    log(...args: unknown[]): void;
+    unregister(id: string): void;
+}
+/** An indicator running on a chart. Create it with `chart.createStudy(indicator)`. */
+export declare class Study extends Emitter<StudyEvents> {
+    #private;
+    readonly id: string;
+    /** @internal Use `chart.createStudy()`. */
+    constructor(bridge: StudyBridge, indicator: Indicator);
+    /** @internal */
+    create(): void;
+    /** The indicator definition running in this study. */
+    get indicator(): Indicator;
+    /** True after the first `study_completed`. */
+    get isReady(): boolean;
+    /** True after `remove()` or when the chart is gone. */
+    get isRemoved(): boolean;
+    /** Plot values, oldest first. */
+    get values(): StudyValue[];
+    /** Drawings (labels, lines, boxes, tables...) produced by the indicator. */
+    get graphics(): GraphicsData;
+    /** Strategy report (Pine strategies only). */
+    get strategyReport(): StrategyReport;
+    /** Replaces the indicator (typically the same script with new inputs). */
+    setIndicator(indicator: Indicator): void;
+    /** Removes the study from the chart. Idempotent. */
+    remove(): void;
+    /** @internal Called when the chart or connection is gone; `error` is reported if set. */
+    dispose(error?: TradingViewError): void;
+    /** @internal Packets addressed to this study (`study_*`). */
+    onPacket(packet: ServerPacket): void;
+    /** @internal Data from `timescale_update` / `du`. */
+    onData(data: any): void;
+}