cool_bedrock 3.0.0

A bedrock package providing the blueprints and abstract definitions necessary to build a scalable and maintainable Dart/Flutter application.

cool_bedrock

A bedrock package providing the blueprints and abstract definitions necessary to build a scalable and maintainable Dart/Flutter application.

---

✨ Features

• 🏛️ Formalized Architecture: Strict base contracts for all layers: Entity, Params, AppService, and Codable.
• 🎯 Domain Logic (Use Cases): Typified UseCase hierarchy for commands and queries, including assisted flow management (UseCaseHandler).
• 🛡️ Functional Error Handling: Leverages the functional types Either<Failure, T> and Option
• 🛑 Typed Errors: Coherent error structure using sealed base classes: Issue, Failure (business logic), RepositoryError, and DataSourceException (technical/infrastructure).
• 🔄 Reactive Services: Base classes for creating services that manage state using BehaviorSubject, PublishSubject, and periodic execution logic (Timer).
• 🧪 Immutability & Testability: All core domain structures (Entity, Params) are immutable and comparable (Equatable).

🚀 Installation

Requires Dart >=3.13.0.

Add the package to your pubspec.yaml:

dependencies:
  cool_bedrock: ^3.0.0

Then run:

dart pub get

📆 Usage

Basic usage

import 'package:cool_bedrock/cool_bedrock.dart';

1. Creating the Use Case

This example demonstrates how to implement a UseCase, defining its specific Failure and parameter validation:

// 1. Define the domain types: params, entity and the raw remote model.
final class FetchUserParams extends Params {
  const FetchUserParams({required this.userId});

  final String userId;

  // Checked automatically before executing the usecase.
  @override
  bool get isValid => userId.isNotEmpty;

  @override
  List<Object?> get props => [userId];
}

final class UserRemote {
  const UserRemote({this.name});

  final String? name;

  UserEntity toEntity() => UserEntity(name: name ?? 'Unknown');
}

final class UserEntity extends Entity {
  const UserEntity({required this.name});

  final String name;

  @override
  List<Object?> get props => [name];
}

// In this example the repository returns a Future<Either<Failure, UserRemote>>.

// 2. Define the specific Failure for this domain
sealed class FetchUserFailure extends Failure {
  const FetchUserFailure({super.message});
}

final class InvalidUserFailure extends FetchUserFailure {
  const InvalidUserFailure() : super(message: 'Invalid User ID provided.');

  @override
  List<Object?> get props => [message];
}

final class InvalidParamsUserFailure extends FetchUserFailure {
  const InvalidParamsUserFailure()
      : super(message: 'Invalid parameters provided.');

  @override
  List<Object?> get props => [message];
}

// 3. Implement the UseCase contract
final class FetchUserUseCase
    extends UseCase<UserEntity, FetchUserParams, FetchUserFailure> {
  const FetchUserUseCase(this.repository);

  final UserRepository repository;

  // Called automatically if params.isNotValid is true.
  @override
  FetchUserFailure onInvalidParams() => const InvalidParamsUserFailure();

  @override
  Future<Either<FetchUserFailure, UserEntity>> execute(
    FetchUserParams params,
  ) async {
    // Core logic goes here. Mappers and Repositories are typically called here.
    try {
      final result = await repository.fetch(params.userId);
      return result.fold(
        // Map the repository failure to a domain failure
        (failure) => const Left(InvalidUserFailure()),
        // Map the remote model to the entity
        (remote) => Right(remote.toEntity()),
      ); // Success
    } catch (e) {
      // Map low-level errors to high-level domain failures
      return const Left(InvalidUserFailure()); // Failure
    }
  }
}

// 4. Or use the Handler: obtain -> transform -> map errors
final class FetchUserUseCaseHandle
    extends UseCaseHandler<
      UserEntity,
      FetchUserParams,
      FetchUserFailure,
      UserRemote
    > {
  const FetchUserUseCaseHandle({required this.repository});

  final UserRepository repository;

  // Called automatically if params.isNotValid is true.
  @override
  FetchUserFailure onInvalidParams() => const InvalidParamsUserFailure();

  // Obtain repository values. Multiple repositories can be called.
  @override
  FutureOr<UserRemote> obtainValues(
    Resolver<FetchUserFailure> $,
    FetchUserParams params,
  ) async {
    // getValue unwraps a Future<Either<Issue, VALUE>> and maps its errors.
    return await $(getValue(() => repository.fetch(params.userId)));
  }

  @override
  UserEntity transformation(UserRemote values) {
    if (values.name == null || values.name!.isEmpty) {
      throw const UsecaseException(InvalidUserFailure());
    }
    // It can throw any exception, it will be handled by [wrapError].
    return values.toEntity();
  }

  @override
  FetchUserFailure wrapError(Object error, StackTrace stackTrace) {
    return const InvalidUserFailure();
  }
}

2. Execution and Error Handling

// Execution with valid parameters
const validParams = FetchUserParams(userId: 'user_123');
final validResult = await fetchUserUsecase.call(validParams);

validResult.fold(
  // LEFT side (Failure)
  (failure) => print('Error: ${failure.message}'),
  // RIGHT side (Success)
  (user) => print('Fetched User: ${user.name}'),
);

💡 Reactive Services Example

The base services provide lifecycle control and reactivity. Here's a service that periodically updates a counter:

import 'package:cool_bedrock/cool_bedrock.dart';
import 'dart:async';

final class HeartbeatService extends TimerAndBehaviorService<int> {
  HeartbeatService()
      : super(periodicDuration: const Duration(seconds: 10));

  int _counter = 0;

  @override
  Future<void> work() async {
    // Logic that runs every 10 seconds
    _counter++;
    // Emit the new value to all subscribers
    add(_counter);
  }

  // start(), stop(), and dispose() logic is inherited and controlled externally.
}

---

🏗️ Use Case Types Comparison

Choosing the right base class ensures your business logic is expressive and safe. Use this table as a quick guide to decide which one fits your needs:

Use Case Type	Success Return	Error Return	Best For...
UseCase	Right(Entity)	Left(Failure)	Standard business logic with manual error mapping.
UseCaseHandler	Right(Entity)	Left(Failure)	Business logic with data fetching, transformation and error mapping.
OneWayUseCase	Some(Entity)	None	Queries where the absence of a value is a valid result (e.g., Search).
OneWayFailureUseCase	None (Success)	Some(Failure)	Standalone validations and guard checks (e.g., Is email taken?).

---

📚 API Reference

Check the full API reference, including all generic types and abstract classes, on pub.dev → cool_bedrock.

---

Authors & Maintainers

This project was created and is primarily maintained by:

• Cayetano Bañón Rubio
• Coolosos

🤝 Contributing

Contributions are welcome!

• Open issues for bugs or feature requests
• Fork the repo and submit a PR
• Run dart format and dart test before submitting

---

🧪 Testing

To run tests and see code coverage:

dart test

---

📄 License

MIT © 2025 Coolosos