gtfs-realtime-bindings 0.0.6 → 1.1.0

package/Dockerfile

@@ -0,0 +1,8 @@
+FROM node:18.12.1-alpine
+
+WORKDIR /lib
+COPY nodejs/package.json /lib/package.json
+COPY nodejs/package-lock.json /lib/package-lock.json
+COPY gtfs-realtime.proto /gtfs-realtime.proto
+RUN npm ci
+RUN npm run buildProto

package/README.md

@@ -1,57 +1,78 @@
-# JavaScript GTFS-realtime Language Bindings
-
-[![npm version](https://badge.fury.io/js/gtfs-realtime-bindings.svg)](http://badge.fury.io/js/gtfs-realtime-bindings)
-
-Provides JavaScript classes generated from the
-[GTFS-realtime](https://github.com/google/transit/tree/master/gtfs-realtime) Protocol
-Buffer specification.  These classes will allow you to parse a binary Protocol
-Buffer GTFS-realtime data feed into JavaScript objects.
-
-These bindings are designed to be used in the [Node.js](http://nodejs.org/)
-environment, but with some effort, they can probably be used in other
-JavaScript environments as well.
-
-We use the [ProtBuf.js](https://github.com/dcodeIO/ProtoBuf.js) library for
-JavaScript Protocol Buffer support.
-
-## Add the Dependency
-
-To use the `gtfs-realtime-bindings` classes in your own project, you need to
-first install our [Node.js npm package](https://www.npmjs.com/package/gtfs-realtime-bindings):
-
-```
-npm install gtfs-realtime-bindings
-```
-
-## Example Code
-
-The following Node.js code snippet demonstrates downloading a GTFS-realtime
-data feed from a particular URL, parsing it as a FeedMessage (the root type of
-the GTFS-realtime schema), and iterating over the results.
-
-```javascript
-var GtfsRealtimeBindings = require('gtfs-realtime-bindings');
-var request = require('request');
-
-var requestSettings = {
-  method: 'GET',
-  url: 'URL OF YOUR GTFS-REALTIME SOURCE GOES HERE',
-  encoding: null
-};
-request(requestSettings, function (error, response, body) {
-  if (!error && response.statusCode == 200) {
-    var feed = GtfsRealtimeBindings.transit_realtime.FeedMessage.decode(body);
-    feed.entity.forEach(function(entity) {
-      if (entity.trip_update) {
-        console.log(entity.trip_update);
-      }
-    });
-  }
-});
-```
-
-For more details on the naming conventions for the Javascript classes generated
-from the
-[gtfs-realtime.proto](https://github.com/google/transit/blob/master/gtfs-realtime/proto/gtfs-realtime.proto),
-check out the [ProtoBuf.js project](https://github.com/dcodeIO/ProtoBuf.js/wiki)
-which we use to handle our Protocol Buffer serialization.
+# JavaScript GTFS-realtime Language Bindings
+
+[![npm version](https://badge.fury.io/js/gtfs-realtime-bindings.svg)](http://badge.fury.io/js/gtfs-realtime-bindings)
+
+Provides JavaScript classes and their associated types generated from the
+[GTFS-realtime](https://github.com/google/transit/tree/master/gtfs-realtime) Protocol
+Buffer specification.  These classes will allow you to parse a binary Protocol
+Buffer GTFS-realtime data feed into JavaScript objects.
+
+These bindings are designed to be used in the [Node.js](http://nodejs.org/)
+environment, but with some effort, they can probably be used in other
+JavaScript environments as well.
+
+We use the [ProtoBuf.js](https://github.com/dcodeIO/ProtoBuf.js) library for
+JavaScript Protocol Buffer support.
+
+## Add the Dependency
+
+To use the `gtfs-realtime-bindings` classes in your own project, you need to
+first install our [Node.js npm package](https://www.npmjs.com/package/gtfs-realtime-bindings):
+
+```
+npm install gtfs-realtime-bindings
+```
+
+## Example Code
+
+The following Node.js code snippet demonstrates downloading a GTFS-realtime
+data feed from a particular URL, parsing it as a FeedMessage (the root type of
+the GTFS-realtime schema), and iterating over the results.
+
+In order to make this example work, you must first install `node-fetch` with NPM.
+
+_Note: this exemple is using ES modules (`import`/`export` syntax) and is not compatible
+with CommonJS (`require` syntax). You can use CommonJS by converting `import` to `require`
+and installing `node-fetch@2`. Learn more about ES modules [here](https://nodejs.org/api/esm.html)._
+
+```javascript
+import GtfsRealtimeBindings from "gtfs-realtime-bindings";
+import fetch from "node-fetch";
+
+(async () => {
+  try {
+    const response = await fetch("<GTFS-realtime source URL>", {
+      headers: {
+        "x-api-key": "<redacted>",
+        // replace with your GTFS-realtime source's auth token
+        // e.g. x-api-key is the header value used for NY's MTA GTFS APIs
+      },
+    });
+    if (!res.ok) {
+      const error = new Error(`${res.url}: ${res.status} ${res.statusText}`);
+      error.response = res;
+      throw error;
+      process.exit(1);
+    }
+    const buffer = await response.arrayBuffer();
+    const feed = GtfsRealtimeBindings.transit_realtime.FeedMessage.decode(
+      new Uint8Array(buffer)
+    );
+    feed.entity.forEach((entity) => {
+      if (entity.tripUpdate) {
+        console.log(entity.tripUpdate);
+      }
+    });
+  }
+  catch (error) {
+    console.log(error);
+    process.exit(1);
+  }
+})();
+```
+
+For more details on the naming conventions for the JavaScript classes generated
+from the
+[gtfs-realtime.proto](https://github.com/google/transit/blob/master/gtfs-realtime/proto/gtfs-realtime.proto),
+check out the [ProtoBuf.js project](https://github.com/dcodeIO/ProtoBuf.js/wiki)
+which we use to handle our Protocol Buffer serialization.

package/UPDATING.md

@@ -1,43 +1,53 @@
-# How-To Update Bindings When gtfs-realtime.proto Changes
-
-## Regenerate the language binding source from gtfs-realtime.proto.
-
-#### One-Time Setup
-
-1. Download and install [Node.js](https://www.npmjs.com/get-npm) (v10.15.2 LTS has been used)
-
-#### Every time `gtfs-realtime.proto` changes
-
-1. Run `npm install` from the `nodejs` folder to install the protobuf package
-
-1. Regenerate the language binding source from gtfs-realtime.proto by running the following from the `nodejs` folder:
-
-    ```
-    npm run buildProto
-    ```
-
-1. Add the license header back to the generated source file.
-
-1. Test the generated code:
-
-    ```
-    npm run test
-    ```
-
-1. Update the version number in `package.json`.
-
-## Publishing a new release
-
-#### Every release
-
-Log in with your account on NPM that has permissions for https://www.npmjs.com/package/gtfs-realtime-bindings:
-
-```
-npm login
-```
-
-Publish the package to NPM:
-
-```
-npm publish
-```
+# How-To Update Bindings When gtfs-realtime.proto Changes
+
+## Regenerate the language binding source from gtfs-realtime.proto.
+
+#### One-Time Setup
+
+1. Download and install [Docker](https://docs.docker.com/get-docker/)
+
+#### Every time node package dependencies change
+
+1. Download and install [Node.js](https://www.npmjs.com/get-npm) (check the `package.json` for `engines` version).
+
+1. Edit the dependency versions in using `npm install` and/or `npm remove`.
+
+1. Re-generate the code by following instructions below.
+
+#### Re-generating the code
+
+1. Run the following from the project root folder:
+
+    ```
+    docker build -t gtfs-nodejs -f nodejs/Dockerfile .
+    # -it to make sure docker run can be killed with ctrl-c
+    # -t uses TTY, which causes linux to include carriage returns, which are stripped using tr
+    docker run -it --rm gtfs-nodejs cat /lib/gtfs-realtime.js | tr -d '\r' > nodejs/gtfs-realtime.js
+    docker run -it --rm gtfs-nodejs cat /lib/gtfs-realtime.d.ts | tr -d '\r' > nodejs/gtfs-realtime.d.ts
+    ```
+
+1. Add the license header back to the generated source file.
+
+1. Test the generated code:
+
+    ```
+    npm run test
+    ```
+
+1. Update the version number in `package.json`.
+
+## Publishing a new release
+
+#### Every release
+
+Log in with your account on NPM that has permissions for https://www.npmjs.com/package/gtfs-realtime-bindings:
+
+```
+npm login
+```
+
+Publish the package to NPM:
+
+```
+npm publish
+```