suggest examples

Author: gregolsky

README.md

@@ -699,6 +699,38 @@ const revisions = await session.advanced.revisions.getFor("users/1");
 //     id: 'users/1' } ]
 ```
 
+### Suggestions
+```javascript
+// Having data:
+// [ User {
+//     name: 'John',
+//     age: 30,
+//     registeredAt: 2017-11-10T23:00:00.000Z,
+//     kids: [Array],
+//     id: 'users/1-A' },
+//   User {
+//     name: 'Stefanie',
+//     age: 25,
+//     registeredAt: 2015-07-29T22:00:00.000Z,
+//     id: 'users/2-A' } ]
+
+// and a static index like:
+class UsersIndex extends AbstractIndexCreationTask {
+    constructor() {
+        super();
+        this.map = "from doc in docs.Users select new { doc.name }";
+        this.suggestion("name");
+    }
+}
+
+// ...
+
+const session = store.openSession();
+const suggestionQueryResult = await session.query({ collection: "users" })
+    .suggestUsing(x => x.byField("name", "Jon"))
+    .execute();
+// { name: { name: 'name', suggestions: [ 'john' ] } }
+```
 
 
 ## Using object literals for entities

test/Documents/ReadmeSamples.ts

@@ -11,6 +11,7 @@ import {
     IDocumentSession,
     QueryStatistics,
     StreamQueryStatistics,
+    AbstractIndexCreationTask,
 } from "../../src";
 import { TypeUtil } from "../../src/Utility/TypeUtil";
 
@@ -406,6 +407,27 @@ describe("Readme query samples", function () {
             });
         });
 
+        it("can suggest", async () => {
+            class UsersIndex extends AbstractIndexCreationTask {
+                constructor() {
+                    super();
+                    this.map = "from doc in docs.Users select new { doc.name }";
+                    this.suggestion("name");
+                }
+            }
+
+            await store.executeIndex(new UsersIndex());
+            await testContext.waitForIndexing(store);
+
+            {
+                const session = store.openSession();
+                const suggestionQueryResult = await session.query({ indexName: "UsersIndex" })
+                    .suggestUsing(x => x.byField("name", "Jon"))
+                    .execute();
+                assert.strictEqual(suggestionQueryResult.name.suggestions.length, 1);
+            }
+        });
+
     });
 
     describe("with revisions set up", function() {