FractalDataWorks.Data 0.4.0-preview.6

FractalDataWorks.Data

Cross-cutting data domain types including TypeCollections for filter operators, sort directions, join types, and expression types.

Overview

This package provides common data types used across the FractalDataWorks framework for building data queries. It implements TypeCollections that replace enums with extensible, type-safe alternatives that know their own SQL and OData representations.

Installation

<PackageReference Include="FractalDataWorks.Data" Version="1.0.0" />

Key Types

TypeCollections

• FilterOperators - Operators for filter expressions (Equal, NotEqual, Contains, GreaterThan, etc.)
• SortDirections - Sort directions for ORDER BY clauses (Ascending, Descending)
• JoinTypes - Join types for data operations (Inner, Left, Right, Full, Cross, None)
• ContainerTypes - Container type definitions
• PathTypes - Data path type definitions

Expression Types

• FilterExpression - Hierarchical WHERE clause representation
• FilterCondition - Single filter condition (property, operator, value)
• FilterGroup - Group of filter nodes with logical operator (AND/OR)
• OrderingExpression - ORDER BY clause representation
• OrderedField - Single ordered field with direction
• PagingExpression - SKIP/TAKE pagination
• JoinExpression - JOIN clause representation
• ProjectionExpression - SELECT clause representation
• AggregationExpression - Aggregation function representation

Usage

FilterOperators TypeCollection

From FilterOperators.cs:40-50:

[TypeCollection(typeof(FilterOperatorBase), typeof(IFilterOperator), typeof(FilterOperators))]
[ExcludeFromCodeCoverage]
public abstract partial class FilterOperators : TypeCollectionBase<FilterOperatorBase, IFilterOperator>
{
    // Source generator will create:
    // - Static constructor
    // - Static properties for each [TypeOption] operator
    // - All() method
    // - GetByName() method
    // - GetById() method
}

Access operators via generated static properties or lookup methods:

From Reference Solution Program.cs:28-47:

// Access operators via static properties (type-safe, no magic strings)
Console.WriteLine("   Direct property access (generated static properties):");
Console.WriteLine($"   - FilterOperators.Equal.SqlOperator = \"{FilterOperators.Equal.SqlOperator}\"");
Console.WriteLine($"   - FilterOperators.Contains.SqlOperator = \"{FilterOperators.Contains.SqlOperator}\"");
Console.WriteLine($"   - FilterOperators.GreaterThan.SqlOperator = \"{FilterOperators.GreaterThan.SqlOperator}\"");
Console.WriteLine($"   - FilterOperators.IsNull.SqlOperator = \"{FilterOperators.IsNull.SqlOperator}\"");

// List all operators
Console.WriteLine("   All filter operators:");
foreach (var op in FilterOperators.All())
{
    Console.WriteLine($"   - {op.Name}: SQL=\"{op.SqlOperator}\", OData=\"{op.ODataOperator}\", RequiresValue={op.RequiresValue}");
}

// ByName lookup (O(1)) - useful for deserialization from config/database
Console.WriteLine("   ByName lookup (O(1) via FrozenDictionary):");
var opFromConfig = FilterOperators.ByName("NotEqual");
Console.WriteLine($"   - FilterOperators.ByName(\"NotEqual\").SqlOperator = \"{opFromConfig.SqlOperator}\"");

FilterCondition

From FilterCondition.cs:26-43:

public sealed record FilterCondition : IFilterCondition, IFilterNode
{
    /// <summary>
    /// Gets the property name to filter on.
    /// </summary>
    public required string PropertyName { get; init; }

    /// <summary>
    /// Gets the filter operator.
    /// This is a FilterOperatorBase (TypeCollection), not an enum!
    /// </summary>
    public required IFilterOperator Operator { get; init; }

    /// <summary>
    /// Gets the value to compare against (null for IS NULL / IS NOT NULL operators).
    /// </summary>
    public object? Value { get; init; }
}

Building filter conditions:

From Reference Solution Program.cs:66-90:

// Simple equality condition
var nameFilter = new FilterCondition
{
    PropertyName = "CustomerName",
    Operator = FilterOperators.Equal,
    Value = "Acme Corp"
};
Console.WriteLine($"   Simple: [{nameFilter.PropertyName}] {nameFilter.Operator.SqlOperator} @{nameFilter.PropertyName}");

// Contains (LIKE) condition - operator knows its own SQL!
var searchFilter = new FilterCondition
{
    PropertyName = "Description",
    Operator = FilterOperators.Contains,
    Value = "widget"
};
Console.WriteLine($"   Contains: [{searchFilter.PropertyName}] {searchFilter.Operator.SqlOperator} @{searchFilter.PropertyName}");

// Null check (no value needed)
var nullCheck = new FilterCondition
{
    PropertyName = "DeletedAt",
    Operator = FilterOperators.IsNull
    // No Value - IsNull doesn't need one (RequiresValue = false)
};
Console.WriteLine($"   NullCheck: [{nullCheck.PropertyName}] {nullCheck.Operator.SqlOperator}");

SortDirections TypeCollection

From SortDirections.cs:7-15:

/// <summary>
/// Collection of sort directions for data queries.
/// Generated by TypeCollectionGenerator with high-performance lookups.
/// </summary>
[ExcludeFromCodeCoverage]
[TypeCollection(typeof(SortDirectionBase), typeof(ISortDirection), typeof(SortDirections))]
public abstract partial class SortDirections : TypeCollectionBase<SortDirectionBase, ISortDirection>
{
}

From Reference Solution Program.cs:53-58:

Console.WriteLine("2. SortDirections TypeCollection:");
foreach (var direction in SortDirections.All())
{
    Console.WriteLine($"   - {direction.Name} (SqlKeyword: \"{direction.SqlKeyword}\")");
}

OrderedField and OrderingExpression

From OrderedField.cs:6-18:

public sealed record OrderedField : IOrderedField
{
    /// <summary>
    /// Gets the property name to order by.
    /// </summary>
    public required string PropertyName { get; init; }

    /// <summary>
    /// Gets the sort direction.
    /// This is a SortDirection TypeCollection, not a traditional enum!
    /// </summary>
    public required ISortDirection Direction { get; init; }
}

From Reference Solution Program.cs:152-162:

Ordering = new OrderingExpression
{
    OrderedFields =
    [
        new OrderedField
        {
            PropertyName = "CustomerName",
            Direction = SortDirections.Ascending
        }
    ]
},

FilterExpression

From FilterExpression.cs:51-57:

public sealed class FilterExpression : IFilterExpression
{
    /// <summary>
    /// Gets or sets the root filter node.
    /// </summary>
    public IFilterNode? Root { get; init; }
}

From Reference Solution Program.cs:141-151:

var directQuery = new QueryCommand<CustomerDto>("dbo.Customers")
{
    Filter = new FilterExpression
    {
        Root = new FilterCondition
        {
            PropertyName = "IsActive",
            Operator = FilterOperators.Equal,
            Value = true
        }
    },

ByName Lookup for Configuration

When operators are stored in configuration or databases, use ByName lookup:

From ConfigurationLoader.cs:191-202:

var headerQuery = new QueryCommand<ConfigurationHeaderEntity>("Configuration")
{
    Filter = new FilterExpression
    {
        Root = new FilterCondition
        {
            PropertyName = "ServiceCategory",
            Operator = FilterOperators.ByName("Equal"),
            Value = "DataStore"
        }
    }
};

FilterOperator Implementations

The package includes these built-in filter operators:

Best Practices

1. Use static properties when the operator is known at compile time - see Reference Solution Program.cs:69 for usage of FilterOperators.Equal.

2. Use ByName lookup when operators come from configuration - see ConfigurationLoader.cs:198 for FilterOperators.ByName("Equal").

3. Check RequiresValue before setting Value - operators like IsNull and IsNotNull do not require values.

From MsSqlDataCommandTranslatorBase.cs:153-164:

var columnName = $"[{condition.PropertyName}]";
var sql = $"{columnName} {condition.Operator.SqlOperator}";

if (condition.Operator.RequiresValue)
{
    var paramName = $"{context.ParameterPrefix}p{context.ParameterCounter++}";
    sql += $" {paramName}";

    // ZERO SQL INJECTION: Value goes into parameter, NOT concatenated into SQL
    var parameter = new SqlParameter(paramName, condition.Value ?? DBNull.Value);
    context.Command.Parameters.Add(parameter);
}

4. Leverage operator knowledge - operators know their own SQL/OData representations, eliminating switch statements. See FilterOperatorBase.SqlOperator and FilterOperatorBase.ODataOperator properties.

Related Packages

• FractalDataWorks.Data.Abstractions - Interfaces and base classes
• FractalDataWorks.Commands.Data - Data commands (QueryCommand, InsertCommand, etc.)
• FractalDataWorks.Collections - TypeCollection base infrastructure

Next Steps

• See Commands.Data for building complete data commands
• See the Reference Solution data layer example for working code