Merge pull request #636 from kuzzleio/587-document-deleteFields

Add support for the document:deleteFields API action

Author: Shiranuit

doc/7/controllers/document/delete-fields/index.md

@@ -0,0 +1,46 @@
+---
+code: true
+type: page
+title: deleteFields
+description: Deletes fields of an existing document.
+---
+
+# delete
+
+Deletes fields of an existing document.
+
+The optional parameter `refresh` can be used with the value `wait_for` in order to wait for the document to be indexed (and to no longer be available in search).
+
+<br/>
+
+```js
+deleteFields (index, collection, id, fields, [options]);
+```
+
+| Argument     | Type                | Description                                                        |
+| ------------ | ------------------- | ------------------------------------------------------------------ |
+| `index`      | <pre>string</pre>   | Index name                                                         |
+| `collection` | <pre>string</pre>   | Collection name                                                    |
+| `id`         | <pre>string</pre>   | Document ID                                                        |
+| `fields`     | <pre>string[]</pre> | [Path](https://lodash.com/docs/4.17.15#toPath) of fields to delete |
+| `options`    | <pre>object</pre>   | Query options                                                      |
+
+### Options
+
+Additional query options
+
+| Options    | Type<br/>(default)               | Description                                                                                                           |
+| ---------- | -------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
+| `queuable` | <pre>boolean</pre><br/>(`true`)  | If true, queues the request during downtime, until connected to Kuzzle again                                          |
+| `refresh`  | <pre>string</pre><br/>(`""`)     | If set to `wait_for`, waits for the change to be reflected for `search` (up to 1s)                                    |
+| `silent`   | <pre>boolean</pre><br/>(`false`) | If `true`, then Kuzzle will not generate notifications <SinceBadge version="7.5.3"/>                                  |
+| `source`   | <pre>boolean</pre><br/>(`false`) | If `true`, then the response will contain the updated document                                                        |
+| `timeout`  | <pre>number</pre>                | Time (in ms) during which a request will still be waited to be resolved. Set it `-1` if you want to wait indefinitely |
+
+## Resolves
+
+Resolves to updated document.
+
+## Usage
+
+<<< ./snippets/deleteFields.js

doc/7/controllers/document/delete-fields/snippets/deleteFields.js

@@ -0,0 +1,7 @@
+try {
+  const response = await kuzzle.document.deleteFields('nyc-open-data', 'yellow-taxi', 'some-id', ['bar'], {source: true});
+
+  console.log(response._source);
+} catch (error) {
+  console.error(error.message);
+}

doc/7/controllers/document/delete-fields/snippets/deleteFields.test.yml

@@ -0,0 +1,11 @@
+name: document#delete
+description: Deletes a document from kuzzle
+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
+    curl --fail -H "Content-type: application/json" -XPUT -d '{"foo": "bar", "bar": "baz"}' kuzzle:7512/nyc-open-data/yellow-taxi/some-id
+  after:
+template: default
+expected: {"foo": "bar"}

src/controllers/Document.ts

@@ -211,6 +211,50 @@ export class DocumentController extends BaseController {
       .then(response => response.result.ids);
   }
 
+  /**
+   * Deletes fields of an existing document.
+   *
+   * @see https://docs.kuzzle.io/core/2/api/controllers/document/delete-fields/
+   *
+   * @param index Index name
+   * @param collection Collection name
+   * @param _id Document ID
+   * @param options Additional options
+   *    - `queuable` If true, queues the request during downtime, until connected to Kuzzle again
+   *    - `refresh` If set to `wait_for`, Kuzzle will not respond until the API key is indexed
+   *    - `silent` If true, then Kuzzle will not generate notifications
+   *    - `source` If true, the response will contain the updated document
+   *    - `timeout` Request Timeout in ms, after the delay if not resolved the promise will be rejected
+   *
+   * @returns The updated document
+   */
+  deleteFields(
+    index: string,
+    collection: string,
+    _id: string,
+    fields: string[],
+    options: {
+      queuable?: boolean,
+      refresh?: 'wait_for',
+      silent?: boolean,
+      source?: boolean,
+      timeout?: number,
+    } = {}
+  ): Promise<Document> {
+    const request = {
+      index,
+      collection,
+      _id,
+      body: { fields },
+      action: 'deleteFields',
+      silent: options.silent,
+      source: options.source,
+    };
+  
+    return this.query(request, options)
+      .then(response => response.result);
+  }
+
   /**
    * Checks if the given document exists.
    *

test/controllers/document.test.js

@@ -118,6 +118,36 @@ describe('Document Controller', () => {
     });
   });
 
+  
+  describe('deleteFields', () => {
+    it('should call document/deleteFields query and return a Promise which resolves the updated document', () => {
+      kuzzle.query.resolves({result: {_id: 'document-id', _source: {foo: 'bar'}}});
+      options.silent = true;
+
+      const optionsCopy = Object.assign({}, options);
+      optionsCopy.source = true;
+
+      return kuzzle.document.deleteFields('index', 'collection', 'document-id', ['bar'], optionsCopy)
+        .then(res => {
+          should(kuzzle.query)
+            .be.calledOnce()
+            .be.calledWithMatch({
+              controller: 'document',
+              action: 'deleteFields',
+              index: 'index',
+              collection: 'collection',
+              _id: 'document-id',
+              body: {fields: ['bar']},
+              silent: true,
+              source: true,
+            }, optionsCopy);
+
+          should(res._id).be.equal('document-id');
+          should(res._source.foo).be.equal('bar');
+        });
+    });
+  });
+
   describe('deleteByQuery', () => {
     it('should call document/deleteByQuery query and return a Promise which resolves the list of deleted document ids', () => {
       kuzzle.query.resolves({result: {ids: ['foo', 'bar', 'baz']}});