@molecule/api-logger

Logger core interface for molecule.dev.

Provides an abstract logging interface with a built-in console logger. Use setLogger to swap in a provider like pino, winston, or loglevel.

Auto-generated, AI-first package reference for the molecule.dev ecosystem. It is written to be read by coding agents as much as by people, and is generated from this package's source — edit src/index.ts JSDoc, not this file.

Quick Start

import { logger, setLevel, setLogger, resetLogger } from '@molecule/api-logger'

// Use the default console logger
logger.info('Server started on port', 3000)
logger.warn('Rate limit approaching')
logger.error('Database connection failed', error)

// The minimum level defaults to 'info' — trace/debug are DROPPED until
// you lower the gate (or set LOG_LEVEL=debug in the environment):
setLevel('debug')
logger.debug('Request received', { method: 'GET', path: '/api' })

// Set a custom logger provider
import { log } from '@molecule/api-logger-loglevel'
setLogger(log)

// Reset to default console logger
resetLogger()

Type

core

Installation

npm install @molecule/api-logger @molecule/api-bond

API

Interfaces

Logger

Logger interface that all implementations must satisfy.

interface Logger {
  trace(...args: unknown[]): void
  debug(...args: unknown[]): void
  info(...args: unknown[]): void
  warn(...args: unknown[]): void
  error(...args: unknown[]): void
}

Types

LogLevel

Log levels supported by the logger.

type LogLevel = 'trace' | 'debug' | 'info' | 'warn' | 'error' | 'silent'

Functions

setLevel(level)

Sets the minimum log level. Messages below this level are silently dropped.

function setLevel(level: LogLevel): void

• level — The minimum log level to allow.

getLevel()

Returns the current minimum log level, resolving it from the LOG_LEVEL environment variable on first call if setLevel() has not been used yet.

function getLevel(): LogLevel

Returns: The active LogLevel.

setLogger(newLogger)

Registers a logger implementation as the active provider.

function setLogger(newLogger: Logger): void

• newLogger — The logger implementation to bond.

resetLogger()

Resets the logger back to the built-in console logger.

function resetLogger(): void

hasLogger()

Checks whether a custom logger provider is active — either bonded via setLogger() directly, or wired through bond('logger', provider) (the path every bond package's getLogger() and this module's own getCurrentLogger() honor). Reflects the actual bond registry rather than a flag private to setLogger(), so it stays accurate regardless of which wiring path bonded the provider.

function hasLogger(): boolean

Returns: true if a custom (non-console) logger provider is bonded.

Constants

logger

Singleton logger proxy. Each method delegates to the currently bonded logger at call time, so swapping providers via setLogger() takes effect immediately without re-importing.

Messages below the active minimum level (set via LOG_LEVEL env var or setLevel()) are silently dropped.

const logger: Logger

Available Providers

Provider	Package
Axiom	@molecule/api-logger-axiom
Console	@molecule/api-logger-console
Loglevel	@molecule/api-logger-loglevel
Pino	@molecule/api-logger-pino
Winston	@molecule/api-logger-winston

Injection Notes

Requirements

Peer dependencies:

• @molecule/api-bond ^1.0.1

Runtime Dependencies

• @molecule/api-bond

• logger.debug(...)/logger.trace(...) print nothing by default. The minimum level is 'info' (from the LOG_LEVEL env var, falling back to 'info' when unset/invalid). A "missing" debug line means the gate is filtering it — call setLevel('debug') or set LOG_LEVEL=debug; the logger is not broken.

• LOG_LEVEL is read lazily, on the first call that needs the level (logger.*/getLevel()), not at module-import time — and the result is then cached until setLevel() overrides it. This means an app that loads dotenv/.env AFTER its first transitive import of this module still sees LOG_LEVEL, as long as env loading finishes before the first log call (true in virtually every app — real logging starts after startup config, not during module evaluation).

• Filtering happens ONCE, here in the core, before the bonded provider is invoked. Provider bonds (pino/winston/loglevel) deliberately pass every level through, so this gate is the single knob — don't also configure a level in the bond unless you want a second, stricter gate.

• setLevel('silent') drops everything, including logger.error(...).

• hasLogger() reflects the bond registry, not just setLogger() calls: it also returns true after bond('logger', provider) wired a provider directly (the path every bond package's getLogger() uses).