hk-bus-eta 1.9.3 → 2.0.0

package/README.md

@@ -1,4 +1,118 @@
 # HK Bus ETA
-  
-It's a npm package for querying bus ETA (Estimated Time of Arrival) in Hong Kong. The ETA data structure is based on [hkbus/hk-bus-crawling](https://github.com/hkbus/hk-bus-crawling) and a live demo is in [chunlaw/hk-independent-bus-eta](https://chunlaw.github.io/hk-independent-bus-eta).
 
+Bus ETAs in Hong Kong is now available as open data in Hong Kong, while there is no format normalization across different transport provider.  This package is a js package (typescript supported) for querying normalized public traffic ETA (Estimated Time of Arrival) in Hong Kong. The ETA data structure is based on [hkbus/hk-bus-crawling](https://github.com/hkbus/hk-bus-crawling) and a well-established open-source project is known as [hkbus.app](https://hkbus.app/).
+
+## Demo
+
+Live demo is available [here](https://hk-bus-eta.chunlaw.io/).
+
+## Install
+
+`npm install hk-bus-eta`
+or 
+`yarn add hk-bus-eta`
+
+
+## Usage
+
+__Crawling traffic database:__
+```ts
+import { fetchEtaObj } from "hk-bus-eta";
+import type { BusDb } from "hk-bus-eta";
+
+fetchEtaDb().then((db: BusDb) => {
+  console.log(db)
+})
+```
+
+__Crawling ETA__
+```ts
+import { fetchEtas } from "hk-bus-eta";
+import tyep { Eta } from "hk-bus-eta";
+
+// busDb is the BusDb object fetched by fetchEtaObj
+
+fetchEtas({
+  ...busDb.routeList["1+1+CHUK YUEN ESTATE+STAR FERRY"],
+  seq: 0,
+  language: "en",
+}).then(etas => {
+  console.log(etas)
+})
+```
+
+## Data Structure
+The data structure of _EtaDb_ is as follows:
+```ts
+{
+    holidays: string[];
+    routeList: {
+        [routeId: string]: {
+            route: string,
+            co: Company[],
+            orig: {
+                en: string,
+                zh: string
+            },
+            dest: {
+                en: string,
+                zh: string
+            },
+            fares: string[] | null,
+            faresHoliday: string[] | null,
+            freq: {
+                [type: string]: {
+                    [startTime: string]: [string, string] | null
+                }
+            } | null,
+            jt: string | null,
+            seq: number,
+            serviceType: string,
+            stops: {
+                [company: string]: string[]
+            },
+            bound: {
+                [company: string]: "O" | "I" | "OI" | "IO"
+            },
+            gtfsId: string,
+            nlbId: string
+        }
+    }
+    stopList: {
+        [stopId: string]: {
+            location: {
+                lat: number,
+                lng: number,
+            },
+            name: {
+                en: string,
+                zh: string
+            }
+        }
+    }
+    stopMap: {
+        [stopId: string]: Array<{
+          [company: string]: string  
+        }>
+    }
+}
+```
+
+The data structure of _Eta_ is as follows:
+```ts
+{
+  eta: string,
+  remark: {
+    zh: string,
+    en: string
+  },
+  co: string
+}
+```
+
+## Contribute
+Project owner [chunlaw](https://github.com/chunlaw) is the initiator of the whole project. Everyone is welcome to contribute. 
+
+## License
+
+GPL-3.0 license

package/index.d.ts

@@ -1,4 +1,4 @@
-export type Company = "kmb" | "nlb" | "ctb" |  "nwfb" | 'lrtfeeder' | 'gmb' | 'lightRail' | 'mtr'
+export type Company = "kmb" | "nlb" | "ctb" | 'lrtfeeder' | 'gmb' | 'lightRail' | 'mtr'
 
 export type Terminal = {
   en: string,
@@ -55,7 +55,7 @@ export type StopList = Record<string, StopListEntry>
 
 export type StopMap = Record<string, StopTuple[]>
 
-export type BusDb = {
+export type EtaDb = {
   holidays: string[],
   routeList: RouteList,
   stopList: StopList,
@@ -73,6 +73,6 @@ export type Eta = {
 
 export declare function fetchEtas(route: RouteListEntry & {seq: number, language: "zh" | "en"}): Promise<Eta[]>
 
-export declare function fetchEtaObj(): Promise<BusDb>
+export declare function fetchEtaDb(): Promise<EtaDb>
 
-export declare function fetchEtaObjMd5(): Promise<string>
+export declare function fetchEtaDbMd5(): Promise<string>

package/index.js

@@ -44,6 +44,6 @@ module.exports = {
       return []
     }
   },
-  fetchEtaObj: () => fetch("https://hkbus.github.io/hk-bus-crawling/routeFareList.min.json").then(r => r.json()),
-  fetchEtaObjMd5: () => fetch('https://hkbus.github.io/hk-bus-crawling/routeFareList.md5').then(r => r.text())
+  fetchEtaDb: () => fetch("https://hkbus.github.io/hk-bus-crawling/routeFareList.min.json").then(r => r.json()),
+  fetchEtaDbMd5: () => fetch('https://hkbus.github.io/hk-bus-crawling/routeFareList.md5').then(r => r.text())
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "hk-bus-eta",
-  "version": "1.9.3",
-  "description": "Query the ETA (Estimated Time of Arrival) of HK Bus/Minibus/Lightrail",
+  "version": "2.0.0",
+  "description": "Query the ETA (Estimated Time of Arrival) of HK Bus/Minibus/MTR/Lightrail",
   "main": "index.js",
   "scripts": {
     "test": "node test.js"