README
¶
namegen — random adjective–noun names in Go
namegen is a tiny open source Go library that builds random, human-readable names by combining words from built-in lists. It is useful when you need memorable strings for development environments, internal hostnames, test databases, staging services, container or VM labels, demo tenants, or anywhere you want something easier to say than a UUID.
You describe the shape with a template string: each {adj} becomes a random adjective and each {noun} a random noun. That gives you the familiar “adjective-noun” style (similar in spirit to Docker’s random container names), with hundreds of thousands of combinations out of the box.
Install
go get github.com/Anhelmz/namegen
Requires Go 1.24+ (see go.mod). That is the lowest version where this module builds as-is: the library uses math/rand/v2, and the tests use testing.B.Loop.
Quick start
import "github.com/Anhelmz/namegen"
namegen.GenerateName("{adj}-{noun}") // e.g. swift-falcon
namegen.GenerateName("{adj}_{noun}") // e.g. nimble_harbor
namegen.GenerateName("{adj}_{adj}_{noun}") // two independent adjectives
The only public API is GenerateName(template string) string. Placeholders are replaced in one pass; every {adj} and {noun} gets its own random pick. Literal text (hyphens, underscores, digits you add yourself) is left as-is.
Custom vocabulary
Word lists live under words/ (adjectives.txt, nouns.txt): one word per line, # comments and blank lines ignored. They are embedded with //go:embed, so your binary ships with the lists you had at build time—fork the repo or vendor the package and edit the files to match your tone (strictly professional, playful, nature-only, etc.).
Vocabulary size and combination counts
The bundled lists currently contain 532 adjectives and 850 nouns. Separators (- vs _) do not change how many outcomes exist; only the number of placeholders matters.
| Template | Formula | Approximate combinations |
|---|---|---|
{adj}-{noun} or {adj}_{noun} |
532 × 850 | 452,200 |
{adj}_{adj}_{noun} |
532 × 532 × 850 | 240,570,400 |
Each placeholder is an independent draw, so the same adjective can appear twice in {adj}_{adj}_{noun}. After you change the word files, multiply your own counts the same way.
License
MIT
Documentation
Source Files