@knowdev/express v1.1.2
KnowDev Express š
Express on AWS Lambda toolkit
ā¹ļø Overview
Encapsulates project opinions on JSON:API, logging, and debugging
projectHandler()
function should wrap all routes- The handler will bootstrap logging provided by
@knowdev/log
- The inbound request will be logged
- The outbound response will be logged
- The outbound response will be decorated with project headers
- The handler will catch any
@knowdev/errors
and respond properly - The handler will catch any uncaught errors and respond with a
500
(from@knowdev/errors
)
š Usage
Installation
npm install --save @knowdev/express
Environment Variables
For @knowdev/log:
LOG_LEVEL=all|trace|*debug*|info|warn|error|fatal|silent
# Project metadata
PROJECT_ENV=dev
PROJECT_KEY=mayhem
PROJECT_VERSION=0.1.0
# Project secret will let tests bypass authentication
PROJECT_SECRET=
# Danger!
PROJECT_UNAVAILABLE=false
ā ļø Danger! Setting PROJECT_UNAVAILABLE=true
will cause the handler to always throw 503 Unavailable errors.
Example
const { log, projectHandler } = require("@knowdev/express");
router.all(
"*",
projectHandler((req, res) => {
log.debug("Entering my handler logic");
const response = { hello: "world" };
res.json(response);
})
);
module.exports = router;
š Reference
Project Handler
const { projectHandler } = require("@knowdev/express");
const myMiddleware = projectHandler((req, res, next) => {
next();
});
const myRouteHandler = projectHandler((req, res) => {
const response = { hello: "world" };
res.json(response);
});
router.all("*", myMiddleWare, myRouteHandler);
š” Note: because the project is opinionated about returning JSON, the project handler assumes res.json()
is going to be called,
Handler Context
Use the context object to pass options
const { projectHandler } = require("@knowdev/express");
const myFunction - (req, res) => {
// ...
}
const context = {
name: "myFunction",
// ...
}
const myRouteHandler = projectHandler(myFunction, context);
router.all("*", myRouteHandler);
Option | Default | Description |
---|---|---|
locals | {} | req.locals will be populated to these values, executing any functions |
name | undefined | Name used in logging |
setup | [] | Functions to run before the handler |
teardown | [] | Functions to run after the handler |
unavailable | false \|\| process.env.PROJECT_UNAVAILABLE | Throw 503 instead of responding. For unusual maintenance situations only (you're welcome) |
validate | [] | Functions to run before the handler, which MUST throw their own errors if they fail |
version | process.env.PROJECT_VERSION | Version used in logging |
Project Headers
The following headers will be included based off the following values:
Header | Value |
---|---|
X-Powered-By | knowdev.studio |
X-Project-Environment | process.env.PROJECT_ENV |
X-Project-Invoke | AWS Lambda invoke UUID |
X-Project-Key | process.env.PROJECT_KEY |
X-Project-Version | process.env.PROJECT_VERSION |
Logging
const { log } = require("@knowdev/express");
// Log by level
log.trace();
log.debug();
log.info();
log.warn();
log.error();
log.fatal();
// Special log variables:
log.var({ response });
// Chain for different levels:
log.trace.var({ response });
log.debug.var({ response }); // Default
log.info.var({ response });
log.warn.var({ response });
log.error.var({ response });
log.fatal.var({ response });
Learn more at @knowdev/log
Routes
echoRoute
const express = require("express");
const { echoRoute } = require("@knowdev/express");
const app = express();
app.use("/echo", echoRoute);
app.use("/echo/*", echoRoute);
Responds by echoing back details of your original submission, helpful for debugging. Some special routes return special messages:
Route | Response |
---|---|
error/400 | Bad request error |
error/403 | Forbidden error |
error/404 | Not found error |
error/500 | Internal error |
error/502 | Bad gateway error |
error/503 | Unavailable error |
error/504 | Gateway timeout error |
error/unhandled | Unhandled error |
error/* | Not found error |
log/error | Logs error and exits |
log/fatal | Logs fatal and exits |
log/warn | Logs warn and exits |
log/both | Logs warn followed by error and exits |
Note these error routes are in addition to the path you may be using to specify the echo route. If you follow the above example of using /echo/*
, your full route would be /echo/error/503
httpRoute
const { httpRoute } = require("@knowdev/express");
const HTTP = require("@knowdev/http");
const app = express();
app.use("/bogus", httpRoute(HTTP.CODE.NOT_FOUND));
app.use("/bogus/*", httpRoute(HTTP.CODE.NOT_FOUND));
Returns an empty body for 200, no content for 204, and a proper error message if possible for 4XX and 5XX.
Accepts any context
that can be passed to the projectHandler
app.use("/*", httpRoute(HTTP.CODE.BAD_REQUEST, { name: "badRequestCatchAll" }));
Functions
summarizeRequest
Summarizes the request, for the debugging. Used by the echo route
const { summarizeRequest } = require("@knowdev/express");
log.var({ req: summarizeRequest(req) })
summarizeResponse
Summarizes the response, for the debugging. Used in logging
const { summarizeResponse } = require("@knowdev/express");
log.var({ res: summarizeResponse(res) })
š Changelog
- v1.1.0: Adds
locals
,setup
,teardown
,validate
- v1.0.6: Handles async errors
- v1.0.0: First stable release
- v0.8.0: Log routes
- v0.7.0: JSON Tagging
- v0.6.0: JSON logging
- v0.5.0: more multi-call safe
- v0.4.0: httpRoute
- v0.3.0: Headers,
PROJECT_UNAVAILABLE
- v0.2.0: Logging, special echo routes, summarize response
- v0.1.0: fork from separate project (echoRoute, log, projectHandler, summarizeRequest)
š License
All rights reserved. Safe for use around pets
2 months ago
2 months ago
2 months ago
3 months ago
4 months ago
4 months ago
4 months ago
4 months ago
7 months ago
7 months ago
7 months ago
7 months ago
7 months ago
7 months ago
7 months ago
7 months ago
7 months ago
7 months ago
7 months ago
7 months ago
7 months ago
7 months ago
7 months ago
10 months ago
10 months ago
10 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago
11 months ago