Logger

Logger is the central orchestrator. It holds a list of channels and forwards every log call to all of them. log is the pre-instantiated singleton exported from the package.

Note

Logger starts with no channels. Register at least one via addChannel or setChannels before any output is produced.

Quick lookup

I want to…	Use
Log at info level	log.info("module", "action", "message")
Register a channel	log.addChannel(myChannel)
Retrieve a channel by name	log.channel("console")
Drop everything below a severity	log.setMinLevel("info")
Strip secrets from every entry	log.setRedact({ paths: ["context.password"] })
Time how long an operation took	const end = log.timer("db", "query"); end()
Log an error if a condition fails	log.assert(condition, "module", "action", "message")

Methods

Method	Signature	Description
addChannel	(channel: LogChannel): this	Register a new channel. Chainable.
setChannels	(channels: LogChannel[]): this	Replace the full channel list.
configure	(config: { channels?: LogChannel[]; autoFlushOn?: AutoFlushEvent[]; minLevel?: LogLevel; redact?: RedactConfig; onChannelError?: ChannelErrorHandler }): this	One-shot setup: channel list, auto-flush handlers, severity floor, redaction floor, channel error handler. Every field optional.
onChannelError	(handler: (error: unknown, channel: LogContract, entry: LoggingData) => void | Promise<void>): this	Receive a channel’s sync throw or async rejection, a redaction that threw, a timed-out flush(), or a channel’s own background failure (FileLog retention). Default: one stderr line. May be async (a rejection is swallowed). Never log through the same logger from it.
log	(data: LoggingData): this	Pass a fully formed LoggingData object through all channels. Synchronous and fire-and-forget (since 5.30.0): async deliveries are tracked for flush(), channel failures go to onChannelError.
debug	(dataOrModule: OmittedLoggingData | string, action?: string, message?: any, context?: Record<string, any>): this	Log at debug.
info	(dataOrModule, action?, message?, context?): this	Log at info.
warn	(dataOrModule, action?, message?, context?): this	Log at warn.
error	(dataOrModule, action?, message?, context?): this	Log at error.
success	(dataOrModule, action?, message?, context?): this	Log at success.
fatal	(dataOrModule, action?, message?, context?): this	Log at fatal — unrecoverable failures, app is going down. Does NOT auto-flush or exit.
assert	(condition: unknown, module: string, action: string, message: any, context?: Record<string, any>): this	Log an error entry when condition is falsy; genuinely free no-op when truthy.
timer	(module: string, action: string): (extra?: Record<string, any>) => this	Start a duration timer. The returned function emits an info entry with completed in <ms>ms and a durationMs field in context.
channel	(name: string): LogChannel | undefined	Find a registered channel by its name property.
flushSync	(): void	Synchronously invoke flushSync() on every channel that implements it.
flush	(options?: { timeout?: number }): Promise<void>	Per channel, concurrently: wait for its in-flight async deliveries (including ones logged during the flush), then await its flush(). Resolves after timeout ms at most (default DEFAULT_FLUSH_TIMEOUT_MS, 5000; Infinity waits without a limit) and reports each channel still draining to onChannelError. The async path for graceful shutdown of network/async channels.
enableAutoFlush	(events: AutoFlushEvent[]): this	Register one process handler per event that flushes before exit. Signals are flushed + re-raised; beforeExit is flushed in place. Idempotent — replaces previous handlers.
disableAutoFlush	(): this	Remove every handler installed by enableAutoFlush. Safe with none registered.
setMinLevel	(level: LogLevel | undefined): this	Drop entries below level before fan-out. undefined clears.
getMinLevel	(): LogLevel | undefined	Read the active minimum severity.
setRedact	(config: RedactConfig | undefined): this	Set the logger-wide redaction floor (applied once before fan-out). See Redaction.
getRedact	(): RedactConfig | undefined	Read the active redaction floor.

Fields

Field	Type	Description
channels	LogChannel[]	The currently registered channel list.
id	string	Unique identifier for this logger instance.

Examples

import { log, ConsoleLog, FileLog } from "@warlock.js/logger";

// Register channels via the fluent API
log.addChannel(new ConsoleLog()).addChannel(new FileLog({ storagePath: "./logs", name: "app" }));

// Positional shorthand — (module, action, message, context?)
log.info("UserService", "login", "User authenticated");

// Full data object — level implied by log.log
log.log({
  type: "info",
  module: "UserService",
  action: "login",
  message: "User authenticated",
});

// Retrieve a registered channel by name
const file = log.channel("file");

// Drop debug noise globally — fast-path filter
log.setMinLevel("info");

// Strip secrets before any channel sees them
log.setRedact({ paths: ["context.password", "context.*.token"] });

// Time an operation
const end = log.timer("db", "query");
const rows = await db.query(sql);
await end({ rowCount: rows.length });

// Assertion — logs at error when condition is falsy, no-op otherwise
log.assert(user !== null, "auth", "session", "user vanished mid-flight", { sessionId });

No bare callable

log is not a function. log({ type, module, action, message }) won’t compile — use log.log({...}) for the data-object form, or any level shortcut for the positional form.

See also

• Types — LoggingData, OmittedLoggingData, LogLevel, AutoFlushEvent, RedactConfig
• LogChannel — the base class for custom channels