FractalDataWorks.Services.Transformations.Abstractions 0.4.0-preview.6

FractalDataWorks.Services.Transformations.Abstractions

Core abstractions and interfaces for data transformation services within the FractalDataWorks framework.

Overview

This package provides the foundational abstractions for data transformation services in the FractalDataWorks ecosystem. It defines contracts that transformation service providers must implement, including transformation interfaces, request/response models, service type definitions, factory interfaces, and configuration interfaces.

Target Framework

• netstandard2.0

Dependencies

Project References

• FractalDataWorks.Configuration.Abstractions - Base configuration interfaces
• FractalDataWorks.Configuration - Configuration implementation
• FractalDataWorks.Services.Abstractions - Core service abstractions
• FractalDataWorks.Services.Abstractions - Service type framework
• FractalDataWorks.Collections - Type collection support
• FractalDataWorks.Data.DataContainers.Abstractions - Data container type definitions

Package References

• Microsoft.Extensions.DependencyInjection.Abstractions - DI abstractions
• Microsoft.Extensions.Diagnostics.HealthChecks - Health check support
• Microsoft.Extensions.Logging.Abstractions - Logging abstractions

Key Types

IGenericTransformation

From IGenericTransformation.cs:10-14:

public interface IGenericTransformation : IDisposable, IGenericService
{
    // Domain-specific methods can be added here if needed
    // Currently inherits all required capabilities from IDisposable and IGenericService
}

Base interface for all transformation services in the framework. Extends IDisposable for resource cleanup and IGenericService for framework integration.

ITransformationProvider

From ITransformationProvider.cs:11-33:

public interface ITransformationProvider
{
    /// <summary>
    /// Gets a transformation using the provided configuration.
    /// The configuration's TransformationType property determines which factory to use.
    /// </summary>
    Task<IGenericResult<IGenericTransformation>> GetTransformation(ITransformationConfiguration configuration);

    /// <summary>
    /// Gets a transformation by configuration name from appsettings.
    /// </summary>
    Task<IGenericResult<IGenericTransformation>> GetTransformation(string configurationName);

    /// <summary>
    /// Gets a transformation using the provided configuration and attempts to cast it to the specified type.
    /// </summary>
    Task<IGenericResult<T>> GetTransformation<T>(ITransformationConfiguration configuration) where T : IGenericTransformation;

    /// <summary>
    /// Gets a transformation by configuration name and attempts to cast it to the specified type.
    /// </summary>
    Task<IGenericResult<T>> GetTransformation<T>(string configurationName) where T : IGenericTransformation;
}

Provider interface that uses TransformationTypes to lookup configuration types and factories. Follows Railway-Oriented Programming - all operations return IGenericResult.

ITransformationConfiguration

From ITransformationConfiguration.cs:11-36:

public interface ITransformationConfiguration : IGenericConfiguration
{
    /// <summary>
    /// Gets the transformation type name this configuration is for.
    /// This property is used by the TransformationProvider to determine which factory to use.
    /// </summary>
    string TransformationType { get; }

    /// <summary>
    /// Gets the service lifetime for this transformation instance.
    /// Determines how the transformation service is registered in the DI container.
    /// </summary>
    IServiceLifetime Lifetime { get; }

    /// <summary>
    /// Gets the name of the secret manager to use for retrieving secrets.
    /// References a SecretManager configuration by name.
    /// </summary>
    string? SecretManagerName { get; init; }

    /// <summary>
    /// Gets the key name within the secret manager to retrieve.
    /// Used in conjunction with SecretManagerName to locate the specific secret.
    /// </summary>
    string? SecretKeyName { get; init; }
}

Configuration interface that specifies which transformation type to use and the service lifetime for DI registration. Supports secret manager integration.

ITransformationFactory

From ITransformationFactory.cs:11-33:

public interface ITransformationFactory : IServiceFactory
{
    /// <summary>
    /// Creates a transformation using the provided configuration.
    /// </summary>
    Task<IGenericResult<IGenericTransformation>> CreateTransformation(IGenericConfiguration configuration);
}

public interface ITransformationFactory<TTransformation, in TConfiguration>
    : ITransformationFactory, IServiceFactory<TTransformation, TConfiguration>
    where TConfiguration : ITransformationConfiguration
    where TTransformation : IGenericTransformation
{
    /// <summary>
    /// Creates a typed transformation using the provided configuration.
    /// </summary>
    Task<IGenericResult<TTransformation>> CreateTransformation(TConfiguration configuration);
}

Factory interfaces for creating transformation instances. The generic variant provides type-safe creation with strongly-typed configuration.

ITransformationType

From ITransformationType.cs:20-87:

public interface ITransformationType<TService, TConfiguration, TFactory> : IServiceType<Guid, TService, TFactory, TConfiguration>, ITransformationType
    where TService : class, IGenericTransformation
    where TConfiguration : class, ITransformationConfiguration
    where TFactory : class, ITransformationFactory<TService, TConfiguration>
{
}

public interface ITransformationType : IServiceType
{
    Type InputType { get; }
    Type OutputType { get; }
    bool SupportsStreaming { get; }
    bool SupportsBatching { get; }
    bool IsReversible { get; }
    long MaxInputSize { get; }
    string PerformanceProfile { get; }
    string MemoryUsagePattern { get; }
    IReadOnlyList<string> SupportedInputFormats { get; }
    IReadOnlyList<string> SupportedOutputFormats { get; }
    IReadOnlyList<IDataContainerType> SupportedContainerTypes { get; }
}

Service type interface for transformation services. Provides metadata about transformation capabilities including input/output types, streaming support, and performance characteristics.

ITransformationServiceType

From ITransformationServiceType.cs:11-52:

public interface ITransformationServiceType : IServiceType
{
    string[] SupportedInputTypes { get; }
    string[] SupportedOutputTypes { get; }
    string[] SupportedCategories { get; }
    bool SupportsParallelExecution { get; }
    bool SupportsTransformationCaching { get; }
    bool SupportsPipelineMode { get; }
    long MaxInputSizeBytes { get; }
    int Priority { get; }
}

Service type metadata interface for transformation providers. Used for capability advertisement and provider selection.

ITransformationsService

From ITransformationsService.cs:13-53:

public interface ITransformationsService : IGenericTransformation
{
    Task<IGenericResult<TOutput>> Transform<TOutput>(
        ITransformationRequest request,
        ITransformationContext context,
        CancellationToken cancellationToken = default);

    Task<IGenericResult<ITransformationMetrics>> GetTransformationMetrics(CancellationToken cancellationToken = default);

    Task<IGenericResult<TResult>> Execute<TResult>(ITransformationsCommand command, CancellationToken cancellationToken = default);

    Task<IGenericResult> Execute(ITransformationsCommand command, CancellationToken cancellationToken = default);
}

Service interface for executing transformations. Provides methods for transformation execution, metrics retrieval, and command-based operations.

ITransformationRequest

From ITransformationRequest.cs:16-171:

public interface ITransformationRequest : IGenericCommand
{
    Guid RequestId { get; }
    object? InputData { get; }
    string InputType { get; }
    string OutputType { get; }
    string? TransformationCategory { get; }
    IReadOnlyDictionary<string, object> Configuration { get; }
    IReadOnlyDictionary<string, object> Options { get; }
    TimeSpan? Timeout { get; }
    ITransformationContext? Context { get; }
    Type ExpectedResultType { get; }

    // Immutable update methods
    ITransformationRequest WithInputData(object? newInputData, string? newInputType = null);
    ITransformationRequest WithOutputType(string newOutputType, Type? newExpectedResultType = null);
    ITransformationRequest WithConfiguration(IReadOnlyDictionary<string, object> newConfiguration);
    ITransformationRequest WithOptions(IReadOnlyDictionary<string, object> newOptions);
}

Request interface that encapsulates input data, transformation configuration, and execution parameters. Extends IGenericCommand for integration with the command pattern. Provides immutable update methods for thread-safe request modification.

A generic variant ITransformationRequest<TInput> is also available for strongly-typed input data.

ITransformationResult

From ITransformationResult.cs:8-47:

public interface ITransformationResult
{
    object? Data { get; }
    string OutputType { get; }
    IReadOnlyDictionary<string, object?> Metadata { get; }
    long DurationMs { get; }
}

public interface ITransformationResult<TOutput> : ITransformationResult
{
    new TOutput? Data { get; }
}

Result interface for transformation operations. Includes the transformed data, output type, metadata, and execution duration. A generic variant provides type-safe access to output data.

ITransformationEngine

From ITransformationEngine.cs:10-49:

public interface ITransformationEngine
{
    string EngineId { get; }
    string EngineType { get; }
    bool IsRunning { get; }

    Task<IGenericResult<ITransformationResult>> ExecuteTransformation(ITransformationRequest request, CancellationToken cancellationToken = default);
    Task<IGenericResult> Start(CancellationToken cancellationToken = default);
    Task<IGenericResult> Stop(CancellationToken cancellationToken = default);
}

Engine interface for complex, multi-step transformations with lifecycle management.

ITransformationEngineConfiguration

From ITransformationEngineConfiguration.cs:9-35:

public interface ITransformationEngineConfiguration : IGenericConfiguration
{
    string EngineType { get; }
    int MaxConcurrency { get; }
    int TimeoutSeconds { get; }
    bool EnableCaching { get; }
    bool EnableMetrics { get; }
}

Configuration interface for transformation engines. Specifies engine type, concurrency limits, timeouts, and feature flags.

ITransformationContext

From ITransformationContext.cs:14-43:

public interface ITransformationContext
{
    string? Identity { get; }
    string? CorrelationId { get; }
    string? PipelineStage { get; }
    IReadOnlyDictionary<string, object> Properties { get; }
}

Context interface providing additional metadata for transformations, including identity, correlation, pipeline stage, and extensible properties.

ITransformationMetrics

From ITransformationMetrics.cs:8-44:

public interface ITransformationMetrics
{
    long TotalTransformations { get; }
    long SuccessfulTransformations { get; }
    long FailedTransformations { get; }
    double AverageTransformationDurationMs { get; }
    int ActiveTransformations { get; }
    DateTime MetricsStartTime { get; }
    DateTime? LastTransformationTime { get; }
}

Interface for transformation performance metrics and execution statistics.

ITransformationsCommand

From ITransformationsCommand.cs:9-11:

public interface ITransformationsCommand : IGenericCommand
{
}

Command interface for transformation operations. Extends IGenericCommand for integration with the unified command pattern.

Architecture

Service Framework Integration

All interfaces extend the core FractalDataWorks service framework patterns:

• IGenericTransformation extends IGenericService
• ITransformationRequest extends IGenericCommand
• ITransformationConfiguration extends IGenericConfiguration
• ITransformationType extends IServiceType
• ITransformationFactory extends IServiceFactory
• All operations return IGenericResult<T> following Railway-Oriented Programming

Immutable Request Pattern

The ITransformationRequest interface provides immutable update methods (WithInputData, WithOutputType, WithConfiguration, WithOptions) that return new instances rather than modifying existing ones. This ensures thread safety and predictable behavior in concurrent scenarios.

Factory Pattern

Transformations are created through factories rather than direct instantiation:

1. ITransformationProvider receives a configuration or configuration name
2. The provider uses TransformationType to determine which factory to use
3. The factory creates the transformation instance with proper DI resolution

Related Packages

• FractalDataWorks.Services.Abstractions - Base service abstractions
• FractalDataWorks.Services.Abstractions - Service type framework
• FractalDataWorks.Configuration - Configuration framework
• FractalDataWorks.Results - Railway-Oriented Programming support