Skip to content

README.md

Latest commit

 

History

History
205 lines (148 loc) · 6.23 KB

README.md

File metadata and controls

205 lines (148 loc) · 6.23 KB

@resq-sw/logger

npm License deps

Structured logging with log levels, decorators, and singleton management for Node.js and Bun.

Installation

bun add @resq-sw/logger

Zero runtime dependencies.

Quick Start

import { Logger, LogLevel } from "@resq-sw/logger";

const log = Logger.getLogger("[MyService]");

log.info("Server started", { port: 3000 });
log.warn("Disk usage high", { percent: 92 });
log.error("Connection failed", new Error("timeout"), { host: "db" });
log.debug("Cache hit", { key: "user:123" });

Output format: YYYY-MM-DD HH:mm:ss.SSS LEVEL [context] message {data}

API Reference

Logger Class

Logger.getLogger(context, options?): Logger

Returns a singleton Logger instance for the given context. Subsequent calls with the same context return the same instance.

new Logger(context, options?)

Creates a new Logger instance.

Option Type Default Description
minLevel LogLevel env-based Minimum log level
includeTimestamp boolean -- Include timestamps
colorize boolean -- Colorize output
logToFile boolean -- Write to file (server-side)
filePath string -- Log file path

Level resolution priority: options.minLevel > LOG_LEVEL env > BUN_LOG_LEVEL env > LogLevel.ERROR (production) / LogLevel.ALL (development).

Logger.setGlobalLogLevel(level: LogLevel): void

Sets the minimum log level for all existing logger instances.

Log Levels

enum LogLevel {
  NONE  = 0,  // No logging
  ERROR = 1,  // Errors only
  WARN  = 2,  // Errors + warnings
  INFO  = 3,  // + informational
  DEBUG = 4,  // + debug messages
  TRACE = 5,  // + trace messages
  ALL   = 6,  // Everything
}

Logging Methods

All methods accept an optional data parameter (Record<string, unknown>).

Method Min Level Console Method Description
info(message, data?) INFO console.info Informational messages
error(message, error?, data?) ERROR console.error Errors (auto-serializes Error objects)
warn(message, data?) WARN console.warn Warnings
debug(message, data?) DEBUG console.debug Debug messages
trace(message, data?) TRACE console.debug Trace messages (most verbose)
action(message, data?) INFO console.info Server actions / user interactions
success(message, data?) INFO console.info Success confirmations

Grouping

log.group("Request Processing");
log.info("Step 1");
log.info("Step 2");
log.groupEnd();

Timing

logger.time<T>(label, fn): Promise<T>

Measures and logs execution time of a sync or async function.

const result = await log.time("DB query", async () => {
  return await db.query("SELECT * FROM users");
});
// Logs: "DB query completed" { duration: "12.34ms" }

On error, logs the failure with duration and rethrows.

Decorators

@Log(options?)

Logs method entry and exit with optional argument and return value logging.

Option Type Default Description
logArgs boolean true Log method arguments
logResult boolean false Log return value
message string method name Custom message prefix
level LogLevelString "debug" Log level to use 
class UserService {
  @Log({ logArgs: true, logResult: true, level: "info" })
  async getUser(id: string) { return { id, name: "John" }; }
}

@LogTiming(options?)

Logs method execution time. Works with both sync and async methods.

Option Type Default Description
label string ClassName.methodName Custom timing label
threshold number 0 Only log if duration exceeds this (ms)
level LogLevelString "info" Log level to use 
class DataService {
  @LogTiming({ threshold: 100 })
  async fetchData() { /* only logged if > 100ms */ }
}

@LogError(options?)

Wraps method in try/catch, logs errors with stack traces.

Option Type Default Description
rethrow boolean true Rethrow after logging
message string "<method> error" Custom error prefix
includeStack boolean true Include stack trace in log 
class Api {
  @LogError({ rethrow: false, message: "API call failed" })
  async callApi() { throw new Error("Network error"); }
  // Error is logged but swallowed; method returns undefined
}

@LogClass(options?)

Class decorator that applies logging to all methods on the prototype.

Option Type Default Description
exclude string[] [] Method names to skip
logCalls boolean true Log method entry/exit
timing boolean false Log execution times 
@LogClass({ exclude: ["internalHelper"], timing: true })
class MyService {
  publicMethod() { /* logged with timing */ }
  internalHelper() { /* not logged */ }
}

Types

Exported types: LogData, LoggerOptions, LogLevel, LogLevelString, ColorKey, LogEntry, LogTransport, LogMethodOptions, LogTimingOptions, LogErrorOptions, LogClassOptions.

License

Apache-2.0