logxpert 2.0.0 → 2.0.3

package/README.md

@@ -1,6 +1,6 @@
 # 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.
+Colorful console logging for Node.js with optional daily file rotation.
 
 ## Installation
 
@@ -8,90 +8,100 @@ LogXpert is a powerful logging library for Node.js that provides easy-to-use log
 npm install logxpert
 ```
 
-## Usage
+Requires Node.js `>=18`. Recommended minimum: Node.js 22 LTS. See [NODE_SUPPORT.md](NODE_SUPPORT.md) for the full support policy.
 
-CommonJS:
+## Quick start
 
 ```js
 const log = require('logxpert');
+// or: import log from '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'));
+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
 ```
 
-ESM:
+Levels: `error → warn → info → http → verbose → debug → silly` (default `debug`).
 
 ```js
-import log from 'logxpert';
+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
 
-log.info('hello');
+// Full control (omit prefix when used):
+log.settings({ files: { folder: 'logs', filePattern: 'app-%datePattern%.log' } });
 ```
 
-Set level (`LOG_LEVEL` env also respected):
+`%datePattern%` is replaced by the date (`datePattern` defaults to `YYYY_MM_DD`). Combining `prefix` with `filePattern` throws — pick one.
 
 ```js
-log.setLevel('info');
-console.log(log.getLevel());
+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
 ```
 
-Isolated instances and child loggers:
+## 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' });
-apiLog.info('isolated');
+const apiLog = createLogger({ level: 'info' }); // independent instance
 
-const child = log.child({ service: 'api' });
-child.info('child message');
+const child = log.child({ service: 'api' }); // bound context
 ```
 
-### File output & console timestamp
+## Full configuration (copy-paste)
 
 ```js
 log.settings({
-  level: 'debug',
+  level: 'debug', // or process.env.LOG_LEVEL
   console: {
     enableTimestamp: true,
     timestampFormat: 'YYYY-MM-DD HH:mm:ss',
     timestampPrefix: '',
     timestampSuffix: '',
-    colorize: true
+    colorize: true,
   },
   files: {
     folder: 'logs',
-    filename: 'application-%DATE%.log',
-    filesName: 'YYYY-MM-DD',
+    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
+    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.
+Legacy aliases: `appName` (= `prefix`), `filename`/`pattern` (= `filePattern`), `filesName`/`dateFormat` (= `datePattern`).
 
-Console options: `enableTimestamp`, `timestampFormat`, `timestampPrefix`, `timestampSuffix`, `colorize`, `level`.
-Files options: `folder`, `filename`, `filesName`/`datePattern`, `maxFile`/`maxFiles`, `maxSize`, `zippedArchive`, `level`.
+Security: messages are stripped of ANSI escapes and control characters (except `\n`, `\t`); file patterns escaping the log folder (`..`, absolute paths) are rejected.
 
 ## License
 
-GPL-3.0-only. See [LICENSE](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

@@ -1,57 +1,79 @@
-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;
-}
+declare namespace log {
+  export type LogLevel = 'error' | 'warn' | 'info' | 'http' | 'verbose' | 'debug' | 'silly';
 
-export interface FilesOptions {
-  folder?: string;
-  filesName?: string;
-  datePattern?: string;
-  filename?: string;
-  maxFile?: string;
-  maxFiles?: string;
-  maxSize?: string;
-  zippedArchive?: boolean;
-  level?: LogLevel;
-}
+  export interface ConsoleOptions {
+    enableTimestamp?: boolean;
+    timestampFormat?: string;
+    timestampPrefix?: string;
+    timestampSuffix?: string;
+    colorize?: boolean;
+    level?: LogLevel;
+  }
 
-export interface LogSettingsOptions {
-  console?: ConsoleOptions;
-  files?: FilesOptions;
-  level?: LogLevel;
-}
+  export interface RunNumberOptions {
+    enabled?: boolean;
+    separator?: string;
+    padding?: number;
+    startAt?: number;
+  }
 
-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 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 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;
+  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;
+declare const log: log.LogXpert;
+
+export = log;