@serve.zone/dcrouter 11.14.0 → 11.16.0

package/dist_ts/config/validator.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Validation result
+ */
+export interface IValidationResult {
+    /**
+     * Whether the validation passed
+     */
+    valid: boolean;
+    /**
+     * Validation errors if any
+     */
+    errors?: string[];
+    /**
+     * Validated configuration (may include defaults)
+     */
+    config?: any;
+}
+/**
+ * Validation schema types
+ */
+export type ValidationSchema = Record<string, {
+    /**
+     * Type of the value
+     */
+    type: 'string' | 'number' | 'boolean' | 'object' | 'array';
+    /**
+     * Whether the field is required
+     */
+    required?: boolean;
+    /**
+     * Default value if not specified
+     */
+    default?: any;
+    /**
+     * Minimum value (for numbers)
+     */
+    min?: number;
+    /**
+     * Maximum value (for numbers)
+     */
+    max?: number;
+    /**
+     * Minimum length (for strings or arrays)
+     */
+    minLength?: number;
+    /**
+     * Maximum length (for strings or arrays)
+     */
+    maxLength?: number;
+    /**
+     * Pattern to match (for strings)
+     */
+    pattern?: RegExp;
+    /**
+     * Allowed values (for strings, numbers)
+     */
+    enum?: any[];
+    /**
+     * Nested schema (for objects)
+     */
+    schema?: ValidationSchema;
+    /**
+     * Item schema (for arrays)
+     */
+    items?: {
+        type: 'string' | 'number' | 'boolean' | 'object';
+        schema?: ValidationSchema;
+    };
+    /**
+     * Custom validation function
+     */
+    validate?: (value: any) => boolean | string;
+}>;
+/**
+ * Configuration validator
+ * Validates configuration objects against schemas and provides default values
+ */
+export declare class ConfigValidator {
+    /**
+     * Validate a configuration object against a schema
+     *
+     * @param config Configuration object to validate
+     * @param schema Validation schema
+     * @returns Validation result
+     */
+    static validate<T>(config: T, schema: ValidationSchema): IValidationResult;
+    /**
+     * Apply defaults to a configuration object based on a schema
+     *
+     * @param config Configuration object to apply defaults to
+     * @param schema Validation schema with defaults
+     * @returns Configuration with defaults applied
+     */
+    static applyDefaults<T>(config: T, schema: ValidationSchema): T;
+    /**
+     * Throw a validation error if the configuration is invalid
+     *
+     * @param config Configuration to validate
+     * @param schema Validation schema
+     * @returns Validated configuration with defaults
+     * @throws ValidationError if validation fails
+     */
+    static validateOrThrow<T>(config: T, schema: ValidationSchema): T;
+}

package/dist_ts/config/validator.js

@@ -0,0 +1,152 @@
+import * as plugins from '../plugins.js';
+import { ValidationError } from '../errors/base.errors.js';
+/**
+ * Configuration validator
+ * Validates configuration objects against schemas and provides default values
+ */
+export class ConfigValidator {
+    /**
+     * Validate a configuration object against a schema
+     *
+     * @param config Configuration object to validate
+     * @param schema Validation schema
+     * @returns Validation result
+     */
+    static validate(config, schema) {
+        const errors = [];
+        const validatedConfig = { ...config };
+        // Validate each field against the schema
+        for (const [key, rules] of Object.entries(schema)) {
+            const value = config[key];
+            // Check if required
+            if (rules.required && (value === undefined || value === null)) {
+                errors.push(`${key} is required`);
+                continue;
+            }
+            // If not present and not required, apply default if available
+            if ((value === undefined || value === null)) {
+                if (rules.default !== undefined) {
+                    validatedConfig[key] = rules.default;
+                }
+                continue;
+            }
+            // Type validation
+            if (value !== undefined && value !== null) {
+                const valueType = Array.isArray(value) ? 'array' : typeof value;
+                if (valueType !== rules.type) {
+                    errors.push(`${key} must be of type ${rules.type}, got ${valueType}`);
+                    continue;
+                }
+                // Type-specific validations
+                switch (rules.type) {
+                    case 'number':
+                        if (rules.min !== undefined && value < rules.min) {
+                            errors.push(`${key} must be at least ${rules.min}`);
+                        }
+                        if (rules.max !== undefined && value > rules.max) {
+                            errors.push(`${key} must be at most ${rules.max}`);
+                        }
+                        break;
+                    case 'string':
+                        if (rules.minLength !== undefined && value.length < rules.minLength) {
+                            errors.push(`${key} must be at least ${rules.minLength} characters`);
+                        }
+                        if (rules.maxLength !== undefined && value.length > rules.maxLength) {
+                            errors.push(`${key} must be at most ${rules.maxLength} characters`);
+                        }
+                        if (rules.pattern && !rules.pattern.test(value)) {
+                            errors.push(`${key} must match pattern ${rules.pattern}`);
+                        }
+                        break;
+                    case 'array':
+                        if (rules.minLength !== undefined && value.length < rules.minLength) {
+                            errors.push(`${key} must have at least ${rules.minLength} items`);
+                        }
+                        if (rules.maxLength !== undefined && value.length > rules.maxLength) {
+                            errors.push(`${key} must have at most ${rules.maxLength} items`);
+                        }
+                        if (rules.items && value.length > 0) {
+                            for (let i = 0; i < value.length; i++) {
+                                const itemType = Array.isArray(value[i]) ? 'array' : typeof value[i];
+                                if (itemType !== rules.items.type) {
+                                    errors.push(`${key}[${i}] must be of type ${rules.items.type}, got ${itemType}`);
+                                }
+                                else if (rules.items.schema && itemType === 'object') {
+                                    const itemResult = this.validate(value[i], rules.items.schema);
+                                    if (!itemResult.valid) {
+                                        errors.push(...itemResult.errors.map(err => `${key}[${i}].${err}`));
+                                    }
+                                }
+                            }
+                        }
+                        break;
+                    case 'object':
+                        if (rules.schema) {
+                            const nestedResult = this.validate(value, rules.schema);
+                            if (!nestedResult.valid) {
+                                errors.push(...nestedResult.errors.map(err => `${key}.${err}`));
+                            }
+                            validatedConfig[key] = nestedResult.config;
+                        }
+                        break;
+                }
+                // Enum validation
+                if (rules.enum && !rules.enum.includes(value)) {
+                    errors.push(`${key} must be one of [${rules.enum.join(', ')}]`);
+                }
+                // Custom validation
+                if (rules.validate) {
+                    const result = rules.validate(value);
+                    if (result !== true) {
+                        errors.push(typeof result === 'string' ? result : `${key} failed custom validation`);
+                    }
+                }
+            }
+        }
+        return {
+            valid: errors.length === 0,
+            errors: errors.length > 0 ? errors : undefined,
+            config: validatedConfig
+        };
+    }
+    /**
+     * Apply defaults to a configuration object based on a schema
+     *
+     * @param config Configuration object to apply defaults to
+     * @param schema Validation schema with defaults
+     * @returns Configuration with defaults applied
+     */
+    static applyDefaults(config, schema) {
+        const result = { ...config };
+        for (const [key, rules] of Object.entries(schema)) {
+            if (result[key] === undefined && rules.default !== undefined) {
+                result[key] = rules.default;
+            }
+            // Apply defaults to nested objects
+            if (result[key] && rules.type === 'object' && rules.schema) {
+                result[key] = this.applyDefaults(result[key], rules.schema);
+            }
+            // Apply defaults to array items
+            if (result[key] && rules.type === 'array' && rules.items && rules.items.schema) {
+                result[key] = result[key].map(item => typeof item === 'object' ? this.applyDefaults(item, rules.items.schema) : item);
+            }
+        }
+        return result;
+    }
+    /**
+     * Throw a validation error if the configuration is invalid
+     *
+     * @param config Configuration to validate
+     * @param schema Validation schema
+     * @returns Validated configuration with defaults
+     * @throws ValidationError if validation fails
+     */
+    static validateOrThrow(config, schema) {
+        const result = this.validate(config, schema);
+        if (!result.valid) {
+            throw new ValidationError(`Configuration validation failed: ${result.errors.join(', ')}`, 'CONFIG_VALIDATION_ERROR', { data: { errors: result.errors } });
+        }
+        return result.config;
+    }
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoidmFsaWRhdG9yLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vLi4vdHMvY29uZmlnL3ZhbGlkYXRvci50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxPQUFPLEtBQUssT0FBTyxNQUFNLGVBQWUsQ0FBQztBQUN6QyxPQUFPLEVBQUUsZUFBZSxFQUFFLE1BQU0sMEJBQTBCLENBQUM7QUEwRjNEOzs7R0FHRztBQUNILE1BQU0sT0FBTyxlQUFlO0lBRTFCOzs7Ozs7T0FNRztJQUNJLE1BQU0sQ0FBQyxRQUFRLENBQUksTUFBUyxFQUFFLE1BQXdCO1FBQzNELE1BQU0sTUFBTSxHQUFhLEVBQUUsQ0FBQztRQUM1QixNQUFNLGVBQWUsR0FBRyxFQUFFLEdBQUcsTUFBTSxFQUFFLENBQUM7UUFFdEMseUNBQXlDO1FBQ3pDLEtBQUssTUFBTSxDQUFDLEdBQUcsRUFBRSxLQUFLLENBQUMsSUFBSSxNQUFNLENBQUMsT0FBTyxDQUFDLE1BQU0sQ0FBQyxFQUFFLENBQUM7WUFDbEQsTUFBTSxLQUFLLEdBQUcsTUFBTSxDQUFDLEdBQUcsQ0FBQyxDQUFDO1lBRTFCLG9CQUFvQjtZQUNwQixJQUFJLEtBQUssQ0FBQyxRQUFRLElBQUksQ0FBQyxLQUFLLEtBQUssU0FBUyxJQUFJLEtBQUssS0FBSyxJQUFJLENBQUMsRUFBRSxDQUFDO2dCQUM5RCxNQUFNLENBQUMsSUFBSSxDQUFDLEdBQUcsR0FBRyxjQUFjLENBQUMsQ0FBQztnQkFDbEMsU0FBUztZQUNYLENBQUM7WUFFRCw4REFBOEQ7WUFDOUQsSUFBSSxDQUFDLEtBQUssS0FBSyxTQUFTLElBQUksS0FBSyxLQUFLLElBQUksQ0FBQyxFQUFFLENBQUM7Z0JBQzVDLElBQUksS0FBSyxDQUFDLE9BQU8sS0FBSyxTQUFTLEVBQUUsQ0FBQztvQkFDaEMsZUFBZSxDQUFDLEdBQUcsQ0FBQyxHQUFHLEtBQUssQ0FBQyxPQUFPLENBQUM7Z0JBQ3ZDLENBQUM7Z0JBQ0QsU0FBUztZQUNYLENBQUM7WUFFRCxr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

package/dist_ts/errors/base.errors.d.ts

@@ -0,0 +1,224 @@
+import { ErrorSeverity, ErrorCategory, ErrorRecoverability } from './error.codes.js';
+/**
+ * Context information added to structured errors
+ */
+export interface IErrorContext {
+    /** Component or service where the error occurred */
+    component?: string;
+    /** Operation that was being performed */
+    operation?: string;
+    /** Unique request ID if available */
+    requestId?: string;
+    /** Error occurred at timestamp */
+    timestamp?: number;
+    /** User-visible message (safe to display to end-users) */
+    userMessage?: string;
+    /** Additional structured data for debugging */
+    data?: Record<string, any>;
+    /** Related entity IDs if applicable */
+    entity?: {
+        type: string;
+        id: string | number;
+    };
+    /** Stack trace (if enabled in configuration) */
+    stack?: string;
+    /** Retry information if applicable */
+    retry?: {
+        /** Maximum number of retries allowed */
+        maxRetries?: number;
+        /** Current retry count */
+        currentRetry?: number;
+        /** Next retry timestamp */
+        nextRetryAt?: number;
+        /** Delay between retries (in ms) */
+        retryDelay?: number;
+    };
+}
+/**
+ * Base class for all errors in the Platform Service
+ * Adds structured error information, logging, and error tracking
+ */
+export declare class PlatformError extends Error {
+    /** Error code identifying the specific error type */
+    readonly code: string;
+    /** Error severity level */
+    readonly severity: ErrorSeverity;
+    /** Error category for grouping related errors */
+    readonly category: ErrorCategory;
+    /** Whether the error can be recovered from automatically */
+    readonly recoverability: ErrorRecoverability;
+    /** Additional context information */
+    readonly context: IErrorContext;
+    /**
+     * Creates a new PlatformError
+     *
+     * @param message Error message
+     * @param code Error code from error.codes.ts
+     * @param severity Error severity level
+     * @param category Error category
+     * @param recoverability Error recoverability indication
+     * @param context Additional context information
+     */
+    constructor(message: string, code: string, severity?: ErrorSeverity, category?: ErrorCategory, recoverability?: ErrorRecoverability, context?: IErrorContext);
+    /**
+     * Logs the error using the platform logger
+     */
+    private logError;
+    /**
+     * Maps severity levels to log levels
+     */
+    private getLogLevelFromSeverity;
+    /**
+     * Returns a JSON representation of the error
+     */
+    toJSON(): Record<string, any>;
+    /**
+     * Creates an instance with retry information
+     *
+     * @param maxRetries Maximum number of retries
+     * @param currentRetry Current retry count
+     * @param retryDelay Delay between retries in ms
+     */
+    withRetry(maxRetries: number, currentRetry?: number, retryDelay?: number): PlatformError;
+    /**
+     * Protected method to create a new instance with updated context
+     * Subclasses can override this to handle their own constructor signatures
+     */
+    protected createWithContext(context: IErrorContext): PlatformError;
+    /**
+     * Checks if the error should be retried based on retry information
+     */
+    shouldRetry(): boolean;
+    /**
+     * Returns a user-friendly message that is safe to display to end users
+     */
+    getUserMessage(): string;
+}
+/**
+ * Error class for validation errors
+ */
+export declare class ValidationError extends PlatformError {
+    /**
+     * Creates a new validation error
+     *
+     * @param message Error message
+     * @param code Error code
+     * @param context Additional context
+     */
+    constructor(message: string, code: string, context?: IErrorContext);
+    /**
+     * Creates a new instance with updated context
+     * Overrides the base implementation to handle ValidationError's constructor signature
+     */
+    protected createWithContext(context: IErrorContext): PlatformError;
+}
+/**
+ * Error class for configuration errors
+ */
+export declare class ConfigurationError extends PlatformError {
+    /**
+     * Creates a new configuration error
+     *
+     * @param message Error message
+     * @param code Error code
+     * @param context Additional context
+     */
+    constructor(message: string, code: string, context?: IErrorContext);
+    /**
+     * Creates a new instance with updated context
+     * Overrides the base implementation to handle ConfigurationError's constructor signature
+     */
+    protected createWithContext(context: IErrorContext): PlatformError;
+}
+/**
+ * Error class for network-related errors
+ */
+export declare class NetworkError extends PlatformError {
+    /**
+     * Creates a new network error
+     *
+     * @param message Error message
+     * @param code Error code
+     * @param context Additional context
+     */
+    constructor(message: string, code: string, context?: IErrorContext);
+    /**
+     * Creates a new instance with updated context
+     * Overrides the base implementation to handle NetworkError's constructor signature
+     */
+    protected createWithContext(context: IErrorContext): PlatformError;
+}
+/**
+ * Error class for resource availability errors (rate limits, quotas)
+ */
+export declare class ResourceError extends PlatformError {
+    /**
+     * Creates a new resource error
+     *
+     * @param message Error message
+     * @param code Error code
+     * @param context Additional context
+     */
+    constructor(message: string, code: string, context?: IErrorContext);
+    /**
+     * Creates a new instance with updated context
+     * Overrides the base implementation to handle ResourceError's constructor signature
+     */
+    protected createWithContext(context: IErrorContext): PlatformError;
+}
+/**
+ * Error class for authentication/authorization errors
+ */
+export declare class AuthenticationError extends PlatformError {
+    /**
+     * Creates a new authentication error
+     *
+     * @param message Error message
+     * @param code Error code
+     * @param context Additional context
+     */
+    constructor(message: string, code: string, context?: IErrorContext);
+    /**
+     * Creates a new instance with updated context
+     * Overrides the base implementation to handle AuthenticationError's constructor signature
+     */
+    protected createWithContext(context: IErrorContext): PlatformError;
+}
+/**
+ * Error class for operation errors (API calls, processing)
+ */
+export declare class OperationError extends PlatformError {
+    /**
+     * Creates a new operation error
+     *
+     * @param message Error message
+     * @param code Error code
+     * @param context Additional context
+     */
+    constructor(message: string, code: string, context?: IErrorContext);
+    /**
+     * Creates a new instance with updated context
+     * Overrides the base implementation to handle OperationError's constructor signature
+     */
+    protected createWithContext(context: IErrorContext): PlatformError;
+}
+/**
+ * Error class for critical system errors
+ */
+export declare class SystemError extends PlatformError {
+    /**
+     * Creates a new system error
+     *
+     * @param message Error message
+     * @param code Error code
+     * @param context Additional context
+     */
+    constructor(message: string, code: string, context?: IErrorContext);
+}
+/**
+ * Helper to get the appropriate error class based on error category
+ *
+ * @param category Error category
+ * @returns The appropriate error class
+ */
+export declare function getErrorClassForCategory(category: ErrorCategory): any;