content-security-toolkit 1.0.0

package/dist/utils/logging/advanced/LoggingFactory.js

@@ -0,0 +1,61 @@
+import { LoggingService } from "./LoggingService";
+import { getComponentLogLevel, getLoggingConfig } from "./LoggingConfig";
+/**
+ * Factory for creating LoggingService instances
+ */
+export class LoggingFactory {
+    /**
+     * Get a LoggingService instance for a component
+     * @param componentName Component name
+     * @returns LoggingService instance
+     */
+    static getLogger(componentName) {
+        // Check if we already have an instance for this component
+        if (this.instances.has(componentName)) {
+            return this.instances.get(componentName);
+        }
+        // Get the global config
+        const config = getLoggingConfig();
+        // Create a new instance
+        const logger = new LoggingService({
+            componentName,
+            level: getComponentLogLevel(componentName),
+            useColors: config.useColors,
+            includeTimestamps: config.includeTimestamps,
+            includeComponentName: config.includeComponentName,
+        });
+        // Apply global settings
+        if (config.enabledComponents !== null) {
+            logger.setEnabledComponents(config.enabledComponents);
+        }
+        if (config.focusedLevel !== null) {
+            logger.focusLevel(config.focusedLevel);
+        }
+        // Store the instance
+        this.instances.set(componentName, logger);
+        return logger;
+    }
+    /**
+     * Update all existing logger instances with current configuration
+     */
+    static updateAllLoggers() {
+        const config = getLoggingConfig();
+        for (const [componentName, logger] of this.instances.entries()) {
+            logger.setLevel(getComponentLogLevel(componentName));
+            if (config.enabledComponents !== null) {
+                logger.setEnabledComponents(config.enabledComponents);
+            }
+            if (config.focusedLevel !== null) {
+                logger.focusLevel(config.focusedLevel);
+            }
+        }
+    }
+    /**
+     * Get all registered logger instances
+     * @returns Map of component names to logger instances
+     */
+    static getAllLoggers() {
+        return new Map(this.instances);
+    }
+}
+LoggingFactory.instances = new Map();

package/dist/utils/logging/advanced/LoggingService.d.ts

@@ -0,0 +1,235 @@
+import { LogLevel } from "./LogLevel";
+/**
+ * Options for the LoggingService
+ */
+export interface LoggingOptions {
+    /**
+     * Component name for log prefixing
+     */
+    componentName: string;
+    /**
+     * Initial log level
+     * @default LogLevel.INFO
+     */
+    level?: LogLevel;
+    /**
+     * Whether logging is enabled
+     * @default true
+     */
+    enabled?: boolean;
+    /**
+     * Whether to use colors in console output
+     * @default true
+     */
+    useColors?: boolean;
+    /**
+     * Whether to include timestamps in logs
+     * @default true
+     */
+    includeTimestamps?: boolean;
+    /**
+     * Whether to include component name in logs
+     * @default true
+     */
+    includeComponentName?: boolean;
+}
+/**
+ * Performance timing result
+ */
+export interface TimingResult<T> {
+    result: T;
+    duration: number;
+}
+/**
+ * Advanced logging service with context tracking, filtering, and performance measurement
+ */
+export declare class LoggingService {
+    private componentName;
+    private currentLevel;
+    private enabled;
+    private useColors;
+    private includeTimestamps;
+    private includeComponentName;
+    private contextStack;
+    private contextDepth;
+    private enabledComponents;
+    private focusedLevel;
+    private groupDepth;
+    /**
+     * Create a new LoggingService
+     * @param options Configuration options
+     */
+    constructor(options: LoggingOptions);
+    /**
+     * Set the current log level threshold
+     * @param level New log level
+     */
+    setLevel(level: LogLevel): void;
+    /**
+     * Get the current log level
+     * @returns The current log level
+     */
+    getLevel(): LogLevel;
+    /**
+     * Get the current log level name
+     * @returns The current log level name
+     */
+    getLevelName(): string;
+    /**
+     * Enable or disable logging
+     * @param enabled Whether logging should be enabled
+     */
+    setEnabled(enabled: boolean): void;
+    /**
+     * Check if logging is enabled
+     * @returns Whether logging is enabled
+     */
+    isEnabled(): boolean;
+    /**
+     * Set components to show logs for
+     * @param components Array of component names to enable, or null to enable all
+     */
+    setEnabledComponents(components: string[] | null): void;
+    /**
+     * Focus on a specific log level
+     * @param level Level to focus on, or null to show all levels
+     */
+    focusLevel(level: LogLevel | null): void;
+    /**
+     * Increase context depth (call when entering a loop or nested function)
+     * @param contextName Optional name for the context
+     * @returns A function that exits this context when called
+     */
+    enterContext(contextName?: string): () => void;
+    /**
+     * Decrease context depth (call when exiting a loop or nested function)
+     */
+    exitContext(): void;
+    /**
+     * Execute a function within a named context
+     * @param contextName Name for the context
+     * @param fn Function to execute
+     * @returns The result of the function
+     */
+    withContext<T>(contextName: string, fn: () => T): T;
+    /**
+     * Execute an async function within a named context
+     * @param contextName Name for the context
+     * @param fn Async function to execute
+     * @returns Promise resolving to the result of the function
+     */
+    withContextAsync<T>(contextName: string, fn: () => Promise<T>): Promise<T>;
+    /**
+     * Start a console group
+     * @param label Label for the group
+     * @param collapsed Whether the group should be collapsed
+     */
+    startGroup(label: string, collapsed?: boolean): void;
+    /**
+     * End the current console group
+     */
+    endGroup(): void;
+    /**
+     * Execute a function within a console group
+     * @param label Label for the group
+     * @param fn Function to execute
+     * @param collapsed Whether the group should be collapsed
+     * @returns The result of the function
+     */
+    group<T>(label: string, fn: () => T, collapsed?: boolean): T;
+    /**
+     * Execute an async function within a console group
+     * @param label Label for the group
+     * @param fn Async function to execute
+     * @param collapsed Whether the group should be collapsed
+     * @returns Promise resolving to the result of the function
+     */
+    groupAsync<T>(label: string, fn: () => Promise<T>, collapsed?: boolean): Promise<T>;
+    /**
+     * Measure the execution time of a function
+     * @param label Label for the timing
+     * @param fn Function to measure
+     * @returns Object containing the result and duration
+     */
+    time<T>(label: string, fn: () => T): TimingResult<T>;
+    /**
+     * Measure the execution time of an async function
+     * @param label Label for the timing
+     * @param fn Async function to measure
+     * @returns Promise resolving to an object containing the result and duration
+     */
+    timeAsync<T>(label: string, fn: () => Promise<T>): Promise<TimingResult<T>>;
+    /**
+     * Log with automatic level adjustment based on context depth
+     * @param message Message to log
+     * @param args Additional arguments to log
+     */
+    logWithContext(message: string, ...args: unknown[]): void;
+    /**
+     * Main logging method
+     * @param level Log level
+     * @param message Message to log
+     * @param args Additional arguments to log
+     */
+    log(level: LogLevel, message: string, ...args: unknown[]): void;
+    /**
+     * Log an error message
+     * @param message Error message
+     * @param args Additional arguments to log
+     */
+    error(message: string, ...args: unknown[]): void;
+    /**
+     * Log a warning message
+     * @param message Warning message
+     * @param args Additional arguments to log
+     */
+    warn(message: string, ...args: unknown[]): void;
+    /**
+     * Log an info message
+     * @param message Info message
+     * @param args Additional arguments to log
+     */
+    info(message: string, ...args: unknown[]): void;
+    /**
+     * Log a debug message
+     * @param message Debug message
+     * @param args Additional arguments to log
+     */
+    debug(message: string, ...args: unknown[]): void;
+    /**
+     * Log a trace message
+     * @param message Trace message
+     * @param args Additional arguments to log
+     */
+    trace(message: string, ...args: unknown[]): void;
+    /**
+     * Log a verbose message
+     * @param message Verbose message
+     * @param args Additional arguments to log
+     */
+    verbose(message: string, ...args: unknown[]): void;
+    /**
+     * Check if a message should be logged
+     * @param level Log level of the message
+     * @returns Whether the message should be logged
+     */
+    private shouldLog;
+    /**
+     * Format a log message
+     * @param level Log level
+     * @param message Message to format
+     * @returns Formatted message
+     */
+    private formatMessage;
+    /**
+     * Get the current timestamp as a string
+     * @returns Formatted timestamp
+     */
+    private getTimestamp;
+    /**
+     * Get prefix for log level
+     * @param level Log level
+     * @returns Formatted prefix
+     */
+    private getLevelPrefix;
+}

package/dist/utils/logging/advanced/LoggingService.js

@@ -0,0 +1,385 @@
+import { LogLevel, getLogLevelName } from "./LogLevel";
+/**
+ * Advanced logging service with context tracking, filtering, and performance measurement
+ */
+export class LoggingService {
+    /**
+     * Create a new LoggingService
+     * @param options Configuration options
+     */
+    constructor(options) {
+        // Context tracking
+        this.contextStack = [];
+        this.contextDepth = 0;
+        // Component filtering
+        this.enabledComponents = null;
+        // Level focusing
+        this.focusedLevel = null;
+        // Console group tracking
+        this.groupDepth = 0;
+        this.componentName = options.componentName;
+        this.currentLevel = options.level ?? LogLevel.INFO;
+        this.enabled = options.enabled ?? true;
+        this.useColors = options.useColors ?? true;
+        this.includeTimestamps = options.includeTimestamps ?? true;
+        this.includeComponentName = options.includeComponentName ?? true;
+    }
+    /**
+     * Set the current log level threshold
+     * @param level New log level
+     */
+    setLevel(level) {
+        this.currentLevel = level;
+    }
+    /**
+     * Get the current log level
+     * @returns The current log level
+     */
+    getLevel() {
+        return this.currentLevel;
+    }
+    /**
+     * Get the current log level name
+     * @returns The current log level name
+     */
+    getLevelName() {
+        return getLogLevelName(this.currentLevel);
+    }
+    /**
+     * Enable or disable logging
+     * @param enabled Whether logging should be enabled
+     */
+    setEnabled(enabled) {
+        this.enabled = enabled;
+    }
+    /**
+     * Check if logging is enabled
+     * @returns Whether logging is enabled
+     */
+    isEnabled() {
+        return this.enabled;
+    }
+    /**
+     * Set components to show logs for
+     * @param components Array of component names to enable, or null to enable all
+     */
+    setEnabledComponents(components) {
+        if (components === null) {
+            this.enabledComponents = null;
+        }
+        else {
+            this.enabledComponents = new Set(components);
+        }
+    }
+    /**
+     * Focus on a specific log level
+     * @param level Level to focus on, or null to show all levels
+     */
+    focusLevel(level) {
+        this.focusedLevel = level;
+    }
+    /**
+     * Increase context depth (call when entering a loop or nested function)
+     * @param contextName Optional name for the context
+     * @returns A function that exits this context when called
+     */
+    enterContext(contextName = "context") {
+        this.contextDepth++;
+        const context = {
+            name: contextName,
+            startTime: performance.now(),
+            depth: this.contextDepth,
+        };
+        this.contextStack.push(context);
+        this.trace(`Entering ${contextName}`);
+        // Return a function that exits this context
+        return () => {
+            this.exitContext();
+        };
+    }
+    /**
+     * Decrease context depth (call when exiting a loop or nested function)
+     */
+    exitContext() {
+        if (this.contextStack.length > 0) {
+            const context = this.contextStack.pop();
+            this.contextDepth = Math.max(0, this.contextDepth - 1);
+            const duration = performance.now() - context.startTime;
+            this.trace(`Exiting ${context.name} (took ${duration.toFixed(2)}ms)`);
+        }
+    }
+    /**
+     * Execute a function within a named context
+     * @param contextName Name for the context
+     * @param fn Function to execute
+     * @returns The result of the function
+     */
+    withContext(contextName, fn) {
+        const exitFn = this.enterContext(contextName);
+        try {
+            return fn();
+        }
+        finally {
+            exitFn();
+        }
+    }
+    /**
+     * Execute an async function within a named context
+     * @param contextName Name for the context
+     * @param fn Async function to execute
+     * @returns Promise resolving to the result of the function
+     */
+    async withContextAsync(contextName, fn) {
+        const exitFn = this.enterContext(contextName);
+        try {
+            return await fn();
+        }
+        finally {
+            exitFn();
+        }
+    }
+    /**
+     * Start a console group
+     * @param label Label for the group
+     * @param collapsed Whether the group should be collapsed
+     */
+    startGroup(label, collapsed = false) {
+        if (!this.shouldLog(LogLevel.INFO))
+            return;
+        this.groupDepth++;
+        if (collapsed) {
+            console.groupCollapsed(this.formatMessage(LogLevel.INFO, label));
+        }
+        else {
+            console.group(this.formatMessage(LogLevel.INFO, label));
+        }
+    }
+    /**
+     * End the current console group
+     */
+    endGroup() {
+        if (this.groupDepth > 0) {
+            console.groupEnd();
+            this.groupDepth--;
+        }
+    }
+    /**
+     * Execute a function within a console group
+     * @param label Label for the group
+     * @param fn Function to execute
+     * @param collapsed Whether the group should be collapsed
+     * @returns The result of the function
+     */
+    group(label, fn, collapsed = false) {
+        this.startGroup(label, collapsed);
+        try {
+            return fn();
+        }
+        finally {
+            this.endGroup();
+        }
+    }
+    /**
+     * Execute an async function within a console group
+     * @param label Label for the group
+     * @param fn Async function to execute
+     * @param collapsed Whether the group should be collapsed
+     * @returns Promise resolving to the result of the function
+     */
+    async groupAsync(label, fn, collapsed = false) {
+        this.startGroup(label, collapsed);
+        try {
+            return await fn();
+        }
+        finally {
+            this.endGroup();
+        }
+    }
+    /**
+     * Measure the execution time of a function
+     * @param label Label for the timing
+     * @param fn Function to measure
+     * @returns Object containing the result and duration
+     */
+    time(label, fn) {
+        const start = performance.now();
+        const result = fn();
+        const duration = performance.now() - start;
+        this.info(`${label} took ${duration.toFixed(2)}ms`);
+        return { result, duration };
+    }
+    /**
+     * Measure the execution time of an async function
+     * @param label Label for the timing
+     * @param fn Async function to measure
+     * @returns Promise resolving to an object containing the result and duration
+     */
+    async timeAsync(label, fn) {
+        const start = performance.now();
+        const result = await fn();
+        const duration = performance.now() - start;
+        this.info(`${label} took ${duration.toFixed(2)}ms`);
+        return { result, duration };
+    }
+    /**
+     * Log with automatic level adjustment based on context depth
+     * @param message Message to log
+     * @param args Additional arguments to log
+     */
+    logWithContext(message, ...args) {
+        // Adjust level based on nesting - deeper nesting means more detailed level
+        const adjustedLevel = Math.min(LogLevel.VERBOSE, LogLevel.INFO + this.contextDepth);
+        this.log(adjustedLevel, message, ...args);
+    }
+    /**
+     * Main logging method
+     * @param level Log level
+     * @param message Message to log
+     * @param args Additional arguments to log
+     */
+    log(level, message, ...args) {
+        if (!this.shouldLog(level))
+            return;
+        const formattedMessage = this.formatMessage(level, message);
+        switch (level) {
+            case LogLevel.ERROR:
+                console.error(formattedMessage, ...args);
+                break;
+            case LogLevel.WARN:
+                console.warn(formattedMessage, ...args);
+                break;
+            default:
+                console.log(formattedMessage, ...args);
+                break;
+        }
+    }
+    /**
+     * Log an error message
+     * @param message Error message
+     * @param args Additional arguments to log
+     */
+    error(message, ...args) {
+        this.log(LogLevel.ERROR, message, ...args);
+    }
+    /**
+     * Log a warning message
+     * @param message Warning message
+     * @param args Additional arguments to log
+     */
+    warn(message, ...args) {
+        this.log(LogLevel.WARN, message, ...args);
+    }
+    /**
+     * Log an info message
+     * @param message Info message
+     * @param args Additional arguments to log
+     */
+    info(message, ...args) {
+        this.log(LogLevel.INFO, message, ...args);
+    }
+    /**
+     * Log a debug message
+     * @param message Debug message
+     * @param args Additional arguments to log
+     */
+    debug(message, ...args) {
+        this.log(LogLevel.DEBUG, message, ...args);
+    }
+    /**
+     * Log a trace message
+     * @param message Trace message
+     * @param args Additional arguments to log
+     */
+    trace(message, ...args) {
+        this.log(LogLevel.TRACE, message, ...args);
+    }
+    /**
+     * Log a verbose message
+     * @param message Verbose message
+     * @param args Additional arguments to log
+     */
+    verbose(message, ...args) {
+        this.log(LogLevel.VERBOSE, message, ...args);
+    }
+    /**
+     * Check if a message should be logged
+     * @param level Log level of the message
+     * @returns Whether the message should be logged
+     */
+    shouldLog(level) {
+        // Always log errors and warnings, otherwise respect enabled flag
+        if (!this.enabled && level > LogLevel.WARN)
+            return false;
+        // If we're focusing on a specific level, only log messages at that level
+        if (this.focusedLevel !== null) {
+            return level === this.focusedLevel || level <= LogLevel.WARN;
+        }
+        // Otherwise, respect the level threshold
+        if (level > this.currentLevel && level > LogLevel.WARN)
+            return false;
+        // Check if component is enabled
+        if (this.enabledComponents !== null && !this.enabledComponents.has(this.componentName)) {
+            // Still allow errors and warnings
+            return level <= LogLevel.WARN;
+        }
+        return true;
+    }
+    /**
+     * Format a log message
+     * @param level Log level
+     * @param message Message to format
+     * @returns Formatted message
+     */
+    formatMessage(level, message) {
+        const parts = [];
+        // Add timestamp if enabled
+        if (this.includeTimestamps) {
+            parts.push(this.getTimestamp());
+        }
+        // Add level prefix
+        parts.push(this.getLevelPrefix(level));
+        // Add component name if enabled
+        if (this.includeComponentName) {
+            parts.push(this.componentName);
+        }
+        // Add indentation based on context depth
+        const indentation = "  ".repeat(this.contextDepth);
+        // Combine all parts
+        return `${parts.join(" ")}: ${indentation}${message}`;
+    }
+    /**
+     * Get the current timestamp as a string
+     * @returns Formatted timestamp
+     */
+    getTimestamp() {
+        const now = new Date();
+        return `[${now.toISOString()}]`;
+    }
+    /**
+     * Get prefix for log level
+     * @param level Log level
+     * @returns Formatted prefix
+     */
+    getLevelPrefix(level) {
+        if (!this.useColors) {
+            return `[${getLogLevelName(level)}]`;
+        }
+        // Use colors for different levels
+        switch (level) {
+            case LogLevel.ERROR:
+                return "\x1b[31m[ERROR]\x1b[0m"; // Red
+            case LogLevel.WARN:
+                return "\x1b[33m[WARN]\x1b[0m"; // Yellow
+            case LogLevel.INFO:
+                return "\x1b[36m[INFO]\x1b[0m"; // Cyan
+            case LogLevel.DEBUG:
+                return "\x1b[32m[DEBUG]\x1b[0m"; // Green
+            case LogLevel.TRACE:
+                return "\x1b[35m[TRACE]\x1b[0m"; // Magenta
+            case LogLevel.VERBOSE:
+                return "\x1b[90m[VERBOSE]\x1b[0m"; // Gray
+            default:
+                return `[${getLogLevelName(level)}]`;
+        }
+    }
+}

package/dist/utils/logging/simple/Loggable.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Interface for components that support logging
+ */
+export interface Loggable {
+    /**
+     * Log a debug message if debug mode is enabled
+     * @param message Message to log
+     * @param args Additional arguments to log
+     */
+    log(message: string, ...args: unknown[]): void;
+    /**
+     * Log a warning message
+     * @param message Warning message
+     * @param args Additional arguments to log
+     */
+    warn(message: string, ...args: unknown[]): void;
+    /**
+     * Log an error message
+     * @param message Error message
+     * @param args Additional arguments to log
+     */
+    error(message: string, ...args: unknown[]): void;
+    /**
+     * Set debug mode
+     * @param enabled Whether debug mode should be enabled
+     */
+    setDebugMode(enabled: boolean): void;
+    /**
+     * Check if debug mode is enabled
+     * @returns Whether debug mode is enabled
+     */
+    isDebugEnabled(): boolean;
+}