backtest-kit 1.5.44 → 1.5.46

package/README.md

@@ -2,7 +2,7 @@
 
 # 🧿 Backtest Kit
 
-> A TypeScript framework for backtesting and live trading strategies on crypto markets or forex, with crash-safe persistence, signal validation, and AI optimization.
+> A TypeScript framework for backtesting and live trading strategies on multi-asset, crypto or forex, with crash-safe persistence, signal validation, and AI optimization.
 
 ![future](./assets/prophet.png)
 

package/build/index.cjs

@@ -4175,17 +4175,29 @@ class SizingConnectionService {
     }
 }
 
+/**
+ * Retrieves a value from an object using a given path.
+ *
+ * @param object - The object from which to retrieve the value.
+ * @param path - The path to the desired value, either as an array or dot-separated string.
+ * @returns - The value at the specified path, or undefined if it does not exist.
+ */
+const get = (object, path) => {
+    const pathArray = Array.isArray(path) ? path : path.split('.').filter((key) => key);
+    const pathArrayFlat = pathArray.flatMap((part) => typeof part === 'string' ? part.split('.') : part);
+    return pathArrayFlat.reduce((obj, key) => obj && obj[key], object);
+};
+
 /** Symbol indicating that positions need to be fetched from persistence */
 const POSITION_NEED_FETCH = Symbol("risk-need-fetch");
 /** Key generator for active position map */
 const GET_KEY_FN = (strategyName, symbol) => `${strategyName}:${symbol}`;
 /** Wrapper to execute risk validation function with error handling */
-const DO_VALIDATION_FN = functoolsKit.trycatch(async (validation, params) => {
-    await validation(params);
-    return true;
-}, {
-    defaultValue: false,
-    fallback: (error) => {
+const DO_VALIDATION_FN = async (validation, params) => {
+    try {
+        return await validation(params);
+    }
+    catch (error) {
         const message = "ClientRisk exception thrown";
         const payload = {
             error: functoolsKit.errorData(error),
@@ -4194,8 +4206,9 @@ const DO_VALIDATION_FN = functoolsKit.trycatch(async (validation, params) => {
         backtest$1.loggerService.warn(message, payload);
         console.warn(message, payload);
         validationSubject.next(error);
-    },
-});
+        return payload.message;
+    }
+};
 /**
  * Initializes active positions by reading from persistence.
  * Uses singleshot pattern to ensure it only runs once.
@@ -4204,7 +4217,9 @@ const DO_VALIDATION_FN = functoolsKit.trycatch(async (validation, params) => {
  * In backtest mode, initializes with empty Map. In live mode, reads from persist storage.
  */
 const WAIT_FOR_INIT_FN$1 = async (self) => {
-    self.params.logger.debug("ClientRisk waitForInit", { backtest: self.params.backtest });
+    self.params.logger.debug("ClientRisk waitForInit", {
+        backtest: self.params.backtest,
+    });
     if (self.params.backtest) {
         self._activePositions = new Map();
         return;
@@ -4267,26 +4282,36 @@ class ClientRisk {
                 activePositionCount: riskMap.size,
                 activePositions: Array.from(riskMap.values()),
             };
-            // Execute custom validations
-            let isValid = true;
-            let rejectionNote = "N/A";
+            let rejectionResult = null;
             if (this.params.validations) {
                 for (const validation of this.params.validations) {
-                    if (functoolsKit.not(await DO_VALIDATION_FN(typeof validation === "function"
-                        ? validation
-                        : validation.validate, payload))) {
-                        isValid = false;
-                        // Capture note from validation if available
-                        if (typeof validation !== "function" && validation.note) {
-                            rejectionNote = validation.note;
-                        }
+                    const rejection = await DO_VALIDATION_FN(typeof validation === "function" ? validation : validation.validate, payload);
+                    if (!rejection) {
+                        continue;
+                    }
+                    if (typeof rejection === "string") {
+                        rejectionResult = {
+                            id: null,
+                            note: rejection
+                                ? rejection
+                                : "note" in validation
+                                    ? validation.note
+                                    : "Validation failed",
+                        };
+                        break;
+                    }
+                    if (functoolsKit.isObject(rejection)) {
+                        rejectionResult = {
+                            id: get(rejection, "id") || null,
+                            note: get(rejection, "note") || "Validation rejected the signal",
+                        };
                         break;
                     }
                 }
             }
-            if (!isValid) {
+            if (rejectionResult) {
                 // Call params.onRejected for riskSubject emission
-                await this.params.onRejected(params.symbol, params, riskMap.size, rejectionNote, Date.now(), this.params.backtest);
+                await this.params.onRejected(params.symbol, params, riskMap.size, rejectionResult, params.timestamp, this.params.backtest);
                 // Call schema callbacks.onRejected if defined
                 if (this.params.callbacks?.onRejected) {
                     this.params.callbacks.onRejected(params.symbol, params);
@@ -4365,18 +4390,19 @@ class ClientRisk {
  * @param symbol - Trading pair symbol
  * @param params - Risk check arguments
  * @param activePositionCount - Number of active positions at rejection time
- * @param comment - Rejection reason from validation note or "N/A"
+ * @param rejectionResult - Rejection result with id and note
  * @param timestamp - Event timestamp in milliseconds
  * @param backtest - True if backtest mode, false if live mode
  */
-const COMMIT_REJECTION_FN = async (symbol, params, activePositionCount, comment, timestamp, backtest) => await riskSubject.next({
+const COMMIT_REJECTION_FN = async (symbol, params, activePositionCount, rejectionResult, timestamp, backtest) => await riskSubject.next({
     symbol,
     pendingSignal: params.pendingSignal,
     strategyName: params.strategyName,
     exchangeName: params.exchangeName,
     currentPrice: params.currentPrice,
     activePositionCount,
-    comment,
+    rejectionId: rejectionResult.id,
+    rejectionNote: rejectionResult.note,
     timestamp,
     backtest,
 });
@@ -7019,11 +7045,13 @@ const performance_columns = [
  * - Signal identification (symbol, strategy name, signal ID, position)
  * - Exchange information (exchange name, active position count)
  * - Price data (open price, take profit, stop loss, current price)
- * - Rejection details (rejection reason/comment, timestamp)
+ * - Rejection details (rejection ID, rejection reason, timestamp)
  *
  * @remarks
  * This configuration helps analyze when and why the risk management system rejected signals.
- * The "note" column visibility is controlled by {@link GLOBAL_CONFIG.CC_REPORT_SHOW_SIGNAL_NOTE}.
+ * - The "note" column (signal note) visibility is controlled by {@link GLOBAL_CONFIG.CC_REPORT_SHOW_SIGNAL_NOTE}.
+ * - The "rejectionNote" column (rejection reason) is always visible as it contains critical risk information.
+ * - The "rejectionId" can be used to correlate rejections with signal IDs for debugging.
  * Useful for tuning risk parameters and understanding risk control effectiveness.
  *
  * @example
@@ -7036,7 +7064,7 @@ const performance_columns = [
  *
  * // Or customize to focus on rejection reasons
  * const customColumns = risk_columns.filter(col =>
- *   ["symbol", "strategyName", "comment", "activePositionCount", "timestamp"].includes(col.key)
+ *   ["symbol", "strategyName", "rejectionId", "rejectionNote", "activePositionCount", "timestamp"].includes(col.key)
  * );
  * await service.getReport("BTCUSDT", "my-strategy", customColumns);
  * ```
@@ -7064,18 +7092,18 @@ const risk_columns = [
         format: (data) => data.pendingSignal.id || "N/A",
         isVisible: () => true,
     },
-    {
-        key: "position",
-        label: "Position",
-        format: (data) => data.pendingSignal.position.toUpperCase(),
-        isVisible: () => true,
-    },
     {
         key: "note",
         label: "Note",
         format: (data) => toPlainString(data.pendingSignal.note ?? "N/A"),
         isVisible: () => GLOBAL_CONFIG.CC_REPORT_SHOW_SIGNAL_NOTE,
     },
+    {
+        key: "position",
+        label: "Position",
+        format: (data) => data.pendingSignal.position.toUpperCase(),
+        isVisible: () => true,
+    },
     {
         key: "exchangeName",
         label: "Exchange",
@@ -7119,9 +7147,15 @@ const risk_columns = [
         isVisible: () => true,
     },
     {
-        key: "comment",
-        label: "Reason",
-        format: (data) => data.comment,
+        key: "rejectionId",
+        label: "ID",
+        format: (data) => data.rejectionId ?? "N/A",
+        isVisible: () => true,
+    },
+    {
+        key: "rejectionNote",
+        label: "Rejection Reason",
+        format: (data) => data.rejectionNote,
         isVisible: () => true,
     },
     {

package/build/index.mjs

@@ -1,6 +1,6 @@
 import { createActivator } from 'di-kit';
 import { scoped } from 'di-scoped';
-import { errorData, getErrorMessage, sleep, memoize, makeExtendable, singleshot, not, trycatch, retry, Subject, randomString, ToolRegistry, isObject, and, resolveDocuments, str, iterateDocuments, distinctDocuments, queued, singlerun } from 'functools-kit';
+import { errorData, getErrorMessage, sleep, memoize, makeExtendable, singleshot, not, trycatch, retry, Subject, randomString, isObject, ToolRegistry, and, resolveDocuments, str, iterateDocuments, distinctDocuments, queued, singlerun } from 'functools-kit';
 import fs, { mkdir, writeFile } from 'fs/promises';
 import path, { join } from 'path';
 import crypto from 'crypto';
@@ -4173,17 +4173,29 @@ class SizingConnectionService {
     }
 }
 
+/**
+ * Retrieves a value from an object using a given path.
+ *
+ * @param object - The object from which to retrieve the value.
+ * @param path - The path to the desired value, either as an array or dot-separated string.
+ * @returns - The value at the specified path, or undefined if it does not exist.
+ */
+const get = (object, path) => {
+    const pathArray = Array.isArray(path) ? path : path.split('.').filter((key) => key);
+    const pathArrayFlat = pathArray.flatMap((part) => typeof part === 'string' ? part.split('.') : part);
+    return pathArrayFlat.reduce((obj, key) => obj && obj[key], object);
+};
+
 /** Symbol indicating that positions need to be fetched from persistence */
 const POSITION_NEED_FETCH = Symbol("risk-need-fetch");
 /** Key generator for active position map */
 const GET_KEY_FN = (strategyName, symbol) => `${strategyName}:${symbol}`;
 /** Wrapper to execute risk validation function with error handling */
-const DO_VALIDATION_FN = trycatch(async (validation, params) => {
-    await validation(params);
-    return true;
-}, {
-    defaultValue: false,
-    fallback: (error) => {
+const DO_VALIDATION_FN = async (validation, params) => {
+    try {
+        return await validation(params);
+    }
+    catch (error) {
         const message = "ClientRisk exception thrown";
         const payload = {
             error: errorData(error),
@@ -4192,8 +4204,9 @@ const DO_VALIDATION_FN = trycatch(async (validation, params) => {
         backtest$1.loggerService.warn(message, payload);
         console.warn(message, payload);
         validationSubject.next(error);
-    },
-});
+        return payload.message;
+    }
+};
 /**
  * Initializes active positions by reading from persistence.
  * Uses singleshot pattern to ensure it only runs once.
@@ -4202,7 +4215,9 @@ const DO_VALIDATION_FN = trycatch(async (validation, params) => {
  * In backtest mode, initializes with empty Map. In live mode, reads from persist storage.
  */
 const WAIT_FOR_INIT_FN$1 = async (self) => {
-    self.params.logger.debug("ClientRisk waitForInit", { backtest: self.params.backtest });
+    self.params.logger.debug("ClientRisk waitForInit", {
+        backtest: self.params.backtest,
+    });
     if (self.params.backtest) {
         self._activePositions = new Map();
         return;
@@ -4265,26 +4280,36 @@ class ClientRisk {
                 activePositionCount: riskMap.size,
                 activePositions: Array.from(riskMap.values()),
             };
-            // Execute custom validations
-            let isValid = true;
-            let rejectionNote = "N/A";
+            let rejectionResult = null;
             if (this.params.validations) {
                 for (const validation of this.params.validations) {
-                    if (not(await DO_VALIDATION_FN(typeof validation === "function"
-                        ? validation
-                        : validation.validate, payload))) {
-                        isValid = false;
-                        // Capture note from validation if available
-                        if (typeof validation !== "function" && validation.note) {
-                            rejectionNote = validation.note;
-                        }
+                    const rejection = await DO_VALIDATION_FN(typeof validation === "function" ? validation : validation.validate, payload);
+                    if (!rejection) {
+                        continue;
+                    }
+                    if (typeof rejection === "string") {
+                        rejectionResult = {
+                            id: null,
+                            note: rejection
+                                ? rejection
+                                : "note" in validation
+                                    ? validation.note
+                                    : "Validation failed",
+                        };
+                        break;
+                    }
+                    if (isObject(rejection)) {
+                        rejectionResult = {
+                            id: get(rejection, "id") || null,
+                            note: get(rejection, "note") || "Validation rejected the signal",
+                        };
                         break;
                     }
                 }
             }
-            if (!isValid) {
+            if (rejectionResult) {
                 // Call params.onRejected for riskSubject emission
-                await this.params.onRejected(params.symbol, params, riskMap.size, rejectionNote, Date.now(), this.params.backtest);
+                await this.params.onRejected(params.symbol, params, riskMap.size, rejectionResult, params.timestamp, this.params.backtest);
                 // Call schema callbacks.onRejected if defined
                 if (this.params.callbacks?.onRejected) {
                     this.params.callbacks.onRejected(params.symbol, params);
@@ -4363,18 +4388,19 @@ class ClientRisk {
  * @param symbol - Trading pair symbol
  * @param params - Risk check arguments
  * @param activePositionCount - Number of active positions at rejection time
- * @param comment - Rejection reason from validation note or "N/A"
+ * @param rejectionResult - Rejection result with id and note
  * @param timestamp - Event timestamp in milliseconds
  * @param backtest - True if backtest mode, false if live mode
  */
-const COMMIT_REJECTION_FN = async (symbol, params, activePositionCount, comment, timestamp, backtest) => await riskSubject.next({
+const COMMIT_REJECTION_FN = async (symbol, params, activePositionCount, rejectionResult, timestamp, backtest) => await riskSubject.next({
     symbol,
     pendingSignal: params.pendingSignal,
     strategyName: params.strategyName,
     exchangeName: params.exchangeName,
     currentPrice: params.currentPrice,
     activePositionCount,
-    comment,
+    rejectionId: rejectionResult.id,
+    rejectionNote: rejectionResult.note,
     timestamp,
     backtest,
 });
@@ -7017,11 +7043,13 @@ const performance_columns = [
  * - Signal identification (symbol, strategy name, signal ID, position)
  * - Exchange information (exchange name, active position count)
  * - Price data (open price, take profit, stop loss, current price)
- * - Rejection details (rejection reason/comment, timestamp)
+ * - Rejection details (rejection ID, rejection reason, timestamp)
  *
  * @remarks
  * This configuration helps analyze when and why the risk management system rejected signals.
- * The "note" column visibility is controlled by {@link GLOBAL_CONFIG.CC_REPORT_SHOW_SIGNAL_NOTE}.
+ * - The "note" column (signal note) visibility is controlled by {@link GLOBAL_CONFIG.CC_REPORT_SHOW_SIGNAL_NOTE}.
+ * - The "rejectionNote" column (rejection reason) is always visible as it contains critical risk information.
+ * - The "rejectionId" can be used to correlate rejections with signal IDs for debugging.
  * Useful for tuning risk parameters and understanding risk control effectiveness.
  *
  * @example
@@ -7034,7 +7062,7 @@ const performance_columns = [
  *
  * // Or customize to focus on rejection reasons
  * const customColumns = risk_columns.filter(col =>
- *   ["symbol", "strategyName", "comment", "activePositionCount", "timestamp"].includes(col.key)
+ *   ["symbol", "strategyName", "rejectionId", "rejectionNote", "activePositionCount", "timestamp"].includes(col.key)
  * );
  * await service.getReport("BTCUSDT", "my-strategy", customColumns);
  * ```
@@ -7062,18 +7090,18 @@ const risk_columns = [
         format: (data) => data.pendingSignal.id || "N/A",
         isVisible: () => true,
     },
-    {
-        key: "position",
-        label: "Position",
-        format: (data) => data.pendingSignal.position.toUpperCase(),
-        isVisible: () => true,
-    },
     {
         key: "note",
         label: "Note",
         format: (data) => toPlainString(data.pendingSignal.note ?? "N/A"),
         isVisible: () => GLOBAL_CONFIG.CC_REPORT_SHOW_SIGNAL_NOTE,
     },
+    {
+        key: "position",
+        label: "Position",
+        format: (data) => data.pendingSignal.position.toUpperCase(),
+        isVisible: () => true,
+    },
     {
         key: "exchangeName",
         label: "Exchange",
@@ -7117,9 +7145,15 @@ const risk_columns = [
         isVisible: () => true,
     },
     {
-        key: "comment",
-        label: "Reason",
-        format: (data) => data.comment,
+        key: "rejectionId",
+        label: "ID",
+        format: (data) => data.rejectionId ?? "N/A",
+        isVisible: () => true,
+    },
+    {
+        key: "rejectionNote",
+        label: "Rejection Reason",
+        format: (data) => data.rejectionNote,
         isVisible: () => true,
     },
     {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "backtest-kit",
-  "version": "1.5.44",
+  "version": "1.5.46",
   "description": "A TypeScript library for trading system backtest",
   "author": {
     "name": "Petr Tripolsky",

package/types.d.ts

@@ -759,6 +759,11 @@ declare const MethodContextService: (new () => {
     };
 }, "prototype"> & di_scoped.IScopedClassRun<[context: IMethodContext]>;
 
+/**
+ * Risk rejection result type.
+ * Can be void, null, or an IRiskRejectionResult object.
+ */
+type RiskRejection = void | IRiskRejectionResult | string | null;
 /**
  * Risk check arguments for evaluating whether to allow opening a new position.
  * Called BEFORE signal creation to validate if conditions allow new signals.
@@ -812,12 +817,23 @@ interface IRiskValidationPayload extends IRiskCheckArgs {
     /** List of currently active positions across all strategies */
     activePositions: IRiskActivePosition[];
 }
+/**
+ * Risk validation rejection result.
+ * Returned when validation fails, contains debugging information.
+ */
+interface IRiskRejectionResult {
+    /** Unique identifier for this rejection instance */
+    id: string | null;
+    /** Human-readable reason for rejection */
+    note: string;
+}
 /**
  * Risk validation function type.
- * Validates risk parameters and throws error if validation fails.
+ * Returns null/void if validation passes, IRiskRejectionResult if validation fails.
+ * Can also throw error which will be caught and converted to IRiskRejectionResult.
  */
 interface IRiskValidationFn {
-    (payload: IRiskValidationPayload): void | Promise<void>;
+    (payload: IRiskValidationPayload): RiskRejection | Promise<RiskRejection>;
 }
 /**
  * Risk validation configuration.
@@ -865,11 +881,11 @@ interface IRiskParams extends IRiskSchema {
      * @param symbol - Trading pair symbol
      * @param params - Risk check arguments
      * @param activePositionCount - Number of active positions at rejection time
-     * @param comment - Rejection reason from validation note or "N/A"
+     * @param rejectionResult - Rejection result with id and note
      * @param timestamp - Event timestamp in milliseconds
      * @param backtest - True if backtest mode, false if live mode
      */
-    onRejected: (symbol: string, params: IRiskCheckArgs, activePositionCount: number, comment: string, timestamp: number, backtest: boolean) => void | Promise<void>;
+    onRejected: (symbol: string, params: IRiskCheckArgs, activePositionCount: number, rejectionResult: IRiskRejectionResult, timestamp: number, backtest: boolean) => void | Promise<void>;
 }
 /**
  * Risk interface implemented by ClientRisk.
@@ -3124,16 +3140,22 @@ interface RiskContract {
      */
     activePositionCount: number;
     /**
-     * Comment describing why the signal was rejected.
-     * Captured from IRiskValidation.note or "N/A" if not provided.
+     * Unique identifier for this rejection instance.
+     * Generated by ClientRisk for tracking and debugging purposes.
+     * Null if validation threw exception without custom ID.
+     */
+    rejectionId: string | null;
+    /**
+     * Human-readable reason why the signal was rejected.
+     * Captured from IRiskValidation.note or error message.
      *
      * @example
      * ```typescript
-     * console.log(`Rejection reason: ${event.comment}`);
+     * console.log(`Rejection reason: ${event.rejectionNote}`);
      * // Output: "Rejection reason: Max 3 positions allowed"
      * ```
      */
-    comment: string;
+    rejectionNote: string;
     /**
      * Event timestamp in milliseconds since Unix epoch.
      * Represents when the signal was rejected.
@@ -4540,8 +4562,10 @@ interface RiskEvent {
     currentPrice: number;
     /** Number of active positions at rejection time */
     activePositionCount: number;
+    /** Unique identifier for this rejection instance (null if validation threw exception without custom ID) */
+    rejectionId: string | null;
     /** Rejection reason from validation note */
-    comment: string;
+    rejectionNote: string;
     /** Whether this event is from backtest mode (true) or live mode (false) */
     backtest: boolean;
 }