lever-ui-logger
Version:
Zero-dependency logging library with optional EventBus integration. Built-in PII redaction, multiple transports, and comprehensive logging capabilities.
225 lines • 8.58 kB
TypeScript
/**
* EventBus integration event classes following lever-ui-eventbus patterns
* All events follow the class-based event pattern with public readonly properties
*/
import type { LogLevel, LogEventData, MetricData, ErrorData } from './types.js';
/**
* 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"
* ```
*/
export 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' });
* ```
*/
export 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
* });
* ```
*/
export 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
*/
export 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
*/
export 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
*/
export 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
*/
export 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
*/
export 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
*/
export 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
*/
export 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
*/
export declare function isLogEvent(event: unknown): event is LogEvent;
/**
* Type guard to check if an event is a MetricEvent
*/
export declare function isMetricEvent(event: unknown): event is MetricEvent;
/**
* Type guard to check if an event is an ErrorEvent
*/
export declare function isErrorEvent(event: unknown): event is ErrorEvent;
/**
* Type guard to check if an event is any logger-related event
*/
export declare function isLoggerEvent(event: unknown): event is LoggerBaseEvent;
//# sourceMappingURL=events.d.ts.map