FractalDataWorks.Commands.Abstractions 0.9.5-alpha.1008

FractalDataWorks.Commands.Abstractions

Comprehensive command infrastructure providing type-safe command definitions, translation capabilities, and execution metadata for universal data operations across different backends.

Overview

FractalDataWorks.Commands.Abstractions defines the command architecture that enables the framework's Universal Data Access pattern. It provides interfaces and base classes for:

• Command Type Definitions - Static metadata about command capabilities
• Command Translators - Converting commands between formats (LINQ→SQL, Expression→HTTP)
• Command Categories - Classification system (Query, Mutation, Bulk operations)
• Translation Context - Metadata for command translation
• Command Messages - Structured feedback for command operations

Target Frameworks: .NET Standard 2.0, .NET 10.0 Dependencies: FractalDataWorks.Abstractions, FractalDataWorks.Collections, FluentValidation

Key Concepts

Command vs CommandType

IGenericCommand (runtime instance):

• Represents a specific command execution
• Contains CommandId, CreatedAt, CommandType properties
• Defined in FractalDataWorks.Abstractions
• Used for actual command execution

IGenericCommandType (static metadata):

• Represents command type definition (singleton)
• Contains metadata: Category, SupportedTranslators, batching capabilities
• Registered via TypeCollections for discovery
• Used for routing and capability checking

Core Interfaces

IGenericCommand (Runtime Instance)

public interface IGenericCommand
{
    string CommandType { get; }
    IGenericCommandCategory Category { get; }
    IGenericResult<ValidationResult> Validate();
}

public interface IGenericCommand<T> : IGenericCommand
{
    T? Payload { get; init; }
    new IGenericResult<ValidationResult> Validate();
}

Usage: Runtime command instances with payloads:

public class SqlQueryCommand : IGenericCommand<QueryPayload>
{
    public string CommandType => "SqlQuery";
    public IGenericCommandCategory Category => CommandCategories.Query;
    public QueryPayload? Payload { get; init; }

    public IGenericResult<ValidationResult> Validate()
    {
        // FluentValidation logic
    }
}

IGenericCommandType (Type Metadata)

public interface IGenericCommandType : ITypeOption<int, CommandTypeBase>
{
    IGenericCommandCategory CommandCategory { get; }
    IReadOnlyCollection<ITranslatorType> SupportedTranslators { get; }
    bool SupportsBatching { get; }
    bool SupportsPipelining { get; }
    int MaxBatchSize { get; }
}

Usage: Static type definitions in TypeCollections:

[TypeOption(typeof(CommandTypes), "SqlQuery")]
public sealed class SqlQueryCommandType() : CommandTypeBase(1, "SqlQuery")
{
    public override IGenericCommandCategory CommandCategory => CommandCategories.Query;

    public override IReadOnlyCollection<ITranslatorType> SupportedTranslators =>
        new[] { TranslatorTypes.SqlTranslator, TranslatorTypes.LinqTranslator };

    public override bool SupportsBatching => true;
    public override int MaxBatchSize => 100;
}

IGenericCommandTranslator

public interface IGenericCommandTranslator
{
    ITranslatorType TranslatorType { get; }

    IGenericResult<bool> CanTranslate(Expression expression);

    IGenericResult<IGenericCommand> Translate(
        Expression expression,
        ITranslationContext? context = null);

    IGenericResult<IGenericCommand> TranslateCommand(
        IGenericCommand command,
        IDataFormat targetFormat);

    Task<IGenericResult<IGenericCommand>> Optimize(
        IGenericCommand command,
        CancellationToken cancellationToken = default);

    IGenericResult<CommandCostEstimate> EstimateCost(IGenericCommand command);
}

Responsibilities:

• Translation: Convert LINQ expressions to backend commands
• Cross-Format: Translate between command formats (SQL↔HTTP↔GraphQL)
• Optimization: Improve translated commands for performance
• Cost Estimation: Predict execution cost before running

Example: SQL Translator

public class SqlCommandTranslator : IGenericCommandTranslator
{
    public ITranslatorType TranslatorType => TranslatorTypes.SqlTranslator;

    public IGenericResult<bool> CanTranslate(Expression expression)
    {
        // Check if expression can be translated to SQL
        return GenericResult<bool>.Success(IsSqlCompatible(expression));
    }

    public IGenericResult<IGenericCommand> Translate(
        Expression expression,
        ITranslationContext? context = null)
    {
        try
        {
            var sql = ConvertExpressionToSql(expression, context);
            return GenericResult<IGenericCommand>.Success(
                new SqlQueryCommand { Payload = sql });
        }
        catch (Exception ex)
        {
            return GenericResult<IGenericCommand>.Failure(
                $"Translation failed: {ex.Message}");
        }
    }

    public IGenericResult<CommandCostEstimate> EstimateCost(IGenericCommand command)
    {
        var estimate = new CommandCostEstimate
        {
            EstimatedRows = AnalyzeQuery(command),
            EstimatedCost = CalculateCost(command)
        };
        return GenericResult<CommandCostEstimate>.Success(estimate);
    }
}

TypeCollections

CommandTypes Collection

[TypeCollection(typeof(CommandTypeBase), typeof(IGenericCommandType), typeof(CommandTypes))]
public abstract partial class CommandTypes : TypeCollectionBase<CommandTypeBase, IGenericCommandType>
{
    // Source generator populates with discovered command types
}

// Usage
var queryType = CommandTypes.ById(1);  // Get SqlQueryCommandType
var allTypes = CommandTypes.All();      // All registered command types

CommandCategories Collection

[TypeCollection(typeof(CommandCategoryBase), typeof(IGenericCommandCategory), typeof(CommandCategories))]
public abstract partial class CommandCategories :
    TypeCollectionBase<CommandCategoryBase, IGenericCommandCategory>
{
}

// Built-in categories
public static IGenericCommandCategory Query => CommandCategories.Query;
public static IGenericCommandCategory Mutation => CommandCategories.Mutation;
public static IGenericCommandCategory Bulk => CommandCategories.Bulk;

Categories Define:

• Query: Read-only operations (SELECT, GET)
• Mutation: State-changing operations (INSERT, UPDATE, DELETE, POST, PUT)
• Bulk: Batch operations with multiple commands

TranslatorTypes Collection

[TypeCollection(typeof(TranslatorTypeBase), typeof(ITranslatorType), typeof(TranslatorTypes))]
public abstract partial class TranslatorTypes :
    TypeCollectionBase<TranslatorTypeBase, ITranslatorType>
{
}

// Usage
var sqlTranslator = TranslatorTypes.SqlTranslator;
var linqTranslator = TranslatorTypes.LinqTranslator;

Translation Context

ITranslationContext

public interface ITranslationContext
{
    IDataSchema? SourceSchema { get; }
    IDataSchema? TargetSchema { get; }
    IDataFormat SourceFormat { get; }
    IDataFormat TargetFormat { get; }
    IDictionary<string, object> Metadata { get; }
}

Usage: Provides metadata during translation

var context = new TranslationContext
{
    SourceSchema = databaseSchema,
    TargetSchema = apiSchema,
    SourceFormat = DataFormats.Linq,
    TargetFormat = DataFormats.Sql,
    Metadata = new Dictionary<string, object>
    {
        ["Timeout"] = 30,
        ["MaxRows"] = 1000
    }
};

var result = translator.Translate(expression, context);

Command Execution Flow

Translation Capabilities

public sealed class TranslationCapabilities
{
    public bool SupportsJoins { get; init; }
    public bool SupportsAggregates { get; init; }
    public bool SupportsSubqueries { get; init; }
    public bool SupportsPaging { get; init; }
    public bool SupportsFiltering { get; init; }
    public bool SupportsSorting { get; init; }
    public int MaxBatchSize { get; init; }
    public IReadOnlyList<string> SupportedFunctions { get; init; }
}

Usage: Declare translator capabilities

public class SqlTranslatorType : TranslatorTypeBase
{
    public override TranslationCapabilities Capabilities => new()
    {
        SupportsJoins = true,
        SupportsAggregates = true,
        SupportsSubqueries = true,
        SupportsPaging = true,
        MaxBatchSize = 100,
        SupportedFunctions = new[] { "COUNT", "SUM", "AVG", "MAX", "MIN" }
    };
}

Command Cost Estimation

public sealed class CommandCostEstimate
{
    public long EstimatedRows { get; init; }
    public decimal EstimatedCost { get; init; }
    public TimeSpan EstimatedDuration { get; init; }
    public int ComplexityScore { get; init; }
    public IDictionary<string, object> AdditionalMetrics { get; init; }
}

Usage: Estimate before execution

var estimate = translator.EstimateCost(command);
if (estimate.Value.EstimatedRows > 1_000_000)
{
    // Warn user or optimize query
}

Command Messages

CommandMessage

public sealed class CommandMessage : IDataMessage
{
    public string Message { get; init; }
    public string? Code { get; init; }
    public string? Source { get; init; }
    public MessageSeverity Severity { get; init; }
}

Specialized Messages

TranslationFailedMessage:

public sealed class TranslationFailedMessage : CommandMessage
{
    public Expression? FailedExpression { get; init; }
    public string TranslatorType { get; init; }
    public Exception? Exception { get; init; }
}

UnsupportedCommandMessage:

public sealed class UnsupportedCommandMessage : CommandMessage
{
    public string CommandType { get; init; }
    public string TranslatorType { get; init; }
    public IReadOnlyList<string> SupportedCommands { get; init; }
}

CommandNullMessage:

public sealed class CommandNullMessage : CommandMessage
{
    public CommandNullMessage()
    {
        Message = "Command cannot be null";
        Severity = MessageSeverity.Error;
        Code = "CMD_NULL";
    }
}

Command Logging

CommandLog

public sealed class CommandLog
{
    public Guid CommandId { get; init; }
    public string CommandType { get; init; }
    public DateTime StartTime { get; init; }
    public DateTime? EndTime { get; init; }
    public TimeSpan? Duration { get; init; }
    public bool IsSuccess { get; init; }
    public IReadOnlyList<IGenericMessage> Messages { get; init; }
    public IDictionary<string, object> Metadata { get; init; }
}

Usage: Track command execution

var log = new CommandLog
{
    CommandId = command.CommandId,
    CommandType = command.CommandType,
    StartTime = DateTime.UtcNow,
    Metadata = new Dictionary<string, object>
    {
        ["User"] = userId,
        ["Query"] = sqlCommand.Payload
    }
};

// After execution
log = log with
{
    EndTime = DateTime.UtcNow,
    Duration = executionTime,
    IsSuccess = result.IsSuccess,
    Messages = result.Messages.ToList()
};

Command Execution Patterns

Translation Pipeline

public async Task<IGenericResult<T>> ExecuteQueryAsync<T>(Expression expression)
{
    // 1. Find translator
    var translator = FindTranslator(expression);
    if (translator == null)
        return GenericResult<T>.Failure(new TranslatorNotFoundMessage());

    // 2. Validate translation capability
    var canTranslate = translator.CanTranslate(expression);
    if (!canTranslate.Value)
        return GenericResult<T>.Failure(new UnsupportedCommandMessage());

    // 3. Translate expression
    var commandResult = translator.Translate(expression, context);
    if (commandResult.IsFailure)
        return GenericResult<T>.Failure(new TranslationFailedMessage());

    // 4. Optimize command
    var optimized = await translator.Optimize(commandResult.Value);
    var command = optimized.IsSuccess ? optimized.Value : commandResult.Value;

    // 5. Execute command
    return await service.Execute<T>(command, cancellationToken);
}

Batching Support

public async Task<IGenericResult> ExecuteBatchAsync(IEnumerable<IGenericCommand> commands)
{
    var commandList = commands.ToList();

    // Check batching support
    var commandType = CommandTypes.Name(commandList[0].CommandType);
    if (!commandType.SupportsBatching)
        return GenericResult.Failure("Command type does not support batching");

    // Validate batch size
    if (commandList.Count > commandType.MaxBatchSize)
        return GenericResult.Failure($"Batch size exceeds maximum of {commandType.MaxBatchSize}");

    // Execute batch
    var batchCommand = CreateBatchCommand(commandList);
    return await service.Execute(batchCommand, cancellationToken);
}

Best Practices

1. Use Railway-Oriented Programming: Always return IGenericResult from translators
2. Validate Before Translation: Check CanTranslate() before calling Translate()
3. Optimize Translated Commands: Use Optimize() for better performance
4. Estimate Costs: Check EstimateCost() for expensive operations
5. Batch When Possible: Use batching for multiple similar commands
6. Provide Context: Include translation context for better results
7. Log Commands: Use CommandLog for debugging and auditing
8. Handle Failures Gracefully: Use structured messages for clear feedback

Dependencies

• FractalDataWorks.Abstractions: Core interfaces (IGenericCommand, IGenericService)
• FractalDataWorks.Collections: TypeCollections infrastructure
• FractalDataWorks.Results: Railway-Oriented Programming support
• FractalDataWorks.Data.Abstractions: Data format and schema interfaces
• FluentValidation: Command validation support

Summary

FractalDataWorks.Commands.Abstractions provides a comprehensive command infrastructure that enables Universal Data Access through type-safe command definitions, pluggable translators, and execution metadata. The combination of TypeCollections-based discovery, Railway-Oriented error handling, and translation capabilities makes it possible to write backend-agnostic data operations that work across SQL, REST, GraphQL, and other data sources.