Merge branch 'master' into dockerfile-dumbinit

Author: fox1t

.dockerignore

@@ -17,6 +17,10 @@ coverage
 # nyc test coverage
 .nyc_output
 
+# TAP files
+out.tap
+junit-testresults.xml
+
 # Grunt intermediate storage (http://gruntjs.com/creating-plugins#storing-task-files)
 .grunt
 
@@ -28,7 +32,6 @@ node_modules
 jspm_packages
 # Compiled binary addons (http://nodejs.org/api/addons.html)
 build
-.nyc_output
 
 # Optional npm cache directory
 .npm

.vscode/launch.json

@@ -1,7 +1,4 @@
 {
-  // Use IntelliSense to learn about possible Node.js debug attributes.
-  // Hover to view descriptions of existing attributes.
-  // For more information, visit: https://go.microsoft.com/fwlink/?linkid=830387
   "version": "0.2.0",
   "configurations": [
     {

README.md

@@ -1,77 +1,144 @@
-# TypeScript Microservice Starter ![microlib](https://user-images.githubusercontent.com/6388707/58275504-7818c880-7d95-11e9-84af-f8aa50b93d5f.png)
+# ![Stampo](https://user-images.githubusercontent.com/6388707/58275504-7818c880-7d95-11e9-84af-f8aa50b93d5f.png) Stampo - TypeScript Microservice Starter
 
 [![styled with prettier](https://img.shields.io/badge/styled%20with-Prettier-blue.svg)](https://github.com/prettier/prettier)
 [![eslint](https://img.shields.io/badge/linted%20by-eslint-brightgreen.svg)](https://eslint.org)
-[![tested with tap](https://img.shields.io/badge/tested%20with-node--tap-yellow.svg)](https://github.com/tapjs/node-tap) ![Node Build](https://github.com/nucleode/typescript-microservice-starter/workflows/Node%20Build/badge.svg) ![Docker Build](https://github.com/nucleode/typescript-microservice-starter/workflows/Docker%20Build/badge.svg?branch=master)
+[![tested with tap](https://img.shields.io/badge/tested%20with-node--tap-yellow.svg)](https://github.com/tapjs/node-tap)
+![Node Build](https://github.com/nucleode/typescript-microservice-starter/workflows/Node%20Build/badge.svg)
+![Docker Build](https://github.com/nucleode/typescript-microservice-starter/workflows/Docker%20Build/badge.svg?branch=master)
 
-This is an easy boilerplate for building Node.js microservices with TypeScript. Put your typescript code inside `./src` folder and you are ready to go!
+`Stampo` is a friction-free features-complete boilerplate for building Node.js backend services and microservices with TypeScript. It works on Windows, Linux, and macOS and makes the developer productive in no time! It supports any _Active LTS_ Node.js version (`12.12.x`, `14.x.x`, `16.x.x`).
+
+There are only three steps you need to do to be productive after `Stampo` is initialized (follow the [Getting Started](#getting-started) section):
+1. Put your code inside the `./src` folder
+2. Put your tests inside the `./test` folder.
+3. Relax and enjoy coding!
 
 ## Features
 
 * VS Code debugger configs in .vscode folder
-* recommended Dockerfile for secure nodejs container
-* tsconfig.json for [typescript compiler](https://www.typescriptlang.org/docs/handbook/tsconfig-json.html)
+* recommended Dockerfile for secure Node.js production-ready images
+* most strict and backend specific [`tsconfig.json`](https://www.typescriptlang.org/docs/handbook/tsconfig-json.html) configuration
+* configured tests and reporters via [tap](https://node-tap.org)
 
 ## Getting Started
+### Clone the repo
+```
+$ git clone https://github.com/nucleode/typescript-microservice-starter.git {your_project_name}
+$ cd {your_project_name}
+```
 
+### Remove references to the original starter
+```
+$ rm -rf .git && npm init
 ```
-# Clone the repo
-git clone https://github.com/nucleode/typescript-microservice-starter.git {your_project_name}
-cd {your_project_name}
 
-# Remove reference to the original starter
-rm -rf .git && npm init
+### Initialize a git repository with your own
+```
+$ git init
+```
 
-# Initialize git repo with your own
-git init
+### Install development dependencies
+```
+$ npm i
+```
 
-# Install development dependencies
-npm i
+### Add remote origin and make an initial commit
+```
+$ git remote add origin [email protected]:{your_repository}.git
+$ git add .
+$ git commit -m "Initial commit"
+$ git push -u origin master
+```
+### Start the development server
 
-# Add remote origin and make initial commit
+```
+$ npm run dev
+```
+
+## Included npm scripts
+`Stampo` includes a bunch of scripts that cover the most common scenarios for Node.js backend projects.
 
-git remote add origin [email protected]:{your_repository}.git
-git add .
-git commit -m "Initial commit"
-git push -u origin master
+The commands must be run from the project's root folder.
 
-# start development server
-npm run dev
+### `dev`
+It runs the project in development mode. It uses [`nodemon`](https://github.com/remy/nodemon) to watch the `./src/**/*.ts` files and restart the server on save. It exposes the debugger port, ready to be used via the provided VS Code configuration.
+```
+$ npm run dev
 ```
 
-## Included npm scripts
+### `build`
+It builds for production all files from the `./src` to the `./build` folder. It uses `tsc` directly and therefore checks types too. It also emits the source maps.
+```
+$ npm run build
+```
+
+### `start`
+It runs previously built code from the `./build` folder. In addition, it uses `--enable-source-maps` flag for native source-maps support. Note: this flag is present in Node.js since version `12.12.x`.
+```
+$ npm run start
+```
+It is advised to run Node.js binary directly to avoid any overhead or `sigterm` propagation issues in production.
+```
+$ node --enable-source-maps build/index.js
+```
 
-Run this commands from the project folder with `npm run "script-name"`.
-* `dev`: runs project in development mode, with [ts linter](https://palantir.github.io/tslint/) and `chokidar` watching `.ts` files inside `./src` folder and autorestart on save.
-* `build`: builds all .ts files from `./src` folder to `./build`
-* `lint`: lints source code using `tslint`
-* `update`: easily check for updates and update all dependencies
-* `test`: run tests using tap
-* `test:watch`: run tests using tap in watch mode
-* `test:report`: run tests using tap and adds report file
-* `test:reporter`: run tests using tap and convert output to mocha
+### `lint`
+It uses [`eslint`](https://eslint.org) and [`prettier`](https://prettier.io) to lint the code. It checks `./src` and `./test` folders. Note: `prettier` is run as `eslint` plugin via [`eslint-plugin-prettier`](https://github.com/prettier/eslint-plugin-prettier).
+```
+$ npm run lint
+```
+If you want to fix all of the fixable problems, run
+```
+$ npm run lint -- --fix
+```
+
+### `update`
+It uses [npm-check](https://www.npmjs.com/package/npm-check) to help you upgrading your dependencies and never have any outdated and broken packages again.
+```
+$ npm run update
+```
+
+### `test`
+It uses [`tap`](https://node-tap.org) to run tests. Since version 15 `tap` needs `ts-node` to run TS files, `Stampo` also includes it.
+```
+$ npm run test
+```
+
+### `test:watch`
+It runs `tap` in [watch mode](https://node-tap.org/docs/watch/) with interactive repl.
+```
+$ npm run test:watch
+```
+
+### `test:report`
+It runs tests and reports the results in the widely used `junit` format using [`tap-mocha-reporter`](https://www.npmjs.com/package/tap-mocha-reporter). The default `xunit` reporter can be changed to anyone from the [supported reporters list](https://node-tap.org/docs/reporting/). This command is mainly intended to be used in CI/CD environments. The generated `junit-testresults.xml` can be consumed by automatic reporting systems.
 
 ## External typings augmentation
-This starter is already configured to allow you to extend typings of external packages. The logic behind it is based on [this](https://www.typescriptlang.org/docs/handbook/declaration-files/templates/module-plugin-d-ts.html) official template. To augment a module, just create a folder with the same name as the module you are augmenting and add an index.d.ts in it. [Here](https://github.com/fox1t/fastify-websocket-router/tree/master/typings/fastify) you can find a real world example.
+`Stampo` is configured to allow you to extend typings of external packages using `./typings` folder. The logic behind it is based on [this](https://www.typescriptlang.org/docs/handbook/declaration-files/templates/module-plugin-d-ts.html) official template. To augment a module, create a folder with the same module name you are augmenting and add an `index.d.ts` file inside it. [Here](https://github.com/fox1t/fastify-websocket-router/tree/master/typings/fastify) you can find a real-world example.
 
-## Debugging
-> Warning: This starter uses new V8 [inspect protocol](https://nodejs.org/api/debugger.html) so you have to use at least Node.js 7.7.4 if you want to use the included debugger settings.
+## Debugging Steps
+
+* run the `dev` script to start your application (`$ npm run dev`)
+* either
+  * use the VS Code included `attach` config for the best debugging experience
+  <img width="327" alt="image" src="https://user-images.githubusercontent.com/1620916/129894966-15385c33-da0c-4e00-9f6f-a8ddf966e63e.png">
 
-#### Steps:
-* start dev server with `npm run dev`
-* now you have two ways:
   * use the provided debug URL in Chrome
-  * use VS Code included (inside .vscode folder) `attach` config (best debugging experience)
 
 ## Docker Support
 
-This stater uses Node.js best practices and creates dummy user to start node process, instead of using root user.
+`Stampo` provides a `Dockerfile` that follows the best practices regarding Node.js containerized applications.
+* the application is run using a dedicated non-root user
+* the Dockerfile uses a dedicated build step
+
 
+### Build your docker image
 ```
-# Go to the root of your repo created from this starter
-# Build your docker image
 docker build -t my-project-name .
+```
 
-# run your docker container
+### Run your docker container
+
+```
 docker run -p PORT:PORT my-project-name
 ```