node-ansi-logger 3.3.2-dev-20260921-3edd1cb → 3.3.2-dev-20261015-6bea90d

package/CHANGELOG.md

@@ -25,18 +25,29 @@ If you like this project and find it useful, please consider giving it a star on
 
 ### Added
 
+- [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.
+- [agents]: Add [`commit message instructions`](.github/commit-message-instructions.md) v.1.0.0 for the VS Code Copilot "Generate Commit Message" button (Conventional Commits).
 
 ### Changed
 
+- [vscode]: Update `.vscode/settings.json` to v.1.0.15.
+- [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.68.0.
-- [package]: Bump `oxlint` to v.1.83.0.
-- [package]: Bump `oxlint-tsgolint` to v.7.0.2002.
-- [package]: Bump `vitest` to v.5.0.1.
-- [package]: Bump `@vitest/coverage-v8` to v.5.0.1.
-- [package]: Bump `@types/node` to v.26.6.2.
+- [package]: Bump `oxfmt` to v.0.73.0.
+- [package]: Bump `oxlint` to v.1.88.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.
+
+### Fixed
+
+- [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

@@ -29,12 +29,13 @@ If you like this project and find it useful, please consider giving it a star on
   for output instead of console.
 - Includes also a fully customizable stringify funtion with colors (it is bigint aware and manage circular reference).
 - Includes a chainable ANSI tagged template API (`ansi`) for styling terminal strings directly.
+- Optional shared circular message cache with configurable capacity (default 200), snapshots, callback replay, and clearing.
 
 ## Getting Started
 
 ### Prerequisites
 
-- Node.js 20-22-24 installed on your machine.
+- Node.js 20.19.0 or later within 20.x, 22.13.0 or later within 22.x, 24.x, or 26.x.
 
 ### Installation
 
@@ -82,6 +83,46 @@ log(LogLevel.WARN, 'Warning message', ...parameters);
 log.debug(`Debug message ${YELLOW}with yellow part${db}`, ...);
 ```
 
+## Caching and replaying messages
+
+Set a shared cache to enable caching for all logger instances:
+
+```typescript
+import { AnsiLogger, AnsiLoggerCache } from 'node-ansi-logger';
+
+const cache = new AnsiLoggerCache(); // Retains the latest 200 messages by default.
+AnsiLogger.setGlobalCache(cache);
+
+const log = new AnsiLogger({ logName: 'MyApp' });
+log.info('Connected');
+
+const messages = cache.get(); // [{ level: 'info', time: '...', name: 'MyApp', message: 'Connected' }]
+const activeCache = AnsiLogger.getGlobalCache(); // Returns cache, or undefined when disabled.
+cache.replay((entry) => {
+  console.log(`[${entry.time}] [${entry.name}] [${entry.level}] ${entry.message}`);
+});
+
+cache.clear(); // Removes retained messages; caching remains enabled.
+AnsiLogger.setGlobalCache(undefined); // Disables caching without clearing retained messages.
+```
+
+`setGlobalCache(cache)` returns the configured cache. Both static methods use
+`globalThis.__AnsiLoggerCache__`, which can also be assigned directly.
+
+Pass a positive safe integer to customize capacity, for example `new AnsiLoggerCache(500)`.
+The circular buffer overwrites the oldest entry when full. Only messages allowed by each
+logger's configured log level are cached, including messages routed to an external logger.
+Additional parameters are joined with spaces, matching logger callbacks; message text and
+ANSI codes are preserved. Existing console, file and callback output is unchanged.
+
+`get()` returns independent copies in oldest-to-newest order. `replay(callback)` sends
+the same structured entries to the callback from a snapshot without consuming the cache.
+Messages added during replay are not included in that replay. Callback errors propagate
+to the caller.
+
+`clear()` empties the cache and resets the circular buffer without changing its capacity
+or disabling caching. Existing snapshots returned by `get()` are unaffected.
+
 ## Using the logger internal timer:
 
 ```typescript

package/dist/ansi.js

@@ -196,9 +196,9 @@ function isStyleName(prop) {
  * @returns {AnsiTag} Chainable ANSI tag.
  */
 function createTag(styles = []) {
+    // oxlint-disable-next-line typescript/no-unsafe-type-assertion
     const tag = ((strings, ...values) => {
         return applyStyles(joinTemplate(strings, values), styles);
-        // oxlint-disable-next-line typescript/no-unsafe-type-assertion
     });
     return new Proxy(tag, {
         get(target, prop) {

package/dist/cache.d.ts

@@ -0,0 +1,71 @@
+/**
+ * @file src/cache.ts
+ * @description Circular message cache for AnsiLogger.
+ * @author Luca Liguori
+ * @created 2026-10-15
+ * @version 3.3.2
+ * @license Apache-2.0
+ *
+ * Copyright 2026 Luca Liguori.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import type { LogLevel } from './logger.js';
+/**
+ * A cached log message with its original level, timestamp and logger name.
+ */
+export interface AnsiLoggerCacheMessage {
+    level: LogLevel;
+    time: string;
+    name: string;
+    message: string;
+}
+/**
+ * Stores the most recent log messages in a fixed-capacity circular buffer.
+ */
+export declare class AnsiLoggerCache {
+    #private;
+    /**
+     * Creates an empty message cache.
+     *
+     * @param {number} capacity - Maximum number of messages to retain; defaults to 200.
+     * @throws {RangeError} If capacity is not a positive safe integer.
+     */
+    constructor(capacity?: number);
+    /**
+     * Adds a message, overwriting the oldest message when the cache is full.
+     *
+     * @param {AnsiLoggerCacheMessage} entry - Message to copy into the cache.
+     * @returns {void}
+     */
+    add(entry: AnsiLoggerCacheMessage): void;
+    /**
+     * Removes all retained messages without changing capacity or disabling caching.
+     *
+     * @returns {void}
+     */
+    clear(): void;
+    /**
+     * Returns a snapshot of cached messages from oldest to newest.
+     *
+     * @returns {AnsiLoggerCacheMessage[]} Copies of all retained messages.
+     */
+    get(): AnsiLoggerCacheMessage[];
+    /**
+     * Replays a snapshot from oldest to newest without consuming the cache.
+     *
+     * @param {(entry: AnsiLoggerCacheMessage) => void} callback - Receives each cached message; thrown errors propagate to the caller.
+     * @returns {void}
+     */
+    replay(callback: (entry: AnsiLoggerCacheMessage) => void): void;
+}

package/dist/cache.js

@@ -0,0 +1,80 @@
+/**
+ * @file src/cache.ts
+ * @description Circular message cache for AnsiLogger.
+ * @author Luca Liguori
+ * @created 2026-10-15
+ * @version 3.3.2
+ * @license Apache-2.0
+ *
+ * Copyright 2026 Luca Liguori.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * Stores the most recent log messages in a fixed-capacity circular buffer.
+ */
+export class AnsiLoggerCache {
+    #capacity;
+    #messages = [];
+    #next = 0;
+    /**
+     * Creates an empty message cache.
+     *
+     * @param {number} capacity - Maximum number of messages to retain; defaults to 200.
+     * @throws {RangeError} If capacity is not a positive safe integer.
+     */
+    constructor(capacity = 200) {
+        if (!Number.isSafeInteger(capacity) || capacity <= 0) {
+            throw new RangeError('Cache capacity must be a positive safe integer.');
+        }
+        this.#capacity = capacity;
+    }
+    /**
+     * Adds a message, overwriting the oldest message when the cache is full.
+     *
+     * @param {AnsiLoggerCacheMessage} entry - Message to copy into the cache.
+     * @returns {void}
+     */
+    add(entry) {
+        this.#messages[this.#next] = { ...entry };
+        this.#next = (this.#next + 1) % this.#capacity;
+    }
+    /**
+     * Removes all retained messages without changing capacity or disabling caching.
+     *
+     * @returns {void}
+     */
+    clear() {
+        this.#messages.length = 0;
+        this.#next = 0;
+    }
+    /**
+     * Returns a snapshot of cached messages from oldest to newest.
+     *
+     * @returns {AnsiLoggerCacheMessage[]} Copies of all retained messages.
+     */
+    get() {
+        return [...this.#messages.slice(this.#next), ...this.#messages.slice(0, this.#next)].map((entry) => ({ ...entry }));
+    }
+    /**
+     * Replays a snapshot from oldest to newest without consuming the cache.
+     *
+     * @param {(entry: AnsiLoggerCacheMessage) => void} callback - Receives each cached message; thrown errors propagate to the caller.
+     * @returns {void}
+     */
+    replay(callback) {
+        for (const entry of this.get()) {
+            callback(entry);
+        }
+    }
+}

package/dist/logger.d.ts

@@ -3,7 +3,7 @@
  * @description This file contains the AnsiLogger class.
  * @author Luca Liguori
  * @created 2023-06-01
- * @version 3.0.3
+ * @version 3.3.2
  * @license Apache-2.0
  *
  * Copyright 2024, 2025, 2026 Luca Liguori.
@@ -20,6 +20,7 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
+import type { AnsiLoggerCache } from './cache.js';
 export declare const RESET = "\u001B[0m";
 export declare const BRIGHT = "\u001B[1m";
 export declare const DIM = "\u001B[2m";
@@ -118,8 +119,18 @@ export interface AnsiLoggerParams {
 }
 export type AnsiLoggerCallback = (level: string, time: string, name: string, message: string) => void;
 declare global {
+    /**
+     * Global cache for AnsiLogger messages.
+     */
+    var __AnsiLoggerCache__: AnsiLoggerCache | undefined;
+    /**
+     * Global callback for AnsiLogger messages.
+     */
     var __AnsiLoggerCallback__: AnsiLoggerCallback | undefined;
     var __AnsiLoggerCallbackLoglevel__: LogLevel | undefined;
+    /**
+     * Global file path for AnsiLogger file output.
+     */
     var __AnsiLoggerFilePath__: string | undefined;
     var __AnsiLoggerFileLoglevel__: LogLevel | undefined;
     var __AnsiLoggerFileLogSize__: number | undefined;
@@ -298,6 +309,19 @@ export declare class AnsiLogger {
      * @returns {AnsiLoggerCallback | undefined} The callback function.
      */
     getCallback(): AnsiLoggerCallback | undefined;
+    /**
+     * Sets the shared cache used by all logger instances.
+     *
+     * @param {AnsiLoggerCache | undefined} cache - Cache to enable, or undefined to disable caching without clearing retained messages.
+     * @returns {AnsiLoggerCache | undefined} The configured cache.
+     */
+    static setGlobalCache(cache: AnsiLoggerCache | undefined): AnsiLoggerCache | undefined;
+    /**
+     * Gets the shared cache currently used by all logger instances.
+     *
+     * @returns {AnsiLoggerCache | undefined} The configured cache, or undefined when caching is disabled.
+     */
+    static getGlobalCache(): AnsiLoggerCache | undefined;
     /**
      * Sets the global callback function to be used by the logger.
      *

package/dist/logger.js

@@ -3,7 +3,7 @@
  * @description This file contains the AnsiLogger class.
  * @author Luca Liguori
  * @created 2023-06-01
- * @version 3.0.3
+ * @version 3.3.2
  * @license Apache-2.0
  *
  * Copyright 2024, 2025, 2026 Luca Liguori.
@@ -102,6 +102,8 @@ export var TimestampFormat;
     TimestampFormat[TimestampFormat["CUSTOM"] = 6] = "CUSTOM";
 })(TimestampFormat || (TimestampFormat = {}));
 // Initialize the global variables
+if (typeof globalThis.__AnsiLoggerCache__ === 'undefined')
+    globalThis.__AnsiLoggerCache__ = undefined;
 if (typeof globalThis.__AnsiLoggerCallback__ === 'undefined')
     globalThis.__AnsiLoggerCallback__ = undefined;
 if (typeof globalThis.__AnsiLoggerCallbackLoglevel__ === 'undefined')
@@ -405,6 +407,24 @@ export class AnsiLogger {
     getCallback() {
         return this.#callback;
     }
+    /**
+     * Sets the shared cache used by all logger instances.
+     *
+     * @param {AnsiLoggerCache | undefined} cache - Cache to enable, or undefined to disable caching without clearing retained messages.
+     * @returns {AnsiLoggerCache | undefined} The configured cache.
+     */
+    static setGlobalCache(cache) {
+        globalThis.__AnsiLoggerCache__ = cache;
+        return globalThis.__AnsiLoggerCache__;
+    }
+    /**
+     * Gets the shared cache currently used by all logger instances.
+     *
+     * @returns {AnsiLoggerCache | undefined} The configured cache, or undefined when caching is disabled.
+     */
+    static getGlobalCache() {
+        return globalThis.__AnsiLoggerCache__;
+    }
     /**
      * Sets the global callback function to be used by the logger.
      *
@@ -713,6 +733,21 @@ export class AnsiLogger {
         if (typeof level !== 'string' || level.startsWith === undefined || typeof message !== 'string' || message.startsWith === undefined) {
             return;
         }
+        // Cache the log message in the global cache if available
+        try {
+            if (globalThis.__AnsiLoggerCache__ !== undefined && this.shouldLog(level, this.#logLevel)) {
+                const parametersString = parameters.length > 0 ? ' ' + parameters.join(' ') : '';
+                globalThis.__AnsiLoggerCache__.add({
+                    level,
+                    time: this.getTimestamp(),
+                    name: this.#logName,
+                    message: message + parametersString,
+                });
+            }
+        }
+        catch (error) {
+            console.error('Error caching log message:', error);
+        }
         // Local callback
         try {
             if (this.#callback !== undefined && this.shouldLog(level, this.#logLevel)) {
@@ -743,7 +778,7 @@ export class AnsiLogger {
                 const size = this.logToFile(this.logFilePath, level, message, ...parameters);
                 this.#logFileSize += size;
                 if (this.#logFileSize >= this.#maxFileSize) {
-                    // istanbul ignore next
+                    /* v8 ignore next */
                     appendFileSync(this.logFilePath, `Logging on file has been stoppped because the file size is greater then ${this.#maxFileSize}B.\n`);
                 }
             }
@@ -761,7 +796,7 @@ export class AnsiLogger {
                 const size = this.logToFile(__AnsiLoggerFilePath__, level, message, ...parameters);
                 __AnsiLoggerFileLogSize__ += size;
                 if (__AnsiLoggerFileLogSize__ >= this.#maxFileSize) {
-                    // istanbul ignore next
+                    /* v8 ignore next */
                     appendFileSync(__AnsiLoggerFilePath__, `Logging on file has been stoppped because the file size is greater then ${this.#maxFileSize}B.\n`);
                 }
             }

package/dist/module.d.ts

@@ -3,7 +3,7 @@
  * @description This file contains the public API entry point for the node-ansi-logger package.
  * @author Luca Liguori
  * @created 2024-02-20
- * @version 3.3.1
+ * @version 3.3.2
  * @license Apache-2.0
  *
  * Copyright 2024, 2025, 2026 Luca Liguori.
@@ -21,5 +21,6 @@
  * limitations under the License.
  */
 export * from './ansi.js';
+export * from './cache.js';
 export * from './logger.js';
 export * from './stringify.js';

package/dist/module.js

@@ -3,7 +3,7 @@
  * @description This file contains the public API entry point for the node-ansi-logger package.
  * @author Luca Liguori
  * @created 2024-02-20
- * @version 3.3.1
+ * @version 3.3.2
  * @license Apache-2.0
  *
  * Copyright 2024, 2025, 2026 Luca Liguori.
@@ -22,5 +22,6 @@
  */
 /* v8 ignore file -- barrel file with only re-exports; nothing to cover (honored by both jest/istanbul and vitest/v8) */
 export * from './ansi.js';
+export * from './cache.js';
 export * from './logger.js';
 export * from './stringify.js';

package/dist/stringify.js

@@ -123,7 +123,7 @@ export function stringify(payload, enableColors = false, colorPayload = 252, col
                 return `${clr(colorUndefined)}(function)${reset()}`;
             // No Default
         }
-        /* istanbul ignore next */
+        /* v8 ignore next */
         return `${clr(colorUndefined)}${String(value)}${reset()}`;
     };
     const isTrackable = typeof payload === 'object' && payload !== null;
@@ -156,7 +156,7 @@ 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);
-        // istanbul ignore next cause is unreachable code for typeof, but included for completeness
+        /* v8 ignore next cause is unreachable code for typeof, but included for completeness */
         if (value === null) {
             newValue = `${clr(colorUndefined)}null${reset()}`;
         }

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "node-ansi-logger",
-  "version": "3.3.2-dev-20260921-3edd1cb",
+  "version": "3.3.2-dev-20261015-6bea90d",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "node-ansi-logger",
-      "version": "3.3.2-dev-20260921-3edd1cb",
+      "version": "3.3.2-dev-20261015-6bea90d",
       "license": "Apache-2.0",
       "engines": {
         "node": ">=20.19.0 <21.0.0 || >=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-20260921-3edd1cb",
+  "version": "3.3.2-dev-20261015-6bea90d",
   "description": "Enhanced Ansi Color Logging and Stringify for Node.js in type script",
   "author": "https://github.com/Luligu",
   "license": "Apache-2.0",