@zudojs/logger 1.3.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.
@@ -164,10 +207,17 @@ 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.
+(`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
 

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,6 +4,7 @@
 import { formatLoggerEntry } from "../../../loggerFormatter/loggerFormatter.core.js";
 import { createLoggerTransport, writeLoggerTransport, } from "../../../loggerTransport/loggerTransport.core.js";
 import { isLoggerTransport } from "../../../loggerTransport/loggerTransportGuard.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";
 /**
@@ -60,16 +61,16 @@ async function withTransportTimeout(timeoutMs, transportName, operation) {
 /**
  * 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.
+ * `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, message: formatted };
+        return { ...entry, formatted };
     }
     if (formatted !== null &&
         typeof formatted === "object" &&
@@ -77,6 +78,7 @@ function toTransportPayload(entry, formatted) {
         return {
             ...entry,
             ...formatted,
+            formatted: toJsonLogLine(formatted),
         };
     }
     return entry;
@@ -104,12 +106,12 @@ function toFormatterError(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,
     };
-    await writeLoggerTransport(transport.transport, toTransportPayload(entry, formatted), transportContext);
+    await writeLoggerTransport(transport.transport, payload, transportContext);
 }
 /**
  * Formats an entry with the configured formatter.
@@ -132,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 = toTransportPayload(entry, formatted);
     const target = transport.transport;
     return typeof target === "function"
         ? target(payload, transportContext)
@@ -147,9 +148,9 @@ 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) {
         handleError(toFormatterError(resolveFormatterName(configuration), error));
@@ -166,7 +167,7 @@ export async function dispatchEntry(configuration, entry, handleError) {
             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) {
             handleError(toTransportError(transportName, error));
@@ -191,9 +192,9 @@ 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(toFormatterError(resolveFormatterName(configuration), error));
@@ -211,7 +212,7 @@ export function dispatchEntrySync(configuration, entry, handleError) {
             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(toTransportError(registered.name, error));

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

@@ -6,6 +6,18 @@ import { InvalidLoggerEntryError, LoggerConfigurationError, } from "../../../log
 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.
  */

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.
  */

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

@@ -1,25 +1,27 @@
 /**
  * ZudojsLogger lifecycle methods.
  */
-import { LoggerLevel } from "../../../loggerLevel/loggerLevel.type.js";
+import { resolveLoggerLevel, } from "../../../loggerLevel/loggerLevel.type.js";
 import { createLoggerTransport } from "../../../loggerTransport/loggerTransport.core.js";
 import { isLoggerTransport } from "../../../loggerTransport/loggerTransportGuard.js";
 import { LoggerConfigurationError } from "../../../loggerErrors/loggerError.base.js";
 import { throwCollectedFailures } from "../../../loggerErrors/loggerError.helpers.js";
 /**
- * Sets the logger level.
+ * Sets the logger level from an enum value or a case-insensitive name.
  */
 export function setLoggerLevel(ctx, level) {
     ctx.assertActive();
-    if (!Number.isInteger(level) ||
-        level < LoggerLevel.FATAL ||
-        level > LoggerLevel.TRACE) {
+    let resolved;
+    try {
+        resolved = resolveLoggerLevel(level);
+    }
+    catch {
         throw new LoggerConfigurationError(`Invalid logger level: ${String(level)}.`);
     }
     ctx.assertMutable();
     ctx.updateConfiguration({
         ...ctx.configuration,
-        level,
+        level: resolved,
     });
 }
 /**

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

@@ -20,9 +20,19 @@ export interface LoggerEntry {
      */
     readonly levelName: LoggerLevelName;
     /**
-     * Human-readable message.
+     * The message as the caller logged it. A transport receives it unchanged;
+     * the formatter's rendering of the whole record is in `formatted`.
      */
     readonly message: string;
+    /**
+     * The record rendered as one line by the logger's formatter: the string a
+     * text or JSON formatter returned, or the JSON line of the record an
+     * object formatter (`createStructuredLoggerFormatter`) returned. Set on
+     * entries a logger hands to its transports. Line-oriented transports
+     * print `entry.formatted ?? entry.message`; `message` is always the raw
+     * message the caller logged.
+     */
+    readonly formatted?: string;
     /**
      * Structured metadata.
      */

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

@@ -3,19 +3,23 @@
  */
 /**
  * Serializes an error-like object into a plain object.
+ *
+ * @param includeStack - `false` leaves the stack out (its frames carry
+ *   absolute file paths). Defaults to `true`.
  */
 export declare function serializeLoggerError(error: {
     name?: string;
     message: string;
     stack?: string;
-}): Record<string, unknown>;
+}, includeStack?: boolean): 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.
+ * taking the whole log line down. `includeErrorStack: false` leaves the
+ * stack out of every Error found in the value.
  */
-export declare function serializeLoggerValue(value: unknown, seen?: WeakSet<object>): unknown;
+export declare function serializeLoggerValue(value: unknown, seen?: WeakSet<object>, includeErrorStack?: boolean): unknown;
 //# sourceMappingURL=loggerEntryHelpers.valueSerialize.d.ts.map

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

@@ -4,13 +4,14 @@
 import { LOGGER_UNREADABLE_TOKEN } from "./loggerEntryHelpers.sanitize.js";
 /**
  * Serializes an error-like object into a plain object.
+ *
+ * @param includeStack - `false` leaves the stack out (its frames carry
+ *   absolute file paths). Defaults to `true`.
  */
-export function serializeLoggerError(error) {
-    return {
-        name: error.name,
-        message: error.message,
-        stack: error.stack,
-    };
+export function serializeLoggerError(error, includeStack = true) {
+    return includeStack
+        ? { name: error.name, message: error.message, stack: error.stack }
+        : { name: error.name, message: error.message };
 }
 /**
  * Converts arbitrary values into safer serializable values.
@@ -18,9 +19,10 @@ export function serializeLoggerError(error) {
  * `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.
+ * taking the whole log line down. `includeErrorStack: false` leaves the
+ * stack out of every Error found in the value.
  */
-export function serializeLoggerValue(value, seen = new WeakSet()) {
+export function serializeLoggerValue(value, seen = new WeakSet(), includeErrorStack = true) {
     if (value === null ||
         value === undefined ||
         typeof value === "string" ||
@@ -35,7 +37,7 @@ export function serializeLoggerValue(value, seen = new WeakSet()) {
         return value.toISOString();
     }
     if (value instanceof Error) {
-        return serializeLoggerError(value);
+        return serializeLoggerError(value, includeErrorStack);
     }
     if (typeof value === "function") {
         return `[Function ${value.name || "anonymous"}]`;
@@ -52,10 +54,10 @@ export function serializeLoggerValue(value, seen = new WeakSet()) {
     seen.add(value);
     try {
         if (Array.isArray(value)) {
-            return value.map((item) => serializeLoggerValue(item, seen));
+            return value.map((item) => serializeLoggerValue(item, seen, includeErrorStack));
         }
         if (value instanceof Set) {
-            return Array.from(value, (item) => serializeLoggerValue(item, seen));
+            return Array.from(value, (item) => serializeLoggerValue(item, seen, includeErrorStack));
         }
         const result = {};
         // defineProperty, never assignment: a "__proto__" key from an
@@ -71,7 +73,7 @@ export function serializeLoggerValue(value, seen = new WeakSet()) {
         };
         if (value instanceof Map) {
             for (const [key, item] of value.entries()) {
-                define(typeof key === "string" ? key : String(key), serializeLoggerValue(item, seen));
+                define(typeof key === "string" ? key : String(key), serializeLoggerValue(item, seen, includeErrorStack));
             }
             return result;
         }
@@ -84,7 +86,7 @@ export function serializeLoggerValue(value, seen = new WeakSet()) {
                 define(key, LOGGER_UNREADABLE_TOKEN);
                 continue;
             }
-            define(key, serializeLoggerValue(item, seen));
+            define(key, serializeLoggerValue(item, seen, includeErrorStack));
         }
         return result;
     }

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

@@ -1,5 +1,5 @@
 import type { Logger } from "../loggerCore/core/loggerCore.type.js";
-import type { LoggerOptions, ChildLoggerOptions } from "../loggerOptions/loggerOptions.type.js";
+import type { LoggerOptions, ChildLoggerOptionsInput } from "../loggerOptions/loggerOptions.type.js";
 /**
  * Factory responsible for creating and managing Zudojs loggers.
  *
@@ -29,7 +29,7 @@ export declare class LoggerFactory {
     /** Gets an existing logger or creates it. */
     getOrCreate(name: string, options?: LoggerOptions): Logger;
     /** Creates a child logger from an existing logger. */
-    child(parent: Logger, options?: ChildLoggerOptions): Logger;
+    child(parent: Logger, options?: ChildLoggerOptionsInput): Logger;
     /**
      * Removes a logger from the factory registry.
      *

package/dist/loggerFormatter/loggerFormatterFormatters/loggerFormatterFormatters.metadata.d.ts

@@ -3,12 +3,15 @@
  */
 /**
  * Formats metadata as key=value pairs.
+ *
+ * @param includeStackTrace - `false` leaves the stack out of any Error in
+ *   the metadata, as the text formatter's option of the same name promises.
  */
-export declare function formatMetadata(metadata: Record<string, unknown>, separator: string): string;
+export declare function formatMetadata(metadata: Record<string, unknown>, separator: string, includeStackTrace?: boolean): string;
 /**
  * Formats an arbitrary metadata value.
  */
-export declare function formatValue(value: unknown): string;
+export declare function formatValue(value: unknown, includeStackTrace?: boolean): string;
 /**
  * Formats an Error.
  *

package/dist/loggerFormatter/loggerFormatterFormatters/loggerFormatterFormatters.metadata.js

@@ -5,19 +5,22 @@ import { serializeLoggerError, serializeLoggerValue, } from "../../loggerEntry/l
 import { escapeLogText } from "../../loggerEntry/loggerEntryHelpers/loggerEntryHelpers.sanitize.js";
 /**
  * Formats metadata as key=value pairs.
+ *
+ * @param includeStackTrace - `false` leaves the stack out of any Error in
+ *   the metadata, as the text formatter's option of the same name promises.
  */
-export function formatMetadata(metadata, separator) {
+export function formatMetadata(metadata, separator, includeStackTrace = true) {
     return (Object.entries(metadata)
         .filter(([, value]) => value !== undefined)
         // Metadata KEYS are as attacker-influenceable as values (a header
         // name, a form field) and were previously interpolated raw.
-        .map(([key, value]) => `${escapeLogText(key)}=${formatValue(value)}`)
+        .map(([key, value]) => `${escapeLogText(key)}=${formatValue(value, includeStackTrace)}`)
         .join(separator));
 }
 /**
  * Formats an arbitrary metadata value.
  */
-export function formatValue(value) {
+export function formatValue(value, includeStackTrace = true) {
     if (value === null) {
         return "null";
     }
@@ -31,7 +34,8 @@ export function formatValue(value) {
         return escapeLogText(value);
     }
     if (typeof value === "object") {
-        return escapeLogText(JSON.stringify(serializeLoggerValue(value)));
+        const serialized = serializeLoggerValue(value, new WeakSet(), includeStackTrace);
+        return escapeLogText(JSON.stringify(serialized));
     }
     return escapeLogText(String(value));
 }
@@ -79,7 +83,10 @@ export function formatError(error, includeStackTrace) {
         }
         return `\n${lines.join("\n")}`;
     }
-    const serialized = serializeLoggerError(error);
+    // Name and message only: the fallback used to serialize the stack as
+    // well, so `includeStackTrace: false` still printed every frame (and the
+    // absolute paths in them) inside the JSON.
+    const serialized = serializeLoggerError(error, false);
     return `error=${escapeLogText(JSON.stringify(serialized))}`;
 }
 //# sourceMappingURL=loggerFormatterFormatters.metadata.js.map

package/dist/loggerFormatter/loggerFormatterFormatters/loggerFormatterFormatters.text.js

@@ -65,12 +65,16 @@ export function createTextLoggerFormatter(options = {}) {
             }
         }
         if (includeMetadata && Object.keys(entry.metadata).length > 0) {
-            parts.push(formatMetadata(entry.metadata, metadataSeparator));
+            parts.push(formatMetadata(entry.metadata, metadataSeparator, includeStackTrace));
         }
-        if (entry.error) {
-            parts.push(formatError(entry.error, includeStackTrace));
+        const line = parts.join(" ");
+        if (!entry.error) {
+            return line;
         }
-        return parts.join(" ");
+        // A stack starts on its own line; joining it with " " left a trailing
+        // space after the message.
+        const error = formatError(entry.error, includeStackTrace);
+        return error.startsWith("\n") ? `${line}${error}` : `${line} ${error}`;
     }, { name: options.name ?? "text" });
 }
 //# sourceMappingURL=loggerFormatterFormatters.text.js.map

package/dist/loggerLevel/loggerLevel.type.d.ts

@@ -14,10 +14,23 @@ export declare enum LoggerLevel {
 }
 /** String representation of supported logger levels. */
 export type LoggerLevelName = "fatal" | "error" | "warn" | "info" | "debug" | "trace";
+/**
+ * A level as configuration accepts it: the enum value, or its name in any
+ * case (`"error"`, `"ERROR"`). `"warning"` and `"information"` are accepted
+ * at runtime as aliases of `"warn"` and `"info"`.
+ */
+export type LoggerLevelLike = LoggerLevel | LoggerLevelName | Uppercase<LoggerLevelName>;
 /** Converts a logger level into its canonical name. */
 export declare function loggerLevelToName(level: LoggerLevel): LoggerLevelName;
 /** Converts a logger level name into its enum value. */
 export declare function loggerLevelFromName(name: LoggerLevelName | string): LoggerLevel;
+/**
+ * Resolves a configured level (enum value or case-insensitive name) to its
+ * enum value.
+ *
+ * @throws InvalidLoggerLevelError when the value is neither.
+ */
+export declare function resolveLoggerLevel(level: LoggerLevelLike): LoggerLevel;
 /** Checks whether a value is a valid LoggerLevel. */
 export declare function isLoggerLevel(value: unknown): value is LoggerLevel;
 /** Checks whether a value is a valid logger level name. */

package/dist/loggerLevel/loggerLevel.type.js

@@ -54,6 +54,20 @@ export function loggerLevelFromName(name) {
             throw new InvalidLoggerLevelError(name);
     }
 }
+/**
+ * Resolves a configured level (enum value or case-insensitive name) to its
+ * enum value.
+ *
+ * @throws InvalidLoggerLevelError when the value is neither.
+ */
+export function resolveLoggerLevel(level) {
+    const value = level;
+    if (isLoggerLevel(value))
+        return value;
+    if (typeof value === "string")
+        return loggerLevelFromName(value.trim());
+    throw new InvalidLoggerLevelError(value);
+}
 /** Checks whether a value is a valid LoggerLevel. */
 export function isLoggerLevel(value) {
     return (typeof value === "number" &&

package/dist/loggerOptions/loggerOptions.type.d.ts

@@ -1,4 +1,4 @@
-import { LoggerLevel } from "../loggerLevel/loggerLevel.type.js";
+import { LoggerLevel, type LoggerLevelLike } from "../loggerLevel/loggerLevel.type.js";
 import type { LoggerContextData } from "../loggerContext/loggerContext.core.js";
 import type { LoggerFormatterLike } from "../loggerFormatter/loggerFormatter.type.js";
 import type { LoggerTransportLike } from "../loggerTransport/loggerTransport.type.js";
@@ -6,7 +6,8 @@ import type { LoggerRedactionOptions } from "../loggerEntry/loggerEntryHelpers/l
 /** Options used to configure a Zudojs logger. */
 export interface LoggerOptions {
     readonly name?: string;
-    readonly level?: LoggerLevel;
+    /** Threshold: `LoggerLevel.WARN`, or a name such as `"warn"` / `"WARN"`. */
+    readonly level?: LoggerLevelLike;
     readonly environment?: string;
     readonly metadata?: LoggerContextData;
     readonly formatter?: LoggerFormatterLike;
@@ -33,6 +34,16 @@ export interface ChildLoggerOptions {
     readonly metadata?: LoggerContextData;
     readonly level?: LoggerLevel;
 }
+/**
+ * What `Logger.child()` accepts: `ChildLoggerOptions` whose `level` may also
+ * be a name (`"debug"`, `"DEBUG"`). `ChildLoggerOptions` itself keeps the
+ * enum, so a custom logger that reads `options.level` still compiles; one
+ * that may be handed a name should pass it through `resolveLoggerLevel()`.
+ */
+export interface ChildLoggerOptionsInput extends Omit<ChildLoggerOptions, "level"> {
+    /** Threshold: `LoggerLevel.DEBUG`, or a name such as `"debug"`. */
+    readonly level?: LoggerLevelLike;
+}
 /** Options for a single log operation. */
 export interface LogOptions {
     readonly metadata?: LoggerContextData;
@@ -74,5 +85,5 @@ export declare function resolveLoggerOptions(options?: LoggerOptions): LoggerCon
 /** Merges two logger option objects. Values from `override` take precedence. */
 export declare function mergeLoggerOptions(base: LoggerOptions, override: LoggerOptions): LoggerOptions;
 /** Creates options for a child logger. */
-export declare function createChildLoggerOptions(parent: LoggerConfiguration, options?: ChildLoggerOptions): LoggerOptions;
+export declare function createChildLoggerOptions(parent: LoggerConfiguration, options?: ChildLoggerOptionsInput): LoggerOptions;
 //# sourceMappingURL=loggerOptions.type.d.ts.map

package/dist/loggerOptions/loggerOptions.type.js

@@ -1,4 +1,4 @@
-import { LoggerLevel } from "../loggerLevel/loggerLevel.type.js";
+import { LoggerLevel, resolveLoggerLevel, } from "../loggerLevel/loggerLevel.type.js";
 /** Default logger configuration values. */
 export const DEFAULT_LOGGER_OPTIONS = {
     enabled: true,
@@ -29,7 +29,9 @@ export function resolveLoggerOptions(options = {}) {
     validateLoggerOptions(options);
     return Object.freeze({
         name: options.name ?? "zudojs",
-        level: options.level ?? LoggerLevel.INFO,
+        level: options.level === undefined
+            ? LoggerLevel.INFO
+            : resolveLoggerLevel(options.level),
         environment: options.environment,
         metadata: Object.freeze({ ...(options.metadata ?? {}) }),
         formatter: options.formatter ?? "text",
@@ -57,7 +59,9 @@ export function mergeLoggerOptions(base, override) {
 export function createChildLoggerOptions(parent, options = {}) {
     return {
         name: options.name ?? parent.name,
-        level: options.level ?? parent.level,
+        level: options.level === undefined
+            ? parent.level
+            : resolveLoggerLevel(options.level),
         environment: parent.environment,
         metadata: { ...parent.metadata, ...(options.metadata ?? {}) },
         formatter: parent.formatter,

package/dist/loggerTransport/loggerTransportConsole/loggerTransportConsole.core.d.ts

@@ -5,8 +5,9 @@ import type { LoggerTransportOptions, RegisteredLoggerTransport } from "../logge
 /**
  * Creates a simple console transport.
  *
- * Uses the standard console methods rather than depending on
- * Node.js-specific APIs.
+ * Prints one line per record through the standard console methods (no
+ * Node.js-specific APIs): `entry.formatted` when the logger's formatter
+ * produced it, otherwise the entry as a single JSON line.
  */
 export declare function createConsoleLoggerTransport(options?: LoggerTransportOptions): RegisteredLoggerTransport;
 //# sourceMappingURL=loggerTransportConsole.core.d.ts.map

package/dist/loggerTransport/loggerTransportConsole/loggerTransportConsole.core.js

@@ -2,19 +2,24 @@
  * Console logger transport.
  */
 import { createLoggerTransport } from "../loggerTransport.core.js";
-import { serializeTransportEntry } from "../loggerTransportHelpers/loggerTransportHelpers.js";
+import { formatTransportLine } from "../loggerTransportHelpers/loggerTransportHelpers.js";
 /**
  * Creates a simple console transport.
  *
- * Uses the standard console methods rather than depending on
- * Node.js-specific APIs.
+ * Prints one line per record through the standard console methods (no
+ * Node.js-specific APIs): `entry.formatted` when the logger's formatter
+ * produced it, otherwise the entry as a single JSON line.
  */
 export function createConsoleLoggerTransport(options = {}) {
     const transport = {
         name: options.name ?? "console",
         enabled: options.enabled ?? true,
         write(entry) {
-            const payload = serializeTransportEntry(entry);
+            // One line per record: the formatter's line (text or JSON), or the
+            // entry as JSON. Printing the record object showed the timestamp and
+            // level twice beside a text line, and spread a structured record over
+            // several lines of console output.
+            const payload = formatTransportLine(entry);
             switch (entry.levelName) {
                 case "fatal":
                 case "error":

package/dist/loggerTransport/loggerTransportHelpers/index.d.ts

@@ -3,5 +3,5 @@
  *
  * Transport helper functions.
  */
-export { serializeTransportEntry, closeLoggerTransport, flushLoggerTransport, } from "./loggerTransportHelpers.js";
+export { serializeTransportEntry, toJsonLogLine, formatTransportLine, closeLoggerTransport, flushLoggerTransport, } from "./loggerTransportHelpers.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/loggerTransport/loggerTransportHelpers/index.js

@@ -3,5 +3,5 @@
  *
  * Transport helper functions.
  */
-export { serializeTransportEntry, closeLoggerTransport, flushLoggerTransport, } from "./loggerTransportHelpers.js";
+export { serializeTransportEntry, toJsonLogLine, formatTransportLine, closeLoggerTransport, flushLoggerTransport, } from "./loggerTransportHelpers.js";
 //# sourceMappingURL=index.js.map

package/dist/loggerTransport/loggerTransportHelpers/loggerTransportHelpers.d.ts

@@ -7,6 +7,21 @@ import type { LoggerTransportLike } from "../loggerTransport.type.js";
  * Converts a LoggerEntry into a console-friendly object.
  */
 export declare function serializeTransportEntry(entry: LoggerEntry): Record<string, unknown>;
+/**
+ * Renders a record as one line of JSON.
+ *
+ * Values go through `serializeLoggerValue` first, so a cycle becomes
+ * `"[Circular]"`, a BigInt its decimal string and an Error its name,
+ * message and stack. `JSON.stringify` escapes `\n`; U+2028 and U+2029,
+ * which it leaves raw and some viewers break lines on, are escaped too.
+ */
+export declare function toJsonLogLine(record: unknown): string;
+/**
+ * The text a line-oriented transport (console, file, stream) prints for an
+ * entry: the formatter's line when there is one, otherwise the entry as a
+ * single JSON line.
+ */
+export declare function formatTransportLine(entry: LoggerEntry): string;
 /**
  * Safely closes a transport.
  */

package/dist/loggerTransport/loggerTransportHelpers/loggerTransportHelpers.js

@@ -42,6 +42,28 @@ export function serializeTransportEntry(entry) {
             : {}),
     };
 }
+/**
+ * Renders a record as one line of JSON.
+ *
+ * Values go through `serializeLoggerValue` first, so a cycle becomes
+ * `"[Circular]"`, a BigInt its decimal string and an Error its name,
+ * message and stack. `JSON.stringify` escapes `\n`; U+2028 and U+2029,
+ * which it leaves raw and some viewers break lines on, are escaped too.
+ */
+export function toJsonLogLine(record) {
+    const json = JSON.stringify(serializeLoggerValue(record)) ?? "null";
+    return json.replace(/\u2028/gu, "\\u2028").replace(/\u2029/gu, "\\u2029");
+}
+/**
+ * The text a line-oriented transport (console, file, stream) prints for an
+ * entry: the formatter's line when there is one, otherwise the entry as a
+ * single JSON line.
+ */
+export function formatTransportLine(entry) {
+    return typeof entry.formatted === "string"
+        ? entry.formatted
+        : toJsonLogLine(serializeTransportEntry(entry));
+}
 /**
  * Safely closes a transport.
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zudojs/logger",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "description": "Structured logging with transports, log levels, and context propagation for Zudojs applications.",
   "license": "MIT",
   "author": {
@@ -28,11 +28,11 @@
     "node": ">=24.0.0"
   },
   "dependencies": {
-    "@zudojs/errors": "1.2.0"
+    "@zudojs/errors": "1.3.0"
   },
   "devDependencies": {
     "typescript": "7.0.2",
-    "vitest": "^4.1.11"
+    "vitest": "^5.0.1"
   },
   "publishConfig": {
     "access": "public"
@@ -43,7 +43,7 @@
     "structured-logs",
     "transports"
   ],
-  "homepage": "https://github.com/oyinlola-tech/zudo#readme",
+  "homepage": "https://zudojs.oyinlola.site/docs/packages-logger",
   "bugs": {
     "url": "https://github.com/oyinlola-tech/zudo/issues"
   },