lifecycleion 0.0.1

package/dist/lib/logger/index.d.cts

@@ -0,0 +1,630 @@
+import { EventEmitter } from '../event-emitter.cjs';
+
+/**
+ * Log level enum for filtering logs by severity
+ * Lower numbers = more important/higher priority
+ * Higher numbers = less important/lower priority
+ */
+declare enum LogLevel {
+    ERROR = 0,
+    WARN = 1,
+    NOTICE = 2,// Normal but significant condition
+    SUCCESS = 3,
+    INFO = 3,// Same level as SUCCESS (routine operational info)
+    DEBUG = 4,
+    RAW = 99
+}
+/**
+ * Log level types
+ */
+type LogType = 'error' | 'info' | 'warn' | 'success' | 'notice' | 'debug' | 'raw';
+/**
+ * Maps a LogType to its corresponding LogLevel
+ */
+declare function getLogLevel(type: LogType): LogLevel;
+/**
+ * Options for log methods
+ */
+interface LogOptions {
+    exitCode?: number;
+    params?: Record<string, unknown>;
+    tags?: string[];
+    redactedKeys?: string[];
+}
+/**
+ * Complete log entry that gets passed to sinks
+ */
+interface LogEntry {
+    timestamp: number;
+    type: LogType;
+    serviceName?: string;
+    entityName?: string;
+    template: string;
+    message: string;
+    params?: Record<string, unknown>;
+    redactedParams?: Record<string, unknown>;
+    redactedKeys?: string[];
+    error?: unknown;
+    exitCode?: number;
+    tags?: string[];
+}
+/**
+ * Sink interface - all sinks must implement this
+ */
+interface LogSink {
+    write(entry: LogEntry): void | Promise<void>;
+    close?(): void | Promise<void>;
+}
+/**
+ * Result from beforeExit callback indicating whether to proceed with exit
+ */
+interface BeforeExitResult {
+    /**
+     * Whether to proceed with the exit
+     * - 'proceed': Continue with process exit
+     * - 'wait': Shutdown is already in progress, wait for it to complete
+     */
+    action: 'proceed' | 'wait';
+}
+/**
+ * Redaction function type
+ */
+type RedactFunction = (keyName: string, value: unknown) => unknown;
+/**
+ * Array log transformer function type.
+ * Receives a log entry and returns either a transformed entry or false to keep the original.
+ */
+type ArrayLogTransformer = (entry: LogEntry) => LogEntry | false;
+/**
+ * Main logger configuration options
+ */
+interface LoggerOptions {
+    sinks?: LogSink[];
+    redactFunction?: RedactFunction;
+    callProcessExit?: boolean;
+    beforeExitCallback?: (exitCode: number, isFirstExit: boolean) => BeforeExitResult | Promise<BeforeExitResult>;
+    onSinkError?: (error: Error, context: 'write' | 'close', sink: LogSink) => void;
+}
+/**
+ * Logger event types
+ */
+interface LoggerEventMap {
+    log: {
+        eventType: 'log';
+        logType: LogType;
+        message: string;
+        timestamp: number;
+    };
+    'exit-called': {
+        eventType: 'exit-called';
+        code: number;
+        isFirstExit: boolean;
+    };
+    'exit-process': {
+        eventType: 'exit-process';
+        code: number;
+    };
+    uncaughtException: {
+        eventType: 'uncaughtException';
+        error: Error;
+    };
+    close: {
+        eventType: 'close';
+    };
+}
+type LoggerEvent = LoggerEventMap[keyof LoggerEventMap];
+
+/**
+ * Internal types used by Logger and LoggerService
+ * These are not part of the public API
+ */
+
+/**
+ * Internal options for handleLog method
+ * Extends LogOptions with internal-only fields
+ */
+interface HandleLogOptions extends LogOptions {
+    serviceName?: string;
+    entityName?: string;
+    error?: unknown;
+}
+
+/**
+ * ArraySink stores logs in memory for testing and debugging
+ */
+declare class ArraySink implements LogSink {
+    logs: LogEntry[];
+    private transformer?;
+    private closed;
+    constructor(options?: {
+        transformer?: ArrayLogTransformer;
+    });
+    write(entry: LogEntry): void;
+    /**
+     * Clear all stored logs
+     */
+    clear(): void;
+    /**
+     * Get logs in a snapshot-friendly format for testing
+     */
+    getSnapshotFriendlyLogs(): string[];
+    /**
+     * Close the sink and stop accepting new logs
+     */
+    close(): void;
+}
+
+interface ConsoleSinkOptions {
+    colors?: boolean;
+    timestamps?: boolean;
+    typeLabels?: boolean;
+    muted?: boolean;
+    minLevel?: LogLevel;
+}
+/**
+ * ConsoleSink writes logs to the console with optional colors, timestamps, and type labels
+ */
+declare class ConsoleSink implements LogSink {
+    private colors;
+    private timestamps;
+    private typeLabels;
+    private closed;
+    private muted;
+    private minLevel;
+    constructor(options?: ConsoleSinkOptions);
+    write(entry: LogEntry): void;
+    /**
+     * Set the minimum log level for this sink
+     */
+    setMinLevel(level: LogLevel): void;
+    /**
+     * Get the current minimum log level
+     */
+    getMinLevel(): LogLevel;
+    /**
+     * Mute the sink to stop writing logs to console
+     */
+    mute(): void;
+    /**
+     * Unmute the sink to resume writing logs to console
+     */
+    unmute(): void;
+    /**
+     * Check if the sink is currently muted
+     */
+    isMuted(): boolean;
+    /**
+     * Close the sink and stop accepting new logs
+     */
+    close(): void;
+}
+
+/**
+ * LoggerService for scoped logging with service names
+ */
+declare class LoggerService {
+    private handleLog;
+    private serviceName;
+    private entityName?;
+    constructor(handleLog: (type: LogType, template: string, options?: HandleLogOptions) => void, serviceName: string, entityName?: string);
+    /**
+     * Create a scoped logger for a specific entity within this service
+     */
+    entity(entityName: string): LoggerService;
+    /**
+     * Log an error message
+     */
+    error(message: string, options?: LogOptions): void;
+    /**
+     * Log an error object with optional prefix
+     */
+    errorObject(prefix: string, error: unknown, options?: LogOptions): void;
+    /**
+     * Log an informational message
+     */
+    info(message: string, options?: LogOptions): void;
+    /**
+     * Log a warning message
+     */
+    warn(message: string, options?: LogOptions): void;
+    /**
+     * Log a success message
+     */
+    success(message: string, options?: LogOptions): void;
+    /**
+     * Log a notice message
+     */
+    notice(message: string, options?: LogOptions): void;
+    /**
+     * Log a debug message
+     */
+    debug(message: string, options?: LogOptions): void;
+    /**
+     * Log a raw message without any formatting
+     */
+    raw(message: string, options?: LogOptions): void;
+}
+
+interface FileSinkOptions {
+    logDir: string;
+    basename: string;
+    maxSizeMB?: number;
+    jsonFormat?: boolean;
+    maxRetries?: number;
+    closeTimeoutMS?: number;
+    minLevel?: LogLevel;
+    onError?: (error: Error, entry: LogEntry, attempt: number, willRetry: boolean) => void;
+}
+interface FileSinkHealth {
+    isHealthy: boolean;
+    queueSize: number;
+    lastError?: Error;
+    consecutiveFailures: number;
+    isInitialized: boolean;
+}
+interface FlushResult {
+    success: boolean;
+    entriesWritten: number;
+    entriesFailed: number;
+    timedOut: boolean;
+}
+/**
+ * FileSink writes logs to files with automatic rotation based on size and date
+ */
+declare class FileSink implements LogSink {
+    private logDir;
+    private basename;
+    private maxSizeMB;
+    private jsonFormat;
+    private maxRetries;
+    private minLevel;
+    private onError?;
+    private logFileStream?;
+    private currentLogFile?;
+    private currentLogSize;
+    private writeQueue;
+    private isInitialized;
+    private initPromise?;
+    private isProcessing;
+    private lastError?;
+    private consecutiveFailures;
+    private totalEntriesWritten;
+    private totalEntriesFailed;
+    private closing;
+    private closed;
+    private closeTimeoutMS;
+    constructor(options: FileSinkOptions);
+    write(entry: LogEntry): void;
+    /**
+     * Set the minimum log level for this sink
+     */
+    setMinLevel(level: LogLevel): void;
+    /**
+     * Get the current minimum log level
+     */
+    getMinLevel(): LogLevel;
+    /**
+     * Get current health status of the sink
+     */
+    getHealth(): FileSinkHealth;
+    /**
+     * Flush all pending writes and wait for completion
+     * Returns statistics about the flush operation
+     * @param timeoutMS Maximum time to wait in milliseconds (default: 30000ms / 30s)
+     */
+    flush(timeoutMS?: number): Promise<FlushResult>;
+    /**
+     * Close the log file and wait for all pending writes
+     */
+    close(): Promise<void>;
+    /**
+     * Initialize the file sink asynchronously
+     */
+    private initialize;
+    /**
+     * Process the write queue
+     * Processes entries one at a time with retry logic
+     */
+    private processQueue;
+    /**
+     * Write a single entry to the file
+     * If stream is broken, it will be recreated on next attempt
+     */
+    private writeEntry;
+    /**
+     * Format a log entry for file output
+     */
+    private formatEntry;
+    /**
+     * Setup the log file
+     */
+    private setupLogFile;
+    /**
+     * Destroy the current stream
+     */
+    private destroyStream;
+    /**
+     * Rotate log file if needed based on size or date
+     */
+    private rotateIfNeeded;
+    /**
+     * Rotate the current log file
+     * Queue processing pauses during rotation, then resumes
+     */
+    private rotateFile;
+}
+
+/**
+ * Types of pipe errors that can occur
+ */
+declare enum PipeErrorType {
+    WRITE = "write",
+    CLOSE = "close",
+    NOT_FOUND = "not_found",
+    NOT_A_PIPE = "not_a_pipe",
+    PERMISSION = "permission",
+    UNSUPPORTED_PLATFORM = "unsupported_platform"
+}
+interface NamedPipeSinkOptions {
+    pipePath: string;
+    jsonFormat?: boolean;
+    closeTimeoutMS?: number;
+    onError?: (errorType: PipeErrorType, error: Error, pipePath: string) => void;
+    formatter?: (entry: LogEntry) => string;
+}
+type ReconnectStatus = {
+    success: true;
+} | {
+    success: false;
+    reason: 'already_reconnecting';
+} | {
+    success: false;
+    reason: 'error';
+    error: Error;
+};
+/**
+ * NamedPipeSink writes logs to a named pipe (FIFO)
+ * Only supported on Linux and macOS
+ */
+declare class NamedPipeSink implements LogSink {
+    private pipePath;
+    private jsonFormat;
+    private onError?;
+    private formatter?;
+    private pipeStream?;
+    private writeQueue;
+    private isInitialized;
+    private _isReconnecting;
+    private initPromise;
+    private closing;
+    private closed;
+    private closeTimeoutMS;
+    constructor(options: NamedPipeSinkOptions);
+    write(entry: LogEntry): void;
+    /**
+     * Attempt to reconnect to the named pipe.
+     * Useful when the pipe reader restarts or after a temporary error.
+     * Queued writes during the outage will be flushed on successful reconnection.
+     */
+    get isReconnecting(): boolean;
+    reconnect(): Promise<ReconnectStatus>;
+    close(): Promise<void>;
+    /**
+     * Initialize the named pipe connection
+     */
+    private initializePipe;
+    /**
+     * Process queued entries
+     */
+    private processQueue;
+    /**
+     * Write a single entry
+     */
+    private writeEntry;
+    /**
+     * Format a log entry for pipe output
+     */
+    private formatEntry;
+    /**
+     * Handle errors
+     */
+    private handleError;
+}
+
+/**
+ * Main Logger class with sink-based architecture and EventEmitter support
+ */
+declare class Logger extends EventEmitter {
+    readonly isLoggerClass = true;
+    private sinks;
+    private redactFunction?;
+    private callProcessExit;
+    private beforeExitCallback?;
+    private onSinkError?;
+    private _didExit;
+    private _exitCode;
+    private _exitRequested;
+    private _isPendingExit;
+    private _closed;
+    private _reportErrorListenerRegistered;
+    private _reportErrorListener;
+    constructor(options?: LoggerOptions);
+    get didExit(): boolean;
+    get exitCode(): number;
+    get isPendingExit(): boolean;
+    get hasExitedOrPending(): boolean;
+    get closed(): boolean;
+    /**
+     * Exit the process with the specified code
+     */
+    exit(code: number): void;
+    /**
+     * Set or update the beforeExit callback
+     *
+     * This allows setting the callback after Logger construction, which is useful
+     * when the callback needs to reference objects that depend on the Logger instance.
+     *
+     * **Note:** This method overwrites any existing beforeExit callback (including
+     * one set in the Logger constructor). Pass `undefined` to remove the callback.
+     *
+     * **Error Handling:** If the callback throws an error or rejects, the logger will
+     * proceed with exit anyway to prevent the process from hanging. The error will be
+     * reported via the global `reportError` event.
+     *
+     * @param callback - Function to call before process exit (receives exitCode and isFirstExit).
+     *                   Must return BeforeExitResult indicating whether to proceed with exit or wait.
+     *                   Return `{ action: 'proceed' }` to continue with exit.
+     *                   Return `{ action: 'wait' }` to prevent exit (e.g., shutdown already in progress).
+     *                   If the callback throws, exit proceeds automatically.
+     *
+     *                   Pass undefined to remove the callback.
+     *
+     * @example
+     * ```typescript
+     * const logger = new Logger();
+     * const lifecycle = new LifecycleManager({ logger });
+     *
+     * // Set callback after both are constructed
+     * logger.setBeforeExitCallback(async (exitCode, isFirstExit) => {
+     *   if (isFirstExit) {
+     *     await lifecycle.stopAllComponents();
+     *   }
+     *   return { action: 'proceed' };
+     * });
+     *
+     * // Later, remove the callback
+     * logger.setBeforeExitCallback(undefined);
+     * ```
+     */
+    setBeforeExitCallback(callback: ((exitCode: number, isFirstExit: boolean) => BeforeExitResult | Promise<BeforeExitResult>) | undefined): void;
+    /**
+     * Log an error message
+     */
+    error(message: string, options?: LogOptions): void;
+    /**
+     * Log an error object with optional prefix
+     */
+    errorObject(prefix: string, error: unknown, options?: LogOptions): void;
+    /**
+     * Log an informational message
+     */
+    info(message: string, options?: LogOptions): void;
+    /**
+     * Log a warning message
+     */
+    warn(message: string, options?: LogOptions): void;
+    /**
+     * Log a success message
+     */
+    success(message: string, options?: LogOptions): void;
+    /**
+     * Log a notice message
+     */
+    notice(message: string, options?: LogOptions): void;
+    /**
+     * Log a debug message
+     */
+    debug(message: string, options?: LogOptions): void;
+    /**
+     * Log a raw message without any formatting
+     */
+    raw(message: string, options?: LogOptions): void;
+    /**
+     * Create a scoped logger with a service name
+     */
+    service(serviceName: string): LoggerService;
+    /**
+     * Registers a listener for the 'reportError' event.
+     *
+     * If the listener is already registered, it returns 'already_registered'.
+     * If 'globalThis.reportError' is not available, it returns 'not_available'.
+     * Otherwise, it registers the listener and returns 'success'.
+     *
+     * @param prefix - The prefix to use when logging the error object. Default is 'Uncaught exception'.
+     * @returns 'success' if the listener is registered successfully,
+     *          'already_registered' if the listener is already registered,
+     *          'not_available' if 'globalThis.reportError' is not available.
+     */
+    registerReportErrorListener(prefix?: string): 'success' | 'already_registered' | 'not_available';
+    /**
+     * Unregister the listener for the 'reportError' event.
+     *
+     * If the listener is not registered, it returns 'not_registered'.
+     * Otherwise, it unregister the listener and returns 'success'.
+     *
+     * @returns 'success' if the listener is unregistered successfully,
+     *          'not_registered' if the listener is not registered.
+     */
+    unregisterReportErrorListener(): 'success' | 'not_registered';
+    /**
+     * Check if the 'reportError' event listener is registered
+     *
+     * @returns 'true' if the listener is registered, 'false' otherwise.
+     */
+    isReportErrorListenerRegistered(): boolean;
+    /**
+     * Check if 'globalThis.reportError' is available
+     *
+     * @returns 'true' if 'globalThis.reportError' is available, 'false' otherwise.
+     */
+    isReportErrorAvailable(): boolean;
+    /**
+     * Add a sink to the logger
+     */
+    addSink(sink: LogSink): void;
+    /**
+     * Remove a sink from the logger
+     * Returns true if the sink was found and removed, false otherwise
+     */
+    removeSink(sink: LogSink): boolean;
+    /**
+     * Get a readonly copy of the current sinks
+     */
+    getSinks(): readonly LogSink[];
+    /**
+     * Close all sinks and cleanup resources
+     * After closing, the logger is marked as closed and all sinks are removed
+     */
+    close(): Promise<void>;
+    /**
+     * Create a logger optimized for testing.
+     * Includes an ArraySink by default for easy log inspection.
+     * Process exit is disabled to prevent tests from terminating.
+     */
+    static createTestOptimizedLogger(options?: {
+        sinks?: LogSink[];
+        arrayLogTransformer?: (entry: LogEntry) => LogEntry | false;
+        includeConsoleSink?: boolean;
+        muteConsole?: boolean;
+    }): {
+        logger: Logger;
+        arraySink: ArraySink;
+        consoleSink?: ConsoleSink;
+    };
+    /**
+     * Create a logger optimized for frontend/browser use.
+     * Includes a ConsoleSink by default for browser devtools output.
+     * Process exit is disabled since browsers don't have process.exit.
+     */
+    static createFrontendOptimizedLogger(options?: {
+        sinks?: LogSink[];
+        muteConsole?: boolean;
+    }): {
+        logger: Logger;
+        consoleSink: ConsoleSink;
+    };
+    /**
+     * Internal method to handle all log operations
+     */
+    protected handleLog(type: LogType, template: string, options?: HandleLogOptions): void;
+    /**
+     * Handle sink errors by calling the onSinkError callback or falling back to console.error
+     */
+    private handleSinkError;
+    /**
+     * Process the exit
+     */
+    private processExit;
+}
+
+export { type ArrayLogTransformer, ArraySink, type BeforeExitResult, ConsoleSink, type ConsoleSinkOptions, FileSink, type FileSinkOptions, type LogEntry, LogLevel, type LogOptions, type LogSink, type LogType, Logger, type LoggerEvent, type LoggerEventMap, type LoggerOptions, LoggerService, NamedPipeSink, type NamedPipeSinkOptions, PipeErrorType, type ReconnectStatus, type RedactFunction, getLogLevel };