Merge pull request #434 from kuzzleio/6.2.0-proposal

# [6.2.0](https://github.com/kuzzleio/sdk-javascript/releases/tag/6.2.0) (2019-07-31)


#### Bug fixes

- [ [#428](#428) ] Properly handle boolean flags in HTTP querystrings   ([scottinet](https://github.com/scottinet))
- [ [#427](#427) ] Solve promise+event+memory leaks when the network fails   ([scottinet](https://github.com/scottinet))
- [ [#424](#424) ] Prevent pending request leak when disconnect the SDK   ([Aschen](https://github.com/Aschen))
- [ [#422](#422) ] Fix bug when decoding JWT in browser   ([Aschen](https://github.com/Aschen))
- [ [#420](#420) ] Fix http protocol unresolved promise on connection error   ([Aschen](https://github.com/Aschen))

#### New features

- [ [#419](#419) ] Add bulk:write and bulk:mWrite   ([Aschen](https://github.com/Aschen))

#### Enhancements

- [ [#421](#421) ] Get api routes from server:publicApi   ([Aschen](https://github.com/Aschen))
- [ [#423](#423) ] Emit queryError event on malformed request   ([Aschen](https://github.com/Aschen))
- [ [#417](#417) ] Security controller documentation   ([benoitvidis](https://github.com/benoitvidis))
---

Author: scottinet

.eslintrc.json

@@ -46,7 +46,7 @@
     "semi": [2, "always"],
     "keyword-spacing": 2,
     "space-before-blocks": 2,
-    "space-in-parens": [2, "never"],
+    "space-in-parens": [0, "never"],
     "vars-on-top": 2,
     "yoda": [2, "never"]
   },

.gitignore

@@ -14,3 +14,6 @@ examples/node_modules/
 
 # Compiled files
 coverage/
+
+doc/framework
+dead_links.json

.travis.yml

@@ -1,10 +1,16 @@
 sudo: true
 
+env:
+  global:
+    - AWS_ACCESS_KEY_ID=AKIAIYAXFUAHXOWP2MJA
+    # AWS_SECRET_ACCESS_KEY
+    - secure: "HU48VGBdv/GyVAm6g8eiA3DbKoAPL98AeORbF7UhKLQenxmQRGb1gfdMPNLdop35+95SlxcFC9ogoHcqLBSPLLcTSX57faWpNacD/7j69Z03avgdmfaFOGMOwGd5tOdq4pYmis34xyGJW1kpwAl2U6jp/pcBXABDnCLfRS5kJUsXvrwdE75UACoXQ1tXEtqq9y5LcFo/dGYrhuVvqYQmAUA+ExrfXaIKtUSf2tN5CvYL0cSxLyoQlnbbIQvouyNRyfuGFqNHc3jyBOc/nZWHS0ES91+6ddwZs/i9Fs98TfB3JS9x+gKYWrhDmxek/fOy22+qYUHQ81txk4SQ3GILWiWTfWOTdsBU+Y0FYnC5syLAqpdIstBhmMUUS8NWs5HdYmBv4q0zkTiwBGL/wrLwXkAcLLKUNOrUeMAL1fjQuVRC3hzql15s/A2LwPOR6xwyCu1mH8GKogYulGVWOEHQuk8bC3MaKgDr/4ZoUlCC9Q+mYP/WT+t/NA/0OQIvZVhVVilXk1MTbQMkvrBSuiuxACsyFGVNrkLaC8x2Pjyd2kgZaIv4c2JiiWfvW5IZd7xeyLLKESOfHP8rIf60jmvE7hxD9Yje7JXjo0uvnpEGx2PuMSq5zeUynoLaa8AIMAJ9an3fgdfKKcZ/XPOCAgpmxnKH+leAQx86qwxdAAIkgPY="
+
 jobs:
   include:
-    - name: Sdk tests
-      stage: Tests
-      sudo: false
+    - stage: Tests
+      name: Unit Tests
+      if: type = pull_request OR type = push AND branch =~ /^master|[0-9]+-(dev|stable)$/ OR type = cron
       language: node_js
       node_js: 8
 
@@ -76,13 +82,80 @@ jobs:
 
       before_script:
         - npm run doc-prepare
-        - npm run --prefix doc/framework clone-repos
+        - npm run --prefix doc/framework repositories -- clone
+      script:
+        - gem install typhoeus
+        - HYDRA_MAX_CONCURRENCY=20 npm run --prefix doc/framework dead-links
+
+
+    - stage: Deployment Doc Dev
+      name: Deploy next-docs.kuzzle.io
+      if: type = push AND branch =~ .*-dev
+      language: node_js
+      node_js: 10
+      env:
+        - NODE_ENV=production
+        - S3_BUCKET=docs-next.kuzzle.io
+        - CLOUDFRONT_DISTRIBUTION_ID=E2ZCCEK9GRB49U
+        - AWS_DEFAULT_REGION=us-west-2
+
+      addons:
+        apt:
+          packages:
+            - python
+            - python-pip
+
+      install:
+        - pip install awscli --upgrade --user
+
       script:
-        - npm run --prefix doc/framework dead-links
+        - npm run doc-prepare
+        - npm run doc-build
+
+      deploy:
+        provider: script
+        script:
+          - npm run doc-upload
+        skip_cleanup: true
 
+      after_deploy:
+        - npm run doc-cloudfront
+
+    # - stage: Deployment Doc Prod
+    #   name: Deploy docs.kuzzle.io
+    #   if: type = push AND branch =~ /^master|[0-9]+-stable$/
+    #   language: node_js
+    #   node_js: 10
+    #   env:
+    #     - NODE_ENV=production
+    #     - S3_BUCKET=docs.kuzzle.io
+    #     - CLOUDFRONT_DISTRIBUTION_ID=E3D6RP0POLCJMM
+    #     - AWS_DEFAULT_REGION=us-west-2
+
+    #   addons:
+    #     apt:
+    #       packages:
+    #         - python
+    #         - python-pip
+
+    #   install:
+    #     - pip install awscli --upgrade --user
+
+    #   script:
+    #     - npm run doc-prepare
+    #     - npm run doc-build
+
+    #   deploy:
+    #     provider: script
+    #     script:
+    #       - npm run doc-upload
+    #     skip_cleanup: true
+
+    #   after_deploy:
+    #     - npm run doc-cloudfront
 
     - stage: Deploy Stable release on NPM
-      if: branch = master AND tag IS present AND type != cron
+      if: branch =~ /^master|[0-9]+-stable$/ AND tag IS present AND type != cron
       sudo: false
       language: node_js
       node_js: 8
@@ -110,13 +183,9 @@ jobs:
         email: [email protected]
         api_key:
           secure: ktfR6QVV59uCVLTfb60JSjPxzxg+UYe63pIGxU9awh1wJW89SQqQdeshHas3ojwrNoMOVybx/L6owtD8uIB4Xlau6pd7StBAA1VQ3vLa6RxU5SUr9VOz3RhZutRnYXH28Ziz/ynr6zVnwGxTzFsxBAdQ9CVS3ErBzliTgMVI+52YRNB3mBDiccSKVNGmp2APiWiaEidrmaOFkCwWQKsAxFTbBoCsDYGGAq8a8b1i2nE+BL4JWB1D2x55xzFaciDIQONXnY9YPAAbzCHBTKAne5iD6XwFj7Zg/42fHTn16LBSG+Sw+7aWyV11U6SJYKAjm/5GZEUrbvX/mwNQ7VYcvMStiP1nnt/L/s/Y7d0K3mwdsV8U8RCctElOeqLsDqoBzQYAxHTqRqJzyFNMcbcMhZgsHH5LgQDoJdKFwzP2ysYoazgm/jnr9atvlqucjWU8madRS34S8wD0zGjYf8VXH3WMUvL5mFwtb58FRCZKO3G7QJlGE8bdZ8CfJa/1tFnYY9SA0018GaXbh0RqQw0RskbmXEKTlnDBxaRd/ZjfaOjF4JcMGGZ8hsCRjxuDFY5Ki0kKDAlDV1W40fkkqPVm8k9H8Elwt0UFZvvAdjG4c+gV0zdAKHQ7P6uKvXiDlsKRHulE3Ztpo6jqGN69s7aLm6DKNVsaE4cNmmUOv3ODrM4=
-        on:
-          repo: kuzzleio/sdk-javascript
-          all_branches: true
-          condition: $TRAVIS_BRANCH = master
 
-    - stage: "Deploy Beta release on NPM"
-      if: type != pull_request && branch =~ ^[0-9]+-beta$
+    - stage: Deploy Beta release on NPM
+      if: type = push && branch =~ /^[0-9]+-dev$/
       sudo: false
       language: node_js
       node_js: 8

bug.js

@@ -0,0 +1,15 @@
+const Kuzzle  = require('./index').Kuzzle;
+
+
+const kuzzle = new Kuzzle('websocket', {host: 'localhost'});
+
+async function run() {
+ await kuzzle.connect();
+ const roomID = await kuzzle.realtime.subscribe('obix', 'firmwares', {}, (r) => {
+   console.log(r);
+ })
+
+ await kuzzle.realtime.publish('obix', 'firmware', {msg: 'hello world'})
+}
+
+run()

doc/6/.vuepress

@@ -0,0 +1 @@
+../framework/src/.vuepress/

doc/6/controllers/bulk/mWrite/index.md

@@ -0,0 +1,70 @@
+---
+code: true
+type: page
+title: mWrite
+description: Creates or replaces multiple documents directly into the storage engine.
+---
+
+# mWrite
+
+<SinceBadge version="6.2.0" />
+
+<SinceBadge version="Kuzzle 1.8.0" />
+
+Creates or replaces multiple documents directly into the storage engine.
+
+This is a low level route intended to bypass Kuzzle actions on document creation, notably:
+  - check [document validity](/core/1/guides/essentials/data-validation),
+  - add [kuzzle metadata](/core/1/guides/essentials/document-metadata),
+  - trigger [realtime notifications](/core/1/guides/essentials/real-time) (unless asked otherwise)
+
+<br/>
+
+```js
+mWrite (index, collection, documents, [options])
+```
+
+<br/>
+
+| Argument     | Type              | Description          |
+| ------------ | ----------------- | -------------------- |
+| `index`      | <pre>string</pre> | Index name           |
+| `collection` | <pre>string</pre> | Collection name      |
+| `documents`   | <pre>object[]</pre> | Array of objects representing the documents     |
+| `options`    | <pre>object</pre> | Query options        |
+
+### documents
+
+An array of objects. Each object describes a document to create or replace, by exposing the following properties:
+  - `_id`: document unique identifier (optional)
+  - `body`: document content
+
+### options
+
+Additional query options
+
+| Property   | Type<br/>(default)              | Description        |
+| ---------- | ------------------------------- | ------------------ |
+| `queuable` | <pre>boolean</pre><br/>(`true`) | If true, queues the request during downtime, until connected to Kuzzle again |
+| `notify` | <pre>boolean</pre><br/>(`false`) | if set to true, Kuzzle will trigger realtime notifications |
+| `refresh`  | <pre>string</pre><br/>(`""`)    | If set to `wait_for`, waits for the change to be reflected for `search` (up to 1s) |
+
+---
+
+## Resolves
+
+Returns a `hits` array, containing the list of created documents, in the same order than the one provided in the query.
+
+Each created document is an object with the following properties:
+
+| Name      | Type              | Description  |
+| --------- | ----------------- | ------------------- |
+| `_id`      | <pre>string</pre> | ID of the newly created document                       |
+| `_version` | <pre>number</pre> | Version of the document in the persistent data storage |
+| `_source`  | <pre>object</pre> | Created document   |
+
+If one or more document creations fail, the promise is rejected and the `error` object contains a [partial error](/core/1/api/essentials/errors/#partialerror) error.
+
+## Usage
+
+<<< ./snippets/mWrite.js

doc/6/controllers/bulk/mWrite/snippets/mWrite.js

@@ -0,0 +1,47 @@
+try {
+  const documents = [
+    {
+      _id: 'panipokari',
+      body: {
+        licence: 'B',
+        _kuzzle_info: { creator: 'bahi', createdAt: 746186305 }
+      }
+    },
+    {
+      body: {
+        licence: 'B',
+        _kuzzle_info: { creator: 'dahi', createdAt: 835005505 }
+      }
+    }
+  ];
+
+  const result = await kuzzle.bulk.mWrite(
+    'nyc-open-data',
+    'yellow-taxi',
+    documents
+  );
+
+  console.log(result);
+  /*
+  { hits:
+    [ { _id: 'panipokari',
+        _source: {
+          "licence": "B",
+          "_kuzzle_info": {
+            "creator": "bahi",
+            "createdAt": 746186305 } },
+        _version: 1 },
+      { _id: 'AWvlrMIZE7sKlamkyoHr',
+        _source: {
+          "licence": "B",
+          "_kuzzle_info": {
+            "creator": "dahi",
+            "createdAt": 835005505 } },
+        _version: 1 } ],
+    total: 2 }
+  */
+
+  console.log(`Document creator is ${result.hits[1]._source._kuzzle_info.creator}`);
+} catch (error) {
+  console.error(error.message);
+}

doc/6/controllers/bulk/mWrite/snippets/mWrite.test.yml

@@ -0,0 +1,10 @@
+---
+name: bulk#mWrite
+description: Creates or replaces multiple documents directly into the storage engine.
+hooks:
+  before: |
+    curl -X DELETE kuzzle:7512/nyc-open-data
+    curl -X POST kuzzle:7512/nyc-open-data/_create
+    curl -X PUT kuzzle:7512/nyc-open-data/yellow-taxi
+template: default
+expected: Document creator is dahi

doc/6/controllers/bulk/write/index.md

@@ -0,0 +1,61 @@
+---
+code: true
+type: page
+title: write
+description: Creates or replaces a document directly into the storage engine.
+---
+
+# write
+
+<SinceBadge version="6.2.0" />
+
+<SinceBadge version="Kuzzle 1.8.0" />
+
+Creates or replaces a document directly into the storage engine.
+
+This is a low level route intended to bypass Kuzzle actions on document creation, notably:
+  - check [document validity](/core/1/guides/essentials/data-validation),
+  - add [kuzzle metadata](/core/1/guides/essentials/document-metadata),
+  - trigger [realtime notifications](/core/1/guides/essentials/real-time) (unless asked otherwise).
+
+<br/>
+
+```js
+write (index, collection, document, [id], [options])
+```
+
+<br/>
+
+| Argument     | Type              | Description          |
+| ------------ | ----------------- | -------------------- |
+| `index`      | <pre>string</pre> | Index name           |
+| `collection` | <pre>string</pre> | Collection name      |
+| `document`   | <pre>object</pre> | Document content     |
+| `id`         | <pre>string</pre> | Optional document ID |
+| `options`    | <pre>object</pre> | Query options        |
+
+### options
+
+Additional query options
+
+| Property   | Type<br/>(default)              | Description        |
+| ---------- | ------------------------------- | ------------------ |
+| `queuable` | <pre>boolean</pre><br/>(`true`) | If true, queues the request during downtime, until connected to Kuzzle again |
+| `notify` | <pre>boolean</pre><br/>(`false`) | if set to true, Kuzzle will trigger realtime notifications |
+| `refresh`  | <pre>string</pre><br/>(`""`)    | If set to `wait_for`, waits for the change to be reflected for `search` (up to 1s) |
+
+---
+
+## Resolves
+
+Resolves to an object containing the document creation result.
+
+| Name      | Type              | Description                                            |
+| --------- | ----------------- | ------------------------------------------------------ |
+| `_id`      | <pre>string</pre> | ID of the newly created document                       |
+| `_version` | <pre>number</pre> | Version of the document in the persistent data storage |
+| `_source`  | <pre>object</pre> | Created document  |                      
+
+## Usage
+
+<<< ./snippets/write.js

doc/6/controllers/bulk/write/snippets/write.js

@@ -0,0 +1,28 @@
+try {
+  const document = {
+    licence: 'B',
+    _kuzzle_info: {
+      creator: 'liia',
+      createdAt: 653132233
+    }
+  };
+
+  const result = await kuzzle.bulk.write(
+    'nyc-open-data',
+    'yellow-taxi',
+    document
+  );
+
+  console.log(result);
+  /*
+  { _id: 'AWvljct6E7sKlamkyoHl',
+    _version: 1,
+    _source:
+     { licence: 'B',
+       _kuzzle_info: { creator: 'liia', createdAt: 653132233 } }
+  */
+
+  console.log(`Document creator is ${result._source._kuzzle_info.creator}`);
+} catch (error) {
+  console.error(error.message);
+}