Trough Middleware Pipeline

Common errors

• ERR_REQUIRE_ESM

  cause 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

  cause 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

  cause 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

  cause 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.

Warnings

• 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.
• breaking Version 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.
• gotcha Asynchronous 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.
• gotcha When 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.
• gotcha While 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.

Install

• npm install trough npm
• yarn add trough yarn
• pnpm add trough pnpm

Imports

• trough
  wrong:

  const trough = require('trough')

  correct:

  import { trough } from 'trough'

  trough is ESM-only since v2.0.0. CommonJS `require` is not supported.
• wrap
  wrong:

  const { wrap } = require('trough')

  correct:

  import { wrap } from '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.

Quickstart

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)