StrictGuid 1.0.0

StrictGuid (UUID v8)

StrictGuid is a high-performance .NET library for working with typed identifiers based on the RFC 9562 standard (UUID v8). It allows you to embed the entity type directly into the GUID, ensuring strict typing at the domain model level without sacrificing performance.

Key Features

• 🚀 Extreme Speed: 55x faster than standard Guid.NewGuid() in Fast mode.
• 💎 Zero-Allocation: Zero heap allocations (0 bytes).
• 🛡️ Type-Safe: Binds IDs to your enum : byte (supports up to 256 types).
• 🔒 Entropy Choice: Fast (Random), Secure (Crypto), and Sequential (DB-friendly).
• 📏 UUID v8 Compliance: Fully compliant with RFC 9562.
• 🛡️ Reliability: Strict protection against regular UUID v4 and "garbage" GUIDs.

Solution Structure

• src/StrictGuid.Library: The core library (Extension methods, generator).
• tests/StrictGuid.Tests: Unit tests (xUnit).
• benchmarks/StrictGuid.Benchmarks: Performance tests (BenchmarkDotNet).
• samples/StrictGuid.Demo: Usage example.

Benchmark Results

Performance comparison on .NET 10.0.202 (Apple M1):

The Sequential mode provides an excellent balance: it is 9x faster than a standard GUID and guarantees correct sorting (prevents index fragmentation) in the DB. The Fast mode outperforms the regular GUID generator by 55 times.

Installation

You can install the package from NuGet via the .NET CLI:

dotnet add package StrictGuid

Or via the Package Manager Console in Visual Studio:

Install-Package StrictGuid

Usage

1. Defining Types

Your enums must be based on the byte type. You can define both domain entities and service types (e.g., logging, webhooks):

public enum EntityType : byte
{
    // Service types
    Log = 0,
    WebHook = 1,
    Request = 2,

    // Domain entities
    User = 3,
    Order = 4,
    Invoice = 5,
    // ... supports up to 256 types
}

2. Generating IDs

using StrictGuid.Library;

// Sequential ID (UUID v7 style) — recommended for DBs
Guid orderId = EntityType.Order.NewStrictGuid(StrictGuidEntropy.Sequential);

// Ultra-fast random ID (for logs or transactions)
Guid logId = EntityType.Log.NewStrictGuid(StrictGuidEntropy.Fast);

// Cryptographically secure ID (tokens)
Guid secretId = EntityType.User.NewStrictGuid(StrictGuidEntropy.Secure);

3. Extraction and Validation

// Extracting type
EntityType type = id.GetEntityType<EntityType>();

// Fast validation (throws StrictGuidException on mismatch)
id.ValidateEntityType(EntityType.Order);

// Safe logical check
if (id.IsEntityType(EntityType.User))
{
    // ...
}

Security and Entropy Choice

Type Isolation and Protection against UUID v4

The library reliably isolates entity types. The validation or type extraction method is guaranteed to detect mismatches.

If a standard UUID v4 is passed to your system (e.g., generated by a normal Guid.NewGuid()), the library will not confuse it with an entity (even an entity with code 0, like Log). The algorithm strictly checks the version bits (UUID v8 requires the value 0x80 in the upper bits of the 7th byte). If a v4 or garbage GUID is passed:

• IsEntityType will safely return false.
• GetEntityType or ValidateEntityType will throw a StrictGuidException.

System Requirements

• .NET 8.0+, .NET 6.0, or .NET Standard 2.0
• Support for System.Runtime.CompilerServices.Unsafe (included automatically in newer .NET, added as a NuGet package for .NET Standard 2.0)

Optimizations

• AggressiveInlining & AggressiveOptimization to eliminate call overhead.
• Unsafe.As for Zero-allocation type conversions.
• Span<byte> & stackalloc for stack-based memory operations.