lightweight-charts-mtf 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 lightweight-charts-mtf contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,198 @@
+# lightweight-charts-mtf
+
+Multi-timeframe (MTF) candle display plugin for [TradingView Lightweight Charts](https://github.com/nickolasburr/lightweight-charts). Renders higher-timeframe candles as native candlestick series alongside your main chart.
+
+![lightweight-charts >=4.0.0](https://img.shields.io/badge/lightweight--charts-%3E%3D4.0.0-blue)
+![npm](https://img.shields.io/npm/v/lightweight-charts-mtf)
+![license](https://img.shields.io/npm/l/lightweight-charts-mtf)
+
+## Features
+
+- Display any number of higher-timeframe columns next to your main chart
+- Native candlestick rendering — HTF candles share the same price scale
+- Accepts any timeframe string as label (e.g. `'4H'`, `'1D'`, `'1W'`, `'1M'`)
+- Built-in OHLC aggregation from lower timeframes (4H, 8H, 12H, 1D, 1W, 1M, 3M, 6M, 1Y)
+- Per-column candle colors (body + wick, up + down)
+- Separator lines and labels between columns
+- Configurable gap between main chart and HTF zone, and between HTF columns
+
+## Install
+
+```bash
+npm install lightweight-charts-mtf
+```
+
+## Quick Start
+
+### With pre-aggregated data (from API)
+
+If your data source already provides higher-timeframe candles (e.g., Bybit, Binance):
+
+```typescript
+import { createChart, CandlestickSeries } from 'lightweight-charts';
+import { MTFPrimitive } from 'lightweight-charts-mtf';
+
+const chart = createChart(container);
+const mainSeries = chart.addSeries(CandlestickSeries);
+
+// Fetch data at different timeframes from your API
+const hourlyData = await fetchKlines('BTCUSDT', '1h');
+const dailyData = await fetchKlines('BTCUSDT', '1d');
+const weeklyData = await fetchKlines('BTCUSDT', '1w');
+
+// Create and attach
+const mtf = new MTFPrimitive({
+  columns: [
+    { timeframe: '1D', data: dailyData, candleCount: 6 },
+    { timeframe: '1W', data: weeklyData, candleCount: 4 },
+  ],
+  gap: 5,
+  columnGap: 2,
+});
+
+mtf.attach(chart, mainSeries, hourlyData);
+```
+
+### With self-aggregated data
+
+If you only have lower-timeframe data and need to derive higher timeframes:
+
+```typescript
+import { createChart, CandlestickSeries } from 'lightweight-charts';
+import { MTFPrimitive, aggregateOHLC } from 'lightweight-charts-mtf';
+
+const chart = createChart(container);
+const mainSeries = chart.addSeries(CandlestickSeries);
+
+const hourlyData = [...];
+
+// Aggregate into higher timeframes
+const fourHour = aggregateOHLC(hourlyData, '4H');
+const daily = aggregateOHLC(hourlyData, '1D');
+const weekly = aggregateOHLC(hourlyData, '1W');
+
+const mtf = new MTFPrimitive({
+  columns: [
+    { timeframe: '4H', data: fourHour, candleCount: 10 },
+    { timeframe: '1D', data: daily, candleCount: 6 },
+    { timeframe: '1W', data: weekly, candleCount: 4 },
+  ],
+  gap: 5,
+  columnGap: 2,
+});
+
+mtf.attach(chart, mainSeries, hourlyData);
+```
+
+## Data Format
+
+The plugin accepts standard Lightweight Charts OHLC data:
+
+```typescript
+// Unix timestamp (seconds)
+{ time: 1704067200, open: 42000, high: 42500, low: 41800, close: 42300, volume: 1500 }
+
+// Date string
+{ time: '2024-01-01', open: 42000, high: 42500, low: 41800, close: 42300 }
+
+// Object
+{ time: { year: 2024, month: 1, day: 1 }, open: 42000, high: 42500, low: 41800, close: 42300 }
+```
+
+The `volume` field is optional.
+
+## Aggregation
+
+If your data source doesn't provide higher-timeframe candles directly, use `aggregateOHLC`:
+
+```typescript
+import { aggregateOHLC } from 'lightweight-charts-mtf';
+
+const fourHour = aggregateOHLC(hourlyCandles, '4H');
+const daily = aggregateOHLC(hourlyCandles, '1D');
+const weekly = aggregateOHLC(hourlyCandles, '1W');
+const monthly = aggregateOHLC(dailyCandles, '1M');
+```
+
+Supported periods: `'4H'`, `'8H'`, `'12H'`, `'1D'`, `'1W'`, `'1M'`, `'3M'`, `'6M'`, `'1Y'`
+
+Legacy helpers are also available:
+
+```typescript
+import { aggregateToWeekly, aggregateToMonthly } from 'lightweight-charts-mtf';
+```
+
+## Options
+
+```typescript
+interface MTFOptions {
+  columns: HTFColumnConfig[];
+  gap?: number;                // whitespace bars between main chart and HTF (default: 5)
+  columnGap?: number;          // whitespace bars between HTF columns (default: 2)
+  showSeparators?: boolean;    // default: true
+  separatorColor?: string;     // default: 'rgba(255,255,255,0.08)'
+  showLabels?: boolean;        // default: true
+  labelFont?: string;          // default: '11px sans-serif'
+  labelColor?: string;         // default: 'rgba(255,255,255,0.5)'
+}
+
+interface HTFColumnConfig {
+  timeframe: string;           // any label: '4H', '1D', '1W', etc.
+  data: OHLCData[];
+  candleCount?: number;        // default: 6
+  upColor?: string;            // default: '#26a69a'
+  downColor?: string;          // default: '#ef5350'
+  wickUpColor?: string;        // defaults to upColor
+  wickDownColor?: string;      // defaults to downColor
+  borderVisible?: boolean;     // default: false
+  borderUpColor?: string;      // defaults to upColor
+  borderDownColor?: string;    // defaults to downColor
+}
+```
+
+## API
+
+```typescript
+// Create the plugin
+const mtf = new MTFPrimitive(options);
+
+// Attach to chart (creates HTF series and renders)
+mtf.attach(chart, mainSeries, mainData);
+
+// Update with new data and/or options
+mtf.update(newMainData);
+mtf.update(newMainData, { columns: [...], gap: 8 });
+
+// Update a single column's data
+mtf.updateColumnData(0, newWeeklyData);
+
+// Detach and clean up
+mtf.detach();
+```
+
+## Example
+
+See [`example/index.html`](./example/index.html) for a live demo using BTC data from Bybit with configurable base timeframe, HTF columns, gap, and column gap.
+
+To run locally:
+
+```bash
+npm run build
+npx serve .
+# Open http://localhost:3000/example/
+```
+
+## Development
+
+```bash
+npm install
+npm run build       # Build CJS, ESM, and type declarations
+npm run dev         # Watch mode
+npm run typecheck   # Type check without emitting
+npm test            # Run unit tests
+npm run test:watch  # Watch mode for tests
+```
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -0,0 +1,82 @@
+import { Time, IChartApi, ISeriesApi } from 'lightweight-charts';
+
+/** OHLC candle data for a single timeframe period */
+interface OHLCData {
+    time: Time;
+    open: number;
+    high: number;
+    low: number;
+    close: number;
+    volume?: number;
+}
+/** Supported higher timeframes — any string label is accepted */
+type HTFTimeframe = string;
+/** Configuration for a single HTF column displayed to the right */
+interface HTFColumnConfig {
+    /** Timeframe label (e.g., '1W', '1M') */
+    timeframe: HTFTimeframe;
+    /** OHLC data for this timeframe — most recent N candles */
+    data: OHLCData[];
+    /** Number of candles to display (default: 6) */
+    candleCount?: number;
+    /** Up candle color */
+    upColor?: string;
+    /** Down candle color */
+    downColor?: string;
+    /** Wick color for up candles (defaults to upColor) */
+    wickUpColor?: string;
+    /** Wick color for down candles (defaults to downColor) */
+    wickDownColor?: string;
+    /** Border visible on candle bodies (default: false) */
+    borderVisible?: boolean;
+    /** Border up color */
+    borderUpColor?: string;
+    /** Border down color */
+    borderDownColor?: string;
+}
+/** Options for the MTF plugin */
+interface MTFOptions {
+    /** Array of HTF columns to display, ordered left-to-right */
+    columns: HTFColumnConfig[];
+    /** Number of whitespace bars between main chart and first HTF column (default: 5) */
+    gap?: number;
+    /** Number of whitespace bars between HTF columns (default: 2) */
+    columnGap?: number;
+    /** Show separator lines between columns (default: true) */
+    showSeparators?: boolean;
+    /** Separator line color (default: 'rgba(255,255,255,0.08)') */
+    separatorColor?: string;
+    /** Show timeframe labels (default: true) */
+    showLabels?: boolean;
+    /** Label font (default: '11px sans-serif') */
+    labelFont?: string;
+    /** Label color (default: 'rgba(255,255,255,0.5)') */
+    labelColor?: string;
+}
+
+declare class MTFPrimitive {
+    private _chart;
+    private _mainSeries;
+    private _htfSeries;
+    private _separator;
+    private _options;
+    private _barDuration;
+    constructor(options: MTFOptions);
+    attach(chart: IChartApi, mainSeries: ISeriesApi<any>, mainData: OHLCData[]): void;
+    detach(): void;
+    update(mainData: OHLCData[], options?: Partial<MTFOptions>): void;
+    updateColumnData(columnIndex: number, data: OHLCData[]): void;
+    private _createHTFSeries;
+    private _removeHTFSeries;
+    private _render;
+    private _detectBarDuration;
+    private _getTimeAsNumber;
+    private _resolveOptions;
+}
+
+type AggregationPeriod = '4H' | '8H' | '12H' | '1D' | '1W' | '1M' | '3M' | '6M' | '1Y';
+declare function aggregateOHLC(data: OHLCData[], period: AggregationPeriod): OHLCData[];
+declare function aggregateToWeekly(data: OHLCData[]): OHLCData[];
+declare function aggregateToMonthly(data: OHLCData[]): OHLCData[];
+
+export { type AggregationPeriod, type HTFColumnConfig, type HTFTimeframe, type MTFOptions, MTFPrimitive, type OHLCData, aggregateOHLC, aggregateToMonthly, aggregateToWeekly };

package/dist/index.d.ts

@@ -0,0 +1,82 @@
+import { Time, IChartApi, ISeriesApi } from 'lightweight-charts';
+
+/** OHLC candle data for a single timeframe period */
+interface OHLCData {
+    time: Time;
+    open: number;
+    high: number;
+    low: number;
+    close: number;
+    volume?: number;
+}
+/** Supported higher timeframes — any string label is accepted */
+type HTFTimeframe = string;
+/** Configuration for a single HTF column displayed to the right */
+interface HTFColumnConfig {
+    /** Timeframe label (e.g., '1W', '1M') */
+    timeframe: HTFTimeframe;
+    /** OHLC data for this timeframe — most recent N candles */
+    data: OHLCData[];
+    /** Number of candles to display (default: 6) */
+    candleCount?: number;
+    /** Up candle color */
+    upColor?: string;
+    /** Down candle color */
+    downColor?: string;
+    /** Wick color for up candles (defaults to upColor) */
+    wickUpColor?: string;
+    /** Wick color for down candles (defaults to downColor) */
+    wickDownColor?: string;
+    /** Border visible on candle bodies (default: false) */
+    borderVisible?: boolean;
+    /** Border up color */
+    borderUpColor?: string;
+    /** Border down color */
+    borderDownColor?: string;
+}
+/** Options for the MTF plugin */
+interface MTFOptions {
+    /** Array of HTF columns to display, ordered left-to-right */
+    columns: HTFColumnConfig[];
+    /** Number of whitespace bars between main chart and first HTF column (default: 5) */
+    gap?: number;
+    /** Number of whitespace bars between HTF columns (default: 2) */
+    columnGap?: number;
+    /** Show separator lines between columns (default: true) */
+    showSeparators?: boolean;
+    /** Separator line color (default: 'rgba(255,255,255,0.08)') */
+    separatorColor?: string;
+    /** Show timeframe labels (default: true) */
+    showLabels?: boolean;
+    /** Label font (default: '11px sans-serif') */
+    labelFont?: string;
+    /** Label color (default: 'rgba(255,255,255,0.5)') */
+    labelColor?: string;
+}
+
+declare class MTFPrimitive {
+    private _chart;
+    private _mainSeries;
+    private _htfSeries;
+    private _separator;
+    private _options;
+    private _barDuration;
+    constructor(options: MTFOptions);
+    attach(chart: IChartApi, mainSeries: ISeriesApi<any>, mainData: OHLCData[]): void;
+    detach(): void;
+    update(mainData: OHLCData[], options?: Partial<MTFOptions>): void;
+    updateColumnData(columnIndex: number, data: OHLCData[]): void;
+    private _createHTFSeries;
+    private _removeHTFSeries;
+    private _render;
+    private _detectBarDuration;
+    private _getTimeAsNumber;
+    private _resolveOptions;
+}
+
+type AggregationPeriod = '4H' | '8H' | '12H' | '1D' | '1W' | '1M' | '3M' | '6M' | '1Y';
+declare function aggregateOHLC(data: OHLCData[], period: AggregationPeriod): OHLCData[];
+declare function aggregateToWeekly(data: OHLCData[]): OHLCData[];
+declare function aggregateToMonthly(data: OHLCData[]): OHLCData[];
+
+export { type AggregationPeriod, type HTFColumnConfig, type HTFTimeframe, type MTFOptions, MTFPrimitive, type OHLCData, aggregateOHLC, aggregateToMonthly, aggregateToWeekly };

package/dist/index.js

@@ -0,0 +1,358 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  MTFPrimitive: () => MTFPrimitive,
+  aggregateOHLC: () => aggregateOHLC,
+  aggregateToMonthly: () => aggregateToMonthly,
+  aggregateToWeekly: () => aggregateToWeekly
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/mtf-primitive.ts
+var import_lightweight_charts = require("lightweight-charts");
+var DEFAULT_OPTIONS = {
+  gap: 5,
+  columnGap: 2,
+  showSeparators: true,
+  separatorColor: "rgba(255,255,255,0.08)",
+  showLabels: true,
+  labelFont: "11px sans-serif",
+  labelColor: "rgba(255,255,255,0.5)"
+};
+var DEFAULT_COLUMN = {
+  candleCount: 6,
+  upColor: "#26a69a",
+  downColor: "#ef5350",
+  wickUpColor: "#26a69a",
+  wickDownColor: "#ef5350",
+  borderVisible: false,
+  borderUpColor: "#26a69a",
+  borderDownColor: "#ef5350"
+};
+var MTFPrimitive = class {
+  constructor(options) {
+    this._chart = null;
+    this._mainSeries = null;
+    this._htfSeries = [];
+    this._separator = null;
+    this._barDuration = 86400;
+    this._options = this._resolveOptions(options);
+  }
+  attach(chart, mainSeries, mainData) {
+    this._chart = chart;
+    this._mainSeries = mainSeries;
+    this._barDuration = this._detectBarDuration(mainData);
+    this._createHTFSeries();
+    this._render(mainData);
+  }
+  detach() {
+    this._removeHTFSeries();
+    if (this._separator && this._mainSeries) {
+      this._mainSeries.detachPrimitive(this._separator);
+      this._separator = null;
+    }
+    this._chart = null;
+    this._mainSeries = null;
+  }
+  update(mainData, options) {
+    if (options) {
+      this._options = this._resolveOptions({ ...this._options, ...options });
+      this._removeHTFSeries();
+      this._createHTFSeries();
+    }
+    this._barDuration = this._detectBarDuration(mainData);
+    this._render(mainData);
+  }
+  updateColumnData(columnIndex, data) {
+    if (columnIndex < this._options.columns.length) {
+      this._options.columns[columnIndex].data = data;
+    }
+  }
+  _createHTFSeries() {
+    if (!this._chart) return;
+    for (const col of this._options.columns) {
+      const seriesOptions = {
+        upColor: col.upColor,
+        downColor: col.downColor,
+        wickUpColor: col.wickUpColor,
+        wickDownColor: col.wickDownColor,
+        borderVisible: col.borderVisible,
+        borderUpColor: col.borderUpColor,
+        borderDownColor: col.borderDownColor
+      };
+      const series = this._chart.addSeries(import_lightweight_charts.CandlestickSeries, seriesOptions);
+      this._htfSeries.push(series);
+    }
+  }
+  _removeHTFSeries() {
+    if (!this._chart) return;
+    for (const series of this._htfSeries) {
+      this._chart.removeSeries(series);
+    }
+    this._htfSeries = [];
+  }
+  _render(mainData) {
+    if (!this._chart || !this._mainSeries || mainData.length === 0) return;
+    const lastMainTime = this._getTimeAsNumber(mainData[mainData.length - 1].time);
+    const { columns, gap, columnGap } = this._options;
+    let currentOffset = gap;
+    const columnPositions = [];
+    for (let i = 0; i < columns.length; i++) {
+      const col = columns[i];
+      const visibleData = col.data.slice(-col.candleCount);
+      const count = visibleData.length;
+      columnPositions.push({ startOffset: currentOffset, count });
+      const htfData = visibleData.map((bar, idx) => ({
+        time: lastMainTime + (currentOffset + idx + 1) * this._barDuration,
+        open: bar.open,
+        high: bar.high,
+        low: bar.low,
+        close: bar.close
+      }));
+      this._htfSeries[i].setData(htfData);
+      currentOffset += count + columnGap;
+    }
+    const totalBars = currentOffset + 2;
+    const whitespace = [];
+    for (let i = 1; i <= totalBars; i++) {
+      whitespace.push({ time: lastMainTime + i * this._barDuration });
+    }
+    this._mainSeries.setData([...mainData, ...whitespace]);
+    if (this._separator && this._mainSeries) {
+      this._mainSeries.detachPrimitive(this._separator);
+    }
+    if (this._options.showSeparators || this._options.showLabels) {
+      this._separator = new MTFSeparatorPrimitive(
+        this._options,
+        lastMainTime,
+        this._barDuration,
+        columnPositions
+      );
+      this._mainSeries.attachPrimitive(this._separator);
+    }
+    this._chart.timeScale().fitContent();
+  }
+  _detectBarDuration(data) {
+    if (data.length < 2) return 86400;
+    const t1 = this._getTimeAsNumber(data[data.length - 1].time);
+    const t2 = this._getTimeAsNumber(data[data.length - 2].time);
+    return t1 - t2;
+  }
+  _getTimeAsNumber(time) {
+    if (typeof time === "number") return time;
+    if (typeof time === "string") return Math.floor(new Date(time).getTime() / 1e3);
+    return Math.floor(
+      (/* @__PURE__ */ new Date(`${time.year}-${String(time.month).padStart(2, "0")}-${String(time.day).padStart(2, "0")}`)).getTime() / 1e3
+    );
+  }
+  _resolveOptions(options) {
+    const columns = options.columns.map((col) => ({
+      timeframe: col.timeframe,
+      data: col.data,
+      candleCount: col.candleCount ?? DEFAULT_COLUMN.candleCount,
+      upColor: col.upColor ?? DEFAULT_COLUMN.upColor,
+      downColor: col.downColor ?? DEFAULT_COLUMN.downColor,
+      wickUpColor: col.wickUpColor ?? col.upColor ?? DEFAULT_COLUMN.wickUpColor,
+      wickDownColor: col.wickDownColor ?? col.downColor ?? DEFAULT_COLUMN.wickDownColor,
+      borderVisible: col.borderVisible ?? DEFAULT_COLUMN.borderVisible,
+      borderUpColor: col.borderUpColor ?? col.upColor ?? DEFAULT_COLUMN.borderUpColor,
+      borderDownColor: col.borderDownColor ?? col.downColor ?? DEFAULT_COLUMN.borderDownColor
+    }));
+    return {
+      gap: options.gap ?? DEFAULT_OPTIONS.gap,
+      columnGap: options.columnGap ?? DEFAULT_OPTIONS.columnGap,
+      showSeparators: options.showSeparators ?? DEFAULT_OPTIONS.showSeparators,
+      separatorColor: options.separatorColor ?? DEFAULT_OPTIONS.separatorColor,
+      showLabels: options.showLabels ?? DEFAULT_OPTIONS.showLabels,
+      labelFont: options.labelFont ?? DEFAULT_OPTIONS.labelFont,
+      labelColor: options.labelColor ?? DEFAULT_OPTIONS.labelColor,
+      columns
+    };
+  }
+};
+var MTFSeparatorPrimitive = class {
+  constructor(options, lastMainTime, barDuration, columnPositions) {
+    this._options = options;
+    this._lastMainTime = lastMainTime;
+    this._barDuration = barDuration;
+    this._columnPositions = columnPositions;
+  }
+  attached() {
+  }
+  detached() {
+  }
+  updateAllViews() {
+  }
+  paneViews() {
+    return [{ renderer: () => this, zOrder: () => "bottom" }];
+  }
+  draw(target) {
+    target.useBitmapCoordinateSpace((scope) => {
+      const ctx = scope.context;
+      const hRatio = scope.horizontalPixelRatio;
+      const vRatio = scope.verticalPixelRatio;
+      const chartHeight = scope.bitmapSize.height;
+      const timeScale = this._chart?.timeScale?.();
+      if (!timeScale) return;
+      if (this._options.showSeparators) {
+        ctx.strokeStyle = this._options.separatorColor;
+        ctx.lineWidth = 1 * hRatio;
+        ctx.setLineDash([4 * hRatio, 3 * hRatio]);
+        for (const pos of this._columnPositions) {
+          const sepTime = this._lastMainTime + pos.startOffset * this._barDuration;
+          const x = timeScale.timeToCoordinate(sepTime);
+          if (x === null) continue;
+          const px = x * hRatio;
+          ctx.beginPath();
+          ctx.moveTo(px, 0);
+          ctx.lineTo(px, chartHeight);
+          ctx.stroke();
+        }
+        ctx.setLineDash([]);
+      }
+      if (this._options.showLabels) {
+        ctx.font = this._options.labelFont;
+        ctx.fillStyle = this._options.labelColor;
+        ctx.textAlign = "center";
+        ctx.textBaseline = "top";
+        for (let i = 0; i < this._columnPositions.length; i++) {
+          const pos = this._columnPositions[i];
+          const midOffset = pos.startOffset + Math.floor(pos.count / 2) + 1;
+          const labelTime = this._lastMainTime + midOffset * this._barDuration;
+          const x = timeScale.timeToCoordinate(labelTime);
+          if (x === null) continue;
+          ctx.fillText(this._options.columns[i].timeframe, x * hRatio, 8 * vRatio);
+        }
+      }
+    });
+  }
+};
+
+// src/data-aggregator.ts
+function aggregateOHLC(data, period) {
+  const getPeriodKey = getPeriodKeyFn(period);
+  return aggregateByPeriod(data, getPeriodKey);
+}
+function aggregateToWeekly(data) {
+  return aggregateByPeriod(data, getWeekStart);
+}
+function aggregateToMonthly(data) {
+  return aggregateByPeriod(data, getMonthStart);
+}
+function getPeriodKeyFn(period) {
+  switch (period) {
+    case "4H":
+      return (ts) => getHourBucket(ts, 4);
+    case "8H":
+      return (ts) => getHourBucket(ts, 8);
+    case "12H":
+      return (ts) => getHourBucket(ts, 12);
+    case "1D":
+      return getDayStart;
+    case "1W":
+      return getWeekStart;
+    case "1M":
+      return getMonthStart;
+    case "3M":
+      return (ts) => getQuarterStart(ts, 3);
+    case "6M":
+      return (ts) => getQuarterStart(ts, 6);
+    case "1Y":
+      return getYearStart;
+  }
+}
+function aggregateByPeriod(data, getPeriodKey) {
+  if (data.length === 0) return [];
+  const periods = /* @__PURE__ */ new Map();
+  for (const bar of data) {
+    const timestamp = timeToTimestamp(bar.time);
+    const periodKey = getPeriodKey(timestamp);
+    const existing = periods.get(periodKey);
+    if (!existing) {
+      periods.set(periodKey, {
+        time: bar.time,
+        open: bar.open,
+        high: bar.high,
+        low: bar.low,
+        close: bar.close,
+        volume: bar.volume ?? 0
+      });
+    } else {
+      existing.high = Math.max(existing.high, bar.high);
+      existing.low = Math.min(existing.low, bar.low);
+      existing.close = bar.close;
+      existing.volume = (existing.volume ?? 0) + (bar.volume ?? 0);
+    }
+  }
+  return Array.from(periods.values());
+}
+function timeToTimestamp(time) {
+  if (typeof time === "number") return time;
+  if (typeof time === "string") return Math.floor(new Date(time).getTime() / 1e3);
+  return Math.floor(
+    (/* @__PURE__ */ new Date(`${time.year}-${String(time.month).padStart(2, "0")}-${String(time.day).padStart(2, "0")}`)).getTime() / 1e3
+  );
+}
+function getHourBucket(timestamp, hours) {
+  const bucketSeconds = hours * 3600;
+  return Math.floor(timestamp / bucketSeconds) * bucketSeconds;
+}
+function getDayStart(timestamp) {
+  const date = new Date(timestamp * 1e3);
+  date.setUTCHours(0, 0, 0, 0);
+  return Math.floor(date.getTime() / 1e3);
+}
+function getWeekStart(timestamp) {
+  const date = new Date(timestamp * 1e3);
+  const day = date.getUTCDay();
+  const diff = day === 0 ? 6 : day - 1;
+  date.setUTCDate(date.getUTCDate() - diff);
+  date.setUTCHours(0, 0, 0, 0);
+  return Math.floor(date.getTime() / 1e3);
+}
+function getMonthStart(timestamp) {
+  const date = new Date(timestamp * 1e3);
+  date.setUTCDate(1);
+  date.setUTCHours(0, 0, 0, 0);
+  return Math.floor(date.getTime() / 1e3);
+}
+function getQuarterStart(timestamp, months) {
+  const date = new Date(timestamp * 1e3);
+  const month = date.getUTCMonth();
+  const quarterMonth = Math.floor(month / months) * months;
+  date.setUTCMonth(quarterMonth, 1);
+  date.setUTCHours(0, 0, 0, 0);
+  return Math.floor(date.getTime() / 1e3);
+}
+function getYearStart(timestamp) {
+  const date = new Date(timestamp * 1e3);
+  date.setUTCMonth(0, 1);
+  date.setUTCHours(0, 0, 0, 0);
+  return Math.floor(date.getTime() / 1e3);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  MTFPrimitive,
+  aggregateOHLC,
+  aggregateToMonthly,
+  aggregateToWeekly
+});

package/dist/index.mjs

@@ -0,0 +1,328 @@
+// src/mtf-primitive.ts
+import { CandlestickSeries } from "lightweight-charts";
+var DEFAULT_OPTIONS = {
+  gap: 5,
+  columnGap: 2,
+  showSeparators: true,
+  separatorColor: "rgba(255,255,255,0.08)",
+  showLabels: true,
+  labelFont: "11px sans-serif",
+  labelColor: "rgba(255,255,255,0.5)"
+};
+var DEFAULT_COLUMN = {
+  candleCount: 6,
+  upColor: "#26a69a",
+  downColor: "#ef5350",
+  wickUpColor: "#26a69a",
+  wickDownColor: "#ef5350",
+  borderVisible: false,
+  borderUpColor: "#26a69a",
+  borderDownColor: "#ef5350"
+};
+var MTFPrimitive = class {
+  constructor(options) {
+    this._chart = null;
+    this._mainSeries = null;
+    this._htfSeries = [];
+    this._separator = null;
+    this._barDuration = 86400;
+    this._options = this._resolveOptions(options);
+  }
+  attach(chart, mainSeries, mainData) {
+    this._chart = chart;
+    this._mainSeries = mainSeries;
+    this._barDuration = this._detectBarDuration(mainData);
+    this._createHTFSeries();
+    this._render(mainData);
+  }
+  detach() {
+    this._removeHTFSeries();
+    if (this._separator && this._mainSeries) {
+      this._mainSeries.detachPrimitive(this._separator);
+      this._separator = null;
+    }
+    this._chart = null;
+    this._mainSeries = null;
+  }
+  update(mainData, options) {
+    if (options) {
+      this._options = this._resolveOptions({ ...this._options, ...options });
+      this._removeHTFSeries();
+      this._createHTFSeries();
+    }
+    this._barDuration = this._detectBarDuration(mainData);
+    this._render(mainData);
+  }
+  updateColumnData(columnIndex, data) {
+    if (columnIndex < this._options.columns.length) {
+      this._options.columns[columnIndex].data = data;
+    }
+  }
+  _createHTFSeries() {
+    if (!this._chart) return;
+    for (const col of this._options.columns) {
+      const seriesOptions = {
+        upColor: col.upColor,
+        downColor: col.downColor,
+        wickUpColor: col.wickUpColor,
+        wickDownColor: col.wickDownColor,
+        borderVisible: col.borderVisible,
+        borderUpColor: col.borderUpColor,
+        borderDownColor: col.borderDownColor
+      };
+      const series = this._chart.addSeries(CandlestickSeries, seriesOptions);
+      this._htfSeries.push(series);
+    }
+  }
+  _removeHTFSeries() {
+    if (!this._chart) return;
+    for (const series of this._htfSeries) {
+      this._chart.removeSeries(series);
+    }
+    this._htfSeries = [];
+  }
+  _render(mainData) {
+    if (!this._chart || !this._mainSeries || mainData.length === 0) return;
+    const lastMainTime = this._getTimeAsNumber(mainData[mainData.length - 1].time);
+    const { columns, gap, columnGap } = this._options;
+    let currentOffset = gap;
+    const columnPositions = [];
+    for (let i = 0; i < columns.length; i++) {
+      const col = columns[i];
+      const visibleData = col.data.slice(-col.candleCount);
+      const count = visibleData.length;
+      columnPositions.push({ startOffset: currentOffset, count });
+      const htfData = visibleData.map((bar, idx) => ({
+        time: lastMainTime + (currentOffset + idx + 1) * this._barDuration,
+        open: bar.open,
+        high: bar.high,
+        low: bar.low,
+        close: bar.close
+      }));
+      this._htfSeries[i].setData(htfData);
+      currentOffset += count + columnGap;
+    }
+    const totalBars = currentOffset + 2;
+    const whitespace = [];
+    for (let i = 1; i <= totalBars; i++) {
+      whitespace.push({ time: lastMainTime + i * this._barDuration });
+    }
+    this._mainSeries.setData([...mainData, ...whitespace]);
+    if (this._separator && this._mainSeries) {
+      this._mainSeries.detachPrimitive(this._separator);
+    }
+    if (this._options.showSeparators || this._options.showLabels) {
+      this._separator = new MTFSeparatorPrimitive(
+        this._options,
+        lastMainTime,
+        this._barDuration,
+        columnPositions
+      );
+      this._mainSeries.attachPrimitive(this._separator);
+    }
+    this._chart.timeScale().fitContent();
+  }
+  _detectBarDuration(data) {
+    if (data.length < 2) return 86400;
+    const t1 = this._getTimeAsNumber(data[data.length - 1].time);
+    const t2 = this._getTimeAsNumber(data[data.length - 2].time);
+    return t1 - t2;
+  }
+  _getTimeAsNumber(time) {
+    if (typeof time === "number") return time;
+    if (typeof time === "string") return Math.floor(new Date(time).getTime() / 1e3);
+    return Math.floor(
+      (/* @__PURE__ */ new Date(`${time.year}-${String(time.month).padStart(2, "0")}-${String(time.day).padStart(2, "0")}`)).getTime() / 1e3
+    );
+  }
+  _resolveOptions(options) {
+    const columns = options.columns.map((col) => ({
+      timeframe: col.timeframe,
+      data: col.data,
+      candleCount: col.candleCount ?? DEFAULT_COLUMN.candleCount,
+      upColor: col.upColor ?? DEFAULT_COLUMN.upColor,
+      downColor: col.downColor ?? DEFAULT_COLUMN.downColor,
+      wickUpColor: col.wickUpColor ?? col.upColor ?? DEFAULT_COLUMN.wickUpColor,
+      wickDownColor: col.wickDownColor ?? col.downColor ?? DEFAULT_COLUMN.wickDownColor,
+      borderVisible: col.borderVisible ?? DEFAULT_COLUMN.borderVisible,
+      borderUpColor: col.borderUpColor ?? col.upColor ?? DEFAULT_COLUMN.borderUpColor,
+      borderDownColor: col.borderDownColor ?? col.downColor ?? DEFAULT_COLUMN.borderDownColor
+    }));
+    return {
+      gap: options.gap ?? DEFAULT_OPTIONS.gap,
+      columnGap: options.columnGap ?? DEFAULT_OPTIONS.columnGap,
+      showSeparators: options.showSeparators ?? DEFAULT_OPTIONS.showSeparators,
+      separatorColor: options.separatorColor ?? DEFAULT_OPTIONS.separatorColor,
+      showLabels: options.showLabels ?? DEFAULT_OPTIONS.showLabels,
+      labelFont: options.labelFont ?? DEFAULT_OPTIONS.labelFont,
+      labelColor: options.labelColor ?? DEFAULT_OPTIONS.labelColor,
+      columns
+    };
+  }
+};
+var MTFSeparatorPrimitive = class {
+  constructor(options, lastMainTime, barDuration, columnPositions) {
+    this._options = options;
+    this._lastMainTime = lastMainTime;
+    this._barDuration = barDuration;
+    this._columnPositions = columnPositions;
+  }
+  attached() {
+  }
+  detached() {
+  }
+  updateAllViews() {
+  }
+  paneViews() {
+    return [{ renderer: () => this, zOrder: () => "bottom" }];
+  }
+  draw(target) {
+    target.useBitmapCoordinateSpace((scope) => {
+      const ctx = scope.context;
+      const hRatio = scope.horizontalPixelRatio;
+      const vRatio = scope.verticalPixelRatio;
+      const chartHeight = scope.bitmapSize.height;
+      const timeScale = this._chart?.timeScale?.();
+      if (!timeScale) return;
+      if (this._options.showSeparators) {
+        ctx.strokeStyle = this._options.separatorColor;
+        ctx.lineWidth = 1 * hRatio;
+        ctx.setLineDash([4 * hRatio, 3 * hRatio]);
+        for (const pos of this._columnPositions) {
+          const sepTime = this._lastMainTime + pos.startOffset * this._barDuration;
+          const x = timeScale.timeToCoordinate(sepTime);
+          if (x === null) continue;
+          const px = x * hRatio;
+          ctx.beginPath();
+          ctx.moveTo(px, 0);
+          ctx.lineTo(px, chartHeight);
+          ctx.stroke();
+        }
+        ctx.setLineDash([]);
+      }
+      if (this._options.showLabels) {
+        ctx.font = this._options.labelFont;
+        ctx.fillStyle = this._options.labelColor;
+        ctx.textAlign = "center";
+        ctx.textBaseline = "top";
+        for (let i = 0; i < this._columnPositions.length; i++) {
+          const pos = this._columnPositions[i];
+          const midOffset = pos.startOffset + Math.floor(pos.count / 2) + 1;
+          const labelTime = this._lastMainTime + midOffset * this._barDuration;
+          const x = timeScale.timeToCoordinate(labelTime);
+          if (x === null) continue;
+          ctx.fillText(this._options.columns[i].timeframe, x * hRatio, 8 * vRatio);
+        }
+      }
+    });
+  }
+};
+
+// src/data-aggregator.ts
+function aggregateOHLC(data, period) {
+  const getPeriodKey = getPeriodKeyFn(period);
+  return aggregateByPeriod(data, getPeriodKey);
+}
+function aggregateToWeekly(data) {
+  return aggregateByPeriod(data, getWeekStart);
+}
+function aggregateToMonthly(data) {
+  return aggregateByPeriod(data, getMonthStart);
+}
+function getPeriodKeyFn(period) {
+  switch (period) {
+    case "4H":
+      return (ts) => getHourBucket(ts, 4);
+    case "8H":
+      return (ts) => getHourBucket(ts, 8);
+    case "12H":
+      return (ts) => getHourBucket(ts, 12);
+    case "1D":
+      return getDayStart;
+    case "1W":
+      return getWeekStart;
+    case "1M":
+      return getMonthStart;
+    case "3M":
+      return (ts) => getQuarterStart(ts, 3);
+    case "6M":
+      return (ts) => getQuarterStart(ts, 6);
+    case "1Y":
+      return getYearStart;
+  }
+}
+function aggregateByPeriod(data, getPeriodKey) {
+  if (data.length === 0) return [];
+  const periods = /* @__PURE__ */ new Map();
+  for (const bar of data) {
+    const timestamp = timeToTimestamp(bar.time);
+    const periodKey = getPeriodKey(timestamp);
+    const existing = periods.get(periodKey);
+    if (!existing) {
+      periods.set(periodKey, {
+        time: bar.time,
+        open: bar.open,
+        high: bar.high,
+        low: bar.low,
+        close: bar.close,
+        volume: bar.volume ?? 0
+      });
+    } else {
+      existing.high = Math.max(existing.high, bar.high);
+      existing.low = Math.min(existing.low, bar.low);
+      existing.close = bar.close;
+      existing.volume = (existing.volume ?? 0) + (bar.volume ?? 0);
+    }
+  }
+  return Array.from(periods.values());
+}
+function timeToTimestamp(time) {
+  if (typeof time === "number") return time;
+  if (typeof time === "string") return Math.floor(new Date(time).getTime() / 1e3);
+  return Math.floor(
+    (/* @__PURE__ */ new Date(`${time.year}-${String(time.month).padStart(2, "0")}-${String(time.day).padStart(2, "0")}`)).getTime() / 1e3
+  );
+}
+function getHourBucket(timestamp, hours) {
+  const bucketSeconds = hours * 3600;
+  return Math.floor(timestamp / bucketSeconds) * bucketSeconds;
+}
+function getDayStart(timestamp) {
+  const date = new Date(timestamp * 1e3);
+  date.setUTCHours(0, 0, 0, 0);
+  return Math.floor(date.getTime() / 1e3);
+}
+function getWeekStart(timestamp) {
+  const date = new Date(timestamp * 1e3);
+  const day = date.getUTCDay();
+  const diff = day === 0 ? 6 : day - 1;
+  date.setUTCDate(date.getUTCDate() - diff);
+  date.setUTCHours(0, 0, 0, 0);
+  return Math.floor(date.getTime() / 1e3);
+}
+function getMonthStart(timestamp) {
+  const date = new Date(timestamp * 1e3);
+  date.setUTCDate(1);
+  date.setUTCHours(0, 0, 0, 0);
+  return Math.floor(date.getTime() / 1e3);
+}
+function getQuarterStart(timestamp, months) {
+  const date = new Date(timestamp * 1e3);
+  const month = date.getUTCMonth();
+  const quarterMonth = Math.floor(month / months) * months;
+  date.setUTCMonth(quarterMonth, 1);
+  date.setUTCHours(0, 0, 0, 0);
+  return Math.floor(date.getTime() / 1e3);
+}
+function getYearStart(timestamp) {
+  const date = new Date(timestamp * 1e3);
+  date.setUTCMonth(0, 1);
+  date.setUTCHours(0, 0, 0, 0);
+  return Math.floor(date.getTime() / 1e3);
+}
+export {
+  MTFPrimitive,
+  aggregateOHLC,
+  aggregateToMonthly,
+  aggregateToWeekly
+};

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "lightweight-charts-mtf",
+  "version": "0.1.0",
+  "description": "Multi-timeframe candle display plugin for TradingView Lightweight Charts",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/nsulistiyawan/lightweight-charts-mtf.git"
+  },
+  "homepage": "https://github.com/nsulistiyawan/lightweight-charts-mtf#readme",
+  "bugs": {
+    "url": "https://github.com/nsulistiyawan/lightweight-charts-mtf/issues"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
+    "dev": "tsup src/index.ts --format esm --dts --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "tradingview",
+    "lightweight-charts",
+    "multi-timeframe",
+    "mtf",
+    "plugin",
+    "candlestick",
+    "trading"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "lightweight-charts": ">=4.0.0"
+  },
+  "devDependencies": {
+    "lightweight-charts": "^5.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.4.0",
+    "vitest": "^3.2.4"
+  }
+}