@zudojs/logger 1.2.0 → 1.4.0

package/README.md

@@ -34,13 +34,56 @@ await logger.flush(); // drain in-flight writes before exit
 (5). A logger emits every message at or below its configured level;
 `level` defaults to `info`.
 
+Wherever a level is configured (the `level` option, `setLevel()` and
+`child({ level })`) it may be the enum value or its name in any case:
+
+```typescript
+createLogger({ level: "error" });            // same as LoggerLevel.ERROR
+logger.setLevel("DEBUG");
+logger.child({ level: LoggerLevel.TRACE });
+createLogger({ level: process.env.LOG_LEVEL as LoggerLevelName });
+```
+
+The type is `LoggerLevelLike` (`LoggerLevel | LoggerLevelName | Uppercase<LoggerLevelName>`);
+`"warning"` and `"information"` are accepted as aliases at runtime, and
+`resolveLoggerLevel(value)` converts one to the enum. An unknown name
+throws (`InvalidLoggerLevelError` from the options and `child`,
+`LoggerConfigurationError` from `setLevel`) rather than leaving a logger
+that silently emits nothing. A custom `Logger` implementation keeps
+compiling (`ChildLoggerOptions.level` is still the enum; `child()` accepts
+`ChildLoggerOptionsInput`), but may now be handed a name in `setLevel()` or
+`child()`: pass it through `resolveLoggerLevel()`.
+
 ## Transports
 
 A transport is either a `{ name, enabled, write, flush?, close? }`
 object or a `(entry, context) => void | Promise<void>` function. When no
 transport is configured the logger writes to the console.
 
-Built in: `createConsoleLoggerTransport`, and the composites
+### What a transport receives
+
+`entry.message` is the message exactly as it was logged. The logger's
+formatter renders the whole record into `entry.formatted`:
+
+- a text formatter (the default): the line with timestamp, level, logger
+  name, message, metadata and, if enabled, the stack;
+- the JSON formatter: its JSON string;
+- an object formatter such as `createStructuredLoggerFormatter()`: its
+  record is merged over the entry, and `entry.formatted` is that record as
+  one line of JSON (cycles become `"[Circular]"`, BigInt a string).
+
+A transport that prints text should print `entry.formatted ?? entry.message`
+(or call `formatTransportLine(entry)`, which falls back to the entry as one
+JSON line); one that ships records can ignore `formatted`.
+
+> **Changed in this release.** A string formatter's output used to replace
+> `entry.message`, so a custom transport printing `entry.message` got the
+> formatted line and could not recover the raw message. It now receives
+> the raw message; switch such a transport to
+> `entry.formatted ?? entry.message` to keep printing the formatted line.
+
+Built in: `createConsoleLoggerTransport` (prints one line per record:
+`entry.formatted`, or the entry as JSON), and the composites
 `createMultiLoggerTransport`, `createConditionalLoggerTransport` and
 `createBufferedLoggerTransport`. File and HTTP transports are not
 included — implement the `LoggerTransport` interface for those.
@@ -55,7 +98,11 @@ that entry, and a failure from a timer-triggered flush is rethrown by the
 next `flush()` or `close()`.
 
 `transportTimeout` (default 10s) bounds every transport write, so a
-transport that stops responding cannot hang `flush()` or `close()`.
+transport that stops responding cannot hang `flush()` or `close()`. A
+write that exceeds it fails with `LoggerTimeoutError`, carrying
+`transportName` and `timeout`; other write failures are reported as
+`LoggerTransportError` with `transportName` set, and formatter failures
+as `LoggerFormatterError` with `formatterName` set.
 
 `throwTransportErrors` (default `false`) rethrows transport and formatter
 failures instead of dropping them. A synchronous transport throws from the
@@ -88,8 +135,14 @@ against `DEFAULT_LOGGER_SECRET_FIELDS` — password, passphrase, secret,
 token, jwt, bearer, auth, authorization, cookie, session, sid,
 credential, api key, private key, client secret, card number, cvv, ssn,
 pin, otp and more — so `sessionId` and `cardNumber` are redacted while
-`passenger` and `authorId` are not. Nested objects, arrays and getters
-are all covered. Passing `redact.pattern` replaces the word matcher with
+`passenger` and `authorId` are not. Nested objects, arrays, `Map`,
+`Set` and getters are all covered — a `Map` is redacted per key and a
+`Set` becomes an array. A getter that THROWS yields `"[Unreadable]"`
+for that field: the rest of the entry is logged and the read failure is
+reported through the same path as transport and formatter failures
+(dropped by default, rethrown with `throwTransportErrors`), so a lazy
+ORM relation can never abort the caller's log statement. Passing
+`redact.pattern` replaces the word matcher with
 your own RegExp (the old substring default is still exported as
 `DEFAULT_LOGGER_SECRET_PATTERN`).
 
@@ -115,7 +168,10 @@ indented so none can start at column 0 and pass for a record. The JSON formatter
 
 Metadata is normalized before serialization, so circular references
 (`"[Circular]"`), BigInt values and functions never make a formatter
-throw and silently drop the record.
+throw and silently drop the record. Only a genuine back-edge becomes
+`"[Circular]"` — the walk tracks the ancestor path, so an object
+referenced from two places in one payload (`{ actor: user, target: user }`)
+is logged in full both times.
 
 ## Context
 
@@ -150,6 +206,19 @@ Pass `{ colors: true }` in the formatter context to colourize the level
 tag of text output. Colour codes are emitted only around the fixed level
 name, never around user-supplied text.
 
+A formatter returns either a string or an object
+(`LoggerFormattedOutput`). A string becomes the payload's `formatted`
+line (`message` stays the raw message); an object is merged OVER the
+entry, so `createStructuredLoggerFormatter()` hands the transport its
+structured record (with an ISO-string `timestamp` and serialized
+metadata) rather than the raw entry, and `formatted` is the record as one
+JSON line. See "What a transport receives".
+
+`includeStackTrace: false` on the text formatter leaves every stack out:
+an entry's error prints as `error={"name":"Error","message":"..."}`, and
+an `Error` inside metadata is serialized without its stack, so no frame
+(and no absolute file path) reaches the log.
+
 ## Use Cases
 
 - Application logging

package/dist/loggerCore/core/loggerCore.context.d.ts

@@ -1,10 +1,10 @@
 /**
  * ContextLogger wrapper implementation.
  */
-import type { LoggerLevel } from "../../loggerLevel/loggerLevel.type.js";
+import type { LoggerLevel, LoggerLevelLike } from "../../loggerLevel/loggerLevel.type.js";
 import type { LogMetadata } from "../../loggerEntry/loggerEntry.type.js";
 import type { LoggerContext, LoggerContextStorage } from "../../loggerContext/loggerContext.core.js";
-import type { ChildLoggerOptions, LogOptions } from "../../loggerOptions/loggerOptions.type.js";
+import type { ChildLoggerOptionsInput, LogOptions } from "../../loggerOptions/loggerOptions.type.js";
 import type { Logger } from "./loggerCore.type.js";
 /**
  * Logger wrapper that provides scoped context.
@@ -30,9 +30,9 @@ export declare class ContextLogger implements Logger {
     debug(message: string, metadata?: LogMetadata): void;
     trace(message: string, metadata?: LogMetadata): void;
     log(level: LoggerLevel, message: string, options?: LogOptions): void;
-    child(options?: ChildLoggerOptions): Logger;
+    child(options?: ChildLoggerOptionsInput): Logger;
     withContext(context: LoggerContext): Logger;
-    setLevel(level: LoggerLevel): void;
+    setLevel(level: LoggerLevelLike): void;
     enable(): void;
     disable(): void;
     flush(): Promise<void>;

package/dist/loggerCore/core/loggerCore.core.d.ts

@@ -1,10 +1,10 @@
 /**
  * Core logger implementation.
  */
-import { LoggerLevel } from "../../loggerLevel/loggerLevel.type.js";
+import { LoggerLevel, type LoggerLevelLike } from "../../loggerLevel/loggerLevel.type.js";
 import type { LogMetadata } from "../../loggerEntry/loggerEntry.type.js";
 import type { LoggerContext, LoggerContextStorage } from "../../loggerContext/loggerContext.core.js";
-import type { ChildLoggerOptions, LoggerConfiguration, LoggerOptions, LogOptions } from "../../loggerOptions/loggerOptions.type.js";
+import type { ChildLoggerOptionsInput, LoggerConfiguration, LoggerOptions, LogOptions } from "../../loggerOptions/loggerOptions.type.js";
 import type { Logger } from "./loggerCore.type.js";
 /**
  * Internal context passed to extracted methods.
@@ -54,9 +54,9 @@ export declare class ZudojsLogger implements Logger, ZudojsLoggerContext {
     debug(message: string, metadata?: LogMetadata): void;
     trace(message: string, metadata?: LogMetadata): void;
     log(level: LoggerLevel, message: string, options?: LogOptions): void;
-    child(options?: ChildLoggerOptions): Logger;
+    child(options?: ChildLoggerOptionsInput): Logger;
     withContext(context: LoggerContext): Logger;
-    setLevel(level: LoggerLevel): void;
+    setLevel(level: LoggerLevelLike): void;
     enable(): void;
     disable(): void;
     flush(): Promise<void>;

package/dist/loggerCore/core/loggerCore.core.js

@@ -1,11 +1,11 @@
 /**
  * Core logger implementation.
  */
-import { LoggerLevel } from "../../loggerLevel/loggerLevel.type.js";
+import { LoggerLevel, } from "../../loggerLevel/loggerLevel.type.js";
 import { createLoggerContextStorage } from "../../loggerContext/loggerContextStorage.js";
 import { resolveLoggerOptions } from "../../loggerOptions/loggerOptions.type.js";
 import { normalizeConfiguration, assertActive as assertActiveHelper, assertMutable as assertMutableHelper, handleInfrastructureError as handleInfrastructureErrorHelper, } from "../helpers/loggerCoreHelpers.js";
-import { logAtLevel, childLogger, withContextLogger, setLoggerLevel, enableLogger, disableLogger, flushLogger, closeLogger, } from "../helpers/loggerCoreMethods/index.js";
+import { logAtLevel, levelOptions, childLogger, withContextLogger, setLoggerLevel, enableLogger, disableLogger, flushLogger, closeLogger, } from "../helpers/loggerCoreMethods/index.js";
 import { getLoggerName, getLoggerLevel, getLoggerEnabled, } from "../helpers/loggerCoreMethods.loggerProps.js";
 /** Upper bound on dispatch failures retained between two flushes. */
 const MAX_RETAINED_DISPATCH_FAILURES = 32;
@@ -48,22 +48,22 @@ export class ZudojsLogger {
         return getLoggerEnabled(this);
     }
     fatal(message, metadata) {
-        logAtLevel(this, LoggerLevel.FATAL, message, { metadata });
+        logAtLevel(this, LoggerLevel.FATAL, message, levelOptions(metadata));
     }
     error(message, metadata) {
-        logAtLevel(this, LoggerLevel.ERROR, message, { metadata });
+        logAtLevel(this, LoggerLevel.ERROR, message, levelOptions(metadata));
     }
     warn(message, metadata) {
-        logAtLevel(this, LoggerLevel.WARN, message, { metadata });
+        logAtLevel(this, LoggerLevel.WARN, message, levelOptions(metadata));
     }
     info(message, metadata) {
-        logAtLevel(this, LoggerLevel.INFO, message, { metadata });
+        logAtLevel(this, LoggerLevel.INFO, message, levelOptions(metadata));
     }
     debug(message, metadata) {
-        logAtLevel(this, LoggerLevel.DEBUG, message, { metadata });
+        logAtLevel(this, LoggerLevel.DEBUG, message, levelOptions(metadata));
     }
     trace(message, metadata) {
-        logAtLevel(this, LoggerLevel.TRACE, message, { metadata });
+        logAtLevel(this, LoggerLevel.TRACE, message, levelOptions(metadata));
     }
     log(level, message, options = {}) {
         logAtLevel(this, level, message, options);

package/dist/loggerCore/core/loggerCore.type.d.ts

@@ -1,10 +1,10 @@
 /**
  * Logger core types and interfaces.
  */
-import type { LoggerLevel } from "../../loggerLevel/loggerLevel.type.js";
+import type { LoggerLevel, LoggerLevelLike } from "../../loggerLevel/loggerLevel.type.js";
 import type { LogMetadata } from "../../loggerEntry/loggerEntry.type.js";
 import type { LoggerContext } from "../../loggerContext/loggerContext.core.js";
-import type { ChildLoggerOptions, LogOptions } from "../../loggerOptions/loggerOptions.type.js";
+import type { ChildLoggerOptionsInput, LogOptions } from "../../loggerOptions/loggerOptions.type.js";
 /**
  * Main Zudojs logger contract.
  */
@@ -19,9 +19,19 @@ export interface Logger {
     debug(message: string, metadata?: LogMetadata): void;
     trace(message: string, metadata?: LogMetadata): void;
     log(level: LoggerLevel, message: string, options?: LogOptions): void;
-    child(options?: ChildLoggerOptions): Logger;
+    /**
+     * Creates a child logger. `level` may be a name (`"debug"`); an
+     * implementation declared with `ChildLoggerOptions` still satisfies this
+     * interface and can resolve a name with `resolveLoggerLevel()`.
+     */
+    child(options?: ChildLoggerOptionsInput): Logger;
     withContext(context: LoggerContext): Logger;
-    setLevel(level: LoggerLevel): void;
+    /**
+     * Sets the threshold. Accepts `LoggerLevel.ERROR` or a name such as
+     * `"error"` (any case). An implementation declared with a `LoggerLevel`
+     * parameter still satisfies this interface.
+     */
+    setLevel(level: LoggerLevelLike): void;
     enable(): void;
     disable(): void;
     flush(): Promise<void>;

package/dist/loggerCore/helpers/loggerCore.helper.d.ts

@@ -3,12 +3,12 @@
  */
 import type { LogMetadata } from "../../loggerEntry/loggerEntry.type.js";
 import type { LoggerContext } from "../../loggerContext/loggerContext.core.js";
-import type { ChildLoggerOptions } from "../../loggerOptions/loggerOptions.type.js";
+import type { ChildLoggerOptionsInput } from "../../loggerOptions/loggerOptions.type.js";
 import type { Logger } from "../core/loggerCore.type.js";
 /**
  * Creates a child logger.
  */
-export declare function createChildLogger(parent: Logger, options?: ChildLoggerOptions): Logger;
+export declare function createChildLogger(parent: Logger, options?: ChildLoggerOptionsInput): Logger;
 /**
  * Creates a logger specifically for an error.
  */

package/dist/loggerCore/helpers/loggerCoreMethods/index.d.ts

@@ -5,7 +5,7 @@
  */
 export { createEntry } from "./loggerCoreMethods.entry.js";
 export { dispatchEntry, dispatchEntrySync, } from "./loggerCoreMethods.dispatch.js";
-export { logAtLevel } from "./loggerCoreMethods.level.js";
+export { logAtLevel, levelOptions } from "./loggerCoreMethods.level.js";
 export { childLogger, withContextLogger } from "./loggerCoreMethods.child.js";
 export { setLoggerLevel, enableLogger, disableLogger, flushLogger, closeLogger, } from "./loggerCoreMethods.lifecycle.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/loggerCore/helpers/loggerCoreMethods/index.js

@@ -5,7 +5,7 @@
  */
 export { createEntry } from "./loggerCoreMethods.entry.js";
 export { dispatchEntry, dispatchEntrySync, } from "./loggerCoreMethods.dispatch.js";
-export { logAtLevel } from "./loggerCoreMethods.level.js";
+export { logAtLevel, levelOptions } from "./loggerCoreMethods.level.js";
 export { childLogger, withContextLogger } from "./loggerCoreMethods.child.js";
 export { setLoggerLevel, enableLogger, disableLogger, flushLogger, closeLogger, } from "./loggerCoreMethods.lifecycle.js";
 //# sourceMappingURL=index.js.map

package/dist/loggerCore/helpers/loggerCoreMethods/loggerCoreMethods.child.d.ts

@@ -2,13 +2,13 @@
  * ZudojsLogger child and context methods.
  */
 import type { LoggerContext } from "../../../loggerContext/loggerContext.core.js";
-import type { ChildLoggerOptions } from "../../../loggerOptions/loggerOptions.type.js";
+import type { ChildLoggerOptionsInput } from "../../../loggerOptions/loggerOptions.type.js";
 import type { Logger } from "../../core/loggerCore.type.js";
 import type { ZudojsLoggerContext } from "../../core/loggerCore.core.js";
 /**
  * Creates a child logger.
  */
-export declare function childLogger(ctx: ZudojsLoggerContext, options?: ChildLoggerOptions): Logger;
+export declare function childLogger(ctx: ZudojsLoggerContext, options?: ChildLoggerOptionsInput): Logger;
 /**
  * Creates a logger with scoped context.
  */

package/dist/loggerCore/helpers/loggerCoreMethods/loggerCoreMethods.dispatch.js

@@ -4,8 +4,9 @@
 import { formatLoggerEntry } from "../../../loggerFormatter/loggerFormatter.core.js";
 import { createLoggerTransport, writeLoggerTransport, } from "../../../loggerTransport/loggerTransport.core.js";
 import { isLoggerTransport } from "../../../loggerTransport/loggerTransportGuard.js";
-import { LoggerFormatterError, LoggerTransportError, } from "../../../loggerErrors/loggerError.base.js";
-import { toLoggerError } from "../../../loggerErrors/loggerError.helpers.js";
+import { toJsonLogLine } from "../../../loggerTransport/loggerTransportHelpers/loggerTransportHelpers.js";
+import { LoggerFormatterError, LoggerTimeoutError, LoggerTransportError, } from "../../../loggerErrors/loggerError.base.js";
+import { createLoggerFormatterError, createLoggerTransportError, } from "../../../loggerErrors/loggerError.helpers.js";
 /**
  * Default formatter used when no formatter is configured.
  */
@@ -33,7 +34,11 @@ async function withTransportTimeout(timeoutMs, transportName, operation) {
     let timer;
     const expiry = new Promise((_resolve, reject) => {
         timer = setTimeout(() => {
-            reject(new LoggerTransportError(`Transport "${transportName}" did not complete within ${timeoutMs}ms.`));
+            // LoggerTimeoutError carries `transportName` and `timeout`, which
+            // the bare LoggerTransportError raised here before did not — so
+            // `catch (e) { if (e instanceof LoggerTimeoutError) retry() }`
+            // could never match.
+            reject(new LoggerTimeoutError(transportName, timeoutMs));
         }, timeoutMs);
         // This timer bounds a write; it is not work in its own right. Left
         // referenced it keeps the event loop alive, so a process that has
@@ -53,20 +58,60 @@ async function withTransportTimeout(timeoutMs, transportName, operation) {
         void operation.catch(() => { });
     }
 }
+/**
+ * Builds the payload handed to a transport.
+ *
+ * `LoggerFormattedOutput` is `string | Record<string, unknown>`. A string
+ * is the formatted line and is carried in `formatted`; `message` stays the
+ * caller's raw message. (It used to be replaced by the line, so a transport
+ * could not get the message back without parsing it out again.) An OBJECT
+ * is the formatted record: it is merged over the entry, so a transport sees
+ * the formatter's fields, and `formatted` is that record as one JSON line.
+ */
+function toTransportPayload(entry, formatted) {
+    if (typeof formatted === "string") {
+        return { ...entry, formatted };
+    }
+    if (formatted !== null &&
+        typeof formatted === "object" &&
+        !Array.isArray(formatted)) {
+        return {
+            ...entry,
+            ...formatted,
+            formatted: toJsonLogLine(formatted),
+        };
+    }
+    return entry;
+}
+/** Name of the configured formatter, for error reporting. */
+function resolveFormatterName(configuration) {
+    const formatter = configuration.formatter;
+    if (typeof formatter === "string") {
+        return formatter;
+    }
+    return formatter.name ?? "formatter";
+}
+/** Wraps a transport failure, keeping an already-typed logger error. */
+function toTransportError(transportName, error) {
+    return error instanceof LoggerTransportError
+        ? error
+        : createLoggerTransportError(transportName, error);
+}
+/** Wraps a formatter failure, keeping an already-typed logger error. */
+function toFormatterError(formatterName, error) {
+    return error instanceof LoggerFormatterError
+        ? error
+        : createLoggerFormatterError(formatterName, error);
+}
 /**
  * Writes to a transport.
  */
-async function writeTransport(configuration, transport, entry, formatted) {
+async function writeTransport(configuration, transport, payload) {
     const transportContext = {
         loggerName: configuration.name,
         environment: configuration.environment,
     };
-    if (typeof formatted === "string") {
-        const formattedEntry = { ...entry, message: formatted };
-        await writeLoggerTransport(transport.transport, formattedEntry, transportContext);
-        return;
-    }
-    await writeLoggerTransport(transport.transport, entry, transportContext);
+    await writeLoggerTransport(transport.transport, payload, transportContext);
 }
 /**
  * Formats an entry with the configured formatter.
@@ -89,12 +134,11 @@ function formatEntry(configuration, entry) {
  * the transport directly lets a synchronous console/array transport
  * complete inline, which is what `asynchronous: false` promises.
  */
-function writeTransportMaybeSync(configuration, transport, entry, formatted) {
+function writeTransportMaybeSync(configuration, transport, payload) {
     const transportContext = {
         loggerName: configuration.name,
         environment: configuration.environment,
     };
-    const payload = typeof formatted === "string" ? { ...entry, message: formatted } : entry;
     const target = transport.transport;
     return typeof target === "function"
         ? target(payload, transportContext)
@@ -104,29 +148,29 @@ function writeTransportMaybeSync(configuration, transport, entry, formatted) {
  * Dispatches an entry to the configured transports.
  */
 export async function dispatchEntry(configuration, entry, handleError) {
-    let formatted;
+    let payload;
     try {
-        formatted = formatEntry(configuration, entry);
+        payload = toTransportPayload(entry, formatEntry(configuration, entry));
     }
     catch (error) {
-        const formatterError = new LoggerFormatterError(`Failed to format log entry: ${toLoggerError(error).message}`, { cause: error });
-        handleError(formatterError);
+        handleError(toFormatterError(resolveFormatterName(configuration), error));
         return;
     }
     for (const transport of configuration.transports) {
+        let transportName = "transport";
         try {
             if (!isLoggerTransport(transport)) {
                 continue;
             }
             const registered = createLoggerTransport(transport);
+            transportName = registered.name;
             if (!registered.enabled) {
                 continue;
             }
-            await withTransportTimeout(configuration.transportTimeout, registered.name, writeTransport(configuration, registered, entry, formatted));
+            await withTransportTimeout(configuration.transportTimeout, registered.name, writeTransport(configuration, registered, payload));
         }
         catch (error) {
-            const transportError = new LoggerTransportError(`Failed to write log entry: ${toLoggerError(error).message}`, { cause: error });
-            handleError(transportError);
+            handleError(toTransportError(transportName, error));
         }
     }
 }
@@ -148,33 +192,35 @@ export function dispatchEntrySync(configuration, entry, handleError) {
         // caller off the transport's critical path.
         return Promise.resolve().then(() => dispatchEntry(configuration, entry, handleError));
     }
-    let formatted;
+    let payload;
     try {
-        formatted = formatEntry(configuration, entry);
+        payload = toTransportPayload(entry, formatEntry(configuration, entry));
     }
     catch (error) {
-        handleError(new LoggerFormatterError(`Failed to format log entry: ${toLoggerError(error).message}`, { cause: error }));
+        handleError(toFormatterError(resolveFormatterName(configuration), error));
         return;
     }
     const pending = [];
     for (const transport of configuration.transports) {
+        let transportName = "transport";
         try {
             if (!isLoggerTransport(transport)) {
                 continue;
             }
             const registered = createLoggerTransport(transport);
+            transportName = registered.name;
             if (!registered.enabled) {
                 continue;
             }
-            const result = writeTransportMaybeSync(configuration, registered, entry, formatted);
+            const result = writeTransportMaybeSync(configuration, registered, payload);
             if (result instanceof Promise) {
                 pending.push(withTransportTimeout(configuration.transportTimeout, registered.name, result).catch((error) => {
-                    handleError(new LoggerTransportError(`Failed to write log entry: ${toLoggerError(error).message}`, { cause: error }));
+                    handleError(toTransportError(registered.name, error));
                 }));
             }
         }
         catch (error) {
-            handleError(new LoggerTransportError(`Failed to write log entry: ${toLoggerError(error).message}`, { cause: error }));
+            handleError(toTransportError(transportName, error));
         }
     }
     if (pending.length === 0) {

package/dist/loggerCore/helpers/loggerCoreMethods/loggerCoreMethods.entry.d.ts

@@ -6,8 +6,13 @@ import type { LoggerEntry } from "../../../loggerEntry/loggerEntry.type.js";
 import type { LoggerConfiguration, LogOptions } from "../../../loggerOptions/loggerOptions.type.js";
 /**
  * Creates a normalized log entry.
+ *
+ * @param onMetadataError - Notified when a metadata property could not
+ *   be read (a throwing getter). The field is replaced with a marker
+ *   and the entry is still produced, so the caller's log statement
+ *   never aborts; reporting is the caller's job.
  */
 export declare function createEntry(configuration: LoggerConfiguration, contextStorage: {
     get(): import("../../../loggerContext/loggerContext.core.js").LoggerContext | undefined;
-}, level: LoggerLevel, message: string, options: LogOptions): LoggerEntry;
+}, level: LoggerLevel, message: string, options: LogOptions, onMetadataError?: (key: string, error: unknown) => void): LoggerEntry;
 //# sourceMappingURL=loggerCoreMethods.entry.d.ts.map

package/dist/loggerCore/helpers/loggerCoreMethods/loggerCoreMethods.entry.js

@@ -6,8 +6,13 @@ import { createSecretMatcher, redactLogValue, LOGGER_REDACTION_TOKEN, } from "..
 import { contextToLogMetadata, createLoggerContext, } from "../../../loggerContext/loggerContext.core.js";
 /**
  * Creates a normalized log entry.
+ *
+ * @param onMetadataError - Notified when a metadata property could not
+ *   be read (a throwing getter). The field is replaced with a marker
+ *   and the entry is still produced, so the caller's log statement
+ *   never aborts; reporting is the caller's job.
  */
-export function createEntry(configuration, contextStorage, level, message, options) {
+export function createEntry(configuration, contextStorage, level, message, options, onMetadataError) {
     const activeContext = configuration.inheritContext
         ? contextStorage.get()
         : undefined;
@@ -29,7 +34,7 @@ export function createEntry(configuration, contextStorage, level, message, optio
     // path can bypass it — including nested objects, arrays and getters.
     const isSecret = createSecretMatcher(configuration.redact);
     const replacement = configuration.redact.replacement ?? LOGGER_REDACTION_TOKEN;
-    const metadata = redactLogValue(rawMetadata, isSecret, replacement);
+    const metadata = redactLogValue(rawMetadata, isSecret, replacement, undefined, onMetadataError);
     const context = options.context
         ? createLoggerContext({
             parent: activeContext,
@@ -46,7 +51,7 @@ export function createEntry(configuration, contextStorage, level, message, optio
         context: context
             ? {
                 ...context.identifiers,
-                metadata: redactLogValue(context.metadata, isSecret, replacement),
+                metadata: redactLogValue(context.metadata, isSecret, replacement, undefined, onMetadataError),
             }
             : undefined,
         source: options.source,

package/dist/loggerCore/helpers/loggerCoreMethods/loggerCoreMethods.level.d.ts

@@ -4,6 +4,13 @@
 import { LoggerLevel } from "../../../loggerLevel/loggerLevel.type.js";
 import type { LogOptions } from "../../../loggerOptions/loggerOptions.type.js";
 import type { ZudojsLoggerContext } from "../../core/loggerCore.core.js";
+/**
+ * Turns the second argument of `logger.error(message, x)` and friends into
+ * log options. An `Error` becomes the entry's `error` (with its stack)
+ * instead of being read as metadata, where it has no enumerable fields and
+ * vanished without trace.
+ */
+export declare function levelOptions(metadata: LogOptions["metadata"] | undefined): LogOptions;
 /**
  * Level logging methods extracted from ZudojsLogger.
  */

package/dist/loggerCore/helpers/loggerCoreMethods/loggerCoreMethods.level.js

@@ -2,9 +2,22 @@
  * ZudojsLogger level methods.
  */
 import { LoggerLevel, shouldLog, } from "../../../loggerLevel/loggerLevel.type.js";
-import { LoggerConfigurationError } from "../../../loggerErrors/loggerError.base.js";
+import { InvalidLoggerEntryError, LoggerConfigurationError, } from "../../../loggerErrors/loggerError.base.js";
+import { toLoggerError } from "../../../loggerErrors/loggerError.helpers.js";
 import { createEntry } from "./loggerCoreMethods.entry.js";
 import { dispatchEntrySync } from "./loggerCoreMethods.dispatch.js";
+/**
+ * Turns the second argument of `logger.error(message, x)` and friends into
+ * log options. An `Error` becomes the entry's `error` (with its stack)
+ * instead of being read as metadata, where it has no enumerable fields and
+ * vanished without trace.
+ */
+export function levelOptions(metadata) {
+    // The static type says metadata, but JavaScript callers (and code typed
+    // loosely) routinely pass the caught error here.
+    const value = metadata;
+    return value instanceof Error ? { error: value } : { metadata };
+}
 /**
  * Level logging methods extracted from ZudojsLogger.
  */
@@ -17,7 +30,24 @@ export function logAtLevel(ctx, level, message, options = {}) {
     if (typeof message !== "string") {
         throw new LoggerConfigurationError("Logger message must be a string.");
     }
-    const entry = createEntry(ctx.configuration, ctx.contextStorage, level, message, options);
+    // Entry construction reads caller-supplied metadata, including
+    // getters. A throwing accessor used to propagate straight out of
+    // logger.info(...) and abort the caller — and only when the level
+    // let the call through, so the same code was a silent no-op at one
+    // log level and a crash at another. The offending field becomes a
+    // marker and the failure is reported like every other infrastructure
+    // failure, AFTER the line has been dispatched.
+    const metadataFailures = [];
+    let entry;
+    try {
+        entry = createEntry(ctx.configuration, ctx.contextStorage, level, message, options, (key, error) => {
+            metadataFailures.push(new InvalidLoggerEntryError(`Failed to read log metadata field "${key}": ${toLoggerError(error).message}`, { cause: error }));
+        });
+    }
+    catch (error) {
+        ctx.handleInfrastructureError(new InvalidLoggerEntryError(`Failed to build log entry: ${toLoggerError(error).message}`, { cause: error }));
+        return;
+    }
     // Dispatch is asynchronous. It used to be fired and forgotten, so
     // flush() and close() could return while entries were still in
     // flight — messages were lost on process exit. Registering the
@@ -26,5 +56,8 @@ export function logAtLevel(ctx, level, message, options = {}) {
     if (dispatch) {
         ctx.trackDispatch(dispatch);
     }
+    for (const failure of metadataFailures) {
+        ctx.handleInfrastructureError(failure);
+    }
 }
 //# sourceMappingURL=loggerCoreMethods.level.js.map

package/dist/loggerCore/helpers/loggerCoreMethods/loggerCoreMethods.lifecycle.d.ts

@@ -1,12 +1,12 @@
 /**
  * ZudojsLogger lifecycle methods.
  */
-import { LoggerLevel } from "../../../loggerLevel/loggerLevel.type.js";
+import { type LoggerLevelLike } from "../../../loggerLevel/loggerLevel.type.js";
 import type { ZudojsLoggerContext } from "../../core/loggerCore.core.js";
 /**
- * Sets the logger level.
+ * Sets the logger level from an enum value or a case-insensitive name.
  */
-export declare function setLoggerLevel(ctx: ZudojsLoggerContext, level: LoggerLevel): void;
+export declare function setLoggerLevel(ctx: ZudojsLoggerContext, level: LoggerLevelLike): void;
 /**
  * Enables the logger.
  */