Dixor.Identity 0.2.0

Dixor

DIXOR

DIXOR stands for Dishant's Infrastructure eXtensible Open Runtime.

Dixor is a modern ecosystem of high-performance, production-ready .NET libraries built to simplify application development through well-designed APIs, excellent documentation, and developer-friendly tooling.

Rather than being a single monolithic dependency, Dixor is a curated collection of focused infrastructure libraries. Every package solves one specific engineering challenge exceptionally well while maintaining a unified philosophy across the entire ecosystem:

• Modern API Design: Intuitive, strongly typed, and predictable interfaces built natively for modern C#.
• High Performance: Optimized execution paths built to handle massive enterprise throughput.
• Allocation-Conscious Implementations: Minimal heap allocations and efficient internal layouts to reduce Garbage Collection (GC) pressure.
• Correctness & Standards: Strict compliance with authoritative internet specifications (RFC 9562 for UUIDs, ULID specifications, RFC email syntax rules).
• Rich Developer Experience: Actionable diagnostics, structured results, and built-in Roslyn compile-time analyzers.
• Modular Architecture: Install strictly what your application requires without pulling in unnecessary overhead.

Table of Contents

• Ecosystem Overview

• Installation

• Dixor.Identity

• Introduction & Core Philosophy

• What is RFC 9562 & UUID Version 7?

• UUID Version Comparison

• Features & API Reference: UUIDv7

• Features & API Reference: ULID

• Additional Identity Encodings & Modules

• Built-in Roslyn Analyzers

• Quick Start

• Dixor.Validation

• Introduction & Core Philosophy

• Why Not Regular Expressions?

• Validation Strategy & Layers

• Features & API Reference

• Intelligent Suggestion Engine

• Quick Start

• Documentation Structure

• Supported Frameworks

• Ecosystem Roadmap

• Contributing

• License

Ecosystem Overview

The Dixor ecosystem currently consists of production-grade, independently distributed libraries designed for high-throughput enterprise systems, cloud-native microservices, and modern ASP.NET Core applications.

Installation

Every library in the Dixor ecosystem is published independently on NuGet. You can adopt individual libraries incrementally without modifying existing infrastructure.

.NET CLI

dotnet add package Dixor.Identity
dotnet add package Dixor.Validation

Visual Studio Package Manager Console

Install-Package Dixor.Identity
Install-Package Dixor.Validation

<PackageReference> (MSBuild)

<ItemGroup>
  <PackageReference Include="Dixor.Identity" Version="0.2.0" />
  <PackageReference Include="Dixor.Validation" Version="0.1.0" />
</ItemGroup>

Dixor.Identity

Dixor.Identity - Introduction & Core Philosophy

Dixor.Identity delivers modern, allocation-conscious identifier generation and encoding for .NET. While standard .NET developers frequently rely on Guid.NewGuid(), that API outputs UUID Version 4 identifiers. Because Version 4 UUIDs are completely random, using them as clustered primary keys in relational databases forces index page splits, random disk I/O, cache misses, and massive database fragmentation under heavy write loads.

Dixor.Identity solves this problem by providing a complete, highly optimized implementation of RFC 9562 UUID Version 7, ULIDs (Universally Unique Lexicographically Sortable Identifiers), and lightweight encoding primitives (Base36, Base62, NanoId, etc.).

What is RFC 9562 & UUID Version 7?

RFC 9562 is the authoritative IETF specification that supersedes the legacy RFC 4122 standard. It introduces new identifier formats specifically architected for modern distributed databases and cloud environments.

A UUID Version 7 is a 128-bit structure composed of four distinct internal segments:

  0                   1                   2                   3
  0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                            unix_ts_ms                         |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|          unix_ts_ms           |  ver  |       rand_a          |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|var|                        rand_b                             |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|                            rand_b                             |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

Example generated string:

019853a6-35c4-7e58-bf91-cb7d0b1b11d2

UUID Version Comparison

Features & API Reference: UUIDv7

🚀 Standard UUIDv7 Generation

Generates a standard time-ordered UUIDv7 with ultra-low latency and zero heap allocations.

using Dixor.Identity.UUID7;
Guid identifier = Uuid7.New();

⚡ Monotonic UUID Generation

Guarantees strict sequential ordering across identical millisecond intervals by incrementing sequence state safely.

Guid monotonicId1 = Uuid7.NewMonotonic();
Guid monotonicId2 = Uuid7.NewMonotonic(); // Guaranteed > monotonicId1

📦 High-Efficiency Batch Generation

Streamlines mass allocations for bulk data pipelines.

IEnumerable<Guid> batchIds = Uuid7.NewGuids(count: 500);

🔍 Validation & Parsing

Verify specifications or parse strings safely.

bool isValidV7 = Uuid7.IsValid(sampleId);
Guid parsedId = Uuid7.Parse("019853a6-35c4-7e58-bf91-cb7d0b1b11d2");

⏱ Zero-Overhead Timestamp Extraction

Extract creation time directly from bytes without DB lookups.

DateTimeOffset creationTime = Uuid7.GetTimestamp(identifier);

Features & API Reference: ULID (v0.2.0 Addition)

ULID combines a 48-bit millisecond Unix timestamp with 80 bits of cryptographic randomness, encoded using Crockford Base32 into a compact 26-character string.

🚀 Standard ULID Generation

using Dixor.Identity.ULID;
string ulid = Ulid.Generate();
// Example: 01J5J8Y9Q6A8K5J8X3Z5N9Y2KP

⚡ Monotonic ULID Generation

Guarantees strict chronological order during high-frequency same-millisecond bursts by safely incrementing the randomness component.

string monotonicUlid = Ulid.GenerateMonotonic();

📦 Batch ULID Generation

Lazily yields multiple unique ULIDs for bulk operations.

foreach (var id in Ulid.Generate(500)) { /* ... */ }

🔄 Binary Formatting, Parsing & Timestamp Extraction

Utilizes Fixed-Index Bit Mapping to eliminate offset drift, ensure compatibility with external libraries, and avoid heap allocations via stackalloc.

byte[] binaryBytes = Ulid.Parse("01J5J8Y9Q6A8K5J8X3Z5N9Y2KP");
string formatted = Ulid.Format(binaryBytes);
DateTime timestamp = Ulid.GetTimestamp("01J5J8Y9Q6A8K5J8X3Z5N9Y2KP");
bool isValid = Ulid.IsValid("01J5J8Y9Q6A8K5J8X3Z5N9Y2KP");

Additional Identity Encodings & Modules

Dixor.Identity features specialized sub-modules for compact data serialization and token generation:

• Base36 (Base36): Compact alphanumeric encoding utilities for case-insensitive identifier representations.
• Base62 (Base62): URL-safe Base62 encoding components optimized for dense, short string representations.
• Hexadecimal (Hexadecimal): Direct hex formatting and parsing tools for low-level binary inspection.
• NanoId (NanoId): Compact, URL-friendly, secure string identifier generation.
• Numeric Code (NumericCode): Specialized numeric-only code generation for pin codes and verification tokens.
• Sequence (Sequence): High-throughput, thread-safe sequential ID generation.
• Short Identifier (ShortId): Optimized short identifier generators for readable references.

Built-in Roslyn Analyzers

Dixor.Identity includes intelligent, built-in Roslyn compile-time analyzers that enforce correct API usage directly inside the Visual Studio IDE or .dotnet build pipeline.

Dixor.Identity - Quick Start

using System;
using Dixor.Identity.UUID7;
using Dixor.Identity.ULID;

// 1. Create a modern time-ordered UUIDv7 primary key
Guid primaryKey = Uuid7.New();
Console.WriteLine($"Generated UUIDv7 : {primaryKey}");

// 2. Generate a sortable 26-character ULID
string ulidId = Ulid.Generate();
Console.WriteLine($"Generated ULID   : {ulidId}");

// 3. Extract when this ID was created without metadata storage
DateTimeOffset createdAt = Uuid7.GetTimestamp(primaryKey);
Console.WriteLine($"Created At       : {createdAt:O}");

Dixor.Validation

Dixor.Validation - Introduction & Core Philosophy

Dixor.Validation is an enterprise-grade validation engine built to replace fragile, error-prone checking strategies with structured, highly informative validation pipelines. The initial v0.1.0 release delivers a comprehensive Email Validation Engine architected to overcome the severe limitations of standard Regex-based email validators.

While conventional validators simply output a boolean true/false, Dixor.Validation treats validation as a deeply analytical process. It returns strongly typed validation results containing exact diagnostic error codes, parsed architectural components, Unicode/IDN analysis, and actionable user suggestions.

Why Not Regular Expressions?

Using Regular Expressions (Regex) for email validation is widely considered an anti-pattern in enterprise software due to several critical engineering flaws:

1. Catastrophic Backtracking (ReDoS): Complex email regexes are notoriously vulnerable to Denial of Service attacks when parsing maliciously crafted input strings.
2. Standards Non-Compliance: Even massive regex patterns regularly fail to handle legitimate RFC syntax rules, quoted strings, comments, or Internationalized Domain Names (IDNs).
3. Zero Actionable Feedback: A failing regex only tells you the input rejected the pattern—it cannot tell you why (e.g., consecutive dots vs. missing TLD).
4. Excessive Heap Allocations: Regex evaluation frequently allocates significant temporary memory strings during complex pattern matching.

Dixor.Validation eliminates regex dependency by utilizing a structured, state-based tokenizer that parses inputs cleanly against RFC internet specifications.

Validation Strategy & Layers

The Dixor.Validation.Email pipeline evaluates email addresses in structured architectural layers:

                ┌──────────────────────────────┐
                │         Input String         │
                └──────────────┬───────────────┘
                               ▼
                ┌──────────────────────────────┐
                │   Basic Structural Check     │  (At-Symbol separation, string bounds)
                └──────────────┬───────────────┘
                               ▼
                ┌──────────────────────────────┐
                │    Local-Part Evaluation     │  (Quotes, character rules, length limits)
                └──────────────┬───────────────┘
                               ▼
                ┌──────────────────────────────┐
                │      Domain Evaluation       │  (TLD rules, IDN support, label structure)
                └──────────────┬───────────────┘
                               ▼
                ┌──────────────────────────────┐
                │  Structured ValidationResult │  (Diagnostics, errors, typo suggestions)
                └──────────────────────────────┘

Dixor.Validation - Features & API Reference

Rich Diagnostics & Structured Results

Validation operations return a generic ValidationResult<EmailValidationError> payload containing complete diagnostic state data.

using Dixor.Validation.Email;
ValidationResult<EmailValidationError> result = EmailValidator.Default.Validate("john..doe@example.com");
if (!result.IsValid) { Console.WriteLine($"Validation Failed: {result.Error}"); }

Strongly Typed Error Enums (EmailValidationError)

• InvalidLocalPart — Prefix contains illegal structure.
• InvalidDomain — Domain structure violates naming standards.
• ConsecutiveDots — Illegal sequence (..).
• MissingAtSymbol — Missing @ delimiter.
• EmptyLocalPart / EmptyDomain — Missing components.
• InvalidCharacter — Prohibited control characters or spaces.

Parsing & Inspection APIs

EmailAddress address = EmailParser.Parse("john.doe@example.co.uk");
Console.WriteLine($"Local Part : {address.LocalPart}");
Console.WriteLine($"Domain     : {address.Domain}");

Intelligent Suggestion Engine

User registration flows frequently suffer from high drop-off rates due to domain typos. Dixor.Validation incorporates an algorithmic domain suggestion engine:

ValidationResult<EmailValidationError> typoResult = EmailValidator.Default.Validate("alice@gmai.com");
if (!typoResult.IsValid && typoResult.HasSuggestions)
{
    foreach (string suggestion in typoResult.Suggestions)
    {
        Console.WriteLine($"Did you mean: {suggestion}?"); // Output: gmail.com
    }
}

Dixor.Validation - Quick Start

using System;
using Dixor.Validation.Email;

public class RegistrationService
{
    public void ProcessRegistration(string userEmailInput)
    {
        ValidationResult<EmailValidationError> result = EmailValidator.Default.Validate(
            userEmailInput, 
            EmailValidationOptions.Default
        );

        if (!result.IsValid)
        {
            Console.WriteLine($"[Error] Rejected email: {result.Error}");
            if (result.HasSuggestions)
            {
                Console.WriteLine($"Suggestion: Try '{string.Join(", ", result.Suggestions)}'");
            }
            return;
        }

        EmailAddress verifiedAddress = EmailParser.Parse(userEmailInput);
        Console.WriteLine($"[Success] Routing welcome packet to domain: {verifiedAddress.Domain}");
    }
}

Documentation Structure

When viewed on our dedicated DocFX web portal, ecosystem documentation is organized into clear domains:

docs/
├── index.md                        <-- Ecosystem Landing Portal
├── getting-started/
│   ├── Installation.md
│   └── MigrationGuide.md
├── identity/
│   ├── uuid7/
│   ├── ulid/
│   ├── analyzers/
│   └── internals/
└── validation/
    └── email/

Supported Frameworks

Every library in the Dixor ecosystem targets modern .NET runtimes to leverage advanced memory primitives (Span<T>, ReadOnlySpan<T>) and aggressive compiler optimizations.

Ecosystem Roadmap

Dixor is actively evolving to cover mission-critical enterprise infrastructure requirements.

🔐 Dixor.Identity Roadmap

• Snowflake Identifiers: Distributed 64-bit integer generation for extreme-scale microservices.
• Sequential GUIDs: Native SQL Server optimized identifier algorithms (AtEnd ordering).
• Source Generators: Compile-time identity binding for high-throughput messaging contracts.

✔️ Dixor.Validation Roadmap

• Email Module Enhancements: Active DNS resolution, MX record verification, disposable email detection.
• URL Validation Engine: RFC 3986 structured URI syntax checking and scheme authorization.
• Enterprise Financial Modules: International Bank Account Number (IBAN), VAT, and ISO credit card validation.

Contributing

Contributions, feature proposals, and bug reports are warmly welcomed!

1. Fork the repository.
2. Create a feature branch (git checkout -b feature/amazing-feature).
3. Commit your changes following standard rules (git commit -m 'Add amazing feature').
4. Ensure all analyzer diagnostics and unit tests pass cleanly.
5. Push to the branch and open a Pull Request.

License

Every package in the Dixor ecosystem is published under the terms of the MIT License. See the root LICENSE file for legal specifics.