randomstring

README

go-randomstring

Fast, flexible random string generation for Go — ids, tokens, and passwords in one small, dependency-free package.

Features

• 🔤 Flexible character sets — seven built-in universes, or bring your own (Unicode included).
• 🔒 Crypto-secure mode — draw from crypto/rand for passwords and security tokens.
• 🔁 Unique batches — generate thousands of guaranteed-distinct strings in one call.
• 🎲 Deterministic output — pin a Seed for reproducible results in tests.
• 🚀 Fast — an ASCII fast path with zero dependencies beyond the standard library.

Installation

go get github.com/gbbocchini/go-randomstring

Quick start

package main

import (
	"fmt"

	"github.com/gbbocchini/go-randomstring"
)

func main() {
	r := randomstring.Randomizer{
		Universe: randomstring.LowerUpperDigits,
		Length:   13,
	}
	id, err := r.GenerateOne()
	if err != nil {
		panic(err)
	}
	fmt.Println(id)
}

Usage

Basic generation

r := randomstring.Randomizer{
	Universe: randomstring.LowerLetters,
	Length:   8,
}
id, err := r.GenerateOne()

Unique batches

Set Unique to guarantee every string in a batch is distinct:

r := randomstring.Randomizer{
	Universe: randomstring.LowerUpperDigits,
	Length:   8,
	Unique:   true,
}
ids, err := r.Generate(10_000) // 10,000 distinct ids

Crypto-secure passwords

r := randomstring.Randomizer{
	Universe: randomstring.LowerUpperDigitsSymbols,
	Length:   32,
	Secure:   true,
}
password, err := r.GenerateOne()

Deterministic output (great for tests)

r := randomstring.Randomizer{
	Universe: randomstring.LowerUpperDigits,
	Length:   13,
	Seed:     1,
}
id, _ := r.GenerateOne() // always "9g14r5YgIsx9v"

Custom universe

r := randomstring.Randomizer{
	Universe: "ABC123", // only these characters
	Length:   6,
}

Built-in character sets

Constant	Contents
LowerLetters	a-z
UpperLetters	A-Z
Digits	0-9
Symbols	!@#$%&*()-_+={};:.,
LowerUpperLetters	a-z + A-Z
LowerUpperDigits	a-z + A-Z + 0-9
LowerUpperDigitsSymbols	a-z + A-Z + 0-9 + symbols

Documentation

Full API reference is available on pkg.go.dev.

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change, and update tests as appropriate.

License

MIT © Gabriel Bocchini

Documentation

Overview

Package randomstring generates random strings for use as identifiers, tokens, passwords, and anywhere else you need short, configurable random text.

The core type is Randomizer, configured through exported struct fields:

r := randomstring.Randomizer{
	Universe: randomstring.LowerUpperDigits,
	Length:   13,
	Unique:   true,
}
id, err := r.GenerateOne()

The package also provides ready-made character sets (LowerLetters, UpperLetters, Digits, Symbols, and their common combinations) that can be passed as a Randomizer's Universe.

Index

• Constants
• type Randomizer
  • func (r Randomizer) Generate(amount int) ([]string, error)
  • func (r Randomizer) GenerateOne() (string, error)
  • func (r Randomizer) UniquePermutations() *big.Int

Examples

• Randomizer.Generate
• Randomizer.GenerateOne
• Randomizer.GenerateOne (Secure)

Constants

const Digits = "0123456789"

Digits contains the decimal digits 0-9.

const LowerLetters = "abcdefghijklmnopqrstuvwxyz"

LowerLetters contains the lowercase ASCII letters a-z.

const LowerUpperDigits = LowerLetters + UpperLetters + Digits

LowerUpperDigits contains all lowercase and uppercase ASCII letters plus digits.

const LowerUpperDigitsSymbols = LowerUpperDigits + Symbols

LowerUpperDigitsSymbols contains all lowercase and uppercase ASCII letters, digits, and symbols.

const LowerUpperLetters = LowerLetters + UpperLetters

LowerUpperLetters contains all lowercase and uppercase ASCII letters.

const Symbols = "!@#$%&*()-_+={};:.,"

Symbols contains a set of common punctuation and symbol characters.

const UpperLetters = "ABCDEFGHIJKLMNOPQRSTUVWXYZ"

UpperLetters contains the uppercase ASCII letters A-Z.

Types

type Randomizer

type Randomizer struct {
	// Universe is the set of runes from which generated strings are drawn.
	// It must not be empty. Multi-byte (Unicode) runes are supported.
	Universe string

	// Length is the number of runes in each generated string. It must be
	// greater than zero.
	Length int

	// Unique, when true, makes a single call to Generate return amount
	// distinct strings. It has no effect on GenerateOne.
	Unique bool

	// Secure, when true, draws randomness from crypto/rand, producing output
	// suitable for passwords and other security-sensitive tokens. Secure
	// generation ignores Seed.
	Secure bool

	// Seed makes output deterministic: two Randomizers with the same
	// configuration and the same non-zero Seed produce identical output.
	// The zero value (the default) seeds from a random source. Seed is
	// ignored when Secure is true.
	Seed int64
}

Randomizer generates random strings according to its configuration.

A Randomizer value may be reused and shared across goroutines: all fields are read only during generation, and no mutable state is kept on the value.

func (Randomizer) Generate

func (r Randomizer) Generate(amount int) ([]string, error)

Generate generates amount random strings.

If Unique is set, the returned strings are all distinct. Generate returns an error if Universe is empty, Length is less than one, amount is negative, or Unique is set and amount exceeds the number of possible permutations.

Example

package main

import (
	"fmt"

	"github.com/gbbocchini/go-randomstring"
)

func main() {
	r := randomstring.Randomizer{
		Universe: randomstring.LowerUpperDigits,
		Length:   8,
		Unique:   true,
	}
	ids, err := r.Generate(1000)
	if err != nil {
		panic(err)
	}
	fmt.Println(len(ids))
}

Output:
1000

func (Randomizer) GenerateOne

func (r Randomizer) GenerateOne() (string, error)

GenerateOne generates a single random string.

It returns an error if Universe is empty or Length is less than one.

Example

package main

import (
	"fmt"

	"github.com/gbbocchini/go-randomstring"
)

func main() {
	r := randomstring.Randomizer{
		Universe: randomstring.LowerUpperDigits,
		Length:   13,
		Seed:     1,
	}
	id, err := r.GenerateOne()
	if err != nil {
		panic(err)
	}
	fmt.Println(id)
}

Output:
9g14r5YgIsx9v

Example (Secure)

package main

import (
	"fmt"

	"github.com/gbbocchini/go-randomstring"
)

func main() {
	r := randomstring.Randomizer{
		Universe: randomstring.LowerUpperDigitsSymbols,
		Length:   32,
		Secure:   true,
	}
	token, err := r.GenerateOne()
	if err != nil {
		panic(err)
	}
	fmt.Println(len(token))
}

Output:
32

func (Randomizer) UniquePermutations

func (r Randomizer) UniquePermutations() *big.Int

UniquePermutations returns the maximum number of distinct strings this Randomizer can produce, as a big.Int.

It is the number of distinct runes in Universe raised to the power of Length. When Universe contains no duplicate runes this equals len(Universe)^Length.