Dis.Uuid

A high-performance .NET library for generating UUID version 7 (UUIDv7) identifiers with time-ordering capabilities.

🎯 What is UUID v7?

UUID version 7 is a time-ordered UUID variant that combines:

• 48-bit timestamp (millisecond precision)
• 12-bit random data for sub-millisecond ordering
• 62-bit random data for uniqueness

This design ensures:

• ✅ Chronological ordering - newer UUIDs are lexicographically greater
• ✅ Database performance - excellent for primary keys and indexes
• ✅ Global uniqueness - collision-resistant across distributed systems
• ✅ Thread safety - safe for concurrent use

🚀 Installation

dotnet add package Dis.Uuid

Or via Package Manager Console:

Install-Package Dis.Uuid

📖 Usage

using Dis.Uuid;

// Generate a new UUID v7
Guid id = UuidV7.New();
Console.WriteLine(id); // e.g., 018f-4230-1234-7000-abcdef123456

// Use in your models
public class Order
{
    public Guid Id { get; set; } = UuidV7.New();
    public DateTime CreatedAt { get; set; } = DateTime.UtcNow;
    // ... other properties
}

🔧 Features

• High Performance: Uses Span<byte> and ThreadLocal<RandomNumberGenerator> for optimal performance
• Thread Safe: Concurrent generation across multiple threads
• Memory Efficient: Zero heap allocations during UUID generation
• Standards Compliant: Follows RFC 4122 UUID v7 specification
• .NET 8+ Optimized: Takes advantage of latest .NET performance improvements

📊 Performance

UUID v7 generation is extremely fast and efficient:

// Benchmark example
var sw = Stopwatch.StartNew();
for (int i = 0; i < 1_000_000; i++)
{
    var uuid = UuidV7.New();
}
sw.Stop();
Console.WriteLine($"Generated 1M UUIDs in {sw.ElapsedMilliseconds}ms");

🔄 Time Ordering

One of the key benefits of UUID v7 is natural time ordering:

var id1 = UuidV7.New();
await Task.Delay(1); // Small delay
var id2 = UuidV7.New();

// id2 will always be lexicographically greater than id1
Assert.True(string.Compare(id1.ToString(), id2.ToString()) < 0);

🎯 Use Cases

Perfect for:

• Database Primary Keys - Better performance than traditional UUIDs
• Distributed Systems - Global uniqueness with time ordering
• Event Sourcing - Natural chronological ordering of events
• Logging Systems - Time-ordered log entries
• Microservices - Consistent ID generation across services

🔒 Thread Safety

The library is fully thread-safe and can be used concurrently:

// Safe to use across multiple threads
var tasks = Enumerable.Range(0, 10)
    .Select(_ => Task.Run(() => 
    {
        var ids = new List<Guid>();
        for (int i = 0; i < 1000; i++)
        {
            ids.Add(UuidV7.New());
        }
        return ids;
    }));

var results = await Task.WhenAll(tasks);
// All generated UUIDs will be unique

🧪 Testing

The library includes comprehensive tests covering:

• Uniqueness validation
• Time ordering verification
• Thread safety testing
• Performance benchmarks

Run tests:

dotnet test

📋 Requirements

• .NET 8.0 or higher
• Compatible with all .NET 8+ workloads (Console, Web, Desktop, etc.)

🤝 Contributing

Contributions are welcome! Please feel free to submit issues and pull requests.

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if needed
5. Submit a pull request

📄 License

This project is licensed under the BSD 3-Clause License - see the LICENSE.txt file for details.

🔗 References

• RFC 4122 - UUID Specification
• UUID Version 7 Draft
• .NET Guid Documentation

Made with ❤️ for the .NET community