@backtest-kit/graph 3.0.0

package/README.md

@@ -0,0 +1,304 @@
+<img src="https://github.com/tripolskypetr/backtest-kit/raw/refs/heads/master/assets/assignation.svg" height="45px" align="right">
+
+# 📊 @backtest-kit/graph
+
+> Compose backtest-kit computations as a typed directed acyclic graph. Define source nodes that fetch market data and output nodes that compute derived values — then resolve the whole graph in topological order.
+
+![screenshot](https://raw.githubusercontent.com/tripolskypetr/backtest-kit/HEAD/assets/screenshots/screenshot8.png)
+
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/tripolskypetr/backtest-kit)
+[![npm](https://img.shields.io/npm/v/@backtest-kit/graph.svg?style=flat-square)](https://npmjs.org/package/@backtest-kit/graph)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.0+-blue)]()
+
+📚 **[Backtest Kit Docs](https://backtest-kit.github.io/documents/example_02_first_backtest.html)** | 🌟 **[GitHub](https://github.com/tripolskypetr/backtest-kit)**
+
+## 🔥 Multi-timeframe Pine Script strategy
+
+The graph below replicates a two-timeframe strategy: a 4h Pine Script acts as a trend filter, a 15m Pine Script generates the entry signal. `outputNode` combines them and returns `null` when the trend disagrees.
+
+```typescript
+import { extract, run, toSignalDto, File } from '@backtest-kit/pinets';
+import { addStrategySchema, Cache } from 'backtest-kit';
+import { randomString } from 'functools-kit';
+import { sourceNode, outputNode, resolve } from '@backtest-kit/graph';
+
+// SourceNode — 4h trend filter, cached per candle interval
+const higherTimeframe = sourceNode(
+    Cache.fn(
+        async (symbol) => {
+            const plots = await run(File.fromPath('timeframe_4h.pine'), {
+                symbol,
+                timeframe: '4h',
+                limit: 100,
+            });
+            return extract(plots, {
+                allowLong:  'AllowLong',
+                allowShort: 'AllowShort',
+                noTrades:   'NoTrades',
+            });
+        },
+        { interval: '4h', key: ([symbol]) => symbol },
+    ),
+);
+
+// SourceNode — 15m entry signal, cached per candle interval
+const lowerTimeframe = sourceNode(
+    Cache.fn(
+        async (symbol) => {
+            const plots = await run(File.fromPath('timeframe_15m.pine'), {
+                symbol,
+                timeframe: '15m',
+                limit: 100,
+            });
+            return extract(plots, {
+                position:            'Signal',
+                priceOpen:           'Close',
+                priceTakeProfit:     'TakeProfit',
+                priceStopLoss:       'StopLoss',
+                minuteEstimatedTime: 'EstimatedTime',
+            });
+        },
+        { interval: '15m', key: ([symbol]) => symbol },
+    ),
+);
+
+// OutputNode — applies MTF filter, returns ISignalDto or null
+const mtfSignal = outputNode(
+    async ([higher, lower]) => {
+        if (higher.noTrades) return null;
+        if (lower.position === 0) return null;
+        if (higher.allowShort && lower.position === 1) return null;
+        if (higher.allowLong && lower.position === -1) return null;
+
+        return toSignalDto(randomString(), lower, null);
+    },
+    higherTimeframe,
+    lowerTimeframe,
+);
+
+addStrategySchema({
+    strategyName: 'mtf_graph_strategy',
+    interval: '5m',
+    getSignal: (symbol) => resolve(mtfSignal),
+    actions: ['partial_profit_action', 'breakeven_action'],
+});
+```
+
+The graph resolves both Pine Script nodes **in parallel** via `Promise.all`, then passes their typed results to `compute`. Replacing either timeframe script or adding a third filter node requires no changes to the strategy wiring.
+
+
+## 🚀 Installation
+
+```bash
+npm install @backtest-kit/graph backtest-kit
+```
+
+## ✨ Features
+
+- 📊 **DAG execution**: Nodes are resolved bottom-up in topological order with `Promise.all` parallelism
+- 🔒 **Type-safe values**: TypeScript infers the return type of every node through the graph via generics
+- 🧱 **Two APIs**: Low-level `INode` for runtime/storage, high-level `TypedNode` + builders for authoring
+- 💾 **DB-ready serialization**: `serialize` / `deserialize` convert the graph to a flat `IFlatNode[]` list with `id` / `nodeIds`
+- 🔌 **Context-aware fetch**: `SourceNode.fetch` receives `(symbol, when, exchangeName)` from the execution context automatically
+
+## 📖 Usage
+
+### Quick Start — builder API
+
+Use `sourceNode` and `outputNode` to define a typed computation graph. TypeScript infers the type of `values` in `compute` from the `nodes` passed to `outputNode`:
+
+```typescript
+import { sourceNode, outputNode, resolve } from '@backtest-kit/graph';
+
+// SourceNode<number> — fetch receives symbol, when, exchangeName from context
+const closePrice = sourceNode(async (symbol, when, exchangeName) => {
+    const candles = await getCandles(symbol, '1h', 1, exchangeName);
+    return candles[0].close; // number
+});
+
+// SourceNode<number>
+const volume = sourceNode(async (symbol, when, exchangeName) => {
+    const candles = await getCandles(symbol, '1h', 1, exchangeName);
+    return candles[0].volume; // number
+});
+
+// OutputNode<[SourceNode<number>, SourceNode<number>], number>
+// price and vol are automatically number
+const vwap = outputNode(
+    ([price, vol]) => price * vol,
+    closePrice,
+    volume,
+);
+
+// Resolve inside a backtest-kit strategy
+const result = await resolve(vwap); // Promise<number>
+```
+
+### Inline anonymous composition
+
+The entire graph can be defined as a single object literal.
+
+```typescript
+import { NodeType } from '@backtest-kit/graph';
+import { TypedNode, resolve } from '@backtest-kit/graph';
+
+const signal: TypedNode = {
+    type: NodeType.OutputNode,
+    nodes: [
+        {
+            type: NodeType.SourceNode,
+            fetch: async (symbol, when, exchangeName) => {
+                const plots = await run(File.fromPath('timeframe_4h.pine'), { symbol, timeframe: '4h', limit: 100 });
+                return extract(plots, { allowLong: 'AllowLong', allowShort: 'AllowShort', noTrades: 'NoTrades' });
+            },
+        },
+        {
+            type: NodeType.SourceNode,
+            fetch: async (symbol, when, exchangeName) => {
+                const plots = await run(File.fromPath('timeframe_15m.pine'), { symbol, timeframe: '15m', limit: 100 });
+                return extract(plots, { position: 'Signal', priceOpen: 'Close', priceTakeProfit: 'TakeProfit', priceStopLoss: 'StopLoss' });
+            },
+        },
+    ],
+    compute: ([higher, lower]) => {
+        if (higher.noTrades || lower.position === 0) return null;
+        if (higher.allowShort && lower.position === 1) return null;
+        if (higher.allowLong && lower.position === -1) return null;
+        return lower.position;
+    },
+};
+
+const result = await resolve(signal);
+```
+
+### Mixed types
+
+TypeScript correctly infers heterogeneous types by position in `nodes`:
+
+```typescript
+const price = sourceNode(async (symbol) => 42);        // SourceNode<number>
+const name  = sourceNode(async (symbol) => 'BTCUSDT'); // SourceNode<string>
+const flag  = sourceNode(async (symbol) => true);      // SourceNode<boolean>
+
+const result = outputNode(
+    ([p, n, f]) => `${n}: ${p} (active: ${f})`, // p: number, n: string, f: boolean
+    price,
+    name,
+    flag,
+);
+// OutputNode<[SourceNode<number>, SourceNode<string>, SourceNode<boolean>], string>
+```
+
+### Using inside a backtest-kit strategy
+
+```typescript
+import { addStrategy } from 'backtest-kit';
+import { sourceNode, outputNode, resolve } from '@backtest-kit/graph';
+
+const rsi = sourceNode(async (symbol, when, exchangeName) => {
+    // ... compute RSI
+    return 55.2;
+});
+
+const signal = outputNode(
+    ([rsiValue]) => rsiValue < 30 ? 1 : rsiValue > 70 ? -1 : 0,
+    rsi,
+);
+
+addStrategy({
+    strategyName: 'graph-rsi',
+    interval: '1h',
+    riskName: 'demo',
+    getSignal: async (symbol) => {
+        const direction = await resolve(signal); // 1 | -1 | 0
+        return direction === 1
+            ? { position: 'long', ... }
+            : null;
+    },
+});
+```
+
+### Low-level INode
+
+For manual graph construction without builders (e.g. after deserialization or in a DI container):
+
+```typescript
+import { INode, Value } from '@backtest-kit/graph';
+import NodeType from '@backtest-kit/graph/enum/NodeType';
+
+const priceNode: INode = {
+    type: NodeType.SourceNode,
+    description: 'Close price',
+    fetch: async (symbol, when, exchangeName) => 42,
+};
+
+const outputNode: INode = {
+    type: NodeType.OutputNode,
+    description: 'Doubled price',
+    nodes: [priceNode],
+    compute: ([price]) => (price as number) * 2,
+};
+```
+
+> `INode` has no generic parameters — `values` in `compute` is typed as `Value[]`. Use `TypedNode` and builders for full IntelliSense.
+
+### DB serialization
+
+`serialize` flattens the graph into an `IFlatNode[]` array, replacing object references in `nodes` with `nodeIds`. `deserialize` reconstructs the tree:
+
+```typescript
+import { serialize, deserialize, IFlatNode } from '@backtest-kit/graph';
+
+// Graph → flat array for DB
+const flat: IFlatNode[] = serialize([vwap]);
+// [
+//   { id: 'abc', type: 'source_node', nodeIds: [] },            // closePrice
+//   { id: 'def', type: 'source_node', nodeIds: [] },            // volume
+//   { id: 'ghi', type: 'output_node', nodeIds: ['abc', 'def'] }, // vwap
+// ]
+
+// Save to DB
+await db.collection('nodes').insertMany(flat);
+
+// Load from DB and reconstruct the graph
+const stored: IFlatNode[] = await db.collection('nodes').find().toArray();
+const roots: INode[] = deserialize(stored); // nodes[] is wired up from nodeIds
+```
+
+> `fetch` and `compute` are not stored in the DB — they must be restored on the application side after `deserialize`.
+
+### deepFlat — traversal utility
+
+`deepFlat` returns all nodes in topological order (dependencies before parents), deduplicated by reference:
+
+```typescript
+import { deepFlat } from '@backtest-kit/graph';
+
+const all = deepFlat([vwap]);
+// [closePrice, volume, vwap] — dependencies first
+
+all.forEach(node => console.log(node.description));
+```
+
+## 📋 API Reference
+
+| Export | Description |
+|--------|-------------|
+| **`sourceNode(fetch)`** | Builder — creates a typed source node |
+| **`outputNode(compute, ...nodes)`** | Builder — creates a typed output node, infers `values` types from `nodes` |
+| **`resolve(node)`** | Recursively resolves a node graph within backtest-kit execution context |
+| **`serialize(roots)`** | Flattens a node tree into `IFlatNode[]` for DB storage |
+| **`deserialize(flat)`** | Reconstructs a node tree from `IFlatNode[]`, returns root nodes |
+| **`deepFlat(nodes)`** | Utility — returns all nodes in topological order (dependencies first) |
+| **`INode`** | Base runtime interface (untyped, used internally and for serialization) |
+| **`TypedNode`** | Discriminated union for authoring with full IntelliSense |
+| **`IFlatNode`** | Serialized node shape for DB storage |
+| **`Value`** | `string \| number \| boolean \| null` |
+
+## 🤝 Contribute
+
+Fork/PR on [GitHub](https://github.com/tripolskypetr/backtest-kit).
+
+## 📜 License
+
+MIT © [tripolskypetr](https://github.com/tripolskypetr)

package/build/index.cjs

@@ -0,0 +1,129 @@
+'use strict';
+
+var backtestKit = require('backtest-kit');
+var functoolsKit = require('functools-kit');
+
+var NodeType;
+(function (NodeType) {
+    NodeType["SourceNode"] = "source_node";
+    NodeType["OutputNode"] = "output_node";
+})(NodeType || (NodeType = {}));
+var NodeType$1 = NodeType;
+
+const sourceNode = (fetch) => ({
+    type: NodeType$1.SourceNode,
+    fetch,
+});
+const outputNode = (compute, ...nodes) => ({
+    type: NodeType$1.OutputNode,
+    nodes,
+    compute,
+});
+
+/**
+ * Рекурсивно разворачивает граф узлов в плоский массив.
+ * Порядок: сначала зависимости (children), затем родитель — топологический порядок.
+ * Дубликаты (один узел может быть зависимостью нескольких) исключаются по ссылке.
+ */
+const deepFlat = (arr = []) => {
+    const result = [];
+    const seen = new Set();
+    const process = (entries = []) => entries.forEach((entry) => {
+        if (seen.has(entry)) {
+            return;
+        }
+        seen.add(entry);
+        process(entry.nodes ?? []);
+        result.push(entry);
+    });
+    process(arr);
+    return result;
+};
+
+/**
+ * Рекурсивно вычисляет значение узла графа.
+ * Для SourceNode вызывает fetch().
+ * Для OutputNode сначала резолвит все дочерние nodes параллельно,
+ * затем передаёт их типизированные значения в compute().
+ */
+const resolve = async (node) => {
+    if (!backtestKit.ExecutionContextService.hasContext()) {
+        throw new Error("Execution context is required to resolve graph nodes. Please ensure that resolve() is called within a valid execution context.");
+    }
+    if (!backtestKit.MethodContextService.hasContext()) {
+        throw new Error("Method context is required to resolve graph nodes. Please ensure that resolve() is called within a valid method context.");
+    }
+    if (node.type === NodeType$1.SourceNode) {
+        const { symbol, when } = backtestKit.lib.executionContextService.context;
+        const { exchangeName } = backtestKit.lib.methodContextService.context;
+        return node.fetch(symbol, when, exchangeName);
+    }
+    const values = await Promise.all(node.nodes.map(resolve));
+    return node.compute(values);
+};
+
+/**
+ * Преобразует древовидный граф в плоский массив IFlatNode для хранения в БД.
+ * Каждому узлу присваивается уникальный id (если не задан),
+ * объектные ссылки nodes заменяются на массив nodeIds.
+ */
+const serialize = (roots) => {
+    const flat = deepFlat(roots);
+    // Первый проход: назначаем id каждому уникальному узлу
+    const idMap = new Map();
+    flat.forEach((node) => {
+        const id = functoolsKit.randomString();
+        idMap.set(node, id);
+    });
+    // Второй проход: строим IFlatNode с nodeIds вместо nodes
+    return flat.map((node) => {
+        const flatNode = {
+            id: idMap.get(node),
+            type: node.type,
+            description: node.description,
+            fetch: node.fetch,
+            compute: node.compute,
+            nodeIds: node.nodes?.map((child) => idMap.get(child)),
+        };
+        return flatNode;
+    });
+};
+/**
+ * Восстанавливает древовидный граф из плоского массива IFlatNode.
+ * nodes каждого узла заполняется по nodeIds.
+ * Возвращает корневые узлы (те, на которые никто не ссылается).
+ */
+const deserialize = (flat) => {
+    // Первый проход: создаём INode-объекты, индексируем по id
+    const byId = new Map();
+    flat.forEach((flatNode) => {
+        const node = {
+            type: flatNode.type,
+            description: flatNode.description,
+            fetch: flatNode.fetch,
+            compute: flatNode.compute,
+        };
+        byId.set(flatNode.id, node);
+    });
+    // Второй проход: проставляем nodes[] по nodeIds
+    flat.forEach((flatNode) => {
+        if (flatNode.nodeIds?.length) {
+            const node = byId.get(flatNode.id);
+            node.nodes = flatNode.nodeIds
+                .map((id) => byId.get(id))
+                .filter((n) => n !== undefined);
+        }
+    });
+    // Корневые узлы — те, на которые не ссылается никто другой
+    const referenced = new Set(flat.flatMap((n) => n.nodeIds ?? []));
+    return [...byId.entries()]
+        .filter(([id]) => !referenced.has(id))
+        .map(([, node]) => node);
+};
+
+exports.deepFlat = deepFlat;
+exports.deserialize = deserialize;
+exports.outputNode = outputNode;
+exports.resolve = resolve;
+exports.serialize = serialize;
+exports.sourceNode = sourceNode;

package/build/index.mjs

@@ -0,0 +1,122 @@
+import { ExecutionContextService, MethodContextService, lib } from 'backtest-kit';
+import { randomString } from 'functools-kit';
+
+var NodeType;
+(function (NodeType) {
+    NodeType["SourceNode"] = "source_node";
+    NodeType["OutputNode"] = "output_node";
+})(NodeType || (NodeType = {}));
+var NodeType$1 = NodeType;
+
+const sourceNode = (fetch) => ({
+    type: NodeType$1.SourceNode,
+    fetch,
+});
+const outputNode = (compute, ...nodes) => ({
+    type: NodeType$1.OutputNode,
+    nodes,
+    compute,
+});
+
+/**
+ * Рекурсивно разворачивает граф узлов в плоский массив.
+ * Порядок: сначала зависимости (children), затем родитель — топологический порядок.
+ * Дубликаты (один узел может быть зависимостью нескольких) исключаются по ссылке.
+ */
+const deepFlat = (arr = []) => {
+    const result = [];
+    const seen = new Set();
+    const process = (entries = []) => entries.forEach((entry) => {
+        if (seen.has(entry)) {
+            return;
+        }
+        seen.add(entry);
+        process(entry.nodes ?? []);
+        result.push(entry);
+    });
+    process(arr);
+    return result;
+};
+
+/**
+ * Рекурсивно вычисляет значение узла графа.
+ * Для SourceNode вызывает fetch().
+ * Для OutputNode сначала резолвит все дочерние nodes параллельно,
+ * затем передаёт их типизированные значения в compute().
+ */
+const resolve = async (node) => {
+    if (!ExecutionContextService.hasContext()) {
+        throw new Error("Execution context is required to resolve graph nodes. Please ensure that resolve() is called within a valid execution context.");
+    }
+    if (!MethodContextService.hasContext()) {
+        throw new Error("Method context is required to resolve graph nodes. Please ensure that resolve() is called within a valid method context.");
+    }
+    if (node.type === NodeType$1.SourceNode) {
+        const { symbol, when } = lib.executionContextService.context;
+        const { exchangeName } = lib.methodContextService.context;
+        return node.fetch(symbol, when, exchangeName);
+    }
+    const values = await Promise.all(node.nodes.map(resolve));
+    return node.compute(values);
+};
+
+/**
+ * Преобразует древовидный граф в плоский массив IFlatNode для хранения в БД.
+ * Каждому узлу присваивается уникальный id (если не задан),
+ * объектные ссылки nodes заменяются на массив nodeIds.
+ */
+const serialize = (roots) => {
+    const flat = deepFlat(roots);
+    // Первый проход: назначаем id каждому уникальному узлу
+    const idMap = new Map();
+    flat.forEach((node) => {
+        const id = randomString();
+        idMap.set(node, id);
+    });
+    // Второй проход: строим IFlatNode с nodeIds вместо nodes
+    return flat.map((node) => {
+        const flatNode = {
+            id: idMap.get(node),
+            type: node.type,
+            description: node.description,
+            fetch: node.fetch,
+            compute: node.compute,
+            nodeIds: node.nodes?.map((child) => idMap.get(child)),
+        };
+        return flatNode;
+    });
+};
+/**
+ * Восстанавливает древовидный граф из плоского массива IFlatNode.
+ * nodes каждого узла заполняется по nodeIds.
+ * Возвращает корневые узлы (те, на которые никто не ссылается).
+ */
+const deserialize = (flat) => {
+    // Первый проход: создаём INode-объекты, индексируем по id
+    const byId = new Map();
+    flat.forEach((flatNode) => {
+        const node = {
+            type: flatNode.type,
+            description: flatNode.description,
+            fetch: flatNode.fetch,
+            compute: flatNode.compute,
+        };
+        byId.set(flatNode.id, node);
+    });
+    // Второй проход: проставляем nodes[] по nodeIds
+    flat.forEach((flatNode) => {
+        if (flatNode.nodeIds?.length) {
+            const node = byId.get(flatNode.id);
+            node.nodes = flatNode.nodeIds
+                .map((id) => byId.get(id))
+                .filter((n) => n !== undefined);
+        }
+    });
+    // Корневые узлы — те, на которые не ссылается никто другой
+    const referenced = new Set(flat.flatMap((n) => n.nodeIds ?? []));
+    return [...byId.entries()]
+        .filter(([id]) => !referenced.has(id))
+        .map(([, node]) => node);
+};
+
+export { deepFlat, deserialize, outputNode, resolve, serialize, sourceNode };

package/package.json

@@ -0,0 +1,85 @@
+{
+  "name": "@backtest-kit/graph",
+  "version": "3.0.0",
+  "description": "Compose backtest-kit computations as a typed directed acyclic graph. Define source nodes that fetch market data and output nodes that compute derived values — then resolve the whole graph in topological order.",
+  "author": {
+    "name": "Petr Tripolsky",
+    "email": "tripolskypetr@gmail.com",
+    "url": "https://github.com/tripolskypetr"
+  },
+  "funding": {
+    "type": "individual",
+    "url": "http://paypal.me/tripolskypetr"
+  },
+  "license": "MIT",
+  "homepage": "https://backtest-kit.github.io/documents/example_02_first_backtest.html",
+  "keywords": [
+    "graph",
+    "dag",
+    "directed-acyclic-graph",
+    "computation-graph",
+    "dataflow",
+    "trading-bot",
+    "algorithmic-trading",
+    "backtest",
+    "backtesting",
+    "cryptocurrency",
+    "forex",
+    "strategy",
+    "typescript",
+    "type-safe",
+    "serialization"
+  ],
+  "files": [
+    "build",
+    "types.d.ts",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/tripolskypetr/backtest-kit",
+    "documentation": "https://github.com/tripolskypetr/backtest-kit/tree/master/docs"
+  },
+  "bugs": {
+    "url": "https://github.com/tripolskypetr/backtest-kit/issues"
+  },
+  "scripts": {
+    "build": "rollup -c"
+  },
+  "main": "build/index.cjs",
+  "module": "build/index.mjs",
+  "source": "src/index.ts",
+  "types": "./types.d.ts",
+  "exports": {
+    "require": "./build/index.cjs",
+    "types": "./types.d.ts",
+    "import": "./build/index.mjs",
+    "default": "./build/index.cjs"
+  },
+  "devDependencies": {
+    "@rollup/plugin-typescript": "11.1.6",
+    "@types/node": "22.9.0",
+    "glob": "11.0.1",
+    "rimraf": "6.0.1",
+    "rollup": "3.29.5",
+    "rollup-plugin-dts": "6.1.1",
+    "rollup-plugin-peer-deps-external": "2.2.4",
+    "ts-morph": "27.0.2",
+    "tslib": "2.7.0",
+    "typedoc": "0.27.9",
+    "worker-testbed": "1.0.12"
+  },
+  "peerDependencies": {
+    "backtest-kit": "^3.0.18",
+    "typescript": "^5.0.0"
+  },
+  "dependencies": {
+    "di-kit": "^1.0.18",
+    "di-scoped": "^1.0.21",
+    "functools-kit": "^1.0.95",
+    "get-moment-stamp": "^1.1.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/types.d.ts

@@ -0,0 +1,147 @@
+declare enum NodeType {
+    SourceNode = "source_node",
+    OutputNode = "output_node"
+}
+
+type ExchangeName = string;
+
+/**
+ * Любое возможное вычисленное значение узла графа.
+ */
+type Value = string | number | boolean | null;
+/**
+ * Плоский базовый интерфейс узла графа.
+ * Следует тому же паттерну, что IField в react-declarative:
+ * все свойства опциональны, type — обязателен.
+ */
+interface INode {
+    /**
+     * Тип узла для логического ветвления при исполнении графа
+     */
+    type: NodeType;
+    /**
+     * Человеко-читаемое описание узла, не влияет на исполнение графа.
+     */
+    description?: string;
+    /**
+     * Источник данных для SourceNode.
+     * Вызывается при вычислении узла без входящих зависимостей.
+     */
+    fetch?: (symbol: string, when: Date, exchangeName: ExchangeName) => Promise<Value> | Value;
+    /**
+     * Функция вычисления для OutputNode.
+     * Получает на вход массив значений, возвращённых fetch/compute
+     * из узлов массива nodes, в том же порядке.
+     */
+    compute?: (values: Value[]) => Promise<Value> | Value;
+    /**
+     * Входящие зависимости для OutputNode.
+     * Значения этих узлов передаются в compute.
+     */
+    nodes?: INode[];
+}
+
+/**
+ * Маппинг tuple нод в tuple их resolved-значений.
+ * Сохраняет позиционную структуру: [SourceNode<number>, SourceNode<string>] → [number, string].
+ */
+type InferValues<TNodes extends TypedNode[]> = {
+    [K in keyof TNodes]: TNodes[K] extends TypedNode ? InferNodeValue<TNodes[K]> : never;
+};
+/**
+ * Извлекает тип возвращаемого значения из TypedNode.
+ * Используется InferValues и run() для типобезопасного резолвинга.
+ */
+type InferNodeValue<T extends TypedNode> = T extends SourceNode<infer V> ? V : T extends OutputNode<any, infer V> ? V : never;
+/**
+ * Узел-источник данных. Не имеет входящих зависимостей.
+ * T — тип значения, возвращаемого fetch().
+ */
+type SourceNode<T extends Value = Value> = {
+    type: NodeType.SourceNode;
+    description?: string;
+    fetch: (symbol: string, when: Date, exchangeName: ExchangeName) => Promise<T> | T;
+};
+/**
+ * Узел вычисления. TNodes — tuple входящих зависимостей,
+ * TResult — тип возвращаемого значения compute().
+ * values в compute автоматически выводится из типов TNodes.
+ */
+type OutputNode<TNodes extends TypedNode[] = TypedNode[], TResult extends Value = Value> = {
+    type: NodeType.OutputNode;
+    description?: string;
+    nodes: TNodes;
+    compute: (values: InferValues<TNodes>) => Promise<TResult> | TResult;
+};
+/**
+ * Типизированный узел графа для прикладного программиста.
+ * Подставляется вместо INode для строгой проверки типов и IntelliSense.
+ */
+type TypedNode = SourceNode<Value> | OutputNode<TypedNode[], Value>;
+
+declare const sourceNode: <T extends Value>(fetch: (symbol: string, when: Date, exchangeName: ExchangeName) => Promise<T> | T) => SourceNode<T>;
+declare const outputNode: <TNodes extends TypedNode[], TResult extends Value = Value>(compute: (values: InferValues<TNodes>) => Promise<TResult> | TResult, ...nodes: TNodes) => OutputNode<TNodes, TResult>;
+
+/**
+ * Рекурсивно разворачивает граф узлов в плоский массив.
+ * Порядок: сначала зависимости (children), затем родитель — топологический порядок.
+ * Дубликаты (один узел может быть зависимостью нескольких) исключаются по ссылке.
+ */
+declare const deepFlat: (arr?: INode[]) => INode[];
+
+/**
+ * Рекурсивно вычисляет значение узла графа.
+ * Для SourceNode вызывает fetch().
+ * Для OutputNode сначала резолвит все дочерние nodes параллельно,
+ * затем передаёт их типизированные значения в compute().
+ */
+declare const resolve: <T extends TypedNode>(node: T) => Promise<InferNodeValue<T>>;
+
+/**
+ * Сериализованная (плоская) форма узла графа для хранения в БД.
+ * Объектные ссылки nodes заменены на массив идентификаторов nodeIds.
+ */
+interface IFlatNode {
+    /**
+     * Уникальный идентификатор узла.
+     */
+    id: string;
+    /**
+     * Тип узла.
+     */
+    type: NodeType;
+    /**
+     * Человеко-читаемое описание узла.
+     */
+    description?: string;
+    /**
+     * Идентификаторы входящих зависимостей.
+     * Порядок соответствует порядку значений в compute(values).
+     */
+    nodeIds?: string[];
+    /**
+     * Источник данных для SourceNode — не сериализуется в БД,
+     * восстанавливается на стороне приложения.
+     */
+    fetch?: (symbol: string, when: Date, exchangeName: ExchangeName) => Promise<Value> | Value;
+    /**
+     * Функция вычисления для OutputNode — не сериализуется в БД,
+     * восстанавливается на стороне приложения.
+     */
+    compute?: (values: Value[]) => Promise<Value> | Value;
+}
+
+/**
+ * Преобразует древовидный граф в плоский массив IFlatNode для хранения в БД.
+ * Каждому узлу присваивается уникальный id (если не задан),
+ * объектные ссылки nodes заменяются на массив nodeIds.
+ */
+declare const serialize: (roots: INode[]) => IFlatNode[];
+/**
+ * Восстанавливает древовидный граф из плоского массива IFlatNode.
+ * nodes каждого узла заполняется по nodeIds.
+ * Возвращает корневые узлы (те, на которые никто не ссылается).
+ */
+declare const deserialize: (flat: IFlatNode[]) => INode[];
+
+export { type IFlatNode, type INode, type TypedNode, type Value, deepFlat, deserialize, outputNode, resolve, serialize, sourceNode };