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

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2020 geOps
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,42 @@
+# mobility-toolbox-js
+
+Toolbox for JavaScript applications in the domains of mobility and logistics.
+The tools in this library have been inspired by many projects realized for public transport agencies, mobility providers and logistics companies.
+
+[![npm](https://img.shields.io/npm/v/mobility-toolbox-js.svg?style=flat-square)](https://www.npmjs.com/package/mobility-toolbox-js)
+[![Build](https://github.com/geops/mobility-toolbox-js/workflows/Build/badge.svg)](https://github.com/geops/mobility-toolbox-js/actions?query=workflow%3ABuild)
+[![Lint / Unit tests](https://github.com/geops/mobility-toolbox-js/workflows/Lint%20/%20Unit%20tests/badge.svg)](https://github.com/geops/mobility-toolbox-js/actions?query=workflow%3ALint%20/%20Unit%20tests)
+![Vercel](https://vercelbadge.vercel.app/api/geops/mobility-toolbox-js)
+
+## Documentation and examples
+
+Visit https://mobility-toolbox-js.vercel.app/
+
+## Demos
+
+* Display [real-time vehicle positions and prognosis data](https://mobility.portal.geops.io) on a map.
+* Search for [stops and stations](https://maps.trafimage.ch) all over the world.
+* Get [precise geographic courses](https://routing-demo.geops.io/) for all modes of transport.
+* Generate beautiful [schematic](https://mobility.portal.geops.io/world.geops.networkplans) or [topographic](https://mobility.portal.geops.io) maps for public transport, mobility and logistics.
+
+## Install
+
+Install the library and the peer dependencies:
+
+```bash
+yarn add mobility-toolbox-js ol maplibre-gl
+```
+
+## Development
+
+```bash
+yarn install
+yarn dev
+```
+
+## Deploy
+
+This library website is deployed automatically using [Vercel](https://vercel.com/geops).
+For Vercel we have to add the nextjs and raw-loader modules in the dev dependencies of the main package.json.
+But those 2 librairies are not needed to build the library.
+

package/api/HttpAPI.d.ts

@@ -0,0 +1,20 @@
+export type HttpAPIOptions = {
+    url: string;
+    apiKey?: string;
+};
+/**
+ * Common class to access to a geOps api using http.
+ * @private
+ */
+declare class HttpAPI {
+    url: string;
+    apiKey?: string;
+    constructor(options: HttpAPIOptions);
+    /**
+     * Append the apiKey before sending the request.
+     *
+     * @private
+     */
+    fetch(path: string, params: Object, config: RequestInit): Promise<any>;
+}
+export default HttpAPI;

package/api/HttpAPI.js

@@ -10,17 +10,6 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 import getUrlWithParams from '../common/utils/getUrlWithParams';
 /**
  * Common class to access to a geOps api using http.
- *
- * @example
- * import { API } from 'mobility-toolbox-js/api';
- *
- * const api = new HttpApi({
- *   url: [yourUrl],
- *   apiKey: [yourApiKey]
- * });
- *
- * @classproperty {string} url Url of the service.
- * @classproperty {string} apiKey Api key to access the service.
  * @private
  */
 class HttpAPI {
@@ -47,6 +36,7 @@ class HttpAPI {
             // Clean requets parameters, removing undefined and null values.
             const searchParams = params || {};
             const url = getUrlWithParams(`${this.url}${path || ''}`, Object.assign({ key: this.apiKey }, searchParams));
+            fetch;
             const response = yield fetch(url.toString(), config);
             const data = yield response.json();
             if (data.error) {

package/api/RealtimeAPI.d.ts

@@ -0,0 +1,365 @@
+import WebSocketAPI, { WebSocketAPIMessageCallback, WebSocketAPIMessageEventData, WebSocketAPIParameters } from './WebSocketAPI';
+import type { RealtimeMode, RealtimeDeparture, RealtimeNews, RealtimeStation, RealtimeExtraGeom, RealtimeTrainId, RealtimeGeneralizationLevel, RealtimeFullTrajectory, RealtimeTrajectoryResponse, RealtimeStationId, RealtimeVersion, RealtimeTrajectory, RealtimeTenant, RealtimeBbox } from '../types';
+import { StopSequence } from './typedefs';
+/**
+ * @typedef RealtimeAPIOptions
+ */
+export type RealtimeAPIOptions = {
+    url?: string;
+    apiKey?: string;
+    version?: RealtimeVersion;
+    bbox?: RealtimeBbox;
+    buffer?: number[];
+    pingIntervalMs?: number;
+    reconnectTimeoutMs?: number;
+};
+export declare type RealtimeAPIExtraGeomsById = {
+    [index: string]: RealtimeExtraGeom;
+};
+export type RealtimeAPIDeparturesById = {
+    [index: string]: RealtimeDeparture;
+};
+export type RealtimeModesType = {
+    RAW: RealtimeMode;
+    TOPOGRAPHIC: RealtimeMode;
+    SCHEMATIC: RealtimeMode;
+};
+/**
+ * Enum for Realtime modes.
+ * @readonly
+ * @typedef {string} RealtimeMode
+ * @property {string} RAW "raw"
+ * @property {string} SCHEMATIC "schematic"
+ * @property {string} TOPOGRAPHIC "topographic"
+ * @enum {RealtimeMode}
+ * @public
+ */
+export declare const RealtimeModes: {
+    RAW: RealtimeMode;
+    TOPOGRAPHIC: RealtimeMode;
+    SCHEMATIC: RealtimeMode;
+};
+/**
+ * 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"],
+ *   // 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));
+ * });
+ *
+ * // Close the websocket connection
+ * // api.close();
+ *
+ * @public
+ */
+declare class RealtimeAPI {
+    _url: string;
+    get url(): string;
+    set url(newUrl: string);
+    _bbox?: RealtimeBbox;
+    /**
+     * 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(): RealtimeBbox | undefined;
+    set bbox(newBbox: RealtimeBbox | undefined);
+    _buffer?: number[];
+    get buffer(): number[] | undefined;
+    set buffer(newBuffer: number[] | undefined);
+    version: RealtimeVersion;
+    wsApi: WebSocketAPI;
+    private pingInterval;
+    private pingIntervalMs;
+    private reconnectTimeout?;
+    private reconnectTimeoutMs?;
+    /**
+     * Constructor
+     *
+     * @param {Object} options Options.
+     * @param {string} options.apiKey Access key for [geOps apis](https://developer.geops.io/).
+     * @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?: RealtimeAPIOptions);
+    /**
+     * Open the websocket connection.
+     *
+     * @public
+     */
+    open(): void;
+    /**
+     * Close the websocket connection without reconnection.
+     *
+     * @public
+     */
+    close(): void;
+    /**
+     * Unsubscribe trajectory and deleted_vehicles channels. To resubscribe you have to set a new BBOX.
+     */
+    reset(): void;
+    /**
+     * Callback when the websocket is opened and ready.
+     * It applies the bbox and the projection.
+     * @private
+     */
+    onOpen(): void;
+    /**
+     * Callback when the websocket is closed by the server.
+     * It auto reconnects after a timeout.
+     * @private
+     */
+    onClose(): void;
+    /**
+     * Send GET to a channel.
+     *
+     * @param {string | WebSocketAPIParameters} channelOrParams Name of the websocket channel to send GET or an object representing parameters to send
+     * @return {Promise<WebSocketAPIMessageEventData<?>>} A websocket response.
+     */
+    get(channelOrParams: string | WebSocketAPIParameters): Promise<WebSocketAPIMessageEventData<any>>;
+    /**
+     * Subscribe to a channel.
+     *
+     * @param {string} channel Name of the websocket channel to subscribe.
+     * @param {function} onSuccess Callback when the subscription succeeds.
+     * @param {function} onError Callback when the subscription fails.
+     * @param {boolean} [quiet=false] If true avoid to store the subscription in the subscriptions list.
+     * @private
+     */
+    subscribe(channel: string, onSuccess: WebSocketAPIMessageCallback<any>, onError?: EventListener, quiet?: boolean): void;
+    /**
+     * Unsubscribe both modes of a channel.
+     *
+     * @param {string} channel Name of the websocket channel to unsubscribe.
+     * @param {string} suffix Suffix to add to the channel name.
+     * @param {function} onMessage Callback function to unsubscribe. If null all subscriptions for the channel will be unsubscribed.
+     * @private
+     */
+    unsubscribe(channel: string, suffix?: string, onMessage?: WebSocketAPIMessageCallback<any>): void;
+    /**
+     * Subscribe to departures channel of a given station.
+     *
+     * @param {number} stationId UIC of the station.
+     * @param {Boolean} sortByMinArrivalTime Sort by minimum arrival time
+     * @param {function(departures:Departure[])} onMessage Function called on each message of the channel.
+     * @param {function} onError Callback when the subscription fails.
+     * @param {boolean} [quiet=false] If true avoid to store the subscription in the subscriptions list.
+     * @public
+     */
+    subscribeDepartures(stationId: number, onMessage: WebSocketAPIMessageCallback<RealtimeDeparture>, onError?: EventListener, quiet?: boolean): void;
+    /**
+     * Unsubscribe from current departures channel.
+     * @param {RealtimeStationId} id Station's id
+     * @param {function(data: { content: RealtimeDeparture[] })} onMessage Callback function to unsubscribe. If null all subscriptions for the channel will be unsubscribed.
+     * @public
+     */
+    unsubscribeDepartures(id: RealtimeStationId, onMessage?: WebSocketAPIMessageCallback<RealtimeDeparture>): void;
+    /**
+     * Subscribe to the disruptions channel for tenant.
+     *
+     * @param {function(data: { content: RealtimeNews[] })} onMessage Function called on each message of the channel.
+     * @param {function} onError Callback when the subscription fails.
+     * @param {boolean} [quiet=false] If true avoid to store the subscription in the subscriptions list.
+     * @public
+     */
+    subscribeDisruptions(tenant: RealtimeTenant, onMessage: WebSocketAPIMessageCallback<RealtimeNews>, onError?: EventListener, quiet?: boolean): void;
+    /**
+     * Unsubscribe disruptions.
+     *
+     * @param {function(data: { content: RealtimeNews[] })} onMessage Callback function to unsubscribe. If null all subscriptions for the channel will be unsubscribed.
+     * @public
+     */
+    unsubscribeDisruptions(tenant: RealtimeTenant, onMessage?: WebSocketAPIMessageCallback<RealtimeNews>): void;
+    /**
+     * Return a station with a given uic number and a mode.
+     *
+     * @param {number} uic UIC of the station.
+     * @param {RealtimeMode} mode Realtime mode.
+     * @return {Promise<{data: { content: RealtimeStation }}>} A station.
+     * @public
+     */
+    getStation(uic: RealtimeStationId, mode: RealtimeMode): Promise<WebSocketAPIMessageEventData<RealtimeStation>>;
+    /**
+     * Get the list of ststions available for a specifc mode. The promise is resolved every 100ms
+     * @param {RealtimeMode} mode Realtime mode.
+     * @param {number} timeout = 100 Duration in ms between each promise resolve calls.
+     * @return {Promise<RealtimeStation[]>} An array of stations.
+     * @public
+     */
+    getStations(mode: RealtimeMode, timeout?: number): Promise<RealtimeStation[]>;
+    /**
+     * Subscribe to stations channel.
+     * One message pro station.
+     *
+     * @param {RealtimeMode} mode Realtime mode.
+     * @param {function(data: { content: RealtimeStation })} onMessage Function called on each message of the channel.
+     * @param {function} onError Callback when the subscription fails.
+     * @param {boolean} [quiet=false] If true avoid to store the subscription in the subscriptions list.
+     * @public
+     */
+    subscribeStations(mode: RealtimeMode, onMessage: WebSocketAPIMessageCallback<RealtimeStation>, onError?: EventListener, quiet?: boolean): void;
+    /**
+     * Unsubscribe to stations channel.
+     * @param {function(data: { content: RealtimeStation })} onMessage The listener callback function to unsubscribe. If null all subscriptions for the channel will be unsubscribe.
+     * @public
+     */
+    unsubscribeStations(onMessage?: WebSocketAPIMessageCallback<RealtimeStation>): void;
+    /**
+     * Subscribe to extra_geoms channel.
+     *
+     * @param {function(data: { content: RealtimeExtraGeom })} onMessage Function called on each message of the channel.
+     * @param {function} onError Callback when the subscription fails.
+     * @param {boolean} [quiet=false] If true avoid to store the subscription in the subscriptions list.
+     */
+    subscribeExtraGeoms(onMessage: WebSocketAPIMessageCallback<RealtimeExtraGeom>, onError?: EventListener, quiet?: boolean): void;
+    /**
+     * Unsubscribe to extra_geoms channel.
+     * @param {function(data: { content: RealtimeExtraGeom })} onMessage Callback function to unsubscribe. If null all subscriptions for the channel will be unsubscribed.
+     */
+    unsubscribeExtraGeoms(onMessage: WebSocketAPIMessageCallback<RealtimeExtraGeom>): void;
+    /**
+     * Return a partial trajectory with a given id and a mode.
+     *
+     * @param {number} trainId The identifier of a trajectory.
+     * @param {RealtimeMode} mode Realtime mode.
+     * @return {Promise<{data: { content: RealtimeTrajectory }}>} A trajectory.
+     * @public
+     */
+    getTrajectory(id: RealtimeTrainId, mode: RealtimeMode): Promise<WebSocketAPIMessageEventData<RealtimeTrajectory>>;
+    /**
+     * Subscribe to trajectory channel.
+     *
+     * @param {RealtimeMode} mode Realtime mode.
+     * @param {function(data: { content: RealtimeTrajectoryResponse[] })} onMessage Function called on each message of the channel.
+     * @param {function} onError Callback when the subscription fails.
+     * @param {boolean} [quiet=false] If true avoid to store the subscription in the subscriptions list.
+     * @public
+     */
+    subscribeTrajectory(mode: RealtimeMode, onMessage: WebSocketAPIMessageCallback<RealtimeTrajectoryResponse[] | RealtimeTrajectoryResponse>, onError?: EventListener, quiet?: boolean): void;
+    /**
+     * Unsubscribe to trajectory channels.
+     * @param {function(data: { content: RealtimeTrajectoryResponse[] })} onMessage Callback function to unsubscribe. If null all subscriptions for the channel will be unsubscribed.
+     * @public
+     */
+    unsubscribeTrajectory(onMessage: WebSocketAPIMessageCallback<RealtimeTrajectoryResponse[]>): void;
+    /**
+     * Subscribe to deleted_vhicles channel.
+     *
+     * @param {RealtimeMode} mode Realtime mode.
+     * @param {function(data: { content: RealtimeTrainId })} onMessage Callback function to unsubscribe. If null all subscriptions for the channel will be unsubscribed.
+     * @param {function} onError Callback when the subscription fails.
+     * @param {boolean} [quiet=false] If true avoid to store the subscription in the subscriptions list.
+     */
+    subscribeDeletedVehicles(mode: RealtimeMode, onMessage: WebSocketAPIMessageCallback<RealtimeTrainId>, onError?: EventListener, quiet?: boolean): void;
+    /**
+     * Unsubscribe to deleted_vhicles channels.
+     * @param {function(data: { content: RealtimeTrainId })} onMessage Callback function to unsubscribe. If null all subscriptions for the channel will be unsubscribed.
+     */
+    unsubscribeDeletedVehicles(onMessage: WebSocketAPIMessageCallback<RealtimeTrainId>): void;
+    /**
+     * Get a full trajectory of a vehicule .
+     *
+     * @param {string} id A vehicle id.
+     * @param {RealtimeMode} mode Realtime mode.
+     * @param {string} generalizationLevel The generalization level to request. Can be one of 5 (more generalized), 10, 30, 100, undefined (less generalized).
+     * @return {Promise<{ data: { content: RealtimeFullTrajectory } }>} Return a full trajectory.
+     * @public
+     */
+    getFullTrajectory(id: RealtimeTrainId, mode: RealtimeMode, generalizationLevel: RealtimeGeneralizationLevel | undefined): Promise<WebSocketAPIMessageEventData<RealtimeFullTrajectory>>;
+    /**
+     * Subscribe to full_trajectory channel of a given vehicle.
+     *
+     * @param {string} id A vehicle id.
+     * @param {RealtimeMode} mode Realtime mode.
+     * @param {function(data: { content: RealtimeFullTrajectory })} onMessage Function called on each message of the channel.
+     * @param {function} onError Callback when the subscription fails.
+     * @param {boolean} [quiet=false] If true avoid to store the subscription in the subscriptions list.
+     * @public
+     */
+    subscribeFullTrajectory(id: RealtimeTrainId, mode: RealtimeMode, onMessage: WebSocketAPIMessageCallback<RealtimeFullTrajectory>, onError?: EventListener, quiet?: boolean): void;
+    /**
+     * Unsubscribe from full_trajectory channel
+     *
+     * @param {string} id A vehicle id.
+     * @param {function(data: { content: RealtimeFullTrajectory })} onMessage Callback function to unsubscribe. If null all subscriptions for the channel will be unsubscribed.
+     * @public
+     */
+    unsubscribeFullTrajectory(id: RealtimeTrainId, onMessage?: WebSocketAPIMessageCallback<RealtimeFullTrajectory>): void;
+    /**
+     * Get the list of stops for this vehicle.
+     *
+     * @param {string} id A vehicle id.
+     * @return {Promise<{ data: { content: StopSequence[] } }>} Returns a stop sequence object.
+     * @public
+     */
+    getStopSequence(id: RealtimeTrainId): Promise<WebSocketAPIMessageEventData<StopSequence[]>>;
+    /**
+     * Subscribe to stopsequence channel of a given vehicle.
+     *
+     * @param {string} id A vehicle id.
+     * @param {function(data: { content: StopSequence[] })} onMessage Function called on each message of the channel.
+     * @param {function} onError Callback when the subscription fails.
+     * @param {boolean} [quiet=false] If true avoid to store the subscription in the subscriptions list.
+     * @public
+     */
+    subscribeStopSequence(id: RealtimeTrainId, onMessage: WebSocketAPIMessageCallback<StopSequence[]>, onError?: EventListener, quiet?: boolean): void;
+    /**
+     * Unsubscribe from stopsequence channel
+     *
+     * @param {string} id A vehicle id.
+     * @param {function(data: { content: StopSequence[] })} onMessage Callback function to unsubscribe. If null all subscriptions for the channel will be unsubscribed.
+     * @public
+     */
+    unsubscribeStopSequence(id: RealtimeTrainId, onMessage?: WebSocketAPIMessageCallback<StopSequence[]>): void;
+    /**
+     * Subscribe to healthcheck channel.
+     * @param {function(data: { content: string })} onMessage Callback when the subscribe to healthcheck channel succeeds.
+     * @param {function} onError Callback when the subscription fails.
+     * @param {boolean} [quiet=false] If true avoid to store the subscription in the subscriptions list.
+     */
+    subscribeHealthCheck(onMessage: WebSocketAPIMessageCallback<string>, onError?: EventListener, quiet?: boolean): void;
+    /**
+     * Unsubscribe to healthcheck channel.
+     * @param {function(data: { content: string })} onMessage Callback function to unsubscribe. If null all subscriptions for the channel will be unsubscribed.
+     */
+    unsubscribeHealthCheck(onMessage?: WebSocketAPIMessageCallback<string>): void;
+}
+export default RealtimeAPI;