FractalDataWorks.Results.Abstractions 0.7.0-alpha.1022

FractalDataWorks.Results.Abstractions

Core result pattern interfaces for Railway-Oriented Programming in the FractalDataWorks ecosystem. This minimal abstractions package provides interface contracts that enable consistent error handling without implementation dependencies.

Overview

FractalDataWorks.Results.Abstractions contains only the interface definitions for the result pattern, enabling:

• Dependency Inversion: Higher-level packages depend on abstractions, not implementations
• Circular Dependency Prevention: Breaks circular references between framework layers
• Maximum Compatibility: .NET Standard 2.0 for broadest reach
• Interface Segregation: Minimal surface area with focused contracts

Target Frameworks: .NET Standard 2.0, .NET 10.0 Implementation: FractalDataWorks.Results provides concrete implementations

Why This Package Exists

The framework follows strict layering to prevent circular dependencies:

FractalDataWorks.Abstractions (foundational interfaces)
    ↓
FractalDataWorks.Results.Abstractions (result interfaces) ← You are here
    ↓
FractalDataWorks.Results (concrete implementations)
    ↓
FractalDataWorks.Services.Abstractions (service interfaces)

By placing result interfaces in a separate abstractions package:

• Source generators can reference result contracts without pulling in implementations
• Lower-level packages avoid heavyweight dependencies
• Clean separation between contract and implementation

Core Interfaces

This package re-exports the result interfaces from FractalDataWorks.Abstractions:

IGenericResult

public interface IGenericResult
{
    bool IsSuccess { get; }
    bool IsFailure { get; }
    bool IsEmpty { get; }
    bool Error { get; }
    string? CurrentMessage { get; }
    IReadOnlyList<IGenericMessage> Messages { get; }
}

IGenericResult<T>

public interface IGenericResult<out T> : IGenericResult
{
    T? Value { get; }
}

Architecture Pattern

Interface-Only Package

This package contains zero implementation code. It serves as a pure contract layer:

// This package: Interfaces only
public interface IGenericResult
{
    bool IsSuccess { get; }
    // ... other properties
}

// FractalDataWorks.Results: Implementations
public class GenericResult : IGenericResult
{
    public bool IsSuccess { get; private set; }
    // ... implementation details
}

Dependency Flow

Low-Level Packages
    ↓ (depend on abstractions)
Results.Abstractions
    ↑ (implemented by)
Results
    ↑ (consumed by)
High-Level Packages

Benefits:

• Source generators reference abstractions without pulling in concrete types
• Testability: Mock interfaces without implementation dependencies
• Flexibility: Swap implementations without changing consumers

Usage Patterns

Referencing from Low-Level Code

<ItemGroup>
  <PackageReference Include="FractalDataWorks.Results.Abstractions" Version="*" />
  
</ItemGroup>

// Can work with result interface without implementation dependency
public interface ICommandAnalyzer
{
    IGenericResult<bool> Validate(IGenericCommand command);
}

Referencing from High-Level Code

<ItemGroup>
  <PackageReference Include="FractalDataWorks.Results" Version="*" />
  
</ItemGroup>

// Use concrete implementations
public class CommandService
{
    public IGenericResult<bool> ValidateCommand(IGenericCommand command)
    {
        return GenericResult<bool>.Success(true);
    }
}

Why Not Just Use Results Package?

Problem: Circular dependencies

Analyzers → Results → Collections → Analyzers (circular!)

Solution: Abstractions layer

Analyzers → Results.Abstractions
                ↑
             Results → Collections → Analyzers (no circle)

Source Generator Scenario

Source generators need result interfaces but can't reference full implementations:

// Source generator code
[Generator]
public class MyGenerator : IIncrementalGenerator
{
    // Can reference interface
    private IGenericResult<TypeInfo> AnalyzeType(ITypeSymbol symbol)
    {
        // But can't create concrete GenericResult here
        // (would create circular dependency)
    }
}

Analyzer Scenario

Analyzers need to define APIs that return results:

// Analyzer code
public interface ITypeAnalyzer
{
    IGenericResult<DiagnosticInfo> Analyze(SyntaxNode node);
}

// Implementation elsewhere
public class TypeAnalyzer : ITypeAnalyzer
{
    public IGenericResult<DiagnosticInfo> Analyze(SyntaxNode node)
    {
        return GenericResult<DiagnosticInfo>.Success(info);
    }
}

Interface Contracts

IsSuccess and IsFailure

Mutually exclusive states:

• IsSuccess == !IsFailure
• Implementations must guarantee this invariant

Error Property

Convenience alias:

• Error == IsFailure
• Provided for readability in certain contexts

IsEmpty Property

Indicates absence of content:

• For IGenericResult: No messages present
• For IGenericResult<T>: No value available
• Implementation-specific semantics

CurrentMessage Property

LIFO message retrieval:

• Returns most recent message
• null if no messages
• Used for quick error display

Messages Property

Full message collection:

• Read-only list of all messages
• Preserves insertion order (or LIFO, implementation-dependent)
• Never null, may be empty

Value Property

Type-safe value access:

• Only available in IGenericResult<T>
• Should throw if IsSuccess == false
• Covariant (out T) for type safety

Best Practices

1. Reference Abstractions in Low-Level Code

// ✅ GOOD: Low-level code references abstractions
public interface IValidator
{
    IGenericResult<bool> Validate(object input);
}

// ❌ BAD: Low-level code references concrete types
public interface IValidator
{
    GenericResult<bool> Validate(object input);  // Concrete type
}

2. Return Interfaces, Not Implementations

// ✅ GOOD: Return interface
public IGenericResult<User> GetUser(int id)
{
    return GenericResult<User>.Success(user);
}

// ❌ BAD: Return concrete type
public GenericResult<User> GetUser(int id)
{
    return GenericResult<User>.Success(user);
}

3. Use Abstractions for Parameters

// ✅ GOOD: Accept interface
public void ProcessResult(IGenericResult<Data> result)
{
    if (result.IsSuccess)
        UseData(result.Value);
}

// ❌ BAD: Accept concrete type
public void ProcessResult(GenericResult<Data> result)
{
    // Tightly coupled to implementation
}

4. Covariance for Flexibility

The out modifier enables covariance:

IGenericResult<Dog> dogResult = GetDog();
IGenericResult<Animal> animalResult = dogResult;  // Valid due to covariance

Integration with Framework

Used By

• Collections.Analyzers: Return validation results
• ServiceTypes.Analyzers: Return diagnostic results
• Commands.Abstractions: Command validation interfaces
• Data.Abstractions: Data operation result contracts
• Source Generators: Code generation result interfaces

Implemented By

• FractalDataWorks.Results: GenericResult and GenericResult<T>

Consumed By

• All framework packages that work with results
• User code implementing framework interfaces

Multi-Targeting

This package multi-targets to maximize reach:

• .NET Standard 2.0: Broad compatibility (Blazor WASM, Unity, Xamarin)
• .NET 10.0: Latest features and performance

Project Structure

FractalDataWorks.Results.Abstractions/
└── (Re-exports from FractalDataWorks.Abstractions)
    ├── IGenericResult
    └── IGenericResult<T>

This package is essentially a facade that re-exports result interfaces from FractalDataWorks.Abstractions for dependency management purposes.

Design Rationale

Why Not Just Use Abstractions Package?

The FractalDataWorks.Abstractions package contains foundational interfaces including result interfaces. However, Results.Abstractions exists to:

1. Semantic Clarity: Clear intent when depending on results specifically
2. Future Flexibility: Can add result-specific abstractions without polluting core
3. Dependency Granularity: Express precise dependencies in project files
4. Documentation Organization: Separate documentation for result patterns

Alternative: Inline Interfaces

Could we define result interfaces inline in each package?

// ❌ BAD: Duplicate interface definitions
// Package A
public interface IGenericResult { ... }

// Package B
public interface IGenericResult { ... }  // Duplicate!

Problems:

• Interface duplication
• Version skew between packages
• No shared implementation possible
• Type compatibility issues

Alternative: Single Shared Package

Could we put everything in one abstractions package?

// ❌ SUBOPTIMAL: Everything in one package
FractalDataWorks.Abstractions
    ├── IGenericService
    ├── IGenericCommand
    ├── IGenericResult
    ├── IGenericConfiguration
    └── ... (grows indefinitely)

Problems:

• Package becomes too large
• Unclear dependency intentions
• All-or-nothing dependencies

Dependencies

• FractalDataWorks.Abstractions: Source of result interface definitions
• FractalDataWorks.Messages: IGenericMessage interface

Summary

FractalDataWorks.Results.Abstractions provides a minimal, focused interface layer for result patterns. By separating interface contracts from implementations, it enables clean dependency management, prevents circular references, and provides maximum flexibility for low-level framework components like analyzers and source generators. This package is a key architectural element that enables the framework's layered design.