Another In-House API Server Frameworklet

I just wanted a basic little API server for toy projects, without having to park a container-ship of modules under them.

So here is a low-dependency toy web server framework. It includes a simple router, some bundled middlewares such as body-parsing and content-negotiation, convenience functions, and a number of opinions.

This is not drop-in compatible with the industry standards, and is in no way intended to replace any mature, full-featured framework. It is spartan in some aspects, brings some unexpected baggage in others, probably makes some questionable design decisions, and is likely somewhat idiosyncratic from an outside perspective.

The primary design goals are:

• self-contained: Uses as few external dependencies as are feasible.
• not-infinitely-extensible: The projects it gets used in drive the feature set, so some expected functionality may be surprisingly missing.
• learning from mistakes made along the way: This was partly created as a means to gain a better understanding of the existing web framework ecosystem by fussing with all the involved fiddly bits, a priori, from the bottom up.

Getting Started

Construct it with a console-level-compatible logger object capable of doing something meaningful with calls like logger[level](scopeString, messageString, dataObject).

Within the server request handler:

• async dispatch(req, res) makes things go.

Within the application implementation:

• on(method, urlPath, handler) declares a thing to do when a request matches.
• async preHandler(req, res, ctx) is called on every request before the handler function, by default adding some request information to the context.

Within your handlers:

• parameters from the route and query, along with other metadata, are set in each context.
• setResponseType(responseTypes, req, res, ctx) can be called to negotiate content types.
• async ingestBody(req, res, ctx, options) will parse request body data.
• throw an Error.ResponseError with an Enum.ErrorResponse for a simple status code with optional details, when something goes awry.

Negotiated content types can be extended by overriding:

• parseBody(contentType, ctx) for incoming types.
• renderError(contentType, err) for outgoing types.

Some handler functions are provided:

• async handlerGetStaticFile(req, res, ctx, file) will return a file from a configured directory, and also supports including CERN-style header metadata. It will also serve pre-encoded variations (e.g. .gz or .br) if available and requested.
• async handlerRedirect(req, res, ctx, newPath, statusCode) will return a redirect response.

Performance

While not a specifically-focused target, performance falls roughly midway between koa and fastify.