nanoid

README

Nano ID

A tiny, fast and convenient Go unique string ID generator.

• Safe. It uses cryptographically strong random APIs and tests distribution of symbols.
• Compact. It uses a larger alphabet than UUID (A-Za-z0-9_-). So ID size was reduced from 36 to 21 symbols.

id := nanoid.New() //=> i25_rX9zwDdDn7Sg-ZoaH

Installation

go get github.com/aidarkhanov/nanoid

Thanks to

• Andrey Sitnik for the original JavaScript algorithm implementation.
• Paul Yuan for allowing me to improve the Python version of the library. Without the previous work, I would not be able to fully understand the algorithm.

Documentation

Overview

Package nanoid provides fast and convenient unique string ID generator.

Index

• func Format(random BytesGenerator, alphabet string, size int) (string, error)
• func Generate(alphabet string, size int) (string, error)
• func Must(id string, err error) string
• func MustFormat(random BytesGenerator, alphabet string, size int) string
• func MustGenerate(alphabet string, size int) string
• func New() string
• type BytesGenerator

Examples

• Format
• Generate
• MustFormat
• MustGenerate
• New

Functions

func Format

func Format(random BytesGenerator, alphabet string, size int) (string, error)

Format generates a random string with the passed in bytes generator.

Example

package main

import (
	"crypto/rand"
	"fmt"

	"github.com/aidarkhanov/nanoid"
)

func main() {
	alphabet := "-0123456789ABCDEFGHIJKLNQRTUVWXYZ_cfgijkpqtvxz"
	size := 21

	// randomBytesGenerator returns random bytes buffer
	// to pass it in Format function
	randomBytesGenerator := func(step int) ([]byte, error) {
		buffer := make([]byte, step)
		if _, err := rand.Read(buffer); err != nil {
			return nil, err
		}
		return buffer, nil
	}

	id, err := nanoid.Format(randomBytesGenerator, alphabet, size)
	if err != nil {
		panic(err)
	}

	fmt.Println(id)
}

func Generate

func Generate(alphabet string, size int) (string, error)

Generate generates a random string.

Example

package main

import (
	"fmt"

	"github.com/aidarkhanov/nanoid"
)

func main() {
	alphabet := "-0123456789ABCDEFGHIJKLNQRTUVWXYZ_cfgijkpqtvxz"
	size := 21

	id, err := nanoid.Generate(alphabet, size)
	if err != nil {
		panic(err)
	}

	fmt.Println(id)
}

func Must

func Must(id string, err error) string

Must returns a random string if err is nil and panics otherwise.

func MustFormat

func MustFormat(random BytesGenerator, alphabet string, size int) string

MustFormat is like Format but panics if a random string cannot be generated.

Example

package main

import (
	"crypto/rand"
	"fmt"

	"github.com/aidarkhanov/nanoid"
)

func main() {
	alphabet := "-0123456789ABCDEFGHIJKLNQRTUVWXYZ_cfgijkpqtvxz"
	size := 21

	// randomBytesGenerator returns random bytes buffer
	// to pass it in Format function
	randomBytesGenerator := func(step int) ([]byte, error) {
		buffer := make([]byte, step)
		if _, err := rand.Read(buffer); err != nil {
			return nil, err
		}
		return buffer, nil
	}

	id := nanoid.MustFormat(randomBytesGenerator, alphabet, size)

	fmt.Println(id)
}

func MustGenerate

func MustGenerate(alphabet string, size int) string

MustGenerate is like Generate but panics if a random string cannot be generated.

Example

package main

import (
	"fmt"

	"github.com/aidarkhanov/nanoid"
)

func main() {
	alphabet := "-0123456789ABCDEFGHIJKLNQRTUVWXYZ_cfgijkpqtvxz"
	size := 21

	id := nanoid.MustGenerate(alphabet, size)

	fmt.Println(id)
}

func New

func New() string

New generates a random string based on default alphabet and size.

Example

package main

import (
	"fmt"

	"github.com/aidarkhanov/nanoid"
)

func main() {
	id := nanoid.New()

	fmt.Println(id)
}

Types

type BytesGenerator

type BytesGenerator func(step int) ([]byte, error)

BytesGenerator represents calculated random bytes buffer.