immaculater_dart 0.7.0

  • Readme
  • Changelog
  • Installing
  • 47

immaculater_dart #

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 source (search for def mergeprotobufs(request):).

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 pyatdl.proto.

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.

0.7.0 #

    - UnauthenticatedException is also used for creating JWTs.

0.6.0 #

    - UnauthenticatedException is a new subclass of ApiException for
    HTTP 403 responses (which confuse authorization with
    authentication (see HTTP 401) but really are about

0.5.0 #

    - Protobufs now feature a message UserInfoAndToDoList.

0.4.0 #

    - JSON Web Token (JWT) authentication is supported.

0.3.0 #

    - Merely updates the protocol with two new booleans for

0.2.0 #

    - Downgrades meta dependency to play nice with Flutter. Many
    incremental improvements and new APIs. Many new tests.

0.1.0 #

    - 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:

  immaculater_dart: ^0.7.0

2. Install it

You can install packages from the command line:

with pub:

$ pub get

with Flutter:

$ 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:

import 'package:immaculater_dart/immaculater_dart.dart';
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]
Learn more about scoring.

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

Health suggestions

Fix lib/src/generated/core/pyatdl.pbjson.dart. (-25 points)

Analysis of 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.

Format bin/main.dart.

Run dartfmt to format bin/main.dart.

Format lib/immaculater_dart.dart.

Run dartfmt to format lib/immaculater_dart.dart.

Fix additional 5 files with analysis or formatting issues.

Additional issues in the following files:

  • lib/src/auth.dart (Run dartfmt to format lib/src/auth.dart.)
  • lib/src/errors.dart (Run dartfmt to format lib/src/errors.dart.)
  • lib/src/generated/core/pyatdl.pb.dart (Run dartfmt to format lib/src/generated/core/pyatdl.pb.dart.)
  • lib/src/generated/core/pyatdl.pbenum.dart (Run dartfmt to format lib/src/generated/core/pyatdl.pbenum.dart.)
  • lib/src/generated/core/pyatdl.pbserver.dart (Run dartfmt to format lib/src/generated/core/pyatdl.pbserver.dart.)

Maintenance suggestions

Maintain an example. (-10 points)

Create a short demo in the example/ directory to show how to use this package.

Common filename patterns include main.dart, example.dart, and immaculater_dart.dart. Packages with multiple examples should provide example/

For more information see the pub package layout conventions.


Package Constraint Resolved Available
Direct dependencies
Dart SDK >=2.5.0 <3.0.0
crypto ^2.1.3 2.1.4
fixnum ^0.10.9 0.10.11
http ^0.12.0+2 0.12.0+4
meta ^1.1.7 1.1.8
protobuf ^1.0.0 1.0.1
Transitive dependencies
async 2.4.0
charcode 1.1.2
collection 1.14.12
convert 2.1.1
http_parser 3.1.3
path 1.6.4
source_span 1.6.0
string_scanner 1.0.5
term_glyph 1.1.0
typed_data 1.1.6
Dev dependencies
mockito ^4.1.1
pedantic ^1.8.0 1.9.0
test ^1.6.0