DEV Community: Mutombo jean-vincent

Offline First: Using the Decorator Pattern to Cache API Responses in Flutter

Mutombo jean-vincent — Mon, 08 Jun 2026 10:23:53 +0000

The Problem

Imagine the network disappears mid-session. What does your app show? For a long time, mine showed nothing. The platform serves articles, videos, user profiles, and settings, all pulled from a .NET backend. No connection meant no data, and I had not planned for that at all.

The first version was simple. A screen called a use case, the use case called a repository, the repository called the API. If the API responded, great. If not, the user saw an error. That is fine for a first pass, but it is not acceptable for a real app. Users expect data to be there, especially for things they have already seen.

The obvious answer is caching. Fetch from the API, store the result locally, and the next time the user opens the app, show the cached data immediately while the fresh data loads in the background. But how you wire that up matters a lot. I did not want the caching logic mixed into my use cases or bleeding into the domain layer. I wanted the rest of the app to be completely unaware that caching was happening at all.

That is where the Proxy and Decorator patterns came in.

The Idea

Both patterns involve wrapping an object and adding behavior around it without changing the interface. The difference is mostly about intent:

Proxy controls access to the real object. It can intercept calls to add caching, authorization checks, lazy loading, or logging. The caller does not know whether it is talking to the real thing or the proxy.
Decorator adds new behavior to an existing object while delegating the original behavior to it. You stack decorators on top of each other, each one adding one responsibility.

In practice, the two patterns look almost identical in code. What I ended up with in the mobile app is a Decorator at the repository layer: a class that implements the same repository interface as the remote implementation, wraps it, and adds local storage behavior on top of it without the rest of the app ever knowing.

The architecture looks like this:

Use Case
    ↓
ISettingsRepository (interface)
    ↓
SettingsCachedRepository (decorator, implements ISettingsRepository)
    ↓
SettingsRemoteRepository (real implementation, also implements ISettingsRepository)
    ↓
HTTP API via Chopper/Dio
    ↓
Backend: /api/v1/settings/profile

The use case only knows about ISettingsRepository. The dependency injection container decides which concrete class gets injected. Everything below the interface is invisible to the caller.

The Implementation

The Interface

First, there is a port (interface) that defines what the repository can do. This is the contract that both the remote and the cached implementations must honour:

/// Repository port for settings operations.
///
/// Both the remote and the cached implementations satisfy this contract.
/// Use cases depend only on this interface, never on concrete classes.
abstract class ISettingsRepository {
  Future<Either<Failure, ProfileResponseEntity>> updateProfile(ProfileModel profile);
  Future<Either<Failure, ProfileResponseEntity>> updateAvatar(File avatarFile);
}

Notice the return type: Either<Failure, T>. This is from fpdart, a functional programming library for Dart. Instead of throwing exceptions, every repository method returns a Left(failure) on error or a Right(value) on success. The caller pattern-matches on the result. No try-catch in use cases, no unhandled exceptions flying up the stack.

The Remote Repository

The remote repository is the real implementation. It calls the API through a data source, maps the DTO response into a domain entity, and wraps errors into Left(failure):

/// Remote settings repository.
///
/// Calls the API through the remote data source and maps DTOs to domain entities.
/// All errors are caught and returned as Left(Failure), never thrown.
class SettingsRemoteRepository implements ISettingsRepository {
  final ISettingsRemoteDataSource _remoteDataSource;

  const SettingsRemoteRepository(this._remoteDataSource);

  @override
  Future<Either<Failure, ProfileResponseEntity>> updateProfile(ProfileModel profile) async {
    try {
      final response = await _remoteDataSource.updateProfile(profile);
      final profileEntity = SettingsMapper.profileResponseFromDto(response);
      return Right(profileEntity);
    } on ServerException catch (exception) {
      return Left(ProblemMapper.toFailure(exception));
    }
  }

  @override
  Future<Either<Failure, ProfileResponseEntity>> updateAvatar(File avatarFile) async {
    try {
      final response = await _remoteDataSource.updateAvatar(avatarFile);
      final profileEntity = SettingsMapper.avatarResponseFromDto(response);
      return Right(profileEntity);
    } on ServerException catch (exception) {
      return Left(ProblemMapper.toFailure(exception));
    }
  }

}

This class knows nothing about local storage. Its one job is to make HTTP calls and translate results.

The Cached Repository (The Decorator)

Here is where the pattern pays off. The cached repository also implements ISettingsRepository, but instead of making API calls itself, it delegates to the inner remote repository and then persists the result locally if the call succeeded:

/// Cached settings repository (decorator pattern).
///
/// Wraps the inner repository and adds local caching functionality.
/// Delegates remote operations to the inner repository, then persists
/// successful results to local storage via auth local datasource.
/// The rest of the app never knows this layer exists.
class SettingsCachedRepository implements ISettingsRepository {
  final ISettingsRepository _remoteRepository;
  final IAuthLocalDataSource _localDataSource;

  const SettingsCachedRepository(this._remoteRepository, this._localDataSource);

  @override
  Future<Either<Failure, ProfileResponseEntity>> updateProfile(ProfileModel profile) async {
    final result = await _remoteRepository.updateProfile(profile);

    // Only persist if the remote call succeeded
    return result.fold(
      (failure) => Left(failure),
      (profileResponse) async {
        try {
          await _localDataSource.setUser(UserModel.fromEntity(profileResponse.user));
          return Right(profileResponse);
        } on CacheException catch (exception) {
          return Left(ProblemMapper.toFailure(exception));
        }
      },
    );
  }

  @override
  Future<Either<Failure, ProfileResponseEntity>> updateAvatar(File avatarFile) async {
    final result = await _remoteRepository.updateAvatar(avatarFile);

    // Only persist if the remote call succeeded
    return result.fold(
      (failure) => Left(failure),
      (profileResponse) async {
        try {
          await _localDataSource.setUser(UserModel.fromEntity(profileResponse.user));
          return Right(profileResponse);
        } on CacheException catch (exception) {
          return Left(ProblemMapper.toFailure(exception));
        }
      },
    );
  }

}

A few things worth pointing out:

Only cache on success. The result.fold(...) call handles both branches. If the remote call returned a Left(failure), the decorator passes the failure through unchanged. It never writes stale or partial data to local storage. The cache only ever holds data that the server confirmed was saved successfully.

The decorator does not know about HTTP. It does not import Chopper/Dio or touch any networking code. It only knows about the ISettingsRepository interface and the IAuthLocalDataSource interface. The two responsibilities, talking to the API and talking to local storage, are in separate classes and stay there. This also means swapping the HTTP client is trivial. The project uses Chopper, but Dio, http, or Retrofit would work exactly the same way. The decorator never sees any of it.

Local Storage with Hive

The local data source uses Hive CE, a fast, pure-Dart key-value store. Each module has its own Hive box, its own set of constants, and its own Hive model classes. The auth module's local data source writes and reads UserModel instances from a dedicated auth_box:

// hive.constants.dart
const String kAuthBox = 'auth_box';
const int kUserTypeId = 0;
const String kUserKey = 'user';

/// Hive-backed implementation of IAuthLocalDataSource.
///
/// Reads and writes UserModel to the auth_box using Hive's put/get/delete API.
/// Throws typed CacheException subclasses so errors can be mapped to Failure
/// by the repository layer.
class AuthLocalDataSource implements IAuthLocalDataSource {
  final Box<dynamic> _authBox;

  AuthLocalDataSource(this._authBox);

  @override
  Future<void> setUser(UserModel user) async {
    try {
      await _authBox.put(kUserKey, user);
    } catch (e) {
      throw WriteFailedCacheException(
        instance: 'AuthLocalDataSource.setUser',
        detail: t.auth.cacheError.setUser(error: e.toString()),
      );
    }
  }

  @override
  Future<UserModel?> getUser() async {
    try {
      return _authBox.get(kUserKey) as UserModel?;
    } catch (e) {
      throw ReadFailedCacheException(
        instance: 'AuthLocalDataSource.getUser',
        detail: t.auth.cacheError.getUser(error: e.toString()),
      );
    }
  }

  @override
  Stream<UserModel?> watchUser() async* {
    try {
      // Emit the current value immediately, then stream all future changes
      yield _authBox.get(kUserKey) as UserModel?;

      await for (final event in _authBox.watch(key: kUserKey)) {
        yield event.value as UserModel?;
      }
    } catch (e) {
      throw ReadFailedCacheException(
        instance: 'AuthLocalDataSource.watchUser',
        detail: t.auth.cacheError.watchUser(error: e.toString()),
      );
    }
  }

  @override
  Future<void> clearUser() async {
    try {
      await _authBox.delete(kUserKey);
    } catch (e) {
      throw WriteFailedCacheException(
        instance: 'AuthLocalDataSource.clearUser',
        detail: t.auth.cacheError.clearUser(error: e.toString()),
      );
    }
  }
}

The watchUser() method is particularly useful. It yields the current stored value immediately when a subscriber starts listening, then continues yielding every time the Hive box emits a change event for that key. A BLoC or Provider widget can subscribe to this stream and reactively update the UI whenever the cached user changes, for example right after updateProfile writes new data.

Hive Initialization

Hive needs to be initialized once at app startup, before any box is accessed. Each module registers its own type adapters and opens its own box. For the auth module that looks like this:

/// Initializes Hive and opens all required boxes.
///
/// Called once in main() before runApp().
Future<void> initializeHive() async {
  final directory = await getApplicationDocumentsDirectory();
  Hive.init(directory.path);

  // Generated by hive_ce, registers all @HiveType annotated models
  Hive.registerAdapters();

  await Hive.openBox(kAuthBox);
}

The Hive.registerAdapters() call is code-generated. Every model annotated with @HiveType gets an adapter generated at build time. When a new module needs persistence, you add a new box constant, annotate its model class, run dart run build_runner build, and add the box to initializeHive().

Wiring It Up with Dependency Injection

The final piece is the DI container. This is where the proxy/decorator composition actually happens. The use case gets SettingsCachedRepository injected, which in turn gets SettingsRemoteRepository and AuthLocalDataSource injected:

// In the module's DI registration:
getIt.registerLazySingleton<ISettingsRepository>(
  () => SettingsCachedRepository(
    getIt<SettingsRemoteRepository>(),   // inner: talks to the API
    getIt<IAuthLocalDataSource>(),       // local storage layer
  ),
);

The use case asks for ISettingsRepository. It gets SettingsCachedRepository. That class forwards calls to SettingsRemoteRepository and then persists results through IAuthLocalDataSource. The entire chain is transparent to everything above it.

What I Got Out of It

A few things changed after putting this in place:

Use cases stayed clean. They call the repository interface and handle Either<Failure, T>. They have no idea that caching exists. If I want to add or remove caching from a module, I change one line in the DI registration, nothing else.
Cache writes never corrupt data. Because the decorator only persists on Right(...), the local storage is always consistent with a confirmed server response. A network failure means no write. A partial response means no write. The cache either has the full, validated data, or nothing.
The local data source is independently testable. AuthLocalDataSource takes a Box<dynamic> in its constructor. In tests, you pass a fake or in-memory box. You can verify that setUser writes the right key and that watchUser emits updates without spinning up any networking code.
Reactivity is free. Hive's box.watch(key: ...) stream means that any widget subscribed to watchUser() automatically sees changes the moment the decorator writes new data after a successful profile update. No manual notification, no separate state management event.

The pattern is not free. You end up with one more class per module that needs caching, and you have to be deliberate about which operations get cached and which do not. But that deliberateness is a feature. You are forced to think about what is worth persisting, what the staleness policy is, and what happens when the write fails. Each of those decisions ends up in one place, the cached repository, and nowhere else.

How to use the Specification Pattern to Clean Up Query Logic in C#, .NET

Mutombo jean-vincent — Tue, 26 May 2026 13:29:42 +0000

The Problem

I was building a content management platform with a .NET 9 backend. The platform manages videos, articles, lyrics, and a bunch of lookup tables. Pretty standard stuff. But the repository layer started getting ugly fast.

Every time I needed to query something, I was writing a new method on the repository. Need to find a video by ID? New method. By slug? Another method. By status? Another one. Search by title? You guessed it.

Here is what the video repository was starting to look like:

/// <summary>
/// Retrieves a video by its unique identifier.
/// </summary>
Task<VideoEntity?> GetByIdAsync(Guid id, CancellationToken ct);

/// <summary>
/// Retrieves a video by its URL-safe slug.
/// </summary>
Task<VideoEntity?> GetBySlugAsync(string slug, CancellationToken ct);

/// <summary>
/// Retrieves all videos matching a given content status.
/// </summary>
Task<List<VideoEntity>> GetByStatusAsync(EnumContentStatus status, CancellationToken ct);

/// <summary>
/// Retrieves all videos belonging to a given category.
/// </summary>
Task<List<VideoEntity>> GetByCategoryAsync(Guid categoryId, CancellationToken ct);

/// <summary>
/// Searches videos by title and description.
/// </summary>
Task<List<VideoEntity>> SearchAsync(string search, CancellationToken ct);

/// <summary>
/// Retrieves videos matching both a status and a category.
/// </summary>
Task<List<VideoEntity>> GetByStatusAndCategoryAsync(EnumContentStatus status, Guid categoryId, CancellationToken ct);

/// <summary>
/// Searches videos filtered by a given status.
/// </summary>
Task<List<VideoEntity>> SearchByStatusAsync(string search, EnumContentStatus status, CancellationToken ct);

// ... and it kept growing

The real pain was when I needed to combine filters. The admin panel lets you filter videos by status, by category, and search by text, all at the same time. Every combination of optional filters was becoming its own method, or worse, one giant method full of if statements:

/// <summary>
/// Retrieves a paginated list of videos with optional search, status, and category filters.
/// </summary>
/// <param name="search">Optional search term to filter by title and description.</param>
/// <param name="status">Optional content status filter.</param>
/// <param name="categoryId">Optional category filter.</param>
/// <param name="ct">Token to observe for cancellation requests.</param>
/// <returns>A list of matching video entities.</returns>
public async Task<List<VideoEntity>> GetAllAsync(
    string? search, EnumContentStatus? status, Guid? categoryId, CancellationToken ct)
{
    IQueryable<VideoEntity> query = context.Videos;

    if (!string.IsNullOrWhiteSpace(search))
    {
        string pattern = $"%{search}%";
        query = query.Where(v =>
            EF.Functions.ILike(v.Title, pattern) ||
            (v.Description != null && EF.Functions.ILike(v.Description, pattern)));
    }

    if (status.HasValue)
    {
        query = query.Where(v => v.Status == status.Value);
    }

    if (categoryId.HasValue)
    {
        query = query.Where(v => v.CategoryId == categoryId.Value);
    }

    return await query.ToListAsync(ct);
}

This works, but the filtering logic is buried inside the repository. You cannot reuse any of it. If the lyrics module needs the same search pattern, you copy paste the code. If you want to test whether a video matches certain criteria without hitting the database, you are stuck. And every time a new filter comes in, you are back in this method adding another if block.

I had the same problem across videos, articles, lyrics, tags, categories, pricing tiers, promotion levels, customers. Every module had its own version of this mess.

The Idea

I had read about the Specification pattern before but never actually used it in a real project. The idea is simple: take each filtering condition and turn it into its own class. Each class holds one rule, expressed as a Func<T, bool> (or more precisely, an Expression<Func<T, bool>> so Entity Framework can translate it to SQL). Then you compose these small classes together using And, Or, and Not.

Instead of the repository knowing about every possible filter combination, it just takes a specification and applies it. The caller decides what filters to use.

The Implementation

First, I defined a simple interface that every specification must implement:

/// <summary>
/// Represents a specification pattern that defines filtering criteria for objects of type T.
/// </summary>
/// <typeparam name="T">The type of object the specification applies to.</typeparam>
public interface ISpecification<T>
{
    /// <summary>
    /// Converts the specification into a LINQ expression.
    /// </summary>
    /// <returns>An expression that represents the filtering criteria.</returns>
    Expression<Func<T, bool>> ToExpression();

    /// <summary>
    /// Evaluates whether a given object satisfies the specification.
    /// </summary>
    /// <param name="entity">The object to evaluate.</param>
    /// <returns>True if the object satisfies the specification, otherwise false.</returns>
    bool IsSatisfiedBy(T entity);
}

Then I built the base class on top of it:

/// <summary>
/// Base class for defining specifications and composing them using logical operators.
/// </summary>
/// <typeparam name="T">The type the specification applies to.</typeparam>
public abstract class Specification<T> : ISpecification<T>
{
    /// <summary>
    /// Converts the specification into a LINQ expression tree.
    /// </summary>
    public abstract Expression<Func<T, bool>> ToExpression();

    /// <summary>
    /// Evaluates whether a given entity satisfies this specification in memory.
    /// </summary>
    /// <param name="entity">The entity to evaluate.</param>
    /// <returns>True if the entity matches the specification.</returns>
    public bool IsSatisfiedBy(T entity)
    {
        Func<T, bool> predicate = ToExpression().Compile();
        return predicate(entity);
    }

    /// <summary>
    /// Combines the current specification with another using logical AND.
    /// </summary>
    public Specification<T> And(Specification<T> other)
        => new AndSpecification<T>(this, other);

    /// <summary>
    /// Combines the current specification with another using logical OR.
    /// </summary>
    public Specification<T> Or(Specification<T> other)
        => new OrSpecification<T>(this, other);

    /// <summary>
    /// Inverts the current specification using logical NOT.
    /// </summary>
    public Specification<T> Not()
        => new NotSpecification<T>(this);
}

Two things to note here. The ToExpression() method returns an Expression tree, not a compiled delegate. This is important because EF Core needs the expression tree to translate it into SQL. If you just use Func<T, bool>, EF will pull every row from the database and filter in memory. Bad.

The IsSatisfiedBy method compiles the expression and runs it in memory. I use this in unit tests to verify that a specification matches or rejects a given entity without needing a database at all.

The And, Or, and Not methods return composite specifications that combine expression trees at the LINQ level. Here is how they work:

/// <summary>
/// Combines two specifications using logical AND.
/// </summary>
public class AndSpecification<T>(Specification<T> left, Specification<T> right) : Specification<T>
{
    /// <summary>
    /// Combines two specification expressions using logical AND.
    /// </summary>
    /// <returns>An expression that evaluates to true when both specifications are satisfied.</returns>
    public override Expression<Func<T, bool>> ToExpression()
    {
        Expression<Func<T, bool>> leftExpr = left.ToExpression();
        Expression<Func<T, bool>> rightExpr = right.ToExpression();

        ParameterExpression param = Expression.Parameter(typeof(T));
        BinaryExpression body = Expression.AndAlso(
            Expression.Invoke(leftExpr, param),
            Expression.Invoke(rightExpr, param)
        );

        return Expression.Lambda<Func<T, bool>>(body, param);
    }
}

/// <summary>
/// Combines two specifications using logical OR.
/// </summary>
public class OrSpecification<T>(Specification<T> left, Specification<T> right) : Specification<T>
{
    /// <summary>
    /// Combines two specification expressions using logical OR.
    /// </summary>
    /// <returns>An expression that evaluates to true when either specification is satisfied.</returns>
    public override Expression<Func<T, bool>> ToExpression()
    {
        Expression<Func<T, bool>> leftExpr = left.ToExpression();
        Expression<Func<T, bool>> rightExpr = right.ToExpression();

        ParameterExpression param = Expression.Parameter(typeof(T));
        BinaryExpression body = Expression.OrElse(
            Expression.Invoke(leftExpr, param),
            Expression.Invoke(rightExpr, param)
        );

        return Expression.Lambda<Func<T, bool>>(body, param);
    }
}

/// <summary>
/// Inverts a specification using the logical NOT.
/// </summary>
public class NotSpecification<T> : Specification<T>
{
    private readonly Specification<T> _inner;

    /// <summary>
    /// Initializes a new instance of the NotSpecification class.
    /// </summary>
    /// <param name="inner">The specification to negate.</param>
    public NotSpecification(Specification<T> inner)
    {
        _inner = inner;
    }

    /// <summary>
    /// Inverts the inner specification expression using logical NOT.
    /// </summary>
    /// <returns>An expression that evaluates to true when the inner specification is not satisfied.</returns>
    public override Expression<Func<T, bool>> ToExpression()
    {
        Expression<Func<T, bool>> innerExpr = _inner.ToExpression();
        ParameterExpression param = Expression.Parameter(typeof(T));
        UnaryExpression body = Expression.Not(Expression.Invoke(innerExpr, param));

        return Expression.Lambda<Func<T, bool>>(body, param);
    }
}

These three classes are the glue. They take expression trees and stitch them together using Expression.AndAlso, Expression.OrElse, and Expression.Not. EF Core sees the final composed expression and translates the whole thing to SQL. No in-memory evaluation.

With those in place, I created concrete specifications for each filter. For videos:

/// <summary>
/// Specification that matches a video by its unique identifier.
/// </summary>
public class VideoByIdSpecification(Guid id) : Specification<VideoEntity>
{
    /// <inheritdoc />
    public override Expression<Func<VideoEntity, bool>> ToExpression()
    {
        return video => video.Id == id;
    }
}

/// <summary>
/// Specification that matches videos by their content status.
/// </summary>
public class VideoByStatusSpecification(EnumContentStatus status) : Specification<VideoEntity>
{
    /// <inheritdoc />
    public override Expression<Func<VideoEntity, bool>> ToExpression()
    {
        return video => video.Status == status;
    }
}

/// <summary>
/// Specification for full-text search across video Title, Description,
/// MetaTitle, and MetaDescription fields.
/// Uses case-insensitive matching (ILIKE in PostgreSQL).
/// </summary>
public class VideoSearchSpecification(string search) : Specification<VideoEntity>
{
    /// <inheritdoc />
    public override Expression<Func<VideoEntity, bool>> ToExpression()
    {
        string pattern = $"%{search}%";
        return video =>
            EF.Functions.ILike(video.Title, pattern)
            || (video.Description != null && EF.Functions.ILike(video.Description, pattern))
            || (video.MetaTitle != null && EF.Functions.ILike(video.MetaTitle, pattern))
            || (video.MetaDescription != null && EF.Functions.ILike(video.MetaDescription, pattern));
    }
}

Each one is tiny. Each one does exactly one thing. And they are all testable on their own.

To apply them to EF Core queries, I wrote an extension method:

/// <summary>
/// Applies a specification to an IQueryable, converting it to a Where clause.
/// Bridges the Specification pattern with EF Core queries.
/// </summary>
/// <typeparam name="T">The entity type.</typeparam>
/// <param name="query">The queryable to apply the specification to.</param>
/// <param name="specification">The specification containing the filtering logic.</param>
/// <returns>A filtered queryable based on the specification criteria.</returns>
public static IQueryable<T> ApplySpecification<T>(
    this IQueryable<T> query, ISpecification<T> specification)
{
    return query.Where(specification.ToExpression());
}

One line. The specification turns into a .Where() clause. EF Core translates the expression tree into a SQL WHERE clause. No in-memory filtering.

Composing Filters with a Builder

The specifications handle individual rules, but I still needed a clean way to combine optional filters. I did not want the repository method to go back to a chain of if statements. So I defined a builder interface per module:

/// <summary>
/// Interface for building dynamic video queries using specifications.
/// Implements the Builder pattern to construct complex queries without conditional logic.
/// </summary>
public interface IVideoQueryBuilder
{
    /// <summary>
    /// Adds a full-text search filter across Title, Description, MetaTitle, and MetaDescription.
    /// </summary>
    IVideoQueryBuilder WithSearch(string? search);

    /// <summary>
    /// Adds a content status filter to the query.
    /// </summary>
    IVideoQueryBuilder WithStatus(EnumContentStatus? status);

    /// <summary>
    /// Adds a category filter to the query.
    /// </summary>
    IVideoQueryBuilder WithCategory(Guid? categoryId);

    /// <summary>
    /// Builds and returns the final specification.
    /// Returns null if no filters were applied.
    /// </summary>
    Specification<VideoEntity>? Build();
}

Then the implementation:

/// <summary>
/// Builder for constructing dynamic video queries using specifications.
/// Implements the Builder pattern to eliminate conditional logic in query construction.
/// </summary>
public class VideoQueryBuilder : IVideoQueryBuilder
{
    private Specification<VideoEntity>? _specification;

    /// <summary>
    /// Adds a full-text search filter if the search term is not empty.
    /// </summary>
    /// <param name="search">Optional search term.</param>
    public IVideoQueryBuilder WithSearch(string? search)
    {
        if (string.IsNullOrWhiteSpace(search)) return this;

        var searchSpec = new VideoSearchSpecification(search);
        CombineSpecification(searchSpec);
        return this;
    }

    /// <summary>
    /// Adds a content status filter if a status is provided.
    /// </summary>
    /// <param name="status">Optional content status.</param>
    public IVideoQueryBuilder WithStatus(EnumContentStatus? status)
    {
        if (!status.HasValue) return this;

        var statusSpec = new VideoByStatusSpecification(status.Value);
        CombineSpecification(statusSpec);
        return this;
    }

    /// <summary>
    /// Adds a category filter if a category ID is provided.
    /// </summary>
    /// <param name="categoryId">Optional category identifier.</param>
    public IVideoQueryBuilder WithCategory(Guid? categoryId)
    {
        if (!categoryId.HasValue) return this;

        var categorySpec = new VideoByCategorySpecification(categoryId.Value);
        CombineSpecification(categorySpec);
        return this;
    }

    /// <summary>
    /// Builds the final composed specification, or null if no filters were added.
    /// </summary>
    public Specification<VideoEntity>? Build()
    {
        return _specification;
    }

    /// <summary>
    /// Combines a new specification with the existing one using logical AND.
    /// </summary>
    private void CombineSpecification(Specification<VideoEntity> spec)
    {
        _specification = _specification is null ? spec : _specification.And(spec);
    }
}

The builder chains optional filters. If a parameter is null or empty, it skips that filter. If multiple filters are provided, it combines them with And. The repository just calls Build() and applies the result:

/// <summary>
/// Retrieves a paginated list of videos using the specification builder.
/// </summary>
/// <param name="page">The 1-based page number.</param>
/// <param name="pageSize">The number of items per page.</param>
/// <param name="search">Optional search term.</param>
/// <param name="status">Optional content status filter.</param>
/// <param name="categoryId">Optional category filter.</param>
/// <param name="ct">Token to observe for cancellation requests.</param>
/// <returns>A tuple containing the list of videos and the total count.</returns>
public async Task<(List<VideoEntity>, int)> GetAllAsync(
    int page, int pageSize, string? search,
    EnumContentStatus? status, Guid? categoryId,
    CancellationToken ct)
{
    IQueryable<VideoEntity> query = context.Videos;

    Specification<VideoEntity>? spec = new VideoQueryBuilder()
        .WithSearch(search)
        .WithStatus(status)
        .WithCategory(categoryId)
        .Build();

    if (spec is not null)
    {
        query = query.ApplySpecification(spec);
    }

    int totalCount = await query.CountAsync(ct);
    List<VideoEntity> videos = await query
        .Skip((page - 1) * pageSize)
        .Take(pageSize)
        .ToListAsync(ct);

    return (videos, totalCount);
}

No if chains in the repository. No conditional logic at all. The builder handles all of that.

Testing

This is where the pattern really paid off. Testing a specification does not require a database. You just create an entity in memory and call IsSatisfiedBy:

/// <summary>
/// Verifies that a video in Draft status satisfies the Draft specification.
/// </summary>
[Fact]
public void VideoByStatusSpecification_WithMatchingStatus_ShouldReturnTrue()
{
    // Arrange
    VideoEntity video = VideoFactory.Create(categoryId);
    var spec = new VideoByStatusSpecification(EnumContentStatus.Draft);

    // Act
    bool result = spec.IsSatisfiedBy(video);

    // Assert
    result.Should().BeTrue();
}

/// <summary>
/// Verifies that a published video does not satisfy the Draft specification.
/// </summary>
[Fact]
public void VideoByStatusSpecification_WithDifferentStatus_ShouldReturnFalse()
{
    // Arrange
    VideoEntity video = VideoFactory.CreatePublished(categoryId);
    var spec = new VideoByStatusSpecification(EnumContentStatus.Draft);

    // Act
    bool result = spec.IsSatisfiedBy(video);

    // Assert
    result.Should().BeFalse();
}

Fast, deterministic, no database setup. I can verify that ActiveVideoSpecification correctly excludes archived and rejected videos without spinning up an in-memory database or mocking anything.

For specifications that use EF.Functions.ILike (which only works with a real PostgreSQL provider), I at least test that the expression compiles:

/// <summary>
/// Verifies that the search specification produces a valid compilable expression.
/// ILike requires PostgreSQL, so we only verify compilation here.
/// </summary>
[Fact]
public void VideoSearchSpecification_ShouldCompileExpression()
{
    // Arrange
    var spec = new VideoSearchSpecification("test");

    // Act
    Func<VideoEntity, bool> predicate = spec.ToExpression().Compile();

    // Assert
    predicate.Should().NotBeNull();
}

Not a full integration test, but it catches expression tree errors at compile time rather than at runtime.

What I Got Out of It

After rolling this out across all modules, a few things changed:

Repository methods got shorter. Instead of growing a new method for every filter combination, each repository has a small set of generic methods that accept specifications. The GetAllAsync method on every repository looks almost identical.
The filtering logic is reusable. The VideoSearchSpecification works whether you call it from the admin panel, a public API, or a background job. Same class, same SQL, same behavior.
New filters are trivial to add. When I needed an ActiveVideoSpecification to exclude archived and rejected videos from a dropdown, I created one small class and was done. No repository changes. No handler changes. Just a new specification.
Composition works naturally. Need active videos in a specific category? activeSpec.And(categorySpec). Need published or featured videos? publishedSpec.Or(featuredSpec). The And, Or, and Not operators handle it.
Unit tests are fast. I have nearly 100 specification tests across the project and they all run in under a second because none of them hit a database.

The pattern is not free. You end up with more files. A module that had one repository class now has a specifications folder with 5 to 10 small classes, plus a builder. But each file is 10 to 15 lines, does one thing, and is independently testable. I will take that over a 200-line repository method with nested conditionals any day.