@mathieuc/tradingview 3.5.2 → 4.0.0-beta.0

package/dist/data/candles.js

@@ -0,0 +1,101 @@
+import { TradingViewError } from '../errors.js';
+import { loadHistory, noDataError, openMarket, planHistory, selectCandles, } from './history.js';
+import { runOperation, startWatcher, } from './operation.js';
+/**
+ * Fetches candles once, oldest first, then releases every resource.
+ *
+ * - `{ symbol, timeframe, count }`: the `count` most recent bars (deep history
+ *   is loaded automatically when `count` exceeds one server batch).
+ * - `{ symbol, timeframe, from, to }`: every bar in the range.
+ *
+ * @example
+ * const candles = await getCandles({ symbol: 'BINANCE:BTCUSDT', timeframe: '60', count: 500 });
+ */
+export function getCandles(query, provider) {
+    const options = typeof query === 'string' ? { symbol: query } : query;
+    let plan;
+    try {
+        plan = planHistory(options);
+    }
+    catch (error) {
+        return Promise.reject(error);
+    }
+    if (provider) {
+        return (async () => {
+            let snapshot = [];
+            const worker = await provider.watchCandles(options, {
+                onData: (candles) => { snapshot = candles; },
+            });
+            try {
+                return [...(snapshot.length ? snapshot : worker.latest)];
+            }
+            finally {
+                await worker.stop();
+            }
+        })();
+    }
+    return runOperation(options, `getCandles(${plan.symbol})`, ({ client, resolve, reject }) => {
+        const chart = client.createChart();
+        chart.on('error', reject);
+        loadHistory(chart, plan, true, (info) => {
+            const candles = selectCandles(chart.candles, plan);
+            if (candles.length === 0)
+                reject(noDataError(plan.symbol, info));
+            else
+                resolve(candles);
+        });
+        openMarket(chart, plan);
+        return () => chart.delete();
+    });
+}
+export function watchCandles(query, handlers, provider) {
+    let plan;
+    try {
+        if (typeof handlers?.onData !== 'function')
+            throw new TradingViewError('INVALID_ARGUMENT', 'onData must be a function');
+        plan = planHistory({ ...query, from: undefined, to: undefined });
+    }
+    catch (error) {
+        return Promise.reject(error);
+    }
+    if (provider)
+        return provider.watchCandles(query, handlers);
+    let latest = Object.freeze([]);
+    let symbolInfo;
+    return startWatcher(query, `watchCandles(${plan.symbol})`, handlers, (ctx) => {
+        const chart = ctx.client.createChart();
+        let started = false;
+        const publish = () => {
+            latest = Object.freeze(selectCandles(chart.candles, plan).map((candle) => Object.freeze({ ...candle })));
+            try {
+                handlers.onData(latest);
+            }
+            catch (error) {
+                ctx.warn(new TradingViewError('CALLBACK_ERROR', 'onData callback threw', { cause: error }));
+            }
+        };
+        chart.on('error', (error) => ctx.fail(error));
+        chart.on('symbolLoaded', (info) => { symbolInfo = info; });
+        chart.on('update', (changes) => {
+            if (started && ctx.isActive() && changes.includes('$prices'))
+                publish();
+        });
+        loadHistory(chart, plan, false, (info) => {
+            if (chart.candles.length === 0) {
+                ctx.fail(noDataError(plan.symbol, info));
+                return;
+            }
+            started = true;
+            publish();
+            ctx.ready();
+        });
+        openMarket(chart, plan);
+        return () => chart.delete();
+    }, (base) => ({
+        stop: base.stop,
+        closed: base.closed,
+        get isActive() { return base.isActive; },
+        get latest() { return latest; },
+        get symbolInfo() { return symbolInfo; },
+    }));
+}

package/dist/data/history.d.ts

@@ -0,0 +1,61 @@
+import type { ChartSession, MarketOptions, SeriesCompletedInfo } from '../chart/chart-session.js';
+import type { Adjustment, Candle, ChartType, ChartTypeInputs, Timeframe, Timezone, TradingSession } from '../chart/types.js';
+import { TradingViewError } from '../errors.js';
+/** Chart settings shared by candle and indicator queries. */
+export interface ChartQuery {
+    /** Exchange-qualified symbol, e.g. `BINANCE:BTCUSDT`. */
+    symbol: string;
+    /** Bar resolution (`1`, `15`, `60`, `240`, `D`, `W`, `M`, `1S`...). Default: `D`. */
+    timeframe?: Timeframe;
+    /** Number of most recent bars. Default: 100. */
+    count?: number;
+    /** Custom bar type: `HeikinAshi`, `Renko`, `LineBreak`, `Kagi`, `PointAndFigure` or `Range`. */
+    chartType?: ChartType;
+    /** Inputs for `chartType`. */
+    chartInputs?: ChartTypeInputs;
+    /** Convert prices to this currency, e.g. `EUR`. */
+    currency?: string;
+    /** `regular` or `extended` trading session. */
+    session?: TradingSession;
+    /** Price adjustment. Default: `splits`. */
+    adjustment?: Adjustment;
+    /** Back-adjust continuous futures contracts. */
+    backAdjustment?: boolean;
+    /** Chart timezone (affects how daily and longer bars are aligned). */
+    timezone?: Timezone;
+}
+/** Historical range options. */
+export interface RangeQuery {
+    /**
+     * Oldest bar time (Date or Unix seconds). When set, history is loaded back
+     * to this time (deep history) and `count` is ignored.
+     */
+    from?: number | Date;
+    /** Newest bar time (Date or Unix seconds). Default: now. */
+    to?: number | Date;
+    /** Safety cap on bars loaded for a `from` range. Default: 20 000. */
+    maxCount?: number;
+}
+export interface HistoryPlan {
+    symbol: string;
+    market: MarketOptions;
+    timezone?: Timezone;
+    count: number;
+    from?: number;
+    to?: number;
+    maxCount: number;
+}
+/** Validates a query and computes how many bars to request first. */
+export declare function planHistory(query: ChartQuery & RangeQuery): HistoryPlan;
+/** Selects the requested bars from everything loaded on a chart. */
+export declare function selectCandles(candles: Candle[], plan: Pick<HistoryPlan, 'from' | 'to' | 'count'>): Candle[];
+/** Opens the market on a chart according to a plan. */
+export declare function openMarket(chart: ChartSession, plan: HistoryPlan): void;
+/**
+ * Loads history: after each `series_completed`, requests more bars until the
+ * plan is satisfied or the server has no more data. `onDone` receives the
+ * last completion info.
+ */
+export declare function loadHistory(chart: ChartSession, plan: HistoryPlan, deep: boolean, onDone: (info: SeriesCompletedInfo) => void): () => void;
+/** Error for an empty result, with the server's reason when known. */
+export declare function noDataError(symbol: string, info?: SeriesCompletedInfo): TradingViewError;

package/dist/data/history.js

@@ -0,0 +1,101 @@
+import { timeframeSeconds } from '../chart/timeframes.js';
+import { TradingViewError } from '../errors.js';
+import { toUnixSeconds, validateSymbol } from './operation.js';
+const MAX_CHUNK = 5_000;
+function positiveInteger(value, name, fallback) {
+    const result = value ?? fallback;
+    if (!Number.isInteger(result) || result < 1) {
+        throw new TradingViewError('INVALID_ARGUMENT', `${name} must be a positive integer`);
+    }
+    return result;
+}
+/** Validates a query and computes how many bars to request first. */
+export function planHistory(query) {
+    const symbol = validateSymbol(query.symbol);
+    const count = positiveInteger(query.count, 'count', 100);
+    const maxCount = positiveInteger(query.maxCount, 'maxCount', 20_000);
+    const from = toUnixSeconds(query.from, 'from');
+    const to = toUnixSeconds(query.to, 'to');
+    if (from !== undefined && to !== undefined && from > to) {
+        throw new TradingViewError('INVALID_ARGUMENT', 'from must be before to');
+    }
+    const timeframe = query.timeframe ?? 'D';
+    let initial = Math.min(count, MAX_CHUNK);
+    if (from !== undefined) {
+        const step = timeframeSeconds(timeframe);
+        const end = to ?? Math.floor(Date.now() / 1000);
+        initial = step ? Math.ceil((end - from) / step) + 2 : 1_000;
+        initial = Math.max(1, Math.min(initial, maxCount, MAX_CHUNK));
+    }
+    return {
+        symbol,
+        count,
+        from,
+        to,
+        maxCount,
+        timezone: query.timezone,
+        market: {
+            timeframe,
+            count: initial,
+            to,
+            type: query.chartType,
+            inputs: query.chartInputs,
+            currency: query.currency,
+            session: query.session,
+            adjustment: query.adjustment,
+            backAdjustment: query.backAdjustment,
+        },
+    };
+}
+/** Selects the requested bars from everything loaded on a chart. */
+export function selectCandles(candles, plan) {
+    let result = candles;
+    if (plan.to !== undefined)
+        result = result.filter((candle) => candle.time <= plan.to);
+    if (plan.from !== undefined)
+        return result.filter((candle) => candle.time >= plan.from);
+    return result.slice(-plan.count);
+}
+/** Opens the market on a chart according to a plan. */
+export function openMarket(chart, plan) {
+    if (plan.timezone)
+        chart.setTimezone(plan.timezone);
+    chart.setMarket(plan.symbol, plan.market);
+}
+/**
+ * Loads history: after each `series_completed`, requests more bars until the
+ * plan is satisfied or the server has no more data. `onDone` receives the
+ * last completion info.
+ */
+export function loadHistory(chart, plan, deep, onDone) {
+    let previousSize = -1;
+    let done = false;
+    return chart.on('seriesCompleted', (info) => {
+        if (done)
+            return;
+        const candles = chart.candles;
+        const inRange = plan.to === undefined ? candles : candles.filter((c) => c.time <= plan.to);
+        const target = plan.from !== undefined ? plan.maxCount : plan.count;
+        const satisfied = plan.from !== undefined
+            ? (inRange[0] !== undefined && inRange[0].time <= plan.from)
+            : inRange.length >= plan.count;
+        const exhausted = info.dataCompleted !== undefined || candles.length <= previousSize;
+        if (!deep || satisfied || exhausted || candles.length >= target) {
+            done = true;
+            onDone(info);
+            return;
+        }
+        previousSize = candles.length;
+        const missing = plan.from !== undefined ? MAX_CHUNK : plan.count - inRange.length;
+        chart.fetchMore(Math.max(1, Math.min(missing, MAX_CHUNK, target - candles.length)));
+    });
+}
+/** Error for an empty result, with the server's reason when known. */
+export function noDataError(symbol, info) {
+    const reason = info?.dataCompleted === 'limit'
+        ? ' (the server reported an access limit: this range or timeframe may need an account with access)'
+        : '';
+    return new TradingViewError('NO_DATA', `No candles available for ${symbol} in the requested range${reason}`, {
+        details: info?.raw,
+    });
+}

package/dist/data/index.d.ts

@@ -0,0 +1,28 @@
+/**
+ * High-level data API: one-shot functions and watchers that manage
+ * connections, sessions, timeouts and cleanup for you.
+ *
+ * @module @mathieuc/tradingview/data
+ */
+export { getCandles, watchCandles } from './candles.js';
+export type { CandleHandlers, CandleQuery, CandleWatcher, WatchCandlesQuery, } from './candles.js';
+export { TradingViewProvider } from './provider.js';
+export type { CandleSourceWorker, MarketDataProvider } from './provider.js';
+export { getQuote, getQuotes, watchQuotes } from './quotes.js';
+export type { QuoteHandlers, QuoteOptions, QuoteQuery, QuotesQuery, QuoteWatcher, } from './quotes.js';
+export { getSymbolInfo } from './symbols.js';
+export type { SymbolInfoQuery } from './symbols.js';
+export { getIndicatorData, watchIndicator } from './indicators.js';
+export type { IndicatorData, IndicatorHandlers, IndicatorQuery, IndicatorWatcher, } from './indicators.js';
+export type { ChartQuery, RangeQuery } from './history.js';
+export { DEFAULT_TIMEOUT_MS } from './operation.js';
+export type { ConnectionOptions, OperationOptions, WatchHandlers, Watcher, } from './operation.js';
+export { getTechnicalAnalysis, searchIndicators, searchMarkets, } from '../http/index.js';
+export type { Credentials, IndicatorSearchResult, MarketSearchResult, SearchMarketsOptions, TechnicalAnalysis, TechnicalRating, } from '../http/index.js';
+export { TradingViewError } from '../errors.js';
+export type { TradingViewErrorCode } from '../errors.js';
+export type { Candle, ChartType, ChartTypeInputs, SymbolInfo, Timeframe, Timezone, } from '../chart/types.js';
+export type { QuoteData, QuoteField } from '../quote/fields.js';
+export type { StudyValue } from '../chart/study.js';
+export type { GraphicsData } from '../chart/graphics.js';
+export type { StrategyReport } from '../chart/strategy.js';

package/dist/data/index.js

@@ -0,0 +1,15 @@
+/**
+ * High-level data API: one-shot functions and watchers that manage
+ * connections, sessions, timeouts and cleanup for you.
+ *
+ * @module @mathieuc/tradingview/data
+ */
+export { getCandles, watchCandles } from './candles.js';
+export { TradingViewProvider } from './provider.js';
+export { getQuote, getQuotes, watchQuotes } from './quotes.js';
+export { getSymbolInfo } from './symbols.js';
+export { getIndicatorData, watchIndicator } from './indicators.js';
+export { DEFAULT_TIMEOUT_MS } from './operation.js';
+// Plain HTTP lookups are already one-shot; they are part of the data API too.
+export { getTechnicalAnalysis, searchIndicators, searchMarkets, } from '../http/index.js';
+export { TradingViewError } from '../errors.js';

package/dist/data/indicators.d.ts

@@ -0,0 +1,54 @@
+import type { GraphicsData } from '../chart/graphics.js';
+import type { StrategyReport } from '../chart/strategy.js';
+import type { StudyValue } from '../chart/study.js';
+import type { Candle } from '../chart/types.js';
+import type { Indicator } from '../indicators/index.js';
+import { type ChartQuery } from './history.js';
+import { type OperationOptions, type WatchHandlers, type Watcher } from './operation.js';
+export interface IndicatorQuery extends ChartQuery, OperationOptions {
+    /**
+     * Indicator to run: a script ID (`STD;RSI`, `PUB;xxxx`, `USER;xxxx`), a
+     * built-in study type (`Volume@tv-basicstudies-241`), or an instance.
+     */
+    indicator: string | Indicator;
+    /** Script version when `indicator` is a script ID. Default: `last`. */
+    version?: string;
+    /** Input values (Pine) or options (built-in) to apply. */
+    inputs?: Record<string, unknown>;
+    /** Newest bar time (Date or Unix seconds). Default: now. */
+    to?: number | Date;
+}
+export interface IndicatorData {
+    indicator: Indicator;
+    /** Chart bars, oldest first. */
+    candles: Candle[];
+    /**
+     * Plot values, oldest first. The server may compute a few rows before the
+     * first returned candle.
+     */
+    values: StudyValue[];
+    /** Drawings (labels, lines, boxes, tables...). */
+    graphics: GraphicsData;
+    /** Strategy report (strategies only; otherwise empty). */
+    strategyReport: StrategyReport;
+}
+/** Resolves an indicator ID or instance and applies inputs. */
+export declare function resolveIndicator(query: IndicatorQuery): Promise<Indicator>;
+/**
+ * Runs an indicator or strategy once and returns its values, drawings and
+ * strategy report.
+ *
+ * @example
+ * const { values } = await getIndicatorData({ symbol: 'BINANCE:BTCUSDT', indicator: 'STD;RSI' });
+ */
+export declare function getIndicatorData(query: IndicatorQuery): Promise<IndicatorData>;
+export interface IndicatorHandlers extends WatchHandlers {
+    /** Receives a fresh result on every study update. */
+    onData(data: IndicatorData): void;
+}
+export interface IndicatorWatcher extends Watcher {
+    /** Latest result. */
+    readonly latest: IndicatorData | undefined;
+}
+/** Streams an indicator in real time. Call `stop()` when finished. */
+export declare function watchIndicator(query: IndicatorQuery, handlers: IndicatorHandlers): Promise<IndicatorWatcher>;

package/dist/data/indicators.js

@@ -0,0 +1,139 @@
+import { TradingViewError, toTradingViewError } from '../errors.js';
+import { getIndicator } from '../http/indicators.js';
+import { BuiltInIndicator } from '../indicators/builtin-indicator.js';
+import { PineIndicator } from '../indicators/pine-indicator.js';
+import { loadHistory, noDataError, openMarket, planHistory, selectCandles, } from './history.js';
+import { runOperation, startWatcher, throwIfAborted, } from './operation.js';
+/** Resolves an indicator ID or instance and applies inputs. */
+export async function resolveIndicator(query) {
+    const { indicator, inputs } = query;
+    let resolved;
+    if (indicator instanceof PineIndicator)
+        resolved = indicator.clone();
+    else if (indicator instanceof BuiltInIndicator)
+        resolved = new BuiltInIndicator(indicator.type, indicator.options);
+    else if (typeof indicator === 'string' && indicator.trim()) {
+        resolved = indicator.includes('@')
+            ? new BuiltInIndicator(indicator)
+            : await getIndicator(indicator, {
+                version: query.version,
+                credentials: query.credentials,
+                signal: query.signal,
+                fetch: query.clientOptions?.fetch,
+            });
+    }
+    else {
+        throw new TradingViewError('INVALID_ARGUMENT', 'indicator must be a script ID, a built-in type or an indicator instance');
+    }
+    for (const [key, value] of Object.entries(inputs ?? {})) {
+        if (resolved instanceof PineIndicator)
+            resolved.setInput(key, value);
+        else
+            resolved.setOption(key, value);
+    }
+    return resolved;
+}
+function snapshot(chart, study, plan) {
+    return {
+        indicator: study.indicator,
+        candles: selectCandles(chart.candles, plan),
+        values: study.values,
+        graphics: study.graphics,
+        strategyReport: structuredClone(study.strategyReport),
+    };
+}
+/**
+ * Runs history loading and the study together; calls `onReady` once both
+ * the bars and the study computation are complete.
+ */
+function trackReadiness(chart, study, plan, deep, onReady, onEmpty) {
+    let historyDone = false;
+    let studyLoading = true;
+    let fired = false;
+    const check = () => {
+        if (fired || !historyDone || studyLoading)
+            return;
+        fired = true;
+        onReady();
+    };
+    study.on('loading', () => { studyLoading = true; });
+    study.on('ready', () => { studyLoading = false; check(); });
+    loadHistory(chart, plan, deep, (info) => {
+        if (chart.candles.length === 0) {
+            fired = true;
+            onEmpty(noDataError(plan.symbol, info));
+            return;
+        }
+        historyDone = true;
+        check();
+    });
+}
+function prepare(query) {
+    return planHistory({ ...query, from: undefined });
+}
+/**
+ * Runs an indicator or strategy once and returns its values, drawings and
+ * strategy report.
+ *
+ * @example
+ * const { values } = await getIndicatorData({ symbol: 'BINANCE:BTCUSDT', indicator: 'STD;RSI' });
+ */
+export async function getIndicatorData(query) {
+    const plan = prepare(query);
+    throwIfAborted(query.signal);
+    const indicator = await resolveIndicator(query).catch((error) => {
+        throw toTradingViewError(error, 'NOT_FOUND');
+    });
+    return runOperation(query, `getIndicatorData(${plan.symbol})`, ({ client, resolve, reject }) => {
+        const chart = client.createChart();
+        chart.on('error', reject);
+        openMarket(chart, plan);
+        const study = chart.createStudy(indicator);
+        study.on('error', reject);
+        trackReadiness(chart, study, plan, true, () => resolve(snapshot(chart, study, plan)), reject);
+        return () => chart.delete();
+    });
+}
+/** Streams an indicator in real time. Call `stop()` when finished. */
+export async function watchIndicator(query, handlers) {
+    if (typeof handlers?.onData !== 'function')
+        throw new TradingViewError('INVALID_ARGUMENT', 'onData must be a function');
+    const plan = prepare({ ...query, to: undefined });
+    throwIfAborted(query.signal);
+    const indicator = await resolveIndicator(query).catch((error) => {
+        throw toTradingViewError(error, 'NOT_FOUND');
+    });
+    let latest;
+    return startWatcher(query, `watchIndicator(${plan.symbol})`, handlers, (ctx) => {
+        const chart = ctx.client.createChart();
+        let started = false;
+        const publish = () => {
+            latest = snapshot(chart, study, plan);
+            try {
+                handlers.onData(latest);
+            }
+            catch (error) {
+                ctx.warn(new TradingViewError('CALLBACK_ERROR', 'onData callback threw', { cause: error }));
+            }
+        };
+        chart.on('error', (error) => ctx.fail(error));
+        openMarket(chart, plan);
+        const study = chart.createStudy(indicator);
+        study.on('error', (error) => ctx.fail(error));
+        study.on('update', () => {
+            if (started && ctx.isActive())
+                publish();
+        });
+        trackReadiness(chart, study, plan, false, () => {
+            started = true;
+            publish();
+            ctx.ready();
+        }, (error) => ctx.fail(error));
+        return () => chart.delete();
+    }, (base) => ({
+        stop: base.stop,
+        closed: base.closed,
+        get isActive() { return base.isActive; },
+        get latest() { return latest; },
+    }));
+}

package/dist/data/operation.d.ts

@@ -0,0 +1,71 @@
+import { TradingViewClient, type ClientOptions } from '../client/client.js';
+import { TradingViewError } from '../errors.js';
+import type { Credentials } from '../http/request.js';
+/** How high-level functions connect to TradingView. */
+export interface ConnectionOptions {
+    /**
+     * Reuse an existing connection. It is left open afterwards; only the
+     * sessions created by the call are removed. Without it, each call opens and
+     * closes its own connection.
+     */
+    client?: TradingViewClient;
+    /** Account cookies, for data your account can access. Ignored with `client`. */
+    credentials?: Credentials;
+    /** Other options for the connection opened by the call. Ignored with `client`. */
+    clientOptions?: Omit<ClientOptions, 'credentials'>;
+}
+export interface OperationOptions extends ConnectionOptions {
+    /**
+     * Maximum wait in milliseconds. One-shot functions: for the whole call.
+     * Watchers: until the first data. Default: 15 000.
+     */
+    timeoutMs?: number;
+    /** Cancels the call (and stops a watcher). */
+    signal?: AbortSignal;
+}
+export declare const DEFAULT_TIMEOUT_MS = 15000;
+export declare function validateTimeout(timeoutMs: number | undefined): number;
+export declare function validateSymbol(symbol: unknown): string;
+export declare function throwIfAborted(signal?: AbortSignal): void;
+export interface OperationContext<T> {
+    client: TradingViewClient;
+    resolve(value: T): void;
+    reject(error: unknown): void;
+}
+type Cleanup = (() => void) | void;
+/**
+ * Runs a one-shot operation with timeout, abort and guaranteed cleanup:
+ * sessions are removed and an owned connection is closed before settling.
+ */
+export declare function runOperation<T>(options: OperationOptions, description: string, start: (context: OperationContext<T>) => Cleanup): Promise<T>;
+/** A running watcher. */
+export interface Watcher {
+    /** Stops the watcher and releases its sessions/connection. Idempotent. */
+    stop(): Promise<void>;
+    /** Resolves when the watcher has stopped (after `stop()`, abort or a fatal error). */
+    readonly closed: Promise<void>;
+    /** True until the watcher stops. */
+    readonly isActive: boolean;
+}
+export interface WatchHandlers {
+    /** Errors after start-up. Fatal errors also stop the watcher. */
+    onError?(error: TradingViewError): void;
+}
+export interface WatchContext {
+    client: TradingViewClient;
+    /** Marks the watcher as started (resolves the start promise). */
+    ready(): void;
+    /** Before start-up: rejects. After: reports to `onError` and stops. */
+    fail(error: unknown): void;
+    /** Reports a non-fatal error to `onError`. */
+    warn(error: unknown): void;
+    isActive(): boolean;
+}
+/**
+ * Starts a watcher. The returned promise resolves once `ready()` is called
+ * and rejects on timeout, abort or failure before that.
+ */
+export declare function startWatcher<W extends Watcher>(options: OperationOptions, description: string, handlers: WatchHandlers, start: (context: WatchContext) => Cleanup, build: (base: Watcher) => W): Promise<W>;
+/** Converts a Date or Unix time (seconds) into Unix seconds. */
+export declare function toUnixSeconds(value: number | Date | undefined, name: string): number | undefined;
+export {};