mobility-toolbox-js 3.0.0-beta.8 → 3.0.0

package/README.md

@@ -10,7 +10,7 @@ The tools in this library have been inspired by many projects realized for publi
 
 ## Documentation and examples
 
-Visit https://mobility-toolbox-js.vercel.app/
+Visit https://mobility-toolbox-js.geops.io/
 
 ## Demos
 
@@ -24,7 +24,7 @@ Visit https://mobility-toolbox-js.vercel.app/
 Install the library and the peer dependencies:
 
 ```bash
-yarn add mobility-toolbox-js ol maplibre-gl
+yarn add ol maplibre-gl mobility-toolbox-js
 ```
 
 ## Development
@@ -34,9 +34,17 @@ yarn install
 yarn dev
 ```
 
+`yarn dev` starts a vite server using the `index.html` file at the root of the project.
+This html file loads the `dev.js` file. Use this file to develop the library.
+Each time you modifiy the library code you have to run `yarn build:tsc` to see the changes.
+
+## Development documentation
+
+The documentations website is located in the `doc/`  folder.
+It's a nextJS website that use the mobility-toolbox-js library built from the `build/` folder.
+
 ## 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 interface HttpAPIOptions {
+    apiKey?: string;
+    url: string;
+}
+/**
+ * Common class to access to a geOps api using http.
+ * @private
+ */
+declare class HttpAPI {
+    apiKey?: string;
+    url: 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,24 +10,11 @@ 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 {
     constructor(options) {
-        /** @private */
         this.url = options.url;
-        /** @private */
         this.apiKey = options.apiKey;
     }
     /**
@@ -40,7 +27,7 @@ class HttpAPI {
             if (!this.url) {
                 throw new Error(`No url defined for request to ${this.url}/${path}`);
             }
-            if (!this.url && !this.apiKey && !/key=/.test(this.url)) {
+            if (!this.url && !this.apiKey && !this.url.includes('key=')) {
                 // eslint-disable-next-line no-console
                 throw new Error(`No apiKey defined for request to ${this.url}`);
             }

package/api/RealtimeAPI.d.ts

@@ -0,0 +1,404 @@
+import WebSocketAPI, { WebSocketAPIMessageCallback, WebSocketAPIMessageEventData, WebSocketAPIParameters } from './WebSocketAPI';
+import type { RealtimeBbox, RealtimeDeparture, RealtimeExtraGeom, RealtimeFullTrajectory, RealtimeGeneralizationLevel, RealtimeMode, RealtimeNews, RealtimeStation, RealtimeStationId, RealtimeStopSequence, RealtimeTenant, RealtimeTrainId, RealtimeTrajectory, RealtimeVersion } from '../types';
+/**
+ * @typedef RealtimeAPIOptions
+ */
+export interface RealtimeAPIOptions {
+    apiKey?: string;
+    bbox?: RealtimeBbox;
+    buffer?: number[];
+    pingIntervalMs?: number;
+    reconnectTimeoutMs?: number;
+    url?: string;
+    version?: RealtimeVersion;
+}
+export type RealtimeAPIExtraGeomsById = Record<string, RealtimeExtraGeom>;
+export type RealtimeAPIDeparturesById = Record<string, RealtimeDeparture>;
+export interface RealtimeModesType {
+    RAW: RealtimeMode;
+    SCHEMATIC: RealtimeMode;
+    TOPOGRAPHIC: 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;
+    SCHEMATIC: RealtimeMode;
+    TOPOGRAPHIC: 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 {
+    _bbox?: RealtimeBbox;
+    _buffer?: number[];
+    _url: string;
+    version: RealtimeVersion;
+    wsApi: WebSocketAPI;
+    /**
+     * This callback type is called `requestCallback` and is displayed as a global symbol.
+     *
+     * @callback onFullTrajectoryMessageCallback
+     * @param {number} responseCode
+     * @param {string} responseMessage
+     */
+    /**
+     * The bounding box to receive data from.\
+     * Example: [minX, minY, maxX, maxY, zoom, mots , gen_level, tenant, ...]\
+     * &nbsp;\
+     * Where:
+     * - **minX**: a string representation of an integer (not a float) representing the minimal X coordinate (in EPSG:3857) of a bounding box\
+     * &nbsp;
+     * - **minY**: a string representation of an integer (not a float) representing the minimal Y coordinate (in EPSG:3857) of a bounding box\
+     * &nbsp;
+     * - **maxX**: a string representation of an integer (not a float) representing the maximal X coordinate (in EPSG:3857) of a bounding box\
+     * &nbsp;
+     * - **maxY**: a string representation of an integer (not a float) representing the maximal Y coordinate (in EPSG:3857) of a bounding box\
+     * &nbsp;
+     * - **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);
+    get buffer(): number[] | undefined;
+    set buffer(newBuffer: number[] | undefined);
+    get url(): string;
+    set url(newUrl: string);
+    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);
+    /**
+     * Close the websocket connection without reconnection.
+     *
+     * @public
+     */
+    close(): 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.
+     * @public
+     */
+    get(channelOrParams: string | WebSocketAPIParameters): Promise<WebSocketAPIMessageEventData<any>>;
+    /**
+     * 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>>;
+    /**
+     * 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[]>;
+    /**
+     * Get the list of stops for this vehicle.
+     *
+     * @param {string} id A vehicle id.
+     * @return {Promise<{data: { content: RealtimeStopSequence[] }}>} Returns a stop sequence object.
+     * @public
+     */
+    getStopSequence(id: RealtimeTrainId): Promise<WebSocketAPIMessageEventData<RealtimeStopSequence[]>>;
+    /**
+     * Return a partial trajectory with a given id and a mode.
+     *
+     * @param {number} id 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>>;
+    /**
+     * Callback when the websocket is closed by the server.
+     * It auto reconnects after a timeout.
+     * @private
+     */
+    onClose(): void;
+    /**
+     * Callback when the websocket is opened and ready.
+     * It applies the bbox and the projection.
+     * @private
+     */
+    onOpen(): void;
+    /**
+     * Open the websocket connection.
+     *
+     * @public
+     */
+    open(): void;
+    /**
+     * Unsubscribe trajectory and deleted_vehicles channels. To resubscribe you have to set a new BBOX.
+     */
+    reset(): void;
+    /**
+     * 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.
+     * @public
+     */
+    subscribe(channel: string, onSuccess: WebSocketAPIMessageCallback<any>, onError?: EventListener, quiet?: boolean): 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.
+     * @public
+     */
+    subscribeDeletedVehicles(mode: RealtimeMode, onMessage: WebSocketAPIMessageCallback<RealtimeTrainId>, onError?: EventListener, quiet?: boolean): void;
+    /**
+     * Subscribe to departures channel of a given station.
+     *
+     * @param {number} stationId UIC of the station.
+     * @param {function(departures: RealtimeDeparture[])} 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.
+     * @deprecated Use subscribeTimetable instead.
+     */
+    subscribeDepartures(stationId: number, onMessage: WebSocketAPIMessageCallback<RealtimeDeparture>, onError?: EventListener, quiet?: boolean): void;
+    /**
+     * Subscribe to the disruptions channel for tenant.
+     *
+     * @param {RealtimeTenant} tenant Tenant's id
+     * @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.
+     * @deprecated Use subscribeNewsticker instead.
+     */
+    subscribeDisruptions(tenant: RealtimeTenant, onMessage: WebSocketAPIMessageCallback<RealtimeNews>, onError?: EventListener, quiet?: boolean): 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;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * Subscribe to the newsticker channel for tenant.
+     *
+     * @param {RealtimeTenant} tenant Tenant's id
+     * @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
+     */
+    subscribeNewsticker(tenant: RealtimeTenant, onMessage: WebSocketAPIMessageCallback<RealtimeNews>, onError?: EventListener, quiet?: boolean): void;
+    /**
+     * 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;
+    /**
+     * Subscribe to stopsequence channel of a given vehicle.
+     *
+     * @param {string} id A vehicle id.
+     * @param {function(data: { content: RealtimeStopSequence[] })} 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<RealtimeStopSequence[]>, onError?: EventListener, quiet?: boolean): void;
+    /**
+     * Subscribe to timetable channel of a given station.
+     *
+     * @param {number} stationId UIC of the station.
+     * @param {function(departures: RealtimeDeparture[])} 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
+     */
+    subscribeTimetable(stationId: number, onMessage: WebSocketAPIMessageCallback<RealtimeDeparture>, onError?: EventListener, quiet?: boolean): void;
+    /**
+     * Subscribe to trajectory channel.
+     *
+     * @param {RealtimeMode} mode Realtime mode.
+     * @param {function(data: { content: RealtimeTrajectory })} 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<RealtimeTrajectory>, 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.
+     * @public
+     */
+    unsubscribe(channel: string, suffix?: string, onMessage?: WebSocketAPIMessageCallback<any>): 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.
+     * @public
+     */
+    unsubscribeDeletedVehicles(onMessage: WebSocketAPIMessageCallback<RealtimeTrainId>): void;
+    /**
+     * Unsubscribe from current departures channel.
+     * @param {number} stationId UIC of the station.
+     * @param {function(data: { content: RealtimeDeparture[] })} onMessage Callback function to unsubscribe. If null all subscriptions for the channel will be unsubscribed.
+     * @deprecated Use RealtimeAPI.unsubscribeTimetabe instead.
+     */
+    unsubscribeDepartures(stationId: RealtimeStationId, onMessage?: WebSocketAPIMessageCallback<RealtimeDeparture>): void;
+    /**
+     * Unsubscribe disruptions.
+     * @param {RealtimeTenant} tenant Tenant's id
+     * @param {Function(data: { content: RealtimeNews[] })} onMessage Callback function to unsubscribe. If null all subscriptions for the channel will be unsubscribed.
+     * @deprecated Use unsubscribeNewsticker instead.
+     */
+    unsubscribeDisruptions(tenant: RealtimeTenant, onMessage?: WebSocketAPIMessageCallback<RealtimeNews>): 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;
+    /**
+     * Unsubscribe from full_trajectory channel
+     *
+     * @param {string} id A vehicle id.
+     * @param {onFullTrajectoryMessageCallback} onMessage Callback function to unsubscribe. If null all subscriptions for the channel will be unsubscribed.
+     * @public
+     */
+    unsubscribeFullTrajectory(id: RealtimeTrainId, onMessage?: WebSocketAPIMessageCallback<RealtimeFullTrajectory>): 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;
+    /**
+     * Unsubscribe disruptions.
+     * @param {RealtimeTenant} tenant Tenant's id
+     * @param {Function(data: { content: RealtimeNews[] })} onMessage Callback function to unsubscribe. If null all subscriptions for the channel will be unsubscribed.
+     * @public
+     */
+    unsubscribeNewsticker(tenant: RealtimeTenant, onMessage?: WebSocketAPIMessageCallback<RealtimeNews>): 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;
+    /**
+     * Unsubscribe from stopsequence channel
+     *
+     * @param {string} id A vehicle id.
+     * @param {function(data: { content: RealtimeStopSequence[] })} onMessage Callback function to unsubscribe. If null all subscriptions for the channel will be unsubscribed.
+     * @public
+     */
+    unsubscribeStopSequence(id: RealtimeTrainId, onMessage?: WebSocketAPIMessageCallback<RealtimeStopSequence[]>): void;
+    /**
+     * Unsubscribe from current departures channel.
+     * @param {number} stationId UIC of the station.
+     * @param {function(data: { content: RealtimeDeparture[] })} onMessage Callback function to unsubscribe. If null all subscriptions for the channel will be unsubscribed.
+     * @public
+     */
+    unsubscribeTimetable(stationId: RealtimeStationId, onMessage?: WebSocketAPIMessageCallback<RealtimeDeparture>): void;
+    /**
+     * Unsubscribe to trajectory channels.
+     * @param {function(data: { content: RealtimeTrajectory })} onMessage Callback function to unsubscribe. If null all subscriptions for the channel will be unsubscribed.
+     * @public
+     */
+    unsubscribeTrajectory(onMessage: WebSocketAPIMessageCallback<RealtimeTrajectory>): void;
+}
+export default RealtimeAPI;