Because n++
wasn't scalable enough.

Quick Start#

The Increment static class is the main entry point. It exposes a fluent API and a JustDoIt shorthand. Both go through the full enterprise pipeline — caching, validation, strategy selection, middleware, event sourcing, telemetry. There is no escape.

// The fluent way.
var result = await Increment.ThisNumber(41)
    .AsUser("DemoUser")
    .BecauseINeedTo("calculate the meaning of life + 1")
    .Urgently()
    .PleaseAsync();

Console.WriteLine(result.ResultValue); // 42

// The impatient way. Still goes through the full pipeline.
var result = await Increment.JustDoIt(99);

// Batch mode.
var batch = await Increment.ThoseNumbers(1, 2, 3, 4, 5);
// Results: 1→2, 2→3, 3→4, 4→5, 5→6

The default orchestrator is created lazily on first use via Lazy<IncrementOrchestrator> and is configured with WithFullEnterpriseConfiguration() — all six strategies, all four validators, all three middleware layers, caching, telemetry, and event sourcing.

Fluent Builder#

IncrementOrchestratorBuilder lets you compose a custom orchestrator. Call Create(), chain the desired components, then Build().

var orchestrator = IncrementOrchestratorBuilder.Create()
    .WithClassicStrategy()
    .WithBitwiseStrategy()
    .WithMonteCarloStrategy()        // live dangerously
    .WithOverflowProtection()
    .WithSuperstitionProtection()
    .WithRateLimiting(maxPerMinute: 10)
    .WithLogging()
    .WithPremiumExperience(delayMs: 200)
    .WithRetryPolicy()
    .WithCaching(maxSize: 50000)
    .WithTelemetry()
    .WithEventSourcing()
    .Build();

// Or: the nuclear option.
var orchestrator = IncrementOrchestratorBuilder.Create()
    .WithFullEnterpriseConfiguration()
    .Build();

Builder Methods

Increment Strategies#

Six strategies, all arriving at the same answer. Strategies are sorted by Priority descending — the orchestrator picks the first one where CanHandle(value) returns true. Pass a name to .UsingStrategy("MonteCarlo") to override selection.

Implementing a Custom Strategy

Implement IIncrementStrategy<T> and register it with .WithStrategy(myStrategy).

public sealed class MyIncrementStrategy : IIncrementStrategy<int>
{
    public string StrategyName    => "MyStrategy";
    public string StrategyDescription => "My custom approach";
    public Version StrategyVersion => new(1, 0, 0);
    public int    Priority        => 75; // between LookupTable(80) and Bitwise(50)

    public bool CanHandle(int value) => value >= 0;

    public Task<IncrementResult<int>> IncrementAsync(
        int value, IncrementContext context, CancellationToken ct = default)
    {
        context.AddAuditEntry($"MyStrategy: computing {value} + 1");
        return Task.FromResult(new IncrementResult<int>
        {
            OriginalValue = value, ResultValue = value + 1,
            IsSuccess = true, StrategyUsed = StrategyName
        });
    }
}

Validation Pipeline#

Validators run sequentially before strategy selection. A single failure short-circuits the pipeline and returns an unsuccessful IncrementResult<T>. Warnings (e.g. from SuperstitionGuard) are recorded in the audit trail but do not block execution.

Implementing a Custom Validator

public sealed class EvenNumberValidator : IIncrementValidator<int>
{
    public string ValidatorName => "EvenNumberGuard";

    public Task<ValidationResult> ValidateAsync(
        int value, IncrementContext context, CancellationToken ct = default)
    {
        if (value % 2 != 0)
            return Task.FromResult(ValidationResult.Failure(
                ValidatorName, "Only even numbers may be incremented here."));

        return Task.FromResult(ValidationResult.Success(ValidatorName));
    }
}

Middleware Pipeline#

Middleware wraps the strategy execution in a chain, ordered by Order ascending. Each piece calls next(value, context) to invoke the rest of the chain. The default stack runs: Logging → PremiumExperience → Retry → Strategy.

Retry Delay Calculation

var delay = context.Options.RetryPolicy switch
{
    RetryPolicy.Linear             => TimeSpan.FromMilliseconds(100 * attempt),
    RetryPolicy.ExponentialBackoff  => TimeSpan.FromMilliseconds(Math.Pow(2, attempt) * 50),
    RetryPolicy.RandomizedJitter    => TimeSpan.FromMilliseconds(new Random().Next(50, 500)),
    _                               => TimeSpan.Zero
};

Event Sourcing#

Every increment operation emits domain events appended to an IncrementEventStore. Each stream is keyed by the RequestId (correlation ID). Events are stored in a ConcurrentDictionary protected by a ReaderWriterLockSlim. The global sequence number is thread-safe via Interlocked.Increment.

var store = orchestrator.GetEventStore();

// All events across all streams, ordered by global sequence number.
var all = store.GetAllEvents();

// Events for a specific operation.
var stream = store.GetStream(request.RequestId);

Console.WriteLine($"Total events:  {store.TotalEvents}");
Console.WriteLine($"Total streams: {store.TotalStreams}");

Increment (facade)#

static class Increment — the top-level entry point. Uses a Lazy<IncrementOrchestrator> singleton configured with WithFullEnterpriseConfiguration().

IncrementRequestBuilder — Fluent Chain

Returned by Increment.ThisNumber(n). All methods return this for chaining. Terminated by PleaseAsync().

IncrementResult<T>#

The return type of every increment operation. You don't just get n+1 — you get n+1 with full provenance. All properties are init-only. Call ToJson() for indented camelCase JSON serialization.

IncrementRequest<T>#

Wraps the input value with metadata. Use the static factory IncrementRequest<T>.Create() or construct directly with object initializer syntax. All properties are init-only.

IncrementOptions#

Per-request pipeline configuration. Pass via .WithOptions(o => { ... }) on the fluent builder, or set directly on IncrementRequest<T>.Options. All properties are init-only.

Batch Processing#

Increment.ThoseNumbers() and IIncrementOrchestrator<T>.OrchestrateBatchAsync() process multiple requests concurrently using a SemaphoreSlim to cap parallelism at BatchOptions.MaxDegreeOfParallelism.

var batch = await Increment.ThoseNumbers(1, 2, 3, 4, 5);

Console.WriteLine($"Requests:     {batch.TotalRequests}");
Console.WriteLine($"Successes:    {batch.SuccessCount}");
Console.WriteLine($"Success rate: {batch.SuccessRate:P0}");
Console.WriteLine($"Total time:   {batch.TotalDuration}");

BatchOptions

BatchIncrementResult<T>

Enums#

ConfidenceLevel

Priority

RetryPolicy

Interfaces#

Good architecture starts with at least 14 interfaces. IaaS ships with exactly 11 public ones — the other 3 are implied by good taste.

Telemetry#

IncrementTelemetryCollector uses Interlocked for all counters and a ConcurrentBag<TimeSpan> for duration samples. Call orchestrator.GetTelemetry() to get a point-in-time snapshot.

var snap = orchestrator.GetTelemetry();
Console.WriteLine($"Attempts:     {snap.TotalAttempts}");
Console.WriteLine($"Successes:    {snap.TotalSuccesses}");
Console.WriteLine($"Failures:     {snap.TotalFailures}");
Console.WriteLine($"Cache hits:   {snap.CacheHits}");
Console.WriteLine($"Cache misses: {snap.CacheMisses}");
Console.WriteLine($"Avg duration: {snap.AverageDuration}");
Console.WriteLine($"Max duration: {snap.MaxDuration}");

foreach (var (name, count) in snap.StrategyUsage)
    Console.WriteLine($"  {name}: {count} uses");

// Cache statistics
var cache = orchestrator.GetCacheStatistics();
Console.WriteLine($"Hit rate:     {cache.HitRate:P1}");
Console.WriteLine($"Cache size:   {cache.CurrentSize}");
Console.WriteLine($"Evictions:    {cache.Evictions}");

Caching#

InMemoryIncrementCache wraps a ConcurrentDictionary keyed by the input value. Each entry stores the result alongside an expiry timestamp. Default TTL: 1 hour. Default max size: 10,000 entries. On capacity breach, the entry with the earliest expiry is evicted — which is enterprise-grade LRU if you squint.

Caching is skipped if IncrementOptions.EnableCaching is false. The second call for the same value returns a copy of the cached result with WasCached = true, bypassing all validators, strategy selection, and middleware.

var first  = await Increment.JustDoIt(7);
var second = await Increment.JustDoIt(7);

Console.WriteLine(first.WasCached);   // false
Console.WriteLine(second.WasCached);  // true
Console.WriteLine(second.Duration);   // near-zero

Benchmarks#

Measured against n++. IaaS loses in every category except observability, which is not benchmarked because it's immeasurable.

* Benchmarks run on a machine that could have used n++ instead. Note: cache hits are competitive with raw n++, which means the cache technically justifies the entire library.

FAQ#