American Airlines Flight Engine

by abertsch72

GitHub Readme.md

Flight Engine

Mock flight data delivered simply and quickly without a database.

Deploy

Running the App Locally

First, make sure you have Node.js and npm then install project dependencies by running npm install.

After dependencies have been installed, run npm run dev, which will perform the following actions:

  • Transpile TS into dist from src
  • Start the application
  • Watch src for changes, and transpile into dist again after observed changes
  • Watch dist for changes and restart the application after observed changes

Once the app has started, try hitting localhost:3030 (3030 is the default port unless overridden from .env) from a browser.

Randomization via a Seed Value

In order to keep the app lightweight and eliminate the need for a database, this project uses seed randomization (credit to @JohnKahn for the amazing idea!). If you don't care about the way data is generated, just read the first two bullets below and skip the rest.

Here are some important things to note if you plan to modify the random data generation:

  • After a Generator is initialized with a seed, the random method will generate random data each time it is called, however, this data generation is deterministic...
  • Because this method of random generation is deterministic, the order and value of the "random" value sets generated by multiple calls to random for a given seed will always be the same
    • That was a lot... let's say we have generatorA and generatorB and each have been initialized with a seed value of RANDOMIZATION_IS_COOL!. If we call the random method of each generator (e.g., A1 and B1), the result will be the same (A1 === B1). If, however, we call the random method again, the new values will again be the same (A2 === B2) but they should differ from the first set of values generated by each of the generators (A1 !== A2 && B1 !== B2).
  • Whenever a GET /flights call is performed, the app generates all flights for the specified date, regardless of the presence of origin and/or destination
    • If we only generate a subset of the data based on origin and/or destination, the order in which the flights generated for each O&D pair would differ and flight data would be different depending on the request parameters (e.g., flight 123 retrieved via/flights?date=2020-01-01 and /flights?date=2020-01-01&origin=DFW would differ). Here's an example:
      • random method calls 1-10 with a seed of 2020-01-01 will ALWAYS result in: [1, 7, 9, 1, 8, 4, 5, 7, 2, 3]
      • /flights?date=2020-01-01:
        1. Generate LGA flights (random calls 1-4)
        2. Generate MIA flights (random calls 6-7)
        3. Generate DFW flights (random calls 8-10), flight 123 was call 9 and got a random value of 2
      • /flights?date=2020-01-01?origin=DFW:
        1. Generate DFW flights (random calls 1-3), flight 123 was call 2 and got a random value of 7
      • Because the values are different, the data for flight 123 will not be the same for those two calls

Pulling in Additional Data

The src/DataCollection folder contains tools and data to augment the airport options. The parse_csv.py script takes the airports in airports.json and compares them with the Wikipedia page for American Airlines destinations. Only airports with American Airlines flights are included.

This data can be customized by changing the constants at the top of parse_csv.json. The ALLOWED_COUNTRIES list is the countries that airports can be in -- currently, this is set to only grab data from the United States. The MIN_DIRECT_FLIGHTS_PER_DAY is another way to narrow down the data by selecting only larger airports. The current value for this is 10, meaning that only airports that have more than 10 direct flights per day there are included.

This script is set up to produce output in the correct format for the typescript file airports.ts. When the script is run, the airports in that file are updated.

Dependencies

The python script uses the wikipedia package, a package for retrieving and parsing Wikipedia pages. Before the script can run, this package must be installed with

pip install wikipedia

Testing

This project utilizes framework uses Facebook's Jest framework for testing. Jest is based on the Jasmine framework. While some developers prefer Mocha, we've chosen to fully adopt Jest on top of Jasmine as-is until a significant need requires an alternative solution.

Writing a test is as simple as creating a *.test.ts file in the ./src directory along with an associated describe() and test() function.

Simply run npm run test to run tests.

Additional testing scripts:

  • test: runs all tests
  • test:changed: runs tests related to uncommited git changes only

Contributing

Interested in contributing to the project? Check out our Contributing Guidelines.