A lightweight utility library for Go projects, designed to simplify logging, common tasks across JSON handling, file operations, validation, encryption, temporal types — and now production‑grade error handling. Built for clarity, composability, and long‑term maintainability.

• Logging - with structured logging for prod and easy to read logging for development
• Faults — Structured Errors With Stack Traces
• Read & write JSON
• Error JSON responses with optional status codes
• Unified error handling helper (HandleError)
• File upload & static file download
• Random string generation
• HTTP JSON POST helper
• XML writer
• Directory creation utilities
• URL‑safe slug generation
• Validation helpers
• Encryption & decryption utilities

go get -u github.com/fouched/toolkit/v2

Toolkit v2 includes a lightweight but powerful error system designed for real‑world services. Key capabilities

• Automatic stack capture at the point of failure
• Context‑rich error wrapping (faults.Wrap)
• Annotation without stack pollution (faults.Annotate)
• Root‑cause extraction (faults.Root)
• Stack inspection (faults.Stack)
• Pretty stack formatting with %+v
• Drop‑in compatibility with errors.Is and errors.As

if err != nil {
    return faults.Wrap(err, "repo: failed to insert user")
}

To attach a stack to a foreign error:

return faults.WithStack(err)

To add context without changing the origin:

return faults.Annotate(err, "service: user creation failed")

🖨️ Pretty Logging Integration

Toolkit v2 includes development‑friendly slog handlers that automatically detect faults.Error values and print:

• the full error chain
• the captured stack trace
• file + line + function for each frame

ERROR 2026-04-02T14:14:29+02:00 failed to accept relationship request
err: repo: failed to insert relationship: ERROR: duplicate key...
stack:
    /internal/repo/relationship_repo.go:56  (*RelationshipRepo).Insert
    /internal/services/relationship_service.go:37  (*RelationshipService).Add
...

🕒 Temporal Types

Includes two production‑ready temporal primitives: DateOnly TimeOnly Both provide:

• JSON marshalling/unmarshalling
• SQL scanning & value support
• Nullable semantics
• Formatting & comparison helpers

Designed to avoid zero‑value ambiguity while remaining ergonomic.

The DateOnly and TimeOnly types are designed to:

• Represent nullable date/time values
• Integrate seamlessly with JSON, SQL, and domain logic
• Avoid zero-value ambiguity by using *time.Time internally
• Provide comparison, conversion, and formatting utilities