🎨 Debugg - Smart Error Handling for Developers

Debug smarter, not harder! A developer-friendly error handling library that makes debugging enjoyable.

🎉 Day 1 MVP Complete! Core error handling foundation with modular architecture

🚀 Why Debugg Exists

We believe error handling should be enjoyable, not frustrating! Debugg was created to solve the universal developer pain points:

1. Inconsistent error handling across different parts of applications
2. Lack of context when errors occur - making debugging difficult
3. No standardized severity levels - hard to prioritize issues
4. Multiple monitoring tools with different formats and APIs
5. Cross-platform challenges - different error handling for browser vs Node.js
6. Poor error tracking - no unique IDs to trace errors across systems

✨ Solution: Universal Error Handler

A single, unified library that provides:

• ✅ Consistent error format across all platforms
• ✅ Automatic error classification with severity levels
• ✅ Rich context attachment for better debugging
• ✅ Unique error IDs for tracking and correlation
• ✅ Multiple reporter support (Sentry, webhooks, custom)
• ✅ Cross-platform detection (browser, Node.js, mobile)
• ✅ Type-safe API with comprehensive TypeScript support
• ✅ Production-ready with minimal performance impact

📦 Installation

# Using Bun (recommended)
bun add debugg

# Using npm
npm install debugg

# Using yarn
yarn add debugg

🏗️ Modular Architecture (Day 1 Complete)

🎯 Day 1 MVP delivers a solid foundation with modular design:

src/
├── types/          # Type definitions and interfaces
│   └── error.ts    # Core type system
├── utils/          # Utility functions
│   └── classify.ts # Advanced error classification
├── core/           # Core functionality
│   └── capture.ts  # Error capture and processing
├── storage/        # Storage system
│   └── index.ts    # In-memory storage with persistence
└── index.ts        # Main entry point

✅ Day 1 Features Implemented:

• Core error handling infrastructure
• Automatic error classification with severity levels
• Rich context support with depth limiting
• Cross-platform detection (browser, Node.js, mobile)
• Type-safe API with comprehensive TypeScript support
• Basic storage system with in-memory and localStorage options
• Multiple reporter support (console, Sentry, webhook)
• Performance-optimized design

🔧 Quick Start

import { ErrorHandler, createConsoleReporter } from 'debugg';

// 🎨 Initialize Debugg with your brand personality
const debugg = new ErrorHandler({
  serviceName: 'my-awesome-app',
  environment: 'development',
  defaultSeverity: 'medium',
  logToConsole: true // See beautiful formatted errors!
});

// 🐞 Add reporters (Sentry, webhooks, or custom)
debugg.addReporter(createConsoleReporter());

// ✨ Handle errors anywhere with rich context
try {
  await riskyDatabaseOperation();
} catch (error) {
  await debugg.handle(error, {
    // 💡 Add context for smarter debugging
    userId: currentUser.id,
    operation: 'update_profile',
    database: 'postgresql',
    query: 'UPDATE users SET name = $1 WHERE id = $2',
    parameters: ['John Doe', currentUser.id]
  });
}

// 🎯 That's it! Enjoy beautiful, structured error handling!

🎯 Why Developers Love Debugg

🤩 Automatic Error Classification

// Smart severity assignment - no more guessing!
debugg.handle(new TypeError('...'));        // → 'high' severity
debugg.handle(new SyntaxError('...'));      // → 'critical' severity
debugg.handle(new Error('Network error'));  // → 'high' severity (auto-detected)
debugg.handle({ status: 500 });            // → 'critical' severity

🔍 Rich Context Support

// Add unlimited context - Debugg handles the rest!
debugg.handle(error, {
  user: { id: 123, email: 'user@example.com' },
  request: { method: 'POST', endpoint: '/api/users' },
  database: { query: 'SELECT * FROM users', timeout: 5000 },
  // ... add anything that helps debugging!
});

📡 Multiple Reporter Support

// Send errors everywhere with one line each!
debugg.addReporter(createSentryReporter('YOUR_DSN'));
debugg.addReporter(createWebhookReporter('https://api.example.com/errors'));
debugg.addReporter(yourCustomReporter);

// 🎉 All errors automatically sent to all reporters!

🌐 Cross-Platform Detection

Automatic platform detection - no configuration needed!

// Works everywhere automatically:
debugg.createError(new Error('test')).metadata.platform;
// Returns: 'browser' | 'node' | 'mobile' | 'unknown'

• Browser: Includes user agent info
• Node.js: Detects Node.js environment
• Mobile: Identifies iOS/Android
• Unknown: Fallback for other environments

5. Type-Safe API

Full TypeScript support with comprehensive type definitions:

interface UniversalError extends Error {
  severity: 'critical' | 'high' | 'medium' | 'low' | 'info';
  context: Record<string, any>;
  timestamp: Date;
  errorId: string;
  metadata: {
    platform: 'browser' | 'node' | 'mobile' | 'unknown';
    serviceName: string;
    environment: string;
    // ... and more
  };
}

🛠️ Advanced Usage

🎛️ Custom Configuration

// Tailor Debugg to your exact needs
const debugg = new ErrorHandler({
  serviceName: 'my-api-service',
  environment: process.env.NODE_ENV || 'development',
  defaultSeverity: 'medium',
  logToConsole: true,          // Beautiful console logging
  includeStackTrace: true,     // Helpful stack traces
  maxContextDepth: 3,          // Prevent memory issues
  reporters: [                 // Start with your reporters
    createConsoleReporter(),
    createSentryReporter('YOUR_DSN')
  ]
});

🔧 Custom Error Reporters

// Build reporters for any service!
const myCustomReporter: ErrorReporter = async (error) => {
  // Use Bun's native fetch for maximum performance!
  await Bun.$fetch('https://my-error-service.com/api/errors', {
    method: 'POST',
    body: Bun.JSON.stringify(error),
    headers: { 'Content-Type': 'application/json' }
  });
};

debugg.addReporter(myCustomReporter);

📊 Error Creation Without Handling

// Create structured errors for analytics, logging, etc.
const structuredError = debugg.createError(
  new Error('Database timeout'),
  {
    database: 'postgresql',
    query: 'SELECT * FROM users',
    timeout: 5000,
    affectedUsers: 150
  },
  'high' // Optional: override automatic severity
);

// Use in analytics, monitoring, or custom processing
analytics.track('error_occurred', structuredError);
monitoring.log(structuredError);
customProcessing(structuredError);

📊 Built-in Reporters

🚀 Sentry Reporter

import { createSentryReporter } from 'debugg';

debugg.addReporter(createSentryReporter('YOUR_SENTRY_DSN'));
// Automatically sends all errors to Sentry!

🌐 Webhook Reporter

import { createWebhookReporter } from 'debugg';

debugg.addReporter(createWebhookReporter('https://api.example.com/error-webhook'));
// POSTs all errors to your webhook endpoint!

💻 Console Reporter

import { createConsoleReporter } from 'universal-error-handler';

debugg.addReporter(createConsoleReporter());
// Beautiful, structured console output!

🔍 Error Classification Rules

Error Type	Severity	Description
SyntaxError	Critical	Code syntax issues
TypeError	High	Type-related errors
ReferenceError	High	Undefined variables
RangeError	Medium	Invalid ranges
Network errors	High	Connection issues
HTTP 5xx	Critical	Server errors
HTTP 4xx	Medium	Client errors
Default	Medium	Other errors

📈 Why Debugg is Valuable

👨‍💻 For Developers

• Saves time - No more writing custom error handling
• Reduces frustration - Makes debugging actually enjoyable
• Improves code quality - Consistent patterns across projects
• Better debugging - Rich context and structured data
• Easy integration - Works with your existing tools

🏢 For Teams & Companies

• Standardized error handling - One solution for all apps
• Better production monitoring - Consistent error formats
• Faster issue resolution - Detailed context for every error
• Cross-platform consistency - Browser, Node.js, Mobile
• Reduced maintenance - Unified error reporting system

💼 For Recruiters & Technical Leaders

• Shows architectural thinking - Solves universal developer pain
• Demonstrates attention to detail - Comprehensive solution
• Proves production experience - Built for real-world use
• Highlights TypeScript expertise - Fully typed, modern API
• Shows innovation - "Debug smarter, not harder" approach

💼 Business Potential

Monetization Opportunities

1. Premium Reporters - Advanced integrations with monitoring services
2. Cloud Service - Error aggregation and analytics dashboard
3. Enterprise Features - Team collaboration, SLAs, advanced filtering
4. Consulting Services - Help companies implement proper error handling
5. Training & Certification - Error handling best practices

Job Market Value

• High demand - Every company needs proper error handling
• Cross-industry applicability - Works for any JavaScript/TypeScript project
• Technical leadership - Shows you understand production systems
• Architectural skills - Demonstrates system design capabilities
• Problem-solving - Addresses a real pain point developers face daily

🚀 Getting Started with Development

# Clone the repository
git clone https://github.com/your-repo/universal-error-handler.git
cd universal-error-handler

# Install dependencies (Bun recommended)
bun install

# Build the library
bun run build

# Run tests
bun test

# Start development mode
bun run dev

🤝 Contributing

Contributions are welcome! Please read our Contributing Guide for details on how to contribute.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgements

• Inspired by the pain points of thousands of developers
• Built with love for the JavaScript/TypeScript community
• Designed to make error handling enjoyable (yes, really!)

---

🎨 Brand Identity

Debugg is more than just a library - it's a developer experience revolution!

• Mascot: Debugg the Bug 🐞 - friendly, helpful, technical
• Mission: Make error handling enjoyable and empower developers
• Vision: Change how the industry thinks about error monitoring
• Colors: Vibrant red (#FF4757) for energy and action
• Typography: Inter for clean, modern readability

🔥 Ready to debug smarter? Install Debugg today!

bun add universal-error-handler

Star this repository if you love debugging again! ⭐

📚 Explore our comprehensive documentation:

• API Documentation
• Brand Identity
• Quality Framework
• Exit Strategy