Middleware Utils

Common errors

• TypeError: (0, _middlewareUtils.series) is not a function

  cause Attempting to use ES module named import syntax (`import { series } from 'middleware-utils';`) for a CommonJS package that exports an object, not named functions.
  fix Change the import statement to `const utils = require('middleware-utils');` and access functions as properties, e.g., `utils.series(...)`.

• Error: Cannot find module 'middleware-utils'

  cause The package is not installed in the project's `node_modules` directory, or there's a typo in the import path.
  fix Run `npm install middleware-utils` or `yarn add middleware-utils` to install the package. Double-check the spelling of the package name in your `require` statement.

• TypeError: next is not a function

  cause This error typically occurs within a middleware function when `next` (the callback to proceed to the next middleware) is either not passed correctly or is called after the middleware chain has already completed or encountered an error, leading to an invalid `next` reference.
  fix Ensure all custom middleware functions passed to `utils.series` or `utils.parallel` properly accept a `next` callback as their last argument and call `next()` exactly once when their asynchronous operations are complete (or `next(err)` if an error occurs).

Warnings

• breaking The `middleware-utils` package is a CommonJS module and does not natively support ES Modules (`import`/`export` syntax). Attempting to use `import` statements directly will likely result in syntax errors or runtime issues in pure ESM environments.
  Fix: For Node.js projects, use `const utils = require('middleware-utils');`. For modern ESM projects, consider using a module bundler that can handle CommonJS modules or alternative modern middleware utilities.
• gotcha This package has not been updated since 2017 (v1.0.0) and is considered abandoned. It targets Node.js `>=4` and uses callback-based asynchronous patterns, which are less common in modern Node.js development that favors Promises and `async`/`await`.
  Fix: While still functional for its original purpose, developers should be aware of potential compatibility issues with newer Node.js versions or dependencies, and consider more actively maintained alternatives if possible.
• gotcha The utility functions (`series`, `parallel`, `error`, `handleError`, `delims`) are exposed as properties of the main object returned by `require('middleware-utils')`. They are not individual named exports. Destructuring imports for these functions (`const { series } = require(...)`) will not work as expected and lead to runtime errors.
  Fix: Always access the utilities via the main imported object, e.g., `const utils = require('middleware-utils'); utils.series(...)`.
• deprecated The callback-based API is a dated pattern. Modern Node.js applications heavily utilize Promises and `async`/`await` for asynchronous control flow. Integrating `middleware-utils` into a Promise-based codebase will require wrapping its callback functions in Promises.
  Fix: Wrap `middleware-utils` functions in Promises for better integration with modern async patterns. For example, `new Promise((resolve, reject) => utils.series(fns)(file, (err) => err ? reject(err) : resolve()));`.

Install

• npm install middleware-utils npm
• yarn add middleware-utils yarn
• pnpm add middleware-utils pnpm

Imports

• utils
  wrong:

  const { utils } = require('middleware-utils');

  correct:

  import utils from 'middleware-utils';

  This package is CommonJS-only. While a default import *might* work in some ESM environments via interoperability, direct named imports are not supported. Prefer `require`.
• series
  wrong:

  import { series } from 'middleware-utils';

  correct:

  const utils = require('middleware-utils');
  const seriesFn = utils.series;

  Functions like `series` are properties of the default exported object, not named exports. Direct destructuring with `require` or `import` for these functions will fail.
• parallel
  wrong:

  import { parallel } from 'middleware-utils';

  correct:

  const utils = require('middleware-utils');
  const parallelFn = utils.parallel;

  Similar to `series`, `parallel` is accessed as a property of the main `utils` object.

Quickstart

This example demonstrates how to use `middleware-utils.series` to run multiple middleware functions sequentially within a simulated application context, and how to define custom middleware functions.

const utils = require('middleware-utils');

// Simulate an application object that can register middleware
const app = {
  _middleware: [],
  preRender: function(pattern, fn) {
    this._middleware.push({ pattern, fn });
  },
  // Simple handler to execute middleware
  handle: function(view, done) {
    const matchingFns = this._middleware.filter(m => view.name.match(m.pattern));
    if (matchingFns.length === 0) {
      return done(null, view);
    }

    const seriesRunner = utils.series(matchingFns.map(m => m.fn));
    seriesRunner(view, done);
  }
};

function createMiddleware(name) {
  return function(file, next) {
    console.log(`Executing middleware: ${name} for file: ${file.name}`);
    // Simulate async work
    setTimeout(() => next(), 50);
  };
}

// Register middleware using utils.series
app.preRender(/\.hbs$/, utils.series([
  createMiddleware('foo'),
  createMiddleware('bar'),
  createMiddleware('baz')
]));

// Register a single middleware
app.preRender(/\.txt$/, createMiddleware('text-processor'));

console.log('Starting middleware processing...');
app.handle({ name: 'template.hbs', content: '...' }, (err, result) => {
  if (err) {
    console.error('Error handling .hbs:', err);
  } else {
    console.log('Finished handling template.hbs.');
  }
});

app.handle({ name: 'document.txt', content: '...' }, (err, result) => {
  if (err) {
    console.error('Error handling .txt:', err);
  } else {
    console.log('Finished handling document.txt.');
  }
});