crisplogs 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 crisplogs contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,333 @@
+# crisplogs
+
+Beautiful, colored, and boxed logging for Node.js. One function call to set up production-ready logs with colors, box decorations, and file output.
+
+**Zero runtime dependencies.** Works with Node.js 16+. Ships with full TypeScript types.
+
+## Installation
+
+```bash
+npm install crisplogs
+```
+
+## Quickstart
+
+```ts
+import { setupLogging } from "crisplogs";
+
+const logger = setupLogging();
+
+logger.debug("This is a debug message");
+logger.info("Server started successfully");
+logger.warning("Disk usage at 85%");
+logger.error("Failed to connect to database");
+logger.critical("System is shutting down");
+```
+
+## Styles
+
+### Colored (default)
+
+Plain colored output. Each log level gets its own color for easy scanning.
+
+```ts
+const logger = setupLogging({ colored: true });
+```
+
+```
+INFO     2025-09-08 12:30:45 [root] /app/main.ts:25 - Server started
+ERROR    2025-09-08 12:31:12 [root] /app/db.ts:45 - Connection failed
+```
+
+### Short Fixed Box
+
+Fixed-width box with left border only. Good for short messages.
+
+```ts
+const logger = setupLogging({ style: "short-fixed" });
+```
+
+```
+┌──────────────────────────────────────────────────────────────────────────────────
+│ INFO     2025-09-08 12:30:45 [root] /app/main.ts:25 - Server started
+└──────────────────────────────────────────────────────────────────────────────────
+```
+
+### Short Dynamic Box
+
+Dynamic-width box with full border. Width adjusts to fit the message.
+
+```ts
+const logger = setupLogging({ style: "short-dynamic" });
+```
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│ INFO     2025-09-08 12:30:45 [root] - Server started         │
+└──────────────────────────────────────────────────────────────┘
+```
+
+### Long Boxed
+
+Word-wrapped box with left border. Best for long messages and extra fields.
+
+```ts
+const logger = setupLogging({ style: "long-boxed" });
+```
+
+```
+┌──────────────────────────────────────────────────────────────────────────────────
+│ INFO     2025-09-08 12:34:56 [root] - This is a long message that wraps neatly
+│ across multiple lines without breaking words in half. [user_id=42 action=login]
+└──────────────────────────────────────────────────────────────────────────────────
+```
+
+To pass extra fields:
+
+```ts
+logger.info("User logged in", { userId: 42, action: "login" });
+```
+
+## API Reference
+
+### `setupLogging(options?)`
+
+Configure logging with colors and optional box formatting in one call. Returns a `Logger` instance.
+
+```ts
+const logger = setupLogging({
+  colored: true,
+  style: "long-boxed",
+  level: "DEBUG",
+  width: 100,
+  datefmt: "%Y-%m-%d %H:%M:%S",
+  logColors: { INFO: "bold_green" },
+  extraFormat: "json",
+  file: "app.log",
+  fileLevel: "WARNING",
+  name: "myapp",
+});
+```
+
+### `getLogger(name?)`
+
+Retrieve a previously configured logger by name. If no logger exists for that name, one is created inheriting the root logger's handlers.
+
+```ts
+setupLogging(); // configure root logger
+const logger = getLogger("myapp"); // inherits root config
+logger.info("works");
+```
+
+### Logger Methods
+
+```ts
+logger.debug(message, extra?)
+logger.info(message, extra?)
+logger.warning(message, extra?)
+logger.warn(message, extra?)      // alias for warning
+logger.error(message, extra?)
+logger.critical(message, extra?)
+logger.log(level, message, extra?) // explicit level
+```
+
+The `extra` parameter is an optional `Record<string, unknown>`. It appears in the log output for the default (no style) and `"long-boxed"` styles. Format is controlled by the `extraFormat` option.
+
+## Options
+
+### `colored` (boolean, default: `true`)
+
+Enable or disable colored console output. Set to `false` for CI, piped output, or plain terminals.
+
+```ts
+setupLogging({ colored: false });
+```
+
+### `style` (string or null, default: `null`)
+
+Box style. One of `"short-fixed"`, `"short-dynamic"`, `"long-boxed"`, or `null` for no box.
+
+You can combine `colored` and `style` independently:
+
+```ts
+setupLogging({ colored: true, style: "long-boxed" });  // colored + boxed
+setupLogging({ colored: false, style: "short-fixed" }); // plain + boxed
+setupLogging({ colored: true, style: null });            // colored, no box
+setupLogging({ colored: false, style: null });           // plain, no box
+```
+
+### `level` (string, default: `"DEBUG"`)
+
+Minimum log level for console output. One of `"DEBUG"`, `"INFO"`, `"WARNING"`, `"ERROR"`, `"CRITICAL"`.
+
+```ts
+setupLogging({ level: "INFO" }); // hides DEBUG messages on console
+```
+
+### `width` (number, default: `100`)
+
+Box width in characters. Only applies to `"short-fixed"` and `"long-boxed"` styles.
+
+```ts
+setupLogging({ style: "long-boxed", width: 120 });
+```
+
+### `datefmt` (string, default: `"%Y-%m-%d %H:%M:%S"`)
+
+Date/time format using Python-compatible `strftime` tokens.
+
+Supported tokens: `%Y`, `%m`, `%d`, `%H`, `%M`, `%S`, `%I`, `%p`, `%f`, `%j`, `%a`, `%A`, `%b`, `%B`, `%%`.
+
+```ts
+setupLogging({ datefmt: "%H:%M:%S" });       // short: 12:30:45
+setupLogging({ datefmt: "%d/%m/%Y %H:%M" }); // European: 08/09/2025 12:30
+```
+
+### `logColors` (object, default: built-in scheme)
+
+Override colors for specific log levels. Uses color strings compatible with Python's `colorlog`:
+
+| Color | Example |
+|-------|---------|
+| Basic | `"red"`, `"green"`, `"cyan"`, `"yellow"`, `"blue"`, `"white"`, `"black"` |
+| Bold | `"bold_red"`, `"bold_green"` |
+| Dim | `"thin_white"`, `"dim_white"` |
+| Background | `"bg_red"`, `"bg_white"` |
+| Combined | `"bold_red,bg_white"` |
+
+```ts
+setupLogging({
+  logColors: {
+    DEBUG: "thin_white",
+    INFO: "bold_green",
+    WARNING: "bold_yellow",
+    ERROR: "bold_red,bg_white",
+    CRITICAL: "bold_white,bg_red",
+  },
+});
+```
+
+Default color scheme:
+
+| Level | Color |
+|-------|-------|
+| DEBUG | `cyan` |
+| INFO | `green` |
+| WARNING | `yellow` |
+| ERROR | `red` |
+| CRITICAL | `bold_red` |
+
+### `file` (string or null, default: `null`)
+
+Path to a log file. ANSI color codes are automatically stripped so the file stays clean and readable.
+
+```ts
+setupLogging({ file: "logs/app.log" });
+```
+
+### `fileLevel` (string or null, default: same as `level`)
+
+Separate minimum level for the file handler. Useful when you want verbose console output but only important messages in the file.
+
+```ts
+setupLogging({ level: "DEBUG", file: "app.log", fileLevel: "WARNING" });
+// Console shows everything, file only gets WARNING and above.
+```
+
+### `name` (string, default: `""`)
+
+Logger name. Empty string configures the root logger (affects all loggers retrieved via `getLogger`). Pass a name for a specific logger.
+
+```ts
+const logger = setupLogging({ name: "myapp" });
+logger.info("from myapp"); // shows [myapp] in output
+```
+
+### `extraFormat` (string, default: `"inline"`)
+
+How `extra` fields are rendered in the log output. Only applies to the default (no style) and `"long-boxed"` outputs.
+
+| Value | Output |
+|-------|--------|
+| `"inline"` | `[userId=42 action=login]` |
+| `"json"` | `{"userId":42,"action":"login"}` |
+| `"pretty"` | Formatted multi-line JSON |
+
+```ts
+setupLogging({ extraFormat: "json" });
+// INFO     2025-09-08 12:30:45 [root] app.ts:10 - User logged in {"userId":42}
+
+setupLogging({ style: "long-boxed", extraFormat: "pretty" });
+// ┌──────────────────────────────────────
+// │ INFO ... - User logged in
+// │ {
+// │   "userId": 42
+// │ }
+// └──────────────────────────────────────
+```
+
+## Full Example
+
+```ts
+import { setupLogging } from "crisplogs";
+
+// Colored + boxed console, warnings+ to file
+const logger = setupLogging({
+  colored: true,
+  style: "long-boxed",
+  level: "DEBUG",
+  width: 110,
+  datefmt: "%H:%M:%S",
+  file: "app.log",
+  fileLevel: "WARNING",
+});
+
+logger.debug("Loading configuration...");
+logger.info("Server started on port 8000");
+logger.warning("Cache miss rate is high", { rate: "45%" });
+logger.error("Payment processing failed", { orderId: 9912 });
+```
+
+## CommonJS Usage
+
+```js
+const { setupLogging } = require("crisplogs");
+
+const logger = setupLogging();
+logger.info("Hello from CommonJS!");
+```
+
+## Exported Types
+
+All types are available for TypeScript users:
+
+```ts
+import type {
+  Style,           // "short-fixed" | "short-dynamic" | "long-boxed"
+  Level,           // "DEBUG" | "INFO" | "WARNING" | "ERROR" | "CRITICAL"
+  ExtraFormat,     // "inline" | "json" | "pretty"
+  SetupLoggingOptions,
+  LogRecord,
+  Formatter,
+  Handler,
+} from "crisplogs";
+```
+
+## Exports
+
+| Export | Description |
+|--------|-------------|
+| `setupLogging` | Main entry point - configure logging in one call |
+| `getLogger` | Retrieve a logger by name |
+| `Logger` | Logger class |
+| `LogFormatter` | Configurable formatter — covers all styles via options |
+| `ConsoleHandler` | Stdout handler |
+| `CleanFileHandler` | File handler with ANSI stripping |
+| `stripAnsi` | Remove ANSI escape sequences from a string |
+| `DEFAULT_LOG_COLORS` | Default color scheme |
+| `LEVEL_VALUES` | Numeric values for each log level |
+| `VERSION` | Package version string |
+
+## License
+
+MIT

package/dist/index.d.mts

@@ -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 };