diff --git a/README.md b/README.md index 111d9c816..9ecb0d43f 100644 --- a/README.md +++ b/README.md @@ -31,13 +31,13 @@ Example: ```js const { Kuzzle, - Websocket, + WebSocket, Http, SocketIO } = require('kuzzle-sdk'); const kuzzle = new Kuzzle( - new Websocket({ host: 'localhost', port: 7512 }) + new WebSocket('localhost', { port: 7512 }) ); try { @@ -56,22 +56,31 @@ This SDK can be used either in NodeJS or in a browser. ### NodeJS ``` -npm install kuzzle-sdk --save # Beta v6 -npm install git://github.com/kuzzleio/sdk-javascript.git#6-beta --save +npm install git://github.com/kuzzleio/sdk-javascript.git#6-beta ``` ### Browser -To run the SDK in the browser, you need to pick the [built beta v6 version available here](https://raw.githubusercontent.com/kuzzleio/sdk-javascript/tree/6-beta/dist/kuzzle.js). You can also build it yourself by cloning this repository and running `npm run build`. A `dist` directory will be created, containing a browser version of this SDK. +To run the SDK in the browser, you have to build it yourself by cloning this repository and running `npm run build`. A `dist` directory will be created, containing a browser version of this SDK. ```html ``` -The browser version is also available from CDN: + +Then the Kuzzle SDK will be available under the `KuzzleSDK` variable: ```html - + + ``` If you want to support older browser versions, you may load `socket.io` before Kuzzle, making the SDK compatible with browsers without websocket support: @@ -98,27 +107,27 @@ const { Kuzzle } = require('kuzzle-sdk/dist/kuzzle.js') import { Kuzzle } from 'kuzzle-sdk/dist/kuzzle.js' ``` -## Protocols used -Currently, the SDK support 3 protocols: `Http`, `Websocket` and `SocketIO`. +## Available protocols + Currently, the SDK provides 3 protocols: `Http`, `WebSocket` and `SocketIO`. WebSocket and Socket.IO protocols implement the whole Kuzzle API, while the **HTTP protocol does not implement realtime features** (rooms and subscriptions). While Socket.IO offers better compatibility with older web browsers, our raw WebSocket implementation is about 20% faster. #### NodeJS -We recommend to use the `websocket` protocol, but you can still use `http`, `socketio` or even a custom protocol if you want. +We recommend using the `WebSocket` protocol, but you can still use `Http`, `SocketIO` or even a custom protocol if you want. #### Web Browsers -We also recommend to use the `webSocket` or `http` protocol, but some old browser may not support Websocket, so you have to implement a fallback to `socketio` in that case. +We also recommend to use the `WebSocket` or `Http` protocol, but some old browser may not support WebSocket, so you have to implement a fallback to `SocketIO` in that case. ```js let kuzzle; if ('WebSocket' in window && window.WebSocket.CLOSING === 2) { - kuzzle = new Kuzzle(new Websocket({ host: 'localhost' })); + kuzzle = new Kuzzle(new WebSocket('localhost')); } else { - kuzzle = new Kuzzle(new SocketIO({ host: 'localhost' })); + kuzzle = new Kuzzle(new SocketIO('localhost')); } ``` @@ -182,7 +191,7 @@ const kuzzle = new Kuzzle(protocol); ### Connection to Kuzzle -By default, the SDK is not connected to Kuzzle when it is instantiated. You must manually call the `kuzzle.connect()` method before using the SDK. +By default, the SDK is not connected to Kuzzle when it is instantiated. You must manually call the [kuzzle:connect](https://docs-v2.kuzzle.io/sdk-reference/js/6/kuzzle/connect/) method before using the SDK. It is then possible to interact with the Kuzzle API through the SDK once the Promise returned by `kuzzle.connect()` has been resolved. @@ -209,15 +218,15 @@ try { ### Match Kuzzle's API -The version 6 of this SDK involve a massive refactor of the SDK structure to match the [Kuzzle API](https://docs.kuzzle.io/api-documentation/connecting-to-kuzzle/). +The version 6 of this SDK involve a massive refactor of the SDK structure to match the [Kuzzle API](https://docs-v2.kuzzle.io/api/1/essentials/connecting-to-kuzzle/). Each controller is accessible from the Kuzzle object. The controller's actions are named in the same way as in the API. -For example, for the `create` action of the `document` controller ([document#create](https://docs.kuzzle.io/api-documentation/controller-document/create)): +For example, for the `create` action of the `document` controller ([document:create](https://docs-v2.kuzzle.io/api/1/controller-document/create)): ```js const options = { refresh: 'wait_for' }; -const documentBody = { hello: 'world' }; -kuzzle.document.create('my-index', 'my-collection', documentBody, 'my-uniq-id', options) +const document = { hello: 'world' }; +kuzzle.document.create('my-index', 'my-collection', document, 'my-uniq-id', options) ``` The parameters of each method differ according to the parameters expected in the API. @@ -229,7 +238,7 @@ This SDK also expose a low level `query` method to access the API even if the co This method take the controller and action name with all parameters needed by the action (`body`, `_id`, etc.) and return the raw Kuzzle response. This is the method used internally for every controller action in this SDK. -Example with the [Admin](https://docs.kuzzle.io/api-documentation/controller-admin/) controller: +Example with the [Admin](https://docs-v2.kuzzle.io/api/1/controller-admin/reset-cache) controller: ```js const query = { controller: 'admin', @@ -268,7 +277,7 @@ try { All SDK methods return a promise resolving the `result` part of Kuzzle API responses. If an error occurs, the promise is rejected with an `Error` object embedding the `error` part of the API response. -For example, for the action `create` of the controller `collection` ([collection#create](https://docs.kuzzle.io/api-documentation/controller-collection/create)), the property `result` contains `{ "acknowledged": true} `. This is therefore what will be returned by the SDK method if successful. +For example, for the action `create` of the controller `collection` ([collection:create](https://docs-v2.kuzzle.io/api/1/controller-collection/create)), the property `result` contains `{ "acknowledged": true} `. This is therefore what will be returned by the SDK method if successful. Any error must be caught either at the end of the Promise chain, or by using `async/await` and a `try...catch`. diff --git a/features/support/world.js b/features/support/world.js index 768ca3846..665ad77c7 100644 --- a/features/support/world.js +++ b/features/support/world.js @@ -2,12 +2,12 @@ const { setWorldConstructor } = require('cucumber'), { Kuzzle, - Websocket + WebSocket } = require('../../index'); class World { constructor () { - this.kuzzle = new Kuzzle(new Websocket({ host: 'localhost', port: 7512 })); + this.kuzzle = new Kuzzle(new WebSocket('localhost', { port: 7512 })); this.index = null; this.collection = null; diff --git a/index.js b/index.js index 8b8cba28c..55c3aa6b6 100644 --- a/index.js +++ b/index.js @@ -2,7 +2,7 @@ const Kuzzle = require('./src/Kuzzle'), { Http, - Websocket, + WebSocket, SocketIO } = require('./src/protocols'), KuzzleAbstractProtocol = require('./src/protocols/abstract/common'), @@ -18,7 +18,7 @@ if (typeof window !== 'undefined' && typeof BUILT === 'undefined') { module.exports = { Kuzzle, Http, - Websocket, + WebSocket, SocketIO, KuzzleAbstractProtocol, KuzzleEventEmitter diff --git a/src/protocols/abstract/common.js b/src/protocols/abstract/common.js index 3e3a7fc53..1dfb939c9 100644 --- a/src/protocols/abstract/common.js +++ b/src/protocols/abstract/common.js @@ -12,10 +12,10 @@ let class AbstractWrapper extends KuzzleEventEmitter { - constructor (options = {}) { + constructor (host, options = {}) { super(); - _host = options.host; + _host = host; _port = typeof options.port === 'number' ? options.port : 7512; _ssl = typeof options.sslConnection === 'boolean' ? options.sslConnection : false; diff --git a/src/protocols/abstract/realtime.js b/src/protocols/abstract/realtime.js index 13627615b..0bc9098f6 100644 --- a/src/protocols/abstract/realtime.js +++ b/src/protocols/abstract/realtime.js @@ -5,8 +5,8 @@ const class RTWrapper extends KuzzleAbstractProtocol { - constructor (options = {}) { - super(options); + constructor (host, options = {}) { + super(host, options); this._autoReconnect = typeof options.autoReconnect === 'boolean' ? options.autoReconnect : true; this._reconnectionDelay = typeof options.reconnectionDelay === 'number' ? options.reconnectionDelay : 1000; diff --git a/src/protocols/http.js b/src/protocols/http.js index cc0af260b..4a0897dce 100644 --- a/src/protocols/http.js +++ b/src/protocols/http.js @@ -44,11 +44,11 @@ const class HttpWrapper extends KuzzleAbstractProtocol { - constructor(options = {}) { - super(options); + constructor(host, options = {}) { + super(host, options); - if (typeof this.host !== 'string' || this.host === '') { - throw new Error('options.host is required'); + if (typeof host !== 'string' || host === '') { + throw new Error('host is required'); } // Application-side HTTP route overrides: diff --git a/src/protocols/index.js b/src/protocols/index.js index 07d02dd35..696a90ca5 100644 --- a/src/protocols/index.js +++ b/src/protocols/index.js @@ -2,11 +2,11 @@ const Http = require('./http'), - Websocket = require('./websocket'), + WebSocket = require('./websocket'), SocketIO = require('./socketio'); module.exports = { Http, - Websocket, + WebSocket, SocketIO }; diff --git a/src/protocols/socketio.js b/src/protocols/socketio.js index de02fef55..ada6bd0f5 100644 --- a/src/protocols/socketio.js +++ b/src/protocols/socketio.js @@ -5,11 +5,11 @@ const class SocketIO extends RTWrapper { - constructor(options = {}) { - super(options); + constructor(host, options = {}) { + super(host, options); - if (typeof this.host !== 'string' || this.host === '') { - throw new Error('options.host is required'); + if (typeof host !== 'string' || host === '') { + throw new Error('host is required'); } this.socket = null; diff --git a/src/protocols/websocket.js b/src/protocols/websocket.js index 0399ebe92..694247b77 100644 --- a/src/protocols/websocket.js +++ b/src/protocols/websocket.js @@ -7,11 +7,11 @@ let WebSocketClient; class WSNode extends RTWrapper { - constructor(options = {}) { - super(options); + constructor(host, options = {}) { + super(host, options); - if (typeof this.host !== 'string' || this.host === '') { - throw new Error('options.host is required'); + if (typeof host !== 'string' || host === '') { + throw new Error('host is required'); } WebSocketClient = typeof WebSocket !== 'undefined' ? WebSocket : require('uws'); diff --git a/test/kuzzle/connect.test.js b/test/kuzzle/connect.test.js index 26a665af6..fb0f018f9 100644 --- a/test/kuzzle/connect.test.js +++ b/test/kuzzle/connect.test.js @@ -7,9 +7,9 @@ const describe('Kuzzle connect', () => { const protocols = { - somewhere: new ProtocolMock({host: 'somewhere'}), - somewhereagain: new ProtocolMock({host: 'somewhereagain'}), - nowhere: new ProtocolMock({host: 'nowhere'}) + somewhere: new ProtocolMock('somewhere'), + somewhereagain: new ProtocolMock('somewhereagain'), + nowhere: new ProtocolMock('nowhere') }; it('should return immediately if already connected', () => { diff --git a/test/kuzzle/constructor.test.js b/test/kuzzle/constructor.test.js index 5b2cdaba1..6dd7087c8 100644 --- a/test/kuzzle/constructor.test.js +++ b/test/kuzzle/constructor.test.js @@ -14,7 +14,7 @@ const ProtocolMock = require('../mocks/protocol.mock'); describe('Kuzzle constructor', () => { - const protocolMock = new ProtocolMock({host: 'somewhere'}); + const protocolMock = new ProtocolMock('somewhere'); it('should throw an error if no protocol wrapper is provided', () => { should(function () { diff --git a/test/kuzzle/getters.test.js b/test/kuzzle/getters.test.js index 1e1937748..b40c84591 100644 --- a/test/kuzzle/getters.test.js +++ b/test/kuzzle/getters.test.js @@ -7,7 +7,7 @@ describe('Kuzzle getters', () => { let kuzzle; beforeEach(() => { - const protocol = new ProtocolMock({host: 'somewhere'}); + const protocol = new ProtocolMock('somewhere'); kuzzle = new Kuzzle(protocol); }); diff --git a/test/kuzzle/protocol.test.js b/test/kuzzle/protocol.test.js index 4925d2de0..8dfab5ee4 100644 --- a/test/kuzzle/protocol.test.js +++ b/test/kuzzle/protocol.test.js @@ -8,7 +8,7 @@ describe('Kuzzle protocol methods', () => { let kuzzle; beforeEach(() => { - const protocol = new ProtocolMock({host: 'somewhere'}); + const protocol = new ProtocolMock('somewhere'); protocol.close = sinon.stub(); kuzzle = new Kuzzle(protocol); diff --git a/test/kuzzle/query.test.js b/test/kuzzle/query.test.js index 5902f0e5b..27f611cdd 100644 --- a/test/kuzzle/query.test.js +++ b/test/kuzzle/query.test.js @@ -21,7 +21,7 @@ describe('Kuzzle query management', () => { let kuzzle; beforeEach(() => { - const protocol = new ProtocolMock({host: 'somewhere'}); + const protocol = new ProtocolMock('somewhere'); kuzzle = new Kuzzle(protocol); kuzzle.protocol.query.resolves(response); diff --git a/test/kuzzle/queue.test.js b/test/kuzzle/queue.test.js index f850bbbb1..34b313282 100644 --- a/test/kuzzle/queue.test.js +++ b/test/kuzzle/queue.test.js @@ -8,7 +8,7 @@ describe('Kuzzle queue', () => { let kuzzle; beforeEach(() => { - const protocol = new ProtocolMock({host: 'somewhere'}); + const protocol = new ProtocolMock('somewhere'); kuzzle = new Kuzzle(protocol); }); diff --git a/test/kuzzle/setters.test.js b/test/kuzzle/setters.test.js index 6457a8642..070d56562 100644 --- a/test/kuzzle/setters.test.js +++ b/test/kuzzle/setters.test.js @@ -8,7 +8,7 @@ describe('Kuzzle setters', () => { let kuzzle; beforeEach(() => { - const protocol = new ProtocolMock({host: 'somewhere'}); + const protocol = new ProtocolMock('somewhere'); kuzzle = new Kuzzle(protocol); }); diff --git a/test/mocks/protocol.mock.js b/test/mocks/protocol.mock.js index 8ecf04414..16616a8f7 100644 --- a/test/mocks/protocol.mock.js +++ b/test/mocks/protocol.mock.js @@ -4,11 +4,11 @@ const class ProtocolMock extends KuzzleEventEmitter { - constructor (options = {}) { + constructor (host, options = {}) { super(); this.options = options || {}; - this.host = this.options.host; + this.host = host; this.port = this.options.port || 7512; this.state = 'offline'; this.connectCalled = false; diff --git a/test/protocol/http.test.js b/test/protocol/http.test.js index c5888ac33..94f120451 100644 --- a/test/protocol/http.test.js +++ b/test/protocol/http.test.js @@ -8,8 +8,7 @@ describe('HTTP networking module', () => { let protocol; beforeEach(() => { - protocol = new HttpWrapper({ - host: 'address', + protocol = new HttpWrapper('address', { port: 1234 }); }); @@ -57,8 +56,7 @@ describe('HTTP networking module', () => { }); it('should initialize http protocol with custom routes', () => { - const customProtocol = new HttpWrapper({ - host: 'address', + const customProtocol = new HttpWrapper('address', { port: 1234, http: { customRoutes: { @@ -408,7 +406,7 @@ describe('HTTP networking module', () => { 'min-req-promise': {request: httpRequestStub} }); - protocol = new MockHttpWrapper({host: 'address', port: 1234}); + protocol = new MockHttpWrapper('address', { port: 1234 }); }); it('should call http.request with empty body', () => { @@ -475,8 +473,7 @@ describe('HTTP networking module', () => { return xhrStub; }; - protocol = new HttpWrapper({ - host: 'address', + protocol = new HttpWrapper('address', { port: 1234 }); }); diff --git a/test/protocol/socketio.test.js b/test/protocol/socketio.test.js index 91a165acb..33dceb257 100644 --- a/test/protocol/socketio.test.js +++ b/test/protocol/socketio.test.js @@ -67,8 +67,7 @@ describe('SocketIO networking module', () => { close: sinon.spy() }; - socketIO = new SocketIO({ - host: 'address', + socketIO = new SocketIO('address', { port: 1234, autoReconnect: false, reconnectionDelay: 1234 @@ -102,8 +101,7 @@ describe('SocketIO networking module', () => { }); it('should connect with the secure connection', () => { - socketIO = new SocketIO({ - host: 'address', + socketIO = new SocketIO('address', { port: 1234, autoReconnect: false, reconnectionDelay: 1234, @@ -225,7 +223,7 @@ describe('SocketIO exposed methods', () => { close: sinon.spy() }; - socketIO = new SocketIO({host: 'address'}); + socketIO = new SocketIO('address'); socketIO.socket = socketStub; window = {io: sinon.stub().returns(socketStub)}; // eslint-disable-line diff --git a/test/protocol/websocket.test.js b/test/protocol/websocket.test.js index da2f8a153..cd1f641a4 100644 --- a/test/protocol/websocket.test.js +++ b/test/protocol/websocket.test.js @@ -23,8 +23,7 @@ describe('WebSocket networking module', () => { return clientStub; }; - websocket = new WS({ - host: 'address', + websocket = new WS('address', { port: 1234, autoReconnect: true, reconnectionDelay: 10 @@ -58,8 +57,7 @@ describe('WebSocket networking module', () => { it('should initialize a WS secure connection', () => { clientStub.on = sinon.stub(); - websocket = new WS({ - host: 'address', + websocket = new WS('address', { port: 1234, autoReconnect: false, reconnectionDelay: 1234, @@ -135,8 +133,7 @@ describe('WebSocket networking module', () => { it('should not try to reconnect on a connection error with autoReconnect = false', () => { const cb = sinon.stub(); - websocket = new WS({ - host: 'address', + websocket = new WS('address', { port: 1234, autoReconnect: false, reconnectionDelay: 10