feat(find): add optional hint parameter for the cursor

Adds the ability to supply an index hint to the mongo find query.

This is useful for situations where there's an optimal index for a
query, but mongo doesn't use it.

Author: Garret Meier

spec/findSpec.js

@@ -501,8 +501,26 @@ describe('find', (it) => {
         t.false(res.hasPrevious);
       });
 
+      it('should use a the hint parameter', async (t) => {
+        const collection = t.context.db.collection('test_paging');
+        await t.context.db.collection('test_paging').ensureIndex({ color: 1 }, { name: 'color_1' });
+        // First page.
+        const res = await paging.find(collection, {
+          query: {
+            color: 'blue',
+          },
+          hint: 'color_1',
+        });
+
+        t.is(res.results.length, 5);
+        t.is(res.results[0].color, 'blue');
+        t.false(res.hasNext);
+        t.false(res.hasPrevious);
+      });
+
       it('should use the "fields" parameter', async (t) => {
         const collection = t.context.db.collection('test_paging');
+
         // First page.
         const res = await paging.find(collection, {
           query: {

src/find.js

@@ -25,6 +25,7 @@ const config = require('./config');
  *    -previous {String} The value to start querying previous page.
  *    -after {String} The _id to start querying the page.
  *    -before {String} The _id to start querying previous page.
+ *    -hint {String} An optional index hint to provide to the mongo query
  */
 module.exports = async function(collection, params) {
   const removePaginatedFieldInResponse = params.fields && !params.fields[params.paginatedField];
@@ -49,10 +50,10 @@ module.exports = async function(collection, params) {
    * See mongo documentation: https://docs.mongodb.com/manual/reference/collation/#collation-and-index-use
    */
   const collatedQuery = config.COLLATION ? query.collation(config.COLLATION) : query;
-  const results = await collatedQuery
-    .sort($sort)
-    .limit(params.limit + 1) // Query one more element to see if there's another page.
-    .toArray();
+  // Query one more element to see if there's another page.
+  const cursor = collatedQuery.sort($sort).limit(params.limit + 1);
+  if (params.hint) cursor.hint(params.hint);
+  const results = await cursor.toArray();
 
   const response = prepareResponse(results, params);