@warlock.js/logger 5.30.0 → 5.32.0

package/cjs/index.cjs

@@ -20,7 +20,7 @@ var __copyProps = (to, from, except, desc) => {
 	}
 	return to;
 };
-var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule || !__hasOwnProp.call(mod, "default") ? __defProp(target, "default", {
 	value: mod,
 	enumerable: true
 }) : target, mod));
@@ -56,6 +56,28 @@ var LogChannel = class {
 		}, 0);
 	}
 	/**
+	* Route this channel's own failures (those outside a `log()` call) to the
+	* given reporter. `Logger` calls this when the channel is added, so the
+	* failures reach `log.onChannelError(...)`.
+	*/
+	setErrorReporter(reporter) {
+		this.errorReporter = reporter;
+	}
+	/**
+	* Report a failure that happened outside a `log()` call. Never throws:
+	* without a reporter it writes one line to stderr.
+	*/
+	reportError(error, entry) {
+		try {
+			if (this.errorReporter) {
+				this.errorReporter(error, entry);
+				return;
+			}
+			const reason = error instanceof Error ? error.message : String(error);
+			process.stderr.write(`[@warlock.js/logger] channel "${this.name}" failed: ${reason}\n`);
+		} catch {}
+	}
+	/**
 	* Get config value
 	*/
 	config(key) {
@@ -194,8 +216,54 @@ var ConsoleLog = class extends LogChannel {
 	}
 };
 
+//#endregion
+//#region ../../packages/logger/src/channels/file-name-pattern.ts
+const TOKEN = /\{(YYYY|MM|DD|HH|mm|name)\}/g;
+const pad = (value) => String(value).padStart(2, "0");
+const escapeRegExp = (text) => text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+/**
+* Render a file name option for the given date.
+*/
+function renderFileName(option, date, name) {
+	if (typeof option === "function") return option(date);
+	return option.replace(TOKEN, (_match, token) => {
+		switch (token) {
+			case "YYYY": return String(date.getFullYear());
+			case "MM": return pad(date.getMonth() + 1);
+			case "DD": return pad(date.getDate());
+			case "HH": return pad(date.getHours());
+			case "mm": return pad(date.getMinutes());
+			default: return name;
+		}
+	});
+}
+/**
+* Regular-expression source matching every name a pattern string can render:
+* literal text is escaped, date tokens become digit runs and `{name}` the
+* escaped channel name. The source is not anchored.
+*/
+function fileNamePatternSource(pattern, name) {
+	let source = "";
+	let lastIndex = 0;
+	for (const match of pattern.matchAll(TOKEN)) {
+		const index = match.index ?? 0;
+		const token = match[1];
+		source += escapeRegExp(pattern.slice(lastIndex, index));
+		source += token === "YYYY" ? "\\d{4}" : token === "name" ? escapeRegExp(name) : "\\d{2}";
+		lastIndex = index + match[0].length;
+	}
+	return source + escapeRegExp(pattern.slice(lastIndex));
+}
+
 //#endregion
 //#region ../../packages/logger/src/channels/file-log.ts
+/** Default file name of a `daily` chunk: sortable ISO date. */
+const DAILY_FILE_NAME = "{YYYY}-{MM}-{DD}";
+/** Default file name of an `hourly` chunk: sortable ISO date and hour. */
+const HOURLY_FILE_NAME = "{YYYY}-{MM}-{DD}-{HH}";
+/** Default date part of a size-rotated file's name. */
+const ROTATE_FILE_NAME = "{YYYY}-{MM}-{DD}";
+const DAY_MS = 864e5;
 var FileLog = class extends LogChannel {
 	constructor(..._args) {
 		super(..._args);
@@ -210,10 +278,8 @@ var FileLog = class extends LogChannel {
 			chunk: "single",
 			maxMessagesToWrite: 100,
 			filter: () => true,
-			maxFileSize: 10 * 1024 * 1024,
-			get rotateFileName() {
-				return (0, dayjs.default)().format("DD-MM-YYYY");
-			},
+			maxFileSize: 10485760,
+			rotateFileName: ROTATE_FILE_NAME,
 			dateFormat: {
 				date: "DD-MM-YYYY",
 				time: "HH:mm:ss"
@@ -221,6 +287,15 @@ var FileLog = class extends LogChannel {
 		};
 		this.lastWriteTime = Date.now();
 		this.isWriting = false;
+		this.retentionDue = false;
+		this.missingMatchReported = false;
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	setConfigurations(configurations) {
+		assertRetention(configurations.retention);
+		return super.setConfigurations(configurations);
 	}
 	/**
 	* Check file size for file rotation
@@ -228,19 +303,24 @@ var FileLog = class extends LogChannel {
 	async checkAndRotateFile(filePath = this.filePath) {
 		if (!this.config("rotate")) return;
 		try {
-			if ((await fs.default.promises.stat(filePath)).size >= this.config("maxFileSize")) await this.rotateLogFile();
+			if ((await fs.default.promises.stat(filePath)).size >= this.config("maxFileSize")) await this.rotateLogFile(filePath);
 		} catch (error) {
 			if (error.code !== "ENOENT") console.error("Error checking log file:", error);
 		}
 	}
 	/**
-	* Rotate log file
+	* Rotate the given log file (the active one by default) aside as
+	* `<file name>-<rotateFileName>-<epoch ms>.<extension>` in its directory.
 	*/
-	async rotateLogFile() {
-		const fileName = `${this.fileName}-${this.config("rotateFileName")}-${Date.now()}`;
+	async rotateLogFile(filePath = this.filePath) {
+		const now = /* @__PURE__ */ new Date();
 		const extension = this.extension;
-		const rotatedFilePath = path.default.join(this.storagePath, `${fileName}.${extension}`);
-		await fs.default.promises.rename(this.filePath, rotatedFilePath).catch((error) => {
+		const baseName = path.default.basename(filePath, `.${extension}`);
+		const rotateName = renderFileName(this.config("rotateFileName") ?? "{YYYY}-{MM}-{DD}", now, this.baseName);
+		const rotatedFilePath = path.default.join(path.default.dirname(filePath), `${baseName}-${rotateName}-${now.getTime()}.${extension}`);
+		await fs.default.promises.rename(filePath, rotatedFilePath).then(() => {
+			this.retentionDue = true;
+		}, (error) => {
 			console.error("Error rotating file:", error);
 		});
 	}
@@ -286,17 +366,32 @@ var FileLog = class extends LogChannel {
 		return this.config("maxMessagesToWrite");
 	}
 	/**
-	* Get file name
+	* The configured `name` option.
 	*/
-	get fileName() {
+	get baseName() {
+		return this.config("name") ?? "app";
+	}
+	/**
+	* The `fileName` option, or the chunk's default. `undefined` means the
+	* plain `name` of a `single` chunk, used as is (braces included).
+	*/
+	get fileNamePattern() {
+		const configured = this.config("fileName");
+		if (configured !== void 0) return configured;
 		switch (this.config("chunk")) {
-			case "single":
-			default: return this.config("name");
-			case "daily": return (0, dayjs.default)().format("DD-MM-YYYY");
-			case "hourly": return (0, dayjs.default)().format("DD-MM-YYYY-HH-00-00-a");
+			case "daily": return DAILY_FILE_NAME;
+			case "hourly": return HOURLY_FILE_NAME;
+			default: return;
 		}
 	}
 	/**
+	* Current file name, without extension
+	*/
+	get fileName() {
+		const pattern = this.fileNamePattern;
+		return pattern === void 0 ? this.baseName : renderFileName(pattern, /* @__PURE__ */ new Date(), this.baseName);
+	}
+	/**
 	* Get file extension
 	*/
 	get extension() {
@@ -321,6 +416,138 @@ var FileLog = class extends LogChannel {
 		const logsDirectory = this.storagePath;
 		await (0, _warlock_js_fs.ensureDirectoryAsync)(logsDirectory);
 		this.initMessageFlush();
+		await this.prune();
+	}
+	/**
+	* Remove old log files as configured by `retention`. Runs on boot and
+	* whenever a new file is started; call it yourself to prune on demand.
+	* Never rejects: failures go to the channel error handler.
+	*/
+	prune() {
+		const run = (this.pruning ?? Promise.resolve()).then(() => this.pruneFiles());
+		this.pruning = run;
+		return run;
+	}
+	/**
+	* Prune once a write started a new file: after a size rotation, or when a
+	* dated file name rolled over. Never throws.
+	*/
+	async afterWrite() {
+		let fileName;
+		try {
+			fileName = this.fileName;
+		} catch {
+			return;
+		}
+		const rolledOver = this.lastFileName !== void 0 && this.lastFileName !== fileName;
+		this.lastFileName = fileName;
+		if (!rolledOver && !this.retentionDue) return;
+		this.retentionDue = false;
+		await this.prune();
+	}
+	/**
+	* Apply `retention` to every directory this channel writes to.
+	*/
+	async pruneFiles() {
+		const retention = this.config("retention");
+		if (!retention || retention.maxFiles === void 0 && retention.maxAgeDays === void 0) return;
+		try {
+			const matcher = this.retentionMatcher(retention);
+			if (!matcher) return;
+			const activeFile = `${this.fileName}.${this.extension}`;
+			for (const directory of await this.retentionDirectories()) await this.pruneDirectory(directory, matcher, retention, activeFile);
+		} catch (error) {
+			this.reportRetentionError(error, this.storagePath);
+		}
+	}
+	/**
+	* The expression a file name must match to be pruned, or `undefined` when
+	* none can be derived (a function `fileName` without `retention.match`).
+	*/
+	retentionMatcher(retention) {
+		if (retention.match) return new RegExp(retention.match.source, retention.match.flags.replace(/[gy]/g, ""));
+		const pattern = this.fileNamePattern;
+		if (typeof pattern === "function") {
+			if (!this.missingMatchReported) {
+				this.missingMatchReported = true;
+				this.reportRetentionError(/* @__PURE__ */ new Error("FileLog retention needs `retention.match` when `fileName` is a function; no files were pruned"), this.storagePath);
+			}
+			return;
+		}
+		const name = this.baseName;
+		const fileSource = pattern === void 0 ? escapeRegExp(name) : fileNamePatternSource(pattern, name);
+		const rotateName = this.config("rotateFileName") ?? "{YYYY}-{MM}-{DD}";
+		const rotateSource = typeof rotateName === "function" ? ".+" : fileNamePatternSource(rotateName, name);
+		return new RegExp(`^${fileSource}(?:-${rotateSource}-\\d{13,})?\\.${escapeRegExp(this.extension)}$`);
+	}
+	/**
+	* The log directory, or each group directory when `groupBy` is set.
+	*/
+	async retentionDirectories() {
+		let directories = [this.storagePath];
+		const depth = this.config("groupBy")?.length ?? 0;
+		for (let level = 0; level < depth; level++) {
+			const next = [];
+			for (const directory of directories) {
+				const entries = await fs.default.promises.readdir(directory, { withFileTypes: true }).catch((error) => {
+					if (error.code !== "ENOENT") this.reportRetentionError(error, directory);
+					return [];
+				});
+				for (const entry of entries) if (entry.isDirectory()) next.push(path.default.join(directory, entry.name));
+			}
+			directories = next;
+		}
+		return directories;
+	}
+	/**
+	* Remove the matching files of one directory that `retention` no longer
+	* keeps. Each failure is reported and the rest still run.
+	*/
+	async pruneDirectory(directory, matcher, retention, activeFile) {
+		let names;
+		try {
+			names = await fs.default.promises.readdir(directory);
+		} catch (error) {
+			if (error.code !== "ENOENT") this.reportRetentionError(error, directory);
+			return;
+		}
+		const candidates = [];
+		for (const name of names) {
+			if (name === activeFile || !matcher.test(name)) continue;
+			const filePath = path.default.join(directory, name);
+			try {
+				const stats = await fs.default.promises.stat(filePath);
+				if (stats.isFile()) candidates.push({
+					filePath,
+					name,
+					modifiedAt: stats.mtimeMs
+				});
+			} catch (error) {
+				if (error.code !== "ENOENT") this.reportRetentionError(error, filePath);
+			}
+		}
+		candidates.sort((a, b) => b.modifiedAt - a.modifiedAt || (a.name < b.name ? 1 : -1));
+		const keep = retention.maxFiles === void 0 ? Infinity : retention.maxFiles - (names.includes(activeFile) ? 1 : 0);
+		const oldestKept = retention.maxAgeDays === void 0 ? -Infinity : Date.now() - retention.maxAgeDays * DAY_MS;
+		for (const [index, candidate] of candidates.entries()) {
+			if (index < keep && candidate.modifiedAt >= oldestKept) continue;
+			try {
+				await fs.default.promises.unlink(candidate.filePath);
+			} catch (error) {
+				if (error.code !== "ENOENT") this.reportRetentionError(error, candidate.filePath);
+			}
+		}
+	}
+	/**
+	* Send a retention failure to the channel error handler.
+	*/
+	reportRetentionError(error, target) {
+		this.reportError(error, {
+			type: "error",
+			module: "logger",
+			action: "retention",
+			message: `Log retention failed for ${target}`
+		});
 	}
 	/**
 	* Synchronously flush messages
@@ -412,14 +639,17 @@ var FileLog = class extends LogChannel {
 		if (this.messages.length === 0 || this.isWriting || !this.isInitialized) return;
 		this.isWriting = true;
 		if (this.messagedShouldBeGrouped) return await this.writeGroupedMessagesToFile();
-		await this.checkAndRotateFile();
 		try {
-			await this.write(this.filePath, this.content);
+			const filePath = this.filePath;
+			await this.checkAndRotateFile(filePath);
+			await this.write(filePath, this.content);
 			this.onSave();
 		} catch (error) {
 			console.error("Failed to write log:", error);
 			this.isWriting = false;
+			return;
 		}
+		await this.afterWrite();
 	}
 	/**
 	* Write grouped messages to the file
@@ -428,11 +658,11 @@ var FileLog = class extends LogChannel {
 		this.prepareGroupedMessages();
 		for (const [key, groupMessages] of Object.entries(this.groupedMessages)) {
 			const directoryPath = path.default.join(this.storagePath, key);
-			await (0, _warlock_js_fs.ensureDirectoryAsync)(directoryPath);
-			const filePath = path.default.join(directoryPath, `${this.fileName}.${this.extension}`);
-			await this.checkAndRotateFile(filePath);
-			const content = groupMessages.map((message) => message.content).join(os.EOL) + os.EOL;
 			try {
+				await (0, _warlock_js_fs.ensureDirectoryAsync)(directoryPath);
+				const filePath = path.default.join(directoryPath, `${this.fileName}.${this.extension}`);
+				await this.checkAndRotateFile(filePath);
+				const content = groupMessages.map((message) => message.content).join(os.EOL) + os.EOL;
 				await this.write(filePath, content);
 			} catch (error) {
 				console.error("Failed to write log:", error);
@@ -440,6 +670,7 @@ var FileLog = class extends LogChannel {
 		}
 		this.onSave();
 		this.isWriting = false;
+		await this.afterWrite();
 	}
 	/**
 	* Prepare grouped messages
@@ -465,6 +696,16 @@ var FileLog = class extends LogChannel {
 		});
 	}
 };
+/**
+* Reject a `retention` that could never keep or remove anything sensibly.
+*/
+function assertRetention(retention) {
+	if (!retention) return;
+	const { maxFiles, maxAgeDays, match } = retention;
+	if (maxFiles !== void 0 && (!Number.isInteger(maxFiles) || maxFiles < 1)) throw new TypeError("FileLog retention.maxFiles must be a positive integer");
+	if (maxAgeDays !== void 0 && (!Number.isFinite(maxAgeDays) || maxAgeDays <= 0)) throw new TypeError("FileLog retention.maxAgeDays must be a positive number");
+	if (match !== void 0 && !(match instanceof RegExp)) throw new TypeError("FileLog retention.match must be a RegExp");
+}
 
 //#endregion
 //#region ../../packages/logger/src/utils/safe-json-stringify.ts
@@ -577,10 +818,18 @@ var JSONFileLog = class extends FileLog {
 		if (this.messages.length === 0 || this.isWriting || !this.isInitialized) return;
 		this.isWriting = true;
 		if (this.messagedShouldBeGrouped) return await this.writeGroupedMessagesToFile();
-		await this.checkAndRotateFile();
+		let filePath;
+		try {
+			filePath = this.filePath;
+		} catch (error) {
+			console.error("Failed to write log:", error);
+			this.isWriting = false;
+			return;
+		}
+		await this.checkAndRotateFile(filePath);
 		let fileContents = { messages: [] };
-		if (await (0, _warlock_js_fs.fileExistsAsync)(this.filePath)) try {
-			fileContents = await (0, _warlock_js_fs.getJsonFileAsync)(this.filePath);
+		if (await (0, _warlock_js_fs.fileExistsAsync)(filePath)) try {
+			fileContents = await (0, _warlock_js_fs.getJsonFileAsync)(filePath);
 		} catch (error) {
 			console.error("Error reading log file, reinitializing:", error);
 			fileContents = { messages: [] };
@@ -588,22 +837,32 @@ var JSONFileLog = class extends FileLog {
 		else fileContents = { messages: [] };
 		fileContents.messages.push(...this.messages);
 		try {
-			await fs.default.promises.writeFile(this.filePath, safeJsonStringify(fileContents, 2));
+			await fs.default.promises.writeFile(filePath, safeJsonStringify(fileContents, 2));
 			this.onSave();
 		} catch (error) {
 			console.error("Failed to write log:", error);
 			this.isWriting = false;
+			return;
 		}
+		await this.afterWrite();
 	}
 	/**
 	* Write grouped messages to the file
 	*/
 	async writeGroupedMessagesToFile() {
+		let fileName;
+		try {
+			fileName = this.fileName;
+		} catch (error) {
+			console.error("Failed to write log:", error);
+			this.isWriting = false;
+			return;
+		}
 		this.prepareGroupedMessages();
 		for (const [key, groupMessages] of Object.entries(this.groupedMessages)) {
 			const directoryPath = path.default.join(this.storagePath, key);
 			await (0, _warlock_js_fs.ensureDirectoryAsync)(directoryPath);
-			const filePath = path.default.join(directoryPath, `${this.fileName}.${this.extension}`);
+			const filePath = path.default.join(directoryPath, `${fileName}.${this.extension}`);
 			await this.checkAndRotateFile(filePath);
 			let fileContents = { messages: [] };
 			if (await (0, _warlock_js_fs.fileExistsAsync)(filePath)) try {
@@ -622,6 +881,7 @@ var JSONFileLog = class extends FileLog {
 			}
 		}
 		this.onSave();
+		await this.afterWrite();
 	}
 };
 
@@ -1200,6 +1460,41 @@ function mergeRedact(base, extra) {
 	};
 }
 
+//#endregion
+//#region ../../packages/logger/src/redact/escape-log-value.ts
+/**
+* ANSI escape sequences: CSI (`ESC [ … final`) and the two-character
+* `ESC x` escapes (`ESC c` resets a terminal). Bounded so matching stays linear on long input.
+*/
+const ANSI_ESCAPE = /\u001b(?:\[[0-?]{0,32}[ -/]{0,8}[@-~]|[0-~])/g;
+/** Control characters that are not already handled as `\r`, `\n` or `\t`. */
+const CONTROL = /[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f-\u009f\u2028\u2029]/g;
+/**
+* Make client-controlled text safe to put inside a log line: line breaks and
+* tabs become the visible escapes `\r`, `\n`, `\t`, other control characters
+* (including NUL, DEL, C1 controls and the Unicode line/paragraph separators)
+* become `\uXXXX`, and ANSI terminal escape sequences are removed.
+*
+* Without it, a user agent or form field containing `\n2026-01-01 [info] …`
+* writes a forged entry into a text log, and an ANSI sequence can rewrite what
+* a terminal shows. Structured channels (JSON) are not affected, but console
+* and file channels are.
+*
+* @example
+* log.info("auth", "login", `Login from ${escapeLogValue(request.userAgent)}`);
+*/
+function escapeLogValue(value, options = {}) {
+	let text = typeof value === "string" ? value : String(value);
+	const maxLength = options.maxLength;
+	let truncated = false;
+	if (maxLength !== void 0 && maxLength >= 0 && text.length > maxLength) {
+		text = text.slice(0, maxLength);
+		truncated = true;
+	}
+	const escaped = text.replace(ANSI_ESCAPE, "").replace(/\r/g, "\\r").replace(/\n/g, "\\n").replace(/\t/g, "\\t").replace(CONTROL, (char) => `\\u${char.charCodeAt(0).toString(16).padStart(4, "0")}`);
+	return truncated ? `${escaped}…[truncated]` : escaped;
+}
+
 //#endregion
 //#region ../../packages/logger/src/redact/mask-email.ts
 /**
@@ -1280,7 +1575,7 @@ function clearMessage(message) {
 
 //#endregion
 //#region ../../packages/logger/src/logger.ts
-const SIGNAL_EVENTS = new Set([
+const SIGNAL_EVENTS = /* @__PURE__ */ new Set([
 	"SIGINT",
 	"SIGTERM",
 	"SIGHUP",
@@ -1314,14 +1609,14 @@ var Logger = class {
 	* Add a new channel
 	*/
 	addChannel(channel) {
-		this.channels.push(channel);
+		this.channels.push(this.attachChannel(channel));
 		return this;
 	}
 	/**
 	* Set base configurations
 	*/
 	configure(config) {
-		if (config.channels) this.channels = config.channels;
+		if (config.channels) this.setChannels(config.channels);
 		if (config.autoFlushOn) this.enableAutoFlush(config.autoFlushOn);
 		if (config.minLevel !== void 0) this.setMinLevel(config.minLevel);
 		if (config.redact !== void 0) this.setRedact(config.redact);
@@ -1388,9 +1683,18 @@ var Logger = class {
 	*/
 	setChannels(channels) {
 		this.channels = channels;
+		for (const channel of channels) this.attachChannel(channel);
 		return this;
 	}
 	/**
+	* Route a channel's own failures (outside `log()`, such as file retention)
+	* to this logger's channel error handler.
+	*/
+	attachChannel(channel) {
+		if (typeof channel.setErrorReporter === "function") channel.setErrorReporter((error, entry) => this.reportChannelError(error, channel, entry));
+		return channel;
+	}
+	/**
 	* Normalize log data to a single object
 	*/
 	normalizeLogData(dataOrModule, action, message = "", level, context) {
@@ -1779,18 +2083,22 @@ function captureAnyUnhandledRejection(options = {}) {
 
 //#endregion
 exports.ConsoleLog = ConsoleLog;
+exports.DAILY_FILE_NAME = DAILY_FILE_NAME;
 exports.DEFAULT_FLUSH_TIMEOUT_MS = DEFAULT_FLUSH_TIMEOUT_MS;
 exports.DEFAULT_REDACT_KEYS = DEFAULT_REDACT_KEYS;
 exports.DEFAULT_REDACT_KEY_SET = DEFAULT_REDACT_KEY_SET;
 exports.FileLog = FileLog;
+exports.HOURLY_FILE_NAME = HOURLY_FILE_NAME;
 exports.JSONFileLog = JSONFileLog;
 exports.LogChannel = LogChannel;
 exports.Logger = Logger;
 exports.MASK_EMAILS_MAX_LENGTH = MASK_EMAILS_MAX_LENGTH;
+exports.ROTATE_FILE_NAME = ROTATE_FILE_NAME;
 exports.SentryLog = SentryLog;
 exports.applyRedact = applyRedact;
 exports.captureAnyUnhandledRejection = captureAnyUnhandledRejection;
 exports.clearMessage = clearMessage;
+exports.escapeLogValue = escapeLogValue;
 exports.log = log;
 exports.maskEmail = maskEmail;
 exports.maskEmailsInText = maskEmailsInText;