nanoid

README

go-nanoid

This module is a Go implementation of nanoid.

Features of the nanoid spec are:

• URL friendly
• Use of hardware random generator
• Uses a bigger alphabet than UUID, so a similar number of random bits are packed in just 21 chars instead of 36 (like UUID)
• Much, much faster than UUID (v4)

Features of this specific implementation are:

• Fastest and most performant implementation of Nano ID around (benchmarks)
• Prefetches random bytes in advance
• Uses optimal memory
• No production dependencies

Install

go get github.com/jaevor/go-nanoid

Security

See comparison of Nano ID and UUID (V4):

"Nano ID is quite comparable to UUID v4 (random-based). It has a similar number of random bits in the ID (126 in Nano ID and 122 in UUID), so it has a similar collision probability -- for there to be a one in a billion chance of duplication, 103 trillion version 4 IDs must be generated"

And NanoID collision calculator:

If 1,000,000 Nano IDs (using nanoid.Standard(21)) were generated each second, it would require ~41 thousand years in order to have a 1% probability of a collision

In other words, with 21 characters, the total number of possible unique IDs would be 21^64, which is ~four septenvigintillion (4 followed by 84 zeros) -- a figure larger than the number of atoms that exist in the universe, apparently

Read more here

Example

import (
	"log"
	"github.com/jaevor/go-nanoid"
)

func main() {
	canonic, err := nanoid.Standard(21)
	if err != nil {
		panic(err)
	}

	id1 := canonic()
	log.Printf("ID 1: %s", id1) // se-jlhSbQbwlviPDFbfGe

	// Makes sense to use CustomASCII since 0-9 is ascii.
	custom, err := nanoid.CustomASCII("0123456789", 12)
	if err != nil {
		panic(err)
	}

	id2 := custom()
	log.Printf("ID 2: %s", id2) // 466568050433
}

Notes

Attempted to make non-secure generation of Nano IDs but removed it because I can't figure out a way to generate many random bytes/numbers efficiently with PRNG

Benchmarks

All benchmarks & tests can be found in nanoid_test.go.

These are all benchmarks of the Standard Nano ID generator

# of characters & # of IDs	benchmark screenshot
8, ~21,800,000
21, ~16,400,000
36, ~11,500,000
255, ~2,500,000

Credits & references

• Original reference
• Outdated (by 2+ years) Go implementation

License

MIT License

Documentation

Index

• func Custom(alphabet string, length int) (generator, error)
• func CustomASCII(alphabet string, length int) (generator, error)
• func CustomUnicode(alphabet string, length int) (generator, error)
• func Standard(length int) (generator, error)

Functions

func Custom

func Custom(alphabet string, length int) (generator, error)

Will be deprecated; same as nanoid.CustomUnicode.

🟡 Change to using nanoid.CustomUnicode.

func CustomASCII

func CustomASCII(alphabet string, length int) (generator, error)

Returns a Nano ID generator which uses a custom alphabet that is of ASCII.

Uses less memory by only supporting ASCII and not unicode. For unicode support use nanoid.CustomUnicode.

⛔ Returns error if length is not, or within 2 and 255.

🧿 Concurrency safe.

func CustomUnicode

func CustomUnicode(alphabet string, length int) (generator, error)

Returns a Nano ID generator which uses a custom alphabet that is allowed to contain non-ASCII (unicode).

Uses more memory by supporting unicode. For ASCII-only, use nanoid.CustomASCII.

⛔ Returns error if length is not, or within 2 and 255.

🧿 Concurrency safe.

func Standard

func Standard(length int) (generator, error)

Returns a new generator of standard Nano IDs.

📝 Recommended (standard) length is 21

⛔ Returns error if length is not, or within 2 and 255.

🧿 Concurrency safe.