Merge branch '2-stable' into 2-dev

.github/workflows/npm-publish.yml

@@ -1,3 +1,6 @@
+# This workflow will run tests using node and then publish a package to GitHub Packages when a release is created
+# For more information see: https://help.github.com/actions/language-and-framework-guides/publishing-nodejs-packages
+
 name: Node.js Package
 
 on:

.gitignore

@@ -1 +1,3 @@
-node_modules
+node_modules
+index.js
+index.js.map

README.md

@@ -2,12 +2,12 @@
 
 This plugin simply exposes the Kuzzle SDK in your Vuejs components.
 
-## Compatibility matrice
+## Compatibility matrix
 
-| Kuzzle Version | Vue.js Kuzzle Plugin Version    |
-| -------------- | ----------------- |
-| 1.x.x          | 1.x.x             | 
-| 2.x.x          | 2.x.x and higher  | 
+| Kuzzle Version | Vue.js Kuzzle Plugin Version |
+| -------------- | ---------------------------- |
+| 1.x.x          | 1.x.x                        |
+| 2.x.x          | 2.x.x and higher             |
 
 ## Getting started
 
@@ -20,7 +20,7 @@ npm install vue-plugin-kuzzle
 Then, in your Vuejs application, you need to register the plugin in your `Vue` class.
 
 ```javascript
-import VueKuzzle from 'vue-plugin-kuzzle';
+import { VueKuzzle } from 'vue-plugin-kuzzle';
 
 Vue.use(VueKuzzle, options);
 ```
@@ -47,6 +47,57 @@ The plugin will instantiate the Kuzzle SDK with the `Websocket` protocol, choosi
 
 **Warning** Don't forget to `connect()` your instance before performing any actions.
 
+### `options.sdkOptions`
+An object that contains the SDK options.
+You can find the available options list [here](https://docs.kuzzle.io/sdk/js/7/core-classes/kuzzle/constructor/#options)
+
+## Specify the backend via environment variables
+
+Aside from the `backends` option, you can define the backend to connect to entirely via environment variables.
+
+* `VUE_APP_BACKEND_HOST` contains the hostname (e.g. `kuzzle.mydomain.com`),
+* `VUE_APP_BACKEND_PORT` contains the port (e.g. `443`),
+* `VUE_APP_BACKEND_SSL` can be set to `true` if the connection supports the SSL layer (do not set this variable if SSL is not supported).
+
+For example, you can build your up to connect the Websocket to `wss://kuzzle.mydomain.com:443` like the following
+
+```
+VUE_APP_BACKEND_HOST=kuzzle.mydomain.com VUE_APP_BACKEND_PORT=443 VUE_APP_BACKEND_SSL=true npm run build
+```
+
+## Specify the backend via a global variable
+
+You can also specify the backend config as a JSON-stringified POJO living in a global variable called `kuzzleBackend`. This variable must be available _before_ the Vue app is started, specifically before the `instantiateKuzzleSDK` public function is called. Here is an example of how to declare it
+
+```javascript
+const kuzzleBackend = JSON.stringify({
+  host: 'myhost.mydomain.com',
+  options: {
+    port: 443,
+    ssl: true
+  }
+})
+```
+
+## Specify the backend via localStorage
+
+_Purely for debug purposes_, you can override all the backend configuration by setting your backend as stringified JSON in the `kuzzle-backend` Local Storage item, e.g.
+
+```
+{ "host": "myinstance.mydomain.io",  "options": { "port": 443, "ssl": true } }
+```
+
+**Beware that Local Storage is persistent and it is fairly easy to forget you set this item.** Use it consciously and keep in mind it is a good practice to unset it as soon as your debug session is over.
+
+## Backend declaration precedence order
+
+The plugin makes a choice of the available backend declaration by setting a preference order.
+
+* Local storage (`kuzzle-backend`)
+* Global variable (`kuzzleBackend`)
+* Environment variables
+* Options passed to `Vue.use`
+
 ## Accessing the Kuzzle SDK instance within the app
 
 You'll be able to access the Kuzzle SDK instance from the components as

index.d.ts

@@ -1,10 +1,40 @@
-declare module 'vue-kuzzle' {
-  import Vue, { PluginFunction } from 'vue';
-  export const install: PluginFunction<{}>;
-
-  module 'vue/types/vue' {
-    interface Vue {
-      $kuzzle: any;
-    }
+import Vue from 'vue';
+import _Vue from 'vue';
+import { Kuzzle } from 'kuzzle-sdk';
+
+declare module 'vue/types/vue' {
+  interface Vue {
+    $kuzzle: Kuzzle;
+  }
+}
+
+export interface Backends {
+  [name: string]: Backend
+}
+
+export interface Backend {
+  host: string;
+  options: {
+    port: number;
+    sslConnection: boolean
   }
-}
+}
+
+/**
+ * The VueKuzzle plugin. Makes the Kuzzle SDK available in Vue components as
+ * `this.$kuzzle`.
+ *
+ * @param Vue The Vue application to apply the plugin to
+ * @param options Options passed to the Kuzzle SDK constructor
+ *
+ * @see https://docs.kuzzle.io/sdk/js/7/core-classes/kuzzle/constructor/#options
+ */
+export declare function VueKuzzle(Vue: typeof _Vue, options: any): void;
+
+/**
+ * Instantiates the Kuzzle SDK by resolving the backend from the given config.
+ * 
+ * @param backendsConfig 
+ * @param sdkOptions 
+ */
+export declare function instantiateKuzzleSDK(backendsConfig: Backends, sdkOptions: any): Kuzzle

index.ts

@@ -1,19 +1,19 @@
 import { Kuzzle, WebSocket } from 'kuzzle-sdk';
-import _Vue from 'vue';
+import _Vue  from 'vue';
 
-const LS_KEY = 'kuzzle-backend';
-const GLOBAL_NAME = 'kuzzleBackend';
+const LS_KEY = 'kuzzle-backend'
+const GLOBAL_NAME = 'kuzzleBackend'
 
 interface Backend {
   host: string;
   options: {
     port: number;
-    sslConnection: boolean;
-  };
+    sslConnection: boolean
+  }
 }
 
 interface Backends {
-  [name: string]: Backend;
+  [name: string]: Backend
 }
 
 export function getBackendFromConf(backendsConfig: Backends) {
@@ -22,19 +22,19 @@ export function getBackendFromConf(backendsConfig: Backends) {
       host: process.env.VUE_APP_BACKEND_HOST || 'localhost',
       options: {
         port: parseInt(process.env.VUE_APP_BACKEND_PORT || '7512'),
-        sslConnection: process.env.VUE_APP_BACKEND_SSL === 'true' || false,
-      },
+        sslConnection: process.env.VUE_APP_BACKEND_SSL === 'true' || false
+      }
     },
-    ...backendsConfig,
-  };
+    ...backendsConfig
+  }
 
   const backendName: string = process.env.VUE_APP_BACKEND
     ? process.env.VUE_APP_BACKEND
     : 'default';
 
-  if (!backends[backendName]) {
-    throw new Error(`Unable to find backend ${backendName} in configuration.`);
-  }
+    if (!backends[backendName]) {
+      throw new Error(`Unable to find backend ${backendName} in configuration.`);
+    }
 
   return backends[backendName] ? backends[backendName] : null;
 }
@@ -104,7 +104,7 @@ export const instantiateKuzzleSDK = (
  * @see https://docs.kuzzle.io/sdk/js/7/core-classes/kuzzle/constructor/#options
  */
 export const VueKuzzle = {
-  install(Vue, options) {
+  install(Vue: typeof _Vue, options: any) {
     const sdkOptions = options.sdkOptions ? options.sdkOptions : {};
     Vue.prototype.$kuzzle = instantiateKuzzleSDK(options.backends, sdkOptions);
   },

package.json

@@ -24,6 +24,9 @@
     "url": "https://github.com/kuzzleio/vue-plugin-kuzzle/issues"
   },
   "homepage": "https://github.com/kuzzleio/vue-plugin-kuzzle#readme",
+  "peerDependencies": {
+    "kuzzle-sdk": "~7.x"
+  },
   "dependencies": {
     "kuzzle-sdk": "^7.7.6",
     "vue": "^2.6.14"

tsconfig.json

@@ -0,0 +1,27 @@
+{
+  "compilerOptions": {
+    "target": "esnext",
+    "module": "esnext",
+    "strict": true,
+    "importHelpers": true,
+    "moduleResolution": "node",
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "declaration": false,
+    "sourceMap": true,
+    "resolveJsonModule": true,
+    "baseUrl": ".",
+    "lib": [
+      "esnext",
+      "dom",
+      "dom.iterable",
+      "scripthost"
+    ]
+  },
+  "include": [
+    "./index.ts"
+  ],
+  "exclude": [
+    "node_modules"
+  ]
+}

vue-kuzzle.d.ts

@@ -0,0 +1,12 @@
+// 1. Make sure to import 'vue' before declaring augmented types
+import Vue from 'vue';
+import { Kuzzle } from 'kuzzle-sdk';
+
+// 2. Specify a file with the types you want to augment
+//    Vue has the constructor type in types/vue.d.ts
+declare module 'vue/types/vue' {
+  // 3. Declare augmentation for Vue
+  interface Vue {
+    $kuzzle: Kuzzle;
+  }
+}