remove autoconnection from sdk code examples

src/guide/essentials/user-authentication.md

@@ -18,33 +18,27 @@ If you have no users in your Kuzzle Backend yet, you can read the documentation
 Create a `login.js` file, NPM-install the Kuzzle SDK and start coding:
 
 ```javascript
-var Kuzzle = require('kuzzle-sdk')
-
-var kuzzle = new Kuzzle('localhost', () => {
-  kuzzle
-    .loginPromise('local', {
-      username: 'admin',
-      password: 'test'
-    })
-    .then(() => {
-      console.log('logged!')
-    })
-    .catch(err => {
-      console.error(err.message)
-    })
-})
-
+const Kuzzle = require('kuzzle-sdk')
+
+const kuzzle = new Kuzzle('localhost')
+
+kuzzle
+  .connectPromise()
+  .then(() => loginPromise('local', {username: '<username>', password: '<password>'})
+  .then(() => {
+    console.log('logged!')
+  })
+  .catch(err => {
+    console.error(err.message)
+  })
 ```
 
-Assuming that you have an `admin` user with `test` password in your Kuzzle Backoffice, the code above does the following:
-* loads the `Kuzzle` SDK from it NPM package,
-* instantiates the SDK by connecting it to the Kuzzle Backoffice running on `localhost`,
-* _after the SDK connected to Kuzzle Backend_, it performs a login for the `admin` user,
-* displays to console a success message or an error message whether the login has succeeded or failed.
+The code above does the following:
 
-<aside class="notice">
-  It's very important that the `login` code executes after the SDK has successfully connected to the backend, since `login` is not a queuable method (queuable methods can be called before the SDK is connected to the backend and are automatically played once the connection is established). That's why we put all the `login` code in the constructor's callback.
-</aside>
+* loads the `Kuzzle` SDK from the NPM package,
+* instantiates a new SDK object
+* connects it to a remote Kuzzle server
+* performs a login with the provided username and password
 
 ---
 

src/guide/getting-started/index.md

@@ -103,26 +103,26 @@ Then, create a `init.js` file and start coding:
 ```javascript
 const Kuzzle = require('kuzzle-sdk')
 
-// connect to the Kuzzle server
+// create a new kuzzle object
 const kuzzle = new Kuzzle('localhost', {defaultIndex: 'playground'})
 
-kuzzle.once('connected', () => {
-  kuzzle
-    .createIndexPromise('playground')
-    .then(() => kuzzle.collection('mycollection').createPromise())
-    .then(() => {
-      console.log('playground/mycollection ready')
-    })
-    .catch(err => {
-      console.error(err.message)
-    })
-    .finally(() => kuzzle.disconnect())
-})
+kuzzle
+  .connectPromise()
+  .then(() => kuzzle.createIndexPromise('playground'))
+  .then(() => kuzzle.collection('mycollection').createPromise())
+  .then(() => {
+    console.log('playground/mycollection ready')
+  })
+  .catch(err => {
+    console.error(err.message)
+  })
+  .finally(() => kuzzle.disconnect())
 ```
 
 This code does the following:
 * loads the `Kuzzle` SDK from its NPM package,
-* creates an instance of the SDK and connects it to the Kuzzle Backoffice running on `localhost` (and selects the `playground` as default index),
+* creates an instance of the SDK,
+* connects the SDK to a remote Kuzzle server running on `localhost` (and selects the `playground` as default index),
 * creates the `playground` index,
 * creates the `mycollection` collection (within the `playground` index),
 * disconnect from Kuzzle to end the script.
@@ -144,23 +144,22 @@ Create a `create.js` file with following code:
 ```javascript
 const Kuzzle = require('kuzzle-sdk')
 
-// connect to the Kuzzle server
+// create a new Kuzzle SDK object
 const kuzzle = new Kuzzle('localhost', {defaultIndex: 'playground'})
 
 // get message from command line arguments
 const message = {message: process.argv[2]}
 
-kuzzle.once('connected', () => {
-  kuzzle.collection('mycollection')
-    .createDocumentPromise(message)
-    .then(res => {
-      console.log('the following document has been successfully created:\n', message)
-    })
-    .catch(err => {
-      console.error(err.message)
-    })
-    .finally(() => kuzzle.disconnect())
-})
+kuzzle
+  .connectPromise()
+  .then(() => kuzzle.collection('mycollection').createDocumentPromise(message))
+  .then(res => {
+    console.log('the following document has been successfully created:\n', message)
+  })
+  .catch(err => {
+    console.error(err.message)
+  })
+  .finally(() => kuzzle.disconnect())
 ```
 
 This code does the following:
@@ -197,7 +196,7 @@ Open a new termnial in the playground directory you created before and create th
 ```javascript
 const Kuzzle = require('kuzzle-sdk')
 
-// connect to the Kuzzle server
+// create a new kuzzle object
 const kuzzle = new Kuzzle('localhost', {defaultIndex: 'playground'})
 
 // create a reference to the data collection
@@ -211,10 +210,16 @@ const filter = {
 }
 
 // create a subscription on the collection matching given filters
-collection.subscribe(filter, result => {
+collection
+  .subscribe(filter, result => {
     // this function is called each time kuzzle notifies us with a document matching our filters
-    console.log('message received from kuzzle:', result)
-})
+    console.log('Message received from kuzzle:', result)
+  })
+  .onDone(() => console.log('Subscription active. Waiting for messages...'))
+
+// Connects the client to a remote Kuzzle server and plays the previously
+// configured subscriptions
+kuzzle.connect()
 ```
 
 Run your file in NodeJS

src/sdk-reference/essentials/offline-first.md

@@ -15,7 +15,7 @@ Our goal is to provide our users with the right tools to handle such situations.
 
 There are two ways to handle a network disconnection:
 
-* Stop all further communication with Kuzzle and invalidate the current instance and all its children. The application will have to manually instantiate a new Kuzzle object once the network has recovered. To do so, simply pass the ``autoReconnect`` option to ``false`` when starting a new Kuzzle instance.
+* Stop all further communication with Kuzzle and invalidate the current instance and all its children. The application will have to manually reconnect once the network has recovered. To do so, simply pass the ``autoReconnect`` option to ``false`` when starting a new Kuzzle instance.
 * Reconnect automatically to Kuzzle when possible, and enter *offline mode* in the meantime. This is the default behavior.
 
 Offline mode simply refers to the time between a ``disconnected`` and a ``reconnected`` event (see [Events]({{ site_base_path }}sdk-reference/essentials/events)).
@@ -46,7 +46,7 @@ The queue itself can be configured using the ``queueTTL`` and ``queueMaxSize`` o
 
 ---
 
-## Filtering requests to be queued
+## Filter requests to be queued
 
 After request queuing is activated, by default, all requests are queued.
 

src/sdk-reference/kuzzle/connect.md

@@ -11,11 +11,32 @@ title: connect
 # connect
 
 ```js
-kuzzle.connect();
+// Using callbacks (NodeJS or Web Browser)
+kuzzle.connect(function (err, kuzzle) {
+  if (err) {
+    console.log('Unable to connect: ', err.message);
+  } else {
+    console.log('Connected!');
+  }
+});
+
+// Using promises (NodeJS only)
+kuzzle.connectPromise()
+  .then(() => console.log('Connected!'));
 ```
 
 ```java
-kuzzle.connect();
+kuzzle.connect(new ResponseListener<Void>() {
+ @Override
+ public void onSuccess(Void object) {
+   // invoked once connected
+ }
+
+ @Override
+ public void onError(JSONObject error) {
+   // Handle connection error
+ }
+});
 ```
 
 ```php
@@ -24,17 +45,10 @@ kuzzle.connect();
 // not implemented (this SDK uses HTTP and is thus stateless)
 ```
 
-Connects to the Kuzzle instance using the provided `host` in the constructor.
-Has no effect if ``connect`` is set to ``auto``, unless ``disconnect`` has been called first.
-
----
-
-## Return value
-
-Returns the `Kuzzle` object to allow chaining.
+Connects to the Kuzzle instance using the `host` and `port` parameters provided to the constructor.
 
 ---
 
 ## Callback response
 
-If a callback has been provided to the `Kuzzle` constructor, it will be called with the `Kuzzle` instance once successfully connected
+Resolves with nothing once connected to a remote Kuzzle server.

src/sdk-reference/kuzzle/index.md

@@ -20,11 +20,6 @@ var kuzzle = new Kuzzle('localhost', {
   autoReconnect: true,
   port: 7512
 });
-
-// A callback is also available and will be invoked once connected to the Kuzzle instance:
-kuzzle = new Kuzzle('localhost', function (err, res) {
-  // ...
-});
 ```
 
 ```java
@@ -37,17 +32,7 @@ options.setDefaultIndex("some index")
   .setAutoReconnect(true),
   .setPort(7512);
 
-Kuzzle kuzzle = new Kuzzle("localhost", options, new ResponseListener<Void>() {
- @Override
- public void onSuccess(Void object) {
-   // invoked once connected, object contains the kuzzle instance
- }
-
- @Override
- public void onError(JSONObject error) {
-   // Handle connection error
- }
-});
+Kuzzle kuzzle = new Kuzzle("localhost", options);
 ```
 
 ```php
@@ -66,13 +51,12 @@ This is the main entry point to communicate with Kuzzle. Every other objects inh
 
 ---
 
-## Kuzzle(host, [options], [callback])
+## Kuzzle(host, [options])
 
 | Arguments | Type | Description |
 |---------------|---------|----------------------------------------|
 | ``host`` | string | The server name (or the IP address) of a Kuzzle instance |
 | ``options`` | JSON object | Optional Kuzzle connection configuration |
-| ``callback`` | function | Optional callback |
 
 ---
 
@@ -84,7 +68,6 @@ This is the main entry point to communicate with Kuzzle. Every other objects inh
 | ``autoReconnect`` | boolean | Automatically reconnect after a connection loss | ``true`` |
 | ``autoReplay`` | boolean | Automatically replay queued requests on a ``reconnected`` event | ``false`` |
 | ``autoResubscribe`` | boolean | Automatically renew all subscriptions on a ``reconnected`` event | ``true`` |
-| ``connect`` | string | Manually or automatically connect to the Kuzzle instance | ``auto`` |
 | ``defaultIndex`` | string | Set the default index to use | |
 | ``offlineMode`` | string | Offline mode configuration | ``manual`` |
 | ``protocol`` | string | (Javascript only) Network protocol to use to connect to Kuzzle (``websocket`` | ``socketio``) | ``websocket``|
@@ -126,18 +109,10 @@ This is the main entry point to communicate with Kuzzle. Every other objects inh
 
 **Notes:**
 
-* if ``connect`` is set to ``manual``, the ``connect`` method will have to be called manually
-* the kuzzle instance will automatically queue all requests, and play them automatically once a first connection is established, regardless of the ``connect`` or offline mode option values.
+* newly instantiated Kuzzle objects automatically start in [offline mode]({{ site_base_path }}sdk-reference/essentials/offline-first/)
 * multiple methods allow passing specific ``volatile`` data. These ``volatile`` data will be merged with the global Kuzzle object ``volatile`` when sending the request, with the request specific ``volatile`` taking priority over the global ones.
 * the ``queueFilter`` property is a function taking a JSON object as an argument. This object is the request sent to Kuzzle, following the [Kuzzle API]({{ site_base_path }}api-documentation/query-syntax) format
 * if ``queueTTL`` is set to ``0``, requests are kept indefinitely
 * The offline buffer acts like a FIFO queue, meaning that if the ``queueMaxSize`` limit is reached, older requests are discarded to make room for new requests
 * if ``queueMaxSize`` is set to ``0``, an unlimited number of requests is kept until the buffer is flushed
 * the ``offlineQueueLoader`` must be set with a function, taking no argument, and returning an array of objects containing a `query` member with a Kuzzle query to be replayed, and an optional `cb` member with the corresponding callback to invoke with the query result
-
----
-
-## Callback response
-
-If the connection succeeds, resolves to the `Kuzzle` object itself.
-If the `connect` option is set to `manual`, the callback will be called after the `connect` method is resolved.