Everett

Introduction

Everett is a library for writing HTTP servers on Node declaratively, using functional reactive programming.

WARNING: this is a highly experimental project! It exists for my own education and amusement. Please do not use it in production.

Concepts

Everett is build on two key ideas. The first is that incoming request are collected on a request$ observable. To construct a server with Everett you have to write a transformer function that maps request$ into a response$ observable. That is it. You do not have to deal with manually subscribing or unsubscribing to anything, or with manipulating req/res objects directly. You just write a function and Everett handles everything for you, so that you never have to dirty your hands with imperative network logic.

The second idea is that not every function that maps one observable to another is suitable as a transformer function. Every HTTP response must correspond to exactly one request. Therefore, the transformer function must map events one to one. Everett provides you with helpers to write such transformation functions declaratively and composably.

Usage

The simplest example is

const { map, runServer } = require('everett')

const transformer = map(() => ({
  resBody: 'Hello, World!'
}))

runServer(transformer).listen(3000)

This starts an HTTP server on port 3000. If you navigate to it with your browser, you will see the 'Hello, World!' response.

Let us unpack this. First, we create our transformer function. Every time a request reaches our server, an event is emitted. These request events are objects roughly with the following shape (there are properties used internally by Everett which are omitted):

interface Request {
  httpVersion: string,
  method: string,
  url: string,
  headers: IncomingHttpHeaders
  body: string,
}

The role of the transformer is to map request events into response events. Response events are objects with the following shape:

interface Response {
  statusCode: number,
  resHeaders: Headers,
  resBody: string,
}

Everett provides helpers to do these transformations. We have already met the simplest one map. It receives a function as an argument and applies to every event that passes through it. So, in our original example, every time a request is received, map generates an object

{
  resBody: 'Hello, World!'
}

which Everett then sends as a response. Notice that some of the fields on the Response interface are missing. If these fields are omitted, Everett fills them with the following default values:

• statusCode => 200
• resHeaders => []
• resBody => ''

However, we don't always want to apply the same transformation to all request. We may want to treat them differently if they are correspond to different routes, for example. This is where split enters. Here is a simple example:

import { map, split, runServer } from 'everett'

const isHome = ({ url }) => url === '/'

const handleHome = map(() => ({
  resBody: "You're home!"
}))

const error404 = map(() => ({
  statusCode: 404,
  resBody: 'Invalid route!'
}))

const transformer = split([
  [isHome, handleHome]
  ], error404
)

runServer(transformer).listen(3000)

This will return a "You're home" body, with 200 OK status, if it receives a request on the '/' route, but will return a 404 error on any other routes.

split must receive two arguments. The first is a list of splitters. A splitter is a pair, where the first element is a predicate and the second is a transformer. The predicate (like isHome above) is simply a function that takes an object and returns a boolean. split goes through the predicates it receives one by one and when the first one matches it executes the corresponding transform. If none of the predicates match, a default transformer, which is the second argument of split is executed.

The transformers passed to split are built just like the top level ones, using map and split. That is what makes servers with Everett very compositional.

In the future, Everett will provide it's own helpers to build predicates, so that you wouldn't have to write manually functions like isHome above.

FAQ

1. Are my transformers supposed to be pure?

There are side effectful things that every web server has to do: listen to requests and fire off responses. Everett takes care of these for you. However, there are other effectful operations, such as sending requests to other servers, talking to a database or mantaining global state in memory which will often also be necessary. This demands that transformers be non pure.

The functions passed to map, are expected to be pure. In the future, Everett will provide it's own helpers for encapsulating side effects and making them explicit.

2. How does Everett know which response corresponds to each request?

Under the hood, both responses and requests are events on RxJS Observables. When a response comes in, it is decorated with an _id property. map is implemented in such a way that this _id property is always passed along. In particular, if you include a property named _id on the object, it will be silently overwritten back to the original value. Everett checks the _id of response events to make sure that they are matched to the correct requests, even if they arrive out of order.

3. Why is it called Everett?

Hugh Everett was a theoretical physicist, who first proposed the Many Worlds interpretation of Quantum Mechanics. This interpretation posits that reality is constantly splitting into multiple parallel ones. Everett's split function is evocative of that.