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 9 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

🤖 AI Agent Instructions

Repository Type: Go utility library providing production-ready infrastructure components

Critical Setup: Run task docker:up for PostgreSQL services (localhost:5439, user: jasoet, password: localhost, database: pkg_db)

Architecture: Multi-package library (not an application)

• 9 core packages: config, logging, db, server, rest, concurrent, temporal, ssh, compress, grpc
• Each package has comprehensive examples with go run -tags=example ./package/examples
• Integration-ready design where packages work seamlessly together

Key Development Patterns:

• Configuration: Type-safe YAML with environment variable overrides (config package)
• Database: Multi-database support (PostgreSQL, MySQL, MSSQL) with GORM and migrations (db package)
• HTTP Server: Echo framework with built-in health checks, metrics, graceful shutdown (server package)
• gRPC Server: Production-ready gRPC server with Echo gateway integration, H2C mode, observability (grpc package)
• HTTP Client: Resilient REST client with retries and middleware (rest package)
• Logging: Zerolog structured logging with context-aware patterns (logging package)
• Concurrency: Type-safe concurrent execution with Go 1.23+ generics (concurrent package)
• Workflows: Temporal integration for distributed workflows (temporal package)

Testing Strategy:

• Unit tests: task test (with race detection and coverage in output/ directory)
• Integration tests: task integration-test (uses testcontainers for databases)
• Temporal tests: task temporal-test (starts Temporal server)
• All integration tests: task all-integration-tests
• Coverage reports: task coverage (generates output/coverage.html)
• Always use assert library (github.com/stretchr/testify/assert) for all test assertions

Library Usage Focus: When helping developers, emphasize zero-configuration startup, type safety, and production-grade features (health endpoints, metrics, observability, graceful shutdown)

🤝 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
• gRPC & Protobuf Support: Production-ready gRPC server with Echo gateway integration
• Distributed Tracing: OpenTelemetry integration

📄 License

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