analogger 2.3.5 → 2.4.0

package/src/ana-logger.cjs

@@ -717,6 +717,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()
@@ -928,6 +934,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;
@@ -977,6 +984,7 @@ class ____AnaLogger
                    contextLenMax = 10,
                    idLenMax = 5,
                    lidLenMax = 6,
+                   only = undefined,
                    symbolLenMax = 2,
                    enableTrace = true,
                    messageLenMax = undefined,
@@ -1022,6 +1030,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;
 
@@ -2583,6 +2592,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
@@ -2613,7 +2730,7 @@ class ____AnaLogger
                         lid: context.lid,
                         callCount: 1,
                         callTimes: [Date.now()]
-                    }
+                    };
                 }
             }
 
@@ -2649,6 +2766,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;
@@ -2771,6 +2919,7 @@ class ____AnaLogger
             options.hasOwnProperty("color") ||
             options.hasOwnProperty("contextName") ||
             options.hasOwnProperty("raw") ||
+            options.hasOwnProperty("only") ||
             options.hasOwnProperty("lid");
     }