Node-Stream Utilities

Common errors

• SyntaxError: Cannot use import statement outside a module

  cause Attempting to use `import` syntax in a CommonJS module context or a Node.js project not configured for ESM.
  fix Change your import statement to `const nodeStream = require('node-stream');` or ensure your project's `package.json` specifies `"type": "module"` and handle CJS interop carefully.

• TypeError: (0 , node_stream_1.where) is not a function

  cause This error often occurs when a CommonJS module, which exports an object, is incorrectly imported using an ESM named import syntax (e.g., `import { where } from 'node-stream';`). The bundler or runtime tries to destructure a non-existent export.
  fix Use CommonJS `require` to import the module and access its properties: `const nodeStream = require('node-stream');` then `nodeStream.where(...)` or `const { where } = require('node-stream');`.

• TypeError: db.createReadStream is not a function

  cause The quickstart example assumes the existence of a `db` object with a `createReadStream` method. If you run the code without a proper mock or an actual database connection, this error will occur.
  fix Ensure that `db` is defined and has a `createReadStream` method that returns a readable stream, or replace it with a standard `fs.createReadStream` or a mock as shown in the quickstart example.

Warnings

• breaking This package is CommonJS-only and does not natively support ECMAScript Modules (ESM) `import` syntax. Attempting to use `import` will cause `ERR_REQUIRE_ESM` or similar errors in modern Node.js environments configured for ESM.
  Fix: Use `const nodeStream = require('node-stream');` for all imports. For projects requiring ESM, consider alternative stream utility libraries that are actively maintained.
• gotcha The `node-stream` package is effectively abandoned, with its last update occurring approximately 9 years ago. This means it receives no further bug fixes, security patches, or feature enhancements. Using it in production applications poses significant risks, including potential security vulnerabilities and incompatibility with future Node.js versions or modern stream patterns (e.g., `async/await` with streams).
  Fix: Migrate to actively maintained stream utility libraries or leverage native Node.js stream capabilities, especially the `stream.promises` API and async iterators for modern asynchronous control flow.
• gotcha Designed for Node.js 0.12+ and Streams3, this library predates many significant advancements in Node.js stream handling, such as `stream.pipeline` for robust error handling, `stream.finished`, and built-in support for `async iterators`. Its API may feel less ergonomic compared to modern approaches, and it lacks direct compatibility with newer stream features, potentially leading to increased boilerplate or inefficient patterns.
  Fix: Review Node.js's native `node:stream` module documentation for current best practices, especially the `stream.pipeline` and `stream.promises` APIs for modern asynchronous stream composition and error management.

Install

• npm install node-stream npm
• yarn add node-stream yarn
• pnpm add node-stream pnpm

Imports

• nodeStream
  wrong:

  import nodeStream from 'node-stream';

  correct:

  const nodeStream = require('node-stream');

  This package is CommonJS only and does not support ESM import syntax. Attempting to use `import` will result in an error.
• where
  wrong:

  import { where } from 'node-stream';

  correct:

  const { where } = require('node-stream');

  Individual utility functions are exposed as properties on the main module export. This package is CommonJS only.
• take
  wrong:

  import { take } from 'node-stream';

  correct:

  const { take } = require('node-stream');

  Access specific methods by destructuring the `require` call or as properties on the `nodeStream` object. ESM imports are not supported.

Quickstart

This quickstart demonstrates piping a mock readable stream through several `node-stream` utility functions to filter, sort, limit, and format data, finally writing it to standard output. It simulates fetching the 5 most recent posts by a specific author.

const nodeStream = require('node-stream');
const { Readable } = require('stream');

// Mock a database read stream for demonstration purposes
const mockData = [
  { id: 1, type: 'post', author: 'stezu', content: 'First post' },
  { id: 2, type: 'comment', author: 'guest', content: 'Nice one!' },
  { id: 3, type: 'post', author: 'stezu', content: 'Second post' },
  { id: 4, type: 'post', author: 'other', content: 'Another post' },
  { id: 5, type: 'post', author: 'stezu', content: 'Third post' },
  { id: 6, type: 'post', author: 'stezu', content: 'Fourth post' },
  { id: 7, type: 'post', author: 'stezu', content: 'Fifth post' }
];

const db = {
  createReadStream: () => {
    let index = 0;
    return new Readable({
      objectMode: true,
      read() {
        if (index < mockData.length) {
          this.push(mockData[index++]);
        } else {
          this.push(null);
        }
      }
    });
  }
};

// Get the 5 most recent posts by stezu
db.createReadStream()
  .pipe(nodeStream.where({ type: 'post', author: 'stezu' }))
  .pipe(nodeStream.sort((a, b) => a.id < b.id ? 1 : -1)) // Sort descending by ID for 'most recent'
  .pipe(nodeStream.take(5))
  .pipe(nodeStream.stringify()) // Convert objects to JSON strings
  .pipe(nodeStream.intersperse('\n')) // Add newlines between items
  .pipe(process.stdout);