DoReMi ID Generator

A high-performance Go library for generating musical note-based unique identifiers. DoReMi ID combines musical notes (do, re, mi, fa, so, la, ti) with alphanumeric characters to create IDs that are not only functional but also memorable, privacy-friendly, and even playable as music!

Features

• 🎵 Musical & Memorable: Uses musical notes (do-re-mi) that are easy to remember and pronounce
• 🎼 Playable as Music: IDs can be played as actual melodies on any instrument
• 🔐 Privacy-Friendly: Random generation prevents sequential pattern guessing
• 🎲 True Randomness: Non-predictable IDs enhance security and privacy
• ⚡ High Performance: Optimized with byte arrays and O(1) lookups
• 🔒 Guaranteed Uniqueness: Batch generation without duplicates
• 🎯 Configurable: Customizable ID length and separator
• 🔄 Bidirectional: Convert between IDs and positions
• 📊 Batch Operations: Generate sequential or unique random IDs
• 🧪 Well Tested: Comprehensive test coverage

Installation

go get github.com/doremi-id/doremid

Quick Start

package main

import (
    "fmt"
    "github.com/doremi-id/doremid"
)

func main() {
    // Create generator with default configuration
    generator := doremid.NewWithDefaults()

    // Generate a single random ID
    id := generator.NewID()
    fmt.Println("Random ID:", id) // e.g., "dofamiso-a1b2c"
}

Why DoReMi IDs?

🎼 Playable as Music & Twelve-Tone Equal Temperament

Each ID contains a complete musical structure based on established music theory:

id := generator.NewID() // "dofamiso-3a7b"

// Musical interpretation:
// First part: do-fa-mi-so (melody in just intonation)
// Second part: 3-a-7-b (pitch sequence in twelve-tone equal temperament)
// Complete musical meaning: melody + harmonic/rhythmic pattern

// Twelve-tone equal temperament character mapping:
// 0,1,2,3,4,5,6,7,8,9,a,b → C,C#,D,D#,E,F,F#,G,G#,A,A#,B
// Example: 3a7b → D#(3) + A#(a) + G(7) + B(b)

// Play this on piano, sing it, or use it as a ringtone!

🧠 Easy to Remember

Musical notes are naturally memorable and follow familiar patterns:

// These IDs are easier to remember than random strings:
"dofamiso-a1b2c"  // vs "x7k9m2qp-h4w8n"
"redolati-5b9a1"  // vs "q2r8v5mt-3k7j2"

🔐 Privacy & Security

Random generation prevents pattern-based attacks:

// Traditional sequential IDs reveal information:
// user_1, user_2, user_3... (predictable, reveals user count)

// DoReMi random IDs provide privacy:
randomIDs := generator.BatchGenerateRandomIDs(3)
// ["misofala-9b3c1", "refatido-2a8f4", "solaredó-7k1m5"]
// No way to guess the next ID or total count

🎯 Pronunciation Friendly

Both parts of the ID are designed for clear pronunciation:

// Musical part: do-re-mi-fa-so (universal musical language)
// Numeric part: 1-a-3-b-5 (clear digits and letters)

// Easy to communicate over phone:
"dofamiso-1a3b5"
// "do-fa-mi-so, one-a-three-b-five"
// Every character has a clear, unambiguous pronunciation

📝 Recording & Transmission Friendly

The design optimizes for both musical expression and practical use:

// Advantages of 0-9,a,b system:
// ✅ Clear pronunciation: "zero", "one", "a", "bee"
// ✅ Easy handwriting: no confusing similar shapes
// ✅ Digital-friendly: standard keyboard characters
// ✅ Musical meaning: represents twelve-tone equal temperament
// ✅ Compact: maximum information in minimum space

Performance

DoReMi ID is optimized for high-performance scenarios:

• Generation: ~100-150 nanoseconds per ID
• Batch Generation: 100,000 IDs in ~10-15ms
• Memory Efficient: Uses byte arrays and pre-allocated slices
• No Collision Checking: Uniqueness guaranteed by algorithm design

Performance Optimizations

• ✅ Byte arrays instead of string slices
• ✅ O(1) lookup maps instead of linear search
• ✅ Pre-allocated slice capacity
• ✅ Direct byte operations
• ✅ Independent random number generators
• ✅ Fisher-Yates sampling for uniqueness

Algorithm Details

ID Structure

[Just Intonation] + [Separator] + [Equal Temperament]
    domisola      +      -       +      a1b2c
  (Musical Notes)                   (Twelve-Tone Equal Temperament)

Design Philosophy:

• First Part (Just Intonation): Uses traditional musical note names (do-re-mi) for natural melody and easy memorization
• Second Part (Equal Temperament): Uses 12-character system (0-9,a,b) representing twelve-tone equal temperament

Character Sets

• Just Intonation (Musical Notes): do, re, mi, fa, so, la, ti (7 notes)
• Equal Temperament (Twelve-Tone): 0-9, a, b (12 characters representing twelve-tone equal temperament)

Maximum Combinations Formula

MaxCombinations = 7^(JustIntonationDigits) × 12^(EqualTemperamentDigits)
                 (7 musical notes)        (twelve-tone equal temperament)

Musical Theory Foundation:

• 7: Traditional Western musical notes (do, re, mi, fa, so, la, ti) - heptatonic scale
• 12: Equal temperament chromatic scale (C, C#, D, D#, E, F, F#, G, G#, A, A#, B) - dodecaphonic system

Uniqueness Algorithm

For BatchGenerateRandomIDs, we use position sampling:

1. Calculate all possible positions (0 to MaxCombinations-1)
2. Randomly sample the required number of positions
3. Convert sampled positions to IDs
4. Result: 100% unique IDs without collision checking

Error Handling

The library handles edge cases gracefully:

• Invalid count: Returns empty slice for count ≤ 0
• Exceeding maximum: Returns empty slice when count > MaxCombinations
• Invalid IDs: Returns -1 for malformed IDs in IDToPosition
• Invalid positions: Returns empty string for negative positions

Testing

Run the test suite:

go test -v

The library includes comprehensive tests covering:

• ID format validation
• Uniqueness verification
• Edge cases and error conditions
• Performance benchmarks
• Round-trip conversion testing

Examples

See the example/ directory for complete usage examples:

go run example/main.go

License

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

Configuration

Basic Configuration

generator := doremid.New(doremid.Config{
    JustIntonationDigits:   4,  // Number of musical note pairs (melody length)
    EqualTemperamentDigits: 5,  // Number of twelve-tone characters (harmony/rhythm pattern)
    Separator:              "-", // Separator between just intonation and equal temperament
})

Default Configuration

// Uses: 4 musical note pairs, 5 alphanumeric chars, "-" separator
generator := doremid.NewWithDefaults()

Configuration Examples

Configuration	Example ID	Max Combinations
{1, 2, "-"}	do-a1	1,008
{2, 3, "_"}	domi_1a2	84,672
{4, 5, "-"}	domisola-1a2b3	597,445,632

API Reference

Core Methods

NewID() string

Generates a single random ID.

id := generator.NewID()
// Example: "domifaso-a1b2c"

BatchGenerateRandomIDs(count int64) []string

Generates unique random IDs without duplicates.

ids := generator.BatchGenerateRandomIDs(10)
// Returns 10 guaranteed unique random IDs
// Returns empty slice if count > MaxCombinations()

BatchGenerateIDs(count, startPosition int64) []string

Generates sequential IDs starting from a specific position.

ids := generator.BatchGenerateIDs(5, 100)
// Returns 5 sequential IDs starting from position 100

IDToPosition(id string) int64

Converts an ID back to its position in the sequence.

position := generator.IDToPosition("dodododo-00000")
// Returns: 0
// Returns: -1 for invalid IDs

PositionToID(position int64) string

Converts a position to its corresponding ID.

id := generator.PositionToID(0)
// Returns: "dodododo-00000"
// Returns: "" for negative positions

MaxCombinations() int64

Returns the maximum number of unique IDs possible with current configuration.

max := generator.MaxCombinations()
// For default config: 597,445,632

Use Cases

Sequential IDs

Perfect for database primary keys, ordered records, or pagination:

// Generate user IDs starting from position 1000
userIDs := generator.BatchGenerateIDs(100, 1000)
for i, id := range userIDs {
    fmt.Printf("User %d: %s\n", 1000+int64(i), id)
}

Privacy-Protected Random IDs

Ideal for session tokens, user identifiers, or any case requiring privacy:

// Generate unique session tokens that can't be guessed
sessionTokens := generator.BatchGenerateRandomIDs(50)
// Each token is musical and memorable: "dotifala-8b2a9"

Memorable URL Shorteners

Create memorable short URLs that users can easily share:

// Convert position to musical short ID
shortURL := generator.PositionToID(12345) // "remifado-3c"
// Users can easily remember and share: "bit.ly/remifado-3c"

Voice-Friendly Customer Support

Perfect for customer service scenarios where IDs need to be communicated verbally:

// Easy to communicate over phone
supportTicketID := generator.NewID() // "domisola-4a8b"
// Support: "Your ticket ID is: do-mi-so-la, 4-a-8-b"
// Customer can easily write it down and remember it

---

DoReMi ID - The only ID generator that's memorable, playable, and privacy-friendly! 🎵

"Why remember random strings when you can sing your IDs?"