A small HTTP router.

This is a package for creating HTTP applications.

It is inspired by express – but uses modern JavaScript features and has a lot less features (on purpose) and has special emphasis on modularization of endpoints.

• Usage
  • Example
    • Code
    • Result
  • Designing your app
    • Routers
      • Router
      • Endpoint
    • Asynchronous everywhere!
    • The context object
      • Example
    • Casing
      • HTTP headers
      • Query parameters
      • Mount paths
    • Endpoints, routers and handlers
      • Endpoints
        • When using endpoints
      • Routers
        • When using routers
      • Handlers
        • When using handlers
• API Reference
  • Application
    • Constructor
      • Parameters
    • Events
      • opening
      • open
      • closing
      • closed
    • Instance methods
      • open
        • Parameters
      • close
        • Parameters
      • root
        • Parameters
      • renderer
        • Parameters
        • Default
    • Properties
      • port
      • server
      • state
        • Possible values
  • Endpoint
    • Constructor
    • Instance methods
      • get, post, put, delete, etc..
        • Parameters
        • Example
        • Catch all
      • mount
        • Parameters
        • Example
      • parameter
        • Parameters
        • Example
      • middleware
        • Parameters
        • Example
      • mixin
        • Parameters
        • Example
  • Router
    • Constructor
    • Instance methods
      • use
        • Parameters
        • Example
      • mixin
        • Parameters
        • Example
  • Request
    • Constructor
    • Instance properties
      • headers
  • Response
    • Constructor
    • Events
      • writeHead
      • processed
    • Instance methods
      • getHeader
        • Parameters
      • setHeader
        • Parameters
      • removeHeader
        • Parameters
      • hasHeader
        • Parameters
      • getHeaderNames
    • Instance properties
      • headers
• License

Below is an example and the result of an application that uses the package.

This example complicates a route that could be vastly simplified. It just does this to show off some of the features of the package.

/* index.js */

import { Application, Endpoint } from '@trenskow/app';

const app = new Application({ port: 8080 });

try {

	const root = new Endpoint()
		.mount('iam', await import('./iam.js'));

	const renderer = async ({ result, response }) => {
			response.headers.contentType = 'text/plain';
			response.end(result);
	};

	await app
		.root(root)
		.renderer(renderer)
		.open();

	console.info(`Application is running on port ${app.port}`)

} catch (error) {
	console.error(error);
}

/* iam.js */

import { Endpoint } from '@trenskow/app';

export default new Endpoint()
	.parameter({
		name: 'name',
		endpoint: await import('./name.js')
	});

/* greeter.js */

import { Router } from '@trenskow/app';

export default new Router()
	.use(async (context) => {
		context.greeter = (name) => `Hello, ${name}!`;
	})

/* name.js */

import { Endpoint } from '@trenskow/app';

export default new Endpoint()
	.middleware(await import('./greeter.js'))
	.get(async ({ parameters: { name }, greeter }) => greeter(name));

The above example will handle a request like below.

GET /iam/trenskow HTTP/1.1
Host: localhost:8080
Accept: */*

– and will respond with below.

HTTP/1.1 200 OK
Content-Type: text/plain
Connection: keep-alive
Content-Length: 16

Hello, trenskow!

Since most people know express, it would make sense to point out some of the differences.

One key difference between express and this package is, that routes cannot define their own paths. Paths are defined by the parent endpoints "mounting" the child endpoint.

The Router type is a basic router, which is only used when dealing with middleware (see below). It only supports one method, which is the .use(...) method.

Endpoint is the most used router, and it is also the one that is mostly similar to express' router. This is where you can define handlers for the HTTP methods – .get(...), .put(...), .delete(...), etc.

Unlike express, and as stated above, you cannot specify the path from a .get(...) method – you can only specify the handler, as the path is determined by the parent endpoint.

Endpoints has the mount method, which "mounts" a router to the specified subpath.

There is a variant of the mount method called parameter which is used to mount an endpoint with a dynamic path – whereas the path is treated like an input parameter (like express' .param method). Parameters also supports a transform function, which is able to transform the parameter into something else (eg. a user identifier into a user object).

Lastly there is the .middleware method, which is used to attach middleware. Middleware is defined as a router, which have the type Router and therefore cannot act as an endpoint. You can regard them like transforms or service providers for the request.

Endpoint extends Router.

All handlers and routers support async functions (and non-async). No need to call next, and when a method handler has a result available it just returns it – and if an error occur, you just throw an error. The provided renderer is responsible for writing the returned value to the response.

Where express gives you the (req, res, next) parameters for each handler, this application instead just provides a single parameter, the "context object", which contains all the information needed to process the request.

Middleware can assign values to the context to provide data and services, which is then available for subsequent endpoints, routers and handlers.

When a request is incoming, the context object looks like this.

Below is an example on how the context is used (also see the example in the beginning of this document).

.get(context) => { /* Use all the available information. */ }
.get({ parameters }) => { /* Use JavaScript object destructuring to get only the information you need. /* }

JavaScript is a camel cased language. HTTP is a mixture of different case types. Therefore this package converts all non-camel case identifiers to camel case for use when coding.

Converting between case type is performed by @trenskow/caseit.

Case is automatically converted in both directions, so if you do context.response.headers.contentType = 'application/json' it will automatically be converted to Content-Type: application/json when the response is sent.

The same goes for request headers like Accept-Language: en which is accessible through context.request.headers.acceptLanguage.

Request with quuries like ?my-parameter=value is accessible through context.query.myParameter .

When match mode is set to 'loosely' (default) a request with the path component my-route or my_route will match an endpoint mounted at myRoute.

This package distinguishes between endpoints, routers and handler.

Endpoints takes care of a path component. As example the /this/is/my/path/ path is handled by a specific endpoint. It only handles one explicit path, so as in the previous example, it does not handle /this/is/my/ – nor does it handle /this/is/my/path/endpoint/.

Endpoints can have a couple of things mounted / attached to it – those are.

• Other endpoints (using the .mount method of Endpoint)
• Parameters (using the .parameter method of Endpoint)
  • which is also a mounted endpoint – but where the path is dynamic and assigned to the context.parameters object.
• Handlers (using the .use method of Router or Endpoint )
• Middleware (using the .middleware method of Endpoint )
  • sets a Router router to that the request will be passed through.
• Methods (using the .get, .post, .put, .delete, etc. method of Endpoint)
  • When a method returns the request ends and the returned value is send to the client as a response (through the Application#renderer)

Whenever a function (such as .mount or .parameter or .root) takes an endpoint as a parameter, it can be provided in any of the following ways.

• An instance of Endpoint.
• An object that has a default key that has an instance of Endpoint as the value (useful when using inline imports as await import('my-endpoint.js')).

A router is the same as above, except it only supports .use.

As above, whenever a function takes a router as a parameter, it can be provided in any of the following ways.

• An instance of Router.
• An object that has a default key that has an instance of Router as the value (useful when using inline imports as await import('my-route.js')).).

Handlers are functions that handles a request. Handlers are functions that takes the context object as it's only parameter.

Whenever a function takes a handler as a parameter, it can be provided in any of the following ways.

• A function that takes a context object as it's parameter.
  • (context) => { /* do whatever */ }
• An object that has a default property that is set to the above.

The Application class holds an application and is responsible for handling and bootstrapping request from the server. It does not provide any routing on its own, instead it has a root method, which is used to set the root router.

If no root route has been set, all requests will be responded with 404 Not Found.

extends events.EventEmitter

The Application class takes an "options" object as it's parameter.

Indicates that the server is starting.

Indicates the the server was started.

The listener callback will be passed the port number the server is listening on.

Indicates that the server is being stopped.

Indicates that the server has stopped.

This method opens (starts) the server. The server will accept connections using the port provided in the constructor.

Will throw an error if the state of the application is anything other than 'closed'.

Returns a Promise that resolves to the application.

Parameters can be passed both as open(port) or open({ port }).

This method closes (stops) the server.

Will throw an error if the state of the application is anything other than 'open'.

Returns a Promise that resolves to the application.

Parameters can be passed both as close(awaitAllConnections) or close({ awaitAllConnections }).

This method sets the root endpoint of the server.

The provided endpoint is the one that will handle all requests to /. It is where you set the "main entry" for your application.

If no root endpoint is provided the server will respond to all requests with 404 Not Found.

Returns the application.

Sets the renderer function (async/non-async).

This method is responsible for writing to the response whatever the routes have returned (JSON encoding of values would be something to put in here).

Returns the application.

The default renderer will just write whatever is returned from the routes to the response. If it's a string it will set Content-Type: text/plain, if it's a buffer it will just write the buffer – otherwise it will just end the response.

Returns the port at which the server is currently listening.

Returns the underlying HTTP server instance.

Returns a string that represents the current state of the application.

extends Router

An endpoint is what resembles the express.js router the most. It is the one where you define parameters and HTTP method handlers like GET, POST, PUT, DELETE, etc.

If an endpoint is requested with a HTTP method not implemented by the endpoint it will respond with 405 Method Not Allowed – otherwise if no HTTP methods has been implemented at all on the endpoint it will respond with 404 Not Found.

The constructor takes no parameters.

This method takes care of handing a specified HTTP method.

Supported HTTP methods are the same as those returned by http.METHODS.

You can only call these methods once per method per endpoint – calling it multiple times will result in only the last one getting used.

These also ends routing. After a method route has been called, the routing will go strait to the renderer.

Notice: If no head method is implemented on endpoint, get will instead be called (if ). When client requests a head the result will be ignored.

Returns the endpoint.

* When more than one handler is provided only the return value of the last handler that returned a non-undefined value will be send the the renderer.

Below is an example on how to use the method.

default export ({ endpoint }) => {  
	endpoint
		.get(
			async (context) => 'Hello, world!',
			() => console.info("Said hello."));
};

In the above example 'Hello, world!' is immediately send to the renderer and the request ends. The second handler is also executed, but as it returns undefined its return value is ignored.

There is also a catch-all variant, which makes the handler able to handle the all paths from that endpoint (useful when serving files from a directory).

Below is an example.

import { Endpoint } from '@trenskow/app';

export default new Endpoint()
	.get.catchAll(async () => 'Hello, World!');

The method mounts another endpoint to a specific subpath.

Returns the endpoint.

Parameters can also be provided as { path, endpoint }.

Below is an example on how to use the method.

import { Endpoint } from '@trenskow/app';

default export new Endpoint()

	.mount('pathComponent', { endpoint }) => {
		/* configure endpoint at `./path-component/` */
	})

	/* Below is an example of a shortcut method. */

	.mounts.pathComponent(({ endpoint }) => {
		/* configure endpoint at `./path-component/`. */
	});

This method mounts another endpoint, but uses the path as a dynamic value which is assigned to the context.parameter object.

Returns the endpoint.

Parameters can also be provided as { name, endpoint, transform }.

Below is an example on how to use the method.

import { Endpoint } from '@trenskow/app';

export default new Endpoint()

	.parameter('name',
		new Endpoint()
			.get(({ parameters: { name } }) => name))

	/* Below is an example of a shortcut method (also demonstrates transforms). */

	.parameters.user({
		transform: async ({ user }) => await getMyUserFromId(user),
		endpoint: new Endpoint()
			.get(({ parameters: { user } }) => `Hello ${user.name}!` })
	});

This method i attaches a piece of middleware. Middleware would typically be routes that do not handle an endpoint, but works as a transform or service provider (body parsers and rate limiters would typically be installed as middleware).

Returns the endpoint.

Below is an example on how to implement a JSON body parser in a middleware router.

/* my-endpoint.js */

import { Endpoint } from '@trenskow/app';

export default = new Endpoint()
	.middleware(await import('./body-json-parser.js'))
	.post(({ body }) => JSON.stringify(body)); /* echo body to response */

/* body-json-parser.js */

import { Router, Error as AppError } from '@trenskow/app';

export default = new Router()
	.use(async (context) => {
	
		const { request } = context;
		const { headers } = request;

		const [
			contentType,
			charset = 'utf-8'
		] = headers.contentType?.match(/^application\/json(?:; ?charset=([a-z0-9-]+)(?:,|$))?/i);

		if (!/^application\/json$/i.test(contentType)) return;

		const chunks = [];

		try {
			for await (const chunk of request) {
				chunks.push(chunk);
			}
			context.body = JSON.parse(Buffer.concat(chunks).toString(charset));
		} catch (error) {
			throw new ApiError.BadRequest();
		}

	});

This method mixes in another endpoint into this.

Returns the endpoint.

Below is an example on how to use mixin.

/* endpoint-1.js */

import { Endpoint } from '@trenskow/app';

export default new Endpoint()
	.get(() => 'Hello, world!')
	.mixin(await import('./endpoint-2.js'));

/* endpoint-2.js */

export default new Endpoint()
	.post(async () => 'Hello, world from POST!');

The constructor takes no parameters.

This method is like the HTTP method handlers of Endpoint, except it is called with all HTTP methods and the return value is ignored. Routing continues after handler returns.

Typically used by middleware.

Returns the router.

See example above.

This method mixes in another router into this.

Returns the router.

Below is an example on how to use mixin.

/* router-1.js */

import { Router } from '@trenskow/app';

export default new Router()
	.mixin(await import('./router-2.js'));

/* router-2.js */

import { Router } from '@trenskow/app';

export default new Router()
	.use(async () => {
		/* Your handler here */
	});

This method hooks into the response chain and allows to change the result of the request. It will transform any value from below the routing tree from which it is added.

Below is an example of how to use a transform.

import { Endpoint } from '@trenskow/app';

export default new Endpoint()
	.transform(async ({ result, context }) => {
  	return (await result()) + ', World!';
	})
	.get(() => {
  	return 'Hello';
	});

When endpoint is called using HTTP GET, it will return 'Hello, World!'.

This class represents the request. Each individual request has its own instance assigned to context.request, where it accessible from endpoint, routers and handlers.

extends http.IncomingMessage

Request instances are constructed by the HTTP server and should not be initialized directly.

Returns an object that has the request headers as key/values, where the keys has been converted to camel case.

extends http.ServerResponse

Response instances are constructed by the HTTP server and should not be initialized directly.

Indicates that the header was written to the client.

Indicates that the response was processed.

The listener callback will be passed an Error object if an error occurred – or undefined if no error occurred.

Returns the value of a header.

Sets the value of a header.

Removed a header.

Return true if header has been set.

Returns an array of all header names set.

Returns an object that has the response headers as key/values, where the keys has been converted to camel case.

See license in LICENSE