Add Observer class (#671)

Add an `Observer` class to manipulate `RealtimeDocument`.

Those documents have the same structure as the `Document` object from the Document Controller except that they are connected to the realtime engine and their content will mutate when a realtime notification about changes is received.

```js
const observer = new Observer(sdk);

// SearchResult containing realtime documents
let realtimeResult = await observer.search('nyc-open-data', 'yellow-taxi', { query }, options);

// Dispose ressources (realtime connection + memory)
observer.stop('nyc-open-data', 'yellow-taxi');
```

Author: Aschen

doc/7/controllers/auth/search-api-keys/snippets/search-api-keys-es.test.yml

@@ -3,18 +3,27 @@ try {
 
   console.log(response);
   /*
-  { mapping:
-    { policies:
-      { properties:
-        { restrictedTo:
-          { properties:
-            { collections:
-              { type: 'text',
-                fields: { keyword: { type: 'keyword', ignore_above: 256 } } },
-              index:
-              { type: 'text',
-                fields: { keyword: { type: 'keyword', ignore_above: 256 } } } } },
-          roleId: { type: 'keyword' } } } } }
+  {
+    "mapping": {
+      "policies": {
+        "properties": {
+          "roleId": {
+            "type": "keyword"
+          },
+          "restrictedTo": {
+            "properties": {
+              "collections": {
+                "type": "text"
+              }
+            },
+            "index": {
+              "type": "text"
+            }
+          }
+        }
+      },
+    }
+  }
    */
 } catch (e) {
   console.error(e);

doc/7/controllers/security/get-profile-mapping/snippets/get-profile-mapping.js

@@ -2,4 +2,4 @@ name: security#getProfileMapping
 description: get profile mapping
 template: default
 expected:
-  - "mapping: { policies: { properties: \\[Object\\] } }"
+  - "mapping: { policies: { properties: \\[Object\\]"

doc/7/controllers/security/get-profile-mapping/snippets/get-profile-mapping.test.yml

@@ -0,0 +1,55 @@
+---
+code: true
+type: page
+title: get
+description: Observer get method
+---
+
+# get
+
+<SinceBadge version="auto-version" />
+
+Gets a realtime document
+
+::: info
+This method uses the [Document.get](/sdk/js/7/controllers/document/get) method under the hood to retrieve document.
+:::
+
+## Arguments
+
+```js
+get (index: string, collection: string, id: string, options: any): Promise<RealtimeDocument>
+```
+
+| Argument | Type | Description |
+|----------|------|-------------|
+| `index` | <pre>string</pre> | Index name |
+| `collection` | <pre>string</pre> | Collection name |
+| `id` | <pre>string</pre> | Document ID |
+| `options` | <pre>any</pre> | Additional options |
+
+## Usage
+
+```js
+const observer = new Observer(sdk);
+
+const doc = await observer.get('nyc-open-data', 'yellow-taxi', 'some-id');
+
+console.log(doc);
+/*
+  RealtimeDocument {
+    _id: 'some-id',
+    _source: {
+      name: 'aschen',
+      age: '29',
+      _kuzzle_info: {
+        author: '-1',
+        createdAt: 1638432270522,
+        updatedAt: null,
+        updater: null
+      }
+    },
+    deleted: false
+  }
+*/
+```

doc/7/controllers/security/search-api-keys/snippets/search-api-keys-es.test.yml

@@ -0,0 +1,6 @@
+---
+code: true
+type: branch
+title: Observer
+description: Observer class documentation
+---

doc/7/core-classes/observer/get/index.md

@@ -0,0 +1,37 @@
+---
+code: false
+type: page
+title: Introduction
+description: Observer class
+order: 0
+---
+
+# Observer
+
+<SinceBadge version="auto-version" />
+
+The `Observer` class allows to manipulate realtime documents.
+A `RealtimeDocument` is like a normal document from Kuzzle except that it is
+connected to the realtime engine and it's content will change with changes
+occuring on the database.
+
+They can be retrieved using methods with the same syntax as in the Document
+Controller:
+
+```js
+const docs = await observer.get('nyc-open-data', 'yellow-taxi', 'foobar');
+
+const result = await observer.search('nyc-open-data', 'yellow-taxi', {
+  query: { exists: 'licence' }
+});
+```
+
+Realtime documents are resources that should be disposed via the [Observer.stop](/sdk/js/7/core-classes/observer/stop) method otherwise subscriptions will never be terminated, documents will be kept into memory, which might lead to a memory leak.
+
+```js
+await observer.stop('nyc-open-data', 'yellow-taxi');
+```
+
+A good frontend practice is to instantiate one observer for the actual page
+and/or component(s) displaying realtime documents and to dispose them when
+they are not displayed anymore.

doc/7/core-classes/observer/index.md

@@ -0,0 +1,71 @@
+---
+code: true
+type: page
+title: mGet
+description: Observer mGet method
+---
+
+# mGet
+
+<SinceBadge version="auto-version" />
+
+
+Gets multiple realtime documents.
+
+::: info
+This method uses the [Document.mGet](/sdk/js/7/controllers/document/m-get) method under the hood to retrieve documents.
+:::
+
+## Arguments
+
+```js
+mGet (index: string, collection: string, ids: string[]): Promise<{ successes: RealtimeDocument[]; errors: string[]; }>
+```
+
+| Argument | Type | Description |
+|----------|------|-------------|
+| `index` | <pre>string</pre> | Index name |
+| `collection` | <pre>string</pre> | Collection name |
+| `ids` | <pre>string[]</pre> | Document IDs |
+
+## Usage
+
+```js
+const observer = new Observer(sdk);
+
+const docs = await observer.get('nyc-open-data', 'yellow-taxi', ['foo', 'bar']);
+
+console.log(docs);
+/*
+  [
+    RealtimeDocument {
+      _id: 'foo',
+      _source: {
+        name: 'aschen',
+        age: '28',
+        _kuzzle_info: {
+          author: '-1',
+          createdAt: 1638432270522,
+          updatedAt: null,
+          updater: null
+        }
+      },
+      deleted: false
+    },
+    RealtimeDocument {
+      _id: 'bar',
+      _source: {
+        name: 'dana',
+        age: '30',
+        _kuzzle_info: {
+          author: '-1',
+          createdAt: 1638432270522,
+          updatedAt: null,
+          updater: null
+        }
+      },
+      deleted: false
+    }
+  ]
+*/
+```

doc/7/core-classes/observer/introduction/index.md

@@ -0,0 +1,52 @@
+---
+code: true
+type: page
+title: observe
+description: Observer observe method
+---
+
+# observe
+
+<SinceBadge version="auto-version" />
+
+Retrieve a realtime document from a document
+
+## Arguments
+
+```js
+observe (index: string, collection: string, document: Document): Promise<RealtimeDocument>
+```
+
+| Argument | Type | Description |
+|----------|------|-------------|
+| `index` | <pre>string</pre> | Index name |
+| `collection` | <pre>string</pre> | Collection name |
+| `document` | <pre>Document</pre> | Document to observe |
+
+## Usage
+
+```js
+const observer = new Observer(sdk);
+
+const doc = await sdk.document.get('nyc-open-data', 'yellow-taxi', 'some-id');
+
+const realtimeDoc = await observer.observe('nyc-open-data', 'yellow-taxi', doc);
+
+console.log(realtimeDoc);
+/*
+  RealtimeDocument {
+    _id: 'some-id',
+    _source: {
+      name: 'aschen',
+      age: '29',
+      _kuzzle_info: {
+        author: '-1',
+        createdAt: 1638432270522,
+        updatedAt: null,
+        updater: null
+      }
+    },
+    deleted: false
+  }
+*/
+```

doc/7/core-classes/observer/m-get/index.md

@@ -0,0 +1,62 @@
+---
+code: true
+type: page
+title: search
+description: Observer search method
+---
+
+# search
+
+<SinceBadge version="auto-version" />
+
+Searches for documents and returns a SearchResult containing realtime
+documents.
+
+::: info
+This method uses the [Document.search](/sdk/js/7/controllers/document/search) method under the hood to retrieve documents.
+:::
+
+## Arguments
+
+```js
+search (index: string, collection: string, searchBody: JSONObject, options: JSONObject): Promise<RealtimeDocumentSearchResult>
+```
+
+| Argument | Type | Description |
+|----------|------|-------------|
+| `index` | <pre>string</pre> | Index name |
+| `collection` | <pre>string</pre> | Collection name |
+| `searchBody` | <pre>JSONObject</pre> | Search body |
+| `options` | <pre>JSONObject</pre> | Additional options |
+
+## Usage
+
+```js
+const observer = new Observer(sdk);
+
+let result = await observer.search('nyc-open-data', 'yellow-taxi', {
+  query: { exists: 'licence' }
+});
+
+console.log(result);
+/*
+  RealtimeDocumentSearchResult {
+    aggregations: undefined,
+    hits: [
+      RealtimeDocument {
+        _id: 'some-id',
+        _source: [Object],
+        deleted: false
+      },
+      RealtimeDocument {
+        _id: 'XaMyen0BDorKTmOQPm2u',
+        _source: [Object],
+        deleted: false
+      }
+    ],
+    fetched: 2,
+    total: 2,
+    suggest: undefined
+  }
+*/
+```