@alphacharts/indicators 0.1.0 → 0.1.1

package/dist/types/chart/marker-floor.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The first bar index whose mark is kept, over bars `[0, n)` of `col`: marks at
+ * or after it are drawn, those before are not. 0 when the plot asks for no limit.
+ */
+export declare function markerFloor(col: ArrayLike<number>, n: number, o: {
+    last?: number;
+    within?: number;
+    text?: boolean;
+}): number;

package/dist/types/chart/studies.d.ts

@@ -1,4 +1,5 @@
 import { type Chart, type ChartPlugin, type DataChange, type PluginApi, type PluginPaneView, type Series, type SeriesType } from "@alphacharts/core";
+import { type FeedBar, type FeedBars, type FeedConfig } from "../engine/feed.js";
 import { type StudyRunner } from "../runner.js";
 import type { InputValue, Params, StudyDef } from "../types.js";
 export declare const PLUGIN_ID = "alphacharts.studies";
@@ -37,6 +38,11 @@ export declare class Study {
     private engine;
     private outs;
     private lines;
+    /** Background shading: one primitive per bgcolor plot, attached to the series of the pane it shades. */
+    private shades;
+    /** Outside series the host gave this study, by key. */
+    private feeds;
+    private sameScale;
     private styles;
     private shown;
     private pane;
@@ -67,8 +73,11 @@ export declare class Study {
     refresh(onlyLast?: boolean): void;
     /** Output series, in plot order. */
     series(): readonly AnySeries[];
-    /** Change inputs; unspecified ones keep their value. Validated before anything changes. */
-    setInputs(partial: Readonly<Record<string, InputValue>>): void;
+    /**
+     * Change inputs; unspecified ones keep their value, and the keys in `reset` go back to their defaults (a preset that
+     * has no value for an input the study has). Validated before anything changes. Outside series the study was given stay.
+     */
+    setInputs(partial: Readonly<Record<string, InputValue>>, reset?: readonly string[]): void;
     setVisible(visible: boolean): void;
     setStyle(plotKey: string, style: PlotStyle): void;
     remove(): void;
@@ -88,6 +97,20 @@ export declare class Study {
         inputs: Record<string, InputValue>;
         source: string;
     };
+    /**
+     * Give the study outside series `key` (see engine/feed.ts for what a feed is and how it is joined), replacing the
+     * previous bars of that key, and compute everything again. The study keeps its own copy.
+     */
+    setFeed(key: string, bars: FeedBars, cfg: FeedConfig): void;
+    /** Keys of the outside series given so far. */
+    feedKeys(): string[];
+    /**
+     * A live bar of outside series `key` (same time as its last bar revises it, a later time appends). Only the study's
+     * last bar is evaluated again, and only when it sees a different feed bar through the join; otherwise nothing is
+     * recomputed or redrawn.
+     */
+    pushFeedBar(key: string, bar: FeedBar): void;
+    get isShown(): boolean;
     private get ohlc();
     private checkSource;
     /** Whether `d` is the store of one of this study's inputs. */
@@ -105,6 +128,8 @@ export declare class Study {
     private seriesOptions;
     private createSeries;
     private syncAll;
+    /** Background shades and bar colours, from the engine's columns (every bar). */
+    private syncOverlays;
     private writeSeries;
     /** Show enough decimals for values below 1 (three significant digits); only ever grows. A def's own `minMove` wins; an overlay reads like its source. */
     private widen;
@@ -122,6 +147,8 @@ export declare class StudiesPlugin implements ChartPlugin {
     api: PluginApi | null;
     private readonly studies;
     private counter;
+    /** Sources whose bars the plugin has coloured: the plugin owns their colour column while a barcolor study exists. */
+    private readonly coloured;
     constructor(chart: Chart, runner: StudyRunner | undefined, resolve: (id: string) => StudyDef);
     install(api: PluginApi): void;
     uninstall(): void;

package/dist/types/engine/feed.d.ts

@@ -0,0 +1,88 @@
+import { Graph } from "./graph.js";
+export type FeedField = "open" | "high" | "low" | "close" | "volume";
+export declare const FEED_FIELDS: readonly FeedField[];
+export type FeedAlign = "same" | "closed";
+export interface FeedConfig {
+    align: FeedAlign;
+    /** Nominal length of one feed bar, ms. Used by "closed" (> 0); ignored by "same". */
+    spanMs: number;
+}
+/** Columnar bars of a feed, in the feed's own time. */
+export interface FeedBars {
+    time: Float64Array;
+    open: Float64Array;
+    high: Float64Array;
+    low: Float64Array;
+    close: Float64Array;
+    volume: Float64Array;
+}
+export interface FeedBar {
+    time: number;
+    open: number;
+    high: number;
+    low: number;
+    close: number;
+    volume: number;
+}
+/** A feed as sent to a runner: its bars and how to join them. */
+export interface FeedData extends FeedConfig {
+    bars: FeedBars;
+}
+export type FeedChange = "appended" | "revised";
+/**
+ * A feed is a graph of its own whose bars are the other series' bars: its base columns (time, open, high, low, close,
+ * volume) are the series itself, and whatever is computed from it (a script's `ta.rsi(outside(...), 14)`) is computed
+ * on those bars, so a window of 14 is 14 of the series' bars whatever the chart's timeframe. The chart's graph reads
+ * the result through the join (`Graph.joined`). Loading or ticking the feed evaluates its graph at once.
+ */
+export declare class Feed {
+    readonly graph: Graph;
+    align: FeedAlign;
+    spanMs: number;
+    private cur;
+    get n(): number;
+    /** Replace the bars (copied) and the join. Throws, naming `what`, on bars that are not a series. */
+    load(bars: FeedBars, cfg: FeedConfig, what?: string): void;
+    /** Change how the bars are joined, keeping them. */
+    configure(cfg: FeedConfig, what?: string): void;
+    /** A live bar: the same time as the last bar replaces it, a later time appends; an earlier time throws. */
+    apply(b: FeedBar, what?: string): FeedChange;
+    /** The bars as a runner takes them (copies, length n). */
+    snapshot(): FeedBars;
+    /** Index of the feed bar the study bar at time `t` sees, or -1 when it sees none. */
+    lookup(t: number): number;
+    value(field: FeedField, i: number): number;
+}
+/** Row `field` of every bar in `feed` joined onto `times`, as a plain array: the join in one call (for tests and tools). */
+export declare function joinFeed(feed: Feed, field: FeedField, times: ArrayLike<number>): Float64Array;
+export type JoinReason = 
+/** Every chart bar sees a feed bar. */
+"complete"
+/** Some chart bars see a feed bar and some do not (holes in the feed, or the feed starts later or ends earlier). */
+ | "partial"
+/** The join finds nothing: the chart has no bars, or the feed has none. */
+ | "empty"
+/** Same-length join and the feed's bar times never equal the chart's: the two sit on different clocks (offsetMs). */
+ | "different-clock"
+/** Longer-timeframe join and no feed bar has finished by any chart bar (the feed starts after the chart ends, or is too short). */
+ | "no-finished-bar";
+export interface JoinReport {
+    align: FeedAlign;
+    chartBars: number;
+    /** Chart bars that see a feed bar. A chart bar that sees none is blank (NaN) in everything read from the feed. */
+    matched: number;
+    reason: JoinReason;
+    /**
+     * For "different-clock": how far the feed's bars sit from the chart's, in ms, in (-spanMs/2, spanMs/2]: the first feed bar's
+     * time minus the first chart bar's, modulo the bar length. NSE hourly bars open at 09:15 and MCX's at 09:00, so a chart on one
+     * reading the other gives +900000 or -900000. Otherwise null.
+     */
+    offsetMs: number | null;
+    /** One sentence a host can show where it would otherwise show "blank". */
+    message: string;
+}
+/**
+ * Why a join gives what it gives, for a host to explain a blank outside series: how many chart bars `cfg` joins to a bar of `feedTimes`
+ * and, when none, the reason. A pure function of the two time columns and the config handed to `setFeed`; it reads no value.
+ */
+export declare function describeJoin(chartTimes: ArrayLike<number>, feedTimes: ArrayLike<number>, cfg: FeedConfig): JoinReport;

package/dist/types/engine/graph.d.ts

@@ -1,3 +1,4 @@
+import { Feed, type FeedField } from "./feed.js";
 export type Ref = Col | number;
 export declare class Col {
     v: Float64Array;
@@ -23,6 +24,8 @@ export declare class Graph {
     readonly close: Col;
     readonly volume: Col;
     private readonly sources;
+    /** Outside series by key: bars given by the host, joined onto this graph's bars by `external`. */
+    readonly feeds: Map<string, Feed>;
     constructor(cap?: number);
     /** An auxiliary column (state a node keeps per bar). */
     col(): Col;
@@ -41,6 +44,15 @@ export declare class Graph {
     /** A constant as a column-compatible value. */
     private val;
     src(name: SourceName): Node;
+    /** The feed `key` (created empty on first use: its bars arrive from the host, and until they do every join is absent). */
+    feed(key: string): Feed;
+    /** Field `field` of feed `key` joined onto this graph's bars (see feed.ts for the two joins). NaN where the join finds no bar. */
+    external(key: string, field: FeedField): Node;
+    /**
+     * A column of feed `key`'s own graph (its base columns by name, or anything computed on its bars) read through the
+     * join: at each bar of this graph, the value at the feed row the join finds, NaN when it finds none.
+     */
+    joined(key: string, col: Col | FeedField): Node;
     map(x: Col, f: (x: number) => number): Node;
     map2(x: Ref, y: Ref, f: (x: number, y: number) => number): Node;
     add(x: Ref, y: Ref): Node;
@@ -80,9 +92,11 @@ export declare class Graph {
     /**
      * Population variance over p bars (TA-Lib VAR): mean-centred two-pass over the
      * window, because running sums of squares lose ~1e-8 relative on price series.
+     * `sample` divides by p - 1 instead (the unbiased estimator, the one a Sharpe or volatility estimate from a sample uses): the
+     * population value scaled by p / (p - 1), undefined for p = 1.
      */
-    variance(x: Col, p: number): Node;
-    stdev(x: Col, p: number): Node;
+    variance(x: Col, p: number, sample?: boolean): Node;
+    stdev(x: Col, p: number, sample?: boolean): Node;
     /**
      * Least-squares line over the last p bars against x = 0..p-1 (oldest..newest).
      * `value` is the line at the newest bar; `slope` per bar; `intercept` at the oldest bar.
@@ -96,6 +110,27 @@ export declare class Graph {
     alias(c: Col): Node;
     /** True range: max(h-l, |h-c'|, |l-c'|); the first bar has no previous close, so is absent (TA-Lib TRANGE). */
     tr(): Node;
+    /** True range with the first bar's range as high - low (Wilder; Pine's `ta.tr(true)`). */
+    trFirst(): Node;
+    /**
+     * Average true range as Wilder defined it: the first true range is high - low, the seed is the
+     * mean of true ranges 0..p-1 (first value at bar p-1), then Wilder's smoothing. Not TA-Lib's ATR (TA-Lib skips the first
+     * true range, so it starts one bar later and differs by a different seed).
+     */
     atr(p: number): Node;
+    /**
+     * Bars per year, read from the bars of this graph and from nothing after the bar it is written on (a causal annualisation). Intraday bars: the median number of bars per exchange-clock day over the
+     * last {@link BPY_SESSIONS} finished days, times 252 sessions (nights and weekends add no bars). A day or longer between bars: 252 a
+     * year for daily bars that leave weekends out, otherwise calendar time (365 days over the median spacing: weekly 52.14,
+     * monthly 12.17), the median over the last {@link BPY_COARSE} bars. Constant within a day, so a finished bar's value never changes
+     * when later bars arrive or the last bar is revised; absent before the first day has finished (and, for a day or
+     * longer, before six bars). The day is cut at `offsetMin` minutes east of UTC: 0 suits every session inside one UTC day
+     * (NSE, BSE, MCX, NYSE, LSE).
+     */
+    barsPerYear(offsetMin?: number): Node;
 }
+/** Finished days whose bar counts the median is taken over (barsPerYear). */
+export declare const BPY_SESSIONS = 60;
+/** Bars the spacing and the weekend test are read from when bars are a day or longer (barsPerYear). */
+export declare const BPY_COARSE = 120;
 export declare function checkPeriod(p: number): void;

package/dist/types/engine/study.d.ts

@@ -1,5 +1,6 @@
 import { Graph, type Col } from "./graph.js";
 import type { BarColumns, BarInput, InputValue, Params, StudyDef } from "../types.js";
+import type { FeedBar, FeedConfig, FeedBars } from "./feed.js";
 /** Validate `given` against the study's inputs and fill defaults. Throws on anything unknown or out of range. */
 export declare function resolveParams(def: StudyDef, given?: Readonly<Record<string, InputValue>>): Params;
 /** A study bound to parameters and a graph: appends, revises and batch-loads bars. */
@@ -18,6 +19,14 @@ export declare class StudyEngine {
      * returns false when `cancelled()` turns true.
      */
     loadChunked(d: BarColumns, chunk: number, pause: () => Promise<void>, cancelled: () => boolean): Promise<boolean>;
+    /** Give the study outside series `key`: bars in their own time and how to join them (copied). Run the study again afterwards. */
+    setFeed(key: string, bars: FeedBars, cfg: FeedConfig): void;
+    /**
+     * A live bar of outside series `key`: the feed's last bar is replaced or one is appended, and what the study computed
+     * on the feed's bars follows. When the study's last bar now sees a different feed row (or the same one revised), that
+     * bar is evaluated again and `true` is returned; otherwise nothing of the study is recomputed. O(1) amortised.
+     */
+    pushFeed(key: string, bar: FeedBar): boolean;
     /** Append a bar (time later than the last). */
     push(b: BarInput): void;
     /** Replace the last bar (a tick revision). */

package/dist/types/index.d.ts

@@ -2,10 +2,13 @@ export * from "./types.js";
 export { Graph, Col, Node, SOURCE_NAMES } from "./engine/graph.js";
 export type { Ref, SourceName } from "./engine/graph.js";
 export { StudyEngine, resolveParams, runStudy } from "./engine/study.js";
+export { Feed, FEED_FIELDS, describeJoin, joinFeed } from "./engine/feed.js";
+export type { FeedAlign, FeedBar, FeedBars, FeedChange, FeedConfig, FeedData, FeedField, JoinReason, JoinReport } from "./engine/feed.js";
 export { registerStudy, registerStudies, getStudy, listStudies, validateDef } from "./registry.js";
 export { defineStudy } from "./define.js";
 export { addStudy, installStudies, StudiesPlugin, Study, PLUGIN_ID } from "./chart/studies.js";
 export type { AddStudyOptions, PlotStyle } from "./chart/studies.js";
+export { markerFloor } from "./chart/marker-floor.js";
 export { InlineRunner, WorkerRunner, createRunner, serveWorker, CancelledError, CHUNK } from "./runner.js";
 export type { StudyRunner, RunRequest, RunResult, WorkerLike } from "./runner.js";
 export { enableWasm, disableWasm } from "./wasm.js";

package/dist/types/runner.d.ts

@@ -1,3 +1,4 @@
+import type { FeedBar, FeedData } from "./engine/feed.js";
 import type { BarColumns, InputValue, StudyDef } from "./types.js";
 export declare const CHUNK: number;
 export interface RunRequest {
@@ -5,6 +6,8 @@ export interface RunRequest {
     params: Readonly<Record<string, InputValue>>;
     /** Transferred to the runner when it is a worker: do not use afterwards. */
     bars: BarColumns;
+    /** Outside series by key, each a copy the runner may keep or transfer. Only a runner that can run a study that reads them (a script) uses them. */
+    feeds?: Record<string, FeedData>;
 }
 export interface RunResult {
     n: number;
@@ -22,6 +25,11 @@ export interface StudyRunner {
         promise: Promise<RunResult>;
         cancel(): void;
     };
+    /**
+     * A live bar of outside series `key` for a study this runner holds state for; the runner answers through the channel
+     * its ticks use. Optional: a runner that keeps no per-study state (every batch starts afresh) does not have it.
+     */
+    feedBar?(def: StudyDef, key: string, bar: FeedBar): void;
     dispose(): void;
 }
 /** Main-thread fallback: same chunked evaluation, same cancellation. */
@@ -75,8 +83,9 @@ export declare class WorkerRunner implements StudyRunner {
 /** Worker-side message handler: wire it to `self.onmessage` (see worker.ts). */
 export declare function serveWorker(post: (msg: WorkerReply, transfer?: Transferable[]) => void, find: (id: string) => StudyDef | undefined): (data: unknown) => void;
 /**
- * A worker runner when Workers exist and start, otherwise the inline fallback.
- * `factory` creates the worker (default: dist/worker.js next to this module).
+ * A worker runner on the worker `factory` creates, otherwise (no factory, or the worker would not start) the inline fallback.
+ * The package never guesses where its worker lives: the host's bundler spells the URL out,
+ * `() => new Worker(new URL("@alphacharts/indicators/worker", import.meta.url), { type: "module" })`.
  */
 export declare function createRunner(builtinIds: ReadonlySet<string>, factory?: () => WorkerLike): StudyRunner;
 export {};

package/dist/types/studies/tv-volume.d.ts

@@ -12,3 +12,4 @@ export declare const anchoredVwap: import("../types.js").StudyDef;
 export declare const pivotPoints: import("../types.js").StudyDef;
 export declare const histVol: import("../types.js").StudyDef;
 export declare const adr: import("../types.js").StudyDef;
+export declare const barsPerYear: import("../types.js").StudyDef;

package/dist/types/types.d.ts

@@ -29,10 +29,18 @@ export type PlotDef = (PlotBase & {
     color: string;
     width?: number;
     style?: LineStyleName;
-    /** Shift in bars (positive = into the future). Negative shifts and `connect` draw on the overlay. */
-    offset?: number;
+    /** Shift in bars (positive = into the future). Negative shifts and `connect` draw on the overlay. A function is worked out from the study's inputs (`-right`). */
+    offset?: number | ((p: Params) => number);
     /** Join across absent bars (drawn on the overlay). */
     connect?: boolean;
+    /**
+     * Per-point colour: where column `col` is present and not zero, the line segment arriving at that bar is drawn in
+     * `color` instead of the plot's own. The column is an ordinary one (a 0/1 condition), computed with the rest.
+     */
+    colorBy?: {
+        col: string;
+        color: string;
+    };
 }) | (PlotBase & {
     kind: "histogram";
     col: string;
@@ -73,10 +81,33 @@ export type PlotDef = (PlotBase & {
     shape: MarkerShape;
     position: "value" | "above" | "below" | "sign";
     color: string;
-    /** Shift in bars (positive = into the future); Fractals confirm two bars late and shift back. */
-    offset?: number;
+    /** Shift in bars (positive = into the future); Fractals confirm two bars late and shift back. A function is worked out from the study's inputs (`-right`). */
+    offset?: number | ((p: Params) => number);
     /** Draw the value as text (pattern scores) instead of a shape. */
     text?: boolean;
+    /** Keep only the most recent `last` marked bars. Decided from the finished columns each time they are drawn, so a tick or a batch gives the same marks. */
+    last?: number;
+    /** Keep only marks on the final `within` bars. */
+    within?: number;
+})
+/**
+ * Colours the candles (or OHLC bars) of the study's source series on every bar where column `col` is present and
+ * not zero. Several barcolor plots (and several studies) compose: the latest one that applies to a bar wins; a bar none
+ * applies to keeps its up/down colours. Needs an OHLC source.
+ */
+ | (PlotBase & {
+    kind: "barcolor";
+    col: string;
+    color: string;
+})
+/**
+ * Shades the background of the study's pane (the source's pane for an overlay) on every bar where column `col` is
+ * present and not zero. Takes no part in autoscale.
+ */
+ | (PlotBase & {
+    kind: "bgcolor";
+    col: string;
+    color: string;
 })
 /** ZigZag: `price` at the confirmation bar and `back` bars to the pivot; joined by straight lines. */
  | (PlotBase & {
@@ -97,6 +128,11 @@ export interface StudyDef {
     needs: StudyNeeds;
     /** Where it is drawn: on the source's pane or in a pane of its own. */
     pane: "overlay" | "new";
+    /**
+     * Which price scale its series use: "right" (default) or the chart's "left" axis, so a series of another magnitude
+     * shares the pane without flattening the price. Either side needs the chart to show that axis to be read.
+     */
+    scale?: "right" | "left";
     /** Names of the computed columns, in the order `build` returns them. */
     columns: readonly string[];
     plots: readonly PlotDef[];

package/dist/worker.js

@@ -1,5 +1,5 @@
-import { o as e } from "./runner-DBP0M8z3.js";
-import { t } from "./all-DeXJJd7D.js";
+import { o as e } from "./runner-B53M0IsJ.js";
+import { t } from "./all-_xzUPrL7.js";
 //#region src/worker.ts
 var n = new Map(t.map((e) => [e.id, e])), r = self, i = e((e, t) => r.postMessage(e, t), (e) => n.get(e));
 r.onmessage = (e) => i(e.data);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@alphacharts/indicators",
-  "version": "0.1.0",
-  "description": "Technical studies for AlphaCharts: a typed study model, an incremental engine, a Web Worker runner and 210 studies.",
+  "version": "0.1.1",
+  "description": "Technical studies for alphacharts: a typed study model, an incremental engine, a Web Worker runner and 211 studies.",
   "keywords": [
     "indicators",
     "technical-analysis",
@@ -25,7 +25,10 @@
     "access": "public"
   },
   "type": "module",
-  "sideEffects": false,
+  "sideEffects": [
+    "./dist/worker.js",
+    "./src/worker.ts"
+  ],
   "main": "./dist/index.js",
   "module": "./dist/index.js",
   "types": "./dist/types/index.d.ts",
@@ -54,13 +57,13 @@
     "@alphacharts/wasm": "0.1.0"
   },
   "peerDependencies": {
-    "@alphacharts/core": "^0.1.0"
+    "@alphacharts/core": "^0.1.1"
   },
   "devDependencies": {
     "typescript": "5.9.3",
     "vite": "8.3.1",
     "vitest": "5.0.2",
-    "@alphacharts/core": "0.1.0"
+    "@alphacharts/core": "0.1.1"
   },
   "scripts": {
     "build": "vite build && tsc -p tsconfig.build.json",