openalgo-charts 2.2.2 → 2.3.0

package/dist/transform/index.d.ts

@@ -226,6 +226,134 @@ declare class KagiTransform implements ISeriesTransform {
     flush(): Bar[];
 }
 
+/**
+ * Symbol arithmetic: a chart of `NIFTY1!/NSE:RELIANCE`, `(A+B)/2`, `1/GOLD`.
+ *
+ * Two halves, deliberately separate. `parseExpression` turns a string into an
+ * AST and, crucially, tells the caller which symbols it needs *before* any data
+ * is fetched, so a host can resolve and load exactly those legs.
+ * `evaluateExpression` then folds the legs into one synthetic bar series.
+ *
+ * The engine does no fetching. A host owns symbol resolution and history, the
+ * same way `addComparison` takes bars rather than a symbol.
+ *
+ * ## Why the high and low are approximations
+ *
+ * A bar says where a market opened, closed, and how far it travelled, but not
+ * *when* it was at each price. For `A/B` the true high of the ratio needs the
+ * instant A was highest relative to B, and two OHLC bars do not record that.
+ *
+ * So the extremes are computed by interval arithmetic: each leg contributes
+ * `[low, high]`, every operator maps intervals to intervals, and the result's
+ * interval is the range the expression *could* have covered. That bound is
+ * guaranteed to contain the truth and is usually wider than it, because it
+ * assumes the legs hit their extremes at the worst possible moments. Open and
+ * close need no such trick: they are read from the legs' own opens and closes,
+ * which are simultaneous by definition, and so are exact.
+ *
+ * One consequence worth knowing: an interval cannot tell that two mentions of
+ * the same symbol move together, so `A/A` bounds to `[low/high, high/low]`
+ * rather than collapsing to 1. That is the classic dependency problem, and it
+ * is why `ohlc: 'close'` (a line from exact closes) is the default.
+ */
+
+/** A parsed expression, with the symbols it needs. */
+interface SymbolExpression {
+    /** The source, as typed. */
+    readonly source: string;
+    /** Distinct symbols, in first-seen order. The first is the default time grid. */
+    readonly symbols: readonly string[];
+    /** Opaque syntax tree. */
+    readonly ast: Node;
+}
+interface EvaluateOptions {
+    /**
+     * `'close'` (default) evaluates only the closes, giving a flat bar whose four
+     * values are equal: exact, and honest about what two OHLC bars can support.
+     * `'interval'` additionally bounds the high and low as described above.
+     */
+    ohlc?: 'close' | 'interval';
+    /**
+     * The leg whose bars define the time grid. Defaults to the first symbol.
+     * Every other leg is matched to it by timestamp; a bar with no match on some
+     * leg produces a gap rather than a guess.
+     */
+    primary?: string;
+}
+type Node = {
+    k: 'num';
+    v: number;
+} | {
+    k: 'sym';
+    name: string;
+} | {
+    k: 'neg';
+    a: Node;
+} | {
+    k: 'bin';
+    op: '+' | '-' | '*' | '/' | '^';
+    a: Node;
+    b: Node;
+} | {
+    k: 'fn';
+    name: FnName;
+    args: Node[];
+};
+/**
+ * Functions are limited to ones whose interval image is cheap and correct to
+ * derive. Anything non-monotonic in a way that needs calculus is left out
+ * rather than shipped with a bound that is quietly wrong.
+ */
+declare const FN_ARITY: {
+    readonly abs: 1;
+    readonly sqrt: 1;
+    readonly ln: 1;
+    readonly log: 1;
+    readonly log10: 1;
+    readonly exp: 1;
+    readonly min: 2;
+    readonly max: 2;
+    readonly pow: 2;
+};
+type FnName = keyof typeof FN_ARITY;
+declare class ExpressionError extends Error {
+    readonly position: number;
+    constructor(message: string, position: number);
+}
+/**
+ * Parse `source` into an expression and the symbols it needs.
+ *
+ * ```ts
+ * const e = parseExpression('NIFTY1!/NSE:RELIANCE');
+ * e.symbols; // ['NIFTY1!', 'NSE:RELIANCE'] -> fetch exactly these
+ * ```
+ *
+ * Throws `ExpressionError` with the offending character's index, so a search
+ * box can underline it. A bare symbol parses too, which lets one code path
+ * handle both an ordinary chart and a synthetic one.
+ */
+declare function parseExpression(source: string): SymbolExpression;
+/** True when `source` is a single plain symbol, needing no arithmetic. */
+declare function isPlainSymbol(source: string): boolean;
+/**
+ * Fold the legs into one synthetic series.
+ *
+ * `legs` maps each symbol in `expr.symbols` to its bars. A symbol with no
+ * entry, or a bar the primary has and a leg does not, yields no output bar: the
+ * series gaps there rather than carrying a stale price forward, because a
+ * ratio against yesterday's close is a number that was never true.
+ *
+ * ```ts
+ * const e = parseExpression('NIFTY1!/NSE:RELIANCE');
+ * const bars = evaluateExpression(e, { 'NIFTY1!': a, 'NSE:RELIANCE': b });
+ * chart.addSeries('line').setData(bars);
+ * ```
+ *
+ * `volume` is deliberately absent from the result. The volume of a ratio is not
+ * a quantity anyone traded, and picking one leg's would be arbitrary.
+ */
+declare function evaluateExpression(expr: SymbolExpression, legs: Readonly<Record<string, readonly Bar[]>>, options?: EvaluateOptions): Bar[];
+
 declare const TRANSFORM_TIER: "transform";
 /**
  * Register the Family-B custom renderers (point-figure, kagi). Called as a side
@@ -238,4 +366,4 @@ declare const TRANSFORM_TIER: "transform";
  */
 declare function registerTransformChartTypes(): void;
 
-export { HeikinAshiTransform, type ISeriesTransform, type KagiOptions, KagiTransform, type LineBreakOptions, LineBreakTransform, type PointFigureBoxMode, type PointFigureColumn, type PointFigureMethod, type PointFigureOptions, PointFigureTransform, RangeBarsTransform, type RangeOptions, type RenkoOptions, RenkoTransform, TRANSFORM_TIER, ensureIncreasingTimes, registerTransformChartTypes, runTransform };
+export { type EvaluateOptions, ExpressionError, HeikinAshiTransform, type ISeriesTransform, type KagiOptions, KagiTransform, type LineBreakOptions, LineBreakTransform, type PointFigureBoxMode, type PointFigureColumn, type PointFigureMethod, type PointFigureOptions, PointFigureTransform, RangeBarsTransform, type RangeOptions, type RenkoOptions, RenkoTransform, type SymbolExpression, TRANSFORM_TIER, ensureIncreasingTimes, evaluateExpression, isPlainSymbol, parseExpression, registerTransformChartTypes, runTransform };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openalgo-charts",
-  "version": "2.2.2",
+  "version": "2.3.0",
   "description": "From-scratch, dependency-free canvas charting engine for OpenAlgo: professional-grade interactive rendering, advanced on-chart trading, and a one-call widget tier that adds the toolbar, drawing rail, dialogs and shortcuts.",
   "license": "Apache-2.0",
   "author": "marketcalls",