____ _ _ _ ___ ____
| _ \ _ _| |__ | (_) ___|_ _| _ \
| |_) | | | | '_ \| | |/ __|| || | | |
| __/| |_| | |_) | | | (__ | || |_| |
|_| \__,_|_.__/|_|_|\___|___|____/ 
The publicid package generates and validates NanoID strings designed to be publicly exposed.
The publicid package is designed to generate and validate unique, public-facing identifiers with a focus on simplicity, efficiency, and usability. Key design decisions include:
- Uses a 62-character alphabet:
0-9,A-Z, anda-z - Excludes special characters like
_and-to maintain a clean "block of characters" visual concept - Prioritizes easy copy-paste functionality, assuming this as the most common use case
- Default IDs: 8 characters
- Long IDs: 12 characters
- Default IDs: 1% collision probability after generating 8 billion IDs at 25 IDs/hour (~10 years)
- Long IDs: 1% collision probability after generating 8 billion IDs at 25 IDs/second (~10 years)
- Simplicity: Easy to generate and validate IDs
- URL-friendly: Suitable for use in web applications
- Configurable: Options for ID length and generation attempts
- Efficient: Fast generation and validation processes
These design choices aim to balance uniqueness, readability, and practical usage in modern web applications. The package is particularly suited for scenarios requiring public-facing, easy-to-share identifiers with a low risk of collisions.
For a detailed analysis of collision probabilities, refer to the NanoID Collision Calculator.
go get github.com/agentstation/publicidTo use the publicid package in your Go code, follow these steps:
- Import the package:
import "github.com/agentstation/publicid"- Generate a default public ID (8 characters):
id, _ := publicid.New()
fmt.Println("Generated default public ID:", id)
// Output: Generated default public ID: Ab3xY9pQ- Generate a long public ID (12 characters):
longID, _ := publicid.New(publicid.Long)
fmt.Println("Generated long public ID:", longID)
// Output: Generated long public ID: 7Zt3xY9pQr5W- Use the
Attemptsoption to specify the number of generation attempts:
id, _ := publicid.New(publicid.Attempts(5))
fmt.Println("Generated public ID within 5 attempts:", id)
// Output: Generated public ID within 5 attempts: Kj2mN8qL- Validate a default public ID:
defaultID := "Ab3xY9pQ"
err := publicid.Validate(defaultID)
if err != nil {
fmt.Println("Invalid default ID:", err)
} else {
fmt.Println("Valid default ID:", defaultID)
}
// Output: Valid default ID: Ab3xY9pQ- Validate a long public ID:
longID := "7Zt3xY9pQr5W"
err := publicid.Validate(longID, publicid.Long)
if err != nil {
fmt.Println("Invalid long ID:", err)
} else {
fmt.Println("Valid long ID:", longID)
}
// Output: Valid long ID: 7Zt3xY9pQr5Wimport "github.com/agentstation/publicid"Package publicid generates and validates NanoID strings designed to be publicly exposed. It uses the nanoid library to generate IDs and provides options to configure the generation process.
- Constants
- func New(opts ...Option) (string, error)
- func Validate(id string, opts ...Option) error
- type Option
const (
// DefaultAlphabet is the set of characters used for generating public IDs.
// It includes 0-9, A-Z, and a-z, providing a balance between uniqueness and readability.
DefaultAlphabet = "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz"
// DefaultIDLength is the default length for public IDs.
// Set to 8 characters, it provides a 1% collision probability after generating
// 8 billion IDs at 25 IDs/hour over approximately 10 years, assuming the use of DefaultAlphabet.
DefaultIDLength = 8
// LongIDLength is the length for long public IDs.
// Set to 12 characters, it provides a 1% collision probability after generating
// 8 billion IDs at 25 IDs/second over approximately 10 years, assuming the use of DefaultAlphabet.
LongIDLength = 12
)func New
func New(opts ...Option) (string, error)New generates a unique nanoID with a length of 8 characters and the given options.
func Validate
func Validate(id string, opts ...Option) errorValidate checks if a given field name's public ID value is valid according to the constraints defined by package publicid.
type Option
Option is a function type for configuring ID generation.
type Option func(*config)Long returns an Option to set the length of the ID to be generated to 12.
var Long Option = Len(LongIDLength)func Alphabet
func Alphabet(a string) OptionAlphabet returns an Option to set the alphabet to be used for ID generation.
func Attempts
func Attempts(n int) OptionAttempts returns an Option to set the number of attempts for ID generation.
func Len
func Len(len int) OptionLen returns an Option to set the length of the ID to be generated.
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.
go test -bench=.
goos: darwin
goarch: arm64
pkg: github.com/agentstation/publicid
BenchmarkNew-12 2012978 574.8 ns/op
BenchmarkNewWithAttempts-12 2091734 577.3 ns/op
BenchmarkLong-12 1966120 616.9 ns/op
BenchmarkLongWithAttempts-12 1952052 610.4 ns/op
BenchmarkValidate-12 100000000 10.73 ns/op
BenchmarkValidateLong-12 99347000 13.31 ns/op
PASS
ok github.com/agentstation/publicid 9.790s