https://github.com/everlastingbeta/strand
Golang library for creating cryptographic and seeded pseudorandom bytes and strings
https://github.com/everlastingbeta/strand
bytes golang library pseudo-random-generator strings
Last synced: 6 months ago
JSON representation
Golang library for creating cryptographic and seeded pseudorandom bytes and strings
- Host: GitHub
- URL: https://github.com/everlastingbeta/strand
- Owner: everlastingbeta
- License: mit
- Created: 2019-10-26T14:28:45.000Z (over 6 years ago)
- Default Branch: main
- Last Pushed: 2025-12-03T14:01:17.000Z (7 months ago)
- Last Synced: 2025-12-04T17:39:13.327Z (7 months ago)
- Topics: bytes, golang, library, pseudo-random-generator, strings
- Language: Go
- Size: 80.1 KB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# strand
A lightweight, powerful Golang library for generating random strings with both cryptographically secure and seeded options.
[](https://pkg.go.dev/github.com/everlastingbeta/strand)
[](https://goreportcard.com/report/everlastingbeta/strand)
## Features
- Generate cryptographically secure random strings using `crypto/rand`
- Create deterministic random strings with custom seeds using `math/rand/v2`
- Context-aware functions for cancellation support
- Predefined character sets for common use cases
- Simple, clean API with both error-returning and panic-on-error versions
## Installation
```sh
go get -u github.com/everlastingbeta/strand
```
## Quick Start
```go
package main
import (
"fmt"
"github.com/everlastingbeta/strand"
)
func main() {
// Generate a secure random string with uppercase letters
token, err := strand.String(16, strand.UppercaseAlphabet)
if err != nil {
panic(err)
}
fmt.Println("Secure token:", token)
// Generate a predictable string with a custom charset and seed
password := strand.SeededString(12, strand.ALL, 42)
fmt.Println("Deterministic password:", password)
}
```
## Usage Examples
### Cryptographically Secure Random Generation
Use these functions for security-sensitive applications like tokens, passwords, and API keys.
```go
// Generate a secure random byte slice with alphanumeric characters
bytes, err := strand.Bytes(12, strand.AlphaNumeric)
if err != nil {
// Handle error
}
fmt.Printf("Random bytes: %v\n", bytes)
// Generate a secure random string with custom character set
apiKey, err := strand.String(32, strand.AlphaNumeric + "-_")
if err != nil {
// Handle error
}
fmt.Println("API key:", apiKey)
// Non-error-returning versions (will panic on error)
token := strand.MustString(16, strand.ALL)
fmt.Println("Secure token:", token)
```
### Deterministic Random Generation
Use these functions when you need reproducible results with a specific seed.
```go
// Generate a random byte slice with a timestamp-based seed
bytes := strand.SeededBytes(8, strand.Numbers)
fmt.Printf("Seeded bytes: %v\n", bytes)
// Generate a random string with a custom seed and charset
id := strand.SeededString(10, "ACDEFGHJKLMNPQRSTUVWXYZ23456789", 12345)
fmt.Println("Deterministic ID:", id)
```
### Context-Aware Functions
For operations that might need to be canceled or have timeouts.
```go
import (
"context"
"time"
)
// Create a context with timeout
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()
// Generate random strings with context support
result, err := strand.StringWithContext(ctx, 20, strand.ALL)
if err != nil {
// Handle context cancellation or other errors
}
// Also available for seeded versions
seededResult, err := strand.SeededStringWithContext(ctx, 20, strand.AlphaNumeric, 42)
if err != nil {
// Handle errors
}
```
## Available Character Sets
Strand provides several predefined character sets for convenience:
| Constant | Description |
|----------|-------------|
| `UppercaseAlphabet` | Uppercase letters (A-Z) |
| `LowercaseAlphabet` | Lowercase letters (a-z) |
| `Alphabet` | All letters (a-z, A-Z) |
| `Numbers` | Digits (0-9) |
| `AlphaNumeric` | All letters and digits |
| `Symbols` | Common special characters |
| `ALL` | All alphanumeric characters and symbols |
You can also define your own custom character sets as strings.
## Security Considerations
- The `Bytes()` and `String()` functions use `crypto/rand` and are suitable for security-sensitive applications.
- The `SeededBytes()` and `SeededString()` functions use `math/rand/v2` and are NOT cryptographically secure. Use them only when predictable output is required.
## License
[MIT](https://github.com/everlastingbeta/strand/blob/main/LICENSE)