README
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
- 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.
- 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.
- 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.