analogger 2.3.4 → 2.4.0

package/README.md

@@ -245,6 +245,19 @@ anaLogger.log({lid: 1236, symbol: "scissors"}, `I'am some log with some scissors
 
 <br/>
 
+#### Example 6: The "only" filter
+
+###### You can filter logs globally so that only specific identifiers are displayed. This supports exact strings, partial matches, or regular expressions.
+
+```javascript
+// Only show logs where the LID or context contains "API"
+anaLogger.setOptions({ only: "API" });
+
+anaLogger.log({ lid: "API_123" }, "This matches and will be seen");
+anaLogger.log({ lid: "WEB_456" }, "This is blocked and hidden");
+```
+
+
 ---
 
 ### listSymbols()
@@ -312,6 +325,7 @@ Display the browser native message box if run from it; otherwise, it displays th
 | compressionLevel      | 	1	         | number                            | _Gzip compression level (0-9)_                                                     |
 | 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 |
 
 <br/>
 

package/ana-logger.d.cts

@@ -75,6 +75,8 @@ declare class ____AnaLogger {
         NODE: string;
         OTHER: string;
     };
+    _localOnlyFilter: any;
+    _localOnlyLabel: string;
     getName(): string;
     getId(): string;
     /**
@@ -123,7 +125,7 @@ declare class ____AnaLogger {
     resetLogger(): void;
     remoteWaitCount: any;
     resetOptions(): void;
-    setOptions({ timeLenMax, contextLenMax, idLenMax, lidLenMax, 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 }?: any): void;
     EOL: string;
     updateOptions(options: any): void;
     getOptions(): {

package/browser/ana-logger.mjs

@@ -721,6 +721,12 @@ class ____AnaLogger
         this.#initialiseDefault();
 
         this.resetLogHistory();
+
+        // Tracks the active local "only" filter across calls.
+        // _localOnlyFilter holds the raw value (for matching),
+        // _localOnlyLabel  holds the stringified form (for change-detection and separator text).
+        this._localOnlyFilter = undefined;
+        this._localOnlyLabel  = undefined;
     }
 
     getName()
@@ -932,6 +938,7 @@ class ____AnaLogger
         this.options.contextLenMax = 10;
         this.options.idLenMax = 5;
         this.options.lidLenMax = 6;
+        this.options.only = undefined;
         this.options.messageLenMax = undefined;
         this.options.symbolLenMax = 60;
         this.options.hideHookMessage = undefined;
@@ -981,6 +988,7 @@ class ____AnaLogger
                    contextLenMax = 10,
                    idLenMax = 5,
                    lidLenMax = 6,
+                   only = undefined,
                    symbolLenMax = 2,
                    enableTrace = true,
                    messageLenMax = undefined,
@@ -1026,6 +1034,7 @@ class ____AnaLogger
         this.options.contextLenMax = contextLenMax;
         this.options.idLenMax = idLenMax;
         this.options.lidLenMax = lidLenMax;
+        this.options.only = only;
         this.options.messageLenMax = messageLenMax;
         this.options.symbolLenMax = symbolLenMax;
 
@@ -2582,6 +2591,114 @@ class ____AnaLogger
         return result;
     }
 
+    /**
+     * Handle the local "only" option on a log context.
+     *
+     * Rules:
+     *  - If context.only is not set, do nothing.
+     *  - If context.only does NOT match context.lid (using the same partial-string /
+     *    regex logic as the global filter), the call is suppressed (returns false).
+     *  - On the very first matching call, the output channel is cleared:
+     *      • Browser  → console.clear()
+     *      • Node     → writes the terminal-reset sequence (\x1bc) to stdout
+     *  - On a subsequent matching call whose only value differs from the last seen
+     *    value, a separator line is printed instead of clearing.
+     *
+     * Returns false when the log entry should be suppressed, true otherwise.
+     *
+     * @param {object} context
+     * @returns {boolean}
+     */
+    #handleLocalOnly(context)
+    {
+        const localOnly = context.only;
+
+        // Helper: test a lid string against a single filter entry.
+        const lidMatchesFilter = (filter, lid) =>
+        {
+            if (filter instanceof RegExp)
+            {
+                return filter.test(lid);
+            }
+            if (typeof filter === "string" || filter instanceof String)
+            {
+                return lid.includes(filter);
+            }
+            return filter === lid;
+        };
+
+        // Helper: test a lid against a filter that may be a single value or an array.
+        const lidMatchesAny = (filter, lid) => Array.isArray(filter)
+            ? filter.some((f) => lidMatchesFilter(f, lid))
+            : lidMatchesFilter(filter, lid);
+
+        // Stable string label for a filter value (used for change-detection and separator text).
+        const toLabel = (filter) => Array.isArray(filter)
+            ? filter.map((f) => (f instanceof RegExp ? f.toString() : String(f))).join(", ")
+            : (filter instanceof RegExp ? filter.toString() : String(filter));
+
+        const lid = context.lid || "";
+
+        if (localOnly === undefined || localOnly === null)
+        {
+            // No local only on this call. If a filter is already active, enforce it.
+            if (this._localOnlyFilter !== undefined)
+            {
+                return lidMatchesAny(this._localOnlyFilter, lid);
+            }
+
+            // No active filter at all – let the call through.
+            return true;
+        }
+
+        // --- This call explicitly sets context.only ---
+
+        if (!lidMatchesAny(localOnly, lid))
+        {
+            // The lid doesn't match – suppress without clearing or printing a separator,
+            // since the filter hasn't been "activated" by an accepted call yet.
+            return false;
+        }
+
+        const onlyLabel = toLabel(localOnly);
+
+        if (this._localOnlyFilter === undefined)
+        {
+            // First ever match – clear the output channel.
+            if (this.isBrowser())
+            {
+                /* istanbul ignore next */
+                ____AnaLogger.Console.clear
+                    ? ____AnaLogger.Console.clear()
+                    : (typeof console !== "undefined" && console.clear && console.clear());
+            }
+            else
+            {
+                // ANSI terminal reset: clears the screen and moves cursor to top.
+                process.stdout.write("\x1bc");
+            }
+        }
+        else if (this._localOnlyLabel !== onlyLabel)
+        {
+            // Filter has changed – print a separator, no clear.
+            const separator = `─── only switched to ${onlyLabel} ───`;
+            if (this.isBrowser())
+            {
+                /* istanbul ignore next */
+                ____AnaLogger.Console.log(`%c${separator}`, "color: #888; font-style: italic");
+            }
+            else
+            {
+                // Use the raw console so the separator bypasses all AnaLogger formatting.
+                ____AnaLogger.Console.log(separator);
+            }
+        }
+
+        this._localOnlyFilter = localOnly;   // raw value – used for matching
+        this._localOnlyLabel  = onlyLabel;   // string    – used for change detection
+        return true;
+    }
+
     /**
      * Display log following template
      * @param context
@@ -2612,7 +2729,7 @@ class ____AnaLogger
                         lid: context.lid,
                         callCount: 1,
                         callTimes: [Date.now()]
-                    }
+                    };
                 }
             }
 
@@ -2648,6 +2765,37 @@ class ____AnaLogger
                 return;
             }
 
+            // Check if global "only" filter is active
+            if (this.options.only !== undefined && this.options.only !== null) {
+                const onlyFilters = Array.isArray(this.options.only) ? this.options.only : [this.options.only];
+                // Check if current log matches one of the filters
+                const matchesFilter = onlyFilters.some((filter) => {
+                    const targetLid = context.lid || "";
+                    const targetOnly = context.only || "";
+
+                    if (filter instanceof RegExp) {
+                        return filter.test(targetLid) || filter.test(targetOnly);
+                    }
+
+                    // String partial match (e.g., "API" matches "API_123")
+                    if (typeof filter === "string") {
+                        return targetLid.includes(filter) || targetOnly.includes(filter);
+                    }
+
+                    return filter === targetLid || filter === targetOnly;
+                });
+
+                if (!matchesFilter) {
+                    return;
+                }
+            }
+
+            // Handle the per-call local "only" option.
+            if (!this.#handleLocalOnly(context))
+            {
+                return;
+            }
+
             const newMessages = this.checkOnLogging(context, argsWithoutContext[0], arguments,"onMessage");
             if (newMessages !== undefined) {
                 arguments[1] = newMessages;
@@ -2732,9 +2880,11 @@ class ____AnaLogger
                 }
             }
 
-            if (this.options.hideLog || context.hideLog || context.silent)
-            {
-                return;
+            if (!(context.silent === false || context.hideLog === false)) {
+                if (this.options.hideLog || context.hideLog || context.silent)
+                {
+                    return;
+                }
             }
 
             this.writeToConsole(output, context);
@@ -2768,6 +2918,7 @@ class ____AnaLogger
             options.hasOwnProperty("color") ||
             options.hasOwnProperty("contextName") ||
             options.hasOwnProperty("raw") ||
+            options.hasOwnProperty("only") ||
             options.hasOwnProperty("lid");
     }