adowning-kuzzle-sdk
v6.0.0-beta-5
Published
Official Javascript SDK for Kuzzle
Downloads
2
Maintainers
Readme
Official Kuzzle Javascript SDK
About Kuzzle
A backend software, self-hostable and ready to use to power modern apps.
You can access the Kuzzle repository on Github
This is the documentation for the beta-6 SDK. We are currently refactoring in deep our documentation to support many versions of each SDK. You can see it here but notice that this is a beta version of the documentation.
This new documentation will be available soon. In the meantime, you can still use the SDK 5 and the old documentation at https://docs.kuzzle.io/sdk-reference/essentials/.
Basic usage
The SDK supports different protocols. When instantiating, you must choose the protocol to use and fill in the different options needed to connect to Kuzzle.
Example:
const {
Kuzzle,
WebSocket,
Http,
SocketIO
} = require('kuzzle-sdk');
const kuzzle = new Kuzzle(
new WebSocket('localhost', { port: 7512 })
);
try {
const serverTime = kuzzle.server.now();
console.log(serverTime);
} catch (error) {
console.error(error);
}
Installation
This SDK can be used either in NodeJS or in a browser.
NodeJS
# Beta v6
npm install git://github.com/kuzzleio/sdk-javascript.git#6-beta
Browser
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.
<script type="text/javascript" src="dist/kuzzle.js"></script>
Then the Kuzzle SDK will be available under the KuzzleSDK
variable:
<script src="dist/kuzzle.js"></script>
<script>
const kuzzle = new KuzzleSDK.Kuzzle(
new KuzzleSDK.WebSocket('localhost')
);
kuzzle.connect();
kuzzle.addListener('connected', () => {
console.log('Hello Kuzzle');
});
</script>
If you want to support older browser versions, you may load socket.io
before Kuzzle, making the SDK compatible with browsers without websocket support:
<!-- Don't forget to include socketio before Kuzzle SDK -->
<script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/socket.io/2.0.3/socket.io.slim.js"></script>
Browser with Webpack
If you use Webpack, you'll likely use the NPM-packaged version of the SDK (like in Node)
npm install kuzzle-sdk --save
But you'll still need to pick the built version (which ships with the package).
// with the classic require...
const { Kuzzle } = require('kuzzle-sdk/dist/kuzzle.js')
// ... or with the new import directive.
import { Kuzzle } from 'kuzzle-sdk/dist/kuzzle.js'
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 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.
let kuzzle;
if ('WebSocket' in window && window.WebSocket.CLOSING === 2) {
kuzzle = new Kuzzle(new WebSocket('localhost'));
} else {
kuzzle = new Kuzzle(new SocketIO('localhost'));
}
Custom protocol
The SDK also proposes to create custom protocols.
There are two ways to write these protocols, the first is to inherit the KuzzleAbstractProtocol
class provided with the SDK and implement only the connect
and send
methods.
const { KuzzleAbstractProtocol } = require('kuzzle-sdk');
class MyCustomProtocol extends KuzzleAbstractProtocol {
connect() {
// (...) do custom connection steps...
// change state and resolve:
this.state = 'ready';
return Promise.resolve();
}
send(request) {
// (...) here the protocol-specific code to send the request to kuzzle and get the result into `result` variable
// Send back the result to SDK and resolve:
this.emit(request.requestId, { result });
return Promise.resolve();
}
}
The second way is to implement the isReady
and query
methods as well as javascript Event API by inheriting the KuzzleEventEmitter
class.
const { KuzzleEventEmitter } = require('kuzzle-sdk');
class MyCustomProtocol extends KuzzleEventEmitter {
isReady() {
return true;
}
query (request, options) {
// (...) here the protocol-specific code to send the request to kuzzle and get the result into `result` variable
// Resolves the response:
return Promise.resolve({ result });
}
}
These customized protocols can then be used by the SDK by passing them as parameters at instantiation.
const protocol = new MyCustomProtocol();
const kuzzle = new Kuzzle(protocol);
SDK Documentation
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.
It is then possible to interact with the Kuzzle API through the SDK once the Promise returned by kuzzle.connect()
has been resolved.
// Without async/await
kuzzle.connect()
.then(() => {
// You are now connected to your Kuzzle instance.
return kuzzle.server.now();
})
.then(serverTime => console.log(serverTime))
.catch(error => console.error(error));
// With async/await
try {
await kuzzle.connect();
const serverTime = await kuzzle.server.now();
console.log(serverTime);
} catch (error) {
console.error(error);
}
Match Kuzzle's API
The version 6 of this SDK involve a massive refactor of the SDK structure to match the Kuzzle API.
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):
const options = { refresh: 'wait_for' };
const documentBody = { hello: 'world' };
kuzzle.document.create('my-index', 'my-collection', documentBody, 'my-uniq-id', options)
The parameters of each method differ according to the parameters expected in the API.
If you want to get the details of the parameters for each method, it is necessary for the moment to see the code of each controller on Github.
Query method
This SDK also expose a low level query
method to access the API even if the controller is not available inside the SDK.
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 controller:
const query = {
controller: 'admin',
action: 'resetCache',
database: 'memoryStorage'
};
const options = {
refresh: 'wait_for'
};
try {
const response = await kuzzle.query(query, options);
/*
{
requestId: '6526be09-330d-4183-be2b-8c30183db0f0',
status: 200,
error: null,
controller: 'admin',
action: 'resetCache',
collection: null,
index: null,
volatile:
{ sdkInstanceId: 'c6fbe345-1d8b-4324-bf1f-2be3cc1a7d27',
sdkVersion: '6.0.0' },
result: { acknowledge: true },
room: '6526be09-330d-4183-be2b-8c30183db0f0'
}
*/
console.log('Kuzzle memory storage successfully reset');
} catch (error) {
console.error(error);
}
Promise based
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), 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
.
const mapping = {
properties: {
hello: { type: 'text' }
}
};
// Without async/await
kuzzle.collection.create('my-index', 'my-collection', mapping)
.then(result => console.log('Success'))
.catch(error => console.error(`Hu oh, we've got some error: ${error.message}`));
// With async/await
try {
const result = await kuzzle.collection.create('my-index', 'my-collection', mapping);
// result contain { "acknowledged": true }
console.log(result);
} catch (error) {
console.error(`Hu oh, we've got some error: ${error.message}`)
}