logxpert 1.0.4-0 → 2.0.0

package/README.md

@@ -1,113 +1,97 @@
-# LogXpert
-
-LogXpert is a powerful logging library for Node.js that provides easy-to-use logging methods with colorful formatted output and optional file logging support
-
-## Table of Contents
-- [Installation](#installation)
-- [Usage](#usage)
-  - [Basic Logging](#basic-logging)
-  - [Advanced Logging: File Output & Custom Console Timestamp](#advanced-logging-file-output--custom-console-timestamp)
-- [API Reference](#api-reference)
-- [Additional Information](#additional-information)
-- [License](#license)
-
-## Installation
-
-You can install LogXpert using npm:
-
-```sh
-npm install logxpert
-```
-
-## Usage
-
-### Basic Logging
-
-Import LogXpert in your project and use it to log messages:
-
-```js
-const log = require('logxpert');
-
-// Log a general message
-log('This is a general log message.');
-
-// Log an error message
-log.error('This is an error message.');
-
-// Log a warning message
-log.warn('This is a warning message.');
-
-// Log an informational message
-log.info('This is an informational message.');
-
-// Log a debug message
-log.debug('This is a debug message.');
-```
-
-### Advanced Logging: File Output & Custom Console Timestamp
-
-LogXpert supports file logging using [winston](https://github.com/winstonjs/winston) and [winston-daily-rotate-file](https://github.com/winstonjs/winston-daily-rotate-file).
-
-Example configuration:
-
-```js
-const log = require('logxpert');
-
-log.settings({ 
-    console: { 
-        enableTimestamp: true,
-        // You can now include decoration characters as desired:
-        timestampFormat: "This is the date: [YYYY-MM-DD HH:mm:ss] - ",
-        timestampPrefix: '',
-        timestampSuffix: ''
-    },
-    files: { 
-        folder: 'logs', 
-        filesName: 'YYYY-MM-DD', 
-        maxFile: '14d', 
-        maxSize: '20m', 
-        zippedArchive: false
-    }
-});
-```
-
-## API Reference
-
-- **log(message: string):**  
-  Logs a general message using the `info` level.
-
-- **log.error(message: string):**  
-  Logs an error message.
-
-- **log.warn(message: string):**  
-  Logs a warning message.
-
-- **log.info(message: string):**  
-  Logs an informational message.
-
-- **log.debug(message: string):**  
-  Logs a debug message.
-
-- **log.settings(options: object):**  
-  Configures file logging and console output options.  
-  **Console Options:**
-  - `enableTimestamp` (boolean): Enable/disable timestamp (default: `true`).
-  - `timestampFormat` (string): Format for the timestamp including any desired literal text or decoration (default: `'YYYY-MM-DD HH:mm:ss'`).
-  - `timestampPrefix` (string): Prefix for the timestamp.
-  - `timestampSuffix` (string): Suffix for the timestamp.
-  
-  **Files Options:**
-  - `folder` (string): Directory where log files will be stored (default: `'logs'`).
-  - `filesName` (string): Date pattern for the log file name (default: `'YYYY-MM-DD'`).
-  - `maxFile` (string): Maximum file retention (default: `'14d'`).
-  - `maxSize` (string): Maximum size per log file (default: `'20m'`).
-  - `zippedArchive` (boolean): Archive logs in zip format (default: `false`).
-
-## Additional Information
-
-- [French Version](./README.fr.md)
-- [Patch Notes](./PATCHNOTE.md)
-
-## License
-
-This project is licensed under the MIT License.
+# LogXpert
+
+LogXpert is a powerful logging library for Node.js that provides easy-to-use logging methods with colorful formatted output and optional file logging support.
+
+## Installation
+
+```sh
+npm install logxpert
+```
+
+## Usage
+
+CommonJS:
+
+```js
+const log = require('logxpert');
+
+log('general message');
+log.error('error message');
+log.warn('warn message');
+log.info('info with meta', { user: 1 });
+log.debug({ structured: 'object' });
+log.error(new Error('boom'));
+```
+
+ESM:
+
+```js
+import log from 'logxpert';
+
+log.info('hello');
+```
+
+Set level (`LOG_LEVEL` env also respected):
+
+```js
+log.setLevel('info');
+console.log(log.getLevel());
+```
+
+Isolated instances and child loggers:
+
+```js
+const { createLogger } = require('logxpert');
+const apiLog = createLogger({ level: 'info' });
+apiLog.info('isolated');
+
+const child = log.child({ service: 'api' });
+child.info('child message');
+```
+
+### File output & console timestamp
+
+```js
+log.settings({
+  level: 'debug',
+  console: {
+    enableTimestamp: true,
+    timestampFormat: 'YYYY-MM-DD HH:mm:ss',
+    timestampPrefix: '',
+    timestampSuffix: '',
+    colorize: true
+  },
+  files: {
+    folder: 'logs',
+    filename: 'application-%DATE%.log',
+    filesName: 'YYYY-MM-DD',
+    maxFile: '14d',
+    maxSize: '20m',
+    zippedArchive: false
+  }
+});
+```
+
+Close file transports on shutdown:
+
+```js
+log.close();
+```
+
+## API Reference
+
+- **log(message, ...meta):** info level.
+- **log.error/warn/info/debug/http/verbose/silly(message, ...meta)**
+- **log.log(level, message, ...meta)**
+- **log.settings({ console, files, level })**
+- **log.setLevel(level) / log.getLevel()**
+- **log.createLogger(options):** independent instance.
+- **log.child(meta):** child logger with bound context.
+- **log.close():** remove file transport.
+
+Console options: `enableTimestamp`, `timestampFormat`, `timestampPrefix`, `timestampSuffix`, `colorize`, `level`.
+Files options: `folder`, `filename`, `filesName`/`datePattern`, `maxFile`/`maxFiles`, `maxSize`, `zippedArchive`, `level`.
+
+## License
+
+GPL-3.0-only. See [LICENSE](LICENSE).

package/index.d.ts

@@ -0,0 +1,57 @@
+export type LogLevel = 'error' | 'warn' | 'info' | 'http' | 'verbose' | 'debug' | 'silly';
+
+export interface ConsoleOptions {
+  enableTimestamp?: boolean;
+  timestampFormat?: string;
+  timestampPrefix?: string;
+  timestampSuffix?: string;
+  colorize?: boolean;
+  level?: LogLevel;
+}
+
+export interface FilesOptions {
+  folder?: string;
+  filesName?: string;
+  datePattern?: string;
+  filename?: string;
+  maxFile?: string;
+  maxFiles?: string;
+  maxSize?: string;
+  zippedArchive?: boolean;
+  level?: LogLevel;
+}
+
+export interface LogSettingsOptions {
+  console?: ConsoleOptions;
+  files?: FilesOptions;
+  level?: LogLevel;
+}
+
+export interface ChildLogger {
+  error(message: unknown, ...meta: unknown[]): void;
+  warn(message: unknown, ...meta: unknown[]): void;
+  info(message: unknown, ...meta: unknown[]): void;
+  debug(message: unknown, ...meta: unknown[]): void;
+  log(level: LogLevel, message: unknown, ...meta: unknown[]): void;
+}
+
+export interface LogXpert {
+  (message: unknown, ...meta: unknown[]): void;
+  error(message: unknown, ...meta: unknown[]): void;
+  warn(message: unknown, ...meta: unknown[]): void;
+  info(message: unknown, ...meta: unknown[]): void;
+  debug(message: unknown, ...meta: unknown[]): void;
+  http(message: unknown, ...meta: unknown[]): void;
+  verbose(message: unknown, ...meta: unknown[]): void;
+  silly(message: unknown, ...meta: unknown[]): void;
+  log(level: LogLevel, message: unknown, ...meta: unknown[]): void;
+  settings(options?: LogSettingsOptions): void;
+  setLevel(level: LogLevel): void;
+  getLevel(): string;
+  child(meta?: Record<string, unknown>): ChildLogger;
+  close(): void;
+  createLogger(options?: LogSettingsOptions): LogXpert;
+}
+
+declare const log: LogXpert;
+export default log;

package/main.js

@@ -1,185 +1,188 @@
-const fs = require('fs');
-const moment = require('moment'); // Add moment as a dependency: npm install moment
-const { createLogger, format, transports } = require('winston');
-require('winston-daily-rotate-file');
-
-/**
- * Helper function to format the timestamp while preserving square brackets.
- * It replaces "[" with "%%LB%%" and "]" with "%%RB%%" to prevent Moment.js from
- * treating the contents as literal text. After formatting, the placeholders are restored.
- *
- * @param {string} fmt - The user-defined format string.
- * @returns {string} - The formatted timestamp with square brackets preserved.
- *
- * Example:
- *   Input: "This is the date: [YYYY-MM-DD HH:mm:ss] - "
- *   Might output: "This is the date: [2025-03-21 15:30:45] - "
- */
-function formatCustomTimestamp(fmt) {
-    // Replace square brackets with temporary placeholders that won't interfere with Moment.js formatting
-    const temp = fmt.replace(/\[/g, '%%LB%%').replace(/\]/g, '%%RB%%');
-    // Format the timestamp using Moment.js
-    const formatted = moment().format(temp);
-    // Replace the placeholders back with the square brackets
-    return formatted.replace(/%%LB%%/g, '[').replace(/%%RB%%/g, ']');
-}
-
-
-/**
- * @typedef {Object} ConsoleOptions
- * @property {boolean} [enableTimestamp=true] - Enable or disable timestamp in console logs.
- * @property {string} [timestampFormat='YYYY-MM-DD HH:mm:ss'] - Custom format for the timestamp.
- *   You can include any decoration characters ([], (), {}) without interference.
- *   For example:
- *     - "This is the date: [YYYY-MM-DD HH:mm:ss] - "
- *     - "date: YYYY-MM-DD heure: HH:mm:ss - "
- */
-
-/**
- * @typedef {Object} FilesOptions
- * @property {string} [folder='logs'] - Directory where log files will be stored.
- * @property {string} [filesName='YYYY-MM-DD'] - Date pattern used in the log file name.
- * @property {string} [maxFile='14d'] - Maximum file retention time.
- * @property {string} [maxSize='20m'] - Maximum file size per log file.
- * @property {boolean} [zippedArchive=false] - Whether to archive logs as zip.
- */
-
-/**
- * @typedef {Object} LogSettingsOptions
- * @property {ConsoleOptions} [console] - Options for customizing console output.
- * @property {FilesOptions} [files] - Options for configuring file logging.
- */
-
-// Custom format for logger output
-const customFormat = format.printf(({ timestamp, level, message }) => {
-    return timestamp ? `${timestamp} [${level}]: ${message}` : `[${level}]: ${message}`;
-});
-
-// Default console timestamp format
-const defaultConsoleFormat = 'YYYY-MM-DD HH:mm:ss';
-
-// Create the global logger. Its default format will be overridden by the console transport settings.
-const logger = createLogger({
-    level: 'debug',
-    format: format.combine(
-        format.timestamp({ format: () => moment().format(defaultConsoleFormat) }),
-        customFormat
-    )
-});
-
-// Create default console transport (will be replaced via settings)
-let consoleTransport = new transports.Console({
-    format: format.combine(
-        format.colorize(),
-        format.timestamp({ format: () => moment().format(defaultConsoleFormat) }),
-        customFormat
-    )
-});
-logger.add(consoleTransport);
-
-// Reference to file transport (added via settings)
-let fileTransport;
-
-/**
- * Configures logging settings for both console and file transports.
- *
- * @param {LogSettingsOptions} options - The settings for both console and file logging.
- * @example
- * // Example: Fully custom console timestamp that preserves decorational brackets,
- * // and enabling file logging.
- * log.settings({ 
- *   console: { 
- *     enableTimestamp: true,
- *     timestampFormat: "This is the date: [YYYY-MM-DD HH:mm:ss] - "
- *   },
- *   files: { 
- *     folder: 'logs', 
- *     filesName: 'YYYY-MM-DD', 
- *     maxFile: '14d', 
- *     maxSize: '20m', 
- *     zippedArchive: false 
- *   }
- * });
- */
-function applySettings(options = {}) {
-    if (options.console) {
-        const enableTimestamp = options.console.enableTimestamp !== undefined ? options.console.enableTimestamp : true;
-        const timestampFormat = options.console.timestampFormat || defaultConsoleFormat;
-
-        // Remove the current console transport
-        logger.remove(consoleTransport);
-
-        // Build the console format based on the enableTimestamp flag.
-        const consoleFormat = enableTimestamp
-            ? format.combine(
-                format.colorize(),
-                format.timestamp({ format: () => formatCustomTimestamp(timestampFormat) }),
-                customFormat
-            )
-            : format.combine(
-                format((info) => { delete info.timestamp; return info; })(),
-                format.colorize(),
-                customFormat
-            );
-
-        consoleTransport = new transports.Console({
-            format: consoleFormat
-        });
-        logger.add(consoleTransport);
-    }
-
-    if (options.files) {
-        const folder = options.files.folder || 'logs';
-        const datePattern = options.files.filesName || 'YYYY-MM-DD';
-        const maxFiles = options.files.maxFile || '14d';
-        const maxSize = options.files.maxSize || '20m';
-        const zippedArchive = options.files.zippedArchive !== undefined ? options.files.zippedArchive : false;
-
-        if (!fs.existsSync(folder)) {
-            fs.mkdirSync(folder, { recursive: true });
-        }
-
-        if (fileTransport) {
-            logger.remove(fileTransport);
-        }
-
-        fileTransport = new transports.DailyRotateFile({
-            filename: `${folder}/application-%DATE%.log`,
-            datePattern,
-            zippedArchive,
-            maxSize,
-            maxFiles
-        });
-        logger.add(fileTransport);
-    }
-}
-
-/**
- * Logs a general message using the info level.
- *
- * @param {string} message - The message to be logged.
- */
-function log(message) {
-    logger.info(message);
-}
-
-log.error = function (message) {
-    logger.error(message);
-};
-
-log.warn = function (message) {
-    logger.warn(message);
-};
-
-log.info = function (message) {
-    logger.info(message);
-};
-
-log.debug = function (message) {
-    logger.debug(message);
-};
-
-// Expose the settings function for configuring both file logging and console output.
-log.settings = applySettings;
-
-module.exports = log;
+const fs = require('fs');
+const path = require('path');
+const dayjs = require('dayjs');
+const { createLogger, format, transports } = require('winston');
+require('winston-daily-rotate-file');
+
+const VALID_LEVELS = ['error', 'warn', 'info', 'http', 'verbose', 'debug', 'silly'];
+const DEFAULT_CONSOLE_FORMAT = 'YYYY-MM-DD HH:mm:ss';
+
+function formatCustomTimestamp(fmt) {
+  if (typeof fmt !== 'string' || !fmt) return dayjs().format(DEFAULT_CONSOLE_FORMAT);
+  if (fmt.includes('[') && fmt.includes(']')) {
+    return fmt.split(/(\[[^\]]*\])/).map((part) => {
+      if (part.startsWith('[') && part.endsWith(']')) {
+        const inner = part.slice(1, -1);
+        return '[' + (inner ? dayjs().format(inner) : '') + ']';
+      }
+      return part;
+    }).join('');
+  }
+  return dayjs().format(fmt);
+}
+
+function formatExtra(meta) {
+  const keys = Object.keys(meta).filter((k) => k !== 'splat' && k !== 'ms');
+  if (!keys.length) return '';
+  try {
+    const picked = {};
+    for (const k of keys) picked[k] = meta[k];
+    return JSON.stringify(picked);
+  } catch {
+    return '';
+  }
+}
+
+const prettyFormat = format.printf(({ timestamp, level, message, ...meta }) => {
+  const msg = typeof message === 'string' ? message : message == null ? '' : JSON.stringify(message);
+  const extra = formatExtra(meta);
+  const body = [msg, extra].filter(Boolean).join(' ');
+  return timestamp ? `${timestamp} [${level}]: ${body}` : `[${level}]: ${body}`;
+});
+
+function assertLevel(level) {
+  if (!VALID_LEVELS.includes(level)) throw new Error(`Invalid log level "${level}". Use one of: ${VALID_LEVELS.join(', ')}`);
+}
+
+function normalizeFilesOptions(files = {}) {
+  const folder = files.folder ?? 'logs';
+  if (typeof folder !== 'string' || !folder.trim() || folder.includes('\0')) {
+    throw new Error('files.folder must be a non-empty string');
+  }
+  const datePattern = files.filesName ?? files.datePattern ?? 'YYYY-MM-DD';
+  if (typeof datePattern !== 'string' || !datePattern.trim()) {
+    throw new Error('files.filesName/datePattern must be a non-empty string');
+  }
+  let filename = files.filename ?? `application-%DATE%.log`;
+  if (typeof filename !== 'string' || !filename.trim()) {
+    throw new Error('files.filename must be a non-empty string');
+  }
+  if (!filename.includes('%DATE%')) {
+    const ext = path.extname(filename) || '.log';
+    const base = path.basename(filename, ext);
+    filename = `${base}-%DATE%${ext}`;
+  }
+  return {
+    folder: path.normalize(folder),
+    datePattern,
+    filename,
+    maxFiles: files.maxFile ?? files.maxFiles ?? '14d',
+    maxSize: files.maxSize ?? '20m',
+    zippedArchive: files.zippedArchive ?? false,
+    level: files.level,
+  };
+}
+
+function buildConsoleTransport({ enableTimestamp = true, timestampFormat = DEFAULT_CONSOLE_FORMAT, timestampPrefix = '', timestampSuffix = '', colorize = true, level } = {}) {
+  const parts = [];
+  if (colorize) parts.push(format.colorize());
+  if (enableTimestamp) {
+    parts.push(format.timestamp({ format: () => `${timestampPrefix}${formatCustomTimestamp(timestampFormat)}${timestampSuffix}` }));
+  } else {
+    parts.push(format((info) => { delete info.timestamp; return info; })());
+  }
+  parts.push(format.errors({ stack: true }), format.splat(), prettyFormat);
+  return new transports.Console({ format: format.combine(...parts), level });
+}
+
+function buildFileTransport({ folder, datePattern, filename, maxFiles, maxSize, zippedArchive, level }) {
+  if (!fs.existsSync(folder)) fs.mkdirSync(folder, { recursive: true });
+  return new transports.DailyRotateFile({
+    filename: path.join(folder, filename),
+    datePattern,
+    zippedArchive,
+    maxSize,
+    maxFiles,
+    level,
+    format: format.combine(format.errors({ stack: true }), format.splat(), format.timestamp(), prettyFormat),
+  });
+}
+
+function createLoggerInstance(initial = {}) {
+  const globalLevel = process.env.LOG_LEVEL || initial.level || 'debug';
+  assertLevel(globalLevel);
+
+  const logger = createLogger({
+    level: globalLevel,
+    format: format.combine(format.errors({ stack: true }), format.splat()),
+  });
+
+  let consoleTransport = buildConsoleTransport(initial.console);
+  consoleTransport.level = initial.console?.level;
+  logger.add(consoleTransport);
+
+  let fileTransport = null;
+  let consoleOpts = { ...(initial.console || {}) };
+  let filesOpts = null;
+
+  function applySettings(options = {}) {
+    if (options.level !== undefined) {
+      assertLevel(options.level);
+      logger.level = options.level;
+    }
+    if (options.console) {
+      if (options.console.level !== undefined && options.console.level !== null) assertLevel(options.console.level);
+      consoleOpts = { ...consoleOpts, ...options.console };
+      logger.remove(consoleTransport);
+      consoleTransport = buildConsoleTransport(consoleOpts);
+      consoleTransport.level = consoleOpts.level;
+      logger.add(consoleTransport);
+    }
+    if (options.files) {
+      const normalized = normalizeFilesOptions(options.files);
+      if (normalized.level !== undefined && normalized.level !== null) assertLevel(normalized.level);
+      filesOpts = normalized;
+      if (fileTransport) logger.remove(fileTransport);
+      fileTransport = buildFileTransport(normalized);
+      logger.add(fileTransport);
+    }
+  }
+
+  function write(level, message, ...meta) {
+    if (message instanceof Error) {
+      logger.log(level, message.message, { stack: message.stack, ...meta[0] });
+      return;
+    }
+    logger.log(level, message, ...meta);
+  }
+
+  function callable(message, ...meta) {
+    write('info', message, ...meta);
+  }
+
+  callable.error = (m, ...a) => write('error', m, ...a);
+  callable.warn = (m, ...a) => write('warn', m, ...a);
+  callable.info = (m, ...a) => write('info', m, ...a);
+  callable.debug = (m, ...a) => write('debug', m, ...a);
+  callable.http = (m, ...a) => write('http', m, ...a);
+  callable.verbose = (m, ...a) => write('verbose', m, ...a);
+  callable.silly = (m, ...a) => write('silly', m, ...a);
+  callable.log = (level, m, ...a) => { assertLevel(level); write(level, m, ...a); };
+
+  callable.settings = applySettings;
+  callable.setLevel = (level) => { assertLevel(level); logger.level = level; };
+  callable.getLevel = () => logger.level;
+  callable.child = (meta = {}) => {
+    const child = logger.child(meta);
+    return {
+      error: (m, ...a) => child.error(m, ...a),
+      warn: (m, ...a) => child.warn(m, ...a),
+      info: (m, ...a) => child.info(m, ...a),
+      debug: (m, ...a) => child.debug(m, ...a),
+      log: child.log.bind(child),
+    };
+  };
+  callable.close = () => {
+    if (fileTransport) { logger.remove(fileTransport); try { fileTransport.close?.(); } catch {} fileTransport = null; }
+  };
+  callable.createLogger = (opts = {}) => createLoggerInstance(opts);
+  callable._winston = logger;
+
+  if (initial.files) applySettings({ files: initial.files });
+  if (initial.console || initial.level) applySettings({ console: initial.console, level: initial.level });
+
+  return callable;
+}
+
+module.exports = createLoggerInstance();
+module.exports.createLogger = createLoggerInstance;