Commit 7500bdcd authored by Léonard Treille's avatar Léonard Treille
Browse files

Update README file and create english version

parent 63e80daf
# Affluence Serv
Affluence backend Nodejs app.
## Install
`npm install`
## Run the app
* `npm run start:dev` to run the server in dev mode (hot reload/compile).
* `npm run start:debug` to run the server in debug mode (hot reload/compile + debuger).
* `npm run build && npm run start` to run the server in production mode.
## REST API
| Resource | Method | Type | Documentation |
| ------------------- | ------ | ---- | ------------------- |
| `/occupancy/report` | POST | JSON | Save a user report. |
# Typescript / Koa project template.
# Affluence Serv
Table of Content
- [Typescript / Koa project template.](#typescript--koa-project-template)
- [Install](#install)
- [NPM Commands](#npm-commands)
- [Template overview](#template-overview)
- [Dependency Injection](#dependency-injection)
- [Services](#services)
- [Middleware](#middleware)
- [Routing](#routing)
- [Controller Options](#controller-options)
- [Attach middlewares](#attach-middlewares)
- [Configurations](#configurations)
- [Load a configuration file](#load-a-configuration-file)
- [Get a configuration](#get-a-configuration)
- [Listen to config changes](#listen-to-config-changes)
- [Applications](#applications)
- [Cron](#cron)
- [Log](#log)
- [Configure log output](#configure-log-output)
- [Example](#example)
- [Controller](#controller)
- [Cron](#cron-1)
Backend Nodejs de l'application Affluence.
## Install
## Installation
* `npm install -g webpack nodemon`
* `npm install`
`npm install`
## NPM Commands
## Exécution
* `npm run build` => Build the project using the production configuration
* `npm run start:dev` => Start the server using the dev config + watch files.
* `npm run start:debug` => Start the server using the debug config + watch files + remote debbuging.
* `npm run start:dev` pour lancer le serveur en mode dev (rechargement/compilation à chaud).
* `npm run start:debug` pour lancer le serveur en mode debug (rechargement/compilation à chaud + debugueur).
* `npm run build && npm run start` pour lancer le serveur en mode production.
## Template overview
## REST API
This project template allow developers to:
* Auto load controller files (`*.controller.ts`, using webpack and typescript plugin)
* Declare services
* Declare middlewares
* Use dependency injection and IoC (available in controllers, services, middlewares, application).
* Declare multiple Koa application
* Declare JSON config files.
The project structure is:
```
src/
app/ # The project app code may be here.
core/ # Boilerplate code
main.ts # Entry point of the project.
webpack/
webpack.config.<env>.js # webpack configuration
dist/
# The bundled code including config files (copy from the src folder at build time)
```
## Dependency Injection
This project template use the tsyringe package to allow developers to use DI and IoC.
## Services
You can declare service using the Service decorator:
```typescript
@Service()
export class MyService {}
```
And use it in other service or controller:
```typescript
@Service()
export class OtherService {
constructor(private myService: MyService) {}
}
```
## Middleware
You can declare a middleware class and use it in controller or route handler.
A middleware class is a singleton and can use DI.
```typescript
import { Context, Next } from "koa";
import { Middleware } from "@decorators/middleware.decorator";
import { MiddlewareInterface } from "@core/middleware.interface";
@Middleware()
export class MyMiddleware implements MiddlewareInterface {
use(ctx: Context, next: Next): any {
/* ... */
}
}
```
You can declare a middleware as application level using the autoloadIn property:
```typescript
// Add the middleware to the main application (default application in the project template).
@Middleware({ autoloadIn: 'main' })
```
## Routing
To declare a Koa route, you must create a `*.controller.ts` file and export an annoted controller class as default:
```typescript
@Controller()
export default class MyController {
@Get('/user/:id')
async getUserById() {/* some code here... */}
}
```
Every `*.controller.ts` in the project are automatically imported in the `main.ts` file.
### Controller Options
You can set options to the controller annotation.
| Option | Description |
| ------ | --------------------------------------------------------- |
| prefix | The prefix apply to each routes defined by the controller |
| app | The application name (default to `main`) |
Example:
```typescript
@Controller({ prefix: '/my_route' })
/*... */
```
(e.g: the prefix must start with a "`/`" if it's provided)
### Attach middlewares
You can attach middlewares to a controller or methods with the `AttachMiddleware` decorator:
```typescript
@AttachMiddleware([/* a list of middleware */])
@Controller()
export default class MyController {}
```
(Note: Middlewares attached to a controller will be called for each controller routes)
```typescript
@Controller()
export default class MyController {
@AttachMiddleware([/* a list of middleware */])
@Get('/my/path')
myPath(ctx: Context) {}
}
```
## Configurations
* You can create several config files at the root of the `src/` folder.
* Each configuration file must be named according to the following pattern: `*.config.json`.
### Load a configuration file
Use the `loadConfigFile` function from the `config.ts` file:
```typescript
import { loadConfigFile } from '@core/config';
loadConfigFile('my_config'); // Note: the expected config file name is "my_config.config.json".
```
### Get a configuration
Simply:
```typescript
import { config } from '@core/config';
config.my_config
```
Or using the config service
```typescript
@Service() // Or any other class that use the IoC (Controller/Middleware/etc...
export class MyService {
constructor(private configService: ConfigService) {
this.configService.my_config
}
}
```
### Listen to config changes
Each config files are watched. The config service allows you to listen to these changes:
```typescript
@Service() // Or any other class that use the IoC (Controller/Middleware/etc...
export class MyService {
constructor(private configService: ConfigService) {
this.configService.change$.on(CONFIG_EVENTS.CHANGE, configName => {
if (configName === 'my_config') {
// Do something with the new config.
}
});
}
}
```
## Applications
The template provide a koa app instance by default, but you can define and run multiple app at the same time.
To create a new koa app, first create a new file called `my_app.app.ts` and export a class:
```typescript
@Application('my_app', MY_APP_PORT)
export default class MyApp extends AbstractApp {}
```
Now you can use your new app on a specific controller :
```typescript
@Controller({ app: 'my_app' })
/*...*/
```
## Cron
You can declare a cron job using the `@Cron()` decorator.
```typescript
import { Cron } from "@decorators/cron.decorator";
@Cron({ cronTime: '* * * * * *' })
```
## Log
This template include the winston package for app logging.
A service is provided:
```typescript
/* ... imports, decorators */
export default class MyClass {
constructor(private logService: LoggerService) {}
someMethod() {
this.logService.logger.info('log with info level');
this.logService.logger.error('log with error level');
/* etc... */
}
}
```
### Configure log output
2 type of output are supported by default:
* Console
* File
The loggerService use the app.config.file for that.
```json
{
"logger": {
"level": "silly",
"transports": [
{ "type": "console" },
{
"type": "file",
"options": {
"filename": "app.log",
"maxsize": 100000,
"maxFiles": 10,
"tailable": true,
"zippedArchive": true
}
}
]
}
}
```
## Example
### Controller
```typescript
import { Controller, Get, Post } from '@core/decorators/controller.decorator';
import { Context } from 'koa';
import { MyService } from '@app/my.service';
import { MyMiddleware } from '@app/my.middleware';
import { Joi } from 'koa-joi-router';
@Controller()
export default class LoremController {
constructor(private myService: MyService) { }
@AttachMiddleware([MyMiddleware])
@Get('/ipsum')
getIpsum(ctx: Context) {
this.myService.fooo();
ctx.body = { message: 'test ipsum dolor sit amet' };
}
@Post('/lorem/:id', {
body: {
name: Joi.string().max(100),
email: Joi.string().lowercase().email()
},
type: 'json'
})
postLorem(ctx: Context) {
ctx.body = ctx.request.body;
ctx.body.id = ctx.request.params.id;
}
}
```
### Cron
```typescript
import { CronJob } from "cron";
import { OnTick, OnInit, OnComplete } from "@core/cron.interface";
import { Cron } from "@decorators/cron.decorator";
@Cron({ cronTime: '* * * * * *' })
export default class SampleCron implements OnInit, OnTick, OnComplete {
/**
* The cron job instance.
* /!\ Not available in the constructor. Use the OnInit interface if you want to start the cron manually.
*/
job: CronJob | undefined;
onInit(): void {
/* ... init code here. */
this.job.start(); // Or use the start property in the decorator options.
setTimeout(() => {
// Stop the job and call the onComplete callback.
this.job?.stop();
}, 5000)
}
onTick(): void {
/* ... */
}
onComplete(): void {
/* ... */
}
}
```
| Ressource | Méthode | Type | Documentation |
| ------------------- | ------- | ---- | ---------------------------- |
| `/occupancy/report` | POST | JSON | Enregistre une contribution. |
......@@ -9,7 +9,7 @@
"run:dev": "nodemon --quiet dist/app.js",
"start:dev": "webpack --env=dev",
"start:debug": "webpack --env=debug",
"start": "node --quiet dist/app.js"
"start": "node dist/app.js"
},
"author": "",
"license": "ISC",
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment