samchon/backend

A template repository for TypeScript backend server

Backend

1. Outline

1.1. Introduction

Template repository for NestJS + Prisma stack with FP and TDD.

@samchon/backend is a template repsitory of backend project utilizing NestJS and Prisma. It has been prepared to educate and spread how to adapt FP (Functional Programming) in the NestJS development. Also, @samchon/backend guides how to utilize those 3rd party libraries (what I've developed) in the production, especially helpful for TDD (Test Driven Development) with dramatic productivity enhancement.

• typia: Superfast runtime validator
• nestia: NestJS helper libaries like SDK generation
• prisma-markdown: Markdown generator of Prisma (ERD + documentation)

Additionally, I've prepared a couple of example backend projects leveraging this template repository. Reading this README.md document and traveling below example projects, you may understand how to develop the TypeScript backend server of NestJS following the FP and TDD paradigm with my 3rd party libraries.

• samchon/bbs-backend: Simple Bullet-in Board System
• Korean only
  • samchon/fake-iamport-server: Fake iamport server, but real SDK
  • samchon/fake-toss-payments-server: Fake toss-payments server, but real SDK

If you've already developed a TypeScript backend server with NestJS + Prisma, and its quality seems like enough good to be a good example for the backend programming learners with FP and TDD paradigm, please leave an issue or a pull request.

1.2. Specializations

Transform this template project to be yours.

When you've created a new backend project through this template project, you can specialize it to be suitable for you by changing some words. Replace below words through IDE specific function like Edit > Replace in Files (Ctrl + Shift + H), who've been supported by the VSCode.

Before	After
ORGANIZATION	Your account or corporation name
PROJECT	Your own project name
AUTHOR	Author name
db_name	Database to connnect
db_schema	Database schema to use
db_account	Database account to use, not root account
https://github.com/samchon/backend	Your repository URL

After those replacements, you should specialize the src/Configuration.ts, .github/workflows/build.yml files. Open those files and change constant values of these files to be suitable for your project. Also, open markdown files like this README.md and write your specific project story. Below is list of the markdown files.

• .github/ISSUE_TEMPLATE/BUG_REPORT.md
• .github/ISSUE_TEMPLATE/FEATURE_REQUEST.md
• .github/ISSUE_TEMPLATE/QUESTION.md
• .github/PULL_REQUEST_TEMPLATE.md
• README.md
• CODE_OF_CONNDUCT.md
• CONTRIBUTING.md
• LICENSE

2. Installation

2.1. NodeJS

This backend server has implemented through TypeScript and it runs on the NodeJS. Therefore, to mount this backend server on your local machine, you've to install the NodeJS.

• https://nodejs.org/en/

Also as you can see from the package.json file, this project requires the private npm module @ORGANIZATION, provided from the Github. Therefore, to develop this backend server, you've configure the .npmrc file. Open the below link and complete the configuration.

• https://github.com/features/packages

2.2. PostgreSQL

bash postgres.sh

If you've installed Docker, then run the script above.

Otherwise, visit below PostgreSQL official site and install it manually.

https://www.enterprisedb.com/downloads/postgres-postgresql-downloads

After that, run the npm run schema <root-account> <password> command.

Database schema for BBS backend system would be automatically constructed.

npm run schema postgres root

2.3. Repository

From now on, you can start the backend server development, right now.

Just download this project through the git clone command and install dependencies by the npm install command. After those preparations, you can start the development by typing the npm run dev command.

# CLONE REPOSITORY
git clone https://github.com/samchon/backend
cd backend

# INSTALL DEPENDENCIES
npm install

# START DEVELOPMENT
npm run dev

3. Development

• A. Definition only
  • Design prisma schema file
  • Build and Share ERD document with your companions
  • Write DTO structures
  • Declare controller method only
• B. Software Development Kit
  • Build SDK from the declaration only controller files
  • SDK supports mockup simulator, boosting up frontend development
  • SDK is type safe, so development be much safer
• C. Test Automation Program
  • Build test program earlier than main program development
  • Utilize SDK library in the test program development
  • This is the TDD (Test Driven Development)
• D. Main Program Development

3.1. Definition

Before developing the main program, define it before.

At first, design the DB architecture on the Prisma Schema file (prisma/schema.prisma).

Writing the schema definitions, don't forget to write the detailed descriptions on each tables and properties. After that, build ERD (Enterprise Relationship Diagram) document through npm run build:prisma command. The ERD document will be generated on the docs/ERD.md path. If you share the ERD document with your companions, your team can enjoy increased productivity by standardizing words and entities.

At second, write DTO structures under the src/api/structures directory and declare API endpoint specs under the src/controllers directory. Note that, do not implement the function body of the controller. Just write declaration only. Below code is never pseudo code, but actual code for current step.

@Controlleer("bbs/articles")
export class BbsArticleController {
  @TypedRoute.Patch()
  public async index(
    @TypedBody() input: IBbsArticle.IRequest
  ): Promise<IPage<IBbsArticle.ISummary>> {
    input;
    return null!;
  }
}

3.2. Software Development Kit

@samchon/backend provides SDK (Software Development Kit) for convenience.

SDK library means a collection of fetch functions with proper types, automatically generated by nestia. As you can see from the above gif image, SDK library boosts up client developments, by providing type hints and auto completions.

Furthermore, the SDK library supports Mockup Simulator.

If client developer configures simulate option to be true, the SDK library will not send HTTP request to your backend server, but simulate the API endpoints by itself. With that feature, frontend developers can directly start the interaction development, even when the main program development has not started.

# BUILD SDK IN LOCAL
npm run build:sdk

# BUILD SDK AND PUBLISH IT TO THE NPM
npm run package:api

3.3. Test Automation Program

TDD (Test Driven Development)

After the Definition and client SDK generation, you've to design the use-case scenarios and implement a test automation program who represents those use-case scenarios and guarantees the Main Program.

To add a new test function in the Test Automation Program, create a new TS file under the test/features directory following the below category and implement the test scenario function with representative function name and export symbol.

Note that, the Test Automation Program resets the local DB schema whenever being run. Therefore, you've to be careful if import data has been stored in the local DB server. To avoid the resetting the local DB, configure the reset option like below.

Also, the Test Automation Program runs all of the test functions placed into the test/features directory. However, those full testing may consume too much time. Therefore, if you want to reduce the testing time by specializing some test functions, use the include option like below.

• supported options
  • include: test only restricted functions who is containing the special keyword.
  • exclude: exclude some functions who is containing the special keyword.
  • reset: do not reset the DB

# test without db reset
npm run test -- --reset false

# include or exclude some features
npm run test -- --include something
npm run test -- --include cart order issue
npm run test -- --include cart order issue --exclude index deposit

3.4. Main Program

After Definition, client SDK building and Test Automation Program are all prepared, finally you can develop the Main Program. Also, when you complete the Main Program implementation, it would better to validate the implementation through the pre-built SDK and Test Automation Program.

However, do not commit a mistake that writing source codes only in the controller classes. The API Controller must have a role that only intermediation. The main source code should be write down separately following the directory categorizing. For example, source code about DB I/O should be written into the src/providers directory.

4. Appendix

4.1. NPM Run Commands

List of the run commands defined in the package.json are like below:

• Test
  • test: Run Test Automation Program
• Build
  • build: Build every below programs
  • build:sdk: Build SDK library, but only for local
  • build:test: Build Test Automation Program
  • build:main: Build main program
  • dev: Incremental builder of the Test Automation Program
  • eslint: EsLint validator runner
  • pretter: Adjust prettier to every source codes
  • webpack: Run webpack bundler
• Deploy
  • package:api: Build and deploy the SDK library to the NPM
  • schema: Create DB, users and schemas on local database
  • start: Start the backend server
• Webpack
  • webpack: Run webpack bundler
  • webpack:start: Start the backend server built by webpack
  • webpack:test: Run test program to the webpack built

4.2. Directories

• .vscode/launch.json: Configuration for debugging
• packages/api/: Client SDK library for the client developers
• docs/: Documents like ERD (Entity Relationship Diagram)
• prisma/schema.prisma: Prisma Schema File
• src/: TypeScript Source directory
  • src/api/: Client SDK that would be published to the @ORGANIZATION/PROJECT-api
    • src/api/functional/: API functions generated by the nestia
    • src/api/structures/: DTO structures
  • src/controllers/: Controller classes of the Main Program
  • src/providers/: Service providers (bridge between DB and controllers)
  • src/executable/: Executable programs
• test/: Test Automation Program

4.3. Related Repositories

Write the related repositories down.

backend's Issues

Update typeorm to v0.1 and adapt `JsonSelectBuilder`

https://github.com/samchon/safe-typeorm#json-select-builder

Implement network level mutex controlling example

Someone requested me to write a pratical code that handling network level mutex.

I think, unifying systematic entities with write-mutex-lock would be a good example for the request.

How to run dev server?

I can't access the api server either by running npm run dev or npm run start

open http://127.0.0.1:37001/ got an ERR_CONNECTION_REFUSED

PS: I have connected to my database and got schema created by npm run schema, and there is no error in the console

Implement non-distruptive update system

Draw an ERD

Support `npm run revert` command

Support npm run revert command which can rollback to previous commit.

Update to `[email protected]`

Implement much more test units

한국어 브랜치 `korean` 만들기

각종 마크다운 문서를 한국어로 쓴, korean 브랜치를 만든다.

Define API controller method types (header only)

src/executable/update.ts file is empty

To complete the #9, src/executable/update.ts file who is run by the npm run update command must be prepared.

However, I've forgotten to filling the file.

Add swagger build command

Although building swagger.json is not recommended, but required for someone.

Do not use `let` keyword, but `const` only.

Only const keyword would be used.

Separate bbs to other repo

backend keeps only default files

bbs-backend takes bbs

Fix typo

backend/package.json

Line 2 in 1d873b1

"name": "@ORGINAZATION/PROJECT-backend",

Should be ORGANIZATION, not ORGINAZATION.

Many thx :D

Change charset and sql_mode of MariaDB

• charset: utf8_unicode_mb4
• sql_mode: ANSI, TRADITIONAL

Implement provider classes

There's no setup script

Bug Report

https://github.com/samchon/backend#24-data

doc says

When those installations have been all completed, you can mount the basic data up or start the local backend server by typing below commands.

# Seed initial data
# minimum data to running the local backend server
npm run setup 

but there's no "setup" script in package.json

"1.3. Directories" requires detailed description

It's extremely short. Requires the detailed description.

ESLint and Prettier

Write README.md

Configure prettier for import order

Let import statements to be sorted automatically by prettier configuration.

Update dependencies: `nestia`

The nestia has been updated to the v2.0 version.

"Comments" has not implemented yet

Support publishing multiple modules

This example backend project publishes the @samchon/bbs-api module for the client developers.

However, if a backend project becomes larger, developer considers to publishing not only the SDK module, but also publishing many other modules like models and providers. For such case, let's separate the module configuration and support the multiple modules' publishing.

Implement body functions of the controller classes

Configure `nestia.config.ts`

Since [email protected] update, configuring nestia parameters into the nestia.config.ts file has been possible - samchon/nestia#14.

Therefore, configure the new file, nestia.config.ts

is typo file name?

INFRASTRUCTURE.md (https://github.com/samchon/backend)/INFRASTRUCTURE.md)

seems like to typo from 'INTRASTRUCTURE.md'

__MvBbsArticleHit.increments()

Implement a static method counting article hit.

Refactor `Configuration` to be asynchronous

Change all constant values in the Configuration to be asynchronous functions that can be modified.

It's to enhancing re-usability and preparing external configuration files.

Debugging configuration file

Have not defined it yet

Define API & ORM data structures

Implement test automation program

Update dependencies to be latest

Update below dependencies to be latest.

• nestia
• nestia-helper
• safe-typeorm

Write community documents

Write those documents

• contribution guide
• code_of_conduct
• issue templates
  • bug report
  • feature request
  • question
• pull request template

Wrong directory name, ".gtihub"

Write INFRASTRUCTURE.md

Change default DBMS to PostgreSQL

Using lots of DBMS, PostgreSQL was the best.

Therefore, change default DBMS configuration to the best PostgreSQL.

Of course, README content would be changed following the new DBMS.