Merge pull request #60 from objectbox/dev

v0.4.0 release

Author: vaind

.github/workflows/dart.yml

@@ -10,10 +10,10 @@ jobs:
     steps:
       - uses: actions/checkout@v1
       - name: Install dependencies
-        working-directory: bin/objectbox_model_generator
+        working-directory: generator
         run: pub get
       - name: Run tests
-        working-directory: bin/objectbox_model_generator
+        working-directory: generator
         run: pub run test
 
   lib:

CHANGELOG.md

@@ -1,14 +1,28 @@
+0.4.0 (2019-10-31)
+------------------
+* Flutter Android support
+* Queries for all currently supported types  
+    (thanks [Jasm Sison](https://github.com/Buggaboo) for [#27](https://github.com/objectbox/objectbox-dart/pull/27) and [#46](https://github.com/objectbox/objectbox-dart/pull/46)]
+* More Box functions (count, isEmpty, contains, remove and their bulk variants)
+    (thanks [liquidiert](https://github.com/liquidiert) for [#42](https://github.com/objectbox/objectbox-dart/pull/42) and [#45](https://github.com/objectbox/objectbox-dart/pull/45)]
+* Explicit write transactions
+    (thanks [liquidiert](https://github.com/liquidiert) for [#50](https://github.com/objectbox/objectbox-dart/pull/50)]    
+* Resolved linter issues
+    (thanks [Gregory Sech](https://github.com/GregorySech) for [#31](https://github.com/objectbox/objectbox-dart/pull/31)]
+* Updated to objectbox-c 0.7.2
+* First release on pub.dev
+
 0.3.0 (2019-10-15)
 ------------------
 * ID/UID generation and model persistence (objectbox-model.json)
 * CI tests using GitHub Actions
 * Code cleanup, refactoring and formatting 
-    (thanks [Buggaboo](https://github.com/Buggaboo) for [#20](https://github.com/objectbox/objectbox-dart/pull/20) & [#21](https://github.com/objectbox/objectbox-dart/pull/21)]
+    (thanks [Jasm Sison](https://github.com/Buggaboo) for [#20](https://github.com/objectbox/objectbox-dart/pull/20) & [#21](https://github.com/objectbox/objectbox-dart/pull/21)]
 
 0.2.0 (2019-09-11)
-------------------
+------------------Buggaboo
 * UTF-8 support for Store and Box 
-    (thanks to [Buggaboo](https://github.com/Buggaboo) for [#14](https://github.com/objectbox/objectbox-dart/pull/14)!)
+    (thanks to [Jasm Sison](https://github.com/Buggaboo) for [#14](https://github.com/objectbox/objectbox-dart/pull/14)!)
 * Bulk put and get functions (getMany, getAll, putMany)
 * Updated to objectbox-c 0.7
 * Basic Store options

CONTRIBUTING.md

@@ -0,0 +1,30 @@
+Contributing
+------------------
+This project is completely managed on GitHub using its [issue tracker](https://github.com/objectbox/objectbox-dart/issues) and [project boards](https://github.com/objectbox/objectbox-dart/projects).
+
+Anyone can contribute, be it by coding, improving docs or just proposing a new feature. 
+Look for tasks having a [**"help wanted"**](https://github.com/objectbox/objectbox-dart/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22) tag. 
+When picking up an existing issue, please let us know in the issue comment. 
+Don't hesitate to reach out for guidance or to discuss a solution proposal!
+
+### Code contributions
+When creating a Pull Request for code changes, please check that you cover the following:
+* Include tests for the changes you introduce. See the [test folder](test) for examples.
+* Formatted the code using `dartfmt -l 120`. You can configure your IDE to do this automatically, 
+  e.g. VS Code needs the project-specific settings `"editor.defaultFormatter": "Dart-Code.dart-code"` and `"dart.lineLength": 120`.
+
+### Project workflow
+Issues on the [project board](https://github.com/objectbox/objectbox-dart/projects/3) are referred to as "cards" which move from left to right:
+
+* New cards start in the "To Do" column.
+  Within the column, cards are ordered: more important tasks should be above less important ones.  
+* Once somebody starts on a task, the according card is moved to "In progress".
+  Also, please assign yourself to the issue.
+* Once a task is considered complete (e.g. PR is made), put it in the "Review" column.
+* Once another person had a look and is happy, the task is finally moved to "Done" and its closed.
+
+### Basic technical approach
+ObjectBox offers a [C API](https://github.com/objectbox/objectbox-c) which can be called by [Dart FFI](https://dart.dev/server/c-interop).
+The C API is is also used by the ObjectBox language bindings for [Go](https://github.com/objectbox/objectbox-go), [Swift](https://github.com/objectbox/objectbox-swift), and [Python](https://github.com/objectbox/objectbox-python).
+These language bindings currently serve as an example for this Dart implementation.
+Internally, ObjectBox uses [FlatBuffers](https://google.github.io/flatbuffers/) to store objects.

README.md

@@ -2,56 +2,50 @@ ObjectBox for Dart/Flutter
 ==========================
 ObjectBox for Dart is a standalone database storing Dart objects locally, with strong ACID semantics.
 
-Help wanted
------------
-ObjectBox for Dart is still in a prototype stage supporting only the most basic database tasks, like putting and getting objects.
-However, the ObjectBox core supports many more features, e.g. queries, indexing, async operations, transaction control.
-To bring all these features to Dart, we're asking the community to help out. PRs are more than welcome!
-The ObjectBox team will try its best to guide you and answer questions. 
-
-Contributing
-------------------
-This project is completely managed here on GitHub using its [issue tracker](https://github.com/objectbox/objectbox-dart/issues) and [project boards](https://github.com/objectbox/objectbox-dart/projects).
-
-To prepare an upcoming version, we create a (Kanban like) board for it.
-Once it is decided which features and fixes go into the version, the according issues are added to the board.
-Issues on the board are referred to as "cards" which move from left to right:
-
-* New cards start in the "To Do" column.
-  Within the column, cards are ordered: more important tasks should be above less important ones.  
-* Once somebody starts on a task, the according card is moved to "In progress".
-  Also, please assign yourself to the issue.
-* Once a task is considered complete (e.g. PR is made), put it in the "Review" column.
-* Once another person had a look and is happy, the task is finally moved to "Done"
- 
-Anyone can contribute, be it by coding, improving docs or just proposing a new feature. 
-Look for tasks having a **"help wanted"** tag.
-
-#### Feedback
-Also, please let us know your feedback by opening an issue:
-for example, if you experience errors or if you have ideas for how to improve the API.
-Thanks!
+Installation
+------------
+Add the following dependencies to your `pubspec.yaml`:
+```yaml
+dependencies:
+  objectbox: ^0.4.0
+
+dev_dependencies:
+  build_runner: ^1.0.0
+  objectbox_generator: ^0.4.0
+```
 
-#### Code style
-Please make sure that all code submitted via Pull Request is formatted using `dartfmt -l 120`. 
-You can configure your IDE to do this automatically, e.g. VS Code needs the project-specific settings 
-`"editor.defaultFormatter": "Dart-Code.dart-code"` and `"dart.lineLength": 120`.
+Proceed based on whether you're developing a Flutter app or a standalone dart program:
+1. **Flutter** only steps:
+    * Install the packages `flutter pub get`
+    * Add `objectbox-android` dependency to your `android/app/build.gradle` 
+        ```
+        dependencies {
+            implementation "io.objectbox:objectbox-android:2.4.1"
+            ...
+       ```
+    * iOS coming soon
+1. **Dart standalone programs**:
+    * Install the packages `pub get`
+    * Install [objectbox-c](https://github.com/objectbox/objectbox-c) system-wide:
+       * macOS/Linux: execute the following command (answer Y when it asks about installing to /usr/lib) 
+            ```shell script
+            bash <(curl -s https://raw.githubusercontent.com/objectbox/objectbox-c/master/download.sh) 0.7.2
+            ```
+       * macOS: if dart later complains that it cannot find the `libobjectbox.dylib` you probably have to unsign the 
+         `dart` binary (source: [dart issue](https://github.com/dart-lang/sdk/issues/38314#issuecomment-534102841)):
+            ```shell script
+            sudo xcode --remove-signature $(which dart)
+            ```
+       * Windows: use "Git Bash" or similar to execute the following command 
+            ```shell script
+            bash <(curl -s https://raw.githubusercontent.com/objectbox/objectbox-c/master/download.sh) 0.7.2
+            ```
+            Then copy the downloaded `lib/objectbox.dll` to `C:\Windows\System32\` (requires admin privileges).
+
+ObjectBox generates code binding code for classes you want stored based using build_runner.
+After you've defined your persisted entities (see below), run `pub run build_runner build` or `flutter pub run build_runner build`.
 
 Getting started
----------------
-To try out the demo code in this repository, follow these steps:
-
-1. Install [objectbox-c](https://github.com/objectbox/objectbox-c) system-wide:
-   * macOS/Linux: `bash <(curl -s https://raw.githubusercontent.com/objectbox/objectbox-c/master/download.sh) 0.7` (answer Y when it asks about installing to /usr/lib).
-   * Windows: 
-        * use "Git Bash" or similar to execute `bash <(curl -s https://raw.githubusercontent.com/objectbox/objectbox-c/master/download.sh) 0.7`
-        * copy the downloaded `lib/objectbox.dll` to `C:\Windows\System32\` (requires admin privileges)
-2. Back in this repository, run `pub get`.
-3. Execute `pub run build_runner build`. This regenerates the ObjectBox model to make it usable in Dart 
-   (i.e. the file `test/test.g.dart`) and is necessary each time you add or change a class annotated with `@Entity(...)`.
-4. Finally run `pub run test` to run the unit tests.
-
-Dart integration
 ----------------
 In general, Dart class annotations are used to mark classes as ObjectBox entities and provide meta information.
 Note that right now, only a limited set of types is supported; this will be expanded upon in the near future.
@@ -98,20 +92,70 @@ print("refetched note: ${box.get(note.id)}");
 store.close();
 ```
 
-Basic technical approach
-------------------------
-ObjectBox offers a [C API](https://github.com/objectbox/objectbox-c) which can be called by [Dart FFI](https://dart.dev/server/c-interop).
-The C API is is also used by the ObjectBox language bindings for [Go](https://github.com/objectbox/objectbox-go), [Swift](https://github.com/objectbox/objectbox-swift), and [Python](https://github.com/objectbox/objectbox-python).
-These language bindings currently serve as an example for this Dart implementation.
+### Query and QueryBuilder
+
+Basic querying can be done with e.g.:
+
+```dart
+// var store ...
+// var box ...
+
+box.putMany([Note(), Note(), Note()]);
+box.put(Note.construct("Hello world!"));
+
+final queryNullText = box.query(Note_.text.isNull()).build();
+
+assert(queryNullText.count() == 3);
+
+queryNullText.close(); // We have to manually close queries and query builders.
+```
+
+More complex queries can be constructed using `and/or` operators.
+Also there is basic operator overloading support for `equal`, `greater`, `less`, `and` and `or`,
+respectively `==`, `>`, `<`, `&`, `|`.
+
+```dart
+// final box ...
 
-Internally, ObjectBox uses [FlatBuffers](https://google.github.io/flatbuffers/) to store objects.
-There are two basic ways to make the conversion: generated binding code, or implicit FlatBuffers conversion.
-The latter is used at the moment (helped us to get started quickly).
-A future version will exchange that with code generation.  
+box.query(value.greaterThan(10).or(date.IsNull())).build();
+
+// equivalent to
+
+final overloaded = (value > 10) | date.IsNull();
+box.query(overloaded as Condition).build(); // the cast is necessary due to the type analyzer
+```
+
+### Ordering
+
+The results from a query can be ordered using the `order` method, e.g.
+
+```dart
+final q = box.query(Entity_.number > 0)
+  .order(Type_.number)
+  .build();
+
+// ...
+
+final qt = box.query(Entity_.text.notNull())
+  .order(Entity_.text, flags: OBXOrderFlag.DESCENDING | OBXOrderFlag.CASE_SENSITIVE)
+  .build();
+```
+
+Help wanted
+-----------
+ObjectBox for Dart is still in an early stage with limited feature set (compared to other languages).
+To bring all these features to Dart, we're asking the community to help out. PRs are more than welcome!
+The ObjectBox team will try its best to guide you and answer questions. 
+
+### Feedback
+Also, please let us know your feedback by opening an issue:
+for example, if you experience errors or if you have ideas for how to improve the API.
+Thanks!
 
-Changelog
+See also
 ---------
-[CHANGELOG.md](CHANGELOG.md)
+* [Changelog](CHANGELOG.md)
+* [Contribution guidelines](CONTRIBUTING.md)
 
 License
 -------

analysis_options.yaml

@@ -0,0 +1,11 @@
+include: package:pedantic/analysis_options.yaml
+
+linter:
+  rules:
+    # additional rules used by pub.dev
+    - non_constant_identifier_names
+
+analyzer:
+  exclude:
+    - example/**
+    - generator/**   # needs to be checked separately because its a separate package