Merge pull request #544 from kuzzleio/7.4.0-proposal

# [7.4.0](https://github.com/kuzzleio/sdk-javascript/releases/tag/7.4.0) (2020-08-18) #### New features - [ [#542](#542) ] Finalize typescript support ([Aschen](https://github.com/Aschen)) - [ [#529](#529) ] Add typescript support for protocols ([Aschen](https://github.com/Aschen)) #### Enhancements - [ [#541](#541) ] Add meaningful stacktrace ([Aschen](https://github.com/Aschen)) - [ [#537](#537) ] Add typescript support realtime ([Aschen](https://github.com/Aschen)) - [ [#531](#531) ] Add typescript support for Index and Collection controllers ([Aschen](https://github.com/Aschen)) - [ [#530](#530) ] Add typescript support for search results ([Aschen](https://github.com/Aschen)) - [ [#523](#523) ] Add support for the collection:delete API action ([morgandruesne](https://github.com/morgandruesne)) ---
kuzzleio · Aug 18, 2020 · 1a985a5 · 1a985a5
2 parents 3b9d209 + 3401e54
commit 1a985a5
Show file tree

Hide file tree

Showing 102 changed files with 2,638 additions and 1,803 deletions.
diff --git a/.eslintignore b/.eslintignore
@@ -3,12 +3,26 @@ src/**/*.d.ts
 src/**/*.js.map
 
 src/Kuzzle.js
+src/KuzzleError.js
 src/controllers/Auth.js
 src/controllers/Document.js
+src/controllers/Realtime.js
+src/controllers/Index.js
+src/controllers/Collection.js
 src/controllers/Base.js
 src/core/security/User.js
 src/core/security/Profile.js
 src/core/security/Role.js
+src/protocols/abstract/Base.js
+src/protocols/abstract/Realtime.js
+src/protocols/Http.js
+src/protocols/WebSocket.js
+src/protocols/index.js
 src/utils/interfaces.js
+src/core/KuzzleEventEmitter.js
 src/core/searchResult/SearchResultBase.js
 src/core/searchResult/Document.js
+src/core/searchResult/Profile.js
+src/core/searchResult/Role.js
+src/core/searchResult/Specifications.js
+src/core/searchResult/User.js
diff --git a/.eslintc-ts.json → .eslintrc-ts.json b/.eslintc-ts.json → .eslintrc-ts.json
diff --git a/.gitignore b/.gitignore
@@ -31,12 +31,26 @@ test-*.js
 *.js.map
 index.js
 src/Kuzzle.js
+src/KuzzleError.js
 src/controllers/Auth.js
 src/controllers/Document.js
+src/controllers/Index.js
+src/controllers/Collection.js
 src/controllers/Base.js
+src/controllers/Realtime.js
 src/core/security/User.js
 src/core/security/Profile.js
 src/core/security/Role.js
+src/protocols/abstract/Base.js
+src/protocols/abstract/Realtime.js
+src/protocols/Http.js
+src/protocols/WebSocket.js
+src/protocols/index.js
 src/utils/interfaces.js
+src/core/KuzzleEventEmitter.js
 src/core/searchResult/SearchResultBase.js
 src/core/searchResult/Document.js
+src/core/searchResult/Profile.js
+src/core/searchResult/Role.js
+src/core/searchResult/Specifications.js
+src/core/searchResult/User.js
diff --git a/.travis.yml b/.travis.yml
@@ -32,6 +32,7 @@ jobs:
 
       install:
         - npm install
+        - npm run build
 
       script:
         - npm run test:lint
@@ -78,7 +79,7 @@ jobs:
         - npm install
         - npm run build
       script:
-        - npm run doc-testing
+        - travis_retry npm run doc-testing
 
     - stage: Tests
       name: Dead link check
@@ -93,7 +94,7 @@ jobs:
         - $(npm bin)/kuzdoc framework:link -d /sdk/js/7/ -v 7
       script:
         - gem install typhoeus
-        - cd doc/framework/ && HYDRA_MAX_CONCURRENCY=20 ruby .ci/dead-links.rb -p src/sdk/js/7/
+        - cd doc/framework/ && HYDRA_MAX_CONCURRENCY=20 travis_retry ruby .ci/dead-links.rb -p src/sdk/js/7/
 
     - stage: Deployment Doc Dev
       name: Deploy next-docs.kuzzle.io

diff --git a/doc/7/controllers/auth/create-api-key/index.md b/doc/7/controllers/auth/create-api-key/index.md
@@ -56,7 +56,7 @@ The API key content has the following properties:
 | Name      | Type              | Description      |
 | --------- | ----------------- | ---------------- |
 | `userId`      | <pre>string</pre> | User kuid |
-| `expiresAt`  | <pre>number</pre> | Expiration date in UNIX micro-timestamp format (`-1` if the token never expires) |
+| `expiresAt`  | <pre>number</pre> | Expiration date in Epoch-millis format (`-1` if the token never expires) |
 | `ttl`  | <pre>number</pre> | Original TTL |
 | `description`  | <pre>string</pre> | API key description |
 | `token`  | <pre>string</pre> | Authentication token associated with this API key |

diff --git a/doc/7/controllers/auth/create-api-key/snippets/create-api-key.test.yml b/doc/7/controllers/auth/create-api-key/snippets/create-api-key.test.yml
@@ -2,7 +2,7 @@ name: auth#createApiKey
 description: Creates a new API key for the currently loggued user.
 hooks:
   before: >
-    curl -H "Content-type: application/json" -d '{
+    curl --fail -H "Content-type: application/json" -d '{
       "content": {
         "profileIds": ["default"]
       },

diff --git a/doc/7/controllers/auth/delete-api-key/snippets/delete-api-key.js b/doc/7/controllers/auth/delete-api-key/snippets/delete-api-key.js
@@ -1,5 +1,5 @@
 try {
-  await kuzzle.auth.login('local', { username: 'john.doe', password: 'password' });
+  await kuzzle.auth.login('local', { username: 'jane.doe', password: 'password' });
 
   await kuzzle.auth.deleteApiKey('fQRa28BsidO6V_wmOcL');
 

diff --git a/doc/7/controllers/auth/delete-api-key/snippets/delete-api-key.test.yml b/doc/7/controllers/auth/delete-api-key/snippets/delete-api-key.test.yml
@@ -2,23 +2,23 @@ name: auth#deleteApiKey
 description: Deletes an API key for the currently loggued user
 hooks:
   before: >
-    curl -H "Content-type: application/json" -d '{
+    curl --fail -H "Content-type: application/json" -d '{
       "content": {
         "profileIds": ["default"]
       },
       "credentials": {
         "local": {
-          "username": "john.doe",
+          "username": "jane.doe",
           "password": "password"
         }
       }
-    }' "kuzzle:7512/users/john.doe/_create?refresh=wait_for"
+    }' "kuzzle:7512/users/jane.doe/_create?refresh=wait_for"
     &&
     curl -XPOST -H "Content-type: application/json" -d '{
       "description": "Sigfox API key"
-    }' "kuzzle:7512/users/john.doe/api-keys/_create?_id=fQRa28BsidO6V_wmOcL&refresh=wait_for"
+    }' "kuzzle:7512/users/jane.doe/api-keys/_create?_id=fQRa28BsidO6V_wmOcL&refresh=wait_for"
   after:
-    curl -XDELETE kuzzle:7512/users/john.doe
+    curl -XDELETE kuzzle:7512/users/jane.doe
 template: default
 expected:
   - API key successfully deleted
diff --git a/doc/7/controllers/auth/search-api-keys/snippets/search-api-keys.js b/doc/7/controllers/auth/search-api-keys/snippets/search-api-keys.js
@@ -1,22 +1,22 @@
 try {
   const promises = [];
 
-  // Create some API keys for user "john.doe"
+  // Create some API keys for user "jared.doe"
   promises.push(
-    kuzzle.security.createApiKey('john.doe', 'Sigfox API key'));
+    kuzzle.security.createApiKey('jared.doe', 'Sigfox API key'));
   promises.push(
-    kuzzle.security.createApiKey('john.doe', 'LoRa 6 month API key', {
+    kuzzle.security.createApiKey('jared.doe', 'LoRa 6 month API key', {
       expiresIn: '6m'
     }));
   promises.push(
-    kuzzle.security.createApiKey('john.doe', 'LoRa permanent API key', {
+    kuzzle.security.createApiKey('jared.doe', 'LoRa permanent API key', {
       refresh: 'wait_for'
     }));
 
   await Promise.all(promises);
 
-  // Log as "john.doe"
-  await kuzzle.auth.login('local', { username: 'john.doe', password: 'password' });
+  // Log as "jared.doe"
+  await kuzzle.auth.login('local', { username: 'jared.doe', password: 'password' });
 
   const results = await kuzzle.auth.searchApiKeys({
     match: {
@@ -33,7 +33,7 @@ try {
         "_id": "znEwbG8BJASM_0-bWU-q",
         "_source": {
           "description": "LoRa permanent API key",
-          "userId": "john.doe",
+          "userId": "jared.doe",
           "expiresAt": -1,
           "ttl": -1
         }
@@ -42,7 +42,7 @@ try {
         "_id": "zXEwbG8BJASM_0-bWU-q",
         "_source": {
           "description": "LoRa 1 year API key",
-          "userId": "john.doe",
+          "userId": "jared.doe",
           "expiresAt": 31557600000,
           "ttl": 360000
         }

diff --git a/doc/7/controllers/auth/search-api-keys/snippets/search-api-keys.test.yml b/doc/7/controllers/auth/search-api-keys/snippets/search-api-keys.test.yml
@@ -2,19 +2,19 @@ name: auth#searchApiKeys
 description: Searches API keys for the currently loggued user.
 hooks:
   before: >
-    curl -H "Content-type: application/json" -d '{
+    curl --fail -H "Content-type: application/json" -d '{
       "content": {
         "profileIds": ["default"]
       },
       "credentials": {
         "local": {
-          "username": "john.doe",
+          "username": "jared.doe",
           "password": "password"
         }
       }
-    }' "kuzzle:7512/users/john.doe/_create?refresh=wait_for"
+    }' "kuzzle:7512/users/jared.doe/_create?refresh=wait_for"
   after:
-    curl -XDELETE kuzzle:7512/users/john.doe
+    curl -XDELETE kuzzle:7512/users/jared.doe
 template: default
 expected:
   - Found 2 API keys matching "LoRa"
diff --git a/doc/7/controllers/bulk/delete-by-query/snippets/delete-by-query.test.yml b/doc/7/controllers/bulk/delete-by-query/snippets/delete-by-query.test.yml
@@ -7,11 +7,11 @@ hooks:
     curl -XPUT kuzzle:7512/nyc-open-data/yellow-taxi
 
     for i in  1 2 3 4 5; do
-      curl -H "Content-type: application/json" -d '{"capacity": 4}' kuzzle:7512/nyc-open-data/yellow-taxi/_create
+      curl --fail -H "Content-type: application/json" -d '{"capacity": 4}' kuzzle:7512/nyc-open-data/yellow-taxi/_create
     done
 
     for i in  1 2 3 4 5; do
-      curl -H "Content-type: application/json" -d '{"capacity": 7}' kuzzle:7512/nyc-open-data/yellow-taxi/_create
+      curl --fail -H "Content-type: application/json" -d '{"capacity": 7}' kuzzle:7512/nyc-open-data/yellow-taxi/_create
     done
 
     curl -XPOST kuzzle:7512/nyc-open-data/yellow-taxi/_refresh

diff --git a/doc/7/controllers/collection/create/index.md b/doc/7/controllers/collection/create/index.md
@@ -7,17 +7,22 @@ description: Create a new collection
 
 # create
 
-Creates a new [collection](/core/2/guides/essentials/store-access-data) in Kuzzle via the persistence engine, in the provided index.
+Creates a new [collection](/core/2/guides/essentials/store-access-data) in the provided index.
 
 You can also provide an optional data mapping that allow you to exploit the full capabilities of our
-persistent data storage layer, [ElasticSearch](https://www.elastic.co/elastic-stack) (check here the [mapping capabilities of ElasticSearch](https://www.elastic.co/guide/en/elasticsearch/reference/7.3/mapping.html)).
+persistent data storage layer, [ElasticSearch](https://www.elastic.co/elastic-stack) (check here the [mapping capabilities of ElasticSearch](/core/2/guides/essentials/database-mappings/)).
 
 This method will only update the mapping if the collection already exists.
 
+<SinceBadge version="Kuzzle 2.2.0" />
+<SinceBadge version="7.4.0" />
+
+You can also provide Elasticsearch [index settings](https://www.elastic.co/guide/en/elasticsearch/reference/7.5/index-modules.html#index-modules-settings) when creating a new collection.
+
 <br/>
 
 ```js
-create(index, collection, [mapping], [options]);
+create(index, collection, [definition], [options]);
 ```
 
 <br/>
@@ -26,17 +31,48 @@ create(index, collection, [mapping], [options]);
 | ------------ | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `index`      | <pre>string</pre> | Index name                                                                                                                                                                    |
 | `collection` | <pre>string</pre> | Collection name                                                                                                                                                               |
-| `mapping`    | <pre>object</pre> | Describes the data mapping to associate to the new collection, using Elasticsearch [mapping format](https://www.elastic.co/guide/en/elasticsearch/reference/7.3/mapping.html) |
+| `definition`    | <pre>object</pre> | Describes the collection mappings and the ES index settings |
 | `options`    | <pre>object</pre> | Query options                                                                                                                                                                 |
+<SinceBadge version="7.4.0">
 
-### mapping
-
-An object representing the data mapping of the collection.
+### definition
 
+An object containings:
+ - [collection mappings](/core/2/guides/essentials/database-mappings).
+ - Elasticsearch [index settings](https://www.elastic.co/guide/en/elasticsearch/reference/7.5/index-modules.html#index-modules-settings)
 The mapping must have a root field `properties` that contain the mapping definition:
 
 ```js
-const mapping = {
+const definition = {
+  mappings: {
+    properties: {
+      field1: { type: 'text' },
+      field2: {
+        properties: {
+          nestedField: { type: 'keyword' }
+        }
+      }
+    }    
+  },
+  settings: {
+
+  }
+};
+```
+
+</SinceBadge>
+
+
+<DeprecatedBadge version="7.4.0">
+
+### definition
+
+An object representing the data mappings of the collection.
+
+The mappings must have a root field `properties` that contain the mappings properties definition:
+
+```js
+const mappings = {
   properties: {
     field1: { type: 'text' },
     field2: {
@@ -50,6 +86,8 @@ const mapping = {
 
 More informations about database mappings [here](/core/2/guides/essentials/database-mappings).
 
+</DeprecatedBadge>
+
 ### options
 
 Additional query options

diff --git a/doc/7/controllers/collection/create/snippets/create.js b/doc/7/controllers/collection/create/snippets/create.js
@@ -1,4 +1,4 @@
-const mapping = {
+const mappings = {
   properties: {
     license: { type: 'keyword' },
     driver: {
@@ -11,7 +11,7 @@ const mapping = {
 };
 
 try {
-  await kuzzle.collection.create('nyc-open-data', 'yellow-taxi', mapping);
+  await kuzzle.collection.create('nyc-open-data', 'yellow-taxi', { mappings });
 
   console.log('Success');
 } catch (error) {

diff --git a/doc/7/controllers/collection/delete/index.md b/doc/7/controllers/collection/delete/index.md
@@ -0,0 +1,32 @@
+---
+code: true
+type: page
+title: delete
+description: Deletes a collection
+---
+
+# delete
+
+Deletes a collection.
+
+<br/>
+
+```js
+delete(index, collection);
+```
+
+<br/>
+
+| Arguments    | Type              | Description     |
+| ------------ | ----------------- | --------------- |
+| `index`      | <pre>string</pre> | Index name      |
+| `collection` | <pre>string</pre> | Collection name |
+
+
+## Resolves
+
+Resolves if the collection is successfully deleted.
+
+## Usage
+
+<<< ./snippets/delete-specifications.js
diff --git a/doc/7/controllers/collection/delete/snippets/delete-specifications.js b/doc/7/controllers/collection/delete/snippets/delete-specifications.js
@@ -0,0 +1,7 @@
+try {
+  await kuzzle.collection.delete('nyc-open-data', 'yellow-taxi');
+
+  console.log('Success');
+} catch (error) {
+  console.error(error.message);
+}
diff --git a/doc/7/controllers/collection/delete/snippets/delete-specifications.test.yml b/doc/7/controllers/collection/delete/snippets/delete-specifications.test.yml
@@ -0,0 +1,7 @@
+name: collection#delete
+description: Delete a collection
+hooks:
+  before: curl -X POST kuzzle:7512/nyc-open-data/_create && curl -X PUT kuzzle:7512/nyc-open-data/yellow-taxi
+  after:
+template: default
+expected: Success
diff --git a/doc/7/controllers/collection/exists/index.md b/doc/7/controllers/collection/exists/index.md
@@ -7,7 +7,7 @@ description: Check if collection exists
 
 # exists
 
-Check if a collection exists in Kuzzle.
+Checks if a collection exists in Kuzzle.
 
 <br/>
 

diff --git a/doc/7/controllers/collection/get-mapping/index.md b/doc/7/controllers/collection/get-mapping/index.md
@@ -30,6 +30,7 @@ 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 |
+| `includeKuzzleMeta` | <pre>boolean</pre><br/>(`true`) | If true, the returned mappings will contain [Kuzzle metadata](/core/2/guides/essentials/document-metadata/) |
 
 ## Resolves
 

diff --git a/doc/7/controllers/collection/refresh/index.md b/doc/7/controllers/collection/refresh/index.md
@@ -7,7 +7,7 @@ description: Forces an Elasticsearch search index update
 
 # refresh
 
-When writing or deleting documents in Kuzzle, the update needs to be indexed before being available in search results.
+Refreshes a collection to reindex the written and deleted documents so they are available in search results.  
 
 :::info
 A refresh operation comes with some performance costs.