randomstring

Documentation

Overview

Package randomstring is a standard-library port of the npm "randomstring" library. It generates random strings from named character-set presets or a custom character set using crypto/rand for unbiased sampling.

Random strings are a common building block for tokens, temporary passwords, session identifiers, file names, and test fixtures. This package packages that need behind a small API: pick a length and either a named charset or a literal set of characters, and receive a string of that length drawn from those characters. Because the source of randomness is crypto/rand, the output is suitable for security-sensitive identifiers, unlike helpers built on math/rand.

Sampling is uniform and unbiased. For each output position the code draws a value in [0, len(charset)) with crypto/rand's rand.Int, which uses rejection sampling internally, so no character is favored even when the charset length does not evenly divide the size of the random space. The charset is treated as a slice of runes, so multi-byte Unicode characters count as a single symbol and are emitted whole.

Three entry points cover the common cases. GenerateFrom takes an explicit character set and is the lowest-level primitive. Generate selects one of the named presets: "alphanumeric" (the default when the name is empty), "alphabetic", "numeric", "hex", "binary", and "octal". New is a convenience wrapper returning a 32-character alphanumeric string, the library's typical default token.

Error semantics are explicit. A negative length is rejected, an empty charset is rejected, and an unknown preset name returns an error rather than falling back silently. A length of zero is valid and yields the empty string. The main parity difference from the npm original is shape rather than behavior: where the JavaScript version exposes a single options object with fields like length, charset, capitalization, and readable, this port offers a small set of explicit functions and leaves higher-level formatting to the caller.

Index

• func Generate(length int, charset string) (string, error)
• func GenerateFrom(length int, chars string) (string, error)
• func New() (string, error)

Examples

• Generate
• New

Functions

func Generate

func Generate(length int, charset string) (string, error)

Generate returns a random string of the requested length using a preset character set. An empty charset defaults to "alphanumeric".

Example

ExampleGenerate draws a random string of a requested length from a named preset character set. Because the output is random it cannot be printed verbatim in a deterministic example, so this checks the two guaranteed properties instead: the length matches what was requested, and every character comes from the chosen "numeric" preset. Sampling uses crypto/rand for unbiased, security-grade randomness. An empty charset name would default to "alphanumeric". Here a 16-character numeric string is produced.

package main

import (
	"fmt"
	"strings"

	"github.com/malcolmston/express/randomstring"
)

func main() {
	s, err := randomstring.Generate(16, "numeric")
	if err != nil {
		panic(err)
	}
	allDigits := strings.Trim(s, "0123456789") == ""
	fmt.Println(len(s), allDigits)
}

Output:
16 true

func GenerateFrom

func GenerateFrom(length int, chars string) (string, error)

GenerateFrom returns a random string of the requested length drawn uniformly from the literal character set chars using crypto/rand.

func New

func New() (string, error)

New returns a 32-character alphanumeric random string.

Example

ExampleNew returns the library's default token: a 32-character alphanumeric string suitable for identifiers and one-off secrets. The value is random, so the example verifies only its length rather than its contents. New is a thin convenience wrapper over Generate with the "alphanumeric" preset and a length of 32. Every character is drawn from crypto/rand, so the result is safe for security-sensitive use. This is the typical starting point when you just need a random token.

package main

import (
	"fmt"

	"github.com/malcolmston/express/randomstring"
)

func main() {
	s, err := randomstring.New()
	if err != nil {
		panic(err)
	}
	fmt.Println(len(s))
}

Output:
32