@api-ts/typed-express-router
A thin wrapper around Express's Router
Goals
- Define Express routes that are associated with routes in an api-ts
apiSpec
- Augment the existing Express request with the decoded request object and api-ts route
metadata
- Augment the existing Express response with a type-checked
encode
function - Allow customization of what to do on decode/encode errors, per-route if desired
- Allow action to be performed after an encoded response is sent, per-route if desired
- Allow routes to define alias routes with path that is different than the one specified
in the
httpRoute
- Follow the express router api as closely as possible otherwise
Non-Goals
- Enforce that all routes listed in an
apiSpec
have an associated route handler - Layer anything on top of the
express.RequestHandler[]
chain beyond the additional
properties described in Goals
(projects and other libraries can do this)
Usage
Creating a router
Two very similar functions are provided by this library that respectively create or wrap
an Express router:
import { createRouter, wrapRouter } from '@api-ts/typed-express-router';
import express from 'express';
import { MyApi } from 'my-api-package';
const app = express();
const typedRouter = createRouter(MyApi);
app.use(typedRouter);
Adding routes
Once you have the typedRouter
, you can start adding routes by the api-ts api name:
typedRouter.get('hello.world', [HelloWorldHandler]);
Here, HelloWorldHandler
is a almost like an Express request handler, but req
and
res
have an extra property. req.decoded
contains the validated and decoded request.
On the response side, there is an extra res.sendEncoded(status, payload)
function that
will enforce types on the payload and encode types appropriately (e.g.
BigIntFromString
will be converted to a string). The exported TypedRequestHandler
type may be used to infer the parameter types for these functions.
Route aliases
If more flexibility is needed in the route path, a routeAliases
function may be
provided to match multiple paths. These paths may use the full Express matching syntax,
but take care to preserve any path parameters or else you will likely get decode errors.
typedRouter.get('hello.world', [HelloWorldHandler], {
routeAliases: ['/oldDeprecatedHelloWorld'],
});
Hooks and error handlers
The createRouter
, wrapRouter
, and individual route methods all take an optional last
parameter where a post-response and error handling function may be provided. Ones
specified for a specific route take precedence over the top-level ones. These may be
used to customize error responses and perform other actions like metrics collection or
logging.
const typedRouter = createRouter(MyApi, {
onDecodeError: (errs, req, res) => {
res.send(400).json({ message: 'Bad request' }).end();
},
onEncodeError: (err, req, res) => {
res.send(500).json({ message: 'Internal server error' }).end();
},
afterEncodedResponseSent: (status, payload, req, res) => {
endRequestMetricsCollection(req);
},
});
typedRouter.get('hello.world', [HelloWorldHandler], {
onDecodeError: customHelloDecodeErrorHandler,
});
Unchecked routes
If you need custom behavior on decode errors that is more involved than just sending an
error response, then the unchecked variant of the router functions can be used. They do
not fail and call onDecodeError
when a request is invalid. Instead, they will still
populate req.decoded
, except this time it'll contain the
Either<Errors, DecodedRequest>
type for route handlers to inspect.
typedRouter.getUnchecked('hello.world', (req, res) => {
if (E.isLeft(req.decoded)) {
console.warn('Route failed to decode! Continuing anyway');
})
res.send(200).end();
});
Router middleware
Middleware added with typedRouter.use()
is ran just after the request is decoded but
before it is validated, even on checked routes. It'll have access to req.decoded
in
the same way that unchecked routes do.
Other usage
Other than what is documented above, a wrapped router should behave like a regular
Express one, so things like typedRouter.use()
should behave the same.