analogger 2.1.0 → 2.2.0

package/README.md

@@ -1,7 +1,5 @@
 
-[![Test workflow](https://github.com/thimpat/analogger/actions/workflows/test.yml/badge.svg)](https://github.com/thimpat/analogger/actions/workflows/test.yml)
 [![nycrc Coverage](https://img.shields.io/nycrc/thimpat/analogger?preferredThreshold=lines)](https://github.com/thimpat/analogger/blob/main/README.md)
-[![Version workflow](https://github.com/thimpat/analogger/actions/workflows/versioning.yml/badge.svg)](https://github.com/thimpat/analogger/actions/workflows/versioning.yml)
 [![npm version](https://badge.fury.io/js/analogger.svg)](https://www.npmjs.com/package/analogger)
 <img alt="semantic-release" src="https://img.shields.io/badge/semantic--release-19.0.2-e10079?logo=semantic-release">
 
@@ -287,23 +285,29 @@ Display the browser native message box if run from it; otherwise, it displays th
 ### setOptions()
 
 
-| **Options**         | **default** | **Expect**                        | **Description**                                                                    | 
-|---------------------|-------------|-----------------------------------|------------------------------------------------------------------------------------|
-| silent              | false       | boolean                           | _Hide logs from console (not errors)_                                              |
-| hideLog             | false       | boolean                           | _Same as above (silent has precedence over hideLog)_                               |              
-| 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_                                                           |           
-| 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)_                             |
-| logMaxSize          | 0           | number                            | _Set maximum size for the log file_                                                |
-| compressArchives    | false       | boolean                           | _Whether to archive and compress the logs after deleting an archive_               |
-| compressionLevel    | 1           | number                            | _Archive compression level (0 to 9 with 0 = no compression)_                       |
-| addArchiveTimestamp | true        | boolean                           | _Whether to add a timestamp to the generated rotated logs_                         |
-| logMaxArchives      | 3           | number                            | _Maximum number of log files to use_                                               |
-| requiredLogLevel    | "LOG"       | "LOG" / "INFO" / "WARN" / "ERROR" | _Define the log level from which the system can show a log entry_                  |
-| enableDate          | false       | boolean                           | _Show date + time (instead of time only)_                                          |
+| **Options**           | **default** | **Expect**                        | **Description**                                                                    | 
+|-----------------------|-------------|-----------------------------------|------------------------------------------------------------------------------------|
+| silent                | false       | boolean                           | _Hide logs from console (not errors)_                                              |
+| hideLog               | false       | boolean                           | _Same as above (silent has precedence over hideLog)_                               |              
+| 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_                                                           |           
+| 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)_                             |
+| logMaxSize            | 0           | number                            | _Set maximum size for the log file_                                                |
+| compressArchives      | false       | boolean                           | _Whether to archive and compress the logs after deleting an archive_               |
+| compressionLevel      | 1           | number                            | _Archive compression level (0 to 9 with 0 = no compression)_                       |
+| addArchiveTimestamp   | true        | boolean                           | _Whether to add a timestamp to the generated rotated logs_                         |
+| logMaxArchives        | 3           | number                            | _Maximum number of log files to use_                                               |
+| requiredLogLevel      | "LOG"       | "LOG" / "INFO" / "WARN" / "ERROR" | _Define the log level from which the system can show a log entry_                  |
+| enableDate            | false       | boolean                           | _Show date + time (instead of time only)_                                          |
+| logToLocalStorage     | false       | 	boolean                          | _Persist logs in browser localStorage_                                             |
+| logToLocalStorageMax	 | 50	         | number                            | _Max entries to keep in localStorage_                                              |
+| compressArchives      | 	false	     | boolean                           | _If true, rotates log files into a .tar.gz archive_                                |
+| 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_                  |
 
 <br/>
 
@@ -1185,6 +1189,69 @@ anaLogger.addPlugin("doSomething", doSomething);
 
 
 
+```
+
+---
+
+[![Test workflow](https://github.com/thimpat/analogger/actions/workflows/test.yml/badge.svg)](https://github.com/thimpat/analogger/actions/workflows/test.yml)
+[![nycrc Coverage](https://img.shields.io/nycrc/thimpat/analogger?preferredThreshold=lines)](https://github.com/thimpat/analogger/blob/main/README.md)
+[![npm version](https://badge.fury.io/js/analogger.svg)](https://www.npmjs.com/package/analogger)
+
+Analogger is a highly customizable logger for Node and Browser environments. It logs to terminals, browser DOM, files, and remote servers.
+
+---
+
+## 🚀 New Features (v1.24+)
+
+### 💾 Local Storage Persistence (Browser)
+You can now persist logs in the browser's Local Storage. This is useful for debugging issues that occur across page refreshes.
+
+```javascript
+// Enable local storage logging
+anaLogger.setOptions({ 
+    logToLocalStorage: true, 
+    logToLocalStorageMax: 100 // Keep last 100 logs
+});
+
+// Restore logs from previous session after page reload
+anaLogger.restoreLogs();
+```
+
+🗄️ Advanced Log Rotation & Archiving (Node)
+Manage large log files with automatic rotation and .tar.gz compression.
+
+```javascript
+anaLogger.setOptions({
+    logToFile: "./app.log",
+    logMaxSize: 5 * 1024 * 1024, // 5MB
+    logMaxArchives: 5,
+    compressArchives: true,      // Archive rotated logs into .tar.gz
+    compressionLevel: 6,         // Gzip level (1-9)
+    addArchiveTimestamp: true    // Add ISO timestamps to filenames
+});
+```
+
+### New Helper Methods
+
+> restoreLogs()
+
+(Browser only) Reads the history from localStorage and re-prints the logs to the current console. Perfect for diagnosing crashes that trigger a page reload.
+
+> getLids()
+
+Returns a deep clone of all loaded Lids, including statistics like callCount, callTimes, and human-readable dates.
+
+> forceResolveLineCall(bool)
+
+When enabled, AnaLogger captures the exact file and line number where the log was called and attaches it to the context.
+
+### Manual LID strings
+
+If you don't want to pass objects, you can use a shorthand string format:
+
+```javascript
+// AnaLogger will parse this string as a context object
+anaLogger.log("lid: USR_LOGIN, color: purple", "User logged in");
 ```
 
 ---

package/ana-logger.d.cts

@@ -114,8 +114,10 @@ declare class ____AnaLogger {
      */
     isBrowser(): boolean;
     resetLogger(): void;
+    remoteBuffer: any[];
+    remoteTimer: NodeJS.Timeout;
     resetOptions(): void;
-    setOptions({ 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, logToLocalStorage, logToLocalStorageMax, protocol, host, port, pathname, binarypathname, loadHtmlToImage }?: any): void;
+    setOptions({ 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, logToLocalStorage, logToLocalStorageMax, logToLocalStorageSize, logToRemoteMaxEntries, logToRemoteDebounce, protocol, host, port, pathname, binarypathname, loadHtmlToImage }?: any): void;
     EOL: string;
     updateOptions(options: any): void;
     getOptions(): {
@@ -268,7 +270,9 @@ declare class ____AnaLogger {
         args?: any;
     }): void;
     writeLogToFile(text: any): void;
-    writeLogToRemote(...data: any[]): any;
+    writeLogToRemote(...data: any[]): void;
+    flushRemoteLogs(): void;
+    performRemotePost(data: any): any;
     writeLogToLocalStorage(context: any, ...args: any[]): void;
     restoreLogs(): void;
     /**

package/browser/ana-logger.mjs

@@ -930,6 +930,11 @@ class ____AnaLogger
         this.options.enableDate = undefined;
         this.options.logToLocalStorage = undefined;
         this.options.logToLocalStorageMax = 50;
+        this.options.logToLocalStorageSize = 10000;
+        this.options.logToRemoteMaxEntries = undefined;
+        this.options.logToRemoteDebounce = undefined;
+        this.remoteBuffer = [];
+        this.remoteTimer = null;
     }
 
     resetOptions()
@@ -967,6 +972,9 @@ class ____AnaLogger
                    enableDate = undefined,
                    logToLocalStorage = undefined,
                    logToLocalStorageMax = 50,
+                   logToLocalStorageSize = 10000,
+                   logToRemoteMaxEntries = undefined,
+                   logToRemoteDebounce = undefined,
                    /** Remote - all optional **/
                    protocol = undefined,
                    host = undefined,
@@ -994,6 +1002,9 @@ class ____AnaLogger
         this.options.enableTrace = enableTrace;
 
         this.options.logToLocalStorageMax = logToLocalStorageMax;
+        this.options.logToLocalStorageSize = logToLocalStorageSize;
+        this.options.logToRemoteMaxEntries = logToRemoteMaxEntries;
+        this.options.logToRemoteDebounce = logToRemoteDebounce;
 
         if (loadHtmlToImage) {
             const code = getHtmlToImage();
@@ -1986,6 +1997,58 @@ class ____AnaLogger
     }
 
     writeLogToRemote(...data)
+    {
+        try
+        {
+            if (this.options.logToRemoteMaxEntries === undefined && this.options.logToRemoteDebounce === undefined)
+            {
+                this.performRemotePost([...data]);
+                return;
+            }
+
+            this.remoteBuffer.push([...data]);
+
+            if (this.options.logToRemoteMaxEntries !== undefined && this.remoteBuffer.length >= this.options.logToRemoteMaxEntries)
+            {
+                this.flushRemoteLogs();
+                return;
+            }
+
+            if (this.options.logToRemoteDebounce !== undefined && !this.remoteTimer)
+            {
+                this.remoteTimer = setTimeout(() =>
+                {
+                    this.flushRemoteLogs();
+                }, this.options.logToRemoteDebounce);
+            }
+        }
+        catch (e)
+        {
+            /* istanbul ignore next */
+            ____AnaLogger.Console.error("LOG_TO_REMOTE_FAILURE: ", e.message);
+        }
+    }
+
+    flushRemoteLogs()
+    {
+        if (this.remoteTimer)
+        {
+            clearTimeout(this.remoteTimer);
+            this.remoteTimer = null;
+        }
+
+        if (this.remoteBuffer.length === 0)
+        {
+            return;
+        }
+
+        const dataToFlush = [...this.remoteBuffer];
+        this.remoteBuffer = [];
+
+        this.performRemotePost(dataToFlush);
+    }
+
+    performRemotePost(data)
     {
         try
         {
@@ -1995,8 +2058,7 @@ class ____AnaLogger
                 return null;
             }
 
-            const entry = [...data];
-            const stringified = JSON.stringify(entry);
+            const stringified = JSON.stringify(data);
             fetch(urlDest, {
                 method : "post",
                 body   : stringified,
@@ -2008,7 +2070,7 @@ class ____AnaLogger
         catch (e)
         {
             /* istanbul ignore next */
-            ____AnaLogger.Console.error("LOG_TO_REMOTE_FAILURE: ", e.message);
+            ____AnaLogger.Console.error("REMOTE_POST_FAILURE: ", e.message);
         }
     }
 
@@ -2044,7 +2106,16 @@ class ____AnaLogger
                 history = history.slice(history.length - max);
             }
 
-            localStorage.setItem(key, JSON.stringify(history));
+            const maxSize = this.options.logToLocalStorageSize || 10000;
+            let serialized = JSON.stringify(history);
+
+            while (serialized.length > maxSize && history.length > 1)
+            {
+                history.shift();
+                serialized = JSON.stringify(history);
+            }
+
+            localStorage.setItem(key, serialized);
         }
         catch (e)
         {