shortuuid

shortuuid is a small Go library that generates standard UUIDs using google/uuid and then re-encodes them into base57 strings — 22-character IDs built from an alphabet that excludes visually similar characters like 0, 1, I, O, and l. It solves one narrow, common problem: exposing non-sequential identifiers to end users without showing them a long, ugly 36-character UUID string in a URL or API response.

Beyond the default random (v4) ID generator, the library supports deterministic v5 UUIDs derived from a name, URL, or DNS input, custom alphabets for teams that want a different character set, and a pluggable Encoder interface for bringing an entirely custom encoding scheme such as base58. Output is designed to be compatible with the popular Python shortuuid library, making it a natural fit for polyglot systems that need identical short-ID behavior across Go and Python services.

What You Get

• A New() function producing base57-encoded v4 (random) UUIDs
• NewWithNamespace() for deterministic v5 UUIDs derived from a name, URL, or DNS input
• NewWithAlphabet() and NewWithEncoder() for custom character sets and encoding schemes
• A DefaultEncoder with Decode() support to reverse a short ID back into a standard UUID

Common Use Cases

• Generating public-facing IDs for database records exposed via API or URL
• Producing deterministic, repeatable IDs from a known name or URL
• Building short-link or slug generators with a custom alphabet
• Interoperating with the Python shortuuid library across polyglot services

Under The Hood

Architecture The library is a small, flat package (shortuuid.go, encoder.go, alphabet.go) with no internal layering — it’s a pure algorithmic wrapper around google/uuid. shortuuid.go defines the top-level API (New, NewWithNamespace, NewWithAlphabet, NewWithEncoder) plus the Encoder interface; alphabet.go defines an immutable, sorted/deduplicated character-set type built once via newAlphabet(); encoder.go defines two Encode/Decode implementations — a generic encoder that walks any alphabet using a custom 128-bit uint128 type built on math/bits primitives, and a specialized b57Encoder that hardcodes base57 division for the default alphabet. There’s no dependency injection or config layer — callers either use the package-level DefaultEncoder or construct and hold their own encoder value. The design is intentionally flat: since both encoders route UUID bytes through the same uint128 arithmetic, that arithmetic is the one place the whole package depends on.

Tech Stack Go 1.21+ (go.mod) with a single production dependency, github.com/google/uuid, for UUID generation and byte layout. Everything else comes from the standard library: encoding/binary for big-endian UUID byte decomposition, math/bits for the 64-bit multiply/divide/add primitives behind its custom uint128 type, unicode/utf8 for multi-byte alphabet support, unsafe for zero-copy string construction, crypto/sha1 for v5 UUID hashing, and slices for alphabet sorting and deduplication. Build tooling is limited to go build/go test; CI runs golangci-lint plus the full test suite across Ubuntu, macOS, and Windows. There’s no database, network, or external service dependency — this is a pure in-memory encoding library.

Code Quality Two test files (shortuuid_test.go, alphabet_test.go, roughly 440 lines combined) use the standard library testing package with a hand-rolled table of UUID/shortuuid string pairs exercising round-trip encode/decode correctness, plus dedicated tests for the alphabet’s sort/dedup behavior. Error handling is explicit and typed — Decode() returns a Go error for out-of-alphabet characters or 128-bit overflow rather than swallowing it, while NewWithAlphabet legitimately panics at construction time on invalid input (fewer than two alphabet characters), a reasonable fail-fast choice rather than a hidden failure. Naming is idiomatic Go, and every exported symbol carries a doc comment. CI enforces golangci-lint across three platforms. No benchmarks or fuzz tests were found, which would add real value for an encoding library like this one.

API Design The public API is minimal and ergonomic — shortuuid.New() is a single zero-argument call returning a ready-to-use ID string, and the four constructor functions form a clean progression from “just give me an ID” to “give me full control over the alphabet and encoding scheme” without forcing users to touch the Encoder interface unless they want to. Every exported identifier is documented, and the README shows working examples for each function, including a full custom-encoder (base58) walkthrough. The main rough edge is that NewWithAlphabet and NewWithEncoder re-derive an encoder on every call rather than letting callers hold a reusable one — a convenience-over-performance tradeoff the library’s own docs acknowledge.