node-ansi-logger 3.3.2-dev-20261024-45fad9d → 3.3.2-dev-20261101-829a7db

package/CHANGELOG.md

@@ -25,6 +25,7 @@ If you like this project and find it useful, please consider giving it a star on
 
 ### Added
 
+- [logger]: Add `AnsiLogger.isLogLevel()` and `AnsiLogger.isTimestampFormat()` static type guard helpers.
 - [logger]: Add an opt-in global circular message cache with configurable capacity, snapshots, callback replay, clearing and static setter/getter.
 - [devcontainer]: Add [`Dev Container`](.devcontainer/README.md) v.2.2.0 with dual Node and Bun runtime support.
 - [agents]: Add a [`shared setup`](.agents/README.md) for all agents: OpenAI Codex, Claude Code, GitHub Copilot and Google Gemini / Antigravity.
@@ -32,21 +33,40 @@ If you like this project and find it useful, please consider giving it a star on
 
 ### Changed
 
-- [vscode]: Update `.vscode/settings.json` to v.1.0.15.
+- [logger]: BREAKING: Remove the deprecated `logDebug` constructor option. Use `logLevel` instead.
+- [vscode]: Update `.vscode/settings.json` to v.1.0.17.
 - [config]: Update Oxlint and Oxfmt configurations to v.1.1.0 and Antigravity settings to v.1.0.5.
 - [config]: Update TypeScript build configurations and rename `vite.config.ts` to `vitest.config.ts`, including CI workflow detection.
 - [styleguide]: Update [`STYLEGUIDE.md`](STYLEGUIDE.md) to v.1.1.0: align it with the lint and format config and add the Commit Messages and Changelog sections.
 - [scripts]: Update scripts to v.2.0.0.
 - [package]: Upgrade package.
-- [package]: Bump `oxfmt` to v.0.74.0.
-- [package]: Bump `oxlint` to v.1.89.0.
+- [package]: Bump `oxfmt` to v.0.75.0.
+- [package]: Bump `oxlint` to v.1.90.0.
 - [package]: Bump `oxlint-tsgolint` to v.7.0.2004.
 - [package]: Bump `vitest` to v.5.0.5.
 - [package]: Bump `@vitest/coverage-v8` to v.5.0.5.
-- [package]: Bump `@types/node` to v.26.6.5.
+- [package]: Bump `@types/node` to v.26.6.6.
+- [codex]: Update `.codex/config.toml` to v.1.0.6.
+- [agents]: Update `.github/commit-message-instructions.md` to v.1.0.1.
+- [vscode]: Update `.vscode/tasks.json`.
+- [agents]: Update `AGENTS.md` to v.1.0.8.
+- [config]: Update `CODE_OF_CONDUCT.md` to v.1.0.0.
+- [config]: Update `CONTRIBUTING.md` to v.1.0.1.
+- [scripts]: Update `scripts/downloads.mjs`.
+- [scripts]: Update `scripts/git-sync-dev.mjs`.
+- [config]: Update `src/logger.ts`.
+- [config]: Update `vitest/cache.test.ts`.
+- [config]: Update `vitest/logger.branchcoverage.test.ts`.
+- [config]: Update `vitest/logger.test.ts`.
+- [config]: Add `SHARED-AGENTS.md`.
+- [config]: Add `TOOLCHAIN.md` v.1.0.1.
 
 ### Fixed
 
+- [logger]: Honor the NO_COLOR standard: any non-empty value (not only `1`) disables colors in the logger, ansi helpers and stringify.
+- [logger]: `logFileSize` now returns `0` instead of `undefined` right after a log file path is set.
+- [logger]: Correct typos in the timer stop message and the file-size limit message.
+- [logger]: Correct the `setGlobalCallback` and `logTimeStampColor` JSDoc.
 - [ansi]: Move the unsafe type assertion suppression to match the current lint diagnostic.
 
 <a href="https://www.buymeacoffee.com/luligugithub"><img src="https://matterbridge.io/assets/bmc-button.svg" alt="Buy me a coffee" width="80"></a>

package/README.md

@@ -24,7 +24,7 @@ If you like this project and find it useful, please consider giving it a star on
 - Simple and intuitive API for data logging.
 - No dependencies.
 - Customizable colors and apperance.
-- Supports environment variable NO_COLOR=1 (https://no-color.org/).
+- Supports the NO_COLOR environment variable (https://no-color.org/): any non-empty value disables colors.
 - It is also possible to pass a top level logger (like Homebridge or Matter logger) and AnsiLogger will use it
   for output instead of console.
 - Includes also a fully customizable stringify funtion with colors (it is bigint aware and manage circular reference).

package/dist/ansi.js

@@ -118,7 +118,7 @@ function joinTemplate(strings, values) {
  * @returns {string} ANSI-decorated text.
  */
 function applyStyles(text, styles) {
-    if ('NO_COLOR' in process.env)
+    if (process.env.NO_COLOR)
         return text;
     let output = text;
     for (const [open, close] of styles) {

package/dist/logger.d.ts

@@ -106,10 +106,6 @@ export interface AnsiLoggerParams {
     extLog?: Logger;
     logName?: string;
     logNameColor?: string;
-    /**
-     * @deprecated Use logLevel instead.
-     */
-    logDebug?: boolean;
     logLevel?: LogLevel;
     logWithColors?: boolean;
     logTimestampFormat?: TimestampFormat;
@@ -165,6 +161,20 @@ export declare class AnsiLogger {
      * AnsiLogger.create({ logName: 'MyLogger' }).info('This is a info message');
      */
     static create(params: AnsiLoggerParams): AnsiLogger;
+    /**
+     * Checks whether a value is a valid LogLevel.
+     *
+     * @param {unknown} value - The value to check.
+     * @returns {value is LogLevel} True if the value is one of the LogLevel values.
+     */
+    static isLogLevel(value: unknown): value is LogLevel;
+    /**
+     * Checks whether a value is a valid TimestampFormat.
+     *
+     * @param {unknown} value - The value to check.
+     * @returns {value is TimestampFormat} True if the value is one of the TimestampFormat values.
+     */
+    static isTimestampFormat(value: unknown): value is TimestampFormat;
     /**
      * Gets the name of the logger.
      *
@@ -202,15 +212,15 @@ export declare class AnsiLogger {
      */
     set logWithColors(logWithColors: boolean);
     /**
-     * Gets the log name color string of the logger.
+     * Gets the log timestamp color string of the logger.
      *
-     * @returns {string} The log name color string.
+     * @returns {string} The log timestamp color string.
      */
     get logTimeStampColor(): string;
     /**
-     * Sets the log name color string for the logger.
+     * Sets the log timestamp color string for the logger.
      *
-     * @param {string} color - The logger name color string to set.
+     * @param {string} color - The log timestamp color string to set.
      */
     set logTimeStampColor(color: string);
     /**
@@ -326,9 +336,9 @@ export declare class AnsiLogger {
      * Sets the global callback function to be used by the logger.
      *
      * @param {AnsiLoggerCallback | undefined} callback - The callback function.
-     * @param {LogLevel} [callbackLevel]  - The log level of the log file (default LogLevel.DEBUG).
+     * @param {LogLevel} [callbackLevel] - The log level of the global callback (default LogLevel.DEBUG).
      *
-     * @returns {AnsiLoggerCallback | undefined} The path name of the log file.
+     * @returns {AnsiLoggerCallback | undefined} The callback function that was set.
      */
     static setGlobalCallback(callback: AnsiLoggerCallback | undefined, callbackLevel?: LogLevel): AnsiLoggerCallback | undefined;
     /**

package/dist/logger.js

@@ -150,16 +150,10 @@ export class AnsiLogger {
         this.#extLog = params.extLog;
         this.#logName = params.logName ?? 'NodeAnsiLogger';
         this.#logNameColor = params.logNameColor ?? '';
-        // oxlint-disable-next-line @typescript-eslint/no-deprecated
-        this.#logLevel = params.logLevel ?? (params.logDebug === true ? "debug" /* LogLevel.DEBUG */ : "info" /* LogLevel.INFO */);
-        this.#logWithColors = params.logWithColors ?? process.env.NO_COLOR !== '1';
-        this.#logTimestampFormat =
-            // oxlint-disable-next-line typescript/prefer-nullish-coalescing
-            params.logTimestampFormat !== undefined
-                ? params.logTimestampFormat
-                : process.env.NODE_ANSI_LOGGER_TIMESTAMP_FORMAT !== undefined && ['0', '1', '2', '3', '4', '5', '6'].includes(process.env.NODE_ANSI_LOGGER_TIMESTAMP_FORMAT)
-                    ? Number(process.env.NODE_ANSI_LOGGER_TIMESTAMP_FORMAT)
-                    : 3 /* TimestampFormat.LOCAL_DATE_TIME */;
+        this.#logLevel = params.logLevel ?? "info" /* LogLevel.INFO */;
+        this.#logWithColors = params.logWithColors ?? !process.env.NO_COLOR;
+        const envTimestampFormat = /^\d$/.test(process.env.NODE_ANSI_LOGGER_TIMESTAMP_FORMAT ?? '') ? Number(process.env.NODE_ANSI_LOGGER_TIMESTAMP_FORMAT) : undefined;
+        this.#logTimestampFormat = params.logTimestampFormat ?? (AnsiLogger.isTimestampFormat(envTimestampFormat) ? envTimestampFormat : 3 /* TimestampFormat.LOCAL_DATE_TIME */);
         this.#logTimeStampColor = params.logTimeStampColor ?? '';
         this.#logCustomTimestampFormat =
             params.logCustomTimestampFormat !== undefined && typeof params.logCustomTimestampFormat === 'string'
@@ -182,6 +176,34 @@ export class AnsiLogger {
     static create(params) {
         return new AnsiLogger(params);
     }
+    /**
+     * Checks whether a value is a valid LogLevel.
+     *
+     * @param {unknown} value - The value to check.
+     * @returns {value is LogLevel} True if the value is one of the LogLevel values.
+     */
+    static isLogLevel(value) {
+        const levels = ["debug" /* LogLevel.DEBUG */, "info" /* LogLevel.INFO */, "notice" /* LogLevel.NOTICE */, "warn" /* LogLevel.WARN */, "error" /* LogLevel.ERROR */, "fatal" /* LogLevel.FATAL */, "" /* LogLevel.NONE */];
+        return typeof value === 'string' && levels.includes(value);
+    }
+    /**
+     * Checks whether a value is a valid TimestampFormat.
+     *
+     * @param {unknown} value - The value to check.
+     * @returns {value is TimestampFormat} True if the value is one of the TimestampFormat values.
+     */
+    static isTimestampFormat(value) {
+        const formats = [
+            0 /* TimestampFormat.ISO */,
+            1 /* TimestampFormat.LOCAL_DATE */,
+            2 /* TimestampFormat.LOCAL_TIME */,
+            3 /* TimestampFormat.LOCAL_DATE_TIME */,
+            4 /* TimestampFormat.TIME_MILLIS */,
+            5 /* TimestampFormat.HOMEBRIDGE */,
+            6 /* TimestampFormat.CUSTOM */,
+        ];
+        return typeof value === 'number' && formats.includes(value);
+    }
     /**
      * Gets the name of the logger.
      *
@@ -231,17 +253,17 @@ export class AnsiLogger {
         this.#logWithColors = logWithColors;
     }
     /**
-     * Gets the log name color string of the logger.
+     * Gets the log timestamp color string of the logger.
      *
-     * @returns {string} The log name color string.
+     * @returns {string} The log timestamp color string.
      */
     get logTimeStampColor() {
         return this.#logTimeStampColor;
     }
     /**
-     * Sets the log name color string for the logger.
+     * Sets the log timestamp color string for the logger.
      *
-     * @param {string} color - The logger name color string to set.
+     * @param {string} color - The log timestamp color string to set.
      */
     set logTimeStampColor(color) {
         this.#logTimeStampColor = color;
@@ -344,7 +366,7 @@ export class AnsiLogger {
      * @returns {number | undefined} The size of log file, or undefined if not set.
      */
     get logFileSize() {
-        return this.#logFilePath && this.#logFileSize ? this.#logFileSize : undefined;
+        return this.#logFilePath ? this.#logFileSize : undefined;
     }
     /**
      * Gets the max file size of the file loggers.
@@ -387,7 +409,7 @@ export class AnsiLogger {
     stopTimer(message) {
         if (this.#logStartTime !== 0) {
             const timePassed = Date.now() - this.#logStartTime;
-            this.info(`Timer stoppped at ${timePassed} ms ${message}`);
+            this.info(`Timer stopped at ${timePassed} ms ${message}`);
         }
         this.#logStartTime = 0;
     }
@@ -429,9 +451,9 @@ export class AnsiLogger {
      * Sets the global callback function to be used by the logger.
      *
      * @param {AnsiLoggerCallback | undefined} callback - The callback function.
-     * @param {LogLevel} [callbackLevel]  - The log level of the log file (default LogLevel.DEBUG).
+     * @param {LogLevel} [callbackLevel] - The log level of the global callback (default LogLevel.DEBUG).
      *
-     * @returns {AnsiLoggerCallback | undefined} The path name of the log file.
+     * @returns {AnsiLoggerCallback | undefined} The callback function that was set.
      */
     static setGlobalCallback(callback, callbackLevel = "debug" /* LogLevel.DEBUG */) {
         __AnsiLoggerCallback__ = callback;
@@ -778,8 +800,7 @@ export class AnsiLogger {
                 const size = this.logToFile(this.logFilePath, level, message, ...parameters);
                 this.#logFileSize += size;
                 if (this.#logFileSize >= this.#maxFileSize) {
-                    /* v8 ignore next */
-                    appendFileSync(this.logFilePath, `Logging on file has been stoppped because the file size is greater then ${this.#maxFileSize}B.\n`);
+                    appendFileSync(this.logFilePath, `Logging on file has been stopped because the file size is greater than ${this.#maxFileSize}B.\n`);
                 }
             }
         }
@@ -796,8 +817,7 @@ export class AnsiLogger {
                 const size = this.logToFile(__AnsiLoggerFilePath__, level, message, ...parameters);
                 __AnsiLoggerFileLogSize__ += size;
                 if (__AnsiLoggerFileLogSize__ >= this.#maxFileSize) {
-                    /* v8 ignore next */
-                    appendFileSync(__AnsiLoggerFilePath__, `Logging on file has been stoppped because the file size is greater then ${this.#maxFileSize}B.\n`);
+                    appendFileSync(__AnsiLoggerFilePath__, `Logging on file has been stopped because the file size is greater than ${this.#maxFileSize}B.\n`);
                 }
             }
         }

package/dist/stringify.js

@@ -94,7 +94,7 @@ export function debugStringify(payload) {
  * @returns {string} A string representation of the payload with colors and quotes.
  */
 export function stringify(payload, enableColors = false, colorPayload = 252, colorKey = 250, colorString = 35, colorNumber = 220, colorBoolean = 159, colorUndefined = 1, keyQuote = '', stringQuote = "'", tab = 0, index = 0, seenObjects = new Set()) {
-    if (process.env.NO_COLOR === '1')
+    if (process.env.NO_COLOR)
         enableColors = false;
     if (payload === null)
         return 'null';
@@ -123,7 +123,7 @@ export function stringify(payload, enableColors = false, colorPayload = 252, col
                 return `${clr(colorUndefined)}(function)${reset()}`;
             // No Default
         }
-        /* v8 ignore next */
+        /* v8 ignore next -- unreachable: only primitives reach formatScalar and every primitive typeof is handled above */
         return `${clr(colorUndefined)}${String(value)}${reset()}`;
     };
     const isTrackable = typeof payload === 'object' && payload !== null;
@@ -156,7 +156,6 @@ export function stringify(payload, enableColors = false, colorPayload = 252, col
         // @ts-expect-error -- The type of value is unknown, but we will handle it in the code below
         newValue = value;
         // console.log(typeof newValue, key, value);
-        /* v8 ignore next cause is unreachable code for typeof, but included for completeness */
         if (value === null) {
             newValue = `${clr(colorUndefined)}null${reset()}`;
         }
@@ -188,10 +187,10 @@ export function stringify(payload, enableColors = false, colorPayload = 252, col
         }
         else if (typeof newValue === 'symbol') {
             newValue = `${clr(colorString)}${String(newValue)}${reset()}`;
-        }
+        } /* v8 ignore start -- unreachable: every typeof result is handled above */
         else {
             throw new Error(`Unsupported type: ${typeof newValue}`);
-        }
+        } /* v8 ignore stop */
         if (isArray) {
             string += newValue;
         }

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "node-ansi-logger",
-  "version": "3.3.2-dev-20261024-45fad9d",
+  "version": "3.3.2-dev-20261101-829a7db",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "node-ansi-logger",
-      "version": "3.3.2-dev-20261024-45fad9d",
+      "version": "3.3.2-dev-20261101-829a7db",
       "license": "Apache-2.0",
       "engines": {
         "node": ">=22.13.0 <23.0.0 || >=24.0.0 <25.0.0 || >=26.0.0 <27.0.0"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "node-ansi-logger",
-  "version": "3.3.2-dev-20261024-45fad9d",
+  "version": "3.3.2-dev-20261101-829a7db",
   "description": "Enhanced Ansi Color Logging and Stringify for Node.js in type script",
   "author": "https://github.com/Luligu",
   "license": "Apache-2.0",