Registry / web-framework / middleware-io

middleware-io

JSON →
library2.4.1jsnpmunverified

middleware-io is a lightweight, zero-dependency library for composing promise-based middleware in JavaScript and TypeScript applications. It provides a `compose` function similar to `koa-compose` and a `Composer` class for building middleware chains with various utility 'snippets' like lazy loading, forking, and concurrency control. The library is written in TypeScript, ensuring type safety and a robust development experience. Currently at version 2.8.1, its release cadence has been irregular since its active development phase around 2019-2021, with the latest significant changes related to `exports` in `package.json` for modern module resolution. Key differentiators include its self-sufficiency (zero dependencies), native ESM support, and a rich set of built-in middleware snippets.

npm install middleware-io
INSTALL
IMPORT
SIG · MIDDLEWARE-IO
M
middleware-io
web-frameworkjavascriptv2.4.1
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

compose
import { compose } from 'middleware-io'
const compose = require('middleware-io')
The `compose` function is a named export. ESM is preferred. CommonJS `require` might fail due to `exports` field in `package.json` since v2.7.0.
Composer
import { Composer } from 'middleware-io'
const Composer = require('middleware-io').Composer
The `Composer` class is a named export. Requires a generic type with an `object` restriction since v2.4.0, e.g., `Composer<MyContext>`.
Middleware
import type { Middleware } from 'middleware-io'
This is a TypeScript type import. It allows type-checking middleware functions without importing runtime code.

This example demonstrates basic promise-based middleware composition, context modification, and asynchronous flow control using `compose`.

import { compose } from 'middleware-io'; interface MyContext { now?: number; customData?: string; } const composedMiddleware = compose<MyContext>([ async (context, next) => { // This is the first middleware in the chain. console.log('Step 1: Before next() in first middleware'); // Pass control to the next middleware in the stack. await next(); // Control returns here after subsequent middleware complete. console.log('Step 4: After next() in first middleware'); // Access data modified by later middleware. console.log(`Context.now from next middleware: ${context.now}`); }, async (context, next) => { // This is the second middleware. console.log('Step 2: Before next() in second middleware'); // Modify the context object, which is shared across the chain. context.now = Date.now(); context.customData = 'Hello from second middleware!'; // Pass control to the next middleware (or the final handler if no more middleware). await next(); // Control returns here after the next middleware (or final handler) completes. console.log('Step 3: After next() in second middleware'); } ]); // Execute the composed middleware with an initial context and a final handler. composedMiddleware({}, () => { console.log('Final handler reached (no more middleware).'); return Promise.resolve(); // Ensure the final handler also returns a Promise }) .then(() => { console.log('Middleware chain finished work successfully.'); }) .catch(console.error);
Debug
Known issues
breakingNode.js 10 and 8 support was dropped in versions 2.8.0 and 2.2.0 respectively. The library now requires Node.js >=12.0.0.
fix
Upgrade your Node.js runtime to version 12.0.0 or newer. Check your `engines` field in `package.json`.
affects: >=2.2.0
breakingVersion 2.0.0 changed the main export to `compose` by default and removed `MiddlewareStatus`. Ensure your imports are updated to use named imports for `compose`.
fix
Change `import middlewareIO from 'middleware-io'` to `import { compose } from 'middleware-io'` and refactor code using `MiddlewareStatus`.
affects: >=2.0.0
breakingIn v2.4.0, the order of arguments for `getBeforeMiddleware` and `getEnforceMiddleware` snippets was reversed. Additionally, the `Composer` class now requires a generic type with an `object` restriction.
fix
Review calls to affected snippets and `Composer` instantiation, updating argument order and providing a generic type for `Composer` (e.g., `new Composer<MyContext>()`).
affects: >=2.4.0
gotchaSince v2.7.0, the library uses the `exports` field in `package.json` for module resolution. This can lead to issues with older tooling or environments that do not correctly support `exports`, particularly for CommonJS `require()` statements trying to access deep paths.
fix
Always use named `import` statements (e.g., `import { compose } from 'middleware-io'`). If using CommonJS, ensure your environment supports `exports` map resolution or consider using dynamic `import()` for ESM-only packages.
affects: >=2.7.0
gotchaIn v2.5.0, `Composer` gained an inherited generic, and `compose` was aligned to correspond with `koa-compose` behavior. This might subtly change how middleware functions are expected to behave, especially concerning multiple `next` calls.
fix
Review your middleware logic, especially around `next()` calls, to ensure compatibility with `koa-compose`'s single `next()` invocation policy. Update `Composer` instantiation with generics where appropriate.
affects: >=2.5.0
Errors
Common errors & fixes
Error [ERR_REQUIRE_ESM]: require() of ES Module ... not supported.
Attempting to `require()` the package in a CommonJS environment, but the package is primarily designed for ESM with its `exports` field in `package.json`.
fix
Ensure your project is set up for ES Modules (`"type": "module"` in `package.json`) and use `import { Symbol } from 'middleware-io'` syntax. Alternatively, use dynamic `import()`: `const { Symbol } = await import('middleware-io')`.
TypeError: (0 , middleware_io_1.compose) is not a function
This typically occurs in transpiled environments (like some Babel or TypeScript configurations targeting CommonJS) where a named ESM import (`import { compose } from 'middleware-io'`) is incorrectly converted, or if `compose` was previously a default export.
fix
Verify your `tsconfig.json` `module` setting (e.g., `"ESNext"` or `"NodeNext"`) and `moduleResolution`. Ensure you are using named imports: `import { compose } from 'middleware-io'`.
Argument of type '(...args: any[]) => Promise<any>' is not assignable to parameter of type 'Middleware<object>'.
The generic type for `Composer` or `compose` is not correctly inferred or provided, leading to type mismatch errors with the `context` object in your middleware functions.
fix
Explicitly provide a generic type to `compose` or `Composer` that matches your context object, e.g., `compose<MyContext>(...)` or `new Composer<MyContext>()`.
Upgrade
Version history
2.4.1latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
6 hits · last 30 days
node
6
Resources