Structured logging with configurable severity levels and error-resilient execution.
## What is @hyperfrontend/logging?
@hyperfrontend/logging provides a production-grade logging abstraction that wraps console-like log functions from any backend (console, Winston, Bunyan) with runtime log level control and automatic error handling. Unlike basic console wrappers, this library enables dynamic severity filtering without code changes or environment restarts - adjust verbosity in running production systems via the `setLogLevel()` API.
The core `createLogger()` factory accepts custom log functions for each severity level (error, warn, log, info, debug), wrapping them with conditional execution based on current log level and automatic error suppression to prevent logging failures from crashing applications. A pre-configured [`logger`](https://www.hyperfrontend.dev/docs/libraries/logging/#api-logger) instance using console methods is available for immediate use.
### Key Features
- **[Runtime Log Level Control](https://www.hyperfrontend.dev/docs/libraries/logging/#api-Logger-prop-setLogLevel)** - Adjust logging verbosity dynamically via `setLogLevel()` without restarting processes
- **[Priority-Based Filtering](https://www.hyperfrontend.dev/docs/libraries/logging/#api-LogLevel)** - Log levels follow standard hierarchy (error > warn > log > info > debug) with automatic filtering
- **Error-Resilient Execution** - All log functions wrapped with error handlers to prevent logging failures from propagating
- **[Console Abstraction](https://www.hyperfrontend.dev/docs/libraries/logging/#api-createLogger)** - Accepts one console-like function per level, from console, Winston, Bunyan or a custom implementation
- **Conditional Execution** - Log functions only execute when current severity meets or exceeds configured threshold
- **Frozen Interfaces** - Logger instances are immutable to prevent runtime modification
- **Zero External Dependencies** - Self-contained implementation with no third-party runtime dependencies
- **Type-Safe API** - Full TypeScript support with strongly-typed log functions and levels
## Why Use @hyperfrontend/logging?
### Production Observability Without Restarts
Debugging production issues requires adjusting log verbosity on running systems without downtime. Traditional logging requires environment variable changes and process restarts, delaying issue resolution. This library exposes `setLogLevel()` APIs that adjust verbosity at runtime - increase debug output during incidents, then return to error-only logging once resolved. Integrate with admin endpoints or monitoring tools to control logging remotely.
### Prevent Logging Failures from Cascading
Logging operations can fail (network issues for remote transports, serialization errors for complex objects, disk space for file logs). Standard console methods throw synchronously, potentially crashing applications during log operations. This library wraps every log function with error suppression - if logging fails, the error is swallowed and execution continues. Your application stays stable even when logging infrastructure fails.
### Uniform Logging Interface Across Environments
Applications often use different logging libraries in different environments (console in development, Winston in Node.js production, browser-specific loggers in frontend). This creates environment-specific code branches and inconsistent log formats. Pass any backend's log functions to `createLogger()` and receive a uniform API across all environments. Switch underlying implementations without changing application code.
### Testable Logging Logic with Dependency Injection
Testing code with direct `console.log()` calls requires mocking global objects or capturing stdout, creating brittle tests. This library uses dependency injection - pass mock functions to `createLogger()` during tests to capture log output programmatically. Verify log messages, assert call counts, and test conditional logging behavior without environment manipulation.
### Minimize Production Log Volume Costs
Cloud logging services charge per log entry and storage volume. Applications using `console.log()` everywhere generate excessive logs, inflating costs without proportional debugging value. Set default log level to 'error' in production to capture only critical issues, then selectively enable verbose logging during investigations. Reduce log volume by 90%+ while maintaining debugging capabilities when needed.
## Installation
```bash
npm install @hyperfrontend/logging
```
## Quick Start
### Using the Pre-Configured Logger
```typescript
import { logger } from '@hyperfrontend/logging'
// Default level is 'error' - only error logs execute
logger.error('Critical failure', { code: 500 }) // ✅ Logged
logger.warn('Deprecation notice') // ❌ Filtered
logger.info('Request completed') // ❌ Filtered
// Increase verbosity at runtime
logger.setLogLevel('info')
logger.info('Request completed') // ✅ Now logged
// Check current level
console.log(logger.getLogLevel()) // 'info'
// Disable all logging
logger.setLogLevel('none')
```
### Creating Custom Loggers
```typescript
import { createLogger } from '@hyperfrontend/logging'
import winston from 'winston'
// Wrap Winston logger
const winstonLogger = createLogger(
winston.error.bind(winston),
winston.warn.bind(winston),
winston.log.bind(winston),
winston.info.bind(winston),
winston.debug.bind(winston)
)
// Custom logger with structured output
const structuredLogger = createLogger(
(msg, meta) => console.error(JSON.stringify({ level: 'error', msg, meta })),
(msg, meta) => console.warn(JSON.stringify({ level: 'warn', msg, meta })),
(msg, meta) => console.log(JSON.stringify({ level: 'log', msg, meta })),
(msg, meta) => console.info(JSON.stringify({ level: 'info', msg, meta })),
(msg, meta) => console.debug(JSON.stringify({ level: 'debug', msg, meta }))
)
```
### Dynamic Log Level Control
```typescript
import { createLogger } from '@hyperfrontend/logging'
import express from 'express'
const { error, warn, log, info, debug } = console
const logger = createLogger(error, warn, log, info, debug)
// Admin endpoint to control log level
const app = express()
app.post('/admin/log-level', (req, res) => {
const { level } = req.body
logger.setLogLevel(level)
res.json({ level: logger.getLogLevel() })
})
// Automatically increase verbosity during errors
process.on('uncaughtException', () => {
logger.setLogLevel('debug') // Enable debug logs for debugging
})
```
### Testing Logging Behavior
```typescript
import { createLogger } from '@hyperfrontend/logging'
test('logs only errors at error level', () => {
const error = jest.fn()
const warn = jest.fn()
const logger = createLogger(error, warn)
logger.setLogLevel('error')
logger.error('Critical')
logger.warn('Warning')
expect(error).toHaveBeenCalledWith('Critical')
expect(warn).not.toHaveBeenCalled()
})
```
### Channels and Timing
```typescript
import { createLogger } from '@hyperfrontend/logging'
const { error, warn, log, info, debug } = console
const logger = createLogger(error, warn, log, info, debug)
logger.setLogLevel('debug')
// channel() returns a sub-logger that prepends `[prefix]` to every emission.
// Nested channels chain with `:`; channel('build').channel('rollup') emits `[build:rollup]`.
const build = logger.channel('build')
build.info('starting') // [build] starting
build.channel('rollup').warn(':') // [build:rollup] :
// timed() wraps a sync call: success -> debug "
