github.com/agentstation/uuidkey

                         _   _  _   _  ___ ____     _  __          
                        | | | || | | ||_ _|  _ \   | |/ /___ _   _ 
                        | | | || | | | | || | | |  | ' // _ \ | | |
                        | |_| || |_| | | || |_| |  | . \  __/ |_| |
                         \___/  \___/ |___|____/   |_|\_\___|\__, |
                                                             |___/ 

The uuidkey package encodes UUIDs to a readable Key format via the Base32-Crockford codec.

UUID Library Compatibility

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.

Installation

To install the uuidkey package, use the following command:

go get github.com/agentstation/uuidkey

Usage

To use the uuidkey package in your Go code, follow these steps:

1. Import the package:

import "github.com/agentstation/uuidkey"

1. Encode a UUID string to a Key type:

key, _ := uuidkey.Encode("d1756360-5da0-40df-9926-a76abff5601d")
fmt.Println(key) // Output: 38QARV0-1ET0G6Z-2CJD9VA-2ZZAR0X

1. 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

1. 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-a76abff5601d

uuidkey

import "github.com/agentstation/uuidkey"

Package uuidkey encodes UUIDs to a readable Key format via the Base32-Crockford codec.

Index

• Constants
• type Key
  • func Encode(uuid string) (Key, error)
  • func EncodeBytes(uuid [16]byte) (Key, error)
  • func Parse(key string) (Key, error)
  • func (k Key) Bytes() ([16]byte, error)
  • func (k Key) Decode() (string, error)
  • func (k Key) String() string
  • func (k Key) UUID() (string, error)
  • func (k Key) Valid() bool

Constants

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 string

func 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() string

String 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() bool

Valid 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

Makefile

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 report

Benchmarks

Note: 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