The @loxjs/express-router
module provides a fluent and convenient way to define and manage routes in Express.js applications. It extends the routing capabilities with advanced response handling, allowing for a variety of response types and behaviors.
- Fluent and chainable API for defining routes.
- Support for all common HTTP methods (GET, POST, PUT, PATCH, DELETE, HEAD).
- Simplified controller association with support for both single and multiple controllers.
- Extended response handling within controllers, including:
- Custom HTTP status codes.
- HTTP response headers.
- Redirects and location headers.
- Response type formatting (HTML, XML, JavaScript, CSV).
- Raw data responses without default packaging.
- Easy integration with existing Express.js applications.
npm install @loxjs/express-router
Or with yarn:
yarn add @loxjs/express-router
Import and use @loxjs/express-router
to define routes in your Express.js application:
// router.js
const ExpressRouter = require('@loxjs/express-router');
const router = new ExpressRouter();
Define routes using the fluent API and attach controllers:
router
.get('/example')
.controller(async (req) => {
// Your GET controller logic here
});
router
.post('/example')
.controller(async (req) => {
// Your POST controller logic here
});
module.exports = router
Once all routes are defined, call end()
to finalize and use them in your Express.js application:
const express = require('express');
const router = require('./router.js');
const app = express();
app.use('/api', router.end());
app.listen(3000, () => {
console.log('Server is running on port 3000');
});
Defines a new path for a route.
-
options
: An object with the following properties:-
method
: The HTTP method (default:'get'
). -
path
: The path for the route (default:'/'
).
-
Associates a controller with the current path.
-
controller
: A function or an array of functions to handle the route.
Finalizes the route definitions and returns the Express router.
The following methods are shortcuts for path()
with the method preset:
get(path)
post(path)
put(path)
patch(path)
delete(path)
head(path)
Uses a middleware function or an array of functions.
-
callback
: A middleware function or an array of middleware functions to apply.
The generate
method within the ExpressRouter
class provides several extended response handling features:
-
Custom HTTP Status Codes
: Controllers can specify custom HTTP status codes for the response. -
HTTP Response Headers
: Controllers can append custom headers to the response. -
Redirects
: Controllers can trigger HTTP redirects usingreq.routerRedirect
. -
Location Headers
: Controllers can set theLocation
header usingreq.routerLocation
. -
Response Type Formatting
: Controllers can specify the response type (HTML, XML, JavaScript, CSV) usingreq.routerResponseType
. -
Raw Data Responses
: Controllers can bypass default data packaging by settingreq.responseRawData
totrue
or by including__disablePackagingData
in the response object. -
File Downloads
: For CSV responses, controllers can specify a filename, which prompts the browser to download the file.
These extended features allow for more granular control over the HTTP response from within your controllers.
By default, responses are sent as JSON with the following format:
{
"code": 200,
"data": "your data here" // If `.controller()` returns data
}
If .controller()
returns void or undefined, responses are sent as JSON with the following format:
{
"code": 200
}
To set a cookie, you can use the req.setCookie
object within your request handler. The req.setCookie
object must contain the name
and value
properties.
-
req.setCookie.name
(String): The name of the cookie. This field is required. -
req.setCookie.value
(String): The value of the cookie. This field is required. -
req.setCookie.options
(Object): Optional settings for the cookie, such asmaxAge
.
router
.post('/set-cookie')
.controller((req) => {
req.setCookie = {
name: 'sessionId',
value: 'abc123',
options: { maxAge: 1000 * 60 * 60 * 24 * 30 } // Expires in 30 days
};
// ...additional logic...
res.end('Cookie set');
});
To set multiple cookies at once, you can assign an array of cookie objects to req.setCookies
.
-
req.setCookies
(Array): An array where each element is an object withname
,value
, and optionaloptions
properties.
router
.post('/set-multiple-cookies')
.controller((req) => {
req.setCookies = [
{
name: 'sessionId',
value: 'abc123',
options: { maxAge: 1000 * 60 * 60 * 24 * 30 }
},
{
name: 'preferences',
value: 'darkmode',
// No options provided, default settings will be used
}
];
// ...additional logic...
res.end('Multiple cookies set');
});
To clear a single cookie, assign the cookie name to req.clearCookie
.
-
req.clearCookie
(String): The name of the cookie to clear.
router
.post('/clear-cookie')
.controller((req) => {
req.clearCookie = 'sessionId';
// ...additional logic...
res.end('Cookie cleared');
});
To clear multiple cookies, provide an array of cookie names to req.clearCookies
.
-
req.clearCookies
(Array): An array of strings, where each string is the name of a cookie to clear.
router
.post('/clear-multiple-cookies')
.controller((req) => {
req.clearCookies = ['sessionId', 'preferences'];
// ...additional logic...
res.end('Multiple cookies cleared');
});
To set the Location
header for HTTP redirection:
router
.get('/example')
.controller((req) => {
req.routerLocation = '/new-location';
req.routerHTTPStatus = 302; // Optional: Set a custom HTTP status code
});
To redirect the request to a different URL:
router
.get('/example')
.controller((req) => {
req.routerRedirect = '/redirect-url';
});
To add custom response headers:
router
.get('/example')
.controller((req) => {
req.routerResponseHeaders = [
['X-Custom-Header', 'HeaderValue'],
['Another-Header', 'AnotherValue']
];
});
To return a specific HTTP status code, possibly with data:
router
.get('/error')
.controller((req) => {
req.routerHTTPStatus = 500; // Set the HTTP status code
return { message: 'Internal Server Error' };
});
To return HTML content:
router
.get('/html')
.controller((req) => {
req.routerResponseType = 'plainHTML';
return '<h1>Welcome to the HTML page</h1>';
});
To return XML content:
router
.get('/xml')
.controller((req) => {
req.routerResponseType = 'xml';
return '<note><body>This is a note</body></note>';
});
To return JavaScript code:
router
.get('/script.js')
.controller((req) => {
req.routerResponseType = 'js';
return 'alert("Hello, world!");';
});
To return CSV content and prompt a file download:
router
.get('/csv')
.controller((req) => {
req.routerResponseType = 'csv';
req.filename = 'example.csv';
return 'id,name\n1,Alice\n2,Bob';
});
To return raw data without the default JSON packaging:
router
.get('/rawdata')
.controller((req) => {
req.responseRawData = true;
return 'Raw data response';
});
Contributions to @loxjs/express-router
are welcome! Please ensure that your contributions adhere to the following guidelines:
- Write clear, readable, and maintainable code.
- Follow existing coding styles and practices.
- Write meaningful commit messages.
- Update the documentation accordingly.
For more detailed information, please read the contributing guide.
Enjoy using @loxjs/express-router
!