mobility-toolbox-js 3.0.0-beta.0 → 3.0.0-beta.10

package/api/RealtimeAPI.js

@@ -1,3 +1,4 @@
+/* eslint-disable no-underscore-dangle */
 /* eslint-disable class-methods-use-this */
 import WebSocketAPI from './WebSocketAPI';
 import debounceWebsocketMessages from '../common/utils/debounceWebsocketMessages';
@@ -10,6 +11,7 @@ import getModeSuffix from '../common/utils/getRealtimeModeSuffix';
  * @property {string} SCHEMATIC "schematic"
  * @property {string} TOPOGRAPHIC "topographic"
  * @enum {RealtimeMode}
+ * @public
  */
 export const RealtimeModes = {
     RAW: 'raw',
@@ -17,123 +19,135 @@ export const RealtimeModes = {
     SCHEMATIC: 'schematic',
 };
 /**
- * This class provides convenience methods to use to the [geOps Realtime API](https://developer.geops.io/apis/realtime/).
+ * This class provides convenience methods to use to the [geOps realtime API](https://developer.geops.io/apis/realtime/).
  *
  * @example
  * import { RealtimeAPI } from 'mobility-toolbox-js/api';
  *
  * const api = new RealtimeAPI({
  *   apiKey: "yourApiKey",
- *   bbox: [782001, 5888803, 923410, 5923660, 11, "mots=rail],
+ *   bbox: [782001, 5888803, 923410, 5923660, 11, "mots=rail"],
  *   // url: "wss://api.geops.io/tracker-ws/v1/",
  * });
  *
+ * // Open the websocket connection
  * api.open();
  *
+ * // Subscribe to channel
  * api.subscribeTrajectory('topographic', (data) => {
  *    console.log('Log trajectories:', JSON.stringify(data.content));
  * });
  *
- * @classproperty {string} apiKey - Access key for [geOps APIs](https://developer.geops.io/)
- * @classproperty {RealtimeBbox} bbox - The bounding box to receive data from. \ Example: \ [ minX, minY, maxX, maxY, zoom, "tenant=tenant1", "gen_level=5", "mots=mot1,mot2" ]. \ tenant, gen_level and mots are optional.
- * @classproperty {string} url - The [geOps Realtime API](https://developer.geops.io/apis/realtime/) url.
+ * // Close the websocket connection
+ * // api.close();
+ *
  * @public
  */
 class RealtimeAPI {
+    get url() {
+        return this._url;
+    }
+    set url(newUrl) {
+        if (this._url !== newUrl) {
+            this._url = newUrl;
+            // Update the websocket only if the url has changed and the websocket is already open or is opening.
+            if (this.wsApi.open || this.wsApi.connecting) {
+                this.open();
+            }
+        }
+    }
+    /**
+     * The bounding box to receive data from.\
+     * Example: [minX, minY, maxX, maxY, zoom, mots , gen_level, tenant, ...]\
+     *  \
+     * Where:
+     * - **minX**: a string representation of an integer (not a float) representing the minimal X coordinate (in EPSG:3857) of a bounding box\
+     *  
+     * - **minY**: a string representation of an integer (not a float) representing the minimal Y coordinate (in EPSG:3857) of a bounding box\
+     *  
+     * - **maxX**: a string representation of an integer (not a float) representing the maximal X coordinate (in EPSG:3857) of a bounding box\
+     *  
+     * - **maxY**: a string representation of an integer (not a float) representing the maximal Y coordinate (in EPSG:3857) of a bounding box\
+     *  
+     * - **zoom**: a string representation of an integer representing the zoom level (from 4 to 22). When zoom < 8 only the trains are displayed for performance reasons.\
+     * &nbsp;
+     * - **mots**: A comma separated list of modes of transport. **Optional**.\
+     *         Example: "mots=rail,subway".\
+     * &nbsp;
+     * - **gen_level**: An integer representing the generalization level. **Optional**.\
+     *              Example: "gen_level=5"\
+     * &nbsp;
+     * - **tenant**: A string representing the tenant. **Optional**.\
+     *           Example: "tenant=sbb"\
+     * &nbsp;
+     * - ...: Any other values added to the bbox will be send to the server
+     *
+     * @type {string[]}
+     *
+     * @public
+     */
+    get bbox() {
+        return this._bbox;
+    }
+    set bbox(newBbox) {
+        if (JSON.stringify(newBbox) !== JSON.stringify(this._bbox)) {
+            this._bbox = newBbox;
+            if (this.wsApi && this._bbox) {
+                this.wsApi.send(`BBOX ${this._bbox.join(' ')}`);
+            }
+        }
+    }
+    get buffer() {
+        return this._buffer;
+    }
+    set buffer(newBuffer) {
+        if (JSON.stringify(newBuffer) !== JSON.stringify(this._buffer)) {
+            this._buffer = newBuffer;
+            if (this.wsApi && this._buffer) {
+                this.wsApi.send(`BUFFER ${this._buffer.join(' ')}`);
+            }
+        }
+    }
     /**
      * Constructor
      *
-     * @param {RealtimeAPIOptions} options A string representing the url of the service or an object containing the url and the apiKey.
-     * @param {string} options.url Url to the [geOps realtime api](https://developer.geops.io/apis/realtime/).
+     * @param {Object} options Options.
      * @param {string} options.apiKey Access key for [geOps apis](https://developer.geops.io/).
-     * @param {number[5]} [options.bbox=[minX, minY, maxX, maxY, zoom, tenant]] The bounding box to receive data from.
+     * @param {string[]} options.bbox The bounding box to receive data from.
+     * @param {string} [options.url='wss://api.geops.io/tracker-ws/v1/'] Url of the [geOps realtime API](https://developer.geops.io/apis/realtime/).
+     * @public
      */
     constructor(options = {}) {
         this.version = '2';
-        this.defineProperties(options);
-        this.onOpen = this.onOpen.bind(this);
-    }
-    defineProperties(options = {}) {
-        let opt = options || {};
+        let opt = options;
         if (typeof options === 'string') {
             opt = { url: options };
         }
-        const { apiKey, version } = opt;
-        let { url, bbox, buffer = [100, 100] } = opt;
+        const { apiKey } = opt;
+        const { url } = opt;
         const wsApi = new WebSocketAPI();
-        if (!url) {
-            url = 'wss://api.geops.io/tracker-ws/v1/';
-        }
-        if (apiKey) {
-            url = `${url}?key=${apiKey}`;
+        let suffix = '';
+        if (apiKey && !(url === null || url === void 0 ? void 0 : url.includes('key='))) {
+            suffix = `?key=${apiKey}`;
         }
-        Object.defineProperties(this, {
-            url: {
-                get: () => url,
-                set: (newUrl) => {
-                    if (url !== newUrl) {
-                        url = newUrl;
-                        // Update the websocket only if the url has changed and the websocket is already open or is opening.
-                        if (this.wsApi.open || this.wsApi.connecting) {
-                            this.open();
-                        }
-                    }
-                },
-            },
-            bbox: {
-                get: () => bbox,
-                set: (newBbox) => {
-                    if (JSON.stringify(newBbox) !== JSON.stringify(bbox)) {
-                        bbox = newBbox;
-                        if (this.wsApi && bbox) {
-                            this.wsApi.send(`BBOX ${bbox.join(' ')}`);
-                        }
-                    }
-                },
-            },
-            buffer: {
-                get: () => buffer,
-                set: (newBuffer) => {
-                    if (JSON.stringify(newBuffer) !== JSON.stringify(buffer)) {
-                        buffer = newBuffer;
-                        if (this.wsApi) {
-                            this.wsApi.send(`BUFFER ${buffer.join(' ')}`);
-                        }
-                    }
-                },
-            },
-            version: {
-                value: version,
-                writable: true,
-            },
-            /**
-             * The websocket helper class to connect the websocket.
-             *
-             * @private
-             */
-            wsApi: {
-                value: wsApi,
-                writable: true,
-            },
-            /**
-             * Interval between PING request in ms.
-             * If equal to 0,  no PING request are sent.
-             * @type {number}
-             * @private
-             */
-            pingIntervalMs: {
-                value: options.pingIntervalMs || 10000,
-                writable: true,
-            },
-            /**
-             * Timeout in ms after an automatic reconnection when the websoscket has been closed by the server.
-             * @type {number}
-             */
-            reconnectTimeoutMs: {
-                value: options.pingIntervalMs || 100,
-                writable: true,
-            },
-        });
+        this._url = (url || 'wss://api.geops.io/tracker-ws/v1/') + suffix;
+        this._buffer = opt.buffer || [100, 100];
+        this.version = opt.version || '2';
+        /**
+         * Interval between PING request in ms.
+         * If equal to 0,  no PING request are sent.
+         * @type {number}
+         */
+        this.pingIntervalMs = opt.pingIntervalMs || 10000;
+        /**
+         * Timeout in ms after an automatic reconnection when the websoscket has been closed by the server.
+         * @type {number}
+         */
+        this.reconnectTimeoutMs = opt.reconnectTimeoutMs || 100;
+        /**
+         * The websocket helper class to connect the websocket.
+         */
+        this.wsApi = wsApi;
     }
     /**
      * Open the websocket connection.
@@ -141,7 +155,7 @@ class RealtimeAPI {
      * @public
      */
     open() {
-        this.wsApi.connect(this.url, this.onOpen);
+        this.wsApi.connect(this.url, this.onOpen.bind(this));
         // Register reconnection on close.
         if (this.wsApi.websocket) {
             this.wsApi.websocket.onclose = () => {
@@ -160,7 +174,6 @@ class RealtimeAPI {
     /**
      * Unsubscribe trajectory and deleted_vehicles channels. To resubscribe you have to set a new BBOX.
      */
-    // eslint-disable-next-line class-methods-use-this
     reset() {
         this.wsApi.send('RESET');
     }

package/api/RoutingAPI.d.ts

@@ -0,0 +1,37 @@
+import HttpAPI from './HttpAPI';
+import { RoutingParameters, RoutingResponse } from '../types';
+export type RoutingAPIOptions = {
+    url?: string;
+    apiKey?: string;
+};
+/**
+ * Access to the [geOps Routing API](https://developer.geops.io/apis/routing).
+ *
+ * @example
+ * import { RoutingAPI } from 'mobility-toolbox-js';
+ *
+ * const api = new RoutingAPI({
+ *   apiKey: [yourApiKey]
+ * });
+ *
+ * @public
+ */
+declare class RoutingAPI extends HttpAPI {
+    /**
+     * Constructor
+     *
+     * @param {RoutingAPIOptions} options Options.
+     * @param {string} [options.url='https://api.geops.io/routing/v1/'] Service url.
+     * @param {string} options.apiKey Access key for [geOps services](https://developer.geops.io/).
+     */
+    constructor(options?: RoutingAPIOptions);
+    /**
+     * Route.
+     *
+     * @param {RoutingParameters} params Request parameters. See [Routing service documentation](https://developer.geops.io/apis/routing/).
+     * @param {RequestInit} config Options for the fetch request.
+     * @return {Promise<RoutingResponse>} An GeoJSON feature collection with coordinates in [EPSG:4326](http://epsg.io/4326).
+     */
+    route(params: RoutingParameters, config: RequestInit): Promise<RoutingResponse>;
+}
+export default RoutingAPI;

package/api/StopsAPI.d.ts

@@ -0,0 +1,44 @@
+import HttpAPI from './HttpAPI';
+import { StopsParameters, StopsResponse } from '../types';
+export type StopsAPIOptions = {
+    url?: string;
+    apiKey?: string;
+};
+/**
+ * This class provides convenience methods to use to the [geOps Stops api](https://developer.geops.io/apis/stops/).
+ *
+ * @example
+ * import { StopsAPI } from 'mobility-toolbox-js/api';
+ *
+ * const api = new StopsAPI({
+ *   apiKey: [yourApiKey],
+ *   // url: 'https://api.geops.io/stops/v1/',
+ * });
+ *
+ * const stops = await api.search({ q:"Bern" });
+ *
+ * console.log('Log stops:', JSON.stringify(stops));
+ *
+ * @public
+ */
+declare class StopsAPI extends HttpAPI {
+    /**
+     * Constructor
+     *
+     * @param {Object} options Options.
+     * @param {string} options.apiKey Access key for [geOps apis](https://developer.geops.io/).
+     * @param {string} [options.url='https://api.geops.io/stops/v1/'] Url of the [geOps stops API](https://developer.geops.io/apis/stops/).
+     * @public
+     */
+    constructor(options?: StopsAPIOptions);
+    /**
+     * Search fo stops.
+     *
+     * @param {StopsAPIParameters} params Request parameters. See [Stops API documentation](https://developer.geops.io/apis/stops).
+     * @param {FetchOptions} config Options for the fetch request.
+     * @returns {Promise<StopsAPIResponse>} An GeoJSON feature collection with coordinates in [EPSG:4326](http://epsg.io/4326). See [Stops API documentation](https://developer.geops.io/apis/stops).
+     * @public
+     */
+    search(params: StopsParameters, config: RequestInit): Promise<StopsResponse>;
+}
+export default StopsAPI;

package/api/StopsAPI.js

@@ -1,24 +1,29 @@
 import HttpAPI from './HttpAPI';
 /**
- * Access to the [geOps Stops api](https://developer.geops.io/apis/5dcbd702a256d90001cf1361/).
+ * This class provides convenience methods to use to the [geOps Stops api](https://developer.geops.io/apis/stops/).
  *
  * @example
  * import { StopsAPI } from 'mobility-toolbox-js/api';
  *
  * const api = new StopsAPI({
- *   url: 'https://api.geops.io/stops/v1/',
- *   apiKey: [yourApiKey]
+ *   apiKey: [yourApiKey],
+ *   // url: 'https://api.geops.io/stops/v1/',
  * });
  *
+ * const stops = await api.search({ q:"Bern" });
+ *
+ * console.log('Log stops:', JSON.stringify(stops));
+ *
  * @public
  */
 class StopsAPI extends HttpAPI {
     /**
      * Constructor
      *
-     * @param {StopsAPIOptions} options Options.
-     * @param {string} [options.url='https://api.geops.io/stops/v1/'] Service url.
-     * @param {string} options.apiKey Access key for [geOps services](https://developer.geops.io/).
+     * @param {Object} options Options.
+     * @param {string} options.apiKey Access key for [geOps apis](https://developer.geops.io/).
+     * @param {string} [options.url='https://api.geops.io/stops/v1/'] Url of the [geOps stops API](https://developer.geops.io/apis/stops/).
+     * @public
      */
     constructor(options = {}) {
         super(Object.assign({ url: 'https://api.geops.io/stops/v1/' }, options));
@@ -26,9 +31,10 @@ class StopsAPI extends HttpAPI {
     /**
      * Search fo stops.
      *
-     * @param {StopsParameters} params Request parameters. See [Stops service documentation](https://developer.geops.io/apis/stops).
-     * @param {RequestInit} config Options for the fetch request.
-     * @return {Promise<StopsResponse>} An GeoJSON feature collection with coordinates in [EPSG:4326](http://epsg.io/4326).
+     * @param {StopsAPIParameters} params Request parameters. See [Stops API documentation](https://developer.geops.io/apis/stops).
+     * @param {FetchOptions} config Options for the fetch request.
+     * @returns {Promise<StopsAPIResponse>} An GeoJSON feature collection with coordinates in [EPSG:4326](http://epsg.io/4326). See [Stops API documentation](https://developer.geops.io/apis/stops).
+     * @public
      */
     search(params, config) {
         return this.fetch('', params, config);

package/api/WebSocketAPI.d.ts

@@ -0,0 +1,153 @@
+import { RealtimeTrajectoryResponse } from '../types';
+export declare type WebSocketAPIParameters = {
+    channel?: string;
+    args?: string | number;
+    id?: string | number;
+};
+export declare type WebSocketAPIMessageEventData<T> = {
+    timestamp: number;
+    source: string;
+    content: T;
+    client_reference: string | number | null;
+};
+export type WebSocketAPIBufferMessageEventData = WebSocketAPIMessageEventData<RealtimeTrajectoryResponse[]> & {
+    source: 'buffer';
+};
+export type WebSocketAPIMessageEvent = Event & {
+    data: string;
+};
+export interface WebSocketAPIMessageEventListener {
+    (evt: WebSocketAPIMessageEvent): void;
+}
+/**
+ * This type represents a function that has been call with each feature returned by the websocket.
+ */
+export interface WebSocketAPIMessageCallback<T> {
+    (data: WebSocketAPIMessageEventData<T>): void;
+}
+export declare type WebSocketAPISubscription = {
+    params: WebSocketAPIParameters;
+    cb: WebSocketAPIMessageCallback<any>;
+    errorCb?: EventListener;
+    onMessageCb: WebSocketAPIMessageEventListener;
+    onErrorCb?: EventListener;
+    quiet: boolean;
+};
+export declare type WebSocketAPISubscribed = {
+    [index: string]: boolean;
+};
+export declare type WebSocketAPIRequest = {
+    params: WebSocketAPIParameters;
+    cb: WebSocketAPIMessageCallback<any>;
+    errorCb?: EventListener;
+    onMessageCb: WebSocketAPIMessageEventListener;
+    onErrorCb?: EventListener;
+    requestString: String;
+};
+/**
+ * Class used to facilitate connection to a WebSocketAPI and
+ * also to manage properly messages send to the WebSocketAPI.
+ * This class must not contain any specific implementation.
+ * @private
+ */
+declare class WebSocketAPI {
+    websocket?: WebSocket;
+    closed?: boolean;
+    closing?: boolean;
+    connecting?: boolean;
+    open?: boolean;
+    messagesOnOpen: Array<string>;
+    subscriptions: Array<WebSocketAPISubscription>;
+    subscribed: WebSocketAPISubscribed;
+    requests: Array<WebSocketAPIRequest>;
+    constructor();
+    defineProperties(): void;
+    /**
+     * Get the websocket request string.
+     *
+     * @param {string} method Request mehtod {GET, SUB}.
+     * @param {WebSocketParameters} params Request parameters.
+     * @param {string} params.channel Channel name
+     * @param {string} [params.args] Request arguments
+     * @param {Number|string} [params.id] Request identifier
+     * @return {string} request string
+     * @private
+     */
+    static getRequestString(method: string, params?: WebSocketAPIParameters): string;
+    /**
+     * (Re)connect the websocket.
+     *
+     * @param {string} url Websocket url.
+     * @param {function} onOpen Callback called when the websocket connection is opened and before subscriptions of previous subscriptions.
+     * @private
+     */
+    connect(url: string, onOpen?: () => void): void;
+    /**
+     * Close the websocket definitively.
+     *
+     * @private
+     */
+    close(): void;
+    /**
+     * Sends a message to the websocket.
+     *
+     * @param {message} message Message to send.
+     * @private
+     */
+    send(message: string): void;
+    addEvents(onMessage: WebSocketAPIMessageEventListener, onError?: EventListener): void;
+    removeEvents(onMessage: WebSocketAPIMessageEventListener, onError?: EventListener): void;
+    /**
+     * Listen to websocket messages.
+     *
+     * @param {WebSocketParameters} params Parameters for the websocket get request
+     * @param {function} cb callback on listen
+     * @param {function} errorCb Callback on error
+     * @return {{onMessage: function, errorCb: function}} Object with onMessage and error callbacks
+     * @private
+     */
+    listen(params: WebSocketAPIParameters, cb: WebSocketAPIMessageCallback<any>, errorCb?: EventListener): {
+        onMessageCb: WebSocketAPIMessageEventListener;
+        onErrorCb?: EventListener;
+    };
+    /**
+     * Unlisten websocket messages.
+     *
+     * @param {Object} params Parameters for the websocket get request.
+     * @param {function} cb Callback used when listen.
+     * @private
+     */
+    unlisten(params: WebSocketAPIParameters, cb: WebSocketAPIMessageCallback<any>): void;
+    /**
+     * Sends a get request to the websocket.
+     * The callback is called only once, when the response is received or when the call returns an error.
+     *
+     * @param {Object} params Parameters for the websocket get request
+     * @param {function} onMessage callback on message event
+     * @param {function} onError Callback on error and close event
+     * @private
+     */
+    get(params: WebSocketAPIParameters, cb: WebSocketAPIMessageCallback<any>, errorCb?: EventListener): void;
+    /**
+     * Subscribe to a given channel.
+     *
+     * @param {Object} params Parameters for the websocket get request
+     * @param {function} cb callback on listen
+     * @param {function} errorCb Callback on error
+     * @param {boolean} quiet if false, no GET or SUB requests are send, only the callback is registered.
+     * @private
+     */
+    subscribe(params: WebSocketAPIParameters, cb: WebSocketAPIMessageCallback<any>, errorCb?: EventListener, quiet?: boolean): void;
+    /**
+     * Unsubscribe from a channel.
+     * @param {string} source source to unsubscribe from
+     * @param {function} cb Callback function to unsubscribe. If null all subscriptions for the channel will be unsubscribed.
+     * @private
+     */
+    unsubscribe(source: string, cb?: WebSocketAPIMessageCallback<any>): void;
+    /**
+     * After an auto reconnection we need to re-subscribe to the channels.
+     */
+    subscribePreviousSubscriptions(): void;
+}
+export default WebSocketAPI;

package/api/index.d.ts

@@ -0,0 +1,3 @@
+export { default as RoutingAPI } from "./RoutingAPI";
+export { default as StopsAPI } from "./StopsAPI";
+export { default as RealtimeAPI, RealtimeModes } from "./RealtimeAPI";