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
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 := mangoenv.EnvAsInt("HTTP_TIMEOUT", 15)
    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).

🧑‍💻 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