backtest-kit 2.0.3 → 2.0.4

package/build/index.cjs

@@ -783,10 +783,14 @@ class ClientExchange {
         // Apply distinct by timestamp to remove duplicates
         const uniqueData = Array.from(new Map(filteredData.map((candle) => [candle.timestamp, candle])).values());
         if (filteredData.length !== uniqueData.length) {
-            this.params.logger.warn(`ClientExchange Removed ${filteredData.length - uniqueData.length} duplicate candles by timestamp`);
+            const msg = `ClientExchange Removed ${filteredData.length - uniqueData.length} duplicate candles by timestamp`;
+            this.params.logger.warn(msg);
+            console.warn(msg);
         }
         if (uniqueData.length < limit) {
-            this.params.logger.warn(`ClientExchange Expected ${limit} candles, got ${uniqueData.length}`);
+            const msg = `ClientExchange Expected ${limit} candles, got ${uniqueData.length}`;
+            this.params.logger.warn(msg);
+            console.warn(msg);
         }
         await CALL_CANDLE_DATA_CALLBACKS_FN(this, symbol, interval, since, limit, uniqueData);
         return uniqueData;
@@ -9896,11 +9900,119 @@ class RiskSchemaService {
     }
 }
 
+/**
+ * List of valid method names allowed in action handlers.
+ * Any public methods not in this list will trigger validation errors.
+ * Private methods (starting with _ or #) are ignored during validation.
+ */
+const VALID_METHOD_NAMES = [
+    "init",
+    "signal",
+    "signalLive",
+    "signalBacktest",
+    "breakevenAvailable",
+    "partialProfitAvailable",
+    "partialLossAvailable",
+    "pingScheduled",
+    "pingActive",
+    "riskRejection",
+    "dispose",
+];
+/**
+ * Validates that all public methods in a class-based action handler are in the allowed list.
+ *
+ * Inspects the class prototype to find all method names and ensures they match
+ * the VALID_METHOD_NAMES list. Private methods (starting with _ or #) are skipped.
+ * Private fields with # are not visible via Object.getOwnPropertyNames() and don't
+ * need validation as they're truly private and inaccessible.
+ *
+ * @param actionName - Name of the action being validated
+ * @param handler - Class constructor for the action handler
+ * @param self - ActionSchemaService instance for logging
+ * @throws Error if any public method is not in VALID_METHOD_NAMES
+ */
+const VALIDATE_CLASS_METHODS = (actionName, handler, self) => {
+    // Get all method names from prototype (for classes)
+    // Note: Private fields with # are not visible via Object.getOwnPropertyNames()
+    // and don't need validation as they're truly private and inaccessible
+    const prototypeProps = Object.getOwnPropertyNames(handler.prototype);
+    for (const methodName of prototypeProps) {
+        // Skip constructor and conventionally private methods (starting with _)
+        if (methodName === "constructor" || methodName.startsWith("_")) {
+            continue;
+        }
+        const descriptor = Object.getOwnPropertyDescriptor(handler.prototype, methodName);
+        const isMethod = descriptor && typeof descriptor.value === "function";
+        if (isMethod && !VALID_METHOD_NAMES.includes(methodName)) {
+            const msg = functoolsKit.str.newline(`ActionSchema ${actionName} contains invalid method "${methodName}". `, `Valid methods are: ${VALID_METHOD_NAMES.join(", ")}`, `If you want to keep this property name use one of these patterns: _${methodName} or #${methodName}`);
+            self.loggerService.log(`actionValidationService exception thrown`, {
+                msg,
+            });
+            throw new Error(msg);
+        }
+    }
+};
+/**
+ * Validates that all public methods in an object-based action handler are in the allowed list.
+ *
+ * Inspects the object's own properties to find all method names and ensures they match
+ * the VALID_METHOD_NAMES list. Private properties (starting with _) are skipped.
+ *
+ * @param actionName - Name of the action being validated
+ * @param handler - Plain object implementing partial IPublicAction interface
+ * @param self - ActionSchemaService instance for logging
+ * @throws Error if any public method is not in VALID_METHOD_NAMES
+ */
+const VALIDATE_OBJECT_METHODS = (actionName, handler, self) => {
+    // For plain objects (Partial<IPublicAction>)
+    const methodNames = Object.keys(handler);
+    for (const methodName of methodNames) {
+        // Skip private properties (starting with _)
+        if (methodName.startsWith("_")) {
+            continue;
+        }
+        if (typeof handler[methodName] === "function" &&
+            !VALID_METHOD_NAMES.includes(methodName)) {
+            const msg = functoolsKit.str.newline(`ActionSchema ${actionName} contains invalid method "${methodName}". `, `Valid methods are: ${VALID_METHOD_NAMES.join(", ")}`, `If you want to keep this property name use one of these patterns: _${methodName} or #${methodName}`);
+            self.loggerService.log(`actionValidationService exception thrown`, {
+                msg,
+            });
+            throw new Error(msg);
+        }
+    }
+};
 /**
  * Service for managing action schema registry.
  *
+ * Manages registration, validation and retrieval of action schemas.
  * Uses ToolRegistry from functools-kit for type-safe schema storage.
- * Action handlers are registered via addAction() and retrieved by name.
+ * Validates that action handlers only contain allowed public methods
+ * from the IPublicAction interface.
+ *
+ * Key features:
+ * - Type-safe action schema registration
+ * - Method name validation for class and object handlers
+ * - Private method support (methods starting with _ or #)
+ * - Schema override capabilities
+ *
+ * @example
+ * ```typescript
+ * // Register a class-based action
+ * actionSchemaService.register("telegram-notifier", {
+ *   actionName: "telegram-notifier",
+ *   handler: TelegramNotifierAction,
+ *   callbacks: { ... }
+ * });
+ *
+ * // Register an object-based action
+ * actionSchemaService.register("logger", {
+ *   actionName: "logger",
+ *   handler: {
+ *     signal: async (event) => { ... },
+ *     dispose: async () => { ... }
+ *   }
+ * });
+ * ```
  */
 class ActionSchemaService {
     constructor() {
@@ -9909,9 +10021,13 @@ class ActionSchemaService {
         /**
          * Registers a new action schema.
          *
-         * @param key - Unique action name
-         * @param value - Action schema configuration
-         * @throws Error if action name already exists
+         * Validates the schema structure and method names before registration.
+         * Throws an error if the action name already exists in the registry.
+         *
+         * @param key - Unique action name identifier
+         * @param value - Action schema configuration with handler and optional callbacks
+         * @throws Error if action name already exists in registry
+         * @throws Error if validation fails (missing required fields, invalid handler, invalid method names)
          */
         this.register = (key, value) => {
             this.loggerService.log(`actionSchemaService register`, { key });
@@ -9923,11 +10039,13 @@ class ActionSchemaService {
          *
          * Performs shallow validation to ensure all required properties exist
          * and have correct types before registration in the registry.
+         * Also validates that all public methods in the handler are allowed.
          *
          * @param actionSchema - Action schema to validate
          * @throws Error if actionName is missing or not a string
-         * @throws Error if handler is missing or not a function
-         * @throws Error if callbacks is not an object
+         * @throws Error if handler is not a function or plain object
+         * @throws Error if handler contains invalid public method names
+         * @throws Error if callbacks is provided but not an object
          */
         this.validateShallow = (actionSchema) => {
             this.loggerService.log(`actionSchemaService validateShallow`, {
@@ -9936,21 +10054,30 @@ class ActionSchemaService {
             if (typeof actionSchema.actionName !== "string") {
                 throw new Error(`action schema validation failed: missing actionName`);
             }
-            if (typeof actionSchema.handler !== "function" && !functoolsKit.isObject(actionSchema.handler)) {
+            if (typeof actionSchema.handler !== "function" &&
+                !functoolsKit.isObject(actionSchema.handler)) {
                 throw new Error(`action schema validation failed: handler is not a function or plain object for actionName=${actionSchema.actionName}`);
             }
-            if (actionSchema.callbacks &&
-                !functoolsKit.isObject(actionSchema.callbacks)) {
+            if (typeof actionSchema.handler === "function" && actionSchema.handler.prototype) {
+                VALIDATE_CLASS_METHODS(actionSchema.actionName, actionSchema.handler, this);
+            }
+            if (typeof actionSchema.handler === "object" && actionSchema.handler !== null) {
+                VALIDATE_OBJECT_METHODS(actionSchema.actionName, actionSchema.handler, this);
+            }
+            if (actionSchema.callbacks && !functoolsKit.isObject(actionSchema.callbacks)) {
                 throw new Error(`action schema validation failed: callbacks is not an object for actionName=${actionSchema.actionName}`);
             }
         };
         /**
          * Overrides an existing action schema with partial updates.
          *
+         * Merges provided partial schema updates with the existing schema.
+         * Useful for modifying handler or callbacks without re-registering the entire schema.
+         *
          * @param key - Action name to override
-         * @param value - Partial schema updates
-         * @returns Updated action schema
-         * @throws Error if action name doesn't exist
+         * @param value - Partial schema updates to merge
+         * @returns Updated action schema after override
+         * @throws Error if action name doesn't exist in registry
          */
         this.override = (key, value) => {
             this.loggerService.log(`actionSchemaService override`, { key });
@@ -9960,9 +10087,12 @@ class ActionSchemaService {
         /**
          * Retrieves an action schema by name.
          *
-         * @param key - Action name
+         * Returns the complete action schema configuration including handler and callbacks.
+         * Used internally by ActionConnectionService to instantiate ClientAction instances.
+         *
+         * @param key - Action name identifier
          * @returns Action schema configuration
-         * @throws Error if action name doesn't exist
+         * @throws Error if action name doesn't exist in registry
          */
         this.get = (key) => {
             this.loggerService.log(`actionSchemaService get`, { key });

package/build/index.mjs

@@ -763,10 +763,14 @@ class ClientExchange {
         // Apply distinct by timestamp to remove duplicates
         const uniqueData = Array.from(new Map(filteredData.map((candle) => [candle.timestamp, candle])).values());
         if (filteredData.length !== uniqueData.length) {
-            this.params.logger.warn(`ClientExchange Removed ${filteredData.length - uniqueData.length} duplicate candles by timestamp`);
+            const msg = `ClientExchange Removed ${filteredData.length - uniqueData.length} duplicate candles by timestamp`;
+            this.params.logger.warn(msg);
+            console.warn(msg);
         }
         if (uniqueData.length < limit) {
-            this.params.logger.warn(`ClientExchange Expected ${limit} candles, got ${uniqueData.length}`);
+            const msg = `ClientExchange Expected ${limit} candles, got ${uniqueData.length}`;
+            this.params.logger.warn(msg);
+            console.warn(msg);
         }
         await CALL_CANDLE_DATA_CALLBACKS_FN(this, symbol, interval, since, limit, uniqueData);
         return uniqueData;
@@ -9876,11 +9880,119 @@ class RiskSchemaService {
     }
 }
 
+/**
+ * List of valid method names allowed in action handlers.
+ * Any public methods not in this list will trigger validation errors.
+ * Private methods (starting with _ or #) are ignored during validation.
+ */
+const VALID_METHOD_NAMES = [
+    "init",
+    "signal",
+    "signalLive",
+    "signalBacktest",
+    "breakevenAvailable",
+    "partialProfitAvailable",
+    "partialLossAvailable",
+    "pingScheduled",
+    "pingActive",
+    "riskRejection",
+    "dispose",
+];
+/**
+ * Validates that all public methods in a class-based action handler are in the allowed list.
+ *
+ * Inspects the class prototype to find all method names and ensures they match
+ * the VALID_METHOD_NAMES list. Private methods (starting with _ or #) are skipped.
+ * Private fields with # are not visible via Object.getOwnPropertyNames() and don't
+ * need validation as they're truly private and inaccessible.
+ *
+ * @param actionName - Name of the action being validated
+ * @param handler - Class constructor for the action handler
+ * @param self - ActionSchemaService instance for logging
+ * @throws Error if any public method is not in VALID_METHOD_NAMES
+ */
+const VALIDATE_CLASS_METHODS = (actionName, handler, self) => {
+    // Get all method names from prototype (for classes)
+    // Note: Private fields with # are not visible via Object.getOwnPropertyNames()
+    // and don't need validation as they're truly private and inaccessible
+    const prototypeProps = Object.getOwnPropertyNames(handler.prototype);
+    for (const methodName of prototypeProps) {
+        // Skip constructor and conventionally private methods (starting with _)
+        if (methodName === "constructor" || methodName.startsWith("_")) {
+            continue;
+        }
+        const descriptor = Object.getOwnPropertyDescriptor(handler.prototype, methodName);
+        const isMethod = descriptor && typeof descriptor.value === "function";
+        if (isMethod && !VALID_METHOD_NAMES.includes(methodName)) {
+            const msg = str.newline(`ActionSchema ${actionName} contains invalid method "${methodName}". `, `Valid methods are: ${VALID_METHOD_NAMES.join(", ")}`, `If you want to keep this property name use one of these patterns: _${methodName} or #${methodName}`);
+            self.loggerService.log(`actionValidationService exception thrown`, {
+                msg,
+            });
+            throw new Error(msg);
+        }
+    }
+};
+/**
+ * Validates that all public methods in an object-based action handler are in the allowed list.
+ *
+ * Inspects the object's own properties to find all method names and ensures they match
+ * the VALID_METHOD_NAMES list. Private properties (starting with _) are skipped.
+ *
+ * @param actionName - Name of the action being validated
+ * @param handler - Plain object implementing partial IPublicAction interface
+ * @param self - ActionSchemaService instance for logging
+ * @throws Error if any public method is not in VALID_METHOD_NAMES
+ */
+const VALIDATE_OBJECT_METHODS = (actionName, handler, self) => {
+    // For plain objects (Partial<IPublicAction>)
+    const methodNames = Object.keys(handler);
+    for (const methodName of methodNames) {
+        // Skip private properties (starting with _)
+        if (methodName.startsWith("_")) {
+            continue;
+        }
+        if (typeof handler[methodName] === "function" &&
+            !VALID_METHOD_NAMES.includes(methodName)) {
+            const msg = str.newline(`ActionSchema ${actionName} contains invalid method "${methodName}". `, `Valid methods are: ${VALID_METHOD_NAMES.join(", ")}`, `If you want to keep this property name use one of these patterns: _${methodName} or #${methodName}`);
+            self.loggerService.log(`actionValidationService exception thrown`, {
+                msg,
+            });
+            throw new Error(msg);
+        }
+    }
+};
 /**
  * Service for managing action schema registry.
  *
+ * Manages registration, validation and retrieval of action schemas.
  * Uses ToolRegistry from functools-kit for type-safe schema storage.
- * Action handlers are registered via addAction() and retrieved by name.
+ * Validates that action handlers only contain allowed public methods
+ * from the IPublicAction interface.
+ *
+ * Key features:
+ * - Type-safe action schema registration
+ * - Method name validation for class and object handlers
+ * - Private method support (methods starting with _ or #)
+ * - Schema override capabilities
+ *
+ * @example
+ * ```typescript
+ * // Register a class-based action
+ * actionSchemaService.register("telegram-notifier", {
+ *   actionName: "telegram-notifier",
+ *   handler: TelegramNotifierAction,
+ *   callbacks: { ... }
+ * });
+ *
+ * // Register an object-based action
+ * actionSchemaService.register("logger", {
+ *   actionName: "logger",
+ *   handler: {
+ *     signal: async (event) => { ... },
+ *     dispose: async () => { ... }
+ *   }
+ * });
+ * ```
  */
 class ActionSchemaService {
     constructor() {
@@ -9889,9 +10001,13 @@ class ActionSchemaService {
         /**
          * Registers a new action schema.
          *
-         * @param key - Unique action name
-         * @param value - Action schema configuration
-         * @throws Error if action name already exists
+         * Validates the schema structure and method names before registration.
+         * Throws an error if the action name already exists in the registry.
+         *
+         * @param key - Unique action name identifier
+         * @param value - Action schema configuration with handler and optional callbacks
+         * @throws Error if action name already exists in registry
+         * @throws Error if validation fails (missing required fields, invalid handler, invalid method names)
          */
         this.register = (key, value) => {
             this.loggerService.log(`actionSchemaService register`, { key });
@@ -9903,11 +10019,13 @@ class ActionSchemaService {
          *
          * Performs shallow validation to ensure all required properties exist
          * and have correct types before registration in the registry.
+         * Also validates that all public methods in the handler are allowed.
          *
          * @param actionSchema - Action schema to validate
          * @throws Error if actionName is missing or not a string
-         * @throws Error if handler is missing or not a function
-         * @throws Error if callbacks is not an object
+         * @throws Error if handler is not a function or plain object
+         * @throws Error if handler contains invalid public method names
+         * @throws Error if callbacks is provided but not an object
          */
         this.validateShallow = (actionSchema) => {
             this.loggerService.log(`actionSchemaService validateShallow`, {
@@ -9916,21 +10034,30 @@ class ActionSchemaService {
             if (typeof actionSchema.actionName !== "string") {
                 throw new Error(`action schema validation failed: missing actionName`);
             }
-            if (typeof actionSchema.handler !== "function" && !isObject(actionSchema.handler)) {
+            if (typeof actionSchema.handler !== "function" &&
+                !isObject(actionSchema.handler)) {
                 throw new Error(`action schema validation failed: handler is not a function or plain object for actionName=${actionSchema.actionName}`);
             }
-            if (actionSchema.callbacks &&
-                !isObject(actionSchema.callbacks)) {
+            if (typeof actionSchema.handler === "function" && actionSchema.handler.prototype) {
+                VALIDATE_CLASS_METHODS(actionSchema.actionName, actionSchema.handler, this);
+            }
+            if (typeof actionSchema.handler === "object" && actionSchema.handler !== null) {
+                VALIDATE_OBJECT_METHODS(actionSchema.actionName, actionSchema.handler, this);
+            }
+            if (actionSchema.callbacks && !isObject(actionSchema.callbacks)) {
                 throw new Error(`action schema validation failed: callbacks is not an object for actionName=${actionSchema.actionName}`);
             }
         };
         /**
          * Overrides an existing action schema with partial updates.
          *
+         * Merges provided partial schema updates with the existing schema.
+         * Useful for modifying handler or callbacks without re-registering the entire schema.
+         *
          * @param key - Action name to override
-         * @param value - Partial schema updates
-         * @returns Updated action schema
-         * @throws Error if action name doesn't exist
+         * @param value - Partial schema updates to merge
+         * @returns Updated action schema after override
+         * @throws Error if action name doesn't exist in registry
          */
         this.override = (key, value) => {
             this.loggerService.log(`actionSchemaService override`, { key });
@@ -9940,9 +10067,12 @@ class ActionSchemaService {
         /**
          * Retrieves an action schema by name.
          *
-         * @param key - Action name
+         * Returns the complete action schema configuration including handler and callbacks.
+         * Used internally by ActionConnectionService to instantiate ClientAction instances.
+         *
+         * @param key - Action name identifier
          * @returns Action schema configuration
-         * @throws Error if action name doesn't exist
+         * @throws Error if action name doesn't exist in registry
          */
         this.get = (key) => {
             this.loggerService.log(`actionSchemaService get`, { key });

package/package.json

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

package/types.d.ts

@@ -16569,8 +16569,35 @@ declare class RiskSchemaService {
 /**
  * Service for managing action schema registry.
  *
+ * Manages registration, validation and retrieval of action schemas.
  * Uses ToolRegistry from functools-kit for type-safe schema storage.
- * Action handlers are registered via addAction() and retrieved by name.
+ * Validates that action handlers only contain allowed public methods
+ * from the IPublicAction interface.
+ *
+ * Key features:
+ * - Type-safe action schema registration
+ * - Method name validation for class and object handlers
+ * - Private method support (methods starting with _ or #)
+ * - Schema override capabilities
+ *
+ * @example
+ * ```typescript
+ * // Register a class-based action
+ * actionSchemaService.register("telegram-notifier", {
+ *   actionName: "telegram-notifier",
+ *   handler: TelegramNotifierAction,
+ *   callbacks: { ... }
+ * });
+ *
+ * // Register an object-based action
+ * actionSchemaService.register("logger", {
+ *   actionName: "logger",
+ *   handler: {
+ *     signal: async (event) => { ... },
+ *     dispose: async () => { ... }
+ *   }
+ * });
+ * ```
  */
 declare class ActionSchemaService {
     readonly loggerService: LoggerService;
@@ -16578,9 +16605,13 @@ declare class ActionSchemaService {
     /**
      * Registers a new action schema.
      *
-     * @param key - Unique action name
-     * @param value - Action schema configuration
-     * @throws Error if action name already exists
+     * Validates the schema structure and method names before registration.
+     * Throws an error if the action name already exists in the registry.
+     *
+     * @param key - Unique action name identifier
+     * @param value - Action schema configuration with handler and optional callbacks
+     * @throws Error if action name already exists in registry
+     * @throws Error if validation fails (missing required fields, invalid handler, invalid method names)
      */
     register: (key: ActionName, value: IActionSchema) => void;
     /**
@@ -16588,28 +16619,36 @@ declare class ActionSchemaService {
      *
      * Performs shallow validation to ensure all required properties exist
      * and have correct types before registration in the registry.
+     * Also validates that all public methods in the handler are allowed.
      *
      * @param actionSchema - Action schema to validate
      * @throws Error if actionName is missing or not a string
-     * @throws Error if handler is missing or not a function
-     * @throws Error if callbacks is not an object
+     * @throws Error if handler is not a function or plain object
+     * @throws Error if handler contains invalid public method names
+     * @throws Error if callbacks is provided but not an object
      */
     private validateShallow;
     /**
      * Overrides an existing action schema with partial updates.
      *
+     * Merges provided partial schema updates with the existing schema.
+     * Useful for modifying handler or callbacks without re-registering the entire schema.
+     *
      * @param key - Action name to override
-     * @param value - Partial schema updates
-     * @returns Updated action schema
-     * @throws Error if action name doesn't exist
+     * @param value - Partial schema updates to merge
+     * @returns Updated action schema after override
+     * @throws Error if action name doesn't exist in registry
      */
     override: (key: ActionName, value: Partial<IActionSchema>) => IActionSchema;
     /**
      * Retrieves an action schema by name.
      *
-     * @param key - Action name
+     * Returns the complete action schema configuration including handler and callbacks.
+     * Used internally by ActionConnectionService to instantiate ClientAction instances.
+     *
+     * @param key - Action name identifier
      * @returns Action schema configuration
-     * @throws Error if action name doesn't exist
+     * @throws Error if action name doesn't exist in registry
      */
     get: (key: ActionName) => IActionSchema;
 }