add query.findUnique()

Author: vaind

objectbox/CHANGELOG.md

@@ -1,3 +1,7 @@
+## latest
+
+* Add `Query.findUnique()` to find a single object matching the query.
+
 ## 1.1.1 (2021-07-09)
 
 * Add support for `Query.param()` on linked entities.

objectbox/lib/src/native/query/query.dart

@@ -748,6 +748,32 @@ class Query<T> {
     return result;
   }
 
+  /// Finds the only object matching the query. Returns null if there are no
+  /// results or throws if there are multiple objects matching.
+  ///
+  /// Note: [offset] and [limit] are respected, if set. Because [limit] affects
+  /// the number of matched objects, make sure you leave it at zero or set it
+  /// higher than one, otherwise the check for non-unique result won't work.
+  T? findUnique() {
+    T? result;
+    Exception? error;
+    final visitor = dataVisitor((Pointer<Uint8> data, int size) {
+      if (result == null) {
+        result = _entity.objectFromFB(
+            _store, InternalStoreAccess.reader(_store).access(data, size));
+      } else {
+        error = UniqueViolationException(
+            'Query findUnique() matched more than one object');
+        return false;
+      }
+      return true;
+    });
+    checkObx(C.query_visit(_ptr, visitor, nullptr));
+    reachabilityFence(this);
+    if (error != null) throw error!;
+    return result;
+  }
+
   /// Finds Objects matching the query and returns their IDs.
   List<int> findIds() {
     final idArrayPtr = checkObxPtr(C.query_find_ids(_ptr), 'find ids');

objectbox/test/query_test.dart

@@ -352,6 +352,25 @@ void main() {
     q.close();
   });
 
+  test('.findUnique', () {
+    box.put(TestEntity(tLong: 0));
+    box.put(TestEntity(tString: 't1'));
+    box.put(TestEntity(tString: 't2'));
+
+    var query = box.query(TestEntity_.tString.startsWith('t')).build();
+
+    expect(
+        () => query.findUnique(),
+        throwsA(predicate((UniqueViolationException e) =>
+            e.toString().contains('more than one'))));
+
+    query.param(TestEntity_.tString).value = 't2';
+    expect(query.findUnique()!.tString, 't2');
+
+    query.param(TestEntity_.tString).value = 'xyz';
+    expect(query.findUnique(), isNull);
+  });
+
   test('.find works on large arrays', () {
     // This would fail on 32-bit system if objectbox-c obx_supports_bytes_array() wasn't respected
     final length = 10 * 1000;