@guinetik/logger

A simple and flexible logger for the browser with localStorage persistence and zero runtime dependencies. Perfect for debugging complex applications where you need fine-grained control over logging output.

Features

• 🎯 Component Filtering - Enable/disable logs per component
• 💾 Persistent State - Settings saved to localStorage (browser) or memory (Node.js)
• 🎚️ Log Levels - Standard levels: error, warn, info, debug, trace
• 🔒 Secret Redaction - Automatic redaction of potential secrets in trace logs
• 🌍 Universal - Works in browser and Node.js
• 📦 Zero Dependencies - No runtime dependencies
• 🎨 TypeScript Support - Full type definitions included
• ⚡ ES2022 - Modern JavaScript, tree-shakeable

Installation

npm install @guinetik/logger

Quick Start

import { createLogger } from '@guinetik/logger';

// Create a logger for your component
const log = createLogger({ 
  prefix: 'MyComponent',
  level: 'debug'
});

log.info('Component initialized');
log.debug('Debug information', { data: 'value' });
log.error('Something went wrong!');

Component Filtering

Filter logs by component in the browser console:

// Enable logging for specific components
window.logFilter.enable('MyComponent', 'AnotherComponent');

// Disable specific components
window.logFilter.disable('NoisyComponent');

// Enable ALL components
window.logFilter.enableAll();

// Disable ALL components (errors still show)
window.logFilter.disableAll();

// Check current status
window.logFilter.status();

// List all registered components
window.logFilter.list();

Note: window.loggerjs is available as an alias for window.logFilter:

// These are equivalent:
window.logFilter.enable('MyComponent');
window.loggerjs.enable('MyComponent');

Settings persist across page reloads via localStorage!

Log Levels

Control verbosity with log levels:

const log = createLogger({ 
  prefix: 'App',
  level: 'info' // error | warn | info | debug | trace
});

log.error('Always visible');
log.warn('Warnings and above');
log.info('Info and above');
log.debug('Debug and above');
log.trace('Everything');

Timestamps

Timestamps are enabled by default and show in ISO format with brackets:

const log = createLogger({ prefix: 'App' });

log.info('This message has a timestamp');
// Output: [2024-11-29T10:30:45.123Z] [App] This message has a timestamp

To disable timestamps:

const log = createLogger({ 
  prefix: 'App',
  showTimestamp: false
});

log.info('No timestamp here');
// Output: [App] No timestamp here

Custom Format

Customize the output format using placeholders: {timestamp}, {prefix}, and {message}:

// Default format
const log1 = createLogger({ 
  prefix: 'App',
  format: '[{timestamp}] [{prefix}] {message}'
});

// Compact format
const log2 = createLogger({ 
  prefix: 'API',
  format: '{timestamp} {prefix}: {message}'
});

// Minimal format
const log3 = createLogger({ 
  prefix: 'DB',
  format: '{message}'
});

log1.info('Default'); // [2024-11-29T10:30:45.123Z] [App] Default
log2.info('Compact'); // 2024-11-29T10:30:45.123Z API: Compact
log3.info('Minimal'); // Minimal

Advanced Usage

Custom Console

import { createLogger } from '@guinetik/logger';

const log = createLogger({
  prefix: 'Custom',
  console: myCustomConsole
});

Secret Redaction

const log = createLogger({
  prefix: 'API',
  redactSecrets: true
});

// Long alphanumeric strings (20+ chars) are redacted
log.debug('Token:', 'abc123def456ghi789jkl012'); 
// Output: Token: [REDACTED]

Manual Logger Setup

import { Logger, LoggingManager, createStorageAdapter } from '@guinetik/logger';

const storage = createStorageAdapter();
const manager = new LoggingManager({ storage });

const log = new Logger({
  prefix: 'Custom',
  loggingManager: manager,
  level: 'debug'
});

Console Methods

All standard console methods are supported:

log.table([{ name: 'Alice', age: 30 }]);
log.group('Group Label');
log.groupCollapsed('Collapsed Group');
log.groupEnd();
log.time('operation');
// ... do something
log.timeEnd('operation');

API Reference

createLogger(options)

Creates a new logger instance.

Options:

• enabled (boolean) - Enable/disable logging (default: true)
• level (string) - Log level: 'error' | 'warn' | 'info' | 'debug' | 'trace' (default: 'info')
• prefix (string) - Prefix for log messages (default: '')
• redactSecrets (boolean) - Redact potential secrets (default: false)
• showTimestamp (boolean) - Show ISO timestamps in logs (default: true)
• format (string) - Output format with placeholders: {timestamp}, {prefix}, {message} (default: '[{timestamp}] [{prefix}] {message}')
• console (Console) - Console object to use (default: global console)

Logger Methods

• error(message, ...args) - Log error
• warn(message, ...args) - Log warning
• info(message, ...args) - Log info
• log(message, ...args) - Log info (alias)
• debug(message, ...args) - Log debug
• trace(message, ...args) - Log trace (with auto-redaction)
• table(data, columns) - Log table
• group(label) - Create group
• groupCollapsed(label) - Create collapsed group
• groupEnd() - End group
• time(label) - Start timer
• timeEnd(label) - End timer
• setLevel(level) - Change log level
• enable() - Enable logging
• disable() - Disable logging
• isEnabled() - Check if enabled

window.logFilter / window.loggerjs (Browser Only)

Global filtering interface automatically available in browser (both window.logFilter and window.loggerjs are aliases):

• enable(...components) - Enable components
• disable(...components) - Disable components
• enableAll() - Enable all
• disableAll() - Disable all
• status() - Show status
• list() - List components

Use Cases

Debugging Complex UIs

// In different components
const navLog = createLogger({ prefix: 'Navigation' });
const modalLog = createLogger({ prefix: 'Modal' });
const apiLog = createLogger({ prefix: 'API' });

// In console, enable only what you need:
window.logFilter.enable('Modal'); // Only modal logs

Production Error Tracking

const log = createLogger({ 
  prefix: 'App',
  level: 'error' // Only errors in production
});

Development vs Production

const log = createLogger({
  prefix: 'App',
  level: process.env.NODE_ENV === 'development' ? 'debug' : 'error'
});

Browser Compatibility

Works in all modern browsers supporting:

• ES2022
• localStorage (falls back to memory storage)
• Console API

Node.js Support

Fully supported in Node.js 18+. Uses in-memory storage instead of localStorage.

TypeScript

Full TypeScript definitions included:

import { createLogger, Logger, LogLevel } from '@guinetik/logger';

const log: Logger = createLogger({
  prefix: 'TypeScript',
  level: 'debug' as LogLevel
});

// window.loggerjs is also typed
window.loggerjs.enable('MyComponent');

Module Support

This package supports both ESM and CommonJS:

ESM (Recommended)

import { createLogger } from '@guinetik/logger';

CommonJS

const { createLogger } = require('@guinetik/logger');

Jest Configuration

If you're using Jest with this package, the exports field automatically handles module resolution:

// jest.config.js
module.exports = {
  testEnvironment: 'jsdom',
  // No additional configuration needed!
};

The package exports:

• ESM: dist/index.mjs (modern bundle)
• CommonJS: dist/index.cjs (Node.js compatible)
• Types: dist/index.d.ts (TypeScript definitions)

License

Apache-2.0

Author

Joao Guilherme (Guinetik) [email protected]

Contributing

Issues and PRs welcome at GitHub!