@guiiai/logg

Lightweight structured logger for Node.js and browser with stack parsing, caller records, and clickable hyperlinks.

Quick Start

import { initLogger, useGlobalLogger } from '@guiiai/logg'

// Initialize with defaults (Verbose level, Pretty format)
initLogger()

const log = useGlobalLogger('MyApp')
log.log('Hello world!')

Core API

Creating Loggers

import { createLogg, createLogger, createGlobalLogger } from '@guiiai/logg'

// Named context
const log = createLogg('http/request').useGlobalConfig()

// Auto-context from call site (includes file:line clickable hyperlinks)
const log = createLogger().useGlobalConfig()

// Auto-context + auto global config
const log = createGlobalLogger()

Aliases: useLogg = createLogg, useLogger = createLogger, useGlobalLogger = createGlobalLogger

Log Levels

import { LogLevel, setGlobalLogLevel, setGlobalLogLevelString } from '@guiiai/logg'

setGlobalLogLevel(LogLevel.Debug)
// or
setGlobalLogLevelString('debug')

Output Formats

import { Format, setGlobalFormat } from '@guiiai/logg'

setGlobalFormat(Format.Pretty) // Colored human-readable output
setGlobalFormat(Format.JSON)   // Structured JSON for production

JSON output:

{"level":"log","context":"app","timestamp":"2024-01-01T00:00:00.000Z","message":"User logged in","fields":{"userId":"123"}}

Pretty output:

[2024-01-01 00:00:00] LOG app: User logged in { userId: '123' }

Structured Fields

// Single field (fluent chaining)
log
  .withField('requestId', req.id)
  .withField('url', req.url)
  .error('Resource not found (404)')

// Multiple fields at once
log
  .withFields({ userId: '12345', ip: '192.168.1.1' })
  .log('User logged in')

Child Loggers

Child loggers inherit parent config and carry persistent fields:

const parentLog = createLogg('app').useGlobalConfig()

const childLog = parentLog.child({
  module: 'database',
  version: '1.0.0',
})

childLog.log('Connected') // includes module + version fields automatically

Error Handling

try {
  // ...
} catch (err) {
  // Automatically extracts message, stack trace, and cause
  log.withError(err).error('Operation failed')

  // Or inline
  log.errorWithError('Failed to process request', err)
}

Custom Processors

// Custom time format
const log = createLogg('app')
  .useGlobalConfig()
  .withTimeFormatter(date => date.toLocaleString('en-US', { timeZone: 'America/New_York' }))

// Custom error processor
const log = createLogg('app')
  .useGlobalConfig()
  .withErrorProcessor(err => {
    if (err instanceof CustomError) return { ...err, customField: 'value' }
    return err
  })

Configuration Methods (Fluent API)

All return a new logger instance (immutable):

Typical Setup Pattern

import { Format, initLogger, LogLevel, useGlobalLogger } from '@guiiai/logg'

// Once at app entry
initLogger(
  process.env.NODE_ENV === 'production' ? LogLevel.Log : LogLevel.Debug,
  process.env.NODE_ENV === 'production' ? Format.JSON : Format.Pretty,
)

// In each module
const log = useGlobalLogger('module-name')
log.log('ready')

Key Rules

1. Call initLogger() or setGlobalLogLevel() + setGlobalFormat() once at app startup
2. Use .useGlobalConfig() on logger instances to pick up global settings
3. withField / withFields / child return new instances — they don't mutate
4. Use Format.JSON in production, Format.Pretty in development
5. Works in both Node.js and browser — format auto-adapts

Documentation

For the latest API reference, use context7 to query @guiiai/logg documentation.