Table of Contents

1. About The Project
   • Built With
2. Getting Started
   • Installation
3. Usage
   • Create DTO File
     • Request Schema
     • Response Schema
     • Full Schema Example
   • Options
   • Method 1
     • Injection process
     • With App
     • With app.Route
     • With app.Router
     • With router.Route
   • Method 2
     • Middleware With App
     • Middleware With app.Route
     • Middleware With app.Router
     • Middleware With router.Route
4. Roadmap
5. Contributing
6. License
7. Contact

About The Project

We use the Mongoose Model.validate() method for validation and the Mongoose Document.toJSON() method for filtering. If you have previous experience with Mongoose, this module will be a breeze for you :smile:

We are currently working on further development to enable automatic Swagger integration through DTO schemas.

• Please note that this module can only be used with Express.

Built With

We express our gratitude to Mongoose for its excellent validation mechanism.
We thank the UUID team for providing a simple and useful package.

Getting Started

This is an example of how you may give instructions on setting up your project locally. To get a local copy up and running follow these simple example steps.

Installation

1npm install express-dto

1yarn add express-dto

Usage

You can utilize this module in two different ways. Examples are provided for both methods.

• The Express-dto module is only applicable to the "POST," "PUT," "PATCH," "GET," and "DELETE" HTTP methods.

Method 1

Using Router methods encapsulating Express methods.

1import express, { Router } from "express";
2import { Inject } from "express-dto";
3
4// Your DTO files
5import { GetUserDto, UpdateUserDto, AddUserDto } from "./dtos";
6import CreateAddressDto from "./createAddress.dto.ts";
7import DeleteAddressDto from "./deleteAddress.dto.json";

Injection process

1const options = {
2  auth: undefined,
3  permissions: undefined,
4  schemaKey: "$key",
5  filter: {
6    request: true,
7    response: true,
8  },
9  validate: {
10    request: true,
11    response: false,
12  },
13  onReqError: undefined,
14  onResError: undefined,
15};
16
17Inject(express, options);

With app

1const app = express();
2
3app.$post("/create-user", AddUserDto, (req, res) => {
4  res.send(req.body);
5});
6
7app.$patch("/update-user", UpdateUserDto, (req, res) => {
8  res.send(req.body);
9});
10
11app.$put("/add-address", CreateAddressDto, (req, res) => {
12  res.send(req.body);
13});
14
15app.$get("/get-user", GetUserDto, (req, res) => {
16  res.send(req.query);
17});
18
19app.$delete("/delete-address", DeleteAddressDto, (req, res) => {
20  res.send(req.query);
21});

With app.Route

1const route = app.route("/user");
2route
3  .$post(AddUserDto, (req, res) => {
4    res.send(req.body);
5  })
6  .$patch(UpdateUserDto, (req, res) => {
7    res.send(req.body);
8  })
9  .$put(CreateAddressDto, (req, res) => {
10    res.send(req.body);
11  })
12  .$get(GetUserDto, (req, res) => {
13    res.send(req.query);
14  })
15  .$delete(DeleteAddressDto, (req, res) => {
16    res.send(req.query);
17  });

With app.Router

1const router = Router();
2
3router.$post("/create-user", AddUserDto, (req, res) => {
4  res.send(req.body);
5});
6
7router.$patch("/update-user", UpdateUserDto, (req, res) => {
8  res.send(req.body);
9});
10
11router.$put("/add-address", CreateAddressDto, (req, res) => {
12  res.send(req.body);
13});
14
15router.$get("/get-user", GetUserDto, (req, res) => {
16  res.send(req.query);
17});
18
19router.$delete("/delete-address", DeleteAddressDto, (req, res) => {
20  res.send(req.query);
21});

With router.Route

1const router = new Router();
2const route = router.route("/user");
3route
4  .$post(AddUserDto, (req, res) => {
5    res.send(req.body);
6  })
7  .$patch(UpdateUserDto, (req, res) => {
8    res.send(req.body);
9  })
10  .$put(CreateAddressDto, (req, res) => {
11    res.send(req.body);
12  })
13  .$get(GetUserDto, (req, res) => {
14    res.send(req.query);
15  })
16  .$delete(DeleteAddressDto, (req, res) => {
17    res.send(req.query);
18  });

Method 2

As a simple Express middleware.

1import express, { Router } from "express";
2import DTO from "express-dto";
3
4// Your DTO files
5import { GetUserDto, UpdateUserDto, AddUserDto } from "./dtos";
6import CreateAddressDto from "./createAddress.dto.ts";
7import DeleteAddressDto from "./deleteAddress.dto.json";

Middleware With app

1const app = express();
2
3const { middleware } = new DTO(AddUserDto.schemas, AddUserDto.options);
4
5app.post("/create-user", middleware, (req, res) => {
6  res.send(req.body);
7});
8
9const { m } = new DTO(UpdateUserDto.schemas);
10
11app.patch("/update-user", m, (req, res) => {
12  res.send(req.body);
13});
14
15const createAddressDTO = new DTO(CreateAddressDto.schemas);
16
17app.put("/add-address", createAddress.middleware, (req, res) => {
18  res.send(req.body);
19});
20
21const getUserDTO = new DTO(GetUserDto.schemas);
22
23app.get("/get-user", getUserDTO.m, (req, res) => {
24  res.send(req.query);
25});
26
27const deleteAddressDTO = new DTO(DeleteAddressDto.schemas);
28
29app.delete("/delete-address", deleteAddressDTO.middleware, (req, res) => {
30  res.send(req.query);
31});

Middleware With app.Route

1const { middleware } = new DTO(AddUserDto.schemas);
2const { m } = new DTO(UpdateUserDto.schemas);
3const createAddressDTO = new DTO(CreateAddressDto.schemas);
4const getUserDTO = new DTO(GetUserDto.schemas);
5const deleteAddressDTO = new DTO(DeleteAddressDto.schemas);
6
7const route = app.route("/user");
8route
9  .$post(middleware, (req, res) => {
10    res.send(req.body);
11  })
12  .$patch(m, (req, res) => {
13    res.send(req.body);
14  })
15  .$put(createAddressDTO.middleware, (req, res) => {
16    res.send(req.body);
17  })
18  .$get(getUserDTO.m, (req, res) => {
19    res.send(req.query);
20  })
21  .$delete(deleteAddressDTO.middleware, (req, res) => {
22    res.send(req.query);
23  });

Middleware With app.Router

1const router = Router();
2
3const { middleware } = new DTO(AddUserDto.schemas);
4
5router.post("/create-user", middleware, (req, res) => {
6  res.send(req.body);
7});
8
9const { m } = new DTO(UpdateUserDto.schemas);
10
11router.patch("/update-user", m, (req, res) => {
12  res.send(req.body);
13});
14
15const createAddressDTO = new DTO(CreateAddressDto.schemas);
16
17router.put("/add-address", createAddress.middleware, (req, res) => {
18  res.send(req.body);
19});
20
21const getUserDTO = new DTO(GetUserDto.schemas);
22
23router.get("/get-user", getUserDTO.m, (req, res) => {
24  res.send(req.query);
25});
26
27const deleteAddressDTO = new DTO(DeleteAddressDto.schemas);
28
29router.delete("/delete-address", deleteAddressDTO.middleware, (req, res) => {
30  res.send(req.query);
31});

Middleware With router.Route

1const { middleware } = new DTO(AddUserDto.schemas);
2const { m } = new DTO(UpdateUserDto.schemas);
3const createAddressDTO = new DTO(CreateAddressDto.schemas);
4const getUserDTO = new DTO(GetUserDto.schemas);
5const deleteAddressDTO = new DTO(DeleteAddressDto.schemas);
6
7const router = new Router();
8const route = router.route("/user");
9
10route
11  .$post(middleware, (req, res) => {
12    res.send(req.body);
13  })
14  .$patch(m, (req, res) => {
15    res.send(req.body);
16  })
17  .$put(createAddressDTO.middleware, (req, res) => {
18    res.send(req.body);
19  })
20  .$get(getUserDTO.m, (req, res) => {
21    res.send(req.query);
22  })
23  .$delete(deleteAddressDTO.middleware, (req, res) => {
24    res.send(req.query);
25  });

Options

Settings fields marked "Will be available in the future" are settings fields created for future updates, we recommend that you use them now.

Field	Type	Default	Description
auth	function or undefined	undefined	Checks the user's permission to use the entpoint (Will be available in the future)
permissions	object or undefined	undefined	Checks the user's permission to use the entpoint (Will be available in the future)
schemaKey	string	$key	Allows you to create schema for non-object responses
filter	object	filterObject	Sets filtering status.
filter.request	boolean	true	Changes the request body according to the dto definition
filter.response	boolean	false	Changes the response body according to the dto definition
validate	object	validateObject	Sets validation status.
validate.request	boolean	true	Validate the request body according to the dto definition
validate.response	boolean	true	Validate the response body according to the dto definition
onReqError	function or undefined	undefined	Function to be triggered when request validation error occurs
onResError	function or undefined	undefined	Function to be triggered when response validation error occurs
onACLError	function or undefined	undefined	Function to be triggered when non-permission error occurs

Default Option Object

1{
2  auth: undefined,
3  permissions: undefined,
4  schemaKey: "$key",
5  filter: {
6    request: true,
7    response: true,
8  },
9  validate: {
10    request: true,
11    response: false,
12  },
13  onReqError: undefined,
14  onResError: undefined,
15  onACLError: undefined,
16}

Full Option Example

1const options = {
2  auth: (req) => {
3    try {
4      req.jwt = null;
5      if (!req.headers.auth || typeof req.headers.auth !== "string") {
6        return false;
7      }
8
9      const auth = req.headers.auth.split(" ");
10
11      if (auth[0] !== "Bearer" || !auth[1]) {
12        return false;
13      }
14
15      req.jwt = jwt.verify(auth[1], config.jwtKey);
16
17      if (result) {
18        return req.jwt.permissions;
19      } else {
20        return false;
21      }
22    } catch (err) {
23      req.jwt = null;
24      return false;
25    }
26  },
27  permissions: {
28    user: ["read", "write"], // OR user:'reader'
29  },
30  schemaKey: "$custom",
31  filter: {
32    request: true,
33    response: true,
34  },
35  validate: {
36    request: true,
37    response: true,
38  },
39  onReqError(req, res, next, message) {
40    next(message);
41  },
42  onResError: (req, res, next, message) => {
43    res.status(500).send({
44      message: "Please contact the development team",
45      code: "001",
46    });
47  },
48  onACLError(req, res, next, message) {
49    res.status(401).json({
50      message: "You are not authorized",
51      code: "002",
52    });
53  },
54};

Methods

DTO

1import DTO from "express-dto";
2
3const { middleware } = new DTO(schemas, options);

Inject

1import express from "express";
2import { Inject } from "express-dto";
3
4Inject(express, options);

SetDefaults

1import { SetDefaults } from "express-dto";
2
3SetDefaults(options);

Create DTO File

1export default {
2  schemas:{
3    title: "Register",
4    description: "Create new user",
5    groups: ["auth"],
6    request: requestSchema
7    response: responseSchemas
8  },
9  options: optionObject
10}

Request Schema

1export default {
2  title: "Register",
3  description: "Create new user",
4  schema: Mongoose.Schema.definition,
5};

Response Schema

1export default {
2  title: "Register",
3  description: "Create new user",
4  schemas: {
5    201: {
6      title: "User Created",
7      description: "If user created successfully",
8      schema: { $key: { type: String } },
9    },
10    400: {
11      title: "User not created",
12      description: "If user not created",
13      schema: { code: { type: String, default: "AUTHX004" } },
14    },
15    409: [
16      {
17        title: "Conflict",
18        description: "If email already exists",
19        schema: {
20          username: { type: String },
21          code: { type: String, default: "ERRORx001" },
22        },
23      },
24      {
25        title: "Conflict",
26        description: "If username already exists",
27        schema: {
28          username: { type: String },
29          code: { type: String, default: "ERRORx001" },
30        },
31      },
32    ],
33  },
34};

Full Schema Example

1import { Document } from "mongoose";
2import validator from "validator";
3import { ErrorMessage, Request, Response, NextFunction } from "../src/types";
4export interface IRequestDocument extends Document {
5  photo: string;
6  language: string;
7  name: string;
8  middleName?: string;
9  surname: string;
10  username?: string;
11  email?: string;
12  phone?: string;
13  password: string;
14  refCode?: string;
15}
16
17const schemas = {
18  title: "Register",
19  description: "Create new user",
20  groups: ["auth"],
21  request: {
22    title: "Register",
23    description: "Create new user",
24    schema: {
25      photo: { type: String, default: "/defaults/profile.png", required: true },
26      language: {
27        type: String,
28        enum: ["en", "tr", "ru"],
29        default: "en",
30      },
31      name: {
32        type: String,
33        required: true,
34      },
35      middleName: {
36        type: String,
37      },
38      surname: {
39        type: String,
40        required: true,
41      },
42      username: {
43        type: String,
44        required(this: IRequestDocument) {
45          return !this.email && !this.phone;
46        },
47      },
48      email: {
49        type: String,
50        required(this: IRequestDocument) {
51          return !this.username && !this.phone;
52        },
53        validate: {
54          validator: (value: string) => validator.isEmail(value),
55          message: "email",
56        },
57      },
58      phone: {
59        type: String,
60        required(this: IRequestDocument) {
61          return !this.email && !this.username;
62        },
63        validate: {
64          validator: (value: string) =>
65            validator.isMobilePhone(value, undefined, { strictMode: true }),
66          message: "phone",
67        },
68      },
69      password: {
70        type: String,
71        required: true,
72      },
73      refCode: {
74        description: "Referral Code",
75        type: String,
76      },
77    },
78  },
79  response: {
80    schemas: {
81      201: {
82        title: "User Created",
83        description: "If user created successfully",
84        schema: { id: { type: String } },
85      },
86      400: {
87        title: "User not created",
88        description: "If user not created",
89        schema: { code: { type: String, default: "AUTHX004" } },
90      },
91      409: [
92        {
93          title: "Conflict",
94          description: "If email already exists",
95          schema: {
96            username: { type: String },
97            code: { type: String, default: "ERRORx001" },
98          },
99        },
100        {
101          title: "Conflict",
102          description: "If username already exists",
103          schema: {
104            username: { type: String },
105            code: { type: String, default: "ERRORx001" },
106          },
107        },
108      ],
109    },
110  },
111};
112
113const options = {
114  filter: {
115    request: true,
116    response: true,
117  },
118  validate: {
119    request: true,
120    response: true,
121  },
122  onReqError(
123    _req: Request,
124    _res: Response,
125    next: NextFunction,
126    message: ErrorMessage
127  ) {
128    next(message);
129  },
130  onResError(
131    _req: Request,
132    res: Response,
133    _next: NextFunction,
134    message: ErrorMessage
135  ) {
136    res.send({
137      message: "Please contact the development team",
138      code: message.code,
139    });
140  },
141};
142
143export default { schemas, options };

Roadmap

• Add Request Validation
• Add Response Validation
• Add Data Filter
• Add Router Medhods
• Add ACL Integration
• Add Swagger Integration

See the open issues for a full list of proposed features (and known issues).

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

License

Distributed under the MIT License. See LICENSE for more information.

Contact

Rohan Acar :wave: hi@rohanacar.com

Project Link: https://github.com/rohanacar/express-dto