@zudojs/logger 1.2.0 → 1.3.0

package/README.md

@@ -55,7 +55,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 +92,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 +125,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 +163,12 @@ 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 `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.
+
 ## Use Cases
 
 - Application logging

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

@@ -4,8 +4,8 @@
 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 { 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 +33,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,6 +57,50 @@ async function withTransportTimeout(timeoutMs, transportName, operation) {
         void operation.catch(() => { });
     }
 }
+/**
+ * Builds the payload handed to a transport.
+ *
+ * `LoggerFormattedOutput` is `string | Record<string, unknown>`. A
+ * string replaces the message; an OBJECT is the formatted record and is
+ * merged over the entry, so a transport sees the formatter's fields.
+ * The object branch used to be computed and then discarded, which made
+ * `createStructuredLoggerFormatter()` pure overhead on every log call
+ * and handed the transport the raw, unformatted entry instead.
+ */
+function toTransportPayload(entry, formatted) {
+    if (typeof formatted === "string") {
+        return { ...entry, message: formatted };
+    }
+    if (formatted !== null &&
+        typeof formatted === "object" &&
+        !Array.isArray(formatted)) {
+        return {
+            ...entry,
+            ...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.
  */
@@ -61,12 +109,7 @@ async function writeTransport(configuration, transport, entry, formatted) {
         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, toTransportPayload(entry, formatted), transportContext);
 }
 /**
  * Formats an entry with the configured formatter.
@@ -94,7 +137,7 @@ function writeTransportMaybeSync(configuration, transport, entry, formatted) {
         loggerName: configuration.name,
         environment: configuration.environment,
     };
-    const payload = typeof formatted === "string" ? { ...entry, message: formatted } : entry;
+    const payload = toTransportPayload(entry, formatted);
     const target = transport.transport;
     return typeof target === "function"
         ? target(payload, transportContext)
@@ -109,24 +152,24 @@ export async function dispatchEntry(configuration, entry, handleError) {
         formatted = 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));
         }
         catch (error) {
-            const transportError = new LoggerTransportError(`Failed to write log entry: ${toLoggerError(error).message}`, { cause: error });
-            handleError(transportError);
+            handleError(toTransportError(transportName, error));
         }
     }
 }
@@ -153,28 +196,30 @@ export function dispatchEntrySync(configuration, entry, handleError) {
         formatted = 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);
             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.js

@@ -2,7 +2,8 @@
  * 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";
 /**
@@ -17,7 +18,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 +44,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/loggerEntry/loggerEntryCreate.js

@@ -2,6 +2,7 @@
  * Logger entry creation from input.
  */
 import { createLoggerEntryId } from "./loggerEntry.core.js";
+import { InvalidLoggerEntryError } from "../loggerErrors/loggerError.base.js";
 import { loggerLevelNameFallback } from "./loggerEntryHelpers/loggerEntryHelpers.serialize.js";
 /**
  * Creates a normalized LoggerEntry.
@@ -10,7 +11,7 @@ export function createLoggerEntry(input) {
     const timestamp = input.timestamp ?? new Date();
     const timestampMs = timestamp.getTime();
     if (!Number.isFinite(timestampMs)) {
-        throw new RangeError("Logger entry timestamp must be a valid date.");
+        throw new InvalidLoggerEntryError("Logger entry timestamp must be a valid date.");
     }
     const levelName = input.levelName ?? loggerLevelNameFallback(input.level);
     return Object.freeze({

package/dist/loggerEntry/loggerEntryHelpers/index.d.ts

@@ -6,6 +6,6 @@
 export type { LogValue, LogMetadata, LoggerSource, LoggerEntryContext, } from "./loggerEntryHelpers.types.js";
 export type { LoggerEntry, LoggerEntryInput, } from "./loggerEntryHelpers.interfaces.js";
 export { serializeLoggerEntry, serializeLoggerError, serializeLoggerValue, loggerLevelNameFallback, } from "./loggerEntryHelpers.serialize.js";
-export { LOGGER_REDACTION_TOKEN, DEFAULT_LOGGER_SECRET_PATTERN, escapeLogText, hasLogControlCharacters, createSecretMatcher, redactLogValue, } from "./loggerEntryHelpers.sanitize.js";
+export { LOGGER_REDACTION_TOKEN, LOGGER_UNREADABLE_TOKEN, DEFAULT_LOGGER_SECRET_PATTERN, escapeLogText, hasLogControlCharacters, createSecretMatcher, redactLogValue, } from "./loggerEntryHelpers.sanitize.js";
 export type { LoggerRedactionOptions } from "./loggerEntryHelpers.sanitize.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/loggerEntry/loggerEntryHelpers/index.js

@@ -4,5 +4,5 @@
  * Logger entry helper types and utilities.
  */
 export { serializeLoggerEntry, serializeLoggerError, serializeLoggerValue, loggerLevelNameFallback, } from "./loggerEntryHelpers.serialize.js";
-export { LOGGER_REDACTION_TOKEN, DEFAULT_LOGGER_SECRET_PATTERN, escapeLogText, hasLogControlCharacters, createSecretMatcher, redactLogValue, } from "./loggerEntryHelpers.sanitize.js";
+export { LOGGER_REDACTION_TOKEN, LOGGER_UNREADABLE_TOKEN, DEFAULT_LOGGER_SECRET_PATTERN, escapeLogText, hasLogControlCharacters, createSecretMatcher, redactLogValue, } from "./loggerEntryHelpers.sanitize.js";
 //# sourceMappingURL=index.js.map

package/dist/loggerEntry/loggerEntryHelpers/loggerEntryHelpers.sanitize.d.ts

@@ -12,6 +12,14 @@
  * Replacement token written in place of a redacted value.
  */
 export declare const LOGGER_REDACTION_TOKEN = "[REDACTED]";
+/**
+ * Replacement token written in place of a property whose getter threw.
+ *
+ * A throwing accessor used to propagate out of `logger.info(...)` and
+ * abort the caller. The field is marked instead, the rest of the entry
+ * is logged, and the failure is reported as an infrastructure error.
+ */
+export declare const LOGGER_UNREADABLE_TOKEN = "[Unreadable]";
 /**
  * Legacy substring pattern for secret field names.
  *
@@ -64,10 +72,15 @@ export declare function createSecretMatcher(options?: LoggerRedactionOptions): (
 /**
  * Recursively replaces secret-named fields with a redaction token.
  *
- * Nesting, arrays and getters are all covered: the walk descends into
- * every enumerable own property, and a getter is read here — once,
- * before the value can reach a transport. Cycles resolve to
- * "[Circular]" rather than recursing forever.
+ * Nesting, arrays, `Map`, `Set` and getters are all covered: the walk
+ * descends into every enumerable own property, and a getter is read
+ * here — once, before the value can reach a transport. A getter that
+ * throws yields {@link LOGGER_UNREADABLE_TOKEN} and is reported through
+ * `onReadError` instead of aborting the caller's log statement.
+ *
+ * `seen` tracks the ANCESTOR PATH only (each object is unmarked as the
+ * walk ascends), so a back-edge resolves to "[Circular]" while an
+ * object merely referenced twice in one payload is logged both times.
  */
-export declare function redactLogValue(value: unknown, isSecret: (key: string) => boolean, replacement?: string, seen?: WeakSet<object>): unknown;
+export declare function redactLogValue(value: unknown, isSecret: (key: string) => boolean, replacement?: string, seen?: WeakSet<object>, onReadError?: (key: string, error: unknown) => void): unknown;
 //# sourceMappingURL=loggerEntryHelpers.sanitize.d.ts.map

package/dist/loggerEntry/loggerEntryHelpers/loggerEntryHelpers.sanitize.js

@@ -19,6 +19,14 @@ const CONTROL_CHARACTERS = /[\u0000-\u001f\u007f-\u009f\u2028\u2029]/g;
  * Replacement token written in place of a redacted value.
  */
 export const LOGGER_REDACTION_TOKEN = "[REDACTED]";
+/**
+ * Replacement token written in place of a property whose getter threw.
+ *
+ * A throwing accessor used to propagate out of `logger.info(...)` and
+ * abort the caller. The field is marked instead, the rest of the entry
+ * is logged, and the failure is reported as an infrastructure error.
+ */
+export const LOGGER_UNREADABLE_TOKEN = "[Unreadable]";
 /**
  * Legacy substring pattern for secret field names.
  *
@@ -85,15 +93,32 @@ export function createSecretMatcher(options = {}) {
         : configured;
     return (key) => exact.has(key.toLowerCase()) || pattern.test(key);
 }
+/** Defines an own, enumerable property without touching a setter. */
+function defineLogProperty(target, key, value) {
+    // defineProperty, never assignment: a "__proto__" key coming from
+    // JSON.parse of untrusted input would otherwise reach the inherited
+    // setter and replace this object's prototype.
+    Object.defineProperty(target, key, {
+        value,
+        enumerable: true,
+        writable: true,
+        configurable: true,
+    });
+}
 /**
  * Recursively replaces secret-named fields with a redaction token.
  *
- * Nesting, arrays and getters are all covered: the walk descends into
- * every enumerable own property, and a getter is read here — once,
- * before the value can reach a transport. Cycles resolve to
- * "[Circular]" rather than recursing forever.
+ * Nesting, arrays, `Map`, `Set` and getters are all covered: the walk
+ * descends into every enumerable own property, and a getter is read
+ * here — once, before the value can reach a transport. A getter that
+ * throws yields {@link LOGGER_UNREADABLE_TOKEN} and is reported through
+ * `onReadError` instead of aborting the caller's log statement.
+ *
+ * `seen` tracks the ANCESTOR PATH only (each object is unmarked as the
+ * walk ascends), so a back-edge resolves to "[Circular]" while an
+ * object merely referenced twice in one payload is logged both times.
  */
-export function redactLogValue(value, isSecret, replacement = LOGGER_REDACTION_TOKEN, seen = new WeakSet()) {
+export function redactLogValue(value, isSecret, replacement = LOGGER_REDACTION_TOKEN, seen = new WeakSet(), onReadError) {
     if (value === null || typeof value !== "object") {
         return value;
     }
@@ -104,23 +129,43 @@ export function redactLogValue(value, isSecret, replacement = LOGGER_REDACTION_T
         return "[Circular]";
     }
     seen.add(value);
-    if (Array.isArray(value)) {
-        return value.map((item) => redactLogValue(item, isSecret, replacement, seen));
+    try {
+        const descend = (item) => redactLogValue(item, isSecret, replacement, seen, onReadError);
+        if (Array.isArray(value)) {
+            return value.map(descend);
+        }
+        if (value instanceof Set) {
+            return Array.from(value, descend);
+        }
+        const result = {};
+        if (value instanceof Map) {
+            for (const [key, item] of value.entries()) {
+                const name = typeof key === "string" ? key : String(key);
+                defineLogProperty(result, name, isSecret(name) ? replacement : descend(item));
+            }
+            return result;
+        }
+        for (const key of Object.keys(value)) {
+            if (isSecret(key)) {
+                // Never even read a secret-named accessor.
+                defineLogProperty(result, key, replacement);
+                continue;
+            }
+            let item;
+            try {
+                item = value[key];
+            }
+            catch (error) {
+                onReadError?.(key, error);
+                defineLogProperty(result, key, LOGGER_UNREADABLE_TOKEN);
+                continue;
+            }
+            defineLogProperty(result, key, descend(item));
+        }
+        return result;
     }
-    const result = {};
-    for (const [key, item] of Object.entries(value)) {
-        // defineProperty, never assignment: a "__proto__" key coming from
-        // JSON.parse of untrusted input would otherwise reach the inherited
-        // setter and replace this object's prototype.
-        Object.defineProperty(result, key, {
-            value: isSecret(key)
-                ? replacement
-                : redactLogValue(item, isSecret, replacement, seen),
-            enumerable: true,
-            writable: true,
-            configurable: true,
-        });
+    finally {
+        seen.delete(value);
     }
-    return result;
 }
 //# sourceMappingURL=loggerEntryHelpers.sanitize.js.map

package/dist/loggerEntry/loggerEntryHelpers/loggerEntryHelpers.serialize.js

@@ -1,6 +1,7 @@
 /**
  * Logger entry serialization helpers.
  */
+import { InvalidLoggerLevelError } from "../../loggerErrors/loggerError.base.js";
 import { serializeLoggerError, serializeLoggerValue, } from "./loggerEntryHelpers.valueSerialize.js";
 /**
  * Returns a plain serializable representation of an entry.
@@ -49,7 +50,7 @@ export function loggerLevelNameFallback(level) {
         case 5:
             return "trace";
         default:
-            throw new RangeError(`Unknown logger level: ${String(level)}`);
+            throw new InvalidLoggerLevelError(level);
     }
 }
 //# sourceMappingURL=loggerEntryHelpers.serialize.js.map

package/dist/loggerEntry/loggerEntryHelpers/loggerEntryHelpers.valueSerialize.d.ts

@@ -11,6 +11,11 @@ export declare function serializeLoggerError(error: {
 }): Record<string, unknown>;
 /**
  * Converts arbitrary values into safer serializable values.
+ *
+ * `seen` tracks the ANCESTOR PATH only, so only a genuine back-edge
+ * becomes "[Circular]"; `Map` and `Set` keep their contents; and a
+ * property whose getter throws becomes "[Unreadable]" rather than
+ * taking the whole log line down.
  */
 export declare function serializeLoggerValue(value: unknown, seen?: WeakSet<object>): unknown;
 //# sourceMappingURL=loggerEntryHelpers.valueSerialize.d.ts.map

package/dist/loggerEntry/loggerEntryHelpers/loggerEntryHelpers.valueSerialize.js

@@ -1,6 +1,7 @@
 /**
  * Logger entry value serialization.
  */
+import { LOGGER_UNREADABLE_TOKEN } from "./loggerEntryHelpers.sanitize.js";
 /**
  * Serializes an error-like object into a plain object.
  */
@@ -13,6 +14,11 @@ export function serializeLoggerError(error) {
 }
 /**
  * Converts arbitrary values into safer serializable values.
+ *
+ * `seen` tracks the ANCESTOR PATH only, so only a genuine back-edge
+ * becomes "[Circular]"; `Map` and `Set` keep their contents; and a
+ * property whose getter throws becomes "[Unreadable]" rather than
+ * taking the whole log line down.
  */
 export function serializeLoggerValue(value, seen = new WeakSet()) {
     if (value === null ||
@@ -44,21 +50,46 @@ export function serializeLoggerValue(value, seen = new WeakSet()) {
         return "[Circular]";
     }
     seen.add(value);
-    if (Array.isArray(value)) {
-        return value.map((item) => serializeLoggerValue(item, seen));
-    }
-    const result = {};
-    for (const [key, item] of Object.entries(value)) {
+    try {
+        if (Array.isArray(value)) {
+            return value.map((item) => serializeLoggerValue(item, seen));
+        }
+        if (value instanceof Set) {
+            return Array.from(value, (item) => serializeLoggerValue(item, seen));
+        }
+        const result = {};
         // defineProperty, never assignment: a "__proto__" key from an
         // untrusted payload would otherwise reach the inherited setter and
         // replace the serialized object's prototype.
-        Object.defineProperty(result, key, {
-            value: serializeLoggerValue(item, seen),
-            enumerable: true,
-            writable: true,
-            configurable: true,
-        });
+        const define = (key, item) => {
+            Object.defineProperty(result, key, {
+                value: item,
+                enumerable: true,
+                writable: true,
+                configurable: true,
+            });
+        };
+        if (value instanceof Map) {
+            for (const [key, item] of value.entries()) {
+                define(typeof key === "string" ? key : String(key), serializeLoggerValue(item, seen));
+            }
+            return result;
+        }
+        for (const key of Object.keys(value)) {
+            let item;
+            try {
+                item = value[key];
+            }
+            catch {
+                define(key, LOGGER_UNREADABLE_TOKEN);
+                continue;
+            }
+            define(key, serializeLoggerValue(item, seen));
+        }
+        return result;
+    }
+    finally {
+        seen.delete(value);
     }
-    return result;
 }
 //# sourceMappingURL=loggerEntryHelpers.valueSerialize.js.map

package/dist/loggerFactory/loggerFactory.core.d.ts

@@ -17,6 +17,13 @@ export declare class LoggerFactory {
      * instance is returned unless `forceNew` is enabled.
      */
     create(name?: string, options?: LoggerOptions, forceNew?: boolean): Logger;
+    /**
+     * Registers an existing logger under its own name (or `name`).
+     *
+     * An adopted logger is then covered by `flushAll()`, `disposeAll()`,
+     * `getAll()` and `size` exactly like one the factory created itself.
+     */
+    register(logger: Logger, name?: string): Logger;
     /** Returns an existing logger. */
     get(name: string): Logger | undefined;
     /** Gets an existing logger or creates it. */

package/dist/loggerFactory/loggerFactory.core.js

@@ -31,6 +31,16 @@ export class LoggerFactory {
         this.loggers.set(loggerName, logger);
         return logger;
     }
+    /**
+     * Registers an existing logger under its own name (or `name`).
+     *
+     * An adopted logger is then covered by `flushAll()`, `disposeAll()`,
+     * `getAll()` and `size` exactly like one the factory created itself.
+     */
+    register(logger, name) {
+        this.loggers.set(name ?? logger.name, logger);
+        return logger;
+    }
     /** Returns an existing logger. */
     get(name) {
         return this.loggers.get(name);

package/dist/loggerFormatter/loggerFormatter.core.js

@@ -1,6 +1,7 @@
 /**
  * Core logger formatter functions.
  */
+import { LoggerFormatterNotFoundError } from "../loggerErrors/loggerError.base.js";
 import { createLoggerFormatterId, isLoggerFormatterFunction, isLoggerFormatterObject, isLoggerFormatter, } from "./loggerFormatterGuard.js";
 /**
  * Creates a function-backed formatter.
@@ -20,7 +21,7 @@ export function createLoggerFormatter(formatter, options = {}) {
                 return formatter(entry, context);
             }
             if (typeof formatter === "string") {
-                throw new Error(`Cannot format with string identifier "${formatter}" directly. Resolve the formatter first.`);
+                throw new LoggerFormatterNotFoundError(formatter);
             }
             return formatter.format(entry, context);
         },
@@ -34,7 +35,7 @@ export function formatLoggerEntry(formatter, entry, context = {}) {
         return formatter(entry, context);
     }
     if (typeof formatter === "string") {
-        throw new Error(`Cannot format with string identifier "${formatter}" directly. Resolve the formatter first.`);
+        throw new LoggerFormatterNotFoundError(formatter);
     }
     return formatter.format(entry, context);
 }

package/dist/loggerFormatter/loggerFormatterFormatters/loggerFormatterFormatters.json.js

@@ -12,29 +12,42 @@ function removeUndefinedValues(value, seen = new WeakSet()) {
             return "[Circular]";
         }
         seen.add(value);
-        return value.map((item) => removeUndefinedValues(item, seen));
+        try {
+            return value.map((item) => removeUndefinedValues(item, seen));
+        }
+        finally {
+            seen.delete(value);
+        }
     }
     if (value && typeof value === "object" && !(value instanceof Date)) {
         // Without a cycle guard this walk recursed until the stack blew,
         // and the resulting RangeError was swallowed by dispatch — losing
-        // the log line rather than reporting the offending value.
+        // the log line rather than reporting the offending value. `seen`
+        // tracks the ancestor path only (unmarked on ascent), so an object
+        // referenced twice in one payload is kept rather than collapsing
+        // to "[Circular]" from its second occurrence on.
         if (seen.has(value)) {
             return "[Circular]";
         }
         seen.add(value);
-        const result = {};
-        for (const [key, item] of Object.entries(value)) {
-            if (item === undefined) {
-                continue;
+        try {
+            const result = {};
+            for (const [key, item] of Object.entries(value)) {
+                if (item === undefined) {
+                    continue;
+                }
+                Object.defineProperty(result, key, {
+                    value: removeUndefinedValues(item, seen),
+                    enumerable: true,
+                    writable: true,
+                    configurable: true,
+                });
             }
-            Object.defineProperty(result, key, {
-                value: removeUndefinedValues(item, seen),
-                enumerable: true,
-                writable: true,
-                configurable: true,
-            });
+            return result;
+        }
+        finally {
+            seen.delete(value);
         }
-        return result;
     }
     return value;
 }

package/dist/loggerLevel/loggerLevel.type.js

@@ -4,6 +4,7 @@
  * Lower numeric values represent more severe messages.
  * Higher numeric values represent more verbose messages.
  */
+import { InvalidLoggerLevelError } from "../loggerErrors/loggerError.base.js";
 export var LoggerLevel;
 (function (LoggerLevel) {
     LoggerLevel[LoggerLevel["FATAL"] = 0] = "FATAL";
@@ -29,7 +30,7 @@ export function loggerLevelToName(level) {
         case LoggerLevel.TRACE:
             return "trace";
         default:
-            throw new RangeError(`Unknown logger level: ${String(level)}`);
+            throw new InvalidLoggerLevelError(level);
     }
 }
 /** Converts a logger level name into its enum value. */
@@ -50,7 +51,7 @@ export function loggerLevelFromName(name) {
         case "trace":
             return LoggerLevel.TRACE;
         default:
-            throw new RangeError(`Unknown logger level name: "${name}"`);
+            throw new InvalidLoggerLevelError(name);
     }
 }
 /** Checks whether a value is a valid LoggerLevel. */

package/dist/loggerManager/loggerManager.core.d.ts

@@ -16,6 +16,16 @@ export declare class LoggerManager {
     constructor(options?: LoggerOptions);
     /** Initializes the logger manager. Initialization is idempotent. */
     initialize(options?: LoggerOptions): Logger;
+    /**
+     * Adopts an existing logger as the manager's default logger.
+     *
+     * The logger is REGISTERED with the underlying factory, so it is
+     * covered by flush(), close(), getAll() and size. Assigning it to the
+     * private default field alone (as createLoggerManagerFromLogger used
+     * to) left the registry empty, making flush()/close() no-ops for the
+     * only logger the manager owned.
+     */
+    adopt(logger: Logger): Logger;
     /** Returns the default application logger. Lazily initializes when necessary. */
     getLogger(): Logger;
     /** Returns a named logger. Named loggers are managed by the underlying factory. */

package/dist/loggerManager/loggerManager.core.js

@@ -1,3 +1,4 @@
+import { LoggerDisposedError } from "../loggerErrors/loggerError.base.js";
 import { createLogger } from "../loggerCore/core/loggerCore.core.js";
 import { createDefaultLogger } from "../loggerCore/helpers/loggerCore.helper.js";
 import { createLoggerFactory } from "../loggerFactory/loggerFactory.core.js";
@@ -19,7 +20,7 @@ export class LoggerManager {
     /** Initializes the logger manager. Initialization is idempotent. */
     initialize(options = {}) {
         if (this.closed)
-            throw new Error("LoggerManager has been closed.");
+            throw new LoggerDisposedError("LoggerManager");
         if (this.initialized && this.defaultLogger)
             return this.defaultLogger;
         const logger = this.factory.create(options.name ?? "zudojs", options);
@@ -27,10 +28,27 @@ export class LoggerManager {
         this.initialized = true;
         return logger;
     }
+    /**
+     * Adopts an existing logger as the manager's default logger.
+     *
+     * The logger is REGISTERED with the underlying factory, so it is
+     * covered by flush(), close(), getAll() and size. Assigning it to the
+     * private default field alone (as createLoggerManagerFromLogger used
+     * to) left the registry empty, making flush()/close() no-ops for the
+     * only logger the manager owned.
+     */
+    adopt(logger) {
+        if (this.closed)
+            throw new LoggerDisposedError("LoggerManager");
+        this.factory.register(logger);
+        this.defaultLogger = logger;
+        this.initialized = true;
+        return logger;
+    }
     /** Returns the default application logger. Lazily initializes when necessary. */
     getLogger() {
         if (this.closed)
-            throw new Error("LoggerManager has been closed.");
+            throw new LoggerDisposedError("LoggerManager");
         if (!this.defaultLogger)
             return this.initialize();
         return this.defaultLogger;
@@ -38,13 +56,13 @@ export class LoggerManager {
     /** Returns a named logger. Named loggers are managed by the underlying factory. */
     get(name, options = {}) {
         if (this.closed)
-            throw new Error("LoggerManager has been closed.");
+            throw new LoggerDisposedError("LoggerManager");
         return this.factory.getOrCreate(name, options);
     }
     /** Creates a new logger even when another logger with the same name already exists. */
     create(name, options = {}) {
         if (this.closed)
-            throw new Error("LoggerManager has been closed.");
+            throw new LoggerDisposedError("LoggerManager");
         return this.factory.create(name, options, true);
     }
     /** Checks whether a named logger exists. */
@@ -99,7 +117,7 @@ export class LoggerManager {
     /** Provides direct access to the underlying factory. */
     getFactory() {
         if (this.closed)
-            throw new Error("LoggerManager has been closed.");
+            throw new LoggerDisposedError("LoggerManager");
         return this.factory;
     }
 }
@@ -120,8 +138,7 @@ export function createManagedDefaultLogger(name = "zudojs") {
 /** Creates a logger manager from an existing logger. */
 export function createLoggerManagerFromLogger(logger) {
     const manager = new LoggerManager();
-    manager["defaultLogger"] = logger;
-    manager["initialized"] = true;
+    manager.adopt(logger);
     return manager;
 }
 /** Returns a logger from a manager or creates a fallback logger when no manager is supplied. */

package/dist/loggerTransport/loggerTransportComposite/loggerTransportComposite.buffered.js

@@ -4,6 +4,7 @@
 import { createLoggerTransport, writeLoggerTransport, } from "../loggerTransport.core.js";
 import { closeLoggerTransport, flushLoggerTransport, } from "../loggerTransportHelpers/loggerTransportHelpers.js";
 import { throwCollectedFailures } from "../../loggerErrors/loggerError.helpers.js";
+import { LoggerTransportClosedError } from "../../loggerErrors/loggerError.base.js";
 /**
  * Creates a transport that buffers entries before forwarding
  * them to another transport.
@@ -14,6 +15,7 @@ export function createBufferedLoggerTransport(transport, options = {}) {
     const flushInterval = options.flushInterval ?? 0;
     let timer;
     let deferredFailure;
+    let closed = false;
     // Each entry is written on its own: one failing write used to abort the
     // loop after the whole batch had already been spliced out, losing every
     // entry behind it. Only the entries that actually failed are dropped.
@@ -80,6 +82,12 @@ export function createBufferedLoggerTransport(transport, options = {}) {
         name: options.name ?? "buffered",
         enabled: options.enabled ?? true,
         async write(entry) {
+            // A write after close() used to be buffered and then silently
+            // dropped: nothing drains the buffer again. Refuse it instead so
+            // the caller learns the entry was not accepted.
+            if (closed) {
+                throw new LoggerTransportClosedError(options.name ?? "buffered");
+            }
             buffer.push(entry);
             if (buffer.length >= maxSize) {
                 await drain();
@@ -90,6 +98,7 @@ export function createBufferedLoggerTransport(transport, options = {}) {
         },
         flush,
         async close() {
+            closed = true;
             if (timer) {
                 clearTimeout(timer);
                 timer = undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zudojs/logger",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Structured logging with transports, log levels, and context propagation for Zudojs applications.",
   "license": "MIT",
   "author": {
@@ -28,7 +28,7 @@
     "node": ">=24.0.0"
   },
   "dependencies": {
-    "@zudojs/errors": "1.1.0"
+    "@zudojs/errors": "1.2.0"
   },
   "devDependencies": {
     "typescript": "7.0.2",