Add Kotlin serialization-based APIs

[snej]

Implements Kotlin extension methods that use serialization to allow developers to work with documents and query rows as native Kotlin classes. (Equivalent to the Swift API extensions implemented last year.)

Query Results & ResultSets

/** Uses Kotlin Serialization to create an object of type [T] from the query row.
 *  If the [key] parameter is non-null, it uses the row's value for that key as the source,
 *  instead of the entire row.
 *
 *  For example, if your query is `SELECT name, age, shoeSize FROM people` and you have a
 *  serializable Person class with properties name, age and shoeSize, you can call:
 *  `val person = result.data<Person>()`
 *
 *  Or you could use the query `SELECT * as person FROM people` and create the Person with
 *  `val person = result.data<Person>("person")`.
 */
@ExperimentalSerializationApi
inline fun <reified T> Result.data(key: String? = null): T

/** Returns the query rows transformed by Kotlin Serialization into instances of [T]. */
@ExperimentalSerializationApi
inline fun <reified T> ResultSet.data(key: String? = null): Sequence<T>

Documents

Document model classes must implement a new interface DocumentModel that defines a documentMeta property that stores the document id and revID, which is needed in order to save the document.

/** Document model classes must implement this interface.
 *  It adds a [documentMeta] property that's used by Couchbase Lite. */
interface DocumentModel {
    /** This tags the model instance with the document ID and revision it was read from,
     *  which enables conflict detection when it's later saved.
     *  You may read this property, but DO NOT alter it.
     *  It should be implemented as a stored property defaulting to `null`, for example:
     *  `@Transient override var documentMeta: DocumentMeta? = null` */
    @Transient var documentMeta: DocumentMeta?
}

/** Stores the Couchbase Lite metadata of a document. Used by the [DocumentModel] interface. */
class DocumentMeta internal constructor(val collection: Collection?,
                                        val id: String,
                                        val revisionID: String)

Documents can be loaded and saved as model instances:

/** Gets an existing document with the given ID, and uses Kotlin Serialization to create an
 *  instance of class [T] from it. [T] must implement [DocumentModel].
 *  If a document with the given ID doesn't exist in the collection, returns null. */
@ExperimentalSerializationApi
inline fun <reified T: DocumentModel> Collection.getDocumentAs(id: String): T? =
    getDocumentAs(id, serializer())

/** Saves a [DocumentModel] instance as a document in the collection, with a specified conflict handler.
 *  If the model's [DocumentModel.documentMeta] property is null, it will be saved as a new document with the
 *  given [docID], which must not be null.
 *  Otherwise the [DocumentModel.documentMeta] property determines the document ID and prior revision ID, and the
 *  [docID] parameter should be null.
 *  After a successful save, the [DocumentModel.documentMeta] property is updated to the current state. */
@ExperimentalSerializationApi
inline fun <reified T: DocumentModel> Collection.save(model: T,
                                                      docID: String? = null,
                                                      noinline conflictHandler: ModelConflictHandler<T>? = null) =

Lower-Level

Both of these use some new internal functions that serialize Kotlin classes to and from Fleece.

/** Uses Kotlin Serialization to encode an arbitrary object or collection to Fleece.
 *  @param value  The object to encode.
 *  @param encoder  A Fleece [FLEncoder] to use; defaults to a fresh instance.
 *  @return  The encoded Fleece data. */
@ExperimentalSerializationApi
inline fun <reified T> serializeToFleece(value: T, encoder: FLEncoder? = null): ByteArray

/** Decodes an object from a Fleece [FLValue] using Kotlin Serialization. */
@ExperimentalSerializationApi
inline fun <reified T> deserializeFromFleece(root: FLValue): T

[snej]

I just noticed that Swift has model-based Collection.delete and Collection.purge methods; I'll add those.

[pasin]

In Swift, we also support id == nil as an auto generated id for a newly created doc. Can we allow that here as well?

[snej]

Done!

[pasin]

Can we also allow null docID here (an auto id (uuid) will be generated)?

[snej]

Done!

[pasin]

Does the body need to be retained as well?

I read iOS code, and iOS is doing something similar. If I read the code correctly, Swift's DocumentEncoder calls FLEncoder_FinishDoc that returns an FLDoc, get the dict from the FLDoc, set the dict to the CBL doc, and abandon the FLDoc. So maybe the data is retained by the dict?

- (BOOL)finishIntoDocument:(CBLDocument*)document error:(NSError**)outError {
    FLError error {};
    FLDoc fldoc = FLEncoder_FinishDoc(_encoder, &error);
    if (!fldoc) {
        return convertError(error, outError);
    }
    Doc doc { fldoc };
    Dict fleeceData = doc.asDict();
    if (!fleeceData) {
        return NO;
    }
    [document setFleece: (FLDict)fleeceData];
    return YES;
}

[snej]

That Obj-C code above leaks the FLDoc, unfortunately. (The Doc constructor retains the FLDoc, then releases it when the function returns. But nothing releases the +1 ref returned by FLEncoder_FinishDoc.

That leak is the only reason it doesn't crash, I think, unless the setFleece: method is doing something clever like explicitly retaining the FLDict.

[snej]

I confess I can't figure out how the memory management of Fleece objects works in the Java code. Do you or Jim have any better knowledge of it?