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. etermining the current user and adding to the request context

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.

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.

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:

mid.define(() => {
  if (withUpdate) {
    return { foo: "bar" };
  }

  if (withResponse) {
    return Response.json({ early: true });
  }

  return (res: Response) => {
    // Optionally return a modified response
    return new Response(res.body, { status: 301 });
  };
});

The second argument Midwinter passes to any middleware is the request context. By default, the middleware instance we're extending from will populate the ctx type, but we can also override this.

const ipLogger = mid.define((req, ctx: { ip: boolean }) => {
  // Ctx type has been override here
  console.log(ctx.ip);
});

If we try to .use this middleware somewhere ip is not yet part of the context, we will get a typescript error.

The third parameter is the middleware meta, which cannot be mutated.

Updating the request context

Via return value

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

const withReqTime = mid.define((req, ctx) => {
  return { start: new Date() };
});

new Midwinter()
  .use(withReqTime) //
  .use((req, ctx) => {
    // Access updated context
    ctx.start instanceof Date; // 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.

const withReqTime = mid.define<{ start: number }>((req, ctx) => {
  const start = Date.now()

  // Update context
    ctx.start = start


    // Returning a response listener
  return () => {
    const end = 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.

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

mid.define(() => {
  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.

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.

const adminRoute = mid
  .use(withAuth) // 1
  .use(isAdmin); // 2

const superAdminRoute = isAdminMid // Reuse this pipeline
  .use(hasEmailDomain("@test.com")); // 3

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.

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.

const handle = mid
  .use(withA)
  .use(withB)
  .use(withC)
  .end((req, ctx, meta) => {
    return Response.json({ ok: true });
  });

// Invoke the handler like:
const response = await handle(request);

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 * as Routing from "midwinter/routing";

export const { router, routing } = Routing.init(opts);

routing

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

const handle = mid
  .use(
    routing({
      path: "/user",
      method: "/get",
    })
  )
  .end(() => {});

We can optionally specify a prefix which will continue along any subsequent middleware pipelines.

const apiRoute = mid.use(
  routing({
    prefix: "/api/v1",
  })
);

const getPost = apiRoute
    .use(routing({
        path: "/post/:id",
        method: "get
    }))
    .end(() => {
        // ...
    })

router

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

const app = router([getPost, ...others], opts);

// Call app router on new request:
const response = await app(request);

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 * as Validation from "midwinter/validation";

export const { valid, validLazy, output } = Validation.init(opts);

valid

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

const Schema = z.object({
  // ...
});

mid
  .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 Output does 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.

mid
  .use(
    validLazy({
      // ...same options
    })
  )
  .end(async (req, ctx) => {
    const { parse } = ctx;

    // Parse a single part
    const query = await parse("query");

    // or parse all parts
    const { query, params, body, headers } = await parse();
  });

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
    })
  );