union

What is union?

The 'union' npm package is a hybrid routing HTTP server with a powerful middleware ecosystem. It is designed to create custom Node.js HTTP servers by combining various middleware and routing logic. Union is particularly useful for building applications that require a high level of customization in their HTTP server behavior.

What are union's main functionalities?

Custom Server Creation

This code sample demonstrates how to create a custom HTTP server using Union. The 'before' array allows you to add middleware functions that process requests before they reach your main logic.

const union = require('union');
const http = require('http');

const server = union.createServer({
  before: [
    function (req, res) {
      res.emit('next');
    }
  ]
});

server.listen(3000, function () {
  console.log('Server running on port 3000');
});

Middleware Integration

This example shows how to integrate a routing library, 'director', as middleware in a Union server. The router's dispatch method is bound and used as middleware, allowing for route handling within the Union server.

const union = require('union');
const director = require('director');

const router = new director.http.Router();
const server = union.createServer({
  before: [
    function (req, res) {
      res.emit('next');
    },
    router.dispatch.bind(router)
  ]
});

Other packages similar to union

express

Express is a widely used web application framework for Node.js, designed for building web applications and APIs. It is more abstracted and less flexible in terms of raw HTTP handling compared to Union, but it offers a simpler, more feature-rich interface for common server tasks.

connect

Connect is an extensible HTTP server framework for node using 'plugins' known as middleware, similar to Union. It is the foundation upon which Express was built. While Connect is more minimalistic compared to Union, it serves a similar purpose in allowing middleware to be chained for request handling.

koa

Koa is a new web framework designed by the team behind Express, aiming to be a smaller, more expressive, and more robust foundation for web applications and APIs. Unlike Union, Koa uses a modern approach with generators and async/await to ditch callbacks and greatly increase error-handling capabilities.

README

union

A hybrid buffered / streaming middleware kernel backwards compatible with connect.

Example

var fs = require('fs'),
    union = require('../lib'),
    director = require('director'),
    favicon = require('./middleware/favicon');

var router = new director.http.Router();

var server = union.createServer({
  before: [
    favicon('./favicon.png'),
    function (req, res) {
      var found = router.dispatch(req, res);
      if (!found) {
        res.emit('next');
      }
    }
  ]
});

router.get(/foo/, function () {
  this.res.writeHead(200, { 'Content-Type': 'text/plain' })
  this.res.end('hello world\n');
});

router.post(/foo/, { stream: true }, function () {
  var req = this.req,
      res = this.res,
      writeStream;
      
  writeStream = fs.createWriteStream(Date.now() + '-foo.txt');
  req.pipe(writeStream);
  
  writeStream.on('close', function () {
    res.writeHead(200, { 'Content-Type': 'text/plain' });
    res.end('wrote to a stream!');
  });
});

server.listen(8080);
console.log('union with director running on 8080');

Installation

Installing npm (node package manager)

  $ curl http://npmjs.org/install.sh | sh

Installing union

  $ [sudo] npm install union

Usage:

union.createServer(options)

The options object is required. Options include:

options.before

options.before is an array of middlewares, which are used to route and serve incoming requests. For instance, in the example, favicon is a middleware which handles requests for /favicon.ico.

Union's request handling is connect-compatible, meaning that all existing connect middlewares should work out-of-the-box with union.

In addition, the response object passed to middlewares listens for a "next" event, which is equivalent to calling next(). Flatiron middlewares are written in this manner, meaning they are not reverse-compatible with connect.

options.after

options.after is an array of stream filters, which are applied after the request handlers in options.before. Stream filters inherit from union.ResponseStream, which implements the Node.js core streams api with a bunch of other goodies.

The advantage to streaming middlewares is that they do not require buffering the entire stream in order to execute their function.

options.limit (optional)

This argument is passed to internal instantiations of union.BufferedStream.

options.https (optional)

This argument specifies the certificate and key necessary to create an instance of https.Server:

  {
    https: {
      cert: 'path/to/cert.pem',
      key: 'path/to/key.pem',
      ca: 'path/to/ca.pem'
    }
  }

union.BufferedStream(limit)

This constructor inherits from Stream and can buffer data up to limit bytes. It also implements pause and resume methods.

union.HttpStream(options);

This constructor inherits from union.BufferedStream and returns a stream with these extra properties:

• httpStream.url: The url from the request.
• httpStream.headers: The HTTP headers associated with the stream.
• httpStream.method: The HTTP method ("GET", "POST", etc).
• httpStream.query: The querystring associated with the stream (if applicable).

union.ResponseStream

This constructor inherits from union.HttpStream, and is additionally writeable.

Union supplies this constructor as a basic response stream middleware from which to inherit.

Tests

All tests are written with vows and should be run with npm:

  $ npm test

Author: Charlie Robbins

License: MIT