it 🎭

Installation 🚀

go get github.com/theHamdiz/it

Core Features

Error Handling (Because panic() is a lifestyle)

import "github.com/theHamdiz/it"
// The "I believe in miracles" approach
config := it.Must(LoadConfig())
// The "let's log and pray" method
user := it.Should(GetUser())
// Maybe we'll connect to the database... eventually
maybeConnect := it.Could(func() (*sql.DB, error) {
 return sql.Open("postgres", "postgres://procrastinator:later@localhost")
})
// Sometime later, when we feel ready...
db := maybeConnect() // First call actually does the work
alsoDb := maybeConnect() // Returns same result, wasn't worth trying again anyway
if value, ok := it.Might(maybeThisWorks); ok {
 // Nice, we got something
} else {
 // No biggie, we weren't counting on it anyway
}
// The "cover your tracks" strategy
err := it.WrapError(dbErr, "database had an existential crisis",
 map[string]any{"attempt": 42, "mood": "gothic"})

SafeGo - Panic-Proof Goroutines

import "github.com/theHamdiz/it"
// Fire and forget (but not really)
it.SafeGo(func() {
 DoSomethingDangerous() // We'll catch you if you fall
})
// For the context-aware crowd
it.SafeGoWithContext(ctx, func(ctx context.Context) {
 ResponsiblyDangerous(ctx) // Safety first, but make it contextual
})

Logging (Now with proper prefixes)

import "github.com/theHamdiz/it"
it.Trace("Like println() but fancier")
it.Debug("For when you're feeling verbose")
it.Info("FYI: Something happened")
it.Warn("Houston, we have a potential problem")
it.Error("Everything is fine 🔥")
it.Audit("For when legal is watching")
// Structured logging (because JSON makes everything enterpriseTM)
it.StructuredInfo("API Call", map[string]any{
 "status": 200,
 "response_time": "too long",
 "excuse": "network congestion"
})

Sub-Packages (For the Control Freaks)

Pool - Object Recycling Center

import "github.com/theHamdiz/it/pool"
pool_ := pool.NewPool(func() *ExpensiveObject {
 // Save the environment, reuse your objects
 return &ExpensiveObject{}
})
obj := pool_.Get()
// Return your shopping cart
defer pool_.Put(obj)

Debouncer - Function Anger Management

import "github.com/theHamdiz/it/debouncer"
calm := debouncer.NewDebouncer(100 * time.Millisecond)
relaxedFunc := calm.Debounce(func() {
 // Now with less spam
 NotifyEveryone("Updates!")
})

Load Balancer - Work Distribution Committee

import "github.com/theHamdiz/it/lb"
// Democratic work distribution
lb_ := lb.NewLoadBalancer(10)
err := lb_.Execute(ctx, func() error {
 // Share the pain
 return HeavyLifting()
})

Benchmarker - The Performance Theater

import "github.com/theHamdiz/it/bm"
// Run your function until the numbers look good
result := bm.Benchmark("definitely-fast", 1000, func() {
 SuperOptimizedCode() // yeah right
})
// Or collect your own timings when you don't trust us
timings := []time.Duration{...}
result := bm.AnalyzeBenchmark("probably-fast", timings)
// Slack-friendly output for bragging rights
fmt.Println(result) // Screenshots or it didn't happen

Exponential Backoff - Professional Failure Management

import "github.com/theHamdiz/it/retry"
// For when you're feeling optimistic
cfg := retry.DefaultRetryConfig()
// For when you know it's going to be rough
cfg := retry.Config{
 Attempts: 5,
 InitialDelay: time.Second,
 MaxDelay: 30 * time.Second,
 Multiplier: 2.0,
 RandomFactor: 0.1,
}
// Actually doing the thing
result, err := retry.WithBackoff(ctx, cfg, func(ctx context.Context) (string, error) {
 return CallThatFlakyService()
})

Shutdown Manager - Graceful Program Retirement

import "github.com/theHamdiz/it/sm"
// Set up the end times
sm_ := sm.NewShutdownManager()
// Add some last wishes
sm_.AddAction(
 "save-data",
 func(ctx context.Context) error {
 return db.Close()
 },
 5 * time.Second,
 true, // This one matters
)
// Start watching for the end
sm_.Start()
// Wait for the inevitable
if err := sm_.Wait(); err != nil {
 log.Fatal("Failed to die gracefully:", err)
}

// Or just use the global shortcut (for the pragmatists)
import "github.com/theHamdiz/it"
it.GracefulShutdown(ctx, server, 30*time.Second, done, func() {
 // Your last words here
})
// Need a phoenix-like rebirth?
it.GracefulRestart(ctx, server, 30*time.Second, done, func() {
 // Rise from the ashes
})

Rate Limiter - Traffic Control for Functions

// The proper way (for when you need full control)
import "github.com/theHamdiz/it/rl"
limiter := rl.NewRateLimiter(time.Second, 10)
defer limiter.Close()
err := limiter.Execute(ctx, func() error {
 return DoSomethingFast() // But not too fast
})
// Or better yet, with actual returns
result, err := rl.ExecuteRateLimited(limiter, ctx, func() (string, error) {
 return GetSomethingQuickly() // Responsibly quick
})

// The shortcut (for the rest of us)
import "github.com/theHamdiz/it"
// Turn any function into a well-behaved citizen
chillVersion := it.RateLimiter(time.Second, func() string {
 return IWouldSpamThisIfICould()
}).(func() string)
// Usage:
result := chillVersion() // Now properly paced
// Waiting (but not forever)
success := it.WaitFor(5*time.Second, func() bool {
 return systemIsReady() // Are we there yet?
})
if !success {
 // Time to give up and go home
}

Time Keeper - Time Tracking for the Obsessed

import "github.com/theHamdiz/it/tk"
// Basic timing
tk_ := tk.NewTimeKeeper("database-query").Start()
defer tk_.Stop()
// With a callback for the micromanagers
tk_ := tk.NewTimeKeeper("expensive-operation",
 tk.WithCallback(func(d time.Duration) {
 metrics.Record("too-slow", d)
 }),
).Start()
// Quick one-liner for the lazy
result := tk.TimeFn("important-stuff", func() string {
 return DoTheWork()
})
// Async timing for the parallel obsessed
atk := tk.NewAsyncTimeKeeper("batch-process")
for task := range tasks {
 atk.Track(func() { process(task) })
}
durations := atk.Wait()

// The dirty shortcut approach!!
import "github.com/theHamdiz/it"
result := it.TimeFunction("critical-operation", func() string {
 return DoSomethingWorthTiming()
})
// Block timing with defer
defer it.TimeBlock("expensive-stuff")()
// Custom timing callback
it.TimeFunctionWithCallback("important-task",
 func() string {
 return ExpensiveOperation()
 },
 func(d time.Duration) {
 if d > time.Second {
 alertSomeone() // Someone's being slow
 },
)
// Parallel timing (for the impatient)
durations := it.TimeParallel("batch-process",
 func() { task1() },
 func() { task2() },
 func() { task3() },
)
// Now you know which one to blame

Circuit Breaker - Your Code's Emotional Support System

import "github.com/theHamdiz/it/cb"
// Create a breaker that gives up after 3 failures
// and needs 30 seconds of alone time
breaker := cb.NewCircuitBreaker(3, 30*time.Second)
// Wrap your flaky calls with trust issues
err := breaker.Execute(func() error {
 return ThatThingThatAlwaysBreaks()
})
// Check if we're still in therapy
if breaker.IsOpen() {
 // Time to implement plan B
}

Result - Because nil Checks Are So 1970s

import "github.com/theHamdiz/it/result"
// For the optimists
res := result.Ok("success")
if res.IsOk() {
 value := res.UnwrapOr("plan B")
}
// For the realists
res := result.Try(func() string {
 return maybeExplode()
}).OrElse(func() Result[string] {
 return Ok("at least we tried")
})
// For the functional programming enthusiasts
result.Ok(42).
 Filter(isNotTooLarge).
 Map(addOne).
 Match(
 func(n int) { fmt.Println("Yay:", n) },
 func(err error) { /* pretend this never happened */ },
 )
// For those who like to live dangerously
value := result.Some(42).UnwrapOrPanic() // YOLO
// For the overachievers
pairs := result.Zip(
 result.Ok("hello"),
 result.Ok(42),
) // Because one value isn't complicated enough
// For when you need to fail collectively
results := result.Collect([]Result[int]{
 Ok(1), Ok(2), Err[int](errors.New("oops"))
}) // Misery loves company

Math - For The Algorithmically Gifted

import "github.com/theHamdiz/it/math"
// O(1) summation that would make Gauss proud
sum := math.Sum(1000000)
// Want to sum a specific range? We've got you covered
rangeSum := math.SumRange(42, 100)
// Need overflow protection? We're responsible adults here
safeSum, err := math.SumWithOverflowCheck(1000000)
// Living dangerously? MustSum will panic if things go wrong
yoloSum := math.MustSum(1000000)
// Sum of squares in O(1) because why not?
squares := math.SumOfSquares(100)
// Sum of cubes, because squares are so last century
cubes := math.SumOfCubes(50)
// Fourth powers, for when you really want to show off
fourthPowers := math.SumOfFourthPowers(25)
// Arithmetic series for the classically inclined
arithmetic := math.ArithmeticSeries(1, 2, 100) // 1, 3, 5, ...
// Geometric series for the exponentially minded
geometric := math.GeometricSeries(1, 2, 10) // 1, 2, 4, 8, ...
// Fast exponentiation because we're not savages
power := math.Pow(2, 10)
// Factorial without the stack overflow drama
factorial, err := math.Factorial(10)
// Need an approximation? Stirling's got your back
approxFact := math.FactorialStirlingApprox(100)
// Binomial coefficients without the tears
choose, err := math.Binomial(20, 10)
// Fibonacci that won't make your CPU cry
fib := math.Fibonacci(42)

import "github.com/theHamdiz/it"
// When you need a secret that's totally random*:
secret := it.GenerateSecret(32)
// *Usually uses crypto/rand, but if that fails... well, we get creative with time.
// It's like using your birthday as a password, but with nanoseconds. Security through obscurity!
// When your password is too lazy to protect itself:
hashed, err := it.HashPassword("mySuperSecret", 12)
// Your password is sent to a rigorous bootcamp (bcrypt rounds), emerging as a hardened hash with its own unique salt.
// If the bootcamp fails, you'll get a polite error message.
// Think your password can waltz past the velvet rope?
err = it.VerifyPassword(hashed, "mySuperSecret")
// If err is nil, congratulations—your password made the cut.
// Otherwise, it's like a bouncer telling you, "Not on the list, buddy."

Config - Because Hardcoding is a Crime

import (
	"github.com/theHamdiz/it/logger"
	"github.com/theHamdiz/it/cfg"
)
// You could use global shortcuts
// Redirect logs to your favorite black hole
file, _ := os.OpenFile("void.log", os.O_APPEND|os.O_CREATE|os.O_WRONLY, 0644)
it.SetLogOutput(file)
// Set log level from "meh" to "everything's on fire"
it.SetLogLevel(logger.LevelDebug)
// Let environment variables do the heavy lifting
// Optimist mode
os.Setenv("LOG_LEVEL", "PANIC")
// The ultimate backup strategy
os.Setenv("LOG_FILE", "/dev/null")
it.InitFromEnv()
// Or you could create a config with sensible* defaults
// *sensible is a relative term
cfg_ := cfg.Configure(
 cfg.WithLogLevel(logger.LevelDebug), // Maximum verbosity
 cfg.WithLogFile("regrets.log"), // For posterity
 cfg.WithShutdownTimeout(5*time.Second), // Ain't nobody got time for that
 cfg.WithColors(true), // Pretty errors are still errors
)
// Check what you did to yourself
if cfg_.ColorsEnabled() {
 // Congratulations, your logs are now fabulous
}

Version - Software Identity Management

// Get all the details
info := version.Get()
fmt.Println(info)
// Output: v1.2.3 built at 2023年12月25日T12:00:00Z from main@abc1234 (go1.21) running on linux/amd64 in production
// For your JSON APIs
jsonData, _ := json.Marshal(info.ToMap())
// Build with:
go build -ldflags="
 -X 'package/version.version=1.2.3'
 -X 'package/version.buildTime=$(date -u +"%Y-%m-%dT%H:%M:%SZ")'
 -X 'package/version.gitCommit=$(git rev-parse HEAD)'
 -X 'package/version.gitBranch=$(git rev-parse --abbrev-ref HEAD)'
 -X 'package/version.environment=production'"

Performance Notes

Known Features 🐛

FAQ 🤔

Contributing 🤝

License

Actual Serious Note