logxpert 1.0.5 → 2.0.3

package/README.md

@@ -1,108 +1,107 @@
-# 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`).
-
-## License
-
-This project is licensed under GNU General Public License v3.0. See the [LICENSE](LICENSE) file for details.
+# LogXpert
+
+Colorful console logging for Node.js with optional daily file rotation.
+
+## Installation
+
+```sh
+npm install logxpert
+```
+
+Requires Node.js `>=18`. Recommended minimum: Node.js 22 LTS. See [NODE_SUPPORT.md](NODE_SUPPORT.md) for the full support policy.
+
+## Quick start
+
+```js
+const log = require('logxpert');
+// or: import log from 'logxpert';
+
+log('general message');          // shortcut for info
+log.info('hello', { user: 1 });  // with metadata
+log.error(new Error('boom'));    // Errors print message + stack
+log.debug(() => JSON.stringify(hugeObject)); // lazy: skipped if level disabled
+```
+
+Levels: `error → warn → info → http → verbose → debug → silly` (default `debug`).
+
+```js
+log.setLevel('info'); // or via LOG_LEVEL env variable
+```
+
+## File logging
+
+```js
+log.settings({ files: { folder: 'logs' } });
+// → logs/logxpert-2026_10_08.log (prefix defaults to your package.json name)
+
+log.settings({ files: { folder: 'logs', prefix: 'api' } });
+// → logs/api-2026_10_08.log
+
+// Full control (omit prefix when used):
+log.settings({ files: { folder: 'logs', filePattern: 'app-%datePattern%.log' } });
+```
+
+`%datePattern%` is replaced by the date (`datePattern` defaults to `YYYY_MM_DD`). Combining `prefix` with `filePattern` throws — pick one.
+
+```js
+log.settings({
+  files: {
+    folder: 'logs',
+    runNumber: true,    // off by default → app-2026_10_08-1.log, -2.log, ...
+    maxFile: '14d',     // retention
+    maxSize: '20m',     // rotate above this size
+    zippedArchive: true,
+  },
+});
+log.close(); // call on shutdown
+```
+
+## Console & instances
+
+```js
+log.settings({
+  console: {
+    enableTimestamp: true,
+    timestampFormat: 'YYYY-MM-DD HH:mm:ss',
+    colorize: true,
+  },
+});
+
+const { createLogger } = require('logxpert');
+const apiLog = createLogger({ level: 'info' }); // independent instance
+
+const child = log.child({ service: 'api' }); // bound context
+```
+
+## Full configuration (copy-paste)
+
+```js
+log.settings({
+  level: 'debug', // or process.env.LOG_LEVEL
+  console: {
+    enableTimestamp: true,
+    timestampFormat: 'YYYY-MM-DD HH:mm:ss',
+    timestampPrefix: '',
+    timestampSuffix: '',
+    colorize: true,
+  },
+  files: {
+    folder: 'logs',
+    prefix: undefined, // defaults to your package.json name
+    // filePattern: 'app-%datePattern%.log', // full control (omit prefix if used)
+    datePattern: 'YYYY_MM_DD',
+    runNumber: false, // or true, or { separator: '-', padding: 0, startAt: 1 }
+    maxFile: '14d',
+    maxSize: '20m',
+    zippedArchive: false,
+  }
+});
+```
+
+Legacy aliases: `appName` (= `prefix`), `filename`/`pattern` (= `filePattern`), `filesName`/`dateFormat` (= `datePattern`).
+
+Security: messages are stripped of ANSI escapes and control characters (except `\n`, `\t`); file patterns escaping the log folder (`..`, absolute paths) are rejected.
+
+## License
+
+Apache-2.0. See [LICENSE](LICENSE).

package/index.d.mts

@@ -0,0 +1,22 @@
+import log from './index.js';
+
+export default log;
+
+export const settings: typeof log.settings;
+export const setLevel: typeof log.setLevel;
+export const getLevel: typeof log.getLevel;
+export const child: typeof log.child;
+export const close: typeof log.close;
+export const createLogger: typeof log.createLogger;
+export const error: typeof log.error;
+export const warn: typeof log.warn;
+export const info: typeof log.info;
+export const debug: typeof log.debug;
+
+export type LogLevel = log.LogLevel;
+export type ConsoleOptions = log.ConsoleOptions;
+export type FilesOptions = log.FilesOptions;
+export type RunNumberOptions = log.RunNumberOptions;
+export type LogSettingsOptions = log.LogSettingsOptions;
+export type ChildLogger = log.ChildLogger;
+export type LogXpert = log.LogXpert;

package/index.d.ts

@@ -0,0 +1,79 @@
+declare namespace log {
+  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 RunNumberOptions {
+    enabled?: boolean;
+    separator?: string;
+    padding?: number;
+    startAt?: number;
+  }
+
+  export interface FilesOptions {
+    folder?: string;
+    /** Preferred: date format for %DATE%. */
+    datePattern?: string;
+    /** @deprecated Use datePattern. */
+    filesName?: string;
+    dateFormat?: string;
+    /** Preferred: filename template containing %DATE%. */
+    filePattern?: string;
+    pattern?: string;
+    /** @deprecated Use filePattern. */
+    filename?: string;
+    /** Preferred: filename prefix used when no pattern is given. */
+    prefix?: string;
+    /** @deprecated Use prefix. */
+    appName?: string;
+    runNumber?: boolean | RunNumberOptions;
+    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: log.LogXpert;
+
+export = log;