lever-ui-logger/dist/types/logger/context-manager.d.ts

Zero-dependency logging library with optional EventBus integration. Built-in PII redaction, multiple transports, and comprehensive logging capabilities.

/**
 * Context Management Component for Logger
 *
 * Manages hierarchical context for logging, supporting context inheritance,
 * merging, and isolation. Provides efficient context stacking for child
 * loggers and temporary context scopes.
 *
 * @example
 * ```typescript
 * import { ContextManager } from './context-manager';
 *
 * const contextManager = new ContextManager({ service: 'api' });
 *
 * // Add context
 * contextManager.add({ userId: '123' });
 *
 * // Get merged context
 * const context = contextManager.getContext(); // { service: 'api', userId: '123' }
 *
 * // Create child with additional context
 * const child = contextManager.createChild({ requestId: 'abc' });
 * ```
 */
/**
 * Manages logging context with support for inheritance and merging
 */
export declare class ContextManager {
    private readonly baseContext;
    private additionalContext;
    private readonly contextStack;
    private readonly parent?;
    /**
     * Creates a new context manager
     *
     * @param baseContext - Base context that cannot be modified
     * @param parent - Optional parent context manager for inheritance
     */
    constructor(baseContext?: Record<string, unknown>, parent?: ContextManager);
    /**
     * Get the current merged context
     *
     * @returns Merged context from all layers
     */
    getContext(): Record<string, unknown>;
    /**
     * Get only the base context (immutable)
     */
    getBaseContext(): Record<string, unknown>;
    /**
     * Get only the additional context
     */
    getAdditionalContext(): Record<string, unknown>;
    /**
     * Add or update context fields
     *
     * @param context - Context to add/merge
     */
    add(context: Record<string, unknown>): void;
    /**
     * Set context (replaces additional context)
     *
     * @param context - New context to set
     */
    set(context: Record<string, unknown>): void;
    /**
     * Remove specific context fields
     *
     * @param keys - Keys to remove from context
     */
    remove(...keys: string[]): void;
    /**
     * Clear all additional context (keeps base context)
     */
    clear(): void;
    /**
     * Push a temporary context onto the stack
     *
     * @param context - Temporary context to push
     * @returns Function to pop this context
     */
    push(context: Record<string, unknown>): () => void;
    /**
     * Pop the most recent context from the stack
     *
     * @returns The popped context or undefined
     */
    pop(): Record<string, unknown> | undefined;
    /**
     * Execute a function with temporary context
     *
     * @param context - Temporary context
     * @param fn - Function to execute
     * @returns Result of the function
     */
    withContext<T>(context: Record<string, unknown>, fn: () => T): T;
    /**
     * Execute an async function with temporary context
     *
     * @param context - Temporary context
     * @param fn - Async function to execute
     * @returns Promise with result of the function
     */
    withContextAsync<T>(context: Record<string, unknown>, fn: () => Promise<T>): Promise<T>;
    /**
     * Create a child context manager
     *
     * @param additionalContext - Additional context for the child
     * @returns New ContextManager instance
     */
    createChild(additionalContext?: Record<string, unknown>): ContextManager;
    /**
     * Clone this context manager
     *
     * @param includeStack - Whether to include the context stack
     * @returns New ContextManager instance
     */
    clone(includeStack?: boolean): ContextManager;
    /**
     * Check if context has a specific key
     *
     * @param key - Key to check
     * @returns True if key exists in context
     */
    has(key: string): boolean;
    /**
     * Get a specific context value
     *
     * @param key - Key to get
     * @returns Value or undefined
     */
    get(key: string): unknown;
    /**
     * Get the size of the current context
     *
     * @returns Number of keys in merged context
     */
    get size(): number;
    /**
     * Get the depth of the context stack
     *
     * @returns Stack depth
     */
    get stackDepth(): number;
    /**
     * Check if context is empty
     *
     * @returns True if no context is set
     */
    get isEmpty(): boolean;
    /**
     * Merge multiple contexts
     *
     * @param contexts - Contexts to merge
     * @returns Merged context
     */
    static merge(...contexts: Record<string, unknown>[]): Record<string, unknown>;
    /**
     * Filter context by allowed keys
     *
     * @param context - Context to filter
     * @param allowedKeys - Keys to allow
     * @returns Filtered context
     */
    static filter(context: Record<string, unknown>, allowedKeys: string[]): Record<string, unknown>;
    /**
     * Exclude keys from context
     *
     * @param context - Context to filter
     * @param excludedKeys - Keys to exclude
     * @returns Filtered context
     */
    static exclude(context: Record<string, unknown>, excludedKeys: string[]): Record<string, unknown>;
    /**
     * Static deep clone helper for use in constructor
     *
     * @private
     */
    private static deepCloneStatic;
    /**
     * Deep clone an object (simple implementation for context objects)
     *
     * @private
     * @param obj - Object to clone
     * @returns Deep cloned object
     */
    private deepClone;
}
//# sourceMappingURL=context-manager.d.ts.map