UseCase Patterns

UseCase is a core component of Clean Architecture that encapsulates business logic.

Reference location: .claude/references/patterns/usecase-patterns.md

UseCase is a core component of Clean Architecture that encapsulates business logic.

Standard Pattern#

Pattern	Description
Optional Constructor Injection	✅ Standard pattern - Easy mock injection, no getIt dependency

Future UseCase (Single Request)#

UseCase Definition#

// domain/usecase/get_user_usecase.dart
class GetUserUseCase {
  /// [GetUserUseCase]를 생성합니다.
  const GetUserUseCase([IUserRepository? repository])
      : _repo = repository ?? const UserRepository();

  final IUserRepository _repo;

  Future<Either<Failure, User>> call(GetUserParams params) async {
    return _repo.getUser(params.id);
  }
}

class GetUserParams {
  const GetUserParams({required this.id});
  final int id;
}

Usage in BLoC (DI Decoupling)#

class UserBloc extends BlocSignal<UserEvent, UserState> {
  UserBloc({
    GetUserUseCase? getUserUseCase,
  }) : _getUserUseCase = getUserUseCase ?? const GetUserUseCase(),
       super(initialState: const UserInitial()) {
    on<UserLoad>(_onLoad);
  }

  final GetUserUseCase _getUserUseCase;

  Future<void> _onLoad(UserLoad event, void Function(UserState) emit) async {
    emit(const UserLoading());

    final result = await _getUserUseCase(
      GetUserParams(id: event.userId),
    );

    if (isClosed) return; // await 후 체크 필수!

    result.fold(
      (failure) => emit(UserError(failure: failure)),
      (user) => emit(UserLoaded(user: user)),
    );
  }
}

Tests#

class MockGetUserUseCase extends Mock implements GetUserUseCase {}

blocSignalTest<UserBloc, UserState>(
  'emits [loading, loaded] when load succeeds',
  setUp: () {
    when(() => mockGetUser(any()))
        .thenAnswer((_) async => right(testUser));
  },
  build: () => UserBloc(getUserUseCase: mockGetUser),
  act: (bloc) => bloc.add(const UserLoad(userId: 1)),
  expect: () => [
    const UserLoading(),
    UserLoaded(user: testUser),
  ],
);

Stream UseCase (SWR/Cache-First)#

A Stream-based UseCase that sequentially emits cached data and server data.

StreamUseCase Interface#

/// Stream 기반 UseCase (SWR 패턴용)
abstract class StreamUseCase<T, Params, Repo> {
  Repo get repo;
  Stream<Either<Failure, T>> call(Params param);
}

StreamUseCase Implementation#

class GetItemsStreamUseCase
    implements StreamUseCase<List<Item>, GetItemsParams, IItemRepository> {
  const GetItemsStreamUseCase([IItemRepository? repository])
      : _repository = repository ?? const ItemRepository();

  final IItemRepository _repository;

  @override
  IItemRepository get repo => _repository;

  @override
  Stream<Either<Failure, List<Item>>> call(GetItemsParams params) {
    return repo.getItemsWithCache(categoryId: params.categoryId);
  }
}

Usage in BlocSignal: container-owned subscription + restartable()#

⚠️ emit.forEach does not exist in bloc_signals. Own the StreamSubscription and cancel it in close().

import 'package:bloc_signals/bloc_signals.dart';

class ItemBloc extends BlocSignal<ItemEvent, ItemState> {
  ItemBloc({
    GetItemsStreamUseCase? getItemsStream,
  }) : _getItemsStream = getItemsStream ?? const GetItemsStreamUseCase(),
       super(initialState: const ItemState()) {
    on<_Load>(
      _onLoad,
      transformer: restartable(),  // superseded 실행의 emission 폐기
    );
  }

  final GetItemsStreamUseCase _getItemsStream;
  StreamSubscription<Either<Failure, List<Item>>>? _itemsSub;

  Future<void> _onLoad(_Load event, void Function(ItemState) emit) async {
    if (stateValue.items.isEmpty) {
      emit(stateValue.copyWith(status: LoadingStatus.loading));
    }

    await _itemsSub?.cancel();

    _itemsSub = _getItemsStream(
      GetItemsParams(categoryId: event.categoryId),
    ).listen((result) {
      if (isClosed) return;
      emit(result.fold(
        (failure) => stateValue.copyWith(
          status: LoadingStatus.error,
          failure: failure,
        ),
        (items) => stateValue.copyWith(
          status: LoadingStatus.loaded,
          items: items,
          lastUpdated: DateTime.now(),
        ),
      ));
    });
  }

  @override
  Future<void> close() async {
    if (isClosed) return;
    await _itemsSub?.cancel(); // ⚠️ no automatic cleanup
    await super.close();
  }
}

How restartable() Works

1. add(_Load(categoryId: 1))  → 스트림A 구독 (캐시 → 서버 순차 yield)
2. add(_Load(categoryId: 2))  → 핸들러가 _itemsSub.cancel() 로 스트림A 해제
                               → 스트림B 구독 시작
                               → restartable() 은 핸들러1 의 늦은 emission 을 폐기

⚠️ bloc_signals' restartable() only discards emissions from the superseded execution — it does not cancel the stream subscription. Holding the StreamSubscription on the container and cancelling it in a close() override is required; there is no automatic cleanup. See swr-pattern.

Repository SWR Stream Implementation#

@override
Stream<Either<Failure, List<Item>>> getItemsWithCache({
  required int categoryId,
}) async* {
  // 1. 캐시 데이터 즉시 yield
  final cached = await _itemDao.getByCategoryId(categoryId);
  if (cached != null && cached.isNotEmpty) {
    yield right(cached.map((e) => e.toDomain()).toList());
  }

  // 2. 서버 데이터 fetch → yield
  try {
    final remote = await _client.item.getItems(categoryId: categoryId);
    await _itemDao.upsertAll(remote.map((e) => e.toLocal()).toList());
    yield right(remote);
  } on Exception catch (error, stackTrace) {
    if (cached == null || cached.isEmpty) {
      yield left(ItemFailure(message: error.toString()));
    }
    // Ignore error if cache existed (cached data already displayed)
    Log.e('서버 갱신 실패', error: error, stackTrace: stackTrace);
  }
}

Stream Test#

class MockGetItemsStreamUseCase extends Mock implements GetItemsStreamUseCase {}

blocSignalTest<ItemBloc, ItemState>(
  'emits cached then fresh data via SWR stream',
  setUp: () {
    when(() => mockGetItemsStream(any())).thenAnswer(
      (_) => Stream.fromIterable([
        right(cachedItems),
        right(freshItems),
      ]),
    );
  },
  build: () => ItemBloc(getItemsStream: mockGetItemsStream),
  act: (bloc) => bloc.add(const ItemEvent.load(categoryId: 1)),
  expect: () => [
    ItemState(status: LoadingStatus.loading),
    ItemState(status: LoadingStatus.loaded, items: cachedItems),
    ItemState(status: LoadingStatus.loaded, items: freshItems),
  ],
);

UseCase Bundle (8 or more)#

When constructor parameters become numerous, group them into a Bundle class.

class DashboardUseCases {
  const DashboardUseCases({
    GetStatsUseCase? getStats,
    GetChartDataUseCase? getChartData,
    GetRecentItemsUseCase? getRecentItems,
  }) : getStats = getStats ?? const GetStatsUseCase(),
       getChartData = getChartData ?? const GetChartDataUseCase(),
       getRecentItems = getRecentItems ?? const GetRecentItemsUseCase();

  final GetStatsUseCase getStats;
  final GetChartDataUseCase getChartData;
  final GetRecentItemsUseCase getRecentItems;
}

class DashboardBloc extends BlocSignal<DashboardEvent, DashboardState> {
  DashboardBloc({DashboardUseCases? useCases})
      : _useCases = useCases ?? const DashboardUseCases(),
        super(initialState: const DashboardState()) {
    on<_Load>(_onLoad);
  }

  final DashboardUseCases _useCases;
}

Selection Guide#

데이터 흐름?
├── 단건 요청 → Future UseCase
└── 캐시+서버 순차 → Stream UseCase + 컨테이너 소유 구독 + restartable()

UseCase injection → Optional Constructor Injection (standard)

UseCase 개수?
├── 1~7개 → 개별 생성자 파라미터
└── 8개+ → UseCase Bundle 패턴

Referencing Agents#

/cc-flutter:feature:domain - Domain Layer Generation
/feature:bloc - BLoC state management
/cc-flutter:feature:presentation - Presentation Layer generation