Production Flutter Networking Without the Boilerplate: Reactive Repositories with BlocSignal

┌────────────────────────────────────────────────────────────────────────┐
│               Traditional Flutter Networking Pipeline                  │
├────────────────────────────────────────────────────────────────────────┤
│ [Dio / HTTP Client] ─▶ [API Service] ─▶ [Repository Layer] ─▶          │
│                      [Cubit / BLoC] ─▶ [UI Builders & Banners]         │
└────────────────────────────────────────────────────────────────────────┘

class UserProfileService {
  UserProfileService(this._dio);
  final Dio _dio;

  Future<UserProfile> fetchUserProfile(String userId) async {
    final response = await _dio.get('/users/\$userId');
    return UserProfile.fromJson(response.data as Map<String, dynamic>);
  }
}

// Converts Future<UserProfile> into a synchronous BlocSignalBase<AsyncState<UserProfile>>
final userProfileBloc = profileService
    .fetchUserProfile('user_123')
    .toAsyncBlocSignal();

BlocSignalBuilder<BlocSignalBase<AsyncState<UserProfile>>, AsyncState<UserProfile>>(
  bloc: userProfileBloc,
  builder: (context, state) => switch (state) {
    AsyncLoading() => const Center(
        child: CircularProgressIndicator(),
      ),
    AsyncData(:final value) => ProfileDetailsView(user: value),
    AsyncError(:final error) => ErrorCard(
        message: error.toString(),
      ),
  },
)

import 'package:bloc_signals/bloc_signals.dart';
import 'package:bloc_signals_hydrate/bloc_signals_hydrate.dart';
import 'package:dio/dio.dart';

/// A production domain repository extending BaseApiClient with 0ms reactivity & disk caching!
class ProductRepository extends BaseApiClient
    with
        CubitSignalMixin<AsyncState<List<Product>>>,
        HydratedMixin<AsyncState<List<Product>>> {
  ProductRepository(super.dio) {
    // 1. Initialize reactive signal container
    initCubitSignal(initialState: const AsyncLoading());

    // 2. Initialize Frame-1 persistent storage cache
    initHydrated(storageKey: 'cached_products_v1');
  }

  /// Refreshes data from the network using toFutureSignal to eliminate try-catch
  Future<void> refresh() async {
    emit(const AsyncLoading());

    // ⚡ toFutureSignal automatically projects success into AsyncData and exceptions into AsyncError!
    final fetchSignal = _fetchProducts().toFutureSignal();
    await fetchSignal.future;
    emit(fetchSignal.value);
  }

  Future<List<Product>> _fetchProducts() async {
    final response = await dio.get('/products');
    final rawList = response.data as List<dynamic>;
    return [
      for (final item in rawList) Product.fromJson(item as Map<String, dynamic>),
    ];
  }

  // 💾 Pattern matching for instant offline hydration:
  @override
  Object? toJson(AsyncState<List<Product>> state) => switch (state) {
        AsyncData(:final value) => [
            for (final product in value) product.toJson(),
          ],
        _ => null,
      };

  @override
  AsyncState<List<Product>>? fromJson(dynamic json) => switch (json) {
        {'products': List<dynamic> list} => AsyncData([
            for (final item in list) Product.fromJson(item as Map<String, dynamic>),
          ]),
        List<dynamic> list => AsyncData([
            for (final item in list) Product.fromJson(item as Map<String, dynamic>),
          ]),
        _ => null,
      };
}

sealed class SearchEvent {
  const SearchEvent();
}

final class SearchQueryChanged extends SearchEvent {
  const SearchQueryChanged(this.query);
  final String query;
}

class SearchRepository extends BaseApiClient
    with
        CubitSignalMixin<AsyncState<List<SearchResult>>>,
        BlocSignalMixin<SearchEvent, AsyncState<List<SearchResult>>> {
  SearchRepository(super.dio) {
    initCubitSignal(initialState: const AsyncData([]));

    // ⚡ Built-in concurrency control: automatically aborts prior in-flight queries!
    on<SearchQueryChanged>((event, emit) async {
      final query = event.query.trim();
      if (query.isEmpty) {
        emit(const AsyncData([]));
        return;
      }

      emit(const AsyncLoading());
      final searchSignal = _executeSearch(query).toFutureSignal();
      await searchSignal.future;
      emit(searchSignal.value);
    }, transformer: restartable());
  }

  Future<List<SearchResult>> _executeSearch(String query) async {
    final response = await dio.get('/search', queryParameters: {'q': query});
    final results = response.data as List<dynamic>;
    return [
      for (final item in results) SearchResult.fromJson(item as Map<String, dynamic>),
    ];
  }
}

┌──────────────────────────────┬────────────────────────┬────────────────────────┐
│ Architectural Concern        │ Traditional Flutter    │ BlocSignal Ecosystem   │
├──────────────────────────────┼────────────────────────┼────────────────────────┤
│ Async State Representation   │ 4 custom classes/enums │ AsyncState<T> sealed   │
│ In-Flight Race Conditions    │ Dio CancelToken / Rx   │ restartable() builtin  │
│ Duplicate Tap Protection     │ Custom boolean flags   │ droppable() builtin    │
│ Frame-1 Offline Persistence  │ SQLite / SharedPreferences│ HydratedMixin frame-1│
│ Existing Base Class Interop  │ Proxy/Wrapper classes  │ CubitSignalMixin       │
└──────────────────────────────┴────────────────────────┴────────────────────────┘