sinsole-log

SinsoleLog 🚀

Advanced logging system with categories, filters, and production debugging support

Transform your debugging experience with categorized logging, smart filtering, and production-safe debugging. Say goodbye to console.log chaos!

🌟 Why SinsoleLog?

Before (console.log chaos):

console.log('User logged in');
console.log('Connecting to database...');
console.log('API call failed');
console.log('Component rendered');
// 😵 Mixed logs, hard to filter, disabled in production

After (organized & powerful):

sinsole.log('User logged in', 'AUTH');
sinsole.log('Connecting to database...', 'DB');
sinsole.error('API call failed', 'NETWORK');
sinsole.log('Component rendered', 'RENDER');

// 🎯 Filter by category: sd.filter('AUTH,DB')
// 📊 Get statistics: sd.stats()
// 🚨 Debug in production: sd.enable()

📦 Installation

npm install sinsole-log

🎭 Interactive Demo

Try it now! The package includes interactive demos and examples:

• 🌐 HTML Demo: Open demo.html in your browser for a complete interactive experience
• 📝 Code Examples: Run npm run examples to see practical usage patterns
• 🖥️ Local Server: Use npm run serve-demo to serve the demo on http://localhost:8080

# After installation
cd node_modules/sinsole-log
npm run serve-demo    # Open browser to http://localhost:8080

⚡ Quick Start

import { sinsole } from 'sinsole-log';

// 1. Basic categorized logging
sinsole.log('User authenticated successfully', 'AUTH');
sinsole.log('Fetching user profile from database', 'DB');
sinsole.error('Payment processing failed', 'PAYMENT');

// 2. Filter logs in browser console
sd.filter('AUTH,DB');  // Only show authentication and database logs
sd.help();             // See all available commands

// 3. Measure performance
const result = await sinsole.measureAsync('API Call', async () => {
  return await fetch('/api/users');
}, 'NETWORK');

// 4. Debug in production (when needed)
sd.enable();           // Activate logs in production
sd.setLevel('error');  // Only show errors

🎯 Available Categories (20+ Built-in)

Category	Key	Description	Example Usage
🗄️ DATABASE	DB	Database operations	sinsole.log('Query executed', 'DB')
🔐 AUTH	AUTH	Authentication	sinsole.log('User login', 'AUTH')
🌐 NETWORK	NETWORK	API calls	sinsole.log('API response', 'NETWORK')
💾 STORAGE	STORAGE	File operations	sinsole.log('File uploaded', 'STORAGE')
🎨 RENDER	RENDER	UI rendering	sinsole.log('Component loaded', 'RENDER')
⚡ EVENT	EVENT	User events	sinsole.log('Button clicked', 'EVENT')
⏳ LAZY	LAZY	Lazy loading	sinsole.log('Module loaded', 'LAZY')
📦 CACHE	CACHE	Cache operations	sinsole.log('Cache updated', 'CACHE')
🔥 FIREBASE	FIREBASE	Firebase ops	sinsole.log('Data synced', 'FIREBASE')
🖼️ UI	UI	Interface updates	sinsole.log('Modal opened', 'UI')

See all 20+ categories in the demo →

🔍 Smart Filtering System

// Filter by single category
sd.filter('DB');                    // Only database logs

// Filter by multiple categories  
sd.filter('AUTH,NETWORK');          // Authentication and network logs
sd.filter(['UI', 'RENDER']);        // Array format also works

// Advanced filtering
sd.filter('DB,AUTH');               // Show only critical operations
sd.setLevel('warn');                // + Only warnings and errors
sd.search('failed');                // + Search for specific terms

// Clear all filters
sd.clearFilter();                   // Back to showing everything

🚨 Production Debugging (Secure)

Logs are automatically disabled in production for security. Enable them when needed:

// In browser console on production site:
sd.enable();                        // ✅ Enable all logs
sd.enable('error');                 // ⚠️ Only errors and warnings
sd.filter('AUTH,PAYMENT');          // 🎯 Focus on critical systems
sd.export();                        // 📥 Download logs for analysis

// Security: Uses hidden localStorage keys
// _sinsole_debug_ - Debug state
// _sinsole_filter_ - Active filters

⚡ Performance Measurement

Measure synchronous operations:

const result = sinsole.measure('Complex Calculation', () => {
  return expensiveOperation();
}, 'PERFORMANCE');
// Output: "Complex Calculation: 245.32ms" [PERFORMANCE]

Measure async operations:

const data = await sinsole.measureAsync('Database Query', async () => {
  const users = await db.users.findMany();
  return users;
}, 'DB');
// Output: "Database Query: 89.45ms" [DB]

📊 Analytics & Statistics

// View detailed statistics
sd.stats();
/* Output:
📊 Sinsole Statistics:
├── Total logs: 1,247
├── Categories used: 8
├── Top categories:
│   ├── 🗄️ DB: 423 logs
│   ├── 🔐 AUTH: 189 logs
│   └── 🌐 NETWORK: 156 logs
*/

// Search through log history
sd.search('error');                 // Find all logs containing "error"
sd.search('user.*login');           // Regex search support

// Export for external analysis
sd.export();                        // Downloads JSON file with all logs

🛠️ Custom Categories

Add your own categories:

sinsole.addCategories({
  PAYMENT: { 
    key: 'PAYMENT', 
    label: 'Payment System', 
    emoji: '💳', 
    color: '#4CAF50' 
  },
  ANALYTICS: 'User Analytics',      // Simplified format
  EMAIL: {
    key: 'EMAIL',
    label: 'Email Service',
    emoji: '📧',
    color: '#FF5722'
  }
});

// Use your custom categories
sinsole.log('Processing credit card payment', 'PAYMENT');
sinsole.log('Sending welcome email', 'EMAIL');

Complete configuration:

sinsole.configure({
  level: 'DEBUG',                   // Minimum log level
  showTimestamp: true,              // Show timestamps
  showCaller: true,                 // Show file:line
  maxHistorySize: 5000,             // History size
  categories: {
    CUSTOM: { key: 'CUSTOM', label: 'My Category', emoji: '🎯', color: '#E91E63' }
  }
});

🎪 Real-World Examples

E-commerce Application:

// User journey tracking
sinsole.log('Product page loaded', 'UI');
sinsole.log('Item added to cart', 'CART');
sinsole.log('Applying discount code', 'PROMO');
sinsole.log('Processing payment', 'PAYMENT');
sinsole.success('Order confirmed #12345', 'ORDER');

// Debug only payment issues
sd.filter('PAYMENT,ORDER');

API Development:

// Request lifecycle
sinsole.log('Incoming request: POST /api/users', 'API');
sinsole.log('Validating request data', 'VALIDATION');
sinsole.log('Checking user permissions', 'AUTH');
sinsole.log('Querying user database', 'DB');
sinsole.success('User created successfully', 'API');

// Performance monitoring
const response = await sinsole.measureAsync('User Creation', async () => {
  return await createUser(userData);
}, 'API');

React/Vue Application:

// Component lifecycle
sinsole.log('UserProfile component mounting', 'RENDER');
sinsole.log('Fetching user data from API', 'NETWORK');
sinsole.log('Updating component state', 'STATE');
sinsole.log('UserProfile component rendered', 'RENDER');

// Debug rendering issues
sd.filter('RENDER,STATE');
sd.setLevel('debug');

📱 Console Commands Reference

All commands available in browser console via sd.command() or sinsoleDebug.command():

Command	Description	Example
enable()	Enable debug mode	sd.enable() or sd.enable('warn')
disable()	Disable debug mode	sd.disable()
filter()	Filter by categories	sd.filter('DB,AUTH')
clearFilter()	Remove all filters	sd.clearFilter()
setLevel()	Set minimum log level	sd.setLevel('error')
stats()	Show usage statistics	sd.stats()
search()	Search log history	sd.search('failed')
export()	Export logs to JSON	sd.export()
clear()	Clear log history	sd.clear()
help()	Show complete help	sd.help()

🔒 Security Features

• 🛡️ Production Safe: Logs automatically disabled in production environments
• 🔐 Access Control: Requires browser console access to enable
• 👤 Obfuscated Keys: Uses hidden localStorage keys (_sinsole_debug_)
• 📝 No Sensitive Data: Framework doesn't log sensitive information by default
• 🚫 Easy Disable: Complete disable with sd.disable()

📈 Migration Guide

From console.log:

// Before
console.log('Database connected');
console.error('Connection failed');

// After
sinsole.log('Database connected', 'DB');
sinsole.error('Connection failed', 'DB');

From other logging libraries:

// Before (other libraries)
logger.info('User logged in');
logger.error('Payment failed');

// After (SinsoleLog)
sinsole.info('User logged in', 'AUTH');
sinsole.error('Payment failed', 'PAYMENT');

// Bonus: Now you can filter, analyze, and debug in production!
sd.filter('PAYMENT');  // Focus on payment issues
sd.stats();           // See usage patterns

🤝 Contributing

We welcome contributions! Please see our GitHub repository for:

• 🐛 Bug reports
• 💡 Feature requests
• 🔄 Pull requests
• 📖 Documentation improvements

📄 License

MIT © Geniova Technologies

⭐ Star us on GitHub if SinsoleLog helps your debugging!

GitHub • NPM • Issues