Happy Web Logger 🎯

A high-performance web logging utility that offloads logging to Web Workers with automatic function tracking and extensible integrations.

Created by Bernard Baker, APLENTIFY GROUP LTD

---

✨ Features

• 🚀 Web Worker Integration: Offload logging to a separate thread for zero main-thread impact
• 📊 Automatic Function Tracking: Track function calls, arguments, execution time, and errors
• 🔄 Console Override: Seamlessly intercept all console methods
• ⚡ Smart Buffering: Choose between immediate, batched, or adaptive buffering strategies
• 🔌 Plugin System: Extensible integration system for webhooks, emails, and custom handlers
• 📝 Full TypeScript Support: Complete type definitions included
• 🎯 Object-Oriented Architecture: Clean, maintainable, and testable code
• ⚙️ Highly Configurable: Customize every aspect of logging behavior
• 🧪 Thoroughly Tested: Comprehensive unit, integration, and performance tests

---

📦 Installation

From GitHub Packages

Step 1: Configure Package Registry

Create a configuration file in your project root:

For npm/pnpm - Create .npmrc:

@bernardbaker:registry=https://npm.pkg.github.com

For yarn - Create .yarnrc.yml:

npmScopes:
  bernardbaker:
    npmRegistryServer: "https://npm.pkg.github.com"

For bun - Create .bunfig.toml:

[install.scopes]
"@bernardbaker" = { registry = "https://npm.pkg.github.com" }

Step 2: Install the Package

Choose your preferred package manager:

npm:

npm install @bernardbaker/happy-web-logger

pnpm:

pnpm add @bernardbaker/happy-web-logger

yarn:

yarn add @bernardbaker/happy-web-logger

bun:

bun add @bernardbaker/happy-web-logger

📖 Need more details? See PACKAGE_MANAGERS.md for comprehensive package manager instructions, troubleshooting, and performance comparisons.

---

🔧 Web Worker Setup

Happy Web Logger uses a Web Worker to offload logging operations. You need to copy the worker file to a location accessible by your web application.

Option 1: Manual Copy (Recommended for Next.js, Vite, etc.)

After installation, copy the worker file to your public directory:

For Next.js:

# Copy to public folder
node node_modules/@bernardbaker/happy-web-logger/scripts/copy-worker.js public/logger.worker.js

For Vite or other frameworks:

# Copy to public folder (adjust path as needed)
node node_modules/@bernardbaker/happy-web-logger/scripts/copy-worker.js public/logger.worker.js

Option 2: Post-Install Script

Add a postinstall script to your package.json to automatically copy the worker file:

{
  "scripts": {
    "postinstall": "node node_modules/@bernardbaker/happy-web-logger/scripts/copy-worker.js public/logger.worker.js"
  }
}

Using the Copy Script

The copy-worker.js script accepts both relative and absolute paths:

# Relative path (resolved from your project root)
node node_modules/@bernardbaker/happy-web-logger/scripts/copy-worker.js public/logger.worker.js

# Absolute path
node node_modules/@bernardbaker/happy-web-logger/scripts/copy-worker.js /absolute/path/to/public/logger.worker.js

Configuring the Worker Path

In your logger configuration, specify the worker path (relative to your public directory):

import HappyLogger from '@bernardbaker/happy-web-logger';

const logger = HappyLogger.getInstance({
  workerPath: '/logger.worker.js', // Absolute path from public folder
  // ... other config options
});

⚠️ Important: The worker file must be accessible via HTTP. In Next.js, place it in the public folder. In Vite, place it in the public directory. The path in your config should be relative to your app's root URL.

---

🚀 Quick Start

import HappyLogger from '@bernardbaker/happy-web-logger';

// Get the singleton instance (captures all log levels by default)
const logger = HappyLogger.getInstance({
  bufferMode: 'adaptive',
  enableConsoleOverride: true,
  enableFunctionTracking: false,
  workerPath: '/logger.worker.js', // Path to worker file in your public directory
  // logLevel: 'debug' is the default - captures all levels
  colors: {
    debug: '#9e9e9e',    // Gray for debug
    info: '#2196F3',     // Blue for info
    warn: '#FF9800',     // Orange for warnings
    error: '#F44336',    // Red for errors
    log: '#4CAF50',      // Green for console.log
  },
});

// Start logging!
logger.info('Application started');
logger.warn('This is a warning');
logger.error('An error occurred');

// Or use console methods (they're automatically intercepted)
console.log('This goes through Happy Web Logger too!');

---

📖 Documentation

Configuration Options

interface LoggerConfig {
  bufferMode?: 'immediate' | 'batched' | 'adaptive';  // Default: 'adaptive'
  batchSize?: number;                                  // Default: 10
  batchInterval?: number;                              // Default: 1000ms
  enableFunctionTracking?: boolean;                    // Default: false
  excludedFunctions?: Set<Function>;
  logLevel?: 'debug' | 'info' | 'warn' | 'error';     // Default: 'debug' (captures all)
  integrations?: LogIntegration[];
  maxStackTraceDepth?: number;                         // Default: 10
  enableConsoleOverride?: boolean;                     // Default: true
  workerPath?: string;                                  // Path to worker file (e.g., '/logger.worker.js')
  colors?: LogColors;                                   // Custom colors for console output
  enableInProduction?: boolean;                        // Default: false - Enable logging in production environment
}

interface LogColors {
  debug?: string;  // Color for debug logs (HEX, RGB, RGBA, or named color)
  info?: string;   // Color for info logs (HEX, RGB, RGBA, or named color)
  warn?: string;   // Color for warn logs (HEX, RGB, RGBA, or named color)
  error?: string;  // Color for error logs (HEX, RGB, RGBA, or named color)
  log?: string;    // Color for console.log (HEX, RGB, RGBA, or named color)
}

Console Log Colors

Customize the colors of console log output in the browser developer tools. Colors can be specified in HEX, RGB, RGBA, or named color formats.

const logger = HappyLogger.getInstance({
  colors: {
    debug: '#9e9e9e',              // HEX format
    info: 'rgb(33, 150, 243)',     // RGB format
    warn: 'rgba(255, 152, 0, 1)',  // RGBA format
    error: '#F44336',              // HEX format
    log: 'blue',                   // Named color
  },
});

Supported Color Formats:

• HEX: #RRGGBB or #RRGGBBAA (e.g., #FF5733 or #FF5733CC)
• RGB: rgb(r, g, b) (e.g., rgb(255, 87, 51))
• RGBA: rgba(r, g, b, a) (e.g., rgba(255, 87, 51, 0.8))
• Named Colors: Standard CSS color names (e.g., blue, red, green)

Example:

const logger = HappyLogger.getInstance({
  enableConsoleOverride: true,
  colors: {
    debug: '#757575',
    info: '#1976D2',
    warn: '#F57C00',
    error: '#D32F2F',
  },
});

// All console methods will use the specified colors
console.log('This will be in default color');
console.info('This will be blue');
console.warn('This will be orange');
console.error('This will be red');
console.debug('This will be gray');

Note: Colors only apply when enableConsoleOverride is true (default). Colors are applied to console output in the browser's developer tools.

Production Mode

By default, Happy Web Logger is disabled in production environments to prevent logging overhead and potential security concerns. The logger automatically detects production mode by checking NODE_ENV === 'production' or other production indicators.

To enable logging in production, set enableInProduction: true:

const logger = HappyLogger.getInstance({
  enableInProduction: true, // Enable logging in production
  // ... other config options
});

Important Notes:

• When disabled in production (default), all logging methods become no-ops
• Console override and function tracking are not initialized in production when disabled
• This helps reduce bundle size and improve performance in production builds
• Only enable production logging when necessary for debugging or monitoring

Example: Conditional Production Logging

const logger = HappyLogger.getInstance({
  // Only enable in production if a feature flag is set
  enableInProduction: process.env.ENABLE_LOGGING === 'true',
  // ... other config options
});

Buffer Modes

Immediate Mode

Logs are processed and sent immediately. Best for real-time logging.

const logger = HappyLogger.getInstance({
  bufferMode: 'immediate',
});

Batched Mode

Logs are collected and sent in batches. Best for high-volume logging.

const logger = HappyLogger.getInstance({
  bufferMode: 'batched',
  batchSize: 50,
  batchInterval: 2000,
});

Adaptive Mode

Errors are sent immediately, other logs are batched. Best for balanced performance.

const logger = HappyLogger.getInstance({
  bufferMode: 'adaptive',
});

Function Tracking

Automatically track function execution:

const logger = HappyLogger.getInstance({
  enableFunctionTracking: true,
});

// All function calls will be logged with:
// - Function name
// - Arguments
// - Execution time
// - Return value
// - Errors (if any)

Exclude specific functions:

function sensitiveFunction() {
  // This won't be tracked
}

logger.excludeFunction(sensitiveFunction);

Or use the decorator:

import { NoLog } from '@bernardbaker/happy-web-logger';

class MyClass {
  @NoLog
  private sensitiveMethod() {
    // This won't be tracked
  }
}

Creating Custom Integrations

import { LogIntegration, LogEntry } from '@bernardbaker/happy-web-logger';

const customIntegration: LogIntegration = {
  name: 'my-custom-integration',
  
  // Determine when this integration should be triggered
  trigger: (entry: LogEntry) => {
    return entry.level === 'error' && entry.message.includes('critical');
  },
  
  // Execute when triggered
  execute: async (entry: LogEntry) => {
    // Send to your custom endpoint
    await fetch('https://my-api.com/logs', {
      method: 'POST',
      body: JSON.stringify(entry),
    });
  },
};

logger.registerIntegration(customIntegration);

Built-in Integrations

Email Integration

import { EmailIntegration } from '@bernardbaker/happy-web-logger';

const emailIntegration = new EmailIntegration({
  apiUrl: 'https://api.sendgrid.com/v3/mail/send',
  apiKey: 'your-api-key',
  from: 'alerts@yourapp.com',
  to: ['admin@yourapp.com', 'team@yourapp.com'],
  subject: 'Application Error Alert',
});

logger.registerIntegration(emailIntegration);

Webhook Integration

import { WebhookIntegration } from '@bernardbaker/happy-web-logger';

const webhookIntegration = new WebhookIntegration({
  url: 'https://hooks.slack.com/services/YOUR/WEBHOOK/URL',
  method: 'POST',
  secret: 'your-webhook-secret',
  timeout: 5000,
});

logger.registerIntegration(webhookIntegration);

---

🎯 Advanced Usage

Dynamic Configuration

// Change configuration at runtime
logger.configure({
  bufferMode: 'batched',
  batchSize: 100,
  logLevel: 'debug',
});

Manual Flushing

// Force flush all buffered logs
logger.flush();

Checking Worker Status

if (logger.isWorkerFallbackMode()) {
  console.log('Running in fallback mode (no Web Worker support)');
}

Cleanup

// Clean up resources before unloading
window.addEventListener('beforeunload', () => {
  logger.flush();
  logger.destroy();
});

---

📊 Performance

Happy Web Logger is designed for high performance:

• Zero main-thread blocking with Web Worker support
• Optimized batching reduces overhead by up to 70%
• Adaptive buffering balances real-time logging with performance
• Minimal memory footprint with efficient serialization

See our performance tests for detailed benchmarks.

---

🧪 Testing

# Run all tests
npm test

# Run with coverage
npm run test:coverage

# Run integration tests
npm run test:integration

# Run performance tests
npm run test:performance

---

🛠️ Development

# Install dependencies
npm install

# Build the project
npm run build

# Watch mode
npm run build:watch

# Lint
npm run lint

# Format code
npm run format

# Generate documentation
npm run docs

---

📄 License

This project is dual-licensed:

Free for Personal Use

Free to use for personal, non-commercial projects.

Commercial License Required

Commercial use requires a separate license. Contact us for licensing:

Bernard Baker
APLENTIFY GROUP LTD
Email: bernard@aplentify.uk

See LICENSE for full details.

---

🤝 Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

Note for Contributors: If you are contributing to this project, please refer to the Development and Testing sections above for setup instructions and testing guidelines.

---

📞 Support

For questions, issues, or commercial licensing inquiries:

• Email: bernard@aplentify.uk
• GitHub Issues: Create an issue

---

🙏 Credits

Created by Bernard Baker
APLENTIFY GROUP LTD
© 2025 All Rights Reserved

---

📚 Examples

Check out the examples directory for complete working examples:

• 🎮 Interactive Web Worker Demo - Full-featured interactive demo showcasing Web Worker functionality with a beautiful UI
• Basic Usage - Simple HTML page demonstrating basic setup
• Custom Integration - Create custom integrations (webhooks, email, etc.)
• Function Tracking - Automatic function call tracking
• Performance Optimization - Different buffering strategies

🚀 Quick Start with the Interactive Demo

1. Build the library:

   npm run build

2. Start a local server:

   npx http-server . -p 8080

3. Open in your browser:

   http://localhost:8080/examples/web-worker-demo.html
   

The interactive demo features:

• ✅ Real-time Web Worker logging visualization
• 📊 Performance metrics and statistics
• 🔔 Custom integration triggers
• 👁️ View Worker console logs: See VIEW_WORKER_LOGS.md for how to view Web Worker output in DevTools
• ⚡ Stress testing capabilities
• 🎨 Modern, responsive UI

See examples/README.md for detailed documentation.

---

🎉 Why "Happy" Web Logger?

Because logging shouldn't make you sad! We believe that:

• Logging should be effortless to set up
• Logging should be performant by default
• Logging should be flexible for any use case
• Logging should make developers happy 😊

---

Made with ❤️ by Bernard Baker