@christtrade/depth 0.12.21

package/types/core/DataEngine.d.ts

@@ -0,0 +1,143 @@
+import { TypedEventBus } from './TypedEventBus';
+import type { IDataAdapter, SymbolInfo, DataLevel, OhlcvBar, TickEvent } from '../interfaces/IDataAdapter';
+import type { FootprintOptions } from '../lib/types/footprint';
+import type { SerialTrade } from '../lib/types';
+import type { PriceHistory } from '../lib/types';
+import type { FootprintBar } from '../lib/types/footprint';
+import type { DataSourceRegistry } from './DataSourceRegistry';
+import { ExecutionEngine } from './ExecutionEngine';
+import { ChartState } from './ChartState';
+import { Timeframe } from '../lib/timeframes';
+export interface DataEngineConfig {
+    initialLoad: {
+        start: string;
+        end: string;
+    };
+    horizon: string;
+    fpOptions?: FootprintOptions;
+    initialWindowNs?: bigint;
+    scrollWindowNs?: bigint;
+    timeframe: Timeframe;
+    /** Active symbol - passed in every FetchRequest so one adapter serves many symbols. */
+    symbol?: string;
+    /**
+     * Symbols served by plugins. A symbol one of them claims is fetched through
+     * that source instead of the adapter, and their symbols are folded into
+     * every picker search alongside the adapter's own.
+     */
+    plugins?: DataSourceRegistry;
+}
+export interface ChartDataSnapshot {
+    readonly dataLevel: DataLevel;
+    readonly trades: SerialTrade[];
+    readonly footprintBars: FootprintBar[];
+    readonly priceHistory: PriceHistory[];
+    /** Populated for ohlcv; derived from footprintBars for l3/tick; empty for l2. */
+    readonly ohlcvBars: OhlcvBar[];
+    /** Populated for tick and l3 (derived from trades). */
+    readonly ticks: TickEvent[];
+    readonly barNs: bigint;
+    /** Unix ms timestamps */
+    readonly dataStart: number;
+    readonly dataEnd: number;
+    readonly symbolInfo: SymbolInfo | null;
+}
+export declare class DataEngine {
+    private readonly eventBus;
+    private readonly state;
+    private adapter;
+    private realtimeUnsub;
+    private executionEngine;
+    private readonly config;
+    private destroyed;
+    private readonly _states;
+    private readonly resolvedSymbols;
+    private readonly paneResolutions;
+    private fpOptions;
+    private initialLoad;
+    private horizonIso;
+    private scrollWindowNs;
+    private activeSymbol;
+    private _loadChain;
+    private symbolUniverse;
+    private symbolUniverseInFlight;
+    private symbolSearchAbort;
+    private latestSymbolSearchId;
+    private readonly symbolSearchCache;
+    private readonly unsubs;
+    readonly sharedData: {
+        dataLevel: DataLevel;
+        compactBuf: ArrayBuffer;
+        trades: SerialTrade[];
+        priceHistory: PriceHistory[];
+        footprintBars: FootprintBar[];
+        ohlcvBars: OhlcvBar[];
+        barNs: bigint;
+        dataStart: number;
+        dataEnd: number;
+        supplemental: Array<{
+            resolution: bigint;
+            bars: Array<{
+                time: number;
+                open: number;
+                high: number;
+                low: number;
+                close: number;
+                volume: number;
+            }>;
+        }> | null;
+    };
+    private maxLookbackBars;
+    constructor(eventBus: TypedEventBus, state: ChartState, config: DataEngineConfig);
+    private _st;
+    private _targetSymbol;
+    setAdapter(adapter: IDataAdapter): void;
+    private _adapterFor;
+    private _applySymbol;
+    getResolvedSymbolInfo(symbol: string): SymbolInfo | null;
+    attachExecutionEngine(engine: ExecutionEngine): void;
+    setLookback(lookback: number): void;
+    load(symbol: string): Promise<void>;
+    private _load;
+    private _loadWindow;
+    seekLoad(targetNs: bigint, fromNs?: bigint): Promise<void>;
+    reload(horizonNs?: bigint): Promise<void>;
+    private _settleGapFills;
+    rehydrate(): void;
+    rebuildFootprint(barNs: bigint, fpOptions?: FootprintOptions): void;
+    getSnapshot(): ChartDataSnapshot;
+    destroy(): void;
+    private _fetchForward;
+    private _fetchBackward;
+    private _supplementalFor;
+    private _symbolSearchMode;
+    private _symbolSearchDebounceMs;
+    private _searchSymbols;
+    private _loadSymbolUniverse;
+    private _withPluginSymbols;
+    private _emitSymbolSearch;
+    private _cacheSymbolSearch;
+    private _cancelSymbolSearch;
+    private _activeBarNs;
+    private _lookbackBarNs;
+    private _onPaneResolution;
+    private _refineStaleSegments;
+    private _effectiveFetchBarNs;
+    private _fetchTimeframe;
+    private _process;
+    private _handleRealtimeBar;
+    private _growMaster;
+    private _prependMaster;
+    private _masterBarNs;
+    private _syncShared;
+    private _subscribeToEventBus;
+    private _runLoadIngest;
+    private _buildPayload;
+    private _emitLoad;
+    private _emitAppend;
+    private _emitPrepend;
+    private _emitAdapterError;
+    private _onTimeframeChange;
+    private _refineSegment;
+    private _openWindows;
+}

package/types/core/DataSourceRegistry.d.ts

@@ -0,0 +1,106 @@
+import type { SerialTrade } from '../lib/types';
+import type { AdapterCapabilities, BarPreviewResponse, BarResponse, FetchRequest, IDataAdapter, SymbolInfo, SymbolSearchRequest, SymbolSearchResponse } from '../interfaces/IDataAdapter';
+/**
+ * A data source registered by a plugin. Everything an {@link IDataAdapter} can
+ * do, plus a claim on the symbols it serves - declare `symbols` when you can
+ * list them, or `prefix` for a namespace.
+ *
+ * Only `fetchBars` is required. The rest have sensible fallbacks, though a
+ * source without `resolveSymbol` is priced as a 24/7 two-decimal instrument.
+ */
+export interface PluginDataSource {
+    /**
+     * Exact symbols this source owns. Prefix convention: `"TYPE:DETAILS"`.
+     */
+    symbols?: string[];
+    /**
+     * Or claim a namespace: every symbol starting with this belongs to the
+     * source, which is what a whole venue behind an API key wants. `''` claims
+     * everything the adapter didn't. The longest matching prefix wins, so a
+     * specific one still beats a catch-all.
+     */
+    prefix?: string;
+    /**
+     * Tick size, price format, session, contract details. Without one the chart
+     * falls back to a 24/7 crypto-ish default, which is rarely what you want -
+     * order sizing and price formatting both read this.
+     */
+    resolveSymbol?(symbol: string): SymbolInfo | Promise<SymbolInfo>;
+    /**
+     * Answer the symbol picker. Results are merged in front of the adapter's
+     * own. Return a {@link SymbolSearchResponse} to page results yourself.
+     * Without this, `symbols` is matched locally instead.
+     */
+    searchSymbols?(request: SymbolSearchRequest): SymbolInfo[] | SymbolSearchResponse | Promise<SymbolInfo[] | SymbolSearchResponse>;
+    /**
+     * Return the bars covering `request.range`. Called for the initial window,
+     * for backward pans, for forward prefetch during playback, and again at a
+     * finer resolution when a pane needs one - `request.direction` says which.
+     */
+    fetchBars(request: FetchRequest): Promise<BarResponse>;
+    /**
+     * Cheap bars for the loading skeleton, drawn before `fetchBars` resolves.
+     * Skip it and the chart just waits.
+     */
+    fetchPreview?(request: FetchRequest): Promise<BarPreviewResponse>;
+    /**
+     * Push live bars as they arrive - a websocket, a poll, anything. Return the
+     * teardown.
+     */
+    subscribeRealtime?(onBar: (bar: BarResponse) => void): () => void;
+    /**
+     * A trade arrived on the host adapter's feed. Return bars to append, or
+     * null to ignore it. This is the hook for a derived instrument, which has
+     * no feed of its own to subscribe to.
+     */
+    onTick?(params: {
+        symbol: string;
+        trade: SerialTrade;
+        barNs: bigint;
+    }): BarResponse | null;
+    /**
+     * Declare supplemental resolutions and how symbol search is filtered. See
+     * {@link AdapterCapabilities}.
+     */
+    getCapabilities?(): AdapterCapabilities;
+    /** Called before the first fetch. Open a socket, refresh a token. */
+    connect?(): Promise<void>;
+    /** Called when the plugin unregisters the source. */
+    destroy?(): void;
+}
+export declare class DataSourceRegistry {
+    private readonly bySymbol;
+    private readonly byPrefix;
+    private readonly resolved;
+    private readonly adapters;
+    private readonly lastRequest;
+    private readonly realtimeSinks;
+    register(source: PluginDataSource): () => void;
+    sourceFor(symbol: string): PluginDataSource | undefined;
+    has(symbol: string): boolean;
+    /** The adapter DataEngine should fetch this symbol through, if any. */
+    adapterFor(symbol: string): IDataAdapter | null;
+    /** The last SymbolInfo handed out for a symbol, if it has been resolved. */
+    getResolved(symbol: string): SymbolInfo | null;
+    resolve(symbol: string): Promise<SymbolInfo | null>;
+    /**
+     * Every registered symbol matching a picker query. Sources with their own
+     * searchSymbols answer it; the rest have their `symbols` matched here.
+     */
+    search(request: SymbolSearchRequest): Promise<SymbolInfo[]>;
+    /**
+     * Longest debounce any registered source wants, or null when none care.
+     * A network search behind someone's rate-limited API key shouldnt fire per
+     * keystroke just because the host adapter matches in memory.
+     */
+    searchDebounceMs(): number | null;
+    /**
+     * Feed a trade from the host adapter to every source building bars off it.
+     * Returns true if any of them produced something.
+     */
+    handleTick(trade: SerialTrade): boolean;
+    destroy(): void;
+    private sources;
+    private capsOf;
+    private adapterOf;
+}