konsole-logger 3.0.0

package/dist/index.d.ts

@@ -0,0 +1,605 @@
+export declare class BrowserFormatter implements Formatter {
+    write(entry: LogEntry): void;
+}
+
+/**
+ * A memory-efficient circular buffer for storing logs
+ * Automatically evicts oldest entries when capacity is reached
+ */
+export declare class CircularBuffer<T> {
+    private buffer;
+    private head;
+    private tail;
+    private _size;
+    private capacity;
+    constructor(capacity: number);
+    /**
+     * Add an item to the buffer
+     * If buffer is full, oldest item is overwritten
+     */
+    push(item: T): void;
+    /**
+     * Get all items in order (oldest to newest)
+     */
+    toArray(): T[];
+    /**
+     * Get a slice of items
+     */
+    slice(start: number, end?: number): T[];
+    /**
+     * Filter items and return matching ones
+     */
+    filter(predicate: (item: T) => boolean): T[];
+    /**
+     * Remove items that don't match the predicate
+     * Returns the new size
+     */
+    retain(predicate: (item: T) => boolean): number;
+    /**
+     * Clear all items
+     */
+    clear(): void;
+    /**
+     * Current number of items
+     */
+    get size(): number;
+    /**
+     * Check if buffer is empty
+     */
+    get isEmpty(): boolean;
+    /**
+     * Check if buffer is at capacity
+     */
+    get isFull(): boolean;
+}
+
+/**
+ * Writes log entries to the console / stdout using the formatter pipeline.
+ *
+ * Primarily useful when the main logger is configured with `format: 'silent'`
+ * and you want granular control over what gets printed via separate transports.
+ *
+ * @example
+ * ```ts
+ * const logger = new Konsole({
+ *   namespace: 'App',
+ *   format: 'silent',
+ *   transports: [
+ *     new ConsoleTransport({ format: 'pretty' }),
+ *     new FileTransport({ path: '/var/log/app.log' }),
+ *   ],
+ * });
+ * ```
+ */
+export declare class ConsoleTransport implements Transport {
+    readonly name: string;
+    private formatter;
+    private filter?;
+    constructor(options?: ConsoleTransportOptions);
+    write(entry: LogEntry): void;
+    destroy(): Promise<void>;
+}
+
+export declare interface ConsoleTransportOptions {
+    /** Default: 'console' */
+    name?: string;
+    /**
+     * Output format. Defaults to `'auto'` (pretty on TTY, JSON on non-TTY, browser in browser).
+     * Useful when the main logger uses `format: 'silent'` and you want transports
+     * to handle all rendering.
+     */
+    format?: KonsoleFormat;
+    /** Only write entries that pass this predicate. */
+    filter?: (entry: LogEntry) => boolean;
+}
+
+/**
+ * Picks the best formatter for the current runtime:
+ *   browser            → BrowserFormatter  (styled DevTools output)
+ *   Node.js + TTY      → PrettyFormatter   (colorized, human-readable)
+ *   Node.js + non-TTY  → JsonFormatter     (newline-delimited JSON)
+ */
+export declare function createAutoFormatter(): Formatter;
+
+export declare function createFormatter(format: KonsoleFormat): Formatter;
+
+/**
+ * Fine-grained output filter. Prefer `level` for simple threshold filtering.
+ * @deprecated Boolean criteria will be removed in a future version. Use `level` or `format: 'silent'`.
+ */
+export declare type Criteria = boolean | ((logEntry: LogEntry) => boolean);
+
+export declare type FileFormat = 'json' | 'text';
+
+/**
+ * Appends log entries as serialized lines to a file on disk.
+ *
+ * Node.js only. Uses `fs.createWriteStream` internally — efficient for
+ * high-throughput logging (writes are buffered by the OS).
+ *
+ * Entries written before the file handle is opened are buffered in memory
+ * and flushed automatically once the stream is ready — no `await ready()`
+ * needed for normal use.
+ *
+ * @example
+ * ```ts
+ * const logger = new Konsole({
+ *   namespace: 'App',
+ *   format: 'pretty',    // human-readable in terminal
+ *   transports: [
+ *     new FileTransport({ path: '/var/log/app.log' }),  // JSON to disk
+ *   ],
+ * });
+ * ```
+ */
+export declare class FileTransport extends StreamTransport {
+    private isReady;
+    private pendingEntries;
+    private filePath;
+    private initialized;
+    constructor(options: FileTransportOptions);
+    /** Override write to buffer entries until the file stream is open. */
+    write(entry: LogEntry): void;
+    /**
+     * Resolves once the underlying file stream has been opened.
+     * Not required for normal use — entries are buffered automatically.
+     */
+    ready(): Promise<void>;
+    private openFile;
+}
+
+export declare interface FileTransportOptions {
+    /** Absolute or relative path of the log file. */
+    path: string;
+    /** Default: derived from path, e.g. `'file:/var/log/app.log'` */
+    name?: string;
+    /**
+     * Line format.
+     * - `'json'`  — newline-delimited JSON (default)
+     * - `'text'`  — human-readable plain text
+     */
+    format?: FileFormat;
+    /**
+     * File open flag passed to `fs.createWriteStream`.
+     * - `'a'`  — append (default, safe for long-running processes)
+     * - `'w'`  — truncate on open
+     */
+    flags?: 'a' | 'w';
+    /** Only write entries that pass this predicate. */
+    filter?: (entry: LogEntry) => boolean;
+}
+
+export declare interface Formatter {
+    write(entry: LogEntry): void;
+}
+
+/**
+ * Resolves the best available `fetch` implementation from the runtime.
+ * Returns `undefined` when fetch is not natively available (Node < 18).
+ */
+export declare function getGlobalFetch(): typeof fetch | undefined;
+
+/**
+ * Batches log entries and POSTs them to an HTTP endpoint.
+ *
+ * Features:
+ * - Configurable batch size and flush interval
+ * - Exponential-backoff retry on failure
+ * - Optional per-entry filter and transform
+ * - Works in browser and Node.js ≥ 18 (or pass `fetchImpl` for older Node)
+ */
+export declare class HttpTransport implements Transport {
+    readonly name: string;
+    private config;
+    private fetchFn;
+    private batch;
+    private flushTimer?;
+    private retryQueue;
+    private isProcessing;
+    constructor(config: TransportConfig);
+    write(entry: LogEntry): void;
+    flush(): Promise<void>;
+    destroy(): Promise<void>;
+    private sendBatch;
+}
+
+/**
+ * Runtime environment detection utilities.
+ * Use these instead of directly checking `window`, `process`, etc.
+ */
+export declare const isBrowser: boolean;
+
+export declare const isNode: boolean;
+
+/**
+ * Returns true when stdout is a TTY (i.e. an interactive terminal).
+ * Used to decide whether to enable pretty-printing by default.
+ */
+export declare function isTTY(): boolean;
+
+export declare function isValidLevel(level: string): level is LogLevelName;
+
+export declare class JsonFormatter implements Formatter {
+    write(entry: LogEntry): void;
+}
+
+/**
+ * Konsole — a lightweight, namespaced logging library for browser and Node.js.
+ *
+ * @example
+ * ```ts
+ * import { Konsole } from 'konsole-logger';
+ *
+ * const logger = new Konsole({ namespace: 'API', level: 'info' });
+ *
+ * logger.info('Server started', { port: 3000 });
+ * logger.error('Request failed', { err: new Error('timeout'), path: '/users' });
+ * ```
+ */
+declare class Konsole implements KonsolePublic {
+    private static instances;
+    private static globalFlagName;
+    private static sharedWorker;
+    private static workerPendingCallbacks;
+    private logs;
+    private namespace;
+    private bindings;
+    private criteria;
+    private formatter;
+    private minLevelValue;
+    private defaultBatchSize;
+    private currentBatchStart;
+    private retentionPeriod;
+    private maxLogs;
+    private cleanupIntervalId?;
+    private useWorker;
+    private transports;
+    constructor(options?: KonsoleOptions);
+    /** Retrieve an existing logger by namespace. Creates a new one if not found. */
+    static getLogger(namespace?: string): Konsole;
+    /** Returns the list of all registered namespace names. */
+    static getNamespaces(): string[];
+    /**
+     * Exposes a `__Konsole` debug handle on `window` for use in browser DevTools.
+     *
+     * @example
+     * ```js
+     * // In browser console:
+     * __Konsole.getLogger('Auth').viewLogs()
+     * __Konsole.listLoggers()
+     * __Konsole.enableAll()
+     * ```
+     */
+    static exposeToWindow(): void;
+    /**
+     * Globally override output for all loggers.
+     * `true`  — forces all loggers to print regardless of their `level` / `criteria`.
+     * `false` — restores normal per-logger rules (default).
+     */
+    static enableGlobalPrint(enabled: boolean): void;
+    /** Add an HTTP transport to every registered logger. */
+    static addGlobalTransport(config: TransportConfig): void;
+    /**
+     * Creates a child logger that inherits this logger's config and prepends
+     * `bindings` to every log entry it produces.
+     *
+     * Bindings accumulate through nested children. Call-site fields always win
+     * over bindings on key collision.
+     *
+     * Children share the parent's circular buffer and formatter.
+     * They are NOT registered in `Konsole.instances` — they are ephemeral.
+     *
+     * @example
+     * ```ts
+     * // Per-request logger
+     * const req = logger.child({ requestId: 'abc', ip: '1.2.3.4' });
+     * req.info('request started', { path: '/users' });
+     * // → INF [App]  request started  requestId=abc ip=1.2.3.4 path=/users
+     *
+     * // Nested child — bindings accumulate
+     * const db = req.child({ component: 'db' }, { namespace: 'App:DB' });
+     * db.debug('query', { sql: 'SELECT...', ms: 4 });
+     * // → DBG [App:DB]  query  requestId=abc ip=1.2.3.4 component=db sql="SELECT..." ms=4
+     * ```
+     */
+    child(bindings: Record<string, unknown>, options?: KonsoleChildOptions): Konsole;
+    /**
+     * Factory that bypasses the normal constructor to produce a child logger
+     * that shares the parent's buffer, formatter, and transports.
+     */
+    private static createChild;
+    /** Level 10 — extremely verbose, disabled in most environments. */
+    trace(...args: unknown[]): void;
+    /** Level 20 — developer-facing detail, hidden at `level: 'info'` and above. */
+    debug(...args: unknown[]): void;
+    /** Level 30 — general informational messages. */
+    info(...args: unknown[]): void;
+    /** Level 30 — alias for `info()` (backward compatibility). */
+    log(...args: unknown[]): void;
+    /** Level 40 — something unexpected but recoverable. */
+    warn(...args: unknown[]): void;
+    /** Level 50 — an operation failed; written to stderr. */
+    error(...args: unknown[]): void;
+    /** Level 60 — unrecoverable failure; written to stderr. */
+    fatal(...args: unknown[]): void;
+    /** Update the minimum log level at runtime. */
+    setLevel(level: LogLevelName): void;
+    /** Update the fine-grained criteria filter. @deprecated Prefer `setLevel()`. */
+    setCriteria(criteria: Criteria): void;
+    /**
+     * Add a transport to this logger.
+     * Accepts both a `TransportConfig` plain object (auto-wrapped in `HttpTransport`)
+     * and a concrete `Transport` instance (`ConsoleTransport`, `FileTransport`, etc.).
+     */
+    addTransport(transport: Transport | TransportConfig): void;
+    /** Flush all pending transport batches immediately. */
+    flushTransports(): Promise<void>;
+    /** Print stored logs in batches using `console.table`. Primarily a browser dev tool. */
+    viewLogs(batchSize?: number): void;
+    /** Returns all stored log entries as a readonly array. */
+    getLogs(): ReadonlyArray<LogEntry>;
+    /** Returns stored log entries asynchronously (resolves from the worker when `useWorker: true`). */
+    getLogsAsync(): Promise<ReadonlyArray<LogEntry>>;
+    /** Discard all stored log entries. */
+    clearLogs(): void;
+    /** Reset the `viewLogs()` pagination cursor back to the beginning. */
+    resetBatch(): void;
+    /** Returns memory usage statistics for this logger's buffer. */
+    getStats(): {
+        logCount: number;
+        maxLogs: number;
+        memoryUsage: string;
+    };
+    /** Flush transports and remove this logger from the registry. */
+    destroy(): Promise<void>;
+    /**
+     * Parses log call arguments into a structured { msg, fields } pair.
+     *
+     * Supported calling conventions:
+     *   logger.info('message')                       → msg='message',   fields={}
+     *   logger.info('message', { userId: 1 })        → msg='message',   fields={userId:1}
+     *   logger.info({ msg: 'message', userId: 1 })   → msg='message',   fields={userId:1}  (Pino-style)
+     *   logger.error(new Error('oops'))              → msg='oops',      fields={err: Error}
+     *   logger.info('a', 'b', 'c')                   → msg='a b c',     fields={}
+     */
+    private parseArgs;
+    private addLog;
+    private outputLog;
+    private initGlobalFlag;
+    private flushOldLogs;
+    private initWorker;
+    private getWorkerCode;
+}
+export { Konsole }
+export default Konsole;
+
+/**
+ * Options accepted by `logger.child()`.
+ */
+export declare interface KonsoleChildOptions {
+    /**
+     * Override the namespace for this child logger.
+     * Useful for labelling a subsystem: `logger.child({}, { namespace: 'App:DB' })`.
+     * Defaults to the parent's namespace.
+     */
+    namespace?: string;
+    /**
+     * Override the minimum log level for this child.
+     * Can only be equal to or more restrictive than the parent — a child cannot
+     * log levels that the parent's buffer would discard.
+     */
+    level?: LogLevelName;
+}
+
+export declare type KonsoleFormat = 'auto' | 'pretty' | 'json' | 'text' | 'browser' | 'silent';
+
+/**
+ * Configuration options for a Konsole logger instance.
+ */
+export declare interface KonsoleOptions {
+    /** Logger namespace shown in every output line (default: 'Global') */
+    namespace?: string;
+    /**
+     * Minimum log level to process. Entries below this level are discarded
+     * immediately — they are neither stored nor output.
+     * @default 'trace' (all levels pass through)
+     */
+    level?: LogLevelName;
+    /**
+     * Output format.
+     * - `'auto'`    — selects based on environment (default)
+     * - `'pretty'`  — colorized, human-readable (Node.js TTY)
+     * - `'json'`    — newline-delimited JSON (pipes / log aggregators)
+     * - `'text'`    — plain text, no ANSI (CI / log files)
+     * - `'browser'` — styled DevTools output via `%c`
+     * - `'silent'`  — no output; logs are still stored in memory
+     * @default 'auto'
+     */
+    format?: KonsoleFormat;
+    /**
+     * Fine-grained output filter or legacy silent flag.
+     * @deprecated Boolean `false` — use `format: 'silent'` instead.
+     *             Boolean `true`  — omit this option (auto-output is now the default).
+     *             Function filter — still fully supported.
+     */
+    criteria?: Criteria;
+    /** Default batch size for `viewLogs()` (default: 100) */
+    defaultBatchSize?: number;
+    /** How long to keep log entries in ms (default: 48 hours) */
+    retentionPeriod?: number;
+    /** How often to run the retention cleanup in ms (default: 1 hour) */
+    cleanupInterval?: number;
+    /** Maximum entries to keep in the circular buffer (default: 10000) */
+    maxLogs?: number;
+    /** Offload log storage to a Web Worker — browser only (default: false) */
+    useWorker?: boolean;
+    /**
+     * Transports to forward log entries to external destinations.
+     * Accepts both `TransportConfig` plain objects (auto-wrapped in `HttpTransport`)
+     * and concrete `Transport` instances (`ConsoleTransport`, `FileTransport`, etc.).
+     */
+    transports?: (Transport | TransportConfig)[];
+}
+
+/**
+ * Public interface for Konsole logger — safe to expose to untrusted code (e.g. via exposeToWindow).
+ */
+export declare interface KonsolePublic {
+    viewLogs(batchSize?: number): void;
+}
+
+/** 3-character uppercase badge shown in terminal output */
+export declare const LEVEL_LABELS: Record<LogLevelName, string>;
+
+export declare const LEVELS: {
+    readonly trace: 10;
+    readonly debug: 20;
+    readonly info: 30;
+    readonly warn: 40;
+    readonly error: 50;
+    readonly fatal: 60;
+};
+
+/**
+ * Represents a single log entry stored in the circular buffer.
+ */
+export declare type LogEntry = {
+    /** Primary log message (extracted from the first string argument). */
+    msg: string;
+    /** All original arguments passed to the log method (kept for backward compatibility). */
+    messages: unknown[];
+    /** Structured key-value fields merged from the call arguments. */
+    fields: Record<string, unknown>;
+    timestamp: Date;
+    namespace: string;
+    level: LogLevelName;
+    levelValue: number;
+    /** @deprecated Use `level` instead. */
+    logtype?: string;
+};
+
+export declare type LogLevelName = keyof typeof LEVELS;
+
+export declare type LogLevelValue = (typeof LEVELS)[LogLevelName];
+
+export declare class PrettyFormatter implements Formatter {
+    write(entry: LogEntry): void;
+}
+
+export declare class SilentFormatter implements Formatter {
+    write(_entry: LogEntry): void;
+}
+
+/**
+ * Writes log entries as serialized lines into any `WritableLike` stream.
+ *
+ * Useful for piping logs into HTTP streams, in-memory streams for testing,
+ * or any custom writable destination.
+ *
+ * @example
+ * ```ts
+ * import { createWriteStream } from 'node:fs';
+ *
+ * const logger = new Konsole({
+ *   namespace: 'App',
+ *   transports: [
+ *     new StreamTransport({
+ *       stream: createWriteStream('/tmp/debug.log', { flags: 'a' }),
+ *       format: 'json',
+ *     }),
+ *   ],
+ * });
+ * ```
+ */
+export declare class StreamTransport implements Transport {
+    readonly name: string;
+    protected stream: WritableLike;
+    protected format: FileFormat;
+    protected filter?: (entry: LogEntry) => boolean;
+    constructor(options: StreamTransportOptions);
+    write(entry: LogEntry): void;
+    destroy(): Promise<void>;
+}
+
+export declare interface StreamTransportOptions {
+    /** The writable stream to pipe entries into. */
+    stream: WritableLike;
+    /** Default: 'stream' */
+    name?: string;
+    /**
+     * Line format written to the stream.
+     * - `'json'`  — newline-delimited JSON (default, best for log aggregators)
+     * - `'text'`  — human-readable plain text
+     */
+    format?: FileFormat;
+    /** Only write entries that pass this predicate. */
+    filter?: (entry: LogEntry) => boolean;
+}
+
+export declare class TextFormatter implements Formatter {
+    write(entry: LogEntry): void;
+}
+
+/**
+ * Base interface all transport implementations must satisfy.
+ *
+ * A transport receives every log entry that passes the logger's level filter
+ * and is responsible for delivering it to some destination (HTTP endpoint,
+ * file, stdout, external stream, etc.).
+ */
+export declare interface Transport {
+    /** Unique identifier used in logs and debug output. */
+    readonly name: string;
+    /** Called synchronously for each entry that passes all filters. */
+    write(entry: LogEntry): void;
+    /**
+     * Flush any buffered entries.
+     * Optional — implement only when the transport batches internally.
+     */
+    flush?(): Promise<void>;
+    /** Flush and release all resources (timers, file handles, sockets). */
+    destroy(): Promise<void>;
+}
+
+/**
+ * Configuration for an HTTP transport that batches and ships logs to an external endpoint.
+ */
+export declare interface TransportConfig {
+    /** Unique identifier for this transport */
+    name: string;
+    /** Endpoint URL to POST logs to */
+    url: string;
+    /** HTTP method (default: POST) */
+    method?: 'POST' | 'PUT';
+    /** Additional request headers */
+    headers?: Record<string, string>;
+    /** Number of entries to accumulate before flushing (default: 50) */
+    batchSize?: number;
+    /** Flush interval in ms (default: 10000) */
+    flushInterval?: number;
+    /** Retry attempts on failure with exponential backoff (default: 3) */
+    retryAttempts?: number;
+    /** Only send entries that pass this predicate */
+    filter?: (entry: LogEntry) => boolean;
+    /** Transform an entry before sending */
+    transform?: (entry: LogEntry) => unknown;
+    /**
+     * Custom fetch implementation.
+     * Required on Node.js < 18. Pass e.g. the default export of `node-fetch`.
+     * Defaults to `globalThis.fetch`.
+     */
+    fetchImpl?: typeof fetch;
+}
+
+/**
+ * Minimal writable-stream contract — duck-typed so it works with Node.js
+ * `stream.Writable`, `fs.WriteStream`, and any compatible implementation
+ * without requiring `@types/node` in the consumer's project.
+ */
+export declare interface WritableLike {
+    write(chunk: string): boolean;
+    end(cb?: (err?: Error | null) => void): void;
+    on(event: 'error', listener: (err: Error) => void): this;
+}
+
+export { }