StableId 1.0.0

StableId

StableId is a high-performance deterministic GUID generator for .NET. Generate consistent, reproducible GUIDs from any input with exceptional performance characteristics.

Features

• ✨ Deterministic: Same input always produces the same GUID
• 🚀 High Performance: Optimized for speed with minimal allocations
• 🔒 Thread Safe: Safe for concurrent use
• 📦 Lightweight: Minimal dependencies
• 🎲 UUID v5 Compatible: Uses SHA-256 hashing for deterministic generation
• 🎯 Modern .NET: Built for .NET 9.0+

Quick Start

Installation

dotnet add package StableId

Basic Usage

using StableId;

// Generate GUID from string values
Guid id1 = DeterministicGuidGenerator.GenerateId("user@example.com");
Guid id2 = DeterministicGuidGenerator.GenerateId("user@example.com");
// id1 == id2 (always true)

// Generate from multiple values
Guid id3 = DeterministicGuidGenerator.GenerateId("Hello", "World", 123);
Guid id4 = DeterministicGuidGenerator.GenerateId("Hello", "World", 123);
// id3 == id4 (always true)

// Different input produces different GUID
Guid id5 = DeterministicGuidGenerator.GenerateId("Hello", "Universe");
// id5 != id3 (different input)

Smart Object Handling

The generator automatically extracts meaningful identifiers from objects using reflection:

using StableId;

// Objects with ID properties
var user = new { Id = Guid.NewGuid(), Name = "John Doe" };
var product = new { Key = 12345, ProductCode = "ABC123" };
var order = new { Identifier = 789L, Amount = 150.00m };

// Generate composite ID - uses ID properties, ignores other properties
Guid compositeId = DeterministicGuidGenerator.GenerateId(user, product, order);

// Same user with different name produces same ID (uses Id property)
var userDifferentName = new { Id = user.Id, Name = "Jane Smith" };
Guid sameId = DeterministicGuidGenerator.GenerateId(userDifferentName, product, order);
// compositeId == sameId ✅ (uses Id property, ignores Name)

ID Property Priority Order:

1. Id
2. Guid
3. Key
4. Identifier
5. ID

Advanced Usage

using StableId;

// High-frequency generation (optimized for performance)
for (int i = 0; i < 1_000_000; i++)
{
    Guid id = DeterministicGuidGenerator.GenerateId("cache-key", i, DateTime.UtcNow.Ticks);
}

// Thread-safe concurrent usage
var tasks = Enumerable.Range(0, 1000)
    .Select(i => Task.Run(() => DeterministicGuidGenerator.GenerateId($"input-{i}")))
    .ToArray();

Guid[] results = await Task.WhenAll(tasks);

// Handle large inputs (automatic buffer management)
string largeString = new string('x', 10_000);
Guid largeId = DeterministicGuidGenerator.GenerateId(largeString);

// Complex objects with nested properties
var complexObject = new 
{
    Id = 12345,
    User = new { Name = "John", Email = "john@example.com" },
    Items = new[] { "item1", "item2", "item3" }
};
Guid complexId = DeterministicGuidGenerator.GenerateId(complexObject);

Performance Characteristics

• Ultra-High Throughput: 4.7M+ operations per second for simple inputs
• Sub-microsecond Latency: ~211ns average per operation
• Excellent Scalability: Linear scaling with thread count (65M+ ops/sec on 16 threads)
• Memory Efficient: Zero allocations for typical workloads
• Bounded Allocations: Uses Span<T>, ArrayPool<T>, and stack allocation
• Smart Buffering: Dynamic buffer sizing with overflow protection

Technical Details

UUID v5 Compliance

Generated GUIDs follow RFC 4122 UUID version 5 specification:

// Version bits (4 bits at position 48-51) set to 5
guidBytes[6] = (byte)((guidBytes[6] & 0x0F) | 0x50);

// Variant bits (2 bits at position 64-65) for RFC 4122 compliance
guidBytes[8] = (byte)((guidBytes[8] & 0x3F) | 0x80);

Security Features

• SHA-256 Hashing: Cryptographically secure hash function
• Collision Resistance: Null-byte separators prevent input collision attacks
• Type Safety: Input validation and bounds checking
• Recursion Protection: Maximum 10 levels of object nesting

Memory Management

• Stack Allocation: Uses stackalloc for buffers ≤ 1KB
• Array Pooling: Rents larger buffers from ArrayPool<byte>.Shared
• Span Operations: Zero-copy operations with Span<T> and ReadOnlySpan<T>
• Cached Reflection: Property lookup results cached with bounded cache size (1000 entries)

Error Handling

The generator includes comprehensive error handling:

// Maximum parameter validation
DeterministicGuidGenerator.GenerateId(params); // Max 100 parameters

// Null parameter protection
DeterministicGuidGenerator.GenerateId("valid", null); // Throws ArgumentException

// Buffer overflow protection
string veryLargeString = new string('x', 100_000);
Guid id = DeterministicGuidGenerator.GenerateId(veryLargeString); // Handles gracefully

// Recursion protection
var deeplyNested = /* object with 20+ levels of nesting */;
Guid id = DeterministicGuidGenerator.GenerateId(deeplyNested); // Max 10 levels, then truncates

Use Cases

• 🗃️ Database Sharding: Consistent partition keys across services
• 💾 Caching: Deterministic cache keys for distributed caches
• 🔄 Distributed Systems: Reproducible identifiers across microservices
• 📊 Data Processing: Deduplication and entity matching
• 🏗️ Event Sourcing: Stable aggregate identifiers
• 🧪 Testing: Predictable test data generation
• 🔍 ETL Pipelines: Consistent record matching across data sources

Thread Safety

DeterministicGuidGenerator is fully thread-safe:

• Static methods with no mutable state
• Thread-safe caching with ConcurrentDictionary<T,K>
• Atomic cache size tracking with Interlocked operations
• No shared mutable state between operations

Requirements

• .NET 9.0+ (uses latest performance features)
• C# 12+ (modern language features)

Project Structure

StableId/
├── src/
│   └── StableId/
│       ├── DeterministicGuidGenerator.cs    # Main implementation
│       └── StableId.csproj                  # Project file
├── examples/
│   └── StableId.Examples/                   # Usage examples
├── tests/
│   └── StableId.Tests/                      # Unit tests
├── benchmarks/
│   └── StableId.Benchmarks/                 # Performance benchmarks
└── README.md

Building and Testing

# Clone the repository
git clone https://github.com/henrikroschmann/StableId.git
cd StableId

# Build the solution
dotnet build

# Run tests
dotnet test

# Run examples
dotnet run --project examples/StableId.Examples

# Run benchmarks
dotnet run --project benchmarks/StableId.Benchmarks -c Release
# Or use the convenience scripts:
# Windows: run-benchmarks.bat [core|comparison|concurrency|memory]
# PowerShell: ./run-benchmarks.ps1 [core|comparison|concurrency|memory]

Performance Benchmarks

Core Performance Results

Comparison with Alternatives

Concurrency Performance

Memory Efficiency

• Zero allocations for simple scenarios
• Minimal allocations for complex inputs
• Stack allocation preferred for buffers ≤ 1KB
• Array pooling for larger temporary buffers
• Bounded memory usage even with very large inputs

Test Environment: .NET 9.0, Arm64 (Snapdragon X), Release build

Examples

See the examples/StableId.Examples project for comprehensive usage examples including:

• Basic string-based ID generation
• Smart object handling with ID property extraction
• Performance demonstrations
• Thread safety examples
• Complex object scenarios

Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Add tests for new functionality
4. Ensure all tests pass (dotnet test)
5. Follow existing code style and patterns
6. Submit a pull request

License

MIT License - see LICENSE file for details.

Acknowledgments

• Inspired by RFC 4122 UUID specification (Version 5 - Name-based UUIDs)
• Built with .NET performance best practices
• Uses modern memory management techniques (Span<T>, ArrayPool<T>, stackalloc)

⭐ Star this repo if StableId helps you build more efficient applications!