@backtest-kit/cli 5.10.2 → 5.11.1

package/template/project/docs/backtest_actions.md

@@ -0,0 +1,158 @@
+# Actions (addActionSchema / IPublicAction / pingActive)
+
+## Overview
+
+Actions are lifecycle hooks that run while a position is open. They are registered with `addActionSchema` and attached to a strategy via `actions` array. The most common use is `pingActive` — called on every tick while a pending signal exists.
+
+```ts
+import {
+  addActionSchema,
+  commitClosePending,
+  getPendingSignal,
+  IPublicAction,
+  ActivePingContract,
+} from "backtest-kit";
+```
+
+---
+
+## `addActionSchema`
+
+```ts
+addActionSchema({
+  actionName: "my_action",
+  handler: class implements IPublicAction {
+    async pingActive(event: ActivePingContract) {
+      // called every tick while a position is open
+    }
+  },
+});
+```
+
+Attach to strategy:
+
+```ts
+addStrategySchema({
+  strategyName: "my_strategy",
+  interval: "15m",
+  getSignal: ...,
+  actions: ["my_action"],
+});
+```
+
+---
+
+## `ActivePingContract`
+
+Fields available inside `pingActive`:
+
+| Field | Type | Description |
+|---|---|---|
+| `symbol` | `string` | Trading pair (e.g. `"BTCUSDT"`) |
+
+---
+
+## `getPendingSignal(symbol)`
+
+Returns the currently active pending signal. Use it to read `position`, `priceOpen`, `priceTakeProfit`, `priceStopLoss`.
+
+```ts
+const pendingSignal = await getPendingSignal(event.symbol);
+pendingSignal.position        // "long" | "short"
+pendingSignal.priceOpen       // entry price
+pendingSignal.priceTakeProfit
+pendingSignal.priceStopLoss
+```
+
+---
+
+## `commitClosePending(symbol)`
+
+Closes the active pending signal immediately (market close).
+
+```ts
+await commitClosePending(event.symbol);
+```
+
+---
+
+## Pattern: Close on trend reversal
+
+Close an open position when the trend indicator reverses against it.
+
+```ts
+addActionSchema({
+  actionName: "trend_reversal_close",
+  handler: class implements IPublicAction {
+    async pingActive(event: ActivePingContract) {
+      const shouldClose = await resolve(exitSignal);
+      if (shouldClose) {
+        await commitClosePending(event.symbol);
+      }
+    }
+  },
+});
+```
+
+Where `exitSignal` is an output node that returns `boolean`:
+
+```ts
+const exitSignal = outputNode(
+  async ([trend, pendingSignal]) => {
+    if (!pendingSignal) return false;
+    if (pendingSignal.position === "long"  && trend.position === -1) return true;
+    if (pendingSignal.position === "short" && trend.position ===  1) return true;
+    return false;
+  },
+  masterTrendSource,
+  pendingSignalSource,
+);
+```
+
+See `backtest_graph_multiple_outputs.md` for the full pattern with `enterSignal` / `exitSignal`.
+
+---
+
+## Other `IPublicAction` lifecycle methods
+
+Beyond `pingActive`, actions can implement:
+
+| Method | When called |
+|---|---|
+| `pingActive(event)` | Every tick while position is open |
+| `onOpen(event)` | Position just opened |
+| `onClose(event)` | Position closed (TP/SL/manual) |
+| `onIdle(event)` | Every tick when no position is open |
+
+All methods are optional — implement only what you need.
+
+---
+
+## Pattern: DCA (dollar-cost averaging)
+
+From `feb_2024.strategy.ts`:
+
+```ts
+addActionSchema({
+  actionName: "long_dollar_cost_averaging",
+  handler: class implements IPublicAction {
+    async pingActive(event: ActivePingContract) {
+      const pendingSignal = await getPendingSignal(event.symbol);
+      if (pendingSignal.position !== "long") return;
+      if (pendingSignal.totalEntries > 5) return;
+      const currentPrice = await getAveragePrice(event.symbol);
+      if (currentPrice > pendingSignal.originalPriceOpen) return;
+      if (await getPositionEntryOverlap(event.symbol, currentPrice, {
+        lowerPercent: 0.5, upperPercent: 0.5,
+      })) return;
+      await commitAverageBuy(event.symbol);
+    }
+  },
+});
+```
+
+Key guards before DCA:
+1. `position !== "long"` — skip if wrong direction
+2. `totalEntries > 5` — cap at 5 entries
+3. `currentPrice > originalPriceOpen` — only average down, not up
+4. `getPositionEntryOverlap` — avoid averaging too close to an existing entry

package/template/project/docs/backtest_graph_multiple_outputs.md

@@ -0,0 +1,137 @@
+# Graph Pattern: Multiple Output Nodes (enterSignal / exitSignal)
+
+## Why Two Output Nodes
+
+A strategy can have separate output nodes for entry and exit logic. This keeps concerns separated and allows `exitSignal` to be reused in both an action (`pingActive`) and risk validators independently.
+
+```
+masterTrendSource ──┬──► enterSignal  →  getSignal()
+                    └──► exitSignal   →  pingActive() in action
+fundamentalSource ──►  enterSignal
+pendingSignalSource ──► exitSignal
+garchSource ────────►  risk validator (resolve directly)
+```
+
+---
+
+## Full Pattern
+
+```ts
+import { sourceNode, outputNode, resolve } from "@backtest-kit/graph";
+import { getPendingSignal, commitClosePending } from "backtest-kit";
+
+// --- Source nodes ---
+
+const masterTrendSource = sourceNode(
+  Cache.fn(
+    async (symbol: string) => {
+      const plots = await run(
+        File.fromPath("master_trend_15m.pine", "../../math"),
+        { symbol, timeframe: "15m", limit: 180 },
+      );
+      return extract(plots, {
+        position: "Position",  // -1 | 0 | 1
+        close: "Close",
+      });
+    },
+    { interval: "15m", key: ([symbol]: [string]) => symbol },
+  ),
+);
+
+// Raw source node — no cache, reads live state every tick
+const pendingSignalSource = sourceNode(
+  async (symbol) => await getPendingSignal(symbol),
+);
+
+// --- Output node: entry ---
+
+const enterSignal = outputNode(
+  async ([trend, fundamental]) => {
+    if (fundamental.position === "wait") return null;
+    if (trend.position === 0) return null;
+    const fundamentalDir = fundamental.position === "long" ? 1 : -1;
+    if (fundamentalDir !== trend.position) return null;
+
+    const position = fundamentalDir === 1 ? "long" : "short";
+    const price = trend.close;
+    return {
+      id: randomString(),
+      position,
+      priceTakeProfit: position === "long" ? price * 1.05 : price * 0.95,
+      priceStopLoss:   position === "long" ? price * 0.95 : price * 1.05,
+      minuteEstimatedTime: 480,
+    } as const;
+  },
+  masterTrendSource,
+  fundamentalSource,
+);
+
+// --- Output node: exit ---
+
+const exitSignal = outputNode(
+  async ([trend, pendingSignal]) => {
+    if (!pendingSignal) return false;
+    if (pendingSignal.position === "long"  && trend.position === -1) return true;
+    if (pendingSignal.position === "short" && trend.position ===  1) return true;
+    return false;
+  },
+  masterTrendSource,    // shared with enterSignal — resolved once per tick
+  pendingSignalSource,
+);
+
+// --- Action uses exitSignal ---
+
+addActionSchema({
+  actionName: "trend_reversal_close",
+  handler: class implements IPublicAction {
+    async pingActive(event: ActivePingContract) {
+      const shouldClose = await resolve(exitSignal);
+      if (shouldClose) {
+        await commitClosePending(event.symbol);
+      }
+    }
+  },
+});
+
+// --- Strategy wires enterSignal ---
+
+addStrategySchema({
+  strategyName: "feb_2026_strategy",
+  interval: "15m",
+  getSignal: () => resolve(enterSignal),
+  actions: ["trend_reversal_close"],
+});
+```
+
+---
+
+## Shared Node Deduplication
+
+`masterTrendSource` is a dependency of both `enterSignal` and `exitSignal`. When both are resolved in the same tick, `@backtest-kit/graph` deduplicates by reference — the Pine script runs **once**, not twice.
+
+This is the main reason to split logic into multiple output nodes rather than one large node: each source is computed once regardless of how many output nodes depend on it.
+
+---
+
+## Raw sourceNode (no Cache.fn)
+
+`pendingSignalSource` has no `Cache.fn` wrapper:
+
+```ts
+const pendingSignalSource = sourceNode(
+  async (symbol) => await getPendingSignal(symbol),
+);
+```
+
+Use this pattern when:
+- The data changes every tick and must not be cached (live position state)
+- The source is cheap to fetch (single in-memory lookup)
+- Caching would return stale data within the same candle
+
+Contrast with `masterTrendSource` which uses `Cache.fn` with `interval: "15m"` — Pine runs once per 15m bar and the result is reused for all ticks within that bar.
+
+---
+
+## `exitSignal` return type
+
+`exitSignal` returns `boolean`, not `ISignalDto | null`. Output nodes are not limited to signal shapes — they can return any value that the consumer needs. The action reads `boolean`, the risk validator could read a number, etc.

package/template/project/docs/backtest_graph_pattern.md

@@ -0,0 +1,235 @@
+# Graph Pattern (sourceNode / outputNode / resolve)
+
+## Purpose
+
+`@backtest-kit/graph` provides a typed directed acyclic graph (DAG) for composing strategy logic. Instead of a single monolithic `getSignal` function, you define reusable **source nodes** (data fetchers) and **output nodes** (computations that combine them).
+
+Benefits:
+- Each node caches independently via `Cache.fn`
+- Type-safe: TypeScript infers value types through the graph
+- Parallel resolution: sibling nodes resolve concurrently
+
+---
+
+## Core API
+
+```ts
+import { sourceNode, outputNode, resolve } from "@backtest-kit/graph";
+import { Cache } from "backtest-kit";
+```
+
+### `sourceNode(fetch)`
+
+A leaf node with no dependencies. Fetches data from an external source.
+
+```ts
+const mySource = sourceNode(
+  Cache.fn(
+    async (symbol: string) => {
+      const candles = await getCandles(symbol, "15m", 500);
+      return garch.predictRange(candles, "15m", 32);
+    },
+    { interval: "15m", key: ([symbol]) => symbol },
+  ),
+);
+```
+
+- `fetch` signature: `(symbol: string, when: Date, exchangeName: string) => Promise<T>`
+- `Cache.fn` wraps the fetch function with interval-based caching (see [Cache section](#cachefn))
+- `T` can be any non-undefined value: `number`, `string`, `boolean`, `object`, `null`
+
+### `outputNode(compute, ...nodes)`
+
+A computation node that receives resolved values from its dependencies.
+
+```ts
+const strategySignal = outputNode(
+  async ([trend, volume, reversal]) => {
+    // trend, volume, reversal are the resolved values of the three source nodes
+    if (!volume.reliable) return null;
+    return { position: "long", priceTakeProfit: volume.upperPrice, ... };
+  },
+  masterTrendSource,  // dependency 1 → trend
+  rangeSource,        // dependency 2 → volume
+  reversalSource,     // dependency 3 → reversal
+);
+```
+
+- `compute` receives a tuple of resolved values **in the same order as the nodes**
+- Return type is inferred automatically
+- Can return `null` (no signal)
+- Can be nested: an output node can be a dependency of another output node
+
+### `resolve(node)`
+
+Executes the graph: resolves all dependencies recursively, then calls `compute`.
+
+```ts
+addStrategySchema({
+  strategyName: "my_strategy",
+  interval: "15m",
+  getSignal: () => resolve(strategySignal),
+});
+```
+
+- Dependencies are resolved **in parallel** (Promise.all internally)
+- The `symbol` and `when` context is injected automatically from the strategy runtime
+- Returns the output node's computed value
+
+---
+
+## Cache.fn
+
+Wraps any async function to cache results per candle interval and per cache key.
+
+```ts
+const cachedFn = Cache.fn(
+  async (symbol: string) => {
+    // expensive operation
+    return fetchSomething(symbol);
+  },
+  {
+    interval: "15m",                    // invalidate every 15m candle boundary
+    key: ([symbol]) => symbol,          // separate cache entry per symbol
+  },
+);
+```
+
+**How invalidation works:** The cache aligns to candle boundaries. At `interval="15m"`, the cache is valid within the same 15-minute bar and invalidated when a new bar opens. This means multiple calls within one bar return the same result without re-fetching.
+
+**Without `key`:** single cache entry — all calls share one result regardless of arguments.
+**With `key`:** separate cache entry per key — `"BTCUSDT"` and `"ETHUSDT"` computed independently.
+
+Cache.fn is designed to be passed directly as the `fetch` argument to `sourceNode`.
+
+---
+
+## Full Pattern Example
+
+```ts
+import { extract, run, File } from "@backtest-kit/pinets";
+import { getCandles, getAggregatedTrades, Cache } from "backtest-kit";
+import { sourceNode, outputNode, resolve } from "@backtest-kit/graph";
+import * as garch from "garch";
+import * as anomaly from "volume-anomaly";
+
+// === Source nodes ===
+
+const masterTrendSource = sourceNode(
+  Cache.fn(
+    async (symbol) => {
+      const plots = await run(
+        File.fromPath("master_trend_15m.pine", "../math"),
+        { symbol, timeframe: "15m", limit: 180 },
+      );
+      return extract(plots, {
+        position: "Position",
+        close:    "Close",
+      });
+    },
+    { interval: "15m", key: ([symbol]) => symbol },
+  ),
+);
+
+const rangeSource = sourceNode(
+  Cache.fn(
+    async (symbol) => {
+      const candles = await getCandles(symbol, "15m", 1_000);
+      return garch.predictRange(candles, "15m", 32);
+    },
+    { interval: "15m", key: ([symbol]) => symbol },
+  ),
+);
+
+const reversalSource = sourceNode(
+  Cache.fn(
+    async (symbol) => {
+      const all = await getAggregatedTrades(symbol, 1400);
+      return anomaly.predict(all.slice(0, 1200), all.slice(1200), 0.75);
+    },
+    { interval: "15m", key: ([symbol]) => symbol },
+  ),
+);
+
+// === Output node (signal logic) ===
+
+const strategySignal = outputNode(
+  async ([trend, volume, reversal]) => {
+    if (!volume.reliable || volume.movePercent < 0.7) return null;
+    if (trend.position === 0) return null;
+    if (!reversal.anomaly) return null;
+
+    let position: "long" | "short" | null = null;
+    if (trend.position === 1  && reversal.direction === "long")  position = "long";
+    if (trend.position === -1 && reversal.direction === "short") position = "short";
+    if (!position) return null;
+
+    return {
+      id: randomString(),
+      position,
+      priceTakeProfit:     position === "long" ? volume.upperPrice : volume.lowerPrice,
+      priceStopLoss:       position === "long" ? volume.lowerPrice : volume.upperPrice,
+      minuteEstimatedTime: 480,
+    } as const;
+  },
+  masterTrendSource,
+  rangeSource,
+  reversalSource,
+);
+
+// === Wire into strategy ===
+
+addStrategySchema({
+  strategyName: "bounce_strategy",
+  interval: "15m",
+  getSignal: () => resolve(strategySignal),
+});
+```
+
+---
+
+## Cache Interval Selection
+
+Choose `Cache.fn` interval to match the data's natural update frequency:
+
+| Data source | Recommended interval |
+|---|---|
+| Pine indicator (15m timeframe) | `"15m"` |
+| `garch.predictRange` on 15m candles | `"15m"` |
+| `garch.predict` on 5m candles | `"5m"` |
+| `anomaly.predict` (trade stream) | `"5m"` — refreshed every 5m bar |
+| Funding rate | `"1h"` |
+| Order book snapshot | `"1m"` |
+
+Setting interval too short wastes compute; too long means stale data spanning multiple bars. Match to the smallest timeframe of the data being fetched.
+
+---
+
+## Type Safety
+
+The graph is fully typed. TypeScript infers the compute callback parameter types from the node declarations:
+
+```ts
+// If rangeSource returns garch.PredictionResult:
+const rangeSource = sourceNode(
+  Cache.fn(async (symbol) => garch.predictRange(candles, "15m", 32), { interval: "15m", key: ([s]) => s }),
+);
+// TS knows rangeSource is SourceNode<PredictionResult>
+
+const out = outputNode(
+  async ([volume]) => {
+    volume.movePercent  // ✓ typed as number
+    volume.upperPrice   // ✓ typed as number
+    volume.nonExistent  // ✗ TS error
+  },
+  rangeSource,
+);
+```
+
+---
+
+## Notes
+
+- `resolve()` is called **inside** `getSignal`, not at module level. This ensures the graph runs per-tick with the correct symbol/when context.
+- Each source node in the graph is resolved **once per tick** even if referenced by multiple output nodes (deduplication by reference).
+- The graph does **not** support cycles.