FractalDataWorks.Commands.Abstractions 0.6.0-rc.1

FractalDataWorks.Commands.Abstractions

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 to SQL, Expression to 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, FractalDataWorks.Data.Abstractions, FractalDataWorks.Messages, FractalDataWorks.Results

Key Concepts

Command vs CommandType

IGenericCommand (runtime instance):

• Represents a specific command execution
• Contains CommandId, CreatedAt, CommandType, Category 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)

From IGenericCommand.cs:14-51 in FractalDataWorks.Abstractions:

public interface IGenericCommand
{
    Guid CommandId { get; }
    DateTime CreatedAt { get; }
    string CommandType { get; }
    string Category { get; }
}

IGenericCommandType (Type Metadata)

From ICommandType.cs:14-44:

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

CommandTypeBase

From CommandTypeBase.cs:30-87:

public abstract class CommandTypeBase : TypeOptionBase<int, CommandTypeBase>, IGenericCommandType
{
    public IGenericCommandCategory CommandCategory { get; }
    public IReadOnlyCollection<ITranslatorType> SupportedTranslators { get; }
    public bool SupportsBatching { get; }
    public bool SupportsPipelining { get; }
    public int MaxBatchSize { get; }
    public virtual Type CommandInterfaceType => typeof(IGenericCommand);

    protected CommandTypeBase(
        int id,
        string name,
        string description,
        IGenericCommandCategory category,
        IReadOnlyCollection<ITranslatorType> supportedTranslators,
        bool supportsBatching = false,
        bool supportsPipelining = false,
        int maxBatchSize = 1)
        : base(id, name, description)
    {
        CommandCategory = category;
        SupportedTranslators = supportedTranslators;
        SupportsBatching = supportsBatching;
        SupportsPipelining = supportsPipelining;
        MaxBatchSize = maxBatchSize;
    }
}

IGenericCommandTranslator

From ICommandTranslator.cs:18-61:

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);
}

TypeCollections

CommandTypes Collection

From CommandTypes.cs:15-18:

[TypeCollection(typeof(CommandTypeBase), typeof(IGenericCommandType), typeof(CommandTypes))]
public abstract partial class CommandTypes : TypeCollectionBase<CommandTypeBase, IGenericCommandType>
{
}

Usage:

// Lookup by ID or name (source generator creates these methods)
var queryType = CommandTypes.ById(1);
var allTypes = CommandTypes.All();

CommandCategories Collection

From CommandCategories.cs:14-17:

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

IGenericCommandCategory

From ICommandCategory.cs:13-43:

public interface IGenericCommandCategory : ITypeOption<int, CommandCategoryBase>
{
    bool RequiresTransaction { get; }
    bool SupportsStreaming { get; }
    bool IsCacheable { get; }
    bool IsMutation { get; }
    int ExecutionPriority { get; }
}

TranslatorTypes Collection

From TranslatorTypes.cs:15-45:

[TypeCollection(typeof(TranslatorTypeBase), typeof(ITranslatorType), typeof(TranslatorTypes))]
public abstract partial class TranslatorTypes : TypeCollectionBase<TranslatorTypeBase, ITranslatorType>
{
    public static ITranslatorType[] FindTranslators(IDataFormat sourceFormat, IDataFormat targetFormat)
    {
        var translators = new System.Collections.Generic.List<ITranslatorType>();

        foreach (var translator in All())
        {
            if (translator.SourceFormat.Id == sourceFormat.Id &&
                translator.TargetFormat.Id == targetFormat.Id)
            {
                translators.Add(translator);
            }
        }

        translators.Sort((a, b) => b.Priority.CompareTo(a.Priority));
        return translators.ToArray();
    }
}

Translation Context

ITranslationContext

From ITranslationContext.cs:13-56:

public interface ITranslationContext
{
    IDataSchema? SourceSchema { get; }
    IDataSchema? TargetSchema { get; }
    IReadOnlyDictionary<string, object> Hints { get; }
    int TranslationTimeoutMs { get; }
    bool PreferPerformance { get; }
    bool IncludeDebugInfo { get; }
    string? TargetEnvironment { get; }
}

Translation Capabilities

From TranslationCapabilities.cs:10-109:

public sealed class TranslationCapabilities
{
    public bool SupportsProjection { get; init; }
    public bool SupportsFiltering { get; init; }
    public bool SupportsOrdering { get; init; }
    public bool SupportsPaging { get; init; }
    public bool SupportsJoins { get; init; }
    public bool SupportsGrouping { get; init; }
    public bool SupportsAggregation { get; init; }
    public bool SupportsSubqueries { get; init; }
    public bool SupportsTransactions { get; init; }
    public bool SupportsBulkOperations { get; init; }
    public bool SupportsParameterization { get; init; }
    public int MaxComplexityLevel { get; init; } = 5;

    public static TranslationCapabilities Full => new()
    {
        SupportsProjection = true,
        SupportsFiltering = true,
        SupportsOrdering = true,
        SupportsPaging = true,
        SupportsJoins = true,
        SupportsGrouping = true,
        SupportsAggregation = true,
        SupportsSubqueries = true,
        SupportsTransactions = true,
        SupportsBulkOperations = true,
        SupportsParameterization = true,
        MaxComplexityLevel = 10
    };

    public static TranslationCapabilities Basic => new()
    {
        SupportsProjection = true,
        SupportsFiltering = true,
        SupportsOrdering = true,
        SupportsPaging = false,
        SupportsJoins = false,
        SupportsGrouping = false,
        SupportsAggregation = false,
        SupportsSubqueries = false,
        SupportsTransactions = false,
        SupportsBulkOperations = false,
        SupportsParameterization = true,
        MaxComplexityLevel = 3
    };
}

Command Cost Estimation

From CommandCostEstimate.cs:13-86:

public sealed class CommandCostEstimate
{
    public long EstimatedRows { get; init; }
    public int EstimatedTimeMs { get; init; }
    public long EstimatedMemoryBytes { get; init; }
    public long EstimatedNetworkBytes { get; init; }
    public int EstimatedIoOperations { get; init; }
    public int ComplexityScore { get; init; }
    public bool IsStatisticsBased { get; init; }
    public double Confidence { get; init; }

    public static CommandCostEstimate Minimal => new()
    {
        EstimatedRows = 1,
        EstimatedTimeMs = 1,
        EstimatedMemoryBytes = 1024,
        EstimatedNetworkBytes = 256,
        EstimatedIoOperations = 1,
        ComplexityScore = 1,
        IsStatisticsBased = false,
        Confidence = 0.5
    };

    public static CommandCostEstimate Unknown => new()
    {
        EstimatedRows = -1,
        EstimatedTimeMs = -1,
        EstimatedMemoryBytes = -1,
        EstimatedNetworkBytes = -1,
        EstimatedIoOperations = -1,
        ComplexityScore = -1,
        IsStatisticsBased = false,
        Confidence = 0.0
    };
}

Command Messages

CommandMessage Base

From Messages/CommandMessage.cs:13-28:

[MessageCollection("CommandMessages")]
public abstract class CommandMessage : MessageTemplate<MessageSeverity>, IGenericMessage
{
    protected CommandMessage(int id, string name, MessageSeverity severity,
        string message, string? code = null)
        : base(id, name, severity, message, code, "Command", null, null)
    {
    }
}

CommandNullMessage

From Messages/CommandNullMessage.cs:8-17:

public sealed class CommandNullMessage : CommandMessage
{
    public CommandNullMessage()
        : base(1001, "CommandNull", MessageSeverity.Error,
               "Command cannot be null", "CMD_NULL")
    {
    }
}

TranslationFailedMessage

From Messages/TranslationFailedMessage.cs:8-24:

public sealed class TranslationFailedMessage : CommandMessage
{
    public string Reason { get; }

    public TranslationFailedMessage(string reason)
        : base(1002, "TranslationFailed", MessageSeverity.Error,
               $"Failed to translate command: {reason}", "CMD_TRANS_001")
    {
        Reason = reason;
    }
}

UnsupportedCommandMessage

From Messages/UnsupportedCommandMessage.cs:8-24:

public sealed class UnsupportedCommandMessage : CommandMessage
{
    public string CommandType { get; }

    public UnsupportedCommandMessage(string commandType)
        : base(1003, "UnsupportedCommand", MessageSeverity.Error,
               $"Command type '{commandType}' is not supported", "CMD_UNSUP")
    {
        CommandType = commandType;
    }
}

TranslatorNotFoundMessage

From Messages/TranslatorNotFoundMessage.cs:8-31:

public sealed class TranslatorNotFoundMessage : CommandMessage
{
    public string SourceFormat { get; }
    public string TargetFormat { get; }

    public TranslatorNotFoundMessage(string sourceFormat, string targetFormat)
        : base(1004, "TranslatorNotFound", MessageSeverity.Error,
               $"No translator found for converting '{sourceFormat}' to '{targetFormat}'", "CMD_TRANS_404")
    {
        SourceFormat = sourceFormat;
        TargetFormat = targetFormat;
    }
}

Command Logging

From Logging/CommandLogger.cs:11-282:

public static partial class CommandLogger
{
    [MessageLogging(
        EventId = 5001,
        Level = LogLevel.Debug,
        Message = "Executing command {commandType} with ID {commandId}")]
    public static partial IGenericMessage CommandExecutionStarted(
        ILogger logger,
        string commandType,
        Guid commandId);

    [MessageLogging(
        EventId = 5002,
        Level = LogLevel.Information,
        Message = "Command {commandType} completed successfully in {elapsedMs}ms")]
    public static partial IGenericMessage CommandExecutionCompleted(
        ILogger logger,
        string commandType,
        long elapsedMs);

    [MessageLogging(
        EventId = 5003,
        Level = LogLevel.Error,
        Message = "Command {commandType} failed: {errorMessage}")]
    public static partial IGenericMessage CommandExecutionFailed(
        ILogger logger,
        Exception exception,
        string commandType,
        string errorMessage);

    [MessageLogging(
        EventId = 5020,
        Level = LogLevel.Debug,
        Message = "Translating command from {sourceFormat} to {targetFormat}")]
    public static partial IGenericMessage TranslationStarted(
        ILogger logger,
        string sourceFormat,
        string targetFormat);

    [MessageLogging(
        EventId = 5031,
        Level = LogLevel.Warning,
        Message = "No translator found for {sourceFormat} to {targetFormat}")]
    public static partial IGenericMessage TranslatorNotFound(
        ILogger logger,
        string sourceFormat,
        string targetFormat);
}

Best Practices

1. Use Railway-Oriented Programming: Return IGenericResult from translators
2. Validate Before Translation: Check CanTranslate() before calling Translate()
3. Use Cost Estimation: Check EstimateCost() before expensive operations
4. Leverage TypeCollections: Use CommandTypes.ByName() for type lookup
5. Provide Context: Include translation context with hints for better results
6. Use MessageLogging: Use CommandLogger for structured logging that returns messages
7. Handle Failures Gracefully: Use structured message types for clear feedback

Dependencies

• FractalDataWorks.Abstractions: Core interfaces (IGenericCommand)
• FractalDataWorks.Collections: TypeCollections infrastructure
• FractalDataWorks.Results: Railway-Oriented Programming support
• FractalDataWorks.Data.Abstractions: Data format and schema interfaces
• FractalDataWorks.Messages: Message infrastructure
• FractalDataWorks.MessageLogging: Source-generated logging

Related Packages

• FractalDataWorks.Abstractions - Core interfaces
• FractalDataWorks.Collections - TypeCollection infrastructure
• FractalDataWorks.Results - Railway-Oriented Programming