1 | <p align="center">
|
2 | <img src="https://user-images.githubusercontent.com/7868838/53197334-3fdcdf00-361a-11e9-8ac4-85f164ee0561.png"/>
|
3 | </p>
|
4 | <p align="center">
|
5 | <a href="https://travis-ci.org/kuzzleio/sdk-javascript">
|
6 | <img src="https://travis-ci.org/kuzzleio/sdk-javascript.svg?branch=master"/>
|
7 | </a>
|
8 | <a href="https://codecov.io/gh/kuzzleio/sdk-javascript">
|
9 | <img src="https://codecov.io/gh/kuzzleio/sdk-javascript/branch/master/graph/badge.svg" />
|
10 | </a>
|
11 | <a href="https://david-dm.org/kuzzleio/sdk-javascript">
|
12 | <img src="https://david-dm.org/kuzzleio/sdk-javascript.svg" />
|
13 | </a>
|
14 | <a href="https://github.com/kuzzleio/sdk-javascript/blob/master/LICENSE">
|
15 | <img alt="undefined" src="https://img.shields.io/github/license/kuzzleio/sdk-javascript.svg?style=flat">
|
16 | </a>
|
17 | </p>
|
18 |
|
19 | ## About
|
20 |
|
21 | ### Kuzzle Javascript SDK
|
22 |
|
23 | This is the official Javascript SDK for the free and open-source backend Kuzzle. It provides a way to dial with a Kuzzle server from Javascript applications using protocols.
|
24 |
|
25 | #### Multiprotocols
|
26 |
|
27 | Currently, the SDK provides 3 protocols: __Http, WebSocket and SocketIO.__
|
28 | WebSocket and Socket.IO protocols implement the whole Kuzzle API, while the HTTP protocol does not implement realtime features (rooms and subscriptions).
|
29 | While Socket.IO offers better compatibility with older web browsers, our raw WebSocket implementation is about 20% faster.
|
30 |
|
31 | #### Promises based
|
32 |
|
33 | 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.
|
34 | 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.
|
35 | Any error must be caught either at the end of the `Promise` chain, or by using `async/await` and a `try...catch`.
|
36 |
|
37 | <p align="center">
|
38 | :books: <b><a href="https://docs-v2.kuzzle.io/sdk-reference/js/6/">Documentation</a></b>
|
39 | </p>
|
40 |
|
41 | ### Kuzzle
|
42 |
|
43 | Kuzzle is an open-source backend that includes a scalable server, a multiprotocol API,
|
44 | an administration console and a set of plugins that provide advanced functionalities like real-time pub/sub, blazing fast search and geofencing.
|
45 |
|
46 | * :octocat: __[Github](https://github.com/kuzzleio/kuzzle)__
|
47 | * :earth_africa: __[Website](https://kuzzle.io)__
|
48 | * :books: __[Documentation](https://docs-v2.kuzzle.io)__
|
49 | * :email: __[Gitter](https://gitter.im/kuzzleio/kuzzle)__
|
50 |
|
51 |
|
52 | ## Get trained by the creators of Kuzzle :zap:
|
53 |
|
54 | Train yourself and your teams to use Kuzzle to maximize its potential and accelerate the development of your projects.
|
55 | Our teams will be able to meet your needs in terms of expertise and multi-technology support for IoT, mobile/web, backend/frontend, devops.
|
56 | :point_right: [Get a quote](https://hubs.ly/H0jkfJ_0)
|
57 |
|
58 | ## Usage
|
59 |
|
60 | ## Compatibility matrice
|
61 |
|
62 | | Kuzzle Version | SDK Version |
|
63 | | -------------- | -------------- |
|
64 | | 1.x.x | 5.x.x |
|
65 | | 1.x.x | 6.x.x |
|
66 | | 2.x.x | 7.x.x |
|
67 |
|
68 | ### Installation
|
69 |
|
70 | This SDK can be used either in NodeJS or in a browser.
|
71 |
|
72 | #### Node.js
|
73 |
|
74 | ```
|
75 | npm install kuzzle-sdk
|
76 | ```
|
77 |
|
78 | #### Browser
|
79 |
|
80 | To run the SDK in the browser, you have to build it yourself by cloning this repository and running
|
81 | ```bash
|
82 | $ npm install
|
83 | $ npm run build
|
84 | ````
|
85 | A `dist` directory will be created, containing a browser version of this SDK.
|
86 |
|
87 | ```html
|
88 | <script type="text/javascript" src="dist/kuzzle.min.js"></script>
|
89 | ```
|
90 |
|
91 | or use the CDN:
|
92 |
|
93 | ```html
|
94 | <script type="text/javascript" src="https://cdn.jsdelivr.net/npm/kuzzle-sdk@latest/dist/kuzzle.min.js"></script>
|
95 | ```
|
96 |
|
97 | Then the Kuzzle SDK will be available under the `KuzzleSDK` variable:
|
98 |
|
99 | ```html
|
100 | <script>
|
101 | const kuzzle = new KuzzleSDK.Kuzzle(
|
102 | new KuzzleSDK.WebSocket('localhost')
|
103 | );
|
104 | // ...
|
105 | </script>
|
106 | ```
|
107 |
|
108 | If you want to support older browser versions, you may load `socket.io` before Kuzzle, making the SDK compatible with browsers without websocket support:
|
109 |
|
110 | ```html
|
111 | <!-- Don't forget to include socketio before Kuzzle SDK -->
|
112 | <script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/socket.io/2.0.3/socket.io.slim.js"></script>
|
113 | ```
|
114 |
|
115 | #### Browser with Webpack
|
116 |
|
117 | If you use Webpack, you'll likely use the NPM-packaged version of the SDK (like in Node)
|
118 |
|
119 | ```
|
120 | npm install kuzzle-sdk --save
|
121 | ```
|
122 |
|
123 | But you'll still need to pick the built version (which ships with the package).
|
124 |
|
125 | ```javascript
|
126 | // with the classic require...
|
127 | const { Kuzzle } = require('kuzzle-sdk')
|
128 | // ... or with the new import directive.
|
129 | import { Kuzzle } from 'kuzzle-sdk'
|
130 | ```
|
131 |
|
132 | ### Example
|
133 |
|
134 | The SDK supports different protocols. When instantiating,
|
135 | you must choose the protocol to use and fill in the different options needed to connect to Kuzzle.
|
136 |
|
137 | ```js
|
138 | const { Kuzzle, WebSocket } = require('kuzzle-sdk');
|
139 | const kuzzle = new Kuzzle(
|
140 | new WebSocket('localhost', { port: 7512 })
|
141 | );
|
142 |
|
143 | try {
|
144 | await kuzzle.connect();
|
145 | const serverTime = await kuzzle.server.now();
|
146 | console.log(serverTime);
|
147 | } catch (error) {
|
148 | console.error(error);
|
149 | }
|
150 | ```
|