@livefolio/sdk 0.3.1 → 0.3.3

package/dist/index.d.ts

@@ -114,9 +114,81 @@ declare class IndicatorHandle {
     private _sync;
     private _upsertSeries;
     private _querySeriesFromDb;
+    /**
+     * Apply leverage compounding to a raw bar series, anchored to a stored
+     * leveraged value. Used by both `_sync` and `computeAt` so they stay
+     * consistent.
+     *
+     * `anchorDate` is the date of the last *already-stored* leveraged bar
+     * (i.e., the bar just before `rawBars[0]`). The stored leveraged value
+     * at that date becomes `leveraged[0]`; raw returns are then compounded
+     * forward for each subsequent bar.
+     *
+     * If no stored anchor exists (first-ever sync), falls back to rawBars[0]
+     * as the starting raw value — identical to `_sync`'s behaviour.
+     */
+    private _applyLeverage;
+    /**
+     * Compute the indicator's value at `date` without persisting anything, with
+     * optional live-quote `overrides` keyed by raw market symbol (the same symbol
+     * space `MarketProvider.fetchBars` uses — ticker symbols for Price/SMA/etc.,
+     * `^VIX` / `^VIX3M` for macro, FRED series IDs like `DGS3MO` for Treasury).
+     *
+     * Bars for the underlying symbol are resolved storage-first when the market
+     * hasn't yet produced bars for `date` (trading day still open), and storage
+     * is the fallback whenever the remote fetch fails — see `_resolveRawBars`.
+     *
+     * For Threshold: returns the threshold constant. For calendar types: computed
+     * from `tradingDays.getRange()`. For all others: `_resolveRawBars` → leverage
+     * compounding (if any) → lookback-specific computation. Returns null if the
+     * value cannot be computed.
+     */
+    computeAt(date: string, overrides?: Record<string, number>): Promise<number | null>;
+    /**
+     * Raw (unleveraged) bars for `symbol` up through `date`, with the live quote
+     * from `overrides[symbol]` (if any) spliced in at `date`.
+     *
+     * Decision policy:
+     *   - `date` > `tradingDays.getLatestClosed()`: market has nothing for that
+     *     day yet — skip the remote fetch entirely and read from storage.
+     *   - otherwise: try `this._market.fetchBars(symbol, from)`. On failure, fall
+     *     back to storage — upstream HTTP providers (Yahoo / FRED) are flaky.
+     *
+     * After the base is resolved, `overrides[symbol]` is spliced at `date`
+     * (replaces the existing bar, or is appended in-order). When no override is
+     * present but `date` isn't in the base bars, the last known value is carried
+     * forward to `date` — this preserves the fallbackMissingQuotes behaviour the
+     * old overlay exposed so leverage compounding / computations always have a
+     * point at `date` to land on.
+     */
+    private _resolveRawBars;
+    /**
+     * Resolve raw (unleveraged) bars for a market symbol from storage. Maps:
+     *   - `^VIX`   → the VIX indicator's stored series
+     *   - `^VIX3M` → the VIX3M indicator's stored series
+     *   - `DGS*`   → the matching Treasury-tenor indicator's stored series
+     *   - anything else → the `Price` indicator for that ticker symbol with
+     *     `leverage = 1` (the raw contract that `MarketProvider.fetchBars` has).
+     *
+     * Returns `[]` when the resolved indicator has no stored bars yet.
+     */
+    private _readStoredBars;
     series(range?: DateRange): Promise<DailyBar[]>;
     private _syntheticThresholdSeries;
     value(date?: string): Promise<number | null>;
+    /**
+     * Read-only preview of the indicator series with an in-memory bar at `date`
+     * computed via `computeAt` with the supplied live-quote `overrides`. Does
+     * NOT write to `indicators_series`. Safe to call before market close.
+     *
+     * @param date - Target trading day whose value is computed in-memory.
+     *   Must be in `tradingDays.getRange()`.
+     * @param overrides - Raw (unleveraged) quotes keyed by market symbol.
+     *   Symbols omitted fall back to the last known value (see `_resolveRawBars`).
+     * @param range - Optional filter applied to the returned bars.
+     * @returns Stored historical bars plus (or with) today's in-memory value.
+     */
+    previewSeries(date: string, overrides: Record<string, number>, range?: DateRange): Promise<DailyBar[]>;
 }
 
 interface StorageProvider {
@@ -188,6 +260,7 @@ interface StorageProvider {
         getSeries(strategyId: number, range?: DateRange): Promise<StrategySeriesEntry[]>;
         writeSeries(strategyId: number, entries: StrategySeriesEntry[]): Promise<void>;
         getLatestSeriesDate(strategyId: number): Promise<string | null>;
+        getLatestAllocationId(strategyId: number): Promise<number | null>;
         resolveReference(linkId: string): Promise<StrategyReferenceData>;
     };
     tradingDays: {
@@ -208,13 +281,12 @@ declare class SignalHandle {
     readonly comparison: Comparison;
     readonly tolerance: number;
     private _storage;
-    private _market;
     private _resolvedId;
     private _resolving;
     private _cachedSeries;
     private _cachedAsOf;
     private _syncing;
-    constructor(storage: StorageProvider, market: MarketProvider, identity: SignalIdentity);
+    constructor(storage: StorageProvider, _market: MarketProvider, identity: SignalIdentity);
     get id(): number;
     resolve(): Promise<{
         id: number;
@@ -228,8 +300,31 @@ declare class SignalHandle {
     private _sync;
     private _upsertSeries;
     private _querySeriesFromDb;
+    /**
+     * Compute the signal's boolean value at `date` without persisting anything,
+     * with optional live-quote `overrides` that are routed through each
+     * indicator's `computeAt`. Returns null if either indicator cannot produce
+     * a value at `date`.
+     *
+     * @param prevBool - The signal's boolean value at the bar immediately
+     *   preceding `date`, used for hysteresis when `tolerance > 0`. If not
+     *   provided, falls back to `storage.signals.getLastValue` (suitable for
+     *   standalone callers). On the preview path `_evaluate` passes this from
+     *   the in-memory `dateMap` so we never read stale storage.
+     */
+    computeAt(date: string, overrides?: Record<string, number>, prevBool?: boolean | null): Promise<boolean | null>;
     series(range?: DateRange): Promise<DailyBar[]>;
     value(date?: string): Promise<number | null>;
+    /**
+     * Read-only preview of the signal series with an in-memory bar at `date`
+     * computed via `computeAt` with the supplied live-quote `overrides`. Does
+     * NOT write to `signals_series`.
+     *
+     * @param date - Target trading day whose boolean is computed in-memory.
+     * @param overrides - Raw (unleveraged) quotes keyed by market symbol.
+     * @param range - Optional filter applied to the returned bars.
+     */
+    previewSeries(date: string, overrides: Record<string, number>, range?: DateRange): Promise<DailyBar[]>;
 }
 
 declare class AllocationHandle {
@@ -280,6 +375,45 @@ interface FinalState {
     closePrices: Record<string, number>;
     leveragedPrices: Record<string, number>;
 }
+/** Per-signal slice of a live strategy snapshot. */
+interface LiveSignalState {
+    indicator1: {
+        value: number | null;
+        date: string | null;
+    };
+    indicator2: {
+        value: number | null;
+        date: string | null;
+    };
+    isTrue: boolean;
+}
+/** Per-rule collection of live signal states, in the same order as the rule's `when` list. */
+interface LiveRuleState {
+    signals: LiveSignalState[];
+}
+/** Full live strategy view for a single evaluation date — no portfolio info. */
+interface StrategyLiveState {
+    allocation: AllocationHandle | null;
+    activeRuleIndex: number;
+    rules: LiveRuleState[];
+}
+/**
+ * Combined live state returned by `SimulationHandle.pushAndPreview`: both the
+ * portfolio snapshot from a `push` and the strategy evaluation at the target
+ * date under the accumulated live-quote overrides.
+ */
+interface LivePreviewState extends StrategyLiveState {
+    snapshot: PortfolioSnapshot;
+}
+/**
+ * Callback shape that `SimulationHandle.pushAndPreview` delegates to. Exists
+ * purely to break the circular import between `SimulationHandle` (in this
+ * file) and `StrategyHandle` (which creates simulations) — a strategy passes
+ * a bound `(date, overrides) => previewLiveState(...)` into the handle.
+ */
+interface LiveEvaluator {
+    previewLiveState(date: string, overrides: Record<string, number>): Promise<StrategyLiveState>;
+}
 declare class SimulationHandle {
     readonly series: DailyBar[];
     readonly trades: Trade[];
@@ -290,8 +424,30 @@ declare class SimulationHandle {
     private _lastLeveragedPrices;
     private _currentLeveragedPrices;
     private _lastDate;
-    constructor(series: DailyBar[], trades: Trade[], startingPortfolio: PortfolioHandle, finalState?: FinalState);
+    private _pushedQuotes;
+    private _liveEvaluator;
+    constructor(series: DailyBar[], trades: Trade[], startingPortfolio: PortfolioHandle, finalState?: FinalState, liveEvaluator?: LiveEvaluator);
     push(...prices: [TickerHandle, number][]): PortfolioSnapshot;
+    /**
+     * One-call live update. Feeds portfolio-relevant ticker prices into `push`
+     * (derived from `quotes` via the running portfolio's holdings), accumulates
+     * every symbol in `quotes` into an internal override map so macro symbols
+     * (e.g. `^VIX`) persist across ticks, then delegates to the simulation's
+     * strategy for rule / signal / indicator evaluation at `date`.
+     *
+     * Without a live evaluator attached, returns just the portfolio snapshot
+     * with allocation/rules/signals empty.
+     *
+     * @param quotes Symbol → raw live price. Portfolio tickers flow through
+     *   `push` for leveraged-equity math; non-portfolio symbols are still
+     *   layered into the overlay so indicators can see them.
+     * @param options.date Target trading day to evaluate against. Defaults to
+     *   the current UTC ISO date; callers with non-UTC semantics or after-hours
+     *   rollover should supply their own.
+     */
+    pushAndPreview(quotes: Record<string, number>, options?: {
+        date?: string;
+    }): Promise<LivePreviewState>;
 }
 
 interface StrategyRule {
@@ -339,10 +495,56 @@ declare class StrategyHandle {
     private _getLatestStrategySeriesDate;
     private _ensureFresh;
     private _sync;
+    /**
+     * Pure evaluate — runs the same pipeline as _sync but returns the computed
+     * evaluation instead of persisting. Used by both _sync (post-close write
+     * path) and the public preview methods (pre-close read-only path).
+     *
+     * When `overrides` is `undefined` we take the write path — syncing signals
+     * through storage as normal. When `overrides` is provided (even an empty
+     * map) we take the read-only preview path: historical signal bars come
+     * straight from storage, today's bar is computed in-memory via
+     * `signal.computeAt(date, overrides, prevBool)`, and nothing is written.
+     */
+    private _evaluate;
     private _querySeriesFromDb;
     series(range?: DateRange): Promise<StrategyBar[]>;
     value(date?: string): Promise<AllocationHandle | null>;
     simulate(options: SimulateOptions): Promise<SimulationHandle>;
+    /**
+     * Preview the allocation this strategy would produce for `date` if today
+     * closed at the provided raw quote prices. Does NOT write to strategies_series,
+     * signals_series, or indicators_series. Safe to call before market close.
+     *
+     * @param date - The trading day to preview (must be in tradingDays.getRange()).
+     * @param overrides - Raw (unleveraged) live prices keyed by market symbol.
+     *   Symbols absent from this map fall back to the last stored value
+     *   (see `IndicatorHandle._resolveRawBars`).
+     * @returns The AllocationHandle for `date`, or null if the strategy has no
+     *   evaluable entry for that date.
+     */
+    previewAllocation(date: string, overrides: Record<string, number>): Promise<AllocationHandle | null>;
+    /**
+     * Read-only preview of the strategy's allocation series including `date`.
+     * Returns stored historical allocations plus an in-memory bar at `date`
+     * computed via the same overrides-based preview path as `previewAllocation`.
+     *
+     * @param date - Target trading day to splice in-memory.
+     * @param overrides - Raw (unleveraged) quotes keyed by market symbol.
+     * @param range - Optional filter applied to the returned bars.
+     */
+    previewSeries(date: string, overrides: Record<string, number>, range?: DateRange): Promise<StrategyBar[]>;
+    /**
+     * Full live strategy view at `date` under live-quote `overrides`: the active
+     * allocation, the index of the rule that fired (or fallback), and per-rule
+     * per-signal indicator values + truth. Computed entirely through the
+     * overrides preview path — no writes to any `*_series` tables.
+     *
+     * Threshold indicators have their date suppressed (`null`) since their
+     * synthetic series runs over every trading day in storage including future
+     * dates and would report a far-future date for the last bar.
+     */
+    previewLiveState(date: string, overrides: Record<string, number>): Promise<StrategyLiveState>;
     private _fetchPricesForTickers;
     private _fetchRawClosePrices;
 }
@@ -394,4 +596,4 @@ interface PriceStream {
     close(): void;
 }
 
-export { AllocationHandle, type Comparison, type DailyBar, type DateRange, IndicatorHandle, type IndicatorIdentity, type IndicatorType, type LivefolioClient, type LivefolioClientOptions, type MarketProvider, PortfolioHandle, type PortfolioSnapshot, type PriceStream, SignalHandle, type SignalIdentity, type SimulateOptions, SimulationHandle, type StorageProvider, type StrategyBar, type StrategyDefinition, StrategyHandle, type StrategyOptions, type StrategyReferenceData, type StrategyRule, type StrategyRuleDefinition, type StrategySeriesEntry, type StreamStatus, TickerHandle, type Trade, type TradingFreq, type Unit, createClient };
+export { AllocationHandle, type Comparison, type DailyBar, type DateRange, IndicatorHandle, type IndicatorIdentity, type IndicatorType, type LiveEvaluator, type LivePreviewState, type LiveRuleState, type LiveSignalState, type LivefolioClient, type LivefolioClientOptions, type MarketProvider, PortfolioHandle, type PortfolioSnapshot, type PriceStream, SignalHandle, type SignalIdentity, type SimulateOptions, SimulationHandle, type StorageProvider, type StrategyBar, type StrategyDefinition, StrategyHandle, type StrategyLiveState, type StrategyOptions, type StrategyReferenceData, type StrategyRule, type StrategyRuleDefinition, type StrategySeriesEntry, type StreamStatus, TickerHandle, type Trade, type TradingFreq, type Unit, createClient };