lever-ui-logger
Version:
Zero-dependency logging library with optional EventBus integration. Built-in PII redaction, multiple transports, and comprehensive logging capabilities.
1,015 lines (1,002 loc) • 35.3 kB
TypeScript
/**
* Core Logger Types and Interface Definitions
*
* Foundational type definitions for the lever-ui-logger system, providing
* comprehensive TypeScript interfaces for logger configuration, transport
* systems, and event structures. Designed for seamless integration with
* the EventBus architecture and maximum type safety.
*
* Key Types:
* - Logger interface for structured logging with context and metadata
* - Transport interface for pluggable log output destinations
* - LoggerConfig for comprehensive logger configuration
* - LogEventData for structured log event representation
* - RedactionConfig for PII protection and data sanitization
* - Sampling configuration for performance optimization
*
* @example
* ```typescript
* import type { Logger, LoggerConfig, Transport } from '@nuanced-labs/lever-ui-logger';
*
* // Type-safe logger configuration
* const config: LoggerConfig = {
* level: 'info',
* component: 'user-service',
* defaultContext: { service: 'api', version: '1.0.0' },
* sampling: { debug: 0.1, info: 1.0 },
* redaction: { enabled: true, patterns: ['password', 'token'] },
* transports: [consoleTransport, beaconTransport]
* };
*
* // Custom transport implementation
* const customTransport: Transport = {
* name: 'custom-transport',
* write: (event: LogEventData) => {
* console.log(`${event.level}: ${event.message}`, event.context);
* },
* flush: async () => { },
* close: async () => { }
* };
* ```
*/
/**
* Log levels supported by the logger
*/
type LogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error';
/**
* Logger configuration options
*/
interface LoggerConfig {
/** Minimum log level to process */
level?: LogLevel;
/** Component/module name for contextual logging */
component?: string;
/** Custom context that will be added to all logs */
defaultContext?: Record<string, unknown>;
/** Sampling rates per log level (0-1) */
sampling?: Partial<Record<LogLevel, number>>;
/** PII redaction configuration */
redaction?: RedactionConfig;
/** Transport configuration */
transports?: Transport[];
/** Enable/disable automatic error capture */
captureUnhandledErrors?: boolean;
/** Enable/disable automatic unhandled rejection capture */
captureUnhandledRejections?: boolean;
/** Enable/disable console.error interception */
captureConsoleErrors?: boolean;
}
/**
* PII redaction configuration
*/
interface RedactionConfig {
/** Enable/disable redaction */
enabled?: boolean;
/** Redaction mode: strict, balanced, permissive, off */
mode?: 'strict' | 'balanced' | 'permissive' | 'off';
/** Custom redaction patterns to add */
patterns?: RedactionPattern[];
/** Specific patterns to enable (overrides defaults) */
enabledPatterns?: string[];
/** Specific patterns to disable */
disabledPatterns?: string[];
/** Custom redaction function */
customRedactor?: (input: string) => string;
/** Use hash-based redaction for analytics */
hashRedaction?: boolean;
/** Enable differential privacy for metrics */
differentialPrivacy?: boolean;
/** Performance warning threshold in ms */
performanceThreshold?: number;
}
/**
* Redaction pattern definition
*/
interface RedactionPattern {
/** Pattern name for debugging and configuration */
name?: string;
/** Regular expression pattern to match */
pattern: RegExp;
/** Replacement string */
replacement: string;
/** Description of what this pattern matches */
description?: string;
/** Whether this pattern is enabled by default */
defaultEnabled?: boolean;
/** Performance category for priority ordering */
priority?: 'high' | 'medium' | 'low';
}
/**
* Transport interface for log output
*/
interface Transport {
/** Transport name for identification */
name: string;
/** Write a log event to this transport */
write(event: LogEventData): Promise<void> | void;
/** Flush any pending logs */
flush(): Promise<void> | void;
/** Close the transport and clean up resources */
close(): Promise<void> | void;
/** Transport configuration */
config?: Record<string, unknown>;
}
/**
* Log event data structure passed to transports
*/
interface LogEventData {
/** Log level */
level: LogLevel;
/** Log message */
message: string;
/** Timestamp when log was created */
timestamp: number;
/** Additional context data */
context: Record<string, unknown>;
/** Additional arguments passed to log call */
args: readonly unknown[];
/** Component/logger name that created this log */
component: string;
/** Logger instance name */
logger: string;
}
/**
* Metric data structure for structured metrics logging
*/
interface MetricData {
/** Metric name */
name: string;
/** Metric fields/values */
fields: Record<string, number | string | boolean>;
/** Timestamp when metric was recorded */
timestamp: number;
/** Additional context */
context: Record<string, unknown>;
/** Component that recorded the metric */
component: string;
}
/**
* Error data structure for error logging
*/
interface ErrorData {
/** Error name/type */
name: string;
/** Error message */
message: string;
/** Stack trace if available */
stack?: string;
/** Whether error was handled by application */
handled: boolean;
/** Timestamp when error occurred */
timestamp: number;
/** Additional context */
context: Record<string, unknown>;
/** Component where error occurred */
component: string;
}
/**
* Logger interface - main logging API
*/
interface Logger {
/** Logger name/identifier */
readonly name: string;
/** Current log level */
readonly level: LogLevel;
/** Log trace message */
trace(message: string, ...args: readonly unknown[]): void;
/** Log debug message */
debug(message: string, ...args: readonly unknown[]): void;
/** Log info message */
info(message: string, ...args: readonly unknown[]): void;
/** Log warning message */
warn(message: string, ...args: readonly unknown[]): void;
/** Log error message */
error(message: string, ...args: readonly unknown[]): void;
/** Record a metric */
metric(name: string, fields?: Record<string, number | string | boolean>): void;
/** Create child logger with additional context */
withContext(context: Record<string, unknown>): Logger;
/** Set minimum log level */
setLevel(level: LogLevel): void;
/** Set component-specific log level */
setComponentLevel(component: string, level: LogLevel): void;
/** Explicitly redact a value */
redact(value: unknown): string;
/** Add a transport to this logger */
addTransport(transport: Transport): void;
/** Remove a transport from this logger */
removeTransport(transportName: string): boolean;
/** Flush all transports */
flush(): Promise<void>;
/** Destroy logger and clean up resources */
destroy(): Promise<void>;
}
/**
* Logger factory function type
*/
type LoggerFactory = (config?: LoggerConfig) => Logger;
/**
* EventBus integration event classes following lever-ui-eventbus patterns
* All events follow the class-based event pattern with public readonly properties
*/
/**
* Base class for all logging events with sync coordination metadata.
*
* All logger events extend this class to provide consistent timestamp and client ID
* tracking for cross-library coordination and lever-ui-sync integration.
*
* @example
* ```typescript
* // Events automatically get timestamp and clientId
* const event = new LogEvent('info', 'message', {}, [], 'component', 'logger');
* console.log(event.timestamp); // 1640995200000
* console.log(event.clientId); // "550e8400-e29b-41d4-a716-446655440000" or "client-abc123-def456"
* ```
*/
declare class LoggerBaseEvent {
readonly timestamp: number;
readonly clientId: string;
/**
* Creates a new logger base event.
*
* @param timestamp - Unix timestamp when event was created (defaults to Date.now())
* @param clientId - Unique client identifier for this browser session (auto-generated)
*/
constructor(timestamp?: number, clientId?: string);
}
/**
* Core logging event published to EventBus for all log calls.
*
* This event is posted to the EventBus whenever a log method is called (trace, debug, info, warn, error).
* Other systems can subscribe to these events for analytics, monitoring, error tracking, etc.
*
* @example
* ```typescript
* // Subscribe to all log events
* eventBus.subscribe(LogEvent, (event) => {
* console.log(`[${event.level.toUpperCase()}] ${event.message}`, event.context);
*
* if (event.level === 'error') {
* sendToErrorTracking(event);
* }
* });
*
* // Logger automatically posts LogEvent to EventBus
* logger.info('User logged in', { userId: '123', method: 'oauth' });
* ```
*/
declare class LogEvent extends LoggerBaseEvent {
readonly level: LogLevel;
readonly message: string;
readonly context: Record<string, unknown>;
readonly args: readonly unknown[];
readonly component: string;
readonly logger: string;
/**
* Creates a new log event.
*
* @param level - Log level (trace, debug, info, warn, error)
* @param message - Primary log message
* @param context - Structured context data object
* @param args - Additional arguments passed to the log call
* @param component - Component or module name that generated the log
* @param logger - Logger instance name
* @param timestamp - Optional custom timestamp (defaults to current time)
* @param clientId - Optional custom client ID (defaults to generated ID)
*/
constructor(level: LogLevel, message: string, context: Record<string, unknown>, args: readonly unknown[], component: string, logger: string, timestamp?: number, clientId?: string);
/**
* Converts this event to the LogEventData format used by transports.
*
* @returns LogEventData object ready for transport processing
* @example
* ```typescript
* const event = new LogEvent('info', 'test', {}, [], 'comp', 'logger');
* const transportData = event.toLogEventData();
* consoleTransport.write(transportData);
* ```
*/
toLogEventData(): LogEventData;
}
/**
* Structured metrics event for performance monitoring and analytics.
*
* Use this event type for recording quantitative measurements like response times,
* user interactions, performance metrics, and business analytics.
*
* @example
* ```typescript
* // Subscribe to metrics for analytics
* eventBus.subscribe(MetricEvent, (event) => {
* analytics.track(event.name, event.fields);
* });
*
* // Logger posts MetricEvent to EventBus
* logger.metric('api_response_time', {
* duration: 234,
* endpoint: '/users',
* status: 200
* });
* ```
*/
declare class MetricEvent extends LoggerBaseEvent {
readonly name: string;
readonly fields: Record<string, number | string | boolean>;
readonly context: Record<string, unknown>;
readonly component: string;
/**
* Creates a new metric event.
*
* @param name - Metric name (e.g., 'page_load_time', 'button_click')
* @param fields - Metric data and measurements
* @param context - Additional context for the metric
* @param component - Component that recorded the metric
* @param timestamp - Optional custom timestamp
* @param clientId - Optional custom client ID
*/
constructor(name: string, fields: Record<string, number | string | boolean>, context: Record<string, unknown>, component: string, timestamp?: number, clientId?: string);
/**
* Convert to metric data format
*/
toMetricData(): MetricData;
}
/**
* Error event for unhandled errors, exceptions, and error boundary catches
*/
declare class ErrorEvent extends LoggerBaseEvent {
readonly error: Error;
readonly handled: boolean;
readonly context: Record<string, unknown>;
readonly component: string;
constructor(error: Error, handled: boolean, context: Record<string, unknown>, component: string, timestamp?: number, clientId?: string);
/**
* Get error name (constructor name or custom name)
*/
get name(): string;
/**
* Get error message
*/
get message(): string;
/**
* Get stack trace if available
*/
get stack(): string | undefined;
/**
* Convert to error data format
*/
toErrorData(): ErrorData;
}
/**
* Logger lifecycle event - emitted when a logger is created
*/
declare class LoggerCreatedEvent extends LoggerBaseEvent {
readonly name: string;
readonly config: Record<string, unknown>;
constructor(name: string, config: Record<string, unknown>, timestamp?: number, clientId?: string);
}
/**
* Logger lifecycle event - emitted when a logger is destroyed
*/
declare class LoggerDestroyedEvent extends LoggerBaseEvent {
readonly name: string;
readonly reason?: string | undefined;
constructor(name: string, reason?: string | undefined, timestamp?: number, clientId?: string);
}
/**
* Transport event - emitted when transport operations occur
*/
declare class TransportEvent extends LoggerBaseEvent {
readonly transportName: string;
readonly operation: 'write' | 'flush' | 'close' | 'error';
readonly details: Record<string, unknown>;
constructor(transportName: string, operation: 'write' | 'flush' | 'close' | 'error', details?: Record<string, unknown>, timestamp?: number, clientId?: string);
}
/**
* Transport error event - emitted when transport operations fail
*/
declare class TransportErrorEvent extends LoggerBaseEvent {
readonly transportName: string;
readonly error: Error;
readonly operation: string;
readonly details: Record<string, unknown>;
constructor(transportName: string, error: Error, operation: string, details?: Record<string, unknown>, timestamp?: number, clientId?: string);
}
/**
* PII detection warning event - emitted in development when potential PII is detected
*/
declare class PIIWarningEvent extends LoggerBaseEvent {
readonly field: string;
readonly value: string;
readonly pattern: string;
readonly suggestion: string;
readonly context: Record<string, unknown>;
constructor(field: string, value: string, pattern: string, suggestion: string, context: Record<string, unknown>, timestamp?: number, clientId?: string);
}
/**
* Logger configuration change event
*/
declare class LoggerConfigChangedEvent extends LoggerBaseEvent {
readonly loggerName: string;
readonly oldConfig: Record<string, unknown>;
readonly newConfig: Record<string, unknown>;
readonly changes: string[];
constructor(loggerName: string, oldConfig: Record<string, unknown>, newConfig: Record<string, unknown>, changes: string[], timestamp?: number, clientId?: string);
}
/**
* Type guard to check if an event is a LogEvent
*/
declare function isLogEvent(event: unknown): event is LogEvent;
/**
* Type guard to check if an event is a MetricEvent
*/
declare function isMetricEvent(event: unknown): event is MetricEvent;
/**
* Type guard to check if an event is an ErrorEvent
*/
declare function isErrorEvent(event: unknown): event is ErrorEvent;
/**
* Type guard to check if an event is any logger-related event
*/
declare function isLoggerEvent(event: unknown): event is LoggerBaseEvent;
/**
* Logger configuration types and default values
*/
/**
* Default log level for new loggers
*/
declare const DEFAULT_LOG_LEVEL: LogLevel;
/**
* Log level hierarchy for comparison
* Higher numbers indicate higher priority
*/
declare const LOG_LEVEL_PRIORITY: Record<LogLevel, number>;
/**
* Default logger configuration
*/
declare const DEFAULT_LOGGER_CONFIG: Required<Omit<LoggerConfig, 'transports'>> & {
transports: Transport[];
};
/**
* Merges user configuration with defaults
*
* @param userConfig - User-provided configuration
* @returns Complete configuration with defaults applied
*/
declare function mergeConfig(userConfig?: LoggerConfig): Required<LoggerConfig>;
/**
* Checks if a log level should be processed based on current minimum level
*
* @param level - Log level to check
* @param minLevel - Minimum log level configured
* @returns True if log should be processed
*/
declare function shouldLog(level: LogLevel, minLevel: LogLevel): boolean;
/**
* Applies sampling to determine if a log should be processed
*
* @param level - Log level
* @param samplingRates - Sampling configuration
* @returns True if log passes sampling check
*/
declare function passesSampling(level: LogLevel, samplingRates: Partial<Record<LogLevel, number>>): boolean;
/** Core Logger Implementation - Standalone logger with transport system */
/** Core standalone logger implementation with transport system */
declare class LoggerImpl implements Logger {
private readonly loggerName;
private readonly transportRegistry;
private readonly configuration;
private readonly contextManager;
private readonly redactionEngine;
private destroyed;
/** Creates a new logger instance */
constructor(config?: LoggerConfig, loggerName?: string);
/** Logger name/identifier */
get name(): string;
/** Current minimum log level */
get level(): LogLevel;
/** Logs a trace-level message */
trace(message: string, ...args: readonly unknown[]): void;
/** Logs a debug-level message */
debug(message: string, ...args: readonly unknown[]): void;
/** Logs an info-level message */
info(message: string, ...args: readonly unknown[]): void;
/** Logs a warning-level message */
warn(message: string, ...args: readonly unknown[]): void;
/** Logs an error-level message */
error(message: string, ...args: readonly unknown[]): void;
/** Records a structured metric */
metric(name: string, fields?: Record<string, number | string | boolean>): void;
/** Creates a child logger with additional context */
withContext(additionalContext: Record<string, unknown>): Logger;
/** Sets the minimum log level for this logger */
setLevel(level: LogLevel): void;
/** Sets log level for a specific component */
setComponentLevel(component: string, level: LogLevel): void;
/** Explicitly redacts a value using the configured redaction engine */
redact(value: unknown): string;
/** Adds a transport to this logger */
addTransport(transport: Transport): void;
/** Removes a transport from this logger */
removeTransport(transportName: string): boolean;
/** Flushes all transports */
flush(): Promise<void>;
/** Destroys the logger and cleans up resources */
destroy(): Promise<void>;
/** Core logging method that handles all log levels */
private log;
}
/** Creates a new standalone logger instance */
declare function createLogger(config?: LoggerConfig): Logger;
/**
* Comprehensive PII Redaction System
*
* Advanced data protection system that automatically detects and redacts personally
* identifiable information (PII) from log messages, structured data, and function
* arguments. Uses pattern matching, field name detection, and customizable rules.
*
* Features:
* - Built-in patterns for emails, phones, SSN, credit cards, API keys
* - Field name detection (password, email, token, etc.)
* - Configurable redaction modes (balanced, strict, permissive)
* - Custom redaction patterns and functions
* - Hash-based redaction for analytics preservation
* - Performance monitoring and statistics
* - Support for nested objects and arrays
*
* @example
* ```typescript
* import { RedactionEngine, redactString, redactObject } from '@nuanced-labs/lever-ui-logger';
*
* // Global redaction functions
* const safe = redactString('Contact user@example.com for help');
* // Result: "Contact <email> for help"
*
* const safeData = redactObject({
* username: 'john_doe',
* password: 'secret123',
* email: 'john@example.com',
* age: 30
* });
* // Result: { username: '<redacted>', password: '<redacted>', email: '<redacted>', age: 30 }
*
* // Custom redaction engine
* const engine = new RedactionEngine({
* enabled: true,
* mode: 'strict',
* hashRedaction: false,
* customPatterns: [{
* name: 'internal-id',
* pattern: /ID-\d{6}/g,
* replacement: '<internal-id>',
* priority: 100
* }]
* });
*
* const result = engine.redactString('User ID-123456 logged in');
* // Result: "User <internal-id> logged in"
* ```
*/
/**
* Redaction modes with different levels of protection
*/
type RedactionMode = 'strict' | 'balanced' | 'permissive' | 'off';
/**
* Performance statistics for redaction operations
*/
interface RedactionStats {
/** Total redaction operations performed */
totalOperations: number;
/** Total time spent on redaction (ms) */
totalTimeMs: number;
/** Average time per operation (ms) */
averageTimeMs: number;
/** Redactions performed by pattern name */
patternHits: Record<string, number>;
/** Field redactions by field name */
fieldHits: Record<string, number>;
}
/**
* Core redaction engine with pattern matching and field detection.
*
* Provides comprehensive PII redaction capabilities including:
* - Pattern-based string redaction (emails, phones, API keys, etc.)
* - Field name detection for sensitive data
* - Configurable redaction modes
* - Performance monitoring and statistics
* - Hash-based redaction for analytics
* - Differential privacy support
*
* @example
* ```typescript
* const engine = new RedactionEngine({
* mode: 'balanced',
* enabled: true,
* disabledPatterns: ['ipv4'] // Keep IP addresses for debugging
* });
*
* // Redact strings
* const safe = engine.redactString('Contact user@example.com for help');
* // Result: 'Contact <email> for help'
*
* // Redact objects
* const safeObj = engine.redactObject({
* username: 'john_doe',
* password: 'secret123',
* email: 'john@example.com'
* });
* // Result: { username: '<redacted>', password: '<redacted>', email: '<redacted>' }
* ```
*/
declare class RedactionEngine {
private readonly patterns;
private readonly config;
private readonly stats;
private performanceWarningThreshold;
constructor(config?: RedactionConfig);
/**
* Redacts PII from a string value using configured patterns and custom redactor.
*
* @param value - The string to redact PII from
* @returns The string with PII replaced by redaction tokens
*
* @example
* ```typescript
* const engine = new RedactionEngine();
* engine.redactString('Contact user@example.com for help');
* // Returns: 'Contact <email> for help'
*
* engine.redactString('Call us at (555) 123-4567');
* // Returns: 'Call us at <phone>'
* ```
*/
redactString(value: string): string;
/**
* Redacts PII from an object, handling nested structures and circular references.
*
* @param obj - The object to redact PII from
* @param visited - Internal WeakSet for tracking circular references
* @returns The object with PII fields and string values redacted
*
* @example
* ```typescript
* const engine = new RedactionEngine();
* const user = {
* name: 'John Doe',
* email: 'john@example.com',
* password: 'secret123',
* profile: {
* phone: '555-1234',
* bio: 'Contact me at john@example.com'
* }
* };
*
* engine.redactObject(user);
* // Returns: {
* // name: 'John Doe',
* // email: '<redacted>', // Field name detected
* // password: '<redacted>', // Field name detected
* // profile: {
* // phone: '<redacted>', // Field name detected
* // bio: 'Contact me at <email>' // Pattern matched
* // }
* // }
* ```
*/
redactObject(obj: unknown, visited?: WeakSet<object>): unknown;
/**
* Redacts PII from log arguments array, processing each argument as an object.
*
* @param args - Array of log arguments to redact
* @returns Array with PII redacted from each argument
*
* @example
* ```typescript
* const engine = new RedactionEngine();
* const logArgs = [
* 'User logged in',
* { email: 'user@example.com', token: 'abc123' },
* 'Session started at user@example.com'
* ];
*
* engine.redactArgs(logArgs);
* // Returns: [
* // 'User logged in',
* // { email: '<redacted>', token: '<redacted>' },
* // 'Session started at <email>'
* // ]
* ```
*/
redactArgs(args: readonly unknown[]): readonly unknown[];
/**
* Adds Laplace noise to numeric values for differential privacy protection.
*
* @param value - The numeric value to add noise to
* @param epsilon - Privacy budget parameter (default: 1.0, lower = more privacy)
* @returns The value with differential privacy noise added
*
* @example
* ```typescript
* const engine = new RedactionEngine({ differentialPrivacy: true });
*
* // Add noise with default epsilon (1.0)
* const noisyValue = engine.addDifferentialPrivacyNoise(100);
* // Returns: ~99.83 (varies each call)
*
* // More privacy (more noise) with lower epsilon
* const privateValue = engine.addDifferentialPrivacyNoise(100, 0.1);
* // Returns: ~107.42 (varies each call, larger deviation)
* ```
*/
addDifferentialPrivacyNoise(value: number, epsilon?: number): number;
/**
* Gets current redaction statistics including operation counts and performance metrics.
*
* @returns Copy of current redaction statistics
*
* @example
* ```typescript
* const engine = new RedactionEngine();
* engine.redactString('Contact user@example.com');
* engine.redactString('Call (555) 123-4567');
*
* const stats = engine.getStats();
* // Returns: {
* // totalOperations: 2,
* // totalTimeMs: 0.43,
* // averageTimeMs: 0.215,
* // patternHits: { email: 1, 'phone-us': 1 },
* // fieldHits: {}
* // }
* ```
*/
getStats(): RedactionStats;
/**
* Resets redaction statistics to initial values.
*
* @example
* ```typescript
* const engine = new RedactionEngine();
* engine.redactString('user@example.com'); // Creates stats
*
* console.log(engine.getStats().totalOperations); // 1
* engine.resetStats();
* console.log(engine.getStats().totalOperations); // 0
* ```
*/
resetStats(): void;
/**
* Validates potential PII in development mode, checking against all patterns.
*
* @param value - String to validate for potential PII
* @param context - Optional context description for warnings
* @returns Array of warning messages for detected PII patterns
*
* @example
* ```typescript
* const engine = new RedactionEngine();
* const warnings = engine.validateForPII(
* 'Contact user@example.com or call 555-1234',
* 'user input'
* );
*
* // Returns: [
* // 'Potential Email addresses detected in user input: email',
* // 'Potential US phone numbers detected in user input: phone-us'
* // ]
* ```
*/
validateForPII(value: string, context?: string): string[];
/**
* Merges user configuration with defaults
*/
private mergeConfig;
/**
* Initializes redaction patterns based on configuration
*/
private initializePatterns;
/**
* Filters patterns based on redaction mode
*/
private filterPatternsByMode;
/**
* Hash-based redaction for analytics preservation
*/
private hashValue;
/**
* Updates performance statistics
*/
private updateStats;
/**
* Initializes statistics tracking
*/
private initializeStats;
}
/**
* Gets or creates the global redaction engine instance.
*
* @param config - Optional configuration to create new engine with
* @returns Global redaction engine instance
*
* @example
* ```typescript
* // Get default engine
* const engine = getRedactionEngine();
*
* // Create new engine with custom config
* const strictEngine = getRedactionEngine({ mode: 'strict' });
* ```
*/
declare function getRedactionEngine(config?: RedactionConfig): RedactionEngine;
/**
* Convenience function for redacting strings using the global engine.
*
* @param value - String to redact PII from
* @param config - Optional configuration for custom redaction behavior
* @returns String with PII redacted
*
* @example
* ```typescript
* import { redactString } from '@nuanced-labs/lever-ui-logger';
*
* const safe = redactString('Contact user@example.com for help');
* // Returns: 'Contact <email> for help'
*
* const strictSafe = redactString('Call 555-1234', { mode: 'strict' });
* // Returns: 'Call <phone>'
* ```
*/
declare function redactString(value: string, config?: RedactionConfig): string;
/**
* Convenience function for redacting objects using the global engine.
*
* @param obj - Object to redact PII from
* @param config - Optional configuration for custom redaction behavior
* @returns Object with PII redacted
*
* @example
* ```typescript
* import { redactObject } from '@nuanced-labs/lever-ui-logger';
*
* const user = { email: 'user@example.com', password: 'secret' };
* const safe = redactObject(user);
* // Returns: { email: '<redacted>', password: '<redacted>' }
*
* const hashRedacted = redactObject(user, { hashRedaction: true });
* // Returns: { email: '<hash:a1b2c3d4>', password: '<hash:e5f6g7h8>' }
* ```
*/
declare function redactObject(obj: unknown, config?: RedactionConfig): unknown;
/**
* Convenience function for redacting log arguments using the global engine.
*
* @param args - Array of log arguments to redact
* @param config - Optional configuration for custom redaction behavior
* @returns Array with PII redacted from each argument
*
* @example
* ```typescript
* import { redactArgs } from '@nuanced-labs/lever-ui-logger';
*
* const logArgs = [
* 'Login attempt',
* { user: 'john@example.com', ip: '192.168.1.1' },
* 'Session token: abc123xyz'
* ];
*
* const safe = redactArgs(logArgs);
* // Returns: [
* // 'Login attempt',
* // { user: '<redacted>', ip: '192.168.1.1' }, // IP not redacted in balanced mode
* // 'Session token: abc123xyz'
* // ]
* ```
*/
declare function redactArgs(args: readonly unknown[], config?: RedactionConfig): readonly unknown[];
/**
* Built-in redaction patterns for common PII types
*/
interface BuiltInRedactionPattern {
/** Pattern name for debugging and configuration */
name: string;
/** Regular expression to match PII */
pattern: RegExp;
/** Replacement text (can include capture groups) */
replacement: string;
/** Description of what this pattern detects */
description: string;
/** Whether this pattern is enabled by default */
defaultEnabled: boolean;
/** Performance category for priority ordering */
priority: 'high' | 'medium' | 'low';
}
/**
* Built-in PII detection patterns
* Ordered by detection priority (high performance patterns first)
*/
declare const BUILT_IN_PATTERNS: readonly BuiltInRedactionPattern[];
/**
* Field names that commonly contain PII
* These trigger redaction regardless of content
*/
declare const PII_FIELD_NAMES: readonly string[];
/**
* Creates a case-insensitive field name matcher.
* Uses exact matches and common patterns to avoid false positives.
*
* @param fieldName - The field name to check for PII indicators
* @returns True if the field name indicates it may contain PII
*
* @example
* ```typescript
* isPIIFieldName('password'); // true
* isPIIFieldName('userId'); // true
* isPIIFieldName('userPassword'); // true (camelCase)
* isPIIFieldName('user_email'); // true (underscore)
* isPIIFieldName('auth-token'); // true (hyphen)
* isPIIFieldName('message'); // false
* isPIIFieldName('timestamp'); // false
* ```
*/
declare function isPIIFieldName(fieldName: string): boolean;
/**
* Gets enabled patterns based on configuration.
*
* @param enabledPatterns - Specific patterns to enable (overrides defaults)
* @param disabledPatterns - Specific patterns to disable
* @returns Array of enabled redaction patterns
*
* @example
* ```typescript
* // Get all default enabled patterns
* const defaultPatterns = getEnabledPatterns();
*
* // Only enable specific patterns
* const emailOnly = getEnabledPatterns(['email']);
*
* // Enable defaults except IP addresses
* const noIPs = getEnabledPatterns(undefined, ['ipv4', 'ipv6']);
* ```
*/
declare function getEnabledPatterns(enabledPatterns?: string[], disabledPatterns?: string[]): BuiltInRedactionPattern[];
/**
* Sorts patterns by priority for optimal performance.
* High priority patterns are processed first for better performance.
*
* @param patterns - Array of redaction patterns to sort
* @returns Sorted array with high priority patterns first
*
* @example
* ```typescript
* const unsorted = [
* { name: 'low-pattern', priority: 'low', ... },
* { name: 'high-pattern', priority: 'high', ... },
* { name: 'medium-pattern', priority: 'medium', ... }
* ];
* const sorted = sortPatternsByPriority(unsorted);
* // Result: [high-pattern, medium-pattern, low-pattern]
* ```
*/
declare function sortPatternsByPriority(patterns: BuiltInRedactionPattern[]): BuiltInRedactionPattern[];
/**
* Lever UI Logger - Standalone logging with PII redaction
*
* A zero-dependency logging system with optional EventBus integration
* via transports. Includes built-in PII redaction capabilities.
*
* @example
* ```typescript
* import { createLogger, ConsoleTransport } from 'lever-ui-logger';
*
* // Standalone logger
* const logger = createLogger({
* level: 'debug',
* component: 'my-service',
* transports: [new ConsoleTransport()]
* });
*
* logger.info('User action completed', { userId: '123', action: 'login' });
* ```
*/
/** Current version of the logger package */
declare const LOGGER_VERSION = "0.1.0";
export { BUILT_IN_PATTERNS, type BuiltInRedactionPattern, DEFAULT_LOGGER_CONFIG, DEFAULT_LOG_LEVEL, type ErrorData, ErrorEvent, LOGGER_VERSION, LOG_LEVEL_PRIORITY, LogEvent, type LogEventData, type LogLevel, type Logger, LoggerBaseEvent, type LoggerConfig, LoggerConfigChangedEvent, LoggerCreatedEvent, LoggerDestroyedEvent, type LoggerFactory, LoggerImpl, type MetricData, MetricEvent, PIIWarningEvent, PII_FIELD_NAMES, type RedactionConfig, RedactionEngine, type RedactionMode, type RedactionPattern, type RedactionStats, type Transport, TransportErrorEvent, TransportEvent, createLogger, getEnabledPatterns, getRedactionEngine, isErrorEvent, isLogEvent, isLoggerEvent, isMetricEvent, isPIIFieldName, mergeConfig, passesSampling, redactArgs, redactObject, redactString, shouldLog, sortPatternsByPriority };