logxpert 2.0.3 → 2.1.2

package/CHANGELOG.md

@@ -1,20 +1,20 @@
-# Changelog
-
-## Unreleased
-- Fix TS types for dual CJS/ESM: `export =` + namespace in `index.d.ts`, dedicated `index.d.mts` for the ESM entry (`attw` clean)
-- Rename `files` options with backward-compatible aliases: `prefix` (`appName`), `filePattern` (`filename`/`pattern`), `datePattern` (`filesName`/`dateFormat`); `%datePattern%` placeholder; `prefix` + `filePattern` now throws instead of silent precedence
-- Default file `datePattern` is now `YYYY_MM_DD`
-- License changed to `Apache-2.0`
-
-## 2.0.0
-- Replace `moment` with `dayjs`
-- Add ESM entry (`main.mjs`) + `index.d.ts` types
-- Add `log.setLevel/getLevel`, `LOG_LEVEL` env support
-- Add `log.createLogger()` isolated instances and `log.child()`
-- Add structured logging: objects, meta, `Error` stacks, `splat`
-- `files.filename` option, input validation in `settings()`
-- Fix license to `GPL-3.0-only`, add `exports`, `files`, `engines`
-- Add tests (`node --test`) and CI
-
-## 1.0.5
-- Previous CJS-only release with `moment` + `winston`.
+# Changelog
+
+## Unreleased
+- Fix TS types for dual CJS/ESM: `export =` + namespace in `index.d.ts`, dedicated `index.d.mts` for the ESM entry (`attw` clean)
+- Rename `files` options with backward-compatible aliases: `prefix` (`appName`), `filePattern` (`filename`/`pattern`), `datePattern` (`filesName`/`dateFormat`); `%datePattern%` placeholder; `prefix` + `filePattern` now throws instead of silent precedence
+- Default file `datePattern` is now `YYYY_MM_DD`
+- License changed to `Apache-2.0`
+
+## 2.0.0
+- Replace `moment` with `dayjs`
+- Add ESM entry (`main.mjs`) + `index.d.ts` types
+- Add `log.setLevel/getLevel`, `LOG_LEVEL` env support
+- Add `log.createLogger()` isolated instances and `log.child()`
+- Add structured logging: objects, meta, `Error` stacks, `splat`
+- `files.filename` option, input validation in `settings()`
+- Fix license to `GPL-3.0-only`, add `exports`, `files`, `engines`
+- Add tests (`node --test`) and CI
+
+## 1.0.5
+- Previous CJS-only release with `moment` + `winston`.

package/README.md

@@ -1,107 +1,119 @@
-# 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).
+# LogXpert
+
+Colorful console logging for Node.js with optional daily file rotation.
+
+- Zero heavy dependencies — built-in engine.
+- Daily file rotation with retention, size limits and gzip.
+- Per-level colors, lazy messages, child loggers, isolated instances.
+- Works from JS and TS, CommonJS and ESM.
+
+## 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,
+    colors: { info: 'blue', error: false }, // names, ANSI 0-255, or false per level
+  },
+});
+
+// Default colors: error red, warn yellow, info green, http magenta,
+// verbose cyan, debug blue, silly gray. Only the [level] tag is colored.
+
+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
+  sanitize: true, // strip ANSI escapes and control chars; false = pass through untouched
+  console: {
+    enableTimestamp: true,
+    timestampFormat: 'YYYY-MM-DD HH:mm:ss',
+    timestampPrefix: '',
+    timestampSuffix: '',
+    colorize: true,
+    colors: { info: 'blue', warn: 208, error: false }
+    // enabled: false, // file-only logging: silence the console
+  },
+  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

@@ -14,6 +14,7 @@ export const info: typeof log.info;
 export const debug: typeof log.debug;
 
 export type LogLevel = log.LogLevel;
+export type LevelColor = log.LevelColor;
 export type ConsoleOptions = log.ConsoleOptions;
 export type FilesOptions = log.FilesOptions;
 export type RunNumberOptions = log.RunNumberOptions;

package/index.d.ts

@@ -1,79 +1,84 @@
-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;
+declare namespace log {
+  export type LogLevel = 'error' | 'warn' | 'info' | 'http' | 'verbose' | 'debug' | 'silly';
+
+  export type LevelColor = string | number | false | null;
+
+  export interface ConsoleOptions {
+    enabled?: boolean;
+    enableTimestamp?: boolean;
+    timestampFormat?: string;
+    timestampPrefix?: string;
+    timestampSuffix?: string;
+    colorize?: boolean;
+    colors?: Partial<Record<LogLevel, LevelColor>>;
+    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 | false;
+    files?: FilesOptions;
+    level?: LogLevel;
+    sanitize?: boolean;
+  }
+
+  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;

package/lib/files.js

@@ -0,0 +1,102 @@
+const fs = require('fs');
+const path = require('path');
+const { sanitizeAppName, isPadChar, assertFilenameSafe } = require('./sanitize');
+
+let cachedAppName = null;
+function getDefaultAppName() {
+  if (cachedAppName) return cachedAppName;
+  try {
+    const pkgPath = path.resolve(process.cwd(), 'package.json');
+    const raw = fs.readFileSync(pkgPath, 'utf8');
+    cachedAppName = sanitizeAppName(JSON.parse(raw)?.name) ?? 'application';
+  } catch {
+    cachedAppName = 'application';
+  }
+  return cachedAppName;
+}
+
+function resolveRunNumber(folder, prefix, opt) {
+  let enabled = false;
+  let separator = '-';
+  let padding = 0;
+  let startAt = 1;
+  if (opt === true) {
+    enabled = true;
+  } else if (opt && typeof opt === 'object') {
+    enabled = opt.enabled ?? true;
+    if (opt.separator !== undefined) {
+      if (typeof opt.separator !== 'string' || !opt.separator) throw new Error('files.runNumber.separator must be a non-empty string');
+      separator = opt.separator;
+    }
+    if (opt.padding !== undefined) {
+      if (!Number.isInteger(opt.padding) || opt.padding < 0) throw new Error('files.runNumber.padding must be a non-negative integer');
+      padding = opt.padding;
+    }
+    if (opt.startAt !== undefined) {
+      if (!Number.isInteger(opt.startAt) || opt.startAt < 0) throw new Error('files.runNumber.startAt must be a non-negative integer');
+      startAt = opt.startAt;
+    }
+  } else if (opt !== undefined && opt !== false) {
+    throw new Error('files.runNumber must be a boolean or an object');
+  }
+  if (!enabled) return null;
+  const counterFile = path.join(folder, `.${prefix}.run`);
+  let next = startAt;
+  try {
+    const raw = fs.readFileSync(counterFile, 'utf8').trim();
+    const prev = parseInt(raw, 10);
+    next = Number.isInteger(prev) ? prev + 1 : startAt;
+  } catch {}
+  try {
+    fs.writeFileSync(counterFile, String(next), 'utf8');
+  } catch {}
+  return separator + String(next).padStart(padding, '0');
+}
+
+function normalizeFilesOptions(files = {}) {
+  const rawFolder = files.folder ?? 'logs';
+  if (typeof rawFolder !== 'string' || !rawFolder.trim() || rawFolder.includes('\0')) {
+    throw new Error('files.folder must be a non-empty string');
+  }
+  const folder = path.normalize(rawFolder);
+  const datePattern = files.datePattern ?? files.dateFormat ?? files.filesName ?? 'YYYY_MM_DD';
+  if (typeof datePattern !== 'string' || !datePattern.trim()) {
+    throw new Error('files.datePattern must be a non-empty string');
+  }
+  const explicitPattern = files.filePattern ?? files.pattern ?? files.filename;
+  const explicitPrefix = files.prefix ?? files.appName;
+  if (explicitPattern !== undefined && explicitPrefix !== undefined) {
+    throw new Error('Do not combine "prefix" with "filePattern", pick one: prefix builds "<prefix>-%DATE%.log" for you, filePattern takes full control');
+  }
+  let filename = explicitPattern ?? `${sanitizeAppName(explicitPrefix) ?? getDefaultAppName()}-%DATE%.log`;
+  filename = filename.split('%datePattern%').join('%DATE%');
+  assertFilenameSafe(filename);
+  if (!filename.includes('%DATE%')) {
+    const ext = path.extname(filename) || '.log';
+    const base = path.basename(filename, ext);
+    filename = `${base}-%DATE%${ext}`;
+  }
+  assertFilenameSafe(filename);
+  if (!fs.existsSync(folder)) fs.mkdirSync(folder, { recursive: true });
+  const rawPrefix = path.basename(filename).split('%DATE%')[0];
+  let prefixEnd = rawPrefix.length;
+  while (prefixEnd > 0 && isPadChar(rawPrefix[prefixEnd - 1])) prefixEnd--;
+  const prefix = rawPrefix.slice(0, prefixEnd) || 'application';
+  const runSuffix = resolveRunNumber(folder, sanitizeAppName(prefix) ?? 'application', files.runNumber ?? false);
+  if (runSuffix) {
+    const ext = path.extname(filename) || '.log';
+    const base = filename.slice(0, -ext.length);
+    filename = `${base}${runSuffix}${ext}`;
+  }
+  return {
+    folder,
+    datePattern,
+    filename,
+    maxFiles: files.maxFile ?? files.maxFiles ?? '14d',
+    maxSize: files.maxSize ?? '20m',
+    zippedArchive: files.zippedArchive ?? false,
+    level: files.level,
+  };
+}
+
+module.exports = { getDefaultAppName, resolveRunNumber, normalizeFilesOptions };

package/lib/format.js

@@ -0,0 +1,38 @@
+const util = require('util');
+
+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 '';
+  }
+}
+
+function mergeMeta(meta) {
+  const out = {};
+  for (const m of meta) {
+    if (m && typeof m === 'object') Object.assign(out, m);
+  }
+  return out;
+}
+
+function renderBody(message, meta) {
+  if (typeof message === 'string' && meta.length && /%[sdifoO%]/.test(message)) {
+    return util.format(message, ...meta);
+  }
+  const msg = typeof message === 'string' ? message : message == null ? '' : JSON.stringify(message);
+  const extra = formatExtra(mergeMeta(meta));
+  return [msg, extra].filter(Boolean).join(' ');
+}
+
+function buildLine(timestamp, level, message, meta, tag) {
+  const body = renderBody(message, meta);
+  const label = tag ?? `[${level}]`;
+  return timestamp ? `${timestamp} ${label}: ${body}` : `${label}: ${body}`;
+}
+
+module.exports = { formatExtra, mergeMeta, renderBody, buildLine };