nanoid

README

Nano ID

A tiny and fast Go unique string 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.

nanoid.New() //> "i25_rX9zwDdDn7Sg-ZoaH"

Installation

Once Go is installed, run the following command to get Nano ID.

go get github.com/aidarkhanov/nanoid

Documentation

The package reference is located at pkg.go.dev/github.com/aidarkhanov/nanoid.

Roadmap

• The API of this package is frozen.
• Release patches if necessary.

License

This package is provided under MIT/Expat license. See LICENSE.md file for details.

Thanks to

• Andrey Sitnik for the original JavaScript algorithm implementation.
• Paul Yuan for letting me 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 generator.

Index

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

Examples

• Format
• Generate
• MustFormat
• MustGenerate
• New

Constants

const (
	// DefaultAlphabet is the default alphabet for Nano ID.
	DefaultAlphabet = "-0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ_abcdefghijklmnopqrstuvwxyz"
	// DefaultSize is the default size for Nano ID.
	DefaultSize = 21
)

Functions

func Format

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

Format generates a random string based on BytesGenerator, alphabet and size.

Example

package main

import (
	"crypto/rand"
	"fmt"

	"github.com/aidarkhanov/nanoid"
)

func main() {
	alphabet := nanoid.DefaultAlphabet
	size := nanoid.DefaultSize

	// generateBytesBuffer returns random bytes buffer
	generateBytesBuffer := 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(generateBytesBuffer, 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 based on alphabet and size.

Example

package main

import (
	"fmt"

	"github.com/aidarkhanov/nanoid"
)

func main() {
	alphabet := nanoid.DefaultAlphabet
	size := nanoid.DefaultSize

	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 or panics otherwise.

func MustFormat

func MustFormat(generateRandomBuffer 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 := nanoid.DefaultAlphabet
	size := nanoid.DefaultSize

	// generateBytesBuffer returns random bytes buffer
	generateBytesBuffer := 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(generateBytesBuffer, 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 := nanoid.DefaultAlphabet
	size := nanoid.DefaultSize

	id := nanoid.MustGenerate(alphabet, size)

	fmt.Println(id)
}

func New

func New() string

New generates a random string.

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 random bytes buffer.