analogger 2.3.5 → 2.6.0

package/README.md

@@ -245,6 +245,43 @@ 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");
+```
+
+
+---
+
+#### Example 7: The "order" option
+
+###### Enforce a call sequence by assigning an `order` number to each log entry. If a log with a lower order value appears after one with a higher value, AnaLogger emits a console warning. Calls without an `order` are transparent and do not affect the sequence.
+
+```javascript
+anaLogger.log({lid: "API",     order: 1},  "This matches");
+anaLogger.log({lid: "API_123", order: 2},  "This shows API_123");
+anaLogger.log({lid: "WEB_456", order: 35}, "This is blocked");
+```
+
+If the calls arrive out of sequence — for example, `API_123` (order 2) appearing after `WEB_456` (order 35) — the following warning is printed to the console:
+
+```
+! Order mismatch:  [API_123| order: 2] appeared after [WEB_456| order: 35]
+```
+
+> **Notes:**
+> - The check is per-instance, so different AnaLogger instances track their own sequences independently.
+> - Calls filtered out by `only`, targets, or log levels are not counted toward the sequence.
+> - Equal order values (non-decreasing) are always allowed; only strictly lower values trigger the warning.
+
+
 ---
 
 ### listSymbols()
@@ -312,6 +349,8 @@ 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 |
+| 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_ |
 
 <br/>
 
@@ -1333,6 +1372,7 @@ anaLogger.log("lid: USR_LOGIN, color: purple", "User logged in");
 *  Add an option to show the date and time in logs
 *  Make the alert method display the lid when detected
 *  Keep format when displaying multiple lines for one entry
+*  Add `order` option to detect and warn on out-of-sequence log calls
 
 
 ##### 1.23.2:

package/ana-logger.d.cts

@@ -75,6 +75,12 @@ declare class ____AnaLogger {
         NODE: string;
         OTHER: string;
     };
+    _localOnlyFilter: any;
+    _localOnlyLabel: string;
+    _lastOrderEntry: {
+        lid: any;
+        order: any;
+    };
     getName(): string;
     getId(): string;
     /**
@@ -123,7 +129,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,15 @@ 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;
+
+        // Tracks the last seen "order" entry { lid, order } for order-mismatch detection.
+        this._lastOrderEntry = null;
     }
 
     getName()
@@ -932,6 +941,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 +991,7 @@ class ____AnaLogger
                    contextLenMax = 10,
                    idLenMax = 5,
                    lidLenMax = 6,
+                   only = undefined,
                    symbolLenMax = 2,
                    enableTrace = true,
                    messageLenMax = undefined,
@@ -1026,6 +1037,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;
 
@@ -2276,6 +2288,7 @@ class ____AnaLogger
                 const {context, args} = entry;
                 if (context) {
                     context.symbol = "floppy_disk";
+                    delete context.order;
                 }
                 this.processOutput(context, ...args);
             });
@@ -2582,6 +2595,146 @@ class ____AnaLogger
         return result;
     }
 
+    /**
+     * Check that log calls with an "order" property arrive in non-decreasing order.
+     * When a call with a lower order value appears after one with a higher order value,
+     * a warning is printed:
+     *   ! Order mismatch: [API_123| order: 2] appeared after [WEB_456| order: 35]
+     *
+     * @param {object} context
+     */
+    #checkOrder(context)
+    {
+        if (context.order === undefined || context.order === null)
+        {
+            return;
+        }
+
+        const currentOrder = context.order;
+        const currentLid   = context.lid || "";
+
+        if (this._lastOrderEntry !== null)
+        {
+            const {lid: prevLid, order: prevOrder} = this._lastOrderEntry;
+
+            if (currentOrder < prevOrder)
+            {
+                const msg = `! Order mismatch:  [${currentLid}| order: ${currentOrder}] appeared after [${prevLid}| order: ${prevOrder}]`;
+                ____AnaLogger.Console.warn(msg);
+            }
+        }
+
+        this._lastOrderEntry = {lid: currentLid, order: currentOrder};
+    }
+
+    /**
+     * 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 +2765,7 @@ class ____AnaLogger
                         lid: context.lid,
                         callCount: 1,
                         callTimes: [Date.now()]
-                    }
+                    };
                 }
             }
 
@@ -2648,6 +2801,40 @@ 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;
+            }
+
+            // Check that "order" values are non-decreasing across calls.
+            this.#checkOrder(context);
+
             const newMessages = this.checkOnLogging(context, argsWithoutContext[0], arguments,"onMessage");
             if (newMessages !== undefined) {
                 arguments[1] = newMessages;
@@ -2770,6 +2957,7 @@ class ____AnaLogger
             options.hasOwnProperty("color") ||
             options.hasOwnProperty("contextName") ||
             options.hasOwnProperty("raw") ||
+            options.hasOwnProperty("only") ||
             options.hasOwnProperty("lid");
     }