@ayepi/log 0.1.0

package/dist/index.cjs

@@ -0,0 +1,239 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_internal = require("./internal.cjs");
+//#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 ?? require_internal.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 ? require_internal.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 = require_internal.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 ? require_internal.formatJson(record) : require_internal.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 (!require_internal.isLazy(raw)) return raw;
+		try {
+			return raw[require_internal.LOG_MAYBE](lvl);
+		} catch (err) {
+			report(err);
+			return require_internal.UNRESOLVED;
+		}
+	};
+	const emit = (lvl, args) => {
+		if (require_internal.LEVELS[lvl] < require_internal.LEVELS[level] || writing) return;
+		let resolved;
+		try {
+			resolved = args.map((raw) => require_internal.resolveLog(seedArg(raw, lvl), "", /* @__PURE__ */ new WeakSet(), resolveOpts));
+		} catch (err) {
+			report(err);
+			return;
+		}
+		if (resolved.some((v) => require_internal.containsThenable(v))) require_internal.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) => require_internal.runWith(add, inner),
+		context: () => Object.freeze({ ...require_internal.getContext() }),
+		setTransports: (t) => {
+			transports = t;
+		},
+		setLevel: (l) => {
+			level = l;
+		},
+		isLevelEnabled: (l) => require_internal.LEVELS[l] >= require_internal.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
+exports.LOG_CONTEXT = require_internal.LOG_CONTEXT;
+exports.consoleTransport = consoleTransport;
+exports.context = context;
+exports.createLogger = createLogger;
+exports.createSanitizer = require_internal.createSanitizer;
+exports.debug = debug;
+exports.deepEqual = require_internal.deepEqual;
+exports.error = error;
+exports.getContext = require_internal.getContext;
+exports.info = info;
+exports.interceptConsole = interceptConsole;
+exports.log = log;
+exports.logMaybe = require_internal.logMaybe;
+exports.logWith = logWith;
+exports.logger = logger;
+exports.merge = require_internal.merge;
+exports.partialMask = require_internal.partialMask;
+exports.resolveLogValue = require_internal.resolveLogValue;
+exports.restoreConsole = restoreConsole;
+exports.serializeError = require_internal.serializeError;
+exports.warn = warn;

package/dist/index.d.cts

@@ -0,0 +1,125 @@
+import { _ as partialMask, a as Level, c as SanitizeOptions, d as Transport, f as createSanitizer, g as merge, h as logMaybe, i as LazyLogValue, l as SerializedError, m as getContext, n as ErrorConfig, o as LogRecord, p as deepEqual, r as LOG_CONTEXT, s as MaybePromise, t as ErrorCaptureConfig, u as Serializer, v as resolveLogValue, y as serializeError } from "./internal.cjs";
+
+//#region src/index.d.ts
+
+/** The minimal `console` surface the logger reads/intercepts (the global one, or your own). */
+interface ConsoleLike {
+  log(...args: unknown[]): void;
+  info(...args: unknown[]): void;
+  debug(...args: unknown[]): void;
+  warn(...args: unknown[]): void;
+  error(...args: unknown[]): void;
+}
+/** Options for {@link consoleTransport}. */
+interface ConsoleTransportOptions {
+  /** The console to **write through** — should be the original (pre-interception) console to avoid recursion. */
+  readonly console?: ConsoleLike;
+  /** Map a record level to a console method (default: error→error, warn→warn, debug→debug, else→log). */
+  readonly method?: (level: Level) => keyof ConsoleLike;
+}
+/** A {@link Transport} that writes the formatted line to a console. */
+declare function consoleTransport(opts?: ConsoleTransportOptions): Transport;
+/** Configuration for {@link createLogger}. */
+interface LoggerConfig {
+  /** Minimum level emitted (default `'info'`). Logs below this are dropped before a record is built. */
+  readonly level?: Level;
+  /** Structured JSON output vs `[tms] level msg key=value` text (default `false` = text). */
+  readonly structured?: boolean;
+  /** Timestamp format — ISO string (default) or numeric epoch ms. */
+  readonly timestamp?: 'iso' | 'epoch';
+  /** Transports to write to (default: a single {@link consoleTransport} bound to the captured original console). */
+  readonly transports?: readonly Transport[];
+  /** Intercept global `console.*` immediately (default `false` — opt-in). */
+  readonly interceptConsole?: boolean;
+  /** `console` method → level mapping for interception (default {@link CONSOLE_LEVEL_MAP}). */
+  readonly consoleMap?: Readonly<Record<string, Level>>;
+  /** The console to read originals from / intercept (default the global `console`). */
+  readonly console?: ConsoleLike;
+  /** Error serialization config, including per-level overrides. */
+  readonly error?: ErrorConfig;
+  /**
+   * Final hook over the built record before it is formatted. Return a (possibly
+   * modified) record to log it — e.g. redact or add fields — or `null`/`undefined`
+   * to drop the log entirely. Runs **before** {@link sanitize}.
+   */
+  readonly filter?: (record: LogRecord) => LogRecord | null | undefined;
+  /**
+   * Declarative redaction/truncation applied to every record (after {@link filter}): drop via a
+   * `filter` predicate, mask `sensitiveKeys`/`sensitiveValues`, and cap `maxStringLength` /
+   * `maxArrayLength`. Applies to direct logger calls **and** intercepted `console.*`. (Equivalent
+   * to passing `createSanitizer(opts)` as `filter`, but it composes after your own `filter`.)
+   */
+  readonly sanitize?: SanitizeOptions;
+  /**
+   * Observe an error from the logging pipeline itself — a throwing `filter`, an
+   * unserializable record, or a transport whose `write` throws. Logging is **best-effort**:
+   * such an error never propagates to the caller (the line is dropped); this hook just lets
+   * you notice (e.g. count a metric, write to `stderr`). Off by default. It must not throw;
+   * if it does, the throw is ignored.
+   */
+  readonly onError?: (err: unknown) => void;
+  /**
+   * Custom {@link Serializer}s for values the logger doesn't own (a `Request`, `URL`, `Buffer`,
+   * a third-party class…) — the predicate-style counterpart to a `toLOG`/`toJSON` hook. Each is
+   * tried in order at every depth; the first non-`undefined` result wins (taking precedence over
+   * the value's own `toLOG`/`toJSON`). They apply to direct calls and intercepted `console.*`.
+   */
+  readonly serializers?: readonly Serializer[];
+  /** Clock injection for tests (default `() => Date.now()`). */
+  readonly now?: () => number;
+}
+/** A logger instance. */
+interface Logger {
+  /** Emit a record at `level` from mixed primitive/object/Error args. No-op below the threshold. */
+  log(level: Level, ...args: unknown[]): void;
+  debug(...args: unknown[]): void;
+  info(...args: unknown[]): void;
+  warn(...args: unknown[]): void;
+  error(...args: unknown[]): void;
+  /** Merge `add` into the current trace context, run `inner` within it, and tag promise rejections with the context. */
+  logWith<R>(add: object, inner: () => R): R;
+  /** Snapshot of the current merged trace context (empty outside any `logWith`). */
+  context(): Readonly<Record<string, unknown>>;
+  /** Replace the transports at runtime. */
+  setTransports(transports: readonly Transport[]): void;
+  /** Change the minimum emitted level at runtime (e.g. bump to `'debug'` on demand). */
+  setLevel(level: Level): void;
+  /** Whether a record at `level` would be emitted at the current threshold — guard expensive prep. */
+  isLevelEnabled(level: Level): boolean;
+  /** Drain every transport's buffered writes (e.g. the file transport) without closing them. */
+  flush(): Promise<void>;
+  /** Flush **and** close every transport (release timers/handles) — wire to a shutdown hook. */
+  close(): Promise<void>;
+  /** The effective level/format/timestamp (`level` reflects {@link setLevel}). */
+  readonly config: {
+    readonly level: Level;
+    readonly structured: boolean;
+    readonly timestamp: 'iso' | 'epoch';
+  };
+  /** Begin intercepting `console.*` (idempotent); returns a restore function. */
+  interceptConsole(): () => void;
+  /** Restore any console interception this logger installed (idempotent). */
+  restoreConsole(): void;
+}
+/**
+ * Create a {@link Logger}.
+ */
+declare function createLogger(config?: LoggerConfig): Logger;
+/** Emit a record at `level` on the default logger. */
+declare const log: (level: Level, ...args: unknown[]) => void;
+declare const debug: (...args: unknown[]) => void;
+declare const info: (...args: unknown[]) => void;
+declare const warn: (...args: unknown[]) => void;
+declare const error: (...args: unknown[]) => void;
+/** Stack trace context on the default logger (and tag promise rejections). */
+declare const logWith: <R>(add: object, inner: () => R) => R;
+/** The default logger's current trace context. */
+declare const context: () => Readonly<Record<string, unknown>>;
+/** Intercept `console.*` through the default logger; returns a restore function. */
+declare const interceptConsole: () => (() => void);
+/** Restore console interception installed by the default logger. */
+declare const restoreConsole: () => void;
+/** The default logger instance. */
+declare const logger: Logger;
+//#endregion
+export { ConsoleLike, ConsoleTransportOptions, type ErrorCaptureConfig, type ErrorConfig, LOG_CONTEXT, type LazyLogValue, type Level, type LogRecord, Logger, LoggerConfig, type MaybePromise, type SanitizeOptions, type SerializedError, type Serializer, type Transport, consoleTransport, context, createLogger, createSanitizer, debug, deepEqual, error, getContext, info, interceptConsole, log, logMaybe, logWith, logger, merge, partialMask, resolveLogValue, restoreConsole, serializeError, warn };

package/dist/index.d.ts

@@ -0,0 +1,125 @@
+import { _ as partialMask, a as Level, c as SanitizeOptions, d as Transport, f as createSanitizer, g as merge, h as logMaybe, i as LazyLogValue, l as SerializedError, m as getContext, n as ErrorConfig, o as LogRecord, p as deepEqual, r as LOG_CONTEXT, s as MaybePromise, t as ErrorCaptureConfig, u as Serializer, v as resolveLogValue, y as serializeError } from "./internal.js";
+
+//#region src/index.d.ts
+
+/** The minimal `console` surface the logger reads/intercepts (the global one, or your own). */
+interface ConsoleLike {
+  log(...args: unknown[]): void;
+  info(...args: unknown[]): void;
+  debug(...args: unknown[]): void;
+  warn(...args: unknown[]): void;
+  error(...args: unknown[]): void;
+}
+/** Options for {@link consoleTransport}. */
+interface ConsoleTransportOptions {
+  /** The console to **write through** — should be the original (pre-interception) console to avoid recursion. */
+  readonly console?: ConsoleLike;
+  /** Map a record level to a console method (default: error→error, warn→warn, debug→debug, else→log). */
+  readonly method?: (level: Level) => keyof ConsoleLike;
+}
+/** A {@link Transport} that writes the formatted line to a console. */
+declare function consoleTransport(opts?: ConsoleTransportOptions): Transport;
+/** Configuration for {@link createLogger}. */
+interface LoggerConfig {
+  /** Minimum level emitted (default `'info'`). Logs below this are dropped before a record is built. */
+  readonly level?: Level;
+  /** Structured JSON output vs `[tms] level msg key=value` text (default `false` = text). */
+  readonly structured?: boolean;
+  /** Timestamp format — ISO string (default) or numeric epoch ms. */
+  readonly timestamp?: 'iso' | 'epoch';
+  /** Transports to write to (default: a single {@link consoleTransport} bound to the captured original console). */
+  readonly transports?: readonly Transport[];
+  /** Intercept global `console.*` immediately (default `false` — opt-in). */
+  readonly interceptConsole?: boolean;
+  /** `console` method → level mapping for interception (default {@link CONSOLE_LEVEL_MAP}). */
+  readonly consoleMap?: Readonly<Record<string, Level>>;
+  /** The console to read originals from / intercept (default the global `console`). */
+  readonly console?: ConsoleLike;
+  /** Error serialization config, including per-level overrides. */
+  readonly error?: ErrorConfig;
+  /**
+   * Final hook over the built record before it is formatted. Return a (possibly
+   * modified) record to log it — e.g. redact or add fields — or `null`/`undefined`
+   * to drop the log entirely. Runs **before** {@link sanitize}.
+   */
+  readonly filter?: (record: LogRecord) => LogRecord | null | undefined;
+  /**
+   * Declarative redaction/truncation applied to every record (after {@link filter}): drop via a
+   * `filter` predicate, mask `sensitiveKeys`/`sensitiveValues`, and cap `maxStringLength` /
+   * `maxArrayLength`. Applies to direct logger calls **and** intercepted `console.*`. (Equivalent
+   * to passing `createSanitizer(opts)` as `filter`, but it composes after your own `filter`.)
+   */
+  readonly sanitize?: SanitizeOptions;
+  /**
+   * Observe an error from the logging pipeline itself — a throwing `filter`, an
+   * unserializable record, or a transport whose `write` throws. Logging is **best-effort**:
+   * such an error never propagates to the caller (the line is dropped); this hook just lets
+   * you notice (e.g. count a metric, write to `stderr`). Off by default. It must not throw;
+   * if it does, the throw is ignored.
+   */
+  readonly onError?: (err: unknown) => void;
+  /**
+   * Custom {@link Serializer}s for values the logger doesn't own (a `Request`, `URL`, `Buffer`,
+   * a third-party class…) — the predicate-style counterpart to a `toLOG`/`toJSON` hook. Each is
+   * tried in order at every depth; the first non-`undefined` result wins (taking precedence over
+   * the value's own `toLOG`/`toJSON`). They apply to direct calls and intercepted `console.*`.
+   */
+  readonly serializers?: readonly Serializer[];
+  /** Clock injection for tests (default `() => Date.now()`). */
+  readonly now?: () => number;
+}
+/** A logger instance. */
+interface Logger {
+  /** Emit a record at `level` from mixed primitive/object/Error args. No-op below the threshold. */
+  log(level: Level, ...args: unknown[]): void;
+  debug(...args: unknown[]): void;
+  info(...args: unknown[]): void;
+  warn(...args: unknown[]): void;
+  error(...args: unknown[]): void;
+  /** Merge `add` into the current trace context, run `inner` within it, and tag promise rejections with the context. */
+  logWith<R>(add: object, inner: () => R): R;
+  /** Snapshot of the current merged trace context (empty outside any `logWith`). */
+  context(): Readonly<Record<string, unknown>>;
+  /** Replace the transports at runtime. */
+  setTransports(transports: readonly Transport[]): void;
+  /** Change the minimum emitted level at runtime (e.g. bump to `'debug'` on demand). */
+  setLevel(level: Level): void;
+  /** Whether a record at `level` would be emitted at the current threshold — guard expensive prep. */
+  isLevelEnabled(level: Level): boolean;
+  /** Drain every transport's buffered writes (e.g. the file transport) without closing them. */
+  flush(): Promise<void>;
+  /** Flush **and** close every transport (release timers/handles) — wire to a shutdown hook. */
+  close(): Promise<void>;
+  /** The effective level/format/timestamp (`level` reflects {@link setLevel}). */
+  readonly config: {
+    readonly level: Level;
+    readonly structured: boolean;
+    readonly timestamp: 'iso' | 'epoch';
+  };
+  /** Begin intercepting `console.*` (idempotent); returns a restore function. */
+  interceptConsole(): () => void;
+  /** Restore any console interception this logger installed (idempotent). */
+  restoreConsole(): void;
+}
+/**
+ * Create a {@link Logger}.
+ */
+declare function createLogger(config?: LoggerConfig): Logger;
+/** Emit a record at `level` on the default logger. */
+declare const log: (level: Level, ...args: unknown[]) => void;
+declare const debug: (...args: unknown[]) => void;
+declare const info: (...args: unknown[]) => void;
+declare const warn: (...args: unknown[]) => void;
+declare const error: (...args: unknown[]) => void;
+/** Stack trace context on the default logger (and tag promise rejections). */
+declare const logWith: <R>(add: object, inner: () => R) => R;
+/** The default logger's current trace context. */
+declare const context: () => Readonly<Record<string, unknown>>;
+/** Intercept `console.*` through the default logger; returns a restore function. */
+declare const interceptConsole: () => (() => void);
+/** Restore console interception installed by the default logger. */
+declare const restoreConsole: () => void;
+/** The default logger instance. */
+declare const logger: Logger;
+//#endregion
+export { ConsoleLike, ConsoleTransportOptions, type ErrorCaptureConfig, type ErrorConfig, LOG_CONTEXT, type LazyLogValue, type Level, type LogRecord, Logger, LoggerConfig, type MaybePromise, type SanitizeOptions, type SerializedError, type Serializer, type Transport, consoleTransport, context, createLogger, createSanitizer, debug, deepEqual, error, getContext, info, interceptConsole, log, logMaybe, logWith, logger, merge, partialMask, resolveLogValue, restoreConsole, serializeError, warn };