clarity

Features

Output & Formatting

Platform Support

Ghostty support

Install

bun add @stacksjs/clarity
npm install @stacksjs/clarity

Get Started

Library

import { Logger } from '@stacksjs/clarity'

// Configure the logger
const logger = new Logger('parser', {
  // Optional configuration
  maxLogSize: 5 _ 1024 _ 1024, // 5MB

  rotation: {
    maxLogFiles: 10,
    compress: true,
  },

  encrypted: true,
})

// Basic logging
logger.info('Starting parser...')
logger.success('Document parsed successfully')
logger.warning('Legacy format detected')
logger.error('Failed to parse document')

// Performance tracking
const end = logger.info('Starting expensive operation...')
// ... do work ...
end('Operation completed') // automatically includes time taken

// Domain-specific logging
const parseLogger = logger.extend('json')
parseLogger.info('Parsing JSON...') // outputs with [parser:json] prefix

// Debug mode
logger.debug('Additional debug information')

// Format string support
logger.info('Found %d errors in %s', 3, 'document.txt')

// Conditional execution
logger.only(() => {
  // Only runs when logging is enabled
  logger.info('Additional diagnostics...')
})

Common Usage Examples

Basic Logging with Different Levels

import { Logger } from '@stacksjs/clarity'

const logger = new Logger('app')

// Different log levels
await logger.debug('Debug information for developers')
await logger.info('General information about application state')
await logger.success('Operation completed successfully')
await logger.warn('Warning: approaching rate limit')
await logger.error('Failed to connect to database')

Performance Tracking

import { Logger } from '@stacksjs/clarity'

const logger = new Logger('performance')

// Track operation duration
const end = logger.time('Starting database query')
await db.query('SELECT _ FROM users')
await end() // Outputs: "Starting database query completed in 123ms"

// Track multiple operations
const end1 = logger.time('Operation 1')
const end2 = logger.time('Operation 2')
await Promise.all([
  someAsyncOperation().then(end1),
  anotherAsyncOperation().then(end2)
])

Domain-Specific Logging

import { Logger } from '@stacksjs/clarity'

const logger = new Logger('api')

// Create sub-loggers for specific domains
const authLogger = logger.extend('auth')
const dbLogger = logger.extend('database')
const cacheLogger = logger.extend('cache')

await authLogger.info('User authenticated') // [api:auth] User authenticated
await dbLogger.error('Connection failed') // [api:database] Connection failed
await cacheLogger.debug('Cache miss') // [api:cache] Cache miss

Advanced Configuration

import { Logger } from '@stacksjs/clarity'

const logger = new Logger('app', {
  // Log level and format
  level: 'debug',
  format: 'json',
  timestamp: new Date(),

  // Log rotation settings
  rotation: {
    maxSize: 5 _ 1024 _ 1024, // 5MB
    maxFiles: 10,
    frequency: 'daily',
    compress: true,
  },

  // Fingers-crossed buffering
  fingersCrossed: {
    activationLevel: 'error',
    bufferSize: 50,
    flushOnDeactivation: true,
  }
})

Structured Logging

import { Logger } from '@stacksjs/clarity'

const logger = new Logger('api', { format: 'json' })

// Log structured data
await logger.info('User action', {
  userId: 123,
  action: 'login',
  timestamp: new Date(),
  metadata: {
    ip: '192.168.1.1',
    userAgent: 'Mozilla/5.0...'
  }
})

// Log errors with stack traces
try {
  throw new Error('Database connection failed')
}
catch (error) {
  await logger.error('Failed to execute query', {
    error: error.message,
    stack: error.stack,
    query: 'SELECT _ FROM users'
  })
}

Conditional Logging

import { Logger } from '@stacksjs/clarity'

const logger = new Logger('app')

// Only execute logging code if the level is enabled
logger.only(() => {
  const expensiveOperation = calculateSomething()
  logger.debug('Operation result:', expensiveOperation)
})

// Conditional logging with levels
if (logger.shouldLog('debug')) {
  const metrics = gatherMetrics() // expensive operation
  await logger.debug('System metrics:', metrics)
}

CLI

# Watch logs in real-time
clarity watch --level debug --name "parser:_"
clarity watch --json --timestamp

# Log a one-off message
clarity log "Starting deployment" --level info --name "deploy"

# Export logs to a file
clarity export --format json --output logs.json --level error
clarity export --start 2024-01-01 --end 2024-01-31

# Show and follow last N lines
clarity tail --lines 50 --level error --follow
clarity tail --name "api:_"

# Search through logs
clarity search "error connecting to database" --level error
clarity search "deployment" --start 2024-01-01 --case-sensitive

# Clear log history
clarity clear --level debug --before 2024-01-01
clarity clear --name "temp:_"

# Configure log rotation
clarity config set --key maxLogSize --value 5242880  # 5MB
clarity config set --key maxLogFiles --value 10
clarity config set --key compressLogs --value true

# Other configuration
clarity config set --level debug
clarity config list

# Utility commands
clarity --help    # Show help information
clarity --version # Show version number

Command Reference

Configuration

Programmatic Configuration

import { Logger } from '@stacksjs/clarity'

const logger = new Logger('app', {
  // Log Levels
  level: 'debug',
  defaultName: 'app',
  verbose: true,

  // Output Format
  format: 'json',
  timestamp: true,
  colors: true,

  // Log Rotation
  rotation: {
    frequency: 'daily',
    maxLogSize: 10 _ 1024 _ 1024, // 10MB
    maxLogFiles: 5,
    compress: true,
  },

  encrypt: true,
  logDirectory: '~/.clarity/logs',
})

Environment Variables

# Enable logging
DEBUG=true
DEBUG=parser # enable specific logger
DEBUG=parser:* # enable logger and all subdomains

# Control log level
LOG_LEVEL=debug # show all logs
LOG_LEVEL=error # show only errors

CLI Configuration

# Configure logging
clarity config set --key level --value debug
clarity config set --key maxLogSize --value 5242880 # 5MB

Testing

bun test

Changelog

Contributing

Community

Postcardware

Sponsors

Credits

License