From 8c4e4a9985f4b74c39b67bfb1088443da971a605 Mon Sep 17 00:00:00 2001
From: Dima Sabanin <sdmitry@gmail.com>
Date: Wed, 17 Jan 2018 12:28:37 -0500
Subject: [PATCH] [nano] Support for db/_find API with Mango query language.
 (#22833)

* Support for db/_find API with Mango query language.

* Clean up for linter.
---
 types/nano/index.d.ts    | 87 ++++++++++++++++++++++++++++++++++++++++
 types/nano/nano-tests.ts | 36 +++++++++++++++++
 2 files changed, 123 insertions(+)

diff --git a/types/nano/index.d.ts b/types/nano/index.d.ts
index 152954190d..7fafa72382 100644
--- a/types/nano/index.d.ts
+++ b/types/nano/index.d.ts
@@ -261,6 +261,8 @@ declare namespace nano {
       params: DocumentViewParams,
       callback?: Callback<any>
     ): Request;
+    // http://docs.couchdb.org/en/latest/api/database/find.html#db-find
+    find(query: MangoQuery, callback?: Callback<MangoResponse<D>>): Request;
     server: ServerScope;
   }
 
@@ -1044,6 +1046,91 @@ declare namespace nano {
     // Current update sequence for the database
     update_seq: any;
   }
+
+  type MangoValue = number | string | Date | boolean;
+
+  // http://docs.couchdb.org/en/latest/api/database/find.html#selector-syntax
+  interface MangoSelector {
+    [key: string]: MangoSelector | MangoValue | MangoValue[];
+  }
+
+  // http://docs.couchdb.org/en/latest/api/database/find.html#sort-syntax
+  type SortOrder = string | string[] | { [key: string]: 'asc' | 'desc' };
+
+  interface MangoQuery {
+    // JSON object describing criteria used to select documents.
+    selector: MangoSelector;
+
+    // Maximum number of results returned. Default is 25.
+    limit?: number;
+
+    // Skip the first 'n' results, where 'n' is the value specified.
+    skip?: number;
+
+    // JSON array following sort syntax.
+    sort?: SortOrder[];
+
+    // JSON array specifying which fields of each object should be returned. If it is omitted,
+    // the entire object is returned.
+    // http://docs.couchdb.org/en/latest/api/database/find.html#filtering-fields
+    fields?: string[];
+
+    // Instruct a query to use a specific index.
+    // Specified either as "<design_document>" or ["<design_document>", "<index_name>"].
+    use_index?: string | [string, string];
+
+    // Read quorum needed for the result. This defaults to 1.
+    r?: number;
+
+    // A string that enables you to specify which page of results you require. Used for paging through result sets.
+    bookmark?: string;
+
+    // Whether to update the index prior to returning the result. Default is true.
+    update?: boolean;
+
+    // Whether or not the view results should be returned from a “stable” set of shards.
+    stable?: boolean;
+
+    // Combination of update = false and stable = true options.Possible options: "ok", false (default).
+    stale?: 'ok' | false;
+
+    // Include execution statistics in the query response. Optional, default: false.
+    execution_stats?: boolean;
+  }
+
+  interface MangoResponse<D> {
+    // Array of documents matching the search. In each matching document, the fields specified in
+    // the fields part of the request body are listed, along with their values.
+    docs: D[];
+
+    // A string that enables you to specify which page of results you require. Used for paging through result sets.
+    bookmark?: string;
+
+    // Execution warnings
+    warning?: string;
+
+    // Basic execution statistics for a specific request.
+    execution_stats?: MangoExecutionStats;
+  }
+
+  // http://docs.couchdb.org/en/latest/api/database/find.html#execution-statistics
+  interface MangoExecutionStats {
+    // Number of index keys examined. Currently always 0.
+    total_keys_examined: number;
+
+    // Number of documents fetched from the database / index, equivalent to using include_docs = true in a view.
+    total_docs_examined: number;
+
+    // Number of documents fetched from the database using an out - of - band document fetch.
+    // This is only non - zero when read quorum > 1 is specified in the query parameters.
+    total_quorum_docs_examined: number;
+
+    // Number of results returned from the query.
+    results_returned: number;
+
+    // Total execution time in milliseconds as measured by the database.
+    execution_time_ms: number;
+  }
 }
 
 export = nano;
diff --git a/types/nano/nano-tests.ts b/types/nano/nano-tests.ts
index d38f54bae2..4f13e90f43 100644
--- a/types/nano/nano-tests.ts
+++ b/types/nano/nano-tests.ts
@@ -118,6 +118,42 @@ mydb.show(
 );
 mydb.replicate("database_replica", (error: any) => {});
 
+const req = mydb.find({
+  selector: {
+    userId: 1234,
+    name: 'Paul',
+    status: { $ne: 'suspended' },
+    age: { $gt: 69 },
+    building: {
+      number: {
+        $in: [101, 203, 205]
+      }
+    }
+  },
+  skip: 10,
+  limit: 1,
+  use_index: "user_index_doc",
+  fields: ['name', 'age'],
+  sort: [{ age: 'desc' }, { name: 'asc' }],
+  r: 2,
+  stale: 'ok',
+  execution_stats: true
+}, (resp: nano.MangoResponse<SomeDocument>, error: any) => {
+  for (const doc of resp.docs) {
+    console.log(doc.name);
+  }
+
+  if (resp.warning) {
+    console.error(resp.warning);
+  }
+
+  if (resp.execution_stats) {
+    console.log(`Execution time: ${resp.execution_stats.execution_time_ms} ms.`);
+  }
+});
+
+req.abort();
+
 /*
  * Attachments
  */