Typescript Express Rest API Boilerplate

A delightful way building a Node.js RESTful API written in TypeScript.
Inspired by the awesome AWS Lambda Boilerplate of my former techlead.
_{Crafted with ❤️ by jL.}

Installation

NPX

npx jl-tsnode-express

Git

git clone https://github.com/johnliveeoroncillo/tsnode-rest-boilerplate.git

Install Dependencies

Requires Node.js v10+, Typescript and Docker (optional) to run. Install the dependencies and devDependencies and start the server.
Link to docker: Docker

npm i -g node
npm i -g typescript
npm i -g ts-node

Development

npm run dev

Build

npm run build

Production

npm run start

PlantUML

Download this VSCode Extension Name: PlantUML Id: jebbs.plantuml Description: Rich PlantUML support for Visual Studio Code. Version: 2.17.2 Publisher: jebbs VS Marketplace Link: https://marketplace.visualstudio.com/items?itemName=jebbs.plantuml
Download JRE for PlantUML Preview in VSCode - https://java.com/en/download/

PUML Preview

Open your .puml file in vscode
Press ALT + D

Exporting Diagram

Open your .puml file in vscode
Press CTRL + SHIFT + P
Select PlantUML: Export Current Diagram
Select your desired file extension

Features

Integrated Redis, MySql and Postgres using Typeorm
Auto creation of API Routes.
Support Middleware for Authorization
Test API using Jest
Parallel Processing or Events
Create sequence diagram using PlantUML
Create api documentation using apidoc
and many more ..

Coming Soon / Roadmap

https://github.com/johnliveeoroncillo/tsnode-rest-boilerplate/projects/

Folder Structure

tsnode-rest-boilerplate
└─code_templates (Templates)
└─core (Main Core of the boilerplate)
└─docs (API Documentations)
└─migrations (Migration files)
└─seeder (Seed fake data to table)
└─src
|   └─functions
|   |   └─apis (Contains API Routes)
|   |   |   └─sample-api (Created from npm run make:api sample-api)
|   |   |       | config.yml (API Configuration)
|   |   |       | handler.ts (1st lifecycle of the API)
|   |   |       | action.ts (Action of the API connected to handler)
|   |   |       | request.ts (Allowed Body Request)
|   |   |       | response.ts (List of responses of the API)
|   |   |       | validate.ts (Body Request Validation)
|   |   |       | handler_test.ts (Unit Testing)
|   |   └─cron (Contains Cron Jobs)
|   |   |   └─sample-cron (Created from npm run make:cron sample-cron)
|   |   |       | config.yml (Cron Configuration)
|   |   |       | handler.ts (1st lifecycle of the CRON)
|   |   └─events (Contains Events)
|   |   |   └─event_test (Created from npm run make:event event_test)
|   |   |       | config.yml (Event Configuration)
|   |   |       | handler.ts (1st lifecycle of the event)
|   |   |       | action.ts (Action of the event connected to handler)
|   |   |       | request.ts (Allowed Body Payload)
|   |   |       | response.ts (List of responses of the event)
|   |   |       | validate.ts (Payload Validation)
|   |   |       | handler_test.ts (Unit Testing)
|   |   └─middlewares (Middlware of the API)
|   |   |    | authorizer.ts (Sample middleware for authentication)
|   |   └─services (Custom Services)
|   └─helpers (Helpers folder)
|   └─models (Table Models)
|   └─repository (Table Repository)
| .env.example
| artisan.ts
| .eslintrc.js
| .gitignore
| .prettierrc
| docker-compose.yml (Docker image files and database configurations)
| jest.config.js
| migrate.ts
| tsconfig.json

Config Structure

./apis/sample-api/config.yml

sample-api: (API Key) 
  handler: ./src/functions/apis/sample-api/handler (1st lifecycle of the API)
  endpoint: /sample-api (API Route)
  method: post (API Method)
  enabled: true (Enable/Disable option)
  middleware: authorizer (File name of the middleware)
  version: 1 (Optional: Version of the api)
  prefix: api (Optional: API prefix)

Enabled Version: /v1/sample-api
Enabled Prefix: /api/sample-api
Enabled Prefix and Version: /api/v1/sample-api
With path parameters: /sample-api/{id}

./cron/sample-cron/config.yml

cron_today: (Cron Key)
  handler: ./src/functions/cron/cron_today/handler (1st lifecycle of the CRON)
  enabled: false (Enable/Disable option)
  cron: '* * * * * *' (Cron frequency)
  timezone: 'Asia/Manila' (Timezone)

./events/event_test/config.yml

event_test: (Event Key) 
  handler: ./src/functions/events/event_test/handler (1st lifecycle of the API)
  enabled: true (Enable/Disable option)

Environment Variables

#DATABASE CONFIGURATION
##MYSQL
MYSQL_HOST=localhost
MYSQL_PORT=3306
MYSQL_USERNAME=root
MYSQL_PASSWORD=admin
MYSQL_DB=database

##POSTGRES
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_USERNAME=root
POSTGRES_PASSWORD=admin
POSTGRES_DB=database

##OTHER DB OPTIONS
DB_LOGGING=true

##REDIS
REDIS_HOST=127.0.0.1
REDIS_USERNAME=root
REDIS_PASSWORD=admin
REDIS_PORT=6379
REDIS_TTL=3600

#JWT CONFIGURATION
JWT_TOKEN=
JWT_ADMIN_TOKEN=

#CRYPTO SECRET KEY
SECRET_KEY=abcdef0123456789abcdef0123456789

#ALLOWED ORIGINS (CORS) - currently unavailable or not working
ALLOWED_ORIGINS=

#EVENT
EVENT_HOST=127.0.0.1

Demo

This is only a sample api to explore the boilerplate. You can also create your own API based on your requirements.

Development

https://tsnode-rest-dev.herokuapp.com/

Production

https://tsnode-rest-prod.herokuapp.com/

REDIS

Create

Endpoint: /redis/insert
Method: POST
Request:
  {
    key: 'my-key',
    value: ['value1', 'value2']
  }

Get

Endpoint: /redis/:key
Method: GET

CLIENT

Login

Endpoint: /login
Method: POST
Request:
  {
    username: '',
    password: ''
  }

Profile

Endpoint: /profile
Authorization: Bearer <TOKEN FROM LOGIN>
Method: GET

ADMIN

Login

Endpoint: /login/admin
Method: POST
Request:
  {
    username: '',
    password: ''
  }

Profile

Endpoint: /profile/admin
Authorization: Bearer <TOKEN FROM LOGIN>
Method: GET

Register

Endpoint: /register
Method: POST
Request:
  {
    username: '',
    password: '',
    scope: '' <- ADMIN or CLIENT
  }

API Reference

Create Model

  npm run make:model <model_name> <table_name>

Create Repository

  npm run make:repository <repository_name> <table_name>

This will create model and repository

Create Migration

  npm run make:migration <table_name>

Create API

  npm run make:api <api_path>

Example:
npm run make:api admin/login
npm run make:api admin/management/users

Create Service

  npm run make:service <service_name>

Create Cron

  npm run make:cron <cron_name>

Create Socket Event

  npm run make:socket <socket_event_name>

Sample: ./src/functions/socket/socket_test

## Server Side Usage: ##
### NOTE: NO NEED FOR "on" LISTENER ON SERVER SIDE! e.g. io.socket.on('socket_test', (payload) => ....)
### THE FOLDER ITSELF ALREADY LISTENED/INITIALIZED TO SOCKET EVENTS
/** SEND TO SELF */
io.socket.emit('socket_test', payload);

/** BROADCAST TO ALL INCLUDING SENDER */
io.socketio.broadcastAll('socket_test', payload);

/** BROADCAST TO ALL EXCLUDING SENDER */
io.socket.broadcast.emit('socket_test', payload);

## GLOBAL USAGE ##
app.get('socketio').broadcastAll('my_event', payload);
### SEND TO SPECIFIC ID
app.get('socketio').sendToId(socket_id, 'my_event', payload);


## Client Side Usage: ##
socket.emit('socket_test', payload);
socket.on('socket_test', (payload) => ...)

Ref: https://socket.io

Create Event

  npm run make:event <event_name>

EVENT USAGE

This function is inspired by AWS Lambda Event which drives the invocation or Lambda polls a queue or data stream and invokes the function in response to activity in the queue or data stream.

This custom event is using "worker_threads" module to recreate the AWS Lambda Event functionality. Wherein it executes functions in parallel process and doesn't affect the current thread of your API.

import { EVENTS } from "../../helpers/Enums";
import { invokeEvent, invokeEventWithResponse } from "../../core/libs/Events";

//OPTION 1 - Event with Response
const data = await invokeEventWithResponse(EVENTS.EVENT_TEST, { message: request.message });
return data;

//OPTION 2 - Event without Response
await invokeEvent(EVENTS.EVENT_TEST, { message: request.message });

Create Documentation

  npm run make:doc <name>

Build Documentation

  npm run build:doc

Optional: Edit apidoc.json

Other API Reference

Lint

  npm run lint

Migrate

  npm run migrate

Refresh Migrate

  npm run migrate:refresh

Run Local Cron Job

  npm run cron

Run Local Event

  npm run dev:event

Running Tests

To run tests, run the following command

Silent Test

  npm run test <path_file>

Example: npm run test ./apis/login/

Documented Test

  npm run test:log <path_file>

Example: npm run test:log ./apis/login/

Local Docker

Start Local MySQL/Redis/Postgres

  npm run docker:start

Stop Local MySQL/Redis/Postgres

  npm run docker:stop

Development

Want to contribute? Great! Email me at johnliveeoroncillo@gmail.com

License

GNU GPLv3

Name		Name	Last commit message	Last commit date
Latest commit History 326 Commits
.devcontainer		.devcontainer
.vscode		.vscode
@types/express		@types/express
code_templates		code_templates
core		core
docs		docs
logs		logs
migrations		migrations
seeder		seeder
src		src
.env.example		.env.example
.eslintrc.js		.eslintrc.js
.gitignore		.gitignore
.prettierrc		.prettierrc
LICENSE		LICENSE
README.md		README.md
apidoc.json		apidoc.json
artisan.ts		artisan.ts
docker-compose.yml		docker-compose.yml
jest.config.js		jest.config.js
migrate.ts		migrate.ts
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

License

johnliveeoroncillo/tsnode-rest-boilerplate

Folders and files

Latest commit

History

Repository files navigation

Typescript Express Rest API Boilerplate

Installation

NPX

Git

Install Dependencies

Development

Build

Production

PlantUML

PUML Preview

Exporting Diagram

Features

Coming Soon / Roadmap

Folder Structure

Config Structure

./apis/sample-api/config.yml

./cron/sample-cron/config.yml

./events/event_test/config.yml

Environment Variables

Demo

This is only a sample api to explore the boilerplate. You can also create your own API based on your requirements.

Development

Production

REDIS

Create

Get

CLIENT

Login

Profile

ADMIN

Login

Profile

Register

API Reference

Create Model

Create Repository

Create Migration

Create API

Create Service

Create Cron

Create Socket Event

Ref: https://socket.io

Create Event

EVENT USAGE

This function is inspired by AWS Lambda Event which drives the invocation or Lambda polls a queue or data stream and invokes the function in response to activity in the queue or data stream.

This custom event is using "worker_threads" module to recreate the AWS Lambda Event functionality. Wherein it executes functions in parallel process and doesn't affect the current thread of your API.

Create Documentation

Build Documentation

Other API Reference

Lint

Migrate

Refresh Migrate

Run Local Cron Job

Run Local Event

Running Tests

Silent Test

Documented Test

Local Docker

Start Local MySQL/Redis/Postgres

Stop Local MySQL/Redis/Postgres

Development

License

About

Topics

Resources

License

Stars

Watchers

Forks

Releases 15

Packages 0

Contributors 3

Languages

Packages