Dixor.Validation 0.1.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, 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
  • 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 two production-grade, independently distributed libraries designed for high-throughput enterprise systems, cloud-native microservices, and modern ASP.NET Core applications.

Package	Current Version	NuGet Downloads	Primary Purpose	Key Highlights
Dixor.Identity	v0.1.3 (Runtime v0.1.4)		RFC 9562 UUID Version 7 generation, monotonic sequencing, and parsing.	Time-ordered database primary keys, embedded timestamp extraction, zero-allocation APIs.
Dixor.Validation	v0.1.0		High-performance validation engine starting with structured email validation.	RFC-aware syntax parsing, strongly typed error diagnostics, domain typo suggestion engine.

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.1.4" />
  <PackageReference Include="Dixor.Validation" Version="0.1.0" />
</ItemGroup>

Dixor.Identity

Dixor.Identity - Introduction & Core Philosophy

Dixor.Identity delivers modern, allocation-conscious identifier generation 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. Version 7 identifiers embed a millisecond-precision Unix timestamp in their most significant bits, making them naturally sortable in chronological order while utilizing 74 bits of cryptographic randomness to guarantee global uniqueness.

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

Dixor.Identity - Features & API Reference

🚀 Standard UUIDv7 Generation

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

using Dixor.Identity.UUID7;

Guid identifier = Uuid7.New();

⚡ Monotonic UUID Generation

In ultra-high-throughput systems generating multiple records within the exact same millisecond, standard UUIDv7 values sort chronologically by timestamp but rely on random bits within that millisecond. Uuid7.NewMonotonic() guarantees strict mathematical sequential order across identical timestamps by safely incrementing the random sequence.

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

📦 High-Efficiency Batch Generation

Reduces loop overhead and streamlines mass insertions during ETL pipelines, batch migrations, or data seeding.

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

🔍 Validation & Parsing

Instantly verify whether any arbitrary Guid adheres to the RFC 9562 UUIDv7 specification, or safely parse incoming strings from HTTP headers or payload strings.

Guid sampleId = Guid.NewGuid(); // Creates a UUIDv4
bool isValidV7 = Uuid7.IsValid(sampleId); // Returns false

Guid parsedId = Uuid7.Parse("Order-019853a6-35c4-7e58-bf91-cb7d0b1b11d2");

⏱ Zero-Overhead Timestamp Extraction

Extract exact generation timestamps directly from the identifier without needing database lookups or storing secondary CreatedAt date columns.

DateTimeOffset creationTime = Uuid7.GetTimestamp(identifier);
// Output: 2026-07-04T18:42:17.125+00:00

🎨 Business-Friendly Formatting

Wrap identifiers in descriptive domain metadata while keeping the core UUID intact.

string orderReference = Uuid7.NewString(prefix: "ORD", suffix: "US");
// Output: ORD-019853a6-35c4-7e58-bf91-cb7d0b1b11d2-US

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. Starting with runtime release v0.1.4, analyzer packages are structured cleanly to optimize restore speeds.

Dixor.Identity - Quick Start

using System;
using Dixor.Identity.UUID7;

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

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

// 3. Create a clean business reference string for external APIs
string trackingNumber = Uuid7.NewString(prefix: "SHP", suffix: "GLOBAL");
Console.WriteLine($"Tracking Ref : {trackingNumber}");

// 4. Batch generate monotonic IDs for bulk transactional processing
foreach (Guid batchId in Uuid7.NewGuids(3))
{
    Console.WriteLine($"Batch Entity : {batchId}");
}

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)

Instead of parsing arbitrary strings, applications can programmatically branch logic using precise failure codes:

• InvalidLocalPart — The local account prefix contains illegal characters or improper structure.
• InvalidDomain — The domain structure violates internet naming standards.
• ConsecutiveDots — Illegal syntax containing consecutive periods (..) in unquoted spaces.
• MissingAtSymbol — Structural failure due to a missing @ delimiter.
• EmptyLocalPart — Address starts directly with @domain.com.
• EmptyDomain — Address lacks a target domain (user@).
• InvalidCharacter — Presence of control characters, spaces, or restricted ASCII symbols.

Parsing & Inspection APIs

In addition to validation, the library provides dedicated parsing and inspection utilities that safely dissect addresses into structured models.

using Dixor.Validation.Email;

// Parse directly into a domain object
EmailAddress address = EmailParser.Parse("john.doe@example.co.uk");

Console.WriteLine($"Local Part : {address.LocalPart}"); // john.doe
Console.WriteLine($"Domain     : {address.Domain}");    // example.co.uk

Intelligent Suggestion Engine

User registration flows frequently suffer from high drop-off rates due to common domain typos on mobile devices. Dixor.Validation incorporates an algorithmic domain suggestion engine that detects common spelling errors and calculates immediate corrections.

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)
    {
        // 1. Execute customized validation pipeline
        ValidationResult<EmailValidationError> result = EmailValidator.Default.Validate(
            userEmailInput, 
            EmailValidationOptions.Default
        );

        // 2. Handle failures cleanly
        if (!result.IsValid)
        {
            Console.WriteLine($"[Error] Rejected email: {result.Error}");

            // 3. Proactively assist users with domain typo corrections
            if (result.HasSuggestions)
            {
                Console.WriteLine($"Suggestion: Try '{string.Join(", ", result.Suggestions)}'");
            }
            return;
        }

        // 4. Parse verified data safely
        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, the ecosystem documentation is organized into clear, intuitive domains:

docs/
├── index.md                        <-- Ecosystem Landing Portal
├── getting-started/
│   ├── Installation.md
│   └── MigrationGuide.md
├── identity/
│   ├── uuid7/
│   │   ├── Overview.md
│   │   ├── Generation.md
│   │   ├── MonotonicGeneration.md
│   │   └── Formatting.md
│   ├── analyzers/
│   └── internals/
└── validation/
    ├── email/
    │   ├── Overview.md
    │   ├── Validation.md
    │   ├── Parsing.md
    │   └── Suggestions.md
    └── roadmap/

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

• ULID Support: High-performance Lexicographically Sortable Identifier generation.
• 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, and domain reputation checks.
• URL Validation Engine: RFC 3986 structured URI syntax checking and scheme authorization.
• Enterprise Financial Modules: International Bank Account Number (IBAN), Value Added Tax (VAT), and ISO credit card validation.
• Structured Data Pipelines: High-speed JSON schema validation and XML structure checking.

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 formatting 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.