Merge branch 'release/1.0.0'

Author: Damiano Giusti

.gitignore

@@ -0,0 +1,9 @@
+.idea/
+build/
+captures/
+*.iml
+.gradle
+local.properties
+.DS_Store
+.externalNativeBuild
+.cxx

CHANGELOG.md

@@ -0,0 +1,11 @@
+# Changelog
+
+### 1.0.0 - (27/03/2020)
+
+First library release.
+
+- Database extensions;
+- Document extensions;
+- Query extensions;
+- Replicator extensions;
+- ResultSet model mapping.

README.md

@@ -1,2 +1,205 @@
-# couchbase-lite-kotlin
+# Couchbase Lite Kotlin
+
 Kotlin-friendly extensions for Couchbase Lite Android and Java SDKs.
+
+Proudly made by [MOLO17 Srl](https://molo17.com/) 🚀
+
+## Kotlin extensions for Couchbase Lite
+
+Couchbase Lite Kotlin is a lightweight library that adds convenient
+extension functions to [Couchbase Lite](https://docs.couchbase.com/couchbase-lite/current/java-android.html)
+Android and Java SDKs.
+
+This library introduces a lightweight wrapper on top of N1QL query language,
+Document creation and much more. Also, it provides support for a more
+fluent listener API, introducing first-class support for
+[Kotlin Coroutines](https://kotlinlang.org/docs/reference/coroutines-overview.html) and the
+[Flow API](https://kotlinlang.org/docs/reference/coroutines/flow.html).
+
+## Installing
+
+Add JitPack as repository for your project:
+
+```groovy
+allprojects {
+    repositories {
+        ...
+        maven { url "https://jitpack.io" }
+    }
+}
+```
+
+And then to your module `build.gradle` file:
+
+```groovy
+implementation "com.github.MOLO17:couchbase-lite-kotlin:1.0.0"
+```
+
+## Contents
+
+Here are the main features that Couchbase Lite Kotlin provides for
+boosting the integration of the Couchbase Lite SDK with Kotlin.
+
+- [QueryBuilder extensions](#querybuilder-extensions)
+- [Document builder DSL](#document-builder-dsl)
+- [Query Flow support](#query-flow-support)
+- [ResultSet model mapping](#resultset-model-mapping)
+- [Database extensions](#database-extensions)
+- [Replicator extensions](#replicator-extensions)
+
+### QueryBuilder extensions
+
+Syntax for building a query has gone more straight-forward thanks to the
+`infix` function support.
+
+```kotlin
+select(all()) from database where { "type" equalTo "user" }
+```
+
+Or just a bunch of fields:
+
+```kotlin
+select("name", "surname") from database where { "type" equalTo "user" }
+```
+
+You can even do more powerful querying:
+
+```kotlin
+select("name", "type")
+  .from(database)
+  .where { 
+    ("type" equalTo "user" and "name" equalTo "Damian") or
+      ("type" equalTo "pet" and "name" like "Kitt") 
+  }
+  .orderBy { "name".ascending() }
+  .limit(10)
+```
+
+### Document builder DSL
+
+For creating a new `MutableDocument` ready to be saved, you can now use
+a new Kotlin DSL:
+
+```kotlin
+val document = MutableDocument {
+  "name" to "Damian"
+  "surname" to "Giusti"
+  "age" to 24
+  "pets" to listOf("Kitty", "Kitten", "Kitto")
+  "type" to "user"
+}
+
+database.save(document)
+```
+
+### Query Flow support
+
+Now Couchbase Lite queries become Flows. Couchbase Lite Kotlin ports
+the coroutines Flow stream API for observing Live Queries results.
+
+```kotlin
+select(all())
+  .from(database)
+  .where { "type" equalTo "user" }
+  .asFlow()
+  .collect { value: ResultSet -> 
+    // consume ResultSet
+  }
+```
+
+As plus, you receive automatic LiveQuery cancellation when the Flow tears down.
+
+### ResultSet model mapping
+
+Thanks to [Map delegation](https://kotlinlang.org/docs/reference/delegated-properties.html#storing-properties-in-a-map),
+mapping a ResultSet to a Kotlin class has never been so easy.
+
+The library provides the `ResultSet.toObjects()` and `Query.asObjectsFlow()`
+extensions for helping to map results given a factory lambda.
+
+Such factory lambda accepts a `Map<String, Any?>` and returns an instance
+of a certain type. Those requirements fits perfectly with a Map-delegated
+class.
+
+```kotlin
+class User(map: Map<String, Any?>) {
+  val name: String by map
+  val surname: String by map
+  val age: Int by map
+}
+
+val users: List<User> = query.execute().toObjects(::User)
+```
+
+```kotlin
+class User(map: Map<String, Any?>) {
+  val name: String by map
+  val surname: String by map
+  val age: Int by map
+}
+
+val users: Flow<List<User>> = query.asObjectsFlow(::User)
+```
+
+### Database extensions
+
+As seen with the Query extensions, the Database has also been powered up.
+
+You can now observe the `DatabaseChange` and `DocumentChangeEvents` using
+the Kotlin Flow API.
+
+```kotlin
+val changes: Flow<DatabaseChange> = database.changesFlow()
+val documentChanges: Flow<DocumentChange> = database.documentChangesFlow(docId)
+```
+
+Also, a new useful syntax has been introduced when performing batch operations:
+
+```kotlin
+database.doInBatch {
+  save(document)
+  delete(otherDocument)
+}
+```
+
+The `Database` is used as receiver in the specified lambda.
+
+### Replicator extensions
+
+Replicator syntax has been boosted with the Kotlin Flow API. You can
+observe events using the following Flows:
+
+```kotlin
+val changesFlow: Flow<ReplicatorChange> = replicator.changesFlow()
+val replicationFlow: Flow<DocumentReplication> = replicator.documentReplicationFlow()
+```
+
+In addition, for Android users, you can now bind the Replicator
+`start()` and `stop()` methods to be performed automatically when your
+[Lifecycle](https://developer.android.com/jetpack/androidx/releases/lifecycle)-enabled
+component gets resumed or paused.
+
+```kotlin
+// Binds the Replicator to the Application lifecycle.
+
+replicator.bindToLifecycle(ProcessLifecycleOwner.get().lifecycle)
+```
+
+```kotlin
+// Binds the Replicator to the Activity/Fragment lifecycle.
+{
+    // inside an Activity or a Fragment ...
+    
+    replicator.bindToLifecycle(lifecycle)
+}
+```
+
+That's it! Replicator will be automatically started when your component
+passes the `ON_RESUME` state, and it will be stopped when the component
+passes the `ON_PAUSED` state. As you may imagine, no further action will
+be made after the `ON_DESTROY` state.
+
+## Authors
+
+- [Damiano Giusti](https://github.com/damianogiusti/)
+- [MOLO17 Srl](https://molo17.com/)

app/.gitignore

@@ -0,0 +1 @@
+/build

app/build.gradle

@@ -0,0 +1,65 @@
+apply plugin: 'com.android.application'
+apply plugin: 'kotlin-android'
+apply plugin: 'kotlin-android-extensions'
+
+android {
+    compileSdkVersion 29
+    buildToolsVersion "29.0.2"
+
+    defaultConfig {
+        applicationId "com.molo17.couchbase.lite"
+        minSdkVersion 22
+        targetSdkVersion 29
+        versionCode 1
+        versionName "1.0"
+
+        testInstrumentationRunner "androidx.test.runner.AndroidJUnitRunner"
+        buildConfigField("String", "REPLICATOR_URL", "\"ws://${findProperty("couchbase.host") ?: "localhost"}:4984/travel-sample\"")
+        buildConfigField("String", "REPLICATOR_USER", "\"${findProperty("couchbase.user") ?: ""}\"")
+        buildConfigField("String", "REPLICATOR_PWD", "\"${findProperty("couchbase.password") ?: ""}\"")
+        buildConfigField("String", "MAPS_API_KEY", "\"${findProperty("couchbase.mapsApiKey") ?: ""}\"")
+    }
+
+    buildTypes {
+        release {
+            minifyEnabled false
+            proguardFiles getDefaultProguardFile('proguard-android-optimize.txt'), 'proguard-rules.pro'
+        }
+    }
+
+    compileOptions {
+        sourceCompatibility 1.8
+        targetCompatibility 1.8
+    }
+
+    kotlinOptions {
+        jvmTarget = "1.8"
+    }
+
+    viewBinding {
+        enabled = true
+    }
+}
+
+dependencies {
+    implementation fileTree(dir: 'libs', include: ['*.jar'])
+    implementation libraries.kotlin
+    implementation libraries.coroutines
+    implementation "com.couchbase.lite:couchbase-lite-android:2.7.0"
+
+    implementation project(":library")
+
+    implementation "androidx.appcompat:appcompat:1.1.0"
+    implementation "androidx.core:core-ktx:1.2.0"
+    implementation "androidx.activity:activity-ktx:1.1.0"
+    implementation "androidx.recyclerview:recyclerview:1.1.0"
+    implementation "androidx.lifecycle:lifecycle-livedata-ktx:2.2.0"
+    implementation "androidx.lifecycle:lifecycle-viewmodel-ktx:2.2.0"
+    implementation "androidx.lifecycle:lifecycle-extensions:2.2.0"
+    implementation "androidx.constraintlayout:constraintlayout:1.1.3"
+    implementation "com.github.bumptech.glide:glide:4.11.0"
+
+    testImplementation libraries.unitTests
+    androidTestImplementation 'androidx.test.ext:junit:1.1.1'
+    androidTestImplementation 'androidx.test.espresso:espresso-core:3.2.0'
+}

app/proguard-rules.pro

@@ -0,0 +1,21 @@
+# Add project specific ProGuard rules here.
+# You can control the set of applied configuration files using the
+# proguardFiles setting in build.gradle.
+#
+# For more details, see
+#   http://developer.android.com/guide/developing/tools/proguard.html
+
+# If your project uses WebView with JS, uncomment the following
+# and specify the fully qualified class name to the JavaScript interface
+# class:
+#-keepclassmembers class fqcn.of.javascript.interface.for.webview {
+#   public *;
+#}
+
+# Uncomment this to preserve the line number information for
+# debugging stack traces.
+#-keepattributes SourceFile,LineNumberTable
+
+# If you keep the line number information, uncomment this to
+# hide the original source file name.
+#-renamesourcefileattribute SourceFile

app/src/androidTest/java/com/molo17/couchbase/lite/ExampleInstrumentedTest.kt

@@ -0,0 +1,24 @@
+package com.molo17.couchbase.lite
+
+import androidx.test.platform.app.InstrumentationRegistry
+import androidx.test.ext.junit.runners.AndroidJUnit4
+
+import org.junit.Test
+import org.junit.runner.RunWith
+
+import org.junit.Assert.*
+
+/**
+ * Instrumented test, which will execute on an Android device.
+ *
+ * See [testing documentation](http://d.android.com/tools/testing).
+ */
+@RunWith(AndroidJUnit4::class)
+class ExampleInstrumentedTest {
+    @Test
+    fun useAppContext() {
+        // Context of the app under test.
+        val appContext = InstrumentationRegistry.getInstrumentation().targetContext
+        assertEquals("com.molo17.couchbase.lite", appContext.packageName)
+    }
+}

app/src/main/AndroidManifest.xml

@@ -0,0 +1,25 @@
+<?xml version="1.0" encoding="utf-8"?>
+<manifest xmlns:android="http://schemas.android.com/apk/res/android"
+    package="com.molo17.couchbase.lite">
+
+    <uses-permission android:name="android.permission.INTERNET" />
+
+    <application
+        android:name=".MainApp"
+        android:allowBackup="false"
+        android:icon="@mipmap/ic_launcher"
+        android:label="@string/app_name"
+        android:roundIcon="@mipmap/ic_launcher_round"
+        android:supportsRtl="true"
+        android:theme="@style/AppTheme"
+        android:usesCleartextTraffic="true">
+        <activity android:name=".MainActivity">
+            <intent-filter>
+                <action android:name="android.intent.action.MAIN" />
+
+                <category android:name="android.intent.category.LAUNCHER" />
+            </intent-filter>
+        </activity>
+    </application>
+
+</manifest>