feat: Log file header

Author: samestrin

examples/log-to-file-and-suppress-console.js

@@ -0,0 +1,21 @@
+const ACL = require("../index");
+
+// Create an ACL instance with file logging and suppressed console logs
+const logger = new ACL({
+	logLevel: 0, // Suppress console logs
+	outputFilename: "app.log", // Specify the file to save logs
+	outputFilenameLogLevel: 1, // Log all levels to file
+	includeTimestamps: true, // Include timestamps in the logs
+	includeCallerInfo: false, // Optional: disable caller info if not needed
+	includeMemoryUsage: false, // Optional: disable memory usage if not needed
+});
+
+// Use the logger as usual
+logger.debug("This is a debug message");
+logger.log("This is a regular message");
+logger.info("This is an info message");
+logger.warn("This is a warning message");
+logger.error("This is an error message");
+logger.fatal("This is a fatal message");
+
+// The above messages will be saved in `app.log` but will not be displayed in the console.

src/acl.js

@@ -129,7 +129,13 @@ class ACL {
 		};
 		this.memoryUsage = "";
 		this.cwd = process.cwd();
+
 		this.currentFileName = __filename.replace(this.cwd, "").replace(/^\//, "");
+
+		// Call the method to write the header if outputFilename is defined
+		if (this.outputFilename) {
+			this.writeHeader();
+		}
 	}
 
 	/**
@@ -157,6 +163,38 @@ class ACL {
 		return ACL.instance;
 	}
 
+	/**
+	 * Writes a custom header to the log file at the start of every new run.
+	 *
+	 * The header includes the current file name (`this.currentFileName`) and a timestamp
+	 * in the format defined by `this.timestampFormat`. It also inserts a separator line
+	 * (`-----------------------------`) for better visual distinction of log sessions.
+	 *
+	 * Example Header Format:
+	 * ```
+	 * /path/to/currentFile.js (YYYY-MM-DD HH:mm:ss.SSS):
+	 * -----------------------------
+	 * ```
+	 *
+	 * This method is called automatically during initialization if `outputFilename` is defined.
+	 * If the file cannot be written, an error message is printed to `stderr`.
+	 *
+	 * @throws {Error} If writing to the log file fails, logs an error message to `stderr`.
+	 */
+	writeHeader() {
+		const scriptName = require.main ? require.main.filename : process.argv[1];
+		const header = `\n${ACL.getCurrentTimestamp(
+			"MM-DD-YYYY HH:mm:ss.SSS"
+		)} ${scriptName}\n\n`;
+		try {
+			fs.appendFileSync(this.outputFilename, header, "utf8");
+		} catch (err) {
+			process.stderr.write(
+				`Failed to write header to log file: ${err.message}\n`
+			);
+		}
+	}
+
 	/**
 	 * Get the current timestamp formatted according to the given pattern.
 	 * Supported patterns: YYYY, MM, DD, HH, mm, ss, SSS
@@ -234,17 +272,14 @@ class ACL {
 	 * @returns {boolean} - Whether to log to console.
 	 */
 	shouldLogToConsole(condition, level) {
-		console.log(this.logLevel, condition, level);
 		if (
 			this.logLevel === 0 ||
 			(typeof condition === "boolean" && !condition) ||
 			(this.logLevel === 2 && level < 2) ||
 			(this.logLevel === 3 && level < 3)
 		) {
-			console.log("shouldLogToConsole", "false");
 			return false;
 		}
-		console.log("shouldLogToConsole", "true");
 		return true;
 	}