@e22m4u/js-trie-router
English | Русский
HTTP router for Node.js based on
a prefix tree (trie).
- Supports path-to-regexp syntax.
- Parses JSON request body automatically.
- Parses query string and
cookie
header. - Supports
preHandler
and postHandler
hooks. - Supports asynchronous handlers.
Installation
Node.js 16 or higher is required.
npm install @e22m4u/js-trie-router
The module supports ESM and CommonJS standards.
ESM
import {TrieRouter} from '@e22m4u/js-trie-router';
CommonJS
const {TrieRouter} = require('@e22m4u/js-trie-router');
Overview
A basic example of creating a router instance, defining
a route and startup Node.js HTTP server.
import http from 'http';
import {TrieRouter} from '@e22m4u/js-trie-router';
const server = new http.Server();
const router = new TrieRouter();
router.defineRoute({
method: 'GET',
path: '/',
handler(ctx) {
return 'Hello world!';
},
});
server.on('request', router.requestListener);
server.listen(3000, 'localhost');
Request context
The first parameter of a route handler is an instance
of the RequestContext
class which has a properties
set with contents of a parsed incoming request.
container: ServiceContainer
instance of service containerreq: IncomingMessage
native incoming request streamres: ServerResponse
native server response streamparams: ParsedParams
key-value object with path parametersquery: ParsedQuery
key-value object with query string parametersheaders: ParsedHeaders
key-value object with request headerscookie: ParsedCookie
key-value object of parsed cookie
headermethod: string
request method in uppercase, e.g. GET
, POST
, etc.path: string
path including query string, e.g. /myPath?foo=bar
pathname: string
request path, e.g. /myMath
body: unknown
request body
Example of accessing the context from a route handler.
router.defineRoute({
method: 'GET',
path: '/users/:id',
handler(ctx) {
console.log(ctx.req);
console.log(ctx.res);
console.log(ctx.params);
console.log(ctx.query);
console.log(ctx.headers);
console.log(ctx.cookie);
console.log(ctx.method);
console.log(ctx.path);
console.log(ctx.pathname);
},
});
Response sending
Return value of a route handler is used as response data.
Value type affects representation of a response data. For example,
if a response data is of type object
, it will be automatically
serialized to JSON.
value | content-type |
---|
string | text/plain |
number | application/json |
boolean | application/json |
object | application/json |
Buffer | application/octet-stream |
Stream | application/octet-stream |
Example of sending data as JSON.
router.defineRoute({
handler(ctx) {
return {foo: 'bar'};
},
});
The request context ctx
contains a native instance
of the ServerResponse
class from the http
module,
which can be used for manual response management.
router.defineRoute({
handler(ctx) {
res.statusCode = 404;
res.setHeader('content-type', 'text/plain; charset=utf-8');
res.end('404 Not Found', 'utf-8');
},
});
Route hooks
Defining a route with the defineRoute
method allows
to set up hooks to monitor and intercept requests and
responses for a specific route.
preHandler
executes before a route handlerpostHandler
executes after a route handler
preHandler
Before calling a route handler, operations such as authorization
and request validation may be performed in the preHandler
hook.
router.defineRoute({
preHandler(ctx) {
console.log(`incoming request ${ctx.method} ${ctx.path}`);
},
handler(ctx) {
return 'Hello world!';
},
});
A route handler will not be called if preHandler
hook
returns a value other than undefined
and null
, because
that value will be sent as response data.
router.defineRoute({
preHandler(ctx) {
return 'Are you authorized?';
},
handler(ctx) {
},
});
postHandler
Return value of a route handler is passed to the second
parameter of postHandler
hook. It may be useful to modify
the value before being sent.
router.defineRoute({
handler(ctx) {
return 'Hello world!';
},
postHandler(ctx, data) {
return data.toUpperCase();
},
});
Global hooks
A TrieRouter
instance allows to set up global hooks
that have higher priority over route hooks and are
called first.
preHandler
executes before each route handlerpostHandler
executes after each route handler
Global hooks can be added using the addHook
method
of a router instance, where the first parameter
is the hook name and the second is a function.
router.addHook('preHandler', (ctx) => {
});
router.addHook('postHandler', (ctx, data) => {
});
Similar to route hooks, if a global hook returns
a value other than undefined
and null
, that
value will be sent as response data.
Debugging
Set the DEBUG
variable to enable log output.
DEBUG=jsTrieRouter* npm run test
Testing
npm run test
License
MIT