Coder Legion - Recent posts tagged design-patterns

Priority-Based Job Processing System in C#

Tue, 26 May 2026 08:51:21 +0000

This tutorial explains how to build a multithreaded, priority-based job processing system using:

PriorityQueue<TElement,TPriority>
SemaphoreSlim
Producer / Consumer pattern
Retry mechanism
Dead Letter Queue (DLQ)
Multiple workers

1. What is PriorityQueue in C#?

Definition

PriorityQueue<TElement,TPriority> is a built-in .NET collection that:

Stores elements so that the item with the highest priority is dequeued first, not the one inserted first.

Official docs:
https://learn.microsoft.com/en-us/dotnet/api/system.collections.generic.priorityqueue-2?view=net-10.0

⚙️ How it works (in this system)

private readonly PriorityQueue<Job, int> _queue = new();

Jobs are added like this:

_queue.Enqueue(job, job.Priority);

Each entry has:

Element → Job
Priority → int

Priority rules in .NET

Lower number = higher priority

Priority	Meaning	Execution Order
1	Highest priority	First
2	Medium priority	Next
5	Low priority	Last

Simple example

var queue = new PriorityQueue<string, int>();

queue.Enqueue("Job A", 5);
queue.Enqueue("Job B", 1);
queue.Enqueue("Job C", 3);

Console.WriteLine(queue.Dequeue()); // Job B

⚠️ Important limitation

❌ PriorityQueue is NOT thread-safe
✔ This system fixes that using lock + SemaphoreSlim

2. Job Model

public record Job(
    string Name,
    int Priority,
    int RetryCount = 0,
    int MaxRetries = 3);

Why this works well

Immutable (record)
Safe for multithreading
Supports retry tracking

3. Blocking Priority Queue (Core Engine)

public class BlockingPriorityQueue
{
    private readonly PriorityQueue<Job, int> _queue = new();
    private readonly object _lock = new();
    private readonly SemaphoreSlim _signal = new(0);

Why these 3 components?

Component	Purpose
PriorityQueue	Stores jobs by priority
lock	Thread safety
SemaphoreSlim	Async waiting / signaling

➕ Enqueue (Producer side)

public void Enqueue(Job job)
{
    lock (_lock)
    {
        _queue.Enqueue(job, job.Priority);
        _signal.Release();
    }
}

Flow

Producer → lock → enqueue → signal workers

➖ Dequeue (Consumer side)

public async Task<Job> DequeueAsync(CancellationToken cancellationToken = default)
{
    await _signal.WaitAsync(cancellationToken);

    lock (_lock)
    {
        return _queue.Dequeue();
    }
}

Flow

Worker waits → signal → lock → dequeue highest priority job

4. Dead Letter Queue (DLQ)

public class DeadLetterQueue
{
    private readonly List<Job> _failedJobs = new();

    public void Add(Job job, Exception ex)
    {
        Console.WriteLine($"DLQ: Job {job.Name} failed permanently: {ex.Message}");
        _failedJobs.Add(job);
    }

    public IReadOnlyList<Job> GetAll() => _failedJobs;
}

Purpose

DLQ stores jobs that:

exceeded retry limit
failed permanently
require manual inspection

5. Job Processor (Worker System)

public class JobProcessor(BlockingPriorityQueue jobQueue, DeadLetterQueue deadLetterQueue)
{
    private readonly BlockingPriorityQueue _jobQueue = jobQueue;
    private readonly DeadLetterQueue _deadLetterQueue = deadLetterQueue;

Main processing loop

public async Task ProcessJobsAsync(CancellationToken cancellationToken = default)
{
    while (!cancellationToken.IsCancellationRequested)
    {
        try
        {
            var job = await _jobQueue.DequeueAsync(cancellationToken);

            await ProcessJob(job, cancellationToken);
        }
        catch (OperationCanceledException)
        {
            Console.WriteLine("Job processing cancelled.");
            break;
        }
    }
}

Job execution logic

private async Task ProcessJob(Job job, CancellationToken ct)
{
    try
    {
        Console.WriteLine($"Processing {job.Name}");

        await Task.Delay(500, ct);

        if (Random.Shared.Next(0, 3) == 0)
            throw new Exception("Random failure");

        Console.WriteLine($"✅ Success: {job.Name}");
    }
    catch (Exception ex)
    {
        await HandleFailure(job, ex);
    }
}

6. Retry Logic

private async Task HandleFailure(Job job, Exception ex)
{
    if (job.RetryCount < job.MaxRetries)
    {
        var retryJob = job with
        {
            RetryCount = job.RetryCount + 1
        };

        Console.WriteLine($"Retrying {job.Name} ({retryJob.RetryCount})");

        await Task.Delay(1000);

        _jobQueue.Enqueue(retryJob);
    }
    else
    {
        _deadLetterQueue.Add(job, ex);
    }
}

Behavior flow

Failure → retry → requeue → success OR DLQ

7. Job Producer

public class JobProducer(BlockingPriorityQueue jobQueue, DeadLetterQueue deadLetterQueue)
{
    private readonly BlockingPriorityQueue _jobQueue = jobQueue;
    private readonly DeadLetterQueue _deadLetterQueue = deadLetterQueue;

Publish single job

public void PublishJob(string name, int priority)
{
    var job = new Job(name, priority);

    Console.WriteLine($"Publishing {job.Name} with priority {job.Priority}");

    _jobQueue.Enqueue(job);
}

Publish multiple jobs

public void PublishJobs(IEnumerable<Job> jobs)
{
    foreach (var job in jobs)
    {
        Console.WriteLine($"Publishing {job.Name} with priority {job.Priority}");
        _jobQueue.Enqueue(job);
    }
}

Manual DLQ injection

public void PublishDeadLetterJob(string name, int priority)
{
    var job = new Job(name, priority);

    Console.WriteLine($"Publishing {job.Name} to DLQ");

    _deadLetterQueue.Add(job, new Exception("Manually added"));
}

8. System Execution

Setup

var queue = new BlockingPriorityQueue();
var dlq = new DeadLetterQueue();
var jobProducer = new JobProducer(queue, dlq);
var cts = new CancellationTokenSource();

Start workers

var job1 = new JobProcessor(queue, dlq);
var job2 = new JobProcessor(queue, dlq);

var workerTasks = new[]
{
    Task.Run(() => job1.ProcessJobsAsync(cts.Token)),
    Task.Run(() => job2.ProcessJobsAsync(cts.Token))
};

Publish jobs

for (int i = 0; i < 10; i++)
{
    var priority = Random.Shared.Next(1, 5);

    Console.WriteLine($"\nPublishing Job - {i} with priority {priority}");

    jobProducer.PublishJob($"Job - {i}", priority);
}

Shutdown system

await Task.Delay(3000);

cts.Cancel();

await Task.WhenAll(workerTasks);

Console.WriteLine("System stopped cleanly.");

9. Runtime behavior

Jobs are published with random priority
Stored in PriorityQueue
Workers wait asynchronously
Highest priority job executes first
Random failures occur
Failed jobs retry if allowed
Permanent failures go to DLQ
System shuts down gracefully

10. Key Concepts Learned

✔ PriorityQueue

Built-in heap structure for priority-based scheduling

✔ Thread Safety

Handled using:

lock
SemaphoreSlim

✔ Producer / Consumer

Producer → JobProducer
Consumer → JobProcessor

✔ Retry System

Automatic retry with counter tracking

✔ Dead Letter Queue

Stores failed jobs permanently

✔ Multithreading

Multiple workers process jobs concurrently

✔ Graceful Shutdown

Uses CancellationTokenSource

Summary

Real-world style system that includes:

Priority scheduling
Concurrent workers
Async processing
Retry logic
Failure isolation (DLQ)
Thread-safe queue coordination

Full Implementation

public record Job(string Name,int Priority,int RetryCount = 0, int MaxRetries = 3);
/// <summary>
/// 
/// </summary>
public class BlockingPriorityQueue
{
    /// <summary>
    /// 
    /// </summary>
    private readonly PriorityQueue<Job, int> _queue = new();
    /// <summary>
    /// 
    /// </summary>
    private readonly object _lock = new();
    /// <summary>
    /// 
    /// </summary>
    private readonly SemaphoreSlim _signal = new(0);

    public void Enqueue(Job job)
    {
        lock (_lock)
        {
            _queue.Enqueue(job, job.Priority);

            _signal.Release();
        }
    }

    public async Task<Job> DequeueAsync(CancellationToken cancellationToken = default) { 
    
        await _signal.WaitAsync(cancellationToken);
       
        lock (_lock)
        {
            return _queue.Dequeue();
        }
    }
}


public class DeadLetterQueue
{
    private readonly List<Job> _failedJobs = new();

    public void Add(Job job, Exception ex)
    {
        Console.WriteLine($"DLQ: Job {job.Name} failed permanently: {ex.Message}");
        _failedJobs.Add(job);
    }

    public IReadOnlyList<Job> GetAll() => _failedJobs;
}


public class JobProcessor(BlockingPriorityQueue jobQueue, DeadLetterQueue deadLetterQueue)
{
    private readonly BlockingPriorityQueue _jobQueue = jobQueue;

    private readonly DeadLetterQueue _deadLetterQueue = deadLetterQueue;

    public async Task ProcessJobsAsync(CancellationToken cancellationToken = default)
    {
        while (!cancellationToken.IsCancellationRequested)
        {
            try
            {
               var job = await _jobQueue.DequeueAsync(cancellationToken);
                if (job != null) 
                { 
                    await ProcessJob(job, cancellationToken);
                }
            }
            catch (OperationCanceledException)
            {
                Console.WriteLine("Job processing cancelled.");
                break;
            }
        }
    }

    private async Task ProcessJob(Job job, CancellationToken ct)
    {

        try
        {
            Console.WriteLine($"Processing {job.Name}");

            // Simulate work
            // In a real implementation, this would be where the actual job logic goes
            // For demonstration, we just delay for a short time
            // http Call .. database operation .. etc
            await Task.Delay(500, ct);

            // Simulate random failure
            if (Random.Shared.Next(0, 3) == 0)
                throw new Exception("Random failure");

            Console.WriteLine($"✅ Success: {job.Name}");
        }
        catch (Exception ex)
        {
            await HandleFailure(job, ex);
        }
    }

    private async Task HandleFailure(Job job, Exception ex)
    {
        if (job.RetryCount < job.MaxRetries)
        {
            var retryJob = job with { RetryCount = job.RetryCount + 1 };

            Console.WriteLine($"Retrying {job.Name} ({retryJob.RetryCount})");

            await Task.Delay(1000);

            _jobQueue.Enqueue(retryJob);
        }
        else
        {
            _deadLetterQueue.Add(job, ex);
        }
    }


    public class JobProducer(BlockingPriorityQueue jobQueue, DeadLetterQueue deadLetterQueue)
    {
        /// <summary>
        /// Thread-safe priority queue for managing jobs.   
        /// </summary>
        /// <remarks>Enables prioritized job processing in concurrent scenarios.</remarks>
        private readonly BlockingPriorityQueue _jobQueue = jobQueue;
        /// <summary>
        /// 
        /// </summary>
        private readonly DeadLetterQueue _deadLetterQueue = deadLetterQueue;
        /// <summary>
        /// Publishes a collection of jobs to the job queue.
        /// </summary>
        /// <param name="jobs">The jobs to be published.</param>
        public void PublishJobs(IEnumerable<Job> jobs)
        {
            foreach (var job in jobs)
            {
                Console.WriteLine($"Publishing {job.Name} with priority {job.Priority}");

                _jobQueue.Enqueue(job);
            }
        }

        public void PublishJob(string name, int priority)
        {
            var job = new Job(name, priority);

            Console.WriteLine($"Publishing {job.Name} with priority {job.Priority}");

            _jobQueue.Enqueue(job);
        }

        public void PublishDeadLetterJob(string name, int priority)
        {
            var job = new Job(name, priority);
            Console.WriteLine($"Publishing {job.Name} to DLQ with priority {job.Priority}");
            _deadLetterQueue.Add(job, new Exception("Manually added to DLQ"));
        }
    }
}

var queue = new BlockingPriorityQueue();
var dlq = new DeadLetterQueue();
var jobProducer = new JobProducer(queue, dlq);
var cts = new CancellationTokenSource();

try
{
    var job1 = new JobProcessor(queue, dlq);
    var job2 = new JobProcessor(queue, dlq);

    var workerTasks = new[]
    {
        Task.Run(() => job1.ProcessJobsAsync(cts.Token)),
        Task.Run(() => job2.ProcessJobsAsync(cts.Token))
    };

    // Publish jobs
    for (int i = 0; i < 10; i++)
    {
        var priority = Random.Shared.Next(1, 5);

        Console.BackgroundColor = ConsoleColor.Green;
        Console.WriteLine(Environment.NewLine + $"Publishing Job - {i} with priority {priority}");
        Console.WriteLine($"Publishing Job - {i} with priority {priority}");
        Console.ResetColor();   
        jobProducer.PublishJob($"Job - {i}", priority);
    }

    await Task.Delay(3000);

    cts.Cancel();

    await Task.WhenAll(workerTasks);

    Console.WriteLine("System stopped cleanly.");
}
catch (OperationCanceledException)
{
    Console.WriteLine("Processing cancelled.");
}
catch (Exception ex)
{
    Console.WriteLine($"Error: {ex.Message}");
}

Console.ReadKey();

Abstract Factory Pattern Tutorial

Mon, 11 May 2026 08:15:04 +0000

Abstract Factory Pattern in C# – Step-by-Step Tutorial.

In this tutorial, I’ll explain how I implemented the Abstract Factory Pattern in C# using my project:

GitHub Repository: https://github.com/stevsharp/AbstractFactoryDemo

This project demonstrates how to support multiple database providers like:

SQL Server
MySQL

Each database needs related objects such as:

Database Connection
Database Command

Instead of hardcoding these objects directly, we use the Abstract Factory Pattern to make the code cleaner and scalable.

Step 1: The Problem

Imagine your application supports multiple databases.

Without using Abstract Factory, your code may look like this:

if(databaseType == "SQL")
{
    var connection = new SqlConnection();
    var command = new SqlCommand();
}
else
{
    var connection = new MySqlConnection();
    var command = new MySqlCommand();
}

Why this is bad:

Too many if/else statements
Hard to maintain
Difficult to scale
Tight coupling with concrete classes

We need a better approach.

Step 2: Create Abstract Products

These interfaces define common behavior for all database implementations.

IDbConnection.cs

public interface IDbConnection
{
    void Connect();
}

IDbCommand.cs

public interface IDbCommand
{
    void Execute();
}

Now every database provider must implement these interfaces.

Step 3: Create SQL Server Products

SqlConnection.cs

public class SqlConnection : IDbConnection
{
    public void Connect()
    {
        Console.WriteLine("Connecting to SQL Server...");
    }
}

SqlCommand.cs

public class SqlCommand : IDbCommand
{
    public void Execute()
    {
        Console.WriteLine("Executing SQL command...");
    }
}

These classes handle SQL Server operations.

Step 4: Create MySQL Products

MySqlConnection.cs

public class MySqlConnection : IDbConnection
{
    public void Connect()
    {
        Console.WriteLine("Connecting to MySQL...");
    }
}

MySqlCommand.cs

public class MySqlCommand : IDbCommand
{
    public void Execute()
    {
        Console.WriteLine("Executing MySQL command...");
    }
}

These classes handle MySQL operations.

Step 5: Create the Abstract Factory

Now we create a factory interface.

IDatabaseFactory.cs

public interface IDatabaseFactory
{
    IDbConnection CreateConnection();
    IDbCommand CreateCommand();
}

This ensures every factory creates:

Connection objects
Command objects

Step 6: Create SQL Server Factory

SqlServerFactory.cs

public class SqlServerFactory : IDatabaseFactory
{
    public IDbConnection CreateConnection()
    {
        return new SqlConnection();
    }

    public IDbCommand CreateCommand()
    {
        return new SqlCommand();
    }
}

This factory creates SQL-related objects.

Step 7: Create MySQL Factory

MySqlFactory.cs

public class MySqlFactory : IDatabaseFactory
{
    public IDbConnection CreateConnection()
    {
        return new MySqlConnection();
    }

    public IDbCommand CreateCommand()
    {
        return new MySqlCommand();
    }
}

This factory creates MySQL-related objects.

Step 8: Use the Factory in Client Code

Now the client works with the factory instead of concrete classes.

Program.cs

class Program
{
    static void Main()
    {
        IDatabaseFactory factory = new MySqlFactory();

        var connection = factory.CreateConnection();
        var command = factory.CreateCommand();

        connection.Connect();
        command.Execute();
    }
}

Output

Connecting to MySQL...
Executing MySQL command...

Step 9: Why This Pattern Is Useful

Let’s say your application needs to support PostgreSQL in the future.

You would simply add:

PostgresConnection
PostgresCommand
PostgresFactory

And your client code stays exactly the same.

That makes your code:

✅ Flexible
✅ Maintainable
✅ Scalable
✅ Easy to test

Visual Flow

Client
   ↓
IDatabaseFactory
   ↓
--------------------------------
↓                              ↓
SqlServerFactory         MySqlFactory
↓                              ↓
SqlConnection            MySqlConnection
SqlCommand               MySqlCommand

Real Interview Explanation

Here’s how you can explain this in an interview:

In this project, I used the Abstract Factory Pattern to create families of related database objects. Each database provider creates its own connection and command objects. This reduces tight coupling and makes the application easier to extend when adding new databases.

When Should You Use Abstract Factory?

Use Abstract Factory when:

You need to create families of related objects
You want loose coupling
Your system supports multiple implementations
You want easier scalability

Examples:

Database providers
UI themes
Payment gateways
Cloud providers

Final Thoughts

Abstract Factory is a great design pattern when your application needs flexibility.

Instead of hardcoding object creation logic everywhere, you centralize it through factories and keep your code clean.

If you want to see the full implementation, check out the repository:

https://github.com/stevsharp/AbstractFactoryDemo

Reference

https://refactoring.guru/design-patterns/abstract-factory

# The Rule Pattern in C#, and Why It Works So Well with the Result Pattern

Tue, 07 Apr 2026 10:01:22 +0000

The Rule Pattern in C#, and Why It Works So Well with the Result Pattern

Business rules rarely stay in one place.

A small validation starts in a command handler. Another check appears in a service. A third gets added somewhere in the domain. A few weeks later, the real business policy is scattered across the application, and nobody can see it clearly anymore.

That is exactly where the Rule pattern becomes useful.

At its core, the idea is simple. Instead of expressing business decisions as anonymous conditionals spread throughout the system, you give each rule a name and wrap it in its own object. Martin Fowler describes this style through the Specification pattern, where the statement of what satisfies a candidate is separated from the candidate itself, and those specifications can be combined into richer logic. (martinfowler.com)

In practical C# applications, especially the ones using CQRS or domain-driven design, that gives you something powerful: business rules that are explicit, reusable, and easy to reason about. (martinfowler.com)

What the Rule pattern really solves

The biggest problem is not that business checks exist. The problem is that they often exist in the wrong shape.

When rules are buried inside handlers, services, or controller actions, they are hard to spot, hard to test in isolation, and very easy to duplicate. The code still works, but the business language disappears.

The Rule pattern fixes that by turning each business condition into a named concept. Instead of asking developers to interpret a chain of low-level checks, the code starts speaking in terms the business would actually recognize. That is very much in line with DDD’s emphasis on modeling around the real language of the domain. (Microsoft Learn)

In other words, the pattern is not just about validation. It is about clarity.

Why it is often called the Specification pattern

If the shape feels familiar, that is because it usually is. What many teams call a Rule pattern is very close to what Fowler documented as Specification. The core idea is to represent business criteria as composable objects rather than raw conditionals, and then combine them with logical operations like AND, OR, and NOT. (martinfowler.com)

That is why this pattern tends to feel so natural in real systems. Business rules are rarely isolated. More often, they are layered:

A customer must be verified.
An order must reach a minimum amount.
A credit limit must not be exceeded.

On their own, each rule is simple. The real value appears when they can be combined into a meaningful policy.

Why this pattern becomes more valuable as the system grows

At first, a few inline checks seem harmless. But as the application grows, the cost of hidden business logic grows with it.

Rules get copied into multiple workflows.
One endpoint enforces them, another forgets.
A handler applies three checks, a background job applies only two.
Tests start focusing on branches instead of policies.

When rules become standalone concepts, those problems start to shrink. You can test a rule directly. You can reuse it in multiple flows. You can combine it with other rules. Most importantly, you can read the application flow and understand what it is trying to protect.

That is one of the reasons this pattern fits so well in systems that care about maintainability.

Where the Result pattern fits

The Rule pattern answers one question:

Is this action allowed according to the business?

The Result pattern answers another:

What happened when we tried to perform it?

That separation is the reason the two patterns fit together so well.

The rule evaluates business truth.
The result communicates application outcome.

Vladimir Khorikov’s writing on Result-based error handling makes this distinction especially useful for expected failures. Instead of throwing exceptions for normal business rejections, you can return an explicit failure outcome and keep the flow predictable. (Enterprise Craftsmanship)

That gives you a very clean mental model:

The domain decides.
The application reports.

Why this pairing feels so clean in practice

A good rule object should not care about HTTP, API responses, logging, UI wording, or transport concerns. Its responsibility is much smaller. It answers whether a business condition holds.

The application layer then takes that answer and decides what to do next. If the rule fails, the application can return a failure result. If it passes, the use case continues.

This separation lines up well with Microsoft’s DDD guidance, which treats validations as invariants and emphasizes that aggregates are responsible for enforcing consistency across state changes. (Microsoft Learn)

That is why the combination works so well. The rule keeps business logic clean. The result keeps flow control clean.

A simple order example, without the code

Imagine an order placement use case with three policies:

The order must meet a minimum amount.
The customer must be verified.
The order must stay within the customer’s credit limit.

Without a rule-based approach, those checks often end up inline inside the command handler. That works, but the handler slowly becomes the place where business policy lives.

With a rule-based approach, those policies become named rules. The handler simply coordinates the workflow: load data, build the order, evaluate the rule set, return a success or failure result, and persist when everything is valid.

That is a much healthier separation of concerns.

The handler stops being the place where business logic is invented, and becomes the place where business logic is orchestrated.

The biggest benefit is not flexibility, it is readability

People often talk about this pattern in terms of reuse or composability, and those are real benefits.

But the biggest benefit is readability.

When rules are named well, the code starts reading like a business conversation instead of a technical negotiation. That matters more than people think. Clear code reduces mistakes, speeds up maintenance, and makes onboarding easier for everyone who touches the system later.

A long chain of conditionals tells you how the system behaves.

A well-named rule tells you why.

One important design note

There is one trap worth mentioning.

Just because a rule is expressed cleanly does not automatically mean it belongs in the application layer.

Some rules are just use-case checks. Those can live comfortably near the workflow.

But some rules are true invariants of the domain. Those should usually be protected by the aggregate itself. Microsoft’s guidance is very clear on this point: aggregates are responsible for enforcing invariants across state changes. (Microsoft Learn)

So the right question is not only, “Can I model this as a rule?”

The better question is, “Who is responsible for protecting this rule?”

If the answer is “the domain itself,” then the aggregate should not rely on the handler to remember it.

Where this pattern can go wrong

Like most good patterns, this one becomes dangerous when overused.

Not every if statement needs to become a rule object.
Not every workflow needs an entire rules engine.
Not every tiny validation deserves its own abstraction.

If the business logic is trivial and local, introducing rule classes may create more ceremony than value.

The pattern shines when the rules are meaningful, reusable, and important enough to deserve a name. If the condition is just a one-off technical check, a plain conditional may still be the better choice.

The goal is not abstraction for its own sake. The goal is to make business intent easier to see.

Why the Result pattern keeps the design honest

The Result pattern adds a second layer of clarity.

A failure is no longer hidden behind a thrown exception for something the system fully expected. Instead, the caller gets an explicit outcome. That makes business rejections feel normal rather than exceptional, which is often the right model for application workflows. (Enterprise Craftsmanship)

When paired with rules, the flow becomes very natural:

Evaluate the business policy.
If it fails, return a failure result.
If it passes, continue the operation.

That is simple, predictable, and easy to test.

Final thought

The Rule pattern is one of those ideas that looks modest at first, but pays off more and more as the codebase grows.

It helps you name business policies.
It helps you reuse them.
It helps you combine them.
And when paired with the Result pattern, it gives your application a very clean way to both enforce rules and communicate outcomes. (martinfowler.com)

If your handlers are starting to fill up with business conditionals, this pattern is often a strong sign that the code wants a better language.

And that, more than anything else, is what good domain design is really about.

Source code :

https://github.com/stevsharp/RulePatternApplication

References

Martin Fowler, Specifications. (martinfowler.com)

Microsoft Learn, Designing validations in the domain model layer. (Microsoft Learn)

Microsoft Learn, Designing a DDD-oriented microservice. (Microsoft Learn)

Vladimir Khorikov, Error handling: Exception or Result? (Enterprise Craftsmanship)

Vladimir Khorikov, Advanced error handling techniques. (Enterprise Craftsmanship)

std::visit is awesome, here’s why

Tue, 17 Feb 2026 22:55:13 +0000

One of the very few features of the C++ standard library that I unapologetically like, is the std::visit. It reduces the amount of boilerplate code, kills multiple birds with a single stone, and doesn’t sacrifice performance while doing it. So let’s have a look at how to use it.

Visitor pattern

The Visitor pattern is a more complex OOP design pattern, but once you understand it, it becomes a great tool for breaking up dependencies and removing obtuse conditional statements with RTTI.

It allows you to separate data structures from algorithms operating on those data structures, making it easier to add new algorithms or alter the structures without having to redeploy the other half.

It is popular in compilers, where your source code is represented by an abstract syntax tree (AST), and every single optimization or analysis, like constant propagation, expression folding, or precondition analysis is implemented as its own class (so-called Visitor), separately from the AST declaration.

If you’d like to know how to implement Visitor from the ground up, look no further than superb refactoring.guru website.

Without inheritance

Unlike the standard object-oriented implementation of the Visitor pattern, std::visit doesn’t require you to use inheritance. Due to the underlying use of std::variant and dark standard library magic, std::visit doesn’t use double dispatch and thus you don’t need any accept method on your data structures:

#include <iostream>
#include <variant>
#include <vector>

struct NodeA {};
struct NodeB {};
struct NodeC {};

using Nodes = std::variant<NodeA, NodeB, NodeC>;

struct Visitor {
    void operator() (const NodeA&) { std::cout << "NodeA" << std::endl; }
    void operator() (const NodeB&) { std::cout << "NodeB" << std::endl; }
    void operator() (const NodeC&) { std::cout << "NodeC" << std::endl; }
};

int main() {
    std::vector<Nodes> nodes = {
        NodeA{},
        NodeB{},
        NodeA{},
        NodeC{}
    };

    for (auto&& node : nodes) std::visit(Visitor{}, node);

    // Prints:
    // NodeA
    // NodeB
    // NodeA
    // NodeC
}

As you can see, all you need is a callable struct with overloads for required types. Note that you need to overload on all types that belong to Nodes or you’ll get a compiler error (like with pattern matching in other languages).

The error itself is a classic std nonsense, so look out for this message:

no type named 'type' in 'std::invoke_result<Visitor, TypeThatIsMissing&>'

With inheritance

However, std::visit allows using inheritance. That is even darker magic because you can, but don’t have to, add overloads for only some of the inherited types. The algorithm needs to be able to match the type on at least one overload, and the base class also applies:

#include <iostream>
#include <variant>
#include <vector>

struct NodeBase {};
struct NodeA : public NodeBase{};
struct NodeB : public NodeBase{};

using Nodes = std::variant<NodeA, NodeB>;

struct Visitor {
    void operator() (const NodeA&) { std::cout << "NodeA" << std::endl; }
    void operator() (const NodeBase&) { std::cout << "NodeBase" << std::endl; }
};

int main()
{
    std::vector<Nodes> nodes = {
        NodeA{},
        NodeB{},
    };

    for (auto&& node : nodes) std::visit(Visitor{}, node);

    // Prints:
    // NodeA
    // NodeBase
}

The order of overloads doesn’t matter here. Specialization is preferred over the base class.

Faster than manual dispatch

While std::visit surely has a nice interface (a rare sight in the standard library) and it requires less boilerplate than implementing double dispatch manually, how’s the performance? I do have an unexpected answer - it is faster or at least as fast as the other solutions!

I highly recommend watching Klaus Ingleberger’s talk about the Visitor pattern implementations where he also shows comparison times on GCC and Clang (timestamped to the part with the performance comparison). My own benchmarks on MSVC way back showed a clear win for std::visit over other methods.

Functional programming

C++ committee often comments on how they like their proposals to kill multiple birds with one stone and in the notion of that mindset, you can use std::visit functionally as well.

#include <iostream>
#include <variant>
#include <vector>

struct NodeA {};
struct NodeB {};

using Nodes = std::variant<NodeA, NodeB>;

template<class... Ts>
struct overloaded : Ts... { using Ts::operator()...; };

// Some compilers might require this explicit deduction guide
template<class... Ts>
overloaded(Ts...) -> overloaded<Ts...>;

int main()
{
    std::vector<Nodes> nodes = {
        NodeA{},
        NodeB{},
    };

    for (auto&& node : nodes) {
        std::visit(overloaded{
            [] (const NodeA&) { std::cout << "NodeA" << std::endl; },
            [] (const NodeB&) { std::cout << "NodeB" << std::endl; }
        }, node);
    }

    // Prints:
    // NodeA
    // NodeB
}

Instead of creating one dedicated visitor struct, you can use a helper template class to create an object out of a set of lambdas. This way, you can define your visiting code in the same place as you call it. Some people use this trick to emulate match statements from other languages, others might like it simply because it is functional programming.

Disadvantages

As noted by Klaus in his talk, every approach has its advantages and disadvantages. Because this approach is driven by the std::variant, you must keep in mind its shortcomings:

Types need to be fully defined before they can be used in the variant. This is because their storage size needs to be known.
Using types with vastly different sizes means that your variant will inherently waste a lot of space.
Adding a new type might mean updating all existing visitors (not if you use inheritance) and updating the variant (which you don’t have to do with the classic OO approach).

Do note that you can address the first two problems by using wrapper types like smart pointers or employing the Pimpl pattern.

Summary

As I said in the beginning, I like std::visit very much. Implementing the Visitor pattern takes some getting used to and with this feature, you greatly reduce the amount of boilerplate, improve the readability of the code, and don’t sacrifice performance.

Functional invocation is just a cherry on top for very localized usage where brand new class would just add noise to the code base.

Learning the Single Responsibility Principle, One Test at a Time

Tue, 26 Aug 2025 13:57:56 +0000

The Problem We're Solving

Ever come across a utils.ts file that's more of a everything-but-the-kitchen-sink.ts file? We've all been there. It starts innocently enough with a small helper function, but over time, it becomes a dumping ground. Let's imagine a function called processUserData that handles everything for user registration. It validates the user's data, saves it to the database, and then sends a welcome email.

While this might seem efficient, it's a nightmare to test. How do you write a test for this one function? You'd have to mock the database to prevent it from saving actual data and mock the email service to stop it from sending real emails. It’s like trying to test if a car's horn works, but you're forced to test the engine, the transmission, and the radio at the same time. This complexity is a huge red flag.

The TDD Mindset: Write a Failing Test First

This is where Test-Driven Development (TDD) comes in. The core idea is simple: before you write any code, you write a test for it. The test should fail initially because the code it's testing doesn't exist yet. This forces you to think about what you want your function to do in a very specific way.

Let's try to write a test for our processUserData function:

// processUserData.test.ts

import { processUserData } from './utils';
import { saveUserToDatabase } from './database';
import { sendWelcomeEmail } from './emailService';

// Mocking the external functions so they don't actually run
jest.mock('./database');
jest.mock('./emailService');

describe('processUserData', () => {
  it('should process user data, save to the database, and send a welcome email', () => {
    const userData = { name: 'Alice', email: '*Emails are not allowed*' };

    // This is the part that gets messy
    const result = processUserData(userData);
    expect(result).toBe(true);
    expect(saveUserToDatabase).toHaveBeenCalledWith(userData);
    expect(sendWelcomeEmail).toHaveBeenCalledWith(userData.email);
  });
});

This test is already complicated. It's trying to verify three different things at once: that the function returns a value, that it calls a database function, and that it calls an email function. The test itself is a signal that our function is doing too much. The test is screaming at us to break the function apart.

The "Aha!" Moment: My Own Real-World Example

Let me share my own experience with this. I was working on a project with a massive utils.ts file. I wanted to test just one simple helper function within it, but I discovered it was impossible to do so in isolation. The function I wanted to test was using other functions from the same file, and because they were all in one big file, I couldn't mock them.

I couldn't write a clean, simple test. The test kept getting bloated and complicated, and I found myself in a testing dead end. This frustration was my "aha!" moment. I realized that my inability to mock the other functions was a clear sign that the design was flawed. The functions were too tightly coupled and doing more than they should. The test was telling me: "You need to separate these things."

The solution was to split the file. I moved each function into its own file or into a file with a very specific, related group of functions. By doing this, I made the unrelated functions easy to mock, and suddenly, my tests were simple, clear, and isolated. I had applied the Single Responsibility Principle without even knowing its name. I didn't do it to follow a rule; I did it to make my life easier and make testing possible.

Principles as Solutions, Not Starting Points

This is a key point I want you to remember. Software principles and patterns are not rules we blindly follow just because they exist. They were created to solve problems developers faced. They are solutions that emerged from real-world pain.

You don't need to memorize a list of principles before you start coding. Instead, it's good to be aware of them. When you run into a problem—like a test that's too difficult to write, or a function that's getting too long—you might realize that the problem is a classic one. By searching for a solution, you'll likely find one of these principles, and it will be easy to understand because you've already experienced the pain it's designed to fix.

So, don't worry about being an expert on every rule. Instead, focus on two simple goals: make your code easy to understand and easy to test. Those two goals will naturally guide you toward good design principles, just like they did for me.

Refactor and Separate Responsibilities

The revelation is this: a difficult-to-write test is a sign that your code's design is flawed. The solution is to separate the concerns. Let's break down our massive function into three smaller, more focused functions.

Here is what our new, refactored utils.ts file looks like:

// new utils.ts

export const isValidUserData = (data: any): boolean => {
  if (!data || !data.email) {
    return false;
  }
  // A simple email validation check
  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(data.email);
};

export const saveUserToDatabase = async (data: any): Promise<boolean> => {
  console.log(`Saving user ${data.email} to the database...`);
  // Pretend this function interacts with a real database
  return true;
};

export const sendWelcomeEmail = async (email: string): Promise<boolean> => {
  console.log(`Sending welcome email to ${email}...`);
  // Pretend this function sends a real email
  return true;
};

Now, look at how easy it is to test each of these functions individually.

// isValidUserData.test.ts
import { isValidUserData } from './utils';

describe('isValidUserData', () => {
  it('should return true for a valid email', () => {
    expect(isValidUserData({ email: '*Emails are not allowed*' })).toBe(true);
  });

  it('should return false for an invalid email', () => {
    expect(isValidUserData({ email: 'invalid-email' })).toBe(false);
  });
});

This is so much simpler! We don't need any complex mocking. The tests are focused and clear, and they only care about one specific piece of functionality. By making our code easy to test, we have naturally applied a key programming principle: each function should do one thing and do it well.

The Orchestrator Pattern

Now that we have our small, focused functions, we can create a new function that coordinates them. We'll call this the "orchestrator" function. It doesn't do any of the heavy lifting itself; it simply calls the other functions in the correct order.

// orchestrator.ts

import { isValidUserData, saveUserToDatabase, sendWelcomeEmail } from './utils';

export const processUserData = async (data: any): Promise<boolean> => {
  if (!isValidUserData(data)) {
    console.log('Invalid user data provided.');
    return false;
  }

  await saveUserToDatabase(data);
  await sendWelcomeEmail(data.email);

  return true;
};

This is much cleaner. Our processUserData function is now a manager that delegates tasks to specialists. It asks isValidUserData to validate, tells saveUserToDatabase to save, and instructs sendWelcomeEmail to send the email. This pattern makes the overall process much easier to understand, debug, and maintain.

Finding the Balance: When to Stop and Why

A word of caution: this doesn't mean you should break down every single line of code into its own function. Over-engineering can lead to a confusing project structure with hundreds of tiny files. The true measure of a good design is its ease of testing.

The Golden Rule: If a function or component is still easy to test and read, it likely doesn't need to be broken down further.
The "Why": The goal isn't to create more files; it's to create code that is more maintainable, readable, and flexible. When you need to fix a bug or add a new feature, you should only have to make changes in one place. If you can change the email format without touching the database saving logic, you've found a good balance.

Summary

Congratulations! You've just applied a core software design principle. You started with a messy function that was difficult to test, used a failing test to signal a design flaw, and then refactored the code into smaller, more manageable pieces.

You've discovered that TDD is more than just a testing technique; it's a powerful guide that naturally pushes you toward better, more focused designs. By focusing on writing easy-to-test code, you will find that your projects become easier to maintain, understand, and grow. Keep this mindset, and you'll be building more robust and flexible applications in no time.

Data-Driven Design: Leveraging Lessons from Game Development in Everyday Software

Tue, 24 Jun 2025 22:18:04 +0000

Overview

Modern software often needs to adapt quickly - whether that means processing new data sets, adjusting to user preferences, or deploying new features safely without downtime. To achieve such flexibility, software engineers increasingly adopt a methodology known as Data-Driven Design (DDD).

Originally popularized by game development, Data-Driven Design emerged prominently in the 1990s as large studios confronted a challenging problem: the need to iterate rapidly on complex and interactive content. Game developers realized it was costly and slow to rebuild and redeploy an entire game every time designers wanted to tweak gameplay mechanics, adjust character behaviors, or revise in-game dialogues.

Jason Gregory's influential book Game Engine Architecture highlighted how AAA games effectively tackled this challenge by externalizing game logic into structured data files. Instead of embedding behaviors directly in C++ code, developers loaded data such as AI rules, game levels, item descriptions, and story dialogues from easily editable files like YAML, JSON, or custom formats. This dramatically accelerated iteration, empowering non-programmers - artists, designers, and writers - to directly experiment and refine experiences without requiring code recompilation or redeployment.

Although originally rooted in game development, Data-Driven Design has proven invaluable across software domains, ranging from web development, data analytics, and DevOps automation to no-code and low-code platforms. The fundamental principle remains the same: separate generic engines from domain-specific data.

The Core Idea Behind Data-Driven Design

Before we dive deeper, let's provide a clear working definition that illustrates why Data-Driven Design is relevant to developers and system administrators today:

Data-Driven Design means that the software's behavior is governed by external data rather than hard-coded logic. The code provides generic mechanisms for processing that data, but the specifics of “what to do” or “how to behave” live in data files (such as YAML, JSON, or databases) that can be changed independently from the source code itself.

To clarify further, here's a quick comparison:

Pattern	What drives behavior?	Practical Example
Hard-coded	Embedded conditional statements in code	`if user.is_premium: enable_feature()`
Config-driven	Simple flags or settings in config files	`max_connections = 10` in `config.ini`
Data-driven	Entire behaviors defined in structured data (YAML, JSON, SQLite)	YAML defining a workflow or SQLite storing business rules

Below are some common misconceptions and anti-patterns to help clarity things:

"It's just a config file." – If removing the file breaks the program, it's not mere config; it's content that defines runtime behaviour.
"DDD = No code." – Wrong: the goal is to keep the engine generic and thin, but domain logic still has to live somewhere (often in a domain-specific language interpreted by the engine).
Premature complexity – Don't invent a custom DSL when a handful of YAML documents plus a small interpreter class will do.
Debugging blind – Always log "which data row caused this action?" so you can trace bugs quickly.

High-Level Architecture Overview

A typical Data-Driven Design architecture clearly separates:

Authoring Layer
- Human-readable formats like YAML or JSON.
- Editable directly by users or via automated processes.
Validation & Build Layer
- Schema definitions or migrations that ensure data consistency.
Runtime Loader & Hot Reload
- Reads and validates data at runtime.
- Supports hot-reload for rapid iterations.
Generic Runtime System
- Executes logic based purely on loaded data.

This creates a robust pipeline where data edits alone trigger different application behaviors.

Data Files (YAML/SQLite)
    │ load & validate
    ▼
Generic Runtime Engine
    │ executes behaviors based on data
    ▼
Dynamic Behavior in Application

Choosing Your Data Container

Here's a quick guide to choosing your data format based on needs:

Format	Advantages	Typical Use Case
YAML/JSON/TOML	Human-readable, simple to version control	Small-to-medium complexity workflows, configs
SQLite	Relational queries, consistency, single file	Complex rule sets, relational data, analytics
Binary Formats	Performance-critical loading	Embedded systems, high-performance scenarios

Typically, you start with YAML or JSON, then upgrade to SQLite as complexity grows.

Practical Example: Data-Driven Workflows with Divooka

Divooka is the visual programming language that naturally embodies Data-Driven Design principles through its composable dataflow nodes. Let's illustrate this clearly with a straightforward example:

Scenario:

A data analyst wants to build an automated workflow to:

Load a CSV file containing customer orders.
Filter orders exceeding a certain threshold.
Send a summary via a web API.

In Divooka, the process is streamlined as follows:

1. Load Data with Path and File Nodes

Path node specifies file location (e.g., /data/orders.csv).
Load from CSV file read node directly loads CSV data into a structured DataGrid.

[Path Node] "/data/orders.csv"
    │
    └─► [Load from CSV Node]
           │
           └─► DataGrid

Equivalent Python-like pseudocode:

orders_df = pd.read_csv("/data/orders.csv")

2. Filtering Data

Filter node takes the DataGrid and filters based on condition (e.g., order_total > 100).

DataGrid
    │
    └─► [Filter Node] condition: order_total > 100
           │
           └─► Filtered DataGrid

Equivalent pseudocode:

high_value_orders = orders_df[orders_df["order_total"] > 100]

3. Sending Data via HTTP API

String node specifies the webhook URI.
HTTP Send Request node sends the filtered data automatically serialized as JSON.

[String Node] "https://hooks.example.com/orders"
    │
    └─► [Send Request Node] method: POST, body: Filtered DataGrid

Equivalent pseudocode:

import requests
payload = high_value_orders.to_dict(orient='records')
requests.post("https://hooks.example.com/orders", json=payload)

Why Divooka Is Naturally Data-Driven:

High-level abstraction nodes (Path, String, File I/O, Web Request) handle data transparently.
Nodes clearly define dependencies and flow, automatically adjusting behavior when input data changes.
Entire workflows can be modified without touching underlying engine code or restarting the runtime environment.

Best Practices and Pitfalls

When embracing Data-Driven Design, keep the following in mind:

Practice	Recommendation
Schema Validation	Always enforce schemas (e.g., JSON Schema or SQLite migrations) to prevent errors
Hot Reloading	Clearly separate parsing from data activation steps
Security Considerations	Never trust external data implicitly; always validate or sanitize it before use
Performance Optimization	Cache loaded data where appropriate to avoid redundant parsing

Try It Yourself: Starter Projects

To practice Data-Driven Design, consider these beginner-friendly projects:

Feature Flag Dashboard: YAML-based flags control feature visibility.
Email Routing Automation: SQLite stores routing rules to sort incoming emails.
Procedural Content Generator: YAML files configure parameters for generated data outputs.

Each project reinforces that your engine stays generic and data explicitly drives all behaviors.

Conclusion

Data-Driven Design originated as a powerful solution to rapid iteration in the game development world, enabling large teams to build and adjust complex software efficiently. Today, its principles transcend industries, benefiting system administrators, data analysts, web developers, and more.

In tools like Divooka, Data-Driven Design emerges naturally - dataflow-based nodes inherently separate behavior from implementation, ensuring flexibility and robustness. By clearly distinguishing between generic program logic and externally-driven data, you create maintainable, adaptable, and resilient software.

References

Wikipedia on Data-driven programming - not to be confused with Data-oriented design.
Jason Gregory's book on Game Engine Architecture (table of contents).
Richard Fabian's book on Data-Oriented Design (online version).

5 tips to know before building a design system

Mon, 23 Jun 2025 18:44:44 +0000

Creating a design system is a big step toward scaling design and development efficiently. Here are 5 key tips to know before you start building one:

1. Define the Purpose and Scope First

Before jumping into components or tokens, clarify why you're building a design system. Are you solving consistency issues? Speeding up dev cycles? Supporting multiple products?
Define:

Primary users (designers, devs, PMs)
Supported platforms (web, mobile, etc.)
Short-term and long-term goals

2. Build a Strong Foundation with Design Tokens

Design tokens (colors, typography, spacing, etc.) are the core of your system's consistency. Start by establishing:

A naming convention (e.g., color-primary, spacing-sm)
Token hierarchy (global vs. component-specific)
How tokens will be consumed by code (via CSS variables, JSON, etc.)

3. Start Small and Scale

Don’t try to build everything at once. Focus on core components first—buttons, inputs, modals—then expand.
Use real product needs to drive what gets added. Avoid "just in case" components.

4. Collaborate Early with Developers

A successful design system is not just a design asset—it's a living product used by teams. Involve engineers from the start to:

Align on tech stack (e.g., React, Vue, Web Components)
Ensure components are accessible, performant, and maintainable
Avoid a “design-only” system no one uses

5. Document Everything Clearly

Adoption depends on clear, centralized documentation. Include:

Guidelines (how and when to use components)
Code snippets or package install instructions
Do/Don’t examples
Contribution and update processes

If you are using Angular, you can keep project Structure like this.

src/
├── app/
│   ├── core/        # Singleton services, guards, interceptors
│   ├── shared/      # Shared components, pipes, directives
│   ├── features/    # Feature modules (lazy-loaded)
│   └── design-system/  # Your component library (if building one)
├── assets/          # Images, icons, styles
├── environments/    # Env-specific settings

You can create a component library of your design system:

ng generate library ui-kit

For documenting UI components you can use Storybook:

npx sb init --type angular

TechTalk 20250611: Factory Pattern - Separating Creation from Use

Wed, 11 Jun 2025 13:28:15 +0000

At its core, the Factory Pattern centralizes object creation into dedicated methods or classes, instead of scattering new calls or complex constructors throughout your codebase. This separation yields several benefits:

Clarity of Intent
A method named CreateFromCsv() or ConfigureNumberDisplay() immediately tells the reader what kind of object will emerge, whereas a bare constructor new TextDisplayConfiguration(…) may require you to look up parameter lists and defaults.
Flexible Return Types
Static factory methods can return any subtype or cached instance they choose. A constructor must always return a fresh instance of its own class.
Simplified Overloads
Instead of dozens of overloaded constructors to cover different initialization scenarios, you provide a handful of well-named static methods (e.g. WithTitle(), WithSubtitle()), each encapsulating its own logic and defaults.
Validation and Caching
Factories can centralize validation (throw early on bad arguments), perform expensive setup only once (returning a shared singleton), or even pool and reuse objects.

Static Factory Methods vs Constructors

Aspect	Constructors	Static Factory Methods
Naming & Discoverability	No name beyond class name	Method names describe purpose
Return Flexibility	Fixed to class it belongs to	Can return subtypes or cached refs
Overload Explosion	Many overloads → unreadable	Distinct methods → self-documented
Default Configuration Logic	Scattered in callers	Encapsulated in one place
Conditional Instantiation	Hard to vary at runtime	Easy to branch inside factory

Divooka's Use Case: Organizing Tools by Category

In Divooka, every static method in a class becomes a toolbox entry - with the class name serving as the toolbox category. By grouping related factory methods inside dedicated static class containers (e.g. PlotConfigurations), Divooka can automatically:

Discover all available tools at startup
Organize them under logical headings (one class = one category)
Expose named methods like ConfigureTextDisplayWithTitleAndSubtitle directly to end-users

Were these methods instead constructors on each configuration type, Divooka would lack a natural grouping: you'd have to scan every class for all its constructors, losing that simple "category = class" mapping based on usage.

Case Study: ASP .NET Core's Builder-Based Factory Approach

ASP .NET Core also relies heavily on factories - but often via the builder pattern:

Host.CreateDefaultBuilder(args)
    .ConfigureServices((ctx, services) =>
    {
        services.AddDbContext<MyDbContext>(opts => 
            opts.UseSqlServer(connectionString));
        services.AddSingleton<IMyService, MyService>();
    })
    .Build();

Here the "factory" is implicit in the IHostBuilder:

Fluent configuration methods (ConfigureServices, UseUrls, etc.) collect options
The final Build() call manufactures the fully wired IHost
You get immutability until build time, plus a clear sequence of configuration steps

Comparing Static vs. Builder Factories

Feature	Static Factory Methods	Builder Pattern (ASP NET Core)
Discovery	Simple reflection on static classes	Extension-method based; discoverable by IDE but less obvious at runtime
Grouping	One class = one category	Spread across many fluent calls
Extensibility	Add new methods in classes	Add new extension methods on interfaces
Configurability	Encapsulated per-method logic	Centralized in a mutable builder state
Readability	Direct: `MyFactory.Create(…)`	Fluent chaining: `builder.Configure…`

In many small‐to‐medium scenarios, static factory methods win on simplicity: you immediately see each creation scenario, and end-users can invoke exactly what they need. In very large frameworks (like ASP .NET Core), the builder shines by aggregating dozens of configuration concerns into a single, coherent pipeline before creating the final product.

Conclusion

The Factory Pattern - whether via simple static methods or a full builder API - decouples what you need from how it's built. Choosing static factory methods:

Keeps creation logic in one readable place
Leverages method naming to self-document different initialization paths
Allows frameworks like Divooka to auto-discover and categorize tools
Avoids constructor overload chaos

Meanwhile, builder-style factories excel when you have large configuration graphs to assemble in a defined sequence. By understanding both approaches, you can pick the pattern that best balances clarity, flexibility, and discoverability in your own projects.