Logger

@hyperse/logger

A high-performance, extensible logging framework with type safety, multiple log levels, rich formatting, and plugin support. Ideal for applications needing structured, reliable, and scalable logging.

pluginadaptermiddlewaresentryloggerhypersepluggable-loggertypescript

Quick start

git clone https://github.com/hyperse-io/logger.git

Hyperse Logger

A powerful, pluggable, and flexible type-safe logger for modern applications.

✨ Features

🔌 Plugin Architecture: Extensible logging through a powerful plugin system
🎯 Multiple Log Levels: Support for Error, Warn, Info, Debug, and Verbose levels
⚡ Pipeline Processing: Built on Hyperse Pipeline for efficient message processing
🎨 Customizable Context: Extend logger context with custom properties
🛡️ TypeScript Support: Full TypeScript support with comprehensive type definitions
🚀 High Performance: Optimized for production use with minimal overhead
🔧 Flexible Configuration: Easy setup with sensible defaults
📝 Rich Message Formatting: Support for structured logging with metadata
🔄 Async Support: Built-in support for asynchronous operations
🛠️ Error Handling: Comprehensive error handling and recovery mechanisms
🎭 Multiple Output Formats: Console, file, and custom output formats
🔍 Debugging Tools: Enhanced debugging capabilities with stack traces
🔄 Plugin Context Merging: Automatic merging and type inference of plugin contexts

📦 Installation

🚀 Quick Start

Basic Usage

Advanced Usage with Custom Context

🔌 Plugin System

Hyperse Logger uses a powerful plugin architecture that allows you to customize every aspect of the logging process. Plugins can be combined to create sophisticated logging pipelines.

Available Plugins

Console Plugin (`@hyperse/logger-plugin-console`)

A console plugin for @hyperse/logger that provides rich console output with customizable formatting, colors, and timestamps.

Features:

Support browser
Colored output for different log levels
Customizable timestamp formats
Configurable message formatting
Support for logger and plugin names
Prefix and metadata display

Quick Setup:

import { createConsolePlugin

📖 View detailed documentation →

Std Plugin (`@hyperse/logger-plugin-stdout`)

A standard output plugin for @hyperse/logger that provides rich terminal output with customizable formatting, colors, and timestamps. This plugin is designed specifically for Node.js environments and outputs to stdout/stderr.

Features:

Support node
Consistent output format
JSON-compatible formatting
Production-ready configuration
Structured logging support
Minimal overhead

Quick Setup:

import { createStdoutPlugin }

📖 View detailed documentation →

Creating Custom Plugins

You can create your own plugins using the definePlugin function:

Plugin Composition

Combine multiple plugins for sophisticated logging setups:

📊 Log Levels

Hyperse Logger supports five log levels, ordered by severity:

Level	Value	Description
`Error`	0	Critical errors that require immediate attention
`Warn`	1	Warnings that may need investigation
`Info`	2	General information and startup messages
`Debug`	3	Detailed debug information
`Verbose`	4	Additional detailed information

Setting Log Level

🎯 Message Types

The logger supports both string and object messages with rich metadata:

String Messages

logger.info('Simple string message');
logger.error('Error occurred'

Object Messages

Message with Function Style

The logger supports function-style messages that provide access to context:

Error Objects

🔧 Configuration Options

Logger Options

🏗️ Architecture

Hyperse Logger is built on top of the Hyperse Pipeline system, providing:

Pipeline Processing: Each log message goes through a configurable pipeline
Plugin Isolation: Plugins are isolated and can be composed independently
Context Sharing: Context is shared across the entire pipeline
Error Handling: Built-in error handling for pipeline failures
Type Safety: Full TypeScript support throughout the pipeline

Pipeline Flow

Log Message → Plugin 1 → Plugin 2 → ... → Plugin N → Output
     ↓           ↓         ↓              ↓
   Context    Context   Context       Context

Core Components

Logger: Main entry point for logging operations
Pipeline: Message processing engine
Plugins: Extensible output and processing modules
Context: Shared state across the pipeline
Message: Structured log data with metadata

🚀 Performance

Hyperse Logger is designed for high-performance applications:

Minimal Overhead: Optimized for production use
Async Processing: Non-blocking log operations
Memory Efficient: Efficient memory usage patterns
Configurable Buffering: Optional message buffering for high-throughput scenarios

@hyperse/pipeline - The pipeline system that powers Hyperse Logger
@hyperse/logger-plugin-console - Console output plugin
@hyperse/logger-plugin-stdout - Standard output plugin

License

This project is licensed under the MIT LICENSE.

# Install the core logger

npm install @hyperse/logger

# Install plugins for different output formats

npm install @hyperse/logger-plugin-console # Console output with colors

npm install @hyperse/logger-plugin-stdout # Standard output formatting

import { createLogger, LogLevel } from '@hyperse/logger';

import { createConsolePlugin } from '@hyperse/logger-plugin-console';

// Create a logger with console output

const logger = createLogger({

thresholdLevel: LogLevel.Info,

.use(createConsolePlugin())

logger.info('Application started');

logger.warn('Deprecated feature used');

logger.error('Something went wrong');

logger.debug('Debug information');

logger.verbose('Detailed debug info');

import { createLogger, LogLevel } from '@hyperse/logger';

import { createConsolePlugin } from '@hyperse/logger-plugin-console';

// Define custom context type

environment: 'development' | 'production';

// Create logger with custom context

const logger = createLogger<AppContext>({

thresholdLevel: LogLevel.Debug,

environment: 'development',

.use(createConsolePlugin())

.build(async () => ({

// Dynamic context that can be set per request

userId: getCurrentUserId(),

requestId: generateRequestId(),

logger.info('User login successful');

logger.error('Database connection failed');

'@hyperse/logger-plugin-console'

const consolePlugin = createConsolePlugin();

'@hyperse/logger-plugin-stdout'

const stdPlugin = createStdoutPlugin();

import { definePlugin, LogLevel } from '@hyperse/logger';

const filePlugin = definePlugin({

pluginName: 'file-logger',

execute: async ({ ctx, level, message, pipe }) => {

// Transform message format

timestamp: new Date().toISOString(),

level: LogLevel[level],

fs.appendFileSync('app.log', JSON.stringify(logEntry) + '\n');

// Use the custom plugin

const logger = createLogger().use(filePlugin).build();

import { createLogger } from '@hyperse/logger';

import { createConsolePlugin } from '@hyperse/logger-plugin-console';

import { createStdoutPlugin } from '@hyperse/logger-plugin-stdout';

const logger = createLogger()

.use(createConsolePlugin(), createStdoutPlugin())

import { LogLevel } from '@hyperse/logger';

const logger = createLogger({

thresholdLevel: LogLevel.Info, // Only logs Info, Warn, and Error

.use(createConsolePlugin())

message: 'User logged in successfully',

logger.verbose((ctx) => ({

message: 'Verbose message',

connectionPool: ctx.connectionPool, // ✅ Correctly infers types from plugin context

permissions: ctx.permissions, // ✅ Correctly infers types from plugin context

name: ctx.name, // ✅ Correctly infers types from plugin context

message: error.message,

const logger = createLogger({

name: 'my-app', // Logger name

thresholdLevel: LogLevel.Info, // Minimum log level

errorHandling: (error) => {

// Error handling function

console.error('Logger error:', error);

}).build(async () => ({

// Dynamic context setup

userId: getCurrentUserId(),

requestId: generateRequestId(),

@hyperse/logger

Hyperse Logger

✨ Features

📦 Installation

🚀 Quick Start

Basic Usage

Advanced Usage with Custom Context

🔌 Plugin System

Available Plugins

Console Plugin (@hyperse/logger-plugin-console)

Std Plugin (@hyperse/logger-plugin-stdout)

Creating Custom Plugins

Plugin Composition

📊 Log Levels

Setting Log Level

🎯 Message Types

String Messages

Object Messages

Message with Function Style

Error Objects

🔧 Configuration Options

Logger Options

🏗️ Architecture

Pipeline Flow

Core Components

🚀 Performance

🔗 Related Projects

License

Console Plugin (`@hyperse/logger-plugin-console`)

Std Plugin (`@hyperse/logger-plugin-stdout`)