@bsb/base 9.0.0

package/lib/base/BSBServiceClient.d.ts

@@ -0,0 +1,135 @@
+/**
+ * BSB (Better-Service-Base) is an event-bus based microservice framework.
+ * Copyright (C) 2016 - 2025 BetterCorp (PTY) Ltd
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published
+ * by the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * Alternatively, you may obtain a commercial license for this program.
+ * The commercial license allows you to use the Program in a closed-source manner,
+ * including the right to create derivative works that are not subject to the terms
+ * of the AGPL.
+ *
+ * To obtain a commercial license, please contact the copyright holders at
+ * https://www.bettercorp.dev. The terms and conditions of the commercial license
+ * will be provided upon request.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <https://www.gnu.org/licenses/>.
+ */
+import { BSBEventSchemas, Observable, ServiceClientEventSchemas } from "../interfaces";
+import { BSBService, BSBServiceClientDefinition } from "./BSBService";
+import { PluginEvents } from "./PluginEvents";
+/**
+ * @hidden
+ * ONLY USE THIS IF YOU NEED SPECIFIC CLIENT LOGIC, OTHERWISE USE ServiceClient
+ */
+/**
+ * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/BSBServiceClient.html | API: BSBServiceClient}
+ */
+export declare abstract class BSBServiceClient<Service extends BSBService<any, any> = BSBService<any, BSBEventSchemas>> {
+    readonly events: PluginEvents<ServiceClientEventSchemas<BSBEventSchemas>>;
+    constructor(context: BSBService);
+    abstract readonly pluginName: string;
+    abstract readonly initBeforePlugins?: Array<string>;
+    abstract readonly initAfterPlugins?: Array<string>;
+    abstract readonly runBeforePlugins?: Array<string>;
+    abstract readonly runAfterPlugins?: Array<string>;
+    abstract dispose?(): void;
+    /**
+     * Init
+     * Optional function to be called when the client is being initialized
+     *
+     * @remarks
+     * **v9 BREAKING CHANGE**: Now requires Observable instead of DTrace.
+     *
+     * @param obs - Observable context with logging, metrics, and trace information
+     */
+    abstract init?(obs: Observable): Promise<void>;
+    /**
+     * Run
+     * Optional function to be called when the client is being run
+     *
+     * @remarks
+     * **v9 BREAKING CHANGE**: Now requires Observable instead of DTrace.
+     *
+     * @param obs - Observable context with logging, metrics, and trace information
+     */
+    abstract run?(obs: Observable): Promise<void>;
+}
+/**
+ * Instantiates a link to a Service Plugin.
+ *
+ * Create a new ServiceClient based on a plugin class/definition and then use the events from that plugin.
+ *
+ * @example
+ * ```typescript
+ * // Example Service Plugin (just an example, not a real plugin):
+ *
+ * import { Plugin as Service1 } from "./myplugin";
+ *
+ * export class Plugin
+ * extends BSBService<null, Events> {
+ *  private service1: ServiceClient<Service1>;
+ *
+ *  constructor(config: BSBServiceConstructor) {
+ *    super(config);
+ *    this.service1 = new ServiceClient(Service1, this);
+ *  }
+ *
+ *  public async init(trace: DTrace) {
+ *    this.events.onReturnableEvent("calculate", trace, async (iTrace: DTrace, a: number, b: number) => {
+ *      this.log.info(iTrace, "Calculating {a} * {b}", { a, b });
+ *      return a * b;
+ *    });
+ *  }
+ * }
+ * ```
+ *
+ * @group Services
+ * @category Plugins
+ */
+export declare class ServiceClient<Service extends BSBService<any, TEventSchemas>, TEventSchemas extends BSBEventSchemas = any, ServiceT extends {
+    PLUGIN_CLIENT: BSBServiceClientDefinition;
+} = any> extends BSBServiceClient<Service> {
+    /**
+     * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/ServiceClient.html | API: ServiceClient}
+     */
+    readonly pluginName: string;
+    readonly initBeforePlugins?: Array<string>;
+    readonly initAfterPlugins?: Array<string>;
+    readonly runBeforePlugins?: Array<string>;
+    readonly runAfterPlugins?: Array<string>;
+    dispose?(): void;
+    /**
+     * Init (v9: Observable only)
+     */
+    init?(obs: Observable): Promise<void>;
+    /**
+     * Run (v9: Observable only)
+     */
+    run?(obs: Observable): Promise<void>;
+    events: PluginEvents<ServiceClientEventSchemas<TEventSchemas>>;
+    constructor(service: ServiceT, context: BSBService);
+}
+/**
+ * @hidden
+ * DO NOT REFERENCE/USE THIS CLASS - IT IS AN INTERNALLY REFERENCED CLASS
+ */
+export declare class BSBServiceClientRef extends BSBServiceClient<any> {
+    pluginName: string;
+    initBeforePlugins?: string[] | undefined;
+    initAfterPlugins?: string[] | undefined;
+    runBeforePlugins?: string[] | undefined;
+    runAfterPlugins?: string[] | undefined;
+    dispose?(): void;
+    init?(obs: Observable): Promise<void>;
+    run?(obs: Observable): Promise<void>;
+}

package/lib/base/BSBServiceClient.js

@@ -0,0 +1,130 @@
+"use strict";
+/**
+ * BSB (Better-Service-Base) is an event-bus based microservice framework.
+ * Copyright (C) 2016 - 2025 BetterCorp (PTY) Ltd
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published
+ * by the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * Alternatively, you may obtain a commercial license for this program.
+ * The commercial license allows you to use the Program in a closed-source manner,
+ * including the right to create derivative works that are not subject to the terms
+ * of the AGPL.
+ *
+ * To obtain a commercial license, please contact the copyright holders at
+ * https://www.bettercorp.dev. The terms and conditions of the commercial license
+ * will be provided upon request.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <https://www.gnu.org/licenses/>.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BSBServiceClientRef = exports.ServiceClient = exports.BSBServiceClient = void 0;
+const interfaces_1 = require("../interfaces");
+const errorMessages_1 = require("./errorMessages");
+const tools_1 = require("./tools");
+/**
+ * @hidden
+ */
+function internalTrace(span) {
+    return (0, interfaces_1.createFakeDTrace)("base/BSBServiceClient", span);
+}
+/**
+ * @hidden
+ * ONLY USE THIS IF YOU NEED SPECIFIC CLIENT LOGIC, OTHERWISE USE ServiceClient
+ */
+/**
+ * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/BSBServiceClient.html | API: BSBServiceClient}
+ */
+class BSBServiceClient {
+    constructor(context) {
+        context._clients.push(this);
+    }
+}
+exports.BSBServiceClient = BSBServiceClient;
+/**
+ * Instantiates a link to a Service Plugin.
+ *
+ * Create a new ServiceClient based on a plugin class/definition and then use the events from that plugin.
+ *
+ * @example
+ * ```typescript
+ * // Example Service Plugin (just an example, not a real plugin):
+ *
+ * import { Plugin as Service1 } from "./myplugin";
+ *
+ * export class Plugin
+ * extends BSBService<null, Events> {
+ *  private service1: ServiceClient<Service1>;
+ *
+ *  constructor(config: BSBServiceConstructor) {
+ *    super(config);
+ *    this.service1 = new ServiceClient(Service1, this);
+ *  }
+ *
+ *  public async init(trace: DTrace) {
+ *    this.events.onReturnableEvent("calculate", trace, async (iTrace: DTrace, a: number, b: number) => {
+ *      this.log.info(iTrace, "Calculating {a} * {b}", { a, b });
+ *      return a * b;
+ *    });
+ *  }
+ * }
+ * ```
+ *
+ * @group Services
+ * @category Plugins
+ */
+class ServiceClient extends BSBServiceClient {
+    /**
+     * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/ServiceClient.html | API: ServiceClient}
+     */
+    pluginName = "{UNSET SERVICE CLIENT PLUGIN NAME}";
+    initBeforePlugins;
+    initAfterPlugins;
+    runBeforePlugins;
+    runAfterPlugins;
+    constructor(service, context) {
+        super(context);
+        if (!tools_1.Tools.isObject(service.PLUGIN_CLIENT)) {
+            throw new errorMessages_1.BSBError(internalTrace("ServiceClient"), "Plugin client is not defined in the service!");
+        }
+        if (!tools_1.Tools.isString(service.PLUGIN_CLIENT.name)) {
+            throw new errorMessages_1.BSBError(internalTrace("ServiceClient"), "Plugin client name is not defined in the service!");
+        }
+        this.pluginName = service.PLUGIN_CLIENT.name;
+        this.initBeforePlugins = service.PLUGIN_CLIENT.initBeforePlugins;
+        this.initAfterPlugins = service.PLUGIN_CLIENT.initAfterPlugins;
+        this.runBeforePlugins = service.PLUGIN_CLIENT.runBeforePlugins;
+        this.runAfterPlugins = service.PLUGIN_CLIENT.runAfterPlugins;
+    }
+}
+exports.ServiceClient = ServiceClient;
+/**
+ * @hidden
+ * DO NOT REFERENCE/USE THIS CLASS - IT IS AN INTERNALLY REFERENCED CLASS
+ */
+class BSBServiceClientRef extends BSBServiceClient {
+    pluginName = "";
+    initBeforePlugins;
+    initAfterPlugins;
+    runBeforePlugins;
+    runAfterPlugins;
+    dispose() {
+        throw new Error("Method not implemented.");
+    }
+    init(obs) {
+        throw new Error("Method not implemented.");
+    }
+    run(obs) {
+        throw new Error("Method not implemented.");
+    }
+}
+exports.BSBServiceClientRef = BSBServiceClientRef;
+//# sourceMappingURL=BSBServiceClient.js.map

package/lib/base/BSBServiceClient.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BSBServiceClient.js","sourceRoot":"","sources":["../../src/base/BSBServiceClient.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;;;AAEH,8CAMuB;AAEvB,mDAA2C;AAE3C,mCAAgC;AAEhC;;GAEG;AACH,SAAS,aAAa,CAAC,IAAY;IACjC,OAAO,IAAA,6BAAgB,EAAC,uBAAuB,EAAE,IAAI,CAAC,CAAC;AACzD,CAAC;AAED;;;GAGG;AACH;;GAEG;AACH,MAAsB,gBAAgB;IAKpC,YAAY,OAAmB;QAC7B,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC9B,CAAC;CA+BF;AAtCD,4CAsCC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAa,aAKX,SAAQ,gBAAyB;IACjC;;OAEG;IACa,UAAU,GAAW,oCAAoC,CAAC;IAC1D,iBAAiB,CAAiB;IAClC,gBAAgB,CAAiB;IACjC,gBAAgB,CAAiB;IACjC,eAAe,CAAiB;IAgBhD,YAAY,OAAiB,EAAE,OAAmB;QAChD,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,aAAK,CAAC,QAAQ,CAAC,OAAO,CAAC,aAAa,CAAC,EAAE,CAAC;YAC3C,MAAM,IAAI,wBAAQ,CAAC,aAAa,CAAC,eAAe,CAAC,EAAE,8CAA8C,CAAC,CAAC;QACrG,CAAC;QACD,IAAI,CAAC,aAAK,CAAC,QAAQ,CAAC,OAAO,CAAC,aAAa,CAAC,IAAI,CAAC,EAAE,CAAC;YAChD,MAAM,IAAI,wBAAQ,CAAC,aAAa,CAAC,eAAe,CAAC,EAAE,mDAAmD,CAAC,CAAC;QAC1G,CAAC;QACD,IAAI,CAAC,UAAU,GAAG,OAAO,CAAC,aAAa,CAAC,IAAI,CAAC;QAC7C,IAAI,CAAC,iBAAiB,GAAG,OAAO,CAAC,aAAa,CAAC,iBAAiB,CAAC;QACjE,IAAI,CAAC,gBAAgB,GAAG,OAAO,CAAC,aAAa,CAAC,gBAAgB,CAAC;QAC/D,IAAI,CAAC,gBAAgB,GAAG,OAAO,CAAC,aAAa,CAAC,gBAAgB,CAAC;QAC/D,IAAI,CAAC,eAAe,GAAG,OAAO,CAAC,aAAa,CAAC,eAAe,CAAC;IAC/D,CAAC;CACF;AA3CD,sCA2CC;AAED;;;GAGG;AACH,MAAa,mBACX,SAAQ,gBAAqB;IACtB,UAAU,GAAW,EAAE,CAAC;IACxB,iBAAiB,CAAwB;IACzC,gBAAgB,CAAwB;IACxC,gBAAgB,CAAwB;IACxC,eAAe,CAAwB;IAEvC,OAAO;QACZ,MAAM,IAAI,KAAK,CAAC,yBAAyB,CAAC,CAAC;IAC7C,CAAC;IAEM,IAAI,CAAE,GAAe;QAC1B,MAAM,IAAI,KAAK,CAAC,yBAAyB,CAAC,CAAC;IAC7C,CAAC;IAEM,GAAG,CAAE,GAAe;QACzB,MAAM,IAAI,KAAK,CAAC,yBAAyB,CAAC,CAAC;IAC7C,CAAC;CACF;AAnBD,kDAmBC"}

package/lib/base/EventValidator.d.ts

@@ -0,0 +1,137 @@
+/**
+ * BSB (Better-Service-Base) is an event-bus based microservice framework.
+ * Copyright (C) 2016 - 2025 BetterCorp (PTY) Ltd
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published
+ * by the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * Alternatively, you may obtain a commercial license, please contact the copyright holders at
+ * https://www.bettercorp.dev. The terms and conditions of the commercial license
+ * will be provided upon request.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <https://www.gnu.org/licenses/>.
+ */
+import { z } from "zod";
+import { IPluginLogging, DTrace, BSBType } from "../interfaces";
+export interface ValidationResult<T = any> {
+    success: boolean;
+    data?: T;
+    error?: Error;
+}
+export interface EventValidationConfig {
+    enabled?: boolean;
+    logValidationErrors?: boolean;
+    throwOnValidationFailure?: boolean;
+    maxRetries?: number;
+    retryDelay?: number;
+    performanceThreshold?: number;
+}
+/**
+ * Utility class for validating event data using Zod schemas.
+ * Provides performance monitoring and configurable validation behavior.
+ * @group Validation
+ * @category Tools
+ * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/EventValidator.html | API: EventValidator}
+ */
+export declare class EventValidator {
+    private config;
+    private logger?;
+    /**
+     * Create a new EventValidator instance.
+     * @param config - Validation configuration options
+     * @param logger - Optional logger for error reporting
+     * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/EventValidator.html#constructor | API: EventValidator#constructor}
+     */
+    constructor(config?: Partial<EventValidationConfig>, logger?: IPluginLogging);
+    /**
+     * Update validation configuration at runtime.
+     * @param config - New configuration options to merge
+     * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/EventValidator.html#updateConfig | API: EventValidator#updateConfig}
+     */
+    updateConfig(config: Partial<EventValidationConfig>): void;
+    /**
+     * Validate input data for an event.
+     * @param eventName - Name of the event being validated
+     * @param data - Data to validate
+     * @param schema - BSBType or Zod schema to validate against
+     * @param trace - Trace for logging context
+     * @param eventConfig - Override configuration for this validation
+     * @returns Validation result with parsed data or error
+     * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/EventValidator.html#validateInput | API: EventValidator#validateInput}
+     */
+    validateInput<T = unknown>(eventName: string, data: unknown, schema: BSBType | z.ZodSchema<T>, trace: DTrace, eventConfig?: Partial<EventValidationConfig>): ValidationResult<T>;
+    /**
+     * Validate output/return data for an event.
+     * @param eventName - Name of the event being validated
+     * @param data - Data to validate
+     * @param schema - BSBType or Zod schema to validate against
+     * @param trace - Trace for logging context
+     * @param eventConfig - Override configuration for this validation
+     * @returns Validation result with parsed data or error
+     * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/EventValidator.html#validateOutput | API: EventValidator#validateOutput}
+     */
+    validateOutput<T = unknown>(eventName: string, data: unknown, schema: BSBType | z.ZodSchema<T>, trace: DTrace, eventConfig?: Partial<EventValidationConfig>): ValidationResult<T>;
+    /**
+     * Check if a schema is a BSBType or a Zod schema.
+     * @param schema - Schema to check
+     * @returns True if schema is a BSBType
+     * @private
+     */
+    private isBSBType;
+    /**
+     * Validate event data using schemas from a validation schema map.
+     * @param eventName - Name of the event to validate
+     * @param data - Data to validate
+     * @param schemas - Map of event validation schemas
+     * @param trace - Trace for logging context
+     * @param direction - Whether validating 'input' or 'output' data
+     * @returns Validation result or null if no schema is defined
+     * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/EventValidator.html#validateFromSchemas | API: EventValidator#validateFromSchemas}
+     */
+    validateFromSchemas<T = unknown>(eventName: string, data: unknown, schemas: any, trace: DTrace, direction?: 'input' | 'output'): ValidationResult<T> | null;
+    /**
+     * Check if validation is enabled for the current configuration.
+     * @param eventConfig - Override configuration to check
+     * @returns True if validation is enabled
+     * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/EventValidator.html#isValidationEnabled | API: EventValidator#isValidationEnabled}
+     */
+    isValidationEnabled(eventConfig?: Partial<EventValidationConfig>): boolean;
+    /**
+     * Internal method to perform the actual validation with performance monitoring.
+     */
+    private performValidation;
+}
+/**
+ * Custom error class for validation failures.
+ * @group Validation
+ * @category Errors
+ * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/ValidationError.html | API: ValidationError}
+ */
+export declare class ValidationError extends Error {
+    readonly zodError: z.ZodError<any>;
+    readonly eventName: string;
+    readonly direction: 'input' | 'output';
+    /**
+     * Create a new validation error.
+     * @param message - Error message
+     * @param zodError - The underlying Zod validation error
+     * @param eventName - Name of the event that failed validation
+     * @param direction - Whether the failure was on 'input' or 'output'
+     * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/ValidationError.html#constructor | API: ValidationError#constructor}
+     */
+    constructor(message: string, zodError: z.ZodError<any>, eventName: string, direction: 'input' | 'output');
+    /**
+     * Get a formatted string representation of the validation errors.
+     * @returns Formatted error details
+     * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/ValidationError.html#getFormattedErrors | API: ValidationError#getFormattedErrors}
+     */
+    getFormattedErrors(): string;
+}

package/lib/base/EventValidator.js

@@ -0,0 +1,210 @@
+"use strict";
+/**
+ * BSB (Better-Service-Base) is an event-bus based microservice framework.
+ * Copyright (C) 2016 - 2025 BetterCorp (PTY) Ltd
+ *
+ * This program is free software: you can redistribute it and/or modify
+ * it under the terms of the GNU Affero General Public License as published
+ * by the Free Software Foundation, either version 3 of the License, or
+ * (at your option) any later version.
+ *
+ * Alternatively, you may obtain a commercial license, please contact the copyright holders at
+ * https://www.bettercorp.dev. The terms and conditions of the commercial license
+ * will be provided upon request.
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU Affero General Public License for more details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program. If not, see <https://www.gnu.org/licenses/>.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ValidationError = exports.EventValidator = void 0;
+const interfaces_1 = require("../interfaces");
+const DEFAULT_VALIDATION_CONFIG = {
+    enabled: true,
+    logValidationErrors: true,
+    throwOnValidationFailure: true,
+    maxRetries: 0,
+    retryDelay: 0,
+    performanceThreshold: 100
+};
+/**
+ * Utility class for validating event data using Zod schemas.
+ * Provides performance monitoring and configurable validation behavior.
+ * @group Validation
+ * @category Tools
+ * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/EventValidator.html | API: EventValidator}
+ */
+class EventValidator {
+    config;
+    logger;
+    /**
+     * Create a new EventValidator instance.
+     * @param config - Validation configuration options
+     * @param logger - Optional logger for error reporting
+     * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/EventValidator.html#constructor | API: EventValidator#constructor}
+     */
+    constructor(config = {}, logger) {
+        this.config = { ...DEFAULT_VALIDATION_CONFIG, ...config };
+        this.logger = logger;
+    }
+    /**
+     * Update validation configuration at runtime.
+     * @param config - New configuration options to merge
+     * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/EventValidator.html#updateConfig | API: EventValidator#updateConfig}
+     */
+    updateConfig(config) {
+        this.config = { ...this.config, ...config };
+    }
+    /**
+     * Validate input data for an event.
+     * @param eventName - Name of the event being validated
+     * @param data - Data to validate
+     * @param schema - BSBType or Zod schema to validate against
+     * @param trace - Trace for logging context
+     * @param eventConfig - Override configuration for this validation
+     * @returns Validation result with parsed data or error
+     * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/EventValidator.html#validateInput | API: EventValidator#validateInput}
+     */
+    validateInput(eventName, data, schema, trace, eventConfig) {
+        // Convert BSBType to Zod schema if needed
+        const zodSchema = this.isBSBType(schema) ? (0, interfaces_1.bsbToZod)(schema) : schema;
+        return this.performValidation(eventName, data, zodSchema, trace, 'input', eventConfig);
+    }
+    /**
+     * Validate output/return data for an event.
+     * @param eventName - Name of the event being validated
+     * @param data - Data to validate
+     * @param schema - BSBType or Zod schema to validate against
+     * @param trace - Trace for logging context
+     * @param eventConfig - Override configuration for this validation
+     * @returns Validation result with parsed data or error
+     * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/EventValidator.html#validateOutput | API: EventValidator#validateOutput}
+     */
+    validateOutput(eventName, data, schema, trace, eventConfig) {
+        // Convert BSBType to Zod schema if needed
+        const zodSchema = this.isBSBType(schema) ? (0, interfaces_1.bsbToZod)(schema) : schema;
+        return this.performValidation(eventName, data, zodSchema, trace, 'output', eventConfig);
+    }
+    /**
+     * Check if a schema is a BSBType or a Zod schema.
+     * @param schema - Schema to check
+     * @returns True if schema is a BSBType
+     * @private
+     */
+    isBSBType(schema) {
+        return schema && typeof schema === 'object' && '_bsb' in schema;
+    }
+    /**
+     * Validate event data using schemas from a validation schema map.
+     * @param eventName - Name of the event to validate
+     * @param data - Data to validate
+     * @param schemas - Map of event validation schemas
+     * @param trace - Trace for logging context
+     * @param direction - Whether validating 'input' or 'output' data
+     * @returns Validation result or null if no schema is defined
+     * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/EventValidator.html#validateFromSchemas | API: EventValidator#validateFromSchemas}
+     */
+    validateFromSchemas(eventName, data, schemas, trace, direction = 'input') {
+        const eventSchema = schemas[eventName];
+        if (!eventSchema) {
+            return null; // No validation schema defined for this event
+        }
+        const schema = direction === 'input' ? eventSchema.input : eventSchema.output;
+        if (!schema) {
+            return null; // No schema defined for this direction
+        }
+        return this.performValidation(eventName, data, schema, trace, direction, eventSchema.config);
+    }
+    /**
+     * Check if validation is enabled for the current configuration.
+     * @param eventConfig - Override configuration to check
+     * @returns True if validation is enabled
+     * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/EventValidator.html#isValidationEnabled | API: EventValidator#isValidationEnabled}
+     */
+    isValidationEnabled(eventConfig) {
+        const config = { ...this.config, ...eventConfig };
+        return config.enabled === true;
+    }
+    /**
+     * Internal method to perform the actual validation with performance monitoring.
+     */
+    performValidation(eventName, data, schema, trace, direction, eventConfig) {
+        const config = { ...this.config, ...eventConfig };
+        if (!config.enabled) {
+            return { success: true, data: data };
+        }
+        const startTime = performance.now();
+        try {
+            const parsedData = schema.parse(data);
+            const duration = performance.now() - startTime;
+            // Log performance warning if threshold exceeded
+            if (config.performanceThreshold && duration > config.performanceThreshold) {
+                this.logger?.warn(trace, `Event validation for '${eventName}' ${direction} took ${duration.toFixed(2)}ms (threshold: ${config.performanceThreshold}ms)`);
+            }
+            return {
+                success: true,
+                data: parsedData
+            };
+        }
+        catch (error) {
+            const zodError = error;
+            if (config.logValidationErrors && this.logger) {
+                const errorMsg = `Event validation failed for '${eventName}' ${direction}: ${zodError.message}`;
+                this.logger.error(trace, errorMsg);
+            }
+            if (config.throwOnValidationFailure) {
+                // Throw the original Zod error
+                throw error;
+            }
+            return {
+                success: false,
+                error: error instanceof Error ? error : new Error(String(error))
+            };
+        }
+    }
+}
+exports.EventValidator = EventValidator;
+/**
+ * Custom error class for validation failures.
+ * @group Validation
+ * @category Errors
+ * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/ValidationError.html | API: ValidationError}
+ */
+class ValidationError extends Error {
+    zodError;
+    eventName;
+    direction;
+    /**
+     * Create a new validation error.
+     * @param message - Error message
+     * @param zodError - The underlying Zod validation error
+     * @param eventName - Name of the event that failed validation
+     * @param direction - Whether the failure was on 'input' or 'output'
+     * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/ValidationError.html#constructor | API: ValidationError#constructor}
+     */
+    constructor(message, zodError, eventName, direction) {
+        super(message);
+        this.zodError = zodError;
+        this.eventName = eventName;
+        this.direction = direction;
+        this.name = 'ValidationError';
+        // Maintain proper stack trace for where our error was thrown
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, ValidationError);
+        }
+    }
+    /**
+     * Get a formatted string representation of the validation errors.
+     * @returns Formatted error details
+     * @see {@link https://bsbcode.dev/languages/nodejs/types/classes/ValidationError.html#getFormattedErrors | API: ValidationError#getFormattedErrors}
+     */
+    getFormattedErrors() {
+        return this.zodError.issues.map((err) => `${err.path.join('.')}: ${err.message}`).join('; ');
+    }
+}
+exports.ValidationError = ValidationError;
+//# sourceMappingURL=EventValidator.js.map

package/lib/base/EventValidator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"EventValidator.js","sourceRoot":"","sources":["../../src/base/EventValidator.ts"],"names":[],"mappings":"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"}