NexusLabs.Framework.Analyzers 0.2.8

NexusLabs.Framework (and friends)

A multi-package repository for cross-cutting NexusLabs C# tooling. Currently ships:

Install

dotnet add package NexusLabs.Framework
dotnet add package NexusLabs.Framework.Analyzers # opt-in lint rules
dotnet add package NexusLabs.StronglyTypedIds    # UUIDv7 creation + bundled analyzers
dotnet add package NexusLabs.Xunit.Assertions    # only in test projects
dotnet add package NexusLabs.TUnit.Assertions    # TUnit assertions + bundled analyzer
dotnet add package NexusLabs.CodeAnalysis.Testing.TUnit  # for TUnit-based analyzer test projects
dotnet add package NexusLabs.Data.Sql            # provider-agnostic decorators
dotnet add package NexusLabs.Data.Sql.MySql      # adds MySql.Data backed factory

Runtime packages target net10.0; Roslyn analyzer assemblies target netstandard2.0. For earlier .NET versions, pin to a 0.1.x of NexusLabs.Framework.

What's in NexusLabs.Framework

Runtime utilities for cross-cutting C# concerns: a result-pattern type family (Tried/TriedEx/TriedNullEx) with Safely / Try orchestration helpers, stream wrappers, AsyncSemaphoreLease and related concurrency primitives, ArrayPool renting handles (RentedSpan/RentedMemory + RentSpan/RentMemory), async event-handler glue, async ADO.NET interface shapes, and process diagnostics. The deprecated ITimeProvider ships for one more 0.x release; migrate to BCL System.TimeProvider.

The authoritative list of public types is the source tree under src/NexusLabs.Framework/ and the XML doc comments shipped in the package. See CHANGELOG.md for what landed in each version.

UUIDv7 strongly typed identifiers

NexusLabs.StronglyTypedIds composes the built-in GUID template with a small additive template. Existing parsing, formatting, equality, JSON conversion, and type conversion remain generated by the underlying identifier package:

using NexusLabs.StronglyTypedIds;
using StronglyTypedIds;

[StronglyTypedId(Template.Guid, GuidIdTemplates.UuidV7)]
public readonly partial struct OrderId;

OrderId orderId = OrderId.Create();

Pass a TimeProvider when the timestamp must be controlled:

OrderId orderId = OrderId.Create(timeProvider);

Or register the generic, mockable generation service:

services.AddUuidV7IdentifierGeneration();

IUuidV7IdentifierGenerator<OrderId> generator =
    serviceProvider.GetRequiredService<IUuidV7IdentifierGenerator<OrderId>>();
OrderId orderId = generator.Create();

The template provides a UUIDv7 creation policy, not a value invariant. The GUID constructor, parsing, deserialization, default, and Empty can preserve arbitrary GUID values for rehydration. The IntelliSense documentation on GuidIdTemplates.UuidV7 calls out this boundary.

The package bundles two error-level analyzers:

• NLS0001 replaces the built-in OrderId.New() UUIDv4 path with OrderId.Create().
• NLS0002 replaces new OrderId(Guid.NewGuid()) while allowing construction from externally sourced GUID values.

UUIDv7 values are timestamp ordered across milliseconds; the remaining bits are random, so the package does not claim strict within-millisecond ordering or database-independent index ordering.

Result pattern

TriedEx<int> result = Safely.GetResultOrException(() => int.Parse(input));

result.Match(
    onSuccess: value => Console.WriteLine($"parsed: {value}"),
    onError: ex => Console.WriteLine($"failed: {ex.Message}"));

TUnit result assertions

NexusLabs.TUnit.Assertions integrates the result pattern with TUnit's native fluent assertions:

using NexusLabs.Framework;
using NexusLabs.TUnit.Assertions;

TriedEx<ThingId> result =
    await service.TryCreateAsync(input, userId, cancellationToken);

var thingId = await Assert.That(result)
    .Succeeded()
    .Because("The service should create the thing");

Failure assertions return the original exception and can require an assignable exception type:

var error = await Assert.That(result)
    .Failed()
    .With<ArgumentException>()
    .Because("Invalid input should be rejected");

The package includes NLT0001, which reports direct assertions such as Assert.That(result.Success) and points callers to the result-level Succeeded() / Failed() API.

Archived packages

Six packages from this repository were archived as part of 0.2.0:

• NexusLabs.Autofac, NexusLabs.Collections.Generic, NexusLabs.Contracts, NexusLabs.Dynamo, NexusLabs.Reflection, NexusLabs.Testing.Xunit

The 0.x lines remain on nuget.org. Source is preserved on the release/0.x branch. See docs/archived-packages/ for per-package migration guidance.

License

MIT © Nexus Software Labs