Quick Start Guide¶

This guide will help you get started with ewrap quickly. We'll cover the basic concepts and show you how to use the main features of the package.

Basic Usage¶

Creating Errors¶

The simplest way to create an error with ewrap is using the New function:

err := ewrap.New("something went wrong")

Adding Context¶

You can add context to your errors using various options:

err := ewrap.New("database connection failed",
    ewrap.WithContext(ctx, ewrap.ErrorTypeDatabase, ewrap.SeverityCritical),
    ewrap.WithLogger(logger))

Wrapping Errors¶

When you want to add context to an existing error:

if err != nil {
    return ewrap.Wrap(err, "failed to process request")
}

Using Error Groups¶

Error groups help you collect and manage multiple errors:

// Create an error group pool
pool := ewrap.NewErrorGroupPool(4)

// Get an error group from the pool
eg := pool.Get()
defer eg.Release()  // Don't forget to release it back to the pool

// Add errors as needed
eg.Add(err1)
eg.Add(err2)

if eg.HasErrors() {
    return eg.Error()
}

Implementing Circuit Breaker¶

Protect your system from cascading failures:

cb := ewrap.NewCircuitBreaker("database", 3, time.Minute)

if cb.CanExecute() {
    err := performOperation()
    if err != nil {
        cb.RecordFailure()
        return err
    }
    cb.RecordSuccess()
}

Next Steps¶

Now that you understand the basics, you can:

Learn about Error Types
Explore Logging Integration
Study Advanced Usage
Check out complete Examples

Best Practices¶

Here are some best practices to follow when using ewrap:

Always provide meaningful error messages
Use appropriate error types and severity levels
Release error groups back to their pools
Configure circuit breakers based on your system's characteristics
Implement proper logging integration
Use metadata to add relevant debugging information

Common Patterns¶

Here are some common patterns you might find useful:

func processItem(ctx context.Context, item string) error {
    // Create error group from pool
    pool := ewrap.NewErrorGroupPool(4)
    eg := pool.Get()
    defer eg.Release()

    // Validate input
    if err := validate(item); err != nil {
        eg.Add(ewrap.Wrap(err, "validation failed",
            ewrap.WithContext(ctx),
            ewrap.WithErrorType(ewrap.ErrorTypeValidation)))
    }

    // Process if no validation errors
    if !eg.HasErrors() {
        if err := process(item); err != nil {
            return ewrap.Wrap(err, "processing failed",
                ewrap.WithContext(ctx),
                ewrap.WithErrorType(ewrap.ErrorTypeInternal))
        }
    }

    return eg.Error()
}

This is just a starting point. For more detailed information about specific features, check out the relevant sections in the documentation.