@mxweb/core 1.0.0

package/dist/logger.d.ts

@@ -0,0 +1,360 @@
+/**
+ * @fileoverview Colorful logging utility for development and debugging.
+ *
+ * This module provides a Logger class with ANSI color support for server-side
+ * console output. Logging is automatically disabled in production environment
+ * or when DEBUG=false.
+ *
+ * Features:
+ * - Color-coded log levels (warn, log, error, info, debug)
+ * - HTTP request logging with status code coloring
+ * - Timestamp logging
+ * - JSON pretty-printing
+ * - Console grouping and table output
+ * - Time measurement utilities
+ *
+ * @module logger
+ *
+ * @example
+ * ```ts
+ * import { logger, Logger } from "@mxweb/core";
+ *
+ * // Use the default singleton instance
+ * logger.info("Application started");
+ * logger.error("Something went wrong", error);
+ *
+ * // Create a custom logger with prefix
+ * const myLogger = Logger.create("MyModule");
+ * myLogger.debug("Debug message");
+ * ```
+ */
+/**
+ * Available log levels for the Logger.
+ * Each level corresponds to a console method and has an associated color.
+ */
+type LogLevel = "warn" | "log" | "error" | "info" | "debug";
+/**
+ * A colorful, feature-rich logging utility for server-side development.
+ *
+ * The Logger class provides structured logging with ANSI color support,
+ * automatic environment-based filtering, and various output formats.
+ *
+ * Logging is enabled when:
+ * - NODE_ENV !== "production" AND
+ * - DEBUG !== "false"
+ *
+ * @remarks
+ * Use the singleton `logger` export for most cases.
+ * Create custom instances with `Logger.create()` for module-specific prefixes.
+ *
+ * @example
+ * ```ts
+ * // Singleton usage
+ * import { logger } from "@mxweb/core";
+ *
+ * logger.info("Server starting...");
+ * logger.warn("Deprecated API used");
+ * logger.error("Failed to connect", error);
+ * logger.debug("Variable value:", someVar);
+ *
+ * // HTTP logging
+ * logger.http("GET", "/api/users", 200, 1024, 50);
+ *
+ * // Timing
+ * logger.time("database-query");
+ * await queryDatabase();
+ * logger.timeEnd("database-query");
+ *
+ * // JSON output
+ * logger.json("info", "User data", { id: 1, name: "John" });
+ * ```
+ */
+export declare class Logger {
+    /** Singleton instance for the default logger */
+    private static _instance;
+    /** The prefix shown in log messages (e.g., "[MyModule]") */
+    private readonly prefix;
+    /** Whether logging is enabled based on environment */
+    private readonly allowLog;
+    /**
+     * Private constructor to enforce singleton pattern for default instance.
+     * Use `Logger.instance` or `Logger.create()` to get logger instances.
+     *
+     * @param prefix - The prefix to show in log messages
+     */
+    private constructor();
+    /**
+     * Gets the singleton Logger instance with the default "@mxweb" prefix.
+     *
+     * @returns The singleton Logger instance
+     *
+     * @example
+     * ```ts
+     * const log = Logger.instance;
+     * log.info("Using singleton logger");
+     * ```
+     */
+    static get instance(): Logger;
+    /**
+     * Creates a new Logger instance with a custom prefix.
+     *
+     * @param prefix - The prefix to show in log messages
+     * @returns A new Logger instance
+     *
+     * @example
+     * ```ts
+     * const dbLogger = Logger.create("Database");
+     * dbLogger.info("Connected"); // Output: [Database] Connected
+     *
+     * const authLogger = Logger.create("Auth");
+     * authLogger.warn("Token expired"); // Output: [Auth] Token expired
+     * ```
+     */
+    static create(prefix: string): Logger;
+    /**
+     * Checks if logging is allowed in the current environment.
+     *
+     * @returns true if logging is enabled
+     * @internal
+     */
+    private isAllowLog;
+    /**
+     * Formats the prefix with the appropriate ANSI color for the log level.
+     *
+     * @param level - The log level to get color for
+     * @returns The formatted prefix string with color codes
+     * @internal
+     */
+    private formatPrefix;
+    /**
+     * Internal method that performs the actual console output.
+     *
+     * @param level - The log level for coloring
+     * @param method - The console method to use
+     * @param message - The primary message to log
+     * @param optionalParams - Additional parameters to log
+     * @internal
+     */
+    private output;
+    /**
+     * Logs a warning message in yellow.
+     *
+     * @param message - The warning message
+     * @param optionalParams - Additional parameters to log
+     *
+     * @example
+     * ```ts
+     * logger.warn("Deprecated API used");
+     * logger.warn("Rate limit approaching:", { current: 95, limit: 100 });
+     * ```
+     */
+    warn(message?: any, ...optionalParams: any[]): void;
+    /**
+     * Logs a general message in cyan.
+     *
+     * @param message - The message to log
+     * @param optionalParams - Additional parameters to log
+     *
+     * @example
+     * ```ts
+     * logger.log("Processing request...");
+     * logger.log("Items:", items.length);
+     * ```
+     */
+    log(message?: any, ...optionalParams: any[]): void;
+    /**
+     * Logs an error message in red.
+     *
+     * @param message - The error message
+     * @param optionalParams - Additional parameters (often an Error object)
+     *
+     * @example
+     * ```ts
+     * logger.error("Failed to connect to database");
+     * logger.error("Unhandled exception:", error);
+     * ```
+     */
+    error(message?: any, ...optionalParams: any[]): void;
+    /**
+     * Logs an informational message in green.
+     *
+     * @param message - The info message
+     * @param optionalParams - Additional parameters to log
+     *
+     * @example
+     * ```ts
+     * logger.info("Server started on port 3000");
+     * logger.info("User logged in:", userId);
+     * ```
+     */
+    info(message?: any, ...optionalParams: any[]): void;
+    /**
+     * Logs a debug message in blue.
+     * Useful for development-only detailed logging.
+     *
+     * @param message - The debug message
+     * @param optionalParams - Additional parameters to log
+     *
+     * @example
+     * ```ts
+     * logger.debug("Variable state:", { x: 1, y: 2 });
+     * logger.debug("Entering function processData");
+     * ```
+     */
+    debug(message?: any, ...optionalParams: any[]): void;
+    /**
+     * Logs an HTTP request with color-coded status.
+     *
+     * Status code colors:
+     * - 5xx: Red (server error)
+     * - 4xx: Yellow (client error)
+     * - 3xx: Cyan (redirect)
+     * - 2xx: Green (success)
+     *
+     * @param method - The HTTP method (GET, POST, etc.)
+     * @param path - The request path
+     * @param statusCode - The HTTP response status code
+     * @param responseSize - The response body size in bytes
+     * @param duration - The request duration in milliseconds
+     *
+     * @example
+     * ```ts
+     * logger.http("GET", "/api/users", 200, 1024, 50);
+     * // Output: [mxweb] GET /api/users 200 - 1024 bytes in 50ms
+     *
+     * logger.http("POST", "/api/login", 401, 128, 25);
+     * // Output: [mxweb] POST /api/login 401 - 128 bytes in 25ms (yellow status)
+     * ```
+     */
+    http(method: string, path: string, statusCode: number, responseSize: number, duration: number): void;
+    /**
+     * Logs a message with an ISO timestamp prefix.
+     *
+     * @param level - The log level to use
+     * @param message - The message to log
+     * @param optionalParams - Additional parameters to log
+     *
+     * @example
+     * ```ts
+     * logger.timestamp("info", "Server started");
+     * // Output: [mxweb] [2024-01-15T10:30:00.000Z] Server started
+     * ```
+     */
+    timestamp(level: LogLevel, message?: any, ...optionalParams: any[]): void;
+    /**
+     * Logs an object as pretty-printed JSON.
+     *
+     * @param level - The log level to use
+     * @param label - A label to identify the data
+     * @param data - The data to stringify and log
+     *
+     * @example
+     * ```ts
+     * logger.json("debug", "User object", { id: 1, name: "John", roles: ["admin"] });
+     * // Output:
+     * // [mxweb] User object:
+     * // {
+     * //   "id": 1,
+     * //   "name": "John",
+     * //   "roles": ["admin"]
+     * // }
+     * ```
+     */
+    json(level: LogLevel, label: string, data: unknown): void;
+    /**
+     * Logs a visual separator line.
+     * Useful for separating log sections.
+     *
+     * @param char - The character to repeat (default: "-")
+     * @param length - The number of repetitions (default: 50)
+     *
+     * @example
+     * ```ts
+     * logger.separator();
+     * // Output: --------------------------------------------------
+     *
+     * logger.separator("=", 30);
+     * // Output: ==============================
+     * ```
+     */
+    separator(char?: string, length?: number): void;
+    /**
+     * Logs messages in a collapsible group.
+     *
+     * @param label - The group label
+     * @param fn - Function containing log statements to group
+     *
+     * @example
+     * ```ts
+     * logger.group("Request Details", () => {
+     *   logger.info("Method: GET");
+     *   logger.info("Path: /api/users");
+     *   logger.info("Headers:", headers);
+     * });
+     * ```
+     */
+    group(label: string, fn: () => void): void;
+    /**
+     * Logs data in a tabular format.
+     *
+     * @param data - Array of objects to display as a table
+     * @param columns - Optional array of column names to include
+     *
+     * @example
+     * ```ts
+     * logger.table([
+     *   { id: 1, name: "Alice", role: "admin" },
+     *   { id: 2, name: "Bob", role: "user" },
+     * ]);
+     *
+     * logger.table(users, ["name", "email"]);
+     * ```
+     */
+    table(data: any[], columns?: string[]): void;
+    /**
+     * Starts a timer with the given label.
+     * Use with `timeEnd()` to measure elapsed time.
+     *
+     * @param label - The timer label (must match in timeEnd)
+     *
+     * @example
+     * ```ts
+     * logger.time("database-query");
+     * const result = await db.query("SELECT * FROM users");
+     * logger.timeEnd("database-query");
+     * // Output: [mxweb] database-query: 45.123ms
+     * ```
+     */
+    time(label: string): void;
+    /**
+     * Stops a timer and logs the elapsed time.
+     *
+     * @param label - The timer label (must match the one used in time())
+     *
+     * @example
+     * ```ts
+     * logger.time("operation");
+     * await someOperation();
+     * logger.timeEnd("operation");
+     * // Output: [mxweb] operation: 123.456ms
+     * ```
+     */
+    timeEnd(label: string): void;
+}
+/**
+ * The default singleton Logger instance.
+ *
+ * This is the recommended way to use the logger for most cases.
+ * The singleton uses "@mxweb" as the default prefix.
+ *
+ * @example
+ * ```ts
+ * import { logger } from "@mxweb/core";
+ *
+ * logger.info("Application initialized");
+ * logger.warn("Configuration missing, using defaults");
+ * logger.error("Failed to start:", error);
+ * ```
+ */
+export declare const logger: Logger;
+export {};

package/dist/logger.js

@@ -0,0 +1 @@
+"use strict";var t=require("@mxweb/utils");const o={warn:"",log:"",error:"",info:"",debug:"",reset:""};class r{constructor(o="@mxweb"){this.prefix=o,this.allowLog="production"!==t.getEnv("NODE_ENV")&&"false"!==t.getEnv("DEBUG")}static get instance(){return r._instance||(r._instance=new r),r._instance}static create(t){return new r(t)}isAllowLog(){return this.allowLog}formatPrefix(t){return`${o[t]}[${this.prefix}]${o.reset}`}output(t,o,r,...i){if(!this.isAllowLog())return;this.formatPrefix(t)}warn(t,...o){this.output("warn","warn",t,...o)}log(t,...o){this.output("log","log",t,...o)}error(t,...o){this.output("error","error",t,...o)}info(t,...o){this.output("info","info",t,...o)}debug(t,...o){this.output("debug","debug",t,...o)}http(t,r,i,e,s){const n=`${t} ${r} ${i>=500?o.error:i>=400?o.warn:i>=300?o.log:o.info}${i}${o.reset} - ${e} bytes in ${s}ms`;this.output("info","info",n)}timestamp(t,o,...r){if(!this.isAllowLog())return;(new Date).toISOString(),this.formatPrefix(t)}json(t,o,r){if(!this.isAllowLog())return;this.formatPrefix(t)}separator(t="-",o=50){this.isAllowLog()}group(t,o){if(!this.isAllowLog())return;this.formatPrefix("info");o()}table(t,o){this.isAllowLog()}time(t){this.isAllowLog()}timeEnd(t){this.isAllowLog()}}const i=r.instance;exports.Logger=r,exports.logger=i;

package/dist/logger.mjs

@@ -0,0 +1 @@
+import{getEnv as t}from"@mxweb/utils";const o={warn:"",log:"",error:"",info:"",debug:"",reset:""};class i{constructor(o="@mxweb"){this.prefix=o,this.allowLog="production"!==t("NODE_ENV")&&"false"!==t("DEBUG")}static get instance(){return i._instance||(i._instance=new i),i._instance}static create(t){return new i(t)}isAllowLog(){return this.allowLog}formatPrefix(t){return`${o[t]}[${this.prefix}]${o.reset}`}output(t,o,i,...r){if(!this.isAllowLog())return;this.formatPrefix(t)}warn(t,...o){this.output("warn","warn",t,...o)}log(t,...o){this.output("log","log",t,...o)}error(t,...o){this.output("error","error",t,...o)}info(t,...o){this.output("info","info",t,...o)}debug(t,...o){this.output("debug","debug",t,...o)}http(t,i,r,s,e){const n=`${t} ${i} ${r>=500?o.error:r>=400?o.warn:r>=300?o.log:o.info}${r}${o.reset} - ${s} bytes in ${e}ms`;this.output("info","info",n)}timestamp(t,o,...i){if(!this.isAllowLog())return;(new Date).toISOString(),this.formatPrefix(t)}json(t,o,i){if(!this.isAllowLog())return;this.formatPrefix(t)}separator(t="-",o=50){this.isAllowLog()}group(t,o){if(!this.isAllowLog())return;this.formatPrefix("info");o()}table(t,o){this.isAllowLog()}time(t){this.isAllowLog()}timeEnd(t){this.isAllowLog()}}const r=i.instance;export{i as Logger,r as logger};