🧠 AID - Advanced ID Generator

AID (Advanced ID Generator) is a powerful, flexible, and easy-to-use Go library for generating various types of identifiers including random strings, UUIDs, ULIDs, and time-based IDs with customizable prefixes, suffixes, and encoding formats.

🚀 Features

• 🔢 Generate random strings with various character sets
• 🕐 Time-based ID generation with multiple encoding options
• 🔤 Multiple character set options (alphanumeric, symbols, case-specific)
• 🏷️ Customizable prefixes and suffixes
• 🔗 UUID and ULID generation support
• ⚙️ Highly configurable generator options
• 📦 Zero-dependency core (external dependencies only for UUID/ULID)

📦 Installation

To install AID, use go get:

go get github.com/evilmagics/go-aid

Then import it in your Go code:

import "github.com/evilmagics/go-aid"

🎯 Quick Start

Simple Random String Generation

// Generate a random alphanumeric string of length 10
id := aid.RandStr(10)
fmt.Println(id) // Output: something like "aB3kL9mN2p"

// Generate a random string with only alphabetic characters
alphaId := aid.RandAlphaStr(8)
fmt.Println(alphaId) // Output: something like "KpMnQrSt"

// Generate a random string with only numeric characters
numId := aid.RandNumStr(6)
fmt.Println(numId) // Output: something like "482910"

UUID & ULID Generation

// Generate UUID v4
uuid := aid.RandUUID()
fmt.Println(uuid) // Output: something like "550e8400-e29b-41d4-a716-446655440000"

// Generate UUID v6
uuid6 := aid.RandUUIDv6()
fmt.Println(uuid6)

// Generate UUID v7
uuid7 := aid.RandUUIDv7()
fmt.Println(uuid7)

// Generate ULID
ulid := aid.RandULID()
fmt.Println(ulid) // Output: something like "01H6W2XYP5Z6S3Q0C4V1J5B8QK"

🛠️ Advanced Usage

Custom Generator Configuration

For advanced use cases, you can create a custom generator with specific options:

// Create a generator with a prefix and custom encoding
gen := aid.NewGenerator(
    aid.WithPrefix("user_"),
    aid.WithEncoder(aid.Base36),
    aid.WithFixedPrefix(),
)

// Generate a time-prefixed ID
id, err := gen.RandTimePrefix(16, aid.CharsetAlphaNum)
if err != nil {
    log.Fatal(err)
}
fmt.Println(id) // Output: something like "user_1a2b3c4d5e6f7g8h"

Available Options

Option	Description
WithPrefix(prefix string)	Adds a fixed prefix to all generated IDs
WithSuffix(suffix string)	Adds a fixed suffix to all generated IDs
WithFixedPrefix()	Makes the prefix length count toward total ID length
WithFixedSuffix()	Makes the suffix length count toward total ID length
WithEncoder(encoder aid.EncoderType)	Sets the encoding method for time-based IDs

Encoder Types

Encoder	Description
Base64	URL-safe Base64 encoding (default)
Base36	Case-insensitive Base36 encoding
Hex	Lowercase hexadecimal encoding
Decimal	Decimal number encoding

🔤 Character Sets

AID provides a variety of predefined character sets for generating IDs:

Constant	Characters	Description
CharsetAlphaLower	abcdefghijklmnopqrstuvwxyz	Lowercase letters
CharsetAlphaUpper	ABCDEFGHIJKLMNOPQRSTUVWXYZ	Uppercase letters
CharsetNumeric	0123456789	Numeric digits
CharsetSymbols	`!@#$%^&*()-_=+[]{}	;:',.<>/?`
CharsetAlpha	abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ	Mixed case letters
CharsetAlphaNum	abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789	Alphanumeric (default)
CharsetAlphaNumSym	Alphanumeric + symbols	All characters

📋 Function Reference

Random String Functions (with error handling)

Function	Description
Rand(length int) (string, error)	Generates alphanumeric string
RandAlpha(length int) (string, error)	Generates alphabetic string
RandNum(length int) (string, error)	Generates numeric string
RandAlphaNum(length int) (string, error)	Generates alphanumeric string
RandAlphaSym(length int) (string, error)	Generates alphabetic + symbol string
RandAlphaNumSym(length int) (string, error)	Generates alphanumeric + symbol string

Convenience Functions (ignoring errors)

Function	Description
RandStr(length int) string	Generates alphanumeric string
RandAlphaStr(length int) string	Generates alphabetic string
RandNumStr(length int) string	Generates numeric string
RandAlphaNumStr(length int) string	Generates alphanumeric string
RandAlphaSymStr(length int) string	Generates alphabetic + symbol string
RandAlphaNumSymStr(length int) string	Generates alphanumeric + symbol string

Case-specific Functions

Function	Description
RandAlphaLower(length int) (string, error)	Generates lowercase alphabetic string
RandAlphaUpper(length int) (string, error)	Generates uppercase alphabetic string
RandAlphaNumLower(length int) (string, error)	Generates lowercase alphanumeric string
RandAlphaNumUpper(length int) (string, error)	Generates uppercase alphanumeric string

Number Functions

Function	Description
RandInt(min, max int) int	Generates random integer in range
RandFloat(min, max float64) float64	Generates random float in range

UUID/ULID Functions

Function	Description
RandUUID() string	Generates UUID v4
RandUUIDv4() string	Generates UUID v4
RandUUIDv6() string	Generates UUID v6
RandUUIDv7() string	Generates UUID v7
RandULID() string	Generates ULID

🧪 Example Use Cases

User IDs with Prefix

// Create generator for user IDs
userGen := aid.NewGenerator(
    aid.WithPrefix("usr_"),
    aid.WithFixedPrefix(),
)

userId := userGen.RandStr(12)
fmt.Println(userId) // Output: something like "usr_a1B2c3D4e5F6"

Session Tokens

// Generate secure session tokens
sessionToken := aid.RandAlphaNumSymStr(32)
fmt.Println(sessionToken) 
// Output: something like "K7$mN9pQ2#vX8zA1bC3dE5fG!hJ4kL6"

Product Codes

// Generate product codes with specific format
productGen := aid.NewGenerator(
    aid.WithPrefix("PRD-"),
    aid.WithSuffix("-XYZ"),
    aid.WithFixedPrefix(),
    aid.WithFixedSuffix(),
)

productCode := productGen.RandAlphaNumStr(8)
fmt.Println(productCode) // Output: something like "PRD-aB3kL9mN-XYZ"

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

📧 Support

If you have any questions or need help, please open an issue on GitHub.