crisplogs 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,272 @@
+/** Box decoration style for console output. */
+type Style = "short-fixed" | "short-dynamic" | "long-boxed";
+/**
+ * How extra fields are serialized in the log output.
+ * - `"inline"` (default): `[key=value key2=value2]`
+ * - `"json"`: compact single-line JSON — `{"key":"value","key2":"value2"}`
+ * - `"pretty"`: formatted multi-line JSON (best paired with `"long-boxed"` style)
+ */
+type ExtraFormat = "inline" | "json" | "pretty";
+/** Supported log levels, matching Python's logging module hierarchy. */
+type Level = "DEBUG" | "INFO" | "WARNING" | "ERROR" | "CRITICAL";
+/** Numeric values for each log level (matches Python logging). */
+declare const LEVEL_VALUES: Record<Level, number>;
+/** A single log record containing all metadata for one log event. */
+interface LogRecord {
+    levelName: Level;
+    levelNo: number;
+    message: string;
+    timestamp: Date;
+    name: string;
+    pathname: string;
+    lineno: number;
+    extra?: Record<string, unknown>;
+}
+/** Options accepted by {@link setupLogging}. */
+interface SetupLoggingOptions {
+    /** Enable colored output on the console. Default: `true`. */
+    colored?: boolean;
+    /** Box style for console output. Default: `null` (no box). */
+    style?: Style | null;
+    /** Minimum log level for the console handler. Default: `"DEBUG"`. */
+    level?: Level;
+    /** Box width in characters (for `"short-fixed"` and `"long-boxed"`). Default: `100`. */
+    width?: number;
+    /** Date/time format string using `strftime` tokens. Default: `"%Y-%m-%d %H:%M:%S"`. */
+    datefmt?: string;
+    /** Override the default color for each log level. */
+    logColors?: Partial<Record<Level, string>>;
+    /** Path to a log file. ANSI codes are stripped automatically. Default: `null`. */
+    file?: string | null;
+    /** Minimum log level for the file handler. Defaults to the console `level`. */
+    fileLevel?: Level | null;
+    /** Logger name. `""` for root logger. Default: `""`. */
+    name?: string;
+    /**
+     * Capture file path and line number of the caller on each log call.
+     * Disable for higher throughput in production. Default: `true`.
+     */
+    captureCallerInfo?: boolean;
+    /**
+     * How `extra` fields are rendered in the log output.
+     * Only applies to no-style (plain/colored) and `"long-boxed"` outputs.
+     * Default: `"inline"`.
+     */
+    extraFormat?: ExtraFormat;
+}
+/** Interface that all formatters implement. */
+interface Formatter {
+    format(record: LogRecord): string;
+}
+/** Interface that all handlers implement. */
+interface Handler {
+    readonly level: number;
+    formatter: Formatter;
+    emit(record: LogRecord): void;
+    /** Release any resources held by this handler (e.g. file streams). */
+    close(): void;
+}
+
+/**
+ * Logger class for crisplogs.
+ *
+ * Mirrors Python's `logging.Logger` API with level-specific methods
+ * and automatic caller-info capture.
+ */
+
+declare class Logger {
+    readonly name: string;
+    private _level;
+    private _handlers;
+    private _captureCallerInfo;
+    constructor(name: string, level?: number, captureCallerInfo?: boolean);
+    get level(): number;
+    set level(val: number);
+    get handlers(): readonly Handler[];
+    addHandler(handler: Handler): void;
+    removeHandler(handler: Handler): boolean;
+    clearHandlers(): void;
+    isEnabledFor(level: Level): boolean;
+    private _log;
+    debug(message: string, extra?: Record<string, unknown>): void;
+    info(message: string, extra?: Record<string, unknown>): void;
+    warning(message: string, extra?: Record<string, unknown>): void;
+    /** Alias for {@link warning} to match Node.js conventions. */
+    warn(message: string, extra?: Record<string, unknown>): void;
+    error(message: string, extra?: Record<string, unknown>): void;
+    critical(message: string, extra?: Record<string, unknown>): void;
+    /**
+     * Log with an explicit level.
+     *
+     * @example
+     * ```ts
+     * logger.log("INFO", "Server started");
+     * ```
+     */
+    log(level: Level, message: string, extra?: Record<string, unknown>): void;
+}
+
+/**
+ * Formatter for crisplogs.
+ *
+ * A single LogFormatter class covers all output styles via options.
+ */
+
+/** Options accepted by {@link LogFormatter}. */
+interface FormatterOptions {
+    datefmt: string;
+    logColors: Record<string, string>;
+    colored: boolean;
+    /** How extra fields are rendered. Only applies when `box` is false or `wordWrap` is true. */
+    extraFormat?: ExtraFormat;
+    /** Draw a box around each log entry. Default: `false`. */
+    box?: boolean;
+    /**
+     * Full border (`┌─┐ │ └─┘`) instead of left-border only (`┌─ │ └─`).
+     * Only applies when `box` is `true`. Default: `false`.
+     */
+    fullBorder?: boolean;
+    /**
+     * Box width in characters, or `"auto"` to size to the longest line.
+     * Only applies when `box` is `true`. Default: `100`.
+     */
+    width?: number | "auto";
+    /**
+     * Word-wrap long lines within the box.
+     * Only applies when `box` is `true`. Default: `false`.
+     */
+    wordWrap?: boolean;
+}
+/**
+ * Single configurable log formatter.
+ *
+ * Covers all output styles through constructor options:
+ *
+ * | Equivalent old class        | Options                                          |
+ * |-----------------------------|--------------------------------------------------|
+ * | `ColoredLogFormatter`       | `{ box: false }`                                 |
+ * | `ShortFixedBoxFormatter`    | `{ box: true, width: N }`                        |
+ * | `ShortDynamicBoxFormatter`  | `{ box: true, fullBorder: true, width: "auto" }` |
+ * | `LongBoxedFormatter`        | `{ box: true, wordWrap: true, width: N }`        |
+ *
+ * @example
+ * ```ts
+ * // Colored, no box (default style)
+ * new LogFormatter({ datefmt, logColors, colored: true });
+ *
+ * // Full border, auto width
+ * new LogFormatter({ datefmt, logColors, colored: true, box: true, fullBorder: true, width: "auto" });
+ *
+ * // Word-wrapped box with JSON extras
+ * new LogFormatter({ datefmt, logColors, colored: true, box: true, wordWrap: true, width: 100, extraFormat: "json" });
+ * ```
+ */
+declare class LogFormatter implements Formatter {
+    private opts;
+    constructor(opts: FormatterOptions);
+    format(record: LogRecord): string;
+}
+
+/**
+ * Custom log handlers for crisplogs.
+ *
+ * Provides handlers that produce clean output for both console and file destinations.
+ */
+
+/**
+ * Console handler that writes formatted log records to stdout.
+ */
+declare class ConsoleHandler implements Handler {
+    readonly level: number;
+    formatter: Formatter;
+    constructor(level: number, formatter: Formatter);
+    emit(record: LogRecord): void;
+    close(): void;
+}
+/**
+ * File handler that strips ANSI color codes before writing.
+ *
+ * Logs written to files should be plain text for readability in editors,
+ * log aggregators, and CI systems. This handler removes all ANSI escape
+ * sequences before writing each record.
+ *
+ * @example
+ * ```ts
+ * const handler = new CleanFileHandler("app.log", LEVEL_VALUES.WARNING, formatter);
+ * ```
+ */
+declare class CleanFileHandler implements Handler {
+    readonly level: number;
+    formatter: Formatter;
+    private stream;
+    constructor(filename: string, level: number, formatter: Formatter);
+    emit(record: LogRecord): void;
+    close(): void;
+}
+
+/**
+ * Internal utilities for crisplogs.
+ */
+/**
+ * Remove all ANSI escape sequences from a string.
+ *
+ * @example
+ * stripAnsi("\x1b[32mHello\x1b[0m") // "Hello"
+ */
+declare function stripAnsi(text: string): string;
+
+/** Default color scheme applied to each log level. */
+declare const DEFAULT_LOG_COLORS: Record<Level, string>;
+
+/**
+ * crisplogs - Beautiful, colored, and boxed logging for Node.js.
+ *
+ * @example
+ * ```ts
+ * import { setupLogging } from "crisplogs";
+ *
+ * const logger = setupLogging();
+ * logger.info("Hello from crisplogs!");
+ * ```
+ *
+ * @example
+ * ```ts
+ * const logger = setupLogging({ style: "long-boxed", file: "app.log" });
+ * logger.warning("Disk usage high", { usage: "85%" });
+ * ```
+ */
+
+declare const VERSION: string;
+/**
+ * Configure logging with colors and optional box formatting in one call.
+ *
+ * This is the main entry point for crisplogs. Call it once at application
+ * startup to configure the root (or named) logger.
+ *
+ * @returns The configured {@link Logger} instance.
+ */
+declare function setupLogging(options?: SetupLoggingOptions): Logger;
+/**
+ * Tear down all loggers, closing their handlers and clearing the registry.
+ * Useful in tests or when reconfiguring logging at runtime.
+ */
+declare function resetLogging(): void;
+/**
+ * Remove a single logger from the registry by name.
+ * Returns `true` if the logger existed and was removed.
+ */
+declare function removeLogger(name: string): boolean;
+/**
+ * Retrieve a previously configured logger by name, or create one
+ * that inherits the root logger's handlers.
+ *
+ * @example
+ * ```ts
+ * setupLogging();                       // configure root
+ * const logger = getLogger("myapp");    // inherits root handlers
+ * logger.info("works");
+ * ```
+ */
+declare function getLogger(name?: string): Logger;
+
+export { CleanFileHandler, ConsoleHandler, DEFAULT_LOG_COLORS, type ExtraFormat, type Formatter, type FormatterOptions, type Handler, LEVEL_VALUES, type Level, LogFormatter, type LogRecord, Logger, type SetupLoggingOptions, type Style, VERSION, getLogger, removeLogger, resetLogging, setupLogging, stripAnsi };