{"id":17140,"library":"union","title":"Union Web Server Middleware","description":"Union is a Node.js middleware kernel designed to provide a hybrid buffered and streaming approach to handling HTTP requests and responses. It aims for backward compatibility with `connect` middlewares, allowing existing `connect` applications to leverage its features. The current stable version is 0.6.0, last published over two years ago as of early 2024. The package's `engines` configuration (`node >= 0.8.0`) further indicates its age and lack of recent maintenance. Key differentiators include its streaming middleware architecture, which avoids buffering entire request streams, and its integration with the Flatiron ecosystem, notably with `director` for routing. Unlike standard `connect` middlewares, `union`'s response object emits a 'next' event for control flow, a pattern used by Flatiron-specific middlewares but not directly compatible in reverse with `connect`'s `next()` callback style.","status":"abandoned","version":"0.6.0","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/flatiron/union","tags":["javascript"],"install":[{"cmd":"npm install union","lang":"bash","label":"npm"},{"cmd":"yarn add union","lang":"bash","label":"yarn"},{"cmd":"pnpm add union","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Often used for middleware compatibility; explicitly mentioned for integration. `union` version 0.3.x is compatible with `connect >= 2.1.0`.","package":"connect","optional":true},{"reason":"Frequently demonstrated in examples for routing, part of the Flatiron ecosystem.","package":"director","optional":true}],"imports":[{"note":"Union is a CommonJS module. ESM import syntax is not supported. `createServer` is the primary entry point for creating a Union HTTP server.","wrong":"import { createServer } from 'union';","symbol":"createServer","correct":"const union = require('union'); const server = union.createServer({});"},{"note":"The package exports an object containing its utilities, not a default export. It is a CommonJS module.","wrong":"import union from 'union';","symbol":"union","correct":"const union = require('union');"},{"note":"`ResponseStream` is exposed as a property of the `union` module, used for defining custom stream filters.","wrong":"const { ResponseStream } = require('union');","symbol":"ResponseStream","correct":"const ResponseStream = union.ResponseStream;"}],"quickstart":{"code":"const fs = require('fs');\nconst union = require('union');\nconst director = require('director');\n\nconst router = new director.http.Router();\n\nconst server = union.createServer({\n  before: [\n    function (req, res) {\n      const found = router.dispatch(req, res);\n      if (!found) {\n        res.emit('next'); // For Flatiron-compatible middlewares\n      }\n    }\n  ]\n});\n\nrouter.get(/foo/, function () {\n  this.res.writeHead(200, { 'Content-Type': 'text/plain' });\n  this.res.end('hello world\\n');\n});\n\nrouter.post(/foo/, { stream: true }, function () {\n  const req = this.req;\n  const res = this.res;\n  const writeStream = fs.createWriteStream(Date.now() + '-foo.txt');\n\n  req.pipe(writeStream);\n\n  writeStream.on('close', function () {\n    res.writeHead(200, { 'Content-Type': 'text/plain' });\n    res.end('Wrote request body to a stream!');\n  });\n});\n\nserver.listen(9090, () => {\n  console.log('Union server with director running on port 9090');\n});\n\n// To run this example, ensure 'director' is installed: npm install director","lang":"javascript","description":"This example sets up a basic Union server with `director` for routing. It demonstrates defining `before` middlewares, handling GET requests, and streaming POST request bodies to a file, showcasing Union's core streaming capabilities."},"warnings":[{"fix":"Consider migrating to actively maintained web frameworks like Express, Koa, or Fastify, which offer similar middleware patterns and modern Node.js support. This package is not suitable for new projects or production use.","message":"The `union` package is effectively abandoned and unmaintained. Its `package.json` specifies `node >= 0.8.0`, indicating compatibility with extremely old Node.js versions, and it has not been updated in over two years.","severity":"breaking","affected_versions":">=0.6.0"},{"fix":"If using `union` with `connect`, ensure you use `connect` version `2.x.x` (specifically `>= 2.1.0`) to maintain compatibility. Do not use `connect 3.x` or later.","message":"Compatibility with `connect` middlewares is explicitly stated for `union 0.3.x` with `connect >= 2.1.0`. Later versions of `connect` (e.g., `3.x` or `2.x` versions not strictly `>= 2.1.0`) may not work as expected due to API changes.","severity":"gotcha","affected_versions":"<=0.6.0"},{"fix":"When writing middlewares for `union` that need to pass control, use `res.emit('next')` if following the Flatiron style. If integrating with existing `connect` middlewares, be aware of this difference and adapt accordingly, potentially by wrapping `connect` middlewares.","message":"Union's response object (`res`) in middlewares uses `res.emit('next')` for control flow, a pattern specific to the Flatiron ecosystem. This is not reverse-compatible with standard `connect` middlewares that expect a `next()` callback as the third argument.","severity":"gotcha","affected_versions":"<=0.6.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Ensure no other application is running on the specified port, or choose a different port for your `union` server. On Linux/macOS, you can find processes using a port with `lsof -i :9090`.","cause":"Another process is already using the port that the `union` server is attempting to listen on.","error":"Error: listen EADDRINUSE :::9090"},{"fix":"Ensure `connect` is installed (`npm install connect@2`). If using `connect` v3+, it changed its API and might not be directly compatible without adapters. Also, `union` is CJS-only, so modern ESM `connect` versions will require specific interoperability layers if they even work.","cause":"You are attempting to use the `connect` module in an incompatible way with a CommonJS context, or an incorrect version of `connect` is installed.","error":"TypeError: connect is not a function"},{"fix":"Install the `director` package: `npm install director`.","cause":"The `director` package, used in many `union` examples for routing, is not installed in your project.","error":"Error: Cannot find module 'director'"}],"ecosystem":"npm","meta_description":null}