@ayepi/log 0.1.0

package/dist/index.js

@@ -0,0 +1,218 @@
+import { S as settleDeep, _ as partialMask, a as LOG_MAYBE, b as runWith, c as containsThenable, d as formatJson, f as formatText, g as merge, h as logMaybe, i as LOG_CONTEXT, l as createSanitizer, m as isLazy, o as UNRESOLVED, p as getContext, r as LEVELS, s as buildRecord, t as CONSOLE_LEVEL_MAP, u as deepEqual, v as resolveLog, x as serializeError, y as resolveLogValue } from "./internal.js";
+//#region src/index.ts
+/**
+* # @ayepi/log
+*
+* Structured logging with **AsyncLocalStorage trace context**. Stack context with
+* {@link logWith} and it flows through the whole async call tree (and onto thrown
+* errors); {@link log} builds a record from mixed primitive/object/Error args;
+* output goes to pluggable {@link Transport}s (console here, file via
+* `@ayepi/log/file`); console.* can be intercepted (opt-in).
+*
+* ```ts
+* import { createLogger } from '@ayepi/log'
+* const log = createLogger({ level: 'debug' })
+*
+* log.logWith({ reqId: 'abc' }, async () => {
+*   log.info('handling', { userId: 'u1' }) // → reqId + userId on the record
+*   await work()                            // a rejection here is tagged with { reqId, userId }
+* })
+* ```
+*
+* Bare `import` has **no side effects** — console interception is opt-in.
+*
+* @module
+*/
+const noopConsole = {
+	log() {},
+	info() {},
+	debug() {},
+	warn() {},
+	error() {}
+};
+const globalConsole = () => globalThis.console ?? noopConsole;
+const defaultMethod = (level) => level === "error" ? "error" : level === "warn" ? "warn" : level === "debug" ? "debug" : "log";
+/** A {@link Transport} that writes the formatted line to a console. */
+function consoleTransport(opts = {}) {
+	const target = opts.console ?? globalConsole();
+	const pick = opts.method ?? defaultMethod;
+	return {
+		name: "console",
+		write(record, text) {
+			target[pick(record.level)](text);
+		}
+	};
+}
+/** Capture the current console methods (bound) so the transport + restore use the originals. */
+function captureConsole(c) {
+	return {
+		log: c.log.bind(c),
+		info: c.info.bind(c),
+		debug: c.debug.bind(c),
+		warn: c.warn.bind(c),
+		error: c.error.bind(c)
+	};
+}
+/**
+* Create a {@link Logger}.
+*/
+function createLogger(config = {}) {
+	let level = config.level ?? "info";
+	const structured = config.structured ?? false;
+	const timestamp = config.timestamp ?? "iso";
+	const now = config.now ?? (() => Date.now());
+	const errorCfg = config.error ?? {};
+	const consoleMap = config.consoleMap ?? CONSOLE_LEVEL_MAP;
+	const targetConsole = config.console ?? globalConsole();
+	const originals = captureConsole(targetConsole);
+	let transports = config.transports ?? [consoleTransport({ console: originals })];
+	let intercepting = false;
+	let writing = false;
+	const report = (err) => {
+		try {
+			config.onError?.(err);
+		} catch {}
+	};
+	const sanitize = config.sanitize ? createSanitizer(config.sanitize) : void 0;
+	const resolveOpts = {
+		onError: report,
+		serializers: config.serializers
+	};
+	/** Build → filter → sanitize → format → write a record from already-resolved args. */
+	const deliver = (lvl, args) => {
+		let record;
+		let text;
+		try {
+			record = buildRecord(lvl, args, {
+				now,
+				timestamp,
+				error: errorCfg
+			});
+			if (config.filter) {
+				const filtered = config.filter(record);
+				if (!filtered) return;
+				record = filtered;
+			}
+			if (sanitize) {
+				const cleaned = sanitize(record);
+				if (!cleaned) return;
+				record = cleaned;
+			}
+			text = structured ? formatJson(record) : formatText(record);
+		} catch (err) {
+			report(err);
+			return;
+		}
+		writing = true;
+		try {
+			for (const t of transports) try {
+				t.write(record, text);
+			} catch (err) {
+				report(err);
+			}
+		} finally {
+			writing = false;
+		}
+	};
+	/** Produce a {@link logMaybe}'s value for this level (only now that we know we'll log), or pass through. */
+	const seedArg = (raw, lvl) => {
+		if (!isLazy(raw)) return raw;
+		try {
+			return raw[LOG_MAYBE](lvl);
+		} catch (err) {
+			report(err);
+			return UNRESOLVED;
+		}
+	};
+	const emit = (lvl, args) => {
+		if (LEVELS[lvl] < LEVELS[level] || writing) return;
+		let resolved;
+		try {
+			resolved = args.map((raw) => resolveLog(seedArg(raw, lvl), "", /* @__PURE__ */ new WeakSet(), resolveOpts));
+		} catch (err) {
+			report(err);
+			return;
+		}
+		if (resolved.some((v) => containsThenable(v))) settleDeep(resolved).then((settled) => deliver(lvl, settled)).catch(report);
+		else deliver(lvl, resolved);
+	};
+	let installed = [];
+	const restore = () => {
+		if (!intercepting) return;
+		intercepting = false;
+		const c = targetConsole;
+		for (const { method, original } of installed) c[method] = original;
+		installed = [];
+	};
+	const install = () => {
+		if (intercepting) return restore;
+		intercepting = true;
+		const c = targetConsole;
+		installed = [];
+		for (const method of Object.keys(consoleMap)) {
+			const lvl = consoleMap[method];
+			installed.push({
+				method,
+				original: c[method]
+			});
+			c[method] = (...args) => emit(lvl, args);
+		}
+		return restore;
+	};
+	/** Run `op` over every transport in parallel, awaiting all and reporting (never throwing) failures. */
+	const drain = (op) => Promise.all(transports.map(async (t) => {
+		try {
+			await op(t);
+		} catch (err) {
+			report(err);
+		}
+	})).then(() => void 0);
+	const logger = {
+		log: (lvl, ...args) => emit(lvl, args),
+		debug: (...args) => emit("debug", args),
+		info: (...args) => emit("info", args),
+		warn: (...args) => emit("warn", args),
+		error: (...args) => emit("error", args),
+		logWith: (add, inner) => runWith(add, inner),
+		context: () => Object.freeze({ ...getContext() }),
+		setTransports: (t) => {
+			transports = t;
+		},
+		setLevel: (l) => {
+			level = l;
+		},
+		isLevelEnabled: (l) => LEVELS[l] >= LEVELS[level],
+		flush: () => drain((t) => t.flush?.()),
+		close: () => drain((t) => t.close?.()),
+		config: {
+			get level() {
+				return level;
+			},
+			structured,
+			timestamp
+		},
+		interceptConsole: install,
+		restoreConsole: restore
+	};
+	if (config.interceptConsole ?? false) install();
+	return logger;
+}
+const instance = createLogger();
+/** Emit a record at `level` on the default logger. */
+const log = (level, ...args) => instance.log(level, ...args);
+const debug = (...args) => instance.debug(...args);
+const info = (...args) => instance.info(...args);
+const warn = (...args) => instance.warn(...args);
+const error = (...args) => instance.error(...args);
+/** Stack trace context on the default logger (and tag promise rejections). */
+const logWith = (add, inner) => instance.logWith(add, inner);
+/** The default logger's current trace context. */
+const context = () => instance.context();
+/** Intercept `console.*` through the default logger; returns a restore function. */
+const interceptConsole = () => instance.interceptConsole();
+/** Restore console interception installed by the default logger. */
+const restoreConsole = () => instance.restoreConsole();
+/** The default logger instance. */
+const logger = instance;
+//#endregion
+export { LOG_CONTEXT, consoleTransport, context, createLogger, createSanitizer, debug, deepEqual, error, getContext, info, interceptConsole, log, logMaybe, logWith, logger, merge, partialMask, resolveLogValue, restoreConsole, serializeError, warn };