feat: Add method Sort.nested (#71)

`Sort.nested` was introduced in elasticsearch >= 6.1 for specifying
both path and filter.
Add deprecation comment in docs for `nestedPath` and `nestedFilter`
methods usage in elasticsearch >= 6.1.

src/core/sort.js

@@ -106,6 +106,9 @@ class Sort {
      * field inside this nested object. When sorting by nested field, this field
      * is mandatory.
      *
+     * Note: This method has been deprecated in elasticsearch 6.1. From 6.1 and
+     * later, use `nested` method instead.
+     *
      * @example
      * const sort = esb.sort('offer.price', 'asc')
      *     .nestedPath('offer')
@@ -124,12 +127,15 @@ class Sort {
      * for its field values to be taken into account by sorting. By default no
      * `nested_filter` is active.
      *
+     * Note: This method has been deprecated in elasticsearch 6.1. From 6.1 and
+     * later, use `nested` method instead.
+     *
      * @example
      * const sort = esb.sort('offer.price', 'asc')
      *     .nestedPath('offer')
      *     .nestedFilter(esb.termQuery('offer.color', 'blue'));
      *
-     * @param {Query} filterQuery
+     * @param {Query} filterQuery Filter query
      * @returns {Sort} returns `this` so that calls can be chained.
      * @throws {TypeError} If filter query is not an instance of `Query`
      */
@@ -140,6 +146,35 @@ class Sort {
         return this;
     }
 
+    /**
+     * Defines on which nested object to sort and the filter that the inner objects inside
+     * the nested path should match with in order for its field values to be taken into
+     * account by sorting
+     *
+     * Note: This method is incompatible with elasticsearch 6.0 and older.
+     * Use it only with elasticsearch 6.1 and later.
+     *
+     * @example
+     * const sort = esb.sort('offer.price', 'asc')
+     *     .nested({
+     *          path: 'offer',
+     *          filter: esb.termQuery('offer.color', 'blue')
+     *      });
+     *
+     * @param {Object} nested Nested config that contains path and filter
+     * @param {string} nested.path Nested object to sort on
+     * @param {Query} nested.filter Filter query
+     * @returns {Sort} returns `this` so that calls can be chained.
+     * @throws {TypeError} If filter query is not an instance of `Query`
+     */
+    nested(nested) {
+        const { filter } = nested;
+        if (!isNil(filter)) checkType(filter, Query);
+
+        this._opts.nested = nested;
+        return this;
+    }
+
     /**
      * The missing parameter specifies how docs which are missing the field should
      * be treated: The missing value can be set to `_last`, `_first`, or a custom value

src/index.d.ts

@@ -8297,6 +8297,9 @@ declare namespace esb {
          * field inside this nested object. When sorting by nested field, this field
          * is mandatory.
          *
+         * Note: This method has been deprecated in elasticsearch 6.1. From 6.1 and
+         * later, use `nested` method instead.
+         *
          * @param {string} path Nested object to sort on
          */
         nestedPath(path: string): this;
@@ -8306,11 +8309,28 @@ declare namespace esb {
          * for its field values to be taken into account by sorting. By default no
          * `nested_filter` is active.
          *
+         * Note: This method has been deprecated in elasticsearch 6.1. From 6.1 and
+         * later, use `nested` method instead.
+         * 
          * @param {Query} filterQuery
          * @throws {TypeError} If filter query is not an instance of `Query`
          */
         nestedFilter(filterQuery: Query): this;
 
+        /**
+         * Defines on which nested object to sort and the filter that the inner objects inside
+         * the nested path should match with in order for its field values to be taken into
+         * account by sorting
+         *
+         * Note: This method is incompatible with elasticsearch 6.0 and older.
+         * Use it only with elasticsearch 6.1 and later.
+         *
+         * @param {Object} nested Nested config that contains path and filter
+         * @param {string} nested.path Nested object to sort on
+         * @param {Query} nested.filter Filter query
+         */
+        nested(nested: { path: string, filter: Query }): this;
+
         /**
          * The missing parameter specifies how docs which are missing the field should
          * be treated: The missing value can be set to `_last`, `_first`, or a custom value

test/core-test/sort.test.js

@@ -44,6 +44,19 @@ test(validatedCorrectly, getInstance, 'unit', [
 );
 test(setsOption, 'nestedPath', { param: 'offer' });
 test(setsOption, 'nestedFilter', { param: filterQry });
+test(setsOption, 'nested', {
+    param: {
+        filter: filterQry,
+        path: 'offer'
+    },
+    keyName: 'nested'
+});
+test(setsOption, 'nested', {
+    param: {
+        path: 'offer'
+    },
+    keyName: 'nested'
+});
 test(setsOption, 'missing', { param: '_last' });
 test(setsOption, 'unmappedType', { param: 'long' });
 test(setsOption, 'reverse', { param: true });