analogger 2.6.0 → 2.8.0

package/README.md

@@ -281,6 +281,74 @@ If the calls arrive out of sequence — for example, `API_123` (order 2) appeari
 > - 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.
 
+---
+
+#### Example 8: The "maxSeen" option
+
+###### Limit how many times a given lid may be logged. Once the count exceeds `maxSeen`, every subsequent call emits a console warning. The limit and the counter are both tied to the lid string, so different lids track independently.
+
+```javascript
+anaLogger.log({lid: "API", maxSeen: 1}, "I'm first");   // OK — seen 1 time
+anaLogger.log({lid: "API", maxSeen: 1}, "I'm second");  // Warning — seen 2 times
+anaLogger.log({lid: "API", maxSeen: 1}, "I'm third");   // Warning — seen 3 times
+```
+
+When the limit is exceeded the following warning is printed to the console:
+
+```
+! MaxSeen exceeded: [API| maxSeen: 1] has been seen 2 time(s)
+! MaxSeen exceeded: [API| maxSeen: 1] has been seen 3 time(s)
+```
+
+> **Notes:**
+> - The counter is per-instance and per-lid — different lids each have their own count.
+> - Calls filtered out by `only`, targets, or log levels are not counted.
+> - `maxSeen` can be combined with `order` in the same context object.
+
+---
+
+#### Example 9: The "test" option and `report()`
+
+###### Attach an inline assertion to any log call. Pass `test: false` (or a function that returns `false`) and AnaLogger records a failure and emits a warning immediately. Call `report()` at any point to print a summary of all pass/fail results.
+
+```javascript
+anaLogger.log({lid: "API_1", test: false},      "I'm first");   // fails — boolean
+anaLogger.log({lid: "API_2", test: () => false}, "I'm second");  // fails — function
+anaLogger.log({lid: "API_3", test: true},        "I'm third");   // passes
+anaLogger.log({lid: "API_4", test: () => true},  "I'm fourth");  // passes
+
+anaLogger.report();
+```
+
+Failing calls emit an immediate warning:
+
+```
+! Test failed: [API_1] I'm first
+! Test failed: [API_2] I'm second
+```
+
+`report()` then prints a bordered summary. If any test failed the output is **bold red**; if all tests passed it is **bold green**:
+
+```
+================== ANALOGGER TEST RESULT ================
+  Total  : 4
+  Passed : 2
+  Failed : 2
+==========================================================
+```
+
+`report()` also returns the counts as an object, so you can assert on them programmatically:
+
+```javascript
+const {total, passed, failed} = anaLogger.report();
+```
+
+> **Notes:**
+> - `test` accepts a plain boolean or a zero-argument function — both are resolved to a boolean.
+> - Every call that carries a `test` key is recorded, whether it passes or fails.
+> - Calls without a `test` key are completely transparent and never appear in the report.
+> - Results accumulate across the lifetime of the instance. Call `anaLogger._testResults = []` to reset between suites if needed.
+
 
 ---
 
@@ -351,6 +419,8 @@ Display the browser native message box if run from it; otherwise, it displays th
 | 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_ |
+| maxSeen | undefined | number | _Emits a console warning when the same lid is logged more times than this limit_ |
+| test | undefined | boolean / () => boolean | _Records a pass/fail result for the log call; emits a warning immediately on failure. Use_ `report()` _to see the full summary_ |
 
 <br/>
 
@@ -1373,6 +1443,8 @@ anaLogger.log("lid: USR_LOGIN, color: purple", "User logged in");
 *  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
+*  Add `maxSeen` option to warn when a lid is logged more times than allowed
+*  Add `test` context option and `report()` method for inline assertions and test summaries
 
 
 ##### 1.23.2:

package/ana-logger.d.cts

@@ -81,6 +81,8 @@ declare class ____AnaLogger {
         lid: any;
         order: any;
     };
+    _seenCount: {};
+    _testResults: any[];
     getName(): string;
     getId(): string;
     /**
@@ -317,6 +319,23 @@ declare class ____AnaLogger {
     checkOnLogging(context: any, data: any, extras: any, callbackName: any): any;
     isContextMessagePattern(str: any): boolean;
     transformContextMessage(template: any, data: any): any;
+    /**
+     * 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
+     * red CSS (browser); otherwise they are printed in green.
+     *
+     * Output format:
+     * ================== ANALOGGER TEST RESULT ================
+     *   Total  : N
+     *   Passed : N
+     *   Failed : N
+     * ==========================================================
+     */
+    report(): {
+        total: number;
+        passed: number;
+        failed: number;
+    };
     /**
      * Display log following template
      * @param context

package/browser/ana-logger.mjs

@@ -730,6 +730,14 @@ class ____AnaLogger
 
         // Tracks the last seen "order" entry { lid, order } for order-mismatch detection.
         this._lastOrderEntry = null;
+
+        // Tracks how many times each lid has been seen, keyed by lid string.
+        // Used by the "maxSeen" context option.
+        this._seenCount = {};
+
+        // Accumulates test results recorded by the "test" context option.
+        // Each entry is { lid, passed, message }.
+        this._testResults = [];
     }
 
     getName()
@@ -2289,6 +2297,8 @@ class ____AnaLogger
                 if (context) {
                     context.symbol = "floppy_disk";
                     delete context.order;
+                    delete context.maxSeen;
+                    delete context.test;
                 }
                 this.processOutput(context, ...args);
             });
@@ -2627,6 +2637,112 @@ class ____AnaLogger
         this._lastOrderEntry = {lid: currentLid, order: currentOrder};
     }
 
+    /**
+     * Check that a lid is not logged more times than its maxSeen limit.
+     * When the count exceeds the limit a warning is emitted:
+     *   ! MaxSeen exceeded: [API| maxSeen: 1] has been seen 2 time(s)
+     *
+     * @param {object} context
+     */
+    #checkMaxSeen(context)
+    {
+        if (context.maxSeen === undefined || context.maxSeen === null)
+        {
+            return;
+        }
+
+        const lid      = context.lid || "";
+        const maxSeen  = context.maxSeen;
+
+        this._seenCount[lid] = (this._seenCount[lid] || 0) + 1;
+        const count = this._seenCount[lid];
+
+        if (count > maxSeen)
+        {
+            const msg = `! MaxSeen exceeded: [${lid}| maxSeen: ${maxSeen}] has been seen ${count} time(s)`;
+            ____AnaLogger.Console.warn(msg);
+        }
+    }
+
+    /**
+     * 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.
+     * - If the resolved value is falsy a console warning is emitted immediately.
+     * - Every call (pass or fail) is appended to this._testResults for report().
+     *
+     * @param {object} context
+     * @param {string} message  — the log message, used in the test record
+     */
+    #checkTest(context, message)
+    {
+        if (!context.hasOwnProperty("test"))
+        {
+            return;
+        }
+
+        const lid        = context.lid || "";
+        const testVal    = context.test;
+        const passed     = typeof testVal === "function" ? !!testVal() : !!testVal;
+
+        this._testResults.push({lid, passed, message});
+
+        if (!passed)
+        {
+            ____AnaLogger.Console.warn(`! Test failed: [${lid}] ${message}`);
+        }
+    }
+
+    /**
+     * 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
+     * red CSS (browser); otherwise they are printed in green.
+     *
+     * Output format:
+     * ================== ANALOGGER TEST RESULT ================
+     *   Total  : N
+     *   Passed : N
+     *   Failed : N
+     * ==========================================================
+     */
+    report()
+    {
+        const total  = this._testResults.length;
+        const passed = this._testResults.filter((r) => r.passed).length;
+        const failed = total - passed;
+        const hasFailed = failed > 0;
+
+        const BORDER  = "================== ANALOGGER TEST RESULT ================";
+        const BORDER2 = "==========================================================";
+        const lines   = [
+            BORDER,
+            `  Total  : ${total}`,
+            `  Passed : ${passed}`,
+            `  Failed : ${failed}`,
+            BORDER2,
+        ];
+
+        if (this.isBrowser())
+        {
+            const style = hasFailed
+                ? "color: red; font-weight: bold;"
+                : "color: green; font-weight: bold;";
+            lines.forEach((line) => ____AnaLogger.Console.log(`%c${line}`, style));
+        }
+        else
+        {
+            lines.forEach((line) =>
+            {
+                const styled = toAnsi.getTextFromColor(line, {
+                    fg    : hasFailed ? "#FF0000" : "#00CC44",
+                    isBold: true,
+                });
+                ____AnaLogger.Console.log(styled);
+            });
+        }
+
+        return {total, passed, failed};
+    }
+
     /**
      * Handle the local "only" option on a log context.
      *
@@ -2835,6 +2951,9 @@ class ____AnaLogger
             // Check that "order" values are non-decreasing across calls.
             this.#checkOrder(context);
 
+            // Check that a lid is not logged more times than its maxSeen limit.
+            this.#checkMaxSeen(context);
+
             const newMessages = this.checkOnLogging(context, argsWithoutContext[0], arguments,"onMessage");
             if (newMessages !== undefined) {
                 arguments[1] = newMessages;
@@ -2844,6 +2963,9 @@ class ____AnaLogger
 
             message = this.convertArgumentsToText(args);
 
+            // Evaluate the "test" option and record the pass/fail result.
+            this.#checkTest(context, message);
+
             // Ensure UID is set early so it's available in history/context when requested
             if (this.options.logUidToRemote)
             {