mango-go

A collection of utility packages for go
📚 Explore the docs »

🔎 View Examples · 🐛 Report Bug · 💡 Request Feature

📂 Table of Contents

1. 📋 About The Project
2. 🚀 Getting Started
   • 📘️ Prerequisites
   • 🛠️ Installation
   • 📦 Packages
   • 🧑‍💻 Developer Guide
3. 👨‍💻 Usage
4. 📝 Contributing
   • ❓ How to Contribute
   • ✨ Getting started with contributing
5. 📜 License
6. 👏 Acknowledgments
   🤝 Contributors 🙌 Special Mentions

📋 About the project

mango-go is a grab-bag of small, dependency-light utilities we found ourselves rewriting across services. Every package is:

• Focused – each folder solves a single problem (logging, env parsing, random data, etc.).
• Drop-in – import paths live under github.com/bitstep-ie/mango-go/pkg/....
• Well-documented – every package ships with dedicated docs plus a developer guide full of copy-paste examples.
• CI-backed – linted, tested, and mutation-tested in CI so helpers stay reliable.

🚀 Getting started

All you need to start using mango-go

📘️ Prerequisites

• Go version: mango-go requires Go version 1.24 or above
• Basic Go knowledge: Familiarity with Go syntax and package management is helpful

🛠️ Installation

go get github.com/bitstep-ie/mango-go@latest

Modules are versioned, so you can pin a specific tag in go.mod if required. With Go's module support, simply import mango-go in your code and Go will automatically fetch it during build:

import "github.com/bitstep-ie/mango-go"

📦 Packages

Package	What it does	Docs
env	read env vars with defaults or panic-on-missing helpers	docs
io	delete/backup/restore files by extension for safe inline edits	docs
logger	opinionated slog handler with CLI/file/syslog outputs	docs
net	network helpers	docs
random	math/crypto random helpers for fixtures, passwords, timestamps	docs
slices	generic slice utilities (contains, chunk, unique, etc.)	docs
testutils	test helpers for temp files and UUID/token assertions	docs
time	start/end-of-day helpers, duration parsing, “time ago” strings	docs

Looking for a tour that stitches these together?
👉 Developer Guide

🔁 Quick start

package main

import (
	"context"
	"log/slog"
	"time"
	mangoenv "github.com/bitstep-ie/mango-go/pkg/env"
	mangolog "github.com/bitstep-ie/mango-go/pkg/logger"
	mangotime "github.com/bitstep-ie/mango-go/pkg/time"
)

func main() {
	cfg := &mangolog.LogConfig{
		MangoConfig: &mangolog.MangoConfig{
			Strict:        true,
			CorrelationId: &mangolog.CorrelationIdConfig{AutoGenerate: true},
		},
		Out: &mangolog.OutConfig{
			Enabled: true,
			Cli:     &mangolog.CliConfig{Enabled: true, Friendly: true, Verbose: true},
			File:    &mangolog.FileOutputConfig{Enabled: false},
		},
	}

	logger := slog.New(mangolog.NewMangoLogger(cfg))
	ctx := context.Background()
	ctx = context.WithValue(ctx, mangolog.APPLICATION, "billing-api")
	ctx = context.WithValue(ctx, mangolog.OPERATION, "invoice-create")
	ctx = context.WithValue(ctx, mangolog.TYPE, mangolog.BusinessType)

    timeout, err := mangoenv.IntDefault("HTTP_TIMEOUT", 15)
    if err != nil {
      panic(err)
    }
	deadline := mangotime.TimeAgo(mangotime.EndOfDay(time.Now()))

	logger.InfoContext(ctx, "ready to serve",
		slog.Int("timeoutSeconds", timeout),
		slog.String("deadline", deadline),
	)
}

Run the snippet to see CLI-friendly output plus structured JSON (when file logging is enabled).

Deprecated env helpers (EnvOrDefault, MustEnv, EnvAsInt, MustEnvAsInt, EnvAsBool, MustEnvAsBool) are scheduled for removal in v1.0.0.

🧑‍💻 Developer Guide

Looking for end-to-end examples that combine logging, environment loading, random data generation, time helpers, and more?
👉 Jump into documentation/docs/guide.md.

👨‍💻 Usage

The packages are intentionally orthogonal, so feel free to mix and match:

import (
"log/slog"
"time"
mangorand "github.com/bitstep-ie/mango-go/pkg/random"
mangoslices "github.com/bitstep-ie/mango-go/pkg/slices"
mangotime "github.com/bitstep-ie/mango-go/pkg/time"
)

func demo() {
orders := []int{1, 2, 2, 3}
if mangoslices.EqualsIgnoreOrder(orders, []int{3, 2, 2, 1}) {
token := mangorand.Password(20, mangorand.PasswordOptions{Letters: true, Digits: true})
start := mangotime.StartOfDay(time.Now())
end := mangotime.EndOfDay(time.Now())

slog.Info("processing window",
slog.String("token", token),
slog.String("start", start.Format(time.RFC3339)),
slog.String("end", end.Format(time.RFC3339)),
)
}
}

Check each package doc (table above) for deeper walkthroughs and additional helpers.

📝 Contributing

We welcome and appreciate your contributions!

❓ How to Contribute

• 🐛 Report bugs - Help us identify and fix issues
• 💡 Suggest features - Share your ideas for improvements
• 📝 Improve documentation - Help make our docs clearer
• 🔧 Submit code - Fix bugs or implement new features
• 🧪 Write tests - Improve our test coverage

✨ Getting started with contributing

• Check out our contributing.md for detailed guidelines
• Join our community discussions and ask questions

All contributions are valued and help make mango better for everyone!

📜 License

👏 Acknowledgments

🤝 Contributors

🙌 Special Mentions

Ronan

Ben