centralized-filter-normalization

Context

Use when a filter record (e.g., AzdoBuildFilter) has optional string fields with server-side defaults and case-insensitive server interpretation. Multiple layers (HTTP client, cache key builder, service layer) historically re-implement the same canonicalization rules, causing algorithmic drift.

The pattern was extracted from the Issue #82 refactor of AzdoBuildFilter, which fixed four rounds of reviewer feedback on PR #78 (each round finding the same class of normalization bug at a different layer).

The Principle

"Canonicalize at boundaries, share the algorithm."

• Validate at user/input boundaries (CLI/MCP) — for early, useful error messages
• Canonicalize at semantic boundaries (URL construction, cache key derivation) — where the value's meaning is consumed
• Centralize the canonicalization algorithm — multiple layers call the shared helper; none re-implement

"Normalize at every layer" (a common first instinct) leads to algorithm duplication and drift.

Pattern: Three Types, One File Per Filter

1. Defaults class (in domain model file, alongside the filter record)

public static class AzdoBuildFilterDefaults
{
    public const string QueryOrder = "queueTimeDescending";
    public const string Outcomes   = "Failed";
}

• Lives in the domain layer (same project/namespace as the filter record)
• Both HTTP client and cache layer reference these constants — no layer depends on another for constants

2. Normalizer class (domain layer, {FilterType}Normalizer.cs)

public static class AzdoBuildFilterNormalizer
{
    public static AzdoBuildFilter Normalize(AzdoBuildFilter filter) =>
        filter with
        {
            PrNumber     = NormalizeString(filter.PrNumber),
            Branch       = NormalizeString(filter.Branch),
            StatusFilter = NormalizeString(filter.StatusFilter),
            QueryOrder   = NormalizeQueryOrder(filter.QueryOrder),
        };

    private static string? NormalizeString(string? value) =>
        string.IsNullOrWhiteSpace(value) ? null : value.Trim();

    private static string? NormalizeQueryOrder(string? value)
    {
        var trimmed = NormalizeString(value);
        if (trimmed is null) return null;
        if (string.Equals(trimmed, AzdoBuildFilterDefaults.QueryOrder, StringComparison.OrdinalIgnoreCase))
            return null;  // collapse explicit server default to null
        return trimmed.ToLowerInvariant();  // lowercase for case-insensitive equivalence
    }
}