Node.js Web Stream Adapters

Common errors

• ERR_MODULE_NOT_FOUND: Cannot find module 'node-readable-stream' from '/path/to/your/file.js'

  cause You are trying to import from 'node-readable-stream' as shown in the README, but you have installed 'node-web-stream-adapters'.
  fix Change your import statements to `import { ... } from 'node-web-stream-adapters';`.

• TypeError: (0, _nodeWebStreamAdapters.toReadableStream) is not a function

  cause This error typically occurs when trying to use CommonJS `require()` syntax (e.g., `const { toReadableStream } = require('node-web-stream-adapters');`) with an ES module-only package, or when incorrectly importing a named export as a default or vice-versa.
  fix Ensure you are using ES module `import` syntax: `import { toReadableStream } from 'node-web-stream-adapters';` and check that `type: "module"` is set in your `package.json` if running in Node.js, or use a bundler that handles ESM correctly.

Warnings

• breaking The documentation (README) and the provided GitHub URL (`https://github.com/bstefanescu/node-readable-stream`) explicitly refer to `node-readable-stream` as the package name for installation and imports. However, the npm metadata provided specifies `node-web-stream-adapters`. This discrepancy is a critical point of confusion and will lead to `ERR_MODULE_NOT_FOUND` if the README's instructions are followed with the `node-web-stream-adapters` package installed.
  Fix: Always use `import { ... } from 'node-web-stream-adapters'` in your code if you installed the `node-web-stream-adapters` package. Verify the exact package name on npm if unsure, as the README might be outdated or refer to a different package/alias.
• gotcha Node.js core's native `Readable.toWeb`, `Writable.toWeb`, `Readable.fromWeb`, and `Writable.fromWeb` methods are currently experimental (as of Node.js 22). While this library provides stable alternatives, be aware that future Node.js versions might stabilize their native implementations, potentially deprecating or superseding this library's approach. This package aims to offer stability where native Node.js methods are still in flux.
  Fix: Monitor Node.js release notes for updates on the Web Streams API and its native integration. For now, using this library provides a robust solution, but be prepared for potential future migration paths if Node.js stabilizes its own converters.
• gotcha As a relatively new package (version 0.2.1), its API surface might undergo breaking changes in minor or patch releases, even though semantic versioning is typically followed. Low version numbers often indicate that the API is still finding its final form.
  Fix: Pin exact versions (e.g., `"node-web-stream-adapters": "0.2.1"`) or use caret ranges (`"^0.2.1"`) with caution, thoroughly reviewing changelogs for any updates. Regular testing is recommended when upgrading minor or patch versions.

Install

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

Imports

• toReadableStream
  wrong:

  const { toReadableStream } = require('node-web-stream-adapters');

  correct:

  import { toReadableStream } from 'node-web-stream-adapters';

  This library ships as an ES module. While `require()` might work in some Node.js configurations, `import` is the officially supported and recommended way. The README shows `from 'node-readable-stream'`, which is a different package name and will result in errors if `node-web-stream-adapters` is installed.
• createReadableStreamFromReadable

  import { createReadableStreamFromReadable } from 'node-web-stream-adapters';

  This helper function converts an existing Node.js Readable stream into a Web ReadableStream. Ensure you import from the correct package name, `node-web-stream-adapters`, not `node-readable-stream`.
• createReadableStreamFromBuffer

  import { createReadableStreamFromBuffer } from 'node-web-stream-adapters';

  This utility simplifies creating a Web ReadableStream directly from a Buffer. As with other exports, use the `node-web-stream-adapters` package name in your import statement.

Quickstart

This example demonstrates how to convert a Node.js Buffer into a Web ReadableStream using `createReadableStreamFromBuffer` and then consume it.

import fs from "fs/promises";
import { createReadableStreamFromBuffer } from "node-web-stream-adapters";

async function processFileAsStream() {
  try {
    const filePath = 'some-file.txt';
    // Assume 'some-file.txt' exists and has content.
    // In a real scenario, you might read a large file or network response.
    const buffer = await fs.readFile(filePath);
    const webStream = createReadableStreamFromBuffer(buffer);

    console.log('Created Web ReadableStream from buffer.');

    // Example: Consume the web stream (e.g., pipe to another writable stream or process chunks)
    const reader = webStream.getReader();
    while (true) {
      const { done, value } = await reader.read();
      if (done) {
        console.log('Stream finished.');
        break;
      }
      console.log('Received chunk:', new TextDecoder().decode(value));
    }
  } catch (error) {
    console.error('Error processing stream:', error);
  }
}

// Create a dummy file for the example to run
async function setupDummyFile() {
  const content = 'Hello, Web Streams!\nThis is a test file.';
  await fs.writeFile('some-file.txt', content);
  console.log('Dummy file created: some-file.txt');
  await processFileAsStream();
}

setupDummyFile();