@ncoderz/log-m8 1.2.4 → 1.3.0

package/dist/index.d.cts

@@ -1,3 +1,57 @@
+/**
+ * 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)[];
+}
+
 /**
  * Contextual metadata automatically included with all log events from a logger.
  *
@@ -268,60 +322,6 @@ interface Log {
     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.
  *
@@ -536,6 +536,7 @@ declare class LogM8$1 {
     private _globalLogLevelNumber;
     private _logLevelValues;
     private _logLevelSet;
+    private _logLevelIndexMap;
     private _logBuffer;
     constructor();
     /**
@@ -632,6 +633,75 @@ declare class LogM8$1 {
      * @param name - Name of the appender to disable
      */
     disableAppender(name: string): void;
+    /**
+     * Adds an appender to the logging system at runtime.
+     *
+     * Creates and initializes the appender using the plugin factory system,
+     * including any configured formatter and filters. The appender is inserted
+     * into the priority-sorted appender list and immediately begins receiving
+     * log events.
+     *
+     * Must be called after init(). The appender name must not already be in use.
+     *
+     * @param config - Appender name (string) or full configuration object
+     *
+     * @throws {Error} When called before init()
+     * @throws {Error} When an appender with the same name already exists
+     * @throws {Error} When the referenced plugin factory is not registered
+     *
+     * @example
+     * ```typescript
+     * // Add by name (uses factory defaults)
+     * Logging.addAppender('console');
+     *
+     * // Add with full configuration
+     * Logging.addAppender({
+     *   name: 'file',
+     *   filename: 'debug.log',
+     *   formatter: 'json-formatter',
+     *   filters: ['sensitive-data'],
+     *   priority: 10
+     * });
+     * ```
+     */
+    addAppender(config: string | AppenderConfig): void;
+    /**
+     * Removes an appender from the logging system at runtime.
+     *
+     * Flushes any buffered output, disposes the appender, and removes it
+     * from the active appender list. The appender will no longer receive
+     * log events after removal.
+     *
+     * @param name - Name of the appender to remove
+     * @returns True if the appender was found and removed, false otherwise
+     *
+     * @example
+     * ```typescript
+     * // Remove a dynamically added appender
+     * Logging.removeAppender('file');
+     *
+     * // Check if removal succeeded
+     * if (!Logging.removeAppender('unknown')) {
+     *   console.warn('Appender not found');
+     * }
+     * ```
+     */
+    removeAppender(name: string): boolean;
+    /**
+     * Returns the names of all currently registered appenders.
+     *
+     * The returned array is a snapshot; modifications to it do not affect
+     * the logging system. Names are in priority-sorted order (highest first).
+     *
+     * @returns Array of appender names
+     *
+     * @example
+     * ```typescript
+     * const names = Logging.getAppenderNames();
+     * console.log('Active appenders:', names); // ['console', 'file']
+     * ```
+     */
+    getAppenderNames(): string[];
     /**
      * Forces an appender to flush any buffered output.
      *
@@ -712,12 +782,21 @@ declare class LogM8$1 {
     private _setLevel;
     private _setContext;
     private _processLogEvent;
+    private _createAndInitAppender;
     private _getAppender;
     private _sortAppenders;
     private _getFilter;
     private _reset;
 }
 
+declare const PACKAGE_INFO: {
+    name: string;
+    version: string;
+    author: string;
+    license: string;
+    description: string;
+};
+
 /**
  * Structured representation of a single log entry containing all event data.
  *
@@ -934,6 +1013,56 @@ interface Appender extends Plugin {
  */
 interface ConsoleAppenderConfig extends AppenderConfig {
 }
+/**
+ * Built-in appender that outputs log events to the global console object.
+ *
+ * Maps log levels to appropriate console methods (error, warn, info, debug, etc.)
+ * with fallback to console.log when specific methods are unavailable.
+ * Automatically detects console availability and gracefully handles environments
+ * where console is not available.
+ *
+ * Features:
+ * - Zero-configuration operation
+ * - Automatic console method mapping by log level
+ * - Graceful degradation when console methods are missing
+ * - No-op flush operation (console output is immediate)
+ * - Environment detection for console availability
+ *
+ * @example
+ * ```typescript
+ * // Automatic registration - no manual setup needed
+ * Logging.init({
+ *   appenders: [{ name: 'console', formatter: 'default-formatter' }]
+ * });
+ * ```
+ */
+declare class ConsoleAppender implements Appender {
+    name: string;
+    version: string;
+    kind: "appender";
+    readonly supportedLevels: Set<LogLevelType>;
+    enabled: boolean;
+    priority?: number;
+    private _config?;
+    private _formatter?;
+    private _filters;
+    private _available;
+    private off;
+    private fatal;
+    private error;
+    private warn;
+    private info;
+    private debug;
+    private trace;
+    private track;
+    init(config: AppenderConfig, formatter?: Formatter, filters?: Filter[]): void;
+    dispose(): void;
+    write(event: LogEvent): void;
+    flush(): void;
+    enableFilter(name: string): void;
+    disableFilter(name: string): void;
+    private _getFilter;
+}
 
 /**
  * Configuration options for the file appender.
@@ -947,6 +1076,37 @@ interface FileAppenderConfig extends AppenderConfig {
     /** Append to existing file (true) or overwrite on startup (false). Default: false */
     append?: boolean;
 }
+/**
+ * Appender that writes each formatted log event to a file (one line per event).
+ *
+ * Behavior
+ * - Initializes a WriteStream on init() using the provided filename.
+ * - Joins formatted tokens with a single space and appends a trailing newline.
+ * - If no formatter is configured, writes the raw LogEvent via String() coercion of tokens.
+ * - Respects per-appender filters before writing.
+ * - flush() is a no-op; data is flushed by the stream implementation. dispose() ends the stream.
+ */
+declare class FileAppender implements Appender {
+    name: string;
+    version: string;
+    kind: "appender";
+    readonly supportedLevels: Set<LogLevelType>;
+    enabled: boolean;
+    priority?: number;
+    private _config?;
+    private _formatter?;
+    private _filters;
+    private _stream?;
+    private _streamCreationFailed;
+    init(config: AppenderConfig, formatter?: Formatter, filters?: Filter[]): void;
+    dispose(): void;
+    write(event: LogEvent): void;
+    flush(): void;
+    enableFilter(name: string): void;
+    disableFilter(name: string): void;
+    private _getFilter;
+    private _createStream;
+}
 
 /**
  * Configuration for MatchFilter.
@@ -983,6 +1143,42 @@ interface MatchFilterConfig extends FilterConfig {
     /** If any rule in this map matches, the event will be denied (OR). */
     deny?: Record<string, unknown>;
 }
+/**
+ * Built-in filter providing straightforward allow/deny path-based matching.
+ *
+ * Use this when you want quick, declarative filtering without writing code. Rules are
+ * evaluated against the LogEvent using robust dot-path resolution (with support for
+ * `array[index]` notation). Comparisons use deep equality for objects/arrays and strict
+ * equality for primitives.
+ */
+declare class MatchFilter implements Filter {
+    name: string;
+    version: string;
+    kind: "filter";
+    enabled: boolean;
+    private _allow?;
+    private _deny?;
+    /**
+     * Initializes allow/deny rule maps. Values are compared using deep equality for
+     * arrays/objects and strict equality for primitives. Missing maps are treated as empty.
+     * @param config - Filter configuration with optional allow/deny maps
+     */
+    init(config: FilterConfig): void;
+    dispose(): void;
+    /**
+     * Evaluates the given event against configured rules.
+     * - allow: if provided and non-empty, ALL rules must match (AND)
+     * - deny: if provided, ANY match denies (OR); deny takes precedence over allow
+     * Returns false on unexpected errors to fail-safe.
+     * @param logEvent - Event to evaluate
+     * @returns true when the event should be logged; false to drop
+     */
+    filter(logEvent: LogEvent): boolean;
+    private _matches;
+    private _isEqual;
+    private _isPlainObject;
+    private _prepareRules;
+}
 
 /**
  * Configuration for the default text formatter.
@@ -1013,6 +1209,163 @@ interface DefaultFormatterConfig extends FormatterConfig {
      */
     color?: boolean;
 }
+/**
+ * Built-in text formatter with token-based templates and optional colorized levels.
+ *
+ * Features
+ * - Customizable templates using curly-brace tokens mixed with literal text.
+ * - Timestamp formatting via presets or custom patterns.
+ * - Optional colorization of the {LEVEL} token (ANSI in Node.js, CSS tuple in browsers).
+ *
+ * Notes
+ * - This formatter outputs text (not JSON). It returns an array of strings/values that
+ *   appenders can pass to console/file outputs.
+ * - The {data} token resolves to the `logEvent.data` array. If present as its own
+ *   line entry, items are expanded in-place; if the array is empty, the token is removed.
+ * - {message} is passed through as-is when it’s not a string (e.g., objects or errors).
+ * - Any other token (including nested paths like {context.userId}) is resolved using
+ *   dot-path access on the LogEvent.
+ *
+ * Supported tokens
+ * - {timestamp}: Formatted with `timestampFormat`.
+ * - {LEVEL}: Uppercase level label (with optional colorization/padding).
+ * - {level}: Lowercase level name.
+ * - {logger}: Logger name.
+ * - {message}: Primary log message (string or non-string value).
+ * - {data}: Additional data arguments array (expanded inline when present alone in a line).
+ * - {context.*}: Nested context properties.
+ *
+ * @example
+ * // Text with colors
+ * formatter.init({
+ *   format: '{timestamp} {LEVEL} [{logger}] {message}',
+ *   timestampFormat: 'hh:mm:ss.SSS',
+ *   color: true,
+ * });
+ *
+ * // Multi-line text output with expanded data
+ * formatter.init({
+ *   format: [
+ *     '{timestamp} {LEVEL} [{logger}] {message}',
+ *     'Context: {context}',
+ *     'Data: {data}',
+ *   ],
+ * });
+ */
+declare class DefaultFormatter implements Formatter {
+    name: string;
+    version: string;
+    kind: "formatter";
+    private _config;
+    private _format;
+    private _timestampFormat;
+    private _levelMap;
+    private _colorEnabled;
+    private _levelColorMap;
+    private _levelCssColorMap;
+    init(config: DefaultFormatterConfig): void;
+    dispose(): void;
+    format(logEvent: LogEvent): unknown[];
+    private resolveToken;
+}
+
+/**
+ * Configuration for the JSON formatter.
+ *
+ * Extends the base FormatterConfig with options for selecting which fields to
+ * include, pretty printing, timestamp formatting, and output size limits.
+ */
+interface JsonFormatterConfig extends FormatterConfig {
+    /**
+     * Fields to include in the output object.
+     * Accepts a single field or an array of fields. Defaults to
+     * ['timestamp', 'level', 'logger', 'message', 'data'].
+     *
+     * Each entry is used as the object key and resolved via dot-path on the LogEvent.
+     * Special handling:
+     * - 'LEVEL' returns the raw level string (e.g., 'info').
+     * - 'timestamp' is formatted with `timestampFormat`.
+     *
+     * If the list is empty, the entire LogEvent object is used.
+     */
+    format?: string | string[];
+    /**
+     * Pretty-print JSON output.
+     * - true: default indentation of 2 spaces.
+     * - number: use the provided number of spaces.
+     * - false/undefined: minified JSON with no extra whitespace.
+     */
+    pretty?: boolean | number;
+    /**
+     * Timestamp format pattern or preset.
+     * Supports 'iso', 'locale', or custom token patterns (yyyy-MM-dd hh:mm:ss).
+     */
+    timestampFormat?: string;
+    /**
+     * Maximum depth for nested objects in JSON output.
+     * Defaults to 3.
+     */
+    maxDepth?: number;
+    /**
+     * Maximum length for string values in JSON output.
+     * Strings longer than this may be truncated by `stringifyLog`. Defaults to 1000.
+     */
+    maxStringLen?: number;
+    /**
+     * Maximum length for array values in JSON output.
+     * Arrays longer than this may be truncated by `stringifyLog`. Defaults to 100.
+     */
+    maxArrayLen?: number;
+}
+/**
+ * JSON formatter that emits a single JSON string per log event.
+ *
+ * Features
+ * - Select fields via `format` (e.g., ['timestamp','level','logger','message','data']).
+ * - Formats timestamps using `timestampFormat` ('iso', 'locale', or custom pattern).
+ * - Pretty printing with fixed (2 spaces) or custom indentation.
+ * - Output size controls via `maxDepth`, `maxStringLen`, and `maxArrayLen` (passed to `LogM8Utils.stringifyLog`).
+ *
+ * Behavior
+ * - Returns an array with a single element: the JSON string representation of the selected fields.
+ * - Field resolution uses dot-path access on the LogEvent (e.g., 'context.userId').
+ * - Special tokens:
+ *   - 'timestamp': formatted per `timestampFormat`.
+ *   - 'LEVEL': raw level string (lowercase; no color or padding).
+ * - If `format` is empty, the entire LogEvent object is serialized.
+ *
+ * Examples
+ *
+ * // Default fields, minified JSON
+ * formatter.init({});
+ * // => ["{\"timestamp\":\"...\",\"level\":\"info\",\"logger\":\"app\",\"message\":\"...\",\"data\":[]}"]
+ *
+ * // Pretty printed output (2 spaces)
+ * formatter.init({ pretty: true });
+ *
+ * // Custom fields with a nested context property
+ * formatter.init({
+ *   format: ['timestamp', 'LEVEL', 'logger', 'context.userId', 'message'],
+ *   timestampFormat: 'hh:mm:ss.SSS',
+ *   pretty: 2,
+ * });
+ */
+declare class JsonFormatter implements Formatter {
+    name: string;
+    version: string;
+    kind: "formatter";
+    private _config;
+    private _format;
+    private _pretty;
+    private _maxDepth;
+    private _maxStringLen;
+    private _maxArrayLen;
+    private _timestampFormat;
+    init(config: JsonFormatterConfig): void;
+    dispose(): void;
+    format(logEvent: LogEvent): unknown[];
+    private resolveToken;
+}
 
 interface StringifyLogOptions {
     /** Max object/array nesting depth to descend into (default 3). */
@@ -1324,4 +1677,4 @@ declare class NullLogger implements Log {
  */
 declare const LogM8: LogM8$1;
 
-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, LogM8, LogM8Utils, type LoggingConfig, type MatchFilterConfig, NullLogger, type Plugin, type PluginConfig, type PluginFactory, PluginKind, type PluginKindType };
+export { type Appender, type AppenderConfig, ConsoleAppender, type ConsoleAppenderConfig, DefaultFormatter, type DefaultFormatterConfig, FileAppender, type FileAppenderConfig, type Filter, type FilterConfig, type Formatter, type FormatterConfig, JsonFormatter, type JsonFormatterConfig, type Log, type LogContext, type LogEvent, LogLevel, type LogLevelType, LogM8, LogM8Utils, type LoggingConfig, MatchFilter, type MatchFilterConfig, NullLogger, PACKAGE_INFO, type Plugin, type PluginConfig, type PluginFactory, PluginKind, type PluginKindType };