diff --git a/packages/leancode_cubit_utils/README.md b/packages/leancode_cubit_utils/README.md index fabc9e9..81cd0b5 100644 --- a/packages/leancode_cubit_utils/README.md +++ b/packages/leancode_cubit_utils/README.md @@ -19,16 +19,20 @@ Implementation of cubits for handling [CQRS](https://pub.dev/packages/cqrs) quer ## Single Request Utils -### `handleResult` +### `RequestCubit` -`handleResult` is a client-specific method needed for handling the API response. It can be defined once and used repeatedly as a mixin. +`RequestCubit` is used to execute a single API request. It has four generic arguments: TRes, TData, TOut and TError. TRes specifies what the request returns, TData specifies what is kept in TRes as response body, TOut determines which model we want to emit as data in the state, TError defines error's type. In the example below, `HttpRequestCubit` provides the generic http implementation that can be used while defining all needed `RequestCubits`. ```dart -mixin HandleResult - on RequestCubit { +/// Base class for http request cubits. +abstract class HttpRequestCubit + extends RequestCubit { + HttpRequestCubit(super.loggerTag, {required this.client}); + + final http.Client client; + @override - // In this method we check the request's state - // and return the result on success or call handleError on failure. + /// Client-specific method needed for handling the API response. Future> handleResult( http.Response result, ) async { @@ -50,21 +54,15 @@ mixin HandleResult } ``` -### `RequestCubit` - -`RequestCubit` is used to execute a single API request. Example implementation of RequestCubit looks like this: +Example implementation of `RequestCubit` using defined `HttpRequestCubit` looks like this: ```dart -// RequestCubit has four generic arguments: TRes, TData, TOut and TError. TRes specifies what the request returns, TData specifies what is kept in TRes as response body, TOut determines which model we want to emit as data in the state, TError defines error's type. -class ProjectDetailsCubit - extends RequestCubit - with HandleResult { +class ProjectDetailsCubit extends HttpRequestCubit { ProjectDetailsCubit({ - required this.client, + required super.client, required this.id, }) : super('ProjectDetailsCubit'); - final http.Client client; final String id; @override @@ -73,11 +71,9 @@ class ProjectDetailsCubit ProjectDetailsDTO.fromJson(jsonDecode(data) as Map); @override - // In this method we should perform the request and return it in form of http.Response. - // http.Response is then internally handled by handleResult. - Future request() { - return client.get(Uri.parse('base-url/$id')); - } + // In this method we should perform the request and return it in form of http.Response + // which is then internally handled by handleResult. + Future request() => client.get(Uri.parse('base-url/$id')); } ``` @@ -276,14 +272,16 @@ You can configure search debounce time and number of characters which needs to b Pre-requests allow you to perform an operation before making a request for the first page. This could be, for example, fetching available filters. -#### `run` +#### `PreRequest` -`run` is a client-specific method that performs the pre-request and returns the new state. It can be defined once and used repeatedly as a mixin. +`PreRequest` is a class that serves as an implementation of a pre-request. To utilize it, create an abstract base class that extends `PreRequest` and then create classes specific for each pre-request. An example base class: ```dart -mixin Run - on PreRequest { +/// Base class for http pre-request use cases. +abstract class HttpPreRequest + extends PreRequest { @override + /// This method performs the pre-request and returns the new state. Future> run( PaginatedState state) async { try { @@ -312,21 +310,17 @@ mixin Run } ``` -#### `PreRequest` - -`PreRequest` is a class that serves as an implementation of a pre-request. To utilize it, create a class that extends `PreRequest`. +Example implementation of `PreRequest` using defined `HttpPreRequest` looks like this: ```dart -class FiltersPreRequest extends PreRequest - with Run { +class FiltersPreRequest extends HttpPreRequest { FiltersPreRequest({required this.api}); final Api api; @override - Future request(PaginatedState state) { - return api.getFilters(); - } + Future request(PaginatedState state) => + api.getFilters(); @override Filters map( @@ -393,4 +387,4 @@ PaginatedResult, KratosIdentityDTO> { } ``` -[leancode_cubit_utils_cqrs]: https://pub.dev/packages/leancode_cubit_utils_cqrs \ No newline at end of file +[leancode_cubit_utils_cqrs]: https://pub.dev/packages/leancode_cubit_utils_cqrs