Cuemon.Kernel

Overview

Cuemon.Kernel is the lowest-level Cuemon package. It supplies the guard clauses, condition queries, option-object conventions, decorator wrapper, conversion primitives, disposable base classes, and asynchronous polling helpers that the rest of the Cuemon family can build on.

The package is broad by design, but the pieces follow a consistent model. Configure parameter objects through Patterns.Configure, validate them through Validator, surface success or failure through ConditionalValue, and use the text, conversion, and disposal types when plain framework APIs need stronger invariants or a reusable contract.

Key APIs

Validator is the main guard surface. It centralizes null, empty, range, type, interface, URI, GUID, reserved keyword, and options validation, and it also coordinates IPostConfigurableParameterObject and IValidatableParameterObject when an options object must be normalized before use.

Condition complements Validator with non-throwing checks. It covers equality, numeric ranges, string shape checks such as email, GUID, hexadecimal, and URI formats, and small control-flow helpers such as FlipFlop, FlipFlopAsync, and TernaryIf.

Configurable<TOptions> formalizes the package's options pattern. Together with IParameterObject, IPostConfigurableParameterObject, and IValidatableParameterObject, it gives reusable components a consistent way to accept, validate, and retain strongly typed options.

Patterns collects the package's composition helpers. It creates configured option objects, reverses or exchanges option delegates, classifies fatal versus recoverable exceptions, and safely initializes disposable resources through the SafeInvoke overloads.

Convertible turns IConvertible values and sequences into byte arrays with configurable endianness and encoding behavior. It also converts byte arrays back to strings, supports global or per-call custom converters, and exposes bit-reversal helpers for integer values.

Decorator and IDecorator<T> wrap an object so non-common extension methods can hang off a narrower surface. The package uses that model for infrastructure-style extensions such as stream helpers without forcing every extension onto the base type.

Disposable and FinalizeDisposable provide the package's disposal contracts. They separate managed and unmanaged cleanup hooks, track the disposed state, and give derived types an explicit place to implement deterministic cleanup.

ByteOrderMark handles BOM-aware encoding work. It can detect encodings from byte arrays or seekable streams, decode a BOM into an Encoding, and remove preambles from both bytes and streams.

Awaiter.RunUntilSuccessfulOrTimeoutAsync packages a retry-until-success loop around ConditionalValue. It keeps polling until success or timeout, honors AsyncRunOptions, and returns an UnsuccessfulValue or aggregated exception state when the work never succeeds.

Basic usage

using System;
using Codebelt.Extensions.Xunit;
using Cuemon;
using Cuemon.Configuration;
using Xunit;

namespace MyProject.Tests;

public sealed class CuemonKernelOptionsTest : Test
{
    public CuemonKernelOptionsTest(ITestOutputHelper output) : base(output)
    {
    }

    [Fact]
    public void ShouldBuildValidatedOptionsForAConsumerComponent()
    {
        var sut = new RetryPolicy(Patterns.Configure<RetryPolicyOptions>(o =>
        {
            o.MaxAttempts = 3;
            o.Delay = TimeSpan.FromMilliseconds(250);
        }));

        TestOutput.WriteLine($"Attempts: {sut.Options.MaxAttempts}; Delay: {sut.Options.Delay.TotalMilliseconds} ms");

        Assert.Equal(3, sut.Options.MaxAttempts);
        Assert.Equal(TimeSpan.FromMilliseconds(250), sut.Options.Delay);
    }

    private sealed class RetryPolicy : Configurable<RetryPolicyOptions>
    {
        public RetryPolicy(RetryPolicyOptions options) : base(options)
        {
        }
    }

    private sealed class RetryPolicyOptions : IPostConfigurableParameterObject, IValidatableParameterObject
    {
        public int MaxAttempts { get; set; }

        public TimeSpan Delay { get; set; }

        public void PostConfigureOptions()
        {
            if (Delay == default) { Delay = TimeSpan.FromMilliseconds(100); }
        }

        public void ValidateOptions()
        {
            Validator.ThrowIfLowerThanOrEqual(MaxAttempts, 0, nameof(MaxAttempts), "MaxAttempts must be greater than zero.");
            Validator.ThrowIfTrue(Delay <= TimeSpan.Zero, nameof(Delay), "Delay must be greater than zero.");
        }
    }
}

Use this pattern when a reusable component needs option defaults and invariants to be enforced before the component can be constructed. It matters because Patterns.Configure, the parameter-object interfaces, and Configurable<TOptions> keep configuration rules in one place instead of scattering guard code across every consumer.

Installation

dotnet add package Cuemon.Kernel

Usage guidance

Adopt Cuemon.Kernel when you want a single foundational package for guards, option objects, encoding or byte-conversion helpers, disposal contracts, and asynchronous retry primitives that can be reused across your own libraries. Prefer a more focused sibling package such as Cuemon.IO, Cuemon.Threading, or one of the higher-level Cuemon extensions when you only need a narrower domain surface, and stay with plain framework APIs when simple one-off checks or conversions are enough.