From e0f190f8851a49a99e6770f82b5690c8e5afc954 Mon Sep 17 00:00:00 2001 From: AbgarSim Date: Mon, 27 May 2024 18:16:42 +0300 Subject: [PATCH] Readme.md --- README.md | 214 +++++++++++++++++--- example/panda_sync_todo/README.md | 16 -- pubspec.lock | 18 +- pubspec.yaml | 2 +- test/unit/mocks/panda_sync.mocks.dart | 13 +- test/unit/mocks/panda_sync.mocks.mocks.dart | 59 +++++- 6 files changed, 274 insertions(+), 48 deletions(-) diff --git a/README.md b/README.md index 8b55e73..cd19b2e 100644 --- a/README.md +++ b/README.md @@ -1,39 +1,207 @@ - +

+ +

-For information about how to write a good package README, see the guide for -[writing package pages](https://dart.dev/guides/libraries/writing-package-pages). +

Flutter Data

-For general information about developing packages, see the Dart guide for -[creating packages](https://dart.dev/guides/libraries/create-library-packages) -and the Flutter guide for -[developing packages and plugins](https://flutter.dev/developing-packages). ---> +[![tests](https://img.shields.io/github/actions/workflow/status/flutterdata/flutter_data/test.yml?branch=master)](https://github.com/flutterdata/flutter_data/actions) [![codecov](https://codecov.io/gh/flutterdata/flutter_data/branch/master/graph/badge.svg)](https://codecov.io/gh/flutterdata/flutter_data) [![pub.dev](https://img.shields.io/pub/v/flutter_data?label=pub.dev&labelColor=333940&logo=dart)](https://pub.dev/packages/flutter_data) [![license](https://img.shields.io/github/license/flutterdata/flutter_data?color=%23007A88&labelColor=333940&logo=mit)](https://github.com/flutterdata/flutter_data/blob/master/LICENSE) -TODO: Put a short description of the package here that helps potential users -know whether this package might be useful for them. + +# panda_sync + +`panda_sync` is a Dart library designed to facilitate the development of offline-first applications +using Flutter. It provides seamless data synchronization between local storage and a remote server, +ensuring your app remains functional even without internet connectivity. The ## Features -TODO: List what your package can do. Maybe include images, gifs, or videos. +- **Offline-First Functionality**: Automatically handles data synchronization when the device is online. +- **Local Storage with Isar**: Utilizes Isar, a high-performance NoSQL database, for local data storage. +- **Network Request Management**: Uses Dio for making network requests and managing connectivity states. +- **Type Registration**: Enforces type registration for data serialization and deserialization. +- **Automatic Retry**: Automatically retries failed network requests when the device regains connectivity. +- **Customizable**: Allows customization of request handling and data processing. -## Getting started +## Installation -TODO: List prerequisites and provide or point to information on how to -start using the package. +Add the following dependency to your `pubspec.yaml` file: + +```yaml + +dependencies: + panda_sync: ^1.0.0 # Add the latest version +``` ## Usage +### Step 1: Initialize Local Storage + +Before using the library, initialize Isar core: + +```dart + +import 'package:panda_sync/panda_sync.dart'; + +void main() async { +await OfflineFirstLocalStorageInit.initialize(); +runApp(MyApp()); +} +``` + +## Step 2: Extend your data models with `Identifieble` and implement static `fromJson` and `toJson` methods. + + +```dart +import 'package:panda_sync/panda_sync.dart'; + +import 'package:json_annotation/json_annotation.dart'; + +part 'task_model.g.dart'; + +//This example uses json_serializable but this is not mandatory +@JsonSerializable() +class Task extends Identifiable{ + @override + int id; + ... + + factory Task.fromJson(Map json) => _$TaskFromJson(json); + static Map taskToJson(Task task) => _$TaskToJson(task); +} + +``` + +### Step 3: Register the types your app will use: + +```dart + +import 'package:panda_sync/panda_sync.dart'; +import 'model/task_model.dart'; // Import your model + +void main() async { + await OfflineFirstLocalStorageInit.initialize(); + + TypeRegistry.register('TaskBox', Task.taskToJson, Task.fromJson); + + runApp(MyApp()); +} + +``` -TODO: Include short and useful examples for package users. Add longer examples -to `/example` folder. +### Step 4: Create an Instance of `OfflineFirstClient` + +Create an instance of OfflineFirstClient: + +```dart + +final OfflineFirstClient offlineFirstClient = + OfflineFirstClient(); +``` + +### Step 5: Use the `OfflineFirstClient` as you would use any other Http client + +Here's how to use the library in a service class: ```dart -const like = 'sample'; +import 'package:dio/dio.dart'; +import 'package:panda_sync/panda_sync.dart'; +import 'model/task_model.dart'; + +class TodoService { + static final TodoService _instance = TodoService._internal(); + static final OfflineFirstClient offlineFirstClient = + OfflineFirstClient(); + + factory TodoService() { + return _instance; + } + + TodoService._internal(); + + Future> getAllTasks() async { + try { + Response> response = await offlineFirstClient.getList('http://10.0.2.2:8080/api/tasks'); + return response.data!; + } catch (e) { + throw Exception('Failed to load tasks: $e'); + } + } + + Future getTaskById(int id) async { + try { + Response response = await offlineFirstClient.get('http://10.0.2.2:8080/api/tasks/$id'); + return response.data!; + } catch (e) { + throw Exception('Failed to get task: $e'); + } + } + + Future createTask(Task task) async { + try { + var postResponse = await offlineFirstClient.post('http://10.0.2.2:8080/api/tasks', task); + return postResponse.data!; + } catch (e) { + throw Exception('Failed to create task: $e'); + } + } + + Future updateTask(Task task) async { + try { + var putResponse = await offlineFirstClient.put('http://10.0.2.2:8080/api/tasks/${task.id}', task); + return putResponse.data!; + } catch (e) { + throw Exception('Failed to update task: $e'); + } + } + + Future deleteTask(int id) async { + try { + Task taskToDelete = await getTaskById(id); + + await offlineFirstClient.delete('http://10.0.2.2:8080/api/tasks/$id',taskToDelete); + } catch (e) { + throw Exception('Failed to delete task: $e'); + } + } +} ``` -## Additional information +# API Documentation + +- **OfflineFirstClient** + + - `OfflineFirstClient()`: Creates an instance of **OfflineFirstClient**. + - `Future> get(String url, {Map? queryParameters}):` Makes a GET request. + - `Future> post(String url, T data, {Map? queryParameters}):` Makes a POST request. + - `Future> put(String url, T data, {Map? queryParameters}):` Makes a PUT request. + - `Future> delete(String url, T data, {Map? queryParameters}):` Makes a DELETE request. + - `Future>> getList(String url, {Map? queryParameters}):` Makes a GET request for a list of items. + - `Future>> postList(String url, List dataList, {Map? queryParameters}):` Makes a POST request for a list of items. + - `Future>> putList(String url, List dataList, {Map? queryParameters}):` Makes a PUT request for a list of items. + - `Future>> deleteList(String url, List dataList, {Map? queryParameters}):` Makes a DELETE request for a list of items. + + +# Contributing + +We welcome contributions! Please follow these steps to contribute: + + 1. Fork the repository. + 2. Create a new branch (`git checkout -b my-feature-branch`). + 3. Make your changes. + 4. Commit your changes (`git commit -am 'Add new feature'`). + 5. Push to the branch (git push origin my-feature-branch). + 6. Create a Pull Request. + +# License + +This project is licensed under the MIT License - see the LICENSE file for details. + +# Acknowledgements + +- [Isar Database](https://github.com/isar/isar) +- [Dio HTTP Client](https://github.com/cfug/dio) +- [Connectivity Plus](https://github.com/fluttercommunity/plus_plugins/tree/main/packages/connectivity_plus/connectivity_plus) + +# Contact -TODO: Tell users more about the package: where to find more information, how to -contribute to the package, how to file issues, what response they can expect -from the package authors, and more. +For any questions or suggestions, feel free to open an issue or contact any maintainer. \ No newline at end of file diff --git a/example/panda_sync_todo/README.md b/example/panda_sync_todo/README.md index 5fb8462..e69de29 100644 --- a/example/panda_sync_todo/README.md +++ b/example/panda_sync_todo/README.md @@ -1,16 +0,0 @@ -# panda_sync_todo - -A new Flutter project. - -## Getting Started - -This project is a starting point for a Flutter application. - -A few resources to get you started if this is your first Flutter project: - -- [Lab: Write your first Flutter app](https://docs.flutter.dev/get-started/codelab) -- [Cookbook: Useful Flutter samples](https://docs.flutter.dev/cookbook) - -For help getting started with Flutter development, view the -[online documentation](https://docs.flutter.dev/), which offers tutorials, -samples, guidance on mobile development, and a full API reference. diff --git a/pubspec.lock b/pubspec.lock index 0082477..c547a68 100644 --- a/pubspec.lock +++ b/pubspec.lock @@ -464,14 +464,22 @@ packages: url: "https://pub.dev" source: hosted version: "2.2.1" + path_provider_macos: + dependency: "direct dev" + description: + name: path_provider_macos + sha256: cd57cb98a30ce9d12fdd1896d9d3b0517ce689f942de6ccd2708cd39b3d18a7c + url: "https://pub.dev" + source: hosted + version: "2.0.7" path_provider_platform_interface: - dependency: transitive + dependency: "direct dev" description: name: path_provider_platform_interface - sha256: "94b1e0dd80970c1ce43d5d4e050a9918fce4f4a775e6142424c30a29a363265c" + sha256: "88f5779f72ba699763fa3a3b06aa4bf6de76c8e5de842cf6f29e2e06476c2334" url: "https://pub.dev" source: hosted - version: "2.1.1" + version: "2.1.2" path_provider_windows: dependency: transitive description: @@ -500,10 +508,10 @@ packages: dependency: transitive description: name: plugin_platform_interface - sha256: da3fdfeccc4d4ff2da8f8c556704c08f912542c5fb3cf2233ed75372384a034d + sha256: "4820fbfdb9478b1ebae27888254d445073732dae3d6ea81f0b7e06d5dedc3f02" url: "https://pub.dev" source: hosted - version: "2.1.6" + version: "2.1.8" pool: dependency: transitive description: diff --git a/pubspec.yaml b/pubspec.yaml index 5077736..cf31433 100644 --- a/pubspec.yaml +++ b/pubspec.yaml @@ -21,4 +21,4 @@ dev_dependencies: sdk: flutter isar_generator: ^3.1.0+1 mockito: ^5.4.4 - test: any + test: any \ No newline at end of file diff --git a/test/unit/mocks/panda_sync.mocks.dart b/test/unit/mocks/panda_sync.mocks.dart index a5538cf..0fafa53 100644 --- a/test/unit/mocks/panda_sync.mocks.dart +++ b/test/unit/mocks/panda_sync.mocks.dart @@ -6,7 +6,16 @@ import 'package:panda_sync/src/services/connectivity_service.dart'; import 'package:panda_sync/src/services/local_storage_service.dart'; import 'package:panda_sync/src/services/synchronization_service.dart'; -@GenerateMocks([Connectivity, Isar, IsarCollection, QueryBuilder, Query, - LocalStorageService, Dio, SynchronizationService, ConnectivityService +@GenerateMocks([ + Connectivity, + Isar, + IsarCollection, + QueryBuilder, + Query, + LocalStorageService, + Dio, + SynchronizationService, + ConnectivityService, + HttpClientAdapter ]) void main() {} diff --git a/test/unit/mocks/panda_sync.mocks.mocks.dart b/test/unit/mocks/panda_sync.mocks.mocks.dart index 51d8548..6dcc526 100644 --- a/test/unit/mocks/panda_sync.mocks.mocks.dart +++ b/test/unit/mocks/panda_sync.mocks.mocks.dart @@ -1,5 +1,5 @@ // Mocks generated by Mockito 5.4.4 from annotations -// in panda_sync/test/mocks/panda_sync.mocks.dart. +// in panda_sync/test/unit/mocks/panda_sync.mocks.dart. // Do not manually edit this file. // ignore_for_file: no_leading_underscores_for_library_prefixes @@ -166,6 +166,16 @@ class _FakeDio_12 extends _i1.SmartFake implements _i4.Dio { ); } +class _FakeResponseBody_13 extends _i1.SmartFake implements _i4.ResponseBody { + _FakeResponseBody_13( + Object parent, + Invocation parentInvocation, + ) : super( + parent, + parentInvocation, + ); +} + /// A class which mocks [Connectivity]. /// /// See the documentation for Mockito's code generation for more information. @@ -2215,3 +2225,50 @@ class MockConnectivityService extends _i1.Mock returnValue: _i2.Future.value(false), ) as _i2.Future); } + +/// A class which mocks [HttpClientAdapter]. +/// +/// See the documentation for Mockito's code generation for more information. +class MockHttpClientAdapter extends _i1.Mock implements _i4.HttpClientAdapter { + MockHttpClientAdapter() { + _i1.throwOnMissingStub(this); + } + + @override + _i2.Future<_i4.ResponseBody> fetch( + _i4.RequestOptions? options, + _i2.Stream<_i9.Uint8List>? requestStream, + _i2.Future? cancelFuture, + ) => + (super.noSuchMethod( + Invocation.method( + #fetch, + [ + options, + requestStream, + cancelFuture, + ], + ), + returnValue: _i2.Future<_i4.ResponseBody>.value(_FakeResponseBody_13( + this, + Invocation.method( + #fetch, + [ + options, + requestStream, + cancelFuture, + ], + ), + )), + ) as _i2.Future<_i4.ResponseBody>); + + @override + void close({bool? force = false}) => super.noSuchMethod( + Invocation.method( + #close, + [], + {#force: force}, + ), + returnValueForMissingStub: null, + ); +}