Merge pull request #513 from kuzzleio/7.2.0-proposal

# [7.2.0](https://github.com/kuzzleio/sdk-javascript/releases/tag/7.2.0) (2020-04-28)


#### Bug fixes

- [ [#508](#508) ] Fix SearchResult.next with sort/size   ([Aschen](https://github.com/Aschen))
- [ [#512](#512) ] Fix token expired   ([Aschen](https://github.com/Aschen))
- [ [#511](#511) ] Avoid to mutate user options   ([Aschen](https://github.com/Aschen))
- [ [#507](#507) ] Fix collection getMapping   ([Aschen](https://github.com/Aschen))

#### New features

- [ [#510](#510) ] Add security:refresh   ([Yoann-Abbes](https://github.com/Yoann-Abbes))

#### Enhancements

- [ [#509](#509) ] Add the rate limit property to Profile objects   ([scottinet](https://github.com/scottinet))
---

.gitignore

@@ -18,7 +18,10 @@ doc/framework
 dead_links.json
 
 # Cypress debug
-doc/6/getting-started/.react/cypress/screenshots
-doc/6/getting-started/.react/cypress/videos
-doc/6/getting-started/.vuejs/cypress/screenshots
-doc/6/getting-started/.vuejs/cypress/videos
+doc/7/getting-started/.react/cypress/screenshots
+doc/7/getting-started/.react/cypress/videos
+doc/7/getting-started/.vuejs/cypress/screenshots
+doc/7/getting-started/.vuejs/cypress/videos
+
+# Debug snippets
+test-*.js

doc/7/controllers/security/refresh/index.md

@@ -0,0 +1,35 @@
+---
+code: true
+type: page
+title: refresh
+---
+
+# refresh
+
+Forces an immediate [reindexation](https://www.elastic.co/guide/en/elasticsearch/reference/7.4/docs-refresh.html) of the provided security collection.
+
+The available security collections are: `users`, `profiles`, `roles`.
+
+When writing or deleting documents in Kuzzle, the changes need to be indexed before being reflected in the search results.
+By default, this operation can take up to 1 second.
+
+::: warning
+Forcing immediate refreshes comes with performance costs, and should only performed when absolutely necessary.
+:::
+
+
+```js
+refresh(collection);
+```
+
+## Arguments
+
+- `collection`: collection name to refresh
+
+## Resolves
+
+Resolves when the refresh has been done.
+
+## Usage
+
+<<< ./snippets/refresh.js

doc/7/controllers/security/refresh/snippets/refresh.js

@@ -0,0 +1,6 @@
+try {
+  await kuzzle.security.refresh('users');
+  console.log('Success');
+} catch (e) {
+  console.error(e);
+}

doc/7/controllers/security/refresh/snippets/refresh.test.yml

@@ -0,0 +1,5 @@
+name: security#refresh
+description: Refreshes security collection
+hooks:
+template: default
+expected: Success

doc/7/core-classes/search-result/next/index.md

@@ -20,9 +20,9 @@ next();
 
 Resolves to a `SearchResult` object, or to `null` if no more pages are available.
 
-## Throw
+## Rejects
 
-This method throws an exception if:
+This method returns a rejected promise with an error if:
 
 - No pagination strategy can be applied (see below)
 - If invoking it would lead to more than 10 000 items being retrieved with the `from/size` strategy
@@ -56,19 +56,26 @@ You can restrict the scroll session maximum duration under the `services.storage
 
 If the initial search contains `sort` and `size` parameters, the `next` method retrieves the next page of results following the sort order, the last item of the current page acting as a live cursor.
 
-To avoid too many duplicates, it is advised to provide a sort combination that will always identify one item only. The recommended way is to use the field `_uid` which is certain to contain one unique value for each document.
+This strategy uses Elasticsearch [search_after](https://www.elastic.co/guide/en/elasticsearch/reference/7.4/search-request-body.html#request-body-search-search-after) parameter.
+
+::: warning
+You have to provide a sort combination that will always identify one item only. The recommended way is to use the field `_id` which is certain to contain one unique value for each document.
+To prevent partial retrieval of results, the SDK will reject with an error if the sort combination can identify multiple items.
+:::
 
 Because this method does not freeze the search results between two calls, there can be missing or duplicated documents between two result pages.
 
 This method efficiently mitigates the costs of scroll searches, but returns less consistent results: it's a middle ground, ideal for real-time search requests.
 
+<<< ./snippets/sortsize.js
+
 ### Strategy: from / size
 
 If the initial search contains `from` and `size` parameters, the `next` method retrieves the next page of result by incrementing the `from` offset.
 
 Because this method does not freeze the search results between two calls, there can be missing or duplicated documents between two result pages.
 
 It's the fastest pagination method available, but also the less consistent, and it is not possible to retrieve more than 10000 items using it.  
-Above that limit, any call to `next` throws an Exception.
+Above that limit, any call to `next` will return a rejected promise with an error.
 
 <<< ./snippets/fromsize.js

doc/7/core-classes/search-result/next/snippets/sortsize.js

@@ -0,0 +1,47 @@
+try {
+  const documents = [];
+
+  for (let i = 0; i < 100; i++) {
+    documents.push({ _id: `suv_no${i}`, body: { category: 'suv' } });
+  }
+
+  await kuzzle.document.mCreate('nyc-open-data', 'yellow-taxi', documents, {
+    refresh: 'wait_for'
+  });
+
+  let results = await kuzzle.document.search(
+    'nyc-open-data',
+    'yellow-taxi',
+    {
+      query: { match: { category: 'suv' } },
+      sort: [
+        { '_kuzzle_info.createdAt': 'desc' },
+        '_id'
+      ]
+    },
+    { size: 5 });
+
+  // Fetch the matched items by advancing through the result pages
+  const matched = [];
+
+  while (results) {
+    matched.push(...results.hits);
+    results = await results.next();
+  }
+
+  console.log(matched[0]);
+  /*
+    { _id: 'suv_no1',
+      _score: 0.03390155,
+      _source:
+       { _kuzzle_info:
+          { author: '-1',
+            updater: null,
+            updatedAt: null,
+            createdAt: 1570093133057 },
+         category: 'suv' } }
+  */
+  console.log(`Successfully retrieved ${matched.length} documents`);
+} catch (error) {
+  console.error(error.message);
+}

doc/7/core-classes/search-result/next/snippets/sortsize.test.yml

@@ -0,0 +1,11 @@
+name: searchresult#sortsize
+description: Next method with sort/size
+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
+  after: |
+    curl -XDELETE kuzzle:7512/nyc-open-data
+template: default
+expected: Successfully retrieved 100 documents

doc/7/getting-started/react-native/index.md

@@ -16,7 +16,7 @@ This section deals with **Kuzzle V2** (+ **Javascript SDK 7**) and **React Nativ
 
 - **Node.js** >= 12.0.0 ([install here](https://nodejs.org/en/download/))
 - **Running Kuzzle V2 Stack** ([instructions here](/core/2/guides/getting-started/running-kuzzle))
-- **Expo CLI** ([install here](https://docs.expo.io/versions/v36.0.0/get-started/installation/))
+- **Expo CLI** ([install here](https://docs.expo.io/get-started/installation))
 
 "[Expo](https://docs.expo.io/versions/latest/) is a framework and a platform for universal React applications. It is a set of tools and services built around React Native and native platforms that help you develop, build, deploy, and quickly iterate on iOS, Android, and web apps from the same JavaScript/TypeScript codebase."