@superbuilders/slog

High-performance structured logging library inspired by Go's slog.

Features

• Zero-allocation byte buffer operations for maximum performance
• Structured logging with key-value attributes
• Automatic toString() handling for objects with custom toString methods
• Configurable log levels
• Optimized timestamp caching to minimize date formatting overhead
• Built for Node.js and Bun with ESNext targeting

Installation

npm install @superbuilders/slog
# or
bun add @superbuilders/slog

Quick Start

import*asloggerfrom'@superbuilders/slog'// Basic logginglogger.info("user logged in",{userId: "123",ip: "192.168.1.1"})logger.error("database connection failed",{error: err})// Set log levellogger.setDefaultLogLevel(logger.DEBUG)

API Reference

Log Levels

import{DEBUG,INFO,WARN,ERROR}from'@superbuilders/slog'// Available levels (lower numbers = more verbose)DEBUG// -4INFO// 0 (default)WARN// 4ERROR// 8

Logging Functions

// Level-specific functionslogger.debug("debug message",{key: "value"})logger.info("info message",{key: "value"})logger.warn("warning message",{key: "value"})logger.error("error message",{key: "value"})

Configuration

// Set minimum log levellogger.setDefaultLogLevel(WARN)// Only WARN and ERROR will be output

Performance Features

Zero-Allocation Design

• Uses pre-allocated byte buffers to avoid garbage collection pressure
• Direct ASCII byte writing for common string operations
• Optimized object serialization with custom toString() detection

Timestamp Caching

• Caches formatted timestamps to avoid repeated date formatting
• Sub-second precision with efficient updates

Smart Serialization

• Fast path for arrays and common object types
• Automatic detection and use of custom toString() methods (Error objects, Date, etc.)
• Handles special number cases (NaN, Infinity) efficiently

Output Format

2024/05/27 10:15:30 INFO user logged in userId=123 ip=192.168.1.1
2024/05/27 10:15:31 ERROR database connection failed error=Connection timeout

Advanced Usage

Custom Error Handling

try{awaitriskyOperation()}catch(error){// Error objects automatically use toString()logger.error("operation failed",{ error,userId: "123"})}

Structured Data

logger.info("user action",{userId: "123",action: "purchase",items: ["item1","item2"],metadata: {source: "mobile",version: "2.1.0"}})

Performance Monitoring

conststart=Date.now()awaitlongRunningOperation()constduration=Date.now()-startlogger.info("operation completed",{operation: "data_export",
duration,recordCount: 1500})

TypeScript Support

Full TypeScript support with comprehensive type definitions:

import*asloggerfrom'@superbuilders/slog'// Type-safe attribute objectsinterfaceUserAttributes{userId: stringemail: stringrole: 'admin'|'user'}constattrs: UserAttributes={userId: "123",email: "user@example.com",role: "admin"}logger.info("user created",attrs)

License

0BSD

Contributing

Contributions welcome! Please ensure all changes maintain the zero-allocation performance characteristics.