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