Process Incident Review Form

// Fast — no stack trace, 0 allocations with pooling err := errors.New("connection failed") // Formatted — full fmt verb support including %w err := errors.Newf("user %s not found", "alice") err := errors.Errorf("query failed: %w", cause) // alias of Newf // With stack trace err := errors.Trace("critical issue") err := errors.Tracef("query %s failed: %w", query, cause) // Named — useful for sentinel-style matching err := errors.Named("AuthError") // Standard library compatible err := errors.Std("connection failed") // returns plain error err := errors.Stdf("error %s", "detail") // formatted plain error

// Capture at creation err := errors.Trace("critical issue") // Add to an existing error err = err.WithStack() // Read frames for _, frame := range err.Stack() { fmt.Println(frame) // "main.go:42 main.main" } // Lightweight version (file:line only, no function names) for _, frame := range err.FastStack() { fmt.Println(frame) }

err := errors.New("processing failed"). With("user_id", "123"). With("attempt", 3). With("retryable", true) // Read back ctx := errors.Context(err) // map[user_id:123 attempt:3 retryable:true] // Check for a key if err.HasContextKey("user_id") { ... } // Variadic bulk attach err.With("k1", v1, "k2", v2) // Semantic helpers err.WithCode(500) err.WithCategory("network") err.WithTimeout() err.WithRetryable()

lowErr := errors.New("connection timeout").With("server", "db01") bizErr := errors.New("failed to load user").Wrap(lowErr) apiErr := errors.Wrapf(bizErr, "request failed: %w", bizErr) // Traverse for i, e := range errors.UnwrapAll(apiErr) { fmt.Printf("%d. %s\n", i+1, e) } // 1. request failed: ... // 2. failed to load user // 3. connection timeout

var ( ErrNotFound = errors.Const("not_found", "resource not found") ErrForbidden = errors.Const("forbidden", "access denied") ) // Match anywhere in a chain if errors.Is(err, ErrNotFound) { ... } // Add call-site context without losing the sentinel err := ErrNotFound.With("user 42 not found") errors.Is(err, ErrNotFound) // true — sentinel is the cause // JSON and slog work automatically b, _ := json.Marshal(ErrNotFound) // {"error":"resource not found","code":"not_found"} slog.Error("lookup failed", "err", ErrNotFound)

// Is — checks identity or name match err := errors.Named("AuthError") wrapped := errors.Wrapf(err, "login failed") errors.Is(wrapped, err) // true // As — extract the first matching *Error from the chain var target *errors.Error if errors.As(wrapped, &target) { fmt.Println(target.Name()) // "AuthError" } // Generic helpers (Go 1.18+) if e, ok := errors.AsType[*MyError](err); ok { ... } if errors.IsType[*MyError](err) { ... } found, ok := errors.FindType(err, func(e *MyError) bool { return e.Code() == 404 }) codes := errors.Map(err, func(e *MyError) int { return e.Code() }) errors.Filter[*MyError](err) // [] *MyError from chain errors.FirstOfType[*MyError](err) // first *MyError

// Basic m := errors.NewMultiError() m.Add(errors.New("name required")) m.Add(errors.New("email invalid")) fmt.Println(m.Count()) // 2 // With limits and sampling m := errors.NewMultiError( errors.WithLimit(100), errors.WithSampling(10), // 10% sample rate ) // Custom formatter m := errors.NewMultiError( errors.WithFormatter(func(errs []error) string { return fmt.Sprintf("%d errors", len(errs)) }), ) // Inspect m.First() // first error m.Last() // last error m.Errors() // []error snapshot m.Has() // bool m.Single() // nil | first error | *MultiError // Filter networkErrs := m.Filter(func(e error) bool { return strings.Contains(e.Error(), "network") }) // Merge two MultiErrors m.Merge(other) // Join is a convenience that collapses errors to *MultiError or nil err := errors.Join(err1, err2, err3)

retry := errors.NewRetry( errors.WithMaxAttempts(5), errors.WithDelay(200*time.Millisecond), errors.WithMaxDelay(2*time.Second), errors.WithJitter(true), errors.WithBackoff(errors.ExponentialBackoff{}), errors.WithRetryIf(errors.IsRetryable), errors.WithOnRetry(func(attempt int, err error) { log.Printf("attempt %d: %v", attempt, err) }), ) err := retry.Execute(func() error { return callExternalService() }) // Generic version — preserves return value result, err := errors.ExecuteReply[string](retry, func() (string, error) { return fetchData() }) // Context-aware ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second) defer cancel() retry2 := retry.Transform(errors.WithContext(ctx)) err = retry2.Execute(fn) // Backoff strategies errors.ConstantBackoff{} errors.LinearBackoff{} errors.ExponentialBackoff{}

chain := errors.NewChain( errors.ChainWithTimeout(10*time.Second), errors.ChainWithLogHandler(slog.Default().Handler()), ). Step(validateInput).Tag("validation"). Step(verifyKYC).Tag("kyc"). Step(processPayment).Tag("billing").Code(402). Retry(3, 100*time.Millisecond, errors.WithRetryIf(errors.IsRetryable)). Step(sendNotification).Tag("notification").Optional() if err := chain.Run(); err != nil { errors.Inspect(err, os.Stderr) } // Run all steps, collect every error if err := chain.RunAll(); err != nil { errors.Inspect(err, os.Stderr) }

chain.StepCtx(func(ctx context.Context) error { req, _ := http.NewRequestWithContext(ctx, "GET", url, nil) _, err := http.DefaultClient.Do(req) return err })

// Drain — block until channel closes, collect into *MultiError err := errors.Drain(errs) // First — return first non-nil error; ctx for deadline only, caller owns cancel err := errors.First(ctx, errs) if err != nil { cancel() // caller decides to stop siblings } // Collect — bounded sample; wraps ErrLimitReached when n is hit err := errors.Collect(ctx, errs, 10) if errors.Is(err, errors.ErrLimitReached) { log.Warn("more than 10 errors — some dropped") } // Fan — merge multiple error channels; caller must drain or cancel to avoid leak merged := errors.Fan(ctx, validateErrs, enrichErrs) for err := range merged { log.Println(err) }

// Process items concurrently, collect all errors s := errors.NewStream(ctx, urls, func(url string) error { return fetch(url) }, 8) // 8 workers; omit for len(items) workers // Option A — block until done if err := s.Wait(); err != nil { errors.Inspect(err, os.Stderr) } // Option B — process errors as they arrive s.Each(func(err error) { log.Println(err) }) // Stop early (drains channel to avoid goroutine leak) s.Stop()

// Resolve HTTP status from an *Error's code status := errors.HTTPStatusCode(err, http.StatusInternalServerError) // Write HTTP error response errors.HTTPError(w, err) // plain text, status from err.Code() // With options errors.HTTPError(w, err, errors.WithFallbackCode(http.StatusBadGateway), errors.WithBody(false), // header only errors.WithBodyFunc(func(e error) string { return fmt.Sprintf(`{"error":%q}`, e.Error()) }), )

g := errors.NewGroup() g.Go(func() error { return validateUser(id) }) g.Go(func() error { return validatePerms(id) }) if err := g.Wait(); err != nil { // err is *MultiError containing every failure errors.Inspect(err, os.Stderr) } // Context-aware g := errors.NewGroup( errors.GroupWithContext(ctx, true), // cancelOnFirst=true errors.GroupWithLimit(50), ) g.GoCtx(func(ctx context.Context) error { return longRunningCheck(ctx) }) _ = g.Wait()

// Default — writes to os.Stderr errors.Inspect(err) // Targeted output var buf bytes.Buffer errors.Inspect(err, &buf) // Multiple destinations errors.Inspect(err, os.Stderr, logFile) // Options errors.Inspect(err, os.Stderr, errors.WithStackFrames(5), errors.WithMaxDepth(20), ) // *Error-specific convenience errors.InspectError(err, os.Stderr)

slog.Error("request failed", "err", err) // produces structured group: err.message, err.name, err.code, err.category, err.context, err.cause slog.Error("lookup failed", "err", errors.ErrNotFound) // produces: err.error="resource not found", err.code="not_found"

// Pre-warm (called automatically at init with 100 instances) errors.WarmPool(1000) errors.WarmStackPool(500) // Tune global config errors.Configure(errors.Config{ StackDepth: 32, ContextSize: 4, DisablePooling: false, FilterInternal: true, AutoFree: false, // opt-in GC-based pool return }) // Explicit pool return (preferred) err := errors.New("temp") defer err.Free() // Copy without affecting original copied := err.Copy().With("extra", "data") // Transform (non-destructive) enriched := errors.Transform(err, func(e *errors.Error) { e.WithCode(500).With("env", "prod").WithStack() })

// Define a reusable template var ErrDBQuery = errmgr.Define("DBQuery", "database query failed: %s") // Instantiate with arguments err := ErrDBQuery("SELECT timed out") fmt.Println(err) // "database query failed: SELECT timed out" fmt.Println(err.Category()) // "database"

err := errmgr.ErrNotFound fmt.Println(err.Code()) // 404 err := errmgr.ErrDBQuery("SELECT failed")

netErr := errmgr.Define("NetError", "network issue: %s") monitor := errmgr.NewMonitor("NetError") errmgr.SetThreshold("NetError", 3) defer monitor.Close() go func() { for alert := range monitor.Alerts() { fmt.Printf("alert: %s (count: %d)\n", alert, alert.Count()) } }() err := netErr("timeout") err.Free()

// Before err := fmt.Errorf("user %s not found: %w", username, cause) // After — same output, plus context, code, and chain traversal err := errors.Newf("user %s not found: %w", username, cause). With("username", username). WithCode(404)

// Before err := pkgerrors.Wrap(cause, "operation failed") // After err := errors.New("operation failed").Wrap(cause).WithStack()

// Fully compatible — no changes needed if errors.Is(err, io.EOF) { ... } var target *errors.Error if errors.As(err, &target) { fmt.Println(target.Name()) }

errors.Inspect(err, os.Stderr, errors.WithMaxDepth(30), errors.WithStackFrames(10))

errors.Inspect(err, os.Stderr, logFile) // io.MultiWriter internally