documentation

Author: MonkyMars

README.md

@@ -1,151 +1,237 @@
 # Gecho
 
-![gecho banner](https://static.wixstatic.com/media/a002ff_126a2882368c4a9c9194eb59df5d2cc4~mv2.jpg/v1/fill/w_640,h_332,al_c,q_80,usm_0.66_1.00_0.01,enc_avif,quality_auto/a002ff_126a2882368c4a9c9194eb59df5d2cc4~mv2.jpg)
+A Go library for structured logging and consistent JSON HTTP responses.
 
+## Install
+
+```bash
+go get github.com/MonkyMars/gecho
+```
 
-A lightweight JSON response builder for Go HTTP handlers.
+## What It Does
 
-## What it is
+Gecho provides two main features:
 
-`gecho` provides a lightweight, functional options-based API for building and sending consistent JSON HTTP responses from Go handlers. It offers success and error helpers, customizable message/data/status, and built-in method validation helpers using a pattern similar to structured logging.
+1. **Structured Logger** - A thread-safe logger with multiple output formats and log levels
+2. **HTTP Response Builder** - Consistent JSON responses for HTTP handlers
 
-## Install
+## Response Handling
 
-Requires Go toolchain.
+### Basic Usage
 
-```bash
-go get github.com/MonkyMars/gecho
+```go
+import "github.com/MonkyMars/gecho"
+
+func handler(w http.ResponseWriter, r *http.Request) {
+    // Success response
+    gecho.Success(w, gecho.Send())
+    
+    // Success with data
+    gecho.Success(w,
+        gecho.WithData(map[string]any{"id": 1, "name": "Alice"}),
+        gecho.Send(),
+    )
+    
+    // Error response
+    gecho.NotFound(w,
+        gecho.WithMessage("User not found"),
+        gecho.Send(),
+    )
+}
 ```
 
-## Quick example
+### Available Functions
 
-```go
-import (
-    "github.com/MonkyMars/gecho"
-)
+**Success Responses:**
+- `Success(w, opts...)` - 200 OK
+- `Created(w, opts...)` - 201 Created
+- `Accepted(w, opts...)` - 202 Accepted
+- `NoContent(w, opts...)` - 204 No Content
 
-// Success response with data
-gecho.Success(w, 
-    gecho.WithData(map[string]any{"id": 1, "name": "Alice"}),
-    gecho.Send(),
-)
+**Error Responses:**
+- `BadRequest(w, opts...)` - 400 Bad Request
+- `Unauthorized(w, opts...)` - 401 Unauthorized
+- `Forbidden(w, opts...)` - 403 Forbidden
+- `NotFound(w, opts...)` - 404 Not Found
+- `MethodNotAllowed(w, opts...)` - 405 Method Not Allowed
+- `Conflict(w, opts...)` - 409 Conflict
+- `InternalServerError(w, opts...)` - 500 Internal Server Error
+- `ServiceUnavailable(w, opts...)` - 503 Service Unavailable
 
-// Error response with custom message
-gecho.BadRequest(w, 
-    gecho.WithMessage("invalid input"),
-    gecho.Send(),
-)
+### Options
 
-// Multiple options
-gecho.NotFound(w,
-    gecho.WithMessage("User not found"),
-    gecho.WithData(map[string]string{"resource": "users", "id": "123"}),
-    gecho.Send(),
-)
-```
+- `WithData(data any)` - Add data to response
+- `WithMessage(msg string)` - Override default message
+- `WithStatus(code int)` - Override default status code
+- `Send()` - Send the response (required)
 
-## Response Format
+### Response Format
 
-All responses return a consistent JSON structure:
+All responses return this JSON structure:
 
 ```json
 {
   "status": 200,
   "success": true,
   "message": "Success",
-  "data": {
-    "id": 1,
-    "name": "Alice"
-  },
+  "data": {"id": 1, "name": "Alice"},
   "timestamp": "2024-01-15T10:30:45.123Z"
 }
 ```
 
-## Available Options
+## Logger
 
-- `gecho.WithData(data any)` - Set response data
-- `gecho.WithMessage(message string)` - Override the default message
-- `gecho.WithStatus(status int)` - Override the default status code
-- `gecho.Send()` - Send the response immediately
+### Basic Usage
+
+```go
+import "github.com/MonkyMars/gecho"
 
-## Common Usage Patterns
+func main() {
+    // Create logger with defaults
+    logger := gecho.NewDefaultLogger()
+    
+    // Log messages
+    logger.Info("Server starting")
+    logger.Error("Failed to connect")
+    
+    // Log with fields
+    logger.Info("User logged in",
+        gecho.Field("user_id", 123),
+        gecho.Field("ip", "192.168.1.1"),
+    )
+}
+```
 
-### Success Responses
+### Configuration
 
 ```go
-// 200 OK
-gecho.Success(w, gecho.WithData(userData), gecho.Send())
+// Custom configuration
+config := gecho.NewConfig(
+    gecho.WithLogLevel(gecho.LevelDebug),
+    gecho.WithLogFormat(gecho.FormatJSON),
+    gecho.WithShowCaller(true),
+)
+logger := gecho.NewLogger(config)
+
+// Change level at runtime
+logger.SetLevel(gecho.ParseLogLevel("debug"))
+```
 
-// 201 Created
-gecho.Created(w, gecho.WithData(newResource), gecho.Send())
+### Configuration Options
 
-// 202 Accepted
-gecho.Accepted(w, gecho.Send())
+- `WithLogLevel(level Level)` - Set minimum log level (default: `LevelInfo`)
+- `WithLogFormat(format Format)` - Set output format (default: `FormatPretty`)
+- `WithColorize(bool)` - Enable/disable colored output (default: auto-detected)
+- `WithShowCaller(bool)` - Show/hide file and line number (default: `true`)
+- `WithTimeFormat(string)` - Custom time format (default: `"2006-01-02 15:04:05.000"`)
+- `WithOutput(io.Writer)` - Set output destination (default: `os.Stdout`)
+- `WithErrorOutput(io.Writer)` - Set error output destination (default: `os.Stderr`)
+- `WithDefaultCallerSkip(int)` - Adjust call stack depth for caller info (default: `2`)
 
-// 204 No Content
-gecho.NoContent(w, gecho.Send())
-```
+### Log Levels
+
+- `LevelDebug` - Debug messages
+- `LevelInfo` - Informational messages
+- `LevelWarn` - Warning messages
+- `LevelError` - Error messages
+- `LevelFatal` - Fatal errors (exits program)
+
+### Output Formats
 
-### Error Responses
+- `FormatText` - Plain text with fields
+- `FormatJSON` - JSON output
+- `FormatPretty` - Colored output with parentheses format (default)
+
+### Persistent Fields
 
 ```go
-// 400 Bad Request
-gecho.BadRequest(w, gecho.WithData(validationErrors), gecho.Send())
+// Create logger with persistent fields
+requestLogger := logger.WithFields(map[string]any{
+    "request_id": "abc123",
+    "user_id": 456,
+})
+
+requestLogger.Info("Processing request") // All logs include request_id and user_id
+```
 
-// 401 Unauthorized
-gecho.Unauthorized(w, gecho.Send())
+### HTTP Logging Middleware
 
-// 403 Forbidden
-gecho.Forbidden(w, gecho.Send())
+```go
+func main() {
+    mux := http.NewServeMux()
+    mux.HandleFunc("/", handler)
+    
+    logger := gecho.NewDefaultLogger()
+    loggedHandler := gecho.Handlers.HandleLogging(mux, logger)
+    
+    http.ListenAndServe(":8080", loggedHandler)
+}
+```
 
-// 404 Not Found
-gecho.NotFound(w, gecho.Send())
+Logs include method, path, status, duration, and remote address.
 
-// 500 Internal Server Error
-gecho.InternalServerError(w, gecho.Send())
+## Method Validation
+
+```go
+func handler(w http.ResponseWriter, r *http.Request) {
+    // Only allow POST requests
+    if err := gecho.Handlers.HandleMethod(w, r, http.MethodPost); err != nil {
+        return // Error response already sent
+    }
+    
+    // Handle POST request
+}
 ```
 
-### Full Example
+## Full Example
 
 ```go
-func getUserHandler(w http.ResponseWriter, r *http.Request) {
-    id := r.URL.Query().Get("id")
+package main
+
+import (
+    "net/http"
+    "github.com/MonkyMars/gecho"
+)
+
+func main() {
+    mux := http.NewServeMux()
+    mux.HandleFunc("/users", getUsers)
 
-    if id == "" {
-        gecho.BadRequest(w,
-            gecho.WithMessage("Missing user ID"),
-            gecho.Send(),
-        )
+    logger := gecho.NewDefaultLogger()
+    loggedHandler := gecho.Handlers.HandleLogging(mux, logger)
+    
+    http.ListenAndServe(":8080", loggedHandler)
+}
+
+func getUsers(w http.ResponseWriter, r *http.Request) {
+    if err := gecho.Handlers.HandleMethod(w, r, http.MethodGet); err != nil {
         return
     }
 
-    user, err := findUser(id)
-    if err != nil {
-        gecho.NotFound(w, utils.Send())
-        return
+    users := []map[string]any{
+        {"id": 1, "name": "Alice"},
+        {"id": 2, "name": "Bob"},
     }
 
     gecho.Success(w,
-        gecho.WithData(user),
+        gecho.WithData(map[string]any{"users": users}),
         gecho.Send(),
     )
 }
 ```
 
-For more detailed examples and documentation, see [USAGE.md](USAGE.md).
-
-## Project layout
+## Project Structure
 
-- `gecho.go` — package entry points
-- `errors/` — error response helpers
-- `success/` — success response helpers
-- `handlers/` — small built-in handlers (method validation)
-- `utils/` — core builder and JSON logic
+- `gecho.go` - Main package exports
+- `errors/` - Error response functions
+- `success/` - Success response functions
+- `handlers/` - HTTP middleware and utilities
+- `utils/` - Core response builder and logger
 
 ## Contributing
 
-Contributions welcome:) Please open issues or pull requests and include a short description and tests for behavior changes.
+Contributions are welcome. Open an issue or pull request with a description and tests for changes.
 
-## Important
+## Note
 
-This library is provided as is. Backward compatibility is not guaranteed. Breaking changes may occur. 
+This library is provided as-is. Breaking changes may occur between versions.