@nestjs-mod/common
A collection of utilities for unifying NestJS applications and modules

Installation
npm i --save @nestjs-mod/common
Utilities
Config model | Decorators for describing the module configuration and a function for its serialization and validation. |
Env model | Decorators for describing module environment variables and functions for its serialization and verification. |
NestJS application | Function for sequential import of nestModules. |
NestJS module | Function for creating a configurable module with the ability to use multi-providing. |
Modules
Utilities descriptions
Config model
Decorators for describing the module configuration and a function for its serialization and validation.
Values for this type of configuration must be described in code.
Decorators
ConfigModel
, ConfigModelProperty
Function
configTransform
Usage
import { ConfigModel, ConfigModelProperty, configTransform } from '@nestjs-mod/common';
import { DynamicModule, Module } from '@nestjs/common';
import { NestFactory } from '@nestjs/core';
import { IsNotEmpty } from 'class-validator';
@ConfigModel()
class AppConfig {
@ConfigModelProperty()
@IsNotEmpty()
option!: string;
}
@Module({ providers: [AppConfig] })
class AppModule {
static forRoot(config: Partial<AppConfig>): DynamicModule {
return {
module: AppModule,
providers: [
{
provide: `${AppConfig.name}_loader`,
useFactory: async (emptyAppConfig: AppConfig) => {
if (config.constructor !== Object) {
Object.setPrototypeOf(emptyAppConfig, config);
}
const obj = await configTransform({
model: AppConfig,
data: config,
});
Object.assign(emptyAppConfig, obj.data);
},
inject: [AppConfig],
},
],
};
}
}
async function bootstrap1() {
const app = await NestFactory.create(AppModule.forRoot({}));
await app.listen(3000);
}
bootstrap1();
async function bootstrap2() {
const app = await NestFactory.create(AppModule.forRoot({ option: 'value1' }));
console.log(app.get(AppConfig));
await app.listen(3000);
}
bootstrap2();
Back to Top
Env model
Decorators for describing module environment variables and functions for its serialization and verification.
Values can be automatically read from process.env.
Decorators
EnvModel
, EnvModelProperty
Function
envTransform
Usage
import { EnvModel, EnvModelProperty, envTransform } from '@nestjs-mod/common';
import { DynamicModule, Module } from '@nestjs/common';
import { NestFactory } from '@nestjs/core';
import { IsNotEmpty } from 'class-validator';
@EnvModel()
class AppEnv {
@EnvModelProperty()
@IsNotEmpty()
option!: string;
}
@Module({ providers: [AppEnv] })
class AppModule {
static forRoot(env: Partial<AppEnv>): DynamicModule {
return {
module: AppModule,
providers: [
{
provide: `${AppEnv.name}_loader`,
useFactory: async (emptyAppEnv: AppEnv) => {
if (env.constructor !== Object) {
Object.setPrototypeOf(emptyAppEnv, env);
}
const obj = await envTransform({
model: AppEnv,
data: env,
});
Object.assign(emptyAppEnv, obj.data);
},
inject: [AppEnv],
},
],
};
}
}
async function bootstrap1() {
const app = await NestFactory.create(AppModule.forRoot({}));
await app.listen(3000);
}
bootstrap1();
async function bootstrap2() {
const app = await NestFactory.create(AppModule.forRoot({ option: 'value1' }));
console.log(app.get(AppEnv));
await app.listen(3000);
}
bootstrap2();
async function bootstrap3() {
process.env['OPTION'] = 'value1';
const app = await NestFactory.create(AppModule.forRoot({}));
console.log(app.get(AppEnv));
await app.listen(3000);
}
bootstrap3();
Back to Top
NestJS application
Function for sequential import of nestModules.
When importing, all preWrapApplication methods of modules are run at the beginning, then all wrapApplication methods, and at the very end all postWrapApplication methods.
Types of modules (list in order of processing):
System modules
- System modules necessary for the operation of the entire application (examples: launching a NestJS application, launching microservices, etc.). Only NestJS-mod compatible modules.
Core modules
- Core modules necessary for the operation of feature and integration modules (examples: main module with connection to the database, main module for connecting to aws, etc.). NestJS and NestJS-mod compatible modules.
Feature modules
- Feature modules with business logic of the application. NestJS and NestJS-mod compatible modules.
Integration modules
- Integration modules are necessary to organize communication between feature or core modules (example: after creating a user in the UsersModule feature module, you need to send him a letter from the NotificationsModule core module). NestJS and NestJS-mod compatible modules.
Infrastructure modules
- Infrastructure modules are needed to create configurations that launch various external services (examples: docker-compose file for raising a database, gitlab configuration for deploying an application). Only NestJS-mod compatible modules.
Function
bootstrapNestApplication
Usage
import {
isInfrastructureMode,
DefaultNestApplicationInitializer,
DefaultNestApplicationListener,
EnvModel,
EnvModelProperty,
bootstrapNestApplication,
createNestModule,
} from '@nestjs-mod/common';
import { Injectable } from '@nestjs/common';
import { IsNotEmpty } from 'class-validator';
@EnvModel()
class AppEnv {
@EnvModelProperty()
@IsNotEmpty()
option!: string;
}
@Injectable()
class AppService {
constructor(private readonly appEnv: AppEnv) {}
getEnv() {
return this.appEnv;
}
}
const { AppModule } = createNestModule({
moduleName: 'AppModule',
environmentsModel: AppEnv,
providers: [AppService],
});
process.env['OPTION'] = 'value1';
bootstrapNestApplication({
modules: {
system: [
DefaultNestApplicationInitializer.forRoot(),
DefaultNestApplicationListener.forRoot({
staticEnvironments: { port: 3000 },
staticConfiguration: {
preListen: async ({ app }) => {
if (app) {
const appService = app.get(AppService);
console.log(appService.getEnv());
}
},
},
}),
],
feature: [AppModule.forRoot()],
},
});
Usage with project name and contextName
isInfrastructureMode,
import {
DefaultNestApplicationInitializer,
DefaultNestApplicationListener,
EnvModel,
EnvModelProperty,
bootstrapNestApplication,
createNestModule,
} from '@nestjs-mod/common';
import { Injectable } from '@nestjs/common';
import { IsNotEmpty } from 'class-validator';
@EnvModel()
class AppEnv {
@EnvModelProperty()
@IsNotEmpty()
option!: string;
}
@Injectable()
class AppService {
constructor(private readonly appEnv: AppEnv) {}
getEnv() {
return this.appEnv;
}
}
const { AppModule } = createNestModule({
moduleName: 'AppModule',
environmentsModel: AppEnv,
providers: [AppService],
});
process.env['TEST_APP_CTX_OPTION'] = 'value1';
bootstrapNestApplication({
project: { name: 'TestApp', description: 'Test application' },
modules: {
system: [
DefaultNestApplicationInitializer.forRoot(),
DefaultNestApplicationListener.forRoot({
staticEnvironments: { port: 3000 },
staticConfiguration: {
preListen: async ({ app }) => {
if (app) {
const appService = app.get(AppService);
console.log(appService.getEnv());
}
},
},
}),
],
feature: [AppModule.forRoot({ contextName: 'CTX' })],
},
});
Back to Top
NestJS module
Function for creating a configurable module with the ability to use multi-providing.
It is possible to create and work with named module instances.
Modules can contain code for creating and managing the application (preWrapApplication, wrapApplication, postWrapApplication).
Type of config or env models used in module:
environmentsModel
- Variables with primitive types used in the module, the values of which can be obtained from various sources, such as: process.env or consul key value.
configurationModel
- Variables of primitive and complex types that are used in the module; values for them must be passed when connecting the module to the application.
staticEnvironmentsModel
- Static variables with primitive types used in the module and can be used at the time of generating module metadata (import, controllers), the values of which can be obtained from various sources, such as: process.env or consul key value.
staticConfigurationModel
- Static variables of primitive and complex types that are used in the module and can be used at the time of generating module metadata (import, controllers); values for them must be passed when connecting the module to the application.
featureConfigurationModel
- Feature variables of primitive and complex types that can be added to the current module from other modules (example: a transport for sending a message can be defined as a generalized interface, but the implementation itself will be added from a module for working with a specific transport or from an integration module).
featureEnvironmentsModel
- Feature variables with primitive types used in the module, the values of which can be obtained from various sources, such as: process.env or consul key value.
Decorators
InjectFeatures
, InjectService
, InjectAllFeatures
, InjectFeatureEnvironments
, InjectAllFeatureEnvironments
Function
createNestModule
, getNestModuleDecorators
Usage
import {
ConfigModel,
ConfigModelProperty,
EnvModel,
EnvModelProperty,
createNestModule,
getNestModuleDecorators,
InjectableFeatureConfigurationType,
} from '@nestjs-mod/common';
import { Injectable } from '@nestjs/common';
import { NestFactory } from '@nestjs/core';
import { IsNotEmpty } from 'class-validator';
const { InjectFeatures } = getNestModuleDecorators({
moduleName: 'App1Module',
});
@ConfigModel()
class AppFeatureConfig {
@ConfigModelProperty()
@IsNotEmpty()
featureOptionConfig!: string;
}
@Injectable()
class AppFeaturesService {
constructor(
@InjectFeatures()
private readonly appFeatureConfigs: InjectableFeatureConfigurationType<AppFeatureConfig>[]
) {}
getFeatureConfigs() {
return this.appFeatureConfigs.map(({ featureConfiguration }) => featureConfiguration);
}
}
const { App1Module } = createNestModule({
moduleName: 'App1Module',
sharedProviders: [AppFeaturesService],
featureConfigurationModel: AppFeatureConfig,
});
@ConfigModel()
class App2Config {
@ConfigModelProperty()
@IsNotEmpty()
option!: string;
}
@Injectable()
class App2Service {
constructor(private readonly appFeaturesService: AppFeaturesService, private readonly app2Config: App2Config) {}
getFeatureConfigs() {
return this.appFeaturesService.getFeatureConfigs();
}
getConfig() {
return this.app2Config;
}
}
const { App2Module } = createNestModule({
moduleName: 'App2Module',
imports: [
App1Module.forFeature({
featureModuleName: 'App2Module',
featureConfiguration: { featureOptionConfig: 'featureOptionConfig-app2' },
}),
],
providers: [App2Service],
configurationModel: App2Config,
});
@EnvModel()
class App3Env {
@EnvModelProperty()
@IsNotEmpty()
option!: string;
}
@Injectable()
class App3Service {
constructor(private readonly appFeaturesService: AppFeaturesService, private readonly app3Env: App3Env) {}
getFeatureConfigs() {
return this.appFeaturesService.getFeatureConfigs();
}
getEnv() {
return this.app3Env;
}
}
const { App3Module } = createNestModule({
moduleName: 'App3Module',
imports: [
App1Module.forFeature({
featureModuleName: 'App2Module',
featureConfiguration: { featureOptionConfig: 'featureOptionConfig-app3' },
}),
],
providers: [App3Service],
environmentsModel: App3Env,
});
const { AppModule } = createNestModule({
moduleName: 'AppModule',
imports: [
App1Module.forRoot(),
App2Module.forRoot({ configuration: { option: 'appConfig3value' } }),
App3Module.forRoot({ environments: { option: 'appEnv2value' } }),
],
});
async function bootstrap() {
const app = await NestFactory.create(AppModule.forRoot());
const appFeatureScannerService = app.get(AppFeaturesService);
const app2Service = app.get(App2Service);
const app3Service = app.get(App3Service);
console.log(appFeatureScannerService.getFeatureConfigs());
console.log(app2Service.getFeatureConfigs());
console.log(app3Service.getFeatureConfigs());
console.log(app2Service.getConfig());
console.log(app3Service.getEnv());
}
bootstrap();
Back to Top
Modules descriptions
Infrastructure markdown report generator.
Use in NestJS-mod
Use with options.
import { bootstrapNestApplication, InfrastructureMarkdownReportGenerator } from '@nestjs-mod/common';
import { join } from 'path';
const appFolder = join(__dirname, '..', '..', '..', 'apps', 'example-basic');
bootstrapNestApplication({
modules: {
infrastructure: [
InfrastructureMarkdownReportGenerator.forRoot({
staticConfiguration: {
markdownFile: join(appFolder, 'INFRASTRUCTURE.MD'),
skipEmptySettings: true,
},
}),
],
},
});
Shared providers
DynamicNestModuleMetadataMarkdownReportGenerator
Static configuration
markdownFile | Name of the markdown-file in which to save the infrastructure report | optional | - | - |
skipEmptySettings | Skip empty values of env and config models | optional | - | - |
Back to Top
Infrastructure markdown report storage
Use in NestJS-mod
Use the forRoot method to create a global report store.
import { bootstrapNestApplication, InfrastructureMarkdownReportStorage } from '@nestjs-mod/common';
bootstrapNestApplication({
modules: {
infrastructure: [InfrastructureMarkdownReportStorage.forRoot()],
},
});
An example of using global storage in a module.
import {
bootstrapNestApplication,
createNestModule,
DefaultNestApplicationInitializer,
DefaultNestApplicationListener,
InfrastructureMarkdownReportGenerator,
InfrastructureMarkdownReportStorage,
InfrastructureMarkdownReportStorageService,
} from '@nestjs-mod/common';
import { Injectable } from '@nestjs/common';
@Injectable()
class AppReportService {
constructor(private readonly infrastructureMarkdownReportStorage: InfrastructureMarkdownReportStorageService) {}
getReport() {
return this.infrastructureMarkdownReportStorage.report;
}
}
const { App1Module } = createNestModule({
moduleName: 'App1Module',
imports: [InfrastructureMarkdownReportStorage.forFeature()],
providers: [AppReportService],
});
bootstrapNestApplication({
modules: {
infrastructure: [InfrastructureMarkdownReportStorage.forRoot(), InfrastructureMarkdownReportGenerator.forRoot()],
system: [
DefaultNestApplicationInitializer.forRoot(),
DefaultNestApplicationListener.forRoot({
staticConfiguration: {
postListen: async ({ app }) => {
if (app) {
const appReportService = app.get(AppReportService);
console.log(appReportService.getReport());
}
},
},
staticEnvironments: { port: 3012 },
}),
],
feature: [App1Module.forRoot()],
},
});
Shared providers
InfrastructureMarkdownReportStorageService
Back to Top
DefaultNestApplicationInitializer
Default NestJS application initializer.
Use in NestJS-mod
Use without options.
import { bootstrapNestApplication, DefaultNestApplicationInitializer } from '@nestjs-mod/common';
bootstrapNestApplication({
modules: {
system: [DefaultNestApplicationInitializer.forRoot()],
},
});
Example of change cors options.
import { bootstrapNestApplication, DefaultNestApplicationInitializer } from '@nestjs-mod/common';
bootstrapNestApplication({
modules: {
system: [
DefaultNestApplicationInitializer.forRoot({
staticConfiguration: {
cors: {
origin: '*',
methods: 'GET,HEAD,PUT,PATCH,POST,DELETE',
preflightContinue: false,
optionsSuccessStatus: 204,
},
},
}),
],
},
});
Static configuration
cors | CORS options from CORS package | optional | {"credentials":true,"methods":"GET,HEAD,PUT,PATCH,POST,DELETE"} | - |
bodyParser | Whether to use underlying platform body parser. | optional | - | - |
httpsOptions | Set of configurable HTTPS options | optional | - | - |
rawBody | Whether to register the raw request body on the request. Use req.rawBody . | optional | - | - |
defaultLogger | Default logger for application | optional | - | - |
logger | Specifies the logger to use. Pass false to turn off logging. | optional | - | - |
abortOnError | Whether to abort the process on Error. By default, the process is exited. Pass false to override the default behavior. If false is passed, Nest will not exit the application and instead will rethrow the exception. @default true | optional | - | - |
bufferLogs | If enabled, logs will be buffered until the "Logger#flush" method is called. @default false | optional | - | - |
autoFlushLogs | If enabled, logs will be automatically flushed and buffer detached when application initialization process either completes or fails. @default true | optional | - | - |
preview | Whether to run application in the preview mode. In the preview mode, providers/controllers are not instantiated & resolved. @default false | optional | - | - |
snapshot | Whether to generate a serialized graph snapshot. @default false | optional | - | - |
forceCloseConnections | Force close open HTTP connections. Useful if restarting your application hangs due to keep-alive connections in the HTTP adapter. | optional | true | - |
Back to Top
DefaultNestApplicationListener
Default NestJS application listener.
Use in NestJS-mod
Use with manual environments and custom configuration.
import {
bootstrapNestApplication,
DefaultNestApplicationInitializer,
DefaultNestApplicationListener,
isInfrastructureMode,
} from '@nestjs-mod/common';
import { Logger } from '@nestjs/common';
bootstrapNestApplication({
modules: {
system: [
DefaultNestApplicationInitializer.forRoot(),
DefaultNestApplicationListener.forRoot({
staticEnvironments: { port: 3000 },
staticConfiguration: {
mode: isInfrastructureMode() ? 'silent' : 'listen',
preListen: async ({ app }) => {
if (app) {
app.setGlobalPrefix('api');
}
},
postListen: async ({ current }) => {
Logger.log(
`π Application is running on: http://${current.staticEnvironments?.hostname || 'localhost'}:${
current.staticEnvironments?.port
}/api`
);
},
},
}),
],
},
});
Static environments
port | The port on which to run the server. | obj['port'] , process.env['PORT'] | isNotEmpty (port should not be empty) | - | - |
hostname | Hostname on which to listen for incoming packets. | obj['hostname'] , process.env['HOSTNAME'] | optional | - | - |
Static configuration
mode | Mode of start application: init - for run NestJS life cycle, listen - for full start NestJS application | optional | listen | - |
preListen | Method for additional actions before listening | optional | - | - |
postListen | Method for additional actions after listening | optional | - | - |
defaultLogger | Default logger for application | optional | - | - |
enableShutdownHooks | Enable shutdown hooks | optional | true | - |
globalPrefix | Global prefix | optional | api | - |
logApplicationStart | Log application start | optional | true | - |
Back to Top
ProjectUtils
Utilities for setting global application parameters, such as project name, description, and settings validation parameters.
Use in NestJS-mod
Use with options.
import { DOT_ENV_FILE, PACKAGE_JSON_FILE, ProjectUtils, bootstrapNestApplication } from '@nestjs-mod/common';
import { join } from 'path';
const rootFolder = join(__dirname, '..', '..', '..');
const appFolder = join(rootFolder, 'apps', 'example-basic');
bootstrapNestApplication({
modules: {
system: [
ProjectUtils.forRoot({
staticConfiguration: {
applicationPackageJsonFile: join(appFolder, PACKAGE_JSON_FILE),
packageJsonFile: join(rootFolder, PACKAGE_JSON_FILE),
envFile: join(rootFolder, DOT_ENV_FILE),
},
}),
],
},
});
An example of access to module services with forFeature.
import {
DOT_ENV_FILE,
DefaultNestApplicationInitializer,
DefaultNestApplicationListener,
DotEnvService,
PACKAGE_JSON_FILE,
ProjectUtils,
bootstrapNestApplication,
createNestModule,
} from '@nestjs-mod/common';
import { Injectable } from '@nestjs/common';
import { join } from 'path';
@Injectable()
class GetEnv {
constructor(private readonly dotEnvService: DotEnvService) {}
getEnv() {
return this.dotEnvService.read();
}
getKeys() {
return this.dotEnvService.keys(true);
}
}
const { AppModule } = createNestModule({
moduleName: 'AppModule',
imports: [ProjectUtils.forFeature()],
providers: [GetEnv],
});
const rootFolder = join(__dirname, '..', '..', '..');
const appFolder = join(rootFolder, 'apps', 'example-basic');
process.env.TEST_APP_PORT = '2000';
process.env.TEST_APP_HOSTNAME = 'host';
bootstrapNestApplication({
project: {
name: 'test-app',
description: 'Description for test-app',
},
globalEnvironmentsOptions: { debug: true },
modules: {
system: [
ProjectUtils.forRoot({
staticConfiguration: {
applicationPackageJsonFile: join(appFolder, PACKAGE_JSON_FILE),
envFile: join(rootFolder, DOT_ENV_FILE),
},
}),
DefaultNestApplicationInitializer.forRoot(),
DefaultNestApplicationListener.forRoot({
staticConfiguration: {
mode: 'silent',
postListen: async ({ app }) => {
if (app) {
const getEnv = app.get(GetEnv);
console.log(await getEnv.getEnv());
}
},
},
}),
],
feature: [AppModule.forRoot()],
},
});
When launched in the infrastructure documentation generation mode, the module creates an .env
file with a list of all required variables, as well as an example example.env
, where you can enter example variable values.
Shared providers
WrapApplicationOptionsService
, DotEnvService
, PackageJsonService
, ApplicationPackageJsonService
, GitignoreService
, NxProjectJsonService
, ProjectUtilsPatcherService
Static configuration
applicationPackageJsonFile | Application package.json-file | optional | - | - |
packageJsonFile | Root package.json-file | optional | - | - |
nxProjectJsonFile | Application project.json-file (nx) | optional | - | - |
envFile | Dot-env file with environment variables | optional | - | - |
updateEnvFile | Update env-file | optional | true | - |
updateProjectOptions | Update project properties | optional | true | - |
updateGlobalConfigurationAndEnvironmentsOptions | Update configuration and environments options | optional | true | - |
Back to Top
Links
License
MIT