FractalDataWorks.Commands.Data.Extensions 0.9.0-alpha.1011.ged0a6c6e98

FractalDataWorks.Commands.Data.Extensions

Extension methods for data command operations providing fluent APIs for command building, validation, and execution. Enhances Commands.Data with builder patterns and convenience methods.

Overview

This package provides extension methods and fluent APIs that simplify working with data commands. It extends Commands.Data with:

• Fluent Command Builders: Chain methods to construct complex commands
• Validation Extensions: Simplified validation workflows
• Execution Extensions: Convenient command execution patterns
• Transformation Pipelines: Transform and compose commands
• Result Mapping: Map command results to different types

Target Frameworks: .NET Standard 2.0, .NET 10.0 Dependencies: FractalDataWorks.Commands.Data, FractalDataWorks.Results

Key Extension Categories

Command Builder Extensions

Fluent APIs for constructing data commands:

var command = dataCommand
    .WithParameter("userId", userId)
    .WithParameter("status", "Active")
    .WithTimeout(TimeSpan.FromSeconds(30))
    .WithRetry(maxAttempts: 3)
    .Build();

Validation Extensions

Simplified validation workflows:

var validationResult = command
    .ValidateRequired()
    .ValidateParameters()
    .ValidateSchema(schema)
    .GetResult();

if (validationResult.IsFailure)
{
    // Handle validation errors
}

Execution Extensions

Convenient execution patterns:

// Execute and map result
var users = await dataCommand
    .ExecuteAsync<User>(service, cancellationToken)
    .MapResult(users => users.OrderBy(u => u.Name))
    .ToListAsync();

// Execute with retry
var result = await dataCommand
    .ExecuteWithRetry(service, maxAttempts: 3, cancellationToken);

Usage Patterns

Building Complex Commands

public IGenericCommand BuildUserQuery(int departmentId, string searchTerm)
{
    return new QueryCommand()
        .WithParameter("departmentId", departmentId)
        .WithParameter("searchTerm", $"%{searchTerm}%")
        .WithPaging(page: 1, pageSize: 50)
        .WithSorting("LastName", ascending: true)
        .WithProjection("Id", "FirstName", "LastName", "Email")
        .Build();
}

Validation Pipelines

var result = command
    .ValidateNotNull()
    .ValidateCommandType()
    .ValidatePayload(payload => payload != null)
    .ValidateCustom(cmd => cmd.Timeout > TimeSpan.Zero, "Timeout must be positive")
    .Execute();

if (result.IsSuccess)
{
    await service.Execute(command, cancellationToken);
}

Result Transformation

var userNames = await queryCommand
    .ExecuteAsync<User>(service, cancellationToken)
    .MapSuccess(users => users.Select(u => u.FullName))
    .OnFailure(error => logger.LogError(error))
    .GetValueOr(Array.Empty<string>());

Extension Method Patterns

IGenericCommand Extensions

public static class GenericCommandExtensions
{
    public static IGenericCommand WithParameter(
        this IGenericCommand command,
        string name,
        object value);

    public static IGenericCommand WithTimeout(
        this IGenericCommand command,
        TimeSpan timeout);

    public static Task<IGenericResult<T>> ExecuteAsync<T>(
        this IGenericCommand command,
        IGenericService service,
        CancellationToken cancellationToken = default);

    public static IGenericResult<bool> IsValid(
        this IGenericCommand command);
}

IGenericResult Extensions

public static class GenericResultExtensions
{
    public static IGenericResult<TOut> Map<TIn, TOut>(
        this IGenericResult<TIn> result,
        Func<TIn, TOut> mapper);

    public static IGenericResult<T> OnSuccess<T>(
        this IGenericResult<T> result,
        Action<T> action);

    public static IGenericResult<T> OnFailure<T>(
        this IGenericResult<T> result,
        Action<string> action);

    public static T GetValueOr<T>(
        this IGenericResult<T> result,
        T defaultValue);
}

Best Practices

1. Use Fluent Builders: Chain methods for readable command construction
2. Validate Early: Use validation extensions before execution
3. Handle Failures: Use OnFailure for consistent error handling
4. Map Results: Transform results inline instead of separate steps
5. Leverage Defaults: Use GetValueOr for safe default handling

Dependencies

• FractalDataWorks.Commands.Data: Core command data types
• FractalDataWorks.Results: Result pattern support
• FractalDataWorks.Abstractions: Base interfaces

Summary

FractalDataWorks.Commands.Data.Extensions provides fluent APIs and extension methods that make working with data commands more convenient and readable. The builder patterns, validation pipelines, and result transformations enable cleaner, more maintainable command-based code.