openalgo-charts 2.5.2 → 2.5.4

package/dist/indicators/index.d.ts

@@ -1,4 +1,5 @@
-import { IndicatorDescriptor, ChartDataContext, IndicatorSettings, Bar, IndicatorBarsRequest, IndicatorInput, IndicatorPlot, IndicatorValues, IndicatorStore, IndicatorCalcContext, IndicatorLevel } from 'openalgo-charts';
+import { IndicatorDescriptor, ChartDataContext, IndicatorRequestState, IndicatorSettings, Bar, IndicatorBarsRequest, IndicatorInput, IndicatorPlot, IndicatorValues, IndicatorStore, IndicatorCalcContext, IndicatorLevel, RequestedBarsSnapshot, IndicatorSnapshotRequest } from 'openalgo-charts';
+export { RequestedBarsSnapshot } from 'openalgo-charts';
 
 declare const SMA: IndicatorDescriptor;
 declare const WMA: IndicatorDescriptor;
@@ -973,6 +974,143 @@ declare const WAVETREND_INDICATORS: readonly IndicatorDescriptor[];
 declare const SEASONALITY: IndicatorDescriptor;
 declare const SEASONALITY_INDICATORS: readonly IndicatorDescriptor[];
 
+/**
+ * Array-based statistics with explicit observation windows. Results keep the
+ * input length and never mutate inputs. NaN and infinities are missing values.
+ * Numeric warmup and undefined statistics are NaN; boolean warmup is false.
+ */
+/** Missing-value policy shared by numerical statistics and predicates. */
+interface NumericalWindowOptions {
+    /**
+     * `propagate` (default) uses chronological windows and rejects missing terms.
+     * `skip` uses finite observations, preserving their original order. Rolling
+     * numeric results hold across missing bars once the window is full.
+     * Predicates require a finite current observation and otherwise return false.
+     */
+    missing?: 'propagate' | 'skip';
+}
+/** Estimator choice for {@link rollingVariance}. */
+interface RollingVarianceOptions extends NumericalWindowOptions {
+    /** Divide by period-1 for a sample, or period for the default population. */
+    sample?: boolean;
+}
+/**
+ * Rolling median, averaging the middle pair for even periods. Uses a full
+ * period including the current bar, with NaN until ready. Missing values
+ * propagate by default; `skip` collects period finite observations and holds
+ * across gaps. Equal values retain their multiplicity. Invalid periods throw
+ * RangeError; an unknown missing policy throws TypeError.
+ */
+declare function rollingMedian(values: readonly number[], period: number, options?: NumericalWindowOptions): number[];
+/**
+ * Most frequent value in a full period ending at the current bar; equal
+ * frequencies choose the smallest value. Warmup is NaN. Missing values
+ * propagate by default; `skip` collects period finite observations and holds
+ * across gaps. Invalid periods throw RangeError; unknown policies TypeError.
+ */
+declare function rollingMode(values: readonly number[], period: number, options?: NumericalWindowOptions): number[];
+/**
+ * Variance of a full period ending at the current bar. Population is the
+ * default; `sample` divides by period-1 and gives NaN for period one. Ties are
+ * repeated observations. Warmup is NaN. Missing values propagate by default;
+ * `skip` collects period finite observations and holds across gaps. Invalid
+ * periods throw RangeError; invalid policy or sample options throw TypeError.
+ * A variance beyond the finite number range is Infinity.
+ */
+declare function rollingVariance(values: readonly number[], period: number, options?: RollingVarianceOptions): number[];
+/**
+ * Maximum minus minimum in a full period ending at the current bar. Repeated
+ * extremes do not change the result. Warmup is NaN. Missing values propagate
+ * by default; `skip` collects period finite observations and holds across gaps.
+ * Invalid periods throw RangeError; unknown missing policies throw TypeError.
+ */
+declare function rollingRange(values: readonly number[], period: number, options?: NumericalWindowOptions): number[];
+/**
+ * Sorted-window percentile at zero-based rank (period-1)*percentage/100,
+ * interpolating its adjacent values. Ties retain multiplicity; endpoints are
+ * the minimum and maximum. A full period includes the current bar; warmup is
+ * NaN. Missing values propagate by default; `skip` collects finite observations
+ * and holds across gaps. Invalid periods or percentages outside 0..100 throw
+ * RangeError; unknown missing policies throw TypeError.
+ */
+declare function percentileLinear(values: readonly number[], period: number, percentage: number, options?: NumericalWindowOptions): number[];
+/**
+ * Spearman correlation of value ranks with chronological order, times 100.
+ * Tied values receive their average rank. A constant or one-value window is
+ * NaN, as is warmup before a full period including the current bar. Missing
+ * values propagate by default; `skip` ranks the last period finite observations
+ * and holds across gaps. Invalid periods throw RangeError; unknown policies
+ * throw TypeError.
+ */
+declare function rankCorrelation(values: readonly number[], period: number, options?: NumericalWindowOptions): number[];
+/**
+ * Negative weighted sum divided by the ordinary sum over a full period,
+ * assigning weight one to the newest value and period to the oldest. Equal
+ * values remain separate observations. A zero compensated ordinary sum and
+ * warmup are NaN; a nonzero sum is never discarded using an epsilon cutoff.
+ * Ratios beyond the finite number range yield signed Infinity.
+ * Missing values propagate by default; `skip` weights the last period finite
+ * observations and holds across gaps. Invalid periods throw RangeError;
+ * unknown missing policies throw TypeError.
+ */
+declare function centerOfGravity(values: readonly number[], period: number, options?: NumericalWindowOptions): number[];
+/**
+ * Minimum from the first bar through the current bar; equal minima retain the
+ * existing value. There is no fixed warmup. Default `propagate` makes the
+ * entire remaining history NaN after any missing term. `skip` holds the last
+ * finite minimum, with NaN before the first finite term. Unknown policies
+ * throw TypeError; empty input returns an empty array.
+ */
+declare function runningMin(values: readonly number[], options?: NumericalWindowOptions): number[];
+/**
+ * Maximum from the first bar through the current bar; equal maxima retain the
+ * existing value. There is no fixed warmup. Default `propagate` makes the
+ * remaining history NaN after any missing term. `skip` holds the last finite
+ * maximum, with NaN before the first finite term. Unknown policies throw
+ * TypeError; empty input returns an empty array.
+ */
+declare function runningMax(values: readonly number[], options?: NumericalWindowOptions): number[];
+/**
+ * Current a>b after previous a<=b. Current equality is false; prior equality
+ * qualifies. Default `propagate` requires finite pairs on adjacent bars;
+ * `skip` compares with the most recent jointly finite pair. Missing current
+ * pairs and the first pair return false. Unequal array lengths throw
+ * RangeError; unknown missing policies throw TypeError.
+ */
+declare function crossesAbove(a: readonly number[], b: readonly number[], options?: NumericalWindowOptions): boolean[];
+/**
+ * Current a<b after previous a>=b. Current equality is false; prior equality
+ * qualifies. Default `propagate` requires finite adjacent pairs; `skip` uses
+ * the most recent jointly finite pair. Missing current pairs and the first
+ * pair return false. Unequal lengths throw RangeError; unknown policies
+ * throw TypeError.
+ */
+declare function crossesBelow(a: readonly number[], b: readonly number[], options?: NumericalWindowOptions): boolean[];
+/**
+ * Crossing in either direction, with strict current inequality and inclusive
+ * prior inequality. Default `propagate` requires finite adjacent pairs;
+ * `skip` compares with the most recent jointly finite pair. Missing current
+ * pairs and the first pair are false. Unequal lengths throw RangeError;
+ * unknown missing policies throw TypeError.
+ */
+declare function crosses(a: readonly number[], b: readonly number[], options?: NumericalWindowOptions): boolean[];
+/**
+ * Whether the finite current value strictly exceeds every one of period prior
+ * observations, excluding the current bar. Equality fails. Default `propagate`
+ * uses prior chronological bars; `skip` collects prior finite observations.
+ * Missing current values, gaps in required history, and insufficient history
+ * return false. Invalid periods throw RangeError; unknown policies TypeError.
+ */
+declare function rising(values: readonly number[], period: number, options?: NumericalWindowOptions): boolean[];
+/**
+ * Whether the finite current value is strictly below every one of period prior
+ * observations, excluding the current bar. Equality fails. Default `propagate`
+ * uses prior chronological bars; `skip` collects prior finite observations.
+ * Missing current values, gaps in required history, and insufficient history
+ * return false. Invalid periods throw RangeError; unknown policies TypeError.
+ */
+declare function falling(values: readonly number[], period: number, options?: NumericalWindowOptions): boolean[];
+
 /**
  * Pure calculation helpers shared by the Tier-1 indicator descriptors
  * (`openalgo-charts/indicators`). Every function returns an array the same
@@ -982,59 +1120,161 @@ declare const SEASONALITY_INDICATORS: readonly IndicatorDescriptor[];
  *
  * `ema`, `rsi`, `atr`, `trueRange`, and `supertrend` are NOT re-implemented
  * here — they ship in the base bundle and the tier imports them from it.
+ *
+ * For helpers accepting missing-value options, omitted options use each
+ * helper's documented default. Supplied options treat NaN and infinities as
+ * missing. An empty options object selects chronological propagation.
+ *
+ * Varying window lengths must align with the source. Each bar uses its own
+ * positive safe-integer length; NaN lengths produce gaps without discarding
+ * source history. Other invalid numeric lengths throw RangeError, malformed
+ * elements throw TypeError, and unequal array lengths throw RangeError.
+ * Array lengths default to chronological propagation. With `skip`, changed
+ * lengths reevaluate finite history even on missing source bars. These paths
+ * use O(n + sum of evaluated window lengths) time and O(n) working storage.
  */
-/** Simple moving average. First value lands at index `period - 1`. */
-declare function sma(values: readonly number[], period: number): number[];
-/** Linearly weighted moving average (most recent bar carries weight `period`). */
-declare function wma(values: readonly number[], period: number): number[];
-/**
- * Wilder's smoothing (RMA): seed with the SMA of the first `period` values,
- * then `(prev * (period - 1) + v) / period`. The basis of RSI, ATR, and ADX.
- */
-declare function rma(values: readonly number[], period: number): number[];
-/** Rolling population standard deviation over `period`. */
-declare function stdev(values: readonly number[], period: number): number[];
-/** Rolling maximum over `period` bars. */
-declare function highest(values: readonly number[], period: number): number[];
-/** Rolling minimum over `period` bars. */
-declare function lowest(values: readonly number[], period: number): number[];
+
+/**
+ * Simple moving average. Valid scalar windows without options sum oldest first
+ * afresh, then divide once. Missing or overflowing sums produce NaN and recover
+ * when they expire. This uses O(n * period) time and O(1) extra working storage.
+ * Unsupported scalar periods retain their historical behavior.
+ * Supplied `skip` collects period finite observations and holds across gaps;
+ * `propagate` (also the default for {}) requires a complete chronological
+ * window. Warmup is NaN. Option-path periods must be positive safe integers;
+ * invalid periods throw RangeError and malformed options throw TypeError.
+ */
+declare function sma(values: readonly number[], period: number, options?: NumericalWindowOptions): number[];
+/** Bar-aligned lengths use each current window; NaN lengths give gaps. Arrays default to propagation. */
+declare function sma(values: readonly number[], period: number | readonly number[], options?: NumericalWindowOptions): number[];
+/**
+ * Linearly weighted average, newest observation carrying weight period.
+ * Valid scalar defaults sum weighted terms oldest first and omit nonfinite
+ * results. Supplied `skip` weights period
+ * finite observations and holds across gaps; `propagate` requires a full
+ * chronological window. Warmup is NaN. The option path validates a positive
+ * safe-integer period and a missing policy, throwing RangeError or TypeError.
+ */
+declare function wma(values: readonly number[], period: number, options?: NumericalWindowOptions): number[];
+/** Bar-aligned lengths weight the newest selected observation most; NaN lengths give gaps. */
+declare function wma(values: readonly number[], period: number | readonly number[], options?: NumericalWindowOptions): number[];
+/**
+ * Wilder's smoothing (RMA): seed from the first complete finite window,
+ * then `(prev * (period - 1) + v) / period`. Valid scalar defaults retry
+ * nonfinite seeds, leave a gap for missing inputs and retain seeded state.
+ * Running overflow is unavailable without restarting. Supplied `skip` seeds from period
+ * finite observations and holds state across gaps. `propagate` clears state on
+ * a missing input and reseeds after period consecutive finite observations.
+ * Warmup is NaN. The option path requires a positive safe-integer period and
+ * valid policy, throwing RangeError or TypeError respectively.
+ */
+declare function rma(values: readonly number[], period: number, options?: NumericalWindowOptions): number[];
+/**
+ * Population standard deviation. Valid scalar defaults accumulate squared
+ * deviations oldest first and omit nonfinite results.
+ * Supplied `skip` uses period finite observations and holds across gaps;
+ * `propagate` requires a full chronological window. Ties retain multiplicity;
+ * warmup is NaN. Invalid option-path periods throw RangeError, malformed
+ * options TypeError. A period must be a positive safe integer.
+ */
+declare function stdev(values: readonly number[], period: number, options?: NumericalWindowOptions): number[];
+/** Bar-aligned lengths select the current population; NaN lengths give gaps. Arrays default to propagation. */
+declare function stdev(values: readonly number[], period: number | readonly number[], options?: NumericalWindowOptions): number[];
+/**
+ * Rolling maximum. Omitted options preserve legacy warmup and gap behavior.
+ * Supplied `skip` searches period finite observations and holds across gaps;
+ * `propagate` requires period chronological finite bars. Insufficient or
+ * all-missing history is NaN. Invalid option-path periods throw RangeError;
+ * malformed policies throw TypeError. Periods must be positive safe integers.
+ */
+declare function highest(values: readonly number[], period: number, options?: NumericalWindowOptions): number[];
+/** Bar-aligned lengths select the current maximum window; NaN lengths give gaps. */
+declare function highest(values: readonly number[], period: number | readonly number[], options?: NumericalWindowOptions): number[];
+/**
+ * Rolling minimum. Omitted options preserve legacy warmup and gap behavior.
+ * Supplied `skip` searches period finite observations and holds across gaps;
+ * `propagate` requires period chronological finite bars. Insufficient or
+ * all-missing history is NaN. Invalid option-path periods throw RangeError;
+ * malformed policies throw TypeError. Periods must be positive safe integers.
+ */
+declare function lowest(values: readonly number[], period: number, options?: NumericalWindowOptions): number[];
+/** Bar-aligned lengths select the current minimum window; NaN lengths give gaps. */
+declare function lowest(values: readonly number[], period: number | readonly number[], options?: NumericalWindowOptions): number[];
 /** NaN → null, so a warmup slot serialises as an explicit gap. */
 declare function nulls(values: readonly number[]): (number | null)[];
 /**
- * the reference `ema`: seeded with the **SMA of the first `period` values**, NaN
- * before that. The base bundle's `ema` seeds from `values[0]` and emits from
- * index 0 instead, so the two disagree for roughly the first `period` bars and
- * converge after. Anything reproducing a reference platform plot needs this one.
- */
-declare function smaSeededEma(values: readonly number[], period: number): number[];
+ * EMA seeded with an SMA, then smoothed with alpha=2/(period+1). Valid scalar
+ * defaults seed from the first complete finite window, retry nonfinite seeds,
+ * and emit gaps for missing inputs while retaining seeded state. A nonfinite
+ * running update stays committed, without restarting. Supplied
+ * `skip` seeds from period finite observations and holds state across gaps.
+ * `propagate` clears state on any missing input and reseeds with period
+ * consecutive finite observations. Warmup is NaN. Invalid option-path
+ * periods throw RangeError; malformed options throw TypeError. Periods must
+ * be positive safe integers.
+ */
+declare function smaSeededEma(values: readonly number[], period: number, options?: NumericalWindowOptions): number[];
 /** the reference `change(src, n)`: `src - src[n]`. NaN for the first `n` bars. */
 declare function change(values: readonly number[], n?: number): number[];
 /** the reference `roc`: `100 * (src - src[n]) / src[n]`. NaN for the first `n` bars. */
 declare function roc(values: readonly number[], n: number): number[];
 /**
- * the reference `dev`: mean **absolute** deviation from the SMA over `period` — not
- * a standard deviation. CCI's 0.015 constant is calibrated against this.
- */
-declare function dev(values: readonly number[], period: number): number[];
-/**
- * the reference `percentrank`: the percentage of the **previous** `period` values
- * that are less than or equal to the current one. The current bar is the
- * subject of the comparison, not part of the window, so the first answer lands
- * at index `period`.
- */
-declare function percentRank(values: readonly number[], period: number): number[];
+ * Mean absolute deviation from the average. Valid scalar defaults accumulate
+ * deviations oldest first and omit nonfinite results.
+ * Supplied `skip` uses period finite observations and holds across
+ * gaps; `propagate` requires a full chronological window. Ties retain their
+ * multiplicity and warmup is NaN. Invalid option-path periods throw RangeError,
+ * malformed options TypeError. Periods must be positive safe integers.
+ */
+declare function dev(values: readonly number[], period: number, options?: NumericalWindowOptions): number[];
+/** Bar-aligned lengths select the current deviation window; NaN lengths give gaps. */
+declare function dev(values: readonly number[], period: number | readonly number[], options?: NumericalWindowOptions): number[];
+/**
+ * Percentage of period previous values less than or equal to the current
+ * subject, excluding the subject itself. Omitted options preserve legacy
+ * behavior. Supplied `skip` collects previous finite observations; `propagate`
+ * requires a full previous chronological window. A missing subject or
+ * insufficient history produces NaN under either policy. Equality counts.
+ * Invalid option-path periods throw RangeError; malformed policies throw
+ * TypeError. Periods must be positive safe integers.
+ */
+declare function percentRank(values: readonly number[], period: number, options?: NumericalWindowOptions): number[];
+/** Bar-aligned lengths count previous observations. A missing current subject or length gives NaN. */
+declare function percentRank(values: readonly number[], period: number | readonly number[], options?: NumericalWindowOptions): number[];
 /** the reference `alma`: Gaussian-weighted MA, `offset` 0..1 and `sigma` > 0. */
 declare function alma(values: readonly number[], period: number, offset: number, sigma: number): number[];
 /** the reference `vwma`: `sma(src * volume, len) / sma(volume, len)`. */
 declare function vwma(values: readonly number[], volumes: readonly number[], period: number): number[];
 /**
- * the reference `highestbars` / `lowestbars`: the **offset** to the extreme bar
- * in the window, `0` for the current bar and `-(period - 1)` for the oldest.
- * Aroon is built entirely out of these, and the sign convention is why.
+ * Highest-value bar offset, zero for current and negative into history; ties
+ * choose the latest bar. Omitted options preserve legacy behavior. Supplied
+ * `skip` searches period finite observations and retains original bar indices,
+ * so an offset can extend beyond period-1 and ages across missing current bars.
+ * `propagate` requires period chronological finite bars. Warmup and all-missing
+ * history are NaN. Invalid option-path periods throw RangeError; malformed
+ * policies throw TypeError. Periods must be positive safe integers.
+ */
+declare function highestBars(values: readonly number[], period: number, options?: NumericalWindowOptions): number[];
+/** Bar-aligned lengths retain original offsets and latest ties; NaN lengths give gaps. */
+declare function highestBars(values: readonly number[], period: number | readonly number[], options?: NumericalWindowOptions): number[];
+/**
+ * Lowest-value bar offset, zero for current and negative into history; ties
+ * choose the latest bar. Omitted options preserve legacy behavior. Supplied
+ * `skip` searches period finite observations using their original indices;
+ * offsets age across gaps. `propagate` requires a full chronological window.
+ * Warmup and all-missing history are NaN. Invalid option-path periods throw
+ * RangeError; malformed policies throw TypeError. Periods must be positive
+ * safe integers.
+ */
+declare function lowestBars(values: readonly number[], period: number, options?: NumericalWindowOptions): number[];
+/** Bar-aligned lengths retain original offsets and latest ties; NaN lengths give gaps. */
+declare function lowestBars(values: readonly number[], period: number | readonly number[], options?: NumericalWindowOptions): number[];
+/**
+ * Fresh oldest-first sum over each complete finite window; NaN on warmup or
+ * overflow. Missing values expire with the window. Valid integer periods use
+ * O(n * period) time and O(1) extra working storage, excluding the result.
+ * Unsupported scalar periods retain their historical behavior.
  */
-declare function highestBars(values: readonly number[], period: number): number[];
-declare function lowestBars(values: readonly number[], period: number): number[];
-/** the reference `sum`: rolling sum over `period` bars. NaN during warmup. */
 declare function rollingSum(values: readonly number[], period: number): number[];
 /** the reference `cum`: running total from the first bar. Non-finite terms count as 0. */
 declare function cumulative(values: readonly number[]): number[];
@@ -1074,7 +1314,22 @@ declare function cci(values: readonly number[], period: number): number[];
  * not a pivot.
  */
 declare function pivotHigh(values: readonly number[], left: number, right: number): number[];
+/**
+ * Array widths align with the source and are read on the confirmation bar.
+ * NaN array elements give gaps; scalar companions and other array elements
+ * must be nonnegative safe integers. Mismatched array lengths throw RangeError.
+ * Zero widths are valid. Finite neighbors and strict comparisons are required.
+ * Results stay on confirmation bars, including repeated confirmations of one
+ * candidate. Invalid numbers throw RangeError; malformed elements TypeError.
+ */
+declare function pivotHigh(values: readonly number[], left: number | readonly number[], right: number | readonly number[]): number[];
 declare function pivotLow(values: readonly number[], left: number, right: number): number[];
+/**
+ * Array widths follow pivotHigh's validation and confirmation placement, with
+ * strictly lower candidates. Missing widths or neighbors give NaN. Both widths
+ * are read from the current confirmation bar, even if the candidate repeats.
+ */
+declare function pivotLow(values: readonly number[], left: number | readonly number[], right: number | readonly number[]): number[];
 /** the reference `barssince`: bars elapsed since `cond` was last true, NaN before the first. */
 declare function barsSince(cond: readonly boolean[]): number[];
 /**
@@ -1110,6 +1365,10 @@ interface Tier2Point {
 interface Tier2Context {
     /** Host identity when supplied. Indicator settings remain independent. */
     dataContext?: Readonly<ChartDataContext>;
+    /** Native source, provider and external-data revisions, when supplied. */
+    requestState?: Readonly<IndicatorRequestState>;
+    /** Inclusive availability cutoff during opted-in native timed replay. */
+    asOf?: number;
     /** Cancelled when this request is obsolete or the instance is removed. */
     signal?: AbortSignal;
     settings: Readonly<IndicatorSettings>;
@@ -1152,6 +1411,13 @@ interface Tier2Descriptor {
     supports?(ctx: Tier2Context): boolean;
     /** Load the series for the current window. */
     fetch(ctx: Tier2Context): Promise<readonly Tier2Point[]>;
+    /**
+     * Opt into native timed replay. fetch must honor finite ctx.asOf, return the
+     * values known then, and use point.time as availability time. Raw requestBars
+     * does not supply historical value versions automatically. Native legacy
+     * replay without an availability clock remains unsupported. Defaults false.
+     */
+    supportsReplay?: boolean;
     /**
      * Optional live subscription. Call `push` with each incoming point; return an
      * unsubscribe function.
@@ -1187,12 +1453,9 @@ 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:
+ * securitySeries aligns aggregate OHLC values. securityExpression calculates
+ * on aggregate bars before alignment, so a rolling window counts requested
+ * bars rather than repeated aligned values. securitySeries names its readings:
  *
  * - `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.
@@ -1211,6 +1474,16 @@ declare function createTier2Indicator(d: Tier2Descriptor): IndicatorDescriptor;
  * its hourly bars.
  */
 
+interface SecurityExpressionOptions {
+    timezone?: string;
+    session?: string;
+    /**
+     * confirmed (default) holds the previous observed bucket's result once the
+     * next bucket starts. developing calculates with the current partial bucket.
+     * lookahead aligns the current bucket's final result onto its earlier bars.
+     */
+    mode?: 'confirmed' | 'developing' | 'lookahead';
+}
 interface SecurityOptions {
     /** The calendar the buckets are cut in. Defaults to the shipped default zone. */
     timezone?: string;
@@ -1244,6 +1517,124 @@ interface SecuritySeries {
     isNew: boolean[];
 }
 declare function securitySeries(bars: readonly Bar[], interval: string, options?: SecurityOptions): SecuritySeries;
+/**
+ * Evaluate on aggregated bars first, then align named columns to source bars.
+ * This differs from applying a rolling formula to already aligned OHLC values,
+ * which counts each repeated requested value as another observation.
+ *
+ * The expression must be pure and causal, returning one value per requested
+ * bar in each column. Confirmed and lookahead modes evaluate the folded history
+ * once; developing mode evaluates every source prefix, with no future source
+ * bars, so its cost includes one expression call per source bar. Completed
+ * buckets are inferred only when the next observed bucket starts. Missing
+ * buckets are not fabricated and the last bucket is never clock-confirmed.
+ *
+ * Supply bars finer than or equal to the requested interval. This function
+ * cannot manufacture lower-timeframe observations from coarser source bars.
+ * Source timestamps must increase strictly. Empty data returns {} without
+ * invoking the expression. Non-finite expression results become null.
+ */
+declare function securityExpression(bars: readonly Bar[], interval: string, expression: (bars: readonly Readonly<Bar>[]) => IndicatorValues, options?: SecurityExpressionOptions): IndicatorValues;
+
+/**
+ * A pure, causal calculation with one value per requested bar in each named
+ * column. Output at index i may depend only on input through i. Helpers cannot
+ * prove callback causality. Inputs are copied and frozen, including each bar.
+ */
+type RequestedExpression = (bars: readonly Readonly<Bar>[]) => IndicatorValues;
+interface RequestedAlignmentOptions {
+    /**
+     * carry retains the latest eligible row, including null values. missing emits
+     * only when the selected row changes; the first target is an initial reading.
+     */
+    gaps?: 'carry' | 'missing';
+}
+/** Opening-time membership is [start, end); availability may equal end. */
+interface RequestedTimeWindow {
+    start: number;
+    end: number;
+}
+interface RequestedIntrabarOptions {
+    /** Inclusive UTC availability cutoff in addition to each window's end. */
+    asOf?: number;
+}
+/** Arrays retain requested row order, including missing expression values. */
+interface RequestedIntrabarValues {
+    times: number[][];
+    values: Record<string, (number | null)[][]>;
+}
+/**
+ * Calculate once on the whole requested history, then align to finite, strictly
+ * increasing UTC evaluation times. The confirmed prefix ends at the first
+ * unconfirmed bar or unknown availability; that bar and all later bars remain
+ * in expression input but cannot emit. Availability is the cumulative maximum
+ * across each prefix. Simultaneously available rows select the latest one.
+ *
+ * Missing/nonfinite results become null and replace older readings. An empty
+ * snapshot returns {} without invoking the expression; an empty target with
+ * nonempty requested history still evaluates to obtain named empty columns.
+ * Invalid timestamps, metadata, options or output shapes throw IndicatorInputError.
+ * Inputs are fully validated before the callback. Runtime is O((n + targets) *
+ * columns), plus expression cost. No transport, aggregation or clock inference.
+ */
+declare function alignRequestedExpression(targetTimes: readonly number[], snapshot: RequestedBarsSnapshot, expression: RequestedExpression, options?: RequestedAlignmentOptions): IndicatorValues;
+/**
+ * Calculate once across all requested observations, then group by nonoverlapping
+ * ordered windows. Windows must have finite start < end; gaps are allowed.
+ * An observation belongs by its opening in [start, end), and emits only when
+ * its confirmed prefix is available by end and by optional finite asOf.
+ * Delayed observations never move to a later window. Expression history never
+ * restarts at window boundaries. Empty windows return empty arrays.
+ *
+ * Uses the same prefix, missing-value, validation and empty-snapshot rules as
+ * alignRequestedExpression. Result times are openings, not availability times.
+ * Runtime is O(n * columns + windows * columns), plus expression cost.
+ */
+declare function requestedIntrabars(targetWindows: readonly RequestedTimeWindow[], snapshot: RequestedBarsSnapshot, expression: RequestedExpression, options?: RequestedIntrabarOptions): RequestedIntrabarValues;
+
+/** Source and settings visible to request selection and requested calculation. */
+interface RequestedIndicatorContext {
+    bars: readonly Bar[];
+    settings: Readonly<IndicatorSettings>;
+    dataContext?: Readonly<ChartDataContext>;
+    requestState?: Readonly<IndicatorRequestState>;
+    calculation?: IndicatorCalcContext;
+}
+/** A requested expression with an instance-owned snapshot lifecycle. */
+interface RequestedIndicatorDescriptor extends Pick<IndicatorDescriptor, 'id' | 'name' | 'category' | 'placement' | 'inputs' | 'plots' | 'levels' | 'range'> {
+    /**
+     * Select a complete history window, including expression warmup. null means
+     * unsupported. The helper owns cancellation; signal is not a selector input.
+     * Symbol, exchange, interval and explicit asOf changes start a new generation.
+     * Window changes refresh the complete selection without merging partial pages.
+     */
+    request(ctx: RequestedIndicatorContext): Omit<IndicatorSnapshotRequest, 'signal'> | null;
+    /**
+     * Calculate on copied, frozen requested bars before alignment. Each result at
+     * i must depend only on requested observations through i. Return every plot's
+     * named column with one value per requested bar. Nonfinite values become null.
+     * Under asOf, only the known, confirmed prefix available by that cutoff is
+     * supplied. Provider correctness for historical value versions remains required.
+     */
+    expression(bars: readonly Readonly<Bar>[], settings: Readonly<IndicatorSettings>, ctx: RequestedIndicatorContext): IndicatorValues;
+    /** carry retains the latest eligible row, including null; missing emits a newly selected row only. */
+    gaps?: RequestedAlignmentOptions['gaps'];
+    /**
+     * Strictly increasing finite availability query times, one per source bar.
+     * Defaults to source opening times. Use an explicit final playhead time when
+     * a forming source bar should observe requested data available after opening.
+     */
+    targetTimes?(ctx: RequestedIndicatorContext): readonly number[];
+}
+/**
+ * Manage one requested snapshot per instance. Changes are observed through the
+ * optional native request hooks, or through data notifications on older hosts.
+ * There is at most one active request and one latest pending refresh. Provider,
+ * source, history or market changes and backward replay cancel obsolete work.
+ * Synchronous style reattachment retains pending work when its selection is
+ * unchanged. Calculation performs no requests and never prealigns cached values.
+ */
+declare function createRequestedIndicator(d: RequestedIndicatorDescriptor): IndicatorDescriptor;
 
 declare const INDICATORS_TIER: "indicators";
 /** Every built-in descriptor, in picker order. */
@@ -1255,4 +1646,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, 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 };
+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, type NumericalWindowOptions, 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, type RequestedAlignmentOptions, type RequestedExpression, type RequestedIndicatorContext, type RequestedIndicatorDescriptor, type RequestedIntrabarOptions, type RequestedIntrabarValues, type RequestedTimeWindow, type RollingVarianceOptions, 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 SecurityExpressionOptions, 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, alignRequestedExpression, alma, barsSince, cci, centerOfGravity, change, connorsStreak, correlation, createRequestedIndicator, createTier2Indicator, crosses, crossesAbove, crossesBelow, cumulative, dev, falling, highest, highestBars, linreg, lowest, lowestBars, nulls, percentRank, percentileLinear, percentileNearestRank, pivotHigh, pivotLow, rankCorrelation, registerBuiltinIndicators, requestedIntrabars, rising, rma, roc, rollingMedian, rollingMode, rollingRange, rollingSum, rollingVariance, runningMax, runningMin, securityExpression, securitySeries, sma, smaSeededEma, stdev, stoch, swma, valueWhen, vwma, wma };