FractalDataWorks.Commands.Data.Abstractions 0.6.0-rc.1

FractalDataWorks.Commands.Data.Abstractions

Core abstractions for universal data commands in the FractalDataWorks Developer Kit.

Overview

This project provides abstractions for data commands that work across different data store types (SQL, REST, GraphQL, File, etc.). The same IDataCommand can execute against different backend stores by routing to the appropriate connection.

Core Concepts

• IDataCommand - Universal command interface representing data operations
• IDataCommandTranslator<TCommand> - Converts universal commands to domain-specific commands (SQL, REST, etc.)
• DataCommandTranslators - TypeCollection for compile-time and runtime translator registration
• IConnectionCommand - Marker interface for translated, connection-specific commands

Architecture (Built-In Translator Pattern)

IDataCommand (universal)
    |
DataGateway (routes by ConnectionName)
    |
IDataConnection (owns translator)
    +-- Translator.Translate(IDataCommand, IStorageContainer)
    +-- Returns IConnectionCommand (e.g., HttpConnectionCommand)
    +-- Connection executes domain-specific command

The translator uses IStorageContainer schema metadata (fields, roles, converters) for intelligent query building.

Core Interfaces

IDataCommand

Base interface for all data commands. Extends IGenericCommand from the Commands.Abstractions project.

From IDataCommand.cs:20-45:

public interface IDataCommand : IGenericCommand
{
    /// <summary>
    /// Gets the container name (table, collection, endpoint, file path).
    /// </summary>
    string ContainerName { get; }

    /// <summary>
    /// Gets the connection name to route this command to.
    /// DataGateway uses this to select which IDataConnection should execute the command.
    /// </summary>
    string ConnectionName { get; }

    /// <summary>
    /// Gets metadata for the command (connection hints, caching, etc.).
    /// </summary>
    IReadOnlyDictionary<string, object> Metadata { get; }
}

Generic Variants:

From IDataCommand.cs:103-107:

public interface IDataCommand<TResult> : IDataCommand
{
    // Marker interface for type-safe result
    // No additional members needed - type parameter provides compile-time safety
}

From IDataCommand.cs:78-85:

public interface IDataCommand<TResult, TInput> : IDataCommand<TResult>, IDataCommandWithInput
{
    /// <summary>
    /// Gets the input data for this command.
    /// </summary>
    TInput Data { get; }
}

IDataCommandTranslator<TCommand>

Interface for translating universal commands to domain-specific commands. The generic type parameter specifies the output command type (e.g., SqlCommand, HttpRequestMessage).

From IDataCommandTranslator.cs:36-55:

public interface IDataCommandTranslator<TCommand> : ITypeOption<int>
{
    /// <summary>
    /// Gets the domain name this translator targets (Sql, Rest, File, GraphQL, etc.).
    /// </summary>
    string DomainName { get; }

    /// <summary>
    /// Translates a data command to a connection-specific command.
    /// Uses container schema for intelligent query building (field roles, types, converters).
    /// </summary>
    Task<IGenericResult<TCommand>> Translate(
        IDataCommand command,
        IStorageContainer container,
        CancellationToken cancellationToken = default);
}

The IStorageContainer parameter provides schema metadata that translators use for building queries with proper field names, types, and converters.

DataCommandTranslators (TypeCollection)

Hybrid TypeCollection supporting both compile-time discovery and runtime registration.

From DataCommandTranslators.cs:39-41:

[TypeCollection(typeof(DataCommandTranslatorBase<>), typeof(IDataCommandTranslator<>), typeof(DataCommandTranslators))]
[ExcludeFromCodeCoverage]
public abstract partial class DataCommandTranslators : TypeCollectionBase<DataCommandTranslatorBase<object>, IDataCommandTranslator<object>>

Runtime Registration:

From DataCommandTranslators.cs:67-85:

/// <summary>
/// Registers a translator at runtime (called by connection types during registration).
/// </summary>
public static void Register(string name, Type translatorType)
{
    if (string.IsNullOrWhiteSpace(name))
        throw new ArgumentException("Translator name cannot be null or whitespace", nameof(name));

    if (translatorType == null)
        throw new ArgumentNullException(nameof(translatorType));

    // Check if the type implements IDataCommandTranslator<T> for some T
    var implementsTranslator = translatorType.GetInterfaces()
        .Any(i => i.IsGenericType && i.GetGenericTypeDefinition() == typeof(IDataCommandTranslator<>));

    if (!implementsTranslator)
        throw new ArgumentException($"Type {translatorType.Name} must implement IDataCommandTranslator<TCommand>", nameof(translatorType));

    _runtimeTranslators[name] = translatorType;
}

Lookup Methods:

From DataCommandTranslators.cs:93-108:

public static Type? GetTranslatorType(string domainName)
{
    if (string.IsNullOrWhiteSpace(domainName))
        return null;

    // Check runtime-registered translators
    if (_runtimeTranslators.TryGetValue(domainName, out var runtimeType))
        return runtimeType;

    return null;
}

IConnectionCommand

Marker interface for translated, connection-specific commands. This is what translators produce.

From IConnectionCommand.cs:24-26:

public interface IConnectionCommand : IGenericCommand
{
}

HttpConnectionCommand

A concrete implementation for HTTP-based connection commands.

From HttpConnectionCommand.cs:21-84:

public sealed class HttpConnectionCommand : IConnectionCommand
{
    public HttpConnectionCommand(
        HttpMethod method,
        string relativePath,
        IReadOnlyDictionary<string, string>? queryParameters = null,
        string? body = null,
        IReadOnlyDictionary<string, string>? headers = null)
    {
        Method = method ?? throw new ArgumentNullException(nameof(method));
        RelativePath = relativePath ?? throw new ArgumentNullException(nameof(relativePath));
        QueryParameters = queryParameters ?? new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase);
        Body = body;
        Headers = headers ?? new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase);
        CommandId = Guid.NewGuid();
        CreatedAt = DateTime.UtcNow;
    }

    public HttpMethod Method { get; }
    public string RelativePath { get; }
    public IReadOnlyDictionary<string, string> QueryParameters { get; }
    public string? Body { get; }
    public IReadOnlyDictionary<string, string> Headers { get; }
    public Guid CommandId { get; }
    public DateTime CreatedAt { get; }
    public string CommandType => "HttpConnection";
    public string Category => "Connection";
}

Project Structure

FractalDataWorks.Commands.Data.Abstractions/
+-- Commands/
|   +-- IDataCommand.cs              # Base command interface (includes generic variants)
|   +-- IConnectionCommand.cs        # Marker for translated commands
|   +-- IFilterableCommand.cs        # Commands with WHERE clause support
|   +-- IQueryCommand.cs             # Full query command interface
|   +-- ICompositeDataCommand.cs     # Composite command interface
|   +-- DataCommandBase.cs           # Base implementations (non-generic and generic variants)
|   +-- DataCommands.cs              # TypeCollection for command types
|   +-- HttpConnectionCommand.cs     # HTTP connection command implementation
+-- Translators/
|   +-- IDataCommandTranslator.cs    # Generic translator interface
|   +-- DataCommandTranslatorBase.cs # Base translator implementation
|   +-- DataCommandTranslators.cs    # TypeCollection for translator discovery
+-- Expressions/
|   +-- IJoinDefinition.cs           # Join relationship definition
+-- Execution/
|   +-- IResultMerger.cs             # Result merging interface
+-- ExecutionStrategies/
|   +-- ExecutionStrategyBase.cs     # Base execution strategy
|   +-- ExecutionStrategies.cs       # TypeCollection for strategies
|   +-- SequentialExecutionStrategy.cs
|   +-- ParallelExecutionStrategy.cs
|   +-- SequentialStopOnFailureExecutionStrategy.cs
|   +-- SequentialContinueOnFailureExecutionStrategy.cs
+-- Federation/
|   +-- IFederationStrategy.cs       # Federation strategy interface
|   +-- FederationStrategyBase.cs    # Base federation strategy
+-- Optimization/
|   +-- IQueryOptimizer.cs           # Query optimization interface
+-- Messages/
    +-- DataCommandMessage.cs        # Base message type
    +-- DataCommandMessages.cs       # Message collection
    +-- CommandRequiredMessage.cs
    +-- ContainerNameRequiredMessage.cs
    +-- TranslationFailedMessage.cs
    +-- TranslatorNotFoundMessage.cs

Note: Expression types like IFilterExpression, IProjectionExpression, FilterOperators, and SortDirection are defined in FractalDataWorks.Data.Abstractions, not this project.

Base Class Implementations

DataCommandBase

The base class for creating data commands. All variants are in the same file.

From DataCommandBase.cs:21-73:

public abstract class DataCommandBase : IDataCommand
{
    protected DataCommandBase(string commandType, string containerName, string category = "Data")
    {
        CommandId = Guid.NewGuid();
        CreatedAt = DateTime.UtcNow;
        CommandType = commandType ?? throw new ArgumentNullException(nameof(commandType));
        ContainerName = containerName ?? throw new ArgumentNullException(nameof(containerName));
        Category = category ?? "Data";
        Metadata = new Dictionary<string, object>(StringComparer.OrdinalIgnoreCase);
    }

    public Guid CommandId { get; }
    public DateTime CreatedAt { get; }
    public string CommandType { get; }
    public string Category { get; }
    public string ContainerName { get; }
    public string ConnectionName { get; init; } = "Default";
    public IReadOnlyDictionary<string, object> Metadata { get; init; }
}

From DataCommandBase.cs:83-94:

public abstract class DataCommandBase<TResult> : DataCommandBase, IDataCommand<TResult>
{
    protected DataCommandBase(string commandType, string containerName)
        : base(commandType, containerName)
    {
    }
}

From DataCommandBase.cs:104-125:

public abstract class DataCommandBase<TResult, TInput> : DataCommandBase<TResult>, IDataCommand<TResult, TInput>
{
    protected DataCommandBase(string commandType, string containerName, TInput data)
        : base(commandType, containerName)
    {
        Data = data;
    }

    public TInput Data { get; }

    object? IDataCommandWithInput.InputData => Data;
}

DataCommandTranslatorBase

Base class for implementing translators.

From DataCommandTranslatorBase.cs:26-100:

public abstract class DataCommandTranslatorBase<TCommand> : IDataCommandTranslator<TCommand>
{
    protected DataCommandTranslatorBase(string name, string domainName)
    {
        Id = GenerateIdFromName(name);
        Name = name;
        DomainName = domainName;
    }

    public int Id { get; }
    public string Name { get; }
    public string Category => DomainName;
    public string DomainName { get; }

    public abstract Task<IGenericResult<TCommand>> Translate(
        IDataCommand command,
        IStorageContainer container,
        CancellationToken cancellationToken = default);
}

Best Practices

Translator Design

• Keep translators focused on one domain (SQL, REST, etc.)
• Use source-generated logging for translation operations
• Return descriptive failure messages via IGenericResult
• Validate commands before translation
• Use the IStorageContainer parameter for schema-aware query building
• Do not mix multiple domain translations in one translator
• Do not throw exceptions - use Result pattern

Command Design

• Keep commands simple and focused
• Use metadata for optional/hint information
• Provide typed generic variants when possible
• Do not put translation logic in commands
• Do not reference domain-specific types (SQL, REST) in commands

Registration

• Use [TypeOption] for compile-time translator discovery
• Use DataCommandTranslators.Register() for runtime registration
• Ensure translator types implement IDataCommandTranslator<TCommand>

Target Framework

• .NET Standard 2.0

Dependencies

NuGet Packages:

• Microsoft.Extensions.Logging.Abstractions
• FluentValidation

Project References:

• FractalDataWorks.Commands.Abstractions - Base command interfaces (IGenericCommand)
• FractalDataWorks.Collections - TypeCollection support
• FractalDataWorks.Results - Result pattern (IGenericResult)
• FractalDataWorks.Messages - Message abstractions
• FractalDataWorks.Data.Abstractions - IStorageContainer, IFilterExpression, etc.

Related Projects

• FractalDataWorks.Data.Abstractions - Expression types, filter operators, and storage container abstractions used by translators

Next Steps

• See FractalDataWorks.Data.Abstractions for expression types used by query commands
• See FractalDataWorks.Collections for TypeCollection patterns used by DataCommandTranslators
• See FractalDataWorks.Results for the Result pattern used by translator operations