Additional query methods (#611)

* add first and find to the QueryBuilder

* add documentation for first() and find()

Author: fischerscode

packages/dart/README.md

@@ -248,6 +248,15 @@ if (dietPlan.success) {
 }
 ```
 
+### Alternative query methods
+
+The standard query method `query()` returns a `ParseResponse` that contains the result or the error. As an alternative, you can also use `Future<List<T>> find()` for receiving options.
+This method returns an `Future` that either resolves in an error (equivalent of the error in the `ParseResponse`) or an `List` containing the queried objects. One difference, you should be aware of, is the fact, that `Future<List<T>> find()` will return an empty list instead of the 'No results' error you receive in case no object matches you query.
+
+Choosing between `query()` and `find()` comes down to personal preference. Both methods can be used for querying a `ParseQuery`, just the output method differs.
+
+Similar to `find()` the `QueryBuilder` also has a function called `Future<T>? first()`. Just like `find()` `first()` is just a convenience method that makes querying the first object satisfying the query simpler. `first()` returns an `Future`, that resoles in an error or the first object matching the query. In case no object satisfies the query, the result will be `null`.
+
 ## Complex queries
 You can create complex queries to really put your database to the test:
 

packages/dart/lib/src/network/parse_query.dart

@@ -513,4 +513,25 @@ class QueryBuilder<T extends ParseObject> {
     });
     return result;
   }
+
+  /// Find the first object that satisfies the query.
+  /// Returns null, if no object is found.
+  Future<T>? first() async {
+    ParseResponse parseResponse =
+        await (QueryBuilder.copy(this)..setLimit(1)).query();
+    if (parseResponse.success) {
+      return parseResponse.results?.first;
+    }
+    throw parseResponse.error ?? ParseError();
+  }
+
+  /// Find the objects that satisfy the query.
+  /// Returns an empty list if no objects are found.
+  Future<List<T>> find() async {
+    ParseResponse parseResponse = await query();
+    if (parseResponse.success) {
+      return parseResponse.results?.map((e) => e as T).toList() ?? <T>[];
+    }
+    throw parseResponse.error ?? ParseError();
+  }
 }

packages/flutter/README.md

@@ -265,6 +265,15 @@ if (response.success) {
 }
 ```
 
+### Alternative query methods
+
+The standard query method `query()` returns a `ParseResponse` that contains the result or the error. As an alternative, you can also use `Future<List<T>> find()` for receiving options.
+This method returns an `Future` that either resolves in an error (equivalent of the error in the `ParseResponse`) or an `List` containing the queried objects. One difference, you should be aware of, is the fact, that `Future<List<T>> find()` will return an empty list instead of the 'No results' error you receive in case no object matches you query.
+
+Choosing between `query()` and `find()` comes down to personal preference. Both methods can be used for querying a `ParseQuery`, just the output method differs.
+
+Similar to `find()` the `QueryBuilder` also has a function called `Future<T>? first()`. Just like `find()` `first()` is just a convenience method that makes querying the first object satisfying the query simpler. `first()` returns an `Future`, that resoles in an error or the first object matching the query. In case no object satisfies the query, the result will be `null`.
+
 ## Complex queries
 You can create complex queries to really put your database to the test: