@nahisaho/musubix-core 1.0.0

package/dist/utils/structured-logger.d.ts

@@ -0,0 +1,294 @@
+/**
+ * Structured Logger (Extended)
+ *
+ * Advanced structured logging with context, correlation, and output formatting
+ *
+ * @packageDocumentation
+ * @module utils/structured-logger
+ *
+ * @see REQ-MNT-001 - Logging & Monitoring
+ * @see Article VI - Decision Transparency
+ */
+/**
+ * Log level
+ */
+export type LogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'fatal';
+/**
+ * Log level values
+ */
+export declare const LOG_LEVEL_VALUES: Record<LogLevel, number>;
+/**
+ * Output format
+ */
+export type OutputFormat = 'json' | 'pretty' | 'compact' | 'logfmt';
+/**
+ * Log transport
+ */
+export type TransportType = 'console' | 'file' | 'http' | 'memory' | 'custom';
+/**
+ * Log entry
+ */
+export interface LogEntry {
+    /** Timestamp */
+    timestamp: Date;
+    /** Level */
+    level: LogLevel;
+    /** Message */
+    message: string;
+    /** Logger name */
+    logger: string;
+    /** Correlation ID */
+    correlationId?: string;
+    /** Request ID */
+    requestId?: string;
+    /** User ID */
+    userId?: string;
+    /** Context data */
+    context?: Record<string, unknown>;
+    /** Error info */
+    error?: {
+        name: string;
+        message: string;
+        stack?: string;
+        code?: string;
+    };
+    /** Duration (ms) */
+    duration?: number;
+    /** Tags */
+    tags?: string[];
+    /** Metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Transport interface
+ */
+export interface LogTransport {
+    /** Transport name */
+    name: string;
+    /** Transport type */
+    type: TransportType;
+    /** Log entry */
+    log(entry: LogEntry): void | Promise<void>;
+    /** Flush */
+    flush?(): void | Promise<void>;
+    /** Close */
+    close?(): void | Promise<void>;
+}
+/**
+ * Logger config
+ */
+export interface StructuredLoggerConfig {
+    /** Logger name */
+    name: string;
+    /** Minimum level */
+    level: LogLevel;
+    /** Output format */
+    format: OutputFormat;
+    /** Include timestamp */
+    includeTimestamp: boolean;
+    /** Include caller info */
+    includeCaller: boolean;
+    /** Pretty print objects */
+    prettyPrint: boolean;
+    /** Color output */
+    colorOutput: boolean;
+    /** Default context */
+    defaultContext?: Record<string, unknown>;
+    /** Redact fields */
+    redactFields?: string[];
+    /** Max context depth */
+    maxContextDepth: number;
+}
+/**
+ * Default configuration
+ */
+export declare const DEFAULT_LOGGER_CONFIG: StructuredLoggerConfig;
+/**
+ * Console transport
+ */
+export declare class ConsoleTransport implements LogTransport {
+    name: string;
+    type: TransportType;
+    private config;
+    constructor(config: StructuredLoggerConfig);
+    log(entry: LogEntry): void;
+    private format;
+    private toJSON;
+    private toPretty;
+    private toCompact;
+    private toLogfmt;
+    private escapeLogfmt;
+}
+/**
+ * Memory transport (for testing)
+ */
+export declare class MemoryTransport implements LogTransport {
+    name: string;
+    type: TransportType;
+    entries: LogEntry[];
+    maxEntries: number;
+    constructor(maxEntries?: number);
+    log(entry: LogEntry): void;
+    clear(): void;
+    getEntries(filter?: {
+        level?: LogLevel;
+        logger?: string;
+    }): LogEntry[];
+}
+/**
+ * Structured Logger
+ */
+export declare class StructuredLogger {
+    private config;
+    private transports;
+    private contextStack;
+    private correlationId?;
+    private requestId?;
+    private userId?;
+    constructor(config?: Partial<StructuredLoggerConfig>);
+    /**
+     * Add transport
+     */
+    addTransport(transport: LogTransport): void;
+    /**
+     * Remove transport
+     */
+    removeTransport(name: string): void;
+    /**
+     * Create child logger with additional context
+     */
+    child(context: Record<string, unknown>): StructuredLogger;
+    /**
+     * Set correlation ID
+     */
+    setCorrelationId(id: string): void;
+    /**
+     * Set request ID
+     */
+    setRequestId(id: string): void;
+    /**
+     * Set user ID
+     */
+    setUserId(id: string): void;
+    /**
+     * Push context
+     */
+    pushContext(context: Record<string, unknown>): void;
+    /**
+     * Pop context
+     */
+    popContext(): Record<string, unknown> | undefined;
+    /**
+     * Log at trace level
+     */
+    trace(message: string, context?: Record<string, unknown>): void;
+    /**
+     * Log at debug level
+     */
+    debug(message: string, context?: Record<string, unknown>): void;
+    /**
+     * Log at info level
+     */
+    info(message: string, context?: Record<string, unknown>): void;
+    /**
+     * Log at warn level
+     */
+    warn(message: string, context?: Record<string, unknown>): void;
+    /**
+     * Log at error level
+     */
+    error(message: string, error?: Error | Record<string, unknown>, context?: Record<string, unknown>): void;
+    /**
+     * Log at fatal level
+     */
+    fatal(message: string, error?: Error | Record<string, unknown>, context?: Record<string, unknown>): void;
+    /**
+     * Log with timing
+     */
+    timed<T>(level: LogLevel, message: string, fn: () => T, context?: Record<string, unknown>): T;
+    /**
+     * Log with async timing
+     */
+    timedAsync<T>(level: LogLevel, message: string, fn: () => Promise<T>, context?: Record<string, unknown>): Promise<T>;
+    /**
+     * Create scoped logger for a specific operation
+     */
+    scope(operation: string, metadata?: Record<string, unknown>): ScopedLogger;
+    /**
+     * Core log method
+     */
+    private log;
+    /**
+     * Build merged context
+     */
+    private buildContext;
+    /**
+     * Redact sensitive fields
+     */
+    private redactSensitive;
+    /**
+     * Flush all transports
+     */
+    flush(): Promise<void>;
+    /**
+     * Close all transports
+     */
+    close(): Promise<void>;
+    /**
+     * Set log level
+     */
+    setLevel(level: LogLevel): void;
+    /**
+     * Get log level
+     */
+    getLevel(): LogLevel;
+    /**
+     * Check if level is enabled
+     */
+    isLevelEnabled(level: LogLevel): boolean;
+}
+/**
+ * Scoped logger for operations
+ */
+export declare class ScopedLogger {
+    private logger;
+    private operation;
+    private metadata?;
+    private startTime;
+    private steps;
+    private lastStepTime;
+    constructor(logger: StructuredLogger, operation: string, metadata?: Record<string, unknown>);
+    /**
+     * Log a step
+     */
+    step(name: string, context?: Record<string, unknown>): void;
+    /**
+     * Log success
+     */
+    success(result?: unknown, context?: Record<string, unknown>): void;
+    /**
+     * Log failure
+     */
+    failure(error: Error, context?: Record<string, unknown>): void;
+    /**
+     * Log progress
+     */
+    progress(current: number, total: number, message?: string): void;
+}
+/**
+ * Create structured logger instance
+ */
+export declare function createStructuredLogger(config?: Partial<StructuredLoggerConfig>): StructuredLogger;
+/**
+ * Global logger instance
+ */
+export declare const logger: StructuredLogger;
+/**
+ * Request context helper
+ */
+export declare function withRequestContext<T>(logger: StructuredLogger, correlationId: string, requestId: string, fn: (logger: StructuredLogger) => T): T;
+/**
+ * Generate correlation ID
+ */
+export declare function generateCorrelationId(): string;
+//# sourceMappingURL=structured-logger.d.ts.map

package/dist/utils/structured-logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"structured-logger.d.ts","sourceRoot":"","sources":["../../src/utils/structured-logger.ts"],"names":[],"mappings":"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"}