https://github.com/aatuh/randutil
Cryptographically safe random utilities for Go. Helpers for generating random hex strings, tokens, numbers, bytes, UUIDs, emails etc. Thin wrappers around crypto/rand for everyday use.
https://github.com/aatuh/randutil
crypto-rand csprng developer-experience faker go go-generics golang permutation random random-stings randomness rejection-sampling rng sampling secure-random shuffle test-data uuid uuidv4 weighted-sampling
Last synced: 28 days ago
JSON representation
Cryptographically safe random utilities for Go. Helpers for generating random hex strings, tokens, numbers, bytes, UUIDs, emails etc. Thin wrappers around crypto/rand for everyday use.
- Host: GitHub
- URL: https://github.com/aatuh/randutil
- Owner: aatuh
- License: mit
- Created: 2025-09-15T18:02:37.000Z (5 months ago)
- Default Branch: master
- Last Pushed: 2025-10-02T13:05:00.000Z (4 months ago)
- Last Synced: 2025-10-02T15:11:49.103Z (4 months ago)
- Topics: crypto-rand, csprng, developer-experience, faker, go, go-generics, golang, permutation, random, random-stings, randomness, rejection-sampling, rng, sampling, secure-random, shuffle, test-data, uuid, uuidv4, weighted-sampling
- Language: Go
- Homepage:
- Size: 61.5 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# randutil
CSPRNG-first random utilities for Go. One small package that does the
common random things: bias-free integers, bytes, strings/tokens, emails,
shuffle/sample for slices, and realistic date/time helpers.
## Install
```bash
go get github.com/aatuh/randutil/v2
```
## Quick start
```go
package main
import (
"fmt"
"github.com/aatuh/randutil/v2/numeric"
"github.com/aatuh/randutil/v2/collection"
"github.com/aatuh/randutil/v2/randstring"
"github.com/aatuh/randutil/v2/email"
"github.com/aatuh/randutil/v2/randtime"
"github.com/aatuh/randutil/v2/uuid"
)
func main() {
// Numbers
n := numeric.MustIntRange(10, 20) // inclusive
f := numeric.MustFloat64() // [0,1)
b := numeric.MustBytes(16) // 16 random bytes
ok := numeric.MustBool()
// Strings / tokens
s := randstring.MustString(12) // lower-case alnum
hex := randstring.MustHex(32) // 32 hex chars (16 bytes)
b64 := randstring.MustBase64(24) // encodes 24 random bytes
tok := randstring.MustTokenURLSafe(24) // URL-safe base64
// Email addresses
mail := email.MustEmailSimple(16) // exact-length local@domain.com
mail2 := email.MustEmail(email.EmailOptions{TLD: "org"}) // options
// Collections
arr := []int{1,2,3,4,5}
collection.MustShuffle(arr) // in-place Fisher–Yates
top2 := collection.MustSample(arr, 2) // k without replacement
pick := collection.MustSlicePickOne(arr)
pickedMany := collection.MustPickByProbability([]string{"a","b","c"}, 0.5)
// Time
t := randtime.MustDatetime()
p := randtime.MustTimeInNearPast()
fu := randtime.MustTimeInNearFuture()
// UUIDs
u4 := uuid.MustV4()
u7 := uuid.MustV7()
fmt.Println(n, f, len(b), ok, s, hex, b64, tok, mail, mail2, arr, top2, pick, pickedMany, t, p, fu, u4, u7)
}
```
Note: Every `MustX(...)` has a non-panicking `X(...)` variant that returns
`(T, error)` for use in servers/CLIs where you want to handle errors.
## API overview
### Numbers
Uniform integers without modulo bias (rejection sampling under the hood),
`[0,1)` float64, and byte helpers. Range functions are inclusive.
* `Uint64()`
* `Uint64n(n uint64)` → \[0,n)
* `Intn(n int)`, `Int64n(n int64)` → \[0,n)
* `IntRange(min, max)`, `Int32Range`, `Int64Range` (inclusive)
* `AnyInt*`, `Positive*`, `Negative*`
* `Float64()`
* `Bytes(n)`, `Fill(b)`
### Booleans
* `Bool()` / `MustBool()`
### Strings & tokens
Lower-case alnum by default; hex/base64 helpers.
* `String(n)` and `StringWithCharset(n, charset)`
* `Hex(len)` where `len` must be even (2 chars per byte)
* `Base64(byteLen)`, `TokenHex(byteLen)`, `TokenBase64(byteLen)`,
`TokenURLSafe(byteLen)`
### Email addresses
Random email generation with customizable local parts, domains, and TLDs.
* `Email(opts)` - Full control with EmailOptions
* `EmailSimple(totalLength)` - Legacy exact-length emails
* `EmailWithCustomLocal(localPart)`
* `EmailWithCustomDomain(domainPart)`
* `EmailWithCustomTLD(tld)`
* `EmailWithRandomTLD()`
* `EmailWithoutTLD()`
### Collections (slices)
Unbiased Fisher–Yates shuffle, sampling without replacement, and simple picks.
* `Shuffle[T]([]T)`
* `Sample[T]([]T, k)` – returns a new slice, no duplicates
* `Perm(n)` – random permutation of 0..n-1
* `SlicePickOne[T]([]T)`
* `PickByProbability[T]([]T, p float64)` – picks each item with prob `p`
(`SlicePickMany` with 0..100 threshold remains for legacy use)
### Time
Calendar-correct random datetimes and near-past/future helpers.
* `Datetime()` → between years 1..9999 (UTC), month/day validity handled
* `TimeInNearPast()` / `TimeInNearFuture()` → a few minutes around now