doc.go

// Copyright 2025 The Rivaas Authors
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

// Package errors provides framework-agnostic error formatting for HTTP responses.
//
// Create a formatter with [New] or [MustNew] and functional options. The default (no options)
// is RFC 9457 with empty base URL. Use [WithRFC9457], [WithJSONAPI], or [WithSimple] to choose
// the format. The package defines a [Formatter] interface and concrete implementations:
//   - RFC9457: RFC 9457 Problem Details (application/problem+json)
//   - JSONAPI: JSON:API error responses (application/vnd.api+json)
//   - Simple: Simple JSON error responses (application/json)
//
// The package is independent of any HTTP framework and can be used with any
// HTTP handler. Domain errors can implement optional interfaces (ErrorType,
// ErrorDetails, ErrorCode) to control status codes and provide structured details.
//
// The errors package follows the functional options pattern:
//   - Options (WithRFC9457, WithJSONAPI, WithSimple) apply to an internal config
//   - New() validates the config and builds the Formatter from it
//   - New() returns (Formatter, error); MustNew() panics on error
//
// # Quick Start
//
// Default formatter (RFC 9457, empty base URL):
//
//	formatter := errors.MustNew()
//
// Explicit formatter and options:
//
//	package main
//
//	import (
//		"encoding/json"
//		"net/http"
//		"rivaas.dev/errors"
//	)
//
//	func handler(w http.ResponseWriter, r *http.Request) {
//		err := someOperation()
//		if err != nil {
//			formatter := errors.MustNew(errors.WithRFC9457("https://api.example.com/problems"))
//			response := formatter.Format(r, err)
//			w.Header().Set("Content-Type", response.ContentType)
//			w.WriteHeader(response.Status)
//			json.NewEncoder(w).Encode(response.Body)
//			return
//		}
//	}
//
// JSON:API format:
//
//	formatter := errors.MustNew(errors.WithJSONAPI())
//	response := formatter.Format(r, err)
//
// Simple JSON format:
//
//	formatter := errors.MustNew(errors.WithSimple())
//	response := formatter.Format(r, err)
//
// # Error Interfaces
//
// Domain errors can implement optional interfaces to provide additional information:
//
//   - ErrorType: Declare HTTP status code
//   - ErrorDetails: Provide structured details (e.g., field-level validation errors)
//   - ErrorCode: Provide machine-readable error codes
//
// Example error with all interfaces:
//
//	type ValidationError struct {
//		Message string
//		Fields  []FieldError
//		Code    string
//	}
//
//	func (e ValidationError) Error() string {
//		return e.Message
//	}
//
//	func (e ValidationError) HTTPStatus() int {
//		return http.StatusBadRequest
//	}
//
//	func (e ValidationError) Details() any {
//		return e.Fields
//	}
//
//	func (e ValidationError) Code() string {
//		return e.Code
//	}
//
// # Standalone Usage
//
// This package works independently without the full Rivaas framework. Use it
// with any Go HTTP handler (net/http, Gin, Echo, etc.).
//
// # Examples
//
// See the example_test.go file for complete working examples.
package errors