@ncoderz/log-m8 1.0.1

package/dist/index.d.ts

@@ -0,0 +1,1276 @@
+/**
+ * Contextual metadata automatically included with all log events from a logger.
+ *
+ * LogContext provides a way to associate persistent metadata with logger instances
+ * that gets automatically included with every log event. This is useful for
+ * tracking request IDs, user sessions, service names, or any other contextual
+ * information that should be consistent across related log entries.
+ *
+ * Context is set via logger.setContext() and can contain both predefined
+ * properties and arbitrary key-value pairs. Formatters can access context
+ * properties using dot-path notation (e.g., {context.requestId}).
+ *
+ * @example
+ * ```typescript
+ * const logger = Logging.getLogger('api.auth');
+ *
+ * // Set context that applies to all subsequent log events
+ * logger.setContext({
+ *   requestId: 'req-123',
+ *   userId: 'user-456',
+ *   sessionId: 'sess-789',
+ *   service: 'authentication'
+ * });
+ *
+ * // All logs from this logger now include the context
+ * logger.info('User authentication started');
+ * logger.debug('Validating credentials');
+ * logger.info('Authentication successful');
+ * ```
+ */
+interface LogContext {
+    /**
+     * Arbitrary context properties using string keys.
+     * Supports any serializable values for maximum flexibility.
+     */
+    [key: string]: unknown;
+    /**
+     * User identifier for associating log events with specific users.
+     * Commonly used for security auditing and user behavior analysis.
+     */
+    userId?: string;
+    /**
+     * Request identifier for tracing the complete lifecycle of a request.
+     * Essential for distributed tracing and debugging request flows.
+     */
+    requestId?: string;
+    /**
+     * Correlation identifier for linking related events across service boundaries.
+     * Used in microservice architectures to track operations across multiple services.
+     */
+    correlationId?: string;
+}
+
+/**
+ * Enumeration of supported log severity levels in ascending order of verbosity.
+ *
+ * The logging system uses this hierarchy to determine which events to emit:
+ * - 'off': Disables all logging
+ * - 'fatal': Critical system failures requiring immediate intervention
+ * - 'error': Failures preventing normal operation
+ * - 'warn': Potentially problematic situations
+ * - 'info': General informational messages about normal operation
+ * - 'debug': Detailed diagnostic information for development
+ * - 'track': Analytics and user behavior tracking events
+ * - 'trace': Most detailed execution information for fine-grained debugging
+ *
+ * Events are emitted when their level index is <= logger's level index.
+ * The 'track' level is positioned between 'debug' and 'trace' to allow
+ * analytics collection without the verbosity of full trace logging.
+ *
+ * @example
+ * ```typescript
+ * // Logger set to 'info' will emit: fatal, error, warn, info
+ * logger.setLevel('info');
+ * logger.debug('Not emitted'); // debug > info in hierarchy
+ * logger.info('Emitted');      // info <= info in hierarchy
+ * ```
+ */
+declare const LogLevel: {
+    readonly off: "off";
+    readonly fatal: "fatal";
+    readonly error: "error";
+    readonly warn: "warn";
+    readonly info: "info";
+    readonly debug: "debug";
+    readonly track: "track";
+    readonly trace: "trace";
+};
+/**
+ * Type representing a LogLevel enum value.
+ */
+type LogLevelType = (typeof LogLevel)[keyof typeof LogLevel];
+
+/**
+ * Interface for a hierarchical logger instance providing level-based logging methods.
+ *
+ * Logger instances are created via LogM8.getLogger() and provide methods for emitting
+ * log events at different severity levels. Each logger maintains its own context and
+ * can create child loggers using dot-separated naming conventions.
+ *
+ * @example
+ * ```typescript
+ * const logger = Logging.getLogger('app.database');
+ * logger.setLevel('debug');
+ * logger.info('Connection established', { host: 'localhost' });
+ *
+ * // Create child logger
+ * const queryLogger = logger.getLogger('queries');
+ * queryLogger.debug('SELECT * FROM users'); // Name becomes 'app.database.queries'
+ *
+ * // Check if logging is enabled before expensive operations
+ * if (logger.isEnabled && logger.isDebug) {
+ *   logger.debug('Expensive debug data', computeExpensiveDebugInfo());
+ * }
+ * ```
+ */
+interface Log {
+    /**
+     * Logs a message at fatal severity level.
+     *
+     * Fatal events indicate critical system failures that typically require
+     * immediate intervention and may result in application termination.
+     *
+     * @param message - Primary message or serializable object to log
+     * @param data - Additional context data to include with the log event
+     */
+    fatal(message: string | unknown, ...data: unknown[]): void;
+    /**
+     * Logs a message at error severity level.
+     *
+     * Error events indicate failures that prevent normal operation but
+     * don't necessarily require application termination.
+     *
+     * @param message - Primary message or serializable object to log
+     * @param data - Additional context data to include with the log event
+     */
+    error(message: string | unknown, ...data: unknown[]): void;
+    /**
+     * Logs a message at warning severity level.
+     *
+     * Warning events indicate potentially problematic situations that
+     * don't prevent operation but may require attention.
+     *
+     * @param message - Primary message or serializable object to log
+     * @param data - Additional context data to include with the log event
+     */
+    warn(message: string | unknown, ...data: unknown[]): void;
+    /**
+     * Logs a message at info severity level.
+     *
+     * Info events provide general informational messages about normal
+     * application operation and significant business events.
+     *
+     * @param message - Primary message or serializable object to log
+     * @param data - Additional context data to include with the log event
+     */
+    info(message: string | unknown, ...data: unknown[]): void;
+    /**
+     * Logs a message at debug severity level.
+     *
+     * Debug events provide detailed diagnostic information useful during
+     * development and troubleshooting.
+     *
+     * @param message - Primary message or serializable object to log
+     * @param data - Additional context data to include with the log event
+     */
+    debug(message: string | unknown, ...data: unknown[]): void;
+    /**
+     * Logs a message at track severity level.
+     *
+     * Track events are specifically designed for analytics and user behavior
+     * tracking, separate from operational logging concerns.
+     *
+     * @param message - Primary message or serializable object to log
+     * @param data - Additional context data to include with the log event
+     */
+    track(message: string | unknown, ...data: unknown[]): void;
+    /**
+     * Logs a message at trace severity level.
+     *
+     * Trace events provide the most detailed execution information,
+     * typically used for fine-grained debugging and performance analysis.
+     *
+     * @param message - Primary message or serializable object to log
+     * @param data - Additional context data to include with the log event
+     */
+    trace(message: string | unknown, ...data: unknown[]): void;
+    /**
+     * True when logger's current level enables fatal severity logging.
+     * When true, fatal() calls will emit log events.
+     */
+    readonly isFatal: boolean;
+    /**
+     * True when logger's current level enables error severity logging.
+     * When true, error() calls will emit log events.
+     */
+    readonly isError: boolean;
+    /**
+     * True when logger's current level enables warn severity logging.
+     * When true, warn() calls will emit log events.
+     */
+    readonly isWarn: boolean;
+    /**
+     * True when logger's current level enables info severity logging.
+     * When true, info() calls will emit log events.
+     */
+    readonly isInfo: boolean;
+    /**
+     * True when logger's current level enables debug severity logging.
+     * When true, debug() calls will emit log events.
+     */
+    readonly isDebug: boolean;
+    /**
+     * True when logger's current level enables track severity logging.
+     * When true, track() calls will emit log events.
+     */
+    readonly isTrack: boolean;
+    /**
+     * True when logger's current level enables trace severity logging.
+     * When true, trace() calls will emit log events.
+     */
+    readonly isTrace: boolean;
+    /**
+     * True when logging is enabled for this logger.
+     * False only when the logger level is set to 'off', disabling all log output.
+     */
+    readonly isEnabled: boolean;
+    /** The dot-separated hierarchical name of this logger instance. */
+    readonly name: string;
+    /** The current logging level determining which events are emitted. */
+    readonly level: LogLevelType;
+    /** Contextual data automatically included with all log events from this logger. */
+    readonly context: LogContext;
+    /**
+     * Updates the logger's severity level threshold.
+     *
+     * Events at or below this level will be emitted based on the level hierarchy:
+     * off < fatal < error < warn < info < debug < track < trace
+     *
+     * @param level - New logging level name (e.g., 'info', 'debug', 'off')
+     */
+    setLevel(level: LogLevelType): void;
+    /**
+     * Replaces the logger's contextual data.
+     *
+     * Context is automatically included with all log events emitted by this logger,
+     * providing consistent metadata across related log entries.
+     *
+     * @param context - New context object to associate with this logger
+     */
+    setContext(context: LogContext): void;
+    /**
+     * Creates or retrieves a child logger with hierarchical naming.
+     *
+     * Child loggers inherit configuration but can have independent levels and context.
+     * The child's name becomes 'parent.child' using dot notation.
+     *
+     * @param name - Name segment for the child logger
+     * @returns Child logger instance with name 'parent.child'
+     *
+     * @example
+     * ```typescript
+     * const parent = Logging.getLogger('app');
+     * const child = parent.getLogger('database'); // Name: 'app.database'
+     * const grandchild = child.getLogger('queries'); // Name: 'app.database.queries'
+     * ```
+     */
+    getLogger(name: string): Log;
+}
+
+/**
+ * Configuration options for initializing a plugin.
+ */
+interface PluginConfig {
+    /**
+     * The plugin's unique name.
+     */
+    name: string;
+    /**
+     * Additional plugin-specific settings.
+     */
+    [key: string]: unknown;
+}
+
+/**
+ * Defines configuration options for a filter plugin.
+ * @extends PluginConfig
+ */
+interface FilterConfig extends PluginConfig {
+    /**
+     * Whether the filter is enabled.
+     */
+    enabled?: boolean;
+}
+
+/**
+ * Defines configuration options for a formatter plugin.
+ * @extends PluginConfig
+ */
+interface FormatterConfig extends PluginConfig {
+}
+
+/**
+ * Defines the configuration options for a log appender plugin.
+ */
+interface AppenderConfig extends PluginConfig {
+    /**
+     * Whether the appender is enabled.
+     */
+    enabled?: boolean;
+    /**
+     * Priority determining execution order; higher values run first (descending order).
+     */
+    priority?: number;
+    /**
+     * The formatter to apply to log events, specified by name or config object.
+     */
+    formatter?: string | FormatterConfig;
+    /**
+     * Filters to apply to log events, specified by name or config objects.
+     */
+    filters?: (string | FilterConfig)[];
+}
+
+/**
+ * Primary configuration object for initializing the LogM8 logging system.
+ *
+ * Defines the overall logging behavior including default levels, per-logger
+ * overrides, and output destinations. Used as the parameter to LogM8.init()
+ * to configure the entire logging pipeline.
+ *
+ * If no configuration is provided, the system defaults to console output
+ * at 'info' level with the default formatter.
+ *
+ * @example
+ * ```typescript
+ * const config: LoggingConfig = {
+ *   level: 'info',
+ *   loggers: {
+ *     'app.database': 'debug',      // More verbose for database operations
+ *     'app.security': 'warn',       // Less verbose for security components
+ *     'app.performance': 'trace'    // Maximum detail for performance monitoring
+ *   },
+ *   appenders: [
+ *     {
+ *       name: 'console',
+ *       formatter: { name: 'default-formatter', color: true }
+ *     },
+ *     {
+ *       name: 'file',
+ *       filename: 'app.log',
+ *       formatter: { name: 'json-formatter', pretty: true }
+ *     }
+ *   ]
+ * };
+ *
+ * Logging.init(config);
+ * ```
+ */
+interface LoggingConfig {
+    /**
+     * Default log level applied to all loggers unless overridden.
+     *
+     * Determines the minimum severity level that will be processed.
+     * Loggers will emit events at this level and all higher severity levels.
+     * Defaults to 'info' if not specified.
+     */
+    level?: LogLevelType;
+    /**
+     * Per-logger level overrides by hierarchical name.
+     *
+     * Allows fine-grained control over logging verbosity for different
+     * parts of the application. Logger names use dot-separated hierarchical
+     * notation where child loggers inherit from parent configurations.
+     *
+     * @example
+     * ```typescript
+     * loggers: {
+     *   'app': 'info',              // Base level for 'app' namespace
+     *   'app.database': 'debug',    // More verbose for database operations
+     *   'app.database.queries': 'trace' // Maximum detail for query logging
+     * }
+     * ```
+     */
+    loggers?: {
+        [key: string]: LogLevelType | undefined;
+    };
+    /**
+     * Output destination configurations.
+     *
+     * Defines where and how log events are written. Each appender can have
+     * its own formatter, filters, and specific configuration options.
+     * If not specified, defaults to a single console appender.
+     *
+     * Appenders are executed in priority order (highest first) for
+     * deterministic output behavior.
+     */
+    appenders?: AppenderConfig[];
+    /**
+     * Global filters applied before any appender-specific processing.
+     *
+     * Each entry may be a string (filter factory name) or a full FilterConfig
+     * object. Global filters run first and can drop events entirely before they
+     * reach appenders. Appenders may also define their own filters via
+     * AppenderConfig.filters.
+     */
+    filters?: (string | FilterConfig)[];
+}
+
+/**
+ * Enumeration of plugin types supported by the LogM8 plugin system.
+ *
+ * The logging system uses a plugin architecture where functionality is
+ * provided by three categories of plugins:
+ *
+ * - **appender**: Output destinations that write formatted log events
+ * - **filter**: Event processors that determine which events to log
+ * - **formatter**: Event transformers that convert LogEvent objects to output format
+ *
+ * Each plugin factory must declare its kind to enable proper registration
+ * and instantiation during system initialization.
+ *
+ * @example
+ * ```typescript
+ * class CustomAppender implements Appender {
+ *   kind = PluginKind.appender;
+ *   // ... implementation
+ * }
+ *
+ * class CustomFilter implements Filter {
+ *   kind = PluginKind.filter;
+ *   // ... implementation
+ * }
+ * ```
+ */
+declare const PluginKind: {
+    readonly appender: "appender";
+    readonly filter: "filter";
+    readonly formatter: "formatter";
+};
+/**
+ * Type representing a PluginKind enum value.
+ */
+type PluginKindType = (typeof PluginKind)[keyof typeof PluginKind];
+
+/**
+ * Represents a plugin with identifying metadata and lifecycle methods.
+ */
+interface Plugin {
+    /** The unique plugin name. */
+    readonly name: string;
+    /** The plugin version in semver format. */
+    readonly version: string;
+    /** The kind of plugin, categorizing its behavior. */
+    readonly kind: PluginKindType;
+    /**
+     * Initializes the plugin with the given configuration.
+     * @param config - Plugin configuration options.
+     */
+    init(config: PluginConfig): void;
+    /**
+     * Disposes the plugin, releasing any used resources.
+     */
+    dispose(): void;
+}
+
+/**
+ * Factory for creating plugin instances of a specific kind.
+ * @template C - Plugin configuration type.
+ * @template P - Plugin instance type.
+ */
+interface PluginFactory<C extends PluginConfig = PluginConfig, P extends Plugin = Plugin> {
+    /** The unique factory name. */
+    readonly name: string;
+    /** The factory version corresponding to plugin implementations. */
+    readonly version: string;
+    /** The kind of plugin this factory creates. */
+    readonly kind: PluginKindType;
+    /**
+     * Creates a plugin instance using the provided configuration.
+     * @param config - Configuration for the plugin.
+     * @returns A new plugin instance.
+     */
+    create(config: C): P;
+}
+
+/**
+ * Central logging manager providing hierarchical loggers and configurable output.
+ *
+ * LogM8 manages the complete logging lifecycle including:
+ * - Logger creation and configuration with hierarchical naming
+ * - Plugin-based appender, formatter, and filter system
+ * - Pre-initialization event buffering (up to 100 events)
+ * - Runtime appender and filter control (enable/disable/flush)
+ * - Built-in console and file appenders with customizable formatting
+ *
+ * The manager operates as a singleton export but can also be instantiated directly.
+ * Events logged before init() are buffered and flushed on first post-init log.
+ *
+ * @example
+ * ```typescript
+ * import { Logging } from 'log-m8';
+ *
+ * // Configure logging system
+ * Logging.init({
+ *   level: 'info',
+ *   loggers: { 'app.database': 'debug' },
+ *   appenders: [
+ *     { name: 'console', formatter: 'default-formatter' },
+ *     { name: 'file', filename: 'app.log' }
+ *   ]
+ * });
+ *
+ * // Use hierarchical loggers
+ * const logger = Logging.getLogger('app.service');
+ * logger.info('Service started');
+ *
+ * // Runtime control
+ * Logging.disableAppender('console');
+ * Logging.disableFilter('sensitive-data');
+ * Logging.flushAppenders();
+ * ```
+ */
+declare class LogM8 {
+    private _initialized;
+    private _pluginManager;
+    private _loggers;
+    private _appenders;
+    private _filters;
+    private _defaultLevel;
+    private _logLevelValues;
+    private _logLevelSet;
+    private _logBuffer;
+    constructor();
+    /**
+     * Initializes the logging system with configuration and flushes any buffered events.
+     *
+     * Sets up default and per-logger levels, creates configured appenders with their
+     * formatters and filters, and processes any events buffered before initialization.
+     * Appenders are sorted by priority (descending) for deterministic execution order.
+     *
+     * @param config - Logging configuration object
+     * @param config.level - Default log level for all loggers ('info' if not specified)
+     * @param config.loggers - Per-logger level overrides by name
+     * @param config.appenders - Appender configurations (defaults to console if not specified)
+     *
+     * @throws {Error} When referenced plugin factories are not registered
+     *
+     * @example
+     * ```typescript
+     * Logging.init({
+     *   level: 'warn',
+     *   loggers: { 'app.database': 'debug' },
+     *   appenders: [{
+     *     name: 'console',
+     *     formatter: 'default-formatter',
+     *     filters: ['sensitive-data']
+     *   }]
+     * });
+     * ```
+     */
+    init(config?: LoggingConfig): void;
+    /**
+     * Shuts down the logging system and releases all resources.
+     *
+     * Flushes all appenders, disposes plugin instances, clears logger registry,
+     * discards buffered events, and deregisters plugin factories. The system
+     * can be reinitialized after disposal.
+     *
+     * @example
+     * ```typescript
+     * // Graceful shutdown
+     * await new Promise(resolve => {
+     *   Logging.flushAppenders();
+     *   setTimeout(() => {
+     *     Logging.dispose();
+     *     resolve();
+     *   }, 100);
+     * });
+     * ```
+     */
+    dispose(): void;
+    /**
+     * Retrieves or creates a logger instance with hierarchical naming.
+     *
+     * Logger instances are cached and reused for the same name. Names can be
+     * provided as strings with dot-separation or as array segments that get
+     * joined. Each logger maintains independent level and context settings.
+     *
+     * @param name - Logger name as string ('app.service') or segments (['app', 'service'])
+     * @returns Logger instance for the specified name
+     *
+     * @example
+     * ```typescript
+     * const logger1 = Logging.getLogger('app.database');
+     * const logger2 = Logging.getLogger(['app', 'database']);
+     * // logger1 === logger2 (same instance)
+     *
+     * logger1.setLevel('debug');
+     * logger1.setContext({ service: 'postgres' });
+     * ```
+     */
+    getLogger(name: string | string[]): Log;
+    /**
+     * Enables an appender to resume processing log events.
+     *
+     * @param name - Name of the appender to enable
+     */
+    enableAppender(name: string): void;
+    /**
+     * Disables an appender to stop processing log events.
+     *
+     * @param name - Name of the appender to disable
+     */
+    disableAppender(name: string): void;
+    /**
+     * Forces an appender to flush any buffered output.
+     *
+     * Catches and logs flush errors to console without interrupting operation.
+     * Useful for ensuring data persistence before shutdown or at intervals.
+     *
+     * @param name - Name of the appender to flush
+     */
+    flushAppender(name: string): void;
+    /**
+     * Flushes all configured appenders.
+     *
+     * Iterates through all appenders calling flush on each, with individual
+     * error handling per appender.
+     */
+    flushAppenders(): void;
+    /**
+     * Enables a filter to resume processing log events.
+     *
+     * When an appender name is provided, enables the filter only for that specific
+     * appender. When no appender is specified, enables the filter globally.
+     * Silently ignores requests for non-existent filters or appenders.
+     *
+     * @param name - Name of the filter to enable
+     * @param appenderName - Optional appender name to enable filter for specific appender only
+     *
+     * @example
+     * ```typescript
+     * // Enable filter globally
+     * Logging.enableFilter('sensitive-data');
+     *
+     * // Enable filter only for console appender
+     * Logging.enableFilter('debug-filter', 'console');
+     * ```
+     */
+    enableFilter(name: string, appenderName?: string): void;
+    /**
+     * Disables a filter to stop processing log events.
+     *
+     * When an appender name is provided, disables the filter only for that specific
+     * appender. When no appender is specified, disables the filter globally.
+     * Silently ignores requests for non-existent filters or appenders.
+     *
+     * @param name - Name of the filter to disable
+     * @param appenderName - Optional appender name to disable filter for specific appender only
+     *
+     * @example
+     * ```typescript
+     * // Disable filter globally
+     * Logging.disableFilter('sensitive-data');
+     *
+     * // Disable filter only for file appender
+     * Logging.disableFilter('debug-filter', 'file');
+     * ```
+     */
+    disableFilter(name: string, appenderName?: string): void;
+    /**
+     * Registers a custom plugin factory for appenders, formatters, or filters.
+     *
+     * Allows extending the logging system with custom implementations.
+     * Must be called before init() to be available during configuration.
+     *
+     * @param pluginFactory - Factory instance implementing the PluginFactory interface
+     *
+     * @example
+     * ```typescript
+     * class SlackAppenderFactory implements PluginFactory {
+     *   name = 'slack';
+     *   kind = PluginKind.appender;
+     *   create(config) { return new SlackAppender(config); }
+     * }
+     *
+     * Logging.registerPluginFactory(new SlackAppenderFactory());
+     * ```
+     */
+    registerPluginFactory(pluginFactory: PluginFactory): void;
+    private _log;
+    private _setLevel;
+    private _setContext;
+    private _processLogEvent;
+    private _getAppender;
+    private _sortAppenders;
+    private _getFilter;
+    private _reset;
+}
+
+/**
+ * Structured representation of a single log entry containing all event data.
+ *
+ * LogEvent objects are created automatically when logger methods are called
+ * and contain the complete context needed for formatting and output by appenders.
+ * They are immutable once created and flow through the logging pipeline.
+ *
+ * @example
+ * ```typescript
+ * // Created automatically when calling:
+ * logger.info('User login', { userId: 123, ip: '192.168.1.1' });
+ *
+ * // Results in LogEvent:
+ * {
+ *   logger: 'app.auth',
+ *   level: 'info',
+ *   message: 'User login',
+ *   data: [{ userId: 123, ip: '192.168.1.1' }],
+ *   context: { sessionId: 'sess-456' },
+ *   timestamp: new Date('2025-08-04T14:23:45.123Z')
+ * }
+ * ```
+ */
+interface LogEvent {
+    /**
+     * Hierarchical name of the logger that generated this event.
+     * Used for filtering and routing by appenders and formatters.
+     */
+    readonly logger: string;
+    /**
+     * Severity level determining event importance and routing.
+     * Must match one of the LogLevel enum values.
+     */
+    readonly level: LogLevelType;
+    /**
+     * Primary log content - can be string, object, or any serializable value.
+     * Formatters determine how this is rendered in output.
+     */
+    readonly message: string | unknown;
+    /**
+     * Additional arguments passed to the logging method.
+     * Typically contains context objects, error details, or supplementary data.
+     */
+    readonly data: unknown[];
+    /**
+     * Logger's contextual metadata at the time of event creation.
+     * Automatically included from logger.setContext() calls.
+     */
+    readonly context: LogContext;
+    /**
+     * Event creation timestamp for chronological ordering and time-based formatting.
+     * Set automatically when the log method is called.
+     */
+    readonly timestamp: Date;
+}
+
+/**
+ * Represents a log event filter that can be initialized with specific configuration and determines whether a log event should be logged.
+ */
+interface Filter extends Plugin {
+    /**
+     * Runtime flag controlling whether this filter processes events.
+     *
+     * Can be toggled via LogM8.enableFilter()/disableFilter() for
+     * dynamic output control without full reconfiguration.
+     */
+    enabled: boolean;
+    /**
+     * Initializes the filter with the specified configuration.
+     * @param config - Filter configuration options.
+     */
+    init(config: FilterConfig): void;
+    /**
+     * Determines whether the given log event should be logged.
+     * @param logEvent - The log event to evaluate.
+     * @returns boolean indicating if the event should be logged.
+     */
+    filter(logEvent: LogEvent): boolean;
+    /**
+     * Disposes of the filter, cleaning up any resources.
+     *
+     * Called during parent's dispose() to clean up the filter's resources.
+     */
+    dispose(): void;
+}
+
+/**
+ * Represents a log event formatter that initializes with configuration and converts log events into output tokens.
+ */
+interface Formatter extends Plugin {
+    /**
+     * Initializes the formatter with the specified configuration.
+     * @param config - Formatter configuration options.
+     */
+    init(config: FormatterConfig): void;
+    /**
+     * Formats the given log event into an array of output tokens.
+     * @param logEvent - The log event to format.
+     * @returns An array of formatted output elements.
+     */
+    format(logEvent: LogEvent): unknown[];
+    /**
+     * Disposes of the formatter, cleaning up any resources.
+     *
+     * Called during parent's dispose() to clean up the formatter's resources.
+     */
+    dispose(): void;
+}
+
+/**
+ * Plugin interface for log event output destinations.
+ *
+ * Appenders receive formatted log events and write them to specific outputs
+ * like console, files, network endpoints, or databases. They can be dynamically
+ * enabled/disabled and support priority-based execution ordering.
+ *
+ * Each appender declares which log levels it supports and can optionally
+ * use formatters to transform events and filters to determine eligibility.
+ *
+ * @example
+ * ```typescript
+ * class DatabaseAppender implements Appender {
+ *   name = 'database';
+ *   supportedLevels = new Set(['error', 'fatal']);
+ *   enabled = true;
+ *   priority = 10;
+ *
+ *   init(config, formatter, filters) {
+ *     this.db = new Database(config.connectionString);
+ *   }
+ *
+ *   write(event) {
+ *     this.db.insert('logs', this.formatter.format(event));
+ *   }
+ * }
+ * ```
+ */
+interface Appender extends Plugin {
+    /**
+     * Set of log levels this appender can process.
+     *
+     * Events with levels not in this set are automatically skipped.
+     * Use this to restrict appenders to specific severity ranges.
+     */
+    readonly supportedLevels: Set<LogLevelType>;
+    /**
+     * Runtime flag controlling whether this appender processes events.
+     *
+     * Can be toggled via LogM8.enableAppender()/disableAppender() for
+     * dynamic output control without full reconfiguration.
+     */
+    enabled: boolean;
+    /**
+     * Execution priority for deterministic appender ordering.
+     *
+     * Higher values execute first. Undefined/null treated as 0.
+     * Useful for ensuring critical appenders (like error alerting)
+     * process events before optional ones (like debug files).
+     */
+    priority?: number;
+    /**
+     * Initializes the appender with configuration and optional processing components.
+     *
+     * Called once during LogM8.init() to set up the appender with its specific
+     * configuration, formatter for event transformation, and filters for event
+     * eligibility determination.
+     *
+     * @param config - Appender-specific configuration options
+     * @param formatter - Optional formatter to transform log events before output
+     * @param filters - Optional filters to determine which events to process
+     */
+    init(config: AppenderConfig, formatter?: Formatter, filters?: Filter[]): void;
+    /**
+     * Processes a single log event for output.
+     *
+     * Called for each log event that passes level and filter checks.
+     * Implementations should handle formatting (if no formatter provided)
+     * and write to their specific output destination.
+     *
+     * @param logEvent - The log event to be processed and output
+     */
+    write(logEvent: LogEvent): void;
+    /**
+     * Forces immediate output of any buffered log events.
+     *
+     * Called during appender shutdown or when explicitly requested via
+     * LogM8.flushAppender(). Implementations should ensure data persistence.
+     */
+    flush(): void;
+    /**
+     * Disposes of the appender and releases any resources.
+     *
+     * Called during LogM8.dispose() to clean up the appender's resources.
+     * Implementations should ensure all buffered events are flushed before disposal.
+     */
+    dispose(): void;
+    /**
+     * Enables the specified filter for this appender.
+     *
+     * @param filterName - The name of the filter to enable
+     */
+    enableFilter(filterName: string): void;
+    /**
+     * Disables the specified filter for this appender.
+     *
+     * @param filterName - The name of the filter to disable
+     */
+    disableFilter(filterName: string): void;
+}
+
+/**
+ * Configuration interface for console appender.
+ * Currently extends base AppenderConfig without additional options.
+ */
+interface ConsoleAppenderConfig extends AppenderConfig {
+}
+
+/**
+ * Configuration options for the file appender.
+ *
+ * - filename: Destination file path. The file is opened on init.
+ * - append:   When true, appends to the existing file; otherwise it is truncated.
+ */
+interface FileAppenderConfig extends AppenderConfig {
+    /** Destination file path to write logs into. */
+    filename: string;
+    /** Append to existing file (true) or overwrite on startup (false). Default: false */
+    append?: boolean;
+}
+
+/**
+ * Configuration for MatchFilter.
+ *
+ * Provides simple allow/deny rule maps where each key is a dot-path into the LogEvent
+ * (supports array bracket notation like `data[0].items[2]`) and each value is the value
+ * that must match for the rule to apply.
+ *
+ * Behavior:
+ * - allow: If provided and non-empty, an event must satisfy ALL allow rules to pass.
+ * - deny: If provided, an event that satisfies ANY deny rule will be blocked.
+ * - Precedence: deny rules take precedence over allow; i.e., an event that passes allow
+ *   but matches a deny rule will be denied.
+ *
+ * Examples:
+ * ```ts
+ * // Only allow events from a specific logger AND with a specific data value
+ * { name: 'match-filter', allow: { 'logger': 'app.service', 'data[0].type': 'audit' } }
+ *
+ * // Deny events for a user id regardless of other matches
+ * { name: 'match-filter', deny: { 'context.userId': '1234' } }
+ *
+ * // Combined example
+ * {
+ *   name: 'match-filter',
+ *   allow: { 'logger': 'allow.this.logger', 'data[0].custom[3].path': 4 },
+ *   deny:  { 'logger': 'block.this.logger', 'context.userId': '1234' }
+ * }
+ * ```
+ */
+interface MatchFilterConfig extends FilterConfig {
+    /** All rules in this map must match for the event to be allowed (AND). */
+    allow?: Record<string, unknown>;
+    /** If any rule in this map matches, the event will be denied (OR). */
+    deny?: Record<string, unknown>;
+}
+
+/**
+ * Configuration for the default text formatter.
+ *
+ * Extends the base FormatterConfig with options for template customization,
+ * timestamp formatting, and optional colorization.
+ */
+interface DefaultFormatterConfig extends FormatterConfig {
+    /**
+     * Custom format template(s) using token syntax.
+     * Provide a single template string or an array of template strings for multi-line output.
+     * Defaults to a readable text format: ['{timestamp} {LEVEL} [{logger}]', '{message}', '{data}'].
+     */
+    format?: string | string[];
+    /**
+     * Timestamp format pattern or preset.
+     * Supports 'iso', 'locale', or custom token patterns (yyyy-MM-dd hh:mm:ss).
+     */
+    timestampFormat?: string;
+    /**
+     * Enable colorized output for level tokens.
+     *
+     * - Node.js: Applies ANSI escape codes.
+     * - Browser: Returns a tuple ['%cLEVEL', css] suitable for console.log('%c..', ..)
+     *   when {LEVEL} is resolved; appenders may pass tokens straight to console APIs.
+     *
+     * Set to true to enable; environment detection is used only to decide ANSI vs CSS.
+     */
+    color?: boolean;
+}
+
+interface StringifyLogOptions {
+    /** Max object/array nesting depth to descend into (default 3). */
+    maxDepth?: number;
+    /** Truncate long string values to this length (default 200). */
+    maxStringLength?: number;
+    /** Truncate long arrays to this length (default: 100) */
+    maxArrayLength?: number;
+}
+interface SerializedError {
+    name: string;
+    message: string;
+    stack?: string;
+    cause?: SerializedError | null;
+    [key: string]: unknown;
+}
+/**
+ * Utility functions for timestamp formatting and object property access.
+ *
+ * Provides environment detection, nested property traversal, and flexible
+ * timestamp formatting with support for custom tokens, ISO formats, and
+ * locale-specific output.
+ */
+declare class LogM8Utils {
+    /**
+     * Detects browser environment for feature compatibility.
+     *
+     * @returns True when both window and document global objects are available
+     */
+    static isBrowser(): boolean;
+    /**
+     * Check if an object is a string.
+     *
+     * @param obj - The object to check.
+     * @returns true if the object is a string, otherwise false.
+     */
+    static isString(obj: unknown): boolean;
+    /**
+     * Traverses nested object properties using dot-separated path notation.
+     *
+     *  Supports both object property access and array indexing with numeric keys.
+     *  Also supports bracket notation for array indices which is normalized internally
+     *  (e.g., `data[0].items[2]` becomes `data.0.items.2`).
+     *  Safe navigation that returns undefined for invalid paths rather than throwing.
+     *
+     *  @param obj - Source object to traverse
+     *  @param path - Dot-separated property path (e.g., 'user.profile.name', 'items.0.id')
+     *               or a path with bracket indices (e.g., 'items[0].id')
+     *  @returns Property value at the specified path, or undefined if not found
+     *
+     *  @example
+     *  ```typescript
+     *  const data = { user: { profile: { name: 'John' } }, items: [{ id: 1 }, { id: 2 }] };
+     *  getPropertyByPath(data, 'user.profile.name'); // 'John'
+     *  getPropertyByPath(data, 'items.0.id');        // 1
+     *  getPropertyByPath(data, 'items[1].id');       // 2 (bracket notation)
+     *  getPropertyByPath(data, 'missing.path');      // undefined
+     *  ```
+     */
+    static getPropertyByPath(obj: unknown, path: string): unknown;
+    /**
+     * Formats Date objects using preset formats or custom token patterns.
+     *
+     * Supports common presets ('iso', 'locale') and flexible token-based formatting
+     * for complete control over timestamp appearance. Tokens are replaced with
+     * corresponding date/time components, while non-token text is preserved literally.
+     *
+     * Supported format tokens:
+     * - yyyy: 4-digit year (2025)
+     * - yy: 2-digit year (25)
+     * - MM: month with leading zero (01-12)
+     * - dd: day with leading zero (01-31)
+     * - hh: 24-hour format hour with leading zero (00-23)
+     * - h: 12-hour format hour (1-12)
+     * - mm: minutes with leading zero (00-59)
+     * - ss: seconds with leading zero (00-59)
+     * - SSS: milliseconds with leading zeros (000-999)
+     * - SS: centiseconds with leading zero (00-99)
+     * - S: deciseconds (0-9)
+     * - A: uppercase AM/PM
+     * - a: lowercase am/pm
+     * - z: timezone offset with colon (±HH:MM)
+     * - zz: timezone offset without colon (±HHMM)
+     *
+     * @param date - Date instance to format
+     * @param fmt - Format preset ('iso'|'locale') or custom token pattern
+     * @returns Formatted timestamp string
+     *
+     * @example
+     * ```typescript
+     * const date = new Date('2025-08-04T14:23:45.123Z');
+     *
+     * // Presets
+     * formatTimestamp(date, 'iso');    // '2025-08-04T14:23:45.123Z'
+     * formatTimestamp(date, 'locale'); // '8/4/2025, 2:23:45 PM' (locale-dependent)
+     *
+     * // Custom patterns
+     * formatTimestamp(date, 'yyyy-MM-dd hh:mm:ss');     // '2025-08-04 14:23:45'
+     * formatTimestamp(date, 'MM/dd/yyyy h:mm A');       // '08/04/2025 2:23 PM'
+     * formatTimestamp(date, 'hh:mm:ss.SSS');            // '14:23:45.123'
+     * formatTimestamp(date, 'yyyy-MM-dd hh:mm:ss z');   // '2025-08-04 14:23:45 +00:00'
+     * ```
+     */
+    static formatTimestamp(date: Date, fmt?: string): string;
+    /**
+     * Converts arbitrary values into JSON strings optimized for logging systems.
+     *
+     * This utility ensures that any JavaScript value can be safely logged without causing
+     * serialization errors or producing excessively large output. It's designed specifically
+     * for logging contexts where reliability and readability are more important than
+     * perfect fidelity.
+     *
+     * ## Key Features
+     *
+     * **Depth Protection**: Prevents stack overflows and excessive output by limiting
+     * object traversal depth. Objects/arrays beyond the limit are replaced with
+     * "[Object]" or "[Array]" placeholders.
+     *
+     * **Array Length Limiting**: Automatically truncates arrays that exceed the maximum
+     * length threshold. Truncated arrays include a message indicating how many additional
+     * items were omitted.
+     *
+     * **String Truncation**: Automatically truncates long strings to prevent log flooding.
+     * Truncated strings end with an ellipsis (…) character.
+     *
+     * **Type Safety**: Handles problematic JavaScript types that would normally cause
+     * JSON.stringify to throw:
+     * - BigInt values are converted to strings
+     * - Date objects are normalized to ISO 8601 format
+     * - Error instances are serialized to structured objects via {@link LogM8Utils.serializeError}
+     *
+     * ## Implementation Details
+     *
+     * - Uses a WeakMap to track traversal depth per object, preventing revisits to the
+     *   same instance at different depths
+     * - Respects existing `toJSON()` methods on objects
+     * - Not designed for full cycle detection - cyclic references are handled by the
+     *   depth limit rather than explicit cycle breaking
+     * - The replacer function executes in the context of the parent object, enabling
+     *   depth tracking through the traversal
+     *
+     * @param value - Any JavaScript value to stringify for logging (events, contexts, errors, etc.)
+     * @param options - Configuration for controlling output size and complexity
+     * @param options.maxDepth - Maximum nesting depth for objects/arrays (default: 3).
+     *                           Level 0 = primitive values only,
+     *                           Level 1 = top-level properties,
+     *                           Level 2 = nested properties, etc.
+     * @param options.maxArrayLength - Maximum number of array elements to include before truncation (default: 100).
+     *                                 Arrays exceeding this limit will be truncated with a message
+     *                                 indicating the number of omitted items.
+     * @param options.maxStringLength - Maximum character length for strings before truncation (default: 200)
+     * @param space - Indentation for pretty-printing. Can be a number (spaces) or string (e.g., '\t').
+     *               Pass undefined for compact output (recommended for production logs).
+     *
+     * @returns A JSON string that is guaranteed to be safe for logging systems
+     *
+     * @example
+     * // Basic usage with default options
+     * const json = LogM8Utils.stringifyLog({ message: 'User logged in', userId: 12345 });
+     * // => '{"message":"User logged in","userId":12345}'
+     *
+     * @example
+     * // Handling problematic types
+     * const data = {
+     *   bigNumber: 123456789012345678901234567890n,
+     *   timestamp: new Date('2024-01-15T10:30:00Z'),
+     *   error: new Error('Connection failed'),
+     *   longText: 'x'.repeat(500)
+     * };
+     * const json = LogM8Utils.stringifyLog(data);
+     * // => '{"bigNumber":"123456789012345678901234567890","timestamp":"2024-01-15T10:30:00.000Z","error":{...},"longText":"xxx...xxx…"}'
+     *
+     * @example
+     * // Array length limiting for large arrays
+     * const largeData = {
+     *   items: new Array(1000).fill({ id: 1, name: 'item' }),
+     *   values: Array.from({ length: 500 }, (_, i) => i)
+     * };
+     * const json = LogM8Utils.stringifyLog(largeData, { maxArrayLength: 50 });
+     * // => '{"items":[{...},{...},...,"... 950 more items"],"values":[0,1,2,...,"... 450 more items"]}'
+     *
+     * @example
+     * // Depth limiting for deeply nested objects
+     * const deepObj = {
+     *   level1: {
+     *     level2: {
+     *       level3: {
+     *         level4: {
+     *           level5: 'too deep'
+     *         }
+     *       }
+     *     }
+     *   }
+     * };
+     * const json = LogM8Utils.stringifyLog(deepObj, { maxDepth: 3 });
+     * // => '{"level1":{"level2":{"level3":{"level4":"[Object]"}}}}'
+     *
+     * @example
+     * // Custom options for verbose debugging
+     * const debugJson = LogM8Utils.stringifyLog(
+     *   complexObject,
+     *   { maxDepth: 5, maxArrayLength: 500, maxStringLength: 1000 },
+     *   2  // Pretty print with 2 spaces
+     * );
+     *
+     * @example
+     * // Production logging with minimal output
+     * const prodJson = LogM8Utils.stringifyLog(
+     *   userEvent,
+     *   { maxDepth: 2, maxArrayLength: 20, maxStringLength: 100 }  // Aggressive truncation for high-volume logs
+     * );
+     *
+     * @example
+     * // Handling arrays with mixed content
+     * const mixedArray = {
+     *   results: [
+     *     { id: 1, data: 'first' },
+     *     { id: 2, data: 'second' },
+     *     ...Array(200).fill({ id: 999, data: 'bulk' })
+     *   ]
+     * };
+     * const json = LogM8Utils.stringifyLog(mixedArray, { maxArrayLength: 10 });
+     * // First 10 items preserved, then truncation message
+     *
+     * @see {@link LogM8Utils.serializeError} - For Error serialization details
+     */
+    static stringifyLog(value: unknown, { maxDepth, maxStringLength, maxArrayLength }?: StringifyLogOptions, space?: number | string): string;
+    /**
+     * Serializes an Error (or Error-like) into a plain, JSON-safe object.
+     *
+     * Behavior:
+     * - Returns null for falsy inputs.
+     * - If the object provides a custom toJSON(), that result is used verbatim to
+     *   honor caller-defined serialization.
+     * - Otherwise includes standard fields: name, message, stack.
+     * - Recursively serializes the optional error.cause chain using the same rules.
+     * - Handles circular references in the cause chain safely.
+     * - Copies other own enumerable properties (excluding name, message, stack, cause),
+     *   skipping properties that throw on access or are not JSON-serializable.
+     * - Optionally includes common non-enumerable properties like 'code' if present.
+     *
+     * Important:
+     * - This function does not attempt to preserve all non-enumerable properties.
+     * - Circular references in the cause chain are detected and handled gracefully.
+     *
+     * @param error - Unknown error input (Error instance or compatible object).
+     * @returns Structured error data suitable for logging, or null when input is falsy.
+     *
+     * @example
+     * try {
+     *   throw new Error('Boom');
+     * } catch (e) {
+     *   const payload = LogM8Utils.serializeError(e);
+     *   // { name: 'Error', message: 'Boom', stack: '...', ... }
+     * }
+     */
+    static serializeError(error: unknown): SerializedError | null;
+}
+
+/**
+ * Default singleton instance of the LogM8 logging manager.
+ *
+ * Pre-configured with built-in appenders and formatters for immediate use.
+ * Most applications should use this export rather than creating new LogM8 instances.
+ *
+ * @example
+ * ```typescript
+ * import { Logging } from 'log-m8';
+ *
+ * // Initialize with default console output
+ * Logging.init();
+ *
+ * // Get a logger and start logging
+ * const logger = Logging.getLogger('app');
+ * logger.info('Application started');
+ * ```
+ */
+declare const Logging: LogM8;
+
+export { type Appender, type AppenderConfig, type ConsoleAppenderConfig, type DefaultFormatterConfig, type FileAppenderConfig, type Filter, type FilterConfig, type Formatter, type FormatterConfig, type Log, type LogContext, LogLevel, type LogLevelType, LogM8Utils, Logging, type LoggingConfig, type MatchFilterConfig, type Plugin, type PluginConfig, type PluginFactory, PluginKind, type PluginKindType };