Family Providers & Dynamic Filter Architecture (shipment_providers.dart)

1. Why Does This File Exist?

In Transwave, travelers browse available package shipments based on complex criteria: departure/destination country, city, price range, weight limit, urgency, and geographic bounding box coordinates.

2. Who Uses This File? (Codebase Search)

3. Dependency Graph

4. Execution Timeline

5. Provider Lifecycle

Because shipmentListProvider is annotated with @riverpod, Riverpod creates an AutoDisposeFutureProviderFamily. When all widgets watching a specific filter selection unmount (e.g. user leaves the list screen), Riverpod schedules auto-disposal to free up device memory.

Special Section A: Family Parameter Equality Breakdown (operator == & hashCode)

This is the most critical Riverpod rule when working with Family providers accepting custom objects:

class ShipmentListFilters {
  const ShipmentListFilters({
    this.status,
    this.category,
    this.departureCountry,
    this.destinationCountry,
    this.minPriceCents,
    this.maxPriceCents,
    this.page = 1,
    this.limit = 20,
  });

  final ShipmentStatus? status;
  final String? category;
  final String? departureCountry;
  final String? destinationCountry;
  final int? minPriceCents;
  final int? maxPriceCents;
  final int page;
  final int limit;

  @override
  bool operator ==(Object other) =>
      identical(this, other) ||
      other is ShipmentListFilters &&
          runtimeType == other.runtimeType &&
          status == other.status &&
          category == other.category &&
          departureCountry == other.departureCountry &&
          destinationCountry == other.destinationCountry &&
          minPriceCents == other.minPriceCents &&
          maxPriceCents == other.maxPriceCents &&
          page == other.page &&
          limit == other.limit;

  @override
  int get hashCode => Object.hash(
        status,
        category,
        departureCountry,
        destinationCountry,
        minPriceCents,
        maxPriceCents,
        page,
        limit,
      );
}

Special Section B: Integer Currency Protocol (EUR Cents)

In compliance with Transwave Architectural Commandment #9, all API monetary values are transmitted and stored as integer EUR cents (e.g., €15.50 is stored as 1550).

6. Alternative Designs Comparison

7. Performance & Memory Analysis

Family providers create a distinct sub-provider instance for each unique parameter hash. Using autoDispose ensures that as soon as the user exits the marketplace screen, all cached shipment arrays and provider instances are evicted from device RAM.

8. Testing Strategy

Unit testing family providers is straightforward. Create a ProviderContainer, override shipmentRepositoryProvider with a mock implementation, and call container.read(shipmentListProvider(myFilters).future). Verify that passing equal filter objects returns the same cached future!

Special Section J: 15 Senior Flutter Interview Questions & Answers