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)

nullfame/knowdev-express