@abdokouta/react-logger 1.0.0

package/dist/index.d.cts

@@ -0,0 +1,1231 @@
+import { DynamicModule } from '@abdokouta/react-di';
+
+/**
+ * Log Level Enum
+ *
+ * Defines the severity levels for log messages, ordered from
+ * least severe (debug) to most severe (fatal). Inspired by
+ * PSR-3 / Laravel logging levels, adapted for client-side use.
+ *
+ * Each level has a numeric value that enables level-based filtering.
+ * A transporter configured with a minimum level will only process
+ * messages at or above that severity.
+ *
+ * @module enums/log-level
+ */
+declare enum LogLevel {
+    /**
+     * Detailed debug information.
+     * Use for development-time diagnostics that should not appear in production.
+     */
+    Debug = 0,
+    /**
+     * Interesting events.
+     * Example: User logs in, feature flag evaluated, route navigated.
+     */
+    Info = 1,
+    /**
+     * Exceptional occurrences that are not errors.
+     * Example: Use of deprecated APIs, poor use of an API, recoverable issues.
+     */
+    Warn = 2,
+    /**
+     * Runtime errors that do not require immediate action but should
+     * typically be logged and monitored.
+     */
+    Error = 3,
+    /**
+     * System is unusable or a critical failure has occurred.
+     * Example: Unrecoverable state, data corruption detected.
+     */
+    Fatal = 4
+}
+
+/**
+ * Log Entry Interface
+ *
+ * Represents a single log message with all associated metadata.
+ * This is the core data structure that flows through formatters
+ * and transporters. Every log call produces one LogEntry.
+ *
+ * @module interfaces/log-entry
+ */
+
+interface LogEntry {
+    /**
+     * The severity level of this log entry.
+     * Determines how the message is displayed and whether it passes
+     * the transporter's minimum level filter.
+     */
+    level: LogLevel;
+    /**
+     * The human-readable log message.
+     * May contain interpolation placeholders depending on the formatter.
+     */
+    message: string;
+    /**
+     * ISO 8601 timestamp of when the log entry was created.
+     * Automatically set by the Logger at the time of the log call.
+     *
+     * @example "2026-03-28T14:30:00.000Z"
+     */
+    timestamp: string;
+    /**
+     * Contextual data attached to this log entry.
+     * Merged from the logger's shared context and any per-call context.
+     * Useful for structured logging (e.g., user ID, request ID, component name).
+     */
+    context: Record<string, unknown>;
+}
+
+/**
+ * Formatter Interface
+ *
+ * Defines the contract for log message formatters. A formatter is
+ * responsible for converting a LogEntry into a presentable string
+ * (or structured output) before it is handed to a transporter.
+ *
+ * Inspired by Monolog's FormatterInterface / Laravel's log formatting,
+ * adapted for lightweight client-side usage.
+ *
+ * @module interfaces/formatter
+ *
+ * @example
+ * ```ts
+ * class MyFormatter implements FormatterInterface {
+ *   format(entry: LogEntry): string {
+ *     return `[${entry.level}] ${entry.message}`;
+ *   }
+ * }
+ * ```
+ */
+
+interface FormatterInterface {
+    /**
+     * Format a log entry into a string representation.
+     *
+     * @param entry - The log entry to format.
+     * @returns The formatted string ready for output.
+     */
+    format(entry: LogEntry): string;
+}
+
+/**
+ * Transporter Interface
+ *
+ * Defines the contract for log transporters (also known as handlers
+ * or channels in other frameworks). A transporter receives formatted
+ * log entries and delivers them to a specific destination — such as
+ * the browser console, localStorage, or a remote endpoint.
+ *
+ * Inspired by Laravel's channel/handler pattern and Monolog's
+ * HandlerInterface, simplified for client-side environments.
+ *
+ * @module interfaces/transporter
+ *
+ * @example
+ * ```ts
+ * class MyTransporter implements TransporterInterface {
+ *   private formatter: FormatterInterface = new SimpleFormatter();
+ *
+ *   transport(entry: LogEntry): void {
+ *     const output = this.formatter.format(entry);
+ *     // deliver output to destination
+ *   }
+ *
+ *   setFormatter(formatter: FormatterInterface): void {
+ *     this.formatter = formatter;
+ *   }
+ *
+ *   getFormatter(): FormatterInterface {
+ *     return this.formatter;
+ *   }
+ * }
+ * ```
+ */
+
+interface TransporterInterface {
+    /**
+     * Deliver a log entry to the transport destination.
+     * The transporter should use its assigned formatter to convert the
+     * entry into the appropriate output format before delivery.
+     *
+     * @param entry - The log entry to transport.
+     */
+    transport(entry: LogEntry): void;
+    /**
+     * Replace the current formatter with a new one.
+     *
+     * @param formatter - The formatter instance to use for future entries.
+     */
+    setFormatter(formatter: FormatterInterface): void;
+    /**
+     * Retrieve the currently assigned formatter.
+     *
+     * @returns The active formatter instance.
+     */
+    getFormatter(): FormatterInterface;
+    /**
+     * Get the minimum log level this transporter will handle.
+     * Entries below this level should be silently ignored.
+     *
+     * @returns The minimum LogLevel threshold.
+     */
+    getLevel(): LogLevel;
+    /**
+     * Set the minimum log level this transporter will handle.
+     *
+     * @param level - The minimum LogLevel threshold.
+     */
+    setLevel(level: LogLevel): void;
+}
+
+/**
+ * Logger Interface
+ *
+ * Defines the public contract for the Logger. Consumers should
+ * depend on this interface rather than the concrete Logger class
+ * to enable easy testing and substitution.
+ *
+ * Follows PSR-3 / Laravel conventions with log level methods,
+ * contextual logging (withContext / withoutContext), and
+ * transporter management.
+ *
+ * @module interfaces/logger
+ */
+
+interface LoggerInterface {
+    /**
+     * Log a message at the debug level.
+     *
+     * @param message - The log message.
+     * @param context - Optional contextual data for this single entry.
+     */
+    debug(message: string, context?: Record<string, unknown>): void;
+    /**
+     * Log a message at the info level.
+     *
+     * @param message - The log message.
+     * @param context - Optional contextual data for this single entry.
+     */
+    info(message: string, context?: Record<string, unknown>): void;
+    /**
+     * Log a message at the warn level.
+     *
+     * @param message - The log message.
+     * @param context - Optional contextual data for this single entry.
+     */
+    warn(message: string, context?: Record<string, unknown>): void;
+    /**
+     * Log a message at the error level.
+     *
+     * @param message - The log message.
+     * @param context - Optional contextual data for this single entry.
+     */
+    error(message: string, context?: Record<string, unknown>): void;
+    /**
+     * Log a message at the fatal level.
+     *
+     * @param message - The log message.
+     * @param context - Optional contextual data for this single entry.
+     */
+    fatal(message: string, context?: Record<string, unknown>): void;
+    /**
+     * Add persistent context that will be merged into every future log entry.
+     * Calling this multiple times merges new keys into the existing context.
+     *
+     * Inspired by Laravel's `Logger::withContext()`.
+     *
+     * @param context - Key-value pairs to add to the shared context.
+     * @returns The logger instance for fluent chaining.
+     */
+    withContext(context: Record<string, unknown>): this;
+    /**
+     * Remove keys from the shared context, or clear it entirely.
+     *
+     * When called with an array of keys, only those keys are removed.
+     * When called without arguments, the entire shared context is flushed.
+     *
+     * Inspired by Laravel's `Logger::withoutContext()`.
+     *
+     * @param keys - Optional array of context keys to remove.
+     * @returns The logger instance for fluent chaining.
+     */
+    withoutContext(keys?: string[]): this;
+    /**
+     * Retrieve all currently registered transporters.
+     *
+     * @returns An array of active transporter instances.
+     */
+    getTransporters(): TransporterInterface[];
+}
+
+/**
+ * Logger Configuration Interface
+ *
+ * Defines the shape of configuration options accepted by the Logger
+ * constructor and the LoggerManager. Provides sensible defaults so
+ * consumers can create a logger with zero configuration.
+ *
+ * @module interfaces/logger-config
+ *
+ * @example
+ * ```ts
+ * const config: LoggerConfig = {
+ *   transporters: [new ConsoleTransporter()],
+ *   context: { app: 'my-app' },
+ * };
+ * const logger = new Logger(config);
+ * ```
+ */
+
+interface LoggerConfig {
+    /**
+     * The list of transporters that will receive log entries.
+     * If omitted, the logger will default to a single ConsoleTransporter.
+     */
+    transporters?: TransporterInterface[];
+    /**
+     * Initial shared context that will be merged into every log entry.
+     * Useful for setting application-wide metadata such as app name,
+     * environment, or version.
+     *
+     * @default {}
+     */
+    context?: Record<string, unknown>;
+}
+
+/**
+ * Logger Service Interface
+ *
+ * Defines the contract for logger service implementations.
+ * Manages multiple logging channels.
+ */
+interface LoggerServiceInterface {
+    /**
+     * Get a logger channel by name
+     *
+     * @param channelName - Channel name (uses default if not specified)
+     * @returns Logger instance
+     */
+    channel(channelName?: string): LoggerInterface;
+    /**
+     * Get the default channel name
+     *
+     * @returns Default channel name
+     */
+    getDefaultChannelName(): string;
+    /**
+     * Get all configured channel names
+     *
+     * @returns Array of channel names
+     */
+    getChannelNames(): string[];
+    /**
+     * Check if a channel exists
+     *
+     * @param channelName - Channel name
+     * @returns True if channel exists
+     */
+    hasChannel(channelName: string): boolean;
+    /**
+     * Log a debug message to default channel
+     */
+    debug(message: string, context?: Record<string, unknown>): void;
+    /**
+     * Log an info message to default channel
+     */
+    info(message: string, context?: Record<string, unknown>): void;
+    /**
+     * Log a warning message to default channel
+     */
+    warn(message: string, context?: Record<string, unknown>): void;
+    /**
+     * Log an error message to default channel
+     */
+    error(message: string, context?: Record<string, unknown>): void;
+}
+
+/**
+ * Logger Module Configuration
+ *
+ * Defines the configuration interface for the logger module.
+ * Supports multiple channels with different transporters and settings.
+ *
+ * @module config/logger
+ */
+
+/**
+ * Logger module options
+ *
+ * Configuration for the logger module with support for multiple channels.
+ * Each channel can have its own transporters, context, and settings.
+ *
+ * @example
+ * ```typescript
+ * const config: LoggerModuleOptions = {
+ *   default: 'console',
+ *   channels: {
+ *     console: {
+ *       transporters: [new ConsoleTransporter()],
+ *       context: { app: 'my-app' },
+ *     },
+ *     storage: {
+ *       transporters: [new StorageTransporter()],
+ *     },
+ *     errors: {
+ *       transporters: [
+ *         new ConsoleTransporter({ level: LogLevel.ERROR }),
+ *         new StorageTransporter({ key: 'error-logs' }),
+ *       ],
+ *     },
+ *   },
+ * };
+ * ```
+ */
+interface LoggerModuleOptions {
+    /**
+     * Default channel name
+     *
+     * The channel to use when no specific channel is requested.
+     * Must match one of the keys in the channels object.
+     */
+    default: string;
+    /**
+     * Channel configurations
+     *
+     * Map of channel names to their configurations.
+     * Each channel can have its own transporters and settings.
+     */
+    channels: Record<string, LoggerConfig>;
+}
+/**
+ * Helper function to define logger configuration with type safety
+ *
+ * @param config - Logger module options
+ * @returns The same config with proper typing
+ *
+ * @example
+ * ```typescript
+ * import { defineConfig } from '@abdokouta/logger';
+ *
+ * const config = defineConfig({
+ *   default: 'console',
+ *   channels: {
+ *     console: {
+ *       transporters: [new ConsoleTransporter()],
+ *     },
+ *   },
+ * });
+ * ```
+ */
+declare function defineConfig(config: LoggerModuleOptions): LoggerModuleOptions;
+
+/**
+ * Logger service implementation
+ *
+ * Provides a unified logging API with support for multiple channels.
+ * Handles channel management internally without a separate manager class.
+ *
+ * @example
+ * ```typescript
+ * @Injectable()
+ * class UserService {
+ *   constructor(
+ *     @Inject(LoggerService) private logger: LoggerService
+ *   ) {}
+ *
+ *   async createUser(data: UserData) {
+ *     // Use default channel
+ *     this.logger.info('Creating user', { email: data.email });
+ *
+ *     try {
+ *       const user = await this.db.users.create(data);
+ *       this.logger.info('User created', { userId: user.id });
+ *       return user;
+ *     } catch (error) {
+ *       this.logger.error('Failed to create user', { error });
+ *       throw error;
+ *     }
+ *   }
+ *
+ *   async auditAction(action: string) {
+ *     // Use specific channel
+ *     const auditLogger = this.logger.channel('audit');
+ *     auditLogger.info('User action', { action });
+ *   }
+ * }
+ * ```
+ */
+declare class LoggerService implements LoggerServiceInterface {
+    /** Logger configuration */
+    private readonly config;
+    /** Cached channel instances */
+    private channels;
+    /** Default channel instance */
+    private defaultChannel?;
+    /**
+     * Create a new logger service
+     *
+     * @param config - Logger configuration
+     */
+    constructor(config: LoggerModuleOptions);
+    /**
+     * Get a logger channel instance
+     *
+     * Returns the specified channel, or the default channel if no name is provided.
+     * Channels are lazily initialized and cached.
+     *
+     * @param name - Channel name (uses default if not specified)
+     * @returns Logger instance
+     * @throws Error if channel is not configured
+     *
+     * @example
+     * ```typescript
+     * // Use default channel
+     * const logger = loggerService.channel();
+     * logger.info('Default message');
+     *
+     * // Use specific channel
+     * const errorLogger = loggerService.channel('errors');
+     * errorLogger.error('Critical error');
+     * ```
+     */
+    channel(name?: string): LoggerInterface;
+    /**
+     * Log a message at the debug level (default channel)
+     *
+     * @param message - The log message
+     * @param context - Optional contextual data
+     *
+     * @example
+     * ```typescript
+     * loggerService.debug('Cache hit', { key: 'user:123' });
+     * ```
+     */
+    debug(message: string, context?: Record<string, unknown>): void;
+    /**
+     * Log a message at the info level (default channel)
+     *
+     * @param message - The log message
+     * @param context - Optional contextual data
+     *
+     * @example
+     * ```typescript
+     * loggerService.info('User logged in', { userId: '123' });
+     * ```
+     */
+    info(message: string, context?: Record<string, unknown>): void;
+    /**
+     * Log a message at the warn level (default channel)
+     *
+     * @param message - The log message
+     * @param context - Optional contextual data
+     *
+     * @example
+     * ```typescript
+     * loggerService.warn('API rate limit approaching', { remaining: 10 });
+     * ```
+     */
+    warn(message: string, context?: Record<string, unknown>): void;
+    /**
+     * Log a message at the error level (default channel)
+     *
+     * @param message - The log message
+     * @param context - Optional contextual data
+     *
+     * @example
+     * ```typescript
+     * loggerService.error('Database connection failed', { error });
+     * ```
+     */
+    error(message: string, context?: Record<string, unknown>): void;
+    /**
+     * Log a message at the fatal level (default channel)
+     *
+     * @param message - The log message
+     * @param context - Optional contextual data
+     *
+     * @example
+     * ```typescript
+     * loggerService.fatal('Application crashed', { error, stack });
+     * ```
+     */
+    fatal(message: string, context?: Record<string, unknown>): void;
+    /**
+     * Add persistent context to the default channel
+     *
+     * @param context - Key-value pairs to add to the shared context
+     * @returns The logger service instance for fluent chaining
+     *
+     * @example
+     * ```typescript
+     * loggerService
+     *   .withContext({ requestId: 'abc-123' })
+     *   .withContext({ userId: 42 })
+     *   .info('Processing request');
+     * ```
+     */
+    withContext(context: Record<string, unknown>): this;
+    /**
+     * Remove keys from the default channel's shared context
+     *
+     * @param keys - Optional array of context keys to remove
+     * @returns The logger service instance for fluent chaining
+     *
+     * @example
+     * ```typescript
+     * // Remove specific keys
+     * loggerService.withoutContext(['userId', 'requestId']);
+     *
+     * // Clear all context
+     * loggerService.withoutContext();
+     * ```
+     */
+    withoutContext(keys?: string[]): this;
+    /**
+     * Get all transporters from the default channel
+     *
+     * @returns Array of transporter instances
+     */
+    getTransporters(): TransporterInterface[];
+    /**
+     * Get the default channel name
+     *
+     * @returns Default channel name
+     */
+    getDefaultChannelName(): string;
+    /**
+     * Get all configured channel names
+     *
+     * @returns Array of channel names
+     */
+    getChannelNames(): string[];
+    /**
+     * Check if a channel is configured
+     *
+     * @param name - Channel name
+     * @returns True if the channel is configured
+     */
+    hasChannel(name: string): boolean;
+    /**
+     * Check if a channel is currently active (cached)
+     *
+     * @param name - Channel name (uses default if not specified)
+     * @returns True if the channel is active
+     */
+    isChannelActive(name?: string): boolean;
+    /**
+     * Get the default channel instance
+     *
+     * @returns Logger instance
+     * @throws Error if default channel cannot be resolved
+     * @private
+     */
+    private getDefaultChannel;
+    /**
+     * Resolve a channel by name
+     *
+     * Creates a new logger instance based on channel configuration.
+     *
+     * @param name - Channel name
+     * @returns Logger instance
+     * @throws Error if channel is not configured
+     * @private
+     */
+    private resolve;
+}
+
+/**
+ * Logger Module
+ *
+ * Configures the logger system for dependency injection.
+ * Provides LoggerService (NO manager) to the application.
+ *
+ * @module logger.module
+ */
+
+/**
+ * Logger module
+ *
+ * Provides LoggerService to the application via dependency injection.
+ * The service handles channels internally (NO separate manager).
+ *
+ * @example
+ * ```typescript
+ * import { Module } from '@abdokouta/react-di';
+ * import { LoggerModule, defineConfig } from '@abdokouta/logger';
+ * import { ConsoleTransporter, StorageTransporter } from '@abdokouta/logger';
+ * import { LogLevel } from '@abdokouta/logger';
+ *
+ * @Module({
+ *   imports: [
+ *     LoggerModule.forRoot(
+ *       defineConfig({
+ *         default: 'console',
+ *         channels: {
+ *           console: {
+ *             transporters: [new ConsoleTransporter()],
+ *             context: { app: 'my-app' },
+ *           },
+ *           storage: {
+ *             transporters: [new StorageTransporter({ maxEntries: 500 })],
+ *           },
+ *           errors: {
+ *             transporters: [
+ *               new ConsoleTransporter({ level: LogLevel.Error }),
+ *               new StorageTransporter({ key: 'error-logs' }),
+ *             ],
+ *           },
+ *         },
+ *       })
+ *     ),
+ *   ],
+ * })
+ * export class AppModule {}
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Using logger in a service
+ * import { Injectable, Inject } from '@abdokouta/react-di';
+ * import { LoggerService } from '@abdokouta/logger';
+ *
+ * @Injectable()
+ * export class UserService {
+ *   constructor(
+ *     @Inject(LoggerService) private logger: LoggerService
+ *   ) {}
+ *
+ *   async createUser(data: UserData) {
+ *     this.logger.info('Creating user', { email: data.email });
+ *
+ *     try {
+ *       const user = await this.db.users.create(data);
+ *       this.logger.info('User created', { userId: user.id });
+ *       return user;
+ *     } catch (error) {
+ *       this.logger.error('Failed to create user', { error });
+ *       throw error;
+ *     }
+ *   }
+ *
+ *   async auditAction(action: string) {
+ *     // Use specific channel
+ *     const auditLogger = this.logger.channel('audit');
+ *     auditLogger.info('User action', { action });
+ *   }
+ * }
+ * ```
+ */
+declare class LoggerModule {
+    /**
+     * Configure the logger module
+     *
+     * @param config - Logger configuration (can be passed directly without defineConfig)
+     * @returns Dynamic module
+     *
+     * @example
+     * ```typescript
+     * LoggerModule.forRoot({
+     *   default: 'console',
+     *   channels: {
+     *     console: {
+     *       transporters: [new ConsoleTransporter()],
+     *     },
+     *   },
+     * })
+     * ```
+     */
+    static forRoot(config: LoggerModuleOptions): DynamicModule;
+    /**
+     * Process configuration to add default transporters if needed
+     *
+     * @param config - Raw configuration
+     * @returns Processed configuration with defaults
+     * @private
+     */
+    private static processConfig;
+}
+
+/**
+ * Pretty Formatter
+ *
+ * A visually rich formatter that produces colorful, emoji-prefixed
+ * log output designed for the browser console. Each log level is
+ * assigned a distinct emoji and CSS color to make scanning logs
+ * effortless during development.
+ *
+ * This is the default formatter used by the ConsoleTransporter.
+ *
+ * @module formatters/pretty
+ *
+ * @example
+ * ```ts
+ * const formatter = new PrettyFormatter();
+ * const output = formatter.format(entry);
+ * // => "🐛 [DEBUG] [14:30:00.000] Hello world {userId: 42}"
+ * ```
+ */
+
+declare class PrettyFormatter implements FormatterInterface {
+    /**
+     * Format a log entry into a pretty, human-readable string with
+     * emoji prefix, level badge, timestamp, message, and context.
+     *
+     * The returned string includes `%c` placeholders for CSS styling
+     * in the browser console. The ConsoleTransporter is responsible
+     * for passing the corresponding style strings.
+     *
+     * @param entry - The log entry to format.
+     * @returns The formatted string with CSS style placeholders.
+     */
+    format(entry: LogEntry): string;
+    /**
+     * Extract a short time string (HH:mm:ss.SSS) from an ISO timestamp.
+     *
+     * @param timestamp - ISO 8601 timestamp string.
+     * @returns A short time-only representation.
+     */
+    private formatTimestamp;
+    /**
+     * Serialize context data into a compact, readable string.
+     * Returns an empty string when context is empty to keep output clean.
+     *
+     * @param context - The context record to serialize.
+     * @returns A formatted context string or empty string.
+     */
+    private formatContext;
+}
+
+declare class JsonFormatter implements FormatterInterface {
+    /**
+     * Format a log entry as a JSON string.
+     *
+     * Produces a flat JSON object with level (as string), message,
+     * timestamp, and context fields. Context is omitted when empty
+     * to keep output compact.
+     *
+     * @param entry - The log entry to format.
+     * @returns A JSON-serialized string representation of the entry.
+     */
+    format(entry: LogEntry): string;
+}
+
+declare class SimpleFormatter implements FormatterInterface {
+    /**
+     * Format a log entry into a plain text line.
+     *
+     * Output pattern: `[LEVEL] [timestamp] message {context}`
+     *
+     * @param entry - The log entry to format.
+     * @returns A plain text string with no styling.
+     */
+    format(entry: LogEntry): string;
+    /**
+     * Serialize context data into a compact string.
+     * Returns an empty string when context is empty.
+     *
+     * @param context - The context record to serialize.
+     * @returns A formatted context string or empty string.
+     */
+    private formatContext;
+}
+
+/**
+ * Console Transporter
+ *
+ * Delivers log entries to the browser's developer console using the
+ * appropriate `console.*` method for each severity level. When paired
+ * with the PrettyFormatter (the default), output includes CSS-styled
+ * level badges with colors and emoji prefixes.
+ *
+ * This is the primary transporter for development environments.
+ *
+ * @module transporters/console
+ *
+ * @example
+ * ```ts
+ * const transporter = new ConsoleTransporter();
+ * transporter.transport(entry); // outputs to console with colors
+ *
+ * // With custom minimum level:
+ * const warnOnly = new ConsoleTransporter({ level: LogLevel.Warn });
+ * ```
+ */
+
+/**
+ * Configuration options for the ConsoleTransporter.
+ */
+interface ConsoleTransporterOptions {
+    /**
+     * The formatter to use for log entries.
+     * Defaults to PrettyFormatter if not provided.
+     */
+    formatter?: FormatterInterface;
+    /**
+     * The minimum log level to transport.
+     * Entries below this level are silently ignored.
+     *
+     * @default LogLevel.Debug
+     */
+    level?: LogLevel;
+}
+declare class ConsoleTransporter implements TransporterInterface {
+    /**
+  The formatter used to convert log entries into output strings. */
+    private _formatter;
+    /**
+  The minimum log level threshold for this transporter. */
+    private _level;
+    /**
+     * Create a new ConsoleTransporter instance.
+     *
+     * @param options - Optional configuration for formatter and minimum level.
+     */
+    constructor(options?: ConsoleTransporterOptions);
+    /**
+     * Deliver a log entry to the browser console.
+     *
+     * Routes the entry to the appropriate `console.*` method based on
+     * the log level. When using the PrettyFormatter, CSS styles are
+     * applied via `%c` placeholders for colored output.
+     *
+     * Entries below the configured minimum level are silently skipped.
+     *
+     * @param entry - The log entry to output.
+     */
+    transport(entry: LogEntry): void;
+    /**
+     * Replace the current formatter.
+     *
+     * @param formatter - The new formatter instance to use.
+     */
+    setFormatter(formatter: FormatterInterface): void;
+    /**
+     * Retrieve the currently assigned formatter.
+     *
+     * @returns The active formatter instance.
+     */
+    getFormatter(): FormatterInterface;
+    /**
+     * Get the minimum log level this transporter handles.
+     *
+     * @returns The current minimum LogLevel threshold.
+     */
+    getLevel(): LogLevel;
+    /**
+     * Set the minimum log level this transporter handles.
+     *
+     * @param level - The new minimum LogLevel threshold.
+     */
+    setLevel(level: LogLevel): void;
+    /**
+     * Resolve the appropriate `console.*` method for a given log level.
+     *
+     * Maps logger severity levels to the closest browser console method
+     * to ensure proper DevTools filtering and visual distinction.
+     *
+     * @param level - The log level to resolve.
+     * @returns The bound console method function.
+     */
+    private resolveConsoleMethod;
+}
+
+/**
+ * Silent Transporter
+ *
+ * A no-op transporter that silently discards all log entries.
+ * Useful for production environments where logging should be
+ * disabled, or for testing scenarios where log output would
+ * pollute test results.
+ *
+ * Equivalent to Laravel's "null" log driver.
+ *
+ * @module transporters/silent
+ *
+ * @example
+ * ```ts
+ * const logger = new Logger({
+ *   transporters: [new SilentTransporter()],
+ * });
+ * logger.info('This will be silently discarded');
+ * ```
+ */
+
+declare class SilentTransporter implements TransporterInterface {
+    /**
+  The formatter instance (maintained for interface compliance). */
+    private _formatter;
+    /**
+  The minimum log level (maintained for interface compliance). */
+    private _level;
+    /**
+     * Create a new SilentTransporter instance.
+     * All parameters are optional and exist only for interface compliance.
+     */
+    constructor();
+    /**
+     * No-op transport method. Silently discards the entry.
+     *
+     * @param _entry - The log entry (ignored).
+     */
+    transport(_entry: LogEntry): void;
+    /**
+     * Replace the current formatter.
+     *
+     * @param formatter - The new formatter instance.
+     */
+    setFormatter(formatter: FormatterInterface): void;
+    /**
+     * Retrieve the currently assigned formatter.
+     *
+     * @returns The active formatter instance.
+     */
+    getFormatter(): FormatterInterface;
+    /**
+     * Get the minimum log level.
+     *
+     * @returns The current minimum LogLevel threshold.
+     */
+    getLevel(): LogLevel;
+    /**
+     * Set the minimum log level.
+     *
+     * @param level - The new minimum LogLevel threshold.
+     */
+    setLevel(level: LogLevel): void;
+}
+
+/**
+ * Storage Transporter
+ *
+ * Persists log entries to the browser's localStorage as JSON strings.
+ * Useful for capturing logs that survive page reloads, enabling
+ * post-mortem debugging or user-submitted bug reports that include
+ * recent log history.
+ *
+ * Entries are stored as a JSON array under a configurable storage key.
+ * A maximum entry limit prevents unbounded storage growth.
+ *
+ * @module transporters/storage
+ *
+ * @example
+ * ```ts
+ * const transporter = new StorageTransporter({
+ *   key: 'app-logs',
+ *   maxEntries: 200,
+ * });
+ * ```
+ */
+
+/**
+ * Configuration options for the StorageTransporter.
+ */
+interface StorageTransporterOptions {
+    /**
+     * The localStorage key under which log entries are stored.
+     *
+     * @default "logger:entries"
+     */
+    key?: string;
+    /**
+     * Maximum number of entries to retain in storage.
+     * When the limit is exceeded, the oldest entries are discarded (FIFO).
+     *
+     * @default 100
+     */
+    maxEntries?: number;
+    /**
+     * The formatter to use for serializing log entries.
+     * Defaults to JsonFormatter if not provided.
+     */
+    formatter?: FormatterInterface;
+    /**
+     * The minimum log level to transport.
+     * Entries below this level are silently ignored.
+     *
+     * @default LogLevel.Debug
+     */
+    level?: LogLevel;
+}
+declare class StorageTransporter implements TransporterInterface {
+    /**
+  The formatter used to convert log entries into storable strings. */
+    private _formatter;
+    /**
+  The minimum log level threshold for this transporter. */
+    private _level;
+    /**
+  The localStorage key for persisting entries. */
+    private readonly _key;
+    /**
+  Maximum number of entries to retain. */
+    private readonly _maxEntries;
+    /**
+     * Create a new StorageTransporter instance.
+     *
+     * @param options - Optional configuration for storage key, limits, and formatter.
+     */
+    constructor(options?: StorageTransporterOptions);
+    /**
+     * Persist a log entry to localStorage.
+     *
+     * The entry is formatted, appended to the existing entries array,
+     * and trimmed to the maximum entry limit. If localStorage is
+     * unavailable or full, the error is silently swallowed to avoid
+     * crashing the application.
+     *
+     * @param entry - The log entry to persist.
+     */
+    transport(entry: LogEntry): void;
+    /**
+     * Replace the current formatter.
+     *
+     * @param formatter - The new formatter instance.
+     */
+    setFormatter(formatter: FormatterInterface): void;
+    /**
+     * Retrieve the currently assigned formatter.
+     *
+     * @returns The active formatter instance.
+     */
+    getFormatter(): FormatterInterface;
+    /**
+     * Get the minimum log level this transporter handles.
+     *
+     * @returns The current minimum LogLevel threshold.
+     */
+    getLevel(): LogLevel;
+    /**
+     * Set the minimum log level this transporter handles.
+     *
+     * @param level - The new minimum LogLevel threshold.
+     */
+    setLevel(level: LogLevel): void;
+    /**
+     * Clear all stored log entries from localStorage.
+     * Useful for manual cleanup or when resetting application state.
+     */
+    clear(): void;
+    /**
+     * Retrieve all stored log entries from localStorage.
+     *
+     * @returns An array of formatted log entry strings.
+     */
+    getEntries(): string[];
+    /**
+     * Read the current entries array from localStorage.
+     * Returns an empty array if the key does not exist or parsing fails.
+     *
+     * @returns The parsed entries array.
+     */
+    private readEntries;
+}
+
+/**
+ * useLogger Hook
+ *
+ * React hook for accessing the logger service in components.
+ * Provides access to the default channel or a specific channel.
+ *
+ * @module hooks/use-logger
+ */
+
+/**
+ * Access the logger service in React components
+ *
+ * Returns the logger service instance or a specific channel.
+ *
+ * @param channelName - Optional channel name (uses default if not specified)
+ * @returns Logger instance
+ *
+ * @example
+ * ```typescript
+ * import { useLogger } from '@abdokouta/logger';
+ *
+ * function MyComponent() {
+ *   const logger = useLogger();
+ *
+ *   const handleClick = () => {
+ *     logger.info('Button clicked', { timestamp: Date.now() });
+ *   };
+ *
+ *   return <button onClick={handleClick}>Click me</button>;
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Use specific channel
+ * function ErrorBoundary({ error }: { error: Error }) {
+ *   const errorLogger = useLogger('errors');
+ *
+ *   useEffect(() => {
+ *     errorLogger.error('Component error', {
+ *       message: error.message,
+ *       stack: error.stack,
+ *     });
+ *   }, [error]);
+ *
+ *   return <div>Something went wrong</div>;
+ * }
+ * ```
+ */
+declare function useLogger(channelName?: string): LoggerInterface;
+
+/**
+ * useLoggerContext Hook
+ *
+ * React hook for managing logger context in components.
+ * Automatically adds and removes context based on component lifecycle.
+ *
+ * @module hooks/use-logger-context
+ */
+/**
+ * Manage logger context in React components
+ *
+ * Automatically adds context when the component mounts and removes it when unmounted.
+ * Useful for adding component-specific context to all logs.
+ *
+ * @param context - Context to add to the logger
+ * @param channelName - Optional channel name (uses default if not specified)
+ *
+ * @example
+ * ```typescript
+ * import { useLoggerContext } from '@abdokouta/logger';
+ *
+ * function UserProfile({ userId }: { userId: string }) {
+ *   // Add userId to all logs in this component
+ *   useLoggerContext({ userId, component: 'UserProfile' });
+ *
+ *   const logger = useLogger();
+ *
+ *   const handleUpdate = () => {
+ *     // This log will include { userId, component: 'UserProfile' }
+ *     logger.info('Updating profile');
+ *   };
+ *
+ *   return <button onClick={handleUpdate}>Update</button>;
+ * }
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With specific channel
+ * function PaymentForm({ orderId }: { orderId: string }) {
+ *   useLoggerContext({ orderId, form: 'payment' }, 'payment');
+ *
+ *   const logger = useLogger('payment');
+ *
+ *   const handleSubmit = () => {
+ *     logger.info('Payment submitted');
+ *   };
+ *
+ *   return <form onSubmit={handleSubmit}>...</form>;
+ * }
+ * ```
+ */
+declare function useLoggerContext(context: Record<string, unknown>, channelName?: string): void;
+
+export { ConsoleTransporter, type ConsoleTransporterOptions, type FormatterInterface, JsonFormatter, type LogEntry, LogLevel, LoggerService as Logger, type LoggerConfig, type LoggerInterface, LoggerModule, type LoggerModuleOptions, LoggerService, type LoggerServiceInterface, PrettyFormatter, SilentTransporter, SimpleFormatter, StorageTransporter, type StorageTransporterOptions, type TransporterInterface, defineConfig, useLogger, useLoggerContext };