Cooper API

Documentation

Postman documentation

Installation

Run npm install.

Install neo4j, enter the web interface and set a new password. It has been tested only with the docker version of neo4j downloaded from the Kitematic app.

Important: Make sure that the variables in the .env file are properly set, because the docker version of neo4j doesn't use the default ports.

Same for redis. Or just download the docker image from Kitematic.

Copy .env.example to .env and change the settings as needed.

Start server

Run npm run build to transpile the code to javascript, run this before start.

Run npm run debug to start server in development mode with live reload.

Run npm test to run the tests.

Project Structure

The test folder remain top level as expected.

The full folder structure of this app is explained below:

Note! Make sure you have already built the app using npm run build before npm start.

Name	Description
.vscode	Contains VS Code specific settings
dist	Contains the distributable (or output) from your TypeScript build. This is the code you ship
node_modules	Contains all your npm dependencies
src	Contains your source code that will be compiled to the dist dir
src/config	Passport authentication strategies and login middleware. Add other complex config code here
src/controllers	Controllers define functions that respond to various http requests
src/models	Models define neo4js schemas that will be used in storing and retrieving data from Neo4j
src/public	Static assets that will be used client side
src/types	Holds .d.ts files not found on DefinitelyTyped. Covered more in this section
src/server.ts	Entry point to your express app
test	Contains your tests. Seperate from source because there is a different build process.
views	Views define how your app renders on the client. In this case we're using pug
.env.example	API keys, tokens, passwords, database URI. Clone this, but don't check it in to public repos.
.travis.yml	Used to configure Travis CI build
jest.config.js	Used to configure Jest
package.json	File that contains npm dependencies as well as build scripts
tsconfig.json	Config settings for compiling server code written in TypeScript
tsconfig.tests.json	Config settings for compiling tests written in TypeScript
tslint.json	Config settings for TSLint code style checking

Building the project

If you're concerned about compile time, the main watch task takes ~2s to refresh.

Configuring TypeScript compilation

TypeScript uses the file tsconfig.json to adjust project compile options. Let's dissect this project's tsconfig.json, starting with the compilerOptions which details how your project is compiled.

    "compilerOptions": {
        "module": "commonjs",
        "target": "es6",
        "noImplicitAny": true,
        "moduleResolution": "node",
        "sourceMap": true,
        "outDir": "dist",
        "baseUrl": ".",
        "paths": {
            "*": [
                "node_modules/*",
                "src/types/*"
            ]
        }
    },

compilerOptions	Description
"module": "commonjs"	The output module type (in your .js files). Node uses commonjs, so that is what we use
"target": "es6"	The output language level. Node supports ES6, so we can target that here
"noImplicitAny": true	Enables a stricter setting which throws errors when something has a default any value
"moduleResolution": "node"	TypeScript attempts to mimic Node's module resolution strategy. Read more here
"sourceMap": true	We want source maps to be output along side our JavaScript. See the debugging section
"outDir": "dist"	Location to output .js files after compilation
"baseUrl": "."	Part of configuring module resolution. See path mapping section
paths: {...}	Part of configuring module resolution. See path mapping section

The rest of the file define the TypeScript project context. This project is fairly simple and all of our .ts files are under the src folder.

Running the build

All the different build steps are orchestrated via npm scripts. Npm scripts basically allow us to call (and chain) terminal commands via npm.

If you open package.json, you will see a scripts section with all the different scripts you can call. To call a script, simply run npm run <script-name> from the command line.

Below is a list of all the scripts available:

Npm Script	Description
start	Does the same as 'npm run serve'. Can be invoked with npm start
build	Full build. Runs ALL build tasks (build-sass, build-ts, tslint, copy-static-assets)
serve	Runs node on dist/server.js which is the apps entry point
watch	Runs all watch tasks (TypeScript, Sass, Node). Use this if you're not touching static assets.
test	Runs tests using Jest test runner
build-ts	Compiles all source .ts files to .js files in the dist folder
watch-ts	Same as build-ts but continuously watches .ts files and re-compiles when needed
build-sass	Compiles all .scss files to .css files
watch-sass	Same as build-sass but continuously watches .scss files and re-compiles when needed
tslint	Runs TSLint on project files