Add document:upsert (#56)

Add document:upsert API action

doc/2/controllers/document/upsert/index.md

@@ -0,0 +1,60 @@
+---
+code: true
+type: page
+title: upsert
+description: Applies partial changes to a document. If the document doesn't already exist, a new document is created.
+---
+
+# upsert
+
+<SinceBadge version="Kuzzle 2.8.0"/>
+<SinceBadge version="auto-version" />
+
+Applies partial changes to a document. If the document doesn't already exist, a new document is created.
+
+
+```dart
+  Future<Map<String, dynamic>> upsert(
+    String index,
+    String collection,
+    String id,
+    Map<String, dynamic> changes, {
+    bool waitForRefresh = false,
+    int retryOnConflict,
+    bool source,
+  })
+```
+
+| Argument     | Type              | Description                               |
+| ------------ | ----------------- | ----------------------------------------- |
+| `index`      | <pre>String</pre> | Index name                                |
+| `collection` | <pre>String</pre> | Collection name                           |
+| `id`         | <pre>String</pre> | Document ID                               |
+| `changes`       | <pre>Map<String, dynamic></pre> | Partial content of the document to update |
+
+### Options
+
+Additional query options
+
+| Options           | Type<br/>(default)              | Description                                                                        |
+| ----------------- | ------------------------------- | ---------------------------------------------------------------------------------- |
+| `defaults` | <pre>Map<String, dynamic></pre><br/>(`{}`)  | (optional) fields to add to the document if it gets created  |
+| `waitForRefresh`         | <pre>bool</pre><br/>(`""`)    | If set to `true`, waits for the change to be reflected for `search` (up to 1s) |
+| `retryOnConflict` | <pre>int</pre><br/>(`10`)        | The number of times the database layer should retry in case of version conflict    |
+| `source`          | <pre>bool</pre><br/>(`false`)| If true, returns the updated document inside the response
+
+
+## Returns
+
+A `Map<String, dynamic>` with the following properties:
+
+| Property     | Type                                         | Description                      |
+|------------- |--------------------------------------------- |--------------------------------- |
+| `_source`    | <pre>Map<String, dynamic></pre> | Updated document (if `source` option set to true)  |
+| `_id`        | <pre>String</pre>                            | ID of the udated document                   |
+| `_version`   | <pre>int</pre>                           | Version of the document in the persistent data storage |
+| `created`     | <pre>bool</pre> | If `true`, a new document was created, otherwise the document existed and was updated |
+
+## Usage
+
+<<< ./snippets/upsert.dart

doc/2/controllers/document/upsert/snippets/upsert.dart

@@ -0,0 +1,6 @@
+final result = await kuzzle
+  .document
+  .upsert('nyc-open-data', 'yellow-taxi', 'some-id', {
+      'changes': { 'category': 'suv' },
+    },
+  );

doc/2/controllers/document/upsert/snippets/upsert.test.yml

@@ -0,0 +1,10 @@
+name: document#upsert
+description: Applies a partial update to an existing document.
+hooks:
+  before: |
+    curl -XDELETE kuzzle:7512/nyc-open-data
+    curl -XPOST kuzzle:7512/nyc-open-data/_create
+    curl -XPUT kuzzle:7512/nyc-open-data/yellow-taxi
+  after:
+template: print-result
+expected: "{_id: some-id, _version: 1, created: true}"

lib/src/controllers/document.dart

@@ -352,7 +352,7 @@ class DocumentController extends KuzzleController {
   ///
   /// Optional
   ///
-  /// **[refresh]**: if set to wait_for, Kuzzle will not respond
+  /// **[waitForRefresh]**: if set to wait_for, Kuzzle will not respond
   /// until the update is indexed \\\
   /// **[retryOnConflict]**: conflicts may occur if the same document gets updated multiple times within a short timespan, in a database cluster. You can set the retryOnConflict optional argument (with a retry count), to tell Kuzzle to retry the failing updates the specified amount of times before rejecting the request with an error. \\\
   /// **[source]**: if set to true Kuzzle will return the updated document body in the response \\\
@@ -421,6 +421,50 @@ class DocumentController extends KuzzleController {
     return response.result as Map<String, dynamic>;
   }
 
+  /// ####Applies a partial update to an existing document.
+  /// If the document doesn't already exist, a new document is created.
+  ///
+  /// **[index]**: index name \\\
+  /// **[collection]**: collection name \\\
+  /// **[id]**: unique identifier of the document to update \\\
+  /// **[changes]**: Partial changes to apply to the document
+
+  ///
+  /// Optional
+  ///
+  /// **[defaults]**: Fields to add to the document if it gets created
+  /// **[waitForRefresh]**: if set to wait_for, Kuzzle will not respond
+  /// until the update is indexed \\\
+  /// **[retryOnConflict]**: conflicts may occur if the same document gets updated multiple times within a short timespan, in a database cluster. You can set the retryOnConflict optional argument (with a retry count), to tell Kuzzle to retry the failing updates the specified amount of times before rejecting the request with an error. \\\
+  /// **[source]**: if set to true Kuzzle will return the updated document body in the response \\\
+  Future<Map<String, dynamic>> upsert(
+    String index,
+    String collection,
+    String id,
+    Map<String, dynamic> changes, {
+    Map<String, dynamic> defaults,
+    bool waitForRefresh = false,
+    int retryOnConflict,
+    bool source,
+  }) async {
+    final response = await kuzzle.query(KuzzleRequest(
+      controller: name,
+      action: 'upsert',
+      index: index,
+      collection: collection,
+      uid: id,
+      body: {
+        'changes': changes,
+        'defaults': defaults
+      },
+      waitForRefresh: waitForRefresh,
+      source: source,
+      retryOnConflict: retryOnConflict,
+    ));
+
+    return response.result as Map<String, dynamic>;
+  }
+
   /// Validates data against existing validation rules.
   ///
   /// Documents are always valid if no validation rules are defined

lib/src/kuzzle/request.dart

@@ -206,7 +206,6 @@ class KuzzleRequest {
     if (source != null) {
       map['source'] = source;
     }
-
     if (includeKuzzleMeta != null) {
       map['includeKuzzleMeta'] = includeKuzzleMeta;
     }