@livefolio/sdk 0.3.0 → 0.3.2

package/dist/index.d.ts

@@ -114,9 +114,53 @@ declare class IndicatorHandle {
     private _sync;
     private _upsertSeries;
     private _querySeriesFromDb;
+    withMarket(market: MarketProvider): IndicatorHandle;
+    /**
+     * 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` using the given market (typically
+     * an overlay market for pre-close preview). Pure — no writes to storage.
+     *
+     * For fetched types (yahoo/fred): fetches a small window of bars from
+     * `market`, applies leverage compounding anchored to the stored leveraged
+     * value at the bar before `date`.
+     * For computed types (SMA, RSI, etc.): fetches enough raw price bars to
+     * cover the indicator's lookback from `market`, applies leverage anchored
+     * to the stored value just before the fetch window, runs the computation,
+     * and returns the value at `date`.
+     * For Threshold: returns the threshold constant.
+     * For calendar: computes calendar value from the trading days list.
+     * Returns null if the value cannot be computed.
+     */
+    computeAt(market: MarketProvider, date: string): Promise<number | null>;
     series(range?: DateRange): Promise<DailyBar[]>;
     private _syntheticThresholdSeries;
     value(date?: string): Promise<number | null>;
+    /**
+     * Read-only preview of the indicator series that includes an in-memory bar
+     * at `date` computed via `computeAt` against a quote-overlay market. Does
+     * NOT write to `indicators_series`. Safe to call before market close.
+     *
+     * @param date - Target trading day whose value is computed in-memory from
+     *   the overridden quotes. Must be in `tradingDays.getRange()`.
+     * @param quoteOverrides - Raw (unleveraged) quotes keyed by ticker symbol.
+     *   Symbols omitted here fall back to yesterday's close via the overlay.
+     * @param range - Optional filter applied to the returned bars.
+     * @returns Stored historical bars plus (or with) today's in-memory value.
+     */
+    previewSeries(date: string, quoteOverrides: Record<string, number>, range?: DateRange): Promise<DailyBar[]>;
 }
 
 interface StorageProvider {
@@ -188,6 +232,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: {
@@ -228,8 +273,31 @@ declare class SignalHandle {
     private _sync;
     private _upsertSeries;
     private _querySeriesFromDb;
+    withMarket(market: MarketProvider): SignalHandle;
+    /**
+     * Compute the signal's boolean value at `date` using the given market
+     * (typically an overlay market for pre-close preview). Pure — no writes.
+     * 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(market: MarketProvider, date: string, 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` against a quote-overlay market. Does NOT write
+     * to `signals_series`.
+     *
+     * @param date - Target trading day whose boolean is computed in-memory.
+     * @param quoteOverrides - Raw (unleveraged) quotes keyed by ticker symbol.
+     * @param range - Optional filter applied to the returned bars.
+     */
+    previewSeries(date: string, quoteOverrides: Record<string, number>, range?: DateRange): Promise<DailyBar[]>;
 }
 
 declare class AllocationHandle {
@@ -339,10 +407,46 @@ 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 previewAllocation (pre-close read-only path).
+     *
+     * The `market === this._market` identity check is what distinguishes the two
+     * paths: when they are the same object the method takes the write path (syncing
+     * signals through storage as normal); when they differ it takes the read-only
+     * preview path (historical bars from storage, today's value computed in-memory
+     * via `computeAt`). Callers that want the preview path must therefore supply a
+     * *different* market object — for example one produced by `createQuoteOverlay`.
+     */
+    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 quoteOverrides - Raw (unleveraged) live prices keyed by ticker symbol.
+     *   Symbols absent from this map will fall back to yesterday's close via the
+     *   quote overlay.
+     * @returns The AllocationHandle for `date`, or null if the strategy has no
+     *   evaluable entry for that date.
+     */
+    previewAllocation(date: string, quoteOverrides: 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 overlay path as `previewAllocation`.
+     *
+     * @param date - Target trading day to splice in-memory via overlay market.
+     * @param quoteOverrides - Raw (unleveraged) quotes keyed by ticker symbol.
+     * @param range - Optional filter applied to the returned bars.
+     */
+    previewSeries(date: string, quoteOverrides: Record<string, number>, range?: DateRange): Promise<StrategyBar[]>;
     private _fetchPricesForTickers;
     private _fetchRawClosePrices;
 }