@zudojs/logger 1.2.0 → 1.4.0

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,9 +51,23 @@ export function loggerLevelFromName(name) {
         case "trace":
             return LoggerLevel.TRACE;
         default:
-            throw new RangeError(`Unknown logger level name: "${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/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/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/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/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.2.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.1.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"
   },