pkg

🚀 Go Utility Packages

A comprehensive collection of production-ready Go utility packages designed to eliminate boilerplate and standardize common patterns across Go applications. These battle-tested components integrate seamlessly to accelerate development while maintaining best practices.

📦 What's Inside

🎯 Quick Start

Installation

go get github.com/jasoet/pkg

Basic Usage

This library provides production-ready infrastructure components. Each package has comprehensive examples and documentation:

🚀 Jump to Examples:

• Configuration Examples - YAML config with environment overrides
• Logging Examples - Structured logging setup
• Server Examples - HTTP server with health checks
• Database Examples - Multi-database connectivity
• REST Client Examples - HTTP client with retries
• More examples below...

📚 Packages Overview

This library provides 8 core packages, each with comprehensive examples and documentation:

🎭 Examples & Usage

Running Examples

Each package has comprehensive examples isolated with build tags:

# Run specific package examples
go run -tags=example ./logging/examples
go run -tags=example ./db/examples
go run -tags=example ./server/examples

# Build all examples
go build -tags=example ./...

Example Categories

• Basic Usage: Simple getting-started examples
• Integration Patterns: Real-world usage with multiple packages
• Production Scenarios: Error handling, performance, security
• Best Practices: Recommended patterns and configurations

Each package's examples directory contains a comprehensive README with:

• Quick reference for LLMs/coding agents
• Step-by-step tutorials
• Common patterns and anti-patterns
• Integration examples with other packages

🔧 Development

Prerequisites

• Go 1.23+
• Task for build automation
• Docker & Docker Compose for services

Development Commands

# Development environment
task docker:up          # Start PostgreSQL and other services
task test              # Run unit tests
task integration-test  # Run integration tests
task lint              # Run linter
task security          # Security analysis
task coverage          # Generate coverage report

# Docker services management
task docker:down       # Stop services
task docker:restart    # Restart services
task docker:logs       # View service logs

# Quality checks
task checkall          # Run all quality checks
task dependencies      # Check for vulnerabilities
task docs              # Generate documentation

Database Configuration

PostgreSQL is available for testing:

• Host: localhost:5439
• Username: jasoet
• Password: localhost
• Database: pkg_db

🤝 Contributing

We welcome contributions! Please read our Contributing Guide for details.

Quick Contribution Guide

1. Fork & Clone

   git clone https://github.com/your-username/pkg.git
   cd pkg
   

2. Setup Development Environment

   task docker:up
   task test
   

3. Create Feature Branch

   git checkout -b feature/your-feature-name
   

4. Make Changes & Test

   task test
   task lint
   task integration-test
   

5. Commit with Conventional Commits

   git commit -m "feat: add new feature"
   git commit -m "fix: resolve issue"
   git commit -m "docs: update README"
   

6. Push & Create PR

   git push origin feature/your-feature-name
   # Create pull request on GitHub
   

Commit Message Format

We use Conventional Commits:

<type>(<scope>): <description>

[optional body]

[optional footer]

Types: feat, fix, docs, style, refactor, test, chore Breaking Changes: Add ! after type or BREAKING CHANGE: in footer

📈 Roadmap

• Core Packages: All essential utilities implemented
• Integration Examples: Real-world usage patterns
• Build Automation: Task-based development workflow
• CI/CD Pipeline: Automated testing and releases
• Comprehensive Documentation: Examples and guides
• Performance Benchmarks: Optimization guides and metrics
• Distributed Tracing: OpenTelemetry integration
• Additional Database Drivers: MongoDB, Redis support
• Cloud Provider Integrations: AWS, GCP, Azure utilities
• Kubernetes Helpers: Service discovery, health checks

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.