v0.4.0

See changelog

CHANGELOG.md

@@ -1,3 +1,19 @@
+## 0.4.0
+* **(!!)** Queries now return a ResultSet object instead of a Dart list. Use `ResultSet.allResults` to get the previous behaviour.
+* **(!!)** Renamed Document `jsonProperties` setter/getter to `json`
+* **(+)** Document constructor's `data` accepts `FLValue`, a json string or json-encodable object as input
+* **(+)** Documents now can hold a reference to the database and have `save`, `delete`, `expiration` methods
+* **(+)** `FLArray` has two new constructors `fromList` and `fromJson`
+* **(+)** `FLDict` has two new constructors `fromMap` and `fromJson`
+* **(+)** `FLArray` and `FLDict` support keypath accessor similar to `FLValue` as `FLArray()` and `FLDict()`. Normal key access using `[]` is unchanged.
+* **(+)** Implemented `CBLLog` class to manage messages that Couchbase Lite logs at runtime. Ability to control the `domain` and `level` of messages logged to either the `console`, `file` or a `callback` registered by the application.
+* Fix mutable document's nested properties not being mutable
+* Clean up listeners and other C callbacks implementation
+* Fix database and document listeners on Android
+* Fix blob `getContent` not returning the correct value
+* Added tests for `Document`, `Blob` and the `Fleece` classes
+* Lots of fixes and improvements in code structure and documentation
+
 ## 0.3.1
 * Fix query parameter setter
 

README.md

@@ -13,7 +13,7 @@ that runs locally on mobile devices
 
 This is a Dart port of the Couchbase Lite database, built on top of the Couchbase Lite C library ([CBL_C]) using dart.ffi.
 
-**Warning: This project is still in early development stage and breaking API changes might still happen!**
+**Warning: This project is still in early development stage, the API is still fluid and breaking changes might still happen!**
 Help with testing, documentation and development is welcome. Here's how you can [contribute](#contributing)
 
 # Feature checklist
@@ -44,7 +44,7 @@ Help with testing, documentation and development is welcome. Here's how you can
     * [x] Pull/push filters
     * [x] Status listeners
     * [ ] Replicated document listeners
-    * [x] Conflict-resolution callbacks
+    * [x] Conflict-resolution callbacks ([See issue #86](https://github.com/couchbaselabs/couchbase-lite-C/issues/86))
 * **Blobs**
     * [x] Create, read through content based API
     * [x] Stream based API
@@ -104,9 +104,12 @@ final q = Query(db, 'SELECT * WHERE foo=\$VALUE');
 q.setParameters = {'VALUE': 'bar'};
 
 // Optionally Turn it into a "live query"
-q.addChangeListener((List results) {
+q.addChangeListener((ResultSet results) {
     print('New query results: ');
-    print(results);
+    while(results.next()){
+        final row = results.rowDict;
+        print(row.json);
+    }
 });
 
 // Execute the query
@@ -135,10 +138,20 @@ replicator.start();
 See the example folder for a more complete example, including the Fleece API.
 
 # Contributing
+Current milestones for versioning are:
+* 0.5.0 - consolidate and document the core API for idiomatic Dart.  Breaking changes after that should be deprecated first, if possible.
+* 1.0.0 
+    - Align the API to the official SDK's as much as possible and where it makes sense.
+    - Implement solid memory management to eliminate memory leaks - a mix of automatic and manual disposal of objects
+    - make the library "production ready"
+    - Documentation beyond what dart docs has: best practices, tips, caveats, N1SQL features, extensive examples
+* post 1.0.0
+    - JSONQuery language support for queries, with a QueryBuilder API like the official SDK has
+
 There are couple of ways in which you can contribute:
 
-* Testing - current status is: it runs on my computer
-* Help with building the dynamic libraries for Android/iOS. I have the C library source code and some custom wrapper code to make it work with Dart's ffi. Currently I have only managed to build it for Windows. In particular iOS/macOS is welcome.
+* Testing
+* Adding/testing iOS/macOs. I have the C library source code and some custom wrapper code to make it work with Dart's ffi.
 * Fixing bugs
 * Improve documentation
 * Write examples

lib/bindings/database.dart

@@ -218,14 +218,14 @@ final CBLDatabase_SetDocumentExpiration = _dylib.lookupFunction<
 /// documents are changed on disk.
 final CBLDatabase_AddChangeListener = _dylib.lookupFunction<
     _c_CBLDatabase_AddChangeListener,
-    _dart_CBLDatabase_AddChangeListener>('CBLDatabase_AddChangeListener');
+    _dart_CBLDatabase_AddChangeListener>('CBLDatabase_AddChangeListener_d');
 
 /// Registers a document change listener callback. It will be called after a specific document
 /// is changed on disk.
 final CBLDatabase_AddDocumentChangeListener = _dylib.lookupFunction<
         _c_CBLDatabase_AddDocumentChangeListener,
         _dart_CBLDatabase_AddDocumentChangeListener>(
-    'CBLDatabase_AddDocumentChangeListener');
+    'CBLDatabase_AddDocumentChangeListener_d');
 
 /// Switches the database to buffered-notification mode. Notifications for objects belonging
 /// to this database (documents, queries, replicators, and of course the database) will not be
@@ -479,15 +479,13 @@ typedef CBLDatabaseChangeListener = ffi.Void Function(
 typedef _c_CBLDatabase_AddChangeListener = ffi.Pointer<CBLListenerToken>
     Function(
   ffi.Pointer<CBLDatabase> db,
-  ffi.Pointer<ffi.NativeFunction<CBLDatabaseChangeListener>> listener,
-  ffi.Pointer<ffi.Void> context,
+  ffi.Pointer<ffi.Int8> context,
 );
 
 typedef _dart_CBLDatabase_AddChangeListener = ffi.Pointer<CBLListenerToken>
     Function(
   ffi.Pointer<CBLDatabase> db,
-  ffi.Pointer<ffi.NativeFunction<CBLDatabaseChangeListener>> listener,
-  ffi.Pointer<ffi.Void> context,
+  ffi.Pointer<ffi.Int8> context,
 );
 
 typedef CBLDocumentChangeListener = ffi.Void Function(
@@ -500,16 +498,14 @@ typedef _c_CBLDatabase_AddDocumentChangeListener = ffi.Pointer<CBLListenerToken>
     Function(
   ffi.Pointer<CBLDatabase> db,
   ffi.Pointer<ffi.Int8> docID,
-  ffi.Pointer<ffi.NativeFunction<CBLDocumentChangeListener>> listener,
-  ffi.Pointer<ffi.Void> context,
+  ffi.Pointer<ffi.Int8> context,
 );
 
 typedef _dart_CBLDatabase_AddDocumentChangeListener
     = ffi.Pointer<CBLListenerToken> Function(
   ffi.Pointer<CBLDatabase> db,
   ffi.Pointer<ffi.Int8> docID,
-  ffi.Pointer<ffi.NativeFunction<CBLDocumentChangeListener>> listener,
-  ffi.Pointer<ffi.Void> context,
+  ffi.Pointer<ffi.Int8> context,
 );
 
 typedef CBLNotificationsReadyCallback = ffi.Void Function(

lib/bindings/document.dart

@@ -63,6 +63,11 @@ final CBLDocument_Purge =
 final CBLDocument_Properties = _dylib.lookupFunction<_c_CBLDocument_Properties,
     _dart_CBLDocument_Properties>('CBLDocument_Properties');
 
+/// Returns a document's mutable properties.
+final CBLDocument_MutableProperties = _dylib.lookupFunction<
+    _c_CBLDocument_MutableProperties,
+    _dart_CBLDocument_MutableProperties>('CBLDocument_MutableProperties');
+
 /// Set a document's properties.
 final CBLDocument_SetProperties = _dylib.lookupFunction<
     _c_CBLDocument_SetProperties,
@@ -152,6 +157,15 @@ typedef _dart_CBLDocument_Properties = ffi.Pointer<FLDict> Function(
   ffi.Pointer<CBLDocument> doc,
 );
 
+typedef _c_CBLDocument_MutableProperties = ffi.Pointer<FLMutableDict> Function(
+  ffi.Pointer<CBLDocument> doc,
+);
+
+typedef _dart_CBLDocument_MutableProperties = ffi.Pointer<FLMutableDict>
+    Function(
+  ffi.Pointer<CBLDocument> doc,
+);
+
 typedef _c_CBLDocument_SetProperties = ffi.Void Function(
   ffi.Pointer<CBLDocument> doc,
   ffi.Pointer<FLDict> properties,

lib/bindings/fleece.dart

@@ -23,10 +23,17 @@ final FLDoc_Release = _dylib
 
 // -- FLValue
 
+final FLValue_Retain = _dylib
+    .lookupFunction<_c_FLValue_Retain, _dart_FLValue_Retain>('FLValue_Retain');
+
 final FLValue_Release =
     _dylib.lookupFunction<_c_FLValue_Release, _dart_FLValue_Release>(
         'FLValue_Release');
 
+final FLValue_FromJSON =
+    _dylib.lookupFunction<_c_FLValue_FromJSON, _dart_FLValue_FromJSON>(
+        'FLValue_FromJSON');
+
 /*
 final FLData_ConvertJSON =
     _dylib.lookupFunction<_c_FLData_ConvertJSON, _dart_FLData_ConvertJSON>(
@@ -238,16 +245,6 @@ final FLSlot_SetValue =
     _dylib.lookupFunction<_c_FLSlot_SetValue, _dart_FLSlot_SetValue>(
         'FLSlot_SetValue');
 
-// void FLSlot_SetNull(FLSlot FLNONNULL) FLAPI;             ///< Stores a JSON null into a slot.
-// void FLSlot_SetBool(FLSlot FLNONNULL, bool) FLAPI;       ///< Stores a boolean into a slot.
-// void FLSlot_SetInt(FLSlot FLNONNULL, int64_t) FLAPI;     ///< Stores an integer into a slot.
-// void FLSlot_SetUInt(FLSlot FLNONNULL, uint64_t) FLAPI;   ///< Stores an unsigned integer into a slot.
-// void FLSlot_SetFloat(FLSlot FLNONNULL, float) FLAPI;     ///< Stores a float into a slot.
-// void FLSlot_SetDouble(FLSlot FLNONNULL, double) FLAPI;   ///< Stores a double into a slot.
-// void FLSlot_SetString(FLSlot FLNONNULL, FLString) FLAPI; ///< Stores a string into a slot.
-// void FLSlot_SetData(FLSlot FLNONNULL, FLSlice) FLAPI;    ///< Stores a data blob into a slot.
-// void FLSlot_SetValue(FLSlot FLNONNULL, FLValue) FLAPI;
-
 // -- Key paths
 
 final FLKeyPath_New = _dylib
@@ -266,16 +263,6 @@ final FLKeyPath_EvalOnce =
 
 // -- FLDoc
 
-// typedef _c_FLDoc_FromJSON = ffi.Pointer<FLDoc> Function(
-//   ffi.Pointer<FLSlice> json,
-//   ffi.Pointer<ffi.Uint8> error,
-// );
-
-// typedef _dart_FLDoc_FromJSON = ffi.Pointer<FLDoc> Function(
-//   ffi.Pointer<FLSlice> json,
-//   ffi.Pointer<ffi.Uint8> error,
-// );
-
 typedef _c_FLDoc_FromJSON = ffi.Pointer<FLDoc> Function(
   ffi.Pointer<ffi.Int8> json,
   ffi.Pointer<ffi.Uint8> error,
@@ -312,36 +299,32 @@ typedef _dart_FLDoc_Release = void Function(
 
 // -- FLValue
 
-typedef _c_FLValue_Release = ffi.Void Function(
-  ffi.Pointer<FLValue> value,
+typedef _c_FLValue_FromJSON = ffi.Pointer<FLValue> Function(
+  ffi.Pointer<ffi.Int8> json,
+  ffi.Pointer<ffi.Uint8> error,
 );
 
-typedef _dart_FLValue_Release = void Function(
-  ffi.Pointer<FLValue> value,
+typedef _dart_FLValue_FromJSON = ffi.Pointer<FLValue> Function(
+  ffi.Pointer<ffi.Int8> json,
+  ffi.Pointer<ffi.Uint8> error,
 );
 
-// TODO write one function that does this both
-/*
-typedef _c_FLData_ConvertJSON = ffi.Pointer<FLSliceResult> Function(
-  ffi.Pointer<FLSlice> json,
-  ffi.Pointer<ffi.Uint8> error,
+typedef _c_FLValue_Retain = ffi.Void Function(
+  ffi.Pointer<FLValue> value,
 );
 
-typedef _dart_FLData_ConvertJSON = ffi.Pointer<FLSliceResult> Function(
-  ffi.Pointer<FLSlice> value,
-  ffi.Pointer<ffi.Uint8> error,
+typedef _dart_FLValue_Retain = void Function(
+  ffi.Pointer<FLValue> value,
 );
 
-typedef _c_FLValue_FromData = ffi.Pointer<FLValue> Function(
-  ffi.Pointer<FLSlice> json,
-  ffi.Uint8 trust,
+typedef _c_FLValue_Release = ffi.Void Function(
+  ffi.Pointer<FLValue> value,
 );
 
-typedef _dart_FLValue_FromData = ffi.Pointer<FLValue> Function(
-  ffi.Pointer<FLSlice> value,
-  int trust,
+typedef _dart_FLValue_Release = void Function(
+  ffi.Pointer<FLValue> value,
 );
-*/
+
 typedef _c_FLDump = ffi.Pointer<ffi.Int8> Function(
   ffi.Pointer<FLValue> value,
 );

lib/bindings/library.dart

@@ -18,6 +18,7 @@ part 'fleece.dart';
 part 'listeners.dart';
 part 'query.dart';
 part 'replicator.dart';
+part 'log.dart';
 
 final packagePath = findPackagePath(Directory.current.path);
 final winLibPath = packagePath.isNotEmpty
@@ -210,6 +211,8 @@ class CBLError extends ffi.Struct {
         ..internal_info = internal_info;
 
   void reset() => domain = code = internal_info = 0;
+
+  void free() => pffi.free(addressOf);
 }
 
 // --- Function types
@@ -223,6 +226,8 @@ typedef _dart_CBLError_Message = ffi.Pointer<ffi.Int8> Function(
 );
 
 typedef _c_RegisterDartPorts = ffi.Void Function(
+  ffi.Uint64 database_listener_port,
+  ffi.Uint64 document_listener_port,
   ffi.Uint64 query_listener_port,
   ffi.Uint64 replicator_status_port,
   ffi.Uint64 replicator_filter_port,
@@ -233,6 +238,8 @@ typedef _c_RegisterDartPorts = ffi.Void Function(
 );
 
 typedef _dart_RegisterDartPorts = void Function(
+  int database_listener_port,
+  int document_listener_port,
   int query_listener_port,
   int replicator_status_port,
   int replicator_filter_port,
@@ -256,6 +263,9 @@ typedef _dart_CBL_InstanceCount = int Function();
 
 /// Error domains, serving as namespaces for numeric error codes. */
 enum CBLErrorDomain {
+  /// Dummay value, because the C enum index starts at 1
+  dummy,
+
   ///< code is a Couchbase Lite error code; see \ref CBLErrorCode
   CBLDomain,
 
@@ -280,6 +290,9 @@ enum CBLErrorDomain {
 
 /// Couchbase Lite error codes, in the CBLDomain. */
 enum CBLErrorCode {
+  /// Dummay value, because the C enum index starts at 1
+  dummy,
+
   /*1*/ ///< Internal assertion failure
   CBLErrorAssertionFailed,