Dart-language code encapsulating Immaculater's mergeprotobufs API for reading and writing personal to-do lists with actions, contexts, projects, folders, and notes.
One future direction is to use this library in a new Immaculater Flutter app. Instead of dealing with little bits of data, you'll be sending back and forth the entire to-do list since they're typically small enough for that to be performant in the asynchronous world of Flutter (it is just for one person, after all).
Users can then have their choice of the Immaculater classic web application or a Flutter mobile/desktop/web app. They will be able to simultaneously use a Flutter iOS app and a Flutter desktop app thanks to mergeprotobufs' ability to synchronize various clients.
To understand this library you must understand the mergeprotobufs API which is
documented in the
In short, though, mergeprotobufs is the way to read and to write. A write is also a read, sometimes, if another device has changed the to-do list in the interim.
Is it any good? #
Not yet. The backend has no ability to merge just yet, for one thing, but much more testing is necessary before data loss is unlikely.
Authentication will change away from username plus password to JSON Web Tokens (JWTs) or something similar before 1.0.0.
Staying up to date with Immaculater's protocol #
Immaculater generates Dart
protocol buffers as a matter of course. Just copy them here with
What to type #
If you're using this library, watch this space for instructions. TODO(chandler37): Give instructions beyond "Call merge()".
If you're developing this library, type this:
make lint fmt test
Which will only work if you have the Dart SDK installed. (I used the Dart SDK via Homebrew, not the Dart inside of Flutter's SDK.)
How does it work under the hood? #
We use a mix of JSON (for errors returned), HTTP 204 NO CONTENT, and protocol buffers for the input and output of mergeprotobufs. It is not gRPC.
To make progress, learn how
immaculater_dart_test.dart works. There is a
skipped test that can be used to make the test suite hit a live backend. Record
that interaction in a "cassette". The tests should not require network access.
Credit where credit is due #
Created from templates made available by Stagehand under a BSD-style license.
- UnauthenticatedException is also used for creating JWTs.
- UnauthenticatedException is a new subclass of ApiException for HTTP 403 responses (which confuse authorization with authentication (see HTTP 401) but really are about authentication).
- Protobufs now feature a message UserInfoAndToDoList.
- JSON Web Token (JWT) authentication is supported.
- Merely updates the protocol with two new booleans for MergeToDoListRequest.
- Downgrades meta dependency to play nice with Flutter. Many incremental improvements and new APIs. Many new tests.
- Initial version (thank you to the Stagehand code generator), shaped with care to perhaps work for a 'we never need to merge' use case. Perhaps even when a merge is required.
Use this package as a library
1. Depend on it
Add this to your package's pubspec.yaml file:
dependencies: immaculater_dart: ^0.7.0
2. Install it
You can install packages from the command line:
$ pub get
$ flutter pub get
Alternatively, your editor might support
pub get or
flutter pub get.
Check the docs for your editor to learn more.
3. Import it
Now in your Dart code, you can use:
Describes how popular the package is relative to other packages. [more]
Code health derived from static analysis. [more]
Reflects how tidy and up-to-date the package is. [more]
Weighted score of the above. [more]
We analyzed this package on Jan 19, 2020, and provided a score, details, and suggestions below. Analysis was completed with status completed using:
- Dart: 2.7.0
- pana: 0.13.4
lib/src/generated/core/pyatdl.pbjson.dart. (-25 points)
lib/src/generated/core/pyatdl.pbjson.dart reported 126 hints, including:
line 8 col 27: Avoid const keyword.
line 10 col 8: Avoid const keyword.
line 11 col 5: Avoid const keyword.
line 12 col 5: Avoid const keyword.
line 17 col 12: Avoid const keyword.
dartfmt to format
dartfmt to format
Fix additional 5 files with analysis or formatting issues.
Additional issues in the following files:
Maintain an example. (-10 points)
Create a short demo in the
example/ directory to show how to use this package.
Common filename patterns include
immaculater_dart.dart. Packages with multiple examples should provide
For more information see the pub package layout conventions.
|Dart SDK||>=2.5.0 <3.0.0|