@tumau/router v1.0.0-alpha.91

🏺 Tumau

A node HTTP framework written in Typescript

Tumau is a small NodeJS server (just like Express or Koa) with almost no external dependencies and written in TypeScript.

Gist

import { Server, TumauResponse, RequestConsumer } from 'tumau';

const server = Server.create(ctx => {
  const request = ctx.get(RequestConsumer);
  return TumauResponse.withText(`Hello World ! (from ${request.url})`);
});

server.listen(3002, () => {
  console.log(`Server is up at http://localhost:3002`);
});

Benefits over Express/Koa/Other

• Written in Typescript (strong yet easy-to-use types)
• Almost no external dependency (easy to audit)
• Simple to extends (using middleware)
• Minimal (contains only the bare minimum)

Install

# npm
npm install tumau

# yarn
yarn add tumau

Packages

The tumau package is a proxi for different packages:

• @tumau/core
• @tumau/url-parser for parsing url (pathname, query...)
• @tumau/router for routing (it uses @tumau/url-parser for url parsing)
• @tumau/json for parsing / sending JSON
• @tumau/compress for Brotli / GZip / Deflate compression

Dependencies

@tumau/router has chemin as a peer dependency. This is the only dependency the project has and chemin itself has zero dependencies.

Overview

Like many other server, Tumau is based on middleware. A middleware is like a layer the request has to go though. At some point a response is created by one of the middleware and the response has to travel back to the outside (go through every layer in the opposite order) to be sent.

A middleware can stop the chain and return a response. In that case the next middleware will not be called !

The context (ctx)

In tumau the context is a way to share data between middleware.

Take a look a this example

For TypeScript users

Contexts are typed when you create them:

// here we could omit <number> because it would be infered
const NumCtx = Context.create<number>('Num', 0);

// you can omit the default value
const NameCtx = Context.create<string>('Num');

Middleware

A middleare is a function that:

• receives a context from the previous middleware
• receives a next function that will execute the next middleware
• can return a response or null (or a promise of one of them)

type Middleware = (ctx: Context, next: Next) => null | Response | Promise<null | Response>;

const myMiddleware = async (ctx, next) => {
  // 1. Context from previous middleware
  // (you need to call `ctx.get(SomeConsumer)` to read data from the context)
  console.log(ctx); // { get, getOrThrow, set, has }
  // 2. We call `next` to call the next middleware
  const response = await next(ctx);
  // 3. The next middleware return a response
  console.log(response);
  // 4. We return that response
  return response;
};

next

The next function is always async (it return a Promise). It take one parameter: the Context and return a Promise of a Response or null

type Next = (ctx: Context) => Promise<Response | null>;

Some examples

// Return a response, ignore next middleware
const middleware = () => Response.withText('Hello');

// Return a response if the next middleware did not
const middleware = async (ctx, next) => {
  const response = await next(ctx);
  if (response === null) {
    return Response.withText('Not found');
  }
  return response;
};

// Add a item to the context before calling the next middleware
// return whatever the next middleware return
const middleware = (ctx, next) => {
  const nextCtx = ctx.set(ReceivedAtContext.Provide(new Date()));
  return next(nextCtx);
};

Conbining multiple Middlewares

The Server.create function take only one middleware as parameter. To use multiple middleware you need to combine them with Middleware.compose:

import { Middleware } from 'tumau';

const composed = Middleware.compose(
  logger,
  cors,
  main
);

const server = Server.create(composed);

Note: Middlewares are executed in the order they are passed to compose. In the example above: logger, then cors, then main (then the reverse order on the way up).

More Examples

Take a look a the Examples folder !

Performance

Is it fast ?

I'm no expert in benchmarks but from my attempt to measure it it's a bit faster than Koa and Express but not as fast as fastify.

You can run the benchmark yourself by running yarn benchmark in the root folder of the monorepo. Fell free to add more framework or more complex cases !

What does "Tumau" means

According to Google Traduction it is the translation of "server" in Maori but I'm not sure which definition it apply to. Anyway I thought it would make a cool name and it was not used on NPM so...