Documentation
¶
Overview ¶
Package random provides secure random string generation with optional timestamp encoding.
The package offers two main features:
- Random string generation using cryptographically secure random number generator
- Timestamped random strings that embed UNIX timestamps for tracking or expiration
Basic Usage ¶
Generate a simple random string:
gen := random.NewGenerator(false) // case-insensitive (base62: 0-9, a-z, A-Z) str := gen.RandomString(16).Unwrap() // e.g., "a3B9kL2mN8pQ4rS"
Generate a random string with current timestamp embedded:
gen := random.NewGenerator(false) str := gen.StringWithNow(20).Unwrap() // e.g., "x7K9mN2pQ4rS5tUvW8yZa3Bc" // The last 6 characters encode the current timestamp
Parse timestamp from a string:
gen := random.NewGenerator(false) timestamp := gen.ParseTimestamp(str).Unwrap() // Returns absolute UNIX timestamp
Character Sets ¶
The Generator supports two character sets based on caseSensitive parameter:
- caseSensitive=false (default): Uses base62 encoding (0-9, a-z, A-Z) - 62 characters Suitable for most use cases, provides longer timestamp range (until 3825)
- caseSensitive=true: Uses base36 encoding (0-9, a-z) - 36 characters Suitable for case-insensitive systems, shorter timestamp range (until 2094)
Timestamp Encoding ¶
When generating strings with timestamps, the last 6 characters encode the timestamp offset from the epoch (2026-01-01 00:00:00 UTC). The timestamp is encoded in the configured base:
- Base62: Can encode timestamps from 2026-01-01 to 3825-12-06
- Base36: Can encode timestamps from 2026-01-01 to 2094-12-24
Security ¶
The package uses crypto/rand for cryptographically secure random number generation, ensuring that generated strings are suitable for security-sensitive applications such as session tokens, API keys, or password reset tokens.
Examples ¶
See the examples package for more detailed usage examples.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type Generator ¶
type Generator struct {
// contains filtered or unexported fields
}
Generator provides random string generation with optional timestamp encoding
func NewGenerator ¶
NewGenerator creates a new Generator instance for generating random strings with optional timestamp encoding caseSensitive: determines the character set used for encoding:
- true: uses lowercase-only characters (0-9, a-z), suitable for case-insensitive systems
- false: uses mixed case characters (0-9, a-z, A-Z), provides more encoding capacity
Timestamp encoding range (when using StringWithTimestamp or StringWithNow):
- caseSensitive=true: can encode timestamps from 2026-01-01 to 2094-12-24 (approximately 69 years)
- caseSensitive=false: can encode timestamps from 2026-01-01 to 3825-12-06 (approximately 1800 years)
func (*Generator) ParseTimestamp ¶
ParseTimestamp parses absolute UNIX timestamp (in seconds) from the suffix of s The timestamp offset is expected to be encoded in the last 6 characters of the string Returns the absolute timestamp by adding the offset to timestampEpoch
func (*Generator) RandomString ¶
RandomString generates a random string of the specified length
func (*Generator) StringWithNow ¶
StringWithNow returns a random string with current UNIX timestamp (in seconds) appended as suffix length: total length of the returned string, must be greater than timestampSecondLength (6) The current time will be converted to offset from timestampEpoch (2026-01-01)
func (*Generator) StringWithTimestamp ¶
StringWithTimestamp returns a random string with UNIX timestamp (in seconds) appended as suffix length: total length of the returned string, must be greater than timestampSecondLength (6) timestamp: absolute UNIX timestamp in seconds, will be converted to offset from timestampEpoch (2026-01-01) Supported timestamp range depends on the caseSensitive setting used when creating the Generator instance:
- caseSensitive=true: timestamps from 2026-01-01 to 2094-12-24 (approximately 69 years)
- caseSensitive=false: timestamps from 2026-01-01 to 3825-12-06 (approximately 1800 years)
Source Files