utils

LazyGophers Utils

🚀 A powerful, modular Go utility library designed for modern development workflows

🌍 Languages: English • 中文 • 繁體中文 • Español • Français • Русский • العربية

🎯 What is LazyGophers Utils?

LazyGophers Utils is a comprehensive Go utility library that provides 20+ specialized modules for common development tasks. Built with modern Go practices, it offers type-safe, high-performance solutions that integrate seamlessly into any Go project.

✨ Why Choose LazyGophers Utils?

• 🧩 Modular by Design - Import only what you need
• ⚡ Performance First - Optimized for speed and minimal memory usage
• 🛡️ Type Safety - Leverages Go generics for compile-time safety
• 🔒 Production Ready - Goroutine-safe and battle-tested
• 📖 Developer Friendly - Comprehensive documentation and examples

🚀 Quick Start

Installation

go get github.com/lazygophers/utils

30-Second Example

package main

import (
    "fmt"
    "github.com/lazygophers/utils"
    "github.com/lazygophers/utils/candy"
    "github.com/lazygophers/utils/xtime"
)

func main() {
    // Error handling made simple
    data := utils.Must(loadData()) // Panics on error

    // Type conversions without hassle
    userAge := candy.ToInt("25")
    isActive := candy.ToBool("true")

    // Advanced time handling
    calendar := xtime.NowCalendar()
    fmt.Printf("Today: %s\n", calendar.String())
    fmt.Printf("Lunar: %s\n", calendar.LunarDate())
}

func loadData() (string, error) {
    return "Hello, World!", nil
}

📦 Module Overview

🔧 Core Utilities

🍭 Data Processing

⏰ Time & Scheduling

🔧 System & Configuration

🌐 Network & Security

🚀 Concurrency & Control Flow

🧪 Development & Testing

💡 Real-World Examples

Configuration Management

type AppConfig struct {
    Database string `json:"database" validate:"required"`
    Port     int    `json:"port" default:"8080" validate:"min=1,max=65535"`
    Debug    bool   `json:"debug" default:"false"`
}

func main() {
    var cfg AppConfig

    // Load from any format: JSON, YAML, TOML, etc.
    utils.MustSuccess(config.Load(&cfg, "config.yaml"))

    // Validate configuration
    utils.MustSuccess(utils.Validate(&cfg))

    fmt.Printf("Server starting on port %d\n", cfg.Port)
}

Database Operations

type User struct {
    ID    int64  `json:"id"`
    Name  string `json:"name" validate:"required"`
    Email string `json:"email" validate:"required,email"`
    Age   int    `json:"age" default:"0" validate:"min=0,max=150"`
}

func SaveUser(db *sql.DB, user *User) error {
    // Validate struct
    if err := utils.Validate(user); err != nil {
        return err
    }

    // Convert to database format
    data, err := utils.Value(user)
    if err != nil {
        return err
    }

    // Save to database
    _, err = db.Exec("INSERT INTO users (data) VALUES (?)", data)
    return err
}

Advanced Time Processing

func timeExample() {
    cal := xtime.NowCalendar()

    // Gregorian calendar
    fmt.Printf("Date: %s\n", cal.Format("2006-01-02"))

    // Chinese lunar calendar
    fmt.Printf("Lunar: %s\n", cal.LunarDate())          // 农历二零二三年六月廿九
    fmt.Printf("Animal: %s\n", cal.Animal())            // 兔 (Rabbit)
    fmt.Printf("Solar Term: %s\n", cal.CurrentSolarTerm()) // 处暑 (End of Heat)

    // Work schedule calculations
    if xtime996.IsWorkTime(time.Now()) {
        fmt.Println("Time to work! (996 schedule)")
    }
}

Concurrent Processing

func processingExample() {
    // Create a worker pool
    pool := routine.NewPool(10) // 10 workers
    defer pool.Close()

    // Submit tasks with circuit breaker protection
    for i := 0; i < 100; i++ {
        taskID := i
        pool.Submit(func() {
            // Circuit breaker protects against failures
            result := hystrix.Do("process-task", func() (interface{}, error) {
                return processTask(taskID)
            })

            fmt.Printf("Task %d result: %v\n", taskID, result)
        })
    }

    // Wait for completion with timeout
    wait.For(5*time.Second, func() bool {
        return pool.Running() == 0
    })
}

🎨 Design Philosophy

Error Handling Strategy

LazyGophers Utils promotes a fail-fast approach for development efficiency:

// Traditional Go error handling
data, err := risky.Operation()
if err != nil {
    return nil, fmt.Errorf("operation failed: %w", err)
}

// LazyGophers approach - cleaner, faster development
data := utils.Must(risky.Operation()) // Panics on error

Type Safety with Generics

Modern Go generics enable compile-time safety:

// Type-safe operations
func process[T constraints.Ordered](items []T) T {
    return candy.Max(items...) // Works with any ordered type
}

// Runtime safety
value := utils.MustOk(getValue()) // Panics if second return value is false

Performance Optimization

Every module is benchmarked and optimized:

• Zero-allocation paths in critical functions
• sync.Pool usage to reduce GC pressure
• Efficient algorithms for common operations
• Minimal dependencies to reduce binary size

📊 Performance Highlights

🤝 Contributing

We welcome contributions! Here's how to get started:

Quick Contribution Guide

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Write code with tests
4. Ensure tests pass: go test ./...
5. Submit a pull request

Development Standards

• ✅ Follow Go Code Review Comments
• 📖 All public APIs must have godoc comments
• 🧪 New features require comprehensive tests
• 📊 Maintain high test coverage
• 🔄 Preserve backward compatibility

Building and Testing

# Run tests
make test

# Run tests with coverage
make test-coverage

# Lint code
make lint

# Format code
make fmt

# Full development cycle
make check

📄 License

This project is licensed under the GNU Affero General Public License v3.0.

See the LICENSE file for details.

🌟 Community & Support

Get Help

• 📖 Documentation: Complete API Reference
• 🐛 Bug Reports: GitHub Issues
• 💬 Discussions: GitHub Discussions
• ❓ Questions: Stack Overflow

Acknowledgments

Thanks to all our contributors who make this project possible!