@zudojs/logger

INSTALLATION

WHAT IT DOES

@zudojs/logger is the structured logging infrastructure for Zudojs. It provides:

• → Structured logging — every log entry is a typed LoggerEntry object, not a plain string
• → Six log levels — FATAL, ERROR, WARN, INFO, DEBUG, TRACE with numeric severity ordering
• → Multiple transports — console, buffered, conditional, and multi-transport composition
• → Formatters — JSON, text, compact, structured, development, and production formatters
• → Context propagation — correlationId, requestId, traceId, spanId, userId, tenantId, sessionId, jobId, moduleId, operationId
• → Child loggers — inherit parent configuration and merge metadata
• → Factory pattern — LoggerFactory manages logger creation, caching, and lifecycle
• → Lifecycle management — enable/disable, flush, close, and dispose operations
• → Buffered transport — batch entries before forwarding with configurable size and flush interval
• → Conditional transport — forward entries only when a predicate passes
• → Async logging — optional asynchronous dispatch with configurable transport timeout

WHERE IT SITS

@zudojs/logger sits in the infrastructure layer. Application code and feature packages create loggers. The logger formats entries and dispatches them to transports. Its only internal dependency is @zudojs/errors for the error hierarchy.

DEPENDENCIES

LOG LEVELS

Six severity levels with numeric ordering. Lower values represent more severe messages. The logger compares messageLevel <= threshold to decide whether to emit.

Enum: LoggerLevel

Type: LoggerLevelName

Type: LoggerLevelLike

Wherever you configure a level (createLogger({ level }), setLevel(), child({ level })), you can pass the enum value or its name in any case. "warning" and "information" also work, as aliases of "warn" and "info".

Utility Functions

Setting a level by name

Levels often come from an environment variable such as LOG_LEVEL=debug, so a name is accepted anywhere a level is. The logger stores the enum value, which is why logger.level prints a number.

LOGGER INTERFACE

The core contract every logger implementation satisfies. Application code depends on this interface, not concrete classes.

Interface: Logger

Methods

CREATING LOGGERS

Function: createLogger

Interface: LoggerOptions

Constants & Helpers

Example: Basic Logger

With no transports the logger writes to the console, one formatted line per call, using the default text formatter:

LOGGING ERRORS

When something throws, you usually want two things in the log: the error itself, with its stack trace (the list of function calls that led to it), and a few facts about what you were doing, such as an order id. The level methods take a message and a metadata object, so the typed way to send both is logger.log(level, message, { error, metadata }).

What you should see: the formatted line, then the stack on the lines below it (the file's directory is shortened to … here; yours shows the full path).

The level methods keep a single signature, logger.error(message, metadata?), so every custom Logger implementation and every structural logger type ({ warn(message, context?) }) still matches. JavaScript, or loosely typed TypeScript, often passes the caught error straight in as the second argument: logger.error("payment failed", err). Since 1.4.0 that call logs err as the entry's error, stack included, exactly like the log() call above (minus the metadata). It used to be read as metadata, and because an Error has no enumerable fields it vanished from the log without a trace.

Hiding stack traces

Stack frames contain absolute file paths from the machine the code runs on, which you may not want in logs that leave the server. Build the text formatter with includeStackTrace: false and every error is printed as its name and message only: the entry's own error, and any Error you put inside metadata.

Changed in 1.4.0: the option used to drop only the stack printed under the line; the fallback still wrote the stack, paths included, and an Error in metadata always carried its stack. With the default (true) nothing changes: the stack follows the line, and a metadata error prints as {"name":…,"message":…,"stack":…}.

CHILD LOGGERS

Child loggers inherit parent configuration (transports, formatter, level) and merge metadata. Every entry from a child logger includes both parent and child metadata.

Interface: ChildLoggerOptions

ChildLoggerOptions keeps the enum, so a custom Logger implementation written against it still compiles. Such an implementation may now be handed a name like "debug"; pass options.level through resolveLoggerLevel() to convert it.

Example: Child Loggers

Class: ContextLogger

A logger wrapper that provides scoped context. Every log call runs within the stored context.

LOG CONTEXT

A context is a set of correlation identifiers (request id, trace id, user id…) plus metadata that you want on every entry while handling one piece of work. Build one with createLoggerContext and attach it with logger.withContext(context), which returns a scoped logger; every entry that logger writes carries the context.

Interface: LoggerContext

Interface: LoggerContextIdentifiers

Interface: LoggerContextData

Interface: LoggerContextOptions

Context Functions

LOG ENTRY

Every log call produces a LoggerEntry — a frozen, typed object containing all data for that log event.

Interface: LoggerEntry

Interface: LoggerEntryInput

Related Types

Metadata Serialization

Metadata and context go through two passes. Redaction runs when the entry is created, before it is frozen, so no formatter and no transport can ever see an unmasked secret. Serialization runs inside the JSON and structured formatters, turning the values that are left into JSON-safe ones. Both walks descend through nested objects, arrays, Map, Set and getters, and both share the same cycle guard.

Changed in 1.3.0.

• → Map and Set keep their contents. They used to collapse to {}, so a headers Map or a tags Set reached the transport empty.
• → The cycle guard tracks the ancestor path only, instead of every object it has ever seen. { actor: user, target: user } now logs user in both fields; only a genuine back-edge — an object that contains itself — becomes "[Circular]". This applies to redaction, to serialization and to the JSON formatter alike.
• → A metadata getter that throws no longer propagates out of logger.info(...) and aborts your call. The field becomes "[Unreadable]", the entry is still logged, and the read failure is reported like any other infrastructure failure — dropped by default, rethrown when throwTransportErrors is on.

If you write your own formatter, the same serializers are exported. Both take an optional flag to leave stacks out: serializeLoggerError(error, false) returns { name, message }, and serializeLoggerValue(value, undefined, false) strips the stack from every Error it finds inside value.

Creating Entries

FORMATTERS

Formatters convert a LoggerEntry into output — either a string or a structured object. A transport always receives a LoggerEntry; the formatter's result travels with it in entry.formatted, while entry.message stays the message you logged.

Interface: LoggerFormatter

Interface: LoggerFormatterContext

Built-in Formatters

Formatter Output

timestamp prints as string because the structured formatter's ISO-8601 value is merged over the entry's Date. Before 1.3.0 the same transport saw the raw entry and printed object.

Options Interfaces

TRANSPORTS

Transports receive formatted entries and deliver them to their destination — console, file, network, or any custom sink. A logger can have multiple transports.

Interface: LoggerTransport

Built-in Transports

Console Output

With the default text formatter the console transport prints one line per entry: timestamp, level, logger name, message, then the metadata as key=value pairs. When the entry carries an error and the formatter includes stack traces, the stack follows on the next lines, with no trailing space left on the first line.

With createStructuredLoggerFormatter() each entry is one line of JSON, which is what log collectors expect. Values JSON cannot hold are made safe: a cycle becomes "[Circular]" and a bigint becomes a string.

Writing a transport

A transport can be a plain function. It receives the entry: entry.message is the message as you logged it, and entry.formatted is the line the logger's formatter produced. A transport that writes lines (a file, a socket, a stream) should print formatTransportLine(entry), which returns entry.formatted when it is set and otherwise the entry as one JSON line.

Transport Helpers

Buffered Transport Options

LOGGER FACTORY

LoggerFactory manages logger creation, caching, and lifecycle. It ensures consistent configuration across the application and prevents duplicate loggers.

Class: LoggerFactory

Factory Functions

Example: Factory Usage

register(logger, name?) puts an existing logger into the factory's registry under its own name, or under the name you pass. From then on it is covered by flushAll(), disposeAll(), getAll(), has() and size exactly like one the factory built itself. Without it, a hand-made logger is invisible to the factory and its transports are never flushed or closed on shutdown.

LOGGER MANAGER

LoggerManager provides application-wide logger management with initialization, lifecycle, and a default application logger.

Class: LoggerManager

Manager Functions

Example: Manager Usage

Adopting an existing logger

adopt(logger) (new in 1.3.0) makes a logger you built yourself the manager's default and registers it with the manager's factory, so flush(), close(), getAll() and size all reach it. It throws LoggerDisposedError if the manager is already closed.

createLoggerManagerFromLogger() is built on adopt(). Before 1.3.0 it only assigned the logger to a private field, leaving the factory registry empty: manager.size reported 0, getAll() returned nothing, and flush() / close() were no-ops for the only logger the manager owned — so buffered and file transports were never drained on shutdown.

ERROR HIERARCHY

All error types extend LoggingError from @zudojs/errors. The base LoggerError adds a loggerCode string for fine-grained classification.

FULL INTEGRATION EXAMPLE

Complete working example: factory, transports, formatters, context, and child loggers.

COMPLETE EXPORT INDEX

Every name @zudojs/logger exports from its package root at v1.4.0 — 153 in total, generated from the package’s own entry point rather than written by hand. The sections above explain the ones you reach for most; this is the exhaustive list, so nothing shipped is undocumented. Names not covered above are typically internal helpers and supporting types.