Middleware Flow Control

0.8.0 · abandoned · verified Wed Apr 22

middleware-flow is a JavaScript library providing enhanced control flow structures for Express-style middleware. It extends the basic sequential execution model by offering utilities for `series`, `parallel`, `parallelWait`, `each`, `or`, `and`, `if().then().else()`, `syncIf`, `asyncIf`, and `mwIf` operations. First published in 2015 and currently at version 0.8.0, it was developed primarily for CommonJS environments, common in older Node.js and Express applications, making it a useful tool for orchestrating complex middleware pipelines. Its key differentiator lies in its declarative API for non-sequential middleware execution, particularly for concurrent tasks or conditional branching, which are not natively provided by Express's core `app.use()` patterns. The project's development appears to be abandoned, with its last publish date being 11 years ago, and no further updates are expected.

Common errors

```
ReferenceError: require is not defined
```
cause Attempting to use `require` in an ES Module context where it is not available.

fix Ensure your Node.js environment is configured for CommonJS, or use a bundler/transpiler to handle the CommonJS module in an ESM project. You can also try dynamic `import()` if the module allows it (`import('middleware-flow').then(({ series }) => ...)`) but this library might not be designed for it.
```
SyntaxError: Unexpected token 'if'
```
cause Attempting to destructure or declare a variable named `if`, which is a reserved JavaScript keyword.

fix When destructuring, alias the 'if' export: `const { 'if': ifFlow } = require('middleware-flow');`. If importing the whole module, access it as a property: `const flow = require('middleware-flow'); app.use(flow.if(...));`
```
Error: Can't set headers after they are sent to the client.
```
cause A middleware within a parallel, conditional, or iterative flow sent a response, but another middleware subsequently attempted to send headers or a response.

fix Ensure that only one middleware is responsible for sending the final response or that subsequent middlewares correctly check `res.headersSent` before attempting to modify headers or send responses. Proper `next()` calls are crucial for controlling flow.

Warnings

breaking The library is abandoned, with its last publish date being May 10, 2015. It is no longer actively maintained, meaning no further updates, bug fixes, or security patches will be released.
Fix: Avoid using this library for new projects. For existing projects, evaluate the risks of using unmaintained software. Consider migrating to a modern, actively maintained middleware solution or a custom implementation.
gotcha The library exclusively uses CommonJS `require()` syntax and does not provide native ES Module (ESM) exports. Using it directly in an ESM-only Node.js project or browser environment will lead to errors without proper transpilation or bundling.
Fix: For Node.js ESM projects, you might need to use dynamic `import()` for specific needs or configure a bundler (like Webpack or Rollup) to handle CommonJS modules. Ensure your project is configured for CommonJS if relying heavily on this library.
gotcha The `if` utility uses a reserved JavaScript keyword. When destructuring, you must alias it (e.g., `const { 'if': ifFlow } = require('middleware-flow');`) or access it via the full module object (e.g., `const flow = require('middleware-flow'); flow.if(...)`).
Fix: Always alias the 'if' export during destructuring (`{ 'if': myIf }`) or import the entire module and access it as a property (`flow.if`).
gotcha Error handling in `parallel` and `parallelWait` explicitly states that it 'returns the first error that occurred'. This means subsequent errors from other parallel middlewares will be ignored. Ensure your application logic accounts for this behavior.
Fix: Design parallel middlewares to be idempotent or ensure that the first error is sufficient for halting processing. If all errors are critical and need to be reported, consider using custom error aggregation or alternative parallel execution libraries.

Install

npm install middleware-flow npm
yarn add middleware-flow yarn
pnpm add middleware-flow pnpm

Imports

series
wrong:
```
import { series } from 'middleware-flow';
```
correct:
```
const { series } = require('middleware-flow');
```
This library is exclusively CommonJS (`require()`). Direct ESM imports (`import`) will not work without a CJS wrapper or bundler configuration, as it was last published 11 years ago.
parallel
wrong:
```
import parallel from 'middleware-flow/parallel';
```
correct:
```
const { parallel } = require('middleware-flow');
```
Named export from the main package. The library does not offer individual file imports as a common pattern, and is CommonJS-only.
if
wrong:
```
const if = require('middleware-flow').if;
```
correct:
```
const { 'if': ifFlow } = require('middleware-flow');
```
The 'if' keyword is reserved in JavaScript. Destructuring it requires aliasing (e.g., 'if': ifFlow) or accessing directly as `flow.if` if the whole module is imported. Importing the whole module is generally safer: `const flow = require('middleware-flow'); app.use(flow.if(...))`.

Quickstart

Demonstrates conditional middleware execution using `if().then().else()` and sequential execution with `series` in an Express application. The `/conditional` route varies its behavior based on a query parameter.

const express = require('express');
const { 'if': ifFlow, series } = require('middleware-flow');

const app = express();

// Dummy middlewares
const middlewareOne = (req, res, next) => {
  console.log('Middleware One executed.');
  next();
};
const middlewareTwo = (req, res, next) => {
  console.log('Middleware Two executed.');
  next();
};
const middlewareError = (req, res, next) => {
  console.error('Error Middleware executed.');
  res.status(500).send('An error occurred!');
};

// A synchronous function for ifFlow condition
function nameQueryExists (req, res) {
  return !!req.query.name;
}

app.use('/conditional', 
  ifFlow(nameQueryExists) // Checks if req.query.name exists
    .then(middlewareOne, middlewareTwo) // If true, run these sequentially
    .else(middlewareError) // If false, run the error middleware
);

app.use('/', series(middlewareOne, middlewareTwo, (req, res) => {
  res.send('Hello from middleware-flow! Try /conditional?name=test or /conditional');
}));

app.listen(3000, () => {
  console.log('Server listening on http://localhost:3000');
});

view raw JSON →