forge

Go utility packages — small, composable, stdlib-first.

Quick Start

# Create a production Go service in one command
go run github.com/azghr/forge/cmd/forge@latest new api my-service
cd my-service
go run .

Or explore the starter template — a production-ready HTTP service showing Forge packages in action:

cd starter/service-template
go run .

CLI

forge is a CLI tool for working with Forge packages.

forge doctor               Check Go version, config validity, env issues
forge example <type>       Generate working example scaffold
forge new <type> <name>    Scaffold production-ready project
forge add <package>        Add forge package to your project

Install

go install github.com/azghr/forge/cmd/forge@latest

Or run from source:

go run ./cmd/forge <command>

Examples

Ready-to-run examples showing Forge packages working together:

• cli — Task manager CLI using flagsub, envconfig, tablewriter, sliceutil, shellquote, option, regexcache
• server — Task API server using flagsub, envconfig, validator, pathsafe, stringutil, atomicfile, stopwatch
• config — JSON config merger using jsonmerge, atomicfile, pathsafe
• pipeline — Data processing pipeline using orderedset, priorityqueue, queue, workerpool, cache, retry, lockutil, multityperror, mathutil

Run any example:

cd examples/<name>
go run .

Packages

• atomicfile — Atomic file writes without leaving partial data on failure.
• cache — Generic in-memory TTL cache.
• envconfig — Load environment variables into structs via tags.
• flagsub — Subcommand support for the standard flag package.
• jsonmerge — Recursively merge and diff JSON-like data.
• lockutil — Non-blocking TryLock and context-aware Lock for Mutex/RWMutex.
• mathutil — Small math helpers: Clamp, Sign, Lerp, GCD, ApproxEqual.
• multityperror — Aggregate multiple errors into one.
• option — Generic Option (Maybe) type for Go.
• orderedset — Insertion-ordered set with Union, Intersect operations.
• pathsafe — Safe path joining to prevent directory traversal.
• priorityqueue — Generic binary heap (min/max) with concurrency-safe push/pop.
• queue — Generic FIFO queue (ring-buffer, concurrency-safe, blocking dequeue).
• regexcache — Concurrency-safe cache for compiled regex patterns.
• retry — Retry operations with exponential backoff and full-jitter.
• shellquote — Shell-safe string quoting for POSIX and Windows.
• sliceutil — Generic slice operations: Map, Filter, Reduce, All, Any, Chunk.
• stopwatch — Simple stopwatch for benchmarking code blocks.
• stringutil — String transformations: Title, Slug, RemoveAccents.
• tablewriter — Format tabular data as ASCII tables.
• validator — Struct field validation via tags (nonzero, email).
• workerpool — Fixed-size worker goroutine pool.