trough

library0.2.0jsnpmunverified

`trough` is a lightweight, promise-aware middleware utility designed for building flexible processing pipelines in JavaScript and TypeScript environments. Currently at version 2.2.0, it is actively maintained with a consistent release cadence for minor improvements and bug fixes, typically addressing specific use cases or compatibility enhancements. Unlike some traditional middleware solutions, `trough` allows each stage of the pipeline to modify the input for subsequent stages and seamlessly integrates both synchronous and asynchronous functions, including those that return promises or use Node.js-style callbacks. Its core differentiator lies in its minimal API and explicit control over data flow, making it suitable for scenarios like plugin systems or data transformation pipelines. It is an ESM-only package, targeting modern Node.js (v16+) and browser environments via `esm.sh`.

web-framework http-networking

npm install trough

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · TROUGH

trough

web-frameworkjavascriptv0.2.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

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 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

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

trough

✓ import { trough } from 'trough'

✗ const trough = require('trough')

trough is ESM-only since v2.0.0. CommonJS `require` is not supported.

wrap

✓ import { wrap } from 'trough'

✗ const { wrap } = require('trough')

`wrap` is a named export, also ESM-only. Ensure correct named import syntax.

Pipeline

✓ import type { Pipeline } from 'trough'

trough ships with TypeScript types. Import types using `import type` for clarity and better tooling.

Middleware

✓ import type { Middleware } from 'trough'

Specific type imports like `Middleware` or `Callback` enhance type safety in TypeScript projects.

This quickstart demonstrates creating a `trough` pipeline with both synchronous and asynchronous (callback and Promise-based) middleware functions, showing how data flows and errors are handled.

import fs from 'node:fs' import path from 'node:path' import process from 'node:process' import {trough} from 'trough' const pipeline = trough() .use(function (fileName) { console.log('Checking… ' + fileName) }) .use(function (fileName) { return path.join(process.cwd(), fileName) }) .use(function (filePath, next) { // Asynchronous middleware uses a callback fs.stat(filePath, function (error, stats) { next(error, {filePath, stats}) }) }) .use(async function (ctx) { // Or use async/await for Promises if (ctx.stats.isFile()) { return new Promise((resolve, reject) => { fs.readFile(ctx.filePath, (err, data) => { if (err) reject(err); else resolve(data) }) }) } else { throw new Error('Expected file') } }) // Example usage with a valid file and an invalid path pipeline.run('readme.md', console.log) pipeline.run('node_modules', console.log)

Debug

Known issues

breaking`trough` transitioned to an ESM-only package in version 2.0.0. All CommonJS `require()` statements will fail, necessitating a migration to `import` syntax.

fix

Refactor module imports from `const trough = require('trough')` to `import { trough } from 'trough'` in your codebase.

affects: >=2.0.0

breakingVersion 2.0.1 fixed a regression from v2.0.0 where incorrect values could be passed between middleware functions in the pipeline.

fix

Ensure you are using `trough` v2.0.1 or newer if you experienced unexpected data flow issues immediately after upgrading to v2.0.0.

affects: 2.0.0

gotchaAsynchronous middleware functions must explicitly signal completion by either returning a Promise (or a thenable) or calling the `next` (or `done`) callback provided as the last argument. Failing to do so will cause the pipeline to proceed prematurely.

fix

For Promise-based middleware, `return someAsyncFunction()`. For callback-based middleware, ensure `next(error, result)` is called. Refer to the API documentation for specific middleware signatures.

affects: >=1.0.0

gotchaWhen using `trough` in a browser environment, be mindful that any middleware functions relying on Node.js-specific APIs (e.g., `fs`, `path`, `process`) will fail.

fix

Ensure all middleware functions intended for browser execution are browser-compatible. Use bundlers like webpack or Rollup to shim Node.js modules or exclude them from browser builds if necessary.

affects: >=1.0.0

gotchaWhile v2.1.0 added support for the `this` context within middleware functions when using the `wrap` utility, developers should still be cautious about how `this` is bound, especially when passing methods as middleware. Arrow functions may capture `this` from their lexical scope.

fix

If experiencing `this` context issues, ensure you are on v2.1.0 or newer. Use `.bind(this)` or arrow functions to explicitly control `this` when needed.

affects: <2.1.0

Errors

Common errors & fixes

ERR_REQUIRE_ESM

Attempting to use `require('trough')` in a CommonJS module or an environment that strictly enforces ESM.

fix

Convert your module to ESM or update your tooling configuration to handle ESM imports. Use `import { trough } from 'trough'` instead.

TypeError: (0, trough_1.trough) is not a function

Incorrect import syntax, often seen when TypeScript compiles ESM to CommonJS, or when mixing default/named import styles with an ESM-only package.

fix

Ensure your import statement matches `import { trough } from 'trough'` and your TypeScript `tsconfig.json` `module` option is set to `ESNext` or `Node16` if targeting modern Node.js.

ReferenceError: process is not defined

A middleware function uses Node.js-specific globals or modules (like `process`, `fs`, `path`) but the code is being executed in a browser environment.

fix

Refactor the problematic middleware to use browser-compatible APIs or ensure it's only run in a Node.js context. For shared code, abstract platform-specific logic.

Error: Expected file

This is an example of a custom error thrown by a middleware function due to specific application logic (e.g., input validation, file type checks) that failed within the pipeline.

fix

Review the middleware that threw the error (in this case, the one checking `ctx.stats.isFile()`) and ensure the input to the pipeline, or the logic within the middleware, handles all expected cases. Implement robust error handling and input validation.

Upgrade

Version history

0.2.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

14 hits · last 30 days

node

Amazon

OpenAI (training)

Resources

githubhttps://github.com/wooorm/trough ↗

packagehttps://www.npmjs.com/package/trough ↗

homepagehttps://trough.com ↗