_ _ _ _ ___ ____ _ __
| | | || | | ||_ _| _ \ | |/ /___ _ _
| | | || | | | | || | | | | ' // _ \ | | |
| |_| || |_| | | || |_| | | . \ __/ |_| |
\___/ \___/ |___|____/ |_|\_\___|\__, |
|___/ 
The uuidkey package encodes UUIDs to a readable Key format via the Base32-Crockford codec.
This package is designed to work with any UUID that follows the official UUID specification (RFC 4122). If your UUID implementation adheres to this standard, it should be compatible with this package.
We specifically test and maintain compatibility with the following UUID libraries:
- github.com/gofrs/uuid (v4.4.0+)
- github.com/google/uuid (v1.6.0+)
While we officially support and test against these specific versions, any UUID library that follows the RFC 4122 specification should work with this package.
To install the uuidkey package, use the following command:
go get github.com/agentstation/uuidkeyTo use the uuidkey package in your Go code, follow these steps:
- Import the package:
import "github.com/agentstation/uuidkey"- Encode a UUID string to a Key type:
key, _ := uuidkey.Encode("d1756360-5da0-40df-9926-a76abff5601d")
fmt.Println(key) // Output: 38QARV0-1ET0G6Z-2CJD9VA-2ZZAR0X- Decode a Key type to a UUID string with Key format validation:
key, _ := uuidkey.Parse("38QARV0-1ET0G6Z-2CJD9VA-2ZZAR0X")
uuid, err := key.UUID()
if err != nil {
log.Fatal("Error:", err)
}
fmt.Println(uuid) // Output: d1756360-5da0-40df-9926-a76abff5601d- Decode a Key type to a UUID string with only basic Key length validation:
key, _ := uuidkey.Parse("38QARV0-1ET0G6Z-2CJD9VA-2ZZAR0X")
uuid, err := key.Decode()
if err != nil {
log.Fatal("Error:", err)
}
fmt.Println(uuid) // Output: d1756360-5da0-40df-9926-a76abff5601dimport "github.com/agentstation/uuidkey"Package uuidkey encodes UUIDs to a readable Key format via the Base32-Crockford codec.
Key validation constraint constants
const (
// KeyLength is the total length of a valid UUID Key, including hyphens.
KeyLength = 31 // 7 + 1 + 7 + 1 + 7 + 1 + 7 = 31 characters
// KeyPartLength is the length of each part in a UUID Key.
// A UUID Key consists of 4 parts separated by hyphens.
KeyPartLength = 7
// KeyHyphenCount is the number of hyphens in a valid UUID Key.
KeyHyphenCount = 3
// KeyPartsCount is the number of parts in a valid UUID Key.
KeyPartsCount = KeyHyphenCount + 1
// UUIDLength is the standard length of a UUID string, including hyphens.
// Reference: RFC 4122 (https://tools.ietf.org/html/rfc4122)
UUIDLength = 36
)type Key
Key is a UUID Key string.
type Key stringfunc Encode
func Encode(uuid string) (Key, error)Encode will encode a given UUID string into a Key with basic length validation.
func EncodeBytes
func EncodeBytes(uuid [16]byte) (Key, error)EncodeBytes encodes a [16]byte UUID into a Key.
func Parse
func Parse(key string) (Key, error)Parse converts a Key formatted string into a Key type.
func (Key) Bytes
func (k Key) Bytes() ([16]byte, error)Bytes converts a Key to a [16]byte UUID.
func (Key) Decode
func (k Key) Decode() (string, error)Decode will decode a given Key into a UUID string with basic length validation.
func (Key) String
func (k Key) String() stringString will convert your Key into a string.
func (Key) UUID
func (k Key) UUID() (string, error)UUID will validate and convert a given Key into a UUID string.
func (Key) Valid
func (k Key) Valid() boolValid verifies if a given Key follows the correct format. The format should be:
- 31 characters long
- Uppercase
- Contains only alphanumeric characters
- Contains 3 hyphens
- Each part is 7 characters long
Examples of valid keys:
- 38QARV0-1ET0G6Z-2CJD9VA-2ZZAR0X
- ABCDEFG-1234567-HIJKLMN-OPQRSTU
Examples of invalid keys:
- 38QARV0-1ET0G6Z-2CJD9VA-2ZZAR0 (too short)
- 38qarv0-1ET0G6Z-2CJD9VA-2ZZAR0X (contains lowercase)
- 38QARV0-1ET0G6Z-2CJD9VA-2ZZAR0X- (extra hyphen)
- 38QARV0-1ET0G6Z-2CJD9VA2ZZAR0X (missing hyphen)
- 38QARV0-1ET0G6-2CJD9VA-2ZZAR0X (part too short)
Generated by gomarkdoc
jack@devbox ➜ make help
Usage:
make <target>
General
help Display the list of targets and their descriptions
Tooling
install-devbox Install Devbox
devbox-update Update Devbox
devbox Run Devbox shell
Installation
install Download go modules
Development
fmt Run go fmt
generate Generate and embed go documentation into README.md
vet Run go vet
lint Run golangci-lint
Benchmarking, Testing, & Coverage
bench Run Go benchmarks
test Run Go tests
coverage Run tests and generate coverage reportNote: These benchmarks were run on an Apple M2 Max CPU with 12 cores (8 performance and 4 efficiency) and 32 GB of memory, running macOS 14.6.1.
Your mileage may vary.
make bench
Running go benchmarks...
go test ./... -tags=bench -bench=.
goos: darwin
goarch: arm64
pkg: github.com/agentstation/uuidkey
cpu: Apple M2 Max
BenchmarkValidate-12 33527211 35.72 ns/op
BenchmarkParse-12 32329798 36.96 ns/op
BenchmarkFromKey-12 4886846 250.6 ns/op
BenchmarkEncode-12 3151844 377.0 ns/op
BenchmarkDecode-12 5587066 216.7 ns/op
BenchmarkValidateInvalid-12 1000000000 0.2953 ns/op
BenchmarkParseValid-12 32424325 36.89 ns/op
BenchmarkParseInvalid-12 70131522 17.01 ns/op
BenchmarkUUIDValid-12 4693452 247.2 ns/op
BenchmarkUUIDInvalid-12 70141429 16.92 ns/op
PASS
ok github.com/agentstation/uuidkey 13.365s