README
Common TsED Application
Basic configurable Application built on top of awesome TsED framework.
All necessary/common middlewares and configs are setted by default under the hood w/ ability to rewrite/disable/enable them using settings.
Important
Until version 1.0.0 Api should be considered as unstable and may be changed.
So prefer using exact version instead of version with ~
or ^
.
Usage
import { Application } from '@tsrt/tsed';
import { Logger } from 'path/to/your/logger';
const port = 3333;
const apiBase = '/api/v1';
const log = new Logger();
new Application({
port,
apiBase,
log,
mount: {
[apiBase]: `${__dirname}/controllers/**/*.ts`,
},
middlewares: {
[apiBase]: [...],
},
statics: {
'/assets': '...',
},
webApps: `${__dirname}/client/index.html`,
...
})
.start(() => log.info(`Server started on port: ${port}. Pid: ${process.pid}'));
API Reference
export declare class Application {
settings: IApplicationSettings;
/** Starts Application. */
start(cb?: Callback): Promise<void>;
/** Application middlewares/config manual setup (which is done by default under `start` method). */
manualSetup(settings?: IApplicationManualSetupSettings): IApplicationManualSetup;
/** Proxy to native Express App `set` method */
set(setting: string, value: any): this;
/** Proxy to native Express App `use` method */
use(...handlers: any[]): IApplicationManualSetup;
/** Proxy to native Express App `use` method, w/ ability to use before one of `IApplicationMethods` methods. */
useBefore(methodName: keyof IApplicationMethods, ...handlers: any[]): IApplicationManualSetup;
}
export interface IApplicationManualSetup extends IApplicationMethods {
/** Proxy to native Express App `set` method */
set(setting: string, value: any): this;
/** Proxy to native Express App `use` method */
use(...handlers: any[]): IApplicationManualSetup;
/** Proxy to native Express App `use` method, w/ ability to use before one of `IApplicationMethods` methods. */
useBefore(methodName: keyof IApplicationMethods, ...handlers: any[]): IApplicationManualSetup;
/** Setups all middlewares and settings (which are used under this method) at once. */
setupAll(): IApplicationManualSetup;
/** Proxy to public Application `start` method */
start(cb?: Callback): void;
/** Sets query parser for App. */
setupQueryParser(cb?: (str: string) => any): IApplicationManualSetup;
/** Sets default middlewares: cors, helmet, bodyparser, ... etc */
setupDefaultExpressMiddlewares(): IApplicationManualSetup;
/** Sets handler for attaching request id for each request. */
setupRequestIdMiddleware(): IApplicationManualSetup;
/** Sets session middleware. */
setupSession(sessionConfig?: IApplicationSession): IApplicationManualSetup;
/** Sets send response pathcer middleware (pathces `send` function before sending response). */
setupSendResponseHandler(handler?: IApplicationSendResponseHandler): IApplicationManualSetup;
/** Sets custom middlewares provide via `options` or via `addMiddlewares` method. */
setupMiddlewares(middlewares?: ApplicationMiddlewareList): IApplicationManualSetup;
/** Sets notFoundHandler. */
setupNotFoundHandler(handler?: RequestHandler): IApplicationManualSetup;
/** Sets webApps statics and serving. */
setupWebApps(webApps?: ApplicationWebApps): IApplicationManualSetup;
/** Sets global request handler. */
setupGlobalErrorHandler(handler?: ErrorRequestHandler): IApplicationManualSetup;
}
export interface IApplicationManualSetupSettings {
/** Whether to use not called manually default methods. @default true. */
useMethodsByDefault?: boolean;
}
Settings (Declarative API reference)
export interface IApplicationSettings extends Partial<Configuration> {
/** Custom application logger. It should implement at least 2 methods: `info` and `error`. */
log?: IApplicationLogger;
/**
* Debug mode.
*
* @enum - TsED: full debug + TsED full debug.
* @enum - Application: Only debug for server start (hooks/middlewares iitialization).
*/
debugMode?: 'TsED' | 'Application';
/** Port to listen. */
port?: number | string;
/** Base api path/pathes. This one is necessary for registering default notFound, globalError and other middlewares. */
apiBase?: ApplicationPaths;
/** List of statics dirs, or object w/ key - route path, and value - statics dir. */
// statics?: ApplicationStatics;
/** Same as for static, but also for serving webApps. */
webApps?: ApplicationWebApps;
/** Cors options. @see https://www.npmjs.com/package/cors */
cors?: CorsOptions;
/** Query parser options. @see https://www.npmjs.com/package/qs */
qs?: IParseOptions;
/** Helmep options @see https://www.npmjs.com/package/helmet */
helmet?: IHelmetConfiguration;
/** Register default middlewares here. */
middlewares?: ApplicationMiddlewareList;
/** Session options. @see https://www.npmjs.com/package/express-session */
session?: IApplicationSession;
/** Whether to use default controllers. They will be mounted under apiBase path(s). 2 controllers - server info and health check. */
useDefaultControllers?: boolean;
/** Middleware to be used instead of default `NotFoundHandler`. Could be also overriden by `OverrideProvider`. */
notFoundHandler?: ApplicationMiddleware;
/** Middleware to be used instead of default `GlobalErrorHandler`. Could be also overriden by `OverrideProvider`. */
globalErrorHandler?: ApplicationErrorMiddleware;
/** Method to be used in as responseFilter of TsED. Should implement `ResponseFilterMethods` interface. */
sendResponseHandler?: Constructor;
/** Whether to set swagger api-docs for `apiBase` if only 1 string value provided for it. @default false. */
setSwaggerForApiBaseByDefault?: boolean;
/**
* Whether to patch `class-validator` validators without groups and set `always: true` for them.
* This will allow to provide groups for some validators and they will be validated only for that groups,
* which should also be provided as `validationGroups` options for BodyParams decorator (if `patchBodyParamsDecorator: true`).
*
* @default true.
*
* @example
* ```ts
* class UpdateDto {
* @Property() @IsOptional({ groups: ['update'] }) @IsString() id: string;
* @Property() @IsString() name: string;
* }
*
* class CreateDto extends UpdateDto {
* @Required() id: string;
* }
*
* @Get('/')
* public async create(@BodyParams() body: CreateDto) { ... }
*
* public async update(@BodyParams({ validationGroups: ['update'] }) body: CreateDto) { ... }
* ```
*/
patchValidatorsWithoutGroups?: boolean;
/** Whether to parse types validating body. @default true. */
parseBodyTypesAfterValidation?: boolean;
/** Whether to parse types of server response. @default false. */
parseResponseTypes?: boolean;
/** `class-validator` options for validation pipe. @default { whitelist: true, forbidNonWhitelisted: true }. */
validationOptions?: ValidatorOptions;
/** List of TsED `ParamTypes` to validate in ValidationPipe. @default all. */
validationParamTypes?: Array<ParamTypes | string>;
/** `class-transformer` options for `DeserializerPipe`. */
deserializerOptions?: ClassTransformOptions;
}
export interface IApplicationLogger {
debug(data: any, ...args: any[]): any;
info(data: any, ...args: any[]): any;
warn?(data: any, ...args: any[]): any;
error(data: any, ...args: any[]): any;
}
License
This project is licensed under the terms of the MIT license.