amtrak - npm Package Compare versions

Comparing version 3.0.4 to 3.0.5

package.json

 {
 	"name": "amtrak",
-	"version": "3.0.4",
+	"version": "3.0.5",
 	"description": "A simple and easy way to parse data from Amtrak's train tracking API.",
@@ -5,0 +5,0 @@ "main": "dist/index.js",

readme.md

 # Amtrak.js
 
-[![Amtrak.js - Unofficial Amtrak Library - The easiest way to track Amtrak Trains Programmatically! | Product Hunt](https://api.producthunt.com/widgets/embed-image/v1/featured.svg?post_id=312322&theme=dark&e=.svg)](https://www.producthunt.com/posts/amtrak-js-unofficial-amtrak-library?utm_source=badge-featured&utm_medium=badge&utm_souce=badge-amtrak-js-unofficial-amtrak-library)
-
 ## Disclaimer
@@ -51,2 +49,3 @@
   value is a list of `Train` objects.
+- Associated endpoint: `https://api-v3.amtraker.com/v3/trains`
 
@@ -59,3 +58,2 @@ #### Example
 
-
 // JS
@@ -67,3 +65,5 @@ fetchAllTrains().then((trains) => {
 // TS
-
+fetchAllTrains().then((trains: TrainResponse) => {
+  console.log(trains);
+});
 ```
@@ -83,3 +83,21 @@
     02/09/2023 would have an ID of `5-9`;
+- Associated endpoint: `https://api-v3.amtraker.com/v3/trains/:trainId`
 
+#### Example
+
+```ts
+const { fetchTrain } = require("amtrak"); // CommonJS
+import { fetchTrain } from "amtrak"; // ES6
+
+// JS
+fetchTrain("5-9").then((train) => {
+  console.log(train);
+});
+
+// TS
+fetchTrain("5-9").then((train: TrainResponse) => {
+  console.log(train);
+});
+```
+
 ### `fetchAllStations()`
@@ -90,3 +108,21 @@
   value is a `StationMeta` object.
+- Associated endpoint: `https://api-v3.amtraker.com/v3/stations`
 
+#### Example
+
+```ts
+const { fetchAllStations } = require("amtrak"); // CommonJS
+import { fetchAllStations } from "amtrak"; // ES6
+
+// JS
+fetchAllStations().then((stations) => {
+  console.log(stations);
+});
+
+// TS
+fetchAllStations().then((stations: StationResponse) => {
+  console.log(stations);
+});
+```
+
 ### `fetchStation(stationId: string)`
@@ -98,3 +134,21 @@
 - If the station ID is not found, the promise will resolve with an empty object.
+- Associated endpoint: `https://api-v3.amtraker.com/v3/stations/:stationId`
 
+#### Example
+
+```ts
+const { fetchStation } = require("amtrak"); // CommonJS
+import { fetchStation } from "amtrak"; // ES6
+
+// JS
+fetchStation("CHI").then((station) => {
+  console.log(station);
+});
+
+// TS
+fetchStation("CHI").then((station: StationResponse) => {
+  console.log(station);
+});
+```
+
 ### `fetchStaleStatus()`
@@ -104,1 +158,136 @@
 - Returns `Promise<StaleStatusResponse>`.
+- Associated endpoint: `https://api-v3.amtraker.com/v3/stale`
+
+#### Example
+
+```ts
+const { fetchStaleStatus } = require("amtrak"); // CommonJS
+import { fetchStaleStatus } from "amtrak"; // ES6
+
+// JS
+fetchStaleStatus().then((status) => {
+  console.log(status);
+});
+
+// TS
+fetchStaleStatus().then((status: StaleStatusResponse) => {
+  console.log(status);
+});
+```
+
+## Types
+
+There are a handful of types that are used throughout the library. Below is a
+list:
+
+### Train
+
+```ts
+interface Train {
+  routeName: string; // Name of the train route
+  trainNum: number; // Train number
+  trainID: string; // Train ID
+  lat: number; // Latitude of the train
+  lon: number; // Longitude of the train
+  trainTimely: string; // On time/early/late status of the train in plain english
+  stations: Station[]; // List of stations the train has and will pass through
+  heading: string; // Direction the train is heading in the 8 cardinal directions
+  eventCode: string; // Upcoming/current station
+  eventTZ: string; // Timezone of the upcoming/current station
+  eventName: string; // Name of the upcoming/current station
+  origCode: string; // Origin station code
+  originTZ: string; // Timezone of the origin station
+  origName: string; // Name of the origin station
+  destCode: string; // Destination station code
+  destTZ: string; // Timezone of the destination station
+  destName: string; // Name of the destination station
+  trainState: string; // Either "Predeparture" or "Active"
+  velocity: number; // Speed of the train in MPH
+  statusMsg: string; // Status message associated with the train, if any
+  createdAt: string; // Timestamp of when the train data was stored in Amtrak's DB
+  updatedAt: string; // Timestamp of when the train data was last updated
+  lastValTS: string; // Timestamp of when the train data was last received
+  objectID: number; // ID of the train data in Amtrak's DB
+}
+```
+
+### Station
+
+```ts
+interface Station {
+  name: string; // Name of the station in plain english
+  code: string; // Station code
+  tz: string; // Timezone of the station
+  bus: boolean; // Whether or not the station is a bus stop, always false
+  schArr: string; // Scheduled arrival time
+  schDep: string; // Scheduled departure time
+  arr: string; // Actual arrival time
+  dep: string; // Actual departure time
+  arrCmnt: string; // Arrival timeliness comment
+  depCmnt: string; // Departure timeliness comment
+  status: string; // One of "Enroute", "Station", "Departed", or "Unknown"
+}
+```
+
+### StationMeta
+
+```ts
+interface StationMeta {
+  name: string; // Name of the station in plain english
+  code: string; // Station code
+  tz: string; // Timezone of the station
+  lat: number; // Latitude of the station
+  lon: number; // Longitude of the station
+  address1: string; // Address line 1 of the station
+  address2: string; // Address line 2 of the station, *usually* empty
+  city: string; // City of the station
+  state: string; // State of the station
+  zip: number; // Zip code of the station
+  trains: string[]; // List of train IDs that pass through the station
+}
+```
+
+### TrainResponse
+
+```ts
+interface TrainResponse {
+  [key: string]: Train[];
+}
+```
+
+### StationResponse
+
+```ts
+interface StationResponse {
+  [key: string]: StationMeta;
+}
+```
+
+### StaleData
+
+```ts
+interface StaleData {
+  avgLastUpdate: number; // Average time in milliseconds since train data was last updated in Amtrak's database
+  activeTrains: number; // Number of trains that are currently active
+  stale: boolean; // Whether or not the data is stale
+}
+```
+
+## Endpoints
+
+As mentioned above in the [Functions](#functions) section, each function is
+associated with an endpoint. Below is a list of all endpoints used by the
+library, where the associated function returns the same data as the endpoint,
+allowing you to use the library with your own HTTP client.
+
+- `https://api-v3.amtraker.com/v3/trains`
+  - Associted with [`fetchAllTrains()`](#fetchAllTrains)
+- `https://api-v3.amtraker.com/v3/trains/:trainId`
+  - Associted with [`fetchTrain(trainId: string)`](#fetchTraintrainId-string)
+- `https://api-v3.amtraker.com/v3/stations`
+  - Associted with [`fetchAllStations()`](#fetchAllStations)
+- `https://api-v3.amtraker.com/v3/stations/:stationId`
+  - Associted with
+    [`fetchStation(stationId: string)`](#fetchStationstationId-string)
+- `https://api-v3.amtraker.com/v3/stale`
+  - Associted with [`fetchStaleStatus()`](#fetchStaleStatus)

src/types.ts

@@ -9,3 +9,3 @@ export interface Train {
   stations: Station[];
-  heading: Heading;
+  heading: string;
   eventCode: string;
@@ -20,3 +20,3 @@ eventTZ: string[];
   destName: string;
-  trainState: TrainState;
+  trainState: string;
   velocity: number;
@@ -57,3 +57,3 @@ statusMsg: string;
   depCmnt: string;
-  status: StationStatus;
+  status: string;
 }
@@ -60,0 +60,0 @@

No alert changes

Improved metrics

Total package byte prevSize

62287

increased by9.55%

Number of lines in readme file

287

increased by192.86%

No dependency changes