📚 Express Route Tracker with HATEOAS

Express Route Tracker A lightweight library for Express.js that adds route tracking and HATEOAS (Hypermedia as the Engine of Application State) capabilities to your API.

---

📷 Example Screenshot

Example Project Node.js express typescript

https://github.com/phamhung075/AIanalist

Example Project Bun express typescript

https://github.com/phamhung075/AIanalist

---

Quick Start

1. Installation

1npm install express-route-tracker
2# or
3yarn add express-route-tracker

2. Basic Setup

1// src/app.ts
2import { RouteDisplay } from 'express-route-tracker';
3import express from 'express';
4
5const app = express();
6app.use("/", router);
7
8// Display all routes in console when starting the app
9const routeDisplay = new RouteDisplay(app);
10routeDisplay.displayRoutes();

1//src\modules\index.ts
2import { Request, Response, NextFunction } from 'express';
3import { Router } from 'express';
4
5const router = Router();
6
7
8router.use('/api/contact', require('./contact'));  //<-- need add this line for each module
9
10// router.use('/v1/api/error', require('./error'));
11router.post('/', (_req: Request, res: Response, _next: NextFunction) => {
12	return res.status(200).json({
13		message: 'Welcome !'
14	})
15});
16
17
18export default router;

3. Creating Routes basic (option 1)

In your route module (e.g., src/modules/contact/index.ts):

1// src/modules/contact/index.ts
2import { createHATEOASMiddleware, createRouter } from 'express-route-tracker';
3import {
4  createContactHandler,
5  deleteContactHandler,
6  getAllContactsHandler,
7  getContactByIdHandler,
8  updateContactHandler
9} from './contact.handler';
10import { asyncHandler } from '@/_core/helper/asyncHandler';
11import { config } from '@/_core/config/dotenv.config';
12
13// Create router with source tracking
14const router = createRouter(__filename);  // replace const router = express.Router();
15
16// Define routes without baseApi prefix
17router.post('/', asyncHandler(createContactHandler));
18router.get('/', asyncHandler(getAllContactsHandler));
19router.get('/:id', asyncHandler(getContactByIdHandler));
20router.put('/:id', asyncHandler(updateContactHandler));
21router.delete('/:id', asyncHandler(deleteContactHandler));
22
23export = router;  // replace export default router;

3. Creating Routes with HATEOAS (option 2)

In your route module (e.g., src/modules/contact/index.ts):

1// src/modules/contact/index.ts
2import { createHATEOASMiddleware, createRouter } from 'express-route-tracker';
3import {
4  createContactHandler,
5  deleteContactHandler,
6  getAllContactsHandler,
7  getContactByIdHandler,
8  updateContactHandler
9} from './contact.handler';
10import { asyncHandler } from '@/_core/helper/asyncHandler';
11import { config } from '@/_core/config/dotenv.config';
12
13// Create router with source tracking
14const router = createRouter(__filename);  // replace const router = express.Router();
15
16router.use(createHATEOASMiddleware(router, {
17  autoIncludeSameRoute: true,
18  baseUrl: config.baseUrl,
19  includePagination: true,
20  customLinks: {
21      documentation: (_req) => ({
22          rel: 'documentation',
23          href: config.baseUrl+'/docs',
24          method: 'GET',
25          'title': 'API Documentation'
26      })
27  }
28}));
29
30// Define routes without baseApi prefix
31router.post('/', asyncHandler(createContactHandler));
32router.get('/', asyncHandler(getAllContactsHandler));
33router.get('/:id', asyncHandler(getContactByIdHandler));
34router.put('/:id', asyncHandler(updateContactHandler));
35router.delete('/:id', asyncHandler(deleteContactHandler));
36
37export = router;  // replace export default router;

---

Response Format

Your API responses will now automatically include HATEOAS links:

1{
2    "id": "yQg9OD4KRTNywa2fHwxN",
3    "name": "John Doe",
4    "links": {
5        "self": {
6            "rel": "self",
7            "href": "localhost:3333/api/contact/yQg9OD4KRTNywa2fHwxN",
8            "method": "GET"
9        },
10        "create": {
11            "title": "POST /",
12            "rel": "create",
13            "href": "localhost:3333/api/contact/",
14            "method": "POST"
15        },
16        "collection": {
17            "title": "GET /",
18            "rel": "collection",
19            "href": "localhost:3333/api/contact/",
20            "method": "GET"
21        },
22        "item": {
23            "title": "GET /:id",
24            "rel": "item",
25            "href": "localhost:3333/api/contact/yQg9OD4KRTNywa2fHwxN",
26            "method": "GET"
27        },
28        "update": {
29            "title": "PUT /:id",
30            "rel": "update",
31            "href": "localhost:3333/api/contact/yQg9OD4KRTNywa2fHwxN",
32            "method": "PUT"
33        },
34        "delete": {
35            "title": "DELETE /:id",
36            "rel": "delete",
37            "href": "localhost:3333/api/contact/yQg9OD4KRTNywa2fHwxN",
38            "method": "DELETE"
39        },
40        "documentation": {
41            "rel": "documentation",
42            "href": "localhost:3333/docs",
43            "method": "GET",
44            "title": "API Documentation"
45        }
46    }
47}

Configuration Options

The createHATEOASMiddleware accepts several options:

1. autoIncludeSameRoute: When true, includes all routes from the same file in the links
2. baseUrl: The base URL for generating absolute URLs
3. includePagination: Adds pagination links when response includes pagination data
4. customLinks: Custom link generators for additional relationships

Pagination Support

When includePagination is enabled and your response includes pagination data:

1{
2    data: items,
3    pagination: {
4        currentPage: 1,
5        totalPages: 5
6    },
7    links: {
8        // Regular links...
9        first: { rel: 'first', href: '/api/contacts?page=1', method: 'GET' },
10        next: { rel: 'next', href: '/api/contacts?page=2', method: 'GET' },
11        last: { rel: 'last', href: '/api/contacts?page=5', method: 'GET' }
12    }
13}

📄 API Reference

createRouter(filename: string)

• Description: Creates a router instance with metadata tracking and route logging.
• Parameters:
  • filename (string): The source file name (use __filename).
• Returns: express.Router Each route handler will have:
• __source: Path of the source file.
• __name: HTTP method and path.

Middleware: routeLoggerMiddleware

• Logs method, path, and source file.

Middleware: createHATEOASMiddleware

• Automatically generates HATEOAS links for your API.

---

🛡️ Best Practices

1. Consistent Base URLs: Use configuration to maintain consistent base URLs across environments.

1// config.ts
2export const config = {
3    baseUrl: process.env.API_BASE_URL || 'http://localhost:3333',
4    baseApi: '/api'
5};

2. Meaningful Relationships: Use semantic rel values that describe the relationship:

   • self: Current resource
   • collection: List endpoint
   • create: Creation endpoint
   • update: Update endpoint
   • delete: Delete endpoint

3. Error Handling: Ensure your error responses also include appropriate HATEOAS links:

1function errorHandler(err: Error, req: Request, res: Response, next: NextFunction) {
2    res.status(500).json({
3        error: err.message,
4        links: {
5            self: {
6                rel: 'self',
7                href: `${config.baseUrl}${req.originalUrl}`,
8                method: req.method as any
9            }
10        }
11    });
12}

• Use createRouter(__filename) for all route files.
• Avoid directly manipulating __source and __name properties.
• Use createHATEOASMiddleware to automatically generate HATEOAS links for your API.

---

🌟 Contributing

We welcome contributions! If you encounter bugs, have feature requests, or want to improve the library:

• Open an issue on GitHub.
• Submit a pull request.

---

📃 License

This project is licensed under the MIT License.

---

✔️ Contributing to Express Route Tracker

Every contribution matters, whether it’s bug fixes, feature requests, or improving documentation.

🛠️ Steps to Contribute

1. Fork and Clone the Repository

   1git clone https://github.com/phamhung075/express-route-tracker.git
   2cd express-route-tracker

2. Install Dependencies

   1npm install

3. Make Changes

   • Create a new branch:

     1git checkout -b feature/your-feature

   • Commit your changes:

     1git add .
     2git commit -m "Your detailed commit message"

📞 Support

For help or inquiries:

• 📧 Email: daihung.pham@gmail.com
• 🌐 Git: https://github.com/phamhung075

Happy Coding! 🚀✨