go-utils/README.md

go-utils

A collection of generic utility functions for Go projects.

Installation

go get github.com/aykhans/go-utils

Packages

common

Generic type conversion utilities.

ToPtr - Convert any value to a pointer

import "github.com/aykhans/go-utils/common"

num := 42
ptr := common.ToPtr(num)  // *int

parser

String parsing utilities with generic type support.

ParseString - Parse string to various types

import "github.com/aykhans/go-utils/parser"

num, err := parser.ParseString[int]("42")
duration, err := parser.ParseString[time.Duration]("5s")
isValid, err := parser.ParseString[bool]("true")

ParseStringOrZero - Parse string or return zero value on error

num := parser.ParseStringOrZero[int]("invalid")  // returns 0

ParseStringWithDefault - Parse string with default value fallback

num, err := parser.ParseStringWithDefault("invalid", 10)  // returns 10, error

ParseStringOrDefault - Parse string or return default value without error

num := parser.ParseStringOrDefault("invalid", 10)  // returns 10

Supported types: string, int, int8, int16, int32, int64, uint, uint8, uint16, uint32, uint64, float64, bool, time.Duration, url.URL

slice

Slice manipulation utilities.

Cycle - Create an infinite cycler through items

import "github.com/aykhans/go-utils/slice"

next := slice.Cycle(1, 2, 3)
fmt.Println(next())  // 1
fmt.Println(next())  // 2
fmt.Println(next())  // 3
fmt.Println(next())  // 1

RandomCycle - Cycle through items with randomization

next := slice.RandomCycle(nil, "a", "b", "c")
// Cycles through all items, then starts from a random position

maps

Map utility functions.

InitMap - Initialize a map pointer if nil

import "github.com/aykhans/go-utils/maps"

var m map[string]int
maps.InitMap(&m)
m["key"] = 42  // safe to use

UpdateMap - Merge entries from one map into another

old := map[string]int{"a": 1, "b": 2}
new := map[string]int{"b": 3, "c": 4}
maps.UpdateMap(&old, new)
// old is now: {"a": 1, "b": 3, "c": 4}

errors

Advanced error handling utilities.

HandleError - Process errors with custom matchers

import "github.com/aykhans/go-utils/errors"

handled, result := errors.HandleError(err,
    errors.OnSentinelError(io.EOF, func(e error) error {
        return nil  // EOF is expected, ignore it
    }),
    errors.OnCustomError(func(e *CustomError) error {
        return fmt.Errorf("custom error: %w", e)
    }),
)

HandleErrorOrDie - Handle errors or panic if unhandled

result := errors.HandleErrorOrDie(err,
    errors.OnSentinelError(context.Canceled, func(e error) error {
        return fmt.Errorf("operation canceled")
    }),
)  // Panics if err doesn't match any handler

HandleErrorOrDefault - Handle errors with a default fallback

result := errors.HandleErrorOrDefault(err,
    func(e error) error {
        // Default handler for unmatched errors
        return fmt.Errorf("unexpected error: %w", e)
    },
    errors.OnSentinelError(context.Canceled, func(e error) error {
        return fmt.Errorf("operation canceled")
    }),
    errors.OnCustomError(func(e *ValidationError) error {
        return fmt.Errorf("validation failed: %w", e)
    }),
)

// Pass nil to suppress unmatched errors
result := errors.HandleErrorOrDefault(err, nil,
    errors.OnSentinelError(io.EOF, func(e error) error {
        return errors.New("EOF handled")
    }),
)  // Returns nil for unmatched errors

OnSentinelError - Create matcher for sentinel errors (like io.EOF)

matcher := errors.OnSentinelError(io.EOF, func(e error) error {
    log.Println("reached end of file")
    return nil
})

OnCustomError - Create matcher for custom error types

type ValidationError struct {
    Field string
    Msg   string
}

matcher := errors.OnCustomError(func(e *ValidationError) error {
    log.Printf("validation failed on field %s", e.Field)
    return fmt.Errorf("invalid input: %w", e)
})

Requirements

• Go 1.25.0 or higher