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

1import { Application } from '@tsrt/tsed';
2import { Logger } from 'path/to/your/logger';
3
4const port = 3333;
5const apiBase = '/api/v1';
6const log = new Logger();
7
8new Application({
9  port,
10  apiBase,
11  log,
12  mount: {
13    [apiBase]: `${__dirname}/controllers/**/*.ts`,
14  },
15  middlewares: {
16    [apiBase]: [...],
17  },
18  statics: {
19    '/assets': '...',
20  },
21  webApps: `${__dirname}/client/index.html`,
22  ...
23})
24  .start(() => log.info(`Server started on port: ${port}. Pid: ${process.pid}'));

API Reference

1export declare class Application {
2  settings: IApplicationSettings;
3
4  /** Starts Application. */
5  start(cb?: Callback): Promise<void>;
6
7  /** Application middlewares/config manual setup (which is done by default under `start` method). */
8  manualSetup(settings?: IApplicationManualSetupSettings): IApplicationManualSetup;
9
10  /** Proxy to native Express App `set` method */
11  set(setting: string, value: any): this;
12
13  /** Proxy to native Express App `use` method */
14  use(...handlers: any[]): IApplicationManualSetup;
15
16  /** Proxy to native Express App `use` method, w/ ability to use before one of `IApplicationMethods` methods. */
17  useBefore(methodName: keyof IApplicationMethods, ...handlers: any[]): IApplicationManualSetup;
18}
19
20export interface IApplicationManualSetup extends IApplicationMethods {
21  /** Proxy to native Express App `set` method */
22  set(setting: string, value: any): this;
23
24  /** Proxy to native Express App `use` method */
25  use(...handlers: any[]): IApplicationManualSetup;
26
27  /** Proxy to native Express App `use` method, w/ ability to use before one of `IApplicationMethods` methods. */
28  useBefore(methodName: keyof IApplicationMethods, ...handlers: any[]): IApplicationManualSetup;
29
30  /** Setups all middlewares and settings (which are used under this method) at once. */
31  setupAll(): IApplicationManualSetup;
32
33  /** Proxy to public Application `start` method */
34  start(cb?: Callback): void;
35
36  /** Sets query parser for App. */
37  setupQueryParser(cb?: (str: string) => any): IApplicationManualSetup;
38
39  /** Sets default middlewares: cors, helmet, bodyparser, ... etc */
40  setupDefaultExpressMiddlewares(): IApplicationManualSetup;
41
42  /** Sets handler for attaching request id for each request. */
43  setupRequestIdMiddleware(): IApplicationManualSetup;
44
45  /** Sets session middleware. */
46  setupSession(sessionConfig?: IApplicationSession): IApplicationManualSetup;
47
48  /** Sets send response pathcer middleware (pathces `send` function before sending response). */
49  setupSendResponseHandler(handler?: IApplicationSendResponseHandler): IApplicationManualSetup;
50
51  /** Sets custom middlewares provide via `options` or via `addMiddlewares` method. */
52  setupMiddlewares(middlewares?: ApplicationMiddlewareList): IApplicationManualSetup;
53
54  /** Sets notFoundHandler. */
55  setupNotFoundHandler(handler?: RequestHandler): IApplicationManualSetup;
56
57  /** Sets webApps statics and serving. */
58  setupWebApps(webApps?: ApplicationWebApps): IApplicationManualSetup;
59
60  /** Sets global request handler. */
61  setupGlobalErrorHandler(handler?: ErrorRequestHandler): IApplicationManualSetup;
62}
63
64export interface IApplicationManualSetupSettings {
65  /** Whether to use not called manually default methods. @default true. */
66  useMethodsByDefault?: boolean;
67}

Settings (Declarative API reference)

1export interface IApplicationSettings extends Partial<Configuration> {
2  /** Custom application logger. It should implement at least 2 methods: `info` and `error`. */
3  log?: IApplicationLogger;
4
5  /**
6   *  Debug mode.
7   *
8   *  @enum - TsED: full debug + TsED full debug.
9   *  @enum - Application: Only debug for server start (hooks/middlewares iitialization).
10   */
11  debugMode?: 'TsED' | 'Application';
12
13  /** Port to listen. */
14  port?: number | string;
15
16  /** Base api path/pathes. This one is necessary for registering default notFound, globalError and other middlewares. */
17  apiBase?: ApplicationPaths;
18
19  /** List of statics dirs, or object w/ key - route path, and value - statics dir. */
20  // statics?: ApplicationStatics;
21
22  /** Same as for static, but also for serving webApps. */
23  webApps?: ApplicationWebApps;
24
25  /** Cors options. @see https://www.npmjs.com/package/cors */
26  cors?: CorsOptions;
27
28  /** Query parser options. @see https://www.npmjs.com/package/qs */
29  qs?: IParseOptions;
30
31  /** Helmep options @see https://www.npmjs.com/package/helmet */
32  helmet?: IHelmetConfiguration;
33
34  /** Register default middlewares here. */
35  middlewares?: ApplicationMiddlewareList;
36
37  /** Session options. @see https://www.npmjs.com/package/express-session */
38  session?: IApplicationSession;
39
40  /** Whether to use default controllers. They will be mounted under apiBase path(s). 2 controllers - server info and health check. */
41  useDefaultControllers?: boolean;
42
43  /** Middleware to be used instead of default `NotFoundHandler`. Could be also overriden by `OverrideProvider`. */
44  notFoundHandler?: ApplicationMiddleware;
45
46  /** Middleware to be used instead of default `GlobalErrorHandler`. Could be also overriden by `OverrideProvider`. */
47  globalErrorHandler?: ApplicationErrorMiddleware;
48
49  /** Method to be used in as responseFilter of TsED. Should implement `ResponseFilterMethods` interface. */
50  sendResponseHandler?: Constructor;
51
52  /** Whether to set swagger api-docs for `apiBase` if only 1 string value provided for it. @default false. */
53  setSwaggerForApiBaseByDefault?: boolean;
54
55  /**
56   *  Whether to patch `class-validator` validators without groups and set `always: true` for them.
57   *  This will allow to provide groups for some validators and they will be validated only for that groups,
58   *  which should also be provided as `validationGroups` options for BodyParams decorator (if `patchBodyParamsDecorator: true`).
59   *
60   *  @default true.
61   *
62   *  @example
63   *  ```ts
64   *  class UpdateDto {
65   *    @Property() @IsOptional({ groups: ['update'] }) @IsString() id: string;
66   *    @Property() @IsString() name: string;
67   *  }
68   *
69   *  class CreateDto extends UpdateDto {
70   *    @Required() id: string;
71   *  }
72   *
73   * @Get('/')
74   * public async create(@BodyParams() body: CreateDto) { ... }
75   *
76   * public async update(@BodyParams({ validationGroups: ['update'] }) body: CreateDto) { ... }
77   *  ```
78   */
79  patchValidatorsWithoutGroups?: boolean;
80
81  /** Whether to parse types validating body. @default true. */
82  parseBodyTypesAfterValidation?: boolean;
83
84  /** Whether to parse types of server response. @default false. */
85  parseResponseTypes?: boolean;
86
87  /** `class-validator` options for validation pipe. @default { whitelist: true, forbidNonWhitelisted: true }. */
88  validationOptions?: ValidatorOptions;
89
90  /** List of TsED `ParamTypes` to validate in ValidationPipe. @default all. */
91  validationParamTypes?: Array<ParamTypes | string>;
92
93  /** `class-transformer` options for `DeserializerPipe`. */
94  deserializerOptions?: ClassTransformOptions;
95}
96
97export interface IApplicationLogger {
98  debug(data: any, ...args: any[]): any;
99  info(data: any, ...args: any[]): any;
100  warn?(data: any, ...args: any[]): any;
101  error(data: any, ...args: any[]): any;
102}

License

This project is licensed under the terms of the MIT license.