analogger 2.10.0 → 2.12.0

package/README.md

@@ -397,6 +397,7 @@ Display the browser native message box if run from it; otherwise, it displays th
 | hideError             | false       | boolean                           | _Hide errors from console_                                                         |              
 | hideHookMessage       | false       | boolean                           | _Hide the automatic message shown when some native console methods are overridden_ |
 | hidePassingTests      | false       | boolean                           | _Hide Live test results_                                                           |           
+| keepBreadcrumb      | false       | boolean                           | _Show brief history graph_                                                           |
 | logToDom              | false       | string (DOM Selector)             | _display log in a DOM container_                                                   |
 | logToFile             | false       | string (File path)                | _write log to a file if running from Node_                                         |
 | logToRemote           | undefined   | string (URL)                      | _Send log to a remote (more info in the next version)_                             |
@@ -418,6 +419,7 @@ Display the browser native message box if run from it; otherwise, it displays th
 | addArchiveTimestamp   | 	true       | boolean                           | 	_Appends a consistent timestamp to rotated files_                                 |
 | forceLidOn            | 	false      | boolean                           | 	_Automatically generates a short hash LID if one isn't provided_                  |
 | only | undefined | string/Regex/Array | Filter logs to show only those matching specific IDs or patterns |
+| resetMaxSeen | 	undefined |	array | Resets maxSeen counters |
 | resetOrder | 	undefined |	boolean | Resets the internal tracking for the order sequence |
 | order | undefined | number | _Enforce call order — emits a console warning if a log with a lower order value appears after one with a higher value_ |
 | maxSeen | undefined | number | _Emits a console warning when the same lid is logged more times than this limit_ |

package/ana-logger.d.cts

@@ -83,6 +83,7 @@ declare class ____AnaLogger {
     };
     _seenCount: {};
     _testResults: any[];
+    _breadcrumbHistory: any[];
     getName(): string;
     getId(): string;
     /**
@@ -131,7 +132,7 @@ declare class ____AnaLogger {
     resetLogger(): void;
     remoteWaitCount: any;
     resetOptions(): void;
-    setOptions({ timeLenMax, contextLenMax, idLenMax, lidLenMax, only, symbolLenMax, enableTrace, messageLenMax, hideLog, hideError, hideHookMessage, hidePassingTests, logToDom, logToFile, logMaxSize, logMaxArchives, logIndexArchive, addArchiveTimestamp, addArchiveIndex, compressArchives, compressionLevel, logToRemote, logToRemoteUrl, logToRemoteBinaryUrl, loopback, requiredLogLevel, oneConsolePerContext, silent, enableDate, enableMillisec, logToLocalStorage, logToLocalStorageMax, logToLocalStorageSize, logToRemoteMaxEntries, logToRemoteDebounce, logToRemoteMaxSize, logToRemoteMinSize, logUidToRemote, protocol, host, port, pathname, binarypathname, loadHtmlToImage }?: any): void;
+    setOptions({ timeLenMax, contextLenMax, idLenMax, lidLenMax, only, symbolLenMax, enableTrace, messageLenMax, hideLog, hideError, hideHookMessage, hidePassingTests, logToDom, logToFile, logMaxSize, logMaxArchives, logIndexArchive, addArchiveTimestamp, addArchiveIndex, compressArchives, compressionLevel, logToRemote, logToRemoteUrl, logToRemoteBinaryUrl, loopback, requiredLogLevel, oneConsolePerContext, silent, enableDate, enableMillisec, logToLocalStorage, logToLocalStorageMax, logToLocalStorageSize, logToRemoteMaxEntries, logToRemoteDebounce, logToRemoteMaxSize, logToRemoteMinSize, logUidToRemote, protocol, host, port, pathname, binarypathname, loadHtmlToImage, keepBreadcrumb }?: any): void;
     EOL: string;
     updateOptions(options: any): void;
     getOptions(): {
@@ -323,6 +324,24 @@ declare class ____AnaLogger {
      * Resets the order tracking.
      */
     resetOrder(): void;
+    /**
+     * Reset the maxSeen counter for one or more lids so they can be logged
+     * up to their maxSeen limit again from scratch.
+     *
+     * @param {string|string[]} lids  - A single lid string or an array of lid strings to reset.
+     *                                  Pass nothing (or an empty array) to reset ALL lid counters.
+     * @returns {string[]} The list of lids that were actually reset.
+     *
+     * @example
+     * anaLogger.resetMaxSeen(["API_1"]);          // reset one lid
+     * anaLogger.resetMaxSeen(["API_1", "API_3"]); // reset several lids
+     * anaLogger.resetMaxSeen();                   // reset every lid counter
+     */
+    resetMaxSeen(lids: string | string[]): string[];
+    /**
+     * Reset the breadcrumb history so the trail starts fresh.
+     */
+    resetBreadcrumb(): void;
     /**
      * Print a summary of all test results collected via the "test" context option.
      * If any test failed the banner and counts are printed in bold red (Node) or

package/browser/ana-logger.mjs

@@ -738,6 +738,10 @@ class ____AnaLogger
         // Accumulates test results recorded by the "test" context option.
         // Each entry is { lid, passed, message }.
         this._testResults = [];
+
+        // Ordered list of lid values seen so far.
+        // Used by the "breadcrumb" context option to print the history path.
+        this._breadcrumbHistory = [];
     }
 
     getName()
@@ -984,6 +988,7 @@ class ____AnaLogger
         this.options.logToRemoteMaxSize = undefined;
         this.options.logToRemoteMinSize = undefined;
         this.options.logUidToRemote = undefined;
+        this.options.keepBreadcrumb = false;
         this.remoteBuffer = [];
         this.remoteTimer = null;
         this.remoteWaitCount = 0;
@@ -1039,7 +1044,8 @@ class ____AnaLogger
                    port = undefined,
                    pathname = undefined,
                    binarypathname = undefined,
-                   loadHtmlToImage = false
+                   loadHtmlToImage = false,
+                   keepBreadcrumb = undefined
                } = null)
     {
         this.options.contextLenMax = contextLenMax;
@@ -1109,6 +1115,7 @@ class ____AnaLogger
             {logToRemote},
             {logToLocalStorage},
             {logUidToRemote},
+            {keepBreadcrumb},
         ].forEach((feature) =>
         {
             const key = Object.keys(feature)[0];
@@ -2677,6 +2684,107 @@ class ____AnaLogger
         }
     }
 
+    /**
+     * Reset the maxSeen counter for one or more lids so they can be logged
+     * up to their maxSeen limit again from scratch.
+     *
+     * @param {string|string[]} lids  - A single lid string or an array of lid strings to reset.
+     *                                  Pass nothing (or an empty array) to reset ALL lid counters.
+     * @returns {string[]} The list of lids that were actually reset.
+     *
+     * @example
+     * anaLogger.resetMaxSeen(["API_1"]);          // reset one lid
+     * anaLogger.resetMaxSeen(["API_1", "API_3"]); // reset several lids
+     * anaLogger.resetMaxSeen();                   // reset every lid counter
+     */
+    resetMaxSeen(lids)
+    {
+        // Normalise: no argument → reset everything
+        if (lids === undefined || lids === null)
+        {
+            const all = Object.keys(this._seenCount);
+            this._seenCount = {};
+            return all;
+        }
+
+        // Accept a bare string as well as an array
+        const targets = Array.isArray(lids) ? lids : [lids];
+        const reset   = [];
+
+        for (const lid of targets)
+        {
+            if (Object.prototype.hasOwnProperty.call(this._seenCount, lid))
+            {
+                delete this._seenCount[lid];
+                reset.push(lid);
+            }
+        }
+
+        return reset;
+    }
+
+    /**
+     * Reset the breadcrumb history so the trail starts fresh.
+     */
+    resetBreadcrumb()
+    {
+        this._breadcrumbHistory = [];
+    }
+
+    /**
+     * Handle the "breadcrumb" context option.
+     *
+     * When context.breadcrumb is true the method:
+     *   1. Appends the current context.lid (if any) to the history.
+     *   2. Prints the full trail as:   lid1 => lid2 => ... => lidN
+     *   3. Returns true to signal that normal log output should be skipped.
+     *
+     * For every other log call (no breadcrumb flag) the lid is silently
+     * appended to the history so the trail always stays up-to-date.
+     *
+     * @param {object} context
+     * @returns {boolean}  true when the call was a breadcrumb display call.
+     */
+    #handleBreadcrumb(context)
+    {
+        const lid = context.lid !== undefined && context.lid !== null && context.lid !== ""
+            ? String(context.lid)
+            : null;
+
+        if (!context.breadcrumb)
+        {
+            // Regular log call — just record the lid if the feature is enabled.
+            if (lid && this.options.keepBreadcrumb)
+            {
+                this._breadcrumbHistory.push(lid);
+            }
+            return false;
+        }
+
+        // breadcrumb: true — append the current lid (if any) and print the trail.
+        // Works even if keepBreadcrumb was just enabled: we record the current lid
+        // so it at least appears in the trail.
+        if (lid && this.options.keepBreadcrumb)
+        {
+            this._breadcrumbHistory.push(lid);
+        }
+
+        const trail = this._breadcrumbHistory.join(" => ") || "(empty)";
+        const label = "Breadcrumb: ";
+
+        if (this.isBrowser())
+        {
+            ____AnaLogger.Console.log(`%c${label}${trail}`, "color: #888; font-style: italic");
+        }
+        else
+        {
+            const styled = toAnsi.getTextFromColor(`${label}${trail}`, {fg: "#888888"});
+            ____AnaLogger.Console.log(styled);
+        }
+
+        return true;
+    }
+
     /**
      * Evaluate the "test" context option and record the result.
      * - If test is a function, it is called with no arguments and its return value is used.
@@ -2914,6 +3022,16 @@ class ____AnaLogger
             }
             this.applySymbolByName(context);
 
+            // Handle the "breadcrumb" option — track lid history and, when
+            // breadcrumb:true, print the trail then skip normal output.
+            // Must run before any filtering (target, logLevel, only) so that:
+            //   a) lids are always recorded regardless of active filters, and
+            //   b) a breadcrumb display call is never silently suppressed.
+            if (this.#handleBreadcrumb(context))
+            {
+                return;
+            }
+
             this.checkOnLogging(context, context, argsWithoutContext, "onContext");
             if (!this.isTargetAllowed(context.target))
             {