backtest-kit 1.6.2 → 1.6.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/build/index.cjs +78 -1
- package/build/index.mjs +77 -2
- package/package.json +1 -1
- package/types.d.ts +421 -375
package/build/index.cjs
CHANGED
|
@@ -2401,7 +2401,7 @@ const CALL_PING_CALLBACKS_FN = functoolsKit.trycatch(async (self, scheduled, tim
|
|
|
2401
2401
|
backtest$1.loggerService.warn(message, payload);
|
|
2402
2402
|
console.warn(message, payload);
|
|
2403
2403
|
errorEmitter.next(error);
|
|
2404
|
-
}
|
|
2404
|
+
},
|
|
2405
2405
|
});
|
|
2406
2406
|
const RETURN_SCHEDULED_SIGNAL_ACTIVE_FN = async (self, scheduled, currentPrice) => {
|
|
2407
2407
|
await CALL_PING_CALLBACKS_FN(self, scheduled, self.params.execution.context.when.getTime());
|
|
@@ -14182,6 +14182,81 @@ async function validate(args = {}) {
|
|
|
14182
14182
|
return await validateInternal(args);
|
|
14183
14183
|
}
|
|
14184
14184
|
|
|
14185
|
+
const STOP_METHOD_NAME = "strategy.stop";
|
|
14186
|
+
const CANCEL_METHOD_NAME = "strategy.cancel";
|
|
14187
|
+
/**
|
|
14188
|
+
* Stops the strategy from generating new signals.
|
|
14189
|
+
*
|
|
14190
|
+
* Sets internal flag to prevent strategy from opening new signals.
|
|
14191
|
+
* Current active signal (if any) will complete normally.
|
|
14192
|
+
* Backtest/Live mode will stop at the next safe point (idle state or after signal closes).
|
|
14193
|
+
*
|
|
14194
|
+
* Automatically detects backtest/live mode from execution context.
|
|
14195
|
+
*
|
|
14196
|
+
* @param symbol - Trading pair symbol
|
|
14197
|
+
* @param strategyName - Strategy name to stop
|
|
14198
|
+
* @returns Promise that resolves when stop flag is set
|
|
14199
|
+
*
|
|
14200
|
+
* @example
|
|
14201
|
+
* ```typescript
|
|
14202
|
+
* import { stop } from "backtest-kit";
|
|
14203
|
+
*
|
|
14204
|
+
* // Stop strategy after some condition
|
|
14205
|
+
* await stop("BTCUSDT", "my-strategy");
|
|
14206
|
+
* ```
|
|
14207
|
+
*/
|
|
14208
|
+
async function stop(symbol, strategyName) {
|
|
14209
|
+
backtest$1.loggerService.info(STOP_METHOD_NAME, {
|
|
14210
|
+
symbol,
|
|
14211
|
+
strategyName,
|
|
14212
|
+
});
|
|
14213
|
+
if (!ExecutionContextService.hasContext()) {
|
|
14214
|
+
throw new Error("stop requires an execution context");
|
|
14215
|
+
}
|
|
14216
|
+
if (!MethodContextService.hasContext()) {
|
|
14217
|
+
throw new Error("stop requires a method context");
|
|
14218
|
+
}
|
|
14219
|
+
const { backtest: isBacktest } = backtest$1.executionContextService.context;
|
|
14220
|
+
await backtest$1.strategyCoreService.stop(isBacktest, { symbol, strategyName });
|
|
14221
|
+
}
|
|
14222
|
+
/**
|
|
14223
|
+
* Cancels the scheduled signal without stopping the strategy.
|
|
14224
|
+
*
|
|
14225
|
+
* Clears the scheduled signal (waiting for priceOpen activation).
|
|
14226
|
+
* Does NOT affect active pending signals or strategy operation.
|
|
14227
|
+
* Does NOT set stop flag - strategy can continue generating new signals.
|
|
14228
|
+
*
|
|
14229
|
+
* Automatically detects backtest/live mode from execution context.
|
|
14230
|
+
*
|
|
14231
|
+
* @param symbol - Trading pair symbol
|
|
14232
|
+
* @param strategyName - Strategy name
|
|
14233
|
+
* @param cancelId - Optional cancellation ID for tracking user-initiated cancellations
|
|
14234
|
+
* @returns Promise that resolves when scheduled signal is cancelled
|
|
14235
|
+
*
|
|
14236
|
+
* @example
|
|
14237
|
+
* ```typescript
|
|
14238
|
+
* import { cancel } from "backtest-kit";
|
|
14239
|
+
*
|
|
14240
|
+
* // Cancel scheduled signal with custom ID
|
|
14241
|
+
* await cancel("BTCUSDT", "my-strategy", "manual-cancel-001");
|
|
14242
|
+
* ```
|
|
14243
|
+
*/
|
|
14244
|
+
async function cancel(symbol, strategyName, cancelId) {
|
|
14245
|
+
backtest$1.loggerService.info(CANCEL_METHOD_NAME, {
|
|
14246
|
+
symbol,
|
|
14247
|
+
strategyName,
|
|
14248
|
+
cancelId,
|
|
14249
|
+
});
|
|
14250
|
+
if (!ExecutionContextService.hasContext()) {
|
|
14251
|
+
throw new Error("cancel requires an execution context");
|
|
14252
|
+
}
|
|
14253
|
+
if (!MethodContextService.hasContext()) {
|
|
14254
|
+
throw new Error("cancel requires a method context");
|
|
14255
|
+
}
|
|
14256
|
+
const { backtest: isBacktest } = backtest$1.executionContextService.context;
|
|
14257
|
+
await backtest$1.strategyCoreService.cancel(isBacktest, { symbol, strategyName }, cancelId);
|
|
14258
|
+
}
|
|
14259
|
+
|
|
14185
14260
|
/**
|
|
14186
14261
|
* Sets custom logger implementation for the framework.
|
|
14187
14262
|
*
|
|
@@ -19621,6 +19696,7 @@ exports.addRisk = addRisk;
|
|
|
19621
19696
|
exports.addSizing = addSizing;
|
|
19622
19697
|
exports.addStrategy = addStrategy;
|
|
19623
19698
|
exports.addWalker = addWalker;
|
|
19699
|
+
exports.cancel = cancel;
|
|
19624
19700
|
exports.dumpSignal = dumpSignal;
|
|
19625
19701
|
exports.emitters = emitters;
|
|
19626
19702
|
exports.formatPrice = formatPrice;
|
|
@@ -19675,4 +19751,5 @@ exports.listenWalkerProgress = listenWalkerProgress;
|
|
|
19675
19751
|
exports.setColumns = setColumns;
|
|
19676
19752
|
exports.setConfig = setConfig;
|
|
19677
19753
|
exports.setLogger = setLogger;
|
|
19754
|
+
exports.stop = stop;
|
|
19678
19755
|
exports.validate = validate;
|
package/build/index.mjs
CHANGED
|
@@ -2399,7 +2399,7 @@ const CALL_PING_CALLBACKS_FN = trycatch(async (self, scheduled, timestamp) => {
|
|
|
2399
2399
|
backtest$1.loggerService.warn(message, payload);
|
|
2400
2400
|
console.warn(message, payload);
|
|
2401
2401
|
errorEmitter.next(error);
|
|
2402
|
-
}
|
|
2402
|
+
},
|
|
2403
2403
|
});
|
|
2404
2404
|
const RETURN_SCHEDULED_SIGNAL_ACTIVE_FN = async (self, scheduled, currentPrice) => {
|
|
2405
2405
|
await CALL_PING_CALLBACKS_FN(self, scheduled, self.params.execution.context.when.getTime());
|
|
@@ -14180,6 +14180,81 @@ async function validate(args = {}) {
|
|
|
14180
14180
|
return await validateInternal(args);
|
|
14181
14181
|
}
|
|
14182
14182
|
|
|
14183
|
+
const STOP_METHOD_NAME = "strategy.stop";
|
|
14184
|
+
const CANCEL_METHOD_NAME = "strategy.cancel";
|
|
14185
|
+
/**
|
|
14186
|
+
* Stops the strategy from generating new signals.
|
|
14187
|
+
*
|
|
14188
|
+
* Sets internal flag to prevent strategy from opening new signals.
|
|
14189
|
+
* Current active signal (if any) will complete normally.
|
|
14190
|
+
* Backtest/Live mode will stop at the next safe point (idle state or after signal closes).
|
|
14191
|
+
*
|
|
14192
|
+
* Automatically detects backtest/live mode from execution context.
|
|
14193
|
+
*
|
|
14194
|
+
* @param symbol - Trading pair symbol
|
|
14195
|
+
* @param strategyName - Strategy name to stop
|
|
14196
|
+
* @returns Promise that resolves when stop flag is set
|
|
14197
|
+
*
|
|
14198
|
+
* @example
|
|
14199
|
+
* ```typescript
|
|
14200
|
+
* import { stop } from "backtest-kit";
|
|
14201
|
+
*
|
|
14202
|
+
* // Stop strategy after some condition
|
|
14203
|
+
* await stop("BTCUSDT", "my-strategy");
|
|
14204
|
+
* ```
|
|
14205
|
+
*/
|
|
14206
|
+
async function stop(symbol, strategyName) {
|
|
14207
|
+
backtest$1.loggerService.info(STOP_METHOD_NAME, {
|
|
14208
|
+
symbol,
|
|
14209
|
+
strategyName,
|
|
14210
|
+
});
|
|
14211
|
+
if (!ExecutionContextService.hasContext()) {
|
|
14212
|
+
throw new Error("stop requires an execution context");
|
|
14213
|
+
}
|
|
14214
|
+
if (!MethodContextService.hasContext()) {
|
|
14215
|
+
throw new Error("stop requires a method context");
|
|
14216
|
+
}
|
|
14217
|
+
const { backtest: isBacktest } = backtest$1.executionContextService.context;
|
|
14218
|
+
await backtest$1.strategyCoreService.stop(isBacktest, { symbol, strategyName });
|
|
14219
|
+
}
|
|
14220
|
+
/**
|
|
14221
|
+
* Cancels the scheduled signal without stopping the strategy.
|
|
14222
|
+
*
|
|
14223
|
+
* Clears the scheduled signal (waiting for priceOpen activation).
|
|
14224
|
+
* Does NOT affect active pending signals or strategy operation.
|
|
14225
|
+
* Does NOT set stop flag - strategy can continue generating new signals.
|
|
14226
|
+
*
|
|
14227
|
+
* Automatically detects backtest/live mode from execution context.
|
|
14228
|
+
*
|
|
14229
|
+
* @param symbol - Trading pair symbol
|
|
14230
|
+
* @param strategyName - Strategy name
|
|
14231
|
+
* @param cancelId - Optional cancellation ID for tracking user-initiated cancellations
|
|
14232
|
+
* @returns Promise that resolves when scheduled signal is cancelled
|
|
14233
|
+
*
|
|
14234
|
+
* @example
|
|
14235
|
+
* ```typescript
|
|
14236
|
+
* import { cancel } from "backtest-kit";
|
|
14237
|
+
*
|
|
14238
|
+
* // Cancel scheduled signal with custom ID
|
|
14239
|
+
* await cancel("BTCUSDT", "my-strategy", "manual-cancel-001");
|
|
14240
|
+
* ```
|
|
14241
|
+
*/
|
|
14242
|
+
async function cancel(symbol, strategyName, cancelId) {
|
|
14243
|
+
backtest$1.loggerService.info(CANCEL_METHOD_NAME, {
|
|
14244
|
+
symbol,
|
|
14245
|
+
strategyName,
|
|
14246
|
+
cancelId,
|
|
14247
|
+
});
|
|
14248
|
+
if (!ExecutionContextService.hasContext()) {
|
|
14249
|
+
throw new Error("cancel requires an execution context");
|
|
14250
|
+
}
|
|
14251
|
+
if (!MethodContextService.hasContext()) {
|
|
14252
|
+
throw new Error("cancel requires a method context");
|
|
14253
|
+
}
|
|
14254
|
+
const { backtest: isBacktest } = backtest$1.executionContextService.context;
|
|
14255
|
+
await backtest$1.strategyCoreService.cancel(isBacktest, { symbol, strategyName }, cancelId);
|
|
14256
|
+
}
|
|
14257
|
+
|
|
14183
14258
|
/**
|
|
14184
14259
|
* Sets custom logger implementation for the framework.
|
|
14185
14260
|
*
|
|
@@ -19592,4 +19667,4 @@ class CacheUtils {
|
|
|
19592
19667
|
*/
|
|
19593
19668
|
const Cache = new CacheUtils();
|
|
19594
19669
|
|
|
19595
|
-
export { Backtest, Cache, Constant, Exchange, ExecutionContextService, Heat, Live, MethodContextService, Optimizer, Partial, Performance, PersistBase, PersistPartialAdapter, PersistRiskAdapter, PersistScheduleAdapter, PersistSignalAdapter, PositionSize, Risk, Schedule, Walker, addExchange, addFrame, addOptimizer, addRisk, addSizing, addStrategy, addWalker, dumpSignal, emitters, formatPrice, formatQuantity, getAveragePrice, getCandles, getColumns, getConfig, getDate, getDefaultColumns, getDefaultConfig, getMode, hasTradeContext, backtest as lib, listExchanges, listFrames, listOptimizers, listRisks, listSizings, listStrategies, listWalkers, listenBacktestProgress, listenDoneBacktest, listenDoneBacktestOnce, listenDoneLive, listenDoneLiveOnce, listenDoneWalker, listenDoneWalkerOnce, listenError, listenExit, listenOptimizerProgress, listenPartialLoss, listenPartialLossOnce, listenPartialProfit, listenPartialProfitOnce, listenPerformance, listenPing, listenPingOnce, listenRisk, listenRiskOnce, listenSignal, listenSignalBacktest, listenSignalBacktestOnce, listenSignalLive, listenSignalLiveOnce, listenSignalOnce, listenValidation, listenWalker, listenWalkerComplete, listenWalkerOnce, listenWalkerProgress, setColumns, setConfig, setLogger, validate };
|
|
19670
|
+
export { Backtest, Cache, Constant, Exchange, ExecutionContextService, Heat, Live, MethodContextService, Optimizer, Partial, Performance, PersistBase, PersistPartialAdapter, PersistRiskAdapter, PersistScheduleAdapter, PersistSignalAdapter, PositionSize, Risk, Schedule, Walker, addExchange, addFrame, addOptimizer, addRisk, addSizing, addStrategy, addWalker, cancel, dumpSignal, emitters, formatPrice, formatQuantity, getAveragePrice, getCandles, getColumns, getConfig, getDate, getDefaultColumns, getDefaultConfig, getMode, hasTradeContext, backtest as lib, listExchanges, listFrames, listOptimizers, listRisks, listSizings, listStrategies, listWalkers, listenBacktestProgress, listenDoneBacktest, listenDoneBacktestOnce, listenDoneLive, listenDoneLiveOnce, listenDoneWalker, listenDoneWalkerOnce, listenError, listenExit, listenOptimizerProgress, listenPartialLoss, listenPartialLossOnce, listenPartialProfit, listenPartialProfitOnce, listenPerformance, listenPing, listenPingOnce, listenRisk, listenRiskOnce, listenSignal, listenSignalBacktest, listenSignalBacktestOnce, listenSignalLive, listenSignalLiveOnce, listenSignalOnce, listenValidation, listenWalker, listenWalkerComplete, listenWalkerOnce, listenWalkerProgress, setColumns, setConfig, setLogger, stop, validate };
|
package/package.json
CHANGED
package/types.d.ts
CHANGED
|
@@ -110,153 +110,51 @@ interface ValidateArgs<T = Enum> {
|
|
|
110
110
|
*/
|
|
111
111
|
declare function validate(args?: Partial<Args>): Promise<void>;
|
|
112
112
|
|
|
113
|
-
declare const GLOBAL_CONFIG: {
|
|
114
|
-
/**
|
|
115
|
-
* Time to wait for scheduled signal to activate (in minutes)
|
|
116
|
-
* If signal does not activate within this time, it will be cancelled.
|
|
117
|
-
*/
|
|
118
|
-
CC_SCHEDULE_AWAIT_MINUTES: number;
|
|
119
|
-
/**
|
|
120
|
-
* Number of candles to use for average price calculation (VWAP)
|
|
121
|
-
* Default: 5 candles (last 5 minutes when using 1m interval)
|
|
122
|
-
*/
|
|
123
|
-
CC_AVG_PRICE_CANDLES_COUNT: number;
|
|
124
|
-
/**
|
|
125
|
-
* Slippage percentage applied to entry and exit prices.
|
|
126
|
-
* Simulates market impact and order book depth.
|
|
127
|
-
* Applied twice (entry and exit) for realistic execution simulation.
|
|
128
|
-
* Default: 0.1% per transaction
|
|
129
|
-
*/
|
|
130
|
-
CC_PERCENT_SLIPPAGE: number;
|
|
131
|
-
/**
|
|
132
|
-
* Fee percentage charged per transaction.
|
|
133
|
-
* Applied twice (entry and exit) for total fee calculation.
|
|
134
|
-
* Default: 0.1% per transaction (total 0.2%)
|
|
135
|
-
*/
|
|
136
|
-
CC_PERCENT_FEE: number;
|
|
137
|
-
/**
|
|
138
|
-
* Minimum TakeProfit distance from priceOpen (percentage)
|
|
139
|
-
* Must be greater than (slippage + fees) to ensure profitable trades
|
|
140
|
-
*
|
|
141
|
-
* Calculation:
|
|
142
|
-
* - Slippage effect: ~0.2% (0.1% × 2 transactions)
|
|
143
|
-
* - Fees: 0.2% (0.1% × 2 transactions)
|
|
144
|
-
* - Minimum profit buffer: 0.1%
|
|
145
|
-
* - Total: 0.5%
|
|
146
|
-
*
|
|
147
|
-
* Default: 0.5% (covers all costs + minimum profit margin)
|
|
148
|
-
*/
|
|
149
|
-
CC_MIN_TAKEPROFIT_DISTANCE_PERCENT: number;
|
|
150
|
-
/**
|
|
151
|
-
* Minimum StopLoss distance from priceOpen (percentage)
|
|
152
|
-
* Prevents signals from being immediately stopped out due to price volatility
|
|
153
|
-
* Default: 0.5% (buffer to avoid instant stop loss on normal market fluctuations)
|
|
154
|
-
*/
|
|
155
|
-
CC_MIN_STOPLOSS_DISTANCE_PERCENT: number;
|
|
156
|
-
/**
|
|
157
|
-
* Maximum StopLoss distance from priceOpen (percentage)
|
|
158
|
-
* Prevents catastrophic losses from extreme StopLoss values
|
|
159
|
-
* Default: 20% (one signal cannot lose more than 20% of position)
|
|
160
|
-
*/
|
|
161
|
-
CC_MAX_STOPLOSS_DISTANCE_PERCENT: number;
|
|
162
|
-
/**
|
|
163
|
-
* Maximum signal lifetime in minutes
|
|
164
|
-
* Prevents eternal signals that block risk limits for weeks/months
|
|
165
|
-
* Default: 1440 minutes (1 day)
|
|
166
|
-
*/
|
|
167
|
-
CC_MAX_SIGNAL_LIFETIME_MINUTES: number;
|
|
168
|
-
/**
|
|
169
|
-
* Maximum time allowed for signal generation (in seconds).
|
|
170
|
-
* Prevents long-running or stuck signal generation routines from blocking
|
|
171
|
-
* execution or consuming resources indefinitely. If generation exceeds this
|
|
172
|
-
* threshold the attempt should be aborted, logged and optionally retried.
|
|
173
|
-
*
|
|
174
|
-
* Default: 180 seconds (3 minutes)
|
|
175
|
-
*/
|
|
176
|
-
CC_MAX_SIGNAL_GENERATION_SECONDS: number;
|
|
177
|
-
/**
|
|
178
|
-
* Number of retries for getCandles function
|
|
179
|
-
* Default: 3 retries
|
|
180
|
-
*/
|
|
181
|
-
CC_GET_CANDLES_RETRY_COUNT: number;
|
|
182
|
-
/**
|
|
183
|
-
* Delay between retries for getCandles function (in milliseconds)
|
|
184
|
-
* Default: 5000 ms (5 seconds)
|
|
185
|
-
*/
|
|
186
|
-
CC_GET_CANDLES_RETRY_DELAY_MS: number;
|
|
187
|
-
/**
|
|
188
|
-
* Maximum allowed deviation factor for price anomaly detection.
|
|
189
|
-
* Price should not be more than this factor lower than reference price.
|
|
190
|
-
*
|
|
191
|
-
* Reasoning:
|
|
192
|
-
* - Incomplete candles from Binance API typically have prices near 0 (e.g., $0.01-1)
|
|
193
|
-
* - Normal BTC price ranges: $20,000-100,000
|
|
194
|
-
* - Factor 1000 catches prices below $20-100 when median is $20,000-100,000
|
|
195
|
-
* - Factor 100 would be too permissive (allows $200 when median is $20,000)
|
|
196
|
-
* - Factor 10000 might be too strict for low-cap altcoins
|
|
197
|
-
*
|
|
198
|
-
* Example: BTC at $50,000 median → threshold $50 (catches $0.01-1 anomalies)
|
|
199
|
-
*/
|
|
200
|
-
CC_GET_CANDLES_PRICE_ANOMALY_THRESHOLD_FACTOR: number;
|
|
201
|
-
/**
|
|
202
|
-
* Minimum number of candles required for reliable median calculation.
|
|
203
|
-
* Below this threshold, use simple average instead of median.
|
|
204
|
-
*
|
|
205
|
-
* Reasoning:
|
|
206
|
-
* - Each candle provides 4 price points (OHLC)
|
|
207
|
-
* - 5 candles = 20 price points, sufficient for robust median calculation
|
|
208
|
-
* - Below 5 candles, single anomaly can heavily skew median
|
|
209
|
-
* - Statistical rule of thumb: minimum 7-10 data points for median stability
|
|
210
|
-
* - Average is more stable than median for small datasets (n < 20)
|
|
211
|
-
*
|
|
212
|
-
* Example: 3 candles = 12 points (use average), 5 candles = 20 points (use median)
|
|
213
|
-
*/
|
|
214
|
-
CC_GET_CANDLES_MIN_CANDLES_FOR_MEDIAN: number;
|
|
215
|
-
/**
|
|
216
|
-
* Controls visibility of signal notes in markdown report tables.
|
|
217
|
-
* When enabled, the "Note" column will be displayed in all markdown reports
|
|
218
|
-
* (backtest, live, schedule, risk, etc.)
|
|
219
|
-
*
|
|
220
|
-
* Default: false (notes are hidden to reduce table width and improve readability)
|
|
221
|
-
*/
|
|
222
|
-
CC_REPORT_SHOW_SIGNAL_NOTE: boolean;
|
|
223
|
-
};
|
|
224
113
|
/**
|
|
225
|
-
*
|
|
114
|
+
* Execution context containing runtime parameters for strategy/exchange operations.
|
|
115
|
+
*
|
|
116
|
+
* Propagated through ExecutionContextService to provide implicit context
|
|
117
|
+
* for getCandles(), tick(), backtest() and other operations.
|
|
226
118
|
*/
|
|
227
|
-
|
|
228
|
-
|
|
119
|
+
interface IExecutionContext {
|
|
120
|
+
/** Trading pair symbol (e.g., "BTCUSDT") */
|
|
121
|
+
symbol: string;
|
|
122
|
+
/** Current timestamp for operation */
|
|
123
|
+
when: Date;
|
|
124
|
+
/** Whether running in backtest mode (true) or live mode (false) */
|
|
125
|
+
backtest: boolean;
|
|
126
|
+
}
|
|
229
127
|
/**
|
|
230
|
-
*
|
|
128
|
+
* Scoped service for execution context propagation.
|
|
231
129
|
*
|
|
232
|
-
*
|
|
233
|
-
*
|
|
234
|
-
*
|
|
130
|
+
* Uses di-scoped for implicit context passing without explicit parameters.
|
|
131
|
+
* Context includes symbol, when (timestamp), and backtest flag.
|
|
132
|
+
*
|
|
133
|
+
* Used by GlobalServices to inject context into operations.
|
|
134
|
+
*
|
|
135
|
+
* @example
|
|
136
|
+
* ```typescript
|
|
137
|
+
* ExecutionContextService.runInContext(
|
|
138
|
+
* async () => {
|
|
139
|
+
* // Inside this callback, context is automatically available
|
|
140
|
+
* return await someOperation();
|
|
141
|
+
* },
|
|
142
|
+
* { symbol: "BTCUSDT", when: new Date(), backtest: true }
|
|
143
|
+
* );
|
|
144
|
+
* ```
|
|
235
145
|
*/
|
|
236
|
-
declare const
|
|
237
|
-
|
|
238
|
-
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
|
|
243
|
-
/** Columns for partial-results / incremental reports */
|
|
244
|
-
partial_columns: ColumnModel<PartialEvent>[];
|
|
245
|
-
/** Columns for performance summary reports */
|
|
246
|
-
performance_columns: ColumnModel<MetricStats>[];
|
|
247
|
-
/** Columns for risk-related reports */
|
|
248
|
-
risk_columns: ColumnModel<RiskEvent>[];
|
|
249
|
-
/** Columns for scheduled report output */
|
|
250
|
-
schedule_columns: ColumnModel<ScheduledEvent>[];
|
|
251
|
-
/** Walker: PnL summary columns */
|
|
252
|
-
walker_pnl_columns: ColumnModel<SignalData$1>[];
|
|
253
|
-
/** Walker: strategy-level summary columns */
|
|
254
|
-
walker_strategy_columns: ColumnModel<IStrategyResult>[];
|
|
255
|
-
};
|
|
146
|
+
declare const ExecutionContextService: (new () => {
|
|
147
|
+
readonly context: IExecutionContext;
|
|
148
|
+
}) & Omit<{
|
|
149
|
+
new (context: IExecutionContext): {
|
|
150
|
+
readonly context: IExecutionContext;
|
|
151
|
+
};
|
|
152
|
+
}, "prototype"> & di_scoped.IScopedClassRun<[context: IExecutionContext]>;
|
|
256
153
|
/**
|
|
257
|
-
* Type for
|
|
154
|
+
* Type helper for ExecutionContextService instance.
|
|
155
|
+
* Used for dependency injection type annotations.
|
|
258
156
|
*/
|
|
259
|
-
type
|
|
157
|
+
type TExecutionContextService = InstanceType<typeof ExecutionContextService>;
|
|
260
158
|
|
|
261
159
|
/**
|
|
262
160
|
* Interface representing a logging mechanism for the swarm system.
|
|
@@ -287,244 +185,30 @@ interface ILogger {
|
|
|
287
185
|
}
|
|
288
186
|
|
|
289
187
|
/**
|
|
290
|
-
*
|
|
291
|
-
*
|
|
292
|
-
* All log messages from internal services will be forwarded to the provided logger
|
|
293
|
-
* with automatic context injection (strategyName, exchangeName, symbol, etc.).
|
|
294
|
-
*
|
|
295
|
-
* @param logger - Custom logger implementing ILogger interface
|
|
296
|
-
*
|
|
297
|
-
* @example
|
|
298
|
-
* ```typescript
|
|
299
|
-
* setLogger({
|
|
300
|
-
* log: (topic, ...args) => console.log(topic, args),
|
|
301
|
-
* debug: (topic, ...args) => console.debug(topic, args),
|
|
302
|
-
* info: (topic, ...args) => console.info(topic, args),
|
|
303
|
-
* });
|
|
304
|
-
* ```
|
|
188
|
+
* Candle time interval for fetching historical data.
|
|
305
189
|
*/
|
|
306
|
-
|
|
190
|
+
type CandleInterval = "1m" | "3m" | "5m" | "15m" | "30m" | "1h" | "2h" | "4h" | "6h" | "8h";
|
|
307
191
|
/**
|
|
308
|
-
*
|
|
309
|
-
*
|
|
310
|
-
* @param _unsafe - Skip config validations - required for testbed
|
|
311
|
-
*
|
|
312
|
-
* @example
|
|
313
|
-
* ```typescript
|
|
314
|
-
* setConfig({
|
|
315
|
-
* CC_SCHEDULE_AWAIT_MINUTES: 90,
|
|
316
|
-
* });
|
|
317
|
-
* ```
|
|
192
|
+
* Single OHLCV candle data point.
|
|
193
|
+
* Used for VWAP calculation and backtesting.
|
|
318
194
|
*/
|
|
319
|
-
|
|
195
|
+
interface ICandleData {
|
|
196
|
+
/** Unix timestamp in milliseconds when candle opened */
|
|
197
|
+
timestamp: number;
|
|
198
|
+
/** Opening price at candle start */
|
|
199
|
+
open: number;
|
|
200
|
+
/** Highest price during candle period */
|
|
201
|
+
high: number;
|
|
202
|
+
/** Lowest price during candle period */
|
|
203
|
+
low: number;
|
|
204
|
+
/** Closing price at candle end */
|
|
205
|
+
close: number;
|
|
206
|
+
/** Trading volume during candle period */
|
|
207
|
+
volume: number;
|
|
208
|
+
}
|
|
320
209
|
/**
|
|
321
|
-
*
|
|
322
|
-
*
|
|
323
|
-
* Returns a shallow copy of the current GLOBAL_CONFIG to prevent accidental mutations.
|
|
324
|
-
* Use this to inspect the current configuration state without modifying it.
|
|
325
|
-
*
|
|
326
|
-
* @returns {GlobalConfig} A copy of the current global configuration object
|
|
327
|
-
*
|
|
328
|
-
* @example
|
|
329
|
-
* ```typescript
|
|
330
|
-
* const currentConfig = getConfig();
|
|
331
|
-
* console.log(currentConfig.CC_SCHEDULE_AWAIT_MINUTES);
|
|
332
|
-
* ```
|
|
333
|
-
*/
|
|
334
|
-
declare function getConfig(): {
|
|
335
|
-
CC_SCHEDULE_AWAIT_MINUTES: number;
|
|
336
|
-
CC_AVG_PRICE_CANDLES_COUNT: number;
|
|
337
|
-
CC_PERCENT_SLIPPAGE: number;
|
|
338
|
-
CC_PERCENT_FEE: number;
|
|
339
|
-
CC_MIN_TAKEPROFIT_DISTANCE_PERCENT: number;
|
|
340
|
-
CC_MIN_STOPLOSS_DISTANCE_PERCENT: number;
|
|
341
|
-
CC_MAX_STOPLOSS_DISTANCE_PERCENT: number;
|
|
342
|
-
CC_MAX_SIGNAL_LIFETIME_MINUTES: number;
|
|
343
|
-
CC_MAX_SIGNAL_GENERATION_SECONDS: number;
|
|
344
|
-
CC_GET_CANDLES_RETRY_COUNT: number;
|
|
345
|
-
CC_GET_CANDLES_RETRY_DELAY_MS: number;
|
|
346
|
-
CC_GET_CANDLES_PRICE_ANOMALY_THRESHOLD_FACTOR: number;
|
|
347
|
-
CC_GET_CANDLES_MIN_CANDLES_FOR_MEDIAN: number;
|
|
348
|
-
CC_REPORT_SHOW_SIGNAL_NOTE: boolean;
|
|
349
|
-
};
|
|
350
|
-
/**
|
|
351
|
-
* Retrieves the default configuration object for the framework.
|
|
352
|
-
*
|
|
353
|
-
* Returns a reference to the default configuration with all preset values.
|
|
354
|
-
* Use this to see what configuration options are available and their default values.
|
|
355
|
-
*
|
|
356
|
-
* @returns {GlobalConfig} The default configuration object
|
|
357
|
-
*
|
|
358
|
-
* @example
|
|
359
|
-
* ```typescript
|
|
360
|
-
* const defaultConfig = getDefaultConfig();
|
|
361
|
-
* console.log(defaultConfig.CC_SCHEDULE_AWAIT_MINUTES);
|
|
362
|
-
* ```
|
|
363
|
-
*/
|
|
364
|
-
declare function getDefaultConfig(): Readonly<{
|
|
365
|
-
CC_SCHEDULE_AWAIT_MINUTES: number;
|
|
366
|
-
CC_AVG_PRICE_CANDLES_COUNT: number;
|
|
367
|
-
CC_PERCENT_SLIPPAGE: number;
|
|
368
|
-
CC_PERCENT_FEE: number;
|
|
369
|
-
CC_MIN_TAKEPROFIT_DISTANCE_PERCENT: number;
|
|
370
|
-
CC_MIN_STOPLOSS_DISTANCE_PERCENT: number;
|
|
371
|
-
CC_MAX_STOPLOSS_DISTANCE_PERCENT: number;
|
|
372
|
-
CC_MAX_SIGNAL_LIFETIME_MINUTES: number;
|
|
373
|
-
CC_MAX_SIGNAL_GENERATION_SECONDS: number;
|
|
374
|
-
CC_GET_CANDLES_RETRY_COUNT: number;
|
|
375
|
-
CC_GET_CANDLES_RETRY_DELAY_MS: number;
|
|
376
|
-
CC_GET_CANDLES_PRICE_ANOMALY_THRESHOLD_FACTOR: number;
|
|
377
|
-
CC_GET_CANDLES_MIN_CANDLES_FOR_MEDIAN: number;
|
|
378
|
-
CC_REPORT_SHOW_SIGNAL_NOTE: boolean;
|
|
379
|
-
}>;
|
|
380
|
-
/**
|
|
381
|
-
* Sets custom column configurations for markdown report generation.
|
|
382
|
-
*
|
|
383
|
-
* Allows overriding default column definitions for any report type.
|
|
384
|
-
* All columns are validated before assignment to ensure structural correctness.
|
|
385
|
-
*
|
|
386
|
-
* @param columns - Partial column configuration object to override default column settings
|
|
387
|
-
* @param _unsafe - Skip column validations - required for testbed
|
|
388
|
-
*
|
|
389
|
-
* @example
|
|
390
|
-
* ```typescript
|
|
391
|
-
* setColumns({
|
|
392
|
-
* backtest_columns: [
|
|
393
|
-
* {
|
|
394
|
-
* key: "customId",
|
|
395
|
-
* label: "Custom ID",
|
|
396
|
-
* format: (data) => data.signal.id,
|
|
397
|
-
* isVisible: () => true
|
|
398
|
-
* }
|
|
399
|
-
* ],
|
|
400
|
-
* });
|
|
401
|
-
* ```
|
|
402
|
-
*
|
|
403
|
-
* @throws {Error} If column configuration is invalid
|
|
404
|
-
*/
|
|
405
|
-
declare function setColumns(columns: Partial<ColumnConfig>, _unsafe?: boolean): void;
|
|
406
|
-
/**
|
|
407
|
-
* Retrieves a copy of the current column configuration for markdown report generation.
|
|
408
|
-
*
|
|
409
|
-
* Returns a shallow copy of the current COLUMN_CONFIG to prevent accidental mutations.
|
|
410
|
-
* Use this to inspect the current column definitions without modifying them.
|
|
411
|
-
*
|
|
412
|
-
* @returns {ColumnConfig} A copy of the current column configuration object
|
|
413
|
-
*
|
|
414
|
-
* @example
|
|
415
|
-
* ```typescript
|
|
416
|
-
* const currentColumns = getColumns();
|
|
417
|
-
* console.log(currentColumns.backtest_columns.length);
|
|
418
|
-
* ```
|
|
419
|
-
*/
|
|
420
|
-
declare function getColumns(): {
|
|
421
|
-
backtest_columns: ColumnModel<IStrategyTickResultClosed>[];
|
|
422
|
-
heat_columns: ColumnModel<IHeatmapRow>[];
|
|
423
|
-
live_columns: ColumnModel<TickEvent>[];
|
|
424
|
-
partial_columns: ColumnModel<PartialEvent>[];
|
|
425
|
-
performance_columns: ColumnModel<MetricStats>[];
|
|
426
|
-
risk_columns: ColumnModel<RiskEvent>[];
|
|
427
|
-
schedule_columns: ColumnModel<ScheduledEvent>[];
|
|
428
|
-
walker_pnl_columns: ColumnModel<SignalData$1>[];
|
|
429
|
-
walker_strategy_columns: ColumnModel<IStrategyResult>[];
|
|
430
|
-
};
|
|
431
|
-
/**
|
|
432
|
-
* Retrieves the default column configuration object for markdown report generation.
|
|
433
|
-
*
|
|
434
|
-
* Returns a reference to the default column definitions with all preset values.
|
|
435
|
-
* Use this to see what column options are available and their default definitions.
|
|
436
|
-
*
|
|
437
|
-
* @returns {ColumnConfig} The default column configuration object
|
|
438
|
-
*
|
|
439
|
-
* @example
|
|
440
|
-
* ```typescript
|
|
441
|
-
* const defaultColumns = getDefaultColumns();
|
|
442
|
-
* console.log(defaultColumns.backtest_columns);
|
|
443
|
-
* ```
|
|
444
|
-
*/
|
|
445
|
-
declare function getDefaultColumns(): Readonly<{
|
|
446
|
-
backtest_columns: ColumnModel<IStrategyTickResultClosed>[];
|
|
447
|
-
heat_columns: ColumnModel<IHeatmapRow>[];
|
|
448
|
-
live_columns: ColumnModel<TickEvent>[];
|
|
449
|
-
partial_columns: ColumnModel<PartialEvent>[];
|
|
450
|
-
performance_columns: ColumnModel<MetricStats>[];
|
|
451
|
-
risk_columns: ColumnModel<RiskEvent>[];
|
|
452
|
-
schedule_columns: ColumnModel<ScheduledEvent>[];
|
|
453
|
-
walker_pnl_columns: ColumnModel<SignalData$1>[];
|
|
454
|
-
walker_strategy_columns: ColumnModel<IStrategyResult>[];
|
|
455
|
-
}>;
|
|
456
|
-
|
|
457
|
-
/**
|
|
458
|
-
* Execution context containing runtime parameters for strategy/exchange operations.
|
|
459
|
-
*
|
|
460
|
-
* Propagated through ExecutionContextService to provide implicit context
|
|
461
|
-
* for getCandles(), tick(), backtest() and other operations.
|
|
462
|
-
*/
|
|
463
|
-
interface IExecutionContext {
|
|
464
|
-
/** Trading pair symbol (e.g., "BTCUSDT") */
|
|
465
|
-
symbol: string;
|
|
466
|
-
/** Current timestamp for operation */
|
|
467
|
-
when: Date;
|
|
468
|
-
/** Whether running in backtest mode (true) or live mode (false) */
|
|
469
|
-
backtest: boolean;
|
|
470
|
-
}
|
|
471
|
-
/**
|
|
472
|
-
* Scoped service for execution context propagation.
|
|
473
|
-
*
|
|
474
|
-
* Uses di-scoped for implicit context passing without explicit parameters.
|
|
475
|
-
* Context includes symbol, when (timestamp), and backtest flag.
|
|
476
|
-
*
|
|
477
|
-
* Used by GlobalServices to inject context into operations.
|
|
478
|
-
*
|
|
479
|
-
* @example
|
|
480
|
-
* ```typescript
|
|
481
|
-
* ExecutionContextService.runInContext(
|
|
482
|
-
* async () => {
|
|
483
|
-
* // Inside this callback, context is automatically available
|
|
484
|
-
* return await someOperation();
|
|
485
|
-
* },
|
|
486
|
-
* { symbol: "BTCUSDT", when: new Date(), backtest: true }
|
|
487
|
-
* );
|
|
488
|
-
* ```
|
|
489
|
-
*/
|
|
490
|
-
declare const ExecutionContextService: (new () => {
|
|
491
|
-
readonly context: IExecutionContext;
|
|
492
|
-
}) & Omit<{
|
|
493
|
-
new (context: IExecutionContext): {
|
|
494
|
-
readonly context: IExecutionContext;
|
|
495
|
-
};
|
|
496
|
-
}, "prototype"> & di_scoped.IScopedClassRun<[context: IExecutionContext]>;
|
|
497
|
-
/**
|
|
498
|
-
* Type helper for ExecutionContextService instance.
|
|
499
|
-
* Used for dependency injection type annotations.
|
|
500
|
-
*/
|
|
501
|
-
type TExecutionContextService = InstanceType<typeof ExecutionContextService>;
|
|
502
|
-
|
|
503
|
-
/**
|
|
504
|
-
* Candle time interval for fetching historical data.
|
|
505
|
-
*/
|
|
506
|
-
type CandleInterval = "1m" | "3m" | "5m" | "15m" | "30m" | "1h" | "2h" | "4h" | "6h" | "8h";
|
|
507
|
-
/**
|
|
508
|
-
* Single OHLCV candle data point.
|
|
509
|
-
* Used for VWAP calculation and backtesting.
|
|
510
|
-
*/
|
|
511
|
-
interface ICandleData {
|
|
512
|
-
/** Unix timestamp in milliseconds when candle opened */
|
|
513
|
-
timestamp: number;
|
|
514
|
-
/** Opening price at candle start */
|
|
515
|
-
open: number;
|
|
516
|
-
/** Highest price during candle period */
|
|
517
|
-
high: number;
|
|
518
|
-
/** Lowest price during candle period */
|
|
519
|
-
low: number;
|
|
520
|
-
/** Closing price at candle end */
|
|
521
|
-
close: number;
|
|
522
|
-
/** Trading volume during candle period */
|
|
523
|
-
volume: number;
|
|
524
|
-
}
|
|
525
|
-
/**
|
|
526
|
-
* Exchange parameters passed to ClientExchange constructor.
|
|
527
|
-
* Combines schema with runtime dependencies.
|
|
210
|
+
* Exchange parameters passed to ClientExchange constructor.
|
|
211
|
+
* Combines schema with runtime dependencies.
|
|
528
212
|
*/
|
|
529
213
|
interface IExchangeParams extends IExchangeSchema {
|
|
530
214
|
/** Logger service for debug output */
|
|
@@ -1369,6 +1053,368 @@ type IStrategyBacktestResult = IStrategyTickResultClosed | IStrategyTickResultCa
|
|
|
1369
1053
|
*/
|
|
1370
1054
|
type StrategyName = string;
|
|
1371
1055
|
|
|
1056
|
+
/**
|
|
1057
|
+
* Stops the strategy from generating new signals.
|
|
1058
|
+
*
|
|
1059
|
+
* Sets internal flag to prevent strategy from opening new signals.
|
|
1060
|
+
* Current active signal (if any) will complete normally.
|
|
1061
|
+
* Backtest/Live mode will stop at the next safe point (idle state or after signal closes).
|
|
1062
|
+
*
|
|
1063
|
+
* Automatically detects backtest/live mode from execution context.
|
|
1064
|
+
*
|
|
1065
|
+
* @param symbol - Trading pair symbol
|
|
1066
|
+
* @param strategyName - Strategy name to stop
|
|
1067
|
+
* @returns Promise that resolves when stop flag is set
|
|
1068
|
+
*
|
|
1069
|
+
* @example
|
|
1070
|
+
* ```typescript
|
|
1071
|
+
* import { stop } from "backtest-kit";
|
|
1072
|
+
*
|
|
1073
|
+
* // Stop strategy after some condition
|
|
1074
|
+
* await stop("BTCUSDT", "my-strategy");
|
|
1075
|
+
* ```
|
|
1076
|
+
*/
|
|
1077
|
+
declare function stop(symbol: string, strategyName: StrategyName): Promise<void>;
|
|
1078
|
+
/**
|
|
1079
|
+
* Cancels the scheduled signal without stopping the strategy.
|
|
1080
|
+
*
|
|
1081
|
+
* Clears the scheduled signal (waiting for priceOpen activation).
|
|
1082
|
+
* Does NOT affect active pending signals or strategy operation.
|
|
1083
|
+
* Does NOT set stop flag - strategy can continue generating new signals.
|
|
1084
|
+
*
|
|
1085
|
+
* Automatically detects backtest/live mode from execution context.
|
|
1086
|
+
*
|
|
1087
|
+
* @param symbol - Trading pair symbol
|
|
1088
|
+
* @param strategyName - Strategy name
|
|
1089
|
+
* @param cancelId - Optional cancellation ID for tracking user-initiated cancellations
|
|
1090
|
+
* @returns Promise that resolves when scheduled signal is cancelled
|
|
1091
|
+
*
|
|
1092
|
+
* @example
|
|
1093
|
+
* ```typescript
|
|
1094
|
+
* import { cancel } from "backtest-kit";
|
|
1095
|
+
*
|
|
1096
|
+
* // Cancel scheduled signal with custom ID
|
|
1097
|
+
* await cancel("BTCUSDT", "my-strategy", "manual-cancel-001");
|
|
1098
|
+
* ```
|
|
1099
|
+
*/
|
|
1100
|
+
declare function cancel(symbol: string, strategyName: StrategyName, cancelId?: string): Promise<void>;
|
|
1101
|
+
|
|
1102
|
+
declare const GLOBAL_CONFIG: {
|
|
1103
|
+
/**
|
|
1104
|
+
* Time to wait for scheduled signal to activate (in minutes)
|
|
1105
|
+
* If signal does not activate within this time, it will be cancelled.
|
|
1106
|
+
*/
|
|
1107
|
+
CC_SCHEDULE_AWAIT_MINUTES: number;
|
|
1108
|
+
/**
|
|
1109
|
+
* Number of candles to use for average price calculation (VWAP)
|
|
1110
|
+
* Default: 5 candles (last 5 minutes when using 1m interval)
|
|
1111
|
+
*/
|
|
1112
|
+
CC_AVG_PRICE_CANDLES_COUNT: number;
|
|
1113
|
+
/**
|
|
1114
|
+
* Slippage percentage applied to entry and exit prices.
|
|
1115
|
+
* Simulates market impact and order book depth.
|
|
1116
|
+
* Applied twice (entry and exit) for realistic execution simulation.
|
|
1117
|
+
* Default: 0.1% per transaction
|
|
1118
|
+
*/
|
|
1119
|
+
CC_PERCENT_SLIPPAGE: number;
|
|
1120
|
+
/**
|
|
1121
|
+
* Fee percentage charged per transaction.
|
|
1122
|
+
* Applied twice (entry and exit) for total fee calculation.
|
|
1123
|
+
* Default: 0.1% per transaction (total 0.2%)
|
|
1124
|
+
*/
|
|
1125
|
+
CC_PERCENT_FEE: number;
|
|
1126
|
+
/**
|
|
1127
|
+
* Minimum TakeProfit distance from priceOpen (percentage)
|
|
1128
|
+
* Must be greater than (slippage + fees) to ensure profitable trades
|
|
1129
|
+
*
|
|
1130
|
+
* Calculation:
|
|
1131
|
+
* - Slippage effect: ~0.2% (0.1% × 2 transactions)
|
|
1132
|
+
* - Fees: 0.2% (0.1% × 2 transactions)
|
|
1133
|
+
* - Minimum profit buffer: 0.1%
|
|
1134
|
+
* - Total: 0.5%
|
|
1135
|
+
*
|
|
1136
|
+
* Default: 0.5% (covers all costs + minimum profit margin)
|
|
1137
|
+
*/
|
|
1138
|
+
CC_MIN_TAKEPROFIT_DISTANCE_PERCENT: number;
|
|
1139
|
+
/**
|
|
1140
|
+
* Minimum StopLoss distance from priceOpen (percentage)
|
|
1141
|
+
* Prevents signals from being immediately stopped out due to price volatility
|
|
1142
|
+
* Default: 0.5% (buffer to avoid instant stop loss on normal market fluctuations)
|
|
1143
|
+
*/
|
|
1144
|
+
CC_MIN_STOPLOSS_DISTANCE_PERCENT: number;
|
|
1145
|
+
/**
|
|
1146
|
+
* Maximum StopLoss distance from priceOpen (percentage)
|
|
1147
|
+
* Prevents catastrophic losses from extreme StopLoss values
|
|
1148
|
+
* Default: 20% (one signal cannot lose more than 20% of position)
|
|
1149
|
+
*/
|
|
1150
|
+
CC_MAX_STOPLOSS_DISTANCE_PERCENT: number;
|
|
1151
|
+
/**
|
|
1152
|
+
* Maximum signal lifetime in minutes
|
|
1153
|
+
* Prevents eternal signals that block risk limits for weeks/months
|
|
1154
|
+
* Default: 1440 minutes (1 day)
|
|
1155
|
+
*/
|
|
1156
|
+
CC_MAX_SIGNAL_LIFETIME_MINUTES: number;
|
|
1157
|
+
/**
|
|
1158
|
+
* Maximum time allowed for signal generation (in seconds).
|
|
1159
|
+
* Prevents long-running or stuck signal generation routines from blocking
|
|
1160
|
+
* execution or consuming resources indefinitely. If generation exceeds this
|
|
1161
|
+
* threshold the attempt should be aborted, logged and optionally retried.
|
|
1162
|
+
*
|
|
1163
|
+
* Default: 180 seconds (3 minutes)
|
|
1164
|
+
*/
|
|
1165
|
+
CC_MAX_SIGNAL_GENERATION_SECONDS: number;
|
|
1166
|
+
/**
|
|
1167
|
+
* Number of retries for getCandles function
|
|
1168
|
+
* Default: 3 retries
|
|
1169
|
+
*/
|
|
1170
|
+
CC_GET_CANDLES_RETRY_COUNT: number;
|
|
1171
|
+
/**
|
|
1172
|
+
* Delay between retries for getCandles function (in milliseconds)
|
|
1173
|
+
* Default: 5000 ms (5 seconds)
|
|
1174
|
+
*/
|
|
1175
|
+
CC_GET_CANDLES_RETRY_DELAY_MS: number;
|
|
1176
|
+
/**
|
|
1177
|
+
* Maximum allowed deviation factor for price anomaly detection.
|
|
1178
|
+
* Price should not be more than this factor lower than reference price.
|
|
1179
|
+
*
|
|
1180
|
+
* Reasoning:
|
|
1181
|
+
* - Incomplete candles from Binance API typically have prices near 0 (e.g., $0.01-1)
|
|
1182
|
+
* - Normal BTC price ranges: $20,000-100,000
|
|
1183
|
+
* - Factor 1000 catches prices below $20-100 when median is $20,000-100,000
|
|
1184
|
+
* - Factor 100 would be too permissive (allows $200 when median is $20,000)
|
|
1185
|
+
* - Factor 10000 might be too strict for low-cap altcoins
|
|
1186
|
+
*
|
|
1187
|
+
* Example: BTC at $50,000 median → threshold $50 (catches $0.01-1 anomalies)
|
|
1188
|
+
*/
|
|
1189
|
+
CC_GET_CANDLES_PRICE_ANOMALY_THRESHOLD_FACTOR: number;
|
|
1190
|
+
/**
|
|
1191
|
+
* Minimum number of candles required for reliable median calculation.
|
|
1192
|
+
* Below this threshold, use simple average instead of median.
|
|
1193
|
+
*
|
|
1194
|
+
* Reasoning:
|
|
1195
|
+
* - Each candle provides 4 price points (OHLC)
|
|
1196
|
+
* - 5 candles = 20 price points, sufficient for robust median calculation
|
|
1197
|
+
* - Below 5 candles, single anomaly can heavily skew median
|
|
1198
|
+
* - Statistical rule of thumb: minimum 7-10 data points for median stability
|
|
1199
|
+
* - Average is more stable than median for small datasets (n < 20)
|
|
1200
|
+
*
|
|
1201
|
+
* Example: 3 candles = 12 points (use average), 5 candles = 20 points (use median)
|
|
1202
|
+
*/
|
|
1203
|
+
CC_GET_CANDLES_MIN_CANDLES_FOR_MEDIAN: number;
|
|
1204
|
+
/**
|
|
1205
|
+
* Controls visibility of signal notes in markdown report tables.
|
|
1206
|
+
* When enabled, the "Note" column will be displayed in all markdown reports
|
|
1207
|
+
* (backtest, live, schedule, risk, etc.)
|
|
1208
|
+
*
|
|
1209
|
+
* Default: false (notes are hidden to reduce table width and improve readability)
|
|
1210
|
+
*/
|
|
1211
|
+
CC_REPORT_SHOW_SIGNAL_NOTE: boolean;
|
|
1212
|
+
};
|
|
1213
|
+
/**
|
|
1214
|
+
* Type for global configuration object.
|
|
1215
|
+
*/
|
|
1216
|
+
type GlobalConfig = typeof GLOBAL_CONFIG;
|
|
1217
|
+
|
|
1218
|
+
/**
|
|
1219
|
+
* Mapping of available table/markdown reports to their column definitions.
|
|
1220
|
+
*
|
|
1221
|
+
* Each property references a column definition object imported from
|
|
1222
|
+
* `src/assets/*.columns`. These are used by markdown/report generators
|
|
1223
|
+
* (backtest, live, schedule, risk, heat, performance, partial, walker).
|
|
1224
|
+
*/
|
|
1225
|
+
declare const COLUMN_CONFIG: {
|
|
1226
|
+
/** Columns used in backtest markdown tables and reports */
|
|
1227
|
+
backtest_columns: ColumnModel<IStrategyTickResultClosed>[];
|
|
1228
|
+
/** Columns used by heatmap / heat reports */
|
|
1229
|
+
heat_columns: ColumnModel<IHeatmapRow>[];
|
|
1230
|
+
/** Columns for live trading reports and logs */
|
|
1231
|
+
live_columns: ColumnModel<TickEvent>[];
|
|
1232
|
+
/** Columns for partial-results / incremental reports */
|
|
1233
|
+
partial_columns: ColumnModel<PartialEvent>[];
|
|
1234
|
+
/** Columns for performance summary reports */
|
|
1235
|
+
performance_columns: ColumnModel<MetricStats>[];
|
|
1236
|
+
/** Columns for risk-related reports */
|
|
1237
|
+
risk_columns: ColumnModel<RiskEvent>[];
|
|
1238
|
+
/** Columns for scheduled report output */
|
|
1239
|
+
schedule_columns: ColumnModel<ScheduledEvent>[];
|
|
1240
|
+
/** Walker: PnL summary columns */
|
|
1241
|
+
walker_pnl_columns: ColumnModel<SignalData$1>[];
|
|
1242
|
+
/** Walker: strategy-level summary columns */
|
|
1243
|
+
walker_strategy_columns: ColumnModel<IStrategyResult>[];
|
|
1244
|
+
};
|
|
1245
|
+
/**
|
|
1246
|
+
* Type for the column configuration object.
|
|
1247
|
+
*/
|
|
1248
|
+
type ColumnConfig = typeof COLUMN_CONFIG;
|
|
1249
|
+
|
|
1250
|
+
/**
|
|
1251
|
+
* Sets custom logger implementation for the framework.
|
|
1252
|
+
*
|
|
1253
|
+
* All log messages from internal services will be forwarded to the provided logger
|
|
1254
|
+
* with automatic context injection (strategyName, exchangeName, symbol, etc.).
|
|
1255
|
+
*
|
|
1256
|
+
* @param logger - Custom logger implementing ILogger interface
|
|
1257
|
+
*
|
|
1258
|
+
* @example
|
|
1259
|
+
* ```typescript
|
|
1260
|
+
* setLogger({
|
|
1261
|
+
* log: (topic, ...args) => console.log(topic, args),
|
|
1262
|
+
* debug: (topic, ...args) => console.debug(topic, args),
|
|
1263
|
+
* info: (topic, ...args) => console.info(topic, args),
|
|
1264
|
+
* });
|
|
1265
|
+
* ```
|
|
1266
|
+
*/
|
|
1267
|
+
declare function setLogger(logger: ILogger): void;
|
|
1268
|
+
/**
|
|
1269
|
+
* Sets global configuration parameters for the framework.
|
|
1270
|
+
* @param config - Partial configuration object to override default settings
|
|
1271
|
+
* @param _unsafe - Skip config validations - required for testbed
|
|
1272
|
+
*
|
|
1273
|
+
* @example
|
|
1274
|
+
* ```typescript
|
|
1275
|
+
* setConfig({
|
|
1276
|
+
* CC_SCHEDULE_AWAIT_MINUTES: 90,
|
|
1277
|
+
* });
|
|
1278
|
+
* ```
|
|
1279
|
+
*/
|
|
1280
|
+
declare function setConfig(config: Partial<GlobalConfig>, _unsafe?: boolean): void;
|
|
1281
|
+
/**
|
|
1282
|
+
* Retrieves a copy of the current global configuration.
|
|
1283
|
+
*
|
|
1284
|
+
* Returns a shallow copy of the current GLOBAL_CONFIG to prevent accidental mutations.
|
|
1285
|
+
* Use this to inspect the current configuration state without modifying it.
|
|
1286
|
+
*
|
|
1287
|
+
* @returns {GlobalConfig} A copy of the current global configuration object
|
|
1288
|
+
*
|
|
1289
|
+
* @example
|
|
1290
|
+
* ```typescript
|
|
1291
|
+
* const currentConfig = getConfig();
|
|
1292
|
+
* console.log(currentConfig.CC_SCHEDULE_AWAIT_MINUTES);
|
|
1293
|
+
* ```
|
|
1294
|
+
*/
|
|
1295
|
+
declare function getConfig(): {
|
|
1296
|
+
CC_SCHEDULE_AWAIT_MINUTES: number;
|
|
1297
|
+
CC_AVG_PRICE_CANDLES_COUNT: number;
|
|
1298
|
+
CC_PERCENT_SLIPPAGE: number;
|
|
1299
|
+
CC_PERCENT_FEE: number;
|
|
1300
|
+
CC_MIN_TAKEPROFIT_DISTANCE_PERCENT: number;
|
|
1301
|
+
CC_MIN_STOPLOSS_DISTANCE_PERCENT: number;
|
|
1302
|
+
CC_MAX_STOPLOSS_DISTANCE_PERCENT: number;
|
|
1303
|
+
CC_MAX_SIGNAL_LIFETIME_MINUTES: number;
|
|
1304
|
+
CC_MAX_SIGNAL_GENERATION_SECONDS: number;
|
|
1305
|
+
CC_GET_CANDLES_RETRY_COUNT: number;
|
|
1306
|
+
CC_GET_CANDLES_RETRY_DELAY_MS: number;
|
|
1307
|
+
CC_GET_CANDLES_PRICE_ANOMALY_THRESHOLD_FACTOR: number;
|
|
1308
|
+
CC_GET_CANDLES_MIN_CANDLES_FOR_MEDIAN: number;
|
|
1309
|
+
CC_REPORT_SHOW_SIGNAL_NOTE: boolean;
|
|
1310
|
+
};
|
|
1311
|
+
/**
|
|
1312
|
+
* Retrieves the default configuration object for the framework.
|
|
1313
|
+
*
|
|
1314
|
+
* Returns a reference to the default configuration with all preset values.
|
|
1315
|
+
* Use this to see what configuration options are available and their default values.
|
|
1316
|
+
*
|
|
1317
|
+
* @returns {GlobalConfig} The default configuration object
|
|
1318
|
+
*
|
|
1319
|
+
* @example
|
|
1320
|
+
* ```typescript
|
|
1321
|
+
* const defaultConfig = getDefaultConfig();
|
|
1322
|
+
* console.log(defaultConfig.CC_SCHEDULE_AWAIT_MINUTES);
|
|
1323
|
+
* ```
|
|
1324
|
+
*/
|
|
1325
|
+
declare function getDefaultConfig(): Readonly<{
|
|
1326
|
+
CC_SCHEDULE_AWAIT_MINUTES: number;
|
|
1327
|
+
CC_AVG_PRICE_CANDLES_COUNT: number;
|
|
1328
|
+
CC_PERCENT_SLIPPAGE: number;
|
|
1329
|
+
CC_PERCENT_FEE: number;
|
|
1330
|
+
CC_MIN_TAKEPROFIT_DISTANCE_PERCENT: number;
|
|
1331
|
+
CC_MIN_STOPLOSS_DISTANCE_PERCENT: number;
|
|
1332
|
+
CC_MAX_STOPLOSS_DISTANCE_PERCENT: number;
|
|
1333
|
+
CC_MAX_SIGNAL_LIFETIME_MINUTES: number;
|
|
1334
|
+
CC_MAX_SIGNAL_GENERATION_SECONDS: number;
|
|
1335
|
+
CC_GET_CANDLES_RETRY_COUNT: number;
|
|
1336
|
+
CC_GET_CANDLES_RETRY_DELAY_MS: number;
|
|
1337
|
+
CC_GET_CANDLES_PRICE_ANOMALY_THRESHOLD_FACTOR: number;
|
|
1338
|
+
CC_GET_CANDLES_MIN_CANDLES_FOR_MEDIAN: number;
|
|
1339
|
+
CC_REPORT_SHOW_SIGNAL_NOTE: boolean;
|
|
1340
|
+
}>;
|
|
1341
|
+
/**
|
|
1342
|
+
* Sets custom column configurations for markdown report generation.
|
|
1343
|
+
*
|
|
1344
|
+
* Allows overriding default column definitions for any report type.
|
|
1345
|
+
* All columns are validated before assignment to ensure structural correctness.
|
|
1346
|
+
*
|
|
1347
|
+
* @param columns - Partial column configuration object to override default column settings
|
|
1348
|
+
* @param _unsafe - Skip column validations - required for testbed
|
|
1349
|
+
*
|
|
1350
|
+
* @example
|
|
1351
|
+
* ```typescript
|
|
1352
|
+
* setColumns({
|
|
1353
|
+
* backtest_columns: [
|
|
1354
|
+
* {
|
|
1355
|
+
* key: "customId",
|
|
1356
|
+
* label: "Custom ID",
|
|
1357
|
+
* format: (data) => data.signal.id,
|
|
1358
|
+
* isVisible: () => true
|
|
1359
|
+
* }
|
|
1360
|
+
* ],
|
|
1361
|
+
* });
|
|
1362
|
+
* ```
|
|
1363
|
+
*
|
|
1364
|
+
* @throws {Error} If column configuration is invalid
|
|
1365
|
+
*/
|
|
1366
|
+
declare function setColumns(columns: Partial<ColumnConfig>, _unsafe?: boolean): void;
|
|
1367
|
+
/**
|
|
1368
|
+
* Retrieves a copy of the current column configuration for markdown report generation.
|
|
1369
|
+
*
|
|
1370
|
+
* Returns a shallow copy of the current COLUMN_CONFIG to prevent accidental mutations.
|
|
1371
|
+
* Use this to inspect the current column definitions without modifying them.
|
|
1372
|
+
*
|
|
1373
|
+
* @returns {ColumnConfig} A copy of the current column configuration object
|
|
1374
|
+
*
|
|
1375
|
+
* @example
|
|
1376
|
+
* ```typescript
|
|
1377
|
+
* const currentColumns = getColumns();
|
|
1378
|
+
* console.log(currentColumns.backtest_columns.length);
|
|
1379
|
+
* ```
|
|
1380
|
+
*/
|
|
1381
|
+
declare function getColumns(): {
|
|
1382
|
+
backtest_columns: ColumnModel<IStrategyTickResultClosed>[];
|
|
1383
|
+
heat_columns: ColumnModel<IHeatmapRow>[];
|
|
1384
|
+
live_columns: ColumnModel<TickEvent>[];
|
|
1385
|
+
partial_columns: ColumnModel<PartialEvent>[];
|
|
1386
|
+
performance_columns: ColumnModel<MetricStats>[];
|
|
1387
|
+
risk_columns: ColumnModel<RiskEvent>[];
|
|
1388
|
+
schedule_columns: ColumnModel<ScheduledEvent>[];
|
|
1389
|
+
walker_pnl_columns: ColumnModel<SignalData$1>[];
|
|
1390
|
+
walker_strategy_columns: ColumnModel<IStrategyResult>[];
|
|
1391
|
+
};
|
|
1392
|
+
/**
|
|
1393
|
+
* Retrieves the default column configuration object for markdown report generation.
|
|
1394
|
+
*
|
|
1395
|
+
* Returns a reference to the default column definitions with all preset values.
|
|
1396
|
+
* Use this to see what column options are available and their default definitions.
|
|
1397
|
+
*
|
|
1398
|
+
* @returns {ColumnConfig} The default column configuration object
|
|
1399
|
+
*
|
|
1400
|
+
* @example
|
|
1401
|
+
* ```typescript
|
|
1402
|
+
* const defaultColumns = getDefaultColumns();
|
|
1403
|
+
* console.log(defaultColumns.backtest_columns);
|
|
1404
|
+
* ```
|
|
1405
|
+
*/
|
|
1406
|
+
declare function getDefaultColumns(): Readonly<{
|
|
1407
|
+
backtest_columns: ColumnModel<IStrategyTickResultClosed>[];
|
|
1408
|
+
heat_columns: ColumnModel<IHeatmapRow>[];
|
|
1409
|
+
live_columns: ColumnModel<TickEvent>[];
|
|
1410
|
+
partial_columns: ColumnModel<PartialEvent>[];
|
|
1411
|
+
performance_columns: ColumnModel<MetricStats>[];
|
|
1412
|
+
risk_columns: ColumnModel<RiskEvent>[];
|
|
1413
|
+
schedule_columns: ColumnModel<ScheduledEvent>[];
|
|
1414
|
+
walker_pnl_columns: ColumnModel<SignalData$1>[];
|
|
1415
|
+
walker_strategy_columns: ColumnModel<IStrategyResult>[];
|
|
1416
|
+
}>;
|
|
1417
|
+
|
|
1372
1418
|
/**
|
|
1373
1419
|
* Statistical data calculated from backtest results.
|
|
1374
1420
|
*
|
|
@@ -11230,4 +11276,4 @@ declare const backtest: {
|
|
|
11230
11276
|
loggerService: LoggerService;
|
|
11231
11277
|
};
|
|
11232
11278
|
|
|
11233
|
-
export { Backtest, type BacktestStatisticsModel, Cache, type CandleInterval, type ColumnConfig, type ColumnModel, Constant, type DoneContract, type EntityId, Exchange, ExecutionContextService, type FrameInterval, type GlobalConfig, Heat, type HeatmapStatisticsModel, type ICandleData, type IExchangeSchema, type IFrameSchema, type IHeatmapRow, type IOptimizerCallbacks, type IOptimizerData, type IOptimizerFetchArgs, type IOptimizerFilterArgs, type IOptimizerRange, type IOptimizerSchema, type IOptimizerSource, type IOptimizerStrategy, type IOptimizerTemplate, type IPersistBase, type IPositionSizeATRParams, type IPositionSizeFixedPercentageParams, type IPositionSizeKellyParams, type IRiskActivePosition, type IRiskCheckArgs, type IRiskSchema, type IRiskValidation, type IRiskValidationFn, type IRiskValidationPayload, type IScheduledSignalCancelRow, type IScheduledSignalRow, type ISignalDto, type ISignalRow, type ISizingCalculateParams, type ISizingCalculateParamsATR, type ISizingCalculateParamsFixedPercentage, type ISizingCalculateParamsKelly, type ISizingSchema, type ISizingSchemaATR, type ISizingSchemaFixedPercentage, type ISizingSchemaKelly, type IStrategyPnL, type IStrategyResult, type IStrategySchema, type IStrategyTickResult, type IStrategyTickResultActive, type IStrategyTickResultCancelled, type IStrategyTickResultClosed, type IStrategyTickResultIdle, type IStrategyTickResultOpened, type IStrategyTickResultScheduled, type IWalkerResults, type IWalkerSchema, type IWalkerStrategyResult, Live, type LiveStatisticsModel, type MessageModel, type MessageRole, MethodContextService, type MetricStats, Optimizer, Partial$1 as Partial, type PartialData, type PartialEvent, type PartialLossContract, type PartialProfitContract, type PartialStatisticsModel, Performance, type PerformanceContract, type PerformanceMetricType, type PerformanceStatisticsModel, PersistBase, PersistPartialAdapter, PersistRiskAdapter, PersistScheduleAdapter, PersistSignalAdapter, type PingContract, PositionSize, type ProgressBacktestContract, type ProgressOptimizerContract, type ProgressWalkerContract, Risk, type RiskContract, type RiskData, type RiskEvent, type RiskStatisticsModel, Schedule, type ScheduleData, type ScheduleStatisticsModel, type ScheduledEvent, type SignalData, type SignalInterval, type TPersistBase, type TPersistBaseCtor, type TickEvent, Walker, type WalkerCompleteContract, type WalkerContract, type WalkerMetric, type SignalData$1 as WalkerSignalData, type WalkerStatisticsModel, addExchange, addFrame, addOptimizer, addRisk, addSizing, addStrategy, addWalker, dumpSignal, emitters, formatPrice, formatQuantity, getAveragePrice, getCandles, getColumns, getConfig, getDate, getDefaultColumns, getDefaultConfig, getMode, hasTradeContext, backtest as lib, listExchanges, listFrames, listOptimizers, listRisks, listSizings, listStrategies, listWalkers, listenBacktestProgress, listenDoneBacktest, listenDoneBacktestOnce, listenDoneLive, listenDoneLiveOnce, listenDoneWalker, listenDoneWalkerOnce, listenError, listenExit, listenOptimizerProgress, listenPartialLoss, listenPartialLossOnce, listenPartialProfit, listenPartialProfitOnce, listenPerformance, listenPing, listenPingOnce, listenRisk, listenRiskOnce, listenSignal, listenSignalBacktest, listenSignalBacktestOnce, listenSignalLive, listenSignalLiveOnce, listenSignalOnce, listenValidation, listenWalker, listenWalkerComplete, listenWalkerOnce, listenWalkerProgress, setColumns, setConfig, setLogger, validate };
|
|
11279
|
+
export { Backtest, type BacktestStatisticsModel, Cache, type CandleInterval, type ColumnConfig, type ColumnModel, Constant, type DoneContract, type EntityId, Exchange, ExecutionContextService, type FrameInterval, type GlobalConfig, Heat, type HeatmapStatisticsModel, type ICandleData, type IExchangeSchema, type IFrameSchema, type IHeatmapRow, type IOptimizerCallbacks, type IOptimizerData, type IOptimizerFetchArgs, type IOptimizerFilterArgs, type IOptimizerRange, type IOptimizerSchema, type IOptimizerSource, type IOptimizerStrategy, type IOptimizerTemplate, type IPersistBase, type IPositionSizeATRParams, type IPositionSizeFixedPercentageParams, type IPositionSizeKellyParams, type IRiskActivePosition, type IRiskCheckArgs, type IRiskSchema, type IRiskValidation, type IRiskValidationFn, type IRiskValidationPayload, type IScheduledSignalCancelRow, type IScheduledSignalRow, type ISignalDto, type ISignalRow, type ISizingCalculateParams, type ISizingCalculateParamsATR, type ISizingCalculateParamsFixedPercentage, type ISizingCalculateParamsKelly, type ISizingSchema, type ISizingSchemaATR, type ISizingSchemaFixedPercentage, type ISizingSchemaKelly, type IStrategyPnL, type IStrategyResult, type IStrategySchema, type IStrategyTickResult, type IStrategyTickResultActive, type IStrategyTickResultCancelled, type IStrategyTickResultClosed, type IStrategyTickResultIdle, type IStrategyTickResultOpened, type IStrategyTickResultScheduled, type IWalkerResults, type IWalkerSchema, type IWalkerStrategyResult, Live, type LiveStatisticsModel, type MessageModel, type MessageRole, MethodContextService, type MetricStats, Optimizer, Partial$1 as Partial, type PartialData, type PartialEvent, type PartialLossContract, type PartialProfitContract, type PartialStatisticsModel, Performance, type PerformanceContract, type PerformanceMetricType, type PerformanceStatisticsModel, PersistBase, PersistPartialAdapter, PersistRiskAdapter, PersistScheduleAdapter, PersistSignalAdapter, type PingContract, PositionSize, type ProgressBacktestContract, type ProgressOptimizerContract, type ProgressWalkerContract, Risk, type RiskContract, type RiskData, type RiskEvent, type RiskStatisticsModel, Schedule, type ScheduleData, type ScheduleStatisticsModel, type ScheduledEvent, type SignalData, type SignalInterval, type TPersistBase, type TPersistBaseCtor, type TickEvent, Walker, type WalkerCompleteContract, type WalkerContract, type WalkerMetric, type SignalData$1 as WalkerSignalData, type WalkerStatisticsModel, addExchange, addFrame, addOptimizer, addRisk, addSizing, addStrategy, addWalker, cancel, dumpSignal, emitters, formatPrice, formatQuantity, getAveragePrice, getCandles, getColumns, getConfig, getDate, getDefaultColumns, getDefaultConfig, getMode, hasTradeContext, backtest as lib, listExchanges, listFrames, listOptimizers, listRisks, listSizings, listStrategies, listWalkers, listenBacktestProgress, listenDoneBacktest, listenDoneBacktestOnce, listenDoneLive, listenDoneLiveOnce, listenDoneWalker, listenDoneWalkerOnce, listenError, listenExit, listenOptimizerProgress, listenPartialLoss, listenPartialLossOnce, listenPartialProfit, listenPartialProfitOnce, listenPerformance, listenPing, listenPingOnce, listenRisk, listenRiskOnce, listenSignal, listenSignalBacktest, listenSignalBacktestOnce, listenSignalLive, listenSignalLiveOnce, listenSignalOnce, listenValidation, listenWalker, listenWalkerComplete, listenWalkerOnce, listenWalkerProgress, setColumns, setConfig, setLogger, stop, validate };
|