backtest-kit 1.5.12 → 1.5.13

package/types.d.ts

@@ -13,10 +13,30 @@ declare const GLOBAL_CONFIG: {
      * Default: 5 candles (last 5 minutes when using 1m interval)
      */
     CC_AVG_PRICE_CANDLES_COUNT: number;
+    /**
+     * Slippage percentage applied to entry and exit prices.
+     * Simulates market impact and order book depth.
+     * Applied twice (entry and exit) for realistic execution simulation.
+     * Default: 0.1% per transaction
+     */
+    CC_PERCENT_SLIPPAGE: number;
+    /**
+     * Fee percentage charged per transaction.
+     * Applied twice (entry and exit) for total fee calculation.
+     * Default: 0.1% per transaction (total 0.2%)
+     */
+    CC_PERCENT_FEE: number;
     /**
      * Minimum TakeProfit distance from priceOpen (percentage)
-     * Must be greater than trading fees to ensure profitable trades
-     * Default: 0.3% (covers 2×0.1% fees + minimum profit margin)
+     * Must be greater than (slippage + fees) to ensure profitable trades
+     *
+     * Calculation:
+     * - Slippage effect: ~0.2% (0.1% × 2 transactions)
+     * - Fees: 0.2% (0.1% × 2 transactions)
+     * - Minimum profit buffer: 0.1%
+     * - Total: 0.5%
+     *
+     * Default: 0.5% (covers all costs + minimum profit margin)
      */
     CC_MIN_TAKEPROFIT_DISTANCE_PERCENT: number;
     /**
@@ -135,7 +155,7 @@ interface ILogger {
  * });
  * ```
  */
-declare function setLogger(logger: ILogger): Promise<void>;
+declare function setLogger(logger: ILogger): void;
 /**
  * Sets global configuration parameters for the framework.
  * @param config - Partial configuration object to override default settings
@@ -147,7 +167,65 @@ declare function setLogger(logger: ILogger): Promise<void>;
  * });
  * ```
  */
-declare function setConfig(config: Partial<GlobalConfig>): Promise<void>;
+declare function setConfig(config: Partial<GlobalConfig>, _unsafe?: boolean): void;
+/**
+ * Retrieves a copy of the current global configuration.
+ *
+ * Returns a shallow copy of the current GLOBAL_CONFIG to prevent accidental mutations.
+ * Use this to inspect the current configuration state without modifying it.
+ *
+ * @returns {GlobalConfig} A copy of the current global configuration object
+ *
+ * @example
+ * ```typescript
+ * const currentConfig = getConfig();
+ * console.log(currentConfig.CC_SCHEDULE_AWAIT_MINUTES);
+ * ```
+ */
+declare function getConfig(): {
+    CC_SCHEDULE_AWAIT_MINUTES: number;
+    CC_AVG_PRICE_CANDLES_COUNT: number;
+    CC_PERCENT_SLIPPAGE: number;
+    CC_PERCENT_FEE: number;
+    CC_MIN_TAKEPROFIT_DISTANCE_PERCENT: number;
+    CC_MIN_STOPLOSS_DISTANCE_PERCENT: number;
+    CC_MAX_STOPLOSS_DISTANCE_PERCENT: number;
+    CC_MAX_SIGNAL_LIFETIME_MINUTES: number;
+    CC_MAX_SIGNAL_GENERATION_SECONDS: number;
+    CC_GET_CANDLES_RETRY_COUNT: number;
+    CC_GET_CANDLES_RETRY_DELAY_MS: number;
+    CC_GET_CANDLES_PRICE_ANOMALY_THRESHOLD_FACTOR: number;
+    CC_GET_CANDLES_MIN_CANDLES_FOR_MEDIAN: number;
+};
+/**
+ * Retrieves the default configuration object for the framework.
+ *
+ * Returns a reference to the default configuration with all preset values.
+ * Use this to see what configuration options are available and their default values.
+ *
+ * @returns {GlobalConfig} The default configuration object
+ *
+ * @example
+ * ```typescript
+ * const defaultConfig = getDefaultConfig();
+ * console.log(defaultConfig.CC_SCHEDULE_AWAIT_MINUTES);
+ * ```
+ */
+declare function getDefaultConfig(): Readonly<{
+    CC_SCHEDULE_AWAIT_MINUTES: number;
+    CC_AVG_PRICE_CANDLES_COUNT: number;
+    CC_PERCENT_SLIPPAGE: number;
+    CC_PERCENT_FEE: number;
+    CC_MIN_TAKEPROFIT_DISTANCE_PERCENT: number;
+    CC_MIN_STOPLOSS_DISTANCE_PERCENT: number;
+    CC_MAX_STOPLOSS_DISTANCE_PERCENT: number;
+    CC_MAX_SIGNAL_LIFETIME_MINUTES: number;
+    CC_MAX_SIGNAL_GENERATION_SECONDS: number;
+    CC_GET_CANDLES_RETRY_COUNT: number;
+    CC_GET_CANDLES_RETRY_DELAY_MS: number;
+    CC_GET_CANDLES_PRICE_ANOMALY_THRESHOLD_FACTOR: number;
+    CC_GET_CANDLES_MIN_CANDLES_FOR_MEDIAN: number;
+}>;
 
 /**
  * Execution context containing runtime parameters for strategy/exchange operations.
@@ -8194,8 +8272,27 @@ declare class HeatMarkdownService {
 }
 
 /**
- * @class ExchangeValidationService
- * Service for managing and validating exchange configurations
+ * Service for managing and validating exchange configurations.
+ *
+ * Maintains a registry of all configured exchanges and validates
+ * their existence before operations. Uses memoization for performance.
+ *
+ * Key features:
+ * - Registry management: addExchange() to register new exchanges
+ * - Validation: validate() ensures exchange exists before use
+ * - Memoization: validation results are cached for performance
+ * - Listing: list() returns all registered exchanges
+ *
+ * @throws {Error} If duplicate exchange name is added
+ * @throws {Error} If unknown exchange is referenced
+ *
+ * @example
+ * ```typescript
+ * const exchangeValidation = new ExchangeValidationService();
+ * exchangeValidation.addExchange("binance", binanceSchema);
+ * exchangeValidation.validate("binance", "backtest"); // OK
+ * exchangeValidation.validate("unknown", "live"); // Throws error
+ * ```
  */
 declare class ExchangeValidationService {
     /**
@@ -8231,8 +8328,29 @@ declare class ExchangeValidationService {
 }
 
 /**
- * @class StrategyValidationService
- * Service for managing and validating strategy configurations
+ * Service for managing and validating trading strategy configurations.
+ *
+ * Maintains a registry of all configured strategies, validates their existence
+ * before operations, and ensures associated risk profiles are valid.
+ * Uses memoization for performance.
+ *
+ * Key features:
+ * - Registry management: addStrategy() to register new strategies
+ * - Dual validation: validates both strategy existence and risk profile (if configured)
+ * - Memoization: validation results are cached for performance
+ * - Listing: list() returns all registered strategies
+ *
+ * @throws {Error} If duplicate strategy name is added
+ * @throws {Error} If unknown strategy is referenced
+ * @throws {Error} If strategy's risk profile doesn't exist
+ *
+ * @example
+ * ```typescript
+ * const strategyValidation = new StrategyValidationService();
+ * strategyValidation.addStrategy("momentum-btc", { ...schema, riskName: "conservative" });
+ * strategyValidation.validate("momentum-btc", "backtest"); // Validates strategy + risk
+ * strategyValidation.validate("unknown", "live"); // Throws error
+ * ```
  */
 declare class StrategyValidationService {
     /**
@@ -8275,8 +8393,27 @@ declare class StrategyValidationService {
 }
 
 /**
- * @class FrameValidationService
- * Service for managing and validating frame configurations
+ * Service for managing and validating frame (timeframe) configurations.
+ *
+ * Maintains a registry of all configured frames and validates
+ * their existence before operations. Uses memoization for performance.
+ *
+ * Key features:
+ * - Registry management: addFrame() to register new timeframes
+ * - Validation: validate() ensures frame exists before use
+ * - Memoization: validation results are cached for performance
+ * - Listing: list() returns all registered frames
+ *
+ * @throws {Error} If duplicate frame name is added
+ * @throws {Error} If unknown frame is referenced
+ *
+ * @example
+ * ```typescript
+ * const frameValidation = new FrameValidationService();
+ * frameValidation.addFrame("2024-Q1", frameSchema);
+ * frameValidation.validate("2024-Q1", "backtest"); // OK
+ * frameValidation.validate("unknown", "live"); // Throws error
+ * ```
  */
 declare class FrameValidationService {
     /**
@@ -8312,8 +8449,29 @@ declare class FrameValidationService {
 }
 
 /**
- * @class WalkerValidationService
- * Service for managing and validating walker configurations
+ * Service for managing and validating walker (parameter sweep) configurations.
+ *
+ * Maintains a registry of all configured walkers and validates
+ * their existence before operations. Uses memoization for performance.
+ *
+ * Walkers define parameter ranges for optimization and hyperparameter tuning.
+ *
+ * Key features:
+ * - Registry management: addWalker() to register new walker configurations
+ * - Validation: validate() ensures walker exists before use
+ * - Memoization: validation results are cached for performance
+ * - Listing: list() returns all registered walkers
+ *
+ * @throws {Error} If duplicate walker name is added
+ * @throws {Error} If unknown walker is referenced
+ *
+ * @example
+ * ```typescript
+ * const walkerValidation = new WalkerValidationService();
+ * walkerValidation.addWalker("rsi-sweep", walkerSchema);
+ * walkerValidation.validate("rsi-sweep", "optimizer"); // OK
+ * walkerValidation.validate("unknown", "optimizer"); // Throws error
+ * ```
  */
 declare class WalkerValidationService {
     /**
@@ -8349,8 +8507,27 @@ declare class WalkerValidationService {
 }
 
 /**
- * @class SizingValidationService
- * Service for managing and validating sizing configurations
+ * Service for managing and validating position sizing configurations.
+ *
+ * Maintains a registry of all configured sizing strategies and validates
+ * their existence before operations. Uses memoization for performance.
+ *
+ * Key features:
+ * - Registry management: addSizing() to register new sizing strategies
+ * - Validation: validate() ensures sizing strategy exists before use
+ * - Memoization: validation results are cached for performance
+ * - Listing: list() returns all registered sizing strategies
+ *
+ * @throws {Error} If duplicate sizing name is added
+ * @throws {Error} If unknown sizing strategy is referenced
+ *
+ * @example
+ * ```typescript
+ * const sizingValidation = new SizingValidationService();
+ * sizingValidation.addSizing("fixed-1000", fixedSizingSchema);
+ * sizingValidation.validate("fixed-1000", "strategy-1"); // OK
+ * sizingValidation.validate("unknown", "strategy-2"); // Throws error
+ * ```
  */
 declare class SizingValidationService {
     /**
@@ -8387,8 +8564,27 @@ declare class SizingValidationService {
 }
 
 /**
- * @class RiskValidationService
- * Service for managing and validating risk configurations
+ * Service for managing and validating risk management configurations.
+ *
+ * Maintains a registry of all configured risk profiles and validates
+ * their existence before operations. Uses memoization for performance.
+ *
+ * Key features:
+ * - Registry management: addRisk() to register new risk profiles
+ * - Validation: validate() ensures risk profile exists before use
+ * - Memoization: validation results are cached by riskName:source for performance
+ * - Listing: list() returns all registered risk profiles
+ *
+ * @throws {Error} If duplicate risk name is added
+ * @throws {Error} If unknown risk profile is referenced
+ *
+ * @example
+ * ```typescript
+ * const riskValidation = new RiskValidationService();
+ * riskValidation.addRisk("conservative", conservativeSchema);
+ * riskValidation.validate("conservative", "strategy-1"); // OK
+ * riskValidation.validate("unknown", "strategy-2"); // Throws error
+ * ```
  */
 declare class RiskValidationService {
     /**
@@ -9019,6 +9215,57 @@ declare class OutlineMarkdownService {
     dumpSignal: (signalId: ResultId, history: MessageModel[], signal: ISignalDto, outputDir?: string) => Promise<void>;
 }
 
+/**
+ * Service for validating GLOBAL_CONFIG parameters to ensure mathematical correctness
+ * and prevent unprofitable trading configurations.
+ *
+ * Performs comprehensive validation on:
+ * - **Percentage parameters**: Slippage, fees, and profit margins must be non-negative
+ * - **Economic viability**: Ensures CC_MIN_TAKEPROFIT_DISTANCE_PERCENT covers all trading costs
+ *   (slippage + fees) to guarantee profitable trades when TakeProfit is hit
+ * - **Range constraints**: Validates MIN < MAX relationships (e.g., StopLoss distances)
+ * - **Time-based parameters**: Ensures positive integer values for timeouts and lifetimes
+ * - **Candle parameters**: Validates retry counts, delays, and anomaly detection thresholds
+ *
+ * @throws {Error} If any validation fails, throws with detailed breakdown of all errors
+ *
+ * @example
+ * ```typescript
+ * const validator = new ConfigValidationService();
+ * validator.validate(); // Throws if config is invalid
+ * ```
+ *
+ * @example Validation failure output:
+ * ```
+ * GLOBAL_CONFIG validation failed:
+ *   1. CC_MIN_TAKEPROFIT_DISTANCE_PERCENT (0.3%) is too low to cover trading costs.
+ *      Required minimum: 0.40%
+ *      Breakdown:
+ *        - Slippage effect: 0.20% (0.1% × 2 transactions)
+ *        - Fees: 0.20% (0.1% × 2 transactions)
+ *      All TakeProfit signals will be unprofitable with current settings!
+ * ```
+ */
+declare class ConfigValidationService {
+    /**
+     * @private
+     * @readonly
+     * Injected logger service instance
+     */
+    private readonly loggerService;
+    /**
+     * Validates GLOBAL_CONFIG parameters for mathematical correctness.
+     *
+     * Checks:
+     * 1. CC_MIN_TAKEPROFIT_DISTANCE_PERCENT must cover slippage + fees
+     * 2. All percentage values must be positive
+     * 3. Time/count values must be positive integers
+     *
+     * @throws Error if configuration is invalid
+     */
+    validate: () => void;
+}
+
 declare const backtest: {
     optimizerTemplateService: OptimizerTemplateService;
     exchangeValidationService: ExchangeValidationService;
@@ -9028,6 +9275,7 @@ declare const backtest: {
     sizingValidationService: SizingValidationService;
     riskValidationService: RiskValidationService;
     optimizerValidationService: OptimizerValidationService;
+    configValidationService: ConfigValidationService;
     backtestMarkdownService: BacktestMarkdownService;
     liveMarkdownService: LiveMarkdownService;
     scheduleMarkdownService: ScheduleMarkdownService;
@@ -9075,4 +9323,4 @@ declare const backtest: {
     loggerService: LoggerService;
 };
 
-export { Backtest, type BacktestStatistics, type CandleInterval, Constant, type DoneContract, type EntityId, ExecutionContextService, type FrameInterval, type GlobalConfig, Heat, type ICandleData, type IExchangeSchema, type IFrameSchema, type IHeatmapRow, type IHeatmapStatistics, 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 IScheduledSignalRow, type ISignalDto, type ISignalRow, type ISizingCalculateParams, type ISizingCalculateParamsATR, type ISizingCalculateParamsFixedPercentage, type ISizingCalculateParamsKelly, type ISizingSchema, type ISizingSchemaATR, type ISizingSchemaFixedPercentage, type ISizingSchemaKelly, type IStrategyPnL, type IStrategySchema, type IStrategyTickResult, type IStrategyTickResultActive, type IStrategyTickResultCancelled, type IStrategyTickResultClosed, type IStrategyTickResultIdle, type IStrategyTickResultOpened, type IStrategyTickResultScheduled, type IWalkerResults, type IWalkerSchema, type IWalkerStrategyResult, Live, type LiveStatistics, type MessageModel, type MessageRole, MethodContextService, Optimizer, Partial$1 as Partial, type PartialData, type PartialLossContract, type PartialProfitContract, type PartialStatistics, Performance, type PerformanceContract, type PerformanceMetricType, type PerformanceStatistics, PersistBase, PersistPartialAdapter, PersistRiskAdapter, PersistScheduleAdapter, PersistSignalAdapter, PositionSize, type ProgressBacktestContract, type ProgressOptimizerContract, type ProgressWalkerContract, type RiskData, Schedule, type ScheduleData, type ScheduleStatistics, type SignalData, type SignalInterval, type TPersistBase, type TPersistBaseCtor, Walker, type WalkerContract, type WalkerMetric, type WalkerStatistics, addExchange, addFrame, addOptimizer, addRisk, addSizing, addStrategy, addWalker, dumpSignal, emitters, formatPrice, formatQuantity, getAveragePrice, getCandles, getDate, getMode, 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, listenSignal, listenSignalBacktest, listenSignalBacktestOnce, listenSignalLive, listenSignalLiveOnce, listenSignalOnce, listenValidation, listenWalker, listenWalkerComplete, listenWalkerOnce, listenWalkerProgress, setConfig, setLogger };
+export { Backtest, type BacktestStatistics, type CandleInterval, Constant, type DoneContract, type EntityId, ExecutionContextService, type FrameInterval, type GlobalConfig, Heat, type ICandleData, type IExchangeSchema, type IFrameSchema, type IHeatmapRow, type IHeatmapStatistics, 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 IScheduledSignalRow, type ISignalDto, type ISignalRow, type ISizingCalculateParams, type ISizingCalculateParamsATR, type ISizingCalculateParamsFixedPercentage, type ISizingCalculateParamsKelly, type ISizingSchema, type ISizingSchemaATR, type ISizingSchemaFixedPercentage, type ISizingSchemaKelly, type IStrategyPnL, type IStrategySchema, type IStrategyTickResult, type IStrategyTickResultActive, type IStrategyTickResultCancelled, type IStrategyTickResultClosed, type IStrategyTickResultIdle, type IStrategyTickResultOpened, type IStrategyTickResultScheduled, type IWalkerResults, type IWalkerSchema, type IWalkerStrategyResult, Live, type LiveStatistics, type MessageModel, type MessageRole, MethodContextService, Optimizer, Partial$1 as Partial, type PartialData, type PartialLossContract, type PartialProfitContract, type PartialStatistics, Performance, type PerformanceContract, type PerformanceMetricType, type PerformanceStatistics, PersistBase, PersistPartialAdapter, PersistRiskAdapter, PersistScheduleAdapter, PersistSignalAdapter, PositionSize, type ProgressBacktestContract, type ProgressOptimizerContract, type ProgressWalkerContract, type RiskData, Schedule, type ScheduleData, type ScheduleStatistics, type SignalData, type SignalInterval, type TPersistBase, type TPersistBaseCtor, Walker, type WalkerContract, type WalkerMetric, type WalkerStatistics, addExchange, addFrame, addOptimizer, addRisk, addSizing, addStrategy, addWalker, dumpSignal, emitters, formatPrice, formatQuantity, getAveragePrice, getCandles, getConfig, getDate, getDefaultConfig, getMode, 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, listenSignal, listenSignalBacktest, listenSignalBacktestOnce, listenSignalLive, listenSignalLiveOnce, listenSignalOnce, listenValidation, listenWalker, listenWalkerComplete, listenWalkerOnce, listenWalkerProgress, setConfig, setLogger };