openalgo-charts 2.3.2 → 2.4.5

package/dist/indicators/index.d.ts

@@ -1,4 +1,4 @@
-import { IndicatorDescriptor, ChartDataContext, IndicatorSettings, Bar, IndicatorInput, IndicatorPlot, IndicatorLevel } from 'openalgo-charts';
+import { IndicatorDescriptor, ChartDataContext, IndicatorSettings, Bar, IndicatorBarsRequest, IndicatorInput, IndicatorPlot, IndicatorValues, IndicatorStore, IndicatorCalcContext, IndicatorLevel } from 'openalgo-charts';
 
 declare const SMA: IndicatorDescriptor;
 declare const WMA: IndicatorDescriptor;
@@ -57,6 +57,18 @@ declare const VOLUME: IndicatorDescriptor;
 declare const OBV: IndicatorDescriptor;
 declare const ADL: IndicatorDescriptor;
 
+/** Per-bar position levels from the instrument itself, with no external alignment. */
+
+/** A missing observation breaks the line; it is not an empty position. */
+declare const OPEN_INTEREST: IndicatorDescriptor;
+/** Adjacent observations only: a gap cannot support a bar-on-bar change. */
+declare const OPEN_INTEREST_CHANGE: IndicatorDescriptor;
+/**
+ * Price and position changes describe a regime, not a second price series.
+ * Publish candle colors only, so the study cannot distort the instrument axis.
+ */
+declare const OPEN_INTEREST_BUILDUP: IndicatorDescriptor;
+
 /**
  * The source is hard-coded to `close` in the reference (`source = close`,
  * not an `input`), so there is no source setting to expose.
@@ -1074,7 +1086,7 @@ declare function valueWhen(cond: readonly boolean[], source: readonly number[],
 
 /**
  * Tier-2 contract — indicators whose data is **not** derived from the chart's
- * OHLCV: open interest, cumulative volume delta, PCR, an external analytics
+ * OHLCV: cumulative volume delta, PCR, an external analytics
  * feed. Where a Tier-1 descriptor is a pure `calc(bars, settings)`, a Tier-2
  * descriptor owns a fetch / subscribe / merge lifecycle and its own series.
  *
@@ -1106,6 +1118,12 @@ interface Tier2Context {
     /** UTC seconds of the first and last source bar (0 when there are none). */
     from: number;
     to: number;
+    /**
+     * The host's bar provider, when the runtime supplies one, so a `fetch` that
+     * needs another instrument's candles asks the host rather than carrying its
+     * own transport and credentials. Rejects when the host registered none.
+     */
+    requestBars?(request: IndicatorBarsRequest): Promise<readonly Bar[]>;
 }
 interface Tier2Descriptor {
     id: string;
@@ -1114,6 +1132,22 @@ interface Tier2Descriptor {
     placement: 'onchart' | 'pane';
     inputs: readonly IndicatorInput[];
     plots: readonly IndicatorPlot[];
+    /**
+     * External columns to align besides the plots, by key. A point may carry
+     * more than what is drawn: a benchmark close that `calc` divides by, an
+     * open-interest figure a ratio is built from. Anything not named here or in
+     * `plots` is dropped at alignment.
+     */
+    series?: readonly string[];
+    /**
+     * Combine the aligned external columns with the chart's own bars. Without
+     * it the aligned columns are the result, one per plot, exactly as before.
+     * With it, `external` holds every plot and `series` key aligned onto the
+     * bars (last-known-value, `null` before the first point), and the return is
+     * what the plots draw: a relative strength, a beta, a spread. Pure in its
+     * arguments, like any `calc`.
+     */
+    calc?(bars: readonly Bar[], external: IndicatorValues, settings: Readonly<IndicatorSettings>, store: IndicatorStore, ctx?: IndicatorCalcContext): IndicatorValues;
     /** A host/provider can explicitly decline data it cannot supply. */
     supports?(ctx: Tier2Context): boolean;
     /** Load the series for the current window. */
@@ -1138,18 +1172,79 @@ interface Tier2Descriptor {
  * Wrap a Tier-2 descriptor as a normal `IndicatorDescriptor`.
  *
  * ```ts
- * export const OPEN_INTEREST = createTier2Indicator({
- *   id: 'open-interest', name: 'Open Interest', placement: 'pane',
+ * export const POSITION_INDEX = createTier2Indicator({
+ *   id: 'external-position-index', name: 'Position Index', placement: 'pane',
  *   inputs: [{ key: 'symbol', type: 'text', label: 'Symbol', default: '' }],
- *   plots: [{ key: 'oi', type: 'line', title: 'OI' }],
+ *   plots: [{ key: 'position', type: 'line', title: 'Position' }],
  *   refetchOn: ['symbol'],
- *   fetch: async ({ settings, from, to }) => loadOi(settings.symbol, from, to),
+ *   fetch: async ({ settings, from, to }) => loadPositionIndex(settings.symbol, from, to),
  * });
- * registerIndicator(OPEN_INTEREST);
+ * registerIndicator(POSITION_INDEX);
  * ```
  */
 declare function createTier2Indicator(d: Tier2Descriptor): IndicatorDescriptor;
 
+/**
+ * A higher-timeframe view of the chart's own bars, one value per source bar.
+ *
+ * A study written for a script language asks for the daily high on a 5-minute
+ * chart and gets a column the same length as the chart. The engine has no
+ * such call, and every port that needed one folded the bars by hand, each a
+ * little differently: some anchored an hourly bucket to midnight and some to
+ * the session open, some read the bucket as it stood and some read its final
+ * values. This is the one fold, with the three readings named:
+ *
+ * - `offset: 0` (the default) reads the bucket **as it stood at that bar**:
+ *   its open so far, high and low so far, the bar's own close, volume so far.
+ *   It is what the live bar sees and it never uses a later bar.
+ * - `offset: k` reads the bucket that completed `k` buckets before, held
+ *   constant across the current one. The classic non-repainting reference,
+ *   `close[1]` on the higher timeframe.
+ * - `lookahead: true` reads the current bucket's **final** values on every one
+ *   of its bars. It uses bars that had not happened yet, which is what the
+ *   source it is porting did; it is here so that can be reproduced, not
+ *   recommended.
+ *
+ * Buckets follow the chart's calendar: a day is a day in `timezone`, a week
+ * starts on Monday there, and a sub-day interval is anchored to the epoch, or
+ * to the session open when `session` is given, which is how an exchange cuts
+ * its hourly bars.
+ */
+
+interface SecurityOptions {
+    /** The calendar the buckets are cut in. Defaults to the shipped default zone. */
+    timezone?: string;
+    /** Read each bucket's final values on all of its bars. Default false. */
+    lookahead?: boolean;
+    /** Read the bucket completed this many buckets ago. Default 0, the current one. */
+    offset?: number;
+    /**
+     * A session window, `'0915-1530'`, that anchors sub-day buckets to the
+     * session open instead of the epoch. Without it a 30-minute bucket on a
+     * 09:15 open runs 09:00 to 09:30; with it, 09:15 to 09:45.
+     */
+    session?: string;
+}
+interface SecuritySeries {
+    open: (number | null)[];
+    high: (number | null)[];
+    low: (number | null)[];
+    close: (number | null)[];
+    /** Null on a bucket none of whose bars carried volume. */
+    volume: (number | null)[];
+    /**
+     * Open interest as at the last source bar of the bucket, null where no bar in
+     * it carried any. A level rather than a flow, so it is the latest reading and
+     * never the sum the way `volume` is.
+     */
+    oi: (number | null)[];
+    /** Time of the first source bar in the bucket being read, UTC seconds. */
+    bucketStart: (number | null)[];
+    /** True on the first source bar of each bucket. */
+    isNew: boolean[];
+}
+declare function securitySeries(bars: readonly Bar[], interval: string, options?: SecurityOptions): SecuritySeries;
+
 declare const INDICATORS_TIER: "indicators";
 /** Every built-in descriptor, in picker order. */
 declare const BUILTIN_INDICATORS: readonly IndicatorDescriptor[];
@@ -1160,4 +1255,4 @@ declare const BUILTIN_INDICATORS: readonly IndicatorDescriptor[];
  */
 declare function registerBuiltinIndicators(): void;
 
-export { ADAPTIVE_INDICATORS, ADL, ADX, ALLIGATOR, ALMA, ALPHATREND, AROON, AROON_OSCILLATOR, ATR, AVERAGE_DAILY_RANGE, AVERAGE_INDICATORS, AWESOME_OSCILLATOR, BALANCE_OF_POWER, BB_TREND, BOLLINGER, BOLLINGER_BANDWIDTH, BOLLINGER_PERCENT_B, BUILTIN_INDICATORS, CCI, CHAIKIN_MONEY_FLOW, CHAIKIN_OSCILLATOR, CHAIKIN_VOLATILITY, CHANDELIER_EXIT, CHANDE_KROLL_STOP, CHANDE_MOMENTUM, CHOPPINESS_INDEX, CHOP_ZONE, CONNORS_RSI, CONSOLIDATION_BREAKOUT, COPPOCK_CURVE, CPR, DEMA, DONCHIAN, DPO, EASE_OF_MOVEMENT, ELDER_FORCE_INDEX, EMA, ENVELOPE, FISHER_TRANSFORM, FLOW_INDICATORS, HALFTREND, HISTORICAL_VOLATILITY, HMA, HULL_SUITE, ICHIMOKU, INDEX_INDICATORS, INDICATORS_TIER, KAMA, KELTNER_CHANNEL, KLINGER_OSCILLATOR, KNOW_SURE_THING, LINREG_SLOPE, LSMA, MACD, MASS_INDEX, MA_CHANNEL, MA_CROSS, MA_RIBBON, MCGINLEY_DYNAMIC, MEDIAN, MFI, MOMENTUM, NET_VOLUME, NVI, OBV, OSCILLATOR_INDICATORS, OVERLAY_INDICATORS, PARABOLIC_SAR, PPO, PVI, PVO, PVT, RANGE_ANALYSIS, RANGE_INDICATORS, RELATIVE_VIGOR_INDEX, RELATIVE_VOLATILITY_INDEX, ROC, RSI, RSI_DIVERGENCE, SEASONALITY, SEASONALITY_INDICATORS, SIGNAL_INDICATORS, SMA, SMI, SMI_ERGODIC_INDICATOR, SMI_ERGODIC_OSCILLATOR, SMMA, SPECIAL_K, STANDARD_DEVIATION, STANDARD_ERROR, STANDARD_ERROR_BANDS, STOCHASTIC, STOCHASTIC_RSI, STRENGTH_INDICATORS, STUDY_INDICATORS, SUPERTREND, T3, TEMA, TREND_STRENGTH_INDEX, TRIX, TSI, TWAP, type Tier2Context, type Tier2Descriptor, type Tier2Point, ULCER_INDEX, ULTIMATE_OSCILLATOR, VOLATILITY_INDICATORS, VOLATILITY_STOP, VOLUME, VORTEX, VWAP, VWMA, WAVETREND, WAVETREND_INDICATORS, WILLIAMS_FRACTALS, WILLIAMS_PERCENT_R, WILLIAMS_VIX_FIX, WMA, WOODIES_CCI, alma, barsSince, cci, change, connorsStreak, correlation, createTier2Indicator, cumulative, dev, highest, highestBars, linreg, lowest, lowestBars, nulls, percentRank, percentileNearestRank, pivotHigh, pivotLow, registerBuiltinIndicators, rma, roc, rollingSum, sma, smaSeededEma, stdev, stoch, swma, valueWhen, vwma, wma };
+export { ADAPTIVE_INDICATORS, ADL, ADX, ALLIGATOR, ALMA, ALPHATREND, AROON, AROON_OSCILLATOR, ATR, AVERAGE_DAILY_RANGE, AVERAGE_INDICATORS, AWESOME_OSCILLATOR, BALANCE_OF_POWER, BB_TREND, BOLLINGER, BOLLINGER_BANDWIDTH, BOLLINGER_PERCENT_B, BUILTIN_INDICATORS, CCI, CHAIKIN_MONEY_FLOW, CHAIKIN_OSCILLATOR, CHAIKIN_VOLATILITY, CHANDELIER_EXIT, CHANDE_KROLL_STOP, CHANDE_MOMENTUM, CHOPPINESS_INDEX, CHOP_ZONE, CONNORS_RSI, CONSOLIDATION_BREAKOUT, COPPOCK_CURVE, CPR, DEMA, DONCHIAN, DPO, EASE_OF_MOVEMENT, ELDER_FORCE_INDEX, EMA, ENVELOPE, FISHER_TRANSFORM, FLOW_INDICATORS, HALFTREND, HISTORICAL_VOLATILITY, HMA, HULL_SUITE, ICHIMOKU, INDEX_INDICATORS, INDICATORS_TIER, KAMA, KELTNER_CHANNEL, KLINGER_OSCILLATOR, KNOW_SURE_THING, LINREG_SLOPE, LSMA, MACD, MASS_INDEX, MA_CHANNEL, MA_CROSS, MA_RIBBON, MCGINLEY_DYNAMIC, MEDIAN, MFI, MOMENTUM, NET_VOLUME, NVI, OBV, OPEN_INTEREST, OPEN_INTEREST_BUILDUP, OPEN_INTEREST_CHANGE, OSCILLATOR_INDICATORS, OVERLAY_INDICATORS, PARABOLIC_SAR, PPO, PVI, PVO, PVT, RANGE_ANALYSIS, RANGE_INDICATORS, RELATIVE_VIGOR_INDEX, RELATIVE_VOLATILITY_INDEX, ROC, RSI, RSI_DIVERGENCE, SEASONALITY, SEASONALITY_INDICATORS, SIGNAL_INDICATORS, SMA, SMI, SMI_ERGODIC_INDICATOR, SMI_ERGODIC_OSCILLATOR, SMMA, SPECIAL_K, STANDARD_DEVIATION, STANDARD_ERROR, STANDARD_ERROR_BANDS, STOCHASTIC, STOCHASTIC_RSI, STRENGTH_INDICATORS, STUDY_INDICATORS, SUPERTREND, type SecurityOptions, type SecuritySeries, T3, TEMA, TREND_STRENGTH_INDEX, TRIX, TSI, TWAP, type Tier2Context, type Tier2Descriptor, type Tier2Point, ULCER_INDEX, ULTIMATE_OSCILLATOR, VOLATILITY_INDICATORS, VOLATILITY_STOP, VOLUME, VORTEX, VWAP, VWMA, WAVETREND, WAVETREND_INDICATORS, WILLIAMS_FRACTALS, WILLIAMS_PERCENT_R, WILLIAMS_VIX_FIX, WMA, WOODIES_CCI, alma, barsSince, cci, change, connorsStreak, correlation, createTier2Indicator, cumulative, dev, highest, highestBars, linreg, lowest, lowestBars, nulls, percentRank, percentileNearestRank, pivotHigh, pivotLow, registerBuiltinIndicators, rma, roc, rollingSum, securitySeries, sma, smaSeededEma, stdev, stoch, swma, valueWhen, vwma, wma };