❄️ Midwinter.js

Middleware + WinterCG = Midwinter

Midwinter is a plugin-based middleware engine used to build HTTP backend applications.

The main innovation driving Midwinter is enabling middleware to declare metadata. This enables powerful introspection and static analysis, which in turn enables an infinitely flexible plugin system.

The plugin system is so powerful that even core functionality like routing can happily exist as a plugin.

npm i midwinter

Important

Midwinter is currently in beta status. It won't be fundamentally overhauled but may experience some breaking API changes. That said, it is currently used in production.

Motivation

When we add middleware to our applications, it might change a req object, add some routes, or something else entirely. As we build up an increasingly complex web of routes, each piece of middleware becomes impossible to track and is essentially a black box.

To improve this situation, we can inform both static and runtime environments as to how our application behaves, in the form of types and metadata, respectively. In doing so, we can offload fundamental functionality to plugins; programmatically introspect and understand our applications; and trace how our request context changes over time, via TypeScript.

Basic Usage

constwithAuth=newMidwinter({requiresAuth: true,// Define metadata (optional)}).use((req,ctx)=>{return{userId: "123"};// Add data to request context});constgetUser=newMidwinter().use(withAuth)// Apply middleware.end((req,ctx)=>{const{ userId }=ctx;returnResponse.json({ userId });});constresponse=awaitgetUser(newRequest(/*...*/));awaitresponse.json();// { userId: "123" }getUser.meta.requiresAuth;// true

Table of Contents

• Guide
  • Getting Started
  • Return value behaviour
  • Request Context
  • Listening to responses
  • Chaining
  • .ending pipelines
  • Metadata
• Plugins
  • Official Plugins
  • Routing
  • Validation
  • Cors
  • Client Types

Key Concepts

Request Context

The request context represents how our app changes over the lifetime of a request. Using Midwinter, the changes to this context are automatically inferred, and can be explicitly defined if necessary.

e.g. determining the current user and adding to the request context

Metadata

Middleware can also register information that doesn't depend on the request lifecycle, in the form of metadata. For example, a given middleware could provide metadata about OpenAPI validation schema, to trivially enable client-side types.

e.g specifying the path, method or validation schema for a request handler, for later use with a routing or validation plugin.

Guide

The following is the entire Midwinter API:

consthandle=newMidwinter(meta)//.use(middleware)//.end(endMiddleware);

Midwinter is remarkably simple and deceptively powerful. With only this API, we can create complex middleware pipelines and defer much of what might exist in a framework to plugins instead, without any loss of functionality or ergonomics.

Note

These docs are currently a work in progress. They are mostly there but may hve the odd gap or minor error. Please raise an issue if you run into anything.

Getting Started

At it's simplest, middleware can be a regular function.

constisAuthed=async(req: Request)=>{constuser=awaitgetUser(req);if(user==null){thrownewError("Unauthorized!");}};

This can then be used to create a basic middleware pipeline.

consthandleRequest=newMidwinter().use(isAuthed)// <--.end(()=>Response.json({ok: true}));

When we .use a middleware, we are registering it to a middleware pipeline. To actually invoke this middleware pipeline, we need to .end it, returning a request handler function.

// Defining and registering middlewareconstmiddleware=newMidwinter().use(()=>{});// Ending a pipelineconsthandle=middleware.end(()=>newResponse(/**...*/));// Executing the request handlerconstresponse=awaithandle(newRequest(/**... */));

We can chain middleware together into reusable pipelines.

constone=newMidwinter().use(()=>{console.log(1);});consttwo=newMidwinter().use(()=>{console.log(2);});constthree=()=>{console.log(3);};constwithOneTwoThree=one.use(two).use(three);

The above example demonstrates the three ways middleware can be defined/registered:

1. Extending from an existing pipeline
2. Applying a pipeline via .use
3. Applying a function via .use

In other words, instances of Midwinter can also be treated as middleware itself!

When this pipeline is .used or extended, the middleware is run in sequence.

consthandle=withOneTwoThree.end();handle(newRequest(/**... */));// 1// 2// 3

When our middleware returns an object, it gets shallowly merged with the existing request context. This context is passed as the second parameter to any middleware functions.

constwithReqId=newMiddleware().use((req)=>{return{id: req.headers.get("x-request-id")};});constwithLogReqId=withReqId.end((req,ctx)=>{console.log(ctx.id);});

We can also specify metadata to make our app more informative to both humans and computers.

constwithPath=<Textendsstring>(path: T)=>{returnnewMidwinter({ path });};constmiddleware=newMidwinter().use(withPath("/users/:id")).end();middleware.meta.path==="/users/:id";// The `meta.path` type is also `/users/:id`

So far, we've only been intercepting the request. But we can also intercept and modify the response. By returning a function, we can register response middleware.

constwithTiming=newMidwinter().use(()=>{conststart=Date.now();return(res: Response)=>{constheaders=newHeaders(res.headers);headers.set("x-timing",String(Date.now()-start));returnnewResponse(res.body,{status: res.status,statusText: res.statusText,
headers,});};});

---

We have seen how Midwinter is fairly simple, but these trivial examples hardly show how it is powerful. To dive deeper into how Midwinter works, continue on below. To get a better sense of how this paradigm can enable interesting plugins, continue to the Plugins section.

Return value behaviour

Expand

Middleware often needs to update the request context,return early responses and observe/modify outbound responses. Midwinter achieves this using a functional style, relying on the value returned by a middleware function.

Object	Update request context (shallowly)
Function	Registers a "response listener" (outbound middleware)
Response	Return the response, passing through any response listeners defined upstream

Note that response listeners are executed in reverse or "inside-out" order

On top of being convenient and simple, relying on return type maintains type-safety across our middleware pipeline by simply inferring what request context updates our middleware makes. In turn, we can avoid entire classes of errors and work, knowing what data does (not) exist at a given point.

These three options look something like:

newMidwinter().use(()=>{if(withUpdate){return{foo: "bar"};}if(withResponse){returnResponse.json({early: true});}return(res: Response)=>{// Optionally return a modified responsereturnnewResponse(res.body,{status: 301,});};});

Request Context

Expand

The second argument Midwinter passes to any middleware is the request context.

constwithIp=newMidwinter().use(()=>({ip: "123"}));constipLogger=withIp.use((req,ctx)=>{console.log(ctx.ip);});

Updating the request context

Via return value

We can return a simple JavaScript object to indicate a context update.

constwithReqTime=mid.define((req,ctx)=>{return{start: newDate()};});newMidwinter().use(withReqTime)//.use((req,ctx)=>{ctx.start!=null;// true});

Via mutation

Much of the time, we only need to return one of the above three return value possibilities: object, function or response.

While returning both a response and response listener is redundant, we may still want to update the request context during these two cases. To do so, we can mutate the request context directly.

constwithReqTime=newMidwinter().use<{start: number}>((req,ctx)=>{conststart=Date.now()// Update contextctx.start=start// Returning a response listenerreturn()=>{constend=Date.now()console.log("Took"start-end)};});

In this example, the type has been explicitly provided, which maintains type-safety. However, this is entirely optional.

Listening to responses

Expand

Returning a function enables listening to and modifying the outbound response. The function takes a single argument: the response object.

newMidwinter().use(()=>{return(res: Response)=>{// TODO: Return a new response... or not};});

We can modify the response object by returning a new one. Bear in mind both Request and Response, as per the WinterCG standard, are immutable, so you should make use of the .clone() method when applicable.

Chaining

Expand

Midwinter makes heavy use of chaining and TypeScript inference which helps to compose complex middleware pipelines using simple code, and to string our applications together at the type-level to surface issues before running anything, like trying to access missing data from the request context.

constwithAuth=newMidwinter().use(/**... */);constisAdmin=withAuth.use(/**... */);constisSuperAdmin=isAdmin.use(/**... */);newMidwinter().use(isSuperAdmin);

By chaining we can extend middleware pipelines easily and create complex pathways for a request to travel through.

Each time we chain middleware a new instance is returned, meaning each pipeline is independent and changing one will not change any others.

.ending pipelines

Expand

To officially end a middleware pipeline, and thus return a request handler we can run, we use the .end method. This is is similar to .use, but must return a Response object.

Instead of a new Midwinter instance being returned, .end results in a request handler function that accepts a Request and returns a Response promise.

consthandle=newMidwinter().use(withA).use(withB).use(withC).end((req,ctx,meta)=>{returnResponse.json({ok: true});});// Invoke the handler like:constresponse=awaithandle(request);

Metadata

Metadata enables middleware to "decorate" our backend apps in powerful ways that traditional middleware can't.

constwithName=(name: string)=>{constmeta={ name };returnnewMidwinter(meta// <--);};

In this case, our "middleware" actually runs nothing at all - it is only metadata. If we .use this middeware, our resulting request handler will possess this metadata, which can then be utilised by other tooling to great effect.

consthandle=newMidwinter().use(withName("getUser"))// <--.end(()=>{// ...});handle.meta.name==="getUser";

This approach to metadata enables plugins, or own code, to fully "see" our app, both programmatically and type-wise. This feature enables a very simple and powerful paradigm for plugins.

Metadata merging

Like request context updates, metadata is shallowly merged.

consthandle=newMidwinter().use(withName("getUser"))// <--.use(withName("getPost"))// <--.end(()=>{// ...});handle.meta.name==="getPost";

Plugins

In Midwinter, "plugins" (as opposed to regular middleware), broadly refers to a set of interacting middleware, or functionality that operates on request handlers.

For example, a plugin might add some metadata to a middleware pipeline and then access that metadata elsewhere, down the line.

Official Plugins

Midwinter itself is a very slim middleware pipeline, and so most "app stuff" is provided by plugins.

Core app functionality like routing and validation (among others) are provided. However, even these can be replaced by third party alternatives, without much downside.

More official plugins will be added in coming months. Feel free to open a PR for any requests.

Routing

Expand

Routing is central to any backend app. However, with the advent of full-stack frameworks and file-system routing, not all apps need an explicit router.

For those who do, this plugin enables a flexible routing solution.

In short, the routing plugin turns a list of request handlers into an actual "app".

Setup

import*asRoutingfrom"midwinter/routing";exportconst{ router, route }=Routing.init(opts);

routing

The routing function is a middleware that adds routing-related metadata to a route.

consthandle=newMidwinter().use(route({path: "/user",method: "/get",})).end(()=>{// ...});

To more easily group routes, while avoiding duplication, we can create a prefixed route utility like so.

constapiRoute=prefixed("/api/v1")constgetPost=newMidwinter().use(apiRoute({path: "/post/:id",method: "get})).end(()=>{// ...})getPost.meta.path// /api/v1/post/:id

router

To actually instantiate our app router, we use the router function.

constapp=router([getPost, ...others],opts);// Call app router on new request:constresponse=awaitapp(request);

Validation

Expand

Input and output validation is table stakes for any serious backend app. While we can always imperatively validate data, the validation plugin enables a declarative API that is more concise.

By virtue of being declarative, the validation plugin also facilitates opportunities for easily inferring types or generating specs like OpenAPI.

The validation plugin works with most popular schema validation libraries out of the box. The below examples are using zod.

Setup

import*asValidationfrom"midwinter/validation";exportconst{ valid, validLazy, output }=Validation.init(opts);

valid

The valid function enables validating various input and outputs of your backend.

constSchema=z.object({// ...});newMidwinter().use(valid({// All possible fields:Query: Schema,Params: Schema,Headers: Schema,Body: Schema,Output: Schema,})).end((req,ctx)=>{const{ query, params, headers, body }=ctx;});

With valid, all components are pre-parsed and added to the context.

Note that Outputdoes not parse the response.body. See below.

validLazy

In contrast to valid, validLazy does not pre-parse anything. Instead a parsing function is added to the context, offering greater flexibility over how parsing is handled and what to parse.

newMidwinter().use(validLazy({// ...same options})).end(async(req,ctx)=>{const{ parse }=ctx;// Parse a single partconstquery=awaitparse("query");// or parse all partsconst{ query, params, body, headers }=awaitparse();});

output

At a minimum, the output function allows us to return a value, which will then get packaged into a JSON response.

If we've specified an Output schema, our return value will be validated against this.

mid.use(valid({Output: z.object({foo: z.string()}),// <-- Optionally specify output schema here})).end(output((req,ctx)=>{return{foo: "bar"};// <-- Will be parsed and returned as a JSON Response}));

Cors

Expand

TODO: Add docs

import*asCorsfrom"midwinter/cors";exportconst{ cors }=Cors.init();newMidwinter().use(cors(opts));

Client Types

Expand

TODO: Add docs

import*asClientTypesfrom"midwinter/client-types";importtype{AppRoutes}from"./app";exporttypeAppDef=ClientTypes.InferApp<typeofAppRoutes>;

Open Telemetry

Expand

TODO: Add docs

import*asOtelfrom"midwinter/otel";const{ otel }=Otel.init();newMidwinter().use(otel());

OpenAPI

Coming soon

...