@webundsoehne/nestjs-util-restful

Description

This is a collection of useful modules for creating a NestJS project. Mostly all of these modules are used by the in-house boilerplate of Web & Söhne.

Modules

• Read The API Documentation
• Changelog

• Interceptors
  • Cache-Lifetime
  • Request-Profiler
• Providers
  • Swagger
• Modules
  • Internal
    • Status
    • Changelog
• Stay in touch

Interceptors

Cache-Lifetime

The interceptor sets the cache-lifetime information of the response as it was configured. The configuration depends normally on project and environment.

It will add a function to the request state request.state.setCacheLifetime(), with that you can set a customized lifetime for each request.

Usage

import { RequestProfilerInterceptor } from '@webundsoehne/nestjs-util'

@Module({
  providers: [
    {
      provide: APP_INTERCEPTOR,
      useClass: RequestProfilerInterceptor
    }
  ]
})
class ServerModule implements NestModule {}

setCacheLifetime()

This function takes 2 parameters, where the second one is optional.

| Name | Type | Optional | Description | | ---------------- | ------- | -------- | ----------------------------------------------------------------------------------------------------------------------------- | | lifetime | Number | false | The lifetime of the cache in seconds | | useExpiresHeader | Boolean | true | If true the expiresHeader header will be set, otherwise the cacheControlHeader, be default it uses the configured value |

Configuration

The default values only exists in out skeleton project.

| Key | Type | Default | Description | | ---------------------------------- | ------- | --------------- | ------------------------------------------------------------------------------------ | | cacheLifetime.defaultExpiresHeader | Boolean | false | If true the expiresHeader header will be set, otherwise the cacheControlHeader | | cacheLifetime.defaultLifetime | Number | 0 | This value may set a default cache lifetime, if there was not set any before | | cacheLifetime.expiresHeader | String | 'Expires' | The header key for the expiresHeader | | cacheLifetime.cacheControlHeader | String | 'Cache-control' | The header key for the cacheControlHeader |

Request-Profiler

On debug logger level the request profile informs you when a request got started and when it was finished. It also logs down the response code information and how many seconds the request round-trip took.

Usage

import { RequestProfilerInterceptor } from '@webundsoehne/nestjs-util'

@Module({
  providers: [
    {
      provide: APP_INTERCEPTOR,
      useClass: RequestProfilerInterceptor
    }
  ]
})
class ServerModule implements NestModule {}

Example

[2020-01-01T12:00:00.000Z] [debug] [RequestProfilerInterceptor] - GET /v1/hello/world starting
[2020-01-01T12:00:00.025Z] [debug] [RequestProfilerInterceptor] - GET /v1/hello/world finished - 200 - took: 0.0250 sec

Providers

Swagger

Automatically creates a Swagger documentation out of your controllers. For detailed information about the how-to, take a deeper look at the Nest documentation.

Usage

import { SwaggerService } from '@webundsoehne/nestjs-util'

const app = await NestFactory.create<INestApplication>(ServerModule, new FastifyAdapter())
SwaggerService.enable(app, options)

Parameters

| Name | Required | Type | Description | | ------- | -------- | ---------------- | ----------------------------------------------------------------------- | | app | true | INestApplication | The Nest application on which the documentation should be created | | options | false | SwaggerOptions | Options for customize the default created document | | config | false | SwaggerConfig | Standard configuration, which are required for creating a documentation |

Types

SwaggerOptions

| Name | Required | Type | Description | | --------- | -------- | -------- | -------------------------------------------------------------- | | customize | false | Function | This function takes an DocumentBuilder modifies and returns it |

SwaggerConfig

| Name | Required | Type | Description | | ----------- | -------- | ------- | ----------------------------------- | | useHttps | true | Boolean | If the API is behind SSL encryption | | basePath | true | String | The base-path of the API | | path | true | String | The sub-path to reach the API | | title | true | String | The name of the API or the customer | | description | true | String | A description for the whole API |

Modules

Internal

This is a NestJS controller module for internal API endpoints, which can simply be added to each project. The controller provides you 2 endpoints /status and /changelog.

Usage

import { InternalModule } from '@webundsoehne/nestjs-util'

@Module({
  imports: [InternalModule]
})
class ServerModule implements NestModule {
  async configure(): Promise<any> {
    await setEnvironmentVariables()
  }
}

Configuration

| Key | Type | Default | Description | | ------------------- | ------ | -------------- | --------------------------------------------------- | | misc.changelogFile | String | 'CHANGELOG.md' | The filepath of the project's changelog information | | misc.lastUpdateFile | String | '.last-update' | The filepath of the projects's last update file |

Status

The status endpoint returns the current API version set during the process environment and the last modification of the .last-update in your root directory. The version will be set with the util function setEnvironmentVariables() read from package.json and the file will normally be generated/modified during the deployment process. You may change this value with the misc.lastUpdateFile configuration.

Changelog

This endpoint simply reads and responds with the CHANGELOG.md from your root directory. You can change the filepath with the configuration value misc.changelogFile.

Stay in touch

• Author: Backend Team
• Website: Web & Söhne