@ayepi/log 0.1.0

package/dist/internal.cjs

@@ -0,0 +1,546 @@
+let node_async_hooks = require("node:async_hooks");
+//#region src/internal.ts
+/**
+* # @ayepi/log internals
+*
+* Shared, dependency-free building blocks used by every entry: the level table,
+* the collision-renaming context {@link merge}, {@link deepEqual}, error
+* serialization, the {@link AsyncLocalStorage}-backed trace context + {@link runWith}
+* (the `logWith` core), record building, and formatting.
+*
+* @module
+*/
+/** Severity ordering — lower = more verbose. The threshold emits levels `>=` it. */
+const LEVELS = {
+	debug: 10,
+	info: 20,
+	warn: 30,
+	error: 40
+};
+/** Default threshold. */
+const DEFAULT_LEVEL = "info";
+/** Give up suffixing after this many collisions (guards pathological loops). The first suffix is `key2`. */
+const SUFFIX_MAX = 100;
+/** Default `console` method → level mapping for interception (the logging-output methods). */
+const CONSOLE_LEVEL_MAP = {
+	log: "info",
+	info: "info",
+	debug: "debug",
+	warn: "warn",
+	error: "error",
+	trace: "debug",
+	dir: "info"
+};
+/** Default `cause` recursion depth for error serialization. */
+const DEFAULT_MAX_CAUSE_DEPTH = 5;
+/** Symbol under which `logWith` stashes the full merged context onto a rejected error. `Symbol.for` → stable across bundled entries. */
+const LOG_CONTEXT = Symbol.for("@ayepi/log:ctx");
+/** Placeholder substituted for a value whose resolution (a `toLOG`/`toJSON` hook, a `logMaybe`, a promise) threw or rejected. */
+const UNRESOLVED = "(unresolved value)";
+/** Recursive structural equality. Handles primitives, `Date`, arrays, `Error`, plain objects, and cycles. */
+function deepEqual(a, b, seen = /* @__PURE__ */ new WeakMap()) {
+	if (Object.is(a, b)) return true;
+	if (typeof a !== typeof b || a === null || b === null || typeof a !== "object") return false;
+	const ao = a;
+	const bo = b;
+	if (seen.get(ao) === bo) return true;
+	seen.set(ao, bo);
+	if (a instanceof Date || b instanceof Date) return a instanceof Date && b instanceof Date && a.getTime() === b.getTime();
+	if (Array.isArray(a) || Array.isArray(b)) {
+		if (!Array.isArray(a) || !Array.isArray(b) || a.length !== b.length) return false;
+		return a.every((x, i) => deepEqual(x, b[i], seen));
+	}
+	if (a instanceof Error || b instanceof Error) return a instanceof Error && b instanceof Error && a.name === b.name && a.message === b.message;
+	const ar = a;
+	const br = b;
+	const ak = Object.keys(ar);
+	if (ak.length !== Object.keys(br).length) return false;
+	return ak.every((k) => k in br && deepEqual(ar[k], br[k], seen));
+}
+/**
+* Merge `b` into `a` immutably. `a` keeps all of its own keys; each key of `b` is
+* placed in the first slot among `key, key2, key3, …` that is free **or** already
+* deep-equals `b`'s value (dedup). Returns a **new** object — neither input is
+* mutated.
+*/
+function merge(a, b) {
+	const result = { ...a };
+	for (const key of Object.keys(b)) {
+		const v = b[key];
+		let placed = false;
+		for (let i = 1; i <= SUFFIX_MAX; i++) {
+			const slot = i === 1 ? key : `${key}${i}`;
+			if (!(slot in result)) {
+				result[slot] = v;
+				placed = true;
+				break;
+			}
+			if (deepEqual(result[slot], v)) {
+				placed = true;
+				break;
+			}
+		}
+		if (!placed) result[`${key}${SUFFIX_MAX}_overflow`] = v;
+	}
+	return result;
+}
+/** Serialize `err` per `cfg` (stack/cause/fields, depth-bounded). Non-`Error` values become `{ name:'NonError', message }`. */
+function serializeError(err, cfg = {}, depth = 0) {
+	if (!(err instanceof Error)) return {
+		name: "NonError",
+		message: typeof err === "string" ? err : safeString(err)
+	};
+	const out = {
+		name: err.name,
+		message: err.message
+	};
+	if (cfg.stack !== false && err.stack) out.stack = err.stack;
+	const cause = err.cause;
+	if (cfg.cause !== false && cause !== void 0 && depth < (cfg.maxCauseDepth ?? DEFAULT_MAX_CAUSE_DEPTH)) out.cause = cause instanceof Error ? serializeError(cause, cfg, depth + 1) : cause;
+	if (cfg.fields !== false) {
+		const rec = err;
+		for (const k of Object.keys(err)) {
+			if (k === "name" || k === "message" || k === "stack" || k === "cause") continue;
+			out[k] = rec[k];
+		}
+	}
+	return out;
+}
+function safeString(v) {
+	try {
+		return String(v);
+	} catch {
+		return "[unstringifiable]";
+	}
+}
+const store = new node_async_hooks.AsyncLocalStorage();
+/** The current merged `logWith` context (empty object outside any `logWith`). */
+const getContext = () => store.getStore() ?? {};
+/** Attach the full context to a rejected error under {@link LOG_CONTEXT} — only if not already present (innermost wins). */
+function attachContext(err, ctx) {
+	if (err !== null && typeof err === "object" && !(LOG_CONTEXT in err)) Object.defineProperty(err, LOG_CONTEXT, {
+		value: ctx,
+		enumerable: false,
+		configurable: true,
+		writable: true
+	});
+}
+/** The core of `logWith`: merge `add` into the current context, run `inner` within it, tag promise rejections. */
+function runWith(add, inner) {
+	const merged = merge(getContext(), add);
+	return store.run(merged, () => {
+		const out = inner();
+		if (out !== null && typeof out === "object" && typeof out.then === "function") return out.then((v) => v, (err) => {
+			attachContext(err, merged);
+			throw err;
+		});
+		return out;
+	});
+}
+const effectiveErrorCfg = (level, cfg) => {
+	const { perLevel, ...base } = cfg;
+	return {
+		...base,
+		...perLevel?.[level]
+	};
+};
+/** Try each serializer in turn; the first that returns non-`undefined` wins (a throw declines + reports). */
+function runSerializers(value, serializers, opts) {
+	for (const s of serializers) {
+		let out;
+		try {
+			out = s(value);
+		} catch (err) {
+			opts.onError?.(err);
+			continue;
+		}
+		if (out !== void 0) return out;
+	}
+}
+/** Call a hook, substituting {@link UNRESOLVED} (and reporting) if it throws — logging is best-effort. */
+function safeCall(fn, ctx, key, opts) {
+	try {
+		return fn.call(ctx, key);
+	} catch (err) {
+		opts.onError?.(err);
+		return UNRESOLVED;
+	}
+}
+/**
+* The resolver core (see {@link resolveLogValue}). `opts.onError` observes a throwing hook or a
+* rejecting promise; without it, such failures still degrade to {@link UNRESOLVED} (rejections
+* propagate to the awaiter). A `toLOG`/`toJSON`/promise may resolve asynchronously: the returned
+* structure then carries embedded promises, which {@link settleDeep} awaits before the record is built.
+*/
+function resolveLog(value, key, seen, opts) {
+	if (value === null || typeof value !== "object") return value;
+	if (opts.serializers) {
+		const s = runSerializers(value, opts.serializers, opts);
+		if (s !== void 0) return resolveLog(s, key, seen, opts);
+	}
+	if (value instanceof Error) return value;
+	if (isThenable(value)) return value.then((r) => resolveLog(r, key, seen, opts), (err) => {
+		opts.onError?.(err);
+		return UNRESOLVED;
+	});
+	const toLog = value.toLOG;
+	if (typeof toLog === "function") return resolveLog(safeCall(toLog, value, key, opts), key, seen, opts);
+	const toJson = value.toJSON;
+	if (typeof toJson === "function") return resolveLog(safeCall(toJson, value, key, opts), key, seen, opts);
+	if (seen.has(value)) return value;
+	seen.add(value);
+	if (Array.isArray(value)) return value.map((v, i) => resolveLog(v, String(i), seen, opts));
+	const src = value;
+	const out = {};
+	for (const k of Object.keys(src)) out[k] = resolveLog(src[k], k, seen, opts);
+	return out;
+}
+/**
+* Resolve a value to its **loggable plain shape**, deeply and eagerly — so a logged value carries
+* its intended shape everywhere consistently: in the record object the transports receive, through
+* the `sanitize` pass, and in both the JSON and text output (not just incidentally when a formatter
+* happens to stringify it). Two serialization hooks are honored before a structural copy:
+*
+* 1. **`toLOG()`** — a logging-specific hook that **takes precedence**: when present, the value
+*    becomes its result. Use it to shape a value for logs alone, without affecting `JSON.stringify`
+*    / API responses (which still use `toJSON`). It may return a **promise** (resolved before the
+*    record is built).
+* 2. **`toJSON(key)`** — the standard hook `JSON.stringify` uses (e.g. `Date`).
+*
+* Objects/arrays without either hook are rebuilt from their own enumerable entries (mirroring
+* `JSON.stringify`); `Error`s and primitives pass through; cycles are left as the original
+* reference. A promise anywhere (an async hook, or a raw promise value) becomes its awaited result.
+*/
+function resolveLogValue(value, key = "", seen = /* @__PURE__ */ new WeakSet()) {
+	return resolveLog(value, key, seen, {});
+}
+/** True if `value` is, or (deeply) contains, a thenable — i.e. resolving it needs an async pass. */
+function containsThenable(value, seen = /* @__PURE__ */ new WeakSet()) {
+	if (isThenable(value)) return true;
+	if (value === null || typeof value !== "object" || seen.has(value)) return false;
+	seen.add(value);
+	if (Array.isArray(value)) return value.some((v) => containsThenable(v, seen));
+	return Object.values(value).some((v) => containsThenable(v, seen));
+}
+/** Await every embedded promise in an already-resolved structure, yielding plain data. */
+async function settleDeep(value, seen = /* @__PURE__ */ new WeakSet()) {
+	if (isThenable(value)) return settleDeep(await value, seen);
+	if (value === null || typeof value !== "object") return value;
+	if (seen.has(value)) return value;
+	seen.add(value);
+	if (Array.isArray(value)) return Promise.all(value.map((v) => settleDeep(v, seen)));
+	const src = value;
+	const out = {};
+	for (const k of Object.keys(src)) out[k] = await settleDeep(src[k], seen);
+	return out;
+}
+/**
+* Build a {@link LogRecord} from `log()` args. `msg` is the space-joined non-object
+* args; objects and the ambient context are merged (ambient keeps bare keys);
+* `Error` args become `error`/`additionalErrors` and contribute any attached
+* trace context.
+*/
+function buildRecord(level, args, opts) {
+	const tms = opts.timestamp === "epoch" ? opts.now() : new Date(opts.now()).toISOString();
+	const msgParts = [];
+	const objects = [];
+	const errors = [];
+	for (const arg of args) if (arg instanceof Error) errors.push(arg);
+	else if (arg !== null && typeof arg === "object") objects.push(arg);
+	else msgParts.push(safeString(arg));
+	const errCfg = effectiveErrorCfg(level, opts.error);
+	let error;
+	const additionalErrors = [];
+	const errorContexts = [];
+	errors.forEach((e, i) => {
+		const ser = serializeError(e, errCfg);
+		if (i === 0) error = ser;
+		else additionalErrors.push(ser);
+		const attached = e[LOG_CONTEXT];
+		if (attached !== null && typeof attached === "object") errorContexts.push(attached);
+	});
+	let record = {
+		tms,
+		level,
+		msg: msgParts.join(" ")
+	};
+	if (error) record.error = error;
+	if (additionalErrors.length) record.additionalErrors = additionalErrors;
+	record = merge(record, getContext());
+	for (const o of objects) record = merge(record, o);
+	for (const c of errorContexts) record = merge(record, c);
+	return record;
+}
+const renderValue = (v) => {
+	if (typeof v === "string") return v;
+	if (typeof v === "number" || typeof v === "boolean" || typeof v === "bigint") return String(v);
+	if (v === null || v === void 0) return String(v);
+	try {
+		return JSON.stringify(v) ?? safeString(v);
+	} catch {
+		return safeString(v);
+	}
+};
+/** `[tms] level msg key=value, key=value` plus a trailing `error=Name: message`. */
+function formatText(record) {
+	const { tms, level, msg, error, additionalErrors, ...rest } = record;
+	let line = `[${String(tms)}] ${level} ${msg}`.trimEnd();
+	const pairs = Object.entries(rest).map(([k, v]) => `${k}=${renderValue(v)}`);
+	if (pairs.length) line += ` ${pairs.join(", ")}`;
+	if (error) line += ` error=${error.name}: ${error.message}`;
+	if (additionalErrors && additionalErrors.length) line += ` (+${additionalErrors.length} more)`;
+	return line;
+}
+/** Stable JSON, dropping `undefined` and guarding residual cycles. */
+function formatJson(record) {
+	const seen = /* @__PURE__ */ new WeakSet();
+	return JSON.stringify(record, (_k, v) => {
+		if (v === void 0) return;
+		if (v !== null && typeof v === "object") {
+			if (seen.has(v)) return "[Circular]";
+			seen.add(v);
+		}
+		return v;
+	});
+}
+/** Symbol marking a {@link logMaybe} value; `Symbol.for` keeps it stable across bundled entries. */
+const LOG_MAYBE = Symbol.for("@ayepi/log:maybe");
+/** Node's custom-inspect symbol, so a lazy value renders nicely under a non-intercepted `console.log`. */
+const INSPECT = Symbol.for("nodejs.util.inspect.custom");
+/** True for a thenable (a `Promise` or any `{ then(): … }`). */
+const isThenable = (v) => v !== null && typeof v === "object" && typeof v.then === "function";
+/** True for a {@link logMaybe} marker. */
+const isLazy = (v) => v !== null && typeof v === "object" && LOG_MAYBE in v;
+/**
+* Defer an expensive log argument. The function runs **only if** the line will actually be
+* logged (its level passes the threshold): under console interception the structured pipeline
+* calls it (with the record's level) and awaits the result, treating it as a normal argument.
+* On the non-intercepted path `toJSON` (and Node's inspect) render the synchronous value, or
+* `'(unresolved value)'` when the function returns a promise that can't be awaited there.
+*
+* ```ts
+* log.debug('state', logMaybe(() => expensiveSnapshot())) // snapshot built only at debug level
+* ```
+*/
+function logMaybe(fn) {
+	const render = () => {
+		let v;
+		try {
+			v = fn("info");
+		} catch {
+			return UNRESOLVED;
+		}
+		return isThenable(v) ? UNRESOLVED : v;
+	};
+	return {
+		[LOG_MAYBE]: fn,
+		toJSON: render,
+		[INSPECT]: render
+	};
+}
+const DEFAULT_MASK = () => "[redacted]";
+/**
+* A {@link SanitizeOptions.mask} that keeps the first `keep` characters and replaces the rest
+* with `fill` (e.g. `partialMask(3)('secret-token') === 'sec***'`). Values no longer than
+* `keep` are fully masked, so nothing short leaks. With the default `keep` of 0 it masks fully.
+*/
+function partialMask(keep = 0, fill = "***") {
+	return (value) => {
+		const s = typeof value === "string" ? value : safeString(value);
+		return s.length <= keep ? fill : s.slice(0, keep) + fill;
+	};
+}
+const matchKey = (key, patterns) => patterns.some((p) => typeof p === "string" ? p.toLowerCase() === key.toLowerCase() : p.test(key));
+const matchValue = (val, patterns) => patterns.some((p) => typeof p === "string" ? val.toLowerCase().includes(p.toLowerCase()) : p.test(val));
+const kindOf = (v) => v === null ? "null" : Array.isArray(v) ? "array" : typeof v;
+const isHomogeneous = (arr) => {
+	const k = kindOf(arr[0]);
+	return arr.every((e) => kindOf(e) === k);
+};
+const isPlainObject = (v) => {
+	const proto = Object.getPrototypeOf(v);
+	return proto === Object.prototype || proto === null;
+};
+const truncateString = (s, max) => `${s.slice(0, max)}... (+${s.length - max} more)`;
+/**
+* Build a record transformer that redacts sensitive keys/values and truncates long
+* strings/arrays per {@link SanitizeOptions}. Returns the (new) record, or `null` to drop it
+* (the `filter` returned `false`) — the same shape as `LoggerConfig.filter`, so it composes
+* there too. Only plain objects and arrays are walked; `Date`/class instances/{@link logMaybe}
+* markers pass through untouched, and the reserved `tms`/`level` fields are left pristine.
+*/
+function createSanitizer(opts) {
+	const mask = opts.mask ?? DEFAULT_MASK;
+	const keys = opts.sensitiveKeys ?? [];
+	const values = opts.sensitiveValues ?? [];
+	const maxStr = opts.maxStringLength;
+	const maxArr = opts.maxArrayLength;
+	const visit = (value, key, seen) => {
+		if (key !== void 0 && keys.length > 0 && matchKey(key, keys)) return mask(value, key);
+		if (typeof value === "string") {
+			if (values.length > 0 && matchValue(value, values)) return mask(value, key);
+			if (maxStr !== void 0 && value.length > maxStr) return truncateString(value, maxStr);
+			return value;
+		}
+		if (value === null || typeof value !== "object" || isLazy(value)) return value;
+		if (seen.has(value)) return value;
+		if (Array.isArray(value)) {
+			seen.add(value);
+			let kept = value;
+			let extra = 0;
+			if (maxArr !== void 0 && value.length > maxArr && isHomogeneous(value)) {
+				extra = value.length - maxArr;
+				kept = value.slice(0, maxArr);
+			}
+			const out = kept.map((e) => visit(e, void 0, seen));
+			if (extra > 0) out.push(`(+${extra} more)`);
+			return out;
+		}
+		if (!isPlainObject(value)) return value;
+		seen.add(value);
+		const src = value;
+		const masked = {};
+		for (const k of Object.keys(src)) masked[k] = visit(src[k], k, seen);
+		return masked;
+	};
+	return (record) => {
+		if (opts.filter && !opts.filter(record)) return null;
+		const seen = /* @__PURE__ */ new WeakSet();
+		const out = {};
+		for (const k of Object.keys(record)) out[k] = k === "tms" || k === "level" ? record[k] : visit(record[k], k, seen);
+		return out;
+	};
+}
+//#endregion
+Object.defineProperty(exports, "CONSOLE_LEVEL_MAP", {
+	enumerable: true,
+	get: function() {
+		return CONSOLE_LEVEL_MAP;
+	}
+});
+Object.defineProperty(exports, "DEFAULT_LEVEL", {
+	enumerable: true,
+	get: function() {
+		return DEFAULT_LEVEL;
+	}
+});
+Object.defineProperty(exports, "LEVELS", {
+	enumerable: true,
+	get: function() {
+		return LEVELS;
+	}
+});
+Object.defineProperty(exports, "LOG_CONTEXT", {
+	enumerable: true,
+	get: function() {
+		return LOG_CONTEXT;
+	}
+});
+Object.defineProperty(exports, "LOG_MAYBE", {
+	enumerable: true,
+	get: function() {
+		return LOG_MAYBE;
+	}
+});
+Object.defineProperty(exports, "UNRESOLVED", {
+	enumerable: true,
+	get: function() {
+		return UNRESOLVED;
+	}
+});
+Object.defineProperty(exports, "buildRecord", {
+	enumerable: true,
+	get: function() {
+		return buildRecord;
+	}
+});
+Object.defineProperty(exports, "containsThenable", {
+	enumerable: true,
+	get: function() {
+		return containsThenable;
+	}
+});
+Object.defineProperty(exports, "createSanitizer", {
+	enumerable: true,
+	get: function() {
+		return createSanitizer;
+	}
+});
+Object.defineProperty(exports, "deepEqual", {
+	enumerable: true,
+	get: function() {
+		return deepEqual;
+	}
+});
+Object.defineProperty(exports, "formatJson", {
+	enumerable: true,
+	get: function() {
+		return formatJson;
+	}
+});
+Object.defineProperty(exports, "formatText", {
+	enumerable: true,
+	get: function() {
+		return formatText;
+	}
+});
+Object.defineProperty(exports, "getContext", {
+	enumerable: true,
+	get: function() {
+		return getContext;
+	}
+});
+Object.defineProperty(exports, "isLazy", {
+	enumerable: true,
+	get: function() {
+		return isLazy;
+	}
+});
+Object.defineProperty(exports, "logMaybe", {
+	enumerable: true,
+	get: function() {
+		return logMaybe;
+	}
+});
+Object.defineProperty(exports, "merge", {
+	enumerable: true,
+	get: function() {
+		return merge;
+	}
+});
+Object.defineProperty(exports, "partialMask", {
+	enumerable: true,
+	get: function() {
+		return partialMask;
+	}
+});
+Object.defineProperty(exports, "resolveLog", {
+	enumerable: true,
+	get: function() {
+		return resolveLog;
+	}
+});
+Object.defineProperty(exports, "resolveLogValue", {
+	enumerable: true,
+	get: function() {
+		return resolveLogValue;
+	}
+});
+Object.defineProperty(exports, "runWith", {
+	enumerable: true,
+	get: function() {
+		return runWith;
+	}
+});
+Object.defineProperty(exports, "serializeError", {
+	enumerable: true,
+	get: function() {
+		return serializeError;
+	}
+});
+Object.defineProperty(exports, "settleDeep", {
+	enumerable: true,
+	get: function() {
+		return settleDeep;
+	}
+});

package/dist/internal.d.cts

@@ -0,0 +1,153 @@
+//#region src/internal.d.ts
+
+/** Symbol under which `logWith` stashes the full merged context onto a rejected error. `Symbol.for` → stable across bundled entries. */
+declare const LOG_CONTEXT: unique symbol;
+/** Placeholder substituted for a value whose resolution (a `toLOG`/`toJSON` hook, a `logMaybe`, a promise) threw or rejected. */
+
+/** The log levels, in console-method parity. */
+type Level = 'debug' | 'info' | 'warn' | 'error';
+/** A finished, fully-merged log record. Always carries the reserved fields. */
+interface LogRecord {
+  /** Timestamp — ISO string by default, numeric epoch ms when `timestamp:'epoch'`. */
+  readonly tms: string | number;
+  readonly level: Level;
+  readonly msg: string;
+  /** Serialized primary error (the first `Error` arg). */
+  readonly error?: SerializedError;
+  /** Serialized 2nd+ `Error` args. */
+  readonly additionalErrors?: readonly SerializedError[];
+  /** Merged fields (ambient context + object args + error-attached context). */
+  readonly [key: string]: unknown;
+}
+/** A serialized `Error`: standard fields, depth-bounded `cause`, and own enumerable props. */
+interface SerializedError {
+  readonly name: string;
+  readonly message: string;
+  readonly stack?: string;
+  readonly cause?: unknown;
+  readonly [key: string]: unknown;
+}
+/** What to capture when serializing an `Error`. */
+interface ErrorCaptureConfig {
+  /** Include `error.stack` (default `true`). */
+  readonly stack?: boolean;
+  /** Recurse into `error.cause` (default `true`). */
+  readonly cause?: boolean;
+  /** Include own enumerable non-standard props like `code`/`statusCode` (default `true`). */
+  readonly fields?: boolean;
+  /** Max `cause` recursion depth (default 5). */
+  readonly maxCauseDepth?: number;
+}
+/** Error capture config plus per-level overrides ("what is captured at each level"). */
+interface ErrorConfig extends ErrorCaptureConfig {
+  /** Per-level overrides, shallow-merged over the base (e.g. drop stacks below `error`). */
+  readonly perLevel?: Partial<Record<Level, ErrorCaptureConfig>>;
+}
+/** A sink for finished records. */
+interface Transport {
+  /** A name, for debugging. */
+  readonly name: string;
+  /** Write one record; `text` is the pre-formatted line. May be async; the logger never awaits it. */
+  write(record: LogRecord, text: string): void | Promise<void>;
+  /** Optional: drain any buffered writes to their destination (without tearing the transport down). */
+  flush?(): void | Promise<void>;
+  /** Optional: flush and release resources (timers, file handles). The transport isn't used after. */
+  close?(): void | Promise<void>;
+}
+/**
+ * Shape a value the logger doesn't own (and so can't carry a {@link logMaybe}/`toLOG` hook) —
+ * e.g. a `Request`, `URL`, `Buffer`, or a third-party class. Return the replacement shape, or
+ * `undefined` to decline (the next serializer, then `toLOG`/`toJSON`/a structural copy, is tried).
+ * Applied at **every depth**. Configured via `LoggerConfig.serializers`.
+ */
+type Serializer = (value: object) => unknown;
+/** Recursive structural equality. Handles primitives, `Date`, arrays, `Error`, plain objects, and cycles. */
+declare function deepEqual(a: unknown, b: unknown, seen?: WeakMap<object, object>): boolean;
+/**
+ * Merge `b` into `a` immutably. `a` keeps all of its own keys; each key of `b` is
+ * placed in the first slot among `key, key2, key3, …` that is free **or** already
+ * deep-equals `b`'s value (dedup). Returns a **new** object — neither input is
+ * mutated.
+ */
+declare function merge(a: Record<string, unknown>, b: Record<string, unknown>): Record<string, unknown>;
+/** Serialize `err` per `cfg` (stack/cause/fields, depth-bounded). Non-`Error` values become `{ name:'NonError', message }`. */
+declare function serializeError(err: unknown, cfg?: ErrorCaptureConfig, depth?: number): SerializedError;
+/** The current merged `logWith` context (empty object outside any `logWith`). */
+declare const getContext: () => Record<string, unknown>;
+/** The core of `logWith`: merge `add` into the current context, run `inner` within it, tag promise rejections. */
+
+/**
+ * Resolve a value to its **loggable plain shape**, deeply and eagerly — so a logged value carries
+ * its intended shape everywhere consistently: in the record object the transports receive, through
+ * the `sanitize` pass, and in both the JSON and text output (not just incidentally when a formatter
+ * happens to stringify it). Two serialization hooks are honored before a structural copy:
+ *
+ * 1. **`toLOG()`** — a logging-specific hook that **takes precedence**: when present, the value
+ *    becomes its result. Use it to shape a value for logs alone, without affecting `JSON.stringify`
+ *    / API responses (which still use `toJSON`). It may return a **promise** (resolved before the
+ *    record is built).
+ * 2. **`toJSON(key)`** — the standard hook `JSON.stringify` uses (e.g. `Date`).
+ *
+ * Objects/arrays without either hook are rebuilt from their own enumerable entries (mirroring
+ * `JSON.stringify`); `Error`s and primitives pass through; cycles are left as the original
+ * reference. A promise anywhere (an async hook, or a raw promise value) becomes its awaited result.
+ */
+declare function resolveLogValue(value: unknown, key?: string, seen?: WeakSet<object>): unknown;
+/** True if `value` is, or (deeply) contains, a thenable — i.e. resolving it needs an async pass. */
+
+/** A value produced either synchronously or asynchronously. */
+type MaybePromise<T> = T | Promise<T>;
+/** Symbol marking a {@link logMaybe} value; `Symbol.for` keeps it stable across bundled entries. */
+declare const LOG_MAYBE: unique symbol;
+/** A deferred log argument produced by {@link logMaybe}. */
+interface LazyLogValue {
+  /** Produce the value for `level` — invoked only when the line will actually be logged. */
+  readonly [LOG_MAYBE]: (level: Level) => MaybePromise<unknown>;
+  /** Best-effort **synchronous** rendering for the non-intercepted path (JSON / `console.log`). */
+  toJSON(): unknown;
+}
+/** True for a thenable (a `Promise` or any `{ then(): … }`). */
+
+/**
+ * Defer an expensive log argument. The function runs **only if** the line will actually be
+ * logged (its level passes the threshold): under console interception the structured pipeline
+ * calls it (with the record's level) and awaits the result, treating it as a normal argument.
+ * On the non-intercepted path `toJSON` (and Node's inspect) render the synchronous value, or
+ * `'(unresolved value)'` when the function returns a promise that can't be awaited there.
+ *
+ * ```ts
+ * log.debug('state', logMaybe(() => expensiveSnapshot())) // snapshot built only at debug level
+ * ```
+ */
+declare function logMaybe(fn: (level: Level) => MaybePromise<unknown>): LazyLogValue;
+/** Options for {@link createSanitizer} (and `LoggerConfig.sanitize`). */
+interface SanitizeOptions {
+  /** Decide whether a built record is logged at all — return `false` to drop it. Runs first. */
+  readonly filter?: (record: LogRecord) => boolean;
+  /** Property names whose values are masked — a `string` (case-insensitive exact match) or a `RegExp`. Matched at any depth. */
+  readonly sensitiveKeys?: readonly (string | RegExp)[];
+  /** String **values** are masked when they match — a `string` (case-insensitive substring) or a `RegExp`. */
+  readonly sensitiveValues?: readonly (string | RegExp)[];
+  /** Turn a sensitive value into its masked form (default `() => '[redacted]'`; see {@link partialMask}). */
+  readonly mask?: (value: unknown, key?: string) => unknown;
+  /** Truncate any string longer than this many characters, appending `'... (+N more)'`. */
+  readonly maxStringLength?: number;
+  /** Truncate a **homogeneous** array (all elements the same kind) beyond this many, appending a `'(+N more)'` element. */
+  readonly maxArrayLength?: number;
+}
+/**
+ * A {@link SanitizeOptions.mask} that keeps the first `keep` characters and replaces the rest
+ * with `fill` (e.g. `partialMask(3)('secret-token') === 'sec***'`). Values no longer than
+ * `keep` are fully masked, so nothing short leaks. With the default `keep` of 0 it masks fully.
+ */
+declare function partialMask(keep?: number, fill?: string): (value: unknown) => string;
+/**
+ * Build a record transformer that redacts sensitive keys/values and truncates long
+ * strings/arrays per {@link SanitizeOptions}. Returns the (new) record, or `null` to drop it
+ * (the `filter` returned `false`) — the same shape as `LoggerConfig.filter`, so it composes
+ * there too. Only plain objects and arrays are walked; `Date`/class instances/{@link logMaybe}
+ * markers pass through untouched, and the reserved `tms`/`level` fields are left pristine.
+ */
+declare function createSanitizer(opts: SanitizeOptions): (record: LogRecord) => LogRecord | null;
+//#endregion
+export { partialMask as _, Level as a, SanitizeOptions as c, Transport as d, createSanitizer as f, merge as g, logMaybe as h, LazyLogValue as i, SerializedError as l, getContext as m, ErrorConfig as n, LogRecord as o, deepEqual as p, LOG_CONTEXT as r, MaybePromise as s, ErrorCaptureConfig as t, Serializer as u, resolveLogValue as v, serializeError as y };