@warlock.js/logger 4.1.15 → 4.2.0

package/cjs/index.cjs

@@ -39,7 +39,7 @@ path = __toESM(path, 1);
 let safe_stable_stringify = require("safe-stable-stringify");
 let _mongez_reinforcements = require("@mongez/reinforcements");
 
-//#region ../../@warlock.js/logger/src/log-channel.ts
+//#region ../@warlock.js/logger/src/log-channel.ts
 var LogChannel = class {
 	/**
 	* Constructor
@@ -112,7 +112,7 @@ var LogChannel = class {
 };
 
 //#endregion
-//#region ../../@warlock.js/logger/src/channels/console-log.ts
+//#region ../@warlock.js/logger/src/channels/console-log.ts
 var ConsoleLog = class extends LogChannel {
 	constructor(..._args) {
 		super(..._args);
@@ -142,6 +142,9 @@ var ConsoleLog = class extends LogChannel {
 			case "success":
 				console.log(_mongez_copper.colors.green("✓"), _mongez_copper.colors.yellow(`(${date})`), _mongez_copper.colors.cyan(`[${module}]`), _mongez_copper.colors.magenta(`[${action}]`), _mongez_copper.colors.greenBright(message));
 				break;
+			case "fatal":
+				console.log(_mongez_copper.colors.bgRedBright(_mongez_copper.colors.bold(" ☠ ")), _mongez_copper.colors.yellow(`(${date})`), _mongez_copper.colors.cyan(`[${module}]`), _mongez_copper.colors.magenta(`[${action}]`), _mongez_copper.colors.redBright.bold(message));
+				break;
 			default: console.log("[log]", _mongez_copper.colors.yellow(`(${date})`), _mongez_copper.colors.cyan(`[${module}]`), _mongez_copper.colors.magenta(`[${action}]`), message);
 		}
 		if (typeof message === "object") console.log(message);
@@ -157,7 +160,7 @@ var ConsoleLog = class extends LogChannel {
 };
 
 //#endregion
-//#region ../../@warlock.js/logger/src/channels/file-log.ts
+//#region ../@warlock.js/logger/src/channels/file-log.ts
 var FileLog = class extends LogChannel {
 	constructor(..._args) {
 		super(..._args);
@@ -305,6 +308,20 @@ var FileLog = class extends LogChannel {
 		this.onSave();
 	}
 	/**
+	* Asynchronously drain buffered entries to disk.
+	*
+	* The async analogue of {@link flushSync}: it reuses the same async writer
+	* as the background interval, so a caller on a graceful-shutdown path can
+	* `await channel.flush()` (or `await log.flush()`) and rely on the buffer
+	* being on disk once it resolves. `JSONFileLog` inherits this unchanged —
+	* its overridden `writeMessagesToFile` performs the JSON merge.
+	*/
+	async flush() {
+		if (this.messages.length === 0 && Object.keys(this.groupedMessages).length === 0) return;
+		this.isWriting = false;
+		await this.writeMessagesToFile();
+	}
+	/**
 	* {@inheritdoc}
 	*/
 	async log(data) {
@@ -415,7 +432,7 @@ var FileLog = class extends LogChannel {
 };
 
 //#endregion
-//#region ../../@warlock.js/logger/src/utils/safe-json-stringify.ts
+//#region ../@warlock.js/logger/src/utils/safe-json-stringify.ts
 /**
 * Replacer that surfaces Error data — `name`, `message`, and `stack` are
 * non-enumerable on `Error`, so neither default JSON serialization nor an
@@ -446,7 +463,7 @@ function safeJsonStringify(value, space) {
 }
 
 //#endregion
-//#region ../../@warlock.js/logger/src/channels/json-file-log.ts
+//#region ../@warlock.js/logger/src/channels/json-file-log.ts
 var JSONFileLog = class extends FileLog {
 	constructor(..._args) {
 		super(..._args);
@@ -574,7 +591,204 @@ var JSONFileLog = class extends FileLog {
 };
 
 //#endregion
-//#region ../../@warlock.js/logger/src/redact/redact.ts
+//#region ../@warlock.js/logger/src/channels/sentry-log.ts
+let Sentry;
+let isModuleExists = null;
+let loadingPromise;
+const SENTRY_INSTALL_INSTRUCTIONS = `
+The Sentry log channel requires the @sentry/node package.
+Install it with:
+
+  npm install @sentry/node
+
+Or with your preferred package manager:
+
+  pnpm add @sentry/node
+  yarn add @sentry/node
+`.trim();
+/**
+* Load @sentry/node once, lazily and concurrency-safely. A bare catch maps any
+* import failure to "not installed" — the curated install message surfaces at
+* `log()` time, never as a boot-time module-resolution crash.
+*/
+function loadSentry() {
+	if (isModuleExists !== null) return Promise.resolve();
+	if (loadingPromise) return loadingPromise;
+	loadingPromise = (async () => {
+		try {
+			Sentry = await import("@sentry/node");
+			isModuleExists = true;
+		} catch {
+			isModuleExists = false;
+		}
+	})();
+	return loadingPromise;
+}
+/**
+* Forwards log entries to Sentry.
+*
+* Entries at an `eventLevels` level (`error` / `warn` by default) become Sentry
+* **events**: an `Error` message via `captureException` (preserving the real
+* stack), any other message via `captureMessage`. Every other level becomes a
+* **breadcrumb** — buffered and attached to the next event, consuming no error
+* quota. `module` / `action` are attached as searchable tags and the entry's
+* `context` as a structured Sentry context.
+*
+* The SDK is an optional peer: pass an existing `client` (reused as-is) or
+* `options` (the channel lazily imports `@sentry/node` and initializes it). On
+* graceful shutdown, `await log.flush()` drains pending events via
+* `Sentry.flush(timeout)`.
+*
+* @example
+* // Existing app — reuse the initialized Sentry client
+* import * as Sentry from "@sentry/node";
+* log.addChannel(new SentryLog({ client: Sentry }));
+*
+* @example
+* // New app — let the channel initialize Sentry
+* log.addChannel(new SentryLog({ options: { dsn: process.env.SENTRY_DSN } }));
+*/
+var SentryLog = class extends LogChannel {
+	/**
+	* Resolve an injected `client` (the Sentry namespace) **synchronously**, so an
+	* entry logged on the same tick as construction — e.g. at app boot, before
+	* the base schedules `init()` on the next tick via `setTimeout(0)` — is not
+	* silently dropped. The `options` (lazy-import) path is inherently async and
+	* still resolves in `init()`.
+	*/
+	constructor(configurations) {
+		super(configurations);
+		this.name = "sentry";
+		this.description = "Forwards entries to Sentry as events (error/warn) or breadcrumbs (everything else)";
+		this.defaultConfigurations = {
+			eventLevels: [
+				"fatal",
+				"error",
+				"warn"
+			],
+			flushTimeout: 2e3
+		};
+		this.warnedMissing = false;
+		const injected = this.config("client");
+		if (injected) this.sentry = injected;
+	}
+	/**
+	* Resolve the forwarder: reuse the injected client, otherwise lazily import
+	* `@sentry/node` and (only when explicit `options` are supplied and no client
+	* exists yet) initialize it. Never throws — the base runs `init()` inside an
+	* un-awaited `setTimeout`, so a throw would become an unhandled rejection and
+	* `isInitialized` would never flip; a missing SDK is reported from `log()`.
+	*/
+	async init() {
+		const injected = this.config("client");
+		if (injected) {
+			this.sentry = injected;
+			return;
+		}
+		await loadSentry();
+		if (!Sentry) return;
+		const options = this.config("options");
+		if (options && !Sentry.getClient()) Sentry.init(options);
+		this.sentry = Sentry;
+	}
+	/**
+	* {@inheritdoc}
+	*/
+	async log(data) {
+		if (!this.shouldBeLogged(data)) return;
+		if (isModuleExists === null) await loadSentry();
+		if (!this.sentry) {
+			this.reportMissingSdk();
+			return;
+		}
+		const { module, action, message, type: level, context } = data;
+		if (this.isEventLevel(level)) {
+			this.captureEvent(this.sentry, {
+				module,
+				action,
+				message,
+				level,
+				context
+			});
+			return;
+		}
+		this.sentry.addBreadcrumb({
+			category: module,
+			message: this.toText(message),
+			level: this.toSentryLevel(level),
+			data: context
+		});
+	}
+	/**
+	* Drain pending Sentry events. Bounded by `flushTimeout` so an unreachable
+	* Sentry can never hang a graceful shutdown. No-op when the SDK is absent.
+	*/
+	async flush() {
+		if (!this.sentry) return;
+		await this.sentry.flush(this.config("flushTimeout"));
+	}
+	/**
+	* Whether the level should be sent as a Sentry event (vs a breadcrumb).
+	*/
+	isEventLevel(level) {
+		return Boolean(this.config("eventLevels")?.includes(level));
+	}
+	/**
+	* Send an entry as a Sentry event. An `Error` message goes through
+	* `captureException` so Sentry parses the real stack and groups properly;
+	* any other message goes through `captureMessage`. `module` / `action` are
+	* attached as tags and `context` as a structured context, scoped to this
+	* event only via `withScope`.
+	*/
+	captureEvent(sentry, entry) {
+		const { module, action, message, level, context } = entry;
+		const sentryLevel = this.toSentryLevel(level);
+		sentry.withScope((scope) => {
+			scope.setLevel(sentryLevel);
+			scope.setTags({
+				module,
+				action
+			});
+			if (context) scope.setContext("context", context);
+			if (message instanceof Error) sentry.captureException(message);
+			else sentry.captureMessage(this.toText(message), sentryLevel);
+		});
+	}
+	/**
+	* Map a logger level to a Sentry severity. `success` has no Sentry
+	* equivalent, so it is reported as informational.
+	*/
+	toSentryLevel(level) {
+		switch (level) {
+			case "warn": return "warning";
+			case "success": return "info";
+			default: return level;
+		}
+	}
+	/**
+	* Coerce a message into the string Sentry's APIs expect — an `Error`'s
+	* `.message`, a string as-is, anything else safely JSON-serialized.
+	*/
+	toText(message) {
+		if (typeof message === "string") return message;
+		if (message instanceof Error) return message.message;
+		return safeJsonStringify(message);
+	}
+	/**
+	* Surface the install instructions exactly once when the SDK is absent. The
+	* logger can't log through itself here, so this writes to stderr — matching
+	* how the file channels report write failures.
+	*/
+	reportMissingSdk() {
+		if (isModuleExists === false && !this.warnedMissing) {
+			this.warnedMissing = true;
+			console.error(SENTRY_INSTALL_INSTRUCTIONS);
+		}
+	}
+};
+
+//#endregion
+//#region ../@warlock.js/logger/src/redact/redact.ts
 /**
 * Deep-clone a value with structural fidelity for log entries — handles plain
 * objects, arrays, `Date`, `Error`, and primitives. Anything else is copied
@@ -681,7 +895,7 @@ function mergeRedact(base, extra) {
 }
 
 //#endregion
-//#region ../../@warlock.js/logger/src/utils/clear-message.ts
+//#region ../@warlock.js/logger/src/utils/clear-message.ts
 /**
 * Clear message from any terminal codes
 */
@@ -691,7 +905,7 @@ function clearMessage(message) {
 }
 
 //#endregion
-//#region ../../@warlock.js/logger/src/logger.ts
+//#region ../@warlock.js/logger/src/logger.ts
 const SIGNAL_EVENTS = new Set([
 	"SIGINT",
 	"SIGTERM",
@@ -711,7 +925,8 @@ const LEVEL_RANK = {
 	info: 1,
 	success: 1,
 	warn: 2,
-	error: 3
+	error: 3,
+	fatal: 4
 };
 var Logger = class {
 	constructor() {
@@ -863,6 +1078,19 @@ var Logger = class {
 		return this.log(data);
 	}
 	/**
+	* Make fatal log — for unrecoverable failures where the application is going
+	* down (failed bootstrap, lost connection to a required dependency that the
+	* caller has decided not to retry, an `uncaughtException`).
+	*
+	* Identical shape to {@link error}; the level is purely informational —
+	* `fatal` does NOT auto-flush or exit. The caller decides whether to call
+	* `await log.flush()` and `process.exit(...)`.
+	*/
+	fatal(dataOrModule, action, message = "", context) {
+		const data = this.normalizeLogData(dataOrModule, action, message, "fatal", context);
+		return this.log(data);
+	}
+	/**
 	* Log an `error` entry when `condition` is falsy. No-op otherwise — the
 	* entry is never built and channels are not invoked, so this is genuinely
 	* free in the happy path. Mirrors the spirit of `console.assert` but routes
@@ -908,6 +1136,34 @@ var Logger = class {
 		for (const channel of this.channels) if (channel.flushSync) channel.flushSync();
 	}
 	/**
+	* Asynchronously drain every channel that implements `flush()`.
+	*
+	* Unlike {@link flushSync}, this awaits each channel's async I/O — the
+	* correct call for a graceful shutdown that can afford to wait
+	* (`await log.flush()` after closing the HTTP server, before
+	* `process.exit`). A channel whose delivery is async (a network transport,
+	* an async disk write) implements `flush()`, not `flushSync()`.
+	*
+	* Channels are isolated: a channel whose flush rejects can neither prevent
+	* the others from draining nor escape as an unhandled rejection. Channels
+	* without `flush()` are skipped.
+	*
+	* @example
+	* async function shutdown() {
+	*   await httpServer.close();
+	*   await log.flush();
+	*   process.exit(0);
+	* }
+	*/
+	async flush() {
+		await Promise.allSettled(this.channels.map(async (channel) => {
+			if (!channel.flush) return;
+			try {
+				await channel.flush();
+			} catch {}
+		}));
+	}
+	/**
 	* Register one process-level handler per event that calls `flushSync()`
 	* before the process terminates.
 	*
@@ -967,7 +1223,7 @@ var Logger = class {
 const log = new Logger();
 
 //#endregion
-//#region ../../@warlock.js/logger/src/utils/capture-unhandled-errors.ts
+//#region ../@warlock.js/logger/src/utils/capture-unhandled-errors.ts
 /**
 * Route Node's process-level failure events through the logger so they land in
 * every configured channel with full stack context. Registers one listener for
@@ -975,6 +1231,14 @@ const log = new Logger();
 * after channels are configured. Pair with `autoFlushOn: ["beforeExit"]` so the
 * final entry survives the process exit that follows an uncaught exception.
 *
+* Levels chosen for semantic honesty:
+*
+* - `uncaughtException` → `log.fatal` — by default Node terminates the process,
+*   so the failure is unrecoverable.
+* - `unhandledRejection` → `log.error` — a rejected promise is a failure, but
+*   not necessarily process-ending (depends on Node's `--unhandled-rejections`
+*   policy and your app's recovery), so it stays at error.
+*
 * @example
 * log.configure({ channels: [new ConsoleLog(), new FileLog()] });
 * captureAnyUnhandledRejection();
@@ -984,7 +1248,7 @@ function captureAnyUnhandledRejection() {
 		log.error("app", "unhandledRejection", reason);
 	});
 	process.on("uncaughtException", (error) => {
-		log.error("app", "uncaughtException", error);
+		log.fatal("app", "uncaughtException", error);
 	});
 }
 
@@ -994,6 +1258,7 @@ exports.FileLog = FileLog;
 exports.JSONFileLog = JSONFileLog;
 exports.LogChannel = LogChannel;
 exports.Logger = Logger;
+exports.SentryLog = SentryLog;
 exports.applyRedact = applyRedact;
 exports.captureAnyUnhandledRejection = captureAnyUnhandledRejection;
 exports.clearMessage = clearMessage;